@openlup/platform 0.0.0 → 0.16.0

package/sql/20260901143000_admin_membership_authority_foundation.sql

@@ -0,0 +1,234 @@
+-- Dormant direct human membership authority.
+--
+-- This forward introduces a provider-neutral human principal and its separate
+-- current-panel membership for the direct bundle. It mirrors the managed role,
+-- active/revoked state, provenance, acceptance, revocation, retained identity,
+-- last-human-administrator refusal, and one-row revoke audit semantics. It does
+-- not verify a login, grant browser access, seed a person, or link to the
+-- existing platform_control_operators machine authority. The direct host owns
+-- activation of a future human-login adapter; until then these relations are
+-- deliberately dormant and default-deny for the actor roles.
+
+CREATE TABLE public.platform_human_principals (
+  principal_id uuid PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE public.platform_human_memberships (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  membership_state text NOT NULL CHECK (membership_state IN ('active', 'revoked')),
+  membership_provenance text NOT NULL CHECK (membership_provenance IN ('legacy', 'invitation')),
+  membership_accepted_at timestamptz NOT NULL,
+  membership_revoked_at timestamptz,
+  membership_revoked_by uuid REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  membership_revocation_reason text,
+  CONSTRAINT platform_human_memberships_lifecycle_check CHECK (
+    (membership_state = 'active'
+      AND membership_revoked_at IS NULL
+      AND membership_revoked_by IS NULL
+      AND membership_revocation_reason IS NULL)
+    OR
+    (membership_state = 'revoked'
+      AND membership_revoked_at IS NOT NULL
+      AND membership_revoked_by IS NOT NULL)
+  ),
+  CONSTRAINT platform_human_memberships_distinct_revoker_check
+    CHECK (membership_revoked_by IS NULL OR membership_revoked_by <> principal_id),
+  CONSTRAINT platform_human_memberships_reason_length_check
+    CHECK (membership_revocation_reason IS NULL OR char_length(membership_revocation_reason) <= 1000)
+);
+
+CREATE TABLE public.platform_human_membership_audit_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  target_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  action text NOT NULL CHECK (action = 'revoke'),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  reason text,
+  occurred_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX platform_human_membership_audit_target_idx
+  ON public.platform_human_membership_audit_events(target_principal_id, occurred_at DESC);
+
+REVOKE ALL ON TABLE
+  public.platform_human_principals,
+  public.platform_human_memberships,
+  public.platform_human_membership_audit_events
+FROM PUBLIC, anon, authenticated;
+
+CREATE FUNCTION public.platform_human_membership_is_active(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_membership_is_administrator(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+      AND membership_row.role = 'admin'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_memberships_guard()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_removes_active_human_admin boolean := false;
+  v_other_active_human_admins integer;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    v_removes_active_human_admin := OLD.membership_state = 'active' AND OLD.role = 'admin';
+  ELSE
+    IF (OLD.membership_state, OLD.membership_provenance, OLD.membership_accepted_at,
+        OLD.membership_revoked_at, OLD.membership_revoked_by,
+        OLD.membership_revocation_reason)
+       IS DISTINCT FROM
+       (NEW.membership_state, NEW.membership_provenance, NEW.membership_accepted_at,
+        NEW.membership_revoked_at, NEW.membership_revoked_by,
+        NEW.membership_revocation_reason)
+      AND current_setting('app.platform_human_membership_revoke', true) IS DISTINCT FROM 'true' THEN
+      RAISE EXCEPTION 'platform_human_membership_lifecycle_update_forbidden' USING ERRCODE = '42501';
+    END IF;
+
+    IF OLD.membership_state <> 'active' AND NEW.role IS DISTINCT FROM OLD.role THEN
+      RAISE EXCEPTION 'platform_human_target_membership_inactive' USING ERRCODE = 'P0001';
+    END IF;
+
+    v_removes_active_human_admin := OLD.membership_state = 'active'
+      AND OLD.role = 'admin'
+      AND (NEW.membership_state <> 'active' OR NEW.role <> 'admin');
+  END IF;
+
+  IF v_removes_active_human_admin THEN
+    PERFORM pg_advisory_xact_lock(hashtext('platform_human_memberships_active_admin')::bigint);
+    SELECT count(*)
+      INTO v_other_active_human_admins
+    FROM public.platform_human_memberships
+    WHERE principal_id <> OLD.principal_id
+      AND membership_state = 'active'
+      AND role = 'admin';
+
+    IF v_other_active_human_admins < 1 THEN
+      RAISE EXCEPTION 'platform_human_last_admin_lockout' USING ERRCODE = 'P0001';
+    END IF;
+  END IF;
+
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'platform_human_membership_delete_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER trg_platform_human_memberships_guard
+  BEFORE UPDATE OR DELETE ON public.platform_human_memberships
+  FOR EACH ROW EXECUTE FUNCTION public.platform_human_memberships_guard();
+
+CREATE FUNCTION public.platform_revoke_human_membership(
+  p_actor_principal_id uuid,
+  p_target_principal_id uuid,
+  p_reason text DEFAULT NULL
+)
+RETURNS public.platform_human_memberships
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_target public.platform_human_memberships;
+  v_reason text := NULLIF(btrim(p_reason), '');
+  v_revoked_at timestamptz := clock_timestamp();
+BEGIN
+  IF NOT public.platform_human_membership_is_administrator(p_actor_principal_id) THEN
+    RAISE EXCEPTION 'platform_human_revoke_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  IF p_target_principal_id IS NULL THEN
+    RAISE EXCEPTION 'platform_human_target_required' USING ERRCODE = '22023';
+  END IF;
+
+  IF p_target_principal_id = p_actor_principal_id THEN
+    RAISE EXCEPTION 'platform_human_self_revoke_forbidden' USING ERRCODE = 'P0001';
+  END IF;
+
+  IF v_reason IS NOT NULL AND char_length(v_reason) > 1000 THEN
+    RAISE EXCEPTION 'platform_human_revocation_reason_too_long' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO v_target
+  FROM public.platform_human_memberships
+  WHERE principal_id = p_target_principal_id
+  FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'platform_human_target_not_found' USING ERRCODE = 'P0002';
+  END IF;
+
+  IF v_target.membership_state = 'revoked' THEN
+    RETURN v_target;
+  END IF;
+
+  PERFORM set_config('app.platform_human_membership_revoke', 'true', true);
+
+  UPDATE public.platform_human_memberships
+  SET membership_state = 'revoked',
+      membership_revoked_at = v_revoked_at,
+      membership_revoked_by = p_actor_principal_id,
+      membership_revocation_reason = v_reason
+  WHERE principal_id = p_target_principal_id
+  RETURNING * INTO v_target;
+
+  INSERT INTO public.platform_human_membership_audit_events
+    (actor_principal_id, target_principal_id, action, old_value, new_value, reason, occurred_at)
+  VALUES (
+    p_actor_principal_id,
+    p_target_principal_id,
+    'revoke',
+    jsonb_build_object('membershipState', 'active', 'role', v_target.role),
+    jsonb_build_object(
+      'membershipState', 'revoked',
+      'revokedAt', v_revoked_at,
+      'revokedBy', p_actor_principal_id,
+      'revocationReason', v_reason
+    ),
+    v_reason,
+    v_revoked_at
+  );
+
+  RETURN v_target;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_active(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_administrator(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_memberships_guard()
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text)
+  FROM PUBLIC, anon, authenticated;
+
+COMMENT ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text) IS
+  'Dormant direct-bundle revoke command. Requires an active human administrator, retains the target principal/membership, refuses self and last-admin removal, and records one atomic revoke event.';

package/sql/20261018120000_identity_operator_invitations.sql

@@ -0,0 +1,42 @@
+-- Pending direct operator invitations. Lifecycle commands use the trusted
+-- server transaction lane; this forward adds no function or actor privilege.
+CREATE TABLE public.identity_operator_invitations (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id),
+  invitation_id uuid NOT NULL UNIQUE,
+  email_key text NOT NULL UNIQUE,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  phase text NOT NULL CHECK (phase IN ('invited', 'accepted', 'expired', 'cancelled')),
+  invited_by uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  invited_at timestamptz NOT NULL,
+  expires_at timestamptz NOT NULL,
+  accepted_at timestamptz,
+  closed_at timestamptz,
+  CHECK (email_key = lower(btrim(email_key)) AND NOT email_key = ''),
+  CHECK (expires_at BETWEEN invited_at + interval '60 seconds' AND invited_at + interval '30 days'),
+  CHECK (
+    (phase = 'invited' AND accepted_at IS NULL AND closed_at IS NULL)
+    OR (phase = 'accepted' AND accepted_at IS NOT NULL
+      AND accepted_at BETWEEN invited_at AND expires_at
+      AND NOT accepted_at = expires_at AND closed_at = accepted_at)
+    OR (phase = 'expired' AND accepted_at IS NULL AND closed_at = expires_at)
+    OR (phase = 'cancelled' AND accepted_at IS NULL AND closed_at IS NOT NULL)
+  )
+);
+
+CREATE TABLE public.identity_operator_invitation_events (
+  event_id uuid PRIMARY KEY,
+  invitation_id uuid NOT NULL,
+  principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  action text NOT NULL CHECK (action IN ('issue', 'reissue', 'accept', 'expire', 'cancel')),
+  actor_kind text NOT NULL CHECK (actor_kind IN ('human', 'system')),
+  actor_principal_id uuid REFERENCES public.platform_human_principals(principal_id),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  occurred_at timestamptz NOT NULL,
+  UNIQUE (invitation_id, action),
+  CHECK ((actor_kind = 'human' AND actor_principal_id IS NOT NULL)
+    OR (actor_kind = 'system' AND actor_principal_id IS NULL))
+);
+
+CREATE INDEX identity_operator_invitation_events_target_idx
+  ON public.identity_operator_invitation_events(principal_id, occurred_at DESC);

package/sql/20261018180000_identity_operator_challenges.sql

@@ -0,0 +1,56 @@
+CREATE UNIQUE INDEX platform_human_principals_normalized_email_key
+  ON public.platform_human_principals (lower(btrim(email)));
+
+CREATE TABLE public.operator_identity_challenges (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  principal_id uuid NOT NULL
+    REFERENCES public.platform_human_principals(principal_id),
+  email_fingerprint text NOT NULL,
+  token_hash text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  used_at timestamptz,
+
+  CONSTRAINT operator_identity_challenges_email_fingerprint_check
+    CHECK (
+      length(email_fingerprint) = 64
+      AND translate(
+        email_fingerprint,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_check
+    CHECK (
+      length(token_hash) = 64
+      AND translate(
+        token_hash,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_key
+    UNIQUE (token_hash),
+
+  CONSTRAINT operator_identity_challenges_expiry_check
+    CHECK (
+      expires_at BETWEEN
+        created_at + INTERVAL '1 second'
+        AND created_at + INTERVAL '10 minutes'
+    ),
+
+  CONSTRAINT operator_identity_challenges_used_at_check
+    CHECK (
+      used_at IS NULL
+      OR used_at BETWEEN created_at AND expires_at
+    )
+);
+
+CREATE INDEX operator_identity_challenges_principal_created_idx
+  ON public.operator_identity_challenges
+    (principal_id, created_at DESC);
+
+CREATE INDEX operator_identity_challenges_expiry_idx
+  ON public.operator_identity_challenges (expires_at, id);

package/sql/20261018190000_identity_privacy_erasures.sql

@@ -0,0 +1,15 @@
+-- Direct identity erasure receipts. Audit and idempotency share one retained
+-- pseudonymous record; no personal export snapshot or actor grants are stored.
+CREATE TABLE public.identity_privacy_erasures (
+  erasure_id uuid PRIMARY KEY,
+  idempotency_key uuid NOT NULL UNIQUE,
+  client_id uuid UNIQUE REFERENCES public.clients(id),
+  principal_id uuid UNIQUE,
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  contract_version text NOT NULL CHECK (contract_version = 'identity.erasure.v1'),
+  contributor_versions jsonb NOT NULL,
+  dispositions jsonb NOT NULL,
+  retained_obligations jsonb NOT NULL,
+  completed_at timestamptz NOT NULL,
+  CHECK (client_id IS NOT NULL OR principal_id IS NOT NULL)
+);

package/src/bff/dispatch.ts

@@ -0,0 +1,81 @@
+// BFF dispatch mechanism.
+//
+// The route table and its handlers belong to the deployment. This module owns the
+// platform-neutral matching loop, so every HttpRuntimePort adapter (a hosted function or the Node
+// runtime of this package) mounts the same route table without duplicating dispatch logic.
+//
+// Per request, in order: the deployment's `beforeDispatch` hook, path normalization, the first
+// matching route, its availability, its decoded path parameters, the deployment's `preflight`
+// hook, then the handler. An unmatched or unavailable path goes to the deployment's `notFound`.
+
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { getBundleDescriptor, resolveBundleId } from "../kernel/index.js";
+
+export type RouteEntry = {
+  route: string;
+  pattern: RegExp;
+  params: string[];
+  handler: (req: HttpRequest, res: HttpResponse) => unknown;
+  /** Fail unsupported hosted bundles closed before auth without weakening direct-route auth. */
+  availability?: "direct-postgres";
+};
+
+/** Match `routes` against one request and run the handler, or answer not found. */
+export type BffDispatch = (
+  routes: readonly RouteEntry[],
+  req: HttpRequest,
+  res: HttpResponse,
+) => Promise<unknown>;
+
+export interface BffDispatcherOptions {
+  /** Environment read on each request to decide a route's bundle availability. */
+  env: () => Record<string, string | undefined>;
+  /** Writes the deployment's not-found response for an unmatched or unavailable path. */
+  notFound: (res: HttpResponse, pathname: string) => void;
+  /** Runs once per request before matching (for example, ambient request configuration). */
+  beforeDispatch?: () => void;
+  /**
+   * Runs after matching and before the handler, for example route authorization; resolving false
+   * means it already answered. Required, so no composition skips it by omission; a deployment
+   * without guarded routes passes `() => true`.
+   */
+  preflight: (req: HttpRequest, res: HttpResponse, route: string) => Promise<boolean> | boolean;
+}
+
+// Only the pathname is read, and it does not depend on the URL base; this host only completes a
+// request that carries no Host header.
+const FALLBACK_HOST = "bff.invalid";
+
+function requestPath(req: HttpRequest): string {
+  const rawUrl = typeof req.url === "string" ? req.url : "/";
+  const host = typeof req.headers?.host === "string" ? req.headers.host : FALLBACK_HOST;
+  return new URL(rawUrl, "https://" + host).pathname.replace(/\/+$/, "") || "/";
+}
+
+/** Build the dispatcher a deployment mounts on its hosted and Node entrypoints alike. */
+export function createBffDispatcher(options: BffDispatcherOptions): BffDispatch {
+  return async function dispatch(routes, req, res) {
+    options.beforeDispatch?.();
+    const pathname = requestPath(req);
+    for (const entry of routes) {
+      const match = entry.pattern.exec(pathname);
+      if (!match) continue;
+      if (entry.availability === "direct-postgres"
+        && getBundleDescriptor(resolveBundleId(options.env())).capabilities.data !== "postgres") {
+        options.notFound(res, pathname);
+        return undefined;
+      }
+      if (entry.params.length > 0) {
+        const query = { ...(req.query ?? {}) };
+        entry.params.forEach((param, index) => {
+          query[param] = decodeURIComponent(match[index + 1] ?? "");
+        });
+        req.query = query;
+      }
+      if (!(await options.preflight(req, res, entry.route))) return undefined;
+      return entry.handler(req, res);
+    }
+    options.notFound(res, pathname);
+    return undefined;
+  };
+}

package/src/bff/envelope.ts

@@ -0,0 +1,142 @@
+// BFF response envelope.
+//
+// Every BFF response is JSON `{ ok: true, data, meta? }` or `{ ok: false, error: { code, message,
+// details? }, meta? }`. A private response carries the request reference in the `x-request-id`
+// header and, for errors or responses with meta, in `meta.requestId`; a shared-cache response
+// (public or s-maxage) carries neither. `undefined` members are stripped before serialization.
+
+import type { HttpResponse } from "../http/index.js";
+
+export const BFF_REQUEST_REFERENCE_HEADER = "x-request-id";
+
+export const BFF_ERROR_CODES = [
+  "BAD_REQUEST",
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "METHOD_NOT_ALLOWED",
+  "CONFLICT",
+  "RATE_LIMITED",
+  "UPSTREAM_UNAVAILABLE",
+  "INTERNAL",
+  "INVALID_RESPONSE",
+] as const;
+
+export type BffErrorCode = (typeof BFF_ERROR_CODES)[number];
+
+export type BffMeta = { requestId?: string; contractVersion?: string; [key: string]: unknown };
+
+export type BffError = { code: BffErrorCode; message: string; details?: unknown };
+
+export type BffSuccessResponse<T> = { ok: true; data: T; meta?: BffMeta };
+
+export type BffErrorResponse = { ok: false; error: BffError; meta?: BffMeta };
+
+export type BffResponse<T> = BffSuccessResponse<T> | BffErrorResponse;
+
+/** The HTTP status each error code answers with unless the caller names another. */
+export const BFF_ERROR_STATUS: Readonly<Record<BffErrorCode, number>> = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  UPSTREAM_UNAVAILABLE: 503,
+  INTERNAL: 500,
+  INVALID_RESPONSE: 502,
+};
+
+export interface BffErrorOptions {
+  status?: number;
+  details?: unknown;
+  meta?: BffMeta;
+}
+
+export interface BffSuccessOptions {
+  cacheControl?: string;
+}
+
+export interface BffResponderOptions {
+  /** The request reference observed for this response, if the deployment records one. */
+  responseRequestId?: (res: HttpResponse) => string | undefined;
+}
+
+export interface BffResponder {
+  sendBffSuccess<T>(res: HttpResponse, data: T, meta?: BffMeta, options?: BffSuccessOptions): void;
+  sendBffError(res: HttpResponse, code: BffErrorCode, message: string, options?: BffErrorOptions): void;
+  sendMethodNotAllowed(res: HttpResponse, allowedMethods: readonly string[]): void;
+}
+
+/** Build the envelope writers a deployment's handlers share. */
+export function createBffResponder(options: BffResponderOptions = {}): BffResponder {
+  function sendBffSuccess<T>(
+    res: HttpResponse,
+    data: T,
+    meta?: BffMeta,
+    successOptions: BffSuccessOptions = {},
+  ): void {
+    sendJson(res, 200, { ok: true, data, meta }, successOptions.cacheControl);
+  }
+
+  function sendBffError(
+    res: HttpResponse,
+    code: BffErrorCode,
+    message: string,
+    errorOptions: BffErrorOptions = {},
+  ): void {
+    sendJson(res, errorOptions.status ?? BFF_ERROR_STATUS[code], {
+      ok: false,
+      error: { code, message, details: errorOptions.details },
+      meta: errorOptions.meta,
+    });
+  }
+
+  function sendMethodNotAllowed(res: HttpResponse, allowedMethods: readonly string[]): void {
+    res.setHeader("Allow", allowedMethods.join(", "));
+    sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+  }
+
+  function sendJson<T>(
+    res: HttpResponse,
+    status: number,
+    body: BffResponse<T>,
+    cacheControl = "no-store",
+  ): void {
+    const shared = /(?:^|,)\s*(?:public\b|s-maxage\s*=)/i.test(cacheControl);
+    const requestId = shared ? undefined : options.responseRequestId?.(res);
+    const responseBody = withRequestReference(body, requestId, shared);
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", cacheControl);
+    if (shared && typeof res.removeHeader === "function") res.removeHeader(BFF_REQUEST_REFERENCE_HEADER);
+    else if (requestId) res.setHeader(BFF_REQUEST_REFERENCE_HEADER, requestId);
+    res.status(status).json(stripUndefined(responseBody));
+  }
+
+  return { sendBffSuccess, sendBffError, sendMethodNotAllowed };
+}
+
+function withRequestReference<T>(
+  body: BffResponse<T>,
+  requestId: string | undefined,
+  omitRequestId: boolean,
+): BffResponse<T> {
+  if (requestId && (body.ok === false || body.meta)) {
+    return { ...body, meta: { ...body.meta, requestId } };
+  }
+  if (!omitRequestId || !body.meta || !("requestId" in body.meta)) return body;
+  const { requestId: _omitted, ...meta } = body.meta;
+  return { ...body, meta: Object.keys(meta).length > 0 ? meta : undefined };
+}
+
+function stripUndefined(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripUndefined);
+  if (!value || typeof value !== "object") return value;
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .map(([key, entryValue]) => [key, stripUndefined(entryValue)]),
+  );
+}

package/src/bff/health.ts

@@ -0,0 +1,37 @@
+// BFF health route.
+//
+// GET answers the deployment's health payload, validated by the deployment's strict contract, with
+// the payload's contract version in `meta`; any other method answers 405 with `Allow: GET`. A
+// payload that fails its own contract answers INTERNAL rather than an unchecked body.
+
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "./envelope.js";
+
+export interface HealthContract<T extends { contractVersion: string }> {
+  safeParse(value: unknown): { success: true; data: T } | { success: false };
+}
+
+export interface HealthHandlerOptions<T extends { contractVersion: string }> {
+  responder: BffResponder;
+  /** The deployment's strict health contract. */
+  contract: HealthContract<T>;
+  /** Builds this request's health payload: service identity, release provenance and the rest. */
+  read: () => unknown;
+}
+
+export function createHealthHandler<T extends { contractVersion: string }>(
+  options: HealthHandlerOptions<T>,
+): (req: HttpRequest, res: HttpResponse) => void {
+  return function health(req, res) {
+    if (req.method !== "GET") {
+      options.responder.sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+    const result = options.contract.safeParse(options.read());
+    if (!result.success) {
+      options.responder.sendBffError(res, "INTERNAL", "Health contract is invalid");
+      return;
+    }
+    options.responder.sendBffSuccess(res, result.data, { contractVersion: result.data.contractVersion });
+  };
+}

package/src/bff/index.ts

@@ -0,0 +1,30 @@
+export { createBffDispatcher, type BffDispatch, type BffDispatcherOptions, type RouteEntry } from "./dispatch.js";
+export { lazyBffRoute } from "./lazyRoute.js";
+export { rewriteBffRouterRequestUrl } from "./routerRewrite.js";
+export {
+  BFF_ERROR_CODES,
+  BFF_ERROR_STATUS,
+  BFF_REQUEST_REFERENCE_HEADER,
+  createBffResponder,
+  type BffError,
+  type BffErrorCode,
+  type BffErrorOptions,
+  type BffErrorResponse,
+  type BffMeta,
+  type BffResponder,
+  type BffResponderOptions,
+  type BffResponse,
+  type BffSuccessOptions,
+  type BffSuccessResponse,
+} from "./envelope.js";
+export {
+  createHealthHandler,
+  type HealthContract,
+  type HealthHandlerOptions,
+} from "./health.js";
+export {
+  createRequestContextStore,
+  type ObservedRequestContext,
+  type RequestContextOptions,
+  type RequestContextStore,
+} from "./requestContext.js";

package/src/bff/lazyRoute.ts

@@ -0,0 +1,28 @@
+// Loads a BFF route module on its first request instead of at cold start.
+//
+// A route table binds each route as `lazyBffRoute(() => import("<specifier>"))`, so the
+// specifier stays a static literal that bundlers and inventories can read, and the load's type
+// keeps every module's default export checked against `RouteEntry["handler"]`.
+//
+// Concurrent first calls share one load. A rejected load is not kept: the requests that awaited
+// it reject as a throwing handler does, and the next request loads again. A module that threw
+// during evaluation stays errored in Node's ESM loader; the retry helps only a failure before
+// evaluation (a missing file or a read error). Once loaded, the module's handler is called
+// synchronously and its result returned.
+import type { RouteEntry } from "./dispatch.js";
+
+export function lazyBffRoute(load: () => Promise<{ default: RouteEntry["handler"] }>): RouteEntry["handler"] {
+  let handler: RouteEntry["handler"] | undefined;
+  let loading: Promise<RouteEntry["handler"]> | undefined;
+  return (req, res) => {
+    if (handler) return handler(req, res);
+    loading ??= load().then(
+      (module) => (handler = module.default),
+      (error: unknown) => {
+        loading = undefined;
+        throw error;
+      },
+    );
+    return loading.then((loaded) => loaded(req, res));
+  };
+}