@c9up/warden 0.1.17 → 0.1.18

package/src/middleware.ts

@@ -20,7 +20,7 @@ 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 { Ability, PolicyContainerResolver } from "./bouncer/types.js";
 import type { ScopeRequestContext } from "./config.js";
 import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
 import {
@@ -56,6 +56,33 @@ interface ContainerResolver {
 	make(token: ResolvableToken): Promise<unknown>;
 }
 
+/**
+ * Adapt the request resolver to the shape the Bouncer needs for policy DI.
+ *
+ * The context resolver is deliberately untyped (`Promise<unknown>`) — it
+ * resolves string tokens too. `instanceof` is what proves the instance is the
+ * policy that was asked for: a real check rather than an assertion, and it
+ * catches a host resolver that hands back something else instead of letting a
+ * wrong object reach the policy's methods.
+ */
+function policyResolver(
+	resolver: ContainerResolver | undefined,
+): PolicyContainerResolver | undefined {
+	if (resolver === undefined) return undefined;
+	return {
+		async make<T>(ctor: new (...args: never[]) => T): Promise<T> {
+			const instance = await resolver.make(ctor);
+			if (!(instance instanceof ctor)) {
+				throw new WardenError(
+					"POLICY_RESOLUTION_FAILED",
+					`The container resolved "${ctor.name}" to something else — a policy must be an instance of the class that was requested.`,
+				);
+			}
+			return instance;
+		},
+	};
+}
+
 /**
  * Agnostic authorization slot — structurally Ream's `Authorizer` interface (and
  * Adonis's bouncer contract): `allows` / `denies` / `authorize`. Typed as the
@@ -317,6 +344,19 @@ export async function silentAuth(ctx: WardenContext, next: WardenNext) {
 	await next();
 }
 
+/**
+ * Merge values into the request's view state, when the app has a template
+ * layer. A no-op outside an HTTP render, or in an app with no views.
+ */
+function shareWithView(
+	ctx: WardenContext,
+	values: Record<string, unknown>,
+): void {
+	const view = Reflect.get(Object(ctx), "view");
+	const share = Reflect.get(Object(view), "share");
+	if (typeof share === "function") share.call(view, values);
+}
+
 /**
  * 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
@@ -329,6 +369,10 @@ function ensureAuthenticator(
 	if (ctx.auth instanceof Authenticator) return ctx.auth;
 	const authenticator = new Authenticator(ctx, auth);
 	ctx.auth = authenticator;
+	// Share it with the request's view, as AdonisJS's auth does, so a migrated
+	// template reads `{{ auth.user.email }}` / `@if(auth.isAuthenticated)`
+	// unchanged. Both middlewares funnel through here, so one share covers them.
+	shareWithView(ctx, { auth: authenticator });
 	return authenticator;
 }
 
@@ -405,10 +449,19 @@ export async function initializeBouncer(ctx: WardenContext, next: WardenNext) {
 		? await registry.resolveScope(toScopeContext(ctx))
 		: "global";
 
-	ctx.bouncer = new Bouncer(user, registry?.abilities, registry?.policies, {
+	const bouncer = new Bouncer(user, registry?.abilities, registry?.policies, {
 		scope,
 		resolver,
+		// The REQUEST's resolver, so a policy taking constructor dependencies
+		// gets them — and gets this request's, not the application container's.
+		// It was never passed, so `@inject()` on a policy silently resolved to a
+		// plain `new Policy()` with no dependencies at all.
+		containerResolver: policyResolver(ctx.containerResolver),
 	});
+	ctx.bouncer = bouncer;
+	// Share the checks with the request's view so `@can(...)` resolves them,
+	// as AdonisJS's own middleware does.
+	shareWithView(ctx, bouncer.templateHelpers);
 	await next();
 }
 

package/src/quasar.ts

@@ -27,20 +27,12 @@ function isConnectionSource(value: unknown): value is ConnectionSource {
 
 function isRedisLikeClient(value: unknown): value is RedisLikeClient {
 	if (typeof value !== "object" || value === null) return false;
-	// The commands this driver actually issues. A connection missing one of
-	// them would fail on the first revocation, far from the cause.
-	const required = [
-		"get",
-		"set",
-		"del",
-		"exists",
-		"keys",
-		"sadd",
-		"srem",
-		"smembers",
-		"expire",
-		"ttl",
-	];
+	// The commands this driver actually issues — the whole of `RedisLikeClient`.
+	// A connection missing one would fail on the first revocation, far from the
+	// cause. Nothing more: the driver documents itself as needing only `set`
+	// with an "EX" ttl and `exists`, so demanding sets or key scans here would
+	// reject a client that works perfectly well.
+	const required = ["set", "exists"];
 	return required.every(
 		(name) => typeof Reflect.get(value, name) === "function",
 	);

package/src/strategies/ApiKeyStrategy.ts

@@ -6,7 +6,12 @@
  * @implements MISS-8
  */
 
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 
 export interface ApiKeyConfig {
 	headerName?: string;
@@ -42,6 +47,23 @@ export class ApiKeyStrategy implements AuthStrategy {
 		);
 	}
 
+	/**
+	 * The header a test client sends to present `key` (AdonisJS
+	 * `authenticateAsClient`).
+	 *
+	 * Takes the KEY, not a user: an API key is issued out of band, so a test
+	 * seeds one through `findByKey` and hands that same key here — inventing a
+	 * key the resolver has never seen would prove nothing.
+	 */
+	authenticateAsClient(key: string): AuthClientResponse {
+		return {
+			headers: {
+				authorization: `Bearer ${key}`,
+				[this.#headerName]: key,
+			},
+		};
+	}
+
 	async verify(token: string): Promise<AuthResult> {
 		const result = await this.#config.findByKey(token);
 		if (!result) return { authenticated: false, error: "Invalid API key" };

package/src/strategies/BasicAuthStrategy.ts

@@ -0,0 +1,127 @@
+/**
+ * HTTP Basic authentication (AdonisJS `basic_auth` guard).
+ *
+ * The browser prompts for credentials and resends them on every request; there
+ * is no session and nothing to log out of. That makes it the right fit for a
+ * machine-to-machine endpoint or an internal tool behind TLS, and the wrong fit
+ * for a user-facing login — the credentials travel on EVERY request, so without
+ * TLS they are exposed on every one of them.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
+
+export interface BasicAuthConfig {
+	/**
+	 * Resolve a user by the username half of the header, and say whether the
+	 * password matches. Returning null is an unknown user.
+	 */
+	verifyCredentials: (
+		uid: string,
+		password: string,
+	) => Promise<UserPayload | null>;
+	/**
+	 * The realm announced in `WWW-Authenticate`. The browser shows it in its
+	 * prompt, so it should name what is being unlocked.
+	 */
+	realm?: string;
+}
+
+/** The `WWW-Authenticate` value a 401 must carry for the browser to prompt. */
+export function basicAuthChallenge(realm = "Restricted"): string {
+	// The realm is quoted, so a quote inside it would end the field early.
+	return `Basic realm="${realm.replace(/["\\]/g, "")}", charset="UTF-8"`;
+}
+
+/**
+ * Split an `Authorization: Basic` header into its two halves.
+ *
+ * RFC 7617 splits on the FIRST colon: a password may contain colons, a username
+ * may not. Splitting on the last one would silently accept the wrong pair.
+ */
+export function decodeBasicAuth(
+	header: string | undefined,
+): { uid: string; password: string } | null {
+	if (!header) return null;
+	const [scheme, encoded] = header.split(" ");
+	if ((scheme ?? "").toLowerCase() !== "basic" || !encoded) return null;
+	let decoded: string;
+	try {
+		decoded = Buffer.from(encoded, "base64").toString("utf8");
+	} catch {
+		return null;
+	}
+	const separator = decoded.indexOf(":");
+	if (separator === -1) return null;
+	return {
+		uid: decoded.slice(0, separator),
+		password: decoded.slice(separator + 1),
+	};
+}
+
+export class BasicAuthStrategy implements AuthStrategy {
+	name = "basic_auth";
+	readonly #config: BasicAuthConfig;
+
+	constructor(config: BasicAuthConfig) {
+		this.#config = config;
+	}
+
+	/** The challenge to send with a 401 so the browser prompts. */
+	get challenge(): string {
+		return basicAuthChallenge(this.#config.realm);
+	}
+
+	/** Authenticate a `{ uid, password }` pair directly. */
+	async authenticate(
+		credentials: Record<string, unknown>,
+	): Promise<AuthResult> {
+		const uid = credentials.uid ?? credentials.username ?? credentials.email;
+		const password = credentials.password;
+		if (typeof uid !== "string" || typeof password !== "string") {
+			return { authenticated: false, error: "Invalid credentials" };
+		}
+		const user = await this.#config.verifyCredentials(uid, password);
+		// One message for an unknown user and for a wrong password: telling them
+		// apart turns the endpoint into a username oracle.
+		if (!user) return { authenticated: false, error: "Invalid credentials" };
+		return { authenticated: true, user };
+	}
+
+	/** Authenticate from the raw `Authorization` header value. */
+	async verify(header: string): Promise<AuthResult> {
+		const decoded = decodeBasicAuth(header);
+		if (!decoded) return { authenticated: false, error: "Invalid credentials" };
+		return this.authenticate(decoded);
+	}
+
+	/**
+	 * Build the header a client sends (AdonisJS `authenticateAsClient`) — what a
+	 * test uses to act as a user without reproducing the encoding by hand.
+	 */
+	authenticateAsClient(uid: string, password: string): AuthClientResponse {
+		const encoded = Buffer.from(`${uid}:${password}`, "utf8").toString(
+			"base64",
+		);
+		return { headers: { authorization: `Basic ${encoded}` } };
+	}
+}
+
+/**
+ * Compare two secrets without leaking how far they matched.
+ *
+ * Exposed because an app implementing `verifyCredentials` against a plaintext
+ * shared secret needs it — a plain `===` returns sooner on an early mismatch,
+ * and that difference is measurable.
+ */
+export function safeCompare(a: string, b: string): boolean {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}

package/src/strategies/JwtStrategy.ts

@@ -4,7 +4,12 @@
  */
 
 import { randomBytes, randomUUID } from "node:crypto";
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 import { nativeWarden } from "../native.js";
 import type { TokenBlacklist } from "../TokenBlacklist.js";
 
@@ -214,6 +219,18 @@ export class JwtStrategy implements AuthStrategy {
 	 * Returns `true` when the token was added to the blacklist, `false` when
 	 * the token is already expired (revocation is unnecessary) or unparseable.
 	 */
+	/**
+	 * The header a test client sends to be `user` (AdonisJS
+	 * `authenticateAsClient`).
+	 *
+	 * Signs a real token with the configured secret, so the request travels the
+	 * SAME verification path as production — a test that forges its own header
+	 * proves only that the forgery works.
+	 */
+	authenticateAsClient(user: UserPayload): AuthClientResponse {
+		return { headers: { authorization: `Bearer ${this.signToken(user)}` } };
+	}
+
 	async revoke(token: string): Promise<boolean> {
 		if (!this.#blacklist) {
 			throw new Error(

package/src/strategies/SessionStrategy.ts

@@ -7,8 +7,19 @@
  * @implements MISS-7
  */
 
-import type { AuthResult, AuthStrategy, UserPayload } from "../AuthManager.js";
+import type {
+	AuthClientResponse,
+	AuthResult,
+	AuthStrategy,
+	UserPayload,
+} from "../AuthManager.js";
 import { WardenError } from "../errors.js";
+import {
+	decodeTokenValue,
+	mintRememberMeToken,
+	type RememberMeTokenDriver,
+	verifyAndRecycleRememberMeToken,
+} from "../RememberMeToken.js";
 
 export interface SessionStore {
 	get(key: string): unknown;
@@ -33,8 +44,27 @@ export interface SessionStore {
 export interface SessionStrategyConfig {
 	sessionKey?: string;
 	findUser: (id: string | number) => Promise<UserPayload | null>;
+	/**
+	 * Turn on "keep me signed in". Adonis calls the equivalent flag
+	 * `useRememberMeTokens`; without a driver there is nowhere to persist the
+	 * token, so passing one IS the opt-in.
+	 */
+	rememberMeTokens?: RememberMeTokenDriver;
+	/**
+	 * How long a remember-me token lives. Adonis defaults to two years, and a
+	 * number here is SECONDS (`durationToSeconds` semantics).
+	 */
+	rememberMeAge?: number;
+	/**
+	 * Cookie name holding the token. Adonis derives `remember_<guard>`; the
+	 * default matches the `web` guard an app is most likely migrating.
+	 */
+	rememberMeCookieName?: string;
 }
 
+/** Two years, Adonis' `rememberMeTokensAge` default. */
+const DEFAULT_REMEMBER_AGE_SECONDS = 63_072_000;
+
 export class SessionStrategy implements AuthStrategy {
 	name = "session";
 	#config: SessionStrategyConfig;
@@ -45,6 +75,71 @@ export class SessionStrategy implements AuthStrategy {
 		this.#sessionKey = config.sessionKey ?? "auth_user_id";
 	}
 
+	/** The cookie the remember-me token travels in. */
+	get rememberMeCookieName(): string {
+		return this.#config.rememberMeCookieName ?? "remember_web";
+	}
+
+	/** Whether "keep me signed in" is wired at all. */
+	get usesRememberMeTokens(): boolean {
+		return this.#config.rememberMeTokens !== undefined;
+	}
+
+	#rememberMeAge(): number {
+		return this.#config.rememberMeAge ?? DEFAULT_REMEMBER_AGE_SECONDS;
+	}
+
+	/**
+	 * Mint a remember-me token for `user` and return the cookie value the caller
+	 * must set. `null` when the feature is not wired.
+	 */
+	async issueRememberMeToken(user: UserPayload): Promise<string | null> {
+		const driver = this.#config.rememberMeTokens;
+		if (!driver) return null;
+		const minted = mintRememberMeToken(user.id, this.#rememberMeAge());
+		await driver.create(minted.stored);
+		return minted.value;
+	}
+
+	/**
+	 * Authenticate from a remember-me cookie, and RECYCLE it: the returned
+	 * `cookieValue` must replace the one the browser holds.
+	 *
+	 * The user is re-read through `findUser`, never trusted from the token — a
+	 * token outlives the row it points at, and a deleted or disabled account
+	 * must not walk back in through a cookie.
+	 */
+	async authenticateViaRememberMeToken(
+		cookieValue: unknown,
+	): Promise<{ user: UserPayload; cookieValue: string } | null> {
+		const driver = this.#config.rememberMeTokens;
+		if (!driver) return null;
+
+		const recycled = await verifyAndRecycleRememberMeToken(
+			driver,
+			cookieValue,
+			this.#rememberMeAge(),
+		);
+		if (!recycled) return null;
+
+		const user = await this.#config.findUser(recycled.userId);
+		if (!user) return null;
+
+		return { user, cookieValue: recycled.value };
+	}
+
+	/**
+	 * Drop the token behind `cookieValue`. Called on logout so the persistent
+	 * credential dies with the session — Adonis deletes the row too.
+	 */
+	async revokeRememberMeToken(cookieValue: unknown): Promise<void> {
+		const driver = this.#config.rememberMeTokens;
+		if (!driver) return;
+		const decoded = decodeTokenValue(cookieValue);
+		if (!decoded) return;
+		await driver.delete(decoded.identifier);
+	}
+
 	/** Authenticate via email/password — stores user ID in session. */
 	async authenticate(
 		_credentials: { email: string; password: string },
@@ -104,7 +199,23 @@ export class SessionStrategy implements AuthStrategy {
 		session.put(this.#sessionKey, user.id);
 	}
 
-	/** Logout — remove user ID from session. */
+	/**
+	 * The session entry a test client needs to be `user` (AdonisJS
+	 * `authenticateAsClient`).
+	 *
+	 * Returns the same key `login()` writes, so the request is authenticated by
+	 * the guard's own logic rather than by the test knowing where the id lives.
+	 */
+	authenticateAsClient(user: UserPayload): AuthClientResponse {
+		return { session: { [this.#sessionKey]: user.id } };
+	}
+
+	/**
+	 * Logout — remove the user id from the session.
+	 *
+	 * The remember-me token is revoked separately through
+	 * {@link revokeRememberMeToken}, because only the caller holds the cookie.
+	 */
 	async logout(session: SessionStore): Promise<void> {
 		session.forget(this.#sessionKey);
 	}