@bevel-software/platform-core-backend 0.1.0

package/src/modules/tool-helpers/tool-handler.ts

@@ -0,0 +1,91 @@
+import type { Request, Response } from 'express';
+import { hasHttpStatus, type ToolHandler } from './tool.contract.js';
+import type { ResolveToolContext } from './tool-context.js';
+import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
+
+function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof (v as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function'
+  );
+}
+
+export interface ToolHandlerOptions {
+  /** Mutating tool — refuse read-scoped callers up front (defense in depth). */
+  write?: boolean;
+}
+
+/**
+ * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
+ * handler, and serializes the result — JSON for a value, SSE for an
+ * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
+ * The handler receives `req.body` as the flat args (UTCP's `body_field` already
+ * delivered the inner body as the request body).
+ */
+export function createToolHandlerFactory(resolve: ResolveToolContext) {
+  return function toolHandler(handler: ToolHandler, opts: ToolHandlerOptions = {}) {
+    return async (req: Request, res: Response): Promise<void> => {
+      const auth = req.toolAuth;
+      if (!auth) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      if (opts.write && auth.scope === 'read') {
+        res.status(403).json({ error: 'This tool requires write access.' });
+        return;
+      }
+      const abort = new AbortController();
+      req.on('close', () => {
+        if (!res.writableEnded) abort.abort();
+      });
+      const body: unknown = req.body;
+      if (body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
+        res.status(400).json({ error: 'Request body must be a JSON object.' });
+        return;
+      }
+      const args = (body ?? {}) as Record<string, unknown>;
+      // `sessionId` rides the tool body like `branch` does: the external MCP
+      // proxy injects it (ask-tool continuity convention) and the in-process
+      // agent passes its thread id. Surfaced on the context so the ontology
+      // gate can scope to one run without each handler re-reading args.
+      const sessionId = typeof args.sessionId === 'string' && args.sessionId.length > 0
+        ? args.sessionId
+        : undefined;
+      try {
+        const ctx = await resolve(auth, abort.signal, sessionId);
+        const out = await handler(args, ctx);
+        if (isAsyncIterable(out)) {
+          res.setHeader('Content-Type', 'text/event-stream');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.setHeader('Connection', 'keep-alive');
+          for await (const chunk of out) {
+            res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+          }
+          res.end();
+        } else {
+          res.json(out);
+        }
+      } catch (err) {
+        // A handler can throw after streaming has begun (headers committed); in
+        // that case we can only end the stream, not rewrite the status.
+        if (res.headersSent) {
+          if (hasHttpStatus(err)) console.error('[tools] handler failed post-stream:', err.message);
+          else console.error('[tools] handler failed post-stream:', err instanceof Error ? err.message : err);
+          res.end();
+          return;
+        }
+        if (hasHttpStatus(err)) {
+          res.status(err.status).json({ error: err.message });
+          return;
+        }
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        console.error('[tools] handler failed:', msg);
+        res.status(500).json({ error: msg });
+      }
+    };
+  };
+}
+
+export type ToolHandlerFactory = ReturnType<typeof createToolHandlerFactory>;

package/src/modules/tool-helpers/tool.contract.ts

@@ -0,0 +1,85 @@
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { LocalFilesystem } from '@mastra/core/workspace';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+
+/**
+ * The hosting/execution contract a module works against when it lets `toolHelpers`
+ * host its endpoint (`toolHandler`). It is NOT a registry concern — the registry
+ * only cares that a tool is a valid UTCP `Tool`. A provider hosting its own
+ * transport (websocket, its own server) never touches any of this.
+ *
+ * The normalized context every tool handler receives, regardless of whether the
+ * caller authenticated with a connection key (external) or an internal token.
+ * The route layer resolves it once via `resolveToolContext`; handlers never look
+ * at the auth source.
+ *
+ * `branch` is passed BY THE TOOL — a KB tool declares a required `branch` input
+ * the model fills, and hands it to `getFilesystem(branch)`. Internal and external
+ * callers are identical: the credential is identity-only, so the workspace always
+ * comes from this argument (the per-branch clone, `workspaceIdForBranch(branch)`).
+ * A tool that never touches the KB never calls `getFilesystem`, so it never
+ * resolves a workspace. Resolution is cached after the first call.
+ */
+export interface ToolContext {
+  user: AuthUser;
+  scope: 'read' | 'write';
+  // `session` (browser JWT) only ever reaches the read-only manual endpoint, not
+  // a tool handler, so in practice a built context is always internal/external —
+  // the union just mirrors `ToolAuth.source`.
+  source: 'internal' | 'external' | 'session';
+  /** Connection-key id (external key callers only) — for daily-token metering. */
+  tokenId?: string;
+  /**
+   * The agent run / conversation id this call belongs to (the agent thread id).
+   * Supplied as a `sessionId` field on the tool's input body — the external MCP
+   * proxy injects it via the `ask`-tool continuity convention, and the
+   * in-process agent passes its thread id. Used to scope the ontology-session
+   * boundary to one run. Absent for non-agent or unthreaded calls.
+   */
+  sessionId?: string;
+  abortSignal: AbortSignal;
+  workspaceService: WorkspaceService;
+  workflowService: IWorkflowService;
+  events: WorkflowEventBus;
+  /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
+  getFilesystem(branch: string): Promise<LocalFilesystem>;
+}
+
+/**
+ * A tool's implementation: a pure function of `(args, ctx)`. Return a value for
+ * a normal JSON tool, or an async-iterable to stream (the `toolHandler` wrapper
+ * serializes each chunk as SSE and the last as the result). `args` is the flat
+ * request body (the `{body}` envelope is already unwrapped by the route).
+ */
+export type ToolHandler = (
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+) => Promise<unknown> | AsyncIterable<unknown>;
+
+/**
+ * A failure a tool handler can throw to choose its own HTTP status. The route
+ * maps any thrown value with a numeric `status` to that code — covering this
+ * and `AgentAskService`'s `AgentAskError`.
+ */
+export class ToolError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'ToolError';
+  }
+}
+
+export function hasHttpStatus(err: unknown): err is { status: number; message: string } {
+  if (typeof err !== 'object' || err === null) return false;
+  const status = (err as { status?: unknown }).status;
+  return (
+    typeof status === 'number' &&
+    Number.isInteger(status) &&
+    status >= 100 &&
+    status <= 599 &&
+    typeof (err as { message?: unknown }).message === 'string'
+  );
+}

package/src/modules/tool-helpers/validate-token.ts

@@ -0,0 +1,50 @@
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import { createTokenVerifier } from '../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver, type ToolContextDeps } from './tool-context.js';
+import { ToolError, type ToolContext } from './tool.contract.js';
+
+export interface ToolValidatorDeps extends ToolContextDeps {
+  externalApiKeyService: IExternalApiKeyService;
+  internalTokenService: InternalTokenService;
+}
+
+/**
+ * The tool-author SDK entry point — framework-agnostic, no Express. Given a
+ * bearer token (the value AFTER `Bearer `), it verifies the token and returns the
+ * per-call `ToolContext` (user, scope, and lazy `getWorkspace()`/`getFilesystem()`
+ * accessors). It does NOT take a branch: a tool that targets a specific branch
+ * declares a `branch` input the model fills and passes it to
+ * `getWorkspace(branch)` / `getFilesystem(branch)` — so a branchless tool never
+ * deals with workspaces at all. Throws a `ToolError` (carrying an HTTP status) on
+ * a bad/expired token or an auth-backend failure, so any framework can map it.
+ *
+ * A tool — ours hosted in-process, or a third-party marketplace plugin hosting
+ * its own endpoint — calls exactly this:
+ *
+ *   const ctx = await validateToken(bearer);
+ *   const fs = await ctx.getFilesystem(branch);   // branch only if the tool declares one
+ *
+ * It shares `createTokenVerifier` with the Express `toolAuth` middleware, so the
+ * auth path is identical whether a request arrives through our router or a
+ * plugin's own server.
+ */
+export type ValidateToken = (
+  token: string | undefined,
+  signal?: AbortSignal,
+) => Promise<ToolContext>;
+
+export function createToolValidator(deps: ToolValidatorDeps): ValidateToken {
+  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService);
+  const resolve = createToolContextResolver(deps);
+  return async (token, signal) => {
+    let result;
+    try {
+      result = await verify(token);
+    } catch {
+      throw new ToolError('Authentication backend unavailable', 500);
+    }
+    if (!result.ok) throw new ToolError(result.message, result.status);
+    return resolve(result.auth, signal ?? new AbortController().signal);
+  };
+}

package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts

@@ -0,0 +1,200 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { ToolManualService, type McpAuthDiscoveryPort } from '../tool-manuals.service.js';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+const BARE_MCP_TOOL = JSON.stringify({
+  name: 'notion',
+  type: 'mcp',
+  url: 'https://mcp.example.com/mcp',
+});
+
+const KEYED_MCP_TOOL = JSON.stringify({
+  name: 'jira',
+  type: 'mcp',
+  url: 'https://mcp.jira.example.com/mcp',
+  headers: { Authorization: 'Bearer ${JIRA_KEY}' },
+});
+
+const OAUTH_PROVIDER = {
+  authorizationUrl: 'https://auth.example.com/authorize',
+  tokenUrl: 'https://auth.example.com/token',
+  clientId: 'dcr-client-1',
+  scopes: ['mcp.read'],
+};
+
+describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
+  let root: string;
+
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  const allowAll: IAccessControl = {
+    canRead: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'tools-oauth-'));
+    const toolsDir = join(root, wsId, KB_DIR, 'Tools');
+    await mkdir(toolsDir, { recursive: true });
+    await writeFile(join(toolsDir, 'notion.tool'), BARE_MCP_TOOL);
+    await writeFile(join(toolsDir, 'jira.tool'), KEYED_MCP_TOOL);
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function svcWith(discovery: McpAuthDiscoveryPort) {
+    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR);
+    svc.setMcpAuthDiscovery(discovery);
+    return svc;
+  }
+
+  test('a bare mcp tool whose server demands OAuth gains the synthetic sign-in var + header', async () => {
+    const discovery: McpAuthDiscoveryPort = {
+      statusFor: vi.fn(async () => ({ status: 'oauth' as const, provider: OAUTH_PROVIDER })),
+    };
+    const svc = svcWith(discovery);
+
+    // The synthetic variable is user-scoped + oauth-backed, so /connect and the
+    // MCP proxy's readiness checks pick it up with no further wiring.
+    const manuals = await svc.listAccessible('user@example.com');
+    const notion = manuals.find((m) => m.name === 'notion')!;
+    expect(notion.variables).toEqual([
+      expect.objectContaining({
+        name: 'MCP_OAUTH',
+        scope: 'user',
+        oauth: expect.objectContaining({ clientId: 'dcr-client-1' }),
+      }),
+    ]);
+
+    const keys = await svc.userScopedKeysForManual('notion');
+    expect(keys).toEqual([
+      expect.objectContaining({ key: 'notion_MCP_OAUTH', oauth: true }),
+    ]);
+    await expect(svc.scopeOfVariable('notion_MCP_OAUTH')).resolves.toBe('user');
+
+    // The served call template carries the header the variable loader will fill.
+    const templates = await svc.toManualCallTemplates('user@example.com');
+    const notionTemplate = templates.find((t) => t.name === 'notion') as any;
+    expect(notionTemplate.config.mcpServers.notion.headers).toEqual({
+      Authorization: 'Bearer ${MCP_OAUTH}',
+    });
+  });
+
+  test('explicitly-configured auth wins: a tool with its own Authorization header is never probed', async () => {
+    const statusFor = vi.fn(async () => ({ status: 'oauth' as const, provider: OAUTH_PROVIDER }));
+    const svc = svcWith({ statusFor });
+
+    await svc.listAccessible('user@example.com');
+
+    expect(statusFor).toHaveBeenCalledTimes(1);
+    expect(statusFor).toHaveBeenCalledWith('notion', 'https://mcp.example.com/mcp'); // never 'jira'
+    const manuals = await svc.listAccessible('user@example.com');
+    const jira = manuals.find((m) => m.name === 'jira')!;
+    // No synthetic sign-in — but its referenced key still auto-surfaces as an admin var.
+    expect(jira.variables).toEqual([{ name: 'JIRA_KEY', scope: 'admin' }]);
+  });
+
+  test('referenced-but-undeclared ${VAR}s are auto-surfaced as admin keys (any tool type)', async () => {
+    const toolsDir = join(root, wsId, KB_DIR, 'Tools');
+    await writeFile(
+      join(toolsDir, 'billing.tool'),
+      JSON.stringify({
+        name: 'billing',
+        type: 'http',
+        url: 'https://api.example.com/utcp',
+        headers: { Authorization: 'Bearer ${BILLING_KEY}' },
+      }),
+    );
+    await writeFile(
+      join(toolsDir, 'weather.tool'),
+      JSON.stringify({
+        name: 'weather',
+        type: 'inline',
+        // Declared user var + an extra undeclared ref in the embedded tool.
+        variables: [{ name: 'WEATHER_KEY', scope: 'user' }],
+        tools: [
+          {
+            name: 'forecast',
+            description: 'forecast',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: {
+              call_template_type: 'http',
+              http_method: 'GET',
+              url: 'https://api.example.com/forecast?region=${REGION}',
+              headers: { Authorization: 'Bearer ${WEATHER_KEY}' },
+            },
+          },
+        ],
+      }),
+    );
+    const svc = svcWith({ statusFor: async () => ({ status: 'open' as const }) });
+
+    const manuals = await svc.listAccessible('user@example.com');
+    const billing = manuals.find((m) => m.name === 'billing')!;
+    expect(billing.variables).toEqual([{ name: 'BILLING_KEY', scope: 'admin' }]);
+
+    const weather = manuals.find((m) => m.name === 'weather')!;
+    // The declared entry keeps its metadata; only the genuinely-undeclared ref
+    // is added, and never the proxy-seeded API_URL / CONNECTION_KEY.
+    expect(weather.variables).toEqual([
+      expect.objectContaining({ name: 'WEATHER_KEY', scope: 'user' }),
+      { name: 'REGION', scope: 'admin' },
+    ]);
+    // Scope resolution matches: undeclared → admin, declared → as written.
+    await expect(svc.scopeOfVariable('billing_BILLING_KEY')).resolves.toBe('admin');
+    await expect(svc.scopeOfVariable('weather_WEATHER_KEY')).resolves.toBe('user');
+  });
+
+  test('setup requirement is recorded per discovery outcome (open / oauth / oauth-manual)', async () => {
+    const oauthSvc = svcWith({ statusFor: async () => ({ status: 'oauth' as const, provider: OAUTH_PROVIDER }) });
+    const oauth = (await oauthSvc.listAccessible('user@example.com')).find((m) => m.name === 'notion')!;
+    expect(oauth.setup).toEqual({ kind: 'oauth-auto' });
+
+    const openSvc = svcWith({ statusFor: async () => ({ status: 'open' as const }) });
+    const open = (await openSvc.listAccessible('user@example.com')).find((m) => m.name === 'notion')!;
+    expect(open.setup).toEqual({ kind: 'open' });
+
+    // The `unsupported` case (e.g. Google — no dynamic client registration) is
+    // the one that must reach the admin UI rather than only the server logs.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const manualSvc = svcWith({
+      statusFor: async () => ({ status: 'unsupported' as const, reason: 'no dynamic client registration' }),
+    });
+    const manual = (await manualSvc.listAccessible('user@example.com')).find((m) => m.name === 'notion')!;
+    expect(manual.setup).toEqual({ kind: 'oauth-manual', reason: 'no dynamic client registration' });
+    // Still bare — the admin declares the provider; we don't inject a sign-in var.
+    expect(manual.variables ?? []).toEqual([]);
+    warn.mockRestore();
+  });
+
+  test('an open server leaves the tool untouched; a discovery failure never breaks the catalog', async () => {
+    const openSvc = svcWith({ statusFor: async () => ({ status: 'open' as const }) });
+    const open = await openSvc.listAccessible('user@example.com');
+    expect(open.find((m) => m.name === 'notion')!.variables ?? []).toEqual([]);
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const throwingSvc = svcWith({
+      statusFor: async () => {
+        throw new Error('network exploded');
+      },
+    });
+    const survived = await throwingSvc.listAccessible('user@example.com');
+    expect(survived.map((m) => m.name).sort()).toEqual(['jira', 'notion']);
+    warn.mockRestore();
+  });
+});