Passkey AAL3 Hardware Enclave Attestation & Non-Exportability Invariant

--- description: Passkey AAL3 Hardware Enclave Attestation & Non-Exportability Invariant - Enforces strict NIST SP 800-63B Authenticator Assurance Level 3 (AAL3) compliance in WebAuthn registration ceremonies. Rejects unmanaged multi-device synced passkeys by requiring direct cryptographic attestation verification, FIDO Metadata Service (MDS3) root-of-trust anchoring, FIDO Level 2+ certification validation, and strict enforcement of single-device non-exportability flags. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/fido/**/*.{ts,tsx}, server/**/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-aal3-hardware-attestation-invariant" --- # Passkey AAL3 Hardware Enclave Attestation & Non-Exportability Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Unattested WebAuthn Credentials or Permitting Synced Multi-Device Passkeys in AAL3 Zero-Trust Perimeters ## System Constraints You are a Principal Security Architect and Cryptographic Rules Author enforcing NIST SP 800-63B AAL3 WebAuthn registration invariants. You must mandate that every WebAuthn credential registration challenge requires direct attestation, parses raw authenticator data flags to reject multi-device backup eligibility (flags.be === false), validates x5c attestation certificate trust chains against the official FIDO Alliance Metadata Service (MDS3), and verifies that the authenticating hardware enclave holds a certified FIDO Level 2 or higher evaluation. ## Strict Guidelines - Registration options MUST ALWAYS specify `attestation: 'direct'` (or `'enterprise'` where contracted) and `userVerification: 'required'`; engineers MUST NOT configure `attestation: 'none'` in AAL3 flows. - Verification routines MUST explicitly parse the authenticator data bit flags and REJECT any credential where the Backup Eligibility (`BE`) flag is set to true (`authData.flags.backupEligible === true`), eliminating unmanaged synced passkeys (e.g., iCloud Keychain, Google Password Manager). - Cryptographic verification MUST resolve the Authenticator Attestation GUID (`AAGUID`) against an authoritative local cache of the FIDO Alliance Metadata Service (MDS3) and assert that `certificationStatuses` includes valid active FIDO certification of at least `FIDO_CERTIFIED_L2` or higher. - The x509 attestation certificate chain (`x5c`) MUST be cryptographically validated from leaf to root against root certificates published in the FIDO MDS3 blob, enforcing revocation checks (CRL) and intermediate validity. - Components NEVER persist credentials or issue authenticated sessions if the attestation type is `self` (self-signed) or `none`, unless explicitly operating in an isolated, sandboxed local development test fixture. ## Bad vs Good Implementations ### AAL3 WebAuthn Registration Attestation & Flag Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code fails AAL3 requirements: it does not enforce direct hardware attestation, ignores authenticator backup eligibility flags (allowing non-hardware-bound, syncable cloud credentials), and fails to inspect the AAGUID against the FIDO MDS3 to confirm Level 2+ certification. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerPasskeyAAL3( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { // VULNERABLE: Does not require or verify direct attestation, // accepts multi-device synced passkeys, and ignores FIDO MDS validation. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'auth.corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Storing credential without asserting hardware boundary or backup flags return verification.registrationInfo; } ``` #### Production Standard (Correct) > **Standard**: Extracts and parses byte 32 flags from the WebAuthn authenticatorData to verify non-backup-eligibility, and validates the AAGUID against FIDO Metadata Service (MDS3) to guarantee that the credential resides in a certified FIDO Level 2+ hardware enclave. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { fidoMdsClient } from '../crypto/fido-mds'; export async function registerPasskeyAAL3( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'auth.corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('AAL3_REGISTRATION_REJECTED', 'Cryptographic verification failed'); } const { attestationObject, aaguid, credentialBackedUp } = verification.registrationInfo; // NIST AAL3 Invariant 1: Reject synced passkeys (multi-device credentials) // authenticatorData flags: bit 3 (BE - Backup Eligibility), bit 4 (BS - Backup State) const authDataBuffer = Buffer.from(attestationObject); const flags = authDataBuffer[32]; // Byte 32 contains the flags bitfield const backupEligible = (flags & 0x08) !== 0; if (backupEligible || credentialBackedUp) { throw new SecurityError('AAL3_VIOLATION_SYNCED_KEY', 'Multi-device passkeys strictly prohibited for AAL3 perimeters'); } // NIST AAL3 Invariant 2: Hardware Enclave Validation via FIDO MDS3 const metadata = await fidoMdsClient.getEntryByAaguid(aaguid); if (!metadata) { throw new SecurityError('AAL3_UNKNOWN_AUTHENTICATOR', `AAGUID ${aaguid} is not recognized in FIDO MDS3`); } const isFidoL2Plus = metadata.metadataStatement?.certificationStatuses?.some( (status) => ['FIDO_CERTIFIED_L2', 'FIDO_CERTIFIED_L2plus', 'FIDO_CERTIFIED_L3'].includes(status.status) ); if (!isFidoL2Plus) { throw new SecurityError('AAL3_INSUFFICIENT_SECURITY_LEVEL', 'Authenticator does not meet FIDO L2+ hardware certification'); } return verification.registrationInfo; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey AAL3 Hardware Enclave Attestation & Non-Exportability Invariant

Passkey AAL3 Hardware Enclave Attestation & Non-Exportability Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict NIST SP 800-63B Authenticator Assurance Level 3 (AAL3) compliance in WebAuthn registration ceremonies. Rejects unmanaged multi-device synced passkeys by requiring direct cryptographic attestation verification, FIDO Metadata Service (MDS3) root-of-trust anchoring, FIDO Level 2+ certification validation, and strict enforcement of single-device non-exportability 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 Unattested WebAuthn Credentials or Permitting Synced Multi-Device Passkeys in AAL3 Zero-Trust 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 Unattested WebAuthn Credentials or Permitting Synced Multi-Device Passkeys in AAL3 Zero-Trust 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:

Registration options MUST ALWAYS specify `attestation

Registration options MUST ALWAYS specify `attestation: 'direct'` (or `'enterprise'` where contracted) and `userVerification: 'required'`; engineers MUST NOT configure `attestation: 'none'` in AAL3 flows.

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.