@tokenoftrust/cli 2.0.19 → 2.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "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/commands/clone.mjs

@@ -275,6 +275,39 @@ export async function run(argv, ctx) {
   }
 }
 
+/**
+ * Is this client_switch failure the EXPECTED "that tenant is not one of your clients"
+ * refusal, as opposed to a broken session (transport, auth, malformed envelope, internal
+ * error)? The distinction is load-bearing: an expected refusal is a normal step on the
+ * staff-preview path and must be tolerated, while anything else means the session itself
+ * is unusable and must surface immediately rather than be mistaken for an authorization
+ * problem later.
+ *
+ * Matched on the server's STRUCTURED signal first (`serverCode` / status), because message
+ * text is not a contract. The text fallback exists only for servers predating a typed code
+ * and is deliberately narrow — when in doubt this returns false, which escalates. Treating
+ * an unknown failure as "expected" is the unsafe direction: it would let a dead connection
+ * pass for a routine refusal.
+ *
+ * Pure + exported so it is unit-tested without any I/O.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNotClientTenantRefusal(error) {
+  const e = /** @type {any} */ (error);
+  if (!e) return false;
+  // A transport/protocol-level failure is never an authorization refusal.
+  const category = e?.diagnostic?.category ?? e?.category;
+  if (category && category !== "tool_error") return false;
+  const code = e?.diagnostic?.serverCode ?? e?.serverCode;
+  if (typeof code === "string") {
+    return code === "not_client_tenant" || code === "over_scoped";
+  }
+  // Text fallback (pre-typed-code servers) — narrow on purpose.
+  const message = typeof e?.message === "string" ? e.message : "";
+  return /not one of your client tenants/i.test(message);
+}
+
 /**
  * The privileged checkout core, composable in-process (used by `tot clone`
  * and by `tot start`): client_switch → tenant_checkout → optionally clone. The
@@ -287,21 +320,37 @@ export async function run(argv, ctx) {
  *   cloned: boolean, dir: string|null, head: string|null }>}
  */
 export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
-  // The switch is LOAD-BEARING, so its refusal is the error the developer must see. When
-  // the tenant is not one of this session's clients the server refuses here with the real
-  // cause (no grant / a grant issued to a client this identity is not bound to / a grant
-  // issued after sign-in that needs a re-auth) — far more specific than the tenant_checkout
-  // refusal that follows it. Surfacing the switch's own words, with the server's nextAction,
-  // stops a genuinely-unentitled tenant from being reported as a scope-selection slip.
+  // tenant_checkout is the SOLE AUTHORITATIVE checkout decision. client_switch is a scope
+  // convenience whose refusal may be entirely expected: a staff human checking out a
+  // merchant tenant under a staff-preview authorization holds no client grant on it, so the
+  // switch MUST refuse while the checkout legitimately succeeds. `tot git-credential` mints
+  // through this same function, so treating the switch as fatal breaks every fetch and push
+  // in such a checkout, not only the clone.
+  //
+  // Two failure modes are therefore BOTH wrong, and the second is the dangerous one:
+  //   - discarding the refusal loses the only good explanation when a tenant genuinely is
+  //     not yours;
+  //   - letting the refusal OVERRIDE a checkout denial replaces an authoritative answer
+  //     ("your staff authorization expired / was revoked / does not cover this resource")
+  //     with grant guidance that sends you chasing the wrong thing entirely.
+  // So an EXPECTED switch refusal may never speak over a checkout denial (see below).
+  //
+  // An UNEXPECTED switch failure — transport, auth, a malformed envelope — is not the
+  // not-a-client case at all. It means the session itself is broken, and carrying it
+  // silently would let a dead connection masquerade as an authorization problem, so it is
+  // raised immediately rather than remembered.
+  let expectedSwitchRefusal = null;
   try {
     await client.callTool("client_switch", { tenant });
   } catch (e) {
-    throw new CliError(redact(String(e?.message || e)), {
-      next:
-        "confirm you're entitled to this store — `tot grants` lists what your session can " +
-        "act on, and `tot login` refreshes a grant issued after you signed in",
-      cause: e,
-    });
+    if (isNotClientTenantRefusal(e)) {
+      expectedSwitchRefusal = e;
+    } else {
+      throw new CliError(redact(String(e?.message || e)), {
+        next: "the session could not be scoped — check your connection and run `tot whoami`",
+        cause: e,
+      });
+    }
   }
   // vc-app-binding safety-net (08-18, §5): ensure THIS developer is bound to the
   // storefront version-control app BEFORE checkout, so tenant_checkout can resolve
@@ -319,13 +368,32 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   } catch {
     /* fail-open — see above */
   }
-  const checkout = await client.callTool("tenant_checkout", { tenant, tag });
+  let checkout;
+  try {
+    checkout = await client.callTool("tenant_checkout", { tenant, tag });
+  } catch (e) {
+    // A THROWN checkout is not a denial — it never rendered an authorization decision. Only
+    // here may the expected switch refusal speak, because it is the only explanation either
+    // call produced.
+    if (expectedSwitchRefusal) {
+      throw new CliError(redact(String(expectedSwitchRefusal?.message || expectedSwitchRefusal)), {
+        next:
+          "confirm you're entitled to this store — `tot grants` lists what your session can " +
+          "act on, and `tot login` refreshes a grant issued after you signed in",
+        cause: expectedSwitchRefusal,
+      });
+    }
+    throw e;
+  }
 
   // A non-checkout result (not provisioned / not entitled / failed) must surface
   // the MCP's human message + a concrete next step, NEVER a raw JSON.stringify
   // dump (James's 2026-07-19 first-experience failure).
   const err = checkoutError(checkout);
   if (err) {
+    // AUTHORITATIVE: the checkout rendered a decision, so it is the answer — even when the
+    // switch also refused. Substituting grant guidance here is what would tell someone whose
+    // staff authorization had EXPIRED to go looking at their grants.
     throw new CliError(redact(err.message), { next: err.next });
   }
   const gitRemote = checkout.gitRemote;