FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity Standard

--- description: FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity Standard - Enforces cryptographic envelope integrity, size-budget verification, and deterministic failover when persisting encrypted state to WebAuthn largeBlob hardware storage. Prevents silent write truncation, state desynchronization, and replay attacks across CTAP2 authenticator lifecycle events. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fido2-largeblob-eviction-signature-continuity" --- # FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Blindly overwriting or reading unversioned, unverified largeBlobs without payload size budgeting, write-status verification, or encrypted vault fallback. ## System Constraints You are a Principal Security Architect enforcing FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity. Mandate authenticated envelope structures (AES-256-GCM/ChaCha20-Poly1305), monotonic sequence sequencing, strict byte-budget quotas (< 1024 bytes default, < 2048 bytes ceiling), and atomic dual-storage failover when writing client secrets to CTAP2 authenticators. ## Strict Guidelines - Engineers MUST ALWAYS wrap any payload written to WebAuthn `largeBlob` in an authenticated, versioned envelope containing an epoch sequence counter, a cryptographic nonce, and an AEAD authentication tag. - Engineers MUST ALWAYS assert that the serialized envelope size remains strictly below safe hardware budget thresholds (1024-byte soft cap, 2048-byte hard limit) prior to invoking `navigator.credentials.get` or `create`. - Engineers MUST ALWAYS check the boolean result of `assertion.getClientExtensionResults().largeBlob?.written` and execute atomic fallback to a secure secondary vault when `written === false` or when CTAP2 errors occur. - Engineers MUST NOT store raw unencrypted or unauthenticated payloads directly into `largeBlob` storage. - Engineers MUST implement rollback and replay protection by verifying that incoming blob sequence numbers are strictly greater than previously cached local or server-attested state. ## Bad vs Good Implementations ### Vulnerable vs. Hardened FIDO2 LargeBlob Envelope & Failover Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing unencrypted, unversioned JSON exposes authentication tokens to local bus interception, risks silent data truncation due to hardware buffer limits, and fails to verify whether the authenticator actually persisted the blob (`written` boolean is ignored). ```typescript async function saveSessionToBlob(credentialId: Uint8Array, token: string): Promise<void> { // Anti-Pattern: Unbudgeted payload, no authenticated encryption, ignores write verification const rawData = new TextEncoder().encode(JSON.stringify({ token })); await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: rawData // Vulnerable: raw plaintext, no size check, silent failure unhandled } } } }); } ``` #### Production Standard (Correct) > **Standard**: The hardened implementation secures payload confidentiality and authenticity with AES-GCM, bounds payload size to prevent silent hardware truncation, confirms `extensions.largeBlob.written === true`, and seamlessly falls back to a remote encrypted vault if the authenticator storage is constrained or unsupported. ```typescript interface BlobEnvelope { version: 1; sequence: number; iv: string; // Base64url ciphertext: string; // Base64url AES-GCM ciphertext + auth tag } const MAX_SAFE_BLOB_BYTES = 1024; async function saveSessionToBlobDeterministic( credentialId: Uint8Array, payload: Record<string, unknown>, derivedAeadKey: CryptoKey, nextSequence: number, vaultFallback: (data: Uint8Array) => Promise<void> ): Promise<{ persistedToDevice: boolean }> { const iv = crypto.getRandomValues(new Uint8Array(12)); const plaintext = new TextEncoder().encode(JSON.stringify(payload)); const encryptedBuf = await crypto.subtle.encrypt( { name: 'AES-GCM', iv }, derivedAeadKey, plaintext ); const envelope: BlobEnvelope = { version: 1, sequence: nextSequence, iv: btoa(String.fromCharCode(...iv)), ciphertext: btoa(String.fromCharCode(...new Uint8Array(encryptedBuf))) }; const serializedEnvelope = new TextEncoder().encode(JSON.stringify(envelope)); if (serializedEnvelope.byteLength > MAX_SAFE_BLOB_BYTES) { await vaultFallback(serializedEnvelope); return { persistedToDevice: false }; } try { const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: serializedEnvelope } } } }) as PublicKeyCredential | null; const extensions = assertion?.getClientExtensionResults(); const wasWritten = extensions?.largeBlob?.written === true; if (!wasWritten) { await vaultFallback(serializedEnvelope); return { persistedToDevice: false }; } return { persistedToDevice: true }; } catch (error) { await vaultFallback(serializedEnvelope); return { persistedToDevice: false }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity Standard

FIDO2 WebAuthn LargeBlob Storage Eviction & Signature Continuity Standard defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic envelope integrity, size-budget verification, and deterministic failover when persisting encrypted state to WebAuthn largeBlob hardware storage. Prevents silent write truncation, state desynchronization, and replay attacks across CTAP2 authenticator lifecycle events. 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: Blindly overwriting or reading unversioned, unverified largeBlobs without payload size budgeting, write-status verification, or encrypted vault fallback. 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	Blindly overwriting or reading unversioned, unverified largeBlobs without payload size budgeting, write-status verification, or encrypted vault fallback.	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 wrap any payload written to WebAuthn `largeBlob` in an authenticated, versioned envelope containing an epoch sequence counter, a cryptographic nonce, and an AEAD authentication tag.

Engineers MUST ALWAYS wrap any payload written to WebAuthn `largeBlob` in an authenticated, versioned envelope containing an epoch sequence counter, a cryptographic nonce, and an AEAD authentication tag.

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.