@specific.dev/spectest 0.41.0 → 0.44.0

package/dist/browser.d.ts

@@ -60,6 +60,14 @@ export interface BrowserSessionRecorder {
      * the dashboard can link a browser event to its replay player.
      */
     readonly sessionId: string;
+    /**
+     * Author-given name of this session (`ctx.browser("alice")`), absent
+     * for the default unnamed one. Echoed onto every op's event so the
+     * step list can say WHICH browser acted without having to resolve the
+     * session record — which the CLI's failure detail can't do (it renders
+     * from the persisted events alone, with no replay bundle).
+     */
+    readonly sessionName?: string;
     /** Called for each drained chunk of rrweb events. */
     recordStep(step: BrowserSessionStep): void;
     /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -302,6 +310,9 @@ export declare function openBrowser(opts?: BrowserOptions): Promise<Browser>;
  * the same object.
  */
 export declare function openMobileBackend(opts?: BrowserOptions): Promise<MobileBackend>;
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export declare function mobileKey(name: string, url: string): string;
 /**
  * What acquiring a persistent session returns. `detach` is the test-end
  * hook (final rrweb drain, stop writing to this test's recorder, keep the
@@ -318,17 +329,19 @@ export interface PersistentBrowser {
     detach(): Promise<void>;
 }
 /**
- * Acquire THE persistent desktop browser (creating it on first use). There
- * is deliberately a single one — `ctx.browser()` always returns it — so a
- * test DAG shares one browsing session along each branch. The first call's
- * options win; later calls attach to the existing view as-is.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
-export declare function acquirePersistentBrowser(opts?: BrowserOptions): Promise<PersistentBrowser>;
+export declare function acquirePersistentBrowser(name?: string, opts?: BrowserOptions): Promise<PersistentBrowser>;
 /**
- * Acquire the persistent mobile session for an app URL (one per app). A
- * fresh session navigates to the app; an attach continues on the live page.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
-export declare function acquirePersistentMobileBackend(url: string, recorder: BrowserSessionRecorder | null, initScript?: string): Promise<PersistentBrowser>;
+export declare function acquirePersistentMobileBackend(url: string, name: string, recorder: BrowserSessionRecorder | null, initScript?: string): Promise<PersistentBrowser>;
 export interface RecordableFields {
     url: string;
     selector: string;

package/dist/browser.js

@@ -872,16 +872,45 @@ export async function openMobileBackend(opts = {}) {
 // ────────────────────────────────────────────────────────────────────────
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
 // ────────────────────────────────────────────────────────────────────────
-// One long-lived desktop browser plus one mobile session per app URL.
+// Long-lived sessions, keyed by NAME: one desktop browser per name, one
+// mobile session per (name, app URL). The default name is `""` — what
+// `ctx.browser()` / `ctx.mobile(app)` use — so an unnamed project keeps
+// exactly the one-session-per-device behaviour it had before names
+// existed. A name is the key and nothing else: two names are two
+// BrowserContexts in the one Chromium, i.e. two independent cookie jars
+// and localStorage, which is what modelling two users needs.
+//
 // Module state lives in daemon memory, so it forks with the snapshot the
-// same way fake `state` and TEST_DATA do: a test's browser — its live
-// page, cookies, localStorage, in-memory SPA state — is captured in the
+// same way fake `state` and TEST_DATA do: a test's browsers — their live
+// pages, cookies, localStorage, in-memory SPA state — are captured in the
 // post-test snapshot and inherited by `dependsOn` children, while sibling
 // forks never see each other's sessions. That's what lets a child test
 // continue where its parent left off (e.g. already signed in) instead of
-// re-navigating and re-authenticating.
-let SHARED_BROWSER = null;
+// re-navigating and re-authenticating. The name is a plain string, so it
+// keys the same session on both sides of a fork.
+const SHARED_BROWSERS = new Map();
 const SHARED_MOBILE = new Map();
+/**
+ * Ceiling on live persistent sessions of one kind (desktop / mobile).
+ * Every session is a Chromium BrowserContext that rides every snapshot
+ * from here down the DAG, so a test that mints names in a loop
+ * (`ctx.browser(userId)`) would grow the VM's memory floor for the rest
+ * of the run. Failing loudly at a sane count beats a wedged guest.
+ */
+const MAX_PERSISTENT_SESSIONS = 8;
+/** Registry key for a named mobile session. NUL can't occur in a name or
+ *  a URL, so the two halves can never run together ambiguously. */
+export function mobileKey(name, url) {
+    return `${name}\u0000${url}`;
+}
+/** Guard the session cap, naming the offender and what to do about it. */
+function checkSessionCap(kind, live, name) {
+    if (live < MAX_PERSISTENT_SESSIONS)
+        return;
+    throw new Error(`too many ${kind} sessions: ${MAX_PERSISTENT_SESSIONS} are already open and "${name}" would be another. ` +
+        `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
+        `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
+}
 async function newHolder(width, height, device) {
     const context = await newViewContext(width, height, device);
     const spawned = await spawnPage(context);
@@ -941,58 +970,65 @@ async function attachReset(holder) {
     }
 }
 /**
- * Acquire THE persistent desktop browser (creating it on first use). There
- * is deliberately a single one — `ctx.browser()` always returns it — so a
- * test DAG shares one browsing session along each branch. The first call's
- * options win; later calls attach to the existing view as-is.
+ * Acquire the persistent desktop browser called `name` (creating it on
+ * first use). There is one per name — `ctx.browser()` uses the default
+ * name `""` — so a test DAG shares each named browsing session along each
+ * branch, and two names are two independent users. The first call for a
+ * name wins its options; later calls attach to the existing view as-is.
  */
-export async function acquirePersistentBrowser(opts = {}) {
+export async function acquirePersistentBrowser(name = "", opts = {}) {
     const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
-    let attached = true;
-    if (!SHARED_BROWSER) {
-        attached = false;
-        SHARED_BROWSER = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device);
+    let holder = SHARED_BROWSERS.get(name);
+    const attached = holder !== undefined;
+    if (holder) {
+        await attachReset(holder);
     }
     else {
-        await attachReset(SHARED_BROWSER);
+        checkSessionCap("browser", SHARED_BROWSERS.size, name);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device);
+        SHARED_BROWSERS.set(name, holder);
     }
-    const holder = SHARED_BROWSER;
-    const { backend, detach } = buildBackend(holder, opts.recorder ?? null, {
+    const view = holder;
+    const { backend, detach } = buildBackend(view, opts.recorder ?? null, {
         persistent: true,
         onDestroy: () => {
-            if (SHARED_BROWSER === holder)
-                SHARED_BROWSER = null;
+            if (SHARED_BROWSERS.get(name) === view)
+                SHARED_BROWSERS.delete(name);
         },
     });
     // Fresh session only: an attached view already carries the init script on
     // its (forked) holder, and first-call-wins means a later call's options
     // don't retroactively apply.
     if (!attached && opts.initScript !== undefined) {
-        await installInitScript(holder, opts.initScript);
+        await installInitScript(view, opts.initScript);
     }
     if (!attached && opts.url !== undefined)
         await backend.goto(opts.url);
     return { browser: backend, attached, detach };
 }
 /**
- * Acquire the persistent mobile session for an app URL (one per app). A
- * fresh session navigates to the app; an attach continues on the live page.
+ * Acquire the persistent mobile session for an app URL under `name` (one
+ * per name per app; `ctx.mobile(app)` uses the default name `""`). A fresh
+ * session navigates to the app; an attach continues on the live page.
  */
-export async function acquirePersistentMobileBackend(url, recorder, initScript) {
-    const existing = SHARED_MOBILE.get(url);
+export async function acquirePersistentMobileBackend(url, name, recorder, initScript) {
+    const key = mobileKey(name, url);
+    const existing = SHARED_MOBILE.get(key);
+    if (!existing)
+        checkSessionCap("mobile", SHARED_MOBILE.size, name);
     const holder = existing ??
         (await newHolder(LATEST_IPHONE.viewport.width, LATEST_IPHONE.viewport.height, LATEST_IPHONE));
     if (existing) {
         await attachReset(holder);
     }
     else {
-        SHARED_MOBILE.set(url, holder);
+        SHARED_MOBILE.set(key, holder);
     }
     const { backend, detach } = buildBackend(holder, recorder, {
         persistent: true,
         onDestroy: () => {
-            if (SHARED_MOBILE.get(url) === holder)
-                SHARED_MOBILE.delete(url);
+            if (SHARED_MOBILE.get(key) === holder)
+                SHARED_MOBILE.delete(key);
         },
     });
     if (!existing) {
@@ -1069,6 +1105,18 @@ function buildBackend(holder, recorder, buildOpts) {
     // when rrweb's load-deferred full snapshot is most likely to be
     // missing from the chunk we're about to drain (see `drainExpr`).
     let lastDrainUrl = null;
+    /** Session provenance stamped on every recorded op: which replay player
+     *  the step belongs to, which named browser it acted on, and where in
+     *  the player to seek (`endT`, in rrweb's clock). */
+    function sessionFields(endT) {
+        if (!recorder)
+            return {};
+        return {
+            sessionId: recorder.sessionId,
+            sessionTimestamp: endT,
+            ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
+        };
+    }
     async function drain(action) {
         if (!holder.recordingInstalled || !recorder || recordingEnded)
             return;
@@ -1112,9 +1160,7 @@ function buildBackend(holder, recorder, buildOpts) {
             const seq = recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: endT - t,
             }, resv);
             await drain(action);
@@ -1132,9 +1178,7 @@ function buildBackend(holder, recorder, buildOpts) {
             recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: endT - t,
                 error: e?.message ?? String(err),
             }, resv);
@@ -1459,9 +1503,7 @@ function buildBackend(holder, recorder, buildOpts) {
             const seq = recordBrowser({
                 action,
                 ...fields,
-                ...(recorder
-                    ? { sessionId: recorder.sessionId, sessionTimestamp: endT }
-                    : {}),
+                ...sessionFields(endT),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
             }, reserveBackdated(waitedMs));

package/dist/components/apple.d.ts

@@ -0,0 +1,47 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type AppleOptions = ProviderOptions;
+/**
+ * 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 declare function apple(opts?: AppleOptions): {
+    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/apple.js

@@ -0,0 +1,59 @@
+// `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 { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    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 = {}) {
+    const users = resolveUsers("apple", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/emulate/service.d.ts

@@ -0,0 +1,126 @@
+/** A person who can sign in. Seeded into the provider's account picker. */
+export interface ProviderUser {
+    /** Primary address. Also the account's test id on the picker page. */
+    email: string;
+    /** Display name. */
+    name?: string;
+    /** Avatar URL, passed through to the profile claims. */
+    picture?: string;
+    /** GitHub username. Defaults to the local part of `email`. */
+    login?: string;
+}
+/** An OAuth client, as registered with the real provider. Declaring one
+ *  makes the environment **stricter**: `clientId`, `clientSecret` and
+ *  `redirectUris` are then all validated, exactly as in production. Omit it
+ *  and any client is accepted. */
+export interface OAuthClient {
+    clientId: string;
+    clientSecret: string;
+    /** Callback URLs the app is allowed to return to. A request to any other
+     *  one is refused, which is what makes a misconfigured callback fail here
+     *  rather than in production. */
+    redirectUris?: string[];
+}
+/**
+ * The accounts every provider offers when a component declares none.
+ *
+ * Two, not one: a test that asserts it signed in as Alice only means
+ * something if the provider had somebody else to return. Both carry a
+ * `login`, so GitHub gets a handle without the caller supplying one.
+ *
+ * `example.com` is reserved for exactly this (RFC 2606), so no default
+ * account can ever collide with a real address.
+ */
+export declare const DEFAULT_USERS: readonly ProviderUser[];
+/** Options every provider component takes. */
+export interface ProviderOptions {
+    /**
+     * The accounts offered on the provider's picker page. Defaults to
+     * **Alice Example** (`alice@example.com`) and **Bob Example**
+     * (`bob@example.com`) — enough to sign in as somebody, and to tell two
+     * people apart, without declaring anything.
+     */
+    users?: ProviderUser[];
+    /** The app's OAuth client. Omit it and any client id, secret and callback
+     *  URL are accepted. */
+    client?: OAuthClient;
+}
+/** What `entry.mjs` consumes. Everything provider-specific lives in the
+ *  per-provider module; the script itself is generic. */
+export interface ProviderSpec {
+    name: string;
+    module: string;
+    pluginExport: string;
+    /** Base URL the emulator advertises — the provider's real sign-in host. */
+    baseUrl: string;
+    /** Every hostname routed to this emulator. */
+    hosts: string[];
+    /** False for a plain OAuth 2.0 provider with no id_token (GitHub). */
+    oidc?: boolean;
+    /** Issuer to stamp on the re-issued id_token, where the emulator cannot
+     *  derive it from `baseUrl`. */
+    issuer?: string;
+    /** Values merged over the emulator's discovery document. */
+    discovery?: Record<string, string>;
+    /** Path (as a regex source) answered with our own JWKS. */
+    jwksPath?: string;
+    /** Picker-page identifier → the account's email, where the provider
+     *  identifies an account by something else. Keeps the account's test id
+     *  the same on every provider. */
+    aliases?: Record<string, string>;
+    /** Real path → the path this emulator serves it on. Identity elsewhere. */
+    rewrites?: {
+        from: string;
+        to: string;
+    }[];
+    fallbackUser?: {
+        login: string;
+        id: number;
+        scopes: string[];
+    };
+    seed?: Record<string, unknown>;
+}
+/** The service definition for one provider: the container, plus the claim
+ *  on its domains (one certificate carrying every hostname as a SAN, and a
+ *  proxy route each). One `certificate(...)` rather than per-host `tls`
+ *  entries, for the reason `aws()` gives — `tls` mints a separate leaf per
+ *  entry, and a provider can claim four names. */
+export declare function emulatorService(spec: ProviderSpec): {
+    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;
+    };
+};
+/** The accounts to seed: what the caller declared, or {@link DEFAULT_USERS}.
+ *  An explicitly empty list is a mistake, not a request for none — a
+ *  provider with no accounts can never sign anyone in. */
+export declare function resolveUsers(component: string, users: ProviderUser[] | undefined): ProviderUser[];
+export declare function localPart(email: string): string;
+export declare function givenName(user: ProviderUser): string | undefined;
+export declare function familyName(user: ProviderUser): string | undefined;
+/** The `oauth_clients` seed entry every provider but GitHub uses. */
+export declare function oauthClients(client: OAuthClient | undefined, extra?: Record<string, unknown>): {
+    oauth_clients?: undefined;
+} | {
+    oauth_clients: {
+        client_id: string;
+        client_secret: string;
+        name: string;
+        redirect_uris: string[];
+    }[];
+};

package/dist/components/emulate/service.js

@@ -0,0 +1,153 @@
+// Shared runtime behind the third-party provider components — `google()`,
+// `github()`, `apple()`, `microsoft()`, `okta()`.
+//
+// Each of those is one container answering at that provider's **real**
+// endpoints: the component claims the provider's domains, so DNS, a leaf
+// certificate from the in-VM root CA, and a reverse proxy all point at it.
+// The app under test keeps its production configuration and never learns it
+// is under test.
+//
+// A provider component is therefore a table, not a program. It names the
+// hosts it claims, the emulator package behind it, the handful of paths
+// where that emulator differs from the real service, and how to seed it.
+// Everything else lives here and in `entry.mjs`.
+//
+// ── Internal notes (deliberately not in the user-facing docs) ─────────────
+//
+// The emulators come from vercel-labs/emulate (Apache-2.0), used through
+// their published `@emulators/*` packages and pinned. They are NOT SDK
+// dependencies: they install into the image below. That matters —
+// `sdk/package.json` is in the base-snapshot discriminator, so a dependency
+// here would force a base rebuild and one cold start for every project on
+// the box, for components most projects never use.
+//
+// Each emulator serves every one of its endpoints on ONE origin. Real
+// providers spread them over several hosts, and a few paths differ.
+// `entry.mjs` routes by Host header, applies the per-provider path table,
+// and corrects the discovery document. It also re-issues every id_token
+// with one RSA key it generates at boot, and serves that key at the
+// provider's real JWKS URL. That single step covers three separate faults:
+// the Google emulator signs HS256 and publishes an empty JWKS (so nothing
+// can verify its token), the Microsoft one cannot put the tenant in its
+// issuer, and any future provider whose issuer is not its base URL is
+// handled in advance.
+//
+// The Dockerfile is deliberately CONSTANT — every provider package is
+// installed whether or not this component is the one using it. Two reasons:
+// one image is shared by every provider component and every project on the
+// box, so the layer cache is hit; and the daemon dedupes identical
+// dockerfile builds inside one bootstrap, so five provider services in one
+// environment cost one build, not five.
+//
+// `entry.mjs` ships as an asset next to this file, read at load time and
+// injected with `files`. It is not a `.ts` string constant: it imports
+// `@emulators/*`, which the SDK does not depend on, so `tsc` could not
+// check it anyway, and 200 lines inside a template literal is worse to
+// maintain. `.mjs` also keeps it out of `tsconfig`'s `include` with no
+// exclude rule, and `files: ["src"]` in the manifest still ships it.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../../index.js";
+/** Base image, pinned. Bun runs the emulators' ESM directly. */
+const IMAGE_BASE = "oven/bun:1.3.14-alpine";
+/** Emulator package version, pinned rather than floated. */
+const EMULATE_VERSION = "0.9.0";
+/** The port the provider is served on. Callers reach it through the
+ *  provider's real hostnames, never through this port. */
+const PORT = 4000;
+/** Ready-check budget. The container boots in about a second; the slow part
+ *  is a cold image build on a machine that has never run it. */
+const READY_TIMEOUT_SECS = 120;
+/**
+ * The accounts every provider offers when a component declares none.
+ *
+ * Two, not one: a test that asserts it signed in as Alice only means
+ * something if the provider had somebody else to return. Both carry a
+ * `login`, so GitHub gets a handle without the caller supplying one.
+ *
+ * `example.com` is reserved for exactly this (RFC 2606), so no default
+ * account can ever collide with a real address.
+ */
+export const DEFAULT_USERS = [
+    { email: "alice@example.com", name: "Alice Example", login: "alice" },
+    { email: "bob@example.com", name: "Bob Example", login: "bob" },
+];
+/** The entry script, read from disk next to this module. */
+const ENTRY_SCRIPT = (() => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return readFileSync(path.join(here, "entry.mjs"), "utf8");
+})();
+const DOCKERFILE = `
+FROM ${IMAGE_BASE}
+WORKDIR /srv
+RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
+ && bun add \\
+      @emulators/core@${EMULATE_VERSION} \\
+      @emulators/google@${EMULATE_VERSION} \\
+      @emulators/github@${EMULATE_VERSION} \\
+      @emulators/apple@${EMULATE_VERSION} \\
+      @emulators/microsoft@${EMULATE_VERSION} \\
+      @emulators/okta@${EMULATE_VERSION} \\
+      jose@6
+`;
+/** The service definition for one provider: the container, plus the claim
+ *  on its domains (one certificate carrying every hostname as a SAN, and a
+ *  proxy route each). One `certificate(...)` rather than per-host `tls`
+ *  entries, for the reason `aws()` gives — `tls` mints a separate leaf per
+ *  entry, and a provider can claim four names. */
+export function emulatorService(spec) {
+    const service = {
+        image: { type: "dockerfile", content: DOCKERFILE },
+        command: "bun /srv/auth.mjs",
+        files: [{ path: "/srv/auth.mjs", content: ENTRY_SCRIPT }],
+        env: { SPECTEST_AUTH_CONFIG: JSON.stringify({ port: PORT, providers: [spec] }) },
+        ports: [PORT],
+        readyCheck: {
+            type: "http",
+            port: PORT,
+            path: "/healthz",
+            timeoutSecs: READY_TIMEOUT_SECS,
+        },
+    };
+    return provides(service, [
+        certificate(spec.hosts),
+        ...spec.hosts.map((hostname) => proxy(hostname, { service: SELF_SERVICE_TOKEN, port: PORT })),
+    ]);
+}
+// ── Seeding helpers, shared by the provider modules ───────────────────────
+/** The accounts to seed: what the caller declared, or {@link DEFAULT_USERS}.
+ *  An explicitly empty list is a mistake, not a request for none — a
+ *  provider with no accounts can never sign anyone in. */
+export function resolveUsers(component, users) {
+    if (users && users.length === 0) {
+        throw new Error(`${component}(): \`users\` is empty — omit it for the default accounts`);
+    }
+    return users ?? [...DEFAULT_USERS];
+}
+export function localPart(email) {
+    return email.split("@")[0] ?? email;
+}
+export function givenName(user) {
+    return user.name?.split(" ")[0];
+}
+export function familyName(user) {
+    const parts = user.name?.split(" ") ?? [];
+    return parts.length > 1 ? parts.slice(1).join(" ") : undefined;
+}
+/** The `oauth_clients` seed entry every provider but GitHub uses. */
+export function oauthClients(client, extra = {}) {
+    if (!client)
+        return {};
+    return {
+        oauth_clients: [
+            {
+                client_id: client.clientId,
+                client_secret: client.clientSecret,
+                name: "spectest",
+                redirect_uris: client.redirectUris ?? [],
+                ...extra,
+            },
+        ],
+    };
+}