harper 5.1.20 → 5.2.0-alpha.5

package/components/mcp/customResourceRegistry.ts

@@ -58,27 +58,20 @@ interface CompiledDef {
 	def: CustomResourceDef;
 	/** Present for template entries only. */
 	regex?: RegExp;
-	params?: TemplateParam[];
-}
-
-interface TemplateParam {
-	name: string;
-	/** `{+name}` — reserved expansion, may span segments. */
-	reserved: boolean;
+	paramNames?: string[];
 }
 
 const registry = new Map<McpProfile, CompiledDef[]>();
 
 /**
  * Compile a URI template into a matcher. `{name}` matches a single path
- * segment (`[^/]+`), and an encoded separator — `%2F`/`%5C` — in the capture
- * rejects the match, so the one-segment contract survives percent-decoding);
- * `{+name}` matches across segments (`.+`), mirroring RFC 6570 level-2
- * reserved expansion, which is how MCP clients construct URIs from templates.
- * Throws on malformed templates so registration can warn-and-skip the entry.
+ * segment (`[^/]+`); `{+name}` matches across segments (`.+`), mirroring
+ * RFC 6570 level-2 reserved expansion, which is how MCP clients construct
+ * URIs from templates. Throws on malformed templates so registration can
+ * warn-and-skip the entry.
  */
-export function compileUriTemplate(template: string): { regex: RegExp; params: TemplateParam[] } {
-	const params: TemplateParam[] = [];
+export function compileUriTemplate(template: string): { regex: RegExp; paramNames: string[] } {
+	const paramNames: string[] = [];
 	let pattern = '';
 	let index = 0;
 	while (index < template.length) {
@@ -96,25 +89,18 @@ export function compileUriTemplate(template: string): { regex: RegExp; params: T
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
 			throw new Error(`invalid template parameter '{${template.slice(open + 1, close)}}' in uriTemplate: ${template}`);
 		}
-		if (params.some((p) => p.name === name)) {
+		if (paramNames.includes(name)) {
 			// a repeated name would silently overwrite the earlier captured value
 			throw new Error(`duplicate template parameter '{${name}}' in uriTemplate: ${template}`);
 		}
-		params.push({ name, reserved });
+		paramNames.push(name);
 		pattern += reserved ? '(.+)' : '([^/]+)';
 		index = close + 1;
 	}
-	if (params.length === 0) throw new Error(`uriTemplate has no parameters (use \`uri\` instead): ${template}`);
-	return { regex: new RegExp(`^${pattern}$`), params };
+	if (paramNames.length === 0) throw new Error(`uriTemplate has no parameters (use \`uri\` instead): ${template}`);
+	return { regex: new RegExp(`^${pattern}$`), paramNames };
 }
 
-// `{name}` captures run against the still-encoded URI, so a client can smuggle
-// a separator through the `[^/]+` class as %2F (or %5C) and have it decode to
-// a real slash/backslash AFTER the segment boundary was checked — defeating
-// the one-segment contract authors rely on for path construction. Reject the
-// match instead (the URI simply doesn't fit a single-segment slot).
-const ENCODED_SEPARATOR = /%2f|%5c/i;
-
 function escapeRegex(literal: string): string {
 	return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -123,9 +109,9 @@ function escapeRegex(literal: string): string {
 export function addCustomResource(def: CustomResourceDef): void {
 	const compiled: CompiledDef = { def };
 	if (def.uriTemplate) {
-		const { regex, params } = compileUriTemplate(def.uriTemplate);
+		const { regex, paramNames } = compileUriTemplate(def.uriTemplate);
 		compiled.regex = regex;
-		compiled.params = params;
+		compiled.paramNames = paramNames;
 	}
 	let list = registry.get(def.profile);
 	if (!list) {
@@ -195,21 +181,14 @@ export function matchCustomResource(
 	for (const { def } of list) {
 		if (def.uri === uri) return { def, params: {} };
 	}
-	for (const { def, regex, params: templateParams } of list) {
-		if (!regex || !templateParams) continue;
+	for (const { def, regex, paramNames } of list) {
+		if (!regex || !paramNames) continue;
 		const match = regex.exec(uri);
 		if (!match) continue;
 		const params: Record<string, string> = {};
-		let separatorSmuggled = false;
-		for (let i = 0; i < templateParams.length; i++) {
-			const raw = match[i + 1];
-			if (!templateParams[i].reserved && ENCODED_SEPARATOR.test(raw)) {
-				separatorSmuggled = true;
-				break;
-			}
-			params[templateParams[i].name] = decodeURIComponentSafe(raw);
+		for (let i = 0; i < paramNames.length; i++) {
+			params[paramNames[i]] = decodeURIComponentSafe(match[i + 1]);
 		}
-		if (separatorSmuggled) continue;
 		return { def, params };
 	}
 	return undefined;

package/components/mcp/listChanged.ts

@@ -32,23 +32,18 @@ const MAX_RESOURCES_PAGE = 1000;
 let initialized = false;
 let onUserChangeBound: (() => void) | undefined;
 let onSchemaChangeBound: (() => void) | undefined;
+let onResourcesRegisteredBound: (() => void) | undefined;
+
+interface ItcHandlers {
+	userHandler?: { addListener?: (fn: () => void) => void };
+	schemaHandler?: { addListener?: (fn: () => void) => void };
+	resourceHandler?: { addListener?: (fn: () => void) => void };
+}
 
 // Test seams: avoid importing the real ITC handler from unit tests.
-let _itcHandlersOverride:
-	| {
-			userHandler?: { addListener?: (fn: () => void) => void };
-			schemaHandler?: { addListener?: (fn: () => void) => void };
-	  }
-	| undefined;
+let _itcHandlersOverride: ItcHandlers | undefined;
 
-export function _setItcHandlersForTest(
-	h:
-		| {
-				userHandler?: { addListener?: (fn: () => void) => void };
-				schemaHandler?: { addListener?: (fn: () => void) => void };
-		  }
-		| undefined
-): void {
+export function _setItcHandlersForTest(h: ItcHandlers | undefined): void {
 	_itcHandlersOverride = h;
 }
 
@@ -56,14 +51,10 @@ export function _resetListChangedForTest(): void {
 	initialized = false;
 	onUserChangeBound = undefined;
 	onSchemaChangeBound = undefined;
+	onResourcesRegisteredBound = undefined;
 }
 
-function loadItcHandlers():
-	| {
-			userHandler?: { addListener?: (fn: () => void) => void };
-			schemaHandler?: { addListener?: (fn: () => void) => void };
-	  }
-	| undefined {
+function loadItcHandlers(): ItcHandlers | undefined {
 	if (_itcHandlersOverride) return _itcHandlersOverride;
 	try {
 		return require('../../server/itc/serverHandlers');
@@ -286,6 +277,27 @@ async function onSchemaChange(): Promise<void> {
 	}
 }
 
+/**
+ * A component's JS resources (resources.js) register on the local worker AFTER the MCP component's
+ * own boot scan and after the schema-change rebuilds (which fire while the @table classes register —
+ * still before the JS subclass that extends them). That JS subclass is where authors declare
+ * `static mcpTools`/`mcpPrompts`, so without a rebuild here the application tool list never reflects
+ * them (#1448). Rebuild and re-notify application sessions; no user re-resolution (a resource
+ * registration doesn't change the acting user) and no operations-profile work (its tool/resource
+ * set isn't derived from JS resources).
+ */
+function onResourcesRegistered(): void {
+	try {
+		refreshApplicationTools();
+	} catch (err) {
+		harperLogger.warn(`MCP listChanged refreshApplicationTools (resources) failed: ${(err as Error).message}`);
+	}
+	for (const r of snapshotSessions('application')) {
+		maybeNotifyToolsChanged(r);
+		maybeNotifyResourcesChanged(r);
+	}
+}
+
 /**
  * Idempotent: subscribe once at component boot. Repeated calls are
  * no-ops. Returns true if subscriptions were actually installed (false
@@ -313,6 +325,11 @@ export function initListChanged(): boolean {
 		handlers.schemaHandler.addListener(onSchemaChangeBound);
 		installed++;
 	}
+	if (handlers.resourceHandler?.addListener) {
+		onResourcesRegisteredBound = onResourcesRegistered;
+		handlers.resourceHandler.addListener(onResourcesRegisteredBound);
+		installed++;
+	}
 	initialized = installed > 0;
 	if (initialized) {
 		harperLogger.info(`MCP listChanged: subscribed to ${installed} event channel(s)`);

package/components/mcp/quota.ts

@@ -0,0 +1,145 @@
+/**
+ * Durable, operator-pluggable quota hook for MCP `tools/call` (#1610).
+ *
+ * The in-memory buckets in `rateLimit.ts` bound instantaneous rates but are
+ * per-worker and reset on restart — insufficient as a COST control for a
+ * public unauthenticated tool (an LLM-backed `answer`, say). This hook lets
+ * the operator implement a durable policy (e.g. a persisted per-IP daily
+ * counter table) behind config:
+ *
+ *   mcp:
+ *     application:
+ *       quota:
+ *         resource: McpQuota        # exported Resource path
+ *         method: allowMcpCall      # static method on it (this is the default)
+ *
+ * Before each admitted tools/call, Harper calls
+ * `QuotaClass.allowMcpCall({ identity, tool, user, profile, sessionId })`.
+ * Return `true` (or any truthy non-object) to allow; return
+ * `{ allowed: false, message?, retryAfterSeconds? }` to deny — the denial
+ * surfaces to the client as `isError` with `kind: 'quota_exceeded'`.
+ * Counting is the hook's business: increment on check, or on success via
+ * your own bookkeeping — Harper calls once per attempted tool call.
+ *
+ * FAIL-CLOSED: a hook that throws (or a configured resource/method that
+ * doesn't resolve) DENIES the call. Cost protection that silently disables
+ * itself on a bug is worse than a hard failure (#1422 set this precedent
+ * for allow* hooks). The raw error goes to the server log only.
+ *
+ * RACE-SAFETY: the hook can run concurrently for the SAME identity — within
+ * a worker (interleaving across the hook's own await boundaries) and across
+ * workers (separate processes sharing the database). A naive read-then-write
+ * counter (`get` → `put used+1`) can undercount under that concurrency and
+ * admit calls past the configured limit. Production implementations should
+ * make the read-modify-write atomic: run it in a transaction that serializes
+ * conflicting writers, use a compare-and-set retry loop, or maintain the
+ * counter in a store with native atomic increments.
+ *
+ * Dispatch uses the LIVE registry class, same as custom tools — an exported
+ * subclass replacing the entry on reload wins.
+ */
+import * as env from '../../utility/environment/environmentManager.ts';
+import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import type { McpProfile } from './transport.ts';
+import type { AuthedUser } from './toolRegistry.ts';
+
+export interface QuotaCheckInfo {
+	/** Client identity from `resolveClientIdentity` (socket IP or trusted-header value); may be undefined. */
+	identity?: string;
+	tool: string;
+	user: AuthedUser;
+	profile: McpProfile;
+	sessionId: string;
+}
+
+export interface QuotaDenial {
+	allowed: false;
+	/** Shown to the client verbatim — author-controlled, keep it safe. */
+	message?: string;
+	retryAfterSeconds?: number;
+}
+
+export type QuotaDecision = { allowed: true } | QuotaDenial;
+
+const CONFIG_KEYS: Record<McpProfile, { resource: string; method: string }> = {
+	operations: {
+		resource: CONFIG_PARAMS.MCP_OPERATIONS_QUOTA_RESOURCE,
+		method: CONFIG_PARAMS.MCP_OPERATIONS_QUOTA_METHOD,
+	},
+	application: {
+		resource: CONFIG_PARAMS.MCP_APPLICATION_QUOTA_RESOURCE,
+		method: CONFIG_PARAMS.MCP_APPLICATION_QUOTA_METHOD,
+	},
+};
+
+const DEFAULT_METHOD = 'allowMcpCall';
+
+type ResourcesLike = Map<string, { Resource: unknown }> | undefined;
+
+// Test seam — mirrors resources.ts: the real registry initializes the whole
+// Harper graph at import, which unit tests can't do.
+let _resourcesOverride: ResourcesLike;
+export function _setQuotaResourcesForTest(r: ResourcesLike): void {
+	_resourcesOverride = r;
+}
+
+function getResources(): ResourcesLike {
+	if (_resourcesOverride) return _resourcesOverride;
+	const { resources } = require('../../resources/Resources');
+	return resources as ResourcesLike;
+}
+
+/** Warn-once-per-profile state for a misconfigured hook (missing resource/method). */
+const warnedMisconfigured = new Set<McpProfile>();
+export function _resetQuotaWarningsForTest(): void {
+	warnedMisconfigured.clear();
+}
+
+/**
+ * Run the configured durable quota hook, if any. Returns `{allowed: true}`
+ * when no hook is configured (the feature is opt-in). Misconfiguration and
+ * hook errors DENY (fail-closed) with a sanitized message.
+ */
+export async function checkDurableQuota(info: QuotaCheckInfo): Promise<QuotaDecision> {
+	const keys = CONFIG_KEYS[info.profile];
+	const resourcePath = env.get(keys.resource);
+	if (typeof resourcePath !== 'string' || !resourcePath) {
+		return { allowed: true };
+	}
+	const methodName =
+		typeof env.get(keys.method) === 'string' && env.get(keys.method) ? env.get(keys.method) : DEFAULT_METHOD;
+	const entry = getResources()?.get(resourcePath);
+	const QuotaClass = entry?.Resource as Record<string, unknown> | undefined;
+	const method = QuotaClass?.[methodName as string];
+	if (typeof method !== 'function') {
+		if (!warnedMisconfigured.has(info.profile)) {
+			warnedMisconfigured.add(info.profile);
+			harperLogger.warn(
+				`MCP ${info.profile} quota hook misconfigured: no exported resource '${resourcePath}' with static method '${methodName}'; DENYING tool calls (fail-closed)`
+			);
+		}
+		return { allowed: false, message: 'quota policy unavailable' };
+	}
+	try {
+		const result = await (method as (i: QuotaCheckInfo) => unknown).call(QuotaClass, info);
+		if (result && typeof result === 'object') {
+			const decision = result as { allowed?: unknown; message?: unknown; retryAfterSeconds?: unknown };
+			if (decision.allowed === false) {
+				return {
+					allowed: false,
+					...(typeof decision.message === 'string' ? { message: decision.message } : {}),
+					...(typeof decision.retryAfterSeconds === 'number' ? { retryAfterSeconds: decision.retryAfterSeconds } : {}),
+				};
+			}
+			return { allowed: true };
+		}
+		return result ? { allowed: true } : { allowed: false };
+	} catch (error) {
+		harperLogger.error(
+			`MCP ${info.profile} quota hook '${resourcePath}.${methodName}' threw; denying (fail-closed)`,
+			error
+		);
+		return { allowed: false, message: 'quota check failed' };
+	}
+}

package/components/mcp/rateLimit.ts

@@ -1,11 +1,20 @@
 /**
- * Per-session, per-tool rate limiting for `tools/call`.
+ * Per-session, per-tool, and per-client rate limiting for `tools/call`.
  *
- * Four configurable limits per profile (operations / application):
+ * Configurable limits per profile (operations / application):
  *   - perToolPerSecond:   sustained per-tool rate (token bucket refill)
  *   - perToolBurst:       per-tool burst capacity (token bucket size)
  *   - sessionConcurrency: max in-flight tool calls per session
  *   - sessionPerSecond:   sustained per-session rate across all tools
+ *   - perClientPerSecond / perClientBurst (#1610, default OFF): sustained
+ *     rate keyed on CLIENT IDENTITY rather than session. Session buckets are
+ *     trivially cycled by an anonymous client (initialize → call → drop
+ *     session → repeat); the client bucket survives that loop.
+ *   - identityHeader (#1610): identity is the socket IP by default; proxied
+ *     deployments can name a trusted header (e.g. `x-forwarded-for`) whose
+ *     first (client-most) value is used instead. Only set this when the
+ *     proxy strips the header from untrusted traffic — a client-controlled
+ *     header is a limit bypass.
  *
  * Limit hits surface as `result.isError = true` with `kind: 'rate_limited'`
  * (NOT a JSON-RPC error) per the MCP spec's tools-call convention. The LLM
@@ -14,21 +23,43 @@
  * State is in-memory per worker process. Buckets are evicted lazily when
  * a session's record is removed (#619 cleanup) or after they've been idle
  * past the idle eviction threshold. Multi-process coordination isn't
- * attempted in v1 — the limits are per-worker.
+ * attempted in v1 — the limits are per-worker. For durable cross-restart
+ * quotas (per-IP daily counters and the like), see the config-named quota
+ * hook in `quota.ts` (#1610).
  */
 import * as env from '../../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
 
 export interface RateLimitConfig {
 	perToolPerSecond: number;
 	perToolBurst: number;
 	sessionConcurrency: number;
 	sessionPerSecond: number;
+	/** 0 disables the per-client-identity bucket (the default). */
+	perClientPerSecond: number;
+	perClientBurst: number;
+	/** Trusted header (lowercased) to derive client identity from; absent = socket IP. */
+	identityHeader?: string;
 }
 
 const DEFAULTS: Record<'operations' | 'application', RateLimitConfig> = {
-	operations: { perToolPerSecond: 10, perToolBurst: 20, sessionConcurrency: 25, sessionPerSecond: 100 },
-	application: { perToolPerSecond: 25, perToolBurst: 50, sessionConcurrency: 50, sessionPerSecond: 200 },
+	operations: {
+		perToolPerSecond: 10,
+		perToolBurst: 20,
+		sessionConcurrency: 25,
+		sessionPerSecond: 100,
+		perClientPerSecond: 0,
+		perClientBurst: 0,
+	},
+	application: {
+		perToolPerSecond: 25,
+		perToolBurst: 50,
+		sessionConcurrency: 50,
+		sessionPerSecond: 200,
+		perClientPerSecond: 0,
+		perClientBurst: 0,
+	},
 };
 
 const CONFIG_KEYS = {
@@ -37,30 +68,91 @@ const CONFIG_KEYS = {
 		perToolBurst: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_PERTOOLBURST,
 		sessionConcurrency: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_SESSIONCONCURRENCY,
 		sessionPerSecond: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_SESSIONPERSECOND,
+		perClientPerSecond: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_PERCLIENTPERSECOND,
+		perClientBurst: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_PERCLIENTBURST,
+		identityHeader: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_IDENTITYHEADER,
 	},
 	application: {
 		perToolPerSecond: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_PERTOOLPERSECOND,
 		perToolBurst: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_PERTOOLBURST,
 		sessionConcurrency: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_SESSIONCONCURRENCY,
 		sessionPerSecond: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_SESSIONPERSECOND,
+		perClientPerSecond: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_PERCLIENTPERSECOND,
+		perClientBurst: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_PERCLIENTBURST,
+		identityHeader: CONFIG_PARAMS.MCP_APPLICATION_RATELIMIT_IDENTITYHEADER,
 	},
 };
 
+// tools/call is a hot path and `resolveClientIdentity` runs per call; reading
+// 6–7 env keys and allocating a config object each time is avoidable GC/CPU
+// pressure. Cache per profile with a short TTL — config edits still take
+// effect within seconds, matching the per-session capture semantics closely
+// enough while keeping the steady-state cost to a Map hit.
+const CONFIG_TTL_MS = 10_000;
+const configCache = new Map<string, { config: RateLimitConfig; at: number }>();
+let warnedIdentityHeader = false;
+
 export function configFor(profile: 'operations' | 'application'): RateLimitConfig {
+	const cached = configCache.get(profile);
+	const t = now();
+	if (cached && t - cached.at < CONFIG_TTL_MS) return cached.config;
+	const config = buildConfig(profile);
+	if (config.identityHeader && !warnedIdentityHeader) {
+		warnedIdentityHeader = true;
+		harperLogger.warn(
+			`MCP ${profile} rateLimit.identityHeader='${config.identityHeader}' derives client identity from a request header; ensure the fronting proxy STRIPS or REPLACES this header on untrusted traffic, or clients can spoof identities and bypass per-client limits`
+		);
+	}
+	configCache.set(profile, { config, at: t });
+	return config;
+}
+
+function buildConfig(profile: 'operations' | 'application'): RateLimitConfig {
 	const keys = CONFIG_KEYS[profile];
 	const defaults = DEFAULTS[profile];
 	const read = (key: string, fallback: number): number => {
 		const v = env.get(key);
 		return typeof v === 'number' && v > 0 ? v : fallback;
 	};
+	const identityHeader = env.get(keys.identityHeader);
+	const perClientPerSecond = read(keys.perClientPerSecond, defaults.perClientPerSecond);
 	return {
 		perToolPerSecond: read(keys.perToolPerSecond, defaults.perToolPerSecond),
 		perToolBurst: read(keys.perToolBurst, defaults.perToolBurst),
 		sessionConcurrency: read(keys.sessionConcurrency, defaults.sessionConcurrency),
 		sessionPerSecond: read(keys.sessionPerSecond, defaults.sessionPerSecond),
+		perClientPerSecond,
+		// Burst defaults to the sustained rate when unset, so enabling the
+		// limit is a one-key change — floored at 1 token, else a fractional
+		// rate (0.1/s = "6 per minute") yields a bucket that can never admit
+		// (consume requires a whole token and refill caps at burst).
+		perClientBurst: read(keys.perClientBurst, perClientPerSecond > 0 ? Math.max(1, perClientPerSecond) : 0),
+		...(typeof identityHeader === 'string' && identityHeader ? { identityHeader: identityHeader.toLowerCase() } : {}),
 	};
 }
 
+/**
+ * Derive the client identity for per-client limiting and the durable quota
+ * hook (#1610): the configured trusted header's first (client-most) value
+ * when set, else the transport-provided socket IP. Returns undefined when
+ * neither is available — callers skip client-scoped checks then.
+ */
+export function resolveClientIdentity(
+	headers: Record<string, string | undefined>,
+	clientIp: string | undefined,
+	profile: 'operations' | 'application'
+): string | undefined {
+	const config = configFor(profile);
+	if (config.identityHeader) {
+		const raw = headers[config.identityHeader];
+		if (raw) {
+			const first = raw.split(',')[0].trim();
+			if (first) return first;
+		}
+	}
+	return clientIp || undefined;
+}
+
 /**
  * Token bucket: starts full at `burst`, refills at `rate` tokens per
  * second up to `burst`, drained by `tryConsume(1)`. Stateless aside from
@@ -119,12 +211,21 @@ interface SessionState {
 
 const sessions = new Map<string, SessionState>();
 
+// Per-client-identity buckets, keyed `${profile}\n${identity}`. Deliberately
+// SEPARATE from session state: the whole point is surviving session cycling,
+// so their lifetime must not be tied to any session's (#1610).
+interface ClientState {
+	rate: TokenBucket;
+	lastSeen: number;
+}
+const clients = new Map<string, ClientState>();
+
 // Belt-and-braces against state leaks: sessions that get TTL-evicted from the
 // system.mcp_session table never reach deleteSession() in this process, so
 // `clearSessionRateState` is never called for them. Prune any session that
 // hasn't admitted a call in this many ms on every getOrCreate. The threshold
 // is generously above the default idle timeout (1800s) — well-behaved live
-// sessions never get pruned by accident.
+// sessions never get pruned by accident. Client buckets ride the same sweep.
 const IDLE_PRUNE_MS = 60 * 60 * 1000; // 1 hour
 const PRUNE_INTERVAL_MS = 5 * 60 * 1000; // run at most every 5 minutes
 let lastPruneAt = 0;
@@ -139,6 +240,11 @@ function pruneIdleSessions(): void {
 			sessions.delete(id);
 		}
 	}
+	for (const [key, c] of clients) {
+		if (c.lastSeen < cutoff) {
+			clients.delete(key);
+		}
+	}
 }
 
 function getOrCreate(sessionId: string, profile: 'operations' | 'application'): SessionState {
@@ -161,29 +267,53 @@ function getOrCreate(sessionId: string, profile: 'operations' | 'application'):
 	return s;
 }
 
+function getOrCreateClient(
+	identity: string,
+	profile: 'operations' | 'application',
+	config: RateLimitConfig
+): ClientState {
+	const key = `${profile}\n${identity}`;
+	let c = clients.get(key);
+	if (!c) {
+		c = { rate: new TokenBucket(config.perClientPerSecond, config.perClientBurst), lastSeen: now() };
+		clients.set(key, c);
+	} else {
+		c.lastSeen = now();
+	}
+	return c;
+}
+
 /** Drop a session's rate-limit state (called on session deletion). */
 export function clearSessionRateState(sessionId: string): void {
 	sessions.delete(sessionId);
 }
 
-/** Test seam: drop all sessions. */
+/** Test seam: drop all sessions, client buckets, and the config cache. */
 export function _resetForTest(): void {
 	sessions.clear();
+	clients.clear();
+	configCache.clear();
+	warnedIdentityHeader = false;
 }
 
 export type RateLimitDecision =
 	| { allowed: true; release: () => void }
-	| { allowed: false; reason: 'per_tool' | 'session_rate' | 'concurrency' };
+	| { allowed: false; reason: 'per_tool' | 'session_rate' | 'concurrency' | 'per_client' };
 
 /**
  * Attempt to admit a tools/call. If allowed, returns a `release()` that
  * decrements in-flight; the caller MUST invoke it (even on tool failure)
  * via `try { ... } finally { release(); }`.
+ *
+ * `clientIdentity` (from `resolveClientIdentity`) engages the per-client
+ * bucket when the profile configures `perClientPerSecond` — the scope that
+ * survives session cycling (#1610). Absent identity or a 0 rate skips it.
  */
 export function tryAdmit(
 	sessionId: string,
 	toolName: string,
-	profile: 'operations' | 'application'
+	profile: 'operations' | 'application',
+	clientIdentity?: string
 ): RateLimitDecision {
 	const state = getOrCreate(sessionId, profile);
 	if (state.inFlight >= state.config.sessionConcurrency) {
@@ -194,19 +324,27 @@ export function tryAdmit(
 		toolBucket = new TokenBucket(state.config.perToolPerSecond, state.config.perToolBurst);
 		state.perTool.set(toolName, toolBucket);
 	}
-	// Peek both buckets first. Consuming session-rate before checking per-tool
-	// (or vice versa) silently drains the unrelated bucket on the denied path.
+	const clientState =
+		state.config.perClientPerSecond > 0 && clientIdentity
+			? getOrCreateClient(clientIdentity, profile, state.config)
+			: undefined;
+	// Peek every bucket first. Consuming one before checking another silently
+	// drains the unrelated bucket on the denied path.
 	if (!toolBucket.hasToken()) {
 		return { allowed: false, reason: 'per_tool' };
 	}
 	if (!state.sessionRate.hasToken()) {
 		return { allowed: false, reason: 'session_rate' };
 	}
-	// Both have capacity — actually deduct. The peeks above ran refill(), so
-	// this immediate-follow-up tryConsume sees the same fresh state and is
-	// guaranteed to succeed (refill() is a no-op for elapsedSec ≤ 0).
+	if (clientState && !clientState.rate.hasToken()) {
+		return { allowed: false, reason: 'per_client' };
+	}
+	// All have capacity — actually deduct. The peeks above ran refill(), so
+	// these immediate-follow-up tryConsume calls see the same fresh state and
+	// are guaranteed to succeed (refill() is a no-op for elapsedSec ≤ 0).
 	toolBucket.tryConsume();
 	state.sessionRate.tryConsume();
+	clientState?.rate.tryConsume();
 	state.inFlight += 1;
 	return {
 		allowed: true,

package/components/mcp/resources.ts

@@ -393,8 +393,7 @@ export async function subscribeToResource(
 	} else {
 		const resourcesRegistry = getResources();
 		const entry = resourcesRegistry.getMatch(path, 'mcp') as
-			| { Resource: { subscribe?: (request: unknown, context: unknown) => unknown }; relativeURL?: string }
-			| undefined;
+			{ Resource: { subscribe?: (request: unknown, context: unknown) => unknown }; relativeURL?: string } | undefined;
 		const ResourceClass = entry?.Resource;
 		if (!entry || typeof ResourceClass?.subscribe !== 'function') return null;
 		// `getMatch` matched the Resource and put the remaining path (the record key,
@@ -461,8 +460,7 @@ function enumerateParamRouteTemplates(prefix: string): ResourceTemplate[] {
 	for (const route of getResources().paramRoutes ?? []) {
 		if (!isMcpExposed(route.entry)) continue;
 		const ResourceClass = route.entry.Resource as
-			| { prototype?: unknown; description?: string; hidden?: boolean }
-			| undefined;
+			{ prototype?: unknown; description?: string; hidden?: boolean } | undefined;
 		// @hidden suppresses the Resource from descriptive surfaces (MCP + OpenAPI).
 		if (ResourceClass?.hidden === true) continue;
 		if (!hasRestVerbs(ResourceClass?.prototype)) continue;