@c9up/warden 0.1.17 → 0.1.19

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

package/src/mfa/webauthn-codec.ts

@@ -48,11 +48,31 @@ interface Decoded {
 	next: number;
 }
 
+/**
+ * How deep a nested item may go.
+ *
+ * Every item here is attacker-supplied: a registration payload is whatever the
+ * browser posted. Without a limit, a run of tag bytes recurses once per byte
+ * and overflows the stack — 200 KB was enough to kill the request.
+ */
+const MAX_DEPTH = 32;
+
 /**
  * Decode a single CBOR item starting at `start`. Definite-length only —
  * indefinite-length items and floats are rejected (WebAuthn uses neither).
+ *
+ * Every declared length is checked against the bytes actually left. A CBOR
+ * header can claim up to 2^64 items in five bytes; believing it meant looping
+ * billions of times over a buffer that ended long ago, which cost seconds of
+ * blocked event loop per request.
  */
-export function decodeCbor(buf: Buffer, start = 0): Decoded {
+export function decodeCbor(buf: Buffer, start = 0, depth = 0): Decoded {
+	if (depth > MAX_DEPTH) {
+		throw new Error(`CBOR: nesting deeper than ${MAX_DEPTH} is not supported`);
+	}
+	if (start < 0 || start >= buf.length) {
+		throw new Error("CBOR: item starts past the end of the buffer");
+	}
 	const major = buf[start] >> 5;
 	const info = buf[start] & 0x1f;
 	let len: number;
@@ -60,36 +80,56 @@ export function decodeCbor(buf: Buffer, start = 0): Decoded {
 	if (info < 24) {
 		len = info;
 	} else if (info === 24) {
+		if (p >= buf.length) throw new Error("CBOR: truncated length");
 		len = buf[p];
 		p += 1;
 	} else if (info === 25) {
+		if (p + 2 > buf.length) throw new Error("CBOR: truncated length");
 		len = buf.readUInt16BE(p);
 		p += 2;
 	} else if (info === 26) {
+		if (p + 4 > buf.length) throw new Error("CBOR: truncated length");
 		len = buf.readUInt32BE(p);
 		p += 4;
 	} else if (info === 27) {
-		len = Number(buf.readBigUInt64BE(p));
+		if (p + 8 > buf.length) throw new Error("CBOR: truncated length");
+		const wide = buf.readBigUInt64BE(p);
+		if (wide > BigInt(Number.MAX_SAFE_INTEGER)) {
+			throw new Error("CBOR: length exceeds the safe integer range");
+		}
+		len = Number(wide);
 		p += 8;
 	} else {
 		throw new Error("CBOR: indefinite or reserved length is not supported");
 	}
 
+	/** Reject a declared count the remaining bytes cannot possibly hold. */
+	const fits = (perItem: number): void => {
+		if (len > (buf.length - p) / perItem) {
+			throw new Error("CBOR: declared length exceeds the remaining bytes");
+		}
+	};
+
 	switch (major) {
 		case 0: // unsigned int
 			return { value: len, next: p };
 		case 1: // negative int
 			return { value: -1 - len, next: p };
 		case 2: // byte string
+			fits(1);
 			return { value: buf.subarray(p, p + len), next: p + len };
 		case 3: // text string
+			fits(1);
 			return { value: buf.toString("utf8", p, p + len), next: p + len };
 		case 4: {
 			// array
+			// One item is one byte at minimum, so a count above the bytes left
+			// cannot be honest.
+			fits(1);
 			const arr: CborValue[] = [];
 			let cur = p;
 			for (let i = 0; i < len; i++) {
-				const d = decodeCbor(buf, cur);
+				const d = decodeCbor(buf, cur, depth + 1);
 				arr.push(d.value);
 				cur = d.next;
 			}
@@ -97,12 +137,14 @@ export function decodeCbor(buf: Buffer, start = 0): Decoded {
 		}
 		case 5: {
 			// map
+			// A pair is two bytes at minimum.
+			fits(2);
 			const map: CborMap = new Map();
 			let cur = p;
 			for (let i = 0; i < len; i++) {
-				const k = decodeCbor(buf, cur);
+				const k = decodeCbor(buf, cur, depth + 1);
 				cur = k.next;
-				const v = decodeCbor(buf, cur);
+				const v = decodeCbor(buf, cur, depth + 1);
 				cur = v.next;
 				if (typeof k.value !== "number" && typeof k.value !== "string") {
 					throw new Error("CBOR: only integer/text map keys are supported");
@@ -113,7 +155,7 @@ export function decodeCbor(buf: Buffer, start = 0): Decoded {
 		}
 		case 6: {
 			// tag — decode and surface the tagged content
-			const d = decodeCbor(buf, p);
+			const d = decodeCbor(buf, p, depth + 1);
 			return { value: d.value, next: d.next };
 		}
 		case 7:

package/src/middleware.ts

@@ -20,7 +20,7 @@ import { Authenticator } from "./Authenticator.js";
 import { AuthManager, type UserPayload } from "./AuthManager.js";
 import type { BasePolicy } from "./bouncer/BasePolicy.js";
 import { Bouncer } from "./bouncer/Bouncer.js";
-import type { Ability } from "./bouncer/types.js";
+import type { Ability, PolicyContainerResolver } from "./bouncer/types.js";
 import type { ScopeRequestContext } from "./config.js";
 import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
 import {
@@ -56,6 +56,33 @@ interface ContainerResolver {
 	make(token: ResolvableToken): Promise<unknown>;
 }
 
+/**
+ * Adapt the request resolver to the shape the Bouncer needs for policy DI.
+ *
+ * The context resolver is deliberately untyped (`Promise<unknown>`) — it
+ * resolves string tokens too. `instanceof` is what proves the instance is the
+ * policy that was asked for: a real check rather than an assertion, and it
+ * catches a host resolver that hands back something else instead of letting a
+ * wrong object reach the policy's methods.
+ */
+function policyResolver(
+	resolver: ContainerResolver | undefined,
+): PolicyContainerResolver | undefined {
+	if (resolver === undefined) return undefined;
+	return {
+		async make<T>(ctor: new (...args: never[]) => T): Promise<T> {
+			const instance = await resolver.make(ctor);
+			if (!(instance instanceof ctor)) {
+				throw new WardenError(
+					"POLICY_RESOLUTION_FAILED",
+					`The container resolved "${ctor.name}" to something else — a policy must be an instance of the class that was requested.`,
+				);
+			}
+			return instance;
+		},
+	};
+}
+
 /**
  * Agnostic authorization slot — structurally Ream's `Authorizer` interface (and
  * Adonis's bouncer contract): `allows` / `denies` / `authorize`. Typed as the
@@ -317,6 +344,19 @@ export async function silentAuth(ctx: WardenContext, next: WardenNext) {
 	await next();
 }
 
+/**
+ * Merge values into the request's view state, when the app has a template
+ * layer. A no-op outside an HTTP render, or in an app with no views.
+ */
+function shareWithView(
+	ctx: WardenContext,
+	values: Record<string, unknown>,
+): void {
+	const view = Reflect.get(Object(ctx), "view");
+	const share = Reflect.get(Object(view), "share");
+	if (typeof share === "function") share.call(view, values);
+}
+
 /**
  * Reuse the request's Authenticator if one is already attached (e.g. `silentAuth`
  * ran first), else build and attach a fresh one. Keeps `ctx.auth` a single
@@ -329,6 +369,10 @@ function ensureAuthenticator(
 	if (ctx.auth instanceof Authenticator) return ctx.auth;
 	const authenticator = new Authenticator(ctx, auth);
 	ctx.auth = authenticator;
+	// Share it with the request's view, as AdonisJS's auth does, so a migrated
+	// template reads `{{ auth.user.email }}` / `@if(auth.isAuthenticated)`
+	// unchanged. Both middlewares funnel through here, so one share covers them.
+	shareWithView(ctx, { auth: authenticator });
 	return authenticator;
 }
 
@@ -405,10 +449,19 @@ export async function initializeBouncer(ctx: WardenContext, next: WardenNext) {
 		? await registry.resolveScope(toScopeContext(ctx))
 		: "global";
 
-	ctx.bouncer = new Bouncer(user, registry?.abilities, registry?.policies, {
+	const bouncer = new Bouncer(user, registry?.abilities, registry?.policies, {
 		scope,
 		resolver,
+		// The REQUEST's resolver, so a policy taking constructor dependencies
+		// gets them — and gets this request's, not the application container's.
+		// It was never passed, so `@inject()` on a policy silently resolved to a
+		// plain `new Policy()` with no dependencies at all.
+		containerResolver: policyResolver(ctx.containerResolver),
 	});
+	ctx.bouncer = bouncer;
+	// Share the checks with the request's view so `@can(...)` resolves them,
+	// as AdonisJS's own middleware does.
+	shareWithView(ctx, bouncer.templateHelpers);
 	await next();
 }
 

package/src/quasar.ts

@@ -27,20 +27,12 @@ function isConnectionSource(value: unknown): value is ConnectionSource {
 
 function isRedisLikeClient(value: unknown): value is RedisLikeClient {
 	if (typeof value !== "object" || value === null) return false;
-	// The commands this driver actually issues. A connection missing one of
-	// them would fail on the first revocation, far from the cause.
-	const required = [
-		"get",
-		"set",
-		"del",
-		"exists",
-		"keys",
-		"sadd",
-		"srem",
-		"smembers",
-		"expire",
-		"ttl",
-	];
+	// The commands this driver actually issues — the whole of `RedisLikeClient`.
+	// A connection missing one would fail on the first revocation, far from the
+	// cause. Nothing more: the driver documents itself as needing only `set`
+	// with an "EX" ttl and `exists`, so demanding sets or key scans here would
+	// reject a client that works perfectly well.
+	const required = ["set", "exists"];
 	return required.every(
 		(name) => typeof Reflect.get(value, name) === "function",
 	);

package/src/sanitize.ts

@@ -0,0 +1,17 @@
+/**
+ * Strip the prototype-pollution keys from a user payload.
+ *
+ * Lives in its own module so `AuthManager` and `Authenticator` do not have to
+ * import each other's values: the manager builds an authenticator, and the
+ * authenticator sanitises — putting both in one file made a runtime cycle.
+ */
+
+import type { UserPayload } from "./AuthManager.js";
+
+export function sanitizePayload(user: UserPayload): void {
+	for (const key of ["__proto__", "constructor", "prototype"]) {
+		if (key in user) {
+			delete (user as Record<string, unknown>)[key];
+		}
+	}
+}

package/src/strategies/ApiKeyStrategy.ts

@@ -6,7 +6,12 @@
  * @implements MISS-8
  */
 
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 
 export interface ApiKeyConfig {
 	headerName?: string;
@@ -42,6 +47,23 @@ export class ApiKeyStrategy implements AuthStrategy {
 		);
 	}
 
+	/**
+	 * The header a test client sends to present `key` (AdonisJS
+	 * `authenticateAsClient`).
+	 *
+	 * Takes the KEY, not a user: an API key is issued out of band, so a test
+	 * seeds one through `findByKey` and hands that same key here — inventing a
+	 * key the resolver has never seen would prove nothing.
+	 */
+	authenticateAsClient(key: string): AuthClientResponse {
+		return {
+			headers: {
+				authorization: `Bearer ${key}`,
+				[this.#headerName]: key,
+			},
+		};
+	}
+
 	async verify(token: string): Promise<AuthResult> {
 		const result = await this.#config.findByKey(token);
 		if (!result) return { authenticated: false, error: "Invalid API key" };

package/src/strategies/BasicAuthStrategy.ts

@@ -0,0 +1,127 @@
+/**
+ * HTTP Basic authentication (AdonisJS `basic_auth` guard).
+ *
+ * The browser prompts for credentials and resends them on every request; there
+ * is no session and nothing to log out of. That makes it the right fit for a
+ * machine-to-machine endpoint or an internal tool behind TLS, and the wrong fit
+ * for a user-facing login — the credentials travel on EVERY request, so without
+ * TLS they are exposed on every one of them.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
+
+export interface BasicAuthConfig {
+	/**
+	 * Resolve a user by the username half of the header, and say whether the
+	 * password matches. Returning null is an unknown user.
+	 */
+	verifyCredentials: (
+		uid: string,
+		password: string,
+	) => Promise<UserPayload | null>;
+	/**
+	 * The realm announced in `WWW-Authenticate`. The browser shows it in its
+	 * prompt, so it should name what is being unlocked.
+	 */
+	realm?: string;
+}
+
+/** The `WWW-Authenticate` value a 401 must carry for the browser to prompt. */
+export function basicAuthChallenge(realm = "Restricted"): string {
+	// The realm is quoted, so a quote inside it would end the field early.
+	return `Basic realm="${realm.replace(/["\\]/g, "")}", charset="UTF-8"`;
+}
+
+/**
+ * Split an `Authorization: Basic` header into its two halves.
+ *
+ * RFC 7617 splits on the FIRST colon: a password may contain colons, a username
+ * may not. Splitting on the last one would silently accept the wrong pair.
+ */
+export function decodeBasicAuth(
+	header: string | undefined,
+): { uid: string; password: string } | null {
+	if (!header) return null;
+	const [scheme, encoded] = header.split(" ");
+	if ((scheme ?? "").toLowerCase() !== "basic" || !encoded) return null;
+	let decoded: string;
+	try {
+		decoded = Buffer.from(encoded, "base64").toString("utf8");
+	} catch {
+		return null;
+	}
+	const separator = decoded.indexOf(":");
+	if (separator === -1) return null;
+	return {
+		uid: decoded.slice(0, separator),
+		password: decoded.slice(separator + 1),
+	};
+}
+
+export class BasicAuthStrategy implements AuthStrategy {
+	name = "basic_auth";
+	readonly #config: BasicAuthConfig;
+
+	constructor(config: BasicAuthConfig) {
+		this.#config = config;
+	}
+
+	/** The challenge to send with a 401 so the browser prompts. */
+	get challenge(): string {
+		return basicAuthChallenge(this.#config.realm);
+	}
+
+	/** Authenticate a `{ uid, password }` pair directly. */
+	async authenticate(
+		credentials: Record<string, unknown>,
+	): Promise<AuthResult> {
+		const uid = credentials.uid ?? credentials.username ?? credentials.email;
+		const password = credentials.password;
+		if (typeof uid !== "string" || typeof password !== "string") {
+			return { authenticated: false, error: "Invalid credentials" };
+		}
+		const user = await this.#config.verifyCredentials(uid, password);
+		// One message for an unknown user and for a wrong password: telling them
+		// apart turns the endpoint into a username oracle.
+		if (!user) return { authenticated: false, error: "Invalid credentials" };
+		return { authenticated: true, user };
+	}
+
+	/** Authenticate from the raw `Authorization` header value. */
+	async verify(header: string): Promise<AuthResult> {
+		const decoded = decodeBasicAuth(header);
+		if (!decoded) return { authenticated: false, error: "Invalid credentials" };
+		return this.authenticate(decoded);
+	}
+
+	/**
+	 * Build the header a client sends (AdonisJS `authenticateAsClient`) — what a
+	 * test uses to act as a user without reproducing the encoding by hand.
+	 */
+	authenticateAsClient(uid: string, password: string): AuthClientResponse {
+		const encoded = Buffer.from(`${uid}:${password}`, "utf8").toString(
+			"base64",
+		);
+		return { headers: { authorization: `Basic ${encoded}` } };
+	}
+}
+
+/**
+ * Compare two secrets without leaking how far they matched.
+ *
+ * Exposed because an app implementing `verifyCredentials` against a plaintext
+ * shared secret needs it — a plain `===` returns sooner on an early mismatch,
+ * and that difference is measurable.
+ */
+export function safeCompare(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);
+}

package/src/strategies/JwtStrategy.ts

@@ -4,7 +4,12 @@
  */
 
 import { randomBytes, randomUUID } from "node:crypto";
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 import { nativeWarden } from "../native.js";
 import type { TokenBlacklist } from "../TokenBlacklist.js";
 
@@ -214,6 +219,18 @@ export class JwtStrategy implements AuthStrategy {
 	 * Returns `true` when the token was added to the blacklist, `false` when
 	 * the token is already expired (revocation is unnecessary) or unparseable.
 	 */
+	/**
+	 * The header a test client sends to be `user` (AdonisJS
+	 * `authenticateAsClient`).
+	 *
+	 * Signs a real token with the configured secret, so the request travels the
+	 * SAME verification path as production — a test that forges its own header
+	 * proves only that the forgery works.
+	 */
+	authenticateAsClient(user: UserPayload): AuthClientResponse {
+		return { headers: { authorization: `Bearer ${this.signToken(user)}` } };
+	}
+
 	async revoke(token: string): Promise<boolean> {
 		if (!this.#blacklist) {
 			throw new Error(