teamclaude-cloud 1.8.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamclaude-cloud",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Multi-account Claude proxy with quota-based rotation + cloud token sync and auth-key control",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -66,6 +66,13 @@ export class AccountManager {
       // `personal` flag). Surfaced so the dashboard/status can label it "private"
       // vs a shared/fleet account.
       isPrivate: acct.cloudPrivate === true,
+      // Cloud-management provenance carried on the LIVE object (not just in mutable
+      // config): an account whose token is shared with the cloud — pulled from it
+      // (cloudSources) OR pushed to it (cloudPushed) — must NEVER be rotated locally.
+      // Keeping it here means a held in-flight account still reports cloud-managed
+      // even after reconcileRemovedAccounts() drops its config entry (revocation
+      // race) — so a late 401→refresh can't fall through to a poisoning local rotation.
+      cloudManaged: (Array.isArray(acct.cloudSources) && acct.cloudSources.length > 0) || !!acct.cloudPushed,
       quota: emptyQuota(),
       usage: {
         totalInputTokens: 0,
@@ -978,24 +985,66 @@ export class AccountManager {
         // Refresh via an injected handler when set (e.g. cloud-centralized refresh
         // so multiple PCs don't each rotate the same account's refresh token); it
         // falls back to a local refresh internally. Default: local OAuth refresh.
+        // A cloud-managed (shared) account must only be refreshed via an injected cloud
+        // handler — never by the DEFAULT local path, which would rotate the token shared
+        // across PCs and poison it. If no handler is set (an AccountManager built outside
+        // the proxy server), refuse rather than poison. The server always sets one.
+        if (!this._refreshHandler && account.cloudManaged) {
+          throw new Error(`Refusing to locally refresh cloud-managed account "${account.name}" (no cloud refresh handler)`);
+        }
         const newTokens = this._refreshHandler
           ? await this._refreshHandler(account)
           : await refreshAccessToken(account.refreshToken);
+        // Validate the payload BEFORE mutating account state. A handler that returns a
+        // malformed 2xx result (e.g. the cloud replies {} or omits accessToken/expiresAt)
+        // must NOT overwrite the live credential with undefined, clear 'error', and let
+        // the account re-enter rotation sending "Bearer undefined". Treat it as a refresh
+        // failure so the account stays unavailable until a real token arrives.
+        if (!newTokens
+            || typeof newTokens.accessToken !== 'string' || newTokens.accessToken === ''
+            || typeof newTokens.refreshToken !== 'string' || newTokens.refreshToken === ''
+            || !Number.isFinite(newTokens.expiresAt) || newTokens.expiresAt <= 0) {
+          throw new Error(`Refresh returned an invalid token payload for "${account.name}"`);
+        }
+        // The token we're rotating AWAY. Anthropic invalidates it the moment newTokens is
+        // issued, so if the on-disk config still holds this exact parent, our new token is
+        // unambiguously newer (even at an equal expiry second) and must overwrite it —
+        // passed to the persist callback so it can break the same-second tie correctly.
+        const parentRefreshToken = account.refreshToken;
         account.credential = newTokens.accessToken;
         account.refreshToken = newTokens.refreshToken;
         account.expiresAt = newTokens.expiresAt;
+        // A successful refresh means the account is usable again — clear a prior
+        // 'error' so a cloud-managed account stuck in error (e.g. after a transient
+        // cloud outage) rejoins rotation once the cloud token is healthy again,
+        // WITHOUT a proxy restart. getActiveAccount excludes 'error', so nothing else
+        // would ever revive it; the recovery timer re-probes such accounts.
+        if (account.status === 'error') account.status = 'active';
+        delete account.errorTransient; // healed — clear the stale failure-class marker
         console.log(`[TeamClaude] Token refreshed for account "${account.name}"`);
         // Only persist if the account is still live at its claimed index. If it was
         // removed during the (awaited) network refresh, its `.index` is stale and
         // would misattribute the write to the survivor that shifted into that slot
         // — and a deleted account's tokens don't need persisting anyway.
-        if (this.accounts[account.index] === account) this._onTokenRefresh?.(account.index, newTokens);
+        // AWAIT the persist callback so this refresh doesn't resolve until the rotated token
+        // reaches disk — a concurrent `cloud push` drains _refreshPromise before snapshotting,
+        // so an un-awaited persist would let it upload the pre-rotation token (dead-chain poison).
+        // Guarded: a persist failure must not turn a successful refresh into an error.
+        if (this.accounts[account.index] === account) {
+          try { await this._onTokenRefresh?.(account.index, newTokens, parentRefreshToken); }
+          catch (persistErr) { console.error(`[TeamClaude] Token persist error for "${account.name}": ${persistErr.message}`); }
+        }
       } catch (err) {
         console.error(`[TeamClaude] Token refresh failed for "${account.name}": ${err.message}`);
         // Only mark as error if the access token is actually expired;
         // a failed proactive refresh shouldn't kill a still-valid token
         if (!account.expiresAt || Date.now() >= account.expiresAt) {
           account.status = 'error';
+          // Record the failure CLASS so the request path can distinguish a TRANSIENT cloud outage
+          // (retryable 503 — the recovery timer heals it) from a TERMINAL auth failure (401 —
+          // re-auth needed). Default (no flag) = terminal; only a cloud handler that classified
+          // the failure as transient (network/5xx) sets err.transient.
+          account.errorTransient = err && err.transient === true;
         }
       } finally {
         account._refreshPromise = null;
@@ -1060,6 +1109,7 @@ export class AccountManager {
       enabled: acctData.enabled !== false,
       priority: Number.isFinite(acctData.priority) ? Math.floor(acctData.priority) : null,
       isPrivate: acctData.cloudPrivate === true,
+      cloudManaged: (Array.isArray(acctData.cloudSources) && acctData.cloudSources.length > 0) || !!acctData.cloudPushed,
       quota: emptyQuota(),
       usage: { totalInputTokens: 0, totalOutputTokens: 0, totalRequests: 0, lastUsed: null },
       rateLimitedUntil: null,

package/src/cloud.js

@@ -6,7 +6,8 @@
 // Config lives under the teamclaude config as `config.cloud`:
 //   { url, anonKey, email, session: { access_token, refresh_token, expires_at } }
 import { createHash } from 'node:crypto';
-import { normalizeExpiresAt } from './oauth.js';
+import { normalizeExpiresAt, refreshAccessToken } from './oauth.js';
+import { findConfigAccount } from './config.js';
 
 // Built-in PUBLIC cloud endpoint — our own domain only. A consumer PC pulls with
 // ONLY an auth key (`teamclaude cloud pull --key <key>` works right after
@@ -27,6 +28,15 @@ export function resolveCloud(config) {
   return { ...DEFAULT_CLOUD, ...(config && config.cloud ? config.cloud : {}) };
 }
 
+// Whether a URL points at the built-in default cloud, tolerant of a trailing slash. Used to
+// gate the ambient env auth key to the default endpoint ONLY (never a custom URL). A raw ===
+// compare would treat `https://…cloud/` as a DIFFERENT endpoint than `https://…cloud`, wrongly
+// SUPPRESSING the env key so cloud-managed accounts can't refresh and go unavailable.
+export function isDefaultCloudUrl(url) {
+  const strip = (u) => (typeof u === 'string' ? u.replace(/\/+$/, '') : u);
+  return strip(url) === strip(DEFAULT_CLOUD.url);
+}
+
 /**
  * Remove live accounts (and their in-memory config entries) that are no longer in
  * the desired disk set — the removal counterpart to syncAccountsFromDisk (which
@@ -245,7 +255,15 @@ export async function cloudPush(cloud, accounts, usageByUuid = null, authKey = n
     headers: fnHeaders(cloud, authHeader),
     body: payload,
   });
-  if (!res.ok) throw new Error(`Cloud push failed (${res.status}): ${describe(res.data)}`);
+  if (!res.ok) {
+    // Attach the HTTP status so callers can tell a DEFINITIVE pre-commit rejection
+    // (4xx — the cloud refused, nothing was stored) from an AMBIGUOUS transport/server
+    // failure (5xx/timeout/network — the write MAY have committed). Reverting a
+    // cloudPushed mark is only safe on the former (irreversible-mutation-uncertain).
+    const err = new Error(`Cloud push failed (${res.status}): ${describe(res.data)}`);
+    err.status = res.status;
+    throw err;
+  }
   return res.data; // { ok, pushed, updated, skipped }
 }
 
@@ -312,7 +330,14 @@ export async function cloudRefreshToken(cloud, authKey, accountUuid, minRemainin
     headers: fnHeaders(cloud, { 'x-teamclaude-key': authKey }),
     body,
   });
-  if (!res.ok) throw new Error(`Cloud refresh failed (${res.status}): ${describe(res.data)}`);
+  if (!res.ok) {
+    // Attach the HTTP status so the handler can classify TERMINAL (4xx invalid_grant/revoked →
+    // needs re-auth) vs TRANSIENT (5xx/network → healable by the recovery timer). A network error
+    // (thrown before res exists) has no status → treated as transient by the handler.
+    const err = new Error(`Cloud refresh failed (${res.status}): ${describe(res.data)}`);
+    err.status = res.status;
+    throw err;
+  }
   return {
     accessToken: res.data.accessToken,
     refreshToken: res.data.refreshToken,
@@ -362,12 +387,14 @@ export async function cloudPull(cloud, authKey) {
   });
   if (!res.ok) {
     // Attach the HTTP status so a live-sync loop can classify the failure:
-    // 403 = the key was revoked/invalidated (stop serving); 5xx/0/network =
-    // transient (keep last-known accounts, retry next interval). See index.js
-    // syncFromCloudOnce (irreversible-mutation 3-way: revoke vs transient).
+    // 401/403 = definitive AUTH failure (bad/revoked/invalidated key) → treat as revoked so the
+    // loop applies the reversible hold (stop serving); 5xx/0/network = transient (keep last-known
+    // accounts, retry next interval). Both 401 and 403 are "the key doesn't authorize" — a server
+    // may use either — and the hold is reversible, so a transient auth blip returning 401 recovers
+    // on the next successful pull. See index.js syncFromCloudOnce (irreversible-mutation 3-way).
     const err = new Error(`Cloud pull failed (${res.status}): ${describe(res.data)}`);
     err.status = res.status;
-    err.revoked = res.status === 403;
+    err.revoked = res.status === 403 || res.status === 401;
     throw err;
   }
   const accounts = (res.data.accounts || []).map((a) => ({
@@ -704,3 +731,150 @@ function describe(data) {
   if (data.error) return String(data.error) + (data.detail ? ` — ${data.detail}` : '');
   return JSON.stringify(data);
 }
+
+/**
+ * Is this account's authoritative token shared with the cloud?
+ *
+ * An account is cloud-shared once it is either PULLED from the cloud (`cloudSources`
+ * set) OR explicitly PUSHED to it (`cloudPushed`). In both cases the cloud holds the
+ * authoritative refresh-token chain, shared across every PC. Such an account must be
+ * refreshed ONLY through the cloud's centralized rotation and NEVER rotated locally:
+ * Anthropic invalidates the previous refresh token on every rotation, so an
+ * independent local rotation on one PC kills the shared token for the cloud AND every
+ * other PC (divergent-chain poisoning — the exact failure the centralized design
+ * exists to prevent). Covering the PUSH side too closes the origin-PC hole: a PC that
+ * pushes an account it authenticated locally has no cloudSources, but its token is now
+ * shared, so it must not local-rotate either. Matches UUID-first then legacy name.
+ */
+export function isCloudManaged(config, account) {
+  if (!config || !account || !Array.isArray(config.accounts)) return false;
+  const i = findConfigAccount(config, account);
+  if (i < 0) return false;
+  const a = config.accounts[i];
+  return (Array.isArray(a.cloudSources) && a.cloudSources.length > 0) || !!a.cloudPushed;
+}
+
+/**
+ * Ordered auth keys AUTHORIZED to refresh a specific account, most-specific first.
+ *
+ * An account can be pulled from more than one auth key (its `cloudSources` lists a
+ * `keySource(key)` per key), but `config.cloud.pullKey` only holds the LAST key used.
+ * Refreshing with a single key 403s for accounts in a different key's group. So we
+ * return EVERY key that grants this account (mapped from its cloudSources via the
+ * `{ keySource(key) -> key }` store `config.cloud.pullKeys` accumulated across pulls),
+ * then the default `pullKey` — and the handler tries them in order. This means that
+ * when one authorizing key is revoked but ANOTHER still grants the account, the refresh
+ * transparently uses the surviving key instead of erroring (key-revocation availability).
+ * Falls back to `[pullKey]` for single-key / legacy configs / a removed account entry.
+ */
+export function refreshKeyCandidates(config, account) {
+  const c = config && config.cloud;
+  if (!c) return [];
+  const out = [];
+  const push = (k) => { if (typeof k === 'string' && k && !out.includes(k)) out.push(k); };
+  const store = c.pullKeys && typeof c.pullKeys === 'object' ? c.pullKeys : null;
+  let hasProvenance = false; // account carries a cloudSources tag (pulled), vs. push-only / none
+  if (store && account) {
+    const i = findConfigAccount(config, account);
+    const sources = i >= 0 && Array.isArray(config.accounts[i].cloudSources)
+      ? config.accounts[i].cloudSources : [];
+    if (sources.length) hasProvenance = true;
+    for (const s of sources) push(store[s]);
+  }
+  push(c.pullKey); // default / single-key / legacy fallback
+  // Then, ONLY for an account with NO cloudSources provenance, EVERY stored key. A pushed
+  // account that hasn't yet gained a cloudSources tag (its post-success reconcile is pending
+  // or failed transiently) has no source-specific key, so it must try all authorized keys —
+  // else a revoked default pullKey would block its refresh while another valid key still
+  // grants it. But an account that DOES have provenance whose source key is simply gone from
+  // the store keeps only the default: don't blast every key at an account whose authorizing
+  // key is known-gone (that would 403-spray unrelated keys). Wrong keys just 403; handler moves on.
+  if (store && !hasProvenance) for (const k of Object.values(store)) push(k);
+  return out;
+}
+
+/**
+ * Build the AccountManager token-refresh handler.
+ *
+ * Cloud-centralized refresh: when a cloud key is present and the account has a UUID,
+ * route the refresh through the cloud so the SAME account used from multiple PCs is
+ * rotated exactly ONCE (by the cloud), not independently by each PC.
+ *
+ * CRITICAL — single-authority for cloud-managed accounts: if the cloud refresh fails
+ * for a cloud-managed account (see isCloudManaged) we DO NOT fall back to a local
+ * rotation. A local `refreshAccessToken` would rotate the shared refresh token
+ * independently of the cloud, and because Anthropic invalidates the previous refresh
+ * token on every rotation, that poisons the token for the cloud and every other PC
+ * (an account "shared across PCs" then dies as invalid_grant everywhere). Instead we
+ * surface the error: on a transient cloud outage the cloud's token is preserved for a
+ * later central refresh (the account recovers automatically — see the recovery timer
+ * in serverCommand); on a terminal invalid_grant the account needs a one-time re-auth
+ * at the source. A brief unavailability is the correct trade-off over permanently
+ * poisoning a token shared across machines.
+ *
+ * NON-cloud (locally-owned) accounts keep the local refresh — there is no shared cloud
+ * token to protect, so this PC is their sole authority.
+ *
+ * `deps` allows injecting cloud/oauth functions for unit testing without network I/O.
+ */
+export function createCloudRefreshHandler(config, deps = {}) {
+  const resolveCloudFn = deps.resolveCloud || resolveCloud;
+  const cloudRefreshTokenFn = deps.cloudRefreshToken || cloudRefreshToken;
+  const refreshAccessTokenFn = deps.refreshAccessToken || refreshAccessToken;
+  const candidatesFn = deps.refreshKeyCandidates || refreshKeyCandidates;
+  return async (account) => {
+    const cloud = resolveCloudFn(config);
+    // Every key that authorizes THIS account (multi-key fleets), most-specific first,
+    // then env — tried in order so a revoked key transparently yields to a surviving
+    // one instead of erroring. Not just the last pullKey (which 403s cross-group).
+    const keys = candidatesFn(config, account);
+    // The ambient env key carries no endpoint binding, so it's presumed for the DEFAULT
+    // cloud: append it ONLY when the resolved endpoint IS the default — never send it to a
+    // custom/self-hosted URL the config points at (key exfiltration via a tricked endpoint).
+    const envKey = deps.envKey !== undefined
+      ? deps.envKey
+      : (isDefaultCloudUrl(cloud.url) ? process.env.TEAMCLAUDE_AUTH_KEY : undefined);
+    if (envKey && !keys.includes(envKey)) keys.push(envKey);
+    // Prefer the provenance flag carried on the LIVE account object — it survives a
+    // reconcileRemovedAccounts() that drops the config entry mid-request (revocation
+    // race), so a held account can't fall through to a poisoning local rotation. Fall
+    // back to the config lookup for accounts constructed without the flag.
+    const cloudManaged = account.cloudManaged === true || isCloudManaged(config, account);
+    // ONLY cloud-managed (shared) accounts ever touch the cloud refresh path. A non-cloud
+    // (local) account must local-refresh ONLY — attempting a cloud refresh for it (e.g.
+    // because an env auth key or some pullKey happens to authorize its UUID) would advance
+    // a cloud token chain WITHOUT marking cloudPushed/cloudSources provenance; a later cloud
+    // failure would then fall back to local rotation and poison that chain. So a local
+    // account skips the cloud path entirely — no cloud attempt, ever.
+    if (cloudManaged) {
+      if (keys.length && account.accountUuid) {
+        let lastErr;
+        for (const k of keys) {
+          try {
+            const t = await cloudRefreshTokenFn(cloud, k, account.accountUuid);
+            return {
+              accessToken: t.accessToken,
+              refreshToken: t.refreshToken || account.refreshToken,
+              expiresAt: t.expiresAt,
+            };
+          } catch (err) { lastErr = err; }
+        }
+        // Single-authority: never local-rotate a cloud-managed (shared) token, even after
+        // every authorized key failed (revoked/outage) — a local rotation would poison the
+        // token shared across PCs. Surface the error → the account goes unavailable and the
+        // recovery timer re-probes until a key/cloud recovers. Preserve the FAILURE CLASS so the
+        // proxy can tell a transient outage (retryable) from a terminal invalid_grant (re-auth):
+        // transient iff the last key's failure had NO status (network) or a 5xx; a 4xx (invalid/
+        // revoked key, invalid_grant) is TERMINAL and must surface as an auth error, not a
+        // permanent "recovering" 503.
+        const e = new Error(`Cloud refresh failed for cloud-managed account "${account.name}" — refusing to rotate locally (a local rotation would poison the token shared across PCs): ${lastErr?.message}`);
+        e.transient = !lastErr?.status || lastErr.status >= 500;
+        throw e;
+      }
+      // Cloud-managed but no cloud key/UUID to reach the cloud → cannot refresh safely;
+      // refusing to local-rotate is still correct (would poison the share).
+      throw new Error(`Cannot refresh cloud-managed account "${account.name}" without a cloud key — refusing to rotate locally (single-authority).`);
+    }
+    return refreshAccessTokenFn(account.refreshToken); // local fallback — non-cloud accounts ONLY
+  };
+}