@specific.dev/spectest 0.88.2 → 0.88.3

package/README.md

@@ -0,0 +1,68 @@
+# Spectest SDK
+
+Spectest runs your application and its dependencies in isolated environments.
+Tests can fork a parent's live state, including memory and files, then drive
+user flows with recorded assertions and graphical replays.
+
+Install the SDK in your project's `spectest/` directory:
+
+```sh
+mkdir -p spectest
+npm install --prefix spectest --save-exact @specific.dev/spectest@0.88.3
+```
+
+Install the [Spectest CLI](https://github.com/specific-dev/spectest/releases/latest)
+and run `spectest docs /installation` for project setup and authentication.
+`spectest docs` contains the complete offline authoring guide.
+
+## Electron apps
+
+Use `electron()` to build and run a real Linux Electron app under Xvfb, with
+its main process, preload, IPC and renderer. Spectest supplies the container
+setup; no custom Dockerfile is needed.
+
+Create `spectest/index.ts`:
+
+```ts
+import { defineEnvironment } from "@specific.dev/spectest";
+import { electron } from "@specific.dev/spectest/components";
+
+export const env = defineEnvironment({
+  name: "desktop-app",
+  services: { app: electron() },
+});
+
+export default env.project();
+```
+
+Create `spectest/tests/notes.ts`, using your app's labels:
+
+```ts
+import { expect } from "@specific.dev/spectest";
+import { env } from "../index";
+
+env.test("Save a note", async (ctx) => {
+  const app = await ctx.desktop(ctx.svc.app);
+  await app.getByRole("textbox", { name: "New note" }).fill("Hello desktop");
+  await app.getByRole("button", { name: "Add note", exact: true }).click();
+  await expect(app.getByRole("listitem")).toHaveText(["Hello desktop"]);
+});
+```
+
+Run `spectest test .` from the project root. The dashboard records desktop
+interactions and replays the app with window chrome derived from its Electron
+configuration. Child tests using `dependsOn` inherit the live app state,
+including unsaved input, in their own isolated environment.
+
+The app must declare Electron in `package.json`. Defaults are `npm ci` with a
+package lock (otherwise `npm install`), `npm run build`, and the package's
+`main` entry. Use `appDir`, `installCommand`, `buildCommand`, `entry`, and
+`nodeVersion` to customize the build. `env` supplies runtime variables;
+`dependsOn` waits for backend services in the same environment.
+
+Applications need Linux-compatible dependencies and binaries. Native OS dialogs
+and macOS-specific APIs are outside this basic support. Replays capture the
+renderer DOM from acquisition onward, not native OS surfaces.
+
+Run `spectest docs /components/electron` for the full configuration reference,
+backend setup, session behavior, and replay scope (CLI 0.2.124 or later).

package/dist/components/emulate/entry.mjs

@@ -0,0 +1,242 @@
+// 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 an
+//     explicit `iss` where the provider declares one. The Google emulator
+//     signs HS256 and serves an empty JWKS, so no client can verify its
+//     token. Providers whose issuer differs from their base URL can
+//     declare it explicitly. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.88.2",
+  "version": "0.88.3",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",