@c9up/warden 0.1.18 → 0.1.20

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;
@@ -231,6 +251,7 @@ export class Bouncer {
 			this.#scope,
 			() => this.#resolvePermissions(),
 			this.#emitter,
+			Bouncer.responseBuilder,
 		);
 	}
 
@@ -245,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,
 		});
 	}
@@ -321,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/index.ts

@@ -4,6 +4,8 @@
  * @implements FR48, FR49, FR50, FR51, FR52, FR53
  */
 
+import "./augmentations.js";
+
 export type { AuthAttempt, ExtractedCredentials } from "./Authenticator.js";
 export {
 	API_KEY_GUARD_NAMES,
@@ -17,7 +19,11 @@ export type {
 	AuthStrategy,
 	UserPayload,
 } from "./AuthManager.js";
-export { AuthManager, type WardenEmitter } 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";
@@ -140,6 +146,7 @@ export {
 	MemoryRememberMeTokenDriver,
 	type MintedRememberMeToken,
 	mintRememberMeToken,
+	RememberMeToken,
 	type RememberMeTokenDriver,
 	type StoredRememberMeToken,
 	safeCompareHashes,
@@ -158,6 +165,7 @@ 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";

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

@@ -69,6 +69,9 @@ export class SessionStrategy implements AuthStrategy {
 	name = "session";
 	#config: SessionStrategyConfig;
 	#sessionKey: string;
+	#viaRemember = false;
+	#loggedOut = false;
+	#attemptedViaRemember = false;
 
 	constructor(config: SessionStrategyConfig) {
 		this.#config = config;
@@ -85,6 +88,47 @@ export class SessionStrategy implements AuthStrategy {
 		return this.#config.rememberMeTokens !== undefined;
 	}
 
+	/**
+	 * Whether the current user was revived from a remember-me cookie rather
+	 * than signing in (AdonisJS `viaRemember`).
+	 *
+	 * This is the distinction that lets an app demand the password again before
+	 * something sensitive — changing an email, spending money, deleting an
+	 * account. Nothing reported it, so a session restored from a cookie looked
+	 * exactly like one where the user had just typed their password.
+	 */
+	get viaRemember(): boolean {
+		return this.#viaRemember;
+	}
+
+	/**
+	 * Whether a remember-me token was even tried on this request (AdonisJS
+	 * `attemptedViaRemember`) — true whether or not it worked.
+	 */
+	get attemptedViaRemember(): boolean {
+		return this.#attemptedViaRemember;
+	}
+
+	/**
+	 * Whether `logout()` ran on this guard (AdonisJS `isLoggedOut`).
+	 *
+	 * A handler that logs out and then keeps working — clearing a cart, writing
+	 * an audit line — could not tell that the session was already gone.
+	 */
+	get isLoggedOut(): boolean {
+		return this.#loggedOut;
+	}
+
+	/** The session key the user id is stored under (AdonisJS `sessionKeyName`). */
+	get sessionKeyName(): string {
+		return this.#sessionKey;
+	}
+
+	/** The cookie key the remember-me token is stored under (AdonisJS `rememberMeKeyName`). */
+	get rememberMeKeyName(): string {
+		return this.rememberMeCookieName;
+	}
+
 	#rememberMeAge(): number {
 		return this.#config.rememberMeAge ?? DEFAULT_REMEMBER_AGE_SECONDS;
 	}
@@ -114,6 +158,7 @@ export class SessionStrategy implements AuthStrategy {
 	): Promise<{ user: UserPayload; cookieValue: string } | null> {
 		const driver = this.#config.rememberMeTokens;
 		if (!driver) return null;
+		this.#attemptedViaRemember = true;
 
 		const recycled = await verifyAndRecycleRememberMeToken(
 			driver,
@@ -125,6 +170,7 @@ export class SessionStrategy implements AuthStrategy {
 		const user = await this.#config.findUser(recycled.userId);
 		if (!user) return null;
 
+		this.#viaRemember = true;
 		return { user, cookieValue: recycled.value };
 	}
 
@@ -197,6 +243,11 @@ export class SessionStrategy implements AuthStrategy {
 	async login(user: UserPayload, session: SessionStore): Promise<void> {
 		session.regenerate();
 		session.put(this.#sessionKey, user.id);
+		this.#loggedOut = false;
+		// A password was typed: this session is no longer "via remember", even
+		// if a cookie was tried earlier in the same request. Without the reset
+		// the flag would stay true and a re-auth prompt would never fire.
+		this.#viaRemember = false;
 	}
 
 	/**
@@ -218,5 +269,8 @@ export class SessionStrategy implements AuthStrategy {
 	 */
 	async logout(session: SessionStore): Promise<void> {
 		session.forget(this.#sessionKey);
+		this.#viaRemember = false;
+		this.#attemptedViaRemember = false;
+		this.#loggedOut = true;
 	}
 }