@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/pages/api/content-edit/ai-edit.ts

@@ -0,0 +1,164 @@
+/**
+ * POST /api/content-edit/ai-edit — the `/dev` page's "Build with Claude" live loop
+ * (WS5 G4 + decision draft-overlay-same-origin). A prompt becomes a reviewable
+ * per-file diff via tot-mcp's `content_edit` tool, applied to the signed-in
+ * developer's OWN tenant content — and materialized into their private DRAFT
+ * overlay so the /dev live preview shows the change instantly (visible AND
+ * interactive), while live/test channels and every other viewer are untouched.
+ *
+ * AUTH: `/dev`'s own signed-in-viewer session (`readViewerSession`) is the
+ * developer-level gate; the MCP call authenticates as the storefront's own
+ * TENANT-OPERATOR credential (`getContentEditClient` — the same
+ * credential_validate path `/api/changes/accept` uses). The tenant edited is the
+ * SESSION'S OWN first membership — never a caller-supplied tenant.
+ *
+ * DRAFT MATERIALIZATION: content_edit returns unified DIFFS, not contents, so we
+ * re-apply each diff to the exact content we sent (applyUnifiedDiff, strict +
+ * fail-closed) and write the results to `dev-draft:` KV keys with a TTL, minting
+ * the signed tot_dev_draft cookie the middleware's overlay verifies. When KV or
+ * the signing secret is absent (e.g. bare `astro dev`), the edit still runs and
+ * returns diffs — `applied:false` tells the page the preview won't change.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { getContentEditClient } from "@/lib/content-edit";
+import { applyUnifiedDiff, DiffApplyError } from "@/lib/content-edit/applyDiff";
+import { json } from "@/lib/grants/route.js";
+import { readEnv, readKv } from "@/lib/env";
+// Arbitrary-tenant lookup lives behind the config-layer provider so this handler
+// doesn't import the concrete resolver/static-map directly (tenancy-resolver-fence).
+import { resolvePreviewTenant } from "@/config/previewTenantLookup";
+import { createContentProvider } from "@/lib/storyblok/provider";
+import { readPublishedArtifact, themeArtifactPath } from "@tot/public-runtime";
+import {
+  DEV_DRAFT_COOKIE,
+  DEV_DRAFT_TTL_SECONDS,
+  devDraftKey,
+  signDevDraftToken,
+  verifyDevDraftToken,
+} from "@/lib/dev/devDraft";
+import type { ContentEditFile } from "@/lib/content-edit/types";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const session = await readViewerSession({ cookies: context.cookies });
+  if (!session) return json({ error: "sign in required" }, 401);
+  if (!session.capability || session.capability === "none") {
+    return json({ error: "no developer capability on this account" }, 403);
+  }
+
+  let body: { prompt?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+  if (!prompt) return json({ error: "prompt is required" }, 400);
+
+  // The tenant is the session's OWN store (first membership, else the session's
+  // primary resource) — the same resolution /dev renders with. No caller-supplied
+  // tenant is ever honored here.
+  const wanted = (session.tenants?.[0]?.resource ?? session.resource ?? "").toLowerCase();
+  const tenant = wanted ? await resolvePreviewTenant(wanted) : null;
+  if (!tenant) return json({ error: "no store linked to this account" }, 403);
+
+  const kv = await readKv("TENANT_CACHE");
+  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+  const secret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
+  // Reuse the caller's existing draft (so successive edits stack) or start a new one.
+  const priorCookie = context.cookies.get(DEV_DRAFT_COOKIE)?.value ?? null;
+  const priorClaims =
+    priorCookie && secret ? await verifyDevDraftToken(secret, priorCookie, nowSeconds) : null;
+  const draftId =
+    priorClaims?.tenantId === tenant.tenant_id ? priorClaims.draftId : crypto.randomUUID();
+
+  // Current content = the developer's draft when present, else what actually serves
+  // (published overlay → build-time), so edits stack and always start from reality.
+  const provider = createContentProvider(tenant, kv ? { get: kvGet, env: "live" } : undefined);
+  const draftHome = await kvGet(devDraftKey(tenant.tenant_id, draftId, "content/home.html"));
+  const homeHtml = draftHome ?? (await provider.getHomeHtml());
+  const draftTheme = await kvGet(devDraftKey(tenant.tenant_id, draftId, "theme.json"));
+  const themeJson =
+    draftTheme ??
+    (await readPublishedArtifact(kvGet, tenant.tenant_id, "live", themeArtifactPath(tenant.tenant_id))) ??
+    JSON.stringify(tenant.theme_tokens ?? {}, null, 2);
+
+  // content_edit's allowlist: home document + theme. A block-based tenant with no raw
+  // home.html still gets theme edits (themeStyle drives its pages).
+  const files: ContentEditFile[] = [];
+  if (homeHtml) files.push({ path: "content/home.html", content: homeHtml });
+  files.push({ path: "theme.json", content: themeJson });
+
+  const client = await getContentEditClient();
+  if (client instanceof Response) return client;
+
+  let result;
+  try {
+    result = await client.editContent(prompt, files);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return json({ ok: false, error: message }, 502);
+  }
+
+  // Materialize the draft: re-apply each returned diff to the exact content we sent.
+  // Strict + fail-closed per file — a bad diff writes nothing for that file. Theme
+  // must still parse as JSON before it may land (a broken draft theme would degrade
+  // the whole preview).
+  const sent = new Map(files.map((f) => [f.path, f.content]));
+  const appliedPaths: string[] = [];
+  const canApply = !!kv && !!secret;
+  if (canApply) {
+    for (const d of result.diffs ?? []) {
+      const base = sent.get(d.path);
+      if (base == null) continue; // never write a path we didn't offer
+      let next: string;
+      try {
+        next = applyUnifiedDiff(base, d.diff);
+      } catch (err) {
+        if (err instanceof DiffApplyError) continue;
+        throw err;
+      }
+      if (next === base) continue;
+      if (d.path === "theme.json") {
+        try {
+          JSON.parse(next);
+        } catch {
+          continue;
+        }
+      }
+      await kv!.put(devDraftKey(tenant.tenant_id, draftId, d.path), next, {
+        expirationTtl: DEV_DRAFT_TTL_SECONDS,
+      });
+      appliedPaths.push(d.path);
+    }
+    if (appliedPaths.length > 0) {
+      // (Re)issue the signed draft cookie so the middleware overlay serves this draft.
+      const token = await signDevDraftToken(
+        secret!,
+        tenant.tenant_id,
+        draftId,
+        DEV_DRAFT_TTL_SECONDS,
+        nowSeconds,
+      );
+      context.cookies.set(DEV_DRAFT_COOKIE, token, {
+        httpOnly: true,
+        secure: true,
+        sameSite: "lax",
+        path: "/",
+        maxAge: DEV_DRAFT_TTL_SECONDS,
+      });
+    }
+  }
+
+  return json({
+    ok: true,
+    ...result,
+    // True when the draft landed and the live preview will show it on reload.
+    applied: appliedPaths.length > 0,
+    appliedPaths,
+  });
+}

package/apps/storefront/src/pages/api/csp-report.ts

@@ -0,0 +1,25 @@
+/**
+ * CSP violation collector (enables the report-only → enforce
+ * rollout). Browsers POST violation reports here (via `report-to` /
+ * `report-uri`); we log them so platform + tenant-script CSP violations surface
+ * before we flip the policy from Report-Only to enforcing. Returns 204.
+ *
+ * Phase 1: log to the worker console. A later iteration can forward to an
+ * analytics/observability sink.
+ */
+import type { APIRoute } from "astro";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.text();
+    if (body) {
+      // Reports can be `application/csp-report` or `application/reports+json`.
+      console.warn("[csp-report]", body.slice(0, 4000));
+    }
+  } catch {
+    /* never fail a report submission */
+  }
+  return new Response(null, { status: 204 });
+};

package/apps/storefront/src/pages/api/dashboard/enter-vendor.ts

@@ -0,0 +1,124 @@
+/**
+ * POST /api/dashboard/enter-vendor { vendorAppDomain } — the ToT-STAFF admission
+ * endpoint (#8425 staff access). Phase 2 of two-phase admission: on the staff
+ * viewer explicitly selecting a searched vendor, tot20 writes the server-side
+ * AUDIT row and returns the staffRoles-scoped capability; we then stamp a
+ * short-lived {@link StaffSelection} on the session and admit the viewer to
+ * `/dashboard/<appDomain>` scoped to that capability.
+ *
+ * AUTHORIZATION — two independent axes:
+ *   NEAR (this endpoint): a valid `tot_session` carrying ToT-STAFF scope
+ *     (`staff[]` non-empty). No session → 401; no staff scope → 403.
+ *   FAR (tot20): `/clients/staffVendorAccess`, operator-authed as storefront,
+ *     presenting a storefront-signed staff broker assertion in the
+ *     `X-ToT-Broker-Assertion` header (minted from the verified session email).
+ *     tot20 verifies it, re-checks staff scope from its `sub`, scopes the capability,
+ *     and writes the audit row — it is the authority. No plaintext email on the wire.
+ *
+ * The staff selection is a DISTINCT access path from `tenants[]`: we NEVER
+ * synthesize a membership. The dashboard guard + login gate consult the marker
+ * separately (see tenantSelection.staffAdmits / loginGate.sessionAdmitsHost).
+ */
+import type { APIContext } from "astro";
+import { readViewerSession, getSessionMutationHandle } from "@/lib/auth/route";
+import { updateSession } from "@/lib/auth/session";
+import { isStaffSession, buildStaffSelection } from "@/lib/dashboard/staffAdmission";
+import {
+  createStaffVendorAccessClient,
+  staffAccessHttpStatus,
+  StaffVendorAccessClientError,
+} from "@/lib/dashboard/staffVendorAccess";
+import { mintBrokerAssertion, BrokerAssertionError } from "@/lib/auth/brokerAssertion";
+
+export const prerender = false;
+
+/** JSON response with no-store (staff access state must never be edge-cached). */
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const session = await readViewerSession(context);
+  if (!session) return json({ error: "not signed in" }, 401);
+  if (!isStaffSession(session)) {
+    return json({ error: "staff access required", reason: "notStaff" }, 403);
+  }
+
+  let body: { vendorAppDomain?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const vendorAppDomain =
+    typeof body.vendorAppDomain === "string" ? body.vendorAppDomain.trim() : "";
+  if (!vendorAppDomain) return json({ error: "vendorAppDomain is required" }, 400);
+
+  let client;
+  try {
+    client = await createStaffVendorAccessClient();
+  } catch (err) {
+    if (err instanceof StaffVendorAccessClientError) {
+      return json({ error: "staff-access integration not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // #8453 `staff-invite-proof-via-broker`: prove the staff actor with a fresh
+  // storefront-signed assertion minted from the VERIFIED session email. Fail closed
+  // (503) if the signing key is unconfigured.
+  let brokerAssertion: string;
+  try {
+    brokerAssertion = await mintBrokerAssertion(session.email);
+  } catch (err) {
+    if (err instanceof BrokerAssertionError) {
+      return json({ error: "staff-proof signing not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // FAR authority: tot20 verifies the assertion, derives the staff actor, scopes the
+  // capability, and writes the audit row. We admit ONLY on its ok.
+  const result = await client.grantStaffAccess(brokerAssertion, vendorAppDomain);
+  if (!result.ok) {
+    return json(
+      { error: result.message, reason: result.reason, code: result.code },
+      staffAccessHttpStatus(result.reason, result.status),
+    );
+  }
+
+  // Stamp the distinct staff-selection marker on the session (short-lived, scoped
+  // to the returned capability). Never a tenants[] entry.
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const selection = buildStaffSelection({
+    resource: vendorAppDomain,
+    capability: result.capability,
+    nowSeconds,
+  });
+  const handle = await getSessionMutationHandle(context);
+  if (!handle) {
+    // No SESSION KV / no cookie (e.g. plain `astro dev`) — the audit row is
+    // written but we can't persist the marker. Fail closed so the viewer isn't
+    // told they're admitted when the guard can't see it.
+    return json({ error: "session store unavailable; cannot persist admission" }, 503);
+  }
+  const updated = await updateSession(
+    handle.store,
+    handle.id,
+    (rec) => ({ ...rec, staffSelection: selection }),
+    nowSeconds,
+  );
+  if (!updated) {
+    return json({ error: "session expired; sign in again" }, 401);
+  }
+
+  return json({
+    ok: true,
+    appDomain: vendorAppDomain,
+    capability: result.capability,
+    redirect: `/dashboard/${encodeURIComponent(vendorAppDomain)}`,
+  });
+}

package/apps/storefront/src/pages/api/dashboard/vendor-search.ts

@@ -0,0 +1,120 @@
+/**
+ * GET|POST /api/dashboard/vendor-search?q=<prefix> — the ToT-STAFF vendor search
+ * proxy (#8425 staff access). Phase 1 of two-phase staff admission: a staff viewer
+ * finds a vendor by prefix; there is no silent access to every host.
+ *
+ * AUTHORIZATION — two independent axes:
+ *   NEAR (this endpoint): a valid `tot_session` that carries ToT-STAFF scope
+ *     (`staff[]` non-empty). No session → 401; a session without staff scope →
+ *     403 (a plain member has nothing to search across — they use their picker).
+ *   FAR (tot20): storefront calls `/clients/vendorSearch` as its OWN operator
+ *     identity, presenting a storefront-signed staff broker assertion in the
+ *     `X-ToT-Broker-Assertion` header (minted from the verified session email);
+ *     tot20 verifies it, derives the staff actor from its `sub`, and scopes results
+ *     to that user's staffRoles. No spoofable plaintext email crosses the wire.
+ *
+ * GET reads `q` (+ optional `limit`) from the query; POST reads them from a JSON
+ * body — the autocomplete client uses GET, but POST is accepted so a no-JS/form
+ * path works too. Returns `{ vendors: [{ appDomain, displayName }] }`.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { isStaffSession } from "@/lib/dashboard/staffAdmission";
+import {
+  createStaffVendorAccessClient,
+  staffAccessHttpStatus,
+  StaffVendorAccessClientError,
+} from "@/lib/dashboard/staffVendorAccess";
+import { mintBrokerAssertion, BrokerAssertionError } from "@/lib/auth/brokerAssertion";
+import {
+  parseVendorQuery,
+  ANCHORED_FETCH_LIMIT,
+  ANCHORED_DISPLAY_LIMIT,
+} from "@/lib/dashboard/vendorQuery";
+
+export const prerender = false;
+
+/** JSON response with no-store (staff access state must never be edge-cached). */
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+async function handle(context: APIContext, q: string, limit: number | undefined): Promise<Response> {
+  const session = await readViewerSession(context);
+  if (!session) return json({ error: "not signed in" }, 401);
+  if (!isStaffSession(session)) {
+    return json({ error: "staff access required", reason: "notStaff" }, 403);
+  }
+
+  let client;
+  try {
+    client = await createStaffVendorAccessClient();
+  } catch (err) {
+    if (err instanceof StaffVendorAccessClientError) {
+      return json({ error: "staff-access integration not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // #8453 `staff-invite-proof-via-broker`: prove the staff actor with a fresh
+  // storefront-signed assertion minted from the VERIFIED session email — tot20
+  // derives the actor + scopes results from it. Fail closed (503) if unconfigured.
+  let brokerAssertion: string;
+  try {
+    brokerAssertion = await mintBrokerAssertion(session.email);
+  } catch (err) {
+    if (err instanceof BrokerAssertionError) {
+      return json({ error: "staff-proof signing not configured" }, 503);
+    }
+    throw err;
+  }
+
+  // Anchor syntax (^prefix / suffix$ / ^exact$) narrows tot20's substring search.
+  // Send the anchor-stripped CORE term upstream (with a widened cap so the exact hit
+  // is in the set), then post-filter by the anchor against appDomain. A plain query
+  // is unchanged: sent as-is, no post-filter. See @/lib/dashboard/vendorQuery.
+  const parsed = parseVendorQuery(q);
+  const upstreamQuery = parsed.anchored ? parsed.core : q;
+  const upstreamLimit = parsed.anchored ? ANCHORED_FETCH_LIMIT : limit;
+
+  const result = await client.searchVendors(brokerAssertion, upstreamQuery, upstreamLimit);
+  if (!result.ok) {
+    return json(
+      { error: result.message, reason: result.reason, code: result.code },
+      staffAccessHttpStatus(result.reason, result.status),
+    );
+  }
+  const vendors = parsed.anchored
+    ? result.vendors
+        .filter((v) => parsed.matches(v.appDomain))
+        .slice(0, limit && limit > 0 ? limit : ANCHORED_DISPLAY_LIMIT)
+    : result.vendors;
+  return json({ vendors });
+}
+
+function parseLimit(raw: string | null | undefined): number | undefined {
+  if (raw == null || raw === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const url = new URL(context.request.url);
+  const q = (url.searchParams.get("q") ?? "").trim();
+  return handle(context, q, parseLimit(url.searchParams.get("limit")));
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  let body: { q?: unknown; limit?: unknown };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  const q = typeof body.q === "string" ? body.q.trim() : "";
+  const limit = typeof body.limit === "number" ? body.limit : undefined;
+  return handle(context, q, limit);
+}

package/apps/storefront/src/pages/api/dev/activity.ts

@@ -0,0 +1,124 @@
+/**
+ * GET/POST /api/dev/activity — the hosted /dev panel's file-level activity
+ * feed (local→hosted activity bridge). See handoff
+ * 2026-07-14-hosted-dev-activity-bridge-and-stepper.
+ *
+ * GET: the signed-in developer's own browser polls this (same capability gate
+ * as every other /dev route) to render the activity log and feed the Step-2
+ * gate's completion signal. POLL, not a held-open stream — Cloudflare Workers
+ * are stateless per request, so a poll means a Worker redeploy mid-session
+ * needs no reconnect logic on either side.
+ *
+ * POST: the developer's LOCAL dev-loop process reports one file save,
+ * authorized by the opaque bearer minted alongside their cli-signin-code
+ * paste (lib/dev/activityIngestToken.ts) — NOT the browser session cookie,
+ * since the local process has no cookie.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { readKv } from "@/lib/env";
+import { resolvePreviewTenant } from "@/config/previewTenantLookup";
+import { verifyActivityIngestToken } from "@/lib/dev/activityIngestToken";
+import {
+  appendActivity,
+  readActivity,
+  describeActivity,
+  type ActivityEvent,
+  type ActivityEventKind,
+} from "@/lib/dev/activityStore";
+import { readRuntime, writeRuntime, shapeRuntime, toRuntimeView } from "@/lib/dev/runtimeStore";
+
+export const prerender = false;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const session = await readViewerSession({ cookies: context.cookies });
+  if (!session) return json({ error: "sign in required" }, 401);
+  if (!session.capability || session.capability === "none") {
+    return json({ error: "no developer capability on this account" }, 403);
+  }
+
+  // Same tenant resolution every other /dev route uses — the session's own store,
+  // never caller input.
+  const wanted = (session.tenants?.[0]?.resource ?? session.resource ?? "").toLowerCase();
+  const tenant = wanted ? await resolvePreviewTenant(wanted) : null;
+  if (!tenant) return json({ error: "no store linked to this account" }, 403);
+
+  const kv = await readKv("TENANT_CACHE");
+  const events = kv ? await readActivity(kv, tenant.tenant_id) : [];
+  // The LIVE local-dev runtime (latest heartbeat), separate from the file-save
+  // feed — the cockpit renders it as a clickable local link + CLI version, with
+  // `live` computed server-side so a skewed local clock can't fake liveness.
+  const runtime = kv ? await readRuntime(kv, tenant.tenant_id) : null;
+  return json({
+    events: events.map((e) => ({ ...e, description: describeActivity(e.file, e.event) })),
+    runtime: runtime ? toRuntimeView(runtime) : null,
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const auth = context.request.headers.get("authorization") || "";
+  const m = /^Bearer\s+(.+)$/i.exec(auth);
+  if (!m) return json({ error: "missing bearer token" }, 401);
+
+  const sessionKv = await readKv("SESSION");
+  if (!sessionKv) return json({ error: "activity bridge not configured" }, 503);
+  const claims = await verifyActivityIngestToken(sessionKv, m[1] ?? "");
+  if (!claims) return json({ error: "invalid or expired token" }, 401);
+
+  let body: {
+    file?: unknown;
+    event?: unknown;
+    at?: unknown;
+    cliVersion?: unknown;
+    runnerVersion?: unknown;
+    url?: unknown;
+  };
+  try {
+    body = (await context.request.json()) as typeof body;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  // The token's own bound tenant, never a caller-supplied one — a stolen/expired
+  // token can't be redirected at a different vendor's runtime/activity feed.
+  const tenant = await resolvePreviewTenant(claims.tenant.toLowerCase());
+  if (!tenant) return json({ error: "no store linked to this token" }, 403);
+  const tenantCache = await readKv("TENANT_CACHE");
+
+  // Heartbeat: latest-wins local-dev runtime (CLI version + live localhost URL),
+  // stored SEPARATELY from the file-save ring buffer. Not a file event, so it
+  // takes no `file`; liveness is stamped from the SERVER clock (aliveAt), never
+  // the client's `at`.
+  if (body.event === "heartbeat") {
+    if (!tenantCache) return json({ ok: true, stored: false }); // no KV in this runtime (dev)
+    await writeRuntime(tenantCache, tenant.tenant_id, shapeRuntime(body, Date.now()));
+    return json({ ok: true, stored: true, kind: "runtime" });
+  }
+
+  const isUp = body.event === "up";
+  const file = typeof body.file === "string" ? body.file : "";
+  if (!file && !isUp) return json({ error: "file is required" }, 400);
+  // A file-relative path never needs to be long; cap it so a misbehaving or
+  // hostile bridge-token holder can't inflate the per-tenant KV ring-buffer
+  // entry toward KV's per-value size limit.
+  if (file.length > 512) return json({ error: "file path too long" }, 400);
+  const event: ActivityEventKind = isUp
+    ? "up"
+    : body.event === "add" || body.event === "unlink"
+      ? body.event
+      : "change";
+  const at = typeof body.at === "number" && Number.isFinite(body.at) ? body.at : Date.now();
+
+  if (!tenantCache) return json({ ok: true, stored: false }); // no KV in this runtime (dev) — accepted, not stored
+
+  const ev: ActivityEvent = { file, event, at };
+  await appendActivity(tenantCache, tenant.tenant_id, ev);
+  return json({ ok: true, stored: true });
+}

package/apps/storefront/src/pages/api/dev/cli-signin-code.ts

@@ -0,0 +1,73 @@
+/**
+ * POST /api/dev/cli-signin-code — mint a browserless CLI sign-in command for the
+ * SIGNED-IN developer (DevAccess #8425). The /dev getting-started page calls this to
+ * render a copyable `tot login --code <token>` so the developer's terminal signs in with
+ * no second browser round-trip and no OTP.
+ *
+ * AUTHORIZATION: the viewer's own session (the `tot_session` cookie). 401 if not signed
+ * in, 403 if the session carries no developer capability (nothing to sign a CLI into).
+ * The minted-for email is the VERIFIED session email — NEVER read from the body — so a
+ * developer can only mint a code for themselves.
+ *
+ * TENANT-SCOPED CODE (roadtoa3 postmortem, 2026-07-12): the mint also carries the
+ * developer's OWN tenant (their invite's vendor, the same resolution /dev renders with —
+ * first membership, else the session resource; never client input). The MCP stores it
+ * with the code so `tot login --code` lands the terminal ALREADY SCOPED to that vendor —
+ * `tot start` goes straight to their store's source, no client_list round-trip, no
+ * "no stores you can build on yet". See handoff
+ * `2026-07-12-tot-mcp-cli-code-tenant-binding` for the MCP half (store tenant with the
+ * code + write the durable subject-capability binding at mint).
+ *
+ * The response `command` CONTAINS the single-use token; it is returned only to this
+ * authenticated developer's own browser and is never logged server-side.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { mintCliSignInCommand } from "@/lib/dev/cliSignInCode";
+import { mintActivityIngestToken } from "@/lib/dev/activityIngestToken";
+import { readKv } from "@/lib/env";
+
+export const prerender = false;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const session = await readViewerSession(context);
+  if (!session) return json({ error: "not signed in" }, 401);
+  // Same gate the /dev page applies (hasStoreAccess): a real developer capability. A
+  // no-capability session has no scoped CLI session to mint.
+  if (!session.capability || session.capability === "none") {
+    return json({ error: "no developer access on this session", reason: "notEligible" }, 403);
+  }
+
+  // The developer's own vendor — the tenant their invite granted (same resolution /dev
+  // renders with). Rides with the code so the CLI session lands on this store directly.
+  const tenant = session.tenants?.[0]?.resource ?? session.resource ?? null;
+
+  // Mint the local→hosted activity-bridge credential alongside the CLI code (best
+  // effort — a runtime without the SESSION KV binding just omits it, and the local
+  // loop runs with no hosted signal, same as before this existed).
+  let activityBridge: { token: string; url: string } | null = null;
+  const sessionKv = await readKv("SESSION");
+  if (sessionKv && tenant) {
+    const { token } = await mintActivityIngestToken(sessionKv, {
+      email: session.email,
+      tenant,
+      capability: session.capability,
+    });
+    activityBridge = { token, url: context.url.origin };
+  }
+
+  const result = await mintCliSignInCommand(session.email, tenant, {}, activityBridge);
+  if (!result.ok) {
+    // 503 = seam not configured / MCP route unmounted; 502 = MCP fault. Surface neither
+    // the token nor internal detail beyond a terse reason.
+    return json({ error: "CLI sign-in code unavailable", reason: result.reason }, result.status);
+  }
+  return json({ command: result.command, expiresAt: result.expiresAt });
+}