feat(core): enforce project MCP trust boundaries

[sethkarten]

Core-05: project MCP declarations and trust boundaries

Draft publication for stack visibility. Validation is in progress and will be appended to this PR.

Scope

• 23 project-MCP declaration, trust, redaction, runtime-snapshot, settings, SDK/public composition, and focused test paths
• declaration/config reachability probe contracts only; transport probe execution remains Core-08
• preserves Core-02 capability wrappers and caller-provided MCP manager authority

Hard exclusions

• no cleanup/lifecycle/recovery changes
• no Core-08 transport-probe execution
• no release metadata

Parent: Core-04 #1262 at 4e9c1f2cbfe072d5226f0e49d37e799b6cdce345
Head: 6e8e33c484a26498d41022accd5f118ebe7822fc

Post-publication objective gates are in progress; valid findings will be fixed append-only.

Note

Enforce MCP project trust boundaries with admission-gated declaration management

• Introduces a full MCP declaration system: CLI command (mcp), document parsing/validation, URL canonicalization, redaction, and per-scope (user/project) read/write via mcp-declarations.ts and mcp-declaration-command.ts.
• Adds a McpProjectTrustAuthority (project-trust-authority.ts) that pins OS directory file descriptors to canonical project paths, issues opaque bindings, and validates them against a revisioned, digest-verified policy snapshot to prevent TOCTOU races.
• Project MCP declarations are only included in runtime snapshots when a valid ProjectMcpDeclarationAdmission is held; admission is derived from a global-only policy (mcpProjectTrustPolicy) and released after use.
• Project settings are read/written via a sandboxed Python openat-style helper (project-settings-openat.ts) that operates over a trusted file descriptor, never exposing raw project paths.
• McpManager and both the SDK (sdk.ts) and agent session (agent-session-services.ts) entry points now build an immutable McpRuntimeDeclarationSnapshot from global + conditionally admitted project declarations, replacing direct settings reads.
• Risk: project MCP declarations are silently omitted (fail-closed) when admission is absent, stale, forged, or the project directory is replaced, rather than falling back to any cached data.

^{Macroscope summarized f0bfce6.}

Final validation

• Head: 1f23778f9a94673de05eff5eecdab15045363c01
• Non-writing Biome: all Core-05 changed paths pass (final three formatting diagnostics fixed manually)
• Root tsgo --noEmit: pass
• Configured MCP regressions: 8 files, 50/50 tests pass
• Env-sanitized daemon-mode regression: 195/195 tests pass
• git diff --check: pass; worktree clean
• Transport probing is deferred to Core-08. Core-05 mcp test is preview-only and cannot call transport.open, eliminating late-open session leakage at this layer.

---

Note

High Risk
New security-critical paths for project MCP (trust bindings, TOCTOU checks, openat settings I/O) and behavior changes: project legacy MCP servers no longer drive host integrations; project declarations require explicit global trust.

Overview
Adds a prime-agent mcp CLI for credential-free MCP declaration records (list, inspect, preview, test, add, enable, disable, remove, optional --project). Output is redacted JSON; mcp test is preview-only (no transport/network).

Introduces M01 declarations (name, url, enabled) with strict parsing and settings APIs (getMcpDeclarationDocument / setMcpDeclarationDocument). Project scope is gated by global-only mcpProjectTrustPolicy: opaque admissions, retained-directory trust authority, and descriptor-relative project I/O via a sandboxed Python openat helper—denied or malformed policy must not open project settings (CLI loads global settings first for --project).

Runtime builds an immutable declaration snapshot (user + admitted project; name/endpoint collisions drop the whole project contribution). McpManager still resolves legacy integrations from global mcpServers only; snapshots are exposed separately and do not register OAuth/host handlers. SDK and session service creation compose project admission/readers before merging declarations; injected mcpManager is unchanged.

^{Reviewed by Cursor Bugbot for commit f0bfce6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 35de6e2. Configure here.}

[sethkarten]

Superseded by #1337 as part of the physical Core/MCP stack split. The replacement preserves this PR’s reviewed semantic delta on the corrected shared #1243 foundation. Closing this PR to avoid duplicate review; branch retained for provenance.