@c9up/warden 0.1.13 → 0.1.14

package/src/middleware.ts

@@ -16,17 +16,13 @@
  *   }
  */
 
-import {
-	AuthManager,
-	type AuthResult,
-	type AuthStrategy,
-	sanitizePayload,
-} from "./AuthManager.js";
+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 { ScopeRequestContext } from "./config.js";
-import { WardenError } from "./errors.js";
+import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
 import {
 	getGuardMetadata,
 	getPermissionMetadata,
@@ -37,18 +33,6 @@ import { RightsResolver } from "./rights/RightsResolver.js";
 import type { Scope } from "./rights/types.js";
 import type { SessionStore } from "./strategies/SessionStrategy.js";
 
-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"
-	);
-}
-
 /**
  * Tokens warden resolves from the container: a service class, or a string/symbol
  * alias (`"bouncer:registry"`). Mirrors Ream's `ServiceToken` without importing
@@ -69,7 +53,7 @@ type ResolvableToken =
  * misconfigured kernel) yields no resolution: guarded routes fail CLOSED.
  */
 interface ContainerResolver {
-	make(token: ResolvableToken): unknown;
+	make(token: ResolvableToken): Promise<unknown>;
 }
 
 /**
@@ -100,6 +84,13 @@ export interface WardenContext {
 	response: {
 		status: (code: number) => unknown;
 		json: (data: unknown) => void;
+		/**
+		 * Redirect the response (Ream's `ctx.response.redirect`). Optional so a
+		 * minimal host without it still gets the 401 JSON fallback — Warden does
+		 * its own content negotiation (see `renderAuthError`) rather than leaning
+		 * on the host's exception handler.
+		 */
+		redirect?: (url: string) => unknown;
 	};
 	/**
 	 * Matched-route info — Ream (like Adonis) exposes the controller class +
@@ -120,8 +111,12 @@ export interface WardenContext {
 	action?: string | symbol;
 	/** Session store — set by a session middleware upstream. */
 	session?: SessionStore;
-	/** Set by the middleware after successful auth (Ream's `auth` slot). */
-	auth?: AuthResult;
+	/**
+	 * The per-request {@link Authenticator} (Ream's `auth` slot). `silentAuth`
+	 * (global) or `wardenMiddleware` (per guarded route) sets it; inline handlers
+	 * then call `ctx.auth.authenticate()` / `ctx.auth.use('session').login(user)`.
+	 */
+	auth?: Authenticator;
 	/**
 	 * Per-request authorization entry point — set by `initializeBouncer`. Typed
 	 * as the agnostic {@link Authorizer} contract (Ream's `ctx.bouncer` slot),
@@ -137,9 +132,12 @@ export interface WardenContext {
  * AuthManager gate in `wardenMiddleware`). No `@c9up/ream` import: warden reads
  * only from the context Ream hands it.
  */
-function resolveFromCtx(ctx: WardenContext, token: ResolvableToken): unknown {
+async function resolveFromCtx(
+	ctx: WardenContext,
+	token: ResolvableToken,
+): Promise<unknown> {
 	try {
-		return ctx.containerResolver?.make(token);
+		return await ctx.containerResolver?.make(token);
 	} catch {
 		return undefined;
 	}
@@ -162,7 +160,7 @@ type WardenNext = () => Promise<void> | void;
  * and authenticates + authorizes the request.
  */
 export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
-	const resolvedAuth = resolveFromCtx(ctx, AuthManager);
+	const resolvedAuth = await resolveFromCtx(ctx, AuthManager);
 	if (!(resolvedAuth instanceof AuthManager)) {
 		// Fail CLOSED — a missing AuthManager (WardenProvider not registered, or
 		// no `ctx.containerResolver` on a non-Ream host) must never silently let
@@ -190,75 +188,33 @@ export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
 		return;
 	}
 
-	// Extract credentials from multiple sources:
-	// 1. Authorization: Bearer <jwt> (JWT strategy)
-	// 2. API key header — reads the header name from the ApiKeyStrategy config
-	//    (defaults to 'x-api-key' if no ApiKeyStrategy is registered)
-	// 3. Cookie/session (Session strategy — handled by the strategy itself via context)
-	const headers = ctx.request.headers();
-	const authHeader = headers.authorization ?? "";
-	const bearerToken = authHeader.startsWith("Bearer ")
-		? authHeader.slice(7)
-		: "";
-	const apiKeyHeader = (() => {
-		try {
-			const s = auth.getStrategy("api-key");
-			return (s as { headerName?: string }).headerName ?? "x-api-key";
-		} catch {
-			return "x-api-key";
+	// Delegate authentication to the per-request Authenticator (the SAME contract
+	// inline handlers use via `ctx.auth.authenticate()`), so the decorator path
+	// and the functional path share one code path. It sets `ctx.auth` and throws
+	// on failure — E_UNAUTHORIZED_ACCESS (401, credential rejection) or a
+	// WARDEN_AUTH_STRATEGY_ERROR (500, every attempted guard crashed).
+	const authenticator = ensureAuthenticator(ctx, auth);
+	const loginRoute = await resolveLoginRoute(ctx);
+	try {
+		await authenticator.authenticateUsing(strategies, { loginRoute });
+	} catch (err) {
+		if (err instanceof E_UNAUTHORIZED_ACCESS) {
+			renderAuthError(ctx, err);
+			return;
 		}
-	})();
-	// HTTP header names are case-insensitive. Node + every Ream-side
-	// runtime lowercases incoming header keys, so an `ApiKeyStrategy`
-	// declared with `headerName: "X-Custom-Key"` would never match the
-	// incoming `x-custom-key` key without this normalisation — auth
-	// would silently fail even with the right header on the wire.
-	const apiKey = headers[apiKeyHeader.toLowerCase()] ?? "";
-
-	const hasSessionStrategy = strategies.some((s) => s === "session");
-	if (!bearerToken && !apiKey && !hasSessionStrategy) {
-		ctx.response.status(401);
-		ctx.response.json({
-			error: {
-				code: "UNAUTHORIZED",
-				message: "Missing authentication token (Bearer or x-api-key)",
-			},
-		});
-		return;
-	}
-
-	// Try each declared strategy. If every attempted strategy crashed AND none
-	// succeeded, the caller returns 500 instead of 401 — a server-side incident
-	// must stay observably distinct from a credential rejection.
-	const { result, attemptCount, crashCount } = await tryAuthenticate(
-		auth,
-		strategies,
-		{ bearerToken, apiKey, session: ctx.session, hasSessionStrategy },
-	);
-
-	if (!result?.authenticated || !result.user) {
-		if (attemptCount > 0 && crashCount === attemptCount) {
+		// Every attempted guard crashed → server-side incident, mapped to 500 so
+		// it stays observably distinct from a credential rejection.
+		if (err instanceof WardenError && err.status === 500) {
 			ctx.response.status(500);
 			ctx.response.json({
-				error: {
-					code: "AUTH_STRATEGY_ERROR",
-					message:
-						"Authentication unavailable — one or more strategies failed. Check server logs.",
-				},
+				error: { code: "AUTH_STRATEGY_ERROR", message: err.message },
 			});
 			return;
 		}
-		ctx.response.status(401);
-		ctx.response.json({
-			error: {
-				code: "UNAUTHORIZED",
-				message: result?.error ?? "Authentication failed",
-			},
-		});
-		return;
+		throw err;
 	}
 
-	const user = result.user;
+	const user = authenticator.getUserOrFail();
 
 	// Permission + role checks are independent AND gates: the user must satisfy
 	// ALL required permissions AND ALL required roles. Having a role does NOT
@@ -293,8 +249,7 @@ export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
 		}
 	}
 
-	// Auth successful — attach to context and continue.
-	ctx.auth = result;
+	// Auth successful — `ctx.auth` (the Authenticator) already carries the user.
 	await next();
 }
 
@@ -316,56 +271,80 @@ export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
  * middleware / route guard enforces).
  *
  * Uses the AuthManager's DEFAULT strategy (Adonis's "default guard"). A missing
- * AuthManager, absent credentials, or a failed/crashed verify all leave the
- * request as a guest (`ctx.auth` unset) — silent auth is non-enforcing.
+ * AuthManager leaves the request a guest with `ctx.auth` unset; otherwise
+ * `ctx.auth` is ALWAYS set to an {@link Authenticator} (AdonisJS
+ * `initialize_auth_middleware` parity) — populated when credentials verify,
+ * left as a guest (`isAuthenticated === false`) when they're absent, invalid, or
+ * a guard crashes. Silent auth NEVER surfaces a 401/500.
  */
 export async function silentAuth(ctx: WardenContext, next: WardenNext) {
-	const resolvedAuth = resolveFromCtx(ctx, AuthManager);
+	const resolvedAuth = await resolveFromCtx(ctx, AuthManager);
 	// Non-enforcing: a host without warden wired runs as guest. (Enforcement
 	// middlewares fail CLOSED on a missing AuthManager; silent auth does not.)
 	if (!(resolvedAuth instanceof AuthManager)) {
 		await next();
 		return;
 	}
-	const auth = resolvedAuth;
+	const authenticator = ensureAuthenticator(ctx, resolvedAuth);
+	try {
+		// `check()` runs the default guard and returns a boolean instead of
+		// throwing on a credential rejection; the catch swallows the residual
+		// crash/config path so silent auth stays strictly non-enforcing.
+		await authenticator.check();
+	} catch {
+		// Guard crash / config error → stay a guest, never surface here.
+	}
+	await next();
+}
 
-	const headers = ctx.request.headers();
-	const authHeader = headers.authorization ?? "";
-	const bearerToken = authHeader.startsWith("Bearer ")
-		? authHeader.slice(7)
-		: "";
-	const apiKeyHeader = (() => {
-		try {
-			const s = auth.getStrategy("api-key");
-			const name = "headerName" in s ? s.headerName : undefined;
-			return typeof name === "string" ? name : "x-api-key";
-		} catch {
-			return "x-api-key";
-		}
-	})();
-	const apiKey = headers[apiKeyHeader.toLowerCase()] ?? "";
+/**
+ * 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
+ * per-request instance across the middleware chain.
+ */
+function ensureAuthenticator(
+	ctx: WardenContext,
+	auth: AuthManager,
+): Authenticator {
+	if (ctx.auth instanceof Authenticator) return ctx.auth;
+	const authenticator = new Authenticator(ctx, auth);
+	ctx.auth = authenticator;
+	return authenticator;
+}
 
-	const strategy = auth.defaultStrategyName;
-	const hasSessionStrategy = strategy === "session";
-	// No credentials on the wire (and not a session strategy) → guest, no-op.
-	if (!bearerToken && !apiKey && !hasSessionStrategy) {
-		await next();
+/**
+ * Optional login route (`ctx.response.redirect` target for session-guard HTML
+ * flows). Registered by `WardenProvider` from `config.auth.loginRoute` under the
+ * `"warden:loginRoute"` token; absent ⇒ no redirect (401 JSON).
+ */
+async function resolveLoginRoute(
+	ctx: WardenContext,
+): Promise<string | undefined> {
+	const value = await resolveFromCtx(ctx, "warden:loginRoute");
+	return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Render an `E_UNAUTHORIZED_ACCESS` to the response — Warden does its OWN content
+ * negotiation (AdonisJS session renderer parity) instead of leaning on the
+ * host's exception handler, so it stays agnostic. An `Accept: text/html` request
+ * against a session guard carrying a `redirectTo` is redirected to the login
+ * route; every other case gets a 401 JSON body. Always fail-closed.
+ */
+export function renderAuthError(
+	ctx: WardenContext,
+	error: E_UNAUTHORIZED_ACCESS,
+): void {
+	const accept = ctx.request.headers().accept ?? "";
+	const wantsHtml = accept.includes("text/html");
+	if (wantsHtml && error.redirectTo && ctx.response.redirect) {
+		ctx.response.redirect(error.redirectTo);
 		return;
 	}
-
-	// Reuse the same per-strategy verification `wardenMiddleware` uses, but only
-	// for the default strategy, and swallow the outcome: a failed/crashed attempt
-	// must NOT surface as 401/500 here — silent auth only ever populates or skips.
-	const { result } = await tryAuthenticate(auth, [strategy], {
-		bearerToken,
-		apiKey,
-		session: ctx.session,
-		hasSessionStrategy,
+	ctx.response.status(error.status ?? 401);
+	ctx.response.json({
+		error: { code: error.code, message: error.message },
 	});
-	if (result?.authenticated && result.user) {
-		ctx.auth = result;
-	}
-	await next();
 }
 
 /**
@@ -396,9 +375,9 @@ export async function initializeBouncer(ctx: WardenContext, next: WardenNext) {
 	// Both dependencies are registered by WardenProvider. Resolve defensively:
 	// a host that wired the middleware but not the provider gets an empty Bouncer
 	// (no abilities/resolver) rather than a crash on every request.
-	const resolved = tryResolve(ctx, RightsResolver);
+	const resolved = await tryResolve(ctx, RightsResolver);
 	const resolver = resolved instanceof RightsResolver ? resolved : undefined;
-	const candidate = tryResolve(ctx, "bouncer:registry");
+	const candidate = await tryResolve(ctx, "bouncer:registry");
 	const registry = isBouncerRegistry(candidate) ? candidate : undefined;
 
 	const user = ctx.auth?.user ?? null;
@@ -414,7 +393,10 @@ export async function initializeBouncer(ctx: WardenContext, next: WardenNext) {
 }
 
 /** Resolve a container token from the request resolver, returning undefined instead of throwing when absent. */
-function tryResolve(ctx: WardenContext, token: ResolvableToken): unknown {
+async function tryResolve(
+	ctx: WardenContext,
+	token: ResolvableToken,
+): Promise<unknown> {
 	return resolveFromCtx(ctx, token);
 }
 
@@ -435,90 +417,13 @@ function isBouncerRegistry(value: unknown): value is BouncerRegistry {
  * hardcoded "global" and tenant-scoped roles/grants never satisfied @Role/@Permission.
  */
 async function resolveRequestScope(ctx: WardenContext): Promise<Scope> {
-	const candidate = tryResolve(ctx, "bouncer:registry");
+	const candidate = await tryResolve(ctx, "bouncer:registry");
 	const registry = isBouncerRegistry(candidate) ? candidate : undefined;
 	return registry?.resolveScope
 		? await registry.resolveScope(toScopeContext(ctx))
 		: "global";
 }
 
-/**
- * Try each declared strategy in order — session strategies 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.
- */
-async function tryAuthenticate(
-	auth: AuthManager,
-	strategies: string[],
-	creds: {
-		bearerToken: string;
-		apiKey: string;
-		session: SessionStore | undefined;
-		hasSessionStrategy: boolean;
-	},
-): Promise<{
-	result: AuthResult | null;
-	attemptCount: number;
-	crashCount: number;
-}> {
-	const { bearerToken, apiKey, session } = creds;
-	let result: AuthResult | null = null;
-	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 strategy).
-				const credential =
-					strategyName === "api-key"
-						? apiKey || bearerToken
-						: bearerToken || apiKey;
-				if (!credential) continue;
-				attemptCount++;
-				r = await auth.verify(credential, strategyName);
-			}
-			if (r.authenticated) {
-				result = r;
-				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, attemptCount, crashCount };
-}
-
 /**
  * Gate the authenticated user against the route's @Permission / @Role decorators.
  * Both are independent AND gates resolved ONCE against the same unified
@@ -527,7 +432,7 @@ async function tryAuthenticate(
  */
 async function checkAuthorization(
 	auth: AuthManager,
-	user: NonNullable<AuthResult["user"]>,
+	user: UserPayload,
 	controller: object,
 	action: string | symbol,
 	scope: Scope,

package/src/standalone.ts

@@ -52,25 +52,33 @@ export interface Warden {
  * Create a standalone Warden instance — no Ream container needed.
  */
 export function createWarden(config: WardenConfig): Warden {
-	// Mirror WardenProvider: build EVERY configured strategy, not just jwt —
-	// otherwise config.session / config.apiKey were silently dropped and a
-	// jwt-less config (e.g. { defaultStrategy: 'api-key', apiKey }) threw
-	// INVALID_CONFIG at boot (audit 2026-06-13). Keys match the @Guard names.
+	// Mirror WardenProvider: accept the AdonisJS `guards` form OR the legacy
+	// driver-keyed fields, building EVERY configured strategy — otherwise
+	// config.session / config.apiKey were silently dropped and a jwt-less config
+	// (e.g. { defaultStrategy: 'api-key', apiKey }) threw INVALID_CONFIG at boot
+	// (audit 2026-06-13). Keys match the @Guard names.
 	const strategies: Record<string, AuthStrategy> = {};
 
-	if (config.jwt) {
-		strategies.jwt = new JwtStrategy(config.jwt);
-	}
-	if (config.session) {
-		strategies.session = new SessionStrategy(config.session);
-	}
-	if (config.apiKey) {
-		strategies["api-key"] = new ApiKeyStrategy(config.apiKey);
+	if (config.guards && Object.keys(config.guards).length > 0) {
+		Object.assign(strategies, config.guards);
+	} else {
+		if (config.jwt) {
+			strategies.jwt = new JwtStrategy(config.jwt);
+		}
+		if (config.session) {
+			strategies.session = new SessionStrategy(config.session);
+		}
+		if (config.apiKey) {
+			const apiKey = new ApiKeyStrategy(config.apiKey);
+			strategies.access_tokens = apiKey;
+			strategies["api-key"] = apiKey;
+		}
 	}
 
 	const manager = new AuthManager({
-		defaultStrategy: config.defaultStrategy ?? "jwt",
-		strategies,
+		default:
+			config.default ?? config.defaultStrategy ?? Object.keys(strategies)[0],
+		guards: strategies,
 	});
 
 	return {

package/src/strategies/ApiKeyStrategy.ts

@@ -16,7 +16,10 @@ export interface ApiKeyConfig {
 }
 
 export class ApiKeyStrategy implements AuthStrategy {
-	name = "api-key";
+	// AdonisJS names this guard driver "access_tokens". The legacy "api-key"
+	// spelling is still accepted as a guard name / credential trigger by the
+	// middleware and providers (see `API_KEY_GUARD_NAMES`) for back-compat.
+	name = "access_tokens";
 	#config: ApiKeyConfig;
 	#headerName: string;
 

package/src/strategies/SessionStrategy.ts

@@ -58,9 +58,9 @@ export class SessionStrategy implements AuthStrategy {
 		// `strategy.authenticate()` directly.
 		throw new WardenError(
 			"USE_LOGIN",
-			"SessionStrategy.authenticate() requires login() instead. Use authManager.login(user, session).",
+			"SessionStrategy has no credential step. Verify the password yourself, then start the session via authManager.login(user, session) (or ctx.auth.use('session').login(user)).",
 			{
-				hint: "Verify the password yourself (e.g. via @c9up/sigil Hash.verify), then call SessionStrategy.login(user, session).",
+				hint: "Verify the password yourself (e.g. via @c9up/sigil Hash.verify), then call authManager.login(user, session) — SessionStrategy.login(user, session) also works directly.",
 			},
 		);
 	}