@tokenoftrust/storefront-runner 2.2.8 → 2.2.9

package/apps/storefront/public/js/dashboard-team.js

@@ -17,12 +17,95 @@
   if (!membersBody) return;
   const tenant = membersBody.dataset.tenant;
 
+  // One verdict from tot-mcp's access_explain, rendered the same everywhere: the Team row,
+  // the invite result and the resend result. `verified` is `true` or the failure object.
+  function verdictParts(verdict) {
+    if (verdict === true || (verdict && verdict.state === "verified")) {
+      return { cls: "ok", label: "Active", why: "" };
+    }
+    const v = verdict || { state: "unavailable", reason: "not verified" };
+    if (v.state === "awaiting-acceptance") {
+      return v.inviteStatus === "accepted"
+        ? { cls: "pend", label: "Accepted — not signed in", why: v.reason + " " + v.fix }
+        : { cls: "pend", label: "Pending", why: "Waiting for the developer to accept and sign in." };
+    }
+    if (v.state === "broken") {
+      return { cls: "bad", label: "Not resolving", why: v.reason + " Fix: " + v.fix };
+    }
+    return { cls: "pend", label: "Unverified", why: "Couldn't check: " + (v.reason || "unknown") + "." };
+  }
+
+  function renderAccessCell(td, verdict) {
+    const parts = verdictParts(verdict);
+    td.replaceChildren();
+    const label = document.createElement("span");
+    label.className = "access " + parts.cls;
+    label.textContent = parts.label;
+    td.appendChild(label);
+    if (parts.why) {
+      const why = document.createElement("span");
+      why.className = "access-why";
+      why.textContent = parts.why;
+      td.appendChild(why);
+    }
+  }
+
+  async function checkAccess(email, td, btn) {
+    if (btn) btn.disabled = true;
+    td.replaceChildren();
+    td.textContent = "Checking…";
+    td.className = "muted";
+    try {
+      const q = "tenant=" + encodeURIComponent(tenant) + "&email=" + encodeURIComponent(email);
+      const res = await fetch("/api/grants/team-access?" + q, { headers: { accept: "application/json" } });
+      const body = await res.json().catch(() => ({}));
+      td.className = "";
+      renderAccessCell(td, res.ok ? body.access
+        : { state: "unavailable", reason: body.error || ("HTTP " + res.status) });
+    } catch (e) {
+      td.className = "";
+      renderAccessCell(td, { state: "unavailable", reason: e && e.message ? e.message : String(e) });
+    } finally {
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  // The invite / resend result: green only when tot-mcp proved the grant resolves; a
+  // broken grant is red with its step and fix and never reads as "invited".
+  function showVerdict(email, verdict, sentLine) {
+    const parts = verdictParts(verdict);
+    const wrap = document.createElement("div");
+    const tag = document.createElement("span");
+    tag.className = "advice";
+    tag.textContent = "tot-mcp advice";
+    wrap.appendChild(tag);
+    const line = document.createElement("p");
+    line.style.margin = ".2rem 0 0";
+    if (parts.cls === "ok") {
+      line.textContent = sentLine + " Access verified — " +
+        ((verdict && verdict.capability) || "preview-access") + " resolves for " + email + ".";
+      wrap.appendChild(line);
+      showMsg("ok", wrap);
+      return;
+    }
+    if (parts.cls === "pend") {
+      line.textContent = sentLine + " " + parts.why;
+      wrap.appendChild(line);
+      showMsg("ok", wrap);
+      return;
+    }
+    line.textContent = "Access for " + email + " will not work yet (step: " + verdict.failedStep +
+      "). " + verdict.reason + " Fix: " + verdict.fix + " No invite email was sent.";
+    wrap.appendChild(line);
+    showMsg("err", wrap);
+  }
+
   function renderMembers(members) {
     membersBody.replaceChildren();
     if (!members || !members.length) {
       const tr = document.createElement("tr");
       const td = document.createElement("td");
-      td.colSpan = 3; td.className = "muted";
+      td.colSpan = 4; td.className = "muted";
       td.textContent = "No developers invited yet.";
       tr.appendChild(td); membersBody.appendChild(tr);
       return;
@@ -33,8 +116,17 @@
       dev.textContent = m.developer;
       const roles = document.createElement("td");
       roles.textContent = (m.roles || []).join(", ") || "developer";
+      const access = document.createElement("td");
       const act = document.createElement("td");
       act.className = "act";
+      const checkBtn = document.createElement("button");
+      checkBtn.type = "button";
+      checkBtn.className = "rowbtn";
+      checkBtn.textContent = "Check access";
+      checkBtn.title = "Check whether " + m.developer + "'s access resolves right now";
+      checkBtn.style.marginRight = ".4rem";
+      checkBtn.addEventListener("click", () => checkAccess(m.developer, access, checkBtn));
+      act.appendChild(checkBtn);
       const btn = document.createElement("button");
       btn.type = "button";
       btn.className = "rowbtn";
@@ -52,8 +144,9 @@
         revokeBtn.addEventListener("click", () => revoke(m.developer, m.inviteId, revokeBtn));
         act.appendChild(revokeBtn);
       }
-      tr.appendChild(dev); tr.appendChild(roles); tr.appendChild(act);
+      tr.appendChild(dev); tr.appendChild(roles); tr.appendChild(access); tr.appendChild(act);
       membersBody.appendChild(tr);
+      checkAccess(m.developer, access, checkBtn);
     }
   }
 
@@ -92,7 +185,9 @@
       });
       const body = await res.json().catch(() => ({}));
       if (res.ok) {
-        showMsg("ok", "Re-sent the sign-in email to " + (body.developer || email) + ".");
+        const who = body.developer || email;
+        showVerdict(who, body.verified, "Re-sent the sign-in email to " + who + ".");
+        loadMembers();
       } else {
         showMsg("err", body.error || ("Couldn't resend (HTTP " + res.status + ")."));
       }
@@ -107,7 +202,7 @@
     membersBody.replaceChildren();
     const tr = document.createElement("tr");
     const td = document.createElement("td");
-    td.colSpan = 2; td.className = "muted";
+    td.colSpan = 4; td.className = "muted";
     td.textContent = msg;
     tr.appendChild(td); membersBody.appendChild(tr);
   }
@@ -206,7 +301,9 @@
       const body = await res.json().catch(() => ({}));
       if (res.ok) {
         const already = body.changed === false;
-        showMsg("ok", (already ? "Already a developer — re-sent the sign-in email to " : "Invited ") + (body.developer || email) + ".");
+        const who = body.developer || email;
+        showVerdict(who, body.verified,
+          (already ? "Already a developer — re-sent the sign-in email to " : "Invited ") + who + ".");
         $("email").value = "";
         if (noteEl) noteEl.value = "";
         loadMembers();

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

@@ -0,0 +1,156 @@
+/**
+ * Developer-access verification — asks tot-mcp whether an invited developer's access to a
+ * store actually resolves, walking the same chain their sign-in and checkout use, and
+ * classifies the answer for the granter.
+ *
+ *   POST {origin(MCP_APP_BINDING_URL)}/internal/dev-access/explain
+ *     header  x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>
+ *     body    { person: <email>, tenant: <appDomain> }
+ *     → 200 { verified, failedStep?, reason?, fix?, capability?, expiry?, app?, steps[] }
+ * Contract source of truth: tot-mcp src/modules/mcp/access/access-explain.ts.
+ *
+ * A failure in a step that can only pass once the invitee accepts and signs in (identity,
+ * the store context, a fresh session, checkout) reads as "awaiting acceptance" while the
+ * invite is pending. Any other failure — the repo is not provisioned, the invite record
+ * and sign-in disagree — is broken now, and the granter is told before they leave.
+ *
+ * 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";
+
+const EXPLAIN_TIMEOUT_MS = 8000;
+
+export interface ExplainStep {
+  step: string;
+  status: "pass" | "fail" | "skip" | "info";
+  dependsOnAcceptance: boolean;
+  detail: string;
+}
+
+/** tot-mcp's explain result, as sent. */
+export interface AccessExplanation {
+  verified: boolean;
+  tenant: string;
+  failedStep?: string;
+  reason?: string;
+  fix?: string;
+  capability?: string;
+  expiry?: "none";
+  app?: string;
+  steps: ExplainStep[];
+}
+
+/** The granter-facing verdict. */
+export type AccessVerification =
+  | { state: "verified"; capability: string; expiry: "none"; advice: "tot-mcp" }
+  | {
+    state: "awaiting-acceptance";
+    inviteStatus: "pending" | "accepted";
+    failedStep: string;
+    reason: string;
+    fix: string;
+    advice: "tot-mcp";
+  }
+  | { state: "broken"; failedStep: string; reason: string; fix: string; advice: "tot-mcp" }
+  | { state: "unavailable"; reason: string; advice: "tot-mcp" };
+
+/** POST transport seam (injectable for tests). */
+export interface ExplainTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+export class FetchExplainTransport implements ExplainTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), EXPLAIN_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: JSON.stringify(body),
+        signal: ctrl.signal,
+      });
+      return { status: res.status, json: () => res.json() };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** Classify an explanation against what the storefront knows about the invite. */
+export function classifyExplanation(
+  explanation: AccessExplanation,
+  inviteStatus: "pending" | "accepted",
+): AccessVerification {
+  if (explanation.verified) {
+    return {
+      state: "verified",
+      capability: explanation.capability ?? "preview-access",
+      expiry: "none",
+      advice: "tot-mcp",
+    };
+  }
+  const failed = explanation.steps.find((s) => s.step === explanation.failedStep);
+  const verdict = {
+    failedStep: explanation.failedStep ?? "unknown",
+    reason: explanation.reason ?? "Access does not resolve.",
+    fix: explanation.fix ?? "Run access_explain for this developer and store.",
+    advice: "tot-mcp" as const,
+  };
+  // Accepting on the storefront does not enroll the tot identity — the developer's first
+  // tot sign-in does — so an unenrolled identity is still waiting on them, accepted or not.
+  if (
+    explanation.failedStep === "identity"
+    || (inviteStatus === "pending" && failed?.dependsOnAcceptance)
+  ) {
+    return { state: "awaiting-acceptance", inviteStatus, ...verdict };
+  }
+  return { state: "broken", ...verdict };
+}
+
+/** Ask tot-mcp to explain `email`'s access to `tenant`. Never throws. */
+export async function explainDeveloperAccess(
+  tenant: string,
+  email: string,
+  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) {
+    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 {
+    return { state: "unavailable", reason: "the tot-mcp address is malformed", advice: "tot-mcp" };
+  }
+  const transport = deps.transport ?? new FetchExplainTransport();
+  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" };
+    }
+    return classifyExplanation(explanation, inviteStatus);
+  } catch (cause) {
+    return {
+      state: "unavailable",
+      reason: "tot-mcp did not answer: " + (cause instanceof Error ? cause.message : String(cause)),
+      advice: "tot-mcp",
+    };
+  }
+}

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

@@ -55,6 +55,7 @@
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
 import { checkStorePreviewReady, type PreflightDecision } from "@/lib/shared/invitePreflight";
+import { explainDeveloperAccess, type AccessVerification } from "@/lib/shared/accessExplain";
 
 /**
  * The header carrying the storefront-signed staff BROKER ASSERTION to tot20
@@ -244,6 +245,8 @@ export interface DeveloperInviteSummary {
   tenant: string;
   developer: string;
   roles: string[];
+  /** tot20's invite state; an entry predating the field is an active member (`accepted`). */
+  status: "pending" | "accepted";
 }
 
 /** Result of listing a tenant's developer invites (typed failure, fail-closed). */
@@ -729,6 +732,7 @@ export function normalizeInvitesListResponse(
         roles: Array.isArray(r.roles)
           ? r.roles.filter((x): x is string => typeof x === "string")
           : [],
+        status: r.status === "pending" ? "pending" : "accepted",
       };
     });
     return { ok: true, tenant, invites };
@@ -945,6 +949,7 @@ export class MockDeveloperInviteClient implements DeveloperInviteClient {
           tenant: t,
           developer: email,
           roles: ["developer"],
+          status: "pending" as const,
         };
       });
     return { ok: true, tenant: t, invites };
@@ -1035,7 +1040,7 @@ export type AppBindingResult =
  *
  * WIRED (confirmed contract):
  *   POST `${MCP_APP_BINDING_URL}`  — the keyless subject-capability writer,
- *     e.g. https://mcp.qa.tokenoftrust.com/api/internal/dev-access/subject-capability
+ *     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' }
@@ -1191,6 +1196,8 @@ export interface InviteDeveloperOutcome {
    * (a failed invite has nothing to bind); undefined otherwise.
    */
   appBinding?: AppBindingResult;
+  /** Whether the grant resolves for the invitee (tot-mcp access_explain); success only. */
+  verification?: AccessVerification;
 }
 
 /** Injectable collaborators (tests); both default to the env-configured impls. */
@@ -1207,6 +1214,12 @@ export interface InviteDeveloperDeps {
    * any inconclusive answer fails open (see invitePreflight).
    */
   preflight?: (tenant: string) => Promise<PreflightDecision>;
+  /** The post-write verification. Defaults to {@link explainDeveloperAccess}. */
+  explain?: (
+    tenant: string,
+    email: string,
+    inviteStatus: "pending" | "accepted",
+  ) => Promise<AccessVerification>;
 }
 
 /**
@@ -1291,5 +1304,17 @@ export async function inviteDeveloperToTenant(
     tenant: invite.tenant,
     capability,
   });
-  return { invite, appBinding };
+
+  // Prove the grant resolves before the granter leaves: tot-mcp walks the invitee's real
+  // sign-in + checkout chain. The invite's own state decides whether an acceptance-bound
+  // failure is "awaiting acceptance" or broken — a re-invite of an accepted developer must
+  // resolve now.
+  const listed = await client.listInvites(invite.tenant, input.brokerAssertion);
+  const inviteStatus = listed.ok
+    ? listed.invites.find((i) => i.developer.toLowerCase() === invite.developer.toLowerCase())
+      ?.status ?? "pending"
+    : "pending";
+  const explain = deps.explain ?? explainDeveloperAccess;
+  const verification = await explain(invite.tenant, invite.developer, inviteStatus);
+  return { invite, appBinding, verification };
 }

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

@@ -3,7 +3,8 @@
  * VIEWER's REAL, owner-revocable ship capability over a tenant, LIVE from the MCP
  * subject-capability store. This is the near-side read of the Step-1 tot-mcp seam:
  *
- *   GET `${origin}/api/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   GET `${origin}/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   (outside tot-mcp's session-guarded `/api` surface, which answers this caller 401)
  *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (NOT a bearer)
  *   → 200 { capability: "ship-on-behalf" | "preview-access" }
  *        · an ABSENT / REVOKED grant answers `preview-access`
@@ -58,7 +59,7 @@ export interface ViewerShipGrantDeps {
 }
 
 /** The Step-1 subject-capability reader path (mounted OUTSIDE the session guard). */
-const SUBJECT_CAPABILITY_PATH = "/api/internal/dev-access/subject-capability";
+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`

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

@@ -26,6 +26,7 @@ import {
 import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
 import { normalizeEmailHint } from "@/lib/privacy/emailHint";
 import { acceptDeveloperInvite } from "@/lib/shared/developerInvites";
+import { explainDeveloperAccess } from "@/lib/shared/accessExplain";
 
 export const prerender = false;
 
@@ -158,5 +159,20 @@ 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.
+  try {
+    const verification = await explainDeveloperAccess(tenant, derived.email, "accepted");
+    if (verification.state === "broken") {
+      console.warn("auth/magic-exchange: accepted invite does not resolve", {
+        tenant,
+        failedStep: verification.failedStep,
+      });
+    }
+  } catch {
+    /* verification must never break the sign-in */
+  }
+
   return context.redirect(next, 303);
 }

package/package.json

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