@ultimat3/mcp 10.0.0 → 11.0.0

package/CLAUDE.md

@@ -12,7 +12,7 @@ import. The CLI wires it.
 |---|---|
 | `wire.ts` | JSON-RPC types, error codes, protocol version, `JsonSchema` subset |
 | `registry.ts` | catalog + the first two security outcomes (visibility, scope) |
-| `audit.ts` | one structured line per `tools/call`, outcome → level |
+| `audit.ts` | one structured line per `tools/call` and per `resources/read`, outcome → level |
 | `validate-args.ts` | JSON-Schema-subset arg validation, applies defaults |
 | `server.ts` | JSON-RPC dispatch, `classify` for rate-limit buckets |
 | `from-action.ts` | action/query → tool; the "one authz system" projection; `toolsFrom` (sweep, skips) vs `toolsListed` (written out, refuses) |
@@ -113,6 +113,14 @@ 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.
+  **On both surfaces**: `mcp.tool-call.<outcome>` from `toolsCall`, `mcp.resource-read.<outcome>`
+  from `resourcesRead`, one `LEVEL` table and one field builder behind them. `resources/read`
+  emitted nothing at all until 2026-08-23, so a URI walk over the four documents that describe an
+  app's whole policy and data map left no trace while the identical walk over tool NAMES was one
+  `warn` per attempt. Two EVENTS and not one, because an alert that buckets a document read as a
+  tool call cannot tell the two walks apart. `resources/list` and `tools/list` are both silent by
+  design — each is answered pre-filtered, so it reveals only what the caller could already see.
+  `resource-security.test.ts` reads BOTH streams: core's logger puts `error` on stderr.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "10.0.0",
+  "version": "11.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": "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"
+    "@ultimat3/action": "11.0.0",
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/entity": "11.0.0",
+    "@ultimat3/jobs": "11.0.0",
+    "@ultimat3/policy": "11.0.0",
+    "@ultimat3/query": "11.0.0",
+    "@ultimat3/schema": "11.0.0"
   }
 }

package/src/audit.ts

@@ -1,5 +1,5 @@
-// One structured line per `tools/call`, whatever the outcome — including the outcomes that
-// deliberately tell the caller nothing.
+// One structured line per `tools/call` and per `resources/read`, whatever the outcome — including
+// the outcomes that deliberately tell the caller nothing.
 //
 // The three-outcome model works by giving a prober no signal. That is a property of the
 // ANSWER, not of the system: enumeration is a pattern across many requests, so the refusal
@@ -88,19 +88,31 @@ export interface McpAuditEntry {
   readonly code?: string;
 }
 
+/** The same entry for the DOCUMENT surface, addressed by URI rather than by tool name. */
+export interface McpResourceAuditEntry {
+  readonly uri: string;
+  readonly outcome: McpOutcome;
+  readonly caller: McpCaller;
+  readonly scope?: string;
+  readonly code?: string;
+}
+
 /**
  * Severity per outcome. Every refusal a prober can drive is `warn` so one alert rule covers
  * the whole enumeration surface; `invalid-args` is a well-behaved client misreading a schema,
  * and an unexpected throw is the only `error` because it is the only one that is a bug.
  */
-const LEVEL = Object.freeze<Record<McpOutcome, 'info' | 'warn' | 'error'>>({
-  ok: 'info',
-  hidden: 'warn',
-  'scope-denied': 'warn',
-  'policy-denied': 'warn',
-  'invalid-args': 'info',
-  failed: 'error',
-});
+const LEVEL: ReadonlyMap<McpOutcome, 'info' | 'warn' | 'error'> = new Map([
+  ['ok', 'info'],
+  ['hidden', 'warn'],
+  ['scope-denied', 'warn'],
+  ['policy-denied', 'warn'],
+  ['invalid-args', 'info'],
+  ['failed', 'error'],
+]);
+// An outcome is a closed union, so the `Map` is total; `?? 'error'` is the type's witness, not a
+// reachable branch — a `Map` rather than a literal because the key is data (`proto-index`).
+const levelOf = (outcome: McpOutcome): 'info' | 'warn' | 'error' => LEVEL.get(outcome) ?? 'error';
 
 /**
  * Audit one call. `log` is a parameter so a test can read the line it produced; production
@@ -111,9 +123,41 @@ const LEVEL = Object.freeze<Record<McpOutcome, 'info' | 'warn' | 'error'>>({
  * that names `post p_42 in org o_9` is a row leak wearing an audit line's clothes.
  */
 export function auditToolCall(entry: McpAuditEntry, log: Logger = logger): void {
-  const fields: LogFields = {
-    surface: 'mcp',
+  // `<subsystem>.<event>.<outcome>`, matching every other structured line in the framework,
+  // so `x logs --json | grep mcp.tool-call.hidden` is the whole enumeration alert.
+  log[levelOf(entry.outcome)](`mcp.tool-call.${entry.outcome}`, {
     tool: entry.tool,
+    ...callerFields(entry),
+  });
+}
+
+/**
+ * Audit one `resources/read`, on the same three outcomes and at the same levels.
+ *
+ * The document surface owed this and emitted nothing at all: a URI walk over the four documents an
+ * app publishes — the manifest, the OpenAPI document, the route table and the entity schema, which
+ * together are its whole policy and data map — left no trace anywhere, while the identical walk
+ * over tool NAMES was one `warn` per attempt. The refusal that tells the caller nothing is exactly
+ * the one that has to reach whoever reads the logs.
+ *
+ * A separate EVENT rather than a `tool:` field holding a URI: an alert rule that buckets a
+ * document read as a tool call cannot tell the two walks apart, and a field named `tool` carrying
+ * `ultimate://manifest` is a lie a query has to work around forever.
+ *
+ * `resources/list` is deliberately NOT audited, exactly as `tools/list` is not — it is answered
+ * pre-filtered, so it reveals only what the caller could already see.
+ */
+export function auditResourceRead(entry: McpResourceAuditEntry, log: Logger = logger): void {
+  log[levelOf(entry.outcome)](`mcp.resource-read.${entry.outcome}`, {
+    resource: entry.uri,
+    ...callerFields(entry),
+  });
+}
+
+/** What every audit line carries whatever it is about. Fields carry the DECISION, never the data. */
+function callerFields(entry: McpResourceAuditEntry | McpAuditEntry): LogFields {
+  return {
+    surface: 'mcp',
     outcome: entry.outcome,
     actor: entry.caller.actor.id,
     actorKind: entry.caller.actor.kind,
@@ -121,7 +165,4 @@ export function auditToolCall(entry: McpAuditEntry, log: Logger = logger): void
     ...(entry.scope === undefined ? {} : { scope: entry.scope }),
     ...(entry.code === undefined ? {} : { code: entry.code }),
   };
-  // `<subsystem>.<event>.<outcome>`, matching every other structured line in the framework,
-  // so `x logs --json | grep mcp.tool-call.hidden` is the whole enumeration alert.
-  log[LEVEL[entry.outcome]](`mcp.tool-call.${entry.outcome}`, fields);
 }

package/src/index.ts

@@ -13,8 +13,8 @@ export type {
 export { appToolPrimitive, appToolPrimitives } from './app-tool';
 export type { AppMcp, AppToolSchemas, DefineAppMcpInput } from './app-tools';
 export { defineAppMcp } from './app-tools';
-export type { McpAuditEntry, McpOutcome } from './audit';
-export { auditToolCall, outcomeForCode } from './audit';
+export type { McpAuditEntry, McpOutcome, McpResourceAuditEntry } from './audit';
+export { auditResourceRead, auditToolCall, outcomeForCode } from './audit';
 export type { CreateDevServerInput } from './dev-host';
 export { createDevServer, devHost, frameworkIntrospection } from './dev-host';
 export type {

package/src/server.ts

@@ -5,7 +5,7 @@
 
 import { singleLine, stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
-import { auditToolCall, outcomeForCode, outcomeForResult } from './audit';
+import { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
 import { McpScopeDeniedError } from './errors';
 import type { AnyMcpTool, McpCaller, McpToolResult, McpVerbClass, ToolListEntry } from './registry';
 import { ToolRegistry } from './registry';
@@ -221,6 +221,11 @@ export class McpServer {
    * The same three-outcome shape `toolsCall` above applies, on the document surface. It took no
    * caller at all until 2026-08: every accepted token could list every URI and read every one of
    * them — the manifest, the OpenAPI document, the route table and the entity schema.
+   *
+   * And every outcome is AUDITED, hidden included, exactly as `toolsCall`'s are: this method
+   * emitted nothing at all, so a URI walk over those four documents was invisible while the same
+   * walk over tool names was one `warn` per attempt. `resources/list` stays silent, as
+   * `tools/list` does — it is answered pre-filtered.
    */
   private async resourcesRead(req: JsonRpcRequest, caller: McpCaller): Promise<JsonRpcResponse> {
     const id = req.id ?? null;
@@ -232,8 +237,11 @@ export class McpServer {
     const resolved = this.resources.resolve(uri, caller);
     switch (resolved.kind) {
       // OUTCOME 1. Absent AND hidden collapse to one answer with no `data`: this branch used to
-      // return `available: [...every uri]`, so one wrong guess enumerated the whole catalog.
+      // return `available: [...every uri]`, so one wrong guess enumerated the whole catalog. No
+      // `code` on the audit line either, because the wire carries none — the tool surface's
+      // `X_MCP_TOOL_UNKNOWN` is an error class this branch has no twin for.
       case 'not-found':
+        auditResourceRead({ uri, outcome: 'hidden', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       // OUTCOME 2. The caller can already see this resource, so naming the missing scope leaks
       // nothing — and the fix travels with it, built by the error that owns the wording.
@@ -243,6 +251,13 @@ export class McpServer {
           scope: resolved.scope,
           subject: 'resource',
         });
+        auditResourceRead({
+          uri,
+          outcome: 'scope-denied',
+          caller,
+          scope: resolved.scope,
+          code: denial.code,
+        });
         return errorResponse(id, INVALID_REQUEST, `missing scope: ${resolved.scope}`, {
           code: denial.code,
           scope: resolved.scope,
@@ -262,12 +277,17 @@ export class McpServer {
     try {
       const contents = await this.resources.read(uri);
       if (contents === undefined) {
+        // The resolver said `ok` and the registry then had nothing: a bug here, not a walk, so it
+        // is `failed` in the log while the caller still gets the same not-found it would have.
+        auditResourceRead({ uri, outcome: 'failed', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       }
+      auditResourceRead({ uri, outcome: 'ok', caller });
       return resultResponse(id, { contents: [contents] });
     } catch (error) {
       const framework = asFrameworkError(error);
       if (framework !== undefined) {
+        auditResourceRead({ uri, outcome: 'failed', caller, code: framework.code });
         return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
           code: framework.code,
           cause: framework.cause,
@@ -276,6 +296,7 @@ export class McpServer {
       }
       // No internals: a provider's own message names a path, a query or a host the caller has no
       // business seeing, exactly as a failing tool's does.
+      auditResourceRead({ uri, outcome: 'failed', caller });
       return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`);
     }
   }