@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/dist/components/mcp/toolRegistry.js

@@ -0,0 +1,176 @@
+"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.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/components/mcp/toolRegistry.js.map

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

package/dist/components/mcp/tools/application.d.ts

@@ -0,0 +1,58 @@
+import { type HarperAttribute } from './schemas/derive.ts';
+type ExportTypes = Record<string, boolean> | undefined;
+interface ResourceRegistryEntry {
+    Resource: ResourceClassLike;
+    path: string;
+    exportTypes?: ExportTypes;
+    hasSubPaths?: boolean;
+    relativeURL?: string;
+}
+interface ResourceClassLike {
+    prototype?: Record<string, unknown>;
+    databaseName?: string;
+    tableName?: string;
+    primaryKey?: string;
+    attributes?: HarperAttribute[];
+    get?: (target: unknown, request: unknown, data?: unknown) => unknown;
+    put?: (target: unknown, data: unknown, request: unknown) => unknown;
+    post?: (target: unknown, data: unknown, request: unknown) => unknown;
+    patch?: (target: unknown, data: unknown, request: unknown) => unknown;
+    delete?: (target: unknown, request: unknown, data?: unknown) => unknown;
+    search?: (target: unknown, request: unknown) => unknown;
+    loadAsInstance?: boolean;
+    /**
+     * Component-author opt-in (#622): expose non-verb instance methods as MCP
+     * tools. Each entry maps an instance-method name to an MCP tool descriptor.
+     * RBAC stays as whatever the Resource's method itself enforces; the MCP
+     * layer does not invent new ACLs for these.
+     */
+    mcpTools?: ReadonlyArray<{
+        name: string;
+        method: string;
+        description?: string;
+        inputSchema?: object;
+        annotations?: {
+            readOnlyHint?: boolean;
+            destructiveHint?: boolean;
+            idempotentHint?: boolean;
+        };
+    }>;
+}
+type ResourcesRegistry = Map<string, ResourceRegistryEntry>;
+type RequestTargetCtor = new () => Record<string, unknown> & {
+    conditions?: unknown[];
+    operator?: string;
+    limit?: number;
+    offset?: number;
+    select?: string[];
+    id?: unknown;
+};
+export declare function _setResourcesForTest(r: ResourcesRegistry | undefined): void;
+export declare function _setRequestTargetForTest(ctor: RequestTargetCtor | undefined): void;
+/**
+ * Idempotent registration — walk the Resources Map, register verb tools
+ * for each entry that passes the exportTypes + verb-presence filters.
+ * Re-invocation overwrites prior tool entries (Map.set semantics).
+ */
+export declare function registerApplicationTools(): void;
+export {};