@c9up/warden 0.1.16 → 0.1.18

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

@@ -0,0 +1,78 @@
+/**
+ * Resolving a Redis connection by name, from `@c9up/quasar`.
+ *
+ * Warden does not depend on quasar: it is an optional peer, and this module
+ * never imports it statically. The specifier is built at runtime so the
+ * TypeScript build stays free of it too — a hard type import would make echo
+ * unbuildable for anyone whose blacklist is in memory.
+ *
+ * The shape is checked before use rather than asserted, the same way warden
+ * duck-types its host framework.
+ */
+
+import type { RedisLikeClient } from "./RedisBlacklistDriver.js";
+
+/** The slice of quasar's manager this needs: a connection, by name. */
+interface ConnectionSource {
+	connection(name?: string): unknown;
+}
+
+function isConnectionSource(value: unknown): value is ConnectionSource {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "connection") === "function"
+	);
+}
+
+function isRedisLikeClient(value: unknown): value is RedisLikeClient {
+	if (typeof value !== "object" || value === null) return false;
+	// 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",
+	);
+}
+
+/**
+ * A resolver for `new RedisBlacklistDriver(quasarConnection())` — quasar is
+ * loaded on the first revocation check, not at config time.
+ */
+export function quasarConnection(
+	name?: string,
+): () => Promise<RedisLikeClient> {
+	return async () => {
+		const specifier = "@c9up/quasar/services/main";
+		let loaded: unknown;
+		try {
+			loaded = await import(/* @vite-ignore */ specifier);
+		} catch (cause) {
+			throw new Error(
+				`Warden: the "${name ?? "default"}" blacklist asks for a quasar connection, but @c9up/quasar is not installed.\n` +
+					"  pnpm add @c9up/quasar",
+				{ cause },
+			);
+		}
+
+		const manager = isConnectionSource(loaded)
+			? loaded
+			: Reflect.get(Object(loaded), "default");
+		if (!isConnectionSource(manager)) {
+			throw new Error(
+				"Warden: @c9up/quasar/services/main did not expose a connection() manager",
+			);
+		}
+
+		const connection = manager.connection(name);
+		if (!isRedisLikeClient(connection)) {
+			throw new Error(
+				`Warden: quasar connection "${name ?? "default"}" does not carry the commands this blacklist needs`,
+			);
+		}
+		return connection;
+	};
+}

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(

package/src/strategies/SessionStrategy.ts

@@ -7,8 +7,19 @@
  * @implements MISS-7
  */
 
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 import { WardenError } from "../errors.js";
+import {
+	decodeTokenValue,
+	mintRememberMeToken,
+	type RememberMeTokenDriver,
+	verifyAndRecycleRememberMeToken,
+} from "../RememberMeToken.js";
 
 export interface SessionStore {
 	get(key: string): unknown;
@@ -33,8 +44,27 @@ export interface SessionStore {
 export interface SessionStrategyConfig {
 	sessionKey?: string;
 	findUser: (id: string | number) => Promise<UserPayload | null>;
+	/**
+	 * Turn on "keep me signed in". Adonis calls the equivalent flag
+	 * `useRememberMeTokens`; without a driver there is nowhere to persist the
+	 * token, so passing one IS the opt-in.
+	 */
+	rememberMeTokens?: RememberMeTokenDriver;
+	/**
+	 * How long a remember-me token lives. Adonis defaults to two years, and a
+	 * number here is SECONDS (`durationToSeconds` semantics).
+	 */
+	rememberMeAge?: number;
+	/**
+	 * Cookie name holding the token. Adonis derives `remember_<guard>`; the
+	 * default matches the `web` guard an app is most likely migrating.
+	 */
+	rememberMeCookieName?: string;
 }
 
+/** Two years, Adonis' `rememberMeTokensAge` default. */
+const DEFAULT_REMEMBER_AGE_SECONDS = 63_072_000;
+
 export class SessionStrategy implements AuthStrategy {
 	name = "session";
 	#config: SessionStrategyConfig;
@@ -45,6 +75,71 @@ export class SessionStrategy implements AuthStrategy {
 		this.#sessionKey = config.sessionKey ?? "auth_user_id";
 	}
 
+	/** The cookie the remember-me token travels in. */
+	get rememberMeCookieName(): string {
+		return this.#config.rememberMeCookieName ?? "remember_web";
+	}
+
+	/** Whether "keep me signed in" is wired at all. */
+	get usesRememberMeTokens(): boolean {
+		return this.#config.rememberMeTokens !== undefined;
+	}
+
+	#rememberMeAge(): number {
+		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: UserPayload): Promise<string | null> {
+		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: unknown,
+	): Promise<{ user: UserPayload; cookieValue: string } | null> {
+		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: unknown): Promise<void> {
+		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: { email: string; password: string },
@@ -104,7 +199,23 @@ export class SessionStrategy implements AuthStrategy {
 		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: UserPayload): AuthClientResponse {
+		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: SessionStore): Promise<void> {
 		session.forget(this.#sessionKey);
 	}