WebAuthn Related Origin Cryptographic Manifest & Cross-Subdomain Relay Guardrail

--- description: WebAuthn Related Origin Cryptographic Manifest & Cross-Subdomain Relay Guardrail - Precludes subdomain passkey credential relay and token interception across distributed micro-frontends by strictly enforcing W3C WebAuthn Related Origin Requests specifications. Requires deterministic server-side cryptographic validation of clientDataJSON origin against an authoritative, statically verified related-origin manifest, rejecting ambient origin reflection or wildcard rpId relaxation. globs: **/auth/**/*.{ts,tsx}, **/webauthn/**/*.{ts,tsx}, **/api/auth/**/*.{ts,tsx}, **/server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-related-origin-cryptographic-binding" --- # WebAuthn Related Origin Cryptographic Manifest & Cross-Subdomain Relay Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Dynamic RP Origin Reflection or Ambient Subdomain rpId Relaxation Without Strict Related-Origin Manifest Validation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Related Origin Cryptographic Binding Guardrail. You must prohibit any implementation that reflects incoming request origins, uses regex wildcard matching on subdomains, or relies on ambient rpId relaxation without validating against an authoritative W3C Related Origin manifest (.well-known/webauthn). All passkey registration and assertion responses must be cryptographically verified against explicit, immutable origin-to-RP mappings. ## Strict Guidelines - Engineers MUST ALWAYS validate clientDataJSON.origin against an explicit, immutably configured set of authorized related origins derived from the canonical .well-known/webauthn manifest. - Engineers MUST NOT dynamically reflect the HTTP Host, Origin, or Referer header into expectedOrigin during verifyRegistrationResponse or verifyAuthenticationResponse. - Code SHOULD enforce exact protocol, hostname, and port matching on all related origins, strictly rejecting regular expressions, wildcard prefixes (e.g., *.example.com), and unpinned TLS schemes. - Services MUST cryptographically isolate session creation, ensuring passkey challenge records are strictly bound to both the initiating callerOrigin and the target rpId at generation time. - Components NEVER permit client-side micro-frontends to dictate or override the canonical rpId or expectedOrigin parameters evaluated during server-side verification. ## Bad vs Good Implementations ### WebAuthn Assertion Verification with Related Origin Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepting dynamic request headers as expectedOrigin exposes the Relying Party to cross-subdomain credential relay attacks. A compromised adjacent micro-frontend or subdomain can successfully assert passkeys across the domain boundary because rpId is broadly scoped to 'example.com' while origin checks are dynamically bypassed. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; export async function verifyAssertion(req: Request, res: Response) { const { response, challenge } = req.body; // CRITICAL SECURITY VULNERABILITY: Dynamically reflecting req.headers.origin // allows any compromised subdomain or malicious origin passing CORS to relay passkey assertions. const dynamicOrigin = (req.headers.origin as string) || 'https://auth.example.com'; const verification = await verifyAuthenticationResponse({ response, expectedChallenge: challenge, expectedOrigin: dynamicOrigin, expectedRPID: 'example.com', // Relaxed RPID without manifest verification authenticator: { credentialPublicKey: Buffer.from([]), credentialID: 'cred-123', counter: 0, }, }); if (verification.verified) { res.json({ status: 'authenticated' }); } } ``` #### Production Standard (Correct) > **Standard**: Implements deterministic cryptographic binding against an immutable set of origins compliant with the W3C WebAuthn Related Origin Requests specification. Ensures that both session challenge creation and assertion resolution are bound to authorized endpoints, neutralizing subdomain relay vulnerabilities. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; // Authoritative manifest mirroring W3C WebAuthn Related Origin Requests (.well-known/webauthn) const AUTHORIZED_RELATED_ORIGINS = new Set<string>([ 'https://auth.example.com', 'https://checkout.example.com', 'https://dashboard.example.com' ]); const CANONICAL_RP_ID = 'auth.example.com'; interface StoredChallengeSession { challenge: string; boundOrigin: string; expiresAt: number; } export async function verifyAssertion(req: Request, res: Response, session: StoredChallengeSession) { const { response } = req.body; const rawOrigin = req.headers.origin; if (!rawOrigin || !AUTHORIZED_RELATED_ORIGINS.has(rawOrigin)) { return res.status(403).json({ error: 'Origin not permitted by Related Origin manifest' }); } // Cryptographically bind session state: origin at verification MUST match origin at challenge creation if (session.boundOrigin !== rawOrigin) { return res.status(401).json({ error: 'Origin mismatch between challenge issuance and assertion' }); } const verification = await verifyAuthenticationResponse({ response, expectedChallenge: session.challenge, expectedOrigin: Array.from(AUTHORIZED_RELATED_ORIGINS), expectedRPID: CANONICAL_RP_ID, authenticator: { credentialPublicKey: Buffer.from([]), credentialID: 'cred-123', counter: 0, }, requireUserVerification: true, }); if (!verification.verified) { return res.status(401).json({ error: 'Passkey verification failed' }); } return res.json({ status: 'authenticated', verifiedOrigin: verification.authenticationInfo.origin }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Related Origin Cryptographic Manifest & Cross-Subdomain Relay Guardrail

WebAuthn Related Origin Cryptographic Manifest & Cross-Subdomain Relay Guardrail defines an industrial-grade behavioral standard for security engineering. Precludes subdomain passkey credential relay and token interception across distributed micro-frontends by strictly enforcing W3C WebAuthn Related Origin Requests specifications. Requires deterministic server-side cryptographic validation of clientDataJSON origin against an authoritative, statically verified related-origin manifest, rejecting ambient origin reflection or wildcard rpId relaxation. 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: Dynamic RP Origin Reflection or Ambient Subdomain rpId Relaxation Without Strict Related-Origin Manifest Validation 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	Dynamic RP Origin Reflection or Ambient Subdomain rpId Relaxation Without Strict Related-Origin Manifest Validation	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 validate clientDataJSON.origin against an explicit, immutably configured set of authorized related origins derived from the canonical .well-known/webauthn manifest.

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.