@kedge/testing 0.0.0-stage → 0.9.0

package/src/http.ts

@@ -0,0 +1,435 @@
+// The scenario DSL over HTTP (docs/proposals/p0.8-cli-agent-kit.md §5.4): a
+// store's acceptance scenarios against a deployed preview, through its public
+// routes only, for Node. It isn't the workerd DSL behind one interface: that
+// one calls stores directly with a clock it controls, this one meets the real
+// relay and cron, so it polls. The method names match, so a scenario moves
+// between them with small edits.
+import { createHmac, randomUUID } from "node:crypto";
+import { INVARIANTS } from "./invariants";
+
+export interface OwnerCredentials {
+  email: string;
+  password: string;
+  /** The TOTP secret, base32, as the enrolment's otpauth URI gave it. */
+  totp: string;
+  /**
+   * The last TOTP step this factor accepted. A code from it, or an earlier one, is refused
+   * exactly as a wrong code is, and counts toward the lockout, so the next sign-in waits past it.
+   */
+  lastStep?: number;
+}
+
+export interface StoreCredentials {
+  url: string;
+  publishableKey: string;
+  secretKey: string;
+  owner?: OwnerCredentials;
+  /** An origin in the store's ADMIN_ORIGINS, for the browser-shaped ceremonies. */
+  adminOrigin?: string;
+  /** An origin the publishable key's storefront allows, for a customer's sign-in (a session-creating ceremony). */
+  storefrontOrigin?: string;
+  /** The preview's D1 database, for expectInvariants. */
+  databaseId?: string;
+  /** A strong Owner session `kedge preview` signed in once for all its scenario files; never cached. */
+  ownerSession?: string;
+}
+
+/** What `kedge preview` puts in a scenario's environment. */
+export function credentialsFromEnv(env: NodeJS.ProcessEnv = process.env): StoreCredentials {
+  const raw = env.KEDGE_PREVIEW_CREDENTIALS;
+  if (!raw) throw new Error("KEDGE_PREVIEW_CREDENTIALS isn't set: run scenarios through kedge preview");
+  return JSON.parse(raw) as StoreCredentials;
+}
+
+// ---- TOTP, as an authenticator app computes it (RFC 6238 over RFC 4226) ------------------------------
+export function base32Decode(text: string): Buffer {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  let bits = "";
+  for (const ch of text.replace(/=+$/, "").toUpperCase()) {
+    const i = alphabet.indexOf(ch);
+    if (i < 0) throw new Error("not base32");
+    bits += i.toString(2).padStart(5, "0");
+  }
+  const out: number[] = [];
+  for (let i = 0; i + 8 <= bits.length; i += 8) out.push(Number.parseInt(bits.slice(i, i + 8), 2));
+  return Buffer.from(out);
+}
+export function hotp(secret: Buffer, step: number): string {
+  const counter = Buffer.alloc(8);
+  counter.writeBigUInt64BE(BigInt(step));
+  const mac = createHmac("sha1", secret).update(counter).digest();
+  const o = (mac[19] as number) & 0xf;
+  return String((mac.readUInt32BE(o) & 0x7fffffff) % 1_000_000).padStart(6, "0");
+}
+export const totpStep = (at = Date.now()) => Math.floor(at / 30_000);
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** A refusal's code and message: the API answers `{ error: { code, message } }` (docs/06). */
+export function errorOf(body: unknown): { code: string; message: string } {
+  const e = (body as { error?: { code?: unknown; message?: unknown } })?.error;
+  return { code: String(e?.code ?? "UNKNOWN"), message: String(e?.message ?? "") };
+}
+
+export interface Answer<T = Record<string, unknown>> {
+  status: number;
+  body: T;
+  /** The request as sent, so retry() resends it with the same idempotency key. */
+  request: { method: string; path: string; headers: Record<string, string>; body?: unknown };
+}
+
+async function send<T>(f: typeof fetch, base: string, req: Answer["request"]): Promise<Answer<T>> {
+  const res = await f(new URL(req.path, base), {
+    method: req.method,
+    headers: { ...(req.body === undefined ? {} : { "content-type": "application/json" }), ...req.headers },
+    ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const text = await res.text();
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { raw: text.slice(0, 500) };
+  }
+  return { status: res.status, body: body as T, request: req };
+}
+
+/**
+ * The first Owner, from an invite token: accept with a password, enrol and
+ * confirm TOTP, then a strong sign-in. A TOTP code works once, so the
+ * sign-in waits past the confirm's step (as the remote runs learned): `lastStep`.
+ */
+export async function enrolOwner(
+  url: string,
+  invite: string,
+  email: string,
+  origin: string,
+  f: typeof fetch = fetch,
+  wait: (ms: number) => Promise<void> = sleep,
+): Promise<{ owner: OwnerCredentials; session: string }> {
+  const first = { origin, "x-kedge-csrf": "1", "x-kedge-session-mode": "bearer" };
+  const password = Buffer.from(crypto.getRandomValues(new Uint8Array(18))).toString("base64url");
+  const accept = await send<{ session_token?: string }>(f, url, {
+    method: "POST",
+    path: "/auth/admin/invites/accept",
+    headers: first,
+    body: {
+      token: invite,
+      password,
+      resume_nonce: Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64url"),
+    },
+  });
+  if (accept.status !== 200 || !accept.body.session_token) throw new Error(`invite accept answered ${accept.status}`);
+  const bearer = { authorization: `Bearer ${accept.body.session_token}` };
+  const enrol = await send<{ otpauth_uri?: string }>(f, url, {
+    method: "POST",
+    path: "/auth/admin/totp/enrol",
+    headers: bearer,
+    body: {},
+  });
+  const totp = new URL(enrol.body.otpauth_uri ?? "otpauth://x").searchParams.get("secret");
+  if (!totp) throw new Error(`TOTP enrolment answered ${enrol.status}`);
+  const confirmStep = totpStep();
+  const confirm = await send(f, url, {
+    method: "POST",
+    path: "/auth/admin/totp/confirm",
+    headers: bearer,
+    body: { code: hotp(base32Decode(totp), confirmStep) },
+  });
+  if (confirm.status !== 200) throw new Error(`TOTP confirm answered ${confirm.status}`);
+  const owner: OwnerCredentials = { email, password, totp, lastStep: confirmStep };
+  return { owner, session: await signInOwner(url, owner, origin, f, wait) };
+}
+
+const turns = new WeakMap<OwnerCredentials, Promise<unknown>>();
+
+/**
+ * A strong Owner session: password, then a TOTP code from a step not used before. Sign-ins for one
+ * Owner in a process take turns, each after the last one's step: run together they would all send
+ * one step's code, and a retry together would collide again (codex code r29).
+ */
+export function signInOwner(
+  url: string,
+  owner: OwnerCredentials,
+  origin: string,
+  f: typeof fetch = fetch,
+  wait: (ms: number) => Promise<void> = sleep,
+): Promise<string> {
+  const mine = (turns.get(owner) ?? Promise.resolve())
+    .catch(() => {})
+    .then(() => signInOnce(url, owner, origin, f, wait));
+  turns.set(owner, mine);
+  return mine;
+}
+
+async function signInOnce(
+  url: string,
+  owner: OwnerCredentials,
+  origin: string,
+  f: typeof fetch,
+  wait: (ms: number) => Promise<void>,
+): Promise<string> {
+  const first = { origin, "x-kedge-csrf": "1", "x-kedge-session-mode": "bearer" };
+  if (owner.lastStep !== undefined && totpStep() <= owner.lastStep)
+    await wait((owner.lastStep + 1) * 30_000 - Date.now() + 500);
+  const signIn = await send<{ challenge?: { token: string } }>(f, url, {
+    method: "POST",
+    path: "/auth/admin/sign-in",
+    headers: first,
+    body: { email: owner.email, password: owner.password },
+  });
+  if (!signIn.body.challenge?.token) throw new Error(`sign-in answered ${signIn.status}`);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const step = totpStep();
+    const strong = await send<{ session_token?: string }>(f, url, {
+      method: "POST",
+      path: "/auth/admin/totp/challenge",
+      headers: first,
+      body: { challenge_token: signIn.body.challenge.token, code: hotp(base32Decode(owner.totp), step) },
+    });
+    if (strong.status === 200 && strong.body.session_token) {
+      owner.lastStep = step;
+      return strong.body.session_token;
+    }
+    // A code already used this step, by a sign-in in another process, is refused as a wrong code is (the
+    // server doesn't say which): once, the next step's. A success clears the count, so collisions don't
+    // add up to a lockout (codex code r28). `kedge preview` signs in once for all its scenario files.
+    const code = errorOf(strong.body).code;
+    if (code === "AUTH_CEREMONY_STALE" || code === "UNAUTHORIZED") await wait(30_000 - (Date.now() % 30_000) + 500);
+    else throw new Error(`TOTP challenge answered ${strong.status}`);
+  }
+  throw new Error("TOTP challenge failed twice");
+}
+
+export interface CheckoutResult {
+  status: "placed" | "pending" | "refused";
+  order?: { id: string; total?: number };
+  error?: { code: string; message?: string };
+}
+
+export interface Line {
+  variantId: string;
+  quantity?: number;
+  custom?: Record<string, unknown>;
+}
+
+const owners = new Map<string, Promise<string>>();
+
+export function httpScenario(
+  c: StoreCredentials,
+  opts: { fetch?: typeof fetch; cloudflare?: { token: string; account: string } } = {},
+) {
+  const f = opts.fetch ?? fetch;
+  const origin = c.adminOrigin ?? "https://kedge-preview.invalid";
+  let ownerSession: Promise<string> | null = null;
+  const auth = (as: "store" | "secret" | "none" | { bearer: string }): Record<string, string> =>
+    as === "store"
+      ? { "x-kedge-key": c.publishableKey }
+      : as === "secret"
+        ? { authorization: `Bearer ${c.secretKey}` }
+        : as === "none"
+          ? {}
+          : { authorization: `Bearer ${as.bearer}` };
+
+  const s = {
+    /** One request; mutations carry a fresh idempotency key unless given one. */
+    async request<T = Record<string, unknown>>(
+      method: string,
+      path: string,
+      o: {
+        as?: "store" | "secret" | "none" | { bearer: string };
+        body?: unknown;
+        key?: string;
+        headers?: Record<string, string>;
+      } = {},
+    ): Promise<Answer<T>> {
+      const mutating = method !== "GET";
+      return send<T>(f, c.url, {
+        method,
+        path,
+        headers: {
+          ...auth(o.as ?? "secret"),
+          ...(mutating ? { "idempotency-key": o.key ?? `scn-${randomUUID()}` } : {}),
+          ...o.headers,
+        },
+        ...(o.body === undefined ? {} : { body: o.body }),
+      });
+    },
+    /** Resends the same request with the same idempotency key. */
+    retry<T>(a: Answer<T>): Promise<Answer<T>> {
+      return send<T>(f, c.url, a.request);
+    },
+    async product(p: { prices?: Record<string, number>; stock?: number; title?: string; kinds?: string[] } = {}) {
+      const handle = `scn-${randomUUID().slice(0, 8)}`;
+      const r = await s.request<{ id?: string; variantIds?: string[] }>("POST", "/admin/products", {
+        body: {
+          title: p.title ?? "Scenario product",
+          handle,
+          variants: [
+            {
+              sku: handle.toUpperCase(),
+              title: "One",
+              prices: p.prices ?? { USD: 1000 },
+              stock: { loc_default: p.stock ?? 10 },
+              ...(p.kinds ? { allowed_kinds: p.kinds } : {}),
+            },
+          ],
+        },
+      });
+      const variantId = r.body.variantIds?.[0];
+      if (r.status !== 200 || !variantId)
+        throw new Error(`creating a product answered ${r.status} ${JSON.stringify(r.body)}`);
+      return { productId: String(r.body.id), variantId, handle };
+    },
+    /** A shopper: a cart, lines, completion, and the staff placement that stands in for payment. */
+    buyer(b: { email?: string; customer?: string; currency?: string } = {}) {
+      const email = b.email ?? `buyer-${randomUUID().slice(0, 8)}@example.com`;
+      const headers = { ...auth("store"), ...(b.customer ? { authorization: `Bearer ${b.customer}` } : {}) };
+      return {
+        async checkout(
+          lines: readonly Line[],
+          o: { place?: boolean; expectedTotal?: number } = {},
+        ): Promise<CheckoutResult> {
+          const cart = await send<{ id: string; token: string }>(f, c.url, {
+            method: "POST",
+            path: "/store/carts",
+            headers,
+            body: { currency_code: b.currency ?? "USD", email },
+          });
+          if (cart.status !== 200) return { status: "refused", error: errorOf(cart.body) };
+          const h = { ...headers, "x-cart-token": cart.body.token };
+          for (const l of lines) {
+            const r = await send(f, c.url, {
+              method: "POST",
+              path: `/store/carts/${cart.body.id}/lines`,
+              headers: h,
+              body: { variant_id: l.variantId, quantity: l.quantity ?? 1, ...(l.custom ? { custom: l.custom } : {}) },
+            });
+            if (r.status !== 200) return { status: "refused", error: errorOf(r.body) };
+          }
+          // Money is `{ amount, currency_code }` in the API (docs/06); expected_total is the minor units the shopper saw.
+          const view = await send<{ totals?: { total?: { amount: number } } }>(f, c.url, {
+            method: "GET",
+            path: `/store/carts/${cart.body.id}`,
+            headers: h,
+          });
+          const total = o.expectedTotal ?? view.body.totals?.total?.amount ?? 0;
+          const done = await send<{ id?: string }>(f, c.url, {
+            method: "POST",
+            path: `/store/carts/${cart.body.id}/complete`,
+            headers: { ...h, "idempotency-key": `scn-${randomUUID()}` },
+            body: { expected_total: total },
+          });
+          if (done.status !== 200 || !done.body.id) return { status: "refused", error: errorOf(done.body) };
+          const order = { id: done.body.id, total };
+          if (o.place === false) return { status: "pending", order };
+          const placed = await s.request("POST", `/admin/orders/${done.body.id}/place`, { body: {} });
+          if (placed.status !== 200) return { status: "refused", order, error: errorOf(placed.body) };
+          return { status: "placed", order };
+        },
+      };
+    },
+    /** The Owner's strong session, signed in once per scenario. */
+    owner(): Promise<string> {
+      if (!c.owner) throw new Error("these credentials have no Owner");
+      // The runner's session when it gave one, so parallel scenario files spend no step; else one sign-in
+      // per Owner in this process, however many scenarios ask.
+      if (c.ownerSession) return Promise.resolve(c.ownerSession);
+      const key = `${c.url} ${c.owner.email}`;
+      ownerSession ??= owners.get(key) ?? signInOwner(c.url, c.owner, origin, f);
+      owners.set(key, ownerSession);
+      return ownerSession;
+    },
+    /** The preview's capture log: calls, webhooks, and sign-in emails in clear for a strong Owner. */
+    async captures(port?: string): Promise<{ kind: string; port: string; envelope: Record<string, unknown> }[]> {
+      const r = await s.request<{ captures?: { kind: string; port: string; envelope: Record<string, unknown> }[] }>(
+        "GET",
+        `/admin/preview/captures${port ? `?port=${encodeURIComponent(port)}` : ""}`,
+        { as: { bearer: await s.owner() } },
+      );
+      if (r.status !== 200) throw new Error(`reading captures answered ${r.status}`);
+      return r.body.captures ?? [];
+    },
+    /** A customer session, signed in with the code the preview captured. */
+    async customer(email: string): Promise<string> {
+      // Creating a session takes CSRF and an allowed Origin even in bearer mode, so a foreign page can't sign someone in.
+      const first = { origin: c.storefrontOrigin ?? origin, "x-kedge-csrf": "1" };
+      const asked = await s.request("POST", "/auth/store/code", { as: "store", body: { email }, headers: first });
+      if (asked.status !== 200) throw new Error(`asking a code answered ${asked.status}`);
+      const code = await s.until(async () => {
+        const found = (await s.captures("auth-email")).filter((x) => x.envelope.to === email).at(-1);
+        return /Your code is (\S+)\./.exec(String(found?.envelope.text ?? ""))?.[1];
+      });
+      const v = await s.request<{ session_token?: string }>("POST", "/auth/store/verify", {
+        as: "store",
+        body: { email, code },
+        headers: { ...first, "x-kedge-session-mode": "bearer" },
+      });
+      if (!v.body.session_token) throw new Error(`verifying the code answered ${v.status}`);
+      return v.body.session_token;
+    },
+    /** Polls until fn returns something other than undefined, null or false: a preview's relay and cron are real. */
+    async until<T>(
+      fn: () => Promise<T | undefined | null | false>,
+      o: { ms?: number; every?: number } = {},
+    ): Promise<T> {
+      const end = Date.now() + (o.ms ?? 120_000);
+      for (;;) {
+        const v = await fn();
+        if (v !== undefined && v !== null && v !== false) return v;
+        if (Date.now() > end) throw new Error("until: timed out");
+        await sleep(o.every ?? 2_000);
+      }
+    },
+    expectExactlyOne(results: readonly CheckoutResult[], status: CheckoutResult["status"]): CheckoutResult {
+      const hits = results.filter((r) => r.status === status);
+      if (hits.length !== 1)
+        throw new Error(`expected exactly one ${status}, got ${hits.length}: ${JSON.stringify(results)}`);
+      return hits[0] as CheckoutResult;
+    },
+    expectError(results: readonly CheckoutResult[], code: string): CheckoutResult {
+      const hit = results.find((r) => r.error?.code === code);
+      if (!hit) throw new Error(`expected an error ${code}: ${JSON.stringify(results)}`);
+      return hit;
+    },
+    /**
+     * Every invariant, through D1's query API with the runner's own token. The
+     * SQL is the workerd suite's, read-only. Without a token it fails rather
+     * than passing silently.
+     */
+    async expectInvariants(): Promise<void> {
+      const cf =
+        opts.cloudflare ??
+        (process.env.CLOUDFLARE_API_TOKEN && process.env.CLOUDFLARE_ACCOUNT_ID
+          ? { token: process.env.CLOUDFLARE_API_TOKEN, account: process.env.CLOUDFLARE_ACCOUNT_ID }
+          : null);
+      if (!cf || !c.databaseId)
+        throw new Error(
+          "expectInvariants needs CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and the preview's database id",
+        );
+      const failures: string[] = [];
+      for (const check of INVARIANTS) {
+        const r = await f(
+          `https://api.cloudflare.com/client/v4/accounts/${cf.account}/d1/database/${c.databaseId}/query`,
+          {
+            method: "POST",
+            headers: { authorization: `Bearer ${cf.token}`, "content-type": "application/json" },
+            body: JSON.stringify({ sql: check.sql }),
+          },
+        );
+        const j = (await r.json()) as { success?: boolean; result?: { results?: unknown[] }[] };
+        if (!j.success) throw new Error(`invariant ${check.name}: the query failed (${r.status})`);
+        const rows = j.result?.[0]?.results ?? [];
+        if (rows.length)
+          failures.push(`${check.name}: ${check.rule} (${rows.length} rows, e.g. ${JSON.stringify(rows[0])})`);
+      }
+      if (failures.length) throw new Error(`invariants broken:\n  ${failures.join("\n  ")}`);
+    },
+  };
+  return s;
+}
+
+/** Runs each at once: the concurrency helper for last-unit races. */
+export function concurrently<T>(...fns: (() => Promise<T>)[]): Promise<T[]> {
+  return Promise.all(fns.map((fn) => fn()));
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { type TestRuntime, testRuntime } from "@kedge/core";
+// Plugin tests write their setup through core's marker (p0.5 §7.1) without depending on @kedge/db.
+export { runMarked } from "@kedge/db";
+export {
+  type BudgetViolation,
+  CHECKOUT_BUDGETS,
+  type CheckoutShape,
+  EXPIRY_BUDGETS,
+  type Measured,
+  measureRows,
+  overBudget,
+  PLACEMENT_BUDGETS,
+  RELAY_BUDGETS,
+  type StatementBudget,
+  TIMER_BUDGETS,
+} from "./budgets";
+export { checkInvariants, INVARIANTS, type Violation } from "./invariants";
+export { type CapturedCall, type Fault, ProviderDouble, testEmailPort, testPaymentPort } from "./ports";
+export { countRequests, type RequestCounter } from "./requests";
+export {
+  type CheckoutOutcome,
+  cartLines,
+  concurrently,
+  type RelayPass,
+  type Scenario,
+  type ScenarioLine,
+  type ScenarioOptions,
+  scenario,
+} from "./scenario";
+export { describeKedgeInvariants } from "./vitest";