@specific.dev/spectest 0.43.0 → 0.45.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/dist/daemon.js

@@ -34,6 +34,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
@@ -3072,15 +3073,34 @@ function installFetchWrapper() {
             const res = await original(input, init);
             let responseBody;
             let responseBodyTruncated;
-            try {
-                const cloned = res.clone();
-                const text = await cloned.text();
-                const t = truncateUtf8(text);
-                responseBody = t.value;
-                responseBodyTruncated = t.truncated;
+            // The reply the test gets is untouched: everything here reads a clone,
+            // and a body known to be binary is not read at all. See
+            // ./harness/http-body.ts for why a blanket `.text()` was wrong.
+            const contentType = res.headers.get("content-type");
+            const contentLength = () => parseContentLength(res.headers.get("content-length"));
+            const textual = isTextualContentType(contentType);
+            if (textual === false) {
+                responseBody = omittedBody("binary", contentType, contentLength());
             }
-            catch {
-                // Binary or unreadable body — leave undefined.
+            else {
+                try {
+                    const cloned = res.clone();
+                    const text = await cloned.text();
+                    if (textual === undefined && looksBinary(text)) {
+                        // No content type (or a multipart one), and the bytes say this
+                        // was never text.
+                        responseBody = omittedBody("binary", contentType, contentLength());
+                    }
+                    else {
+                        const t = truncateUtf8(text);
+                        responseBody = t.value;
+                        responseBodyTruncated = t.truncated;
+                    }
+                }
+                catch {
+                    // The stream failed, or something had already consumed the body.
+                    responseBody = omittedBody("unreadable", contentType, contentLength());
+                }
             }
             const seq = recordHttp({
                 method,

package/dist/harness/http-body.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What to record for an HTTP response body.
+ *
+ * The fetch recorder used to call `Response.text()` on every reply. That is
+ * correct for text and wrong for bytes. `text()` decodes as UTF-8 and it
+ * does **not** throw on binary: each undecodable byte becomes U+FFFD and
+ * each NUL byte survives as U+0000. So a PNG was recorded as a string that
+ * can no longer rebuild the image, and that string was then stored, shipped
+ * to the CLI, and drawn in the dashboard as noise. The `catch` that was
+ * supposed to cover this case never ran.
+ *
+ * The response is never changed by any of this — the recorder reads a clone,
+ * and an image reply reaches the test exactly as the server sent it. Only
+ * the recorded description changes: `responseBody` carries an
+ * {@link OmittedBody} naming and measuring the reply, in place of the text
+ * it would otherwise hold.
+ *
+ * Pure, so the boundary cases are tested rather than inferred.
+ */
+import type { OmittedBody } from "../recorder.js";
+/**
+ * Is this content type text?
+ *
+ * `true` = record the body. `false` = record a placeholder and do not even
+ * read the body. `undefined` = the type does not say (it is absent, or it is
+ * `multipart/*`, which mixes both), so the caller must read the body and
+ * examine it with [`looksBinary`].
+ */
+export declare function isTextualContentType(contentType: string | null | undefined): boolean | undefined;
+/**
+ * Does decoded text hold bytes that were never text?
+ *
+ * Only U+0000 counts. It cannot appear in a body that a server meant as
+ * text, and it is also the one character Postgres refuses inside a `jsonb`
+ * string, so a payload that holds it fails the event insert.
+ *
+ * A count of U+FFFD would find more binaries, and it would also condemn a
+ * text reply that carries a few characters of broken encoding. This runs
+ * only where the content type gave no answer, so the cheap test is enough.
+ */
+export declare function looksBinary(text: string): boolean;
+/**
+ * What the body field carries when the body itself was not recorded.
+ *
+ * Separate fields, not a sentence: a reader can group by content type, sum
+ * the bytes, or count what was dropped. A rendered string like
+ * "[binary body: image/png, 70 bytes]" can do none of that, and every
+ * consumer would have to parse it back apart.
+ *
+ * It replaces the body rather than sitting beside it, so the two states
+ * cannot both be set and there is one key to read.
+ */
+export declare function omittedBody(reason: OmittedBody["reason"], contentType?: string | null, byteLength?: number | null): OmittedBody;
+/** `Content-Length` as a number, or `undefined` if it is absent or unusable. */
+export declare function parseContentLength(value: string | null | undefined): number | undefined;

package/dist/harness/http-body.js

@@ -0,0 +1,116 @@
+/**
+ * What to record for an HTTP response body.
+ *
+ * The fetch recorder used to call `Response.text()` on every reply. That is
+ * correct for text and wrong for bytes. `text()` decodes as UTF-8 and it
+ * does **not** throw on binary: each undecodable byte becomes U+FFFD and
+ * each NUL byte survives as U+0000. So a PNG was recorded as a string that
+ * can no longer rebuild the image, and that string was then stored, shipped
+ * to the CLI, and drawn in the dashboard as noise. The `catch` that was
+ * supposed to cover this case never ran.
+ *
+ * The response is never changed by any of this — the recorder reads a clone,
+ * and an image reply reaches the test exactly as the server sent it. Only
+ * the recorded description changes: `responseBody` carries an
+ * {@link OmittedBody} naming and measuring the reply, in place of the text
+ * it would otherwise hold.
+ *
+ * Pure, so the boundary cases are tested rather than inferred.
+ */
+/**
+ * Is this content type text?
+ *
+ * `true` = record the body. `false` = record a placeholder and do not even
+ * read the body. `undefined` = the type does not say (it is absent, or it is
+ * `multipart/*`, which mixes both), so the caller must read the body and
+ * examine it with [`looksBinary`].
+ */
+export function isTextualContentType(contentType) {
+    const essence = contentTypeEssence(contentType);
+    if (!essence)
+        return undefined;
+    // Structured-syntax suffixes come first: `image/svg+xml` is text, and its
+    // type alone would call it an image.
+    if (essence.endsWith("+json") || essence.endsWith("+xml") || essence.endsWith("+yaml")) {
+        return true;
+    }
+    if (essence.startsWith("text/"))
+        return true;
+    if (TEXTUAL_TYPES.has(essence))
+        return true;
+    // A multipart body holds text fields and file parts together. Only the
+    // bytes can say which one this is.
+    if (essence.startsWith("multipart/"))
+        return undefined;
+    return false;
+}
+/**
+ * Does decoded text hold bytes that were never text?
+ *
+ * Only U+0000 counts. It cannot appear in a body that a server meant as
+ * text, and it is also the one character Postgres refuses inside a `jsonb`
+ * string, so a payload that holds it fails the event insert.
+ *
+ * A count of U+FFFD would find more binaries, and it would also condemn a
+ * text reply that carries a few characters of broken encoding. This runs
+ * only where the content type gave no answer, so the cheap test is enough.
+ */
+export function looksBinary(text) {
+    return text.includes("\u0000");
+}
+/**
+ * What the body field carries when the body itself was not recorded.
+ *
+ * Separate fields, not a sentence: a reader can group by content type, sum
+ * the bytes, or count what was dropped. A rendered string like
+ * "[binary body: image/png, 70 bytes]" can do none of that, and every
+ * consumer would have to parse it back apart.
+ *
+ * It replaces the body rather than sitting beside it, so the two states
+ * cannot both be set and there is one key to read.
+ */
+export function omittedBody(reason, contentType, byteLength) {
+    const out = { reason };
+    const essence = contentTypeEssence(contentType);
+    if (essence)
+        out.contentType = essence;
+    if (typeof byteLength === "number" && Number.isFinite(byteLength) && byteLength >= 0) {
+        out.bytes = byteLength;
+    }
+    return out;
+}
+/** `Content-Length` as a number, or `undefined` if it is absent or unusable. */
+export function parseContentLength(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value.trim());
+    return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+}
+/** `image/png; charset=x` → `image/png`. Empty string → `undefined`. */
+function contentTypeEssence(contentType) {
+    const essence = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+    return essence ? essence : undefined;
+}
+/**
+ * Text types whose name does not say so. Everything else is caught by
+ * `text/` or by a `+json`/`+xml`/`+yaml` suffix.
+ */
+const TEXTUAL_TYPES = new Set([
+    "application/json",
+    "application/xml",
+    "application/yaml",
+    "application/x-yaml",
+    "application/javascript",
+    "application/x-javascript",
+    "application/ecmascript",
+    "application/graphql",
+    "application/graphql-response+json",
+    "application/x-ndjson",
+    "application/ndjson",
+    "application/jsonl",
+    "application/x-www-form-urlencoded",
+    "application/x-sh",
+    "application/sql",
+    "application/csp-report",
+    "application/problem+json",
+]);

package/dist/recorder.d.ts

@@ -171,6 +171,31 @@ export interface S3Event extends BaseEvent {
     /** Set if the op threw. */
     error?: string;
 }
+/**
+ * A body that was not captured, described in place of the body itself.
+ *
+ * This is the object form of `requestBody` / `responseBody`: the field holds
+ * the text when the body was text, and this when it was not. One key, and
+ * the two states cannot both be set. A reader tells them apart with
+ * `typeof body === "string"` (`jsonb_typeof(...)` in SQL).
+ *
+ * A body that is not text is described rather than transcribed. The recorder
+ * used to force one into a string with `Response.text()`, which decodes
+ * lossily and cannot be reversed — see `harness/http-body.ts`. The fields are
+ * separate values, not a sentence, so a reader can group by content type,
+ * sum the bytes, or find every reply that was dropped.
+ */
+export interface OmittedBody {
+    /** `binary` — the body was not text. `unreadable` — the stream failed, or
+     *  something had already consumed it. */
+    reason: "binary" | "unreadable";
+    /** The content type the server declared, without its parameters. Absent
+     *  when the server declared none. */
+    contentType?: string;
+    /** Size from `Content-Length`. Absent when the server declared none — the
+     *  body is never read to count it. */
+    bytes?: number;
+}
 export interface HttpEvent extends BaseEvent {
     kind: "http";
     method: string;
@@ -179,7 +204,10 @@ export interface HttpEvent extends BaseEvent {
     requestBody?: string;
     requestBodyTruncated?: boolean;
     status?: number;
-    responseBody?: string;
+    /** The response body as text, or an {@link OmittedBody} describing what
+     *  was there when it was not text. */
+    responseBody?: string | OmittedBody;
+    /** Only meaningful for a text body. */
     responseBodyTruncated?: boolean;
     durationMs: number;
     /** Set if the request threw (network error, abort, etc.). */
@@ -222,7 +250,10 @@ export interface KubeEvent extends BaseEvent {
     requestBody?: string;
     requestBodyTruncated?: boolean;
     status?: number;
-    responseBody?: string;
+    /** The response body as text, or an {@link OmittedBody} describing what
+     *  was there when it was not text. */
+    responseBody?: string | OmittedBody;
+    /** Only meaningful for a text body. */
     responseBodyTruncated?: boolean;
     durationMs: number;
     error?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.43.0",
+  "version": "0.45.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));
+}