WebAuthn Enterprise Attestation and Non-Exportable Passkey Boundary Standard

--- description: WebAuthn Enterprise Attestation and Non-Exportable Passkey Boundary Standard - Enforces cryptographic attestation validation and authenticator flag verification to restrict high-assurance perimeters to non-exportable, hardware-backed credentials. Prevents multi-device cloud-synced passkeys from masquerading as dedicated enterprise hardware authenticators by validating AAGUID allowlists, attestation certificate chains against FIDO MDS, and backing state flags. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/identity/**/*.{ts,tsx}, src/server/api/routers/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-enterprise-attestation-sync-boundary-standard" --- # WebAuthn Enterprise Attestation and Non-Exportable Passkey Boundary Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting unverified attestation ('none') or multi-device syncable credentials (BE/BS flags active) within high-assurance authentication perimeters. ## System Constraints You are a Principal Security Architect and Cryptographic Engineer enforcing strict WebAuthn Enterprise Attestation and Hardware Boundary standards. Mandate cryptographic verification of authenticator attestation (X.509 chains via FIDO MDS3), strict parsing of authenticator data flags (Backup Eligibility 'BE' and Backup State 'BS'), and explicit AAGUID allowlisting. Never permit multi-device syncable passkeys or unverified attestation types ('none') to satisfy high-assurance credential enrollment. ## Strict Guidelines - Engineers MUST ALWAYS demand 'enterprise' or 'direct' attestation during registration options generation for high-assurance enterprise realms (`attestation: 'enterprise'`). - Engineers MUST ALWAYS reject registration credentials when attestation format is 'none' or self-attestation ('packed' without a valid trusted X.509 leaf certificate). - Engineers MUST ALWAYS verify the authenticator data flags: if credential policy forbids syncable keys, reject credentials where Backup Eligibility (BE, bit 3) is true or Backup State (BS, bit 4) is true. - Engineers MUST ALWAYS validate the credential AAGUID against an explicit enterprise-approved hardware allowlist sourced from FIDO Alliance Metadata Service (MDS3) or custom enterprise roots. - Engineers MUST NOT trust client-reported authenticator transport or platform hints without cryptographically verifying the attestation statement (`attStmt`) and public key certificate chain (`x5c`). - Services MUST verify attestation certificate revocation via CRL/OCSP endpoints defined in the FIDO MDS3 payload before accepting credential public keys. - Services MUST enforce `userVerification: 'required'` across both credential creation and authentication ceremony options to guarantee biometric or PIN hardware-level gating. - Components NEVER store or trust raw client-side navigator.credentials assertions without passing through server-side cryptographic verification routines. ## Bad vs Good Implementations ### Enforcing Hardware Attestation and Sync Flag Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration accepts any passkey, including consumer multi-device cloud-synced passkeys. It ignores attestation format ('none' accepted by default), fails to inspect Backup Eligibility (BE) and Backup State (BS) flags, and does not validate the AAGUID against a hardware allowlist (e.g., FIPS YubiKeys or corporate MDM-managed Secure Enclaves). ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerEnterprisePasskey( user: { id: string; email: string }, response: RegistrationResponseJSON, expectedChallenge: string ) { // VULNERABLE: Permits 'none' attestation, allows syncable passkeys (iCloud/Google Password Mgr), // and does not validate the AAGUID or hardware boundary flags against enterprise policy. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://admin.corp.internal', expectedRPID: 'corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } return saveCredentialToDatabase({ userId: user.id, credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, }); } ``` #### Production Standard (Correct) > **Standard**: Explicitly verifies the hardware boundary by asserting `backupEligibility` and `backupState` are false (`singleDevice`), rejecting unverified/none attestation formats, and confirming that the cryptographic AAGUID matches the enterprise-approved hardware token repository. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; // Enterprise-managed approved hardware AAGUIDs (e.g., YubiKey 5 Series FIPS, Nitrokey 3A Enterprise) const APPROVED_ENTERPRISE_AAGUIDS = new Set<string>([ 'ee882879-721c-4913-9775-3dfcce97072a', 'fa2b99dc-9e39-4257-8f92-4a30d23c4118', ]); export async function registerEnterprisePasskey( user: { id: string; email: string }, response: RegistrationResponseJSON, expectedChallenge: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://admin.corp.internal', expectedRPID: 'corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('Credential validation failed: invalid signature or challenge mismatch.'); } const { attestationObject, credentialDeviceType, aaguid } = verification.registrationInfo; const { flags } = attestationObject.authData; // Security Boundary 1: Reject cloud-synced / multi-device passkeys // Flags bit 3 = Backup Eligibility (BE), bit 4 = Backup State (BS) if (flags.backupEligibility || flags.backupState || credentialDeviceType !== 'singleDevice') { throw new SecurityError('Policy Violation: Multi-device syncable passkeys are prohibited in enterprise perimeter.'); } // Security Boundary 2: Reject unverified or self-signed attestation statements const attFmt = attestationObject.fmt; if (attFmt === 'none' || attFmt === 'packed' && !attestationObject.attStmt.x5c) { throw new SecurityError(`Policy Violation: Inadmissible attestation format '${attFmt}'. Verified X.509 chain required.`); } // Security Boundary 3: Validate AAGUID against corporate hardware inventory if (!aaguid || !APPROVED_ENTERPRISE_AAGUIDS.has(aaguid)) { throw new SecurityError(`Policy Violation: Hardware AAGUID '${aaguid}' is not authorized for high-assurance access.`); } return saveCredentialToDatabase({ userId: user.id, credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, aaguid, attestationFormat: attFmt, isBackupEligible: flags.backupEligibility, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Enterprise Attestation and Non-Exportable Passkey Boundary Standard

WebAuthn Enterprise Attestation and Non-Exportable Passkey Boundary Standard defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic attestation validation and authenticator flag verification to restrict high-assurance perimeters to non-exportable, hardware-backed credentials. Prevents multi-device cloud-synced passkeys from masquerading as dedicated enterprise hardware authenticators by validating AAGUID allowlists, attestation certificate chains against FIDO MDS, and backing state flags. 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 unverified attestation ('none') or multi-device syncable credentials (BE/BS flags active) within high-assurance authentication perimeters. 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 unverified attestation ('none') or multi-device syncable credentials (BE/BS flags active) within high-assurance authentication perimeters.	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 demand 'enterprise' or 'direct' attestation during registration options generation for high-assurance enterprise realms (`attestation

Engineers MUST ALWAYS demand 'enterprise' or 'direct' attestation during registration options generation for high-assurance enterprise realms (`attestation: 'enterprise'`).

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.