@specific.dev/spectest 0.38.0 → 0.41.0

package/src/components/supabase.ts

@@ -0,0 +1,1699 @@
+// 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 { dirname, 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";
+import { email, emailHelpers, type EmailHelpers } from "./email.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",
+  functions: "supabase/edge-runtime:v1.74.0",
+} as const;
+
+/**
+ * The project root inside the VM. A service's `volumes[].source` is a static
+ * string in the wire config, so the edge runtime's bind mount cannot go
+ * through `ctx.projectRoot` (which only exists once a hook runs) — this is
+ * the same value, read the same way the harness reads it.
+ */
+function projectRootPath(): string {
+  return process.env.SPECTEST_WORKSPACE ?? "/workspace";
+}
+
+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;
+
+  /**
+   * Capture GoTrue's outgoing mail (signup confirmations, magic links, OTPs,
+   * password recovery, invites) with the standard `email()` component. **On
+   * by default**: the stack includes the capture server (`<name>-mail`) with
+   * GoTrue's SMTP wired at it, and tests read the mailbox through the typed
+   * helpers at `ctx.svc.<name>.mail` (`lastEmail` / `emails` / `clear`), each
+   * captured message rendering mail-client-style on the dashboard timeline.
+   *
+   * Signups complete in **one step** by default (`autoconfirm: true`), so
+   * the mailbox is purely additive and a suite that just needs accounts
+   * writes nothing extra. Pass `{ autoconfirm: false }` to run the real
+   * confirmation flow instead — the signup then issues no session until a
+   * test follows the emailed link out of the mailbox. Pass
+   * `{ service: "<key>" }` to point GoTrue at
+   * an `email()` service the environment already declares — keep a single
+   * mailbox per environment rather than one per component: if the app under
+   * test also sends mail, share one `email()` between it and Supabase
+   * instead of standing up a second capture server. `false` disables mail
+   * capture entirely.
+   */
+  mail?: boolean | SupabaseMailOptions;
+
+  /**
+   * Extra API keys the gateway accepts alongside the derived JWT keys — for
+   * clients that ship a hardcoded key (e.g. an `sb_publishable_…` /
+   * `sb_secret_…` pair baked into an app build). Each `anon` key is admitted
+   * with anon privileges and each `serviceRole` key with service-role
+   * privileges; Kong swaps the matching *derived JWT* in before proxying, so
+   * GoTrue/PostgREST/Realtime still receive a validly-signed token.
+   */
+  extraApiKeys?: { anon?: string[]; serviceRole?: string[] };
+
+  /**
+   * Where the project's SQL migrations live, e.g. `"supabase/migrations"`
+   * (relative to the project root, or absolute). **Nothing is applied unless
+   * you set this** — there is no assumed path, so a project whose schema
+   * arrives some other way (an app that migrates itself at boot, a dump
+   * restored in `setup`) never gets a second, surprising source of DDL.
+   *
+   * Every `*.sql` directly in the directory is applied in sorted filename
+   * order, then — the standard Supabase layout — the **`seed.sql` beside
+   * that directory**, if there is one:
+   *
+   * ```
+   * supabase/
+   *   migrations/0001_init.sql   ← applied, sorted
+   *   migrations/0002_todos.sql
+   *   seed.sql                   ← applied last
+   * ```
+   *
+   * It all runs **once the whole stack is up** — the same point `supabase db
+   * reset` applies migrations — so your SQL may use schema the services
+   * create when they boot (`storage.buckets`, the modern `auth.*` tables).
+   * PostgREST's schema cache is reloaded afterwards.
+   *
+   * A path that doesn't resolve is an error at env start; a silent no-op
+   * there surfaces much later as a confusing `relation … does not exist`.
+   * Because `supabase/**` is project content, editing a migration correctly
+   * forces a cold rebuild and re-apply (unlike `spectest/tests/**`).
+   */
+  migrations?: string;
+
+  /**
+   * Where the project's **edge functions** live, e.g.
+   * `"supabase/functions"` — one subdirectory per function, each with an
+   * entrypoint the runtime can serve (`supabase/functions/hello/index.ts`).
+   *
+   * **Nothing runs unless you set this.** Point at the directory and every
+   * function in it is served on the real Supabase edge runtime at
+   * `<url>/functions/v1/<name>` through the gateway — the same path
+   * `supabase.functions.invoke(...)` derives, so the app under test needs no
+   * override. Leave it unset and the runtime is left out of the stack
+   * entirely, along with the gateway's `/functions/v1` route.
+   *
+   * Function code is read straight from the repo — nothing is copied or
+   * bundled — so editing a function is an ordinary project edit.
+   *
+   * Pass an object instead of a path to turn JWT verification off, or to set
+   * the function secrets your code reads with `Deno.env.get(...)`.
+   */
+  functions?: string | SupabaseFunctionsOptions;
+}
+
+/** Tuning for `SupabaseOptions.functions`. */
+export interface SupabaseFunctionsOptions {
+  /**
+   * Directory holding one subdirectory per function, relative to the project
+   * root (or absolute). Required — there is no assumed location.
+   */
+  dir: string;
+  /**
+   * Reject a call that carries no valid JWT, exactly as hosted Supabase
+   * does. Default `true` — so a test that forgets the `Authorization`
+   * header fails here instead of in production. Set `false` for the
+   * `--no-verify-jwt` behaviour (webhooks, public endpoints).
+   */
+  verifyJwt?: boolean;
+  /**
+   * Extra environment variables the functions read (`Deno.env.get("…")`) —
+   * the local stand-in for function secrets. `SUPABASE_URL`,
+   * `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_DB_URL` and
+   * `JWT_SECRET` are already set for you.
+   */
+  env?: Record<string, string>;
+}
+
+/** Tuning for `SupabaseOptions.mail`. */
+export interface SupabaseMailOptions {
+  /**
+   * Reuse an `email()` service the environment already declares (its
+   * services-map key) instead of adding one to the group — the way to keep a
+   * single global mailbox when the app under test sends mail too. Assumes
+   * the service's default ports (SMTP 1025, API 8025).
+   */
+  service?: string;
+  /**
+   * Whether GoTrue confirms a signup without the emailed verification.
+   * **`true` by default**: signups complete in one step and send no
+   * confirmation mail, which keeps account creation a single call in the
+   * suites where it is setup rather than the thing under test.
+   *
+   * Set `false` to run the flow a hosted project runs: the signup issues no
+   * session, and the test follows the emailed link out of the mailbox
+   * exactly as a user would (see `examples/supabase-app`). Recovery,
+   * magic-link, OTP and invite mail is sent either way. Forced `true` when
+   * the stack has no mailbox (`mail: false`), since the confirmation would
+   * go nowhere.
+   */
+  autoconfirm?: boolean;
+  /** Sender address GoTrue mails from. Default `admin@example.com`. */
+  adminEmail?: string;
+  /** Sender display name. Default `Supabase`. */
+  senderName?: 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;
+  /**
+   * The captured-mail mailbox (`lastEmail` / `emails` / `clear`) — present
+   * unless the stack was built with `mail: false`. Wait for delivery with
+   * the standard `ctx.poll`:
+   *
+   * ```ts
+   * const mail = await ctx.poll("confirmation email", () =>
+   *   ctx.svc.supabase.mail!.lastEmail());
+   * expect(mail.to).toContain("alice@example.com");
+   * ```
+   */
+  mail?: EmailHelpers;
+}
+
+/** 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;
+  /**
+   * Where the stack's SMTP capture server listens (absent with
+   * `mail: false`) — point the app under test's own mail transport here to
+   * share the one mailbox: `env: { SMTP_HOST: sb.smtp.host, SMTP_PORT: String(sb.smtp.port) }`.
+   */
+  smtp?: { host: string; port: number };
+  /** 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: pass the incoming apikey (a legacy
+// HS256 JWT) through unchanged, preferring an existing non-`sb_`
+// Authorization header. `extraApiKeys` extends both: an extra key (arriving
+// as `apikey` header, `Authorization: Bearer <key>`, or the websocket
+// `?apikey=` query param) is swapped for the corresponding *derived JWT*
+// before proxying, so the upstream services still see a validly-signed token.
+//
+// SPECTEST DEVIATION — the `apikey` **query parameter** is a first-class
+// credential here, not just a websocket one. Kong's key-auth already accepts
+// it (`key_in_query` defaults on), but upstream saw only the header, so a
+// query-param request reached PostgREST as the anon role. A browser is the
+// reason this matters: `browser.goto(url)` sends no headers, so a top-level
+// navigation to a gated URL can carry a key ONLY in the query string (and a
+// 401 there surfaces as Chromium's opaque `ERR_INVALID_AUTH_CREDENTIALS`,
+// not a status code).
+//
+// The rest/graphql routes additionally `remove.querystring: [apikey]` in
+// their request-transformer, because PostgREST reads every unknown query
+// parameter as a column filter and answers `400 PGRST100` on the leftover
+// key. `hide_credentials: true` on key-auth would strip it (and the header)
+// far earlier — before this request-transformer runs — which would break
+// both the header swap above and the realtime websocket route, whose own
+// expression reads `query_params.apikey`. So the strip belongs here, on the
+// one upstream that cannot tolerate the parameter.
+//
+// MEASURED CONSEQUENCE — request-transformer removes the query parameter
+// BEFORE it renders the Authorization template, so on `/rest/v1` the JWT
+// never reaches PostgREST and the request runs as **anon**, whichever key
+// was sent. Verified against an RLS-protected table: the service-role key
+// as a header returned the row, the same key in the query returned `[]`.
+// Anon is the right privilege for the browser navigation this exists for;
+// anything needing service-role must send the header.
+function buildLuaExprs(
+  extra: Array<{ key: string; jwt: string }>,
+): { auth: string; realtimeWs: string } {
+  // Keep a client's `Authorization: Bearer <extraKey>` from winning the
+  // header-passthrough clause with the raw (non-JWT) key.
+  const guards = extra
+    .map((m) => ` and headers.authorization ~= 'Bearer ${m.key}'`)
+    .join("");
+  const mappings = extra
+    .map(
+      (m) =>
+        ` or ((headers.apikey == '${m.key}' or headers.authorization == 'Bearer ${m.key}' or query_params.apikey == '${m.key}') and 'Bearer ${m.jwt}')`,
+    )
+    .join("");
+  const auth = `$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_'${guards} and headers.authorization)${mappings} or headers.apikey or query_params.apikey)`;
+  const wsMappings = extra
+    .map((m) => `(query_params.apikey == '${m.key}' and '${m.jwt}') or `)
+    .join("");
+  return { auth, realtimeWs: `$(${wsMappings}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"
+          remove:
+            querystring:
+              - apikey
+      - 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"
+          remove:
+            querystring:
+              - apikey
+      - 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"
+          remove:
+            querystring:
+              - apikey
+      - 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
+  # >>> functions (dropped when the edge runtime is off)
+  - name: functions-v1
+    url: http://functions:9000/
+    read_timeout: 150000
+    routes:
+      - name: functions-v1-all
+        strip_path: true
+        paths:
+          - /functions/v1/
+    plugins:
+      - name: cors
+  # <<< functions
+  - 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
+`;
+
+// ──────────────────────────────────────────────────────────────────────────
+// Edge functions — the runtime's "main service": the request router that
+// spawns one user worker per function directory.
+//
+// Upstream ships an equivalent file in the repo the user is expected to copy
+// (`docker/volumes/functions/main/index.ts`). We inject our own instead, for
+// two reasons: the project's `supabase/functions/` holds the user's
+// functions and should not need a `main/` of ours in it; and upstream's
+// router imports `jsr:@panva/jose` at boot, which is a network fetch inside
+// an otherwise hermetic VM. HS256 is the only algorithm this stack signs
+// with, and Web Crypto verifies it in a few lines with no dependency.
+// ──────────────────────────────────────────────────────────────────────────
+
+const FUNCTIONS_MAIN_TS = String.raw`// spectest-generated edge-functions router. Do not edit.
+const FUNCTIONS_DIR = "/home/deno/functions";
+const JWT_SECRET = Deno.env.get("JWT_SECRET") ?? "";
+const VERIFY_JWT = Deno.env.get("VERIFY_JWT") === "true";
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function base64UrlToBytes(s: string): Uint8Array {
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// HS256 only — every token this stack mints (the anon/service-role API keys
+// and every GoTrue access token) is signed with the shared JWT secret.
+async function validJwt(token: string): Promise<boolean> {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !JWT_SECRET) return false;
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(JWT_SECRET),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"],
+    );
+    const signed = new TextEncoder().encode(parts[0] + "." + parts[1]);
+    if (!(await crypto.subtle.verify("HMAC", key, base64UrlToBytes(parts[2]), signed))) {
+      return false;
+    }
+    const claims = JSON.parse(new TextDecoder().decode(base64UrlToBytes(parts[1])));
+    if (typeof claims.exp === "number" && claims.exp * 1000 < Date.now()) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+Deno.serve(async (req: Request) => {
+  const { pathname } = new URL(req.url);
+
+  // Ready probe — answered before any auth check, so bring-up never needs a
+  // token, and never treated as a function name.
+  if (pathname === "/_spectest/health") return new Response("ok");
+
+  const name = pathname.split("/")[1] ?? "";
+  if (name === "") return json({ msg: "missing function name in request" }, 400);
+
+  if (VERIFY_JWT && req.method !== "OPTIONS") {
+    const header = req.headers.get("authorization") ?? "";
+    const [scheme, token] = header.split(" ");
+    if (scheme !== "Bearer" || !token || !(await validJwt(token))) {
+      return json({ msg: "Invalid JWT" }, 401);
+    }
+  }
+
+  const servicePath = FUNCTIONS_DIR + "/" + name;
+  try {
+    const worker = await EdgeRuntime.userWorkers.create({
+      servicePath,
+      memoryLimitMb: 256,
+      workerTimeoutMs: 5 * 60 * 1000,
+      noModuleCache: false,
+      importMapPath: null,
+      envVars: Object.entries(Deno.env.toObject()),
+    });
+    return await worker.fetch(req);
+  } catch (e) {
+    // A missing directory lands here too, so say which function was asked
+    // for — the runtime's own message names only the path.
+    return json({ msg: String(e), function: name, servicePath }, 500);
+  }
+});
+`;
+
+/** Keep or drop a `# >>> <tag>` … `# <<< <tag>` block, and always remove the
+ *  marker lines themselves. */
+function stripMarkedBlock(yaml: string, tag: string, keep: boolean): string {
+  const out: string[] = [];
+  let inside = false;
+  for (const line of yaml.split("\n")) {
+    if (line.trim().startsWith(`# >>> ${tag}`)) {
+      inside = true;
+      continue;
+    }
+    if (line.trim().startsWith(`# <<< ${tag}`)) {
+      inside = false;
+      continue;
+    }
+    if (inside && !keep) continue;
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/** 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;
+    extraAnonKeys: string[];
+    extraServiceRoleKeys: string[];
+    /** Is the edge runtime part of this stack? When it isn't, the
+     *  `/functions/v1` route is dropped rather than left pointing at a
+     *  service that doesn't exist: a call then falls through to the
+     *  gateway's catch-all and is rejected there (measured: 401), instead
+     *  of proxying to an unresolvable host. */
+    functions: boolean;
+  },
+): string {
+  let y = KONG_YML_RAW;
+  y = stripMarkedBlock(y, "functions", vals.functions);
+  // Extra API keys land where kong-entrypoint.sh's opaque keys would: as
+  // additional keyauth credentials on the matching consumer. The template's
+  // placeholder lines are either expanded here or dropped by the filter below.
+  if (vals.extraAnonKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_PUBLISHABLE_KEY",
+      vals.extraAnonKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
+  if (vals.extraServiceRoleKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_SECRET_KEY",
+      vals.extraServiceRoleKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
+  // 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).
+  const lua = buildLuaExprs([
+    ...vals.extraAnonKeys.map((k) => ({ key: k, jwt: vals.anonKey })),
+    ...vals.extraServiceRoleKeys.map((k) => ({ key: k, jwt: vals.serviceRoleKey })),
+  ]);
+  y = y.replaceAll("$LUA_AUTH_EXPR", lua.auth).replaceAll(
+    "$LUA_RT_WS_EXPR",
+    lua.realtimeWs,
+  );
+  // 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 **group's** `setup`, which chains after
+// the primary (the gateway), and the gateway is the group's dependency sink
+// — so by then every service is up and has finished its own bootstrap. That
+// ordering is the whole point:
+//
+//   Several services own schema of their own and create it when THEY boot,
+//   not when the database does. storage-api creates `storage.buckets` /
+//   `storage.objects`; GoTrue creates the modern `auth.*` tables
+//   (`identities`, `sessions`, `mfa_*`, `one_time_tokens`); realtime creates
+//   its own. The stock `supabase/postgres` image ships only the legacy auth
+//   stubs (`auth.users` and friends) and nothing at all under `storage`.
+//
+//   Applied any earlier, an ordinary migration — `insert into
+//   storage.buckets`, a policy on `auth.identities` — fails with `relation
+//   … does not exist`, and the error points at the user's SQL rather than at
+//   the ordering. This is also the point at which `supabase db reset`
+//   applies migrations: against a stack that is already running.
+//
+// The database's OWN bootstrap (roles, JWT GUC, `_realtime` schema) stays in
+// the db service's `setup`, because the other services need it to start at
+// all.
+//
+// Uses the setup context's `exec` (docker exec with piped stdin) and
+// `projectRoot` — no hand-rolled child_process, no hard-coded workspace path.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Either setup hook's context: the db part's (no helpers) or the group's
+ *  (the consolidated handle). Nothing below reads `helpers`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SetupCtx = ServiceSetupContext<any>;
+
+/** 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: SetupCtx,
+  sql: string,
+  label: string,
+  user: string,
+  /** The db service to run `psql` in. Defaults to the hook's own service,
+   *  which is the db only for the bootstrap; the project's migrations run
+   *  from the group hook, where `ctx.name` is the gateway. */
+  service: string = ctx.name,
+): Promise<void> {
+  const res = await ctx.exec(
+    service,
+    ["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 — and the
+ *  `seed.sql` the standard layout puts beside them — against the running db
+ *  container as the `postgres` role (matching `supabase db reset`: tables end
+ *  up owned by postgres).
+ *
+ *  Only ever called with a path the user gave: there is no assumed location,
+ *  so this never applies SQL nobody asked for. */
+async function applyMigrations(
+  ctx: SetupCtx,
+  migrations: string,
+  /** Where `psql` runs — the db part, named from the group hook. */
+  db: string,
+): Promise<void> {
+  const dir = migrations.startsWith("/")
+    ? migrations
+    : join(ctx.projectRoot, migrations);
+  // A path that doesn't resolve is a hard error: a silent no-op here
+  // surfaces much later as a baffling `relation "public.…" does not exist`.
+  if (!existsSync(dir) || !(await stat(dir)).isDirectory()) {
+    throw new Error(
+      `supabase: migrations path ${JSON.stringify(migrations)} does not ` +
+        `resolve to a directory (looked at ${dir}). The path is resolved ` +
+        `inside the uploaded project — check it isn't ignored (e.g. via ` +
+        `.spectestignore).`,
+    );
+  }
+
+  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", db);
+  }
+
+  // `seed.sql` sits next to the migrations directory in the layout the
+  // Supabase CLI creates, so it needs no option of its own — pointing at
+  // the migrations is enough to say where the project's SQL lives. Absent
+  // is fine: plenty of projects have migrations and no seed.
+  const seedPath = join(dirname(dir), "seed.sql");
+  if (existsSync(seedPath)) {
+    const sql = await ctx.readProjectFile(seedPath);
+    await applySqlFile(ctx, sql, "seed.sql", "postgres", db);
+  }
+}
+
+/**
+ * Make PostgREST serve the schema the migrations just created, and do not
+ * return until it does so **stably**.
+ *
+ * PostgREST reads the schema once, at boot, and now boots before the
+ * project's migrations run. Without this, the first REST call for a new
+ * table answers `PGRST205 Could not find the table` — the failure the user
+ * would otherwise have to diagnose and work around themselves.
+ *
+ * Two things make this more than one request:
+ *
+ *  - **A rebuild is not atomic from the outside.** While PostgREST reloads,
+ *    a request can still miss the table. So a single successful check is not
+ *    proof; the cache has to answer correctly several times in a row.
+ *  - **Reloads are already in flight.** The `supabase/postgres` image ships
+ *    `pgrst_ddl_watch`, an event trigger that notifies on every DDL, so a
+ *    migration run queues several reloads of its own. Ours goes *first* and
+ *    the settle loop then waits them all out — checking before sending the
+ *    notify was a real bug: the poll passed, our own notify landed after it,
+ *    and a test raced the rebuild it caused.
+ *
+ * The expectation comes from the database itself: every base table in the
+ * exposed `public` schema should be listed. A stack with no public tables
+ * has nothing to wait for.
+ */
+async function reloadPostgrestSchema(
+  ctx: SetupCtx,
+  db: string,
+  rest: string,
+): Promise<void> {
+  // Ours first, so every reload — ours and the DDL trigger's — is already
+  // queued before we start watching for the result.
+  await applySqlFile(ctx, "notify pgrst, 'reload schema';\n", "schema reload", "postgres", db);
+
+  const listed = await ctx.exec(
+    db,
+    [
+      "psql", "-U", "postgres", "-d", "postgres", "-t", "-A", "-c",
+      "select table_name from information_schema.tables " +
+        "where table_schema = 'public' and table_type = 'BASE TABLE' order by 1",
+    ],
+    { timeoutMs: 60_000 },
+  );
+  const tables = String(listed.stdout)
+    .split("\n")
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (tables.length === 0) return;
+
+  /** One check: are all the tables served right now? */
+  const served = async (): Promise<string[]> => {
+    const res = await fetch(`http://${rest}:3000/`);
+    if (!res.ok) return tables;
+    const spec = (await res.json()) as { paths?: Record<string, unknown> };
+    const paths = Object.keys(spec.paths ?? {});
+    return tables.filter((t) => !paths.includes(`/${t}`));
+  };
+
+  const SETTLE = 3;
+  const deadline = Date.now() + 30_000;
+  let streak = 0;
+  let missing: string[] = tables;
+  while (Date.now() < deadline) {
+    try {
+      missing = await served();
+      streak = missing.length === 0 ? streak + 1 : 0;
+      if (streak >= SETTLE) return;
+    } catch {
+      // Mid-reload PostgREST can refuse the connection outright.
+      streak = 0;
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error(
+    `supabase: PostgREST did not settle on the migrated schema within 30s ` +
+      `(still missing: ${missing.join(", ") || "nothing, but not stably"}). ` +
+      `The migrations applied — this is the REST schema cache, not your SQL.`,
+  );
+}
+
+/**
+ * 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;
+
+  // Mail capture (see SupabaseOptions.mail) — on unless explicitly disabled.
+  // `mailKey` is the SMTP host GoTrue mails through — the in-group part
+  // (`<name>-mail`) or a user-declared `email()` service shared with the app
+  // under test.
+  // Edge functions — like `migrations`, a path the caller gives or nothing
+  // at all. A directory that doesn't resolve is an error rather than an
+  // empty runtime whose every call 500s much later.
+  const fnOpts: SupabaseFunctionsOptions | null =
+    opts.functions === undefined
+      ? null
+      : typeof opts.functions === "string"
+        ? { dir: opts.functions }
+        : opts.functions;
+  const withFunctions = fnOpts !== null;
+  const fnDir =
+    fnOpts === null
+      ? ""
+      : fnOpts.dir.startsWith("/")
+        ? fnOpts.dir
+        : join(projectRootPath(), fnOpts.dir);
+  if (withFunctions && !existsSync(fnDir)) {
+    throw new Error(
+      `supabase(): functions path ${JSON.stringify(fnOpts!.dir)} does not ` +
+        `resolve to a directory (looked at ${fnDir}). It should hold one ` +
+        `subdirectory per function. The path is resolved inside the uploaded ` +
+        `project — check it isn't ignored (e.g. via .spectestignore).`,
+    );
+  }
+
+  const withMail = opts.mail !== false;
+  const mailOpts: SupabaseMailOptions =
+    typeof opts.mail === "object" ? opts.mail : {};
+  const mailExternal = mailOpts.service !== undefined;
+  const mailKey = mailOpts.service ?? `${name}-mail`;
+  const mailAutoconfirm = mailOpts.autoconfirm ?? true;
+
+  const extraAnonKeys = opts.extraApiKeys?.anon ?? [];
+  const extraServiceRoleKeys = opts.extraApiKeys?.serviceRole ?? [];
+  for (const k of [...extraAnonKeys, ...extraServiceRoleKeys]) {
+    // The keys are spliced into Kong's YAML and its quoted Lua expressions —
+    // restrict to the token charset real API keys use so neither can break.
+    if (!/^[A-Za-z0-9._-]+$/.test(k)) {
+      throw new Error(
+        `supabase(): extraApiKeys entries must match [A-Za-z0-9._-]+ (got ${JSON.stringify(k)})`,
+      );
+    }
+  }
+
+  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) => {
+          // Only the database's own bootstrap (role passwords / JWT GUC /
+          // `_realtime` schema) runs here: the other services need it before
+          // they can start. The project's migrations run later, from the
+          // group hook, once the whole stack is up — see the migration
+          // section above for why.
+          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",
+          );
+        },
+      };
+      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 },
+      };
+
+      // ── mail (SMTP capture, the standard email() component) ─────────
+      if (withMail && !mailExternal) {
+        parts.mail = email();
+      }
+
+      // ── 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 is ON by default: a signup completes in one step
+            // and sends no confirmation mail, so the always-on mailbox is
+            // purely additive and a suite that only needs accounts to exist
+            // writes nothing. `autoconfirm: false` opts into the real
+            // confirmation flow, which the mailbox is there to drive.
+            //
+            // Always ON when there is no mailbox (`mail: false`), whatever
+            // was asked for: the confirmation would be sent nowhere and no
+            // account could ever be used.
+            GOTRUE_MAILER_AUTOCONFIRM:
+              !withMail || mailAutoconfirm ? "true" : "false",
+            GOTRUE_EXTERNAL_PHONE_ENABLED: "false",
+            GOTRUE_SMS_AUTOCONFIRM: "true",
+            ...(withMail
+              ? {
+                  GOTRUE_SMTP_HOST: mailKey,
+                  GOTRUE_SMTP_PORT: "1025",
+                  // Deliberately NO GOTRUE_SMTP_USER/PASS: the capture
+                  // server advertises AUTH, and with credentials set
+                  // GoTrue's Go smtp.PlainAuth refuses to send them over a
+                  // plaintext connection ("unencrypted connection" → every
+                  // mail 500s). Unauthenticated submission is accepted.
+                  GOTRUE_SMTP_ADMIN_EMAIL:
+                    mailOpts.adminEmail ?? "admin@example.com",
+                  GOTRUE_SMTP_SENDER_NAME: mailOpts.senderName ?? "Supabase",
+                  // GoTrue rate-limits repeat mail to the same address
+                  // (default 1/min) — far too slow for tests that
+                  // request an OTP, assert, and request again.
+                  GOTRUE_SMTP_MAX_FREQUENCY: "1s",
+                  GOTRUE_MAILER_URLPATHS_INVITE: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_CONFIRMATION: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_RECOVERY: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: "/auth/v1/verify",
+                }
+              : {}),
+          },
+          ports: [9999],
+          dependsOn: ["db", ...(withMail && !mailExternal ? ["mail"] : [])],
+          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,
+          },
+        };
+      }
+
+      // ── functions (edge runtime) ────────────────────────────────────
+      if (withFunctions) {
+        parts.functions = {
+          image: { type: "registry", reference: IMAGES.functions },
+          // The repo's own function directory, mounted where the runtime
+          // looks. Read-only: the runtime only ever reads the sources, and
+          // a function that writes into its own directory would be writing
+          // into the user's checkout.
+          volumes: [{ source: fnDir, target: "/home/deno/functions", readOnly: true }],
+          // Our router (see FUNCTIONS_MAIN_TS) sits outside that mount, so
+          // the project never has to carry a `main/` function of ours.
+          files: [{ path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS }],
+          args: ["start", "--main-service", "/home/deno/main", "--port", "9000"],
+          env: {
+            JWT_SECRET: jwtSecret,
+            VERIFY_JWT: (fnOpts!.verifyJwt ?? true) ? "true" : "false",
+            // A function calls back into its own project through the
+            // gateway, exactly as it does when hosted.
+            SUPABASE_URL: `http://${g.name}:8000`,
+            SUPABASE_PUBLIC_URL: url,
+            SUPABASE_ANON_KEY: anonKey,
+            SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
+            SUPABASE_DB_URL: `postgresql://postgres:${dbPassword}@${db}:5432/postgres`,
+            ...(fnOpts!.env ?? {}),
+          },
+          ports: [9000],
+          dependsOn: ["db"],
+          readyCheck: {
+            type: "http",
+            port: 9000,
+            path: "/_spectest/health",
+            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,
+              extraAnonKeys,
+              extraServiceRoleKeys,
+              functions: withFunctions,
+            }),
+          },
+        ],
+        ports: [8000, 8443],
+        ...(opts.hostname ? { tls: [{ hostname: opts.hostname, port: 8000 }] } : {}),
+        readyCheck: { type: "exec", command: "kong health", timeoutSecs: 90 },
+      };
+
+      return parts;
+    },
+    // The project's own SQL, applied with the whole stack up (the group
+    // hook chains after the primary, and the primary is the group's
+    // dependency sink). Still inside bring-up, so the result is captured
+    // into the cached environment like everything else.
+    setup: async (ctx) => {
+      if (opts.migrations === undefined) return;
+      await applyMigrations(ctx, opts.migrations, dbKey);
+      await reloadPostgrestSchema(ctx, dbKey, `${name}-rest`);
+    },
+    // The group's consolidated handle at `ctx.svc.<name>`.
+    helpers: (): SupabaseHelpers => ({
+      sql: new SQL(adminDbUrl, { label: name }),
+      url,
+      anonKey,
+      serviceRoleKey,
+      ...(withMail ? { mail: emailHelpers(mailKey) } : {}),
+    }),
+  });
+
+  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,
+    ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
+  };
+}