@plitzi/sdk-server 0.37.2 → 0.37.4

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;

package/dist/core/auth/totp.js

@@ -55,28 +55,33 @@ var codeAt = (secret, counter) => {
 /** The code an app would be showing right now. Exported so a test does not have to reimplement the algorithm. */
 var totpCode = (secret, at = Date.now()) => codeAt(secret, Math.floor(at / 1e3 / STEP_SECONDS));
 /**
-* 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.
 */
-var verifyTotp = (secret, code, options = {}) => {
+var totpStep = (secret, code, options = {}) => {
 	const { window = 1, at = Date.now() } = options;
 	const candidate = code.trim();
-	if (!/^\d{6}$/.test(candidate)) return false;
+	if (!/^\d{6}$/.test(candidate)) return;
 	const counter = Math.floor(at / 1e3 / STEP_SECONDS);
 	const supplied = Buffer.from(candidate);
-	let matched = false;
+	let matched;
 	for (let drift = -window; drift <= window; drift++) {
 		const expected = Buffer.from(codeAt(secret, counter + drift));
-		matched = timingSafeEqual(expected, supplied) || matched;
+		if (timingSafeEqual(expected, supplied)) matched = counter + drift;
 	}
 	return matched;
 };
+/** Is this the code? `totpStep`, for a caller that does not need to know which step it was. */
+var verifyTotp = (secret, code, options = {}) => totpStep(secret, code, options) !== void 0;
 /**
 * The URI an authenticator app scans. `issuer` appears twice by convention — in the label and as a parameter —
 * because different apps read different ones, and an entry that says only an email address is unidentifiable in a
@@ -115,4 +120,4 @@ var generateRecoveryCodes = (count = 10) => Array.from({ length: count }, () =>
 /** Normalised before hashing so that case and the hyphen a person types or omits do not decide whether it works. */
 var normalizeRecoveryCode = (code) => code.trim().toUpperCase().replace(/[^A-Z0-9]/g, "");
 //#endregion
-export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp };
+export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpStep, totpUri, verifyTotp };

package/dist/core/createServer.actions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/createServer.d.ts

@@ -19,5 +19,18 @@ export type ServerConfig = Omit<SSRServerConfig, 'adapters'> & {
      * `adapters` or `authCookie` still wins, so a deployment can override one piece without giving up the rest.
      */
     auth?: Auth;
+    /**
+     * Where a page request whose access cookie has died, while its refresh cookie lives on, is sent to renew before
+     * the page is rendered — so the server renders the visitor the browser is about to become, rather than a guest
+     * the browser then replaces. The endpoint is `GET <basePath>/refresh`, served by `auth` here or by
+     * `mountAuthRoutes` wherever `/auth` lives.
+     *
+     * On by default with `auth`, at its own `/refresh`. Without it, name the endpoint — an absolute URL when another
+     * host serves `/auth` (a host sharing the session's cookie domain, or the hint that triggers this never arrives).
+     * `false` turns it off.
+     */
+    sessionRenewal?: {
+        url: string;
+    } | false;
 };
-export declare const createServer: ({ auth, ...config }: ServerConfig, extensions?: PipelineExtensions) => SSRServer;
+export declare const createServer: ({ auth, sessionRenewal, ...config }: ServerConfig, extensions?: PipelineExtensions) => SSRServer;

package/dist/core/createServer.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/createServer.js

@@ -1,6 +1,7 @@
 import { actionsModuleFor } from "../modules/actions/moduleFor.js";
 import { connectorRscData } from "../modules/rsc/connectorRscData.js";
 import { createAuthApiStage } from "./http/stages/authApi.js";
+import { createRenewalEndpointStage, createSessionRenewalStage } from "./http/stages/sessionRenewal.js";
 import { resolveServices } from "./services/resolve.js";
 import { createPageServer } from "./server/pageServer.js";
 //#region src/core/createServer.ts
@@ -24,23 +25,27 @@ import { createPageServer } from "./server/pageServer.js";
 */
 var withConnectorRsc = (config) => {
 	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups) return config;
-	const module = actionsModuleFor(config);
+	const resolved = {
+		...config,
+		adapters: { ...config.adapters }
+	};
+	const module = actionsModuleFor(resolved);
 	const actions = module && config.action?.lookups ? {
 		lookups: config.action.lookups,
 		module
 	} : void 0;
-	return {
-		...config,
-		adapters: {
-			...config.adapters,
-			getRscData: connectorRscData(config.connectors, actions, config.rsc?.elementTimeoutMs)
-		}
-	};
+	resolved.adapters.getRscData = connectorRscData(config.connectors, actions, config.rsc?.elementTimeoutMs);
+	return resolved;
 };
-var createServer = ({ auth, ...config }, extensions) => {
+/** The renewal stage in front of whatever else gates itself, when there is anywhere to renew. */
+var withRenewal = (extensions, url) => ({
+	...extensions,
+	preAuth: [...extensions?.preAuth ?? [], ...url ? [createSessionRenewalStage(url)] : []]
+});
+var createServer = ({ auth, sessionRenewal, ...config }, extensions) => {
 	if (!auth) {
 		const resolvedConfig = withConnectorRsc(config);
-		return createPageServer(resolvedConfig, resolveServices(resolvedConfig), extensions);
+		return createPageServer(resolvedConfig, resolveServices(resolvedConfig), withRenewal(extensions, sessionRenewal ? sessionRenewal.url : void 0));
 	}
 	const entries = Object.entries(config.adapters);
 	const supplied = Object.fromEntries(entries.filter(([, value]) => value !== void 0));
@@ -57,9 +62,14 @@ var createServer = ({ auth, ...config }, extensions) => {
 	});
 	const withAuthRoutes = {
 		...extensions,
-		preAuth: [...extensions?.preAuth ?? [], createAuthApiStage(auth, auth.basePath)]
+		preAuth: [
+			...extensions?.preAuth ?? [],
+			createAuthApiStage(auth, auth.basePath),
+			createRenewalEndpointStage(auth)
+		]
 	};
-	return createPageServer(resolved, resolveServices(resolved), withAuthRoutes);
+	const renewalUrl = sessionRenewal === false ? void 0 : sessionRenewal?.url ?? `${auth.basePath}/refresh`;
+	return createPageServer(resolved, resolveServices(resolved), withRenewal(withAuthRoutes, renewalUrl));
 };
 //#endregion
 export { createServer, resolveServices };

package/dist/core/fontStore.js

@@ -1,5 +1,5 @@
-import fs from "node:fs";
 import path from "node:path";
+import fs from "node:fs";
 //#region src/core/fontStore.ts
 /** `<spaceId>/<name>` — the space segment is what keeps one space's files out of another's. */
 var storePathOf = (spaceId, name) => `${spaceId}/${name}`;

package/dist/core/handlers/authRouteHandlers.d.ts

@@ -12,7 +12,7 @@ export interface AuthRouteHandlersOptions {
      * deployment that means to go without says so with `csrf: false` there rather than by forgetting here.
      */
     csrf?: Csrf;
-    /** Reports a flow that threw. Without it the failure goes to `console.error`; the caller still gets a 500. */
+    /** Reports a flow that threw. Without it the failure goes to the server log at `error`; the caller still gets a 500. */
     onError?: (error: unknown, context: {
         method: string;
         path: string;