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

package/dist/index.js

@@ -1,97 +1,25 @@
 #!/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).
-import { assertServerAccountsConfigured, getAccountSet } from './accounts.js';
+// 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 { GENERATED_SERVICES } from './tools/generated/index.js';
-import { GENERATED_GATES, SERVICES, unknownToolMessage } from './services.js';
-import { ToolRegistry, resolveDiscoveryMode } 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 { resolveDiscoveryMode } from './registry.js';
 import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
+import { buildRegistry, createMcpServer, requestHooksFor } from './compose.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
-import { argNormalizationEnabled, withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
-import { unknownArgMode } from './arg-strict.js';
+import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
 import { envValueSource } from './env-load.js';
 import { loadConfigFile } from './config-file.js';
 import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-/** Unknown-argument screening options, or undefined when the feature is off.
- * Shared by both transports so a mistyped argument behaves identically. */
-function strictArgOptions(registry, metrics) {
-    const mode = unknownArgMode();
-    if (mode === 'off')
-        return undefined;
-    return {
-        mode,
-        declaredFor: (tool) => registry.declaredKeys(tool),
-        siblingsFor: (tool, keys) => registry.siblingSpellings(tool, keys),
-        unknownTool: (name) => unknownToolMessage(registry, name),
-        onDrop: metrics ? (tool, keys) => metrics.recordArgDrop(tool, keys) : undefined,
-    };
-}
-function buildRegistry(server, ctx, mode, metrics = null) {
-    const policy = ctx.policy;
-    const registry = new ToolRegistry(server, policy, mode, metrics);
-    const toolsets = getToolsets();
-    if (toolsets !== 'all') {
-        const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
-        for (const requested of toolsets) {
-            if (!known.has(requested)) {
-                process.stderr.write(`GOOGLE_TOOLSETS: unknown service "${requested}" ignored\n`);
-            }
-        }
-    }
-    for (const svc of SERVICES) {
-        if (!toolsetEnabled(toolsets, svc.name))
-            continue;
-        if (svc.enabled && !svc.enabled()) {
-            if (toolsets !== 'all') {
-                const hint = svc.name === 'admin' ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS)' : `add "${svc.name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`;
-                process.stderr.write(`GOOGLE_TOOLSETS: "${svc.name}" requested but not enabled — ${hint}\n`);
-            }
-            continue;
-        }
-        svc.register(registry);
-    }
-    for (const gen of GENERATED_SERVICES) {
-        if (!toolsetEnabled(toolsets, gen.name))
-            continue;
-        const curated = SERVICES.find((s) => s.name === gen.name);
-        const gate = curated?.enabled ?? GENERATED_GATES[gen.name]?.enabled;
-        if (gate && !gate()) {
-            if (!curated && toolsets !== 'all') {
-                process.stderr.write(`GOOGLE_TOOLSETS: "${gen.name}" requested but not enabled — ${GENERATED_GATES[gen.name].hint}\n`);
-            }
-            continue;
-        }
-        gen.register(registry);
-    }
-    if (registry.services().length === 0) {
-        const known = [...new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)])].sort();
-        throw new Error(`GOOGLE_TOOLSETS="${process.env.GOOGLE_TOOLSETS ?? ''}" selected no enabled services. ` +
-            `Known services: ${known.join(', ')}. ` +
-            `Note: optional services need their bundle in an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES); admin needs an admin account/profile.`);
-    }
-    registerDiscoverTools(registry, policy);
-    registerEscapeTools(registry, policy);
-    registerAccountTools(registry);
-    registerDiagnoseTool(registry);
-    registerAccountWizardTools(registry, server);
-    return registry;
-}
 async function main() {
     if (process.argv.includes('auth')) {
         const { runAuthFlow } = await import('./auth.js');
@@ -152,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();
@@ -198,14 +126,8 @@ async function main() {
         }
         return;
     }
-    // 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();
+    // Transport derivation FIRST: the accounts gate below is transport-aware
+    // (a multi-tenant HTTP deploy legitimately boots with zero accounts).
     const { resolveHttpConfig, transportIncludesHttp } = await import('./http-config.js');
     let httpCfg;
     try {
@@ -217,9 +139,20 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
-    // 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`.
+    // 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();
+    if (mt) {
+        assertNoEnvAccountsMode();
+        assertNoEnvOptionalScopesMode();
+    }
+    // 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();
+    // 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)
@@ -249,80 +182,69 @@ 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 registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }), undefined, stdioMetrics);
+        const stdioCtx = buildIdentityContext(process.env, { transport: 'stdio' });
+        const registry = buildRegistry(server, stdioCtx, undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
-        // 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.
-        let transport = withValidationEnvelope(new StdioServerTransport(), {
-            isKnownTool: (n) => registry.hasTool(n),
-            defaultAccount: () => getAccountSet().defaultAccount,
-        });
+        const stdioHooks = requestHooksFor(registry, stdioCtx, stdioMetrics);
+        // 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');
             transport = tapUsageMetrics(transport, stdioMetrics, (n) => registry.hasTool(n));
         }
-        const strictStdio = strictArgOptions(registry, stdioMetrics);
-        await server.connect(argNormalizationEnabled() || strictStdio
+        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.
-            argNormalizationEnabled() ? (n) => registry.argShape(n) : () => undefined, undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, strictStdio)
+            // 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);
     }
     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);
+        const gates = mtBootGates();
+        if (gates?.multiTenant) {
+            // Same fail-fast shape as below, but the gate is "a valid provisioning
+            // mechanism exists", not a flat owner allowlist.
+            gates.assertProvisioningGate();
+        }
+        else {
+            // 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 registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated', httpMetrics);
+        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.
-        const { buildAuthServer } = await import('./oauth-as.js');
+        // 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');
         const { OAuth2Client } = await import('googleapis-common');
-        const { writeToken } = await import('./token-store.js');
+        const { readToken, writeToken } = await import('./token-store.js');
         const { resolveScopesForAccount } = await import('./auth.js');
+        const { ownerAuthUrlOptions } = await import('./oauth-consent.js');
+        const { scopeGrantDiff, setWizardHttpConsent } = await import('./tools/account-wizard.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,
@@ -333,20 +255,7 @@ async function main() {
             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 });
-            },
+            buildGoogleAuthUrl: ({ flow, alias, state }) => googleClient().generateAuthUrl(ownerAuthUrlOptions({ flow, alias, state }, (a) => resolveScopesForAccount(a))),
             exchangeCode: async (code, flow) => {
                 const { tokens } = await googleClient().getToken(code);
                 const email = verifiedEmailFromIdToken(tokens.id_token ?? undefined);
@@ -355,13 +264,25 @@ async function main() {
                 return { tokens: flow === 'owner_gate' ? {} : tokens, email };
             },
             writeToken: (alias, tokens) => writeToken(alias, tokens),
+            missingScopes: (alias, granted) => scopeGrantDiff(resolveScopesForAccount(alias), granted),
+            hasToken: (alias) => {
+                try {
+                    return readToken(alias) != null;
+                }
+                catch {
+                    return false; // undecryptable: nothing usable to keep
+                }
+            },
             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);
+        // 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));
+        // Wizard consent over HTTP: hand out the same signed link instead of
+        // binding a loopback listener.
+        setWizardHttpConsent({ mintConsentUrl: (alias) => authServer.reauthLink(alias) });
         let httpTap;
         if (httpMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
@@ -375,18 +296,13 @@ async function main() {
             authenticate: authServer.authenticate,
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
-            argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
+            ...requestHooksFor(registry, httpCtx, httpMetrics),
             metricsTap: httpTap,
-            validationEnvelope: {
-                isKnownTool: (n) => registry.hasTool(n),
-                defaultAccount: () => getAccountSet().defaultAccount,
-            },
             onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
-            strictArgs: strictArgOptions(registry, httpMetrics),
         });
         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,23 +30,24 @@ 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;
 }
-// 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.
-function anyTokenFileExists() {
+function anyEncFileUnder(dir) {
     try {
-        return fs.readdirSync(getTokenDir()).some((f) => f.endsWith('.enc'));
+        return fs.readdirSync(dir, { recursive: true }).some((f) => String(f).endsWith('.enc'));
     }
     catch {
         return false;
     }
 }
+// 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());
+}
 function readKeyFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf8').trim();
@@ -90,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()}. ` +
@@ -107,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.`);
@@ -143,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)
@@ -181,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,
@@ -203,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