Passkey WebAuthn largeBlob Zero-Knowledge Envelope Encryption Standard

--- description: Passkey WebAuthn largeBlob Zero-Knowledge Envelope Encryption Standard - Enforces client-side zero-knowledge envelope encryption on all WebAuthn largeBlob extension payloads prior to calling navigator.credentials.create or navigator.credentials.get. Prevents identity leakage, session hijacking, and cross-account transplant attacks in the event of compromised passkey cloud sync vaults (e.g., iCloud Keychain, Google Password Manager). globs: src/**/auth/**/*.{ts,tsx}, src/**/passkey/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/crypto/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-largeblob-envelope-encryption-standard-passkey-webauthn-130" --- # Passkey WebAuthn largeBlob Zero-Knowledge Envelope Encryption Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Plaintext or Server-Known Keys into Authenticator largeBlob Extensions Without Cryptographic Envelope Binding ## System Constraints You are a Principal Security Architect enforcing the Passkey WebAuthn largeBlob Ephemeral Envelope Encryption Standard. WebAuthn largeBlob extensions sync across device cloud ecosystems without hardware boundary guarantees against cloud platform subpoena or sync vault exfiltration. You must strictly mandate client-side zero-knowledge envelope encryption (AES-256-GCM + Authenticator PRF or client-side KEK derivation) with Additional Authenticated Data (AAD) bound to the credential ID, user handle, and RP ID before any largeBlob write occurs. ## Strict Guidelines - Engineers MUST ALWAYS encrypt largeBlob payloads using an ephemeral Data Encryption Key (DEK) via AES-256-GCM before writing to the authenticator. - Engineers MUST derive the Key Encryption Key (KEK) using a client-side zero-knowledge source, such as the WebAuthn PRF (pseudo-random function) extension or Argon2id/PBKDF2 over client master passphrases; raw server secrets MUST NEVER serve as the sole KEK. - Engineers MUST bind RP ID, Credential ID, and User Handle as Additional Authenticated Data (AAD) in the AES-GCM cipher parameters to prevent cross-account transplant attacks across passkeys. - Engineers MUST NOT write plaintext JSON, sensitive PII, raw access tokens, or unencrypted cryptographic keys directly into largeBlob write buffers. - Code SHOULD zeroize ephemeral DEKs and sensitive plaintext buffers from memory (e.g., via Uint8Array.fill(0)) immediately after ciphertext generation. - Services MUST NEVER receive or store the KEK or decrypted largeBlob payload on application servers; only zero-knowledge verification proofs or re-encrypted envelopes may be transmitted if cloud backup is needed. ## Bad vs Good Implementations ### Client-Side Envelope Encryption with AAD for WebAuthn largeBlob #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing serialized plaintext directly to the largeBlob extension leaves user tokens and PII fully vulnerable to compromise if the vendor's synced passkey cloud vault (e.g., iCloud Keychain or Google Password Manager) is breached or inspected. It also lacks authentication binding (AAD) against credential transplant attacks. ```typescript export async function saveSessionToPasskey( credentialId: Uint8Array, sessionData: { token: string; userId: string } ): Promise<Credential | null> { // VULNERABILITY: Raw plaintext serialized into largeBlob // Any cloud sync breach exposes the session token in plaintext. const rawBlob = new TextEncoder().encode(JSON.stringify(sessionData)); return navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: rawBlob } } } }); } ``` #### Production Standard (Correct) > **Standard**: Implements zero-knowledge envelope encryption using an ephemeral AES-256-GCM DEK wrapped by a client-side KEK. Binds the RP ID, Credential ID, and User Handle as Additional Authenticated Data (AAD) to prevent blob transplant attacks, and explicitly zeroes out sensitive plaintext buffers from memory. ```typescript export interface EncryptedBlobEnvelope { version: 1; iv: string; // base64url wrappedDek: string; // base64url ciphertext: string; // base64url } export async function encryptAndWriteLargeBlob( credentialId: Uint8Array, userHandle: Uint8Array, rpId: string, kekKey: CryptoKey, payload: Record<string, unknown> ): Promise<Credential | null> { const iv = crypto.getRandomValues(new Uint8Array(12)); const rawPlaintext = new TextEncoder().encode(JSON.stringify(payload)); // 1. Generate ephemeral DEK (AES-256-GCM) const dek = await crypto.subtle.generateKey( { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt'] ); // 2. Construct AAD binding credential context to prevent transplant attacks const aadBuffer = new TextEncoder().encode( `${rpId}:${Array.from(credentialId).join(',')}:${Array.from(userHandle).join(',')}` ); // 3. Encrypt payload with DEK and AAD const ciphertextBuffer = await crypto.subtle.encrypt( { name: 'AES-GCM', iv, additionalData: aadBuffer }, dek, rawPlaintext ); // 4. Wrap DEK using PRF-derived KEK const rawDek = await crypto.subtle.exportKey('raw', dek); const wrappedDekIv = crypto.getRandomValues(new Uint8Array(12)); const wrappedDekBuffer = await crypto.subtle.encrypt( { name: 'AES-GCM', iv: wrappedDekIv, additionalData: aadBuffer }, kekKey, rawDek ); // 5. Zeroize raw key buffer immediately new Uint8Array(rawDek).fill(0); rawPlaintext.fill(0); // 6. Pack zero-knowledge envelope into largeBlob const envelope = { version: 1, iv: Buffer.from(iv).toString('base64url'), dekIv: Buffer.from(wrappedDekIv).toString('base64url'), wrappedDek: Buffer.from(wrappedDekBuffer).toString('base64url'), ciphertext: Buffer.from(ciphertextBuffer).toString('base64url') }; const serializedEnvelope = new TextEncoder().encode(JSON.stringify(envelope)); return navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), rpId, allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: serializedEnvelope } } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey WebAuthn largeBlob Zero-Knowledge Envelope Encryption Standard

Passkey WebAuthn largeBlob Zero-Knowledge Envelope Encryption Standard defines an industrial-grade behavioral standard for security engineering. Enforces client-side zero-knowledge envelope encryption on all WebAuthn largeBlob extension payloads prior to calling navigator.credentials.create or navigator.credentials.get. Prevents identity leakage, session hijacking, and cross-account transplant attacks in the event of compromised passkey cloud sync vaults (e.g., iCloud Keychain, Google Password Manager). 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: Persisting Plaintext or Server-Known Keys into Authenticator largeBlob Extensions Without Cryptographic Envelope Binding 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	Persisting Plaintext or Server-Known Keys into Authenticator largeBlob Extensions Without Cryptographic Envelope Binding	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 encrypt largeBlob payloads using an ephemeral Data Encryption Key (DEK) via AES-256-GCM before writing to the authenticator.

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.