@specific.dev/spectest 0.12.0 → 0.14.0

package/src/components/supabase.ts

@@ -0,0 +1,1109 @@
+// A ready-to-use, self-hosted **Supabase** stack, expressed as a set of
+// spectest services (one container each) wired together on spectest-net.
+//
+// This is the standard Supabase self-hosted Docker topology
+// (github.com/supabase/supabase, `docker/docker-compose.yml`) reproduced with
+// the *exact upstream images and config* — the Kong API gateway, GoTrue auth,
+// PostgREST, storage-api (+imgproxy), Realtime, and a `supabase/postgres`
+// database with the standard role/JWT bootstrap — just orchestrated as
+// spectest services instead of via docker-compose. That means it rides
+// spectest's parallel image prep, ready-check DAG, DNS, host image cache, and
+// snapshot/fork for free, with no daemon or control-plane changes.
+//
+// Unlike the single-`ServiceDefinition` components (`postgres()`, `s3()`),
+// Supabase is inherently a constellation of containers, so `supabase()` returns
+// a **service group** (one services-map entry that `defineEnvironment` expands)
+// plus the derived connection surface:
+//
+// ```ts
+// import { defineEnvironment } from "@specific.dev/spectest";
+// import { supabase } from "@specific.dev/spectest/components";
+//
+// const sb = supabase({ dbPassword: "postgres" });
+//
+// export const env = defineEnvironment({
+//   name: "my-app",
+//   services: {
+//     supabase: sb.group,      // expands to supabase, supabase-db, supabase-auth, ...
+//     app: {
+//       image: { type: "dockerfile", content: "..." },
+//       env: { ...sb.appEnv }, // SUPABASE_URL / _ANON_KEY / _SERVICE_ROLE_KEY / DATABASE_URL
+//       dependsOn: [sb.ready], // wait for the gateway (and the stack behind it)
+//     },
+//   },
+// });
+//
+// // in a test:
+// await ctx.svc.supabase.sql`select * from auth.users`;   // instrumented DB client
+// await ctx.fetch(`${sb.url}/rest/v1/todos`, { headers: { apikey: sb.anonKey } });
+// ```
+//
+// The gateway is the group's primary part, so it takes the group key itself:
+// reachable at `http://supabase:8000` on spectest-net, helpers (the group's
+// consolidated handle) at `ctx.svc.supabase`, and `dependsOn: ["supabase"]`
+// waits for the whole stack (group expansion makes the primary the sink).
+// Every other piece lands at `<name>-<part>` (`supabase-db`, `supabase-auth`,
+// …); internal references (env + the Kong declarative config) are built from
+// the group naming context, so two Supabase stacks (or a user service
+// innocently named `db`) never collide. The group must be mounted at the key
+// matching the `name` option (default `"supabase"`) since the derived surface
+// (`sb.url`, `sb.appEnv`) embeds it — a mismatch errors at load.
+
+import { createHmac } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  serviceGroup,
+  type ServiceConfig,
+  type ServiceDefinition,
+  type ServiceGroup,
+  type ServiceSetupContext,
+  type ServicesMap,
+} from "../index.js";
+import { SQL, type SqlClient } from "../sql.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
+// current master). Bump together; each is pulled through the host Hub mirror on
+// first cold boot and captured into the warm-template snapshot thereafter.
+// ──────────────────────────────────────────────────────────────────────────
+const IMAGES = {
+  db: "supabase/postgres:17.6.1.136",
+  kong: "kong/kong:3.9.1",
+  auth: "supabase/gotrue:v2.189.0",
+  rest: "postgrest/postgrest:v14.12",
+  realtime: "supabase/realtime:v2.102.3",
+  storage: "supabase/storage-api:v1.60.4",
+  imgproxy: "darthsim/imgproxy:v3.30.1",
+  meta: "supabase/postgres-meta:v0.96.6",
+  studio: "supabase/studio:2026.07.07-sha-a6a04f2",
+} as const;
+
+export interface SupabaseOptions {
+  /**
+   * Key of the API-gateway service and the prefix for every other piece.
+   * Default `"supabase"`. The gateway is reachable at `http://<name>:8000`
+   * and its helpers at `ctx.svc.<name>`; the rest are `<name>-db`,
+   * `<name>-auth`, `<name>-rest`, `<name>-storage`, `<name>-realtime`, ….
+   */
+  name?: string;
+  /**
+   * Password for the Postgres roles the services authenticate with (and the
+   * `postgres` superuser the app / SQL helper connect as). Default
+   * `"postgres"`. Purely local to the hermetic VM — not a secret to guard.
+   */
+  dbPassword?: string;
+  /**
+   * HS256 secret that signs and verifies all JWTs (user access tokens plus the
+   * derived `anonKey` / `serviceRoleKey` API keys). Must be ≥32 chars. Default
+   * is Supabase's well-known demo secret. Changing it re-derives the keys
+   * deterministically, so the warm-template cache stays stable.
+   */
+  jwtSecret?: string;
+  /** Studio dashboard Basic-Auth username (only relevant with `studio`). Default `"supabase"`. */
+  dashboardUsername?: string;
+  /** Studio dashboard Basic-Auth password (only relevant with `studio`). */
+  dashboardPassword?: string;
+
+  /** Include GoTrue auth (`<name>-auth`). Default `true`. */
+  auth?: boolean;
+  /** Include storage-api + imgproxy (`<name>-storage`, `<name>-imgproxy`). Default `true`. */
+  storage?: boolean;
+  /** Include Realtime (`<name>-realtime`). Default `true`. */
+  realtime?: boolean;
+  /**
+   * Include the Studio dashboard (`<name>-studio`) and its postgres-meta
+   * backend (`<name>-meta`). Off by default — Studio is a heavy Next.js image
+   * and is only useful for interactive `ctx.browser()` exploration, not
+   * automated backend assertions. Turning it on implies `meta`.
+   */
+  studio?: boolean;
+  /** Include postgres-meta (`<name>-meta`). Defaults to whatever `studio` is. */
+  meta?: boolean;
+
+  /**
+   * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
+   * daemon's CA-trusted TLS reverse proxy (in addition to the plain
+   * `http://<name>:8000`). Set this only when the app under test hardcodes a
+   * specific Supabase URL it can't be told to override — otherwise leave it and
+   * point the app at `sb.url`.
+   */
+  hostname?: string;
+
+  /**
+   * Auto-apply SQL migrations found in the project before any dependent service
+   * starts. `true` (default) applies every `*.sql` under `supabase/migrations/`
+   * (sorted, the Supabase convention), then `supabase/seed.sql` if present — a
+   * no-op when the directory is absent. Pass a string to point at a different
+   * directory (relative to the project root or absolute), or `false` to skip.
+   * Because `supabase/**` is project content, editing a migration correctly
+   * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
+   */
+  migrations?: boolean | string;
+  /**
+   * Seed SQL applied after migrations. `true` (default) applies
+   * `supabase/seed.sql` if it exists; a string overrides the path; `false`
+   * skips it.
+   */
+  seed?: boolean | string;
+}
+
+/** Helpers the gateway service exposes on `ctx.svc.<name>`. */
+export interface SupabaseHelpers {
+  /**
+   * An instrumented {@link SqlClient} connected to the database as the
+   * `postgres` superuser — every query lands on the test event log and its rows
+   * come back provenance-wrapped, so `expect(...)` on a read links to the
+   * query. Point of direct DB verification alongside the REST/auth surface.
+   */
+  sql: SqlClient;
+  /** The gateway base URL the app uses as `SUPABASE_URL` (e.g. `http://supabase:8000`). */
+  url: string;
+  /** Long-lived `anon` API key (HS256 JWT). Pass as the `apikey` header. */
+  anonKey: string;
+  /** Long-lived `service_role` API key (HS256 JWT). Bypasses RLS — server-side only. */
+  serviceRoleKey: string;
+}
+
+/** What `supabase()` returns: the service group plus the derived
+ *  connection surface for wiring the app under test. */
+export interface SupabaseStack {
+  /** The Supabase stack as a service group. Mount it at the key matching
+   *  the `name` option (default `"supabase"`):
+   *  `services: { supabase: sb.group, ... }`. */
+  group: ServiceGroup<ServicesMap, SupabaseHelpers>;
+  /** Gateway base URL — `http://<name>:8000`, or `https://<hostname>` when set. */
+  url: string;
+  /** `anon` API key (HS256 JWT). */
+  anonKey: string;
+  /** `service_role` API key (HS256 JWT). */
+  serviceRoleKey: string;
+  /** Direct Postgres URL for the app (`postgres` superuser): `postgresql://postgres:<pw>@<name>-db:5432/postgres`. */
+  dbUrl: string;
+  /** The gateway service key — use in a dependent service's `dependsOn` to wait
+   *  for the whole stack (the gateway waits on the services behind it). */
+  ready: string;
+  /** Ready-to-spread env for the app under test: `SUPABASE_URL`,
+   *  `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`. */
+  appEnv: Record<string, string>;
+}
+
+// Supabase's well-known demo secret (≥32 chars). Local-only; override via opts.
+const DEFAULT_JWT_SECRET =
+  "your-super-secret-jwt-token-with-at-least-32-characters-long";
+
+// Fixed issued-at / expiry for the derived API keys. Constant (not `Date.now`)
+// so the keys are a pure function of the secret and never perturb the
+// warm-template hash. `exp` is 2027-01-01, matching Supabase's demo keys.
+const KEY_IAT = 1641769200;
+const KEY_EXP = 1799535600;
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** Sign a compact HS256 JWT. Any token with the right `role` claim signed by
+ *  `JWT_SECRET` is a valid Supabase API key — we don't need to reproduce the
+ *  exact demo string, just a validly-signed one. */
+function signHs256(payload: Record<string, unknown>, secret: string): string {
+  const header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = base64url(JSON.stringify(payload));
+  const data = `${header}.${body}`;
+  const sig = base64url(createHmac("sha256", secret).update(data).digest());
+  return `${data}.${sig}`;
+}
+
+function apiKey(role: "anon" | "service_role", secret: string): string {
+  return signHs256({ role, iss: "supabase-demo", iat: KEY_IAT, exp: KEY_EXP }, secret);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Postgres bootstrap SQL. The `supabase/postgres` image already creates every
+// Supabase role/schema in its baked init-scripts; we only need to (a) set the
+// network-facing roles' passwords to ours, (b) plant the JWT secret as a DB GUC
+// (used by RLS `auth.jwt()`), and (c) create the `_realtime` schema.
+//
+// We apply this in the db service's `setup` hook (via `psql`) rather than as
+// mounted init-scripts, deliberately: the image's `migrate.sh` runs mounted
+// files under `ON_ERROR_STOP`, so a single unexpected role (e.g.
+// `supabase_functions_admin`, which only exists when the DB-webhooks script is
+// present) aborts the whole init and the container exits. `setup` runs after
+// the DB is ready and before any dependent service starts, so ordering is still
+// guaranteed, and we touch only roles the base image is known to create.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Quote a Postgres string literal (single-quote, double any embedded quote). */
+function pgLiteral(s: string): string {
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+function buildBootstrapSql(
+  dbPassword: string,
+  jwtSecret: string,
+  withRealtime: boolean,
+): string {
+  const pw = pgLiteral(dbPassword);
+  const lines = [
+    // Network-facing roles the services authenticate as. supabase_admin and
+    // postgres already have their password set to POSTGRES_PASSWORD by the
+    // image's own bootstrap, so we leave them alone.
+    `ALTER USER authenticator WITH PASSWORD ${pw};`,
+    `ALTER USER supabase_auth_admin WITH PASSWORD ${pw};`,
+    `ALTER USER supabase_storage_admin WITH PASSWORD ${pw};`,
+    // JWT secret GUC for RLS (`current_setting('app.settings.jwt_secret')`).
+    `ALTER DATABASE postgres SET "app.settings.jwt_secret" TO ${pgLiteral(jwtSecret)};`,
+    `ALTER DATABASE postgres SET "app.settings.jwt_exp" TO '3600';`,
+  ];
+  if (withRealtime) {
+    lines.push(
+      "CREATE SCHEMA IF NOT EXISTS _realtime;",
+      "ALTER SCHEMA _realtime OWNER TO supabase_admin;",
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Kong declarative gateway config (docker/volumes/api/kong.yml). Embedded
+// verbatim with `$VAR` placeholders; substituted below the same way
+// kong-entrypoint.sh does — including the legacy (opaque-keys-disabled) Lua
+// expressions that just pass the `apikey` header/query param straight through.
+// ──────────────────────────────────────────────────────────────────────────
+
+// The two Lua router expressions kong-entrypoint.sh emits when the opaque
+// `sb_`-style keys are NOT configured (our case): pass the incoming apikey (a
+// legacy HS256 JWT) through unchanged, preferring an existing non-`sb_`
+// Authorization header.
+const LUA_AUTH_EXPR =
+  "$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_' and headers.authorization) or headers.apikey)";
+const LUA_RT_WS_EXPR = "$(query_params.apikey)";
+
+const KONG_YML_RAW = String.raw`_format_version: '2.1'
+_transform: true
+
+consumers:
+  - username: DASHBOARD
+  - username: anon
+    keyauth_credentials:
+      - key: $SUPABASE_ANON_KEY
+      - key: $SUPABASE_PUBLISHABLE_KEY
+  - username: service_role
+    keyauth_credentials:
+      - key: $SUPABASE_SERVICE_KEY
+      - key: $SUPABASE_SECRET_KEY
+
+acls:
+  - consumer: anon
+    group: anon
+  - consumer: service_role
+    group: admin
+
+basicauth_credentials:
+  - consumer: DASHBOARD
+    username: '$DASHBOARD_USERNAME'
+    password: '$DASHBOARD_PASSWORD'
+
+services:
+  - name: auth-v1-open
+    url: http://auth:9999/verify
+    routes:
+      - name: auth-v1-open
+        strip_path: true
+        paths:
+          - /auth/v1/verify
+    plugins:
+      - name: cors
+  - name: auth-v1-open-callback
+    url: http://auth:9999/callback
+    routes:
+      - name: auth-v1-open-callback
+        strip_path: true
+        paths:
+          - /auth/v1/callback
+    plugins:
+      - name: cors
+  - name: auth-v1-open-authorize
+    url: http://auth:9999/authorize
+    routes:
+      - name: auth-v1-open-authorize
+        strip_path: true
+        paths:
+          - /auth/v1/authorize
+    plugins:
+      - name: cors
+  - name: auth-v1-open-jwks
+    url: http://auth:9999/.well-known/jwks.json
+    routes:
+      - name: auth-v1-open-jwks
+        strip_path: true
+        paths:
+          - /auth/v1/.well-known/jwks.json
+    plugins:
+      - name: cors
+  - name: auth-v1-open-sso-acs
+    url: "http://auth:9999/sso/saml/acs"
+    routes:
+      - name: auth-v1-open-sso-acs
+        strip_path: true
+        paths:
+        - /auth/v1/sso/saml/acs
+    plugins:
+      - name: cors
+  - name: auth-v1-open-sso-metadata
+    url: "http://auth:9999/sso/saml/metadata"
+    routes:
+      - name: auth-v1-open-sso-metadata
+        strip_path: true
+        paths:
+        - /auth/v1/sso/saml/metadata
+    plugins:
+      - name: cors
+  - name: auth-v1
+    url: http://auth:9999/
+    routes:
+      - name: auth-v1-all
+        strip_path: true
+        paths:
+          - /auth/v1/
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+            - anon
+  - name: rest-v1-openapi
+    url: http://rest:3000/
+    routes:
+      - name: rest-v1-openapi-root
+        strip_path: true
+        expression: 'http.path == "/rest/v1/"'
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+  - name: rest-v1
+    url: http://rest:3000/
+    routes:
+      - name: rest-v1-all
+        strip_path: true
+        paths:
+          - /rest/v1/
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+            - anon
+  - name: graphql-v1
+    url: http://rest:3000/rpc/graphql
+    routes:
+      - name: graphql-v1-all
+        strip_path: true
+        paths:
+          - /graphql/v1
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Content-Profile: graphql_public"
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+            - anon
+  - name: realtime-v1-ws
+    url: http://realtime-dev.supabase-realtime:4000/socket
+    protocol: ws
+    routes:
+      - name: realtime-v1-ws
+        strip_path: true
+        paths:
+          - /realtime/v1/
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "x-api-key:$LUA_RT_WS_EXPR"
+          replace:
+            querystring:
+              - "apikey:$LUA_RT_WS_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+            - anon
+  - name: realtime-v1-rest-openapi
+    url: http://realtime-dev.supabase-realtime:4000/api/openapi
+    protocol: http
+    routes:
+      - name: realtime-v1-rest-openapi
+        strip_path: true
+        paths:
+          - /realtime/v1/api/openapi
+    plugins:
+      - name: request-termination
+        config:
+          status_code: 403
+          message: "Access is forbidden."
+  - name: realtime-v1-rest-tenants
+    url: http://realtime-dev.supabase-realtime:4000/api/tenants
+    protocol: http
+    routes:
+      - name: realtime-v1-rest-tenants
+        strip_path: true
+        paths:
+          - /realtime/v1/api/tenants
+    plugins:
+      - name: request-termination
+        config:
+          status_code: 403
+          message: "Access is forbidden."
+  - name: realtime-v1-rest
+    url: http://realtime-dev.supabase-realtime:4000/api
+    protocol: http
+    routes:
+      - name: realtime-v1-rest
+        strip_path: true
+        paths:
+          - /realtime/v1/api
+    plugins:
+      - name: cors
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+            - anon
+  - name: storage-v1
+    url: http://storage:5000/
+    routes:
+      - name: storage-v1-all
+        strip_path: true
+        paths:
+          - /storage/v1/
+    plugins:
+      - name: cors
+      - name: request-transformer
+        config:
+          add:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+          replace:
+            headers:
+              - "Authorization: $LUA_AUTH_EXPR"
+      - name: post-function
+        config:
+          access:
+            - |
+              local auth = kong.request.get_header("authorization")
+              if auth == nil or auth == "" or auth:find("^%s*$") then
+                kong.service.request.clear_header("authorization")
+              end
+  - name: functions-v1
+    url: http://functions:9000/
+    read_timeout: 150000
+    routes:
+      - name: functions-v1-all
+        strip_path: true
+        paths:
+          - /functions/v1/
+    plugins:
+      - name: cors
+  - name: well-known-oauth
+    url: http://auth:9999/.well-known/oauth-authorization-server
+    routes:
+      - name: well-known-oauth
+        strip_path: true
+        paths:
+          - /.well-known/oauth-authorization-server
+    plugins:
+      - name: cors
+  - name: meta
+    url: http://meta:8080/
+    routes:
+      - name: meta-all
+        strip_path: true
+        paths:
+          - /pg/
+    plugins:
+      - name: key-auth
+        config:
+          hide_credentials: false
+      - name: acl
+        config:
+          hide_groups_header: true
+          allow:
+            - admin
+  - name: dashboard
+    url: http://studio:3000/
+    routes:
+      - name: dashboard-all
+        strip_path: true
+        paths:
+          - /
+    plugins:
+      - name: cors
+      - name: basic-auth
+        config:
+          hide_credentials: true
+`;
+
+/** Produce the final Kong declarative config: rewrite upstream bare hostnames
+ *  to the group's final service DNS names, substitute the API keys / dashboard
+ *  credentials / Lua expressions, and drop the empty opaque-key lines. */
+function buildKongYaml(
+  key: (part: string) => string,
+  vals: {
+    anonKey: string;
+    serviceRoleKey: string;
+    dashboardUsername: string;
+    dashboardPassword: string;
+  },
+): string {
+  let y = KONG_YML_RAW;
+  // Rewrite upstream bare service hosts → the group's final DNS names.
+  y = y
+    .replaceAll("http://auth:9999", `http://${key("auth")}:9999`)
+    .replaceAll("http://rest:3000", `http://${key("rest")}:3000`)
+    .replaceAll("http://storage:5000", `http://${key("storage")}:5000`)
+    .replaceAll("http://meta:8080", `http://${key("meta")}:8080`)
+    .replaceAll("http://studio:3000", `http://${key("studio")}:3000`)
+    .replaceAll("http://functions:9000", `http://${key("functions")}:9000`)
+    .replaceAll("realtime-dev.supabase-realtime", `realtime-dev.${key("realtime")}`);
+  // Lua expressions first (they contain no `$SUPABASE_*` tokens).
+  y = y.replaceAll("$LUA_AUTH_EXPR", LUA_AUTH_EXPR).replaceAll(
+    "$LUA_RT_WS_EXPR",
+    LUA_RT_WS_EXPR,
+  );
+  // API keys + dashboard credentials.
+  y = y
+    .replaceAll("$SUPABASE_ANON_KEY", vals.anonKey)
+    .replaceAll("$SUPABASE_SERVICE_KEY", vals.serviceRoleKey)
+    .replaceAll("$DASHBOARD_USERNAME", vals.dashboardUsername)
+    .replaceAll("$DASHBOARD_PASSWORD", vals.dashboardPassword);
+  // Drop the unconfigured opaque-key credential lines (kong-entrypoint.sh does
+  // the same with a `sed` after substitution).
+  y = y
+    .split("\n")
+    .filter(
+      (line) =>
+        !/^\s*- key:\s*\$SUPABASE_PUBLISHABLE_KEY\s*$/.test(line) &&
+        !/^\s*- key:\s*\$SUPABASE_SECRET_KEY\s*$/.test(line),
+    )
+    .join("\n");
+  return y;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Migration application (runs in the db service's `setup`, after the DB is
+// ready and before any dependent service starts). Uses the setup context's
+// `exec` (docker exec with piped stdin) and `projectRoot` — no hand-rolled
+// child_process, no hard-coded workspace path.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Pipe one SQL file's contents into `psql` inside the db container. Uses
+ *  `psql -f -` (stdin) so multi-statement files and non-transactional DDL
+ *  (e.g. `CREATE INDEX CONCURRENTLY`) behave exactly as `supabase db reset`
+ *  applies them — not wrapped in a single transaction. `ON_ERROR_STOP=1` fails
+ *  fast on the first bad statement. */
+async function applySqlFile(
+  ctx: ServiceSetupContext,
+  sql: string,
+  label: string,
+  user: string,
+): Promise<void> {
+  const res = await ctx.exec(
+    ctx.name,
+    ["psql", "-v", "ON_ERROR_STOP=1", "-U", user, "-d", "postgres", "-f", "-"],
+    { stdin: sql, timeoutMs: 300_000 },
+  );
+  if (res.exitCode !== 0) {
+    throw new Error(
+      `supabase: applying ${label} failed (psql rc=${res.exitCode}):\n${
+        res.stderr.trim() || res.stdout.trim()
+      }`,
+    );
+  }
+}
+
+/** Resolve, sort, and apply the project's Supabase migrations + seed against
+ *  the running db container as the `postgres` role (matching `supabase db
+ *  reset` — tables end up owned by postgres). No-op when nothing is
+ *  configured/present. */
+async function applyMigrations(
+  ctx: ServiceSetupContext,
+  cfg: { migrations: boolean | string; seed: boolean | string },
+): Promise<void> {
+  // Migrations directory.
+  if (cfg.migrations !== false) {
+    const dir =
+      typeof cfg.migrations === "string"
+        ? cfg.migrations.startsWith("/")
+          ? cfg.migrations
+          : join(ctx.projectRoot, cfg.migrations)
+        : join(ctx.projectRoot, "supabase", "migrations");
+    if (existsSync(dir) && (await stat(dir)).isDirectory()) {
+      const files = (await readdir(dir))
+        .filter((f) => f.endsWith(".sql"))
+        .sort();
+      for (const f of files) {
+        const sql = await ctx.readProjectFile(join(dir, f));
+        await applySqlFile(ctx, sql, `migration ${f}`, "postgres");
+      }
+    }
+  }
+  // Seed file.
+  if (cfg.seed !== false) {
+    const seedPath =
+      typeof cfg.seed === "string"
+        ? cfg.seed.startsWith("/")
+          ? cfg.seed
+          : join(ctx.projectRoot, cfg.seed)
+        : join(ctx.projectRoot, "supabase", "seed.sql");
+    if (existsSync(seedPath)) {
+      const sql = await ctx.readProjectFile(seedPath);
+      await applySqlFile(ctx, sql, "seed.sql", "postgres");
+    }
+  }
+}
+
+/**
+ * A ready-to-use self-hosted Supabase stack. Mount `.group` at the key
+ * matching the `name` option (default `"supabase"`) and wire the app with
+ * `.appEnv` / `.ready`:
+ *
+ * ```ts
+ * const sb = supabase({ dbPassword: "postgres" });
+ * services: { supabase: sb.group, app: { image, env: sb.appEnv, dependsOn: [sb.ready] } }
+ * ```
+ *
+ * See the file header for the full picture. Tests get an instrumented DB client
+ * at `ctx.svc.<name>.sql` plus `sb.url` / `sb.anonKey` / `sb.serviceRoleKey`
+ * for hitting the REST/auth/storage APIs through the gateway.
+ */
+export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
+  const name = opts.name ?? "supabase";
+  const dbPassword = opts.dbPassword ?? "postgres";
+  const jwtSecret = opts.jwtSecret ?? DEFAULT_JWT_SECRET;
+  if (jwtSecret.length < 32) {
+    throw new Error(
+      `supabase(): jwtSecret must be at least 32 characters (got ${jwtSecret.length})`,
+    );
+  }
+  const dashboardUsername = opts.dashboardUsername ?? "supabase";
+  const dashboardPassword =
+    opts.dashboardPassword ?? "this_password_is_insecure_and_should_be_updated";
+
+  const withAuth = opts.auth ?? true;
+  const withStorage = opts.storage ?? true;
+  const withRealtime = opts.realtime ?? true;
+  const withStudio = opts.studio ?? false;
+  const withMeta = opts.meta ?? withStudio;
+
+  const anonKey = apiKey("anon", jwtSecret);
+  const serviceRoleKey = apiKey("service_role", jwtSecret);
+
+  // Derived surface, embedded in `appEnv` / `url` before the group expands.
+  // `expectKey: name` on the group guarantees these names and the expanded
+  // service keys agree (`g.key("db")` at expansion === `${name}-db` here).
+  const dbKey = `${name}-db`;
+  const url = opts.hostname ? `https://${opts.hostname}` : `http://${name}:8000`;
+  // App-facing URL: the conventional `postgres` role (owns migrated tables).
+  const dbUrl = `postgresql://postgres:${dbPassword}@${dbKey}:5432/postgres`;
+  // The test-side `ctx.svc.<name>.sql` helper connects as the superuser
+  // `supabase_admin` so it can inspect everything — public tables plus the
+  // `auth`/`storage` schemas — regardless of ownership.
+  const adminDbUrl = `postgresql://supabase_admin:${dbPassword}@${dbKey}:5432/postgres`;
+
+  const group = serviceGroup({
+    // Kong: the group key itself is the gateway (`http://<name>:8000`), and
+    // as the primary it's the group's sink — `dependsOn: [sb.ready]` from
+    // outside waits for the whole stack.
+    primary: "gateway",
+    expectKey: name,
+    services: (g) => {
+      const db = g.key("db");
+      // Realtime derives its tenant id from the host subdomain, so it must
+      // be reachable at `realtime-dev.<realtime key>` — the host Kong
+      // routes to.
+      const realtimeHost = `realtime-dev.${g.key("realtime")}`;
+      const parts: Record<string, ServiceConfig> = {};
+
+      // ── db ──────────────────────────────────────────────────────────
+      const dbDef: ServiceDefinition = {
+        image: { type: "registry", reference: IMAGES.db },
+        // `args` (not `command`): keep the image's docker-entrypoint.sh so it
+        // runs initdb + its baked init-scripts before starting.
+        args: [
+          "postgres",
+          "-c",
+          "config_file=/etc/postgresql/postgresql.conf",
+          "-c",
+          "log_min_messages=fatal",
+        ],
+        env: {
+          POSTGRES_HOST: "/var/run/postgresql",
+          PGPORT: "5432",
+          POSTGRES_PORT: "5432",
+          PGPASSWORD: dbPassword,
+          POSTGRES_PASSWORD: dbPassword,
+          PGDATABASE: "postgres",
+          POSTGRES_DB: "postgres",
+          JWT_SECRET: jwtSecret,
+          JWT_EXP: "3600",
+        },
+        ports: [5432],
+        // `pg_isready` succeeds only once the image finishes initdb + its
+        // baked init-scripts and starts serving for real.
+        readyCheck: { type: "exec", command: "pg_isready -U postgres -h 127.0.0.1 -p 5432", timeoutSecs: 180 },
+        setup: async (ctx) => {
+          // Bootstrap first (role passwords / JWT GUC / _realtime schema),
+          // then the project's own migrations + seed — both before any
+          // dependent service.
+          await applySqlFile(
+            ctx,
+            buildBootstrapSql(dbPassword, jwtSecret, withRealtime),
+            "supabase bootstrap",
+            // The bootstrap alters reserved roles (authenticator, …) and the
+            // database — superuser-only. `postgres` is deliberately NOT a
+            // superuser in modern supabase/postgres; `supabase_admin` is.
+            "supabase_admin",
+          );
+          await applyMigrations(ctx, {
+            migrations: opts.migrations ?? true,
+            seed: opts.seed ?? true,
+          });
+        },
+      };
+      parts.db = dbDef;
+
+      // ── rest (PostgREST) ────────────────────────────────────────────
+      parts.rest = {
+        image: { type: "registry", reference: IMAGES.rest },
+        env: {
+          PGRST_DB_URI: `postgres://authenticator:${dbPassword}@${db}:5432/postgres`,
+          PGRST_DB_SCHEMAS: "public,graphql_public",
+          PGRST_DB_ANON_ROLE: "anon",
+          PGRST_JWT_SECRET: jwtSecret,
+          PGRST_DB_USE_LEGACY_GUCS: "false",
+          PGRST_APP_SETTINGS_JWT_SECRET: jwtSecret,
+          PGRST_APP_SETTINGS_JWT_EXP: "3600",
+          PGRST_ADMIN_SERVER_PORT: "3001",
+          PGRST_DB_MAX_ROWS: "1000",
+          PGRST_DB_EXTRA_SEARCH_PATH: "public",
+        },
+        ports: [3000],
+        dependsOn: ["db"],
+        // PostgREST opens :3000 only after connecting to the DB and loading
+        // the schema cache, so a TCP connect is a good ready signal.
+        readyCheck: { type: "tcp", port: 3000, timeoutSecs: 120 },
+      };
+
+      // ── auth (GoTrue) ───────────────────────────────────────────────
+      if (withAuth) {
+        const apiExternalUrl = `${url}/auth/v1`;
+        parts.auth = {
+          image: { type: "registry", reference: IMAGES.auth },
+          env: {
+            GOTRUE_API_HOST: "0.0.0.0",
+            GOTRUE_API_PORT: "9999",
+            API_EXTERNAL_URL: apiExternalUrl,
+            GOTRUE_DB_DRIVER: "postgres",
+            GOTRUE_DB_DATABASE_URL: `postgres://supabase_auth_admin:${dbPassword}@${db}:5432/postgres`,
+            GOTRUE_SITE_URL: url,
+            GOTRUE_URI_ALLOW_LIST: "*",
+            GOTRUE_DISABLE_SIGNUP: "false",
+            GOTRUE_JWT_ADMIN_ROLES: "service_role",
+            GOTRUE_JWT_AUD: "authenticated",
+            GOTRUE_JWT_DEFAULT_GROUP_NAME: "authenticated",
+            GOTRUE_JWT_EXP: "3600",
+            GOTRUE_JWT_SECRET: jwtSecret,
+            GOTRUE_JWT_ISSUER: apiExternalUrl,
+            GOTRUE_EXTERNAL_EMAIL_ENABLED: "true",
+            GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED: "true",
+            // Autoconfirm so tests can sign up without a mail server
+            // round-trip.
+            GOTRUE_MAILER_AUTOCONFIRM: "true",
+            GOTRUE_EXTERNAL_PHONE_ENABLED: "false",
+            GOTRUE_SMS_AUTOCONFIRM: "true",
+          },
+          ports: [9999],
+          dependsOn: ["db"],
+          readyCheck: { type: "http", port: 9999, path: "/health", timeoutSecs: 90 },
+        };
+      }
+
+      // ── storage (+ imgproxy) ────────────────────────────────────────
+      if (withStorage) {
+        // Named shared volume so imgproxy can read what storage-api wrote —
+        // one backing dir mounted by both containers, snapshot/fork- and
+        // teardown-managed like any other volume.
+        const storageData = { name: `${g.name}-storage-data`, target: "/var/lib/storage" };
+        parts.imgproxy = {
+          image: { type: "registry", reference: IMAGES.imgproxy },
+          env: {
+            IMGPROXY_BIND: ":5001",
+            IMGPROXY_LOCAL_FILESYSTEM_ROOT: "/",
+            IMGPROXY_USE_ETAG: "true",
+            IMGPROXY_AUTO_WEBP: "true",
+            IMGPROXY_MAX_SRC_RESOLUTION: "16.8",
+          },
+          volumes: [storageData],
+          ports: [5001],
+          readyCheck: { type: "tcp", port: 5001, timeoutSecs: 60 },
+        };
+        parts.storage = {
+          image: { type: "registry", reference: IMAGES.storage },
+          env: {
+            ANON_KEY: anonKey,
+            SERVICE_KEY: serviceRoleKey,
+            POSTGREST_URL: `http://${g.key("rest")}:3000`,
+            AUTH_JWT_SECRET: jwtSecret,
+            DATABASE_URL: `postgres://supabase_storage_admin:${dbPassword}@${db}:5432/postgres`,
+            STORAGE_PUBLIC_URL: url,
+            REQUEST_ALLOW_X_FORWARDED_PATH: "true",
+            FILE_SIZE_LIMIT: "52428800",
+            STORAGE_BACKEND: "file",
+            GLOBAL_S3_BUCKET: "stub",
+            FILE_STORAGE_BACKEND_PATH: "/var/lib/storage",
+            TENANT_ID: "stub",
+            REGION: "stub",
+            ENABLE_IMAGE_TRANSFORMATION: "true",
+            IMGPROXY_URL: `http://${g.key("imgproxy")}:5001`,
+            S3_PROTOCOL_ACCESS_KEY_ID: "625729a08b95bf1b7ff351a663f3a23c",
+            S3_PROTOCOL_ACCESS_KEY_SECRET:
+              "850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907",
+          },
+          volumes: [storageData],
+          ports: [5000],
+          dependsOn: ["db", "rest", "imgproxy"],
+          readyCheck: { type: "http", port: 5000, path: "/status", timeoutSecs: 90 },
+        };
+      }
+
+      // ── realtime ────────────────────────────────────────────────────
+      if (withRealtime) {
+        parts.realtime = {
+          image: { type: "registry", reference: IMAGES.realtime },
+          // Extra peer alias so Kong (and the tenant-subdomain parser)
+          // reaches it at `realtime-dev.<realtime key>`.
+          hostnames: [realtimeHost],
+          env: {
+            PORT: "4000",
+            DB_HOST: db,
+            DB_PORT: "5432",
+            DB_USER: "supabase_admin",
+            DB_PASSWORD: dbPassword,
+            DB_NAME: "postgres",
+            DB_AFTER_CONNECT_QUERY: "SET search_path TO _realtime",
+            DB_ENC_KEY: "supabaserealtime",
+            API_JWT_SECRET: jwtSecret,
+            METRICS_JWT_SECRET: jwtSecret,
+            SECRET_KEY_BASE:
+              "UpNVntn3cDxHJpq99YMc1T1AQgQpc8kfYTuRgBiYa15BLrx8etQoXz3gZv1/u2oq",
+            ERL_AFLAGS: "-proto_dist inet_tcp",
+            DNS_NODES: "''",
+            RLIMIT_NOFILE: "10000",
+            APP_NAME: "realtime",
+            SEED_SELF_HOST: "true",
+            RUN_JANITOR: "true",
+            DISABLE_HEALTHCHECK_LOGGING: "true",
+          },
+          ports: [4000],
+          dependsOn: ["db"],
+          // The health endpoint wants a valid JWT — `headers` keeps the
+          // probe image-agnostic (no curl-in-image dependency).
+          readyCheck: {
+            type: "http",
+            port: 4000,
+            path: "/api/tenants/realtime-dev/health",
+            headers: { Authorization: `Bearer ${anonKey}` },
+            timeoutSecs: 120,
+          },
+        };
+      }
+
+      // ── meta (postgres-meta) ────────────────────────────────────────
+      if (withMeta) {
+        parts.meta = {
+          image: { type: "registry", reference: IMAGES.meta },
+          env: {
+            PG_META_PORT: "8080",
+            PG_META_DB_HOST: db,
+            PG_META_DB_PORT: "5432",
+            PG_META_DB_NAME: "postgres",
+            PG_META_DB_USER: "postgres",
+            PG_META_DB_PASSWORD: dbPassword,
+            CRYPTO_KEY: "your-encryption-key-32-chars-min",
+          },
+          ports: [8080],
+          dependsOn: ["db"],
+          readyCheck: { type: "tcp", port: 8080, timeoutSecs: 90 },
+        };
+      }
+
+      // ── studio ──────────────────────────────────────────────────────
+      if (withStudio) {
+        parts.studio = {
+          image: { type: "registry", reference: IMAGES.studio },
+          env: {
+            HOSTNAME: "0.0.0.0",
+            STUDIO_PG_META_URL: `http://${g.key("meta")}:8080`,
+            POSTGRES_PORT: "5432",
+            POSTGRES_HOST: db,
+            POSTGRES_DB: "postgres",
+            POSTGRES_PASSWORD: dbPassword,
+            POSTGRES_USER_READ_WRITE: "postgres",
+            PG_META_CRYPTO_KEY: "your-encryption-key-32-chars-min",
+            PGRST_DB_SCHEMAS: "public,graphql_public",
+            DEFAULT_ORGANIZATION_NAME: "Default Organization",
+            DEFAULT_PROJECT_NAME: "Default Project",
+            SUPABASE_URL: `http://${g.name}:8000`,
+            SUPABASE_PUBLIC_URL: url,
+            SUPABASE_ANON_KEY: anonKey,
+            SUPABASE_SERVICE_KEY: serviceRoleKey,
+            AUTH_JWT_SECRET: jwtSecret,
+          },
+          ports: [3000],
+          dependsOn: ["meta"],
+          readyCheck: {
+            type: "http",
+            port: 3000,
+            path: "/api/platform/profile",
+            timeoutSecs: 180,
+          },
+        };
+      }
+
+      // ── kong (gateway / primary) — no explicit dependsOn: the group
+      // expansion makes the primary depend on every member ──────────────
+      parts.gateway = {
+        image: { type: "registry", reference: IMAGES.kong },
+        env: {
+          KONG_DATABASE: "off",
+          KONG_DECLARATIVE_CONFIG: "/home/kong/kong.yml",
+          KONG_ROUTER_FLAVOR: "expressions",
+          KONG_DNS_ORDER: "LAST,A,CNAME",
+          KONG_DNS_NOT_FOUND_TTL: "1",
+          KONG_PLUGINS:
+            "request-transformer,cors,key-auth,acl,basic-auth,request-termination,ip-restriction,post-function",
+          KONG_NGINX_PROXY_PROXY_BUFFER_SIZE: "160k",
+          KONG_NGINX_PROXY_PROXY_BUFFERS: "64 160k",
+        },
+        files: [
+          {
+            path: "/home/kong/kong.yml",
+            content: buildKongYaml(g.key, {
+              anonKey,
+              serviceRoleKey,
+              dashboardUsername,
+              dashboardPassword,
+            }),
+          },
+        ],
+        ports: [8000, 8443],
+        ...(opts.hostname ? { tls: [{ hostname: opts.hostname, port: 8000 }] } : {}),
+        readyCheck: { type: "exec", command: "kong health", timeoutSecs: 90 },
+      };
+
+      return parts;
+    },
+    // The group's consolidated handle at `ctx.svc.<name>`.
+    helpers: (): SupabaseHelpers => ({
+      sql: new SQL(adminDbUrl, { label: name }),
+      url,
+      anonKey,
+      serviceRoleKey,
+    }),
+  });
+
+  const appEnv = {
+    SUPABASE_URL: url,
+    SUPABASE_ANON_KEY: anonKey,
+    SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
+    DATABASE_URL: dbUrl,
+  };
+
+  return {
+    group,
+    url,
+    anonKey,
+    serviceRoleKey,
+    dbUrl,
+    ready: name,
+    appEnv,
+  };
+}