mcp-google-multi 6.0.0-alpha.63 → 6.0.0-alpha.64

package/dist/mcp-token.d.ts

@@ -80,40 +80,78 @@ export declare class ReplayGuard {
     get size(): number;
     private evictExpired;
 }
+/** An earlier release's record, keyed by its live token. */
 export interface RefreshRecord {
     sub: string;
     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).
+ * 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;
+/** 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
+ * (E_REFRESH_STORE_FORMAT). */
+export declare function assertRefreshStoreReadable(file: string, masterKey: string): void;
+export interface RefreshStoreOptions {
+    /** Absolute family lifetime in seconds, counted from the sign-in. Unset: unlimited. */
+    maxAgeSec?: number;
+    /** Idle lifetime in seconds, counted from the last issue or rotation. Unset: unlimited. */
+    idleSec?: number;
+    /** Server-side log for a revoked, dropped or expired family. Never given a token or a subject. */
+    log?: (line: string) => void;
+}
+/**
+ * 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
+ * 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.
  */
 export declare class RefreshStore {
     private readonly path;
     private readonly masterKey;
-    constructor(path: string, masterKey: string);
+    private readonly log;
+    private readonly maxAgeMs;
+    private readonly idleMs;
+    private macKey;
+    private legacyEmpty;
+    constructor(path: string, masterKey: string, options?: RefreshStoreOptions);
+    private get timed();
+    private live;
+    /** Drop expired sessions in both formats; the count of those dropped. */
+    private prune;
+    /** A session written while the clock ran ahead would otherwise outlive its
+     * limit by the size of the jump. */
+    private clamp;
+    private key;
+    /** With `nowMs` (every issue and rotation), also clamps and prunes. */
     private load;
     private save;
-    issue(nowMs: number, sub: string, 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). The
-     * record's sub is copied forward and returned so the caller can mint the
-     * matching access token without trusting anything client-supplied.
+    private emit;
+    private newFamilyId;
+    issue(nowMs: number, sub: string): string;
+    /** 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
+     * without trusting anything client-supplied.
      *
      * `accept` (optional) is called inside the store lock, before any mutation,
-     * with the record's sub. false: every active record of that sub is dropped
-     * and null returned. A throw: nothing is mutated and the error propagates,
-     * so the presented token stays valid. Absent: unchanged. */
+     * 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): {
         token: string;
         sub: string;
     } | null;
-    /** Drop every ACTIVE record minted under `sub` (linear scan under the store
-     * lock); the save then drops the spent entries of every family left with no
-     * active token. Returns the number of active tokens dropped. */
+    /** Drop every session minted under `sub`, in both formats (linear scan under
+     * the store lock); the save then drops the earlier-release spent entries of
+     * the families that died with them. Returns the number of sessions dropped. */
     purgeTenant(sub: string): number;
 }

package/dist/mcp-token.js

@@ -1,10 +1,11 @@
 // 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
+// the rotated refresh-token store. Keyed by the provisioned MCP_JWT_KEY
 // (B5), so tokens survive a restart as long as the key persists.
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, hkdfSync, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { SignJWT, jwtVerify } from 'jose';
 import { deriveKey, encryptToken, decryptToken } from './token-store.js';
 import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
@@ -132,7 +133,80 @@ export class ReplayGuard {
         }
     }
 }
-const SPENT_CAP = 2000;
+/** 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.
+const R1_PREFIX = 'r1.';
+const R1_LENGTH = 94;
+const R1_BODY = 36;
+const R1_BYTES = 68;
+const R1_MAC_DOMAIN = Buffer.from('mcp-google-multi refresh r1\n');
+const R1_KEY_INFO = 'mcp-google-multi:refresh-mac:v1';
+// Every r1 token carries a MAC under a key from MASTER_KEY, so a passphrase
+// key (deriveKey's bare-sha256 branch) would let one leaked token test
+// guesses offline at hash speed. scrypt gives that branch a work factor.
+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;
+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) {
+    const hit = macKeyMemo.get(masterKey);
+    if (hit)
+        return hit;
+    const raw = deriveKey(masterKey);
+    const ikm = Buffer.from(masterKey, 'base64').length === 32 ? raw : scryptSync(masterKey, R1_SCRYPT_SALT, 32, R1_SCRYPT);
+    const key = Buffer.from(hkdfSync('sha256', ikm, Buffer.alloc(0), R1_KEY_INFO, 32));
+    macKeyMemo.set(masterKey, key);
+    return key;
+}
+function r1Mac(key, body) {
+    return createHmac('sha256', key).update(R1_MAC_DOMAIN).update(body).digest();
+}
+/** A token this key minted, or null. Pure CPU: runs before the file lock. */
+function parseR1(t, key) {
+    if (typeof t !== 'string' || t.length !== R1_LENGTH || !t.startsWith(R1_PREFIX))
+        return null;
+    const text = t.slice(R1_PREFIX.length);
+    const buf = Buffer.from(text, 'base64url');
+    // The decoder skips stray characters and ignores the last one's pad bits;
+    // re-encoding leaves one spelling per token.
+    if (buf.length !== R1_BYTES || buf.toString('base64url') !== text)
+        return null;
+    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) };
+}
+function mintR1(key, fid, gen) {
+    const body = Buffer.alloc(R1_BODY);
+    fid.copy(body, 0);
+    body.writeUInt32BE(gen, 16);
+    randomBytes(16).copy(body, 20);
+    const buf = Buffer.concat([body, r1Mac(key, body)]);
+    return { token: R1_PREFIX + buf.toString('base64url'), cur: sha256(buf).toString('base64url') };
+}
+/**
+ * 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 function refreshFamilyTagger(masterKey) {
+    const key = refreshMacKey(masterKey);
+    return (token) => {
+        const p = parseR1(token, key);
+        return p ? familyTag(p.fidBytes) : null;
+    };
+}
 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__') : [];
@@ -143,143 +217,349 @@ function isLegacyRecord(r) {
     const x = r;
     return typeof x.sub === 'string' && x.sub !== '' && typeof x.family === 'string' && typeof x.issuedAt === 'number' && Number.isFinite(x.issuedAt);
 }
+function isCanonicalB64(s, bytes) {
+    return B64URL.test(s) && Buffer.from(s, 'base64url').length === bytes && Buffer.from(s, 'base64url').toString('base64url') === s;
+}
+function isFamilyRecord(key, r) {
+    if (r === null || typeof r !== 'object')
+        return false;
+    const x = r;
+    return (isCanonicalB64(key, 16) &&
+        typeof x.sub === 'string' && x.sub !== '' &&
+        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'));
+}
+function formatError(file, format) {
+    const name = basename(file);
+    return new Error(`E_REFRESH_STORE_FORMAT: ${name} was written by a newer release (format ${JSON.stringify(format)}): upgrade, or delete ${name} to sign every MCP client out`);
+}
+/** The decrypted plaintext, or null when the file is absent. Throws when it
+ * does not decrypt; the caller decides what that means. */
+function readPlain(file, masterKey) {
+    if (!existsSync(file))
+        return null;
+    return decryptToken(readFileSync(file, 'utf-8'), masterKey);
+}
+// Outside any decrypt catch: a file from a newer release loaded as empty
+// would be erased by the next write.
+function checkFormat(file, d) {
+    if (d !== null && typeof d === 'object' && Object.hasOwn(d, 'format') && d.format !== REFRESH_FORMAT) {
+        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. */
+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 }) };
+        }
+        else
+            dropped += 1;
+    }
+    for (const [t, r] of ownEntries(x.active)) {
+        if (isLegacyRecord(r))
+            data.active[t] = { sub: r.sub, issuedAt: r.issuedAt, family: r.family };
+        else
+            dropped += 1;
+    }
+    for (const [t, fam] of ownEntries(x.spent)) {
+        if (typeof fam === 'string')
+            data.spent[t] = fam;
+        else
+            dropped += 1;
+    }
+    return { data, dirty: dropped > 0 };
+}
+/** Every session of `sub`, in both formats. */
+function dropSub(data, sub) {
+    let n = 0;
+    for (const [k, f] of Object.entries(data.families)) {
+        if (f.sub === sub) {
+            delete data.families[k];
+            n += 1;
+        }
+    }
+    for (const [t, r] of Object.entries(data.active)) {
+        if (r.sub === sub) {
+            delete data.active[t];
+            n += 1;
+        }
+    }
+    return n;
+}
+/** 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
+ * (E_REFRESH_STORE_FORMAT). */
+export function assertRefreshStoreReadable(file, masterKey) {
+    let d;
+    try {
+        d = readPlain(file, masterKey);
+    }
+    catch (e) {
+        throw new Error(`E_REFRESH_STORE_UNREADABLE: ${basename(file)} does not decrypt with this MASTER_KEY`, { cause: e });
+    }
+    checkFormat(file, d);
+}
+function lifetimeMs(name, v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'number' || !Number.isSafeInteger(v) || v <= 0)
+        throw new Error(`E_REFRESH_OPTION_INVALID: ${name} must be a positive whole number`);
+    return v * 1000;
+}
 /**
- * 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).
+ * 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
+ * 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.
  */
 export class RefreshStore {
     path;
     masterKey;
-    constructor(path, masterKey) {
+    log;
+    maxAgeMs;
+    idleMs;
+    macKey;
+    // Set once a load finds no earlier-release record. Nothing here adds one,
+    // so from then on a legacy-shaped token is refused before the lock.
+    legacyEmpty = false;
+    constructor(path, masterKey, options = {}) {
         this.path = path;
         this.masterKey = masterKey;
+        this.maxAgeMs = lifetimeMs('maxAgeSec', options.maxAgeSec);
+        this.idleMs = lifetimeMs('idleSec', options.idleSec);
+        this.log = options.log ?? (() => undefined);
+    }
+    get timed() {
+        return this.maxAgeMs !== undefined || this.idleMs !== undefined;
+    }
+    // Positive form: a non-finite time can only make a session dead.
+    live(createdAt, usedAt, nowMs) {
+        return (this.maxAgeMs === undefined || nowMs < createdAt + this.maxAgeMs) && (this.idleMs === undefined || nowMs < usedAt + this.idleMs);
+    }
+    /** Drop expired sessions in both formats; the count of those dropped. */
+    prune(data, nowMs, lines) {
+        if (!this.timed)
+            return 0;
+        let n = 0;
+        for (const [k, f] of Object.entries(data.families)) {
+            if (!this.live(f.createdAt, f.usedAt, nowMs)) {
+                delete data.families[k];
+                n += 1;
+            }
+        }
+        for (const [t, r] of Object.entries(data.active)) {
+            if (!this.live(r.issuedAt, r.issuedAt, nowMs)) {
+                delete data.active[t];
+                n += 1;
+            }
+        }
+        if (n > 0) {
+            lines.push(`refresh families expired n=${n}`);
+            if (Object.keys(data.families).length === 0 && Object.keys(data.active).length === 0)
+                lines.push('refresh store: every session expired at once (check the host clock)');
+        }
+        return n;
+    }
+    /** A session written while the clock ran ahead would otherwise outlive its
+     * limit by the size of the jump. */
+    clamp(data, nowMs, lines) {
+        if (!this.timed)
+            return false;
+        const limit = nowMs + CLOCK_SKEW_MS;
+        let n = 0;
+        const pull = (t) => {
+            if (t <= limit)
+                return t;
+            n += 1;
+            return nowMs;
+        };
+        for (const f of Object.values(data.families)) {
+            f.createdAt = pull(f.createdAt);
+            f.usedAt = pull(f.usedAt);
+        }
+        for (const r of Object.values(data.active))
+            r.issuedAt = pull(r.issuedAt);
+        if (n > 0)
+            lines.push(`refresh store clock: n=${n} timestamps ahead of the clock were clamped`);
+        return n > 0;
+    }
+    key() {
+        return (this.macKey ??= refreshMacKey(this.masterKey));
     }
-    load() {
-        const data = { active: {}, spent: {} };
-        if (!existsSync(this.path))
-            return data;
+    /** With `nowMs` (every issue and rotation), also clamps and prunes. */
+    load(nowMs, lines = []) {
         let d;
+        let readOk = true;
         try {
-            d = decryptToken(readFileSync(this.path, 'utf-8'), this.masterKey);
+            d = readPlain(this.path, this.masterKey);
         }
         catch {
-            return data;
+            d = null;
+            readOk = false;
         }
-        // Only well-formed own entries survive, so no lookup can land on an
-        // inherited key or a record without a subject.
-        for (const [t, r] of ownEntries(d?.active)) {
-            if (isLegacyRecord(r))
-                data.active[t] = { sub: r.sub, issuedAt: r.issuedAt, family: r.family };
+        checkFormat(this.path, d);
+        const loaded = decodeData(d);
+        if (nowMs !== undefined) {
+            if (this.clamp(loaded.data, nowMs, lines))
+                loaded.dirty = true;
+            if (this.prune(loaded.data, nowMs, lines) > 0)
+                loaded.dirty = true;
         }
-        for (const [t, fam] of ownEntries(d?.spent))
-            if (typeof fam === 'string')
-                data.spent[t] = fam;
-        return data;
+        // A failed read is not evidence that the file holds no legacy record.
+        if (readOk && Object.keys(loaded.data.active).length === 0 && Object.keys(loaded.data.spent).length === 0)
+            this.legacyEmpty = true;
+        return loaded;
     }
     save(data) {
-        // A family with no active token has nothing left to revoke. Over the cap,
-        // the subject holding the most spent tokens loses its oldest (ties: the
-        // oldest entry), so a subject's rotations, across all its families, only
-        // push out its own history (docs/internals.md). Insertion order = rotation
-        // order.
-        const owner = new Map();
+        // Earlier-release evidence matters only while its family lives on, as a
+        // legacy record or as the family it migrated into.
+        const live = new Set();
         for (const r of Object.values(data.active))
-            owner.set(r.family, r.sub);
-        const order = Object.keys(data.spent);
-        const held = new Map();
-        let total = 0;
-        order.forEach((t, i) => {
-            const sub = owner.get(data.spent[t]);
-            if (sub === undefined) {
+            live.add(r.family);
+        for (const f of Object.values(data.families))
+            if (f.legacy !== undefined)
+                live.add(f.legacy);
+        for (const [t, fam] of Object.entries(data.spent))
+            if (!live.has(fam))
                 delete data.spent[t];
-                return;
+        atomicWriteFileSync(this.path, encryptToken({ format: REFRESH_FORMAT, families: data.families, active: data.active, spent: data.spent }, this.masterKey), 0o600);
+    }
+    // After the write, so a failed save or a throwing accept logs nothing.
+    emit(lines) {
+        for (const line of lines) {
+            try {
+                this.log(line);
             }
-            const h = held.get(sub);
-            if (h)
-                h.at.push(i);
-            else
-                held.set(sub, { at: [i], head: 0 });
-            total += 1;
-        });
-        while (total > SPENT_CAP) {
-            let most = { at: [], head: 0 };
-            let mostN = 0;
-            for (const h of held.values()) {
-                const n = h.at.length - h.head;
-                if (n > mostN || (n === mostN && n > 0 && h.at[h.head] < most.at[most.head])) {
-                    most = h;
-                    mostN = n;
-                }
+            catch {
+                // The rotation is already on disk; a log sink must not lose its token.
             }
-            delete data.spent[order[most.at[most.head++]]];
-            total -= 1;
         }
-        atomicWriteFileSync(this.path, encryptToken(data, this.masterKey), 0o600);
     }
-    issue(nowMs, sub, family) {
+    newFamilyId(data) {
+        let fid;
+        do
+            fid = randomBytes(16);
+        while (Object.hasOwn(data.families, fid.toString('base64url')));
+        return fid;
+    }
+    issue(nowMs, sub) {
+        if (typeof sub !== 'string' || sub === '')
+            throw new Error('RefreshStore.issue: sub must be a non-empty string');
+        const key = this.key();
         return withFileLock(this.path, () => {
-            const token = randomBytes(32).toString('base64url');
-            const data = this.load();
-            data.active[token] = { sub, issuedAt: nowMs, family: family ?? randomBytes(12).toString('hex') };
+            const lines = [];
+            const { data } = this.load(nowMs, lines);
+            const fid = this.newFamilyId(data);
+            const { token, cur } = mintR1(key, fid, 0);
+            data.families[fid.toString('base64url')] = { sub, gen: 0, cur, createdAt: nowMs, usedAt: nowMs };
             this.save(data);
+            this.emit(lines);
             return token;
         });
     }
-    /** Rotate a presented refresh token; null if unknown OR if the presented
-     * token was already 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 without trusting anything client-supplied.
+    /** 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
+     * without trusting anything client-supplied.
      *
      * `accept` (optional) is called inside the store lock, before any mutation,
-     * with the record's sub. false: every active record of that sub is dropped
-     * and null returned. A throw: nothing is mutated and the error propagates,
-     * so the presented token stays valid. Absent: unchanged. */
+     * 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) {
+        const key = this.key();
+        const r1 = parseR1(oldToken, key);
+        if (!r1 && !(typeof oldToken === 'string' && LEGACY_TOKEN.test(oldToken) && !this.legacyEmpty))
+            return null;
         return withFileLock(this.path, () => {
-            const data = this.load();
+            const lines = [];
+            // Expiry runs first: a dead session is refused without consulting accept.
+            const { data, dirty } = this.load(nowMs, lines);
+            const done = (result, write) => {
+                if (write)
+                    this.save(data);
+                this.emit(lines);
+                return result;
+            };
+            const refuse = (sub) => {
+                lines.push(`refresh sessions dropped: accept n=${dropSub(data, sub)}`);
+                return done(null, true);
+            };
+            if (r1) {
+                const f = Object.hasOwn(data.families, r1.fid) ? data.families[r1.fid] : undefined;
+                if (!f)
+                    return done(null, dirty);
+                const drop = (why) => {
+                    delete data.families[r1.fid];
+                    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');
+                // 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)
+                    return drop('ahead');
+                if (!timingSafeEqual(r1.digest, Buffer.from(f.cur, 'base64url')))
+                    return drop('mismatch');
+                if (accept && !accept(f.sub))
+                    return refuse(f.sub);
+                if (f.gen === GEN_MAX)
+                    return drop('overflow');
+                const next = mintR1(key, r1.fidBytes, f.gen + 1);
+                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);
+                return done({ token: next.token, sub: f.sub }, true);
+            }
             const rec = Object.hasOwn(data.active, oldToken) ? data.active[oldToken] : undefined;
             if (!rec) {
-                // Reuse of a rotated-away token signals theft: revoke the whole family.
                 const fam = Object.hasOwn(data.spent, oldToken) ? data.spent[oldToken] : undefined;
-                if (fam) {
-                    for (const [t, r] of Object.entries(data.active))
-                        if (r.family === fam)
-                            delete data.active[t];
-                    this.save(data);
-                }
-                return null;
-            }
-            if (accept && !accept(rec.sub)) {
+                if (fam === undefined)
+                    return done(null, dirty);
+                // Reuse of an earlier-release rotated-away token: revoke the family in
+                // both formats.
                 for (const [t, r] of Object.entries(data.active))
-                    if (r.sub === rec.sub)
+                    if (r.family === fam)
                         delete data.active[t];
-                this.save(data);
-                return null;
+                for (const [k, f] of Object.entries(data.families))
+                    if (f.legacy === fam)
+                        delete data.families[k];
+                lines.push(`refresh family revoked: reuse tag=${familyTag(fam)}`);
+                return done(null, true);
             }
+            if (accept && !accept(rec.sub))
+                return refuse(rec.sub);
+            // Migrate: the presented token stays behind as reuse evidence.
             delete data.active[oldToken];
             data.spent[oldToken] = rec.family;
-            const next = randomBytes(32).toString('base64url');
-            data.active[next] = { sub: rec.sub, issuedAt: nowMs, family: rec.family };
-            this.save(data);
-            return { token: next, sub: rec.sub };
+            const fid = this.newFamilyId(data);
+            const next = mintR1(key, fid, 0);
+            data.families[fid.toString('base64url')] = { sub: rec.sub, gen: 0, cur: next.cur, createdAt: rec.issuedAt, usedAt: Math.max(rec.issuedAt, nowMs), legacy: rec.family };
+            return done({ token: next.token, sub: rec.sub }, true);
         });
     }
-    /** Drop every ACTIVE record minted under `sub` (linear scan under the store
-     * lock); the save then drops the spent entries of every family left with no
-     * active token. Returns the number of active tokens dropped. */
+    /** Drop every session minted under `sub`, in both formats (linear scan under
+     * the store lock); the save then drops the earlier-release spent entries of
+     * the families that died with them. Returns the number of sessions dropped. */
     purgeTenant(sub) {
         return withFileLock(this.path, () => {
-            const data = this.load();
-            let dropped = 0;
-            for (const [t, r] of Object.entries(data.active)) {
-                if (r.sub === sub) {
-                    delete data.active[t];
-                    dropped += 1;
-                }
-            }
+            const { data } = this.load();
+            const dropped = dropSub(data, sub);
             if (dropped > 0)
                 this.save(data);
             return dropped;

package/dist/oauth-as.d.ts

@@ -20,6 +20,12 @@ export interface AuthServerConfig {
     accessTtlSec?: number;
     masterKey: string;
     refreshStorePath: string;
+    /** `maxAgeSec` of the refresh store buildAuthServer creates: sessions end
+     * this long after their sign-in. Unset: unlimited. */
+    refreshMaxAgeSec?: number;
+    /** `idleSec` of that store: sessions end this long after their last
+     * refresh. Unset: unlimited. */
+    refreshIdleSec?: number;
     /** Default true. The clientless `flow=alias_reauth` link names an alias with
      * no tenant binding, so a multi-tenant deployment sets false: with several
      * tenants an alias name alone is ambiguous and the branch becomes a

package/dist/oauth-as.js

@@ -11,8 +11,8 @@ import { signAccessToken, verifyAccessToken, signState, verifyState, signAuthzCo
 import { fetchCimdDocument, SsrfBlockedError } from './ssrf-guard.js';
 const CLAUDE_AI_FIXED_CALLBACK = 'https://claude.ai/api/mcp/auth_callback';
 // DCR (/register) is public + unauthenticated, so its in-memory store must be
-// bounded like every sibling store (ReplayGuard cap, RefreshStore SPENT_CAP) or
-// a request loop OOMs the process. Cap client count (FIFO-evict the oldest) and
+// bounded like every sibling store (the ReplayGuard cap) or a request loop
+// OOMs the process. Cap client count (FIFO-evict the oldest) and
 // the per-request redirect_uris shape so one entry can't be arbitrarily large.
 export const DCR_MAX_CLIENTS = 1000;
 export const DCR_MAX_REDIRECT_URIS = 10;
@@ -180,10 +180,14 @@ export function buildAuthServer(config, deps = {}) {
     const accessTtl = config.accessTtlSec ?? ACCESS_TTL_DEFAULT;
     const cimd = deps.fetchCimd ?? ((clientId) => fetchCimdDocument(clientId));
     const replay = deps.replayGuard ?? new ReplayGuard();
-    const refresh = deps.refreshStore ?? new RefreshStore(config.refreshStorePath, config.masterKey);
     const registered = deps.registeredClients ?? new Map();
     const now = deps.now ?? (() => Date.now());
     const log = deps.log ?? (() => undefined);
+    // Silently dropping a lifetime the caller asked for would leave sessions unlimited.
+    if (deps.refreshStore && (config.refreshMaxAgeSec !== undefined || config.refreshIdleSec !== undefined)) {
+        throw new Error('E_REFRESH_OPTION_CONFLICT: refreshMaxAgeSec and refreshIdleSec configure the refresh store buildAuthServer creates; set them on the injected refreshStore instead');
+    }
+    const refresh = deps.refreshStore ?? new RefreshStore(config.refreshStorePath, config.masterKey, { maxAgeSec: config.refreshMaxAgeSec, idleSec: config.refreshIdleSec, log });
     const nowSec = () => Math.floor(now() / 1000);
     const resolveSubject = deps.resolveSubject ?? ((email) => (config.ownerEmails.includes(email) ? { sub: 'owner' } : null));
     const issHeader = { 'Cache-Control': 'no-store' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.63",
+  "version": "6.0.0-alpha.64",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",