@tokenoftrust/cli 1.0.0

package/src/mcp.mjs

@@ -0,0 +1,100 @@
+/**
+ * Minimal MCP JSON-RPC client — the transport `tot` uses to talk to the Token
+ * of Trust MCP (default https://mcp.tokenoftrust.com/mcp).
+ *
+ * Ported verbatim in behaviour from scripts/tenant/checkout.mjs (which proved
+ * this transport live against qa): a single streamable-HTTP endpoint that may
+ * answer as JSON or as an SSE stream, with the session id carried in the
+ * `Mcp-Session-Id` header across calls. Dependency-free (global fetch, Node 20+).
+ */
+
+/**
+ * @param {string} baseUrl - MCP base URL; `/mcp` is appended if absent.
+ * @param {{ token?: string }} [opts] - optional developer OAuth bearer to attach.
+ * @returns a small client: { mcpUrl, initialize, callRaw, callTool, sessionId(), setToken }
+ */
+export function createMcpClient(baseUrl, opts = {}) {
+  const trimmed = String(baseUrl).replace(/\/+$/, "");
+  const mcpUrl = trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
+  let rpcId = 0;
+  let sessionId = null;
+  // The developer OAuth bearer (set at login-resolve time via setToken, or up
+  // front via opts.token). Absent for the operator path, which authenticates by
+  // credential_validate + the Mcp-Session-Id below.
+  let bearer = typeof opts.token === "string" ? opts.token : null;
+
+  /** Attach (or clear) the developer bearer for subsequent calls. */
+  function setToken(token) {
+    bearer = token || null;
+  }
+
+  async function callRaw(method, params) {
+    const envelope = { jsonrpc: "2.0", id: ++rpcId, method, params };
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    };
+    if (bearer) headers.Authorization = `Bearer ${bearer}`;
+    if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+
+    const res = await fetch(mcpUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(envelope),
+    });
+    const sid = res.headers.get("Mcp-Session-Id");
+    if (sid) sessionId = sid;
+
+    const ct = res.headers.get("content-type") || "";
+    const text = await res.text();
+    if (!res.ok && !text) {
+      throw new Error(`${method} failed: HTTP ${res.status} ${res.statusText}`);
+    }
+
+    let parsed;
+    if (ct.includes("text/event-stream")) {
+      const lines = text
+        .split(/\r?\n/)
+        .filter((l) => l.startsWith("data:"))
+        .map((l) => l.slice(5).trim())
+        .filter(Boolean);
+      parsed = lines.length ? JSON.parse(lines[lines.length - 1]) : null;
+    } else {
+      parsed = text ? JSON.parse(text) : null;
+    }
+    if (parsed?.error) {
+      throw new Error(`${method} failed: ${JSON.stringify(parsed.error)}`);
+    }
+    return parsed?.result;
+  }
+
+  /** Call an MCP tool and unwrap its structured / text result to a plain object. */
+  async function callTool(name, args) {
+    const r = await callRaw("tools/call", { name, arguments: args });
+    if (r?.structuredContent) return r.structuredContent;
+    const tb = Array.isArray(r?.content)
+      ? r.content.find((c) => c?.type === "text")
+      : null;
+    if (tb?.text) {
+      try {
+        return JSON.parse(tb.text);
+      } catch {
+        return { raw: tb.text };
+      }
+    }
+    return r;
+  }
+
+  /** Complete the MCP handshake. Call once before any tool call. */
+  async function initialize(clientInfo = { name: "tot-cli", version: "0.1.0" }) {
+    await callRaw("initialize", {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo,
+    });
+    // Best-effort — some servers don't require the notification.
+    await callRaw("notifications/initialized", undefined).catch(() => {});
+  }
+
+  return { mcpUrl, initialize, callRaw, callTool, sessionId: () => sessionId, setToken };
+}

package/src/oauth.mjs

@@ -0,0 +1,409 @@
+/**
+ * The MCP OAuth 2.1 (PKCE) client for `tot login` — the SAME loopback flow that
+ * `claude mcp add` runs against the Token of Trust MCP. The developer's identity
+ * is a normal MCP OAuth token, minted by the MCP's own authorization server, and
+ * entitlement is derived server-side from the developer's ToT memberships (see
+ * 04-q1-foundation-analysis.md).
+ *
+ * The shape (RFC 8252 native-app + OAuth 2.1 + PKCE S256):
+ *   1. discover the AS metadata (authorize/token/registration endpoints),
+ *   2. dynamically register a PUBLIC client (token_endpoint_auth_method "none"),
+ *   3. bind a 127.0.0.1 loopback listener on an ephemeral port,
+ *   4. open the browser to /authorize (dev signs in with their ToT identity +
+ *      consents), capture code on the loopback callback,
+ *   5. exchange code -> { access_token, refresh_token, expires_in } with the PKCE
+ *      verifier, and hand back a credentials record the token-store persists.
+ *
+ * B3 adds the RFC 8628 device-authorization grant (deviceLoginFlow, below) for
+ * headless/SSH/no-browser boxes where the loopback can never be reached — same
+ * dynamically-registered client_id, same credentials shape, just a different
+ * dance: print a code, poll the token endpoint until it's approved elsewhere.
+ *
+ * The pieces are exported individually so the flow is unit-testable against a
+ * mocked `fetch` with no network. Dependency-free (node:http/crypto/timers + open.mjs).
+ */
+import http from "node:http";
+import crypto from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { openBrowser } from "./open.mjs";
+
+const CLIENT_NAME = "Token of Trust CLI (tot)";
+const SCOPE = "mcp offline_access"; // offline_access → the refresh token
+// Portless loopback: RFC 8252 §7.3 + the MCP's loopback exception — we register
+// this once and reuse the clientId across logins; each login binds a fresh
+// ephemeral port that the MCP matches port-agnostically.
+const LOOPBACK_REDIRECT = "http://127.0.0.1/callback";
+
+const b64url = (buf) =>
+  buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** Thrown by loginFlow() when no browser opener exists on this box. Callers
+ * catch it to fall through to deviceLoginFlow() (B3) instead of hanging. */
+export class NoOpenerError extends Error {
+  constructor(authorizeUrl) {
+    super("no browser opener available on this machine");
+    this.name = "NoOpenerError";
+    this.authorizeUrl = authorizeUrl;
+  }
+}
+
+/** A PKCE verifier + its S256 challenge (OAuth 2.1 mandates S256). */
+export function generatePkce() {
+  const verifier = b64url(crypto.randomBytes(32));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+/** An opaque anti-CSRF state nonce for the authorize round-trip. */
+export function randomState() {
+  return b64url(crypto.randomBytes(16));
+}
+
+/** Fetch the Authorization Server metadata (RFC 8414). */
+export async function discoverMetadata(mcpUrl, fetchImpl = fetch) {
+  const root = String(mcpUrl).replace(/\/+$/, "");
+  const url = `${root}/.well-known/oauth-authorization-server`;
+  const res = await fetchImpl(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) throw new Error(`could not read the MCP's OAuth metadata (HTTP ${res.status} at ${url})`);
+  const meta = await res.json();
+  if (!meta?.authorization_endpoint || !meta?.token_endpoint) {
+    throw new Error("the MCP's OAuth metadata is missing authorization/token endpoints");
+  }
+  return meta;
+}
+
+/** Dynamic Client Registration (RFC 7591) for a public PKCE client → clientId. */
+export async function registerClient(
+  registrationEndpoint,
+  redirectUri = LOOPBACK_REDIRECT,
+  fetchImpl = fetch,
+) {
+  if (!registrationEndpoint) throw new Error("the MCP does not advertise a registration endpoint");
+  const res = await fetchImpl(registrationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({
+      client_name: CLIENT_NAME,
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      scope: SCOPE,
+    }),
+  });
+  if (!res.ok) throw new Error(`client registration failed (HTTP ${res.status})`);
+  const body = await res.json();
+  if (!body?.client_id) throw new Error("client registration returned no client_id");
+  return body.client_id;
+}
+
+/** Build the /authorize URL carrying PKCE + state (no `resource` — the AS binds
+ * its own canonical MCP audience, and naming the wrong one is an invalid_target). */
+export function buildAuthorizeUrl(authorizationEndpoint, {
+  clientId, redirectUri, challenge, state, scope = SCOPE,
+}) {
+  const u = new URL(authorizationEndpoint);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("client_id", clientId);
+  u.searchParams.set("redirect_uri", redirectUri);
+  u.searchParams.set("scope", scope);
+  u.searchParams.set("state", state);
+  u.searchParams.set("code_challenge", challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  return u.toString();
+}
+
+async function tokenRequest(tokenEndpoint, params, fetchImpl) {
+  const res = await fetchImpl(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body: new URLSearchParams(params).toString(),
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  if (!res.ok) {
+    const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
+    throw new Error(`token request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+  }
+  if (!body.access_token) throw new Error("token endpoint returned no access_token");
+  return body;
+}
+
+/** Exchange the authorization code for tokens (PKCE verifier proves the client). */
+export function exchangeCode(tokenEndpoint, { code, verifier, clientId, redirectUri }, fetchImpl = fetch) {
+  return tokenRequest(tokenEndpoint, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: verifier,
+  }, fetchImpl);
+}
+
+/** Refresh an expired access token. Public client → no secret, just the refresh token. */
+export function refreshAccessToken(tokenEndpoint, { refreshToken, clientId }, fetchImpl = fetch) {
+  return tokenRequest(tokenEndpoint, {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId,
+  }, fetchImpl);
+}
+
+/**
+ * Normalize a token-endpoint response into the credentials record we persist.
+ * Refresh responses often omit a new refresh_token — the caller passes the prior
+ * one through so we never drop the ability to refresh again.
+ */
+export function credentialsFromToken({ mcpUrl, clientId, tokenEndpoint, scope = SCOPE, token, now = Date.now() }) {
+  const expiresIn = Number(token.expires_in) || 0;
+  return {
+    mcpUrl,
+    clientId,
+    tokenEndpoint,
+    scope: token.scope || scope,
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token || null,
+    expiresAt: expiresIn ? now + expiresIn * 1000 : null,
+    obtainedAt: now,
+  };
+}
+
+/**
+ * A 127.0.0.1 loopback listener for the OAuth redirect. Resolves `waitForCallback`
+ * with { code, state } on /callback, or rejects on an ?error= response. Binds an
+ * ephemeral port (`.ready()` → the chosen port).
+ */
+export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
+  let settle, reject;
+  const callback = new Promise((res, rej) => { settle = res; reject = rej; });
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, `http://${host}`);
+    if (u.pathname !== "/callback") {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("not found");
+      return;
+    }
+    const error = u.searchParams.get("error");
+    res.writeHead(error ? 400 : 200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(resultPage(error, u.searchParams.get("error_description")));
+    if (error) {
+      const d = u.searchParams.get("error_description");
+      reject(new Error(`authorization was denied (${error}${d ? `: ${d}` : ""})`));
+    } else {
+      settle({ code: u.searchParams.get("code"), state: u.searchParams.get("state") });
+    }
+  });
+  const listening = new Promise((res, rej) => {
+    server.once("error", rej);
+    server.listen(0, host, () => res());
+  });
+  return {
+    async ready() { await listening; return server.address().port; },
+    waitForCallback() { return callback; },
+    close() { try { server.close(); } catch { /* already closed */ } },
+  };
+}
+
+function resultPage(error, detail) {
+  const ok = !error;
+  const title = ok ? "Signed in" : "Sign-in failed";
+  const body = ok
+    ? "You're signed in to Token of Trust. You can close this tab and return to your terminal."
+    : `Sign-in didn't complete${detail ? `: ${escapeHtml(detail)}` : ""}. Close this tab and run <code>tot login</code> again.`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>${title} · Token of Trust</title>
+<style>body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+background:#044a38;color:#eafff9;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;padding:24px}
+.card{max-width:30rem;background:#06392c;border:1px solid #1d6b54;border-radius:12px;padding:28px;text-align:center}
+h1{font-size:1.2rem;margin:.2rem 0 .8rem}p{color:#bfe9df;line-height:1.5}code{background:#053f30;padding:1px 6px;border-radius:4px}</style>
+</head><body><div class="card"><h1>${title}</h1><p>${body}</p></div></body></html>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]
+  ));
+}
+
+/**
+ * Run the full loopback login and return a persistable credentials record.
+ * Injectable (`fetchImpl`, `open`, `log`) so it can be driven in a test or a
+ * headless environment. Reuses `clientId` when the caller cached one for this MCP.
+ * @returns {Promise<object>} credentials to hand to writeCredentials()
+ */
+export async function loginFlow({
+  mcpUrl,
+  clientId,
+  fetchImpl = fetch,
+  open = openBrowser,
+  log = () => {},
+  now = () => Date.now(),
+}) {
+  const meta = await discoverMetadata(mcpUrl, fetchImpl);
+  const listener = startLoopbackListener();
+  try {
+    const port = await listener.ready();
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
+    const { verifier, challenge } = generatePkce();
+    const state = randomState();
+    const authorizeUrl = buildAuthorizeUrl(meta.authorization_endpoint, {
+      clientId: resolvedClientId, redirectUri, challenge, state,
+    });
+
+    log("  opening your browser to sign in …");
+    const opened = open(authorizeUrl);
+    if (!opened) {
+      // No opener on this box (headless/SSH) — the loopback can never be hit
+      // from here, so waiting on it would hang forever. Let the caller (B3:
+      // login.mjs#loginAndCache) fall through to deviceLoginFlow() instead.
+      throw new NoOpenerError(authorizeUrl);
+    }
+
+    const { code, state: returnedState } = await listener.waitForCallback();
+    if (!code) throw new Error("no authorization code came back from the browser");
+    if (returnedState !== state) throw new Error("state mismatch on the OAuth callback — aborting");
+
+    const token = await exchangeCode(
+      meta.token_endpoint,
+      { code, verifier, clientId: resolvedClientId, redirectUri },
+      fetchImpl,
+    );
+    return credentialsFromToken({
+      mcpUrl,
+      clientId: resolvedClientId,
+      tokenEndpoint: meta.token_endpoint,
+      token,
+      now: now(),
+    });
+  } finally {
+    listener.close();
+  }
+}
+
+// ── B3: device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
+
+/**
+ * RFC 8628 §3.1 — request a device_code + user_code to display. Same request
+ * shape as any other token-endpoint-adjacent POST (form-urlencoded, JSON back).
+ * @returns {Promise<{device_code, user_code, verification_uri,
+ *   verification_uri_complete?, expires_in, interval}>}
+ */
+export async function deviceAuthorize(deviceAuthorizationEndpoint, { clientId, scope = SCOPE }, fetchImpl = fetch) {
+  const res = await fetchImpl(deviceAuthorizationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams({ client_id: clientId, scope }).toString(),
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  if (!res.ok) {
+    const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
+    throw new Error(`device authorization request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+  }
+  if (!body.device_code || !body.user_code) {
+    throw new Error("device authorization response is missing device_code/user_code");
+  }
+  return body;
+}
+
+/**
+ * One device-flow poll attempt (RFC 8628 §3.4/§3.5). Unlike tokenRequest(),
+ * `authorization_pending` and `slow_down` are NOT failures — they're the
+ * normal "keep waiting" responses — so this resolves `{ pending: true }`
+ * (with `slowDown` set) for those instead of throwing.
+ */
+async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId }, fetchImpl) {
+  const res = await fetchImpl(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: deviceCode,
+      client_id: clientId,
+    }).toString(),
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  if (res.ok) {
+    if (!body.access_token) throw new Error("token endpoint returned no access_token");
+    return { pending: false, token: body };
+  }
+  if (body.error === "authorization_pending") return { pending: true, slowDown: false };
+  if (body.error === "slow_down") return { pending: true, slowDown: true };
+  const reason = body.error === "access_denied" ? "was denied" : body.error === "expired_token" ? "code expired" : "failed";
+  const detail = body.error_description ? ` — ${body.error_description}` : "";
+  throw new Error(`sign-in ${reason}${detail}`);
+}
+
+/**
+ * Poll the token endpoint until the device code is approved (or denied/
+ * expires), honoring the server's `interval` and the `slow_down` backoff
+ * (RFC 8628 §3.5: +5s, keep polling — not a failure). Injectable `sleep`/
+ * `now` so it's testable with no real waiting.
+ * @returns {Promise<object>} the raw token response (→ credentialsFromToken)
+ */
+export async function pollDeviceToken(
+  tokenEndpoint,
+  { deviceCode, clientId, intervalSec, expiresInSec },
+  fetchImpl = fetch,
+  { sleep = delay, now = () => Date.now() } = {},
+) {
+  let intervalMs = Math.max(1, Number(intervalSec) || 5) * 1000;
+  const deadline = now() + Math.max(1, Number(expiresInSec) || 600) * 1000;
+  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);
+    if (!r.pending) return r.token;
+    if (r.slowDown) intervalMs += 5000;
+  }
+}
+
+/**
+ * Run the full device-code login (RFC 8628) and return a persistable
+ * credentials record — the headless/SSH-friendly sibling of loginFlow(),
+ * same credentials shape, same dynamically-registered client_id. 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 deviceLoginFlow({
+  mcpUrl,
+  clientId,
+  fetchImpl = fetch,
+  log = () => {},
+  sleep = delay,
+  now = () => Date.now(),
+}) {
+  const meta = await discoverMetadata(mcpUrl, fetchImpl);
+  if (!meta.device_authorization_endpoint) {
+    throw new Error("this MCP doesn't support device-code sign-in yet — try `tot login` (browser) from a machine with one");
+  }
+  const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
+  const auth = await deviceAuthorize(meta.device_authorization_endpoint, { clientId: resolvedClientId }, fetchImpl);
+
+  log(`  Go to: ${auth.verification_uri_complete || auth.verification_uri}`);
+  if (!auth.verification_uri_complete) log(`  Enter code: ${auth.user_code}`);
+  log("  Waiting for approval …");
+
+  const token = await pollDeviceToken(
+    meta.token_endpoint,
+    { deviceCode: auth.device_code, clientId: resolvedClientId, intervalSec: auth.interval, expiresInSec: auth.expires_in },
+    fetchImpl,
+    { sleep, now },
+  );
+  return credentialsFromToken({
+    mcpUrl,
+    clientId: resolvedClientId,
+    tokenEndpoint: meta.token_endpoint,
+    token,
+    now: now(),
+  });
+}

package/src/open.mjs

@@ -0,0 +1,63 @@
+/**
+ * Tiny cross-platform helpers for the "and then it just opens" moment:
+ *   - openBrowser(url) — hand the URL to the OS (macOS `open` / Linux `xdg-open`
+ *     / Windows `start`), detached, so `tot` doesn't babysit the browser.
+ *   - waitForServer(url) — poll until the dev server answers, so we open the tab
+ *     the instant the site is live (not before, not on a fixed sleep).
+ *
+ * Dependency-free (global fetch, node:child_process, Node 20+).
+ */
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+
+/**
+ * Open `url` in the user's default browser. Best-effort and non-blocking: the
+ * child is detached + unref'd so it never holds `tot` open, and any failure
+ * (headless box, no opener) returns false instead of throwing.
+ * @returns {boolean} whether we managed to launch an opener.
+ */
+export function openBrowser(url, platform = process.platform) {
+  let cmd, args, shell = false;
+  if (platform === "darwin") {
+    cmd = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    // `start` is a shell builtin; the empty first arg is the window title.
+    cmd = "start";
+    args = ["", url];
+    shell = true;
+  } else {
+    cmd = "xdg-open";
+    args = [url];
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true, shell });
+    child.on("error", () => {}); // swallow "opener not found" async errors
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve true once `url` responds to a GET (any HTTP status counts — a 404
+ * still means the server is up), or false if it hasn't within `timeoutMs`.
+ * @param {string} url
+ * @param {{ timeoutMs?: number, intervalMs?: number, until?: () => boolean }} [opts]
+ *   until - optional early-stop predicate (e.g. "the dev process already died").
+ */
+export async function waitForServer(url, { timeoutMs = 60000, intervalMs = 400, until } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (until && until()) return false;
+    try {
+      const res = await fetch(url, { method: "GET", signal: AbortSignal.timeout(2500) });
+      if (res) return true;
+    } catch {
+      // not up yet — keep polling
+    }
+    await delay(intervalMs);
+  }
+  return false;
+}

package/src/token-store.mjs

@@ -0,0 +1,65 @@
+/**
+ * The developer credential cache for `tot` — where `tot login` writes the MCP
+ * OAuth token and every developer-session command reads it back.
+ *
+ * ONE file, `~/.tot/credentials.json` (0600 in a 0700 dir), holding exactly what
+ * a later command needs to authenticate AND to silently refresh:
+ *
+ *   { mcpUrl, clientId, tokenEndpoint, scope,
+ *     accessToken, refreshToken, expiresAt (epoch ms), obtainedAt }
+ *
+ * We persist `clientId` + `tokenEndpoint` so a refresh needs no re-discovery /
+ * re-registration, and `mcpUrl` so we never present a token minted for one MCP
+ * to a different one. Dependency-free (node:fs/os/path).
+ *
+ * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+/** Absolute path to the credential file for this environment. */
+export function defaultCredentialsPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "credentials.json");
+}
+
+/**
+ * Read + parse the cached credentials, or null if absent/unreadable/malformed.
+ * Never throws — a missing or corrupt cache simply means "not signed in".
+ */
+export function readCredentials(filePath) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write credentials atomically with owner-only permissions: the containing
+ * `~/.tot` is created 0700, the file lands 0600 via a temp-file rename so a
+ * reader never sees a half-written token, and we chmod after rename to force
+ * 0600 even when the file already existed.
+ */
+export function writeCredentials(filePath, creds) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, filePath);
+  chmodSync(filePath, 0o600);
+}
+
+/**
+ * Is the access token expired (or within `skewMs` of it)? A cache with no
+ * `expiresAt` is treated as NOT expired — we can't know, so we present it and
+ * let the server reject it rather than force an unnecessary re-login.
+ * @param {{expiresAt?: number|null}} creds
+ */
+export function isExpired(creds, { now = Date.now(), skewMs = 60_000 } = {}) {
+  if (!creds || !creds.expiresAt) return false;
+  return now >= creds.expiresAt - skewMs;
+}