@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -0,0 +1,213 @@
+/**
+ * Drizzle schema — the source of truth for `STOREFRONT_APPS_DB` *migration
+ * generation* (ADR-0002). Split out of `schema.ts` (which now covers only the
+ * catalog + customization tables on `CATALOG_DB`): these tables are the
+ * storefront-apps registry/webhooks/orders spine and belong to a DEDICATED
+ * D1, never the catalog.
+ *
+ * `drizzle-kit generate --config drizzle.config.apps.ts` diffs this into
+ * numbered SQL under `migrations-apps/`, applied by `wrangler d1 migrations
+ * apply STOREFRONT_APPS_DB`.
+ */
+import { sqliteTable, text, integer, real, index, uniqueIndex, primaryKey } from "drizzle-orm/sqlite-core";
+
+// --- Private Apps registry (PrivateApps epic, D2) ----------------------------
+// One install per (app, tenant, env). `installId` is the future JWT `sub`.
+// Append-only `app_audit_log` is never pruned by the service layer.
+export const appInstalls = sqliteTable(
+  "app_installs",
+  {
+    installId: text("install_id").primaryKey(),
+    appId: text("app_id").notNull(),
+    appVersion: text("app_version").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    env: text("env").notNull(),
+    status: text("status").notNull().default("active"),
+    scopes: text("scopes").notNull().default("[]"),
+    manifest: text("manifest").notNull(),
+    webhookEndpoint: text("webhook_endpoint"),
+    widgetPlacements: text("widget_placements").notNull().default("[]"),
+    installActor: text("install_actor").notNull(),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    uqAppInstallsTenantEnv: uniqueIndex("uq_app_installs_app_tenant_env").on(
+      t.appId,
+      t.tenantId,
+      t.env,
+    ),
+    idxAppInstallsTenant: index("idx_app_installs_tenant").on(t.tenantId),
+  }),
+);
+
+// Server-issued client-credentials for one install. The secret is never stored
+// in plaintext — only its sha256 hash (@tot/public-runtime's `sha256Hex`).
+export const appCredentials = sqliteTable("app_credentials", {
+  installId: text("install_id").primaryKey(),
+  clientId: text("client_id").notNull().unique(),
+  secretHash: text("secret_hash").notNull(),
+  secretCreatedAt: text("secret_created_at").notNull(),
+  rotatedAt: text("rotated_at"),
+  jwksKid: text("jwks_kid").notNull(),
+});
+
+// Append-only audit trail. `actor` is an opaque id — never email/PII — and
+// `detail` is redacted JSON (never secret material).
+export const appAuditLog = sqliteTable(
+  "app_audit_log",
+  {
+    id: text("id").primaryKey(),
+    installId: text("install_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    event: text("event").notNull(),
+    actor: text("actor").notNull(),
+    traceId: text("trace_id"),
+    detail: text("detail").notNull().default("{}"),
+    at: text("at").notNull(),
+  },
+  (t) => ({
+    idxAppAuditInstall: index("idx_app_audit_install").on(t.installId),
+  }),
+);
+
+// --- Webhook event spine (PrivateApps epic, D4 Chunk A) ---------------------
+// Immutable event log. `id` is the semantic event id we mint — distinct from
+// any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).
+export const webhookEvents = sqliteTable("webhook_events", {
+  id: text("id").primaryKey(),
+  tenantId: text("tenant_id").notNull(),
+  topic: text("topic").notNull(),
+  dataschemaVersion: text("dataschema_version").notNull(),
+  payload: text("payload").notNull(),
+  createdAt: text("created_at").notNull(),
+});
+
+// One row per (event × target install). `deliveryId` is the on-wire
+// CloudEvents `id` — stable across retries/replays so receivers can dedupe —
+// which is why it, not `eventId`, is the primary key here.
+export const webhookDeliveries = sqliteTable(
+  "webhook_deliveries",
+  {
+    deliveryId: text("delivery_id").primaryKey(),
+    // FK to webhookEvents.id, enforced in code only (no SQL FK — repo convention).
+    eventId: text("event_id").notNull(),
+    installId: text("install_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    topic: text("topic").notNull(),
+    state: text("state").notNull().default("pending"),
+    attempts: integer("attempts").notNull().default(0),
+    lastStatus: integer("last_status"),
+    lastErrorClass: text("last_error_class"),
+    lastTraceId: text("last_trace_id"),
+    nextAttemptAt: text("next_attempt_at"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    idxWebhookDeliveriesInstall: index("idx_webhook_deliveries_install").on(t.installId),
+    idxWebhookDeliveriesDue: index("idx_webhook_deliveries_due").on(t.state, t.nextAttemptAt),
+  }),
+);
+
+// Append-only per-HTTP-attempt log, never pruned by the service layer.
+export const webhookDeliveryAttempts = sqliteTable(
+  "webhook_delivery_attempts",
+  {
+    id: text("id").primaryKey(),
+    deliveryId: text("delivery_id").notNull(),
+    attemptNo: integer("attempt_no").notNull(),
+    startedAt: text("started_at").notNull(),
+    durationMs: integer("duration_ms"),
+    httpStatus: integer("http_status"),
+    errorClass: text("error_class"),
+    traceId: text("trace_id"),
+  },
+  (t) => ({
+    idxWebhookDeliveryAttemptsDelivery: index("idx_webhook_delivery_attempts_delivery").on(t.deliveryId),
+  }),
+);
+
+// Rollup, one row per install — mirrors the openapi `InstallHealth` shape.
+// `recentTraceIds` is a capped (~10) JSON array, newest first.
+export const webhookInstallHealth = sqliteTable("webhook_install_health", {
+  installId: text("install_id").primaryKey(),
+  lastSuccessAt: text("last_success_at"),
+  failureStreak: integer("failure_streak").notNull().default(0),
+  dlqCount: integer("dlq_count").notNull().default(0),
+  lastStatus: integer("last_status"),
+  lastErrorClass: text("last_error_class"),
+  recentTraceIds: text("recent_trace_ids").notNull().default("[]"),
+  updatedAt: text("updated_at").notNull(),
+});
+
+// --- Order ingestion (PrivateApps epic, D6 Chunk A) --------------------------
+// The read-model `ordersStore.ts` diffs incoming Foxy orders against (created
+// → fulfilled transitions, for a later chunk's event emission) and that the
+// attribution route (also later) reads from for its cross-tenant ownership
+// check. `(tenantId, externalOrderId)` is the composite PK — same "no
+// synthetic id, the natural key IS the key" style as `customizationVersions`
+// (schema.ts) — no SQL FK to `appAttributions.orderId` (repo convention — code-only).
+export const orders = sqliteTable(
+  "orders",
+  {
+    tenantId: text("tenant_id").notNull(),
+    // Foxy's own transaction id — never generated here.
+    externalOrderId: text("external_order_id").notNull(),
+    env: text("env").notNull(),
+    status: text("status").notNull(),
+    currency: text("currency").notNull(),
+    total: real("total").notNull().default(0),
+    subtotal: real("subtotal"),
+    // Opaque, stable per (tenant, app-install) — see `orders/customerHash.ts`. Never raw PII.
+    customerHash: text("customer_hash"),
+    lineItems: text("line_items").notNull().default("[]"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.externalOrderId] }),
+    idxOrdersTenant: index("idx_orders_tenant").on(t.tenantId),
+  }),
+);
+
+// First idempotency ledger in the codebase (D6 Chunk A) — keyed per
+// `(installId, idempotencyKey)` so a retried write (e.g. attribution POST)
+// replays the stored `responseBody` instead of re-applying the mutation.
+// `bodyHash` (sha256 of the canonical request body) lets a caller re-sending
+// the SAME key with a DIFFERENT body be rejected rather than silently replayed.
+export const idempotencyKeys = sqliteTable(
+  "idempotency_keys",
+  {
+    installId: text("install_id").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    bodyHash: text("body_hash").notNull(),
+    responseBody: text("response_body").notNull(),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({ pk: primaryKey({ columns: [t.installId, t.idempotencyKey] }) }),
+);
+
+// App-owned attribution/commission records (`attribution:write`, D6 — later
+// chunk owns the route). `orderId` references `orders.externalOrderId` in code
+// only (no SQL FK, repo convention); the route chunk enforces the cross-tenant
+// ownership check the contract requires before ever writing a row here.
+export const appAttributions = sqliteTable(
+  "app_attributions",
+  {
+    installId: text("install_id").notNull(),
+    attributionId: text("attribution_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    orderId: text("order_id").notNull(),
+    campaign: text("campaign"),
+    referralCode: text("referral_code"),
+    commissionAmount: real("commission_amount"),
+    commissionCurrency: text("commission_currency"),
+    customerHash: text("customer_hash"),
+    recordedAt: text("recorded_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.installId, t.attributionId] }),
+    idxAppAttributionsTenantOrder: index("idx_app_attributions_tenant_order").on(t.tenantId, t.orderId),
+  }),
+);

package/apps/storefront/src/lib/dev/apiBase.ts

@@ -8,7 +8,13 @@
  *
  * See decision `architecture-environment-aware-cockpit`
  * (workstream tot-lime-cloud-dev-cockpit).
+ *
+ * `basePath` is the request's tenant prefix ("" host-routed, "/<tenant>" path-routed).
+ * The HOSTED routes are tenant-scoped through the middleware's host/path resolution, so
+ * a `/<tenant>/cockpit` render must call `/<tenant>/api/dev/*` for `locals.tenant` to be
+ * that store on the API request (not the generic home host). The local `/__tot/*` dev
+ * plugins are single-tenant and take no prefix.
  */
-export function resolveDevApiBase(isDev: boolean): string {
-  return isDev ? "/__tot" : "/api/dev";
+export function resolveDevApiBase(isDev: boolean, basePath = ""): string {
+  return isDev ? "/__tot" : `${basePath}/api/dev`;
 }

package/apps/storefront/src/lib/dev/cliSignInCode.ts

@@ -1,133 +1,81 @@
 /**
  * Mint a browserless "get going" command for an ALREADY-AUTHENTICATED developer — the
  * second half of the invite story. The developer accepted the magic link (OTP-free web
- * sign-in) and landed on /dev; this hands them a single-copy, TWO-LINE paste — line 1 signs
- * the terminal in with the one-time code, line 2 runs `start` (checkout → run → open the
- * browser on the working site) — so they go from web sign-in to a running store with NO
- * second browser round-trip and NO OTP.
+ * sign-in) and landed on /cockpit; this hands them a single-copy, THREE-LINE paste — line 1
+ * installs the CLI, line 2 signs the terminal in, line 3 runs `start` (checkout → run →
+ * open the browser on the working site) — so they go from web sign-in to a running store
+ * with NO second browser round-trip and NO OTP.
  *
- * The token is minted by the MCP (POST /api/internal/dev-access/cli-signin-code), bound
- * to the MCP's OWN audience, so it's redeemable only by that same MCP's /oauth/redeem-code
- * — exactly what `tot login --code` does. We reuse the SAME seam as the app-binding writer:
- *   - MCP host  ← the ORIGIN of MCP_APP_BINDING_URL (one source, so the mint host and the
- *                 --mcp host the developer runs are provably the same MCP tier).
- *   - auth      ← header x-mcp-service-secret: MCP_SERVICE_SHARED_SECRET (the storefront
- *                 never holds the MCP's core credential).
+ * The paste carries a NON-SECRET rendezvous handle minted by the MCP's
+ * POST /oauth/device/rendezvous (RFC 8628 rendezvous), authenticated by the storefront's
+ * SIGNED CLIENT ASSERTION (private_key_jwt) — NOT a shared secret. `tot login --code <handle>`
+ * then ATTACHES the terminal's own PKCE key and the developer approves it by fingerprint
+ * back here in the cockpit (see the /api/dev/cli-signin-{status,approve} routes). The handle
+ * is not a credential: intercepting it grants nothing without the terminal's private key,
+ * and the developer must still approve the matching fingerprint.
  *
- * Line 1 appends `--mcp <origin>` ONLY when the MCP is not the CLI's built-in prod default —
- * on prod the shortest form (`npx @tokenoftrust/cli login --code <token>`) is emitted.
+ * Line 2 appends `--mcp <origin>` ONLY when the MCP is not the CLI's built-in prod default —
+ * on prod the shortest form is emitted.
  *
  * `activityBridge` (optional) piggybacks the local→hosted activity-bridge credential
- * (see lib/dev/activityIngestToken.ts) onto the SAME pasted line as two extra `tot
- * login` flags — no second browser round-trip, no MCP-repo change. `tot login`
- * caches it in ~/.tot/credentials.json, and `tot dev` threads it into the spawned
- * dev-loop process so it can report file saves to the developer's own hosted /dev
- * panel. Omitted entirely when the caller has no SESSION KV to mint against — the
- * local loop then simply runs with no hosted signal, same as today.
+ * (see lib/dev/activityIngestToken.ts) onto the SAME pasted line as two extra `tot login`
+ * flags — no second browser round-trip. Omitted entirely when the caller has no SESSION KV
+ * to mint against — the local loop then simply runs with no hosted signal.
  */
 import { readEnv } from "@/lib/env";
 import { redactEmailForHint } from "@/lib/privacy/emailHint";
+import { createRendezvous, type RendezvousDeps } from "@/lib/dev/rendezvousBroker";
 
 // The CLI's built-in default MCP (packages/cli login.mjs DEFAULT_MCP_URL). When the derived
 // MCP origin equals this, --mcp is redundant noise, so we omit it.
 const PROD_MCP_ORIGIN = "https://mcp.tokenoftrust.com";
 
-export interface HttpTransport {
-  post(
-    url: string,
-    headers: Record<string, string>,
-    body: unknown,
-  ): Promise<{ status: number; json(): Promise<unknown> }>;
-}
-
-export class FetchHttpTransport implements HttpTransport {
-  async post(url: string, headers: Record<string, string>, body: unknown) {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", ...headers },
-      body: JSON.stringify(body),
-    });
-    return { status: res.status, json: () => res.json() };
-  }
-}
-
 export type CliSignInCodeResult =
-  | { ok: true; command: string; expiresAt: string | null }
+  | { ok: true; command: string; rendezvousCode: string; expiresAt: string | null }
   | { ok: false; status: 502 | 503; reason: string };
 
 /**
  * Mint the ready-to-paste CLI sign-in command for `email`. The caller MUST pass the
  * VERIFIED session email (never a client-supplied value) — a signed-in developer can only
- * mint a code for themselves. `tenant` (the developer's own vendor, session-derived) is
- * threaded to the MCP so the code is TENANT-SCOPED: the redeemed CLI session lands
- * already bound to that store (no client_list round-trip; see the route header). Older
- * MCP deploys ignore the extra field — additive, never breaking. Fail-closed: an
- * unconfigured seam (no URL/secret) or a 401 (MCP route unmounted / bad secret) is a 503;
- * any other non-2xx / transport / parse fault is a 502. Never throws.
+ * start a rendezvous for themselves. `tenant` (the developer's own vendor, session-derived)
+ * is threaded so the CLI session lands already bound to that store (no client_list
+ * round-trip). Fail-closed: an unconfigured seam or a 401/403 (assertion rejected / client
+ * not entitled to broker) is a 503; any other fault is a 502. Never throws.
+ *
+ * Returns the pasteable `command` AND the `rendezvousCode` — the cockpit polls the latter
+ * for a terminal attaching, then shows the fingerprint approval prompt.
  */
 export async function mintCliSignInCommand(
   email: string,
   tenant: string | null = null,
-  deps: { transport?: HttpTransport } = {},
+  deps: RendezvousDeps = {},
   activityBridge: { token: string; url: string } | null = null,
   traceId: string | null = null,
 ): Promise<CliSignInCodeResult> {
-  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
-  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
-  if (!bindingUrl || !secret) {
+  // MCP_BASE_URL is the MCP tier this storefront's client assertion is registered
+  // with (where the rendezvous is created), so the pasted `--mcp` host MUST match it
+  // — the terminal redeems the rendezvous against that same MCP. (The retired shim
+  // used MCP_APP_BINDING_URL, which may point at a different tier.)
+  const baseUrl = await readEnv("MCP_BASE_URL");
+  if (!baseUrl) {
     return { ok: false, status: 503, reason: "not-configured" };
   }
   let mcpOrigin: string;
-  let endpoint: string;
   try {
-    mcpOrigin = new URL(bindingUrl).origin;
-    // Mounted OUTSIDE /api on the MCP (the /api surface there is session-guarded); use the
-    // origin of MCP_APP_BINDING_URL, not its full path.
-    endpoint = `${mcpOrigin}/internal/dev-access/cli-signin-code`;
+    mcpOrigin = new URL(baseUrl).origin;
   } catch {
     return { ok: false, status: 503, reason: "bad-mcp-url" };
   }
 
-  const transport = deps.transport ?? new FetchHttpTransport();
-  let res: { status: number; json(): Promise<unknown> };
-  try {
-    res = await transport.post(
-      endpoint,
-      { "x-mcp-service-secret": secret },
-      {
-        email: email.toLowerCase(),
-        ...(tenant ? { tenant: tenant.toLowerCase() } : {}),
-      },
-    );
-  } catch (cause) {
-    return {
-      ok: false,
-      status: 502,
-      reason: "mcp request failed: " + (cause instanceof Error ? cause.message : String(cause)),
-    };
-  }
-
-  if (res.status < 200 || res.status >= 300) {
-    // 401 = MCP route unmounted or bad shared secret → treat as not-configured (503).
-    return {
-      ok: false,
-      status: res.status === 401 ? 503 : 502,
-      reason: `mcp cli-signin-code returned status ${res.status}`,
-    };
-  }
-
-  let payload: { token?: string; expiresAt?: string };
-  try {
-    payload = (await res.json()) as typeof payload;
-  } catch {
-    return { ok: false, status: 502, reason: "unparseable mcp response" };
-  }
-  if (!payload.token) {
-    return { ok: false, status: 502, reason: "mcp returned no token" };
+  const created = await createRendezvous(email, tenant, deps);
+  if (!created.ok) {
+    // 503 = seam not configured / assertion rejected / not entitled on this env;
+    // 502 = MCP fault. Surface neither internal detail nor any token.
+    return { ok: false, status: created.status, reason: created.reason };
   }
 
   const mcpFlag = mcpOrigin === PROD_MCP_ORIGIN ? "" : ` --mcp ${mcpOrigin}`;
-  // Display-only recovery hint for a stale one-use code. If redemption fails before
+  // Display-only recovery hint for a stale one-use handle. If sign-in fails before
   // anything is cached locally, `tot login` can still send the developer back to
   // cockpit with the right address prefilled.
   const emailHint = redactEmailForHint(email);
@@ -137,38 +85,40 @@ export async function mintCliSignInCommand(
   const activityFlags = activityBridge
     ? ` --activity-token ${activityBridge.token} --activity-url ${activityBridge.url}`
     : "";
-  // The invite→terminal→problem trace id, minted once with this sign-in code and
-  // baked into the activity-ingest-token claims. Emitted here too so `tot login`
-  // records it locally — additive, ignored by older CLI builds. The receiver gets
-  // the SAME id from the ingest-token claims, so runtime/activity writes stamp it.
+  // The invite→terminal→problem trace id, minted once with this rendezvous and baked
+  // into the activity-ingest-token claims. Emitted here too so `tot login` records it
+  // locally — additive, ignored by older CLI builds.
   const traceFlag = traceId ? ` --trace-id ${traceId}` : "";
-  // A single copy → a three-line paste that takes the developer all the way to a running
-  // store, no browser, AND leaves `tot` on their PATH so every later command is a bare
-  // `tot …` (not `npx @tokenoftrust/cli …`):
-  //   1. `npm i -g @tokenoftrust/cli` — install the `tot` command once.
-  //   2. `tot login --code <token>` — sign the terminal in with the single-use code.
-  //   3. `tot start` — checkout + run + open the browser on the working site, reusing the
-  //      session step 2 just cached (so `start` never opens its own sign-in).
-  //
-  // The trailing `&&` chains them: each step runs ONLY if the previous succeeded. In
-  // particular a stale/burned code (single-use, short-TTL) fails step 2 and stops there
-  // with `login`'s cockpit recovery step — it never falls through to `start`'s browser
-  // sign-in (the surprise we're avoiding).
-  // The EXACT version this build was cut alongside — `@tokenoftrust/cli@<version>` — baked
-  // in at build time (astro.config Vite define) so the paste installs precisely the CLI this
-  // cockpit expects, never a floating dist-tag the terminal resolves (which can drift behind
-  // the build; that gap shipped stampless installs). `typeof` guard: the define isn't applied
-  // under vitest, where it falls back to the unpinned spec.
+  // The EXACT version this build was cut alongside — baked in at build time (astro.config
+  // Vite define) so the paste installs precisely the CLI this cockpit expects. `typeof`
+  // guard: the define isn't applied under vitest, where it falls back to the unpinned spec.
   const cliInstallSpec =
     typeof __CLI_INSTALL_SPEC__ !== "undefined" ? __CLI_INSTALL_SPEC__ : "@tokenoftrust/cli";
+  // `hash -r` after the install clears the shell's cached command path so the
+  // just-installed `tot` is the one that runs — without it, a shell that already
+  // resolved an OLDER `tot` (e.g. a stray Homebrew/other-prefix install earlier in
+  // this session) keeps running the stale binary, and `npm i -g` silently updates a
+  // file the shell never consults. Portable across bash/zsh/sh; fish can't run the
+  // `&&` chain anyway. This is what makes the pinned version actually take effect.
+  // A first-line no-op stamping which cockpit build generated this command (short git
+  // SHA — the same one /health reports) + the CLI it pins, so a paste can be matched to
+  // a deploy at a glance (pairs with `tot login`'s runtime version banner). Uses the
+  // `: '…'` null-command form, NOT a `#` comment — interactive zsh doesn't treat `#` as
+  // a comment (no INTERACTIVE_COMMENTS) and errors on it; `: '…'` is a portable no-op.
+  const cockpitBuild = (typeof __GIT_SHA__ !== "undefined" ? __GIT_SHA__ : "unknown").slice(0, 7);
   const command = [
+    `: 'tot setup (cockpit ${cockpitBuild}, ${cliInstallSpec})'`,
     `npm i -g ${cliInstallSpec} &&`,
-    `tot login --code ${payload.token}${emailHintFlag}${mcpFlag}${traceFlag}${activityFlags} &&`,
-    `tot start`,
+    `hash -r &&`,
+    `tot login --code ${created.rendezvousCode}${emailHintFlag}${mcpFlag}${traceFlag}${activityFlags} &&`,
+    // `start` must talk to the SAME MCP the session was minted on — it otherwise defaults
+    // to the prod MCP and won't see a qa session (→ "not signed in" → sample fallback).
+    `tot start${mcpFlag}`,
   ].join("\n");
   return {
     ok: true,
     command,
-    expiresAt: payload.expiresAt ?? null,
+    rendezvousCode: created.rendezvousCode,
+    expiresAt: created.expiresIn != null ? new Date(Date.now() + created.expiresIn * 1000).toISOString() : null,
   };
 }

package/apps/storefront/src/lib/dev/cockpitStore.ts

@@ -0,0 +1,65 @@
+/**
+ * "Which store is this cockpit request about?" — the ONE resolver the hosted
+ * cockpit page, its /api/dev/* routes, and the CLI sign-in-code mint all share, so
+ * they never disagree about the developer's store.
+ *
+ * REGRESSION FIXED (8500 <tenant>/cockpit): the page and the mint used to derive
+ * the store purely from the session's FIRST membership
+ * (`session.tenants?.[0]?.resource ?? session.resource`), ignoring the store the
+ * request URL actually named. An invite to `/<tenantB>/cockpit` therefore rendered —
+ * and minted a `tot login --code … && tot start` for — whatever store happened to be
+ * listed first in the session, "losing track of the store" for any developer who
+ * belongs to more than one.
+ *
+ * Rule: the URL wins WHEN THE VIEWER CAN ACCESS IT. The middleware has already
+ * resolved the request's host/path to `locals.tenant` (the trusted, authenticated
+ * store seam — never client body input), so when that is a SPECIFIC store (not the
+ * public marketing home) and the signed-in developer holds a membership for it (or a
+ * live staff admission), that store is authoritative. Otherwise we fall back to the
+ * session's own first store (the generic-host `/cockpit` case, unchanged), and for an
+ * anonymous viewer to the path store's branding, else the caller-supplied `?tenant=`.
+ *
+ * Access is gated with the SAME primitive (`viewerCanAccess`) the vendor dashboard
+ * uses, so a developer can never steer the mint at a store they don't belong to; a
+ * store they can't access simply falls through to their own.
+ */
+import type { APIContext } from "astro";
+import type { SessionRecord } from "@/lib/auth/session";
+import { PUBLIC_HOME_TENANT_ID } from "@/lib/auth/loginGate";
+import { viewerCanAccess, type StaffAdmission } from "@/lib/dashboard/tenantSelection";
+
+/** The request's host/path-resolved store resource, or "" when it's the marketing home. */
+function pathStoreResource(context: Pick<APIContext, "locals">): string {
+  const t = context.locals?.tenant;
+  if (!t || t.tenant_id === PUBLIC_HOME_TENANT_ID) return "";
+  return (t.appDomain || t.tenant_id || "").toLowerCase();
+}
+
+/**
+ * Resolve the store this cockpit request is scoped to, as a lowercased resource
+ * (appDomain/tenant_id). Empty string when nothing resolves (e.g. anonymous on the
+ * generic host with no `?tenant=`).
+ */
+export function resolveCockpitStoreResource(
+  context: Pick<APIContext, "locals" | "url">,
+  session: SessionRecord | null,
+): string {
+  const pathStore = pathStoreResource(context);
+
+  if (session) {
+    // The URL wins when the signed-in developer can actually access that store.
+    if (pathStore) {
+      const staff: StaffAdmission | undefined = session.staffSelection
+        ? { selection: session.staffSelection, nowSeconds: Math.floor(Date.now() / 1000) }
+        : undefined;
+      if (viewerCanAccess(session.tenants, pathStore, staff)) return pathStore;
+    }
+    // Generic host, or a store the viewer doesn't belong to: their own first store.
+    return (session.tenants?.[0]?.resource ?? session.resource ?? "").toLowerCase();
+  }
+
+  // Anonymous: the path store is just branding (no privileged mint happens), else the
+  // caller-supplied preview hint. Never overrides a signed-in developer (handled above).
+  if (pathStore) return pathStore;
+  return (context.url?.searchParams.get("tenant") ?? "").toLowerCase();
+}

package/apps/storefront/src/lib/dev/previewStatus.ts

@@ -0,0 +1,112 @@
+/**
+ * Read whether a tenant appDomain's store is SET UP — its forge repo is provisioned —
+ * from the credential-free MCP preview-status seam (tot-mcp
+ * GET /internal/preview-status; legacy alias /internal/dev-access/preview-status). The
+ * seam answers `{ tenant, app, repo, provisioned, previewReleased }`.
+ *
+ * This is the cockpit's own small reader — self-contained, mirroring `cliSignInCode.ts`
+ * (same MCP-origin + service-secret seam) rather than importing another cluster's copy,
+ * so the two stay decoupled (the same reason `cliSignInCode` duplicates its transport).
+ * It gates the CLI sign-in-code mint + the /cockpit setup fastpath so a developer whose
+ * store isn't provisioned yet gets an honest "not set up" state instead of a
+ * `tot login --code … && tot start` command that would die at checkout on
+ * "Repo <owner>-main is not provisioned" (James's 2026-07-19 first-run failure).
+ *
+ *   - MCP host  ← the ORIGIN of MCP_APP_BINDING_URL (one source, so this read hits the
+ *                 SAME MCP tier the sign-in-code mint does).
+ *   - auth      ← header x-mcp-service-secret: MCP_SERVICE_SHARED_SECRET.
+ *
+ * Fail-closed but non-blocking by design: an UNCONFIGURED seam (no URL/secret) →
+ * { configured:false } so callers keep today's behavior (no regression); any non-2xx /
+ * transport / parse fault → { configured:true, ok:false } so a caller can distinguish
+ * "definitely not provisioned" (ok + provisioned:false) from "couldn't tell". Never throws.
+ */
+import { readEnv } from "@/lib/env";
+
+export interface HttpGetTransport {
+  get(
+    url: string,
+    headers: Record<string, string>,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+export class FetchGetTransport implements HttpGetTransport {
+  async get(url: string, headers: Record<string, string>) {
+    const res = await fetch(url, { method: "GET", headers });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+export interface TenantPreviewStatus {
+  /** False when the seam isn't wired on this deploy (no URL/secret) — gate inactive. */
+  configured: boolean;
+  /** True only when we got a definitive answer back from the MCP. */
+  ok: boolean;
+  /** The forge repo is provisioned for this owner (checkout/`tot start` can succeed). */
+  provisioned?: boolean;
+  /** A released preview exists. TODAY equals `provisioned`; Track B.3 tightens it. */
+  previewReleased?: boolean;
+  status?: number;
+  reason?: string;
+}
+
+export async function readTenantPreviewStatus(
+  tenant: string | null,
+  deps: { transport?: HttpGetTransport } = {},
+): Promise<TenantPreviewStatus> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret || !tenant) return { configured: false, ok: false };
+
+  let endpoint: string;
+  try {
+    // Mounted OUTSIDE /api on the MCP (its /api surface is session-guarded); use the
+    // ORIGIN of MCP_APP_BINDING_URL, same as the cli-signin-code mint. Canonical path
+    // (namespace-neutral) — the MCP still serves the /internal/dev-access alias too.
+    endpoint = `${new URL(bindingUrl).origin}/internal/preview-status`;
+  } catch {
+    return { configured: false, ok: false, reason: "bad-mcp-url" };
+  }
+
+  const transport = deps.transport ?? new FetchGetTransport();
+  const full = `${endpoint}?tenant=${encodeURIComponent(tenant.toLowerCase())}`;
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.get(full, { "x-mcp-service-secret": secret });
+  } catch (cause) {
+    return {
+      configured: true,
+      ok: false,
+      reason: "mcp request failed: " + (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    return { configured: true, ok: false, status: res.status, reason: `status ${res.status}` };
+  }
+  let payload: unknown;
+  try {
+    payload = await res.json();
+  } catch {
+    return { configured: true, ok: false, status: res.status, reason: "unparseable mcp response" };
+  }
+  const p = (payload ?? {}) as Record<string, unknown>;
+  return {
+    configured: true,
+    ok: true,
+    status: res.status,
+    provisioned: p.provisioned === true,
+    previewReleased: p.previewReleased === true,
+  };
+}
+
+/**
+ * The gate signal shared by /cockpit + the CLI sign-in-code mint: TRUE only when the
+ * seam gave a DEFINITIVE "this store's repo is NOT provisioned" — the exact case where
+ * `tot clone` / `tot start` would die locally on "Repo … is not provisioned". An
+ * unconfigured seam or one that couldn't answer returns FALSE — callers then keep today's
+ * behavior and lean on the CLI's own clean "not set up yet" error as the backstop, rather
+ * than blocking a possibly-fine developer on a transient MCP blip.
+ */
+export function isStoreNotSetUp(status: TenantPreviewStatus): boolean {
+  return status.configured && status.ok && status.provisioned === false;
+}