@c9up/warden 0.1.17 → 0.1.19

package/src/Authenticator.ts

@@ -14,15 +14,15 @@
  * `@c9up/ream`.
  */
 
-import {
-	type AuthManager,
-	type AuthResult,
-	type AuthStrategy,
-	sanitizePayload,
-	type UserPayload,
+import type {
+	AuthManager,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
 } from "./AuthManager.js";
 import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
 import type { WardenContext } from "./middleware.js";
+import { sanitizePayload } from "./sanitize.js";
 import type { SessionStore } from "./strategies/SessionStrategy.js";
 
 /**
@@ -308,6 +308,31 @@ export class Authenticator {
 		}
 	}
 
+	/**
+	 * Try the given guards in order and report whether one succeeded, without
+	 * throwing (AdonisJS `checkUsing`).
+	 *
+	 * The non-throwing sibling of {@link authenticateUsing}: `check()` is to
+	 * `authenticate()` what this is to it. A handler that wants to branch on
+	 * "is anyone signed in through either of these" had to wrap the throwing
+	 * form in a try/catch itself.
+	 */
+	async checkUsing(
+		guards?: string[],
+		options?: { loginRoute?: string },
+	): Promise<boolean> {
+		try {
+			await this.authenticateUsing(guards, options);
+			return this.isAuthenticated;
+		} catch (err) {
+			// A credential rejection is an answer, not a failure. Anything else
+			// — a crashed strategy, a config error — is still a real problem and
+			// must not be reported as "not signed in".
+			if (err instanceof E_UNAUTHORIZED_ACCESS) return false;
+			throw err;
+		}
+	}
+
 	/**
 	 * Authenticate by trying the given guards in order (default: the default
 	 * guard). Sets the user on the first success; throws `E_UNAUTHORIZED_ACCESS`
@@ -321,6 +346,14 @@ export class Authenticator {
 		this.#attempted = true;
 		const names =
 			guards && guards.length > 0 ? guards : [this.#auth.defaultStrategyName];
+		const guardName = names[0] ?? this.#auth.defaultStrategyName;
+		// Namespaced by the guard's driver, as AdonisJS does: `session_auth:*`,
+		// `access_tokens_auth:*`, `basic_auth:*`. An app auditing session logins
+		// must not be told about bearer-token traffic under the same name.
+		this.#auth.emitAuthEvent(
+			`${this.#auth.eventPrefixFor(guardName)}:authentication_attempted`,
+			{ guardName },
+		);
 		const creds = extractCredentials(this.#ctx, this.#auth);
 		const hasSessionStrategy = names.includes("session");
 		const { result, viaGuard, attemptCount, crashCount } =
@@ -332,6 +365,13 @@ export class Authenticator {
 		if (result?.authenticated && result.user) {
 			this.#user = result.user;
 			this.#viaGuard = viaGuard;
+			// The guard that actually answered names the event, not the one asked
+			// for first.
+			const winner = viaGuard ?? guardName;
+			this.#auth.emitAuthEvent(
+				`${this.#auth.eventPrefixFor(winner)}:authentication_succeeded`,
+				{ guardName: winner, user: result.user, sessionId: undefined },
+			);
 			return;
 		}
 		// Every attempted guard crashed → a server-side incident, not a
@@ -343,10 +383,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(
+			`${this.#auth.eventPrefixFor(guardName)}:authentication_failed`,
+			{ guardName, error: failure },
+		);
+		throw failure;
 	}
 
 	/** Return the authenticated user or throw `E_UNAUTHORIZED_ACCESS`. */

package/src/RememberMeToken.ts

@@ -0,0 +1,357 @@
+/**
+ * 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";
+import { Secret } from "./Secret.js";
+
+/** 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);
+			}
+		}
+	}
+}
+
+/**
+ * A remember-me token as an object, matching `@adonisjs/auth`'s
+ * `RememberMeToken` (modules/session_guard/remember_me_token.ts).
+ *
+ * The functions above are what warden's own guard uses and stay the primary
+ * API. This class exists because an app moving over calls
+ * `RememberMeToken.decode(...)` / `token.verify(secret)` directly — upstream
+ * exports it — and finding nothing under that name is a migration stopping at
+ * an import line. Both sit on the same encoding and the same hashing, so they
+ * cannot disagree about what a token is.
+ *
+ * Secrets come back wrapped in {@link Secret} so one cannot end up in a log by
+ * being interpolated into a string, which is what upstream does too.
+ */
+export class RememberMeToken {
+	/**
+	 * Split a public token value into its identifier and secret. Returns `null`
+	 * for anything malformed rather than throwing — a bad cookie is an ordinary
+	 * event, not an exception.
+	 */
+	static decode(
+		value: string,
+	): { identifier: string; secret: Secret<string> } | null {
+		const decoded = decodeTokenValue(value);
+		if (!decoded) return null;
+		return {
+			identifier: decoded.identifier,
+			secret: new Secret(decoded.secret),
+		};
+	}
+
+	/** A fresh secret and the hash to store for it. */
+	static seed(size: number = DEFAULT_SECRET_LENGTH): {
+		secret: Secret<string>;
+		hash: string;
+	} {
+		const secret = randomBytes(size).toString("base64url");
+		return { secret: new Secret(secret), hash: hashSecret(secret) };
+	}
+
+	/**
+	 * Everything the persistence layer needs for a new token, without deciding
+	 * how it is stored (upstream `createTransientToken`).
+	 *
+	 * `expiresIn` is in SECONDS, as everywhere else in this module. AdonisJS
+	 * also accepts a duration string there; warden takes the number, so the
+	 * unit is never ambiguous at a call site.
+	 */
+	static createTransientToken(
+		userId: string | number,
+		size: number,
+		expiresIn: number,
+	): {
+		secret: Secret<string>;
+		hash: string;
+		userId: string | number;
+		expiresAt: Date;
+	} {
+		const { secret, hash } = RememberMeToken.seed(size);
+		return {
+			secret,
+			hash,
+			userId,
+			expiresAt: new Date(Date.now() + expiresIn * 1000),
+		};
+	}
+
+	identifier: string;
+	tokenableId: string | number;
+	hash: string;
+	createdAt: Date;
+	updatedAt: Date;
+	expiresAt: Date;
+	/** The public `identifier.secret` value — only on a token just minted. */
+	value?: Secret<string>;
+
+	constructor(attributes: {
+		identifier: string;
+		tokenableId: string | number;
+		hash: string;
+		createdAt: Date;
+		updatedAt: Date;
+		expiresAt: Date;
+		secret?: Secret<string>;
+	}) {
+		this.identifier = attributes.identifier;
+		this.tokenableId = attributes.tokenableId;
+		this.hash = attributes.hash;
+		this.createdAt = attributes.createdAt;
+		this.updatedAt = attributes.updatedAt;
+		this.expiresAt = attributes.expiresAt;
+		if (attributes.secret) {
+			this.value = new Secret(
+				encodeTokenValue(attributes.identifier, attributes.secret.release()),
+			);
+		}
+	}
+
+	/** Build one from a stored row, whose timestamps are epoch milliseconds. */
+	static fromStored(stored: StoredRememberMeToken): RememberMeToken {
+		return new RememberMeToken({
+			identifier: stored.identifier,
+			tokenableId: stored.tokenableId,
+			hash: stored.hash,
+			createdAt: new Date(stored.createdAt),
+			updatedAt: new Date(stored.updatedAt),
+			expiresAt: new Date(stored.expiresAt),
+		});
+	}
+
+	/** The row to persist, in the shape {@link RememberMeTokenDriver} takes. */
+	toStored(): StoredRememberMeToken {
+		return {
+			identifier: this.identifier,
+			tokenableId: this.tokenableId,
+			hash: this.hash,
+			createdAt: this.createdAt.getTime(),
+			updatedAt: this.updatedAt.getTime(),
+			expiresAt: this.expiresAt.getTime(),
+		};
+	}
+
+	/** Whether the token is past its expiry. */
+	isExpired(): boolean {
+		return this.expiresAt.getTime() <= Date.now();
+	}
+
+	/** Constant-time check of a presented secret against the stored hash. */
+	verify(secret: Secret<string>): boolean {
+		return safeCompareHashes(this.hash, hashSecret(secret.release()));
+	}
+}

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/Secret.ts

@@ -0,0 +1,41 @@
+/**
+ * Wraps a sensitive value so it never leaks through a log, `JSON.stringify`, or
+ * `util.inspect`. Read it back deliberately with {@link Secret.release}.
+ *
+ * AdonisJS takes this from `@adonisjs/core/helpers`, and its `RememberMeToken`
+ * hands secrets out wrapped in one. Warden carries its own copy rather than
+ * importing `@c9up/ream`: it has no runtime dependencies and ships a standalone
+ * entry point, so reaching for a peer here would break the framework-free mode.
+ * Same reason every native package carries its own platform map.
+ */
+const REDACTED = "[redacted]";
+
+export class Secret<T> {
+	readonly #value: T;
+	readonly #keyword: string;
+
+	constructor(value: T, redactedKeyword: string = REDACTED) {
+		this.#value = value;
+		this.#keyword = redactedKeyword;
+	}
+
+	/** Redacted placeholder, so `JSON.stringify` never emits the secret. */
+	toJSON(): string {
+		return this.#keyword;
+	}
+
+	/** Redacted placeholder for string coercion and template literals. */
+	toString(): string {
+		return this.#keyword;
+	}
+
+	/** Redacted placeholder for `console.log` / `util.inspect`. */
+	[Symbol.for("nodejs.util.inspect.custom")](): string {
+		return this.#keyword;
+	}
+
+	/** Release the underlying value — the one deliberate way to read it. */
+	release(): T {
+		return this.#value;
+	}
+}