WebAuthn LargeBlob Hardware-Attested Deterministic Session Storage

--- description: WebAuthn LargeBlob Hardware-Attested Deterministic Session Storage - Enforces hardware-bound session bootstrapping via the FIDO2 WebAuthn largeBlob extension. Mandates cryptographic verification, fail-closed authenticator support checks, and strict prohibition of plaintext credential caching in vulnerable storage layers such as localStorage or unencrypted IndexedDB. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-largeblob-session-storage-standard" --- # WebAuthn LargeBlob Hardware-Attested Deterministic Session Storage > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Falling back to insecure localStorage or plaintext client storage when WebAuthn largeBlob extension operations fail or are unsupported. ## System Constraints You are a Principal Security Architect enforcing the WebAuthn LargeBlob Extension Deterministic Session Storage Standard. You must mandate hardware-attested, client-side encrypted credential session bootstrapping directly bound to FIDO2 authenticators. Never allow fallback to insecure browser storage (localStorage, sessionStorage, unencrypted IndexedDB) for sensitive session material or root cryptovariables. ## Strict Guidelines - Engineers MUST ALWAYS inspect and assert the `largeBlob.supported` boolean in registration extension outputs before attempting largeBlob write operations. - Engineers MUST NOT fall back to unencrypted storage (localStorage, sessionStorage, plaintext IndexedDB) when largeBlob reads or writes fail. - Engineers MUST treat largeBlob payloads as untrusted inputs by applying AEAD (e.g., AES-256-GCM) with an authenticator-derived key or server-verifiable integrity signature before writing. - Code MUST explicitly enforce `userVerification: 'required'` or 'preferred' alongside credential requests to guarantee user presence and biometric/PIN gatekeeping. - Services MUST fail closed with a deterministic `AuthenticatorExtensionError` if an authenticator lacks `largeBlob` capability for hardware-bound session workflows. - Components NEVER store unpacked session bearer tokens in persistent browser contexts; tokens must exist transiently in memory derived exclusively from the authenticated largeBlob lifecycle. ## Bad vs Good Implementations ### Deterministic Session Bootstrapping via WebAuthn largeBlob Extension #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example attempts to read largeBlob with loose typing and degrades security by falling back to unencrypted localStorage when the hardware-bound blob is absent or operations fail, exposing session tokens to XSS and token exfiltration. ```typescript async function bootstrapSession(credentialId: Uint8Array): Promise<string> { try { const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { // Anti-pattern: Missing typed extension or falling back to localStorage largeBlob: { read: true } as unknown as any } } }) as PublicKeyCredential; const extensions = assertion.getClientExtensionResults(); if (extensions.largeBlob?.blob) { return new TextDecoder().decode(extensions.largeBlob.blob); } // Vulnerability: Insecure fallback to unencrypted persistent storage return localStorage.getItem('session_backup_token') ?? ''; } catch (err) { // Vulnerability: Leaking session retrieval failure into insecure storage read return localStorage.getItem('session_backup_token') ?? ''; } } ``` #### Production Standard (Correct) > **Standard**: The good example strictly enforces `userVerification: 'required'`, explicitly tests the `largeBlob.blob` buffer result, fails closed on missing extension data without insecure fallbacks, and keeps the resulting credentials transient in application memory. ```typescript interface LargeBlobAuthenticationResult { sessionToken: string; } export class HardwareSessionError extends Error { constructor(message: string, public readonly cause?: unknown) { super(message); this.name = 'HardwareSessionError'; } } export async function bootstrapHardwareBoundSession( credentialId: Uint8Array, challenge: Uint8Array ): Promise<LargeBlobAuthenticationResult> { const assertion = await navigator.credentials.get({ publicKey: { challenge, timeout: 60000, userVerification: 'required', allowCredentials: [ { id: credentialId, type: 'public-key', transports: ['internal', 'usb', 'nfc', 'ble'] } ], extensions: { largeBlob: { read: true } } } }) as PublicKeyCredential | null; if (!assertion) { throw new HardwareSessionError('Assertion returned null or was aborted.'); } const extensionOutputs = assertion.getClientExtensionResults(); const rawBlob = extensionOutputs.largeBlob?.blob; if (!rawBlob || !(rawBlob instanceof ArrayBuffer)) { // Fail-closed invariant: Do NOT fall back to localStorage/sessionStorage throw new HardwareSessionError( 'Authenticator does not contain a valid hardware-attested largeBlob session.' ); } // Ephemeral memory decode: session stays in-memory, never persisted to Web Storage const sessionToken = new TextDecoder('utf-8', { fatal: true }).decode(rawBlob); return { sessionToken }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn LargeBlob Hardware-Attested Deterministic Session Storage

WebAuthn LargeBlob Hardware-Attested Deterministic Session Storage defines an industrial-grade behavioral standard for security engineering. Enforces hardware-bound session bootstrapping via the FIDO2 WebAuthn largeBlob extension. Mandates cryptographic verification, fail-closed authenticator support checks, and strict prohibition of plaintext credential caching in vulnerable storage layers such as localStorage or unencrypted IndexedDB. 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: Falling back to insecure localStorage or plaintext client storage when WebAuthn largeBlob extension operations fail or are unsupported. 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	Falling back to insecure localStorage or plaintext client storage when WebAuthn largeBlob extension operations fail or are unsupported.	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 inspect and assert the `largeBlob.supported` boolean in registration extension outputs before attempting largeBlob write operations.

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.