@plitzi/sdk-server 0.33.1 → 0.34.0

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

@@ -0,0 +1,20 @@
+import { AuthedRequest, JsonResponse } from './types';
+import { Csrf } from '../auth/csrf';
+import { SessionCookies } from '../auth/session';
+export interface CsrfMiddlewareOptions {
+    /** Paths this deployment answers that must not be asked for a token — a payment gateway's webhook, say. */
+    exempt?: (path: string) => boolean;
+    /** `message` on some APIs, `error` on others. Matches whatever the rest of the deployment answers with. */
+    errorKey?: 'message' | 'error';
+}
+/**
+ * The CSRF check as middleware, for a deployment with a router.
+ *
+ * No framework is imported and none is assumed: it reads the handful of properties `AuthedRequest` describes, so
+ * an Express, Connect or Koa request satisfies it unchanged. Mount it after whatever parses bodies and cookies —
+ * a token posted in a form field cannot be read before the body is.
+ *
+ * A webhook is the case worth thinking about: it is a cross-site POST by design, it authenticates with a signature
+ * rather than a cookie, and it will never carry a token. Exempt it by path.
+ */
+export declare const createCsrfMiddleware: (csrf: Csrf, cookies: SessionCookies, { exempt, errorKey }?: CsrfMiddlewareOptions) => (req: AuthedRequest, res: JsonResponse, next: () => void) => void;

package/dist/core/handlers/csrfMiddleware.js

@@ -0,0 +1,32 @@
+import { csrfFailureMessage } from "../auth/csrf.js";
+//#region src/core/handlers/csrfMiddleware.ts
+/**
+* The CSRF check as middleware, for a deployment with a router.
+*
+* No framework is imported and none is assumed: it reads the handful of properties `AuthedRequest` describes, so
+* an Express, Connect or Koa request satisfies it unchanged. Mount it after whatever parses bodies and cookies —
+* a token posted in a form field cannot be read before the body is.
+*
+* A webhook is the case worth thinking about: it is a cross-site POST by design, it authenticates with a signature
+* rather than a cookie, and it will never carry a token. Exempt it by path.
+*/
+var createCsrfMiddleware = (csrf, cookies, { exempt, errorKey = "message" } = {}) => (req, res, next) => {
+	if (exempt?.(req.path) || !csrf.required({
+		...req,
+		method: req.method
+	})) {
+		next();
+		return;
+	}
+	const result = csrf.verify(req, cookies.resolveSessionToken(req));
+	if (result.ok) {
+		next();
+		return;
+	}
+	res.status(403).json({
+		[errorKey]: csrfFailureMessage[result.reason],
+		reason: result.reason
+	});
+};
+//#endregion
+export { createCsrfMiddleware };

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

@@ -0,0 +1,46 @@
+import { AuthedRequest, HttpRoute, RouterLike } from './types';
+import { OAuthConfig } from '@plitzi/sdk-shared';
+/**
+ * A response that can send bytes, which OAuth needs and `JsonResponse` does not offer.
+ *
+ * The grant screen is HTML and the code hand-off is a 302, so this asks for the two things a JSON-only response
+ * cannot do. Express satisfies it as it stands; anything else needs a `send`, a `setHeader` and a status.
+ */
+export interface OAuthResponse {
+    status: (code: number) => OAuthResponse;
+    setHeader: (name: string, value: string | string[]) => unknown;
+    send: (body: string) => unknown;
+    end: () => unknown;
+}
+export type OAuthRouteHandler = (req: AuthedRequest, res: OAuthResponse) => Promise<void>;
+export interface OAuthRouteHandlersOptions {
+    config: OAuthConfig;
+    onError?: (error: unknown, route: {
+        method: string;
+        path: string;
+    }) => void;
+}
+/**
+ * OAuth 2.1 authorization as ordinary routes, for a host that runs a router rather than the render pipeline.
+ *
+ * The same handlers the pipeline stage calls — this is the mounting, not a second implementation. A deployment
+ * whose API is an Express app mounts these; one whose MCP server is the SDK's own pipeline mounts the stage. Both
+ * grant the credential `config.adapters.issueToken` mints, and THAT is what distinguishes one mounting from
+ * another: a space-scoped agent token for a connector, a user session for a native client.
+ *
+ * `paths` are relative, so the host decides where the set answers. The discovery documents must be reachable at
+ * the well-known paths off the ORIGIN root, so a host that mounts this under a prefix serves those two itself.
+ */
+export declare const createOAuthRouteHandlers: ({ config, onError }: OAuthRouteHandlersOptions) => HttpRoute<OAuthRouteHandler>[];
+/**
+ * Where the set answers, relative to wherever it is mounted.
+ *
+ * Exported so a host's auth policy can DERIVE which paths are public rather than restating them: every one of
+ * these is reached without a session by definition — `/authorize` is what a signed-out person opens, `/token` is
+ * authenticated by PKCE, and the discovery documents are what a client reads before it has anything at all. A
+ * restated list is one that drifts, and drifting the wrong way here means an authorization server nobody can
+ * start a flow against.
+ */
+export declare const OAUTH_ROUTE_PATHS: string[];
+/** {@link createOAuthRouteHandlers}, hung on anything with `get` and `post`. */
+export declare const mountOAuthRoutes: (router: RouterLike<OAuthRouteHandler>, options: OAuthRouteHandlersOptions) => void;

package/dist/core/handlers/oauthRouteHandlers.js

@@ -0,0 +1,159 @@
+import { authorizationServerMetadata, protectedResourceMetadata } from "../oauth/metadata.js";
+import { sendErrorJson } from "../oauth/respond.js";
+import { handleAuthorizeStart, handleAuthorizeSubmit } from "../oauth/authorize.js";
+import { handleRegister } from "../oauth/register.js";
+import { handleRevoke, handleToken } from "../oauth/token.js";
+//#region src/core/handlers/oauthRouteHandlers.ts
+/**
+* The host's response, described the way the protocol handlers expect it.
+*
+* They were written against the render pipeline's helpers, which is a different shape from a router's response
+* and deliberately so: one collects a status and headers to be applied later, the other writes as it goes. This
+* is the whole of the difference, in one place, so neither side learns about the other.
+*/
+var asHelpers = (res) => {
+	const helpers = {
+		status: 200,
+		headers: {},
+		setHeader: (name, value) => {
+			helpers.headers[name] = value;
+			res.setHeader(name, value);
+		},
+		setStatus: (code) => {
+			helpers.status = code;
+			res.status(code);
+		},
+		send: (body) => {
+			res.send(typeof body === "string" ? body : body.toString("utf8"));
+		},
+		write: (chunk) => {
+			res.send(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+		},
+		end: () => {
+			res.end();
+		}
+	};
+	return helpers;
+};
+/**
+* The request, as the protocol reads it.
+*
+* `protocol` earns its place: the issuer published in the discovery documents is built from it, and a request
+* that omits it publishes `undefined://api.example.com` — a document every client rejects. Behind a proxy the
+* forwarded header is the only thing that knows, since the hop to this process is plain HTTP.
+*/
+var asRequest = (req) => {
+	const forwarded = req.headers["x-forwarded-proto"];
+	const protocol = (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(",")[0] ?? req.protocol ?? "https";
+	return {
+		method: req.method ?? "GET",
+		path: req.path,
+		headers: req.headers,
+		hostname: req.hostname,
+		protocol: protocol === "http" ? "http" : "https",
+		query: req.query ?? {}
+	};
+};
+/** Query first, body second: a field posted by the grant form wins over one the client left in the URL. */
+var params = (req) => ({
+	...req.query ?? {},
+	...req.body ?? {}
+});
+/**
+* OAuth 2.1 authorization as ordinary routes, for a host that runs a router rather than the render pipeline.
+*
+* The same handlers the pipeline stage calls — this is the mounting, not a second implementation. A deployment
+* whose API is an Express app mounts these; one whose MCP server is the SDK's own pipeline mounts the stage. Both
+* grant the credential `config.adapters.issueToken` mints, and THAT is what distinguishes one mounting from
+* another: a space-scoped agent token for a connector, a user session for a native client.
+*
+* `paths` are relative, so the host decides where the set answers. The discovery documents must be reachable at
+* the well-known paths off the ORIGIN root, so a host that mounts this under a prefix serves those two itself.
+*/
+var createOAuthRouteHandlers = ({ config, onError }) => {
+	const guarded = (method, path, run) => async (req, res) => {
+		try {
+			await run(req, res);
+		} catch (error) {
+			if (onError) onError(error, {
+				method,
+				path
+			});
+			else console.error(`[oauth] ${method} ${path} failed:`, error);
+			sendErrorJson(asHelpers(res), 500, "server_error", "The authorization server failed to answer.");
+		}
+	};
+	return [
+		{
+			method: "GET",
+			path: "/authorize",
+			handle: guarded("GET", "/authorize", async (req, res) => handleAuthorizeStart(config, asHelpers(res), params(req), asRequest(req)))
+		},
+		{
+			method: "POST",
+			path: "/authorize",
+			handle: guarded("POST", "/authorize", async (req, res) => handleAuthorizeSubmit(config, asHelpers(res), params(req), asRequest(req)))
+		},
+		{
+			method: "POST",
+			path: "/token",
+			handle: guarded("POST", "/token", async (req, res) => handleToken(config, asHelpers(res), params(req)))
+		},
+		{
+			method: "POST",
+			path: "/revoke",
+			handle: guarded("POST", "/revoke", async (req, res) => handleRevoke(config, asHelpers(res), params(req)))
+		},
+		{
+			method: "POST",
+			path: "/register",
+			handle: guarded("POST", "/register", async (req, res) => handleRegister(config, asHelpers(res), req.body))
+		},
+		{
+			method: "GET",
+			path: "/.well-known/oauth-authorization-server",
+			handle: guarded("GET", "/.well-known/oauth-authorization-server", (req, res) => {
+				const helpers = asHelpers(res);
+				helpers.setHeader("Content-Type", "application/json");
+				helpers.setStatus(200);
+				helpers.send(JSON.stringify(authorizationServerMetadata(config, asRequest(req))));
+				return Promise.resolve();
+			})
+		},
+		{
+			method: "GET",
+			path: "/.well-known/oauth-protected-resource",
+			handle: guarded("GET", "/.well-known/oauth-protected-resource", (req, res) => {
+				const helpers = asHelpers(res);
+				helpers.setHeader("Content-Type", "application/json");
+				helpers.setStatus(200);
+				helpers.send(JSON.stringify(protectedResourceMetadata(config, asRequest(req))));
+				return Promise.resolve();
+			})
+		}
+	];
+};
+/**
+* Where the set answers, relative to wherever it is mounted.
+*
+* Exported so a host's auth policy can DERIVE which paths are public rather than restating them: every one of
+* these is reached without a session by definition — `/authorize` is what a signed-out person opens, `/token` is
+* authenticated by PKCE, and the discovery documents are what a client reads before it has anything at all. A
+* restated list is one that drifts, and drifting the wrong way here means an authorization server nobody can
+* start a flow against.
+*/
+var OAUTH_ROUTE_PATHS = [
+	"/authorize",
+	"/token",
+	"/revoke",
+	"/register",
+	"/.well-known/oauth-authorization-server",
+	"/.well-known/oauth-protected-resource"
+];
+/** {@link createOAuthRouteHandlers}, hung on anything with `get` and `post`. */
+var mountOAuthRoutes = (router, options) => {
+	for (const { method, path, handle } of createOAuthRouteHandlers(options)) if (method === "GET") router.get(path, handle);
+	else router.post(path, handle);
+};
+//#endregion
+export { OAUTH_ROUTE_PATHS, createOAuthRouteHandlers, mountOAuthRoutes };

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

@@ -0,0 +1,40 @@
+import { HttpRoute, RouterLike, SocialRouteHandler } from './types';
+import { SocialAuth } from '../auth/oauth';
+import { SessionCookies } from '../auth/session';
+import { SSRSession } from '@plitzi/sdk-shared';
+export interface SocialRouteHandlersOptions {
+    /** A `createSocialAuth(...)` result — the providers this deployment has credentials for. */
+    social: SocialAuth;
+    /** Writes the session at the end of a successful callback, and holds the flow state between the two legs. */
+    cookies: SessionCookies;
+    /**
+     * Mints the session for the account that just signed in. `auth.api.issueSession` is the one to pass: the flow
+     * proves WHO, and what a session is worth is the kernel's answer, not the provider's.
+     */
+    issueSession: (userId: number) => Promise<SSRSession>;
+    /** Reports a callback that threw. Without it the failure goes to `console.error`; the caller still gets a 500. */
+    onError?: (error: unknown, context: {
+        method: string;
+        path: string;
+    }) => void;
+}
+/**
+ * Social sign-in as request handlers: the provider listing, and the two legs of the authorization-code flow.
+ *
+ * The counterpart to {@link createAuthRouteHandlers}, and it exists for the same reason. `createSocialAuth` already
+ * answers the whole flow — where to send the browser, what state to hold, whether the caller came back with anything
+ * worth a session — and every deployment then wrote the identical fifty lines that turn those answers into
+ * redirects: set the flow cookie, clear it on the way back, decide that a failure with no vetted target has nowhere
+ * to report to, write the session cookies before the final redirect. None of that is a deployment's own policy, and
+ * two of the steps are the kind that look right while being wrong (clearing the flow cookie only on success leaves a
+ * stale nonce; redirecting to an unvetted target is an open redirect).
+ *
+ * What stays the deployment's is what it already was: which providers it has credentials for, and what
+ * `linkAccount` does with the person who comes back.
+ *
+ * A list, so nothing has to be a router — {@link mountSocialAuthRoutes} is the loop that hangs it on one. Mount it
+ * on the same base as the `/auth` flows: the paths are `/providers` and `/<provider>/{login,callback}`.
+ */
+export declare const createSocialAuthRouteHandlers: ({ social, cookies, issueSession, onError }: SocialRouteHandlersOptions) => HttpRoute<SocialRouteHandler>[];
+/** {@link createSocialAuthRouteHandlers}, hung on a router. Mount it wherever the `/auth` flows are mounted. */
+export declare const mountSocialAuthRoutes: (router: RouterLike<SocialRouteHandler>, options: SocialRouteHandlersOptions) => void;

package/dist/core/handlers/socialRouteHandlers.js

@@ -0,0 +1,129 @@
+//#region src/core/handlers/socialRouteHandlers.ts
+/**
+* A provider id from the request.
+*
+* `params` when the host filled it in (Express does, from the `:provider` segment) and the path otherwise, so a
+* framework that does not populate params — or a bare `node:http` dispatch — needs nothing extra. The path form
+* reads the segment before the trailing action, which is where both routes carry it.
+*/
+var providerOf = (req) => {
+	const fromParams = req.params?.provider;
+	if (fromParams) return fromParams;
+	const segments = req.path.split("/").filter(Boolean);
+	return segments.length >= 2 ? segments[segments.length - 2] : "";
+};
+/**
+* Social sign-in as request handlers: the provider listing, and the two legs of the authorization-code flow.
+*
+* The counterpart to {@link createAuthRouteHandlers}, and it exists for the same reason. `createSocialAuth` already
+* answers the whole flow — where to send the browser, what state to hold, whether the caller came back with anything
+* worth a session — and every deployment then wrote the identical fifty lines that turn those answers into
+* redirects: set the flow cookie, clear it on the way back, decide that a failure with no vetted target has nowhere
+* to report to, write the session cookies before the final redirect. None of that is a deployment's own policy, and
+* two of the steps are the kind that look right while being wrong (clearing the flow cookie only on success leaves a
+* stale nonce; redirecting to an unvetted target is an open redirect).
+*
+* What stays the deployment's is what it already was: which providers it has credentials for, and what
+* `linkAccount` does with the person who comes back.
+*
+* A list, so nothing has to be a router — {@link mountSocialAuthRoutes} is the loop that hangs it on one. Mount it
+* on the same base as the `/auth` flows: the paths are `/providers` and `/<provider>/{login,callback}`.
+*/
+var createSocialAuthRouteHandlers = ({ social, cookies, issueSession, onError }) => {
+	const report = (error, context) => {
+		if (onError) {
+			onError(error, context);
+			return;
+		}
+		console.error(`[auth] ${context.method} ${context.path} failed:`, error);
+	};
+	return [
+		{
+			method: "GET",
+			path: "/providers",
+			handle: (_req, res) => {
+				res.status(200).json({ providers: social.list() });
+				return Promise.resolve();
+			}
+		},
+		{
+			/**
+			* Where a sign-in screen sends somebody once they have a session.
+			*
+			* It exists because the screen cannot make this decision itself. The destination arrives as `?redirect=` on a
+			* link the visitor followed, so it is attacker-supplied — and a shared sign-in page that navigates to it
+			* unchecked is an open redirect on the one origin every person on the platform is trained to type a password
+			* into. The page is also a rendered space, with no way to ask whether an origin is ours.
+			*
+			* So the page ends its flow HERE and this hop decides, with the same `sanitizeRedirect` the social callback
+			* uses: a relative path or an allowed origin is honoured, anything else silently becomes the default. A
+			* missing or unresolved parameter lands on the default too, which is what makes it safe for a template to
+			* pass a token it could not fill in.
+			*/
+			method: "GET",
+			path: "/continue",
+			handle: (req, res) => {
+				res.redirect(social.sanitizeRedirect(req.query?.redirect));
+				return Promise.resolve();
+			}
+		},
+		{
+			method: "GET",
+			path: "/:provider/login",
+			handle: (req, res) => {
+				const started = social.start(providerOf(req), req.query?.redirect);
+				if (!started) {
+					res.status(404).json({ error: "Unknown provider" });
+					return Promise.resolve();
+				}
+				cookies.writeFlow(req, res, started.stateCookie, started.ttl);
+				res.redirect(started.redirectTo);
+				return Promise.resolve();
+			}
+		},
+		{
+			method: "GET",
+			path: "/:provider/callback",
+			handle: async (req, res) => {
+				const providerId = providerOf(req);
+				try {
+					const { code, state, error } = req.query ?? {};
+					const stateCookie = cookies.readFlow(req);
+					cookies.clearFlow(req, res);
+					const result = await social.complete(providerId, {
+						code,
+						state,
+						error,
+						stateCookie
+					});
+					if (!result.ok) {
+						if (!result.redirectTo) {
+							res.status(400).json({ error: result.error });
+							return;
+						}
+						if (result.reason === "server_error") report(new Error(result.error), {
+							method: "GET",
+							path: `/${providerId}/callback`
+						});
+						res.redirect(result.redirectTo);
+						return;
+					}
+					cookies.write(req, res, await issueSession(result.account.id));
+					res.redirect(result.redirectTo);
+				} catch (error) {
+					report(error, {
+						method: "GET",
+						path: `/${providerId}/callback`
+					});
+					res.status(500).json({ error: "Internal server error" });
+				}
+			}
+		}
+	];
+};
+/** {@link createSocialAuthRouteHandlers}, hung on a router. Mount it wherever the `/auth` flows are mounted. */
+var mountSocialAuthRoutes = (router, options) => {
+	for (const route of createSocialAuthRouteHandlers(options)) router.get(route.path, route.handle);
+};
+//#endregion
+export { createSocialAuthRouteHandlers, mountSocialAuthRoutes };

package/dist/core/handlers/socialRouteHandlers.test.d.ts

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

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

@@ -11,6 +11,13 @@ import { CookieSink } from '../auth/session';
 export interface AuthedRequest extends CredentialCarrier {
     /** The path alone, without the query string — what the policy matches on. */
     path: string;
+    /** Path parameters, when the host router fills them in. Only the social flows read one, and they fall back to
+     *  the path when it is absent, so a framework that does not populate this needs nothing extra. */
+    params?: Record<string, string | undefined>;
+    /** Read by the CSRF check, which asks nothing of a safe method. Absent is treated as `GET`. */
+    method?: string;
+    /** `http` or `https`, when the host router knows. The OAuth flows publish an issuer built from it. */
+    protocol?: string;
     /** The parsed body, when there is one. The flows read fields off it; how it got parsed is the host's business. */
     body?: unknown;
     /** The account this request proved, once the auth middleware has run. */
@@ -23,15 +30,25 @@ export interface JsonResponse extends CookieSink {
     json: (body: unknown) => unknown;
 }
 export type RouteHandler = (req: AuthedRequest, res: JsonResponse) => Promise<void>;
+/**
+ * A response that can also send the browser somewhere.
+ *
+ * Only the social flows need it: an authorization-code grant ends in a redirect, not a body. Express satisfies it
+ * as it stands; a bare `node:http` response needs three lines (302 plus a `Location` header).
+ */
+export interface RedirectResponse extends JsonResponse {
+    redirect: (url: string) => unknown;
+}
+export type SocialRouteHandler = (req: AuthedRequest, res: RedirectResponse) => Promise<void>;
 /** One flow, ready to serve: where it answers, and what to call when it does. */
-export interface HttpRoute {
+export interface HttpRoute<H = RouteHandler> {
     method: 'GET' | 'POST';
     /** Relative to wherever the host mounts the set — `/auth`, conventionally. */
     path: string;
-    handle: RouteHandler;
+    handle: H;
 }
 /** Anything routes can be hung on: a router, an app, or a stand-in in a test — `get` and `post`, nothing else. */
-export interface RouterLike {
-    get: (path: string, handler: RouteHandler) => unknown;
-    post: (path: string, handler: RouteHandler) => unknown;
+export interface RouterLike<H = RouteHandler> {
+    get: (path: string, handler: H) => unknown;
+    post: (path: string, handler: H) => unknown;
 }

package/dist/core/health.d.ts

@@ -7,4 +7,14 @@ export interface HealthIdentity {
     version?: string;
 }
 export declare const buildHealthPayload: (identity?: Partial<HealthIdentity>) => Record<string, unknown>;
-export declare const registerHealthCheck: (app: HealthCheckApp, identity: HealthIdentity) => void;
+/**
+ * Attach the generic /health endpoint to an Express-style app — a deployment whose roles are not all on the sdk-server
+ * http pipeline. Servers built on the pipeline get the same endpoint from `healthStage`.
+ *
+ * `check` is what makes it a readiness probe rather than a liveness one, and it is here for the same reason it is on
+ * `healthStage`: a role reports the stores it depends on, and `healthy: false` answers 503 so an orchestrator stops
+ * routing to a replica that can serve nothing. Without it the two halves of one deployment answered different
+ * questions at the same path — and the Express half's real check ended up as a second, password-guarded endpoint the
+ * probes were never pointed at.
+ */
+export declare const registerHealthCheck: (app: HealthCheckApp, identity: HealthIdentity, check?: () => Record<string, unknown> | Promise<Record<string, unknown>>) => void;

package/dist/core/health.js

@@ -4,11 +4,35 @@ var buildHealthPayload = (identity = {}) => ({
 	Version: identity.version ? `v${identity.version}` : "unknown",
 	role: identity.role
 });
-var registerHealthCheck = (app, identity) => {
+/**
+* Attach the generic /health endpoint to an Express-style app — a deployment whose roles are not all on the sdk-server
+* http pipeline. Servers built on the pipeline get the same endpoint from `healthStage`.
+*
+* `check` is what makes it a readiness probe rather than a liveness one, and it is here for the same reason it is on
+* `healthStage`: a role reports the stores it depends on, and `healthy: false` answers 503 so an orchestrator stops
+* routing to a replica that can serve nothing. Without it the two halves of one deployment answered different
+* questions at the same path — and the Express half's real check ended up as a second, password-guarded endpoint the
+* probes were never pointed at.
+*/
+var registerHealthCheck = (app, identity, check) => {
 	const payload = buildHealthPayload(identity);
 	app.get("/health", (_req, res) => {
-		res.writeHead(200, { "Content-Type": "application/json" });
-		res.end(JSON.stringify(payload));
+		(async () => {
+			let live = {};
+			if (check) try {
+				live = await check();
+			} catch (error) {
+				live = {
+					healthy: false,
+					reason: error instanceof Error ? error.message : String(error)
+				};
+			}
+			res.writeHead(live.healthy === false ? 503 : 200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				...payload,
+				...live
+			}));
+		})();
 	});
 };
 //#endregion

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

@@ -3,5 +3,5 @@ import { RawResponse } from '../../helpers/buildResponseHelpers';
 import { Handler } from '../transports';
 import { SSRRequest, SSRResponseHelpers, SSRServerConfig } from '@plitzi/sdk-shared';
 import { IncomingMessage } from 'node:http';
-export type BuildContext<C extends BaseContext> = (raw: IncomingMessage, rawRes: RawResponse, req: SSRRequest, res: SSRResponseHelpers) => C;
+export type BuildContext<C extends BaseContext> = (raw: IncomingMessage, rawRes: RawResponse, req: SSRRequest, res: SSRResponseHelpers) => Omit<C, 'signal'>;
 export declare const makeHandler: <C extends BaseContext>(label: string, buildContext: BuildContext<C>, stages: Stage<C>[], compressionConfig?: SSRServerConfig["compression"]) => Handler;

package/dist/core/http/dispatcher.js

@@ -15,7 +15,26 @@ var runPipeline = async (raw, rawRes, buildContext, stages, server, compression)
 	const startedAt = Date.now();
 	const req = parseRequest(raw);
 	const res = buildResponseHelpers(rawRes, req.headers["accept-encoding"], compression);
-	const ctx = buildContext(raw, rawRes, req, res);
+	/**
+	* One controller per request, aborted when the PEER goes away.
+	*
+	* Watched on the RESPONSE, not on the request: `IncomingMessage` emits `close` as soon as its body has been
+	* read, so a POST aborted itself the millisecond the server finished parsing it — measurably, at 9ms of a
+	* 300ms request. Everything downstream either ignored that (a listener attached after the event never fires,
+	* which is what kept actions working at all) or acted on it and cancelled work nobody had abandoned.
+	*
+	* `writableFinished` is what tells the two apart: a response that closed after finishing was SERVED, and one
+	* that closed before is a caller who left. `once` so a request that ends normally leaves no listener on a
+	* socket the runtime may keep alive for the next one.
+	*/
+	const controller = new AbortController();
+	rawRes.once?.("close", () => {
+		if (!rawRes.writableFinished) controller.abort();
+	});
+	const ctx = {
+		...buildContext(raw, rawRes, req, res),
+		signal: controller.signal
+	};
 	const logger = ctx.config.logger;
 	const ip = logger ? clientIp(raw, req) : "";
 	const logRequest = (error) => {

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

@@ -49,7 +49,7 @@ var createAuthApiStage = (auth, basePath = auth.basePath) => {
 			actor: decision.actor
 		};
 		const outcome = await route.handler(authRequest);
-		auth.applySession(req, res, outcome, auth.cookies);
+		auth.applySession(req, res, outcome);
 		if (isNavigation(req)) {
 			res.setStatus(303);
 			res.setHeader("Location", outcome.ok ? safeRedirectTarget(req) : req.path);

package/dist/core/http/stages/fontAssets.d.ts

@@ -0,0 +1,9 @@
+import { Stage } from '../types';
+/**
+ * The font files this deployment stores, when it stores them itself.
+ *
+ * Off unless `fonts.dir` is configured, because a cloud deployment serves them from a CDN and would otherwise
+ * shadow that path with a directory it does not have. Served CORS-open on purpose: a font is fetched in CORS mode
+ * whatever its origin, so without this a page on the space's own domain cannot use a face from this server.
+ */
+export declare const fontAssetsStage: Stage;

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

@@ -0,0 +1,27 @@
+import { serveStatic } from "../../staticFiles.js";
+//#region src/core/http/stages/fontAssets.ts
+/** Where a manifest's `hosted` paths are addressed from by default — see `fontUrlResolver`. */
+var FONTS_PREFIX = "/fonts";
+/**
+* The font files this deployment stores, when it stores them itself.
+*
+* Off unless `fonts.dir` is configured, because a cloud deployment serves them from a CDN and would otherwise
+* shadow that path with a directory it does not have. Served CORS-open on purpose: a font is fetched in CORS mode
+* whatever its origin, so without this a page on the space's own domain cannot use a face from this server.
+*/
+var fontAssetsStage = (ctx) => {
+	const dir = ctx.config.fonts?.dir;
+	if (!dir || !ctx.req.path.startsWith(`${FONTS_PREFIX}/`)) 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(6) || "/"
+	};
+	if (serveStatic(strippedReq, ctx.res, dir)) return true;
+	ctx.res.setStatus(404);
+	ctx.res.send("Not found");
+	return true;
+};
+//#endregion
+export { fontAssetsStage };

package/dist/core/http/stages/oauth.d.ts

@@ -0,0 +1,19 @@
+import { Stage } from '../types';
+import { OAuthConfig } from '@plitzi/sdk-shared';
+/** OAuth 2.1 authorization for the MCP server, mounted ONLY when a deployment configures `oauth`. Without it the
+ *  stage falls straight through and the server keeps its anonymous contract: discovery 404s, the public surface
+ *  (handshake, listings, the guide, plitzi_render) answers without a token, and nothing below changes.
+ *
+ *  It sits before the MCP stage because that one answers every path on a dedicated MCP server — these endpoints
+ *  would otherwise be swallowed by the JSON-RPC transport, which is exactly the 406 a host hits on /register. */
+export declare const createOAuthStage: (oauth?: OAuthConfig) => Stage;
+/** The protected-resource half of OAuth: an MCP call that presents no bearer this server can verify is refused
+ *  with RFC 6750's challenge instead of being served the anonymous surface. That 401 is the whole handshake — it
+ *  is how a host learns the server needs authorization, where its metadata lives and which scopes to ask for, and
+ *  a 200 tells it none of that. Only the JSON-RPC POST is guarded: the CORS preflight, the GET 405 and the
+ *  discovery probes carry no credential and must keep answering as they do.
+ *
+ *  Mounted only when `oauth` is configured. A deployment that configures none keeps the open server it had, where
+ *  the whole public surface — handshake, listings, the guide, plitzi_render — answers without a token; with OAuth
+ *  on, the grant that carries no space is what covers that same ground. */
+export declare const createOAuthGuardStage: (oauth?: OAuthConfig) => Stage;