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

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

@@ -0,0 +1,214 @@
+/**
+ * Per-DEVELOPER "startup obstacle" — the FAILURE half of the local→hosted dev
+ * bridge (v2 §6). Where runtimeStore.ts holds the latest SUCCESSFUL heartbeat and
+ * activityStore.ts the file-save ring buffer, this holds the latest reason a
+ * developer's local `tot start` could NOT come up: a Node-version floor miss, a
+ * missing pnpm, a failed install/clone. The hosted cockpit reads it to turn the
+ * bridge strip into an actionable obstacle card ("This machine is running Node
+ * 20.17 — needs 22.12+; fix: …") instead of spinning forever on "watching…".
+ *
+ * WHY ITS OWN KEY (not folded into the runtime record): an obstacle is PRECISELY
+ * the state where no successful heartbeat exists, so it must never carry an
+ * `aliveAt` that liveness reads — mixing it into the runtime record would flicker
+ * the loop "live". It is its own latest-wins slot, cleared the moment a real
+ * heartbeat lands (writeRuntime → clearObstacle) and on a ?reset.
+ *
+ * SCOPED PER (tenant, developer email), exactly like the runtime record
+ * (commit 0d4bb7d): the obstacle is beaconed with the developer's OWN
+ * activity-ingest token — carried in the setup command's argv — so a machine that
+ * FAILS the Node gate (no session, no MCP, maybe no global `fetch`) can still
+ * report it. The viewer's own GET (their email) reads their own obstacle; a
+ * teammate's failure is theirs.
+ *
+ * REMEDIATION COPY LIVES HERE (server-side), keyed by `kind` — so the fix-it
+ * guidance changes without shipping a new CLI. The CLI reports only a stable,
+ * machine-readable {kind, have, need}; the human sentence is composed here.
+ */
+
+/** The failure modes `tot start` can beacon. Stable machine-readable contract —
+ * the CLI emitter (a bounded follow-up) POSTs one of these; the human copy is
+ * composed server-side in describeObstacle(). */
+export const OBSTACLE_KINDS = [
+  "node-too-old",
+  "pnpm-missing",
+  "install-failed",
+  "clone-failed",
+] as const;
+export type ObstacleKind = (typeof OBSTACLE_KINDS)[number];
+
+/** The latest startup obstacle a developer's local loop reported. */
+export interface DevObstacle {
+  kind: ObstacleKind;
+  /** The version the machine HAS, when the kind carries one (node-too-old). e.g. "20.17.0". */
+  have?: string;
+  /** The version the loop NEEDS, when the beacon knows it. e.g. "22.12.0". */
+  need?: string;
+  /** The `tot` CLI version that reported the obstacle, when carried. */
+  cliVersion?: string;
+  /** Epoch ms the obstacle was reported, stamped by the SERVER at ingest (never
+   * the client `ts` — skew-proof, matching the runtime record's aliveAt). */
+  reportedAt: number;
+}
+
+/** The obstacle as the GET feed exposes it: the stored record PLUS the
+ * server-composed remediation copy the cockpit renders verbatim. */
+export interface DevObstacleView extends DevObstacle {
+  /** Short label for the bridge kicker, e.g. "Node version too old". */
+  title: string;
+  /** One-line human explanation, with have/need interpolated. */
+  message: string;
+  /** The single shell command that fixes it, when there is one (rendered in mono). */
+  fixCommand?: string;
+  /** The instruction around the fix command (or the whole fix, when there is no command). */
+  fixNote: string;
+}
+
+const KEY_PREFIX = "dev-obstacle:";
+/** Match the runtime record's TTL: an obstacle lingers long enough for the
+ * developer to see it after a failed start, then self-expires. A real heartbeat
+ * clears it well before this. */
+const TTL_SECONDS = 3600;
+
+/** A reported version ("20.17.0") is short; cap it for KV value-size hygiene. */
+const MAX_VERSION_LEN = 32;
+const MAX_CLI_LEN = 64;
+
+/** Astro's engines floor (enforced by CLI 1.3.4-rc.2). Used ONLY as a fallback
+ * when a node-too-old beacon omits `need`; a beacon that carries `need` wins. */
+const NODE_FLOOR = "22.12";
+
+/** Per-developer record key: `dev-obstacle:<tenant>:<email>` (email lowercased
+ * for a stable key, mirroring runtimeStore). */
+function key(appDomain: string, email: string | undefined): string {
+  return `${KEY_PREFIX}${appDomain}:${(email ?? "").toLowerCase()}`;
+}
+
+function clip(v: unknown, max: number): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v.slice(0, max) : undefined;
+}
+
+function isKind(v: unknown): v is ObstacleKind {
+  return typeof v === "string" && (OBSTACLE_KINDS as readonly string[]).includes(v);
+}
+
+/**
+ * Normalize a raw obstacle beacon into a stored record, or null when the `kind`
+ * is unrecognized (the route rejects that as a 400 — an unknown kind has no
+ * remediation copy, so storing it would render a blank card). Pure + exported so
+ * the route's validation is unit-tested without KV. have/need/cliVersion are
+ * bounded strings; `reportedAt` is the SERVER clock, never the client's `ts`.
+ */
+export function shapeObstacle(
+  body: { kind?: unknown; have?: unknown; need?: unknown; cliVersion?: unknown },
+  reportedAt: number,
+): DevObstacle | null {
+  if (!isKind(body.kind)) return null;
+  const rec: DevObstacle = { kind: body.kind, reportedAt };
+  const have = clip(body.have, MAX_VERSION_LEN);
+  const need = clip(body.need, MAX_VERSION_LEN);
+  const cliVersion = clip(body.cliVersion, MAX_CLI_LEN);
+  if (have) rec.have = have;
+  if (need) rec.need = need;
+  if (cliVersion) rec.cliVersion = cliVersion;
+  return rec;
+}
+
+/** Read a developer's latest obstacle (their tenant + email), or null when
+ * none/malformed/unknown-kind. Never throws. */
+export async function readObstacle(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<DevObstacle | null> {
+  try {
+    const raw = await kv.get(key(appDomain, email));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof parsed.reportedAt !== "number" ||
+      !isKind(parsed.kind)
+    ) {
+      return null;
+    }
+    return parsed as DevObstacle;
+  } catch {
+    return null;
+  }
+}
+
+/** Overwrite a developer's obstacle with their latest beacon (latest-wins, TTL'd),
+ * scoped to (tenant, email). */
+export async function writeObstacle(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+  rec: DevObstacle,
+): Promise<void> {
+  await kv.put(key(appDomain, email), JSON.stringify(rec), { expirationTtl: TTL_SECONDS });
+}
+
+/** Delete a developer's obstacle record — a live heartbeat supersedes it, and a
+ * ?reset clears it. Idempotent; never throws on an absent key. */
+export async function clearObstacle(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<void> {
+  await kv.delete(key(appDomain, email));
+}
+
+/**
+ * Compose the human remediation copy for an obstacle, keyed by kind — SERVER-side
+ * so the fix-it guidance changes without a CLI release. Pure. The exhaustive
+ * switch means adding a new ObstacleKind is a compile error here until its copy
+ * exists (so no kind can ship without a fix message).
+ */
+export function describeObstacle(rec: DevObstacle): {
+  title: string;
+  message: string;
+  fixCommand?: string;
+  fixNote: string;
+} {
+  switch (rec.kind) {
+    case "node-too-old": {
+      const need = rec.need || NODE_FLOOR;
+      const message = rec.have
+        ? `This machine is running Node ${rec.have} — the dev loop needs ${need} or newer.`
+        : `The dev loop needs Node ${need} or newer, and this machine's version is too old.`;
+      return {
+        title: "Node version too old",
+        message,
+        fixCommand: "nvm install 24 && nvm use 24",
+        fixNote: "then re-run the setup command above. No nvm? Install Node 24 LTS from nodejs.org.",
+      };
+    }
+    case "pnpm-missing":
+      return {
+        title: "pnpm not found",
+        message: "The dev loop needs pnpm, which isn't installed on this machine.",
+        fixCommand: "npm install -g pnpm",
+        fixNote: "then re-run the setup command above.",
+      };
+    case "install-failed":
+      return {
+        title: "Install failed",
+        message: "Installing the dev runner didn't finish on this machine.",
+        fixNote:
+          "Check your terminal for the npm or network error, then re-run the setup command. If it keeps failing, send us that output.",
+      };
+    case "clone-failed":
+      return {
+        title: "Couldn't fetch your store",
+        message: "The dev loop couldn't download your store's starter files.",
+        fixNote: "Check your network and the terminal output, then re-run the setup command.",
+      };
+  }
+}
+
+/** Attach the server-composed remediation copy to a stored obstacle — the
+ * developer-facing view the GET feed returns. Pure. */
+export function toObstacleView(rec: DevObstacle): DevObstacleView {
+  return { ...rec, ...describeObstacle(rec) };
+}

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;
+}

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

@@ -0,0 +1,241 @@
+/**
+ * The storefront (cockpit) half of the browserless CLI sign-in RENDEZVOUS — the
+ * server-to-server calls into the MCP's device-rendezvous endpoints, authenticated
+ * by the storefront's SIGNED CLIENT ASSERTION (private_key_jwt, RFC 7523), NOT the
+ * retired `x-mcp-service-secret`. The developer's cockpit (already authenticated as
+ * that developer) drives these; the MCP verifies the assertion against the
+ * storefront's published JWKS and admits only a client registered to broker CLI
+ * sign-in.
+ *
+ *   createRendezvous  → POST /oauth/device/rendezvous          (start; returns the
+ *                       NON-SECRET rendezvous_code rendered into `tot login --code`)
+ *   rendezvousStatus  → POST /oauth/device/rendezvous/status   (poll for a terminal
+ *                       attaching → { state, fingerprint })
+ *   approveRendezvous → POST /oauth/device/rendezvous/approve  (the human confirmed
+ *                       the fingerprint; carries the dev's fresh subject_token proof)
+ *   denyRendezvous    → POST /oauth/device/rendezvous/deny
+ *
+ * All four endpoints verify the SAME assertion audience — `<mcpBase>/oauth/device/rendezvous`
+ * (the MCP derives the expected audience from that fixed path, not the sub-path), so
+ * one minted assertion shape covers every call. SERVER-SIDE ONLY.
+ */
+import { readEnv } from "@/lib/env";
+import { mintMcpClientAssertion, McpClientAssertionError } from "@/lib/auth/mcpClientAssertion";
+
+const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/** The path whose audience the MCP binds EVERY rendezvous assertion to. */
+const RENDEZVOUS_AUDIENCE_PATH = "/oauth/device/rendezvous";
+
+/** Injectable transport so the broker calls unit-test with no network. */
+export interface HttpTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+// Bound every rendezvous call to the MCP. The MCP runs on AppRunner (scale-to-zero),
+// so the FIRST call after idle hits a cold instance that can take many seconds to
+// answer. Without a bound the storefront Worker's subrequest hangs and the browser's
+// POST to /api/dev/cli-signin-code eventually dies at the transport layer — the cockpit
+// shows the opaque catch-branch "Couldn't reach the sign-in service" and the button is
+// simply dead. Aborting at a fixed deadline turns that silent hang into a fast, RETRYABLE
+// 502 ("having a moment — try again"); the retry lands on a now-warm MCP and succeeds.
+const RENDEZVOUS_FETCH_TIMEOUT_MS = 12_000;
+
+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),
+      // A timeout/abort rejects the fetch → callRendezvous's catch → a 502 the cockpit
+      // renders as a retryable error, instead of a hung request the browser gives up on.
+      signal: AbortSignal.timeout(RENDEZVOUS_FETCH_TIMEOUT_MS),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+export interface RendezvousDeps {
+  transport?: HttpTransport;
+  /** Override the assertion minter in tests (defaults to the real private-key signer). */
+  mintAssertion?: (audience: string) => Promise<string>;
+}
+
+/** A resolved MCP target: the origin to POST to + the assertion audience. */
+interface McpTarget {
+  origin: string;
+  audience: string;
+}
+
+/**
+ * Resolve the MCP origin from `MCP_BASE_URL` (its ORIGIN). MCP_BASE_URL is the MCP
+ * this storefront authenticates to with its private_key_jwt client assertion (kid
+ * storefront-mcp-client-1) — the SAME credential + tier the confidential broker
+ * client (canBrokerCliSignin) is registered under (e.g. mcp.qa for preview). NOT
+ * MCP_APP_BINDING_URL, which the retired shared-secret shim used and which may point
+ * at a different MCP tier. Returns null when unset/malformed (route maps that to 503).
+ */
+export async function resolveMcpTarget(): Promise<McpTarget | null> {
+  const baseUrl = await readEnv("MCP_BASE_URL");
+  if (!baseUrl) return null;
+  try {
+    const origin = new URL(baseUrl).origin;
+    return { origin, audience: `${origin}${RENDEZVOUS_AUDIENCE_PATH}` };
+  } catch {
+    return null;
+  }
+}
+
+async function callRendezvous(
+  target: McpTarget,
+  path: string,
+  extra: Record<string, unknown>,
+  deps: RendezvousDeps,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const mint = deps.mintAssertion ?? ((aud: string) => mintMcpClientAssertion(aud));
+  const clientAssertion = await mint(target.audience);
+  const transport = deps.transport ?? new FetchHttpTransport();
+  const res = await transport.post(
+    `${target.origin}${path}`,
+    {},
+    {
+      client_assertion: clientAssertion,
+      client_assertion_type: JWT_BEARER_ASSERTION_TYPE,
+      ...extra,
+    },
+  );
+  let body: Record<string, unknown> = {};
+  try {
+    body = (await res.json()) as Record<string, unknown>;
+  } catch {
+    body = {};
+  }
+  return { status: res.status, body };
+}
+
+export type RendezvousCreateResult =
+  | { ok: true; rendezvousCode: string; expiresIn: number | null }
+  | { ok: false; status: 502 | 503; reason: string };
+
+/**
+ * Start a rendezvous for the signed-in developer's OWN email (+ their vendor tenant).
+ * Fail-closed mapping mirrors the retired mint: an unconfigured seam or a 401/403
+ * (assertion rejected / client not entitled to broker) is a 503 ("not wired up on
+ * this environment"); any other fault is a 502.
+ */
+export async function createRendezvous(
+  email: string,
+  tenant: string | null,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousCreateResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(
+      target,
+      RENDEZVOUS_AUDIENCE_PATH,
+      { email: email.toLowerCase(), ...(tenant ? { tenant: tenant.toLowerCase() } : {}) },
+      deps,
+    );
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed: " + (cause instanceof Error ? cause.message : String(cause)) };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    // 401 invalid_client / 403 unauthorized_client|not_entitled = "not wired up /
+    // not entitled on this environment" → 503; a fault is 502.
+    const notConfigured = res.status === 401 || res.status === 403;
+    return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous create returned ${res.status}` };
+  }
+  const rendezvousCode = typeof res.body.rendezvous_code === "string" ? res.body.rendezvous_code : "";
+  if (!rendezvousCode) return { ok: false, status: 502, reason: "rendezvous create returned no code" };
+  return {
+    ok: true,
+    rendezvousCode,
+    expiresIn: typeof res.body.expires_in === "number" ? res.body.expires_in : null,
+  };
+}
+
+export type RendezvousState = "pending" | "attached" | "approved" | "denied" | "expired";
+export type RendezvousStatusResult =
+  | { ok: true; state: RendezvousState; fingerprint: string | null }
+  | { ok: false; status: 502 | 503; reason: string };
+
+/** Poll for a terminal attaching. `fingerprint` is present once state is `attached`. */
+export async function rendezvousStatus(
+  rendezvousCode: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousStatusResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(target, `${RENDEZVOUS_AUDIENCE_PATH}/status`, { rendezvous_code: rendezvousCode }, deps);
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    const notConfigured = res.status === 401 || res.status === 403;
+    return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous status returned ${res.status}` };
+  }
+  const state = String(res.body.state ?? "expired") as RendezvousState;
+  return { ok: true, state, fingerprint: typeof res.body.fingerprint === "string" ? res.body.fingerprint : null };
+}
+
+export type RendezvousDecisionResult =
+  | { ok: true }
+  | { ok: false; status: 403 | 409 | 502 | 503; reason: string };
+
+/**
+ * Approve the attached terminal. Carries the developer's fresh `subject_token`
+ * (Part A / Finding 3) so the MCP can bind the approval to the dev's own identity —
+ * a 403 `approver_mismatch` means the proof didn't match the rendezvous developer;
+ * a 409 `not_approvable` means the fingerprint didn't match a waiting terminal.
+ */
+export async function approveRendezvous(
+  rendezvousCode: string,
+  fingerprint: string,
+  subjectToken: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousDecisionResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  let res: { status: number; body: Record<string, unknown> };
+  try {
+    res = await callRendezvous(
+      target,
+      `${RENDEZVOUS_AUDIENCE_PATH}/approve`,
+      { rendezvous_code: rendezvousCode, fingerprint, subject_token: subjectToken },
+      deps,
+    );
+  } catch (cause) {
+    if (cause instanceof McpClientAssertionError) return { ok: false, status: 503, reason: "assertion-unconfigured" };
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+  if (res.status >= 200 && res.status < 300) return { ok: true };
+  if (res.status === 403) return { ok: false, status: 403, reason: String(res.body.error ?? "approver_mismatch") };
+  if (res.status === 409) return { ok: false, status: 409, reason: String(res.body.error ?? "not_approvable") };
+  const notConfigured = res.status === 401;
+  return { ok: false, status: notConfigured ? 503 : 502, reason: `rendezvous approve returned ${res.status}` };
+}
+
+/** Reject the attached terminal (the human said "not me"). */
+export async function denyRendezvous(
+  rendezvousCode: string,
+  deps: RendezvousDeps = {},
+): Promise<RendezvousDecisionResult> {
+  const target = await resolveMcpTarget();
+  if (!target) return { ok: false, status: 503, reason: "not-configured" };
+  try {
+    const res = await callRendezvous(target, `${RENDEZVOUS_AUDIENCE_PATH}/deny`, { rendezvous_code: rendezvousCode }, deps);
+    if (res.status >= 200 && res.status < 300) return { ok: true };
+    return { ok: false, status: res.status === 401 ? 503 : 502, reason: `rendezvous deny returned ${res.status}` };
+  } catch {
+    return { ok: false, status: 502, reason: "mcp request failed" };
+  }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Re-issue a FRESH tot20-signed id_token for an already-signed-in developer — the
+ * `subject_token` proof the cockpit sends when APPROVING a browserless CLI sign-in
+ * rendezvous (Part A / Finding 3).
+ *
+ * WHY re-issue: the storefront verifies tot20's id_token OFFLINE at sign-in and then
+ * DISCARDS it (only derived claims live in the KV session), and it's short-lived —
+ * long expired by the time the developer approves. So at approve time we MINT a fresh
+ * single-use sign-in token for the session's VERIFIED email and exchange it for a
+ * freshly-signed id_token.
+ *
+ * WHY it closes Finding 3: the mint + exchange authenticate with the storefront's tot20
+ * CORE machine credential (TOT_API_KEY/TOT_SECRET_KEY) — a DIFFERENT secret from the MCP
+ * broker key. A compromised broker key alone cannot produce this proof.
+ *
+ * WHY mint, NOT developerInvites: tot20's access-code `/mint` is NOT operator-grant-gated
+ * per tenant, whereas developerInvites is (it 403s `notGranted` for a non-staff developer
+ * re-attesting themselves on a tenant the storefront doesn't operate). `/mint` binds the
+ * token to (email, aud = the storefront's OWN appDomain) — which equals the storefront's
+ * MCP client_id, exactly what the MCP binds the subject_token audience to. This is the
+ * same non-gated mint the MCP itself uses to power rendezvous creation.
+ */
+import { getAccessClient } from "@/lib/auth/route";
+import type { TotAccessClient } from "@/lib/auth/totAccessClient";
+
+/** Short — the proof is minted and used immediately at approve time. */
+const SUBJECT_TOKEN_TTL_SECONDS = 120;
+
+export type SubjectReissueResult =
+  | { ok: true; idToken: string }
+  | { ok: false; reason: string };
+
+export interface SubjectReissueDeps {
+  accessClient?: TotAccessClient | null;
+}
+
+/**
+ * Produce a fresh subject id_token for `email`. Fail-closed: any gap (unconfigured seam,
+ * mint refused, exchange failed / step-up required) returns a typed `{ ok:false, reason }`
+ * and NEVER throws — the caller maps that to a refusal to approve. The id_token is returned
+ * only to the server; it is never logged.
+ */
+export async function reissueSubjectToken(
+  email: string,
+  deps: SubjectReissueDeps = {},
+): Promise<SubjectReissueResult> {
+  if (!email) return { ok: false, reason: "missing-identity" };
+
+  const accessClient =
+    deps.accessClient !== undefined ? deps.accessClient : await getAccessClient();
+  if (!accessClient) return { ok: false, reason: "access-client-unconfigured" };
+
+  // Mint a fresh single-use sign-in token for the developer's OWN email (bound to the
+  // storefront's appDomain as audience — not grant-gated per tenant).
+  const minted = await accessClient.mintSignInToken(email, SUBJECT_TOKEN_TTL_SECONDS);
+  if (!minted.ok || !minted.token) {
+    return { ok: false, reason: minted.ok ? "no-signin-token" : `mint-${minted.reason}` };
+  }
+
+  // Exchange (single-use; tot20 burns it) → a signed federated id_token whose aud is the
+  // storefront appDomain and whose email is this developer.
+  const exchanged = await accessClient.exchangeSignInToken(minted.token);
+  if (!exchanged.ok || !exchanged.id_token) {
+    return { ok: false, reason: exchanged.ok ? "no-id-token" : `exchange-${exchanged.reason}` };
+  }
+  return { ok: true, idToken: exchanged.id_token };
+}

package/apps/storefront/src/lib/email/magicLinkInviteEmail.ts

@@ -40,20 +40,20 @@ export function renderMagicLinkInviteEmail(input: MagicLinkInviteEmailInput): {
   const html = `<!doctype html>
 <html lang="en">
   <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
-  <body style="margin:0;padding:0;background:#f5f4f0;">
-    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#1c1c1c;">
-      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0f7b6c;margin:0 0 24px;">
+  <body style="margin:0;padding:0;background:#f7f9fc;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#33415b;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0b7a6d;margin:0 0 24px;">
         Token of Trust&#169; &middot; ${esc(store)}
       </div>
-      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.01em;margin:0 0 12px;color:#0b1f3a;">You've been invited</h1>
-      <p style="margin:0 0 8px;color:#3a3a3a;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
-      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#eef4ff;border:1px solid #c3d4f5;border-radius:8px;color:#234;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.02em;margin:0 0 12px;color:#0a2540;">You've been invited</h1>
+      <p style="margin:0 0 8px;color:#33415b;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
+      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#e7f6f4;border:1px solid #b8e6df;border-radius:10px;color:#0a2540;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
       <div style="margin:28px 0;">
-        <a href="${url}" style="display:inline-block;background:#0f7b6c;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:9px;">Sign in to ${esc(store)}</a>
+        <a href="${url}" style="display:inline-block;background:#0b7a6d;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:999px;">Sign in to ${esc(store)}</a>
       </div>
-      <p style="margin:0 0 4px;font-size:13px;color:#6a6a6a;">Or paste this link into your browser:</p>
-      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0f7b6c;">${url}</a></p>
-      <p style="margin:0;font-size:12px;color:#9a9a9a;border-top:1px solid #e6e4de;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
+      <p style="margin:0 0 4px;font-size:13px;color:#55637a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0b7a6d;">${url}</a></p>
+      <p style="margin:0;font-size:12px;color:#8593a8;border-top:1px solid #e3e8ef;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
     </div>
   </body>
 </html>`;