opentel-mcp 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## 0.18.0
+
+Security observability: five small signals that help you notice some attacks
+and mistakes on an MCP server. This is **observability, not enforcement**:
+nothing here blocks a call, alters a response or authenticates anyone, and none
+of it records tool arguments, result content, tool descriptions or matched
+secrets (derived signals only: booleans, counts, type names, hashes, tool
+names). Every new feature is off by default except the auth failure counter,
+which adds no new data. No new metric label keys. Python (0.1.0) is not
+affected; these signals are JS-only (ADR 034). This is the first release made
+by the signed release workflow (npm provenance, SBOM).
+
+### Security
+
+- **Tool definition integrity (ADR 029).** New opt-in `toolIntegrity: {
+  enabled, pins }`. Each tool definition seen in `tools/list` (name, title,
+  description, inputSchema, outputSchema, annotations) is hashed with SHA-256
+  over a canonical JSON form (`computeToolDefinitionHash()`, new export).
+  Span events on the `tools/list` span report `mcp.tool.integrity.changed`
+  (differs from the first hash seen), `.pin_mismatch` (differs from `pins`;
+  high severity), `.added` and `.removed`, once per distinct new state, with
+  hashes and tool names only. New counter `mcp.tool.integrity_violations`
+  (label: `gen_ai.tool.name`). `server.getToolIntegrityHashes()` returns the
+  current hashes, and in dev mode (`setupNodeSdk: true`) a copy-pasteable
+  `pins` snippet is printed once to stderr. Works with `schemaDrift` disabled
+  and does not change the ADR 010 drift hash. Detection only: the first hash
+  seen is trusted unless pinned.
+- **Secret leak detection in tool output (ADR 030).** New opt-in
+  `secretLeakDetection: { enabled, maxScanBytes }` (default 65536). Text
+  content of successful and `isError` results is checked in-process with the
+  same detectors that scrub error text. Span attributes
+  `mcp.tool.secret_leak.detected`, `.types` (a closed set of six names),
+  `.count` and `.scan_truncated`; counter `mcp.tool.secret_leaks` (label:
+  `gen_ai.tool.name`). Never the matched text, its position or its
+  surroundings; the type is span-only; span status is unchanged. Pattern
+  based: it misses formats and can fire on look-alikes. The detectors gained
+  internal type names without any change to scrubbing, fingerprints or
+  `conformance/patterns.json`.
+- **Auth failure counter (ADR 031).** New always-on counter
+  `mcp.tool.auth_failures` (label: `gen_ai.tool.name`), +1 per failed call,
+  silent or thrown, classified into the existing `auth` category. Stays at zero
+  with `fingerprinting: false`. Burst detection is not in the library.
+- **Sensitive tool auditing (ADR 032).** New opt-in `sensitiveTools` (exact
+  names and `*` wildcards, matched in linear time). A matching call gets the
+  span attribute `mcp.tool.sensitive` and an `mcp.audit.sensitive_call` event
+  with outcome, duration and failure category. Never arguments or results. It
+  is telemetry, not a tamper-evident audit log.
+- **Clock-skew visibility (ADR 027 amendment).** A producer whose `asOf` is
+  ahead of this process's clock is now recorded as the span attribute
+  `mcp.tool.freshness.clock_skew_ms`, including inside the tolerance (an
+  `asOf` up to 5 s ahead used to be silently treated as "now"). New option
+  `staleness.clockSkewToleranceMs` (default `5000`, today's behavior; invalid
+  values are warned about and ignored). Verdicts are unchanged. Credit: the
+  r/mcp community.
+
+### Internal
+
+- **Test reliability.** Timing-sensitive tests were made deterministic: the
+  flush-on-exit child-process tests (the shutdown flush is now told apart from
+  the 5 s periodic metric print by a stderr readiness marker, a longer hang
+  guard, a monotonic clock for the cap check), the thrash benchmark (no spy on
+  the timed loop, a relative bound instead of an absolute throughput floor)
+  and a staleness test that assumed the wall clock never steps backwards. The
+  global `testTimeout` raise was reverted; two tests carry their own timeouts.
+- **Tooling.** Test tooling moved from vitest 5 (which requires Node 22.12+)
+  to vitest 4.1.12 so the suites run on every Node version in `engines`
+  (`>=20`). The `engines` field is unchanged. Runtime dependencies are
+  unchanged.
+
+## 0.17.0
+
+Staleness detection: a read tool that returns data older than its own
+freshness window now shows up, even though the call succeeded. Suggested by
+the r/mcp community. Opt-in per tool; tools that don't report freshness
+are untouched. No new metric label keys.
+
+### Added
+
+- **Staleness detection (ADR 027, `docs/adr/027-staleness-detection.md`).**
+  A tool reports freshness in its result's `_meta` under
+  `FRESHNESS_META_KEY` (`'io.github.thirumalaiboobathi.opentel-mcp/freshness'`,
+  a reverse-DNS key per the MCP spec): `{ asOf, maxAgeMs }` or
+  `{ asOf, freshUntil }` (both allowed; the earlier deadline wins).
+  `asOf`/`freshUntil` are epoch milliseconds or ISO 8601 strings with a
+  timezone. Every successful `tools/call` carrying it gets:
+  - span attributes `mcp.tool.freshness.verdict` (`fresh` | `stale` |
+    `unknown`), `.data_age_ms`, `.max_age_ms`, `.limit_source`
+    (`max_age_ms` | `fresh_until` | `config`) and, for `unknown`,
+    `.unknown_reason` (`invalid_as_of` | `future_as_of` | `missing_window`
+    | `invalid_window`);
+  - `+1` on the new `mcp.tool.stale_responses` counter (label:
+    `gen_ai.tool.name` only) when stale.
+  - **Stale is not an error:** span status stays `OK`, no `error.type`,
+    never a silent failure, ToolOutcome stays `SUCCESS`.
+  - Responses without the key get no verdict and no attributes.
+    `isError: true` responses are skipped.
+  - Malformed input (epoch seconds, timezone-less ISO strings, negative
+    windows, `freshUntil` before `asOf`, `asOf` more than 5 s in the
+    future, throwing getters…) never throws: it yields `unknown` with a
+    reason and at most one `diag.warn` per tool.
+  - Only `asOf`, `maxAgeMs` and `freshUntil` under that one key are read;
+    content and other `_meta` fields are never read for this, and raw
+    values never reach spans, metrics or logs (canary-tested).
+- **`staleness` option.** `staleness.tools[toolName].maxAgeMs` overrides a
+  tool's own window (config can't supply `asOf`); `staleness.enabled:
+  false` turns the feature off. On by default, which is a no-op for tools
+  that don't report freshness.
+- **Types:** `FRESHNESS_META_KEY`, `FreshnessMeta` (autocomplete for the
+  `_meta` value), `FreshnessTimestamp`, `FreshnessVerdict`, and
+  `InstrumentOptions.staleness`.
+
+### Security
+
+- **Credentials are scrubbed from recorded exceptions, in every mode.**
+  Bearer and Basic tokens, AWS access key ids, `sk-`/`sk-proj-`/`sk-ant-`,
+  Stripe, `ghp_`/`github_pat_`, Slack `xox…` and Google `AIza…` keys, JWTs,
+  passwords in URLs (`https://user:<password>@host`), and the values of keys like
+  `token=`, `api_key=`, `access_token=`, `password=`, `client_secret` are
+  replaced with `<SECRET>`. Ordinary words and ids (`token expired`, UUIDs,
+  commit hashes) are left alone.
+- **Behavior change: the default `errorRecording.mode: 'full'` is no
+  longer raw and uncapped.** It still records the error's type, message and
+  stack, keeping ids, paths, URLs and line numbers, but with credentials
+  scrubbed as above, the message capped at 4096 characters and the stack at
+  16384 (a ` …[truncated by opentel-mcp]` marker shows where).
+  `exception.type` is capped at 128 characters, as in `'normalized'` mode.
+  Ordinary errors are recorded exactly as before. There is no switch back
+  to unscrubbed output. To record *less*, use `'normalized'`, `'none'`, or
+  a `redactor`.
+- **Fingerprints change only for errors that contain a credential.** The
+  same patterns now run first in `'normalized'` mode and in fingerprinting,
+  so two errors that differ only by a leaked token now share one
+  fingerprint (before, each token value made its own). Expect a one-time
+  regrouping of those errors only.
+- A thrown value whose properties throw when read (e.g. a throwing
+  `message` getter) now still marks the span `ERROR`; before, the span was
+  left with no status.
+- New test: one canary test runs every feature at once (fingerprinting,
+  cost and budget, thrash, schema drift, unactionable errors,
+  resources/prompts coverage, staleness) on SDK v1 and v2, `Server` and
+  `McpServer`, and checks that no tool argument, result content, `_meta`
+  value, resource URI, prompt argument or request `_meta` reaches any span,
+  metric or diag log. Nothing leaked; no code change was needed.
+- New `SECURITY.md` at the repository root: private vulnerability reporting
+  and what the library does and doesn't record.
+
+### Changed
+
+- The cost extractor and staleness detection now read `result._meta`
+  through one shared accessor (`src/result-meta.js`). Extraction behavior is
+  unchanged.
+- Dev-mode metrics (`setupNodeSdk: true`) print 13 instruments, up from 12.
+- README examples and `examples/hello-mcpserver` use `registerTool()`
+  instead of the deprecated `server.tool()`.
+- README's configuration table now lists `unactionableErrors`, `coverage`
+  and `staleness`; the misplaced `unactionableErrors` doc comment in
+  `index.d.ts` is back on its own option.
+- Test: the flush-on-exit "capped at 1000 ms" check now allows up to 5 s
+  (half the uncapped 10 s), so a loaded CI runner can't fail it.
+
 ## 0.16.0
 
 Finishes what 0.15 started. Telemetry now survives the way MCP clients