@tokenoftrust/cli 1.3.4 → 1.4.0-rc.1

package/src/commands/grants.mjs

@@ -0,0 +1,264 @@
+/**
+ * `tot grants` — what can the signed-in identity actually do on each store?
+ *
+ * A diagnostic sibling of `tot whoami`: where whoami answers "who am I and which
+ * stores can I touch", `grants` drills into the DEVELOPER-ACCESS GRANT behind each
+ * of those stores — its capability, ship-on-behalf tier, expiry, and whether it's
+ * been revoked. This is the RFC 7662-shaped introspection the MCP already runs
+ * internally on every `tenant_checkout` (tot-mcp: operator/grant-introspection.ts,
+ * `GrantIntrospector.introspect({developer, tenant}) -> {active, capability, tier,
+ * exp, revokedAt}`) — surfaced to the developer so a "why can't I check this store
+ * out?" is answerable without an operator.
+ *
+ * Forward-compatible by design: it PREFERS a server-side `grant_introspect` tool
+ * (the follow-up that exposes the introspector per the signed-in session's stores)
+ * and, until that tool ships, FALLS BACK to `client_list` — which today returns only
+ * the store ids + environment, no grant detail. In the fallback it renders the store
+ * list and says plainly that the capability/tier/expiry/revocation picture needs the
+ * server-side tool, rather than inventing numbers it can't see. The moment
+ * `grant_introspect` lands, the same command consumes it with no further CLI change.
+ *
+ * Auth/session and MCP transport are reused verbatim from the doctor/whoami pattern
+ * (establishSession attaches the developer bearer BEFORE the handshake so the server
+ * binds this identity — the same ordering that fixes the "no stores" dead-end).
+ * Dependency-free.
+ */
+import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { createMcpClient } from "../mcp.mjs";
+import { storeListError } from "./checkout.mjs";
+import { offerSignIn } from "./login.mjs";
+import { recordServerPolicy } from "../update-check.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot grants — capability / tier / expiry / revocation for the stores you can act on
+
+  tot grants          show each store's developer-access grant
+  tot grants --json   machine-readable output`;
+
+function parseArgs(argv) {
+  const a = { json: false, help: false };
+  for (const t of argv) {
+    if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Normalize the grant source into plain rows, tolerant of the two shapes we may
+ * read: the introspector-backed `grant_introspect` result (`{ activeTenant?, grants:
+ * [{ tenant, environment, active, capability, tier, exp, revokedAt }] }`) and the
+ * `client_list` fallback (`{ activeTenant?, clients: [{ tenant, environment, active
+ * }] }` or a bare array). The introspector's `active` means "grant currently valid";
+ * client_list's `active` means "the currently-SELECTED tenant" — two different bits,
+ * so they're kept apart here (`grantActive` vs `selected`) and never conflated.
+ *
+ * @param {unknown} resp
+ * @returns {{ introspected: boolean, rows: Array<{ tenant: string, environment: string|null,
+ *   selected: boolean, grantActive: boolean|null, capability: string|null, tier: string|null,
+ *   exp: number|null, revokedAt: string|null }> }}
+ */
+export function normalizeGrantRows(resp) {
+  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(resp.grants)) {
+    const activeTenant = typeof resp.activeTenant === "string" ? resp.activeTenant : null;
+    const rows = resp.grants
+      .map((g) => {
+        const tenant = g?.tenant ?? g?.id ?? null;
+        return {
+          tenant,
+          environment: g?.environment ?? null,
+          selected: activeTenant ? tenant === activeTenant : Boolean(g?.selected),
+          grantActive: typeof g?.active === "boolean" ? g.active : null,
+          capability: g?.capability ?? null,
+          tier: g?.tier ?? null,
+          exp: typeof g?.exp === "number" ? g.exp : null,
+          revokedAt: g?.revokedAt ?? null,
+        };
+      })
+      .filter((r) => r.tenant);
+    return { introspected: true, rows };
+  }
+
+  // Fallback: client_list — store ids + environment + the selected marker only. No
+  // grant detail is knowable here (grantActive/capability/tier/exp/revokedAt stay null).
+  const clients = Array.isArray(resp) ? resp : resp?.clients || resp?.tenants || [];
+  const rows = (Array.isArray(clients) ? clients : [])
+    .map((c) => ({
+      tenant: c?.tenant ?? c?.id ?? c?.clientId ?? c?.appDomain ?? null,
+      environment: c?.environment ?? null,
+      selected: Boolean(c?.active),
+      grantActive: null,
+      capability: null,
+      tier: null,
+      exp: null,
+      revokedAt: null,
+    }))
+    .filter((r) => r.tenant);
+  return { introspected: false, rows };
+}
+
+/**
+ * Classify a grant row into a single status word. `unknown` is the honest answer
+ * for a fallback (client_list) row where the grant state simply isn't observable
+ * yet. For an introspected row it derives from grantActive + exp + revokedAt, and
+ * defensively downgrades an active-but-past-exp grant to `expired` even if the
+ * server hasn't flipped `active` (clock-skew / caching robustness).
+ *
+ * @param {{ grantActive: boolean|null, exp: number|null, revokedAt: string|null }} row
+ * @param {{ now?: number }} [opts]
+ * @returns {"active"|"revoked"|"expired"|"inactive"|"unknown"}
+ */
+export function grantStatus(row, { now = Date.now() } = {}) {
+  if (!row || row.grantActive === null || row.grantActive === undefined) return "unknown";
+  if (row.grantActive === false) return row.revokedAt ? "revoked" : "inactive";
+  if (typeof row.exp === "number" && row.exp * 1000 <= now) return "expired";
+  return "active";
+}
+
+/**
+ * Humanize an RFC 7662 `exp` (epoch SECONDS) into an ISO instant + a coarse relative
+ * hint. `no expiry` for a grant that never expires; `expired <iso>` once it's past.
+ * @param {number|null|undefined} exp
+ * @param {{ now?: number }} [opts]
+ * @returns {string}
+ */
+export function formatExpiry(exp, { now = Date.now() } = {}) {
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return "no expiry";
+  const ms = exp * 1000;
+  const iso = new Date(ms).toISOString();
+  const deltaMs = ms - now;
+  if (deltaMs <= 0) return `expired ${iso}`;
+  const days = Math.floor(deltaMs / 86_400_000);
+  const hours = Math.floor((deltaMs % 86_400_000) / 3_600_000);
+  const rel = days > 0 ? `in ${days}d ${hours}h` : hours > 0 ? `in ${hours}h` : "in <1h";
+  return `${iso} (${rel})`;
+}
+
+/**
+ * The one-line grant detail printed (and asserted in tests) under each store. Pure —
+ * no I/O — so the exact copy is unit-tested. An unknown (fallback) row says so instead
+ * of pretending; every other status is `status · capability=… · tier=… · <expiry|revoked>`.
+ * @param {ReturnType<typeof normalizeGrantRows>["rows"][number]} row
+ * @param {{ now?: number }} [opts]
+ * @returns {string}
+ */
+export function describeGrantRow(row, { now = Date.now() } = {}) {
+  const status = grantStatus(row, { now });
+  if (status === "unknown") return "grant detail unavailable (server introspection not enabled)";
+  const parts = [status];
+  if (row.capability) parts.push(`capability=${row.capability}`);
+  if (row.tier) parts.push(`tier=${row.tier}`);
+  if (status === "revoked" && row.revokedAt) parts.push(`revoked ${row.revokedAt}`);
+  else if (row.grantActive) parts.push(`expiry ${formatExpiry(row.exp, { now })}`);
+  return parts.join(" · ");
+}
+
+/**
+ * Best-effort read of the introspector-backed tool. Returns the result only when it
+ * is a genuine introspection response (carries a `grants` array); anything else —
+ * including the JSON-RPC error a server that doesn't register `grant_introspect` yet
+ * throws — resolves to null so the caller falls back to `client_list`.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ */
+async function tryIntrospect(client) {
+  try {
+    const r = await client.callTool("grant_introspect", {});
+    if (r && typeof r === "object" && Array.isArray(r.grants)) return r;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string[]} argv @param {any} _ctx */
+export async function run(argv, _ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  const env = process.env;
+  const now = Date.now();
+
+  // Same MCP-URL resolution as whoami: the cached session's origin wins, then env
+  // overrides, then the public default.
+  const creds = readCredentials(defaultCredentialsPath(env));
+  const mcpUrl = creds?.mcpUrl || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(mcpUrl);
+
+  // Attach the developer bearer BEFORE the handshake (establishSession) so the server
+  // binds this identity — the grants belong to the signed-in developer. When there's
+  // no session yet and we're on a TTY, offer to sign in inline and retry once;
+  // otherwise the AuthUnavailableError surfaces house-style with its next step.
+  try {
+    await establishSession(client, { env });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError && e.reason === "missing") {
+      const signedIn = await offerSignIn(mcpUrl, env, {});
+      if (!signedIn) throw e;
+      await establishSession(client, { env }); // retry once, in-flow
+    } else {
+      throw e;
+    }
+  }
+
+  // Prefer the introspector-backed tool; fall back to client_list until it ships.
+  let resp = await tryIntrospect(client);
+  if (!resp) {
+    resp = await client.callTool("client_list", {});
+    // Update-awareness Layer 2: an authed response may carry a version-support policy.
+    recordServerPolicy(resp?.cliPolicy, env);
+  } else {
+    recordServerPolicy(resp?.cliPolicy, env);
+  }
+
+  const { introspected, rows } = normalizeGrantRows(resp);
+  const listErr = storeListError(resp);
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        {
+          introspected,
+          error: listErr || null,
+          grants: rows.map((r) => ({ ...r, status: grantStatus(r, { now }) })),
+        },
+        null,
+        2,
+      ),
+    );
+    return listErr && rows.length === 0 ? 1 : 0;
+  }
+
+  if (listErr && rows.length === 0) {
+    console.log(`\nCouldn't read your grants: ${listErr}`);
+    console.log("Run `tot whoami` to check your session, or `tot login` again.");
+    return 1;
+  }
+  if (rows.length === 0) {
+    console.log("\nNo stores you can act on yet for this identity.");
+    console.log("If you were just invited, it may still be propagating — try again in a minute.");
+    return 0;
+  }
+
+  console.log("\nDeveloper-access grants for the stores you can act on:\n");
+  for (const row of rows) {
+    const envLabel = row.environment ? ` [${row.environment}]` : "";
+    const marker = row.selected ? "  (active tenant)" : "";
+    console.log(`  ${row.tenant}${envLabel}${marker}`);
+    console.log(`      ${describeGrantRow(row, { now })}`);
+  }
+
+  if (!introspected) {
+    console.log(
+      "\nNote: full grant detail (capability / tier / expiry / revocation) needs the",
+    );
+    console.log(
+      "server-side `grant_introspect` MCP tool, which this MCP doesn't expose yet —",
+    );
+    console.log("showing the stores you can act on only. Run `tot whoami` for session status.");
+  }
+  return 0;
+}

package/src/commands/login.mjs

@@ -23,7 +23,8 @@ import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oa
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
-import { cockpitRecoveryUrl, normalizeEmailHint } from "../auth.mjs";
+import { cockpitRecoveryUrl, normalizeEmailHint, redactEmailForHint, emailFromJwt } from "../auth.mjs";
+import { isInteractive, promptYesNo } from "../prompt.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -140,6 +141,52 @@ export async function loginAndCache(mcpUrl, env = process.env, { log = () => {},
   return merged;
 }
 
+/**
+ * Interactive sign-in assist — the no-dead-end path. When a command hits "you're
+ * not signed in" on a TTY, don't tell the developer to go run `tot login` and come
+ * back: offer to sign them in RIGHT HERE, open the browser, and hand control back
+ * so they continue in the same flow (handoff 2026-08-02 v2 §UX bar — "the product
+ * taking their hand", no re-run, no OAuth jargon).
+ *
+ * Returns the cached credentials on success, or null when the offer is declined,
+ * skipped (non-interactive and not auto-yes — never hang CI), or the sign-in
+ * doesn't complete. A null return means "fall back to your own not-signed-in
+ * behavior" (the free sample preview for `tot start`, a crisp error for others).
+ *
+ * All I/O is injectable so this unit-tests with no real prompt or browser:
+ *   interactive — is this a TTY we can prompt on (default: stdin+stdout are a TTY)
+ *   yes         — auto-accept, skip the prompt (the caller's --yes)
+ *   prompt      — async (question, defaultYes) => boolean
+ *   login       — async (mcpUrl, env, {log}) => creds (defaults to loginAndCache)
+ *   out         — where the human-facing lines go (default: stderr, like the rest)
+ *
+ * @returns {Promise<object|null>}
+ */
+export async function offerSignIn(mcpUrl, env = process.env, {
+  interactive = isInteractive(),
+  yes = false,
+  prompt = promptYesNo,
+  login = loginAndCache,
+  out = (m) => console.error(m),
+} = {}) {
+  if (!interactive && !yes) return null; // non-TTY without --yes: never prompt/hang
+  if (!yes) {
+    out("");
+    out("  One quick step — sign in to Token of Trust and I'll take you straight to your store.");
+    const ok = await prompt("  Sign in now?", true);
+    if (!ok) return null;
+  }
+  out("  → opening your browser to sign in …");
+  try {
+    const creds = await login(mcpUrl, env, { log: out });
+    out("  ✓ signed in");
+    return creds;
+  } catch (e) {
+    out(`  couldn't finish signing in (${e?.message || e}).`);
+    return null;
+  }
+}
+
 /**
  * The core of `tot login --code`: run the browserless redemption (POST the invite
  * token to the MCP, get a grant back) and cache it, reusing a previously-registered
@@ -164,20 +211,29 @@ export async function redeemAndCache(mcpUrl, code, env = process.env) {
  * (a full-object overwrite, not a merge) — carry it forward when re-authing against
  * the SAME mcpUrl (a different MCP means a different session; the old bridge
  * credential and trace no longer apply).
+ *
+ * IDENTITY GUARD: only carry it when the new sign-in is the SAME person. If we can
+ * POSITIVELY tell it's a different identity — both the prior and the new token
+ * carry an email and they differ — we drop the prior bridge/trace/hint rather than
+ * bleed one identity's hosted /dev panel + feedback trace into another's (the
+ * staff↔developer re-login on one machine). When we can't tell (opaque token, no
+ * hint either side) we preserve the same-person carry, so this never regresses a
+ * routine re-login. For genuinely concurrent identities, prefer per-terminal
+ * `TOT_PROFILE` (separate credential files — no carry to guard at all).
  */
 export function mergeActivityBridge(prior, mcpUrl, creds) {
-  if (prior?.mcpUrl === mcpUrl) {
-    const emailHint = normalizeEmailHint(prior.emailHint) || normalizeEmailHint(prior.email);
-    return {
-      ...creds,
-      ...(prior.activityToken && prior.activityUrl
-        ? { activityToken: prior.activityToken, activityUrl: prior.activityUrl }
-        : {}),
-      ...(prior.traceId ? { traceId: prior.traceId } : {}),
-      ...(emailHint ? { emailHint } : {}),
-    };
-  }
-  return creds;
+  if (prior?.mcpUrl !== mcpUrl) return creds;
+  const priorHint = normalizeEmailHint(prior.emailHint) || normalizeEmailHint(prior.email);
+  const newHint = redactEmailForHint(emailFromJwt(creds?.accessToken || "") || "");
+  if (priorHint && newHint && priorHint !== newHint) return creds; // different identity → no bleed
+  return {
+    ...creds,
+    ...(prior.activityToken && prior.activityUrl
+      ? { activityToken: prior.activityToken, activityUrl: prior.activityUrl }
+      : {}),
+    ...(prior.traceId ? { traceId: prior.traceId } : {}),
+    ...(priorHint ? { emailHint: priorHint } : {}),
+  };
 }
 
 export function inviteCodeRecoveryNext(activityUrl, emailHint = null) {

package/src/commands/start.mjs

@@ -5,7 +5,8 @@
  * It COMPOSES the other commands' cores in-process (no shelling out to `tot …`):
  *
  *   preflight   collectChecks()  (F — self-healing where it can be)
- *   login       resolveSession()  (operator today; device-code is the B seam)
+ *   login       establishSession()  (developer OAuth; offers inline sign-in when
+ *               there's no session yet — no re-run — see tryResolveSession)
  *              (A2 — run concurrently: neither gates the other; wait on the slower)
  *      ↓
  *   store       normalizeStores(client_list) → auto-pick if exactly one, else
@@ -69,19 +70,20 @@ import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
+import { offerSignIn } from "./login.mjs";
+import { isInteractive, promptYesNo } from "../prompt.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const CLAUDE_MCP_ARGS = ["mcp", "add", "--transport", "http", "tot", `${DEFAULT_MCP_URL}/mcp`];
 
 function parseArgs(argv) {
   const a = {
-    mcp: null, identity: null, tenant: null, port: "4321",
+    mcp: null, tenant: null, port: "4321",
     noOpen: false, noConnect: false, yes: false, docker: false, sample: false, help: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
-    else if (t === "--identity") a.identity = argv[++i];
     else if (t === "--tenant") a.tenant = argv[++i];
     else if (t === "--port") a.port = argv[++i];
     else if (t === "--no-open") a.noOpen = true;
@@ -106,8 +108,7 @@ Options:
                     artifact can't be fetched
   --no-open        don't auto-open the browser
   --no-connect     skip the "Connect Claude for AI editing?" prompt
-  --yes, -y        assume yes for prompts (non-interactive)
-  --identity <who> force "operator" or "developer" auth (default: auto)
+  --yes, -y        assume yes for prompts (non-interactive; also auto-signs-in)
   --mcp <url>      MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
 On a multi-store identity, the tenant you pick (or pass via --tenant) is
@@ -373,15 +374,14 @@ async function runSampleStart(args, ctx, env, startedAt) {
  * MCP init + session resolve — the "login" half of preflight. Throws
  * AuthUnavailableError (no creds) or a CliError (can't reach the MCP).
  */
-async function loginStep(client, env, args) {
+async function loginStep(client, env, _args) {
   // establishSession attaches auth in the right order relative to the handshake:
-  // the developer bearer BEFORE initialize (so the server binds this identity at
-  // initialize time — otherwise the session is anonymous and client_list is empty),
-  // the operator credential_validate after it. We inject our own initialize so the
-  // unreachable-MCP case still surfaces the actionable CliError below.
+  // the developer bearer BEFORE initialize, so the server binds this identity at
+  // initialize time — otherwise the session is anonymous and client_list is empty.
+  // We inject our own initialize so the unreachable-MCP case still surfaces the
+  // actionable CliError below.
   return establishSession(client, {
     env,
-    prefer: args.identity || undefined,
     initialize: async () => {
       try {
         await client.initialize();
@@ -398,12 +398,27 @@ async function loginStep(client, env, args) {
  * Resolve a session but return null (instead of throwing) for the two conditions
  * the free-taste fallback should absorb: no usable session, or the MCP being
  * unreachable. A blocking machine problem (or any other error) still throws.
+ *
+ * When there's simply no session yet, we don't dead-end at "go run tot login" —
+ * on a TTY (or --yes) we OFFER to sign the developer in right here (browser opens),
+ * then continue straight into the run with no re-run (handoff 2026-08-02 v2). A
+ * declined/skipped offer falls through to the free sample preview as before.
  */
 async function tryResolveSession(client, env, args) {
   try {
     return await loginStep(client, env, args);
   } catch (e) {
-    if (e instanceof AuthUnavailableError && e.reason === "missing") return null;
+    if (e instanceof AuthUnavailableError && e.reason === "missing") {
+      const signedIn = await offerSignIn(client.mcpUrl, env, { yes: args.yes });
+      if (!signedIn) return null; // declined/skipped → sample preview
+      try {
+        return await loginStep(client, env, args); // retry once, in-flow
+      } catch (e2) {
+        if (e2 instanceof AuthUnavailableError && e2.reason === "missing") return null;
+        if (e2 instanceof CliError && /can't reach the Token of Trust MCP/.test(e2.message)) return null;
+        throw e2;
+      }
+    }
     if (e instanceof CliError && /can't reach the Token of Trust MCP/.test(e.message)) return null;
     throw e;
   }
@@ -499,13 +514,10 @@ async function prefetchDockerLogin(client, devArgs, env) {
 }
 
 /** A human label for a resolved session — the email when we could read it from
- * the OAuth token, else the operator app domain, else the identity kind. */
+ * the OAuth token, else a generic developer label. */
 function describeIdentity(session) {
   if (!session) return "an unknown identity";
   if (session.email) return session.email;
-  if (session.identity === "operator") {
-    return session.appDomain ? `operator (${session.appDomain})` : "operator";
-  }
   return "your developer identity";
 }
 
@@ -727,22 +739,8 @@ function connectClaude() {
 }
 
 // ── small prompt helpers (respect non-TTY so nothing hangs in CI) ────────────
-
-function isInteractive() {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-
-async function promptYesNo(question, defaultYes) {
-  if (!isInteractive()) return defaultYes;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const ans = (await rl.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
-    if (!ans) return defaultYes;
-    return ans === "y" || ans === "yes";
-  } finally {
-    rl.close();
-  }
-}
+// isInteractive + promptYesNo now live in ../prompt.mjs (shared with the sign-in
+// offer); promptChoice stays here as it's only used by the store picker.
 
 /** Prompt for a 1..n choice; returns a 0-based index (defaults to first). */
 async function promptChoice(n) {