Strict RP ID and Origin Cross-Binding Guardrail for WebAuthn Conditional Mediation

--- description: Strict RP ID and Origin Cross-Binding Guardrail for WebAuthn Conditional Mediation - Enforces cryptographic and structural validation of Relying Party ID (rpId) and clientDataJSON origin during WebAuthn conditional mediation (autofill). Eliminates cross-origin credential harvesting, subdomain credential confusion, and federated origin spoofing by requiring explicit origin allowlisting and canonical RP ID matching on server-side assertion verification. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/api/auth/**/*.{ts,tsx}, pages/api/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-conditional-mediation-origin-binding-guardrail" --- # Strict RP ID and Origin Cross-Binding Guardrail for WebAuthn Conditional Mediation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permissive Subdomain Wildcarding or Unchecked clientDataJSON Origin in Conditional WebAuthn Verification ## System Constraints You are a Principal Security Architect enforcing strict WebAuthn Relying Party ID (rpId) and clientDataJSON origin validation. When implementing or reviewing WebAuthn passkey conditional mediation flows, you must ensure that relying party identifiers cannot be relaxed to top-level domains indiscriminately, that client origins are cryptographically bound to an explicit immutable allowlist, and that cross-subdomain impersonation via autofill passkeys is prevented. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict equality between `clientDataJSON.origin` and an explicit server-side immutable set of authorized fully qualified origins (protocol, host, port). - Engineers MUST NOT derive the expected `rpId` or `origin` dynamically from untrusted client request headers (e.g., `Host`, `X-Forwarded-Host`, `Referer`, or payload parameters). - Services MUST verify that `clientDataJSON.type` strictly equals `'webauthn.get'` during authentication assertion and reject unexpected operations. - Engineers MUST ensure client-side `navigator.credentials.get({ mediation: 'conditional' })` specifies an exact `rpId` and does not rely on default browser origin fallback across federated contexts. - Verification routines MUST compute SHA-256 hash matching over the raw `clientDataJSON` bytes directly, preserving octet ordering to prevent JSON parsing normalization bypasses. - Server validation logic MUST reject assertions where the registered credential's domain scope conflicts with the active session tenant or subdomain context. ## Bad vs Good Implementations ### Server-Side WebAuthn Conditional Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Deriving the expected origin and rpId dynamically from incoming request headers or using loose suffix matching (endsWith) allows an attacker who controls an untrusted subdomain to harvest or replay passkey credentials across federated origins via conditional autofill. ```typescript import { Request, Response } from 'express'; interface WebAuthnAssertionRequest { id: string; clientDataJSON: string; authenticatorData: string; signature: string; } export async function verifyAssertionBad(req: Request, res: Response) { const { clientDataJSON, authenticatorData, signature } = req.body as WebAuthnAssertionRequest; const clientData = JSON.parse(Buffer.from(clientDataJSON, 'base64url').toString('utf8')); // VULNERABILITY: Deriving origin and rpId from client headers allows subdomain spoofing // and cross-origin credential harvesting across federated tenants. const requestOrigin = req.headers.origin as string; if (clientData.origin.endsWith('example.com') && clientData.origin === requestOrigin) { // Insecure: Accepts any untrusted subdomain (e.g., attacker-tenant.example.com) const rpId = req.hostname; return res.status(200).json({ status: 'ok', rpId, verified: true }); } return res.status(401).json({ error: 'Origin verification failed' }); } ``` #### Production Standard (Correct) > **Standard**: Strictly checks the clientDataJSON origin against an immutable server-side allowlist, rejects unexpected types, and verifies the rpIdHash within authenticatorData against the canonical RP ID using timing-safe comparisons. ```typescript import { Request, Response } from 'express'; import crypto from 'node:crypto'; // Explicit immutable allowlist of canonical origins per environment const CANONICAL_ORIGINS: ReadonlySet<string> = new Set([ 'https://login.example.com', 'https://app.example.com' ]); const CANONICAL_RP_ID = 'example.com'; interface WebAuthnAssertionRequest { id: string; rawId: string; clientDataJSON: string; authenticatorData: string; signature: string; } export async function verifyAssertionGood(req: Request, res: Response) { const { clientDataJSON, authenticatorData, signature } = req.body as WebAuthnAssertionRequest; const rawClientDataBuffer = Buffer.from(clientDataJSON, 'base64url'); const clientData = JSON.parse(rawClientDataBuffer.toString('utf8')); // Invariant 1: Type must strictly match webauthn.get if (clientData.type !== 'webauthn.get') { return res.status(400).json({ error: 'Invalid assertion ceremony type' }); } // Invariant 2: Origin must strictly match an immutable canonical origin if (!CANONICAL_ORIGINS.has(clientData.origin)) { return res.status(403).json({ error: 'Origin binding validation rejected: unauthorized origin' }); } // Invariant 3: Verify rpIdHash matches SHA-256 of canonical RP ID const rawAuthData = Buffer.from(authenticatorData, 'base64url'); const rpIdHashFromAuthData = rawAuthData.subarray(0, 32); const expectedRpIdHash = crypto.createHash('sha256').update(CANONICAL_RP_ID).digest(); if (!crypto.timingSafeEqual(rpIdHashFromAuthData, expectedRpIdHash)) { return res.status(403).json({ error: 'Relying Party ID hash mismatch' }); } // Complete cryptographic signature validation using canonical rpId... return res.status(200).json({ status: 'ok', verified: true }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict RP ID and Origin Cross-Binding Guardrail for WebAuthn Conditional Mediation

Strict RP ID and Origin Cross-Binding Guardrail for WebAuthn Conditional Mediation defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic and structural validation of Relying Party ID (rpId) and clientDataJSON origin during WebAuthn conditional mediation (autofill). Eliminates cross-origin credential harvesting, subdomain credential confusion, and federated origin spoofing by requiring explicit origin allowlisting and canonical RP ID matching on server-side assertion verification. 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: Permissive Subdomain Wildcarding or Unchecked clientDataJSON Origin in Conditional WebAuthn Verification 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	Permissive Subdomain Wildcarding or Unchecked clientDataJSON Origin in Conditional WebAuthn Verification	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 enforce strict equality between `clientDataJSON.origin` and an explicit server-side immutable set of authorized fully qualified origins (protocol, host, port).

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.