FIDO2 / WebAuthn Synced Passkey Attestation and Step-Up Invariant

--- description: FIDO2 / WebAuthn Synced Passkey Attestation and Step-Up Invariant - Enforces cryptographic discrimination between multi-device synced credentials (passkeys) and hardware-bound tokens (e.g., YubiKeys) during registration and authentication. Systems must inspect authenticator data flags (BE/BS) and attestation statement formats to enforce hardware-bound credentials for step-up authentication during high-risk transactional workflows. globs: src/auth/**/*.ts, src/security/**/*.ts, src/api/auth/**/*.ts, src/services/webauthn/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-synced-vs-hardware-attestation-invariant" --- # FIDO2 / WebAuthn Synced Passkey Attestation and Step-Up Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Conflating Synced Passkeys with Dedicated Hardware Keys During High-Risk Step-Up Actions ## System Constraints You are a Principal Security Architect enforcing strict FIDO2/WebAuthn credential policy invariants. Multi-device synced credentials (cloud-synced passkeys) must NEVER satisfy step-up authorization constraints for privileged or high-risk transactional operations. You must verify authenticator data bit flags (Backup Eligibility 'BE' and Backup State 'BS') and validate Enterprise/Direct Attestation statements (e.g., packed, fido-u2f, apple) against FIDO Metadata Service (MDS) roots to distinguish hardware-bound authenticators from multi-device passkeys. ## Strict Guidelines - Engineers MUST ALWAYS verify bit 3 (Backup Eligibility / BE) and bit 4 (Backup State / BS) of the authenticator data flags during credential registration and authentication. - Engineers MUST NOT allow credentials with BE=1 and BS=1 to satisfy authorization scopes reserved for dedicated hardware security keys (e.g., FIPS 140-2 Level 3 or CC EAL6+ authenticators). - Registration handlers MUST persist the credential's AAGUID, attestation type ('direct' or 'enterprise'), and hardware-bound state to the database for authorization policy enforcement. - Step-up authentication endpoints MUST explicitly enforce `authenticatorAttachment: 'cross-platform'` and validate against an allowlist of verified hardware-bound AAGUIDs via the FIDO Metadata Service (MDS3). - Services MUST reject 'none' attestation formats when enrolling credentials destined for high-risk transactional signing scopes. ## Bad vs Good Implementations ### Distinguishing Hardware-Bound Authenticators from Synced Passkeys #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code treats all registered credentials equally. Cloud-synced passkeys (which have backup eligibility set and can sync across devices) are permitted to sign high-risk transactions, violating the step-up hardware invariant. ```typescript import { VerifiedRegistrationResponse } from '@simplewebauthn/server'; // ANTI-PATTERN: Blindly trusting any WebAuthn registration as hardware-bound export async function registerCredential(userId: string, verification: VerifiedRegistrationResponse) { const { registrationInfo } = verification; if (!registrationInfo) throw new Error('Verification failed'); await db.credentials.create({ data: { userId, credentialId: registrationInfo.credentialID, publicKey: registrationInfo.credentialPublicKey, counter: registrationInfo.counter, // Blindly assigns high-privilege access to any passkey (e.g. iCloud Keychain, Google Password Manager) canExecuteHighRiskTransfer: true, }, }); } ``` #### Production Standard (Correct) > **Standard**: Extracts and evaluates the Authenticator Data flag bits (BE and BS) along with AAGUID validation to mathematically verify that the credential cannot be synchronized across consumer cloud accounts before granting elevated transactional privileges. ```typescript import { VerifiedRegistrationResponse } from '@simplewebauthn/server'; export async function registerCredential(userId: string, verification: VerifiedRegistrationResponse) { const { registrationInfo } = verification; if (!registrationInfo) throw new Error('Registration verification failed'); const { credentialID, credentialPublicKey, counter, aaguid, attestationObject } = registrationInfo; // Extract flags byte (offset 32 in authData) // Bit 3 (0x08): Backup Eligibility (BE), Bit 4 (0x10): Backup State (BS) const flags = attestationObject.get('authData')[32]; const isBackupEligible = (flags & 0x08) !== 0; const isBackedUp = (flags & 0x10) !== 0; // Hardware-bound keys (YubiKey, Titan) are not backup eligible and have non-zero AAGUIDs const isHardwareBound = !isBackupEligible && !isBackedUp && aaguid !== '00000000-0000-0000-0000-000000000000'; await db.credentials.create({ data: { userId, credentialId: credentialID, publicKey: credentialPublicKey, counter, aaguid, isHardwareBound, // Synced passkeys are restricted from high-risk wire transfers or privileged administrative actions canExecuteHighRiskTransfer: isHardwareBound, }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 / WebAuthn Synced Passkey Attestation and Step-Up Invariant

FIDO2 / WebAuthn Synced Passkey Attestation and Step-Up Invariant defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic discrimination between multi-device synced credentials (passkeys) and hardware-bound tokens (e.g., YubiKeys) during registration and authentication. Systems must inspect authenticator data flags (BE/BS) and attestation statement formats to enforce hardware-bound credentials for step-up authentication during high-risk transactional workflows. 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: Conflating Synced Passkeys with Dedicated Hardware Keys During High-Risk Step-Up Actions 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	Conflating Synced Passkeys with Dedicated Hardware Keys During High-Risk Step-Up Actions	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 bit 3 (Backup Eligibility / BE) and bit 4 (Backup State / BS) of the authenticator data flags during credential registration and authentication.

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.