mcp-google-multi 6.0.0-beta.2 → 6.0.0-beta.4

package/dist/services.d.ts

@@ -1,19 +1,27 @@
-import type { ToolRegistry } from './registry.js';
+import type { AccountSet } from './accounts.js';
+import type { CuratedToolDeps } from './client.js';
+import { type ToolRegistry } from './registry.js';
 export interface ServiceEntry {
     name: string;
-    register: (registry: ToolRegistry) => void;
-    enabled?: () => boolean;
+    register: (registry: ToolRegistry, deps?: CuratedToolDeps) => void;
+    /** Absent = always on. Gates evaluate against the PASSED account set (the
+     * calling tenant's view); omitted set = the global registry, today's
+     * behavior. */
+    enabled?: (set?: AccountSet) => boolean;
 }
 export declare const SERVICES: ServiceEntry[];
 export declare const GENERATED_GATES: Record<string, {
-    enabled: () => boolean;
+    enabled: (set?: AccountSet) => boolean;
     hint: string;
 }>;
+/** Message for a `tools/call` naming a tool that is not registered: the SDK's
+ * bare "Tool X not found" reads identically for a typo, a gated service, and
+ * an unknown API, but the server knows which is which from its boot-time enabled-service list. */
+export declare function unknownToolMessage(registry: ToolRegistry, rawName: string): string;
 /**
- * Message for a `tools/call` naming a tool that is not registered. The SDK's
- * own answer is a bare "Tool X not found", which reads identically for a typo,
- * for a service gated behind a scope bundle, and for an API this server has
- * never heard of. Those need different next steps, and the server knows which
- * is which: it composed the enabled-service list at boot.
+ * Gated services the registry's CURRENT accounts enable but that registered
+ * nothing: an account added mid-session unlocked them after buildRegistry
+ * decided the gates. Mirrors compose.ts gate for gate, so an ungated or
+ * toolset-excluded service is never reported.
  */
-export declare function unknownToolMessage(registry: ToolRegistry, name: string): string;
+export declare function servicesAwaitingRestart(registry: ToolRegistry): string[];

package/dist/services.js

@@ -13,8 +13,12 @@ import { registerChatTools } from './tools/chat.js';
 import { registerAdminTools } from './tools/admin.js';
 import { registerAnalyticsTools } from './tools/analytics.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
+import { serviceOf } from './registry.js';
+import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { GENERATED_SERVICES } from './tools/generated/index.js';
 import { suggestKeys } from './arg-strict.js';
+import { sliceClean } from './trim.js';
+import { hints } from './hint-provider.js';
 export const SERVICES = [
     { name: 'gmail', register: registerGmailTools },
     { name: 'drive', register: registerDriveTools },
@@ -25,16 +29,16 @@ export const SERVICES = [
     { name: 'searchconsole', register: registerSearchConsoleTools },
     { name: 'tasks', register: registerTasksTools },
     { name: 'meet', register: registerMeetTools },
-    { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
-    { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
-    { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
-    { name: 'analytics', register: registerAnalyticsTools, enabled: () => { const b = new Set(getOptionalBundles()); return b.has('analytics') || b.has('analytics_write'); } },
-    { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
+    { name: 'slides', register: registerSlidesTools, enabled: (set) => new Set(getOptionalBundles(set)).has('slides') },
+    { name: 'forms', register: registerFormsTools, enabled: (set) => new Set(getOptionalBundles(set)).has('forms') },
+    { name: 'chat', register: registerChatTools, enabled: (set) => new Set(getOptionalBundles(set)).has('chat') },
+    { name: 'analytics', register: registerAnalyticsTools, enabled: (set) => { const b = new Set(getOptionalBundles(set)); return b.has('analytics') || b.has('analytics_write'); } },
+    { name: 'admin', register: registerAdminTools, enabled: (set) => getAdminAccounts(set).length > 0 },
 ];
 // Generated-only services with opt-in scopes; admin/forms/chat/analytics reuse their curated gate in buildRegistry,
 // and workspaceevents is deliberately absent — no dedicated scope (subscriptions use resource scopes).
 const bundleGate = (name) => ({
-    enabled: () => new Set(getOptionalBundles()).has(name),
+    enabled: (set) => new Set(getOptionalBundles(set)).has(name),
     hint: `add "${name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`,
 });
 export const GENERATED_GATES = {
@@ -53,26 +57,61 @@ export const GENERATED_GATES = {
     script: bundleGate('script'),
     vault: bundleGate('vault'),
 };
-/**
- * Message for a `tools/call` naming a tool that is not registered. The SDK's
- * own answer is a bare "Tool X not found", which reads identically for a typo,
- * for a service gated behind a scope bundle, and for an API this server has
- * never heard of. Those need different next steps, and the server knows which
- * is which: it composed the enabled-service list at boot.
- */
-export function unknownToolMessage(registry, name) {
-    const near = suggestKeys(name, registry.toolNames(), 3);
-    if (near.length > 0)
-        return `Tool ${name} not found. Did you mean: ${near.join(', ')}?`;
-    // A service that EXISTS in the build but registered nothing is gated, not
-    // misspelled, and the fix is a scope bundle rather than a different name.
-    const service = name.split('_')[0];
+const MAX_TOOL_NAME_ECHO = 64;
+/** Message for a `tools/call` naming a tool that is not registered: the SDK's
+ * bare "Tool X not found" reads identically for a typo, a gated service, and
+ * an unknown API, but the server knows which is which from its boot-time enabled-service list. */
+export function unknownToolMessage(registry, rawName) {
+    // The name is the caller's, unvalidated: echo a bounded prefix only.
+    const name = rawName.length > MAX_TOOL_NAME_ECHO ? `${sliceClean(rawName, MAX_TOOL_NAME_ECHO)}...` : rawName;
+    // A service that EXISTS but registered nothing is off, not misspelled;
+    // checked before the did-you-mean, which would otherwise point chat_spaces_get at meet_spaces_get.
+    const service = serviceOf(name);
     const known = SERVICES.some((s) => s.name === service) || GENERATED_SERVICES.some((s) => s.name === service);
     if (known && !registry.services().includes(service)) {
-        const hint = service === 'admin'
+        const aliases = registry.accountSet().aliases;
+        if (!toolsetEnabled(getToolsets(), service)) {
+            const rendered = hints()?.render({ kind: 'service_not_enabled', tool: name, service, aliases, admin: false, toolsetOff: true, awaitingRestart: false });
+            return rendered?.hint ?? `Tool ${name} not found: the "${service}" service is turned off in this deployment (GOOGLE_TOOLSETS).`;
+        }
+        if (servicesAwaitingRestart(registry).includes(service)) {
+            const rendered = hints()?.render({ kind: 'service_not_enabled', tool: name, service, aliases, admin: false, toolsetOff: false, awaitingRestart: true });
+            return rendered?.hint ?? `Tool ${name} not found: the "${service}" service was enabled after this server started, and tools register at startup. Restart the server to use them. Until then, google_api_call can reach the same API.`;
+        }
+        const isAdmin = service === 'admin';
+        const hint = isAdmin
             ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS), then re-auth'
             : (GENERATED_GATES[service]?.hint ?? `add "${service}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES), then re-auth`);
-        return `Tool ${name} not found: the "${service}" service is not enabled in this deployment. To enable it, ${hint}. Until then, google_api_call can reach the same API.`;
+        const rendered = hints()?.render({
+            kind: 'service_not_enabled',
+            tool: name,
+            service,
+            bundle: isAdmin ? undefined : service,
+            aliases,
+            admin: isAdmin,
+            toolsetOff: false,
+            awaitingRestart: false,
+        });
+        return rendered?.hint ?? `Tool ${name} not found: the "${service}" service is not enabled in this deployment. To enable it, ${hint}. Until then, google_api_call can reach the same API.`;
     }
+    const near = suggestKeys(rawName, registry.toolNames(), 3);
+    if (near.length > 0)
+        return `Tool ${name} not found. Did you mean: ${near.join(', ')}?`;
     return `Tool ${name} not found. Call {service}_discover to list a service's tools, or google_api_search to find a method on any Google API.`;
 }
+/**
+ * Gated services the registry's CURRENT accounts enable but that registered
+ * nothing: an account added mid-session unlocked them after buildRegistry
+ * decided the gates. Mirrors compose.ts gate for gate, so an ungated or
+ * toolset-excluded service is never reported.
+ */
+export function servicesAwaitingRestart(registry) {
+    const toolsets = getToolsets();
+    const registered = new Set(registry.services());
+    const live = registry.accountSet();
+    const names = [...new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((g) => g.name)])];
+    return names.filter((n) => {
+        const gate = SERVICES.find((s) => s.name === n)?.enabled ?? GENERATED_GATES[n]?.enabled;
+        return gate !== undefined && toolsetEnabled(toolsets, n) && !registered.has(n) && gate(live);
+    });
+}

package/dist/ssrf-guard.d.ts

@@ -1,6 +1,12 @@
 export declare class SsrfBlockedError extends Error {
     constructor(message: string);
 }
+/** A non-2xx answer, kept apart so the cache can tell an issuer that is
+ * overloaded for now from one that says the document is gone. */
+export declare class CimdHttpError extends SsrfBlockedError {
+    readonly status: number;
+    constructor(status: number);
+}
 /** True if an IPv4 literal is in a blocked (private/link-local/loopback/etc) range. */
 export declare function isBlockedIPv4(ip: string): boolean;
 /** True if an IPv6 literal is blocked. */
@@ -10,28 +16,35 @@ export interface SsrfDeps {
     /** Injectable resolver (defaults to dns.lookup all-addresses) for tests. */
     resolveAll?: (host: string) => Promise<string[]>;
 }
+/** The most lookups started here that may be unsettled at once, abandoned ones included; process-wide, as the libuv threadpool is. */
+export declare const MAX_UNSETTLED_LOOKUPS = 4;
 /**
  * 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.
+ * the host resolves to is public. Throws SsrfBlockedError otherwise, except
+ * that a resolver error with a transient code (a lookup that could not answer
+ * this time) is rethrown as is. 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.
+ * fetching, and fetchCimdDocument follows no redirect, so no hop leaves it),
+ * 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 declare function assertPublicHttpsUrl(rawUrl: string, deps?: SsrfDeps): Promise<{
     url: URL;
     addresses: string[];
 }>;
 export interface CimdFetchOptions {
+    /** Default 5120: CIMD section 8.7 recommends at most 5 KB. */
     maxBytes?: number;
+    /** One attempt's cap, never past what is left of deadlineMs (default 5000). */
     timeoutMs?: number;
-    maxRedirects?: number;
-    /** Transient-network-error retries per hop (default 2 → up to 3 attempts). */
+    /** One budget for every attempt, DNS lookups and backoff included (default 8000). */
+    deadlineMs?: number;
+    /** Transient-network-error retries (default 1, so at most 2 attempts). */
     retries?: number;
     /** Base backoff between retries in ms; grows linearly per attempt (default 200). */
     retryBackoffMs?: number;
@@ -40,9 +53,10 @@ export interface CimdFetchOptions {
     sleepImpl?: (ms: number) => Promise<void>;
     ssrf?: SsrfDeps;
 }
+export declare function isTransientFetchError(e: unknown): boolean;
 /**
- * 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.
+ * SSRF-guarded fetch of a CIMD client-metadata document (JSON): HTTPS and
+ * public-IP checked, no redirect followed, size-capped, and every attempt
+ * inside one deadline. Returns the parsed JSON object.
  */
 export declare function fetchCimdDocument(rawUrl: string, opts?: CimdFetchOptions): Promise<Record<string, unknown>>;

package/dist/ssrf-guard.js

@@ -1,8 +1,5 @@
-// 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.
+// SSRF guard for every server-side fetch (the CIMD client_id doc): HTTPS-only,
+// resolve-then-check ALL addresses (anti-rebind), no redirects, capped size/time.
 import { lookup } from 'node:dns/promises';
 import { isIPv4, isIPv6, BlockList } from 'node:net';
 export class SsrfBlockedError extends Error {
@@ -11,6 +8,16 @@ export class SsrfBlockedError extends Error {
         this.name = 'SsrfBlockedError';
     }
 }
+/** A non-2xx answer, kept apart so the cache can tell an issuer that is
+ * overloaded for now from one that says the document is gone. */
+export class CimdHttpError extends SsrfBlockedError {
+    status;
+    constructor(status) {
+        super(`CIMD fetch failed: HTTP ${status}`);
+        this.name = 'CimdHttpError';
+        this.status = status;
+    }
+}
 /** 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);
@@ -35,10 +42,8 @@ export function isBlockedIPv4(ip) {
         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).
+// Built-in subnet math blocks v4-mapped/NAT64/6to4 embeddings too: a public
+// host never resolves to those, so the whole range closes the embedding gap.
 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
@@ -61,25 +66,45 @@ export function isBlockedIp(ip) {
         return isBlockedIPv6(ip);
     return true; // unparseable → block
 }
+/** The most lookups started here that may be unsettled at once, abandoned ones included; process-wide, as the libuv threadpool is. */
+export const MAX_UNSETTLED_LOOKUPS = 4;
+let unsettledLookups = 0;
+/** The lookup cap refused to start one: transient for the cache, but never retried, since the hung lookups it waits on outlast any backoff. */
+class LookupBusyError extends Error {
+    code = 'EAI_AGAIN';
+}
 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);
+    // getaddrinfo keeps its thread until it returns, even once no attempt waits
+    // on it, so a new lookup past the cap would only queue behind the hung ones.
+    if (unsettledLookups >= MAX_UNSETTLED_LOOKUPS) {
+        throw new LookupBusyError(`DNS lookup for ${host} not started: ${MAX_UNSETTLED_LOOKUPS} earlier lookups have not returned`);
+    }
+    unsettledLookups++;
+    try {
+        const results = await lookup(host, { all: true });
+        return results.map((r) => r.address);
+    }
+    finally {
+        unsettledLookups--;
+    }
 }
 /**
  * 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.
+ * the host resolves to is public. Throws SsrfBlockedError otherwise, except
+ * that a resolver error with a transient code (a lookup that could not answer
+ * this time) is rethrown as is. 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.
+ * fetching, and fetchCimdDocument follows no redirect, so no hop leaves it),
+ * 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;
@@ -98,6 +123,11 @@ export async function assertPublicHttpsUrl(rawUrl, deps = {}) {
         addresses = await resolveAll(url.hostname);
     }
     catch (e) {
+        // A resolver that could not answer this time says nothing about the host,
+        // so the fetch may retry it; a name that does not exist stays a block.
+        const code = e?.code;
+        if (typeof code === 'string' && TRANSIENT_CODES.has(code))
+            throw e;
         throw new SsrfBlockedError(`DNS resolution failed for ${url.hostname}: ${e.message}`);
     }
     if (addresses.length === 0)
@@ -109,10 +139,8 @@ export async function assertPublicHttpsUrl(rawUrl, deps = {}) {
     }
     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.
+// Connection-level failures a retry can recover from; an SSRF block, a bad
+// HTTP status, or malformed JSON are deterministic and must NOT be retried.
 const TRANSIENT_CODES = new Set([
     'ETIMEDOUT',
     'ECONNRESET',
@@ -124,7 +152,7 @@ const TRANSIENT_CODES = new Set([
     'UND_ERR_CONNECT_TIMEOUT',
     'UND_ERR_SOCKET',
 ]);
-function isTransientFetchError(e) {
+export function isTransientFetchError(e) {
     if (e instanceof SsrfBlockedError)
         return false; // deterministic security/shape reject
     const name = e?.name;
@@ -134,83 +162,83 @@ function isTransientFetchError(e) {
     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.
+    // undici's TypeError('fetch failed') retries even with no useful .cause code.
     if (e instanceof TypeError && /fetch failed/i.test(e.message))
         return true;
     return false;
 }
+// dns.lookup cannot be cancelled, so an attempt stops waiting on it instead.
+function untilAborted(work, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        void work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
 /**
- * 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.
+ * SSRF-guarded fetch of a CIMD client-metadata document (JSON): HTTPS and
+ * public-IP checked, no redirect followed, size-capped, and every attempt
+ * inside one deadline. Returns the parsed JSON object.
  */
 export async function fetchCimdDocument(rawUrl, opts = {}) {
-    const maxBytes = opts.maxBytes ?? 64 * 1024;
+    const maxBytes = opts.maxBytes ?? 5120;
     const timeoutMs = opts.timeoutMs ?? 5000;
-    const maxRedirects = opts.maxRedirects ?? 3;
-    const retries = opts.retries ?? 2;
+    const deadline = Date.now() + (opts.deadlineMs ?? 8000);
+    const retries = opts.retries ?? 1;
     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);
+    // Each attempt re-runs resolve-then-check so a retry can't skip the
+    // anti-rebind guard; the timer is per-attempt, armed across lookup and body read.
+    for (let attempt = 0;; attempt++) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, Math.max(0, Math.min(timeoutMs, deadline - Date.now())));
+        try {
+            await untilAborted(assertPublicHttpsUrl(rawUrl, opts.ssrf), controller.signal);
+            const res = await doFetch(rawUrl, { redirect: 'manual', signal: controller.signal, headers: { accept: 'application/json' } });
+            // CIMD section 5: a redirect is never followed. Only this URL passed the
+            // issuer allowlist, and a document behind a redirect could claim its client_id.
+            if (res.status >= 300 && res.status < 400)
+                throw new SsrfBlockedError('CIMD redirect refused');
+            if (!res.ok)
+                throw new CimdHttpError(res.status);
+            const text = await readCapped(res, maxBytes, controller);
+            let parsed;
             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;
+                parsed = JSON.parse(text);
             }
-            catch (e) {
-                if (attempt < retries && isTransientFetchError(e)) {
-                    await sleep(backoffMs * (attempt + 1));
-                    continue;
-                }
-                throw e;
+            catch {
+                throw new SsrfBlockedError('CIMD document is not valid JSON');
             }
-            finally {
-                clearTimeout(timer);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new SsrfBlockedError('CIMD document is not a JSON object');
+            }
+            return parsed;
+        }
+        catch (e) {
+            // A refused status throws with the body unread, and only an abort hands
+            // that connection back; the controller is this attempt's alone.
+            controller.abort();
+            const wait = backoffMs * (attempt + 1);
+            // A timed-out attempt may leave a lookup hung on the threadpool, ours or
+            // fetch's own at connect time, and a retry would start another beside it.
+            if (!timedOut && !(e instanceof LookupBusyError) && attempt < retries && isTransientFetchError(e) && deadline - Date.now() > wait) {
+                await sleep(wait);
+                continue;
             }
+            throw e;
         }
-        if (redirectTo !== null) {
-            current = new URL(redirectTo, current).toString();
-            continue;
+        finally {
+            clearTimeout(timer);
         }
-        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). */
+// Aborts the moment maxBytes is exceeded (never buffers an oversized body);
+// falls back to a capped arrayBuffer when there's no readable stream (e.g. a test Response).
 async function readCapped(res, maxBytes, controller) {
     const reader = res.body?.getReader?.();
     if (!reader) {

package/dist/tenant-purge.d.ts

@@ -0,0 +1,26 @@
+import type { TokenData } from './types.js';
+/** Best-effort Google-side revocation (RFC 7009 endpoint). Returns whether
+ * Google acknowledged; NEVER throws — a network failure must not block the
+ * local purge (the local copy is the thing we control). */
+export declare function revokeGoogleToken(tokenData: {
+    refresh_token?: string;
+    access_token?: string;
+}, fetchFn?: typeof fetch): Promise<boolean>;
+export interface TenantTokenPurge {
+    /** Aliases whose .enc files were removed. */
+    removed: string[];
+    /** How many tokens Google acknowledged revoking (best-effort). */
+    revoked: number;
+}
+/** Remove every `.enc` under the tenant's token dir, optionally revoking each
+ * at Google first. Decrypt failures still purge the file — an unreadable
+ * token is exactly the thing to delete. Only THIS tenant's dir is touched. */
+export declare function purgeTenantTokens(tenantId: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    revoke?: (t: TokenData) => Promise<boolean>;
+    resolveKey?: () => string;
+}): Promise<TenantTokenPurge>;
+/** Remove the whole tenants/<id> directory (config + tokens). The id is
+ * validated by the path helper, so a traversal-shaped id throws before any
+ * filesystem access. */
+export declare function removeTenantDir(tenantId: string, env?: NodeJS.ProcessEnv): void;

package/dist/tenant-purge.js

@@ -0,0 +1,65 @@
+// Tenant offboarding primitives: core owns the reusable token-purge legs;
+// orchestration (what to purge, in what order) lives with the tenancy module calling these.
+import fs from 'node:fs';
+import path from 'node:path';
+import { tenantConfigFilePath, tenantTokenDir } from './config-file.js';
+import { createTokenStore } from './token-store.js';
+/** Best-effort Google-side revocation (RFC 7009 endpoint). Returns whether
+ * Google acknowledged; NEVER throws — a network failure must not block the
+ * local purge (the local copy is the thing we control). */
+export async function revokeGoogleToken(tokenData, fetchFn = fetch) {
+    const token = tokenData.refresh_token ?? tokenData.access_token;
+    if (!token)
+        return false;
+    try {
+        const res = await fetchFn('https://oauth2.googleapis.com/revoke', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ token }).toString(),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove every `.enc` under the tenant's token dir, optionally revoking each
+ * at Google first. Decrypt failures still purge the file — an unreadable
+ * token is exactly the thing to delete. Only THIS tenant's dir is touched. */
+export async function purgeTenantTokens(tenantId, opts = {}) {
+    const dir = tenantTokenDir(tenantId, opts.env);
+    const store = createTokenStore(dir, { tenantId, resolveKey: opts.resolveKey });
+    const removed = [];
+    let revoked = 0;
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { removed, revoked }; // no token dir = nothing to purge
+    }
+    for (const name of names) {
+        if (!name.endsWith('.enc'))
+            continue;
+        const alias = name.slice(0, -'.enc'.length);
+        if (opts.revoke) {
+            try {
+                const token = store.readToken(alias);
+                if (token && (await opts.revoke(token)))
+                    revoked += 1;
+            }
+            catch {
+                // undecryptable or invalid-alias filename: still remove the file
+            }
+        }
+        fs.rmSync(path.join(dir, name), { force: true });
+        removed.push(alias);
+    }
+    return { removed, revoked };
+}
+/** Remove the whole tenants/<id> directory (config + tokens). The id is
+ * validated by the path helper, so a traversal-shaped id throws before any
+ * filesystem access. */
+export function removeTenantDir(tenantId, env) {
+    fs.rmSync(path.dirname(tenantConfigFilePath(tenantId, env)), { recursive: true, force: true });
+}

package/dist/token-store.d.ts

@@ -1,8 +1,26 @@
 import type { TokenData } from './types.js';
 export declare function deriveKey(masterKey: string): Buffer;
-export declare function encryptToken(data: object, masterKey: string): string;
-export declare function decryptToken(fileContents: string, masterKey: string): TokenData;
+export declare function deriveTenantKey(masterKey: string, tenantId: string): Buffer;
+export declare function encryptToken(data: object, masterKey: string, tenantId?: string): string;
+export declare function decryptToken(fileContents: string, masterKey: string, tenantId?: string): TokenData;
 export declare function readToken(alias: string): TokenData | null;
 export declare function writeToken(alias: string, data: object): void;
 export declare function updateToken(alias: string, updates: object): void;
 export declare function hasToken(alias: string): boolean;
+export interface TokenStore {
+    readToken(alias: string): TokenData | null;
+    writeToken(alias: string, data: object): void;
+    updateToken(alias: string, updates: object): void;
+    hasToken(alias: string): boolean;
+}
+/**
+ * Context-scoped token store: `.enc` files live under `dir`, ciphertext keyed
+ * by `tenantId` when present (HKDF v2 envelope; omitted = the single-owner v1
+ * envelope). Same lock + atomic-write + error contract as the module-level
+ * functions: readToken returns null ONLY when the file is missing and throws
+ * on a decrypt failure.
+ */
+export declare function createTokenStore(dir: string, opts?: {
+    tenantId?: string;
+    resolveKey?: () => string;
+}): TokenStore;

package/dist/tools/_coerce.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
-export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
+export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPreprocess<z.ZodArray<T>, unknown>;
+export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T, unknown>;
 /** Numeric args arrive string-encoded from some clients. Arg normalization
  * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
  * sent under the correct key never passes through it and the coercion has to
  * live in the schema. */
-export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
-export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;
+export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T, unknown>;
+export declare const coerceBoolean: z.ZodPreprocess<z.ZodBoolean, unknown>;