@plitzi/sdk-server 0.37.2 → 0.37.4

package/README.md

@@ -106,9 +106,12 @@ server.listen(3001, '127.0.0.1');
 
 ```bash
 yarn add @plitzi/sdk-server react react-dom
-yarn tsx server.ts     # http://127.0.0.1:3001/
+node server.ts     # http://127.0.0.1:3001/ — Node 22.18+ runs TypeScript itself
 ```
 
+No transpiler in front of it: Node strips the types. A loader such as `tsx` costs a page server more memory than the
+server itself — on a 128 MB host, the difference between starting and being killed on boot.
+
 Both pages render server-side, with the CSS the space declared. `authorSpace` refuses to hand back a space that
 would not render — a CSS property the style editor could not read back, a class nothing declares, a binding
 pointing at an element that is not there — so a mistake is an error at the line that made it rather than a blank
@@ -158,26 +161,32 @@ serve it — worth running over anything that arrives as a file.
 |---|---|---|---|
 | `httpVersion` | `1 \| 2 \| 3` | `2` with `tls`, else `1` | HTTP protocol version. Falls back to the nearest available lower version. |
 | `tls` | `{ key, cert, minVersion? }` | — | TLS key and certificate. Required for versions 2 and 3; optional for version 1. |
-| `devMode` | `boolean` | `NODE_ENV !== 'production'` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). |
+| `devMode` | `boolean` | `false` | Enables development mode: appends `?dev` to esm.sh CDN URLs for React, and activates per-request timing metrics (see [Dev metrics](#dev-metrics)). Off, the process must run with `NODE_ENV=production` or React renders with its development build; the server says so once, at `error`. |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
 | `cacheTtlMs` | `number` | `300000` | TTL in milliseconds for the SSR render cache. Set to `0` to disable. |
 | `loginPath` | `string \| false` | `'/auth/login'` | Path for the built-in login endpoint. Set to `false` to disable it entirely. |
 | `logoutPath` | `string \| false` | `'/auth/logout'` | Path for the built-in logout endpoint. Set to `false` to disable it entirely. |
+| `signIn` | `SSRSignInConfig` | — | Sign visitors in by redirect through an OAuth 2.1 authorization server: `GET /auth/sign-in?return=/x` registers this host as a client, sends the browser out with PKCE (state in a `__Host-` cookie), and `/auth/sign-in/callback` redeems the code server to server and hands the token to `exchangeCredential`, which makes the session here. Needs the `exchangeCredential` adapter. |
 | `templateFn` | `SSRTemplateFn` | built-in EJS template | Custom render function. Receives all template params and returns an HTML string. |
 | `plugins` | `Record<string, PluginSource>` | — | Named plugin definitions. Compiled or copied on first use and cached for `pluginsTtlMs`. |
 | `pluginsCacheDir` | `string` | `.sdk-plugins` | Directory where compiled plugin files are stored. |
 | `pluginsTtlMs` | `number` | `604800000` | TTL in milliseconds for compiled plugins (default: 1 week). |
 | `autoLoadSchemaPlugins` | `boolean` | `true` | Auto-download and cache plugins declared in the schema's `offlineData.plugins` list. Set to `false` to manage plugin loading manually. |
+| `allowPrivatePluginHosts` | `boolean` | `false` | Read a schema plugin from a private address (`localhost`, this server's own network). A plugin's address is typed by whoever edits a space, so leave it off anywhere but a development machine whose bucket is local. |
 | `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked before `static` prefix routes. |
 | `static` | `Record<string, string>` | — | URL prefix → filesystem path mappings for static file serving. |
 | `ssrOnly` | `boolean` | `false` | Omit client-side JS from the rendered page. Useful for verifying SSR HTML without hydration. |
 | `streaming` | `boolean` | `false` | Stream HTML to the browser incrementally to reduce TTFB. See [Streaming](#streaming). |
 | `middlewares` | `SSRMiddleware[]` | — | Array of custom middleware functions executed before the SSR renderer on every request (see [Custom middlewares](#custom-middlewares)). |
 | `rsc` | `SSRRscConfig` | — | React Server Components endpoint configuration (see [RSC](#react-server-components-rsc)). |
+| `realtime` | `{ pubsub?, path?, transport?, allowedOrigins? } \| false` | in memory, at `/_realtime`, `sse` | Realtime channels the space declares. `transport` is what pages connect with: `sse` (a stream, publishes over `POST`) or `websocket` (one socket both ways, HTTP/1.1 only; pages fall back to the stream where a socket cannot open). `allowedOrigins` lists the other origins whose pages may open a socket. `pubsub` is how messages reach other processes — `createMemoryPubSub()` (the default, across workers) or `createRedisPubSub({ publisher, subscriber })` for several replicas. `false` serves no endpoint. See [`docs/en/realtime.md`](../../docs/en/realtime.md). |
 | `compression` | `SSRCompressionConfig \| false` | Brotli, then gzip | Response compression (see [Compression](#compression)). `false` never compresses. |
 | `health` | `SSRHealthConfig` | identity payload | The `/health` endpoint. `check` adds live state per probe and turns it into a readiness probe (see [Health](#health)). |
 | `adapters` | `SSRAdapters` | — | Required. Adapter callbacks for data fetching. |
+| `logLevel` | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `info` with `devMode`, else `error` | How much the server says, for the whole process (see [Logging](#logging)). |
+| `logger` | `ServerLogger` | the console | Where it says it: one structured `ServerLogEvent` stream. `consoleLogger` prints each as one line. |
 | `onListenError` | `(error, { port, host, label }) => void` | exits non-zero | What to do when the server cannot take its port. By default it prints what went wrong and what to do about it, then exits — a process whose server never bound is not running. Supply this to keep it alive and decide yourself. |
+| `workers` | `boolean \| number \| 'auto'` | `'auto'` under `NODE_ENV=production`, else `false` | How many processes serve the port: one per core, a number (lowered to the cores there are), or one. `SDK_SERVER_WORKERS` sets it when the config does not. See [Using every core](#using-every-core). |
 
 ### HTTP version behaviour
 
@@ -409,7 +418,8 @@ createServer({ compression: false, adapters });
 |---|---|---|---|
 | `encodings` | `('br' \| 'gzip')[]` | `['br', 'gzip']` | What this server offers, most preferred first; the first one the client accepts wins. `[]` disables compression. |
 | `threshold` | `number` | `1024` | Responses smaller than this many bytes go out uncompressed. |
-| `brotliQuality` | `number` | `4` | Brotli quality, 0–11. Past 4 the CPU cost outgrows the bytes saved on HTML. |
+| `brotliQuality` | `number` | `2` | Brotli quality, 0–11, for a body compressed on every request (a page rendered for that request alone). Measured on a quarter core, 4 cost a tenth of the pages a second to save half a kilobyte each. |
+| `keptBrotliQuality` | `number` | `6` | Brotli quality for a body compressed once and kept: a cached page, a static file such as the SDK bundle. Paid once; the bundle comes out 10% smaller than at 4, for the same memory. 9 needs ~40 MB more to compress the bundle, which a 128 MB server does not have. |
 | `gzipLevel` | `number` | `6` | Gzip level, 0–9. |
 
 A response that sets `Cache-Control: no-transform` is never compressed, whatever the settings say — that header is
@@ -546,7 +556,7 @@ const getSpaceDeployment = async (req): Promise<SSRSpaceDeployment> => {
 };
 ```
 
-Plugins listed in `pluginSources` are registered into the plugin manager on-the-fly using `ensure()`, which only triggers a rebuild if the plugin is new or its `version` has changed. Both `pluginNames` and `pluginSources` entries are resolved in parallel before the HTML is rendered.
+Plugins listed in `pluginSources` — and the external plugins a space's schema lists — are registered into the plugin manager on-the-fly using `ensure()`, under a key that carries the source's identity as well as its name and version (`name@1.0.0+<digest>` of its `js`, `css`, `action` and `props`). A plugin published again under the same version, or another space's plugin with the same name and version, is therefore a source of its own rather than whichever this process met first, and is built only once. Both `pluginNames` and `pluginSources` entries are resolved in parallel before the HTML is rendered.
 
 ### Plugin sources
 
@@ -966,8 +976,8 @@ and every refusal names a machine-readable `reason`, so a client can tell "renew
 | `identity` | Your own hosts and origins — the floor for domain binding and framing |
 | `tokens.lifetimes` | How long each credential lives |
 
-Working examples are in [`examples/02-with-users`](../../examples/02-with-users): `01-sessions` over a store you
-write, `02-mysql` over one you do not.
+Working examples are in [`examples/self-hosting`](../../examples/self-hosting): `03-sessions` over a store you
+write, `04-mysql` over one you do not.
 
 ### Cross-site request forgery
 
@@ -1134,6 +1144,54 @@ A stage receives the `SSRContext` — the request, the config, and the render si
 **is** the decision to mount them: there is no config flag mirroring it, and a server that never passes them
 never loads them.
 
+## Using every core
+
+Node runs JavaScript on one thread, so one process renders on one core however many the machine has. With
+`workers`, the server runs one process per core and the connections are spread between them: more requests a second,
+and less time waiting behind another page's render.
+
+```ts
+createServer({ adapters, workers: 'auto' }); // one per core — the default under NODE_ENV=production
+createServer({ adapters, workers: 4 });      // at most four, and never more than the cores there are
+createServer({ adapters, workers: false });  // one process, exactly as before
+```
+
+`SDK_SERVER_WORKERS=auto|false|<n>` sets it from the environment. The cores are the ones the process may use: a
+container's CPU quota counts, so a pod limited to one CPU runs one process whatever the node has.
+
+**One process is the server as it always was.** Workers off, one asked for, or one core to run on: nothing is forked,
+nothing is wrapped, and every in-memory default is this process's own.
+
+**Several are still one server.** The process you started serves nothing itself; it starts the workers, restarts them
+and keeps what they must share:
+
+- The in-memory defaults — an action's `kv`, the job queue, draft previews, the sign-in rate limit — are kept once, by
+  that process, and every worker reaches the same copy. A counter counts every request once; a draft written through
+  one worker is read through another. A store you supply (Redis, a table) is used as it is.
+- The scheduler and the job consumers run in one worker only: a schedule fires once, and `jobs.workers` is the whole
+  server's concurrency.
+- `server.cache.invalidate()`, `server.plugins.register()` and `server.plugins.invalidate()` reach every worker,
+  whichever process calls them — a publish webhook lands on one of them.
+- Plugins are built once, before the workers start.
+
+Per worker: the rendered-page cache (each renders a page once), the plugin components, and the action caps
+(`action.concurrency`). A plugin registered with a `component` stays in the process that registered it — register
+those where the server is created.
+
+**When a worker dies** — a crash, an uncaught error, the OOM killer — it is replaced, and its replacement takes over the
+jobs it carried (a claimed job goes back to the queue when its lease lapses). Past one death per worker a minute the
+replacements wait, doubling from half a second up to thirty, so a request that crashes every worker it reaches cannot
+turn the server into a fork loop. A replacement that fails to start is retried the same way while the rest keep
+serving. Two exceptions: a worker that dies before any has served stops the server with a non-zero exit (a port in use
+would fail the same way every time), and a server that is killed outright takes its workers with it.
+
+`closeOnSignals(server)` stops them all on SIGTERM, each finishing what it is serving. The workers of one machine are
+one replica; several machines are several replicas, and what must hold across those still needs a shared store — see
+below.
+
+A process that starts servers of its own beside this one (an Express app on another port) should say `workers:
+false`: each worker runs the whole entry file again.
+
 ## Scheduled jobs across replicas
 
 Server actions with a `schedule` trigger, and jobs queued for later, run with no configuration — over an in-process
@@ -1156,6 +1214,12 @@ server.listen(3000);
 closeOnSignals(server, { afterClose: () => mongoClient.close() });
 ```
 
+`close()` does not wait for what never ends on its own: it stops taking connections, tells every realtime socket and
+stream to go (a WebSocket is closed with 1001, "going away", which the pages reconnect from once the server is back),
+ends any other event stream, lets what is being answered finish, and cuts whatever is still open after ten seconds
+(`SHUTDOWN_GRACE_MS`). A page left open on a board, or an agent's app listening, no longer holds a Ctrl+C or a
+SIGTERM until something kills the process.
+
 `@plitzi/sdk-server/mysql` has the same pair over a `mysql2` pool (`createMysqlJobQueue`, `createMysqlKv`). Anything
 else is the `ActionJobQueue` contract written against your store — see
 [server actions § self-hosted](https://github.com/plitzi/plitzi-workspace/blob/main/docs/en/server-actions.md#13-for-a-self-hosted-deployment).
@@ -1291,12 +1355,41 @@ How it works:
 
 **Compression**: streaming responses use chunked transfer encoding and skip Brotli/gzip compression. A `Content-Length` header cannot be set before the body is complete, so compression is intentionally bypassed for streaming responses.
 
+## Logging
+
+One stream and one threshold, the usual hierarchy: `silent` < `error` < `warn` < `info` < `debug`. In production the
+server says only what went wrong — a failed request, a failed run, a server that could not start — and everything
+below it is one `logLevel` away:
+
+| Level | What it adds |
+|---|---|
+| `error` | Requests answered 5xx or that threw, runs that did not complete, anything the server could not do. |
+| `warn` | Refused actions (a bad webhook signature, a missing session), plugin manifests it could not fetch, HTTP/3 falling back. |
+| `info` | Every request line, every run, plugin builds, `listening on`. |
+| `debug` | The per-render phase breakdown of [Dev metrics](#dev-metrics). |
+
+```ts
+createServer({ adapters, logLevel: process.env.LOG_LEVEL === 'info' ? 'info' : 'error', logger: consoleLogger });
+```
+
+A request below the threshold is not even turned into an event, so a quiet server pays nothing per request. Everything goes to the `logger` —
+requests, MCP tool calls, runs, and the server's own messages as `kind: 'message'` events — and `logLevelOf(event)`
+tells a sink how severe each one is. The run and refusal loggers a deployment wires itself (`createRunLogger`,
+`createRejectLogger`) are held to the same threshold, and so is `serverLog`, the server's own voice, which a
+deployment's adapters can speak through too:
+
+```ts
+import { serverLog } from '@plitzi/sdk-server';
+
+serverLog.warn('Adapters', 'space 12 has no deployment, serving main');
+```
+
 ## Dev metrics
 
 When `devMode: true`, per-phase timing is instrumented on every render and reported in two ways:
 
 - A `Server-Timing` header is set on the response, visible in the browser's DevTools under **Network → Timing**.
-- A one-line summary is logged to stdout:
+- A one-line summary is logged at `debug` (see [Logging](#logging)):
 
 ```
 [SSR] GET / — schema=1ms rsc=0ms extPlugins=0ms plugins=0ms template=2ms react=16ms | total=19ms

package/dist/actions.d.ts

@@ -15,7 +15,7 @@
  * from somewhere else — a queue consumer, or the API role answering a builder's test run. Same runner, same
  * checks: a trigger that skipped them would be a weaker path to the same work.
  */
-export { createActionsModule } from './modules/actions';
+export { createActionsModule, spaceKvPatterns } from './modules/actions';
 /**
  * Scheduled runs: a durable queue, a leaderless producer and the workers that drain it.
  *
@@ -39,7 +39,7 @@ export { cronFiresBetween, cronMatches, cronNextFire, parseCron } from '@plitzi/
  */
 export { checkAction } from './modules/actions/runtime/check';
 export type { ActionCheckDeps } from './modules/actions/runtime/check';
-export { ActionRunError } from './modules/actions/runtime/errors';
+export { ActionRefusal, ActionRunError } from './modules/actions/runtime/errors';
 export { DEFAULT_LIMITS } from './modules/actions/runtime/limits';
 export { createTaskRegistry, taskName } from './modules/actions/tasks/registry';
 export { describeCatalog, describeTask } from './modules/actions/taskCatalog';
@@ -54,6 +54,10 @@ export { describeCatalog, describeTask } from './modules/actions/taskCatalog';
  */
 export { createMemoryKv } from './modules/actions/runtime/memoryKv';
 export { createKvStore } from './modules/actions/runtime/kvStore';
+export { createRedisKv } from './modules/actions/runtime/redisKv';
+export type { RedisKvClient, RedisKvOptions } from './modules/actions/runtime/redisKv';
+export { MAX_LIST_BYTES, MAX_LIST_ENTRIES } from './modules/actions/runtime/kvList';
+export type { KvListEntry, KvListPut, KvListPutOptions, KvListRange } from './modules/actions/runtime/kvList';
 /**
  * `onRun` and `onReject` for a deployment that wants to SEE its flows without building somewhere to keep them: a
  * run — and a request that never became one — becomes one more event on the log stream the server already

package/dist/actions.js

@@ -1,16 +1,19 @@
 import { createMemoryJobQueue } from "./modules/actions/jobs/memoryQueue.js";
 import { DEFAULT_MAX_ATTEMPTS, scheduleFor, scheduleJobId, schedulesFor } from "./modules/actions/jobs/schedules.js";
 import { createScheduler } from "./modules/actions/jobs/scheduler.js";
-import { ActionRunError } from "./modules/actions/runtime/errors.js";
+import { ActionRefusal, ActionRunError } from "./modules/actions/runtime/errors.js";
 import { createJobWorker } from "./modules/actions/jobs/worker.js";
 import { createActionJobs } from "./modules/actions/jobs/index.js";
+import { MAX_LIST_BYTES, MAX_LIST_ENTRIES } from "./modules/actions/runtime/kvList.js";
 import { createKvStore } from "./modules/actions/runtime/kvStore.js";
 import { DEFAULT_LIMITS } from "./modules/actions/runtime/limits.js";
 import { createMemoryKv } from "./modules/actions/runtime/memoryKv.js";
+import { spaceKvPatterns } from "./modules/actions/runtime/namespaceKv.js";
 import { createTaskRegistry, taskName } from "./modules/actions/tasks/registry.js";
 import { checkAction } from "./modules/actions/runtime/check.js";
 import { createRejectLogger, createRunLogger } from "./modules/actions/runtime/runLogger.js";
 import { describeCatalog, describeTask } from "./modules/actions/taskCatalog.js";
 import { createActionsModule } from "./modules/actions/index.js";
+import { createRedisKv } from "./modules/actions/runtime/redisKv.js";
 import { cronFiresBetween, cronMatches, cronNextFire, parseCron } from "@plitzi/sdk-shared/actions";
-export { ActionRunError, DEFAULT_LIMITS, DEFAULT_MAX_ATTEMPTS, checkAction, createActionJobs, createActionsModule, createJobWorker, createKvStore, createMemoryJobQueue, createMemoryKv, createRejectLogger, createRunLogger, createScheduler, createTaskRegistry, cronFiresBetween, cronMatches, cronNextFire, describeCatalog, describeTask, parseCron, scheduleFor, scheduleJobId, schedulesFor, taskName };
+export { ActionRefusal, ActionRunError, DEFAULT_LIMITS, DEFAULT_MAX_ATTEMPTS, MAX_LIST_BYTES, MAX_LIST_ENTRIES, checkAction, createActionJobs, createActionsModule, createJobWorker, createKvStore, createMemoryJobQueue, createMemoryKv, createRedisKv, createRejectLogger, createRunLogger, createScheduler, createTaskRegistry, cronFiresBetween, cronMatches, cronNextFire, describeCatalog, describeTask, parseCron, scheduleFor, scheduleJobId, schedulesFor, spaceKvPatterns, taskName };

package/dist/adapters/cloudAdapters.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../helpers/serverLog.js";
 //#region src/adapters/cloudAdapters.ts
 /**
 * A space fetched from Plitzi, for a server that is not Plitzi's.
@@ -150,17 +151,17 @@ var createCloudAdapters = (config) => {
 				})
 			});
 			if (!response.ok) {
-				console.error(`[CloudAdapters] ${what} answered ${response.status}`);
+				serverLog.error("CloudAdapters", `${what} answered ${response.status}`);
 				return;
 			}
 			const payload = await response.json();
 			if (payload.errors?.length) {
-				console.error(`[CloudAdapters] ${what}: ${payload.errors.map((error) => error.message).join("; ")}`);
+				serverLog.error("CloudAdapters", `${what}: ${payload.errors.map((error) => error.message).join("; ")}`);
 				return;
 			}
 			return payload.data;
 		} catch (error) {
-			console.error(`[CloudAdapters] ${what} could not be reached:`, error.message);
+			serverLog.error("CloudAdapters", `${what} could not be reached`, error);
 			return;
 		}
 	};

package/dist/adapters/jsonAdapters.js

@@ -1,8 +1,29 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { serverLog } from "../helpers/serverLog.js";
+import { readFileSync, statSync, writeFileSync } from "node:fs";
 //#region src/adapters/jsonAdapters.ts
 var isDeploymentObject = (v) => typeof v === "object" && ("spaceId" in v || "environment" in v || "error" in v);
-var readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf-8"));
+var createJsonReader = () => {
+	const held = /* @__PURE__ */ new Map();
+	return {
+		read: (filePath) => {
+			const { mtimeMs, size } = statSync(filePath);
+			const hit = held.get(filePath);
+			if (hit?.mtimeMs === mtimeMs && hit.size === size) return hit.value;
+			const value = JSON.parse(readFileSync(filePath, "utf-8"));
+			held.set(filePath, {
+				mtimeMs,
+				size,
+				value
+			});
+			return value;
+		},
+		forget: (filePath) => {
+			held.delete(filePath);
+		}
+	};
+};
 var createJsonAdapters = (config) => {
+	const json = createJsonReader();
 	const pathFor = (spaceId, environment, revision) => {
 		if (typeof config.offlineData === "function") return config.offlineData(spaceId, environment, revision);
 		return typeof config.offlineData === "string" ? config.offlineData : void 0;
@@ -11,9 +32,9 @@ var createJsonAdapters = (config) => {
 		try {
 			const filePath = pathFor(spaceId, environment, revision);
 			if (!filePath) return Promise.resolve(config.offlineData);
-			return Promise.resolve(readJson(filePath));
+			return Promise.resolve(json.read(filePath));
 		} catch (err) {
-			console.error("[JsonAdapters] Failed to read offlineData:", err.message);
+			serverLog.error("JsonAdapters", "Failed to read offlineData", err);
 			return Promise.resolve(void 0);
 		}
 	};
@@ -21,6 +42,7 @@ var createJsonAdapters = (config) => {
 		const filePath = pathFor(spaceId, environment);
 		if (!filePath) return Promise.resolve();
 		writeFileSync(filePath, JSON.stringify(data, null, 2));
+		json.forget(filePath);
 		return Promise.resolve();
 	};
 	const getSpaceDeployment = (req) => {
@@ -31,9 +53,9 @@ var createJsonAdapters = (config) => {
 			revision: 0
 		});
 		if (typeof deployment === "string") try {
-			return Promise.resolve(readJson(deployment));
+			return Promise.resolve(json.read(deployment));
 		} catch (err) {
-			console.error("[JsonAdapters] Failed to read deployment file:", err.message);
+			serverLog.error("JsonAdapters", "Failed to read deployment file", err);
 			return Promise.resolve({ error: {
 				code: 500,
 				message: "Deployment config unreadable"

package/dist/adapters/jsonAdapters.test.d.ts

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

package/dist/auth.d.ts

@@ -23,6 +23,7 @@
 export { createAuth } from './core/auth/createAuth';
 export { createAuthApi } from './core/auth/api';
 export { createCsrf, csrfFailureMessage } from './core/auth/csrf';
+export { SESSION_ACTIVITY_RESOLUTION_SECONDS, activityDue } from './core/auth/sessionActivity';
 export { createAuthorizer, checkPermission, checkSpaceAccess, requirementFor } from './core/auth/authorize';
 export { createCarriers, presentedOrigin } from './core/auth/credentials';
 export { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from './core/auth/domains';
@@ -30,21 +31,23 @@ export { createIdentity } from './core/auth/identity';
 export { generateToken, hashPassword, verifyPassword } from './core/auth/passwords';
 export { BUILT_IN_PROVIDERS, OAuthFailure, createSocialAuth, requestProfileJson } from './core/auth/oauth';
 export { createRedirectPolicy } from './core/auth/redirects';
+export { isDocumentNavigation, renewForNavigation } from './core/auth/renewal';
+export type { RenewalOptions } from './core/auth/renewal';
 export type { RedirectPolicyConfig } from './core/auth/redirects';
 export { applySessionOutcome, authPolicyRules, authRoutes } from './core/auth/routes';
-export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from './core/auth/session';
+export { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, parseSessionHint, readFlowCookie, readRefreshToken, readSessionHint, readSessionToken, sessionCookieParams, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeSessionCookies } from './core/auth/session';
 export { createMemoryRateLimit } from './core/auth/throttle';
 export { createSpaceTokenApi } from './core/auth/spaceTokens';
 export { SCOPES, authFailureMessage, createTokens, userIdOf } from './core/auth/tokens';
-export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp } from './core/auth/totp';
+export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpStep, totpUri, verifyTotp } from './core/auth/totp';
 export type { Auth, AuthConfig } from './core/auth/createAuth';
-export type { AccountAccess, AccountAdapters, AccountQuery, AccountRecord, AccountStatus, AuthApi, AuthApiConfig, AuthOutcome, ExchangeResult, MfaRecord, PasswordPolicy, SecurityEvent, SessionClient, SessionContext, SessionSummary, ThrottleAttempt, ThrottledAction } from './core/auth/api';
+export type { AccountAccess, AccountAdapters, AccountQuery, AccountRecord, AccountStatus, AuthApi, AuthApiConfig, AuthOutcome, ExchangeResult, MfaRecord, PasswordPolicy, SecurityEvent, SessionApp, SessionClient, SessionContext, SessionSummary, ThrottleAttempt, ThrottledAction } from './core/auth/api';
 export type { AuthPolicy, AuthorizeResult, Authorizer, MembershipFacts, PathMatcher, PermissionCheck, Requirement, SpaceAccessCheck } from './core/auth/authorize';
 export type { CredentialCarrier } from './core/auth/credentials';
 export type { Csrf, CsrfCarrier, CsrfConfig, CsrfFailure, CsrfResult, CsrfSubject } from './core/auth/csrf';
 export type { Actor, ActorResult, Grant, GrantOptions, GrantResult, Identity, IdentityAdapters, IdentityConfig, SpaceMembership, StoredSpaceToken } from './core/auth/identity';
 export type { CompletedFlow, OAuthFailureReason, OAuthProfile, OAuthProvider, OAuthProviderConfig, SocialAuth, SocialAuthAdapters, SocialAuthConfig, StartedFlow } from './core/auth/oauth';
 export type { AuthRequest, AuthRoute } from './core/auth/routes';
-export type { CookieCarrier, CookieSink, SessionCookieParams, SessionCookies } from './core/auth/session';
+export type { CookieCarrier, CookieSink, SessionCookieParams, SessionCookies, SessionHint } from './core/auth/session';
 export type { SpaceTokenAdapters, SpaceTokenApi, SpaceTokenContext, SpaceTokenOutcome, SpaceTokenRecord, SpaceTokenSummary } from './core/auth/spaceTokens';
 export type { AuthFailure, MfaChallengePayload, RefreshTokenPayload, SpaceScope, SpaceTokenOptions, SpaceTokenPayload, TokenConfig, TokenScope, Tokens, UserTokenOptions, UserTokenPayload, VerifyResult, WidgetTokenPayload } from './core/auth/tokens';

package/dist/auth.js

@@ -1,19 +1,21 @@
-import { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
+import { appendCookies, clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, parseSessionHint, readFlowCookie, readRefreshToken, readSessionHint, readSessionToken, sessionCookieParams, sessionHintValue, sessionReturnTarget, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
+import { createCsrf, csrfFailureMessage } from "./core/auth/csrf.js";
+import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
+import { isDocumentNavigation, renewForNavigation } from "./core/auth/renewal.js";
+import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
 import { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from "./core/auth/domains.js";
 import { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from "./core/auth/authorize.js";
 import { generateToken, hashPassword, verifyPassword } from "./core/auth/passwords.js";
 import { createMemoryRateLimit } from "./core/auth/throttle.js";
 import { SCOPES, authFailureMessage, createTokens, userIdOf } from "./core/auth/tokens.js";
-import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp } from "./core/auth/totp.js";
+import { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpStep, totpUri, verifyTotp } from "./core/auth/totp.js";
 import { createAuthApi } from "./core/auth/api.js";
-import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
-import { createCsrf, csrfFailureMessage } from "./core/auth/csrf.js";
 import { createIdentity } from "./core/auth/identity.js";
-import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
 import { createAuth } from "./core/auth/createAuth.js";
+import { SESSION_ACTIVITY_RESOLUTION_SECONDS, activityDue } from "./core/auth/sessionActivity.js";
 import { OAuthFailure } from "./core/auth/oauth/types.js";
 import { requestProfileJson } from "./core/auth/oauth/client.js";
 import { createRedirectPolicy } from "./core/auth/redirects.js";
 import { BUILT_IN_PROVIDERS, createSocialAuth } from "./core/auth/oauth/index.js";
 import { createSpaceTokenApi } from "./core/auth/spaceTokens.js";
-export { ANY_DOMAIN, BUILT_IN_PROVIDERS, OAuthFailure, SCOPES, appendCookies, applySessionOutcome, authFailureMessage, authPolicyRules, authRoutes, checkPermission, checkSpaceAccess, clearFlowCookie, clearSessionCookies, corsOrigins, createAuth, createAuthApi, createAuthorizer, createCarriers, createCsrf, createIdentity, createMemoryRateLimit, createRedirectPolicy, createSessionCookies, createSocialAuth, createSpaceTokenApi, createTokens, csrfFailureMessage, domainAllowed, frameAncestors, generateRecoveryCodes, generateToken, generateTotpSecret, hashPassword, hostnameOf, isLocalHost, normalizeDomain, normalizeRecoveryCode, presentedOrigin, randomCode, readFlowCookie, readRefreshToken, readSessionToken, requestProfileJson, requirementFor, sessionCookieParams, sessionHintValue, totpCode, totpUri, userIdOf, verifyPassword, verifyTotp, writeFlowCookie, writeSessionCookies };
+export { ANY_DOMAIN, BUILT_IN_PROVIDERS, OAuthFailure, SCOPES, SESSION_ACTIVITY_RESOLUTION_SECONDS, activityDue, appendCookies, applySessionOutcome, authFailureMessage, authPolicyRules, authRoutes, checkPermission, checkSpaceAccess, clearFlowCookie, clearSessionCookies, corsOrigins, createAuth, createAuthApi, createAuthorizer, createCarriers, createCsrf, createIdentity, createMemoryRateLimit, createRedirectPolicy, createSessionCookies, createSocialAuth, createSpaceTokenApi, createTokens, csrfFailureMessage, domainAllowed, frameAncestors, generateRecoveryCodes, generateToken, generateTotpSecret, hashPassword, hostnameOf, isDocumentNavigation, isLocalHost, normalizeDomain, normalizeRecoveryCode, parseSessionHint, presentedOrigin, randomCode, readFlowCookie, readRefreshToken, readSessionHint, readSessionToken, renewForNavigation, requestProfileJson, requirementFor, sessionCookieParams, sessionHintValue, sessionReturnTarget, totpCode, totpStep, totpUri, userIdOf, verifyPassword, verifyTotp, writeFlowCookie, writeSessionCookies };

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

@@ -36,6 +36,16 @@ export interface AccountAccess {
 export interface SessionClient {
     userAgent?: string;
     ip?: string;
+    /**
+     * The application holding it, when it is not a browser: a native client names itself when it registers
+     * (`Plitzi CLI on carlos-mbp`, software `plitzi-cli`). A user agent says which browser; this says which app.
+     */
+    app?: SessionApp;
+}
+export interface SessionApp {
+    name: string;
+    /** A stable name for the software, the same on every machine — what a list picks an icon by. */
+    softwareId?: string;
 }
 /**
  * What an account is allowed to be. `inactive` is the account's own doing (deactivated, never confirmed);
@@ -47,7 +57,10 @@ export interface SessionSummary {
     id: number;
     userAgent?: string;
     ip?: string;
+    app?: SessionApp;
     createdAt: number;
+    /** When it was last used, where the store keeps it; a session never seen since it was made has none. */
+    lastActiveAt?: number;
     expiresAt: number;
     /** The session asking. A device list without it invites someone to revoke the one they are using. */
     current: boolean;
@@ -58,6 +71,12 @@ export interface MfaRecord {
     /** Unix seconds the enrolment was proven with a real code. Absent means started and never finished. */
     confirmedAt?: number;
     recoveryCodes?: string[];
+    /**
+     * The time step of the last code that was accepted. A code of that step or an earlier one is refused: a code is valid
+     * for its whole window, and one watched over a shoulder or lifted from a phishing page would otherwise sign a second
+     * person in within that window (RFC 6238 §5.2).
+     */
+    lastUsedStep?: number;
 }
 /** Something worth writing down. Fed to an audit log, a webhook, a SIEM — whatever the deployment has. */
 export interface SecurityEvent {
@@ -138,6 +157,15 @@ export interface AccountAdapters {
      * session, which deleting the account's sessions does.
      */
     deleteAccount?: (userId: number) => Promise<void>;
+    /**
+     * What would be lost if this account were deleted now, in sentences its owner can act on — "“Studio” has 3 spaces;
+     * delete them or make somebody else an owner". Any at all and the deletion is refused, with the list.
+     *
+     * The account is what holds things a deployment cannot simply drop: a workspace nobody else owns, the spaces in it,
+     * a plan still being paid for. Deleting it anyway leaves them orphaned — unreachable by anyone, and possibly still
+     * billed. Optional, for a deployment whose accounts own nothing.
+     */
+    deletionBlockers?: (userId: number) => Promise<string[]>;
     /** Page through accounts, for an administrator. `total` is the count before the page was taken. */
     listAccounts?: (query: AccountQuery) => Promise<{
         accounts: AccountRecord[];
@@ -298,7 +326,7 @@ export interface AuthApiConfig {
         allowed: boolean;
         retryAfter?: number;
     }>;
-    /** Where a failed delivery is reported. Defaults to `console.error`; it is never thrown — see `deliver`. */
+    /** Where a failed delivery is reported. Defaults to the server log at `error`; it is never thrown — see `deliver`. */
     onMailError?: (error: unknown, message: {
         to: string;
         template: string;

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. */