@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/components/mcp/listChanged.ts

@@ -0,0 +1,270 @@
+/**
+ * MCP server-push notification dispatcher (#619). Subscribes to Harper's
+ * existing role-cache-invalidation + schema-reload event channels and
+ * emits per-session `notifications/tools/list_changed` /
+ * `notifications/resources/list_changed` frames over the registered
+ * SSE streams.
+ *
+ * Per-session computation only — never broadcast. For each event, we
+ * walk the per-worker session registry, re-resolve the session's user
+ * (so the diff sees the freshly-mutated permission set, not the snapshot
+ * captured at GET-stream open), recompute that session's tools/list (or
+ * resources/list) under the fresh user, diff against the snapshot from
+ * the prior emission, and push a notification iff the visible set
+ * actually changed. Sessions whose visible surface is unchanged see
+ * nothing.
+ */
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import { listResources } from './resources.ts';
+import { type RegisteredSession, forEachSessionByProfile, getRegisteredSession } from './sessionRegistry.ts';
+import { listTools, type AuthedUser } from './toolRegistry.ts';
+import type { McpProfile } from './transport.ts';
+
+const MAX_TOOLS_PAGE = 1000;
+const MAX_RESOURCES_PAGE = 1000;
+
+let initialized = false;
+let onUserChangeBound: (() => void) | undefined;
+let onSchemaChangeBound: (() => void) | undefined;
+
+// Test seams: avoid importing the real ITC handler from unit tests.
+let _itcHandlersOverride:
+	| {
+			userHandler?: { addListener?: (fn: () => void) => void };
+			schemaHandler?: { addListener?: (fn: () => void) => void };
+	  }
+	| undefined;
+
+export function _setItcHandlersForTest(
+	h:
+		| {
+				userHandler?: { addListener?: (fn: () => void) => void };
+				schemaHandler?: { addListener?: (fn: () => void) => void };
+		  }
+		| undefined
+): void {
+	_itcHandlersOverride = h;
+}
+
+export function _resetListChangedForTest(): void {
+	initialized = false;
+	onUserChangeBound = undefined;
+	onSchemaChangeBound = undefined;
+}
+
+function loadItcHandlers():
+	| {
+			userHandler?: { addListener?: (fn: () => void) => void };
+			schemaHandler?: { addListener?: (fn: () => void) => void };
+	  }
+	| undefined {
+	if (_itcHandlersOverride) return _itcHandlersOverride;
+	try {
+		return require('../../server/itc/serverHandlers');
+	} catch (err) {
+		harperLogger.trace(`MCP listChanged: ITC handlers unavailable (${(err as Error).message})`);
+		return undefined;
+	}
+}
+
+// Test seam: lets unit tests stub the user re-resolution without pulling in
+// security/user.ts (which initializes the system catalogs at module-load).
+let _userResolverOverride: ((username: string) => Promise<AuthedUser | undefined>) | undefined;
+
+export function _setUserResolverForTest(fn: ((username: string) => Promise<AuthedUser | undefined>) | undefined): void {
+	_userResolverOverride = fn;
+}
+
+async function resolveUser(username: string | undefined): Promise<AuthedUser | undefined> {
+	if (!username) return undefined;
+	if (_userResolverOverride) return _userResolverOverride(username);
+	try {
+		const { findAndValidateUser } = require('../../security/user');
+		const fresh = await findAndValidateUser(username, null, false);
+		return fresh as AuthedUser;
+	} catch (err) {
+		harperLogger.trace(`MCP listChanged: user re-resolve failed for ${username}: ${(err as Error).message}`);
+		return undefined;
+	}
+}
+
+function toolsListNames(profile: McpProfile, session: RegisteredSession): Array<{ name: string }> {
+	const { tools } = listTools({
+		user: session.user,
+		profile,
+		sessionId: session.sessionId,
+		limit: MAX_TOOLS_PAGE,
+	});
+	return tools.map((t) => ({ name: t.name }));
+}
+
+function resourcesListUris(profile: McpProfile, session: RegisteredSession): Array<{ uri: string }> {
+	const result = listResources({ user: session.user, profile, limit: MAX_RESOURCES_PAGE });
+	return result.resources.map((r) => ({ uri: r.uri }));
+}
+
+function sameSet(
+	a: ReadonlyArray<{ name?: string; uri?: string }> | undefined,
+	b: ReadonlyArray<{ name?: string; uri?: string }>
+): boolean {
+	if (!a) return false;
+	if (a.length !== b.length) return false;
+	const aKeys = new Set(a.map((x) => x.name ?? x.uri));
+	for (const x of b) {
+		if (!aKeys.has(x.name ?? x.uri)) return false;
+	}
+	return true;
+}
+
+/**
+ * Re-emit `notifications/tools/list_changed` for one session iff its
+ * visible tools list has changed since the last snapshot. Wrapped in
+ * try/catch so a single failing session never breaks the loop.
+ */
+function maybeNotifyToolsChanged(record: RegisteredSession): void {
+	try {
+		const current = toolsListNames(record.profile, record);
+		if (sameSet(record.lastTools, current)) return;
+		record.lastTools = current;
+		record.queue.send({
+			event: 'message',
+			data: { jsonrpc: '2.0', method: 'notifications/tools/list_changed' },
+		});
+	} catch (err) {
+		harperLogger.trace(`MCP listChanged tools/* for session ${record.sessionId}: ${(err as Error).message}`);
+	}
+}
+
+function maybeNotifyResourcesChanged(record: RegisteredSession): void {
+	try {
+		const current = resourcesListUris(record.profile, record);
+		if (sameSet(record.lastResources, current)) return;
+		record.lastResources = current;
+		record.queue.send({
+			event: 'message',
+			data: { jsonrpc: '2.0', method: 'notifications/resources/list_changed' },
+		});
+	} catch (err) {
+		harperLogger.trace(`MCP listChanged resources/* for session ${record.sessionId}: ${(err as Error).message}`);
+	}
+}
+
+/**
+ * Snapshot the current registry as a flat list so re-resolves can happen
+ * sequentially without re-walking the live map (which a concurrent
+ * registerSession could mutate mid-iteration).
+ */
+function snapshotSessions(profile: McpProfile): RegisteredSession[] {
+	const out: RegisteredSession[] = [];
+	forEachSessionByProfile(profile, (r) => out.push(r));
+	return out;
+}
+
+async function refreshSessionUser(record: RegisteredSession): Promise<void> {
+	const fresh = await resolveUser(record.user?.username);
+	if (fresh) record.user = fresh;
+}
+
+/**
+ * Fan out a user/role change: for each session on either profile,
+ * re-resolve the user (so a role-perm mutation is visible to the diff —
+ * the captured `record.user` at GET-stream open is otherwise frozen),
+ * recompute the tools list and notify if changed. Resources may also
+ * change visibility (table-perm-gated schema URIs), so we re-check
+ * those too.
+ */
+async function onUserChange(): Promise<void> {
+	for (const r of snapshotSessions('operations')) {
+		await refreshSessionUser(r);
+		maybeNotifyToolsChanged(r);
+		maybeNotifyResourcesChanged(r);
+	}
+	for (const r of snapshotSessions('application')) {
+		await refreshSessionUser(r);
+		maybeNotifyToolsChanged(r);
+		maybeNotifyResourcesChanged(r);
+	}
+}
+
+/**
+ * Schema changes touch both surfaces — application-profile tools are
+ * generated from the Resources registry, and operations-profile
+ * resources include the OPERATION list (unchanged) plus harper://schema
+ * URIs (changed). Application sessions need the bigger refresh. We also
+ * re-resolve the user here in case the schema change coincided with a
+ * role mutation (Harper sometimes fires both channels on database-level
+ * grants).
+ */
+async function onSchemaChange(): Promise<void> {
+	for (const r of snapshotSessions('application')) {
+		await refreshSessionUser(r);
+		maybeNotifyToolsChanged(r);
+		maybeNotifyResourcesChanged(r);
+	}
+	// Operations sessions only need resources/list refresh — there are no
+	// schema-derived operations tools, but `harper://schema/...` URIs may
+	// shift if a new table appears under a database the user can describe.
+	for (const r of snapshotSessions('operations')) {
+		await refreshSessionUser(r);
+		maybeNotifyResourcesChanged(r);
+	}
+}
+
+/**
+ * Idempotent: subscribe once at component boot. Repeated calls are
+ * no-ops. Returns true if subscriptions were actually installed (false
+ * if Harper's ITC handlers aren't available in this process).
+ */
+export function initListChanged(): boolean {
+	if (initialized) return true;
+	const handlers = loadItcHandlers();
+	if (!handlers) return false;
+	let installed = 0;
+	if (handlers.userHandler?.addListener) {
+		// Harper's ITC handler treats listeners as `() => void`. Our handler is
+		// async (re-resolves users); fire-and-forget with a swallow so a rejection
+		// can never escape the event emitter as an UnhandledPromiseRejection.
+		onUserChangeBound = () => {
+			onUserChange().catch((err) => harperLogger.trace(`MCP listChanged onUserChange: ${(err as Error).message}`));
+		};
+		handlers.userHandler.addListener(onUserChangeBound);
+		installed++;
+	}
+	if (handlers.schemaHandler?.addListener) {
+		onSchemaChangeBound = () => {
+			onSchemaChange().catch((err) => harperLogger.trace(`MCP listChanged onSchemaChange: ${(err as Error).message}`));
+		};
+		handlers.schemaHandler.addListener(onSchemaChangeBound);
+		installed++;
+	}
+	initialized = installed > 0;
+	if (initialized) {
+		harperLogger.info(`MCP listChanged: subscribed to ${installed} event channel(s)`);
+	} else {
+		harperLogger.warn(
+			'MCP listChanged: ITC handlers do not expose addListener; list_changed notifications will not fire'
+		);
+	}
+	return initialized;
+}
+
+/**
+ * Compute and stash the initial tools/resources snapshot for a session
+ * that just opened its GET stream. Without this seed, the first event
+ * would always be a "changed" because `lastTools === undefined !==
+ * current`. Call right after registerSession.
+ */
+export function seedSessionSnapshot(sessionId: string): void {
+	const record = getRegisteredSession(sessionId);
+	if (!record) return;
+	try {
+		record.lastTools = toolsListNames(record.profile, record);
+	} catch (err) {
+		harperLogger.trace(`MCP seed tools list for ${sessionId}: ${(err as Error).message}`);
+	}
+	try {
+		record.lastResources = resourcesListUris(record.profile, record);
+	} catch (err) {
+		harperLogger.trace(`MCP seed resources list for ${sessionId}: ${(err as Error).message}`);
+	}
+}

package/components/mcp/rateLimit.ts

@@ -0,0 +1,217 @@
+/**
+ * Per-session, per-tool rate limiting for `tools/call`.
+ *
+ * Four 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
+ *
+ * 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
+ * sees and adapts; the protocol envelope stays clean.
+ *
+ * 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.
+ */
+import * as env from '../../utility/environment/environmentManager.ts';
+import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
+
+export interface RateLimitConfig {
+	perToolPerSecond: number;
+	perToolBurst: number;
+	sessionConcurrency: number;
+	sessionPerSecond: number;
+}
+
+const DEFAULTS: Record<'operations' | 'application', RateLimitConfig> = {
+	operations: { perToolPerSecond: 10, perToolBurst: 20, sessionConcurrency: 25, sessionPerSecond: 100 },
+	application: { perToolPerSecond: 25, perToolBurst: 50, sessionConcurrency: 50, sessionPerSecond: 200 },
+};
+
+const CONFIG_KEYS = {
+	operations: {
+		perToolPerSecond: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_PERTOOLPERSECOND,
+		perToolBurst: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_PERTOOLBURST,
+		sessionConcurrency: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_SESSIONCONCURRENCY,
+		sessionPerSecond: CONFIG_PARAMS.MCP_OPERATIONS_RATELIMIT_SESSIONPERSECOND,
+	},
+	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,
+	},
+};
+
+export function configFor(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;
+	};
+	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),
+	};
+}
+
+/**
+ * Token bucket: starts full at `burst`, refills at `rate` tokens per
+ * second up to `burst`, drained by `tryConsume(1)`. Stateless aside from
+ * `tokens` + `lastRefill`, both updated on every consume call.
+ */
+class TokenBucket {
+	private readonly rate: number;
+	private readonly burst: number;
+	private tokens: number;
+	private lastRefill: number;
+	constructor(rate: number, burst: number) {
+		this.rate = rate;
+		this.burst = burst;
+		this.tokens = burst;
+		this.lastRefill = now();
+	}
+	tryConsume(): boolean {
+		this.refill();
+		if (this.tokens >= 1) {
+			this.tokens -= 1;
+			return true;
+		}
+		return false;
+	}
+	/**
+	 * Refill-and-check, without consuming. Used by `tryAdmit` to peek each
+	 * bucket so denial doesn't burn a token in *another* bucket.
+	 */
+	hasToken(): boolean {
+		this.refill();
+		return this.tokens >= 1;
+	}
+	private refill(): void {
+		const t = now();
+		const elapsedSec = (t - this.lastRefill) / 1000;
+		this.lastRefill = t;
+		if (elapsedSec <= 0) return;
+		this.tokens = Math.min(this.burst, this.tokens + elapsedSec * this.rate);
+	}
+}
+
+/** Lazily monkey-patchable for tests. */
+let now: () => number = () => Date.now();
+export function _setClockForTest(fn: (() => number) | undefined): void {
+	now = fn ?? (() => Date.now());
+}
+
+interface SessionState {
+	perTool: Map<string, TokenBucket>;
+	sessionRate: TokenBucket;
+	inFlight: number;
+	config: RateLimitConfig;
+	profile: 'operations' | 'application';
+	lastSeen: number;
+}
+
+const sessions = new Map<string, SessionState>();
+
+// 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.
+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;
+
+function pruneIdleSessions(): void {
+	const t = now();
+	if (t - lastPruneAt < PRUNE_INTERVAL_MS) return;
+	lastPruneAt = t;
+	const cutoff = t - IDLE_PRUNE_MS;
+	for (const [id, s] of sessions) {
+		if (s.inFlight === 0 && s.lastSeen < cutoff) {
+			sessions.delete(id);
+		}
+	}
+}
+
+function getOrCreate(sessionId: string, profile: 'operations' | 'application'): SessionState {
+	pruneIdleSessions();
+	let s = sessions.get(sessionId);
+	if (!s) {
+		const config = configFor(profile);
+		s = {
+			perTool: new Map(),
+			sessionRate: new TokenBucket(config.sessionPerSecond, config.sessionPerSecond),
+			inFlight: 0,
+			config,
+			profile,
+			lastSeen: now(),
+		};
+		sessions.set(sessionId, s);
+	} else {
+		s.lastSeen = now();
+	}
+	return s;
+}
+
+/** 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. */
+export function _resetForTest(): void {
+	sessions.clear();
+}
+
+export type RateLimitDecision =
+	| { allowed: true; release: () => void }
+	| { allowed: false; reason: 'per_tool' | 'session_rate' | 'concurrency' };
+
+/**
+ * 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(); }`.
+ */
+export function tryAdmit(
+	sessionId: string,
+	toolName: string,
+	profile: 'operations' | 'application'
+): RateLimitDecision {
+	const state = getOrCreate(sessionId, profile);
+	if (state.inFlight >= state.config.sessionConcurrency) {
+		return { allowed: false, reason: 'concurrency' };
+	}
+	let toolBucket = state.perTool.get(toolName);
+	if (!toolBucket) {
+		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.
+	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).
+	toolBucket.tryConsume();
+	state.sessionRate.tryConsume();
+	state.inFlight += 1;
+	return {
+		allowed: true,
+		release: () => {
+			if (state.inFlight > 0) state.inFlight -= 1;
+		},
+	};
+}