@tokenoftrust/cli 2.5.1 → 2.5.2

package/README.md

@@ -48,13 +48,36 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 `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.
 
-- 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 clone`, `tot start`, `tot preview`, `tot ship`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- 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 privately under `~/.tot/` for that MCP authority and refreshed silently. Every later command (`tot clone`, `tot start`, `tot preview`, `tot ship`, …) 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 clone` **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.
 
+### QA and production on one machine
+
+Sign in to each authority once:
+
+```sh
+tot login --mcp https://mcp.qa.tokenoftrust.com
+tot login --mcp https://mcp.tokenoftrust.com
+```
+
+Both sessions remain available. Commands select `--mcp` first, the checkout's local
+`tot.mcp-url` binding next, then `MCP_BASE_URL` / `TOT_MCP_URL`, then production.
+Cloning records the authenticated authority in local git configuration. In an existing
+store or kit checkout, a successful `tot login --mcp <url>` records its authority.
+The binding contains no token and is never committed; the shared forge hostname does
+not identify an environment.
+
+`tot whoami --mcp <url>` inspects one session. `tot logout --mcp <url>` clears only
+that authority in the active profile. Git operations and the local activity bridge
+use the checkout's authority, so a production login leaves QA work signed in.
+Cached tokens are never attached to a different MCP authority. Existing valid
+credentials are converted once into an authority-specific file with owner-only
+permissions. No separate home directory is needed.
+
 ### Optional: multiple identities at once (`TOT_PROFILE`)
 
-**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):
+**Most people never set this** — the default identity profile holds your sessions for each authority, and `tot login` replaces only the selected authority's session. 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                     # terminal B
@@ -69,7 +92,7 @@ export TOT_PROFILE=$(uuidgen)    # a fresh isolated identity per terminal / test
 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.
+A clean short profile name is included in the credential filename; other labels are hashed. Every profile holds independent sessions per MCP authority. `tot whoami` shows the active profile and authority.
 
 ## Design notes
 

package/bin/tot.mjs

@@ -16,6 +16,7 @@
  */
 import "../src/ensure-node.mjs"; // hard Node-version gate — must stay first (see the module doc)
 import { readFileSync } from "node:fs";
+import { selectedAuthority } from "../src/token-store.mjs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
@@ -362,6 +363,13 @@ function safeSubcommand(cmd, rest) {
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const ctx = detectContext();
+  const mcpIndex = rest.indexOf("--mcp");
+  const mcpUrl = mcpIndex < 0 ? undefined : rest[mcpIndex + 1];
+  if (mcpIndex >= 0 && (!mcpUrl || mcpUrl.startsWith("--"))) throw new Error("--mcp requires an HTTPS URL.");
+  // One invocation context drives auth, telemetry and every runner child.
+  delete process.env.TOT_SELECTED_MCP_URL;
+  process.env.TOT_SELECTED_MCP_URL = selectedAuthority(process.env, { mcpUrl, cwd: ctx.cwd });
+  process.env.MCP_BASE_URL = process.env.TOT_SELECTED_MCP_URL;
   const startedAt = Date.now();
   const command = cmd || "(none)";
   resetInvocationDiagnostics({ command, cliVersion: VERSION });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "Token of Trust developer CLI — clone 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/activity.mjs

@@ -32,7 +32,7 @@
  * Dependency-free (node: builtins + global fetch, Node ≥22).
  */
 import { createHash } from "node:crypto";
-import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+import { readSessionCredentials } from "./token-store.mjs";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Envelope (mirror of event.ts)
@@ -235,14 +235,14 @@ export function isActivityDisabled(env = process.env) {
  * configured (→ emitActivity is a no-op). Mirrors the resolution the obstacle
  * beacon (obstacle.mjs) and the heartbeat (dev-heartbeat.mjs) use: the env override
  * `TOT_DEV_ACTIVITY_URL`/`TOT_DEV_ACTIVITY_TOKEN` (threaded to runner-spawning
- * paths) wins, else the `activityUrl`/`activityToken` cached in ~/.tot/credentials.json.
+ * paths) wins, else the `activityUrl`/`activityToken` cached in the selected authority/profile cache.
  */
 export function resolveActivityBridge(env = process.env) {
   const url = env.TOT_DEV_ACTIVITY_URL;
   const token = env.TOT_DEV_ACTIVITY_TOKEN;
   if (url && token) return { url, token };
   try {
-    const creds = readCredentials(defaultCredentialsPath(env));
+    const creds = readSessionCredentials(env);
     if (creds?.activityUrl && creds?.activityToken) {
       return { url: creds.activityUrl, token: creds.activityToken };
     }
@@ -264,7 +264,7 @@ export function resolveActor(env = process.env) {
   const kind = env.TOT_ACTOR_KIND === "agent" ? "agent" : "dev";
   let seed = "anonymous";
   try {
-    const creds = readCredentials(defaultCredentialsPath(env));
+    const creds = readSessionCredentials(env);
     if (creds?.emailHint) seed = `hint:${creds.emailHint}`;
     else if (creds?.activityToken) seed = `tok:${creds.activityToken}`;
   } catch {
@@ -282,7 +282,7 @@ export function resolveActor(env = process.env) {
 function resolveScope(env = process.env, extra = {}) {
   const scope = /** @type {any} */ ({ ...extra });
   try {
-    const creds = readCredentials(defaultCredentialsPath(env));
+    const creds = readSessionCredentials(env);
     if (creds?.traceId && !scope.traceId) scope.traceId = creds.traceId;
   } catch {
     /* best-effort */

package/src/auth.mjs

@@ -5,7 +5,7 @@
  * 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);
+ * PKCE loopback and caches the token (the selected authority/profile cache 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)`.
@@ -20,7 +20,7 @@
  * read or transmit the secret.
  */
 import {
-  defaultCredentialsPath, readCredentials, writeCredentials, isExpired,
+  defaultCredentialsPath, readCredentials, writeCredentials, isExpired, normalizeAuthority, selectedAuthority,
 } from "./token-store.mjs";
 import { refreshAccessToken, credentialsFromToken } from "./oauth.mjs";
 
@@ -140,19 +140,31 @@ export function warnLegacyOperatorEnv(env = process.env, warn = (m) => console.e
  */
 export async function resolveDeveloperSession(client, env, deps = {}) {
   const { fetchImpl = fetch, now = Date.now() } = deps;
-  const path = defaultCredentialsPath(env);
+  const authority = selectedAuthority(env, { mcpUrl: client?.mcpUrl });
+  const path = defaultCredentialsPath(env, authority);
   let creds = readCredentials(path);
 
-  if (!creds || !creds.accessToken) {
+  if (!creds || typeof creds.accessToken !== "string" || !creds.accessToken) {
     throw new AuthUnavailableError(
       "you're not signed in to Token of Trust.",
       {
         reason: "missing",
-        hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run.",
+        hint: `run \`tot login --mcp ${authority}\` to sign in, then re-run.`,
       },
     );
   }
 
+  let matches = false;
+  try {
+    matches = normalizeAuthority(creds.mcpUrl) === authority &&
+      (!creds.tokenEndpoint || normalizeAuthority(creds.tokenEndpoint) === authority);
+  } catch { /* malformed cache is unauthenticated */ }
+  if (!matches) {
+    throw new AuthUnavailableError("your cached session does not match this MCP authority.", {
+      reason: "authorityMismatch", hint: `run \`tot login --mcp ${authority}\`, then re-run.`,
+    });
+  }
+
   if (isExpired(creds, { now })) {
     if (!creds.refreshToken || !creds.tokenEndpoint) {
       throw new AuthUnavailableError(
@@ -169,7 +181,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
       );
     } catch (e) {
       throw new AuthUnavailableError(
-        `couldn't refresh your Token of Trust session: ${e?.message || e}`,
+        "couldn't refresh your Token of Trust session.",
         { reason: "refreshFailed", hint: developerCredentialRecoveryHint(creds) },
       );
     }

package/src/commands/clone.mjs

@@ -64,6 +64,7 @@
  *
  * Dependency-free (global fetch + `git` via child_process).
  */
+import { recordRepositoryAuthority } from "../token-store.mjs";
 import { execFile, execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -472,7 +473,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   if (!cloneDir) {
     return { gitRemote, cloneUrl, publicUrl, cloned: false, dir: null, head: null };
   }
-  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, cloneDeps);
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, { ...cloneDeps, mcpUrl: client.mcpUrl });
   return { gitRemote, cloneUrl, publicUrl, cloned: true, dir, head };
 }
 
@@ -502,6 +503,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
  * @param {(s: string) => string} redact
  * @param {{
  *   store?: boolean,
+ *   mcpUrl?: string,
  *   git?: (cargs: string[]) => Promise<string>,
  *   gitSync?: (cargs: string[]) => string,
  *   installHelper?: (git: (cargs: string[]) => string, opts: { host?: string }) => boolean,
@@ -510,6 +512,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
  */
 async function cloneRepo(gitRemote, dir, redact, {
   store = true,
+  mcpUrl = undefined,
   git = async (/** @type {string[]} */ cargs) => (await execFileP("git", cargs)).stdout.toString(),
   gitSync = (/** @type {string[]} */ cargs) => execFileSync("git", ["-C", dir, ...cargs], { encoding: "utf8" }),
   installHelper = installForgeCredentialHelper,
@@ -551,6 +554,7 @@ async function cloneRepo(gitRemote, dir, redact, {
       command: "clone", operation: "credential_helper_install", required: false, degraded: true,
     });
   }
+  if (mcpUrl) recordRepositoryAuthority(gitSync, mcpUrl);
   if (record) {
     // Not best-effort: without the record, the credential helper cannot tell what this
     // checkout is, so every later fetch would fail with nothing to say why.
@@ -660,6 +664,7 @@ export async function clonePublicationSpaces(client, { tenant, dir, topology, re
       const scrub = (/** @type {string} */ s) => (cred ? redact(s).split(cred.token).join("***") : redact(s));
       const { head } = await cloneRepo(gitRemote, target, scrub, {
         ...deps,
+        mcpUrl: client.mcpUrl,
         store: false,
         record: (gitSync) => recordPublicationSpaceCheckout(gitSync, { tenant, spaceId: space.id, repo: space.source.repo }),
       });
@@ -752,7 +757,7 @@ function serverReason(error) {
  * (a server that dropped the `alias` key would otherwise hand back the caller's own store).
  * The server reports no expiry — it reaps the reader token after ~24h — so the helper's TTL
  * and erase→re-mint are what bound a cached copy.
- * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
+ * @param {{ callTool: (name: string, args: unknown) => Promise<any>, mcpUrl?: string }} client
  * @param {{ target: string, repo: string }} alias
  * @param {(s: string) => string} [redact]
  * @returns {Promise<{ gitRemote: string, publicUrl: string }>}
@@ -797,7 +802,7 @@ export async function mintReadOnlyAlias(client, alias, redact = (s) => s) {
  * `tot clone agency-kit [dir]`: mint the read-only credential, clone token-free through a
  * one-shot `http.extraheader`, install the host-scoped credential helper, and record the
  * checkout as a read-only kit clone so the helper re-mints it the same way.
- * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
+ * @param {{ callTool: (name: string, args: unknown) => Promise<any>, mcpUrl?: string }} client
  * @param {{ alias: { target: string, repo: string }, cloneDir?: string|null, redact?: (s:string)=>string }} opts
  * @param {Parameters<typeof cloneRepo>[3]} [deps]
  */
@@ -806,6 +811,7 @@ export async function cloneReadOnlyAlias(client, { alias, cloneDir = null, redac
   if (!cloneDir) return { gitRemote, publicUrl, cloned: false, dir: null, head: null };
   const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, {
     ...deps,
+    mcpUrl: client.mcpUrl,
     store: false,
     record: (gitSync) => recordReadOnlyKitCheckout(gitSync, alias.target),
   });

package/src/commands/dev.mjs

@@ -38,7 +38,7 @@ import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient, CLI_VERSION, setRunnerVersion, versionStamp } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
-import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { readSessionCredentials } from "../token-store.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
@@ -241,7 +241,7 @@ async function runNativePublic(workspace, args, ctx) {
  * @returns {{TOT_DEV_ACTIVITY_TOKEN?: string, TOT_DEV_ACTIVITY_URL?: string}}
  */
 export function activityBridgeEnv(env = process.env) {
-  const creds = readCredentials(defaultCredentialsPath(env));
+  const creds = readSessionCredentials(env);
   if (!creds?.activityToken || !creds?.activityUrl) return {};
   return { TOT_DEV_ACTIVITY_TOKEN: creds.activityToken, TOT_DEV_ACTIVITY_URL: creds.activityUrl };
 }
@@ -347,7 +347,7 @@ async function runNative(workspace, args, ctx) {
 /**
  * The env bootNative threads into the spawned runner. NEVER thread a real
  * developer's activity-bridge credential into the zero-login --sample run:
- * activityBridgeEnv() reads ~/.tot/credentials.json unconditionally, so a
+ * activityBridgeEnv() reads the selected authority/profile cache unconditionally, so a
  * developer who's ever run `tot login --code` and then runs `tot dev --sample`
  * (the "free taste"/demo path) would otherwise leak their real credential,
  * posting fake sample-store activity to their real hosted /dev panel —

package/src/commands/doctor.mjs

@@ -30,7 +30,7 @@ import {
   nativeWindowsDetail,
   shouldAttemptDoctorAutoLogin,
 } from "../platform.mjs";
-import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
+import { readSessionCredentials, isExpired } from "../token-store.mjs";
 import { dockerAvailable, tryStartDocker, RENDERER_CACHE_ROOT, rendererArtifactComplete } from "./dev.mjs";
 import { loginAndCache } from "./login.mjs";
 
@@ -140,7 +140,7 @@ export function collectChecks(_ctx, env = process.env) {
     blocking: false,
   });
 
-  const devCreds = readCredentials(defaultCredentialsPath(env));
+  const devCreds = readSessionCredentials(env);
   const devUsable = !!devCreds?.accessToken && (!isExpired(devCreds) || !!devCreds.refreshToken);
   checks.push({
     name: "auth identity",

package/src/commands/feedback.mjs

@@ -24,7 +24,7 @@ import { createInterface } from "node:readline/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
-import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { readSessionCredentials } from "../token-store.mjs";
 import { fail } from "../errors.mjs";
 import { formatDiagnostics, readDiagnostics, recordDiagnostic } from "../diagnostics.mjs";
 
@@ -154,7 +154,7 @@ export async function run(argv) {
   // session. Read it BEFORE establishSession — a silent token refresh rewrites the
   // credential file, so read the cached value first. Absent for a bare (non-invite)
   // login; omitted from the payload then.
-  const traceId = readCredentials(defaultCredentialsPath(env))?.traceId || null;
+  const traceId = readSessionCredentials(env)?.traceId || null;
 
   // Preview — sending publishes to Token of Trust, so show exactly what goes out.
   console.error("\nAbout to send to Token of Trust:");

package/src/commands/git-credential.mjs

@@ -50,7 +50,8 @@
 import { readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
-import { establishSession } from "../auth.mjs";
+import { selectedAuthority, readSessionCredentials } from "../token-store.mjs";
+import { AuthUnavailableError, establishSession } from "../auth.mjs";
 import { checkoutTenant, mintPublicationSpace, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
 import { scopeToTenant } from "../tenant-scope.mjs";
 import { detectContext } from "../context.mjs";
@@ -127,6 +128,13 @@ export async function mintOrCacheCredential({
   createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
   mintReadOnly = mintReadOnlyAlias, mintSpace = mintPublicationSpace,
 } = {}) {
+  let authority;
+  try { authority = selectedAuthority(env, { cwd }); }
+  catch { console.error("tot: this checkout has an invalid MCP authority. Run tot login --mcp <url> in this checkout."); return null; }
+  env = { ...env, TOT_SELECTED_MCP_URL: authority, MCP_BASE_URL: authority };
+  const authFailure = (e) => {
+    if (e instanceof AuthUnavailableError) console.error(`tot: ${e.message} ${e.hint || `Run tot login --mcp ${authority}.`}`);
+  };
   const recorded = recordedCheckout(cwd);
   if (recorded?.kind === "invalid") return null; // a half-recorded space mints nothing, never the store's
   if (recorded?.kind === PUBLICATION_SPACE_KIND) {
@@ -135,7 +143,8 @@ export async function mintOrCacheCredential({
     const client = createClient(baseUrl);
     try {
       await establish(client, { env });
-    } catch {
+    } catch (e) {
+      authFailure(e);
       return null;
     }
     try {
@@ -147,6 +156,7 @@ export async function mintOrCacheCredential({
       const cred = splitAuthedRemote(res.gitRemote || "");
       return cred ? { username: cred.username, password: cred.token } : null;
     } catch (e) {
+      authFailure(e);
       if (e instanceof CliError) console.error(formatError(e));
       return null;
     }
@@ -158,7 +168,7 @@ export async function mintOrCacheCredential({
     if (!alias) return null; // a recorded target this CLI does not know — never guess a mint
     const cachePath = kitCredentialCachePath(alias.target, env);
     const cached = readCachedCredential(cachePath);
-    if (cached) return { username: cached.username, password: cached.password };
+    if (cached && readSessionCredentials(env)?.accessToken) return { username: cached.username, password: cached.password };
     const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
     const client = createClient(baseUrl);
     try {
@@ -174,6 +184,7 @@ export async function mintOrCacheCredential({
       // report it on stderr so `git fetch` doesn't dead-end the developer in silence. A
       // bare network/auth failure (not signed in, MCP unreachable) has no decision to
       // report and stays silent, same as every other "nothing this helper can do" path.
+      authFailure(e);
       if (e instanceof CliError) console.error(formatError(e));
       return null;
     }
@@ -227,7 +238,8 @@ export async function mintOrCacheCredential({
   const client = createClient(baseUrl);
   try {
     await establish(client, { env });
-  } catch {
+  } catch (e) {
+    authFailure(e);
     return null; // not signed in (or session unrefreshable) — nothing this helper can do
   }
   try {
@@ -295,7 +307,8 @@ export function forgetCredential({ env = process.env, cwd = process.cwd(), expec
     const kit = kitCheckout(cwd);
     if (!kit) return;
     if (expectedHost && !hostMatches(kit.originUrl, expectedHost)) return;
-    dropCachedCredential(kitCredentialCachePath(kit.target, env));
+    const authority = selectedAuthority(env, { cwd });
+    dropCachedCredential(kitCredentialCachePath(kit.target, { ...env, TOT_SELECTED_MCP_URL: authority }));
   } catch {
     /* erase is advisory — never fail git over it */
   }

package/src/commands/grants.mjs

@@ -23,7 +23,7 @@
  * binds this identity — the same ordering that fixes the "no stores" dead-end).
  * Dependency-free.
  */
-import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { readSessionCredentials } from "../token-store.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { storeListError, noStoresGuidance } from "./clone.mjs";
@@ -190,7 +190,7 @@ export async function run(argv, _ctx) {
 
   // 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 creds = readSessionCredentials(env);
   const mcpUrl = creds?.mcpUrl || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(mcpUrl);
 

package/src/commands/login.mjs

@@ -4,7 +4,7 @@
  * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
  * opens the browser to the MCP's authorize page, the developer signs in with their
  * ToT identity + approves, and the loopback catches the code and exchanges it for a
- * token cached at ~/.tot/credentials.json. Every later command (`tot clone`,
+ * token cached at the selected authority/profile cache. Every later command (`tot clone`,
  * `tot submit`, …) then runs as that developer with NO re-auth.
  *
  * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
@@ -20,7 +20,9 @@
  * Dependency-free (node built-ins via oauth.mjs).
  */
 import { loginFlow, deviceLoginFlow, rendezvousLoginFlow, NoOpenerError } from "../oauth.mjs";
-import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
+import { defaultCredentialsPath, readCredentials, writeCredentials, normalizeAuthority, selectedAuthority, recordRepositoryAuthority } from "../token-store.mjs";
+import { execFileSync } from "node:child_process";
+import { detectContext } from "../context.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
 import { cockpitRecoveryUrl, normalizeEmailHint, redactEmailForHint, emailFromJwt } from "../auth.mjs";
@@ -28,8 +30,6 @@ import { loginFailureNext } from "../platform.mjs";
 import { isInteractive, promptYesNo } from "../prompt.mjs";
 import { versionStamp } from "../mcp.mjs";
 
-const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
-
 function parseArgs(argv) {
   const a = {
     mcp: null, device: false, code: null, help: false,
@@ -122,9 +122,12 @@ After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot subm
  * @returns {Promise<object>} the credentials written to disk.
  */
 export async function loginAndCache(mcpUrl, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}), device = false } = {}) {
-  const path = defaultCredentialsPath(env);
-  const prior = readCredentials(path);
-  const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
+  mcpUrl = normalizeAuthority(mcpUrl);
+  const path = defaultCredentialsPath(env, mcpUrl);
+  let prior = readCredentials(path);
+  try { if (normalizeAuthority(prior?.mcpUrl) !== mcpUrl) prior = null; }
+  catch { prior = null; }
+  const clientId = prior?.clientId;
 
   let creds;
   if (device) {
@@ -198,7 +201,8 @@ export async function offerSignIn(mcpUrl, env = process.env, {
  * @returns {Promise<object>} the credentials written to disk.
  */
 export async function redeemAndCache(mcpUrl, code, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}) } = {}) {
-  const path = defaultCredentialsPath(env);
+  mcpUrl = normalizeAuthority(mcpUrl);
+  const path = defaultCredentialsPath(env, mcpUrl);
   const prior = readCredentials(path);
   const creds = await rendezvousLoginFlow({ mcpUrl, code, log });
   const merged = mergeActivityBridge(prior, mcpUrl, creds);
@@ -225,7 +229,8 @@ export async function redeemAndCache(mcpUrl, code, env = process.env, { log = /*
  * `TOT_PROFILE` (separate credential files — no carry to guard at all).
  */
 export function mergeActivityBridge(prior, mcpUrl, creds) {
-  if (prior?.mcpUrl !== mcpUrl) return creds;
+  try { if (normalizeAuthority(prior?.mcpUrl) !== normalizeAuthority(mcpUrl)) return creds; }
+  catch { 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
@@ -260,16 +265,26 @@ export async function run(argv, _ctx) {
   // a "why did sign-in behave oddly" investigation needs (e.g. a stale shadowing `tot`).
   console.error(versionStamp());
 
-  const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const mcpUrl = selectedAuthority(env, { mcpUrl: args.mcp });
+  const loginEnv = { ...env, TOT_SELECTED_MCP_URL: mcpUrl };
+  const bindCheckout = () => {
+    if (!args.mcp) return;
+    const git = (cargs) => execFileSync("git", cargs, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    let kind = "";
+    try { kind = git(["config", "--local", "--get", "tot.checkoutKind"]).trim(); } catch { /* root store or loose directory */ }
+    if (detectContext().mode !== "checkout" && !["read-only-kit", "publication-space"].includes(kind)) return;
+    recordRepositoryAuthority(git, mcpUrl);
+  };
 
   if (args.code) {
     console.error(`~ signing in to Token of Trust with your invite code (${mcpUrl})`);
     try {
-      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);
-      console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
+      await redeemAndCache(mcpUrl, args.code, loginEnv, { log: (m) => console.error(m) });
+      cacheActivityBridge(loginEnv, args.activityToken, args.activityUrl);
+      cacheTraceId(loginEnv, args.traceId);
+      cacheEmailHint(loginEnv, args.emailHint);
+      bindCheckout();
+    console.log("\n+ signed in. Session cached privately for this MCP authority.");
       console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
       return 0;
     } catch (e) {
@@ -285,9 +300,10 @@ export async function run(argv, _ctx) {
 
   console.error(`~ signing in to Token of Trust (${mcpUrl})`);
   try {
-    await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
-    cacheTraceId(env, args.traceId);
-    console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
+    await loginAndCache(mcpUrl, loginEnv, { log: (m) => console.error(m), device: args.device });
+    cacheTraceId(loginEnv, args.traceId);
+    bindCheckout();
+    console.log("\n+ signed in. Session cached privately for this MCP authority.");
     console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
     return 0;
   } catch (e) {

package/src/commands/logout.mjs

@@ -1,7 +1,7 @@
 /**
  * `tot logout` — sign this machine out of Token of Trust.
  *
- * Deletes the cached session (`~/.tot/credentials.json`) so the next command starts
+ * Deletes only the selected authority/profile session so the next command starts
  * clean — the counterpart to `tot login` / `tot login --code`. Idempotent: logging
  * out when already signed out is success, not an error.
  *
@@ -10,11 +10,11 @@
  *
  * Dependency-free (node built-ins via token-store.mjs).
  */
-import { defaultCredentialsPath, readCredentials, clearCredentials } from "../token-store.mjs";
+import { defaultCredentialsPath, readCredentials, clearCredentials, selectedAuthority } from "../token-store.mjs";
 
 const USAGE = `tot logout — sign this machine out of Token of Trust
 
-  tot logout    delete the cached session (~/.tot/credentials.json)
+  tot logout [--mcp <url>]    clear only the selected authority/profile session
 
 Idempotent — safe to run when already signed out. Clears only this machine's cache;
 it does not revoke server-side. Run \`tot whoami\` to confirm you're signed out.`;
@@ -25,12 +25,14 @@ export async function run(argv) {
     console.log(USAGE);
     return 0;
   }
-  const path = defaultCredentialsPath(process.env);
+  const index = argv.indexOf("--mcp");
+  const authority = selectedAuthority(process.env, { mcpUrl: index < 0 ? undefined : argv[index + 1] });
+  const path = defaultCredentialsPath(process.env, authority);
   // Report against the prior state so "signed out" vs "already clean" is honest.
   const wasSignedIn = !!readCredentials(path);
   const removed = clearCredentials(path);
   if (wasSignedIn || removed) {
-    console.log(`+ signed out. Cleared ${path}.`);
+    console.log(`+ signed out of ${authority}.`);
     console.log("  Run `tot login` (or `tot login --code <token>`) to sign in again.");
   } else {
     console.log("+ already signed out — no cached session to clear.");

package/src/commands/start.mjs

@@ -57,7 +57,7 @@ import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
-import { readCredentials, defaultCredentialsPath } from "../token-store.mjs";
+import { readSessionCredentials } from "../token-store.mjs";
 import { collectChecks } from "./doctor.mjs";
 import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./clone.mjs";
 import {
@@ -173,7 +173,7 @@ export function decideStartMode({ sampleFlag, hasSession }) {
  */
 export function cachedMcpUrl(env) {
   try {
-    const creds = readCredentials(defaultCredentialsPath(env));
+    const creds = readSessionCredentials(env);
     return creds && typeof creds.mcpUrl === "string" && creds.mcpUrl ? creds.mcpUrl : null;
   } catch {
     return null;

package/src/commands/whoami.mjs

@@ -1,14 +1,14 @@
 /**
  * `tot whoami` — who is `tot` signed in as, and what can they touch.
  *
- * Reads the cached session (~/.tot/credentials.json). If a live token is present
+ * Reads the cached session (the selected authority/profile cache). If a live token is present
  * it best-effort asks the MCP for the stores this developer may act on (proving the
  * token still works), degrading cleanly to the cached status if the MCP is
  * unreachable or the developer isn't entitled yet.
  *
  * Dependency-free.
  */
-import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
+import { readSessionCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
@@ -32,7 +32,7 @@ export function sessionStatus(creds, { now = Date.now() } = {}) {
 /** @param {string[]} argv @param {any} _ctx */
 export async function run(argv, _ctx) {
   const env = process.env;
-  const creds = readCredentials(defaultCredentialsPath(env));
+  const creds = readSessionCredentials(env);
   const status = sessionStatus(creds);
 
   const profile = activeProfile(env);

package/src/git-credential.mjs

@@ -21,7 +21,7 @@ import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 import { mkdirSync, writeFileSync, chmodSync, rmSync } from "node:fs";
-import { readCredentials, writeCredentials } from "./token-store.mjs";
+import { readCredentials, writeCredentials, selectedAuthority, profileSlug, readSessionCredentials } from "./token-store.mjs";
 
 /** The git config value that routes credential requests through `tot` — the
  *  `!` tells git to run this as a shell command (git appends the operation,
@@ -129,10 +129,13 @@ export function kitCredentialCacheKey(target) {
   return `kit-${createHash("sha256").update(`kit|${target}`).digest("hex").slice(0, 32)}`;
 }
 
-/** Absolute path to a read-only kit checkout's cached credential. */
+/** Kit credentials are isolated by authority, profile and the current OAuth grant. */
 export function kitCredentialCachePath(target, env = process.env) {
   const home = env.TOT_HOME || homedir();
-  return join(home, ".tot", "git-credentials", `${kitCredentialCacheKey(target)}.json`);
+  const grant = readSessionCredentials(env)?.accessToken || "";
+  const scope = createHash("sha256")
+    .update(JSON.stringify([selectedAuthority(env), profileSlug(env), grant])).digest("hex");
+  return join(home, ".tot", "git-credentials", `${kitCredentialCacheKey(target)}-${scope}.json`);
 }
 
 /** Is a cached credential still trusted? A cache with no `mintedAt` is

package/src/oauth.mjs

@@ -22,6 +22,7 @@
  * 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 { normalizeAuthority } from "./token-store.mjs";
 import http from "node:http";
 import crypto from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
@@ -45,6 +46,7 @@ async function oauthJson(url, init, operation, fetchImpl) {
   try {
     res = await fetchImpl(url, {
       ...init,
+      redirect: "error",
       headers: { ...(init?.headers || {}), "X-Trace-Id": traceId },
     });
   } catch (cause) {
@@ -143,7 +145,7 @@ export function randomState() {
 
 /** Fetch the Authorization Server metadata (RFC 8414). */
 export async function discoverMetadata(mcpUrl, fetchImpl = fetch) {
-  const root = String(mcpUrl).replace(/\/+$/, "");
+  const root = normalizeAuthority(mcpUrl);
   const url = `${root}/.well-known/oauth-authorization-server`;
   const { res, body: meta, context } = await oauthJson(
     url, { headers: { Accept: "application/json" } }, "oauth_metadata", fetchImpl,
@@ -247,7 +249,7 @@ export function refreshAccessToken(tokenEndpoint, { refreshToken, clientId }, fe
 export function credentialsFromToken({ mcpUrl, clientId, tokenEndpoint, scope = SCOPE, token, now = Date.now() }) {
   const expiresIn = Number(token.expires_in) || 0;
   return {
-    mcpUrl,
+    mcpUrl: normalizeAuthority(mcpUrl),
     clientId,
     tokenEndpoint,
     scope: token.scope || scope,

package/src/obstacle.mjs

@@ -2,7 +2,7 @@
  * ESM front door to the obstacle beacon (src/obstacle-beacon.cjs). The post-login
  * failure paths — `pnpm-missing`, `install-failed`, `clone-failed` — run on a
  * supported Node where the bridge credential is already cached, so they resolve
- * {url, token} from ~/.tot/credentials.json (the same source activityBridgeEnv +
+ * {url, token} from the selected authority/profile cache (the same source activityBridgeEnv +
  * the heartbeat use) rather than argv. `node-too-old` does NOT come through here:
  * it fires from the ES5 launcher pre-login, where creds may not exist yet.
  *
@@ -13,7 +13,7 @@
  */
 import beaconCore from "./obstacle-beacon.cjs";
 import { CLI_VERSION } from "./mcp.mjs";
-import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+import { readSessionCredentials } from "./token-store.mjs";
 
 /**
  * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
@@ -24,7 +24,7 @@ import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
  */
 export async function emitObstacle(kind, { have, need, env = process.env } = {}) {
   try {
-    const creds = readCredentials(defaultCredentialsPath(env));
+    const creds = readSessionCredentials(env);
     const url = creds?.activityUrl;
     const token = creds?.activityToken;
     if (!url || !token) return;

package/src/token-store.mjs

@@ -1,54 +1,14 @@
 /**
- * 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,
- *     activityToken, activityUrl, traceId, emailHint }
- *
- * 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. `activityToken`/`activityUrl` are a SEPARATE credential
- * (storefront-issued, not MCP OAuth) that `tot login --code` caches when the
- * invite paste carries it — see commands/login.mjs `cacheActivityBridge` and
- * commands/dev.mjs `activityBridgeEnv`, which every runner-spawning path (native
- * monorepo, native standalone, Docker) threads in so the local dev-loop process
- * can report file saves to the developer's hosted /dev panel. `traceId` is the
- * storefront-minted invite→terminal→problem trace id (cached by `tot login`'s
- * `--trace-id` flag, see commands/login.mjs `cacheTraceId`); `tot feedback`
- * stamps it onto a problem report so triage can join it to the invite + the live
- * heartbeat session. `emailHint` is masked, display-only recovery context from
- * the setup command, used to orient cockpit/login after a local credential
- * expires without persisting a raw address.
- *
- * The read/write is a plain JSON pass-through (no schema) — new fields like
- * `traceId` ride along additively; readers simply pick the keys they need.
- * Dependency-free (node:fs/os/path).
- *
- * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
- *
- * 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.
+ * OAuth sessions are private files keyed by MCP authority and identity profile.
+ * Endpoint paths share an authority; QA and production retain separate sessions.
+ * TOT_HOME selects a private home and TOT_PROFILE selects an independent identity.
  */
 import {
-  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, rmSync,
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, rmSync, linkSync, unlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 
 /** A short token safe to drop straight into a filename (readable profiles). */
@@ -78,24 +38,134 @@ export function profileSlug(env = process.env) {
   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) {
+export const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+export const MCP_AUTHORITY_KEY = "tot.mcp-url";
+
+/** Identity boundary shared by every MCP endpoint on one origin. */
+export function normalizeAuthority(value) {
+  try {
+    const url = new URL(value);
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && local))) throw new Error();
+    return url.origin;
+  } catch {
+    throw new Error("invalid MCP authority — use an HTTPS URL without credentials, query or fragment.");
+  }
+}
+
+/** Local checkout provenance, never inferred from a shared forge hostname. */
+export function repositoryAuthority(cwd = process.cwd()) {
+  let value;
+  try {
+    value = execFileSync("git", ["-C", cwd, "config", "--local", "--get", MCP_AUTHORITY_KEY], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch { return null; }
+  return value ? normalizeAuthority(value) : null;
+}
+
+/**
+ * Explicit request > checkout provenance > shell configuration > production.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{mcpUrl?: string|null, cwd?: string}} opts
+ */
+export function selectedAuthority(env = process.env, { mcpUrl, cwd = process.cwd() } = {}) {
+  return normalizeAuthority(mcpUrl || env.TOT_SELECTED_MCP_URL || repositoryAuthority(cwd) || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL);
+}
+
+/** Record the authority used to authenticate this checkout. No credentials land in git. */
+export function recordRepositoryAuthority(git, mcpUrl) {
+  git(["config", "--local", MCP_AUTHORITY_KEY, normalizeAuthority(mcpUrl)]);
+}
+
+function credentialsPath(env, authority) {
+  const home = env.TOT_HOME || homedir();
+  const profile = profileSlug(env);
+  const key = createHash("sha256").update(normalizeAuthority(authority)).digest("hex");
+  return join(home, ".tot", `credentials${profile ? `.${profile}` : ""}.${key}.json`);
+}
+
+/** Cache failures expose fixed diagnostics, never raw filesystem text or causes. */
+class CredentialCacheError extends Error {
+  constructor(conflict = false) {
+    super(conflict
+      ? "credential cache authority conflict — refusing to replace or clear another authority's session."
+      : "could not access the local credential cache — check permissions and retry.");
+    this.code = conflict ? "credential_cache_authority_conflict" : "credential_cache_unavailable";
+  }
+}
+
+/** Convert one valid unscoped session once, without overwriting another session. */
+function convertCredentials(env) {
   const home = env.TOT_HOME || homedir();
-  const slug = profileSlug(env);
-  return join(home, ".tot", slug ? `credentials.${slug}.json` : "credentials.json");
+  const profile = profileSlug(env);
+  const oldPath = join(home, ".tot", profile ? `credentials.${profile}.json` : "credentials.json");
+  const prior = readCredentials(oldPath);
+  if (typeof prior?.accessToken !== "string" || !prior.accessToken || typeof prior.mcpUrl !== "string") return;
+  const target = credentialsPath(env, prior.mcpUrl);
+  try {
+    // link is atomic and refuses an existing destination. Unlink completes the move.
+    linkSync(oldPath, target);
+  } catch (error) {
+    // A current session for this same authority/profile supersedes the unscoped copy.
+    // Retire that duplicate so logout cannot restore it on the next cache read.
+    if (error?.code === "ENOENT") return; // another reader already retired the source
+    if (error?.code !== "EEXIST") throw error;
+    const current = readCredentials(target);
+    let currentAuthority = null;
+    try { currentAuthority = normalizeAuthority(current?.mcpUrl); } catch { /* corrupt destination */ }
+    if (!currentAuthority || typeof current?.accessToken !== "string" || !current.accessToken) {
+      writeCredentials(target, prior);
+    } else if (currentAuthority !== normalizeAuthority(prior.mcpUrl)) {
+      throw new CredentialCacheError(true);
+    }
+  }
+  chmodSync(dirname(target), 0o700);
+  chmodSync(target, 0o600);
+  // Another first reader may have retired this source after our EEXIST result.
+  try { unlinkSync(oldPath); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+}
+
+/**
+ * Absolute path to the selected authority/profile session.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string|undefined} mcpUrl
+ */
+export function defaultCredentialsPath(env = process.env, mcpUrl = undefined) {
+  try { convertCredentials(env); }
+  catch (error) { throw error instanceof CredentialCacheError ? error : new CredentialCacheError(); }
+  return credentialsPath(env, selectedAuthority(env, { mcpUrl }));
 }
 
 /**
- * Read + parse the cached credentials, or null if absent/unreadable/malformed.
- * Never throws — a missing or corrupt cache simply means "not signed in".
+ * Read a session only when its issuer matches the selected destination.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string|undefined} mcpUrl
+ */
+export function readSessionCredentials(env = process.env, mcpUrl = undefined) {
+  const authority = selectedAuthority(env, { mcpUrl });
+  const creds = readCredentials(defaultCredentialsPath(env, authority));
+  try { return creds && normalizeAuthority(creds.mcpUrl) === authority ? creds : null; }
+  catch { return null; }
+}
+
+/**
+ * Read + parse credentials, or null if absent/malformed. Operational read errors
+ * refuse so an unreadable session cannot be mistaken for a missing session.
  */
 export function readCredentials(filePath) {
-  try {
-    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
-    return parsed && typeof parsed === "object" ? parsed : null;
-  } catch {
-    return null;
+  let text;
+  try { text = readFileSync(filePath, "utf8"); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new CredentialCacheError();
   }
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch { return null; }
 }
 
 /**
@@ -106,10 +176,15 @@ export function readCredentials(filePath) {
  */
 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);
+  chmodSync(dirname(filePath), 0o700);
+  const tmp = `${filePath}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(tmp, filePath);
+    chmodSync(filePath, 0o600);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
 }
 
 /**
@@ -126,7 +201,7 @@ export function isExpired(creds, { now = Date.now(), skewMs = 60_000 } = {}) {
 /**
  * Delete the cached session (the whole "signed in" state), idempotently. Returns
  * true if a credential file was actually removed, false if there was nothing to
- * remove. Never throws — "already signed out" is success. Local-only: this clears
+ * remove. An unreadable/locked cache refuses rather than claiming sign-out. Local-only: this clears
  * the machine's cache; it does NOT revoke the grant server-side.
  */
 export function clearCredentials(filePath) {
@@ -134,7 +209,7 @@ export function clearCredentials(filePath) {
   try {
     rmSync(filePath, { force: true });
   } catch {
-    /* best-effort: a missing/locked file still means "not signed in here" */
+    throw new Error("could not clear the selected session cache — check its permissions, then retry.");
   }
   return existed;
 }