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

package/dist/master-key.js

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

package/dist/mcp-token.d.ts

@@ -88,7 +88,7 @@ export declare class ReplayGuard {
     reserve(jti: string, ttlMs: number, nowMs: number): 'ok' | 'full';
     /** Record a jti as spent. A full guard refuses instead of evicting a live
      * jti: a flood of spends would otherwise make a spent artifact usable again,
-     * such as a callback the browser binding refused (H4 F1). `artifactExpMs`
+     * such as a callback the browser binding refused. `artifactExpMs`
      * keeps the record alive as long as the artifact itself, even when the clock
      * stepped back between its signing and this spend. */
     spend(jti: string, ttlMs: number, nowMs: number, artifactExpMs?: number): ReplaySpend;
@@ -107,12 +107,31 @@ export interface RefreshRecord {
     issuedAt: number;
     family: string;
 }
+/** A gen-1-behind token presented within this long of the rotation that
+ * retired it, from the same client, can be a concurrent duplicate rather
+ * than theft. See docs/internals.md. */
+export declare const REPLAY_WINDOW_MS = 30000;
+/** The store's own MAC key for `masterKey`, memoized. Exported so a caller
+ * that never touches a RefreshStore (the AS computing a request's
+ * clientFingerprint) can key it the same way the store does. */
+export declare function refreshMacKey(masterKey: string): Buffer;
 /**
  * The family tag of a refresh token this `masterKey`'s store minted, or null
  * for anything else. Derives the key once; the returned function does no I/O,
  * so a host can key a pre-auth rate limit on it.
  */
 export declare function refreshFamilyTagger(masterKey: string): (token: string) => string | null;
+/**
+ * A correlation tag for the client presenting a refresh token:
+ * HMAC-SHA256(key, client_id + "\n" + user-agent + "\n" + address), truncated
+ * to 16 bytes and base64url-encoded. `key` is the store's own MAC key
+ * (refreshMacKey), so computing it needs MASTER_KEY: a reader of the store
+ * file alone (`by` is stored, not these inputs) cannot brute-force the
+ * client_id/user-agent/address that produced it. It is still not a secret:
+ * anyone who can see a live request can send the same inputs and get the
+ * same tag. Pure, no I/O.
+ */
+export declare function clientFingerprint(clientId: string, userAgent: string, address: string, key: Buffer): string;
 /** Boot check for a refresh store file: returns when it is absent or this
  * release can read it; throws when it does not decrypt under `masterKey`
  * (E_REFRESH_STORE_UNREADABLE) or a newer release wrote it
@@ -138,10 +157,10 @@ export interface RefreshStoreOptions {
  * Persisted (encrypted under MASTER_KEY) refresh-token store. Rotates on every
  * use, and a token carries its family and generation under a MAC, so
  * presenting any generation the family has rotated past is REUSE: the family
- * is revoked for the rest of its life (#7 / C14, H4 F2). The store keeps one
+ * is revoked for the rest of its life. The store keeps one
  * record per family, whatever its rotation count. Every read-modify-write goes
  * through a file lock so concurrent stdio+HTTP processes can't lost-update or
- * double-spend (#12). See docs/internals.md.
+ * double-spend. See docs/internals.md.
  */
 export declare class RefreshStore {
     private readonly path;
@@ -165,19 +184,15 @@ export declare class RefreshStore {
     private load;
     private save;
     private emit;
-    /** Evict `sub`'s own least-recently-used sessions (both formats) so at
-     * most `limit` of its live sessions remain; dropping one here is the same
-     * as deleting it from `data.families` / `data.active` on a revoke, so it
-     * can never be presented again (reuse detection for every OTHER family is
-     * untouched). Only `sub`'s own entries are ever inspected.
-     *
-     * `keepKey` is the family just issued: it is excluded from the ranking so
-     * a clock step back, or a concurrent rotate's `usedAt = max(usedAt, nowMs)`
-     * racing ahead of it under the lock, can never make the brand-new family
-     * look like the least recently used one and drop itself. */
     private enforceFamilyCap;
     private newFamilyId;
-    issue(nowMs: number, sub: string): string;
+    issue(nowMs: number, sub: string, fingerprint?: string): string;
+    /** A presented token exactly one generation behind `f`, inside the replay
+     * window, from the fingerprint that retired it, whose derived successor
+     * matches `f.cur`: a concurrent duplicate request rather than theft (see
+     * docs/internals.md). Null for anything else at that generation, including
+     * a different rand (a genuinely different gen-1 token) or no fingerprint. */
+    private concurrentDuplicate;
     /** Rotate a presented refresh token; null if it is unknown, malformed, or
      * rotated away (reuse => the family is revoked). The record's sub is copied
      * forward and returned so the caller can mint the matching access token
@@ -186,8 +201,17 @@ export declare class RefreshStore {
      * `accept` (optional) is called inside the store lock, before any mutation,
      * with the record's sub. false: every session of that sub is dropped and
      * null returned. A throw: nothing is written and the error propagates, so
-     * the presented token stays valid. Absent: unchanged. */
-    rotate(oldToken: string, nowMs: number, accept?: (sub: string) => boolean): {
+     * the presented token stays valid. Absent: unchanged.
+     *
+     * `fingerprint` (optional) names the presenting client (clientFingerprint).
+     * Absent: a rotated-away token is always reuse, as before. Present: a
+     * token exactly one generation behind, from the same fingerprint, presented
+     * no earlier than and at most REPLAY_WINDOW_MS after the rotation that
+     * retired it, is a concurrent duplicate: it gets back the SAME successor
+     * token, with no change to the family (not even `usedAt`). Anything else
+     * rotated-away is still reuse, including a clock that has stepped back
+     * past `usedAt`, which cannot be told apart from a genuinely stale replay. */
+    rotate(oldToken: string, nowMs: number, accept?: (sub: string) => boolean, fingerprint?: string): {
         token: string;
         sub: string;
     } | null;

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,31 +185,42 @@ 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');
+// Domain-separated from R1_MAC_DOMAIN: a successor derived under this key
+// must never verify as a current token's own MAC, or vice versa.
+const R1_SUCCESSOR_DOMAIN = Buffer.from('mcp-google-multi refresh r1 successor\n');
+// Domain-separated from both of the above: a fingerprint must never verify as
+// either a token MAC or a successor derivation under the same key.
+const R1_FINGERPRINT_DOMAIN = Buffer.from('mcp-google-multi refresh r1 fingerprint\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;
 const LEGACY_TOKEN = /^[A-Za-z0-9_-]{43}$/;
 /** With a lifetime set, a stored time further ahead than this is pulled back to the clock. */
 const CLOCK_SKEW_MS = 5 * 60_000;
+/** A gen-1-behind token presented within this long of the rotation that
+ * retired it, from the same client, can be a concurrent duplicate rather
+ * than theft. See docs/internals.md. */
+export const REPLAY_WINDOW_MS = 30_000;
 const B64URL = /^[A-Za-z0-9_-]+$/;
 const sha256 = (b) => createHash('sha256').update(b).digest();
 /** A non-secret tag for log lines and rate-limit keys: never the token. */
 const familyTag = (family) => sha256(family).toString('hex').slice(0, 8);
 // Keyed on the master key: scrypt runs once per process, not once per store.
 const macKeyMemo = new Map();
-function refreshMacKey(masterKey) {
+/** The store's own MAC key for `masterKey`, memoized. Exported so a caller
+ * that never touches a RefreshStore (the AS computing a request's
+ * clientFingerprint) can key it the same way the store does. */
+export function refreshMacKey(masterKey) {
     const hit = macKeyMemo.get(masterKey);
     if (hit)
         return hit;
@@ -240,7 +246,7 @@ function parseR1(t, key) {
     if (!timingSafeEqual(buf.subarray(R1_BODY), r1Mac(key, buf.subarray(0, R1_BODY))))
         return null;
     const fidBytes = buf.subarray(0, 16);
-    return { fidBytes, fid: fidBytes.toString('base64url'), gen: buf.readUInt32BE(16), digest: sha256(buf) };
+    return { fidBytes, fid: fidBytes.toString('base64url'), gen: buf.readUInt32BE(16), digest: sha256(buf), body: buf.subarray(0, R1_BODY) };
 }
 function mintR1(key, fid, gen) {
     const body = Buffer.alloc(R1_BODY);
@@ -250,6 +256,24 @@ function mintR1(key, fid, gen) {
     const buf = Buffer.concat([body, r1Mac(key, body)]);
     return { token: R1_PREFIX + buf.toString('base64url'), cur: sha256(buf).toString('base64url') };
 }
+/**
+ * The token a rotation of `presentedBody` (a parsed token's fid||gen||rand)
+ * mints: generation + 1, and a random part derived (not drawn) from the
+ * presented body, so re-deriving it from a retired token and comparing the
+ * digest against a family's stored `cur` tells a concurrent duplicate from a
+ * different gen-1 token. Domain-separated from `r1Mac` so neither function's
+ * output can be read as the other's. See docs/internals.md.
+ */
+function mintR1Successor(key, presentedBody) {
+    const rand = createHmac('sha256', key).update(R1_SUCCESSOR_DOMAIN).update(presentedBody).digest().subarray(0, 16);
+    const body = Buffer.alloc(R1_BODY);
+    presentedBody.copy(body, 0, 0, 16); // fid
+    body.writeUInt32BE(presentedBody.readUInt32BE(16) + 1, 16); // gen + 1
+    rand.copy(body, 20);
+    const buf = Buffer.concat([body, r1Mac(key, body)]);
+    const digest = sha256(buf);
+    return { token: R1_PREFIX + buf.toString('base64url'), cur: digest.toString('base64url'), digest };
+}
 /**
  * The family tag of a refresh token this `masterKey`'s store minted, or null
  * for anything else. Derives the key once; the returned function does no I/O,
@@ -262,6 +286,24 @@ export function refreshFamilyTagger(masterKey) {
         return p ? familyTag(p.fidBytes) : null;
     };
 }
+/**
+ * A correlation tag for the client presenting a refresh token:
+ * HMAC-SHA256(key, client_id + "\n" + user-agent + "\n" + address), truncated
+ * to 16 bytes and base64url-encoded. `key` is the store's own MAC key
+ * (refreshMacKey), so computing it needs MASTER_KEY: a reader of the store
+ * file alone (`by` is stored, not these inputs) cannot brute-force the
+ * client_id/user-agent/address that produced it. It is still not a secret:
+ * anyone who can see a live request can send the same inputs and get the
+ * same tag. Pure, no I/O.
+ */
+export function clientFingerprint(clientId, userAgent, address, key) {
+    return createHmac('sha256', key).update(R1_FINGERPRINT_DOMAIN).update(`${clientId}\n${userAgent}\n${address}`).digest().subarray(0, 16).toString('base64url');
+}
+function timingSafeStringEqual(a, b) {
+    const ab = Buffer.from(a, 'utf-8');
+    const bb = Buffer.from(b, 'utf-8');
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
 function ownEntries(o) {
     // An own `__proto__` key (JSON.parse makes one) would set the prototype when copied.
     return o !== null && typeof o === 'object' && !Array.isArray(o) ? Object.entries(o).filter(([k]) => k !== '__proto__') : [];
@@ -284,7 +326,8 @@ function isFamilyRecord(key, r) {
         Number.isInteger(x.gen) && x.gen >= 0 && x.gen <= GEN_MAX &&
         typeof x.cur === 'string' && x.cur.length === 43 && isCanonicalB64(x.cur, 32) &&
         Number.isFinite(x.createdAt) && Number.isFinite(x.usedAt) &&
-        (x.legacy === undefined || typeof x.legacy === 'string'));
+        (x.legacy === undefined || typeof x.legacy === 'string') &&
+        (x.by === undefined || typeof x.by === 'string'));
 }
 function formatError(file, format) {
     const name = basename(file);
@@ -304,16 +347,19 @@ 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 ?? {});
     let dropped = 0;
     for (const [k, f] of ownEntries(x.families)) {
         if (isFamilyRecord(k, f)) {
-            data.families[k] = { sub: f.sub, gen: f.gen, cur: f.cur, createdAt: f.createdAt, usedAt: f.usedAt, ...(f.legacy === undefined ? {} : { legacy: f.legacy }) };
+            data.families[k] = {
+                sub: f.sub, gen: f.gen, cur: f.cur, createdAt: f.createdAt, usedAt: f.usedAt,
+                ...(f.legacy === undefined ? {} : { legacy: f.legacy }),
+                ...(f.by === undefined ? {} : { by: f.by }),
+            };
         }
         else
             dropped += 1;
@@ -378,10 +424,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 +550,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)) {
@@ -556,7 +594,7 @@ export class RefreshStore {
         while (Object.hasOwn(data.families, fid.toString('base64url')));
         return fid;
     }
-    issue(nowMs, sub) {
+    issue(nowMs, sub, fingerprint) {
         if (typeof sub !== 'string' || sub === '')
             throw new Error('RefreshStore.issue: sub must be a non-empty string');
         const key = this.key();
@@ -566,7 +604,7 @@ export class RefreshStore {
             const fid = this.newFamilyId(data);
             const fidKey = fid.toString('base64url');
             const { token, cur } = mintR1(key, fid, 0);
-            data.families[fidKey] = { sub, gen: 0, cur, createdAt: nowMs, usedAt: nowMs };
+            data.families[fidKey] = { sub, gen: 0, cur, createdAt: nowMs, usedAt: nowMs, ...(fingerprint === undefined ? {} : { by: fingerprint }) };
             if (this.maxFamiliesPerSub !== undefined)
                 this.enforceFamilyCap(data, sub, this.maxFamiliesPerSub, lines, fidKey);
             this.save(data);
@@ -574,6 +612,25 @@ export class RefreshStore {
             return token;
         });
     }
+    /** A presented token exactly one generation behind `f`, inside the replay
+     * window, from the fingerprint that retired it, whose derived successor
+     * matches `f.cur`: a concurrent duplicate request rather than theft (see
+     * docs/internals.md). Null for anything else at that generation, including
+     * a different rand (a genuinely different gen-1 token) or no fingerprint. */
+    concurrentDuplicate(r1, f, nowMs, fingerprint, key) {
+        if (fingerprint === undefined || f.by === undefined)
+            return null;
+        if (r1.gen !== f.gen - 1)
+            return null;
+        if (nowMs < f.usedAt || nowMs - f.usedAt > REPLAY_WINDOW_MS)
+            return null;
+        if (!timingSafeStringEqual(fingerprint, f.by))
+            return null;
+        const succ = mintR1Successor(key, r1.body);
+        if (!timingSafeEqual(succ.digest, Buffer.from(f.cur, 'base64url')))
+            return null;
+        return { token: succ.token };
+    }
     /** Rotate a presented refresh token; null if it is unknown, malformed, or
      * rotated away (reuse => the family is revoked). The record's sub is copied
      * forward and returned so the caller can mint the matching access token
@@ -582,8 +639,17 @@ export class RefreshStore {
      * `accept` (optional) is called inside the store lock, before any mutation,
      * with the record's sub. false: every session of that sub is dropped and
      * null returned. A throw: nothing is written and the error propagates, so
-     * the presented token stays valid. Absent: unchanged. */
-    rotate(oldToken, nowMs, accept) {
+     * the presented token stays valid. Absent: unchanged.
+     *
+     * `fingerprint` (optional) names the presenting client (clientFingerprint).
+     * Absent: a rotated-away token is always reuse, as before. Present: a
+     * token exactly one generation behind, from the same fingerprint, presented
+     * no earlier than and at most REPLAY_WINDOW_MS after the rotation that
+     * retired it, is a concurrent duplicate: it gets back the SAME successor
+     * token, with no change to the family (not even `usedAt`). Anything else
+     * rotated-away is still reuse, including a clock that has stepped back
+     * past `usedAt`, which cannot be told apart from a genuinely stale replay. */
+    rotate(oldToken, nowMs, accept, fingerprint) {
         const key = this.key();
         const r1 = parseR1(oldToken, key);
         if (!r1 && !(typeof oldToken === 'string' && LEGACY_TOKEN.test(oldToken) && !this.legacyEmpty))
@@ -611,9 +677,16 @@ export class RefreshStore {
                     lines.push(`refresh family ${why === 'reuse' ? 'revoked' : 'dropped'}: ${why} tag=${familyTag(r1.fidBytes)}`);
                     return done(null, true);
                 };
-                // Older: a rotated-away token, and the MAC proves this server minted it.
-                if (r1.gen < f.gen)
-                    return drop('reuse');
+                // Older: a rotated-away token verified by MAC as server-minted, unless a concurrent duplicate.
+                if (r1.gen < f.gen) {
+                    const duplicate = this.concurrentDuplicate(r1, f, nowMs, fingerprint, key);
+                    if (!duplicate)
+                        return drop('reuse');
+                    if (accept && !accept(f.sub))
+                        return refuse(f.sub);
+                    lines.push(`refresh family replayed tag=${familyTag(r1.fidBytes)}`);
+                    return done({ token: duplicate.token, sub: f.sub }, dirty);
+                }
                 // Newer, or the same generation with another random part: the store
                 // lost a write the client saw. Not evidence of theft.
                 if (r1.gen > f.gen)
@@ -624,11 +697,15 @@ export class RefreshStore {
                     return refuse(f.sub);
                 if (f.gen === GEN_MAX)
                     return drop('overflow');
-                const next = mintR1(key, r1.fidBytes, f.gen + 1);
+                const next = mintR1Successor(key, r1.body);
                 f.gen += 1;
                 f.cur = next.cur;
                 // now() is read before the lock wait, so a later writer can hold an earlier time.
                 f.usedAt = Math.max(f.usedAt, nowMs);
+                if (fingerprint === undefined)
+                    delete f.by;
+                else
+                    f.by = fingerprint;
                 return done({ token: next.token, sub: f.sub }, true);
             }
             const rec = Object.hasOwn(data.active, oldToken) ? data.active[oldToken] : undefined;

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;
@@ -91,6 +91,11 @@ export interface AuthServerDeps {
     }>;
     replayGuard?: ReplayGuard;
     refreshStore?: RefreshStore;
+    /** The presenting client's address, for the refresh-rotation fingerprint
+     * (clientFingerprint) that tells a concurrent duplicate request from a
+     * different holder of the same token. Default: the socket's remote
+     * address. A host behind a trusted proxy wires its own resolver here. */
+    clientAddress?: (req: IncomingMessage) => string | undefined;
     now?: () => number;
     /** Server-side log (never sent to callers) for auth failures / SSRF blocks. */
     log?: (line: string) => void;
@@ -146,7 +151,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;