@tokenoftrust/cli 2.4.8 → 2.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.8",
+  "version": "2.4.10",
   "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/admission-hint.mjs

@@ -0,0 +1,36 @@
+/**
+ * The next step to print when the storefront refuses a call with 401/403.
+ *
+ * The server's admission rule (apps/storefront lib/pipeline/admission.ts) names exactly what is
+ * missing in `admission.missing[].grant`, and its reason is already in the refusal's `error`.
+ * The hint follows that answer instead of restating a policy of its own: a client copy of the
+ * rule goes stale — every refusal here used to say "you need a live ship-on-behalf grant", which
+ * is wrong for an unpaid store, where an invited developer needs no grant at all.
+ */
+
+/** The grant names a refusal body reports missing, or `[]` when it names none. */
+export function missingGrantsOf(body) {
+  const missing = body && typeof body === "object" ? body.admission?.missing : undefined;
+  return Array.isArray(missing)
+    ? missing.map((m) => m?.grant).filter((g) => typeof g === "string")
+    : [];
+}
+
+/** One actionable next step for a refused call, from the grants the server named. */
+export function refusalHint(status, missingGrants = []) {
+  if (status === 401 || missingGrants.includes("session")) return "run `tot login`, then re-run";
+  if (missingGrants.includes("tenant-binding")) {
+    return "your sign-in is for a different store — check --tenant, then re-run";
+  }
+  if (missingGrants.includes("tenant-standing")) {
+    return "ask the store owner to invite you to this store from its Team page, then re-run";
+  }
+  if (missingGrants.includes("ship-on-behalf")) {
+    return "this store's live site is active, so ask the store owner for a ship-on-behalf grant from its Team page, then re-run";
+  }
+  if (missingGrants.includes("owner-standing")) return "only the store owner can do this";
+  if (missingGrants.includes("console-capability")) {
+    return "the operator secret is acting with preview-access — set X-Tot-Capability: ship-on-behalf (or ACCEPT_OPERATOR_CAPABILITY), then re-run";
+  }
+  return "ask the store owner for access to this store — or use an operator secret authorised for it";
+}

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/accept.mjs

@@ -47,8 +47,9 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { scopeToTenant } from "../tenant-scope.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
-// login and integrate as themselves (server gates on their live ship-on-behalf grant).
+// login and integrate as themselves (the server's admission rule decides).
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 // The doctor PUSH: on a failed accept/integrate, auto-append the COMPACT
 // "here's what's blocking you" summary over the SAME transport we just used, so a
 // developer doesn't have to remember to run `tot preview doctor` themselves.
@@ -529,7 +530,7 @@ export async function runIntegrate(
   //    - OPERATOR SECRET (operators/CI): Bearer + X-Tot-Owner on the generic host.
   //    - VIEWER SESSION (an invited developer, no secret): mint a `tot_session` from
   //      their OWN `tot` login on the TENANT'S host and send it as a cookie. The
-  //      server authorizes on their live ship-on-behalf grant either way.
+  //      server's admission rule authorizes either way.
   //    No `content-type` here: it's added per-POST; the mergeable preflight GET wants none.
   let authHeaders;
   if (secret) {
@@ -688,7 +689,7 @@ function reportIntegrateHttpError(result, res, { tenant, label }) {
     fail(
       `the integration queue refused the request: ${msg}`,
       res.status === 401 || res.status === 403
-        ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
+        ? refusalHint(res.status, missingGrantsOf(result.raw))
         : res.status === 404
           ? `check that ${label} has a built candidate in ${tenant}'s queue (\`tot pr list --tenant ${tenant}\`)`
           : "check --tenant / --url / --pr, then re-run",

package/src/commands/preview-doctor.mjs

@@ -38,6 +38,7 @@
  */
 import { fail } from "../errors.mjs";
 import { resolveOperatorSecret } from "./ship.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 import { resolveViewerTransport } from "../viewer-session.mjs";
 import {
   DOCTOR_PATH,
@@ -165,7 +166,7 @@ export async function runDoctor(
     console.error(
       fail(
         `not authorized to diagnose ${tenant}'s merges: ${data?.error || `HTTP ${res.status}`}`,
-        "you need a live ship-on-behalf grant on this tenant (ask the store owner), or an operator secret authorised for it — then re-run",
+        refusalHint(res.status, missingGrantsOf(data)),
       ),
     );
     return 2;

package/src/commands/revert.mjs

@@ -45,8 +45,9 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 // speak ONE operator-auth contract.
 import { resolveOperatorSecret } from "./ship.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
-// login. The server still gates the request on their live ship-on-behalf grant.
+// login. The server's admission rule still gates the request.
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
@@ -337,7 +338,7 @@ export async function runRevert(
       fail(
         `the revert request was refused: ${msg}`,
         res.status === 401 || res.status === 403
-          ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
+          ? refusalHint(res.status, missingGrantsOf(data))
           : "check --tenant / --url / --preview, then re-run",
       ),
     );

package/src/commands/ship.mjs

@@ -47,7 +47,8 @@
  *
  * TRANSPORT: operators/CI may use a Bearer operator secret. A signed-in owner or
  * developer instead mints a storefront viewer session from their OWN `tot login`
- * identity; the server still enforces the live owner / `ship-on-behalf` grant.
+ * identity; the server's admission rule decides who may ship (owner; a live
+ * `ship-on-behalf` grant; or, while the store is unpaid, any developer invited to it).
  */
 import { createHash } from "node:crypto";
 import { fail } from "../errors.mjs";
@@ -61,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";
 
@@ -75,11 +77,13 @@ 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: a signed-in owner/developer with a live ship-on-behalf grant
-  can use their own \`tot login\` session. Operators/CI may instead provide a
-  secret via PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET,
-  TOT_OPERATOR_SECRET, or --secret.
+  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
+  it as a developer. Operators/CI may instead provide a secret via
+  PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET, or --secret.
 
   \`tot ship\` has ONE meaning: it publishes the tenant's shared preview
   aggregate — the batch of PRs that integrated cleanly and went GREEN — to
@@ -107,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++) {
@@ -117,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;
@@ -422,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
  */
@@ -436,6 +442,7 @@ export async function runShip(
     yes = false,
     noOpen = false,
     acceptQualityReason = null,
+    verbose = false,
     env = process.env,
   },
   deps = {},
@@ -443,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) {
@@ -452,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;
@@ -471,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 });
@@ -480,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: [] };
@@ -725,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

@@ -6,9 +6,10 @@
  * a storefront VIEWER session from the developer's OWN MCP token (POST
  * /api/dev/cli-session on the tenant's own host, which resolves WHO the opaque token
  * is via the MCP and hands back a `tot_session` cookie), then hands the caller a
- * cookie-based transport pointed at the tenant host. Authorization is still the
- * developer's live `ship-on-behalf` grant, enforced server-side at the ship route —
- * this only carries their identity, it grants nothing.
+ * cookie-based transport pointed at the tenant host. Authorization is the server's
+ * admission rule at the ship route (owner; a live `ship-on-behalf` grant; or, while the
+ * store is unpaid, any developer invited to it) — this only carries their identity, it
+ * grants nothing.
  *
  * Minted FRESH per call (no disk cache): a `tot accept` is interactive + infrequent,
  * and minting-per-call means a revoked session/grant is never honored past its life.
@@ -43,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
@@ -53,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 }
@@ -65,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;
@@ -95,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: {
@@ -110,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 {