@plitzi/sdk-server 0.32.25 → 0.33.1

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

@@ -0,0 +1,27 @@
+import { AuthedRequest, JsonResponse } from './types';
+import { AuthPolicy } from '../auth/authorize';
+import { Identity } from '../auth/identity';
+export interface AuthMiddlewareOptions {
+    /**
+     * Which key carries the human-readable refusal. `error` by convention; `message` for an API whose clients already
+     * read that. Only the wording moves — `reason` is always beside it, because that is the half a client acts on.
+     */
+    errorKey?: 'error' | 'message';
+}
+/**
+ * The authorizer, as middleware: `(req, res, next)`.
+ *
+ * The decision itself is `createAuthorizer` and is the same on every transport — that is why it lives a level down,
+ * and why a host that has no middleware chain should call that instead. What is here is the binding: put what was
+ * resolved onto the request so everything behind it can read `req.user` and `req.grant`, and answer a refusal in a
+ * shape a client can act on.
+ *
+ * Both halves of that answer matter. The message is for a person reading a log; `reason` is for the browser, and it
+ * is what separates "renew me" from "you are gone" — without it a client either signs people out on a hiccup or
+ * retries a dead session forever.
+ *
+ * ```ts
+ * app.use(createAuthMiddleware(auth.identity, policy));
+ * ```
+ */
+export declare const createAuthMiddleware: (identity: Identity, policy: AuthPolicy, options?: AuthMiddlewareOptions) => (req: AuthedRequest, res: JsonResponse, next: () => void) => Promise<void>;

package/dist/core/handlers/authMiddleware.js

@@ -0,0 +1,38 @@
+import { authFailureMessage } from "../auth/tokens.js";
+import { createAuthorizer } from "../auth/authorize.js";
+//#region src/core/handlers/authMiddleware.ts
+/**
+* The authorizer, as middleware: `(req, res, next)`.
+*
+* The decision itself is `createAuthorizer` and is the same on every transport — that is why it lives a level down,
+* and why a host that has no middleware chain should call that instead. What is here is the binding: put what was
+* resolved onto the request so everything behind it can read `req.user` and `req.grant`, and answer a refusal in a
+* shape a client can act on.
+*
+* Both halves of that answer matter. The message is for a person reading a log; `reason` is for the browser, and it
+* is what separates "renew me" from "you are gone" — without it a client either signs people out on a hiccup or
+* retries a dead session forever.
+*
+* ```ts
+* app.use(createAuthMiddleware(auth.identity, policy));
+* ```
+*/
+var createAuthMiddleware = (identity, policy, options = {}) => {
+	const { errorKey = "error" } = options;
+	const authorize = createAuthorizer(identity, policy);
+	return async (req, res, next) => {
+		const result = await authorize(req, req.path);
+		if (!result.ok) {
+			res.status(result.status).json({
+				[errorKey]: authFailureMessage[result.reason],
+				reason: result.reason
+			});
+			return;
+		}
+		if (result.actor) req.user = result.actor;
+		if (result.grant) req.grant = result.grant;
+		next();
+	};
+};
+//#endregion
+export { createAuthMiddleware };

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

@@ -0,0 +1,46 @@
+import { HttpRoute, RouterLike } from './types';
+import { AuthApi } from '../auth/api';
+import { SessionCookies } from '../auth/session';
+export interface AuthRouteHandlersOptions {
+    api: AuthApi;
+    cookies: SessionCookies;
+    /** Reports a flow 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;
+}
+/**
+ * The whole `/auth` surface as request handlers: signing in and out, renewing, who-am-I, revoking every session,
+ * and whichever of signup and password reset the deployment's adapters offer.
+ *
+ * The kernel answers these as *outcomes* — a body, a status, what should happen to the session — because it has no
+ * idea what any deployment runs behind. Turning an outcome into an HTTP answer is the same everywhere, and every
+ * deployment wrote the same loop for it. Doing what the outcome says about the cookies is the part worth not
+ * rewriting: writing the session but not its readable hint is the failure that looks like a session which exists
+ * and then does not.
+ *
+ * A list, so nothing has to be a router. On a bare `node:http` server, dispatch it yourself:
+ *
+ * ```ts
+ * const routes = createAuthRouteHandlers({ api: auth.api, cookies: auth.cookies });
+ * const route = routes.find(r => r.method === req.method && `/auth${r.path}` === url.pathname);
+ * await route?.handle(request, response);
+ * ```
+ *
+ * With a router, {@link mountAuthRoutes} is that same loop already written.
+ *
+ * Which flows actually answer is decided by the adapters, not here — no `createAccount`, no signup, and the route
+ * reports 404 rather than failing at runtime. Mounting all of them is correct for a deployment that offers three.
+ */
+export declare const createAuthRouteHandlers: ({ api, cookies, onError }: AuthRouteHandlersOptions) => HttpRoute[];
+/**
+ * {@link createAuthRouteHandlers}, hung on anything with `get` and `post`.
+ *
+ * ```ts
+ * const router = Router();
+ * mountAuthRoutes(router, { api: auth.api, cookies: auth.cookies });
+ * app.use('/auth', router);
+ * ```
+ */
+export declare const mountAuthRoutes: (router: RouterLike, options: AuthRouteHandlersOptions) => void;

package/dist/core/handlers/authRouteHandlers.js

@@ -0,0 +1,75 @@
+import { applySessionOutcome, authRoutes } from "../auth/routes.js";
+//#region src/core/handlers/authRouteHandlers.ts
+/**
+* Built field by field rather than spread: on several frameworks `hostname` is a getter on the request prototype,
+* and a spread copies own properties only — it would arrive undefined, and every cookie would then be named for
+* nowhere. The kind of thing that is obvious once and costs an afternoon otherwise, which is why it is stated here
+* rather than left for each deployment to rediscover.
+*/
+var carrier = (req) => ({
+	headers: req.headers,
+	hostname: req.hostname,
+	cookies: req.cookies,
+	query: req.query,
+	body: req.body,
+	actor: req.user
+});
+/**
+* The whole `/auth` surface as request handlers: signing in and out, renewing, who-am-I, revoking every session,
+* and whichever of signup and password reset the deployment's adapters offer.
+*
+* The kernel answers these as *outcomes* — a body, a status, what should happen to the session — because it has no
+* idea what any deployment runs behind. Turning an outcome into an HTTP answer is the same everywhere, and every
+* deployment wrote the same loop for it. Doing what the outcome says about the cookies is the part worth not
+* rewriting: writing the session but not its readable hint is the failure that looks like a session which exists
+* and then does not.
+*
+* A list, so nothing has to be a router. On a bare `node:http` server, dispatch it yourself:
+*
+* ```ts
+* const routes = createAuthRouteHandlers({ api: auth.api, cookies: auth.cookies });
+* const route = routes.find(r => r.method === req.method && `/auth${r.path}` === url.pathname);
+* await route?.handle(request, response);
+* ```
+*
+* With a router, {@link mountAuthRoutes} is that same loop already written.
+*
+* Which flows actually answer is decided by the adapters, not here — no `createAccount`, no signup, and the route
+* reports 404 rather than failing at runtime. Mounting all of them is correct for a deployment that offers three.
+*/
+var createAuthRouteHandlers = ({ api, cookies, onError }) => authRoutes({
+	api,
+	cookies
+}).map(({ method, path, handler }) => ({
+	method,
+	path,
+	handle: async (req, res) => {
+		try {
+			const outcome = await handler(carrier(req));
+			applySessionOutcome(req, res, outcome, cookies);
+			res.status(outcome.ok ? outcome.status ?? 200 : outcome.status).json(outcome.body);
+		} catch (error) {
+			if (onError) onError(error, {
+				method,
+				path
+			});
+			else console.error(`[auth] ${method} ${path} failed:`, error);
+			res.status(500).json({ error: "Internal server error" });
+		}
+	}
+}));
+/**
+* {@link createAuthRouteHandlers}, hung on anything with `get` and `post`.
+*
+* ```ts
+* const router = Router();
+* mountAuthRoutes(router, { api: auth.api, cookies: auth.cookies });
+* app.use('/auth', router);
+* ```
+*/
+var mountAuthRoutes = (router, options) => {
+	for (const { method, path, handle } of createAuthRouteHandlers(options)) if (method === "GET") router.get(path, handle);
+	else router.post(path, handle);
+};
+//#endregion
+export { createAuthRouteHandlers, mountAuthRoutes };

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

@@ -0,0 +1,37 @@
+import { CredentialCarrier } from '../auth/credentials';
+import { Actor, Grant } from '../auth/identity';
+import { CookieSink } from '../auth/session';
+/**
+ * A request and a response, described by what these handlers actually touch and nothing more.
+ *
+ * No framework is imported and none is assumed. A bare `node:http` request satisfies `AuthedRequest` once `path`
+ * is filled in (`parseRequest` from the kernel does that); an Express, Connect or Koa request satisfies it as it
+ * stands. The response needs three things — a status, a JSON body, and a header for the cookies.
+ */
+export interface AuthedRequest extends CredentialCarrier {
+    /** The path alone, without the query string — what the policy matches on. */
+    path: 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. */
+    user?: Actor;
+    /** The space this request is addressed to, and what its bearer may do with it. */
+    grant?: Grant;
+}
+export interface JsonResponse extends CookieSink {
+    status: (code: number) => JsonResponse;
+    json: (body: unknown) => unknown;
+}
+export type RouteHandler = (req: AuthedRequest, res: JsonResponse) => Promise<void>;
+/** One flow, ready to serve: where it answers, and what to call when it does. */
+export interface HttpRoute {
+    method: 'GET' | 'POST';
+    /** Relative to wherever the host mounts the set — `/auth`, conventionally. */
+    path: string;
+    handle: RouteHandler;
+}
+/** 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;
+}

package/dist/{src/core → core}/http/dispatcher.d.ts

@@ -1,7 +1,7 @@
 import { BaseContext, Stage } from './types';
 import { RawResponse } from '../../helpers/buildResponseHelpers';
 import { Handler } from '../transports';
-import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+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 declare const makeHandler: <C extends BaseContext>(label: string, buildContext: BuildContext<C>, stages: Stage<C>[]) => Handler;
+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

@@ -1,6 +1,7 @@
+import { clientIp, parseRequest } from "../requestParser.js";
 import { applySecurityHeaders } from "./securityHeaders.js";
+import { resolveCompression } from "../../helpers/compress.js";
 import { buildResponseHelpers } from "../../helpers/buildResponseHelpers.js";
-import { clientIp, parseRequest } from "../requestParser.js";
 //#region src/core/http/dispatcher.ts
 var safePath = (url) => {
 	const [path = "/", query] = url.split("?");
@@ -10,10 +11,10 @@ var safePath = (url) => {
 };
 var errorText = (error) => error instanceof Error ? error.message : String(error);
 var statusOf = (rawRes, res) => rawRes.headersSent ? rawRes.statusCode : res.status;
-var runPipeline = async (raw, rawRes, buildContext, stages, server) => {
+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"]);
+	const res = buildResponseHelpers(rawRes, req.headers["accept-encoding"], compression);
 	const ctx = buildContext(raw, rawRes, req, res);
 	const logger = ctx.config.logger;
 	const ip = logger ? clientIp(raw, req) : "";
@@ -29,7 +30,7 @@ var runPipeline = async (raw, rawRes, buildContext, stages, server) => {
 			...ctx.operation === void 0 ? {} : { operation: ctx.operation },
 			status,
 			durationMs: Date.now() - startedAt,
-			ok: !error && status < 400,
+			ok: !error && status < 500,
 			...error ? { error: errorText(error) } : {},
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
@@ -52,9 +53,10 @@ var runPipeline = async (raw, rawRes, buildContext, stages, server) => {
 		throw error;
 	}
 };
-var makeHandler = (label, buildContext, stages) => {
+var makeHandler = (label, buildContext, stages, compressionConfig) => {
+	const compression = resolveCompression(compressionConfig);
 	return (raw, rawRes) => {
-		runPipeline(raw, rawRes, buildContext, stages, label).catch((err) => {
+		runPipeline(raw, rawRes, buildContext, stages, label, compression).catch((err) => {
 			console.error(`[${label}] Unhandled error:`, err);
 			try {
 				if (!rawRes.headersSent) rawRes.writeHead(500, { "Content-Type": "text/plain" });

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

@@ -0,0 +1,11 @@
+import { SSRRequest } from '@plitzi/sdk-shared';
+/**
+ * A full-page form submission, as opposed to a script's fetch.
+ *
+ * The difference decides how an auth flow answers: a browser navigating away from a page it has already left shows
+ * its own error page for a bodyless 401, and stays on the stale one for a 204. Either way the visitor sees the wrong
+ * thing, so a navigation is answered with a redirect and the view re-renders through a GET. A fetch wants the body.
+ */
+export declare const isNavigation: (req: SSRRequest) => boolean;
+/** Same-origin only: absolute URLs and protocol-relative `//host` are refused, to avoid an open redirect. */
+export declare const safeRedirectTarget: (req: SSRRequest) => string;

package/dist/core/http/navigation.js

@@ -0,0 +1,16 @@
+//#region src/core/http/navigation.ts
+/**
+* A full-page form submission, as opposed to a script's fetch.
+*
+* The difference decides how an auth flow answers: a browser navigating away from a page it has already left shows
+* its own error page for a bodyless 401, and stays on the stale one for a 204. Either way the visitor sees the wrong
+* thing, so a navigation is answered with a redirect and the view re-renders through a GET. A fetch wants the body.
+*/
+var isNavigation = (req) => req.headers["sec-fetch-mode"] === "navigate";
+/** Same-origin only: absolute URLs and protocol-relative `//host` are refused, to avoid an open redirect. */
+var safeRedirectTarget = (req) => {
+	const redirectParam = req.query["redirect"];
+	return redirectParam && redirectParam.startsWith("/") && !redirectParam.startsWith("//") ? redirectParam : "/";
+};
+//#endregion
+export { isNavigation, safeRedirectTarget };

package/dist/core/http/securityHeaders.js

@@ -4,10 +4,12 @@ var applySecurityHeaders = (res, config, port) => {
 	res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
 	res.setHeader("X-DNS-Prefetch-Control", "off");
 	const frameOptions = config.frameOptions === void 0 ? "DENY" : config.frameOptions;
-	if (frameOptions) if (Array.isArray(frameOptions)) res.setHeader("Content-Security-Policy", `frame-ancestors ${frameOptions.join(" ")}`);
-	else {
-		res.setHeader("X-Frame-Options", frameOptions);
-		res.setHeader("Content-Security-Policy", `frame-ancestors '${frameOptions === "DENY" ? "none" : "self"}'`);
+	if (frameOptions) {
+		if (Array.isArray(frameOptions)) res.setHeader("Content-Security-Policy", `frame-ancestors ${frameOptions.join(" ")}`);
+		else {
+			res.setHeader("X-Frame-Options", frameOptions);
+			res.setHeader("Content-Security-Policy", `frame-ancestors '${frameOptions === "DENY" ? "none" : "self"}'`);
+		}
 	}
 	if ((config.httpVersion ?? 2) >= 3) res.setHeader("Alt-Svc", `h3=":${port}"; ma=86400`);
 };

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

@@ -0,0 +1,17 @@
+import { Auth } from '../../auth/createAuth';
+import { BaseContext, Stage } from '../types';
+/**
+ * Serves the whole `/auth` surface: signing in and out, renewing before the credential lapses, answering who this
+ * is, revoking every session, and whichever of signup and password reset the deployment offers.
+ *
+ * A page server that stops at login and logout leaves a space unable to keep anybody signed in — the SDK renews
+ * against `refreshUrl`, and with nothing there a visitor is signed out the moment their access token ages out. So
+ * `createServer({ auth })` mounts these, and a deployment gets the whole cycle rather than the two ends of it.
+ *
+ * It owns login and logout too, rather than leaving them to the adapter-only stages that can also answer on those
+ * paths: those know how to establish a session and nothing about the account behind it, so they can only answer a
+ * bodyless 200 where this one returns the grant — the token, its expiry and who it belongs to. Whichever runs is
+ * what a caller gets, so having both live meant a signed-in client that could not tell it had signed in.
+ * `createServer` stands the adapter-only pair down when an auth kernel is present.
+ */
+export declare const createAuthApiStage: (auth: Auth, basePath?: string) => Stage<BaseContext>;

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

@@ -0,0 +1,66 @@
+import { readRawBody } from "../../requestParser.js";
+import { isNavigation, safeRedirectTarget } from "../navigation.js";
+//#region src/core/http/stages/authApi.ts
+var parseBody = (raw, contentType) => {
+	if (!raw) return;
+	if (typeof contentType === "string" && contentType.includes("application/json")) try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+	return Object.fromEntries(new URLSearchParams(raw));
+};
+/**
+* Serves the whole `/auth` surface: signing in and out, renewing before the credential lapses, answering who this
+* is, revoking every session, and whichever of signup and password reset the deployment offers.
+*
+* A page server that stops at login and logout leaves a space unable to keep anybody signed in — the SDK renews
+* against `refreshUrl`, and with nothing there a visitor is signed out the moment their access token ages out. So
+* `createServer({ auth })` mounts these, and a deployment gets the whole cycle rather than the two ends of it.
+*
+* It owns login and logout too, rather than leaving them to the adapter-only stages that can also answer on those
+* paths: those know how to establish a session and nothing about the account behind it, so they can only answer a
+* bodyless 200 where this one returns the grant — the token, its expiry and who it belongs to. Whichever runs is
+* what a caller gets, so having both live meant a signed-in client that could not tell it had signed in.
+* `createServer` stands the adapter-only pair down when an auth kernel is present.
+*/
+var createAuthApiStage = (auth, basePath = auth.basePath) => {
+	const byPath = new Map(auth.routes.map((route) => [`${basePath}${route.path}`, route]));
+	return async (ctx) => {
+		const { req, res, raw } = ctx;
+		const route = byPath.get(req.path);
+		if (!route || route.method !== req.method) return false;
+		const decision = await auth.authorize(req, req.path);
+		if (!decision.ok) {
+			res.setStatus(decision.status);
+			res.setHeader("Content-Type", "application/json");
+			res.send(JSON.stringify({
+				error: "Access Not Authorized",
+				reason: decision.reason
+			}));
+			return true;
+		}
+		req.body = req.method === "POST" ? await readRawBody(raw) : void 0;
+		const authRequest = {
+			headers: req.headers,
+			hostname: req.hostname,
+			query: req.query,
+			body: parseBody(req.body, req.headers["content-type"]),
+			actor: decision.actor
+		};
+		const outcome = await route.handler(authRequest);
+		auth.applySession(req, res, outcome, auth.cookies);
+		if (isNavigation(req)) {
+			res.setStatus(303);
+			res.setHeader("Location", outcome.ok ? safeRedirectTarget(req) : req.path);
+			res.end();
+			return true;
+		}
+		res.setStatus(outcome.ok ? outcome.status ?? 200 : outcome.status);
+		res.setHeader("Content-Type", "application/json");
+		res.send(JSON.stringify(outcome.body));
+		return true;
+	};
+};
+//#endregion
+export { createAuthApiStage };

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

@@ -1,23 +1,47 @@
 import { readRawBody } from "../../requestParser.js";
+import { isNavigation, safeRedirectTarget } from "../navigation.js";
+import { clearSessionCookies, writeSessionCookies } from "../../auth/session.js";
+import { exchangeStage } from "./exchangeRoute.js";
 //#region src/core/http/stages/authRoutes.ts
-var safeRedirectTarget = (req) => {
-	const redirectParam = req.query["redirect"];
-	return redirectParam && redirectParam.startsWith("/") && !redirectParam.startsWith("//") ? redirectParam : "/";
+/**
+* Credentials as they arrive from a page: a posted form, or JSON from a script. Every field is handed to the
+* adapter — a deployment may sign people in with something other than a username and a password, and this layer
+* has no opinion about which fields those are.
+*/
+var parseCredentials = (req) => {
+	if (!req.body) return {};
+	const contentType = req.headers["content-type"];
+	if (typeof contentType === "string" && contentType.includes("application/json")) try {
+		const parsed = JSON.parse(req.body);
+		return Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === "string"));
+	} catch {
+		return {};
+	}
+	return Object.fromEntries(new URLSearchParams(req.body));
 };
 var loginStage = async (ctx) => {
 	const { config, raw, req, res } = ctx;
 	const loginPath = config.loginPath === false ? null : config.loginPath ?? "/auth/login";
 	if (!loginPath || req.method !== "POST" || req.path !== loginPath) return false;
 	req.body = await readRawBody(raw);
-	const isLoggedIn = await config.adapters.onLogin?.(req, res);
-	if (req.headers["sec-fetch-mode"] === "navigate") {
+	const session = await config.adapters.authenticate?.(parseCredentials(req), req);
+	if (session) writeSessionCookies(req, res, session, config.authCookie);
+	if (isNavigation(req)) {
 		res.setStatus(303);
-		res.setHeader("Location", isLoggedIn ? safeRedirectTarget(req) : loginPath);
+		res.setHeader("Location", session ? safeRedirectTarget(req) : loginPath);
 		res.end();
 		return true;
 	}
-	res.setStatus(isLoggedIn ? 200 : 401);
-	res.end();
+	res.setStatus(session ? 200 : 401);
+	res.setHeader("Content-Type", "application/json");
+	res.send(JSON.stringify(session ? {
+		success: true,
+		access_token: session.token,
+		expire_at: session.expiresAt
+	} : {
+		error: "Invalid credentials",
+		reason: "invalid"
+	}));
 	return true;
 };
 var logoutStage = async (ctx) => {
@@ -25,8 +49,9 @@ var logoutStage = async (ctx) => {
 	const logoutPath = config.logoutPath === false ? null : config.logoutPath ?? "/auth/logout";
 	if (!logoutPath || req.method !== "POST" || req.path !== logoutPath) return false;
 	req.body = await readRawBody(raw);
-	await config.adapters.onLogout?.(req, res);
-	if (req.headers["sec-fetch-mode"] === "navigate") {
+	await config.adapters.endSession?.(req);
+	clearSessionCookies(req, res, config.authCookie);
+	if (isNavigation(req)) {
 		res.setStatus(303);
 		res.setHeader("Location", safeRedirectTarget(req));
 		res.end();
@@ -36,6 +61,10 @@ var logoutStage = async (ctx) => {
 	res.end();
 	return true;
 };
-var authRoutesStages = [loginStage, logoutStage];
+var authRoutesStages = [
+	loginStage,
+	logoutStage,
+	exchangeStage
+];
 //#endregion
 export { authRoutesStages, loginStage, logoutStage };

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

@@ -0,0 +1,15 @@
+import { Stage } from '../types';
+/**
+ * Turns a credential the browser obtained on its own into a session of this server's, through the
+ * `exchangeCredential` adapter. A deployment running the auth kernel gets `POST /auth/exchange` from the flows
+ * instead, and `createServer` stands this one down so the two never answer on the same path.
+ *
+ * It exists for identity providers that live in the front-end — Auth0 and the like — where this server never sees
+ * the sign-in and would go on rendering every page as a guest while the browser knows perfectly well who the
+ * visitor is. The page then changes under them as it hydrates. Handing the credential over closes that gap.
+ *
+ * Everything that decides whether the credential is any good is the adapter's: which providers this deployment
+ * trusts, whether the token was minted for *this* application, and who it belongs to. This layer contributes the
+ * part that is the same everywhere — reading the request, and writing the session it gets back.
+ */
+export declare const exchangeStage: Stage;

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

@@ -0,0 +1,67 @@
+import { readRawBody } from "../../requestParser.js";
+import { writeSessionCookies } from "../../auth/session.js";
+//#region src/core/http/stages/exchangeRoute.ts
+var parseBody = (req) => {
+	if (!req.body) return {};
+	try {
+		const parsed = JSON.parse(req.body);
+		return {
+			provider: typeof parsed.provider === "string" ? parsed.provider : void 0,
+			token: typeof parsed.token === "string" ? parsed.token : void 0
+		};
+	} catch {
+		return {};
+	}
+};
+/**
+* Turns a credential the browser obtained on its own into a session of this server's, through the
+* `exchangeCredential` adapter. A deployment running the auth kernel gets `POST /auth/exchange` from the flows
+* instead, and `createServer` stands this one down so the two never answer on the same path.
+*
+* It exists for identity providers that live in the front-end — Auth0 and the like — where this server never sees
+* the sign-in and would go on rendering every page as a guest while the browser knows perfectly well who the
+* visitor is. The page then changes under them as it hydrates. Handing the credential over closes that gap.
+*
+* Everything that decides whether the credential is any good is the adapter's: which providers this deployment
+* trusts, whether the token was minted for *this* application, and who it belongs to. This layer contributes the
+* part that is the same everywhere — reading the request, and writing the session it gets back.
+*/
+var exchangeStage = async (ctx) => {
+	const { config, raw, req, res } = ctx;
+	const exchangePath = config.exchangePath === false ? null : config.exchangePath ?? "/auth/exchange";
+	if (!exchangePath || req.method !== "POST" || req.path !== exchangePath) return false;
+	if (!config.adapters.exchangeCredential) {
+		res.setStatus(404);
+		res.end();
+		return true;
+	}
+	req.body = await readRawBody(raw);
+	const { provider, token } = parseBody(req);
+	if (!provider || !token) {
+		res.setStatus(400);
+		res.setHeader("Content-Type", "application/json");
+		res.send(JSON.stringify({ error: "A provider and a token are required" }));
+		return true;
+	}
+	const result = await config.adapters.exchangeCredential(provider, token, req);
+	if (!result.ok) {
+		res.setStatus(result.status ?? 401);
+		res.setHeader("Content-Type", "application/json");
+		res.send(JSON.stringify({
+			error: result.error,
+			reason: result.reason ?? "revoked"
+		}));
+		return true;
+	}
+	writeSessionCookies(req, res, result.session, config.authCookie);
+	res.setStatus(200);
+	res.setHeader("Content-Type", "application/json");
+	res.send(JSON.stringify({
+		success: true,
+		details: result.user,
+		access_token: result.session.token
+	}));
+	return true;
+};
+//#endregion
+export { exchangeStage };

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

@@ -0,0 +1,11 @@
+import { Stage } from '../types';
+/**
+ * Liveness/readiness endpoint for standalone servers (k8s probes). Always answers at /health so every server built
+ * on sdk-server has one without the consumer wiring it. The body is the generic identity payload (from
+ * `config.health.name/version/role`) unless `payload` overrides it entirely.
+ *
+ * `check` is what makes it a readiness probe: it reports live state — the stores this process depends on, most
+ * often — and `healthy: false` answers 503 so an orchestrator stops routing to a replica that cannot serve. A
+ * server that answered 200 while its database was gone is one an orchestrator keeps sending traffic to.
+ */
+export declare const healthStage: Stage;

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

@@ -1,11 +1,33 @@
 import { buildHealthPayload } from "../../health.js";
 //#region src/core/http/stages/health.ts
-var healthStage = (ctx) => {
+/**
+* Liveness/readiness endpoint for standalone servers (k8s probes). Always answers at /health so every server built
+* on sdk-server has one without the consumer wiring it. The body is the generic identity payload (from
+* `config.health.name/version/role`) unless `payload` overrides it entirely.
+*
+* `check` is what makes it a readiness probe: it reports live state — the stores this process depends on, most
+* often — and `healthy: false` answers 503 so an orchestrator stops routing to a replica that cannot serve. A
+* server that answered 200 while its database was gone is one an orchestrator keeps sending traffic to.
+*/
+var healthStage = async (ctx) => {
 	const health = ctx.config.health;
 	if (ctx.req.path !== (health?.path ?? "/health")) return false;
+	const payload = health?.payload ?? buildHealthPayload(health);
+	let live = {};
+	if (health?.check) try {
+		live = await health.check();
+	} catch (error) {
+		live = {
+			healthy: false,
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	}
 	ctx.res.setHeader("Content-Type", "application/json");
-	ctx.res.setStatus(200);
-	ctx.res.send(JSON.stringify(health?.payload ?? buildHealthPayload(health)));
+	ctx.res.setStatus(live.healthy === false ? 503 : 200);
+	ctx.res.send(JSON.stringify({
+		...payload,
+		...live
+	}));
 	return true;
 };
 //#endregion

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

@@ -0,0 +1,2 @@
+import { SSRContext, Stage } from '../types';
+export declare const middlewaresStage: Stage<SSRContext>;

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

@@ -0,0 +1,13 @@
+import { Stage } from '../types';
+export declare const publicDirStage: Stage;
+export declare const wellKnownStage: Stage;
+export declare const configStaticStage: Stage;
+/**
+ * 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': … }`.
+ */
+export declare const sdkAssetsStage: Stage;