@tokenoftrust/storefront-runner 2.2.12 → 2.2.13

package/apps/storefront/public/js/dashboard-access-banner.js

@@ -0,0 +1,53 @@
+/**
+ * The granter's "an invited developer can't use their access" banner, shared by the vendor
+ * dashboard home and the Team page.
+ *
+ * Served as a STATIC same-origin file (public/) and referenced via
+ * <script src="/js/dashboard-access-banner.js">, so the strict production CSP allows it via
+ * `script-src 'self'` (see the header of dashboard-team.js). The tenant appDomain is read
+ * from the `#access-alerts` element's `data-tenant` attribute; the element carries the
+ * `hidden` attribute until there is something to show. Any failure leaves it hidden.
+ */
+(function () {
+  const root = document.getElementById("access-alerts");
+  if (!root) return;
+  const tenant = root.dataset.tenant;
+  const teamHref = root.dataset.teamHref;
+
+  function render(broken) {
+    root.replaceChildren();
+    const n = broken.length;
+    const head = document.createElement("p");
+    head.className = "access-alerts-head";
+    head.textContent = n + (n === 1 ? " developer you invited can't" : " developers you invited can't") +
+      " use their access";
+    root.appendChild(head);
+    const tag = document.createElement("span");
+    tag.className = "advice";
+    tag.textContent = "tot-mcp advice";
+    root.appendChild(tag);
+    const list = document.createElement("ul");
+    for (const b of broken) {
+      const li = document.createElement("li");
+      li.textContent = b.developer + " — step: " + b.failedStep + ". " + b.reason + " Fix: " + b.fix;
+      list.appendChild(li);
+    }
+    root.appendChild(list);
+    if (teamHref) {
+      const a = document.createElement("a");
+      a.href = teamHref;
+      a.textContent = "Open the Team page →";
+      root.appendChild(a);
+    }
+    root.hidden = false;
+  }
+
+  fetch("/api/grants/team-access-alerts?tenant=" + encodeURIComponent(tenant), {
+    headers: { accept: "application/json" },
+  })
+    .then((res) => (res.ok ? res.json() : null))
+    .then((body) => {
+      if (body && Array.isArray(body.broken) && body.broken.length) render(body.broken);
+    })
+    .catch(() => {});
+})();

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

@@ -20,7 +20,7 @@
  * 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";
+import { callMcpService } from "@/lib/http/mcpServiceCall";
 import { FetchHttpTransport, type HttpGetTransport } from "@/lib/http/fetchTransport";
 
 export type { HttpGetTransport };
@@ -42,35 +42,22 @@ 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 FetchHttpTransport();
-  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 (!tenant) return { configured: false, ok: false };
+  const outcome = await callMcpService({
+    method: "GET",
+    path: "/internal/preview-status",
+    query: { tenant: tenant.toLowerCase() },
+    transport: deps.transport ?? new FetchHttpTransport(),
+  });
+  if (outcome.kind === "not-configured") return { configured: false, ok: false };
+  if (outcome.kind === "bad-url") return { configured: false, ok: false, reason: "bad-mcp-url" };
+  if (outcome.kind === "transport-error") {
+    return { configured: true, ok: false, reason: "mcp request failed: " + outcome.message };
   }
-  if (res.status < 200 || res.status >= 300) {
-    return { configured: true, ok: false, status: res.status, reason: `status ${res.status}` };
+  if (outcome.kind === "misconfigured" || outcome.kind === "http-error") {
+    return { configured: true, ok: false, status: outcome.status, reason: `status ${outcome.status}` };
   }
+  const res = outcome;
   let payload: unknown;
   try {
     payload = await res.json();

package/apps/storefront/src/lib/http/mcpServiceCall.ts

@@ -0,0 +1,85 @@
+/**
+ * The one transport for storefront → tot-mcp service calls (`/internal/*`, keyless
+ * `x-mcp-service-secret` seam). Every caller builds its URL here from the ORIGIN of
+ * `MCP_APP_BINDING_URL` plus a literal contract path, so the paths and capabilities a caller
+ * sends are pinned by `contracts/tot-mcp-service-seam.json` (see `mcpServiceSeam.test.ts`).
+ *
+ * A 401 or 404 from a seam route is misconfiguration, never a business answer: tot-mcp's
+ * routes answer 200 for every absent/unknown case, so 401 means the secret or URL is wrong
+ * and 404 means the path is not served. Both log LOUDLY and come back as `misconfigured`
+ * (a non-skipped failure), while each caller keeps its own fail-open / fail-closed mapping
+ * for the outcome.
+ */
+import { readEnv } from "@/lib/env";
+
+export interface McpServiceResponse {
+  status: number;
+  json(): Promise<unknown>;
+}
+
+/** A transport implementing the method(s) the call uses; test stubs may implement only one. */
+export interface McpServiceTransport {
+  get?(url: string, headers: Record<string, string>): Promise<McpServiceResponse>;
+  post?(url: string, headers: Record<string, string>, body: unknown): Promise<McpServiceResponse>;
+}
+
+export type McpServiceOutcome =
+  | { kind: "not-configured" }
+  | { kind: "bad-url" }
+  | { kind: "misconfigured"; status: 401 | 404; reason: string }
+  | { kind: "http-error"; status: number }
+  | { kind: "transport-error"; message: string }
+  | { kind: "ok"; status: number; json(): Promise<unknown> };
+
+export interface McpServiceRequest {
+  method: "GET" | "POST";
+  /** A literal `/internal/...` contract path. */
+  path: string;
+  query?: Record<string, string>;
+  body?: unknown;
+  transport: McpServiceTransport;
+}
+
+function misconfigurationReason(status: 401 | 404): string {
+  return status === 401
+    ? "tot-mcp rejected the service secret, or MCP_APP_BINDING_URL points at a session-guarded surface"
+    : "tot-mcp does not serve this path; storefront and tot-mcp disagree on the service-seam contract";
+}
+
+export async function callMcpService(req: McpServiceRequest): Promise<McpServiceOutcome> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret) return { kind: "not-configured" };
+
+  let url: string;
+  try {
+    url = `${new URL(bindingUrl).origin}${req.path}`;
+  } catch {
+    return { kind: "bad-url" };
+  }
+  if (req.query) url += `?${new URLSearchParams(req.query).toString()}`;
+
+  const headers = { "x-mcp-service-secret": secret };
+  let res: McpServiceResponse;
+  try {
+    if (req.method === "GET") {
+      if (!req.transport.get) throw new Error("transport has no get()");
+      res = await req.transport.get(url, headers);
+    } else {
+      if (!req.transport.post) throw new Error("transport has no post()");
+      res = await req.transport.post(url, headers, req.body);
+    }
+  } catch (cause) {
+    return { kind: "transport-error", message: cause instanceof Error ? cause.message : String(cause) };
+  }
+
+  if (res.status === 401 || res.status === 404) {
+    const reason = misconfigurationReason(res.status);
+    console.error(
+      `[mcp-service-seam] ${req.method} ${req.path} answered ${res.status}: ${reason}`,
+    );
+    return { kind: "misconfigured", status: res.status, reason };
+  }
+  if (res.status < 200 || res.status >= 300) return { kind: "http-error", status: res.status };
+  return { kind: "ok", status: res.status, json: () => res.json() };
+}

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

@@ -17,7 +17,7 @@
  * Nothing here is ever reported as verified unless tot-mcp said so: an unconfigured seam,
  * a non-200 or a timeout is `unavailable`, which the UI shows as unverified.
  */
-import { readEnv } from "@/lib/env";
+import { callMcpService } from "@/lib/http/mcpServiceCall";
 
 const EXPLAIN_TIMEOUT_MS = 8000;
 
@@ -120,27 +120,30 @@ export async function explainDeveloperAccess(
   inviteStatus: "pending" | "accepted",
   deps: { transport?: ExplainTransport } = {},
 ): Promise<AccessVerification> {
-  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
-  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
-  if (!bindingUrl || !secret) {
+  const outcome = await callMcpService({
+    method: "POST",
+    path: "/internal/dev-access/explain",
+    body: { person: email.trim().toLowerCase(), tenant: tenant.trim().toLowerCase() },
+    transport: deps.transport ?? new FetchExplainTransport(),
+  });
+  if (outcome.kind === "not-configured") {
     return { state: "unavailable", reason: "verification is not configured here", advice: "tot-mcp" };
   }
-  let endpoint: string;
-  try {
-    endpoint = `${new URL(bindingUrl).origin}/internal/dev-access/explain`;
-  } catch {
+  if (outcome.kind === "bad-url") {
     return { state: "unavailable", reason: "the tot-mcp address is malformed", advice: "tot-mcp" };
   }
-  const transport = deps.transport ?? new FetchExplainTransport();
+  if (outcome.kind === "transport-error") {
+    return {
+      state: "unavailable",
+      reason: "tot-mcp did not answer: " + outcome.message,
+      advice: "tot-mcp",
+    };
+  }
+  if (outcome.kind === "misconfigured" || outcome.kind === "http-error") {
+    return { state: "unavailable", reason: `tot-mcp answered ${outcome.status}`, advice: "tot-mcp" };
+  }
+  const res = outcome;
   try {
-    const res = await transport.post(
-      endpoint,
-      { "x-mcp-service-secret": secret },
-      { person: email.trim().toLowerCase(), tenant: tenant.trim().toLowerCase() },
-    );
-    if (res.status < 200 || res.status >= 300) {
-      return { state: "unavailable", reason: `tot-mcp answered ${res.status}`, advice: "tot-mcp" };
-    }
     const explanation = (await res.json()) as AccessExplanation;
     if (typeof explanation?.verified !== "boolean" || !Array.isArray(explanation.steps)) {
       return { state: "unavailable", reason: "tot-mcp sent an unreadable answer", advice: "tot-mcp" };

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

@@ -53,6 +53,7 @@
  * control-plane cluster stays self-contained (see `.dependency-cruiser.cjs`).
  */
 import { readEnv } from "@/lib/env";
+import { callMcpService } from "@/lib/http/mcpServiceCall";
 import { diagEmail } from "@/lib/diag/redact";
 import { checkStorePreviewReady, type PreflightDecision } from "@/lib/shared/invitePreflight";
 import { explainDeveloperAccess, type AccessVerification } from "@/lib/shared/accessExplain";
@@ -1038,8 +1039,8 @@ export type AppBindingResult =
  * MCP store is the app-binding source of truth; the writer is this keyless flow.
  *
  * WIRED (confirmed contract):
- *   POST `${MCP_APP_BINDING_URL}`  — the keyless subject-capability writer,
- *     e.g. https://mcp.qa.tokenoftrust.com/internal/dev-access/subject-capability
+ *   POST `${origin(MCP_APP_BINDING_URL)}/internal/dev-access/subject-capability` — the keyless
+ *     subject-capability writer, e.g. https://mcp.qa.tokenoftrust.com/internal/dev-access/subject-capability
  *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (compared
  *     constant-time to the MCP's shared secret) — NOT an Authorization bearer.
  *   Body: { subject:<email>, tenant, capability:'preview-access', app:'storefront' }
@@ -1057,49 +1058,47 @@ export async function recordDeveloperAppBinding(
   binding: DeveloperAppBinding,
   deps: { transport?: HttpTransport } = {},
 ): Promise<AppBindingResult> {
-  const url = await readEnv("MCP_APP_BINDING_URL");
-  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
-  if (!url || !secret) {
-    // Seam not fully configured (the MCP route isn't mounted until the shared
-    // secret exists). Skip cleanly rather than fail the invite.
-    return { recorded: false, skipped: true, reason: "not-configured" };
-  }
-  const transport = deps.transport ?? new FetchHttpTransport();
-  try {
-    const res = await transport.post(
-      url,
-      { "x-mcp-service-secret": secret },
-      {
-        // Option B fixed fields — the subject-capability binding for storefront.
-        subject: binding.email.toLowerCase(),
-        tenant: binding.tenant,
-        capability: binding.capability ?? "preview-access",
-        app: "storefront",
-      },
-    );
-    if (res.status >= 200 && res.status < 300) return { recorded: true };
-    if (res.status === 401) {
-      // A route answered and refused: the secret does not match, or the URL sits under the
-      // MCP's session-guarded /api surface. Both are misconfiguration, so it is a failure.
+  const outcome = await callMcpService({
+    method: "POST",
+    path: "/internal/dev-access/subject-capability",
+    // Option B fixed fields — the subject-capability binding for storefront.
+    body: {
+      subject: binding.email.toLowerCase(),
+      tenant: binding.tenant,
+      capability: binding.capability ?? "preview-access",
+      app: "storefront",
+    },
+    transport: deps.transport ?? new FetchHttpTransport(),
+  });
+  switch (outcome.kind) {
+    case "ok":
+      return { recorded: true };
+    case "not-configured":
+      // Seam not fully configured (the MCP route isn't mounted until the shared secret
+      // exists). Skip cleanly rather than fail the invite.
+      return { recorded: false, skipped: true, reason: "not-configured" };
+    case "bad-url":
+      return { recorded: false, skipped: false, reason: "mcp app-binding url is malformed" };
+    case "misconfigured":
+      // A route answered and refused (401), or does not exist (404): misconfiguration, so a
+      // failure, never a skip.
       return {
         recorded: false,
         skipped: false,
-        reason: "unauthorized: the mcp service secret was rejected, or MCP_APP_BINDING_URL is not the /internal path",
+        reason: `${outcome.status === 401 ? "unauthorized" : "not found"}: ${outcome.reason}`,
+      };
+    case "http-error":
+      return {
+        recorded: false,
+        skipped: false,
+        reason: `mcp app-binding write returned status ${outcome.status}`,
+      };
+    case "transport-error":
+      return {
+        recorded: false,
+        skipped: false,
+        reason: "mcp app-binding write failed: " + outcome.message,
       };
-    }
-    return {
-      recorded: false,
-      skipped: false,
-      reason: `mcp app-binding write returned status ${res.status}`,
-    };
-  } catch (cause) {
-    return {
-      recorded: false,
-      skipped: false,
-      reason:
-        "mcp app-binding write failed: " +
-        (cause instanceof Error ? cause.message : String(cause)),
-    };
   }
 }
 

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

@@ -22,7 +22,7 @@
  * mirroring recordDeveloperAppBinding's "skipped when not-configured" stance — we
  * never break invites just because the MCP is briefly unreachable.
  */
-import { readEnv } from "@/lib/env";
+import { callMcpService } from "@/lib/http/mcpServiceCall";
 
 /** How long we'll wait on the preview-status read before failing open. */
 const PREFLIGHT_TIMEOUT_MS = 4000;
@@ -71,39 +71,26 @@ export async function checkStorePreviewReady(
   tenant: string,
   deps: { transport?: PreflightTransport } = {},
 ): Promise<PreflightDecision> {
-  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
-  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
-  if (!bindingUrl || !secret) {
-    // Seam not configured (the MCP route isn't even mounted without the secret) —
-    // inconclusive, so allow rather than break every invite.
-    return { block: false, reason: "not-configured" };
+  const outcome = await callMcpService({
+    method: "GET",
+    path: "/internal/preview-status",
+    query: { tenant: tenant.toLowerCase(), app: "storefront", tag: "main" },
+    transport: deps.transport ?? new FetchPreflightTransport(),
+  });
+  // Only a clean 200 is a conclusive answer; every other outcome is inconclusive → allow
+  // (a 401/404 is logged loudly by the seam helper as misconfiguration).
+  if (outcome.kind === "not-configured") return { block: false, reason: "not-configured" };
+  if (outcome.kind === "bad-url") return { block: false, reason: "bad-mcp-url" };
+  if (outcome.kind === "transport-error") {
+    return { block: false, reason: "preflight request failed: " + outcome.message };
   }
-
-  let endpoint: string;
-  try {
-    const origin = new URL(bindingUrl).origin;
-    const q = new URLSearchParams({ tenant: tenant.toLowerCase(), app: "storefront", tag: "main" });
-    // Canonical, namespace-neutral path (the read is generic, not dev-role-scoped).
-    endpoint = `${origin}/internal/preview-status?${q.toString()}`;
-  } catch {
-    return { block: false, reason: "bad-mcp-url" };
+  if (outcome.kind === "misconfigured") {
+    return { block: false, reason: `preflight misconfigured: status ${outcome.status}` };
   }
-
-  const transport = deps.transport ?? new FetchPreflightTransport();
-  let res: { status: number; json(): Promise<unknown> };
-  try {
-    res = await transport.get(endpoint, { "x-mcp-service-secret": secret });
-  } catch (cause) {
-    return {
-      block: false,
-      reason: "preflight request failed: " + (cause instanceof Error ? cause.message : String(cause)),
-    };
-  }
-
-  // Only a clean 200 is a conclusive answer; anything else is inconclusive → allow.
-  if (res.status < 200 || res.status >= 300) {
-    return { block: false, reason: `preflight returned status ${res.status}` };
+  if (outcome.kind === "http-error") {
+    return { block: false, reason: `preflight returned status ${outcome.status}` };
   }
+  const res = outcome;
   let payload: { provisioned?: unknown; previewReleased?: unknown };
   try {
     payload = (await res.json()) as typeof payload;

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

@@ -30,7 +30,7 @@
  * app-binding WRITE (`recordDeveloperAppBinding`) targets, so this READ and that
  * WRITE always agree on which subject-capability store they speak to.
  */
-import { readEnv } from "@/lib/env";
+import { callMcpService } from "@/lib/http/mcpServiceCall";
 import type { Capability } from "./capability.js";
 
 /** Minimal GET transport (mirrors `dev/previewStatus.ts` — decoupled by design). */
@@ -58,9 +58,6 @@ export interface ViewerShipGrantDeps {
   transport?: ViewerShipGrantGetTransport;
 }
 
-/** The Step-1 subject-capability reader path (mounted OUTSIDE the session guard). */
-const SUBJECT_CAPABILITY_PATH = "/internal/dev-access/subject-capability";
-
 /** The viewer's blog-contribute capability — a NEW, blog-scoped projection kept OUT
  * of the forge `Capability` union (which stays exactly two rungs). `ship-on-behalf`
  * supersets contribute, so a ship grant also yields `"blog-contribute"` here. */
@@ -87,31 +84,16 @@ async function resolveRawViewerCapability(
   const tenant = (appDomain ?? "").trim();
   if (!subject || !tenant) return "preview-access";
 
-  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
-  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
-  // Unconfigured seam → deny (the MCP route is only mounted once the secret exists).
-  if (!bindingUrl || !secret) return "preview-access";
-
-  let endpoint: string;
-  try {
-    endpoint = `${new URL(bindingUrl).origin}${SUBJECT_CAPABILITY_PATH}`;
-  } catch {
-    return "preview-access";
-  }
-  const full =
-    `${endpoint}?subject=${encodeURIComponent(subject)}` +
-    `&tenant=${encodeURIComponent(tenant)}&app=storefront`;
-
-  const transport = deps.transport ?? new FetchShipGrantTransport();
-  let res: { status: number; json(): Promise<unknown> };
-  try {
-    res = await transport.get(full, { "x-mcp-service-secret": secret });
-  } catch {
-    // Transport / timeout fault — fail closed.
-    return "preview-access";
-  }
-  // Any non-2xx (incl. 502 store fault, 401 unmounted, 404) → deny.
-  if (res.status < 200 || res.status >= 300) return "preview-access";
+  const outcome = await callMcpService({
+    method: "GET",
+    path: "/internal/dev-access/subject-capability",
+    query: { subject, tenant, app: "storefront" },
+    transport: deps.transport ?? new FetchShipGrantTransport(),
+  });
+  // Unconfigured, misconfigured (401/404, logged loudly), any other non-2xx (incl. 502
+  // store fault) or a transport/timeout fault → deny.
+  if (outcome.kind !== "ok") return "preview-access";
+  const res = outcome;
 
   let payload: unknown;
   try {

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

@@ -159,9 +159,10 @@ export async function POST(context: APIContext): Promise<Response> {
     });
   }
 
-  // The granter left at Send invite; re-prove the grant now that the invitee accepted, so a
-  // break shows on the granter's Team page (team-access re-runs the same check) and in the
-  // logs, not only in the invitee's terminal. Best-effort: never blocks the sign-in.
+  // The granter left at Send invite; re-prove the grant now that the invitee accepted. The
+  // granter is told by the red banner on their dashboard home and Team page
+  // (/api/grants/team-access-alerts re-runs this same check per invitee); this warn line is
+  // the log trace. Best-effort: never blocks the sign-in.
   try {
     const verification = await explainDeveloperAccess(tenant, derived.email, "accepted");
     if (verification.state === "broken") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.12",
+  "version": "2.2.13",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",