@tokenoftrust/cli 1.3.4-rc.5 → 1.4.0-rc.0

package/README.md

@@ -40,10 +40,24 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 ## Auth
 
-`tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It authenticates as one of two identities, transparently:
+`tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It is **single-plane**: the only identity is **you**, signed in against the MCP over OAuth.
 
-- **developer** — you, signed in against the MCP (the real invited-developer path). Depends on entitlement-derived MCP access; until that ships, `tot` reports it clearly and points you at operator creds.
-- **operator** — `TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN` in the environment (how we dogfood the CLI and how CI exercises it).
+- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot checkout`, `tot start`, `tot submit`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- Not signed in? On a terminal, `tot start` / `tot checkout` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
+- The old operator env-triple (`TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN`) **no longer signs the CLI in** — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, `tot` prints a one-line advisory and uses your `tot login` session anyway; it never reads them for auth.
+
+### Multiple identities at once (`TOT_PROFILE`)
+
+One credential file = one active identity, so a plain `tot login` replaces the previous session. To keep **different identities live in different terminals** — e.g. a staff `@tokenoftrust.com` sign-in in one shell and a plain developer identity in another — set a profile per shell:
+
+```
+# terminal A
+export TOT_PROFILE=staff && tot login
+# terminal B
+export TOT_PROFILE=dev   && tot login
+```
+
+Each profile gets its own `~/.tot/credentials.<profile>.json` (the renderer cache and everything else stay shared). Unset → the default session, unchanged. `tot whoami` shows the active profile.
 
 ## Design notes
 

package/bin/tot.mjs

@@ -8,6 +8,7 @@
  *   tot login                 sign in to Token of Trust (OAuth)          ← built (MCP OAuth PKCE loopback; caches ~/.tot/credentials.json)
  *   tot logout                sign out (clear the cached session)        ← built (deletes ~/.tot/credentials.json; local-only, no server revoke)
  *   tot whoami                who you're signed in as                    ← built
+ *   tot grants                capability/tier/expiry per store you can act on  ← built (introspection diagnostics)
  *   tot checkout [<tenant>]   clone a store you can build on            ← built
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
@@ -52,6 +53,7 @@ tot — Token of Trust developer CLI
   tot login                 sign in to Token of Trust
   tot logout                sign out (clear the cached session)
   tot whoami                show who you're signed in as
+  tot grants                capability/tier/expiry per store you can act on
   tot checkout [<tenant>]   clone a store you can build on
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
@@ -112,6 +114,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "grants") {
+    const { run } = await import("../src/commands/grants.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "ideas") {
     const { run } = await import("../src/commands/ideas.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.5",
+  "version": "1.4.0-rc.0",
   "description": "Token of Trust developer CLI — check out 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

@@ -1,33 +1,28 @@
 /**
- * Auth providers for `tot` — how we establish a VALIDATED MCP session before a
- * privileged tool call (tenant_checkout, client_switch, …).
+ * Auth for `tot` — how we establish a VALIDATED MCP session before a privileged
+ * tool call (tenant_checkout, client_switch, …).
  *
- * There are two identities that can drive `tot`, and the whole point of this
- * seam is that every command calls `resolveSession(client)` and never cares
- * which one answered:
+ * SINGLE PLANE: there is exactly one identity that drives `tot` — the human
+ * developer, signed in as THEMSELVES against the MCP via OAuth (the same identity
+ * `claude mcp add … tot` + `/mcp` establishes). `tot login` runs the MCP OAuth
+ * PKCE loopback and caches the token (~/.tot/credentials.json via token-store.mjs);
+ * this provider reads it back, silently refreshing when expired, and attaches it as
+ * the client's Bearer. Entitlement is derived server-side from the developer's ToT
+ * memberships — no local check. Every command calls `establishSession(client)`.
  *
- *   operator   — TOT_API_KEY / TOT_SECRET_KEY / TOT_APP_DOMAIN in the env →
- *                credential_validate. This is a STOREFRONT-OPERATOR (or CI)
- *                identity, resolved from SSM in our tooling. It is NOT what an
- *                invited external developer has — it's how WE dogfood the CLI
- *                end-to-end today, and how CI exercises it.
- *
- *   developer  — the invited developer, signed in as THEMSELVES against the MCP
- *                via OAuth (the same identity `claude mcp add … tot` + `/mcp`
- *                establishes). `tot login` runs the MCP OAuth PKCE loopback and
- *                caches the token (~/.tot/credentials.json via token-store.mjs);
- *                this provider reads it back, silently refreshing when expired,
- *                and attaches it as the client's Bearer. Entitlement is derived
- *                server-side from the developer's ToT memberships — no local check.
- *
- * Selection: operator creds win when present (explicit, deterministic, what CI
- * sets); otherwise we fall to the developer provider.
+ * The old `operator` provider (a TOT_API_KEY / TOT_SECRET_KEY / TOT_APP_DOMAIN
+ * env-triple → `credential_validate`) is GONE. tot-mcp went OAuth-first on
+ * 2026-07-23: `credential_validate` was retired to a stateless key-liveness probe
+ * that establishes NO human identity and sets NO tenant scope, so the operator
+ * path can no longer sign the CLI in to anything. The env-triple is now treated as
+ * DETECTION ONLY — if it's set we print a one-line advisory and proceed on the
+ * OAuth session (see hasLegacyOperatorEnv / legacyOperatorEnvAdvisory). We never
+ * read or transmit the secret.
  */
 import {
   defaultCredentialsPath, readCredentials, writeCredentials, isExpired,
 } from "./token-store.mjs";
 import { refreshAccessToken, credentialsFromToken } from "./oauth.mjs";
-import { recordServerPolicy } from "./update-check.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
@@ -99,42 +94,29 @@ export function developerCredentialRecoveryHint(creds) {
   return "run `tot login` to sign in again.";
 }
 
-/** True when a full operator credential triple is present in the environment. */
-export function hasOperatorCreds(env = process.env) {
+/**
+ * True when the RETIRED operator env-triple (TOT_API_KEY / TOT_SECRET_KEY /
+ * TOT_APP_DOMAIN) is fully set. Detection only — these keys no longer sign the
+ * CLI in to the MCP (OAuth-first since 2026-07-23); we use it purely to emit an
+ * advisory so a stale env setup self-explains instead of silently doing nothing.
+ * We never read the secret values.
+ */
+export function hasLegacyOperatorEnv(env = process.env) {
   return Boolean(env.TOT_API_KEY && env.TOT_SECRET_KEY && env.TOT_APP_DOMAIN);
 }
 
+/** One quiet line shown when the retired operator env-triple is present. */
+export const legacyOperatorEnvAdvisory =
+  "note: ToT API keys in this shell no longer sign the CLI in — using your `tot login` session instead.";
+
 /**
- * Establish a validated session on `client`.
- *
- * @param {ReturnType<import("./mcp.mjs").createMcpClient>} client
- * @param {{ env?: NodeJS.ProcessEnv, prefer?: "operator"|"developer" }} [opts]
- * @returns {Promise<{ identity: "operator"|"developer", appDomain: string|null }>}
+ * Emit the legacy-env advisory to stderr when the retired operator triple is set.
+ * A no-op otherwise. `warn` is injectable for tests; never touches the secret.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {(msg: string) => void} [warn]
  */
-export async function resolveSession(client, opts = {}) {
-  const env = opts.env || process.env;
-  const prefer = opts.prefer || (hasOperatorCreds(env) ? "operator" : "developer");
-
-  if (prefer === "operator") {
-    if (!hasOperatorCreds(env)) {
-      throw new AuthUnavailableError(
-        "operator auth requested but TOT_API_KEY / TOT_SECRET_KEY / TOT_APP_DOMAIN are not all set.",
-        { hint: "source apps/storefront/lib/resolve-tot-credentials.sh (from a storefront checkout), or unset --identity to use developer sign-in." },
-      );
-    }
-    const validated = await client.callTool("credential_validate", {
-      totApiKey: env.TOT_API_KEY,
-      totSecretKey: env.TOT_SECRET_KEY,
-      appDomain: env.TOT_APP_DOMAIN,
-    });
-    // Update-awareness Layer 2: the MCP may attach a version-support policy to the
-    // authed response (wire contract: `cliPolicy`). Safe no-op when absent.
-    recordServerPolicy(validated?.cliPolicy, env);
-    return { identity: "operator", appDomain: env.TOT_APP_DOMAIN };
-  }
-
-  // developer provider — the real invited-dev path.
-  return resolveDeveloperSession(client, env);
+export function warnLegacyOperatorEnv(env = process.env, warn = (m) => console.error(m)) {
+  if (hasLegacyOperatorEnv(env)) warn(legacyOperatorEnvAdvisory);
 }
 
 /**
@@ -221,39 +203,35 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
  * Establish a validated session on `client`, attaching auth in the CORRECT order
  * relative to the MCP handshake — the one thing every command must get right:
  *
- *   developer  → attach the cached bearer via setToken() BEFORE client.initialize(),
- *                so the server binds the session to this identity AT initialize time.
- *                An init-then-attach order leaves the session anonymous for its whole
- *                life on a server that only binds identity at initialize — this is the
- *                invited-developer "no stores you can build on" dead-end.
- *   operator   → client.initialize() FIRST, then credential_validate, which is an
- *                in-session tool call that requires a completed handshake.
+ *   attach the cached developer bearer via setToken() BEFORE client.initialize(),
+ *   so the server binds the session to this identity AT initialize time. An
+ *   init-then-attach order leaves the session anonymous for its whole life on a
+ *   server that only binds identity at initialize — this is the invited-developer
+ *   "no stores you can build on" dead-end. This ordering is load-bearing.
  *
- * Every command calls THIS instead of hand-ordering initialize() + resolveSession(),
- * so the ordering rule lives in exactly one place. `opts.initialize` lets a caller
- * inject its own handshake (to wrap the unreachable-MCP error, or pass custom
- * clientInfo); it defaults to `() => client.initialize()`.
+ * Every command calls THIS instead of hand-ordering initialize() + the developer
+ * resolver, so the ordering rule lives in exactly one place. `opts.initialize`
+ * lets a caller inject its own handshake (to wrap the unreachable-MCP error, or
+ * pass custom clientInfo); it defaults to `() => client.initialize()`.
+ *
+ * If the retired operator env-triple is set it emits a one-line advisory (see
+ * warnLegacyOperatorEnv) and proceeds on the OAuth session regardless — the keys
+ * are never read for auth.
  *
  * @param {ReturnType<import("./mcp.mjs").createMcpClient>} client
- * @param {{ env?: NodeJS.ProcessEnv, prefer?: "operator"|"developer",
- *   initialize?: () => Promise<any> }} [opts]
- * @returns {Promise<{ identity: "operator"|"developer", appDomain: string|null, email?: string|null }>}
+ * @param {{ env?: NodeJS.ProcessEnv, initialize?: () => Promise<any> }} [opts]
+ * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null }>}
  */
 export async function establishSession(client, opts = {}) {
   const env = opts.env || process.env;
-  const prefer = opts.prefer || (hasOperatorCreds(env) ? "operator" : "developer");
   const initialize = opts.initialize || (() => client.initialize());
 
-  if (prefer === "developer") {
-    // Attach the bearer, THEN handshake — the handshake carries the Authorization
-    // header so the server binds this identity at initialize time.
-    const session = await resolveDeveloperSession(client, env);
-    await initialize();
-    return session;
-  }
-  // Operator: handshake FIRST, then credential_validate (an in-session tool call).
+  warnLegacyOperatorEnv(env);
+  // Attach the bearer, THEN handshake — the handshake carries the Authorization
+  // header so the server binds this identity at initialize time.
+  const session = await resolveDeveloperSession(client, env);
   await initialize();
-  return resolveSession(client, { env, prefer });
+  return session;
 }
 
 /**

package/src/commands/checkout.mjs

@@ -6,15 +6,15 @@
  *   tot checkout <tenant>             show the checkout for <tenant>
  *   tot checkout <tenant> --clone DIR clone it to DIR with an authed remote
  *
- * This is the SAME MCP code path a developer/operator gets when they switch to a
- * tenant: credential/sign-in → client_switch(tenant) → tenant_checkout, where
- * the MCP derives your per-tenant Git user and mints a FRESH, single-active,
- * repo-scoped push credential (a later checkout for the same tenant rotates it).
- * `tot` performs NO privileged forge work itself — the MCP owns that.
+ * This is the SAME MCP code path a developer gets when they switch to a tenant:
+ * sign-in → client_switch(tenant) → tenant_checkout, where the MCP derives your
+ * per-tenant Git user and mints a FRESH, single-active, repo-scoped push
+ * credential (a later checkout for the same tenant rotates it). `tot` performs NO
+ * privileged forge work itself — the MCP owns that.
  *
- * Auth is resolved through src/auth.mjs: operator creds (our dogfooding / CI) or
- * the developer's own ToT identity. This command doesn't care
- * which — it just needs a validated session.
+ * Auth is the developer's own ToT identity (the cached `tot login` session,
+ * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
+ * offer to sign in right here and retry — no "run tot login, then re-run".
  *
  * Dependency-free (global fetch + `git` via child_process).
  */
@@ -22,6 +22,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { offerSignIn } from "./login.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
@@ -36,7 +37,6 @@ function parseArgs(argv) {
     tag: "main",
     clone: null,
     mcp: null,
-    identity: null, // "operator" | "developer" — override auto-selection
     printRemote: false,
     help: false,
   };
@@ -45,7 +45,6 @@ function parseArgs(argv) {
     if (t === "--tag") a.tag = argv[++i];
     else if (t === "--clone") a.clone = argv[++i];
     else if (t === "--mcp") a.mcp = argv[++i];
-    else if (t === "--identity") a.identity = argv[++i];
     else if (t === "--print-remote") a.printRemote = true;
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
@@ -64,7 +63,6 @@ Options:
   --clone <dir>     git clone the authenticated remote into <dir>.
   --mcp <url>       MCP base URL. Default: env MCP_BASE_URL / TOT_MCP_URL, else
                     ${DEFAULT_MCP_URL}.
-  --identity <who>  force "operator" or "developer" auth (default: auto).
   --print-remote    also print the authenticated remote (contains a live token!).`;
 
 /** Redact known secrets from any string before it hits the terminal. */
@@ -100,12 +98,21 @@ export async function run(argv, ctx) {
 
   try {
     // Attach auth in the right order relative to the handshake (developer bearer
-    // BEFORE initialize; operator credential_validate after) — see establishSession.
-    const session = await establishSession(client, {
-      env,
-      prefer: args.identity || undefined,
-    });
-    console.error(`~ signed in (${session.identity}) → ${client.mcpUrl}`);
+    // BEFORE initialize) — see establishSession. When there's no session yet and
+    // we're on a TTY, offer to sign in inline and retry once, so a not-signed-in
+    // developer isn't dead-ended at "run tot login, then re-run".
+    try {
+      await establishSession(client, { env });
+    } catch (e) {
+      if (e instanceof AuthUnavailableError && e.reason === "missing") {
+        const signedIn = await offerSignIn(client.mcpUrl, env, {});
+        if (!signedIn) throw e; // declined/non-TTY → the crisp error below
+        await establishSession(client, { env }); // retry once, in-flow
+      } else {
+        throw e;
+      }
+    }
+    console.error(`~ signed in → ${client.mcpUrl}`);
 
     // No tenant → list the stores this identity can build on and stop.
     if (!args.tenant) {

package/src/commands/dev.mjs

@@ -651,7 +651,7 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
  *
  * Exported + accepts an already-authenticated `client` (C1/F3 integration:
  * `tot start` reuses its own session and overlaps this with the checkout clone
- * instead of paying for a second client.initialize()+resolveSession() — same
+ * instead of paying for a second client.initialize()+establishSession() — same
  * pattern as ensureRegistryLogin's `providedClient`). `tot dev` standalone
  * omits it and this establishes its own, as before.
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
@@ -1355,7 +1355,7 @@ export function isPrivateRegistryImage(image) {
  *
  * Exported + accepts an already-authenticated `client` (C1: `tot start` reuses
  * its own session and overlaps this with the checkout clone instead of paying
- * for a second client.initialize()+resolveSession() serially afterward).
+ * for a second client.initialize()+establishSession() serially afterward).
  * `tot dev` standalone omits it and this establishes its own, as before.
  */
 export async function ensureRegistryLogin(image, args, { client: providedClient } = {}) {

package/src/commands/doctor.mjs

@@ -22,7 +22,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { hasOperatorCreds } from "../auth.mjs";
+import { hasLegacyOperatorEnv, legacyOperatorEnvAdvisory } from "../auth.mjs";
 import { MIN_NODE, nodeMeetsFloor } from "../ensure-node.mjs";
 import { clientPackages, osLabel } from "../mcp.mjs";
 import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
@@ -110,28 +110,34 @@ export function collectChecks(_ctx, env = process.env) {
     blocking: false,
   });
 
-  const operator = hasOperatorCreds(env);
-  const devCreds = operator ? null : readCredentials(defaultCredentialsPath(env));
+  const devCreds = readCredentials(defaultCredentialsPath(env));
   const devUsable = !!devCreds?.accessToken && (!isExpired(devCreds) || !!devCreds.refreshToken);
   checks.push({
     name: "auth identity",
-    pass: operator || devUsable,
-    detail: operator
-      ? "operator creds present (TOT_API_KEY/TOT_SECRET_KEY/TOT_APP_DOMAIN)"
-      : devUsable
-        ? "signed in as a developer"
-        : "not signed in — run `tot login`",
+    pass: devUsable,
+    detail: devUsable ? "signed in as a developer" : "not signed in — run `tot login`",
     blocking: false,
   });
 
+  // A stale operator env-triple no longer signs the CLI in (OAuth-first since
+  // 2026-07-23) — surface it as an informational note, never a failure.
+  if (hasLegacyOperatorEnv(env)) {
+    checks.push({
+      name: "legacy keys",
+      pass: true,
+      detail: legacyOperatorEnvAdvisory,
+      blocking: false,
+    });
+  }
+
   return checks;
 }
 
 /**
  * Auto-remediate the checks that are safely fixable without human judgment
  * (F2) — announcing each one as it runs. A stale-but-refreshable sign-in isn't
- * handled here because it isn't a failing check: resolveSession() refreshes it
- * silently the next time it's actually used (B4).
+ * handled here because it isn't a failing check: the developer session refreshes
+ * it silently the next time it's actually used (B4).
  */
 async function applyFixes(checks, env) {
   const totDir = join(env.TOT_HOME || homedir(), ".tot");
@@ -144,7 +150,7 @@ async function applyFixes(checks, env) {
   if (docker && !docker.pass) await tryStartDocker();
 
   const auth = checks.find((c) => c.name === "auth identity");
-  if (auth && !auth.pass && !hasOperatorCreds(env)) {
+  if (auth && !auth.pass) {
     const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
     console.log("  ~ not signed in — opening the browser to sign in…");
     try {

package/src/commands/feedback.mjs

@@ -9,8 +9,8 @@
  * the developer copy-pasting anything.
  *
  * Auth: the MCP feedback tool is authenticated, so this reuses the signed-in session
- * (`resolveSession` → operator creds if present, else the `tot login` developer
- * token). Not signed in → a clear "run `tot login`" instead of a stack trace.
+ * (the `tot login` developer token, via `establishSession`). Not signed in → a
+ * clear "run `tot login`" instead of a stack trace.
  *
  * Sending publishes to Token of Trust, so we PREVIEW the report and ask before
  * sending (skippable with --yes; required in a non-interactive shell).
@@ -179,8 +179,8 @@ export async function run(argv) {
   const client = createMcpClient(mcpUrl);
   try {
     // Attach auth in the right order relative to the handshake (developer bearer
-    // pre-initialize, operator credential_validate post-initialize). We keep the
-    // feedback-specific clientInfo by injecting our own initialize.
+    // pre-initialize). We keep the feedback-specific clientInfo by injecting our
+    // own initialize.
     await establishSession(client, {
       env,
       initialize: () => client.initialize({ name: "tot-cli", version: "feedback" }),