Passkey W3C Signal API Credential Invalidation Standard

--- description: Passkey W3C Signal API Credential Invalidation Standard - Mandates client- and server-side compliance with the W3C WebAuthn Signal API specification (`signalUnknownCredential` and `signalAllAcceptedCredentials`) upon passkey deletion, lifecycle revocation, or unrecognized assertion encounters. Prevents ghost passkeys and replay authentication attempts on de-provisioned hardware across distributed authenticator sync fabrics such as Apple iCloud Keychain, Google Password Manager, and third-party credential managers. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-w3c-signal-api-invalidation-standard" --- # Passkey W3C Signal API Credential Invalidation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Silent Server-Side Credential Revocation Without Authenticator Sync Fabric Signal Propagation ## System Constraints You are a Principal Security Architect enforcing the W3C WebAuthn Signal API specification for passkey lifecycles. Passkey deletion or de-provisioning MUST NOT occur purely in server databases. Whenever a credential is revoked, deleted by a user, or recognized as invalid/stale during assertion verification, systems MUST coordinate and emit cryptographic revocation signals via PublicKeyCredential.signalUnknownCredential or PublicKeyCredential.signalAllAcceptedCredentials to synchronize state across federated authenticator fabrics. ## Strict Guidelines - Services MUST ALWAYS issue Signal API instructions to the client when a credential is de-registered or revoked in backend datastores. - Engineers MUST NOT silently drop unknown passkey assertions on the backend; if an unknown or revoked credential attempts authentication, the server MUST return an explicit status (e.g., HTTP 410 Gone / 404 Credential Revoked) requiring the client to execute `PublicKeyCredential.signalUnknownCredential`. - Client authentication adapters MUST check for feature support (`'signalUnknownCredential' in PublicKeyCredential`) and dispatch `signalUnknownCredential` using the base64url-encoded credential ID and valid RP ID. - When a user triggers an account reset or global credential purge, the frontend MUST invoke `PublicKeyCredential.signalAllAcceptedCredentials` providing only the active valid credential IDs for the specified user handle (`userId`). - Components NEVER store or process raw credential signals without strictly validating that the Relying Party ID matches `window.location.hostname` or the registered domain boundary to prevent cross-origin signaling attacks. ## Bad vs Good Implementations ### Client-Side Invalidation via W3C WebAuthn Signal API #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When passkeys are deleted on the server or on another device, the authenticator retains the passkey. Failing to invoke PublicKeyCredential.signalUnknownCredential causes the client authenticator sync fabric (e.g., iCloud Keychain, Google Password Manager) to retain orphan passkeys, causing persistent replay attempts and broken UX. ```typescript import { startAuthentication } from '@simplewebauthn/browser'; export async function authenticatePasskey(): Promise<void> { try { const optionsRes = await fetch('/api/auth/passkey-options'); const options = await optionsRes.json(); const authResult = await startAuthentication(options); const verifyRes = await fetch('/api/auth/verify-passkey', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(authResult), }); if (!verifyRes.ok) { // Anti-pattern: Silently aborting or showing a generic error without // signaling the client authenticator sync fabric about the dead credential. throw new Error('Authentication failed'); } } catch (error) { console.error('Passkey failed to authenticate', error); throw error; } } ``` #### Production Standard (Correct) > **Standard**: Adheres to the W3C Signal API standard. When the server encounters a credential that is no longer valid, it instructs the client with specific error parameters. The client then checks for `signalUnknownCredential` support and safely signals the authenticator sync fabric to purge the credential, preventing phantom credentials and repeated replay failures. ```typescript import { startAuthentication } from '@simplewebauthn/browser'; interface VerifyPasskeyErrorResponse { error: string; code: 'CREDENTIAL_REVOKED' | 'CREDENTIAL_UNKNOWN'; credentialId: string; rpId: string; } export async function authenticatePasskey(): Promise<void> { const optionsRes = await fetch('/api/auth/passkey-options'); const options = await optionsRes.json(); const authResult = await startAuthentication(options); const verifyRes = await fetch('/api/auth/verify-passkey', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(authResult), }); if (!verifyRes.ok) { const errorData: VerifyPasskeyErrorResponse = await verifyRes.json().catch(() => ({})); if ( (errorData.code === 'CREDENTIAL_REVOKED' || errorData.code === 'CREDENTIAL_UNKNOWN') && 'signalUnknownCredential' in PublicKeyCredential && typeof (PublicKeyCredential as unknown as { signalUnknownCredential: Function }).signalUnknownCredential === 'function' ) { // W3C Signal API: Inform the authenticator fabric to purge the orphaned passkey await (PublicKeyCredential as unknown as { signalUnknownCredential: (params: { rpId: string; credentialId: string }) => Promise<void>; }).signalUnknownCredential({ rpId: errorData.rpId, credentialId: errorData.credentialId, }); } throw new Error(`Authentication rejected: ${errorData.error || 'Unknown failure'}`); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey W3C Signal API Credential Invalidation Standard

Passkey W3C Signal API Credential Invalidation Standard defines an industrial-grade behavioral standard for security engineering. Mandates client- and server-side compliance with the W3C WebAuthn Signal API specification (`signalUnknownCredential` and `signalAllAcceptedCredentials`) upon passkey deletion, lifecycle revocation, or unrecognized assertion encounters. Prevents ghost passkeys and replay authentication attempts on de-provisioned hardware across distributed authenticator sync fabrics such as Apple iCloud Keychain, Google Password Manager, and third-party credential managers. 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: Silent Server-Side Credential Revocation Without Authenticator Sync Fabric Signal Propagation 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	Silent Server-Side Credential Revocation Without Authenticator Sync Fabric Signal Propagation	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:

Services MUST ALWAYS issue Signal API instructions to the client when a credential is de-registered or revoked in backend datastores.

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.