@mathismeadows/roamer-device-auth 1.4.2 → 1.5.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mathismeadows/roamer-device-auth",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "private": false,
   "mcpName": "com.mathismeadows/roamer-mcp",
   "type": "module",
-  "description": "AUTH-14/AUTH-25/AUTH-38: stdio<->HTTP MCP proxy for Roamer MCP with two auth mechanisms, chosen per-machine by default-browser detection. Safari-default machines use a server-mediated device authorization flow (AUTH-25) since Safari's HTTPS-Only Mode blocks a loopback redirect; every other machine uses a standard direct loopback redirect instead. Both authenticate against RoamerMcp's own OAuth authorization server (AUTH-38).",
+  "description": "AUTH-14/AUTH-25/AUTH-38: stdio<->HTTP MCP proxy for Roamer MCP with two auth mechanisms, chosen per-machine by default-browser detection. Safari-default machines use a server-mediated device authorization flow (AUTH-25) since Safari's HTTPS-Only Mode blocks a loopback redirect; every other machine uses a standard direct loopback redirect instead. Both authenticate against RoamerMcp's own OAuth authorization server (AUTH-38). AUTH-54/55/57/58: sessions are cached per (client, identity) pair, with explicit login/logout/status subcommands to switch or inspect which identity a client is using.",
   "bin": {
     "roamer-device-auth": "./roamer-device-auth.mjs"
   },

package/roamer-device-auth.mjs

@@ -43,7 +43,7 @@ import {
   exchangeAuthorization,
   refreshAuthorization,
 } from "@modelcontextprotocol/sdk/client/auth.js";
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, unlink } from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -66,9 +66,141 @@ const CACHE_DIR = join(homedir(), ".mcp-auth-device");
 // interactive sign-in on every single invocation instead of falling into any shared
 // catch-all bucket, which would just recreate the bug this item fixes for a smaller
 // population of clients.
-function cacheFilePath(baseName, clientSlug) {
+//
+// AUTH-54: an optional third segment, identityKey, namespaces the token caches further by
+// WHICH PERSON authenticated, not just which app is connecting — AUTH-51 alone still let a
+// second identity on the same client silently reuse or shadow the first one's cache, since
+// identity wasn't part of the key at all. Only the actual token caches take an identityKey
+// (see call sites below); roamer_loopback_client (DCR registration) and roamer_pending
+// (in-progress device-code flow) are deliberately left clientSlug-only — a registered OAuth
+// client and an in-flight sign-in aren't tied to any one person yet, and folding an identity
+// segment into them would just be dead complexity. `__` is reserved as this function's own
+// delimiter: identityKeyFromTokens below never emits one, so splitting on it is unambiguous.
+function cacheFilePath(baseName, clientSlug, identityKey = null) {
   if (!clientSlug) return null;
-  return join(CACHE_DIR, `${baseName}__${clientSlug}.json`);
+  const suffix = identityKey ? `__${identityKey}` : "";
+  return join(CACHE_DIR, `${baseName}__${clientSlug}${suffix}.json`);
+}
+
+// AUTH-54: derives a stable, filesystem-safe identity key from an access token's own claims.
+// Prefers oid deliberately (over identityLabelFromTokens' email-first choice below) — oid is
+// durable and never changes for a given person, where email/preferred_username can (a verified
+// contact email update, a UPN change). Keying the cache FILE by something that can change would
+// silently orphan an existing cache entry and grow a spurious "new identity" next to it, which
+// is exactly the confusion this item exists to prevent. No signature verification here — this
+// is purely a local cache-partitioning key, not a trust decision; the server has already
+// validated the token by the time this process holds it.
+function identityKeyFromTokens(tokens) {
+  const raw = decodeTokenPayload(tokens)?.oid ?? identityLabelFromTokens(tokens);
+  if (!raw) return null;
+  return String(raw)
+    .trim()
+    .toLowerCase()
+    // Deliberately excludes "_" (unlike clientSlugFromInitializeLine's slug sanitizer) so "__"
+    // stays a delimiter cacheFilePath can split on unambiguously.
+    .replace(/[^a-z0-9.@-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || null;
+}
+
+// AUTH-54/56: the human-readable form (email/preferred_username first, falling back to the raw
+// oid) used for the "status" listing and the AUTH-56 stderr line — deliberately independent of
+// identityKeyFromTokens' own oid-first priority above: a key optimizes for stability, a label
+// optimizes for being recognizable to the person reading it.
+function identityLabelFromTokens(tokens) {
+  const payload = decodeTokenPayload(tokens);
+  return payload?.email ?? payload?.preferred_username ?? payload?.oid ?? null;
+}
+
+function decodeTokenPayload(tokens) {
+  try {
+    return JSON.parse(Buffer.from(tokens.access_token.split(".")[1], "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// AUTH-54: which identity a client slug's NORMAL (non-login/logout/status) runs should use.
+// This is the piece that makes identity-aware caching invisible to the common single-identity
+// case — the first-ever sign-in for a client writes both the token cache AND this pointer, so
+// every later ordinary run finds it automatically with no config change. It only changes when
+// an explicit `login` establishes a new one, or `logout` clears it back to "none" (AUTH-57).
+async function readActiveIdentity(clientSlug) {
+  const path = cacheFilePath("roamer_active", clientSlug);
+  if (!path) return null;
+  try {
+    const active = JSON.parse(await readFile(path, "utf8"));
+    return active?.identityKey ? active : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeActiveIdentity(clientSlug, { identityKey, label }) {
+  const path = cacheFilePath("roamer_active", clientSlug);
+  if (!path) return;
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify({ identityKey, label }, null, 2), { mode: 0o600 });
+}
+
+function clearActiveIdentity(clientSlug) {
+  const path = cacheFilePath("roamer_active", clientSlug);
+  if (!path) return Promise.resolve();
+  return unlink(path).catch(() => {});
+}
+
+// AUTH-58: lists every identity currently cached for a client slug, across both auth
+// mechanisms (a machine's default browser — and therefore which mechanism is in play — can
+// change over time; a person could have identities cached under either). Reads each file's own
+// stamped label rather than keeping a separate index, so this can never drift from what's
+// actually on disk — the same self-describing-file approach CACHE_VERSION already uses.
+async function listCachedIdentities(clientSlug) {
+  const active = await readActiveIdentity(clientSlug);
+  const prefixes = [`roamer_tokens__${clientSlug}__`, `roamer_loopback_tokens__${clientSlug}__`];
+  const seen = new Map(); // identityKey -> label, deduped across the two mechanisms
+  let entries;
+  try {
+    entries = await readdir(CACHE_DIR);
+  } catch {
+    entries = [];
+  }
+  for (const entry of entries) {
+    const prefix = prefixes.find((p) => entry.startsWith(p));
+    if (!prefix || !entry.endsWith(".json")) continue;
+    const identityKey = entry.slice(prefix.length, -".json".length);
+    if (!identityKey || seen.has(identityKey)) continue;
+    try {
+      const contents = JSON.parse(await readFile(join(CACHE_DIR, entry), "utf8"));
+      seen.set(identityKey, contents?.label ?? identityKey);
+    } catch {
+      seen.set(identityKey, identityKey);
+    }
+  }
+  return [...seen.entries()].map(([identityKey, label]) => ({
+    identityKey,
+    label,
+    active: identityKey === active?.identityKey,
+  }));
+}
+
+// AUTH-55/57/58: login/logout/status run standalone, with no MCP `initialize` handshake to
+// derive a client slug from the way normal bridge operation does — so unlike every other
+// function in this file, they need to discover what slugs even exist on disk, to guide someone
+// who omitted --client (or got it wrong) rather than just failing opaquely.
+async function listKnownClientSlugs() {
+  let entries;
+  try {
+    entries = await readdir(CACHE_DIR);
+  } catch {
+    return [];
+  }
+  const slugs = new Set();
+  for (const entry of entries) {
+    // Safe to split on "__" without ambiguity: neither a client slug (clientSlugFromInitializeLine)
+    // nor an identity key (identityKeyFromTokens) can contain an underscore post-sanitization.
+    const match = entry.match(/^roamer_(?:tokens|loopback_tokens)__([^_]+)__/);
+    if (match) slugs.add(match[1]);
+  }
+  return [...slugs].sort();
 }
 
 // Bumped whenever the cached shape changes meaningfully. A cache written by a prior
@@ -96,6 +228,13 @@ function isAuthError(err) {
 // missing/blank name just means "no usable identity", never a thrown error — a
 // non-compliant host must degrade gracefully (an uncached, always-fresh sign-in), not crash
 // the bridge.
+//
+// AUTH-54: "_" was dropped from the allowed character set (it previously joined "-" as
+// filename-safe) so a client slug can never itself contain "__" — that sequence is now
+// cacheFilePath's own reserved delimiter between the client-slug and identity-key segments of
+// a filename, and listKnownClientSlugs/listCachedIdentities parse filenames back apart on
+// exactly that assumption. No real MCP client name has ever produced an underscore here in
+// practice; this only changes behavior for a hypothetical clientInfo.name containing one.
 function clientSlugFromInitializeLine(line) {
   try {
     const message = JSON.parse(line);
@@ -104,7 +243,7 @@ function clientSlugFromInitializeLine(line) {
     const slug = name
       .trim()
       .toLowerCase()
-      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/[^a-z0-9-]+/g, "-")
       .replace(/^-+|-+$/g, "");
     return slug || null;
   } catch {
@@ -132,9 +271,14 @@ async function showDeviceCodeDialog(verificationUri, userCode) {
 // mid-session refreshes of an already-visible, already-established session (see forwardLine
 // below) — only for the initial per-process acquisition, so a long-lived connection doesn't
 // spam a notification every time its token happens to roll over.
-async function notifySessionReused(clientSlug) {
-  const label = clientSlug ?? "an unidentified client";
-  const message = `Reused an existing Roamer MCP session for ${label}.`;
+// AUTH-54: now includes the identity label alongside the client slug — AUTH-51's original
+// notification could only ever say "which app", not "reused as whom", which is exactly the
+// distinction someone needs in order to notice a stale identity is still active.
+async function notifySessionReused(clientSlug, identityLabel) {
+  const clientLabel = clientSlug ?? "an unidentified client";
+  const message = identityLabel
+    ? `Reused an existing Roamer MCP session for ${clientLabel} (${identityLabel}).`
+    : `Reused an existing Roamer MCP session for ${clientLabel}.`;
   try {
     await execFileAsync("osascript", [
       "-e",
@@ -146,8 +290,12 @@ async function notifySessionReused(clientSlug) {
   log(message);
 }
 
-async function readCachedTokens(clientSlug) {
-  const path = cacheFilePath("roamer_tokens", clientSlug);
+// AUTH-54: identityKey defaults to null (the pre-AUTH-54 file shape) rather than being
+// required, so existing callers/tests that only ever knew about clientSlug keep working
+// unchanged — production call sites in doGetValidTokens below always pass a real one once an
+// identity is known.
+async function readCachedTokens(clientSlug, identityKey = null) {
+  const path = cacheFilePath("roamer_tokens", clientSlug, identityKey);
   if (!path) return null;
   try {
     const tokens = JSON.parse(await readFile(path, "utf8"));
@@ -160,16 +308,19 @@ async function readCachedTokens(clientSlug) {
   }
 }
 
-async function writeCachedTokens(clientSlug, tokens) {
-  const path = cacheFilePath("roamer_tokens", clientSlug);
+// AUTH-54: stamps `label` alongside the pre-existing `cacheVersion` so listCachedIdentities
+// (AUTH-58) can read a human-readable identity straight off the file, without re-decoding the
+// access token or keeping a separate index that could drift from what's actually on disk.
+async function writeCachedTokens(clientSlug, tokens, identityKey = null) {
+  const path = cacheFilePath("roamer_tokens", clientSlug, identityKey);
   if (!path) return; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
-  const stamped = { ...tokens, cacheVersion: CACHE_VERSION };
+  const stamped = { ...tokens, cacheVersion: CACHE_VERSION, label: identityLabelFromTokens(tokens) };
   await writeFile(path, JSON.stringify(stamped, null, 2), { mode: 0o600 });
 }
 
-function clearCachedTokens(clientSlug) {
-  const path = cacheFilePath("roamer_tokens", clientSlug);
+function clearCachedTokens(clientSlug, identityKey = null) {
+  const path = cacheFilePath("roamer_tokens", clientSlug, identityKey);
   if (!path) return Promise.resolve();
   return writeFile(path, "{}", { mode: 0o600 }).catch(() => {});
 }
@@ -181,8 +332,10 @@ function clearCachedTokens(clientSlug) {
 // discovery documents from Cloudflare Access Managed OAuth to RoamerMcp's own AS, and a client_id
 // or token cached from before that change would otherwise be silently carried forward and
 // presented to a completely different issuer with no invalidation at all.
-async function readLoopbackTokens(clientSlug, issuerUrl) {
-  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+// AUTH-54: identityKey defaults to null for the same backward-compatibility reason as
+// readCachedTokens above.
+async function readLoopbackTokens(clientSlug, issuerUrl, identityKey = null) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug, identityKey);
   if (!path) return null;
   try {
     const tokens = JSON.parse(await readFile(path, "utf8"));
@@ -193,16 +346,16 @@ async function readLoopbackTokens(clientSlug, issuerUrl) {
   }
 }
 
-async function writeLoopbackTokens(clientSlug, tokens, issuerUrl) {
-  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+async function writeLoopbackTokens(clientSlug, tokens, issuerUrl, identityKey = null) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug, identityKey);
   if (!path) return; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
-  const stamped = { ...tokens, issuerUrl };
+  const stamped = { ...tokens, issuerUrl, label: identityLabelFromTokens(tokens) };
   await writeFile(path, JSON.stringify(stamped, null, 2), { mode: 0o600 });
 }
 
-function clearLoopbackTokens(clientSlug) {
-  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+function clearLoopbackTokens(clientSlug, identityKey = null) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug, identityKey);
   if (!path) return Promise.resolve();
   return writeFile(path, "{}", { mode: 0o600 }).catch(() => {});
 }
@@ -360,38 +513,65 @@ async function pollDeviceFlow(deviceCode, intervalSeconds) {
 // more than one client's flow in flight within a single process anyway.
 let inFlightTokens = null;
 
-function getValidTokens(clientSlug, forceRefresh = false) {
+function getValidTokens(clientSlug, forceRefresh = false, forceFreshLogin = false) {
   if (inFlightTokens) return inFlightTokens;
-  inFlightTokens = doGetValidTokens(clientSlug, forceRefresh).finally(() => {
+  inFlightTokens = doGetValidTokens(clientSlug, forceRefresh, forceFreshLogin).finally(() => {
     inFlightTokens = null;
   });
   return inFlightTokens;
 }
 
-// AUTH-51: returns { tokens, reusedSilently } — reusedSilently is true only when no
-// interactive step ran this call (a valid cache hit or a silent refresh-token refresh),
-// which is exactly the case that used to be invisible and is now what triggers
-// notifySessionReused in main().
-async function doGetValidTokens(clientSlug, forceRefresh) {
-  let tokens = forceRefresh ? null : await readCachedTokens(clientSlug);
-
-  if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
-    return { tokens, reusedSilently: true };
+// AUTH-51/54: returns { tokens, reusedSilently, identityKey, label } — reusedSilently is true
+// only when no interactive step ran this call (a valid cache hit or a silent refresh-token
+// refresh), which is exactly the case that used to be invisible and is now what triggers
+// notifySessionReused in main(). identityKey/label are the person this run is/became — resolved
+// from the active-identity pointer (AUTH-54) for a normal run, or freshly derived once a
+// brand-new interactive sign-in completes.
+//
+// AUTH-55: forceFreshLogin (distinct from the pre-existing forceRefresh) is the `login`
+// command's own entry point — unlike forceRefresh, which still operates against whichever
+// identity is CURRENTLY active (the existing AUTH-51/reactive-401-invalidation behavior,
+// unchanged), forceFreshLogin skips resolving the active identity at all, always runs a fresh
+// interactive sign-in, and then makes WHOEVER signs in the new active identity — without
+// deleting any other identity's own cache entry.
+async function doGetValidTokens(clientSlug, forceRefresh, forceFreshLogin = false) {
+  const active = forceFreshLogin ? null : await readActiveIdentity(clientSlug);
+  const identityKey = active?.identityKey ?? null;
+
+  // BUG (found live, same session, immediately post-1.5.0-publish): identityKey being null
+  // here is ambiguous between "no active identity has ever been established" (must never read
+  // any file — force a fresh sign-in) and "explicitly asked for the identity-less cache" (only
+  // ever true from a 2-arg test call). cacheFilePath maps a null identityKey to the exact same
+  // filename AUTH-54 shipped alongside — the pre-AUTH-54 file every already-authenticated
+  // client already had on disk. Without this guard, a machine upgrading straight from a
+  // pre-AUTH-54 version silently keeps reusing that old file forever (a real "reused existing
+  // creds" notification a user hit immediately after this shipped) and never establishes an
+  // active-identity pointer at all — reproducing the exact silent-stale-identity bug AUTH-54
+  // exists to fix, and permanently hiding that identity from login/logout/status, which only
+  // ever look at the new (client, identity)-keyed files. noActiveIdentity forces the same
+  // fresh-sign-in path a genuinely first-ever run takes, which is what self-heals into a real
+  // active pointer + a new-format file — see the fresh-sign-in branch below.
+  const noActiveIdentity = !forceFreshLogin && !active;
+
+  let tokens = forceRefresh || forceFreshLogin || noActiveIdentity ? null : await readCachedTokens(clientSlug, identityKey);
+
+  if (!forceRefresh && !forceFreshLogin && tokens?.access_token && !expiresSoon(tokens)) {
+    return { tokens, reusedSilently: true, identityKey, label: active?.label };
   }
 
-  if (!forceRefresh && tokens?.refresh_token) {
+  if (!forceRefresh && !forceFreshLogin && tokens?.refresh_token) {
     try {
       log("Refreshing cached token...");
       const fresh = await refreshTokens(tokens.refresh_token);
       tokens = { ...fresh, obtained_at: Date.now() };
-      await writeCachedTokens(clientSlug, tokens);
-      return { tokens, reusedSilently: true };
+      await writeCachedTokens(clientSlug, tokens, identityKey);
+      return { tokens, reusedSilently: true, identityKey, label: identityLabelFromTokens(tokens) };
     } catch (err) {
       log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
     }
   }
 
-  if (forceRefresh) await clearCachedTokens(clientSlug);
+  if (forceRefresh && identityKey) await clearCachedTokens(clientSlug, identityKey);
 
   // Resume an already-in-progress flow (from a process this host killed and respawned)
   // instead of minting a new device_code the user would have to start over for.
@@ -430,10 +610,16 @@ async function doGetValidTokens(clientSlug, forceRefresh) {
   try {
     const fresh = await pollDeviceFlow(device.device_code, device.interval ?? 5);
     tokens = { ...fresh, obtained_at: Date.now() };
-    await writeCachedTokens(clientSlug, tokens);
+    const freshIdentityKey = identityKeyFromTokens(tokens);
+    const freshLabel = identityLabelFromTokens(tokens);
+    await writeCachedTokens(clientSlug, tokens, freshIdentityKey);
+    // AUTH-54/55: every fresh sign-in (not just an explicit `login`) re-establishes the active
+    // pointer — a routine cold start after a cache miss self-heals into a correctly-recorded
+    // active identity exactly like it always implicitly did before this item, just now explicit.
+    if (freshIdentityKey) await writeActiveIdentity(clientSlug, { identityKey: freshIdentityKey, label: freshLabel });
     await clearPendingFlow(clientSlug);
     log("Sign-in complete.");
-    return { tokens, reusedSilently: false };
+    return { tokens, reusedSilently: false, identityKey: freshIdentityKey, label: freshLabel };
   } catch (err) {
     // A hard failure (expired/denied, not just this process being killed) means the pending
     // code is genuinely dead — clear it so the next attempt starts a real fresh one instead
@@ -509,44 +695,55 @@ async function discoverLoopbackServerInfo() {
 // of the two mechanisms is ever active in a given process (see detectDefaultBrowser).
 let inFlightLoopbackTokens = null;
 
-function getValidTokensLoopback(clientSlug, forceRefresh = false) {
+function getValidTokensLoopback(clientSlug, forceRefresh = false, forceFreshLogin = false) {
   if (inFlightLoopbackTokens) return inFlightLoopbackTokens;
-  inFlightLoopbackTokens = doGetValidTokensLoopback(clientSlug, forceRefresh).finally(() => {
+  inFlightLoopbackTokens = doGetValidTokensLoopback(clientSlug, forceRefresh, forceFreshLogin).finally(() => {
     inFlightLoopbackTokens = null;
   });
   return inFlightLoopbackTokens;
 }
 
-// AUTH-51: returns { tokens, reusedSilently } — see doGetValidTokens's comment above, same
-// contract for the loopback mechanism.
-async function doGetValidTokensLoopback(clientSlug, forceRefresh) {
+// AUTH-51/54/55: returns { tokens, reusedSilently, identityKey, label } — see
+// doGetValidTokens's comment above, same contract and same forceFreshLogin semantics, for the
+// loopback mechanism.
+async function doGetValidTokensLoopback(clientSlug, forceRefresh, forceFreshLogin = false) {
   // AUTH-38: discovery has to run before any cached token/client is trusted, not after — a
   // cached-but-not-yet-expired token from a prior authorization server would otherwise be
   // returned early below without ever learning the issuer changed underneath it.
   const serverInfo = await discoverLoopbackServerInfo();
   const issuerUrl = serverInfo.authorizationServerUrl.toString();
 
-  let tokens = forceRefresh ? null : await readLoopbackTokens(clientSlug, issuerUrl);
+  const active = forceFreshLogin ? null : await readActiveIdentity(clientSlug);
+  const identityKey = active?.identityKey ?? null;
+  // See doGetValidTokens's identical guard above for why this is required, not optional: a
+  // null identityKey here would otherwise silently resolve to the exact pre-AUTH-54 filename.
+  const noActiveIdentity = !forceFreshLogin && !active;
+
+  let tokens =
+    forceRefresh || forceFreshLogin || noActiveIdentity ? null : await readLoopbackTokens(clientSlug, issuerUrl, identityKey);
 
-  if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
-    return { tokens, reusedSilently: true };
+  if (!forceRefresh && !forceFreshLogin && tokens?.access_token && !expiresSoon(tokens)) {
+    return { tokens, reusedSilently: true, identityKey, label: active?.label };
   }
 
+  // AUTH-54: DCR client registration stays clientSlug-only, deliberately not identity-scoped —
+  // it identifies this app instance to the authorization server, not the person using it, so
+  // every identity signing in from the same client-slug reuses the same registered client_id.
   let clientInformation = await readLoopbackClientInfo(clientSlug, issuerUrl);
 
-  if (!forceRefresh && tokens?.refresh_token && clientInformation) {
+  if (!forceRefresh && !forceFreshLogin && tokens?.refresh_token && clientInformation) {
     try {
       log("Refreshing cached token...");
       const fresh = await refreshLoopbackTokens(tokens.refresh_token, serverInfo, clientInformation);
       tokens = { ...fresh, obtained_at: Date.now() };
-      await writeLoopbackTokens(clientSlug, tokens, issuerUrl);
-      return { tokens, reusedSilently: true };
+      await writeLoopbackTokens(clientSlug, tokens, issuerUrl, identityKey);
+      return { tokens, reusedSilently: true, identityKey, label: identityLabelFromTokens(tokens) };
     } catch (err) {
       log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
     }
   }
 
-  if (forceRefresh) await clearLoopbackTokens(clientSlug);
+  if (forceRefresh && identityKey) await clearLoopbackTokens(clientSlug, identityKey);
 
   if (!clientInformation) {
     log("Registering as a new OAuth client...");
@@ -616,9 +813,14 @@ async function doGetValidTokensLoopback(clientSlug, forceRefresh) {
     redirectUri: LOOPBACK_REDIRECT_URI,
   });
   tokens = { ...fresh, obtained_at: Date.now() };
-  await writeLoopbackTokens(clientSlug, tokens, issuerUrl);
+  const freshIdentityKey = identityKeyFromTokens(tokens);
+  const freshLabel = identityLabelFromTokens(tokens);
+  await writeLoopbackTokens(clientSlug, tokens, issuerUrl, freshIdentityKey);
+  // AUTH-54/55: see doGetValidTokens's identical step for the device-code path — a routine
+  // cold start self-heals the active pointer the same way an explicit login does.
+  if (freshIdentityKey) await writeActiveIdentity(clientSlug, { identityKey: freshIdentityKey, label: freshLabel });
   log("Sign-in complete.");
-  return { tokens, reusedSilently: false };
+  return { tokens, reusedSilently: false, identityKey: freshIdentityKey, label: freshLabel };
 }
 
 // AUTH-28: extracted so it can run both for live traffic (post-sign-in) and for messages
@@ -746,14 +948,24 @@ async function main() {
   // redirect, including refreshes and reactive re-auth below.
   const isSafari = (await detectDefaultBrowser()) === "com.apple.safari";
   getFreshTokens = isSafari ? getValidTokens : getValidTokensLoopback;
-  clearFreshTokens = () => (isSafari ? clearCachedTokens(clientSlug) : clearLoopbackTokens(clientSlug));
+  // AUTH-54: resolves whichever identity is currently active before clearing — clearing the
+  // pre-AUTH-54, identity-less file path would silently no-op now that real caches live under
+  // an identity-scoped filename.
+  clearFreshTokens = async () => {
+    const active = await readActiveIdentity(clientSlug);
+    return isSafari
+      ? clearCachedTokens(clientSlug, active?.identityKey)
+      : clearLoopbackTokens(clientSlug, active?.identityKey);
+  };
   freshTokensForForward = (force) => getFreshTokens(clientSlug, force).then((result) => result.tokens);
 
   let reusedSilently = false;
+  let identityLabel = null;
   try {
     const result = await getFreshTokens(clientSlug);
     tokens = result.tokens;
     reusedSilently = result.reusedSilently;
+    identityLabel = result.label;
   } catch (err) {
     // Sign-in genuinely failed (denied/expired), not just slow — every message queued while
     // we waited, starting with `initialize`, gets a real JSON-RPC error so the host sees an
@@ -763,9 +975,15 @@ async function main() {
     process.exit(1);
   }
 
+  // AUTH-56: unconditional, on every run (cache-hit or fresh sign-in alike) — unlike the
+  // reused-only notification below, this is the persistent record that a running session used
+  // this identity, findable later in the MCP host's own log panel rather than only at the
+  // instant a transient OS notification fired.
+  log(identityLabel ? `Authenticated as ${identityLabel} for client "${clientSlug}".` : `Authenticated for client "${clientSlug}" (no identity claim found on the token).`);
+
   // AUTH-51: the moment that used to be completely silent — a process starting up and
   // immediately using a credential it never interactively obtained this run.
-  if (reusedSilently) await notifySessionReused(clientSlug);
+  if (reusedSilently) await notifySessionReused(clientSlug, identityLabel);
 
   transport = new StreamableHTTPClientTransport(new URL(ROAMER_MCP_URL), {
     requestInit: {
@@ -798,6 +1016,125 @@ async function main() {
   }
 }
 
+// AUTH-55/57/58: login/logout/status share this — none of them get a client slug from an MCP
+// `initialize` handshake the way normal bridge operation does (they run standalone), so all
+// three require it spelled out explicitly rather than guessing.
+function parseClientFlag(args) {
+  const idx = args.indexOf("--client");
+  if (idx === -1 || !args[idx + 1]) return null;
+  return args[idx + 1];
+}
+
+async function requireClientFlag(args, commandName) {
+  const clientSlug = parseClientFlag(args);
+  if (clientSlug) return clientSlug;
+  const known = await listKnownClientSlugs();
+  const suggestion = known.length
+    ? `Known client slugs with a cached identity: ${known.join(", ")}.`
+    : "No client has ever cached an identity on this machine yet.";
+  log(`${commandName} requires --client <slug>. ${suggestion}`);
+  process.exitCode = 1;
+  return null;
+}
+
+function deleteCacheFile(path) {
+  if (!path) return Promise.resolve();
+  return unlink(path).catch(() => {});
+}
+
+// AUTH-55: the deliberate, one-shot counterpart to normal bridge startup's silent reuse —
+// always runs a fresh interactive sign-in (forceFreshLogin, see doGetValidTokens/
+// doGetValidTokensLoopback) via whichever mechanism (device-code vs. loopback) this machine
+// would actually use at real connect time, then makes whoever signs in the new active identity
+// for --client, without touching any other identity already cached for it.
+async function loginCommand(args) {
+  const clientSlug = await requireClientFlag(args, "login");
+  if (!clientSlug) return;
+
+  const isSafari = (await detectDefaultBrowser()) === "com.apple.safari";
+  const getFreshTokens = isSafari ? getValidTokens : getValidTokensLoopback;
+  try {
+    const result = await getFreshTokens(clientSlug, false, /* forceFreshLogin */ true);
+    log(`Signed in as ${result.label ?? "(no identity claim found on the token)"} — now the active identity for "${clientSlug}".`);
+  } catch (err) {
+    log(`Login failed: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// AUTH-57: default scope is the active identity only — clearing it (and the active-identity
+// pointer itself) is enough to make the client's next normal launch fall back to a fresh
+// interactive sign-in, per AUTH-57's own Given/When/Then; --all additionally clears every
+// other identity ever cached for this client slug, for a full offboard/cleanup.
+async function logoutCommand(args) {
+  const clientSlug = await requireClientFlag(args, "logout");
+  if (!clientSlug) return;
+
+  if (args.includes("--all")) {
+    const identities = await listCachedIdentities(clientSlug);
+    if (identities.length === 0) {
+      log(`Nothing cached for "${clientSlug}".`);
+      return;
+    }
+    for (const { identityKey, label } of identities) {
+      await Promise.all([
+        deleteCacheFile(cacheFilePath("roamer_tokens", clientSlug, identityKey)),
+        deleteCacheFile(cacheFilePath("roamer_loopback_tokens", clientSlug, identityKey)),
+      ]);
+      log(`Cleared cached identity ${label} for "${clientSlug}".`);
+    }
+    await clearActiveIdentity(clientSlug);
+    return;
+  }
+
+  const active = await readActiveIdentity(clientSlug);
+  if (!active) {
+    log(`"${clientSlug}" has no active identity to log out of.`);
+    return;
+  }
+  await Promise.all([
+    deleteCacheFile(cacheFilePath("roamer_tokens", clientSlug, active.identityKey)),
+    deleteCacheFile(cacheFilePath("roamer_loopback_tokens", clientSlug, active.identityKey)),
+  ]);
+  await clearActiveIdentity(clientSlug);
+  log(`Logged out ${active.label} for "${clientSlug}". Its next launch will sign in fresh, exactly like a first-ever run.`);
+}
+
+// AUTH-58: --client lists that one slug's cached identities; omitting it surveys every client
+// slug that has cached anything at all, one summary line each.
+async function statusCommand(args) {
+  const clientSlug = parseClientFlag(args);
+  if (clientSlug) {
+    const identities = await listCachedIdentities(clientSlug);
+    if (identities.length === 0) {
+      log(`No identities cached for "${clientSlug}".`);
+      return;
+    }
+    for (const { label, active } of identities) {
+      log(`${active ? "*" : " "} ${label}${active ? " (active)" : ""} — client "${clientSlug}"`);
+    }
+    return;
+  }
+
+  const slugs = await listKnownClientSlugs();
+  if (slugs.length === 0) {
+    log("No identities cached for any client on this machine.");
+    return;
+  }
+  for (const slug of slugs) {
+    const identities = await listCachedIdentities(slug);
+    const activeLabel = identities.find((i) => i.active)?.label ?? "none";
+    log(`${slug}: ${identities.length} identit${identities.length === 1 ? "y" : "ies"} cached, active = ${activeLabel}`);
+  }
+}
+
+function runCli(promise) {
+  promise.catch((err) => {
+    log(`Fatal error: ${err.stack ?? err.message}`);
+    process.exit(1);
+  });
+}
+
 // Only auto-run when invoked directly (npx/CLI) — importing this module from a test file
 // must not trigger a live device-auth flow and stdio takeover as a side effect.
 // AUTH-29: npx always launches this via the node_modules/.bin symlink, so argv[1] must be
@@ -805,10 +1142,15 @@ async function main() {
 const isMainModule =
   process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
 if (isMainModule) {
-  main().catch((err) => {
-    log(`Fatal error: ${err.stack ?? err.message}`);
-    process.exit(1);
-  });
+  // AUTH-55/57/58: a subcommand routes to login/logout/status(/whoami); anything else —
+  // including today's only invocation shape, zero args — falls through to the normal MCP
+  // stdio bridge unchanged. This is the one and only new branch point; every existing caller
+  // (roamer-bridge.sh, every plugin/client config) passes no args and is unaffected.
+  const [subcommand, ...rest] = process.argv.slice(2);
+  if (subcommand === "login") runCli(loginCommand(rest));
+  else if (subcommand === "logout") runCli(logoutCommand(rest));
+  else if (subcommand === "status" || subcommand === "whoami") runCli(statusCommand(rest));
+  else runCli(main());
 }
 
 export {
@@ -825,4 +1167,17 @@ export {
   writeLoopbackTokens,
   readLoopbackClientInfo,
   writeLoopbackClientInfo,
+  // AUTH-54/55/57/58
+  cacheFilePath,
+  identityKeyFromTokens,
+  identityLabelFromTokens,
+  readActiveIdentity,
+  writeActiveIdentity,
+  clearActiveIdentity,
+  listCachedIdentities,
+  listKnownClientSlugs,
+  parseClientFlag,
+  loginCommand,
+  logoutCommand,
+  statusCommand,
 };