@specific.dev/spectest 0.45.0 → 0.47.0

package/src/components/supabase.ts

@@ -50,7 +50,7 @@
 // (`sb.url`, `sb.appEnv`) embeds it — a mismatch errors at load.
 
 import { createHmac } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
@@ -63,7 +63,22 @@ import {
   type ServicesMap,
 } from "../index.js";
 import { SQL, type SqlClient } from "../sql.js";
+import { apple } from "./apple.js";
+import type { OAuthClient } from "./emulate/service.js";
 import { email, emailHelpers, type EmailHelpers } from "./email.js";
+import { github } from "./github.js";
+import { google } from "./google.js";
+import { microsoft } from "./microsoft.js";
+import {
+  mapSupabaseConfig,
+  parseSupabaseConfigFile,
+  type MailTemplateId,
+  type MailTemplateSpec,
+  type ExternalProvider,
+  type MappedSupabaseConfig,
+} from "./supabase-config.js";
+
+export type { MailTemplateId, MailTemplateSpec } from "./supabase-config.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -78,11 +93,101 @@ const IMAGES = {
   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",
+  // Serves custom mail templates to GoTrue over HTTP (see the `templates`
+  // part). Tiny, and only pulled by a stack that configures a template.
+  templates: "busybox:1.37",
 } as const;
 
+/**
+ * Social sign-in providers this stack can serve, by the name GoTrue (and
+ * `[auth.external.<name>]`) uses. Each factory builds one container answering
+ * at that provider's **real** endpoints — `accounts.google.com`,
+ * `login.microsoftonline.com`, … — with DNS, a CA-trusted certificate and a
+ * proxy pointing there, so GoTrue performs the ordinary flow against the
+ * ordinary URLs and never learns it is under test.
+ *
+ * A provider that is enabled in the config and absent here is reported rather
+ * than served: there is nothing to point GoTrue at.
+ */
+const EXTERNAL_PROVIDERS: Record<string, (client: OAuthClient) => ServiceDefinition> = {
+  google: (client) => google({ client }),
+  // `azure` is what GoTrue calls Entra ID.
+  azure: (client) => microsoft({ client }),
+  github: (client) => github({ client }),
+  apple: (client) => apple({ client }),
+};
+
+/**
+ * The client credentials GoTrue presents to a provider. Taken from the config
+ * where it holds a literal, and otherwise made up: the file's values are
+ * `env(NAME)` references to a shell this environment does not have, and no
+ * real credential is meaningful against an emulator. Only GoTrue and the
+ * provider have to agree, and both are ours.
+ */
+function providerCredentials(
+  providerName: string,
+  declared: ExternalProvider,
+  env: Record<string, string> | undefined,
+): { clientId: string; clientSecret: string } {
+  const read = (from: string | undefined): string | undefined =>
+    from === undefined ? undefined : env?.[from];
+  return {
+    clientId: declared.clientId ?? read(declared.clientIdFrom) ?? `spectest-${providerName}-client`,
+    clientSecret: declared.secret ?? read(declared.secretFrom) ?? `spectest-${providerName}-secret`,
+  };
+}
+
+/**
+ * The edge runtime, with every remote module its functions import already in
+ * the module cache.
+ *
+ * A Supabase function may import straight from a URL
+ * (`import Fuse from "https://deno.land/x/fuse@v6.4.1/…"`), and Deno fetches
+ * that when the worker boots. Inside a hermetic VM that is a network call at
+ * test time — slow at best, and a failed boot at worst.
+ *
+ * So it is done at **build** time instead. `edge-runtime bundle` walks the
+ * module graph and, unless told otherwise, fills `DENO_DIR` as it goes; the
+ * eszip it produces is thrown away, since all we want is the cache. Docker
+ * builds run on the host builder, which has ordinary network access, and the
+ * cache rides into the image as a layer — so at run time the worker resolves
+ * those URLs locally and never reaches for the network.
+ *
+ * One synthetic entrypoint imports every function, so the whole set is one
+ * graph rather than one per function. Bundling is best-effort: a function that
+ * fails to bundle (a type error, an import that only resolves at run time)
+ * leaves the cache thinner and is never a build failure — the worker then
+ * behaves exactly as it did before.
+ */
+function functionsDockerfile(fnRelPath: string): string {
+  return `FROM ${IMAGES.functions}
+ENV DENO_DIR=${DENO_DIR}
+COPY ${fnRelPath} /warm/functions
+RUN set -eu; \
+    : > /warm/all.ts; \
+    for d in /warm/functions/*/; do \
+      [ -f "$d/index.ts" ] || continue; \
+      n=$(basename "$d"); \
+      printf 'import "./functions/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
+    done; \
+    edge-runtime bundle --entrypoint /warm/all.ts --output /tmp/warm.eszip --quiet || true; \
+    rm -rf /tmp/warm.eszip /warm
+`;
+}
+
+/** Where the module cache lives in the edge-runtime image, written at build
+ *  time and read at run time. Outside the repo mount, deliberately. */
+const DENO_DIR = "/deno-dir";
+
+/** Where the project root is mounted in the edge-runtime container. Functions
+ *  keep their position relative to it, so an import that reaches outside the
+ *  functions directory resolves exactly as it does in the repo. */
+const REPO_MOUNT = "/repo";
+
+/** Where the mail-template server listens; upstream's CLI uses the same port. */
+const TEMPLATE_PORT = 8088;
+
 /**
  * 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
@@ -93,6 +198,11 @@ function projectRootPath(): string {
   return process.env.SPECTEST_WORKSPACE ?? "/workspace";
 }
 
+/** A caller-supplied path: absolute as given, otherwise project-root relative. */
+function absProjectPath(p: string): string {
+  return p.startsWith("/") ? p : join(projectRootPath(), p);
+}
+
 export interface SupabaseOptions {
   /**
    * Key of the API-gateway service and the prefix for every other piece.
@@ -114,26 +224,17 @@ export interface SupabaseOptions {
    * 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;
+  /**
+   * GoTrue auth. `false` drops it from the stack; an object configures the
+   * two settings that are **addresses in this environment** rather than
+   * behaviour — everything else about auth comes from your `config.toml`.
+   */
+  auth?: boolean | SupabaseAuthOptions;
   /** 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
@@ -177,77 +278,132 @@ export interface SupabaseOptions {
   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:
+   * The project's Supabase folder, e.g. `"supabase"` (relative to the project
+   * root, or absolute) — the layout `supabase init` creates and the CLI
+   * requires. This is the **only** way to point the stack at your project, and
+   * everything in the folder is used the way the Supabase CLI uses it:
    *
    * ```
    * supabase/
-   *   migrations/0001_init.sql   ← applied, sorted
-   *   migrations/0002_todos.sql
-   *   seed.sql                   ← applied last
+   *   config.toml     ← auth rules, mail templates, per-function JWT verification
+   *   migrations/     ← applied in filename order once the stack is up
+   *   seed.sql        ← applied after them, if it's there
+   *   functions/      ← one directory per function, served at /functions/v1/<name>
    * ```
    *
-   * 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.
+   * `config.json` is read in preference to `config.toml` where a newer CLI has
+   * written one. Nothing is derived unless you name the folder, and each piece
+   * is optional inside it — a folder with only a `config.toml` is fine.
    *
-   * 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/**`).
+   * There is deliberately no per-piece path option and no way to configure
+   * mail, OTP, redirect or JWT behaviour here: those live in `config.toml`,
+   * where your project already declares them and where the Supabase CLI reads
+   * them too. One source of truth, and the environment matches the one you run
+   * locally.
    */
-  migrations?: string;
+  dir?: 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`).
+   * The `.env` of this environment — the values your `config.toml` reads with
+   * `env(...)`.
+   *
+   * ```toml
+   * # supabase/config.toml
+   * [edge_runtime.secrets]
+   * STRIPE_KEY = "env(STRIPE_SECRET_KEY)"
+   * FEATURE_X  = "true"
+   *
+   * [auth.external.google]
+   * client_id = "env(GOOGLE_OAUTH_CLIENT_ID)"
+   * ```
+   * ```ts
+   * supabase({
+   *   dir: "supabase",
+   *   env: {
+   *     STRIPE_SECRET_KEY: "sk_test_…",
+   *     GOOGLE_OAUTH_CLIENT_ID: "1234.apps.googleusercontent.com",
+   *   },
+   * })
+   * ```
    *
-   * **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.
+   * Keyed exactly as your `supabase/.env` is: by the name inside `env(...)`.
+   * That file is what the Supabase CLI resolves against — locally at `start`,
+   * and in CI at `config push` / `secrets set` — and it is excluded from the
+   * upload here, deliberately, since real credentials should not enter a test
+   * environment. This is its stand-in, holding test values.
    *
-   * Function code is read straight from the repo — nothing is copied or
-   * bundled — so editing a function is an ordinary project edit.
+   * It covers every `env(...)` in the file, not only secrets: a provider's
+   * client id is a field on your project's auth settings rather than a named
+   * secret, and it reads from the same place.
    *
-   * 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(...)`.
+   * A value reaches your **functions** because `[edge_runtime.secrets]`
+   * declares it — `SECRET = "env(NAME)"` — not merely because it is here. A
+   * deployed project can have secrets its config never mentions (the dashboard
+   * and `supabase secrets set` write straight to the project's store), but
+   * declaring them is what makes the test environment's inputs reviewable in
+   * the project's own config rather than implicit in its test setup. A name
+   * passed here and referenced nowhere is called out in the boot log.
+   *
+   * A literal in the file needs nothing. An inline `encrypted:` ciphertext
+   * cannot be supplied this way at all — it names no variable, and decrypting
+   * it needs a `DOTENV_PRIVATE_KEY` a test environment has no business
+   * holding — so it is named in the boot log and left unset. Anything else
+   * left unresolved is reported the same way, and never passed through as the
+   * string `env(NAME)` or as base64.
    */
-  functions?: string | SupabaseFunctionsOptions;
+  env?: Record<string, string>;
 }
 
-/** Tuning for `SupabaseOptions.functions`. */
-export interface SupabaseFunctionsOptions {
+/** Tuning for {@link SupabaseOptions.auth}. */
+export interface SupabaseAuthOptions {
   /**
-   * Directory holding one subdirectory per function, relative to the project
-   * root (or absolute). Required — there is no assumed location.
+   * Where GoTrue sends a user when a flow finishes — the base of every
+   * emailed confirmation, recovery and invite link's `redirect_to`, and the
+   * fallback when a requested redirect is refused. Defaults to the gateway
+   * (`http://<name>:8000`).
+   *
+   * This is deliberately **not** read from `config.toml`. That file's
+   * `site_url` is the developer's own machine (`http://localhost:3000`),
+   * which inside a VM is the browser's own namespace rather than the app
+   * container — so honouring it would point every redirect at nothing. Set
+   * it to the app under test's address in *this* environment:
+   *
+   * ```ts
+   * supabase({ dir: "supabase", auth: { siteUrl: "https://app.test" } })
+   * ```
    */
-  dir: string;
+  siteUrl?: 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).
+   * Extra addresses a flow may redirect to, beyond `siteUrl` (which GoTrue
+   * always allows). Glob patterns, exactly as `config.toml` spells them:
+   * `["https://app.test/**"]`.
+   *
+   * **Redirect validation is off unless you set this.** GoTrue has no switch
+   * for it — an empty allow list is its *strictest* state, not its loosest,
+   * because a redirect is then refused unless it matches `siteUrl` — so the
+   * default here is the wildcard, and a suite is never rejected for a
+   * redirect it didn't declare. Set it to make the environment enforce what
+   * production enforces; the addresses are per-environment, so they belong
+   * here rather than in the config file.
    */
-  verifyJwt?: boolean;
+  additionalRedirectUrls?: string[];
   /**
-   * 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.
+   * Provider components to serve the config's `[auth.external.*]` blocks
+   * with, keyed by the provider name GoTrue uses (`google`, `azure`,
+   * `github`, `apple`). **You do not normally need this**: a provider the
+   * config enables is stood up automatically with that component's defaults.
+   * Supply one to choose the accounts it offers, or to serve a provider this
+   * stack has no built-in emulator for:
+   *
+   * ```ts
+   * auth: {
+   *   providers: {
+   *     google: google({ users: [{ email: "alice@corp.test", name: "Alice" }] }),
+   *   },
+   * }
+   * ```
    */
-  env?: Record<string, string>;
+  providers?: Record<string, ServiceDefinition>;
 }
 
 /** Tuning for `SupabaseOptions.mail`. */
@@ -257,26 +413,14 @@ export interface SupabaseMailOptions {
    * 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.
+   * This is the only mail option, deliberately. Everything else about mail —
+   * whether a signup is confirmed, the sender identity, custom templates and
+   * their subjects — is GoTrue behaviour your project already declares in
+   * `config.toml` (`[auth.email]`, `[auth.email.smtp]`,
+   * `[auth.email.template.*]`), and it is read from there.
    */
-  autoconfirm?: boolean;
-  /** Sender address GoTrue mails from. Default `admin@example.com`. */
-  adminEmail?: string;
-  /** Sender display name. Default `Supabase`. */
-  senderName?: string;
+  service?: string;
 }
 
 /** Helpers the gateway service exposes on `ctx.svc.<name>`. */
@@ -286,6 +430,11 @@ export interface SupabaseHelpers {
    * `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.
+   *
+   * The same client the `postgres()` component exposes: a tagged template for
+   * ordinary queries, plus `unsafe(text, params?)` for what a template cannot
+   * carry — a whole `.sql` file, or a dynamic column list — which is recorded
+   * on the timeline just the same. See `spectest docs /components/postgres`.
    */
   sql: SqlClient;
   /** The gateway base URL the app uses as `SUPABASE_URL` (e.g. `http://supabase:8000`). */
@@ -774,6 +923,36 @@ services:
               if auth == nil or auth == "" or auth:find("^%s*$") then
                 kong.service.request.clear_header("authorization")
               end
+  # >>> oauthserver (added only when the config enables the OAuth server)
+  # The OAuth-server endpoints must be reachable by a client that has no
+  # Supabase API key at all — a third-party connector knows only what the
+  # authorization-server metadata advertises. So they bypass the key-auth on
+  # /auth/v1/ below, exactly as /auth/v1/verify and /auth/v1/callback do,
+  # and the client's own Authorization header (a user token at the consent
+  # step, client credentials at the token endpoint) passes through untouched.
+  # RFC 8414 discovery. The issuer carries a path (.../auth/v1), so a compliant
+  # client asks for the metadata with that path INSERTED after the well-known
+  # segment — which is where hosted Supabase publishes it, and what an MCP
+  # connector will request. GoTrue only registers the bare path, so map it.
+  - name: well-known-oauth-issuer-path
+    url: http://auth:9999/.well-known/oauth-authorization-server
+    routes:
+      - name: well-known-oauth-issuer-path
+        strip_path: true
+        paths:
+          - /.well-known/oauth-authorization-server/auth/v1
+    plugins:
+      - name: cors
+  - name: auth-v1-open-oauth
+    url: http://auth:9999/oauth/
+    routes:
+      - name: auth-v1-open-oauth
+        strip_path: true
+        paths:
+          - /auth/v1/oauth/
+    plugins:
+      - name: cors
+  # <<< oauthserver
   # >>> functions (dropped when the edge runtime is off)
   - name: functions-v1
     url: http://functions:9000/
@@ -795,34 +974,6 @@ services:
           - /.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
 `;
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -839,9 +990,15 @@ services:
 // ──────────────────────────────────────────────────────────────────────────
 
 const FUNCTIONS_MAIN_TS = String.raw`// spectest-generated edge-functions router. Do not edit.
-const FUNCTIONS_DIR = "/home/deno/functions";
+const FUNCTIONS_DIR = Deno.env.get("FUNCTIONS_DIR") ?? "/repo/supabase/functions";
 const JWT_SECRET = Deno.env.get("JWT_SECRET") ?? "";
 const VERIFY_JWT = Deno.env.get("VERIFY_JWT") === "true";
+// Per-function overrides (the project's config file). Hosted Supabase decides
+// this per function, so the global flag is only the default for a function the
+// map says nothing about.
+const VERIFY_JWT_MAP: Record<string, boolean> = JSON.parse(
+  Deno.env.get("VERIFY_JWT_MAP") ?? "{}",
+);
 
 function json(body: unknown, status: number): Response {
   return new Response(JSON.stringify(body), {
@@ -893,7 +1050,7 @@ Deno.serve(async (req: Request) => {
   const name = pathname.split("/")[1] ?? "";
   if (name === "") return json({ msg: "missing function name in request" }, 400);
 
-  if (VERIFY_JWT && req.method !== "OPTIONS") {
+  if ((VERIFY_JWT_MAP[name] ?? VERIFY_JWT) && req.method !== "OPTIONS") {
     const header = req.headers.get("authorization") ?? "";
     const [scheme, token] = header.split(" ");
     if (scheme !== "Bearer" || !token || !(await validJwt(token))) {
@@ -948,8 +1105,6 @@ function buildKongYaml(
   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
@@ -958,10 +1113,14 @@ function buildKongYaml(
      *  gateway's catch-all and is rejected there (measured: 401), instead
      *  of proxying to an unresolvable host. */
     functions: boolean;
+    /** Is Supabase Auth acting as an OAuth authorization server? Its endpoints
+     *  need a key-auth-free route, since an OAuth client has no API key. */
+    oauthServer: boolean;
   },
 ): string {
   let y = KONG_YML_RAW;
   y = stripMarkedBlock(y, "functions", vals.functions);
+  y = stripMarkedBlock(y, "oauthserver", vals.oauthServer);
   // 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.
@@ -982,8 +1141,6 @@ function buildKongYaml(
     .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).
@@ -999,8 +1156,7 @@ function buildKongYaml(
   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
@@ -1153,12 +1309,20 @@ async function reloadPostgrestSchema(
   // queued before we start watching for the result.
   await applySqlFile(ctx, "notify pgrst, 'reload schema';\n", "schema reload", "postgres", db);
 
+  // Only the tables PostgREST will actually publish. The spec below is
+  // fetched unauthenticated, so it is the `anon` role's view — and a table
+  // deliberately granted to nobody else (Supabase projects do this routinely:
+  // a lookup table only `supabase_auth_admin` may read, RLS with no anon
+  // grant) never appears in it. Waiting for those would wait for ever, on a
+  // schema cache that is in fact up to date.
   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",
+      "select c.relname from pg_class c join pg_namespace n on n.oid = c.relnamespace " +
+        "where n.nspname = 'public' and c.relkind = 'r' " +
+        // `anon` is created by this component's own bootstrap, so it exists.
+        "and has_table_privilege('anon', c.oid, 'SELECT') order by 1",
     ],
     { timeoutMs: 60_000 },
   );
@@ -1222,51 +1386,153 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       `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 withAuth = opts.auth !== false;
+  const authOpts: SupabaseAuthOptions = typeof opts.auth === "object" ? opts.auth : {};
   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)) {
+
+  // ── the project's supabase/ folder ────────────────────────────────────
+  // One option locates everything, because the Supabase CLI fixes the layout:
+  // it finds a project by `supabase/config.toml`, `supabase migration new`
+  // writes to `supabase/migrations`, and a function is `supabase/functions/
+  // <name>/`. So there is nothing to point at piece by piece — name the
+  // folder, and each piece inside it is optional.
+  const dirPath = opts.dir === undefined ? null : absProjectPath(opts.dir);
+  if (dirPath !== null && !existsSync(dirPath)) {
     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).`,
+      `supabase(): dir ${JSON.stringify(opts.dir)} does not resolve to a ` +
+        `directory (looked at ${dirPath}). It should be the project's Supabase ` +
+        `folder — the one holding config.toml / migrations / functions. The ` +
+        `path is resolved inside the uploaded project — check it isn't ignored ` +
+        `(e.g. via .spectestignore).`,
     );
   }
+  const inDir = (rel: string): string | null => {
+    const p = dirPath === null ? null : join(dirPath, rel);
+    return p !== null && existsSync(p) ? p : null;
+  };
+
+  const fnDir = inDir("functions");
+  const withFunctions = fnDir !== null;
+  // The functions directory as the runtime will see it: the same path it has
+  // in the repo, under the root mount.
+  const root = projectRootPath();
+  /** The functions directory relative to the build context (the project root). */
+  const fnRelPath =
+    fnDir === null ? "" : fnDir.startsWith(`${root}/`) ? fnDir.slice(root.length + 1) : "supabase/functions";
+  const fnServePath =
+    fnDir === null
+      ? ""
+      : fnDir.startsWith(`${root}/`)
+        ? `${REPO_MOUNT}/${fnDir.slice(root.length + 1)}`
+        : `${REPO_MOUNT}/supabase/functions`;
+  const migrationsPath = inDir("migrations");
+
+  // ── config file (config.toml / config.json) ───────────────────────────
+  // The CLI's own project config, mapped onto the stack. Read at build time:
+  // the values become container config, so they must be in hand before the
+  // services map is returned. `config.json` wins where a newer CLI wrote one.
+  const configPath = inDir("config.json") ?? inDir("config.toml");
+  let mapped: MappedSupabaseConfig | null = null;
+  if (configPath !== null) {
+    const shown = configPath.startsWith(projectRootPath())
+      ? configPath.slice(projectRootPath().length + 1)
+      : configPath;
+    mapped = mapSupabaseConfig(parseSupabaseConfigFile(configPath));
+    // What the file asked for and did not get. Reported, never fatal: the
+    // config belongs to the project and describes more than this environment,
+    // so a key that is meaningless in a hermetic VM is not grounds to refuse
+    // to start. Silence is the thing to avoid, not the setting itself.
+    for (const { key, reason } of mapped.unsupported) {
+      console.warn(`supabase(): ${shown} sets ${key}, which this stack does not apply — ${reason}.`);
+    }
+    const unmet = Object.entries(mapped.deferredSecrets)
+      .filter(([, from]) => opts.env?.[from] === undefined)
+      .map(([name, from]) => (name === from ? name : `${name} (env ${from})`));
+    if (unmet.length > 0) {
+      console.warn(
+        `supabase(): ${shown} reads ${unmet.length} value(s) from the ` +
+          `environment: ${unmet.join(", ")}. They are unset here — pass them ` +
+          `with env: { … } if a test needs them.`,
+      );
+    }
+    if (mapped.encryptedValues.length > 0) {
+      console.warn(
+        `supabase(): ${shown} carries encrypted values (${mapped.encryptedValues.join(", ")}), ` +
+          `which need a DOTENV_PRIVATE_KEY this environment does not have. They ` +
+          `are unset here.`,
+      );
+    }
+    // The other direction: something supplied here that the config never
+    // reads. Without this the gap is silent — a function goes without a value
+    // and nothing says why.
+    const referenced = new Set<string>([
+      ...Object.values(mapped.deferredSecrets),
+      ...Object.values(mapped.externalProviders).flatMap((p) =>
+        [p.clientIdFrom, p.secretFrom].filter((n): n is string => n !== undefined),
+      ),
+    ]);
+    const unread = Object.keys(opts.env ?? {}).filter((k) => !referenced.has(k));
+    if (unread.length > 0) {
+      console.warn(
+        `supabase(): env supplies ${unread.join(", ")}, which ${shown} never ` +
+          `reads with env(...) — nothing receives them. Declare what a function ` +
+          `needs in [edge_runtime.secrets], e.g. NAME = "env(NAME)".`,
+      );
+    }
+    for (const key of mapped.warnings) {
+      console.warn(
+        `supabase(): ${shown} sets ${key}, which this component does not know about — ignoring it.`,
+      );
+    }
+  }
+
+  // The OAuth server is on only if the project's config says so — it adds
+  // gateway routes, so the stack has to know before Kong's config is built.
+  const withOAuthServer = mapped?.auth.GOTRUE_OAUTH_SERVER_ENABLED === "true";
 
   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;
+
+  // ── custom mail templates ─────────────────────────────────────────────
+  // `[auth.email.template.*]` from the project's config, keyed by GoTrue's own
+  // template ids — which is what the container variables are named after.
+  const templates: Partial<Record<MailTemplateId, MailTemplateSpec>> = { ...mapped?.templates };
+  // A subject with no body is legitimate (GoTrue's default template, the
+  // project's wording), and only a body needs serving.
+  const templateBodies = Object.entries(templates).filter(([, spec]) => spec.path !== "") as [
+    MailTemplateId,
+    MailTemplateSpec,
+  ][];
+  if (templateBodies.length > 0 && (!withMail || !withAuth)) {
+    const why = !withAuth ? "auth is off (auth: false)" : "mail is off (mail: false)";
+    throw new Error(
+      `supabase(): the config file sets mail templates (${templateBodies
+        .map(([id]) => id)
+        .join(", ")}) but ${why}, so nothing would ever send them.`,
+    );
+  }
+  const templateFiles = templateBodies.map(([id, spec]) => {
+    // `content_path` is written relative to the project root, the way the CLI
+    // resolves it — not relative to the supabase/ folder.
+    const path = absProjectPath(spec.path);
+    if (!existsSync(path)) {
+      throw new Error(
+        `supabase(): mail template ${JSON.stringify(spec.path)} for ${id} does ` +
+          `not resolve to a file (looked at ${path}). The path is resolved ` +
+          `inside the uploaded project — check it isn't ignored (e.g. via ` +
+          `.spectestignore).`,
+      );
+    }
+    // Read now rather than bind-mounting the directory: a template's config
+    // key decides the served name, which a mount cannot rename, and the paths
+    // may be anywhere in the repo.
+    return { path: `/srv/email/${id}.html`, content: readFileSync(path, "utf8") };
+  });
+  const withTemplates = templateFiles.length > 0;
 
   const extraAnonKeys = opts.extraApiKeys?.anon ?? [];
   const extraServiceRoleKeys = opts.extraApiKeys?.serviceRole ?? [];
@@ -1295,6 +1561,41 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   // `auth`/`storage` schemas — regardless of ownership.
   const adminDbUrl = `postgresql://supabase_admin:${dbPassword}@${dbKey}:5432/postgres`;
 
+  // ── social sign-in ────────────────────────────────────────────────────
+  // Every `[auth.external.<name>]` the config enables: served in-environment
+  // where there is an emulator for it, reported where there isn't. The app
+  // under test keeps its production configuration either way — the provider
+  // answers at its own real endpoints.
+  const providerOverrides = authOpts.providers ?? {};
+  const externalProviders = Object.entries(mapped?.externalProviders ?? {})
+    .filter(([, p]) => p.enabled)
+    .map(([providerName, declared]) => {
+      const { clientId, clientSecret } = providerCredentials(providerName, declared, opts.env);
+      // Registering the client makes the provider validate it, so a callback
+      // URL that doesn't match fails here rather than in production.
+      const service =
+        providerOverrides[providerName] ??
+        EXTERNAL_PROVIDERS[providerName]?.({
+          clientId,
+          clientSecret,
+          redirectUris: [`${url}/auth/v1/callback`],
+        });
+      return { providerName, declared, service };
+    });
+  for (const { providerName, service } of externalProviders) {
+    if (service === undefined) {
+      console.warn(
+        `supabase(): the config enables the ${providerName} sign-in provider, which ` +
+          `this stack has no emulator for — sign-in through it will not work here. ` +
+          `Supply one with auth: { providers: { ${providerName}: … } }.`,
+      );
+    }
+  }
+  const servedProviders = externalProviders.filter(
+    (p): p is typeof p & { service: ServiceDefinition } => p.service !== undefined,
+  );
+
+
   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
@@ -1369,6 +1670,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           PGRST_ADMIN_SERVER_PORT: "3001",
           PGRST_DB_MAX_ROWS: "1000",
           PGRST_DB_EXTRA_SEARCH_PATH: "public",
+          // `api.schemas` / `extra_search_path` / `max_rows` from the project's
+          // config file, if it has one.
+          ...(mapped?.rest ?? {}),
         },
         ports: [3000],
         dependsOn: ["db"],
@@ -1382,9 +1686,41 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         parts.mail = email();
       }
 
+      // ── social sign-in providers ────────────────────────────────────
+      for (const { providerName, service } of servedProviders) {
+        parts[providerName] = service;
+      }
+
+      // ── mail templates (static server) ──────────────────────────────
+      // GoTrue fetches a template over HTTP — `http.DefaultClient.Do` on the
+      // configured URL — so a bind-mounted path or a `file://` URL does not
+      // work. Upstream's CLI solves this with an nginx static server beside
+      // Kong; this is the same shape as its own part, and only exists when a
+      // template is configured.
+      if (withTemplates) {
+        parts.templates = {
+          image: { type: "registry", reference: IMAGES.templates },
+          command: `httpd -f -p ${TEMPLATE_PORT} -h /srv`,
+          files: templateFiles,
+          ports: [TEMPLATE_PORT],
+          readyCheck: { type: "tcp", port: TEMPLATE_PORT, timeoutSecs: 60 },
+        };
+      }
+
       // ── auth (GoTrue) ───────────────────────────────────────────────
       if (withAuth) {
         const apiExternalUrl = `${url}/auth/v1`;
+        const templateHost = `${g.key("templates")}:${TEMPLATE_PORT}`;
+        const templateEnv: Record<string, string> = {};
+        for (const [id, spec] of Object.entries(templates)) {
+          if (spec.path !== "") {
+            templateEnv[`GOTRUE_MAILER_TEMPLATES_${id.toUpperCase()}`] =
+              `http://${templateHost}/email/${id}.html`;
+          }
+          if (spec.subject !== undefined) {
+            templateEnv[`GOTRUE_MAILER_SUBJECTS_${id.toUpperCase()}`] = spec.subject;
+          }
+        }
         parts.auth = {
           image: { type: "registry", reference: IMAGES.auth },
           env: {
@@ -1393,8 +1729,13 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             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: "*",
+            // Addresses in *this* environment, so they come from the option
+            // rather than the config file (whose values name the developer's
+            // machine). The wildcard is deliberate: GoTrue has no way to turn
+            // redirect validation off, and an empty allow list is its
+            // strictest state, not its loosest.
+            GOTRUE_SITE_URL: authOpts.siteUrl ?? url,
+            GOTRUE_URI_ALLOW_LIST: authOpts.additionalRedirectUrls?.join(",") ?? "*",
             GOTRUE_DISABLE_SIGNUP: "false",
             GOTRUE_JWT_ADMIN_ROLES: "service_role",
             GOTRUE_JWT_AUD: "authenticated",
@@ -1413,8 +1754,9 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             // 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",
+            // One-step signups by default; `[auth.email] enable_confirmations`
+            // in the project's config turns the real confirmation flow on.
+            GOTRUE_MAILER_AUTOCONFIRM: "true",
             GOTRUE_EXTERNAL_PHONE_ENABLED: "false",
             GOTRUE_SMS_AUTOCONFIRM: "true",
             ...(withMail
@@ -1426,9 +1768,8 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
                   // 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_SMTP_ADMIN_EMAIL: "admin@example.com",
+                  GOTRUE_SMTP_SENDER_NAME: "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.
@@ -1439,9 +1780,44 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
                   GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: "/auth/v1/verify",
                 }
               : {}),
+            // The project's config file outranks the defaults above — that is
+            // what reading it is for.
+            ...(mapped?.auth ?? {}),
+            ...templateEnv,
+            // One block per served provider. The credentials are this
+            // environment's own: the config file's are `env(...)` references
+            // to the developer's shell, and nothing here needs the real ones —
+            // only GoTrue and the provider have to agree, and both are ours.
+            ...Object.fromEntries(
+              servedProviders.flatMap(({ providerName, declared }) => {
+                const upper = providerName.toUpperCase();
+                const { clientId, clientSecret } = providerCredentials(providerName, declared, opts.env);
+                return [
+                  [`GOTRUE_EXTERNAL_${upper}_ENABLED`, "true"],
+                  [`GOTRUE_EXTERNAL_${upper}_CLIENT_ID`, clientId],
+                  [`GOTRUE_EXTERNAL_${upper}_SECRET`, clientSecret],
+                  [`GOTRUE_EXTERNAL_${upper}_REDIRECT_URI`, `${url}/auth/v1/callback`],
+                  ...(declared.url === undefined
+                    ? []
+                    : [[`GOTRUE_EXTERNAL_${upper}_URL`, declared.url]]),
+                ];
+              }),
+            ),
+            // Autoconfirm is forced on when there is no mailbox, whatever the
+            // config said: the confirmation would go nowhere, and no account
+            // could ever be used.
+            ...(!withMail ? { GOTRUE_MAILER_AUTOCONFIRM: "true" } : {}),
           },
           ports: [9999],
-          dependsOn: ["db", ...(withMail && !mailExternal ? ["mail"] : [])],
+          dependsOn: [
+            "db",
+            ...(withMail && !mailExternal ? ["mail"] : []),
+            ...(withTemplates ? ["templates"] : []),
+            // GoTrue reads the provider's discovery document during a flow,
+            // not at boot — but a test that signs in immediately should not
+            // race the emulator's first start.
+            ...servedProviders.map((p) => p.providerName),
+          ],
           readyCheck: { type: "http", port: 9999, path: "/health", timeoutSecs: 90 },
         };
       }
@@ -1539,19 +1915,48 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       // ── 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 }],
+          // Built rather than pulled, so the functions' remote imports are
+          // fetched by the host builder and cached into the image — see
+          // `functionsDockerfile`.
+          image: {
+            type: "dockerfile",
+            content: functionsDockerfile(fnRelPath),
+          },
+          // The **project root**, mounted with the functions directory in its
+          // real position underneath. Mounting only `supabase/functions`
+          // would be enough for a self-contained function, but a monorepo's
+          // functions routinely import shared code from outside it
+          // (`../../../../packages/…`), and that only resolves if the
+          // directory sits where it sits in the repo. Read-only: the runtime
+          // only reads sources, and a function writing into its own directory
+          // would be writing into the user's checkout.
+          volumes: [{ source: projectRootPath(), target: REPO_MOUNT, 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",
+            // Where the router looks for `<name>/`, inside the repo mount.
+            FUNCTIONS_DIR: fnServePath,
+            // The default a function inherits when the config says nothing:
+            // reject an unauthenticated call, as hosted Supabase does.
+            VERIFY_JWT: "true",
+            // Per-function overrides from the config file's `[functions.<name>]`
+            // blocks. Hosted Supabase verifies per function, so one global flag
+            // makes a project pick a single answer for the whole set.
+            VERIFY_JWT_MAP: JSON.stringify(mapped?.functionVerifyJwt ?? {}),
+            // `[edge_runtime.secrets]`, then the values the file deferred to
+            // the environment.
+            ...(mapped?.functionSecrets ?? {}),
+            // …the ones it reads from the environment, under the names the
+            // file gives them…
+            ...Object.fromEntries(
+              Object.entries(mapped?.deferredSecrets ?? {})
+                .map(([name, from]) => [name, opts.env?.[from]])
+                .filter(([, v]) => v !== undefined) as [string, string][],
+            ),
+
             // A function calls back into its own project through the
             // gateway, exactly as it does when hosted.
             SUPABASE_URL: `http://${g.name}:8000`,
@@ -1559,7 +1964,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             SUPABASE_ANON_KEY: anonKey,
             SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
             SUPABASE_DB_URL: `postgresql://postgres:${dbPassword}@${db}:5432/postgres`,
-            ...(fnOpts!.env ?? {}),
           },
           ports: [9000],
           dependsOn: ["db"],
@@ -1572,58 +1976,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         };
       }
 
-      // ── 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 = {
@@ -1645,11 +1997,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             content: buildKongYaml(g.key, {
               anonKey,
               serviceRoleKey,
-              dashboardUsername,
-              dashboardPassword,
               extraAnonKeys,
               extraServiceRoleKeys,
               functions: withFunctions,
+              oauthServer: withOAuthServer,
             }),
           },
         ],
@@ -1665,8 +2016,8 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     // 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);
+      if (migrationsPath === null) return;
+      await applyMigrations(ctx, migrationsPath, dbKey);
       await reloadPostgrestSchema(ctx, dbKey, `${name}-rest`);
     },
     // The group's consolidated handle at `ctx.svc.<name>`.