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

package/dist/http-transport.js

@@ -1,30 +1,21 @@
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
-// 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 { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
 import { logSafe } from './trim.js';
 // A host wrapping the log callbacks it hands core needs this, and trim has no package export.
 export { logSafe } from './trim.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.
+// serialize() lock forever; generous by default so slow-but-valid calls still finish.
 const DISPATCH_TIMEOUT_DEFAULT = 120_000;
-/** MCP 2025-06-18 dropped JSON-RPC batching, and the SDK screens every frame
- * of a batch synchronously in one tick: without a cap one body multiplies the
- * per-call work by however many frames fit in it. */
+// Without a cap, one body multiplies per-call work by however many
+// JSON-RPC frames the SDK's synchronous batch screening finds in it.
 const MAX_BATCH_FRAMES = 16;
-// A resolveServer refusal's body reaches the wire verbatim (H3 PR1): validated
-// so a host cannot accidentally leak an operator path/env var through a wrongly
-// shaped slug or an overlong message. No new slug literal enters core itself —
-// the slug is always the host's own value.
+// A refusal's body reaches the wire verbatim, so it's validated: no new slug
+// literal enters core, and an overlong message can't leak an operator path/env var.
 const REFUSAL_SLUG_RE = /^[a-z][a-z0-9_]{0,39}$/;
 const MAX_REFUSAL_MESSAGE_CHARS = 300;
-// C0/C1 controls, format chars (includes bidi overrides like U+202E and
-// zero-width joiners) and the line/paragraph separators; ordinary non-ASCII
-// letters stay allowed.
+// C0/C1 controls, format chars (bidi overrides, zero-width joiners) and
+// line/paragraph separators; ordinary non-ASCII letters stay allowed.
 const NON_PRINTABLE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
 function isValidRefusal(r) {
     return (typeof r.error === 'string' &&
@@ -42,7 +33,7 @@ export function parseOwnerEmails(env = process.env) {
 }
 /** 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). */
+ * connector calls /mcp server-to-server with no Origin). */
 export function originAllowed(origin, allowed) {
     if (!origin)
         return true;
@@ -81,25 +72,17 @@ export function jsonRpcMethod(body) {
 /** 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.
+// A lingering close (ends the socket, never destroys it); see docs/internals.md (Graceful close).
 function endAfterFlush(socket) {
     if (socket.destroyed || socket.writableEnded)
         return;
-    // Node arms a keep-alive timer when a response finishes and destroys the
-    // socket when it fires, which would cut a slow reader's unread tail just as
-    // an early destroy does. Only the client's FIN or the grace ends it now.
+    // Disarm the keep-alive timer Node arms on finish, or it destroys the
+    // socket ~6s later and cuts a slow reader's unread tail the same way an early destroy does.
     socket.setTimeout(0);
     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.
+// Stops reading for good so TCP flow control stops the client, instead of
+// piling up a flood pipelined behind a held response; see docs/internals.md (Graceful close).
 function stopReading(socket) {
     socket.pause();
     socket.resume = () => socket;
@@ -117,18 +100,12 @@ function pathOf(req) {
 export class HttpTransportHost {
     opts;
     httpServer;
-    // Serialize the connect→dispatch critical section PER SERVER: a McpServer
-    // captures its transport per request (protocol.js), but the gap between
-    // connect() and the dispatch capturing it would still race under true
-    // concurrency, so all traffic to ONE server runs under one mutex. The free
-    // core has one lane (the boot server); with resolveServer each resolved
-    // server gets its own, however subjects map onto servers.
+    // Per-server dispatch mutex; see docs/internals.md.
     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.
+    // What a graceful close waits on: open sockets and every handle() not yet
+    // settled; see docs/internals.md (Graceful close).
     sockets = new Set();
     pending = new Map();
     // Sockets that have accepted a request: nothing pending means the last
@@ -145,9 +122,8 @@ export class HttpTransportHost {
         const run = prev.then(fn, fn);
         const tail = run.then(() => undefined, () => undefined);
         this.locks.set(key, tail);
-        // An idle lane drops out, so the map holds only in-flight subjects rather
-        // than every subject ever seen. A request that chained on this tail has
-        // already replaced it, so the identity check never frees a live lane.
+        // An idle lane drops out of the map; the identity check below skips a
+        // later request that already replaced this tail, so it never frees a live lane.
         void tail.then(() => {
             if (this.locks.get(key) === tail)
                 this.locks.delete(key);
@@ -161,9 +137,8 @@ export class HttpTransportHost {
         const { config } = this.opts;
         const server = createServer((req, res) => {
             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.
+            // Once closing, a request arriving now is never handled (RFC 9112 §9.6)
+            // and its body is left unread.
             if (this.closing) {
                 stopReading(socket);
                 return;
@@ -190,10 +165,8 @@ export class HttpTransportHost {
             };
             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.
+            // Never rejects (close() waits on it); the thrown message can name
+            // server paths, so it goes only to the host's log.
             const done = this.handle(req, res)
                 .catch((e) => {
                 try {
@@ -265,20 +238,13 @@ export class HttpTransportHost {
     }
     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.
+        // Node's close() also destroys idle connections, which would cut short a
+        // large response still flushing; 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. A
-        // socket with nothing pending may still be delivering the tail of its
-        // last response, so only one that never accepted a request is destroyed.
+        // Socket bookkeeping below; see docs/internals.md (Graceful close).
         for (const socket of this.sockets) {
             const entry = this.pending.get(socket);
             if (!entry && !this.served.has(socket)) {
@@ -357,10 +323,7 @@ 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.
+        // Registered before anything awaits (client-gone skip); see docs/internals.md.
         let gone = false;
         res.once('close', () => (gone = true));
         const socket = req.socket;
@@ -375,8 +338,8 @@ export class HttpTransportHost {
             return;
         }
         const sub = auth.sub ?? 'owner';
-        // Tenant resolution (the seam EE fills): map the verified subject to ITS
-        // server. Absent resolver = the one boot server for every subject.
+        // Tenant resolution (a multi-tenant host fills this seam): map the
+        // verified subject to ITS server. Absent resolver = the one boot server for every subject.
         let target = {
             server: this.opts.server,
             argShapeFor: this.opts.argShapeFor,
@@ -400,8 +363,7 @@ export class HttpTransportHost {
                     return;
                 }
                 // An invalid shape falls through to today's exact answer rather than
-                // forwarding something unvalidated; a refusal never reaches dispatch
-                // either way.
+                // forwarding something unvalidated.
                 resolved = null;
             }
             target = resolved;
@@ -437,9 +399,8 @@ export class HttpTransportHost {
         }
     }
     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.
+        // Thread the verified subject to tool handlers via ctx.http.authInfo;
+        // token/clientId stay empty so the bearer value never re-enters the dispatch path.
         req.auth = {
             token: '',
             clientId: '',
@@ -457,28 +418,16 @@ export class HttpTransportHost {
         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
-        // exact-Host match is stricter than the front guard and would 403 valid
-        // Hosts (double enforcement, differing rules).
+        // The SDK's own DNS-rebind guard is disabled: Host/Origin are already
+        // enforced above, and its stricter exact-Host match would 403 valid Hosts.
         const transport = new NodeStreamableHTTPServerTransport({
             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.)
+        // connect + dispatch + disconnect run inside the per-server mutex, keyed
+        // on the server identity, never the subject; see docs/internals.md.
         const deadlineMs = this.opts.dispatchTimeoutMs ?? DISPATCH_TIMEOUT_DEFAULT;
-        // The lock lane is the SERVER identity, never the subject: two subjects
-        // reaching one server (the boot server, or a resolver mapping several
-        // 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()) {
@@ -491,16 +440,14 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            // Same composition as the stdio leg: the envelope rewrite is innermost,
-            // so the tap above it still classifies the original validation prose.
+            // Envelope rewrite innermost, as on stdio; see docs/internals.md (Argument normalization).
             const enveloped = withValidationEnvelope(transport, validationEnvelope ?? {});
             const tapped = this.opts.metricsTap ? this.opts.metricsTap(enveloped) : enveloped;
             await mcpServer.connect(argShapeFor || strictArgs
                 ? withArgNormalization(tapped, argShapeFor ?? (() => undefined), this.opts.log, this.opts.onArgRename, strictArgs)
                 : tapped);
-            // 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).
+            // Non-rejecting arm: an orphaned handler settling after the deadline wins
+            // must not surface as an unhandled rejection; a real error is rethrown below.
             let dispatchErr;
             const dispatchArm = transport
                 .handleRequest(req, res, body)
@@ -538,7 +485,7 @@ export class HttpTransportHost {
     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).
+        // No secrets, no owner emails.
         res.end(JSON.stringify({
             status: 'ok',
             transport: config.transport,

package/dist/identity.d.ts

@@ -4,8 +4,8 @@ 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.
+ * exactly one context with subject "owner"; a multi-tenant host instantiates
+ * N contexts from N registries. Nothing here may assume a global current-account.
  * `subject` is a string (not the literal 'owner') so a context can carry a
  * tenant id; the free core still always builds 'owner'.
  */

package/dist/identity.js

@@ -2,18 +2,15 @@ import { getAccountSet, getTokenDir, refreshAccountSetIfStale } from './accounts
 import { makeGetClient } from './client.js';
 import { createTokenStore } from './token-store.js';
 import { resolvePolicy } from './write-control.js';
-// Only buildIdentityContext mints the owner brand. The subject string alone
-// never unlocks the owner-only surfaces (account wizard, host-file tools, the
-// operator diagnose report): a hand-built context claiming 'owner' stays a
-// non-owner context.
+// Only buildIdentityContext mints the owner brand: the subject string alone
+// never unlocks owner-only surfaces, so a hand-built context claiming 'owner' stays non-owner.
 const ownerContexts = new WeakSet();
 export function isOwnerContext(ctx) {
     return ctx !== undefined && ownerContexts.has(ctx);
 }
 export function buildIdentityContext(env = process.env, opts = {}) {
-    // Real closures over the single-owner state (the SAME factories EE
-    // instantiates per tenant), bound here to the global registry + token dir —
-    // behavior-identical to the module-level functions for the free core.
+    // The SAME factories a multi-tenant host instantiates per tenant, bound here
+    // to the global registry + token dir.
     const tokenStore = createTokenStore(getTokenDir());
     const ctx = {
         subject: 'owner',
@@ -22,8 +19,8 @@ export function buildIdentityContext(env = process.env, opts = {}) {
         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.
+        // The dispatch transport rides into the resolved policy as a reserved seam;
+        // it does not change any write-control verdict.
         policy: resolvePolicy(env, { transport: opts.transport }),
         getClient: makeGetClient('owner', {
             accounts: getAccountSet,

package/dist/index.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 // 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).
+// anything else. Named to also pull the server-only empty-registry guard.
 import { assertServerAccountsConfigured } from './accounts.js';
 import { accountsAssertRequired, assertNoEnvAccountsMode, assertNoEnvOptionalScopesMode, isMultiTenantBoot, mtBootGates } from './boot-gates.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
-import { McpServer } from "@modelcontextprotocol/server";
 import { resolveDiscoveryMode } from './registry.js';
 import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
-import { buildRegistry, requestHooksFor } from './compose.js';
+import { buildRegistry, createMcpServer, requestHooksFor } from './compose.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
 import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
@@ -81,7 +80,7 @@ async function main() {
     if (process.argv.includes('config') && process.argv.includes('check')) {
         const ctx = buildIdentityContext();
         const policy = ctx.policy;
-        const registry = buildRegistry(new McpServer({ name: 'mcp-google-multi', version: pkg.version }), ctx);
+        const registry = buildRegistry(createMcpServer(pkg.version), ctx);
         const cud = registry.tools.filter((t) => t.cud !== 'read');
         const disabled = cud.filter((t) => !isAllowed(t, policy));
         const counts = registry.visibleCount();
@@ -140,10 +139,8 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
-    // BR-4: the SERVER never boots with an empty registry — stdio always, HTTP
-    // when single-owner. The bootstrap and diagnostic CLIs above already
-    // returned. A multi-tenant boot instead refuses the two process-wide env
-    // vectors that would leak one operator's accounts/scopes into every tenant.
+    // The SERVER never boots with an empty registry (stdio always, HTTP when
+    // single-owner); a multi-tenant boot instead refuses the two process-wide env vectors.
     const mt = isMultiTenantBoot();
     if (accountsAssertRequired(wantStdio, mt))
         assertServerAccountsConfigured();
@@ -155,9 +152,7 @@ async function main() {
     // specced "fatal at startup", never mid-dispatch.
     const { resolveMasterKey } = await import('./master-key.js');
     resolveMasterKey();
-    // Local usage metrics: fail-closed resolve, self-announcing source, null
-    // when off (no wrapper, no dir, nothing initializes). One instance per
-    // transport so `boots` keys stay honest under `both`.
+    // One Metrics instance per transport so `boots` keys stay honest under `both`.
     const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
     const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
     if (metricsState.warning)
@@ -187,21 +182,17 @@ async function main() {
             });
         }
     }
-    // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
-    // never rebuilt per request); `both` runs the two concurrently.
+    // Build one McpServer + registry per transport at boot (never
+    // rebuilt per request); `both` runs the two concurrently.
     if (wantStdio) {
-        const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
+        const server = createMcpServer(pkg.version);
         const stdioMetrics = initMetricsFor('stdio', resolveDiscoveryMode());
         const stdioCtx = buildIdentityContext(process.env, { transport: 'stdio' });
         const registry = buildRegistry(server, stdioCtx, undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
         const stdioHooks = requestHooksFor(registry, stdioCtx, stdioMetrics);
-        // Outbound runs outermost-first, so the composition is deliberate: the
-        // envelope rewrite is INNERMOST (last to touch the frame), the tap sits
-        // above it (classifying the ORIGINAL validation prose), arg normalization
-        // outermost. The tap only counts outbound JSON-RPC error frames (no
-        // handler ran) plus id->tool names.
+        // Composition order (outbound runs outermost-first): see docs/internals.md (Argument normalization).
         let transport = withValidationEnvelope(new StdioServerTransport(), stdioHooks.validationEnvelope);
         if (stdioMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
@@ -209,10 +200,8 @@ async function main() {
         }
         await server.connect(stdioHooks.argShapeFor || stdioHooks.strictArgs
             ? withArgNormalization(transport, 
-            // Gated exactly as the HTTP leg gates `argShapeFor`. Passing the
-            // shape unconditionally made stdio rename keys while
-            // GOOGLE_ARG_NORMALIZE=off, so the same call succeeded on stdio
-            // and failed on HTTP once screening rejects.
+            // Gated exactly as the HTTP leg gates argShapeFor, or GOOGLE_ARG_NORMALIZE=off
+            // would rename keys on stdio while HTTP's screening rejects the same call.
             stdioHooks.argShapeFor ?? (() => undefined), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, stdioHooks.strictArgs)
             : transport);
     }
@@ -221,31 +210,30 @@ async function main() {
         const owners = parseOwnerEmails(process.env);
         const gates = mtBootGates();
         if (gates?.multiTenant) {
-            // Same fail-fast SHAPE, different condition: an ungated HTTP endpoint
-            // must never boot; under tenancy the gate is "a valid provisioning
+            // Same fail-fast shape as below, but the gate is "a valid provisioning
             // mechanism exists", not a flat owner allowlist.
             gates.assertProvisioningGate();
         }
         else {
-            // BR3 / C13: the owner allowlist is the entire multi-tenant collapse;
+            // The owner allowlist is the entire multi-tenant collapse;
             // refuse to open an ungated HTTP endpoint.
             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.
+        // 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 httpServer = createMcpServer(pkg.version);
         const httpMetrics = initMetricsFor('http', 'curated');
         const httpCtx = buildIdentityContext(process.env, { transport: 'http' });
         const registry = buildRegistry(httpServer, httpCtx, 'curated', httpMetrics);
         registry.installListHandler();
         registerSetupPrompt(httpServer);
-        // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
+        // Mount the OAuth 2.1 AS (MCP-client tokens + owner login) + the Bearer authenticator.
         const { buildAuthServer, verifiedEmailFromIdToken } = await import('./oauth-as.js');
         const { jwtSecretFrom } = await import('./mcp-token.js');
         const { resolveJwtKey, resolveMasterKeyForDispatch } = await import('./master-key.js');
@@ -288,7 +276,7 @@ async function main() {
             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,
+        // Over HTTP, a dead/missing per-account token surfaces a clickable,
         // signed re-auth link into the AS's alias_reauth flow instead of a CLI hint.
         const { setHttpReauthLink } = await import('./reauth-hint.js');
         setHttpReauthLink((alias) => authServer.reauthLink(alias));
@@ -314,7 +302,7 @@ async function main() {
         });
         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.
+        // Graceful shutdown so `docker run --init` forwards SIGTERM cleanly.
         const shutdown = () => {
             host.close().finally(() => process.exit(0));
         };

package/dist/master-key.d.ts

@@ -15,7 +15,7 @@ export interface KeyDeps {
     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.
+/** 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
@@ -28,14 +28,14 @@ export declare function peekMasterKeyProvenance(deps?: KeyDeps): KeyProvenance |
  * 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,
+ * 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
+/** 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

package/dist/master-key.js

@@ -5,10 +5,8 @@ import { createRequire } from 'node:module';
 import { configDir, failStartup } from './config-file.js';
 import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { getTokenDir } from './accounts.js';
-// The keychain is a native optionalDependency: load lazily and synchronously
-// (createRequire — the token store's key read is sync), and treat EVERY
-// failure (no prebuild, native load error, headless Linux without a Secret
-// Service) as "keychain unavailable", falling through to the 0600 file.
+// Native optionalDependency, loaded lazily and synchronously (the token
+// store's key read is sync); EVERY failure falls through to the 0600 file.
 const require_ = createRequire(import.meta.url);
 function systemKeychain(account) {
     try {
@@ -32,8 +30,7 @@ function systemKeychain(account) {
     }
 }
 // Default keychain factory, replaceable ONLY for tests: unit tests must never
-// read or write the developer's real OS keyring (the BR-5 mirror once leaked a
-// test fixture key into a real GNOME keyring — never again).
+// read or write the developer's real OS keyring.
 let keychainFactory = systemKeychain;
 export function __setKeychainFactoryForTest(fn) {
     keychainFactory = fn ?? systemKeychain;
@@ -46,14 +43,8 @@ function anyEncFileUnder(dir) {
         return false;
     }
 }
-// Glob the token dir instead of iterating registered aliases: an orphan .enc
-// (alias removed from the registry, or a partial GOOGLE_ACCOUNTS override in
-// one client) must still stop a fresh key from being minted. TOKEN_STORE_PATH
-// may relocate the token dir outside configDir(), so scan it directly; the
-// recursive configDir() walk then covers BOTH the tenant-namespaced token root
-// (tenants/<id>) AND any top-level master-key-encrypted registry beside it
-// (e.g. a downstream tenant map / invite store). Minting a fresh MASTER_KEY
-// over any existing .enc bricks it irreversibly, so the scan must see them all.
+// Globs the token dir rather than iterating registered aliases, so an orphan
+// .enc still stops a fresh key from being minted. See docs/internals.md.
 function anyTokenFileExists() {
     return anyEncFileUnder(getTokenDir()) || anyEncFileUnder(configDir());
 }
@@ -98,7 +89,7 @@ function resolveKey(envName, fileName, hardGuard, deps, onFail = 'exit') {
     const fromFile = readKeyFile(filePath);
     if (fromFile)
         return { key: fromFile, provenance: 'file' };
-    // Generate-on-setup. The hard guard is cc-security Cgen: minting a fresh
+    // Generate-on-setup. The hard guard: minting a fresh
     // MASTER_KEY while <alias>.enc files exist would silently brick them all.
     if (hardGuard && hasAnyToken()) {
         fail('E_MASTER_KEY_MISSING_TOKENS_EXIST', `no ${envName} found in env, keychain or ${filePath}, but encrypted tokens exist under ${getTokenDir()}. ` +
@@ -115,10 +106,8 @@ function resolveKey(envName, fileName, hardGuard, deps, onFail = 'exit') {
             return { key: racedFile, provenance: 'file' };
         // Exactly randomBytes(32) base64: hits deriveKey's 32-byte fast path.
         const generated = randomBytes(32).toString('base64');
-        // The 0600 file is ALWAYS written: on Linux the "keychain" can be the
-        // kernel keyutils keyring, which does not survive a reboot — a key that
-        // lives only there bricks every token at the next boot. The file is the
-        // durable sink; byte-exact read-back gates any use of the key.
+        // The 0600 file is ALWAYS written (some keychain backends don't survive
+        // a reboot); byte-exact read-back gates any use of the key.
         atomicWriteFileSync(filePath, `${generated}\n`, 0o600);
         if (readKeyFile(filePath) !== generated) {
             fail('E_KEY_PROVISIONING_FAILED', `generated ${envName} could not be read back byte-exact from ${filePath}; refusing to encrypt anything with an unverified key.`);
@@ -151,7 +140,7 @@ function resolveKey(envName, fileName, hardGuard, deps, onFail = 'exit') {
 }
 let cachedMaster = null;
 let cachedJwt = null;
-/** BR-1 single choke point: no other module may read the env vars directly.
+/** 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 function resolveMasterKey(deps) {
     if (deps)
@@ -189,7 +178,7 @@ export function resolveJwtKey(deps) {
 }
 let mirrored = false;
 /**
- * BR-5: after the FIRST successful token decrypt with an env-sourced key,
+ * 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,
@@ -211,7 +200,7 @@ export function noteSuccessfulDecrypt() {
         // Keychain backend unavailable; env stays the working source.
     }
 }
-/** B6 reset: drop the generated MASTER_KEY material (0600 file + keychain
+/** 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

package/dist/mcp-token.d.ts

@@ -88,7 +88,7 @@ export declare class ReplayGuard {
     reserve(jti: string, ttlMs: number, nowMs: number): 'ok' | 'full';
     /** Record a jti as spent. A full guard refuses instead of evicting a live
      * jti: a flood of spends would otherwise make a spent artifact usable again,
-     * such as a callback the browser binding refused (H4 F1). `artifactExpMs`
+     * such as a callback the browser binding refused. `artifactExpMs`
      * keeps the record alive as long as the artifact itself, even when the clock
      * stepped back between its signing and this spend. */
     spend(jti: string, ttlMs: number, nowMs: number, artifactExpMs?: number): ReplaySpend;
@@ -138,10 +138,10 @@ export interface RefreshStoreOptions {
  * Persisted (encrypted under MASTER_KEY) refresh-token store. Rotates on every
  * use, and a token carries its family and generation under a MAC, so
  * presenting any generation the family has rotated past is REUSE: the family
- * is revoked for the rest of its life (#7 / C14, H4 F2). The store keeps one
+ * is revoked for the rest of its life. The store keeps one
  * record per family, whatever its rotation count. Every read-modify-write goes
  * through a file lock so concurrent stdio+HTTP processes can't lost-update or
- * double-spend (#12). See docs/internals.md.
+ * double-spend. See docs/internals.md.
  */
 export declare class RefreshStore {
     private readonly path;
@@ -165,16 +165,6 @@ export declare class RefreshStore {
     private load;
     private save;
     private emit;
-    /** Evict `sub`'s own least-recently-used sessions (both formats) so at
-     * most `limit` of its live sessions remain; dropping one here is the same
-     * as deleting it from `data.families` / `data.active` on a revoke, so it
-     * can never be presented again (reuse detection for every OTHER family is
-     * untouched). Only `sub`'s own entries are ever inspected.
-     *
-     * `keepKey` is the family just issued: it is excluded from the ranking so
-     * a clock step back, or a concurrent rotate's `usedAt = max(usedAt, nowMs)`
-     * racing ahead of it under the lock, can never make the brand-new family
-     * look like the least recently used one and drop itself. */
     private enforceFamilyCap;
     private newFamilyId;
     issue(nowMs: number, sub: string): string;