@specific.dev/spectest 0.43.0 → 0.45.0

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

package/src/daemon.ts

@@ -57,6 +57,12 @@ import {
   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,
@@ -120,6 +126,7 @@ import {
   stopRecording,
   truncateUtf8,
   type TestEvent,
+  type OmittedBody,
 } from "./recorder.js";
 import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
@@ -3800,16 +3807,33 @@ function installFetchWrapper(): () => void {
     const reqBody = describeRequestBody(input, init);
     try {
       const res = await original(input as RequestInfo, init);
-      let responseBody: string | undefined;
+      let responseBody: string | OmittedBody | undefined;
       let responseBodyTruncated: boolean | undefined;
-      try {
-        const cloned = res.clone();
-        const text = await cloned.text();
-        const t = truncateUtf8(text);
-        responseBody = t.value;
-        responseBodyTruncated = t.truncated;
-      } catch {
-        // Binary or unreadable body — leave undefined.
+      // 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());
+      } 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/src/harness/http-body.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isTextualContentType,
+  looksBinary,
+  omittedBody,
+  parseContentLength,
+} from "./http-body";
+
+describe("isTextualContentType", () => {
+  test("records text types", () => {
+    for (const ct of [
+      "text/plain",
+      "text/html; charset=utf-8",
+      "TEXT/CSS",
+      "application/json",
+      "application/problem+json",
+      "application/vnd.api+json",
+      "application/xml",
+      "application/x-ndjson",
+      "application/x-www-form-urlencoded",
+      "application/javascript",
+    ]) {
+      expect(isTextualContentType(ct)).toBe(true);
+    }
+  });
+
+  /** An SVG is an image by name and text by content. The suffix rule must
+   *  win, or the recorder stops keeping a body a user can read. */
+  test("keeps svg, which is text under an image type", () => {
+    expect(isTextualContentType("image/svg+xml")).toBe(true);
+  });
+
+  test("refuses binary types", () => {
+    for (const ct of [
+      "image/png",
+      "image/jpeg",
+      "application/octet-stream",
+      "application/pdf",
+      "application/zip",
+      "audio/mpeg",
+      "video/mp4",
+      "font/woff2",
+    ]) {
+      expect(isTextualContentType(ct)).toBe(false);
+    }
+  });
+
+  /** Both of these must read the body and look at it: absent says nothing,
+   *  and a multipart body holds text fields and file parts together. */
+  test("gives no answer without a usable type", () => {
+    expect(isTextualContentType(null)).toBeUndefined();
+    expect(isTextualContentType(undefined)).toBeUndefined();
+    expect(isTextualContentType("")).toBeUndefined();
+    expect(isTextualContentType("  ")).toBeUndefined();
+    expect(isTextualContentType("multipart/form-data; boundary=x")).toBeUndefined();
+  });
+});
+
+describe("looksBinary", () => {
+  test("passes ordinary text, including empty and unicode", () => {
+    expect(looksBinary("")).toBe(false);
+    expect(looksBinary('{"ok":true}')).toBe(false);
+    expect(looksBinary("héllo — ok ✓")).toBe(false);
+    // A lone replacement character is not enough. A text reply with broken
+    // encoding still belongs in the timeline.
+    expect(looksBinary("caf\ufffd")).toBe(false);
+  });
+
+  /** The exact shape that reached production: a PNG decoded by `.text()`. */
+  test("catches a decoded PNG", () => {
+    const png = "\ufffdPNG\r\n\u001a\n\u0000\u0000\u0000\rIHDR";
+    expect(looksBinary(png)).toBe(true);
+  });
+});
+
+describe("omittedBody", () => {
+  test("carries the type and the size as values", () => {
+    expect(omittedBody("binary", "image/png", 70)).toEqual({
+      reason: "binary",
+      contentType: "image/png",
+      bytes: 70,
+    });
+  });
+
+  test("drops the charset parameter", () => {
+    expect(omittedBody("binary", "image/png; charset=binary", 1).contentType).toBe("image/png");
+  });
+
+  /** A missing key is what "the server never said" looks like. A zero or an
+   *  empty string would read as a fact the recorder does not have. */
+  test("omits what it does not know", () => {
+    expect(omittedBody("binary", "application/pdf", undefined)).toEqual({
+      reason: "binary",
+      contentType: "application/pdf",
+    });
+    expect(omittedBody("binary", null, 12)).toEqual({ reason: "binary", bytes: 12 });
+    expect(omittedBody("unreadable", null, null)).toEqual({ reason: "unreadable" });
+  });
+
+  test("keeps a declared zero-byte body", () => {
+    expect(omittedBody("binary", "image/png", 0).bytes).toBe(0);
+  });
+});
+
+describe("parseContentLength", () => {
+  test("reads a length", () => {
+    expect(parseContentLength("95")).toBe(95);
+    expect(parseContentLength(" 95 ")).toBe(95);
+    expect(parseContentLength("0")).toBe(0);
+  });
+
+  test("refuses anything it cannot trust", () => {
+    for (const v of [null, undefined, "", "abc", "-1", "1.5", "9".repeat(30)]) {
+      expect(parseContentLength(v)).toBeUndefined();
+    }
+  });
+});

package/src/harness/http-body.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 function isTextualContentType(contentType: string | null | undefined): boolean | undefined {
+  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: string): boolean {
+  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: OmittedBody["reason"],
+  contentType?: string | null,
+  byteLength?: number | null,
+): OmittedBody {
+  const out: OmittedBody = { 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: string | null | undefined): number | undefined {
+  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: string | null | undefined): string | undefined {
+  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/src/recorder.ts

@@ -206,6 +206,32 @@ export interface S3Event extends BaseEvent {
   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;
@@ -214,7 +240,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.). */
@@ -259,7 +288,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;