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

package/dist/master-key.js

@@ -0,0 +1,242 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+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.
+const require_ = createRequire(import.meta.url);
+function systemKeychain(account) {
+    try {
+        const { Entry } = require_('@napi-rs/keyring');
+        const entry = new Entry('mcp-google-multi', account);
+        return {
+            get: () => {
+                try {
+                    return entry.getPassword();
+                }
+                catch {
+                    return null;
+                }
+            },
+            set: (value) => entry.setPassword(value),
+            del: () => entry.deletePassword(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// 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).
+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() {
+    try {
+        return fs.readdirSync(getTokenDir()).some((f) => f.endsWith('.enc'));
+    }
+    catch {
+        return false;
+    }
+}
+function readKeyFile(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8').trim();
+        if (!raw)
+            return null;
+        try {
+            const mode = fs.statSync(filePath).mode & 0o777;
+            if (process.platform !== 'win32' && (mode & 0o077) !== 0) {
+                process.stderr.write(`WARN: ${filePath} is readable by others (mode ${mode.toString(8)}); chmod 600 it.\n`);
+            }
+        }
+        catch {
+            // stat raced a delete; the read already succeeded.
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveKey(envName, fileName, hardGuard, deps, onFail = 'exit') {
+    const env = deps.env ?? process.env;
+    const dir = deps.dir ?? configDir();
+    const keychain = deps.keychain ?? keychainFactory;
+    const hasAnyToken = deps.hasAnyToken ?? anyTokenFileExists;
+    const fail = (slug, message) => {
+        if (onFail === 'throw')
+            throw new Error(`${slug}: ${message}`);
+        failStartup(slug, message);
+    };
+    const fromEnv = env[envName]?.trim();
+    if (fromEnv)
+        return { key: fromEnv, provenance: 'env' };
+    const entry = keychain(envName);
+    const fromKeychain = entry?.get();
+    if (fromKeychain)
+        return { key: fromKeychain, provenance: 'keychain' };
+    const filePath = path.join(dir, fileName);
+    const fromFile = readKeyFile(filePath);
+    if (fromFile)
+        return { key: fromFile, provenance: 'file' };
+    // Generate-on-setup. The hard guard is cc-security Cgen: 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()}. ` +
+            'Restore the original key, or delete those .enc files and re-auth each account.');
+    }
+    // Lock the generate critical section so two concurrent first-boots cannot
+    // both mint (the loser re-reads the winner's key under the lock).
+    return withFileLock(filePath, () => {
+        const racedKeychain = keychain(envName)?.get();
+        if (racedKeychain)
+            return { key: racedKeychain, provenance: 'keychain' };
+        const racedFile = readKeyFile(filePath);
+        if (racedFile)
+            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.
+        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.`);
+        }
+        // Keychain copy is best-effort QoL; a mismatched read-back would SHADOW
+        // the file on the next boot (keychain > file), so clean it up.
+        let keychainNote = '';
+        try {
+            if (entry) {
+                entry.set(generated);
+                if (keychain(envName)?.get() === generated) {
+                    keychainNote = ' and the OS keychain (service mcp-google-multi)';
+                }
+                else {
+                    try {
+                        entry.del();
+                    }
+                    catch {
+                        process.stderr.write(`WARN: OS keychain holds a mismatched ${envName} entry; the ${fileName} file is authoritative.\n`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Keychain unavailable; the file already has the key.
+        }
+        process.stderr.write(`Generated ${envName}: stored at ${filePath} (0600)${keychainNote}.\n`);
+        return { key: generated, provenance: 'generated' };
+    }, `${envName} provisioning`);
+}
+let cachedMaster = null;
+let cachedJwt = null;
+/** BR-1 single choke point: no other module may read the env vars directly.
+ * Boot/CLI form: failures exit with a clean stderr slug ("fatal at startup"). */
+export function resolveMasterKey(deps) {
+    if (deps)
+        return resolveKey('MASTER_KEY', 'master.key', true, deps);
+    cachedMaster ??= resolveKey('MASTER_KEY', 'master.key', true, {});
+    return cachedMaster;
+}
+/** Dispatch form: identical resolution, but failures THROW (caught by the tool
+ * handler into an error envelope) — a live server is never process.exit'd. */
+export function resolveMasterKeyForDispatch() {
+    cachedMaster ??= resolveKey('MASTER_KEY', 'master.key', true, {}, 'throw');
+    return cachedMaster;
+}
+/** Side-effect-free provenance probe for diagnostics: NEVER generates, never
+ * fires the hard guard (config check must not mint keys or exit). */
+export function peekMasterKeyProvenance(deps) {
+    const env = deps?.env ?? process.env;
+    if (env.MASTER_KEY?.trim())
+        return 'env';
+    const keychain = deps?.keychain ?? keychainFactory;
+    if (keychain('MASTER_KEY')?.get())
+        return 'keychain';
+    const dir = deps?.dir ?? configDir();
+    if (readKeyFile(path.join(dir, 'master.key')))
+        return 'file';
+    return 'unprovisioned';
+}
+/** MCP_JWT_KEY variant: NO hard guard — regenerating only invalidates
+ * outstanding MCP tokens and clients re-auth silently. */
+export function resolveJwtKey(deps) {
+    if (deps)
+        return resolveKey('MCP_JWT_KEY', 'mcp-jwt.key', false, deps);
+    cachedJwt ??= resolveKey('MCP_JWT_KEY', 'mcp-jwt.key', false, {});
+    return cachedJwt;
+}
+let mirrored = false;
+/**
+ * BR-5: after the FIRST successful token decrypt with an env-sourced key,
+ * mirror it into the keychain (only when the keychain holds no entry) so the
+ * key survives an env loss. Gating on a successful decrypt means a stale or
+ * wrong env key is never mirrored. Best-effort: failures are doctor material,
+ * never fatal.
+ */
+export function noteSuccessfulDecrypt() {
+    if (mirrored)
+        return;
+    mirrored = true;
+    try {
+        if (cachedMaster?.provenance !== 'env')
+            return;
+        const entry = keychainFactory('MASTER_KEY');
+        if (!entry || entry.get())
+            return;
+        entry.set(cachedMaster.key);
+    }
+    catch {
+        // Keychain backend unavailable; env stays the working source.
+    }
+}
+/** B6 reset: drop the generated MASTER_KEY material (0600 file + keychain
+ * entry) so the next run re-provisions. Never removes an env-provided key (the
+ * deployer owns that; `env:true` flags it so reset can warn). The caller MUST
+ * have wiped every .enc token first — regenerating with tokens present would
+ * brick them (enforced by the reset planner). */
+export function deleteMasterKeyMaterial(deps) {
+    const dir = deps?.dir ?? configDir();
+    const keychain = deps?.keychain ?? keychainFactory;
+    const env = Boolean(process.env.MASTER_KEY?.trim());
+    let file = false;
+    let kc = false;
+    try {
+        fs.unlinkSync(path.join(dir, 'master.key'));
+        file = true;
+    }
+    catch {
+        // already absent
+    }
+    try {
+        const entry = keychain('MASTER_KEY');
+        if (entry && entry.get()) {
+            entry.del();
+            kc = true;
+        }
+    }
+    catch {
+        // keychain unavailable
+    }
+    cachedMaster = null;
+    return { file, keychain: kc, env };
+}
+/** Test hook: the production cache is process-lifetime by design. */
+export function clearKeyCacheForTest() {
+    cachedMaster = null;
+    cachedJwt = null;
+    mirrored = false;
+}

package/dist/mcp-token.d.ts

@@ -0,0 +1,81 @@
+export declare const ACCESS_TTL_DEFAULT = 600;
+export declare const STATE_TTL_DEFAULT = 600;
+export declare const CODE_TTL_DEFAULT = 60;
+export declare const REPLAY_CAP_DEFAULT = 10000;
+/** Derive the HS256 secret (32 bytes) from the provisioned MCP_JWT_KEY string. */
+export declare function jwtSecretFrom(jwtKey: string): Uint8Array;
+export interface AccessTokenParams {
+    base: string;
+    secret: Uint8Array;
+    ttlSec?: number;
+    iat: number;
+}
+export declare function signAccessToken(p: AccessTokenParams): Promise<string>;
+export interface AccessClaims {
+    sub: string;
+    scope: string;
+    jti: string;
+}
+/** Verify an access token for `/mcp`. Throws on bad sig / aud / iss / exp. */
+export declare function verifyAccessToken(token: string, base: string, secret: Uint8Array): Promise<AccessClaims>;
+export interface StatePayload {
+    flow: 'owner_gate' | 'alias_reauth';
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    client_state?: string;
+    resource: string;
+    alias?: string;
+}
+export interface CodePayload {
+    redirect_uri: string;
+    code_challenge: string;
+    resource: string;
+    sub: 'owner';
+}
+export declare function signState(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
+export declare function verifyState(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+    jti: string;
+}>;
+/** A pending-authorization artifact for the DCR consent interstitial (same
+ * shape as `state`, distinct purpose so the two can't be confused). */
+export declare function signPending(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
+export declare function verifyPending(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+    jti: string;
+}>;
+export declare function signAuthzCode(payload: CodePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
+export declare function verifyAuthzCode(token: string, base: string, secret: Uint8Array): Promise<CodePayload & {
+    jti: string;
+}>;
+export declare class ReplayGuard {
+    private readonly cap;
+    private readonly seen;
+    constructor(cap?: number);
+    /** Record a jti as spent. Returns false if it was already spent (replay). */
+    consume(jti: string, ttlMs: number, nowMs: number): boolean;
+    get size(): number;
+    private evictExpired;
+}
+export interface RefreshRecord {
+    sub: 'owner';
+    issuedAt: number;
+    family: string;
+}
+/**
+ * Persisted (encrypted under MASTER_KEY) opaque refresh-token store. Rotates on
+ * every use (a stolen token is usable at most once), and detects REUSE of a
+ * rotated-away token as theft: the whole token family is revoked (#7 / C14).
+ * All read-modify-write goes through a file lock so concurrent stdio+HTTP
+ * processes can't lost-update or double-spend (#12).
+ */
+export declare class RefreshStore {
+    private readonly path;
+    private readonly masterKey;
+    constructor(path: string, masterKey: string);
+    private load;
+    private save;
+    issue(nowMs: number, family?: string): string;
+    /** Rotate a presented refresh token; null if unknown OR if the presented
+     * token was already rotated away (reuse => the family is revoked). */
+    rotate(oldToken: string, nowMs: number): string | null;
+}

package/dist/mcp-token.js

@@ -0,0 +1,176 @@
+// 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 opaque rotated refresh-token store. Keyed by the provisioned MCP_JWT_KEY
+// (B5), so tokens survive a restart as long as the key persists.
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { SignJWT, jwtVerify } from 'jose';
+import { deriveKey, encryptToken, decryptToken } from './token-store.js';
+import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
+export const ACCESS_TTL_DEFAULT = 600; // seconds
+export const STATE_TTL_DEFAULT = 600;
+export const CODE_TTL_DEFAULT = 60;
+export const REPLAY_CAP_DEFAULT = 10_000;
+/** Derive the HS256 secret (32 bytes) from the provisioned MCP_JWT_KEY string. */
+export function jwtSecretFrom(jwtKey) {
+    return new Uint8Array(deriveKey(jwtKey));
+}
+function newJti() {
+    return randomBytes(16).toString('base64url');
+}
+export async function signAccessToken(p) {
+    const ttl = p.ttlSec ?? ACCESS_TTL_DEFAULT;
+    return new SignJWT({ scope: 'mcp:use', purpose: 'mcp_access' })
+        .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+        .setIssuer(p.base)
+        .setSubject('owner')
+        .setAudience(`${p.base}/mcp`)
+        .setIssuedAt(p.iat)
+        .setExpirationTime(p.iat + ttl)
+        .setJti(newJti())
+        .sign(p.secret);
+}
+/** Verify an access token for `/mcp`. Throws on bad sig / aud / iss / exp. */
+export async function verifyAccessToken(token, base, secret) {
+    const { payload } = await jwtVerify(token, secret, { issuer: base, audience: `${base}/mcp` });
+    if (payload.purpose !== 'mcp_access')
+        throw new Error('wrong token purpose');
+    return { sub: String(payload.sub), scope: String(payload.scope ?? ''), jti: String(payload.jti ?? '') };
+}
+async function signArtifact(claims, purpose, base, secret, iat, ttlSec) {
+    return new SignJWT({ ...claims, purpose })
+        .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+        .setIssuer(base)
+        .setIssuedAt(iat)
+        .setExpirationTime(iat + ttlSec)
+        .setJti(newJti())
+        .sign(secret);
+}
+async function verifyArtifact(token, purpose, base, secret) {
+    const { payload } = await jwtVerify(token, secret, { issuer: base });
+    if (payload.purpose !== purpose)
+        throw new Error(`wrong artifact purpose (${String(payload.purpose)})`);
+    return { ...payload, jti: String(payload.jti ?? '') };
+}
+export function signState(payload, base, secret, iat, ttlSec = STATE_TTL_DEFAULT) {
+    return signArtifact(payload, 'mcp_state', base, secret, iat, ttlSec);
+}
+export async function verifyState(token, base, secret) {
+    return (await verifyArtifact(token, 'mcp_state', base, secret));
+}
+/** A pending-authorization artifact for the DCR consent interstitial (same
+ * shape as `state`, distinct purpose so the two can't be confused). */
+export function signPending(payload, base, secret, iat, ttlSec = STATE_TTL_DEFAULT) {
+    return signArtifact(payload, 'mcp_pending', base, secret, iat, ttlSec);
+}
+export async function verifyPending(token, base, secret) {
+    return (await verifyArtifact(token, 'mcp_pending', base, secret));
+}
+export function signAuthzCode(payload, base, secret, iat, ttlSec = CODE_TTL_DEFAULT) {
+    return signArtifact(payload, 'mcp_code', base, secret, iat, ttlSec);
+}
+export async function verifyAuthzCode(token, base, secret) {
+    return (await verifyArtifact(token, 'mcp_code', base, secret));
+}
+// --- Replay guard (C10/C17: single-use, capped, TTL-evicted) ----------------
+export class ReplayGuard {
+    cap;
+    seen = new Map(); // jti -> expiry (ms)
+    constructor(cap = REPLAY_CAP_DEFAULT) {
+        this.cap = cap;
+    }
+    /** Record a jti as spent. Returns false if it was already spent (replay). */
+    consume(jti, ttlMs, nowMs) {
+        this.evictExpired(nowMs);
+        if (this.seen.has(jti))
+            return false;
+        if (this.seen.size >= this.cap) {
+            // drop the oldest-inserted entry to bound memory (C17)
+            const oldest = this.seen.keys().next().value;
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+        this.seen.set(jti, nowMs + ttlMs);
+        return true;
+    }
+    get size() {
+        return this.seen.size;
+    }
+    evictExpired(nowMs) {
+        for (const [jti, exp] of this.seen) {
+            if (exp <= nowMs)
+                this.seen.delete(jti);
+        }
+    }
+}
+const SPENT_CAP = 2000;
+/**
+ * Persisted (encrypted under MASTER_KEY) opaque refresh-token store. Rotates on
+ * every use (a stolen token is usable at most once), and detects REUSE of a
+ * rotated-away token as theft: the whole token family is revoked (#7 / C14).
+ * All read-modify-write goes through a file lock so concurrent stdio+HTTP
+ * processes can't lost-update or double-spend (#12).
+ */
+export class RefreshStore {
+    path;
+    masterKey;
+    constructor(path, masterKey) {
+        this.path = path;
+        this.masterKey = masterKey;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return { active: {}, spent: {} };
+        try {
+            const d = decryptToken(readFileSync(this.path, 'utf-8'), this.masterKey);
+            return { active: d.active ?? {}, spent: d.spent ?? {} };
+        }
+        catch {
+            return { active: {}, spent: {} };
+        }
+    }
+    save(data) {
+        // bound the spent set (drop oldest-inserted) so it can't grow forever.
+        const keys = Object.keys(data.spent);
+        if (keys.length > SPENT_CAP) {
+            for (const k of keys.slice(0, keys.length - SPENT_CAP))
+                delete data.spent[k];
+        }
+        atomicWriteFileSync(this.path, encryptToken(data, this.masterKey), 0o600);
+    }
+    issue(nowMs, family) {
+        return withFileLock(this.path, () => {
+            const token = randomBytes(32).toString('base64url');
+            const data = this.load();
+            data.active[token] = { sub: 'owner', issuedAt: nowMs, family: family ?? randomBytes(12).toString('hex') };
+            this.save(data);
+            return token;
+        });
+    }
+    /** Rotate a presented refresh token; null if unknown OR if the presented
+     * token was already rotated away (reuse => the family is revoked). */
+    rotate(oldToken, nowMs) {
+        return withFileLock(this.path, () => {
+            const data = this.load();
+            const rec = data.active[oldToken];
+            if (!rec) {
+                // Reuse of a rotated-away token signals theft: revoke the whole family.
+                const fam = data.spent[oldToken];
+                if (fam) {
+                    for (const [t, r] of Object.entries(data.active))
+                        if (r.family === fam)
+                            delete data.active[t];
+                    this.save(data);
+                }
+                return null;
+            }
+            delete data.active[oldToken];
+            data.spent[oldToken] = rec.family;
+            const next = randomBytes(32).toString('base64url');
+            data.active[next] = { sub: 'owner', issuedAt: nowMs, family: rec.family };
+            this.save(data);
+            return next;
+        });
+    }
+}

package/dist/migrate-config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function runMigrateConfig(env?: NodeJS.ProcessEnv): void;

package/dist/migrate-config.js

@@ -0,0 +1,103 @@
+import { CONFIG_VERSION, configFilePath, loadConfigFile, mutateConfigFile } from './config-file.js';
+import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+function parseCsv(value) {
+    return (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * 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.
+ */
+export function runMigrateConfig(env = process.env) {
+    const raw = env.GOOGLE_ACCOUNTS;
+    if (!raw || raw.trim() === '') {
+        console.log('GOOGLE_ACCOUNTS is not set — nothing to migrate.');
+        return;
+    }
+    const adminAliases = parseCsv(env.GOOGLE_ADMIN_ACCOUNTS);
+    const desired = {};
+    const entries = raw.split(',');
+    for (let i = 0; i < entries.length; i++) {
+        const trimmed = entries[i].trim();
+        if (!trimmed)
+            continue;
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) {
+            console.error(`Skipping GOOGLE_ACCOUNTS entry ${i + 1}: expected alias:email.`);
+            continue;
+        }
+        const alias = trimmed.slice(0, colonIdx).trim();
+        const email = trimmed.slice(colonIdx + 1).trim();
+        if (!alias || !email || !/^[a-zA-Z0-9_-]+$/.test(alias)) {
+            console.error(`Skipping GOOGLE_ACCOUNTS entry ${i + 1}: empty or invalid alias/email.`);
+            continue;
+        }
+        desired[alias] = { email };
+    }
+    // Legacy global scopes (BC7) 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;
+    if (legacyNames.length > 0) {
+        const bundles = resolveBundleAliases(legacyNames);
+        for (const bundle of bundles) {
+            if (bundle === 'admin') {
+                console.error('E_UNKNOWN_BUNDLE: "admin" is not a global bundle: use GOOGLE_ADMIN_ACCOUNTS or an "admin: true" scope profile. Nothing written.');
+                process.exitCode = 1;
+                return;
+            }
+            if (!(bundle in BUNDLE_CATALOG)) {
+                const hint = closestBundle(bundle);
+                console.error(`E_UNKNOWN_BUNDLE: unknown bundle "${bundle}" in GOOGLE_OPTIONAL_SCOPES${hint ? ` — did you mean "${hint}"?` : ''}. Nothing written.`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        legacyProfile = { bundles };
+    }
+    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.
+    const existing = before?.accounts ?? {};
+    const dropped = Object.keys(existing).filter((a) => !(a in desired));
+    for (const [alias, entry] of Object.entries(desired)) {
+        const prev = existing[alias];
+        if (legacyProfile)
+            entry.scopeProfile = 'legacy-global';
+        else if (prev?.scopeProfile)
+            entry.scopeProfile = prev.scopeProfile;
+        if (adminAliases.length > 0) {
+            if (adminAliases.includes(alias))
+                entry.admin = true;
+        }
+        else if (prev?.admin) {
+            entry.admin = true;
+        }
+    }
+    const beforeAccounts = JSON.stringify(existing);
+    const beforeProfiles = JSON.stringify(before?.scopeProfiles ?? {});
+    const desiredProfiles = legacyProfile
+        ? { ...(before?.scopeProfiles ?? {}), 'legacy-global': legacyProfile }
+        : (before?.scopeProfiles ?? {});
+    if (beforeAccounts === JSON.stringify(desired) && beforeProfiles === JSON.stringify(desiredProfiles)) {
+        console.log(`${filePath} already matches the environment — nothing to do.`);
+        return;
+    }
+    mutateConfigFile((current) => {
+        current.version = current.version || CONFIG_VERSION;
+        current.accounts = desired;
+        if (legacyProfile)
+            current.scopeProfiles = desiredProfiles;
+        return current;
+    }, filePath);
+    if (dropped.length > 0) {
+        console.error(`Dropping ${dropped.length} alias(es) present in config.json but absent from GOOGLE_ACCOUNTS.`);
+    }
+    console.log(`Wrote ${filePath}:`);
+    console.log(`  accounts before: ${beforeAccounts}`);
+    console.log(`  accounts after:  ${JSON.stringify(desired)}`);
+    console.log('Environment variables were NOT modified; while GOOGLE_ACCOUNTS is set, env still wins.');
+}

package/dist/migrate-tokens.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
-import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { getAccountSet } from './accounts.js';
 import { writeToken, hasToken } from './token-store.js';
 export function runMigrateTokens() {
     let migrated = 0;
     let skipped = 0;
-    for (const alias of ACCOUNTS) {
-        const plain = ACCOUNT_CONFIG[alias].tokenPath;
+    const { aliases, configs } = getAccountSet();
+    for (const alias of aliases) {
+        const plain = configs[alias].tokenPath;
         if (!fs.existsSync(plain))
             continue;
         if (hasToken(alias)) {

package/dist/net-tuning.d.ts

@@ -0,0 +1,8 @@
+export declare const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+/** Pure decision: the timeout to apply, or null to leave Node's setting alone. */
+export declare function decideConnectAttemptTimeout(opts: {
+    execArgv: readonly string[];
+    nodeOptions: string | undefined;
+    current: number;
+}): number | null;
+export declare function applyNetTuning(): void;

package/dist/net-tuning.js

@@ -0,0 +1,25 @@
+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.
+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. */
+export function decideConnectAttemptTimeout(opts) {
+    const userArgs = [...opts.execArgv, opts.nodeOptions ?? ''].join(' ');
+    if (USER_FLAGS.some((f) => userArgs.includes(f)))
+        return null;
+    if (opts.current >= CONNECT_ATTEMPT_TIMEOUT_MS)
+        return null;
+    return CONNECT_ATTEMPT_TIMEOUT_MS;
+}
+export function applyNetTuning() {
+    const timeout = decideConnectAttemptTimeout({
+        execArgv: process.execArgv,
+        nodeOptions: process.env.NODE_OPTIONS,
+        current: net.getDefaultAutoSelectFamilyAttemptTimeout(),
+    });
+    if (timeout !== null)
+        net.setDefaultAutoSelectFamilyAttemptTimeout(timeout);
+}