@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/core/auth/api.js

@@ -1,14 +1,26 @@
+import { serverLog } from "../../helpers/serverLog.js";
+import { forwardedIp } from "../requestParser.js";
 import { checkPermission } from "./authorize.js";
 import { generateToken, hashPassword, verifyPassword } from "./passwords.js";
-import { createMemoryRateLimit } from "./throttle.js";
+import { createMemoryRateLimit, fleetRateLimit } from "./throttle.js";
 import { authFailureMessage } from "./tokens.js";
-import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpUri, verifyTotp } from "./totp.js";
+import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpStep, totpUri } from "./totp.js";
 import { createHash } from "node:crypto";
 //#region src/core/auth/api.ts
-/** The user agent, off whatever carried the request. Nothing else here reads headers, so it is done once. */
+/**
+* The user agent and the address, off whatever carried the request — what lets somebody tell their devices apart.
+* Nothing else here reads headers, so it is done once. The address is the host's when it resolved one, the proxies'
+* otherwise; it names a session in a list and decides nothing.
+*/
 var clientOf = (carrier) => {
-	const userAgent = carrier?.headers["user-agent"];
-	return typeof userAgent === "string" && userAgent ? { userAgent } : void 0;
+	if (!carrier) return;
+	const userAgent = carrier.headers["user-agent"];
+	const ip = carrier.ip || forwardedIp(carrier.headers);
+	const client = {
+		...typeof userAgent === "string" && userAgent ? { userAgent } : {},
+		...ip ? { ip } : {}
+	};
+	return client.userAgent || client.ip ? client : void 0;
 };
 var refuse = (status, error, reason) => ({
 	ok: false,
@@ -88,7 +100,7 @@ var profileOf = (account) => ({
 * form without either owning it.
 */
 var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
-	const { verifyPassword: verifyPassword$1 = verifyPassword, hashPassword: hashPassword$1 = hashPassword, generateToken: generateToken$1 = generateToken, verifyOnSignup = false, adminPermission = "userManage", impersonationPermission, password: policy = {}, rateLimit = createMemoryRateLimit(), onMailError, onEvent, mfaIssuer, csrf } = config;
+	const { verifyPassword: verifyPassword$1 = verifyPassword, hashPassword: hashPassword$1 = hashPassword, generateToken: generateToken$1 = generateToken, verifyOnSignup = false, adminPermission = "userManage", impersonationPermission, password: policy = {}, rateLimit = fleetRateLimit() ?? createMemoryRateLimit(), onMailError, onEvent, mfaIssuer, csrf } = config;
 	/** Never awaited, never able to throw: a logging outage must not become an authentication outage. */
 	const record = (event) => {
 		if (!onEvent) return;
@@ -98,7 +110,7 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				at: Math.floor(Date.now() / 1e3)
 			});
 		} catch (error) {
-			console.error("[auth] security event handler threw:", error);
+			serverLog.error("auth", "security event handler threw", error);
 		}
 	};
 	/**
@@ -132,7 +144,7 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 		try {
 			await adapters.sendMail?.(message);
 		} catch (error) {
-			(onMailError ?? ((cause) => console.error("[auth] could not send mail:", cause)))(error, {
+			(onMailError ?? ((cause) => serverLog.error("auth", "could not send mail", cause)))(error, {
 				to: message.to,
 				template: message.template
 			});
@@ -386,6 +398,11 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				return refuse(401, authFailureMessage[reason], reason);
 			}
 			if ((capabilities.mfa ? await adapters.loadMfa?.(account.id) : void 0)?.confirmedAt) {
+				throttleSucceeded({
+					action: "login",
+					key: username,
+					carrier
+				});
 				record({
 					type: "login.mfa-required",
 					userId: account.id,
@@ -444,17 +461,23 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			const stored = mfa.recoveryCodes ?? [];
 			const supplied = digestRecoveryCode(code);
 			const usedRecovery = stored.includes(supplied);
-			if (!usedRecovery && !verifyTotp(mfa.secret, code)) {
+			const step = usedRecovery ? void 0 : totpStep(mfa.secret, code);
+			const replayed = step !== void 0 && mfa.lastUsedStep !== void 0 && step <= mfa.lastUsedStep;
+			if (!usedRecovery && (step === void 0 || replayed)) {
 				record({
 					type: "mfa.failed",
 					userId,
-					carrier
+					carrier,
+					...replayed ? { detail: { replayed: true } } : {}
 				});
 				return refuse(401, "Invalid code");
 			}
-			if (usedRecovery) await adapters.saveMfa?.(userId, {
+			await adapters.saveMfa?.(userId, usedRecovery ? {
 				...mfa,
 				recoveryCodes: stored.filter((entry) => entry !== supplied)
+			} : {
+				...mfa,
+				lastUsedStep: step
 			});
 			const session = await issue(userId, { client: clientOf(carrier) });
 			throttleSucceeded({
@@ -631,7 +654,8 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				const mfa = await adapters.loadMfa?.(actor.id);
 				if (!mfa) return refuse(400, "Start the enrolment first");
 				if (mfa.confirmedAt) return refuse(409, "A second factor is already set up");
-				if (!verifyTotp(mfa.secret, code)) {
+				const step = totpStep(mfa.secret, code);
+				if (step === void 0) {
 					record({
 						type: "mfa.failed",
 						userId: actor.id
@@ -642,7 +666,8 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 				await adapters.saveMfa?.(actor.id, {
 					...mfa,
 					confirmedAt: Math.floor(Date.now() / 1e3),
-					recoveryCodes: plain.map(digestRecoveryCode)
+					recoveryCodes: plain.map(digestRecoveryCode),
+					lastUsedStep: step
 				});
 				record({
 					type: "mfa.enabled",
@@ -1070,6 +1095,15 @@ var createAuthApi = ({ tokens, identity, adapters, config = {} }) => {
 			if (account?.passwordHash) {
 				if (!password || !await verifyPassword$1(password, account.passwordHash)) return refuse(401, "Invalid credentials");
 			}
+			const blockers = await adapters.deletionBlockers?.(actor.id) ?? [];
+			if (blockers.length > 0) return {
+				ok: false,
+				status: 409,
+				body: {
+					error: "This account still owns things that would be lost with it",
+					blockers
+				}
+			};
 			await adapters.deleteAccount(actor.id);
 			record({
 				type: "account.deleted",

package/dist/core/auth/createAuth.d.ts

@@ -177,6 +177,9 @@ export declare const createAuth: (config: AuthConfig) => {
             hostname: string;
         }, res: CookieSink) => void;
         readFlow: (req: import('./session').CookieCarrier) => string | undefined;
+        returnTarget: (req: {
+            hostname: string;
+        }, target: unknown) => string;
         resolveSessionToken: (req: import('./session').CookieCarrier) => string | undefined;
         resolveRefreshToken: (req: import('./session').CookieCarrier, body?: unknown) => string | undefined;
     };
@@ -202,6 +205,7 @@ export declare const createAuth: (config: AuthConfig) => {
         }, res: CookieSink) => void;
         read: (carrier: import('./csrf').CsrfCarrier) => string | undefined;
         required: (carrier: import('./csrf').CsrfCarrier, subject?: import('./csrf').CsrfSubject) => boolean;
+        crossSite: (carrier: import('./csrf').CsrfCarrier, alsoAllowed?: readonly string[]) => boolean;
         verify: (carrier: import('./csrf').CsrfCarrier, sessionToken?: string) => import('./csrf').CsrfResult;
     } | undefined;
     /** The `/auth` flows as descriptors, ready for whatever serves HTTP here. */

package/dist/core/auth/createAuth.js

@@ -1,11 +1,11 @@
 import { createSessionCookies, sessionCookieParams } from "./session.js";
+import { createCsrf } from "./csrf.js";
+import { applySessionOutcome, authPolicyRules, authRoutes } from "./routes.js";
+import { createCarriers, presentedOrigin } from "./credentials.js";
 import { createAuthorizer } from "./authorize.js";
 import { createTokens } from "./tokens.js";
 import { createAuthApi } from "./api.js";
-import { createCarriers, presentedOrigin } from "./credentials.js";
-import { createCsrf } from "./csrf.js";
 import { createIdentity } from "./identity.js";
-import { applySessionOutcome, authPolicyRules, authRoutes } from "./routes.js";
 //#region src/core/auth/createAuth.ts
 /**
 * The whole auth cycle, wired.

package/dist/core/auth/credentials.d.ts

@@ -9,7 +9,10 @@ export interface CredentialCarrier {
     query?: Record<string, unknown>;
     /** Populated by cookie-parser on Express; absent elsewhere, where the header is parsed. */
     cookies?: Record<string, string>;
+    /** The client's address as the host resolved it (Express's `req.ip`, honouring its `trust proxy`). */
+    ip?: string;
 }
+export declare const readCookies: (carrier: CredentialCarrier) => Record<string, string>;
 /**
  * Where a credential of each kind is allowed to ride.
  *

package/dist/core/auth/credentials.js

@@ -51,4 +51,4 @@ var createCarriers = (sessionCookieName) => ({
 */
 var presentedOrigin = (carrier) => headerValue(carrier.headers.origin);
 //#endregion
-export { createCarriers, presentedOrigin };
+export { createCarriers, presentedOrigin, readCookies };

package/dist/core/auth/csrf.d.ts

@@ -26,7 +26,7 @@ export interface CsrfConfig {
  *   space declared. Applying the check below on top would refuse every legitimate embed.
  */
 export type CsrfSubject = 'write' | 'signIn' | 'delegated';
-export type CsrfFailure = 'missing' | 'malformed' | 'expired' | 'mismatch';
+export type CsrfFailure = 'missing' | 'malformed' | 'expired' | 'mismatch' | 'foreign';
 export declare const csrfFailureMessage: Record<CsrfFailure, string>;
 export type CsrfResult = {
     ok: true;
@@ -42,6 +42,20 @@ export interface CsrfCarrier {
     cookies?: Record<string, string>;
     body?: unknown;
 }
+/**
+ * The carrier, read off whatever request a host hands over — named field by field, never spread.
+ *
+ * A spread copies OWN properties, and on Node's `IncomingMessage` (which an Express request is) `headers` is a getter on
+ * the prototype: `{ ...req }` arrives with no headers at all, and the first header read throws. Every guard built on a
+ * spread failed that way on every request.
+ */
+export declare const carrierOf: (req: {
+    method?: string;
+    headers: CsrfCarrier["headers"];
+    hostname: string;
+    cookies?: unknown;
+    body?: unknown;
+}, method?: string | undefined) => CsrfCarrier;
 export declare const createCsrf: (config: CsrfConfig) => {
     issue: (sessionToken?: string) => string;
     /** The name the cookie lands under, for a client that reads it by hand. */
@@ -79,6 +93,16 @@ export declare const createCsrf: (config: CsrfConfig) => {
      * protected by the session cookie's presence, a sign-in by where the request came from. See {@link CsrfSubject}.
      */
     required: (carrier: CsrfCarrier, subject?: CsrfSubject) => boolean;
+    /**
+     * Whether a browser sent this from a site this deployment does not recognise — its own origins, and
+     * `alsoAllowed` (the origins a SPACE declared, for a request that carries that space's credential).
+     *
+     * The rule `signIn` flows are guarded by, offered on its own for a router whose writes cannot all carry a token:
+     * a cookie-carried write that a foreign page caused is refused by where it came from — see
+     * `createOriginGuardMiddleware`. A request with neither Fetch Metadata nor `Origin` is not a browser's, and is
+     * never foreign: there is no victim's session in a script.
+     */
+    crossSite: (carrier: CsrfCarrier, alsoAllowed?: readonly string[]) => boolean;
     /**
      * The whole check. The echoed token must verify against the session the request carries, and — when the
      * cookie is also present — match it. The second half costs nothing and blocks a token that leaked somewhere

package/dist/core/auth/csrf.js

@@ -40,8 +40,23 @@ var csrfFailureMessage = {
 	missing: "A CSRF token is required",
 	malformed: "CSRF token malformed",
 	expired: "CSRF token expired",
-	mismatch: "CSRF token does not match this session"
+	mismatch: "CSRF token does not match this session",
+	foreign: "A request from another site may not act with this session"
 };
+/**
+* The carrier, read off whatever request a host hands over — named field by field, never spread.
+*
+* A spread copies OWN properties, and on Node's `IncomingMessage` (which an Express request is) `headers` is a getter on
+* the prototype: `{ ...req }` arrives with no headers at all, and the first header read throws. Every guard built on a
+* spread failed that way on every request.
+*/
+var carrierOf = (req, method = req.method) => ({
+	method,
+	headers: req.headers,
+	hostname: req.hostname,
+	...req.cookies && typeof req.cookies === "object" ? { cookies: req.cookies } : {},
+	body: req.body
+});
 var equal = (a, b) => {
 	const left = Buffer.from(a);
 	const right = Buffer.from(b);
@@ -94,10 +109,10 @@ var createCsrf = (config) => {
 	* anything: there is no victim's session sitting in it. That is what keeps every API client, mobile app and
 	* script signing in with nothing extra to send.
 	*/
-	const foreign = (carrier) => {
+	const foreign = (carrier, alsoAllowed = []) => {
 		const site = header(carrier, "sec-fetch-site");
 		const origin = header(carrier, "origin");
-		const allowed = origin !== void 0 && permitted(origin);
+		const allowed = origin !== void 0 && (permitted(origin) || alsoAllowed.includes(origin));
 		if (site !== void 0) return site === "cross-site" && !allowed;
 		if (!origin) return false;
 		return originHost(origin) !== carrier.hostname && !allowed;
@@ -212,6 +227,16 @@ var createCsrf = (config) => {
 			return readCookieHeader(carrier, sessionCookieParams(carrier.hostname, cookie).name) !== void 0;
 		},
 		/**
+		* Whether a browser sent this from a site this deployment does not recognise — its own origins, and
+		* `alsoAllowed` (the origins a SPACE declared, for a request that carries that space's credential).
+		*
+		* The rule `signIn` flows are guarded by, offered on its own for a router whose writes cannot all carry a token:
+		* a cookie-carried write that a foreign page caused is refused by where it came from — see
+		* `createOriginGuardMiddleware`. A request with neither Fetch Metadata nor `Origin` is not a browser's, and is
+		* never foreign: there is no victim's session in a script.
+		*/
+		crossSite: (carrier, alsoAllowed) => foreign(carrier, alsoAllowed),
+		/**
 		* The whole check. The echoed token must verify against the session the request carries, and — when the
 		* cookie is also present — match it. The second half costs nothing and blocks a token that leaked somewhere
 		* the cookie did not.
@@ -231,4 +256,4 @@ var createCsrf = (config) => {
 	};
 };
 //#endregion
-export { createCsrf, csrfFailureMessage };
+export { carrierOf, createCsrf, csrfFailureMessage };

package/dist/core/auth/renewal.d.ts

@@ -0,0 +1,26 @@
+import { AuthApi } from './api';
+import { CredentialCarrier } from './credentials';
+import { Csrf } from './csrf';
+import { CookieSink, SessionCookies } from './session';
+/**
+ * A navigation of the whole tab — not a frame, not an image, not a script's fetch. The one kind of request another
+ * site cannot make on a visitor's behalf without the visitor watching it happen, which is what lets a renewal (it
+ * rotates the session) answer a `GET`.
+ */
+export declare const isDocumentNavigation: (headers: Record<string, string | string[] | undefined>) => boolean;
+export interface RenewalOptions {
+    api: AuthApi;
+    cookies: SessionCookies;
+    /** Re-issued for the renewed session, as every flow that grants one does. */
+    csrf?: Csrf;
+}
+/**
+ * `GET <basePath>/refresh?redirect=<page>`: renews the session this browser's refresh cookie holds, and answers where
+ * to send the browser next — always back to the page, whether or not the renewal worked.
+ *
+ * It is where a page server sends a browser whose access cookie has died while its refresh cookie lives on, because
+ * this is the one path the refresh cookie is sent to. What it writes is what makes the page render right on the way
+ * back: the new session, or — for a refresh token that can never work again — no session and no hint, so the page
+ * renders a guest and does not send the browser here a second time.
+ */
+export declare const renewForNavigation: (req: CredentialCarrier, res: CookieSink, { api, cookies, csrf }: RenewalOptions) => Promise<string>;

package/dist/core/auth/renewal.js

@@ -0,0 +1,24 @@
+import { applySessionOutcome } from "./routes.js";
+//#region src/core/auth/renewal.ts
+/**
+* A navigation of the whole tab — not a frame, not an image, not a script's fetch. The one kind of request another
+* site cannot make on a visitor's behalf without the visitor watching it happen, which is what lets a renewal (it
+* rotates the session) answer a `GET`.
+*/
+var isDocumentNavigation = (headers) => headers["sec-fetch-mode"] === "navigate" && headers["sec-fetch-dest"] === "document";
+/**
+* `GET <basePath>/refresh?redirect=<page>`: renews the session this browser's refresh cookie holds, and answers where
+* to send the browser next — always back to the page, whether or not the renewal worked.
+*
+* It is where a page server sends a browser whose access cookie has died while its refresh cookie lives on, because
+* this is the one path the refresh cookie is sent to. What it writes is what makes the page render right on the way
+* back: the new session, or — for a refresh token that can never work again — no session and no hint, so the page
+* renders a guest and does not send the browser here a second time.
+*/
+var renewForNavigation = async (req, res, { api, cookies, csrf }) => {
+	const outcome = await api.refresh(cookies.resolveRefreshToken(req), req);
+	applySessionOutcome(req, res, outcome, cookies, csrf);
+	return cookies.returnTarget(req, req.query?.redirect);
+};
+//#endregion
+export { isDocumentNavigation, renewForNavigation };

package/dist/core/auth/routes.js

@@ -1,9 +1,14 @@
-import { csrfFailureMessage } from "./csrf.js";
+import { carrierOf, csrfFailureMessage } from "./csrf.js";
 //#region src/core/auth/routes.ts
 var body = (req) => req.body ?? {};
-/** A body field as a string, whatever arrived. Handlers validate what they need; this only stops `[object Object]`. */
+/**
+* A body field as text. A NUMBER counts — JSON carries an all-digit code or password as one, and a client that sent
+* `123456` has sent a code: reading it as absent answered a right second-factor code with "Invalid code". Anything else
+* (an object, a boolean) is not a value anybody typed, and is absent.
+*/
 var field = (req, name) => {
 	const value = body(req)[name];
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
 	return typeof value === "string" ? value : "";
 };
 /** A body field as a whole number. `NaN` for anything else, which every handler refuses as a missing id. */
@@ -286,10 +291,7 @@ var authRoutes = ({ api, cookies, csrf }) => FLOWS.map(({ run, csrf: policy, ...
 		* unbound token satisfies a signed-out caller, which is how signing in is protected when a deployment asks
 		* for that.
 		*/
-		const carrier = {
-			...req,
-			method: route.method
-		};
+		const carrier = carrierOf(req, route.method);
 		if (csrf && csrfNeeded(csrf, policy, carrier)) {
 			const result = csrf.verify(carrier, cookies.resolveSessionToken(req));
 			if (!result.ok) return {

package/dist/core/auth/session.d.ts

@@ -44,6 +44,14 @@ export declare const sessionCookieParams: (hostname: string, config?: SSRAuthCoo
  * same question with `credentials: 'include'`.
  */
 export declare const sessionHintValue: (expiresAt: number, refreshExpiresAt?: number) => string;
+export type SessionHint = {
+    /** Unix seconds the access credential dies at. */
+    expiresAt: number;
+    /** Unix seconds renewal stops being possible at, when the session has a refresh half. */
+    refreshExpiresAt?: number;
+};
+/** {@link sessionHintValue} read back — the same reading `@plitzi/sdk-auth` gives it in the browser. */
+export declare const parseSessionHint: (value: string | undefined) => SessionHint | undefined;
 /**
  * Adds to `Set-Cookie` rather than replacing it. A handler may already have written one — clearing an OAuth flow
  * before granting the session it produced is exactly that — and replacing the header would silently drop it.
@@ -93,6 +101,40 @@ export declare const readRefreshToken: (req: SSRRequest | {
     };
     hostname: string;
 }, config?: SSRAuthCookie) => string | undefined;
+/** What the readable companion cookie says about this browser's session, without presenting any credential. */
+export declare const readSessionHint: (req: SSRRequest | {
+    headers: {
+        cookie?: string;
+    };
+    hostname: string;
+}, config?: SSRAuthCookie) => SessionHint | undefined;
+/**
+ * How long a page server holds off sending a browser to renew again. Long enough to cover the round trip there and
+ * back, short enough that a renewal which failed for a passing reason is retried on a later visit.
+ */
+export declare const RENEWAL_GUARD_SECONDS = 30;
+/**
+ * Marks a browser as having just been sent to renew its session, so the page it comes back to is rendered rather
+ * than bounced again. Every renewal that can fail without ending the session — the refresh cookie not reaching the
+ * endpoint, the store being down — would otherwise send the visitor round in a loop.
+ */
+export declare const writeRenewalGuard: (req: {
+    hostname: string;
+}, res: CookieSink, config?: SSRAuthCookie) => void;
+/**
+ * Where a renewal sends the browser back to: a path on this host, or a page on any host this session's cookies are
+ * scoped to — the only hosts that could have sent a browser here to renew, since the hint that triggers it rides on
+ * the same cookie domain. Anything else is an open redirect, and goes to `/` instead.
+ */
+export declare const sessionReturnTarget: (req: {
+    hostname: string;
+}, target: unknown, config?: SSRAuthCookie) => string;
+export declare const readRenewalGuard: (req: SSRRequest | {
+    headers: {
+        cookie?: string;
+    };
+    hostname: string;
+}, config?: SSRAuthCookie) => boolean;
 /** Anything a credential can be read off: this server's own request, an Express one, a bare `node:http` one. */
 export type CookieCarrier = SSRRequest | {
     headers: {
@@ -124,6 +166,9 @@ export declare const createSessionCookies: (config?: SSRAuthCookie) => {
         hostname: string;
     }, res: CookieSink) => void;
     readFlow: (req: CookieCarrier) => string | undefined;
+    returnTarget: (req: {
+        hostname: string;
+    }, target: unknown) => string;
     /**
      * The session credential from `Authorization: Bearer` or the cookie, so one endpoint serves a bearer client and a
      * browser. The header wins: a caller that went to the trouble of presenting one means it.

package/dist/core/auth/session.js

@@ -51,6 +51,18 @@ var sessionCookieParams = (hostname, config = {}) => {
 * same question with `credentials: 'include'`.
 */
 var sessionHintValue = (expiresAt, refreshExpiresAt) => `${Math.floor(expiresAt)}.${refreshExpiresAt === void 0 ? "" : Math.floor(refreshExpiresAt)}`;
+/** {@link sessionHintValue} read back — the same reading `@plitzi/sdk-auth` gives it in the browser. */
+var parseSessionHint = (value) => {
+	if (!value) return;
+	const [expiresAt, refreshExpiresAt] = value.split(".");
+	const expiry = Number(expiresAt);
+	if (!Number.isFinite(expiry) || expiry <= 0) return;
+	const refreshExpiry = Number(refreshExpiresAt);
+	return {
+		expiresAt: expiry,
+		refreshExpiresAt: Number.isFinite(refreshExpiry) && refreshExpiry > 0 ? refreshExpiry : void 0
+	};
+};
 var serializeCookie = (name, value, maxAgeSeconds, params, { httpOnly = true, path = "/" } = {}) => {
 	const parts = [
 		`${name}=${encodeURIComponent(value)}`,
@@ -127,6 +139,39 @@ var readCookie = (req, name) => {
 var readSessionToken = (req, config) => readCookie(req, sessionCookieParams(req.hostname, config).name);
 /** The renewal credential, which rides in its own cookie confined to the refresh path. */
 var readRefreshToken = (req, config) => readCookie(req, `${sessionCookieParams(req.hostname, config).name}_refresh`);
+/** What the readable companion cookie says about this browser's session, without presenting any credential. */
+var readSessionHint = (req, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	return parseSessionHint(readCookie(req, `${params.name}${params.hintSuffix}`));
+};
+/**
+* Marks a browser as having just been sent to renew its session, so the page it comes back to is rendered rather
+* than bounced again. Every renewal that can fail without ending the session — the refresh cookie not reaching the
+* endpoint, the store being down — would otherwise send the visitor round in a loop.
+*/
+var writeRenewalGuard = (req, res, config) => {
+	const params = sessionCookieParams(req.hostname, config);
+	appendCookies(res, [serializeCookie(`${params.name}_renewing`, "1", 30, params)]);
+};
+/**
+* Where a renewal sends the browser back to: a path on this host, or a page on any host this session's cookies are
+* scoped to — the only hosts that could have sent a browser here to renew, since the hint that triggers it rides on
+* the same cookie domain. Anything else is an open redirect, and goes to `/` instead.
+*/
+var sessionReturnTarget = (req, target, config) => {
+	if (typeof target !== "string" || target === "") return "/";
+	if (target.startsWith("/") && !target.startsWith("//") && !target.startsWith("/\\")) return target;
+	let url;
+	try {
+		url = new URL(target);
+	} catch {
+		return "/";
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") return "/";
+	const { domain } = sessionCookieParams(req.hostname, config);
+	return url.hostname === req.hostname || domain !== void 0 && (url.hostname === domain.slice(1) || url.hostname.endsWith(domain)) ? url.toString() : "/";
+};
+var readRenewalGuard = (req, config) => readCookie(req, `${sessionCookieParams(req.hostname, config).name}_renewing`) !== void 0;
 /**
 * The cookie side of a session with this deployment's naming already bound in.
 *
@@ -142,6 +187,7 @@ var createSessionCookies = (config) => ({
 	writeFlow: (req, res, value, ttlSeconds) => writeFlowCookie(req, res, value, ttlSeconds, config),
 	clearFlow: (req, res) => clearFlowCookie(req, res, config),
 	readFlow: (req) => readFlowCookie(req, config),
+	returnTarget: (req, target) => sessionReturnTarget(req, target, config),
 	/**
 	* The session credential from `Authorization: Bearer` or the cookie, so one endpoint serves a bearer client and a
 	* browser. The header wins: a caller that went to the trouble of presenting one means it.
@@ -162,4 +208,4 @@ var createSessionCookies = (config) => ({
 	}
 });
 //#endregion
-export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, registrableDomain, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies };
+export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, parseSessionHint, readFlowCookie, readRefreshToken, readRenewalGuard, readSessionHint, readSessionToken, registrableDomain, sessionCookieParams, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeRenewalGuard, writeSessionCookies };

package/dist/core/auth/sessionActivity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * When a session was last used, to the resolution a device list needs.
+ *
+ * "Active 3 minutes ago" against "active last March" is what tells somebody which of their devices is the one they do
+ * not recognise — and the time a session was CREATED says neither: a laptop signed in a month ago and used this morning
+ * reads as a month-old session. Recording every request would be a write per request on the hottest read in the
+ * system, so a store records it at most once per this many seconds, on the lookup it already makes.
+ */
+export declare const SESSION_ACTIVITY_RESOLUTION_SECONDS = 300;
+/** Whether a session last seen at `lastActiveAt` (unix seconds, absent when never) is due a new record at `now`. */
+export declare const activityDue: (lastActiveAt: number | null | undefined, now: number) => boolean;

package/dist/core/auth/sessionActivity.js

@@ -0,0 +1,14 @@
+//#region src/core/auth/sessionActivity.ts
+/**
+* When a session was last used, to the resolution a device list needs.
+*
+* "Active 3 minutes ago" against "active last March" is what tells somebody which of their devices is the one they do
+* not recognise — and the time a session was CREATED says neither: a laptop signed in a month ago and used this morning
+* reads as a month-old session. Recording every request would be a write per request on the hottest read in the
+* system, so a store records it at most once per this many seconds, on the lookup it already makes.
+*/
+var SESSION_ACTIVITY_RESOLUTION_SECONDS = 300;
+/** Whether a session last seen at `lastActiveAt` (unix seconds, absent when never) is due a new record at `now`. */
+var activityDue = (lastActiveAt, now) => lastActiveAt === null || lastActiveAt === void 0 || now - lastActiveAt >= 300;
+//#endregion
+export { SESSION_ACTIVITY_RESOLUTION_SECONDS, activityDue };

package/dist/core/auth/throttle.d.ts

@@ -1,5 +1,20 @@
 import { ThrottleAttempt } from './api';
+import { StoreMethods } from '../server/fleet/channel';
 export declare const createMemoryRateLimit: () => ((attempt: ThrottleAttempt) => Promise<{
     allowed: boolean;
     retryAfter?: number;
 }>);
+type RateLimitStore = {
+    check: ReturnType<typeof createMemoryRateLimit>;
+};
+/** Every method of the store, for the copy a fleet's workers share (see `fleet/stores.ts`). */
+export declare const RATE_LIMIT_METHODS: StoreMethods<RateLimitStore>;
+/**
+ * In a worker of a fleet, the primary's {@link createMemoryRateLimit}, so an attacker spreading attempts over
+ * connections meets one counter rather than one per worker. Nothing anywhere else.
+ */
+export declare const fleetRateLimit: () => ((attempt: ThrottleAttempt) => Promise<{
+    allowed: boolean;
+    retryAfter?: number;
+}>) | undefined;
+export {};

package/dist/core/auth/throttle.js

@@ -1,4 +1,17 @@
+import { fleetStore } from "../server/fleet/link.js";
 //#region src/core/auth/throttle.ts
+/**
+* The rate limit a deployment gets without asking for one.
+*
+* This used to be a required-to-be-safe option: no `rateLimit`, no limit, and sign-in was an unmetered password
+* oracle. Nobody sets an option they have not read about, so the effect of "there is no sensible default" was that
+* the common deployment shipped without any — which is not a neutral outcome, it is the bad one.
+*
+* It counts in memory, and that is an honest limitation rather than a hidden one: several replicas each keep
+* their own window, so four replicas tolerate four times the attempts. Four times a small number is still a small
+* number, and it beats infinity. A deployment that wants one counter for all of them supplies `rateLimit` and puts
+* it in Redis. The workers of one server are one replica: they count in the primary (`fleetRateLimit`).
+*/
 /** Attempts allowed per window, per key, per action. */
 var LIMITS = {
 	/** Credential stuffing is the thing being priced out. Ten wrong passwords in five minutes is already a lot. */
@@ -77,5 +90,20 @@ var createMemoryRateLimit = () => {
 		return Promise.resolve({ allowed: true });
 	};
 };
+/** Every method of the store, for the copy a fleet's workers share (see `fleet/stores.ts`). */
+var RATE_LIMIT_METHODS = { check: true };
+/**
+* In a worker of a fleet, the primary's {@link createMemoryRateLimit}, so an attacker spreading attempts over
+* connections meets one counter rather than one per worker. Nothing anywhere else.
+*/
+var fleetRateLimit = () => {
+	const shared = fleetStore("auth.rateLimit", RATE_LIMIT_METHODS);
+	if (!shared) return;
+	return (attempt) => shared.check({
+		action: attempt.action,
+		key: attempt.key,
+		...attempt.succeeded ? { succeeded: true } : {}
+	});
+};
 //#endregion
-export { createMemoryRateLimit };
+export { RATE_LIMIT_METHODS, createMemoryRateLimit, fleetRateLimit };

package/dist/core/auth/totp.d.ts

@@ -3,15 +3,23 @@ export declare const generateTotpSecret: () => string;
 /** The code an app would be showing right now. Exported so a test does not have to reimplement the algorithm. */
 export declare const totpCode: (secret: string, at?: number) => string;
 /**
- * Is this the code?
+ * Which time step this code belongs to, or `undefined` when it belongs to none near now.
  *
  * `window` steps either side are accepted, one by default — thirty seconds of tolerance for a clock that drifts
  * and for a person who starts typing at second twenty-nine. Wider is friendlier and weaker; this is the usual
  * trade and the same one Google Authenticator's own guidance makes.
  *
+ * The step is the answer, not a yes: a code stays valid for its whole window, so a verifier that remembers nothing
+ * accepts the same code twice. RFC 6238 §5.2 forbids that — see `MfaRecord.lastUsedStep`.
+ *
  * Compared in constant time: a comparison that returns on the first differing digit leaks how much of a guess was
  * right, which turns a million-guess space into ten guesses per position.
  */
+export declare const totpStep: (secret: string, code: string, options?: {
+    window?: number;
+    at?: number;
+}) => number | undefined;
+/** Is this the code? `totpStep`, for a caller that does not need to know which step it was. */
 export declare const verifyTotp: (secret: string, code: string, options?: {
     window?: number;
     at?: number;