Hardware-Attested Device-Bound Passkey Enforcement for Step-Up Authorization

--- description: Hardware-Attested Device-Bound Passkey Enforcement for Step-Up Authorization - Enforces cryptographic isolation between multi-device cloud-synced passkeys and high-risk step-up authorization flows. Mandates verification of WebAuthn Level 3 authenticator data flags (Backup Eligibility and Backup State) and hardware-backed Secure Enclave attestation before authorizing privileged operations such as wire transfers and administrative role escalations. globs: src/auth/**/*.{ts,tsx}, src/services/security/**/*.{ts,tsx}, src/api/v1/transactions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-passkey-escalation-boundary" --- # Hardware-Attested Device-Bound Passkey Enforcement for Step-Up Authorization > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Multi-Device Synced Passkeys to Sign High-Risk Step-Up Actions Without Hardware Boundary Attestation ## System Constraints You are a Principal Security Architect enforcing zero-trust WebAuthn boundaries. You must reject any authorization logic that treats multi-device synced credentials as equivalent to hardware-bound credentials for privileged transactions. Mandate strict inspection of authenticator data flags (BE/BS) and hardware attestation verification. ## Strict Guidelines - Engineers MUST ALWAYS verify authenticator data bit flags (BE = Backup Eligibility, BS = Backup State) during step-up assertion verification, enforcing BE === 0 and BS === 0 for privileged operations. - Engineers MUST NOT allow multi-device synced credentials (e.g., iCloud Keychain or Google Password Manager passkeys) to satisfy step-up authorization for critical or financial transactions. - Code SHOULD inspect the Authenticator Attestation GUID (AAGUID) against an enterprise allowlist or the FIDO Alliance Metadata Service (MDS) to ensure credentials reside in a certified hardware Secure Enclave or TPM. - Services MUST enforce 'userVerification: required' and reject any WebAuthn response where the User Verified (UV) flag (bit 2) is not explicitly set in the authData buffer. - Components NEVER store or trust client-side claims regarding device-bound status; validation MUST occur exclusively on the server against the cryptographically signed authData buffer. ## Bad vs Good Implementations ### WebAuthn Step-Up Authorization Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation verifies only signature validity and replay counters. It fails to inspect the authenticator data flags (BE and BS) or attestations, allowing any multi-device synced passkey synced across untrusted end-user devices to authorize high-risk transactions. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; interface StepUpPayload { response: any; expectedChallenge: string; credentialPublicKey: Uint8Array; counter: number; } export async function verifyStepUpAuthorization(payload: StepUpPayload) { const verification = await verifyAuthenticationResponse({ response: payload.response, expectedChallenge: payload.expectedChallenge, expectedOrigin: 'https://bank.example.com', expectedRPID: 'bank.example.com', credential: { id: payload.response.id, publicKey: payload.credentialPublicKey, counter: payload.counter, }, }); // VULNERABILITY: Blindly trusts the signature without inspecting backup flags // Synced passkeys (iCloud/Google) can sign financial wire transfers if (!verification.verified) { throw new Error('Verification failed'); } return { authorized: true }; } ``` #### Production Standard (Correct) > **Standard**: The implementation enforces the escalation boundary by parsing byte 32 of authData, guaranteeing user verification (UV=1), and rejecting any credential with Backup Eligibility (BE=1) or Backup State (BS=1). It optionally checks the AAGUID against an approved hardware baseline. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; interface StepUpPayload { response: any; expectedChallenge: string; credentialPublicKey: Uint8Array; counter: number; allowedHardwareAaguids: Set<string>; } export async function verifyStepUpAuthorization(payload: StepUpPayload) { const verification = await verifyAuthenticationResponse({ response: payload.response, expectedChallenge: payload.expectedChallenge, expectedOrigin: 'https://bank.example.com', expectedRPID: 'bank.example.com', credential: { id: payload.response.id, publicKey: payload.credentialPublicKey, counter: payload.counter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('Cryptographic signature verification failed'); } const { authData } = verification.authenticationInfo; // Extract flags from the 33rd byte (index 32) of WebAuthn authData buffer const flags = authData[32]; const userVerified = (flags & 0x04) !== 0; // Bit 2: UV const backupEligible = (flags & 0x08) !== 0; // Bit 3: BE const backedUp = (flags & 0x10) !== 0; // Bit 4: BS if (!userVerified) { throw new Error('Biometric/Hardware User Verification required'); } // STRICT INVARIANT: Privileged boundary rejects cloud-synced passkeys if (backupEligible || backedUp) { throw new Error('Cloud-synced passkey prohibited. Hardware-bound credential required.'); } const aaguid = verification.authenticationInfo.aaguid; if (aaguid && !payload.allowedHardwareAaguids.has(aaguid)) { throw new Error('Authenticator hardware model not permitted for step-up escalation.'); } return { authorized: true, credentialId: payload.response.id }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Attested Device-Bound Passkey Enforcement for Step-Up Authorization

Hardware-Attested Device-Bound Passkey Enforcement for Step-Up Authorization defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic isolation between multi-device cloud-synced passkeys and high-risk step-up authorization flows. Mandates verification of WebAuthn Level 3 authenticator data flags (Backup Eligibility and Backup State) and hardware-backed Secure Enclave attestation before authorizing privileged operations such as wire transfers and administrative role escalations. 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: Permitting Multi-Device Synced Passkeys to Sign High-Risk Step-Up Actions Without Hardware Boundary Attestation 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	Permitting Multi-Device Synced Passkeys to Sign High-Risk Step-Up Actions Without Hardware Boundary Attestation	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 verify authenticator data bit flags (BE = Backup Eligibility, BS = Backup State) during step-up assertion verification, enforcing BE === 0 and BS === 0 for privileged operations.

Engineers MUST ALWAYS verify authenticator data bit flags (BE = Backup Eligibility, BS = Backup State) during step-up assertion verification, enforcing BE === 0 and BS === 0 for privileged operations.

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.