@openlup/platform 0.0.0-stage → 0.15.0

package/src/data/queryBuilder.ts

@@ -0,0 +1,300 @@
+// Vanilla-Postgres query-builder shim.
+//
+// Option A (approved): a SCOPED, injection-safe builder that emulates ONLY the supabase-js methods
+// the 6 existing gateway consumers actually call — never a full PostgREST reimplementation. It
+// translates a builder chain into a single PARAMETERIZED `pg` query ($1,$2,…). Values are never
+// string-interpolated and identifiers are allowlist-validated; both invariants live in the pure SQL
+// layer (queryBuilderSql.ts), which this file composes.
+//
+// Result semantics mirror PostgREST for the methods used:
+//   - default (await builder)            -> { data: Row[], error }
+//   - .maybeSingle()                     -> { data: Row | null, error } (0/1 row; >1 is an error)
+//   - .single()                          -> { data: Row, error }       (exactly 1 row; else error)
+//   - .range(from,to)/.limit(n)          -> LIMIT/OFFSET, returns { data: Row[], error }
+//   - .select(c, {count:"exact"[,head]}) -> { data, count } from a separate aggregate; head omits rows
+//   - .insert(v).select(c).maybeSingle() -> INSERT ... RETURNING c, single row
+//   - .update(v)...                      -> UPDATE ... [RETURNING c]
+//   - error.code carries the pg SQLSTATE (e.g. 23505 unique-violation) so consumers' code-based
+//     branches (idempotency replay) keep working unchanged.
+//
+// The shim is constructed over a SINGLE acquired pg client (one per asActor/asService tx in the
+// DataGatewayPort), so every query here runs inside that request's transaction with its RLS GUCs set.
+
+import type { PoolClient } from "pg";
+
+import {
+  ParamAccumulator,
+  joinParts,
+  quoteIdent,
+  rangeNotSatisfiable,
+  renderColumns,
+  renderCountQuery,
+  renderFilter,
+  renderInsertStatement,
+  toShimError,
+  unwrapRpcRows,
+  type Filter,
+  type OrderBy,
+  type PgQueryExecutor,
+  type PgShimError,
+  type PgShimResult,
+} from "./queryBuilderSql.js";
+
+// Re-export the result/error/executor shapes so consumers import them from the builder entrypoint.
+export type { PgQueryExecutor, PgShimError, PgShimResult };
+
+interface BuilderState {
+  table: string;
+  mode: "select" | "insert" | "update";
+  columns: string; // RETURNING / SELECT projection
+  filters: Filter[];
+  orders: OrderBy[];
+  limit: number | null;
+  offset: number | null;
+  insertRows: Array<Record<string, unknown>> | null;
+  updateValues: Record<string, unknown> | null;
+  exactCount: boolean;
+  head: boolean;
+  rangeRequested: boolean;
+}
+
+/**
+ * Builder over one pg client. Chainable + awaitable (PromiseLike). Every value flows through a param
+ * accumulator, so the rendered SQL contains only $N placeholders for values.
+ */
+export class PgQueryBuilder<T = unknown> implements PromiseLike<PgShimResult<T>> {
+  private state: BuilderState;
+
+  constructor(
+    private readonly client: PgQueryExecutor,
+    table: string,
+  ) {
+    this.state = {
+      table,
+      mode: "select",
+      columns: "*",
+      filters: [],
+      orders: [],
+      limit: null,
+      offset: null,
+      insertRows: null,
+      updateValues: null,
+      exactCount: false,
+      head: false,
+      rangeRequested: false,
+    };
+  }
+
+  select(columns: string, options?: { count?: string; head?: boolean }): this {
+    this.state.columns = columns;
+    this.state.exactCount = options?.count === "exact";
+    this.state.head = options?.head === true;
+    return this;
+  }
+
+  insert(values: Record<string, unknown> | Array<Record<string, unknown>>): this {
+    this.state.mode = "insert";
+    this.state.insertRows = Array.isArray(values) ? values : [values];
+    return this;
+  }
+
+  update(values: Record<string, unknown>): this {
+    this.state.mode = "update";
+    this.state.updateValues = values;
+    return this;
+  }
+
+  eq(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "eq", column, value });
+    return this;
+  }
+
+  gt(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "gt", column, value });
+    return this;
+  }
+
+  gte(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "gte", column, value });
+    return this;
+  }
+
+  lte(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "lte", column, value });
+    return this;
+  }
+
+  in(column: string, values: unknown[]): this {
+    this.state.filters.push({ kind: "in", column, values });
+    return this;
+  }
+
+  is(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "is", column, value });
+    return this;
+  }
+
+  ilike(column: string, value: string): this {
+    this.state.filters.push({ kind: "ilike", column, value });
+    return this;
+  }
+
+  order(column: string, options?: { ascending?: boolean }): this {
+    this.state.orders.push({ column, ascending: options?.ascending !== false });
+    return this;
+  }
+
+  limit(count: number): this {
+    this.state.limit = count;
+    return this;
+  }
+
+  range(from: number, to: number): Promise<PgShimResult<T>> {
+    // PostgREST range is inclusive on both ends → LIMIT (to-from+1) OFFSET from.
+    this.state.offset = from;
+    this.state.limit = to - from + 1;
+    this.state.rangeRequested = true;
+    return this.run("many");
+  }
+
+  async maybeSingle(): Promise<PgShimResult<T>> {
+    return this.run("maybe");
+  }
+
+  async single(): Promise<PgShimResult<T>> {
+    return this.run("single");
+  }
+
+  then<R1 = PgShimResult<T>, R2 = never>(
+    onfulfilled?: ((value: PgShimResult<T>) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): Promise<R1 | R2> {
+    return this.run("many").then(onfulfilled, onrejected);
+  }
+
+  private async run(cardinality: "many" | "maybe" | "single"): Promise<PgShimResult<T>> {
+    try {
+      const count = this.state.exactCount ? await this.runExactCount() : null;
+      // A page past the end is a REFUSAL upstream, not an empty answer — but only once the total is
+      // known, which is why this sits behind the count and not behind `.range()` itself.
+      const unsatisfiable = this.state.rangeRequested ? rangeNotSatisfiable(this.state.offset, count) : null;
+      if (unsatisfiable) return { data: [] as T, error: unsatisfiable, count: null };
+      // head:true is a HEAD request: no body, so the client contract reports data:null and no row query.
+      if (this.state.head) return { data: null as T, error: null, count };
+      const { text, values } = this.compile();
+      const { rows } = await this.client.query(text, values);
+      // The client contract reports count: null unless a count was requested; `shape` must not invent one.
+      return { ...this.shape(rows, cardinality), count };
+    } catch (error) {
+      return { data: (cardinality === "many" ? [] : null) as T, error: toShimError(error), count: null };
+    }
+  }
+
+  private async runExactCount(): Promise<number> {
+    const params = new ParamAccumulator();
+    const { rows } = await this.client.query(renderCountQuery(this.state.table, this.state.filters, params), params.values);
+    return Number(rows[0]?.exact_count ?? 0);
+  }
+
+  private shape(rows: Record<string, unknown>[], cardinality: "many" | "maybe" | "single"): PgShimResult<T> {
+    if (cardinality === "many") {
+      return { data: rows as T, error: null };
+    }
+    if (rows.length > 1) {
+      // PostgREST returns 406 (PGRST116) when maybeSingle/single match multiple rows.
+      return { data: null as T, error: { code: "PGRST116", message: "multiple rows returned" } };
+    }
+    if (cardinality === "single" && rows.length === 0) {
+      return { data: null as T, error: { code: "PGRST116", message: "no rows returned" } };
+    }
+    return { data: (rows[0] ?? null) as T, error: null };
+  }
+
+  private compile(): { text: string; values: unknown[] } {
+    const params = new ParamAccumulator();
+    if (this.state.mode === "insert") return this.compileInsert(params);
+    if (this.state.mode === "update") return this.compileUpdate(params);
+    return this.compileSelect(params);
+  }
+
+  private compileSelect(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const parts = [`SELECT ${renderColumns(this.state.columns)} FROM ${quoteIdent(this.state.table)}`];
+    parts.push(this.renderWhere(params));
+    parts.push(this.renderOrder());
+    parts.push(this.renderLimitOffset(params));
+    return { text: joinParts(parts), values: params.values };
+  }
+
+  private compileInsert(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const text = renderInsertStatement(this.state.table, this.state.insertRows ?? [], this.state.columns, params);
+    return { text, values: params.values };
+  }
+
+  private compileUpdate(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const values = this.state.updateValues ?? {};
+    const assignments = Object.keys(values)
+      .map((c) => `${quoteIdent(c)} = ${params.add(values[c])}`)
+      .join(", ");
+    if (assignments === "") throw new Error("pg-shim: update requires at least one column");
+    const parts = [`UPDATE ${quoteIdent(this.state.table)} SET ${assignments}`];
+    parts.push(this.renderWhere(params));
+    const returning = this.state.columns && this.state.columns !== "*"
+      ? `RETURNING ${renderColumns(this.state.columns)}`
+      : "";
+    if (returning) parts.push(returning);
+    return { text: joinParts(parts), values: params.values };
+  }
+
+  private renderWhere(params: ParamAccumulator): string {
+    if (this.state.filters.length === 0) return "";
+    const clauses = this.state.filters.map((f) => renderFilter(f, params));
+    return `WHERE ${clauses.join(" AND ")}`;
+  }
+
+  private renderOrder(): string {
+    if (this.state.orders.length === 0) return "";
+    const cols = this.state.orders
+      .map((o) => `${quoteIdent(o.column)} ${o.ascending ? "ASC" : "DESC"}`)
+      .join(", ");
+    return `ORDER BY ${cols}`;
+  }
+
+  private renderLimitOffset(params: ParamAccumulator): string {
+    const parts: string[] = [];
+    if (this.state.limit !== null) parts.push(`LIMIT ${params.add(this.state.limit)}`);
+    if (this.state.offset !== null) parts.push(`OFFSET ${params.add(this.state.offset)}`);
+    return parts.join(" ");
+  }
+}
+
+/** supabase-js-style client over one acquired pg client: `.from(t)` + `.rpc(fn, args)`. */
+export class PgGatewayClient {
+  constructor(private readonly client: PgQueryExecutor) {}
+
+  query(text: string, values?: unknown[]) { return this.client.query(text, values); }
+
+  from<T = Record<string, unknown>>(table: string): PgQueryBuilder<T> {
+    return new PgQueryBuilder<T>(this.client, table);
+  }
+
+  async rpc(functionName: string, args: Record<string, unknown> = {}): Promise<PgShimResult> {
+    try {
+      const name = quoteIdent(functionName);
+      const params = new ParamAccumulator();
+      // Named-arg invocation: every existing RPC uses `p_*` named params. `name => $n` binds by name
+      // so arg order is irrelevant and values are fully parameterized.
+      const namedArgs = Object.keys(args)
+        .map((key) => `${quoteIdent(key)} => ${params.add(args[key])}`)
+        .join(", ");
+      const text = `SELECT * FROM ${name}(${namedArgs})`;
+      const { rows } = await this.client.query(text, params.values);
+      // RPCs returning a scalar set-returning function expose the value under the function name;
+      // a single-column single-row result unwraps to that value (matches supabase-js rpc shape).
+      return { data: unwrapRpcRows(rows, functionName), error: null };
+    } catch (error) {
+      return { data: null, error: toShimError(error) };
+    }
+  }
+}
+
+export type { PoolClient };

package/src/data/queryBuilderSql.ts

@@ -0,0 +1,183 @@
+// Vanilla-Postgres query-builder SQL primitives.
+//
+// Extracted from queryBuilder.ts (300-LOC cap) — the pure, stateless SQL-fragment layer the builder
+// composes: result/error shapes, the injection-safety chokepoint (ParamAccumulator), identifier
+// quoting (allowlist), column projection, and filter rendering. VALUES ARE NEVER string-interpolated;
+// they flow through ParamAccumulator as $N placeholders. Identifiers (table/column names) are validated
+// against a strict allowlist regex and double-quoted, so they cannot smuggle SQL either.
+
+/** PostgREST-shaped error the consumers narrow on (`.code`, `.message`, `.details`, `.hint`). */
+export interface PgShimError {
+  code?: string;
+  message?: string;
+  details?: string;
+  hint?: string;
+}
+
+export interface PgShimResult<T = unknown> {
+  data: T;
+  error: PgShimError | null;
+  count?: number | null;
+}
+
+/** Minimal query surface we need from a pg client (Pool acquires a PoolClient per request). */
+export interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export type Filter =
+  | { kind: "eq" | "gte" | "lte" | "gt"; column: string; value: unknown }
+  | { kind: "in"; column: string; values: unknown[] }
+  | { kind: "ilike"; column: string; value: string }
+  | { kind: "is"; column: string; value: unknown };
+
+export interface OrderBy {
+  column: string;
+  ascending: boolean;
+}
+
+// Identifiers (table + column names) are NEVER parameterizable in SQL, so they are validated against
+// a strict allowlist and quoted. Consumers only ever pass static, code-literal identifiers; this
+// guard turns any attempt to pass a crafted identifier into a thrown error rather than injected SQL.
+const IDENTIFIER_RE = /^[a-z_][a-z0-9_]*$/i;
+
+export function quoteIdent(raw: string): string {
+  if (!IDENTIFIER_RE.test(raw)) {
+    throw new Error(`pg-shim: unsafe identifier ${JSON.stringify(raw)}`);
+  }
+  return `"${raw}"`;
+}
+
+// `select("a, b")` etc. — a comma list of identifiers or "*". Each segment is validated; "*" passes
+// through. PostgREST embedding syntax (foo(bar)) is NOT used by any consumer, so it is rejected
+// (fail-closed) rather than silently mistranslated.
+export function renderColumns(columns: string): string {
+  const trimmed = columns.trim();
+  if (trimmed === "" || trimmed === "*") return "*";
+  return trimmed
+    .split(",")
+    .map((c) => c.trim())
+    .map((c) => (c === "*" ? "*" : quoteIdent(c)))
+    .join(", ");
+}
+
+export function renderFilter(filter: Filter, params: ParamAccumulator): string {
+  const col = quoteIdent(filter.column);
+  switch (filter.kind) {
+    case "eq":
+      return `${col} = ${params.add(filter.value)}`;
+    case "gt":
+      return `${col} > ${params.add(filter.value)}`;
+    case "gte":
+      return `${col} >= ${params.add(filter.value)}`;
+    case "lte":
+      return `${col} <= ${params.add(filter.value)}`;
+    case "ilike":
+      return `${col} ILIKE ${params.add(filter.value)}`;
+    case "in": {
+      // Empty IN () is invalid SQL; PostgREST treats `.in([])` as matching nothing.
+      if (filter.values.length === 0) return "false";
+      const placeholders = filter.values.map((v) => params.add(v)).join(", ");
+      return `${col} IN (${placeholders})`;
+    }
+    case "is":
+      // .is(col, null) → IS NULL; .is(col, true/false) → IS TRUE/FALSE. Value is a literal keyword,
+      // not user data (consumers only pass null/true/false), so it is rendered, not parameterized.
+      if (filter.value === null) return `${col} IS NULL`;
+      if (filter.value === true) return `${col} IS TRUE`;
+      if (filter.value === false) return `${col} IS FALSE`;
+      throw new Error("pg-shim: .is() only supports null/true/false");
+  }
+}
+
+/**
+ * PostgREST `count=exact` rendered as a SEPARATE aggregate over the same FROM/WHERE — deliberately
+ * NOT a `COUNT(*) OVER()` folded into the row query. PostgREST's exact count ignores limit/offset,
+ * and a window function emits no row at all for an empty page, so an offset past the end would
+ * report 0 instead of the true total. Keeping it separate also leaves the row projection
+ * byte-identical: there is no synthetic column to strip before cardinality shaping.
+ */
+export function renderCountQuery(table: string, filters: readonly Filter[], params: ParamAccumulator): string {
+  const where = filters.length === 0
+    ? ""
+    : `WHERE ${filters.map((filter) => renderFilter(filter, params)).join(" AND ")}`;
+  return joinParts([`SELECT count(*) AS exact_count FROM ${quoteIdent(table)}`, where]);
+}
+
+/**
+ * PostgREST refuses an out-of-bounds page instead of answering an empty one -- but ONLY when it
+ * knows the total, i.e. when an exact count was requested; without one it answers 200 and `[]`,
+ * which is what this shim already did. The boundary is strict: offset === total is a legal empty
+ * page, offset === total + 1 is not. Measured against PostgREST 14.10 before this was written,
+ * including the `details` sentence, which carries the two numbers a caller pages on.
+ */
+export function rangeNotSatisfiable(offset: number | null, total: number | null): PgShimError | null {
+  if (offset === null || total === null || offset <= total) return null;
+  return {
+    code: "PGRST103",
+    message: "Requested range not satisfiable",
+    details: `An offset of ${offset} was requested, but there are only ${total} rows.`,
+  };
+}
+
+/**
+ * INSERT ... VALUES ... RETURNING, with the column list taken from the FIRST row and every later
+ * row required to carry the same key set. Deriving the columns from row 0 alone and binding the
+ * rest positionally is how a batch used to lose a column silently: an extra key vanished, a missing
+ * one bound NULL over a DEFAULT. PostgREST answers PGRST102 "All object keys must match" to exactly
+ * this payload -- and keeps answering it under `Prefer: missing=default`, measured -- so the shim
+ * refuses too. Refusal, not union: parity is the point, and this builder exposes no Prefer header
+ * through which a caller could ask for anything else.
+ */
+export function renderInsertStatement(
+  table: string,
+  rows: readonly Record<string, unknown>[],
+  projection: string,
+  params: ParamAccumulator,
+): string {
+  if (rows.length === 0) throw new Error("pg-shim: insert requires at least one row");
+  const columns = Object.keys(rows[0]!);
+  const signature = [...columns].sort().join("\u0000");
+  for (const row of rows) {
+    if ([...Object.keys(row)].sort().join("\u0000") !== signature) {
+      throw Object.assign(new Error("All object keys must match"), { code: "PGRST102" });
+    }
+  }
+  const tuples = rows.map((row) => `(${columns.map((column) => params.add(row[column])).join(", ")})`).join(", ");
+  return `INSERT INTO ${quoteIdent(table)} (${columns.map(quoteIdent).join(", ")}) VALUES ${tuples} `
+    + `RETURNING ${renderColumns(projection)}`;
+}
+
+// supabase-js rpc() returns the function's return value directly: a scalar/json function yields that
+// value; a TABLE/SETOF function yields the row array. Heuristic mirrors that: 1 row × 1 column whose
+// name equals the function → the scalar; otherwise the rows array (TABLE-returning).
+export function unwrapRpcRows(rows: Record<string, unknown>[], functionName: string): unknown {
+  if (rows.length === 1) {
+    const keys = Object.keys(rows[0]);
+    if (keys.length === 1 && keys[0] === functionName) return rows[0][functionName];
+  }
+  return rows;
+}
+
+/** Accumulates values and hands back $1,$2,… placeholders — the single injection-safety chokepoint. */
+export class ParamAccumulator {
+  readonly values: unknown[] = [];
+  add(value: unknown): string {
+    this.values.push(value);
+    return `$${this.values.length}`;
+  }
+}
+
+export function joinParts(parts: string[]): string {
+  return parts.filter((p) => p.trim() !== "").join(" ");
+}
+
+export function toShimError(error: unknown): PgShimError {
+  const e = error as { code?: string; message?: string; detail?: string; hint?: string };
+  return {
+    code: e?.code,
+    message: e?.message ?? "query failed",
+    details: e?.detail,
+    hint: e?.hint,
+  };
+}

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;
+}