@tokenoftrust/cli 2.4.8 → 2.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "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/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";
@@ -76,10 +77,10 @@ const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live
                             record the required reason, then continue publishing
   tot ship --no-open         don't open the live URL in your browser
 
-  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

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.