@harperfast/harper-pro 5.0.30 → 5.1.0-beta.2

package/dist/core/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/core/components/mcp/session.js.map

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

package/dist/core/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/core/components/mcp/sessionRegistry.js.map

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

package/dist/core/components/mcp/toolRegistry.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTool = addTool;
+exports.removeTool = removeTool;
+exports.getTool = getTool;
+exports.clearSessionCache = clearSessionCache;
+exports._resetRegistryForTest = _resetRegistryForTest;
+exports.listTools = listTools;
+exports.isSuperUser = isSuperUser;
+exports.hasClassLevelVerbs = hasClassLevelVerbs;
+exports.canRoleInvokeOperation = canRoleInvokeOperation;
+const registry = new Map();
+/** Per-session pagination cache. Invalidated when a fresh `tools/list` (no cursor) call recomputes. */
+const sessionListCache = new Map();
+function addTool(def) {
+    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();
+}
+function removeTool(name) {
+    const existed = registry.delete(name);
+    if (existed)
+        sessionListCache.clear();
+    return existed;
+}
+function getTool(name) {
+    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.
+ */
+function clearSessionCache(sessionId) {
+    sessionListCache.delete(sessionId);
+}
+/** Test seam: drop all registrations. */
+function _resetRegistryForTest() {
+    registry.clear();
+    sessionListCache.clear();
+}
+/**
+ * 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.
+ */
+function listTools(args) {
+    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, profile) {
+    const out = [];
+    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.outputSchema ? { outputSchema: def.outputSchema } : {}),
+            ...(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) {
+    return Buffer.from(JSON.stringify({ offset }), 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        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. */
+function isSuperUser(user) {
+    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.
+ */
+function hasClassLevelVerbs(prototype, resourcePrototype) {
+    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`.
+ */
+function canRoleInvokeOperation(user, operation) {
+    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',
+]);
+//# sourceMappingURL=toolRegistry.js.map

package/dist/core/components/mcp/toolRegistry.js.map

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