Mandatory Zero-Knowledge Client-Side AEAD Envelope Encryption for WebAuthn LargeBlob Storage

Passkey LargeBlob storage synchronizes opaque binary payloads across multi-device credential ecosystems (e.g., Apple iCloud Keychain, Google Password Manager), inherently exposing unencrypted data to synchronization providers. All data committed to WebAuthn LargeBlob must undergo client-side zero-knowledge envelope encryption using authenticated symmetric ciphers (AES-256-GCM) with distinct ephemeral Data Encryption Keys (DEK) wrapped by a hardened Key Encryption Key (KEK) derived independently of the passkey provider.

--- description: Mandatory Zero-Knowledge Client-Side AEAD Envelope Encryption for WebAuthn LargeBlob Storage - Passkey LargeBlob storage synchronizes opaque binary payloads across multi-device credential ecosystems (e.g., Apple iCloud Keychain, Google Password Manager), inherently exposing unencrypted data to synchronization providers. All data committed to WebAuthn LargeBlob must undergo client-side zero-knowledge envelope encryption using authenticated symmetric ciphers (AES-256-GCM) with distinct ephemeral Data Encryption Keys (DEK) wrapped by a hardened Key Encryption Key (KEK) derived independently of the passkey provider. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-largeblob-envelope-encryption-standard" --- # Mandatory Zero-Knowledge Client-Side AEAD Envelope Encryption for WebAuthn LargeBlob Storage > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Raw Plaintext or Unauthenticated Payloads Directly into WebAuthn LargeBlob Storage ## System Constraints You are a Principal Security Architect enforcing zero-knowledge client-side envelope encryption across all WebAuthn LargeBlob operations. LargeBlob sync providers must remain untrusted conduits. You must reject any code committing unencrypted data, raw JSON, or unauthenticated ciphers to `largeBlob.write`. Mandate ephemeral DEK generation via AES-256-GCM with unique 96-bit nonces, DEK wrapping via KEK (derived from WebAuthn PRF extension or client-side Argon2id/PBKDF2), and strict structural envelope schema verification with constant-time MAC/tag evaluation. ## Strict Guidelines - Engineers MUST ALWAYS encrypt data on the client using an authenticated cipher (AES-256-GCM with a 96-bit cryptographically random IV) prior to passing binary buffers to `largeBlob.write`. - Engineers MUST NOT persist plaintext buffers, unauthenticated ciphertext (e.g., AES-CBC without HMAC), or static nonce-ciphertext pairs into WebAuthn LargeBlob structures. - Code SHOULD implement envelope encryption: an ephemeral Data Encryption Key (DEK) encrypts the user payload, and a Key Encryption Key (KEK)—derived from the WebAuthn PRF extension or client passphrase—wraps the DEK using AES-KW or AES-GCM. - Services MUST validate the envelope header, payload format version, and 128-bit authentication tag before parsing or exposing decrypted buffer contents to downstream domain memory. - Components NEVER leak decrypted LargeBlob contents or raw cryptographic keys into unencrypted browser persistence (localStorage, sessionStorage, unencrypted IndexedDB) or telemetry diagnostics. ## Bad vs Good Implementations ### Client-Side Zero-Knowledge LargeBlob Envelope Encryption vs. Raw Plaintext Commit #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing serialized plaintext directly into `largeBlob.write` exposes sensitive user data directly to the synchronization provider (Apple, Google, Microsoft, password manager vendors) and compromised client extensions. It lacks authenticity verification and confidentiality. ```typescript export async function saveUserDataToLargeBlob( credentialId: string, userData: Record<string, unknown> ): Promise<void> { // CRITICAL VULNERABILITY: Plaintext written directly to LargeBlob sync provider const rawBuffer = new TextEncoder().encode(JSON.stringify(userData)); await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: Buffer.from(credentialId, 'base64'), type: 'public-key' }], extensions: { largeBlob: { write: rawBuffer.buffer } } } }); } ``` #### Production Standard (Correct) > **Standard**: Implements zero-knowledge symmetric envelope encryption: payload is encrypted with an ephemeral DEK using authenticated AES-256-GCM, the DEK is encrypted with the client's KEK, and only the ciphertext envelope is committed to the synchronizing WebAuthn authenticator. ```typescript export interface EncryptedEnvelope { version: number; iv: string; wrappedDek: string; dekIv: string; ciphertext: string; } export async function saveUserDataToLargeBlob( credentialId: string, userData: Record<string, unknown>, kekCryptoKey: CryptoKey ): Promise<void> { const payloadBytes = new TextEncoder().encode(JSON.stringify(userData)); // 1. Generate ephemeral 256-bit AES-GCM Data Encryption Key (DEK) const dek = await window.crypto.subtle.generateKey( { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt'] ); // 2. Encrypt payload with DEK using cryptographically random 96-bit IV const payloadIv = window.crypto.getRandomValues(new Uint8Array(12)); const ciphertextBuffer = await window.crypto.subtle.encrypt( { name: 'AES-GCM', iv: payloadIv, tagLength: 128 }, dek, payloadBytes ); // 3. Wrap DEK with Key Encryption Key (KEK) const dekIv = window.crypto.getRandomValues(new Uint8Array(12)); const rawDek = await window.crypto.subtle.exportKey('raw', dek); const wrappedDekBuffer = await window.crypto.subtle.encrypt( { name: 'AES-GCM', iv: dekIv, tagLength: 128 }, kekCryptoKey, rawDek ); // 4. Pack into authenticated envelope buffer const envelope: EncryptedEnvelope = { version: 1, iv: btoa(String.fromCharCode(...payloadIv)), wrappedDek: btoa(String.fromCharCode(...new Uint8Array(wrappedDekBuffer))), dekIv: btoa(String.fromCharCode(...dekIv)), ciphertext: btoa(String.fromCharCode(...new Uint8Array(ciphertextBuffer))) }; const envelopeBuffer = new TextEncoder().encode(JSON.stringify(envelope)); // 5. Commit envelope safely to LargeBlob await navigator.credentials.get({ publicKey: { challenge: window.crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: Uint8Array.from(atob(credentialId), c => c.charCodeAt(0)), type: 'public-key' }], extensions: { largeBlob: { write: envelopeBuffer.buffer } } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Zero-Knowledge Client-Side AEAD Envelope Encryption for WebAuthn LargeBlob Storage

Mandatory Zero-Knowledge Client-Side AEAD Envelope Encryption for WebAuthn LargeBlob Storage defines an industrial-grade behavioral standard for security engineering. Passkey LargeBlob storage synchronizes opaque binary payloads across multi-device credential ecosystems (e.g., Apple iCloud Keychain, Google Password Manager), inherently exposing unencrypted data to synchronization providers. All data committed to WebAuthn LargeBlob must undergo client-side zero-knowledge envelope encryption using authenticated symmetric ciphers (AES-256-GCM) with distinct ephemeral Data Encryption Keys (DEK) wrapped by a hardened Key Encryption Key (KEK) derived independently of the passkey provider. 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 Raw Plaintext or Unauthenticated Payloads Directly into WebAuthn LargeBlob Storage 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 Raw Plaintext or Unauthenticated Payloads Directly into WebAuthn LargeBlob Storage	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 data on the client using an authenticated cipher (AES-256-GCM with a 96-bit cryptographically random IV) prior to passing binary buffers to `largeBlob.write`.

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.