@rikcodes/teamclaude 1.1.13-rik.1

package/src/account-uuid-rewrite.js

@@ -0,0 +1,115 @@
+// Rewrite the request body's account_uuid to match the account whose token we
+// inject. Claude Code puts the logged-in account's UUID inside `metadata.user_id`
+// (a stringified JSON) of /v1/messages; under rotation that would disagree with
+// the injected token.
+//
+// This is a STREAMING, byte-exact JSON state machine — no regex, no whole-body
+// buffering — so it handles arbitrarily large bodies fed in chunks. It tracks
+// JSON structure (container stack, current key, in-string/escape) to find the
+// `metadata.user_id` string value, and only inside that value does it look for
+// the `account_uuid` field and overwrite its 36-char value with the new UUID
+// (same length → no content-length/flow-control changes). A stray `account_uuid`
+// elsewhere in the body (user content, tool results) is never touched.
+
+// Byte sequence of `account_uuid":"` as it appears INSIDE the (escaped) user_id
+// string: account_uuid \ " : \ "
+const PREFIX = Buffer.from('account_uuid\\":\\"', 'latin1');
+
+export class AccountUuidPatcher {
+  constructor(newUuid) {
+    this.newUuid = (typeof newUuid === 'string' && newUuid.length === 36) ? Buffer.from(newUuid, 'latin1') : null;
+    this.frames = [];          // container stack: { container:'obj'|'arr', name, key, awaitingKey }
+    this.inStr = false;
+    this.esc = false;
+    this.readingKey = false;
+    this.keyBuf = [];
+    this.target = false;       // inside the metadata.user_id string value
+    this.matchPos = 0;         // PREFIX match progress (within target)
+    this.uuidRemaining = 0;    // value bytes left to overwrite
+    this.done = false;         // patched the one account_uuid already
+    this.changed = false;
+  }
+
+  /** Feed a chunk; returns a same-length chunk (patched in place). */
+  push(chunk) {
+    if (!this.newUuid || this.done) return chunk;
+    const out = Buffer.from(chunk);
+    for (let i = 0; i < out.length; i++) {
+      out[i] = this.#byte(out[i]);
+      if (this.done) break; // rest passes through unchanged
+    }
+    return out;
+  }
+
+  #top() { return this.frames[this.frames.length - 1]; }
+
+  #byte(b) {
+    if (this.target) return this.#targetByte(b);
+
+    if (this.inStr) {
+      if (this.esc) { this.esc = false; if (this.readingKey) this.keyBuf.push(b); return b; }
+      if (b === 0x5c) { this.esc = true; return b; }             // backslash
+      if (b === 0x22) {                                          // end of string
+        this.inStr = false;
+        if (this.readingKey) { this.#top().key = Buffer.from(this.keyBuf).toString('latin1'); this.keyBuf = []; this.readingKey = false; }
+        return b;
+      }
+      if (this.readingKey) this.keyBuf.push(b);
+      return b;
+    }
+
+    const top = this.#top();
+    switch (b) {
+      case 0x7b: this.frames.push({ container: 'obj', name: top ? top.key : null, key: null, awaitingKey: true }); break; // {
+      case 0x5b: this.frames.push({ container: 'arr', name: top ? top.key : null, key: null, awaitingKey: false }); break; // [
+      case 0x7d: case 0x5d: this.frames.pop(); break;            // } ]
+      case 0x3a: if (top) top.awaitingKey = false; break;        // : (key → value)
+      case 0x2c: if (top && top.container === 'obj') top.awaitingKey = true; break; // ,
+      case 0x22:                                                 // string start
+        if (top && top.container === 'obj' && top.awaitingKey) {
+          this.readingKey = true; this.keyBuf = []; this.inStr = true; this.esc = false;
+        } else {
+          this.inStr = true; this.esc = false; this.readingKey = false;
+          if (top && top.container === 'obj' && top.name === 'metadata' && top.key === 'user_id' && this.frames.length === 2) {
+            this.target = true; this.matchPos = 0; this.uuidRemaining = 0;
+          }
+        }
+        break;
+      default: break; // scalars / whitespace
+    }
+    return b;
+  }
+
+  // Inside the metadata.user_id string value: stream-match the account_uuid key
+  // and overwrite its 36-byte value. Detect the (unescaped) closing quote to exit.
+  #targetByte(b) {
+    if (this.uuidRemaining > 0) {
+      const outByte = this.newUuid[this.newUuid.length - this.uuidRemaining];
+      this.uuidRemaining--;
+      if (outByte !== b) this.changed = true;
+      if (this.uuidRemaining === 0) this.done = true; // only one account_uuid per body
+      return outByte;
+    }
+    if (this.esc) { this.esc = false; this.#match(b); return b; }
+    if (b === 0x5c) { this.esc = true; this.#match(b); return b; }
+    if (b === 0x22) { this.target = false; this.matchPos = 0; return b; } // end of user_id value
+    this.#match(b);
+    return b;
+  }
+
+  #match(b) {
+    if (b === PREFIX[this.matchPos]) {
+      this.matchPos++;
+      if (this.matchPos === PREFIX.length) { this.uuidRemaining = 36; this.matchPos = 0; }
+    } else {
+      this.matchPos = (b === PREFIX[0]) ? 1 : 0; // PREFIX has no internal repeat of its first byte
+    }
+  }
+}
+
+/** One-shot convenience (whole-buffer); returns the same instance if unchanged. */
+export function patchAccountUuid(buf, newUuid) {
+  const p = new AccountUuidPatcher(newUuid);
+  const out = p.push(buf);
+  return p.changed ? out : buf;
+}

package/src/alias.js

@@ -0,0 +1,125 @@
+// `claude` shell alias — print or install/uninstall.
+//
+// The alias simply routes plain `claude` through `teamclaude run`, which probes
+// the proxy and, when it's down, errors out rather than silently bypassing the
+// proxy. All the smarts live in `run`; add `--auto-fallback` to the alias if you
+// want plain `claude` to launch directly when the proxy is down instead.
+//
+// This only affects interactive shells (aliases aren't seen by editors/scripts
+// that exec `claude` themselves). It's intentionally lighter than a PATH shim:
+// no binary shadowing, one line per rc, trivially reversible.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, realpathSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const MARKER = '# teamclaude alias';
+
+/** Basename of the user's login shell, e.g. "zsh". Defaults to bash. */
+export function detectShell() {
+  return (process.env.SHELL || '').split('/').pop() || 'bash';
+}
+
+/** Whether a bare command resolves on the current $PATH. */
+function commandOnPath(cmd) {
+  for (const dir of (process.env.PATH || '').split(':')) {
+    if (dir && existsSync(join(dir, cmd))) return true;
+  }
+  return false;
+}
+
+/**
+ * How the alias should invoke teamclaude. Prefer the bare `teamclaude` when it's
+ * on $PATH; otherwise embed the absolute path to this CLI (quoted) so the alias
+ * still works when teamclaude isn't installed on PATH — e.g. run from a clone.
+ */
+export function teamclaudeRef() {
+  if (commandOnPath('teamclaude')) return 'teamclaude';
+  const entry = process.argv[1];
+  if (!entry) return 'teamclaude';
+  let abs;
+  try { abs = realpathSync(entry); } catch { abs = entry; }
+  return `"${abs}"`;
+}
+
+/** The alias definition for a given shell family. */
+export function aliasLine(shell = detectShell(), ref = teamclaudeRef()) {
+  const body = `${ref} run --`;
+  if (shell === 'fish') return `alias claude '${body}'`;
+  return `alias claude='${body}'`;
+}
+
+/** The rc file an alias for this shell should live in. */
+export function rcPathForShell(shell = detectShell()) {
+  const home = homedir();
+  switch (shell) {
+    case 'zsh':  return join(home, '.zshrc');
+    case 'sh':   return join(home, '.profile');
+    case 'fish': {
+      const cfg = process.env.XDG_CONFIG_HOME || join(home, '.config');
+      return join(cfg, 'fish', 'conf.d', 'teamclaude.fish');
+    }
+    case 'bash':
+    default:     return join(home, '.bashrc');
+  }
+}
+
+export function printAlias({ shell = detectShell() } = {}) {
+  const line = aliasLine(shell);
+  console.log('# Route plain `claude` through the proxy (errors if the proxy is down;');
+  console.log('# append --auto-fallback before `--` to launch claude directly instead).');
+  console.log('# Add this to your shell config:');
+  console.log('');
+  console.log(`  ${line}`);
+  console.log('');
+  console.log(`# Or install it automatically: teamclaude alias --install`);
+  console.log(`#   → writes to ${rcPathForShell(shell)} (override with --shell <bash|zsh|fish|sh>)`);
+}
+
+export function installAlias({ shell = detectShell(), rcPath = rcPathForShell(shell) } = {}) {
+  const line = aliasLine(shell);
+  mkdirSync(dirname(rcPath), { recursive: true });
+  let text = existsSync(rcPath) ? readFileSync(rcPath, 'utf8') : '';
+
+  if (text.includes(line)) {
+    console.log(`Alias already present in ${rcPath}`);
+    return;
+  }
+  if (text && !text.endsWith('\n')) text += '\n';
+  text += `${MARKER}\n${line}\n`;
+  writeFileSync(rcPath, text);
+  console.log(`Installed alias in ${rcPath}`);
+  console.log('Reload your shell (or open a new terminal) to use it.');
+}
+
+export function uninstallAlias({ shell = detectShell(), rcPath = rcPathForShell(shell) } = {}) {
+  if (!existsSync(rcPath)) {
+    console.log(`Nothing to remove (${rcPath} does not exist)`);
+    return;
+  }
+  const text = readFileSync(rcPath, 'utf8');
+  // Strip our marked block: the marker comment + the single line after it.
+  // Matching by marker (not by exact alias text) makes this robust even if the
+  // embedded teamclaude path differs from what's computed now.
+  const blockRe = new RegExp(`\\n?${escapeRe(MARKER)}\\n[^\\n]*\\n?`, 'g');
+  let cleaned = text.replace(blockRe, '\n');
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+
+  if (cleaned === text) {
+    console.log(`Alias not found in ${rcPath}`);
+    return;
+  }
+
+  // For the dedicated fish drop-file, remove it entirely if now empty.
+  if (rcPath.endsWith('teamclaude.fish') && cleaned.trim() === '') {
+    rmSync(rcPath);
+    console.log(`Removed ${rcPath}`);
+    return;
+  }
+  writeFileSync(rcPath, cleaned);
+  console.log(`Removed alias from ${rcPath}`);
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/claude-env.js

@@ -0,0 +1,65 @@
+// Percent-encode an account name (or key) for a URL, leaving ONLY the unreserved
+// set. encodeURIComponent alone is not enough here: it passes `( ) ' ! *`
+// through untouched, and these lines are emitted as unquoted shell `export`
+// statements for `eval "$(teamclaude env)"` — a name like "work (Acme)" would be
+// a shell syntax error. Clients percent-decode userinfo before using it
+// (verified against Claude Code 2.1.220), so the extra escaping is transparent.
+export function encodePinComponent(s) {
+  return encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+// Build the shell `export` lines that point Claude Code — or any tool that
+// spawns it, e.g. an agent multiplexer — at the proxy. This is the same
+// environment `teamclaude run` sets up, but emitted for `eval "$(teamclaude
+// env)"` instead of launching claude directly. Pure and side-effect free so it
+// can be unit-tested; the caller resolves the port, cert path, and holdSeconds.
+//
+// MITM (forward-proxy) mode is the default, matching `teamclaude run`: it routes
+// ALL of claude's traffic through the proxy — even hardcoded api.anthropic.com
+// endpoints (e.g. the design MCP) — with claude trusting our leaf via
+// NODE_EXTRA_CA_CERTS. base-URL mode only redirects the Anthropic base URL and
+// leaves other hosts alone.
+//
+// No ANTHROPIC_API_KEY is emitted: loopback clients are exempt from the proxy's
+// key gate, and setting it would drop Claude Code out of subscription mode (and
+// its full model access). Remote clients that aren't on loopback must add the
+// proxy key themselves.
+// `account` pins the session to one account (TC_ACCT), exactly as `teamclaude
+// run` does: in MITM mode it rides in the proxy URL's userinfo and reaches the
+// proxy as the CONNECT's Basic username; in base-URL mode it becomes a
+// `/tc-acct/` prefix. TC_ACCT itself is then unset, so the pin does not leak
+// into claude or anything it spawns — same reasoning as `run` deleting it from
+// the child environment.
+export function buildClaudeEnvLines({ port, useMitm = true, caPath = null, holdSeconds = 0, account = null, proxyApiKey = '' }) {
+  const lines = [];
+  const pin = (account || '').trim();
+
+  if (useMitm) {
+    const userinfo = pin ? `${encodePinComponent(pin)}:${encodePinComponent(proxyApiKey || '')}@` : '';
+    const proxyUrl = `http://${userinfo}127.0.0.1:${port}`;
+    lines.push(
+      `export HTTPS_PROXY=${proxyUrl}`,
+      `export HTTP_PROXY=${proxyUrl}`,
+      `export https_proxy=${proxyUrl}`,
+      `export http_proxy=${proxyUrl}`,
+      'export NO_PROXY=localhost,127.0.0.1,::1',
+      'export no_proxy=localhost,127.0.0.1,::1',
+    );
+    if (caPath) lines.push(`export NODE_EXTRA_CA_CERTS=${caPath}`);
+    // Clear any stale base-URL so the two modes don't stack in one shell.
+    lines.push('unset ANTHROPIC_BASE_URL');
+  } else {
+    const prefix = pin ? `/tc-acct/${encodePinComponent(pin)}` : '';
+    lines.push(`export ANTHROPIC_BASE_URL=http://localhost:${port}${prefix}`);
+  }
+
+  // The pin is now carried by the routing itself; keep it out of the child.
+  if (pin) lines.push('unset TC_ACCT');
+
+  // Parity with `run`: if the proxy may hold the connection on exhaustion, raise
+  // the client-side timeout so it doesn't give up mid-hold.
+  const holdMs = (holdSeconds || 0) * 1000;
+  if (holdMs > 0) lines.push(`export API_TIMEOUT_MS=${holdMs + 60_000}`);
+
+  return lines;
+}

package/src/config.js

@@ -0,0 +1,146 @@
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { resolveUpstreamProxy, setUpstreamProxy } from './upstream-proxy.js';
+
+export function getConfigPath() {
+  if (process.env.TEAMCLAUDE_CONFIG) return process.env.TEAMCLAUDE_CONFIG;
+  const configDir = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(configDir, 'teamclaude.json');
+}
+
+/**
+ * Path to the runtime state file (a sibling of the config). This holds volatile
+ * data learned at runtime — e.g. quota utilization observed passively from
+ * traffic — kept out of the hand-editable config so config stays clean and
+ * isn't rewritten on every state save.
+ */
+export function getStatePath() {
+  const cfg = getConfigPath();
+  return cfg.endsWith('.json') ? cfg.replace(/\.json$/, '.state.json') : cfg + '.state';
+}
+
+/**
+ * Path to the crash log (a sibling of the config), where a fatal error is
+ * recorded before the process exits.
+ */
+export function getCrashLogPath() {
+  const cfg = getConfigPath();
+  return cfg.endsWith('.json') ? cfg.replace(/\.json$/, '-crash.log') : cfg + '-crash.log';
+}
+
+export async function loadState() {
+  try {
+    return JSON.parse(await readFile(getStatePath(), 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function saveState(state) {
+  const path = getStatePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  // `mode` only applies when the file is CREATED; enforce 0600 on every save so
+  // a pre-existing state file (holding quota + tokens) can't linger world-readable.
+  await chmod(path, 0o600).catch(() => {});
+}
+
+export function createDefaultConfig() {
+  return {
+    proxy: {
+      port: 3456,
+      apiKey: 'tc-' + randomBytes(24).toString('base64url'),
+    },
+    upstream: 'https://api.anthropic.com',
+    switchThreshold: 0.98,
+    holdSeconds: 0,
+    distributeSessions: false,
+    eventLogging: 'hide',
+    blockedModels: [],
+    accounts: [],
+  };
+}
+
+export async function loadConfig() {
+  const path = getConfigPath();
+  try {
+    const config = JSON.parse(await readFile(path, 'utf-8'));
+    applyUpstreamProxy(config);
+    return config;
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Publish the config's egress proxy to the process-wide setting.
+ *
+ * Done here, in the one place every command loads its config, rather than at
+ * each of the sixteen call sites: `login`, `import`, `accounts`, `probe` and the
+ * server all reach the network, and a proxy that applied to only some of them
+ * would be worse than none — the account list would refresh while logging in
+ * failed, or vice versa.
+ *
+ * A bad value is fatal on purpose. Falling back to a direct connection on a host
+ * that has no route to the internet would turn one clear error into a pile of
+ * ETIMEDOUTs pointing nowhere near the typo that caused them.
+ */
+function applyUpstreamProxy(config) {
+  try {
+    setUpstreamProxy(resolveUpstreamProxy(config));
+  } catch (err) {
+    console.error(`[TeamClaude] Bad proxy setting in ${getConfigPath()}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+export async function loadOrCreateConfig() {
+  let config = await loadConfig();
+  if (!config) {
+    config = createDefaultConfig();
+    await saveConfig(config);
+    console.log(`Created config at ${getConfigPath()}`);
+  }
+  return config;
+}
+
+export async function saveConfig(config) {
+  const path = getConfigPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  // Enforce 0600 even if the file already existed (the proxy apiKey + account
+  // tokens live here); `mode` above is honored only on creation.
+  await chmod(path, 0o600).catch(() => {});
+}
+
+// Serialize config updates. atomicConfigUpdate is a read-modify-write, so two
+// concurrent callers can both read the same config and then save in turn, and
+// the later save silently drops the earlier caller's change. This bites hardest
+// on startup, when several OAuth accounts refresh their tokens at once: only the
+// last writer's rotated refresh token persists, and the other accounts keep a
+// token that was just rotated away, so they fail on the next restart with
+// invalid_grant and need a re-login. Chaining the updates keeps every write.
+let configUpdateChain = Promise.resolve();
+
+/**
+ * Atomically update the config: re-reads from disk, calls updater(config),
+ * then saves. Returns the updated config. This prevents overwriting changes
+ * made by other processes (e.g. `teamclaude import` while the server runs), and
+ * serializes concurrent callers so simultaneous updates queue instead of
+ * clobbering one another.
+ */
+export function atomicConfigUpdate(updater) {
+  const run = async () => {
+    const config = await loadConfig() || createDefaultConfig();
+    await updater(config);
+    await saveConfig(config);
+    return config;
+  };
+  const result = configUpdateChain.then(run, run);
+  configUpdateChain = result.then(() => {}, () => {});
+  return result;
+}

package/src/crash-log.js

@@ -0,0 +1,27 @@
+import { appendFileSync } from 'node:fs';
+
+/**
+ * Write a fatal error to `path` before the process dies.
+ *
+ * Node prints an uncaught exception to stderr and exits, which is invisible in
+ * practice: the server runs under a full-screen TUI that repaints over the
+ * stack, and stderr usually goes nowhere anyone kept. The one artifact that
+ * explains a sudden exit has to outlive the process, so write it to a file.
+ *
+ * Handling these events replaces Node's own behaviour, so this must do what
+ * Node would: report and exit non-zero. Continuing after an uncaught exception
+ * would leave the proxy running on unknown state.
+ */
+export function installCrashHandlers(path, { exit = process.exit, log = process.stderr } = {}) {
+  const report = (kind) => (err) => {
+    const stack = err?.stack || String(err);
+    const entry = `\n=== ${new Date().toISOString()} ${kind} ===\n${stack}\n`;
+    // 0600: a stack can carry request context. A write failure (read-only home,
+    // full disk) must not mask the crash itself — stderr still gets the entry.
+    try { appendFileSync(path, entry, { mode: 0o600 }); } catch { /* report to stderr regardless */ }
+    log.write(entry);
+    exit(1);
+  };
+  process.on('uncaughtException', report('uncaughtException'));
+  process.on('unhandledRejection', report('unhandledRejection'));
+}

package/src/egress-guard.js

@@ -0,0 +1,132 @@
+// Egress pinning — refuse to spend an account from the wrong exit IP.
+//
+// When a VPN drops mid-session, traffic silently continues from the machine's
+// own address. Anthropic answers a request from an unexpected region with 403
+// "Request not allowed", and Claude Code reads that 403 as a dead session and
+// asks for a re-login — over a network event, with the token still valid. The
+// account has already been used from the new address by then.
+//
+// So the check belongs BEFORE the request: if the exit IP is not the pinned
+// one, hold the request until the tunnel is back rather than sending it. A held
+// request looks like a slow response; a sent one can cost a re-login.
+//
+// Opt-in: without `egress.pin` in the config this is inert and nothing here runs.
+
+const DEFAULT_CHECK_URL = 'https://api.ipify.org';
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_HOLD_MS = 120_000;
+const POLL_MS = 3_000;
+
+export class EgressGuard {
+  /**
+   * @param {object} opts
+   * @param {string|string[]} opts.pin  'auto' (pin whatever is seen first), or one or more allowed IPs
+   */
+  constructor({ pin, checkUrl = DEFAULT_CHECK_URL, ttlMs = DEFAULT_TTL_MS, holdMs = DEFAULT_HOLD_MS,
+    fetchImpl = fetch, pollMs = POLL_MS, log = () => {} } = {}) {
+    this.pin = pin || null;
+    this.checkUrl = checkUrl;
+    this.ttlMs = ttlMs;
+    this.holdMs = holdMs;
+    this.pollMs = pollMs;
+    this._fetch = fetchImpl;
+    this.log = log;
+    this._ip = null;         // last observed exit IP
+    this._checkedAt = 0;     // when it was observed
+    this._auto = null;       // the address 'auto' latched onto
+    this._inFlight = null;   // coalesces concurrent probes
+  }
+
+  enabled() { return !!this.pin; }
+
+  /** The addresses considered correct, once known. */
+  allowed() {
+    if (this.pin === 'auto') return this._auto ? [this._auto] : [];
+    return Array.isArray(this.pin) ? this.pin : [this.pin];
+  }
+
+  /**
+   * Current exit IP, cached for ttlMs. Returns null when the probe fails — the
+   * caller treats that as "unknown", never as "wrong": a probe that cannot
+   * complete is usually the same outage that is about to fail the request
+   * anyway, and blocking on it would turn a third-party hiccup into an outage
+   * of our own.
+   */
+  async currentIp({ force = false } = {}) {
+    if (!force && this._ip && Date.now() - this._checkedAt < this.ttlMs) return this._ip;
+    if (this._inFlight) return this._inFlight;
+
+    this._inFlight = (async () => {
+      try {
+        const res = await this._fetch(this.checkUrl, { signal: AbortSignal.timeout(5_000) });
+        const ip = (await res.text()).trim();
+        if (!ip) return null;
+        this._ip = ip;
+        this._checkedAt = Date.now();
+        // 'auto' pins the first address it sees. The server starts with the
+        // tunnel up in the normal case, so that address is the one to hold for.
+        if (this.pin === 'auto' && !this._auto) {
+          this._auto = ip;
+          this.log(`[TeamClaude] Egress pinned to ${ip}`);
+        }
+        return ip;
+      } catch {
+        return null;
+      } finally {
+        this._inFlight = null;
+      }
+    })();
+
+    return this._inFlight;
+  }
+
+  /** Is `ip` one of the pinned addresses? Unknown (null) counts as allowed. */
+  matches(ip) {
+    if (!ip) return true;
+    const allowed = this.allowed();
+    return allowed.length === 0 || allowed.includes(ip);
+  }
+
+  /** One check against the pin: { ok, ip, expected }. */
+  async check(opts) {
+    const ip = await this.currentIp(opts);
+    return { ok: this.matches(ip), ip, expected: this.allowed() };
+  }
+
+  /**
+   * Block until the exit IP is the pinned one again, or the hold budget runs
+   * out. Returns { ok, ip, expected, waitedMs } — ok:false means the caller
+   * should refuse the request rather than send it from the wrong address.
+   */
+  async waitUntilPinned({ isAborted = () => false } = {}) {
+    const started = Date.now();
+    let state = await this.check();
+    if (state.ok) return { ...state, waitedMs: 0 };
+
+    this.log(`[TeamClaude] Egress is ${state.ip}, not the pinned ${state.expected.join(', ')} — holding requests`);
+    while (Date.now() - started < this.holdMs) {
+      if (isAborted()) return { ...state, waitedMs: Date.now() - started };
+      await new Promise(resolve => setTimeout(resolve, this.pollMs));
+      state = await this.check({ force: true });
+      if (state.ok) {
+        const waitedMs = Date.now() - started;
+        this.log(`[TeamClaude] Egress back on ${state.ip} after ${Math.round(waitedMs / 1000)}s`);
+        return { ...state, waitedMs };
+      }
+    }
+    return { ...state, waitedMs: Date.now() - started };
+  }
+}
+
+/** Build a guard from config, or null when the feature is not configured. */
+export function createEgressGuard(config, log) {
+  const cfg = config?.egress;
+  if (!cfg?.pin) return null;
+  return new EgressGuard({
+    pin: cfg.pin,
+    checkUrl: cfg.checkUrl,
+    ttlMs: cfg.ttlSeconds != null ? cfg.ttlSeconds * 1000 : undefined,
+    holdMs: cfg.holdSeconds != null ? cfg.holdSeconds * 1000 : undefined,
+    log,
+  });
+}