pluribus-context 0.3.37 → 0.3.39

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.39 - 2026-06-07
+
+- Added `pluribus demo mcp-telemetry-import`, a tiny npm-runnable converter from MCP `rpc-messages.jsonl`-style JSON-RPC traces into privacy-safe audit receipts that preserve attribution, redacted shapes, status, and timing gaps without storing raw tool payloads.
+
+## 0.3.38 - 2026-06-06
+
+- Added `pluribus demo mcp-audit-receipt`, a tiny npm-runnable demo that validates privacy-safe MCP tool-call audit events and low-cardinality usage metrics without logging raw prompts, args, results, tokens, or row data.
+
 ## 0.3.37 - 2026-06-06
 
 - Published the canonical top-level Agent Skills layout (`skills/*/SKILL.md`) and backwards-compatible legacy mirrors so external skill registries can keep source links verifiable while package users get the current recipes from npm.

package/bin/pluribus.js

@@ -67,7 +67,8 @@ OPTIONS (watch)
   --debounce      Debounce delay in ms (minimum 300, default 400)
 
 OPTIONS (demo)
-  --receipt       Validate a custom skill use-rate receipt JSON file
+  --receipt       Validate a custom demo receipt JSON file
+  --input         Import a custom demo input file, such as rpc-messages.jsonl
   --json          Print machine-readable demo results
 
 EXAMPLES
@@ -89,6 +90,10 @@ EXAMPLES
   pluribus watch --tools claude,cursor
   pluribus demo skill-use-rate
   pluribus demo skill-use-rate --json
+  pluribus demo mcp-audit-receipt
+  pluribus demo mcp-audit-receipt --json
+  pluribus demo mcp-telemetry-import
+  pluribus demo mcp-telemetry-import --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
@@ -100,7 +105,7 @@ const COMMAND_FLAGS = {
   validate: new Set(['source', 'update-imports']),
   audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations', 'fidelity-report']),
   watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
-  demo: new Set(['receipt', 'json']),
+  demo: new Set(['receipt', 'input', 'json']),
 }
 
 function getFlagNames(argv) {

package/examples/mcp-audit-receipts/README.md

@@ -0,0 +1,24 @@
+# MCP audit receipt demo
+
+This example validates a privacy-safe audit receipt for MCP `tools/call` activity.
+
+Run from any directory after `pluribus-context@latest` is published:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt
+npx --yes pluribus-context@latest demo mcp-audit-receipt --json
+```
+
+Or validate your own receipt shape:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt --receipt ./mcp-audit-receipt.json
+```
+
+The point is to split:
+
+- **audit events**: correlation IDs, hashed user/token subject, token scopes, tool name, redacted argument shape, status, duration, result shape, and error class;
+- **usage metrics**: low-cardinality counters/histograms such as tool name, status, and token scope;
+- **privacy boundary**: no raw prompts, raw SQL, row data, tokens, tool outputs, or private connection strings in the receipt.
+
+This is for MCP server/gateway operators who need to answer: “who invoked which tool, under what scope, and did it succeed?” without dumping sensitive content into logs.

package/examples/mcp-audit-receipts/mcp-audit-receipt.json

@@ -0,0 +1,70 @@
+{
+  "schema": "pluribus.mcp_tool_call_audit_receipt.v1",
+  "run_id": "mcp-audit-2026-06-06T22:00Z",
+  "generated_at": "2026-06-06T22:00:00Z",
+  "server": {
+    "name": "analytics-mcp",
+    "transport": "http",
+    "version": "1.4.0"
+  },
+  "client": {
+    "name": "claude-desktop",
+    "workspace": "hashed:7f3f0f5f"
+  },
+  "audit_policy": {
+    "raw_arguments": "redacted_shape_only",
+    "raw_results": "redacted_shape_only",
+    "privacy_boundary": "no prompts, raw SQL, row data, tokens, or private connection strings in receipt"
+  },
+  "tool_calls": [
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6GATEWAY",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read", "query:run"],
+      "tool_name": "query_database",
+      "args_shape": {
+        "database_id": "number",
+        "query": "redacted_sql",
+        "limit": "number"
+      },
+      "status": "ok",
+      "duration_ms": 184,
+      "result_shape": "rows:12 columns:4",
+      "error_class": null
+    },
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6DENIED",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read"],
+      "tool_name": "update_dashboard",
+      "args_shape": {
+        "dashboard_id": "number",
+        "mutation": "redacted_object"
+      },
+      "status": "denied",
+      "duration_ms": 12,
+      "result_shape": "policy_denial",
+      "error_class": "insufficient_scope"
+    }
+  ],
+  "usage_metrics": [
+    {
+      "name": "mcp_tool_calls_total",
+      "type": "counter",
+      "value": "1",
+      "labels": ["tool_name", "status", "token_scope"]
+    },
+    {
+      "name": "mcp_tool_call_duration_ms",
+      "type": "histogram",
+      "value": "184",
+      "labels": ["tool_name", "status"]
+    }
+  ]
+}

package/examples/mcp-telemetry-import/README.md

@@ -0,0 +1,27 @@
+# MCP telemetry import demo
+
+This example converts a tiny MCP `rpc-messages.jsonl`-style trace into the same privacy-safe audit receipt shape used by `pluribus demo mcp-audit-receipt`.
+
+Run from any directory after `pluribus-context@latest` includes this demo:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-telemetry-import
+npx --yes pluribus-context@latest demo mcp-telemetry-import --json
+```
+
+Or convert your own log:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-telemetry-import --input ./rpc-messages.jsonl --json
+```
+
+The point is not to store raw MCP payloads forever. The import keeps only:
+
+- request/session IDs;
+- hashed user/token subjects;
+- token scopes;
+- tool name;
+- redacted argument/result shape;
+- status, duration if timestamps exist, and error class.
+
+If only fallback `rpc-messages.jsonl` exists, the receipt can still prove tool-call attribution. If gateway telemetry is absent, latency/status coverage should be marked as a gap instead of silently implied.

package/examples/mcp-telemetry-import/sample-rpc-messages.jsonl

@@ -0,0 +1,4 @@
+{"timestamp":"2026-06-07T13:00:00.000Z","direction":"client_to_server","session_id":"sess_demo","user_id":"user-123","token_subject":"oauth-subject-456","token_scopes":["repo:read"],"message":{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"github.search_issues","arguments":{"query":"repo:org/app label:bug MCP audit","limit":5}}}}
+{"timestamp":"2026-06-07T13:00:00.142Z","direction":"server_to_client","session_id":"sess_demo","message":{"jsonrpc":"2.0","id":"1","result":{"content":[{"type":"text","text":"2 issues found"}],"isError":false}}}
+{"timestamp":"2026-06-07T13:00:02.000Z","direction":"client_to_server","session_id":"sess_demo","user_id":"user-123","token_subject":"oauth-subject-456","token_scopes":["repo:read"],"message":{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"github.create_issue","arguments":{"repo":"org/app","title":"Add audit log","body":"redacted before receipt export"}}}}
+{"timestamp":"2026-06-07T13:00:02.019Z","direction":"server_to_client","session_id":"sess_demo","message":{"jsonrpc":"2.0","id":"2","error":{"code":"insufficient_scope","message":"write scope required"}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "description": "AI context and rules sync CLI for Claude.md, Claude Code, Cursor, and Copilot instructions, with privacy-safe context receipts that prove what memory, tools, skills, compactions, and security findings crossed agent boundaries without logging raw content.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",

package/src/commands/demo.js

@@ -4,10 +4,16 @@
 
 import * as fs from 'fs'
 import * as path from 'path'
+import { createHash } from 'crypto'
 import { fileURLToPath } from 'url'
 
 const DEFAULT_DEMO = 'skill-use-rate'
+const SKILL_USE_RATE_DEMO = 'skill-use-rate'
+const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
+const MCP_TELEMETRY_IMPORT_DEMO = 'mcp-telemetry-import'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO, MCP_TELEMETRY_IMPORT_DEMO]
 const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
+const MCP_AUDIT_RECEIPT_SCHEMA = 'pluribus.mcp_tool_call_audit_receipt.v1'
 
 /**
  * @param {Record<string, string | boolean>} args
@@ -16,29 +22,44 @@ const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
 export async function runDemo(args, positional = []) {
   const demoName = positional[0] || DEFAULT_DEMO
 
-  if (demoName !== DEFAULT_DEMO) {
-    console.error(`❌ Unknown demo: ${demoName}`)
-    console.error('   Available demos: skill-use-rate')
-    process.exit(1)
+  switch (demoName) {
+    case SKILL_USE_RATE_DEMO:
+      return runSkillUseRateDemo(args)
+    case MCP_AUDIT_RECEIPT_DEMO:
+      return runMcpAuditReceiptDemo(args)
+    case MCP_TELEMETRY_IMPORT_DEMO:
+      return runMcpTelemetryImportDemo(args)
+    default:
+      console.error(`❌ Unknown demo: ${demoName}`)
+      console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
+      process.exit(1)
   }
+}
 
-  const receiptPath = typeof args.receipt === 'string' && args.receipt.trim()
-    ? path.resolve(process.cwd(), args.receipt)
-    : bundledSkillUseRateReceiptPath()
-
-  let receipt
+function readReceipt(receiptPath, label) {
   try {
-    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+    return JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
   } catch (err) {
-    console.error(`❌ Could not read skill use-rate receipt at ${receiptPath}: ${err.message}`)
+    console.error(`❌ Could not read ${label} receipt at ${receiptPath}: ${err.message}`)
     process.exit(1)
   }
+}
 
+function selectedReceiptPath(args, defaultPath) {
+  return typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : defaultPath
+}
+
+function runSkillUseRateDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledSkillUseRateReceiptPath())
+  const receipt = readReceipt(receiptPath, 'skill use-rate')
   const result = validateSkillUseRateReceipt(receipt)
+
   if (Boolean(args.json)) {
     console.log(JSON.stringify({
       ok: result.errors.length === 0,
-      demo: DEFAULT_DEMO,
+      demo: SKILL_USE_RATE_DEMO,
       receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
       summary: result.summary,
       warnings: result.warnings,
@@ -65,10 +86,108 @@ export async function runDemo(args, positional = []) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function selectedInputPath(args, defaultPath) {
+  return typeof args.input === 'string' && args.input.trim()
+    ? path.resolve(process.cwd(), args.input)
+    : defaultPath
+}
+
+function runMcpAuditReceiptDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledMcpAuditReceiptPath())
+  const receipt = readReceipt(receiptPath, 'MCP audit')
+  const result = validateMcpAuditReceipt(receipt)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: MCP_AUDIT_RECEIPT_DEMO,
+      receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
+      summary: result.summary,
+      warnings: result.warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP audit receipt')
+    console.log(`   Receipt: ${path.relative(process.cwd(), receiptPath) || receiptPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ MCP audit receipt ok: ${result.summary.toolCallCount} tool calls, ${result.summary.auditEventCount} audit events, ${result.summary.metricCount} metrics`)
+      for (const warning of result.warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: production MCP needs audit events and low-cardinality metrics, not raw prompt/tool dumps. Prove who invoked which tool, under which scope, with redacted argument/result shape.')
+      console.log('Try your own receipt: pluribus demo mcp-audit-receipt --receipt path/to/mcp-audit-receipt.json')
+    } else {
+      console.error('❌ MCP audit receipt invalid:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
+
+function runMcpTelemetryImportDemo(args) {
+  const inputPath = selectedInputPath(args, bundledMcpTelemetryJsonlPath())
+  let logText
+  try {
+    logText = fs.readFileSync(inputPath, 'utf8')
+  } catch (err) {
+    console.error(`❌ Could not read MCP telemetry JSONL at ${inputPath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  const imported = importMcpTelemetryJsonl(logText)
+  const result = validateMcpAuditReceipt(imported.receipt)
+  const warnings = [...imported.warnings, ...result.warnings]
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: MCP_TELEMETRY_IMPORT_DEMO,
+      input: path.relative(process.cwd(), inputPath) || inputPath,
+      summary: {
+        ...result.summary,
+        parsedEntryCount: imported.summary.parsedEntryCount,
+        matchedResponseCount: imported.summary.matchedResponseCount,
+        missingGatewayLatency: imported.summary.missingGatewayLatency,
+      },
+      receipt: imported.receipt,
+      warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP telemetry import')
+    console.log(`   Input: ${path.relative(process.cwd(), inputPath) || inputPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ MCP telemetry imported: ${imported.summary.parsedEntryCount} JSONL entries → ${result.summary.toolCallCount} audit receipt tool calls`)
+      if (warnings.length > 0) for (const warning of warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: rpc-messages.jsonl is a useful fallback, but it usually proves tool-call attribution before it proves gateway latency. Convert raw JSON-RPC traces into privacy-safe receipts, then mark missing gateway evidence explicitly.')
+      console.log('Try your own log: pluribus demo mcp-telemetry-import --input path/to/rpc-messages.jsonl --json')
+    } else {
+      console.error('❌ MCP telemetry import produced an invalid receipt:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
 function bundledSkillUseRateReceiptPath() {
   return fileURLToPath(new URL('../../examples/skill-use-rate-receipts/skill-use-rate-receipt.json', import.meta.url))
 }
 
+function bundledMcpAuditReceiptPath() {
+  return fileURLToPath(new URL('../../examples/mcp-audit-receipts/mcp-audit-receipt.json', import.meta.url))
+}
+
+function bundledMcpTelemetryJsonlPath() {
+  return fileURLToPath(new URL('../../examples/mcp-telemetry-import/sample-rpc-messages.jsonl', import.meta.url))
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []
@@ -153,3 +272,268 @@ export function validateSkillUseRateReceipt(receipt) {
     },
   }
 }
+
+
+export function importMcpTelemetryJsonl(logText) {
+  const warnings = []
+  const entries = []
+  const pending = new Map()
+  const toolCalls = []
+  let matchedResponseCount = 0
+  let missingGatewayLatency = true
+
+  for (const [lineIndex, rawLine] of logText.split(/\r?\n/).entries()) {
+    const line = rawLine.trim()
+    if (!line) continue
+    try {
+      const entry = JSON.parse(line)
+      entries.push(entry)
+      const message = unwrapMcpMessage(entry)
+      const timestamp = entry.timestamp || entry.time || message.timestamp || null
+
+      if (isToolCallRequest(message)) {
+        pending.set(String(message.id), { entry, message, timestamp, lineIndex })
+      } else if (message.id != null && pending.has(String(message.id))) {
+        const request = pending.get(String(message.id))
+        pending.delete(String(message.id))
+        matchedResponseCount++
+        const durationMs = durationBetween(request.timestamp, timestamp)
+        if (durationMs > 0) missingGatewayLatency = false
+        toolCalls.push(toolCallFromRequestResponse(request, message, durationMs))
+      }
+    } catch (err) {
+      warnings.push(`line ${lineIndex + 1} was skipped: invalid JSON (${err.message})`)
+    }
+  }
+
+  for (const request of pending.values()) {
+    toolCalls.push(toolCallFromRequestResponse(request, null, 0))
+  }
+
+  if (toolCalls.length === 0) warnings.push('no tools/call request/response pairs were found')
+  if (missingGatewayLatency) warnings.push('gateway.jsonl-style latency/status evidence is missing; fallback rpc-messages.jsonl can still prove tool-call attribution')
+
+  const receipt = {
+    schema: MCP_AUDIT_RECEIPT_SCHEMA,
+    run_id: 'mcp-telemetry-import-demo',
+    generated_at: '2026-06-07T13:00:00Z',
+    server: {
+      name: 'mcp-gateway-or-fallback-log',
+      transport: 'jsonrpc-jsonl',
+      version: 'unknown',
+    },
+    client: {
+      name: 'unknown-mcp-client',
+      workspace: 'redacted',
+    },
+    audit_policy: {
+      raw_arguments: 'redacted_shape_only',
+      raw_results: 'redacted_shape_only',
+      privacy_boundary: 'source JSONL may contain raw protocol data; receipt keeps only shapes, hashes, status, and timing evidence',
+    },
+    telemetry_source: {
+      kind: missingGatewayLatency ? 'rpc-messages.jsonl-fallback' : 'gateway-or-timestamped-jsonl',
+      parsed_entries: entries.length,
+      matched_responses: matchedResponseCount,
+    },
+    tool_calls: toolCalls,
+    usage_metrics: buildMcpUsageMetrics(toolCalls),
+  }
+
+  return {
+    receipt,
+    warnings,
+    summary: {
+      parsedEntryCount: entries.length,
+      matchedResponseCount,
+      missingGatewayLatency,
+    },
+  }
+}
+
+function unwrapMcpMessage(entry) {
+  return entry.message || entry.msg || entry.rpc || entry.jsonrpc_message || entry
+}
+
+function isToolCallRequest(message) {
+  return message && message.id != null && ['tools/call', 'tools.call', 'mcp.tools.call'].includes(message.method)
+}
+
+function toolCallFromRequestResponse(request, response, durationMs) {
+  const params = request.message.params || {}
+  const toolName = params.name || params.tool_name || params.tool || 'unknown_tool'
+  const status = response == null ? 'empty' : response.error ? 'error' : 'ok'
+  const resultShape = response == null ? 'missing_response' : response.error ? `error:${response.error.code || 'unknown'}` : shapeLabel(response.result)
+  const userSource = request.entry.user_id || request.entry.actor || request.entry.principal || request.entry.session_id || 'unknown-user'
+  const tokenSource = request.entry.token_subject || request.entry.token_id || request.entry.principal || 'unknown-token'
+
+  return {
+    event: 'mcp.tool_call',
+    request_id: String(request.message.id),
+    session_id: String(request.entry.session_id || request.entry.run_id || 'unknown-session'),
+    user_id_hash: privacyHash(userSource),
+    token_subject_hash: privacyHash(tokenSource),
+    token_scopes: Array.isArray(request.entry.token_scopes) && request.entry.token_scopes.length > 0 ? request.entry.token_scopes : ['unknown'],
+    tool_name: String(toolName),
+    args_shape: shapeObject(params.arguments || params.args || {}),
+    status,
+    duration_ms: Math.max(0, durationMs),
+    result_shape: resultShape,
+    error_class: response?.error ? String(response.error.code || response.error.message || 'mcp_error') : null,
+  }
+}
+
+function buildMcpUsageMetrics(toolCalls) {
+  const callsByStatus = new Map()
+  for (const call of toolCalls) {
+    const key = `${call.tool_name}:${call.status}:${call.token_scopes[0] || 'unknown'}`
+    callsByStatus.set(key, (callsByStatus.get(key) || 0) + 1)
+  }
+  const metrics = [...callsByStatus.entries()].map(([key, value]) => ({
+    name: 'mcp_tool_calls_total',
+    type: 'counter',
+    value: String(value),
+    labels: ['tool_name', 'status', 'token_scope'],
+    dimensions: key,
+  }))
+  const durations = toolCalls.filter((call) => call.duration_ms > 0)
+  if (durations.length > 0) {
+    metrics.push({
+      name: 'mcp_tool_call_duration_ms',
+      type: 'histogram',
+      value: String(Math.round(durations.reduce((sum, call) => sum + call.duration_ms, 0) / durations.length)),
+      labels: ['tool_name', 'status'],
+    })
+  }
+  return metrics.length > 0 ? metrics : [{ name: 'mcp_tool_calls_total', type: 'counter', value: '0', labels: ['tool_name', 'status'] }]
+}
+
+function durationBetween(start, end) {
+  if (!start || !end) return 0
+  const started = Date.parse(start)
+  const ended = Date.parse(end)
+  if (Number.isNaN(started) || Number.isNaN(ended) || ended < started) return 0
+  return ended - started
+}
+
+function privacyHash(value) {
+  return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`
+}
+
+function shapeObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, shapeLabel(nested)]))
+}
+
+function shapeLabel(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return `array:${value.length}`
+  if (typeof value === 'object') return `object:${Object.keys(value).length}`
+  if (typeof value === 'string') return looksSensitive(value) ? 'redacted_string' : 'string'
+  if (typeof value === 'number') return 'number'
+  if (typeof value === 'boolean') return 'boolean'
+  return typeof value
+}
+
+function looksSensitive(value) {
+  return /select\s|insert\s|update\s|delete\s|token|secret|password|bearer/i.test(value)
+}
+
+export function validateMcpAuditReceipt(receipt) {
+  const errors = []
+  const warnings = []
+
+  function requireString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      errors.push(`${field} must be a non-empty string`)
+    }
+  }
+
+  function requireArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+      errors.push(`${field} must be a non-empty array`)
+    }
+  }
+
+  function requireNonNegativeNumber(value, field) {
+    if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+      errors.push(`${field} must be a non-negative number`)
+    }
+  }
+
+  if (receipt.schema !== MCP_AUDIT_RECEIPT_SCHEMA) {
+    errors.push(`schema must be ${MCP_AUDIT_RECEIPT_SCHEMA}`)
+  }
+
+  requireString(receipt.run_id, 'run_id')
+  requireString(receipt.generated_at, 'generated_at')
+  requireString(receipt.server?.name, 'server.name')
+  requireString(receipt.server?.transport, 'server.transport')
+  requireString(receipt.client?.name, 'client.name')
+  requireString(receipt.audit_policy?.raw_arguments, 'audit_policy.raw_arguments')
+  requireString(receipt.audit_policy?.raw_results, 'audit_policy.raw_results')
+  requireString(receipt.audit_policy?.privacy_boundary, 'audit_policy.privacy_boundary')
+  requireArray(receipt.tool_calls, 'tool_calls')
+  requireArray(receipt.usage_metrics, 'usage_metrics')
+
+  if (receipt.audit_policy?.raw_arguments !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_arguments must be redacted_shape_only')
+  }
+  if (receipt.audit_policy?.raw_results !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_results must be redacted_shape_only')
+  }
+
+  const lowCardinalityMetricLabels = new Set(['tool_name', 'status', 'token_scope', 'user_type'])
+
+  for (const [index, call] of (receipt.tool_calls || []).entries()) {
+    const prefix = `tool_calls[${index}]`
+    requireString(call.event, `${prefix}.event`)
+    requireString(call.request_id, `${prefix}.request_id`)
+    requireString(call.session_id, `${prefix}.session_id`)
+    requireString(call.user_id_hash, `${prefix}.user_id_hash`)
+    requireString(call.token_subject_hash, `${prefix}.token_subject_hash`)
+    requireArray(call.token_scopes, `${prefix}.token_scopes`)
+    requireString(call.tool_name, `${prefix}.tool_name`)
+    requireString(call.status, `${prefix}.status`)
+    requireNonNegativeNumber(call.duration_ms, `${prefix}.duration_ms`)
+    requireString(call.result_shape, `${prefix}.result_shape`)
+
+    if (call.event !== 'mcp.tool_call') errors.push(`${prefix}.event must be mcp.tool_call`)
+    if (!['ok', 'empty', 'error', 'timeout', 'denied'].includes(call.status)) {
+      errors.push(`${prefix}.status must be one of ok|empty|error|timeout|denied`)
+    }
+    if (!call.args_shape || typeof call.args_shape !== 'object' || Array.isArray(call.args_shape)) {
+      errors.push(`${prefix}.args_shape must be an object with redacted argument types/shapes`)
+    }
+    if (typeof call.args_preview === 'string' || typeof call.result_preview === 'string') {
+      errors.push(`${prefix} must not include raw args/results previews; use args_shape/result_shape instead`)
+    }
+    if (call.error_class != null && typeof call.error_class !== 'string') {
+      errors.push(`${prefix}.error_class must be string or null`)
+    }
+  }
+
+  for (const [index, metric] of (receipt.usage_metrics || []).entries()) {
+    const prefix = `usage_metrics[${index}]`
+    requireString(metric.name, `${prefix}.name`)
+    requireString(metric.type, `${prefix}.type`)
+    requireString(metric.value, `${prefix}.value`)
+    requireArray(metric.labels, `${prefix}.labels`)
+
+    for (const label of metric.labels || []) {
+      if (!lowCardinalityMetricLabels.has(label)) {
+        warnings.push(`${prefix}.labels includes high-cardinality label ${label}; prefer ${[...lowCardinalityMetricLabels].join(', ')}`)
+      }
+    }
+  }
+
+  return {
+    errors,
+    warnings,
+    summary: {
+      toolCallCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      auditEventCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      metricCount: Array.isArray(receipt.usage_metrics) ? receipt.usage_metrics.length : 0,
+    },
+  }
+}

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.37'
+export const VERSION = '0.3.39'