@tokenoftrust/storefront-runner 4.7.10 → 4.8.1

package/apps/storefront/astro.config.mjs

@@ -59,6 +59,7 @@ const gitSha = (() => {
 import preact from "@astrojs/preact";
 import tailwindcss from "@tailwindcss/vite";
 import { tenantHotReload } from "./dev-plugins/tenant-hot-reload.mjs";
+import { devAuthOutbox } from "./dev-plugins/dev-auth-outbox.mjs";
 import { materializeGuard } from "./integrations/materialize-guard.mjs";
 import { lifecycleHostAsset } from "./integrations/lifecycle-host-asset.mjs";
 import { googleMeasurementSandboxAsset } from "./integrations/google-measurement-sandbox-asset.mjs";
@@ -133,7 +134,7 @@ export default defineConfig({
       __CLI_INSTALL_SPEC__: JSON.stringify(cliInstallSpec),
       __GIT_SHA__: JSON.stringify(gitSha),
     },
-    plugins: [tailwindcss(), tenantHotReload()],
+    plugins: [tailwindcss(), tenantHotReload(), devAuthOutbox()],
     optimizeDeps: {
       // Vite's SSR optimizer can try to prebundle the Cloudflare adapter's
       // worker entrypoints, then the worker runner looks for a generated

package/apps/storefront/dev-plugins/dev-auth-outbox.mjs

@@ -0,0 +1,181 @@
+// @ts-check
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// DEV_AUTH=1 local sign-in code delivery. Dev-only (`apply: "serve"`), never reaches
+// the production Worker.
+//
+// The one-time code is minted inside workerd (POST /api/auth/send), which has no host
+// filesystem, so it hands the code to this Node-side endpoint. The endpoint appends it to
+// apps/storefront/.dev-auth/outbox.txt (directory 0700, file 0600, gitignored) — readable
+// only by the developer who owns the checkout. The code and the address are never written
+// to the console or to any response.
+//
+// Wiring: on POST /api/auth/send this plugin stamps the request with the outbox URL and a
+// per-process token (`x-tot-dev-auth-outbox`, `x-tot-dev-auth-outbox-token`). Both headers
+// are overwritten on that route and stripped from every other request, so a browser can
+// neither forge them nor learn the token.
+
+export const OUTBOX_PATH = "/__tot/dev-auth-outbox";
+export const OUTBOX_URL_HEADER = "x-tot-dev-auth-outbox";
+export const OUTBOX_TOKEN_HEADER = "x-tot-dev-auth-outbox-token";
+const SEND_ROUTE = "/api/auth/send";
+
+const EMAIL_SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const CODE_SHAPE = /^\d{6}$/;
+
+/** Default outbox file: apps/storefront/.dev-auth/outbox.txt */
+export const DEFAULT_OUTBOX_FILE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  ".dev-auth",
+  "outbox.txt",
+);
+
+/** @param {any} req @returns {Promise<string>} */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (/** @type {any} */ c) => {
+      data += c;
+      if (data.length > 16 * 1024) req.destroy();
+    });
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(data));
+  });
+}
+
+/** @param {string | undefined} address */
+export function isLoopback(address) {
+  if (!address) return false;
+  return address === "::1" || address === "::ffff:127.0.0.1" || address.startsWith("127.");
+}
+
+/** @param {string} a @param {string} b */
+function tokenMatches(a, b) {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * The outbox endpoint as a plain function, so it is testable without a dev server.
+ * Returns the HTTP status it answered with.
+ *
+ * @param {{ outboxFile: string, token: string, log: (line: string) => void, now?: () => Date }} opts
+ */
+export function createOutboxHandler({ outboxFile, token, log, now = () => new Date() }) {
+  /**
+   * @param {{ remoteAddress?: string, headers: Record<string, string | string[] | undefined>, body: string }} input
+   * @returns {number}
+   */
+  return function handle({ remoteAddress, headers, body }) {
+    if (!isLoopback(remoteAddress)) return 403;
+    const presented = headers[OUTBOX_TOKEN_HEADER];
+    if (typeof presented !== "string" || !tokenMatches(presented, token)) return 403;
+    /** @type {any} */
+    let parsed;
+    try {
+      parsed = JSON.parse(body || "{}");
+    } catch {
+      return 400;
+    }
+    const email = typeof parsed?.email === "string" ? parsed.email : "";
+    const code = typeof parsed?.code === "string" ? parsed.code : "";
+    const ttl = Number.isInteger(parsed?.ttlSeconds) && parsed.ttlSeconds > 0 ? parsed.ttlSeconds : 0;
+    if (!EMAIL_SHAPE.test(email) || !CODE_SHAPE.test(code) || /[\r\n]/.test(email)) return 400;
+
+    const at = now();
+    const expires = ttl ? new Date(at.getTime() + ttl * 1000).toISOString() : "unknown";
+    mkdirSync(dirname(outboxFile), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(outboxFile), 0o700);
+    appendFileSync(
+      outboxFile,
+      `${at.toISOString()}  ${email}  code ${code}  valid until ${expires}  (single use)\n`,
+      { mode: 0o600 },
+    );
+    chmodSync(outboxFile, 0o600);
+    log(`[DEV AUTH] sign-in code delivered to ${outboxFile} (owner-only)`);
+    return 204;
+  };
+}
+
+/**
+ * Remove any client-supplied outbox headers, then set `set`. Both `headers` and
+ * `rawHeaders` are rewritten, because request adapters differ in which one they read.
+ *
+ * @param {any} req @param {Record<string, string>} set
+ */
+export function stampHeaders(req, set) {
+  const names = [OUTBOX_URL_HEADER, OUTBOX_TOKEN_HEADER];
+  for (const n of names) delete req.headers[n];
+  if (Array.isArray(req.rawHeaders)) {
+    /** @type {string[]} */
+    const kept = [];
+    for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
+      if (!names.includes(String(req.rawHeaders[i]).toLowerCase())) {
+        kept.push(req.rawHeaders[i], req.rawHeaders[i + 1]);
+      }
+    }
+    for (const [k, v] of Object.entries(set)) kept.push(k, v);
+    req.rawHeaders.length = 0;
+    req.rawHeaders.push(...kept);
+  }
+  for (const [k, v] of Object.entries(set)) req.headers[k] = v;
+}
+
+/** @param {any} server @returns {string} */
+function outboxUrl(server) {
+  const addr = server.httpServer?.address?.();
+  if (!addr || typeof addr === "string") return "";
+  const host = addr.family === "IPv6" || addr.family === 6 ? `[${addr.address === "::" ? "::1" : addr.address}]` : addr.address === "0.0.0.0" ? "127.0.0.1" : addr.address;
+  return `http://${host}:${addr.port}${OUTBOX_PATH}`;
+}
+
+/** @param {{ outboxFile?: string }} [opts] */
+export function devAuthOutbox(opts = {}) {
+  const outboxFile = opts.outboxFile ?? DEFAULT_OUTBOX_FILE;
+  const token = randomBytes(32).toString("hex");
+  const handle = createOutboxHandler({
+    outboxFile,
+    token,
+    // eslint-disable-next-line no-console -- pointer only; never the code or address
+    log: (line) => console.log(line),
+  });
+
+  /** @type {any} */
+  const plugin = {
+    name: "tot:dev-auth-outbox",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.middlewares.use(
+        async (/** @type {any} */ req, /** @type {any} */ res, /** @type {any} */ next) => {
+          const path = (req.url ?? "").split("?")[0];
+          if (path === OUTBOX_PATH) {
+            if (req.method !== "POST") {
+              res.statusCode = 405;
+              res.end();
+              return;
+            }
+            const status = handle({
+              remoteAddress: req.socket?.remoteAddress,
+              headers: req.headers,
+              body: await readBody(req),
+            });
+            res.statusCode = status;
+            res.setHeader("cache-control", "no-store");
+            res.end();
+            return;
+          }
+          const url = req.method === "POST" && path === SEND_ROUTE ? outboxUrl(server) : "";
+          stampHeaders(req, url ? { [OUTBOX_URL_HEADER]: url, [OUTBOX_TOKEN_HEADER]: token } : {});
+          next();
+        },
+      );
+    },
+  };
+  return plugin;
+}

package/apps/storefront/src/components/content/storefront/blog/PostGrid.astro

@@ -10,9 +10,13 @@ interface Props {
   posts: BlogPostSummary[];
   basePath: string;
   paths: CollectionPathsV1;
+  /** Card title level. An archive page uses h2; a section under its own h2 uses h3. */
+  headingLevel?: "h2" | "h3";
+  /** Leading cards whose image loads eagerly. Below-the-fold placements pass 0. */
+  eagerCount?: number;
 }
 
-const { posts, basePath, paths } = Astro.props;
+const { posts, basePath, paths, headingLevel = "h2", eagerCount = 3 } = Astro.props;
 const href = (path: string) => `${basePath}${path}` || "/";
 ---
 
@@ -26,14 +30,14 @@ const href = (path: string) => `${basePath}${path}` || "/";
             alt={post.featuredImage.alt}
             width={post.featuredImage.width}
             height={post.featuredImage.height}
-            loading={index < 3 ? "eager" : "lazy"}
+            loading={index < eagerCount ? "eager" : "lazy"}
             decoding="async"
           />
         ) : <div class="image-placeholder" aria-hidden="true"></div>}
         <div class="post-card-copy">
           <p class="post-meta"><time datetime={post.publishedAt}>{new Date(post.publishedAt).toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" })}</time>{post.tags[0] && <> · {post.tags[0]}</>}</p>
           <PostAccessBadge access={post.access} />
-          <h2>{post.title}</h2>
+          {headingLevel === "h3" ? <h3>{post.title}</h3> : <h2>{post.title}</h2>}
           <p>{post.excerpt}</p>
           <span>Read article <span aria-hidden="true">→</span></span>
         </div>
@@ -50,7 +54,7 @@ const href = (path: string) => `${basePath}${path}` || "/";
   .post-card img, .image-placeholder { width: 100%; aspect-ratio: 16 / 9; object-fit: cover; background: linear-gradient(135deg, color-mix(in srgb, var(--color-primary) 12%, white), color-mix(in srgb, var(--color-accent) 24%, white)); }
   .post-card-copy { display: flex; flex: 1; flex-direction: column; padding: 1.25rem; }
   .post-meta { margin: 0 0 .7rem; color: var(--color-muted); font: 600 .72rem/1.45 var(--font-mono); text-transform: uppercase; letter-spacing: .05em; }
-  .post-card h2 { font-size: 1.18rem; line-height: 1.25; }
+  .post-card h2, .post-card h3 { font-size: 1.18rem; line-height: 1.25; }
   .post-card-copy > p:not(.post-meta) { display: -webkit-box; margin: .75rem 0 1rem; overflow: hidden; color: var(--color-muted); font-size: .92rem; -webkit-line-clamp: 3; -webkit-box-orient: vertical; }
   .post-card-copy > span { margin-top: auto; color: var(--color-accent-ink); font-weight: 700; font-size: .88rem; }
   @media (max-width: 980px) { .post-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }

package/apps/storefront/src/lib/access/auth/devAuth.ts

@@ -3,8 +3,10 @@
  *
  * On localhost tot20 isn't reachable, so real sign-in/invite emails can't be sent
  * or verified. This module lets a developer complete sign-in locally: `/api/auth/send`
- * prints a one-time code to the server console + stores it here; `/api/auth/verify`
- * consumes it and mints a session WITHOUT tot20/JWKS.
+ * stores a one-time code here and delivers it to the owner-private local outbox
+ * (`apps/storefront/.dev-auth/outbox.txt`, written by `dev-plugins/dev-auth-outbox.mjs`);
+ * `/api/auth/verify` consumes it and mints a session WITHOUT tot20/JWKS. The code is
+ * never printed to the console or returned in a response.
  *
  * SECURITY — this must never exist in a deployed build:
  *   1. EVERY call site MUST wrap use in `if (import.meta.env.DEV)`. That is a STATIC
@@ -54,6 +56,36 @@ export async function storeDevCode(kv: CodeKv, email: string, code: string): Pro
   });
 }
 
+/** Headers the dev-auth-outbox Vite plugin stamps onto POST /api/auth/send. */
+export const DEV_AUTH_OUTBOX_URL_HEADER = "x-tot-dev-auth-outbox";
+export const DEV_AUTH_OUTBOX_TOKEN_HEADER = "x-tot-dev-auth-outbox-token";
+
+/**
+ * Hand `code` to the dev server's owner-private outbox. Returns false when the outbox
+ * plugin isn't wired (no stamped headers) or the write fails; never throws, and never
+ * logs the code or the address.
+ */
+export async function deliverDevCode(
+  request: Request,
+  email: string,
+  code: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  const url = request.headers.get(DEV_AUTH_OUTBOX_URL_HEADER);
+  const token = request.headers.get(DEV_AUTH_OUTBOX_TOKEN_HEADER);
+  if (!url || !token) return false;
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", [DEV_AUTH_OUTBOX_TOKEN_HEADER]: token },
+      body: JSON.stringify({ email, code, ttlSeconds: DEV_AUTH_CODE_TTL_SECONDS }),
+    });
+    return res.status === 204;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * One-time consume: returns true iff `code` matches the stored code for `email`,
  * deleting it on success so a code can't be replayed.

package/apps/storefront/src/lib/access/auth/route.ts

@@ -171,7 +171,41 @@ export function safeNext(next: string | null | undefined): string {
   return next;
 }
 
-/** Redirect back to the login page carrying step-2 state (email/error), no-JS-safe. */
+/**
+ * The address being signed in, carried between the login steps. It rides an HttpOnly
+ * cookie rather than the redirect URL, so it never lands in access logs, browser
+ * history, Referer headers or analytics. Its lifetime matches a sign-in code's.
+ */
+export const LOGIN_EMAIL_COOKIE = "tot_login_email";
+export const LOGIN_EMAIL_MAX_AGE_SECONDS = 600;
+
+type CookieContext = { cookies: APIContext["cookies"] };
+
+export function setLoginEmailCookie(context: CookieContext, email: string): void {
+  context.cookies.set(LOGIN_EMAIL_COOKIE, email, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/",
+    maxAge: LOGIN_EMAIL_MAX_AGE_SECONDS,
+  });
+}
+
+/** The in-progress sign-in address, or "" when absent or not email-shaped. */
+export function readLoginEmail(context: CookieContext): string {
+  const value = context.cookies.get(LOGIN_EMAIL_COOKIE)?.value ?? "";
+  return EMAIL_RE.test(value) ? value : "";
+}
+
+export function clearLoginEmailCookie(context: CookieContext): void {
+  context.cookies.delete(LOGIN_EMAIL_COOKIE, { path: "/" });
+}
+
+/**
+ * Redirect back to the login page carrying step-2 state, no-JS-safe. The query holds
+ * only finite state (`sent`, `error`, `reason`, `requiredAcr`, `next`); a supplied
+ * `email` goes to the HttpOnly login-email cookie, never the URL.
+ */
 export function loginRedirect(
   context: APIContext,
   params: {
@@ -189,9 +223,9 @@ export function loginRedirect(
     requiredAcr?: string;
   },
 ): Response {
+  if (params.email) setLoginEmailCookie(context, params.email);
   const q = new URLSearchParams();
   if (params.sent) q.set("sent", "1");
-  if (params.email) q.set("email", params.email);
   if (params.error) q.set("error", params.error);
   if (params.reason) q.set("reason", params.reason);
   if (params.requiredAcr) q.set("requiredAcr", params.requiredAcr);

package/apps/storefront/src/lib/access/auth/totAccessClient.ts

@@ -27,7 +27,6 @@
  * bodies, response shapes) is contract-fixed.
  */
 import { readEnv } from "@/lib/publication/shared/env";
-import { diagEmail } from "@/lib/observability/diag/redact";
 import { FetchHttpTransport, type HttpResponseLike, type HttpTransport } from "@/lib/developer-experience/http/fetchTransport";
 import { classifyStepUp, type StepUpChallenge, type StepUpObligation } from "./stepUpChallenge.js";
 
@@ -249,26 +248,15 @@ export class HttpTotAccessClient implements TotAccessClient {
         {},
         { email: email.toLowerCase(), ...this.credentialFields() },
       );
-      let body: unknown = "(unread)";
+      // Finite fields only: no address, domain, or upstream body content.
       try {
-        body = await res.json();
-      } catch {
-        body = "(non-JSON)";
-      }
-      try {
-        console.info(
-          "[diag:federated-send]",
-          JSON.stringify({ email: diagEmail(email.toLowerCase()), status: res.status, body }),
-        );
+        console.info("[diag:federated-send]", JSON.stringify({ status: res.status }));
       } catch {
         /* never break */
       }
     } catch (e) {
       try {
-        console.warn(
-          "[diag:federated-send] transport error",
-          e instanceof Error ? e.message : String(e),
-        );
+        console.warn("[diag:federated-send] transport error");
       } catch {
         /* never break */
       }
@@ -333,9 +321,9 @@ export class HttpTotAccessClient implements TotAccessClient {
           ...this.credentialFields(),
         },
       );
-    } catch (e) {
+    } catch {
       try {
-        console.warn("[diag:mint] transport error", e instanceof Error ? e.message : String(e));
+        console.warn("[diag:mint] transport error");
       } catch {
         /* never break */
       }
@@ -353,7 +341,7 @@ export class HttpTotAccessClient implements TotAccessClient {
     // (only present on success) is never in this branch, so nothing sensitive leaks.
     if (!result.ok) {
       try {
-        console.warn("[diag:mint]", JSON.stringify({ status: res.status, body }));
+        console.warn("[diag:mint]", JSON.stringify({ status: res.status }));
       } catch {
         /* never break */
       }

package/apps/storefront/src/lib/access/dashboard/staffStoreEntry.ts

@@ -21,6 +21,7 @@ import { updateSession } from "@/lib/access/auth/session";
 import { isStaffSession, buildStaffSelection } from "./staffAdmission";
 import {
   createStaffVendorAccessClient,
+  staffAccessFailureMessage,
   staffAccessHttpStatus,
   StaffVendorAccessClientError,
 } from "./staffVendorAccess";
@@ -89,7 +90,7 @@ export async function enterStoreAsStaff(input: StaffStoreEntryInput): Promise<St
     return {
       ok: false,
       status: staffAccessHttpStatus(result.reason, result.status),
-      body: { error: result.message, reason: result.reason, code: result.code },
+      body: { error: staffAccessFailureMessage(result.reason), reason: result.reason, code: result.code },
     };
   }
 

package/apps/storefront/src/lib/access/dashboard/staffVendorAccess.ts

@@ -188,9 +188,7 @@ export class HttpStaffVendorAccessClient implements StaffVendorAccessClient {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "staffVendorAccess: transport failure searching vendors " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "staffVendorAccess: transport failure searching vendors",
       };
     }
     let parsed: unknown;
@@ -228,9 +226,7 @@ export class HttpStaffVendorAccessClient implements StaffVendorAccessClient {
         ok: false,
         status: 0,
         reason: "error",
-        message:
-          "staffVendorAccess: transport failure granting access " +
-          (cause instanceof Error ? cause.message : String(cause)),
+        message: "staffVendorAccess: transport failure granting access",
       };
     }
     let parsed: unknown;
@@ -295,9 +291,8 @@ function failure(
   c: Record<string, unknown>,
 ): { ok: false; status: number; reason: StaffAccessFailureReason; message: string; code?: string } {
   const code = typeof c.code === "string" ? c.code : undefined;
-  const message = typeof c.message === "string" ? c.message : undefined;
   const reason = reasonFor(code, status);
-  return { ok: false, status, reason, message: message ?? defaultMessage(reason, status), ...(code ? { code } : {}) };
+  return { ok: false, status, reason, message: staffAccessFailureMessage(reason), ...(code ? { code } : {}) };
 }
 
 function reasonFor(code: string | undefined, status: number): StaffAccessFailureReason {
@@ -340,7 +335,8 @@ export function staffAccessHttpStatus(reason: StaffAccessFailureReason, upstream
   }
 }
 
-function defaultMessage(reason: StaffAccessFailureReason, status: number): string {
+/** Finite staff-facing copy for a staff-access refusal — the only text a route returns. */
+export function staffAccessFailureMessage(reason: StaffAccessFailureReason): string {
   switch (reason) {
     case "notStaff":
       return "this account doesn't hold ToT-staff access to that vendor";
@@ -351,7 +347,7 @@ function defaultMessage(reason: StaffAccessFailureReason, status: number): strin
     case "invalid":
       return "a valid vendor is required";
     default:
-      return `staffVendorAccess: tot20 returned status ${status}`;
+      return "Token of Trust couldn't complete the staff-access request; try again shortly";
   }
 }
 

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

@@ -41,19 +41,109 @@ export interface AccessExplanation {
   steps: ExplainStep[];
 }
 
-/** The granter-facing verdict. */
+/** The steps tot-mcp's explain can fail on (tot-mcp access-explain-advice.ts `AccessStep`). */
+export const ACCESS_STEPS = [
+  "identity",
+  "broker",
+  "tenant-context",
+  "capability-row",
+  "row-resolution",
+  "repo-provisioned",
+  "session-scope",
+  "checkout",
+] as const;
+
+export type AccessStep = (typeof ACCESS_STEPS)[number];
+export type VerdictStep = AccessStep | "unknown";
+
+/**
+ * The reason and fix shown for each failed step. The storefront owns this copy: tot-mcp's
+ * own `reason`/`fix` are fixed text today, but the granter's page and its logs must not
+ * depend on a remote service never putting identity detail there.
+ */
+export const STEP_ADVICE = {
+  // Each value is ONE string literal: `"a" + "b"` widens to `string` even under
+  // `as const`, which would make StepReason/StepFix free text again.
+  identity: {
+    reason:
+      "This person has no Token of Trust identity enrolled with tot-mcp yet, so no session of theirs can resolve any store.",
+    fix: "Have them accept the invite and sign in once (`tot login`, or connect the tot MCP and complete sign-in). If they already have, run identity_link_begin from their session; enrollment did not happen at sign-in.",
+  },
+  broker: {
+    reason: "Token of Trust did not answer the store enumeration for this identity.",
+    fix: "Retry in a minute. If it persists, the broker is failing for this identity — file it with this result attached.",
+  },
+  "tenant-context": {
+    reason:
+      "Token of Trust does not list this store for this identity: the invite is still pending, or it was accepted under a different email address.",
+    fix: "Confirm the invitee accepted from the exact address invited. If they accepted from a different address, resend the invite to the address they sign in with.",
+  },
+  "capability-row": {
+    reason: "No invite record exists for this person on this store.",
+    fix: "Resend the invite.",
+  },
+  "row-resolution": {
+    reason:
+      "The invite record and the sign-in read disagree about this person — the two paths resolve different identities.",
+    fix: "This is a tot-mcp defect, not a setup problem. File it with this result attached.",
+  },
+  "repo-provisioned": {
+    reason: "The store has no provisioned code repository, so there is nothing to check out.",
+    fix: "Provision the store repository first (Team page \"Provision now\", or repo_provision).",
+  },
+  "session-scope": {
+    reason:
+      "Token of Trust lists the store for this identity, but a fresh session built from that answer does not hold it.",
+    fix: "This is a tot-mcp defect, not a setup problem. File it with this result attached.",
+  },
+  checkout: {
+    reason: "A session holds the store, but checkout cannot resolve its repository.",
+    fix: "Provision the store repository, or resend the invite so it records the app binding.",
+  },
+  unknown: {
+    reason: "Access does not resolve.",
+    fix: "Run access_explain for this developer and store.",
+  },
+} as const satisfies Record<VerdictStep, { reason: string; fix: string }>;
+
+export type StepReason = (typeof STEP_ADVICE)[VerdictStep]["reason"];
+export type StepFix = (typeof STEP_ADVICE)[VerdictStep]["fix"];
+
+/** Why a verification could not be completed; never upstream text. */
+export const UNAVAILABLE_REASONS = [
+  "verification is not configured here",
+  "the tot-mcp address is malformed",
+  "tot-mcp did not answer",
+  "tot-mcp refused the verification request",
+  "tot-mcp sent an unreadable answer",
+  "not verified",
+] as const;
+
+export type UnavailableReason = (typeof UNAVAILABLE_REASONS)[number];
+
+const STEPS: ReadonlySet<string> = new Set(ACCESS_STEPS);
+
+/** The finite step for a value tot-mcp sent ("unknown" when it is not one we know). */
+export function verdictStepOf(value: unknown): VerdictStep {
+  return typeof value === "string" && STEPS.has(value) ? (value as AccessStep) : "unknown";
+}
+
+/** The capability a verified invitee holds (the invite always writes this one). */
+const VERIFIED_CAPABILITY = "preview-access";
+
+/** The granter-facing verdict. Every string in it is storefront-owned, finite copy. */
 export type AccessVerification =
-  | { state: "verified"; capability: string; expiry: "none"; advice: "tot-mcp" }
+  | { state: "verified"; capability: typeof VERIFIED_CAPABILITY; expiry: "none"; advice: "tot-mcp" }
   | {
     state: "awaiting-acceptance";
     inviteStatus: "pending" | "accepted";
-    failedStep: string;
-    reason: string;
-    fix: string;
+    failedStep: VerdictStep;
+    reason: StepReason;
+    fix: StepFix;
     advice: "tot-mcp";
   }
-  | { state: "broken"; failedStep: string; reason: string; fix: string; advice: "tot-mcp" }
-  | { state: "unavailable"; reason: string; advice: "tot-mcp" };
+  | { state: "broken"; failedStep: VerdictStep; reason: StepReason; fix: StepFix; advice: "tot-mcp" }
+  | { state: "unavailable"; reason: UnavailableReason; advice: "tot-mcp" };
 
 /** POST transport seam (injectable for tests). */
 export interface ExplainTransport {
@@ -88,18 +178,14 @@ export function classifyExplanation(
   inviteStatus: "pending" | "accepted",
 ): AccessVerification {
   if (explanation.verified) {
-    return {
-      state: "verified",
-      capability: explanation.capability ?? "preview-access",
-      expiry: "none",
-      advice: "tot-mcp",
-    };
+    return { state: "verified", capability: VERIFIED_CAPABILITY, expiry: "none", advice: "tot-mcp" };
   }
   const failed = explanation.steps.find((s) => s.step === explanation.failedStep);
+  const failedStep = verdictStepOf(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.",
+    failedStep,
+    reason: STEP_ADVICE[failedStep].reason,
+    fix: STEP_ADVICE[failedStep].fix,
     advice: "tot-mcp" as const,
   };
   // Accepting on the storefront does not enroll the tot identity — the developer's first
@@ -133,14 +219,10 @@ export async function explainDeveloperAccess(
     return { state: "unavailable", reason: "the tot-mcp address is malformed", advice: "tot-mcp" };
   }
   if (outcome.kind === "transport-error") {
-    return {
-      state: "unavailable",
-      reason: "tot-mcp did not answer: " + outcome.message,
-      advice: "tot-mcp",
-    };
+    return { state: "unavailable", reason: "tot-mcp did not answer", advice: "tot-mcp" };
   }
   if (outcome.kind === "misconfigured" || outcome.kind === "http-error") {
-    return { state: "unavailable", reason: `tot-mcp answered ${outcome.status}`, advice: "tot-mcp" };
+    return { state: "unavailable", reason: "tot-mcp refused the verification request", advice: "tot-mcp" };
   }
   const res = outcome;
   try {
@@ -149,11 +231,7 @@ export async function explainDeveloperAccess(
       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",
-    };
+  } catch {
+    return { state: "unavailable", reason: "tot-mcp sent an unreadable answer", advice: "tot-mcp" };
   }
 }