@plitzi/sdk-server 0.32.24 → 0.33.0

package/dist/core/http/stages/static.js

@@ -1,10 +1,6 @@
+import { resolveSdkAssetsDir } from "../../sdkAssets.js";
 import { serveStatic } from "../../staticFiles.js";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 //#region src/core/http/stages/static.ts
-var __dirname = path.dirname(fileURLToPath(import.meta.url));
-var BUILTIN_PUBLIC_DIR = path.resolve(__dirname, "../../../public");
-var builtinPublicStage = (ctx) => serveStatic(ctx.req, ctx.res, BUILTIN_PUBLIC_DIR);
 var publicDirStage = (ctx) => ctx.config.publicDir ? serveStatic(ctx.req, ctx.res, ctx.config.publicDir) : false;
 var wellKnownStage = (ctx) => {
 	if (!ctx.req.path.startsWith("/.well-known/")) return false;
@@ -29,5 +25,24 @@ var configStaticStage = (ctx) => {
 	}
 	return false;
 };
+var sdkAssetsDir = resolveSdkAssetsDir();
+/**
+* The SDK bundle, served from this package's own copy.
+*
+* The rendered page is told to fetch `/sdk-assets/plitzi-sdk.js`, and it is this server that puts the URL there — so
+* answering it is this server's job too, not a mount every deployment has to remember to declare. It runs after
+* `configStaticStage`, so a deployment serving its own build (a pinned version, a CDN mirror) still wins by
+* declaring `static: { '/sdk-assets': … }`.
+*/
+var sdkAssetsStage = (ctx) => {
+	if (!sdkAssetsDir || !ctx.req.path.startsWith(`/sdk-assets/`)) return false;
+	ctx.res.setHeader("Access-Control-Allow-Origin", "*");
+	ctx.res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
+	const strippedReq = {
+		...ctx.req,
+		path: ctx.req.path.slice(11) || "/"
+	};
+	return serveStatic(strippedReq, ctx.res, sdkAssetsDir);
+};
 //#endregion
-export { builtinPublicStage, configStaticStage, publicDirStage, wellKnownStage };
+export { configStaticStage, publicDirStage, sdkAssetsStage, wellKnownStage };

package/dist/core/http/types.d.ts

@@ -0,0 +1,35 @@
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+import { ServerCaches } from '../../helpers/cache';
+import { PluginManager } from '../../plugins/manager';
+import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
+import { IncomingMessage } from 'node:http';
+export interface BaseContext {
+    raw: IncomingMessage;
+    rawRes: RawResponse;
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    config: SSRServerConfig;
+    port: number;
+    /** Set by the stage that answers when the path alone does not identify the work (the MCP endpoint serves every
+     *  JSON-RPC method on the same URL). The dispatcher folds it into the access log. */
+    operation?: string;
+}
+export interface SSRContext extends BaseContext {
+    config: SSRPageServerConfig;
+    renderFn: SSRTemplateFn;
+    caches: ServerCaches;
+    pluginManager: PluginManager;
+}
+export type Stage<C extends BaseContext = BaseContext> = (ctx: C) => boolean | Promise<boolean>;
+/** Where a package built on this one hands its stages to a page server. Slots, not a list, because the ORDER is
+ *  the pipeline's invariant and cannot be expressed across a package boundary: a stage's slot states what it
+ *  needs from the pipeline, and the pipeline decides where that lands. `@plitzi/sdk-mcp` is the in-tree
+ *  consumer. Declared here, with the context types, so the kernel entry can carry it without reaching into the
+ *  registry — which imports every page stage. */
+export type PipelineExtensions = {
+    /** Stages that gate themselves — on a shared secret, a bearer token, or nothing at all — and so must run
+     *  BEFORE the auth middleware chain. The MCP endpoint, the widget proxy and the draft-preview endpoint. */
+    preAuth?: Stage<SSRContext>[];
+    /** Stages serving data to an already-identified visitor: after the auth chain, before the page render. */
+    data?: Stage<SSRContext>[];
+};

package/dist/{modules/mcp/constants.js → core/previewToken.js}

@@ -1,4 +1,4 @@
-//#region src/modules/mcp/constants.ts
+//#region src/core/previewToken.ts
 var PREVIEW_TOKEN_PARAM = "__pt";
 //#endregion
 export { PREVIEW_TOKEN_PARAM };

package/dist/core/sdkAssets.d.ts

@@ -0,0 +1,16 @@
+/** Where the rendered page is told to fetch the SDK bundle from. Emitted by the render, so it is also served. */
+export declare const SDK_ASSETS_PREFIX = "/sdk-assets";
+/**
+ * The SDK's built output, resolved through the module system rather than guessed from `process.cwd()`.
+ *
+ * The rendered page asks for `/sdk-assets/plitzi-sdk.js` — the server puts that URL there itself — so the server is
+ * also what should answer it. It used to be a mount every deployment had to declare, and forgetting it produced no
+ * error at all: the asset requests fell through to the page renderer, which answered each one with a 200 and an HTML
+ * document. The browser then refused them for their MIME type and the page stayed blank. A missing line of config
+ * that looks like a broken SDK is not a choice worth offering.
+ *
+ * Returns undefined if the SDK is not installed, which is legitimate: a server rendering `ssrOnly` pages, or one
+ * whose deployment serves the bundle from a CDN, needs none of this.
+ */
+export declare const resolveSdkAssetsDir: () => string | undefined;
+export declare const sdkAssetVersion: () => string;

package/dist/core/sdkAssets.js

@@ -0,0 +1,46 @@
+import { createRequire } from "node:module";
+import { statSync } from "node:fs";
+import path from "node:path";
+//#region src/core/sdkAssets.ts
+/** Where the rendered page is told to fetch the SDK bundle from. Emitted by the render, so it is also served. */
+var SDK_ASSETS_PREFIX = "/sdk-assets";
+/**
+* The SDK's built output, resolved through the module system rather than guessed from `process.cwd()`.
+*
+* The rendered page asks for `/sdk-assets/plitzi-sdk.js` — the server puts that URL there itself — so the server is
+* also what should answer it. It used to be a mount every deployment had to declare, and forgetting it produced no
+* error at all: the asset requests fell through to the page renderer, which answered each one with a 200 and an HTML
+* document. The browser then refused them for their MIME type and the page stayed blank. A missing line of config
+* that looks like a broken SDK is not a choice worth offering.
+*
+* Returns undefined if the SDK is not installed, which is legitimate: a server rendering `ssrOnly` pages, or one
+* whose deployment serves the bundle from a CDN, needs none of this.
+*/
+var resolveSdkAssetsDir = () => {
+	try {
+		const require = createRequire(import.meta.url);
+		return path.dirname(require.resolve("@plitzi/plitzi-sdk/plitzi-sdk.css"));
+	} catch {
+		return;
+	}
+};
+/**
+* A cache-buster for the SDK URLs, taken from the bundle's own mtime.
+*
+* The assets are served with a long `Cache-Control`, so something has to change in the URL when the bundle does or
+* browsers keep the old one. Since the version a deployment runs IS the version of this package, the server can work
+* it out — nobody should have to compute it and pass it in, and forgetting to is a stale bundle nobody can explain.
+*/
+var cachedVersion;
+var sdkAssetVersion = () => {
+	if (cachedVersion !== void 0) return cachedVersion;
+	const dir = resolveSdkAssetsDir();
+	try {
+		cachedVersion = dir ? Math.floor(statSync(path.join(dir, "plitzi-sdk.js")).mtimeMs).toString(36) : "";
+	} catch {
+		cachedVersion = "";
+	}
+	return cachedVersion;
+};
+//#endregion
+export { SDK_ASSETS_PREFIX, resolveSdkAssetsDir, sdkAssetVersion };

package/dist/core/server/baseServer.js

@@ -1,8 +1,22 @@
 import { buildTransport, protoLabel } from "../transports.js";
 //#region src/core/server/baseServer.ts
+/**
+* What went wrong taking the port, and what to do about it.
+*
+* A server that cannot bind used to surface as an unhandled `error` event: a stack trace through `node:net` naming
+* neither the port nor the server, printed as if the process had crashed at random. It is the first thing a new
+* deployment hits — two roles configured on one port, or a previous run still holding it — so it is worth saying
+* plainly.
+*/
+var bindFailure = (error, port, label) => {
+	if (error.code === "EADDRINUSE") return `[${label}] cannot bind port ${port}: already in use. Another server is running, or the previous one has not released it yet — find it with \`lsof -iTCP:${port} -sTCP:LISTEN\`, or start this one on another port.`;
+	if (error.code === "EACCES") return `[${label}] cannot bind port ${port}: permission denied. Ports below 1024 need privileges — run elevated, or use a port above 1024 and put a proxy in front.`;
+	if (error.code === "EADDRNOTAVAIL") return `[${label}] cannot bind port ${port}: the requested host is not an address of this machine.`;
+	return `[${label}] failed to bind port ${port}: ${error.message}`;
+};
 var createHttpServer = (config, makeHandlerForPort, parts) => {
 	const { label } = parts;
-	const version = config.httpVersion ?? 2;
+	const version = config.httpVersion ?? (config.tls ? 2 : 1);
 	if (version >= 3 && !config.tls) throw new Error(`[${label}] httpVersion: ${version} requires a tls config with key and cert`);
 	let primary;
 	let h3;
@@ -12,16 +26,37 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 		listen(port, host = "0.0.0.0") {
 			const handler = makeHandlerForPort(port);
 			({primary, h3} = buildTransport(config, handler, port, label));
+			primary.on("error", (error) => {
+				if (config.onListenError) {
+					config.onListenError(error, {
+						port,
+						host,
+						label
+					});
+					return;
+				}
+				console.error(bindFailure(error, port, label));
+				process.exitCode = 1;
+				process.exit(1);
+			});
 			primary.listen(port, host, () => {
 				console.log(`[${label}] ${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
 			});
 		},
 		async close() {
 			parts.onDestroy?.();
-			const closeOne = (srv) => new Promise((resolve, reject) => {
-				srv.close((err) => err ? reject(err) : resolve());
-			});
-			await Promise.all([closeOne(primary), ...h3 ? [closeOne(h3)] : []]);
+			const open = [primary, h3].filter((srv) => srv !== void 0);
+			primary = void 0;
+			h3 = void 0;
+			await Promise.all(open.map((srv) => new Promise((resolve, reject) => {
+				srv.close((err) => {
+					if (err && err.code !== "ERR_SERVER_NOT_RUNNING") {
+						reject(err);
+						return;
+					}
+					resolve();
+				});
+			})));
 		}
 	};
 };

package/dist/core/server/pageServer.d.ts

@@ -0,0 +1,7 @@
+import { PipelineExtensions } from '../http/types';
+import { ResolvedServices } from '../services/resolve';
+import { SSRPageServerConfig, SSRServer } from '@plitzi/sdk-shared';
+/** The page-serving machinery: html/rsc caches, the render template and the plugin manager, driving the page
+ *  pipeline. Which services it mounts is the CALLER's decision — {@link createServer} passes whatever the config
+ *  enables — so this unit never second-guesses a factory's promise. */
+export declare const createPageServer: (config: SSRPageServerConfig, services: ResolvedServices, extensions?: PipelineExtensions) => SSRServer;

package/dist/core/server/pageServer.js

@@ -1,19 +1,19 @@
 import { createHttpServer } from "./baseServer.js";
-import { makeHandler } from "../http/dispatcher.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildCacheManager } from "../../helpers/cache/cacheManager.js";
 import { createServerCaches, destroyServerCaches } from "../../helpers/cache/serverCaches.js";
-import { createMemoryDraftStore } from "../../modules/ssr/preview.js";
-import { buildPagePipeline } from "../services/registry.js";
 import normalizePlugins, { normalizePluginSource } from "../../helpers/normalizePlugins.js";
+import { invalidatePluginComponentCache } from "../../modules/ssr/loadPluginComponents.js";
+import { createMemoryDraftStore } from "../../modules/ssr/preview.js";
 import { compileTemplate } from "../../modules/ssr/template.js";
 import { PluginManager } from "../../plugins/manager.js";
-import { resolveServices } from "../services/resolve.js";
+import { makeHandler } from "../http/dispatcher.js";
+import { buildPagePipeline } from "../services/registry.js";
 //#region src/core/server/pageServer.ts
 /** The page-serving machinery: html/rsc caches, the render template and the plugin manager, driving the page
 *  pipeline. Which services it mounts is the CALLER's decision — {@link createServer} passes whatever the config
-*  enables, createSSRServer pins the page surface — so this unit never second-guesses a factory's promise. */
-var createPageServer = (config, services) => {
+*  enables — so this unit never second-guesses a factory's promise. */
+var createPageServer = (config, services, extensions) => {
 	const { cacheTtlMs: htmlTtlMs = DEFAULT_TTL_MS.html } = config;
 	if (config.preview?.enabled && !config.draftStore) config.draftStore = createMemoryDraftStore();
 	const caches = createServerCaches(htmlTtlMs, config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc);
@@ -25,9 +25,12 @@ var createPageServer = (config, services) => {
 			const normalized = normalizePluginSource(source);
 			pluginManager.register(`${name}@${normalized.version}`, normalized);
 		},
-		invalidate: (name, version) => pluginManager.invalidate(name, version)
+		invalidate: async (name, version) => {
+			await pluginManager.invalidate(name, version);
+			invalidatePluginComponentCache();
+		}
 	};
-	const stages = buildPagePipeline(services);
+	const stages = buildPagePipeline(services, extensions);
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
 			raw,
@@ -40,7 +43,7 @@ var createPageServer = (config, services) => {
 			caches,
 			pluginManager
 		});
-		return makeHandler("SSR", buildContext, stages);
+		return makeHandler("SSR", buildContext, stages, config.compression);
 	};
 	return createHttpServer(config, makeHandlerForPort, {
 		label: "SSR",
@@ -52,12 +55,5 @@ var createPageServer = (config, services) => {
 		}
 	});
 };
-/** The page server: SSR and RSC, and nothing else. MCP is pinned OFF here even when the config asks for it —
-*  what a factory named after a surface mounts must be readable from its name alone. A deployment that wants
-*  both surfaces in one process asks {@link createServer} for them; a dedicated MCP server is createMCPServer. */
-var createSSRServer = (config) => createPageServer(config, {
-	...resolveServices(config),
-	mcp: false
-});
 //#endregion
-export { createPageServer, createSSRServer };
+export { createPageServer };

package/dist/core/services/action.d.ts

@@ -0,0 +1,9 @@
+import { SSRContext, Stage } from '../http/types';
+/**
+ * Write endpoint for server-driven providers. RSC is read-only, so this is the only path a page has to mutate a
+ * connected backend — and it answers POST on its own path alone, never falling through to SSR.
+ *
+ * Inert unless the consumer supplied the connector lookups: without them there is no manifest to authorize a
+ * write against, and guessing would be the whole vulnerability.
+ */
+export declare const actionStage: Stage<SSRContext>;

package/dist/core/services/action.js

@@ -0,0 +1,21 @@
+import { readRawBody } from "../requestParser.js";
+import { handleAction } from "../../modules/actions/handler.js";
+//#region src/core/services/action.ts
+/**
+* Write endpoint for server-driven providers. RSC is read-only, so this is the only path a page has to mutate a
+* connected backend — and it answers POST on its own path alone, never falling through to SSR.
+*
+* Inert unless the consumer supplied the connector lookups: without them there is no manifest to authorize a
+* write against, and guessing would be the whole vulnerability.
+*/
+var actionStage = async (ctx) => {
+	const { config, req } = ctx;
+	const actionPath = config.action?.path ?? "/_action";
+	if (!config.action?.lookups || req.method !== "POST" || req.path !== actionPath) return false;
+	ctx.operation = "action";
+	req.body = await readRawBody(ctx.raw);
+	await handleAction(req, ctx.res, config, config.action.lookups);
+	return true;
+};
+//#endregion
+export { actionStage };

package/dist/core/services/registry.d.ts

@@ -0,0 +1,3 @@
+import { ResolvedServices } from './resolve';
+import { PipelineExtensions, SSRContext, Stage } from '../http/types';
+export declare const buildPagePipeline: (services: ResolvedServices, extensions?: PipelineExtensions) => Stage<SSRContext>[];

package/dist/core/services/registry.js

@@ -1,39 +1,29 @@
-import { mcpOnlyStage, mcpStage } from "./mcp.js";
-import { oauthGuardStage, oauthStage } from "./oauth.js";
-import { previewStage } from "./preview.js";
-import { widgetProxyStage } from "./proxy.js";
+import { actionStage } from "./action.js";
 import { rscStage } from "./rsc.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
 import { authRoutesStages } from "../http/stages/authRoutes.js";
 import { healthStage } from "../http/stages/health.js";
 import { middlewaresStage } from "../http/stages/middlewares.js";
 import { pluginAssetsStage } from "../http/stages/pluginAssets.js";
-import { builtinPublicStage, configStaticStage, publicDirStage, wellKnownStage } from "../http/stages/static.js";
+import { configStaticStage, publicDirStage, sdkAssetsStage, wellKnownStage } from "../http/stages/static.js";
 //#region src/core/services/registry.ts
-var buildPagePipeline = (services) => {
+var buildPagePipeline = (services, extensions = {}) => {
 	const stages = [
 		healthStage,
-		builtinPublicStage,
 		publicDirStage,
 		wellKnownStage,
 		pluginAssetsStage,
 		...authRoutesStages,
-		configStaticStage
+		configStaticStage,
+		sdkAssetsStage
 	];
-	if (services.mcp) stages.push(widgetProxyStage, mcpStage);
-	stages.push(previewStage);
+	stages.push(...extensions.preAuth ?? []);
 	stages.push(middlewaresStage);
 	if (services.rsc) stages.push(rscStage);
+	stages.push(actionStage);
+	stages.push(...extensions.data ?? []);
 	stages.push(services.ssr ? ssrStage : notFoundStage);
 	return stages;
 };
-var buildMCPPipeline = () => [
-	healthStage,
-	configStaticStage,
-	widgetProxyStage,
-	oauthStage,
-	oauthGuardStage,
-	mcpOnlyStage
-];
 //#endregion
-export { buildMCPPipeline, buildPagePipeline };
+export { buildPagePipeline };

package/dist/{src/core → core}/services/resolve.d.ts

@@ -1,3 +1,4 @@
 import { ServerServices, SSRServerConfig } from '@plitzi/sdk-shared';
 export type ResolvedServices = Required<ServerServices>;
 export declare const resolveServices: (config: SSRServerConfig) => ResolvedServices;
+export declare const resolveRscEndpoint: (config: SSRServerConfig) => string | undefined;

package/dist/core/services/resolve.js

@@ -3,10 +3,12 @@ var resolveServices = (config) => {
 	const services = config.services ?? {};
 	return {
 		ssr: services.ssr ?? true,
-		rsc: services.rsc ?? !!config.adapters.getRscData,
-		mcp: services.mcp ?? config.mcpAi?.enabled ?? false,
-		ai: services.ai ?? false
+		rsc: services.rsc ?? !!config.adapters.getRscData
 	};
 };
+var resolveRscEndpoint = (config) => {
+	if (!resolveServices(config).rsc || !(config.rsc?.enabled ?? true) || !config.adapters.getRscData) return;
+	return config.rsc?.path ?? "/_rsc";
+};
 //#endregion
-export { resolveServices };
+export { resolveRscEndpoint, resolveServices };

package/dist/core/services/rsc.js

@@ -1,9 +1,10 @@
+import { resolveRscEndpoint } from "./resolve.js";
 import { handleRsc } from "../../modules/rsc/handler.js";
 //#region src/core/services/rsc.ts
 var rscStage = async (ctx) => {
 	const { config, req } = ctx;
-	const rscPath = config.rsc?.path ?? "/_rsc";
-	if (!(config.rsc?.enabled ?? true) || req.method !== "GET" || req.path !== rscPath) return false;
+	const rscPath = resolveRscEndpoint(config);
+	if (!rscPath || req.method !== "GET" || req.path !== rscPath) return false;
 	ctx.operation = "rsc";
 	await handleRsc(req, ctx.res, config, ctx.pluginManager, ctx.caches.rsc);
 	return true;

package/dist/core/staticFiles.js

@@ -1,6 +1,6 @@
 import { getCacheControl, getMimeType } from "./mimeTypes.js";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 //#region src/core/staticFiles.ts
 var buildEtag = (stat) => `"${stat.mtimeMs.toString(36)}-${stat.size.toString(36)}"`;
 var serveFile = (req, res, filePath, stat) => {

package/dist/{src/core → core}/transports.d.ts

@@ -4,6 +4,9 @@ import { IncomingMessage } from 'node:http';
 export type CloseableServer = {
     close: (cb?: (err?: Error) => void) => unknown;
     listen: (port: number, host: string, cb: () => void) => unknown;
+    /** Bind failures arrive here. Without a listener Node throws the `error` event as an uncaught exception, which
+     *  is how a taken port used to read as a crash in `node:net` rather than as this server not starting. */
+    on: (event: 'error', listener: (error: NodeJS.ErrnoException) => void) => unknown;
 };
 export type Handler = (req: IncomingMessage, res: RawResponse) => void;
 export declare const tlsOptions: (config: SSRServerConfig, label?: string) => {

package/dist/core/transports.js

@@ -35,12 +35,13 @@ var buildTransport = (config, handler, port, label = "Server") => {
 				console.warn(`[${label}] HTTP/3 unavailable — start Node.js with --experimental-quic (requires Node ≥ 23). Falling back to HTTP/2.`);
 			}
 		})();
-	} else if (version >= 2) if (config.tls) primary = http2.createSecureServer({
-		...tlsOptions(config, label),
-		allowHTTP1: true
-	}, handler);
-	else primary = http.createServer(handler);
-	else if (config.tls) primary = https.createServer(tlsOptions(config, label), handler);
+	} else if (version >= 2) {
+		if (config.tls) primary = http2.createSecureServer({
+			...tlsOptions(config, label),
+			allowHTTP1: true
+		}, handler);
+		else primary = http.createServer(handler);
+	} else if (config.tls) primary = https.createServer(tlsOptions(config, label), handler);
 	else primary = http.createServer(handler);
 	return {
 		primary,

package/dist/handlers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The auth kernel as ready-made request handlers. Import as `@plitzi/sdk-server/handlers`.
+ *
+ * **No framework is imported here, and none is assumed.** The request, response and router are described by the
+ * handful of properties these functions touch (see `AuthedRequest`, `JsonResponse`, `RouterLike`), so an Express,
+ * Connect or Koa object satisfies them as it stands, and a bare `node:http` server satisfies them with a few lines
+ * of its own. Tying this package to one framework would be the wrong trade — but so is leaving every deployment to
+ * rediscover the same twenty lines, one of which has a real trap in it (`hostname` and spreads, see below).
+ *
+ * A deployment with a router:
+ *
+ * ```ts
+ * import { createAuthMiddleware, mountAuthRoutes } from '@plitzi/sdk-server/handlers';
+ *
+ * app.use(createAuthMiddleware(auth.identity, policy));
+ *
+ * const router = Router();
+ * mountAuthRoutes(router, { api: auth.api, cookies: auth.cookies });
+ * app.use('/auth', router);
+ * ```
+ *
+ * A deployment without one — `createAuthRouteHandlers` is a list, and dispatching it is yours:
+ *
+ * ```ts
+ * import { createAuthRouteHandlers } from '@plitzi/sdk-server/handlers';
+ *
+ * const routes = createAuthRouteHandlers({ api: auth.api, cookies: auth.cookies });
+ *
+ * http.createServer(async (raw, rawRes) => {
+ *   const req = parseRequest(raw);              // from @plitzi/sdk-server/kernel
+ *   const route = routes.find(r => r.method === req.method && `/auth${r.path}` === req.path);
+ *   if (route) {
+ *     await route.handle(req, jsonResponse(rawRes));
+ *   }
+ * });
+ * ```
+ *
+ * Everything a deployment must decide — its accounts, its policy, its cookie naming — stays `createAuth`'s. What is
+ * here is only what is the same for everyone.
+ *
+ * `req.user` and `req.grant` are what the guard resolved. To have those typed across your own routers, declare them
+ * once in your app rather than expecting them from here — a library augmenting its consumer's globals only merges
+ * when both resolve the identical copy of the framework's types, and two installs do not:
+ *
+ * ```ts
+ * declare module 'express-serve-static-core' {
+ *   interface Request {
+ *     user?: Actor;
+ *     grant?: Grant;
+ *   }
+ * }
+ * ```
+ */
+export { createAuthRouteHandlers, mountAuthRoutes } from './core/handlers/authRouteHandlers';
+export { createAuthMiddleware } from './core/handlers/authMiddleware';
+export type { AuthRouteHandlersOptions } from './core/handlers/authRouteHandlers';
+export type { AuthMiddlewareOptions } from './core/handlers/authMiddleware';
+export type { AuthedRequest, JsonResponse, HttpRoute, RouteHandler, RouterLike } from './core/handlers/types';

package/dist/handlers.js

@@ -0,0 +1,3 @@
+import { createAuthRouteHandlers, mountAuthRoutes } from "./core/handlers/authRouteHandlers.js";
+import { createAuthMiddleware } from "./core/handlers/authMiddleware.js";
+export { createAuthMiddleware, createAuthRouteHandlers, mountAuthRoutes };

package/dist/{src/helpers → helpers}/buildResponseHelpers.d.ts

@@ -1,3 +1,4 @@
+import { ResolvedCompression } from './compress';
 import { SSRResponseHelpers } from '@plitzi/sdk-shared';
 export type RawResponse = {
     headersSent: boolean;
@@ -9,4 +10,4 @@ export type RawResponse = {
     write(chunk: string | Buffer): unknown;
     end(chunk?: string | Buffer): unknown;
 };
-export declare const buildResponseHelpers: (raw: RawResponse, acceptEncoding?: string) => SSRResponseHelpers;
+export declare const buildResponseHelpers: (raw: RawResponse, acceptEncoding?: string, compression?: ResolvedCompression) => SSRResponseHelpers;

package/dist/helpers/buildResponseHelpers.js

@@ -1,10 +1,19 @@
-import { compressBody, selectEncoding } from "./compress.js";
+import { DEFAULT_COMPRESSION, compressBody, selectEncoding } from "./compress.js";
 //#region src/helpers/buildResponseHelpers.ts
-var buildResponseHelpers = (raw, acceptEncoding) => {
+var buildResponseHelpers = (raw, acceptEncoding, compression = DEFAULT_COMPRESSION) => {
 	let statusCode = 200;
-	const encoding = selectEncoding(acceptEncoding);
+	const encoding = selectEncoding(acceptEncoding, compression);
+	/**
+	* `Cache-Control: no-transform` means what it says, and this server is one of the parties it addresses.
+	*
+	* A stage sets it on a response whose body must reach the client byte for byte — the OAuth token endpoint above
+	* all, where a credential travels beside a value the caller chose (the `scope` it echoes back). Compressing the
+	* two together is the shape a BREACH-style attack needs, and the stage that knows this is the one that has
+	* already said so in a header.
+	*/
+	const transformable = () => !String(raw.getHeaders()["cache-control"]).includes("no-transform");
 	const writeSend = (body) => {
-		const compressed = compressBody(body, encoding);
+		const compressed = transformable() ? compressBody(body, encoding, compression) : body;
 		if (compressed !== body) {
 			raw.setHeader("Content-Encoding", encoding);
 			raw.setHeader("Vary", "Accept-Encoding");

package/dist/helpers/buildServerInfo.d.ts

@@ -0,0 +1,3 @@
+import { OfflineDataLoader } from './offlineDataLoader';
+import { Server, SSRRequest, SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const buildServerInfo: (req: SSRRequest, config: SSRServerConfig, loadOfflineData: OfflineDataLoader) => Promise<Partial<Server>>;

package/dist/helpers/buildServerInfo.js

@@ -1,3 +1,4 @@
+import { resolveRscEndpoint } from "../core/services/resolve.js";
 //#region src/helpers/buildServerInfo.ts
 var getEnvironment = (env = "production", server) => {
 	switch (env) {
@@ -28,7 +29,7 @@ var getEnvironment = (env = "production", server) => {
 		};
 	}
 };
-var buildServerInfo = async (req, config) => {
+var buildServerInfo = async (req, config, loadOfflineData) => {
 	const accessToken = req.query["access-token"];
 	const origin = `${req.protocol}://${req.hostname}`;
 	const user = req.ctx.user;
@@ -44,8 +45,29 @@ var buildServerInfo = async (req, config) => {
 		},
 		authenticated: !!user,
 		skipAuth: !!accessToken,
-		user: user ? { details: user } : void 0,
-		rscData: await config.adapters.getRscData?.(req, spaceId, environment, revision, user)
+		user: user ? {
+			details: {
+				id: user.id,
+				username: user.username,
+				email: user.email,
+				verified: user.verified,
+				permissions: user.permissions,
+				roles: user.roles
+			},
+			accessToken: user.token,
+			expiresAt: user.expiresAt
+		} : void 0,
+		ssr: {
+			rscPath: resolveRscEndpoint(config),
+			rscData: await config.adapters.getRscData?.({
+				req,
+				spaceId,
+				environment,
+				revision,
+				user,
+				loadOfflineData
+			})
+		}
 	});
 };
 //#endregion

package/dist/{src/helpers → helpers}/cache/keys.d.ts

@@ -4,4 +4,8 @@ export declare const buildHtmlCacheKey: (accessToken: string | undefined, spaceI
     search: string;
 }) => string;
 export declare const buildOfflineDataCacheKey: (spaceId: number, environment: string, revision: number) => string;
-export declare const buildRscCacheKey: (spaceId: number, environment: string, revision: number, userId: string | number | undefined, idsParam: string | undefined) => string;
+export declare const buildRscCacheKey: (spaceId: number, environment: string, revision: number, userId: string | number | undefined, idsParam: string | undefined, req: {
+    hostname: string;
+    path: string;
+    search: string;
+}) => string;

package/dist/helpers/cache/keys.js

@@ -1,6 +1,6 @@
 //#region src/helpers/cache/keys.ts
 var buildHtmlCacheKey = (accessToken = "anonymous", spaceId, environment, revision, req) => `${accessToken}\0${spaceId ?? 1}\0${environment}\0${revision}\0${req.hostname}\0${req.path}\0${req.search}`;
 var buildOfflineDataCacheKey = (spaceId, environment, revision) => `${spaceId}|${environment}|${revision}`;
-var buildRscCacheKey = (spaceId, environment, revision, userId, idsParam) => `${spaceId}|${environment}|${revision}|${userId ?? "anon"}|${idsParam ?? ""}`;
+var buildRscCacheKey = (spaceId, environment, revision, userId, idsParam, req) => `${spaceId}\0${environment}\0${revision}\0${userId ?? "anon"}\0${idsParam ?? ""}\0${req.hostname}\0${req.path}\0${req.search}`;
 //#endregion
 export { buildHtmlCacheKey, buildOfflineDataCacheKey, buildRscCacheKey };

package/dist/helpers/compress.d.ts

@@ -0,0 +1,18 @@
+import { SSRCompressionConfig } from '@plitzi/sdk-shared';
+export type ContentEncoding = 'br' | 'gzip' | 'identity';
+/** What the server does when the deployment says nothing: Brotli where the client takes it, gzip otherwise. */
+export declare const DEFAULT_COMPRESSION: {
+    encodings: ("br" | "gzip")[];
+    threshold: number;
+    brotliQuality: number;
+    gzipLevel: number;
+};
+export type ResolvedCompression = typeof DEFAULT_COMPRESSION;
+/**
+ * The deployment's compression policy, with the gaps filled in. `false` means never compress, and is expressed as
+ * an empty encoding list so there is one shape downstream rather than a boolean to re-test at every use.
+ */
+export declare const resolveCompression: (config?: SSRCompressionConfig | false) => ResolvedCompression;
+/** The first encoding this server prefers that the client actually takes. `*` counts as taking anything. */
+export declare const selectEncoding: (acceptEncoding: string | undefined, compression?: ResolvedCompression) => ContentEncoding;
+export declare const compressBody: (body: string, encoding: ContentEncoding, compression?: ResolvedCompression) => Buffer | string;