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

package/dist/mcp-token.js

@@ -1,8 +1,5 @@
-// B13 token model (oauth-authorization-server.md §Data model): the MCP access
-// token (HS256 JWT, jose-only — AS==RS so no JWKS), the signed self-contained
-// `state` and authorization code, the in-memory single-use replay guard, and
-// the rotated refresh-token store. Keyed by the provisioned MCP_JWT_KEY
-// (B5), so tokens survive a restart as long as the key persists.
+// Token model: the MCP access token (HS256 JWT, jose-only), signed state and
+// authorization code, the replay guard, and the rotated refresh-token store.
 import { createHash, createHmac, hkdfSync, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { basename } from 'node:path';
@@ -126,7 +123,7 @@ export class ReplayGuard {
     }
     /** 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, ttlMs, nowMs, artifactExpMs = 0) {
@@ -165,10 +162,8 @@ export class ReplayGuard {
         if (exp < this.earliest)
             this.earliest = exp;
     }
-    // Expired entries are dropped only here, when the map is at the cap: a refusal
-    // costs O(1), and a sweep runs only once something can have expired, at most
-    // once a second. Walking the map from its head on every call is not cheap: a
-    // Map iterator steps over every deleted slot until the table is rebuilt.
+    // Swept only when at the cap (a refusal otherwise costs O(1)), and at most
+    // once a second: a Map iterator steps over every deleted slot until rebuilt.
     room(nowMs) {
         if (this.seen.size < this.cap)
             return true;
@@ -190,18 +185,16 @@ export class ReplayGuard {
 }
 /** Store files this release writes; an absent `format` is an earlier release's. */
 const REFRESH_FORMAT = 2;
-// r1 token: "r1." + base64url(fid 16 || gen uint32 BE || rand 16 || HMAC-SHA256
-// of those 36 bytes). The dot is outside the base64url alphabet, so an r1
-// token can never be read as an earlier release's 43-character token.
+// r1 token: "r1." + base64url(fid 16 || gen uint32 BE || rand 16 || HMAC-SHA256).
+// The dot is outside the base64url alphabet, so it can't be read as a legacy 43-char token.
 const R1_PREFIX = 'r1.';
 const R1_LENGTH = 94;
 const R1_BODY = 36;
 const R1_BYTES = 68;
 const R1_MAC_DOMAIN = Buffer.from('mcp-google-multi refresh r1\n');
 const R1_KEY_INFO = 'mcp-google-multi:refresh-mac:v1';
-// Every r1 token carries a MAC under a key from MASTER_KEY, so a passphrase
-// key (deriveKey's bare-sha256 branch) would let one leaked token test
-// guesses offline at hash speed. scrypt gives that branch a work factor.
+// A passphrase key (deriveKey's bare-sha256 branch) would otherwise let one
+// leaked r1 token test guesses offline at hash speed; scrypt adds a work factor.
 const R1_SCRYPT_SALT = 'mcp-google-multi:refresh-mac:scrypt:v1';
 const R1_SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 const GEN_MAX = 0xffffffff;
@@ -304,9 +297,8 @@ function checkFormat(file, d) {
         throw formatError(file, d.format);
     }
 }
-/** Only well-formed own entries survive, so no lookup lands on an inherited
- * key and no malformed record reaches a liveness test or the token codec.
- * `dirty` says something was dropped. */
+// Only well-formed own entries survive, so no malformed record reaches a
+// liveness test or the token codec; `dirty` says something was dropped.
 function decodeData(d) {
     const data = { families: {}, active: {}, spent: {} };
     const x = (d ?? {});
@@ -378,10 +370,10 @@ function lifetimeMs(name, v) {
  * 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 class RefreshStore {
     path;
@@ -504,20 +496,12 @@ export class RefreshStore {
                 this.log(line);
             }
             catch {
-                // The rotation is already on disk; a log sink must not lose its token.
+                // log sink failure ignored
             }
         }
     }
-    /** 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. */
+    // Evicts sub's own least-recently-used sessions down to `limit`; keepKey (the
+    // family just issued) is excluded from ranking. See docs/internals.md.
     enforceFamilyCap(data, sub, limit, lines, keepKey) {
         const entries = [];
         for (const [k, f] of Object.entries(data.families)) {

package/dist/metrics-cli.d.ts

@@ -15,7 +15,7 @@ interface PromotionRow {
     calls: number;
     kind: 'curation-candidate' | 'visibility-failure' | 'generation-gap';
 }
-/** The promotion-queue view: ranked evidence, a human decides (spec section 5). */
+/** The promotion-queue view: ranked evidence, a human decides. */
 export declare function classifyPromotion(merged: DayAgg, data: PromotionData): PromotionRow[];
 export declare function runMetricsCli(argv: string[], deps: MetricsCliDeps): number;
 export {};

package/dist/metrics-cli.js

@@ -87,7 +87,7 @@ function renderReport(merged, days, out) {
     }
 }
 const tail = (id) => id.split('.').slice(1).join('.');
-/** The promotion-queue view: ranked evidence, a human decides (spec section 5). */
+/** The promotion-queue view: ranked evidence, a human decides. */
 export function classifyPromotion(merged, data) {
     const curated = new Set();
     for (const id of data.curatedIds) {

package/dist/metrics-tap.js

@@ -1,10 +1,7 @@
 import { isSchemaValidationText } from './arg-normalize.js';
 const PENDING_CAP = 1_000;
-// The detector lives next to the rewriter that consumes the same frames, so
-// the two can never drift apart. This tap sees the ORIGINAL prose:
-// withValidationEnvelope sits BELOW it and converts that same frame into an
-// envelope for the client, so classification here and the contract on the wire
-// stay independent.
+// This tap sees the ORIGINAL prose; withValidationEnvelope sits BELOW it and
+// converts the same frame for the client, so the two stay independent.
 export { isSchemaValidationText };
 /**
  * @param isKnownTool membership test against the REGISTERED tool set. The

package/dist/migrate-config.d.ts

@@ -1,7 +1,6 @@
 /**
  * Synthesize config.json accounts{} from the v5 env (GOOGLE_ACCOUNTS +
  * GOOGLE_ADMIN_ACCOUNTS). Never deletes or edits env; idempotent (a re-run
- * that changes nothing says so). Scope-profile and preference fields are
- * migrated by their own slices' commands.
+ * that changes nothing says so).
  */
 export declare function runMigrateConfig(env?: NodeJS.ProcessEnv): void;

package/dist/migrate-config.js

@@ -6,8 +6,7 @@ function parseCsv(value) {
 /**
  * Synthesize config.json accounts{} from the v5 env (GOOGLE_ACCOUNTS +
  * GOOGLE_ADMIN_ACCOUNTS). Never deletes or edits env; idempotent (a re-run
- * that changes nothing says so). Scope-profile and preference fields are
- * migrated by their own slices' commands.
+ * that changes nothing says so).
  */
 export function runMigrateConfig(env = process.env) {
     const raw = env.GOOGLE_ACCOUNTS;
@@ -35,7 +34,7 @@ export function runMigrateConfig(env = process.env) {
         }
         desired[alias] = { email };
     }
-    // Legacy global scopes (BC7) become an explicit named profile every account
+    // Legacy global scopes become an explicit named profile every account
     // points at, so removing the env var later changes nothing.
     const legacyNames = parseCsv(env.GOOGLE_OPTIONAL_SCOPES);
     let legacyProfile;
@@ -59,8 +58,7 @@ export function runMigrateConfig(env = process.env) {
     const filePath = configFilePath(env);
     const before = loadConfigFile(filePath);
     // Merge per-alias: env owns the alias set and emails, but file-only fields
-    // (scopeProfile, admin) survive for retained aliases — mirroring runtime
-    // precedence, where unset GOOGLE_ADMIN_ACCOUNTS preserves file admin flags.
+    // (scopeProfile, admin) survive for retained aliases.
     const existing = before?.accounts ?? {};
     const dropped = Object.keys(existing).filter((a) => !(a in desired));
     for (const [alias, entry] of Object.entries(desired)) {

package/dist/net-tuning.js

@@ -1,8 +1,6 @@
 import net from 'node:net';
-// Node's happy-eyeballs gives each address family 250ms per connect attempt on
-// every LTS line (raised to 500ms only in v25.2+); on high-latency or
-// broken-IPv6 links that aborts EVERY Google call while curl works. Raise the
-// process default unless the user tuned it themselves. Why: docs/internals.md.
+// Node's happy-eyeballs 250ms-per-attempt default aborts EVERY Google call on
+// a high-latency or broken-IPv6 link while curl works. See docs/internals.md.
 export const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
 const USER_FLAGS = ['--network-family-autoselection-attempt-timeout', '--no-network-family-autoselection'];
 /** Pure decision: the timeout to apply, or null to leave Node's setting alone. */

package/dist/oauth-as.d.ts

@@ -60,7 +60,7 @@ export interface GoogleIdentity {
     sub?: string;
     hd?: string;
 }
-/** Only trust the id_token identity when Google marks the email verified (#8).
+/** Only trust the id_token identity when Google marks the email verified.
  * The token comes straight from Google's token endpoint, so its claims are
  * read unsigned. A malformed sub or hd is dropped, never passed on. */
 export declare function verifiedIdentityFromIdToken(idToken?: string | null): GoogleIdentity | undefined;
@@ -146,7 +146,7 @@ export interface AuthServer {
      * start a re-auth nor learn which aliases exist or what they hold. */
     reauthLink: (alias: string) => string;
 }
-/** C6: exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
+/** Exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
  *  the fixed claude.ai callback. */
 export declare function redirectAllowed(redirectUri: string, docRedirectUris: string[]): boolean;
 export declare function buildAuthServer(config: AuthServerConfig, deps?: AuthServerDeps): AuthServer;

package/dist/oauth-as.js

@@ -1,10 +1,5 @@
-// B13: the minimal OAuth 2.1 Authorization Server + Resource Server
-// (oauth-authorization-server.md). Federate-and-hold: the server mints its own
-// audience-bound HS256 token for the MCP client (leg A), gates on an owner
-// Google login (leg B, tokens discarded), and separately holds per-alias Google
-// tokens (leg C, unchanged). Mounts into B12's HttpTransportHost as `routes` +
-// an `authenticate` for POST /mcp. All Google/CIMD I/O is injectable so the
-// whole surface is exercised by an offline harness.
+// The minimal OAuth 2.1 Authorization Server + Resource Server: federate-and-hold
+// (own token / discarded owner login / held per-alias tokens). See docs/internals.md.
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { isIPv4 } from 'node:net';
 import { decodeJwt } from 'jose';
@@ -13,21 +8,17 @@ import { fetchCimdDocument } from './ssrf-guard.js';
 import { CimdClientCache } from './cimd-cache.js';
 import { logSafe } from './trim.js';
 const CLAUDE_AI_FIXED_CALLBACK = 'https://claude.ai/api/mcp/auth_callback';
-// DCR (/register) is public + unauthenticated, so its in-memory store must be
-// bounded like every sibling store (the ReplayGuard cap) or a request loop
-// OOMs the process. Cap client count (FIFO-evict the oldest) and
-// the per-request redirect_uris shape so one entry can't be arbitrarily large.
+// /register is public and unauthenticated, so its store must stay bounded
+// (FIFO-evict the oldest) like every sibling store, or a request loop OOMs.
 export const DCR_MAX_CLIENTS = 1000;
 export const DCR_MAX_REDIRECT_URIS = 10;
 const DCR_MAX_URI_LEN = 2048;
 const OIDC_SUB = /^[\x21-\x7e]{1,255}$/;
 const HOSTED_DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i;
-// RFC 6749's error_description charset: %x20-21 / %x23-5B / %x5D-7E (printable
-// ASCII minus the backslash and double-quote that would need escaping in the
-// query string). A resolveSubject denial outside this set is dropped rather
-// than forwarded unvalidated (H3 PR1).
+// RFC 6749 error_description charset (%x20-21/%x23-5B/%x5D-7E); a denial
+// description outside it is dropped rather than forwarded unvalidated.
 const ERROR_DESCRIPTION_RE = /^[\x20-\x21\x23-\x5b\x5d-\x7e]{1,200}$/;
-/** Only trust the id_token identity when Google marks the email verified (#8).
+/** Only trust the id_token identity when Google marks the email verified.
  * The token comes straight from Google's token endpoint, so its claims are
  * read unsigned. A malformed sub or hd is dropped, never passed on. */
 export function verifiedIdentityFromIdToken(idToken) {
@@ -90,7 +81,7 @@ function isLoopbackHostname(h) {
     // prefix (which would let "127.evil.com" masquerade as loopback).
     return isIPv4(host) && host.split('.')[0] === '127';
 }
-/** C6: exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
+/** Exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
  *  the fixed claude.ai callback. */
 export function redirectAllowed(redirectUri, docRedirectUris) {
     if (redirectUri === CLAUDE_AI_FIXED_CALLBACK)
@@ -118,10 +109,7 @@ export function redirectAllowed(redirectUri, docRedirectUris) {
         return isLoopbackHostname(du.hostname) && du.protocol === r.protocol && du.pathname === r.pathname;
     });
 }
-// The owner_gate browser binding (docs/internals.md). One cookie per flow, so
-// two sign-ins started in one browser do not overwrite each other. __Host-
-// requires Secure, which an http base (the loopback owner) cannot rely on in
-// every browser, so an http base gets a plain host-only name instead.
+// Owner-gate browser binding: one cookie per flow; see docs/internals.md.
 const BIND_HASH = /^[A-Za-z0-9_-]{43}$/;
 function bindCookieName(base, bind) {
     return `${base.startsWith('https:') ? '__Host-' : ''}mgm-og-${bind.slice(0, 16)}`;
@@ -193,10 +181,7 @@ export function buildAuthServer(config, deps = {}) {
     const base = config.base;
     const resource = config.resourceUri;
     const secret = config.secret;
-    // States, approvals and codes live minutes, and their single use rests on an
-    // in-memory replay guard that a restart empties. So they are signed with a
-    // key only this AuthServer holds: a restart invalidates every one in flight,
-    // instead of letting a spent or unreserved one pass the new, empty guard.
+    // States/approvals/codes are signed with a per-process secret; see docs/internals.md.
     const flowSecret = new Uint8Array(randomBytes(32));
     const accessTtl = config.accessTtlSec ?? ACCESS_TTL_DEFAULT;
     const cimd = deps.fetchCimd ?? ((clientId) => fetchCimdDocument(clientId));
@@ -256,7 +241,7 @@ export function buildAuthServer(config, deps = {}) {
         const reg = registered.get(clientId);
         if (reg)
             return { redirect_uris: reg.redirect_uris, dcr: true };
-        // C7/#5: validate the issuer host + scheme BEFORE any outbound fetch, so we
+        // Validate the issuer host + scheme BEFORE any outbound fetch, so we
         // only ever fetch an allowlisted issuer (no arbitrary-URL SSRF surface).
         let issuerHost;
         let scheme;
@@ -273,15 +258,15 @@ export function buildAuthServer(config, deps = {}) {
             log(`CIMD rejected: issuer=${logSafe(`${scheme}//${issuerHost}`, 80)} not allowlisted client_id_len=${clientId.length}`);
             return { error: 'E_CIMD_INVALID', message: 'invalid client' };
         }
-        // #15: cached only once it validates; the cache logs a failed fetch.
+        // Cached only once it validates; the cache logs a failed fetch.
         const got = await cimdClients.resolve(clientId, (doc) => doc.client_id === clientId && Array.isArray(doc.redirect_uris) && doc.redirect_uris.length > 0);
         if ('busy' in got)
             return got;
-        // #13: never echo internal fetch details to the caller (blind-SSRF oracle).
+        // Never echo internal fetch details to the caller (blind-SSRF oracle).
         if ('error' in got)
             return { error: got.error, message: 'invalid client' };
         const uris = got.doc.redirect_uris;
-        // C6 #14: warn on a localhost-only redirect set (loopback impersonation),
+        // Warn on a localhost-only redirect set (loopback impersonation),
         // once per fetch rather than on every sign-in the cache serves.
         if (got.fresh && uris.every((u) => { try {
             return isLoopbackHostname(new URL(u).hostname);
@@ -299,7 +284,7 @@ export function buildAuthServer(config, deps = {}) {
     /** `incoming`: the artifact spent to get here. If no slot is left for the
      * new state it is unspent, so retrying it works once a slot frees. */
     async function toGoogle(res, sp, incoming) {
-        // H4 F1: without this, a Google URL minted here and forwarded to someone
+        // Without this, a Google URL minted here and forwarded to someone
         // else signs THEM in and hands their subject to the starting client.
         const headers = {};
         if (sp.flow === 'owner_gate') {
@@ -323,8 +308,6 @@ export function buildAuthServer(config, deps = {}) {
             : `https://accounts.google.com/o/oauth2/v2/auth?state=${encodeURIComponent(state)}`;
         return redirect(res, authUrl, headers);
     }
-    // GET /authorize (validate + interstitial for DCR clients); POST /authorize
-    // (a DCR consent approval — verify the signed pending token, then proceed).
     const authorize = async (req, res, url) => {
         if (req.method === 'POST') {
             let form;
@@ -341,7 +324,6 @@ export function buildAuthServer(config, deps = {}) {
             catch {
                 return errorPage(res, 400, 'E_STATE_INVALID', 'the approval is invalid or expired');
             }
-            // Only the client leg signs pendings, and it is always the owner sign-in.
             // Defence in depth: a pending from an earlier release, which could carry
             // flow=alias_reauth, was signed with MCP_JWT_KEY and no longer verifies.
             if (pending.flow !== 'owner_gate') {
@@ -364,10 +346,8 @@ export function buildAuthServer(config, deps = {}) {
         const resourceParam = q.get('resource') ?? '';
         const clientState = q.get('state') ?? undefined;
         const aliasParam = q.get('alias') ?? undefined;
-        // Server-minted alias_add link: the whole request identity (tenant, alias,
-        // bundles) lives inside the SIGNED state — verify, spend it (single-use),
-        // then re-sign fresh for the Google leg. A tampered tenantId breaks the
-        // signature; a caller cannot supply one at all.
+        // alias_add: tenant/alias/bundles live inside the SIGNED state, verified
+        // and spent single-use before re-signing for Google; a caller can't tamper with them.
         if (q.get('flow') === 'alias_add' && !clientId) {
             let minted;
             try {
@@ -388,11 +368,7 @@ export function buildAuthServer(config, deps = {}) {
             void _spent;
             return toGoogle(res, sp, minted.jti);
         }
-        // In-call re-auth (BV-1): a user-clicked `flow=alias_reauth` link has NO
-        // client leg — no code is delivered to any client, the refreshed token is
-        // written server-side for the alias — so it skips the client_id/redirect/
-        // PKCE requirements. The link must be one this server signed (reauthLink),
-        // and /callback still binds the completing identity to the alias's email.
+        // alias_reauth skips client_id/redirect/PKCE (no client leg); see docs/internals.md.
         if (q.get('flow') === 'alias_reauth' && !clientId) {
             if (config.legacyAliasReauth === false) {
                 // Alias-only, tenant-ambiguous: disabled on multi-tenant deployments.
@@ -413,22 +389,18 @@ export function buildAuthServer(config, deps = {}) {
             return clientUnavailable(res);
         if ('error' in client)
             return json(res, 400, { error: 'invalid_client', message: client.message, iss: base }, issHeader);
-        // (2) exact redirect_uri match BEFORE minting anything (open-redirect defense)
+        // Exact redirect_uri match BEFORE minting anything (open-redirect defense).
         if (!redirectUri || !redirectAllowed(redirectUri, client.redirect_uris)) {
             return errorPage(res, 400, 'E_REDIRECT_URI_MISMATCH', 'redirect_uri is not an allowed callback for this client');
         }
-        // (3) PKCE S256 required
         if (!codeChallenge || method !== 'S256') {
             return json(res, 400, { error: 'invalid_request', message: 'code_challenge with S256 required', iss: base }, issHeader);
         }
-        // (4) resource must be the canonical resource URI
         if (resourceParam !== resource) {
             return json(res, 400, { error: 'invalid_request', message: `resource must be ${resource}`, iss: base }, issHeader);
         }
-        // (5) only after full validation do we build the request artifact.
-        // A client leg is always the owner sign-in. Re-auth has its own signed
-        // link: accepting flow=alias_reauth here let any client (a self-registered
-        // one, or a public CIMD client_id) start it and read the alias's scopes.
+        // Only after full validation, and always as owner_gate: a caller-supplied
+        // flow here would let any client read an alias's scopes via alias_reauth.
         const statePayload = {
             flow: 'owner_gate',
             client_id: clientId,
@@ -437,12 +409,8 @@ export function buildAuthServer(config, deps = {}) {
             client_state: clientState,
             resource,
         };
-        // Confused-deputy defense (#3): a self-registered DCR client can pick an
-        // arbitrary redirect_uri, so before we send the owner to Google (whose
-        // consent screen names only THIS server, not the requesting app), show an
-        // approval interstitial naming the client + destination. CIMD clients skip
-        // it — their redirect_uris come from an issuer-allowlisted document a rogue
-        // cannot forge, so there is nothing to spoof.
+        // DCR clients get a consent interstitial naming the client + destination
+        // (confused-deputy defense); CIMD clients skip it. See docs/internals.md.
         if (client.dcr) {
             const pendingToken = await signPending(statePayload, base, flowSecret, nowSec());
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Content-Security-Policy': "frame-ancestors 'none'", 'X-Frame-Options': 'DENY' });
@@ -458,7 +426,6 @@ export function buildAuthServer(config, deps = {}) {
         }
         return toGoogle(res, statePayload);
     };
-    // GET /callback
     const callback = async (req, res, url) => {
         const code = url.searchParams.get('code') ?? '';
         const stateToken = url.searchParams.get('state') ?? '';
@@ -529,20 +496,16 @@ export function buildAuthServer(config, deps = {}) {
         if (st.flow === 'alias_reauth') {
             if (!st.alias)
                 return errorPage(res, 400, 'invalid_request', 'alias_reauth without an alias');
-            // C13 / identity binding (#2/#6): only overwrite the alias's tokens if the
-            // completing Google identity IS that alias's configured account — else an
-            // attacker who crafts an alias_reauth link and logs in with their OWN
-            // account could inject their tokens (account swap). The alias emails (leg
-            // C) are distinct from MCP_OWNER_EMAILS (leg B), so bind to the alias.
+            // Identity binding: only overwrite the alias's tokens if the completing
+            // Google identity matches the alias's configured account (else account swap).
             const gotEmail = (exchanged.email ?? '').toLowerCase();
             const expected = (deps.aliasEmail?.(st.alias) ?? '').toLowerCase();
             if (!expected || !gotEmail || gotEmail !== expected) {
                 log(`alias_reauth identity mismatch for "${logSafe(st.alias, 64)}" (got ${logSafe(gotEmail || 'none', 254)})`);
                 return errorPage(res, 403, 'access_denied', 'the Google account you signed in with is not the one configured for this alias');
             }
-            // A completion without a refresh token (a Google URL built without
-            // offline access, say) would replace a working credential with one that
-            // dies within the hour. Keep the stored token instead.
+            // A completion without a refresh token would replace a working credential
+            // with one that dies within the hour; keep the stored token instead.
             const refreshToken = exchanged.tokens.refresh_token;
             if (typeof refreshToken !== 'string' || refreshToken === '') {
                 log(`alias_reauth for "${logSafe(st.alias, 64)}" returned no refresh token; stored token kept`);
@@ -551,9 +514,8 @@ export function buildAuthServer(config, deps = {}) {
             const granted = typeof exchanged.tokens.scope === 'string' ? exchanged.tokens.scope : undefined;
             const missing = deps.missingScopes?.(st.alias, granted) ?? [];
             const listed = missing.map((m) => `<code>${escapeHtml(m)}</code>`).join(', ');
-            // A narrower grant replaces nothing that works. The link can be reused
-            // for an hour and the Google URL's scope is not signed, so a narrower
-            // grant is not necessarily the account holder's choice.
+            // A narrower grant replaces nothing that works: the link is reusable for
+            // an hour and the scope isn't signed, so it may not be the holder's choice.
             if (missing.length > 0 && deps.hasToken?.(st.alias)) {
                 log(`alias_reauth for "${logSafe(st.alias, 64)}" granted ${missing.length} fewer scope(s); stored token kept`);
                 res.writeHead(400, { 'Content-Type': 'text/html' });
@@ -570,9 +532,8 @@ export function buildAuthServer(config, deps = {}) {
             res.end(`<!doctype html><meta charset=utf-8><p>Re-authenticated "${escapeHtml(st.alias)}". You can close this window.</p>${gap}`);
             return true;
         }
-        // owner_gate: resolve the verified email to its subject (default = the
-        // owner allowlist -> 'owner'), discard Google tokens. The resolved sub is
-        // signed into the authz code and flows into every token minted from it.
+        // owner_gate: resolve the verified email to its subject (default: owner
+        // allowlist -> 'owner'), discard Google tokens; the sub signs into the authz code.
         const email = (exchanged.email ?? '').toLowerCase();
         const iss = encodeURIComponent(base);
         const resolved = email ? resolveSubject(email, { sub: exchanged.sub, hd: exchanged.hd }) : null;
@@ -590,7 +551,6 @@ export function buildAuthServer(config, deps = {}) {
         const s = st.client_state ? `&state=${encodeURIComponent(st.client_state)}` : '';
         return redirect(res, `${st.redirect_uri}${sep}code=${encodeURIComponent(authzCode)}${s}&iss=${iss}`);
     };
-    // POST /token
     const token = async (req, res) => {
         let form;
         try {
@@ -677,8 +637,7 @@ export function buildAuthServer(config, deps = {}) {
         }
         return json(res, 400, { error: 'unsupported_grant_type', message: 'authorization_code or refresh_token only' });
     };
-    // POST /register (minimal DCR, D2). Parse the raw JSON body directly (the
-    // redirect_uris array must survive intact).
+    // Parse the raw JSON body directly; the redirect_uris array must survive intact.
     const register = async (req, res) => {
         let parsed;
         try {

package/dist/oauth-consent.js

@@ -1,12 +1,8 @@
 import { OAuth2Client } from 'googleapis-common';
 import http from 'node:http';
 import { URL } from 'node:url';
-// Shared loopback OAuth consent (leg C of cc-auth), used by the account wizard
-// (B7) and the `auth --account` CLI. Live-server-safe: typed errors instead of
-// process.exit, and a timeout so a never-completed consent can't wedge a tool
-// call forever. The listener binds an EPHEMERAL loopback port (RFC 8252 §7.3;
-// Google Desktop clients accept any http://localhost:<port> redirect), so a
-// second local process on a fixed port can never break auth.
+// Shared loopback OAuth consent, used by the account wizard and `auth
+// --account`; a timeout keeps a never-completed consent from wedging a tool call forever.
 /** Google authorize-URL options for the owner's HTTP authorization server.
  * alias_reauth asks for the alias's scopes plus openid/email, which /callback
  * needs to bind the returned identity to the alias. It carries no login_hint:
@@ -44,10 +40,8 @@ export class ConsentDeniedError extends Error {
         super(`E_CONSENT_DENIED: ${reason}`);
     }
 }
-// Surfaced after every successful consent: the expiry is invisible until the
-// token dies a week later as reauth_required, so the moment of success is the
-// one place the warning is guaranteed to be seen. Full walkthrough in
-// docs/google-cloud-setup.md.
+// Surfaced after every successful consent: the moment of success is the one
+// place this warning is guaranteed to be seen, before the token dies a week later as reauth_required.
 export const TESTING_MODE_WARNING = 'Heads-up: while your OAuth client\'s Publishing status is "Testing", Google expires refresh tokens after 7 days (weekly re-auth for every account). ' +
     'When your setup works, set it to "In production" at https://console.cloud.google.com/auth/audience. ' +
     'No verification review is needed for personal use; see docs/google-cloud-setup.md.';

package/dist/outbound-allowlist.js

@@ -1,8 +1,5 @@
-// Opt-in outbound recipient allowlist for unattended deployments: a
-// prompt-injection blast-radius control (a hijacked agent cannot mail, invite
-// or share outside the operator's list), a safety feature first and an
-// enterprise checkbox second. FREE-core forever (ee-definition-v0 handoff).
-// Off by default: an unset/empty GOOGLE_OUTBOUND_ALLOWLIST gates nothing.
+// Opt-in outbound recipient allowlist: a prompt-injection blast-radius
+// control (a hijacked agent cannot mail/invite/share outside the operator's list). Off by default.
 import { hints } from './hint-provider.js';
 /** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
  * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
@@ -59,10 +56,8 @@ export function checkOutbound(kind, emails, account, env = process.env) {
     const blocked = outboundViolations(emails, env);
     return blocked.length > 0 ? outboundDeniedEnvelope(kind, blocked, account, env) : null;
 }
-// Escape-hatch / generated-tool enforcement. Structured bodies are inspected
-// for the known recipient fields; RAW compose methods cannot be inspected
-// (base64 RFC 822), so with the allowlist active they are refused outright in
-// favor of the curated tools that enforce it.
+// RAW compose methods can't be inspected (base64 RFC 822), so with the
+// allowlist active they're refused outright in favor of the curated tools that enforce it.
 const RAW_SEND_METHODS = new Set(['gmail.users.messages.send', 'gmail.users.drafts.send', 'gmail.users.drafts.create', 'gmail.users.messages.insert', 'gmail.users.messages.import']);
 export function collectBodyRecipients(body) {
     const out = [];

package/dist/reauth-hint.js

@@ -1,8 +1,5 @@
-// B13 in-call re-auth (BV-1): a dead/missing per-account Google token is a
-// leg-C failure. Over stdio the fix is the `auth --account` CLI; over HTTP the
-// user cannot run a CLI, so the hint becomes a clickable, server-signed link
-// into the AS's clientless alias_reauth flow (AuthServer.reauthLink). The HTTP
-// bootstrap installs the linker when the AS starts; stdio never does.
+// Over stdio the fix is the `auth --account` CLI; over HTTP it's a clickable,
+// server-signed link instead, installed by the AS bootstrap. See docs/internals.md.
 import { hints } from './hint-provider.js';
 let httpReauthLink = null;
 export function setHttpReauthLink(linker) {

package/dist/registry-transfer.d.ts

@@ -1,4 +1,4 @@
-/** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
+/** Refuse-only for v1: export/import operate on the FLAT single-owner
  * store. A tenant-namespaced layout means the bundle would either miss every
  * tenant's tokens or exfiltrate all of them in one file — refuse instead.
  * Returns the offending dir, or null when the store is flat. */

package/dist/registry-transfer.js

@@ -1,9 +1,5 @@
-// B19: encrypted registry export / import (account-registry.md). Moves a whole
-// setup to another machine. The bundle is encrypted under a user PASSPHRASE
-// (portable across machines with different MASTER_KEYs) via the token-store AES
-// primitives; the bundled <alias>.enc token files stay encrypted under the
-// SOURCE MASTER_KEY (double-locked), so the target needs the same MASTER_KEY to
-// use them. Secrets (MASTER_KEY / client secret) are never in the bundle.
+// Encrypted registry export/import: the bundle is passphrase-encrypted, but
+// the bundled <alias>.enc files stay double-locked under the SOURCE MASTER_KEY.
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as readline from 'node:readline';
 import path from 'node:path';
@@ -11,7 +7,7 @@ import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:
 import { atomicWriteFileSync, atomicWriteWithLock } from './fs-atomic.js';
 import { ALIAS_RE, configFilePath, CONFIG_VERSION, tenantsDir } from './config-file.js';
 import { getTokenDir } from './accounts.js';
-/** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
+/** Refuse-only for v1: export/import operate on the FLAT single-owner
  * store. A tenant-namespaced layout means the bundle would either miss every
  * tenant's tokens or exfiltrate all of them in one file — refuse instead.
  * Returns the offending dir, or null when the store is flat. */
@@ -61,12 +57,8 @@ export function buildTransferBundle(exportedAt, deps = {}) {
     }
     return { manifest: { v: 1, exportedAt, aliases: [...aliasSet].sort() }, config, tokens };
 }
-// Bundle envelope v2: a REAL passphrase KDF. The v1 envelope reused the
-// token store's deriveKey, whose passphrase branch is one unsalted sha256 —
-// an exported bundle could be brute-forced offline (CodeQL
-// js/insufficient-password-hash). scrypt with a per-bundle random salt fixes
-// that; v1 bundles (a prerelease-only format, never produced by any stable
-// release) are refused with a re-export hint rather than kept decryptable.
+// v2: a REAL passphrase KDF (scrypt, per-bundle salt). v1 reused the token
+// store's unsalted-sha256 passphrase branch (CodeQL js/insufficient-password-hash) and is refused outright.
 const BUNDLE_VERSION = 2;
 const SCRYPT_PARAMS = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 function bundleKey(passphrase, salt) {

package/dist/registry.d.ts

@@ -51,8 +51,6 @@ export declare class ToolRegistry {
     private readonly revealed;
     private readonly jsonSchemaCache;
     private readonly argShapeCache;
-    /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
-     * bundle catalog only, so it never changes within a process. */
     private readonly ungrantable;
     private readonly compactOutput;
     private registeringMeta;
@@ -106,7 +104,7 @@ export declare class ToolRegistry {
     /** discover_all: advertise the full curated set at once. Idempotent. */
     expand(): boolean;
     /** discover_reset: back to the lean meta-only surface. Clears reveals too.
-     * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
+     * If a client mishandles a SHRINKING tools/list, this degrades to a
      * no-op for that session — tools stay callable regardless (graceful
      * dispatch), zero correctness impact. */
     collapse(): boolean;
@@ -128,11 +126,5 @@ export declare class ToolRegistry {
     };
     installListHandler(): void;
     private toToolJson;
-    /** Advertise the CURRENT alias enum on every tools/list: account validation
-     * is (or is becoming) live, so a cached boot-time enum would go stale the
-     * moment account_add lands mid-session. The structural schema stays cached;
-     * only the account property's values are refreshed per call. Skipped for
-     * the subject-taking account tools (their `account` is the OPERAND, e.g. a
-     * brand-new alias name, not an identity to enumerate). */
     private withLiveAccountEnum;
 }