docs/security.md

Security design

Trace2MCP separates three decisions: what was observed, what was compiled, and what is authorized to execute. Trace labels and aliases never override trusted runtime contracts.

The default policy allows pure and read, requires approval for write and external_side_effect, and denies delete and unknown. Contract hashes detect drift. Workflow hashes detect artifact changes. Generated adapters start as inert stubs; generated contracts start unreviewed and are preserved during regeneration.

All supported capability paths converge on RuntimeDispatcher.dispatch. The dispatcher captures the exact handler/contract pair, checks policy and approvals, detects registry mutation, validates arguments, optionally asks a RuntimeGuard, invokes the same bound handler, and validates its output. Managed nested calls return through the same boundary. Unknown, uncontracted, unreviewed, malformed, changed, guard-denied, or guard-error capabilities are rejected before their handler begins.

Threats considered include malicious trace data, effect-label spoofing, ambiguous value matches, secret leakage, JSON parser abuse, path/symlink overwrite, contract drift, unbounded parallelism, unsafe retries, and orphaned tasks. See SECURITY.md for the operational boundary and reporting guidance.