mcp-google-multi 6.0.0-alpha.60 → 6.0.0-alpha.62

package/dist/discovery-client.js

@@ -74,6 +74,21 @@ export function discoveryCacheDir(env = process.env) {
     return (env.DISCOVERY_CACHE_PATH ??
         path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'mcp-google-multi', 'discovery'));
 }
+// Default cache path only (an operator's DISCOVERY_CACHE_PATH may be shared,
+// even /tmp, and keeps its mode), only when this process owns it, and best
+// effort. Clears group/other bits and keeps setuid/setgid/sticky.
+function tightenOwnDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        const st = fs.statSync(dir);
+        if (st.uid === process.getuid?.() && (st.mode & 0o077) !== 0)
+            fs.chmodSync(dir, st.mode & ~0o077 & 0o7777);
+    }
+    catch {
+        // the cache still works with the directory's own mode
+    }
+}
 // A poisoned cache file could repoint baseUrl off-Google; refuse to send the
 // user's Bearer token anywhere but a googleapis.com host.
 export function isGoogleApiUrl(url) {
@@ -135,6 +150,7 @@ export async function loadMethodIndex(api, deps = {}) {
         throw new Error(`Unknown api "${api}". Known: ${Object.keys(SUPPORTED_APIS).join(', ')}`);
     }
     const fetchFn = deps.fetchFn ?? ((url) => fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) }));
+    const defaultDir = deps.cacheDir === undefined && process.env.DISCOVERY_CACHE_PATH === undefined;
     const cacheDir = deps.cacheDir ?? discoveryCacheDir();
     const cacheFile = path.join(cacheDir, `${api}.json`);
     const readCache = () => {
@@ -172,7 +188,9 @@ export async function loadMethodIndex(api, deps = {}) {
                 if (!res.ok)
                     throw new Error(`HTTP ${res.status}`);
                 doc = (await res.json());
-                fs.mkdirSync(cacheDir, { recursive: true });
+                fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+                if (defaultDir)
+                    tightenOwnDir(cacheDir);
                 fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
                 break;
             }

package/dist/http-transport.d.ts

@@ -61,6 +61,11 @@ export interface HttpHostOptions {
     onArgRename?: (tool: string, renames: number) => void;
     /** Unknown-argument screening (arg-strict.ts); absent = off. */
     strictArgs?: StrictArgOptions;
+    /** Per-server cap on /mcp requests reading their body, queued or running;
+     * the next answers 429 lane_busy before its body is read. Unset = no cap. */
+    maxQueuedPerLane?: number;
+    /** Max JSON-RPC messages in one /mcp body (default 16). */
+    maxBatchFrames?: number;
 }
 export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be
@@ -74,11 +79,28 @@ export declare class HttpTransportHost {
     private readonly opts;
     private httpServer?;
     private readonly locks;
+    private readonly depth;
+    private readonly sockets;
+    private readonly pending;
+    private readonly handling;
+    private closing;
+    private graceful?;
     constructor(opts: HttpHostOptions);
     private serializeFor;
     private log;
     start(): Promise<void>;
-    close(): Promise<void>;
+    /** Without graceMs, every connection is cut at once, even during a graceful
+     * close. With it, the host stops accepting, lets in-flight requests finish
+     * and their responses finish writing, then resolves once each client has
+     * closed its side; whatever is still open after graceMs is cut. A repeat
+     * call with graceMs during a graceful close joins it, keeping the first
+     * grace. graceMs must be a number from 0 to 2^31-1 ms (about 24.8 days, the
+     * longest delay a timer holds); anything else, Infinity included, rejects
+     * with a TypeError and leaves the host as it was. */
+    close(opts?: {
+        graceMs?: number;
+    }): Promise<void>;
+    private closeGracefully;
     /** The bound port (useful when listening on port 0 in tests). */
     address(): {
         port: number;
@@ -86,6 +108,7 @@ export declare class HttpTransportHost {
     private handle;
     private frontGuard;
     private mcp;
+    private admitted;
     private health;
     private readJson;
     private fail;

package/dist/http-transport.js

@@ -44,6 +44,38 @@ export function jsonRpcMethod(body) {
         return body.map(one).filter(Boolean).join(',') || 'batch';
     return one(body) ?? 'unknown';
 }
+/** setTimeout fires at once for a delay above this, so a longer grace would
+ * cut every connection immediately. */
+const MAX_GRACE_MS = 2 ** 31 - 1;
+// A lingering close: a socket destroyed while its client is still sending (a
+// body pipelined after the close) is reset by the kernel, which drops whatever
+// of the last response is still unsent. So the socket only ends its side and
+// waits for the client's FIN, or for the grace to end.
+function endAfterFlush(socket) {
+    if (socket.destroyed || socket.writableEnded)
+        return;
+    socket.end();
+}
+// A request that arrives while closing is never answered, so Node keeps it
+// until the socket closes, and a flood pipelined behind a held response would
+// pile up without limit. Reading stops for good instead, which lets TCP flow
+// control stop the client. Node resumes a socket after every parsed request
+// and on drain, so resume becomes a no-op. Such a socket never sees the
+// client's FIN either: the grace ends it.
+function stopReading(socket) {
+    socket.pause();
+    socket.resume = () => socket;
+}
+// For a log line: the pathname only (a query can carry a code or a state),
+// and never a throw, since the caller is the catch-all.
+function pathOf(req) {
+    try {
+        return new URL(req.url ?? '/', 'http://localhost').pathname;
+    }
+    catch {
+        return '?';
+    }
+}
 export class HttpTransportHost {
     opts;
     httpServer;
@@ -54,6 +86,16 @@ export class HttpTransportHost {
     // core has one lane (the boot server); with resolveServer each resolved
     // server gets its own, however subjects map onto servers.
     locks = new Map();
+    // Requests holding a lane slot, per server; used only with maxQueuedPerLane.
+    depth = new Map();
+    // What a graceful close waits on: open sockets, per socket the requests it
+    // has accepted whose response has not settled and the last of them, and
+    // every handle() that has not settled.
+    sockets = new Set();
+    pending = new Map();
+    handling = new Set();
+    closing = false;
+    graceful;
     constructor(opts) {
         this.opts = opts;
     }
@@ -77,7 +119,64 @@ export class HttpTransportHost {
     async start() {
         const { config } = this.opts;
         const server = createServer((req, res) => {
-            this.handle(req, res).catch((e) => this.fail(res, 500, 'internal_error', e.message));
+            const socket = req.socket;
+            // Once closing, a connection ends after the last request it accepted
+            // before the close, so one arriving now is never handled (RFC 9112 9.6).
+            // Its body is left unread: nothing reads the socket again.
+            if (this.closing) {
+                stopReading(socket);
+                return;
+            }
+            const entry = this.pending.get(socket);
+            if (entry) {
+                entry.count++;
+                entry.last = res;
+            }
+            else
+                this.pending.set(socket, { count: 1, last: res });
+            let settled = false;
+            const settle = () => {
+                if (settled)
+                    return;
+                settled = true;
+                const e = this.pending.get(socket);
+                if (!e || --e.count > 0)
+                    return;
+                this.pending.delete(socket);
+                if (this.closing)
+                    endAfterFlush(socket);
+            };
+            res.once('finish', settle);
+            res.once('close', settle);
+            // Never rejects: close() waits on it, and a catch-all that itself threw
+            // must neither reject close() nor surface as an unhandled rejection.
+            // The thrown message can name server paths (a lock timeout does), so it
+            // goes only to the host's log.
+            const done = this.handle(req, res)
+                .catch((e) => {
+                try {
+                    this.fail(res, 500, 'internal_error', 'internal error');
+                }
+                finally {
+                    // A throwing log must not reach the destroy below: the answer is sent.
+                    try {
+                        this.log(`500 internal_error path=${pathOf(req)}: ${e instanceof Error ? e.message : 'non-Error throw'}`);
+                    }
+                    catch {
+                        // nowhere left to report it
+                    }
+                }
+            })
+                .catch(() => void res.destroy());
+            this.handling.add(done);
+            void done.finally(() => this.handling.delete(done));
+        });
+        server.on('connection', (socket) => {
+            this.sockets.add(socket);
+            socket.once('close', () => {
+                this.sockets.delete(socket);
+                this.pending.delete(socket);
+            });
         });
         // Slow-loris mitigation behind the tunnel.
         server.headersTimeout = 15_000;
@@ -93,15 +192,72 @@ export class HttpTransportHost {
         });
         this.log(`listening on ${config.host}:${config.port} (public ${config.publicUrl}, transport ${config.transport})`);
     }
-    async close() {
+    /** Without graceMs, every connection is cut at once, even during a graceful
+     * close. With it, the host stops accepting, lets in-flight requests finish
+     * and their responses finish writing, then resolves once each client has
+     * closed its side; whatever is still open after graceMs is cut. A repeat
+     * call with graceMs during a graceful close joins it, keeping the first
+     * grace. graceMs must be a number from 0 to 2^31-1 ms (about 24.8 days, the
+     * longest delay a timer holds); anything else, Infinity included, rejects
+     * with a TypeError and leaves the host as it was. */
+    async close(opts = {}) {
+        const { graceMs } = opts;
+        if (graceMs !== undefined && !(typeof graceMs === 'number' && graceMs >= 0 && graceMs <= MAX_GRACE_MS)) {
+            throw new TypeError(`graceMs must be a number from 0 to ${MAX_GRACE_MS}`);
+        }
         const s = this.httpServer;
         if (!s)
             return;
-        await new Promise((resolve) => {
-            s.close(() => resolve());
-            s.closeAllConnections?.();
+        if (graceMs === undefined) {
+            await new Promise((resolve) => {
+                s.close(() => resolve());
+                s.closeAllConnections?.();
+            });
+            this.httpServer = undefined;
+            return;
+        }
+        // Starting over would destroy every socket in its lingering close.
+        this.graceful ??= this.closeGracefully(s, graceMs).finally(() => (this.graceful = undefined));
+        return this.graceful;
+    }
+    async closeGracefully(s, graceMs) {
+        this.closing = true;
+        // Node's close() also destroys every connection it deems idle, and that
+        // includes one whose response has ended but is still flushing: a large
+        // body would be cut short. Idle sockets are closed below instead.
+        const nodeIdleCloser = s.closeIdleConnections;
+        s.closeIdleConnections = () => undefined;
+        const closed = new Promise((resolve) => s.close(() => resolve()));
+        s.closeIdleConnections = nodeIdleCloser;
+        // Every request accepted before now is answered, and a connection ends
+        // after the last of them: that one says so if it has not started, and the
+        // settle hook in start() ends the socket once it finishes. Node itself
+        // destroys a socket once a Connection: close response is flushed, which
+        // resets it just as endAfterFlush explains, so that end lingers too.
+        for (const socket of this.sockets) {
+            const entry = this.pending.get(socket);
+            if (!entry) {
+                socket.destroy();
+                continue;
+            }
+            socket.destroySoon = () => endAfterFlush(socket);
+            if (!entry.last.headersSent)
+                entry.last.setHeader('Connection', 'close');
+        }
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(resolve, graceMs);
         });
-        this.httpServer = undefined;
+        try {
+            await Promise.race([closed.then(() => Promise.all(this.handling)), expired]);
+        }
+        finally {
+            clearTimeout(timer);
+            s.closeAllConnections();
+            await closed;
+            this.httpServer = undefined;
+            this.closing = false;
+        }
     }
     /** The bound port (useful when listening on port 0 in tests). */
     address() {
@@ -154,6 +310,14 @@ export class HttpTransportHost {
         }
         if (!this.frontGuard(req, res))
             return;
+        // Registered before anything awaits: a client that leaves while its request
+        // waits on the lane must not have it dispatched once its turn comes. A
+        // response queued behind another on its connection never emits 'close', so
+        // the socket is checked too.
+        let gone = false;
+        res.once('close', () => (gone = true));
+        const socket = req.socket;
+        const clientGone = () => gone || socket.destroyed;
         const auth = await this.opts.authenticate(req);
         if (!auth.ok) {
             for (const [k, v] of Object.entries(auth.headers ?? {}))
@@ -186,6 +350,31 @@ export class HttpTransportHost {
                 return;
             }
         }
+        // Checked before the body read, so a refused request never buffers its body.
+        const cap = this.opts.maxQueuedPerLane;
+        if (cap === undefined)
+            return this.admitted(req, res, target, sub, clientGone);
+        const lane = target.server;
+        const held = this.depth.get(lane) ?? 0;
+        if (held >= cap) {
+            res.setHeader('Retry-After', '1');
+            this.fail(res, 429, 'lane_busy', 'too many requests are already queued for this server');
+            this.log('429 lane_busy path=/mcp');
+            return;
+        }
+        this.depth.set(lane, held + 1);
+        try {
+            await this.admitted(req, res, target, sub, clientGone);
+        }
+        finally {
+            const left = (this.depth.get(lane) ?? 1) - 1;
+            if (left > 0)
+                this.depth.set(lane, left);
+            else
+                this.depth.delete(lane);
+        }
+    }
+    async admitted(req, res, target, sub, clientGone) {
         // Thread the verified subject to tool handlers: the Node transport forwards
         // req.auth verbatim as ctx.http.authInfo. Token/clientId stay empty — the
         // bearer value must not re-enter the dispatch path via handler context.
@@ -202,8 +391,9 @@ export class HttpTransportHost {
         catch (e) {
             return this.fail(res, 400, 'invalid_body', e.message);
         }
-        if (Array.isArray(body) && body.length > MAX_BATCH_FRAMES) {
-            return this.fail(res, 400, 'batch_too_large', `a JSON-RPC batch may hold at most ${MAX_BATCH_FRAMES} messages`);
+        const maxFrames = this.opts.maxBatchFrames ?? MAX_BATCH_FRAMES;
+        if (Array.isArray(body) && body.length > maxFrames) {
+            return this.fail(res, 400, 'batch_too_large', `a JSON-RPC batch may hold at most ${maxFrames} messages`);
         }
         // Host/Origin are enforced by the front guard above (uniformly for /mcp and
         // the mounted AS routes), so the SDK's own DNS-rebind guard is disabled: its
@@ -229,6 +419,10 @@ export class HttpTransportHost {
         // subjects to one) would otherwise race it through the connect gap.
         const { server: mcpServer, argShapeFor, strictArgs, validationEnvelope } = target;
         await this.serializeFor(mcpServer, async () => {
+            if (clientGone()) {
+                this.log('499 client_gone path=/mcp');
+                return;
+            }
             const disconnected = new Promise((resolve) => res.once('close', () => resolve('closed')));
             let timer;
             const timedOut = new Promise((resolve) => {
@@ -294,6 +488,10 @@ export class HttpTransportHost {
     readJson(req) {
         const max = this.opts.maxBodyBytes ?? 4_000_000;
         return new Promise((resolve, reject) => {
+            // A client that left while the request was authenticated or resolved has
+            // already destroyed it, and no 'end' or 'error' would ever follow.
+            if (req.destroyed)
+                return reject(new Error('request aborted'));
             let size = 0;
             const chunks = [];
             req.on('data', (c) => {
@@ -322,6 +520,12 @@ export class HttpTransportHost {
     fail(res, status, error, message) {
         if (res.writableEnded)
             return;
+        // A response already started cannot become an error one; cutting it tells
+        // the client it is incomplete.
+        if (res.headersSent) {
+            res.destroy();
+            return;
+        }
         res.writeHead(status, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error, message }));
     }

package/dist/mcp-token.d.ts

@@ -110,8 +110,7 @@ export declare class RefreshStore {
         sub: string;
     } | null;
     /** Drop every ACTIVE record minted under `sub` (linear scan under the store
-     * lock). Spent entries carry no sub and stay: with their families gone, a
-     * reuse finds nothing to revoke — inert by construction. Returns the number
-     * of active tokens dropped. */
+     * lock); the save then drops the spent entries of every family left with no
+     * active token. Returns the number of active tokens dropped. */
     purgeTenant(sub: string): number;
 }

package/dist/mcp-token.js

@@ -155,11 +155,42 @@ export class RefreshStore {
         }
     }
     save(data) {
-        // bound the spent set (drop oldest-inserted) so it can't grow forever.
-        const keys = Object.keys(data.spent);
-        if (keys.length > SPENT_CAP) {
-            for (const k of keys.slice(0, keys.length - SPENT_CAP))
-                delete data.spent[k];
+        // A family with no active token has nothing left to revoke. Over the cap,
+        // the subject holding the most spent tokens loses its oldest (ties: the
+        // oldest entry), so a subject's rotations, across all its families, only
+        // push out its own history (docs/internals.md). Insertion order = rotation
+        // order.
+        const owner = new Map();
+        for (const r of Object.values(data.active))
+            owner.set(r.family, r.sub);
+        const order = Object.keys(data.spent);
+        const held = new Map();
+        let total = 0;
+        order.forEach((t, i) => {
+            const sub = owner.get(data.spent[t]);
+            if (sub === undefined) {
+                delete data.spent[t];
+                return;
+            }
+            const h = held.get(sub);
+            if (h)
+                h.at.push(i);
+            else
+                held.set(sub, { at: [i], head: 0 });
+            total += 1;
+        });
+        while (total > SPENT_CAP) {
+            let most = { at: [], head: 0 };
+            let mostN = 0;
+            for (const h of held.values()) {
+                const n = h.at.length - h.head;
+                if (n > mostN || (n === mostN && n > 0 && h.at[h.head] < most.at[most.head])) {
+                    most = h;
+                    mostN = n;
+                }
+            }
+            delete data.spent[order[most.at[most.head++]]];
+            total -= 1;
         }
         atomicWriteFileSync(this.path, encryptToken(data, this.masterKey), 0o600);
     }
@@ -212,9 +243,8 @@ export class RefreshStore {
         });
     }
     /** Drop every ACTIVE record minted under `sub` (linear scan under the store
-     * lock). Spent entries carry no sub and stay: with their families gone, a
-     * reuse finds nothing to revoke — inert by construction. Returns the number
-     * of active tokens dropped. */
+     * lock); the save then drops the spent entries of every family left with no
+     * active token. Returns the number of active tokens dropped. */
     purgeTenant(sub) {
         return withFileLock(this.path, () => {
             const data = this.load();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.60",
+  "version": "6.0.0-alpha.62",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",