@c9up/warden 0.1.13 → 0.1.15

package/src/AuthManager.ts

@@ -8,6 +8,7 @@ import { WardenError } from "./errors.js";
 import { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
 import { RightsResolver } from "./rights/RightsResolver.js";
 import type { EffectivePermissions, Scope } from "./rights/types.js";
+import type { SessionStore } from "./strategies/SessionStrategy.js";
 
 export interface UserPayload {
 	id: string;
@@ -36,15 +37,32 @@ export interface AuthStrategy {
 	verify(token: string, context?: Record<string, unknown>): Promise<AuthResult>;
 }
 
+/**
+ * AuthManager configuration. Two equivalent forms are accepted:
+ *
+ *   - AdonisJS form (preferred): `{ default, guards }` — `default` names the
+ *     guard used when none is specified, `guards` maps guard name → strategy.
+ *   - Legacy form: `{ defaultStrategy, strategies }` — kept working so existing
+ *     call sites and tests need no change.
+ *
+ * Exactly one of each pair must be supplied. Internally normalised to the
+ * AdonisJS names (`default` / `guards`).
+ */
 export interface AuthConfig {
-	defaultStrategy: string;
-	strategies: Record<string, AuthStrategy>;
+	/** AdonisJS name for the default guard. */
+	default?: string;
+	/** AdonisJS name for the guard map (name → strategy). */
+	guards?: Record<string, AuthStrategy>;
+	/** Legacy alias for {@link AuthConfig.default}. */
+	defaultStrategy?: string;
+	/** Legacy alias for {@link AuthConfig.guards}. */
+	strategies?: Record<string, AuthStrategy>;
 	/**
 	 * The rights resolver backing the coarse RBAC helpers (Epic 56). When
 	 * absent, a default `RightsResolver(new MemoryRightsStore())` is used so
-	 * `new AuthManager({ defaultStrategy, strategies })` keeps working — with
-	 * an empty store, payload roles still fold in (D2) and permissions are
-	 * empty (token `user.permissions` is not an input — D1).
+	 * `new AuthManager({ default, guards })` keeps working — with an empty
+	 * store, payload roles still fold in (D2) and permissions are empty (token
+	 * `user.permissions` is not an input — D1).
 	 */
 	rights?: RightsResolver;
 }
@@ -69,32 +87,44 @@ function isTokenIssuer(
  * Manages authentication strategies and provides guard/permission checks.
  */
 export class AuthManager {
-	private strategies: Map<string, AuthStrategy> = new Map();
-	private defaultStrategy: string;
+	// AdonisJS names: `guards` (name → strategy) and `default` (the guard used
+	// when none is named). Renamed from the previous `strategies`/`defaultStrategy`.
+	private guards: Map<string, AuthStrategy> = new Map();
+	private default: string;
 	private readonly rights: RightsResolver;
 
 	constructor(config: AuthConfig) {
-		this.defaultStrategy = config.defaultStrategy;
+		// Normalise the two accepted forms — AdonisJS `{ default, guards }` and
+		// the legacy `{ defaultStrategy, strategies }` — to the AdonisJS names.
+		const guards = config.guards ?? config.strategies;
+		const defaultGuard = config.default ?? config.defaultStrategy;
+		if (!guards || defaultGuard === undefined) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"AuthManager: config must supply `default` + `guards` (or the legacy `defaultStrategy` + `strategies`).",
+			);
+		}
+		this.default = defaultGuard;
 		this.rights = config.rights ?? new RightsResolver(new MemoryRightsStore());
-		for (const [name, strategy] of Object.entries(config.strategies)) {
-			this.strategies.set(name, strategy);
+		for (const [name, strategy] of Object.entries(guards)) {
+			this.guards.set(name, strategy);
 		}
-		// Fail-fast at construction: an AuthManager with zero strategies
-		// is a configuration bug. Previously, an empty `strategies: {}`
-		// passed the constructor cleanly and the first protected request
-		// crashed at runtime when `getStrategy('jwt')` threw — opaque 401
-		// or 500 instead of a boot-time INVALID_CONFIG that points the
-		// operator at the missing `config.auth.jwt` (or other strategy).
-		if (Object.keys(config.strategies).length === 0) {
+		// Fail-fast at construction: an AuthManager with zero guards is a
+		// configuration bug. Previously, an empty `guards: {}` passed the
+		// constructor cleanly and the first protected request crashed at
+		// runtime when `getStrategy('jwt')` threw — opaque 401 or 500 instead
+		// of a boot-time INVALID_CONFIG that points the operator at the missing
+		// `config.auth.jwt` (or other guard).
+		if (this.guards.size === 0) {
 			throw new WardenError(
 				"INVALID_CONFIG",
-				`AuthManager: no authentication strategies registered. Configure at least one strategy (e.g. config.warden.auth.jwt) before booting WardenProvider.`,
+				`AuthManager: no authentication guards registered. Configure at least one guard (e.g. config.warden.auth.jwt) before booting WardenProvider.`,
 			);
 		}
-		if (!this.strategies.has(config.defaultStrategy)) {
+		if (!this.guards.has(defaultGuard)) {
 			throw new WardenError(
 				"INVALID_CONFIG",
-				`defaultStrategy '${config.defaultStrategy}' is not present in strategies`,
+				`default guard '${defaultGuard}' is not present in guards`,
 			);
 		}
 	}
@@ -164,7 +194,7 @@ export class AuthManager {
 		if (!isTokenIssuer(strategy)) {
 			throw new WardenError(
 				"STRATEGY_CANNOT_ISSUE",
-				`Auth strategy '${strategyName ?? this.defaultStrategy}' cannot issue tokens.`,
+				`Auth strategy '${strategyName ?? this.default}' cannot issue tokens.`,
 				{
 					hint: "issueFor() needs a token-minting strategy (e.g. JwtStrategy with signToken). Session / API-key strategies don't mint tokens.",
 				},
@@ -228,8 +258,8 @@ export class AuthManager {
 
 	/** Get a registered strategy by name. */
 	getStrategy(name?: string): AuthStrategy {
-		const strategyName = name ?? this.defaultStrategy;
-		const strategy = this.strategies.get(strategyName);
+		const strategyName = name ?? this.default;
+		const strategy = this.guards.get(strategyName);
 		if (!strategy) {
 			throw new WardenError(
 				"STRATEGY_NOT_FOUND",
@@ -243,24 +273,91 @@ export class AuthManager {
 	}
 
 	/**
-	 * Name of the default strategy (Adonis's "default guard"). Used by
-	 * `silentAuth` to pick which strategy to attempt when a route declares none.
+	 * Name of the default guard (Adonis's "default guard"). Used by `silentAuth`
+	 * and the {@link Authenticator} to pick which guard to attempt when a route
+	 * declares none.
 	 */
 	get defaultStrategyName(): string {
-		return this.defaultStrategy;
+		return this.default;
 	}
 
 	/** Register a new strategy at runtime. */
 	registerStrategy(name: string, strategy: AuthStrategy): void {
-		this.strategies.set(name, strategy);
+		this.guards.set(name, strategy);
 	}
 
 	/** Get all registered strategy names. */
 	getStrategyNames(): string[] {
-		return [...this.strategies.keys()];
+		return [...this.guards.keys()];
+	}
+
+	/**
+	 * Log a user in through a session-capable guard (AdonisJS
+	 * `auth.use('web').login(user)` parity). Delegates to the guard's own
+	 * `login()` — for `SessionStrategy` this rotates the session id (session
+	 * fixation defence) and stores the user id. Throws if the resolved guard
+	 * cannot log in (e.g. JWT / API-key guards, which are stateless).
+	 *
+	 * Fixes the misleading `SessionStrategy.authenticate()` sentinel that
+	 * pointed at a then-nonexistent `authManager.login()` (bug-3261).
+	 */
+	async login(
+		user: UserPayload,
+		session: SessionStore,
+		strategyName?: string,
+	): Promise<void> {
+		const strategy = this.getStrategy(strategyName);
+		if (!isLoginCapable(strategy)) {
+			throw new WardenError(
+				"STRATEGY_CANNOT_LOGIN",
+				`Auth strategy '${strategyName ?? this.default}' does not support session login.`,
+				{
+					hint: "login()/logout() need a stateful guard (e.g. SessionStrategy). JWT / API-key guards are stateless — mint a token with issueFor() instead.",
+				},
+			);
+		}
+		await strategy.login(user, session);
+	}
+
+	/**
+	 * Log a user out of a session-capable guard (AdonisJS `auth.use('web').logout()`
+	 * parity). Delegates to the guard's `logout()`. Throws if the resolved guard
+	 * cannot log out.
+	 */
+	async logout(session: SessionStore, strategyName?: string): Promise<void> {
+		const strategy = this.getStrategy(strategyName);
+		if (!isLoginCapable(strategy)) {
+			throw new WardenError(
+				"STRATEGY_CANNOT_LOGIN",
+				`Auth strategy '${strategyName ?? this.default}' does not support session logout.`,
+			);
+		}
+		await strategy.logout(session);
 	}
 }
 
+/** A guard that can start/stop a session for a resolved user (e.g. SessionStrategy). */
+interface LoginCapable {
+	login(user: UserPayload, session: SessionStore): Promise<void>;
+	logout(session: SessionStore): Promise<void>;
+}
+
+/**
+ * Capability check for {@link AuthManager.login}/{@link AuthManager.logout}.
+ * `login`/`logout` are not on the base `AuthStrategy` contract (only stateful
+ * guards implement them), so narrow via `in` + `typeof` — no cast.
+ */
+function isLoginCapable(
+	strategy: AuthStrategy,
+): strategy is AuthStrategy & LoginCapable {
+	return (
+		"login" in strategy &&
+		typeof strategy.login === "function" &&
+		"logout" in strategy &&
+		typeof strategy.logout === "function"
+	);
+}
+
 /** Strip dangerous prototype-pollution keys from user payload. */
 /**
  * Strip prototype-pollution keys from a user payload before it's

package/src/Authenticator.ts

@@ -0,0 +1,385 @@
+/**
+ * Authenticator — a PER-REQUEST authentication contract (AdonisJS
+ * `@adonisjs/auth` `Authenticator` parity), attached as `ctx.auth`.
+ *
+ * Why it exists: before this, `ctx.auth` was a plain data object with no
+ * methods, so an INLINE route handler (`router.post('/login', handler)`) had no
+ * way to authenticate on demand — only the `@Guard` decorator path worked, and
+ * that reads `ctx.route.controller/action`, which inline/functional routes don't
+ * expose. This contract makes `await ctx.auth.authenticate()` /
+ * `ctx.auth.use('session').login(user)` work anywhere, exactly like Adonis.
+ *
+ * Warden stays agnostic: the Authenticator is built from the {@link AuthManager}
+ * (resolved via `ctx.containerResolver`) + the request `ctx`; it never imports
+ * `@c9up/ream`.
+ */
+
+import {
+	type AuthManager,
+	type AuthResult,
+	type AuthStrategy,
+	sanitizePayload,
+	type UserPayload,
+} from "./AuthManager.js";
+import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
+import type { WardenContext } from "./middleware.js";
+import type { SessionStore } from "./strategies/SessionStrategy.js";
+
+/**
+ * Guard names Warden accepts for the API-key / access-tokens driver. AdonisJS
+ * names the driver `access_tokens`; the legacy `api-key` spelling stays valid so
+ * existing `@Guard('api-key')` routes and configs keep working.
+ */
+export const API_KEY_GUARD_NAMES: readonly string[] = [
+	"access_tokens",
+	"api-key",
+];
+
+interface StrategyWithContext extends AuthStrategy {
+	verifyWithContext(token: string, ctx: unknown): Promise<AuthResult>;
+}
+
+function hasVerifyWithContext(
+	strategy: AuthStrategy,
+): strategy is StrategyWithContext {
+	return (
+		typeof (strategy as StrategyWithContext).verifyWithContext === "function"
+	);
+}
+
+/** The credentials Warden extracts from a request, independent of guard list. */
+export interface ExtractedCredentials {
+	bearerToken: string;
+	apiKey: string;
+	session: SessionStore | undefined;
+}
+
+/**
+ * Resolve the header the API-key guard reads its key from. Prefers the
+ * registered guard's `headerName` (under either accepted guard name), else the
+ * `x-api-key` default. Never throws.
+ */
+function resolveApiKeyHeader(auth: AuthManager): string {
+	for (const name of API_KEY_GUARD_NAMES) {
+		try {
+			const s = auth.getStrategy(name);
+			const header = "headerName" in s ? s.headerName : undefined;
+			if (typeof header === "string" && header.length > 0) return header;
+		} catch {
+			// Guard not registered under this name — try the next.
+		}
+	}
+	return "x-api-key";
+}
+
+/**
+ * Extract the request's credentials once — a Bearer token, an API key (read from
+ * the configured header, matched case-insensitively), and the session store.
+ * Shared by `wardenMiddleware`, `silentAuth`, and the Authenticator so all three
+ * read credentials identically.
+ */
+export function extractCredentials(
+	ctx: WardenContext,
+	auth: AuthManager,
+): ExtractedCredentials {
+	const headers = ctx.request.headers();
+	const authHeader = headers.authorization ?? "";
+	const bearerToken = authHeader.startsWith("Bearer ")
+		? authHeader.slice(7)
+		: "";
+	// HTTP header names are case-insensitive; runtimes lowercase incoming keys,
+	// so normalise the configured header name before the lookup.
+	const apiKey = headers[resolveApiKeyHeader(auth).toLowerCase()] ?? "";
+	return { bearerToken, apiKey, session: ctx.session };
+}
+
+/** Outcome of {@link tryAuthenticate}. */
+export interface AuthAttempt {
+	result: AuthResult | null;
+	/** Name of the guard that authenticated (only when `result.authenticated`). */
+	viaGuard?: string;
+	attemptCount: number;
+	crashCount: number;
+}
+
+/**
+ * Try each declared guard in order — session guards via `verifyWithContext()`,
+ * others via `verify(token)` with native-first credential fallback.
+ * Distinguishes crashes (strategy threw / `strategyCrash`) from credential
+ * rejections so the caller can return 500 vs 401.
+ */
+export async function tryAuthenticate(
+	auth: AuthManager,
+	strategies: string[],
+	creds: {
+		bearerToken: string;
+		apiKey: string;
+		session: SessionStore | undefined;
+		hasSessionStrategy: boolean;
+	},
+): Promise<AuthAttempt> {
+	const { bearerToken, apiKey, session } = creds;
+	let result: AuthResult | null = null;
+	let viaGuard: string | undefined;
+	let attemptCount = 0;
+	let crashCount = 0;
+	for (const strategyName of strategies) {
+		try {
+			let r: AuthResult;
+			if (strategyName === "session") {
+				const strategy = auth.getStrategy(strategyName);
+				const verifyWithContext =
+					strategy && hasVerifyWithContext(strategy)
+						? strategy.verifyWithContext
+						: undefined;
+				if (verifyWithContext) {
+					attemptCount++;
+					r = await verifyWithContext.call(strategy, "", { session });
+					// The session path bypasses AuthManager.verify(), so apply the
+					// same prototype-pollution guard JWT / api-key users get there.
+					if (r.user) sanitizePayload(r.user);
+				} else {
+					continue;
+				}
+			} else {
+				// Native-first credential, other transport as fallback so a
+				// single-credential client still authenticates (and an invalid
+				// Bearer no longer masks a valid API key for the api-key guard).
+				const credential = API_KEY_GUARD_NAMES.includes(strategyName)
+					? apiKey || bearerToken
+					: bearerToken || apiKey;
+				if (!credential) continue;
+				attemptCount++;
+				r = await auth.verify(credential, strategyName);
+			}
+			if (r.authenticated) {
+				result = r;
+				viaGuard = strategyName;
+				break;
+			}
+			if (r.strategyCrash === true) {
+				crashCount++;
+				console.error(
+					`[warden] strategy '${strategyName}' threw during verify(): ${r.error ?? "unknown error"}`,
+				);
+			}
+		} catch (err) {
+			// AuthManager rethrows structured WardenError sentinels — treat these
+			// as crashes too (config errors, SessionStrategy.USE_LOGIN, etc.).
+			crashCount++;
+			console.error(
+				`[warden] strategy '${strategyName}' threw during verify():`,
+				err,
+			);
+		}
+	}
+	return { result, viaGuard, attemptCount, crashCount };
+}
+
+/**
+ * A named-guard accessor (AdonisJS `auth.use('web')`). Exposes the stateful
+ * `login()`/`logout()` for session guards plus per-guard `authenticate()`.
+ */
+export class GuardAccessor {
+	readonly #ctx: WardenContext;
+	readonly #auth: AuthManager;
+	readonly #name: string;
+	readonly #parent: Authenticator;
+
+	constructor(
+		ctx: WardenContext,
+		auth: AuthManager,
+		name: string,
+		parent: Authenticator,
+	) {
+		this.#ctx = ctx;
+		this.#auth = auth;
+		this.#name = name;
+		this.#parent = parent;
+	}
+
+	/** The user, only if the request authenticated via THIS guard. */
+	get user(): UserPayload | undefined {
+		return this.#parent.authenticatedViaGuard === this.#name
+			? this.#parent.user
+			: undefined;
+	}
+
+	get isAuthenticated(): boolean {
+		return this.user !== undefined;
+	}
+
+	/** Authenticate the request using only this guard (throws on failure). */
+	authenticate(): Promise<void> {
+		return this.#parent.authenticateUsing([this.#name]);
+	}
+
+	/** Log a user in through this guard (session guards). */
+	login(user: UserPayload): Promise<void> {
+		return this.#auth.login(user, this.#requireSession(), this.#name);
+	}
+
+	/** Log the current user out of this guard (session guards). */
+	logout(): Promise<void> {
+		return this.#auth.logout(this.#requireSession(), this.#name);
+	}
+
+	#requireSession(): SessionStore {
+		if (!this.#ctx.session) {
+			throw new WardenError(
+				"NO_SESSION",
+				`Guard '${this.#name}'.login()/logout() requires a session, but ctx.session is unset. Register the session middleware upstream.`,
+			);
+		}
+		return this.#ctx.session;
+	}
+}
+
+/**
+ * Per-request Authenticator attached as `ctx.auth`. Mirrors AdonisJS's
+ * `Authenticator` surface: `authenticate` / `check` / `authenticateUsing` /
+ * `getUserOrFail` / `use`, plus the `user` / `isAuthenticated` /
+ * `authenticationAttempted` / `authenticatedViaGuard` getters.
+ */
+export class Authenticator {
+	readonly #ctx: WardenContext;
+	readonly #auth: AuthManager;
+	#user?: UserPayload;
+	#viaGuard?: string;
+	#attempted = false;
+	readonly #guardCache = new Map<string, GuardAccessor>();
+
+	constructor(ctx: WardenContext, auth: AuthManager) {
+		this.#ctx = ctx;
+		this.#auth = auth;
+	}
+
+	/** The authenticated user, or `undefined` for a guest. */
+	get user(): UserPayload | undefined {
+		return this.#user;
+	}
+
+	/** Whether the request has an authenticated user (AdonisJS name). */
+	get isAuthenticated(): boolean {
+		return this.#user !== undefined;
+	}
+
+	/** Whether `authenticate`/`check`/`authenticateUsing` ran this request. */
+	get authenticationAttempted(): boolean {
+		return this.#attempted;
+	}
+
+	/** Name of the guard that authenticated the request, if any. */
+	get authenticatedViaGuard(): string | undefined {
+		return this.#viaGuard;
+	}
+
+	/**
+	 * Roles of the authenticated user (Ream reads `ctx.auth.roles ??
+	 * ctx.auth.user.roles`). Warden nests them under `user`; this getter mirrors
+	 * them at the top level for the host's guard readers.
+	 */
+	get roles(): string[] | undefined {
+		return this.#user?.roles;
+	}
+
+	/** Permissions of the authenticated user (see {@link Authenticator.roles}). */
+	get permissions(): string[] | undefined {
+		return this.#user?.permissions;
+	}
+
+	/** Authenticate via the default guard. Throws `E_UNAUTHORIZED_ACCESS` on failure. */
+	authenticate(): Promise<void> {
+		return this.authenticateUsing([this.#auth.defaultStrategyName]);
+	}
+
+	/**
+	 * Like {@link Authenticator.authenticate} but returns a boolean instead of
+	 * throwing on a credential rejection. A strategy CRASH / config error still
+	 * propagates (a server incident must not be silently swallowed as "guest").
+	 */
+	async check(): Promise<boolean> {
+		try {
+			await this.authenticate();
+			return this.isAuthenticated;
+		} catch (err) {
+			if (err instanceof E_UNAUTHORIZED_ACCESS) return false;
+			throw err;
+		}
+	}
+
+	/**
+	 * Authenticate by trying the given guards in order (default: the default
+	 * guard). Sets the user on the first success; throws `E_UNAUTHORIZED_ACCESS`
+	 * (401, carrying `redirectTo` for session guards) when all reject, or a
+	 * `WARDEN_AUTH_STRATEGY_ERROR` (500) when every attempted guard crashed.
+	 */
+	async authenticateUsing(
+		guards?: string[],
+		options?: { loginRoute?: string },
+	): Promise<void> {
+		this.#attempted = true;
+		const names =
+			guards && guards.length > 0 ? guards : [this.#auth.defaultStrategyName];
+		const creds = extractCredentials(this.#ctx, this.#auth);
+		const hasSessionStrategy = names.includes("session");
+		const { result, viaGuard, attemptCount, crashCount } =
+			await tryAuthenticate(this.#auth, names, {
+				...creds,
+				hasSessionStrategy,
+			});
+
+		if (result?.authenticated && result.user) {
+			this.#user = result.user;
+			this.#viaGuard = viaGuard;
+			return;
+		}
+		// Every attempted guard crashed → a server-side incident, not a
+		// credential rejection. Surface distinctly (mapped to 500 by the caller).
+		if (attemptCount > 0 && crashCount === attemptCount) {
+			throw new WardenError(
+				"AUTH_STRATEGY_ERROR",
+				"Authentication unavailable — one or more strategies failed. Check server logs.",
+				{ status: 500 },
+			);
+		}
+		throw new E_UNAUTHORIZED_ACCESS(result?.error ?? "Unauthorized access", {
+			guardDriverName: names[0] ?? this.#auth.defaultStrategyName,
+			redirectTo: hasSessionStrategy ? options?.loginRoute : undefined,
+		});
+	}
+
+	/** Return the authenticated user or throw `E_UNAUTHORIZED_ACCESS`. */
+	getUserOrFail(): UserPayload {
+		if (!this.#user) {
+			throw new E_UNAUTHORIZED_ACCESS(
+				'Cannot access authenticated user. Call "ctx.auth.authenticate()" first.',
+				{ guardDriverName: this.#viaGuard ?? this.#auth.defaultStrategyName },
+			);
+		}
+		return this.#user;
+	}
+
+	/** Access a named guard (AdonisJS `auth.use('web')`). Instances are cached per request. */
+	use(name: string): GuardAccessor {
+		let accessor = this.#guardCache.get(name);
+		if (!accessor) {
+			accessor = new GuardAccessor(this.#ctx, this.#auth, name, this);
+			this.#guardCache.set(name, accessor);
+		}
+		return accessor;
+	}
+
+	/**
+	 * @internal Seed the Authenticator from a result the enforcing middleware
+	 * already computed, so `ctx.auth` reflects the authenticated user without a
+	 * second verify pass.
+	 */
+	adopt(result: AuthResult | null, viaGuard: string | undefined): void {
+		this.#attempted = true;
+		if (result?.authenticated && result.user) {
+			this.#user = result.user;
+			this.#viaGuard = viaGuard;
+		}
+	}
+}