@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/apps/storefront/src/lib/shared/invitePreflight.ts

@@ -0,0 +1,123 @@
+/**
+ * Invite preflight — block a developer invite when the target store's repo isn't
+ * provisioned on THIS environment, so a broken connection surfaces to the INVITER
+ * at invite time instead of dead-ending later in the invitee's terminal on
+ * "Repo <owner>-main is not provisioned".
+ *
+ * The check is the MCP's credential-free resource-registry read — the SAME read
+ * `tenant_checkout` gates on — reached the SAME way the app-binding writer +
+ * cli-signin-code seam reach the MCP:
+ *   GET {origin(MCP_APP_BINDING_URL)}/internal/preview-status?tenant=<appDomain>&app=storefront&tag=main
+ *     header  x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>
+ *     → 200 { owner, app, repo, provisioned, previewReleased } | 400 | 502
+ * Contract source of truth: tot-mcp src/server/preview-status-routes.ts. We gate on
+ * `provisioned` — the exact precondition `tenant_checkout` needs. We do NOT gate on
+ * `previewReleased`: it is (provisioned && preview-approved), which is FALSE for every
+ * store that hasn't shipped a preview yet — gating on it would block invites for
+ * provisioned-but-unreleased stores whose checkout would actually succeed.
+ *
+ * FAIL-OPEN: we BLOCK only on a DEFINITIVE not-ready answer (a clean 200 with
+ * previewReleased:false). An unconfigured seam (no URL/secret), a non-200, a
+ * transport/parse fault, or a timeout is INCONCLUSIVE → allow (log a warning),
+ * mirroring recordDeveloperAppBinding's "skipped when not-configured" stance — we
+ * never break invites just because the MCP is briefly unreachable.
+ */
+import { readEnv } from "@/lib/env";
+
+/** How long we'll wait on the preview-status read before failing open. */
+const PREFLIGHT_TIMEOUT_MS = 4000;
+
+/** GET transport seam (injectable for tests) — mirrors HttpTransport but read-only. */
+export interface PreflightTransport {
+  get(
+    url: string,
+    headers: Record<string, string>,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+/** The real transport: a timeout-bounded GET. */
+export class FetchPreflightTransport implements PreflightTransport {
+  async get(url: string, headers: Record<string, string>) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), PREFLIGHT_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: ctrl.signal });
+      return { status: res.status, json: () => res.json() };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** BLOCK carries the inviter-facing message; ALLOW carries a reason (for logging). */
+export type PreflightDecision =
+  | { block: true; reason: "not-provisioned"; message: string }
+  | { block: false; reason: string };
+
+/** The inviter-facing block message, naming the store. */
+function blockMessage(tenant: string): string {
+  return (
+    `${tenant} isn't set up on this environment yet — its store repo isn't ` +
+    `provisioned. Finish provisioning that store before inviting a developer to it.`
+  );
+}
+
+/**
+ * Preflight `tenant` (the target appDomain). Returns a BLOCK only on a definitive
+ * not-provisioned answer; every inconclusive condition allows (fail-open). Never
+ * throws.
+ */
+export async function checkStorePreviewReady(
+  tenant: string,
+  deps: { transport?: PreflightTransport } = {},
+): Promise<PreflightDecision> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret) {
+    // Seam not configured (the MCP route isn't even mounted without the secret) —
+    // inconclusive, so allow rather than break every invite.
+    return { block: false, reason: "not-configured" };
+  }
+
+  let endpoint: string;
+  try {
+    const origin = new URL(bindingUrl).origin;
+    const q = new URLSearchParams({ tenant: tenant.toLowerCase(), app: "storefront", tag: "main" });
+    // Canonical, namespace-neutral path (the read is generic, not dev-role-scoped).
+    endpoint = `${origin}/internal/preview-status?${q.toString()}`;
+  } catch {
+    return { block: false, reason: "bad-mcp-url" };
+  }
+
+  const transport = deps.transport ?? new FetchPreflightTransport();
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.get(endpoint, { "x-mcp-service-secret": secret });
+  } catch (cause) {
+    return {
+      block: false,
+      reason: "preflight request failed: " + (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+
+  // Only a clean 200 is a conclusive answer; anything else is inconclusive → allow.
+  if (res.status < 200 || res.status >= 300) {
+    return { block: false, reason: `preflight returned status ${res.status}` };
+  }
+  let payload: { provisioned?: unknown; previewReleased?: unknown };
+  try {
+    payload = (await res.json()) as typeof payload;
+  } catch {
+    return { block: false, reason: "unparseable preflight response" };
+  }
+  // Gate on `provisioned` — the ONE precondition the invitee's first `tot start`
+  // checkout needs (a missing repo is the austin→sample-store failure). Treat only
+  // an explicit `false` as a definitive block; a missing/non-boolean field is
+  // inconclusive → allow. NOT `previewReleased` (see the file header): that now means
+  // provisioned && preview-approved, which is false for every not-yet-shipped store and
+  // would block invites whose checkout actually succeeds.
+  if (payload.provisioned === false) {
+    return { block: true, reason: "not-provisioned", message: blockMessage(tenant) };
+  }
+  return { block: false, reason: "provisioned" };
+}

package/apps/storefront/src/lib/storyblok/provider.ts

@@ -30,6 +30,7 @@ import {
 import { renderRawChrome } from "../rawChrome.js";
 import { parseChromeConfig } from "../chrome/parseConfig.js";
 import { parseChromeAssignments } from "../chrome/model.js";
+import { stampTrackingIdsAtPublish } from "../tracking/publishSafetyNet.js";
 
 /** Safe, always-valid fallback when neither the tenant's own chrome.json nor
  * the default scope's validates — the storefront must always render. */
@@ -599,12 +600,21 @@ export class PublishedContentProvider implements ContentProvider {
   // Raw whole-page documents (T0 marketing tenants) publish via KV too, so a
   // vendor edit previews / goes live with NO Worker rebuild. Artifact path mirrors
   // the source file: content/<tenant>/home.html and .../pages-html/<slug>.html.
+  //
+  // This is content that bypasses git review entirely (a direct KV publish,
+  // never touched by dt-id-writeback's reviewable-diff flow) — so the
+  // publish-time HTMLRewriter safety net (publishSafetyNet.ts) stamps
+  // `data-tot-el` on it here, at the read boundary, before it ever reaches a
+  // route. The base chain's own git-tracked content is NOT re-stamped: that
+  // is dt-id-writeback's job.
   async getHomeHtml(): Promise<string | null> {
-    return (await this.publishedRaw("home.html")) ?? this.base.getHomeHtml();
+    const raw = await this.publishedRaw("home.html");
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getHomeHtml();
   }
   async getPageHtml(slug: string): Promise<string | null> {
     const rel = `pages-html/${normalizeRawPageSlug(slug)}.html`;
-    return (await this.publishedRaw(rel)) ?? this.base.getPageHtml(slug);
+    const raw = await this.publishedRaw(rel);
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getPageHtml(slug);
   }
   listPageHtmlSlugs(): Promise<string[]> {
     return this.listArtifactPaths("pages-html/").then((paths) =>
@@ -618,8 +628,9 @@ export class PublishedContentProvider implements ContentProvider {
   async getChromeHtml(currentPath?: string): Promise<string | null> {
     // A published raw chrome.html override (parallels the home.html/pages-html
     // publish path) wins, so a vendor edit previews / goes live with no rebuild.
+    // Same bypasses-git-review reasoning as getHomeHtml/getPageHtml above: stamp it.
     const publishedHtml = await this.publishedRaw("chrome.html");
-    if (publishedHtml) return publishedHtml;
+    if (publishedHtml) return stampTrackingIdsAtPublish(publishedHtml);
     // Else, if the PUBLISHED chrome.json opts into shared chrome, render
     // the canonical wrapper from it — so a config edit previews without a rebuild.
     const config = parseChromeConfig(await this.published<unknown>("chrome.json"));
@@ -696,12 +707,17 @@ export class DevDraftContentProvider implements ContentProvider {
     return this.get(`dev-draft:${this.tenantId}:${this.draftId}:${path}`);
   }
 
+  // AI-edit drafts (WS5 G4 `/api/content-edit/ai-edit`) never touch
+  // dt-id-writeback's git-reviewed flow either — same publish-time
+  // HTMLRewriter safety net as PublishedContentProvider above.
   async getHomeHtml(): Promise<string | null> {
-    return (await this.draftRaw("content/home.html")) ?? this.base.getHomeHtml();
+    const draft = await this.draftRaw("content/home.html");
+    return draft !== null ? stampTrackingIdsAtPublish(draft) : this.base.getHomeHtml();
   }
   async getPageHtml(slug: string): Promise<string | null> {
     const rel = `content/pages-html/${normalizeRawPageSlug(slug)}.html`;
-    return (await this.draftRaw(rel)) ?? this.base.getPageHtml(slug);
+    const draft = await this.draftRaw(rel);
+    return draft !== null ? stampTrackingIdsAtPublish(draft) : this.base.getPageHtml(slug);
   }
   getHome(): Promise<HomeContent> {
     return this.base.getHome();

package/apps/storefront/src/lib/tracking/collectorAllowlist.ts

@@ -0,0 +1,40 @@
+/**
+ * OWNER: dt-collector-v1. Central allowlist for `POST /api/tracking/interaction`.
+ *
+ * Default-deny, same posture as `@tot/public-runtime`'s activity redaction
+ * contract (`activity/redaction.ts`): the wire payload posted by the browser
+ * collector may carry ONLY these keys. Anything else is dropped and counted —
+ * never stored, never coerced into a known field. There is no per-action
+ * catalog here (unlike the activity spine) because the shape is fixed by the
+ * `TotInteraction` contract (`packages/public-runtime/src/interaction-tracking.ts`):
+ * one event kind, always the same fields.
+ *
+ * Every field here is either a `TotInteraction` attribute-contract field (read
+ * from `data-tot-*`, never from rendered content) or something this unit's own
+ * client-side collector synthesizes (ts / correlationId / seq) — never
+ * anything DOM-derived. Extending this allowlist is the ONE place a new field
+ * must be declared before the ingest module (`collectorIngest.ts`) will accept
+ * it from the wire.
+ */
+
+/** The exact keys a posted interaction event may carry. */
+export const INTERACTION_WIRE_ALLOWLIST = [
+  "type",
+  "el",
+  "action",
+  "placement",
+  "scope",
+  "index",
+  "ts",
+  "correlationId",
+  "seq",
+] as const;
+
+export type InteractionWireKey = (typeof INTERACTION_WIRE_ALLOWLIST)[number];
+
+const ALLOWLIST_SET: ReadonlySet<string> = new Set(INTERACTION_WIRE_ALLOWLIST);
+
+/** True when `key` is a declared field. Anything else must be dropped, not stored. */
+export function isAllowedInteractionKey(key: string): key is InteractionWireKey {
+  return ALLOWLIST_SET.has(key);
+}

package/apps/storefront/src/lib/tracking/collectorIngest.ts

@@ -0,0 +1,188 @@
+/**
+ * Ingest validation for `POST /api/tracking/interaction` (dt-collector-v1).
+ *
+ * PURE (no I/O) — a thin auth-free parse/validate shell, same split as
+ * `activity/ingest.ts`: this module decides accept/reject, the route
+ * (`pages/api/tracking/interaction.ts`) does auth/transport/persistence.
+ *
+ * DEFAULT-DENY ALLOWLIST (reuses the posture of `activity/redaction.ts` /
+ * `activity/ingest.ts`'s `createActivityEvent()` re-validation, not their
+ * code — there is no per-action catalog for a fixed-shape event):
+ *   1. Only keys in `INTERACTION_WIRE_ALLOWLIST` are ever read from the raw
+ *      body. Every other key is DROPPED and COUNTED (`droppedKeys`) — never
+ *      stored, never logged with its value.
+ *   2. A declared key with the WRONG TYPE is never coerced — the whole event
+ *      is rejected with a reason naming the field, exactly like a malformed
+ *      `activity` event is rejected rather than papered over.
+ *
+ * TENANT + STREAM ISOLATION. `tenant_id` and `stream` are NEVER read from the
+ * posted body (they are not even in the allowlist) — the route stamps both
+ * server-side on every accepted event: `tenant_id` from the authenticated
+ * `context.locals.tenant.tenant_id`, `stream` as the fixed literal this module
+ * exports (`INTERACTION_STREAM`). A client cannot claim another tenant's scope
+ * or another stream.
+ */
+import { isIsoTimestamp } from "@tot/public-runtime";
+import { isAllowedInteractionKey } from "./collectorAllowlist.js";
+
+/** The single stream this collector accepts in V1. Never client-supplied —
+ *  stamped server-side so `dt-storage-per-tenant-d1` has a stable discriminator
+ *  column ready before a second stream (e.g. a future custom `track()` call)
+ *  exists. */
+export const INTERACTION_STREAM = "interaction" as const;
+
+/** Interaction kinds this collector accepts. Mirrors `TotInteraction["type"]`
+ *  (currently "click" only — V1 has no other interaction kind). */
+const INTERACTION_TYPES = new Set(["click"]);
+
+/** A validated wire event, before tenant/stream are stamped. */
+export interface InteractionWireEvent {
+  type: "click";
+  el: string;
+  action: string | null;
+  placement: string | null;
+  scope: string | null;
+  index: number | null;
+  /** Client emit clock (ISO-8601). Informational only — never trusted for
+   *  ordering guarantees; the store also has its own receive clock. */
+  ts: string;
+  /** Groups events emitted by one collector lifetime (roughly: one page load). */
+  correlationId: string;
+  /** Monotonic within `correlationId`, assigned by the client collector. */
+  seq: number;
+}
+
+/** The stored/forwarded shape: a validated wire event plus the server stamp. */
+export interface StampedInteractionEvent extends InteractionWireEvent {
+  tenant_id: string;
+  stream: typeof INTERACTION_STREAM;
+  /** Server receive clock (ISO-8601), stamped once per ingest. */
+  ingested_at: string;
+}
+
+export interface InteractionRejection {
+  index: number;
+  reason:
+    | "not_object"
+    | "unknown_type"
+    | "el_invalid"
+    | "action_invalid"
+    | "placement_invalid"
+    | "scope_invalid"
+    | "index_invalid"
+    | "ts_invalid"
+    | "correlation_id_invalid"
+    | "seq_invalid";
+}
+
+export interface AcceptedInteraction {
+  event: StampedInteractionEvent;
+  /** Non-allowlisted keys present on the raw body, dropped before validation
+   *  (fact-of, never the value) — for audit / alerting, same convention as
+   *  `RedactionFieldHit`. */
+  droppedKeys: string[];
+}
+
+export interface InteractionIngestOutcome {
+  accepted: AcceptedInteraction[];
+  rejected: InteractionRejection[];
+}
+
+const MAX_CORRELATION_ID_LEN = 128;
+
+function nullableString(v: unknown): v is string | null {
+  return v === null || v === undefined || typeof v === "string";
+}
+
+function asNullableString(v: unknown): string | null {
+  return typeof v === "string" ? v : null;
+}
+
+/**
+ * Validate + stamp one posted interaction under the authenticated tenant.
+ * Strips any non-allowlisted key first (dropped + counted, never stored),
+ * then validates each allowlisted field's TYPE — a wrong-typed field rejects
+ * the whole event rather than being coerced.
+ */
+export function ingestInteraction(
+  index: number,
+  raw: unknown,
+  tenantId: string,
+  ingestedAt: string,
+): AcceptedInteraction | InteractionRejection {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { index, reason: "not_object" };
+  const e = raw as Record<string, unknown>;
+
+  const droppedKeys = Object.keys(e).filter((k) => !isAllowedInteractionKey(k));
+
+  const type = e.type;
+  if (typeof type !== "string" || !INTERACTION_TYPES.has(type)) return { index, reason: "unknown_type" };
+
+  const el = e.el;
+  if (typeof el !== "string" || el.trim().length === 0) return { index, reason: "el_invalid" };
+
+  if (!nullableString(e.action)) return { index, reason: "action_invalid" };
+  if (!nullableString(e.placement)) return { index, reason: "placement_invalid" };
+  if (!nullableString(e.scope)) return { index, reason: "scope_invalid" };
+
+  const rawIndex = e.index;
+  let idx: number | null;
+  if (rawIndex === null || rawIndex === undefined) {
+    idx = null;
+  } else if (typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0) {
+    idx = rawIndex;
+  } else {
+    return { index, reason: "index_invalid" };
+  }
+
+  const ts = e.ts;
+  if (!isIsoTimestamp(ts)) return { index, reason: "ts_invalid" };
+
+  const correlationId = e.correlationId;
+  if (
+    typeof correlationId !== "string" ||
+    correlationId.trim().length === 0 ||
+    correlationId.length > MAX_CORRELATION_ID_LEN
+  ) {
+    return { index, reason: "correlation_id_invalid" };
+  }
+
+  const seq = e.seq;
+  if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 0) {
+    return { index, reason: "seq_invalid" };
+  }
+
+  const event: StampedInteractionEvent = {
+    type: "click",
+    el,
+    action: asNullableString(e.action),
+    placement: asNullableString(e.placement),
+    scope: asNullableString(e.scope),
+    index: idx,
+    ts,
+    correlationId,
+    seq,
+    // Server-stamped, never from the client.
+    tenant_id: tenantId,
+    stream: INTERACTION_STREAM,
+    ingested_at: ingestedAt,
+  };
+
+  return { event, droppedKeys };
+}
+
+/** Validate + stamp a whole posted batch under the authenticated tenant. */
+export function ingestInteractions(
+  events: unknown[],
+  tenantId: string,
+  ingestedAt: string,
+): InteractionIngestOutcome {
+  const accepted: AcceptedInteraction[] = [];
+  const rejected: InteractionRejection[] = [];
+  events.forEach((raw, i) => {
+    const r = ingestInteraction(i, raw, tenantId, ingestedAt);
+    if ("event" in r) accepted.push(r);
+    else rejected.push(r);
+  });
+  return { accepted, rejected };
+}

package/apps/storefront/src/lib/tracking/d1Control.ts

@@ -0,0 +1,180 @@
+/**
+ * Cloudflare D1 control + data plane over the REST API — how a PER-TENANT D1
+ * database is created and queried from inside the Worker.
+ *
+ * WHY REST AND NOT A BINDING. Worker bindings are STATIC: `wrangler.toml`
+ * declares a fixed set of `[[d1_databases]]` at build time, so there is no
+ * `env.lookupD1(name)` and no way for a request to bind a database that did not
+ * exist when the Worker was built. One database per tenant is therefore only
+ * reachable through the D1 HTTP API (`/accounts/:account/d1/database/...`),
+ * which addresses a database by UUID at call time. The shared bindings
+ * (`CATALOG_DB`, `STOREFRONT_APPS_DB`) stay exactly as they are; this module is
+ * additive and used ONLY for the per-tenant raw-interaction stores.
+ *
+ * CREDENTIALS. `CF_ACCOUNT_ID` + `TRACKING_D1_API_TOKEN` (a `wrangler secret`,
+ * scoped to D1:edit). Either one absent ⇒ `readD1Control()` returns undefined
+ * and every caller treats that as "sink unavailable, skip it" — never an error,
+ * the same posture `readAnalytics` + `activity/store.ts` already establish for
+ * an unbound sink. Nothing here ever throws to the caller.
+ *
+ * The query adapter satisfies the same `Queryable` seam the binding-backed
+ * stores use (`d1/catalog.ts`), so the insert code in `interactionStore.ts` is
+ * transport-agnostic and unit-testable against an in-memory sqlite.
+ */
+import { readEnv } from "../env.js";
+import type { Queryable, QueryStatement } from "../d1/catalog.js";
+
+const CF_API_BASE = "https://api.cloudflare.com/client/v4";
+
+/** Resolved REST credentials for the D1 API. */
+export interface D1ControlConfig {
+  accountId: string;
+  apiToken: string;
+  /** Injected for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Injected for tests; defaults to the public Cloudflare API. */
+  apiBase?: string;
+}
+
+/**
+ * Read the D1 REST credentials from the runtime env. Undefined when either is
+ * unset — i.e. the per-tenant store is not configured in this environment
+ * (local `astro dev`, an un-provisioned tier). Callers SKIP, never fail.
+ */
+export async function readD1Control(): Promise<D1ControlConfig | undefined> {
+  const [accountId, apiToken] = await Promise.all([
+    readEnv("CF_ACCOUNT_ID"),
+    readEnv("TRACKING_D1_API_TOKEN"),
+  ]);
+  if (!accountId || !apiToken) return undefined;
+  return { accountId, apiToken };
+}
+
+interface CfEnvelope<T> {
+  success?: boolean;
+  result?: T;
+  errors?: Array<{ code?: number; message?: string }>;
+}
+
+async function cfRequest<T>(
+  cfg: D1ControlConfig,
+  path: string,
+  init?: { method?: string; body?: unknown },
+): Promise<CfEnvelope<T>> {
+  const doFetch = cfg.fetchImpl ?? fetch;
+  const res = await doFetch(`${cfg.apiBase ?? CF_API_BASE}/accounts/${cfg.accountId}${path}`, {
+    method: init?.method ?? "GET",
+    headers: {
+      authorization: `Bearer ${cfg.apiToken}`,
+      "content-type": "application/json",
+    },
+    body: init?.body === undefined ? undefined : JSON.stringify(init.body),
+  });
+  const parsed = (await res.json()) as CfEnvelope<T>;
+  if (!res.ok || parsed.success === false) {
+    const detail = parsed.errors?.map((e) => e.message).filter(Boolean).join("; ") || `HTTP ${res.status}`;
+    throw new Error(`d1 api ${path} failed: ${detail}`);
+  }
+  return parsed;
+}
+
+interface D1DatabaseSummary {
+  uuid?: string;
+  name?: string;
+}
+
+/** The UUID of the D1 database with this exact name, or null if none exists. */
+export async function findDatabaseByName(
+  cfg: D1ControlConfig,
+  name: string,
+): Promise<string | null> {
+  const body = await cfRequest<D1DatabaseSummary[]>(
+    cfg,
+    `/d1/database?name=${encodeURIComponent(name)}&per_page=100`,
+  );
+  // `?name=` is a SUBSTRING filter on Cloudflare's side, so match exactly here —
+  // otherwise `…-dt-acme` could resolve to `…-dt-acme-staging` and route one
+  // tenant's rows into another tenant's database.
+  const exact = (body.result ?? []).find((d) => d.name === name);
+  return exact?.uuid ?? null;
+}
+
+/** Create a D1 database and return its UUID. */
+export async function createDatabase(cfg: D1ControlConfig, name: string): Promise<string> {
+  const body = await cfRequest<D1DatabaseSummary>(cfg, "/d1/database", {
+    method: "POST",
+    body: { name },
+  });
+  const uuid = body.result?.uuid;
+  if (!uuid) throw new Error(`d1 api create ${name} returned no uuid`);
+  return uuid;
+}
+
+/**
+ * Find-or-create, tolerant of a concurrent creator: two beacons for a brand-new
+ * tenant can race here, and the loser's `create` fails with "already exists" —
+ * which is a SUCCESS for our purposes, so we re-resolve by name instead of
+ * propagating it.
+ */
+export async function ensureDatabase(cfg: D1ControlConfig, name: string): Promise<string> {
+  const existing = await findDatabaseByName(cfg, name);
+  if (existing) return existing;
+  try {
+    return await createDatabase(cfg, name);
+  } catch (err) {
+    const raced = await findDatabaseByName(cfg, name);
+    if (raced) return raced;
+    throw err;
+  }
+}
+
+interface D1QueryResult {
+  results?: unknown[];
+}
+
+/** POST one (or a semicolon-separated script of) statement(s) to a database. */
+async function query(
+  cfg: D1ControlConfig,
+  databaseUuid: string,
+  sql: string,
+  params: readonly unknown[],
+): Promise<unknown[]> {
+  const body = await cfRequest<D1QueryResult[]>(cfg, `/d1/database/${databaseUuid}/query`, {
+    method: "POST",
+    body: { sql, params },
+  });
+  // One entry per statement; flatten to the rows of the LAST statement, which is
+  // what a single-statement `all`/`first` caller means.
+  const blocks = body.result ?? [];
+  return (blocks[blocks.length - 1]?.results ?? []) as unknown[];
+}
+
+/**
+ * Adapt a per-tenant database (addressed by UUID over REST) to the same
+ * `Queryable` seam the D1 bindings use. `batch` is emulated as a
+ * semicolon-joined script in ONE HTTP call — D1's `/query` runs a multi-
+ * statement script inside one implicit transaction, which is what the binding's
+ * `batch()` guarantees too.
+ */
+export function fromD1Rest(cfg: D1ControlConfig, databaseUuid: string): Queryable {
+  return {
+    all: async <T>(sql: string, ...params: unknown[]) =>
+      (await query(cfg, databaseUuid, sql, params)) as T[],
+    first: async <T>(sql: string, ...params: unknown[]) =>
+      (((await query(cfg, databaseUuid, sql, params))[0] ?? null) as T | null),
+    run: async (sql: string, ...params: unknown[]) => {
+      await query(cfg, databaseUuid, sql, params);
+    },
+    exec: async (sql: string) => {
+      await query(cfg, databaseUuid, sql, []);
+    },
+    batch: async (statements: readonly QueryStatement[]) => {
+      if (statements.length === 0) return;
+      // The REST `params` array is positional across the whole script, so the
+      // placeholders of every statement bind in order.
+      const sql = statements.map((s) => s.sql.trim().replace(/;$/, "")).join(";\n");
+      const params = statements.flatMap((s) => [...(s.params ?? [])]);
+      await query(cfg, databaseUuid, sql, params);
+    },
+  };
+}