@tokenoftrust/cli 2.4.9 → 2.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.9",
+  "version": "2.4.11",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/auth.mjs

@@ -136,7 +136,7 @@ export function warnLegacyOperatorEnv(env = process.env, warn = (m) => console.e
  * @param {(import("./mcp.mjs").createMcpClient extends (...a:any)=>infer R ? R : any)|null} client
  * @param {NodeJS.ProcessEnv} env
  * @param {{ fetchImpl?: typeof fetch, now?: number }} [deps] injectable for tests
- * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null }>}
+ * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null, mcpUrl?: string|null }>}
  */
 export async function resolveDeveloperSession(client, env, deps = {}) {
   const { fetchImpl = fetch, now = Date.now() } = deps;
@@ -204,6 +204,10 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     appDomain: null,
     token: creds.accessToken,
     email: emailFromJwt(creds.accessToken),
+    // The MCP this developer is signed in to — so a caller can tell the human
+    // which MCP their OWN session is against when a store reports it trusts a
+    // different one (the tier-mismatch case: signed in to qa, store trusts prod).
+    mcpUrl: creds.mcpUrl || null,
   };
 }
 
@@ -228,7 +232,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
  *
  * @param {ReturnType<import("./mcp.mjs").createMcpClient>} client
  * @param {{ env?: NodeJS.ProcessEnv, initialize?: () => Promise<any>, prefer?: string }} [opts]
- * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null }>}
+ * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null, mcpUrl?: string|null }>}
  */
 export async function establishSession(client, opts = {}) {
   const env = opts.env || process.env;

package/src/commands/hotfix.mjs

@@ -36,6 +36,7 @@ import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 // Reuse `tot ship`'s operator-secret precedence + live-url derivation verbatim so
 // ship + hotfix speak ONE operator-auth contract.
 import { resolveOperatorSecret, liveUrlFor } from "./ship.mjs";
@@ -245,18 +246,27 @@ export async function runHotfix(
     return 1;
   }
   const planData = await readJsonSafe(planRes);
-  if (!planRes.ok && planData?.ok !== false) {
+  if (planRes.status === 401 || planRes.status === 403) {
+    // The admission rule's own refusal (body shape `{ ok:false, error,
+    // admission:{ missing } }`) — name exactly what's missing instead of a
+    // generic "check the operator secret" when the server named one.
     const msg = planData?.error || `HTTP ${planRes.status}`;
+    const missing = missingGrantsOf(planData);
     console.error(
       fail(
         `the hotfix plan was refused: ${msg}`,
-        planRes.status === 401 || planRes.status === 403
-          ? "check the operator secret and that it's authorised for this tenant"
-          : "check --tenant / --url / --pr, then re-run",
+        missing.length > 0 ? refusalHint(planRes.status, missing) : "check the operator secret and that it's authorised for this tenant",
       ),
     );
     return 1;
   }
+  if (!planRes.ok && planData?.ok !== false) {
+    // A transport-level refusal the endpoint didn't explain in its own shape
+    // (tenant-resolution/network) — surface it honestly.
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(fail(`the hotfix plan was refused: ${msg}`, "check --tenant / --url / --pr, then re-run"));
+    return 1;
+  }
   const plan = normalizeHotfixPlan(planData);
   if (!plan.ok) {
     console.error(fail(plan.message, hotfixNextStep(plan.reason)));

package/src/commands/pr.mjs

@@ -41,6 +41,7 @@ import { repoNameFromRemote, currentBranch } from "./submit.mjs";
 // `tot pr list` reuses `tot ship --pr`'s operator-secret transport helpers verbatim
 // (same env precedence, same queue normalisation) so the two speak one wire, not two.
 import { resolveOperatorSecret, normalizeChangesQueue } from "./ship.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -280,11 +281,14 @@ export async function runPrListOperator({ tenant, secret, storefrontUrl = null }
   }
   if (!res.ok) {
     const msg = data?.error || `HTTP ${res.status}`;
+    const missing = missingGrantsOf(data);
     console.error(
       fail(
         `the candidate queue refused the request: ${msg}`,
         res.status === 401 || res.status === 403
-          ? "check the operator secret and that it's authorised for this tenant"
+          ? missing.length > 0
+            ? refusalHint(res.status, missing)
+            : "check the operator secret and that it's authorised for this tenant"
           : "check --tenant / --url, then re-run",
       ),
     );

package/src/commands/preview-token.mjs

@@ -14,6 +14,7 @@
  * Treat the token like a password: anyone holding it sees the unpublished site.
  */
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 
 const MAX_TTL_SECONDS = 24 * 3600;
 
@@ -107,19 +108,19 @@ export async function run(argv, ctx, deps = {}) {
     return 1;
   }
 
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON error body — this endpoint answers 401/403 as plain text */
+  }
   if (res.status === 401 || res.status === 403) {
     err(
       `✗ your account can't view ${tenant}'s preview.\n\n` +
-        "  → next: ask the store owner for developer access (or check `tot whoami`), then re-run.",
+        `  → next: ${refusalHint(res.status, missingGrantsOf(data))}.`,
     );
     return 1;
   }
-  let data = null;
-  try {
-    data = await res.json();
-  } catch {
-    /* non-JSON error body */
-  }
   if (!res.ok || typeof data?.token !== "string") {
     err(`✗ the store didn't mint a token (HTTP ${res.status}).\n\n  → next: retry shortly; if it persists, report it with \`tot feedback\`.`);
     return 1;

package/src/commands/ship.mjs

@@ -62,6 +62,7 @@ import { emitActivity } from "../activity.mjs";
 // `tot preview doctor` run.
 import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -76,6 +77,8 @@ const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live
                             accept this revision's overridable quality findings,
                             record the required reason, then continue publishing
   tot ship --no-open         don't open the live URL in your browser
+  tot ship --verbose         print each request's URL, HTTP status, and the
+                            server's error code — never a token or cookie
 
   Authentication: use your own \`tot login\` session if you own the store, hold
   a live ship-on-behalf grant, or — while the store is unpaid — were invited to
@@ -108,6 +111,7 @@ export function parseShipArgs(argv) {
     url: null,
     secret: null,
     acceptQualityReason: null,
+    verbose: false,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -118,6 +122,7 @@ export function parseShipArgs(argv) {
     else if (t === "--url") a.url = argv[++i];
     else if (t === "--secret") a.secret = argv[++i];
     else if (t === "--accept-quality-findings") a.acceptQualityReason = argv[++i];
+    else if (t === "--verbose") a.verbose = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -423,9 +428,9 @@ async function readJsonSafe(res) {
  *
  * @param {{ tenant:string, secret:string, storefrontUrl?:string|null,
  *   yes?:boolean, noOpen?:boolean, acceptQualityReason?:string|null,
- *   env?:NodeJS.ProcessEnv }} params
+ *   verbose?:boolean, env?:NodeJS.ProcessEnv }} params
  * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
- *   openUrl?:(u:string)=>boolean, progress?:boolean,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean, log?:(s:string)=>void,
  *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
  * @returns {Promise<number>} process exit code
  */
@@ -437,6 +442,7 @@ export async function runShip(
     yes = false,
     noOpen = false,
     acceptQualityReason = null,
+    verbose = false,
     env = process.env,
   },
   deps = {},
@@ -444,6 +450,9 @@ export async function runShip(
   const fetchImpl = deps.fetch || globalThis.fetch;
   const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
   const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+  // --verbose: request URL + HTTP status + the server's error code only — NEVER
+  // a token, secret, or cookie value.
+  const vlog = verbose ? (deps.log || ((s) => console.error(`[verbose] ${s}`))) : () => {};
   let base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
   let authHeaders;
   if (secret) {
@@ -453,7 +462,7 @@ export async function runShip(
       "x-tot-capability": "ship-on-behalf",
     };
   } else {
-    const viewer = await resolveViewer({ tenant, env, fetchImpl, storefrontUrl });
+    const viewer = await resolveViewer({ tenant, env, fetchImpl, storefrontUrl, verbose, log: vlog });
     if (!viewer.ok) {
       console.error(fail(viewer.message, viewer.hint));
       return 2;
@@ -472,6 +481,7 @@ export async function runShip(
 
   // 1. GET the read-only plan: the pinned sha + artifact digest + included PRs +
   //    rollback target + paywall verdict. Zero side effects.
+  vlog(`GET ${base}/api/changes/ship`);
   let planRes;
   try {
     planRes = await fetchImpl(`${base}/api/changes/ship`, { method: "GET", headers: authHeaders });
@@ -481,21 +491,35 @@ export async function runShip(
     );
     return 1;
   }
+  vlog(`ship plan → HTTP ${planRes.status}`);
   const planData = await readJsonSafe(planRes);
-  if (!planRes.ok && planData?.ok !== false) {
-    // A transport-level refusal the endpoint didn't explain in its own shape
-    // (auth/tenant-resolution/network) — surface it honestly.
+  if (verbose && !planRes.ok) {
+    const code = planData?.error || planData?.admission?.missing?.map((m) => m?.grant).join(",") || null;
+    if (code) vlog(`ship plan error: ${code}`);
+  }
+  if (planRes.status === 401 || planRes.status === 403) {
+    // The admission rule's own refusal (body shape `{ ok:false, error,
+    // admission:{ missing } }`) — name exactly what's missing instead of a
+    // generic "check the operator secret", which is actively wrong for the
+    // viewer-session transport (no operator secret involved at all).
     const msg = planData?.error || `HTTP ${planRes.status}`;
     console.error(
       fail(
         `the ship plan was refused: ${msg}`,
-        planRes.status === 401 || planRes.status === 403
+        secret
           ? "check the operator secret and that it's authorised for this tenant"
-          : "check --tenant / --url, then re-run",
+          : refusalHint(planRes.status, missingGrantsOf(planData)),
       ),
     );
     return 1;
   }
+  if (!planRes.ok && planData?.ok !== false) {
+    // A transport-level refusal the endpoint didn't explain in its own shape
+    // (tenant-resolution/network) — surface it honestly.
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(fail(`the ship plan was refused: ${msg}`, "check --tenant / --url, then re-run"));
+    return 1;
+  }
   const plan = normalizeShipPlan(planData);
   // The tenant's mounted publication spaces ride the same release (see the file header).
   const spaces = (await readSpaceRelease({ base, authHeaders, fetchImpl })) ?? { ready: [], waiting: [] };
@@ -726,6 +750,7 @@ export async function run(argv, ctx) {
       yes: args.yes,
       noOpen: args.noOpen,
       acceptQualityReason: args.acceptQualityReason,
+      verbose: args.verbose,
       env,
     },
     { openUrl: (u) => openBrowser(u) },

package/src/viewer-session.mjs

@@ -44,6 +44,66 @@ export function parseSessionCookie(setCookie) {
   return m ? m[1] : null;
 }
 
+/** @param {string|null|undefined} url @returns {string|null} */
+function originOf(url) {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Turn a non-2xx `/api/dev/cli-session` response into one clean, actionable
+ * `{ message, hint }` — the ONE place this CLI interprets that endpoint's refusal
+ * shape, so ship/preview-token (both routed through `resolveViewerTransport`)
+ * never duplicate or drift from each other.
+ *
+ * - 401 `unresolved_token` carrying `trustedMcp`, where the CLI's OWN signed-in
+ *   MCP (`signedInMcpUrl`, from `resolveDeveloperSession`) is a DIFFERENT origin
+ *   — the genuine tier mismatch (signed in to qa, store trusts prod, or vice
+ *   versa): say exactly which two origins disagree and the exact fix.
+ * - Any other 401 — a real "you're not recognized here" — keeps the plain
+ *   login hint, but still surfaces the server's error code so a report isn't
+ *   just "it didn't work".
+ * - 502/503 — the SEAM is broken (unconfigured, unreachable, malformed), which
+ *   is never a login problem: say so, with the server's code, and suggest a
+ *   retry instead of `tot login`.
+ *
+ * @param {number} status
+ * @param {Record<string, unknown>|null} body
+ * @param {string|null|undefined} signedInMcpUrl — this CLI's own `creds.mcpUrl`
+ * @returns {{ message: string, hint: string }}
+ */
+export function describeCliSessionRefusal(status, body, signedInMcpUrl) {
+  const error = body && typeof body.error === "string" ? body.error : null;
+  const code = body && typeof body.code === "string" ? body.code : null;
+  const trustedMcp = body && typeof body.trustedMcp === "string" ? body.trustedMcp : null;
+
+  if (status === 502 || status === 503) {
+    return {
+      message: `couldn't verify your session — the store's identity check failed${code ? ` (${code})` : ""}.`,
+      hint: "retry shortly; if it persists, report it with `tot feedback`.",
+    };
+  }
+
+  if (error === "unresolved_token" && trustedMcp) {
+    const signedInOrigin = originOf(signedInMcpUrl);
+    if (signedInOrigin && signedInOrigin !== trustedMcp) {
+      return {
+        message: `you're signed in to ${signedInOrigin}, but this store trusts ${trustedMcp}.`,
+        hint: `run \`tot login --mcp ${trustedMcp}\` (or unset TOT_MCP_URL), then re-run.`,
+      };
+    }
+  }
+
+  return {
+    message: `your \`tot\` session wasn't recognized for this store${error && error !== "unresolved_token" ? ` (${error})` : ""}.`,
+    hint: "run `tot login`, then re-run.",
+  };
+}
+
 /**
  * Resolve a viewer-session transport for `tenant`. Returns
  *   { ok:true, base, authHeaders }               — base = tenant host; cookie transport
@@ -54,7 +114,8 @@ export function parseSessionCookie(setCookie) {
  * developer can point the same command at a non-default deployment.
  *
  * @param {{ tenant:string, env?:NodeJS.ProcessEnv, fetchImpl?:typeof fetch,
- *   storefrontUrl?:string|null, resolveDev?:typeof resolveDeveloperSession }} params
+ *   storefrontUrl?:string|null, resolveDev?:typeof resolveDeveloperSession,
+ *   verbose?:boolean, log?:(s:string)=>void }} params
  * @returns {Promise<
  *   { ok:true, base:string, authHeaders:Record<string,string> } |
  *   { ok:false, message:string, hint:string }
@@ -66,7 +127,12 @@ export async function resolveViewerTransport({
   fetchImpl = fetch,
   storefrontUrl = null,
   resolveDev = resolveDeveloperSession,
+  verbose = false,
+  log = (s) => console.error(`[verbose] ${s}`),
 }) {
+  // --verbose: request URL + HTTP status + the server's error code only — NEVER
+  // the bearer token or the minted session cookie.
+  const vlog = verbose ? log : () => {};
   // The developer's OWN MCP token (read + silently refreshed by the resolver). No
   // client needed — resolveDeveloperSession tolerates a null client.
   let dev;
@@ -96,6 +162,7 @@ export async function resolveViewerTransport({
     // cross-origin without a CORS preflight this worker never answers, so the
     // anti-CSRF property is preserved exactly. Spoofing an `Origin` header instead
     // would assert a browser context that does not exist and protect nothing.
+    vlog(`POST ${base}/api/dev/cli-session`);
     res = await fetchImpl(`${base}/api/dev/cli-session`, {
       method: "POST",
       headers: {
@@ -111,12 +178,17 @@ export async function resolveViewerTransport({
       hint: "check the --tenant domain / your network, then re-run.",
     };
   }
-  if (res.status === 401) {
-    return {
-      ok: false,
-      message: "your `tot` session wasn't recognized for this store.",
-      hint: "run `tot login`, then re-run.",
-    };
+  vlog(`cli-session → HTTP ${res.status}`);
+  if (res.status === 401 || res.status === 502 || res.status === 503) {
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      /* non-JSON error body — describeCliSessionRefusal falls back cleanly */
+    }
+    if (body?.error || body?.code) vlog(`cli-session error: ${[body.error, body.code].filter(Boolean).join(" / ")}`);
+    const { message, hint } = describeCliSessionRefusal(res.status, body, dev.mcpUrl);
+    return { ok: false, message, hint };
   }
   if (!res.ok) {
     return {