@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/core/auth/totp.js

@@ -55,28 +55,33 @@ var codeAt = (secret, counter) => {
 /** The code an app would be showing right now. Exported so a test does not have to reimplement the algorithm. */
 var totpCode = (secret, at = Date.now()) => codeAt(secret, Math.floor(at / 1e3 / STEP_SECONDS));
 /**
-* Is this the code?
+* Which time step this code belongs to, or `undefined` when it belongs to none near now.
 *
 * `window` steps either side are accepted, one by default — thirty seconds of tolerance for a clock that drifts
 * and for a person who starts typing at second twenty-nine. Wider is friendlier and weaker; this is the usual
 * trade and the same one Google Authenticator's own guidance makes.
 *
+* The step is the answer, not a yes: a code stays valid for its whole window, so a verifier that remembers nothing
+* accepts the same code twice. RFC 6238 §5.2 forbids that — see `MfaRecord.lastUsedStep`.
+*
 * Compared in constant time: a comparison that returns on the first differing digit leaks how much of a guess was
 * right, which turns a million-guess space into ten guesses per position.
 */
-var verifyTotp = (secret, code, options = {}) => {
+var totpStep = (secret, code, options = {}) => {
 	const { window = 1, at = Date.now() } = options;
 	const candidate = code.trim();
-	if (!/^\d{6}$/.test(candidate)) return false;
+	if (!/^\d{6}$/.test(candidate)) return;
 	const counter = Math.floor(at / 1e3 / STEP_SECONDS);
 	const supplied = Buffer.from(candidate);
-	let matched = false;
+	let matched;
 	for (let drift = -window; drift <= window; drift++) {
 		const expected = Buffer.from(codeAt(secret, counter + drift));
-		matched = timingSafeEqual(expected, supplied) || matched;
+		if (timingSafeEqual(expected, supplied)) matched = counter + drift;
 	}
 	return matched;
 };
+/** Is this the code? `totpStep`, for a caller that does not need to know which step it was. */
+var verifyTotp = (secret, code, options = {}) => totpStep(secret, code, options) !== void 0;
 /**
 * The URI an authenticator app scans. `issuer` appears twice by convention — in the label and as a parameter —
 * because different apps read different ones, and an entry that says only an email address is unidentifiable in a
@@ -115,4 +120,4 @@ var generateRecoveryCodes = (count = 10) => Array.from({ length: count }, () =>
 /** Normalised before hashing so that case and the hyphen a person types or omits do not decide whether it works. */
 var normalizeRecoveryCode = (code) => code.trim().toUpperCase().replace(/[^A-Z0-9]/g, "");
 //#endregion
-export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpUri, verifyTotp };
+export { generateRecoveryCodes, generateTotpSecret, normalizeRecoveryCode, randomCode, totpCode, totpStep, totpUri, verifyTotp };

package/dist/core/createServer.actions.test.d.ts

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

package/dist/core/createServer.d.ts

@@ -19,5 +19,18 @@ export type ServerConfig = Omit<SSRServerConfig, 'adapters'> & {
      * `adapters` or `authCookie` still wins, so a deployment can override one piece without giving up the rest.
      */
     auth?: Auth;
+    /**
+     * Where a page request whose access cookie has died, while its refresh cookie lives on, is sent to renew before
+     * the page is rendered — so the server renders the visitor the browser is about to become, rather than a guest
+     * the browser then replaces. The endpoint is `GET <basePath>/refresh`, served by `auth` here or by
+     * `mountAuthRoutes` wherever `/auth` lives.
+     *
+     * On by default with `auth`, at its own `/refresh`. Without it, name the endpoint — an absolute URL when another
+     * host serves `/auth` (a host sharing the session's cookie domain, or the hint that triggers this never arrives).
+     * `false` turns it off.
+     */
+    sessionRenewal?: {
+        url: string;
+    } | false;
 };
-export declare const createServer: ({ auth, ...config }: ServerConfig, extensions?: PipelineExtensions) => SSRServer;
+export declare const createServer: ({ auth, sessionRenewal, ...config }: ServerConfig, extensions?: PipelineExtensions) => SSRServer;

package/dist/core/createServer.functions.test.d.ts

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

package/dist/core/createServer.js

@@ -1,6 +1,7 @@
 import { actionsModuleFor } from "../modules/actions/moduleFor.js";
 import { connectorRscData } from "../modules/rsc/connectorRscData.js";
 import { createAuthApiStage } from "./http/stages/authApi.js";
+import { createRenewalEndpointStage, createSessionRenewalStage } from "./http/stages/sessionRenewal.js";
 import { resolveServices } from "./services/resolve.js";
 import { createPageServer } from "./server/pageServer.js";
 //#region src/core/createServer.ts
@@ -24,23 +25,27 @@ import { createPageServer } from "./server/pageServer.js";
 */
 var withConnectorRsc = (config) => {
 	if (config.adapters.getRscData || !config.connectors && !config.action?.lookups) return config;
-	const module = actionsModuleFor(config);
+	const resolved = {
+		...config,
+		adapters: { ...config.adapters }
+	};
+	const module = actionsModuleFor(resolved);
 	const actions = module && config.action?.lookups ? {
 		lookups: config.action.lookups,
 		module
 	} : void 0;
-	return {
-		...config,
-		adapters: {
-			...config.adapters,
-			getRscData: connectorRscData(config.connectors, actions, config.rsc?.elementTimeoutMs)
-		}
-	};
+	resolved.adapters.getRscData = connectorRscData(config.connectors, actions, config.rsc?.elementTimeoutMs);
+	return resolved;
 };
-var createServer = ({ auth, ...config }, extensions) => {
+/** The renewal stage in front of whatever else gates itself, when there is anywhere to renew. */
+var withRenewal = (extensions, url) => ({
+	...extensions,
+	preAuth: [...extensions?.preAuth ?? [], ...url ? [createSessionRenewalStage(url)] : []]
+});
+var createServer = ({ auth, sessionRenewal, ...config }, extensions) => {
 	if (!auth) {
 		const resolvedConfig = withConnectorRsc(config);
-		return createPageServer(resolvedConfig, resolveServices(resolvedConfig), extensions);
+		return createPageServer(resolvedConfig, resolveServices(resolvedConfig), withRenewal(extensions, sessionRenewal ? sessionRenewal.url : void 0));
 	}
 	const entries = Object.entries(config.adapters);
 	const supplied = Object.fromEntries(entries.filter(([, value]) => value !== void 0));
@@ -57,9 +62,14 @@ var createServer = ({ auth, ...config }, extensions) => {
 	});
 	const withAuthRoutes = {
 		...extensions,
-		preAuth: [...extensions?.preAuth ?? [], createAuthApiStage(auth, auth.basePath)]
+		preAuth: [
+			...extensions?.preAuth ?? [],
+			createAuthApiStage(auth, auth.basePath),
+			createRenewalEndpointStage(auth)
+		]
 	};
-	return createPageServer(resolved, resolveServices(resolved), withAuthRoutes);
+	const renewalUrl = sessionRenewal === false ? void 0 : sessionRenewal?.url ?? `${auth.basePath}/refresh`;
+	return createPageServer(resolved, resolveServices(resolved), withRenewal(withAuthRoutes, renewalUrl));
 };
 //#endregion
 export { createServer, resolveServices };

package/dist/core/fontStore.js

@@ -1,5 +1,5 @@
-import fs from "node:fs";
 import path from "node:path";
+import fs from "node:fs";
 //#region src/core/fontStore.ts
 /** `<spaceId>/<name>` — the space segment is what keeps one space's files out of another's. */
 var storePathOf = (spaceId, name) => `${spaceId}/${name}`;

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

@@ -12,7 +12,7 @@ export interface AuthRouteHandlersOptions {
      * deployment that means to go without says so with `csrf: false` there rather than by forgetting here.
      */
     csrf?: Csrf;
-    /** Reports a flow that threw. Without it the failure goes to `console.error`; the caller still gets a 500. */
+    /** Reports a flow that threw. Without it the failure goes to the server log at `error`; the caller still gets a 500. */
     onError?: (error: unknown, context: {
         method: string;
         path: string;

package/dist/core/handlers/authRouteHandlers.js

@@ -1,4 +1,6 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { applySessionOutcome, authRoutes } from "../auth/routes.js";
+import { isDocumentNavigation, renewForNavigation } from "../auth/renewal.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,
@@ -37,28 +39,62 @@ var carrier = (req) => ({
 * 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, csrf, onError }) => authRoutes({
-	api,
-	cookies,
-	csrf
-}).map(({ method, path, handler }) => ({
-	method,
-	path,
-	handle: async (req, res) => {
-		try {
-			const outcome = await handler(carrier(req));
-			applySessionOutcome(req, res, outcome, cookies, csrf);
-			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" });
+var createAuthRouteHandlers = ({ api, cookies, csrf, onError }) => {
+	const failed = (error, method, path, res) => {
+		if (onError) onError(error, {
+			method,
+			path
+		});
+		else serverLog.error("auth", `${method} ${path} failed`, error);
+		res.status(500).json({ error: "Internal server error" });
+	};
+	const flows = authRoutes({
+		api,
+		cookies,
+		csrf
+	}).map(({ method, path, handler }) => ({
+		method,
+		path,
+		handle: async (req, res) => {
+			try {
+				const outcome = await handler(carrier(req));
+				applySessionOutcome(req, res, outcome, cookies, csrf);
+				res.status(outcome.ok ? outcome.status ?? 200 : outcome.status).json(outcome.body);
+			} catch (error) {
+				failed(error, method, path, res);
+			}
 		}
-	}
-}));
+	}));
+	/**
+	* Renewal on the way to a page — see `renewForNavigation`. Answered with a status and a `Location` rather than a
+	* framework's `redirect`, so the set keeps asking a response for nothing beyond a status and a body; the body says
+	* the same thing, for whoever reads it. Anything but a whole-tab navigation is told to renew the usual way.
+	*/
+	const renewal = {
+		method: "GET",
+		path: "/refresh",
+		handle: async (req, res) => {
+			if (!isDocumentNavigation(req.headers)) {
+				res.setHeader("Allow", "POST");
+				res.status(405).json({ error: "Renew with POST" });
+				return;
+			}
+			try {
+				const location = await renewForNavigation(carrier(req), res, {
+					api,
+					cookies,
+					csrf
+				});
+				res.setHeader("Cache-Control", "no-store");
+				res.setHeader("Location", location);
+				res.status(303).json({ redirect: location });
+			} catch (error) {
+				failed(error, "GET", "/refresh", res);
+			}
+		}
+	};
+	return [...flows, renewal];
+};
 /**
 * {@link createAuthRouteHandlers}, hung on anything with `get` and `post`.
 *

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

@@ -18,3 +18,26 @@ export interface CsrfMiddlewareOptions {
  * 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;
+export interface OriginGuardOptions {
+    /**
+     * Origins this request may also come from, beyond the deployment's own — the ones the space credential it carries
+     * declares. `true` for a credential that declares any origin at all.
+     */
+    allowedFor?: (req: AuthedRequest) => readonly string[] | true | undefined;
+    /** Paths never guarded. A webhook carries no session cookie and is never refused anyway; this is for the rest. */
+    exempt?: (path: string) => boolean;
+    errorKey?: 'message' | 'error';
+}
+/**
+ * Cross-site request forgery refused by ORIGIN, for a router whose cookie-carried writes do not all send a token.
+ *
+ * A write is refused when a session COOKIE could have authenticated it (an unsafe method, no `Authorization`, the
+ * cookie present) and a browser says another site caused it — Fetch Metadata first, `Origin` exactly otherwise (see
+ * `Csrf.crossSite`). The deployment's own origins pass, and so do the ones a space credential on the request declares:
+ * a published site calling its own space is not forging anything. A client that is not a browser sends neither header
+ * and passes, as does anything with a bearer — neither has a victim's cookie to borrow.
+ *
+ * This is the guard OWASP calls Fetch Metadata / origin verification. It is what a token is for, without a token: the
+ * difference is only which clients can satisfy it, and every legitimate one here already does.
+ */
+export declare const createOriginGuardMiddleware: (csrf: Csrf, { allowedFor, exempt, errorKey }?: OriginGuardOptions) => (req: AuthedRequest, res: JsonResponse, next: () => void) => void;

package/dist/core/handlers/csrfMiddleware.js

@@ -1,4 +1,4 @@
-import { csrfFailureMessage } from "../auth/csrf.js";
+import { carrierOf, csrfFailureMessage } from "../auth/csrf.js";
 //#region src/core/handlers/csrfMiddleware.ts
 /**
 * The CSRF check as middleware, for a deployment with a router.
@@ -11,14 +11,11 @@ import { csrfFailureMessage } from "../auth/csrf.js";
 * 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
-	})) {
+	if (exempt?.(req.path) || !csrf.required(carrierOf(req))) {
 		next();
 		return;
 	}
-	const result = csrf.verify(req, cookies.resolveSessionToken(req));
+	const result = csrf.verify(carrierOf(req), cookies.resolveSessionToken(req));
 	if (result.ok) {
 		next();
 		return;
@@ -28,5 +25,32 @@ var createCsrfMiddleware = (csrf, cookies, { exempt, errorKey = "message" } = {}
 		reason: result.reason
 	});
 };
+/**
+* Cross-site request forgery refused by ORIGIN, for a router whose cookie-carried writes do not all send a token.
+*
+* A write is refused when a session COOKIE could have authenticated it (an unsafe method, no `Authorization`, the
+* cookie present) and a browser says another site caused it — Fetch Metadata first, `Origin` exactly otherwise (see
+* `Csrf.crossSite`). The deployment's own origins pass, and so do the ones a space credential on the request declares:
+* a published site calling its own space is not forging anything. A client that is not a browser sends neither header
+* and passes, as does anything with a bearer — neither has a victim's cookie to borrow.
+*
+* This is the guard OWASP calls Fetch Metadata / origin verification. It is what a token is for, without a token: the
+* difference is only which clients can satisfy it, and every legitimate one here already does.
+*/
+var createOriginGuardMiddleware = (csrf, { allowedFor, exempt, errorKey = "message" } = {}) => (req, res, next) => {
+	if (exempt?.(req.path) || !csrf.required(carrierOf(req))) {
+		next();
+		return;
+	}
+	const allowed = allowedFor?.(req);
+	if (allowed === true || !csrf.crossSite(carrierOf(req), allowed ?? [])) {
+		next();
+		return;
+	}
+	res.status(403).json({
+		[errorKey]: csrfFailureMessage.foreign,
+		reason: "foreign"
+	});
+};
 //#endregion
-export { createCsrfMiddleware };
+export { createCsrfMiddleware, createOriginGuardMiddleware };

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

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

package/dist/core/handlers/oauthRouteHandlers.js

@@ -1,7 +1,8 @@
+import { serverLog } from "../../helpers/serverLog.js";
 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 { handleAuthorizeStart, handleAuthorizeSubmit } from "../oauth/authorize.js";
 import { handleRevoke, handleToken } from "../oauth/token.js";
 //#region src/core/handlers/oauthRouteHandlers.ts
 /**
@@ -51,7 +52,8 @@ var asRequest = (req) => {
 		headers: req.headers,
 		hostname: req.hostname,
 		protocol: protocol === "http" ? "http" : "https",
-		query: req.query ?? {}
+		query: req.query ?? {},
+		...req.ip ? { ip: req.ip } : {}
 	};
 };
 /** Query first, body second: a field posted by the grant form wins over one the client left in the URL. */
@@ -79,7 +81,7 @@ var createOAuthRouteHandlers = ({ config, onError }) => {
 				method,
 				path
 			});
-			else console.error(`[oauth] ${method} ${path} failed:`, error);
+			else serverLog.error("oauth", `${method} ${path} failed`, error);
 			sendErrorJson(asHelpers(res), 500, "server_error", "The authorization server failed to answer.");
 		}
 	};

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

@@ -12,7 +12,7 @@ export interface SocialRouteHandlersOptions {
      * 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. */
+    /** Reports a callback that threw. Without it the failure goes to the server log at `error`; the caller still gets a 500. */
     onError?: (error: unknown, context: {
         method: string;
         path: string;

package/dist/core/handlers/socialRouteHandlers.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 //#region src/core/handlers/socialRouteHandlers.ts
 /**
 * A provider id from the request.
@@ -35,7 +36,7 @@ var createSocialAuthRouteHandlers = ({ social, cookies, issueSession, onError })
 			onError(error, context);
 			return;
 		}
-		console.error(`[auth] ${context.method} ${context.path} failed:`, error);
+		serverLog.error("auth", `${context.method} ${context.path} failed`, error);
 	};
 	return [
 		{

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

@@ -4,4 +4,12 @@ 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) => Omit<C, 'signal'>;
-export declare const makeHandler: <C extends BaseContext>(label: string, buildContext: BuildContext<C>, stages: Stage<C>[], compressionConfig?: SSRServerConfig["compression"]) => Handler;
+export type HandlerOptions = {
+    compression?: SSRServerConfig['compression'];
+    /**
+     * The paths that may switch protocols. An upgrade anywhere else is refused before the pipeline runs: a WebSocket
+     * opened on a page's address would otherwise render the page — and count a visit — to answer a socket.
+     */
+    upgrades?: (path: string) => boolean;
+};
+export declare const makeHandler: <C extends BaseContext>(label: string, buildContext: BuildContext<C>, stages: Stage<C>[], { compression: compressionConfig, upgrades }?: HandlerOptions) => Handler;

package/dist/core/http/dispatcher.js

@@ -1,5 +1,7 @@
+import { isLogged, serverLog } from "../../helpers/serverLog.js";
 import { clientIp, parseRequest } from "../requestParser.js";
 import { applySecurityHeaders } from "./securityHeaders.js";
+import { socketResponse } from "./socketResponse.js";
 import { resolveCompression } from "../../helpers/compress.js";
 import { buildResponseHelpers } from "../../helpers/buildResponseHelpers.js";
 //#region src/core/http/dispatcher.ts
@@ -11,7 +13,7 @@ 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, compression) => {
+var runPipeline = async (raw, rawRes, buildContext, stages, server, compression, upgrade) => {
 	const startedAt = Date.now();
 	const req = parseRequest(raw);
 	const res = buildResponseHelpers(rawRes, req.headers["accept-encoding"], compression);
@@ -33,13 +35,16 @@ var runPipeline = async (raw, rawRes, buildContext, stages, server, compression)
 	});
 	const ctx = {
 		...buildContext(raw, rawRes, req, res),
-		signal: controller.signal
+		signal: controller.signal,
+		...upgrade ? { upgrade } : {}
 	};
 	const logger = ctx.config.logger;
 	const ip = logger ? clientIp(raw, req) : "";
 	const logRequest = (error) => {
 		if (!logger) return;
 		const status = statusOf(rawRes, res);
+		const failed = !!error || status >= 500;
+		if (!isLogged(ctx.config.logLevel ?? "error", failed ? "error" : "info")) return;
 		logger({
 			kind: "request",
 			server,
@@ -72,17 +77,39 @@ var runPipeline = async (raw, rawRes, buildContext, stages, server, compression)
 		throw error;
 	}
 };
-var makeHandler = (label, buildContext, stages, compressionConfig) => {
+var pathOf = (url) => (url ?? "/").split("?")[0];
+var makeHandler = (label, buildContext, stages, { compression: compressionConfig, upgrades } = {}) => {
 	const compression = resolveCompression(compressionConfig);
-	return (raw, rawRes) => {
-		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" });
-				rawRes.end("Internal Server Error");
-			} catch {}
-		});
+	const fail = (rawRes) => (err) => {
+		serverLog.error(label, "Unhandled error", err);
+		try {
+			if (!rawRes.headersSent) rawRes.writeHead(500, { "Content-Type": "text/plain" });
+			rawRes.end("Internal Server Error");
+		} catch {}
+	};
+	const handler = (raw, rawRes) => {
+		runPipeline(raw, rawRes, buildContext, stages, label, compression).catch(fail(rawRes));
+	};
+	if (upgrades) handler.upgrade = (raw, socket, head) => {
+		const rawRes = socketResponse(socket);
+		if (!upgrades(pathOf(raw.url))) {
+			rawRes.writeHead(404, { "Content-Type": "text/plain" });
+			rawRes.end("Not Found");
+			return;
+		}
+		const upgrade = {
+			socket,
+			head,
+			taken: false
+		};
+		runPipeline(raw, rawRes, buildContext, stages, label, compression, upgrade).then(() => {
+			if (!upgrade.taken && !rawRes.writableFinished) {
+				rawRes.writeHead(404, { "Content-Type": "text/plain" });
+				rawRes.end("Not Found");
+			}
+		}).catch(fail(rawRes));
 	};
+	return handler;
 };
 //#endregion
 export { makeHandler };

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

@@ -7,5 +7,8 @@ import { SSRRequest } from '@plitzi/sdk-shared';
  * 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;
+/**
+ * Same-origin only: absolute URLs and protocol-relative `//host` are refused, to avoid an open redirect — and so is
+ * `/\host`, which a browser reads as `//host`.
+ */
+export declare const safeRedirectTarget: (req: SSRRequest, param?: string) => string;

package/dist/core/http/navigation.js

@@ -7,10 +7,13 @@
 * 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 : "/";
+/**
+* Same-origin only: absolute URLs and protocol-relative `//host` are refused, to avoid an open redirect — and so is
+* `/\host`, which a browser reads as `//host`.
+*/
+var safeRedirectTarget = (req, param = "redirect") => {
+	const target = req.query[param];
+	return target && target.startsWith("/") && !/^\/[\\/]/u.test(target) ? target : "/";
 };
 //#endregion
 export { isNavigation, safeRedirectTarget };

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

@@ -0,0 +1,18 @@
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+import { Duplex } from 'node:stream';
+/** A request asking to switch protocols, as the transport handed it over: the raw socket, and what was read past the headers. */
+export type UpgradeRequest = {
+    socket: Duplex;
+    head: Buffer;
+    /** Set by the stage that switched protocols: from then on the socket is its connection, not an HTTP response. */
+    taken: boolean;
+};
+/**
+ * An HTTP response written straight to a socket — what an upgrade request gets when it is NOT upgraded.
+ *
+ * An upgrade arrives with no `ServerResponse`: node hands over the socket and expects whoever listens to speak for
+ * it. Every stage of the pipeline writes to a `RawResponse`, so this is one: a refusal (a 403, a 404, a redirect)
+ * reaches the client as the stage wrote it, and the socket closes after it — a connection that asked to switch
+ * protocols and was answered in HTTP has nothing left to say.
+ */
+export declare const socketResponse: (socket: Duplex) => RawResponse;

package/dist/core/http/socketResponse.js

@@ -0,0 +1,59 @@
+import { STATUS_CODES } from "node:http";
+//#region src/core/http/socketResponse.ts
+/**
+* An HTTP response written straight to a socket — what an upgrade request gets when it is NOT upgraded.
+*
+* An upgrade arrives with no `ServerResponse`: node hands over the socket and expects whoever listens to speak for
+* it. Every stage of the pipeline writes to a `RawResponse`, so this is one: a refusal (a 403, a 404, a redirect)
+* reaches the client as the stage wrote it, and the socket closes after it — a connection that asked to switch
+* protocols and was answered in HTTP has nothing left to say.
+*/
+var socketResponse = (socket) => {
+	const headers = {};
+	const body = [];
+	let statusCode = 200;
+	let headersSent = false;
+	let finished = false;
+	const flush = () => {
+		if (finished) return;
+		finished = true;
+		headersSent = true;
+		const payload = Buffer.concat(body);
+		const lines = Object.entries({
+			...headers,
+			Connection: "close",
+			"Content-Length": payload.length
+		}).flatMap(([name, value]) => (Array.isArray(value) ? value : [value]).map((entry) => `${name}: ${String(entry)}`));
+		const head = `HTTP/1.1 ${statusCode} ${STATUS_CODES[statusCode] ?? ""}\r\n${lines.join("\r\n")}\r\n\r\n`;
+		socket.end(Buffer.concat([Buffer.from(head), payload]));
+	};
+	return {
+		get headersSent() {
+			return headersSent;
+		},
+		get statusCode() {
+			return statusCode;
+		},
+		get writableFinished() {
+			return finished;
+		},
+		setHeader: (name, value) => {
+			headers[name] = value;
+		},
+		getHeaders: () => ({ ...headers }),
+		writeHead: (code, extra) => {
+			statusCode = code;
+			Object.assign(headers, extra);
+		},
+		write: (chunk) => {
+			body.push(Buffer.from(chunk));
+		},
+		end: (chunk) => {
+			if (chunk !== void 0) body.push(Buffer.from(chunk));
+			flush();
+		},
+		once: (_event, listener) => socket.once("close", listener)
+	};
+};
+//#endregion
+export { socketResponse };

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

@@ -0,0 +1,26 @@
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+export type EventStream = {
+    /** Sends one event. Silently drops once the socket is gone — writing into a closed peer is not an error. */
+    send: (event: string, data: unknown) => void;
+    /** Ends the stream and stops the heartbeat. */
+    close: () => void;
+    /** Whether the peer is still there. */
+    isOpen: () => boolean;
+};
+export type EventStreamOptions = {
+    /** Called once when the peer is found gone — a failed write, or a peer that stopped reading. */
+    onAbort: () => void;
+    /** Headers besides the ones every event stream sends. */
+    headers?: Record<string, string>;
+    /** What an `EventSource` should wait before reconnecting, in milliseconds. */
+    retryMs: number;
+};
+/**
+ * Opens a Server-Sent Events response — an action's progress, a realtime channel.
+ *
+ * Written straight to the RAW response, never through the response helpers: those compress the body, set a
+ * Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
+ * thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
+ * until its buffer fills and turns a live stream into one late burst.
+ */
+export declare const openEventStream: (raw: RawResponse, { onAbort, headers, retryMs }: EventStreamOptions) => EventStream;