@c9up/warden 0.1.17 → 0.1.19

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

@@ -18,7 +18,13 @@ import type { EffectivePermissions, Scope } from "../rights/types.js";
 import { AbilitiesBuilder } from "./AbilitiesBuilder.js";
 import { AuthorizationResponse } from "./AuthorizationResponse.js";
 import type { BasePolicy } from "./BasePolicy.js";
-import { evaluate, isAction, throwAuthorizationFailure } from "./evaluate.js";
+import {
+	defaultResponseBuilder,
+	evaluate,
+	isAction,
+	type ResponseBuilder,
+	throwAuthorizationFailure,
+} from "./evaluate.js";
 import { PolicyAuthorizer } from "./PolicyAuthorizer.js";
 import { emptyPermissions } from "./policyContext.js";
 import type {
@@ -31,6 +37,20 @@ import type {
 } from "./types.js";
 
 export class Bouncer {
+	/**
+	 * How a bare boolean from an ability or a policy becomes an
+	 * {@link AuthorizationResponse} (AdonisJS `Bouncer.responseBuilder`).
+	 *
+	 * Replace it once at boot to give every `return false` a house message and
+	 * status instead of a naked 403:
+	 *
+	 * ```ts
+	 * Bouncer.responseBuilder = (value) =>
+	 *   value === false ? AuthorizationResponse.deny('Nope', 404) : normalizeResponse(value)
+	 * ```
+	 */
+	static responseBuilder: ResponseBuilder = defaultResponseBuilder;
+
 	readonly #userOrResolver: UserPayload | (() => UserPayload | null) | null;
 	/** Lazily-resolved user cache (`undefined` until `#getUser` runs). */
 	#user: UserPayload | null | undefined;
@@ -38,7 +58,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 +78,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 +190,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 =
@@ -171,6 +251,7 @@ export class Bouncer {
 			this.#scope,
 			() => this.#resolvePermissions(),
 			this.#emitter,
+			Bouncer.responseBuilder,
 		);
 	}
 
@@ -185,10 +266,17 @@ export class Bouncer {
 	}
 
 	/** Emit `authorization:finished` when an emitter is wired (no-op otherwise). */
-	#emit(action: string, response: AuthorizationResponse): void {
+	#emit(
+		action: string,
+		response: AuthorizationResponse,
+		parameters: unknown[],
+	): void {
 		this.#emitter?.emit("authorization:finished", {
 			user: this.#getUser(),
 			action,
+			// What the check was ABOUT. AdonisJS carries it, and without it an
+			// audit log can say "Ada was denied editPost" but never which post.
+			parameters,
 			response,
 		});
 	}
@@ -261,8 +349,9 @@ export class Bouncer {
 			allowGuest: resolved.allowGuest,
 			run: (user) => resolved.execute(user, ...args),
 			args,
+			responseBuilder: Bouncer.responseBuilder,
 		});
-		this.#emit(action, response);
+		this.#emit(action, response, args);
 		return response;
 	}
 

package/src/bouncer/PolicyAuthorizer.ts

@@ -16,6 +16,7 @@ import {
 	type Action,
 	evaluate,
 	isAction,
+	type ResponseBuilder,
 	throwAuthorizationFailure,
 } from "./evaluate.js";
 import { emptyPermissions, setPolicyContext } from "./policyContext.js";
@@ -69,7 +70,8 @@ export class PolicyAuthorizer {
 	readonly #factory: () => Promise<BasePolicy>;
 	readonly #scope: Scope;
 	readonly #resolvePermissions: () => Promise<EffectivePermissions>;
-	readonly #emitter: BouncerEmitter | undefined;
+	#emitter: BouncerEmitter | undefined;
+	readonly #responseBuilder: ResponseBuilder | undefined;
 
 	constructor(
 		user: UserPayload | null,
@@ -78,12 +80,14 @@ export class PolicyAuthorizer {
 		resolvePermissions: () => Promise<EffectivePermissions> = () =>
 			Promise.resolve(emptyPermissions(scope)),
 		emitter?: BouncerEmitter,
+		responseBuilder?: ResponseBuilder,
 	) {
 		this.#user = user;
 		this.#factory = factory;
 		this.#scope = scope;
 		this.#resolvePermissions = resolvePermissions;
 		this.#emitter = emitter;
+		this.#responseBuilder = responseBuilder;
 	}
 
 	/** Run a check and resolve to the full response (D8 — fresh policy per check). */
@@ -106,15 +110,30 @@ export class PolicyAuthorizer {
 			args,
 			before: policy.before?.bind(policy),
 			after: policy.after?.bind(policy),
+			responseBuilder: this.#responseBuilder,
 		});
 		this.#emitter?.emit("authorization:finished", {
 			user: this.#user,
 			action,
+			// Same payload as an ability check: which resource the decision was
+			// about, not just that a decision happened.
+			parameters: args,
 			response,
 		});
 		return response;
 	}
 
+	/**
+	 * Swap the event sink after construction (AdonisJS `setEmitter`).
+	 *
+	 * The Bouncer passes its own down, but an authorizer built directly — a
+	 * test, a console command — had no way to be given one.
+	 */
+	setEmitter(emitter?: BouncerEmitter): this {
+		this.#emitter = emitter;
+		return this;
+	}
+
 	/** True iff the action is authorized. Never throws on denial. */
 	async allows(action: string, ...args: unknown[]): Promise<boolean> {
 		return (await this.execute(action, ...args)).authorized;

package/src/bouncer/evaluate.ts

@@ -19,14 +19,31 @@ export type Action = (
 	...args: unknown[]
 ) => AuthorizerResponse;
 
-/** Boolean sugar → response; an explicit response passes through (D7). */
-export function normalizeResponse(
+/** Turns whatever an ability returned into an {@link AuthorizationResponse}. */
+export type ResponseBuilder = (
 	value: boolean | AuthorizationResponse,
-): AuthorizationResponse {
+) => AuthorizationResponse;
+
+/** The default: boolean sugar → response; an explicit response passes through (D7). */
+export const defaultResponseBuilder: ResponseBuilder = (value) => {
 	if (value instanceof AuthorizationResponse) {
 		return value;
 	}
 	return value ? AuthorizationResponse.allow() : AuthorizationResponse.deny();
+};
+
+/**
+ * Boolean sugar → response, through whatever builder is installed.
+ *
+ * `Bouncer.responseBuilder` replaces it app-wide, which is how you give every
+ * bare `return false` a house message and status instead of a naked 403
+ * (AdonisJS `Bouncer.responseBuilder`).
+ */
+export function normalizeResponse(
+	value: boolean | AuthorizationResponse,
+	builder: ResponseBuilder = defaultResponseBuilder,
+): AuthorizationResponse {
+	return builder(value);
 }
 
 /**
@@ -71,8 +88,11 @@ export async function evaluate(params: {
 		result: AuthorizationResponse,
 		...args: unknown[]
 	) => HookResponse;
+	/** Overrides how a bare boolean becomes a response. */
+	responseBuilder?: ResponseBuilder;
 }): Promise<AuthorizationResponse> {
 	const { user, action, allowGuest, run, args, before, after } = params;
+	const builder = params.responseBuilder ?? defaultResponseBuilder;
 
 	let response: AuthorizationResponse | undefined;
 
@@ -80,7 +100,7 @@ export async function evaluate(params: {
 	if (before) {
 		const early = await before(user, action, ...args);
 		if (early !== undefined) {
-			response = normalizeResponse(early);
+			response = normalizeResponse(early, builder);
 		}
 	}
 
@@ -89,7 +109,7 @@ export async function evaluate(params: {
 		if (user === null && !allowGuest) {
 			response = AuthorizationResponse.deny();
 		} else {
-			response = normalizeResponse(await run(user));
+			response = normalizeResponse(await run(user), builder);
 		}
 	}
 
@@ -98,7 +118,7 @@ export async function evaluate(params: {
 	if (after) {
 		const override = await after(user, action, response, ...args);
 		if (override !== undefined) {
-			response = normalizeResponse(override);
+			response = normalizeResponse(override, builder);
 		}
 	}
 

package/src/bouncer/types.ts

@@ -23,8 +23,10 @@ export interface PolicyContainerResolver {
 
 /**
  * Agnostic event sink (Adonis `Bouncer.emitter`). When present, an
- * `authorization:finished` event fires after every ability/policy evaluation with
- * `{ user, action, response }`. No-op when absent.
+ * `authorization:finished` event fires after every ability/policy evaluation
+ * with `{ user, action, parameters, response }` (AdonisJS `BouncerEvents`).
+ * `parameters` are the arguments the check ran against — an audit log needs
+ * them to say WHICH resource was refused. No-op when absent.
  */
 export interface BouncerEmitter {
 	emit(event: string, payload: unknown): void;

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,11 @@ export type {
 	AuthStrategy,
 	UserPayload,
 } from "./AuthManager.js";
-export { AuthManager } from "./AuthManager.js";
+export {
+	AuthManager,
+	authEventPrefix,
+	type WardenEmitter,
+} from "./AuthManager.js";
 export type { AuthRateLimiterConfig } from "./AuthRateLimiter.js";
 export { AuthRateLimiter } from "./AuthRateLimiter.js";
 export { AbilitiesBuilder } from "./bouncer/AbilitiesBuilder.js";
@@ -41,6 +45,7 @@ export type {
 export type { GuardFactory, WardenConfig } from "./config.js";
 export {
 	apiKeyGuard,
+	basicAuthGuard,
 	defineConfig,
 	jwtGuard,
 	sessionGuard,
@@ -98,8 +103,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,
@@ -130,6 +136,20 @@ export {
 	generateRefreshToken,
 	MemoryRefreshTokenDriver,
 } from "./RefreshTokenStore.js";
+export {
+	DEFAULT_SECRET_LENGTH,
+	decodeTokenValue,
+	encodeTokenValue,
+	hashSecret,
+	MemoryRememberMeTokenDriver,
+	type MintedRememberMeToken,
+	mintRememberMeToken,
+	RememberMeToken,
+	type RememberMeTokenDriver,
+	type StoredRememberMeToken,
+	safeCompareHashes,
+	verifyAndRecycleRememberMeToken,
+} from "./RememberMeToken.js";
 export type {
 	BlacklistDegradeEvent,
 	ResilientBlacklistConfig,
@@ -143,8 +163,16 @@ export type {
 	Scope,
 } from "./rights/types.js";
 export { scopeKey } from "./rights/types.js";
+export { Secret } from "./Secret.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 ─────────────────────────────────────────────────