Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard

--- description: Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard - Mandates cryptographic differentiation between synced multi-device passkeys and device-bound hardware authenticators (e.g., FIDO2/WebAuthn hardware tokens) to gate high-risk operations. Validates Authenticator Attestation Globally Unique Identifiers (AAGUID) against trusted FIDO Metadata Service (MDS) data and verifies authenticator flags (rejecting backup-eligible credentials) during step-up challenges. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, server/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-aaguid-hardware-step-up-standard" --- # Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Authorizing High-Risk Operations via Synced Passkeys or Unverified Client-Supplied AAGUIDs ## System Constraints You are a Principal Security Architect enforcing the Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard. You must prevent privilege escalation via multi-device synced passkeys on tier-1/high-risk administrative endpoints. Always mandate verified AAGUID hardware registry checks, attestation validation via FIDO MDS3, and strict inspection of WebAuthn authenticator flags (specifically rejecting credentials where backupEligible or backupState are active). Never trust unverified client assertions or client-supplied AAGUID strings. ## Strict Guidelines - Engineers MUST ALWAYS verify the credential's AAGUID against an authenticated, cryptographically validated server-side registry (or FIDO Alliance MDS3) rather than trusting client-provided parameters. - Engineers MUST NOT allow credentials with the `backupEligible` (BE) or `backupState` (BS) flags set to authorize high-risk administrative operations. - Services MUST query the server's persisted credential record using the authenticated `credentialId` to inspect the registered AAGUID and hardware binding classification before accepting a step-up assertion. - Services MUST reject the zeroed AAGUID (`00000000-0000-0000-0000-000000000000`) and uncertified virtual/cloud authenticators for privileged step-up ceremonies. - Components NEVER downgrade step-up verification to a standard session check; a fresh WebAuthn assertion with `userVerified: true` and hardware token proof is mandatory. ## Bad vs Good Implementations ### Passkey Step-Up Authorization for Sensitive Admin Operations #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler relies on client-supplied `claimedAaguid` rather than checking persisted server-side credential metadata. It also fails to inspect `backupEligible` and `backupState` flags from the authenticator data, allowing a synced multi-device passkey (which may clone keys across non-FIPS devices) to bypass hardware isolation controls. ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; interface StepUpRequestBody { assertionResponse: any; claimedAaguid: string; // VULNERABILITY: Client asserts hardware identity } export async function handlePrivilegedStepUp(req: Request, res: Response) { const { assertionResponse, claimedAaguid } = req.body as StepUpRequestBody; const expectedChallenge = req.session.currentChallenge; // Flaw 1: Validating only signature without checking authenticator flags const verification = await verifyAuthenticationResponse({ response: assertionResponse, expectedChallenge, expectedOrigin: 'https://admin.example.com', expectedRPID: 'example.com', authenticator: { credentialID: Buffer.from(assertionResponse.id, 'base64url'), credentialPublicKey: req.session.userPublicKey, counter: req.session.userCounter, }, }); if (!verification.verified) { return res.status(401).json({ error: 'Verification failed' }); } // Flaw 2: Blindly trusting client-supplied AAGUID to grant hardware privilege const ALLOWED_HARDWARE_AAGUIDS = ['cbfe0a44-9730-40e1-8e14-53c4c7f87028']; // YubiKey 5 NFC if (ALLOWED_HARDWARE_AAGUIDS.includes(claimedAaguid)) { req.session.hasHardwareElevation = true; return res.json({ status: 'elevated' }); } return res.status(403).json({ error: 'Hardware key required' }); } ``` #### Production Standard (Correct) > **Standard**: The fix validates the WebAuthn signature with mandatory User Verification (`requireUserVerification: true`), inspects authenticator flags directly from the assertion data (`flags.backupEligible === false` and `flags.backupState === false`), and checks the persisted, server-side validated AAGUID against an authoritative hardware registry (FIDO MDS3). ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { getStoredCredential, isHardwareBoundAaguid } from '../services/fidoMdsService'; interface StepUpRequestBody { assertionResponse: any; } export async function handlePrivilegedStepUp(req: Request, res: Response) { const { assertionResponse } = req.body as StepUpRequestBody; const expectedChallenge = req.session.currentChallenge; const userId = req.session.userId; if (!expectedChallenge || !userId) { return res.status(401).json({ error: 'Invalid authentication session state' }); } const credentialId = assertionResponse.id; // 1. Fetch immutable server-side record established and verified at attestation const storedCredential = await getStoredCredential(userId, credentialId); if (!storedCredential) { return res.status(404).json({ error: 'Unregistered credential' }); } // 2. Perform cryptographic verification of the WebAuthn assertion const verification = await verifyAuthenticationResponse({ response: assertionResponse, expectedChallenge, expectedOrigin: 'https://admin.example.com', expectedRPID: 'example.com', authenticator: { credentialID: Buffer.from(storedCredential.id, 'base64url'), credentialPublicKey: storedCredential.publicKey, counter: storedCredential.counter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { return res.status(401).json({ error: 'Cryptographic challenge verification failed' }); } const { userVerified, flags } = verification.authenticationInfo; // 3. Reject credentials that are backup-eligible (synced passkeys) or not user-verified if (!userVerified || flags.backupEligible || flags.backupState) { return res.status(403).json({ error: 'Hardware step-up rejected: synced passkeys or non-UV authenticators not permitted', }); } // 4. Verify persisted AAGUID against certified FIDO MDS hardware-bound registry const isHardwareBound = await isHardwareBoundAaguid(storedCredential.aaguid); if (!isHardwareBound) { return res.status(403).json({ error: 'Authenticator is not a validated hardware security key' }); } // 5. Update counter and issue scoped step-up ticket storedCredential.counter = verification.authenticationInfo.newCounter; req.session.hardwareElevationExpiresAt = Date.now() + 5 * 60 * 1000; return res.json({ status: 'elevated' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard

Passkey AAGUID Cryptographic Hardware Step-Up Escalation Standard defines an industrial-grade behavioral standard for security engineering. Mandates cryptographic differentiation between synced multi-device passkeys and device-bound hardware authenticators (e.g., FIDO2/WebAuthn hardware tokens) to gate high-risk operations. Validates Authenticator Attestation Globally Unique Identifiers (AAGUID) against trusted FIDO Metadata Service (MDS) data and verifies authenticator flags (rejecting backup-eligible credentials) during step-up challenges. 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: Authorizing High-Risk Operations via Synced Passkeys or Unverified Client-Supplied AAGUIDs 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	Authorizing High-Risk Operations via Synced Passkeys or Unverified Client-Supplied AAGUIDs	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 the credential's AAGUID against an authenticated, cryptographically validated server-side registry (or FIDO Alliance MDS3) rather than trusting client-provided parameters.

Engineers MUST ALWAYS verify the credential's AAGUID against an authenticated, cryptographically validated server-side registry (or FIDO Alliance MDS3) rather than trusting client-provided parameters.

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.