@openlup/platform 0.0.0 → 0.15.0

package/dist/data/supabaseClientFactory.d.ts

@@ -0,0 +1,34 @@
+/** Structural shape of the supabase-js `createClient` we depend on (injection seam for tests). */
+export type SupabaseCreateClient = (url: string, key: string, options?: {
+    auth?: {
+        persistSession?: boolean;
+        autoRefreshToken?: boolean;
+    };
+    global?: {
+        headers?: Record<string, string>;
+    };
+}) => unknown;
+export interface SupabaseDataGatewayEnv {
+    /** Project URL (SUPABASE_URL / VITE_SUPABASE_URL). */
+    url: string;
+    /** Anon/publishable key — used for actor (RLS-bound) clients. */
+    anonKey: string;
+    /** Service-role key — used for elevated (RLS-bypassing) clients. */
+    serviceRoleKey: string;
+}
+/** Read the gateway env using the same precedence the inline sites use today. */
+export declare function readSupabaseDataGatewayEnv(env: Record<string, string | undefined>): SupabaseDataGatewayEnv | null;
+/** Read env for actor-only gateway consumers. Does not require the elevated service-role key. */
+export declare function readSupabaseActorDataGatewayEnv(env: Record<string, string | undefined>): SupabaseDataGatewayEnv | null;
+/**
+ * Build an elevated (service-role) supabase client — byte-identical to the inline
+ * `createClient(env.url, env.serviceRoleKey, { auth: { persistSession: false, autoRefreshToken: false } })`
+ * shape the BFF handlers use today.
+ */
+export declare function createServiceClient(env: SupabaseDataGatewayEnv, factory: SupabaseCreateClient): unknown;
+/**
+ * Build an actor (RLS-bound) supabase client — anon key + the actor's Bearer access token, matching
+ * the inline `createAdminAuthClient` / `createCustomerClient` shape. When no token is supplied the
+ * global Authorization header is omitted (identical to the inline `accessToken ? {...} : {}`).
+ */
+export declare function createActorClient(env: SupabaseDataGatewayEnv, accessToken: string | null, factory: SupabaseCreateClient): unknown;

package/dist/data/supabaseClientFactory.js

@@ -0,0 +1,56 @@
+// Supabase client factory for the DataGatewayPort.
+//
+// ONE canonical definition of the two supabase-js client shapes BFF handlers need:
+//   - SERVICE-ROLE client (elevated, RLS-bypassing) — `createClient(url, serviceRoleKey, {auth:{...}})`
+//   - ACTOR client (RLS-bound via a Bearer access token)  — anon key + `Authorization: Bearer <jwt>`
+// Both use one exact option shape
+// (`auth: { persistSession: false, autoRefreshToken: false }`, plus the actor's global Authorization
+// header). The supabase-js `createClient`
+// is always supplied by the application's composition root, so this package carries no SDK import
+// and the adapter stays unit-testable without network.
+/** Read the gateway env using the same precedence the inline sites use today. */
+export function readSupabaseDataGatewayEnv(env) {
+    const url = env.SUPABASE_URL ?? env.VITE_SUPABASE_URL;
+    const anonKey = env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+        env.VITE_SUPABASE_ANON_KEY ??
+        env.SUPABASE_ANON_KEY;
+    const serviceRoleKey = env.SUPABASE_SERVICE_ROLE_KEY;
+    // anonKey is only needed for actor clients; service-role work needs only url + serviceRoleKey.
+    // We require url + serviceRoleKey (the elevated path the default bundle uses); anonKey may be
+    // empty for service-only deployments and is validated lazily when an actor client is requested.
+    return url && serviceRoleKey ? { url, anonKey: anonKey ?? "", serviceRoleKey } : null;
+}
+/** Read env for actor-only gateway consumers. Does not require the elevated service-role key. */
+export function readSupabaseActorDataGatewayEnv(env) {
+    const url = env.SUPABASE_URL ?? env.VITE_SUPABASE_URL;
+    const anonKey = env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+        env.VITE_SUPABASE_ANON_KEY ??
+        env.SUPABASE_ANON_KEY;
+    return url && anonKey ? { url, anonKey, serviceRoleKey: env.SUPABASE_SERVICE_ROLE_KEY ?? "" } : null;
+}
+/**
+ * Build an elevated (service-role) supabase client — byte-identical to the inline
+ * `createClient(env.url, env.serviceRoleKey, { auth: { persistSession: false, autoRefreshToken: false } })`
+ * shape the BFF handlers use today.
+ */
+export function createServiceClient(env, factory) {
+    return factory(env.url, env.serviceRoleKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+    });
+}
+/**
+ * Build an actor (RLS-bound) supabase client — anon key + the actor's Bearer access token, matching
+ * the inline `createAdminAuthClient` / `createCustomerClient` shape. When no token is supplied the
+ * global Authorization header is omitted (identical to the inline `accessToken ? {...} : {}`).
+ */
+export function createActorClient(env, accessToken, factory) {
+    if (!env.anonKey) {
+        throw new Error("supabase_data_gateway_actor_requires_anon_key");
+    }
+    return factory(env.url, env.anonKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+        global: {
+            headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
+        },
+    });
+}

package/dist/data/supabaseGateway.d.ts

@@ -0,0 +1,22 @@
+import type { DataGatewayPort } from "@openlup/core/platform-runtime";
+import { type SupabaseCreateClient, type SupabaseDataGatewayEnv } from "./supabaseClientFactory.js";
+type ActorClaims = {
+    sub?: string;
+    role?: string;
+} | null;
+export interface SupabaseDataGatewayOptions {
+    /** The supabase-js `createClient` (tests pass a stub). */
+    createClientImpl: SupabaseCreateClient;
+    /**
+     * Resolve an actor's Bearer access token from their claims. The port contract carries only
+     * `{ sub, role }`, but RLS needs the raw JWT; call sites that have the request token bind it here.
+     * Returns null → anon (RLS-bound but unauthenticated) client.
+     */
+    resolveAccessToken?: (claims: ActorClaims) => string | null;
+}
+/**
+ * Build a supabase-backed DataGatewayPort from resolved env. Pure: no client is created until a
+ * port method runs work (matches the per-request creation the inline sites do today).
+ */
+export declare function createSupabaseDataGateway(env: SupabaseDataGatewayEnv, options: SupabaseDataGatewayOptions): DataGatewayPort;
+export {};

package/dist/data/supabaseGateway.js

@@ -0,0 +1,49 @@
+// Supabase adapter for the platform-runtime DataGatewayPort.
+//
+// Centralizes the two persistence access modes the BFF handlers build inline today:
+//   - asService(work): elevated, RLS-bypassing — a service-role client (the default bundle's path).
+//   - asActor(claims, work): RLS-bound — an anon client carrying the actor's Bearer access token, so
+//     RLS evaluates the request as that principal (UUID-keep: claims.sub IS the supabase auth uuid).
+// The work callback receives the concrete supabase client (typed `unknown` per the port contract;
+// consumers cast to their narrow read/write surface). Behavior is byte-identical to the inline
+// `createClient(...)` sites this replaces — same option shape, same Authorization header — so the
+// default vercel-supabase bundle stays unchanged (golden-master byte-identical).
+//
+// POOLING SEMANTICS (documented, no behavior change):
+//   - Serverless (vercel-supabase): each invocation is short-lived; supabase-js talks to PostgREST
+//     over HTTP (PgBouncer in transaction-mode behind the scenes), so there is no long-lived pool to
+//     manage — a fresh client per asActor/asService call matches the current per-request creation and
+//     is correct for transaction-pooled connections (no session-level state assumed).
+//   - Long-running Node (node-supabase): the same supabase-js HTTP path applies; a direct-PG gateway
+//     (node-postgres) would instead hold a standard `pg.Pool` and run asActor work inside a
+//     `BEGIN; SET LOCAL request.jwt.claims = ...; ... COMMIT` tx-per-request for RLS. That is the
+//     MigrationRunner/postgres band's concern; this supabase adapter stays HTTP-pooled either way.
+//
+// asActor honors the access token supplied via `options.resolveAccessToken(claims)` (defaults to the
+// claims' own bearer if present) so RLS is enforced; when no token resolves it falls back to an anon
+// client (RLS still applies, just unauthenticated) rather than silently elevating — fail-safe.
+import { createActorClient, createServiceClient, } from "./supabaseClientFactory.js";
+/**
+ * Build a supabase-backed DataGatewayPort from resolved env. Pure: no client is created until a
+ * port method runs work (matches the per-request creation the inline sites do today).
+ */
+export function createSupabaseDataGateway(env, options) {
+    const resolveAccessToken = options.resolveAccessToken ?? defaultResolveAccessToken;
+    return {
+        async asService(work) {
+            const client = createServiceClient(env, options.createClientImpl);
+            return work(client);
+        },
+        async asActor(claims, work) {
+            const accessToken = resolveAccessToken(claims);
+            const client = createActorClient(env, accessToken, options.createClientImpl);
+            return work(client);
+        },
+    };
+}
+// Default token resolver: the port's claims shape doesn't carry a raw JWT, so without an injected
+// resolver an actor request maps to an anon (unauthenticated, still RLS-bound) client. Call sites
+// that hold the request bearer inject `resolveAccessToken` to make RLS see the real principal.
+function defaultResolveAccessToken(_claims) {
+    return null;
+}

package/dist/http/deadline.d.ts

@@ -0,0 +1,20 @@
+import type { HttpRequest, HttpResponse } from "./types.js";
+export declare const NODE_HTTP_TIMEOUT_CODE = "NODE_HTTP_TIMEOUT";
+export interface HttpDeadlineOptions {
+    req: HttpRequest;
+    res: HttpResponse;
+    durationMs: number;
+    run: () => Promise<unknown> | unknown;
+    onLateError?: (error: unknown) => void;
+}
+/**
+ * Run one Node HTTP admission from the instant before lazy loading/adaptation.
+ *
+ * A timeout before headers commit gets one minimal JSON 504. After headers are
+ * committed we cannot change the status safely, so the response is destroyed.
+ * The invocation promise remains observed, preventing a late rejection from
+ * becoming an unhandled rejection or a second response.
+ */
+export declare function runWithHttpDeadline(options: HttpDeadlineOptions): Promise<void>;
+/** Send a response before closing its request input, so the status is deliverable. */
+export declare function closeInputAfterResponse(req: HttpRequest, res: HttpResponse): void;

package/dist/http/deadline.js

@@ -0,0 +1,93 @@
+// Bounded request/response lifecycle for the Node HTTP adapter.
+//
+// This owns transport cancellation only. It gives handlers a cooperative
+// AbortSignal, but cannot roll back downstream work that ignores it.
+export const NODE_HTTP_TIMEOUT_CODE = "NODE_HTTP_TIMEOUT";
+/**
+ * Run one Node HTTP admission from the instant before lazy loading/adaptation.
+ *
+ * A timeout before headers commit gets one minimal JSON 504. After headers are
+ * committed we cannot change the status safely, so the response is destroyed.
+ * The invocation promise remains observed, preventing a late rejection from
+ * becoming an unhandled rejection or a second response.
+ */
+export async function runWithHttpDeadline(options) {
+    const { req, res, durationMs, run, onLateError } = options;
+    if (!Number.isSafeInteger(durationMs) || durationMs <= 0 || durationMs > 2_147_483_647) {
+        throw new Error("invalid_node_http_deadline");
+    }
+    const controller = new AbortController();
+    // Node 24 exposes IncomingMessage.signal as a getter without a setter. Keep
+    // that host-native property untouched and use the portable adapter seam.
+    req.abortSignal = controller.signal;
+    const eventedReq = req;
+    const eventedRes = res;
+    const abortForClose = () => controller.abort();
+    eventedReq.once?.("aborted", abortForClose);
+    eventedRes.once?.("close", abortForClose);
+    let expired = false;
+    let finishTimeout;
+    const timeout = new Promise((resolve) => { finishTimeout = resolve; });
+    const timer = setTimeout(() => {
+        expired = true;
+        controller.abort();
+        if (res.destroyed || res.writableEnded) {
+            destroyInput(req);
+            return finishTimeout?.();
+        }
+        if (!res.headersSent && !res.writableEnded) {
+            closeInputAfterResponse(req, res);
+            res.statusCode = 504;
+            res.setHeader("content-type", "application/json; charset=utf-8");
+            res.end(JSON.stringify({ ok: false, error: { code: NODE_HTTP_TIMEOUT_CODE, message: "Request timed out" } }));
+            sealLateWrites(res);
+        }
+        else if (!res.writableEnded) {
+            sealLateWrites(res);
+            res.destroy?.();
+            destroyInput(req);
+        }
+        finishTimeout?.();
+    }, durationMs);
+    const invocation = Promise.resolve().then(run);
+    // Keep a late completion/rejection observed after timeout. It must never get a
+    // chance to write a second envelope, and its raw value is not client output.
+    void invocation.catch((error) => {
+        if (expired)
+            onLateError?.(error);
+    });
+    try {
+        await Promise.race([invocation.then(() => undefined), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+        eventedReq.removeListener?.("aborted", abortForClose);
+        eventedRes.removeListener?.("close", abortForClose);
+    }
+}
+/** Send a response before closing its request input, so the status is deliverable. */
+export function closeInputAfterResponse(req, res) {
+    const evented = res;
+    let closed = false;
+    const destroy = () => {
+        if (closed)
+            return;
+        closed = true;
+        evented.removeListener?.("finish", destroy);
+        evented.removeListener?.("close", destroy);
+        destroyInput(req);
+    };
+    evented.once?.("finish", destroy);
+    evented.once?.("close", destroy);
+}
+function destroyInput(req) {
+    req.destroy?.();
+}
+/** Refuse late handler writes after a deadline response has committed. */
+function sealLateWrites(res) {
+    const mutable = res;
+    mutable.write = () => false;
+    mutable.writeHead = () => mutable;
+    mutable.end = () => mutable;
+    mutable.setHeader = () => mutable;
+}

package/dist/http/index.d.ts

@@ -0,0 +1,6 @@
+export type { EntrypointLoader, HttpHandler, HttpRequest, HttpResponse } from "./types.js";
+export { DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES, NodeRequestAbortedError, NodeRequestBodyTooLargeError, adaptRequest, decorateRequest, decorateResponse, isRawStreamEntrypoint, isWebhookPath, pathnameOf, } from "./requestAdapter.js";
+export { NODE_HTTP_TIMEOUT_CODE, closeInputAfterResponse, runWithHttpDeadline, type HttpDeadlineOptions, } from "./deadline.js";
+export { applySecurityHeaders, contentTypeFor, looksLikeAsset, serveSpaStatic, type NodeSecurityHeaderPolicy, type StaticAssetReader, } from "./security.js";
+export { createDistStaticReader } from "./staticAssets.js";
+export { createNodeHttpRuntime, createRequestHandler, type HttpEntrypointRegistration, type HttpPathEntrypoint, type NodeCsrFallback, type NodeHttpRuntimeOptions, type NodeLegacyRedirect, } from "./runtime.js";

package/dist/http/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES, NodeRequestAbortedError, NodeRequestBodyTooLargeError, adaptRequest, decorateRequest, decorateResponse, isRawStreamEntrypoint, isWebhookPath, pathnameOf, } from "./requestAdapter.js";
+export { NODE_HTTP_TIMEOUT_CODE, closeInputAfterResponse, runWithHttpDeadline, } from "./deadline.js";
+export { applySecurityHeaders, contentTypeFor, looksLikeAsset, serveSpaStatic, } from "./security.js";
+export { createDistStaticReader } from "./staticAssets.js";
+export { createNodeHttpRuntime, createRequestHandler, } from "./runtime.js";

package/dist/http/requestAdapter.d.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HttpRequest, HttpResponse } from "./types.js";
+export declare const DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES = 1048576;
+export declare class NodeRequestBodyTooLargeError extends Error {
+    constructor();
+}
+export declare class NodeRequestAbortedError extends Error {
+    constructor();
+}
+/** A path is a webhook iff it contains a `/webhooks/` segment. */
+export declare function isWebhookPath(pathname: string): boolean;
+/**
+ * The PLATFORM's stream-first standalone entrypoints: they read the raw stream
+ * themselves, so the runtime must never pre-parse their body.
+ *
+ * A deployment's own stream-first endpoint is NOT listed here. It declares
+ * `rawStream: true` on its `HttpEntrypointRegistration` and the runtime passes that
+ * decision to `adaptRequest` directly — which is what stops this publishable list
+ * from having to name a path only that deployment owns.
+ */
+export declare function isRawStreamEntrypoint(pathname: string): boolean;
+export declare function pathnameOf(req: IncomingMessage): string;
+/**
+ * Decorate a Node response with Vercel's status/json/send/redirect sugar (productionized from the
+ * dev shim's decorateResponse — identical semantics).
+ */
+export declare function decorateResponse(res: ServerResponse): HttpResponse;
+/**
+ * Adapt a Node IncomingMessage into the Vercel request shape, honoring the raw-body invariant:
+ *  - raw-stream entrypoints (process/csp/feedback): stream left intact, NO req.body;
+ *  - everything else: raw bytes buffered + re-exposed as async-iterable (so readRawBody sees the
+ *    EXACT bytes for any signature-verifying route, webhook-segment or not) AND req.body = parsed JSON.
+ */
+export declare function adaptRequest(req: IncomingMessage, pathname: string, 
+/** Explicit override for a caller that knows the entrypoint's body contract (see above). */
+rawStream?: boolean, bufferedBodyLimitBytes?: number): Promise<HttpRequest>;
+/** Narrow a raw IncomingMessage to HttpRequest at the server boundary (query/cookies set in adapt). */
+export declare function decorateRequest(req: IncomingMessage): HttpRequest;

package/dist/http/requestAdapter.js

@@ -0,0 +1,203 @@
+// Node request/response adaptation to the hosted-function request shape for the HttpRuntimePort.
+//
+// Owns the RAW-BODY INVARIANT: every buffered request gets the exact bytes re-exposed as an
+// async-iterable (so raw-body signature verification works for ANY route, including ones outside a
+// `/webhooks/` segment) while still setting a parsed JSON req.body; stream-first standalone
+// entrypoints keep their live stream and NO req.body.
+export const DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES = 1_048_576;
+export class NodeRequestBodyTooLargeError extends Error {
+    constructor() {
+        super("node_request_body_too_large");
+    }
+}
+export class NodeRequestAbortedError extends Error {
+    constructor() {
+        super("node_request_aborted");
+    }
+}
+/** A path is a webhook iff it contains a `/webhooks/` segment. */
+export function isWebhookPath(pathname) {
+    return pathname.includes("/webhooks/");
+}
+/**
+ * The PLATFORM's stream-first standalone entrypoints: they read the raw stream
+ * themselves, so the runtime must never pre-parse their body.
+ *
+ * A deployment's own stream-first endpoint is NOT listed here. It declares
+ * `rawStream: true` on its `HttpEntrypointRegistration` and the runtime passes that
+ * decision to `adaptRequest` directly — which is what stops this publishable list
+ * from having to name a path only that deployment owns.
+ */
+export function isRawStreamEntrypoint(pathname) {
+    return pathname === "/api/csp-report";
+}
+export function pathnameOf(req) {
+    return new URL(req.url ?? "/", "http://node.local").pathname;
+}
+function parseQuery(req) {
+    const url = new URL(req.url ?? "/", "http://node.local");
+    const query = {};
+    for (const key of url.searchParams.keys()) {
+        if (key in query)
+            continue;
+        const all = url.searchParams.getAll(key);
+        query[key] = all.length > 1 ? all : all[0];
+    }
+    return query;
+}
+function parseCookies(req) {
+    const header = req.headers.cookie;
+    if (!header)
+        return {};
+    const out = {};
+    for (const part of header.split(";")) {
+        const idx = part.indexOf("=");
+        if (idx < 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key)
+            out[key] = decodeURIComponent(value);
+    }
+    return out;
+}
+/** Buffer the request stream once into a single Buffer (GET/HEAD => empty). */
+async function bufferBody(req, maxBytes) {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method === "GET" || method === "HEAD")
+        return Buffer.alloc(0);
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            req.removeListener("data", onData);
+            req.removeListener("end", onEnd);
+            req.removeListener("error", onError);
+            req.abortSignal?.removeEventListener("abort", onAbort);
+            if (result instanceof Error)
+                reject(result);
+            else
+                resolve(result);
+        };
+        const onData = (chunk) => {
+            const bytesChunk = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            bytes += bytesChunk.length;
+            if (bytes > maxBytes) {
+                finish(new NodeRequestBodyTooLargeError());
+                return;
+            }
+            chunks.push(bytesChunk);
+        };
+        const onEnd = () => finish(Buffer.concat(chunks));
+        const onError = (error) => finish(error);
+        const onAbort = () => finish(new NodeRequestAbortedError());
+        if (req.abortSignal?.aborted)
+            return onAbort();
+        req.on("data", onData);
+        req.once("end", onEnd);
+        req.once("error", onError);
+        req.abortSignal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Re-expose a fixed Buffer as the request's async-iterable so readRawBody sees the EXACT bytes. */
+function reexposeRawStream(req, raw) {
+    req[Symbol.asyncIterator] =
+        async function* () {
+            yield raw;
+        };
+}
+/** Best-effort JSON parse of a buffered body for handlers that read `req.body`. */
+function parseJsonBody(raw, contentType) {
+    if (raw.length === 0)
+        return undefined;
+    const text = raw.toString("utf8").trim();
+    if (!text)
+        return undefined;
+    if (contentType.includes("application/json") || text.startsWith("{") || text.startsWith("[")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/**
+ * Decorate a Node response with Vercel's status/json/send/redirect sugar (productionized from the
+ * dev shim's decorateResponse — identical semantics).
+ */
+export function decorateResponse(res) {
+    const vres = res;
+    vres.status = function status(code) {
+        res.statusCode = code;
+        return vres;
+    };
+    vres.json = function json(body) {
+        if (!res.hasHeader("content-type")) {
+            res.setHeader("content-type", "application/json; charset=utf-8");
+        }
+        res.end(JSON.stringify(body));
+        return vres;
+    };
+    vres.send = function send(body) {
+        if (Buffer.isBuffer(body) || typeof body === "string") {
+            res.end(body);
+            return vres;
+        }
+        if (!res.hasHeader("content-type")) {
+            res.setHeader("content-type", "application/json; charset=utf-8");
+        }
+        res.end(JSON.stringify(body));
+        return vres;
+    };
+    vres.redirect = function redirect(statusOrUrl, maybeUrl) {
+        const code = typeof statusOrUrl === "number" ? statusOrUrl : 302;
+        const location = typeof statusOrUrl === "number" ? maybeUrl ?? "/" : statusOrUrl;
+        res.statusCode = code;
+        res.setHeader("location", location);
+        res.end();
+        return vres;
+    };
+    return vres;
+}
+/**
+ * Adapt a Node IncomingMessage into the Vercel request shape, honoring the raw-body invariant:
+ *  - raw-stream entrypoints (process/csp/feedback): stream left intact, NO req.body;
+ *  - everything else: raw bytes buffered + re-exposed as async-iterable (so readRawBody sees the
+ *    EXACT bytes for any signature-verifying route, webhook-segment or not) AND req.body = parsed JSON.
+ */
+export async function adaptRequest(req, pathname, 
+/** Explicit override for a caller that knows the entrypoint's body contract (see above). */
+rawStream = isRawStreamEntrypoint(pathname), bufferedBodyLimitBytes = DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES) {
+    const vreq = req;
+    vreq.query = parseQuery(req);
+    vreq.cookies = parseCookies(req);
+    if (rawStream) {
+        // Leave the live stream untouched; the handler reads it itself (formidable / custom readBody).
+        return vreq;
+    }
+    const raw = await bufferBody(vreq, bufferedBodyLimitBytes);
+    const contentType = String(req.headers["content-type"] ?? "");
+    // Re-expose the EXACT bytes as an async-iterable for EVERY buffered request, not only
+    // `/webhooks/` paths. Some signature-verifying routes live outside that segment — e.g.
+    // `/api/bff/communications/integrations/events` calls readRawBody for HMAC verification.
+    // readRawBody is stream-first (isAsyncIterable), so any handler that needs the raw bytes
+    // works; handlers that read req.body still get parsed JSON. The re-exposed iterator is
+    // simply never consumed for routes that don't call readRawBody, so this is a safe superset
+    // of the old `/webhooks/`-only behavior (and not dependent on a fragile path convention).
+    reexposeRawStream(req, raw);
+    vreq.body = parseJsonBody(raw, contentType);
+    return vreq;
+}
+/** Narrow a raw IncomingMessage to HttpRequest at the server boundary (query/cookies set in adapt). */
+export function decorateRequest(req) {
+    const vreq = req;
+    if (!vreq.query)
+        vreq.query = {};
+    return vreq;
+}

package/dist/http/runtime.d.ts

@@ -0,0 +1,83 @@
+import { type Server } from "node:http";
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+import type { EntrypointLoader } from "./types.js";
+import type { BffDispatch, RouteEntry } from "../bff/index.js";
+import { type NodeSecurityHeaderPolicy, type StaticAssetReader } from "./security.js";
+/** One deployment-specific standalone entrypoint, matched by its exact path. */
+export interface HttpEntrypointRegistration {
+    path: string;
+    rawStream?: boolean;
+    maxDurationMs?: number;
+    load: EntrypointLoader;
+}
+/**
+ * One deployment-specific entrypoint matched by a path rule. `match` returns the query values the
+ * entrypoint receives for this path, or null when the path is not its own. The body is buffered.
+ */
+export interface HttpPathEntrypoint {
+    match(pathname: string): Record<string, string> | null;
+    load: EntrypointLoader;
+    /** Request deadline; defaults to 10 seconds. */
+    maxDurationMs?: number;
+}
+export interface NodeLegacyRedirect {
+    source: string;
+    destination: string;
+    permanent: boolean;
+}
+export interface NodeCsrFallback {
+    exactPaths: readonly string[];
+    routeFamilies: readonly string[];
+}
+export interface NodeHttpRuntimeOptions {
+    /** The deployment's BFF route table. */
+    routes: readonly RouteEntry[];
+    /** The dispatcher that matches `routes` (see `createBffDispatcher`). */
+    dispatch: BffDispatch;
+    /** Validated public-route contract supplied by the host composition root. */
+    routing?: {
+        legacyRedirects: readonly NodeLegacyRedirect[];
+        ssgPaths: readonly string[];
+        csrFallback: NodeCsrFallback;
+    };
+    /** Deployment header policy, including the content security policy. */
+    security: NodeSecurityHeaderPolicy;
+    /** robots.txt body for a request host; without it `/robots.txt` is served like any other path. */
+    robotsTxt?: (host: string | undefined) => string;
+    /**
+     * Platform-path standalone handlers: the CSP report sink at `/api/csp-report` and the hosted
+     * BFF router at `/api/bff-router`. A path without a handler is treated like any other path.
+     */
+    entrypoints?: {
+        cspReport?: EntrypointLoader;
+        bffRouter?: EntrypointLoader;
+    };
+    /**
+     * Deployment exact-path handlers, checked after the CSP report entrypoint and before the BFF
+     * router; a later registration replaces an earlier one with the same path.
+     */
+    extraEntrypoints?: readonly HttpEntrypointRegistration[];
+    /** Deployment path-rule handlers checked before the BFF dispatcher, first match wins. */
+    pathEntrypoints?: readonly HttpPathEntrypoint[];
+    /** Deployment path-rule handlers checked after legacy redirects and before static documents. */
+    fallbackPathEntrypoints?: readonly HttpPathEntrypoint[];
+    /** Registry-derived allowlist; undeclared job ids must resolve null. */
+    scheduledEntrypoint?: (jobId: string) => EntrypointLoader | null;
+    /** Explicit host deadlines; missing cells use the bounded defaults below. */
+    durations?: {
+        bff?: number;
+        cspReport?: number;
+        bffRouter?: number;
+        scheduled?: (jobId: string) => number;
+    };
+    /** Static SPA reader; without one, unmatched non-API paths answer 404. */
+    staticReader?: StaticAssetReader;
+    /** Structured error sink (defaults to console.error). */
+    onError?: (context: string, error: unknown) => void;
+}
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export declare function createRequestHandler(options: NodeHttpRuntimeOptions): HttpRuntimePort["handle"];
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export declare function createNodeHttpRuntime(options: NodeHttpRuntimeOptions): HttpRuntimePort & {
+    server: Server | null;
+};