@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/dist/modules/tool-manuals/mcp-json-discovery.js

@@ -0,0 +1,276 @@
+import { HEXIS_EXTENSION_NS, PLUGIN_MCP_FILE, PLUGIN_MANIFEST_FILE, PLUGINS_DIR, } from '@bevel-software/platform-shared';
+import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { RESERVED_VARIABLE_NAMES, findReservedVariableRef } from '../../shared/variable-refs.js';
+/**
+ * The same reserved-reference policy `.tool` parsing enforces, applied to the
+ * extension block: `API_URL`/`CONNECTION_KEY` (bare or namespaced) are seeded
+ * by the platform for its own manuals, and an extension header referencing one
+ * would be asking the substitutor to hand a third-party server the caller's
+ * bearer. One rule, both declaration surfaces — and one GRAMMAR deciding what
+ * a reference is (shared/variable-refs.ts), so nothing the migration or the
+ * editor classifies as a portable literal can be reserved here.
+ */
+const referencesReservedVariable = findReservedVariableRef;
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** The `mcpServers` extension map from a parsed plugin.json, or `{}`. */
+function extensionServers(pluginJson) {
+    if (!isRecord(pluginJson))
+        return {};
+    const ext = pluginJson.extensions;
+    if (!isRecord(ext))
+        return {};
+    const ns = ext[HEXIS_EXTENSION_NS];
+    if (!isRecord(ns) || !isRecord(ns.mcpServers))
+        return {};
+    return ns.mcpServers;
+}
+/** A manual name must be usable as a UTCP namespace + route slug. Same shape `.tool` ids use. */
+const SERVER_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * Validate an extension entry's `variables` declarations, or `null` when any
+ * entry is malformed. The `.tool` parser THROWS on a bad entry so the whole
+ * file is skipped — a variable silently dropped or mis-read is not cosmetic:
+ * an undeclared reference defaults to the shared `admin` scope, so losing a
+ * `scope: user` declaration would hand one caller's slot to everyone. The
+ * same stake applies here, at this file's per-server grain: a bad entry
+ * invalidates the SERVER, never its siblings.
+ *
+ * Exported for the mcp-server editor: what it saves is what this scan reads
+ * on the next pass, so the two must judge a declaration with ONE function —
+ * a shape saveable there but undiscoverable here would be a server that
+ * silently vanishes from the catalog the moment its edit lands.
+ */
+export function validatedVariables(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    const declared = new Set();
+    for (const entry of raw) {
+        if (!isRecord(entry))
+            return null;
+        if (typeof entry.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(entry.name))
+            return null;
+        // The `.tool` parser's declaration rules, at this file's grain: a
+        // platform-seeded name may not be re-declared (it would shadow the
+        // seeding), and a duplicate would make later scope resolution depend on
+        // declaration order.
+        if (RESERVED_VARIABLE_NAMES.includes(entry.name) || declared.has(entry.name))
+            return null;
+        declared.add(entry.name);
+        const scope = entry.scope ?? 'admin';
+        if (scope !== 'admin' && scope !== 'user')
+            return null;
+        let oauth;
+        if (entry.oauth !== undefined) {
+            // OAuth is inherently per-caller (same rule the `.tool` parser
+            // enforces): an admin-shared OAuth token would leak one user's token
+            // to all callers. The provider config's required halves must be there
+            // — a sign-in wired to a missing URL is a declaration, not a feature.
+            if (!isRecord(entry.oauth) || scope !== 'user')
+                return null;
+            const o = entry.oauth;
+            // `clientId` is trimmed and must be non-empty, exactly as the `.tool`
+            // parser requires: a whitespace-only value would pass discovery and
+            // then fail the owner's client-secret setup with "clientId is
+            // required" — an error at the wrong surface, long after the save.
+            if (typeof o.authorizationUrl !== 'string' ||
+                typeof o.tokenUrl !== 'string' ||
+                typeof o.clientId !== 'string' ||
+                !o.clientId.trim()) {
+                return null;
+            }
+            // The same https + SSRF gate the `.tool` parser runs on these URLs: a
+            // sign-in or token exchange aimed at an internal host is a declaration
+            // this surface must refuse exactly like the other one does.
+            try {
+                assertSafeFetchUrl(o.authorizationUrl, { requireHttps: true, label: `${entry.name} oauth.authorizationUrl` });
+                assertSafeFetchUrl(o.tokenUrl, { requireHttps: true, label: `${entry.name} oauth.tokenUrl` });
+            }
+            catch {
+                return null;
+            }
+            // Forwarded verbatim as query params later — a non-string value here is
+            // a malformed declaration, not something to coerce.
+            if (o.authParams !== undefined) {
+                if (!isRecord(o.authParams) || !Object.values(o.authParams).every((v) => typeof v === 'string')) {
+                    return null;
+                }
+            }
+            oauth = {
+                authorizationUrl: o.authorizationUrl,
+                tokenUrl: o.tokenUrl,
+                clientId: o.clientId.trim(),
+                ...(Array.isArray(o.scopes) && o.scopes.every((s) => typeof s === 'string')
+                    ? { scopes: o.scopes }
+                    : {}),
+                ...(o.authParams !== undefined ? { authParams: o.authParams } : {}),
+            };
+        }
+        out.push({
+            name: entry.name,
+            scope,
+            ...(typeof entry.label === 'string' && entry.label.trim() ? { label: entry.label.trim() } : {}),
+            ...(oauth ? { oauth } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Descriptors for one plugin's `mcp.json`. Malformed entries are skipped with
+ * a logged reason — one bad server must not take the plugin's others offline —
+ * and a missing/unparsable file yields `[]` (the caller decides whether that
+ * is worth a log line; an absent mcp.json is the common case, not an error).
+ *
+ * `stdio` entries are inherently LOCAL (`remote: false`): the hosted proxy can
+ * never spawn a subprocess out of knowledge-base content, so they are served
+ * only to local consumers (hexis-mcp), whose UTCP mcp plugin spawns them.
+ * `${PLUGIN_ROOT}`/`${PLUGIN_DATA}` placeholders are NOT expanded yet — local
+ * materialization is a later phase — so a stdio server relying on them will
+ * fail to spawn until then; bare-command servers (`npx …`) work today.
+ */
+export function descriptorsFromMcpJson(pluginFolder, mcpJsonText, pluginJsonText) {
+    let mcp;
+    try {
+        mcp = JSON.parse(mcpJsonText);
+    }
+    catch {
+        console.warn(`[tool-manuals] ${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MCP_FILE} is not valid JSON — skipped.`);
+        return [];
+    }
+    if (!isRecord(mcp) || !isRecord(mcp.mcpServers))
+        return [];
+    let manifest = null;
+    if (pluginJsonText !== null) {
+        try {
+            manifest = JSON.parse(pluginJsonText);
+        }
+        catch {
+            // A broken manifest costs the extension data (auth wiring), not the
+            // servers themselves — they are still listed, as the spec's own
+            // "invalid components are skipped, valid ones load" posture suggests.
+            console.warn(`[tool-manuals] ${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MANIFEST_FILE} is not valid JSON — ` +
+                'its mcp-server auth/variable declarations are ignored.');
+        }
+    }
+    const extensions = extensionServers(manifest);
+    const mcpJsonPath = `${PLUGINS_DIR}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
+    const out = [];
+    for (const [name, raw] of Object.entries(mcp.mcpServers)) {
+        if (!SERVER_NAME_RE.test(name)) {
+            console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: the name is the secret ` +
+                'namespace and route slug, so it must be lowercase alphanumeric with `_`/`-`.');
+            continue;
+        }
+        if (!isRecord(raw) || typeof raw.type !== 'string') {
+            console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: no transport type.`);
+            continue;
+        }
+        // The extension entry is knowledge-base content too — same zero-trust
+        // parse as the rest: a non-object entry reads as "no extension data".
+        const ext = isRecord(extensions[name])
+            ? extensions[name]
+            : {};
+        // The EFFECTIVE declaration, not just the extension block: a reserved
+        // reference in mcp.json's own url or literal headers would be expanded
+        // into outbound requests exactly the same way.
+        const reserved = referencesReservedVariable({ raw, ext });
+        if (reserved !== null) {
+            console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: its declaration (mcp.json ` +
+                `entry or plugin.json extension) references the reserved variable "${reserved}" — API_URL and ` +
+                'CONNECTION_KEY are platform-seeded and may not appear in server declarations.');
+            continue;
+        }
+        const variables = validatedVariables(ext.variables);
+        if (variables === null) {
+            console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: its plugin.json \`variables\` ` +
+                'declaration is malformed — a dropped declaration would silently re-scope a credential, so ' +
+                'the server stays offline until the manifest is fixed.');
+            continue;
+        }
+        const shared = {
+            slug: name,
+            name,
+            path: mcpJsonPath,
+            type: 'mcp',
+            ...(typeof ext.description === 'string' ? { description: ext.description } : {}),
+            ...(variables.length > 0 ? { variables } : {}),
+        };
+        if (raw.type === 'stdio') {
+            if (typeof raw.command !== 'string' || raw.command.length === 0) {
+                console.warn(`[tool-manuals] skipping stdio server "${name}" in ${mcpJsonPath}: no command.`);
+                continue;
+            }
+            out.push({
+                ...shared,
+                remote: false,
+                stdio: {
+                    command: raw.command,
+                    args: Array.isArray(raw.args) ? raw.args.map(String) : [],
+                    env: isRecord(raw.env) ? raw.env : undefined,
+                    cwd: typeof raw.cwd === 'string' ? raw.cwd : undefined,
+                },
+            });
+            continue;
+        }
+        if (raw.type === 'streamable-http' || raw.type === 'sse') {
+            if (typeof raw.url !== 'string' || raw.url.length === 0) {
+                console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: no url.`);
+                continue;
+            }
+            // Remote-capable servers get the same SSRF gate `.tool` urls pass —
+            // otherwise mcp.json becomes the way to point the backend at loopback,
+            // private ranges, or the cloud metadata endpoint. A `local: true` entry
+            // is exempt because loopback is exactly what local MEANS, and only the
+            // user's own machine ever dials it.
+            // Scheme first, for EVERYONE: `local: true` exempts a server from the
+            // private-network reachability policy, not from being http(s) at all.
+            let schemeOk = false;
+            try {
+                const u = new URL(raw.url);
+                schemeOk = u.protocol === 'http:' || u.protocol === 'https:';
+            }
+            catch {
+                schemeOk = false;
+            }
+            if (!schemeOk) {
+                console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: url must be http(s).`);
+                continue;
+            }
+            if (ext.local !== true) {
+                try {
+                    assertSafeFetchUrl(raw.url, { label: `mcp server "${name}" url` });
+                }
+                catch (err) {
+                    console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: ` +
+                        `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`);
+                    continue;
+                }
+            }
+            // Extension headers (auth, `${VAR}` refs) win over mcp.json's literal
+            // ones on a key collision: the portable file cannot carry a credential,
+            // so when both name the same header the extension is the operative one.
+            // Both sides pass the isRecord gate — spreading a malformed non-object
+            // value (a string, say) would scatter its indices into header keys.
+            const headers = {
+                ...(isRecord(raw.headers) ? raw.headers : {}),
+                ...(isRecord(ext.headers) ? ext.headers : {}),
+            };
+            out.push({
+                ...shared,
+                url: raw.url,
+                ...(Object.keys(headers).length > 0 ? { headers } : {}),
+                ...(ext.local === true ? { remote: false } : {}),
+            });
+            continue;
+        }
+        // Unknown transport: the spec says an unknown `type` invalidates the
+        // ENTRY, not the file — skip it, keep its siblings.
+        console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: unknown type "${raw.type}".`);
+    }
+    return out;
+}
+//# sourceMappingURL=mcp-json-discovery.js.map

package/dist/modules/tool-manuals/mcp-json-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-json-discovery.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/mcp-json-discovery.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-manuals/mcp-server-edit.service.d.ts

@@ -0,0 +1,92 @@
+import { type AuthUser } from '@bevel-software/platform-shared';
+import { type WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IToolManualService, ToolVariable } from './tool-manuals.contract.js';
+/**
+ * Server-scoped editing of one MCP server — the form the tool page uses
+ * instead of dropping a writer into raw `mcp.json`.
+ *
+ * One server's truth spans TWO files (the spec's split, not ours): the
+ * portable half in `mcp.json` (transport, url, literal headers) and our half
+ * in `plugin.json`'s `extensions["software.bevel.hexis"].mcpServers[<name>]`
+ * (auth headers carrying `${VAR}` vault references, variable declarations,
+ * description, `local`). This service is the ONE writer that keeps the two in
+ * step: a save rewrites both entries and commits them together, because a
+ * server whose auth landed without its url — or the reverse — is a broken
+ * tool with no author to blame.
+ *
+ * RENAME IS DESTRUCTIVE BY DESIGN and the route says so: the `mcpServers` key
+ * is the namespace vault secrets bind to (`<name>_<VAR>`), so renaming a
+ * server orphans every configured secret and completed sign-in under the old
+ * key. The frontend counts what disconnects (it already holds per-variable
+ * status) and confirms; this service just refuses a rename onto a taken key.
+ */
+export type McpTransport = 'streamable-http' | 'sse' | 'stdio';
+export interface McpServerView {
+    name: string;
+    transport: McpTransport;
+    url?: string;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Portable headers, stored in mcp.json. Never carry a `${VAR}`. */
+    literalHeaders: Record<string, string>;
+    /** Auth headers with vault references, stored in the extensions block. */
+    authHeaders: Record<string, string>;
+    variables: ToolVariable[];
+    description?: string;
+    local: boolean;
+    canWrite: boolean;
+}
+/**
+ * PATCH semantics, field by field: `undefined` means "the client did not
+ * surface this field" and the stored value survives; a present-but-empty
+ * value (`{}`, `[]`, `''`) is an explicit clear. A full-replace contract
+ * would make every client responsible for echoing back fields it does not
+ * edit — and the one that forgot would silently destroy the literal headers
+ * in mcp.json or the variable declarations behind `${VAR}` references.
+ */
+export interface McpServerWrite {
+    newName?: string;
+    transport: McpTransport;
+    url?: string;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    literalHeaders?: Record<string, string>;
+    authHeaders?: Record<string, string>;
+    variables?: ToolVariable[];
+    description?: string;
+    local?: boolean;
+}
+export declare class McpServerEditError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface CommitDriver {
+    runPendingCommit(workspaceId: string, branch: string, targetPath: string, user: AuthUser, opts?: {
+        systemAuthorized?: boolean;
+    }): Promise<void>;
+}
+export declare class McpServerEditService {
+    private readonly workspaceService;
+    private readonly commits;
+    private readonly accessControl;
+    private readonly toolManuals;
+    private readonly kbDirName;
+    constructor(workspaceService: WorkspaceService, commits: CommitDriver, accessControl: IAccessControl, toolManuals: IToolManualService, kbDirName: string);
+    /** The merged view of one server, or null when unknown/unreadable (indistinguishable, fail closed). */
+    getServer(userEmail: string, slug: string): Promise<McpServerView | null>;
+    /** Rewrite one server across both files, in one commit. Returns the (possibly new) name. */
+    putServer(user: AuthUser, slug: string, write: McpServerWrite): Promise<{
+        name: string;
+    }>;
+    /** Resolve a slug to an mcp.json-backed server the caller can READ; null otherwise. */
+    private locate;
+    private readFiles;
+    private extensionEntry;
+}
+export {};
+//# sourceMappingURL=mcp-server-edit.service.d.ts.map

package/dist/modules/tool-manuals/mcp-server-edit.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server-edit.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/mcp-server-edit.service.ts"],"names":[],"mappings":"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"}