mcp-google-multi 5.4.1-alpha.2 → 6.0.0-alpha.2

package/dist/ssrf-guard.js

@@ -0,0 +1,242 @@
+// B13 / C11: SSRF guard for every server-side fetch (the CIMD client_id doc).
+// D4 decision (dependencies-and-bv §2.2): a small AUDITED private-range check,
+// no dependency — HTTPS-only, resolve-then-check ALL addresses (anti-rebind),
+// and cap redirects / size / time. Blocks 10/8, 172.16/12, 192.168/16, 127/8,
+// 169.254/16, 0/8, multicast, ::1, fc00::/7, fe80::/10, and v4-mapped forms.
+import { lookup } from 'node:dns/promises';
+import { isIPv4, isIPv6, BlockList } from 'node:net';
+export class SsrfBlockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SsrfBlockedError';
+    }
+}
+/** True if an IPv4 literal is in a blocked (private/link-local/loopback/etc) range. */
+export function isBlockedIPv4(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return true;
+    const [a, b] = parts;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network"
+    if (a === 10)
+        return true; // 10/8 private
+    if (a === 127)
+        return true; // 127/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254/16 link-local (incl. cloud metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64/10 CGNAT
+    if (a >= 224)
+        return true; // 224/4 multicast + 240/4 reserved
+    return false;
+}
+// Built-in subnet math (no hand-rolled IPv6 parsing): blocks loopback,
+// unspecified, ULA, link-local, multicast, and ALL v4-mapped / v4-compatible /
+// NAT64 / 6to4 embeddings (a public host never resolves to those, so blocking
+// the whole range closes the embedded-private-target gap without parsing).
+const V6_BLOCKED = new BlockList();
+V6_BLOCKED.addSubnet('::', 96, 'ipv6'); // ::/96 = ::1, ::, and v4-compatible
+V6_BLOCKED.addSubnet('::ffff:0:0', 96, 'ipv6'); // v4-mapped
+V6_BLOCKED.addSubnet('64:ff9b::', 96, 'ipv6'); // NAT64
+V6_BLOCKED.addSubnet('2002::', 16, 'ipv6'); // 6to4
+V6_BLOCKED.addSubnet('fc00::', 7, 'ipv6'); // unique-local
+V6_BLOCKED.addSubnet('fe80::', 10, 'ipv6'); // link-local
+V6_BLOCKED.addSubnet('ff00::', 8, 'ipv6'); // multicast
+/** True if an IPv6 literal is blocked. */
+export function isBlockedIPv6(ip) {
+    const addr = ip.replace(/^\[|\]$/g, '');
+    if (!isIPv6(addr))
+        return true;
+    return V6_BLOCKED.check(addr, 'ipv6');
+}
+export function isBlockedIp(ip) {
+    if (isIPv4(ip))
+        return isBlockedIPv4(ip);
+    if (isIPv6(ip))
+        return isBlockedIPv6(ip);
+    return true; // unparseable → block
+}
+async function defaultResolveAll(host) {
+    // A bare IP literal needs no DNS; check it directly.
+    if (isIPv4(host) || isIPv6(host))
+        return [host];
+    const results = await lookup(host, { all: true });
+    return results.map((r) => r.address);
+}
+/**
+ * Assert a URL is safe to fetch server-side: HTTPS scheme, and every address
+ * the host resolves to is public. Throws SsrfBlockedError otherwise, and
+ * returns the resolved IPs.
+ *
+ * NOTE: this checks the host's addresses but does NOT pin them — the caller
+ * fetches by hostname, so undici re-resolves at connect time (a check-time vs
+ * connect-time TOCTOU / short-TTL rebind window). We deliberately do not pin
+ * (CDN IPs rotate). The real anti-SSRF control is the caller-side issuer
+ * allowlist (oauth-as validateClient rejects any non-allowlisted host BEFORE
+ * fetching), so an attacker can't steer the fetch at an arbitrary hostname;
+ * this public-range check is defense-in-depth on top of that.
+ */
+export async function assertPublicHttpsUrl(rawUrl, deps = {}) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new SsrfBlockedError(`not a valid URL: ${rawUrl}`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new SsrfBlockedError(`only https is allowed (got ${url.protocol})`);
+    }
+    const resolveAll = deps.resolveAll ?? defaultResolveAll;
+    let addresses;
+    try {
+        addresses = await resolveAll(url.hostname);
+    }
+    catch (e) {
+        throw new SsrfBlockedError(`DNS resolution failed for ${url.hostname}: ${e.message}`);
+    }
+    if (addresses.length === 0)
+        throw new SsrfBlockedError(`no addresses resolved for ${url.hostname}`);
+    for (const ip of addresses) {
+        if (isBlockedIp(ip)) {
+            throw new SsrfBlockedError(`${url.hostname} resolves to a blocked address (${ip})`);
+        }
+    }
+    return { url, addresses };
+}
+// Connection-level failures that a retry can legitimately recover from. A dead
+// IPv6 route (broken egress with Happy-Eyeballs falling through), a reset, or a
+// DNS blip are transient; an SSRF block, a bad HTTP status, or malformed JSON
+// are deterministic and must NOT be retried.
+const TRANSIENT_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_SOCKET',
+]);
+function isTransientFetchError(e) {
+    if (e instanceof SsrfBlockedError)
+        return false; // deterministic security/shape reject
+    const name = e?.name;
+    if (name === 'AbortError' || name === 'TimeoutError')
+        return true; // our per-attempt timeout: dead/slow peer
+    const cause = e?.cause;
+    const code = cause?.code ?? e?.code;
+    if (code && TRANSIENT_CODES.has(code))
+        return true;
+    // undici surfaces connection failures as TypeError('fetch failed') with the
+    // real reason in .cause; retry even when the cause carries no useful code.
+    if (e instanceof TypeError && /fetch failed/i.test(e.message))
+        return true;
+    return false;
+}
+/**
+ * SSRF-guarded fetch of a CIMD client-metadata document (JSON). Every hop
+ * (including redirects) is HTTPS + public-IP checked; response is size- and
+ * time-capped. Returns the parsed JSON object.
+ */
+export async function fetchCimdDocument(rawUrl, opts = {}) {
+    const maxBytes = opts.maxBytes ?? 64 * 1024;
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    const maxRedirects = opts.maxRedirects ?? 3;
+    const retries = opts.retries ?? 2;
+    const backoffMs = opts.retryBackoffMs ?? 200;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let current = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        let redirectTo = null;
+        let doc = null;
+        // Retry transient connection failures IN PLACE. Each attempt re-runs the
+        // resolve-then-check so a retry can never skip the anti-rebind guard, and
+        // the timer is per-attempt (armed across the body read, #10).
+        for (let attempt = 0;; attempt++) {
+            await assertPublicHttpsUrl(current, opts.ssrf);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await doFetch(current, { redirect: 'manual', signal: controller.signal, headers: { accept: 'application/json' } });
+                if (res.status >= 300 && res.status < 400) {
+                    const loc = res.headers.get('location');
+                    if (!loc)
+                        throw new SsrfBlockedError('redirect without a Location header');
+                    redirectTo = loc;
+                    break;
+                }
+                if (!res.ok)
+                    throw new SsrfBlockedError(`CIMD fetch failed: HTTP ${res.status}`);
+                const text = await readCapped(res, maxBytes, controller);
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    throw new SsrfBlockedError('CIMD document is not valid JSON');
+                }
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    throw new SsrfBlockedError('CIMD document is not a JSON object');
+                }
+                doc = parsed;
+                break;
+            }
+            catch (e) {
+                if (attempt < retries && isTransientFetchError(e)) {
+                    await sleep(backoffMs * (attempt + 1));
+                    continue;
+                }
+                throw e;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        if (redirectTo !== null) {
+            current = new URL(redirectTo, current).toString();
+            continue;
+        }
+        return doc;
+    }
+    throw new SsrfBlockedError(`too many redirects (> ${maxRedirects})`);
+}
+/** Read a response body, aborting the moment it exceeds maxBytes (never buffers
+ * an oversized body). Falls back to a capped arrayBuffer when there is no
+ * readable stream (e.g. a test Response). */
+async function readCapped(res, maxBytes, controller) {
+    const reader = res.body?.getReader?.();
+    if (!reader) {
+        const buf = new Uint8Array(await res.arrayBuffer());
+        if (buf.byteLength > maxBytes)
+            throw new SsrfBlockedError(`CIMD document exceeds ${maxBytes} bytes`);
+        return new TextDecoder().decode(buf);
+    }
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            controller.abort();
+            throw new SsrfBlockedError(`CIMD document exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(value);
+    }
+    const all = new Uint8Array(size);
+    let off = 0;
+    for (const c of chunks) {
+        all.set(c, off);
+        off += c.byteLength;
+    }
+    return new TextDecoder().decode(all);
+}

package/dist/token-store.js

@@ -1,13 +1,14 @@
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
-import path from 'node:path';
-import { ACCOUNT_CONFIG } from './accounts.js';
+import { getAccountSet } from './accounts.js';
+import { noteSuccessfulDecrypt, resolveMasterKeyForDispatch } from './master-key.js';
+import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 const ENC_VERSION = 1;
 const ALGO = 'aes-256-gcm';
-const LOCK_TIMEOUT_MS = 5_000;
-const LOCK_RETRY_MS = 10;
-const RENAME_ATTEMPTS = 5;
-const RENAME_RETRY_MS = 20;
+// KDF is COMPAT-FROZEN: generated keys are randomBytes(32) base64 and take the
+// raw path; only human-passphrase keys hit the bare-sha256 branch (v5 legacy —
+// changing it would brick every existing token). HKDF + ENC_VERSION=2 is the
+// sanctioned post-6.0 hardening route.
 export function deriveKey(masterKey) {
     if (!masterKey) {
         throw new Error('MASTER_KEY is required to encrypt/decrypt tokens. Generate one with: openssl rand -base64 32');
@@ -48,141 +49,38 @@ export function decryptToken(fileContents, masterKey) {
     return JSON.parse(plaintext.toString('utf8'));
 }
 function masterKey() {
-    return process.env.MASTER_KEY ?? '';
+    return resolveMasterKeyForDispatch().key;
+}
+function encPath(alias) {
+    return getAccountSet().configs[alias].encPath;
 }
 export function readToken(alias) {
     let contents;
     try {
-        contents = fs.readFileSync(ACCOUNT_CONFIG[alias].encPath, 'utf8');
+        contents = fs.readFileSync(encPath(alias), 'utf8');
     }
     catch {
         return null;
     }
-    return decryptToken(contents, masterKey());
-}
-function sleep(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    const data = decryptToken(contents, masterKey());
+    noteSuccessfulDecrypt();
+    return data;
 }
-function withTokenLock(alias, fn) {
-    const p = ACCOUNT_CONFIG[alias].encPath;
-    const dir = path.dirname(p);
-    const lock = path.join(dir, `.${path.basename(p)}.lock`);
-    const ownerFile = `${lock}.${process.pid}.${randomBytes(6).toString('hex')}.owner`;
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
-    const deadline = Date.now() + LOCK_TIMEOUT_MS;
-    try {
-        while (true) {
-            try {
-                fs.linkSync(ownerFile, lock);
-                break;
-            }
-            catch (error) {
-                const err = error;
-                if (err.code !== 'EEXIST')
-                    throw error;
-                try {
-                    const observedOwner = fs.readFileSync(lock, 'utf8');
-                    const owner = Number(observedOwner);
-                    // Non-PID content can only come from a corrupt or interrupted lock
-                    // write — recover it like a dead owner instead of spinning to timeout.
-                    let ownerDead = !(Number.isSafeInteger(owner) && owner > 0);
-                    if (!ownerDead) {
-                        try {
-                            process.kill(owner, 0);
-                        }
-                        catch (ownerError) {
-                            const code = ownerError.code;
-                            // EPERM: PID exists but is not signalable (recycled by another user);
-                            // treat as alive, never break a lock we cannot verify.
-                            if (code === 'ESRCH')
-                                ownerDead = true;
-                            else if (code !== 'EPERM')
-                                throw ownerError;
-                        }
-                    }
-                    if (ownerDead) {
-                        if (fs.readFileSync(lock, 'utf8') === observedOwner)
-                            fs.rmSync(lock, { force: true });
-                        continue;
-                    }
-                }
-                catch (readError) {
-                    if (readError.code === 'ENOENT') {
-                        continue;
-                    }
-                    throw readError;
-                }
-                if (Date.now() >= deadline) {
-                    throw new Error(`Timed out waiting for token lock: ${alias}`, { cause: error });
-                }
-                sleep(LOCK_RETRY_MS);
-            }
-        }
-    }
-    finally {
-        fs.rmSync(ownerFile, { force: true });
-    }
-    try {
-        return fn();
-    }
-    finally {
-        fs.rmSync(lock, { force: true });
-    }
+// Lock + atomic-write mechanics live in fs-atomic.ts (generalized path-keyed
+// from this file's original alias-keyed implementation; behavior unchanged).
+export function writeToken(alias, data) {
+    withFileLock(encPath(alias), () => writeTokenAtomic(alias, data), `token lock: ${alias}`);
 }
 function writeTokenAtomic(alias, data) {
-    const p = ACCOUNT_CONFIG[alias].encPath;
-    const dir = path.dirname(p);
-    const tmp = path.join(dir, `.${path.basename(p)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
-    try {
-        fs.writeFileSync(tmp, encryptToken(data, masterKey()), { mode: 0o600, flag: 'wx' });
-        // Open read-write, not read-only: on Windows fsync maps to FlushFileBuffers,
-        // which returns EPERM on a read-only handle.
-        const fd = fs.openSync(tmp, 'r+');
-        try {
-            fs.fsyncSync(fd);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        renameWithRetry(tmp, p);
-    }
-    finally {
-        try {
-            fs.rmSync(tmp, { force: true });
-        }
-        catch {
-            // force only suppresses ENOENT; a Windows handle-holder can make this
-            // throw and mask the real write error. The orphan tmp is harmless.
-        }
-    }
-}
-// Windows only: renaming over a momentarily-open file throws transient EPERM/EACCES/EBUSY (reads take no lock); see docs/internals.md.
-function renameWithRetry(from, to) {
-    for (let attempt = 1;; attempt++) {
-        try {
-            fs.renameSync(from, to);
-            return;
-        }
-        catch (error) {
-            const code = error.code;
-            const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
-            if (!transient || attempt >= RENAME_ATTEMPTS)
-                throw error;
-            sleep(RENAME_RETRY_MS * attempt);
-        }
-    }
-}
-export function writeToken(alias, data) {
-    withTokenLock(alias, () => writeTokenAtomic(alias, data));
+    atomicWriteFileSync(encPath(alias), encryptToken(data, masterKey()), 0o600);
 }
 export function updateToken(alias, updates) {
-    withTokenLock(alias, () => {
+    withFileLock(encPath(alias), () => {
         const existing = readToken(alias) ?? {};
         const definedUpdates = Object.fromEntries(Object.entries(updates).filter(([, value]) => value !== null && value !== undefined));
         writeTokenAtomic(alias, { ...existing, ...definedUpdates });
-    });
+    }, `token lock: ${alias}`);
 }
 export function hasToken(alias) {
-    return fs.existsSync(ACCOUNT_CONFIG[alias].encPath);
+    return fs.existsSync(encPath(alias));
 }

package/dist/tools/_errors.d.ts

@@ -6,8 +6,14 @@ export interface ErrorEnvelope {
     retriable: boolean;
     account: string;
 }
-export declare function mapGoogleError(error: any, account: Account, forbiddenHint?: string): ErrorEnvelope;
-export declare function handleGoogleApiError(error: any, account: Account, forbiddenHint?: string): {
+export declare function mapGoogleError(error: any, account: Account, forbiddenHint?: string, scopeContext?: () => {
+    hint: string;
+    retriable: boolean;
+} | null): ErrorEnvelope;
+export declare function handleGoogleApiError(error: any, account: Account, forbiddenHint?: string, scopeContext?: () => {
+    hint: string;
+    retriable: boolean;
+} | null): {
     content: {
         type: "text";
         text: string;

package/dist/tools/_errors.js

@@ -1,3 +1,4 @@
+import { reauthHint } from '../reauth-hint.js';
 function statusOf(error) {
     const c = error?.code ?? error?.status ?? error?.response?.status;
     const n = typeof c === 'string' ? Number(c) : c;
@@ -11,29 +12,106 @@ function reasonOf(error) {
 function messageOf(error) {
     return error?.response?.data?.error?.message ?? error?.message ?? String(error);
 }
-export function mapGoogleError(error, account, forbiddenHint) {
+// Connect/DNS syscall codes. ENOTFOUND (no such name) is the one non-transient
+// member. node-fetch flattens the happy-eyeballs AggregateError to a bare code
+// with an empty message, so the code is the only surviving signal to surface.
+const RETRIABLE_NET_CODES = new Set([
+    'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ENETUNREACH',
+    'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
+]);
+const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
+/** First known network code on the error or its cause chain (GaxiosError.cause
+ * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
+function netCodeOf(error) {
+    for (let e = error, depth = 0; e && depth < 5; e = e.cause ?? e.error, depth++) {
+        if (typeof e.code === 'string' && NET_CODES.has(e.code))
+            return e.code;
+        if (Array.isArray(e.errors)) {
+            const sub = e.errors.find((x) => typeof x?.code === 'string' && NET_CODES.has(x.code));
+            if (sub)
+                return sub.code;
+        }
+    }
+    return undefined;
+}
+/** Console deep-link to enable one API (noob-proofing hint, B10). */
+function apiEnableLink(api) {
+    return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
+}
+/** Extract the disabled API id from an accessNotConfigured / SERVICE_DISABLED
+ * error so the hint can deep-link straight to its enable page. */
+function disabledApiId(message) {
+    const url = message.match(/\/apis\/api\/([a-z0-9-]+)\.googleapis\.com/i);
+    if (url)
+        return url[1].toLowerCase();
+    const named = message.match(/\b([A-Za-z][A-Za-z0-9 ]*?) API has not been used/);
+    if (named)
+        return named[1].trim().toLowerCase().replace(/\s+/g, '');
+    return null;
+}
+export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
     const status = statusOf(error);
     const reason = reasonOf(error);
     const message = messageOf(error);
+    // 7-day Testing-mode trap: a BYO OAuth client in "Testing" status expires
+    // refresh tokens weekly; the dead token surfaces as invalid_grant. Name the
+    // real fix (publish to production) so the agent stops looping on re-auth.
+    // Checked before the generic 401 so it wins on either 400 or 401.
+    const rawError = error?.response?.data?.error;
+    const grantHaystack = [message, reason, typeof rawError === 'string' ? rawError : '', error?.response?.data?.error_description]
+        .filter(Boolean)
+        .join(' ');
+    if ((status === 400 || status === 401) && /invalid_grant/i.test(grantHaystack)) {
+        return {
+            error: 'reauth_required',
+            message,
+            hint: `Refresh token for "${account}" is dead (often the 7-day Testing-mode trap). ` +
+                'Set Publishing status to In production at https://console.cloud.google.com/auth/audience, ' +
+                `then ${reauthHint(account)}`,
+            retriable: false,
+            account,
+        };
+    }
     if (status === 401) {
         return {
             error: 'auth_required',
             message: `Authentication failed for account "${account}".`,
-            hint: `Run: npx mcp-google-multi auth --account ${account}`,
+            hint: reauthHint(account),
             retriable: false,
             account,
         };
     }
     if (status === 403) {
+        // API not enabled for the project: a distinct, self-serve fix (enable the
+        // API) rather than a scope/permission dead-end.
+        const notEnabled = reason === 'accessNotConfigured' ||
+            reason === 'SERVICE_DISABLED' ||
+            /has not been used in project|accessNotConfigured|SERVICE_DISABLED|it is disabled/i.test(message);
+        if (notEnabled) {
+            const api = disabledApiId(message);
+            return {
+                error: 'api_not_enabled',
+                message,
+                hint: api
+                    ? `Enable this API for your project: ${apiEnableLink(api)}`
+                    : 'Enable the API for your project at https://console.cloud.google.com/apis/library',
+                retriable: false,
+                account,
+            };
+        }
         const scopeIssue = reason === 'insufficientPermissions' ||
             reason === 'ACCESS_TOKEN_SCOPE_INSUFFICIENT' ||
             /insufficient.*scope/i.test(message);
         if (scopeIssue) {
+            // #114 three-state enrichment when the method's required scopes are
+            // known (escape hatch / generated tools): state-specific remediation and
+            // an honest retriable so agents stop retrying dead ends.
+            const enriched = scopeContext?.() ?? null;
             return {
                 error: 'insufficient_scope',
                 message,
-                hint: forbiddenHint ?? `Re-auth "${account}" with the scope this operation needs.`,
-                retriable: false,
+                hint: enriched?.hint ?? forbiddenHint ?? `Re-auth "${account}" with the scope this operation needs.`,
+                retriable: enriched?.retriable ?? false,
                 account,
             };
         }
@@ -58,10 +136,23 @@ export function mapGoogleError(error, account, forbiddenHint) {
     if (status !== undefined && status >= 500) {
         return { error: 'upstream_error', message, retriable: true, account };
     }
+    if (status === undefined) {
+        const netCode = netCodeOf(error);
+        if (netCode) {
+            return {
+                error: 'network_error',
+                message: message.includes(netCode) ? message : message.endsWith('reason: ') ? `${message}${netCode}` : `${message} (${netCode})`,
+                hint: `Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
+                    'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.',
+                retriable: RETRIABLE_NET_CODES.has(netCode),
+                account,
+            };
+        }
+    }
     return { error: 'upstream_error', message, retriable: false, account };
 }
-export function handleGoogleApiError(error, account, forbiddenHint) {
-    const envelope = mapGoogleError(error, account, forbiddenHint);
+export function handleGoogleApiError(error, account, forbiddenHint, scopeContext) {
+    const envelope = mapGoogleError(error, account, forbiddenHint, scopeContext);
     return {
         content: [{ type: 'text', text: JSON.stringify(envelope) }],
         isError: true,

package/dist/tools/account-wizard.d.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolRegistry } from '../registry.js';
+export interface AddForm {
+    alias: string;
+    email: string;
+    allBundles: boolean;
+    forms: boolean;
+    chat: boolean;
+    otherBundles: string;
+    admin: boolean;
+}
+/** Every optional bundle (admin is granted via its own checkbox, not here). */
+export declare function allOptionalBundles(): string[];
+/** elicitation/create form schema (flat primitives only, per the MCP spec). */
+export declare function addFormSchema(): Record<string, unknown>;
+export type AddValidation = {
+    ok: true;
+    alias: string;
+    email: string;
+    bundles: string[];
+    admin: boolean;
+} | {
+    ok: false;
+    slug: string;
+    message: string;
+};
+/** Validate the collected form against the alias rules, dup check, and the
+ * bundle catalog. Pure (no I/O) for unit testing. */
+export declare function validateAddForm(input: Partial<AddForm>, existingAliases: string[]): AddValidation;
+/** Scopes requested by the profile but NOT granted at consent (granular
+ * consent / unchecked bundles). Pure. */
+export declare function scopeGrantDiff(requested: string[], grantedScope: string | undefined): string[];
+export declare function registerAccountWizardTools(registry: ToolRegistry, server: McpServer): void;