@specific.dev/spectest 0.43.0 → 0.44.0

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

package/src/components/google.ts

@@ -0,0 +1,104 @@
+// `google()` — Google, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with Google: OpenID Connect discovery, the account
+// picker, PKCE, the token exchange, refresh, and userinfo. The component is
+// named for the provider rather than for the feature, because the backing
+// emulator also carries Gmail, Calendar and Drive — claiming
+// `gmail.googleapis.com` and routing it here is a table entry, not a new
+// design.
+
+import type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import {
+  emulatorService,
+  familyName,
+  givenName,
+  oauthClients,
+  resolveUsers,
+} from "./emulate/service.js";
+
+export type GoogleOptions = ProviderOptions;
+
+function spec(users: ProviderUser[], opts: GoogleOptions): ProviderSpec {
+  return {
+    name: "google",
+    module: "@emulators/google",
+    pluginExport: "googlePlugin",
+    baseUrl: "https://accounts.google.com",
+    hosts: [
+      "accounts.google.com",
+      "oauth2.googleapis.com",
+      "www.googleapis.com",
+      "openidconnect.googleapis.com",
+    ],
+    discovery: {
+      issuer: "https://accounts.google.com",
+      authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+      token_endpoint: "https://oauth2.googleapis.com/token",
+      userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+      revocation_endpoint: "https://oauth2.googleapis.com/revoke",
+      jwks_uri: "https://www.googleapis.com/oauth2/v3/certs",
+    },
+    jwksPath: "^/oauth2/v3/certs$",
+    rewrites: [
+      // oauth2.googleapis.com serves these at the root; the emulator puts
+      // them under /oauth2.
+      { from: "^/token$", to: "/oauth2/token" },
+      { from: "^/revoke$", to: "/oauth2/revoke" },
+      // openidconnect.googleapis.com and the v3 alias both mean userinfo.
+      { from: "^/v1/userinfo$", to: "/oauth2/v2/userinfo" },
+      { from: "^/oauth2/v3/userinfo$", to: "/oauth2/v2/userinfo" },
+    ],
+    fallbackUser: { login: users[0]!.email, id: 1, scopes: ["openid", "email", "profile"] },
+    seed: {
+      users: users.map((u) => ({
+        email: u.email,
+        name: u.name,
+        given_name: givenName(u),
+        family_name: familyName(u),
+        picture: u.picture,
+        email_verified: true,
+      })),
+      ...oauthClients(opts.client),
+    },
+  };
+}
+
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export function google(opts: GoogleOptions = {}) {
+  const users = resolveUsers("google", opts.users);
+  return emulatorService(spec(users, opts));
+}

package/src/components/index.ts

@@ -62,6 +62,20 @@ export {
   type AwsOptions,
   type LambdaOptions,
 } from "./aws.js";
+// Third-party providers, each answering at its own real endpoints. Named
+// for the provider rather than for sign-in, because each one's surface can
+// grow past auth (Gmail and Calendar for `google`, the REST API for
+// `github`, Graph for `microsoft`).
+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,

package/src/components/microsoft.ts

@@ -0,0 +1,89 @@
+// `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 type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import { emulatorService, oauthClients, resolveUsers } 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;
+}
+
+function spec(users: ProviderUser[], opts: MicrosoftOptions): ProviderSpec {
+  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: MicrosoftOptions = {}) {
+  const users = resolveUsers("microsoft", opts.users);
+  return emulatorService(spec(users, opts));
+}

package/src/components/okta.ts

@@ -0,0 +1,93 @@
+// `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 type { ProviderOptions, ProviderSpec, ProviderUser } from "./emulate/service.js";
+import {
+  emulatorService,
+  familyName,
+  givenName,
+  oauthClients,
+  resolveUsers,
+} from "./emulate/service.js";
+
+export interface OktaOptions extends ProviderOptions {
+  /** The org's domain, e.g. `"dev-12345.okta.com"`. */
+  domain: string;
+}
+
+/** 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: string): string {
+  return `u-${email.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+}
+
+function spec(users: ProviderUser[], opts: OktaOptions): ProviderSpec {
+  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: OktaOptions) {
+  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));
+}