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

package/dist/tools/_escape-hatch.js

@@ -0,0 +1,239 @@
+import { escapeHatchVerdict, writeDisabledResult } from '../write-control.js';
+import { resolveOutboundAllowlist } from '../outbound-allowlist.js';
+import { jsonResult } from '../executor.js';
+// ROUND 7 (MEDIUM 3): every DISPLAYED string is run through this first.
+// \p{Cc} (controls, incl. \n/\r/\t, which is fine: this only touches
+// individual VALUES before they are embedded in the template, never the
+// template's own line breaks), \p{Cf} (format, incl. bidi overrides),
+// \p{Zl}/\p{Zp} (U+2028/U+2029) can otherwise forge what looks like a
+// genuine new prompt line ("Body: (none)\nAccept to run it...") inside an
+// attacker-controlled value. Escaped visibly rather than stripped, so the
+// fake line reads as the literal escape text instead of silently vanishing.
+const HIDDEN_CHAR_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+function sanitizeDisplay(value) {
+    return value.replace(HIDDEN_CHAR_RE, (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
+// ROUND 7 (HIGH 2): redact by KEY NAME, never by what a value looks like.
+// The old value-shape regex (a long quoted token-looking string) is gone:
+// it swallowed real destinations (Gmail raw, Drive parents) exactly as
+// readily as a real secret, and nothing here ever sees a real secret in
+// the first place (OAuth tokens live in the token store, never in a tool
+// call's own arguments), so there is nothing to protect by value shape.
+const SECRET_KEY_RE = /(token|secret|password|passwd|authoriz|api[_-]?key|private[_-]?key|credential)/i;
+function redactSecretsByKey(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[circular]';
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactSecretsByKey(v, seen));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = SECRET_KEY_RE.test(k) ? '[redacted]' : redactSecretsByKey(v, seen);
+    }
+    return out;
+}
+// ROUND 7 (HIGH 2): what the Destinations section looks for, recursively,
+// across pathParams, queryParams and body. Two independent signals: the
+// VALUE looks like an email or a URL (wherever it sits), or the KEY looks
+// like it names a destination/target outright (a Drive parent, an owner,
+// a path param naming the resource acted on) even when the value itself
+// is just an opaque id with no recognizable shape of its own.
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const URL_RE = /\bhttps?:\/\/[^\s"'<>]+/gi;
+const DESTINATION_KEY_RE = /^(parents?|folder[_-]?id|new[_-]?owner|owner|destination|target|recipient|delegate(email)?|forwarding(email)?|send[_-]?as(email)?|grantee|member|attendee|to|cc|bcc|email(address)?|address|file[_-]?id|calendar[_-]?id|user[_-]?id|space[_-]?id|document[_-]?id|spreadsheet[_-]?id|presentation[_-]?id|drive[_-]?id|group[_-]?id|customer[_-]?id|device[_-]?id)$/i;
+const MAX_DESTINATION_LEN = 200;
+function lastKeySegment(keyPath) {
+    const cleaned = keyPath.replace(/\[\d+\]/g, '');
+    const parts = cleaned.split('.');
+    return parts[parts.length - 1] ?? '';
+}
+function collectDestinations(value, keyPath, out, seen) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string') {
+        const lastKey = lastKeySegment(keyPath);
+        if (DESTINATION_KEY_RE.test(lastKey) && value.length > 0)
+            out.push(value);
+        for (const m of value.matchAll(EMAIL_RE))
+            out.push(m[0]);
+        for (const m of value.matchAll(URL_RE))
+            out.push(m[0]);
+        return;
+    }
+    if (typeof value !== 'object')
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => collectDestinations(v, `${keyPath}[${i}]`, out, seen));
+        return;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        collectDestinations(v, keyPath ? `${keyPath}.${k}` : k, out, seen);
+    }
+}
+// ROUND 7 (HIGH 2): a Gmail `raw` field is base64url-encoded RFC 822 MIME;
+// the body summary otherwise hides its real recipients entirely. Found by
+// KEY NAME anywhere in the body (gmail.users.messages.send carries it at
+// the top level, gmail.users.drafts.update under message.raw). A `raw`
+// that fails to decode, or decodes to something with no recognizable
+// header block, cannot be summarized safely: the caller refuses rather
+// than show a confirmation that might not describe the real destination.
+const WANTED_HEADERS = ['to', 'cc', 'bcc', 'from', 'reply-to', 'subject'];
+function decodeGmailRaw(raw) {
+    if (!/^[A-Za-z0-9_-]+$/.test(raw))
+        return null;
+    let decoded;
+    try {
+        decoded = Buffer.from(raw, 'base64url').toString('utf-8');
+    }
+    catch {
+        return null;
+    }
+    if (!decoded)
+        return null;
+    const headerBlockEnd = decoded.search(/\r?\n\r?\n/);
+    const headerBlock = headerBlockEnd === -1 ? decoded : decoded.slice(0, headerBlockEnd);
+    const headers = {};
+    let current = null;
+    for (const line of headerBlock.split(/\r?\n/)) {
+        // Space before the colon is legal older RFC syntax, and a repeated header
+        // must append: overwriting would hide one recipient from the confirmation.
+        const m = /^([A-Za-z-]+)[ \t]*:\s*(.*)$/.exec(line);
+        if (m && WANTED_HEADERS.includes(m[1].toLowerCase())) {
+            current = m[1].toLowerCase();
+            headers[current] = headers[current] ? `${headers[current]}, ${m[2]}` : m[2];
+        }
+        else if (current && /^[ \t]/.test(line)) {
+            headers[current] += ` ${line.trim()}`;
+        }
+        else {
+            current = null;
+        }
+    }
+    return Object.keys(headers).length > 0 ? headers : null;
+}
+/** Every `raw` string found anywhere in `value`, by key name. */
+function collectRawFields(value, out, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectRawFields(v, out, seen);
+        return;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        if (k === 'raw' && typeof v === 'string')
+            out.push(v);
+        else
+            collectRawFields(v, out, seen);
+    }
+}
+const MAX_BODY_CHARS = 500;
+/** Builds the Destinations section and the (secret-key-redacted, length-
+ * capped) Body section for the confirmation prompt, or reports that the
+ * body cannot be summarized safely at all. Destinations are never cut:
+ * only the Body JSON is subject to the character cap. */
+function buildSummary(info) {
+    const seen = new WeakSet();
+    const destinations = [];
+    collectDestinations(info.pathParams, 'pathParams', destinations, seen);
+    collectDestinations(info.queryParams, 'queryParams', destinations, seen);
+    collectDestinations(info.body, 'body', destinations, seen);
+    const rawFields = [];
+    collectRawFields(info.body, rawFields);
+    for (const raw of rawFields) {
+        const headers = decodeGmailRaw(raw);
+        if (!headers) {
+            return { ok: false, reason: 'the request body carries a "raw" field that could not be decoded as a MIME message' };
+        }
+        for (const [name, headerValue] of Object.entries(headers)) {
+            destinations.push(`${name}: ${headerValue}`);
+        }
+    }
+    const dedupedDestinations = [...new Set(destinations)].map((d) => sanitizeDisplay(d.length > MAX_DESTINATION_LEN ? `${d.slice(0, MAX_DESTINATION_LEN)}...` : d));
+    const destinationsText = dedupedDestinations.length > 0 ? dedupedDestinations.join('; ') : '(none found)';
+    let bodyText;
+    try {
+        bodyText = JSON.stringify(redactSecretsByKey(info.body)) ?? '(none)';
+    }
+    catch {
+        return { ok: false, reason: 'the request body could not be serialized for the confirmation prompt' };
+    }
+    bodyText = sanitizeDisplay(bodyText);
+    if (bodyText.length > MAX_BODY_CHARS) {
+        bodyText = `${bodyText.slice(0, MAX_BODY_CHARS)}... (truncated, ${bodyText.length} chars total)`;
+    }
+    return { ok: true, destinationsText, bodyText };
+}
+function buildPrompt(info, summary) {
+    return [
+        'A write via the Google API escape hatch needs your confirmation.',
+        `Account: ${sanitizeDisplay(info.account)}${info.accountEmail ? ` (${sanitizeDisplay(info.accountEmail)})` : ''}`,
+        `Method: ${sanitizeDisplay(info.methodId)}`,
+        `HTTP verb: ${sanitizeDisplay(info.httpMethod)}`,
+        `Path params: ${sanitizeDisplay(JSON.stringify(info.pathParams ?? {}))}`,
+        `Query params: ${sanitizeDisplay(JSON.stringify(info.queryParams ?? {}))}`,
+        `Destinations: ${summary.destinationsText}`,
+        `Body: ${summary.bodyText}`,
+        'Accept to run it as shown; decline or cancel to refuse.',
+    ].join('\n');
+}
+const UNSUMMARIZABLE_HINT = 'Refused rather than ask with a confirmation that might not show the real destination. Use a curated tool for this operation instead, or restructure the call so its body is plain JSON (no undecodable raw content).';
+/**
+ * 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 async function escapeHatchGate(registry, denyNames, primaryName, base, policy, info) {
+    const outboundActive = resolveOutboundAllowlist() !== null;
+    const verdict = escapeHatchVerdict(denyNames, base, primaryName, policy, outboundActive);
+    if (verdict.decision === 'allow')
+        return null;
+    if (verdict.decision === 'deny')
+        return writeDisabledResult(verdict.ref, policy, info.account);
+    const summary = buildSummary(info);
+    if (!summary.ok) {
+        return jsonResult({ error: 'write_unsummarizable', message: `This write cannot be safely summarized for confirmation: ${summary.reason}.`, hint: UNSUMMARIZABLE_HINT, retriable: false, account: info.account }, true);
+    }
+    const outcome = await registry.elicitConfirmation(buildPrompt(info, summary));
+    if (outcome.action === 'accept')
+        return null;
+    if (outcome.action === 'unsupported') {
+        // Owner decision: over HTTP this covers BOTH a self-hosted HTTP
+        // deployment and an EE hosted tenant, which this server cannot tell
+        // apart, so the hint must not instruct the caller to set
+        // GOOGLE_PROFILE (a hosted tenant cannot). stdio's causes ARE the
+        // operator, so naming the env var there is safe, actionable advice.
+        if (outcome.cause === 'http_transport') {
+            return jsonResult({
+                error: 'elicitation_unsupported',
+                message: 'This write needs a human confirmation that this server cannot show yet over this connection.',
+                hint: 'Use a curated tool for this operation instead.',
+                retriable: false,
+                account: info.account,
+            }, true);
+        }
+        return jsonResult({
+            error: 'elicitation_unsupported',
+            message: `This write needs human confirmation, but the connected client could not be asked (${outcome.reason}).`,
+            hint: 'Either set GOOGLE_PROFILE=full-writes (with GOOGLE_OUTBOUND_ALLOWLIST unset) to allow escape-hatch writes without asking, or use a curated tool for this operation instead.',
+            retriable: false,
+            account: info.account,
+        }, true);
+    }
+    return jsonResult({
+        error: 'write_declined',
+        message: `The human ${outcome.action === 'decline' ? 'declined' : 'cancelled'} this write via the Google API escape hatch.`,
+        hint: 'Ask again if this should go through, or use GOOGLE_PROFILE=full-writes (with GOOGLE_OUTBOUND_ALLOWLIST unset) if escape-hatch writes should not need confirmation at all.',
+        retriable: false,
+        account: info.account,
+    }, true);
+}

package/dist/tools/_local-files.d.ts

@@ -8,5 +8,98 @@ export declare function hostFilesRefused(account: string | undefined, what: stri
     }[];
     isError: true;
 };
-export declare function prepareLocalDest(savePath: string, filename: string): string;
+/** Thrown by assertLocalPathAllowed. `reason` lets each tool render its own
+ * wording (Gmail's E_ATTACHMENT_FORBIDDEN vs Drive's generic envelope)
+ * without re-deriving the policy that produced it. */
+export declare class LocalFileError extends Error {
+    readonly reason: 'forbidden' | 'exists';
+    constructor(reason: 'forbidden' | 'exists', message: string);
+}
+/** Standard envelope for a LocalFileError, shared so Drive and Gmail's
+ * host-file tools render the same shape instead of each inventing one. */
+export declare function localFileErrorResult(error: LocalFileError, account: string | undefined): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/** GOOGLE_LOCAL_FILES_DIR, or its default, resolved but not yet checked for
+ * existence. `homedir` is a test-only override (see ensureLocalFilesRoot). */
+export declare function localFilesRoot(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/** Logs the configured (or default) root once per process, WITHOUT
+ * creating it. Safe to call eagerly at startup (and from `config check`):
+ * the root itself is created lazily, only on the first actual host-file
+ * use (see ensureLocalFilesRoot), so a read-only or missing HOME at boot
+ * (hardened systemd, an isolated service user) can never fail server
+ * startup over a feature that might never be used this run. */
+export declare function logLocalFilesRootAtStartup(env?: NodeJS.ProcessEnv, homedir?: () => string): void;
+/** Resolves GOOGLE_LOCAL_FILES_DIR (or its default) and creates it (mode
+ * 0700, owner-only) if missing. Called lazily, from assertLocalPathAllowed
+ * only, on the first actual host-file use, never at startup: mkdir can
+ * fail (a read-only or missing HOME, the root already existing as a plain
+ * file), and that failure must surface as an ordinary refused tool call,
+ * not an uncaught throw out of request handling. */
+export declare function ensureLocalFilesRoot(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+/**
+ * One policy for every host-file tool (Drive upload/update/download/export,
+ * Gmail attachments/downloads). A path must resolve, after symlinks, INSIDE
+ * GOOGLE_LOCAL_FILES_DIR (or its default, ~/Downloads/mcp-google-multi): a
+ * relative path (or filename) resolves inside that root, an absolute one
+ * must already be inside it. On top of the root, as defense in depth for a
+ * root configured too wide (e.g. $HOME), the path must also not resolve
+ * inside the server's own config/token directory (master.key, tokens/*.enc,
+ * mcp-tokens.enc), the Discovery cache dir, or /proc (which includes
+ * /proc/self/environ: the process's own environment, holding the same
+ * secrets a .env file does), nor BE one of the .env files this process
+ * actually loaded a secret from, wherever they live. `kind: 'read'`
+ * requires the path to exist (realpath resolves it directly, so a missing
+ * file's ENOENT surfaces unchanged to the caller); `kind: 'write'` only
+ * needs some leading portion to exist yet, so it resolves the deepest
+ * existing ancestor instead (see realpathDeepestExisting).
+ *
+ * Returns the resolved real path: callers should perform the actual I/O
+ * against IT, not the caller-supplied one, so a symlink swapped in after
+ * this check cannot redirect the operation.
+ */
+export declare function assertLocalPathAllowed(targetPath: string, kind: 'read' | 'write'): Promise<string>;
+/** True when GOOGLE_LOCAL_FILES is set to an off-synonym (off|0|false|no,
+ * any case, the same switch parsing as GOOGLE_USAGE_METRICS), the operator
+ * switch that removes every host-file tool/param regardless of context
+ * (see compose.ts). Unset (or empty) leaves host files at their default
+ * (enabled). An unrecognised non-empty value fails CLOSED (treated as
+ * off), with a warning: a typo in a security-relevant switch must narrow
+ * the surface, not silently widen it the way GOOGLE_USAGE_METRICS's own
+ * fail-open-to-its-default is fine to for a telemetry switch. */
+export declare function localFilesDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+/** Resolve and validate a download/export destination directory, then
+ * create it if missing. Refuses to overwrite an existing file: downloads
+ * are attacker-influenced content (a shared Drive file, an inbound
+ * attachment), so clobbering whatever is already at that path silently is
+ * never the right default. */
+export declare function prepareLocalDest(savePath: string, filename: string): Promise<string>;
+/**
+ * Cleans up after a failed exclusive (wx) write to destPath, but only when
+ * this call's own write actually started. EEXIST means the exclusive open
+ * was refused outright: this call lost a TOCTOU race (the existence check
+ * above and the real open are not atomic together) to some other call
+ * that already owns destPath, so there is nothing here that belongs to
+ * this call to delete. Any other error means this call's own fd opened
+ * and then failed partway, so the partial file it made is cleaned up as
+ * before (best-effort; the original error still wins over a failed unlink).
+ */
+export declare function cleanupPartialWrite(destPath: string, err: unknown): Promise<void>;
+/**
+ * Reads a path the SERVER itself created and fully controls (e.g.
+ * drive_transfer's download+upload fallback staging a file under
+ * os.tmpdir() before re-uploading it): this is not a caller-supplied
+ * argument, so it must not go through assertLocalPathAllowed. The
+ * GOOGLE_LOCAL_FILES_DIR root is an allow-list for host-file TOOL
+ * arguments (localPath/savePath/attachment paths); the server's own
+ * internal plumbing is not one of those, and must not even have the side
+ * effect of creating that root (it may not exist, GOOGLE_LOCAL_FILES may
+ * be off, or the caller may not be the owner; none of that should matter
+ * for a file the server made for itself and will delete when done).
+ */
+export declare function openInternalReadStream(absolutePath: string): Promise<fs.ReadStream>;
 export declare function openLocalReadStream(localPath: string): Promise<fs.ReadStream>;

package/dist/tools/_local-files.js

@@ -1,6 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { stringifyEnvelope } from './_errors.js';
+import { configDir } from '../config-file.js';
+import { getTokenDir } from '../accounts.js';
+import { discoveryCacheDir } from '../discovery-client.js';
+import { getLoadedEnvFiles } from '../env-load.js';
 /** Refusal for a host-file argument on a context that may not touch the
  * server's disk: the host belongs to its operator, not to every caller. */
 export function hostFilesRefused(account, what) {
@@ -18,26 +23,262 @@ export function hostFilesRefused(account, what) {
         isError: true,
     };
 }
-// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
-export function prepareLocalDest(savePath, filename) {
-    const name = path.basename(filename);
+/** Thrown by assertLocalPathAllowed. `reason` lets each tool render its own
+ * wording (Gmail's E_ATTACHMENT_FORBIDDEN vs Drive's generic envelope)
+ * without re-deriving the policy that produced it. */
+export class LocalFileError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'LocalFileError';
+    }
+}
+/** Standard envelope for a LocalFileError, shared so Drive and Gmail's
+ * host-file tools render the same shape instead of each inventing one. */
+export function localFileErrorResult(error, account) {
+    const code = error.reason === 'exists' ? 'local_path_exists' : 'local_path_forbidden';
+    return {
+        content: [{
+                type: 'text',
+                text: stringifyEnvelope({
+                    error: code,
+                    message: error.message,
+                    retriable: false,
+                    account,
+                }),
+            }],
+        isError: true,
+    };
+}
+// path.basename() is a traversal guard: a caller-supplied filename must never escape savePath.
+function sanitizedName(filename) {
+    return path.basename(filename);
+}
+// Case-insensitive on win32 (drive-letter/casing differences otherwise make
+// path.relative report "outside" for the same directory).
+function isInside(dir, target) {
+    let d = path.resolve(dir);
+    let t = path.resolve(target);
+    if (process.platform === 'win32') {
+        d = d.toLowerCase();
+        t = t.toLowerCase();
+    }
+    const rel = path.relative(d, t);
+    if (rel === '')
+        return true;
+    if (path.isAbsolute(rel))
+        return false;
+    // A real escape is exactly ".." (target is dir's parent) or starts with
+    // "../" (target is outside, via an ancestor); a leaf merely NAMED with
+    // leading dots (e.g. "..notes.txt", directly inside `dir`) is not an
+    // escape, even though the string also starts with the two characters "..".
+    return rel !== '..' && !rel.startsWith(`..${path.sep}`);
+}
+/** Deny if realTarget resolves inside `dir` (both realpath'd so a symlinked
+ * dir or 8.3/extended-prefix form can't slip past). */
+async function isInsideRealDir(dir, realTarget) {
+    let realDir;
+    try {
+        realDir = await fs.promises.realpath(dir);
+    }
+    catch {
+        return false; // dir does not exist → target cannot be inside it
+    }
+    return isInside(realDir, realTarget);
+}
+/** Deny if realTarget IS one of `files` (both realpath'd: a symlink to a
+ * loaded .env file is the same secret source as the file itself). */
+async function isOneOfRealFiles(files, realTarget) {
+    for (const f of files) {
+        try {
+            if ((await fs.promises.realpath(f)) === realTarget)
+                return true;
+        }
+        catch {
+            // the .env file this process loaded earlier no longer exists: nothing to match
+        }
+    }
+    return false;
+}
+/** realpath of the deepest EXISTING ancestor of `targetPath`, with the
+ * still-nonexistent tail (if any) reattached literally. A write target's
+ * leaf file, and sometimes several of its parent directories, do not exist
+ * yet, so plain realpath would just throw ENOENT; this resolves every
+ * component that DOES exist, so a symlinked ancestor directory cannot
+ * smuggle the eventual write past the confinement check below. */
+async function realpathDeepestExisting(targetPath) {
+    let current = targetPath;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = await fs.promises.realpath(current);
+            return tail.length > 0 ? path.join(real, ...tail.reverse()) : real;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw err; // reached the root and it's still missing
+            tail.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/** GOOGLE_LOCAL_FILES_DIR, or its default, resolved but not yet checked for
+ * existence. `homedir` is a test-only override (see ensureLocalFilesRoot). */
+export function localFilesRoot(env = process.env, homedir = os.homedir) {
+    const raw = env.GOOGLE_LOCAL_FILES_DIR;
+    return raw && raw.trim() !== '' ? path.resolve(raw.trim()) : path.join(homedir(), 'Downloads', 'mcp-google-multi');
+}
+let loggedRoot;
+/** Logs the configured (or default) root once per process, WITHOUT
+ * creating it. Safe to call eagerly at startup (and from `config check`):
+ * the root itself is created lazily, only on the first actual host-file
+ * use (see ensureLocalFilesRoot), so a read-only or missing HOME at boot
+ * (hardened systemd, an isolated service user) can never fail server
+ * startup over a feature that might never be used this run. */
+export function logLocalFilesRootAtStartup(env = process.env, homedir = os.homedir) {
+    try {
+        const root = localFilesRoot(env, homedir);
+        if (loggedRoot !== root) {
+            loggedRoot = root;
+            process.stderr.write(`Host-file tools (uploads, downloads, attachments), when used, are confined to: ${root}\n`);
+        }
+    }
+    catch {
+        // Best-effort only: never let a log line fail startup.
+    }
+}
+/** Resolves GOOGLE_LOCAL_FILES_DIR (or its default) and creates it (mode
+ * 0700, owner-only) if missing. Called lazily, from assertLocalPathAllowed
+ * only, on the first actual host-file use, never at startup: mkdir can
+ * fail (a read-only or missing HOME, the root already existing as a plain
+ * file), and that failure must surface as an ordinary refused tool call,
+ * not an uncaught throw out of request handling. */
+export function ensureLocalFilesRoot(env = process.env, homedir = os.homedir) {
+    const root = localFilesRoot(env, homedir);
+    try {
+        fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new LocalFileError('forbidden', `could not create or access the local-files root (${root}): ${err.message}`);
+    }
+    if (loggedRoot !== root) {
+        loggedRoot = root;
+        process.stderr.write(`Host-file tools (uploads, downloads, attachments) are confined to: ${root}\n`);
+    }
+    return root;
+}
+/**
+ * One policy for every host-file tool (Drive upload/update/download/export,
+ * Gmail attachments/downloads). A path must resolve, after symlinks, INSIDE
+ * GOOGLE_LOCAL_FILES_DIR (or its default, ~/Downloads/mcp-google-multi): a
+ * relative path (or filename) resolves inside that root, an absolute one
+ * must already be inside it. On top of the root, as defense in depth for a
+ * root configured too wide (e.g. $HOME), the path must also not resolve
+ * inside the server's own config/token directory (master.key, tokens/*.enc,
+ * mcp-tokens.enc), the Discovery cache dir, or /proc (which includes
+ * /proc/self/environ: the process's own environment, holding the same
+ * secrets a .env file does), nor BE one of the .env files this process
+ * actually loaded a secret from, wherever they live. `kind: 'read'`
+ * requires the path to exist (realpath resolves it directly, so a missing
+ * file's ENOENT surfaces unchanged to the caller); `kind: 'write'` only
+ * needs some leading portion to exist yet, so it resolves the deepest
+ * existing ancestor instead (see realpathDeepestExisting).
+ *
+ * Returns the resolved real path: callers should perform the actual I/O
+ * against IT, not the caller-supplied one, so a symlink swapped in after
+ * this check cannot redirect the operation.
+ */
+export async function assertLocalPathAllowed(targetPath, kind) {
+    const root = ensureLocalFilesRoot();
+    const absolute = path.isAbsolute(targetPath) ? targetPath : path.join(root, targetPath);
+    const realPath = kind === 'read' ? await fs.promises.realpath(absolute) : await realpathDeepestExisting(absolute);
+    if (!(await isInsideRealDir(root, realPath))) {
+        throw new LocalFileError('forbidden', `refusing to ${kind} a path outside the allowed local-files root (${root}): ${path.basename(targetPath)}`);
+    }
+    const deniedDirs = [configDir(), getTokenDir(), discoveryCacheDir(), '/proc'];
+    for (const dir of deniedDirs) {
+        if (await isInsideRealDir(dir, realPath)) {
+            throw new LocalFileError('forbidden', `refusing to ${kind} a path inside the server's config/token/cache directory, or /proc: ${path.basename(targetPath)}`);
+        }
+    }
+    if (await isOneOfRealFiles(getLoadedEnvFiles(), realPath)) {
+        throw new LocalFileError('forbidden', `refusing to ${kind} a .env file this server loaded secrets from: ${path.basename(targetPath)}`);
+    }
+    return realPath;
+}
+const LOCAL_FILES_OFF = new Set(['off', '0', 'false', 'no']);
+const LOCAL_FILES_ON = new Set(['on', '1', 'true', 'yes']);
+/** True when GOOGLE_LOCAL_FILES is set to an off-synonym (off|0|false|no,
+ * any case, the same switch parsing as GOOGLE_USAGE_METRICS), the operator
+ * switch that removes every host-file tool/param regardless of context
+ * (see compose.ts). Unset (or empty) leaves host files at their default
+ * (enabled). An unrecognised non-empty value fails CLOSED (treated as
+ * off), with a warning: a typo in a security-relevant switch must narrow
+ * the surface, not silently widen it the way GOOGLE_USAGE_METRICS's own
+ * fail-open-to-its-default is fine to for a telemetry switch. */
+export function localFilesDisabledByEnv(env = process.env) {
+    const raw = env.GOOGLE_LOCAL_FILES;
+    if (raw === undefined || raw.trim() === '')
+        return false;
+    const v = raw.trim().toLowerCase();
+    if (LOCAL_FILES_OFF.has(v))
+        return true;
+    if (LOCAL_FILES_ON.has(v))
+        return false;
+    process.stderr.write(`GOOGLE_LOCAL_FILES="${raw}" is not a valid value (off|0|false|no / on|1|true|yes); host-file tools are disabled (fail closed)\n`);
+    return true;
+}
+/** Resolve and validate a download/export destination directory, then
+ * create it if missing. Refuses to overwrite an existing file: downloads
+ * are attacker-influenced content (a shared Drive file, an inbound
+ * attachment), so clobbering whatever is already at that path silently is
+ * never the right default. */
+export async function prepareLocalDest(savePath, filename) {
+    const name = sanitizedName(filename);
     // Agents routinely repeat the leaf in both savePath and filename; a blind
     // join would bury the download in a directory named like the file itself.
     const dir = path.basename(savePath) === name ? path.dirname(savePath) : savePath;
-    const dest = path.join(dir, name);
-    fs.mkdirSync(dir, { recursive: true });
+    // Write through the SAME resolved real path that was just checked, not
+    // the caller-supplied one: re-deriving the destination from `dir` again
+    // here would let a symlink swapped in between the check and this mkdir
+    // (TOCTOU) redirect the eventual write past the check that just ran.
+    const realDir = await assertLocalPathAllowed(dir, 'write');
+    fs.mkdirSync(realDir, { recursive: true });
+    const dest = path.join(realDir, name);
+    if (fs.existsSync(dest)) {
+        throw new LocalFileError('exists', `refusing to overwrite an existing file: ${dest}`);
+    }
     return dest;
 }
+/**
+ * Cleans up after a failed exclusive (wx) write to destPath, but only when
+ * this call's own write actually started. EEXIST means the exclusive open
+ * was refused outright: this call lost a TOCTOU race (the existence check
+ * above and the real open are not atomic together) to some other call
+ * that already owns destPath, so there is nothing here that belongs to
+ * this call to delete. Any other error means this call's own fd opened
+ * and then failed partway, so the partial file it made is cleaned up as
+ * before (best-effort; the original error still wins over a failed unlink).
+ */
+export async function cleanupPartialWrite(destPath, err) {
+    if (err?.code === 'EEXIST')
+        return;
+    await fs.promises.unlink(destPath).catch(() => { });
+}
 // createReadStream's open failure surfaces as an unhandled 'error' event that
 // kills the process; opening the fd first turns it into a normal rejection.
-export async function openLocalReadStream(localPath) {
-    const handle = await fs.promises.open(localPath, 'r');
+async function openFdReadStream(absolutePath) {
+    const handle = await fs.promises.open(absolutePath, 'r');
     // open() succeeds on a directory; fail it here rather than as an async read error.
     if ((await handle.stat()).isDirectory()) {
         await handle.close();
-        throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${localPath}'`), {
+        throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${absolutePath}'`), {
             code: 'EISDIR',
-            path: localPath,
+            path: absolutePath,
         });
     }
     const stream = handle.createReadStream();
@@ -46,3 +287,22 @@ export async function openLocalReadStream(localPath) {
     stream.on('error', () => { });
     return stream;
 }
+/**
+ * Reads a path the SERVER itself created and fully controls (e.g.
+ * drive_transfer's download+upload fallback staging a file under
+ * os.tmpdir() before re-uploading it): this is not a caller-supplied
+ * argument, so it must not go through assertLocalPathAllowed. The
+ * GOOGLE_LOCAL_FILES_DIR root is an allow-list for host-file TOOL
+ * arguments (localPath/savePath/attachment paths); the server's own
+ * internal plumbing is not one of those, and must not even have the side
+ * effect of creating that root (it may not exist, GOOGLE_LOCAL_FILES may
+ * be off, or the caller may not be the owner; none of that should matter
+ * for a file the server made for itself and will delete when done).
+ */
+export async function openInternalReadStream(absolutePath) {
+    return openFdReadStream(absolutePath);
+}
+export async function openLocalReadStream(localPath) {
+    const realPath = await assertLocalPathAllowed(localPath, 'read');
+    return openFdReadStream(realPath);
+}