Passkey Conditional Mediation Cross-Origin Downgrade Fencing & RP Binding Invariant

--- description: Passkey Conditional Mediation Cross-Origin Downgrade Fencing & RP Binding Invariant - Enforces cryptographic and architectural fencing for WebAuthn autofill (conditional mediation) flows to prevent relying-party origin reflection vulnerabilities. Verifies that the clientDataJSON origin and authenticatorData rpIdHash match immutable, cryptographically sealed whitelists rather than trusting incoming HTTP headers or permissive cross-origin delegations. globs: src/**/auth/**/*.{ts,tsx,js,jsx}, src/**/webauthn/**/*.{ts,tsx,js,jsx}, src/**/api/**/*.{ts,tsx,js,jsx}, src/**/services/auth/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-conditional-mediation-origin-downgrade-fencing" --- # Passkey Conditional Mediation Cross-Origin Downgrade Fencing & RP Binding Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Reflecting Dynamic HTTP Origin/Host Headers into WebAuthn Assertion RP Verification ## System Constraints You are a Principal Security Architect enforcing cryptographic origin integrity and WebAuthn Conditional Mediation fencing. You must prevent cross-origin downgrade attacks, subdomain assertion hijacking, and HTTP header reflection during passkey autofill. Mandate strict cryptographic verification of `clientDataJSON.origin`, `clientDataJSON.crossOrigin`, and `authenticatorData.rpIdHash` against immutable, environment-sealed canonical identity bounds. ## Strict Guidelines - Engineers MUST ALWAYS match clientDataJSON.origin against an immutable, hardcoded or environment-sealed set of fully qualified canonical origins. - Engineers MUST NEVER reflect `req.headers.origin`, `req.headers.host`, or `X-Forwarded-Host` into the `expectedOrigin` or `expectedRPID` verification parameters. - Code SHOULD inspect the `crossOrigin` boolean in `clientDataJSON` and explicitly reject assertion responses where `crossOrigin === true` unless multi-domain iframe delegation is cryptographically authorized and structurally isolated. - Services MUST verify that `authenticatorData.rpIdHash` matches the SHA-256 hash of the canonical RP ID (e.g., `crypto.subtle.digest('SHA-256', canonicalRpId)`). - Components NEVER trigger `navigator.credentials.get({ mediation: 'conditional' })` inside untrusted, cross-origin, or un-sandboxed iframes lacking explicit `publickey-credentials-get` Feature-Policy / Permissions-Policy declarations. ## Bad vs Good Implementations ### Vulnerable Dynamic Origin Reflection vs. Fenced Immutable RP Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Deriving expectedOrigin and expectedRPID dynamically from incoming HTTP headers (Origin/Host) permits origin reflection and cross-origin downgrade attacks. An attacker manipulating proxy headers or routing assertions through alternative endpoints can coerce verification against an unauthorized relying party context. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; export async function verifyPasskeyAssertion(req: Request, res: Response) { const { assertionResponse, challenge } = req.body; // CRITICAL SECURITY FLAW: Reflecting dynamic HTTP host/origin headers // Attacker on a compromised subdomain or malicious origin can spoof expectedOrigin/expectedRPID const clientOrigin = req.headers.origin || `https://${req.headers.host}`; const derivedRpId = new URL(clientOrigin).hostname; const verification = await verifyAuthenticationResponse({ response: assertionResponse, expectedChallenge: challenge, expectedOrigin: clientOrigin, expectedRPID: derivedRpId, requireUserVerification: true, }); if (!verification.verified) { return res.status(401).json({ error: 'Authentication failed' }); } return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: Decodes and inspects clientDataJSON prior to crypto assertion, fences the origin against an immutable compile-time allowlist, verifies that crossOrigin downgrade flags are strictly rejected, and anchors expectedRPID to an unalterable canonical domain identifier. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; // Cryptographically sealed canonical relying party parameters const CANONICAL_RP_ID = Object.freeze('identity.corp.example.com'); const TRUSTED_ORIGIN_SET = Object.freeze(new Set([ 'https://identity.corp.example.com', 'https://login.corp.example.com' ])); export async function verifyPasskeyAssertion(req: Request, res: Response) { const { assertionResponse, sessionChallenge } = req.body; // Decode clientDataJSON to evaluate structural security fields const rawClientData = Buffer.from(assertionResponse.response.clientDataJSON, 'base64url').toString('utf8'); const clientData = JSON.parse(rawClientData); // 1. Verify exact operation intent if (clientData.type !== 'webauthn.get') { return res.status(400).json({ error: 'Invalid WebAuthn operation type' }); } // 2. Fence origin strictly against sealed allowlist (reject header reflection) if (!TRUSTED_ORIGIN_SET.has(clientData.origin)) { return res.status(403).json({ error: 'Assertion origin not permitted by relying party fencing' }); } // 3. Reject cross-origin autofill downgrades unless explicitly handled if (clientData.crossOrigin === true) { return res.status(403).json({ error: 'Cross-origin conditional mediation is explicitly rejected' }); } const verification = await verifyAuthenticationResponse({ response: assertionResponse, expectedChallenge: sessionChallenge, expectedOrigin: clientData.origin, expectedRPID: CANONICAL_RP_ID, requireUserVerification: true, }); if (!verification.verified) { return res.status(401).json({ error: 'Cryptographic assertion verification failed' }); } return res.json({ success: true }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey Conditional Mediation Cross-Origin Downgrade Fencing & RP Binding Invariant

Passkey Conditional Mediation Cross-Origin Downgrade Fencing & RP Binding Invariant defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic and architectural fencing for WebAuthn autofill (conditional mediation) flows to prevent relying-party origin reflection vulnerabilities. Verifies that the clientDataJSON origin and authenticatorData rpIdHash match immutable, cryptographically sealed whitelists rather than trusting incoming HTTP headers or permissive cross-origin delegations. 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: Reflecting Dynamic HTTP Origin/Host Headers into WebAuthn Assertion RP 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	Reflecting Dynamic HTTP Origin/Host Headers into WebAuthn Assertion RP 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 match clientDataJSON.origin against an immutable, hardcoded or environment-sealed set of fully qualified canonical origins.

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.