@c9up/warden 0.1.17 → 0.1.18

package/dist/strategies/SessionStrategy.js

@@ -7,6 +7,9 @@
  * @implements MISS-7
  */
 import { WardenError } from "../errors.js";
+import { decodeTokenValue, mintRememberMeToken, verifyAndRecycleRememberMeToken, } from "../RememberMeToken.js";
+/** Two years, Adonis' `rememberMeTokensAge` default. */
+const DEFAULT_REMEMBER_AGE_SECONDS = 63_072_000;
 export class SessionStrategy {
     name = "session";
     #config;
@@ -15,6 +18,62 @@ export class SessionStrategy {
         this.#config = config;
         this.#sessionKey = config.sessionKey ?? "auth_user_id";
     }
+    /** The cookie the remember-me token travels in. */
+    get rememberMeCookieName() {
+        return this.#config.rememberMeCookieName ?? "remember_web";
+    }
+    /** Whether "keep me signed in" is wired at all. */
+    get usesRememberMeTokens() {
+        return this.#config.rememberMeTokens !== undefined;
+    }
+    #rememberMeAge() {
+        return this.#config.rememberMeAge ?? DEFAULT_REMEMBER_AGE_SECONDS;
+    }
+    /**
+     * Mint a remember-me token for `user` and return the cookie value the caller
+     * must set. `null` when the feature is not wired.
+     */
+    async issueRememberMeToken(user) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return null;
+        const minted = mintRememberMeToken(user.id, this.#rememberMeAge());
+        await driver.create(minted.stored);
+        return minted.value;
+    }
+    /**
+     * Authenticate from a remember-me cookie, and RECYCLE it: the returned
+     * `cookieValue` must replace the one the browser holds.
+     *
+     * The user is re-read through `findUser`, never trusted from the token — a
+     * token outlives the row it points at, and a deleted or disabled account
+     * must not walk back in through a cookie.
+     */
+    async authenticateViaRememberMeToken(cookieValue) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return null;
+        const recycled = await verifyAndRecycleRememberMeToken(driver, cookieValue, this.#rememberMeAge());
+        if (!recycled)
+            return null;
+        const user = await this.#config.findUser(recycled.userId);
+        if (!user)
+            return null;
+        return { user, cookieValue: recycled.value };
+    }
+    /**
+     * Drop the token behind `cookieValue`. Called on logout so the persistent
+     * credential dies with the session — Adonis deletes the row too.
+     */
+    async revokeRememberMeToken(cookieValue) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return;
+        const decoded = decodeTokenValue(cookieValue);
+        if (!decoded)
+            return;
+        await driver.delete(decoded.identifier);
+    }
     /** Authenticate via email/password — stores user ID in session. */
     async authenticate(_credentials, _context) {
         // Session strategy doesn't handle password verification — that's done
@@ -62,7 +121,22 @@ export class SessionStrategy {
         session.regenerate();
         session.put(this.#sessionKey, user.id);
     }
-    /** Logout — remove user ID from session. */
+    /**
+     * The session entry a test client needs to be `user` (AdonisJS
+     * `authenticateAsClient`).
+     *
+     * Returns the same key `login()` writes, so the request is authenticated by
+     * the guard's own logic rather than by the test knowing where the id lives.
+     */
+    authenticateAsClient(user) {
+        return { session: { [this.#sessionKey]: user.id } };
+    }
+    /**
+     * Logout — remove the user id from the session.
+     *
+     * The remember-me token is revoked separately through
+     * {@link revokeRememberMeToken}, because only the caller holds the cookie.
+     */
     async logout(session) {
         session.forget(this.#sessionKey);
     }

package/dist/strategies/SessionStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"SessionStrategy.js","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA2B3C,MAAM,OAAO,eAAe;IAC3B,IAAI,GAAG,SAAS,CAAC;IACjB,OAAO,CAAwB;IAC/B,WAAW,CAAS;IAEpB,YAAY,MAA6B;QACxC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC;IACxD,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,YAAY,CACjB,YAAiD,EACjD,QAAqC;QAErC,sEAAsE;QACtE,wEAAwE;QACxE,mEAAmE;QACnE,sEAAsE;QACtE,kEAAkE;QAClE,sCAAsC;QACtC,MAAM,IAAI,WAAW,CACpB,WAAW,EACX,6KAA6K,EAC7K;YACC,IAAI,EAAE,yKAAyK;SAC/K,CACD,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,KAAK,CAAC,MAAM,CAAC,MAAc;QAC1B,OAAO;YACN,aAAa,EAAE,KAAK;YACpB,KAAK,EACJ,qEAAqE;SACtE,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,iBAAiB,CACtB,MAAc,EACd,OAAoC;QAEpC,IAAI,CAAC,OAAO,EAAE,OAAO;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;QACvE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ;YAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;QACpE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,IAAiB,EAAE,OAAqB;QACnD,OAAO,CAAC,UAAU,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,MAAM,CAAC,OAAqB;QACjC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;CACD"}
+{"version":3,"file":"SessionStrategy.js","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/warden",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Warden — Authentication & authorization for the Ream framework",
   "license": "MIT",
   "type": "module",
@@ -62,6 +62,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
+    "@c9up/quasar": "^0.1.0",
     "@types/node": "^22.19.15",
     "reflect-metadata": "^0.2.2",
     "typescript": "^6.0.2",
@@ -85,6 +86,7 @@
     "test:rust": "cargo test -p warden-engine",
     "lint": "biome check src/",
     "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:integration": "vitest run -c vitest.integration.config.ts"
   }
 }

package/src/AuthManager.ts

@@ -31,10 +31,34 @@ export interface AuthResult {
 	strategyCrash?: true;
 }
 
+/**
+ * What a test client must send to act as a user (AdonisJS `AuthClientResponse`).
+ *
+ * Each guard answers in its own currency — a header for a token guard, a
+ * session entry for a session guard — so the test harness applies whichever
+ * fields come back instead of knowing how each guard authenticates.
+ */
+export interface AuthClientResponse {
+	/** Headers to set on the request. */
+	headers?: Record<string, string>;
+	/** Session values to seed before the request. */
+	session?: Record<string, unknown>;
+	/** Cookies to send. */
+	cookies?: Record<string, string>;
+}
+
 export interface AuthStrategy {
 	name: string;
 	authenticate(credentials: Record<string, unknown>): Promise<AuthResult>;
 	verify(token: string, context?: Record<string, unknown>): Promise<AuthResult>;
+	/**
+	 * Build what a test client sends to be this user (AdonisJS
+	 * `authenticateAsClient`). Optional: a guard with no test seam simply has
+	 * none, and the harness says so instead of forging one.
+	 */
+	authenticateAsClient?(
+		...args: never[]
+	): Promise<AuthClientResponse> | AuthClientResponse;
 }
 
 /**
@@ -86,6 +110,14 @@ function isTokenIssuer(
 /**
  * Manages authentication strategies and provides guard/permission checks.
  */
+/**
+ * The slice of an event emitter warden publishes through — `emit(name, data)`,
+ * which is what both `@c9up/ream`'s Emitter and Adonis' expose.
+ */
+export interface WardenEmitter {
+	emit(event: string, data: unknown): unknown;
+}
+
 export class AuthManager {
 	// AdonisJS names: `guards` (name → strategy) and `default` (the guard used
 	// when none is named). Renamed from the previous `strategies`/`defaultStrategy`.
@@ -93,6 +125,40 @@ export class AuthManager {
 	private default: string;
 	private readonly rights: RightsResolver;
 
+	/**
+	 * Where auth events go. Structural and optional: warden is a leaf and must
+	 * not import an emitter — a host wires its own through `setEmitter`, and one
+	 * that wires none simply gets no events.
+	 */
+	#emitter: WardenEmitter | undefined;
+
+	/**
+	 * Publish auth events on `emitter`. AdonisJS emits six of them from its
+	 * session guard, and an app that audits logins reads exactly those.
+	 */
+	setEmitter(emitter: WardenEmitter): this {
+		this.#emitter = emitter;
+		return this;
+	}
+
+	/**
+	 * Publish one auth event. Public so the per-request `Authenticator` can
+	 * report what it observed — it holds the guard chain, the manager holds the
+	 * emitter.
+	 */
+	emitAuthEvent(event: string, payload: Record<string, unknown>): void {
+		this.#emit(event, payload);
+	}
+
+	/** Fire-and-forget: an event listener must never break authentication. */
+	#emit(event: string, payload: Record<string, unknown>): void {
+		try {
+			void this.#emitter?.emit(event, payload);
+		} catch {
+			// A throwing listener is the listener's problem, not the login's.
+		}
+	}
+
 	constructor(config: AuthConfig) {
 		// Normalise the two accepted forms — AdonisJS `{ default, guards }` and
 		// the legacy `{ defaultStrategy, strategies }` — to the AdonisJS names.
@@ -316,7 +382,16 @@ export class AuthManager {
 				},
 			);
 		}
+		this.#emit("session_auth:login_attempted", {
+			guardName: strategyName ?? this.default,
+			user,
+		});
 		await strategy.login(user, session);
+		this.#emit("session_auth:login_succeeded", {
+			guardName: strategyName ?? this.default,
+			user,
+			sessionId: undefined,
+		});
 	}
 
 	/**
@@ -333,6 +408,11 @@ export class AuthManager {
 			);
 		}
 		await strategy.logout(session);
+		this.#emit("session_auth:logged_out", {
+			guardName: strategyName ?? this.default,
+			user: null,
+			error: null,
+		});
 	}
 }
 

package/src/Authenticator.ts

@@ -321,6 +321,12 @@ export class Authenticator {
 		this.#attempted = true;
 		const names =
 			guards && guards.length > 0 ? guards : [this.#auth.defaultStrategyName];
+		const guardName = names[0] ?? this.#auth.defaultStrategyName;
+		// The four authentication events AdonisJS' session guard emits. An app
+		// auditing logins subscribes to exactly these names.
+		this.#auth.emitAuthEvent("session_auth:authentication_attempted", {
+			guardName,
+		});
 		const creds = extractCredentials(this.#ctx, this.#auth);
 		const hasSessionStrategy = names.includes("session");
 		const { result, viaGuard, attemptCount, crashCount } =
@@ -332,6 +338,11 @@ export class Authenticator {
 		if (result?.authenticated && result.user) {
 			this.#user = result.user;
 			this.#viaGuard = viaGuard;
+			this.#auth.emitAuthEvent("session_auth:authentication_succeeded", {
+				guardName: viaGuard ?? guardName,
+				user: result.user,
+				sessionId: undefined,
+			});
 			return;
 		}
 		// Every attempted guard crashed → a server-side incident, not a
@@ -343,10 +354,18 @@ export class Authenticator {
 				{ status: 500 },
 			);
 		}
-		throw new E_UNAUTHORIZED_ACCESS(result?.error ?? "Unauthorized access", {
-			guardDriverName: names[0] ?? this.#auth.defaultStrategyName,
-			redirectTo: hasSessionStrategy ? options?.loginRoute : undefined,
+		const failure = new E_UNAUTHORIZED_ACCESS(
+			result?.error ?? "Unauthorized access",
+			{
+				guardDriverName: guardName,
+				redirectTo: hasSessionStrategy ? options?.loginRoute : undefined,
+			},
+		);
+		this.#auth.emitAuthEvent("session_auth:authentication_failed", {
+			guardName,
+			error: failure,
 		});
+		throw failure;
 	}
 
 	/** Return the authenticated user or throw `E_UNAUTHORIZED_ACCESS`. */

package/src/RememberMeToken.ts

@@ -0,0 +1,223 @@
+/**
+ * Remember-me tokens — "keep me signed in" that survives the session cookie.
+ *
+ * Modelled on `@adonisjs/auth`'s `RememberMeToken`
+ * (modules/session_guard/remember_me_token.ts), because an app moving over
+ * carries the same table and the same cookie:
+ *
+ *   value  = base64url(identifier) + "." + base64url(secret)
+ *   stored = sha256(secret), never the secret itself
+ *
+ * The three properties that make this safe, all taken from upstream:
+ *
+ *  1. **Only a hash is stored.** A dump of the tokens table does not let anyone
+ *     log in — the secret exists solely in the user's cookie.
+ *  2. **The comparison is constant-time.** Comparing hashes with `===` leaks
+ *     how many leading bytes matched, which is enough to forge one byte at a
+ *     time.
+ *  3. **A used token is recycled.** Authenticating rotates the secret and
+ *     invalidates the old one, so a stolen cookie stops working the moment the
+ *     legitimate user comes back.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/** Bytes of entropy in a token secret. Adonis defaults to 40. */
+export const DEFAULT_SECRET_LENGTH = 40;
+
+/** A token as persisted. The secret is NOT here — only its hash. */
+export interface StoredRememberMeToken {
+	/** Unique id of the row; the public half of the token value. */
+	identifier: string;
+	/** Whose token this is. */
+	tokenableId: string | number;
+	/** `sha256(secret)`, hex. */
+	hash: string;
+	createdAt: number;
+	updatedAt: number;
+	expiresAt: number;
+}
+
+/** What a store must implement. Structural: warden owns no database. */
+export interface RememberMeTokenDriver {
+	create(token: StoredRememberMeToken): Promise<void>;
+	find(identifier: string): Promise<StoredRememberMeToken | null>;
+	/** Replace the hash + expiry of an existing row (recycling). */
+	update(identifier: string, hash: string, expiresAt: number): Promise<void>;
+	delete(identifier: string): Promise<void>;
+	deleteAllForUser(userId: string | number): Promise<void>;
+}
+
+/** Base64url without padding — the encoding Adonis uses for the token halves. */
+function base64UrlEncode(value: string): string {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function base64UrlDecode(value: string): string | null {
+	try {
+		const decoded = Buffer.from(value, "base64url").toString("utf8");
+		// A non-base64url character decodes to something that does not round-trip;
+		// reject rather than authenticate against a mangled identifier.
+		return Buffer.from(decoded, "utf8").toString("base64url") === value
+			? decoded
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/** `sha256(secret)` as hex — what gets stored. */
+export function hashSecret(secret: string): string {
+	return createHash("sha256").update(secret).digest("hex");
+}
+
+/**
+ * Compare two hex hashes without leaking where they diverge. Length is checked
+ * first because `timingSafeEqual` throws on a mismatch — and the length of a
+ * sha256 hex digest is public anyway.
+ */
+export function safeCompareHashes(a: string, b: string): boolean {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}
+
+/** Split a cookie value into its identifier and secret, or `null` if malformed. */
+export function decodeTokenValue(
+	value: unknown,
+): { identifier: string; secret: string } | null {
+	if (typeof value !== "string" || value.length === 0) return null;
+	const [encodedIdentifier, ...rest] = value.split(".");
+	if (!encodedIdentifier || rest.length === 0) return null;
+	const identifier = base64UrlDecode(encodedIdentifier);
+	const secret = base64UrlDecode(rest.join("."));
+	if (identifier === null || secret === null) return null;
+	if (identifier === "" || secret === "") return null;
+	return { identifier, secret };
+}
+
+/** Build the cookie value from its two halves. */
+export function encodeTokenValue(identifier: string, secret: string): string {
+	return `${base64UrlEncode(identifier)}.${base64UrlEncode(secret)}`;
+}
+
+/** A freshly minted token: what to store, and what to hand the browser. */
+export interface MintedRememberMeToken {
+	stored: StoredRememberMeToken;
+	/** Goes in the cookie. Never persisted. */
+	value: string;
+}
+
+/**
+ * Mint a token for `userId`, valid for `ageSeconds`.
+ *
+ * `identifier` is random too, not a counter: a guessable identifier would let
+ * an attacker enumerate rows and target a specific user's token.
+ */
+export function mintRememberMeToken(
+	userId: string | number,
+	ageSeconds: number,
+	secretLength = DEFAULT_SECRET_LENGTH,
+): MintedRememberMeToken {
+	const identifier = randomBytes(16).toString("hex");
+	const secret = randomBytes(secretLength).toString("base64url");
+	const now = Date.now();
+	return {
+		stored: {
+			identifier,
+			tokenableId: userId,
+			hash: hashSecret(secret),
+			createdAt: now,
+			updatedAt: now,
+			expiresAt: now + ageSeconds * 1000,
+		},
+		value: encodeTokenValue(identifier, secret),
+	};
+}
+
+/**
+ * Verify a cookie value against the store, and RECYCLE the token on success:
+ * the row keeps its identifier but gets a fresh secret and expiry, and the
+ * caller must send the returned value back as the new cookie.
+ *
+ * Recycling is what limits the damage of a stolen cookie — the thief's copy
+ * dies as soon as the real user authenticates again.
+ *
+ * Returns `null` for anything wrong: malformed value, unknown identifier,
+ * expired row, or a secret that does not match. The caller cannot tell these
+ * apart, which is deliberate — a distinguishable "unknown identifier" tells an
+ * attacker which identifiers exist.
+ */
+export async function verifyAndRecycleRememberMeToken(
+	driver: RememberMeTokenDriver,
+	cookieValue: unknown,
+	ageSeconds: number,
+	secretLength = DEFAULT_SECRET_LENGTH,
+): Promise<{ userId: string | number; value: string } | null> {
+	const decoded = decodeTokenValue(cookieValue);
+	if (!decoded) return null;
+
+	const stored = await driver.find(decoded.identifier);
+	if (!stored) return null;
+
+	if (stored.expiresAt <= Date.now()) {
+		// Expired rows are removed on sight rather than left to a cleanup job.
+		await driver.delete(stored.identifier);
+		return null;
+	}
+
+	if (!safeCompareHashes(stored.hash, hashSecret(decoded.secret))) {
+		return null;
+	}
+
+	const secret = randomBytes(secretLength).toString("base64url");
+	const expiresAt = Date.now() + ageSeconds * 1000;
+	await driver.update(stored.identifier, hashSecret(secret), expiresAt);
+
+	return {
+		userId: stored.tokenableId,
+		value: encodeTokenValue(stored.identifier, secret),
+	};
+}
+
+/** In-memory store — for tests and single-process apps. Not for a cluster. */
+export class MemoryRememberMeTokenDriver implements RememberMeTokenDriver {
+	readonly #rows = new Map<string, StoredRememberMeToken>();
+
+	async create(token: StoredRememberMeToken): Promise<void> {
+		this.#rows.set(token.identifier, { ...token });
+	}
+
+	async find(identifier: string): Promise<StoredRememberMeToken | null> {
+		const row = this.#rows.get(identifier);
+		return row ? { ...row } : null;
+	}
+
+	async update(
+		identifier: string,
+		hash: string,
+		expiresAt: number,
+	): Promise<void> {
+		const row = this.#rows.get(identifier);
+		if (!row) return;
+		this.#rows.set(identifier, {
+			...row,
+			hash,
+			expiresAt,
+			updatedAt: Date.now(),
+		});
+	}
+
+	async delete(identifier: string): Promise<void> {
+		this.#rows.delete(identifier);
+	}
+
+	async deleteAllForUser(userId: string | number): Promise<void> {
+		for (const [identifier, row] of this.#rows) {
+			if (String(row.tokenableId) === String(userId)) {
+				this.#rows.delete(identifier);
+			}
+		}
+	}
+}

package/src/ResilientBlacklistDriver.ts

@@ -4,17 +4,23 @@
  * takes the whole app down.
  *
  * Policy (fail-open on reads):
- *   - `add()`  — if the primary throws, the revocation is recorded in the
- *                fallback so logout stays effective on this instance.
- *   - `has()`  — if the primary throws, consult the fallback: a token revoked
- *                during the outage is still caught here; anything else is
- *                allowed through (fail-open). Access tokens are short-lived, so
- *                the window a missed revocation survives is bounded by the token
- *                TTL — the blacklist is defense-in-depth above expiry, not the
+ *   - `add()`  — records the revocation in BOTH, always. The fallback is this
+ *                instance's own record of what it has revoked, not a log of its
+ *                outages: writing only on failure meant a token revoked while
+ *                the primary was HEALTHY was absent from the fallback, so the
+ *                first check during a later outage let that logged-out token
+ *                through. A primary failure still does not fail the logout.
+ *   - `has()`  — asks the fallback FIRST: what this instance revoked is known
+ *                locally and needs no round trip. Otherwise it asks the
+ *                primary, and if that throws, allows the token through
+ *                (fail-open). Access tokens are short-lived, so the window a
+ *                revocation missed by BOTH survives is bounded by the token TTL
+ *                — the blacklist is defense-in-depth above expiry, not the
  *                primary boundary.
  *
- * Every degradation invokes `onDegrade` (defaults to a stderr warning) so the
- * outage is observable.
+ * Every degradation invokes `onDegrade`. The default reports the first failure
+ * per operation and then a periodic count: an outage that logs on every request
+ * buries itself, and the reader stops seeing what the flood is about.
  */
 
 import {
@@ -32,11 +38,36 @@ export interface ResilientBlacklistConfig {
 	onDegrade?: (event: BlacklistDegradeEvent) => void;
 }
 
-function defaultOnDegrade({ op, error }: BlacklistDegradeEvent): void {
-	console.warn(
-		`[warden] blacklist primary failed on ${op}; using in-memory fallback:`,
-		error,
-	);
+/** How long a repeat of the same failing operation stays folded into a count. */
+const DEGRADE_LOG_WINDOW_MS = 60_000;
+
+/**
+ * Report the first failure of each operation, then one line per window with
+ * how many were suppressed.
+ *
+ * Keyed by operation — a fixed, three-value set — never by the error text,
+ * which an attacker could influence and which would make the key set unbounded.
+ */
+function makeDefaultOnDegrade(): (event: BlacklistDegradeEvent) => void {
+	const windows = new Map<string, { until: number; suppressed: number }>();
+	return ({ op, error }: BlacklistDegradeEvent): void => {
+		const now = Date.now();
+		const open = windows.get(op);
+		if (open === undefined || open.until <= now) {
+			if (open !== undefined && open.suppressed > 0) {
+				console.warn(
+					`[warden] blacklist primary failed on ${op} ${open.suppressed} more time(s) in the last minute.`,
+				);
+			}
+			windows.set(op, { until: now + DEGRADE_LOG_WINDOW_MS, suppressed: 0 });
+			console.warn(
+				`[warden] blacklist primary failed on ${op}; using in-memory fallback:`,
+				error,
+			);
+			return;
+		}
+		open.suppressed++;
+	};
 }
 
 export class ResilientBlacklistDriver implements BlacklistDriver {
@@ -51,25 +82,34 @@ export class ResilientBlacklistDriver implements BlacklistDriver {
 	) {
 		this.#primary = primary;
 		this.#fallback = fallback;
-		this.#onDegrade = config.onDegrade ?? defaultOnDegrade;
+		this.#onDegrade = config.onDegrade ?? makeDefaultOnDegrade();
 	}
 
 	async add(jti: string, expiresAt: number): Promise<void> {
+		// The fallback first, and unconditionally: it is what this instance
+		// knows it revoked. Recording only on failure left every revocation made
+		// while the primary was healthy invisible to the fallback — and those are
+		// most of them.
+		await this.#fallback.add(jti, expiresAt);
 		try {
 			await this.#primary.add(jti, expiresAt);
 		} catch (error) {
+			// The revocation is already durable enough for this instance, so a
+			// primary failure must not fail the logout.
 			this.#onDegrade({ op: "add", error });
-			await this.#fallback.add(jti, expiresAt);
 		}
 	}
 
 	async has(jti: string): Promise<boolean> {
+		// What this instance revoked is known locally — no round trip needed, and
+		// it stays correct through an outage that starts a moment later.
+		if (await this.#fallback.has(jti)) return true;
 		try {
 			return await this.#primary.has(jti);
 		} catch (error) {
 			this.#onDegrade({ op: "has", error });
-			// Fail-open: honour in-outage revocations on this instance, allow rest.
-			return this.#fallback.has(jti);
+			// Fail-open on what neither knows: access tokens are short-lived.
+			return false;
 		}
 	}