@specific.dev/spectest 0.14.0 → 0.16.0

package/src/components/supabase.ts

@@ -63,6 +63,7 @@ import {
   type ServicesMap,
 } from "../index.js";
 import { SQL, type SqlClient } from "../sql.js";
+import { email, emailHelpers, type EmailHelpers } from "./email.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -132,12 +133,45 @@ export interface SupabaseOptions {
    */
   hostname?: string;
 
+  /**
+   * Capture GoTrue's outgoing mail (magic links, OTPs, password recovery,
+   * invites — and signup confirmations with `autoconfirm: false`) with the
+   * standard `email()` component. **On by default**: the stack includes the
+   * capture server (`<name>-mail`) with GoTrue's SMTP wired at it, and tests
+   * read the mailbox through the typed helpers at `ctx.svc.<name>.mail`
+   * (`lastEmail` / `emails` / `clear`), each captured message rendering
+   * mail-client-style on the dashboard timeline.
+   *
+   * Signups stay one-step by default (`autoconfirm: true`) so the mailbox is
+   * purely additive; pass `{ autoconfirm: false }` to test real
+   * email-confirmation flows. Pass `{ service: "<key>" }` to point GoTrue at
+   * an `email()` service the environment already declares — keep a single
+   * mailbox per environment rather than one per component: if the app under
+   * test also sends mail, share one `email()` between it and Supabase
+   * instead of standing up a second capture server. `false` disables mail
+   * capture entirely.
+   */
+  mail?: boolean | SupabaseMailOptions;
+
+  /**
+   * Extra API keys the gateway accepts alongside the derived JWT keys — for
+   * clients that ship a hardcoded key (e.g. an `sb_publishable_…` /
+   * `sb_secret_…` pair baked into an app build). Each `anon` key is admitted
+   * with anon privileges and each `serviceRole` key with service-role
+   * privileges; Kong swaps the matching *derived JWT* in before proxying, so
+   * GoTrue/PostgREST/Realtime still receive a validly-signed token.
+   */
+  extraApiKeys?: { anon?: string[]; serviceRole?: string[] };
+
   /**
    * Auto-apply SQL migrations found in the project before any dependent service
    * starts. `true` (default) applies every `*.sql` under `supabase/migrations/`
    * (sorted, the Supabase convention), then `supabase/seed.sql` if present — a
    * no-op when the directory is absent. Pass a string to point at a different
    * directory (relative to the project root or absolute), or `false` to skip.
+   * An *explicitly configured* 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/**`).
    */
@@ -150,6 +184,28 @@ export interface SupabaseOptions {
   seed?: boolean | string;
 }
 
+/** Tuning for `SupabaseOptions.mail`. */
+export interface SupabaseMailOptions {
+  /**
+   * Reuse an `email()` service the environment already declares (its
+   * services-map key) instead of adding one to the group — the way to keep a
+   * single global mailbox when the app under test sends mail too. Assumes
+   * the service's default ports (SMTP 1025, API 8025).
+   */
+  service?: string;
+  /**
+   * Whether GoTrue autoconfirms signups. `true` (default): signups complete
+   * in one step and send no confirmation mail — recovery, magic-link and OTP
+   * mail is still sent and captured. Set `false` to exercise real
+   * email-confirmation flows (signups require the emailed verification).
+   */
+  autoconfirm?: boolean;
+  /** Sender address GoTrue mails from. Default `admin@example.com`. */
+  adminEmail?: string;
+  /** Sender display name. Default `Supabase`. */
+  senderName?: string;
+}
+
 /** Helpers the gateway service exposes on `ctx.svc.<name>`. */
 export interface SupabaseHelpers {
   /**
@@ -165,6 +221,18 @@ export interface SupabaseHelpers {
   anonKey: string;
   /** Long-lived `service_role` API key (HS256 JWT). Bypasses RLS — server-side only. */
   serviceRoleKey: string;
+  /**
+   * The captured-mail mailbox (`lastEmail` / `emails` / `clear`) — present
+   * unless the stack was built with `mail: false`. Wait for delivery with
+   * the standard `ctx.poll`:
+   *
+   * ```ts
+   * const mail = await ctx.poll("confirmation email", () =>
+   *   ctx.svc.supabase.mail!.lastEmail());
+   * expect(mail.to).toContain("alice@example.com");
+   * ```
+   */
+  mail?: EmailHelpers;
 }
 
 /** What `supabase()` returns: the service group plus the derived
@@ -185,6 +253,12 @@ export interface SupabaseStack {
   /** The gateway service key — use in a dependent service's `dependsOn` to wait
    *  for the whole stack (the gateway waits on the services behind it). */
   ready: string;
+  /**
+   * Where the stack's SMTP capture server listens (absent with
+   * `mail: false`) — point the app under test's own mail transport here to
+   * share the one mailbox: `env: { SMTP_HOST: sb.smtp.host, SMTP_PORT: String(sb.smtp.port) }`.
+   */
+  smtp?: { host: string; port: number };
   /** Ready-to-spread env for the app under test: `SUPABASE_URL`,
    *  `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`. */
   appEnv: Record<string, string>;
@@ -277,12 +351,32 @@ function buildBootstrapSql(
 // ──────────────────────────────────────────────────────────────────────────
 
 // The two Lua router expressions kong-entrypoint.sh emits when the opaque
-// `sb_`-style keys are NOT configured (our case): pass the incoming apikey (a
-// legacy HS256 JWT) through unchanged, preferring an existing non-`sb_`
-// Authorization header.
-const LUA_AUTH_EXPR =
-  "$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_' and headers.authorization) or headers.apikey)";
-const LUA_RT_WS_EXPR = "$(query_params.apikey)";
+// `sb_`-style keys are NOT configured: pass the incoming apikey (a legacy
+// HS256 JWT) through unchanged, preferring an existing non-`sb_`
+// Authorization header. `extraApiKeys` extends both: an extra key (arriving
+// as `apikey` header, `Authorization: Bearer <key>`, or the websocket
+// `?apikey=` query param) is swapped for the corresponding *derived JWT*
+// before proxying, so the upstream services still see a validly-signed token.
+function buildLuaExprs(
+  extra: Array<{ key: string; jwt: string }>,
+): { auth: string; realtimeWs: string } {
+  // Keep a client's `Authorization: Bearer <extraKey>` from winning the
+  // header-passthrough clause with the raw (non-JWT) key.
+  const guards = extra
+    .map((m) => ` and headers.authorization ~= 'Bearer ${m.key}'`)
+    .join("");
+  const mappings = extra
+    .map(
+      (m) =>
+        ` or ((headers.apikey == '${m.key}' or headers.authorization == 'Bearer ${m.key}') and 'Bearer ${m.jwt}')`,
+    )
+    .join("");
+  const auth = `$((headers.authorization ~= nil and headers.authorization:sub(1, 10) ~= 'Bearer sb_'${guards} and headers.authorization)${mappings} or headers.apikey)`;
+  const wsMappings = extra
+    .map((m) => `(query_params.apikey == '${m.key}' and '${m.jwt}') or `)
+    .join("");
+  return { auth, realtimeWs: `$(${wsMappings}query_params.apikey)` };
+}
 
 const KONG_YML_RAW = String.raw`_format_version: '2.1'
 _transform: true
@@ -631,9 +725,26 @@ function buildKongYaml(
     serviceRoleKey: string;
     dashboardUsername: string;
     dashboardPassword: string;
+    extraAnonKeys: string[];
+    extraServiceRoleKeys: string[];
   },
 ): string {
   let y = KONG_YML_RAW;
+  // Extra API keys land where kong-entrypoint.sh's opaque keys would: as
+  // additional keyauth credentials on the matching consumer. The template's
+  // placeholder lines are either expanded here or dropped by the filter below.
+  if (vals.extraAnonKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_PUBLISHABLE_KEY",
+      vals.extraAnonKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
+  if (vals.extraServiceRoleKeys.length > 0) {
+    y = y.replace(
+      "      - key: $SUPABASE_SECRET_KEY",
+      vals.extraServiceRoleKeys.map((k) => `      - key: ${k}`).join("\n"),
+    );
+  }
   // Rewrite upstream bare service hosts → the group's final DNS names.
   y = y
     .replaceAll("http://auth:9999", `http://${key("auth")}:9999`)
@@ -644,9 +755,13 @@ function buildKongYaml(
     .replaceAll("http://functions:9000", `http://${key("functions")}:9000`)
     .replaceAll("realtime-dev.supabase-realtime", `realtime-dev.${key("realtime")}`);
   // Lua expressions first (they contain no `$SUPABASE_*` tokens).
-  y = y.replaceAll("$LUA_AUTH_EXPR", LUA_AUTH_EXPR).replaceAll(
+  const lua = buildLuaExprs([
+    ...vals.extraAnonKeys.map((k) => ({ key: k, jwt: vals.anonKey })),
+    ...vals.extraServiceRoleKeys.map((k) => ({ key: k, jwt: vals.serviceRoleKey })),
+  ]);
+  y = y.replaceAll("$LUA_AUTH_EXPR", lua.auth).replaceAll(
     "$LUA_RT_WS_EXPR",
-    LUA_RT_WS_EXPR,
+    lua.realtimeWs,
   );
   // API keys + dashboard credentials.
   y = y
@@ -707,14 +822,17 @@ async function applyMigrations(
   ctx: ServiceSetupContext,
   cfg: { migrations: boolean | string; seed: boolean | string },
 ): Promise<void> {
-  // Migrations directory.
+  // Migrations directory. An *explicitly configured* path that doesn't
+  // resolve is a hard error — a silent no-op here surfaces much later as a
+  // baffling `relation "public.…" does not exist`. Only the `true` default
+  // (conventional `supabase/migrations/`) is allowed to be absent.
   if (cfg.migrations !== false) {
-    const dir =
-      typeof cfg.migrations === "string"
-        ? cfg.migrations.startsWith("/")
-          ? cfg.migrations
-          : join(ctx.projectRoot, cfg.migrations)
-        : join(ctx.projectRoot, "supabase", "migrations");
+    const explicit = typeof cfg.migrations === "string";
+    const dir = explicit
+      ? (cfg.migrations as string).startsWith("/")
+        ? (cfg.migrations as string)
+        : join(ctx.projectRoot, cfg.migrations as string)
+      : join(ctx.projectRoot, "supabase", "migrations");
     if (existsSync(dir) && (await stat(dir)).isDirectory()) {
       const files = (await readdir(dir))
         .filter((f) => f.endsWith(".sql"))
@@ -723,19 +841,34 @@ async function applyMigrations(
         const sql = await ctx.readProjectFile(join(dir, f));
         await applySqlFile(ctx, sql, `migration ${f}`, "postgres");
       }
+    } else if (explicit) {
+      throw new Error(
+        `supabase: configured migrations path ${JSON.stringify(
+          cfg.migrations,
+        )} does not resolve to a directory (looked at ${dir}). ` +
+          `Fix the \`migrations\` option, or remove it to use the default ` +
+          `supabase/migrations/. Note the path is resolved inside the uploaded ` +
+          `project — check it isn't ignored (e.g. via .spectestignore).`,
+      );
     }
   }
-  // Seed file.
+  // Seed file — same contract: only the conventional default may be absent.
   if (cfg.seed !== false) {
-    const seedPath =
-      typeof cfg.seed === "string"
-        ? cfg.seed.startsWith("/")
-          ? cfg.seed
-          : join(ctx.projectRoot, cfg.seed)
-        : join(ctx.projectRoot, "supabase", "seed.sql");
+    const explicit = typeof cfg.seed === "string";
+    const seedPath = explicit
+      ? (cfg.seed as string).startsWith("/")
+        ? (cfg.seed as string)
+        : join(ctx.projectRoot, cfg.seed as string)
+      : join(ctx.projectRoot, "supabase", "seed.sql");
     if (existsSync(seedPath)) {
       const sql = await ctx.readProjectFile(seedPath);
       await applySqlFile(ctx, sql, "seed.sql", "postgres");
+    } else if (explicit) {
+      throw new Error(
+        `supabase: configured seed path ${JSON.stringify(cfg.seed)} not found ` +
+          `(looked at ${seedPath}). Fix the \`seed\` option or remove it to ` +
+          `use the default supabase/seed.sql.`,
+      );
     }
   }
 }
@@ -773,6 +906,29 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   const withStudio = opts.studio ?? false;
   const withMeta = opts.meta ?? withStudio;
 
+  // Mail capture (see SupabaseOptions.mail) — on unless explicitly disabled.
+  // `mailKey` is the SMTP host GoTrue mails through — the in-group part
+  // (`<name>-mail`) or a user-declared `email()` service shared with the app
+  // under test.
+  const withMail = opts.mail !== false;
+  const mailOpts: SupabaseMailOptions =
+    typeof opts.mail === "object" ? opts.mail : {};
+  const mailExternal = mailOpts.service !== undefined;
+  const mailKey = mailOpts.service ?? `${name}-mail`;
+  const mailAutoconfirm = mailOpts.autoconfirm ?? true;
+
+  const extraAnonKeys = opts.extraApiKeys?.anon ?? [];
+  const extraServiceRoleKeys = opts.extraApiKeys?.serviceRole ?? [];
+  for (const k of [...extraAnonKeys, ...extraServiceRoleKeys]) {
+    // The keys are spliced into Kong's YAML and its quoted Lua expressions —
+    // restrict to the token charset real API keys use so neither can break.
+    if (!/^[A-Za-z0-9._-]+$/.test(k)) {
+      throw new Error(
+        `supabase(): extraApiKeys entries must match [A-Za-z0-9._-]+ (got ${JSON.stringify(k)})`,
+      );
+    }
+  }
+
   const anonKey = apiKey("anon", jwtSecret);
   const serviceRoleKey = apiKey("service_role", jwtSecret);
 
@@ -872,6 +1028,11 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         readyCheck: { type: "tcp", port: 3000, timeoutSecs: 120 },
       };
 
+      // ── mail (SMTP capture, the standard email() component) ─────────
+      if (withMail && !mailExternal) {
+        parts.mail = email();
+      }
+
       // ── auth (GoTrue) ───────────────────────────────────────────────
       if (withAuth) {
         const apiExternalUrl = `${url}/auth/v1`;
@@ -894,14 +1055,39 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             GOTRUE_JWT_ISSUER: apiExternalUrl,
             GOTRUE_EXTERNAL_EMAIL_ENABLED: "true",
             GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED: "true",
-            // Autoconfirm so tests can sign up without a mail server
-            // round-trip.
-            GOTRUE_MAILER_AUTOCONFIRM: "true",
+            // Autoconfirm defaults ON (one-step signups, no confirmation
+            // mail) so the always-on mailbox is purely additive; the mail
+            // option's `autoconfirm: false` opts into real confirmation
+            // flows.
+            GOTRUE_MAILER_AUTOCONFIRM:
+              withMail && !mailAutoconfirm ? "false" : "true",
             GOTRUE_EXTERNAL_PHONE_ENABLED: "false",
             GOTRUE_SMS_AUTOCONFIRM: "true",
+            ...(withMail
+              ? {
+                  GOTRUE_SMTP_HOST: mailKey,
+                  GOTRUE_SMTP_PORT: "1025",
+                  // Deliberately NO GOTRUE_SMTP_USER/PASS: the capture
+                  // server advertises AUTH, and with credentials set
+                  // GoTrue's Go smtp.PlainAuth refuses to send them over a
+                  // plaintext connection ("unencrypted connection" → every
+                  // mail 500s). Unauthenticated submission is accepted.
+                  GOTRUE_SMTP_ADMIN_EMAIL:
+                    mailOpts.adminEmail ?? "admin@example.com",
+                  GOTRUE_SMTP_SENDER_NAME: mailOpts.senderName ?? "Supabase",
+                  // GoTrue rate-limits repeat mail to the same address
+                  // (default 1/min) — far too slow for tests that
+                  // request an OTP, assert, and request again.
+                  GOTRUE_SMTP_MAX_FREQUENCY: "1s",
+                  GOTRUE_MAILER_URLPATHS_INVITE: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_CONFIRMATION: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_RECOVERY: "/auth/v1/verify",
+                  GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: "/auth/v1/verify",
+                }
+              : {}),
           },
           ports: [9999],
-          dependsOn: ["db"],
+          dependsOn: ["db", ...(withMail && !mailExternal ? ["mail"] : [])],
           readyCheck: { type: "http", port: 9999, path: "/health", timeoutSecs: 90 },
         };
       }
@@ -1071,6 +1257,8 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
               serviceRoleKey,
               dashboardUsername,
               dashboardPassword,
+              extraAnonKeys,
+              extraServiceRoleKeys,
             }),
           },
         ],
@@ -1087,6 +1275,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       url,
       anonKey,
       serviceRoleKey,
+      ...(withMail ? { mail: emailHelpers(mailKey) } : {}),
     }),
   });
 
@@ -1105,5 +1294,6 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     dbUrl,
     ready: name,
     appEnv,
+    ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
   };
 }