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

package/README.md

@@ -4,7 +4,7 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-- 🧰 **Exhaustive** — 940 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 942 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
 - 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
 - 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
 - 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)
@@ -55,6 +55,20 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 **Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Local usage metrics](./docs/usage-metrics.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
+## Agent skill
+
+The repo and the npm package both ship an [Agent Skill](https://code.claude.com/docs/en/skills) at `skills/google-workspace/`: a hand-written `SKILL.md` covering account selection, the discover step, incremental Gmail sweeps, keeping results small, write profiles, and the escape hatch, plus a `reference/` folder with a generated argument table per service. Loading it gets an agent calling this server's tools correctly without guessing argument names.
+
+To install it for Claude Code, copy or symlink the `skills/google-workspace` folder into `~/.claude/skills/` (every project) or a project's own `.claude/skills/` (that project only):
+
+```bash
+# from a cloned copy of this repo
+ln -s "$(pwd)/skills/google-workspace" ~/.claude/skills/google-workspace
+
+# from the installed npm package
+ln -s "$(npm root -g)/mcp-google-multi/skills/google-workspace" ~/.claude/skills/google-workspace
+```
+
 ## Maintainer, sponsor & license
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)

package/dist/discover.js

@@ -96,9 +96,8 @@ export function registerDiscoverTools(registry, policy) {
                             service,
                             operations,
                             writeControl: rendered?.hint ?? describePolicy(policy),
-                            next: operations.length > 0
-                                ? 'Call the chosen tool by name; it is now listed and callable.'
-                                : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,
+                            // catalog() falls back to a full one-line listing when nothing matches, so this is never empty.
+                            next: 'Call the chosen tool by its exact name. A client that loads tools on demand may need its own tool-search or load step before the call succeeds.',
                         }),
                     },
                 ],

package/dist/fs-atomic.js

@@ -10,6 +10,9 @@ const RENAME_RETRY_MS = 20;
 const LOCK_LEASE_MS = 60_000;
 // Breaking a lock takes microseconds, so an older breaker file was left by a crash.
 const BREAKER_STALE_MS = 2_000;
+// The no-hard-link fallback writes the lock in two syscalls (create, then the
+// pid); a reader can catch it empty in between. See docs/internals.md.
+const LOCK_WRITE_GRACE_MS = 2_000;
 const PROCESS_START_MS = performance.timeOrigin;
 const OWNER_NAME = /^(\d+)\.(\d+|host)\.(\d+)\.([0-9a-f]{8}|0)\.[0-9a-f]{12}\.owner$/;
 function startOf(pid) {
@@ -63,11 +66,19 @@ function sameFile(a, b) {
 function isEnoent(error) {
     return error.code === 'ENOENT';
 }
+function bindingRecord(id) {
+    return `${id.dev}:${id.ino}:${id.mtimeNs}`;
+}
+function matchesBinding(content, id) {
+    const m = /^(\d+):(\d+):(\d+)$/.exec(content);
+    return m !== null && BigInt(m[1]) === id.dev && BigInt(m[2]) === id.ino && BigInt(m[3]) === id.mtimeNs;
+}
 // Undefined when the lock changed hands while it was being read.
 function readHolder(lock) {
     const before = fs.lstatSync(lock, { bigint: true });
     const body = before.isFile() ? fs.readFileSync(lock, 'utf8') : '';
     let owner;
+    let ownerPending = false;
     if (before.isFile()) {
         const dir = path.dirname(lock);
         const prefix = `${path.basename(lock)}.`;
@@ -79,10 +90,12 @@ function readHolder(lock) {
                 continue;
             const ownerPath = path.join(dir, name);
             try {
-                if (sameFile(fs.lstatSync(ownerPath, { bigint: true }), before)) {
+                const ownerStat = fs.lstatSync(ownerPath, { bigint: true });
+                if (sameFile(ownerStat, before) || matchesBinding(fs.readFileSync(ownerPath, 'utf8'), before)) {
                     owner = { path: ownerPath, ns: m[2], start: m[3], boot: m[4] };
                     break;
                 }
+                ownerPending = true;
             }
             catch (error) {
                 if (!isEnoent(error))
@@ -93,7 +106,7 @@ function readHolder(lock) {
     const after = fs.lstatSync(lock, { bigint: true });
     if (!sameFile(before, after))
         return undefined;
-    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner };
+    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner, ownerPending };
 }
 // The owner file's random name tells two holders apart even when the second
 // lock reuses the first one's freed inode.
@@ -115,10 +128,21 @@ function probeDead(pid) {
         return false;
     }
 }
+// Symmetric: a clock step back must not make a write-in-progress lock look
+// permanently fresh (see docs/internals.md).
+function withinWriteGrace(now, mtimeMs) {
+    return Math.abs(now - mtimeMs) < LOCK_WRITE_GRACE_MS;
+}
 function holderDead(holder, now) {
+    if (holder.body === '' && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const pid = Number(holder.body);
     if (!(Number.isSafeInteger(pid) && pid > 0))
         return true;
+    // A same-pid owner file exists but is not yet bound (the fallback lock's two
+    // writes race a reader); give it the same grace as an empty lock.
+    if (!holder.owner && holder.ownerPending && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const leaseOver = now - holder.mtimeMs >= LOCK_LEASE_MS;
     const owner = holder.owner;
     // No owner file: an older writer, whose namespace is unknown.
@@ -196,6 +220,53 @@ function releaseBreaker(breaker, token) {
             throw error;
     }
 }
+// No hard links here (Android/Termux denies link() in private storage, some
+// filesystems lack it entirely): the lock is created directly with O_EXCL,
+// carrying the bare pid a linked owner file would carry, and the owner file
+// is bound to it by a recorded identity instead of a hard link. See docs/internals.md.
+function takeFallbackLock(lock, ownerFile) {
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    let acquired;
+    try {
+        fs.writeSync(fd, String(process.pid));
+        const stat = fs.fstatSync(fd, { bigint: true });
+        acquired = { dev: stat.dev, ino: stat.ino, mtimeNs: stat.mtimeNs };
+    }
+    catch (error) {
+        // The lock is left empty; remove it only if it is still the one we just
+        // created, then rethrow so the caller never retries a write failure.
+        const stat = fs.fstatSync(fd, { bigint: true });
+        fs.closeSync(fd);
+        try {
+            if (sameFile(fs.lstatSync(lock, { bigint: true }), stat))
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    fs.closeSync(fd);
+    try {
+        fs.writeFileSync(ownerFile, bindingRecord(acquired));
+    }
+    catch (error) {
+        // The lock already exists holding our live pid; without this cleanup
+        // every other writer sees an ownerless holder and waits out the full lease.
+        try {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs)
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return acquired;
+}
 // Hardlink-based advisory lock; the lock body is the bare pid, as older
 // readers expect. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
@@ -206,17 +277,31 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
     let linked = false;
+    let acquired;
     try {
         while (true) {
             try {
                 fs.linkSync(ownerFile, lock);
                 linked = true;
+                acquired = fs.lstatSync(lock, { bigint: true });
                 break;
             }
             catch (error) {
                 const err = error;
-                if (err.code !== 'EEXIST')
+                if (err.code === 'EACCES' || err.code === 'EPERM') {
+                    try {
+                        acquired = takeFallbackLock(lock, ownerFile);
+                        linked = true;
+                        break;
+                    }
+                    catch (fbError) {
+                        if (fbError.code !== 'EEXIST')
+                            throw fbError;
+                    }
+                }
+                else if (err.code !== 'EEXIST') {
                     throw error;
+                }
                 try {
                     const holder = readHolder(lock);
                     if (holder && holderDead(holder, Date.now()) && breakLock(lock, holder))
@@ -238,23 +323,24 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
         if (!linked)
             fs.rmSync(ownerFile, { force: true });
     }
-    let bound = false;
     try {
-        // Some network and FUSE filesystems give each name of one file its own
-        // inode number; there the owner file cannot vouch for the lock.
-        bound = sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true }));
         return fn();
     }
     finally {
-        releaseLock(lock, ownerFile, bound);
+        releaseLock(lock, ownerFile, acquired);
     }
 }
 // A holder whose lock was broken (its owner file removed with it) must not
-// remove its successor's lock.
-function releaseLock(lock, ownerFile, bound) {
+// remove its successor's lock: only drop the lock if it is still the exact
+// file this call created, and our own owner file is still there to vouch for it.
+function releaseLock(lock, ownerFile, acquired) {
     try {
-        if (!bound || sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true })))
-            fs.rmSync(lock, { force: true });
+        if (acquired) {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs && fs.existsSync(ownerFile)) {
+                fs.rmSync(lock, { force: true });
+            }
+        }
     }
     catch (error) {
         if (!isEnoent(error))

package/dist/hint-provider.d.ts

@@ -58,7 +58,10 @@ export type HintCase = {
     entries: string[];
 } | {
     kind: 'no_default_account';
-    aliases: string[];
+    accounts: {
+        alias: string;
+        email: string;
+    }[];
 } | {
     kind: 'no_accounts';
 } | {

package/dist/mcp-token.d.ts

@@ -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
@@ -167,7 +186,13 @@ export declare class RefreshStore {
     private emit;
     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
@@ -176,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

@@ -192,6 +192,12 @@ 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';
 // 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.
@@ -201,13 +207,20 @@ 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;
@@ -233,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);
@@ -243,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,
@@ -255,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__') : [];
@@ -277,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);
@@ -305,7 +355,11 @@ function decodeData(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;
@@ -540,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();
@@ -550,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);
@@ -558,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
@@ -566,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))
@@ -595,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)
@@ -608,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/oauth-as.d.ts

@@ -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;

package/dist/oauth-as.js

@@ -3,7 +3,7 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { isIPv4 } from 'node:net';
 import { decodeJwt } from 'jose';
-import { signAccessToken, verifyAccessToken, signState, verifyState, signAuthzCode, verifyAuthzCode, signReauthLink, verifyReauthLink, signPending, verifyPending, ReplayGuard, RefreshStore, STATE_TTL_DEFAULT, CODE_TTL_DEFAULT, ACCESS_TTL_DEFAULT, } from './mcp-token.js';
+import { signAccessToken, verifyAccessToken, signState, verifyState, signAuthzCode, verifyAuthzCode, signReauthLink, verifyReauthLink, signPending, verifyPending, ReplayGuard, RefreshStore, STATE_TTL_DEFAULT, CODE_TTL_DEFAULT, ACCESS_TTL_DEFAULT, clientFingerprint, refreshMacKey, } from './mcp-token.js';
 import { fetchCimdDocument } from './ssrf-guard.js';
 import { CimdClientCache } from './cimd-cache.js';
 import { logSafe } from './trim.js';
@@ -189,6 +189,14 @@ export function buildAuthServer(config, deps = {}) {
     const registered = deps.registeredClients ?? new Map();
     const now = deps.now ?? (() => Date.now());
     const log = deps.log ?? (() => undefined);
+    const clientAddress = deps.clientAddress ?? ((req) => req.socket.remoteAddress);
+    // Not used for authorization, only to tell a concurrent duplicate /token
+    // request from a different holder of the same refresh token; keyed on the
+    // refresh store's own MAC key so a reader of the store file cannot
+    // brute-force the client_id/user-agent/address that produced a stored `by`.
+    // See docs/internals.md.
+    const fingerprintKey = refreshMacKey(config.masterKey);
+    const fingerprintOf = (req, clientId) => clientFingerprint(clientId, req.headers['user-agent'] ?? '', clientAddress(req) ?? '', fingerprintKey);
     // Silently dropping a lifetime the caller asked for would leave sessions unlimited.
     if (deps.refreshStore && (config.refreshMaxAgeSec !== undefined || config.refreshIdleSec !== undefined || config.refreshMaxFamiliesPerSub !== undefined)) {
         throw new Error('E_REFRESH_OPTION_CONFLICT: refreshMaxAgeSec, refreshIdleSec and refreshMaxFamiliesPerSub configure the refresh store buildAuthServer creates; set them on the injected refreshStore instead');
@@ -417,7 +425,7 @@ export function buildAuthServer(config, deps = {}) {
             res.end(`<!doctype html><meta charset=utf-8><title>Authorize access</title>` +
                 `<body style="font-family:system-ui,sans-serif;max-width:36em;margin:3em auto;line-height:1.5">` +
                 `<h2>Authorize access?</h2>` +
-                `<p>A newly-registered application (<code>${escapeHtml(clientId)}</code>) is requesting access to your Google Workspace through this server.</p>` +
+                `<p>An application (<code>${escapeHtml(clientId)}</code>) asks to connect to this server as you.</p>` +
                 `<p>If approved, it will receive an authorization redirected to:<br><code>${escapeHtml(redirectUri)}</code></p>` +
                 `<p><strong>If you did not start this, close this window.</strong></p>` +
                 `<form method="POST" action="/authorize"><input type="hidden" name="pending" value="${escapeHtml(pendingToken)}">` +
@@ -490,7 +498,7 @@ export function buildAuthServer(config, deps = {}) {
             }
             log(`callback ok flow=alias_add alias=${logSafe(st.alias, 64)}`);
             res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end(`<!doctype html><meta charset=utf-8><p>Connected "${escapeHtml(st.alias)}". You can close this window and retry your request.</p>`);
+            res.end(`<!doctype html><meta charset=utf-8><p>Linked "${escapeHtml(st.alias)}" to this server. Start a new chat to use it.</p>`);
             return true;
         }
         if (st.flow === 'alias_reauth') {
@@ -599,7 +607,7 @@ export function buildAuthServer(config, deps = {}) {
                     return json(res, 400, { error: 'invalid_grant', message: 'the subject is no longer provisioned' });
                 }
             }
-            const refreshToken = refresh.issue(now(), code.sub);
+            const refreshToken = refresh.issue(now(), code.sub, fingerprintOf(req, form.client_id ?? ''));
             log('token issued grant=authorization_code');
             return json(res, 200, { access_token: access, token_type: 'Bearer', expires_in: accessTtl, refresh_token: refreshToken, scope: 'mcp:use' });
         }
@@ -621,7 +629,7 @@ export function buildAuthServer(config, deps = {}) {
                 : undefined;
             let next;
             try {
-                next = refresh.rotate(form.refresh_token ?? '', now(), accept);
+                next = refresh.rotate(form.refresh_token ?? '', now(), accept, fingerprintOf(req, form.client_id ?? ''));
             }
             catch (e) {
                 if (!(e instanceof SubjectCheckUnavailable))

package/dist/registry.d.ts

@@ -38,6 +38,8 @@ export interface CatalogOperation {
      * real scope error rather than a bare "not found". */
     unreachable?: true;
 }
+/** The leading sentence of a (possibly multi-sentence) tool description. */
+export declare function firstSentence(text: string): string;
 /** The service a tool name belongs to: its prefix, unless overridden. */
 export declare function serviceOf(name: string): string;
 export declare function inferCud(name: string): Cud;