@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/components/mcp/session.ts

@@ -0,0 +1,151 @@
+/**
+ * MCP session store backed by the `system.mcp_session` Harper table.
+ *
+ * Eviction is delegated to Harper's native TTL (`Table.setTTLExpiration`):
+ * every write to a session record updates its `version`, which Harper uses
+ * to determine expiration. So calling `saveSession(record)` on each request
+ * gives sliding-window idle semantics for free — no custom timer, no sweep.
+ *
+ * Spec: when a request bears an `Mcp-Session-Id` the server doesn't
+ * recognize (expired, terminated, or unknown), the server MUST return HTTP
+ * 404 so the client can re-`initialize`. That decision lives in the
+ * transport core; this module only reports `null` for "not found".
+ */
+import { v4 as uuid } from 'uuid';
+import { table, type Table } from '../../resources/databases.ts';
+import * as env from '../../utility/environment/environmentManager.ts';
+import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import { clearSessionRateState } from './rateLimit.ts';
+import { unregisterSession } from './sessionRegistry.ts';
+import { clearSessionCache } from './toolRegistry.ts';
+
+const TABLE_NAME = 'mcp_session';
+const DATABASE_NAME = 'system';
+
+/** Default idle timeout when `mcp.session.idleTimeoutSeconds` is omitted. */
+const DEFAULT_IDLE_TIMEOUT_SECONDS = 1800;
+
+/**
+ * Window between expiration and physical eviction. Short, but long enough
+ * to absorb clock skew and let a late client request resolve to a tombstone
+ * 404 rather than a "session never existed" 404. (The client recovery path
+ * is identical either way.)
+ */
+const EVICTION_WINDOW_SECONDS = 60;
+
+export interface McpSessionRecord {
+	id: string;
+	protocolVersion: string;
+	initialized: boolean;
+	user: string;
+	createdAt: number;
+	lastActivity: number;
+}
+
+let _sessionTable: Table | undefined;
+
+/**
+ * Lazily declare the system table. Called by `ensureSessionTable()` at
+ * component-init. Declaring lazily lets unit tests that don't boot a real
+ * Harper instance skip the table entirely.
+ */
+function declareSessionTable(): Table {
+	const idleTimeoutSeconds =
+		(env.get(CONFIG_PARAMS.MCP_SESSION_IDLETIMEOUTSECONDS) as number | undefined) ?? DEFAULT_IDLE_TIMEOUT_SECONDS;
+	return table<Table>({
+		table: TABLE_NAME,
+		database: DATABASE_NAME,
+		expiration: idleTimeoutSeconds,
+		eviction: idleTimeoutSeconds + EVICTION_WINDOW_SECONDS,
+		attributes: [
+			{ name: 'id', isPrimaryKey: true },
+			{ name: 'protocolVersion' },
+			{ name: 'initialized' },
+			{ name: 'user' },
+			{ name: 'createdAt' },
+			{ name: 'lastActivity' },
+		],
+	});
+}
+
+/**
+ * Initialize the session table. Called from `handleApplication(scope)` and
+ * `registerMcpProfile()` when the MCP component boots. Idempotent.
+ */
+export function ensureSessionTable(): Table {
+	if (!_sessionTable) {
+		_sessionTable = declareSessionTable();
+		harperLogger.trace(`MCP session table system.${TABLE_NAME} initialized`);
+	}
+	return _sessionTable;
+}
+
+/** Test seam: allow tests to inject a fake table without touching Harper. */
+export function _setSessionTableForTest(fake: Table | undefined): void {
+	_sessionTable = fake;
+}
+
+function getTable(): Table {
+	if (!_sessionTable) throw new Error('MCP session table not initialized');
+	return _sessionTable;
+}
+
+export async function createSession({
+	user,
+	protocolVersion,
+}: {
+	user: string;
+	protocolVersion: string;
+}): Promise<McpSessionRecord> {
+	const now = Date.now();
+	const record: McpSessionRecord = {
+		id: uuid(),
+		protocolVersion,
+		initialized: false,
+		user,
+		createdAt: now,
+		lastActivity: now,
+	};
+	await (getTable() as any).put(record);
+	return record;
+}
+
+/**
+ * Look up a session by id. Returns the record if present and not expired,
+ * else `null`. The transport core maps `null` to HTTP 404.
+ */
+export async function loadSession(id: string): Promise<McpSessionRecord | null> {
+	const record = (await (getTable() as any).get(id)) as McpSessionRecord | undefined | null;
+	if (!record) return null;
+	return record;
+}
+
+/**
+ * Persist updated session state. Used to bump `lastActivity` (sliding-window
+ * idle reset) and to flip `initialized` after `notifications/initialized`.
+ */
+export async function saveSession(record: McpSessionRecord): Promise<void> {
+	await (getTable() as any).put(record);
+}
+
+export async function deleteSession(id: string): Promise<void> {
+	await (getTable() as any).delete(id);
+	// Tear down ancillary per-session in-memory state — the `tools/list`
+	// pagination cache and the per-session rate-limit buckets. Without
+	// these, every session that ever paged or called a tool leaves orphan
+	// entries until the process restarts.
+	clearSessionCache(id);
+	clearSessionRateState(id);
+	unregisterSession(id);
+}
+
+/**
+ * Convenience: touch `lastActivity` and persist. Returns the updated
+ * record so the caller doesn't re-fetch.
+ */
+export async function touchSession(record: McpSessionRecord): Promise<McpSessionRecord> {
+	const touched: McpSessionRecord = { ...record, lastActivity: Date.now() };
+	await saveSession(touched);
+	return touched;
+}

package/components/mcp/sessionRegistry.ts

@@ -0,0 +1,140 @@
+/**
+ * Per-worker in-memory registry of active MCP sessions with open GET-SSE
+ * streams. The persistent session record lives in `system.mcp_session`
+ * (RocksDB); this registry holds the things that can't be persisted —
+ * the live IterableEventQueue, plus per-session snapshots of the last
+ * `tools/list` / `resources/list` results so the listChanged dispatcher
+ * can suppress no-op notifications.
+ *
+ * Per-worker only. A session's GET stream is bound to the worker that
+ * accepted the GET; cross-worker fan-out isn't attempted in v1.
+ *
+ * Lifecycle: an entry is created on GET-SSE open and removed via three
+ * paths — explicit DELETE (transport calls `deleteSession`), the on-close
+ * hook fired when the consumer's async-iterator returns/throws (e.g.
+ * client drop), or the idle-prune sweep that catches zombies the close
+ * hook missed (e.g. a proxy holding the connection after the client died
+ * without a graceful close).
+ */
+import { IterableEventQueue } from '../../resources/IterableEventQueue.ts';
+import type { AuthedUser } from './toolRegistry.ts';
+import type { McpProfile } from './transport.ts';
+
+export interface SseEvent {
+	event?: string;
+	data?: unknown;
+	id?: string;
+}
+
+export interface RegisteredSession {
+	sessionId: string;
+	profile: McpProfile;
+	user: AuthedUser;
+	queue: IterableEventQueue<SseEvent>;
+	/** Most recent tools/list payload sent on this session — used for diffing. */
+	lastTools?: ReadonlyArray<{ name: string }>;
+	/** Most recent resources/list payload sent on this session — used for diffing. */
+	lastResources?: ReadonlyArray<{ uri: string }>;
+	/** Wall-clock ms of last activity. Bumped by registerSession + touchSession. */
+	lastSeen: number;
+}
+
+const registry: Map<string, RegisteredSession> = new Map();
+
+const IDLE_PRUNE_MS = 60 * 60 * 1000;
+const PRUNE_INTERVAL_MS = 5 * 60 * 1000;
+let lastPruneAt = 0;
+
+let now: () => number = () => Date.now();
+export function _setClockForTest(fn: (() => number) | undefined): void {
+	now = fn ?? (() => Date.now());
+}
+
+function pruneIdleSessions(): void {
+	const t = now();
+	if (t - lastPruneAt < PRUNE_INTERVAL_MS) return;
+	lastPruneAt = t;
+	const cutoff = t - IDLE_PRUNE_MS;
+	for (const [id, record] of registry) {
+		// Don't prune sessions whose iterator is actively awaiting data; that
+		// signals a live consumer mid-stream. Belt-and-braces around lastSeen.
+		if (record.queue.resolveNext !== null) continue;
+		if (record.lastSeen < cutoff) {
+			record.queue.emit('close');
+			registry.delete(id);
+		}
+	}
+}
+
+export function registerSession(sessionId: string, profile: McpProfile, user: AuthedUser): RegisteredSession {
+	pruneIdleSessions();
+	const existing = registry.get(sessionId);
+	if (existing) {
+		// A client that opens a second GET on the same session id supersedes
+		// the first. Close the prior stream so callers don't dangle.
+		existing.queue.emit('close');
+	}
+	const queue = new IterableEventQueue<SseEvent>();
+	const record: RegisteredSession = { sessionId, profile, user, queue, lastSeen: now() };
+	registry.set(sessionId, record);
+	// On-close hook: when the consumer's async-iterator returns/throws (or
+	// supersede emits 'close' above), drop the entry so it doesn't leak past
+	// the underlying HTTP stream's lifetime. We delete directly rather than
+	// calling unregisterSession() — the latter would re-emit 'close', firing
+	// any other user-registered 'close' listeners a second time.
+	queue.once('close', () => {
+		// Only delete if we're still the live record. A racing supersede
+		// could have already replaced us in the map.
+		if (registry.get(sessionId) === record) {
+			registry.delete(sessionId);
+		}
+	});
+	return record;
+}
+
+export function unregisterSession(sessionId: string): void {
+	const record = registry.get(sessionId);
+	if (!record) return;
+	registry.delete(sessionId);
+	record.queue.emit('close');
+}
+
+export function getRegisteredSession(sessionId: string): RegisteredSession | undefined {
+	return registry.get(sessionId);
+}
+
+/**
+ * Mark a session as having activity right now (e.g. a `tools/call` came in).
+ * Keeps idle-prune from sweeping live sessions whose GET stream is dormant
+ * between server-push events. Distinct from `session.touchSession` — that
+ * one updates the persistent RocksDB record's `lastActivity`; this one
+ * updates the in-memory registry's `lastSeen` (used only by the idle-prune).
+ */
+export function touchRegisteredSession(sessionId: string): void {
+	const record = registry.get(sessionId);
+	if (record) record.lastSeen = now();
+}
+
+/**
+ * Apply a callback to every session matching `profile`. Used by the
+ * listChanged dispatcher to recompute lists per-session.
+ */
+export function forEachSessionByProfile(profile: McpProfile, cb: (record: RegisteredSession) => void): void {
+	for (const record of registry.values()) {
+		if (record.profile === profile) cb(record);
+	}
+}
+
+/** Test seam — drop all sessions. */
+export function _resetSessionRegistryForTest(): void {
+	for (const r of registry.values()) {
+		r.queue.emit('close');
+	}
+	registry.clear();
+	lastPruneAt = 0;
+}
+
+/** Test seam — peek count. */
+export function _sessionRegistrySize(): number {
+	return registry.size;
+}

package/components/mcp/toolRegistry.ts

@@ -0,0 +1,292 @@
+/**
+ * MCP tool registry — framework for `tools/list` and `tools/call` per MCP
+ * §server/tools. No real tools register here yet — the operations profile
+ * walks `OPERATION_FUNCTION_MAP`, and the application profile walks the
+ * `Resources` registry. Both call `addTool(def)` to publish.
+ *
+ * Filtering follows a two-step pattern:
+ *   1. Class-level verb introspection (which tools are *publishable*)
+ *      reuses the prototype-comparison helper from `resources/openApi.ts:149-153`.
+ *   2. User-level RBAC walk (which publishable tools are *visible*) reuses
+ *      the direct `user.role.permission[db].tables[table]` walk from
+ *      `dataLayer/schemaDescribe.ts:29-49`. Resource.allow* methods are
+ *      *not* used — they're per-record instance methods.
+ *
+ * Security model — important:
+ *   - `visibleTo` controls **listing** (the LLM only sees what it's likely
+ *     allowed to use). It is **not** invoked at `tools/call` time and is
+ *     explicitly NOT a security boundary.
+ *   - **Enforcement runs in the tool handler at call time**, via Harper's
+ *     existing `transactional()` + per-record `allow{Read,Create,Update,
+ *     Delete}` predicates. The framework intentionally passes a
+ *     known-but-filtered-out tool through to its handler so an LLM that
+ *     hallucinates a name gets a clean `isError` result from the runtime
+ *     predicate. See the `tools/call` pass-through test in
+ *     `transport.test.js`.
+ */
+import type { McpProfile } from './transport.ts';
+
+export interface ToolAnnotations {
+	title?: string;
+	readOnlyHint?: boolean;
+	destructiveHint?: boolean;
+	idempotentHint?: boolean;
+	openWorldHint?: boolean;
+}
+
+export interface ToolContent {
+	type: 'text' | 'image' | 'audio' | 'resource';
+	text?: string;
+	data?: string;
+	mimeType?: string;
+}
+
+export interface ToolResult {
+	content: ToolContent[];
+	isError?: boolean;
+	structuredContent?: unknown;
+}
+
+/** Public shape sent to clients on `tools/list`. */
+export interface ToolDescriptor {
+	name: string;
+	description: string;
+	inputSchema: object;
+	annotations?: ToolAnnotations;
+}
+
+/** Authenticated user object as Harper builds it (subset we touch). */
+export interface AuthedUser {
+	username?: string;
+	role?: {
+		role?: string;
+		permission?: {
+			super_user?: boolean;
+			structure_user?: boolean;
+			operations?: string[];
+			[database: string]:
+				| boolean
+				| string[]
+				| undefined
+				| {
+						describe?: boolean;
+						tables?: {
+							[table: string]:
+								| undefined
+								| {
+										read?: boolean;
+										insert?: boolean;
+										update?: boolean;
+										delete?: boolean;
+										describe?: boolean;
+										attribute_permissions?: unknown;
+								  };
+						};
+				  };
+		};
+	};
+}
+
+export interface ToolCallContext {
+	user: AuthedUser;
+	profile: McpProfile;
+	sessionId: string;
+}
+
+/**
+ * Internal tool definition. `handler` and `visibleTo` are not sent to the
+ * client; only the public `ToolDescriptor` fields are.
+ */
+export interface ToolDef extends ToolDescriptor {
+	profile: McpProfile;
+	visibleTo: (user: AuthedUser) => boolean;
+	handler: (args: unknown, context: ToolCallContext) => Promise<ToolResult> | ToolResult;
+}
+
+const registry = new Map<string, ToolDef>();
+
+/** Per-session pagination cache. Invalidated when a fresh `tools/list` (no cursor) call recomputes. */
+const sessionListCache = new Map<string, { tools: ToolDescriptor[] }>();
+
+export function addTool(def: ToolDef): void {
+	if (!def?.name) throw new Error('addTool: name is required');
+	registry.set(def.name, def);
+	// New tool → drop pagination caches; next list call rebuilds.
+	sessionListCache.clear();
+}
+
+export function removeTool(name: string): boolean {
+	const existed = registry.delete(name);
+	if (existed) sessionListCache.clear();
+	return existed;
+}
+
+export function getTool(name: string): ToolDef | undefined {
+	return registry.get(name);
+}
+
+/**
+ * Drop the pagination cache entry for a session. Called by
+ * `session.deleteSession` so the cache doesn't outlive the session that
+ * created it. Without this, every session that ever paged tools/list
+ * leaves an orphan entry until the process restarts.
+ */
+export function clearSessionCache(sessionId: string): void {
+	sessionListCache.delete(sessionId);
+}
+
+/** Test seam: drop all registrations. */
+export function _resetRegistryForTest(): void {
+	registry.clear();
+	sessionListCache.clear();
+}
+
+export interface ListToolsArgs {
+	user: AuthedUser;
+	profile: McpProfile;
+	sessionId: string;
+	cursor?: string;
+	limit: number;
+}
+
+export interface ListToolsResult {
+	tools: ToolDescriptor[];
+	nextCursor?: string;
+}
+
+/**
+ * Filter the registry to tools the user can see on this profile, then page.
+ *
+ * Cursor encoding: base64 of `{offset:N}`. Opaque to clients per MCP
+ * §server/utilities/pagination. A fresh call (no cursor) recomputes and
+ * caches the filtered list; subsequent paged calls reuse the cache so
+ * pagination is stable even if the registry mutates between pages.
+ */
+export function listTools(args: ListToolsArgs): ListToolsResult {
+	const { user, profile, sessionId, cursor, limit } = args;
+	if (limit < 1) throw new Error('listTools: limit must be >= 1');
+
+	let cached = sessionListCache.get(sessionId);
+	let offset = 0;
+	if (cursor) {
+		offset = decodeCursor(cursor);
+		if (!cached) {
+			// Cache evicted (likely registry change). Treat as a fresh call from
+			// the cursor's offset — best effort. The client may see the next
+			// page from a slightly different list, which is acceptable per
+			// MCP's eventual-consistency stance on listChanged.
+			cached = { tools: computeFilteredList(user, profile) };
+			sessionListCache.set(sessionId, cached);
+		}
+	} else {
+		cached = { tools: computeFilteredList(user, profile) };
+		sessionListCache.set(sessionId, cached);
+	}
+
+	const slice = cached.tools.slice(offset, offset + limit);
+	const next = offset + slice.length;
+	return {
+		tools: slice,
+		nextCursor: next < cached.tools.length ? encodeCursor(next) : undefined,
+	};
+}
+
+function computeFilteredList(user: AuthedUser, profile: McpProfile): ToolDescriptor[] {
+	const out: ToolDescriptor[] = [];
+	for (const def of registry.values()) {
+		if (def.profile !== profile) continue;
+		if (!def.visibleTo(user)) continue;
+		out.push({
+			name: def.name,
+			description: def.description,
+			inputSchema: def.inputSchema,
+			...(def.annotations ? { annotations: def.annotations } : {}),
+		});
+	}
+	// Sort for deterministic pagination (insertion order would also work, but
+	// the registry can mutate between calls and we want stable cursor offsets).
+	out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+	return out;
+}
+
+function encodeCursor(offset: number): string {
+	return Buffer.from(JSON.stringify({ offset }), 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor: string): number {
+	try {
+		const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as { offset?: unknown };
+		const offset = decoded?.offset;
+		if (typeof offset !== 'number' || offset < 0 || !Number.isFinite(offset) || !Number.isInteger(offset)) {
+			return 0;
+		}
+		return offset;
+	} catch {
+		return 0;
+	}
+}
+
+// ─── RBAC + introspection helpers ──────────────────────────────────────────
+
+/** True if any role-level flag grants super-user privilege. */
+export function isSuperUser(user: AuthedUser | undefined): boolean {
+	return user?.role?.permission?.super_user === true;
+}
+
+/**
+ * Class-level verb introspection. Mirrors `resources/openApi.ts:149-153` so
+ * a class is considered to "have" a verb only if its prototype overrides the
+ * base Resource implementation. Note that `post`'s default in Harper's
+ * `Resource` is a no-op that ResourceClass implementations frequently
+ * override implicitly via `update` — the openApi pattern accounts for that.
+ */
+export function hasClassLevelVerbs(
+	prototype: any,
+	resourcePrototype: any
+): { get: boolean; post: boolean; put: boolean; patch: boolean; delete: boolean } {
+	return {
+		get: typeof prototype.get === 'function' && prototype.get !== resourcePrototype.get,
+		post:
+			(typeof prototype.post === 'function' && prototype.post !== resourcePrototype.post) ||
+			typeof prototype.update === 'function',
+		put: typeof prototype.put === 'function' && prototype.put !== resourcePrototype.put,
+		patch: typeof prototype.patch === 'function' && prototype.patch !== resourcePrototype.patch,
+		delete: typeof prototype.delete === 'function' && prototype.delete !== resourcePrototype.delete,
+	};
+}
+
+/**
+ * Role-level operations check for the operations profile. Returns true if
+ * the user has the role-level privilege required to invoke `operation`,
+ * regardless of any per-call schema/table predicate (those run at tool-call
+ * time).
+ *
+ * The implementation here is intentionally conservative — only flags that
+ * grant operations globally short-circuit. Per-operation per-target checks
+ * are evaluated at call time by Harper's existing `verifyPerms`.
+ */
+export function canRoleInvokeOperation(user: AuthedUser, operation: string): boolean {
+	if (isSuperUser(user)) return true;
+	const perm = user?.role?.permission;
+	if (!perm) return false;
+	if (perm.structure_user && SCHEMA_STRUCTURE_OPERATIONS.has(operation)) return true;
+	if (Array.isArray(perm.operations) && perm.operations.includes(operation)) return true;
+	return false;
+}
+
+/**
+ * Operations that `structure_user` is permitted to invoke. Pre-seeded with
+ * the canonical structure ops so the helper is functional and tests have
+ * something to assert against. Adding entries here is the right shape;
+ * removing them is not (would silently lock users out).
+ */
+const SCHEMA_STRUCTURE_OPERATIONS = new Set([
+	'create_schema',
+	'create_database',
+	'drop_schema',
+	'drop_database',
+	'create_table',
+	'drop_table',
+	'create_attribute',
+	'drop_attribute',
+]);