@c9up/warden 0.1.21 → 0.1.23

package/scripts/generate-napi-types.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Generate the TypeScript surface of the native module FROM the Rust.
+ *
+ * `napi-derive`'s `type-def` feature emits one JSON line per exported item
+ * while cargo compiles. Those lines are the source of truth: they are derived
+ * from the `#[napi]` items themselves, so a signature cannot drift from the
+ * Rust without this file changing.
+ *
+ * Hand-written interfaces are what this replaces, and they do drift — nothing
+ * on the TypeScript side notices when a `pub fn` gains a parameter or stops
+ * being `async`.
+ *
+ * One thing napi-rs cannot infer: the shape of a `JsFunction` callback. It
+ * emits `(...args: any[]) => any`. Any such parameter is refined below, by
+ * name, and the script fails if a refinement no longer matches anything — so
+ * the table cannot rot either.
+ *
+ *   TYPE_DEF_TMP_PATH=<file> cargo build -p <crate>
+ *   node scripts/generate-napi-types.mjs <file> <out.d.ts>
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+
+/**
+ * Callback signatures napi-rs erases to `any`, restored here.
+ *
+ * Keyed by `<owner>.<method>`; the value replaces the whole parameter. Every
+ * entry must match, or the script fails: a stale refinement is how a hand
+ * annotation quietly stops describing the Rust.
+ *
+ * Empty while this crate exposes no `JsFunction` parameter — add an entry the
+ * day one appears, rather than letting an `any` through.
+ */
+const CALLBACK_REFINEMENTS = {}
+
+const [input, output] = process.argv.slice(2)
+if (!input || !output) {
+  console.error('usage: generate-napi-types.mjs <type-def file> <out.d.ts>')
+  process.exit(2)
+}
+
+const entries = readFileSync(input, 'utf8')
+  .split('\n')
+  .map((l) => l.trim())
+  .filter(Boolean)
+  .map((l) => JSON.parse(l))
+
+const used = new Set()
+
+/** Apply the refinements that belong to `owner`, tracking which ones matched. */
+function refine(owner, body) {
+  let out = body
+  for (const [key, { from, to }] of Object.entries(CALLBACK_REFINEMENTS)) {
+    const [entryOwner] = key.split('.')
+    if (entryOwner !== owner) continue
+    if (out.includes(from)) {
+      out = out.replace(from, to)
+      used.add(key)
+    }
+  }
+  return out
+}
+
+/**
+ * JSDoc as emitted by napi-derive, indented to sit above its member.
+ *
+ * `*` followed by `/` inside the text closes the comment early — a Rust doc
+ * example holding a cron expression (`0 *​/5 * * *`) is enough to do it, and
+ * the generated file then fails to parse. Escaped rather than stripped, so the
+ * example still reads correctly.
+ */
+function docBlock(doc, indent = '') {
+  if (!doc) return ''
+  // Escape every `*/` EXCEPT the one that closes the block. A Rust doc example
+  // holding a cron expression (`0 */5 * * *`) closes the comment early
+  // otherwise, and the generated file stops parsing — but escaping the closer
+  // too breaks it just as thoroughly, whether the block spans one line or many.
+  const closer = doc.lastIndexOf('*/')
+  const escaped =
+    closer === -1
+      ? doc
+      : doc.slice(0, closer).replaceAll('*/', '*\\/') + doc.slice(closer)
+  return (
+    escaped
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => `${indent}${l}`)
+      .join('\n') + '\n'
+  )
+}
+
+const interfaces = entries.filter((e) => e.kind === 'interface')
+const structs = entries.filter((e) => e.kind === 'struct')
+const impls = new Map(entries.filter((e) => e.kind === 'impl').map((e) => [e.name, e]))
+const fns = entries.filter((e) => e.kind === 'fn')
+
+const out = [
+  '// GENERATED FROM THE RUST — do not edit.',
+  '//',
+  "// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def",
+  '// output. Editing this file by hand puts it back where it started: a',
+  '// description that can disagree with the code it describes.',
+  '',
+]
+
+for (const iface of interfaces) {
+  out.push(docBlock(iface.js_doc))
+  out.push(`export interface ${iface.name} {`)
+  for (const line of iface.def.split('\n')) {
+    out.push(line ? `  ${line.trim()}` : '')
+  }
+  out.push('}', '')
+}
+
+for (const struct of structs) {
+  const impl = impls.get(struct.name)
+  out.push(docBlock(struct.js_doc))
+  out.push(`export declare class ${struct.name} {`)
+  if (impl) {
+    for (const line of refine(struct.name, impl.def).split('\n')) {
+      out.push(line ? `  ${line.trim()}` : '')
+    }
+  }
+  out.push('}', '')
+}
+
+for (const fn of fns) {
+  out.push(docBlock(fn.js_doc))
+  // napi-derive emits the whole declaration for a function, unlike a struct
+  // where `def` holds only the members.
+  const declaration = fn.def.trim()
+  out.push(
+    declaration.startsWith('export declare function')
+      ? `${declaration};`
+      : `export declare function ${fn.name}${declaration};`,
+    '',
+  )
+}
+
+const stale = Object.keys(CALLBACK_REFINEMENTS).filter((k) => !used.has(k))
+if (stale.length > 0) {
+  console.error(
+    `[napi-types] refinement(s) that matched nothing: ${stale.join(', ')}\n` +
+      '[napi-types] the Rust changed under them — update or remove the entry.',
+  )
+  process.exit(1)
+}
+
+writeFileSync(output, out.join('\n'))
+console.log(
+  `[napi-types] ${output} — ${interfaces.length} interface(s), ${structs.length} class(es), ${fns.length} function(s)`,
+)

package/src/AuthManager.ts

@@ -14,7 +14,10 @@ export { sanitizePayload };
 import { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
 import { RightsResolver } from "./rights/RightsResolver.js";
 import type { EffectivePermissions, Scope } from "./rights/types.js";
-import type { SessionStore } from "./strategies/SessionStrategy.js";
+import type {
+	SessionGuardState,
+	SessionStore,
+} from "./strategies/SessionStrategy.js";
 
 export interface UserPayload {
 	id: string;
@@ -453,6 +456,7 @@ export class AuthManager {
 		user: UserPayload,
 		session: SessionStore,
 		strategyName?: string,
+		state?: SessionGuardState,
 	): Promise<void> {
 		const strategy = this.getStrategy(strategyName);
 		if (!isLoginCapable(strategy)) {
@@ -469,7 +473,7 @@ export class AuthManager {
 			guardName: strategyName ?? this.#default,
 			user,
 		});
-		await strategy.login(user, session);
+		await strategy.login(user, session, state);
 		this.#emit(`${prefix}:login_succeeded`, {
 			guardName: strategyName ?? this.#default,
 			user,
@@ -477,12 +481,41 @@ export class AuthManager {
 		});
 	}
 
+	/**
+	 * Revive a user from a remember-me cookie through a session guard, recording
+	 * the attempt on the caller's per-request `state`.
+	 *
+	 * The returned `cookieValue` must replace the one the browser holds — the
+	 * token is single-use and recycled on every successful revival.
+	 */
+	async authenticateViaRememberMeToken(
+		cookieValue: unknown,
+		strategyName?: string,
+		state?: SessionGuardState,
+	): Promise<{ user: UserPayload; cookieValue: string } | null> {
+		const strategy = this.getStrategy(strategyName);
+		if (!isRememberMeCapable(strategy)) {
+			throw new WardenError(
+				"STRATEGY_CANNOT_LOGIN",
+				`Auth strategy '${strategyName ?? this.#default}' has no remember-me tokens.`,
+				{
+					hint: "Remember-me is a session-guard feature. Configure `rememberMeTokens` on the guard, or implement authenticateViaRememberMeToken() on your own.",
+				},
+			);
+		}
+		return strategy.authenticateViaRememberMeToken(cookieValue, state);
+	}
+
 	/**
 	 * Log a user out of a session-capable guard (AdonisJS `auth.use('web').logout()`
 	 * parity). Delegates to the guard's `logout()`. Throws if the resolved guard
 	 * cannot log out.
 	 */
-	async logout(session: SessionStore, strategyName?: string): Promise<void> {
+	async logout(
+		session: SessionStore,
+		strategyName?: string,
+		state?: SessionGuardState,
+	): Promise<void> {
 		const strategy = this.getStrategy(strategyName);
 		if (!isLoginCapable(strategy)) {
 			throw new WardenError(
@@ -490,7 +523,7 @@ export class AuthManager {
 				`Auth strategy '${strategyName ?? this.#default}' does not support session logout.`,
 			);
 		}
-		await strategy.logout(session);
+		await strategy.logout(session, state);
 		this.#emit(`${authEventPrefix(strategy.name)}:logged_out`, {
 			guardName: strategyName ?? this.#default,
 			user: null,
@@ -500,9 +533,38 @@ export class AuthManager {
 }
 
 /** A guard that can start/stop a session for a resolved user (e.g. SessionStrategy). */
+/** A guard that can revive a user from a remember-me cookie. */
+interface RememberMeCapable {
+	authenticateViaRememberMeToken(
+		cookieValue: unknown,
+		state?: SessionGuardState,
+	): Promise<{ user: UserPayload; cookieValue: string } | null>;
+}
+
+/**
+ * Capability check for {@link AuthManager.authenticateViaRememberMeToken}.
+ *
+ * Structural, like {@link isLoginCapable} beside it, and NOT an `instanceof`:
+ * a guard an application wrote itself, carrying the same method, is as capable
+ * as the one shipped here — refusing it would make the built-in strategy the
+ * only one that can ever hold a remember-me token.
+ */
+function isRememberMeCapable(
+	strategy: AuthStrategy,
+): strategy is AuthStrategy & RememberMeCapable {
+	return (
+		"authenticateViaRememberMeToken" in strategy &&
+		typeof strategy.authenticateViaRememberMeToken === "function"
+	);
+}
+
 interface LoginCapable {
-	login(user: UserPayload, session: SessionStore): Promise<void>;
-	logout(session: SessionStore): Promise<void>;
+	login(
+		user: UserPayload,
+		session: SessionStore,
+		state?: SessionGuardState,
+	): Promise<void>;
+	logout(session: SessionStore, state?: SessionGuardState): Promise<void>;
 }
 
 /**

package/src/Authenticator.ts

@@ -23,7 +23,11 @@ import type {
 import { E_UNAUTHORIZED_ACCESS, WardenError } from "./errors.js";
 import type { WardenContext } from "./middleware.js";
 import { sanitizePayload } from "./sanitize.js";
-import type { SessionStore } from "./strategies/SessionStrategy.js";
+import {
+	createSessionGuardState,
+	type SessionGuardState,
+	type SessionStore,
+} from "./strategies/SessionStrategy.js";
 
 /**
  * Guard names Warden accepts for the API-key / access-tokens driver. AdonisJS
@@ -39,6 +43,66 @@ interface StrategyWithContext extends AuthStrategy {
 	verifyWithContext(token: string, ctx: unknown): Promise<AuthResult>;
 }
 
+/**
+ * The strategy behind a guard name, or `undefined` when nothing is registered
+ * under it.
+ *
+ * `getStrategy()` throws for an unknown name — correct when an application
+ * asks for a guard by name, wrong here: this is a capability probe across a
+ * list, and a name that resolves to nothing simply is not a session guard.
+ */
+function strategyOrUndefined(
+	auth: AuthManager,
+	name: string,
+): AuthStrategy | undefined {
+	try {
+		return auth.getStrategy(name);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * A guard that can keep a user signed in: mint a token, name its cookie, read
+ * one back, and seat the session that follows.
+ */
+interface RememberMeIssuer {
+	issueRememberMeToken(user: UserPayload): Promise<string | null>;
+	authenticateViaRememberMeToken(
+		cookieValue: unknown,
+		state?: SessionGuardState,
+	): Promise<{ user: UserPayload; cookieValue: string } | null>;
+	seatSession(user: UserPayload, session: SessionStore): void;
+	revokeRememberMeToken(cookieValue: unknown): Promise<void>;
+	readonly rememberMeCookieName: string;
+	readonly rememberMeAgeSeconds: number;
+}
+
+/**
+ * Structural, like every other capability probe here: a guard an application
+ * wrote itself, carrying the same three members, keeps users signed in just as
+ * well as the one shipped with the package.
+ */
+function isRememberMeIssuer(
+	strategy: AuthStrategy,
+): strategy is AuthStrategy & RememberMeIssuer {
+	return (
+		typeof Reflect.get(strategy, "issueRememberMeToken") === "function" &&
+		typeof Reflect.get(strategy, "authenticateViaRememberMeToken") ===
+			"function" &&
+		typeof Reflect.get(strategy, "seatSession") === "function" &&
+		typeof Reflect.get(strategy, "revokeRememberMeToken") === "function" &&
+		typeof Reflect.get(strategy, "rememberMeCookieName") === "string" &&
+		typeof Reflect.get(strategy, "rememberMeAgeSeconds") === "number"
+	);
+}
+
+/** Whether the guard behind `name` authenticates from the request context. */
+function isSessionGuard(auth: AuthManager, name: string): boolean {
+	const strategy = strategyOrUndefined(auth, name);
+	return strategy !== undefined && hasVerifyWithContext(strategy);
+}
+
 function hasVerifyWithContext(
 	strategy: AuthStrategy,
 ): strategy is StrategyWithContext {
@@ -115,7 +179,6 @@ export async function tryAuthenticate(
 		bearerToken: string;
 		apiKey: string;
 		session: SessionStore | undefined;
-		hasSessionStrategy: boolean;
 	},
 ): Promise<AuthAttempt> {
 	const { bearerToken, apiKey, session } = creds;
@@ -126,21 +189,22 @@ export async function tryAuthenticate(
 	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;
-				}
+			// A session guard is one that can verify FROM THE REQUEST CONTEXT,
+			// not one registered under a particular name. `guards: { web:
+			// sessionGuard(...) }` is the documented config shape, and matching
+			// on the literal "session" sent it down the bearer-token path — so
+			// `auth.use('web').authenticate()` never read the session at all.
+			const strategy = strategyOrUndefined(auth, strategyName);
+			const verifyWithContext =
+				strategy && hasVerifyWithContext(strategy)
+					? strategy.verifyWithContext
+					: undefined;
+			if (verifyWithContext !== undefined) {
+				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 {
 				// Native-first credential, other transport as fallback so a
 				// single-credential client still authenticates (and an invalid
@@ -185,6 +249,12 @@ export class GuardAccessor {
 	readonly #auth: AuthManager;
 	readonly #name: string;
 	readonly #parent: Authenticator;
+	/**
+	 * The session-guard flags for THIS request. They live on the accessor —
+	 * which the Authenticator builds and caches per request — and never on the
+	 * strategy, which is built once from config and shared by every request.
+	 */
+	readonly #state: SessionGuardState = createSessionGuardState();
 
 	constructor(
 		ctx: WardenContext,
@@ -209,19 +279,203 @@ export class GuardAccessor {
 		return this.user !== undefined;
 	}
 
+	/**
+	 * Whether the user was revived from a remember-me cookie rather than
+	 * signing in.
+	 *
+	 * This is the distinction that lets an app demand the password again before
+	 * something sensitive — changing an email, spending money, deleting an
+	 * account.
+	 */
+	get viaRemember(): boolean {
+		return this.#state.viaRemember;
+	}
+
+	/** Whether a remember-me cookie was tried at all on this request. */
+	get attemptedViaRemember(): boolean {
+		return this.#state.attemptedViaRemember;
+	}
+
+	/**
+	 * Whether `logout()` has run during this request.
+	 *
+	 * A handler that logs out and then keeps working — clearing a cart, writing
+	 * an audit line — could not otherwise tell the session was already gone.
+	 */
+	get isLoggedOut(): boolean {
+		return this.#state.isLoggedOut;
+	}
+
+	/**
+	 * Revive the user from a remember-me cookie, recording on this request that
+	 * one was tried and whether it worked.
+	 *
+	 * The returned `cookieValue` must replace the one the browser holds: the
+	 * token is single-use and is recycled on every successful revival.
+	 */
+	authenticateViaRememberMeToken(
+		cookieValue: unknown,
+	): Promise<{ user: UserPayload; cookieValue: string } | null> {
+		return this.#auth.authenticateViaRememberMeToken(
+			cookieValue,
+			this.#name,
+			this.#state,
+		);
+	}
+
 	/** Authenticate the request using only this guard (throws on failure). */
 	authenticate(): Promise<void> {
 		return this.#parent.authenticateUsing([this.#name]);
 	}
 
-	/** Log a user in through this guard (session guards). */
-	login(user: UserPayload): Promise<void> {
-		return this.#auth.login(user, this.#requireSession(), this.#name);
+	/**
+	 * Revive this request from the remember-me cookie, if the browser holds one.
+	 *
+	 * The token is single-use: a success recycles the cookie and re-seats the
+	 * session, so a stolen copy stops working the moment the real user comes
+	 * back, and the rest of the request sees an ordinary signed-in user.
+	 */
+	async tryRememberMeCookie(): Promise<UserPayload | undefined> {
+		const read = this.#ctx.request.encryptedCookie;
+		const write = this.#ctx.response.encryptedCookie;
+		const session = this.#ctx.session;
+		if (!read || !write || !session) return undefined;
+
+		const strategy = strategyOrUndefined(this.#auth, this.#name);
+		if (!strategy || !isRememberMeIssuer(strategy)) return undefined;
+
+		const cookie = read.call(this.#ctx.request, strategy.rememberMeCookieName);
+		if (!cookie) return undefined;
+
+		const revived = await strategy.authenticateViaRememberMeToken(
+			cookie,
+			this.#state,
+		);
+		if (!revived) return undefined;
+
+		write.call(
+			this.#ctx.response,
+			strategy.rememberMeCookieName,
+			revived.cookieValue,
+			{ maxAge: strategy.rememberMeAgeSeconds, httpOnly: true },
+		);
+		// Seat the session WITHOUT `login()`: that method means a password was
+		// typed, and it clears `viaRemember` — the one thing this path exists to
+		// report, and what an app checks before letting someone change an email
+		// or spend money.
+		strategy.seatSession(revived.user, session);
+		return revived.user;
+	}
+
+	/**
+	 * Log a user in through this guard (session guards).
+	 *
+	 * `remember` mints a remember-me token and writes it as an ENCRYPTED,
+	 * httpOnly cookie — the cookie IS the credential, so anyone who can read it
+	 * can present it. Without `remember`, any cookie the browser still holds is
+	 * cleared: signing in without ticking the box has to REVOKE the standing
+	 * permission, not leave it in place.
+	 */
+	async login(user: UserPayload, remember = false): Promise<void> {
+		const session = this.#requireSession();
+		const issued = remember ? await this.#issueRememberMe(user) : undefined;
+		if (!remember) this.#clearRememberMe();
+		try {
+			await this.#auth.login(user, session, this.#name, this.#state);
+		} catch (err) {
+			// The token is minted and the cookie sent before the session is
+			// seated — upstream's order, and it has to be, because the cookie
+			// belongs on the same response.
+			//
+			// NAMED DEVIATION — upstream does not roll any of this back; it has
+			// no need to, because its session write is a map assignment that
+			// cannot fail. Here `login()` also fires listeners, any of which
+			// can throw, so the window is real.
+			//
+			// And clearing the cookie is not enough: the token was PERSISTED,
+			// and its value reached the wire, where it may have been captured
+			// — a proxy log, an already-flushed response. Revoking the row is
+			// what makes a failed sign-in leave nothing usable behind.
+			if (issued !== undefined) await this.#revokeRememberMe(issued);
+			throw err;
+		}
+	}
+
+	/** Undo an issued remember-me: the stored row first, then the cookie. */
+	async #revokeRememberMe(value: string): Promise<void> {
+		const strategy = strategyOrUndefined(this.#auth, this.#name);
+		if (strategy && isRememberMeIssuer(strategy)) {
+			// Best-effort: a store that is itself down must not replace the
+			// caller's error with its own.
+			await strategy.revokeRememberMeToken(value).catch(() => undefined);
+		}
+		this.#clearRememberMe();
+	}
+
+	/**
+	 * Mint the token and put it in the browser, or say why it cannot.
+	 *
+	 * Returns the minted value so a failure further along can revoke it: a
+	 * persisted token nobody can reach is still a credential.
+	 */
+	async #issueRememberMe(user: UserPayload): Promise<string> {
+		const strategy = strategyOrUndefined(this.#auth, this.#name);
+		if (!strategy || !isRememberMeIssuer(strategy)) {
+			throw new WardenError(
+				"REMEMBER_ME_UNAVAILABLE",
+				`Guard '${this.#name}' cannot keep a user signed in: no remember-me tokens are configured.`,
+				{
+					hint: "Set `rememberMeTokens` on the session guard, or call login(user) without the remember flag.",
+				},
+			);
+		}
+		const value = await strategy.issueRememberMeToken(user);
+		if (value === null) {
+			throw new WardenError(
+				"REMEMBER_ME_UNAVAILABLE",
+				`Guard '${this.#name}' cannot keep a user signed in: no remember-me tokens are configured.`,
+				{
+					hint: "Set `rememberMeTokens` on the session guard, or call login(user) without the remember flag.",
+				},
+			);
+		}
+		const write = this.#ctx.response.encryptedCookie;
+		if (!write) {
+			throw new WardenError(
+				"REMEMBER_ME_UNAVAILABLE",
+				"This host cannot write an encrypted cookie, which is where the remember-me token lives.",
+				{
+					hint: "Use a host whose response exposes encryptedCookie(), or call login(user) without the remember flag.",
+				},
+			);
+		}
+		try {
+			write.call(this.#ctx.response, strategy.rememberMeCookieName, value, {
+				maxAge: strategy.rememberMeAgeSeconds,
+				httpOnly: true,
+			});
+		} catch (err) {
+			// The row exists and the browser will never hold it: a credential
+			// nobody can reach is still one, so it does not survive the failure.
+			await strategy.revokeRememberMeToken(value).catch(() => undefined);
+			throw err;
+		}
+		return value;
+	}
+
+	/** Drop whatever remember-me cookie the browser is still holding. */
+	#clearRememberMe(): void {
+		const strategy = strategyOrUndefined(this.#auth, this.#name);
+		if (!strategy || !isRememberMeIssuer(strategy)) return;
+		this.#ctx.response.clearCookie?.call(
+			this.#ctx.response,
+			strategy.rememberMeCookieName,
+		);
 	}
 
 	/** Log the current user out of this guard (session guards). */
 	logout(): Promise<void> {
-		return this.#auth.logout(this.#requireSession(), this.#name);
+		return this.#auth.logout(this.#requireSession(), this.#name, this.#state);
 	}
 
 	#requireSession(): SessionStore {
@@ -355,12 +609,29 @@ export class Authenticator {
 			{ guardName },
 		);
 		const creds = extractCredentials(this.#ctx, this.#auth);
-		const hasSessionStrategy = names.includes("session");
-		const { result, viaGuard, attemptCount, crashCount } =
-			await tryAuthenticate(this.#auth, names, {
-				...creds,
-				hasSessionStrategy,
-			});
+		// Same rule as the loop above: a session guard is one that verifies from
+		// the request context. Matching the literal name meant a guard called
+		// `web` never got the login redirect a browser needs.
+		const hasSessionStrategy = names.some((name) =>
+			isSessionGuard(this.#auth, name),
+		);
+		const attempt = await tryAuthenticate(this.#auth, names, creds);
+		const { attemptCount, crashCount } = attempt;
+		let result = attempt.result;
+		let viaGuard = attempt.viaGuard;
+
+		// No credential answered, but the browser may still hold a remember-me
+		// cookie — that is what "keep me signed in" means, and nothing read it.
+		if (!result?.authenticated && hasSessionStrategy) {
+			for (const name of names) {
+				const user = await this.use(name).tryRememberMeCookie();
+				if (user) {
+					result = { authenticated: true, user };
+					viaGuard = name;
+					break;
+				}
+			}
+		}
 
 		if (result?.authenticated && result.user) {
 			this.#user = result.user;

package/src/config.ts

@@ -61,7 +61,14 @@ export interface JwtConfig {
  * 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).
+ * are shared per-app instances rather than one built per request.
+ *
+ * Because the instance is shared, a guard must hold NO per-request state: the
+ * flags a request asks about — `viaRemember`, `attemptedViaRemember`,
+ * `isLoggedOut` — live on the per-request guard the Authenticator hands out
+ * (`auth.use(name)`), and a strategy method records into the state it is
+ * given. A flag stored on the strategy would answer the next request with the
+ * previous one's truth.
  */
 export type GuardFactory = AuthStrategy;