Hardware-Bound WebAuthn Step-Up Invariant for Privileged Operations

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting Synced Multi-Device Credentials for Privileged In-Session Transactions Without Hardware-Bound Attestation) 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 Invariant for Privileged Operations

--- description: Hardware-Bound WebAuthn Step-Up Invariant for Privileged Operations - Enforces dual-attested, non-exportable hardware-bound assertion claims during step-up authentication for high-privilege operations. Mitigates cloud keychain credential-cloning vectors by strictly verifying AuthenticatorData flags (UV=1, UP=1, BE=0, BS=0) or enterprise-attested device public keys (Device PubKey extension). globs: src/auth/**/*.ts, src/security/**/*.ts, src/server/auth/**/*.ts, src/services/stepup/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-hardware-bound-step-up-standard" --- # Hardware-Bound WebAuthn Step-Up Invariant for Privileged Operations > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Synced Multi-Device Credentials for Privileged In-Session Transactions Without Hardware-Bound Attestation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Synced-Passkey Hardware-Bound Assertion Step-Up Standard. Multi-device synced credentials (e.g., iCloud Keychain, Google Password Manager) expose high-risk transactions to account-takeover cascades and cross-device session leakage. You must enforce non-exportable, device-bound assertions (BE=0, BS=0, UV=1) or explicit cross-platform hardware authenticators with validated attestation for privileged actions. ## Strict Guidelines - Services MUST inspect WebAuthn `flags.backupEligibility` (BE) and `flags.backupState` (BS) within AuthenticatorData; privileged step-up transactions MUST fail if `backupState === true`. - Engineers MUST require User Verification (`userVerification: 'required'`) on step-up challenges; fallback to simple User Presence (UP) is strictly forbidden for tier-1 mutations. - Privileged endpoints MUST mandate a freshly generated cryptographically random server challenge with a TTL strictly <= 60 seconds, bound to the caller's session ID. - Step-up verification routines MUST NOT reuse the session authentication credential ID if that credential was registered as multi-device eligible (BE=1), unless validated via a bound Device Public Key (`devicePubKey`) extension. - Registration handlers for step-up credentials MUST enforce `authenticatorSelection.authenticatorAttachment = 'cross-platform'` or explicit device-bound attestation (`attestation: 'direct'`) when enrolling hardware keys. ## Bad vs Good Implementations ### Privileged Step-Up WebAuthn Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code fails to inspect authenticator flags. A passkey synchronized across iCloud or Google Keychains can sign this assertion from an unauthorized or shared secondary device, violating device-binding security invariants for tier-1 operations. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function verifyPrivilegedStepUp(session: UserSession, response: any) { // VULNERABLE: Accepts any valid passkey assertion, including synced credentials // from compromised secondary devices in the user's cloud keychain. const verification = await verifyAuthenticationResponse({ response, expectedChallenge: session.currentChallenge, expectedOrigin: process.env.ORIGIN!, expectedRPID: process.env.RP_ID!, authenticator: { credentialPublicKey: session.registeredPublicKey, credentialID: session.registeredCredentialId, counter: session.counter, }, }); if (!verification.verified) { throw new Error('Authentication failed'); } // Does not verify userVerification (UV) or backup status (BE/BS) await executeHighValueTransfer(session.userId); } ``` #### Production Standard (Correct) > **Standard**: The verified assertion strictly checks that `flags.backupState` is false, ensuring the credential cannot be an exported or synced copy, and validates that cryptographic user verification (`flags.userVerified`) was completed within a 60-second challenge window. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function verifyPrivilegedStepUp( session: UserSession, response: any, expectedChallenge: string, challengeCreatedAt: number ): Promise<void> { // Invariant 1: Step-up challenge expiry <= 60 seconds if (Date.now() - challengeCreatedAt > 60_000) { throw new SecurityException('Step-up challenge expired.'); } const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: process.env.ORIGIN!, expectedRPID: process.env.RP_ID!, authenticator: { credentialPublicKey: session.stepUpPublicKey, credentialID: session.stepUpCredentialId, counter: session.stepUpCounter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new SecurityException('Step-up verification failed.'); } const { flags } = verification.authenticationInfo; // Invariant 2: Hardware-bound invariant - Reject synced keys for tier-1 mutations if (flags.backupState) { throw new SecurityException('Compromised invariant: Assertion originated from a synced cloud credential.'); } // Invariant 3: Must be both hardware-locked and actively user-verified (PIN/biometrics) if (!flags.userVerified) { throw new SecurityException('Compromised invariant: User Verification flag missing.'); } await executeHighValueTransfer(session.userId); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Bound WebAuthn Step-Up Invariant for Privileged Operations

Hardware-Bound WebAuthn Step-Up Invariant for Privileged Operations defines an industrial-grade behavioral standard for security engineering. Enforces dual-attested, non-exportable hardware-bound assertion claims during step-up authentication for high-privilege operations. Mitigates cloud keychain credential-cloning vectors by strictly verifying AuthenticatorData flags (UV=1, UP=1, BE=0, BS=0) or enterprise-attested device public keys (Device PubKey extension). 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 Synced Multi-Device Credentials for Privileged In-Session Transactions Without Hardware-Bound 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	Accepting Synced Multi-Device Credentials for Privileged In-Session Transactions Without Hardware-Bound 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:

Services MUST inspect WebAuthn `flags.backupEligibility` (BE) and `flags.backupState` (BS) within AuthenticatorData

Services MUST inspect WebAuthn `flags.backupEligibility` (BE) and `flags.backupState` (BS) within AuthenticatorData; privileged step-up transactions MUST fail if `backupState === true`.

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.