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

package/dist/fs-atomic.js

@@ -5,23 +5,216 @@ const LOCK_TIMEOUT_MS = 5_000;
 const LOCK_RETRY_MS = 10;
 const RENAME_ATTEMPTS = 5;
 const RENAME_RETRY_MS = 20;
+// A holder this process cannot identify (another PID namespace, another boot,
+// or no /proc) is dead only once its lock is this old.
+const LOCK_LEASE_MS = 60_000;
+// Breaking a lock takes microseconds, so an older breaker file was left by a crash.
+const BREAKER_STALE_MS = 2_000;
+const PROCESS_START_MS = performance.timeOrigin;
+const OWNER_NAME = /^(\d+)\.(\d+|host)\.(\d+)\.([0-9a-f]{8}|0)\.[0-9a-f]{12}\.owner$/;
+function startOf(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const start = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+        return /^\d+$/.test(start ?? '') ? start : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function selfIdentity() {
+    const identity = { ns: 'host', start: '0', boot: '0' };
+    try {
+        identity.ns = /^pid:\[(\d+)\]$/.exec(fs.readlinkSync('/proc/self/ns/pid'))?.[1] ?? 'host';
+    }
+    catch {
+        // no /proc
+    }
+    try {
+        const boot = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').replace(/[^0-9a-f]/g, '').slice(0, 8);
+        if (boot.length === 8)
+            identity.boot = boot;
+    }
+    catch {
+        // no /proc
+    }
+    try {
+        // A /proc mounted for another PID namespace describes other processes,
+        // so no pid can be looked up in it.
+        if (fs.readlinkSync('/proc/self') === String(process.pid))
+            identity.start = startOf('self') ?? '0';
+    }
+    catch {
+        // no /proc
+    }
+    return identity;
+}
+let SELF = selfIdentity();
+/** Test hook: act as a process with this identity (undefined restores the real one). */
+export function __setLockIdentityForTest(identity) {
+    SELF = identity ?? selfIdentity();
+}
 function sleep(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+function sameFile(a, b) {
+    return a.ino === b.ino && a.dev === b.dev;
+}
+function isEnoent(error) {
+    return error.code === 'ENOENT';
+}
+// Undefined when the lock changed hands while it was being read.
+function readHolder(lock) {
+    const before = fs.lstatSync(lock, { bigint: true });
+    const body = before.isFile() ? fs.readFileSync(lock, 'utf8') : '';
+    let owner;
+    if (before.isFile()) {
+        const dir = path.dirname(lock);
+        const prefix = `${path.basename(lock)}.`;
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.startsWith(prefix))
+                continue;
+            const m = OWNER_NAME.exec(name.slice(prefix.length));
+            if (!m || m[1] !== body)
+                continue;
+            const ownerPath = path.join(dir, name);
+            try {
+                if (sameFile(fs.lstatSync(ownerPath, { bigint: true }), before)) {
+                    owner = { path: ownerPath, ns: m[2], start: m[3], boot: m[4] };
+                    break;
+                }
+            }
+            catch (error) {
+                if (!isEnoent(error))
+                    throw error;
+            }
+        }
+    }
+    const after = fs.lstatSync(lock, { bigint: true });
+    if (!sameFile(before, after))
+        return undefined;
+    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner };
+}
+// The owner file's random name tells two holders apart even when the second
+// lock reuses the first one's freed inode.
+function sameHolder(a, b) {
+    return sameFile(a, b) && a.body === b.body && a.mtimeNs === b.mtimeNs && a.owner?.path === b.owner?.path;
+}
+function probeDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        const code = error.code;
+        // EPERM: PID exists but is not signalable (another user's process).
+        if (code === 'ESRCH')
+            return true;
+        if (code !== 'EPERM')
+            throw error;
+        return false;
+    }
+}
+function holderDead(holder, now) {
+    const pid = Number(holder.body);
+    if (!(Number.isSafeInteger(pid) && pid > 0))
+        return true;
+    const leaseOver = now - holder.mtimeMs >= LOCK_LEASE_MS;
+    const owner = holder.owner;
+    // No owner file: an older writer, whose namespace is unknown.
+    if (!owner)
+        return probeDead(pid) || leaseOver;
+    if (owner.ns !== SELF.ns || owner.boot !== SELF.boot)
+        return leaseOver;
+    // Two unreadable parts compare equal without naming the same namespace or
+    // boot, so only a fully known identity is looked up by start time.
+    if (SELF.ns !== 'host' && SELF.boot !== '0' && SELF.start !== '0' && owner.start !== '0') {
+        // A live namespace id is never shared, so the recorded pid is ours to
+        // look up: a restarted container reuses both the id and the pid, but not
+        // the start time.
+        const start = startOf(pid);
+        if (start !== undefined)
+            return start !== owner.start;
+        return probeDead(pid) || leaseOver;
+    }
+    if (pid === process.pid)
+        return holder.mtimeMs < PROCESS_START_MS;
+    return probeDead(pid) || leaseOver;
+}
+// One waiter at a time breaks a dead lock: two breakers could otherwise both
+// see the dead holder, and the second would unlink the first one's new lock.
+// False when another waiter is breaking it.
+function breakLock(lock, holder) {
+    const breaker = `${lock}.break`;
+    // A token, not the inode: a breaker created after ours was removed can
+    // get our freed inode.
+    const token = `${process.pid}.${randomBytes(6).toString('hex')}`;
+    try {
+        fs.writeFileSync(breaker, token, { mode: 0o600, flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        clearStaleBreaker(breaker);
+        return false;
+    }
+    try {
+        const current = readHolder(lock);
+        if (current && sameHolder(current, holder)) {
+            fs.rmSync(lock, { force: true });
+            if (holder.owner)
+                fs.rmSync(holder.owner.path, { force: true });
+        }
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+    finally {
+        releaseBreaker(breaker, token);
+    }
+    return true;
+}
+// A symlink, or a breaker dated the other side of a clock step, would
+// otherwise block every break.
+function clearStaleBreaker(breaker) {
+    try {
+        const st = fs.lstatSync(breaker);
+        if (!st.isFile() || Math.abs(Date.now() - st.mtimeMs) >= BREAKER_STALE_MS)
+            fs.rmSync(breaker, { force: true });
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+}
+function releaseBreaker(breaker, token) {
+    try {
+        if (fs.readFileSync(breaker, 'utf8') === token)
+            fs.rmSync(breaker, { force: true });
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+}
 // Hardlink-based advisory lock, generalized path-keyed from the token store's
-// alias-keyed original (same mechanics: dead-owner recovery via signal-0 probe,
-// EPERM = alive, corrupt lock content recovered as dead, 5s timeout).
+// alias-keyed original. The lock body is the bare pid, as older readers expect;
+// the owner file stays linked while held and names the holder's process
+// instance. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     const dir = path.dirname(absPath);
     const lock = path.join(dir, `.${path.basename(absPath)}.lock`);
-    const ownerFile = `${lock}.${process.pid}.${randomBytes(6).toString('hex')}.owner`;
+    const ownerFile = `${lock}.${process.pid}.${SELF.ns}.${SELF.start}.${SELF.boot}.${randomBytes(6).toString('hex')}.owner`;
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let linked = false;
     try {
         while (true) {
             try {
                 fs.linkSync(ownerFile, lock);
+                linked = true;
                 break;
             }
             catch (error) {
@@ -29,33 +222,13 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
                 if (err.code !== 'EEXIST')
                     throw error;
                 try {
-                    const observedOwner = fs.readFileSync(lock, 'utf8');
-                    const owner = Number(observedOwner);
-                    let ownerDead = !(Number.isSafeInteger(owner) && owner > 0);
-                    if (!ownerDead) {
-                        try {
-                            process.kill(owner, 0);
-                        }
-                        catch (ownerError) {
-                            const code = ownerError.code;
-                            // EPERM: PID exists but is not signalable (recycled by another
-                            // user); treat as alive, never break a lock we cannot verify.
-                            if (code === 'ESRCH')
-                                ownerDead = true;
-                            else if (code !== 'EPERM')
-                                throw ownerError;
-                        }
-                    }
-                    if (ownerDead) {
-                        if (fs.readFileSync(lock, 'utf8') === observedOwner)
-                            fs.rmSync(lock, { force: true });
+                    const holder = readHolder(lock);
+                    if (holder && holderDead(holder, Date.now()) && breakLock(lock, holder))
                         continue;
-                    }
                 }
                 catch (readError) {
-                    if (readError.code === 'ENOENT') {
+                    if (isEnoent(readError))
                         continue;
-                    }
                     throw readError;
                 }
                 if (Date.now() >= deadline) {
@@ -66,14 +239,32 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
         }
     }
     finally {
-        fs.rmSync(ownerFile, { force: true });
+        if (!linked)
+            fs.rmSync(ownerFile, { force: true });
     }
+    let bound = false;
     try {
+        // Some network and FUSE filesystems give each name of one file its own
+        // inode number; there the owner file cannot vouch for the lock.
+        bound = sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true }));
         return fn();
     }
     finally {
-        fs.rmSync(lock, { force: true });
+        releaseLock(lock, ownerFile, bound);
+    }
+}
+// A holder whose lock was broken (its owner file removed with it) must not
+// remove its successor's lock.
+function releaseLock(lock, ownerFile, bound) {
+    try {
+        if (!bound || sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true })))
+            fs.rmSync(lock, { force: true });
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
     }
+    fs.rmSync(ownerFile, { force: true });
 }
 export function atomicWriteFileSync(absPath, contents, mode = 0o600) {
     const dir = path.dirname(absPath);

package/dist/hint-provider.d.ts

@@ -0,0 +1,129 @@
+import type { DenyReason, Policy } from './write-control.js';
+export type HintCase = {
+    kind: 'reauth';
+    account: string;
+} | {
+    kind: 'legacy_plaintext_token';
+    account: string;
+} | {
+    kind: 'dead_refresh_token';
+    account: string;
+} | {
+    kind: 'token_unreadable';
+    account: string;
+} | {
+    kind: 'scopes_missing';
+    account: string;
+} | {
+    kind: 'scope_not_granted';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_needs_bundle';
+    account: string;
+    scope: string;
+    bundle: string;
+} | {
+    kind: 'scope_base_excluded';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_account_type';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_unknown_scope';
+    scope: string;
+} | {
+    kind: 'scope_unknown';
+    account: string;
+    serviceText?: string;
+    bundle?: string;
+} | {
+    kind: 'write_denied';
+    tool: {
+        name: string;
+        service: string;
+        cud: string;
+    };
+    reason: DenyReason;
+    policy: Policy;
+} | {
+    kind: 'policy_summary';
+    policy: Policy;
+} | {
+    kind: 'outbound_denied';
+    what: string;
+    blocked: string[];
+    entries: string[];
+} | {
+    kind: 'no_default_account';
+    aliases: string[];
+} | {
+    kind: 'no_accounts';
+} | {
+    kind: 'api_not_enabled';
+    api?: string;
+    service?: string;
+    project?: string;
+    googleMessage: string;
+} | {
+    kind: 'apis_disabled';
+    services: {
+        service: string;
+        api: string;
+    }[];
+} | {
+    kind: 'daily_quota';
+} | {
+    kind: 'project_suspended';
+    account: string;
+} | {
+    kind: 'invalid_scope';
+    account: string;
+} | {
+    kind: 'no_oauth_client';
+} | {
+    kind: 'network_error';
+    code: string;
+} | {
+    kind: 'local_path';
+    code: string;
+    path?: string;
+} | {
+    kind: 'internal';
+    account?: string;
+} | {
+    kind: 'untrusted_host';
+} | {
+    kind: 'toolset_disabled';
+    api: string;
+    service: string;
+} | {
+    kind: 'service_not_enabled';
+    tool: string;
+    service: string;
+    bundle?: string;
+    aliases: string[];
+    admin: boolean;
+    toolsetOff: boolean;
+    awaitingRestart: boolean;
+} | {
+    kind: 'operator_only';
+    slug: string;
+};
+export declare const HINT_KINDS: readonly ["reauth", "legacy_plaintext_token", "dead_refresh_token", "token_unreadable", "scopes_missing", "scope_not_granted", "scope_needs_bundle", "scope_base_excluded", "scope_account_type", "scope_unknown_scope", "scope_unknown", "write_denied", "policy_summary", "outbound_denied", "no_default_account", "no_accounts", "api_not_enabled", "apis_disabled", "daily_quota", "project_suspended", "invalid_scope", "no_oauth_client", "network_error", "local_path", "internal", "untrusted_host", "toolset_disabled", "service_not_enabled", "operator_only"];
+/** `message` only for the kinds whose message leaks today (write_denied,
+ * no_oauth_client, local_path, internal, toolset_disabled); every other call
+ * site ignores it. `retriable` only where it may legitimately differ from
+ * the owner's default (scope_not_granted). */
+export interface Rendered {
+    hint: string;
+    message?: string;
+    retriable?: boolean;
+}
+export interface HintProvider {
+    render(c: HintCase): Rendered;
+}
+export declare function setHintProvider(p: HintProvider | null): void;
+export declare function hints(): HintProvider | null;

package/dist/hint-provider.js

@@ -0,0 +1,64 @@
+// A plain array literal, not derived from the union: deriving it would need a
+// value-level mirror of the type anyway, and this way a missing member is
+// caught by the completeness check below instead of silently compiling.
+// `as const` so that check narrows to the literal tuple rather than widening
+// every element back to the whole HintCase['kind'] union (which would make
+// it pass trivially, whatever was listed).
+export const HINT_KINDS = [
+    'reauth',
+    'legacy_plaintext_token',
+    'dead_refresh_token',
+    'token_unreadable',
+    'scopes_missing',
+    'scope_not_granted',
+    'scope_needs_bundle',
+    'scope_base_excluded',
+    'scope_account_type',
+    'scope_unknown_scope',
+    'scope_unknown',
+    'write_denied',
+    'policy_summary',
+    'outbound_denied',
+    'no_default_account',
+    'no_accounts',
+    'api_not_enabled',
+    'apis_disabled',
+    'daily_quota',
+    'project_suspended',
+    'invalid_scope',
+    'no_oauth_client',
+    'network_error',
+    'local_path',
+    'internal',
+    'untrusted_host',
+    'toolset_disabled',
+    'service_not_enabled',
+    'operator_only',
+];
+const _hintKindsComplete = true;
+void _hintKindsComplete;
+// Process-global, like the HTTP reauth linker: one process is either the
+// single owner or one multi-tenant host, never both.
+let installed = null;
+export function setHintProvider(p) {
+    installed = p;
+}
+// A throwing provider must never take down the call site: every call site
+// does `hints()?.render(...)?.hint ?? <default>`, so a render that cannot
+// produce a Rendered falls back to the same literal a missing provider
+// would, and the provider's own error text never reaches a client.
+export function hints() {
+    if (!installed)
+        return null;
+    const provider = installed;
+    return {
+        render(c) {
+            try {
+                return provider.render(c);
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/http-transport.d.ts

@@ -2,8 +2,10 @@ import type { McpServer, Transport } from "@modelcontextprotocol/server";
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { HttpConfig } from './http-config.js';
 import { type ArgShape, type StrictArgOptions, type ValidationEnvelopeOptions } from './arg-normalize.js';
+export { logSafe } from './trim.js';
 export type AuthOutcome = {
     ok: true;
+    sub?: string;
 } | {
     ok: false;
     status: number;
@@ -14,6 +16,16 @@ export type AuthOutcome = {
 export type Authenticator = (req: IncomingMessage) => AuthOutcome | Promise<AuthOutcome>;
 /** A mounted extra route (the AS endpoints, B13). Return true if it wrote a response. */
 export type RouteHandler = (req: IncomingMessage, res: ServerResponse, url: URL) => boolean | Promise<boolean>;
+/** What a verified subject resolves to: ITS server plus the per-request hooks
+ * bound to that server's registry (tool shapes, declared keys, the default
+ * account a validation envelope names). The metrics observers (metricsTap,
+ * onArgRename) stay host-wide and must not be bound to any one registry. */
+export interface ServerTarget {
+    server: McpServer;
+    argShapeFor?: (tool: string) => ArgShape | undefined;
+    strictArgs?: StrictArgOptions;
+    validationEnvelope?: ValidationEnvelopeOptions;
+}
 export interface HttpHostOptions {
     /** The ONE McpServer + registry built at boot (P1 / BV gap #4: never per request). */
     server: McpServer;
@@ -21,6 +33,26 @@ export interface HttpHostOptions {
     version: string;
     ownerConfigured: boolean;
     authenticate: Authenticator;
+    /** Tenant-resolution seam: map the verified subject to ITS server. Absent
+     * (free core) = every request dispatches to the one boot `server`. Return
+     * null for an unknown subject -> 403 tenant_not_found. Each distinct
+     * resolved server gets its own dispatch lane. With a resolver, the
+     * per-request hooks come from the resolved target ONLY: the host-level
+     * argShapeFor / strictArgs / validationEnvelope describe the boot server's
+     * registry, never another subject's. */
+    resolveServer?: (claims: {
+        sub: string;
+    }) => Promise<ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    }> | ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    };
     /** Extra routes keyed by exact pathname (AS endpoints mount here in B13). */
     routes?: Record<string, RouteHandler>;
     log?: (line: string) => void;
@@ -40,6 +72,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
@@ -47,17 +84,37 @@ export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
  * connector calls /mcp server-to-server with no Origin, BV-4). */
 export declare function originAllowed(origin: string | undefined, allowed: string[]): boolean;
 export declare function hostAllowed(host: string | undefined, allowed: string[]): boolean;
-/** JSON-RPC method name(s) for an observability log line — no params, no PII. */
+/** JSON-RPC method name(s) for an observability log line: no params, no PII.
+ * The method is the caller's: anything not shaped like a method name, which
+ * includes a value whose String() throws, is logged as `<invalid>`. */
 export declare function jsonRpcMethod(body: unknown): string;
 export declare class HttpTransportHost {
     private readonly opts;
     private httpServer?;
-    private lock;
+    private readonly locks;
+    private readonly depth;
+    private readonly sockets;
+    private readonly pending;
+    private readonly served;
+    private readonly handling;
+    private closing;
+    private graceful?;
     constructor(opts: HttpHostOptions);
-    private serialize;
+    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;
@@ -65,6 +122,7 @@ export declare class HttpTransportHost {
     private handle;
     private frontGuard;
     private mcp;
+    private admitted;
     private health;
     private readJson;
     private fail;