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

package/dist/index.js

@@ -1,97 +1,26 @@
 #!/usr/bin/env node
 // First import: triggers accounts.js module load (env files + registry) before
 // anything else. Named to also pull the server-only empty-registry guard (BR-4).
-import { assertServerAccountsConfigured, getAccountSet } from './accounts.js';
+import { assertServerAccountsConfigured } from './accounts.js';
+import { accountsAssertRequired, assertNoEnvAccountsMode, assertNoEnvOptionalScopesMode, isMultiTenantBoot, mtBootGates } from './boot-gates.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { McpServer } from "@modelcontextprotocol/server";
-import { GENERATED_SERVICES } from './tools/generated/index.js';
-import { GENERATED_GATES, SERVICES, unknownToolMessage } from './services.js';
-import { ToolRegistry, resolveDiscoveryMode } from './registry.js';
-import { registerDiscoverTools } from './discover.js';
-import { registerEscapeTools } from './tools/google-api.js';
-import { registerAccountTools } from './tools/accounts-tool.js';
-import { registerDiagnoseTool } from './doctor.js';
-import { registerAccountWizardTools } from './tools/account-wizard.js';
-import { getToolsets, toolsetEnabled } from './toolsets.js';
+import { resolveDiscoveryMode } from './registry.js';
 import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
+import { buildRegistry, requestHooksFor } from './compose.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
-import { argNormalizationEnabled, withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
-import { unknownArgMode } from './arg-strict.js';
+import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
 import { envValueSource } from './env-load.js';
 import { loadConfigFile } from './config-file.js';
 import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-/** Unknown-argument screening options, or undefined when the feature is off.
- * Shared by both transports so a mistyped argument behaves identically. */
-function strictArgOptions(registry, metrics) {
-    const mode = unknownArgMode();
-    if (mode === 'off')
-        return undefined;
-    return {
-        mode,
-        declaredFor: (tool) => registry.declaredKeys(tool),
-        siblingsFor: (tool, keys) => registry.siblingSpellings(tool, keys),
-        unknownTool: (name) => unknownToolMessage(registry, name),
-        onDrop: metrics ? (tool, keys) => metrics.recordArgDrop(tool, keys) : undefined,
-    };
-}
-function buildRegistry(server, ctx, mode, metrics = null) {
-    const policy = ctx.policy;
-    const registry = new ToolRegistry(server, policy, mode, metrics);
-    const toolsets = getToolsets();
-    if (toolsets !== 'all') {
-        const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
-        for (const requested of toolsets) {
-            if (!known.has(requested)) {
-                process.stderr.write(`GOOGLE_TOOLSETS: unknown service "${requested}" ignored\n`);
-            }
-        }
-    }
-    for (const svc of SERVICES) {
-        if (!toolsetEnabled(toolsets, svc.name))
-            continue;
-        if (svc.enabled && !svc.enabled()) {
-            if (toolsets !== 'all') {
-                const hint = svc.name === 'admin' ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS)' : `add "${svc.name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`;
-                process.stderr.write(`GOOGLE_TOOLSETS: "${svc.name}" requested but not enabled — ${hint}\n`);
-            }
-            continue;
-        }
-        svc.register(registry);
-    }
-    for (const gen of GENERATED_SERVICES) {
-        if (!toolsetEnabled(toolsets, gen.name))
-            continue;
-        const curated = SERVICES.find((s) => s.name === gen.name);
-        const gate = curated?.enabled ?? GENERATED_GATES[gen.name]?.enabled;
-        if (gate && !gate()) {
-            if (!curated && toolsets !== 'all') {
-                process.stderr.write(`GOOGLE_TOOLSETS: "${gen.name}" requested but not enabled — ${GENERATED_GATES[gen.name].hint}\n`);
-            }
-            continue;
-        }
-        gen.register(registry);
-    }
-    if (registry.services().length === 0) {
-        const known = [...new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)])].sort();
-        throw new Error(`GOOGLE_TOOLSETS="${process.env.GOOGLE_TOOLSETS ?? ''}" selected no enabled services. ` +
-            `Known services: ${known.join(', ')}. ` +
-            `Note: optional services need their bundle in an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES); admin needs an admin account/profile.`);
-    }
-    registerDiscoverTools(registry, policy);
-    registerEscapeTools(registry, policy);
-    registerAccountTools(registry);
-    registerDiagnoseTool(registry);
-    registerAccountWizardTools(registry, server);
-    return registry;
-}
 async function main() {
     if (process.argv.includes('auth')) {
         const { runAuthFlow } = await import('./auth.js');
@@ -198,14 +127,8 @@ async function main() {
         }
         return;
     }
-    // BR-4: the SERVER never boots with an empty registry. The bootstrap and
-    // diagnostic CLIs above already returned; a fresh user configures accounts
-    // (env / migrate-config / account import / auth) before the server runs.
-    assertServerAccountsConfigured();
-    // Resolve (or provision) the master key BEFORE serving: the hard guard is
-    // specced "fatal at startup", never mid-dispatch.
-    const { resolveMasterKey } = await import('./master-key.js');
-    resolveMasterKey();
+    // Transport derivation FIRST: the accounts gate below is transport-aware
+    // (a multi-tenant HTTP deploy legitimately boots with zero accounts).
     const { resolveHttpConfig, transportIncludesHttp } = await import('./http-config.js');
     let httpCfg;
     try {
@@ -217,6 +140,21 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
+    // BR-4: the SERVER never boots with an empty registry — stdio always, HTTP
+    // when single-owner. The bootstrap and diagnostic CLIs above already
+    // returned. A multi-tenant boot instead refuses the two process-wide env
+    // vectors that would leak one operator's accounts/scopes into every tenant.
+    const mt = isMultiTenantBoot();
+    if (accountsAssertRequired(wantStdio, mt))
+        assertServerAccountsConfigured();
+    if (mt) {
+        assertNoEnvAccountsMode();
+        assertNoEnvOptionalScopesMode();
+    }
+    // Resolve (or provision) the master key BEFORE serving: the hard guard is
+    // specced "fatal at startup", never mid-dispatch.
+    const { resolveMasterKey } = await import('./master-key.js');
+    resolveMasterKey();
     // Local usage metrics: fail-closed resolve, self-announcing source, null
     // when off (no wrapper, no dir, nothing initializes). One instance per
     // transport so `boots` keys stay honest under `both`.
@@ -254,40 +192,47 @@ async function main() {
     if (wantStdio) {
         const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
         const stdioMetrics = initMetricsFor('stdio', resolveDiscoveryMode());
-        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }), undefined, stdioMetrics);
+        const stdioCtx = buildIdentityContext(process.env, { transport: 'stdio' });
+        const registry = buildRegistry(server, stdioCtx, undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
+        const stdioHooks = requestHooksFor(registry, stdioCtx, stdioMetrics);
         // Outbound runs outermost-first, so the composition is deliberate: the
         // envelope rewrite is INNERMOST (last to touch the frame), the tap sits
         // above it (classifying the ORIGINAL validation prose), arg normalization
         // outermost. The tap only counts outbound JSON-RPC error frames (no
         // handler ran) plus id->tool names.
-        let transport = withValidationEnvelope(new StdioServerTransport(), {
-            isKnownTool: (n) => registry.hasTool(n),
-            defaultAccount: () => getAccountSet().defaultAccount,
-        });
+        let transport = withValidationEnvelope(new StdioServerTransport(), stdioHooks.validationEnvelope);
         if (stdioMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
             transport = tapUsageMetrics(transport, stdioMetrics, (n) => registry.hasTool(n));
         }
-        const strictStdio = strictArgOptions(registry, stdioMetrics);
-        await server.connect(argNormalizationEnabled() || strictStdio
+        await server.connect(stdioHooks.argShapeFor || stdioHooks.strictArgs
             ? withArgNormalization(transport, 
             // Gated exactly as the HTTP leg gates `argShapeFor`. Passing the
             // shape unconditionally made stdio rename keys while
             // GOOGLE_ARG_NORMALIZE=off, so the same call succeeded on stdio
             // and failed on HTTP once screening rejects.
-            argNormalizationEnabled() ? (n) => registry.argShape(n) : () => undefined, undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, strictStdio)
+            stdioHooks.argShapeFor ?? (() => undefined), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, stdioHooks.strictArgs)
             : transport);
     }
     if (wantHttp) {
         const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
-        // BR3 / C13: the owner allowlist is the entire multi-tenant collapse; refuse
-        // to open an ungated HTTP endpoint.
         const owners = parseOwnerEmails(process.env);
-        if (owners.length === 0) {
-            process.stderr.write('E_OWNER_EMAILS_REQUIRED: MCP_TRANSPORT includes http but MCP_OWNER_EMAILS is empty. Set MCP_OWNER_EMAILS to the Google email(s) allowed to authenticate.\n');
-            process.exit(1);
+        const gates = mtBootGates();
+        if (gates?.multiTenant) {
+            // Same fail-fast SHAPE, different condition: an ungated HTTP endpoint
+            // must never boot; under tenancy the gate is "a valid provisioning
+            // mechanism exists", not a flat owner allowlist.
+            gates.assertProvisioningGate();
+        }
+        else {
+            // BR3 / C13: the owner allowlist is the entire multi-tenant collapse;
+            // refuse to open an ungated HTTP endpoint.
+            if (owners.length === 0) {
+                process.stderr.write('E_OWNER_EMAILS_REQUIRED: MCP_TRANSPORT includes http but MCP_OWNER_EMAILS is empty. Set MCP_OWNER_EMAILS to the Google email(s) allowed to authenticate.\n');
+                process.exit(1);
+            }
         }
         // BR7: stateless HTTP cannot push tools/list_changed, so it forces curated.
         const configuredMode = (process.env.GOOGLE_DISCOVERY ?? '').trim().toLowerCase();
@@ -296,33 +241,22 @@ async function main() {
         }
         const httpServer = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
         const httpMetrics = initMetricsFor('http', 'curated');
-        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated', httpMetrics);
+        const httpCtx = buildIdentityContext(process.env, { transport: 'http' });
+        const registry = buildRegistry(httpServer, httpCtx, 'curated', httpMetrics);
         registry.installListHandler();
         registerSetupPrompt(httpServer);
         // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
-        const { buildAuthServer } = await import('./oauth-as.js');
+        const { buildAuthServer, verifiedEmailFromIdToken } = await import('./oauth-as.js');
         const { jwtSecretFrom } = await import('./mcp-token.js');
         const { resolveJwtKey, resolveMasterKeyForDispatch } = await import('./master-key.js');
         const { OAuth2Client } = await import('googleapis-common');
-        const { writeToken } = await import('./token-store.js');
+        const { readToken, writeToken } = await import('./token-store.js');
         const { resolveScopesForAccount } = await import('./auth.js');
+        const { ownerAuthUrlOptions } = await import('./oauth-consent.js');
+        const { scopeGrantDiff, setWizardHttpConsent } = await import('./tools/account-wizard.js');
         const { configDir } = await import('./config-file.js');
         const { getAccountSet } = await import('./accounts.js');
         const googleClient = () => new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, `${httpCfg.publicUrl}/callback`);
-        // Only trust the id_token email when Google marks it verified (#8).
-        const verifiedEmailFromIdToken = (idToken) => {
-            if (!idToken)
-                return undefined;
-            try {
-                const [, payload] = idToken.split('.');
-                const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8'));
-                const verified = claims.email_verified === true || claims.email_verified === 'true';
-                return verified ? claims.email : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        };
         const authServer = buildAuthServer({
             base: httpCfg.publicUrl,
             resourceUri: httpCfg.resourceUri,
@@ -333,20 +267,7 @@ async function main() {
             masterKey: resolveMasterKeyForDispatch().key,
             refreshStorePath: path.join(configDir(), 'mcp-tokens.enc'),
         }, {
-            buildGoogleAuthUrl: ({ flow, alias, state }) => {
-                if (flow === 'alias_reauth' && alias) {
-                    const cfg = getAccountSet().configs[alias];
-                    // openid+email so /callback can bind the returned identity to the alias.
-                    return googleClient().generateAuthUrl({
-                        access_type: 'offline',
-                        prompt: 'consent',
-                        scope: [...new Set([...resolveScopesForAccount(alias), 'openid', 'email'])],
-                        login_hint: cfg?.email,
-                        state,
-                    });
-                }
-                return googleClient().generateAuthUrl({ scope: ['openid', 'email'], prompt: 'select_account', state });
-            },
+            buildGoogleAuthUrl: ({ flow, alias, state }) => googleClient().generateAuthUrl(ownerAuthUrlOptions({ flow, alias, state }, (a) => resolveScopesForAccount(a))),
             exchangeCode: async (code, flow) => {
                 const { tokens } = await googleClient().getToken(code);
                 const email = verifiedEmailFromIdToken(tokens.id_token ?? undefined);
@@ -355,13 +276,25 @@ async function main() {
                 return { tokens: flow === 'owner_gate' ? {} : tokens, email };
             },
             writeToken: (alias, tokens) => writeToken(alias, tokens),
+            missingScopes: (alias, granted) => scopeGrantDiff(resolveScopesForAccount(alias), granted),
+            hasToken: (alias) => {
+                try {
+                    return readToken(alias) != null;
+                }
+                catch {
+                    return false; // undecryptable: nothing usable to keep
+                }
+            },
             aliasEmail: (alias) => getAccountSet().configs[alias]?.email,
             log: (l) => process.stderr.write(`[as] ${l}\n`),
         });
-        // BV-1: over HTTP, a dead/missing per-account token surfaces a clickable
-        // re-auth link into the AS's alias_reauth flow instead of a stdio CLI hint.
-        const { setHttpReauthBase } = await import('./reauth-hint.js');
-        setHttpReauthBase(httpCfg.publicUrl);
+        // BV-1: over HTTP, a dead/missing per-account token surfaces a clickable,
+        // signed re-auth link into the AS's alias_reauth flow instead of a CLI hint.
+        const { setHttpReauthLink } = await import('./reauth-hint.js');
+        setHttpReauthLink((alias) => authServer.reauthLink(alias));
+        // Wizard consent over HTTP: hand out the same signed link instead of
+        // binding a loopback listener.
+        setWizardHttpConsent({ mintConsentUrl: (alias) => authServer.reauthLink(alias) });
         let httpTap;
         if (httpMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
@@ -375,14 +308,9 @@ async function main() {
             authenticate: authServer.authenticate,
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
-            argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
+            ...requestHooksFor(registry, httpCtx, httpMetrics),
             metricsTap: httpTap,
-            validationEnvelope: {
-                isKnownTool: (n) => registry.hasTool(n),
-                defaultAccount: () => getAccountSet().defaultAccount,
-            },
             onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
-            strictArgs: strictArgOptions(registry, httpMetrics),
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);

package/dist/master-key.js

@@ -38,17 +38,25 @@ let keychainFactory = systemKeychain;
 export function __setKeychainFactoryForTest(fn) {
     keychainFactory = fn ?? systemKeychain;
 }
-// Glob the token dir instead of iterating registered aliases: an orphan .enc
-// (alias removed from the registry, or a partial GOOGLE_ACCOUNTS override in
-// one client) must still stop a fresh key from being minted.
-function anyTokenFileExists() {
+function anyEncFileUnder(dir) {
     try {
-        return fs.readdirSync(getTokenDir()).some((f) => f.endsWith('.enc'));
+        return fs.readdirSync(dir, { recursive: true }).some((f) => String(f).endsWith('.enc'));
     }
     catch {
         return false;
     }
 }
+// Glob the token dir instead of iterating registered aliases: an orphan .enc
+// (alias removed from the registry, or a partial GOOGLE_ACCOUNTS override in
+// one client) must still stop a fresh key from being minted. TOKEN_STORE_PATH
+// may relocate the token dir outside configDir(), so scan it directly; the
+// recursive configDir() walk then covers BOTH the tenant-namespaced token root
+// (tenants/<id>) AND any top-level master-key-encrypted registry beside it
+// (e.g. a downstream tenant map / invite store). Minting a fresh MASTER_KEY
+// over any existing .enc bricks it irreversibly, so the scan must see them all.
+function anyTokenFileExists() {
+    return anyEncFileUnder(getTokenDir()) || anyEncFileUnder(configDir());
+}
 function readKeyFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf8').trim();

package/dist/mcp-token.d.ts

@@ -1,7 +1,7 @@
 export declare const ACCESS_TTL_DEFAULT = 600;
 export declare const STATE_TTL_DEFAULT = 600;
 export declare const CODE_TTL_DEFAULT = 60;
-export declare const REPLAY_CAP_DEFAULT = 10000;
+export declare const REPLAY_CAP_DEFAULT = 100000;
 /** Derive the HS256 secret (32 bytes) from the provisioned MCP_JWT_KEY string. */
 export declare function jwtSecretFrom(jwtKey: string): Uint8Array;
 export interface AccessTokenParams {
@@ -9,6 +9,7 @@ export interface AccessTokenParams {
     secret: Uint8Array;
     ttlSec?: number;
     iat: number;
+    sub: string;
 }
 export declare function signAccessToken(p: AccessTokenParams): Promise<string>;
 export interface AccessClaims {
@@ -19,63 +20,179 @@ export interface AccessClaims {
 /** Verify an access token for `/mcp`. Throws on bad sig / aud / iss / exp. */
 export declare function verifyAccessToken(token: string, base: string, secret: Uint8Array): Promise<AccessClaims>;
 export interface StatePayload {
-    flow: 'owner_gate' | 'alias_reauth';
+    flow: 'owner_gate' | 'alias_reauth' | 'alias_add';
     client_id: string;
     redirect_uri: string;
     code_challenge: string;
     client_state?: string;
     resource: string;
     alias?: string;
+    /** alias_add only: the tenant the new alias binds under. Signed server-side
+     * at mint time — never caller-supplied at /authorize or /callback. */
+    tenantId?: string;
+    /** alias_add only: scope bundles chosen when the link was minted. */
+    bundles?: string[];
+    /** alias_add only: an opaque value the minting caller chose, signed like
+     * tenantId and handed back to its binder (e.g. a server-side link record). */
+    nonce?: string;
+    /** owner_gate only: base64url sha256 of the browser-binding cookie the
+     * Google redirect set; /callback refuses a browser that lacks it. */
+    bind?: string;
 }
 export interface CodePayload {
     redirect_uri: string;
     code_challenge: string;
     resource: string;
-    sub: 'owner';
+    sub: string;
 }
 export declare function signState(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyState(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+export declare function verifyState(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<StatePayload & {
     jti: string;
+    exp: number;
 }>;
+/** 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 declare const REAUTH_LINK_TTL_SEC = 3600;
+/** 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 declare function signReauthLink(base: string, secret: Uint8Array, alias: string, nowSec: number): string;
+/** The alias a link was issued for, or null when it is missing, forged or expired. */
+export declare function verifyReauthLink(base: string, secret: Uint8Array, params: {
+    alias: string;
+    exp: string;
+    sig: string;
+}, nowSec: number): string | null;
 /** A pending-authorization artifact for the DCR consent interstitial (same
  * shape as `state`, distinct purpose so the two can't be confused). */
 export declare function signPending(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyPending(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+export declare function verifyPending(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<StatePayload & {
     jti: string;
+    exp: number;
 }>;
 export declare function signAuthzCode(payload: CodePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyAuthzCode(token: string, base: string, secret: Uint8Array): Promise<CodePayload & {
+export declare function verifyAuthzCode(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<CodePayload & {
     jti: string;
+    exp: number;
 }>;
+/** `full`: there is no room without forgetting a jti that is still live. */
+export type ReplaySpend = 'ok' | 'replay' | 'full';
 export declare class ReplayGuard {
     private readonly cap;
     private readonly seen;
+    private earliest;
+    private sweptAt;
     constructor(cap?: number);
-    /** Record a jti as spent. Returns false if it was already spent (replay). */
+    /** 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: string, ttlMs: number, nowMs: number): 'ok' | 'full';
+    /** Record a jti as spent. A full guard refuses instead of evicting a live
+     * jti: a flood of spends would otherwise make a spent artifact usable again,
+     * such as a callback the browser binding refused (H4 F1). `artifactExpMs`
+     * keeps the record alive as long as the artifact itself, even when the clock
+     * stepped back between its signing and this spend. */
+    spend(jti: string, ttlMs: number, nowMs: number, artifactExpMs?: number): ReplaySpend;
+    /** 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: string): void;
+    /** `spend` as a boolean: false for a replay and for a full guard alike. */
     consume(jti: string, ttlMs: number, nowMs: number): boolean;
     get size(): number;
-    private evictExpired;
+    private record;
+    private room;
 }
+/** An earlier release's record, keyed by its live token. */
 export interface RefreshRecord {
-    sub: 'owner';
+    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;
+    /** 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;
+}
+/**
+ * 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 readonly maxFamiliesPerSub;
+    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, 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). */
-    rotate(oldToken: string, nowMs: number): string | null;
+    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
+     * 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: string, nowMs: number, accept?: (sub: string) => boolean): {
+        token: string;
+        sub: string;
+    } | null;
+    /** 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;
 }