@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/components/supabase.js

@@ -0,0 +1,1003 @@
+// 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, } from "../index.js";
+import { SQL } from "../sql.js";
+import { email, 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",
+};
+// 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) {
+    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, secret) {
+    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, secret) {
+    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) {
+    return `'${s.replace(/'/g, "''")}'`;
+}
+function buildBootstrapSql(dbPassword, jwtSecret, withRealtime) {
+    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.
+function buildLuaExprs(extra) {
+    // 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}') 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)`;
+    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"
+      - 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, vals) {
+    let y = KONG_YML_RAW;
+    // 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 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, sql, label, user) {
+    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, cfg) {
+    // Migrations directory. An *explicitly configured* 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`. Only the `true` default
+    // (conventional `supabase/migrations/`) is allowed to be absent.
+    if (cfg.migrations !== false) {
+        const explicit = typeof cfg.migrations === "string";
+        const dir = explicit
+            ? 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");
+            }
+        }
+        else if (explicit) {
+            throw new Error(`supabase: configured migrations path ${JSON.stringify(cfg.migrations)} does not resolve to a directory (looked at ${dir}). ` +
+                `Fix the \`migrations\` option, or remove it to use the default ` +
+                `supabase/migrations/. Note the path is resolved inside the uploaded ` +
+                `project — check it isn't ignored (e.g. via .spectestignore).`);
+        }
+    }
+    // Seed file — same contract: only the conventional default may be absent.
+    if (cfg.seed !== false) {
+        const explicit = typeof cfg.seed === "string";
+        const seedPath = explicit
+            ? 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");
+        }
+        else if (explicit) {
+            throw new Error(`supabase: configured seed path ${JSON.stringify(cfg.seed)} not found ` +
+                `(looked at ${seedPath}). Fix the \`seed\` option or remove it to ` +
+                `use the default supabase/seed.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 = {}) {
+    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.
+    const withMail = opts.mail !== false;
+    const mailOpts = 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 = {};
+            // ── db ──────────────────────────────────────────────────────────
+            const dbDef = {
+                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 },
+            };
+            // ── 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 defaults ON (one-step signups, no confirmation
+                        // mail) so the always-on mailbox is purely additive; the mail
+                        // option's `autoconfirm: false` opts into real confirmation
+                        // flows.
+                        GOTRUE_MAILER_AUTOCONFIRM: withMail && !mailAutoconfirm ? "false" : "true",
+                        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,
+                    },
+                };
+            }
+            // ── 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,
+                        }),
+                    },
+                ],
+                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: () => ({
+            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 } } : {}),
+    };
+}