@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/dist/components/mcp/session.js

@@ -0,0 +1,170 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSessionTable = ensureSessionTable;
+exports._setSessionTableForTest = _setSessionTableForTest;
+exports.createSession = createSession;
+exports.loadSession = loadSession;
+exports.saveSession = saveSession;
+exports.deleteSession = deleteSession;
+exports.touchSession = touchSession;
+/**
+ * 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".
+ */
+const uuid_1 = require("uuid");
+const databases_ts_1 = require("../../resources/databases.js");
+const env = __importStar(require("../../utility/environment/environmentManager.js"));
+const hdbTerms_ts_1 = require("../../utility/hdbTerms.js");
+const harper_logger_ts_1 = __importDefault(require("../../utility/logging/harper_logger.js"));
+const rateLimit_ts_1 = require("./rateLimit.js");
+const sessionRegistry_ts_1 = require("./sessionRegistry.js");
+const toolRegistry_ts_1 = require("./toolRegistry.js");
+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;
+let _sessionTable;
+/**
+ * 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() {
+    const idleTimeoutSeconds = env.get(hdbTerms_ts_1.CONFIG_PARAMS.MCP_SESSION_IDLETIMEOUTSECONDS) ?? DEFAULT_IDLE_TIMEOUT_SECONDS;
+    return (0, databases_ts_1.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.
+ */
+function ensureSessionTable() {
+    if (!_sessionTable) {
+        _sessionTable = declareSessionTable();
+        harper_logger_ts_1.default.trace(`MCP session table system.${TABLE_NAME} initialized`);
+    }
+    return _sessionTable;
+}
+/** Test seam: allow tests to inject a fake table without touching Harper. */
+function _setSessionTableForTest(fake) {
+    _sessionTable = fake;
+}
+function getTable() {
+    if (!_sessionTable)
+        throw new Error('MCP session table not initialized');
+    return _sessionTable;
+}
+async function createSession({ user, protocolVersion, }) {
+    const now = Date.now();
+    const record = {
+        id: (0, uuid_1.v4)(),
+        protocolVersion,
+        initialized: false,
+        user,
+        createdAt: now,
+        lastActivity: now,
+    };
+    await getTable().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.
+ */
+async function loadSession(id) {
+    const record = (await getTable().get(id));
+    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`.
+ */
+async function saveSession(record) {
+    await getTable().put(record);
+}
+async function deleteSession(id) {
+    await getTable().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.
+    (0, toolRegistry_ts_1.clearSessionCache)(id);
+    (0, rateLimit_ts_1.clearSessionRateState)(id);
+    (0, sessionRegistry_ts_1.unregisterSession)(id);
+}
+/**
+ * Convenience: touch `lastActivity` and persist. Returns the updated
+ * record so the caller doesn't re-fetch.
+ */
+async function touchSession(record) {
+    const touched = { ...record, lastActivity: Date.now() };
+    await saveSession(touched);
+    return touched;
+}
+//# sourceMappingURL=session.js.map

package/dist/components/mcp/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../components/mcp/session.ts"],"names":[],"mappings":"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"}

package/dist/components/mcp/sessionRegistry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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;
+}
+export declare function _setClockForTest(fn: (() => number) | undefined): void;
+export declare function registerSession(sessionId: string, profile: McpProfile, user: AuthedUser): RegisteredSession;
+export declare function unregisterSession(sessionId: string): void;
+export declare function getRegisteredSession(sessionId: string): RegisteredSession | undefined;
+/**
+ * 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 declare function touchRegisteredSession(sessionId: string): void;
+/**
+ * Apply a callback to every session matching `profile`. Used by the
+ * listChanged dispatcher to recompute lists per-session.
+ */
+export declare function forEachSessionByProfile(profile: McpProfile, cb: (record: RegisteredSession) => void): void;
+/** Test seam — drop all sessions. */
+export declare function _resetSessionRegistryForTest(): void;
+/** Test seam — peek count. */
+export declare function _sessionRegistrySize(): number;

package/dist/components/mcp/sessionRegistry.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._setClockForTest = _setClockForTest;
+exports.registerSession = registerSession;
+exports.unregisterSession = unregisterSession;
+exports.getRegisteredSession = getRegisteredSession;
+exports.touchRegisteredSession = touchRegisteredSession;
+exports.forEachSessionByProfile = forEachSessionByProfile;
+exports._resetSessionRegistryForTest = _resetSessionRegistryForTest;
+exports._sessionRegistrySize = _sessionRegistrySize;
+/**
+ * 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).
+ */
+const IterableEventQueue_ts_1 = require("../../resources/IterableEventQueue.js");
+const registry = new Map();
+const IDLE_PRUNE_MS = 60 * 60 * 1000;
+const PRUNE_INTERVAL_MS = 5 * 60 * 1000;
+let lastPruneAt = 0;
+let now = () => Date.now();
+function _setClockForTest(fn) {
+    now = fn ?? (() => Date.now());
+}
+function pruneIdleSessions() {
+    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);
+        }
+    }
+}
+function registerSession(sessionId, profile, user) {
+    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_ts_1.IterableEventQueue();
+    const record = { 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;
+}
+function unregisterSession(sessionId) {
+    const record = registry.get(sessionId);
+    if (!record)
+        return;
+    registry.delete(sessionId);
+    record.queue.emit('close');
+}
+function getRegisteredSession(sessionId) {
+    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).
+ */
+function touchRegisteredSession(sessionId) {
+    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.
+ */
+function forEachSessionByProfile(profile, cb) {
+    for (const record of registry.values()) {
+        if (record.profile === profile)
+            cb(record);
+    }
+}
+/** Test seam — drop all sessions. */
+function _resetSessionRegistryForTest() {
+    for (const r of registry.values()) {
+        r.queue.emit('close');
+    }
+    registry.clear();
+    lastPruneAt = 0;
+}
+/** Test seam — peek count. */
+function _sessionRegistrySize() {
+    return registry.size;
+}
+//# sourceMappingURL=sessionRegistry.js.map

package/dist/components/mcp/sessionRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionRegistry.js","sourceRoot":"","sources":["../../../components/mcp/sessionRegistry.ts"],"names":[],"mappings":"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"}

package/dist/components/mcp/toolRegistry.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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;
+}
+export declare function addTool(def: ToolDef): void;
+export declare function removeTool(name: string): boolean;
+export declare function getTool(name: string): ToolDef | undefined;
+/**
+ * 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 declare function clearSessionCache(sessionId: string): void;
+/** Test seam: drop all registrations. */
+export declare function _resetRegistryForTest(): void;
+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 declare function listTools(args: ListToolsArgs): ListToolsResult;
+/** True if any role-level flag grants super-user privilege. */
+export declare function isSuperUser(user: AuthedUser | undefined): boolean;
+/**
+ * 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 declare function hasClassLevelVerbs(prototype: any, resourcePrototype: any): {
+    get: boolean;
+    post: boolean;
+    put: boolean;
+    patch: boolean;
+    delete: boolean;
+};
+/**
+ * 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 declare function canRoleInvokeOperation(user: AuthedUser, operation: string): boolean;