Passkey Hardware-Bound Registration Attestation Verification Standard

--- description: Passkey Hardware-Bound Registration Attestation Verification Standard - Enforces strict validation of WebAuthn attestation statements against certified hardware roots of trust during passkey registration. Guarantees that credentials originating in high-assurance environments are bound to verified physical authenticators (e.g., FIDO2 Level 2+ / CC EAL6+) by cryptographically verifying x5c certificate chains, AAGUID metadata, and authenticator flags, rejecting software-emulated or synced consumer passkeys. globs: src/auth/**/*.{ts,js}, src/services/passkey/**/*.{ts,js}, src/security/**/*.{ts,js}, src/api/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-attestation-hardware-binding-standard" --- # Passkey Hardware-Bound Registration Attestation Verification Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting 'none' attestation or unverified AAGUIDs in high-assurance workflows, allowing software-emulated or exportable credentials. ## System Constraints You are a Principal Security Architect enforcing the Passkey Device-Bound Registration Attestation Verifier Standard. Mandate that all passkey registration routines intended for enterprise, privileged, or high-assurance workflows cryptographically verify attestation statements (packed, tpm, android-key, apple) against FIDO Alliance Metadata Service (MDS3) or known enterprise PKI trust roots. You must strictly reject attestation format 'none', verify that credential backup state (BE/BS flags) enforces non-exportable hardware constraints, validate clientDataJSON hashes, and ensure zero trust in client-reported AAGUIDs without certificate-backed attestation signature verification. ## Strict Guidelines - Engineers MUST ALWAYS demand 'direct' attestation conveyance in PublicKeyCredentialCreationOptions for high-assurance registrations. - Engineers MUST NOT accept attestationStatement format 'none' or missing attestation certificates in privileged authentication scopes. - Code SHOULD validate the Authenticator Data flags, asserting that the User Present (UP) and User Verified (UV) bits are set, while Backup Eligibility (BE) and Backup State (BS) flags are evaluated according to organizational policy (e.g., BE=0 and BS=0 for non-synced enterprise keys). - Services MUST verify the x5c certificate chain up to a trusted FIDO MDS3 root or explicit enterprise CA, checking revocation status and validity periods. - Services MUST cryptographically match the AAGUID embedded within the authData against the certified subject alternative name (SAN) OID (1.3.6.1.4.1.45724.1.1.4) in the attestation leaf certificate. - Components NEVER store or trust clientDataJSON or authData before verifying that the SHA-256 hash of clientDataJSON matches the clientDataHash within the signature verification computation. ## Bad vs Good Implementations ### Registration Attestation Verification with Hardware Trust Anchor #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts soft tokens and synced consumer passkeys without validating hardware attestation. Missing user verification enforcement, allows 'none' attestation, ignores AAGUID verification against FIDO Metadata Service (MDS), and ignores Backup Eligibility (BE) / Backup State (BS) flags. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; export async function verifyUserPasskey(req: any, expectedChallenge: string) { // VULNERABLE: Accepts any attestation, defaults to 'none', does not verify AAGUID or backup flags const verification = await verifyRegistrationResponse({ response: req.body, expectedChallenge, expectedOrigin: 'https://app.example.com', expectedRPID: 'app.example.com', requireUserVerification: false }); if (verification.verified && verification.registrationInfo) { const { credentialPublicKey, credentialID } = verification.registrationInfo; return saveCredential(credentialID, credentialPublicKey); } throw new Error('Registration failed'); } ``` #### Production Standard (Correct) > **Standard**: Rejects 'none' attestation, checks Backup Eligibility (BE) and Backup State (BS) flags to prevent multi-device passkey syncing, validates authenticator hardware against an AAGUID allowlist, and cryptographically evaluates the leaf-to-root certificate chain against certified FIDO MDS trust anchors. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import { fetchMdsMetadata, verifyAttestationCertificateChain } from './fidoMdsService'; const ENTERPRISE_ALLOWED_AAGUIDS = new Set([ 'ee882879-721c-4916-be26-2a7e4e17d667', // YubiKey 5 Series NFC '2fc0579f-8113-47ea-b116-e82db93540b6' // Feitian BioPass FIDO2 ]); export async function verifyHardwareBoundPasskey(req: any, expectedChallenge: string) { const verification = await verifyRegistrationResponse({ response: req.body, expectedChallenge, expectedOrigin: 'https://app.example.com', expectedRPID: 'app.example.com', requireUserVerification: true }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('WebAuthn cryptographic verification failed'); } const { attestationObject, authenticatorExtensionResults } = req.body.response; const { aaguid, flags, credentialPublicKey, credentialID, attestationStatementFormat } = verification.registrationInfo; // 1. Disallow 'none' attestation; require certified formats if (attestationStatementFormat === 'none') { throw new SecurityError('Software-emulated or attestation-free credentials rejected'); } // 2. Enforce hardware binding: Prevent passkey multi-device syncing if (flags.backupEligible || flags.backupState) { throw new SecurityError('Multi-device synced credentials violate enterprise hardware boundary'); } // 3. Verify AAGUID matches authorized hardware authenticators if (!ENTERPRISE_ALLOWED_AAGUIDS.has(aaguid)) { throw new SecurityError(`Unauthorized authenticator AAGUID: ${aaguid}`); } // 4. Validate x5c chain against FIDO MDS3 roots const mdsEntry = await fetchMdsMetadata(aaguid); const isCertValid = await verifyAttestationCertificateChain( verification.registrationInfo.attestationStatement, mdsEntry.rootCertificates ); if (!isCertValid) { throw new SecurityError('Failed root of trust attestation validation via FIDO MDS'); } return saveHardwareCredential(credentialID, credentialPublicKey, aaguid); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey Hardware-Bound Registration Attestation Verification Standard

Passkey Hardware-Bound Registration Attestation Verification Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict validation of WebAuthn attestation statements against certified hardware roots of trust during passkey registration. Guarantees that credentials originating in high-assurance environments are bound to verified physical authenticators (e.g., FIDO2 Level 2+ / CC EAL6+) by cryptographically verifying x5c certificate chains, AAGUID metadata, and authenticator flags, rejecting software-emulated or synced consumer passkeys. 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: Accepting 'none' attestation or unverified AAGUIDs in high-assurance workflows, allowing software-emulated or exportable credentials. 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	Accepting 'none' attestation or unverified AAGUIDs in high-assurance workflows, allowing software-emulated or exportable credentials.	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 demand 'direct' attestation conveyance in PublicKeyCredentialCreationOptions for high-assurance registrations.

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.