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

package/dist/doctor.js

@@ -2,16 +2,19 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { getAccountSet } from './accounts.js';
-import { deriveAccountHealth } from './tools/accounts-tool.js';
+import { accountHealthDepsFor, deriveAccountHealth } from './tools/accounts-tool.js';
+import { isOwnerContext } from './identity.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
 import { configDir, loadConfigFile } from './config-file.js';
 import { envValueSource } from './env-load.js';
+import { reauthHint } from './reauth-hint.js';
 import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
-import { probeApiEnablement } from './api-probe.js';
+import { apiProbeDepsFor, probeApiEnablement } from './api-probe.js';
 import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
+import { hints } from './hint-provider.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -68,9 +71,22 @@ export function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
 const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
-function sectionRuntime(deps) {
+function sectionRuntime(deps, tenantScope = false) {
     const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
     if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {
+        if (tenantScope) {
+            // The host version is operator infrastructure, not the tenant's (E7
+            // residue): no version string, and the fix is the operator's to apply.
+            const rendered = hints()?.render({ kind: 'operator_only', slug: 'E_NODE_TOO_OLD' });
+            return {
+                id: 1,
+                title: 'Runtime',
+                verdict: 'fail',
+                slug: 'E_NODE_TOO_OLD',
+                lines: ['Runtime below the supported version'],
+                hint: rendered?.hint ?? 'Tell the server operator the code E_NODE_TOO_OLD.',
+            };
+        }
         return {
             id: 1,
             title: 'Runtime',
@@ -80,23 +96,36 @@ function sectionRuntime(deps) {
             hint: `Upgrade to Node ${MIN_NODE_MAJOR} LTS or newer.`,
         };
     }
-    return { id: 1, title: 'Runtime', verdict: 'ok', lines: [`Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`] };
+    return {
+        id: 1,
+        title: 'Runtime',
+        verdict: 'ok',
+        lines: [tenantScope ? 'Runtime ok' : `Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`],
+    };
 }
-function sectionConfig(deps, set) {
+function sectionConfig(deps, set, tenantScope = false) {
     const lines = [];
     let verdict = 'ok';
     let hint;
     let slug;
     if (!set || set.aliases.length === 0) {
+        const tenantHint = tenantScope ? (hints()?.render({ kind: 'no_accounts' })?.hint ?? '') : undefined;
         return {
             id: 2,
             title: 'Config',
             verdict: 'fail',
             slug: 'E_NO_ACCOUNTS_CONFIGURED',
             lines: ['No accounts configured.'],
-            hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.',
+            ...(tenantScope
+                ? (tenantHint ? { hint: tenantHint } : {})
+                : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
         };
     }
+    // The config file, process env, working directory and metrics store below
+    // are the operator's host, not the context's: a tenant sees its own count.
+    if (tenantScope) {
+        return { id: 2, title: 'Config', verdict: 'ok', lines: [`${set.aliases.length} account(s) configured`] };
+    }
     const cfgPath = path.join(configDir(), 'config.json');
     lines.push(deps.fileExists(cfgPath) ? `config.json present (${set.aliases.length} account(s))` : `config.json absent — accounts sourced from env (${set.aliases.length})`);
     const legacyEnv = LEGACY_ENV_KEYS.filter((k) => deps.env[k]);
@@ -181,7 +210,8 @@ function sectionsTokensAndScopes(deps, aliases) {
             if (scopeVerdict === 'ok')
                 scopeVerdict = 'warn';
             scopeLines.push(`${alias}: ${r.callable.length} callable, ${r.requestable.length} requested-not-granted`);
-            scopeHint = `Re-auth to grant missing scopes: \`npx mcp-google-multi auth --account ${alias}\`.`;
+            const rendered = hints()?.render({ kind: 'scopes_missing', account: alias });
+            scopeHint = rendered?.hint ?? `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
         }
         else {
             scopeLines.push(`${alias}: ${r.callable.length} callable, all profile scopes granted`);
@@ -192,7 +222,7 @@ function sectionsTokensAndScopes(deps, aliases) {
         { id: 5, title: 'Scopes', verdict: scopeVerdict, lines: scopeLines, ...(scopeHint ? { hint: scopeHint } : {}), ...(scopeVerdict === 'warn' ? { slug: 'E_SCOPE_NOT_GRANTED' } : {}) },
     ];
 }
-async function sectionApiEnablement(deps, aliases) {
+async function sectionApiEnablement(deps, aliases, tenantScope = false) {
     if (!deps.probeApi) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['Probe not run (no live account probe configured).'] };
     }
@@ -209,8 +239,15 @@ async function sectionApiEnablement(deps, aliases) {
         results = await deps.probeApi(healthy);
     }
     catch (e) {
-        // Network / transient: WARN with the target, never crash the report.
-        return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
+        // Network / transient: WARN with the target, never crash the report. The
+        // raw text can name an egress or proxy host (E7 residue): tenant scope
+        // drops it.
+        return {
+            id: 6,
+            title: 'API enablement',
+            verdict: 'warn',
+            lines: [tenantScope ? 'Probe could not complete.' : `Probe could not complete: ${e?.message ?? e}`],
+        };
     }
     if (results.length === 0) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: [`No probeable service scopes granted on "${healthy}".`] };
@@ -218,13 +255,14 @@ async function sectionApiEnablement(deps, aliases) {
     const disabled = results.filter((r) => r.notEnabled);
     const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
     if (disabled.length > 0) {
+        const rendered = hints()?.render({ kind: 'apis_disabled', services: disabled.map((r) => ({ service: r.service, api: r.api })) });
         return {
             id: 6,
             title: 'API enablement',
             verdict: 'fail',
             slug: 'E_API_NOT_ENABLED',
             lines,
-            hint: disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
+            hint: rendered?.hint ?? disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
         };
     }
     return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
@@ -299,21 +337,29 @@ export function overallVerdict(sections) {
     }
     return worst;
 }
-export async function runDiagnostics(deps = DEFAULT_DEPS) {
+export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
+    // Tenant scope omits the OPERATOR sections: §3 (key provenance = box
+    // infrastructure) and §7 (its owner-gate lines print MCP_OWNER_EMAILS
+    // values — other people's addresses from a tenant's seat), and trims §2 to
+    // the context's own account count.
+    const tenantScope = opts.scope === 'tenant';
     const sections = [];
-    sections.push(sectionRuntime(deps));
+    sections.push(sectionRuntime(deps, tenantScope));
     const set = deps.accountSet();
-    sections.push(sectionConfig(deps, set));
+    sections.push(sectionConfig(deps, set, tenantScope));
     const aliases = set?.aliases ?? [];
-    sections.push(sectionKeys(deps, aliases));
+    if (!tenantScope)
+        sections.push(sectionKeys(deps, aliases));
     if (aliases.length > 0) {
         const [tokens, scopes] = sectionsTokensAndScopes(deps, aliases);
         sections.push(tokens, scopes);
-        sections.push(await sectionApiEnablement(deps, aliases));
+        sections.push(await sectionApiEnablement(deps, aliases, tenantScope));
+    }
+    if (!tenantScope) {
+        const http = await sectionHttp(deps, aliases);
+        if (http)
+            sections.push(http);
     }
-    const http = await sectionHttp(deps, aliases);
-    if (http)
-        sections.push(http);
     return { verdict: overallVerdict(sections), sections };
 }
 // --- skins -----------------------------------------------------------------
@@ -333,9 +379,35 @@ export function renderDoctorText(report) {
     out.push(`Overall: ${report.verdict.toUpperCase()}`);
     return out.join('\n');
 }
-/** Mask the local-part of an email so a report never carries a full address (BR8). */
+const EMAIL_LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
+const EMAIL_DOMAIN_CHAR = /[A-Za-z0-9.-]/;
+/** Mask the local-part of an email so a report never carries a full address
+ * (BR8). A linear scan, not a regex: the `local* @domain` pattern backtracks
+ * polynomially on long local-charset runs without an @ (CodeQL
+ * js/polynomial-redos), and report text can embed arbitrary error strings. */
 function maskEmails(text) {
-    return text.replace(/([A-Za-z0-9._%+-])[A-Za-z0-9._%+-]*(@[A-Za-z0-9.-]+)/g, '$1***$2');
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] === '@') {
+            let j = i + 1;
+            while (j < text.length && EMAIL_DOMAIN_CHAR.test(text[j]))
+                j += 1;
+            let k = out.length;
+            while (k > 0 && EMAIL_LOCAL_CHAR.test(out[k - 1]))
+                k -= 1;
+            if (j > i + 1 && k < out.length) {
+                // keep the first local char, mask the rest ('*' is outside the local
+                // charset, so a masked run can never be re-masked by a later @)
+                out = `${out.slice(0, k + 1)}***${text.slice(i, j)}`;
+                i = j;
+                continue;
+            }
+        }
+        out += text[i];
+        i += 1;
+    }
+    return out;
 }
 /** Redacted, paste-ready bug report (BR8): verdicts + provenance labels + token
  * statuses + slugs; NO token values, secrets, keys, or full email addresses. */
@@ -356,6 +428,26 @@ export function exitCodeFor(report, strict) {
         return 1;
     return 0;
 }
+/** The engine's account, token and probe reads bound to one context, so a
+ * report never shows (or probes with) another context's accounts. */
+function diagnosticsDepsFor(ctx) {
+    const health = accountHealthDepsFor(ctx.tokenStore, () => ctx.accounts);
+    const probe = apiProbeDepsFor(ctx.tokenStore.readToken, ctx.getClient);
+    return {
+        ...DEFAULT_DEPS,
+        accountSet: () => {
+            try {
+                return ctx.accounts;
+            }
+            catch {
+                return null;
+            }
+        },
+        accountHealth: (alias) => deriveAccountHealth(alias, health),
+        anyTokensExist: (aliases) => aliases.some((a) => ctx.tokenStore.hasToken(a)),
+        probeApi: (alias) => probeApiEnablement(alias, probe),
+    };
+}
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
  * engine. Registered as a META tool, like `account_list`: it introspects this
  * server rather than Google data, and as a normal tool it became a service of
@@ -363,14 +455,18 @@ export function exitCodeFor(report, strict) {
  * from already-registered services, and this runs after that), so it was
  * advertised only once something else expanded the surface. The README sends
  * people here when they are stuck, so it has to be findable. */
-export function registerDiagnoseTool(registry) {
+export function registerDiagnoseTool(registry, ctx) {
+    // A non-owner context gets the tenant-scoped report; only the owner context
+    // (or the context-free CLI surface) keeps the full operator report.
+    const scope = ctx && !isOwnerContext(ctx) ? 'tenant' : 'operator';
+    const deps = ctx ? diagnosticsDepsFor(ctx) : DEFAULT_DEPS;
     registry.registerMeta('diagnose', {
         annotations: { readOnlyHint: true, openWorldHint: true },
         description: 'Health report for this server: runtime, config, keys, per-account token status, scope grants, and API enablement. Read-only; returns copy-pasteable fixes for anything wrong. Call this to diagnose auth/config failures.',
         inputSchema: {},
     }, async () => {
         try {
-            const result = await runDiagnostics();
+            const result = await runDiagnostics(deps, { scope });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (e) {

package/dist/executor.d.ts

@@ -1,4 +1,5 @@
 import { getClient } from './client.js';
+import { type ScopeSetDeps } from './scope-observability.js';
 export declare const MAX_RESPONSE_CHARS = 100000;
 export type QueryValue = string | number | boolean;
 export type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -13,6 +14,8 @@ export interface ApiMethodRef {
 }
 export interface ExecuteDeps {
     getClientFn?: typeof getClient;
+    /** Token + profile view behind a 403 scope hint; absent = the single owner. */
+    scopeDeps?: ScopeSetDeps;
 }
 export interface ExecuteArgs {
     account: string;

package/dist/executor.js

@@ -4,6 +4,7 @@ import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
 import { checkOutboundForMethod } from './outbound-allowlist.js';
+import { hints } from './hint-provider.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -70,10 +71,11 @@ export async function executeApiMethod(method, args, deps = {}) {
         }, true);
     }
     if (!isGoogleApiUrl(url)) {
+        const rendered = hints()?.render({ kind: 'untrusted_host' });
         return jsonResult({
             error: 'untrusted_host',
             message: `Refusing to send credentials to a non-googleapis.com host for "${method.id}".`,
-            hint: 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
+            hint: rendered?.hint ?? 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
             retriable: false,
             account: args.account,
         }, true);
@@ -103,6 +105,6 @@ export async function executeApiMethod(method, args, deps = {}) {
         return { content: [{ type: 'text', text }] };
     }
     catch (error) {
-        return handleGoogleApiError(error, args.account, undefined, () => method.scopes?.length ? scopeHintForMethod(method.scopes, args.account) : null);
+        return handleGoogleApiError(error, args.account, undefined, () => method.scopes?.length ? scopeHintForMethod(method.scopes, args.account, deps.scopeDeps) : null);
     }
 }

package/dist/fanout.d.ts

@@ -1,6 +1,14 @@
 import { z } from 'zod';
 export declare const CSV_RE: RegExp;
-export declare function fanoutAccountField(description: string): z.ZodType;
+export declare function fanoutAccountField(description: string, aliases: () => readonly string[]): z.ZodType;
+/** '*' over an empty account set would fan out to nothing and report success. */
+export declare function noAccountsResult(): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
 export type AccountSelector = {
     ok: true;
     fanout: boolean;

package/dist/fanout.js

@@ -1,22 +1,48 @@
 import { z } from 'zod';
-import { ACCOUNTS, getAccountSet, unknownAliasMessage } from './accounts.js';
+import { getAccountSet, liveAccountCheck, unknownAliasMessage } from './accounts.js';
+import { echoName, echoNames, MAX_SUGGESTED_KEYS } from './arg-strict.js';
+import { hints } from './hint-provider.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
-export function fanoutAccountField(description) {
-    const csvExample = ACCOUNTS.length > 1 ? `; or a CSV subset like "${ACCOUNTS.slice(0, 2).join(',')}"` : '';
+// `aliases` is required (no global default): the field is baked into a
+// registry's inputSchema, so it must read THAT registry's account set or a
+// '*' would advertise and accept another registry's aliases. It is a getter:
+// the set is read at parse time, so an alias added mid-session (account_add,
+// a tenant link) is valid on tools registered before it existed.
+export function fanoutAccountField(description, aliases) {
+    const boot = aliases();
+    const csvExample = boot.length > 1 ? `; or a CSV subset like "${boot.slice(0, 2).join(',')}"` : '';
     // The union's OWN error only fires when every branch aborts at the type
     // check (a non-string). For a string, zod surfaces the single non-aborted
     // branch verbatim, which is the CSV regex, so a mistyped alias used to read
     // as "Invalid string: must match pattern /^[a-zA-Z0-9_-]+(,...)/" and never
     // named an alias. Hence the same message on BOTH.
-    const bad = () => unknownAliasMessage(ACCOUNTS, true);
+    const bad = () => unknownAliasMessage(aliases(), true);
     return z
-        // '*' first so the tuple is statically non-empty even when ACCOUNTS is empty
-        // (a fresh install): z.enum requires [string, ...string[]].
-        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE, { error: bad })], { error: bad })
+        // The selector branch stays first: tools/list injects the live
+        // '*' + alias enum into it (registry withLiveAccountEnum).
+        .union([z.string().check(liveAccountCheck(aliases, true)), z.string().regex(CSV_RE, { error: bad })], { error: bad })
         .optional()
         .describe(`${description}; "*" = all accounts${csvExample}; omit for the default account`);
 }
+/** '*' over an empty account set would fan out to nothing and report success. */
+export function noAccountsResult() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'validation_error',
+                    message: 'No Google account is configured, so "*" selects nothing.',
+                    hint: unknownAliasMessage([]),
+                    retriable: false,
+                    account: '*',
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
 export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
@@ -53,10 +79,11 @@ export function invalidAccountsResult(invalid, accounts = getAccountSet().aliase
                 type: 'text',
                 text: JSON.stringify({
                     error: 'validation_error',
-                    message: `Unknown account alias(es): ${invalid.join(', ')}.`,
+                    // The caller's CSV can hold any number of tokens: echo a prefix.
+                    message: `Unknown account alias(es): ${echoNames(invalid)}.`,
                     hint: unknownAliasMessage(accounts, true),
                     retriable: false,
-                    account: invalid.join(','),
+                    account: invalid.slice(0, MAX_SUGGESTED_KEYS).map(echoName).join(','),
                 }),
             },
         ],
@@ -87,10 +114,17 @@ export async function runFanout(handler, args, aliases) {
                 results[i] = res?.isError ? { account, ok: false, error: payload } : { account, ok: true, data: payload };
             }
             catch (err) {
+                const rendered = hints()?.render({ kind: 'internal', account });
                 results[i] = {
                     account,
                     ok: false,
-                    error: { error: 'internal', message: err.message, retriable: false, account },
+                    error: {
+                        error: 'internal',
+                        message: rendered?.message ?? err.message,
+                        hint: rendered?.hint,
+                        retriable: false,
+                        account,
+                    },
                 };
             }
         }

package/dist/fs-atomic.d.ts

@@ -1,3 +1,14 @@
+/** Which process instance holds a lock: PID namespace id, start time in
+ * clock ticks since boot, and a boot id prefix. A part this process cannot
+ * read is `host` or `0` (all three without /proc). */
+interface LockIdentity {
+    ns: string;
+    start: string;
+    boot: string;
+}
+/** Test hook: act as a process with this identity (undefined restores the real one). */
+export declare function __setLockIdentityForTest(identity?: LockIdentity): void;
 export declare function withFileLock<T>(absPath: string, fn: () => T, label?: string): T;
 export declare function atomicWriteFileSync(absPath: string, contents: string, mode?: number): void;
 export declare function atomicWriteWithLock(absPath: string, contents: string, mode?: number): void;
+export {};