@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/pages/api/admin/orders/[id].ts

@@ -0,0 +1,53 @@
+/**
+ * `GET /api/admin/orders/:id` — one order's full detail for the Orders tab (U2).
+ *
+ * Server-side proxy to tot-foxycart `GET /commerce/orders/:orderId` for the
+ * resolved tenant + env. Bearer stays server-side; response is the FoxyOrderDetail
+ * DTO. `verificationDetail` is empty until U4 fills it — consumers tolerate that.
+ * Read-only (scope-locks).
+ */
+import type { APIContext } from "astro";
+import { readEnv } from "@/lib/env";
+import {
+  createFoxyOrderClient,
+  orderApiBaseUrl,
+  OrderApiError,
+} from "@/lib/admin/orderClient";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+function jsonError(code: string, status: number): Response {
+  return new Response(JSON.stringify({ error: code }), {
+    status,
+    headers: JSON_HEADERS,
+  });
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tenant, customizationEnv } = context.locals;
+  const orderId = context.params.id;
+  if (!orderId) return jsonError("order_not_found", 404);
+
+  const bearer = await readEnv("FOXY_ORDER_API_KEY");
+  if (!bearer) return jsonError("not_provisioned", 503);
+
+  const client = createFoxyOrderClient({
+    baseUrl: orderApiBaseUrl(customizationEnv),
+    appDomain: tenant.appDomain,
+    bearer,
+  });
+
+  try {
+    const order = await client.getOrder(orderId);
+    return new Response(JSON.stringify({ order }), { headers: JSON_HEADERS });
+  } catch (err) {
+    if (err instanceof OrderApiError) return jsonError(err.code, err.status);
+    return jsonError("unexpected", 500);
+  }
+}

package/apps/storefront/src/pages/api/admin/orders.ts

@@ -0,0 +1,71 @@
+/**
+ * `GET /api/admin/orders` — internal admin route backing the Orders tab (U2).
+ *
+ * Server-side proxy to tot-foxycart's order READ API for the resolved tenant +
+ * environment. The per-tenant bearer key stays on the Worker (never in the
+ * response); the browser only ever sees order DTO JSON. Read-only (scope-locks).
+ * U3 consumes this and maps the DTO → OrdersViewModel.
+ *
+ * Access control matches the rest of the admin surface (owned by the admin
+ * host/approver layer) — same posture as `api/evidence.json.ts`; no new gate here.
+ */
+import type { APIContext } from "astro";
+import type { FoxyOrderListFilters } from "@tot/public-runtime";
+import { readEnv } from "@/lib/env";
+import {
+  createFoxyOrderClient,
+  orderApiBaseUrl,
+  OrderApiError,
+} from "@/lib/admin/orderClient";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+function jsonError(code: string, status: number): Response {
+  return new Response(JSON.stringify({ error: code }), {
+    status,
+    headers: JSON_HEADERS,
+  });
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tenant, customizationEnv } = context.locals;
+
+  const bearer = await readEnv("FOXY_ORDER_API_KEY");
+  if (!bearer) {
+    // Worker secret not provisioned for this env — a config error, not the
+    // caller's fault. Never echo the (missing) key.
+    return jsonError("not_provisioned", 503);
+  }
+
+  const url = new URL(context.request.url);
+  const q = url.searchParams;
+  const limitRaw = q.get("limit");
+  const filters: FoxyOrderListFilters = {
+    queue: q.get("queue") ?? undefined,
+    status: q.get("status") ?? undefined,
+    from: q.get("from") ?? undefined,
+    to: q.get("to") ?? undefined,
+    limit: limitRaw != null ? Number(limitRaw) : undefined,
+    cursor: q.get("cursor") ?? undefined,
+  };
+
+  const client = createFoxyOrderClient({
+    baseUrl: orderApiBaseUrl(customizationEnv),
+    appDomain: tenant.appDomain,
+    bearer,
+  });
+
+  try {
+    const data = await client.listOrders(filters);
+    return new Response(JSON.stringify(data), { headers: JSON_HEADERS });
+  } catch (err) {
+    if (err instanceof OrderApiError) return jsonError(err.code, err.status);
+    return jsonError("unexpected", 500);
+  }
+}

package/apps/storefront/src/pages/api/auth/logout.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/auth/logout — end the signed-in session.
+ *
+ * Revokes the server-side record (so the session can't be reused even if the
+ * cookie is replayed) and clears the cookie, then bounces to the login page.
+ * Exempt from the login gate (it's under /api/auth/), so a viewer can always
+ * sign out.
+ */
+import type { APIContext } from "astro";
+import { getSessionStore, clearSessionCookie } from "@/lib/auth/route";
+import { revokeSession, SESSION_COOKIE } from "@/lib/auth/session";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const sid = context.cookies.get(SESSION_COOKIE)?.value ?? null;
+  const store = await getSessionStore();
+  if (store) await revokeSession(store, sid);
+  clearSessionCookie(context);
+  return context.redirect("/auth/login", 303);
+}

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -0,0 +1,107 @@
+/**
+ * POST /api/auth/magic-exchange — exchange a magic-link token for a signed-in session.
+ *
+ * The POST half of the magic-link flow (see /auth/magic for the GET-safe landing). The
+ * one-time `signInToken` (minted by tot20 via developerInvites `issueSignInToken:true`,
+ * embedded in the storefront's branded email) is exchanged HERE — only on a POST, only
+ * from the human clicking "Confirm sign in", never on a GET (inbox link-scanners fire
+ * GET and would burn the token).
+ *
+ * tot20 verifies + BURNS the token (single-use), resolves memberships fresh, and returns
+ * a signed federated `id_token` — identical contract to /api/auth/verify. We verify that
+ * assertion OFFLINE against tot's JWKS and derive the session from its claims (never trust
+ * unsigned JSON). Fail closed on any gap.
+ */
+import type { APIContext } from "astro";
+import {
+  getAccessClient,
+  getSessionStore,
+  setSessionCookie,
+  safeNext,
+} from "@/lib/auth/route";
+import {
+  getFederatedVerifier,
+  sessionFromFederatedClaims,
+} from "@/lib/auth/identityToken";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+
+export const prerender = false;
+
+/** Back to the landing page carrying an error (no token in the URL on failure). */
+function magicRedirect(
+  context: APIContext,
+  params: { error?: string; next?: string },
+): Response {
+  const q = new URLSearchParams();
+  if (params.error) q.set("error", params.error);
+  if (params.next && params.next !== "/dashboard") q.set("next", params.next);
+  const qs = q.toString();
+  return context.redirect(`/auth/magic${qs ? `?${qs}` : ""}`, 303);
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  let token = "";
+  let next = "/dashboard";
+  try {
+    const form = await context.request.formData();
+    token = String(form.get("token") ?? "").trim();
+    next = safeNext(String(form.get("next") ?? "/dashboard"));
+  } catch {
+    return magicRedirect(context, { error: "invalid", next });
+  }
+  if (!token) return magicRedirect(context, { error: "missing", next });
+
+  const client = await getAccessClient();
+  const store = await getSessionStore();
+  if (!client || !store) {
+    return magicRedirect(context, { error: "unconfigured", next });
+  }
+
+  // Consume the token (single-use; burned server-side by tot20).
+  const result = await client.exchangeSignInToken(token);
+  if (!result.ok) {
+    // reason ∈ invalid|expired|error (tot20's "used" normalizes to invalid).
+    const error = result.reason === "expired" ? "expired" : "invalid";
+    return magicRedirect(context, { error, next });
+  }
+
+  // Prove authorization offline — fail closed with no flat-JSON fallback.
+  const idToken = result.id_token;
+  if (!idToken) {
+    console.error("auth/magic-exchange: no id_token on exchange; failing closed");
+    return magicRedirect(context, { error: "verify_failed", next });
+  }
+  const verifier = await getFederatedVerifier();
+  if (!verifier) {
+    console.error("auth/magic-exchange: federated verifier unconfigured");
+    return magicRedirect(context, { error: "unconfigured", next });
+  }
+
+  let derived;
+  try {
+    const claims = await verifier.verify(idToken); // enforces aud === STOREFRONT_APP_DOMAIN
+    derived = sessionFromFederatedClaims(claims);
+  } catch (err) {
+    console.error("auth/magic-exchange: id_token verification failed; failing closed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return magicRedirect(context, { error: "verify_failed", next });
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const { id } = await createSession(
+    store,
+    {
+      email: derived.email,
+      resource: derived.resource,
+      roles: [],
+      capability: "member",
+      tenants: derived.tenants,
+      staff: derived.staff,
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    nowSeconds,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  return context.redirect(next, 303);
+}

package/apps/storefront/src/pages/api/auth/send.ts

@@ -0,0 +1,85 @@
+/**
+ * POST /api/auth/send — ask tot20 to email a one-time access code (FEDERATED).
+ *
+ * Federated multi-tenant sign-in: storefront authenticates as its OWN operator
+ * identity and asks tot20 to mail a code to the email if it holds a role on ANY
+ * tenant — no `resource` is sent (the resource-scoped `/access-code/send` stays
+ * for preview-host gating; console sign-in is federated). ENUMERATION-RESISTANT:
+ * the response is identical whether or not the email is eligible — we always
+ * redirect to the "enter your code" step. Accepts an HTML form post (no JS needed).
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+import {
+  EMAIL_RE,
+  getAccessClient,
+  safeNext,
+  loginRedirect,
+} from "@/lib/auth/route";
+import {
+  devAuthEnabled,
+  devAuthCode,
+  storeDevCode,
+  DEV_AUTH_CODE_TTL_SECONDS,
+} from "@/lib/auth/devAuth";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  let email = "";
+  let next = "/";
+  try {
+    const form = await context.request.formData();
+    email = String(form.get("email") ?? "").trim().toLowerCase();
+    next = safeNext(String(form.get("next") ?? "/"));
+  } catch {
+    return loginRedirect(context, { error: "invalid", next });
+  }
+
+  // Bad address → send them back to step 1 with a gentle error (no code step).
+  if (!EMAIL_RE.test(email)) {
+    return loginRedirect(context, { error: "bad_email", next });
+  }
+
+  // LOCAL DEV AUTH (send side). `import.meta.env.DEV` is a STATIC boolean — this
+  // whole branch is tree-shaken out of the production build (same mechanism as the
+  // dev guards in middleware/index.ts). It NEVER weakens the hosted path.
+  //
+  // On localhost tot20 isn't reachable, so no email can be sent. When a developer
+  // opts in with `DEV_AUTH=1` in `.dev.vars`, we instead mint a one-time code,
+  // store it in the SESSION KV, and PRINT it to the server console so the developer
+  // can complete sign-in locally. (The verify side that ACCEPTS this code + mints a
+  // session without tot20 is the security-sensitive half — see the handoff
+  // `2026-07-09-storefront-local-dev-auth-mode.md`; until it lands, the code is
+  // stored + printed but sign-in completes only once that verify path is wired.)
+  if (import.meta.env.DEV && (await devAuthEnabled())) {
+    const kv = await readKv("SESSION");
+    if (kv) {
+      const code = devAuthCode();
+      await storeDevCode(kv, email, code);
+      // eslint-disable-next-line no-console -- dev-only server-console code delivery
+      console.log(
+        `\n  🔑 [DEV AUTH] sign-in code for ${email}: ${code}\n` +
+          `     valid ${DEV_AUTH_CODE_TTL_SECONDS / 60}m · printed here only (no email in local dev)\n`,
+      );
+    } else {
+      // eslint-disable-next-line no-console -- dev-only diagnostic
+      console.warn(
+        "[DEV AUTH] DEV_AUTH=1 but no SESSION KV is bound — cannot store a dev code.",
+      );
+    }
+    // Same opaque redirect as the real path (keeps the UX identical).
+    return loginRedirect(context, { sent: true, email, next });
+  }
+
+  const client = await getAccessClient();
+  if (!client) {
+    // Integration not configured — don't pretend we sent a code.
+    return loginRedirect(context, { error: "unconfigured", email, next });
+  }
+
+  // Fire-and-neutral: even a failure here resolves opaque so we never leak
+  // whether the address is a role-holder.
+  await client.sendFederatedCode(email);
+  return loginRedirect(context, { sent: true, email, next });
+}

package/apps/storefront/src/pages/api/auth/verify.ts

@@ -0,0 +1,135 @@
+/**
+ * POST /api/auth/verify — verify the one-time code and mint the FEDERATED,
+ * multi-tenant signed-in session.
+ *
+ * Federated sign-in: storefront calls tot20's `/access-code/federated-verify`
+ * (as its own operator identity, no `resource`). tot20 checks the code and returns
+ * a signed `id_token` whose `aud` = the STOREFRONT app identity (not a tenant) and
+ * whose `tenants[]` carries ALL of the email's memberships.
+ *
+ * We verify that assertion OFFLINE against tot's JWKS with `aud` pinned to the
+ * storefront's configured app identity (`STOREFRONT_APP_DOMAIN`), then bind EVERY
+ * membership into the session — so the dashboard picker sees every vendor. Fail
+ * closed if the signed assertion is missing or verification fails (never trust the
+ * flat JSON). See `@/lib/auth/identityToken`.
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+import {
+  getAccessClient,
+  getSessionStore,
+  setSessionCookie,
+  safeNext,
+  loginRedirect,
+} from "@/lib/auth/route";
+import {
+  getFederatedVerifier,
+  sessionFromFederatedClaims,
+} from "@/lib/auth/identityToken";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+import { devAuthEnabled, consumeDevCode, devSessionFields } from "@/lib/auth/devAuth";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  let email = "";
+  let code = "";
+  let next = "/";
+  try {
+    const form = await context.request.formData();
+    email = String(form.get("email") ?? "").trim().toLowerCase();
+    code = String(form.get("code") ?? "").trim();
+    next = safeNext(String(form.get("next") ?? "/"));
+  } catch {
+    return loginRedirect(context, { error: "invalid", next });
+  }
+
+  if (!email || !code) {
+    return loginRedirect(context, { sent: true, email, error: "invalid", next });
+  }
+
+  // LOCAL DEV AUTH (verify side). `import.meta.env.DEV` is a STATIC boolean — this
+  // whole branch (and the devAuth imports) are tree-shaken out of the production
+  // build, so the hosted path below (offline JWKS verification, fail-closed) is
+  // never weakened. Second gate: the DEV_AUTH opt-in. Consume the console-printed
+  // code stored by /api/auth/send and mint a local session WITHOUT tot20 — the
+  // localhost completion of the invite→sign-in loop. See @/lib/auth/devAuth.
+  if (import.meta.env.DEV && (await devAuthEnabled())) {
+    const store = await getSessionStore();
+    const kv = await readKv("SESSION");
+    if (!store || !kv) {
+      return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+    }
+    if (!(await consumeDevCode(kv, email, code))) {
+      // Same "code didn't match" UX as the real path (wrong/expired/replayed code).
+      return loginRedirect(context, { sent: true, email, error: "invalid", next });
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const { id } = await createSession(
+      store,
+      await devSessionFields(email),
+      DEFAULT_SESSION_TTL_SECONDS,
+      nowSeconds,
+    );
+    setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+    return context.redirect(next, 303);
+  }
+
+  const client = await getAccessClient();
+  const store = await getSessionStore();
+  if (!client || !store) {
+    return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+  }
+
+  const result = await client.verifyFederatedCode(email, code);
+  if (!result.ok) {
+    // Show the code step again with the specific reason (invalid/expired/too_many_attempts).
+    return loginRedirect(context, { sent: true, email, error: result.reason, next });
+  }
+
+  // Prove authorization offline. Fail closed (no flat-JSON fallback) if the signed
+  // assertion is missing or fails verification.
+  const idToken = result.id_token;
+  if (!idToken) {
+    console.error("auth/verify: no id_token on federated result; failing closed");
+    return loginRedirect(context, { sent: true, email, error: "verify_failed", next });
+  }
+
+  // aud is the STOREFRONT app identity (STOREFRONT_APP_DOMAIN), not a tenant.
+  const verifier = await getFederatedVerifier();
+  if (!verifier) {
+    console.error("auth/verify: federated verifier unconfigured (TOT_CORE_URL/STOREFRONT_APP_DOMAIN)");
+    return loginRedirect(context, { sent: true, email, error: "unconfigured", next });
+  }
+
+  let derived;
+  try {
+    const claims = await verifier.verify(idToken); // enforces aud === STOREFRONT_APP_DOMAIN
+    // Bind EVERY membership — no single-tenant scoping (multi-vendor picker input).
+    derived = sessionFromFederatedClaims(claims);
+  } catch (err) {
+    console.error("auth/verify: federated id_token verification failed; failing closed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return loginRedirect(context, { sent: true, email, error: "verify_failed", next });
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const { id } = await createSession(
+    store,
+    {
+      email: derived.email,
+      // The verified aud (storefront app identity) — the console session's scope.
+      resource: derived.resource,
+      // Per-tenant roles live in tenants[]; the console session itself is role-neutral.
+      roles: [],
+      capability: "member",
+      tenants: derived.tenants,
+      staff: derived.staff,
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    nowSeconds,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  return context.redirect(next, 303);
+}

package/apps/storefront/src/pages/api/cache-purge.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /api/cache-purge — bump a tenant's edge page-cache version.
+ *
+ * The ETL load step calls this per tenant after a (re)migration so freshly
+ * migrated content is visible immediately, rather than waiting out the page
+ * TTL. This closes the loop that HttpToTClient.purgeTenant() (catalog API cache)
+ * only half-covered: that purges the data cache; this purges the rendered HTML.
+ *
+ * Auth: `Authorization: Bearer <CACHE_PURGE_SECRET>`. JSON bodies are exempt from
+ * Astro's CSRF origin check, so the server-to-server ETL caller works.
+ */
+import type { APIContext } from "astro";
+import { readEnv, readKv } from "@/lib/env";
+import { bumpCacheVersion } from "@/lib/edgeCache";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const secret = await readEnv("CACHE_PURGE_SECRET");
+  const auth = context.request.headers.get("authorization");
+  if (!secret || auth !== `Bearer ${secret}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const kv = await readKv("TENANT_CACHE");
+  if (!kv) {
+    return new Response("No cache store bound", { status: 503 });
+  }
+
+  let tenantId: string | undefined;
+  try {
+    tenantId = ((await context.request.json()) as { tenantId?: string })?.tenantId;
+  } catch {
+    /* fall through to 400 */
+  }
+  if (!tenantId) {
+    return new Response("tenantId required", { status: 400 });
+  }
+
+  const version = await bumpCacheVersion(kv, tenantId);
+  return new Response(JSON.stringify({ tenantId, version }), {
+    headers: { "content-type": "application/json" },
+  });
+}

package/apps/storefront/src/pages/api/checkout-style.css.ts

@@ -0,0 +1,43 @@
+/**
+ * `GET /api/checkout-style.css` — the stable, per-tenant storefront URL that hosts
+ * the published checkout styling as `text/css`. This URL is what U11's publisher
+ * points FoxyCart's checkout-template `content_url` at (PUT /theme/foxy) and what
+ * Foxy fetches server-side when it (re)caches the checkout template.
+ *
+ * The tenant + environment are self-identifying from the request Host (Foxy's
+ * fetch carries no session): the middleware resolves `locals.tenant` +
+ * `locals.customizationEnv`, and we serve exactly that tenant's published style
+ * for that env (live on prod hosts, test behind a preview token). Falls back to
+ * the neutral DEFAULT_CHECKOUT_STYLE tokens when nothing is published, so the URL
+ * is always a valid, non-empty stylesheet.
+ *
+ * ASCII-safety (Foxy cache is not Unicode-safe) is enforced inside
+ * buildCheckoutStyleCss. No secrets, no cross-service call — read-only from KV.
+ */
+import type { APIContext } from "astro";
+import { buildCheckoutStyleCss } from "@tot/public-runtime";
+import { readKv } from "@/lib/env";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tenant, customizationEnv } = context.locals;
+  const kv = await readKv("TENANT_CACHE");
+  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+
+  const css = await buildCheckoutStyleCss(
+    kvGet,
+    tenant.tenant_id,
+    customizationEnv,
+  );
+
+  return new Response(css, {
+    headers: {
+      "content-type": "text/css; charset=utf-8",
+      // Foxy caches on its side via /theme/foxy/refresh; keep the origin fresh so
+      // a re-cache always pulls the latest published styling.
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}

package/apps/storefront/src/pages/api/cli/policy.ts

@@ -0,0 +1,70 @@
+/**
+ * GET /api/cli/policy — the storefront-hosted, KV-dynamic version-support policy
+ * for the `tot` CLI (update-awareness Layer 2). PUBLIC, unauthenticated: it only
+ * answers "which CLI versions does ToT still support / recommend?", which is not
+ * secret and must be readable by an unauthenticated CLI on first run.
+ *
+ * The CLI's detached update-check refresh fetches this best-effort and hands the
+ * body to recordServerPolicy() (packages/cli/src/update-check.mjs), so the next
+ * `tot` run renders ToT's support verdict. Because the value lives in KV, ToT can
+ * raise the floor / recommend a new rc WITHOUT a storefront redeploy.
+ *
+ * Contract: JSON `{ minSupported?, recommended?, message? }`. When the KV key is
+ * unset (or no KV in this runtime), returns `{}` — a safe no-op, so shipping this
+ * route changes nothing for any CLI until ToT actually sets the value.
+ *
+ * SETTING THE POLICY (no code change, no redeploy — the whole point):
+ *   wrangler kv key put --binding=TENANT_CACHE --env preview cli:policy \
+ *     '{"minSupported":"1.3.1","recommended":"1.3.1-rc.6","message":"rc.5 has a bad build; move to rc.6"}'
+ *   Clear it (back to no-op) with: wrangler kv key delete --binding=TENANT_CACHE --env preview cli:policy
+ * A small authed PUT is a possible follow-up for nicer ergonomics; the KV put is
+ * the idiomatic write path today. See docs/architecture/dev-experience-hosted-vs-local.md.
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+
+export const prerender = false;
+
+/** KV key holding the (global, not per-tenant) CLI version-support policy. */
+export const CLI_POLICY_KV_KEY = "cli:policy";
+
+interface CliPolicy {
+  minSupported?: string;
+  recommended?: string;
+  message?: string;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      // Public + safe to cache briefly at the edge; the CLI itself only refreshes
+      // once/day, so a short TTL keeps ToT's edits propagating quickly.
+      "cache-control": "public, max-age=300",
+    },
+  });
+}
+
+/** Keep only the three known string fields — never echo arbitrary stored data. */
+function sanitize(raw: unknown): CliPolicy {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: CliPolicy = {};
+  if (typeof r.minSupported === "string") out.minSupported = r.minSupported;
+  if (typeof r.recommended === "string") out.recommended = r.recommended;
+  if (typeof r.message === "string") out.message = r.message;
+  return out;
+}
+
+export async function GET(_context: APIContext): Promise<Response> {
+  const kv = await readKv("TENANT_CACHE");
+  if (!kv) return json({}); // no KV in this runtime (dev) — safe no-op default
+  const raw = await kv.get(CLI_POLICY_KV_KEY);
+  if (!raw) return json({}); // unset — no-op until ToT sets it
+  try {
+    return json(sanitize(JSON.parse(raw)));
+  } catch {
+    return json({}); // malformed stored value — degrade to no-op, never 500
+  }
+}