WebAuthn Device-Bound Attestation Key Quarantine and Step-Up Protocol

--- description: WebAuthn Device-Bound Attestation Key Quarantine and Step-Up Protocol - Enforces strict cryptographic isolation and quarantine for passkeys configured for high-assurance, device-bound execution contexts when detected with synced backup flags or missing hardware-backed attestation. Requires immediate privilege downgrade and mandatory step-up re-registration before granting access to hardware-isolated enterprise boundary tiers. globs: src/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/services/webauthn/**/*.{ts,tsx}, src/api/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-quarantine-protocol" --- # WebAuthn Device-Bound Attestation Key Quarantine and Step-Up Protocol > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting Multi-Device Synced Passkeys for Hardware-Bound Isolation Tiers Without Quarantine Checks ## System Constraints You are a Principal Security Architect and Cryptographic Protocol Engineer enforcing WebAuthn Device-Bound Attestation Key Quarantine Protocols. Your core objective is to prevent session hijacking and unauthorized lateral movement arising from synced cloud passkeys (Apple iCloud Keychain, Google Password Manager) operating within device-bound trust tiers. You must ensure all registration and authentication assertions verify Authenticator Data flags (`BE` - Backup Eligibility, `BS` - Backup State), examine AAGUID identity against FIDO Alliance Metadata Service (MDS3), and trigger deterministic credential quarantine when synchronization anomalies or lack of direct hardware attestation are detected. ## Strict Guidelines - Engineers MUST ALWAYS inspect AuthenticatorData bit flags 3 (Backup Eligibility - BE) and 4 (Backup State - BS) during both registration and assertion verification. - Engineers MUST NOT grant device-bound enterprise privileges to any credential exhibiting `backupEligibility: true` or `backupState: true` unless explicitly classified as a roaming/synced credential tier. - Services MUST place any credential attempting device-bound tier operations with missing or invalid direct attestation into a `QUARANTINED` status and strip high-assurance scopes. - Code SHOULD verify AAGUID values and root-of-trust certificate chains against the FIDO Alliance Metadata Service (MDS3) blob during attestation validation. - Components NEVER persist or activate high-assurance session tokens without verifying that the credential's attestation format is direct/enterprise (e.g., `packed`, `tpm`, `android-key`) and backed by an immutable hardware-bound key. ## Bad vs Good Implementations ### Enforcing WebAuthn Attestation Quarantine on Synced Credentials #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation ignores WebAuthn AuthenticatorData flags (bits 3 and 4 for BE and BS). Synced cloud passkeys (e.g., synced across iCloud Keychain) are blindly accepted into the 'device-bound-enterprise' tier without checking whether the credential is hardware-bound or synced, completely undermining the device isolation invariant. ```typescript import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; interface SessionContext { userId: string; accessTier: 'standard' | 'device-bound-enterprise'; } export async function verifyAssertion( response: AuthenticationResponseJSON, session: SessionContext ): Promise<{ success: boolean }> { // Flaw: Ignores backup flags (BE, BS) and treats all valid signatures identically const isSignatureValid = await dummyVerifySignature(response); if (!isSignatureValid) { throw new Error('Invalid signature'); } // Security Breach: Multi-device cloud-synced passkeys inherit hardware-bound tier if (session.accessTier === 'device-bound-enterprise') { return { success: true }; } return { success: true }; } async function dummyVerifySignature(_res: AuthenticationResponseJSON): Promise<boolean> { return true; } ``` #### Production Standard (Correct) > **Standard**: The code extracts the Authenticator Data flags and strictly validates bit 3 (Backup Eligibility) and bit 4 (Backup State). If a credential attempting to access a device-bound enterprise boundary is backed up or eligible for cloud sync, it is immediately downgraded and marked as QUARANTINED, preventing credential cloning attacks and maintaining zero-trust hardware isolation. ```typescript import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; export enum CredentialQuarantineState { VERIFIED_DEVICE_BOUND = 'VERIFIED_DEVICE_BOUND', SYNCED_PASSKEY_RESTRICTED = 'SYNCED_PASSKEY_RESTRICTED', QUARANTINED = 'QUARANTINED', } export interface AuthenticatorFlags { userPresent: boolean; userVerified: boolean; backupEligibility: boolean; backupState: boolean; } export interface CredentialMetadata { id: string; aaguid: string; isDeviceBound: boolean; quarantineState: CredentialQuarantineState; } export function parseAuthenticatorFlags(authDataBuffer: Buffer): AuthenticatorFlags { // Authenticator data layout: 32 bytes rpIdHash + 1 byte flags at offset 32 const flags = authDataBuffer[32]; return { userPresent: (flags & 0x01) !== 0, userVerified: (flags & 0x04) !== 0, backupEligibility: (flags & 0x08) !== 0, backupState: (flags & 0x10) !== 0, }; } export async function evaluateDeviceBoundAssertion( authDataBuffer: Buffer, registeredCredential: CredentialMetadata, targetTier: 'standard' | 'device-bound-enterprise' ): Promise<{ authorizedTier: 'standard'; quarantineState: CredentialQuarantineState }> { const flags = parseAuthenticatorFlags(authDataBuffer); // Invariant: Device-bound credentials MUST NOT be backup-eligible or currently backed up const isSyncedPasskey = flags.backupEligibility || flags.backupState; if (targetTier === 'device-bound-enterprise') { if (isSyncedPasskey || !registeredCredential.isDeviceBound) { // Transition anomaly: Credential claiming hardware boundary is synced across cloud return { authorizedTier: 'standard', quarantineState: CredentialQuarantineState.QUARANTINED, }; } if (!flags.userVerified) { throw new SecurityError('User Verification (UV) mandatory for device-bound access.'); } } return { authorizedTier: 'standard', quarantineState: isSyncedPasskey ? CredentialQuarantineState.SYNCED_PASSKEY_RESTRICTED : CredentialQuarantineState.VERIFIED_DEVICE_BOUND, }; } class SecurityError extends Error { constructor(message: string) { super(message); this.name = 'SecurityError'; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Device-Bound Attestation Key Quarantine and Step-Up Protocol

WebAuthn Device-Bound Attestation Key Quarantine and Step-Up Protocol defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic isolation and quarantine for passkeys configured for high-assurance, device-bound execution contexts when detected with synced backup flags or missing hardware-backed attestation. Requires immediate privilege downgrade and mandatory step-up re-registration before granting access to hardware-isolated enterprise boundary tiers. 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: Trusting Multi-Device Synced Passkeys for Hardware-Bound Isolation Tiers Without Quarantine Checks 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	Trusting Multi-Device Synced Passkeys for Hardware-Bound Isolation Tiers Without Quarantine Checks	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 inspect AuthenticatorData bit flags 3 (Backup Eligibility - BE) and 4 (Backup State - BS) during both registration and assertion verification.

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.