WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Lax Subdomain Origin Validation and Ignored Backup Flags Permitting Multi-Device Credential Hijacking) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant

--- description: WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant - Mandates strict origin validation, RP ID isolation, and authenticator data flag verification (BE=0, BS=0) during WebAuthn Level 3 registration and authentication ceremonies. Enforces FIDO Metadata Service (MDS3) attestation certificate path validation to block subdomain impersonation and non-device-bound credential synchronization in high-assurance environments. globs: src/**/auth/**/*.{ts,js}, src/**/webauthn/**/*.{ts,js}, src/**/security/**/*.{ts,js}, packages/**/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-device-bound-origin-attestation" --- # WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Lax Subdomain Origin Validation and Ignored Backup Flags Permitting Multi-Device Credential Hijacking ## System Constraints You are a Principal Security Architect and Cryptographer enforcing WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Verification. Mandate zero-trust validation of incoming WebAuthn assertion and attestation payloads. Ensure server-side validation strictly enforces expected fully-qualified origins, computes exact SHA-256 digests over expected RP IDs, asserts non-exportable hardware flags (Backup Eligibility bit = 0, Backup State bit = 0), and validates attestation trust anchors against FIDO MDS3 roots. ## Strict Guidelines - Engineers MUST ALWAYS validate 'clientDataJSON.origin' against an exact, fully qualified origin allowlist (scheme, host, port) and NEVER perform suffix matching or lax top-level wildcard matching. - Engineers MUST verify that 'rpIdHash' in the decoded authenticator data precisely matches the SHA-256 hash of the exact authorized Relying Party ID configured for the specific high-assurance boundary. - Services MUST verify the Authenticator Data flags: User Present (UP, bit 0) and User Verified (UV, bit 2) MUST be set to 1 for high-assurance flows. - Services enforcing L3 Device-Bound Passkeys MUST ensure Backup Eligibility (BE, bit 3) is 0 and Backup State (BS, bit 4) is 0 to reject multi-device synced passkeys (e.g., iCloud Keychain, Google Password Manager). - Registration ceremonies MUST enforce direct or enterprise attestation statement validation by verifying the x5c certificate chain against an authoritative FIDO Alliance Metadata Service (MDS3) root store, rejecting 'none' attestation. - Components NEVER store or reuse the registration or authentication challenge; challenges MUST be cryptographically random (minimum 32 bytes), single-use, bounded by a strict TTL (<= 120 seconds), and stored server-side in secure session or cache storage. ## Bad vs Good Implementations ### WebAuthn Registration Response Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Suffix matching on origin enables session hijacking from compromised peer subdomains. The verification ignores authenticator flags (BE and BS), accepting synced passkeys instead of enforcing hardware device-bound credentials, and omits attestation certificate chain validation against FIDO MDS3. ```typescript import { Request, Response } from 'express'; export async function verifyRegistration(req: Request, res: Response) { const { id, rawId, response } = req.body; const clientData = JSON.parse(Buffer.from(response.clientDataJSON, 'base64url').toString('utf8')); // VULNERABLE: Suffix matching permits malicious subdomains (e.g., attacker.subdomain.example.com) if (!clientData.origin.endsWith('example.com')) { return res.status(400).send('Invalid origin'); } // VULNERABLE: Accepts 'none' attestation and fails to verify hardware-backed device-bound flags (BE/BS) const clientChallenge = clientData.challenge; if (clientChallenge !== req.session.challenge) { return res.status(400).send('Challenge mismatch'); } // Stores credential without verifying AAGUID against MDS3 or checking device-bound status await saveCredential({ userId: req.session.userId, credentialId: id }); return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: Strictly matches the exact origin and RP ID against hard invariants, requires user verification, and parses the authenticator data flags to explicitly reject credentials where backup eligibility (BE) or backup state (BS) is true, guaranteeing hardware-bound L3 credentials. ```typescript import { createHash, timingSafeEqual } from 'crypto'; import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { getExpectedOrigin, getExpectedRPID, getMdsRootCertificates } from './auth-config'; export async function verifyL3DeviceBoundRegistration( body: RegistrationResponseJSON, expectedChallenge: string, userId: string ) { const expectedOrigin = getExpectedOrigin(); // e.g., 'https://vault.secure.example.com' const expectedRPID = getExpectedRPID(); // e.g., 'vault.secure.example.com' const verification = await verifyRegistrationResponse({ response: body, expectedChallenge, expectedOrigin, expectedRPID, requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityException('WebAuthn L3 registration verification failed'); } const { authenticatorData, credential } = verification.registrationInfo; const flags = authenticatorData.flags; // Bit 0: UP, Bit 2: UV, Bit 3: BE, Bit 4: BS const isUserPresent = flags.userPresent; const isUserVerified = flags.userVerified; const isBackupEligible = flags.backupEligibility; const isBackedUp = flags.backupState; // Enforce L3 Invariant: Must be hardware device-bound; reject multi-device synced credentials if (!isUserPresent || !isUserVerified || isBackupEligible || isBackedUp) { throw new SecurityException('Policy Violation: Credential is not a device-bound hardware authenticator (BE=0, BS=0 required)'); } return { credentialId: credential.id, publicKey: Buffer.from(credential.publicKey).toString('base64url'), counter: credential.counter, aaguid: credential.aaguid, deviceBound: true, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant

WebAuthn L3 Device-Bound Passkey Origin Binding & Attestation Invariant defines an industrial-grade behavioral standard for security engineering. Mandates strict origin validation, RP ID isolation, and authenticator data flag verification (BE=0, BS=0) during WebAuthn Level 3 registration and authentication ceremonies. Enforces FIDO Metadata Service (MDS3) attestation certificate path validation to block subdomain impersonation and non-device-bound credential synchronization in high-assurance environments. 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 Subdomain Origin Validation and Ignored Backup Flags Permitting Multi-Device Credential Hijacking 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 Subdomain Origin Validation and Ignored Backup Flags Permitting Multi-Device Credential Hijacking	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 exact, fully qualified origin allowlist (scheme, host, port) and NEVER perform suffix matching or lax top-level wildcard 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.