@ultimat3/mcp 1.0.0

package/src/readonly-sql.ts

@@ -0,0 +1,318 @@
+// Enforcement for the dev server's two dangerous tools: `db.query` must be read-only and
+// `db.migrate` must be pointed at a branch database.
+//
+// A description saying "read-only" is documentation; documentation is not a guarantee. The
+// gate is structural: one statement, an allowed leading keyword, and no mutating keyword
+// anywhere at statement level (which also catches a data-modifying CTE — `WITH x AS
+// (INSERT ...) SELECT`, which reads like a SELECT and is not one).
+
+import { McpNotBranchDbError, McpQueryRejectedError } from './errors';
+
+/** Named in `db.query`'s `guards`, so a caller can see that layer 3 actually ran. */
+export const PARSE_GUARD = 'parse:single-read';
+
+/** Statements that may begin a read-only query. */
+const READ_LEADERS = new Set(['select', 'with', 'explain', 'show', 'table', 'values']);
+
+/**
+ * Keywords that make a statement a write. Includes transaction control (a session the tool
+ * left open is a lock held on a shared dev DB), `set`/`copy` (session mutation, file I/O),
+ * and `analyze` — `EXPLAIN ANALYZE` executes the plan and `ANALYZE t` rewrites statistics,
+ * so both are refused rather than special-cased. One rule, no exceptions to remember.
+ */
+const WRITE_KEYWORDS = new Set([
+  'alter',
+  'analyze',
+  'begin',
+  'call',
+  'cluster',
+  'comment',
+  'commit',
+  'copy',
+  'create',
+  'deallocate',
+  'declare',
+  'delete',
+  'discard',
+  'do',
+  'drop',
+  'execute',
+  'grant',
+  'import',
+  'insert',
+  'listen',
+  'lock',
+  'merge',
+  'move',
+  'notify',
+  'prepare',
+  'reassign',
+  'refresh',
+  'reindex',
+  'release',
+  'rename',
+  'reset',
+  'revoke',
+  'rollback',
+  'savepoint',
+  'security',
+  'set',
+  'start',
+  'truncate',
+  'unlisten',
+  'update',
+  'vacuum',
+]);
+
+/**
+ * Function families a read may not call, matched as a PREFIX of a CALLED function name.
+ *
+ * The family is the unit, never the name. Refusing `pg_sleep` while admitting `pg_sleep_for` is a
+ * distinction only this parser draws, and an exact-name list admits by default: every spelling
+ * nobody thought to write down passes. A prefix refuses by default instead, so a member Postgres
+ * adds next release is covered on the day it ships.
+ *
+ * Each family is a ban this file already makes in some other spelling:
+ *  - reach outside the database — the original list (`pg_read_*`, `pg_ls_*`, `lo_*`, `dblink`);
+ *  - hold a lock, which `FOR UPDATE` is refused for below. The call is the worse of the two: a
+ *    SESSION advisory lock is not released by the `ROLLBACK` layer 2 always runs, so it outlives
+ *    the read on a pooled connection the app's own writers use;
+ *  - mutate the server or the session — `set_config` is `SET` spelled as a call, and `SET` is a
+ *    write keyword above;
+ *  - burn the wall clock — layer 2's `statement_timeout` cannot interrupt embedded PGlite
+ *    (single-threaded WASM), which is the database `x dev` runs, so this ban is the only one
+ *    that holds there.
+ *
+ * The prefix is applied to a CALL — a name followed by `(` — and never to a bare word, so a
+ * column called `pg_sleep_for_seconds` stays readable. Quoting does not evade it: the scan reads
+ * a form where a quoted identifier keeps its content, because `"pg_advisory_lock"(1)` is the same
+ * call as `pg_advisory_lock(1)`.
+ */
+const FORBIDDEN_FUNCTIONS = [
+  'dblink',
+  'lo_',
+  'pg_advisory_',
+  'pg_cancel_backend',
+  'pg_ls_',
+  'pg_read_',
+  'pg_sleep',
+  'pg_stat_file',
+  'pg_stat_reset',
+  'pg_terminate_backend',
+  'pg_try_advisory_',
+  'set_config',
+];
+
+/** The family refusing `called`, or `undefined`. A prefix, so a new member is refused by default. */
+function forbiddenFamily(called: string): string | undefined {
+  return FORBIDDEN_FUNCTIONS.find((family) => called.startsWith(family));
+}
+
+/**
+ * A call: an identifier immediately before `(`. Schema qualification falls out of the scan —
+ * `pg_catalog.set_config(` matches on the last segment, which is the function being called.
+ */
+const CALL_PATTERN = /([a-z_][a-z0-9_$]*)\s*\(/g;
+
+/** Every function `sql` calls, lowercased. Read from the identifier-preserving strip. */
+function calledFunctions(sql: string): readonly string[] {
+  const names: string[] = [];
+  for (const match of sql.toLowerCase().matchAll(CALL_PATTERN)) {
+    const name = match[1];
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Throw unless `sql` is a single read-only statement. Every check runs on the *stripped* form
+ * (literals and comments blanked) so a keyword hiding in a string cannot fool it — but the
+ * string returned is the caller's own `sql`, verbatim apart from surrounding whitespace and
+ * one trailing `;`, because the caller *executes* this value. Returning the stripped form ran
+ * `select 'delete from posts' as note` as `select   as note`.
+ */
+export function assertReadOnlyQuery(sql: string): string {
+  const stripped = stripLiteralsAndComments(sql);
+  const statements = stripped
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  if (statements.length === 0) {
+    throw rejected('the statement is empty', 'send one SELECT statement');
+  }
+  if (statements.length > 1) {
+    throw rejected(
+      `${statements.length} statements were sent; batching hides a write behind a read`,
+      'send exactly one SELECT statement per db.query call',
+    );
+  }
+
+  const statement = statements[0] ?? '';
+  const words: readonly string[] = statement.toLowerCase().match(/[a-z_]+/g) ?? [];
+  const leader = words[0] ?? '';
+  if (!READ_LEADERS.has(leader)) {
+    throw rejected(
+      `statement begins with "${leader}", which is not a read`,
+      `begin with one of: ${[...READ_LEADERS].sort().join(', ')}`,
+    );
+  }
+  for (const word of words) {
+    if (WRITE_KEYWORDS.has(word)) {
+      throw rejected(
+        `the statement contains the mutating keyword "${word}"`,
+        // `db.migrate` applies pending migrations; it is not an INSERT/UPDATE/DELETE path, and
+        // there is no MCP tool that is. Data changes go through an action, which carries a policy.
+        'db.query has no write path: change data by calling an action exposed with ' +
+          'mcp: { expose: true }, and change schema with db.migrate after x db branch <name>',
+      );
+    }
+  }
+  // A family refuses a CALL, never a bare word: scanning every word rejected a column named
+  // `pg_sleep_for_seconds`, and scanning the blanked form missed `"pg_advisory_lock"(1)`, which
+  // is the same call wearing quotes. So this pass reads the form that keeps identifier content.
+  for (const called of calledFunctions(stripLiteralsAndComments(sql, 'keep'))) {
+    const family = forbiddenFamily(called);
+    if (family !== undefined) {
+      // The cause names what the author wrote AND the family it belongs to: the second half is
+      // the rule, and without it the next spelling looks like a different, arguable refusal.
+      throw rejected(
+        family === called
+          ? `the statement calls ${called}(), which db.query may not call`
+          : `the statement calls ${called}(), one of the ${family}* functions db.query may not call`,
+        'query tables only: no file access, no locks, no session settings, no sleeps',
+      );
+    }
+  }
+  // `SELECT ... FOR UPDATE` takes row locks — a read that blocks other writers.
+  if (/\bfor\s+(update|no\s+key\s+update|share|key\s+share)\b/i.test(statement)) {
+    throw rejected(
+      'the statement takes row locks (FOR UPDATE/SHARE)',
+      'drop the locking clause; db.query may not hold locks',
+    );
+  }
+  return verbatim(sql);
+}
+
+/**
+ * The caller's bytes, minus surrounding whitespace and one trailing `;`. Anything past that
+ * semicolon is whitespace or a comment — the single-statement check above already proved the
+ * stripped form has nothing else there.
+ */
+function verbatim(sql: string): string {
+  const trimmed = sql.trim();
+  return trimmed.endsWith(';') ? trimmed.slice(0, -1).trimEnd() : trimmed;
+}
+
+/** What the host knows about the connection `db.migrate` would run against. */
+export interface DatabaseTarget {
+  /** Human-readable identity for the message. Never a connection string with a password. */
+  readonly label: string;
+  /** Branch name, or `null` when this is a shared/long-lived database. */
+  readonly branch: string | null;
+  /** True when this database backs production traffic. */
+  readonly production: boolean;
+}
+
+/**
+ * Throw unless `target` is a branch database. Two separate refusals so the message names
+ * the actual problem: production is never migratable from MCP at all, and a non-production
+ * shared database still is not a branch.
+ */
+export function assertBranchDatabase(target: DatabaseTarget): string {
+  if (target.production) {
+    throw notBranch(
+      `"${target.label}" is a production database`,
+      'run migrations in production through the migrate role: ROLE=migrate in your deploy hook',
+    );
+  }
+  if (target.branch === null) {
+    throw notBranch(
+      `"${target.label}" is not a branch database`,
+      'x db branch <name>, then retry db.migrate',
+    );
+  }
+  return target.branch;
+}
+
+function rejected(cause: string, fix: string): McpQueryRejectedError {
+  return new McpQueryRejectedError({ cause, fix });
+}
+
+function notBranch(cause: string, fix: string): McpNotBranchDbError {
+  return new McpNotBranchDbError({ cause, fix });
+}
+
+/**
+ * Replace string/identifier literals and comments with spaces so keyword scanning cannot be
+ * fooled by `SELECT 'delete'` (a harmless literal that looks like a write) and cannot be
+ * evaded by hiding a second statement behind a block comment. Only word boundaries matter
+ * downstream, so collapsing each run to one space is enough.
+ *
+ * `identifiers: 'keep'` unwraps a double-quoted identifier to its content instead — the call
+ * scan needs it, because `"pg_advisory_lock"(1)` calls the function the blanked form hides.
+ * String and dollar-quoted literals are blanked in both modes: a literal is never a call.
+ */
+function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = 'blank'): string {
+  let out = '';
+  let i = 0;
+  while (i < sql.length) {
+    const two = sql.slice(i, i + 2);
+    if (two === '--') {
+      const end = sql.indexOf('\n', i);
+      i = end === -1 ? sql.length : end;
+      out += ' ';
+      continue;
+    }
+    if (two === '/*') {
+      const end = sql.indexOf('*/', i + 2);
+      i = end === -1 ? sql.length : end + 2;
+      out += ' ';
+      continue;
+    }
+    const char = sql[i];
+    if (char === "'" || char === '"') {
+      const end = skipQuoted(sql, i, char);
+      // Padded, never spliced in place: `select"pg_advisory_lock"(1)` must not fuse into one
+      // token, or the call the quotes were hiding stays hidden behind the leading keyword.
+      out += char === '"' && identifiers === 'keep' ? ` ${inner(sql.slice(i, end))} ` : ' ';
+      i = end;
+      continue;
+    }
+    if (char === '$') {
+      const tag = /^\$[a-z_]*\$/i.exec(sql.slice(i));
+      if (tag !== null) {
+        const marker = tag[0];
+        const end = sql.indexOf(marker, i + marker.length);
+        i = end === -1 ? sql.length : end + marker.length;
+        out += ' ';
+        continue;
+      }
+    }
+    out += char;
+    i += 1;
+  }
+  return out;
+}
+
+/** A quoted run's content: the delimiters dropped, SQL's doubled-quote escape collapsed. */
+function inner(run: string): string {
+  const closed = run.length > 1 && run.endsWith(run[0] ?? '');
+  return run.slice(1, closed ? -1 : undefined).replaceAll('""', '"');
+}
+
+/** Advance past a quoted run, honouring SQL's doubled-quote escape (`'it''s'`). */
+function skipQuoted(sql: string, start: number, quote: string): number {
+  let i = start + 1;
+  while (i < sql.length) {
+    if (sql[i] === quote) {
+      if (sql[i + 1] === quote) {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i += 1;
+  }
+  return sql.length;
+}

package/src/registry.ts

@@ -0,0 +1,229 @@
+// The tool catalog and the first two of the three security outcomes every MCP surface owes
+// a caller. See `docs/architecture/11-ai-surface.md` § Security posture.
+//
+// OUTCOME 1 — hidden (role). A tool whose `visibleTo` excludes the caller is omitted from
+// `tools/list` and answers ToolNotFound (`-32601`) on call, with the same message an absent
+// tool gets. Never Forbidden: "Forbidden" confirms the tool exists, which turns an authz
+// boundary into a catalog an agent can enumerate by probing. Hidden ≠ Forbidden.
+//
+// OUTCOME 2 — scope (capability). A tool the caller may SEE but whose `scope` its token does
+// not carry is refused (`-32600`, `X_MCP_SCOPE_DENIED`). Being refused is correct here: the
+// caller was shown the tool, so naming it leaks nothing, and the message can say which scope
+// to obtain — hiding it would strand a well-behaved client that can legitimately fix this.
+//
+// OUTCOME 3 — policy (`X_FORBIDDEN`) belongs to the tool's own `handle`, which reaches
+// `guard()` in @ultimat3/action. It is deliberately NOT here: the scope gate must decide
+// before any policy runs against attacker-supplied input.
+//
+// The outcomes are orthogonal on purpose. A tool can be visible and still refused for a
+// narrow token; a token holding every scope still cannot see a tool its role may not.
+
+import type { Actor } from '@ultimat3/core';
+import type { ArgIssue } from './validate-args';
+import { validateArgs } from './validate-args';
+import type { JsonSchema } from './wire';
+
+/** Arbitrary role identifier — apps own their role vocabulary, the framework does not. */
+export type McpRole = string;
+
+/**
+ * The resolved caller behind one MCP request. `actor` is the framework-wide authz subject
+ * (`kind: 'agent'` for a token-authenticated agent) and is what a projected action hands
+ * to `policy` — which is why an MCP call and an HTTP call reach the same decision.
+ */
+export interface McpCaller {
+  readonly actor: Actor;
+  /** Token scopes, checked by string membership against a tool's `scope`. */
+  readonly scopes: ReadonlySet<string>;
+  /** Absent = no role filter applies (the caller sees every unrestricted tool). */
+  readonly role?: McpRole;
+}
+
+/**
+ * Who may see a tool: a role list, or a predicate over the caller for a surface that derives
+ * visibility from something richer than a role name (`@ultimat3/admin` derives it from the
+ * actor's admin permissions).
+ *
+ * The predicate takes `McpCaller` and nothing else — it structurally CANNOT see call
+ * arguments, which is what makes "visibility is input-independent" an invariant rather than a
+ * convention. Two calls with different arguments therefore cannot reveal a tool's existence.
+ *
+ * Declarations (`mcp: { visibleTo: [...] }` on an action) stay a plain role list: a declared
+ * fact has to be static and serialisable for the manifest.
+ */
+export type McpVisibility = readonly McpRole[] | ((caller: McpCaller) => boolean);
+
+export type ContentBlock =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'resource'; readonly uri: string; readonly mimeType?: string };
+
+/**
+ * `tools/call` result. `isError` flags an EXPECTED tool-level failure (a policy denied the
+ * action, a queue was unreachable) so the model sees it as an outcome to reason about.
+ * Malformed requests and unknown methods are JSON-RPC errors instead.
+ */
+export interface McpToolResult {
+  readonly content: readonly ContentBlock[];
+  readonly isError?: boolean;
+}
+
+export type ToolArgs = Record<string, unknown>;
+
+export interface McpTool<A extends ToolArgs = ToolArgs> {
+  readonly name: string;
+  readonly description: string;
+  /** The only argument contract. Handed verbatim to the agent by `tools/list`. */
+  readonly inputSchema: JsonSchema;
+  /** Required scope. Absent = no scope gate (the tool's own policy is the gate). */
+  readonly scope?: string;
+  /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
+  readonly visibleTo?: McpVisibility;
+  /**
+   * Marks a tool that changes state. Drives the transport's rate-limit bucket and is
+   * asserted by tests over the dev server, so a new mutating tool cannot be metered as
+   * cheap read chatter by omission.
+   */
+  readonly destructive?: boolean;
+  // Method syntax (not a property) so a tool declared with narrower args stays assignable.
+  handle(args: A, caller: McpCaller): Promise<McpToolResult>;
+}
+
+export type AnyMcpTool = McpTool<ToolArgs>;
+
+/** One `tools/list` row — complete and standalone, no follow-up fetch required. */
+export interface ToolListEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: JsonSchema;
+}
+
+/** Rate-limit class of a call. Derived from `destructive`, never declared twice. */
+export type McpVerbClass = 'read' | 'write';
+
+/**
+ * True when `caller` may see (and therefore call) `tool`. See OUTCOME 1 above.
+ *
+ * FAIL-CLOSED, three ways:
+ *
+ *  1. A role list admits only the roles it names, so a caller with no role matches none of
+ *     them. The opposite — treating "no role" as "no filter applies" — hands an unroled
+ *     connection every restricted tool in the catalog.
+ *  2. A predicate must return the literal `true`. Author-supplied code returning something
+ *     merely truthy ("admin", 1, an object) would otherwise widen the gate by accident.
+ *  3. A predicate that THROWS denies. A predicate is app code that can fail for ordinary
+ *     reasons (`@ultimat3/admin` builds a request context inside its own), and an escaping
+ *     throw would answer `-32603` where a hidden tool answers `-32601` — a different error
+ *     code is exactly what a prober reads as "this tool exists", which is the enumeration
+ *     oracle OUTCOME 1 exists to remove. It would also break `list` outright for that
+ *     caller, turning one broken audience into an empty catalog.
+ */
+export function visibleToCaller(tool: AnyMcpTool, caller: McpCaller): boolean {
+  const visibility = tool.visibleTo;
+  if (visibility === undefined) return true;
+  if (typeof visibility === 'function') {
+    try {
+      return visibility(caller) === true;
+    } catch {
+      return false;
+    }
+  }
+  return caller.role !== undefined && visibility.includes(caller.role);
+}
+
+/** The outcome of the two gates plus validation, before a tool runs. */
+export type ToolResolution =
+  | { readonly kind: 'ok'; readonly tool: AnyMcpTool; readonly args: ToolArgs }
+  | { readonly kind: 'not-found'; readonly name: string }
+  | { readonly kind: 'scope-denied'; readonly name: string; readonly scope: string }
+  | { readonly kind: 'invalid-args'; readonly name: string; readonly issues: readonly ArgIssue[] };
+
+export class ToolRegistry {
+  private readonly tools = new Map<string, AnyMcpTool>();
+
+  register(tool: AnyMcpTool): this {
+    if (this.tools.has(tool.name)) {
+      throw new McpDuplicateToolError(tool.name);
+    }
+    this.tools.set(tool.name, tool);
+    return this;
+  }
+
+  registerAll(tools: readonly AnyMcpTool[]): this {
+    for (const tool of tools) this.register(tool);
+    return this;
+  }
+
+  /** Raw lookup with NO gate applied — the resolver owns the gates. */
+  get(name: string): AnyMcpTool | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * `tools/list` payload, role-filtered and name-sorted. Sorted because an agent diffs
+   * this catalog between runs and map insertion order is not a contract.
+   */
+  list(caller?: McpCaller): readonly ToolListEntry[] {
+    const all = [...this.tools.values()];
+    const visible = caller === undefined ? all : all.filter((t) => visibleToCaller(t, caller));
+    return visible
+      .map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  }
+
+  names(caller?: McpCaller): readonly string[] {
+    return this.list(caller).map((t) => t.name);
+  }
+
+  /**
+   * Both gates then validation, in the only order that is safe:
+   *   1. visibility → not-found     (never reveals existence)
+   *   2. scope      → scope-denied  (safe: the caller was already shown the tool)
+   *   3. args       → invalid-args
+   *   4. policy     → inside `tool.handle`, which is why it is not here
+   * Validating before the gates would leak a schema to a caller that may not see the tool;
+   * running the policy before the scope gate would decide a refusal from attacker-supplied
+   * input. Absent and hidden collapse into ONE branch so the two cannot drift apart.
+   */
+  resolve(name: string, rawArgs: unknown, caller: McpCaller): ToolResolution {
+    const tool = this.tools.get(name);
+    if (tool === undefined || !visibleToCaller(tool, caller)) {
+      return { kind: 'not-found', name };
+    }
+    if (tool.scope !== undefined && !caller.scopes.has(tool.scope)) {
+      return { kind: 'scope-denied', name, scope: tool.scope };
+    }
+    const validation = validateArgs(tool.inputSchema, rawArgs ?? {});
+    if (!validation.ok) return { kind: 'invalid-args', name, issues: validation.issues };
+    return { kind: 'ok', tool, args: validation.value };
+  }
+
+  /**
+   * Rate-limit class of a call WITHOUT running it. Fail-closed: an unknown tool bills the
+   * strict bucket, because a probing client must never get the cheap one.
+   */
+  verbClass(name: string): McpVerbClass {
+    const tool = this.tools.get(name);
+    if (tool === undefined) return 'write';
+    return tool.destructive === true ? 'write' : 'read';
+  }
+}
+
+/** Registration is a boot-time programming error, so it throws rather than returning. */
+class McpDuplicateToolError extends Error {
+  constructor(name: string) {
+    super(`MCP tool already registered: ${name}`);
+    this.name = 'McpDuplicateToolError';
+  }
+}
+
+/** Convenience constructor for a one-block text result. */
+export function textResult(text: string, isError = false): McpToolResult {
+  const content: readonly ContentBlock[] = [{ type: 'text', text }];
+  // exactOptionalPropertyTypes: attach `isError` only when it is true.
+  return isError ? { content, isError: true } : { content };
+}
+
+/** JSON payload as a text block — stable 2-space form so an agent can diff two calls. */
+export function jsonResult(value: unknown): McpToolResult {
+  return textResult(JSON.stringify(value, null, 2));
+}