@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/testing/index.ts

@@ -0,0 +1,337 @@
+/**
+ * `@asturiu/v0-sdk/testing` (ADR-074 §5): an in-memory stand-in for the Tenant API, so a Tenant's CI can run its
+ * start-up code and `asturiu-v0-tenant` without a key the Engine knows, a network or an Engine. Node only.
+ *
+ * It answers every route of `TENANT_API_ROUTES` the way the Tenant API does: a signed assertion on every call (checked
+ * against the stand-in's key when one is given), a `404` for a route the key's scopes do not reach, problem documents
+ * for refusals. It holds its state in memory and records each call. It is a stand-in, not the Engine: it plans no
+ * Definition change and checks no Definition rule.
+ */
+import { createHash, createPrivateKey, createPublicKey, verify } from "node:crypto";
+import type { RepositoryBranding, RepositoryPortal, TenantSource } from "../branding.js";
+import type { ChangesetStatus, FeedbackReport, TenantChangeset } from "../changesets.js";
+import { type DefinitionStatus, type DefinitionSubmitResult, type EngineInfo, TENANT_API_ROUTES, TENANT_ASSERTION_AUDIENCE, TENANT_ASSERTION_MAX_SECONDS, type TenantKeyRecord, type TenantKeyScope, TENANT_KEY_SCOPES, definitionSetHash, formatTenantKey, fromB64url, generateTenantKeyPair, keyReachesRoute, matchTenantApiRoute, parseTenantKey } from "../definition-set.js";
+import type { PortalPage, PortalSwitch } from "../portal-options.js";
+import type { TagView } from "../tags.js";
+import type { AnnouncementItem, AnyStatus, PostView, TicketView } from "../tickets.js";
+import { SDK_VERSION } from "../version.js";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface StandInOptions {
+  /** The Tenant key whose assertions it takes; without one, any well-formed assertion passes. */
+  key?: string;
+  /** What the key reaches (default: every scope). */
+  scopes?: TenantKeyScope[];
+  /** Routes it answers with 404, as an older Engine does: `"GET /tenant/v0/key"`. */
+  missing?: string[];
+  /** Answer every call with this status (`401`: the key was refused). */
+  refuse?: number;
+  /** Throw as `fetch` does when nothing answers (`ECONNREFUSED`), or another network code. */
+  down?: boolean | string;
+  engine?: Partial<EngineInfo>;
+  definitions?: Partial<DefinitionStatus> & {
+    /** How it answers a submitted set other than the live one: applied at once (default) or waiting for approval. */
+    submit?: "apply" | "wait" | ((set: Record<string, unknown>, hash: string) => DefinitionSubmitResult);
+  };
+  branding?: { source?: TenantSource; branding?: RepositoryBranding };
+  portal?: { source?: TenantSource; portal?: Record<string, unknown>; redirected?: PortalPage[] };
+  changesets?: TenantChangeset[];
+  /** Documents of the Engine site, by their whole address: what `changesets pull` fetches. */
+  documents?: Record<string, string>;
+  feedback?: TicketView[];
+  tickets?: TicketView[];
+  announcements?: { items?: TicketView[]; platform?: AnnouncementItem[] };
+  tags?: TagView[];
+  keyRecord?: Partial<TenantKeyRecord>;
+  now?: () => number;
+}
+
+export interface StandInCall {
+  method: string;
+  path: string;
+  query: string;
+  body: unknown;
+  status: number;
+  /** The SDK version the caller named in its User-Agent, as the Tenant API forwards it. */
+  sdk_version: string | null;
+}
+
+const ALL_PAGES: PortalPage[] = ["profile", "security", "plan", "privacy", "recovery", "support"];
+const ALL_SWITCHES: PortalSwitch[] = ["account_link", "open_app", "back_link", "language_menu", "appearance"];
+
+/** A Tenant key for tests: made here, registered with no Engine, so a real Tenant API refuses it. */
+export async function testTenantKey(slug = "acme", kid = "0123456789abcdef"): Promise<string> {
+  return formatTenantKey({ slug, kid, pkcs8: (await generateTenantKeyPair()).privatePkcs8 });
+}
+
+const problem = (status: number, type: string, detail: string) => new Response(JSON.stringify({ type, title: type.replace(/-/g, " "), status, detail }), { status, headers: { "content-type": "application/problem+json" } });
+const ok = (body: unknown, status = 200, headers: Record<string, string> = {}) => new Response(body === undefined ? null : JSON.stringify(body), { status, headers: { "content-type": "application/json", ...headers } });
+const b64 = (s: string) => JSON.parse(Buffer.from(s, "base64url").toString("utf8")) as Record<string, any>;
+
+function post(at: string, body: string, mine: boolean, label: string): PostView {
+  return { id: `pst-${createHash("sha256").update(at + body).digest("hex").slice(0, 12)}`, at, side: mine ? "requester" : "handling", visibility: "all", author: { label, mine }, body, refs: [] };
+}
+
+function ticket(o: { arid: string; subject: string; body: string; status?: AnyStatus; primary?: TicketView["primary"]; direction?: TicketView["direction"]; at: string; with_label?: string }): TicketView {
+  return {
+    arid: o.arid,
+    scope: "tenant",
+    direction: o.direction ?? "tenant_platform",
+    primary: o.primary ?? "request",
+    secondary: null,
+    type_label: o.primary === "announcement" ? "Announcement" : "Request",
+    subject: o.subject,
+    status: o.status ?? "new",
+    priority: "normal",
+    archived: false,
+    created_at: o.at,
+    updated_at: o.at,
+    side: "requester",
+    unread: false,
+    with_label: o.with_label ?? "Asturiu",
+    parties: [],
+    posts: o.body ? [post(o.at, o.body, true, "Your servers")] : [],
+    links: [],
+    refs: [],
+    audience: null,
+    hold_until: null,
+    closed_at: null,
+    can: { post: true, note: false, triage: false, statuses: ["canceled", "resolved"], reopen: false },
+  };
+}
+
+/** The in-memory Tenant API. `fetch` is what the SDK's calls and `asturiu-v0-tenant` take as their `fetch`. */
+export function createTenantApiStandIn(o: StandInOptions = {}) {
+  const now = o.now ?? (() => Date.now());
+  const iso = () => new Date(now()).toISOString();
+  const scopes = o.scopes ?? [...TENANT_KEY_SCOPES];
+  let counter = 0;
+  const id = (type: string) => `ARID:0:global:${type}:01STANDIN${String(++counter).padStart(17, "0")}`;
+  const seenJti = new Set<string>();
+  const publicKey = o.key ? createPublicKey(createPrivateKey({ key: Buffer.from(fromB64url(parseTenantKey(o.key).pkcs8)), format: "der", type: "pkcs8" })) : null;
+
+  const state = {
+    engine: { version: "0.1.0", released_at: "2026-11-09", latest_changeset: 0, site: { docs: "https://engine.example/docs/tenants", changesets: "https://engine.example/changesets" }, sdk: { built_with: SDK_VERSION, minimum: SDK_VERSION }, ...o.engine } as EngineInfo,
+    definitions: { revision: 1, hash: null, source: "repository", auto_apply: "safe", waiting: [], ...o.definitions } as DefinitionStatus,
+    branding: { source: o.branding?.source ?? "repository", branding: o.branding?.branding ?? {} },
+    portal: { source: o.portal?.source ?? "repository", portal: { ...Object.fromEntries(ALL_SWITCHES.map((s) => [s, true])), pages: Object.fromEntries(ALL_PAGES.map((p) => [p, { mode: "portal" }])), ...o.portal?.portal } as Record<string, unknown>, redirected: o.portal?.redirected ?? [] },
+    changesets: (o.changesets ?? []).map((c) => ({ ...c })),
+    feedback: (o.feedback ?? []).map((t) => structuredClone(t)),
+    tickets: (o.tickets ?? []).map((t) => structuredClone(t)),
+    announcements: (o.announcements?.items ?? []).map((t) => structuredClone(t)),
+    platform: o.announcements?.platform ?? [],
+    tags: (o.tags ?? []).map((t) => ({ ...t })),
+    customerTags: new Map<string, Set<string>>(),
+    tiers: { source: "repository" as TenantSource, tiers: {}, default_tier: null as string | null },
+    reports: [] as FeedbackReport[],
+  };
+  const calls: StandInCall[] = [];
+  const submit = o.definitions?.submit ?? "apply";
+
+  /** The assertion, as the Tenant API and the Operations API check it; null when it passes. */
+  function refuseAssertion(headers: Headers, method: string, path: string, body: string): Response | null {
+    const m = /^Asturiu-Assertion ([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$/.exec(headers.get("authorization") ?? "");
+    if (!m) return problem(401, "unauthorized", "a signed assertion is required");
+    let header: Record<string, any>;
+    let claims: Record<string, any>;
+    try {
+      header = b64(m[1]);
+      claims = b64(m[2]);
+    } catch {
+      return problem(401, "unauthorized", "a signed assertion is required");
+    }
+    if (header.alg !== "EdDSA" || typeof header.kid !== "string") return problem(401, "unauthorized", "invalid assertion");
+    if (o.key) {
+      const k = parseTenantKey(o.key);
+      // An unknown key or Tenant is nothing to the Engine: 404, as the Operations API answers.
+      if (header.kid !== k.kid || claims.iss !== k.slug) return problem(404, "not-found", "Not Found");
+      if (!verify(null, Buffer.from(`${m[1]}.${m[2]}`), publicKey!, Buffer.from(m[3], "base64url"))) return problem(401, "unauthorized", "invalid signature");
+    }
+    const t = Math.floor(now() / 1000);
+    if (claims.aud !== TENANT_ASSERTION_AUDIENCE) return problem(401, "unauthorized", "wrong audience");
+    if (claims.htm !== method || claims.htu !== path) return problem(401, "unauthorized", "the assertion names another request");
+    if (typeof claims.exp !== "number" || typeof claims.iat !== "number" || claims.exp < t || claims.exp - claims.iat > TENANT_ASSERTION_MAX_SECONDS) return problem(401, "unauthorized", "assertion expired");
+    if (claims.bdh !== createHash("sha256").update(body).digest("base64url")) return problem(401, "unauthorized", "the body is not the one signed");
+    if (seenJti.has(claims.jti)) return problem(401, "unauthorized", "assertion already used");
+    seenJti.add(claims.jti);
+    return null;
+  }
+
+  async function route(method: string, path: string, query: URLSearchParams, body: any): Promise<Response> {
+    const p = path.split("/").slice(3).map(decodeURIComponent); // after /tenant/v0
+    const [a, b, c, d] = p;
+    if (a === "engine") return ok(state.engine);
+    if (a === "key") {
+      const k = o.key ? parseTenantKey(o.key) : { slug: "acme", kid: "0123456789abcdef" };
+      return ok({ id: k.kid, name: "Test key", tenant: k.slug, scopes, created_at: "2026-11-01T00:00:00.000Z", expires_at: new Date(now() + 120 * 86_400_000).toISOString(), ...o.keyRecord });
+    }
+    if (a === "definitions" && b === "status") return ok(state.definitions);
+    if (a === "definitions" && method === "POST") {
+      if (state.definitions.source !== "repository") return problem(409, "definitions-not-repository", "the Definitions are edited in the Admin UI");
+      const hash = await definitionSetHash(body ?? {});
+      if (hash === state.definitions.hash) return ok({ status: "unchanged", hash, revision: state.definitions.revision });
+      if (typeof submit === "function") return ok(submit(body, hash));
+      if (submit === "wait") {
+        const plan_id = `plan-${hash.slice(0, 8)}`;
+        if (!state.definitions.waiting.some((w) => w.hash === hash)) state.definitions.waiting.push({ plan_id, hash, created_at: iso() });
+        return ok({ status: "waiting", hash, revision: state.definitions.revision, plan_id, summary: { changes: 1, unsafe: 1 }, changes: [{ address: "wallet:example", kind: "wallet", change: "label", effect: "repins", safe: false }], approve_url: `https://admin.example/tenants/acme?tab=definitions&plan=${plan_id}` });
+      }
+      state.definitions = { ...state.definitions, revision: state.definitions.revision + 1, hash, waiting: [] };
+      return ok({ status: "applied", hash, revision: state.definitions.revision, summary: { changes: 1, unsafe: 0 }, changes: [{ address: "wallet:example", kind: "wallet", change: "registered", effect: "creates", safe: true }] });
+    }
+    for (const tab of ["branding", "portal"] as const) {
+      if (a !== tab) continue;
+      if (method === "GET") return ok(tab === "branding" ? state.branding : state.portal);
+      if (state[tab].source !== "repository") return problem(409, `${tab}-not-repository`, `the ${tab === "branding" ? "Branding" : "Portal"} tab is edited in the Admin UI`);
+      if (tab === "branding") {
+        const same = JSON.stringify(state.branding.branding) === JSON.stringify(body);
+        state.branding.branding = body;
+        return ok({ status: same ? "unchanged" : "applied" });
+      }
+      const next: Record<string, unknown> = { ...Object.fromEntries(ALL_SWITCHES.map((s) => [s, (body as RepositoryPortal)[s] ?? true])), pages: { ...(state.portal.portal.pages as object), ...((body as RepositoryPortal).pages ?? {}) } };
+      const same = JSON.stringify(next) === JSON.stringify(state.portal.portal);
+      state.portal.portal = next;
+      const kept = state.portal.redirected.filter((pg) => (body as RepositoryPortal).pages?.[pg]);
+      return ok({ status: same ? "unchanged" : "applied", ...(kept.length ? { kept } : {}) });
+    }
+    if (a === "tiers") {
+      if (method === "GET") return ok(state.tiers);
+      state.tiers = { ...state.tiers, ...body };
+      return ok({ status: "applied" });
+    }
+    if (a === "subscription") return ok({ arid: null, tier: "starter", label: "Starter", state: "active", frozen: false, renews: true, period_end: null, trial_end: null, allowance: { active_customers: 100, storage: 1_000_000_000 }, used: { active_customers: 3, storage: 0 }, overage: null, closing_at: null, features: null });
+    if (a === "customers" && c === "entitlement") return ok({ customer: b, tier: body?.tier, billing: { status: body?.status ?? "active" } });
+    if (a === "customers" && c === "entitlements") return ok({ customer: b, tier: null, features: {} });
+    if (a === "customers" && c === "tags") {
+      const tag = state.tags.find((t) => t.name === d);
+      if (!tag) return problem(404, "not-found", "Not Found");
+      const set = state.customerTags.get(b) ?? new Set<string>();
+      state.customerTags.set(b, set);
+      if (method === "PUT") {
+        const added = !set.has(d);
+        set.add(d);
+        return ok({ customer: b, tag: d, added });
+      }
+      const removed = set.delete(d);
+      return ok({ customer: b, tag: d, removed });
+    }
+    if (a === "tags" && !b) return ok({ items: state.tags });
+    if (a === "tags" && b) {
+      const existing = state.tags.find((t) => t.name === b);
+      if (existing) {
+        Object.assign(existing, body, { updated_at: iso() });
+        return ok({ ...existing, created: false });
+      }
+      const made: TagView = { id: `tag-${b}`, name: b, shown: `acme:${b}`, scope: "tenant", subject: "customer", visibility: body?.visibility ?? "staff", description: body?.description ?? "", colour: body?.colour ?? "slate", rules: body?.rules ?? [], effects: body?.effects ?? [], system: false, subjects: 0, created_at: iso(), updated_at: iso() };
+      state.tags.push(made);
+      return ok({ ...made, created: true }, 201);
+    }
+    if (a === "changesets" && !b) {
+      const since = Number(query.get("since") ?? 0) || 0;
+      return ok({ latest: state.engine.latest_changeset || (state.changesets.at(-1)?.number ?? 0), changesets: state.changesets.filter((x) => x.number > since) });
+    }
+    if (a === "changesets" && c === "status") {
+      const cs = state.changesets.find((x) => x.number === Number(b));
+      if (!cs || !cs.ticket) return problem(404, "not-found", "Not Found");
+      if (body?.status === "canceled" && !body.reason) return problem(422, "unprocessable", "a canceled changeset needs a reason");
+      cs.status = body?.status as ChangesetStatus;
+      return ok(cs);
+    }
+    if (a === "feedback" && !b && method === "POST") {
+      state.reports.push(body);
+      const arid = id("tkt");
+      state.feedback.push(ticket({ arid, subject: body.summary, body: body.detail, primary: "feedback", at: iso() }));
+      return ok({ id: arid, received_at: iso() }, 201);
+    }
+    if (a === "feedback" && !b) return ok({ items: state.feedback, next: state.feedback.length ? iso() : null });
+    if (a === "feedback" && c === "posts") {
+      const t = state.feedback.find((x) => x.arid === b);
+      if (!t) return problem(404, "not-found", "Not Found");
+      t.posts.push(post(iso(), body.body, true, "Your servers"));
+      return ok(t, 201);
+    }
+    if (a === "tickets" && !b && method === "GET") {
+      const status = query.get("status");
+      return ok({ items: state.tickets.filter((t) => !status || t.status === status).map(({ parties: _p, posts: _q, links: _l, refs: _r, audience: _a, hold_until: _h, closed_at: _c, can: _k, ...summary }) => summary) });
+    }
+    if (a === "tickets" && !b && method === "POST") {
+      if (body?.to !== "platform" && !/^ARID:0:[a-z0-9-]+:cst:/.test(body?.to ?? "")) return problem(422, "unprocessable", "to is platform or a Customer of this Tenant");
+      const t = ticket({ arid: id("tkt"), subject: body.subject, body: body.body, direction: body.to === "platform" ? "tenant_platform" : "tenant_customer", at: iso(), with_label: body.to === "platform" ? "Asturiu" : (body.to_name ?? "A Customer") });
+      state.tickets.push(t);
+      return ok(t, 201);
+    }
+    for (const [family, list] of [["tickets", state.tickets], ["announcements", state.announcements]] as const) {
+      if (a !== family || !b) continue;
+      const t = list.find((x) => x.arid === b);
+      if (!t) return problem(404, "not-found", "Not Found");
+      if (method === "GET") return ok(t);
+      if (method === "PATCH") {
+        if (body?.status) t.status = body.status;
+        if (body?.priority) t.priority = body.priority;
+        if (body?.archived !== undefined) t.archived = body.archived;
+        t.updated_at = iso();
+        return ok(t);
+      }
+      if (method === "POST" && c === "posts") {
+        t.posts.push(post(iso(), body.body, true, "Your servers"));
+        return ok(t, 201);
+      }
+      if (method === "DELETE") {
+        if (t.status !== "draft") return problem(409, "conflict", "only a draft is deleted; withdraw a published announcement");
+        state.announcements.splice(state.announcements.indexOf(t), 1);
+        return new Response(null, { status: 204 });
+      }
+    }
+    if (a === "announcements" && method === "GET") return ok({ items: state.announcements, platform: state.platform });
+    if (a === "announcements" && method === "POST") {
+      const t = ticket({ arid: id("tkt"), subject: body.subject, body: body.body ?? "", status: "draft", primary: "announcement", direction: "tenant_customers", at: iso(), with_label: "Customers" });
+      state.announcements.push(t);
+      return ok(t, 201);
+    }
+    return problem(404, "not-found", "Not Found");
+  }
+
+  async function handle(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const body = request.method === "GET" || request.method === "HEAD" ? "" : await request.text();
+    const record = (status: number) => calls.push({ method: request.method, path: url.pathname, query: url.search, body: body ? safeJson(body) : undefined, status, sdk_version: /(?:^|\s)asturiu-v0-sdk\/(\S+)/.exec(request.headers.get("user-agent") ?? "")?.[1] ?? null });
+    // The Engine site's documents.
+    if (!url.pathname.startsWith("/tenant/v0/")) {
+      const doc = o.documents?.[url.href];
+      record(doc === undefined ? 404 : 200);
+      return doc === undefined ? new Response("Not Found", { status: 404 }) : new Response(doc, { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" } });
+    }
+    const respond = (r: Response) => {
+      record(r.status);
+      return r;
+    };
+    if (o.refuse) return respond(problem(o.refuse, o.refuse === 401 ? "unauthorized" : "refused", o.refuse === 401 ? "the key was refused" : "refused"));
+    const m = matchTenantApiRoute(request.method, url.pathname);
+    if (!m || o.missing?.includes(`${m.route.method} ${m.route.path}`)) return respond(problem(404, "not-found", "Not Found"));
+    const refused = refuseAssertion(request.headers, request.method, url.pathname, body);
+    if (refused) return respond(refused);
+    if (!keyReachesRoute(scopes, m.route)) return respond(problem(404, "not-found", "Not Found"));
+    return respond(await route(request.method, url.pathname, url.searchParams, body ? safeJson(body) : undefined));
+  }
+
+  const fetch: FetchLike = async (input, init) => {
+    if (o.down) {
+      const code = typeof o.down === "string" ? o.down : "ECONNREFUSED";
+      throw Object.assign(new TypeError("fetch failed"), { cause: Object.assign(new Error(code), { code }) });
+    }
+    return handle(new Request(input, init));
+  };
+
+  return { fetch, handle, state, calls, routes: TENANT_API_ROUTES };
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export type TenantApiStandIn = ReturnType<typeof createTenantApiStandIn>;