@c9up/warden 0.1.18 → 0.1.19

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

@@ -17,7 +17,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 +144,7 @@ export {
 	MemoryRememberMeTokenDriver,
 	type MintedRememberMeToken,
 	mintRememberMeToken,
+	RememberMeToken,
 	type RememberMeTokenDriver,
 	type StoredRememberMeToken,
 	safeCompareHashes,
@@ -158,6 +163,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;
 	}
 }