@c9up/warden 0.1.0

package/src/standalone.ts

@@ -0,0 +1,128 @@
+/**
+ * Standalone Warden factory — works without the Ream IoC container.
+ *
+ * Same pattern as `createBlackhole()`: construct the auth manager from a
+ * config object, return a typed handle that Express/Fastify/Hono can use.
+ *
+ * @example Express
+ *   import { createWarden } from '@c9up/warden/standalone'
+ *   const warden = createWarden({
+ *     defaultStrategy: 'jwt',
+ *     jwt: { secret: '...', findUser: ..., verifyCredentials: ... },
+ *   })
+ *   app.use(warden.expressMiddleware())
+ *
+ * @example Manual
+ *   const result = await warden.verify(token)
+ *   if (!result.authenticated) return res.status(401).json(result)
+ */
+
+import {
+	AuthManager,
+	type AuthResult,
+	type UserPayload,
+} from "./AuthManager.js";
+import type { WardenConfig } from "./config.js";
+import { JwtStrategy } from "./strategies/JwtStrategy.js";
+
+export interface Warden {
+	/** Verify a bearer token. Returns auth result with user payload. */
+	verify(token: string, strategy?: string): Promise<AuthResult>;
+	/** Authenticate with credentials (email + password). */
+	authenticate(
+		credentials: Record<string, unknown>,
+		strategy?: string,
+	): Promise<AuthResult>;
+	/** Generate a JWT for a user (jwt strategy only). */
+	generateToken(user: UserPayload): Promise<string>;
+	/** The underlying AuthManager for advanced use. */
+	manager: AuthManager;
+	/** Express middleware — extracts Bearer token, verifies, attaches `req.auth`. */
+	expressMiddleware(): (
+		req: Record<string, unknown>,
+		res: Record<string, unknown>,
+		next: () => void,
+	) => void;
+}
+
+/**
+ * Create a standalone Warden instance — no Ream container needed.
+ */
+export function createWarden(config: WardenConfig): Warden {
+	const strategies: Record<string, JwtStrategy> = {};
+
+	if (config.jwt) {
+		strategies.jwt = new JwtStrategy(config.jwt);
+	}
+
+	const manager = new AuthManager({
+		defaultStrategy: config.defaultStrategy ?? "jwt",
+		strategies,
+	});
+
+	return {
+		verify: (token, strategy) => manager.verify(token, strategy),
+		authenticate: (credentials, strategy) =>
+			manager.authenticate(credentials, strategy),
+
+		async generateToken(user: UserPayload): Promise<string> {
+			const jwt = manager.getStrategy("jwt") as JwtStrategy;
+			return jwt.signToken(user);
+		},
+
+		manager,
+
+		expressMiddleware() {
+			return (req, res, next) => {
+				const headers = req.headers as Record<string, string> | undefined;
+				const authHeader = headers?.authorization ?? "";
+				const token =
+					typeof authHeader === "string" && authHeader.startsWith("Bearer ")
+						? authHeader.slice(7)
+						: "";
+
+				if (!token) {
+					(res as { status: (n: number) => { json: (d: unknown) => void } })
+						.status(401)
+						.json({
+							error: {
+								code: "UNAUTHORIZED",
+								message: "Missing authentication token",
+							},
+						});
+					return;
+				}
+
+				manager
+					.verify(token)
+					.then((result) => {
+						if (!result.authenticated || !result.user) {
+							(res as { status: (n: number) => { json: (d: unknown) => void } })
+								.status(401)
+								.json({
+									error: {
+										code: "UNAUTHORIZED",
+										message: result.error ?? "Authentication failed",
+									},
+								});
+							return;
+						}
+						// Attach auth result to the request object (Express convention).
+						req.auth = result;
+						req.user = result.user;
+						next();
+					})
+					.catch(() => {
+						(res as { status: (n: number) => { json: (d: unknown) => void } })
+							.status(500)
+							.json({
+								error: {
+									code: "AUTH_ERROR",
+									message: "Internal authentication error",
+								},
+							});
+					});
+			};
+		},
+	};
+}

package/src/strategies/ApiKeyStrategy.ts

@@ -0,0 +1,54 @@
+/**
+ * API Key authentication strategy.
+ *
+ * Supports: Authorization: Bearer <key> or X-API-Key: <key>
+ *
+ * @implements MISS-8
+ */
+
+import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+
+export interface ApiKeyConfig {
+	headerName?: string;
+	findByKey: (
+		key: string,
+	) => Promise<{ user: UserPayload; scopes?: string[] } | null>;
+}
+
+export class ApiKeyStrategy implements AuthStrategy {
+	name = "api-key";
+	#config: ApiKeyConfig;
+	#headerName: string;
+
+	constructor(config: ApiKeyConfig) {
+		this.#config = config;
+		this.#headerName = config.headerName ?? "x-api-key";
+	}
+
+	/** The HTTP header name to extract the API key from. */
+	get headerName(): string {
+		return this.#headerName;
+	}
+
+	async authenticate(_credentials: {
+		email: string;
+		password: string;
+	}): Promise<AuthResult> {
+		throw new Error(
+			"ApiKeyStrategy does not support credential-based auth. Use verify() with the API key.",
+		);
+	}
+
+	async verify(token: string): Promise<AuthResult> {
+		const result = await this.#config.findByKey(token);
+		if (!result) return { authenticated: false, error: "Invalid API key" };
+
+		const user: UserPayload = { ...result.user };
+		if (result.scopes && result.scopes.length > 0) {
+			// Merge scopes into permissions without mutating source object.
+			const merged = new Set([...(user.permissions ?? []), ...result.scopes]);
+			user.permissions = [...merged];
+		}
+		return { authenticated: true, user };
+	}
+}

package/src/strategies/JwtStrategy.ts

@@ -0,0 +1,217 @@
+/**
+ * JwtStrategy — HMAC-SHA256 JWT authentication strategy.
+ * All signing and verification runs through the Rust warden-engine via NAPI.
+ */
+
+import { randomBytes, randomUUID } from "node:crypto";
+import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import { nativeWarden } from "../native.js";
+import type { TokenBlacklist } from "../TokenBlacklist.js";
+
+interface JwtPayloadData {
+	sub: string;
+	roles?: string[];
+	permissions?: string[];
+	iat: number;
+	exp: number;
+	/** RFC 7519 JWT ID — populated at sign time so revocation can target a single token. */
+	jti: string;
+	[key: string]: unknown;
+}
+
+function sign(payload: JwtPayloadData, secret: string): string {
+	const rust = nativeWarden();
+	if (!rust) {
+		throw new Error(
+			"[WARDEN_NAPI_REQUIRED] The Rust warden-engine binary is required. Build it with `cd packages/warden && pnpm build:napi`.",
+		);
+	}
+	return rust.jwtSign(JSON.stringify(payload), secret);
+}
+
+function verify(token: string, secret: string): JwtPayloadData | null {
+	const rust = nativeWarden();
+	if (!rust) {
+		throw new Error(
+			"[WARDEN_NAPI_REQUIRED] The Rust warden-engine binary is required. Build it with `cd packages/warden && pnpm build:napi`.",
+		);
+	}
+	try {
+		const payloadJson = rust.jwtVerify(token, secret);
+		const payload = JSON.parse(payloadJson) as JwtPayloadData;
+		if (typeof payload.sub !== "string" || !payload.sub) return null;
+		return payload;
+	} catch {
+		return null;
+	}
+}
+
+export interface JwtStrategyConfig {
+	/**
+	 * Active signing secret. New tokens are always signed with this key.
+	 * For zero-downtime key rotation, also pass `previousSecrets` — verify
+	 * tries each entry until one matches, then `revoke()` the rotated key
+	 * by removing it from the config on the next deploy.
+	 */
+	secret: string;
+	/**
+	 * Older secrets accepted at verify time but never used to sign new
+	 * tokens. Empty / omitted by default. Order doesn't matter for
+	 * correctness but ordering by recency keeps the common path fast.
+	 */
+	previousSecrets?: readonly string[];
+	expiresInSeconds?: number;
+	findUser: (id: string) => Promise<UserPayload | null>;
+	verifyCredentials: (
+		email: string,
+		password: string,
+	) => Promise<UserPayload | null>;
+	/**
+	 * Optional blacklist for revocation. When supplied, `verify` rejects
+	 * tokens whose `jti` is present, and `revoke(token)` adds the token's
+	 * `jti` to the blacklist for the remainder of its lifetime. Without a
+	 * blacklist, `revoke()` throws — the call would be a no-op silently.
+	 */
+	blacklist?: TokenBlacklist;
+}
+
+export class JwtStrategy implements AuthStrategy {
+	name = "jwt";
+	#secret: string;
+	/**
+	 * Verify-only secrets ordered active-first. Mirrors `config.secret` at
+	 * index 0 plus any `previousSecrets`. Built once at construction so
+	 * `verify()` doesn't re-allocate per call.
+	 */
+	#verifySecrets: readonly string[];
+	#expiresIn: number;
+	#findUser: JwtStrategyConfig["findUser"];
+	#verifyCredentials: JwtStrategyConfig["verifyCredentials"];
+	#blacklist: TokenBlacklist | undefined;
+
+	constructor(config: JwtStrategyConfig) {
+		if (config.secret.length < 32) {
+			throw new Error("JWT secret must be at least 32 characters");
+		}
+		for (const prev of config.previousSecrets ?? []) {
+			if (prev.length < 32) {
+				throw new Error(
+					"JWT previousSecrets entries must be at least 32 characters",
+				);
+			}
+		}
+		this.#secret = config.secret;
+		this.#verifySecrets = [config.secret, ...(config.previousSecrets ?? [])];
+		this.#expiresIn = config.expiresInSeconds ?? 3600;
+		this.#findUser = config.findUser;
+		this.#verifyCredentials = config.verifyCredentials;
+		this.#blacklist = config.blacklist;
+	}
+
+	/**
+	 * Try each accepted secret in order. First successful verify wins.
+	 * Returns `null` when no secret accepts the token — same semantics as
+	 * the single-secret path so callers see "invalid or expired token".
+	 */
+	#verifyWithRotation(token: string): JwtPayloadData | null {
+		for (const secret of this.#verifySecrets) {
+			const payload = verify(token, secret);
+			if (payload) return payload;
+		}
+		return null;
+	}
+
+	async authenticate(
+		credentials: Record<string, unknown>,
+	): Promise<AuthResult> {
+		const email =
+			typeof credentials.email === "string" ? credentials.email : null;
+		const password =
+			typeof credentials.password === "string" ? credentials.password : null;
+		if (!email || !password) {
+			return { authenticated: false, error: "Email and password are required" };
+		}
+
+		const user = await this.#verifyCredentials(email, password);
+		if (!user) {
+			return { authenticated: false, error: "Invalid credentials" };
+		}
+
+		const token = this.signToken(user);
+		return { authenticated: true, user: { ...user, token } };
+	}
+
+	async verify(token: string): Promise<AuthResult> {
+		const payload = this.#verifyWithRotation(token);
+		if (!payload) {
+			return { authenticated: false, error: "Invalid or expired token" };
+		}
+
+		// Blacklist check runs BEFORE findUser so a revoked token never
+		// triggers a user lookup (cheaper, and avoids leaking user existence
+		// via timing differences between revoked and unknown-user paths).
+		if (this.#blacklist) {
+			// A token with no `jti` cannot be checked against the blacklist
+			// (`isRevoked(undefined)` always returns false), so it could
+			// never be revoked. When revocation is configured we must NOT
+			// trust such a token — reject it rather than let an
+			// unrevocable token through. (signToken always sets a jti;
+			// this guards legacy / externally-signed tokens.)
+			if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+				return { authenticated: false, error: "Token missing jti claim" };
+			}
+			if (await this.#blacklist.isRevoked(payload.jti)) {
+				return { authenticated: false, error: "Token revoked" };
+			}
+		}
+
+		const user = await this.#findUser(payload.sub);
+		if (!user) {
+			return { authenticated: false, error: "User not found" };
+		}
+
+		return { authenticated: true, user };
+	}
+
+	signToken(user: UserPayload): string {
+		const now = Math.floor(Date.now() / 1000);
+		return sign(
+			{
+				sub: user.id,
+				roles: user.roles,
+				permissions: user.permissions,
+				iat: now,
+				exp: now + this.#expiresIn,
+				jti: randomUUID(),
+			},
+			this.#secret,
+		);
+	}
+
+	/**
+	 * Revoke a token until its `exp` claim. Requires the strategy to be
+	 * constructed with a `blacklist` driver — otherwise throws so that a
+	 * caller assuming revocation does not silently succeed against
+	 * a no-op implementation.
+	 *
+	 * Returns `true` when the token was added to the blacklist, `false` when
+	 * the token is already expired (revocation is unnecessary) or unparseable.
+	 */
+	async revoke(token: string): Promise<boolean> {
+		if (!this.#blacklist) {
+			throw new Error(
+				"JwtStrategy.revoke() requires a `blacklist` driver. Pass `{ blacklist: new TokenBlacklist(driver) }` to the constructor.",
+			);
+		}
+		const payload = this.#verifyWithRotation(token);
+		if (!payload) return false;
+		const expMs = payload.exp * 1000;
+		if (expMs <= Date.now()) return false;
+		await this.#blacklist.revoke(payload.jti, expMs);
+		return true;
+	}
+}
+
+export function generateJwtSecret(): string {
+	return randomBytes(48).toString("base64url");
+}

package/src/strategies/SessionStrategy.ts

@@ -0,0 +1,105 @@
+/**
+ * Session-based authentication strategy.
+ *
+ * AdonisJS session guard pattern:
+ *   login stores userId in session, subsequent requests check session.
+ *
+ * @implements MISS-7
+ */
+
+import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import { WardenError } from "../errors.js";
+
+export interface SessionStore {
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+	forget(key: string): void;
+	/**
+	 * Rotate the session id while preserving the data. REQUIRED to mitigate
+	 * session fixation (CWE-384) at login. Ream's `Session.regenerate()`
+	 * implements this; adapters around other session stores MUST too. The
+	 * default ream → warden plumbing exposes the `Session` instance
+	 * directly so this is wired automatically.
+	 */
+	regenerate(): void;
+}
+
+export interface SessionStrategyConfig {
+	sessionKey?: string;
+	findUser: (id: string | number) => Promise<UserPayload | null>;
+}
+
+export class SessionStrategy implements AuthStrategy {
+	name = "session";
+	#config: SessionStrategyConfig;
+	#sessionKey: string;
+
+	constructor(config: SessionStrategyConfig) {
+		this.#config = config;
+		this.#sessionKey = config.sessionKey ?? "auth_user_id";
+	}
+
+	/** Authenticate via email/password — stores user ID in session. */
+	async authenticate(
+		_credentials: { email: string; password: string },
+		_context?: { session?: SessionStore },
+	): Promise<AuthResult> {
+		// Session strategy doesn't handle password verification — that's done
+		// by the caller. We throw a typed sentinel WardenError so AuthManager's
+		// try/catch (which swallows generic errors into a soft AuthResult)
+		// re-throws this one — the design boundary stays unmissable even when
+		// a caller routes through `authManager.authenticate()` instead of
+		// `strategy.authenticate()` directly.
+		throw new WardenError(
+			"USE_LOGIN",
+			"SessionStrategy.authenticate() requires login() instead. Use authManager.login(user, session).",
+			{
+				hint: "Verify the password yourself (e.g. via @c9up/sigil Hash.verify), then call SessionStrategy.login(user, session).",
+			},
+		);
+	}
+
+	/** Verify session — check if user ID is stored in session. */
+	async verify(_token: string): Promise<AuthResult> {
+		return {
+			authenticated: false,
+			error:
+				"SessionStrategy.verify() requires context. Use verifyWithContext().",
+		};
+	}
+
+	/** Verify session with context — check if user ID is stored in session. */
+	async verifyWithContext(
+		_token: string,
+		context?: { session?: SessionStore },
+	): Promise<AuthResult> {
+		if (!context?.session) return { authenticated: false, error: "No session" };
+		const userId = context.session.get(this.#sessionKey);
+		if (!userId) return { authenticated: false, error: "No session user" };
+		if (typeof userId !== "string" && typeof userId !== "number")
+			return { authenticated: false, error: "Invalid session data" };
+		const user = await this.#config.findUser(userId);
+		if (!user) return { authenticated: false, error: "User not found" };
+		return { authenticated: true, user };
+	}
+
+	/**
+	 * Login a user — store their ID in the session.
+	 *
+	 * Rotates the session id BEFORE writing the authenticated user id, so an
+	 * attacker who fed the victim a pre-login session cookie (classic
+	 * session-fixation attack, CWE-384) ends up holding a now-discarded id
+	 * while the victim continues under a fresh one. The driver-side cookie
+	 * migration is handled by Ream's `SessionMiddleware` on the response
+	 * path — see `wasRegenerated()` there.
+	 */
+	async login(user: UserPayload, session: SessionStore): Promise<void> {
+		session.regenerate();
+		session.set(this.#sessionKey, user.id);
+	}
+
+	/** Logout — remove user ID from session. */
+	async logout(session: SessionStore): Promise<void> {
+		session.forget(this.#sessionKey);
+	}
+}