@ultimat3/mcp 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -113,6 +113,23 @@ import. The CLI wires it.
   terminal. `server.ts` renders it; the test pins it against `format()`, never a literal.
 - Every outcome is audited via `audit.ts`, hidden included, at `warn`. Never log arguments
   or row data — a denial reason naming a row is a leak wearing an audit line's clothes.
+- **A tool that renders its OWN `isError` result may NAME the code it refused with**
+  (`McpToolResult.code`), and `outcomeForResult` sends it through the same `outcomeForCode` a
+  THROWN error goes through. Audit-only: `server.ts` never puts it on the wire, because the code is
+  already inside the rendered body. Without it every self-rendered refusal was `policy-denied` at
+  `warn` — so `@ultimat3/admin`'s `X_ADMIN_INVALID` (a client mistyping an argument the published
+  JSON Schema could not have refused: admin publishes a `type` per field and nothing else) sat in
+  the bucket this package's enumeration alert watches. `X_ADMIN_INVALID` is `ARGUMENT_CODES`;
+  `X_INPUT_INVALID` deliberately stays `failed`, because a projected action publishes its WHOLE
+  schema and input this server already validated failing inside it means the two have drifted.
+  A result naming no code keeps the conservative `policy-denied`.
+- **A `--` comment ends at the first CR *or* LF, because that is Postgres' own boundary set**
+  (`readonly-sql.ts`). `non_newline` is `[^\n\r]`, so a bare CR ends the comment for the SERVER
+  and did not for this scanner: `select 1;--\rupdate members set role='admin'` was one statement
+  with no mutating keyword to all five layer-3 checks at once — the statement split, the read-leader
+  check, the write-keyword scan, the forbidden-call scan and the `FOR UPDATE` regex all read the
+  stripped form — and `verbatim()` handed the caller's bytes back to run. `endOfLineComment` is the
+  lexer's set, never one character of it, the same shape `skipSingleQuoted` already had.
 - `security.test.ts` and `app-security.test.ts` are the executable contract for all of the
   above — the first over hand-built tools (each gate in isolation), the second over what an app
   actually declares (`defineAppMcp` projecting real actions and queries). Extend them, never
@@ -191,6 +208,17 @@ import. The CLI wires it.
 - `db.query` / `db.migrate` refuse structurally, in `readonly-sql.ts`, before the host runs
   (`X_MCP_QUERY_REJECTED` / `X_MCP_NOT_BRANCH_DB` — one code each, because they want different
   next commands).
+- `pg_notify` and the server-control / replication families are banned for the reason every other
+  family is: the same ban already exists in another spelling. `notify`/`listen`/`unlisten` are
+  WRITE KEYWORDS, so `pg_notify()` is `NOTIFY` as a call the keyword scan cannot see;
+  `pg_cancel_backend`/`pg_terminate_backend` establish that server control belongs, so
+  `pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote` and `pg_wal_replay_*` join them; and
+  `pg_logical_slot_get_changes` is `nextval`'s argument exactly — it advances a slot's confirmed
+  position, a write with no keyword that no `ROLLBACK` undoes — which brings `pg_create_*`,
+  `pg_drop_*`, `pg_replication_*` and `pg_logical_*` with it. `pg_file_*` is the writing half of
+  `pg_read_*`. `txid_current`/`pg_current_xact_id` ASSIGN a transaction id a rollback does not
+  return. The catalog VIEWS beside them (`pg_replication_slots`, `pg_stat_replication`) are read
+  `from` and never called, so the call scan never sees them.
 - Banned SQL functions are matched as a **prefix of a CALLED function name**, so the family is the
   unit and a spelling nobody wrote down is refused rather than admitted — an exact-name list let
   `pg_sleep_for` past a ban on `pg_sleep`, and `set_config` past `SET`, which is already a write

package/README.md

@@ -79,7 +79,7 @@ strand a well-behaved client.
 | A predicate audience sees the caller and nothing else | it is handed `McpCaller` — never the call arguments, so two calls with different inputs cannot answer differently. Must return the literal `true`; if it throws, the tool is hidden |
 | `tools/list` is answered per caller | filtered on every call against the caller the transport resolved — one per HTTP request, one per stdio connection — never a static catalog |
 | Gate order | visibility → scope → arguments → policy; the scope gate never waits on a policy run against attacker-supplied input |
-| Every outcome is audited | one line per `tools/call`; hidden/scope/policy at `warn`, ok at `info` — see `audit.ts` |
+| Every outcome is audited | one line per `tools/call`; hidden/scope/policy at `warn`, ok and invalid-args at `info` — see `audit.ts`. A tool that renders its OWN `isError` result may name the code it refused with (`McpToolResult.code`, audit-only, never on the wire) and is then classified by the same `outcomeForCode` a thrown error is — otherwise every self-rendered refusal lands in the `policy-denied` bucket a prober's name walk is alerted from |
 | Audit lines carry no payload | tool, outcome, actor, code. Never arguments, never rows |
 | No trusted-tool mode | there is no flag that skips policy evaluation |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "MCP server, dev tools, and the action-to-tool projection — one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,12 +31,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "8.0.0",
-    "@ultimat3/core": "8.0.0",
-    "@ultimat3/entity": "8.0.0",
-    "@ultimat3/jobs": "8.0.0",
-    "@ultimat3/policy": "8.0.0",
-    "@ultimat3/query": "8.0.0",
-    "@ultimat3/schema": "8.0.0"
+    "@ultimat3/action": "10.0.0",
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/entity": "10.0.0",
+    "@ultimat3/jobs": "10.0.0",
+    "@ultimat3/policy": "10.0.0",
+    "@ultimat3/query": "10.0.0",
+    "@ultimat3/schema": "10.0.0"
   }
 }

package/src/audit.ts

@@ -36,11 +36,46 @@ export type McpOutcome =
  * entry classified a code no build can produce — and every real denial that reached it still had
  * to be recognised by one of the other two.
  */
-const DENIAL_CODES: ReadonlySet<string> = new Set(['X_FORBIDDEN', 'X_UNAUTHENTICATED']);
+const DENIAL_CODES: ReadonlySet<string> = new Set([
+  'X_ADMIN_DENIED',
+  'X_FORBIDDEN',
+  'X_UNAUTHENTICATED',
+]);
+
+/**
+ * Codes that mean the CALLER got the arguments wrong, in a way the published JSON Schema could
+ * not have refused. `X_ADMIN_INVALID` is the case: `@ultimat3/admin` publishes a `type` per field
+ * and nothing else, so an entity's own rules are the first thing a value meets, and a mistyped
+ * `admin.create` is a client misreading a schema — `invalid-args`, at `info`.
+ *
+ * `X_INPUT_INVALID` deliberately stays OUT: a projected action publishes its whole schema, so
+ * input this server already validated failing inside the action means the two have drifted, and
+ * that wants a human.
+ */
+const ARGUMENT_CODES: ReadonlySet<string> = new Set(['X_ADMIN_INVALID']);
 
 /** Classify a code a tool threw. Denials are outcome 3; everything else wants a human. */
 export function outcomeForCode(code: string): McpOutcome {
-  return DENIAL_CODES.has(code) ? 'policy-denied' : 'failed';
+  if (DENIAL_CODES.has(code)) return 'policy-denied';
+  return ARGUMENT_CODES.has(code) ? 'invalid-args' : 'failed';
+}
+
+/**
+ * Classify a result a tool RENDERED rather than threw.
+ *
+ * A tool may answer `isError` itself — `@ultimat3/admin` does, so the model reads code/cause/fix
+ * instead of a transport failure — and that answer used to be audited `policy-denied` at `warn`
+ * whatever it refused for. So a malformed `admin.create` landed in the bucket this file exists to
+ * make alertable: every refusal a prober can drive. A result that NAMES its code goes through
+ * `outcomeForCode`, the same classifier a thrown one goes through; one that names none keeps the
+ * conservative reading, because a tool cannot be assumed to have refused for a benign reason.
+ */
+export function outcomeForResult(result: {
+  readonly isError?: boolean;
+  readonly code?: string;
+}): McpOutcome {
+  if (result.isError !== true) return 'ok';
+  return result.code === undefined ? 'policy-denied' : outcomeForCode(result.code);
 }
 
 export interface McpAuditEntry {

package/src/errors.ts

@@ -42,7 +42,12 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(MCP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-const docsFor = (code: McpErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
+// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
+// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
+// answered 404, host included, on every error it has ever thrown; restating the replacement here
+// would be the same constant in eight places waiting to drift again.
 
 /**
  * OUTCOME 1 of three: a tool name reached the dispatcher that no VISIBLE tool answers to —
@@ -59,7 +64,6 @@ export class McpToolUnknownError extends UltimateError {
         input.visible.length > 0 ? input.visible.join(', ') : 'none'
       })`,
       fix: 'call tools/list to read the catalog this caller may use',
-      docs: docsFor('X_MCP_TOOL_UNKNOWN'),
     });
   }
 }
@@ -87,7 +91,6 @@ export class McpScopeDeniedError extends UltimateError {
         subject === 'tool'
           ? `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop "${input.scope}" from defineAppMcp({ scopes }); scopes are fixed for the life of a connection`
           : `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop scope: '${input.scope}' from the resource declaring "${input.name}"; scopes are fixed for the life of a connection`,
-      docs: docsFor('X_MCP_SCOPE_DENIED'),
     });
     this.scope = input.scope;
   }
@@ -100,7 +103,6 @@ export class McpArgsInvalidError extends UltimateError {
       code: 'X_MCP_ARGS_INVALID',
       cause: `arguments for "${input.name}" are invalid: ${input.issues.join('; ')}`,
       fix: `re-read the tool's inputSchema from tools/list and resend`,
-      docs: docsFor('X_MCP_ARGS_INVALID'),
     });
   }
 }
@@ -116,7 +118,6 @@ export class McpToolUnsafeError extends UltimateError {
       code: 'X_MCP_TOOL_UNSAFE',
       cause: `tool "${input.name}" declares no policy; an unguarded tool is a second door into the data`,
       fix: `add policy: '<resource>:<verb>' to the tool, reusing the permission its action uses`,
-      docs: docsFor('X_MCP_TOOL_UNSAFE'),
     });
   }
 }
@@ -143,7 +144,6 @@ export class McpToolUndeclaredError extends UltimateError {
       fix:
         "add mcp: { expose: true, description: '<what it does>' } beside the policy on each — " +
         "or drop it from the list and let include: 'exposed' project what opted in",
-      docs: docsFor('X_MCP_TOOL_UNDECLARED'),
     });
     this.names = input.names;
   }
@@ -176,7 +176,6 @@ export class McpToolDuplicateError extends UltimateError {
         sites.length > 0
           ? `rename one — "${input.name}" is projected by ${sites.join(' and ')}; change the name at one of them`
           : "rename one: the tool name is the primitive's export name, the `tools` record key, or an admin action's `name`",
-      docs: docsFor('X_MCP_TOOL_DUPLICATE'),
     });
     this.declaredBy = sites;
   }
@@ -194,7 +193,6 @@ export class McpResourceDuplicateError extends UltimateError {
       code: 'X_MCP_RESOURCE_DUPLICATE',
       cause: `two resources are registered at "${input.uri}"; a URI addresses one document`,
       fix: `give one of them its own URI — register({ uri: '${input.uri}-<what-it-is>', … }) — or drop the duplicate registration`,
-      docs: docsFor('X_MCP_RESOURCE_DUPLICATE'),
     });
   }
 }
@@ -215,7 +213,6 @@ export class McpScopeUnknownError extends UltimateError {
       code: 'X_MCP_SCOPE_UNKNOWN',
       cause: `scopes["${input.scope}"] names "${input.name}", which this server does not project (projected: ${projected})`,
       fix: `in defineAppMcp, spell it as one of the projected names above — or drop "${input.name}" from scopes["${input.scope}"]`,
-      docs: docsFor('X_MCP_SCOPE_UNKNOWN'),
     });
     this.projected = input.projected;
   }
@@ -239,7 +236,6 @@ export class McpScopeConflictError extends UltimateError {
       code: 'X_MCP_SCOPE_CONFLICT',
       cause: `tool "${input.name}" is claimed by two scopes ("${input.scopes[0]}" and "${input.scopes[1]}"); a tool carries one`,
       fix: `in defineAppMcp, keep "${input.name}" under the single scope a token must hold for it, and remove the other entry`,
-      docs: docsFor('X_MCP_SCOPE_CONFLICT'),
     });
     this.scopes = input.scopes;
   }
@@ -252,7 +248,6 @@ export class McpProtocolError extends UltimateError {
       code: 'X_MCP_PROTOCOL',
       cause: input.cause,
       fix: input.fix ?? `send a JSON-RPC 2.0 body: { jsonrpc: '2.0', id, method, params }`,
-      docs: docsFor('X_MCP_PROTOCOL'),
     });
   }
 }
@@ -275,7 +270,6 @@ export class McpQueryRejectedError extends UltimateError {
       code: 'X_MCP_QUERY_REJECTED',
       cause: input.cause,
       fix: input.fix,
-      docs: docsFor('X_MCP_QUERY_REJECTED'),
     });
   }
 }
@@ -295,7 +289,6 @@ export class McpNotBranchDbError extends UltimateError {
       code: 'X_MCP_NOT_BRANCH_DB',
       cause: input.cause,
       fix: input.fix,
-      docs: docsFor('X_MCP_NOT_BRANCH_DB'),
     });
   }
 }

package/src/readonly-sql.ts

@@ -89,7 +89,22 @@ const WRITE_KEYWORDS = new Set([
  *  - ADVANCE A SEQUENCE (`nextval`, `setval`) — a write that leaves no keyword behind, and one
  *    `ROLLBACK` does not undo: a consumed sequence value is gone, so a read can silently burn the
  *    next id a real insert would have taken. `currval`/`lastval` read the session and stay legal.
+ *    `txid_current`/`pg_current_xact_id` are the same ban one level down: they ASSIGN a real
+ *    transaction id to a read, and a rollback does not give it back;
+ *  - PUBLISH A MESSAGE — `pg_notify` is `NOTIFY` spelled as a call, and `notify`, `listen` and
+ *    `unlisten` are all write keywords above. The keyword scan cannot see it: it is one token;
+ *  - CONTROL THE SERVER (`pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`,
+ *    `pg_wal_replay_*`) — the family `pg_cancel_backend`/`pg_terminate_backend` already
+ *    established, in the spellings that reconfigure or fail over the server rather than a backend;
+ *  - CONSUME THE REPLICATION STREAM (`pg_create_*`, `pg_drop_*`, `pg_replication_*`,
+ *    `pg_logical_*`) — `pg_logical_slot_get_changes` advances a slot's confirmed position, so the
+ *    changes it returned are gone for the real consumer. Exactly the `nextval` argument: a write
+ *    with no keyword, and no `ROLLBACK` undoes it. The catalog VIEWS beside them
+ *    (`pg_replication_slots`, `pg_stat_replication`) are read `from`, never called, so the call
+ *    scan never sees them;
+ *  - WRITE A FILE (`pg_file_*`) — the other half of `pg_read_*`, which was banned from the start.
  *
+
  * 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
@@ -101,15 +116,31 @@ const FORBIDDEN_FUNCTIONS = [
   'nextval',
   'pg_advisory_',
   'pg_cancel_backend',
+  'pg_create_',
+  'pg_current_xact_id',
+  'pg_drop_',
+  'pg_file_',
+  'pg_logical_',
   'pg_ls_',
+  'pg_notify',
+  'pg_promote',
   'pg_read_',
+  'pg_reload_',
+  'pg_replication_',
+  'pg_rotate_',
   'pg_sleep',
   'pg_stat_file',
   'pg_stat_reset',
+  // Not reachable from `pg_stat_reset`: the extension spells the same reset with the statistics
+  // view's name in the middle, so a prefix of one is not a prefix of the other.
+  'pg_stat_statements_reset',
+  'pg_switch_',
   'pg_terminate_backend',
   'pg_try_advisory_',
+  'pg_wal_replay_',
   'set_config',
   'setval',
+  'txid_current',
 ];
 
 /** The family refusing `called`, or `undefined`. A prefix, so a new member is refused by default. */
@@ -291,8 +322,7 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
   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;
+      i = endOfLineComment(sql, i);
       out += ' ';
       continue;
     }
@@ -336,6 +366,24 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
   return out;
 }
 
+/**
+ * Where a `--` comment ends: the first CR **or** LF, or the end of the input.
+ *
+ * The boundary set is the lexer's, never one character of it. Postgres defines a line comment as
+ * `--` followed by `non_newline*`, and `non_newline` is `[^\n\r]` — so a bare CR ends the comment
+ * for the server. Scanning for `\n` alone blanked everything after a CR, and that tail is real SQL
+ * the server runs: `select 1;--\rupdate members set role='admin'` was one statement with no
+ * mutating keyword to every check in this file, and was handed back verbatim to be executed.
+ * Same shape as `skipSingleQuoted` below, which reads Postgres' escape rules rather than one of them.
+ */
+function endOfLineComment(sql: string, start: number): number {
+  for (let i = start + 2; i < sql.length; i += 1) {
+    const char = sql[i];
+    if (char === '\n' || char === '\r') return i;
+  }
+  return sql.length;
+}
+
 /** 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] ?? '');

package/src/registry.ts

@@ -66,6 +66,16 @@ export type ContentBlock =
 export interface McpToolResult {
   readonly content: readonly ContentBlock[];
   readonly isError?: boolean;
+  /**
+   * The `X_*` code an `isError` result refused with. AUDIT ONLY — never written to the wire,
+   * because the code is already in the rendered body the model reads.
+   *
+   * A tool that renders its own refusal was otherwise audited `policy-denied` whatever it refused
+   * for, so a tool's own ARGUMENT check landed in the bucket a prober's name walk is alerted from.
+   * Naming the code sends it through `outcomeForCode`, the classifier a THROWN error already goes
+   * through. Absent keeps the conservative reading.
+   */
+  readonly code?: string;
 }
 
 export type ToolArgs = Record<string, unknown>;

package/src/server.ts

@@ -5,7 +5,7 @@
 
 import { singleLine, stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
-import { auditToolCall, outcomeForCode } from './audit';
+import { auditToolCall, outcomeForCode, outcomeForResult } from './audit';
 import { McpScopeDeniedError } from './errors';
 import type { AnyMcpTool, McpCaller, McpToolResult, McpVerbClass, ToolListEntry } from './registry';
 import { ToolRegistry } from './registry';
@@ -202,12 +202,16 @@ export class McpServer {
       return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
     }
 
-    // A tool may answer `isError` itself (admin renders its own denial): still outcome 3.
+    // A tool may answer `isError` itself (admin renders its own denial). Outcome 3 unless it
+    // NAMED the code it refused with, in which case the same classifier a thrown error goes
+    // through decides — a tool's own argument check is not a denial a prober drove.
     auditToolCall({
       tool: name,
-      outcome: result.isError === true ? 'policy-denied' : 'ok',
+      outcome: outcomeForResult(result),
       caller,
+      ...(result.code === undefined ? {} : { code: result.code }),
     });
+    // `code` is audit-only and never reaches the wire: it is already inside the rendered body.
     const payload: Record<string, unknown> = { content: result.content };
     if (result.isError === true) payload['isError'] = true;
     return resultResponse(id, payload);