@specific.dev/spectest 0.43.0 → 0.44.0

package/dist/components/index.d.ts

@@ -6,4 +6,10 @@ export { expo, type ExpoOptions, type ExpoHelpers, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";
 export { aws, type AwsOptions, type LambdaOptions, } from "./aws.js";
+export { type ProviderOptions, type ProviderUser, type OAuthClient, } from "./emulate/service.js";
+export { google, type GoogleOptions } from "./google.js";
+export { github, type GithubOptions } from "./github.js";
+export { apple, type AppleOptions } from "./apple.js";
+export { microsoft, type MicrosoftOptions } from "./microsoft.js";
+export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";

package/dist/components/index.js

@@ -16,4 +16,9 @@ export { expo, } from "./expo.js";
 export { supabase, } from "./supabase.js";
 export { email, } from "./email.js";
 export { aws, } from "./aws.js";
+export { google } from "./google.js";
+export { github } from "./github.js";
+export { apple } from "./apple.js";
+export { microsoft } from "./microsoft.js";
+export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";

package/dist/components/microsoft.d.ts

@@ -0,0 +1,55 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export interface MicrosoftOptions extends ProviderOptions {
+    /**
+     * Directory (tenant) the app signs in against — whatever its authority
+     * URL uses. It appears in the issuer and in every endpoint path, so a
+     * client that checks the issuer sees what it expects. Default `"common"`.
+     */
+    tenantId?: string;
+}
+/**
+ * Microsoft, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { microsoft } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   microsoft: microsoft({
+ *     tenantId: "11111111-2222-3333-4444-555555555555",
+ *     users: [{ email: "bob@example.com", name: "Bob Example" }],
+ *     client: {
+ *       clientId: "6f1a2b3c-…",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/microsoft"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["microsoft"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`,
+ * and the account read back from `https://graph.microsoft.com/v1.0/me`.
+ */
+export declare function microsoft(opts?: MicrosoftOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/microsoft.js

@@ -0,0 +1,76 @@
+// `microsoft()` — Microsoft, emulated inside the environment, answering at
+// its real endpoints.
+//
+// Today that is Sign in with Microsoft (Entra ID) plus the part of Graph an
+// app reads straight after: discovery, the account picker, the token
+// exchange, `/oidc/userinfo` and `/v1.0/me`. The component is named for the
+// provider rather than for the feature — Graph is already claimed, and
+// widening what it serves is a table entry.
+import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    const authority = `https://login.microsoftonline.com/${opts.tenantId || "common"}`;
+    return {
+        name: "microsoft",
+        module: "@emulators/microsoft",
+        pluginExport: "microsoftPlugin",
+        baseUrl: "https://login.microsoftonline.com",
+        hosts: ["login.microsoftonline.com", "graph.microsoft.com"],
+        // The emulator has no tenant, so its issuer is the bare host. A client
+        // that checks the issuer against the authority it configured would
+        // reject that; the re-issue step corrects it.
+        issuer: `${authority}/v2.0`,
+        discovery: {
+            issuer: `${authority}/v2.0`,
+            authorization_endpoint: `${authority}/oauth2/v2.0/authorize`,
+            token_endpoint: `${authority}/oauth2/v2.0/token`,
+            jwks_uri: `${authority}/discovery/v2.0/keys`,
+            end_session_endpoint: `${authority}/oauth2/v2.0/logout`,
+            userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo",
+        },
+        jwksPath: "^/discovery/v2\\.0/keys$",
+        rewrites: [
+            // Real Entra paths carry the tenant; the emulator's do not. The
+            // discovery route is the exception — it handles the tenant itself.
+            { from: "^/[^/]+/(oauth2/v2\\.0/.*)$", to: "/$1" },
+            { from: "^/[^/]+/(discovery/v2\\.0/keys)$", to: "/$1" },
+        ],
+        fallbackUser: {
+            login: users[0].email,
+            id: 1,
+            scopes: ["openid", "email", "profile", "User.Read"],
+        },
+        seed: {
+            users: users.map((u) => ({ email: u.email, name: u.name })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Microsoft, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { microsoft } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   microsoft: microsoft({
+ *     tenantId: "11111111-2222-3333-4444-555555555555",
+ *     users: [{ email: "bob@example.com", name: "Bob Example" }],
+ *     client: {
+ *       clientId: "6f1a2b3c-…",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/microsoft"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["microsoft"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`,
+ * and the account read back from `https://graph.microsoft.com/v1.0/me`.
+ */
+export function microsoft(opts = {}) {
+    const users = resolveUsers("microsoft", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/okta.d.ts

@@ -0,0 +1,51 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export interface OktaOptions extends ProviderOptions {
+    /** The org's domain, e.g. `"dev-12345.okta.com"`. */
+    domain: string;
+}
+/**
+ * Okta, answering at your org's real domain. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { okta } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   okta: okta({
+ *     domain: "dev-12345.okta.com",
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "0oaexample",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/okta"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["okta"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://dev-12345.okta.com/.well-known/openid-configuration`, and
+ * everything it names.
+ */
+export declare function okta(opts: OktaOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/okta.js

@@ -0,0 +1,78 @@
+// `okta()` — Okta, emulated inside the environment, answering at your org's
+// real domain.
+//
+// Today that is Okta sign-in: discovery, the account picker, the token
+// exchange, userinfo, introspection and revocation, on both the org
+// authorization server (`/oauth2/v1/…`) and a custom one
+// (`/oauth2/default/…`). The component is named for the provider rather
+// than for the feature — the backing emulator also carries the users,
+// groups and apps management API.
+//
+// Okta has no fixed hostname: every organization gets its own domain, so
+// `domain` is required where the other providers need nothing.
+import { emulatorService, familyName, givenName, oauthClients, resolveUsers, } from "./emulate/service.js";
+/** Okta's picker identifies an account by its opaque Okta id, so the id has
+ *  to be seeded rather than generated — otherwise nothing on the page can be
+ *  mapped back to an address. */
+function oktaId(email) {
+    return `u-${email.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+}
+function spec(users, opts) {
+    const domain = opts.domain.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    return {
+        name: "okta",
+        module: "@emulators/okta",
+        pluginExport: "oktaPlugin",
+        baseUrl: `https://${domain}`,
+        hosts: [domain],
+        // Okta's issuer is per authorization server and the emulator already
+        // builds it from the base URL, which here is the real org domain.
+        jwksPath: "^/oauth2/(?:[^/]+/)?v1/keys$",
+        aliases: Object.fromEntries(users.map((u) => [oktaId(u.email), u.email])),
+        fallbackUser: { login: users[0].email, id: 1, scopes: ["openid", "profile", "email"] },
+        seed: {
+            users: users.map((u) => ({
+                okta_id: oktaId(u.email),
+                // An Okta login is the address, not the GitHub-style handle that
+                // `login` carries — it comes back as `preferred_username`.
+                login: u.email,
+                email: u.email,
+                first_name: givenName(u),
+                last_name: familyName(u),
+                display_name: u.name,
+            })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Okta, answering at your org's real domain. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { okta } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   okta: okta({
+ *     domain: "dev-12345.okta.com",
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "0oaexample",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/okta"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["okta"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://dev-12345.okta.com/.well-known/openid-configuration`, and
+ * everything it names.
+ */
+export function okta(opts) {
+    const users = resolveUsers("okta", opts.users);
+    if (!opts.domain)
+        throw new Error("okta(): `domain` is required (e.g. \"dev-12345.okta.com\")");
+    return emulatorService(spec(users, opts));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/apple.ts

@@ -0,0 +1,65 @@
+// `apple()` — Apple, emulated inside the environment, answering at its real
+// endpoints.
+//
+// Today that is Sign in with Apple: discovery, the account picker, the
+// token exchange, the refresh grant, and revocation, all on
+// `appleid.apple.com`.
+//
+// Apple publishes **no userinfo endpoint** — the real one does not either,
+// because for Apple the id_token is the whole profile. An app that wants to
+// re-read an account uses the refresh grant, which is the only
+// server-to-server call Apple offers.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+
+export type AppleOptions = ProviderOptions;
+
+function spec(users: ProviderUser[], opts: AppleOptions): ProviderSpec {
+  return {
+    name: "apple",
+    module: "@emulators/apple",
+    pluginExport: "applePlugin",
+    baseUrl: "https://appleid.apple.com",
+    // Every Apple endpoint is on this one host, so no path or discovery
+    // correction is needed.
+    hosts: ["appleid.apple.com"],
+    jwksPath: "^/auth/keys$",
+    fallbackUser: { login: users[0]!.email, id: 1, scopes: ["openid", "email", "name"] },
+    seed: {
+      users: users.map((u) => ({ email: u.email, name: u.name })),
+      // Apple authenticates the client with a signed assertion rather than
+      // a shared secret, so the registration carries a team id instead.
+      ...oauthClients(opts.client, { team_id: "SPECTEST" }),
+    },
+  };
+}
+
+/**
+ * Apple, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { apple } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   apple: apple({
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "com.example.app",
+ *       clientSecret: "client-assertion",
+ *       redirectUris: ["https://app.test/callback/apple"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["apple"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://appleid.apple.com/auth/authorize` and exchanges the code at
+ * `https://appleid.apple.com/auth/token`.
+ */
+export function apple(opts: AppleOptions = {}) {
+  const users = resolveUsers("apple", opts.users);
+  return emulatorService(spec(users, opts));
+}

package/src/components/emulate/entry.mjs

@@ -0,0 +1,244 @@
+// The `socialAuth()` container's entry point.
+//
+// It runs one emulator per configured provider (the `@emulators/*` packages
+// from vercel-labs/emulate) and puts all of them behind ONE port, routed by
+// `Host` header. That is what lets the component answer at the providers'
+// real endpoints: the daemon owns DNS and TLS for those names and proxies
+// every one of them here.
+//
+// The engine is generic. Everything provider-specific — which hosts to
+// claim, which paths differ from the real ones, which discovery values to
+// correct — arrives as JSON in SPECTEST_AUTH_CONFIG, built by
+// `../social-auth.ts`. Add a provider there, not here.
+//
+// Four things happen to a response on the way out:
+//
+//   * discovery — the emulator advertises every endpoint on its own single
+//     origin. Real providers spread them over several hosts. We merge the
+//     real URLs in.
+//   * JWKS — we serve one RSA public key, for every provider.
+//   * id_token — we re-issue it: same claims, RS256, our key, and a
+//     corrected `iss` where the emulator cannot know it. This is one step
+//     that fixes three faults. The Google emulator signs HS256 and serves
+//     an empty JWKS, so no client can verify its token. The Microsoft one
+//     cannot put the tenant in the issuer, because it does not know it.
+//     And any future provider whose issuer does not match its base URL is
+//     covered in advance. No signature check is needed on the way in: the
+//     token comes from an in-process function call, not from the network.
+//   * the account picker page — each button gets a `data-testid`, so a
+//     browser test has a stable locator.
+//
+// Every request is logged. Per-case service logs reach the dashboard, so
+// the whole OAuth exchange is readable on the case page with no helper API.
+
+import { createServer } from "@emulators/core";
+import { SignJWT, decodeJwt, exportJWK } from "jose";
+
+const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
+const PORT = Number(CONFIG.port ?? 4000);
+/** Key id published in the JWKS and stamped on every re-issued id_token. */
+const KID = "spectest-social-auth";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Signing key
+//
+// Generated once, at boot — which is before the warm-template snapshot, so
+// every fork of this environment holds the same key and a token minted in a
+// parent stays valid in a child. Never generate it later: after a fork the
+// guest RNG is frozen, and sibling forks would produce identical keys.
+// ──────────────────────────────────────────────────────────────────────────
+
+const KEY_PAIR = await crypto.subtle.generateKey(
+  {
+    name: "RSASSA-PKCS1-v1_5",
+    modulusLength: 2048,
+    publicExponent: new Uint8Array([1, 0, 1]),
+    hash: "SHA-256",
+  },
+  true,
+  ["sign", "verify"],
+);
+const JWKS = {
+  keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
+};
+
+// ──────────────────────────────────────────────────────────────────────────
+// Providers
+// ──────────────────────────────────────────────────────────────────────────
+
+/** host → runtime record. One emulator can claim several hosts. */
+const BY_HOST = new Map();
+
+for (const spec of CONFIG.providers ?? []) {
+  const mod = await import(spec.module);
+  const plugin = mod[spec.pluginExport];
+  if (!plugin) {
+    throw new Error(
+      `social-auth: ${spec.module} has no export ${spec.pluginExport}`,
+    );
+  }
+
+  // `port` only feeds the emulator's default base URL, which we always
+  // override — nothing listens on it. Each emulator is a fetch handler.
+  const { app, store, webhooks } = createServer(plugin, {
+    port: PORT,
+    baseUrl: spec.baseUrl,
+    fallbackUser: spec.fallbackUser,
+  });
+  plugin.seed?.(store, spec.baseUrl);
+  if (spec.seed && mod.seedFromConfig) {
+    mod.seedFromConfig(store, spec.baseUrl, spec.seed, webhooks);
+  }
+
+  const runtime = {
+    name: spec.name,
+    baseUrl: spec.baseUrl,
+    oidc: spec.oidc !== false,
+    issuer: spec.issuer,
+    discovery: spec.discovery ?? {},
+    jwksPath: spec.jwksPath ? new RegExp(spec.jwksPath) : null,
+    aliases: spec.aliases,
+    rewrites: (spec.rewrites ?? []).map((r) => ({ re: new RegExp(r.from), to: r.to })),
+    fetch: app.fetch,
+  };
+  for (const host of spec.hosts) BY_HOST.set(host.toLowerCase(), runtime);
+  console.log(`[social-auth] ${spec.name} → ${spec.hosts.join(", ")}`);
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Response rewriting
+// ──────────────────────────────────────────────────────────────────────────
+
+const DISCOVERY_RE = /\/\.well-known\/openid-configuration$/;
+
+/** Correct the discovery document: real hosts per endpoint, and RS256,
+ *  which is what we actually sign with after `reissueIdToken`. */
+async function patchDiscovery(res, provider) {
+  const doc = await res.json();
+  const patched = {
+    ...doc,
+    ...provider.discovery,
+    id_token_signing_alg_values_supported: ["RS256"],
+  };
+  return json(patched, res.status);
+}
+
+/** Re-issue the id_token on a token response. Claims pass through
+ *  unchanged except `iss`, which only a provider that cannot derive it
+ *  from its base URL overrides. */
+async function patchTokenResponse(res, provider) {
+  const body = await res.json();
+  if (typeof body.id_token !== "string") return json(body, res.status);
+
+  const claims = decodeJwt(body.id_token);
+  if (provider.issuer) claims.iss = provider.issuer;
+  body.id_token = await new SignJWT(claims)
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .sign(KEY_PAIR.privateKey);
+  return json(body, res.status);
+}
+
+/** Give every account button on the picker page a stable test id, and mark
+ *  the page itself. The hidden field that identifies the account is named
+ *  differently per provider, and does not always hold the address — GitHub
+ *  identifies an account by its login — so `aliases` maps it back. The test
+ *  id is the account's email on every provider. */
+async function patchPickerPage(res, provider) {
+  let html = await res.text();
+  html = html.replace(/<form class="user-form"[\s\S]*?<\/form>/g, (form) => {
+    const id = /<input type="hidden" name="(?:email|login|sub|username|user_ref)" value="([^"]*)"/.exec(form);
+    if (!id) return form;
+    const account = provider.aliases?.[id[1]] ?? id[1];
+    return form.replace(
+      "<button type=\"submit\"",
+      `<button type="submit" data-testid="spectest-user-${account}"`,
+    );
+  });
+  html = html.replace("<body", '<body data-spectest-signin="1"');
+  return new Response(html, { status: res.status, headers: res.headers });
+}
+
+function json(value, status) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Server
+// ──────────────────────────────────────────────────────────────────────────
+
+Bun.serve({
+  port: PORT,
+  // The default 10s kills nothing here, but an authorize page fetched by a
+  // cold browser can be slower than it looks. Ingress uses the same margin.
+  idleTimeout: 60,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // Answered on any Host, because the ready check probes the container's
+    // own IP and never sends a provider name.
+    if (url.pathname === "/healthz") return new Response("ok\n");
+
+    // The daemon reverse-proxies us and rewrites `Host` to the service-net
+    // name, so the provider the client asked for only survives in
+    // `X-Forwarded-Host`. Read that first; `Host` covers a direct call.
+    const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "")
+      .toLowerCase()
+      .replace(/:\d+$/, "");
+    const provider = BY_HOST.get(host);
+    if (!provider) {
+      return new Response(
+        `spectest social-auth: no provider claims Host=${JSON.stringify(host)}\n` +
+          `claimed hosts: ${[...BY_HOST.keys()].join(", ")}\n`,
+        { status: 404, headers: { "content-type": "text/plain" } },
+      );
+    }
+
+    // Real path → the path this emulator serves it on. Identity by default,
+    // which is also what carries the emulator's own internal endpoints (the
+    // picker's POST target) through untouched.
+    let path = url.pathname;
+    for (const rule of provider.rewrites) {
+      if (rule.re.test(path)) {
+        path = path.replace(rule.re, rule.to);
+        break;
+      }
+    }
+
+    let res;
+    if (provider.oidc && provider.jwksPath?.test(path)) {
+      // Our key, never the emulator's — we re-sign every id_token.
+      res = json(JWKS, 200);
+    } else {
+      const body =
+        req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
+      // Restore the Host the client used, so an emulator that reads it sees
+      // the provider rather than our container.
+      const headers = new Headers(req.headers);
+      headers.set("host", host);
+      const inner = new Request(new URL(path + url.search, provider.baseUrl), {
+        method: req.method,
+        headers,
+        body,
+      });
+      res = await provider.fetch(inner);
+
+      const type = res.headers.get("content-type") ?? "";
+      if (type.includes("json")) {
+        if (DISCOVERY_RE.test(path)) res = await patchDiscovery(res, provider);
+        else if (provider.oidc) res = await patchTokenResponse(res, provider);
+      } else if (type.includes("text/html")) {
+        res = await patchPickerPage(res, provider);
+      }
+    }
+
+    console.log(
+      `[social-auth] ${provider.name} ${req.method} ${host}${url.pathname} → ${res.status}`,
+    );
+    return res;
+  },
+});
+
+console.log(`[social-auth] listening on :${PORT}`);