teamclaude-cloud 1.4.1

package/src/cloud.js

@@ -0,0 +1,618 @@
+// teamclaude-cloud client — zero runtime dependencies (Node built-ins only).
+//
+// Talks to the Supabase `cloud` Edge Function (token sync + auth-key control) and
+// Supabase Auth (owner login). Pure HTTP helpers so a mock server can drive tests.
+//
+// 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';
+
+// 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
+// `npm install`, no `cloud login`), and owner login goes through the cloud API's
+// /auth proxy — so no backing-infrastructure host or API key ships in this
+// package. Override via `cloud login --url` or a `config.cloud` entry —
+// resolveCloud() layers user config on top of this.
+export const DEFAULT_CLOUD = {
+  url: 'https://auth.teamclaude.cloud',
+};
+
+/**
+ * Resolve the cloud endpoint for a command: user config (from `cloud login`)
+ * layered over the built-in public default. So key-only `pull` works with zero
+ * config, while an explicit `cloud login` (custom url/anonKey/session) still wins.
+ */
+export function resolveCloud(config) {
+  return { ...DEFAULT_CLOUD, ...(config && config.cloud ? config.cloud : {}) };
+}
+
+/**
+ * Remove live accounts (and their in-memory config entries) that are no longer in
+ * the desired disk set — the removal counterpart to syncAccountsFromDisk (which
+ * only adds/updates). Used after a cloud pull prunes accounts (group change or key
+ * revocation). Matches UUID-first then name, as everywhere else. In-flight requests
+ * holding the removed account OBJECT drain safely (AccountManager keys on object
+ * identity, not array index). Pure logic over the AccountManager interface so it is
+ * unit-testable with a lightweight fake. Returns the count removed.
+ */
+export function reconcileRemovedAccounts(diskConfig, memConfig, accountManager) {
+  const desiredUuids = new Set();
+  const desiredNames = new Set();
+  for (const a of (diskConfig && diskConfig.accounts) || []) {
+    if (a.accountUuid) desiredUuids.add(a.accountUuid);
+    desiredNames.add(a.name); // name is only a fallback for UUID-less (legacy) live accounts
+  }
+  // UUID-FIRST (same precedence as syncAccountsFromDisk): a live account that HAS a
+  // UUID is judged by UUID only — never kept by a name that collides with a
+  // different-UUID desired account (else a revoked/removed uuid:A,name:X account
+  // survives because desired uuid:B shares name X). Only a UUID-less live account
+  // falls back to a name match.
+  const isDesired = (a) => a.accountUuid ? desiredUuids.has(a.accountUuid) : desiredNames.has(a.name);
+  let removed = 0;
+  for (const am of accountManager.accounts.filter((a) => !isDesired(a))) {
+    const idx = accountManager.accounts.indexOf(am); // current index (removeAccount re-indexes)
+    if (idx >= 0) {
+      accountManager.removeAccount(idx);
+      console.log(`[TeamClaude] Removed account "${am.name}" — no longer allowed by cloud`);
+      removed++;
+    }
+  }
+  if (memConfig && Array.isArray(memConfig.accounts)) {
+    memConfig.accounts = memConfig.accounts.filter(isDesired); // mirror so a later save doesn't resurrect
+  }
+  return removed;
+}
+
+// A stable, non-reversible per-KEY tag used to scope the merge prune. Deriving it
+// from the auth key (not the group) means a key that MOVES groups replaces its own
+// account set (old-group accounts get pruned), while two DIFFERENT keys never
+// prune each other (Codex HIGH: key-move revocation + multi-key footgun).
+export function keySource(authKey) {
+  return 'key:' + createHash('sha256').update(String(authKey)).digest('hex').slice(0, 16);
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+async function httpJson(url, { method = 'GET', headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: { 'content-type': 'application/json', ...headers },
+      body: body != null ? JSON.stringify(body) : undefined,
+      signal: ctrl.signal,
+      // Never follow redirects: an https→http 307/308 would replay credential
+      // bodies (passwords, JWTs, auth keys) over plaintext. The cloud API never
+      // legitimately redirects, so treat any redirect as an error.
+      redirect: 'error',
+    });
+    const text = await res.text();
+    let data = null;
+    if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+    return { ok: res.ok, status: res.status, data };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function fnBase(cloud) {
+  return `${cloud.url.replace(/\/+$/, '')}/functions/v1/cloud`;
+}
+
+// Refuse to send credentials (passwords, JWTs, refresh/auth keys) over plaintext
+// HTTP. Loopback is allowed for local development against a mock/dev server.
+function assertSecureUrl(url) {
+  let u;
+  try { u = new URL(url); } catch { throw new Error(`Invalid cloud URL: ${url}`); }
+  const loopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1';
+  if (u.protocol !== 'https:' && !loopback) {
+    throw new Error(`Refusing to send credentials over ${u.protocol}//. Use https:// (loopback excepted).`);
+  }
+}
+
+function requireCloud(cloud) {
+  if (!cloud || !cloud.url) {
+    throw new Error('Cloud not configured. Run `teamclaude cloud login` first.');
+  }
+  assertSecureUrl(cloud.url);
+}
+
+// The Edge Function itself needs no API key; `apikey` is only sent when a user
+// config carries one (a legacy login against a raw Supabase host).
+function fnHeaders(cloud, extra = {}) {
+  const h = { ...extra };
+  if (cloud.anonKey) h.apikey = cloud.anonKey;
+  return h;
+}
+
+function requireSession(cloud) {
+  requireCloud(cloud);
+  if (!cloud.session || !cloud.session.access_token) {
+    throw new Error('Not logged in to cloud. Run `teamclaude cloud login`.');
+  }
+}
+
+// ── owner auth (via the cloud API's /auth proxy) ─────────────────────────────
+// Login goes through OUR endpoint — the CLI never talks to the backing auth
+// host directly and needs no API key.
+
+/** Password grant → session. Does NOT persist; caller stores it in config.cloud. */
+export async function cloudLogin(cloud, email, password) {
+  assertSecureUrl(cloud.url);
+  const res = await httpJson(`${fnBase(cloud)}/auth/login`, {
+    method: 'POST',
+    headers: fnHeaders(cloud),
+    body: { email, password },
+  });
+  if (!res.ok) throw new Error(`Cloud login failed (${res.status}): ${describe(res.data)}`);
+  return {
+    access_token: res.data.access_token,
+    refresh_token: res.data.refresh_token,
+    expires_at: res.data.expires_at, // seconds epoch
+  };
+}
+
+/** Refresh an expired owner session. */
+export async function cloudRefreshSession(cloud, refreshToken) {
+  assertSecureUrl(cloud.url);
+  const res = await httpJson(`${fnBase(cloud)}/auth/refresh`, {
+    method: 'POST',
+    headers: fnHeaders(cloud),
+    body: { refresh_token: refreshToken },
+  });
+  if (!res.ok) throw new Error(`Cloud session refresh failed (${res.status}): ${describe(res.data)}`);
+  return {
+    access_token: res.data.access_token,
+    refresh_token: res.data.refresh_token,
+    expires_at: res.data.expires_at,
+  };
+}
+
+// ── token sync ───────────────────────────────────────────────────────────────
+
+/**
+ * Map one `<config>.quota.json` snapshot entry (exportQuotaState shape) to the
+ * usage payload the cloud stores for the dashboard: 5h session, 7d weekly, and
+ * model-scoped weekly windows (e.g. `7d_oi`, shown as "Fable"). Returns null
+ * when the account has no measured numbers — no row is written for it, so the
+ * dashboard shows "no data" instead of a fake zero (fail-loud, not fallback).
+ */
+export function buildUsageFromQuota(entry) {
+  const q = entry?.quota;
+  if (!q || typeof q !== 'object') return null;
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const modelWeekly = {};
+  for (const [label, w] of Object.entries(q.modelWeekly || {})) {
+    const utilization = num(w?.utilization), reset = num(w?.reset);
+    if (utilization == null && reset == null) continue;
+    modelWeekly[label] = { utilization, reset };
+  }
+  const usage = {
+    session: { utilization: num(q.unified5h), reset: num(q.unified5hReset) },
+    weekly: { utilization: num(q.unified7d), reset: num(q.unified7dReset) },
+    modelWeekly,
+  };
+  const measured = usage.session.utilization != null || usage.weekly.utilization != null
+    || Object.keys(modelWeekly).length > 0;
+  return measured ? usage : null;
+}
+
+/**
+ * Push local accounts' tokens to the cloud (owner-authenticated).
+ * `expiresAt` is normalized to ms so the cloud freshest-token-wins compares apples to apples.
+ * `usageByUuid` (optional Map/object accountUuid → usage from buildUsageFromQuota)
+ * rides along so the dashboard can show 5h/7d/Fable utilization.
+ */
+export async function cloudPush(cloud, accounts, usageByUuid = null) {
+  requireSession(cloud);
+  const usageOf = (uuid) => {
+    if (!usageByUuid || !uuid) return undefined;
+    const u = usageByUuid instanceof Map ? usageByUuid.get(uuid) : usageByUuid[uuid];
+    return u || undefined;
+  };
+  const payload = {
+    accounts: (accounts || []).map((a) => ({
+      accountUuid: a.accountUuid,
+      name: a.name,
+      tier: a.subscriptionType || a.tier || null,
+      type: a.type || 'oauth',
+      accessToken: a.accessToken ?? null,
+      refreshToken: a.refreshToken ?? null,
+      expiresAt: normalizeExpiresAt(a.expiresAt) || 0,
+      usage: usageOf(a.accountUuid),
+    })),
+  };
+  const res = await httpJson(`${fnBase(cloud)}/sync/push`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: payload,
+  });
+  if (!res.ok) throw new Error(`Cloud push failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, pushed, updated, skipped }
+}
+
+/**
+ * Usage-only push (owner session): update the cloud's live 5h/7d/Fable usage for
+ * the given accounts WITHOUT touching tokens, so the dashboard reflects real-time
+ * usage instead of only-on-push. `usageByUuid` is a Map/object accountUuid ->
+ * buildUsageFromQuota() output. Only accounts that already exist in the cloud
+ * (established by a prior cloudPush) are updated; the cloud never creates an
+ * account or writes a token from this path. Returns { ok, updated, skipped }.
+ */
+export async function cloudPushUsage(cloud, usageByUuid) {
+  requireSession(cloud);
+  const usage = {};
+  const entries = usageByUuid instanceof Map ? usageByUuid.entries() : Object.entries(usageByUuid || {});
+  for (const [uuid, u] of entries) { if (uuid && u) usage[uuid] = u; }
+  if (!Object.keys(usage).length) return { ok: true, updated: 0, skipped: 0 };
+  const res = await httpJson(`${fnBase(cloud)}/sync/usage`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { usage },
+  });
+  if (!res.ok) throw new Error(`Cloud usage push failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, updated, skipped }
+}
+
+/**
+ * Consumer usage report (auth key): the proxies that actually USE the accounts
+ * report the live 5h/7d/Fable numbers they observe — no owner session required,
+ * the pull key IS the credential (same as pull/refresh). The cloud restricts the
+ * write to the key's group accounts. Same payload/result as cloudPushUsage.
+ */
+export async function cloudReportUsage(cloud, authKey, usageByUuid) {
+  requireCloud(cloud);
+  if (!authKey) throw new Error('Missing auth key');
+  const usage = {};
+  const entries = usageByUuid instanceof Map ? usageByUuid.entries() : Object.entries(usageByUuid || {});
+  for (const [uuid, u] of entries) { if (uuid && u) usage[uuid] = u; }
+  if (!Object.keys(usage).length) return { ok: true, updated: 0, skipped: 0 };
+  const res = await httpJson(`${fnBase(cloud)}/sync/usage`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { 'x-teamclaude-key': authKey }),
+    body: { usage },
+  });
+  if (!res.ok) throw new Error(`Cloud usage report failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, updated, skipped }
+}
+
+/**
+ * Cloud-centralized token refresh (auth key). Ask the cloud for a fresh access
+ * token for `accountUuid` instead of refreshing (rotating) the OAuth refresh token
+ * locally — the cloud does the single rotation, so the same account is safe to use
+ * from many PCs at once. Returns { accessToken, refreshToken, expiresAt, refreshed }.
+ * Throws on any non-2xx (the caller should fall back to a local refresh).
+ */
+export async function cloudRefreshToken(cloud, authKey, accountUuid, minRemainingMs) {
+  requireCloud(cloud);
+  if (!authKey) throw new Error('Auth key required for cloud refresh.');
+  if (!accountUuid) throw new Error('accountUuid required for cloud refresh.');
+  const body = { accountUuid };
+  if (Number.isFinite(minRemainingMs)) body.minRemainingMs = minRemainingMs;
+  const res = await httpJson(`${fnBase(cloud)}/sync/refresh`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { 'x-teamclaude-key': authKey }),
+    body,
+  });
+  if (!res.ok) throw new Error(`Cloud refresh failed (${res.status}): ${describe(res.data)}`);
+  return {
+    accessToken: res.data.accessToken,
+    refreshToken: res.data.refreshToken,
+    expiresAt: normalizeExpiresAt(res.data.expiresAt) || 0,
+    refreshed: !!res.data.refreshed,
+  };
+}
+
+/**
+ * Pull allowed accounts+tokens using an auth key (no owner session needed).
+ * Returns `{ accounts, allowed, groupId, source }`:
+ *  - `accounts` — the token payload (accounts that actually have a cloud token), ms-normalized.
+ *  - `allowed`  — the authoritative allow-set (EVERY enabled account uuid in the
+ *    key's group, token or not); the merge prunes against THIS, so an allowed-but-
+ *    tokenless account isn't pruned (Codex HIGH-B).
+ *  - `groupId`  — informational (the key's group).
+ *  - `source`   — a stable per-key tag for scoping the merge prune (keySource).
+ * The server fails loud (non-2xx) on any DB/decrypt error, so a thrown pull never
+ * reaches merge and never prunes on a transient failure.
+ */
+export async function cloudPull(cloud, authKey) {
+  requireCloud(cloud);
+  if (!authKey) throw new Error('Auth key required for pull.');
+  const res = await httpJson(`${fnBase(cloud)}/sync/pull`, {
+    headers: fnHeaders(cloud, { 'x-teamclaude-key': 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).
+    const err = new Error(`Cloud pull failed (${res.status}): ${describe(res.data)}`);
+    err.status = res.status;
+    err.revoked = res.status === 403;
+    throw err;
+  }
+  const accounts = (res.data.accounts || []).map((a) => ({
+    ...a,
+    expiresAt: normalizeExpiresAt(a.expiresAt) || 0,
+  }));
+  // `allowed` is the server's authoritative allow-set. If the server didn't send
+  // it (an OLDER function version), we CANNOT safely prune — using the token
+  // payload as the allow-set could delete legitimate local accounts on a partial
+  // response (Codex round 4). So leave it null → merge skips pruning entirely
+  // (additive-only, the pre-group behavior).
+  const allowed = Array.isArray(res.data.allowed) ? res.data.allowed : null;
+  return { accounts, allowed, groupId: res.data.groupId ?? null, source: keySource(authKey) };
+}
+
+// ── auth-key management (owner-authenticated) ────────────────────────────────
+
+export async function cloudKeyCreate(cloud, { label, groupId } = {}) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/auth-keys`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { label: label ?? null, groupId: groupId ?? null },
+  });
+  if (!res.ok) throw new Error(`Key create failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, id, key (raw, once), prefix, label, status, groupId }
+}
+
+/** Reveal (decrypt) a key's full value for re-copy. Owner-only; only works for
+ * keys issued with encrypted storage (410 not_revealable for old hash-only keys). */
+export async function cloudKeyReveal(cloud, id) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/auth-keys/${encodeURIComponent(id)}/reveal`, {
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+  });
+  if (!res.ok) throw new Error(`Key reveal failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, id, key }
+}
+
+/** Move a key to another group. */
+export async function cloudKeyMove(cloud, id, groupId) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/auth-keys/${encodeURIComponent(id)}/group`, {
+    method: 'PUT',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { groupId },
+  });
+  if (!res.ok) throw new Error(`Key move failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, id, groupId, group }
+}
+
+export async function cloudKeyList(cloud) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/auth-keys`, {
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+  });
+  if (!res.ok) throw new Error(`Key list failed (${res.status}): ${describe(res.data)}`);
+  return res.data.keys || [];
+}
+
+export async function cloudKeyRevoke(cloud, id) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/auth-keys/${encodeURIComponent(id)}/revoke`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+  });
+  if (!res.ok) throw new Error(`Key revoke failed (${res.status}): ${describe(res.data)}`);
+  return res.data;
+}
+
+// ── group management (owner-authenticated) ───────────────────────────────────
+// Accounts are allowed per GROUP (not per key). An account may be enabled in at
+// most one group at a time — the cloud answers 409 (account_in_use) otherwise.
+
+export async function cloudGroupList(cloud) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/groups`, {
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+  });
+  if (!res.ok) throw new Error(`Group list failed (${res.status}): ${describe(res.data)}`);
+  return res.data.groups || []; // [{ id, name, accounts: [{accountUuid, name, enabled, priority}], activeKeys }]
+}
+
+export async function cloudGroupCreate(cloud, name) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/groups`, {
+    method: 'POST',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { name },
+  });
+  if (!res.ok) throw new Error(`Group create failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, id, name }
+}
+
+export async function cloudGroupRename(cloud, id, name) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/groups/${encodeURIComponent(id)}`, {
+    method: 'PUT',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { name },
+  });
+  if (!res.ok) throw new Error(`Group rename failed (${res.status}): ${describe(res.data)}`);
+  return res.data;
+}
+
+export async function cloudGroupDelete(cloud, id) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/groups/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+  });
+  if (!res.ok) throw new Error(`Group delete failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, id, keysMovedTo }
+}
+
+/**
+ * Replace a group's allowed accounts. `accounts` = [{accountUuid, enabled, priority}].
+ * A 409 means one of the accounts is enabled in another group (exclusivity) —
+ * the error message names the conflicting group(s).
+ * `expectedRevision` (optional) enables optimistic-concurrency: pass the revision
+ * you read; a stale write (concurrent edit) is rejected 409.
+ */
+export async function cloudGroupSetAccounts(cloud, id, accounts, expectedRevision = null) {
+  requireSession(cloud);
+  const body = { accounts: accounts || [] };
+  if (Number.isInteger(expectedRevision)) body.expectedRevision = expectedRevision;
+  const res = await httpJson(`${fnBase(cloud)}/groups/${encodeURIComponent(id)}/accounts`, {
+    method: 'PUT',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body,
+  });
+  if (!res.ok) {
+    if (res.status === 409 && res.data?.error === 'stale_revision') {
+      throw new Error('Group changed concurrently (409 stale_revision): re-list and retry.');
+    }
+    if (res.status === 409 && Array.isArray(res.data?.conflicts)) {
+      const who = res.data.conflicts.map((c) => `${c.accountName} (그룹 "${c.group}")`).join(', ');
+      throw new Error(`Group mapping conflict (409): 이미 다른 그룹에서 사용 중 — ${who}`);
+    }
+    throw new Error(`Group mapping failed (${res.status}): ${describe(res.data)}`);
+  }
+  return res.data; // { ok, id, accounts, revision }
+}
+
+// ── account global enable/disable ────────────────────────────────────────────
+
+export async function cloudAccountSetEnabled(cloud, accountUuid, enabled) {
+  requireSession(cloud);
+  const res = await httpJson(`${fnBase(cloud)}/accounts/${encodeURIComponent(accountUuid)}`, {
+    method: 'PATCH',
+    headers: fnHeaders(cloud, { Authorization: `Bearer ${cloud.session.access_token}` }),
+    body: { enabled: !!enabled },
+  });
+  if (!res.ok) throw new Error(`Account update failed (${res.status}): ${describe(res.data)}`);
+  return res.data; // { ok, accountUuid, enabled }
+}
+
+// ── merge pulled accounts into a local config (freshest-token-wins) ──────────
+
+/**
+ * Merge cloud-pulled accounts into a teamclaude config in place.
+ * Matches by accountUuid then name. Never overwrites a locally-fresher token
+ * (compares ms-normalized expiresAt) — the same rule the proxy uses on disk sync.
+ *
+ * The pulled `priority` (the key's GROUP ordering) is control-plane state and is
+ * applied even when the token itself is skipped as staler: the group config is
+ * authoritative for how a consumer orders its accounts, and the local proxy's
+ * existing `_priority`-then-use-or-lose selection consumes it unchanged.
+ * `priority: null` clears the field back to automatic (use-or-lose) ordering.
+ *
+ * **Revocation propagation (Codex HIGH #3):** a pull returns the *authoritative*
+ * allowed set for the key's group. Accounts written by a pull are tagged with
+ * their source group (`cloudSource: <groupId>`); on each subsequent pull, any
+ * account tagged with THIS group's source but NOT in the new set is **pruned** —
+ * otherwise removing an account from the group (or disabling/moving it) would
+ * leave its token locally, where the proxy keeps refreshing and using it
+ * indefinitely. Scoping the prune to the source group means alternating pulls
+ * with two different keys/groups don't prune each other's accounts. Accounts
+ * with no source tag (locally-added, or pulled before this version) are never
+ * pruned. When `source` (groupId) is null (a pre-group server response) nothing
+ * is tagged and nothing is pruned — the additive-only legacy behavior.
+ *
+ * @param {object} config  teamclaude config (mutated in place)
+ * @param {Array}  pulled  cloudPull().accounts — the token payload
+ * @param {string|null} source  cloudPull().source — a stable per-key tag; scopes tagging + pruning
+ * @param {Array|null}  allowed cloudPull().allowed — authoritative allow-set (uuids/names) to prune against.
+ *                              Defaults to the pulled token payload's keys when omitted.
+ * Returns a summary { added, updated, skipped, removed }.
+ */
+export function mergePulledAccounts(config, pulled, source = null, allowed = null) {
+  const summary = { added: 0, updated: 0, skipped: 0, removed: 0 };
+  if (!Array.isArray(config.accounts)) config.accounts = [];
+  const applyPriority = (target, incoming) => {
+    if (!('priority' in incoming)) return; // pre-group cloud response — leave local as-is
+    if (Number.isInteger(incoming.priority)) target.priority = incoming.priority;
+    else delete target.priority; // null → automatic ordering
+  };
+  // Multi-source tagging: an account can be managed by several keys (a consumer
+  // using >1 key whose groups overlap). Each key adds its source; an account is
+  // only pruned once NO managing key still allows it (Codex round 4 R4-3).
+  const addSource = (target) => {
+    if (source == null) return;
+    if (!Array.isArray(target.cloudSources)) target.cloudSources = [];
+    if (!target.cloudSources.includes(source)) target.cloudSources.push(source);
+  };
+  const hasAnyToken = (a) => a.accessToken != null || a.refreshToken != null;
+  const list = pulled || [];
+  for (const a of list) {
+    const incomingExp = normalizeExpiresAt(a.expiresAt) || 0;
+    // Match by accountUuid FIRST across the whole array; fall back to name only
+    // for legacy rows without a UUID. A name-first match could otherwise overwrite
+    // the wrong account when a same-name/different-UUID row appears earlier.
+    let idx = a.accountUuid ? config.accounts.findIndex((x) => x.accountUuid === a.accountUuid) : -1;
+    if (idx === -1) idx = config.accounts.findIndex((x) => !x.accountUuid && x.name === a.name);
+    if (idx === -1) {
+      const fresh = {
+        name: a.name,
+        accountUuid: a.accountUuid,
+        type: a.type || 'oauth',
+        accessToken: a.accessToken ?? null,
+        refreshToken: a.refreshToken ?? null,
+        expiresAt: incomingExp,
+        subscriptionType: a.tier || undefined,
+        enabled: true,
+      };
+      addSource(fresh);
+      applyPriority(fresh, a);
+      config.accounts.push(fresh);
+      summary.added++;
+      continue;
+    }
+    const cur = config.accounts[idx];
+    addSource(cur); // now managed by this key (so this key can prune it later)
+    // A payload entry with no token at all (allowed-but-tokenless) must not clobber
+    // a valid local token — only apply priority/metadata, keep the local token.
+    if (!hasAnyToken(a)) { applyPriority(cur, a); summary.skipped++; continue; }
+    const curExp = normalizeExpiresAt(cur.expiresAt) || 0;
+    if (curExp > incomingExp) { applyPriority(cur, a); summary.skipped++; continue; } // local token fresher — keep it
+    config.accounts[idx] = {
+      ...cur,
+      accountUuid: a.accountUuid || cur.accountUuid,
+      type: a.type || cur.type || 'oauth',
+      // Preserve a local token field the payload leaves null — a partial token
+      // payload (one field null) must not wipe the other (Codex round 4 R4-2).
+      accessToken: a.accessToken ?? cur.accessToken ?? null,
+      refreshToken: a.refreshToken ?? cur.refreshToken ?? null,
+      expiresAt: incomingExp,
+      subscriptionType: a.tier || cur.subscriptionType,
+    };
+    applyPriority(config.accounts[idx], a);
+    summary.updated++;
+  }
+  // Prune: only when the server sent an authoritative allow-set (`allowed`). Never
+  // prune against the token payload alone — a partial payload could delete
+  // legitimate accounts (Codex round 4 R4-1). Scope to THIS key's source: drop
+  // this source from any account it no longer allows; prune only accounts left
+  // with no managing source.
+  if (source != null && Array.isArray(allowed)) {
+    const allowSet = new Set(allowed);
+    // Ensure EVERY account this key currently allows carries this key's source —
+    // including allowed-but-tokenless accounts that never appear in the token
+    // payload (else a later prune by another key would drop them, Codex round 5).
+    for (const x of config.accounts) {
+      if (allowSet.has(x.accountUuid) || allowSet.has(x.name)) addSource(x);
+    }
+    const before = config.accounts.length;
+    config.accounts = config.accounts.filter((x) => {
+      const sources = Array.isArray(x.cloudSources) ? x.cloudSources : [];
+      if (!sources.includes(source)) return true; // not managed by this key — keep
+      if (allowSet.has(x.accountUuid) || allowSet.has(x.name)) return true; // still allowed by this key
+      // This key no longer allows it — drop this source. Keep if another key still manages it.
+      x.cloudSources = sources.filter((s) => s !== source);
+      return x.cloudSources.length > 0;
+    });
+    summary.removed = before - config.accounts.length;
+  }
+  return summary;
+}
+
+function describe(data) {
+  if (data == null) return '';
+  if (typeof data === 'string') return data;
+  if (data.error) return String(data.error) + (data.detail ? ` — ${data.detail}` : '');
+  return JSON.stringify(data);
+}