WebAuthn Conditional Mediation & Passkey Signal API Revocation Guardrail

--- description: WebAuthn Conditional Mediation & Passkey Signal API Revocation Guardrail - Enforces strict synchronization between WebAuthn Conditional Mediation (autofill) UI lifecycles and the Passkey Signal API (PublicKeyCredential.signal*). Mandates that client autofill abort controllers are deterministically aborted and re-instantiated upon credential invalidation or hardware revocation events, preventing compromised credentials from persisting in active browser autofill caches. globs: src/**/*.{ts,tsx}, packages/auth/**/*.{ts,tsx}, apps/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-conditional-mediation-passkey-signal-revocation-invariant" --- # WebAuthn Conditional Mediation & Passkey Signal API Revocation Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Stale Conditional Mediation Requests Exposing Revoked Passkeys in Client Autofill Prompts ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Conditional Mediation & Passkey Signal API Revocation Invariant. Mandate that every WebAuthn conditional mediation session binds to a scoped AbortController managed alongside credential revocation state. Ensure that any backend revocation signal dispatches a `PublicKeyCredential.signalAllAcceptedCredentials` or `PublicKeyCredential.signalCurrentUserDetails` call to update the client authenticator, immediately followed by aborting in-flight conditional `navigator.credentials.get()` requests before re-initializing autofill with fresh server challenge state. ## Strict Guidelines - Engineers MUST ALWAYS manage conditional mediation `navigator.credentials.get()` calls with an explicit `AbortController` instance stored in an accessible lifecycle scope. - Engineers MUST NOT allow active conditional mediation requests to persist across administrative credential revocations, multi-factor resets, or global sign-out events. - Services MUST invoke `PublicKeyCredential.signalAllAcceptedCredentials({ rpId, userId, allAcceptedCredentialIds })` immediately when an IdP or server-side passkey revocation event is received. - Code SHOULD verify `PublicKeyCredential.isConditionalMediationAvailable()` and capability checks for `signalAllAcceptedCredentials` before invoking Passkey Signal APIs. - Components NEVER suppress or ignore `AbortError` (DOMException code 20) when cancelling conditional mediation for intentional revocation or refresh cycles. ## Bad vs Good Implementations ### Passkey Revocation and Conditional Autofill Lifecycle Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The conditional mediation request is detached from an AbortController. When a credential is administratively revoked via the API, the local browser passkey state is not signaled via the Passkey Signal API, leaving compromised credentials selectable in the OS/browser autofill overlay. ```typescript class PasskeyAuthManager { async initAutofill(): Promise<void> { // ANTI-PATTERN: In-flight conditional get has no abort signal binding // and is never revoked when credentials are invalidated. const credential = await navigator.credentials.get({ mediation: 'conditional', publicKey: { challenge: new Uint8Array([1, 2, 3, 4]), rpId: window.location.hostname } }); await this.verify(credential); } async revokePasskey(credentialId: string): Promise<void> { await fetch(`/api/passkeys/${credentialId}/revoke`, { method: 'POST' }); // Fails to notify the client platform authenticator via Signal API, // leaving revoked passkeys cached in the active browser autofill dialog. } private async verify(cred: Credential | null): Promise<void> {} } ``` #### Production Standard (Correct) > **Standard**: Correctly pairs conditional mediation with an explicit AbortController and synchronizes revoked credentials with the authenticator via PublicKeyCredential.signalAllAcceptedCredentials. It gracefully catches AbortError and clears stale autofill sessions. ```typescript interface PasskeySignalAPI extends PublicKeyCredentialConstructor { signalAllAcceptedCredentials?(options: { rpId: string; userId: ArrayBuffer; allAcceptedCredentialIds: ArrayBuffer[]; }): Promise<void>; } class PasskeyAuthManager { private autofillAbortController: AbortController | null = null; private readonly rpId = window.location.hostname; async startConditionalMediation(challenge: Uint8Array): Promise<void> { if (!window.PublicKeyCredential || !await PublicKeyCredential.isConditionalMediationAvailable?.()) { return; } this.abortConditionalMediation(); this.autofillAbortController = new AbortController(); try { const credential = await navigator.credentials.get({ mediation: 'conditional', signal: this.autofillAbortController.signal, publicKey: { challenge, rpId: this.rpId, userVerification: 'preferred' } }); if (credential) { await this.verifyAssertion(credential as PublicKeyCredential); } } catch (error: unknown) { if (error instanceof DOMException && error.name === 'AbortError') { return; // Expected lifecycle tear-down } throw error; } } async handleRevocationEvent(userIdBuffer: ArrayBuffer, activeCredentialIds: ArrayBuffer[]): Promise<void> { // 1. Immediately abort active conditional mediation in UI this.abortConditionalMediation(); // 2. Synchronize authenticator state via Passkey Signal API (Level 3) const PkCred = window.PublicKeyCredential as unknown as PasskeySignalAPI; if (typeof PkCred.signalAllAcceptedCredentials === 'function') { await PkCred.signalAllAcceptedCredentials({ rpId: this.rpId, userId: userIdBuffer, allAcceptedCredentialIds: activeCredentialIds }); } } abortConditionalMediation(): void { if (this.autofillAbortController && !this.autofillAbortController.signal.aborted) { this.autofillAbortController.abort('Passkey state invalidated'); this.autofillAbortController = null; } } private async verifyAssertion(cred: PublicKeyCredential): Promise<void> {} } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Conditional Mediation & Passkey Signal API Revocation Guardrail

WebAuthn Conditional Mediation & Passkey Signal API Revocation Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict synchronization between WebAuthn Conditional Mediation (autofill) UI lifecycles and the Passkey Signal API (PublicKeyCredential.signal*). Mandates that client autofill abort controllers are deterministically aborted and re-instantiated upon credential invalidation or hardware revocation events, preventing compromised credentials from persisting in active browser autofill caches. 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: Stale Conditional Mediation Requests Exposing Revoked Passkeys in Client Autofill Prompts 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	Stale Conditional Mediation Requests Exposing Revoked Passkeys in Client Autofill Prompts	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 manage conditional mediation `navigator.credentials.get()` calls with an explicit `AbortController` instance stored in an accessible lifecycle scope.

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.