@c9up/warden 0.1.0

package/src/bouncer/evaluate.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared evaluation pipeline — the single place that encodes the Adonis Bouncer
+ * evaluation order (D5), used by BOTH standalone abilities (no hooks) and policy
+ * methods (with `before`/`after`). Pinned by `bouncer-parity.test.ts` (AC-E2).
+ *
+ * Order: (1) `before` — a non-`undefined` return short-circuits the action;
+ * (2) guest-deny — `user === null` && !allowGuest ⇒ auto-deny WITHOUT running the
+ * action; (3) run the action; (4) `after` — a non-`undefined` return overrides.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import { WardenError } from "../errors.js";
+import { AuthorizationResponse } from "./AuthorizationResponse.js";
+import type { AuthorizerResponse, HookResponse } from "./types.js";
+
+/** A policy action method / ability callback, structurally. */
+export type Action = (
+	user: UserPayload | null,
+	...args: unknown[]
+) => AuthorizerResponse;
+
+/** Boolean sugar → response; an explicit response passes through (D7). */
+export function normalizeResponse(
+	value: boolean | AuthorizationResponse,
+): AuthorizationResponse {
+	if (value instanceof AuthorizationResponse) {
+		return value;
+	}
+	return value ? AuthorizationResponse.allow() : AuthorizationResponse.deny();
+}
+
+/**
+ * Type guard for a callable action. A function's parameter/return types are not
+ * observable at runtime, so this asserts the structural `Action` shape from a
+ * `typeof === "function"` check — a type guard (not an `as` cast), the standard
+ * escape for dynamic dispatch.
+ */
+export function isAction(value: unknown): value is Action {
+	return typeof value === "function";
+}
+
+/** Throw the canonical authorization failure for a denied response (D2). */
+export function throwAuthorizationFailure(
+	response: AuthorizationResponse,
+): never {
+	throw new WardenError(
+		"AUTHORIZATION_FAILURE",
+		response.message ?? "Authorization failed",
+		{
+			hint: "The current user is not authorized for this action.",
+			status: response.status ?? 403,
+		},
+	);
+}
+
+/** Run the D5 evaluation pipeline and resolve to the final response. */
+export async function evaluate(params: {
+	user: UserPayload | null;
+	action: string;
+	allowGuest: boolean;
+	run: (user: UserPayload | null) => AuthorizerResponse;
+	args: unknown[];
+	before?: (
+		user: UserPayload | null,
+		action: string,
+		...args: unknown[]
+	) => HookResponse;
+	after?: (
+		user: UserPayload | null,
+		action: string,
+		result: AuthorizationResponse,
+	) => HookResponse;
+}): Promise<AuthorizationResponse> {
+	const { user, action, allowGuest, run, args, before, after } = params;
+
+	let response: AuthorizationResponse | undefined;
+
+	// (1) before — non-undefined short-circuits the action.
+	if (before) {
+		const early = await before(user, action, ...args);
+		if (early !== undefined) {
+			response = normalizeResponse(early);
+		}
+	}
+
+	// (2) guest-deny + (3) action — only if before did not short-circuit.
+	if (response === undefined) {
+		if (user === null && !allowGuest) {
+			response = AuthorizationResponse.deny();
+		} else {
+			response = normalizeResponse(await run(user));
+		}
+	}
+
+	// (4) after — non-undefined overrides.
+	if (after) {
+		const override = await after(user, action, response);
+		if (override !== undefined) {
+			response = normalizeResponse(override);
+		}
+	}
+
+	return response;
+}

package/src/bouncer/policyContext.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal policy context attach — Layer-2 ⨯ Layer-1 wiring (Epic 56, story 56.3).
+ *
+ * The active `scope` and the resolved `EffectivePermissions` for the in-flight
+ * `(user, scope)` are attached to a freshly-constructed policy via a package-
+ * internal `WeakMap` (D2) — NOT a public setter on `BasePolicy` and NOT barrelled.
+ * `BasePolicy`'s `this.scope` / `this.permissions` getters read it back; the
+ * `PolicyAuthorizer` writes it before dispatch. A policy used without a Bouncer
+ * has no entry, so the getters fall back to `global` + {@link emptyPermissions}.
+ */
+
+import type { EffectivePermissions, Scope } from "../rights/types.js";
+import type { BasePolicy } from "./BasePolicy.js";
+
+/** What the authorizer attaches to a policy instance for one check. */
+export interface PolicyContext {
+	readonly scope: Scope;
+	readonly permissions: EffectivePermissions;
+}
+
+const contexts = new WeakMap<BasePolicy, PolicyContext>();
+
+/** Attach the active scope + resolved permissions to a policy instance (internal). */
+export function setPolicyContext(
+	policy: BasePolicy,
+	context: PolicyContext,
+): void {
+	contexts.set(policy, context);
+}
+
+/** Read back a policy's attached context, or `undefined` when used standalone. */
+export function getPolicyContext(
+	policy: BasePolicy,
+): PolicyContext | undefined {
+	return contexts.get(policy);
+}
+
+/**
+ * The empty `EffectivePermissions` for a guest / no-resolver Bouncer (D9). Built
+ * locally — never a `resolve()` call (the resolver requires a non-null user) and
+ * never importing 56.1's non-exported `ResolvedPermissions`. `has` → false;
+ * `hasAll([])` → true (vacuous); `hasAny` → false; empty sets; `scope` = active.
+ */
+export function emptyPermissions(scope: Scope): EffectivePermissions {
+	return {
+		has: () => false,
+		hasAll: (permissions) => permissions.length === 0,
+		hasAny: () => false,
+		permissions: new Set<string>(),
+		roles: new Set<string>(),
+		scope,
+	};
+}

package/src/bouncer/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Bouncer evaluation contract — Layer 2 of Warden's unified authorization.
+ *
+ * The shapes here are faithful to AdonisJS Bouncer (verified context7
+ * `/adonisjs/bouncer`, 2026-06-01): a predicate returns a boolean (sugar for
+ * allow / deny) or an explicit `AuthorizationResponse`, sync or async.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import type { RightsResolver } from "../rights/RightsResolver.js";
+import type { Scope } from "../rights/types.js";
+import type { AuthorizationResponse } from "./AuthorizationResponse.js";
+
+/**
+ * Optional 4th `Bouncer` ctor argument (56.3, D1) — the scope dimension + the
+ * Layer-1 resolver. Both optional; omitting it ⇒ the implicit `global` scope
+ * with no resolver (single-tenant zero-config, D7). Additive: every 56.2 call
+ * site keeps compiling.
+ */
+export interface BouncerContext {
+	/** Active resolution scope. Defaults to `"global"`. */
+	readonly scope?: Scope;
+	/** Layer-1 resolver consulted for this Bouncer's `(user, scope)`. */
+	readonly resolver?: RightsResolver;
+}
+
+/** A predicate's return — bool sugar or an explicit response, sync or async (D7). */
+export type AuthorizerResponse =
+	| boolean
+	| AuthorizationResponse
+	| Promise<boolean | AuthorizationResponse>;
+
+/** A `before`/`after` hook return — like {@link AuthorizerResponse} plus `undefined` (fall-through). */
+export type HookResponse =
+	| boolean
+	| AuthorizationResponse
+	| undefined
+	| Promise<boolean | AuthorizationResponse | undefined>;
+
+/** Options accepted by `Bouncer.ability` and the `@action` decorator. */
+export interface AbilityOptions {
+	allowGuest?: boolean;
+}
+
+/**
+ * An opaque ability reference produced by `Bouncer.ability`. Usable by-reference
+ * (typed call args via the `Args` phantom) AND by-name (registered in the
+ * Bouncer ctor's abilities record).
+ *
+ * `Args` is carried by the contravariant `__args` phantom — never read at
+ * runtime — so a concrete `Ability<[Post]>` is assignable to the universal
+ * `Ability<never[]>` storage type while `execute` stays invokable with the real
+ * args. This is a branding pattern (carry the type parameter in the signature),
+ * not a cast: `execute` itself takes `unknown[]` and the call sites validate
+ * args via the phantom at the verb boundary.
+ */
+export interface Ability<Args extends unknown[] = unknown[]> {
+	/** Whether a guest (null user) may invoke the callback (D5 step 2). */
+	readonly allowGuest: boolean;
+	/** Runs the ability callback. Guest-deny is applied by the evaluator, not here. */
+	readonly execute: (
+		user: UserPayload | null,
+		...args: unknown[]
+	) => AuthorizerResponse;
+	/** Phantom — ties the by-reference call args to `Args`; never read at runtime. */
+	readonly __args?: (...args: Args) => void;
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+/**
+ * Warden configuration — declared in `config/auth.ts` of the user app.
+ *
+ * @example
+ *   // config/auth.ts
+ *   import { defineConfig } from '@c9up/warden/config'
+ *   export default defineConfig({
+ *     defaultStrategy: 'jwt',
+ *     jwt: {
+ *       secret: env('APP_KEY'),
+ *       expiresInSeconds: 3600,
+ *       findUser: (id) => User.find(id),
+ *       verifyCredentials: (email, password) => User.verifyCredentials(email, password),
+ *     },
+ *   })
+ */
+
+import type { UserPayload } from "./AuthManager.js";
+import type { RightsStore } from "./rights/types.js";
+
+export interface JwtConfig {
+	secret: string;
+	expiresInSeconds?: number;
+	findUser: (id: string) => Promise<UserPayload | null>;
+	verifyCredentials: (
+		email: string,
+		password: string,
+	) => Promise<UserPayload | null>;
+}
+
+export interface WardenConfig {
+	/** Default auth strategy (default: 'jwt'). */
+	defaultStrategy?: string;
+	/** JWT strategy configuration. */
+	jwt?: JwtConfig;
+	/**
+	 * Rights layer configuration (Epic 56). Supply a custom `store` to back the
+	 * unified resolver with a DB-backed driver; when omitted, an in-memory
+	 * `MemoryRightsStore` is registered as the default (AD5 — pluggable store,
+	 * in-memory shipped).
+	 */
+	rights?: { store?: RightsStore };
+}
+
+/** Typed config helper — identity function for editor inference. */
+export function defineConfig(config: WardenConfig): WardenConfig {
+	return config;
+}

package/src/configure.ts

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	const jwtSecret = randomBytes(32).toString("hex");
+	await codemods.addProvider("@c9up/warden/provider");
+	await codemods.addEnvVars({
+		JWT_SECRET: jwtSecret,
+		JWT_EXPIRY: "3600",
+	});
+	await codemods.writeFile(
+		"config/auth.ts",
+		`import { defineConfig } 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')
+    },
+  },
+})
+`,
+	);
+	// Announce the TODOs on stderr so `ream add @c9up/warden` doesn't end
+	// with a quiet success that the user reads as "auth is wired". The
+	// generated config/auth.ts ships with `throw new Error('TODO ...')`
+	// stubs for findUser + verifyCredentials — login and JWT verify will
+	// fail at the first call until the user fills them in. Surfacing the
+	// list here means an operator running the installer sees it
+	// immediately, not at the first request that hits the auth path.
+	process.stderr.write(
+		[
+			"",
+			"[@c9up/warden] config/auth.ts written with TODO stubs:",
+			"  - jwt.findUser(id) — wire to your user lookup (ORM)",
+			"  - jwt.verifyCredentials(email, password) — wire to your sign-in flow",
+			"Both throw at runtime until you implement them — login + JWT verify",
+			"will fail with `TODO: implement …` errors otherwise.",
+			"",
+		].join("\n"),
+	);
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+/**
+ * WardenError — structured error for Warden auth.
+ */
+export class WardenError extends Error {
+	readonly code: string;
+	readonly hint?: string;
+	/**
+	 * Optional HTTP status carried by the error so the HTTP layer can map it
+	 * (e.g. an authorization failure carries 403 — Epic 56 / story 56.2, D2).
+	 * Additive and optional: callers that omit it behave exactly as before.
+	 */
+	readonly status?: number;
+
+	constructor(
+		code: string,
+		message: string,
+		options?: { hint?: string; status?: number },
+	) {
+		super(message);
+		this.name = "WardenError";
+		this.code = `WARDEN_${code}`;
+		this.hint = options?.hint;
+		this.status = options?.status;
+	}
+}

package/src/firstcontact/FirstContactManager.ts

@@ -0,0 +1,54 @@
+/**
+ * FirstContactManager — OAuth2 social authentication.
+ *
+ * Usage:
+ *   firstContact.use('google').redirectUrl()
+ *   firstContact.use('google').callback(code)
+ */
+
+import type { FirstContactDriver, OAuthToken, OAuthUser } from "./types.js";
+
+export class FirstContactManager {
+	#drivers: Map<string, FirstContactDriver> = new Map();
+
+	use(name: string): FirstContactDriver {
+		const driver = this.#drivers.get(name);
+		if (!driver)
+			throw new Error(
+				`OAuth driver '${name}' not registered. Available: ${[...this.#drivers.keys()].join(", ")}`,
+			);
+		return driver;
+	}
+
+	register(name: string, driver: FirstContactDriver): void {
+		this.#drivers.set(name, driver);
+	}
+
+	redirect(name: string, state?: string): string {
+		return this.use(name).redirectUrl(state);
+	}
+
+	/**
+	 * Handle the OAuth callback. Pass `state` (from the query string) and
+	 * `expectedState` (from the session, stored at redirect time) for CSRF
+	 * protection. Omitting `expectedState` logs a security warning.
+	 */
+	async callback(
+		name: string,
+		code: string,
+		state?: string,
+		expectedState?: string,
+	): Promise<{ user: OAuthUser; token: OAuthToken }> {
+		if (!expectedState) {
+			throw new Error(
+				`[warden] OAuth callback for '${name}' requires expectedState for CSRF protection. ` +
+					`Store the state from redirect() in the session and pass it here.`,
+			);
+		}
+		return this.use(name).callback(code, state, expectedState);
+	}
+
+	get registeredDrivers(): string[] {
+		return [...this.#drivers.keys()];
+	}
+}

package/src/firstcontact/drivers/GitHubDriver.ts

@@ -0,0 +1,78 @@
+/**
+ * GitHub OAuth2 driver for FirstContact.
+ */
+
+import type {
+	FirstContactDriver,
+	OAuthConfig,
+	OAuthToken,
+	OAuthUser,
+} from "../types.js";
+
+export class GitHubDriver implements FirstContactDriver {
+	constructor(private config: OAuthConfig) {}
+
+	redirectUrl(state?: string): string {
+		const params = new URLSearchParams({
+			client_id: this.config.clientId,
+			redirect_uri: this.config.callbackUrl,
+			scope: (this.config.scopes ?? ["read:user", "user:email"]).join(" "),
+			...(state ? { state } : {}),
+		});
+		return `https://github.com/login/oauth/authorize?${params}`;
+	}
+
+	async callback(
+		code: string,
+		state?: string,
+		expectedState?: string,
+	): Promise<{ user: OAuthUser; token: OAuthToken }> {
+		if (expectedState && state !== expectedState) {
+			throw new Error("OAuth state mismatch — possible CSRF attack");
+		}
+		const tokenRes = await fetch(
+			"https://github.com/login/oauth/access_token",
+			{
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					client_id: this.config.clientId,
+					client_secret: this.config.clientSecret,
+					code,
+				}),
+			},
+		);
+		if (!tokenRes.ok) {
+			throw new Error(
+				`GitHub OAuth token exchange failed (HTTP ${tokenRes.status})`,
+			);
+		}
+		const tokens = (await tokenRes.json()) as Record<string, unknown>;
+		if (!tokens.access_token)
+			throw new Error("GitHub OAuth: no access_token in response");
+
+		const userRes = await fetch("https://api.github.com/user", {
+			headers: {
+				Authorization: `Bearer ${tokens.access_token}`,
+				Accept: "application/json",
+			},
+		});
+		if (!userRes.ok)
+			throw new Error(`GitHub user API failed (${userRes.status})`);
+		const raw = (await userRes.json()) as Record<string, unknown>;
+
+		return {
+			user: {
+				id: String(raw.id ?? ""),
+				email: String(raw.email ?? ""),
+				name: String(raw.name ?? raw.login ?? ""),
+				avatarUrl: raw.avatar_url as string | undefined,
+				raw,
+			},
+			token: { accessToken: String(tokens.access_token) },
+		};
+	}
+}

package/src/firstcontact/drivers/GoogleDriver.ts

@@ -0,0 +1,81 @@
+/**
+ * Google OAuth2 driver for FirstContact.
+ */
+
+import type {
+	FirstContactDriver,
+	OAuthConfig,
+	OAuthToken,
+	OAuthUser,
+} from "../types.js";
+
+export class GoogleDriver implements FirstContactDriver {
+	constructor(private config: OAuthConfig) {}
+
+	redirectUrl(state?: string): string {
+		const params = new URLSearchParams({
+			client_id: this.config.clientId,
+			redirect_uri: this.config.callbackUrl,
+			response_type: "code",
+			scope: (this.config.scopes ?? ["openid", "email", "profile"]).join(" "),
+			access_type: "offline",
+			...(state ? { state } : {}),
+		});
+		return `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
+	}
+
+	async callback(
+		code: string,
+		state?: string,
+		expectedState?: string,
+	): Promise<{ user: OAuthUser; token: OAuthToken }> {
+		// CSRF protection: validate state matches what we sent in redirectUrl().
+		if (expectedState && state !== expectedState) {
+			throw new Error("OAuth state mismatch — possible CSRF attack");
+		}
+		const tokenRes = await fetch("https://oauth2.googleapis.com/token", {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				code,
+				client_id: this.config.clientId,
+				client_secret: this.config.clientSecret,
+				redirect_uri: this.config.callbackUrl,
+				grant_type: "authorization_code",
+			}),
+		});
+		if (!tokenRes.ok) {
+			throw new Error(
+				`Google OAuth token exchange failed (HTTP ${tokenRes.status})`,
+			);
+		}
+		const tokens = (await tokenRes.json()) as Record<string, unknown>;
+		if (!tokens.access_token)
+			throw new Error("Google OAuth: no access_token in response");
+
+		const userRes = await fetch(
+			"https://www.googleapis.com/oauth2/v2/userinfo",
+			{
+				headers: { Authorization: `Bearer ${tokens.access_token}` },
+			},
+		);
+		if (!userRes.ok)
+			throw new Error(`Google userinfo failed (${userRes.status})`);
+		const raw = (await userRes.json()) as Record<string, unknown>;
+
+		return {
+			user: {
+				id: String(raw.id ?? ""),
+				email: String(raw.email ?? ""),
+				name: String(raw.name ?? ""),
+				avatarUrl: raw.picture as string | undefined,
+				raw,
+			},
+			token: {
+				accessToken: String(tokens.access_token),
+				refreshToken: tokens.refresh_token as string | undefined,
+				expiresIn: tokens.expires_in as number | undefined,
+			},
+		};
+	}
+}

package/src/firstcontact/types.ts

@@ -0,0 +1,38 @@
+/**
+ * FirstContact — OAuth2 social authentication types.
+ */
+
+export interface OAuthConfig {
+	clientId: string;
+	clientSecret: string;
+	callbackUrl: string;
+	scopes?: string[];
+}
+
+export interface OAuthUser {
+	id: string;
+	email: string;
+	name: string;
+	avatarUrl?: string;
+	raw: Record<string, unknown>;
+}
+
+export interface OAuthToken {
+	accessToken: string;
+	refreshToken?: string;
+	expiresIn?: number;
+}
+
+export interface FirstContactDriver {
+	redirectUrl(state?: string): string;
+	/**
+	 * Handle the OAuth callback. `state` MUST be validated against the value
+	 * originally passed to `redirectUrl()` to prevent CSRF login attacks.
+	 * Throws if state is missing or mismatched.
+	 */
+	callback(
+		code: string,
+		state?: string,
+		expectedState?: string,
+	): Promise<{ user: OAuthUser; token: OAuthToken }>;
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @module @c9up/warden
+ * @description Warden — Authentication & authorization for the Ream framework
+ * @implements FR48, FR49, FR50, FR51, FR52, FR53
+ */
+
+export type {
+	AuthConfig,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "./AuthManager.js";
+export { AuthManager } from "./AuthManager.js";
+export type { AuthRateLimiterConfig } from "./AuthRateLimiter.js";
+export { AuthRateLimiter } from "./AuthRateLimiter.js";
+export { AuthorizationResponse } from "./bouncer/AuthorizationResponse.js";
+export { BasePolicy } from "./bouncer/BasePolicy.js";
+export { Bouncer } from "./bouncer/Bouncer.js";
+export {
+	action,
+	allowGuest,
+	getActionMetadata,
+} from "./bouncer/decorators.js";
+export type { PolicyAuthorizer } from "./bouncer/PolicyAuthorizer.js";
+export type {
+	Ability,
+	AbilityOptions,
+	AuthorizerResponse,
+	BouncerContext,
+} from "./bouncer/types.js";
+export { defineConfig } from "./config.js";
+export { configure } from "./configure.js";
+export { WardenError } from "./errors.js";
+export { GitHubDriver } from "./firstcontact/drivers/GitHubDriver.js";
+export { GoogleDriver } from "./firstcontact/drivers/GoogleDriver.js";
+export { FirstContactManager } from "./firstcontact/FirstContactManager.js";
+export type {
+	FirstContactDriver,
+	OAuthConfig,
+	OAuthToken,
+	OAuthUser,
+} from "./firstcontact/types.js";
+export {
+	Guard,
+	getGuardMetadata,
+	getPermissionMetadata,
+	getRoleMetadata,
+	Permission,
+	Role,
+} from "./Guard.js";
+export type {
+	RefreshTokenDriver,
+	StoredRefreshToken,
+} from "./RefreshTokenStore.js";
+export {
+	generateRefreshToken,
+	MemoryRefreshTokenDriver,
+} from "./RefreshTokenStore.js";
+export { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
+export { RightsResolver } from "./rights/RightsResolver.js";
+export type {
+	EffectivePermissions,
+	RightsStore,
+	Scope,
+} from "./rights/types.js";
+export { scopeKey } from "./rights/types.js";
+export type { ApiKeyConfig } from "./strategies/ApiKeyStrategy.js";
+export { ApiKeyStrategy } from "./strategies/ApiKeyStrategy.js";
+export type { JwtStrategyConfig } from "./strategies/JwtStrategy.js";
+export { generateJwtSecret, JwtStrategy } from "./strategies/JwtStrategy.js";
+export type {
+	SessionStore,
+	SessionStrategyConfig,
+} from "./strategies/SessionStrategy.js";
+export { SessionStrategy } from "./strategies/SessionStrategy.js";
+export type { BlacklistDriver } from "./TokenBlacklist.js";
+export { MemoryBlacklistDriver, TokenBlacklist } from "./TokenBlacklist.js";