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

package/dist/scope-catalog.js

@@ -0,0 +1,182 @@
+// The curated bundle catalog: ONE source of truth consumed by the wizard
+// picker, scope observability (#114) hints, and docs. Keys are a frozen
+// public API (config.json references them by name) — renames go through
+// BUNDLE_ALIASES, never in place.
+export const ADMIN_SCOPES = [
+    'https://www.googleapis.com/auth/admin.reports.audit.readonly',
+    'https://www.googleapis.com/auth/admin.directory.user',
+    'https://www.googleapis.com/auth/admin.directory.group.readonly',
+    'https://www.googleapis.com/auth/admin.directory.group.member.readonly',
+];
+export const BUNDLE_CATALOG = {
+    slides: {
+        scopes: ['https://www.googleapis.com/auth/presentations'],
+        description: 'Create and edit Google Slides presentations.',
+        risk: 'low',
+    },
+    forms: {
+        scopes: [
+            'https://www.googleapis.com/auth/forms.body',
+            'https://www.googleapis.com/auth/forms.responses.readonly',
+        ],
+        description: 'Build Google Forms and read their responses.',
+        risk: 'medium',
+    },
+    chat: {
+        scopes: [
+            'https://www.googleapis.com/auth/chat.spaces',
+            'https://www.googleapis.com/auth/chat.messages',
+            'https://www.googleapis.com/auth/chat.messages.create',
+        ],
+        description: 'Read and send Google Chat messages and manage spaces (Workspace accounts).',
+        risk: 'medium',
+    },
+    // These extend the always-on gmail service: users.settings.* writes require
+    // them (reads already work via gmail.modify); sharing is split out as riskier.
+    gmail_settings: {
+        scopes: ['https://www.googleapis.com/auth/gmail.settings.basic'],
+        description: 'Change mailbox settings: filters, labels, vacation responder.',
+        risk: 'medium',
+    },
+    gmail_settings_sharing: {
+        scopes: ['https://www.googleapis.com/auth/gmail.settings.sharing'],
+        description: 'Manage forwarding addresses and delegates — can route mail out of the mailbox.',
+        risk: 'high',
+    },
+    classroom: {
+        scopes: [
+            'https://www.googleapis.com/auth/classroom.courses',
+            'https://www.googleapis.com/auth/classroom.coursework.me',
+            'https://www.googleapis.com/auth/classroom.coursework.students',
+            'https://www.googleapis.com/auth/classroom.courseworkmaterials',
+            'https://www.googleapis.com/auth/classroom.rosters',
+            'https://www.googleapis.com/auth/classroom.announcements',
+            'https://www.googleapis.com/auth/classroom.topics',
+        ],
+        description: 'Manage Classroom courses, coursework, rosters and announcements.',
+        risk: 'medium',
+    },
+    cloudidentity: {
+        scopes: [
+            'https://www.googleapis.com/auth/cloud-identity.groups',
+            'https://www.googleapis.com/auth/cloud-identity.devices',
+        ],
+        description: 'Manage Cloud Identity groups and devices across the directory.',
+        risk: 'high',
+    },
+    cloudsearch: {
+        scopes: ['https://www.googleapis.com/auth/cloud_search'],
+        description: 'Query Google Cloud Search across Workspace content.',
+        risk: 'medium',
+    },
+    vault: {
+        scopes: ['https://www.googleapis.com/auth/ediscovery'],
+        description: 'Google Vault eDiscovery: matters, holds and exports over the whole domain.',
+        risk: 'high',
+        workspaceOnly: true,
+    },
+    keep: {
+        scopes: ['https://www.googleapis.com/auth/keep'],
+        description: 'Read and edit Google Keep notes.',
+        risk: 'low',
+    },
+    driveactivity: {
+        scopes: ['https://www.googleapis.com/auth/drive.activity.readonly'],
+        description: 'Read the Drive activity feed (who did what, when).',
+        risk: 'low',
+    },
+    drivelabels: {
+        scopes: [
+            'https://www.googleapis.com/auth/drive.labels',
+            'https://www.googleapis.com/auth/drive.admin.labels',
+        ],
+        description: 'Manage Drive labels, including admin label taxonomy.',
+        risk: 'medium',
+    },
+    script: {
+        scopes: [
+            'https://www.googleapis.com/auth/script.projects',
+            'https://www.googleapis.com/auth/script.deployments',
+            'https://www.googleapis.com/auth/script.processes',
+            'https://www.googleapis.com/auth/script.metrics',
+        ],
+        description: 'Manage Apps Script projects and deployments.',
+        risk: 'medium',
+    },
+    postmaster: {
+        scopes: ['https://www.googleapis.com/auth/postmaster.readonly'],
+        description: 'Read Gmail Postmaster Tools deliverability data.',
+        risk: 'low',
+    },
+    groupssettings: {
+        scopes: ['https://www.googleapis.com/auth/apps.groups.settings'],
+        description: 'Change Google Groups settings for the domain.',
+        risk: 'medium',
+    },
+    groupsmigration: {
+        scopes: ['https://www.googleapis.com/auth/apps.groups.migration'],
+        description: 'Migrate archived messages into Google Groups.',
+        risk: 'high',
+    },
+    licensing: {
+        scopes: ['https://www.googleapis.com/auth/apps.licensing'],
+        description: 'Assign and revoke Workspace license seats.',
+        risk: 'high',
+    },
+    reseller: {
+        scopes: ['https://www.googleapis.com/auth/apps.order'],
+        description: 'Manage reseller customer subscriptions and orders.',
+        risk: 'high',
+    },
+    appsmarket: {
+        scopes: ['https://www.googleapis.com/auth/appsmarketplace.license'],
+        description: 'Read Marketplace app license assignments.',
+        risk: 'high',
+    },
+    admin: {
+        scopes: ADMIN_SCOPES,
+        description: 'Workspace admin: user directory management and audit reports.',
+        risk: 'high',
+        workspaceOnly: true,
+    },
+};
+/** One-way soft-rename map (UD5): empty at 6.0.0; the mechanism ships now so a
+ * future rename is a deprecation warning, never a breaking config change. */
+export const BUNDLE_ALIASES = {};
+const warnedAliases = new Set();
+export function resolveBundleAliases(bundles) {
+    return bundles.map((name) => {
+        const target = BUNDLE_ALIASES[name];
+        if (!target)
+            return name;
+        if (!warnedAliases.has(name)) {
+            warnedAliases.add(name);
+            process.stderr.write(`WARN: bundle "${name}" is deprecated; use "${target}".\n`);
+        }
+        return target;
+    });
+}
+/** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
+export function closestBundle(name) {
+    let best;
+    let bestDist = 3;
+    for (const key of Object.keys(BUNDLE_CATALOG)) {
+        const d = editDistance(name.toLowerCase(), key);
+        if (d < bestDist) {
+            bestDist = d;
+            best = key;
+        }
+    }
+    return best;
+}
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return dp[a.length][b.length];
+}

package/dist/scope-observability.d.ts

@@ -0,0 +1,78 @@
+import { resolveScopesForAccount } from './auth.js';
+import { readToken } from './token-store.js';
+export type ScopeState = 'callable' | 'requestable_not_granted' | 'not_requestable';
+export type NotRequestableReason = 'add_bundle' | 'account_type' | 'unknown_scope';
+export interface ScopeClassification {
+    state: ScopeState;
+    reason?: NotRequestableReason;
+    bundle?: string;
+    alsoIn?: string[];
+}
+export declare function classifyScope(scope: string, granted: ReadonlySet<string>, profile: ReadonlySet<string>): ScopeClassification;
+export interface MethodScopeClassification {
+    state: ScopeState;
+    /** The alternative that achieved the best state — hint and classification
+     * always refer to this SAME scope. */
+    scope: string;
+    classification: ScopeClassification;
+}
+/**
+ * Discovery `method.scopes` is an ANY-OF list: holding any ONE listed scope
+ * authorizes the call. The method's state is therefore the BEST state among
+ * the alternatives (a catalog-unknown alternative like chat.bot must never
+ * mask a requestable one), and the remediation targets the cheapest fix.
+ */
+export declare function classifyMethodScopes(alternatives: readonly string[], granted: ReadonlySet<string>, profile: ReadonlySet<string>): MethodScopeClassification | null;
+/**
+ * gh-CLI-style copy-pasteable remediation. Never promises a delta-only consent
+ * screen (Google re-lists everything at re-consent).
+ */
+export declare function scopeHint(scope: string, c: ScopeClassification, alias: string): {
+    hint: string;
+    retriable: boolean;
+};
+export interface AccountScopeSets {
+    granted: Set<string>;
+    profile: Set<string>;
+}
+/** Best-effort per-account sets; null when the token/profile is unreadable
+ * (decrypt error, missing token) — callers fall back to generic hints. */
+export declare function accountScopeSets(alias: string, deps?: {
+    readTokenFn?: typeof readToken;
+    profileFn?: typeof resolveScopesForAccount;
+}): AccountScopeSets | null;
+/**
+ * Runtime enrichment for a scope 403 on a method whose required scopes are
+ * known (escape hatch: runtime Discovery; generated tools: baked). The
+ * account_type refinement lives here: a 403 on an admin scope that IS in the
+ * profile means Google refuses it for this account type (personal Gmail),
+ * so re-auth would loop — report the dead end instead.
+ */
+export declare function scopeHintForMethod(required: readonly string[], alias: string, deps?: Parameters<typeof accountScopeSets>[1]): {
+    hint: string;
+    retriable: boolean;
+} | null;
+export interface ScopesReport {
+    configured: number;
+    granted: number;
+    callable: string[];
+    requestable: string[];
+    notRequestable: {
+        addBundle: {
+            scope: string;
+            bundle: string;
+        }[];
+        /** Runtime-signal bucket: static classification cannot prove account
+         * type; doctor (B9) fills it from observed persistent admin 403s. */
+        accountType: string[];
+        unknown: string[];
+    };
+    missing: string[];
+}
+/**
+ * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
+ * required by REGISTERED tools ("registered but not requestable" is the
+ * original #114 ask).
+ */
+export declare function buildScopesReport(granted: ReadonlySet<string>, profile: ReadonlySet<string>, registeredScopes?: Iterable<string>): ScopesReport;
+export declare function clearScopeIndexForTest(): void;

package/dist/scope-observability.js

@@ -0,0 +1,192 @@
+import { ADMIN_SCOPES, BUNDLE_CATALOG } from './scope-catalog.js';
+import { BASE_SCOPES, resolveScopesForAccount } from './auth.js';
+import { readToken } from './token-store.js';
+// Reverse index scope -> bundles offering it, narrowest bundle first (fewest
+// scopes) so the remediation names the smallest grant. BASE_SCOPES map to the
+// pseudo-bundle "base" (outside a profile only via includesBase:false).
+let reverseIndex = null;
+function scopeIndex() {
+    if (reverseIndex)
+        return reverseIndex;
+    const idx = new Map();
+    const add = (scope, bundle) => {
+        const list = idx.get(scope) ?? [];
+        list.push(bundle);
+        idx.set(scope, list);
+    };
+    for (const [name, entry] of Object.entries(BUNDLE_CATALOG)) {
+        for (const scope of entry.scopes)
+            add(scope, name);
+    }
+    for (const scope of BASE_SCOPES)
+        add(scope, 'base');
+    const size = (b) => (b === 'base' ? BASE_SCOPES.length : BUNDLE_CATALOG[b].scopes.length);
+    for (const list of idx.values())
+        list.sort((a, b) => size(a) - size(b) || a.localeCompare(b));
+    reverseIndex = idx;
+    return idx;
+}
+export function classifyScope(scope, granted, profile) {
+    if (granted.has(scope))
+        return { state: 'callable' };
+    if (profile.has(scope))
+        return { state: 'requestable_not_granted' };
+    const bundles = scopeIndex().get(scope);
+    if (bundles && bundles.length > 0) {
+        return {
+            state: 'not_requestable',
+            reason: 'add_bundle',
+            bundle: bundles[0],
+            ...(bundles.length > 1 ? { alsoIn: bundles.slice(1) } : {}),
+        };
+    }
+    return { state: 'not_requestable', reason: 'unknown_scope' };
+}
+const STATE_ORDER = {
+    callable: 0,
+    requestable_not_granted: 1,
+    not_requestable: 2,
+};
+/**
+ * Discovery `method.scopes` is an ANY-OF list: holding any ONE listed scope
+ * authorizes the call. The method's state is therefore the BEST state among
+ * the alternatives (a catalog-unknown alternative like chat.bot must never
+ * mask a requestable one), and the remediation targets the cheapest fix.
+ */
+export function classifyMethodScopes(alternatives, granted, profile) {
+    let best = null;
+    for (const scope of alternatives) {
+        const c = classifyScope(scope, granted, profile);
+        if (!best || STATE_ORDER[c.state] < STATE_ORDER[best.classification.state]) {
+            best = { state: c.state, scope, classification: c };
+        }
+        if (best.state === 'callable')
+            break;
+    }
+    return best;
+}
+/**
+ * gh-CLI-style copy-pasteable remediation. Never promises a delta-only consent
+ * screen (Google re-lists everything at re-consent).
+ */
+export function scopeHint(scope, c, alias) {
+    switch (c.state) {
+        case 'requestable_not_granted':
+            return {
+                hint: `Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
+                    `Re-grant: npx mcp-google-multi auth --account ${alias}`,
+                retriable: true,
+            };
+        case 'not_requestable':
+            if (c.reason === 'add_bundle') {
+                // "base" is a pseudo-bundle (BASE_SCOPES excluded by includesBase:
+                // false), NOT a catalog key — telling users to add it to bundles[]
+                // would fail boot with E_UNKNOWN_BUNDLE.
+                if (c.bundle === 'base') {
+                    return {
+                        hint: `Scope ${scope} is a base scope excluded by "includesBase": false in ${alias}'s profile. ` +
+                            `Set includesBase back to true (or remove it) in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                        retriable: false,
+                    };
+                }
+                return {
+                    hint: `Scope ${scope} needs the "${c.bundle}" bundle, which is not in ${alias}'s profile. ` +
+                        `Add it: set ${alias}'s profile bundles to include "${c.bundle}" in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                    retriable: false,
+                };
+            }
+            if (c.reason === 'account_type') {
+                return {
+                    hint: `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    retriable: false,
+                };
+            }
+            return {
+                hint: `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. Do not retry.`,
+                retriable: false,
+            };
+        default:
+            return { hint: '', retriable: true };
+    }
+}
+/** Best-effort per-account sets; null when the token/profile is unreadable
+ * (decrypt error, missing token) — callers fall back to generic hints. */
+export function accountScopeSets(alias, deps = {}) {
+    try {
+        const token = (deps.readTokenFn ?? readToken)(alias);
+        const granted = new Set(typeof token?.scope === 'string' ? token.scope.split(' ').filter(Boolean) : []);
+        const profile = new Set((deps.profileFn ?? resolveScopesForAccount)(alias));
+        return { granted, profile };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runtime enrichment for a scope 403 on a method whose required scopes are
+ * known (escape hatch: runtime Discovery; generated tools: baked). The
+ * account_type refinement lives here: a 403 on an admin scope that IS in the
+ * profile means Google refuses it for this account type (personal Gmail),
+ * so re-auth would loop — report the dead end instead.
+ */
+export function scopeHintForMethod(required, alias, deps = {}) {
+    const sets = accountScopeSets(alias, deps);
+    if (!sets || required.length === 0)
+        return null;
+    const best = classifyMethodScopes(required, sets.granted, sets.profile);
+    if (!best || best.state === 'callable')
+        return null; // 403 despite grants: not a scope-classification problem
+    const base = scopeHint(best.scope, best.classification, alias);
+    // Hedged, never fabricated: an in-profile admin scope that 403s is EITHER a
+    // Workspace account needing re-auth OR a personal account that can never be
+    // granted admin — the inputs cannot distinguish, so say both.
+    if (best.state === 'requestable_not_granted' && ADMIN_SCOPES.includes(best.scope)) {
+        return {
+            hint: `${base.hint} Note: personal (non-Workspace) accounts can never grant admin scopes — if ${alias} is a personal Gmail account, use a Workspace alias instead.`,
+            retriable: true,
+        };
+    }
+    return base;
+}
+/**
+ * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
+ * required by REGISTERED tools ("registered but not requestable" is the
+ * original #114 ask).
+ */
+export function buildScopesReport(granted, profile, registeredScopes = []) {
+    const callable = [];
+    const requestable = [];
+    const addBundle = [];
+    const accountType = [];
+    const unknown = [];
+    const universe = new Set([...profile, ...granted, ...registeredScopes]);
+    for (const scope of [...universe].sort()) {
+        const c = classifyScope(scope, granted, profile);
+        // Spec-exact: callable = granted ∩ profile (a granted scope the profile
+        // dropped is not reported as callable capacity).
+        if (c.state === 'callable') {
+            if (profile.has(scope))
+                callable.push(scope);
+            continue;
+        }
+        if (c.state === 'requestable_not_granted')
+            requestable.push(scope);
+        else if (c.reason === 'add_bundle')
+            addBundle.push({ scope, bundle: c.bundle });
+        else if (c.reason === 'account_type')
+            accountType.push(scope);
+        else
+            unknown.push(scope);
+    }
+    return {
+        configured: profile.size,
+        granted: granted.size,
+        callable,
+        requestable,
+        notRequestable: { addBundle, accountType, unknown },
+        missing: [...requestable, ...addBundle.map((e) => e.scope), ...accountType, ...unknown],
+    };
+}
+export function clearScopeIndexForTest() {
+    reverseIndex = null;
+}

package/dist/services.js

@@ -31,7 +31,7 @@ export const SERVICES = [
 // and workspaceevents is deliberately absent — no dedicated scope (subscriptions use resource scopes).
 const bundleGate = (name) => ({
     enabled: () => new Set(getOptionalBundles()).has(name),
-    hint: `add "${name}" to GOOGLE_OPTIONAL_SCOPES`,
+    hint: `add "${name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`,
 });
 export const GENERATED_GATES = {
     appsmarket: bundleGate('appsmarket'),

package/dist/setup-prompt.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface SetupOptions {
+    /** Public base URL when serving over HTTP; used for the Web client redirect. */
+    publicUrl?: string;
+}
+/** Pure builder (unit-testable): the full guided walkthrough as Markdown. */
+export declare function buildSetupText(opts?: SetupOptions): string;
+/** Register the `setup` prompt on the MCP server. */
+export declare function registerSetupPrompt(server: McpServer): void;

package/dist/setup-prompt.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/** Pure builder (unit-testable): the full guided walkthrough as Markdown. */
+export function buildSetupText(opts = {}) {
+    const base = opts.publicUrl?.replace(/\/+$/, '');
+    const clientStep = base
+        ? `Create an OAuth client of type **Web application** and add the redirect URI \`${base}/callback\`.`
+        : 'Create an OAuth client of type **Desktop app** (for the default stdio transport). If you serve over HTTP instead, create a **Web application** client with redirect `${MCP_PUBLIC_URL}/callback`.';
+    return [
+        '# Set up mcp-google-multi (Google Cloud Console prelude)',
+        '',
+        'This server uses **your own** Google OAuth client (BYO). Steps 1–5 below are one-time Google Cloud Console setup that **has no creation API** — Google provides no way to script consent screens or OAuth clients, so this guided walkthrough with deep links is the honest ceiling. Do them once in the browser; the server automates everything after.',
+        '',
+        '## 1. Create or pick a Google Cloud project',
+        'Open https://console.cloud.google.com/projectcreate and create a project (or pick an existing one). Note its project id.',
+        '',
+        '## 2. Enable the APIs your bundles need',
+        'Open https://console.cloud.google.com/apis/library and enable each Workspace API you will use (Gmail, Drive, Calendar, Sheets, Docs, People, …). Each API also has a direct link: `https://console.cloud.google.com/apis/library/<api>.googleapis.com` (e.g. `gmail.googleapis.com`). Later, `diagnose` / `doctor` will flag any API you missed with its exact enable link.',
+        '',
+        '## 3. Configure the OAuth consent screen',
+        'Open https://console.cloud.google.com/auth/audience — set **User type: External**, and under **Test users** add yourself (the owner) and anyone else who will authenticate.',
+        '',
+        '> **Expect an "unverified app" screen.** Because this is your own self-hosted client (not a Google-verified public app), the consent flow shows *"Google hasn\'t verified this app."* That is normal and safe for a client you created. Click **Advanced → Go to <your app> (unsafe)** to continue — you are trusting your own client. It is not a real security warning for your own setup.',
+        '',
+        '## 4. Set Publishing status to In production (avoid the 7-day trap)',
+        'On the same https://console.cloud.google.com/auth/audience page, set **Publishing status: In production**. While an app is in **Testing**, Google expires refresh tokens after **7 days**, so you would have to re-authenticate every week. Publishing to production removes that expiry. (No verification is required for personal use with your own test users.)',
+        '',
+        `## 5. Create an OAuth client`,
+        `Open https://console.cloud.google.com/auth/clients. ${clientStep} Copy the generated **Client ID** and **Client secret**.`,
+        '',
+        '## 6. Give the server your client credentials',
+        'Put them in real environment variables or in `~/.config/mcp-google-multi/.env` (never in `config.json`):',
+        '',
+        '```',
+        'GOOGLE_CLIENT_ID=<your client id>',
+        'GOOGLE_CLIENT_SECRET=<your client secret>',
+        '```',
+        '',
+        '## 7. Add your first account',
+        'Run the `account_add` flow (or `npx mcp-google-multi auth --account <alias>`) and complete the browser consent. The server then validates the granted scopes live and stores the encrypted token.',
+        '',
+        '---',
+        'When you are done, run `doctor` (or call `diagnose`) — it checks runtime, config, keys, tokens, scopes, and API enablement, and prints a copy-pasteable fix for anything still wrong.',
+    ].join('\n');
+}
+/** Register the `setup` prompt on the MCP server. */
+export function registerSetupPrompt(server) {
+    server.registerPrompt('setup', {
+        title: 'Set up mcp-google-multi',
+        description: 'Guided Google Cloud Console prelude: project, APIs, consent screen, OAuth client, and credentials. The one-time browser setup that has no API.',
+        argsSchema: { publicUrl: z.string().optional().describe('Public base URL when serving over HTTP (for the Web OAuth client redirect). Omit for stdio.') },
+    }, (args) => ({
+        messages: [
+            {
+                role: 'assistant',
+                content: { type: 'text', text: buildSetupText({ publicUrl: args?.publicUrl }) },
+            },
+        ],
+    }));
+}

package/dist/ssrf-guard.d.ts

@@ -0,0 +1,48 @@
+export declare class SsrfBlockedError extends Error {
+    constructor(message: string);
+}
+/** 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. */
+export declare function isBlockedIPv6(ip: string): boolean;
+export declare function isBlockedIp(ip: string): boolean;
+export interface SsrfDeps {
+    /** Injectable resolver (defaults to dns.lookup all-addresses) for tests. */
+    resolveAll?: (host: string) => Promise<string[]>;
+}
+/**
+ * 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 declare function assertPublicHttpsUrl(rawUrl: string, deps?: SsrfDeps): Promise<{
+    url: URL;
+    addresses: string[];
+}>;
+export interface CimdFetchOptions {
+    maxBytes?: number;
+    timeoutMs?: number;
+    maxRedirects?: number;
+    /** Transient-network-error retries per hop (default 2 → up to 3 attempts). */
+    retries?: number;
+    /** Base backoff between retries in ms; grows linearly per attempt (default 200). */
+    retryBackoffMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep for tests (default real setTimeout). */
+    sleepImpl?: (ms: number) => Promise<void>;
+    ssrf?: SsrfDeps;
+}
+/**
+ * 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 declare function fetchCimdDocument(rawUrl: string, opts?: CimdFetchOptions): Promise<Record<string, unknown>>;