WebAuthn Conditional Mediation Step-Up Attestation & Cryptographic Origin Invariant

--- description: WebAuthn Conditional Mediation Step-Up Attestation & Cryptographic Origin Invariant - Mandates strict cryptographic validation of clientDataJSON origin, challenge replay defense, authenticator data flags, and hardware-backed attestation during passkey conditional mediation and auto-upgrade step-up flows. Neutralizes Adversary-in-the-Middle (AitM) reverse proxy relay attacks by enforcing canonical Relying Party bindings and hardware security tier verification. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, api/**/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-conditional-mediation-origin-attestation" --- # WebAuthn Conditional Mediation Step-Up Attestation & Cryptographic Origin Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Reflecting client-supplied origins, skipping user verification flags, or omitting hardware attestation during passkey step-up authentication. ## System Constraints You are a Principal Security Architect enforcing zero-trust WebAuthn standards. You must mandate strict cryptographic origin verification, ephemeral single-use challenge consumption, authenticator flag enforcement (UP/UV), and hardware attestation verification (AAGUID validation) in WebAuthn conditional mediation auto-upgrade flows. Reject any implementation that uses wildcard origins, dynamic reflection of Host headers, or soft-fail attestation during step-up challenges. ## Strict Guidelines - Engineers MUST ALWAYS validate clientDataJSON.origin against an immutable, canonical server configuration whitelist (scheme + fully qualified domain + optional port); NEVER reflect the Host header or use substring/regex matching. - Engineers MUST ALWAYS enforce the User Verification (UV) flag (flags.uv === true) and User Presence (UP) flag on authenticator responses for privileged step-up authentication. - Services MUST verify single-use cryptographic challenges by tying them to an active, encrypted server session and deleting them immediately upon receipt to prevent replay attacks. - Engineers MUST verify the Authenticator Attestation GUID (AAGUID) against a trusted FIDO Metadata Service (MDS) catalog when upgrading credentials to hardware-backed security tiers. - Components NEVER fall back to non-attested credentials or multi-device passkeys when a cryptographic step-up policy explicitly demands a device-bound hardware token (e.g., FIPS 140-3 Level 2+ / WebAuthn Enterprise Attestation). ## Bad vs Good Implementations ### WebAuthn Step-Up Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler dynamically derives the expected origin from the client request Host header, completely neutralizing WebAuthn origin-binding protections against AitM proxies. It also fails to atomically consume the challenge and ignores authenticator data flags (UV/UP) and hardware attestation tiers. ```typescript import { Request, Response } from 'express'; export async function verifyStepUpAssertion(req: Request, res: Response) { const { credential, expectedChallenge } = req.body; // VULNERABILITY 1: Reflecting request Host header allows AitM reverse proxies (e.g., Evilginx) // to bypass origin validation when relaying credentials. const clientData = JSON.parse(Buffer.from(credential.response.clientDataJSON, 'base64').toString('utf8')); const hostHeader = req.headers.host; if (!clientData.origin.includes(hostHeader)) { return res.status(401).json({ error: 'Origin mismatch' }); } // VULNERABILITY 2: Challenge is not invalidated immediately, allowing replay. if (clientData.challenge !== expectedChallenge) { return res.status(401).json({ error: 'Invalid challenge' }); } // VULNERABILITY 3: Skips User Verification (UV) and Authenticator Data flag checks, // allowing passkeys operating in non-biometric/non-PIN modes to pass step-up. return res.status(200).json({ status: 'upgraded' }); } ``` #### Production Standard (Correct) > **Standard**: Enforces static canonical origin checking, atomically clears the server-side challenge to prevent replays, verifies the cryptographic signature with user verification (UV) enforced, and validates the AAGUID against an approved hardware catalog. ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { sessionStore } from '../security/sessionStore'; import { CANONICAL_RP_ORIGIN, RP_ID, TRUSTED_HARDWARE_AAGUIDS } from '../config/security'; export async function verifyStepUpAssertion(req: Request, res: Response) { const session = await sessionStore.get(req.sessionID); if (!session || !session.currentChallenge) { return res.status(401).json({ error: 'Invalid session or missing challenge' }); } // Consume challenge immediately to ensure single-use replay defense const expectedChallenge = session.currentChallenge; await sessionStore.update(req.sessionID, { currentChallenge: null }); const { credential } = req.body; const verification = await verifyAuthenticationResponse({ response: credential, expectedChallenge, expectedOrigin: CANONICAL_RP_ORIGIN, // Immutable constant: https://auth.production.domain expectedRPID: RP_ID, authenticator: { credentialID: session.userPasskey.id, credentialPublicKey: session.userPasskey.publicKey, counter: session.userPasskey.counter, }, requireUserVerification: true, // Guarantees flags.uv is set }); if (!verification.verified || !verification.authenticationInfo) { return res.status(401).json({ error: 'Cryptographic verification failed' }); } // Enforce Hardware-Backed Passkey Invariant for Step-Up Tier const { aaguid } = verification.authenticationInfo; if (session.stepUpTier === 'HARDWARE_TOKEN' && !TRUSTED_HARDWARE_AAGUIDS.has(aaguid)) { return res.status(403).json({ error: 'Step-up requires hardware-bound authenticator' }); } await sessionStore.update(req.sessionID, { stepUpVerified: true, passkeyCounter: verification.authenticationInfo.newCounter, }); return res.status(200).json({ status: 'step-up-verified' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Conditional Mediation Step-Up Attestation & Cryptographic Origin Invariant

WebAuthn Conditional Mediation Step-Up Attestation & Cryptographic Origin Invariant defines an industrial-grade behavioral standard for security engineering. Mandates strict cryptographic validation of clientDataJSON origin, challenge replay defense, authenticator data flags, and hardware-backed attestation during passkey conditional mediation and auto-upgrade step-up flows. Neutralizes Adversary-in-the-Middle (AitM) reverse proxy relay attacks by enforcing canonical Relying Party bindings and hardware security tier 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: Reflecting client-supplied origins, skipping user verification flags, or omitting hardware attestation during passkey step-up authentication. 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 client-supplied origins, skipping user verification flags, or omitting hardware attestation during passkey step-up authentication.	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 immutable, canonical server configuration whitelist (scheme + fully qualified domain + optional port)

Engineers MUST ALWAYS validate clientDataJSON.origin against an immutable, canonical server configuration whitelist (scheme + fully qualified domain + optional port); NEVER reflect the Host header or use substring/regex matching.

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.