@plitzi/sdk-server 0.32.24 → 0.33.0

package/README.md

@@ -1,6 +1,11 @@
 # @plitzi/sdk-server
 
-Server-side rendering (SSR) server for Plitzi spaces. Ships as an HTTP/2 server by default with support for HTTP/1.1 and HTTP/3.
+The page server for Plitzi spaces: server-side rendering, React Server Components, plugins, connectors and the
+HTTP kernel they run on. Ships as an HTTP/2 server by default, with support for HTTP/1.1 and HTTP/3.
+
+This package serves **pages**. The AI surface — the MCP server, its tool engine and the draft-preview
+endpoint — lives in [`@plitzi/sdk-mcp`](../mcp/README.md), which builds on this one. A deployment that only
+renders pages never installs it, and never loads it.
 
 ## Installation
 
@@ -11,29 +16,33 @@ yarn add @plitzi/sdk-server
 ## Usage
 
 ```ts
-import { readFileSync } from 'node:fs';
-import { createSSRServer } from '@plitzi/sdk-server';
+import { createServer } from '@plitzi/sdk-server';
 
-const server = createSSRServer({
-  httpVersion: 2,
-  tls: {
-    key: readFileSync('./certs/server-key.pem'),
-    cert: readFileSync('./certs/server.pem')
-  },
-  adapters: {
-    getOfflineData,
-    getSpaceDeployment
-  }
-});
+const server = createServer({ adapters: { getOfflineData, getSpaceDeployment } });
 
 server.listen(3001);
 ```
 
+That is a whole page server: two adapters saying which space to render and where its content lives. The SDK bundle,
+the transport and the rest have defaults the server can work out for itself — see
+[What the server does without being asked](#what-the-server-does-without-being-asked).
+
+Add TLS and it speaks HTTP/2:
+
+```ts
+import { readFileSync } from 'node:fs';
+
+createServer({
+  tls: { key: readFileSync('./certs/server-key.pem'), cert: readFileSync('./certs/server.pem') },
+  adapters: { getOfflineData, getSpaceDeployment }
+});
+```
+
 ## Configuration
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `httpVersion` | `1 \| 2 \| 3` | `2` | HTTP protocol version. Falls back to the nearest available lower version. |
+| `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)). |
 | `assetVersion` | `string` | — | Cache-buster appended as `?v=<assetVersion>` to all default SDK asset URLs. Compute from file mtime or package version at startup. |
@@ -45,13 +54,16 @@ server.listen(3001);
 | `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. |
-| `publicDir` | `string` | — | Absolute path to a directory served at the root URL level (e.g. `robots.txt`, `favicon.png`). Files are checked after the built-in public directory and before `static` prefix routes. |
+| `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)). |
+| `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. |
+| `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. |
 
 ### HTTP version behaviour
 
@@ -65,45 +77,37 @@ HTTP/3 requires Node.js ≥ 23 started with `--experimental-quic`. When unavaila
 
 ## Adapters
 
-The `adapters` option is the integration point between the SSR server and your data layer.
+The `adapters` option is the integration point between the SSR server and your data layer. For the auth ones, `createAuth` answers all three for you — see [User authentication](#user-authentication).
 
 ```ts
 type SSRAdapters = {
   getOfflineData: (spaceId: number, environment: string, revision?: number) => Promise<OfflineDataRaw | undefined>;
   getSpaceDeployment: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
   getUser?: (req: SSRRequest) => Promise<SSRUser | undefined>;
-  onLogin?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<boolean>;
-  onLogout?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<void>;
-  getRscData?: (
-    req: SSRRequest,
-    spaceId: number,
-    environment: Environment,
-    revision: number,
-    user: SSRUser | undefined,
-    ids?: string[]  // present on partial refresh; absent for full fetch
-  ) => Promise<SSRRscData>;
+  authenticate?: (credentials: Record<string, string>, req: SSRRequest) => Promise<SSRSession | undefined>;
+  endSession?: (req: SSRRequest) => Promise<void>;
+  getRscData?: (context: SSRRscContext) => Promise<SSRRscData>;
 };
 ```
 
 - **`getOfflineData`** — returns the space snapshot (schema, plugins, styles, segments, collections) for SSR.
 - **`getSpaceDeployment`** — resolves which space and environment to render for a given inbound request. Return `{ error: { code, message } }` to abort with an HTTP error. Optionally include `templateProps` to override template variables, or `pluginNames` to activate plugins for the space (see [Plugins](#plugins) and [Template props](#template-props)).
-- **`getUser`** *(optional)* — resolves the authenticated user from the inbound request (e.g. via a session cookie or `Authorization` header). Called in parallel with `getOfflineData` on every cache miss. The returned user is forwarded to the SDK as `authenticated: true` and `user.details`, which controls page-level access for guest vs. registered users. Return `undefined` for unauthenticated requests.
-- **`onLogin`** *(optional)* — called when `POST {loginPath}` is received. Responsible for establishing a session or issuing tokens. The raw request body is available on `req.body` (e.g. `JSON.stringify({ username, password })`), and `res` lets the adapter set the session cookie via `res.setHeader('Set-Cookie', …)`. Return `true` if login succeeded; return `false` to reject it. For a navigation (full-page form submit, `Sec-Fetch-Mode: navigate`) the server responds with a `303` redirect so the view re-renders via a GET; for a fetch it responds `200`/`401`.
-- **`onLogout`** *(optional)* — called when `POST {logoutPath}` is received. Responsible for invalidating any server-side user session or cache entry, and may clear the session cookie via `res`. A navigation receives a `303` redirect; a fetch receives `204 No Content`.
-- **`getRscData`** *(optional)* — called by the RSC endpoint (`/_rsc`) to fetch server-side data for schema elements with `runtime: 'server'`. Receives the full request, space context, and the resolved user so that authenticated operations can be performed. When `ids` is provided the adapter should return data only for those element IDs (partial refresh); omitting `ids` means a full fetch for all elements. Return `{}` when there is no server data for the current request (see [RSC](#react-server-components-rsc)).
+- **`getUser`** *(optional)* — resolves the authenticated user from the inbound request (e.g. via a session cookie or `Authorization` header). Called in parallel with `getOfflineData` on every cache miss. Return `undefined` for unauthenticated requests. What it returns is inlined into the page — `authenticated`, `user.details`, the access token and its expiry — and that does two things: it decides page-level access for guest vs. registered users during the render, and it **saves the browser its first auth request**. The SDK adopts the inlined session on boot, stores it and schedules the renewal, rather than asking the same authority the same question a few milliseconds later. Implement this one adapter and every server-rendered page starts signed in with no round trip; `createAuth` answers it for you.
+- **`authenticate`** *(optional)* — called when `POST {loginPath}` is received, with the credentials already parsed from the body (a posted form or JSON), whatever fields they are. Return a session to grant one, `undefined` to refuse — and never throw for a wrong password. **Identity only**: the cookies, their lifetimes and the readable hint are the server's, which is what keeps a session established here visible to the API side and the other way round. For a navigation (full-page form submit, `Sec-Fetch-Mode: navigate`) the server answers a `303` so the view re-renders via a GET; for a fetch it answers `200` with `{ success, access_token, expire_at }` or `401` with `{ error, reason }` — never a bodyless status, which leaves a caller holding nothing. This route knows a session and not the account behind it; `createServer({ auth })` serves the same path from the auth kernel instead, which answers the full grant.
+- **`endSession`** *(optional)* — called when `POST {logoutPath}` is received. Revoke the session at the source; the server clears the cookies. Clearing them alone would leave the credential itself working for anyone who had already copied it. A navigation receives a `303` redirect; a fetch receives `204 No Content`.
+- **`getRscData`** *(optional)* — called by the RSC endpoint (`/_rsc`), and once per page render, to fetch server-side data for schema elements with `runtime: 'server'`. Takes one `SSRRscContext`: the request, the space context, the resolved user so authenticated operations are safe, `ids` on a partial refresh (absent means every element), and `loadOfflineData`. That last one is the space itself, shared with the page render happening alongside — await it instead of fetching the schema again, and it is read once per request however many callers ask. Return `{}` when there is no server data for the current request (see [RSC](#react-server-components-rsc)).
 
 ## JSON adapters (offline mode)
 
-`createJsonAdapters` provides a ready-made adapter set that reads data from local JSON files, useful for offline mode, integration tests, and static deployments.
+`createJsonAdapters` provides a ready-made adapter set that reads a space from local JSON files, useful for offline mode, integration tests, and static deployments.
 
 ```ts
-import { createSSRServer, createJsonAdapters } from '@plitzi/sdk-server';
+import { createServer, createJsonAdapters } from '@plitzi/sdk-server';
 
-const server = createSSRServer({
+const server = createServer({
   adapters: createJsonAdapters({
     offlineData: '/exports/offline.json',
-    deployment: { spaceId: 1, environment: 'main', revision: 0 },
-    user: { id: 1, username: 'admin', email: 'admin@example.com', verified: true, permissions: [], roles: [] }
+    deployment: { spaceId: 1, environment: 'main', revision: 0 }
   })
 });
 
@@ -116,18 +120,83 @@ server.listen(3001);
 |---|---|---|
 | `offlineData` | `string` | Path to a single JSON file used for every request. |
 | `offlineData` | `(spaceId, environment, revision?) => string` | Function returning the path for the requested space. |
+| `offlineData` | `OfflineDataRaw` | The space itself, for a consumer that already holds it. Read-only: `saveOfflineData` is offered only for a path. |
 | `deployment` | `string` | Path to a JSON file containing an `SSRSpaceDeployment` object. |
 | `deployment` | `SSRSpaceDeployment` | Inline deployment object used for every request. |
 | `deployment` | `Record<hostname, SSRSpaceDeployment>` | Per-hostname map. Use `'*'` as a catch-all. |
+
+## Auth adapters
+
+Where a space comes from and who is looking at it are two integrations, so they are two factories. `createAuthAdapters` answers the identity half, and the two compose with a spread:
+
+```ts
+import { createAuthAdapters, createJsonAdapters, createServer } from '@plitzi/sdk-server';
+
+createServer({
+  adapters: {
+    ...createJsonAdapters({ offlineData: '/exports/offline.json' }),
+    ...createAuthAdapters({ user: req => sessionsFor(req) })
+  }
+});
+```
+
+### `AuthAdaptersConfig`
+
+| Option | Type | Description |
+|---|---|---|
 | `user` | `SSRUser` | Fixed user returned for every request. Useful for testing authenticated flows. |
-| `user` | `(req) => SSRUser \| undefined \| Promise<SSRUser \| undefined>` | Function for dynamic user resolution per request. |
+| `user` | `(req) => SSRUser \| undefined \| Promise<SSRUser \| undefined>` | Dynamic resolution per request. |
+| `authenticate` | `(credentials, req) => Promise<SSRSession \| undefined>` | Verify credentials and mint a session for `POST {loginPath}`. |
+| `endSession` | `(req) => Promise<void>` | Revoke this request's session for `POST {logoutPath}`. |
+
+Anything left out is omitted rather than set to `undefined`, so composing these never unwires an adapter another factory supplied.
+
+A deployment running the auth kernel needs none of this: `createServer({ auth })` fills the same three in from `createAuth(...).ssrAdapters`, and serves the full `/auth` surface instead of just login and logout.
+
+## What the server does without being asked
+
+Four things it used to make every deployment declare, each of which it can answer itself:
+
+| | |
+|---|---|
+| **The SDK bundle** | The rendered page is told to fetch `/sdk-assets/plitzi-sdk.js`, so the server serves it, from its own copy of `@plitzi/plitzi-sdk`. Declaring `static: { '/sdk-assets': … }` still wins — a pinned build, a CDN mirror |
+| **The transport** | `httpVersion` defaults to HTTP/2 with `tls` and HTTP/1.1 without. No browser speaks cleartext h2, so the old default of `2` meant every local run had to say otherwise |
+| **The audience** | `tokens.audience` defaults to the issuer, which is right for a deployment that is its own audience |
+| **The space** | `createJsonAdapters({ offlineData })` alone resolves to space 1, `main`, revision 0 |
+
+A page server therefore needs `port`, `adapters`, and nothing else.
+
+## Health
+
+Every server answers `GET /health` with its identity — no wiring needed:
+
+```json
+{ "Server": "SDK Server", "Version": "v1.2.3", "role": "ssr" }
+```
+
+`check` adds what only the deployment can know, read on every probe. Returning `healthy: false` answers **503**,
+which is what makes this a readiness probe rather than a liveness one: an orchestrator stops routing to a replica
+whose database has gone, instead of sending it traffic it can only fail. A check that throws is itself an unhealthy
+answer, reported as one rather than as a 500.
+
+```ts
+createServer({
+  health: {
+    role: 'ssr',
+    name: 'Acme Renderer',
+    version: pkg.version,
+    check: () => ({ Databases: { mongo: mongo.status() }, healthy: mongo.healthy })
+  },
+  adapters
+});
+```
 
 ## Static files
 
 Map URL prefixes to local directories:
 
 ```ts
-createSSRServer({
+createServer({
   static: {
     '/sdk-assets': './node_modules/@plitzi/plitzi-sdk/dist',
     '/builder-assets': './node_modules/@plitzi/plitzi-builder/dist'
@@ -140,44 +209,61 @@ Static responses include `ETag`, `Last-Modified`, and `Cache-Control` headers. S
 
 ### Public directory
 
-Any file placed in the package's `public/` directory is served automatically at its root path (e.g. `public/favicon.png` → `/favicon.png`).
-
-Use `publicDir` to serve your own root-level files (e.g. `robots.txt`, `sitemap.xml`) without prefixes:
+Use `publicDir` to serve your own root-level files (e.g. `robots.txt`, `sitemap.xml`, `favicon.png`) without prefixes:
 
 ```ts
-createSSRServer({
+createServer({
   publicDir: path.resolve(process.cwd(), 'src/services/ssr/public'),
   adapters: { ... }
 });
 ```
 
-The lookup order for a request is: built-in `public/` → `publicDir` → `static` prefix routes → SSR renderer.
+The lookup order for a request is: `publicDir` → `static` prefix routes → SSR renderer.
 
 `/.well-known/` paths follow the same lookup order: served from `publicDir` if a matching file exists, otherwise `404 Not Found`. They are never handled by the SSR renderer.
 
 ## Compression
 
-Responses are compressed automatically based on the `Accept-Encoding` request header. The server prefers Brotli (`br`) over gzip, and skips compression for payloads under 1 KB.
+Responses are compressed based on the `Accept-Encoding` request header. By default the server offers Brotli, then
+gzip, and leaves payloads under 1 KB alone — below that the compressed body plus its headers is no smaller.
 
-| Encoding | Algorithm | Settings |
-|---|---|---|
-| `br` | Brotli | Quality 4 |
-| `gzip` | Gzip | Level 6 |
+`Content-Encoding` and `Vary: Accept-Encoding` are set on every compressed response. An encoding the client refused
+with `q=0` is never used.
+
+```ts
+createServer({
+  compression: { encodings: ['gzip'], threshold: 2048, gzipLevel: 9 },
+  adapters
+});
+
+// Nothing at all — for a CDN or proxy in front that already compresses.
+createServer({ compression: false, adapters });
+```
 
-`Content-Encoding` and `Vary: Accept-Encoding` are set on all compressed responses.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `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. |
+| `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
+how a handler declares its body must reach the client byte for byte. The OAuth token endpoint in
+[`@plitzi/sdk-mcp`](../mcp/README.md) relies on it: a credential travelling beside a caller-chosen value is the
+shape a BREACH-style attack needs.
 
 ## Render cache
 
 SSR output is cached in-memory per `(spaceId, environment, revision, hostname, path, search)`. The cache uses a 5-minute TTL by default. The `main` environment is always excluded from caching — it is the development environment and its schema changes frequently.
 
 ```ts
-createSSRServer({
+createServer({
   cacheTtlMs: 60_000,  // 1 minute
   adapters: { ... }
 });
 
 // Disable caching entirely
-createSSRServer({
+createServer({
   cacheTtlMs: 0,
   adapters: { ... }
 });
@@ -192,7 +278,7 @@ Responses include an `X-Cache: HIT` or `X-Cache: MISS` header for observability.
 `server.cache` exposes programmatic cache control, useful when content changes and you need to invalidate entries without restarting the server.
 
 ```ts
-const server = createSSRServer({ cacheTtlMs: 300_000, adapters });
+const server = createServer({ cacheTtlMs: 300_000, adapters });
 
 // Invalidate all entries for a specific space
 server.cache?.invalidate({ spaceId: 42 });
@@ -229,7 +315,7 @@ Plugins are React component bundles that extend the Plitzi schema renderer. They
 ```ts
 import type { SSRSpaceDeployment } from '@plitzi/sdk-server';
 
-const server = createSSRServer({
+const server = createServer({
   plugins: {
     // From a source file — compiled to ESM with esbuild
     'my-chart': {
@@ -310,7 +396,7 @@ Plugins listed in `pluginSources` are registered into the plugin manager on-the-
 
 ### Plugin versioning
 
-Every plugin registered through `createSSRServer` (or via `server.plugins.register`) is versioned. If you omit `version`, it defaults to `'1.0.0'`:
+Every plugin registered through `createServer` (or via `server.plugins.register`) is versioned. If you omit `version`, it defaults to `'1.0.0'`:
 
 ```ts
 plugins: {
@@ -364,7 +450,7 @@ To force recompilation without waiting for TTL expiry, call `server.plugins.inva
 Plugins can be registered after the server has started without restarting it. This is useful when plugins are loaded from a database or activated at runtime:
 
 ```ts
-const server = createSSRServer({ adapters });
+const server = createServer({ adapters });
 server.listen(3001);
 
 // Later — register a new plugin dynamically
@@ -426,18 +512,12 @@ Implement `getRscData` in your adapters to serve data from the `/_rsc` endpoint.
 When `ids` is provided the client is performing a **partial refresh** — only return data for those element IDs. When `ids` is absent, return data for all elements (full fetch):
 
 ```ts
-import type { SSRAdapters, SSRRscData, SSRUser } from '@plitzi/sdk-server';
+import type { SSRAdapters, SSRRscContext, SSRRscData } from '@plitzi/sdk-server';
 
-const getRscData = async (
-  req: SSRRequest,
-  spaceId: number,
-  environment: string,
-  revision: number,
-  user: SSRUser | undefined,
-  ids?: string[]
-): Promise<SSRRscData> => {
-  // Only serve data when the schema has RSC enabled
-  const offlineData = await getOfflineData(spaceId, environment, revision);
+const getRscData = async ({ user, ids, loadOfflineData }: SSRRscContext): Promise<SSRRscData> => {
+  // Only serve data when the schema has RSC enabled. `loadOfflineData` joins the read the page render already
+  // started — it never costs a second trip to your database.
+  const offlineData = await loadOfflineData();
   if (!offlineData?.schema.rsc?.enabled) {
     return {};
   }
@@ -502,7 +582,7 @@ The server automatically registers `GET /_rsc` when `adapters.getRscData` is pro
 1. Reads `spaceId`, `environment`, and `revision` from the resolved `spaceDeployment` context.
 2. Reads the authenticated user from `ctx.user`.
 3. Reads optional `?ids=elem1,elem2` for partial refresh.
-4. Calls `adapters.getRscData(req, spaceId, environment, revision, user, ids?)`.
+4. Calls `adapters.getRscData({ req, spaceId, environment, revision, user, ids, loadOfflineData })`.
 5. Returns a JSON payload:
 
 ```json
@@ -523,7 +603,7 @@ The endpoint returns `400` if `spaceId` is missing or invalid, `500` if `getRscD
 ### RSC configuration
 
 ```ts
-createSSRServer({
+createServer({
   rsc: {
     enabled: true,   // default: true when getRscData is provided
     path: '/_rsc'    // default: '/_rsc'
@@ -565,46 +645,123 @@ The hook is backed by `RscProvider`, which fetches `/_rsc` once on mount and upd
 
 ## User authentication
 
-The server supports per-request user resolution to enable page-level access control within a space. Schemas can have pages restricted to registered users; the SDK uses `authenticated` and `user.details` to decide which pages to render.
+Sessions, in one call. `createAuth` takes what only your deployment knows — the signing secret, what you call your
+cookies, and the store your accounts live in — and returns the whole cycle wired together.
+
+```ts
+import { createServer } from '@plitzi/sdk-server';
+import { createAuth } from '@plitzi/sdk-server/kernel';
+
+const auth = createAuth({
+  tokens: { secret: process.env.AUTH_SECRET, issuer: 'https://acme.com', audience: ['https://acme.com'] },
+  cookie: { name: 'acme_session' },
+  adapters: accounts,
+  api: { verifyPassword }
+});
+
+createServer({ port: 443, adapters: { getOfflineData, getSpaceDeployment }, auth });
+```
 
-### `getUser` adapter
+`auth` on the server is the whole of the wiring: it mounts the `/auth` flows, answers the identity adapters a page
+server asks for, and carries the cookie naming with it — so there is no second place to keep in step. Everything is
+still exported separately (`createTokens`, `createIdentity`, `createAuthApi`, `authRoutes`, …) for a deployment that
+wants to assemble or replace one piece.
 
-Implement `getUser` to resolve the current visitor from the request. The server calls it on every render (cache misses only) in parallel with `getOfflineData`, so there is no sequential overhead.
+Nothing here assumes a web framework: a request is `{ headers, hostname, cookies?, query?, body? }` and a response is
+anything that can carry `Set-Cookie`, both true of bare `node:http`.
+
+### Serving the flows from your own server
+
+A page server gets the `/auth` surface from `createServer({ auth })`. A deployment that serves its API elsewhere —
+its own HTTP server, or one behind a router — gets the same flows as ready-made handlers from
+`@plitzi/sdk-server/handlers`.
+
+**That entry imports no framework and does not add one as a dependency.** The request, response and router are
+described by the few properties the handlers touch, which an Express, Connect or Koa object already satisfies and a
+`node:http` server satisfies with a few lines of its own.
 
 ```ts
-import type { SSRUser } from '@plitzi/sdk-server';
+import { createAuthMiddleware, mountAuthRoutes } from '@plitzi/sdk-server/handlers';
 
-const getUser = async (req: SSRRequest): Promise<SSRUser | undefined> => {
-  const token = req.headers['authorization']?.replace('Bearer ', '')
-    ?? parseCookies(req.headers['cookie'] ?? '')['my_session'];
+// Every request: resolves the credential against your policy and puts it on `req.user` / `req.grant`,
+// or answers `{ error, reason }` with the right status.
+app.use(createAuthMiddleware(auth.identity, policy));
 
-  if (!token) {
-    return undefined;
-  }
+// The twelve flows, on whatever has `get` and `post`.
+const router = Router();
+mountAuthRoutes(router, { api: auth.api, cookies: auth.cookies });
+app.use('/auth', router);
+```
 
-  const user = await db.users.findByToken(token);
-  if (!user || user.tokenExpiredAt < Date.now() / 1000) {
-    return undefined;
-  }
+Without a router, `createAuthRouteHandlers` returns the same flows as a list — `{ method, path, handle }` — and
+dispatching them is yours:
 
-  return {
-    id: user.id,
-    username: user.username,
-    email: user.email,
-    verified: user.isActive,
-    permissions: user.permissions,
-    roles: user.roles
-  };
-};
+```ts
+import { createAuthRouteHandlers } from '@plitzi/sdk-server/handlers';
+import { parseRequest } from '@plitzi/sdk-server/kernel';
 
-createSSRServer({ adapters: { getOfflineData, getSpaceDeployment, getUser } });
+const routes = createAuthRouteHandlers({ api: auth.api, cookies: auth.cookies });
+const route = routes.find(r => r.method === req.method && `/auth${r.path}` === req.path);
+await route?.handle(req, res);
 ```
 
+What is *not* here is anything a deployment must decide: its accounts, its policy, its cookie naming. Those stay
+`createAuth`'s. What is here is the part that was identical in every deployment that wrote it by hand — including
+one real trap: `hostname` is a prototype getter on several frameworks, so building the carrier with a spread drops
+it, and every cookie is then named for nowhere.
+
+### What you implement
+
+An account store. These are the only functions the server needs from it, and it never learns whether they read
+Postgres, MySQL, Mongo or an identity service:
+
+| Adapter | Needed for |
+|---|---|
+| `findAccountByToken(token)` | every request — the row **is** the revocation switch, so look accounts up *by token* |
+| `saveSession(userId, session)` | signing in and renewing. Storing the new pair retires the previous one; that is rotation |
+| `clearSession(target)` | signing out |
+| `loadAccess(userId)` | the roles and permissions a grant answers with |
+| `findByUsername(username)` | password sign-in |
+| `findByRefreshToken(token)` | renewal. Answer with `refreshExpiresAt`, or every renewal is refused as expired |
+| `findMembership(userId, spaceId)` | space-level permission checks (`auth.can`) |
+| `createAccount`, `findByEmail`, `setResetToken`, `sendMail`, … | signup, password reset, verification |
+
+**What is absent decides what the deployment offers.** No `createAccount`, no signup — and the route answers 404
+rather than failing at runtime. Declining a flow is one act: do not implement it. `GET /auth/capabilities` publishes
+the result, so a sign-in page renders what the backend actually answers instead of a button that dead-ends.
+
+### What you get
+
+`POST /auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/sessions/revoke`, `/auth/exchange`, `GET /auth/session`,
+`GET /auth/capabilities`, plus signup, password reset and verification where the adapters support them. Sign-in and
+sign-out also answer a full-page form submission with a `303` so the view re-renders, which a `fetch` client does
+not need and a `<form>` does.
+
+Behaviour you do not have to get right yourself: the credential is renewed ahead of expiry and rotated when it is;
+signing out revokes at the source rather than only clearing the browser's copy; a readable hint cookie rides beside
+the session carrying nothing but expiry timestamps, so a page can tell that nobody is signed in without a request;
+and every refusal names a machine-readable `reason`, so a client can tell "renew me" from "you are gone".
+
+### Beyond the defaults
+
+| Config | Effect |
+|---|---|
+| `cookie` | Name, domain, `SameSite`, `Secure`, the refresh path, the hint suffix. Defaults derive from the request host |
+| `basePath` | Where the flows are mounted. The guard's rules follow it |
+| `rules` / `fallback` | Extra authorization rules, applied before the derived ones, and what an unlisted path requires |
+| `identity` | Your own hosts and origins — the floor for domain binding and framing |
+| `tokens.lifetimes` | How long each credential lives |
+
+A working example is [`examples/02-with-users`](../../examples/02-with-users).
+
 ### `SSRUser`
 
+What a rendered page sees, so a schema can restrict pages to signed-in visitors — the SDK reads `authenticated` and
+`user.details`.
+
 | Field | Type | Description |
 |---|---|---|
-| `token` | `string` | Opaque token or JWT from the auth provider. |
+| `token` | `string` | Opaque token or JWT. |
 | `id` | `number` | Unique user identifier. |
 | `username` | `string` | Display name. |
 | `email` | `string` | Email address. |
@@ -612,59 +769,26 @@ createSSRServer({ adapters: { getOfflineData, getSpaceDeployment, getUser } });
 | `permissions` | `string[]` | Permission keys for fine-grained access control. |
 | `roles` | `string[]` | Role names. |
 
-### Login endpoint
+### Bringing your own identity entirely
 
-The server exposes a built-in `POST /auth/login` endpoint. When hit, it calls `adapters.onLogin(req, res)`. The raw request body is on `req.body`, and `res` is used to set the session cookie. A navigation (full-page form submit) gets a `303` redirect so the view re-renders; a fetch gets `200 OK` on success or `401 Unauthorized` when the adapter returns `false`:
+Skip `createAuth` and implement three adapters directly — the server then knows only what you tell it:
 
 ```ts
-const onLogin = async (req: SSRRequest, res: SSRResponseHelpers): Promise<boolean> => {
-  const { username, password } = JSON.parse(req.body ?? '{}');
-  const session = await db.users.authenticate(username, password);
-  if (!session) return false;
-
-  res.setHeader('Set-Cookie', `my_session=${session.token}; Path=/; HttpOnly; SameSite=Lax`);
-  return true;
-};
-
-createSSRServer({ adapters: { getOfflineData, getSpaceDeployment, onLogin } });
-```
-
-The path is configurable via `loginPath`. Set it to `false` to disable the endpoint entirely:
-
-```ts
-createSSRServer({
-  loginPath: '/api/login',   // custom path
-  // loginPath: false,       // disable
-  adapters: { ... }
+createServer({
+  adapters: {
+    getOfflineData,
+    getSpaceDeployment,
+    getUser: async req => /* … resolve the visitor, or undefined */,
+    authenticate: async (credentials, req) => /* … a session, or undefined to refuse */,
+    endSession: async req => /* … revoke it */
+  },
+  loginPath: '/api/login',   // or false to serve no endpoint
+  logoutPath: false
 });
 ```
 
-### Logout endpoint
-
-The server exposes a built-in `POST /auth/logout` endpoint. When hit, it calls `adapters.onLogout(req, res)`. A navigation gets a `303` redirect so the view re-renders logged out; a fetch gets `204 No Content`. Implement `onLogout` to invalidate the session or cached user entry and clear the cookie:
-
-```ts
-const onLogout = async (req: SSRRequest, res: SSRResponseHelpers): Promise<void> => {
-  const token = parseCookies(req.headers['cookie'] ?? '')['my_session'];
-  if (token) {
-    await cache.delete(`user-${token}`);
-  }
-
-  res.setHeader('Set-Cookie', 'my_session=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0');
-};
-
-createSSRServer({ adapters: { getOfflineData, getSpaceDeployment, getUser, onLogout } });
-```
-
-The path is configurable via `logoutPath`. Set it to `false` to disable the endpoint entirely:
-
-```ts
-createSSRServer({
-  logoutPath: '/api/logout',   // custom path
-  // logoutPath: false,        // disable
-  adapters: { ... }
-});
-```
+`authenticate` returns identity and nothing else: the cookies, their lifetimes and the readable hint are the
+server's, which is what keeps a session established on the API side visible to the renderer and the other way round.
 
 ## Basic auth
 
@@ -694,7 +818,7 @@ const rateLimitMiddleware: SSRMiddleware = async (req, res, next) => {
   return next();
 };
 
-createSSRServer({
+createServer({
   middlewares: [corsMiddleware, rateLimitMiddleware],
   adapters: { ... }
 });
@@ -702,12 +826,62 @@ createSSRServer({
 
 Middlewares run after the built-in auth checks (Basic auth, `spaceDeployment` resolution, `getUser`) and before RSC and the SSR renderer.
 
+## Extending the pipeline
+
+A page server runs a fixed, ordered pipeline of stages. Order is an invariant — static assets first, then stages
+that authenticate themselves, then the auth middleware chain, then the data services, then the renderer — so a
+companion package does not hand over a list of stages. It hands them over by **slot**, and this package decides
+where the slot lands:
+
+```ts
+import { createServer } from '@plitzi/sdk-server';
+import { mcpExtensions } from '@plitzi/sdk-mcp';
+
+const server = createServer({ adapters }, mcpExtensions());
+```
+
+| Slot | Runs | For |
+|---|---|---|
+| `preAuth` | after static assets, **before** the auth middleware chain | stages that gate themselves — on a shared secret, a bearer token, or nothing at all |
+| `data` | after the auth chain, before the page render | stages serving data to an already-identified visitor |
+
+Pass only the stages you want rather than the whole bundle:
+
+```ts
+import { previewStage } from '@plitzi/sdk-mcp';
+
+// Draft-preview, but no MCP endpoint on this port.
+const server = createServer({ adapters, preview: { enabled: true, secret } }, { preAuth: [previewStage] });
+```
+
+A stage receives the `SSRContext` — the request, the config, and the render singletons (`renderFn`,
+`pluginManager`, `caches`) — and returns `true` when it has answered, `false` to fall through. Passing the stages
+**is** the decision to mount them: there is no config flag mirroring it, and a server that never passes them
+never loads them.
+
+## Running it locally
+
+The package ships a small harness in [`dev/`](./dev) — file-backed adapters over a sample space, three demo
+plugins and a demo style document — so you can exercise SSR and RSC without standing up a platform:
+
+```bash
+yarn start        # pages + RSC on :3002 against dev/sample
+yarn start:dev    # same, resolving every @plitzi/* workspace package from source
+yarn start:watch  # same as start, restarting on change
+```
+
+`SSR_ENABLED=0` and `RSC_ENABLED=0` switch the surfaces off individually; `LOG_REQUESTS=0` quiets the request log.
+Writes land back in `dev/sample`, so `git restore dev/sample` resets a session.
+
+`dev/` is not part of the published package and nothing in `src/` imports it — it consumes this package's public
+API exactly as a consumer would.
+
 ## SSR-only mode
 
 Set `ssrOnly: true` to serve raw server-rendered HTML without any client-side scripts. Useful for inspecting SSR output or building purely static pages:
 
 ```ts
-createSSRServer({
+createServer({
   ssrOnly: true,
   adapters: { ... }
 });
@@ -724,7 +898,7 @@ import { statSync } from 'node:fs';
 
 const assetVersion = String(statSync('./node_modules/@plitzi/plitzi-sdk/dist/plitzi-sdk.js').mtimeMs | 0);
 
-createSSRServer({
+createServer({
   assetVersion,
   adapters: { ... }
 });
@@ -755,7 +929,7 @@ const templateFn: SSRTemplateFn = ({ html, offlineData, jsPath, cssPath, plugins
   </html>
 `;
 
-createSSRServer({ templateFn, adapters: { ... } });
+createServer({ templateFn, adapters: { ... } });
 ```
 
 The function is called once per render (cache misses only). The built-in `template.ejs` is used as fallback when `templateFn` is not set.
@@ -798,7 +972,7 @@ return {
 Enable streaming to reduce TTFB by sending the `<head>` section to the browser before React finishes rendering:
 
 ```ts
-createSSRServer({
+createServer({
   streaming: true,
   adapters: { ... }
 });
@@ -839,23 +1013,11 @@ When `devMode: true`, per-phase timing is instrumented on every render and repor
 
 In production (`devMode: false`) timing instrumentation is skipped entirely — no `Server-Timing` header, no console output.
 
-## Agent skill
-
-This package ships an [Agent Skill](https://agentskills.io/) for `plitzi_render`, the MCP tool that renders a
-self-contained UI widget from a batch of operations. The skill teaches an agent when to show a widget instead of
-writing prose, the shape of a good call, the layout/theme traps that make a widget look wrong in a chat panel, and
-how to iterate on a widget it already rendered.
-
-It lives in [`skills/plitzi-render`](./skills/plitzi-render/SKILL.md) and is a plain `SKILL.md`, so it installs by
-copying that folder into the skills directory of the agent you use (Claude Code, VS Code / Copilot, Codex, Gemini
-CLI, Cline, Goose…):
-
-```bash
-cp -R node_modules/@plitzi/sdk-server/skills/plitzi-render ~/.claude/skills/
-```
+## Examples
 
-The skill only pays off with the Plitzi MCP server connected — it defers every detail to the `plitzi://render/guide`
-resource the server publishes, so the two never drift apart.
+Runnable setups live in [`examples/`](../../examples): server-rendering a space, adding React Server Components,
+and mounting the MCP endpoint and draft preview alongside pages. Each one starts with `yarn start` and is a real
+package, not a snippet.
 
 ## Exported types
 
@@ -885,6 +1047,8 @@ import type {
   PluginRegistry,
   CacheFilter,
   CacheManager,
-  JsonAdaptersConfig
+  JsonAdaptersConfig,
+  AuthAdapters,
+  AuthAdaptersConfig
 } from '@plitzi/sdk-server';
 ```