@c9up/warden 0.1.16 → 0.1.18

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;
 		}
 	}
 

package/src/WardenProvider.ts

@@ -153,5 +153,95 @@ export default class WardenProvider {
 	async boot() {
 		const manager = await this.app.container.resolve(AuthManager);
 		if (manager instanceof AuthManager) setAuth(manager);
+		await this.#registerTemplateTags();
 	}
+
+	/**
+	 * Publish `@can` / `@cannot` to the template engine, as AdonisJS's bouncer
+	 * does. A migrated template keeps `@can('PostPolicy.edit', post) … @endcan`
+	 * unchanged.
+	 *
+	 * Both are BLOCK tags and both AWAIT — the check returns a promise — so they
+	 * render on the async path and raise on a synchronous one, matching upstream
+	 * (which emits `await bouncer.can(...)`). The checks themselves come from
+	 * `ctx.bouncer.templateHelpers`, shared into the view per request.
+	 *
+	 * Resolved through the container: warden must not depend on the engine, and
+	 * an app with no template layer simply skips this.
+	 */
+	async #registerTemplateTags(): Promise<void> {
+		const engine = await this.#resolveTemplateEngine();
+		if (engine === undefined) return;
+		for (const tagName of ["can", "cannot"] as const) {
+			engine.registerTag({
+				tagName,
+				block: true,
+				seekable: true,
+				async compile(_parser, buffer, token) {
+					// The shared bag lives in the render scope under `bouncer`.
+					const bouncer = token.evaluate(
+						"typeof bouncer === 'undefined' ? undefined : bouncer",
+					);
+					const check = Reflect.get(Object(bouncer), tagName);
+					if (typeof check !== "function") {
+						// No bouncer on this request: deny rather than render an
+						// unguarded body.
+						return;
+					}
+					const args = token.evaluate(`[${token.properties.jsArg}]`);
+					const allowed = await check.apply(
+						bouncer,
+						Array.isArray(args) ? args : [],
+					);
+					if (allowed === true) buffer.writeRaw(await token.renderBody());
+				},
+			});
+		}
+	}
+
+	/** The template engine, if the host installed one. */
+	async #resolveTemplateEngine(): Promise<TemplateEngineLike | undefined> {
+		for (const token of ["inker", "view"]) {
+			try {
+				const binding: unknown = await this.app.container.resolve(token);
+				for (const candidate of [
+					binding,
+					Reflect.get(Object(binding), "_templates"),
+				]) {
+					if (
+						typeof candidate === "object" &&
+						candidate !== null &&
+						typeof Reflect.get(candidate, "registerTag") === "function"
+					) {
+						return {
+							registerTag: Reflect.get(candidate, "registerTag").bind(
+								candidate,
+							),
+						};
+					}
+				}
+			} catch {
+				// A host without a template layer is not an error.
+			}
+		}
+		return undefined;
+	}
+}
+
+/** The only surface warden needs of a template engine. */
+interface TemplateEngineLike {
+	registerTag(tag: {
+		tagName: string;
+		block: boolean;
+		seekable: boolean;
+		compile(
+			parser: unknown,
+			buffer: { writeRaw(text: string): void },
+			token: {
+				properties: { jsArg: string };
+				renderBody(): string | Promise<string>;
+				evaluate(expression: string): unknown;
+			},
+		): void | Promise<void>;
+	}): void;
 }

package/src/bouncer/Bouncer.ts

@@ -38,7 +38,7 @@ export class Bouncer {
 	readonly #policies: Record<string, new () => BasePolicy>;
 	readonly #scope: Scope;
 	readonly #resolver: RightsResolver | undefined;
-	readonly #containerResolver: PolicyContainerResolver | undefined;
+	#containerResolver: PolicyContainerResolver | undefined;
 	readonly #emitter: BouncerEmitter | undefined;
 	/** Memoized resolution — a Bouncer is fixed per `(user, scope)`, so resolve once (D3). */
 	#resolved: Promise<EffectivePermissions> | undefined;
@@ -58,6 +58,19 @@ export class Bouncer {
 		this.#emitter = context?.emitter;
 	}
 
+	/**
+	 * Point the bouncer at an IoC resolver, so a policy's constructor
+	 * dependencies are injected (AdonisJS `setContainerResolver`).
+	 *
+	 * The constructor takes one too; this is the setter AdonisJS exposes so the
+	 * HTTP layer can hand over the REQUEST's resolver after the bouncer exists.
+	 * Passing `undefined` clears it, and policies fall back to `new Policy()`.
+	 */
+	setContainerResolver(containerResolver?: PolicyContainerResolver): this {
+		this.#containerResolver = containerResolver;
+		return this;
+	}
+
 	/**
 	 * Resolve the user, lazily invoking a resolver callback once and memoizing
 	 * the result (Adonis `#getUser`). A plain `UserPayload | null` passes through.
@@ -157,6 +170,53 @@ export class Bouncer {
 		return AuthorizationResponse.deny(message, status);
 	}
 
+	/**
+	 * The checks a TEMPLATE performs, shared into the view per request so
+	 * `@can('post.edit', post)` resolves them (AdonisJS shares the same pair
+	 * under `bouncer`; it names the bag `edgeHelpers`, we do not borrow the
+	 * engine's name).
+	 *
+	 * AdonisJS reads a dotted action as `policy.method` —
+	 * `'PostPolicy.edit'` is `with('PostPolicy').allows('edit', …)`. Warden,
+	 * however, keys its ABILITIES with dots (`'post.edit'`), so applying that
+	 * split blindly would break every warden app.
+	 *
+	 * NAMED DEVIATION, strictly more permissive: a registered ability wins, and
+	 * only an action with no matching ability falls through to the policy
+	 * split. A migrated AdonisJS template resolves its policies exactly as
+	 * before, and a warden app keeps its dotted abilities.
+	 */
+	readonly templateHelpers: {
+		bouncer: {
+			can(action: string, ...args: unknown[]): Promise<boolean>;
+			cannot(action: string, ...args: unknown[]): Promise<boolean>;
+		};
+	} = {
+		bouncer: {
+			can: (action: string, ...args: unknown[]): Promise<boolean> => {
+				const split = this.#splitAction(action);
+				return split === undefined
+					? this.allows(action, ...args)
+					: this.with(split.policy).allows(split.method, ...args);
+			},
+			cannot: (action: string, ...args: unknown[]): Promise<boolean> => {
+				const split = this.#splitAction(action);
+				return split === undefined
+					? this.denies(action, ...args)
+					: this.with(split.policy).denies(split.method, ...args);
+			},
+		},
+	};
+
+	/** `policy.method` for a dotted action that names no registered ability;
+	 * `undefined` when the action IS an ability (warden keys its own with dots). */
+	#splitAction(action: string): { policy: string; method: string } | undefined {
+		if (Object.hasOwn(this.#abilities, action)) return undefined;
+		const dot = action.indexOf(".");
+		if (dot <= 0 || dot === action.length - 1) return undefined;
+		return { policy: action.slice(0, dot), method: action.slice(dot + 1) };
+	}
+
 	/** Open a policy for checks (D8 — fresh policy instance per check). */
 	with(policy: (new () => BasePolicy) | string): PolicyAuthorizer {
 		const factory =

package/src/config.ts

@@ -22,6 +22,10 @@ import type { MfaManager } from "./mfa/MfaManager.js";
 import type { RightsStore, Scope } from "./rights/types.js";
 import type { ApiKeyConfig } from "./strategies/ApiKeyStrategy.js";
 import { ApiKeyStrategy } from "./strategies/ApiKeyStrategy.js";
+import {
+	type BasicAuthConfig,
+	BasicAuthStrategy,
+} from "./strategies/BasicAuthStrategy.js";
 import { JwtStrategy } from "./strategies/JwtStrategy.js";
 import type { SessionStrategyConfig } from "./strategies/SessionStrategy.js";
 import { SessionStrategy } from "./strategies/SessionStrategy.js";
@@ -76,6 +80,11 @@ export function apiKeyGuard(config: ApiKeyConfig): GuardFactory {
 	return new ApiKeyStrategy(config);
 }
 
+/** Build an HTTP Basic guard from its config (AdonisJS `basicAuthGuard()`). */
+export function basicAuthGuard(config: BasicAuthConfig): GuardFactory {
+	return new BasicAuthStrategy(config);
+}
+
 export interface WardenConfig {
 	/**
 	 * AdonisJS-style default guard NAME — the key in {@link WardenConfig.guards}

package/src/firstcontact/drivers/GitHubDriver.ts

@@ -8,6 +8,7 @@ import type {
 	OAuthToken,
 	OAuthUser,
 } from "../types.js";
+import { assertOAuthState } from "../types.js";
 
 export class GitHubDriver implements FirstContactDriver {
 	constructor(private config: OAuthConfig) {}
@@ -27,9 +28,7 @@ export class GitHubDriver implements FirstContactDriver {
 		state?: string,
 		expectedState?: string,
 	): Promise<{ user: OAuthUser; token: OAuthToken }> {
-		if (expectedState && state !== expectedState) {
-			throw new Error("OAuth state mismatch — possible CSRF attack");
-		}
+		assertOAuthState(state, expectedState);
 		const tokenRes = await fetch(
 			"https://github.com/login/oauth/access_token",
 			{

package/src/firstcontact/drivers/GoogleDriver.ts

@@ -8,6 +8,7 @@ import type {
 	OAuthToken,
 	OAuthUser,
 } from "../types.js";
+import { assertOAuthState } from "../types.js";
 
 export class GoogleDriver implements FirstContactDriver {
 	constructor(private config: OAuthConfig) {}
@@ -30,9 +31,7 @@ export class GoogleDriver implements FirstContactDriver {
 		expectedState?: string,
 	): Promise<{ user: OAuthUser; token: OAuthToken }> {
 		// CSRF protection: validate state matches what we sent in redirectUrl().
-		if (expectedState && state !== expectedState) {
-			throw new Error("OAuth state mismatch — possible CSRF attack");
-		}
+		assertOAuthState(state, expectedState);
 		const tokenRes = await fetch("https://oauth2.googleapis.com/token", {
 			method: "POST",
 			headers: { "Content-Type": "application/x-www-form-urlencoded" },

package/src/firstcontact/types.ts

@@ -36,3 +36,27 @@ export interface FirstContactDriver {
 		expectedState?: string,
 	): Promise<{ user: OAuthUser; token: OAuthToken }>;
 }
+
+/**
+ * Check the OAuth `state` round-trip, failing CLOSED.
+ *
+ * The check used to be `if (expectedState && state !== expectedState)`, so a
+ * caller that passed no expected state got NO CSRF protection and no sign that
+ * it was missing. A driver used directly — without the manager, which already
+ * refuses — was therefore open by default. Anything that cannot be verified is
+ * refused instead.
+ */
+export function assertOAuthState(
+	state: string | undefined,
+	expectedState: string | undefined,
+): void {
+	if (!expectedState) {
+		throw new Error(
+			"[warden] OAuth callback requires expectedState for CSRF protection. " +
+				"Store the state given to redirectUrl() in the session and pass it here.",
+		);
+	}
+	if (state !== expectedState) {
+		throw new Error("OAuth state mismatch — possible CSRF attack");
+	}
+}

package/src/index.ts

@@ -17,7 +17,7 @@ export type {
 	AuthStrategy,
 	UserPayload,
 } from "./AuthManager.js";
-export { AuthManager } from "./AuthManager.js";
+export { AuthManager, type WardenEmitter } from "./AuthManager.js";
 export type { AuthRateLimiterConfig } from "./AuthRateLimiter.js";
 export { AuthRateLimiter } from "./AuthRateLimiter.js";
 export { AbilitiesBuilder } from "./bouncer/AbilitiesBuilder.js";
@@ -41,6 +41,7 @@ export type {
 export type { GuardFactory, WardenConfig } from "./config.js";
 export {
 	apiKeyGuard,
+	basicAuthGuard,
 	defineConfig,
 	jwtGuard,
 	sessionGuard,
@@ -98,8 +99,9 @@ export type {
 	TotpAlgorithm,
 	TotpConfig,
 	TotpEnrollment,
+	TotpReplayGuard,
 } from "./mfa/TotpProvider.js";
-export { TotpProvider } from "./mfa/TotpProvider.js";
+export { MemoryTotpReplayGuard, TotpProvider } from "./mfa/TotpProvider.js";
 export type {
 	AuthenticationOptionsJSON,
 	AuthenticationResponseJSON,
@@ -116,6 +118,7 @@ export {
 	MemoryWebauthnCredentialStore,
 	WebauthnProvider,
 } from "./mfa/WebauthnProvider.js";
+export { quasarConnection } from "./quasar.js";
 export type {
 	RedisBlacklistConfig,
 	RedisLikeClient,
@@ -129,6 +132,19 @@ export {
 	generateRefreshToken,
 	MemoryRefreshTokenDriver,
 } from "./RefreshTokenStore.js";
+export {
+	DEFAULT_SECRET_LENGTH,
+	decodeTokenValue,
+	encodeTokenValue,
+	hashSecret,
+	MemoryRememberMeTokenDriver,
+	type MintedRememberMeToken,
+	mintRememberMeToken,
+	type RememberMeTokenDriver,
+	type StoredRememberMeToken,
+	safeCompareHashes,
+	verifyAndRecycleRememberMeToken,
+} from "./RememberMeToken.js";
 export type {
 	BlacklistDegradeEvent,
 	ResilientBlacklistConfig,
@@ -144,6 +160,13 @@ export type {
 export { scopeKey } from "./rights/types.js";
 export type { ApiKeyConfig } from "./strategies/ApiKeyStrategy.js";
 export { ApiKeyStrategy } from "./strategies/ApiKeyStrategy.js";
+export type { BasicAuthConfig } from "./strategies/BasicAuthStrategy.js";
+export {
+	BasicAuthStrategy,
+	basicAuthChallenge,
+	decodeBasicAuth,
+	safeCompare,
+} from "./strategies/BasicAuthStrategy.js";
 export type { JwtClaims, JwtStrategyConfig } from "./strategies/JwtStrategy.js";
 export { generateJwtSecret, JwtStrategy } from "./strategies/JwtStrategy.js";
 export type {

package/src/mfa/MfaManager.ts

@@ -136,7 +136,7 @@ export class MfaManager {
 		if (!factor || factor.kind !== "totp" || !factor.secret) {
 			return false;
 		}
-		if (!totp.verify(factor.secret, code)) {
+		if (!(await totp.verify(factor.secret, code))) {
 			return false;
 		}
 		await this.#store.save({ ...factor, confirmedAt: Date.now() });
@@ -147,13 +147,20 @@ export class MfaManager {
 	async verifyTotp(userId: string, code: string): Promise<boolean> {
 		const totp = this.#requireTotp();
 		const factors = await this.#store.findByUser(userId);
-		return factors.some(
-			(f) =>
-				f.kind === "totp" &&
-				f.confirmedAt !== undefined &&
-				f.secret !== undefined &&
-				totp.verify(f.secret, code),
-		);
+		// Sequential, not Promise.all: the replay guard must see one accepted
+		// code at a time, and stopping at the first match avoids burning the
+		// code against a second factor that would then reject it as replayed.
+		for (const factor of factors) {
+			if (
+				factor.kind !== "totp" ||
+				factor.confirmedAt === undefined ||
+				factor.secret === undefined
+			) {
+				continue;
+			}
+			if (await totp.verify(factor.secret, code)) return true;
+		}
+		return false;
 	}
 
 	// ── Backup codes ─────────────────────────────────────────────────

package/src/mfa/TotpProvider.ts

@@ -25,6 +25,57 @@ export interface TotpConfig {
 	 * tolerate clock skew. Default `1` (i.e. ±30s with the default period).
 	 */
 	window?: number;
+	/**
+	 * Remembers codes already accepted, so one cannot be used twice
+	 * (RFC 6238 §5.2). Defaults to an in-process guard, which is correct for a
+	 * single instance; inject a shared store (Redis, the session table) when the
+	 * app runs on several.
+	 *
+	 * Omit deliberately — `replayGuard: null` — to accept replays, e.g. when an
+	 * outer layer already enforces single use.
+	 */
+	replayGuard?: TotpReplayGuard | null;
+}
+
+/**
+ * Remembers accepted (secret, time-step) pairs for as long as they could still
+ * be replayed.
+ *
+ * Keys are opaque digests, never the secret itself: a store may be shared, and
+ * a guard that leaks the seed is worse than the replay it prevents.
+ */
+export interface TotpReplayGuard {
+	/** True when this exact code has already been accepted. */
+	used(key: string): boolean | Promise<boolean>;
+	/** Record it as used; `ttlMs` is how long it could still be replayed. */
+	remember(key: string, ttlMs: number): void | Promise<void>;
+}
+
+/**
+ * In-process replay guard. Entries expire on their own, and a sweep runs
+ * whenever one is added, so the set stays bounded by the accept window rather
+ * than by how many codes have been tried.
+ */
+export class MemoryTotpReplayGuard implements TotpReplayGuard {
+	readonly #seen = new Map<string, number>();
+
+	used(key: string): boolean {
+		const expiresAt = this.#seen.get(key);
+		if (expiresAt === undefined) return false;
+		if (expiresAt <= Date.now()) {
+			this.#seen.delete(key);
+			return false;
+		}
+		return true;
+	}
+
+	remember(key: string, ttlMs: number): void {
+		const now = Date.now();
+		for (const [seenKey, expiresAt] of this.#seen) {
+			if (expiresAt <= now) this.#seen.delete(seenKey);
+		}
+		this.#seen.set(key, now + ttlMs);
+	}
 }
 
 export interface TotpEnrollment {
@@ -43,10 +94,18 @@ const DEFAULTS = {
 
 export class TotpProvider {
 	readonly kind = "totp" as const;
-	readonly #cfg: Required<TotpConfig>;
+	readonly #cfg: Required<Omit<TotpConfig, "replayGuard">>;
+	readonly #replayGuard: TotpReplayGuard | null;
 
 	constructor(config: TotpConfig = {}) {
-		this.#cfg = { ...DEFAULTS, ...config };
+		const { replayGuard, ...rest } = config;
+		this.#cfg = { ...DEFAULTS, ...rest };
+		// Defaults ON: a code that works twice is the failure this exists to
+		// prevent, so opting out has to be deliberate.
+		this.#replayGuard =
+			replayGuard === null
+				? null
+				: (replayGuard ?? new MemoryTotpReplayGuard());
 		if (this.#cfg.digits < 6 || this.#cfg.digits > 8) {
 			throw new WardenError(
 				"INVALID_CONFIG",
@@ -91,7 +150,11 @@ export class TotpProvider {
 	 * Verify a user-supplied code against the secret, accepting codes from the
 	 * surrounding `window` time steps to tolerate clock skew. Constant-time.
 	 */
-	verify(secret: string, code: string, atMs: number = Date.now()): boolean {
+	async verify(
+		secret: string,
+		code: string,
+		atMs: number = Date.now(),
+	): Promise<boolean> {
 		const normalized = code.replace(/\s/g, "");
 		if (normalized.length !== this.#cfg.digits) {
 			return false;
@@ -99,13 +162,34 @@ export class TotpProvider {
 		const key = base32Decode(secret);
 		const current = Math.floor(atMs / 1000 / this.#cfg.period);
 		for (let offset = -this.#cfg.window; offset <= this.#cfg.window; offset++) {
-			if (constantTimeEqual(this.#hotp(key, current + offset), normalized)) {
-				return true;
-			}
+			const counter = current + offset;
+			if (!constantTimeEqual(this.#hotp(key, counter), normalized)) continue;
+			if (this.#replayGuard === null) return true;
+			// A matching code is only accepted ONCE. Without this it stays valid
+			// for the whole window — with the default settings, ~90 seconds in
+			// which a shoulder-surfed or intercepted code still works.
+			const seenKey = this.#replayKey(secret, counter);
+			if (await this.#replayGuard.used(seenKey)) return false;
+			// Remember it for as long as it could still be replayed: until the
+			// last step that would accept it has passed.
+			const ttlMs =
+				(counter + this.#cfg.window + 1) * this.#cfg.period * 1000 - atMs;
+			await this.#replayGuard.remember(seenKey, Math.max(ttlMs, 0));
+			return true;
 		}
 		return false;
 	}
 
+	/**
+	 * An opaque key for one (secret, step) pair. Hashed, so a shared store never
+	 * holds the seed, and bounded in length whatever the secret looks like.
+	 */
+	#replayKey(secret: string, counter: number): string {
+		return createHmac("sha256", secret)
+			.update(`totp:${counter}`)
+			.digest("base64url");
+	}
+
 	/** RFC 4226 HOTP: HMAC over the 8-byte counter, dynamically truncated. */
 	#hotp(key: Uint8Array, counter: number): string {
 		const buf = Buffer.alloc(8);