WebAuthn Level 3 ClientDataJSON Origin Binding & Related Origin Validation

--- description: WebAuthn Level 3 ClientDataJSON Origin Binding & Related Origin Validation - Enforces strict canonical origin binding verification on deserialized WebAuthn Level 3 clientDataJSON payloads in federated multi-tenant edge architectures. Precludes sub-origin relay, cross-tenant impersonation, and conditional UI credential leakage by enforcing strict exact-match origin validation, scheme/port verification, and Related Origin Requests (ROR) explicit allowlisting across reverse-proxy layers. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/identity/**/*.{ts,tsx}, src/**/guards/**/*.{ts,tsx}, edge/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-client-data-origin-binding-invariant" --- # WebAuthn Level 3 ClientDataJSON Origin Binding & Related Origin Validation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Lax or Regex-Based Origin Validation Allowing Subdomain Traversal and Cross-Tenant Credential Relay ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 Client Data JSON Origin Binding Invariant. In multi-tenant edge architectures with federated passkey auto-fill (Conditional UI), relying party authentication handlers must enforce deterministic, constant-time origin validation. Reject regex suffix matching, unverified sub-origins, and ambient Host headers. Strictly mandate exact canonical tuple matches (scheme, fully-qualified domain, port) and validate the Relying Party ID against canonical tenant metadata or explicit Related Origin Requests (ROR) manifests. ## Strict Guidelines - Engineers MUST ALWAYS parse `clientDataJSON` using a secure JSON parser and extract the canonical `origin` tuple (scheme, hostname, port) using the standard `URL` Web API. - Engineers MUST NEVER perform substring, suffix (`endsWith`), or loose regular-expression matching on `clientData.origin` to avoid sub-origin traversal (e.g., `tenant-a.auth.example.com.attacker.com`). - Services MUST validate that `clientData.origin` exactly matches the expected canonical tenant origin registered in cryptographic tenant metadata, or matches a strictly verified Related Origin Requests (ROR) set. - Services MUST verify that `clientData.type` is strictly either `webauthn.get` or `webauthn.create` matching the operational context, and verify the cryptographic signature over `clientDataHash`. - Edge Proxies MUST NOT rewrite or forward untrusted ambient `Host` or `X-Forwarded-Host` headers as the expected origin ground truth for WebAuthn authentication ceremony assertions. ## Bad vs Good Implementations ### WebAuthn clientDataJSON Origin Validation in Multi-Tenant Edge Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `String.prototype.endsWith()` allows an attacker to mount sub-origin relay attacks by registering domains such as `victim.domain.attacker.com`. Additionally, checking `type.startsWith('webauthn.')` permits registration credentials (`webauthn.create`) to be submitted to assertion endpoints (`webauthn.get`). ```typescript import { AuthenticatorAssertionResponse } from '@simplewebauthn/types'; interface VerifyRequest { tenantId: string; response: AuthenticatorAssertionResponse; } export async function verifyAssertionBad(req: VerifyRequest, tenantBaseDomain: string) { const clientData = JSON.parse( Buffer.from(req.response.clientDataJSON, 'base64url').toString('utf-8') ); // CRITICAL VULNERABILITY: Loose suffix matching allows relay attacks // e.g. 'https://tenant-target.corp.com.attacker-controlled.net' passes if (!clientData.origin.endsWith(tenantBaseDomain)) { throw new Error('Invalid origin'); } // CRITICAL VULNERABILITY: Permissive type check allows registration replay in auth flow if (!clientData.type.startsWith('webauthn.')) { throw new Error('Invalid ceremony type'); } return true; } ``` #### Production Standard (Correct) > **Standard**: Parses the origin using the `URL` API to normalize the scheme, host, and port tuple, then evaluates canonical equivalence against tenant isolation boundaries and explicit Related Origin sets. Validates the exact ceremonial operation (`webauthn.get`) and performs constant-time challenge comparison before returning the cryptographic `clientDataHash`. ```typescript import { AuthenticatorAssertionResponse } from '@simplewebauthn/types'; import crypto from 'node:crypto'; interface VerifyRequest { tenantId: string; response: AuthenticatorAssertionResponse; expectedChallenge: string; } interface TenantConfig { expectedOrigin: string; // e.g. 'https://tenant-a.identity.cloud.com' allowedRelatedOrigins: ReadonlySet<string>; expectedRpId: string; } export async function verifyAssertionSecure( req: VerifyRequest, tenant: TenantConfig ): Promise<{ clientDataHash: Buffer }> { const rawClientData = Buffer.from(req.response.clientDataJSON, 'base64url'); const clientData = JSON.parse(rawClientData.toString('utf-8')); // INVARIANT 1: Strict ceremony type assertion if (clientData.type !== 'webauthn.get') { throw new Error('Disallowed clientData type: expected webauthn.get'); } // INVARIANT 2: Constant-time challenge comparison const clientChallenge = Buffer.from(clientData.challenge, 'base64url'); const expectedChallengeBuf = Buffer.from(req.expectedChallenge, 'base64url'); if ( clientChallenge.length !== expectedChallengeBuf.length || !crypto.timingSafeEqual(clientChallenge, expectedChallengeBuf) ) { throw new Error('Challenge mismatch'); } // INVARIANT 3: Strict origin parsing and canonical tuple validation const clientOriginUrl = new URL(clientData.origin); const canonicalClientOrigin = clientOriginUrl.origin; const isPrimaryOrigin = canonicalClientOrigin === tenant.expectedOrigin; const isRelatedOrigin = tenant.allowedRelatedOrigins.has(canonicalClientOrigin); if (!isPrimaryOrigin && !isRelatedOrigin) { throw new Error(`Unauthorized origin binding: ${canonicalClientOrigin}`); } // Compute SHA-256 clientDataHash for signature verification over authenticatorData const clientDataHash = crypto.createHash('sha256').update(rawClientData).digest(); return { clientDataHash }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 ClientDataJSON Origin Binding & Related Origin Validation

WebAuthn Level 3 ClientDataJSON Origin Binding & Related Origin Validation defines an industrial-grade behavioral standard for security engineering. Enforces strict canonical origin binding verification on deserialized WebAuthn Level 3 clientDataJSON payloads in federated multi-tenant edge architectures. Precludes sub-origin relay, cross-tenant impersonation, and conditional UI credential leakage by enforcing strict exact-match origin validation, scheme/port verification, and Related Origin Requests (ROR) explicit allowlisting across reverse-proxy layers. 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: Lax or Regex-Based Origin Validation Allowing Subdomain Traversal and Cross-Tenant Credential Relay 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	Lax or Regex-Based Origin Validation Allowing Subdomain Traversal and Cross-Tenant Credential Relay	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 parse `clientDataJSON` using a secure JSON parser and extract the canonical `origin` tuple (scheme, hostname, port) using the standard `URL` Web API.

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.