@specific.dev/spectest 0.44.0 → 0.46.0

package/dist/components/supabase.js

@@ -49,12 +49,17 @@
 // 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 { existsSync, readFileSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { serviceGroup, } from "../index.js";
 import { SQL } from "../sql.js";
+import { apple } from "./apple.js";
 import { email, emailHelpers } from "./email.js";
+import { github } from "./github.js";
+import { google } from "./google.js";
+import { microsoft } from "./microsoft.js";
+import { mapSupabaseConfig, parseSupabaseConfigFile, } from "./supabase-config.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
@@ -68,10 +73,89 @@ 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",
 };
+/**
+ * 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 = {
+    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, declared, env) {
+    const read = (from) => 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) {
+    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
@@ -81,6 +165,10 @@ const IMAGES = {
 function projectRootPath() {
     return process.env.SPECTEST_WORKSPACE ?? "/workspace";
 }
+/** A caller-supplied path: absolute as given, otherwise project-root relative. */
+function absProjectPath(p) {
+    return p.startsWith("/") ? p : join(projectRootPath(), p);
+}
 // 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`)
@@ -495,6 +583,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/
@@ -516,34 +634,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
 `;
 // ──────────────────────────────────────────────────────────────────────────
 // Edge functions — the runtime's "main service": the request router that
@@ -558,9 +648,15 @@ services:
 // with, and Web Crypto verifies it in a few lines with no dependency.
 // ──────────────────────────────────────────────────────────────────────────
 const FUNCTIONS_MAIN_TS = String.raw `// spectest-generated edge-functions router. Do not edit.
-const FUNCTIONS_DIR = "/home/deno/functions";
+const 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), {
@@ -612,7 +708,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))) {
@@ -664,6 +760,7 @@ function stripMarkedBlock(yaml, tag, keep) {
 function buildKongYaml(key, vals) {
     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.
@@ -678,8 +775,6 @@ function buildKongYaml(key, vals) {
         .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).
@@ -691,9 +786,7 @@ function buildKongYaml(key, vals) {
     // 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);
+        .replaceAll("$SUPABASE_SERVICE_KEY", vals.serviceRoleKey);
     // Drop the unconfigured opaque-key credential lines (kong-entrypoint.sh does
     // the same with a `sed` after substitution).
     y = y
@@ -783,10 +876,18 @@ async function reloadPostgrestSchema(ctx, db, rest) {
     // Ours first, so every reload — ours and the DDL trigger's — is already
     // queued before we start watching for the result.
     await applySqlFile(ctx, "notify pgrst, 'reload schema';\n", "schema reload", "postgres", db);
+    // 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 });
     const tables = String(listed.stdout)
         .split("\n")
@@ -845,42 +946,125 @@ export function supabase(opts = {}) {
     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 withAuth = opts.auth !== false;
+    const authOpts = 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 = opts.functions === undefined
-        ? null
-        : typeof opts.functions === "string"
-            ? { dir: opts.functions }
-            : opts.functions;
-    const withFunctions = fnOpts !== null;
-    const fnDir = fnOpts === null
+    // ── 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(): 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) => {
+        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
         ? ""
-        : fnOpts.dir.startsWith("/")
-            ? fnOpts.dir
-            : join(projectRootPath(), fnOpts.dir);
-    if (withFunctions && !existsSync(fnDir)) {
-        throw new Error(`supabase(): functions path ${JSON.stringify(fnOpts.dir)} does not ` +
-            `resolve to a directory (looked at ${fnDir}). It should hold one ` +
-            `subdirectory per function. The path is resolved inside the uploaded ` +
-            `project — check it isn't ignored (e.g. via .spectestignore).`);
+        : 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 = 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([
+            ...Object.values(mapped.deferredSecrets),
+            ...Object.values(mapped.externalProviders).flatMap((p) => [p.clientIdFrom, p.secretFrom].filter((n) => 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 = 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 = { ...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 !== "");
+    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 ?? [];
     for (const k of [...extraAnonKeys, ...extraServiceRoleKeys]) {
@@ -903,6 +1087,34 @@ export function supabase(opts = {}) {
     // `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`;
+    // ── 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.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
@@ -971,6 +1183,9 @@ export function supabase(opts = {}) {
                     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"],
@@ -982,9 +1197,39 @@ export function supabase(opts = {}) {
             if (withMail && !mailExternal) {
                 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 = {};
+                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: {
@@ -993,8 +1238,13 @@ export function supabase(opts = {}) {
                         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",
@@ -1013,7 +1263,9 @@ export function supabase(opts = {}) {
                         // 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
@@ -1025,8 +1277,8 @@ export function supabase(opts = {}) {
                                 // 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.
@@ -1037,9 +1289,42 @@ export function supabase(opts = {}) {
                                 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 },
                 };
             }
@@ -1132,19 +1417,45 @@ export function supabase(opts = {}) {
             // ── 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)),
                         // A function calls back into its own project through the
                         // gateway, exactly as it does when hosted.
                         SUPABASE_URL: `http://${g.name}:8000`,
@@ -1152,7 +1463,6 @@ export function supabase(opts = {}) {
                         SUPABASE_ANON_KEY: anonKey,
                         SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
                         SUPABASE_DB_URL: `postgresql://postgres:${dbPassword}@${db}:5432/postgres`,
-                        ...(fnOpts.env ?? {}),
                     },
                     ports: [9000],
                     dependsOn: ["db"],
@@ -1164,56 +1474,6 @@ export function supabase(opts = {}) {
                     },
                 };
             }
-            // ── 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 = {
@@ -1234,11 +1494,10 @@ export function supabase(opts = {}) {
                         content: buildKongYaml(g.key, {
                             anonKey,
                             serviceRoleKey,
-                            dashboardUsername,
-                            dashboardPassword,
                             extraAnonKeys,
                             extraServiceRoleKeys,
                             functions: withFunctions,
+                            oauthServer: withOAuthServer,
                         }),
                     },
                 ],
@@ -1253,9 +1512,9 @@ export function supabase(opts = {}) {
         // 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)
+            if (migrationsPath === null)
                 return;
-            await applyMigrations(ctx, opts.migrations, dbKey);
+            await applyMigrations(ctx, migrationsPath, dbKey);
             await reloadPostgrestSchema(ctx, dbKey, `${name}-rest`);
         },
         // The group's consolidated handle at `ctx.svc.<name>`.