mcp-google-multi 6.0.0-alpha.67 → 6.0.0-alpha.69

package/dist/discover.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
+import { hints } from './hint-provider.js';
 // The description budget is the whole point of lazy mode: a full op list per
 // service put lazy tools/list at ~11.5k tokens (RQ2), so descriptions carry a
 // CAPPED vocabulary and the complete catalog stays in this tool's RESULT.
@@ -91,6 +92,7 @@ export function registerDiscoverTools(registry, policy) {
         }, async ({ query }) => {
             const operations = registry.catalog(service, query);
             registry.reveal(service);
+            const rendered = hints()?.render({ kind: 'policy_summary', policy });
             return {
                 content: [
                     {
@@ -98,7 +100,7 @@ export function registerDiscoverTools(registry, policy) {
                         text: JSON.stringify({
                             service,
                             operations,
-                            writeControl: describePolicy(policy),
+                            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.`,

package/dist/doctor.js

@@ -14,6 +14,7 @@ import { apiProbeDepsFor, probeApiEnablement } from './api-probe.js';
 import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
+import { hints } from './hint-provider.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -70,9 +71,22 @@ export function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
 const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
-function sectionRuntime(deps) {
+function sectionRuntime(deps, tenantScope = false) {
     const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
     if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {
+        if (tenantScope) {
+            // The host version is operator infrastructure, not the tenant's (E7
+            // residue): no version string, and the fix is the operator's to apply.
+            const rendered = hints()?.render({ kind: 'operator_only', slug: 'E_NODE_TOO_OLD' });
+            return {
+                id: 1,
+                title: 'Runtime',
+                verdict: 'fail',
+                slug: 'E_NODE_TOO_OLD',
+                lines: ['Runtime below the supported version'],
+                hint: rendered?.hint ?? 'Tell the server operator the code E_NODE_TOO_OLD.',
+            };
+        }
         return {
             id: 1,
             title: 'Runtime',
@@ -82,7 +96,12 @@ function sectionRuntime(deps) {
             hint: `Upgrade to Node ${MIN_NODE_MAJOR} LTS or newer.`,
         };
     }
-    return { id: 1, title: 'Runtime', verdict: 'ok', lines: [`Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`] };
+    return {
+        id: 1,
+        title: 'Runtime',
+        verdict: 'ok',
+        lines: [tenantScope ? 'Runtime ok' : `Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`],
+    };
 }
 function sectionConfig(deps, set, tenantScope = false) {
     const lines = [];
@@ -90,13 +109,16 @@ function sectionConfig(deps, set, tenantScope = false) {
     let hint;
     let slug;
     if (!set || set.aliases.length === 0) {
+        const tenantHint = tenantScope ? (hints()?.render({ kind: 'no_accounts' })?.hint ?? '') : undefined;
         return {
             id: 2,
             title: 'Config',
             verdict: 'fail',
             slug: 'E_NO_ACCOUNTS_CONFIGURED',
             lines: ['No accounts configured.'],
-            ...(tenantScope ? {} : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
+            ...(tenantScope
+                ? (tenantHint ? { hint: tenantHint } : {})
+                : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
         };
     }
     // The config file, process env, working directory and metrics store below
@@ -188,7 +210,8 @@ function sectionsTokensAndScopes(deps, aliases) {
             if (scopeVerdict === 'ok')
                 scopeVerdict = 'warn';
             scopeLines.push(`${alias}: ${r.callable.length} callable, ${r.requestable.length} requested-not-granted`);
-            scopeHint = `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
+            const rendered = hints()?.render({ kind: 'scopes_missing', account: alias });
+            scopeHint = rendered?.hint ?? `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
         }
         else {
             scopeLines.push(`${alias}: ${r.callable.length} callable, all profile scopes granted`);
@@ -199,7 +222,7 @@ function sectionsTokensAndScopes(deps, aliases) {
         { id: 5, title: 'Scopes', verdict: scopeVerdict, lines: scopeLines, ...(scopeHint ? { hint: scopeHint } : {}), ...(scopeVerdict === 'warn' ? { slug: 'E_SCOPE_NOT_GRANTED' } : {}) },
     ];
 }
-async function sectionApiEnablement(deps, aliases) {
+async function sectionApiEnablement(deps, aliases, tenantScope = false) {
     if (!deps.probeApi) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['Probe not run (no live account probe configured).'] };
     }
@@ -216,8 +239,15 @@ async function sectionApiEnablement(deps, aliases) {
         results = await deps.probeApi(healthy);
     }
     catch (e) {
-        // Network / transient: WARN with the target, never crash the report.
-        return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
+        // Network / transient: WARN with the target, never crash the report. The
+        // raw text can name an egress or proxy host (E7 residue): tenant scope
+        // drops it.
+        return {
+            id: 6,
+            title: 'API enablement',
+            verdict: 'warn',
+            lines: [tenantScope ? 'Probe could not complete.' : `Probe could not complete: ${e?.message ?? e}`],
+        };
     }
     if (results.length === 0) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: [`No probeable service scopes granted on "${healthy}".`] };
@@ -225,13 +255,14 @@ async function sectionApiEnablement(deps, aliases) {
     const disabled = results.filter((r) => r.notEnabled);
     const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
     if (disabled.length > 0) {
+        const rendered = hints()?.render({ kind: 'apis_disabled', services: disabled.map((r) => ({ service: r.service, api: r.api })) });
         return {
             id: 6,
             title: 'API enablement',
             verdict: 'fail',
             slug: 'E_API_NOT_ENABLED',
             lines,
-            hint: disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
+            hint: rendered?.hint ?? disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
         };
     }
     return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
@@ -313,7 +344,7 @@ export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
     // the context's own account count.
     const tenantScope = opts.scope === 'tenant';
     const sections = [];
-    sections.push(sectionRuntime(deps));
+    sections.push(sectionRuntime(deps, tenantScope));
     const set = deps.accountSet();
     sections.push(sectionConfig(deps, set, tenantScope));
     const aliases = set?.aliases ?? [];
@@ -322,7 +353,7 @@ export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
     if (aliases.length > 0) {
         const [tokens, scopes] = sectionsTokensAndScopes(deps, aliases);
         sections.push(tokens, scopes);
-        sections.push(await sectionApiEnablement(deps, aliases));
+        sections.push(await sectionApiEnablement(deps, aliases, tenantScope));
     }
     if (!tenantScope) {
         const http = await sectionHttp(deps, aliases);

package/dist/executor.js

@@ -4,6 +4,7 @@ import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
 import { checkOutboundForMethod } from './outbound-allowlist.js';
+import { hints } from './hint-provider.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -70,10 +71,11 @@ export async function executeApiMethod(method, args, deps = {}) {
         }, true);
     }
     if (!isGoogleApiUrl(url)) {
+        const rendered = hints()?.render({ kind: 'untrusted_host' });
         return jsonResult({
             error: 'untrusted_host',
             message: `Refusing to send credentials to a non-googleapis.com host for "${method.id}".`,
-            hint: 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
+            hint: rendered?.hint ?? 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
             retriable: false,
             account: args.account,
         }, true);

package/dist/fanout.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { getAccountSet, liveAccountCheck, unknownAliasMessage } from './accounts.js';
 import { echoName, echoNames, MAX_SUGGESTED_KEYS } from './arg-strict.js';
+import { hints } from './hint-provider.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
 // `aliases` is required (no global default): the field is baked into a
@@ -113,10 +114,17 @@ export async function runFanout(handler, args, aliases) {
                 results[i] = res?.isError ? { account, ok: false, error: payload } : { account, ok: true, data: payload };
             }
             catch (err) {
+                const rendered = hints()?.render({ kind: 'internal', account });
                 results[i] = {
                     account,
                     ok: false,
-                    error: { error: 'internal', message: err.message, retriable: false, account },
+                    error: {
+                        error: 'internal',
+                        message: rendered?.message ?? err.message,
+                        hint: rendered?.hint,
+                        retriable: false,
+                        account,
+                    },
                 };
             }
         }

package/dist/hint-provider.d.ts

@@ -0,0 +1,129 @@
+import type { DenyReason, Policy } from './write-control.js';
+export type HintCase = {
+    kind: 'reauth';
+    account: string;
+} | {
+    kind: 'legacy_plaintext_token';
+    account: string;
+} | {
+    kind: 'dead_refresh_token';
+    account: string;
+} | {
+    kind: 'token_unreadable';
+    account: string;
+} | {
+    kind: 'scopes_missing';
+    account: string;
+} | {
+    kind: 'scope_not_granted';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_needs_bundle';
+    account: string;
+    scope: string;
+    bundle: string;
+} | {
+    kind: 'scope_base_excluded';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_account_type';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_unknown_scope';
+    scope: string;
+} | {
+    kind: 'scope_unknown';
+    account: string;
+    serviceText?: string;
+    bundle?: string;
+} | {
+    kind: 'write_denied';
+    tool: {
+        name: string;
+        service: string;
+        cud: string;
+    };
+    reason: DenyReason;
+    policy: Policy;
+} | {
+    kind: 'policy_summary';
+    policy: Policy;
+} | {
+    kind: 'outbound_denied';
+    what: string;
+    blocked: string[];
+    entries: string[];
+} | {
+    kind: 'no_default_account';
+    aliases: string[];
+} | {
+    kind: 'no_accounts';
+} | {
+    kind: 'api_not_enabled';
+    api?: string;
+    service?: string;
+    project?: string;
+    googleMessage: string;
+} | {
+    kind: 'apis_disabled';
+    services: {
+        service: string;
+        api: string;
+    }[];
+} | {
+    kind: 'daily_quota';
+} | {
+    kind: 'project_suspended';
+    account: string;
+} | {
+    kind: 'invalid_scope';
+    account: string;
+} | {
+    kind: 'no_oauth_client';
+} | {
+    kind: 'network_error';
+    code: string;
+} | {
+    kind: 'local_path';
+    code: string;
+    path?: string;
+} | {
+    kind: 'internal';
+    account?: string;
+} | {
+    kind: 'untrusted_host';
+} | {
+    kind: 'toolset_disabled';
+    api: string;
+    service: string;
+} | {
+    kind: 'service_not_enabled';
+    tool: string;
+    service: string;
+    bundle?: string;
+    aliases: string[];
+    admin: boolean;
+    toolsetOff: boolean;
+    awaitingRestart: boolean;
+} | {
+    kind: 'operator_only';
+    slug: string;
+};
+export declare const HINT_KINDS: readonly ["reauth", "legacy_plaintext_token", "dead_refresh_token", "token_unreadable", "scopes_missing", "scope_not_granted", "scope_needs_bundle", "scope_base_excluded", "scope_account_type", "scope_unknown_scope", "scope_unknown", "write_denied", "policy_summary", "outbound_denied", "no_default_account", "no_accounts", "api_not_enabled", "apis_disabled", "daily_quota", "project_suspended", "invalid_scope", "no_oauth_client", "network_error", "local_path", "internal", "untrusted_host", "toolset_disabled", "service_not_enabled", "operator_only"];
+/** `message` only for the kinds whose message leaks today (write_denied,
+ * no_oauth_client, local_path, internal, toolset_disabled); every other call
+ * site ignores it. `retriable` only where it may legitimately differ from
+ * the owner's default (scope_not_granted). */
+export interface Rendered {
+    hint: string;
+    message?: string;
+    retriable?: boolean;
+}
+export interface HintProvider {
+    render(c: HintCase): Rendered;
+}
+export declare function setHintProvider(p: HintProvider | null): void;
+export declare function hints(): HintProvider | null;

package/dist/hint-provider.js

@@ -0,0 +1,64 @@
+// A plain array literal, not derived from the union: deriving it would need a
+// value-level mirror of the type anyway, and this way a missing member is
+// caught by the completeness check below instead of silently compiling.
+// `as const` so that check narrows to the literal tuple rather than widening
+// every element back to the whole HintCase['kind'] union (which would make
+// it pass trivially, whatever was listed).
+export const HINT_KINDS = [
+    'reauth',
+    'legacy_plaintext_token',
+    'dead_refresh_token',
+    'token_unreadable',
+    'scopes_missing',
+    'scope_not_granted',
+    'scope_needs_bundle',
+    'scope_base_excluded',
+    'scope_account_type',
+    'scope_unknown_scope',
+    'scope_unknown',
+    'write_denied',
+    'policy_summary',
+    'outbound_denied',
+    'no_default_account',
+    'no_accounts',
+    'api_not_enabled',
+    'apis_disabled',
+    'daily_quota',
+    'project_suspended',
+    'invalid_scope',
+    'no_oauth_client',
+    'network_error',
+    'local_path',
+    'internal',
+    'untrusted_host',
+    'toolset_disabled',
+    'service_not_enabled',
+    'operator_only',
+];
+const _hintKindsComplete = true;
+void _hintKindsComplete;
+// Process-global, like the HTTP reauth linker: one process is either the
+// single owner or one multi-tenant host, never both.
+let installed = null;
+export function setHintProvider(p) {
+    installed = p;
+}
+// A throwing provider must never take down the call site: every call site
+// does `hints()?.render(...)?.hint ?? <default>`, so a render that cannot
+// produce a Rendered falls back to the same literal a missing provider
+// would, and the provider's own error text never reaches a client.
+export function hints() {
+    if (!installed)
+        return null;
+    const provider = installed;
+    return {
+        render(c) {
+            try {
+                return provider.render(c);
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/http-transport.d.ts

@@ -42,7 +42,17 @@ export interface HttpHostOptions {
      * registry, never another subject's. */
     resolveServer?: (claims: {
         sub: string;
-    }) => Promise<ServerTarget | null> | ServerTarget | null;
+    }) => Promise<ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    }> | ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    };
     /** Extra routes keyed by exact pathname (AS endpoints mount here in B13). */
     routes?: Record<string, RouteHandler>;
     log?: (line: string) => void;

package/dist/http-transport.js

@@ -16,6 +16,24 @@ const DISPATCH_TIMEOUT_DEFAULT = 120_000;
  * of a batch synchronously in one tick: without a cap one body multiplies the
  * per-call work by however many frames fit in it. */
 const MAX_BATCH_FRAMES = 16;
+// A resolveServer refusal's body reaches the wire verbatim (H3 PR1): validated
+// so a host cannot accidentally leak an operator path/env var through a wrongly
+// shaped slug or an overlong message. No new slug literal enters core itself —
+// the slug is always the host's own value.
+const REFUSAL_SLUG_RE = /^[a-z][a-z0-9_]{0,39}$/;
+const MAX_REFUSAL_MESSAGE_CHARS = 300;
+// C0/C1 controls, format chars (includes bidi overrides like U+202E and
+// zero-width joiners) and the line/paragraph separators; ordinary non-ASCII
+// letters stay allowed.
+const NON_PRINTABLE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+function isValidRefusal(r) {
+    return (typeof r.error === 'string' &&
+        REFUSAL_SLUG_RE.test(r.error) &&
+        typeof r.message === 'string' &&
+        r.message.length > 0 &&
+        r.message.length <= MAX_REFUSAL_MESSAGE_CHARS &&
+        !NON_PRINTABLE_RE.test(r.message));
+}
 export function parseOwnerEmails(env = process.env) {
     return (env.MCP_OWNER_EMAILS ?? '')
         .split(',')
@@ -366,12 +384,27 @@ export class HttpTransportHost {
             validationEnvelope: this.opts.validationEnvelope,
         };
         if (this.opts.resolveServer) {
+            let resolved;
             try {
-                target = await this.opts.resolveServer({ sub });
+                resolved = await this.opts.resolveServer({ sub });
             }
             catch {
-                target = null;
+                resolved = null;
+            }
+            if (resolved && 'refused' in resolved) {
+                const { refused } = resolved;
+                if (isValidRefusal(refused)) {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: refused.error, message: refused.message }));
+                    this.log(`403 ${refused.error} path=/mcp`);
+                    return;
+                }
+                // An invalid shape falls through to today's exact answer rather than
+                // forwarding something unvalidated; a refusal never reaches dispatch
+                // either way.
+                resolved = null;
             }
+            target = resolved;
             if (!target) {
                 res.writeHead(403, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'tenant_not_found', message: 'no tenant is provisioned for this subject' }));

package/dist/mcp-token.d.ts

@@ -123,6 +123,14 @@ export interface RefreshStoreOptions {
     maxAgeSec?: number;
     /** Idle lifetime in seconds, counted from the last issue or rotation. Unset: unlimited. */
     idleSec?: number;
+    /** Max live refresh-token families per subject (both formats). Unset:
+     * unlimited (default; the single-owner server passes none). When issuing a
+     * new family would put a subject over this, that subject's own
+     * least-recently-used family is dropped (by its last issue or rotation
+     * time) until it fits; a dropped family behaves exactly like a revoked
+     * one. Only the subject signing in ever triggers it, and only its own
+     * families are ever touched. */
+    maxFamiliesPerSub?: number;
     /** Server-side log for a revoked, dropped or expired family. Never given a token or a subject. */
     log?: (line: string) => void;
 }
@@ -141,6 +149,7 @@ export declare class RefreshStore {
     private readonly log;
     private readonly maxAgeMs;
     private readonly idleMs;
+    private readonly maxFamiliesPerSub;
     private macKey;
     private legacyEmpty;
     constructor(path: string, masterKey: string, options?: RefreshStoreOptions);
@@ -156,6 +165,17 @@ export declare class RefreshStore {
     private load;
     private save;
     private emit;
+    /** Evict `sub`'s own least-recently-used sessions (both formats) so at
+     * most `limit` of its live sessions remain; dropping one here is the same
+     * as deleting it from `data.families` / `data.active` on a revoke, so it
+     * can never be presented again (reuse detection for every OTHER family is
+     * untouched). Only `sub`'s own entries are ever inspected.
+     *
+     * `keepKey` is the family just issued: it is excluded from the ranking so
+     * a clock step back, or a concurrent rotate's `usedAt = max(usedAt, nowMs)`
+     * racing ahead of it under the lock, can never make the brand-new family
+     * look like the least recently used one and drop itself. */
+    private enforceFamilyCap;
     private newFamilyId;
     issue(nowMs: number, sub: string): string;
     /** Rotate a presented refresh token; null if it is unknown, malformed, or

package/dist/mcp-token.js

@@ -363,12 +363,16 @@ export function assertRefreshStoreReadable(file, masterKey) {
     }
     checkFormat(file, d);
 }
-function lifetimeMs(name, v) {
+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 * 1000;
+    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
@@ -385,6 +389,7 @@ export class RefreshStore {
     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.
@@ -394,6 +399,7 @@ export class RefreshStore {
         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() {
@@ -502,6 +508,47 @@ export class RefreshStore {
             }
         }
     }
+    /** Evict `sub`'s own least-recently-used sessions (both formats) so at
+     * most `limit` of its live sessions remain; dropping one here is the same
+     * as deleting it from `data.families` / `data.active` on a revoke, so it
+     * can never be presented again (reuse detection for every OTHER family is
+     * untouched). Only `sub`'s own entries are ever inspected.
+     *
+     * `keepKey` is the family just issued: it is excluded from the ranking so
+     * a clock step back, or a concurrent rotate's `usedAt = max(usedAt, nowMs)`
+     * racing ahead of it under the lock, can never make the brand-new family
+     * look like the least recently used one and drop itself. */
+    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)}`);
+                },
+            });
+        }
+        // +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();
+    }
     newFamilyId(data) {
         let fid;
         do
@@ -517,8 +564,11 @@ export class RefreshStore {
             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[fid.toString('base64url')] = { sub, gen: 0, cur, createdAt: nowMs, usedAt: nowMs };
+            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;

package/dist/oauth-as.d.ts

@@ -26,6 +26,10 @@ export interface AuthServerConfig {
     /** `idleSec` of that store: sessions end this long after their last
      * refresh. Unset: unlimited. */
     refreshIdleSec?: number;
+    /** `maxFamiliesPerSub` of that store: bounds how many live refresh-token
+     * families one subject may hold, dropping its least-recently-used one to
+     * make room. Unset: unlimited. */
+    refreshMaxFamiliesPerSub?: 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
@@ -103,7 +107,11 @@ export interface AuthServerDeps {
         hd?: string;
     }) => {
         sub: string;
-    } | null;
+    } | null | {
+        denied: {
+            description: string;
+        };
+    };
     /** alias_add completion: persist the new alias's config row and tokens under
      * its tenant. /callback awaits it only after a successful Google exchange.
      * A returned refusal answers 403 with its slug; a throw or rejection answers