Enforce WebAuthn Device-Bound Attestation and Device Public Key (DPK) Extension Verification

--- description: Enforce WebAuthn Device-Bound Attestation and Device Public Key (DPK) Extension Verification - Enterprise security boundaries require hardware-backed, non-exportable passkeys to prevent exfiltration into unmanaged consumer sync fabrics (e.g., iCloud Keychain, Google Password Manager). Registration ceremonies must strictly request and cryptographically verify the Device Public Key (devicePubKey) extension, validate enterprise attestation statements (direct or enterprise), and enforce authenticator attachment flags to fence passkey usage to vetted physical corporate hardware. globs: src/auth/**/*.ts, src/server/auth/**/*.ts, src/identity/**/*.ts, packages/backend/src/webauthn/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-dpk-enterprise-fence" --- # Enforce WebAuthn Device-Bound Attestation and Device Public Key (DPK) Extension Verification > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting client-reported passkey attachment without cryptographic verification of devicePubKey extensions and direct enterprise attestation statements ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Device-Bound Attestation Level (DPK) Enterprise Passkey Fence. You must reject any registration flow that accepts synced multi-device credentials on corporate boundary endpoints. You must mandate that registration options request 'enterprise' attestation and the 'devicePubKey' extension, and the verification pipeline must strictly decode, validate the signature, and persist the devicePubKey alongside the credential public key. ## Strict Guidelines - Engineers MUST ALWAYS configure `attestation: 'enterprise'` or `'direct'` combined with `authenticatorSelection: { authenticatorAttachment: 'platform', userVerification: 'required' }` during enterprise registration option generation. - Engineers MUST ALWAYS request the `devicePubKey` extension (`extensions: { devicePubKey: { attestation: 'direct' } }`) in `PublicKeyCredentialCreationOptions`. - Engineers MUST NOT accept registration responses that omit the `devicePubKey` extension when registering high-privilege corporate credentials. - Verification services MUST parse and cryptographically verify the device public key statement (`dpkNonce`, `dpkSignature`, and raw attestation object) matching the client data JSON challenge. - Services MUST verify the enterprise attestation certificate chain against the organization's approved FIDO Metadata Service (MDS) roots or hardware root of trust (AAGUID allowlist). - Components NEVER treat `authenticatorAttachment === 'platform'` alone as proof of non-exportability, because multi-device hybrid sync keys report platform attachment while remaining synced. ## Bad vs Good Implementations ### Insecure Passkey Registration vs Cryptographically Enforced DPK Enterprise Fence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation does not request or verify the WebAuthn `devicePubKey` extension, accepts default `none` attestation, and relies on user-agent self-reporting. This allows multi-device synced passkeys to register as platform authenticators, violating corporate data fencing policies. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerCorporatePasskey(response: RegistrationResponseJSON, expectedChallenge: string) { // Anti-pattern: Accepts platform attachment without DPK extension or direct attestation. // iCloud Keychain or Google Sync Passkeys will pass this check, permitting unmanaged key exfiltration. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://corp.internal.example.com', expectedRPID: 'corp.internal.example.com', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Storing only credentialID and credentialPublicKey allows synced multi-device keys return { credentialID: verification.registrationInfo.credentialID, credentialPublicKey: verification.registrationInfo.credentialPublicKey, deviceBound: false, }; } ``` #### Production Standard (Correct) > **Standard**: Validates the hardware root of trust via an AAGUID allowlist and verifies the Device Public Key (`devicePubKey`) extension signature. This mathematically guarantees the passkey is bound to the physical Secure Enclave/TPM of the enterprise machine and cannot sync across consumer clouds. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { verifyDevicePublicKeyExtension, isPermittedEnterpriseAaguid } from './crypto/enterprise-attestation'; export async function registerCorporatePasskey(response: RegistrationResponseJSON, expectedChallenge: string) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://corp.internal.example.com', expectedRPID: 'corp.internal.example.com', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('Passkey verification failed'); } const { aaguid, credentialID, credentialPublicKey } = verification.registrationInfo; // 1. Enforce physical enterprise hardware boundary via MDS/AAGUID allowlist if (!isPermittedEnterpriseAaguid(aaguid)) { throw new SecurityError(`AAGUID ${aaguid} is not an authorized enterprise hardware authenticator`); } // 2. Cryptographically verify Device Public Key (DPK) extension to fence against cloud sync const clientExtensionResults = response.clientExtensionResults; if (!clientExtensionResults?.devicePubKey) { throw new SecurityError('devicePubKey extension missing: multi-device passkeys are barred'); } const dpkResult = await verifyDevicePublicKeyExtension({ rawResponse: response, devicePubKeyExtension: clientExtensionResults.devicePubKey, credentialPublicKey, expectedChallenge, }); if (!dpkResult.isValid) { throw new SecurityError('Cryptographic verification of device public key failed'); } return { credentialID, credentialPublicKey, devicePublicKey: dpkResult.devicePublicKey, aaguid, isDeviceBound: true, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce WebAuthn Device-Bound Attestation and Device Public Key (DPK) Extension Verification

Enforce WebAuthn Device-Bound Attestation and Device Public Key (DPK) Extension Verification defines an industrial-grade behavioral standard for security engineering. Enterprise security boundaries require hardware-backed, non-exportable passkeys to prevent exfiltration into unmanaged consumer sync fabrics (e.g., iCloud Keychain, Google Password Manager). Registration ceremonies must strictly request and cryptographically verify the Device Public Key (devicePubKey) extension, validate enterprise attestation statements (direct or enterprise), and enforce authenticator attachment flags to fence passkey usage to vetted physical corporate hardware. 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: Trusting client-reported passkey attachment without cryptographic verification of devicePubKey extensions and direct enterprise attestation statements 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	Trusting client-reported passkey attachment without cryptographic verification of devicePubKey extensions and direct enterprise attestation statements	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 configure `attestation

Engineers MUST ALWAYS configure `attestation: 'enterprise'` or `'direct'` combined with `authenticatorSelection: { authenticatorAttachment: 'platform', userVerification: 'required' }` during enterprise registration option generation.

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.