mcp-google-multi 6.0.1 → 6.1.0-alpha.1

package/dist/compose.js

@@ -14,6 +14,7 @@ import { registerAccountWizardTools } from './tools/account-wizard.js';
 import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { isOwnerContext } from './identity.js';
 import { resolveScopesForAccount } from './auth.js';
+import { localFilesDisabledByEnv, logLocalFilesRootAtStartup } from './tools/_local-files.js';
 /** The one place the MCP server is constructed, so an embedding host can pass
  * per-session `instructions` without re-deriving the server identity. */
 export function createMcpServer(version, opts = {}) {
@@ -26,7 +27,18 @@ export function buildRegistry(server, ctx, mode, metrics = null) {
     const registry = new ToolRegistry(server, policy, mode, metrics, () => ctx.accounts);
     // ctx.accounts is read per call, never snapshotted here, so a live getter stays live.
     const owner = isOwnerContext(ctx);
-    const clientDeps = { getClientFn: ctx.getClient, localFiles: owner };
+    // GOOGLE_LOCAL_FILES=off removes every host-file tool/param for every
+    // context, including the owner, regardless of the transport.
+    const localFilesEnabled = owner && !localFilesDisabledByEnv();
+    // Log (never create) the effective GOOGLE_LOCAL_FILES_DIR root so an
+    // operator sees where uploads/downloads/attachments will be confined
+    // without triggering a tool call first; the root itself is created
+    // lazily, on first actual use, so a read-only or missing HOME (hardened
+    // systemd, an isolated service user) cannot fail server startup over a
+    // feature this run might never use. `config check` hits this same path.
+    if (localFilesEnabled)
+        logLocalFilesRootAtStartup();
+    const clientDeps = { getClientFn: ctx.getClient, localFiles: localFilesEnabled };
     const execDeps = {
         getClientFn: ctx.getClient,
         scopeDeps: {

package/dist/env-load.d.ts

@@ -9,6 +9,12 @@ export interface EnvLoadPaths {
     configDir?: string;
 }
 export declare function loadEnvFiles(paths?: EnvLoadPaths): EnvLoadResult;
+/** The .env files this process actually loaded a secret from (candidates
+ * that did not exist are not included). Used by the local-file guard to
+ * refuse reading or writing a file the server itself sourced secrets from,
+ * even though it sits outside the config/token directory (e.g. a project
+ * root .env, or MCP_GOOGLE_MULTI_ENV pointing elsewhere entirely). */
+export declare function getLoadedEnvFiles(): string[];
 /**
  * Which layer supplied `key`: the real process env, or the first loaded .env
  * file defining it (autoload never overwrites, so first wins). undefined when

package/dist/env-load.js

@@ -49,6 +49,14 @@ export function loadEnvFiles(paths = {}) {
     return { loaded, searched: candidates };
 }
 let lastLoad;
+/** The .env files this process actually loaded a secret from (candidates
+ * that did not exist are not included). Used by the local-file guard to
+ * refuse reading or writing a file the server itself sourced secrets from,
+ * even though it sits outside the config/token directory (e.g. a project
+ * root .env, or MCP_GOOGLE_MULTI_ENV pointing elsewhere entirely). */
+export function getLoadedEnvFiles() {
+    return lastLoad?.loaded ?? [];
+}
 /**
  * Which layer supplied `key`: the real process env, or the first loaded .env
  * file defining it (autoload never overwrites, so first wins). undefined when

package/dist/executor.js

@@ -3,7 +3,6 @@ import { sliceEncoded } from './trim.js';
 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) {
@@ -31,12 +30,11 @@ export function resolveRequestBody(httpMethod, body) {
         return undefined;
     return body ?? undefined;
 }
+// Write-control for a write call (deny-check, full-writes auto-allow, or an
+// elicitation round-trip asking a human) runs in the caller, BEFORE this is
+// invoked (src/tools/_escape-hatch.ts): by the time a write reaches here it
+// has already been cleared.
 export async function executeApiMethod(method, args, deps = {}) {
-    // Outbound allowlist: no-op when off; with it active, structured bodies are
-    // inspected for recipient fields and raw-compose methods are refused.
-    const outbound = checkOutboundForMethod(method.id, args.body, args.account);
-    if (outbound)
-        return outbound;
     if (args.queryParams?.alt === 'media') {
         return jsonResult({
             error: 'binary_unsupported',

package/dist/identity.js

@@ -19,8 +19,10 @@ export function buildIdentityContext(env = process.env, opts = {}) {
         get accounts() {
             return getAccountSet();
         },
-        // The dispatch transport rides into the resolved policy as a reserved seam;
-        // it does not change any write-control verdict.
+        // The dispatch transport rides into the resolved policy: it never changes
+        // isAllowed's verdict or the profile, but over HTTP it does turn an
+        // escape-hatch "ask" into a refusal (see Policy.transport in
+        // write-control.ts and docs/internals.md).
         policy: resolvePolicy(env, { transport: opts.transport }),
         getClient: makeGetClient('owner', {
             accounts: getAccountSet,

package/dist/index.js

@@ -103,7 +103,8 @@ async function main() {
         console.log(`Services: ${registry.services().join(', ')}`);
         console.log(`Discovery mode: ${registry.mode}${registry.mode === 'lazy' ? ' (expand at runtime with discover_all)' : ''}`);
         console.log(`Tool surface: ${counts.eager} eager (discover + escape hatch), ${counts.revealed} advertised, ${counts.hidden} deferred`);
-        console.log(`Escape hatch: google_api_call CUD verdicts follow profile=${policy.profile} and your allow/deny globs`);
+        console.log(`Escape hatch: google_api_call and generated tools ignore GOOGLE_WRITE_ALLOW; GOOGLE_READ_ONLY/GOOGLE_WRITE_DENY still refuse ` +
+            `outright, full-writes (no outbound allowlist) still allows outright, everything else asks a human${policy.transport === 'http' ? ' (refused immediately over HTTP: see docs/configuration.md)' : ''}; current profile=${policy.profile}`);
         const { getAccountSet } = await import('./accounts.js');
         const set = getAccountSet();
         console.log(`Default account: ${set.defaultAccount ? `${set.defaultAccount} (${set.defaultAccountSource})` : '(none — "account" is required per call)'}`);

package/dist/outbound-allowlist.d.ts

@@ -23,9 +23,42 @@ export declare function checkOutbound(kind: string, emails: string[], account: s
     }[];
     isError: true;
 } | null;
-export declare function collectBodyRecipients(body: unknown): string[];
-/** Gate one escape-hatch/generated dispatch; envelope when blocked, else null. */
-export declare function checkOutboundForMethod(methodId: string, body: unknown, account: string, env?: NodeJS.ProcessEnv): {
+export interface GranteeCheck {
+    /** Plain addresses to run through the allowlist. */
+    emails: string[];
+    /** "@domain" strings that need an exact allowlist entry. */
+    domains: string[];
+    /** A share-with-anyone / calendar-default grant: always blocked while the
+     * allowlist is active, however it is spelled, since there is no address
+     * an operator could add to permit it. */
+    public: boolean;
+    /** False when the body does not match any shape this method is known to
+     * take (a required field missing or of the wrong type): the caller fails
+     * closed instead of treating an unexamined body as grantee-free. */
+    understood: boolean;
+}
+/** Shared by drive_share's own type/domain/emailAddress args and
+ * drive_permission_update's permissions.get lookup (same resource
+ * shape, fetched instead of trusted from the body: drive.permissions.update
+ * only takes role/expirationTime, the grantee is named by the permissionId
+ * path parameter, which Google resolves server-side). */
+export declare function driveGranteeFromPermission(perm: {
+    type?: string | null;
+    domain?: string | null;
+    emailAddress?: string | null;
+} | null | undefined): GranteeCheck;
+/** The access proposal's own recipient (the person who gains access if an
+ * ACCEPT goes through), for drive_access_proposal_resolve's own
+ * accessproposals.get lookup: its own body is just an ACCEPT/DENY action,
+ * the requester is a property of the proposal itself. */
+export declare function driveGranteeFromAccessProposal(proposal: {
+    recipientEmailAddress?: string | null;
+    requesterEmailAddress?: string | null;
+} | null | undefined): GranteeCheck;
+/** Applies an already-resolved GranteeCheck against the allowlist: the
+ * entry point curated tools use once they have looked up a grantee
+ * themselves (drive_permission_update, drive_access_proposal_resolve). */
+export declare function checkOutboundGrantee(kind: string, grantee: GranteeCheck, account: string, env?: NodeJS.ProcessEnv): {
     content: {
         type: "text";
         text: string;

package/dist/outbound-allowlist.js

@@ -1,5 +1,16 @@
 // Opt-in outbound recipient allowlist: a prompt-injection blast-radius
 // control (a hijacked agent cannot mail/invite/share outside the operator's list). Off by default.
+//
+// Only serves CURATED tools now (drive_share, drive_permission_update,
+// drive_access_proposal_resolve, drive_revision_update, gmail_send/
+// create_draft/send_draft, gmail_set_vacation, calendar attendees). The
+// escape hatch (google_api_call and every generated per-method tool,
+// including the raw gmail.users.settings.delegates/forwardingAddresses/
+// sendAs/filters methods this file used to gate) no longer has its own
+// content-based reasoning here at all: a write there either fails closed
+// on an explicit deny, is allowed outright under full-writes with this
+// allowlist off, or asks a human via elicitation, who sees the real body
+// and decides (src/tools/_escape-hatch.ts).
 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). */
@@ -16,6 +27,13 @@ export function resolveOutboundAllowlist(env = process.env) {
         entries,
         allows(email) {
             const a = email.trim().toLowerCase();
+            // Reject anything that isn't a single address: a comma/semicolon/
+            // whitespace-joined string, or more than one "@", could smuggle an
+            // unlisted address alongside one that happens to make the WHOLE
+            // string pass an @domain suffix check (e.g. "evil@x.io,ok@corp.com"
+            // ends with "@corp.com") even though it names two recipients.
+            if (!a || /[,;\s]/.test(a) || a.indexOf('@') !== a.lastIndexOf('@'))
+                return false;
             if (exact.has(a))
                 return true;
             return domains.some((d) => a.endsWith(d));
@@ -56,51 +74,69 @@ export function checkOutbound(kind, emails, account, env = process.env) {
     const blocked = outboundViolations(emails, env);
     return blocked.length > 0 ? outboundDeniedEnvelope(kind, blocked, account, env) : null;
 }
-// RAW compose methods can't be inspected (base64 RFC 822), so with the
-// allowlist active they're refused outright in favor of the curated tools that enforce it.
-const RAW_SEND_METHODS = new Set(['gmail.users.messages.send', 'gmail.users.drafts.send', 'gmail.users.drafts.create', 'gmail.users.messages.insert', 'gmail.users.messages.import']);
-export function collectBodyRecipients(body) {
-    const out = [];
-    const walk = (v, depth) => {
-        if (!v || typeof v !== 'object' || depth > 4)
-            return;
-        if (Array.isArray(v)) {
-            for (const x of v)
-                walk(x, depth + 1);
-            return;
-        }
-        for (const [k, x] of Object.entries(v)) {
-            if ((k === 'emailAddress' || k === 'email') && typeof x === 'string' && x.includes('@'))
-                out.push(x);
-            else if (k === 'attendees' || k === 'permissions')
-                walk(x, depth + 1);
-            else if (typeof x === 'object')
-                walk(x, depth + 1);
-        }
+function asNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+const UNRECOGNIZED = { emails: [], domains: [], public: false, understood: false };
+/** Shared by drive_share's own type/domain/emailAddress args and
+ * drive_permission_update's permissions.get lookup (same resource
+ * shape, fetched instead of trusted from the body: drive.permissions.update
+ * only takes role/expirationTime, the grantee is named by the permissionId
+ * path parameter, which Google resolves server-side). */
+export function driveGranteeFromPermission(perm) {
+    const type = perm?.type ?? undefined;
+    if (type === 'anyone')
+        return { emails: [], domains: [], public: true, understood: true };
+    if (type === 'domain') {
+        const domain = asNonEmptyString(perm?.domain);
+        return domain ? { emails: [], domains: [`@${domain.toLowerCase()}`], public: false, understood: true } : UNRECOGNIZED;
+    }
+    if (type === 'user' || type === 'group') {
+        const email = asNonEmptyString(perm?.emailAddress);
+        return email ? { emails: [email], domains: [], public: false, understood: true } : UNRECOGNIZED;
+    }
+    return UNRECOGNIZED;
+}
+/** The access proposal's own recipient (the person who gains access if an
+ * ACCEPT goes through), for drive_access_proposal_resolve's own
+ * accessproposals.get lookup: its own body is just an ACCEPT/DENY action,
+ * the requester is a property of the proposal itself. */
+export function driveGranteeFromAccessProposal(proposal) {
+    const email = asNonEmptyString(proposal?.recipientEmailAddress) ?? asNonEmptyString(proposal?.requesterEmailAddress);
+    return email ? { emails: [email], domains: [], public: false, understood: true } : UNRECOGNIZED;
+}
+function unrecognizedShapeEnvelope(kind, account) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'recipient_not_allowed',
+                    message: `${kind} has a body shape the outbound allowlist does not recognize while it is active.`,
+                    hint: 'Refused rather than risk an unexamined grantee; check the field names against the Discovery schema for this method.',
+                    retriable: false,
+                    account,
+                }),
+            },
+        ],
+        isError: true,
     };
-    walk(body, 0);
-    return out;
 }
-/** Gate one escape-hatch/generated dispatch; envelope when blocked, else null. */
-export function checkOutboundForMethod(methodId, body, account, env = process.env) {
-    if (!resolveOutboundAllowlist(env))
+/** Applies an already-resolved GranteeCheck against the allowlist: the
+ * entry point curated tools use once they have looked up a grantee
+ * themselves (drive_permission_update, drive_access_proposal_resolve). */
+export function checkOutboundGrantee(kind, grantee, account, env = process.env) {
+    const list = resolveOutboundAllowlist(env);
+    if (!list)
         return null;
-    if (RAW_SEND_METHODS.has(methodId)) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        error: 'recipient_not_allowed',
-                        message: `${methodId} carries an uninspectable raw message while GOOGLE_OUTBOUND_ALLOWLIST is active.`,
-                        hint: 'Use gmail_send / gmail_create_draft, which enforce the allowlist on parsed recipients.',
-                        retriable: false,
-                        account,
-                    }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    return checkOutbound(`${methodId} recipient`, collectBodyRecipients(body), account, env);
+    if (!grantee.understood)
+        return unrecognizedShapeEnvelope(kind, account);
+    if (grantee.public)
+        return outboundDeniedEnvelope(`${kind} grantee`, ['anyone (public)'], account, env);
+    const blockedDomains = grantee.domains.filter((d) => !list.entries.includes(d));
+    if (blockedDomains.length > 0)
+        return outboundDeniedEnvelope(`${kind} domain grantee`, blockedDomains, account, env);
+    if (grantee.emails.length > 0)
+        return checkOutbound(`${kind} grantee`, grantee.emails, account, env);
+    return null;
 }

package/dist/registry.d.ts

@@ -63,6 +63,52 @@ export declare class ToolRegistry {
     private expanded;
     constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null, accounts?: () => AccountSet);
     registerMeta: McpServer['registerTool'];
+    /**
+     * Server-side MCP elicitation: asks the connected human to confirm an
+     * escape-hatch write. `unsupported` covers every way asking can fail
+     * (no elicitation capability, the transport cannot deliver a mid-call
+     * request, the negotiated protocol era replaced the push-style
+     * request, a timeout, a closed connection, ...) uniformly, since the
+     * caller's only correct response to any of them is the same: refuse
+     * rather than silently proceed without an answer. `cause` lets the
+     * caller phrase the refusal correctly: `http_transport` covers BOTH a
+     * self-hosted HTTP deployment and an EE hosted tenant, which this
+     * server cannot tell apart, so the caller must not suggest
+     * GOOGLE_PROFILE there (a hosted tenant cannot set it); the other
+     * causes are stdio-only, where the caller IS the operator and that
+     * suggestion is safe.
+     *
+     * `policy.transport === 'http'` refuses before ever touching
+     * elicitInput, regardless of what the client declared. This server's
+     * HTTP (EE) transport dispatches every `/mcp` call through a fresh,
+     * disposable transport with `enableJsonResponse: true` (see
+     * docs/internals.md); a mid-call server-to-client request has nothing
+     * to be delivered over there, so even a client that DID declare the
+     * capability would otherwise just hang until elicitInput's own
+     * request timeout before this failed closed anyway, not fail fast.
+     * stdio keeps one live connection for the whole call, so it is
+     * unaffected and still attempts a real elicitation below.
+     *
+     * The capability check (same pattern account-wizard.ts's form
+     * elicitation already uses) covers the remaining case on stdio: a
+     * client that never declared the capability is refused immediately
+     * too, instead of attempting the call and only finding out once
+     * elicitInput's own request timeout elapses. A bare `elicitation: {}`
+     * (no nested `form` key) still counts as form support: some clients on
+     * the 2025-06-18 protocol revision declare the capability this way,
+     * before the form/url sub-modes existed to declare.
+     *
+     * The confirmation itself gets several minutes, not the SDK's 60s
+     * request default: reading a real call and deciding is slower than a
+     * typical tool round trip (documented in docs/configuration.md).
+     */
+    elicitConfirmation(message: string): Promise<{
+        action: 'accept' | 'decline' | 'cancel';
+    } | {
+        action: 'unsupported';
+        reason: string;
+        cause: 'http_transport' | 'no_capability' | 'error';
+    }>;
     services(): string[];
     /** The registry's OWN alias list: registration-time schema builders (the
      * generated account enums) read this, never the process global. */

package/dist/registry.js

@@ -13,6 +13,10 @@ const EMPTY_SCOPES = new Set();
 // Client-side result budget for tools that do not declare their own (fat
 // readers do; see trim.ts); stays well inside a default client context limit.
 const DEFAULT_MAX_RESULT_CHARS = 50_000;
+// A human reading a real write's confirmation prompt and deciding takes far
+// longer than a typical tool round trip; the SDK's 60s request default would
+// otherwise time the ask out mid-read on a slow or distracted reviewer.
+const ELICIT_TIMEOUT_MS = 5 * 60_000;
 const DISCOVERY_MODES = ['lazy', 'curated', 'eager'];
 export function resolveDiscoveryMode(env = process.env) {
     const raw = (env.GOOGLE_DISCOVERY ?? 'lazy').trim();
@@ -208,7 +212,7 @@ export class ToolRegistry {
                 irreversible: IRREVERSIBLE_TOOLS.has(name),
                 requiredScopes: config.requiredScopes,
             });
-            const guarded = cud === 'read'
+            const guarded = cud === 'read' || config.escapeHatch
                 ? baseHandler
                 : (...args) => isAllowed({ name, service, cud, scopes: config.requiredScopes }, policy)
                     ? baseHandler(...args)
@@ -277,6 +281,68 @@ export class ToolRegistry {
             this.registeringMeta = false;
         }
     });
+    /**
+     * Server-side MCP elicitation: asks the connected human to confirm an
+     * escape-hatch write. `unsupported` covers every way asking can fail
+     * (no elicitation capability, the transport cannot deliver a mid-call
+     * request, the negotiated protocol era replaced the push-style
+     * request, a timeout, a closed connection, ...) uniformly, since the
+     * caller's only correct response to any of them is the same: refuse
+     * rather than silently proceed without an answer. `cause` lets the
+     * caller phrase the refusal correctly: `http_transport` covers BOTH a
+     * self-hosted HTTP deployment and an EE hosted tenant, which this
+     * server cannot tell apart, so the caller must not suggest
+     * GOOGLE_PROFILE there (a hosted tenant cannot set it); the other
+     * causes are stdio-only, where the caller IS the operator and that
+     * suggestion is safe.
+     *
+     * `policy.transport === 'http'` refuses before ever touching
+     * elicitInput, regardless of what the client declared. This server's
+     * HTTP (EE) transport dispatches every `/mcp` call through a fresh,
+     * disposable transport with `enableJsonResponse: true` (see
+     * docs/internals.md); a mid-call server-to-client request has nothing
+     * to be delivered over there, so even a client that DID declare the
+     * capability would otherwise just hang until elicitInput's own
+     * request timeout before this failed closed anyway, not fail fast.
+     * stdio keeps one live connection for the whole call, so it is
+     * unaffected and still attempts a real elicitation below.
+     *
+     * The capability check (same pattern account-wizard.ts's form
+     * elicitation already uses) covers the remaining case on stdio: a
+     * client that never declared the capability is refused immediately
+     * too, instead of attempting the call and only finding out once
+     * elicitInput's own request timeout elapses. A bare `elicitation: {}`
+     * (no nested `form` key) still counts as form support: some clients on
+     * the 2025-06-18 protocol revision declare the capability this way,
+     * before the form/url sub-modes existed to declare.
+     *
+     * The confirmation itself gets several minutes, not the SDK's 60s
+     * request default: reading a real call and deciding is slower than a
+     * typical tool round trip (documented in docs/configuration.md).
+     */
+    async elicitConfirmation(message) {
+        if (this.policy.transport === 'http') {
+            return {
+                action: 'unsupported',
+                reason: 'elicitation is not available over this server\'s HTTP transport',
+                cause: 'http_transport',
+            };
+        }
+        const caps = this.server.server.getClientCapabilities?.();
+        if (!caps?.elicitation || typeof caps.elicitation !== 'object') {
+            return { action: 'unsupported', reason: 'the connected client has not declared elicitation support', cause: 'no_capability' };
+        }
+        try {
+            const result = await this.server.server.elicitInput({ message, requestedSchema: { type: 'object', properties: {} } }, { timeout: ELICIT_TIMEOUT_MS });
+            if (result.action === 'accept' || result.action === 'decline' || result.action === 'cancel') {
+                return { action: result.action };
+            }
+            return { action: 'unsupported', reason: `unexpected elicitation result action "${result.action}"`, cause: 'error' };
+        }
+        catch (err) {
+            return { action: 'unsupported', reason: err instanceof Error ? err.message : String(err), cause: 'error' };
+        }
+    }
     services() {
         return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
     }

package/dist/tools/_escape-hatch.d.ts

@@ -0,0 +1,23 @@
+import type { ToolRegistry, Cud } from '../registry.js';
+import { type Policy } from '../write-control.js';
+import { jsonResult } from '../executor.js';
+export interface EscapeHatchCallInfo {
+    account: string;
+    accountEmail?: string;
+    methodId: string;
+    httpMethod: string;
+    pathParams?: Record<string, unknown>;
+    queryParams?: Record<string, unknown>;
+    body?: unknown;
+}
+/**
+ * Gate for every escape-hatch write; returns null when the call may
+ * proceed (to executeApiMethod), or a ToolResult when it must not (a
+ * hard refusal, the body could not be summarized safely, or the human
+ * declined/cancelled/could not be asked).
+ */
+export declare function escapeHatchGate(registry: ToolRegistry, denyNames: readonly string[], primaryName: string, base: {
+    service: string;
+    cud: Cud;
+    scopes?: readonly string[];
+}, policy: Policy, info: EscapeHatchCallInfo): Promise<ReturnType<typeof jsonResult> | null>;