AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
securitycritical PriorityID: webauthn-device-bound-step-up-attestation

WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard

Enforces strict cryptographic verification of WebAuthn authenticator flags and client extensions to differentiate multi-device synced passkeys from enterprise hardware-bound security keys during privileged step-up operations. Mandates inspection of Backup Eligibility (BE), Backup State (BS), and device-bound public key extensions to prevent synced credential impersonation across security tiers.

Prohibited Anti-Pattern: Treating Synced Passkeys Identically to Enterprise Hardware-Bound Authenticators in High-Assurance Step-Up Workflows

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard - Enforces strict cryptographic verification of WebAuthn authenticator flags and client extensions to differentiate multi-device synced passkeys from enterprise hardware-bound security keys during privileged step-up operations. Mandates inspection of Backup Eligibility (BE), Backup State (BS), and device-bound public key extensions to prevent synced credential impersonation across security tiers.
globs: src/auth/**/*.{ts,js,tsx}, src/server/auth/**/*.{ts,js}, src/api/auth/**/*.{ts,js}, server/src/security/**/*.{ts,js}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/webauthn-device-bound-step-up-attestation"
---

# WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Treating Synced Passkeys Identically to Enterprise Hardware-Bound Authenticators in High-Assurance Step-Up Workflows

## System Constraints
You are a Principal Security Architect enforcing the WebAuthn Synced-Passkey Device-Bound Step-Up Attestation Standard. You must mandate that all step-up authentication endpoints and high-assurance credential evaluations explicitly parse raw authenticatorData flags (specifically Backup Eligibility 'BE' bit 3, and Backup State 'BS' bit 4) or verify the 'devicePubKey' client extension. Never allow multi-device synced credentials to satisfy zero-trust or privileged step-up policies without explicit device binding verification.

## Strict Guidelines
- Services MUST inspect WebAuthn authenticatorData bit flags: Backup Eligibility (BE, bit 3) and Backup State (BS, bit 4) during step-up assertion verification.
- Privileged operations requiring non-exportable hardware binding MUST reject credentials where `flags.backupEligible === true` unless a valid cryptographic `devicePubKey` extension attestation binds the signature to an enrolled physical hardware token.
- Authentication handlers MUST NOT assume successful signature verification and User Verification (UV flag) alone satisfy Tier-3 or step-up assurance levels.
- Registration policies for enterprise step-up authenticators MUST enforce `authenticatorAttachment: 'cross-platform'` (or platform TPM) with `attestation: 'direct'` or `'enterprise'` and validate the AAGUID against an approved FIDO Metadata Service (MDS) hardware catalog.
- Cryptographic verifiers MUST validate signature counters against replay attacks, ensuring hardware counters monotonically increment while accounting for passkey providers that freeze counter values to zero (`flags.backupEligible === true`).

## Bad vs Good Implementations
### Verifying Device-Bound vs Synced Passkeys in Step-Up Operations

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: The handler relies solely on User Verification (UV) and signature correctness. It ignores the authenticator flags (BE and BS) and extension data, allowing any synced credential (e.g., synced to personal iPhones or laptops via iCloud/Google Password Manager) to execute privileged enterprise operations requiring hardware isolation.
```typescript
import { verifyAuthenticationResponse } from '@simplewebauthn/server';
import type { AuthenticationResponseJSON } from '@simplewebauthn/types';
import type { Request, Response } from 'express';

export async function verifyPrivilegedStepUp(req: Request, res: Response) {
  const { response, expectedChallenge, userCredential } = req.body;

  // VULNERABLE: Only verifies signature and UV flag; treats iCloud/Google synced passkeys identically
  // to physical hardware security keys (e.g., YubiKey FIPS), bypassing device-bound boundary.
  const verification = await verifyAuthenticationResponse({
    response: response as AuthenticationResponseJSON,
    expectedChallenge,
    expectedOrigin: 'https://admin.enterprise.com',
    expectedRPID: 'enterprise.com',
    authenticator: userCredential,
    requireUserVerification: true,
  });

  if (!verification.verified) {
    return res.status(401).json({ error: 'Authentication failed' });
  }

  // Elevation granted to a multi-device synced passkey synced across unauthorized endpoints
  await grantPrivilegedAccess(req.session.userId);
  return res.json({ success: true });
}
```

#### Production Standard (Correct)
> **Standard**: The fixed implementation evaluates the `backupEligible` and `backupState` flags from the authenticatorData. It enforces that privileged step-up access is only granted to genuine device-bound credentials or authenticators presenting a validated `devicePubKey` extension, completely neutralizing credential-sync exfiltration risks.
```typescript
import { verifyAuthenticationResponse } from '@simplewebauthn/server';
import type { AuthenticationResponseJSON } from '@simplewebauthn/types';
import type { Request, Response } from 'express';

export class InsufficientAssuranceLevelError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'InsufficientAssuranceLevelError';
  }
}

export async function verifyPrivilegedStepUp(req: Request, res: Response) {
  const { response, expectedChallenge, userCredential } = req.body;

  const verification = await verifyAuthenticationResponse({
    response: response as AuthenticationResponseJSON,
    expectedChallenge,
    expectedOrigin: 'https://admin.enterprise.com',
    expectedRPID: 'enterprise.com',
    authenticator: userCredential,
    requireUserVerification: true,
  });

  if (!verification.verified || !verification.authenticationInfo) {
    return res.status(401).json({ error: 'Authentication failed' });
  }

  const { flags, authenticatorExtensionResults } = verification.authenticationInfo;

  // Enforce hardware-bound invariant: credential cannot be synced or backup eligible
  // unless bound by a validated devicePubKey client extension.
  const isDeviceBoundHardware =
    !flags.backupEligible && !flags.backupState;

  const hasValidDevicePubKeyExtension =
    Boolean(authenticatorExtensionResults?.devicePubKey);

  if (!isDeviceBoundHardware && !hasValidDevicePubKeyExtension) {
    throw new InsufficientAssuranceLevelError(
      'Privileged step-up requires a hardware-bound authenticator (YubiKey/Enterprise TPM). Synced passkeys are rejected.'
    );
  }

  // Verify monotonic counter strictly for hardware authenticators
  if (isDeviceBoundHardware && verification.authenticationInfo.newCounter <= userCredential.counter) {
    return res.status(400).json({ error: 'Authenticator counter replay detected' });
  }

  await grantPrivilegedAccess(req.session.userId);
  return res.json({ success: true, assurance: 'AAL3-DeviceBound' });
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Fetch MCP Server
Enables querying FIDO Alliance Metadata Service (MDS3) endpoints to validate authenticator AAGUIDs and certification levels.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

StepSecurity Secure Repo Skill
Continuous scanning and validation of WebAuthn and cryptographic dependencies for protocol vulnerabilities.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard

WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic verification of WebAuthn authenticator flags and client extensions to differentiate multi-device synced passkeys from enterprise hardware-bound security keys during privileged step-up operations. Mandates inspection of Backup Eligibility (BE), Backup State (BS), and device-bound public key extensions to prevent synced credential impersonation across security 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: Treating Synced Passkeys Identically to Enterprise Hardware-Bound Authenticators in High-Assurance Step-Up Workflows 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftTreating Synced Passkeys Identically to Enterprise Hardware-Bound Authenticators in High-Assurance Step-Up WorkflowsCritical
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 InconsistencyAI 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:

1

Services MUST inspect WebAuthn authenticatorData bit flags

Services MUST inspect WebAuthn authenticatorData bit flags: Backup Eligibility (BE, bit 3) and Backup State (BS, bit 4) during step-up 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Privileged operations requiring non-exportable hardware binding MUST reject credentials where `flags.backupEligible === true` unless a valid cryptographic `devicePubKey` extension attestation binds the signature to an enrolled physical hardware token.

Privileged operations requiring non-exportable hardware binding MUST reject credentials where `flags.backupEligible === true` unless a valid cryptographic `devicePubKey` extension attestation binds the signature to an enrolled physical hardware token.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Authentication handlers MUST NOT assume successful signature verification and User Verification (UV flag) alone satisfy Tier-3 or step-up assurance levels.

Authentication handlers MUST NOT assume successful signature verification and User Verification (UV flag) alone satisfy Tier-3 or step-up assurance levels.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Registration policies for enterprise step-up authenticators MUST enforce `authenticatorAttachment

Registration policies for enterprise step-up authenticators MUST enforce `authenticatorAttachment: 'cross-platform'` (or platform TPM) with `attestation: 'direct'` or `'enterprise'` and validate the AAGUID against an approved FIDO Metadata Service (MDS) hardware catalog.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Cryptographic verifiers MUST validate signature counters against replay attacks, ensuring hardware counters monotonically increment while accounting for passkey providers that freeze counter values to zero (`flags.backupEligible === true`).

Cryptographic verifiers MUST validate signature counters against replay attacks, ensuring hardware counters monotonically increment while accounting for passkey providers that freeze counter values to zero (`flags.backupEligible === 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is WebAuthn Device-Bound Step-Up Attestation & Synced-Passkey Differentiation Standard critical for AI coding assistants?

Enforces strict cryptographic verification of WebAuthn authenticator flags and client extensions to differentiate multi-device synced passkeys from enterprise hardware-bound security keys during privileged step-up operations. Mandates inspection of Backup Eligibility (BE), Backup State (BS), and device-bound public key extensions to prevent synced credential impersonation across security tiers. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Treating Synced Passkeys Identically to Enterprise Hardware-Bound Authenticators in High-Assurance Step-Up Workflows) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related SECURITY Rules

View all rules →
security
105

OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service.

security
81

WebAuthn Conditional UI Mediation, Nonce Atomicity, and Assertion Cryptographic Verification

Enforces zero-trust cryptographic validation for FIDO2/WebAuthn Passkey authentication with Conditional UI autofill. Requires atomic single-use challenge consumption to eliminate replay attacks, strict RP ID hash and origin binding, authenticatorData flag verification (User Presence and User Verification), and monotonic signature counter enforcement to detect authenticator cloning.

security
111

Enforce Sigstore Keyless OIDC Attestation and Admission Controller Verification

Enforces immutable supply-chain security using Sigstore Cosign keyless signing via ephemeral OIDC tokens issued by Fulcio and verified against the Rekor transparency log. Container workloads must be signed and attested at build time by digest, and admission controllers (such as Kyverno or Sigstore Policy Controller) must strictly validate the OIDC issuer and subject identity before allowing image execution.

1 Rule in Stack

WebAuthn