@c9up/warden 0.1.12 → 0.1.14

package/src/WardenProvider.ts

@@ -39,35 +39,60 @@ export default class WardenProvider {
 		// AuthManager with `strategies: {}` and `defaultStrategy: 'jwt'`,
 		// passing the (then-permissive) constructor and erroring deep in the
 		// middleware loop.
-		if (!config?.jwt && !config?.session && !config?.apiKey) {
+		const hasGuards = config?.guards && Object.keys(config.guards).length > 0;
+		if (!hasGuards && !config?.jwt && !config?.session && !config?.apiKey) {
 			throw new WardenError(
 				"WARDEN_NO_AUTH_CONFIG",
-				`@c9up/warden: no authentication strategies configured. Set at least one of config.warden.auth.jwt / .session / .apiKey in your reamrc.ts before registering WardenProvider.`,
+				`@c9up/warden: no authentication guards configured. Set config.warden.auth.guards (AdonisJS form) or at least one of .jwt / .session / .apiKey in your reamrc.ts before registering WardenProvider.`,
 			);
 		}
 
-		// Build the strategy table from whatever the app configured. Each strategy
-		// is also exposed by its class token (mirrors the jwt convention) so apps
-		// can resolve a specific one. The `revoke()` blacklist flows through
-		// `config.jwt.blacklist` into JwtStrategy.
+		// Build the guard table. Two accepted forms:
+		//  - AdonisJS: `config.guards` (name → AuthStrategy, via *Guard() factories).
+		//  - Legacy driver-keyed: `config.jwt` / `.session` / `.apiKey`.
+		// Each strategy is also exposed by its class token (so apps can resolve a
+		// specific one). The `revoke()` blacklist flows through `config.jwt.blacklist`.
 		const strategies: Record<string, AuthStrategy> = {};
 
-		if (config.jwt) {
-			const jwt = new JwtStrategy(config.jwt);
-			this.app.container.singleton(JwtStrategy, () => jwt);
-			strategies.jwt = jwt;
-		}
-		if (config.session) {
-			const session = new SessionStrategy(config.session);
-			this.app.container.singleton(SessionStrategy, () => session);
-			strategies.session = session;
-		}
-		if (config.apiKey) {
-			const apiKey = new ApiKeyStrategy(config.apiKey);
-			this.app.container.singleton(ApiKeyStrategy, () => apiKey);
-			strategies["api-key"] = apiKey;
+		if (hasGuards && config.guards) {
+			for (const [name, strategy] of Object.entries(config.guards)) {
+				strategies[name] = strategy;
+				// Expose recognised driver instances by their class token too.
+				if (strategy instanceof JwtStrategy) {
+					this.app.container.singleton(JwtStrategy, () => strategy);
+				} else if (strategy instanceof SessionStrategy) {
+					this.app.container.singleton(SessionStrategy, () => strategy);
+				} else if (strategy instanceof ApiKeyStrategy) {
+					this.app.container.singleton(ApiKeyStrategy, () => strategy);
+				}
+			}
+		} else {
+			if (config.jwt) {
+				const jwt = new JwtStrategy(config.jwt);
+				this.app.container.singleton(JwtStrategy, () => jwt);
+				strategies.jwt = jwt;
+			}
+			if (config.session) {
+				const session = new SessionStrategy(config.session);
+				this.app.container.singleton(SessionStrategy, () => session);
+				strategies.session = session;
+			}
+			if (config.apiKey) {
+				const apiKey = new ApiKeyStrategy(config.apiKey);
+				this.app.container.singleton(ApiKeyStrategy, () => apiKey);
+				// AdonisJS names this guard driver "access_tokens"; keep "api-key"
+				// as an accepted alias so existing `@Guard('api-key')` routes work.
+				strategies.access_tokens = apiKey;
+				strategies["api-key"] = apiKey;
+			}
 		}
 
+		// Login route (session-guard HTML redirect target) — resolved by the
+		// enforcing middleware via the "warden:loginRoute" token. Registered even
+		// when undefined so the lookup is a clean resolve, not a throw.
+		const loginRoute = config.loginRoute;
+		this.app.container.singleton("warden:loginRoute", () => loginRoute);
+
 		// Rights layer (Epic 56): one resolver singleton backs BOTH the coarse
 		// RBAC helpers (injected into AuthManager below) and — once 56.6 lands —
 		// the Bouncer construction, so a coarse question and a policy question
@@ -93,13 +118,14 @@ export default class WardenProvider {
 		};
 		this.app.container.singleton("bouncer:registry", () => bouncerRegistry);
 
-		// Default to the configured strategy, else the first one registered.
-		const defaultStrategy =
-			config.defaultStrategy ?? Object.keys(strategies)[0];
+		// Default to the configured guard (AdonisJS `default`, then legacy
+		// `defaultStrategy`), else the first one registered.
+		const defaultGuard =
+			config.default ?? config.defaultStrategy ?? Object.keys(strategies)[0];
 		this.app.container.singleton(AuthManager, () => {
 			return new AuthManager({
-				defaultStrategy,
-				strategies,
+				default: defaultGuard,
+				guards: strategies,
 				rights: rightsResolver,
 			});
 		});

package/src/bouncer/AbilitiesBuilder.ts

@@ -0,0 +1,41 @@
+/**
+ * AbilitiesBuilder — a chainable builder that fluently assembles an object of
+ * named abilities (Adonis `AbilitiesBuilder`). Each `.define(...)` delegates to
+ * `Bouncer.ability` and stores the result on `.abilities`, returning `this` so
+ * calls chain: `new AbilitiesBuilder().define(a).define(b).abilities`.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import { Bouncer } from "./Bouncer.js";
+import type { Ability, AbilityOptions, AuthorizerResponse } from "./types.js";
+
+export class AbilitiesBuilder {
+	/** The abilities accumulated so far, keyed by name. */
+	readonly abilities: Record<string, Ability<never[]>>;
+
+	constructor(abilities: Record<string, Ability<never[]>> = {}) {
+		this.abilities = abilities;
+	}
+
+	/**
+	 * Define a named ability (Adonis `.define(name, authorizer, options?)`). The
+	 * callback receives a non-null user (a guest is denied by the evaluator before
+	 * it runs); pass `{ allowGuest: true }` to let the callback run for a guest.
+	 */
+	define<Args extends unknown[]>(
+		name: string,
+		authorizer: (user: UserPayload, ...args: Args) => AuthorizerResponse,
+		options?: AbilityOptions,
+	): this {
+		// Delegate the callback wrapping to `Bouncer.ability` (guest-denied form),
+		// then apply the `allowGuest` option. Store without the `__args` phantom —
+		// its concrete-args brand cannot widen to the `never[]` storage slot, while
+		// `execute` is already non-generic.
+		const built = Bouncer.ability(authorizer);
+		this.abilities[name] = {
+			allowGuest: options?.allowGuest ?? built.allowGuest,
+			execute: built.execute,
+		};
+		return this;
+	}
+}

package/src/bouncer/AuthorizationResponse.ts

@@ -3,27 +3,22 @@
  *
  * Layer 2 (EVALUATION) of Warden's unified authorization (Epic 56). Faithful
  * to AdonisJS Bouncer's `AuthorizationResponse`: instances are produced only by
- * the `allow()` / `deny()` static constructors (the constructor is private), a
- * denial defaults to HTTP 403, and a `translation` field is carried for shape
- * parity with Adonis's i18n hook (always `undefined` in 56.2 — D6).
+ * the `allow()` / `deny()` static constructors (the constructor is private). A
+ * denial carries no `status` unless one is passed — the HTTP 403 default is
+ * applied only at the throw/HTTP boundary (Adonis parity) — and a `translation`
+ * field carries the i18n binding set via {@link t}.
  */
 export class AuthorizationResponse {
 	readonly authorized: boolean;
-	readonly message?: string;
-	readonly status?: number;
-	/** Parity placeholder for an i18n binding (always undefined in 56.2 — D6). */
-	readonly translation?: { identifier: string; data?: Record<string, unknown> };
+	message?: string;
+	status?: number;
+	/** i18n binding set via {@link t} (Adonis `AuthorizationResponse.t`). */
+	translation?: { identifier: string; data?: Record<string, unknown> };
 
-	private constructor(
-		authorized: boolean,
-		message?: string,
-		status?: number,
-		translation?: { identifier: string; data?: Record<string, unknown> },
-	) {
+	private constructor(authorized: boolean, message?: string, status?: number) {
 		this.authorized = authorized;
 		this.message = message;
 		this.status = status;
-		this.translation = translation;
 	}
 
 	/** Authorized response (no status). */
@@ -31,8 +26,21 @@ export class AuthorizationResponse {
 		return new AuthorizationResponse(true);
 	}
 
-	/** Denied response; `status` defaults to 403 (D6). */
-	static deny(message?: string, status = 403): AuthorizationResponse {
+	/**
+	 * Denied response. `status` is left `undefined` unless passed — the 403
+	 * default is applied only when the denial is thrown / mapped to HTTP (Adonis
+	 * parity).
+	 */
+	static deny(message?: string, status?: number): AuthorizationResponse {
 		return new AuthorizationResponse(false, message, status);
 	}
+
+	/**
+	 * Set the i18n translation binding and return `this` for chaining (Adonis
+	 * `AuthorizationResponse.t`), e.g. `AuthorizationResponse.deny().t('errors.forbidden')`.
+	 */
+	t(identifier: string, data?: Record<string, unknown>): this {
+		this.translation = { identifier, data };
+		return this;
+	}
 }

package/src/bouncer/BasePolicy.ts

@@ -27,13 +27,15 @@ export abstract class BasePolicy {
 
 	/**
 	 * Runs after the action (or after a `before` short-circuit), receiving the
-	 * resolved response. A non-`undefined` return overrides it; `undefined`
-	 * keeps it.
+	 * resolved response and the same resource args passed to the action (Adonis
+	 * `after(user, action, result, ...args)`). A non-`undefined` return overrides
+	 * the response; `undefined` keeps it.
 	 */
 	after?(
 		user: UserPayload | null,
 		action: string,
 		result: AuthorizationResponse,
+		...args: unknown[]
 	): HookResponse;
 
 	/**

package/src/bouncer/Bouncer.ts

@@ -15,6 +15,7 @@ import type { UserPayload } from "../AuthManager.js";
 import { WardenError } from "../errors.js";
 import type { RightsResolver } from "../rights/RightsResolver.js";
 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";
@@ -25,28 +26,63 @@ import type {
 	AbilityOptions,
 	AuthorizerResponse,
 	BouncerContext,
+	BouncerEmitter,
+	PolicyContainerResolver,
 } from "./types.js";
 
 export class Bouncer {
-	readonly #user: UserPayload | null;
+	readonly #userOrResolver: UserPayload | (() => UserPayload | null) | null;
+	/** Lazily-resolved user cache (`undefined` until `#getUser` runs). */
+	#user: UserPayload | null | undefined;
 	readonly #abilities: Record<string, Ability<never[]>>;
 	readonly #policies: Record<string, new () => BasePolicy>;
 	readonly #scope: Scope;
 	readonly #resolver: RightsResolver | undefined;
+	readonly #containerResolver: PolicyContainerResolver | undefined;
+	readonly #emitter: BouncerEmitter | undefined;
 	/** Memoized resolution — a Bouncer is fixed per `(user, scope)`, so resolve once (D3). */
 	#resolved: Promise<EffectivePermissions> | undefined;
 
 	constructor(
-		user: UserPayload | null,
+		user: UserPayload | (() => UserPayload | null) | null,
 		abilities?: Record<string, Ability<never[]>>,
 		policies?: Record<string, new () => BasePolicy>,
 		context?: BouncerContext,
 	) {
-		this.#user = user;
+		this.#userOrResolver = user;
 		this.#abilities = abilities ?? {};
 		this.#policies = policies ?? {};
 		this.#scope = context?.scope ?? "global";
 		this.#resolver = context?.resolver;
+		this.#containerResolver = context?.containerResolver;
+		this.#emitter = context?.emitter;
+	}
+
+	/**
+	 * Resolve the user, lazily invoking a resolver callback once and memoizing
+	 * the result (Adonis `#getUser`). A plain `UserPayload | null` passes through.
+	 */
+	#getUser(): UserPayload | null {
+		if (this.#user === undefined) {
+			this.#user =
+				typeof this.#userOrResolver === "function"
+					? this.#userOrResolver()
+					: this.#userOrResolver;
+		}
+		return this.#user;
+	}
+
+	/**
+	 * Define an ability and open a chainable {@link AbilitiesBuilder} (Adonis
+	 * `Bouncer.define`). Read `.abilities` off the returned builder to pass into a
+	 * `new Bouncer(user, abilities)`.
+	 */
+	static define<Args extends unknown[]>(
+		name: string,
+		authorizer: (user: UserPayload, ...args: Args) => AuthorizerResponse,
+		options?: AbilityOptions,
+	): AbilitiesBuilder {
+		return new AbilitiesBuilder().define(name, authorizer, options);
 	}
 
 	/** The active resolution scope (default `"global"`). */
@@ -62,9 +98,10 @@ export class Bouncer {
 	 */
 	#resolvePermissions(): Promise<EffectivePermissions> {
 		if (this.#resolved === undefined) {
+			const user = this.#getUser();
 			this.#resolved =
-				this.#resolver !== undefined && this.#user !== null
-					? this.#resolver.resolve(this.#user, this.#scope)
+				this.#resolver !== undefined && user !== null
+					? this.#resolver.resolve(user, this.#scope)
 					: Promise.resolve(emptyPermissions(this.#scope));
 		}
 		return this.#resolved;
@@ -120,19 +157,42 @@ export class Bouncer {
 		return AuthorizationResponse.deny(message, status);
 	}
 
-	/** Open a policy for checks (D8 — fresh `new PolicyClass()` per check). */
+	/** Open a policy for checks (D8 — fresh policy instance per check). */
 	with(policy: (new () => BasePolicy) | string): PolicyAuthorizer {
 		const factory =
 			typeof policy === "string"
 				? this.#resolvePolicyClass(policy)
-				: () => new policy();
+				: () => this.#construct(policy);
 		// The PolicyAuthorizer inherits the Bouncer's scope + the shared memoized
 		// resolve so every policy check sees the active `(user, scope)` (AC1/AC3).
-		return new PolicyAuthorizer(this.#user, factory, this.#scope, () =>
-			this.#resolvePermissions(),
+		return new PolicyAuthorizer(
+			this.#getUser(),
+			factory,
+			this.#scope,
+			() => this.#resolvePermissions(),
+			this.#emitter,
 		);
 	}
 
+	/**
+	 * Construct a policy instance via the container resolver when present (Adonis
+	 * DI parity), else a plain `new Policy()` (D8 — a fresh instance per check).
+	 */
+	#construct(ctor: new () => BasePolicy): Promise<BasePolicy> {
+		return this.#containerResolver !== undefined
+			? this.#containerResolver.make(ctor)
+			: Promise.resolve(new ctor());
+	}
+
+	/** Emit `authorization:finished` when an emitter is wired (no-op otherwise). */
+	#emit(action: string, response: AuthorizationResponse): void {
+		this.#emitter?.emit("authorization:finished", {
+			user: this.#getUser(),
+			action,
+			response,
+		});
+	}
+
 	/** Run an ability check and resolve to the full response. */
 	execute<Args extends unknown[]>(
 		ability: Ability<Args>,
@@ -194,13 +254,16 @@ export class Bouncer {
 	): Promise<AuthorizationResponse> {
 		const resolved =
 			typeof ability === "string" ? this.#resolveAbility(ability) : ability;
-		return evaluate({
-			user: this.#user,
-			action: typeof ability === "string" ? ability : "(ability)",
+		const action = typeof ability === "string" ? ability : "(ability)";
+		const response = await evaluate({
+			user: this.#getUser(),
+			action,
 			allowGuest: resolved.allowGuest,
 			run: (user) => resolved.execute(user, ...args),
 			args,
 		});
+		this.#emit(action, response);
+		return response;
 	}
 
 	#resolveAbility(name: string): Ability<never[]> {
@@ -215,7 +278,7 @@ export class Bouncer {
 		return found;
 	}
 
-	#resolvePolicyClass(name: string): () => BasePolicy {
+	#resolvePolicyClass(name: string): () => Promise<BasePolicy> {
 		// Lazy: the lookup runs when a verb constructs the policy, so an unknown
 		// name surfaces as a promise rejection (like every other verb error),
 		// not a synchronous throw at `with()` time.
@@ -230,7 +293,7 @@ export class Bouncer {
 					},
 				);
 			}
-			return new ctor();
+			return this.#construct(ctor);
 		};
 	}
 }

package/src/bouncer/PolicyAuthorizer.ts

@@ -19,6 +19,7 @@ import {
 	throwAuthorizationFailure,
 } from "./evaluate.js";
 import { emptyPermissions, setPolicyContext } from "./policyContext.js";
+import type { BouncerEmitter } from "./types.js";
 
 /**
  * Resolve a named action method declared anywhere on the policy's own subclass
@@ -65,21 +66,24 @@ function resolveActionMethod(policy: BasePolicy, action: string): Action {
 
 export class PolicyAuthorizer {
 	readonly #user: UserPayload | null;
-	readonly #factory: () => BasePolicy;
+	readonly #factory: () => Promise<BasePolicy>;
 	readonly #scope: Scope;
 	readonly #resolvePermissions: () => Promise<EffectivePermissions>;
+	readonly #emitter: BouncerEmitter | undefined;
 
 	constructor(
 		user: UserPayload | null,
-		factory: () => BasePolicy,
+		factory: () => Promise<BasePolicy>,
 		scope: Scope = "global",
 		resolvePermissions: () => Promise<EffectivePermissions> = () =>
 			Promise.resolve(emptyPermissions(scope)),
+		emitter?: BouncerEmitter,
 	) {
 		this.#user = user;
 		this.#factory = factory;
 		this.#scope = scope;
 		this.#resolvePermissions = resolvePermissions;
+		this.#emitter = emitter;
 	}
 
 	/** Run a check and resolve to the full response (D8 — fresh policy per check). */
@@ -87,14 +91,14 @@ export class PolicyAuthorizer {
 		action: string,
 		...args: unknown[]
 	): Promise<AuthorizationResponse> {
-		const policy = this.#factory();
+		const policy = await this.#factory();
 		// Attach the active scope + resolved permissions BEFORE dispatch so the
 		// before/method/after pipeline all read `this.scope` / `this.permissions`.
 		const permissions = await this.#resolvePermissions();
 		setPolicyContext(policy, { scope: this.#scope, permissions });
 		const method = resolveActionMethod(policy, action);
 		const options = getActionMetadata(policy, action);
-		return evaluate({
+		const response = await evaluate({
 			user: this.#user,
 			action,
 			allowGuest: options.allowGuest ?? false,
@@ -103,6 +107,12 @@ export class PolicyAuthorizer {
 			before: policy.before?.bind(policy),
 			after: policy.after?.bind(policy),
 		});
+		this.#emitter?.emit("authorization:finished", {
+			user: this.#user,
+			action,
+			response,
+		});
+		return response;
 	}
 
 	/** True iff the action is authorized. Never throws on denial. */

package/src/bouncer/evaluate.ts

@@ -69,6 +69,7 @@ export async function evaluate(params: {
 		user: UserPayload | null,
 		action: string,
 		result: AuthorizationResponse,
+		...args: unknown[]
 	) => HookResponse;
 }): Promise<AuthorizationResponse> {
 	const { user, action, allowGuest, run, args, before, after } = params;
@@ -92,9 +93,10 @@ export async function evaluate(params: {
 		}
 	}
 
-	// (4) after — non-undefined overrides.
+	// (4) after — non-undefined overrides. Receives the resource args (Adonis
+	// `policy.after(user, action, result, ...args)`).
 	if (after) {
-		const override = await after(user, action, response);
+		const override = await after(user, action, response, ...args);
 		if (override !== undefined) {
 			response = normalizeResponse(override);
 		}

package/src/bouncer/types.ts

@@ -11,9 +11,28 @@ import type { RightsResolver } from "../rights/RightsResolver.js";
 import type { Scope } from "../rights/types.js";
 import type { AuthorizationResponse } from "./AuthorizationResponse.js";
 
+/**
+ * Agnostic IoC-container resolver used to construct policy instances (Adonis
+ * `PolicyAuthorizer`'s `#containerResolver`). Same shape as `ctx.containerResolver`
+ * so a Ream request context is passed through directly — warden never imports the
+ * container. Absent ⇒ policies are built with a plain `new Policy()`.
+ */
+export interface PolicyContainerResolver {
+	make<T>(ctor: new (...args: never[]) => T): Promise<T>;
+}
+
+/**
+ * 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.
+ */
+export interface BouncerEmitter {
+	emit(event: string, payload: unknown): void;
+}
+
 /**
  * Optional 4th `Bouncer` ctor argument (56.3, D1) — the scope dimension + the
- * Layer-1 resolver. Both optional; omitting it ⇒ the implicit `global` scope
+ * Layer-1 resolver. All optional; omitting it ⇒ the implicit `global` scope
  * with no resolver (single-tenant zero-config, D7). Additive: every 56.2 call
  * site keeps compiling.
  */
@@ -22,6 +41,10 @@ export interface BouncerContext {
 	readonly scope?: Scope;
 	/** Layer-1 resolver consulted for this Bouncer's `(user, scope)`. */
 	readonly resolver?: RightsResolver;
+	/** IoC-container resolver used to construct policies (Adonis DI parity). */
+	readonly containerResolver?: PolicyContainerResolver;
+	/** Event sink for `authorization:finished` (Adonis `Bouncer.emitter`). */
+	readonly emitter?: BouncerEmitter;
 }
 
 /** A predicate's return — bool sugar or an explicit response, sync or async (D7). */

package/src/config.ts

@@ -15,13 +15,16 @@
  *   })
  */
 
-import type { UserPayload } from "./AuthManager.js";
+import type { AuthStrategy, UserPayload } from "./AuthManager.js";
 import type { BasePolicy } from "./bouncer/BasePolicy.js";
 import type { Ability } from "./bouncer/types.js";
 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 { JwtStrategy } from "./strategies/JwtStrategy.js";
 import type { SessionStrategyConfig } from "./strategies/SessionStrategy.js";
+import { SessionStrategy } from "./strategies/SessionStrategy.js";
 import type { TokenBlacklist } from "./TokenBlacklist.js";
 
 /**
@@ -50,10 +53,51 @@ export interface JwtConfig {
 	blacklist?: TokenBlacklist;
 }
 
+/**
+ * A guard entry in the AdonisJS-style config — an {@link AuthStrategy} instance,
+ * built via {@link jwtGuard}/{@link sessionGuard}/{@link apiKeyGuard}. Named a
+ * "factory" for AdonisJS symmetry (`sessionGuard({...})`), though Warden guards
+ * are shared per-app instances (the per-request state lives on the Authenticator).
+ */
+export type GuardFactory = AuthStrategy;
+
+/** Build a JWT guard from its config (AdonisJS `jwtGuard()` shape). */
+export function jwtGuard(config: JwtConfig): GuardFactory {
+	return new JwtStrategy(config);
+}
+
+/** Build a session guard from its config (AdonisJS `sessionGuard()` shape). */
+export function sessionGuard(config: SessionStrategyConfig): GuardFactory {
+	return new SessionStrategy(config);
+}
+
+/** Build an API-key / access-tokens guard from its config. */
+export function apiKeyGuard(config: ApiKeyConfig): GuardFactory {
+	return new ApiKeyStrategy(config);
+}
+
 export interface WardenConfig {
-	/** Default auth strategy (default: 'jwt'). */
+	/**
+	 * AdonisJS-style default guard NAME — the key in {@link WardenConfig.guards}
+	 * used when a route/call names none. Preferred over {@link
+	 * WardenConfig.defaultStrategy}.
+	 */
+	default?: string;
+	/**
+	 * AdonisJS-style named guard map, e.g.
+	 * `{ web: sessionGuard({...}), api: jwtGuard({...}) }`. Guards are named by
+	 * YOU (multiple instances of the same driver are allowed). When supplied,
+	 * this takes precedence over the driver-keyed `jwt`/`session`/`apiKey` fields.
+	 */
+	guards?: Record<string, GuardFactory>;
+	/**
+	 * Login route an HTML client is redirected to when a session-guarded request
+	 * is unauthenticated (AdonisJS session renderer parity). Absent ⇒ 401 JSON.
+	 */
+	loginRoute?: string;
+	/** Legacy default auth strategy name (default: 'jwt'). Prefer {@link WardenConfig.default}. */
 	defaultStrategy?: string;
-	/** JWT strategy configuration. */
+	/** JWT strategy configuration (legacy driver-keyed form). */
 	jwt?: JwtConfig;
 	/**
 	 * Session strategy configuration. Supply `findUser` so `@Guard('session')`

package/src/configure.ts

@@ -19,21 +19,23 @@ export async function configure(codemods: Codemods): Promise<void> {
 	});
 	await codemods.writeFile(
 		"config/auth.ts",
-		`import { defineConfig } from '@c9up/warden'
+		`import { defineConfig, jwtGuard } from '@c9up/warden'
 
 export default defineConfig({
-  defaultStrategy: 'jwt',
-  jwt: {
-    secret: process.env.JWT_SECRET ?? '',
-    expiresInSeconds: Number(process.env.JWT_EXPIRY ?? '3600'),
-    // TODO: wire these to your user model (e.g. via your ORM).
-    // The JWT strategy needs both to issue and verify tokens.
-    findUser: async (_id) => {
-      throw new Error('TODO: implement findUser(id) for the JWT strategy in config/auth.ts')
-    },
-    verifyCredentials: async (_email, _password) => {
-      throw new Error('TODO: implement verifyCredentials(email, password) in config/auth.ts')
-    },
+  default: 'jwt',
+  guards: {
+    jwt: jwtGuard({
+      secret: process.env.JWT_SECRET ?? '',
+      expiresInSeconds: Number(process.env.JWT_EXPIRY ?? '3600'),
+      // TODO: wire these to your user model (e.g. via your ORM).
+      // The JWT guard needs both to issue and verify tokens.
+      findUser: async (_id) => {
+        throw new Error('TODO: implement findUser(id) for the JWT guard in config/auth.ts')
+      },
+      verifyCredentials: async (_email, _password) => {
+        throw new Error('TODO: implement verifyCredentials(email, password) in config/auth.ts')
+      },
+    }),
   },
 })
 `,