@openlup/platform 0.0.0 → 0.16.0

package/src/data/supabaseClientFactory.ts

@@ -0,0 +1,92 @@
+// 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.
+
+/** 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 function readSupabaseDataGatewayEnv(
+  env: Record<string, string | undefined>,
+): SupabaseDataGatewayEnv | null {
+  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: Record<string, string | undefined>,
+): SupabaseDataGatewayEnv | null {
+  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: SupabaseDataGatewayEnv,
+  factory: SupabaseCreateClient,
+): unknown {
+  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: SupabaseDataGatewayEnv,
+  accessToken: string | null,
+  factory: SupabaseCreateClient,
+): unknown {
+  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/src/data/supabaseGateway.ts

@@ -0,0 +1,76 @@
+// 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 type { DataGatewayPort } from "@openlup/core/platform-runtime";
+import {
+  createActorClient,
+  createServiceClient,
+  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 function createSupabaseDataGateway(
+  env: SupabaseDataGatewayEnv,
+  options: SupabaseDataGatewayOptions,
+): DataGatewayPort {
+  const resolveAccessToken = options.resolveAccessToken ?? defaultResolveAccessToken;
+
+  return {
+    async asService<T>(work: (gateway: unknown) => Promise<T>): Promise<T> {
+      const client = createServiceClient(env, options.createClientImpl);
+      return work(client);
+    },
+
+    async asActor<T>(claims: ActorClaims, work: (gateway: unknown) => Promise<T>): Promise<T> {
+      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: ActorClaims): string | null {
+  return null;
+}

package/src/http/deadline.ts

@@ -0,0 +1,117 @@
+// 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.
+
+import type { HttpRequest, HttpResponse } from "./types.js";
+
+export const NODE_HTTP_TIMEOUT_CODE = "NODE_HTTP_TIMEOUT";
+
+type Destroyable = { destroy?: (error?: Error) => void };
+type Evented = { once?: (event: string, listener: () => void) => unknown; removeListener?: (event: string, listener: () => void) => unknown };
+type WritableResponse = HttpResponse & {
+  write?: (...args: unknown[]) => boolean;
+  writeHead?: (...args: unknown[]) => unknown;
+  end?: (...args: unknown[]) => unknown;
+  setHeader?: (...args: unknown[]) => unknown;
+};
+
+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 async function runWithHttpDeadline(options: HttpDeadlineOptions): Promise<void> {
+  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 as HttpRequest & Evented;
+  const eventedRes = res as HttpResponse & Evented;
+  const abortForClose = () => controller.abort();
+  eventedReq.once?.("aborted", abortForClose);
+  eventedRes.once?.("close", abortForClose);
+
+  let expired = false;
+  let finishTimeout: (() => void) | undefined;
+  const timeout = new Promise<void>((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 as HttpResponse & Destroyable).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: HttpRequest, res: HttpResponse): void {
+  const evented = res as HttpResponse & Evented;
+  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: HttpRequest): void {
+  (req as HttpRequest & Destroyable).destroy?.();
+}
+
+/** Refuse late handler writes after a deadline response has committed. */
+function sealLateWrites(res: HttpResponse): void {
+  const mutable = res as WritableResponse;
+  mutable.write = () => false;
+  mutable.writeHead = () => mutable;
+  mutable.end = () => mutable;
+  mutable.setHeader = () => mutable;
+}

package/src/http/index.ts

@@ -0,0 +1,36 @@
+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/src/http/requestAdapter.ts

@@ -0,0 +1,215 @@
+// 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.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { HttpRequest, HttpResponse } from "./types.js";
+
+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: string): boolean {
+  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: string): boolean {
+  return pathname === "/api/csp-report";
+}
+
+export function pathnameOf(req: IncomingMessage): string {
+  return new URL(req.url ?? "/", "http://node.local").pathname;
+}
+
+function parseQuery(req: IncomingMessage): Record<string, string | string[] | undefined> {
+  const url = new URL(req.url ?? "/", "http://node.local");
+  const query: Record<string, string | string[] | undefined> = {};
+  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: IncomingMessage): Record<string, string> {
+  const header = req.headers.cookie;
+  if (!header) return {};
+  const out: Record<string, string> = {};
+  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: HttpRequest, maxBytes: number): Promise<Buffer> {
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method === "GET" || method === "HEAD") return Buffer.alloc(0);
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (result: Buffer | Error) => {
+      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: Buffer | string) => {
+      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: 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: IncomingMessage, raw: Buffer): void {
+  (req as unknown as { [Symbol.asyncIterator]: () => AsyncIterator<Buffer> })[Symbol.asyncIterator] =
+    async function* () {
+      yield raw;
+    };
+}
+
+/** Best-effort JSON parse of a buffered body for handlers that read `req.body`. */
+function parseJsonBody(raw: Buffer, contentType: string): unknown {
+  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: ServerResponse): HttpResponse {
+  const vres = res as HttpResponse;
+  vres.status = function status(code: number): HttpResponse {
+    res.statusCode = code;
+    return vres;
+  };
+  vres.json = function json(body: unknown): HttpResponse {
+    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: string | Buffer | object): HttpResponse {
+    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: number | string, maybeUrl?: string): HttpResponse {
+    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: IncomingMessage,
+  pathname: string,
+  /** Explicit override for a caller that knows the entrypoint's body contract (see above). */
+  rawStream: boolean = isRawStreamEntrypoint(pathname),
+  bufferedBodyLimitBytes: number = DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES,
+): Promise<HttpRequest> {
+  const vreq = req as HttpRequest;
+  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: IncomingMessage): HttpRequest {
+  const vreq = req as HttpRequest;
+  if (!vreq.query) vreq.query = {};
+  return vreq;
+}