@specific.dev/spectest 0.41.0 → 0.44.0

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}`);

package/src/components/emulate/service.ts

@@ -0,0 +1,235 @@
+// 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 type { ServiceDefinition } from "../../index.js";
+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;
+
+/** 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 const DEFAULT_USERS: readonly ProviderUser[] = [
+  { email: "alice@example.com", name: "Alice Example", login: "alice" },
+  { email: "bob@example.com", name: "Bob Example", login: "bob" },
+];
+
+/** 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 entry script, read from disk next to this module. */
+const ENTRY_SCRIPT: string = (() => {
+  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: ProviderSpec) {
+  const service = {
+    image: { type: "dockerfile" as const, 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" as const,
+      port: PORT,
+      path: "/healthz",
+      timeoutSecs: READY_TIMEOUT_SECS,
+    },
+  } satisfies ServiceDefinition;
+
+  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: string, users: ProviderUser[] | undefined): ProviderUser[] {
+  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: string): string {
+  return email.split("@")[0] ?? email;
+}
+
+export function givenName(user: ProviderUser): string | undefined {
+  return user.name?.split(" ")[0];
+}
+
+export function familyName(user: ProviderUser): string | undefined {
+  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: OAuthClient | undefined, extra: Record<string, unknown> = {}) {
+  if (!client) return {};
+  return {
+    oauth_clients: [
+      {
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        name: "spectest",
+        redirect_uris: client.redirectUris ?? [],
+        ...extra,
+      },
+    ],
+  };
+}

package/src/components/github.ts

@@ -0,0 +1,96 @@
+// `github()` — GitHub, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with GitHub — the authorize page, the token
+// exchange, and the profile reads every GitHub sign-in makes (`/user`,
+// `/user/emails`). The component is named for the provider rather than for
+// the feature: the backing emulator carries most of the REST API — repos,
+// issues, pull requests, checks, webhooks — and reaching it is a matter of
+// what this component chooses to expose, not of new plumbing.
+//
+// Landmine for whoever extends this: the claim is env-wide. `github.com`
+// and `api.github.com` stop reaching the internet for every container in
+// the environment, so anything else that talks to GitHub — a build step
+// that clones a repository, an unrelated API call — reaches the emulator
+// and gets a 404 outside the surface it serves.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import { emulatorService, localPart, resolveUsers } from "./emulate/service.js";
+
+export type GithubOptions = ProviderOptions;
+
+function spec(users: ProviderUser[], opts: GithubOptions): ProviderSpec {
+  const client = opts.client;
+  return {
+    name: "github",
+    module: "@emulators/github",
+    pluginExport: "githubPlugin",
+    baseUrl: "https://github.com",
+    // api.github.com cannot be avoided: every GitHub sign-in reads the
+    // profile from /user and the addresses from /user/emails.
+    hosts: ["github.com", "api.github.com"],
+    // OAuth 2.0, not OIDC — there is no id_token to re-issue and no JWKS.
+    oidc: false,
+    // GitHub identifies an account by login, not by address.
+    aliases: Object.fromEntries(users.map((u) => [u.login ?? localPart(u.email), u.email])),
+    fallbackUser: {
+      login: users[0]!.login ?? localPart(users[0]!.email),
+      id: 1,
+      scopes: ["user", "user:email"],
+    },
+    seed: {
+      users: users.map((u) => ({
+        login: u.login ?? localPart(u.email),
+        name: u.name,
+        email: u.email,
+      })),
+      // GitHub calls them oauth_apps, and its own field is `oauth_apps`.
+      ...(client
+        ? {
+            oauth_apps: [
+              {
+                client_id: client.clientId,
+                client_secret: client.clientSecret,
+                name: "spectest",
+                redirect_uris: client.redirectUris ?? [],
+              },
+            ],
+          }
+        : {}),
+    },
+  };
+}
+
+/**
+ * GitHub, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { github } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   github: github({
+ *     users: [{ email: "bob@example.com", name: "Bob Example", login: "bob" }],
+ *     client: {
+ *       clientId: "Iv1.example",
+ *       clientSecret: "ghs_example",
+ *       redirectUris: ["https://app.test/callback/github"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["github"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://github.com/login/oauth/authorize`, exchanges the code at
+ * `https://github.com/login/oauth/access_token`, and reads the account from
+ * `https://api.github.com/user`.
+ *
+ * The account's test id on the picker page is its **email**, even though
+ * GitHub identifies it by login — so a test reads the same whichever
+ * provider it drives.
+ */
+export function github(opts: GithubOptions = {}) {
+  const users = resolveUsers("github", opts.users);
+  return emulatorService(spec(users, opts));
+}