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

package/dist/oauth-consent.d.ts

@@ -1,4 +1,14 @@
 import { OAuth2Client } from 'googleapis-common';
+/** Google authorize-URL options for the owner's HTTP authorization server.
+ * alias_reauth asks for the alias's scopes plus openid/email, which /callback
+ * needs to bind the returned identity to the alias. It carries no login_hint:
+ * the link works without authentication, so a hint would hand the alias's
+ * address to anyone who opens it. Every other flow is identity-only. */
+export declare function ownerAuthUrlOptions(opts: {
+    flow: string;
+    alias?: string;
+    state: string;
+}, scopesFor: (alias: string) => string[]): Parameters<OAuth2Client['generateAuthUrl']>[0];
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export declare class ClientCredentialsMissingError extends Error {
     constructor();

package/dist/oauth-consent.js

@@ -7,6 +7,22 @@ import { URL } from 'node:url';
 // call forever. The listener binds an EPHEMERAL loopback port (RFC 8252 §7.3;
 // Google Desktop clients accept any http://localhost:<port> redirect), so a
 // second local process on a fixed port can never break auth.
+/** Google authorize-URL options for the owner's HTTP authorization server.
+ * alias_reauth asks for the alias's scopes plus openid/email, which /callback
+ * needs to bind the returned identity to the alias. It carries no login_hint:
+ * the link works without authentication, so a hint would hand the alias's
+ * address to anyone who opens it. Every other flow is identity-only. */
+export function ownerAuthUrlOptions(opts, scopesFor) {
+    if (opts.flow === 'alias_reauth' && opts.alias) {
+        return {
+            access_type: 'offline',
+            prompt: 'select_account consent',
+            scope: [...new Set([...scopesFor(opts.alias), 'openid', 'email'])],
+            state: opts.state,
+        };
+    }
+    return { scope: ['openid', 'email'], prompt: 'select_account', state: opts.state };
+}
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export class ClientCredentialsMissingError extends Error {
     constructor() {

package/dist/outbound-allowlist.js

@@ -3,6 +3,7 @@
 // or share outside the operator's list), a safety feature first and an
 // enterprise checkbox second. FREE-core forever (ee-definition-v0 handoff).
 // Off by default: an unset/empty GOOGLE_OUTBOUND_ALLOWLIST gates nothing.
+import { hints } from './hint-provider.js';
 /** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
  * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
 export function resolveOutboundAllowlist(env = process.env) {
@@ -34,6 +35,7 @@ export function outboundViolations(emails, env = process.env) {
 /** The standard error envelope for a blocked outbound target. */
 export function outboundDeniedEnvelope(kind, blocked, account, env = process.env) {
     const list = resolveOutboundAllowlist(env);
+    const rendered = hints()?.render({ kind: 'outbound_denied', what: kind, blocked, entries: list?.entries ?? [] });
     return {
         content: [
             {
@@ -41,8 +43,9 @@ export function outboundDeniedEnvelope(kind, blocked, account, env = process.env
                 text: JSON.stringify({
                     error: 'recipient_not_allowed',
                     message: `${kind} blocked by the outbound allowlist: ${blocked.join(', ')}.`,
-                    hint: `GOOGLE_OUTBOUND_ALLOWLIST is active (${(list?.entries ?? []).join(', ')}). ` +
-                        'The operator must add the address (or its @domain) to the list, or unset the variable, to allow this target.',
+                    hint: rendered?.hint ??
+                        (`GOOGLE_OUTBOUND_ALLOWLIST is active (${(list?.entries ?? []).join(', ')}). ` +
+                            'The operator must add the address (or its @domain) to the list, or unset the variable, to allow this target.'),
                     retriable: false,
                     account,
                 }),

package/dist/reauth-hint.d.ts

@@ -1,2 +1,2 @@
-export declare function setHttpReauthBase(base: string | null): void;
+export declare function setHttpReauthLink(linker: ((alias: string) => string) | null): void;
 export declare function reauthHint(account: string): string;

package/dist/reauth-hint.js

@@ -1,15 +1,19 @@
 // B13 in-call re-auth (BV-1): a dead/missing per-account Google token is a
 // leg-C failure. Over stdio the fix is the `auth --account` CLI; over HTTP the
-// user cannot run a CLI, so the hint becomes a clickable link into the AS's
-// clientless alias_reauth flow (${BASE}/authorize?flow=alias_reauth&alias=…).
-// The HTTP bootstrap sets the base when the AS starts; stdio never does.
-let httpReauthBase = null;
-export function setHttpReauthBase(base) {
-    httpReauthBase = base;
+// user cannot run a CLI, so the hint becomes a clickable, server-signed link
+// into the AS's clientless alias_reauth flow (AuthServer.reauthLink). The HTTP
+// bootstrap installs the linker when the AS starts; stdio never does.
+import { hints } from './hint-provider.js';
+let httpReauthLink = null;
+export function setHttpReauthLink(linker) {
+    httpReauthLink = linker;
 }
 export function reauthHint(account) {
-    if (httpReauthBase) {
-        return `Re-authenticate "${account}" in your browser, then retry: ${httpReauthBase}/authorize?flow=alias_reauth&alias=${encodeURIComponent(account)}`;
+    const rendered = hints()?.render({ kind: 'reauth', account });
+    if (rendered)
+        return rendered.hint;
+    if (httpReauthLink) {
+        return `Re-authenticate "${account}" in your browser, then retry: ${httpReauthLink(account)}`;
     }
     return `Run: npx mcp-google-multi auth --account ${account}`;
 }

package/dist/registry-transfer.d.ts

@@ -1,3 +1,8 @@
+/** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
+ * store. A tenant-namespaced layout means the bundle would either miss every
+ * tenant's tokens or exfiltrate all of them in one file — refuse instead.
+ * Returns the offending dir, or null when the store is flat. */
+export declare function refuseIfMultiTenant(dir?: string): string | null;
 export interface TransferBundle {
     manifest: {
         v: 1;

package/dist/registry-transfer.js

@@ -7,11 +7,24 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as readline from 'node:readline';
 import path from 'node:path';
-import { encryptToken, decryptToken } from './token-store.js';
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
 import { atomicWriteFileSync, atomicWriteWithLock } from './fs-atomic.js';
-import { configFilePath, CONFIG_VERSION } from './config-file.js';
+import { ALIAS_RE, configFilePath, CONFIG_VERSION, tenantsDir } from './config-file.js';
 import { getTokenDir } from './accounts.js';
-const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+/** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
+ * store. A tenant-namespaced layout means the bundle would either miss every
+ * tenant's tokens or exfiltrate all of them in one file — refuse instead.
+ * Returns the offending dir, or null when the store is flat. */
+export function refuseIfMultiTenant(dir = tenantsDir()) {
+    try {
+        if (readdirSync(dir).length > 0)
+            return dir;
+    }
+    catch {
+        // absent or unreadable tenants/ = flat store
+    }
+    return null;
+}
 function resolveDeps(deps) {
     return {
         configPath: deps.configPath ?? configFilePath(),
@@ -48,15 +61,52 @@ export function buildTransferBundle(exportedAt, deps = {}) {
     }
     return { manifest: { v: 1, exportedAt, aliases: [...aliasSet].sort() }, config, tokens };
 }
+// Bundle envelope v2: a REAL passphrase KDF. The v1 envelope reused the
+// token store's deriveKey, whose passphrase branch is one unsalted sha256 —
+// an exported bundle could be brute-forced offline (CodeQL
+// js/insufficient-password-hash). scrypt with a per-bundle random salt fixes
+// that; v1 bundles (a prerelease-only format, never produced by any stable
+// release) are refused with a re-export hint rather than kept decryptable.
+const BUNDLE_VERSION = 2;
+const SCRYPT_PARAMS = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+function bundleKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32, SCRYPT_PARAMS);
+}
 export function encryptBundle(bundle, passphrase) {
-    return encryptToken(bundle, passphrase);
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', bundleKey(passphrase, salt), iv);
+    const data = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(bundle), 'utf8')), cipher.final()]);
+    const file = {
+        bv: BUNDLE_VERSION,
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+        data: data.toString('base64'),
+    };
+    return JSON.stringify(file);
 }
 export class BundleDecryptError extends Error {
 }
 export function decryptBundle(contents, passphrase) {
+    let file;
+    try {
+        file = JSON.parse(contents);
+    }
+    catch {
+        throw new BundleDecryptError('The file is not a registry export bundle.');
+    }
+    if (file.v !== undefined && file.bv === undefined) {
+        throw new BundleDecryptError('This bundle uses the retired v1 prerelease format (weak passphrase derivation); re-export it from the source machine with the current version.');
+    }
+    if (file.bv !== BUNDLE_VERSION || !file.salt || !file.iv || !file.tag || !file.data) {
+        throw new BundleDecryptError('The file is not a valid registry export (bad envelope).');
+    }
     let obj;
     try {
-        obj = decryptToken(contents, passphrase);
+        const decipher = createDecipheriv('aes-256-gcm', bundleKey(passphrase, Buffer.from(file.salt, 'base64')), Buffer.from(file.iv, 'base64'));
+        decipher.setAuthTag(Buffer.from(file.tag, 'base64'));
+        obj = JSON.parse(Buffer.concat([decipher.update(Buffer.from(file.data, 'base64')), decipher.final()]).toString('utf8'));
     }
     catch {
         throw new BundleDecryptError('Could not decrypt the bundle — wrong passphrase or the file is corrupt.');
@@ -153,6 +203,11 @@ async function resolvePassphrase(prompt) {
     }
 }
 export async function runExportCli(argv) {
+    const mtDir = refuseIfMultiTenant();
+    if (mtDir) {
+        console.error(`E_MULTI_TENANT_EXPORT_REFUSED: tenant-namespaced token stores exist under ${mtDir}; account export only operates on a flat single-owner store.`);
+        return 2;
+    }
     const out = argFlag(argv, '--out');
     if (!out) {
         console.error('Usage: mcp-google-multi account export --out <bundle.enc>');
@@ -170,6 +225,11 @@ export async function runExportCli(argv) {
     return 0;
 }
 export async function runImportCli(argv) {
+    const mtDir = refuseIfMultiTenant();
+    if (mtDir) {
+        console.error(`E_MULTI_TENANT_EXPORT_REFUSED: tenant-namespaced token stores exist under ${mtDir}; account import only operates on a flat single-owner store.`);
+        return 2;
+    }
     const file = argv[argv.indexOf('import') + 1];
     if (!file || file.startsWith('--')) {
         console.error('Usage: mcp-google-multi account import <bundle.enc> [--replace]');

package/dist/registry.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
+import { type AccountSet } from './accounts.js';
 import type { ArgShape } from './arg-normalize.js';
 import type { Metrics } from './usage-metrics.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
@@ -37,10 +38,13 @@ export interface CatalogOperation {
      * real scope error rather than a bare "not found". */
     unreachable?: true;
 }
+/** The service a tool name belongs to: its prefix, unless overridden. */
+export declare function serviceOf(name: string): string;
 export declare function inferCud(name: string): Cud;
 export declare class ToolRegistry {
     private readonly server;
     private readonly metrics;
+    private readonly accounts;
     readonly tools: ToolEntry[];
     readonly policy: Policy;
     readonly registerTool: McpServer['registerTool'];
@@ -57,9 +61,15 @@ export declare class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     private expanded;
-    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null);
+    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null, accounts?: () => AccountSet);
     registerMeta: McpServer['registerTool'];
     services(): string[];
+    /** The registry's OWN alias list: registration-time schema builders (the
+     * generated account enums) read this, never the process global. */
+    accountAliases(): readonly string[];
+    /** The registry's OWN account set: handlers needing an account's email or
+     * profile read this, never the process global. */
+    accountSet(): AccountSet;
     /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
      * normalization; the kind drives value coercion on renamed keys). */
     argShape(name: string): ArgShape | undefined;
@@ -118,4 +128,11 @@ export declare class ToolRegistry {
     };
     installListHandler(): void;
     private toToolJson;
+    /** Advertise the CURRENT alias enum on every tools/list: account validation
+     * is (or is becoming) live, so a cached boot-time enum would go stale the
+     * moment account_add lands mid-session. The structural schema stays cached;
+     * only the account property's values are refreshed per call. Skipped for
+     * the subject-taking account tools (their `account` is the OPERAND, e.g. a
+     * brand-new alias name, not an identity to enumerate). */
+    private withLiveAccountEnum;
 }

package/dist/registry.js

@@ -1,11 +1,12 @@
 import { z } from 'zod';
 import { isAllowed, writeDisabledResult, IRREVERSIBLE_TOOLS } from './write-control.js';
-import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
+import { getAccountSet, isLiveAccountField, refreshAccountSetIfStale } from './accounts.js';
 import { compactResult, trimEnabled } from './trim.js';
-import { fanoutAccountField, invalidAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
+import { fanoutAccountField, invalidAccountsResult, noAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
 import { MAX_RESPONSE_CHARS } from './executor.js';
-import { suggestKeys } from './arg-strict.js';
+import { MAX_SUGGESTED_KEYS, suggestKeys } from './arg-strict.js';
 import { classifyScope } from './scope-observability.js';
+import { hints } from './hint-provider.js';
 /** Nothing granted, no profile: asks the BUNDLE CATALOG whether a scope is
  * reachable at all, independently of any account. */
 const EMPTY_SCOPES = new Set();
@@ -40,6 +41,10 @@ const CUD_OVERRIDES = {
 const SERVICE_OVERRIDES = {
     reports_activities_list: 'admin',
 };
+/** The service a tool name belongs to: its prefix, unless overridden. */
+export function serviceOf(name) {
+    return Object.hasOwn(SERVICE_OVERRIDES, name) ? SERVICE_OVERRIDES[name] : name.includes('_') ? name.slice(0, name.indexOf('_')) : name;
+}
 // read tools that write local files — same savePath fanned across accounts would clobber
 const FANOUT_EXCLUDE = new Set(['gmail_download_attachment', 'drive_download', 'drive_export']);
 /** Account-management tools: the `account` they take is the SUBJECT of the
@@ -64,7 +69,11 @@ function scalarKindOf(field) {
     }
     return 'other';
 }
-function isAccountEnum(field) {
+/** A field naming one of the registry's accounts: a baked enum or a live
+ * account check (curated tools and generated tools both validate live). */
+function isAccountSelector(field) {
+    if (isLiveAccountField(field))
+        return true;
     const def = field?._zod?.def;
     if (!def)
         return false;
@@ -91,6 +100,7 @@ export function inferCud(name) {
 export class ToolRegistry {
     server;
     metrics;
+    accounts;
     tools = [];
     policy;
     registerTool;
@@ -107,13 +117,18 @@ export class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     expanded = false;
-    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null) {
+    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null, 
+    // The registry's OWN account view: fan-out expansion, selector validation
+    // and default-account injection all read through it so a registry built
+    // over a subset never observes (or leaks) the global set.
+    accounts = getAccountSet) {
         this.server = server;
         this.metrics = metrics;
+        this.accounts = accounts;
         this.policy = policy;
         this.mode = mode;
         this.registerTool = ((name, config, handler) => {
-            const service = SERVICE_OVERRIDES[name] ?? (name.includes('_') ? name.slice(0, name.indexOf('_')) : name);
+            const service = serviceOf(name);
             const cud = config.cud ?? inferCud(name);
             // destructiveHint=false claims "additive only" (MCP spec) — updates overwrite, so they stay true.
             // idempotent: reads trivially, deletes (already-gone = same), updates
@@ -140,14 +155,16 @@ export class ToolRegistry {
             let inputShape = config.inputSchema ?? {};
             let baseHandler = handler;
             const hasAccountField = 'account' in inputShape && !DEFAULT_ACCOUNT_EXCLUDE.has(name);
-            if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountEnum(inputShape.account)) {
+            if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountSelector(inputShape.account)) {
                 const description = inputShape.account.description ?? 'Google account alias';
-                inputShape = { ...inputShape, account: fanoutAccountField(description) };
+                inputShape = { ...inputShape, account: fanoutAccountField(description, () => this.accounts().aliases) };
                 baseHandler = async (...args) => {
                     const first = args[0];
-                    const parsed = parseAccountSelector(typeof first?.account === 'string' ? first.account : '');
+                    const parsed = parseAccountSelector(typeof first?.account === 'string' ? first.account : '', this.accounts().aliases);
                     if (!parsed.ok)
-                        return invalidAccountsResult(parsed.invalid);
+                        return invalidAccountsResult(parsed.invalid, this.accounts().aliases);
+                    if (parsed.aliases.length === 0)
+                        return noAccountsResult();
                     if (!parsed.fanout)
                         return handler({ ...first, account: parsed.aliases[0] }, ...args.slice(1));
                     return runFanout(handler, args, parsed.aliases);
@@ -188,8 +205,10 @@ export class ToolRegistry {
                     // heals for a client that always omits account (this branch never
                     // reaches getClient's probe). One stat, only on omission.
                     refreshAccountSetIfStale();
-                    const def = getAccountSet().defaultAccount;
+                    const def = this.accounts().defaultAccount;
                     if (!def) {
+                        const aliases = this.accounts().aliases;
+                        const rendered = hints()?.render({ kind: 'no_default_account', aliases });
                         return {
                             content: [
                                 {
@@ -197,7 +216,7 @@ export class ToolRegistry {
                                     text: JSON.stringify({
                                         error: 'E_NO_DEFAULT_ACCOUNT',
                                         message: 'No "account" given and no default account is configured.',
-                                        hint: `Pass account explicitly (valid: ${getAccountSet().aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
+                                        hint: rendered?.hint ?? `Pass account explicitly (valid: ${aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
                                         retriable: false,
                                     }),
                                 },
@@ -219,7 +238,7 @@ export class ToolRegistry {
                     const v = a?.account;
                     if (typeof v !== 'string' || (v !== '*' && !v.includes(',')))
                         return 1;
-                    const sel = parseAccountSelector(v);
+                    const sel = parseAccountSelector(v, this.accounts().aliases);
                     return sel.ok ? sel.aliases.length : 1;
                 })
                 : finalHandler;
@@ -239,6 +258,16 @@ export class ToolRegistry {
     services() {
         return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
     }
+    /** The registry's OWN alias list: registration-time schema builders (the
+     * generated account enums) read this, never the process global. */
+    accountAliases() {
+        return this.accounts().aliases;
+    }
+    /** The registry's OWN account set: handlers needing an account's email or
+     * profile read this, never the process global. */
+    accountSet() {
+        return this.accounts();
+    }
     /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
      * normalization; the kind drives value coercion on renamed keys). */
     argShape(name) {
@@ -293,7 +322,7 @@ export class ToolRegistry {
         // case (parentId against parentFolderId) fails containment and edit
         // distance alike, which is the whole reason that matcher exists.
         const keys = candidates.map(([key]) => key);
-        const hits = new Set(unknownKeys.flatMap((k) => suggestKeys(k, keys)));
+        const hits = new Set(unknownKeys.slice(0, MAX_SUGGESTED_KEYS).flatMap((k) => suggestKeys(k, keys)));
         return candidates
             .filter(([key]) => hits.has(key))
             .slice(0, 2)
@@ -440,9 +469,36 @@ export class ToolRegistry {
         return {
             name: tool.name,
             description: tool.description,
-            inputSchema,
+            inputSchema: this.withLiveAccountEnum(tool, inputSchema),
             annotations: tool.annotations,
             ...(tool.clientMeta ? { _meta: tool.clientMeta } : {}),
         };
     }
+    /** Advertise the CURRENT alias enum on every tools/list: account validation
+     * is (or is becoming) live, so a cached boot-time enum would go stale the
+     * moment account_add lands mid-session. The structural schema stays cached;
+     * only the account property's values are refreshed per call. Skipped for
+     * the subject-taking account tools (their `account` is the OPERAND, e.g. a
+     * brand-new alias name, not an identity to enumerate). */
+    withLiveAccountEnum(tool, schema) {
+        if (DEFAULT_ACCOUNT_EXCLUDE.has(tool.name))
+            return schema;
+        const s = schema;
+        const account = s?.properties?.account;
+        if (!account)
+            return schema;
+        const aliases = this.accounts().aliases;
+        if (aliases.length === 0)
+            return schema;
+        if (Array.isArray(account.anyOf)) {
+            // fan-out union: advertise '*' + the live aliases on the selector branch
+            // (the one without the CSV pattern), keep the CSV branch as is
+            const isSelector = (b) => b.pattern === undefined;
+            if (!account.anyOf.some(isSelector))
+                return schema;
+            const anyOf = account.anyOf.map((b) => (isSelector(b) ? { ...b, enum: ['*', ...aliases] } : b));
+            return { ...s, properties: { ...s.properties, account: { ...account, anyOf } } };
+        }
+        return { ...s, properties: { ...s.properties, account: { ...account, enum: [...aliases] } } };
+    }
 }

package/dist/scope-catalog.d.ts

@@ -14,7 +14,18 @@ export declare const BUNDLE_CATALOG: Record<string, BundleCatalogEntry>;
 /** 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 declare const BUNDLE_ALIASES: Record<string, string>;
+/** Bundle names are user input: an Object.prototype member ("constructor",
+ * "toString") passes a plain `in` or index lookup, so membership is own-key only. */
+export declare function isKnownBundle(name: string): boolean;
 export declare function resolveBundleAliases(bundles: string[]): string[];
 /** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
 export declare function closestBundle(name: string): string | undefined;
+/** Longest input any did-you-mean compares. Every name it suggests (tool,
+ * argument key, bundle, Discovery method id) is far shorter, and the inputs
+ * are caller-controlled: an unbounded comparison let one oversized name block
+ * the event loop for minutes. */
+export declare const SUGGEST_MAX_INPUT = 128;
+/** Levenshtein distance. Past SUGGEST_MAX_INPUT it returns the longer length
+ * without comparing: an upper bound on the true distance, and above every
+ * caller's accept threshold, so a capped pair is never suggested. */
 export declare function editDistance(a: string, b: string): number;

package/dist/scope-catalog.js

@@ -160,9 +160,14 @@ export const BUNDLE_CATALOG = {
  * future rename is a deprecation warning, never a breaking config change. */
 export const BUNDLE_ALIASES = {};
 const warnedAliases = new Set();
+/** Bundle names are user input: an Object.prototype member ("constructor",
+ * "toString") passes a plain `in` or index lookup, so membership is own-key only. */
+export function isKnownBundle(name) {
+    return Object.hasOwn(BUNDLE_CATALOG, name);
+}
 export function resolveBundleAliases(bundles) {
     return bundles.map((name) => {
-        const target = BUNDLE_ALIASES[name];
+        const target = Object.hasOwn(BUNDLE_ALIASES, name) ? BUNDLE_ALIASES[name] : undefined;
         if (!target)
             return name;
         if (!warnedAliases.has(name)) {
@@ -177,6 +182,8 @@ export function closestBundle(name) {
     let best;
     let bestDist = 3;
     for (const key of Object.keys(BUNDLE_CATALOG)) {
+        if (Math.abs(name.length - key.length) >= bestDist)
+            continue;
         const d = editDistance(name.toLowerCase(), key);
         if (d < bestDist) {
             bestDist = d;
@@ -185,14 +192,24 @@ export function closestBundle(name) {
     }
     return best;
 }
+/** Longest input any did-you-mean compares. Every name it suggests (tool,
+ * argument key, bundle, Discovery method id) is far shorter, and the inputs
+ * are caller-controlled: an unbounded comparison let one oversized name block
+ * the event loop for minutes. */
+export const SUGGEST_MAX_INPUT = 128;
+/** Levenshtein distance. Past SUGGEST_MAX_INPUT it returns the longer length
+ * without comparing: an upper bound on the true distance, and above every
+ * caller's accept threshold, so a capped pair is never suggested. */
 export 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;
+    if (a.length > SUGGEST_MAX_INPUT || b.length > SUGGEST_MAX_INPUT)
+        return Math.max(a.length, b.length);
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
     for (let i = 1; i <= a.length; i++) {
+        const row = [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));
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
         }
+        prev = row;
     }
-    return dp[a.length][b.length];
+    return prev[b.length];
 }

package/dist/scope-observability.d.ts

@@ -1,4 +1,3 @@
-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';
@@ -35,12 +34,15 @@ export interface AccountScopeSets {
     granted: Set<string>;
     profile: Set<string>;
 }
+/** Where a scope hint reads the granted token and the configured profile;
+ * absent = the single-owner token store and global registry. */
+export interface ScopeSetDeps {
+    readTokenFn?: typeof readToken;
+    profileFn?: (alias: string) => 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;
+export declare function accountScopeSets(alias: string, deps?: ScopeSetDeps): AccountScopeSets | null;
 /**
  * Runtime enrichment for a scope 403 on a method whose required scopes are
  * known (escape hatch: runtime Discovery; generated tools: baked). The
@@ -48,7 +50,7 @@ export declare function accountScopeSets(alias: string, deps?: {
  * 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]): {
+export declare function scopeHintForMethod(required: readonly string[], alias: string, deps?: ScopeSetDeps): {
     hint: string;
     retriable: boolean;
 } | null;

package/dist/scope-observability.js

@@ -1,6 +1,8 @@
 import { ADMIN_SCOPES, BUNDLE_CATALOG } from './scope-catalog.js';
 import { BASE_SCOPES, resolveScopesForAccount } from './auth.js';
 import { readToken } from './token-store.js';
+import { reauthHint } from './reauth-hint.js';
+import { hints } from './hint-provider.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).
@@ -71,40 +73,54 @@ export function classifyMethodScopes(alternatives, granted, profile) {
  */
 export function scopeHint(scope, c, alias) {
     switch (c.state) {
-        case 'requestable_not_granted':
+        case 'requestable_not_granted': {
+            const rendered = hints()?.render({ kind: 'scope_not_granted', account: alias, scope });
             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,
+                hint: rendered?.hint ??
+                    (`Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
+                        reauthHint(alias)),
+                // The ONE kind whose retriable the host may flip (Decision 3): the
+                // owner keeps true, a multi-tenant host may report false because the
+                // fix needs the user in a browser.
+                retriable: rendered?.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') {
+                    const rendered = hints()?.render({ kind: 'scope_base_excluded', account: alias, scope });
                     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}`,
+                        hint: rendered?.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,
                     };
                 }
+                const rendered = hints()?.render({ kind: 'scope_needs_bundle', account: alias, scope, bundle: c.bundle });
                 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}`,
+                    hint: rendered?.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') {
+                const rendered = hints()?.render({ kind: 'scope_account_type', account: alias, scope });
                 return {
-                    hint: `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    hint: rendered?.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,
+                };
+            }
+            {
+                const rendered = hints()?.render({ kind: 'scope_unknown_scope', scope });
+                return {
+                    hint: rendered?.hint ?? `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. 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 };
     }