WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol

Enforces hardware-bound, monotonically increasing cryptographic epoch counters within WebAuthn largeBlob payloads to protect offline-first zero-trust client credentials. Without atomic epoch progression and authenticated data binding via Authenticator Assertion Data (authData) or HMAC-SHA256 integrity tags, attackers can execute state rollback attacks by replaying stale largeBlob captures across offline clients. All largeBlob write/read transactions must mandate strict client-side verification of epoch sequence numbers and authenticated encryption before trusting payload states.

--- description: WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol - Enforces hardware-bound, monotonically increasing cryptographic epoch counters within WebAuthn largeBlob payloads to protect offline-first zero-trust client credentials. Without atomic epoch progression and authenticated data binding via Authenticator Assertion Data (authData) or HMAC-SHA256 integrity tags, attackers can execute state rollback attacks by replaying stale largeBlob captures across offline clients. All largeBlob write/read transactions must mandate strict client-side verification of epoch sequence numbers and authenticated encryption before trusting payload states. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-largeblob-epoch-validation-protocol" --- # WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting raw WebAuthn largeBlob payloads without verifying monotonically increasing client epoch counters and cryptographic AEAD bindings ## System Constraints You are a Principal Security Architect enforcing the WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol. Mandate invariant cryptographic state enforcement for all WebAuthn largeBlob extensions. Reject any unauthenticated blob storage, unverified state transitions, and unprotected deserialization of passkey largeBlob data. Ensure that every largeBlob payload is sealed using authenticated encryption (AES-256-GCM) with an AAD-bound, monotonically increasing 64-bit epoch counter, and verify that the authenticator's signCount or local secure enclave counter strictly exceeds previously acknowledged state checkpoints before committing updates. ## Strict Guidelines - Engineers MUST ALWAYS enforce authenticated encryption (AES-GCM or ChaCha20-Poly1305) on all WebAuthn largeBlob payloads, binding the credential ID, client epoch counter, and assertion challenge in the Additional Authenticated Data (AAD). - Engineers MUST NOT write unencrypted, unauthenticated, or un-versioned JSON/binary payloads to `navigator.credentials.create` or `navigator.credentials.get` largeBlob extensions. - Code MUST verify that the decrypted epoch counter from a retrieved largeBlob is strictly greater than the highest epoch persisted in local state before committing state to local storage or offline databases. - Services MUST reject largeBlob mutation requests if the client's monotonic counter cannot be atomically incremented and verified against the authenticator's hardware signCount or enclave-backed monotonic state. - Components NEVER execute raw decryption or deserialization without prior validation of message authentication tags and epoch boundary invariants. ## Bad vs Good Implementations ### Vulnerable Unauthenticated largeBlob Ingestion vs Hardware Epoch-Validated Protocol #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing unprotected state to largeBlob lacks an authenticated monotonic counter and AEAD envelope. A compromised local cache or malicious intermediary can swap the largeBlob with a previously captured valid blob, rolling back credential state without detection. ```typescript export async function saveClientState(credentialId: Uint8Array, secretData: object) { // VULNERABLE: Direct plaintext storage into largeBlob without epoch counter or AEAD integrity const rawBytes = new TextEncoder().encode(JSON.stringify(secretData)); await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: rawBytes.buffer } } } }); } ``` #### Production Standard (Correct) > **Standard**: Enforces a cryptographically sealed envelope where the monotonic 64-bit epoch is strictly incremented and bound to the credential ID via AES-256-GCM AAD. Any attempt to replay a stale largeBlob state will fail either the monotonic comparison or authentication tag verification. ```typescript export interface VerifiedBlobEnvelope { epoch: number; iv: Uint8Array; ciphertext: Uint8Array; tag: Uint8Array; } export async function writeClientEpochState( credentialId: Uint8Array, secretData: Uint8Array, key: CryptoKey, currentLocalEpoch: number ): Promise<number> { const nextEpoch = currentLocalEpoch + 1; const iv = crypto.getRandomValues(new Uint8Array(12)); // Invariant: Bind Credential ID and Monotonic Epoch Counter as AAD to prevent cross-credential substitution const aad = new Uint8Array([ ...credentialId, ...new Uint8Array(new BigUint64Array([BigInt(nextEpoch)]).buffer) ]); const encrypted = await crypto.subtle.encrypt( { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, key, secretData ); const envelope = JSON.stringify({ epoch: nextEpoch, iv: Array.from(iv), data: Array.from(new Uint8Array(encrypted)) }); const blobPayload = new TextEncoder().encode(envelope); const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: blobPayload } } } }) as PublicKeyCredential; const extResults = assertion.getClientExtensionResults(); if (!extResults.largeBlob?.written) { throw new Error('largeBlob write rejected or unsupported by authenticator'); } return nextEpoch; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol

WebAuthn largeBlob Client-Side Cryptographic Epoch Validation Protocol defines an industrial-grade behavioral standard for security engineering. Enforces hardware-bound, monotonically increasing cryptographic epoch counters within WebAuthn largeBlob payloads to protect offline-first zero-trust client credentials. Without atomic epoch progression and authenticated data binding via Authenticator Assertion Data (authData) or HMAC-SHA256 integrity tags, attackers can execute state rollback attacks by replaying stale largeBlob captures across offline clients. All largeBlob write/read transactions must mandate strict client-side verification of epoch sequence numbers and authenticated encryption before trusting payload states. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Trusting raw WebAuthn largeBlob payloads without verifying monotonically increasing client epoch counters and cryptographic AEAD bindings Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Trusting raw WebAuthn largeBlob payloads without verifying monotonically increasing client epoch counters and cryptographic AEAD bindings	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce authenticated encryption (AES-GCM or ChaCha20-Poly1305) on all WebAuthn largeBlob payloads, binding the credential ID, client epoch counter, and assertion challenge in the Additional Authenticated Data (AAD).

Engineers MUST ALWAYS enforce authenticated encryption (AES-GCM or ChaCha20-Poly1305) on all WebAuthn largeBlob payloads, binding the credential ID, client epoch counter, and assertion challenge in the Additional Authenticated Data (AAD).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.