Client-Side Cryptographic Vault Isolation for WebAuthn largeBlob Payloads

Enforces mandatory client-side authenticated envelope encryption (AEAD) for all payloads destined for the WebAuthn largeBlob extension. Modern passkeys replicate across third-party cloud synchronization fabrics (e.g., Apple iCloud Keychain, Google Password Manager), exposing raw blob data to vendor infrastructure unless shielded by zero-knowledge client-side encryption. All reads and writes must cryptographically bind the relying party identity and credential ID to the encrypted envelope.

--- description: Client-Side Cryptographic Vault Isolation for WebAuthn largeBlob Payloads - Enforces mandatory client-side authenticated envelope encryption (AEAD) for all payloads destined for the WebAuthn largeBlob extension. Modern passkeys replicate across third-party cloud synchronization fabrics (e.g., Apple iCloud Keychain, Google Password Manager), exposing raw blob data to vendor infrastructure unless shielded by zero-knowledge client-side encryption. All reads and writes must cryptographically bind the relying party identity and credential ID to the encrypted envelope. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-largeblob-client-side-encryption-vault" --- # Client-Side Cryptographic Vault Isolation for WebAuthn largeBlob Payloads > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Unencrypted or Malleable Plaintext directly into WebAuthn largeBlob Extension Buffers ## System Constraints You are a Principal Security Architect enforcing Zero-Knowledge isolation across WebAuthn credential vaults. You must prohibit direct serialization of plaintext buffers into the WebAuthn largeBlob extension. Every largeBlob write operation must be guarded by client-side Authenticated Encryption with Associated Data (AEAD AES-256-GCM), with random Initialization Vectors (IVs) and explicit cryptographic binding to the Credential ID and Relying Party ID via Additional Authenticated Data (AAD). ## Strict Guidelines - Engineers MUST ALWAYS encrypt data using AES-GCM (minimum 256-bit key) or ChaCha20-Poly1305 client-side before assigning any buffer to `publicKey.extensions.largeBlob.write`. - Engineers MUST NOT pass raw UTF-8 serialized strings, JSON blobs, or unencrypted binary buffers directly to `largeBlob.write`. - Code MUST supply the Relying Party ID (`rpId`) and binary `credentialId` as Additional Authenticated Data (AAD) during AEAD encryption to prevent cross-origin or cross-credential blob substitution attacks. - Services MUST generate a cryptographically secure, non-repeating 96-bit initialization vector (`crypto.getRandomValues(new Uint8Array(12))`) for every single `largeBlob.write` operation. - Components NEVER store or transmit unencrypted vault secrets in memory beyond the immediate scope of the cryptographic operation, ensuring plaintext buffers are scrubbed or left to short-lived local lexical scopes. ## Bad vs Good Implementations ### largeBlob Vault Storage: Plaintext Leakage vs. Zero-Knowledge AEAD Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing serialized plaintext directly into `largeBlob.write` violates zero-knowledge security guarantees. Synced passkeys replicate this blob across ecosystem cloud providers in cleartext, exposing sensitive client vault data to platform vendors and unauthorized sync-channel interception. ```typescript export async function storeVaultInLargeBlob( credentialId: Uint8Array, sensitiveVault: Record<string, unknown> ): Promise<void> { // VULNERABLE: Serializing plaintext directly into largeBlob. // Cloud-synced passkey fabrics (Google, Apple) can inspect and index raw payload. const rawData = new TextEncoder().encode(JSON.stringify(sensitiveVault)); await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: rawData } } } }); } ``` #### Production Standard (Correct) > **Standard**: Encrypts the payload using AES-256-GCM with a fresh 96-bit random IV before touching `largeBlob`. It cryptographically binds both the `rpId` and `credentialId` as Additional Authenticated Data (AAD) to prevent cross-credential replay, ensuring zero-knowledge isolation across cloud synchronization providers. ```typescript export interface EncryptedBlobEnvelope { iv: Uint8Array; // 12-byte IV for AES-GCM ciphertext: Uint8Array; // Includes 16-byte authentication tag } export async function storeVaultInLargeBlob( credentialId: Uint8Array, rpId: string, encryptionKey: CryptoKey, sensitiveVault: Record<string, unknown> ): Promise<void> { const plaintext = new TextEncoder().encode(JSON.stringify(sensitiveVault)); const iv = crypto.getRandomValues(new Uint8Array(12)); // Cryptographically bind RP ID and Credential ID via Additional Authenticated Data (AAD) const aad = new TextEncoder().encode(`${rpId}:${Array.from(credentialId).join(',')}`); const ciphertextBuffer = await crypto.subtle.encrypt( { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, encryptionKey, plaintext ); // Pack [12-byte IV | Ciphertext + Tag] into a contiguous envelope const ciphertext = new Uint8Array(ciphertextBuffer); const packedPayload = new Uint8Array(iv.byteLength + ciphertext.byteLength); packedPayload.set(iv, 0); packedPayload.set(ciphertext, iv.byteLength); await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), rpId, allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { largeBlob: { write: packedPayload } } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Client-Side Cryptographic Vault Isolation for WebAuthn largeBlob Payloads

Client-Side Cryptographic Vault Isolation for WebAuthn largeBlob Payloads defines an industrial-grade behavioral standard for security engineering. Enforces mandatory client-side authenticated envelope encryption (AEAD) for all payloads destined for the WebAuthn largeBlob extension. Modern passkeys replicate across third-party cloud synchronization fabrics (e.g., Apple iCloud Keychain, Google Password Manager), exposing raw blob data to vendor infrastructure unless shielded by zero-knowledge client-side encryption. All reads and writes must cryptographically bind the relying party identity and credential ID to the encrypted envelope. 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 Unencrypted or Malleable Plaintext directly into WebAuthn largeBlob Extension Buffers 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 Unencrypted or Malleable Plaintext directly into WebAuthn largeBlob Extension Buffers	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 using AES-GCM (minimum 256-bit key) or ChaCha20-Poly1305 client-side before assigning any buffer to `publicKey.extensions.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.