@c9up/warden 0.1.0

package/src/middleware.ts

@@ -0,0 +1,283 @@
+/**
+ * Warden auth middleware — resolves the AuthManager from the Ream IoC container
+ * and authenticates the request using the configured strategy.
+ *
+ * Same pattern as `@c9up/blackhole/middleware` and AdonisJS `@adonisjs/auth`.
+ *
+ * @example
+ *   // start/kernel.ts
+ *   router.use([() => import('@c9up/warden/middleware')])
+ *
+ *   // On protected routes
+ *   import { Guard } from '@c9up/warden'
+ *   class OrderController {
+ *     @Guard('jwt')
+ *     async index(ctx) { ... }
+ *   }
+ */
+
+import {
+	AuthManager,
+	type AuthResult,
+	type AuthStrategy,
+	sanitizePayload,
+} from "./AuthManager.js";
+import {
+	getGuardMetadata,
+	getPermissionMetadata,
+	getRoleMetadata,
+} from "./Guard.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"
+	);
+}
+
+export interface WardenContext {
+	request: {
+		method: string;
+		url: string;
+		headers: Record<string, string>;
+	};
+	response: {
+		status: (code: number) => void;
+		json: (data: unknown) => void;
+	};
+	container: {
+		resolve: (
+			key: string | symbol | (abstract new (...args: never[]) => unknown),
+		) => unknown;
+	};
+	/** Session store — set by a session middleware upstream. */
+	session?: SessionStore;
+	/** Set by the middleware after successful auth. */
+	auth?: AuthResult;
+	/** The route handler metadata (decorators). */
+	route?: {
+		controller?: object;
+		action?: string | symbol;
+	};
+}
+
+type WardenNext = () => Promise<void> | void;
+
+/**
+ * Ream auth middleware — resolves AuthManager from the container,
+ * reads `@Guard`/`@Permission`/`@Role` metadata from the route handler,
+ * and authenticates + authorizes the request.
+ */
+export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
+	const auth = ctx.container.resolve(AuthManager) as AuthManager;
+
+	// Read guard metadata from the route handler (if declared via decorators).
+	const controller = ctx.route?.controller;
+	const action = ctx.route?.action;
+	const strategies =
+		controller && action ? getGuardMetadata(controller, action) : [];
+
+	// No guard on this route — pass through (public endpoint).
+	if (strategies.length === 0) {
+		await next();
+		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 authHeader = ctx.request.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";
+		}
+	})();
+	// 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 = ctx.request.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) {
+			ctx.response.status(500);
+			ctx.response.json({
+				error: {
+					code: "AUTH_STRATEGY_ERROR",
+					message:
+						"Authentication unavailable — one or more strategies failed. Check server logs.",
+				},
+			});
+			return;
+		}
+		ctx.response.status(401);
+		ctx.response.json({
+			error: {
+				code: "UNAUTHORIZED",
+				message: result?.error ?? "Authentication failed",
+			},
+		});
+		return;
+	}
+
+	const user = result.user;
+
+	// Permission + role checks are independent AND gates: the user must satisfy
+	// ALL required permissions AND ALL required roles. Having a role does NOT
+	// bypass permission checks. This is the strictest model — callers who want
+	// role-OR-permission semantics should use a custom guard instead.
+	if (controller && action) {
+		const denied = await checkAuthorization(auth, user, controller, action);
+		if (denied) {
+			ctx.response.status(403);
+			ctx.response.json({ error: { code: "FORBIDDEN", message: denied } });
+			return;
+		}
+	}
+
+	// Auth successful — attach to context and continue.
+	ctx.auth = result;
+	await next();
+}
+
+/**
+ * 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
+ * EffectivePermissions set (Epic 56, D7). Returns the FORBIDDEN message, or null
+ * when authorised (and zero-cost when neither decorator is present).
+ */
+async function checkAuthorization(
+	auth: AuthManager,
+	user: NonNullable<AuthResult["user"]>,
+	controller: object,
+	action: string | symbol,
+): Promise<string | null> {
+	const requiredPermissions = getPermissionMetadata(controller, action);
+	const requiredRoles = getRoleMetadata(controller, action);
+	if (requiredPermissions.length === 0 && requiredRoles.length === 0) {
+		return null;
+	}
+	const effective = await auth.resolvePermissions(user, "global");
+	if (requiredPermissions.length > 0) {
+		const missing = requiredPermissions.filter((p) => !effective.has(p));
+		if (missing.length > 0) return `Missing permissions: ${missing.join(", ")}`;
+	}
+	if (requiredRoles.length > 0) {
+		const missing = requiredRoles.filter((r) => !effective.roles.has(r));
+		if (missing.length > 0) return `Missing roles: ${missing.join(", ")}`;
+	}
+	return null;
+}

package/src/native.ts

@@ -0,0 +1,53 @@
+/**
+ * Warden NAPI loader — loads the `warden-engine-napi` binary for Rust-native
+ * JWT/HMAC/random operations. There is no TS fallback: when the binary is
+ * absent, `nativeWarden()` returns `undefined` and `JwtStrategy` (and any
+ * other consumer) throws `WARDEN_NAPI_REQUIRED` at use time. Password
+ * hashing is the sole responsibility of `@c9up/sigil` (story 40.1).
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const nodeRequire = createRequire(import.meta.url);
+const currentDir = dirname(fileURLToPath(import.meta.url));
+
+const platformMap: Record<string, string> = {
+	"linux-x64": "linux-x64-gnu",
+	"linux-arm64": "linux-arm64-gnu",
+	"darwin-x64": "darwin-x64",
+	"darwin-arm64": "darwin-arm64",
+	"win32-x64": "win32-x64-msvc",
+};
+
+export interface NativeWarden {
+	jwtSign(payload: string, secret: string): string;
+	jwtVerify(token: string, secret: string): string;
+	constantTimeEq(a: string, b: string): boolean;
+	hmacSign(data: string, secret: string): string;
+	hmacVerify(data: string, signature: string, secret: string): boolean;
+	randomBytes(len: number): string;
+	randomHex(len: number): string;
+}
+
+let native: NativeWarden | undefined;
+
+try {
+	const suffix = platformMap[`${platform}-${arch}`];
+	if (suffix) {
+		native = nodeRequire(join(currentDir, `../index.${suffix}.node`));
+	}
+} catch {
+	// Binary not available — JwtStrategy will throw WARDEN_NAPI_REQUIRED at use time.
+}
+
+/** Whether the Rust NAPI engine loaded. */
+export function isNativeAvailable(): boolean {
+	return native !== undefined;
+}
+
+/** Get the native engine. Returns undefined if not loaded — caller must throw. */
+export function nativeWarden(): NativeWarden | undefined {
+	return native;
+}

package/src/rights/MemoryRightsStore.ts

@@ -0,0 +1,92 @@
+/**
+ * MemoryRightsStore — the shipped in-memory rights driver.
+ *
+ * Implements the read-only `RightsStore` contract and adds chainable seeding
+ * methods (`defineRole`/`assignRole`/`grant`/`revoke`) for app boot and tests.
+ * DB-backed drivers are a documented copy-in adapter, not a hard dependency —
+ * this driver keeps Warden's agnostic posture with zero new dependencies.
+ *
+ * Storage is Map-based, keyed by `scopeKey(scope)` then by role/userId, so
+ * `global` and `tenant:X` rights stay isolated (inheritance is the resolver's
+ * job, not the store's).
+ */
+
+import { type RightsStore, type Scope, scopeKey } from "./types.js";
+
+export class MemoryRightsStore implements RightsStore {
+	/** scopeKey → role → permissions */
+	private readonly roleDefs = new Map<string, Map<string, Set<string>>>();
+	/** scopeKey → userId → roles */
+	private readonly userRoleMap = new Map<string, Map<string, Set<string>>>();
+	/** scopeKey → userId → directly granted permissions */
+	private readonly userGrantMap = new Map<string, Map<string, Set<string>>>();
+
+	// — read contract —
+
+	async rolePermissions(
+		role: string,
+		scope: Scope,
+	): Promise<readonly string[]> {
+		return snapshot(this.roleDefs.get(scopeKey(scope))?.get(role));
+	}
+
+	async userRoles(userId: string, scope: Scope): Promise<readonly string[]> {
+		return snapshot(this.userRoleMap.get(scopeKey(scope))?.get(userId));
+	}
+
+	async userGrants(userId: string, scope: Scope): Promise<readonly string[]> {
+		return snapshot(this.userGrantMap.get(scopeKey(scope))?.get(userId));
+	}
+
+	// — seeding (in-memory driver only; not part of RightsStore) —
+
+	defineRole(
+		role: string,
+		permissions: readonly string[],
+		scope: Scope = "global",
+	): this {
+		const set = bucket(this.roleDefs, scopeKey(scope), role);
+		set.clear();
+		for (const perm of permissions) set.add(perm);
+		return this;
+	}
+
+	assignRole(userId: string, role: string, scope: Scope = "global"): this {
+		bucket(this.userRoleMap, scopeKey(scope), userId).add(role);
+		return this;
+	}
+
+	grant(userId: string, permission: string, scope: Scope = "global"): this {
+		bucket(this.userGrantMap, scopeKey(scope), userId).add(permission);
+		return this;
+	}
+
+	revoke(userId: string, permission: string, scope: Scope = "global"): this {
+		this.userGrantMap.get(scopeKey(scope))?.get(userId)?.delete(permission);
+		return this;
+	}
+}
+
+/** Defensive array snapshot — never hands back a live reference to internal state. */
+function snapshot(set: Set<string> | undefined): readonly string[] {
+	return set ? [...set] : [];
+}
+
+/** Get-or-create the inner `Set` for `outer[key][inner]`. */
+function bucket(
+	outer: Map<string, Map<string, Set<string>>>,
+	key: string,
+	inner: string,
+): Set<string> {
+	let mid = outer.get(key);
+	if (!mid) {
+		mid = new Map<string, Set<string>>();
+		outer.set(key, mid);
+	}
+	let set = mid.get(inner);
+	if (!set) {
+		set = new Set<string>();
+		mid.set(inner, set);
+	}
+	return set;
+}

package/src/rights/RightsResolver.ts

@@ -0,0 +1,84 @@
+/**
+ * RightsResolver — computes a user's effective permissions for a scope.
+ *
+ * This is the unification point the epic calls `user.permissions`: every later
+ * authorization facet consults `resolve(user, scope)` instead of reading roles
+ * or permissions ad hoc.
+ *
+ * Resolution rules:
+ *   - Scope chain: `["global"]` for global, `["global", { tenant }]` for a
+ *     tenant scope — global rights are inherited into every tenant scope.
+ *   - Roles: token-carried `user.roles` are global identity — they apply at
+ *     the `global` link only; each scope additionally uses `store.userRoles(...)`.
+ *     A global role's global permissions still inherit into tenant scopes via
+ *     the chain, but a payload role never picks up a same-named tenant role's
+ *     permissions (no cross-tenant escalation by name collision).
+ *   - Permissions = (∪ over roles of `store.rolePermissions(...)`) ∪
+ *     `store.userGrants(...)` (the ACL). The payload's `user.permissions` is
+ *     NOT an input — permissions are derived from the rights model only.
+ *   - Fail-closed: absent data contributes nothing and never throws.
+ *   - Exact-match comparison; no wildcard or role-hierarchy expansion.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import type { EffectivePermissions, RightsStore, Scope } from "./types.js";
+
+class ResolvedPermissions implements EffectivePermissions {
+	constructor(
+		readonly permissions: ReadonlySet<string>,
+		readonly roles: ReadonlySet<string>,
+		readonly scope: Scope,
+	) {}
+
+	has(permission: string): boolean {
+		return this.permissions.has(permission);
+	}
+
+	hasAll(permissions: readonly string[]): boolean {
+		return permissions.every((p) => this.permissions.has(p));
+	}
+
+	hasAny(permissions: readonly string[]): boolean {
+		return permissions.some((p) => this.permissions.has(p));
+	}
+}
+
+export class RightsResolver {
+	constructor(private readonly store: RightsStore) {}
+
+	async resolve(
+		user: UserPayload,
+		scope: Scope = "global",
+	): Promise<EffectivePermissions> {
+		const chain: Scope[] = scope === "global" ? ["global"] : ["global", scope];
+
+		const roles = new Set<string>();
+		const permissions = new Set<string>();
+		const payloadRoles = user.roles ?? [];
+
+		for (const link of chain) {
+			const storeRoles = await this.store.userRoles(user.id, link);
+			// Token-carried roles are global identity: they contribute at the
+			// `global` link only, so a payload role never inherits a same-named
+			// tenant role's permissions. A global role's global permissions still
+			// reach tenant scopes via the chain.
+			const scopeRoles =
+				link === "global"
+					? new Set<string>([...payloadRoles, ...storeRoles])
+					: new Set<string>(storeRoles);
+
+			for (const role of scopeRoles) {
+				roles.add(role);
+				for (const perm of await this.store.rolePermissions(role, link)) {
+					permissions.add(perm);
+				}
+			}
+
+			for (const grant of await this.store.userGrants(user.id, link)) {
+				permissions.add(grant);
+			}
+		}
+
+		return new ResolvedPermissions(permissions, roles, scope);
+	}
+}

package/src/rights/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Rights data model — Layer 1 of Warden's unified authorization (Epic 56).
+ *
+ * The single resolution point: `resolve(user, scope) → EffectivePermissions`.
+ * Roles → permissions (RBAC) and direct user → permission grants (ACL) are
+ * both keyed by scope (`global` | `{ tenant }`). The store contract is
+ * read-only; concrete drivers (the shipped in-memory one, or a copy-in DB
+ * adapter) provide seeding/mutation on top.
+ */
+
+/**
+ * Resolution scope. `"global"` is the implicit single-tenant scope; a tenant
+ * scope is the discriminated object form so it stays type-distinguishable from
+ * the global sentinel at call sites.
+ */
+export type Scope = "global" | { readonly tenant: string };
+
+/**
+ * The single unification point — a user's effective permissions within a scope.
+ */
+export interface EffectivePermissions {
+	/** True iff the permission is in the resolved set (exact match). */
+	has(permission: string): boolean;
+	/** True iff ALL listed permissions are present (empty list ⇒ vacuously true). */
+	hasAll(permissions: readonly string[]): boolean;
+	/** True iff ANY listed permission is present (empty list ⇒ false). */
+	hasAny(permissions: readonly string[]): boolean;
+	/** The user's effective permissions in this scope (role-derived ∪ direct grants). */
+	readonly permissions: ReadonlySet<string>;
+	/** The roles that contributed (payload ∪ store, within the resolved scope incl. global). */
+	readonly roles: ReadonlySet<string>;
+	/** The scope this was resolved for. */
+	readonly scope: Scope;
+}
+
+/**
+ * Read contract consulted by the resolver. All methods scoped + async: a
+ * DB-backed adapter is inherently async, and the evaluation layer (56.2) is
+ * async end-to-end. Writes are NOT part of this contract — drivers add their
+ * own seeding API.
+ */
+export interface RightsStore {
+	/** Permissions a role grants in the given scope (unknown role ⇒ []). */
+	rolePermissions(role: string, scope: Scope): Promise<readonly string[]>;
+	/** Roles assigned to a user in the given scope (none ⇒ []). */
+	userRoles(userId: string, scope: Scope): Promise<readonly string[]>;
+	/** Direct per-user permission grants (ACL) in the given scope (none ⇒ []). */
+	userGrants(userId: string, scope: Scope): Promise<readonly string[]>;
+}
+
+/**
+ * Stable string key for a scope. `"global"` → `"global"`,
+ * `{ tenant: "X" }` → `"tenant:X"`. Used by drivers to key their storage and
+ * by 56.3 when threading scope through the evaluation context.
+ */
+export function scopeKey(scope: Scope): string {
+	return scope === "global" ? "global" : `tenant:${scope.tenant}`;
+}

package/src/services/main.ts

@@ -0,0 +1,40 @@
+/**
+ * Default `AuthManager` singleton — mirror of Adonis's
+ * `import auth from '@adonisjs/auth/services/main'` shape.
+ *
+ *   import auth from '@c9up/warden/services/main'
+ *
+ *   const result = await auth.verify(bearerToken)
+ *   if (result.authenticated) { ... }
+ *
+ * Populated by `WardenProvider.boot()`.
+ */
+
+import type { AuthManager } from "../AuthManager.js";
+
+let _instance: AuthManager | undefined;
+
+/** @internal Bind the singleton (called by WardenProvider). */
+export function _setAuth(instance: AuthManager): void {
+	_instance = instance;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function _getAuth(): AuthManager | undefined {
+	return _instance;
+}
+
+const auth: AuthManager = new Proxy({} as AuthManager, {
+	get(_target, prop) {
+		if (!_instance) {
+			throw new Error(
+				"[warden] AuthManager singleton accessed before WardenProvider.boot() ran. " +
+					"Check that `@c9up/warden/provider` is listed in your reamrc.ts providers.",
+			);
+		}
+		const value = Reflect.get(_instance, prop, _instance);
+		return typeof value === "function" ? value.bind(_instance) : value;
+	},
+});
+
+export default auth;