WebAuthn Synced-Credential Epoch Revocation and Distributed Fencing Standard

--- description: WebAuthn Synced-Credential Epoch Revocation and Distributed Fencing Standard - Mandates cryptographic epoch-counter fencing across distributed session stores and authorization layers upon compromise reporting of multi-device synced passkeys. Guarantees that any device revocation or passkey credential cycle atomically increments the security epoch, rendering all pre-existing distributed sessions, refresh tokens, and authentication assertions cryptographically obsolete across all nodes immediately. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,js}, src/services/session/**/*.{ts,js}, src/security/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-synced-passkey-epoch-revocation-fencing" --- # WebAuthn Synced-Credential Epoch Revocation and Distributed Fencing Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Passive Soft-Deletion of Synced Passkeys Without Epoch Fencing Allowing Compromised Stale Sessions to Persist ## System Constraints You are a Principal Software Architect enforcing the WebAuthn Passkey Synced-Credential Epoch Revocation Standard. Multi-device synced credentials (e.g., Apple iCloud Keychain, Google Password Manager) expose all linked endpoints to cross-device compromise. You must mandate atomic monotonic epoch fencing on all passkey mutations and session evaluations. Never allow decoupled database updates that rely on passive TTL expirations or non-linearizable distributed session caches. ## Strict Guidelines - Engineers MUST ALWAYS couple credential revocation or compromise reports with an atomic, monotonic increment of the user's credential_epoch in both the primary datastore and the distributed session fence (e.g., Redis RedisBloom/Hash via Lua script or multi-region CAS). - Engineers MUST NOT rely on passive JWT expiration, eventual-consistency eventual sync, or mere boolean flags (e.g., `is_revoked = true`) without fencing active distributed tokens against the latest epoch barrier. - Services MUST validate that `token.credential_epoch >= current_fenced_epoch` on every non-idempotent operation and session renewal cycle, immediately rejecting and purging tokens below the fence. - Code SHOULD include the cryptographic fence epoch directly within WebAuthn challenge verification contexts and downstream signed assertion validation pipelines. - Components NEVER issue refreshed access tokens if the client's assertion epoch is strictly less than the epoch recorded during the most recent device compromise event. ## Bad vs Good Implementations ### Compromise Handling and Session Validation via Epoch Fencing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Revoking the passkey in the primary database without fencing the active epoch allows active tokens and distributed sessions on other synced devices to continue executing privileged actions until their natural TTL expires. ```typescript import { db } from '../db'; import { redisClient } from '../cache'; // ANTI-PATTERN: Merely marking the passkey record as deleted in Postgres // Stale sessions, access tokens, and distributed cache entries remain valid until TTL expiration. export async function reportCompromisedPasskeyBad( userId: string, passkeyId: string ): Promise<void> { await db.query('UPDATE passkeys SET is_active = false WHERE id = $1 AND user_id = $2', [ passkeyId, userId, ]); } export async function validateSessionBad(sessionToken: string): Promise<boolean> { const session = await redisClient.get(`session:${sessionToken}`); if (!session) return false; // Flaw: Does not check whether the passkey was revoked after session issuance return true; } ``` #### Production Standard (Correct) > **Standard**: Revocation increments a monotonic user-level epoch in an ACID transaction and synchronizes the distributed fence key in Redis. Every session verification checks `sessionEpoch >= activeFenceEpoch`, immediately rendering all credentials and active sessions from compromised synced devices invalid in O(1) time. ```typescript import { db } from '../db'; import { redisCluster } from '../cache'; interface AuthenticatedSessionPayload { userId: string; sessionEpoch: number; passkeyId: string; } // PRODUCTION INVARIANT: Atomic epoch increment across DB and distributed cache with fence validation export async function reportCompromisedPasskeyGood( userId: string, passkeyId: string, reason: string ): Promise<number> { return await db.transaction(async (tx) => { // 1. Atomically increment the security epoch in persistent storage const result = await tx.query( `UPDATE users SET passkey_epoch = passkey_epoch + 1, updated_at = NOW() WHERE id = $1 RETURNING passkey_epoch`, [userId] ); const newEpoch: number = result.rows[0].passkey_epoch; // 2. Mark passkey revoked with explicit audit reason await tx.query( `UPDATE passkeys SET is_revoked = true, revoked_at_epoch = $1, revocation_reason = $2 WHERE id = $3 AND user_id = $4`, [newEpoch, reason, passkeyId, userId] ); // 3. Atomically update the distributed epoch fence (Lua script or linearizable CAS) const fenceScript = ` local current = redis.call('GET', KEYS[1]) if not current or tonumber(ARGV[1]) > tonumber(current) then redis.call('SET', KEYS[1], ARGV[1]) end return redis.call('GET', KEYS[1]) `; await redisCluster.eval(fenceScript, 1, `user:epoch:${userId}`, newEpoch.toString()); return newEpoch; }); } export async function validateSessionGood( session: AuthenticatedSessionPayload ): Promise<boolean> { // Linearizable read of current security epoch fence const rawEpoch = await redisCluster.get(`user:epoch:${session.userId}`); const activeFenceEpoch = rawEpoch ? parseInt(rawEpoch, 10) : 0; // Immediately invalidate stale sessions issued prior to the compromise event if (session.sessionEpoch < activeFenceEpoch) { return false; } return true; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Synced-Credential Epoch Revocation and Distributed Fencing Standard

WebAuthn Synced-Credential Epoch Revocation and Distributed Fencing Standard defines an industrial-grade behavioral standard for security engineering. Mandates cryptographic epoch-counter fencing across distributed session stores and authorization layers upon compromise reporting of multi-device synced passkeys. Guarantees that any device revocation or passkey credential cycle atomically increments the security epoch, rendering all pre-existing distributed sessions, refresh tokens, and authentication assertions cryptographically obsolete across all nodes immediately. 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: Passive Soft-Deletion of Synced Passkeys Without Epoch Fencing Allowing Compromised Stale Sessions to Persist 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	Passive Soft-Deletion of Synced Passkeys Without Epoch Fencing Allowing Compromised Stale Sessions to Persist	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 couple credential revocation or compromise reports with an atomic, monotonic increment of the user's credential_epoch in both the primary datastore and the distributed session fence (e.g., Redis RedisBloom/Hash via Lua script or multi-region CAS).

Engineers MUST ALWAYS couple credential revocation or compromise reports with an atomic, monotonic increment of the user's credential_epoch in both the primary datastore and the distributed session fence (e.g., Redis RedisBloom/Hash via Lua script or multi-region CAS).

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.