mcp-google-multi 5.4.1-alpha.2 → 6.0.0-alpha.2

package/dist/http-transport.js

@@ -0,0 +1,269 @@
+// B12: the Streamable HTTP transport host (cc-transport-hosting T2/T3). Owns the
+// node:http server, the route table, the front guard (Host / Origin / DNS-rebind),
+// and the stateless per-request /mcp dispatch. The OAuth AS endpoints and Bearer
+// verification are a seam filled by B13 (oauth-authorization-server); B12 ships a
+// loopback-owner authenticator so the local-HTTP model works before the AS lands.
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+// A hung handler that keeps the connection open would otherwise hold the global
+// serialize() lock forever. Generous by default so slow-but-valid calls (large
+// Drive exports, fan-out) still finish; the point is only to guarantee release.
+const DISPATCH_TIMEOUT_DEFAULT = 120_000;
+export function parseOwnerEmails(env = process.env) {
+    return (env.MCP_OWNER_EMAILS ?? '')
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+/** Front guard: an Origin, if present, must be allowlisted; a Host must be
+ * allowlisted. Absent Origin passes (native/CLI/backend clients — the claude.ai
+ * connector calls /mcp server-to-server with no Origin, BV-4). */
+export function originAllowed(origin, allowed) {
+    if (!origin)
+        return true;
+    return allowed.includes(origin);
+}
+export function hostAllowed(host, allowed) {
+    if (allowed.length === 0)
+        return true;
+    if (!host)
+        return false;
+    // Port-agnostic, matching the SDK's DNS-rebind guard: allow an exact match or
+    // the bare hostname (allowedHosts carries both host[:port] and bare forms).
+    const bare = host.replace(/:\d+$/, '');
+    return allowed.includes(host) || allowed.includes(bare);
+}
+/** JSON-RPC method name(s) for an observability log line — no params, no PII. */
+export function jsonRpcMethod(body) {
+    const one = (b) => b && typeof b === 'object' && 'method' in b ? String(b.method) : undefined;
+    if (Array.isArray(body))
+        return body.map(one).filter(Boolean).join(',') || 'batch';
+    return one(body) ?? 'unknown';
+}
+export class HttpTransportHost {
+    opts;
+    httpServer;
+    // Serialize the connect→dispatch critical section: the shared McpServer
+    // captures its transport per request (protocol.js), but the gap between
+    // connect() and the dispatch capturing it would still race under true
+    // concurrency. Single-owner HTTP traffic is effectively serial, so a mutex
+    // keeps correctness at negligible cost (and never rebuilds the registry).
+    lock = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    serialize(fn) {
+        const run = this.lock.then(fn, fn);
+        this.lock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    log(line) {
+        this.opts.log?.(line);
+    }
+    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));
+        });
+        // Slow-loris mitigation behind the tunnel.
+        server.headersTimeout = 15_000;
+        server.requestTimeout = 30_000;
+        this.httpServer = server;
+        await new Promise((resolve, reject) => {
+            const onErr = (e) => reject(e);
+            server.once('error', onErr);
+            server.listen(config.port, config.host, () => {
+                server.off('error', onErr);
+                resolve();
+            });
+        });
+        this.log(`listening on ${config.host}:${config.port} (public ${config.publicUrl}, transport ${config.transport})`);
+    }
+    async close() {
+        const s = this.httpServer;
+        if (!s)
+            return;
+        await new Promise((resolve) => {
+            s.close(() => resolve());
+            s.closeAllConnections?.();
+        });
+        this.httpServer = undefined;
+    }
+    /** The bound port (useful when listening on port 0 in tests). */
+    address() {
+        const a = this.httpServer?.address();
+        return a && typeof a === 'object' ? { port: a.port } : undefined;
+    }
+    async handle(req, res) {
+        // req.url is the path+query; parse against a FIXED base so a malformed/hostile
+        // Host header can't throw here (the Host is validated in the front guard).
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const path = url.pathname;
+        if (path === '/health') {
+            if (req.method !== 'GET') {
+                res.setHeader('Allow', 'GET');
+                return this.fail(res, 405, 'method_not_allowed', 'GET /health only');
+            }
+            return this.health(res);
+        }
+        const route = this.opts.routes?.[path];
+        if (route) {
+            if (!this.frontGuard(req, res))
+                return;
+            const handled = await route(req, res, url);
+            if (!handled && !res.writableEnded)
+                this.fail(res, 404, 'not_found', `No handler for ${path}`);
+            return;
+        }
+        if (path === '/mcp')
+            return this.mcp(req, res);
+        this.fail(res, 404, 'not_found', `Unknown path ${path}`);
+    }
+    frontGuard(req, res) {
+        const { allowedHosts, allowedOrigins } = this.opts.config;
+        if (!hostAllowed(req.headers.host, allowedHosts)) {
+            this.log(`403 host_rejected host=${req.headers.host ?? ''}`);
+            this.fail(res, 403, 'host_rejected', 'Host not allowed (DNS-rebinding guard).');
+            return false;
+        }
+        if (!originAllowed(req.headers.origin, allowedOrigins)) {
+            this.log(`403 origin_rejected origin=${req.headers.origin ?? ''}`);
+            this.fail(res, 403, 'origin_rejected', 'Origin not allowed.');
+            return false;
+        }
+        return true;
+    }
+    async mcp(req, res) {
+        if (req.method !== 'POST') {
+            res.setHeader('Allow', 'POST');
+            return this.fail(res, 405, 'method_not_allowed', 'POST /mcp only (stateless mode; no GET SSE).');
+        }
+        if (!this.frontGuard(req, res))
+            return;
+        const auth = await this.opts.authenticate(req);
+        if (!auth.ok) {
+            for (const [k, v] of Object.entries(auth.headers ?? {}))
+                res.setHeader(k, v);
+            res.writeHead(auth.status, { 'Content-Type': 'application/json' });
+            res.end(auth.body);
+            this.log(`${auth.status} auth_failed path=/mcp`);
+            return;
+        }
+        let body;
+        try {
+            body = await this.readJson(req);
+        }
+        catch (e) {
+            return this.fail(res, 400, 'invalid_body', e.message);
+        }
+        // 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
+        // exact-Host match is stricter than the front guard and would 403 valid
+        // Hosts (double enforcement, differing rules).
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+            enableDnsRebindingProtection: false,
+        });
+        // The shared McpServer holds exactly one connected transport at a time, so
+        // connect + dispatch + DISCONNECT all run inside the mutex: the next request
+        // can never hit "Already connected". The serialized section is guaranteed to
+        // settle three ways — the handler finishes, the client disconnects (res
+        // 'close'), or a dispatch deadline fires — so neither a client that holds the
+        // connection open nor a hung upstream can wedge the lock. The transport is
+        // closed in a finally (which resets server._transport) before the lock
+        // releases. (A shared initialized-state persists across stateless requests;
+        // benign for the single-owner design.)
+        const deadlineMs = this.opts.dispatchTimeoutMs ?? DISPATCH_TIMEOUT_DEFAULT;
+        await this.serialize(async () => {
+            const disconnected = new Promise((resolve) => res.once('close', () => resolve('closed')));
+            let timer;
+            const timedOut = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), deadlineMs);
+                timer.unref?.();
+            });
+            await this.opts.server.connect(transport);
+            // Reflect the dispatch into a non-rejecting arm: if the deadline wins the
+            // race, an orphaned handler settling later must not surface as an unhandled
+            // rejection — but a genuine dispatch error still propagates (rethrown below).
+            let dispatchErr;
+            const dispatchArm = transport
+                .handleRequest(req, res, body)
+                .then(() => 'done', (e) => {
+                dispatchErr = e;
+                return 'error';
+            });
+            try {
+                const outcome = await Promise.race([dispatchArm, disconnected, timedOut]);
+                if (outcome === 'error')
+                    throw dispatchErr;
+                if (outcome === 'timeout') {
+                    this.log('504 dispatch_timeout path=/mcp');
+                    if (!res.headersSent) {
+                        res.writeHead(504, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'dispatch_timeout', message: 'the handler exceeded the dispatch deadline' }));
+                    }
+                    else {
+                        res.destroy();
+                    }
+                }
+                else if (outcome === 'done') {
+                    // Success path: close the observability gap (failures already log; a
+                    // completed dispatch logged nothing). Method only — no params, no PII.
+                    this.log(`200 /mcp method=${jsonRpcMethod(body)}`);
+                }
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                await transport.close().catch(() => undefined);
+            }
+        });
+    }
+    health(res) {
+        const { config, ownerConfigured, version } = this.opts;
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        // No secrets, no owner emails (cc-transport-hosting /health rule).
+        res.end(JSON.stringify({
+            status: 'ok',
+            transport: config.transport,
+            publicUrl: config.publicUrl,
+            ownerConfigured,
+            version,
+        }));
+    }
+    readJson(req) {
+        const max = this.opts.maxBodyBytes ?? 4_000_000;
+        return new Promise((resolve, reject) => {
+            let size = 0;
+            const chunks = [];
+            req.on('data', (c) => {
+                size += c.length;
+                if (size > max) {
+                    reject(new Error('request body too large'));
+                    req.destroy();
+                    return;
+                }
+                chunks.push(c);
+            });
+            req.on('end', () => {
+                const raw = Buffer.concat(chunks).toString('utf-8');
+                if (raw.trim() === '')
+                    return resolve(undefined);
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch {
+                    reject(new Error('request body is not valid JSON'));
+                }
+            });
+            req.on('error', reject);
+        });
+    }
+    fail(res, status, error, message) {
+        if (res.writableEnded)
+            return;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error, message }));
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,24 @@
+import type { AccountSet } from './accounts.js';
+import { getClient } from './client.js';
+import { hasToken, readToken, updateToken, writeToken } from './token-store.js';
+import { type Policy, type Transport } from './write-control.js';
+/**
+ * The one forward-compat seam (frozen public API): the free core builds
+ * exactly one context with subject "owner"; EE later instantiates N contexts
+ * from N registries. Nothing here may assume a global current-account.
+ */
+export interface IdentityContext {
+    subject: 'owner';
+    accounts: AccountSet;
+    policy: Policy;
+    getClient: typeof getClient;
+    tokenStore: {
+        readToken: typeof readToken;
+        writeToken: typeof writeToken;
+        updateToken: typeof updateToken;
+        hasToken: typeof hasToken;
+    };
+}
+export declare function buildIdentityContext(env?: NodeJS.ProcessEnv, opts?: {
+    transport?: Transport;
+}): IdentityContext;

package/dist/identity.js

@@ -0,0 +1,19 @@
+import { getAccountSet } from './accounts.js';
+import { getClient } from './client.js';
+import { hasToken, readToken, updateToken, writeToken } from './token-store.js';
+import { resolvePolicy } from './write-control.js';
+export function buildIdentityContext(env = process.env, opts = {}) {
+    return {
+        subject: 'owner',
+        // Live getter: the seam must always see the current registry, never a
+        // snapshot pinned from before a wizard mutation or cross-process reload.
+        get accounts() {
+            return getAccountSet();
+        },
+        // The dispatch transport rides into the resolved policy as a reserved seam
+        // (cc-write-control B14); it does not change any write-control verdict.
+        policy: resolvePolicy(env, { transport: opts.transport }),
+        getClient,
+        tokenStore: { readToken, writeToken, updateToken, hasToken },
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import './accounts.js';
+export {};

package/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import './accounts.js';
+// First import: triggers accounts.js module load (env files + registry) before
+// anything else. Named to also pull the server-only empty-registry guard (BR-4).
+import { assertServerAccountsConfigured } from './accounts.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -11,12 +13,19 @@ import { ToolRegistry } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
 import { registerEscapeTools } from './tools/google-api.js';
 import { 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 { resolvePolicy, isAllowed, describePolicy } from './write-control.js';
+import { isAllowed, describePolicy } from './write-control.js';
+import { buildIdentityContext } from './identity.js';
+import { registerSetupPrompt } from './setup-prompt.js';
+import { applyNetTuning } from './net-tuning.js';
+applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-function buildRegistry(server, policy) {
-    const registry = new ToolRegistry(server, policy);
+function buildRegistry(server, ctx, mode) {
+    const policy = ctx.policy;
+    const registry = new ToolRegistry(server, policy, mode);
     const toolsets = getToolsets();
     if (toolsets !== 'all') {
         const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
@@ -31,7 +40,7 @@ function buildRegistry(server, policy) {
             continue;
         if (svc.enabled && !svc.enabled()) {
             if (toolsets !== 'all') {
-                const hint = svc.name === 'admin' ? 'set GOOGLE_ADMIN_ACCOUNTS' : `add "${svc.name}" to GOOGLE_OPTIONAL_SCOPES`;
+                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;
@@ -55,11 +64,13 @@ function buildRegistry(server, policy) {
         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 require their bundle in GOOGLE_OPTIONAL_SCOPES, admin requires GOOGLE_ADMIN_ACCOUNTS.`);
+            `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);
     registerAccountTools(registry);
+    registerDiagnoseTool(registry);
+    registerAccountWizardTools(registry, server);
     return registry;
 }
 async function main() {
@@ -73,9 +84,40 @@ async function main() {
         runMigrateTokens();
         return;
     }
+    if (process.argv.includes('migrate-config')) {
+        const { runMigrateConfig } = await import('./migrate-config.js');
+        runMigrateConfig();
+        return;
+    }
+    if (process.argv.includes('doctor')) {
+        const { runDoctorCli } = await import('./doctor.js');
+        process.exitCode = await runDoctorCli(process.argv, pkg.version);
+        return;
+    }
+    if (process.argv.includes('reset')) {
+        const { runResetCli } = await import('./doctor.js');
+        process.exitCode = await runResetCli(process.argv);
+        return;
+    }
+    if (process.argv.includes('write-client-config')) {
+        const { runWriteClientConfigCli } = await import('./client-config.js');
+        process.exitCode = await runWriteClientConfigCli(process.argv);
+        return;
+    }
+    if (process.argv.includes('account') && process.argv.includes('export')) {
+        const { runExportCli } = await import('./registry-transfer.js');
+        process.exitCode = await runExportCli(process.argv);
+        return;
+    }
+    if (process.argv.includes('account') && process.argv.includes('import')) {
+        const { runImportCli } = await import('./registry-transfer.js');
+        process.exitCode = await runImportCli(process.argv);
+        return;
+    }
     if (process.argv.includes('config') && process.argv.includes('check')) {
-        const policy = resolvePolicy();
-        const registry = buildRegistry(new McpServer({ name: 'mcp-google-multi', version: pkg.version }), policy);
+        const ctx = buildIdentityContext();
+        const policy = ctx.policy;
+        const registry = buildRegistry(new McpServer({ name: 'mcp-google-multi', version: pkg.version }), ctx);
         const cud = registry.tools.filter((t) => t.cud !== 'read');
         const disabled = cud.filter((t) => !isAllowed(t, policy));
         const counts = registry.visibleCount();
@@ -96,19 +138,158 @@ async function main() {
         }
         console.log(`Disabled: ${disabledLine}`);
         console.log(`Services: ${registry.services().join(', ')}`);
-        console.log(`Tool surface: ${counts.eager} eager (discover + escape hatch), ${counts.hidden} deferred until discovery`);
+        console.log(`Discovery mode: ${registry.mode}${registry.mode === 'lazy' ? ' (expand at runtime with discover_all)' : ''}`);
+        console.log(`Tool surface: ${counts.eager} eager (discover + escape hatch), ${counts.revealed} advertised, ${counts.hidden} deferred`);
         console.log(`Escape hatch: google_api_call CUD verdicts follow profile=${policy.profile} and your allow/deny globs`);
+        const { getAccountSet } = await import('./accounts.js');
+        const set = getAccountSet();
+        console.log(`Default account: ${set.defaultAccount ? `${set.defaultAccount} (${set.defaultAccountSource})` : '(none — "account" is required per call)'}`);
+        const { peekMasterKeyProvenance } = await import('./master-key.js');
+        const prov = peekMasterKeyProvenance();
+        console.log(`MASTER_KEY: ${prov === 'unprovisioned' ? 'unprovisioned (will be generated on first use)' : prov}`);
+        try {
+            const { resolveHttpConfig, transportIncludesHttp } = await import('./http-config.js');
+            const http = resolveHttpConfig();
+            console.log(`Transport: ${http.transport}`);
+            if (transportIncludesHttp(http.transport)) {
+                console.log(`  HTTP bind: ${http.host}:${http.port}`);
+                console.log(`  Public URL: ${http.publicUrl} (resource ${http.resourceUri})`);
+                console.log(`  Allowed hosts: ${http.allowedHosts.join(', ')}`);
+                console.log(`  Allowed origins: ${http.allowedOrigins.join(', ')}`);
+            }
+        }
+        catch (e) {
+            console.log(`Transport: (config error) ${e.message}`);
+        }
         return;
     }
-    const policy = resolvePolicy();
-    const server = new McpServer({
-        name: 'mcp-google-multi',
-        version: pkg.version,
-    });
-    const registry = buildRegistry(server, policy);
-    registry.installListHandler();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    // BR-4: the SERVER never boots with an empty registry. The bootstrap and
+    // diagnostic CLIs above already returned; a fresh user configures accounts
+    // (env / migrate-config / account import / auth) before the server runs.
+    assertServerAccountsConfigured();
+    // Resolve (or provision) the master key BEFORE serving: the hard guard is
+    // specced "fatal at startup", never mid-dispatch.
+    const { resolveMasterKey } = await import('./master-key.js');
+    resolveMasterKey();
+    const { resolveHttpConfig, transportIncludesHttp } = await import('./http-config.js');
+    let httpCfg;
+    try {
+        httpCfg = resolveHttpConfig();
+    }
+    catch (e) {
+        process.stderr.write(`Fatal: ${e.message}\n`);
+        process.exit(1);
+    }
+    const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
+    const wantHttp = transportIncludesHttp(httpCfg.transport);
+    // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
+    // never rebuilt per request); `both` runs the two concurrently.
+    if (wantStdio) {
+        const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
+        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }));
+        registry.installListHandler();
+        registerSetupPrompt(server);
+        await server.connect(new StdioServerTransport());
+    }
+    if (wantHttp) {
+        const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
+        // BR3 / C13: the owner allowlist is the entire multi-tenant collapse; refuse
+        // to open an ungated HTTP endpoint.
+        const owners = parseOwnerEmails(process.env);
+        if (owners.length === 0) {
+            process.stderr.write('E_OWNER_EMAILS_REQUIRED: MCP_TRANSPORT includes http but MCP_OWNER_EMAILS is empty. Set MCP_OWNER_EMAILS to the Google email(s) allowed to authenticate.\n');
+            process.exit(1);
+        }
+        // BR7: stateless HTTP cannot push tools/list_changed, so it forces curated.
+        const configuredMode = (process.env.GOOGLE_DISCOVERY ?? '').trim().toLowerCase();
+        if (configuredMode && configuredMode !== 'curated') {
+            process.stderr.write(`GOOGLE_DISCOVERY="${configuredMode}" is ignored over HTTP; the stateless transport forces "curated".\n`);
+        }
+        const httpServer = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
+        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated');
+        registry.installListHandler();
+        registerSetupPrompt(httpServer);
+        // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
+        const { buildAuthServer } = await import('./oauth-as.js');
+        const { jwtSecretFrom } = await import('./mcp-token.js');
+        const { resolveJwtKey, resolveMasterKeyForDispatch } = await import('./master-key.js');
+        const { OAuth2Client } = await import('googleapis-common');
+        const { writeToken } = await import('./token-store.js');
+        const { resolveScopesForAccount } = await import('./auth.js');
+        const { configDir } = await import('./config-file.js');
+        const { getAccountSet } = await import('./accounts.js');
+        const googleClient = () => new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, `${httpCfg.publicUrl}/callback`);
+        // Only trust the id_token email when Google marks it verified (#8).
+        const verifiedEmailFromIdToken = (idToken) => {
+            if (!idToken)
+                return undefined;
+            try {
+                const [, payload] = idToken.split('.');
+                const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8'));
+                const verified = claims.email_verified === true || claims.email_verified === 'true';
+                return verified ? claims.email : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const authServer = buildAuthServer({
+            base: httpCfg.publicUrl,
+            resourceUri: httpCfg.resourceUri,
+            secret: jwtSecretFrom(resolveJwtKey().key),
+            ownerEmails: owners,
+            cimdIssuers: (process.env.MCP_CIMD_ALLOWED_ISSUERS ?? 'claude.ai').split(',').map((s) => s.trim()).filter(Boolean),
+            accessTtlSec: Number(process.env.MCP_ACCESS_TTL) || undefined,
+            masterKey: resolveMasterKeyForDispatch().key,
+            refreshStorePath: path.join(configDir(), 'mcp-tokens.enc'),
+        }, {
+            buildGoogleAuthUrl: ({ flow, alias, state }) => {
+                if (flow === 'alias_reauth' && alias) {
+                    const cfg = getAccountSet().configs[alias];
+                    // openid+email so /callback can bind the returned identity to the alias.
+                    return googleClient().generateAuthUrl({
+                        access_type: 'offline',
+                        prompt: 'consent',
+                        scope: [...new Set([...resolveScopesForAccount(alias), 'openid', 'email'])],
+                        login_hint: cfg?.email,
+                        state,
+                    });
+                }
+                return googleClient().generateAuthUrl({ scope: ['openid', 'email'], prompt: 'select_account', state });
+            },
+            exchangeCode: async (code, flow) => {
+                const { tokens } = await googleClient().getToken(code);
+                const email = verifiedEmailFromIdToken(tokens.id_token ?? undefined);
+                // owner_gate discards Google tokens (identity proof only); alias_reauth
+                // keeps them but still needs the email for the identity binding.
+                return { tokens: flow === 'owner_gate' ? {} : tokens, email };
+            },
+            writeToken: (alias, tokens) => writeToken(alias, tokens),
+            aliasEmail: (alias) => getAccountSet().configs[alias]?.email,
+            log: (l) => process.stderr.write(`[as] ${l}\n`),
+        });
+        // BV-1: over HTTP, a dead/missing per-account token surfaces a clickable
+        // re-auth link into the AS's alias_reauth flow instead of a stdio CLI hint.
+        const { setHttpReauthBase } = await import('./reauth-hint.js');
+        setHttpReauthBase(httpCfg.publicUrl);
+        const host = new HttpTransportHost({
+            server: httpServer,
+            config: httpCfg,
+            version: pkg.version,
+            ownerConfigured: owners.length > 0,
+            authenticate: authServer.authenticate,
+            routes: authServer.routes,
+            log: (l) => process.stderr.write(`[http] ${l}\n`),
+        });
+        await host.start();
+        process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);
+        // Graceful shutdown so `docker run --init` (B16) forwards SIGTERM cleanly.
+        const shutdown = () => {
+            host.close().finally(() => process.exit(0));
+        };
+        process.once('SIGTERM', shutdown);
+        process.once('SIGINT', shutdown);
+    }
 }
 main().catch((err) => {
     process.stderr.write(`Fatal error: ${err.message}\n`);

package/dist/master-key.d.ts

@@ -0,0 +1,53 @@
+export type KeyProvenance = 'env' | 'keychain' | 'file' | 'generated';
+export interface ResolvedKey {
+    key: string;
+    provenance: KeyProvenance;
+}
+interface KeychainEntry {
+    get(): string | null;
+    set(value: string): void;
+    del(): void;
+}
+export interface KeyDeps {
+    env?: NodeJS.ProcessEnv;
+    dir?: string;
+    keychain?: (account: string) => KeychainEntry | null;
+    hasAnyToken?: () => boolean;
+}
+export declare function __setKeychainFactoryForTest(fn: ((account: string) => KeychainEntry | null) | null): void;
+/** BR-1 single choke point: no other module may read the env vars directly.
+ * Boot/CLI form: failures exit with a clean stderr slug ("fatal at startup"). */
+export declare function resolveMasterKey(deps?: KeyDeps): ResolvedKey;
+/** Dispatch form: identical resolution, but failures THROW (caught by the tool
+ * handler into an error envelope) — a live server is never process.exit'd. */
+export declare function resolveMasterKeyForDispatch(): ResolvedKey;
+/** Side-effect-free provenance probe for diagnostics: NEVER generates, never
+ * fires the hard guard (config check must not mint keys or exit). */
+export declare function peekMasterKeyProvenance(deps?: KeyDeps): KeyProvenance | 'unprovisioned';
+/** MCP_JWT_KEY variant: NO hard guard — regenerating only invalidates
+ * outstanding MCP tokens and clients re-auth silently. */
+export declare function resolveJwtKey(deps?: KeyDeps): ResolvedKey;
+/**
+ * BR-5: after the FIRST successful token decrypt with an env-sourced key,
+ * mirror it into the keychain (only when the keychain holds no entry) so the
+ * key survives an env loss. Gating on a successful decrypt means a stale or
+ * wrong env key is never mirrored. Best-effort: failures are doctor material,
+ * never fatal.
+ */
+export declare function noteSuccessfulDecrypt(): void;
+/** B6 reset: drop the generated MASTER_KEY material (0600 file + keychain
+ * entry) so the next run re-provisions. Never removes an env-provided key (the
+ * deployer owns that; `env:true` flags it so reset can warn). The caller MUST
+ * have wiped every .enc token first — regenerating with tokens present would
+ * brick them (enforced by the reset planner). */
+export declare function deleteMasterKeyMaterial(deps?: {
+    dir?: string;
+    keychain?: (a: string) => KeychainEntry | null;
+}): {
+    file: boolean;
+    keychain: boolean;
+    env: boolean;
+};
+/** Test hook: the production cache is process-lifetime by design. */
+export declare function clearKeyCacheForTest(): void;
+export {};