WebAuthn LargeBlob Authenticated Encryption Verification Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Trusting raw WebAuthn LargeBlob payloads without client-side AEAD envelope verification and credential-bound AAD) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

WebAuthn LargeBlob Authenticated Encryption Verification Standard

--- description: WebAuthn LargeBlob Authenticated Encryption Verification Standard - Enforces client-side Authenticated Encryption with Associated Data (AEAD) envelope verification and strict payload size bounding for WebAuthn LargeBlob extensions. Prevents credential-state tampering, ciphertext malleability, and memory-exhaustion attacks across multi-tenant or shared hardware authenticators by binding the credential ID to the AEAD Additional Authenticated Data (AAD). globs: src/**/auth/**/*.{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-aead-envelope-verification" --- # WebAuthn LargeBlob Authenticated Encryption Verification Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting raw WebAuthn LargeBlob payloads without client-side AEAD envelope verification and credential-bound AAD ## System Constraints You are a Principal Security Architect enforcing the WebAuthn LargeBlob Authenticated Encryption Verification Standard. WebAuthn authenticators providing the largeBlob extension store opaque bytes that can be modified or overwritten if an attacker gains physical or shared access to the authenticator or intermediate relay channel. You must mandate client-side AEAD (e.g., AES-256-GCM) with strict payload size validation (max 2048 bytes) and explicit binding of the Credential ID and User Handle as Additional Authenticated Data (AAD) prior to serializing or deserializing largeBlob buffers. ## Strict Guidelines - Engineers MUST ALWAYS encrypt largeBlob payloads using client-side AEAD (AES-GCM-256 or ChaCha20-Poly1305) before writing to the WebAuthn largeBlob extension. - Engineers MUST ALWAYS bind the Credential ID, User Handle, and Relying Party ID into the AEAD Additional Authenticated Data (AAD) to prevent ciphertext transplantation across credentials. - Engineers MUST NOT trust or parse unverified largeBlob data before cryptographic MAC verification succeeds. - Services MUST enforce strict envelope size limits (e.g., max 2048 bytes) before writing or upon reading raw largeBlob buffers to prevent client-side denial-of-service or buffer overflow vulnerabilities. - Components NEVER store encryption master keys inside the largeBlob itself; keys must derive from PRF (Pseudo-Random Function WebAuthn extension) or a secure client-managed session secret. ## Bad vs Good Implementations ### WebAuthn LargeBlob Write and Read with AES-256-GCM Envelope Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw largeBlob bytes are parsed directly into memory without cryptographic integrity validation. Any party with physical access to the authenticator or capable of overwriting the largeBlob storage can tamper with stored credentials, inject malicious JSON payloads, or transplant payloads from other credentials. ```typescript export async function readLargeBlob(assertion: PublicKeyCredential): Promise<any> { const extensionResults = assertion.getClientExtensionResults(); // VULNERABLE: Direct deserialization of unverified, unauthenticated raw blob const rawBlob = extensionResults.largeBlob?.blob; if (!rawBlob) { return null; } const decoder = new TextDecoder(); return JSON.parse(decoder.decode(rawBlob)); } ``` #### Production Standard (Correct) > **Standard**: The envelope enforces strict size limits (max 2048 bytes), extracts an initialization vector, and requires AES-256-GCM verification before returning bytes. The raw credential ID and user handle are passed as AAD, mathematically guaranteeing that the blob cannot be transplanted from another authenticator credential. ```typescript const MAX_LARGE_BLOB_BYTES = 2048; const IV_LENGTH_BYTES = 12; const TAG_LENGTH_BYTES = 16; export interface DecryptedLargeBlobEnvelope { payload: Uint8Array; } export async function verifyAndDecryptLargeBlob( assertion: PublicKeyCredential, aeadKey: CryptoKey, expectedUserHandle: Uint8Array ): Promise<Uint8Array | null> { const extensionResults = assertion.getClientExtensionResults(); const rawBlob = extensionResults.largeBlob?.blob; if (!rawBlob) { return null; } const blobBytes = new Uint8Array(rawBlob); if (blobBytes.byteLength > MAX_LARGE_BLOB_BYTES) { throw new SecurityError('LargeBlob payload exceeds maximum allowed boundary.'); } const minLength = IV_LENGTH_BYTES + TAG_LENGTH_BYTES; if (blobBytes.byteLength < minLength) { throw new SecurityError('Malformed LargeBlob envelope: buffer underflow.'); } const iv = blobBytes.subarray(0, IV_LENGTH_BYTES); const ciphertext = blobBytes.subarray(IV_LENGTH_BYTES); // Cryptographically bind Credential ID and User Handle to AAD const credentialIdBytes = new Uint8Array(assertion.rawId); const aad = new Uint8Array(credentialIdBytes.length + expectedUserHandle.length); aad.set(credentialIdBytes, 0); aad.set(expectedUserHandle, credentialIdBytes.length); try { const decryptedBuffer = await crypto.subtle.decrypt( { name: 'AES-GCM', iv: iv, additionalData: aad, tagLength: 128 }, aeadKey, ciphertext ); return new Uint8Array(decryptedBuffer); } catch (err) { throw new SecurityError('LargeBlob AEAD envelope authentication failed: payload tampered or transplanted.', { cause: err }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn LargeBlob Authenticated Encryption Verification Standard

WebAuthn LargeBlob Authenticated Encryption Verification Standard defines an industrial-grade behavioral standard for security engineering. Enforces client-side Authenticated Encryption with Associated Data (AEAD) envelope verification and strict payload size bounding for WebAuthn LargeBlob extensions. Prevents credential-state tampering, ciphertext malleability, and memory-exhaustion attacks across multi-tenant or shared hardware authenticators by binding the credential ID to the AEAD Additional Authenticated Data (AAD). 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: Trusting raw WebAuthn LargeBlob payloads without client-side AEAD envelope verification and credential-bound AAD 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	Trusting raw WebAuthn LargeBlob payloads without client-side AEAD envelope verification and credential-bound AAD	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 client-side AEAD (AES-GCM-256 or ChaCha20-Poly1305) before writing to the WebAuthn largeBlob extension.

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.