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

package/dist/auth.js

@@ -1,12 +1,10 @@
-import { OAuth2Client } from 'googleapis-common';
-import http from 'node:http';
-import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { openUrl } from './open-url.js';
 import { ACCOUNTS, getAccountSet } from './accounts.js';
-import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, isKnownBundle, resolveBundleAliases } from './scope-catalog.js';
 import { resolveMasterKey } from './master-key.js';
 import { writeToken } from './token-store.js';
+import { buildConsentClient, openLoopbackConsent, TESTING_MODE_WARNING } from './oauth-consent.js';
 // Personal (non-Workspace) accounts 403 on admin scopes; ADMIN_SCOPES stays per-account opt-in, never granted by default.
 export const BASE_SCOPES = [
     'https://www.googleapis.com/auth/gmail.modify',
@@ -50,18 +48,17 @@ function legacyGlobalProfile() {
         if (bundle === 'admin') {
             throw new Error('E_UNKNOWN_BUNDLE: "admin" is not a global bundle: grant it per account via GOOGLE_ADMIN_ACCOUNTS or an "admin: true" scope profile.');
         }
-        if (!(bundle in BUNDLE_CATALOG)) {
+        if (!isKnownBundle(bundle)) {
             const hint = closestBundle(bundle);
             throw new Error(`E_UNKNOWN_BUNDLE: unknown bundle "${bundle}" in GOOGLE_OPTIONAL_SCOPES${hint ? ` — did you mean "${hint}"?` : ''}`);
         }
     }
     return { bundles };
 }
-function profileForAccount(alias) {
+function profileForAccount(alias, set = getAccountSet()) {
     const legacy = legacyGlobalProfile();
     if (legacy)
         return legacy;
-    const set = getAccountSet();
     const name = set.configs[alias]?.scopeProfile ?? 'base';
     // hasOwn: a profile named like an Object.prototype member must never
     // resolve to the inherited function.
@@ -69,14 +66,13 @@ function profileForAccount(alias) {
 }
 /** Union of every account's resolved bundles: a service registers if ANY
  * account can authorize it; per-account authz happens at call time (BR2). */
-export function getOptionalBundles() {
+export function getOptionalBundles(set = getAccountSet()) {
     const legacy = legacyGlobalProfile();
     if (legacy)
         return legacy.bundles.filter(b => b !== 'admin');
     const union = new Set();
-    const set = getAccountSet();
     for (const alias of set.aliases) {
-        for (const b of profileForAccount(alias).bundles) {
+        for (const b of profileForAccount(alias, set).bundles) {
             if (b !== 'admin')
                 union.add(b);
         }
@@ -86,12 +82,12 @@ export function getOptionalBundles() {
 /** Aliases granted ADMIN_SCOPES: per-account admin flag (env
  * GOOGLE_ADMIN_ACCOUNTS overrides config.json at resolve) OR the account's
  * scope profile carrying admin (boolean or "admin" bundle) — equivalent forms. */
-export function getAdminAccounts() {
-    const { aliases, configs } = getAccountSet();
+export function getAdminAccounts(set = getAccountSet()) {
+    const { aliases, configs } = set;
     return aliases.filter((a) => {
         if (configs[a].admin === true)
             return true;
-        const p = profileForAccount(a);
+        const p = profileForAccount(a, set);
         return p.admin === true || p.bundles.includes('admin');
     });
 }
@@ -99,15 +95,15 @@ export function getAdminAccounts() {
  * legacy env) changes its consent set and requires re-running auth. Evaluated
  * per account: `work` can carry admin + gmail_settings while `personal` is
  * never asked for them. */
-export function resolveScopesForAccount(alias) {
-    const profile = profileForAccount(alias);
+export function resolveScopesForAccount(alias, set = getAccountSet()) {
+    const profile = profileForAccount(alias, set);
     const scopes = profile.includesBase === false ? [] : [...BASE_SCOPES];
     for (const bundle of profile.bundles) {
         if (bundle === 'admin')
             continue;
         scopes.push(...BUNDLE_CATALOG[bundle].scopes);
     }
-    if (getAdminAccounts().includes(alias)) {
+    if (getAdminAccounts(set).includes(alias)) {
         scopes.push(...ADMIN_SCOPES);
     }
     return Array.from(new Set(scopes));
@@ -134,7 +130,11 @@ export async function runAuthFlow(args) {
     // Auto-provisions on a fresh install (env > keychain > file > generate);
     // resolves eagerly so a provisioning failure surfaces before the browser opens.
     resolveMasterKey();
-    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // Shared ephemeral-port loopback flow (oauth-consent.ts): listen first, then
+    // build the auth URL from the assigned redirect. CLI gets a patient timeout;
+    // errors propagate to main()'s fatal handler like every other CLI failure.
+    const loop = await openLoopbackConsent({ timeoutMs: 10 * 60_000 });
+    const oauth2Client = buildConsentClient(loop.redirect);
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
     const authorizeUrl = oauth2Client.generateAuthUrl({
@@ -149,72 +149,13 @@ export async function runAuthFlow(args) {
     if (getAdminAccounts().includes(alias)) {
         console.log('  ⚠ Admin scopes included — this account will be granted Workspace admin access.');
     }
-    console.log(`Opening browser for authorization...`);
-    return new Promise((resolve, reject) => {
-        const server = http
-            .createServer(async (req, res) => {
-            try {
-                if (req.url && req.url.startsWith('/oauth2callback')) {
-                    const qs = new URL(req.url, 'http://localhost:4242').searchParams;
-                    const error = qs.get('error');
-                    if (error) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end(`Authorization denied: ${error}`);
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error(`Authorization denied: ${error}`));
-                        return;
-                    }
-                    const code = qs.get('code');
-                    if (!code) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('No authorization code received.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('No authorization code received'));
-                        return;
-                    }
-                    const returnedState = qs.get('state');
-                    if (returnedState !== expectedState) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('State mismatch — possible CSRF attempt. Aborting.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('OAuth state token mismatch'));
-                        return;
-                    }
-                    const { tokens } = await oauth2Client.getToken(code);
-                    writeToken(alias, tokens);
-                    res.writeHead(200, { 'Content-Type': 'text/html' });
-                    res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
-                    server.close();
-                    server.closeAllConnections();
-                    console.log(`Token saved (encrypted) for ${alias}.`);
-                    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
-                    resolve();
-                }
-            }
-            catch (e) {
-                res.writeHead(500, { 'Content-Type': 'text/plain' });
-                res.end('Internal error during authentication.');
-                server.close();
-                server.closeAllConnections();
-                reject(e);
-            }
-        })
-            // Bind to loopback only — never expose the OAuth callback to the local network.
-            .listen(4242, '127.0.0.1', () => {
-            // Always print the URL first: the browser launch is best-effort and
-            // silently does nothing on headless/SSH sessions.
-            console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
-            openUrl(authorizeUrl);
-        });
-        server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                console.error('Port 4242 is already in use. Close the process using it and retry.');
-                process.exit(1);
-            }
-            reject(err);
-        });
-    });
+    // Always print the URL first: the browser launch is best-effort and
+    // silently does nothing on headless/SSH sessions.
+    console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
+    openUrl(authorizeUrl);
+    const tokens = await loop.finish(oauth2Client, expectedState);
+    writeToken(alias, tokens);
+    console.log(`Token saved (encrypted) for ${alias}.`);
+    console.log(TESTING_MODE_WARNING);
+    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
 }

package/dist/boot-gates.d.ts

@@ -0,0 +1,26 @@
+export interface MtBootGates {
+    /** True = multi-tenant deployment: the server boots with zero accounts
+     * (tenants provision in-band) and the provisioning gate below replaces the
+     * flat owner-allowlist requirement. */
+    multiTenant: boolean;
+    /** Fail-fast replacement for the E_OWNER_EMAILS_REQUIRED check. MUST refuse
+     * (exit/throw) when no valid provisioning mechanism is configured — an
+     * ungated HTTP endpoint must never boot, whatever the condition checked. */
+    assertProvisioningGate: () => void;
+}
+export declare function setMtBootGates(g: MtBootGates | null): void;
+export declare function mtBootGates(): MtBootGates | null;
+export declare function isMultiTenantBoot(): boolean;
+/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export declare function accountsAssertRequired(wantStdio: boolean, multiTenant: boolean): boolean;
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export declare function assertNoEnvAccountsMode(env?: NodeJS.ProcessEnv): void;
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export declare function assertNoEnvOptionalScopesMode(env?: NodeJS.ProcessEnv): void;

package/dist/boot-gates.js

@@ -0,0 +1,38 @@
+// S1.16: multi-tenant boot gates. The free core never sets these — every
+// helper reduces to today's single-owner behavior when no gates are
+// installed. Deliberately a side-effect-free module (accounts.ts/auth.ts
+// resolve env at import time) so the tenancy module can import it cheaply.
+import { failStartup } from './config-file.js';
+let gates = null;
+export function setMtBootGates(g) {
+    gates = g;
+}
+export function mtBootGates() {
+    return gates;
+}
+export function isMultiTenantBoot() {
+    return gates?.multiTenant === true;
+}
+/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export function accountsAssertRequired(wantStdio, multiTenant) {
+    return wantStdio || !multiTenant;
+}
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export function assertNoEnvAccountsMode(env = process.env) {
+    if (env.GOOGLE_ACCOUNTS?.trim()) {
+        failStartup('E_ENV_ACCOUNTS_MODE_MT', 'GOOGLE_ACCOUNTS must not be set on a multi-tenant deployment; accounts are linked in-band per tenant. Unset it and restart.');
+    }
+}
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export function assertNoEnvOptionalScopesMode(env = process.env) {
+    if (env.GOOGLE_OPTIONAL_SCOPES?.trim()) {
+        failStartup('E_ENV_OPTIONAL_SCOPES_MT', 'GOOGLE_OPTIONAL_SCOPES must not be set on a multi-tenant deployment; scopes are chosen per tenant at consent. Unset it and restart.');
+    }
+}

package/dist/cimd-cache.d.ts

@@ -0,0 +1,38 @@
+export declare const CIMD_TTL_MS: number;
+/** The oldest validated document still served while the cap is full or the issuer cannot answer. */
+export declare const CIMD_MAX_STALE_MS: number;
+/** Fetches at once. A lookup can outlive the fetch that gave up on it, so ssrf-guard caps its own lookups apart. */
+export declare const CIMD_MAX_IN_FLIGHT = 4;
+export declare const CIMD_CACHE_MAX = 256;
+export type CimdDocument = Record<string, unknown>;
+type CimdError = {
+    error: 'E_CIMD_SSRF_BLOCKED' | 'E_CIMD_INVALID';
+};
+/** `fresh` is true only for the request whose fetch produced the document. */
+export type CimdResolution = {
+    doc: CimdDocument;
+    fresh: boolean;
+} | {
+    busy: true;
+} | CimdError;
+export interface CimdCacheDeps {
+    fetch: (clientId: string) => Promise<CimdDocument>;
+    now: () => number;
+    log: (line: string) => void;
+}
+export declare class CimdClientCache {
+    private readonly deps;
+    private readonly entries;
+    private readonly inFlight;
+    private busyLoggedAt;
+    private busySuppressed;
+    constructor(deps: CimdCacheDeps);
+    get size(): number;
+    /** `validate` runs once per fetch, in the request that started it, and every
+     * request waiting on that fetch gets the same answer. */
+    resolve(clientId: string, validate: (doc: CimdDocument) => boolean): Promise<CimdResolution>;
+    private fetchFor;
+    private store;
+    private noteBusy;
+}
+export {};

package/dist/cimd-cache.js

@@ -0,0 +1,117 @@
+// H4 F6: GET /authorize is unauthenticated, and a client_id on an allowlisted
+// issuer with a path never seen before forces an outbound fetch. So the
+// fetches running at once are capped, one client_id is fetched once however
+// many requests wait on it, and only a document that passed validation is
+// kept. Errors are never cached (CIMD section 5.2), and a negative cache would
+// not help anyway: the attack varies the path, so its key never repeats.
+import { CimdHttpError, isTransientFetchError, SsrfBlockedError } from './ssrf-guard.js';
+import { logSafe } from './trim.js';
+export const CIMD_TTL_MS = 5 * 60_000;
+/** The oldest validated document still served while the cap is full or the issuer cannot answer. */
+export const CIMD_MAX_STALE_MS = 24 * 60 * 60_000;
+/** Fetches at once. A lookup can outlive the fetch that gave up on it, so ssrf-guard caps its own lookups apart. */
+export const CIMD_MAX_IN_FLIGHT = 4;
+export const CIMD_CACHE_MAX = 256;
+const BUSY_LOG_EVERY_MS = 60_000;
+export class CimdClientCache {
+    deps;
+    entries = new Map();
+    // One entry per running fetch, so its size is the number of permits taken.
+    inFlight = new Map();
+    busyLoggedAt = -Infinity;
+    busySuppressed = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /** `validate` runs once per fetch, in the request that started it, and every
+     * request waiting on that fetch gets the same answer. */
+    async resolve(clientId, validate) {
+        const entry = this.entries.get(clientId);
+        const age = entry ? this.deps.now() - entry.at : 0;
+        if (entry && age < CIMD_TTL_MS)
+            return { doc: entry.doc, fresh: false };
+        if (entry && age >= CIMD_MAX_STALE_MS)
+            this.entries.delete(clientId);
+        const running = this.inFlight.get(clientId);
+        if (running) {
+            const out = await running;
+            return 'doc' in out ? { doc: out.doc, fresh: false } : out;
+        }
+        if (this.inFlight.size >= CIMD_MAX_IN_FLIGHT) {
+            // A flood of fresh paths is exactly when the cap is full, and a client
+            // that signed in before must still be able to.
+            const stale = this.entries.get(clientId);
+            if (stale)
+                return { doc: stale.doc, fresh: false };
+            this.noteBusy();
+            return { busy: true };
+        }
+        return this.fetchFor(clientId, validate);
+    }
+    async fetchFor(clientId, validate) {
+        // Never rejects: neither core nor a host installs an unhandledRejection
+        // handler, and a waiter that stopped listening must not take the process down.
+        let settle;
+        this.inFlight.set(clientId, new Promise((r) => (settle = r)));
+        let out = { error: 'E_CIMD_INVALID' };
+        try {
+            const doc = await this.deps.fetch(clientId);
+            if (validate(doc)) {
+                this.store(clientId, doc);
+                out = { doc, fresh: true };
+            }
+            else {
+                this.entries.delete(clientId);
+            }
+        }
+        catch (e) {
+            out = { error: e instanceof SsrfBlockedError ? 'E_CIMD_SSRF_BLOCKED' : 'E_CIMD_INVALID' };
+            // A document that went bad is never served stale. An issuer that is down
+            // or overloaded says nothing about the document, so the last good one
+            // stays and answers this fetch's requests too (stale-if-error; the error
+            // itself is never stored).
+            const stale = this.entries.get(clientId);
+            if (!saysNothingAboutDocument(e))
+                this.entries.delete(clientId);
+            else if (stale && this.deps.now() - stale.at < CIMD_MAX_STALE_MS)
+                out = { doc: stale.doc, fresh: false };
+            // #13: the detail goes to the log only; the caller gets a generic answer.
+            this.deps.log(`CIMD fetch failed for ${logSafe(clientId, 128)}: ${logSafe(e instanceof Error ? e.message : 'non-Error rejection', 200)}`);
+        }
+        finally {
+            this.inFlight.delete(clientId);
+            settle(out);
+        }
+        return out;
+    }
+    store(clientId, doc) {
+        this.entries.delete(clientId);
+        while (this.entries.size >= CIMD_CACHE_MAX) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        this.entries.set(clientId, { doc, at: this.deps.now() });
+    }
+    // Over-cap requests arrive at whatever rate the caller likes.
+    noteBusy() {
+        const now = this.deps.now();
+        if (now >= this.busyLoggedAt && now - this.busyLoggedAt < BUSY_LOG_EVERY_MS) {
+            this.busySuppressed++;
+            return;
+        }
+        const suppressed = this.busySuppressed;
+        this.busyLoggedAt = now;
+        this.busySuppressed = 0;
+        this.deps.log(`CIMD busy: in-flight cap reached${suppressed > 0 ? ` (n=${suppressed} suppressed)` : ''}`);
+    }
+}
+function saysNothingAboutDocument(e) {
+    if (isTransientFetchError(e))
+        return true;
+    return e instanceof CimdHttpError && (e.status === 408 || e.status === 429 || e.status >= 500);
+}

package/dist/client.d.ts

@@ -1,3 +1,33 @@
 import { OAuth2Client } from 'googleapis-common';
-import type { Account } from './accounts.js';
-export declare function getClient(account: Account): Promise<OAuth2Client>;
+import type { Account, AccountSet } from './accounts.js';
+import type { TokenData } from './types.js';
+export interface GetClientDeps {
+    /** Live account view — read at call time, never a captured snapshot. */
+    accounts: () => AccountSet;
+    readToken: (alias: string) => TokenData | null;
+    updateToken: (alias: string, updates: object) => void;
+    /** Cross-process staleness probe (single-owner global registry only). */
+    refreshIfStale?: () => void;
+}
+/** Test-only visibility into the dedupe map. */
+export declare function __inflightSizeForTest(): number;
+/**
+ * Per-context client factory: `contextKey` namespaces the single-flight map
+ * (one lane per tenant), `deps` carry that context's account view and token
+ * custody. The free core builds exactly one, bound to the global registry.
+ */
+export declare function makeGetClient(contextKey: string, deps: GetClientDeps): (account: Account) => Promise<OAuth2Client>;
+/** Injection surface for curated tool files: absent = the single-owner
+ * getClient below (today's behavior); a tenant context passes its own. */
+export interface CuratedToolDeps {
+    getClientFn?: typeof getClient;
+    /** Whether tools may read or write the server host's disk (local uploads,
+     * downloads, attachments). Absent = true; the host belongs to its operator,
+     * so a non-owner context passes false. */
+    localFiles?: boolean;
+}
+/** The single-owner client, bound to the global registry + token store. The
+ * operator surfaces that never carry a tenant (api-probe, executor and
+ * escape-hatch `deps.getClientFn ?? getClient` defaults) resolve through
+ * this. */
+export declare const getClient: (account: Account) => Promise<OAuth2Client>;

package/dist/compose.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { ServerTarget } from './http-transport.js';
+import { ToolRegistry, type DiscoveryMode } from './registry.js';
+import { type IdentityContext } from './identity.js';
+import type { Metrics } from './usage-metrics.js';
+export declare function buildRegistry(server: McpServer, ctx: IdentityContext, mode?: DiscoveryMode, metrics?: Metrics | null): ToolRegistry;
+/** The per-request hooks bound to one registry: argument shapes, unknown-
+ * argument screening and the account a validation envelope names. Both
+ * transports and every resolved server target build them here, so a mistyped
+ * argument behaves the same wherever it arrives. */
+export declare function requestHooksFor(registry: ToolRegistry, ctx: Pick<IdentityContext, 'accounts'>, metrics?: Metrics | null, env?: NodeJS.ProcessEnv): Omit<ServerTarget, 'server'>;

package/dist/compose.js

@@ -0,0 +1,109 @@
+// S1.12: registry composition, extracted from index.ts so the tenancy module
+// (and tests) can build registries without touching the CLI entrypoint. This
+// module must stay free of import-time side effects of its own: no argv
+// parsing, no process.exit, no prints (accounts.js module-load resolution is
+// the one inherited, pre-existing exception on the import chain).
+import { GENERATED_SERVICES } from './tools/generated/index.js';
+import { GENERATED_GATES, SERVICES, servicesAwaitingRestart, unknownToolMessage } from './services.js';
+import { argNormalizationEnabled } from './arg-normalize.js';
+import { unknownArgMode } from './arg-strict.js';
+import { ToolRegistry } from './registry.js';
+import { registerDiscoverTools } from './discover.js';
+import { registerEscapeTools } from './tools/google-api.js';
+import { accountHealthDepsFor, registerAccountTools } from './tools/accounts-tool.js';
+import { registerDiagnoseTool } from './doctor.js';
+import { registerAccountWizardTools } from './tools/account-wizard.js';
+import { getToolsets, toolsetEnabled } from './toolsets.js';
+import { isOwnerContext } from './identity.js';
+import { resolveScopesForAccount } from './auth.js';
+export function buildRegistry(server, ctx, mode, metrics = null) {
+    const policy = ctx.policy;
+    // The registry's account view IS the context's: fan-out expansion,
+    // selector validation and default-account injection all follow this
+    // context, not the process global (identical for the free core's one ctx).
+    const registry = new ToolRegistry(server, policy, mode, metrics, () => ctx.accounts);
+    // Every handler resolves its client, token reads and scope hints through
+    // this context; ctx.accounts is read per call, never snapshotted here, so
+    // the owner's live getter stays live.
+    const owner = isOwnerContext(ctx);
+    const clientDeps = { getClientFn: ctx.getClient, localFiles: owner };
+    const execDeps = {
+        getClientFn: ctx.getClient,
+        scopeDeps: {
+            readTokenFn: ctx.tokenStore.readToken,
+            profileFn: (alias) => resolveScopesForAccount(alias, ctx.accounts),
+        },
+    };
+    const toolsets = getToolsets();
+    if (toolsets !== 'all') {
+        const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
+        for (const requested of toolsets) {
+            if (!known.has(requested)) {
+                process.stderr.write(`GOOGLE_TOOLSETS: unknown service "${requested}" ignored\n`);
+            }
+        }
+    }
+    for (const svc of SERVICES) {
+        if (!toolsetEnabled(toolsets, svc.name))
+            continue;
+        if (svc.enabled && !svc.enabled(ctx.accounts)) {
+            if (toolsets !== 'all') {
+                const hint = svc.name === 'admin' ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS)' : `add "${svc.name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`;
+                process.stderr.write(`GOOGLE_TOOLSETS: "${svc.name}" requested but not enabled — ${hint}\n`);
+            }
+            continue;
+        }
+        svc.register(registry, clientDeps);
+    }
+    for (const gen of GENERATED_SERVICES) {
+        if (!toolsetEnabled(toolsets, gen.name))
+            continue;
+        const curated = SERVICES.find((s) => s.name === gen.name);
+        const gate = curated?.enabled ?? GENERATED_GATES[gen.name]?.enabled;
+        if (gate && !gate(ctx.accounts)) {
+            if (!curated && toolsets !== 'all') {
+                process.stderr.write(`GOOGLE_TOOLSETS: "${gen.name}" requested but not enabled — ${GENERATED_GATES[gen.name].hint}\n`);
+            }
+            continue;
+        }
+        gen.register(registry, execDeps);
+    }
+    if (registry.services().length === 0) {
+        const known = [...new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)])].sort();
+        throw new Error(`GOOGLE_TOOLSETS="${process.env.GOOGLE_TOOLSETS ?? ''}" selected no enabled services. ` +
+            `Known services: ${known.join(', ')}. ` +
+            `Note: optional services need their bundle in an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES); admin needs an admin account/profile.`);
+    }
+    registerDiscoverTools(registry, policy);
+    registerEscapeTools(registry, policy, execDeps);
+    registerAccountTools(registry, accountHealthDepsFor(ctx.tokenStore));
+    registerDiagnoseTool(registry, ctx);
+    // The wizard edits the owner's config.json and token store; any other
+    // context has neither.
+    if (owner)
+        registerAccountWizardTools(registry, server, () => servicesAwaitingRestart(registry));
+    return registry;
+}
+/** The per-request hooks bound to one registry: argument shapes, unknown-
+ * argument screening and the account a validation envelope names. Both
+ * transports and every resolved server target build them here, so a mistyped
+ * argument behaves the same wherever it arrives. */
+export function requestHooksFor(registry, ctx, metrics = null, env = process.env) {
+    const mode = unknownArgMode(env);
+    return {
+        argShapeFor: argNormalizationEnabled(env) ? (tool) => registry.argShape(tool) : undefined,
+        strictArgs: mode === 'off'
+            ? undefined
+            : {
+                mode,
+                declaredFor: (tool) => registry.declaredKeys(tool),
+                siblingsFor: (tool, keys) => registry.siblingSpellings(tool, keys),
+                unknownTool: (name) => unknownToolMessage(registry, name),
+                onDrop: metrics ? (tool, keys) => metrics.recordArgDrop(tool, keys) : undefined,
+            },
+        validationEnvelope: {
+            isKnownTool: (name) => registry.hasTool(name),
+            defaultAccount: () => ctx.accounts.defaultAccount,
+        },
+    };
+}

package/dist/config-file.d.ts

@@ -1,7 +1,20 @@
 export declare const CONFIG_VERSION = 1;
 export declare function configDir(env?: NodeJS.ProcessEnv): string;
 export declare function configFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function tenantsDir(env?: NodeJS.ProcessEnv): string;
+export declare function tenantConfigFilePath(tenantId: string, env?: NodeJS.ProcessEnv): string;
+export declare function tenantTokenDir(tenantId: string, env?: NodeJS.ProcessEnv): string;
+/** Create and permission-harden the tenant directory chain. mkdirSync's
+ * recursive mode only stamps the DEEPEST newly-created dir, so every level
+ * gets an explicit chmod: the shared tenants/ root (created by whichever
+ * tenant provisions first) must never stay group-readable. */
+export declare function ensureTenantDirs(tenantId: string, env?: NodeJS.ProcessEnv): {
+    configFile: string;
+    tokenDir: string;
+};
 export declare const ALIAS_RE: RegExp;
+export declare const RESERVED_ALIASES: string[];
+export declare function isReservedAlias(name: string): boolean;
 export interface ConfigFile {
     version: number;
     accounts?: Record<string, {
@@ -17,6 +30,7 @@ export interface ConfigFile {
     defaultAccount?: string;
     discovery?: 'lazy' | 'curated' | 'eager';
     toolsets?: string;
+    usageMetrics?: boolean;
 }
 export declare function failStartup(slug: string, message: string): never;
 export declare class ConfigFileError extends Error {

package/dist/config-file.js

@@ -10,6 +10,39 @@ export function configDir(env = process.env) {
 export function configFilePath(env = process.env) {
     return path.join(configDir(env), 'config.json');
 }
+export function tenantsDir(env = process.env) {
+    return path.join(configDir(env), 'tenants');
+}
+// A tenant id becomes a filesystem path segment exactly like an account
+// alias, so it rides the same traversal guard. 'owner' is the single-owner
+// context's subject and client lane, so no tenant may take it.
+function assertTenantId(tenantId) {
+    if (!ALIAS_RE.test(tenantId) || isReservedAlias(tenantId) || tenantId === 'owner') {
+        throw new Error(`E_TENANT_ID_INVALID: invalid tenant id "${tenantId}".`);
+    }
+}
+export function tenantConfigFilePath(tenantId, env = process.env) {
+    assertTenantId(tenantId);
+    return path.join(tenantsDir(env), tenantId, 'config.json');
+}
+export function tenantTokenDir(tenantId, env = process.env) {
+    assertTenantId(tenantId);
+    return path.join(tenantsDir(env), tenantId, 'tokens');
+}
+/** Create and permission-harden the tenant directory chain. mkdirSync's
+ * recursive mode only stamps the DEEPEST newly-created dir, so every level
+ * gets an explicit chmod: the shared tenants/ root (created by whichever
+ * tenant provisions first) must never stay group-readable. */
+export function ensureTenantDirs(tenantId, env = process.env) {
+    const tokenDir = tenantTokenDir(tenantId, env);
+    const levels = [configDir(env), tenantsDir(env), path.join(tenantsDir(env), tenantId), tokenDir];
+    for (const dir of levels) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32')
+            fs.chmodSync(dir, 0o700);
+    }
+    return { configFile: tenantConfigFilePath(tenantId, env), tokenDir };
+}
 // Alias charset is load-bearing security, not cosmetics: the alias becomes a
 // tokenDir path segment (encPath), so this guard blocks path traversal.
 export const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
@@ -22,7 +55,10 @@ const accountEntrySchema = z.strictObject({
 // masterKey, jwtKey, clientId) fails validation, structurally enforcing
 // secrets-env-only. scopeProfiles/defaultAccount/discovery/toolsets are part
 // of the frozen envelope; their consumers land in later slices.
-const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
+export const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
+export function isReservedAlias(name) {
+    return RESERVED_ALIASES.includes(name);
+}
 const configSchema = z.strictObject({
     version: z.number().int(),
     accounts: z.record(z.string().regex(ALIAS_RE), accountEntrySchema).optional(),
@@ -36,6 +72,10 @@ const configSchema = z.strictObject({
     defaultAccount: z.string().optional(),
     discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
     toolsets: z.string().optional(),
+    // Local usage metrics (metrics-feature-spec): absent = off. Downgrade rule:
+    // a pre-6.0 build reading a config carrying this key fails E_CONFIG_INVALID
+    // (strictObject); remove the key first.
+    usageMetrics: z.boolean().optional(),
 });
 export function failStartup(slug, message) {
     process.stderr.write(`${slug}: ${message}\n`);