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

package/dist/mcp-token.js

@@ -1,17 +1,15 @@
-// B13 token model (oauth-authorization-server.md §Data model): the MCP access
-// token (HS256 JWT, jose-only — AS==RS so no JWKS), the signed self-contained
-// `state` and authorization code, the in-memory single-use replay guard, and
-// the opaque rotated refresh-token store. Keyed by the provisioned MCP_JWT_KEY
-// (B5), so tokens survive a restart as long as the key persists.
-import { randomBytes } from 'node:crypto';
+// 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';
 import { SignJWT, jwtVerify } from 'jose';
 import { deriveKey, encryptToken, decryptToken } from './token-store.js';
 import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 export const ACCESS_TTL_DEFAULT = 600; // seconds
 export const STATE_TTL_DEFAULT = 600;
 export const CODE_TTL_DEFAULT = 60;
-export const REPLAY_CAP_DEFAULT = 10_000;
+export const REPLAY_CAP_DEFAULT = 100_000;
 /** Derive the HS256 secret (32 bytes) from the provisioned MCP_JWT_KEY string. */
 export function jwtSecretFrom(jwtKey) {
     return new Uint8Array(deriveKey(jwtKey));
@@ -20,11 +18,13 @@ function newJti() {
     return randomBytes(16).toString('base64url');
 }
 export async function signAccessToken(p) {
+    if (typeof p.sub !== 'string' || p.sub === '')
+        throw new Error('signAccessToken: sub must be a non-empty string');
     const ttl = p.ttlSec ?? ACCESS_TTL_DEFAULT;
     return new SignJWT({ scope: 'mcp:use', purpose: 'mcp_access' })
         .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
         .setIssuer(p.base)
-        .setSubject('owner')
+        .setSubject(p.sub)
         .setAudience(`${p.base}/mcp`)
         .setIssuedAt(p.iat)
         .setExpirationTime(p.iat + ttl)
@@ -36,7 +36,9 @@ export async function verifyAccessToken(token, base, secret) {
     const { payload } = await jwtVerify(token, secret, { issuer: base, audience: `${base}/mcp` });
     if (payload.purpose !== 'mcp_access')
         throw new Error('wrong token purpose');
-    return { sub: String(payload.sub), scope: String(payload.scope ?? ''), jti: String(payload.jti ?? '') };
+    if (typeof payload.sub !== 'string' || payload.sub === '')
+        throw new Error('access token has no subject');
+    return { sub: payload.sub, scope: String(payload.scope ?? ''), jti: String(payload.jti ?? '') };
 }
 async function signArtifact(claims, purpose, base, secret, iat, ttlSec) {
     return new SignJWT({ ...claims, purpose })
@@ -47,130 +49,609 @@ async function signArtifact(claims, purpose, base, secret, iat, ttlSec) {
         .setJti(newJti())
         .sign(secret);
 }
-async function verifyArtifact(token, purpose, base, secret) {
-    const { payload } = await jwtVerify(token, secret, { issuer: base });
+// `nowSec`: the caller's clock, so expiry is judged by the same clock as the
+// replay guard that records the artifact's spend.
+async function verifyArtifact(token, purpose, base, secret, nowSec) {
+    const { payload } = await jwtVerify(token, secret, { issuer: base, ...(nowSec !== undefined ? { currentDate: new Date(nowSec * 1000) } : {}) });
     if (payload.purpose !== purpose)
         throw new Error(`wrong artifact purpose (${String(payload.purpose)})`);
-    return { ...payload, jti: String(payload.jti ?? '') };
+    return { ...payload, jti: String(payload.jti ?? ''), exp: Number(payload.exp ?? 0) };
 }
 export function signState(payload, base, secret, iat, ttlSec = STATE_TTL_DEFAULT) {
     return signArtifact(payload, 'mcp_state', base, secret, iat, ttlSec);
 }
-export async function verifyState(token, base, secret) {
-    return (await verifyArtifact(token, 'mcp_state', base, secret));
+export async function verifyState(token, base, secret, nowSec) {
+    return (await verifyArtifact(token, 'mcp_state', base, secret, nowSec));
+}
+// --- alias_reauth link -------------------------------------------------------
+/** A re-auth link is handed out in a tool error, so it has to survive until
+ * the user clicks it; an hour, not the 10-minute state TTL. */
+export const REAUTH_LINK_TTL_SEC = 3600;
+function reauthMac(base, secret, alias, exp) {
+    // The newline-separated input can never be a JWT signing input (two
+    // base64url segments and one dot), so the shared key stays unambiguous.
+    return createHmac('sha256', secret).update(`alias_reauth\n${base}\n${alias}\n${exp}`).digest();
+}
+/** Query string of a server-issued alias_reauth link: the alias, an expiry and
+ * an HMAC over both. Synchronous, so the error hints that carry it stay so. */
+export function signReauthLink(base, secret, alias, nowSec) {
+    const exp = nowSec + REAUTH_LINK_TTL_SEC;
+    return `alias=${encodeURIComponent(alias)}&exp=${exp}&sig=${reauthMac(base, secret, alias, exp).toString('base64url')}`;
+}
+/** The alias a link was issued for, or null when it is missing, forged or expired. */
+export function verifyReauthLink(base, secret, params, nowSec) {
+    const exp = Number(params.exp);
+    if (!params.alias || !/^\d+$/.test(params.exp) || exp < nowSec)
+        return null;
+    const want = reauthMac(base, secret, params.alias, exp);
+    const got = Buffer.from(params.sig, 'base64url');
+    return got.length === want.length && timingSafeEqual(got, want) ? params.alias : null;
 }
 /** A pending-authorization artifact for the DCR consent interstitial (same
  * shape as `state`, distinct purpose so the two can't be confused). */
 export function signPending(payload, base, secret, iat, ttlSec = STATE_TTL_DEFAULT) {
     return signArtifact(payload, 'mcp_pending', base, secret, iat, ttlSec);
 }
-export async function verifyPending(token, base, secret) {
-    return (await verifyArtifact(token, 'mcp_pending', base, secret));
+export async function verifyPending(token, base, secret, nowSec) {
+    return (await verifyArtifact(token, 'mcp_pending', base, secret, nowSec));
 }
 export function signAuthzCode(payload, base, secret, iat, ttlSec = CODE_TTL_DEFAULT) {
     return signArtifact(payload, 'mcp_code', base, secret, iat, ttlSec);
 }
-export async function verifyAuthzCode(token, base, secret) {
-    return (await verifyArtifact(token, 'mcp_code', base, secret));
+export async function verifyAuthzCode(token, base, secret, nowSec) {
+    return (await verifyArtifact(token, 'mcp_code', base, secret, nowSec));
 }
-// --- Replay guard (C10/C17: single-use, capped, TTL-evicted) ----------------
+/** A full guard refuses rather than sweeping again sooner than this. */
+const FULL_SWEEP_EVERY_MS = 1000;
 export class ReplayGuard {
     cap;
-    seen = new Map(); // jti -> expiry (ms)
+    seen = new Map();
+    // A lower bound on every entry's expiry: below it nothing can have expired.
+    earliest = Infinity;
+    sweptAt = -Infinity;
     constructor(cap = REPLAY_CAP_DEFAULT) {
         this.cap = cap;
     }
-    /** Record a jti as spent. Returns false if it was already spent (replay). */
-    consume(jti, ttlMs, nowMs) {
-        this.evictExpired(nowMs);
-        if (this.seen.has(jti))
-            return false;
-        if (this.seen.size >= this.cap) {
-            // drop the oldest-inserted entry to bound memory (C17)
-            const oldest = this.seen.keys().next().value;
-            if (oldest !== undefined)
-                this.seen.delete(oldest);
+    /** Hold a slot for an artifact about to be handed out, so its spend can
+     * never meet a full guard. The flood then lands where the artifact is
+     * minted, and refusing there loses nothing. */
+    reserve(jti, ttlMs, nowMs) {
+        if (!this.room(nowMs))
+            return 'full';
+        this.record(jti, nowMs + ttlMs, false);
+        return 'ok';
+    }
+    /** 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. `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) {
+        const exp = Math.max(nowMs + ttlMs, artifactExpMs);
+        const held = this.seen.get(jti);
+        if (held && held.exp > nowMs) {
+            if (held.spent)
+                return 'replay';
+            held.spent = true;
+            held.exp = Math.max(held.exp, exp);
+            return 'ok';
         }
-        this.seen.set(jti, nowMs + ttlMs);
-        return true;
+        if (held)
+            this.seen.delete(jti);
+        if (!this.room(nowMs))
+            return 'full';
+        this.record(jti, exp, true);
+        return 'ok';
+    }
+    /** Undo a spend whose next step could not go ahead. The slot stays held, so
+     * nothing is forgotten, and the artifact can be spent once more. */
+    unspend(jti) {
+        const held = this.seen.get(jti);
+        if (held)
+            held.spent = false;
+    }
+    /** `spend` as a boolean: false for a replay and for a full guard alike. */
+    consume(jti, ttlMs, nowMs) {
+        return this.spend(jti, ttlMs, nowMs) === 'ok';
     }
     get size() {
         return this.seen.size;
     }
-    evictExpired(nowMs) {
-        for (const [jti, exp] of this.seen) {
-            if (exp <= nowMs)
+    record(jti, exp, spent) {
+        this.seen.set(jti, { exp, spent });
+        if (exp < this.earliest)
+            this.earliest = exp;
+    }
+    // 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;
+        if (nowMs < this.earliest)
+            return false;
+        if (nowMs >= this.sweptAt && nowMs - this.sweptAt < FULL_SWEEP_EVERY_MS)
+            return false;
+        this.sweptAt = nowMs;
+        let earliest = Infinity;
+        for (const [jti, e] of this.seen) {
+            if (e.exp <= nowMs)
                 this.seen.delete(jti);
+            else if (e.exp < earliest)
+                earliest = e.exp;
         }
+        this.earliest = earliest;
+        return this.seen.size < this.cap;
     }
 }
-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).
+// 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');
+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.
+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') };
+}
 /**
- * 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 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__') : [];
+}
+function isLegacyRecord(r) {
+    if (r === null || typeof r !== 'object')
+        return false;
+    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 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 positiveInt(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;
+}
+function lifetimeMs(name, v) {
+    const n = positiveInt(name, v);
+    return n === undefined ? undefined : n * 1000;
+}
+/**
+ * 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. 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. See docs/internals.md.
  */
 export class RefreshStore {
     path;
     masterKey;
-    constructor(path, masterKey) {
+    log;
+    maxAgeMs;
+    idleMs;
+    maxFamiliesPerSub;
+    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.maxFamiliesPerSub = positiveInt('maxFamiliesPerSub', options.maxFamiliesPerSub);
+        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() {
-        if (!existsSync(this.path))
-            return { active: {}, spent: {} };
+    /** With `nowMs` (every issue and rotation), also clamps and prunes. */
+    load(nowMs, lines = []) {
+        let d;
+        let readOk = true;
         try {
-            const d = decryptToken(readFileSync(this.path, 'utf-8'), this.masterKey);
-            return { active: d.active ?? {}, spent: d.spent ?? {} };
+            d = readPlain(this.path, this.masterKey);
         }
         catch {
-            return { active: {}, spent: {} };
+            d = null;
+            readOk = false;
+        }
+        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;
         }
+        // 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) {
-        // bound the spent set (drop oldest-inserted) so it can't grow forever.
-        const keys = Object.keys(data.spent);
-        if (keys.length > SPENT_CAP) {
-            for (const k of keys.slice(0, keys.length - SPENT_CAP))
-                delete data.spent[k];
+        // 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))
+            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];
+        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);
+            }
+            catch {
+                // log sink failure ignored
+            }
+        }
+    }
+    // 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)) {
+            if (f.sub !== sub || k === keepKey)
+                continue;
+            entries.push({
+                at: f.usedAt,
+                drop: () => {
+                    delete data.families[k];
+                    lines.push(`refresh family dropped: cap tag=${familyTag(Buffer.from(k, 'base64url'))}`);
+                },
+            });
+        }
+        for (const [t, r] of Object.entries(data.active)) {
+            if (r.sub !== sub)
+                continue;
+            entries.push({
+                at: r.issuedAt,
+                drop: () => {
+                    delete data.active[t];
+                    lines.push(`refresh family dropped: cap tag=${familyTag(r.family)}`);
+                },
+            });
         }
-        atomicWriteFileSync(this.path, encryptToken(data, this.masterKey), 0o600);
+        // +1 accounts for the kept family, which stays live but is never ranked.
+        if (entries.length + 1 <= limit)
+            return;
+        entries.sort((a, b) => a.at - b.at);
+        for (const e of entries.slice(0, entries.length + 1 - limit))
+            e.drop();
     }
-    issue(nowMs, 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: 'owner', issuedAt: nowMs, family: family ?? randomBytes(12).toString('hex') };
+            const lines = [];
+            const { data } = this.load(nowMs, lines);
+            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 };
+            if (this.maxFamiliesPerSub !== undefined)
+                this.enforceFamilyCap(data, sub, this.maxFamiliesPerSub, lines, fidKey);
             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). */
-    rotate(oldToken, nowMs) {
+    /** 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 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 rec = data.active[oldToken];
-            if (!rec) {
-                // Reuse of a rotated-away token signals theft: revoke the whole family.
-                const fam = data.spent[oldToken];
-                if (fam) {
-                    for (const [t, r] of Object.entries(data.active))
-                        if (r.family === fam)
-                            delete data.active[t];
+            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);
-                }
-                return null;
+                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) {
+                const fam = Object.hasOwn(data.spent, oldToken) ? data.spent[oldToken] : undefined;
+                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.family === fam)
+                        delete data.active[t];
+                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: 'owner', issuedAt: nowMs, family: rec.family };
-            this.save(data);
-            return next;
+            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 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();
+            const dropped = dropSub(data, sub);
+            if (dropped > 0)
+                this.save(data);
+            return dropped;
         });
     }
 }