Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Permitting Synced Passkeys (BE=1) or Unverified Attestation for High-Risk Transaction Boundaries) 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.

Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement

--- description: Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement - Enforces non-exportable, hardware-attested platform credentials (Secure Enclave, TPM, StrongBox) for high-risk transactional boundaries. Rejects multi-device synced passkeys by cryptographically validating WebAuthn authenticator data Backup Eligibility (BE) and Backup State (BS) flags alongside cryptographic root-of-trust hardware attestation. globs: src/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/services/auth/**/*.{ts,tsx}, src/api/step-up/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-hardware-bound-stepup-attestation" --- # Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Passkeys (BE=1) or Unverified Attestation for High-Risk Transaction Boundaries ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Device-Bound Hardware Attestation Step-Up Protocol. You must guarantee that high-risk transaction boundaries reject synced passkeys and accept only credentials bound cryptographically to physical hardware (Secure Enclave, TPM 2.0, Android StrongBox). Ensure rigorous verification of authenticator data flags (BE=0, BS=0, UV=1), direct attestation certificates, and transaction-bound challenges. ## Strict Guidelines - Engineers MUST ALWAYS inspect AuthenticatorData bit flags during assertion: Backup Eligibility (bit 3 / BE) MUST be 0 and Backup State (bit 4 / BS) MUST be 0 for device-bound credentials. - Engineers MUST ALWAYS mandate 'userVerification: required' on both registration and step-up assertion; verify that User Verified (bit 2 / UV) is 1 in authenticator data. - Engineers MUST NOT allow multi-device synced passkeys (e.g., iCloud Keychain, Google Password Manager) to satisfy step-up authorization challenges for critical operations. - Services MUST bind the challenge for high-risk step-up assertions to the cryptographic hash of the transaction parameters (e.g., SHA-256(amount + recipient + timestamp + nonce)) to prevent prompt-injection and replay attacks. - Registration of step-up credentials MUST require 'attestation: direct' and validate the x5c certificate chain against trusted Root CAs (Apple WebAuthn Root, Google Android Hardware Attestation CA, FIDO Alliance MDS). - Components NEVER store or trust user assertions without verifying signCount anomalies or credential binding to the enrolled hardware public key stored in the persistent database. ## Bad vs Good Implementations ### Verifying Device-Bound Hardware Assertion vs. Synced Passkeys for Step-Up #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The insecure code accepts any valid WebAuthn assertion without checking the authenticatorData flags. Synced passkeys (such as iCloud Keychain or Google Password Manager) can be synced across untrusted devices or exported if the underlying ecosystem account is compromised. Additionally, the challenge is not cryptographically bound to the transaction context, allowing assertion replays or bait-and-switch payload tampering. ```typescript import { createHash } from 'crypto'; interface StepUpRequest { credentialId: string; clientDataJSON: string; authenticatorData: string; signature: string; } // VULNERABLE: Accepts any valid WebAuthn assertion including multi-device synced passkeys. // Fails to inspect authData flags (BE/BS), does not verify hardware binding, and challenge is not bound to transaction. export async function verifyStepUpAssertion( userId: string, request: StepUpRequest, transactionId: string ): Promise<boolean> { const clientData = JSON.parse(Buffer.from(request.clientDataJSON, 'base64url').toString('utf8')); if (clientData.type !== 'webauthn.get') { throw new Error('Invalid assertion type'); } // Flaw: Accepts generic session challenge; not cryptographically bound to transaction details const isChallengeValid = clientData.challenge.length > 0; if (!isChallengeValid) { throw new Error('Missing challenge'); } // Flaw: Ignores authenticatorData flags (allows synced passkeys where BE=1) // Flaw: Does not check if the credential was registered with verified hardware attestation return true; } ``` #### Production Standard (Correct) > **Standard**: The secure implementation inspects bit 3 (BE) and bit 4 (BS) in the authenticatorData flags byte to ensure the credential cannot be backed up or synced across devices. It requires bit 2 (UV) for biometric/PIN enforcement, confirms the registered credential had verified hardware attestation, and cryptographically validates that the assertion challenge was bound to the exact transaction payload via SHA-256. ```typescript import { createHash, timingSafeEqual } from 'crypto'; interface StepUpVerificationInput { credentialId: string; clientDataJSON: Buffer; authenticatorData: Buffer; signature: Buffer; transactionPayload: { txId: string; amount: bigint; recipient: string }; expectedNonce: string; userHardwareCredential: { id: string; publicKeyPem: string; isHardwareBound: boolean; attestationType: 'apple-secure-enclave' | 'android-strongbox' | 'tpm'; }; } const AUTH_DATA_FLAGS = { UP: 0x01, // User Present UV: 0x04, // User Verified BE: 0x08, // Backup Eligibility BS: 0x10, // Backup State AT: 0x40, // Attested Credential Data Present } as const; export function verifyHardwareBoundStepUp(input: StepUpVerificationInput): boolean { // 1. Verify credential was enrolled with direct hardware attestation if (!input.userHardwareCredential.isHardwareBound) { throw new SecurityError('Credential does not meet hardware-bound enclave requirements'); } // 2. Parse and validate clientDataJSON const clientData = JSON.parse(input.clientDataJSON.toString('utf8')); if (clientData.type !== 'webauthn.get') { throw new SecurityError('Invalid assertion type for step-up'); } // 3. Cryptographically enforce transaction-bound challenge: SHA-256(txId || amount || recipient || nonce) const txHash = createHash('sha256') .update(`${input.transactionPayload.txId}:${input.transactionPayload.amount}:${input.transactionPayload.recipient}:${input.expectedNonce}`) .digest('base64url'); const challengeBuffer = Buffer.from(clientData.challenge, 'utf8'); const expectedChallengeBuffer = Buffer.from(txHash, 'utf8'); if (challengeBuffer.length !== expectedChallengeBuffer.length || !timingSafeEqual(challengeBuffer, expectedChallengeBuffer)) { throw new SecurityError('Transaction binding mismatch: Challenge does not match transaction digest'); } // 4. Inspect Authenticator Data Flags // Flag byte is located at offset 32 (after 32-byte rpIdHash) if (input.authenticatorData.length < 37) { throw new SecurityError('Malformed authenticatorData structure'); } const flags = input.authenticatorData[32]; const isUserVerified = (flags & AUTH_DATA_FLAGS.UV) !== 0; const isBackupEligible = (flags & AUTH_DATA_FLAGS.BE) !== 0; const isBackedUp = (flags & AUTH_DATA_FLAGS.BS) !== 0; // Invariant: Must be hardware-bound on this physical device; synced passkeys strictly rejected if (!isUserVerified) { throw new SecurityError('User verification (biometric / PIN) required for step-up'); } if (isBackupEligible || isBackedUp) { throw new SecurityError('Policy Violation: Multi-device synced credentials rejected for high-risk action'); } return true; } class SecurityError extends Error { constructor(message: string) { super(message); this.name = 'SecurityError'; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement

Hardware-Bound WebAuthn Step-Up Protocol with Secure Enclave Attestation & Backup Flag Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces non-exportable, hardware-attested platform credentials (Secure Enclave, TPM, StrongBox) for high-risk transactional boundaries. Rejects multi-device synced passkeys by cryptographically validating WebAuthn authenticator data Backup Eligibility (BE) and Backup State (BS) flags alongside cryptographic root-of-trust hardware attestation. 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 Synced Passkeys (BE=1) or Unverified Attestation for High-Risk Transaction Boundaries 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 Synced Passkeys (BE=1) or Unverified Attestation for High-Risk Transaction Boundaries	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 during assertion

Engineers MUST ALWAYS inspect AuthenticatorData bit flags during assertion: Backup Eligibility (bit 3 / BE) MUST be 0 and Backup State (bit 4 / BS) MUST be 0 for device-bound credentials.

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.