@tokenoftrust/cli 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "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

@@ -132,5 +132,70 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
   }
 
   if (client && typeof client.setToken === "function") client.setToken(creds.accessToken);
-  return { identity: "developer", appDomain: null, token: creds.accessToken };
+  return {
+    identity: "developer",
+    appDomain: null,
+    token: creds.accessToken,
+    email: emailFromJwt(creds.accessToken),
+  };
+}
+
+/**
+ * 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.
+ *
+ * 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()`.
+ *
+ * @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 }>}
+ */
+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).
+  await initialize();
+  return resolveSession(client, { env, prefer });
+}
+
+/**
+ * Best-effort email from an OAuth access token when it's a JWT — for DISPLAY ONLY
+ * (self-diagnosing dead-ends: "signed in as <email> via <origin>"), never for trust.
+ * Decodes the unverified payload segment; returns null for an opaque token or one
+ * with no email-ish claim. Never throws.
+ * @param {string} token
+ * @returns {string|null}
+ */
+export function emailFromJwt(token) {
+  try {
+    const seg = String(token).split(".")[1];
+    if (!seg) return null;
+    const json = JSON.parse(
+      Buffer.from(seg.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"),
+    );
+    return json.email || json.preferred_username || null;
+  } catch {
+    return null;
+  }
 }

package/src/commands/checkout.mjs

@@ -20,7 +20,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -94,8 +94,9 @@ export async function run(argv, ctx) {
   const client = createMcpClient(baseUrl);
 
   try {
-    await client.initialize();
-    const session = await resolveSession(client, {
+    // 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,
     });
@@ -218,10 +219,47 @@ export function normalizeStores(list) {
     .filter((r) => r.id);
 }
 
+/**
+ * Detect whether a `client_list` tool result is an ERROR result rather than a
+ * genuinely empty-but-successful store list — so callers surface it (identity +
+ * origin + reason, per fb-1783905718950-f45zg9) instead of collapsing it to an
+ * empty list and dead-ending at "ask for an invite". callTool unwraps a tool
+ * result to its structuredContent / parsed text, so an error surfaces as a
+ * status other than ok/success, an `error`/`isError` field, or an unparseable
+ * `raw` text blob. A response that carries a resolvable store array (even empty)
+ * is always a success. Returns a short human reason, or null when it's not an
+ * error. Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @returns {string|null}
+ */
+export function storeListError(list) {
+  if (list == null || typeof list !== "object" || Array.isArray(list)) return null;
+  // A resolvable store array present → it succeeded, never an error.
+  if (Array.isArray(list.clients) || Array.isArray(list.tenants)) return null;
+  const msg =
+    list.message ||
+    (typeof list.error === "string" ? list.error : list.error?.message) ||
+    null;
+  if (list.isError) return msg || "the store list request returned an error";
+  if (typeof list.status === "string" && !/^(ok|success)$/i.test(list.status)) {
+    return msg || `the store list request returned status "${list.status}"`;
+  }
+  if (list.error) return msg || "the store list request returned an error";
+  if (typeof list.raw === "string" && list.raw.trim()) return list.raw.trim();
+  return null;
+}
+
 function printClientList(list) {
+  const err = storeListError(list);
   const stores = normalizeStores(list);
+  if (err && stores.length === 0) {
+    console.log(`\nCouldn't list your stores: ${err}`);
+    console.log("Run `tot whoami` to check your session, or `tot login` again.");
+    return;
+  }
   if (stores.length === 0) {
     console.log("\nNo stores available to build on for this identity yet.");
+    console.log("If you were just invited, it may still be propagating — try again in a minute.");
     if (list && !Array.isArray(list)) console.log(JSON.stringify(list, null, 2));
     return;
   }

package/src/commands/dev.mjs

@@ -40,7 +40,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession } from "../auth.mjs";
+import { establishSession } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
 import {
@@ -328,8 +328,9 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
   const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = providedClient || createMcpClient(baseUrl);
   if (!providedClient) {
-    await client.initialize();
-    await resolveSession(client, { env: process.env });
+    // Auth before the entitlement-gated tool call, in handshake order (developer
+    // bearer pre-initialize) — see establishSession.
+    await establishSession(client, { env: process.env });
   }
   const res = await client.callTool("dev_renderer_artifact", {});
   if (!res?.url || !res?.version) {
@@ -360,8 +361,8 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
   try {
     const client = providedClient || createMcpClient(baseUrl);
     if (!providedClient) {
-      await client.initialize();
-      await resolveSession(client, { env: process.env });
+      // Auth in handshake order before the entitlement-gated tool call.
+      await establishSession(client, { env: process.env });
     }
     const res = await client.callTool("dev_renderer_artifact", {});
     if (!res?.url || !res?.version) {
@@ -765,8 +766,8 @@ export async function ensureRegistryLogin(image, args, { client: providedClient
   try {
     const client = providedClient || createMcpClient(baseUrl);
     if (!providedClient) {
-      await client.initialize();
-      await resolveSession(client, { env: process.env });
+      // Auth in handshake order before the entitlement-gated tool call.
+      await establishSession(client, { env: process.env });
     }
     const tok = await client.callTool("dev_image_pull_token", {});
     const username = tok?.username || "AWS";

package/src/commands/feedback.mjs

@@ -22,7 +22,7 @@
  */
 import { createInterface } from "node:readline/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
 import { fail } from "../errors.mjs";
 
@@ -145,8 +145,13 @@ export async function run(argv) {
   const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(mcpUrl);
   try {
-    await resolveSession(client);
-    await client.initialize({ name: "tot-cli", version: "feedback" });
+    // 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.
+    await establishSession(client, {
+      env,
+      initialize: () => client.initialize({ name: "tot-cli", version: "feedback" }),
+    });
     const payload = {
       type: args.type,
       category: args.category,

package/src/commands/start.mjs

@@ -50,12 +50,12 @@ import { createInterface } from "node:readline/promises";
 
 import { detectContext } from "../context.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, checkoutTenant } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -193,11 +193,17 @@ export async function run(argv, ctx) {
     // Authenticated path. Preflight (F) now that we know we're taking it — the
     // local machine checks (node/git/Docker) that the authed loop needs.
     await preflight(ctx, env);
-    console.log(`  ✓ signed in as ${session.identity}${session.appDomain ? ` (${session.appDomain})` : ""}`);
+    console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
     // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
-    const stores = normalizeStores(await client.callTool("client_list", {}));
-    const tenant = await resolveTenant(stores, args, env, baseUrl);
+    // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
+    // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
+    const listResp = await client.callTool("client_list", {});
+    const stores = normalizeStores(listResp);
+    const tenant = await resolveTenant(stores, args, env, baseUrl, {
+      session,
+      listErr: storeListError(listResp),
+    });
 
     // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
     // OVERLAPPED (C1) with prefetching the runner: the native artifact by
@@ -340,14 +346,24 @@ async function runSampleStart(args, ctx, env, startedAt) {
  * AuthUnavailableError (no creds) or a CliError (can't reach the MCP).
  */
 async function loginStep(client, env, args) {
-  try {
-    await client.initialize();
-  } catch (e) {
-    throw new CliError(`can't reach the Token of Trust MCP at ${client.mcpUrl} (${String(e?.message || e)})`, {
-      next: "check your network, then re-run — or point elsewhere with --mcp <url>",
-    });
-  }
-  return resolveSession(client, { env, prefer: args.identity || undefined });
+  // 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.
+  return establishSession(client, {
+    env,
+    prefer: args.identity || undefined,
+    initialize: async () => {
+      try {
+        await client.initialize();
+      } catch (e) {
+        throw new CliError(`can't reach the Token of Trust MCP at ${client.mcpUrl} (${String(e?.message || e)})`, {
+          next: "check your network, then re-run — or point elsewhere with --mcp <url>",
+        });
+      }
+    },
+  });
 }
 
 /**
@@ -436,12 +452,59 @@ async function prefetchDockerLogin(client, devArgs, env) {
   if (!dockerAvailable()) await tryStartDocker();
 }
 
+/** 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. */
+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";
+}
+
+/** The MCP host for user-facing messages (never the full /mcp URL). */
+function mcpOrigin(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return String(baseUrl);
+  }
+}
+
+/**
+ * Build the CliError for an authenticated session that surfaced NO usable store,
+ * making the dead-end SELF-DIAGNOSING (fb-1783905718950-f45zg9): always report who
+ * we're signed in as and against which MCP, and distinguish an ERRORED client_list
+ * (surface the reason — likely an auth/entitlement problem) from a genuinely empty
+ * result (invite may still be propagating, or you need one). Points at `tot whoami`.
+ */
+function noStoresError({ session, baseUrl, listErr }) {
+  const who = describeIdentity(session);
+  const origin = mcpOrigin(baseUrl);
+  if (listErr) {
+    return new CliError(
+      `signed in as ${who} via ${origin}, but listing your stores failed: ${listErr}`,
+      { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
+    );
+  }
+  return new CliError(
+    `signed in as ${who} via ${origin}, but you have no stores to build on yet`,
+    {
+      next:
+        "if you were just invited, it may still be propagating — try again in a minute; " +
+        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`), " +
+        "or `tot start --sample` for the free local preview",
+    },
+  );
+}
+
 /**
  * Resolve the tenant to work on from the (normalized) store list, args, and
  * the remembered last tenant (A4) — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
-async function resolveTenant(stores, args, env, baseUrl) {
+async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
     explicit: args.tenant || null,
@@ -450,9 +513,7 @@ async function resolveTenant(stores, args, env, baseUrl) {
 
   let tenant;
   if (pick.kind === "none") {
-    throw new CliError("no stores you can build on yet", {
-      next: "ask your Token of Trust contact for a store invite, then re-run — or `tot start --sample` for the free local preview",
-    });
+    throw noStoresError({ session, baseUrl, listErr });
   } else if (pick.kind === "explicit") {
     tenant = pick.tenant;
     console.log(`  → your store: ${tenant} (--tenant)`);

package/src/commands/submit.mjs

@@ -33,7 +33,7 @@
 import { execFileSync } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
@@ -138,8 +138,9 @@ export async function run(argv, ctx) {
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(baseUrl);
   try {
-    await client.initialize();
-    await resolveSession(client, { env, prefer: args.identity || undefined });
+    // Attach auth before the first server call (developer bearer pre-initialize,
+    // operator credential_validate post-initialize) — see establishSession.
+    await establishSession(client, { env, prefer: args.identity || undefined });
     // Set the active tenant so preview_status reads the right scope (it keys on
     // the session's tenant + the commit — no tenant arg of its own).
     await client.callTool("client_switch", { tenant });

package/src/commands/whoami.mjs

@@ -10,9 +10,9 @@
  * Dependency-free.
  */
 import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
-import { hasOperatorCreds, resolveDeveloperSession } from "../auth.mjs";
+import { hasOperatorCreds, establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores } from "./checkout.mjs";
+import { normalizeStores, storeListError } from "./checkout.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**
@@ -55,17 +55,22 @@ export async function run(argv, _ctx) {
   // identity or an unreachable MCP just shows the cached status above.
   try {
     const client = createMcpClient(status.mcpUrl || env.MCP_BASE_URL || env.TOT_MCP_URL || "https://mcp.tokenoftrust.com");
-    await client.initialize();
-    await resolveDeveloperSession(client, env);
+    // Developer bearer must be attached BEFORE initialize so the server binds this
+    // identity at handshake time — otherwise client_list resolves anonymously and
+    // (misleadingly) reports no stores (establishSession orders this correctly).
+    await establishSession(client, { env, prefer: "developer" });
     const listResp = await client.callTool("client_list", {});
     // Update-awareness Layer 2: an authed response may carry a version-support
     // policy (wire contract: `cliPolicy`). Safe no-op when absent.
     recordServerPolicy(listResp?.cliPolicy, env);
+    const listErr = storeListError(listResp);
     const stores = normalizeStores(listResp);
     if (stores.length) {
       console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
+    } else if (listErr) {
+      console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {
-      console.log("  (no stores resolved yet for this identity)");
+      console.log("  (no stores resolved yet — if you were just invited, it may still be propagating)");
     }
   } catch {
     console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");