@tokenoftrust/cli 1.4.0-rc.0 → 1.4.0-rc.2

package/README.md

@@ -46,18 +46,24 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 - 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`)
+### Optional: 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:
+**Most people never set this** — the single default session is all you need, and a plain `tot login` just replaces it. Reach for a profile only when you want **more than one identity live at the same time**: a staff `@tokenoftrust.com` sign-in alongside a plain developer one, or many parallel test identities. Set it per shell and each gets its own credential file under `~/.tot` (the renderer cache and everything else stay shared):
 
 ```
-# terminal A
-export TOT_PROFILE=staff && tot login
-# terminal B
-export TOT_PROFILE=dev   && tot login
+# terminal A                     # terminal B
+export TOT_PROFILE=staff         export TOT_PROFILE=dev
+tot login                        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.
+The value is an **opaque label** — any string works, so it's easy to script parallel identities:
+
+```
+export TOT_PROFILE=$(uuidgen)    # a fresh isolated identity per terminal / test worker
+tot login
+```
+
+A clean short name (`staff`, `dev`, `test-7`) becomes a readable `credentials.<name>.json`; any other value (symbols, uppercase, long) is hashed to a stable `credentials.h<hash>.json` — so an arbitrary id never collides or escapes `~/.tot`. Unset → the default session, unchanged. `tot whoami` shows the active profile.
 
 ## Design notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.0",
+  "version": "1.4.0-rc.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/commands/login.mjs

@@ -19,7 +19,7 @@
  *
  * Dependency-free (node built-ins via oauth.mjs).
  */
-import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oauth.mjs";
+import { loginFlow, deviceLoginFlow, rendezvousLoginFlow, NoOpenerError } from "../oauth.mjs";
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
@@ -188,23 +188,25 @@ export async function offerSignIn(mcpUrl, env = process.env, {
 }
 
 /**
- * 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
- * client for THIS MCP so we don't re-register on every login.
+ * The core of `tot login --code`: run the browserless RENDEZVOUS sign-in (attach the
+ * terminal's PKCE challenge to the pasted rendezvous handle, surface the fingerprint,
+ * poll until the developer approves it in the cockpit) and cache the grant, reusing a
+ * previously-registered client for THIS MCP so we don't re-register on every login.
+ * `log` carries the fingerprint + "waiting for approval" lines to the terminal.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function redeemAndCache(mcpUrl, code, env = process.env) {
+export async function redeemAndCache(mcpUrl, code, env = process.env, { log = () => {} } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
   const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
-  const creds = await redeemCodeFlow({ mcpUrl, clientId, code });
+  const creds = await rendezvousLoginFlow({ mcpUrl, clientId, code, log });
   const merged = mergeActivityBridge(prior, mcpUrl, creds);
   writeCredentials(path, merged);
   return merged;
 }
 
 /**
- * `loginFlow`/`deviceLoginFlow`/`redeemCodeFlow` all return the bare OAuth shape —
+ * `loginFlow`/`deviceLoginFlow`/`rendezvousLoginFlow` all return the bare OAuth shape —
  * none of them know about activityToken/activityUrl, a SEPARATE credential this
  * same file caches via cacheActivityBridge. A bare re-login (no --code) after a
  * prior --code sign-in would otherwise silently drop it on the next `writeCredentials`
@@ -258,7 +260,7 @@ export async function run(argv, _ctx) {
   if (args.code) {
     console.error(`~ signing in to Token of Trust with your invite code (${mcpUrl})`);
     try {
-      await redeemAndCache(mcpUrl, args.code, env);
+      await redeemAndCache(mcpUrl, args.code, env, { log: (m) => console.error(m) });
       cacheActivityBridge(env, args.activityToken, args.activityUrl);
       cacheTraceId(env, args.traceId);
       cacheEmailHint(env, args.emailHint);

package/src/oauth.mjs

@@ -285,41 +285,50 @@ export async function loginFlow({
   }
 }
 
-// ── WS2b: browserless invite-code redemption (`tot login --code <token>`) ─────
+// ── Browserless CLI sign-in — RFC 8628 RENDEZVOUS (`tot login --code <handle>`) ──
 //
-// The invited developer pastes the single-use sign-in token their invite minted;
-// we hand it to the MCP's redeem endpoint, which validates + BURNS it via ToT and
-// returns a normal MCP OAuth grant. No browser, no loopback, no OTP — the token IS
-// the operator's authorization. Same credentials shape as loginFlow/deviceLoginFlow,
-// and the grant is bound to our registered client_id so later silent refreshes go
-// through the standard token endpoint like any other session.
+// The invited developer pastes the NON-SECRET rendezvous handle their cockpit
+// rendered. Unlike the retired bearer-redeem (a secret received elsewhere, replayed
+// once), the terminal generates its OWN PKCE key here, ATTACHES only the public
+// challenge to the pending rendezvous, prints a human-verifiable fingerprint, and
+// polls the standard token endpoint (device_code grant + PKCE) until the developer
+// approves that fingerprint in the cockpit. Same credentials shape as
+// loginFlow/deviceLoginFlow, same dynamically-registered client_id, so later silent
+// refreshes go through the standard token endpoint like any other session.
 //
-// Wire contract (CLI → MCP):
-//   POST {mcp-origin}/oauth/redeem-code   (application/json)
-//     { code: "<invite sign-in token>", client_id, scope? }
-//   → 200 { access_token, refresh_token, token_type, expires_in, scope }
-//   → 400 { error, error_description }   (invalid_grant | invalid_client)
+// Wire contract (CLI → MCP), all off the MCP origin (from the AS token endpoint):
+//   POST /oauth/device/attach  (application/json)
+//     { rendezvous_code, client_id, code_challenge, code_challenge_method: "S256" }
+//     → 200 { device_code, user_fingerprint, interval, expires_in }
+//     → 400 { error, error_description }   (invalid_grant | invalid_client)
+//   POST /oauth/token  (form)  grant_type=…:device_code, device_code, code_verifier,
+//     client_id → RFC 8628 polling until approved/denied/expired.
 //
-// The token→CLI binding is inherent to the single request: the tokens are returned
-// only in the direct TLS response to the client that presented the code, and the
-// grant is pinned to our dynamically-registered client_id (only that client can
-// refresh it). A separate PKCE nonce would add nothing here — there is no second
-// exchange step at which a verifier could be presented.
-
-/** The MCP's redeem endpoint — the MCP origin (from the AS token endpoint) + a
- * fixed path. Kept beside the flow so the path lives in exactly one place. */
-export function redeemCodeEndpoint(mcpUrl, meta) {
+// Device-bound by construction: the pasted handle attaches only a PUBLIC PKCE
+// challenge (intercepting it grants nothing — an interceptor's terminal shows a
+// DIFFERENT fingerprint the developer won't approve), and only the terminal holding
+// the matching verifier can redeem the device_code at /oauth/token.
+
+/** An MCP device/rendezvous endpoint — the MCP origin (from the AS token endpoint)
+ * + a fixed path. Kept beside the flow so the paths live in exactly one place. */
+export function deviceEndpoint(mcpUrl, meta, path) {
   const origin = meta?.token_endpoint ? new URL(meta.token_endpoint) : new URL(mcpUrl);
-  return new URL("/oauth/redeem-code", origin).toString();
+  return new URL(path, origin).toString();
 }
 
-/** POST the invite token to the MCP redeem endpoint and return the raw token
- * response (→ credentialsFromToken). Throws a clear, non-stack error on rejection. */
-export async function redeemInviteCode(redeemEndpoint, { code, clientId, scope = SCOPE }, fetchImpl = fetch) {
-  const res = await fetchImpl(redeemEndpoint, {
+/** Attach the terminal's PKCE challenge to a pending rendezvous. Returns the raw
+ * response { device_code, user_fingerprint, interval, expires_in }. Throws a clear,
+ * non-stack error on rejection (an expired / already-used handle). */
+export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientId, challenge }, fetchImpl = fetch) {
+  const res = await fetchImpl(attachEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "application/json" },
-    body: JSON.stringify({ code, client_id: clientId, scope }),
+    body: JSON.stringify({
+      rendezvous_code: rendezvousCode,
+      client_id: clientId,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+    }),
   });
   const text = await res.text();
   let body;
@@ -328,31 +337,57 @@ export async function redeemInviteCode(redeemEndpoint, { code, clientId, scope =
     const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
     throw new Error(`your sign-in code was not accepted (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
   }
-  if (!body.access_token) throw new Error("the redeem endpoint returned no access_token");
+  if (!body.device_code || !body.user_fingerprint) {
+    throw new Error("the attach endpoint returned no device_code/fingerprint");
+  }
   return body;
 }
 
 /**
- * Run the full browserless redemption and return a persistable credentials record
- * — the invite-token sibling of loginFlow()/deviceLoginFlow(), same credentials
- * shape, same dynamically-registered client_id (reused when the caller cached one
- * for this MCP). Injectable (`fetchImpl`, `now`) so it's testable with no network.
+ * Run the full browserless rendezvous sign-in and return a persistable credentials
+ * record — the invite sibling of loginFlow()/deviceLoginFlow(), same credentials
+ * shape + dynamically-registered client_id (reused when the caller cached one for
+ * this MCP). The terminal generates its own PKCE key, attaches, surfaces the
+ * fingerprint via `log` for the developer to confirm in the cockpit, then polls the
+ * token endpoint until approved. Injectable (`fetchImpl`, `log`, `sleep`, `now`) so
+ * it's testable with no network and no real waiting.
  * @returns {Promise<object>} credentials to hand to writeCredentials()
  */
-export async function redeemCodeFlow({
+export async function rendezvousLoginFlow({
   mcpUrl,
   clientId,
   code,
   fetchImpl = fetch,
+  log = () => {},
+  sleep = delay,
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
   const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
-  const token = await redeemInviteCode(
-    redeemCodeEndpoint(mcpUrl, meta),
-    { code, clientId: resolvedClientId },
+  const { verifier, challenge } = generatePkce();
+
+  const attach = await attachRendezvous(
+    deviceEndpoint(mcpUrl, meta, "/oauth/device/attach"),
+    { rendezvousCode: code, clientId: resolvedClientId, challenge },
     fetchImpl,
   );
+
+  log("");
+  log(`  Confirm this code in your browser to finish signing in:  ${attach.user_fingerprint}`);
+  log("  Waiting for you to approve it in Token of Trust …");
+
+  const token = await pollDeviceToken(
+    meta.token_endpoint,
+    {
+      deviceCode: attach.device_code,
+      clientId: resolvedClientId,
+      codeVerifier: verifier,
+      intervalSec: attach.interval,
+      expiresInSec: attach.expires_in,
+    },
+    fetchImpl,
+    { sleep, now },
+  );
   return credentialsFromToken({
     mcpUrl,
     clientId: resolvedClientId,
@@ -395,7 +430,7 @@ export async function deviceAuthorize(deviceAuthorizationEndpoint, { clientId, s
  * normal "keep waiting" responses — so this resolves `{ pending: true }`
  * (with `slowDown` set) for those instead of throwing.
  */
-async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImpl) {
+async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifier }, fetchImpl) {
   const res = await fetchImpl(tokenEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
@@ -403,6 +438,10 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImp
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       device_code: deviceCode,
       client_id: clientId,
+      // The rendezvous flow binds the grant to the terminal's PKCE key: the
+      // verifier proves this is the same terminal that attached the challenge.
+      // Absent for the plain RFC 8628 device flow (no PKCE) — omitted then.
+      ...(codeVerifier ? { code_verifier: codeVerifier } : {}),
     }).toString(),
   });
   const text = await res.text();
@@ -428,7 +467,7 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImp
  */
 export async function pollDeviceToken(
   tokenEndpoint,
-  { deviceCode, clientId, intervalSec, expiresInSec },
+  { deviceCode, clientId, codeVerifier, intervalSec, expiresInSec },
   fetchImpl = fetch,
   { sleep = delay, now = () => Date.now() } = {},
 ) {
@@ -437,7 +476,7 @@ export async function pollDeviceToken(
   for (;;) {
     await sleep(intervalMs);
     if (now() >= deadline) throw new Error("the device code expired before it was approved");
-    const r = await deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImpl);
+    const r = await deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifier }, fetchImpl);
     if (!r.pending) return r.token;
     if (r.slowDown) intervalMs += 5000;
   }

package/src/token-store.mjs

@@ -30,36 +30,59 @@
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
  *
- * PROFILES (`TOT_PROFILE`): single-plane auth means one active identity per
- * credential file, so to keep DIFFERENT identities live at once — e.g. a staff
- * `@tokenoftrust.com` sign-in in one terminal and a plain developer identity in
- * another — export a profile per shell (`export TOT_PROFILE=staff` / `=dev`).
- * Each profile gets its OWN `credentials.<profile>.json` under the same `~/.tot`
- * (the renderer cache, last-tenant, etc. stay shared — only the identity splits).
- * Unset → the default `credentials.json`, so existing sessions are untouched.
+ * PROFILES (`TOT_PROFILE`) — OPTIONAL, for parallel work. Almost every developer
+ * leaves this UNSET and uses the single default `credentials.json` — that path is
+ * unchanged and is the norm. It exists only when you want MORE THAN ONE identity
+ * live at once (a staff `@tokenoftrust.com` sign-in and a plain developer one, or
+ * many parallel test identities): export a profile per shell and each gets its OWN
+ * credential file under the same `~/.tot` (the renderer cache, last-tenant, etc.
+ * stay shared — only the identity splits). The value is an OPAQUE label — any
+ * string works, so `export TOT_PROFILE=$(uuidgen)` per terminal/test is fine:
+ *   - a clean short token (`staff`, `dev`, `test-7`) is used verbatim for a
+ *     readable `credentials.<profile>.json`;
+ *   - any other value (symbols, uppercase, long) is HASHED to a stable, safe
+ *     `credentials.h<hash>.json` — so an arbitrary opaque id can never collide
+ *     with another or escape `~/.tot`, while `tot whoami` still shows what you set.
  */
 import {
   readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, rmSync,
 } from "node:fs";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 
+/** A short token safe to drop straight into a filename (readable profiles). */
+const CLEAN_PROFILE_RE = /^[a-z0-9_-]{1,64}$/;
+
 /**
- * The active credential profile from `TOT_PROFILE`, sanitized to a safe filename
- * token (`[a-z0-9_-]`, lowercased, ≤64 chars), or null for the default
- * (unnamespaced) session. Sanitizing — not just trusting the value — keeps a
- * stray `/` or `..` from ever escaping the `~/.tot` dir.
+ * The active profile's DISPLAY label — the raw `TOT_PROFILE`, trimmed — or null
+ * when unset. This is what `tot whoami` shows; it is NOT the filename (see
+ * profileSlug, which makes any value filesystem-safe).
  */
 export function activeProfile(env = process.env) {
-  const safe = String(env.TOT_PROFILE || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "").slice(0, 64);
-  return safe || null;
+  return String(env.TOT_PROFILE || "").trim() || null;
+}
+
+/**
+ * The active profile's safe filename token, or null for the default session. A
+ * clean short label passes through verbatim (readable files); ANY other opaque
+ * value is hashed — collision-resistant and incapable of a `/` or `..` path
+ * escape, so `TOT_PROFILE` can be a literally arbitrary identifier. Hashing the
+ * RAW value (not a stripped form) keeps distinct tokens distinct.
+ */
+export function profileSlug(env = process.env) {
+  const raw = String(env.TOT_PROFILE || "").trim();
+  if (!raw) return null;
+  const lower = raw.toLowerCase();
+  if (CLEAN_PROFILE_RE.test(lower)) return lower;
+  return `h${createHash("sha256").update(raw).digest("hex").slice(0, 16)}`;
 }
 
 /** Absolute path to the credential file for this environment (+ TOT_PROFILE). */
 export function defaultCredentialsPath(env = process.env) {
   const home = env.TOT_HOME || homedir();
-  const profile = activeProfile(env);
-  return join(home, ".tot", profile ? `credentials.${profile}.json` : "credentials.json");
+  const slug = profileSlug(env);
+  return join(home, ".tot", slug ? `credentials.${slug}.json` : "credentials.json");
 }
 
 /**