refactor(ddd): isolate MCP adapter contracts

CHANGELOG.md

@@ -48,6 +48,7 @@ All notable changes to OriginWeave are documented in this file. The format follo
 
 ### Changed
 
+- Active PR #272 hardens the MCP `2026-07-28` `tools/call` adapter so a validated call requires matching transport/request protocol versions and per-request client-capabilities presence; optional self-reported `clientInfo` is neither required nor retained as authority, and the former constructor shape now fails closed for otherwise valid legacy calls. This is active-PR evidence, not protected-main shipment.
 - Aligned the hourly product-development branch-coverage toolchain and its one-shot materializer with the reviewed `nightly-2026-08-18` pin, and corrected the official Dependabot Rust-toolchain reference.
 - Separated logical origin authority from resolved network destination authority; an origin grant no longer implies permission to connect to every resolver result.
 - Separated resolved-address authorization from direct transport evidence; an approved IP now becomes a usable stream only after the operating system reports the exact requested IP and port.
@@ -102,4 +103,4 @@ All notable changes to OriginWeave are documented in this file. The format follo
 - The hourly product agent has no Git metadata or repository authority. A separate post-verification publisher opens one PR and cannot approve or merge it.
 - The unprivileged OpenCode user is restricted to loopback egress during model execution, preventing runner-wide allow-listed endpoints from becoming direct source-exfiltration channels.
 
-[Unreleased]: https://github.com/ContextualWisdomLab/OriginWeave/compare/main...HEAD
+[Unreleased]: https://github.com/ContextualWisdomLab/OriginWeave/compare/main...HEAD

Cargo.toml

@@ -2,6 +2,7 @@
 members = [
     "crates/originweave-core",
     "crates/originweave-bap",
+    "crates/originweave-mcp",
     "crates/originweave-policy",
     "crates/originweave-resource",
     "crates/originweave-evidence",

crates/originweave-core/src/root.rs

@@ -11,7 +11,5 @@ mod contracts;
 
 pub use contracts::*;
 
-/// Stateless MCP routing validation that maps only explicit tools to typed actions.
-pub mod mcp;
 /// Deterministic fail-closed release benchmark acceptance aggregation.
 pub mod release_acceptance;

crates/originweave-mcp/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "originweave-mcp"
+description = "OriginWeave MCP adapter contracts."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+publish = false
+
+[dependencies]
+originweave-core = { path = "../originweave-core" }
+originweave-policy = { path = "../originweave-policy" }
+
+[lints]
+workspace = true

crates/originweave-mcp/src/lib.rs

@@ -0,0 +1,92 @@
+//! Fail-closed MCP adapter contracts for OriginWeave.
+//!
+//! This crate owns MCP protocol-generation, discovery, and stateless tool-routing
+//! contracts. It maps reviewed MCP protocol values into existing OriginWeave
+//! action contracts but grants no policy, browser, network, secret, or evidence
+//! authority.
+
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+
+use originweave_core::{ActionRequest, PolicyContext};
+use originweave_policy::Decision;
+
+pub(crate) use originweave_core::{ActionKind, Capability, RiskClass};
+
+mod request;
+mod routing;
+
+pub use request::{McpToolBoundaryError, ValidatedMcpToolCall};
+pub use routing::{
+    MAX_MCP_METHOD_NAME_BYTES, MAX_MCP_TOOL_NAME_BYTES, MCP_PROTOCOL_VERSION,
+    MCP_TOOLS_CALL_METHOD, MCP_TOOLS_LIST_METHOD, McpCacheScope, McpResultType,
+    McpToolCatalogEntry, McpToolsListBoundaryError, McpToolsListPage, ValidatedMcpToolsListRequest,
+    mcp_tools_list_page, supported_mcp_tools,
+};
+
+/// A fail-closed rejection owned by the MCP routing boundary rather than policy.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McpRouteRejection {
+    /// The validated MCP route resolves to a different action than the typed request.
+    ActionMismatch,
+}
+
+/// Evaluate one validated MCP route through the ordinary OriginWeave policy boundary.
+///
+/// Route validation proves only protocol integrity. It grants no capability, origin, approval,
+/// secret, browser, network, or evidence authority. A route/action mismatch is returned as an
+/// MCP-owned rejection before the request reaches policy. Callers may execute only
+/// `Ok(Decision::Allow)`; every other result remains non-authorizing.
+pub fn evaluate_mcp(
+    call: &ValidatedMcpToolCall,
+    request: &ActionRequest,
+    context: &PolicyContext,
+) -> Result<Decision, McpRouteRejection> {
+    if call.action_kind() != request.action() {
+        return Err(McpRouteRejection::ActionMismatch);
+    }
+
+    Ok(originweave_policy::evaluate(request, context))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::error::Error;
+
+    use super::routing::McpToolBoundaryError;
+
+    #[test]
+    fn private_routing_error_diagnostics_are_total_and_source_free() {
+        let cases = [
+            (
+                McpToolBoundaryError::UnsupportedProtocolVersion,
+                "unsupported MCP protocol version",
+            ),
+            (
+                McpToolBoundaryError::HeaderBodyMismatch,
+                "MCP routing headers do not match the request body",
+            ),
+            (
+                McpToolBoundaryError::InvalidMethod,
+                "MCP method violates the bounded ASCII routing syntax",
+            ),
+            (
+                McpToolBoundaryError::UnsupportedMethod,
+                "only MCP tools/call requests can enter the typed action boundary",
+            ),
+            (
+                McpToolBoundaryError::InvalidToolName,
+                "MCP tool name violates the bounded ASCII routing syntax",
+            ),
+            (
+                McpToolBoundaryError::UnknownTool,
+                "MCP tool is not mapped to an OriginWeave typed action",
+            ),
+        ];
+
+        for (error, message) in cases {
+            assert_eq!(error.to_string(), message);
+            assert!(error.source().is_none());
+        }
+    }
+}

crates/originweave-mcp/src/request.rs

@@ -0,0 +1,239 @@
+//! MCP 2026-07-28 request-envelope validation for typed tool calls.
+//!
+//! This adapter layer binds transport protocol metadata to the existing bounded
+//! tool-routing validator. It deliberately retains no client identity or
+//! capability contents and grants no OriginWeave browser, policy, secret, or
+//! evidence authority.
+
+use std::fmt;
+
+use crate::{ActionKind, MCP_PROTOCOL_VERSION, routing};
+
+/// A deterministic failure while validating one MCP `tools/call` request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McpToolBoundaryError {
+    /// The transport request omitted the required MCP protocol-version header.
+    MissingProtocolVersionHeader,
+    /// The structured request metadata omitted the required MCP protocol version.
+    MissingProtocolVersionMetadata,
+    /// The transport protocol version disagrees with the structured request metadata.
+    ProtocolVersionHeaderBodyMismatch,
+    /// The request names an MCP protocol generation this adapter does not support.
+    UnsupportedProtocolVersion,
+    /// The structured request metadata omitted the required client-capabilities object.
+    MissingClientCapabilities,
+    /// MCP routing metadata disagrees with the method or tool name in the body.
+    HeaderBodyMismatch,
+    /// The request method violates the bounded ASCII MCP routing syntax.
+    InvalidMethod,
+    /// The request method is not the supported `tools/call` operation.
+    UnsupportedMethod,
+    /// The tool name violates the bounded ASCII MCP routing syntax.
+    InvalidToolName,
+    /// The tool name has no explicit mapping to an OriginWeave typed action.
+    UnknownTool,
+}
+
+impl fmt::Display for McpToolBoundaryError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::MissingProtocolVersionHeader => {
+                formatter.write_str("MCP protocol version header is required")
+            }
+            Self::MissingProtocolVersionMetadata => {
+                formatter.write_str("MCP request metadata protocol version is required")
+            }
+            Self::ProtocolVersionHeaderBodyMismatch => {
+                formatter.write_str("MCP protocol version header does not match request metadata")
+            }
+            Self::UnsupportedProtocolVersion => {
+                formatter.write_str("unsupported MCP protocol version")
+            }
+            Self::MissingClientCapabilities => {
+                formatter.write_str("MCP request metadata client capabilities are required")
+            }
+            Self::HeaderBodyMismatch => {
+                formatter.write_str("MCP routing headers do not match the request body")
+            }
+            Self::InvalidMethod => {
+                formatter.write_str("MCP method violates the bounded ASCII routing syntax")
+            }
+            Self::UnsupportedMethod => formatter
+                .write_str("only MCP tools/call requests can enter the typed action boundary"),
+            Self::InvalidToolName => {
+                formatter.write_str("MCP tool name violates the bounded ASCII routing syntax")
+            }
+            Self::UnknownTool => {
+                formatter.write_str("MCP tool is not mapped to an OriginWeave typed action")
+            }
+        }
+    }
+}
+
+impl std::error::Error for McpToolBoundaryError {}
+
+impl From<routing::McpToolBoundaryError> for McpToolBoundaryError {
+    fn from(error: routing::McpToolBoundaryError) -> Self {
+        match error {
+            routing::McpToolBoundaryError::UnsupportedProtocolVersion => {
+                Self::UnsupportedProtocolVersion
+            }
+            routing::McpToolBoundaryError::HeaderBodyMismatch => Self::HeaderBodyMismatch,
+            routing::McpToolBoundaryError::InvalidMethod => Self::InvalidMethod,
+            routing::McpToolBoundaryError::UnsupportedMethod => Self::UnsupportedMethod,
+            routing::McpToolBoundaryError::InvalidToolName => Self::InvalidToolName,
+            routing::McpToolBoundaryError::UnknownTool => Self::UnknownTool,
+        }
+    }
+}
+
+/// An MCP tool call whose required request metadata and routing envelope were validated.
+///
+/// The value proves protocol-envelope integrity only. Client capability contents and optional
+/// `clientInfo` are deliberately not retained because self-reported client metadata is not an
+/// OriginWeave authorization signal.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ValidatedMcpToolCall {
+    routed: routing::ValidatedMcpToolCall,
+}
+
+impl ValidatedMcpToolCall {
+    /// Fail closed for the pre-2026-07-28 constructor shape.
+    ///
+    /// This compatibility surface preserves deterministic routing diagnostics for malformed
+    /// legacy callers, but a syntactically valid route is rejected because this signature cannot
+    /// prove the required per-request protocol metadata or client-capabilities presence. New
+    /// adapters must use [`Self::new_with_request_metadata`].
+    pub fn new(
+        protocol_version: &str,
+        routing_method: &str,
+        routing_tool_name: &str,
+        body_method: &str,
+        body_tool_name: &str,
+    ) -> Result<Self, McpToolBoundaryError> {
+        let _ = routing::ValidatedMcpToolCall::new(
+            protocol_version,
+            routing_method,
+            routing_tool_name,
+            body_method,
+            body_tool_name,
+        )
+        .map_err(McpToolBoundaryError::from)?;
+
+        Err(McpToolBoundaryError::MissingProtocolVersionMetadata)
+    }
+
+    /// Validate one MCP 2026-07-28 `tools/call` request envelope.
+    ///
+    /// The transport protocol-version header and structured request `_meta` protocol version are
+    /// both mandatory, are bounded before comparison, must agree exactly, and must equal
+    /// [`MCP_PROTOCOL_VERSION`]. A trusted structured parser must also attest that the request's
+    /// client-capabilities object was present. Capability contents and optional `clientInfo` grant
+    /// no OriginWeave authority and are not retained. After metadata validation, the existing
+    /// bounded method/tool validator performs the explicit tool-to-action mapping.
+    pub fn new_with_request_metadata(
+        protocol_version_header: Option<&str>,
+        protocol_version_metadata: Option<&str>,
+        client_capabilities_present: bool,
+        routing_method: &str,
+        routing_tool_name: &str,
+        body_method: &str,
+        body_tool_name: &str,
+    ) -> Result<Self, McpToolBoundaryError> {
+        let protocol_version_header =
+            protocol_version_header.ok_or(McpToolBoundaryError::MissingProtocolVersionHeader)?;
+        let protocol_version_metadata = protocol_version_metadata
+            .ok_or(McpToolBoundaryError::MissingProtocolVersionMetadata)?;
+
+        if protocol_version_header.len() > MCP_PROTOCOL_VERSION.len()
+            || protocol_version_metadata.len() > MCP_PROTOCOL_VERSION.len()
+        {
+            return Err(McpToolBoundaryError::UnsupportedProtocolVersion);
+        }
+        if protocol_version_header != protocol_version_metadata {
+            return Err(McpToolBoundaryError::ProtocolVersionHeaderBodyMismatch);
+        }
+        if protocol_version_metadata != MCP_PROTOCOL_VERSION {
+            return Err(McpToolBoundaryError::UnsupportedProtocolVersion);
+        }
+        if !client_capabilities_present {
+            return Err(McpToolBoundaryError::MissingClientCapabilities);
+        }
+
+        let routed = routing::ValidatedMcpToolCall::new(
+            protocol_version_metadata,
+            routing_method,
+            routing_tool_name,
+            body_method,
+            body_tool_name,
+        )
+        .map_err(McpToolBoundaryError::from)?;
+
+        Ok(Self { routed })
+    }
+
+    /// Validate one MCP 2026-07-28 stdio `tools/call` request envelope.
+    ///
+    /// Stdio has no HTTP routing headers, so callers provide only request-body protocol metadata,
+    /// capability presence, method, and tool name. The body values are correlated with themselves
+    /// inside the existing pure envelope validator only to reuse its bounds and catalog checks; no
+    /// HTTP header value is accepted, retained, or surfaced as evidence by this constructor.
+    pub fn new_for_stdio(
+        protocol_version_metadata: Option<&str>,
+        client_capabilities_present: bool,
+        body_method: &str,
+        body_tool_name: &str,
+    ) -> Result<Self, McpToolBoundaryError> {
+        let protocol_version_metadata = protocol_version_metadata
+            .ok_or(McpToolBoundaryError::MissingProtocolVersionMetadata)?;
+
+        Self::new_with_request_metadata(
+            Some(protocol_version_metadata),
+            Some(protocol_version_metadata),
+            client_capabilities_present,
+            body_method,
+            body_tool_name,
+            body_method,
+            body_tool_name,
+        )
+    }
+
+    /// Return the canonical static tool name selected by the explicit mapping.
+    #[must_use]
+    pub const fn tool_name(&self) -> &'static str {
+        self.routed.tool_name()
+    }
+
+    /// Return the existing OriginWeave typed action selected by this tool.
+    #[must_use]
+    pub const fn action_kind(&self) -> ActionKind {
+        self.routed.action_kind()
+    }
+}
+
+impl routing::ValidatedMcpToolsListRequest {
+    /// Validate one MCP 2026-07-28 stdio `tools/list` request envelope.
+    ///
+    /// Stdio carries the protocol metadata and method in the JSON-RPC request body and has no HTTP
+    /// routing headers. The body method/version are correlated with themselves inside the existing
+    /// pure list validator only to reuse its bounded syntax, cache, and cursor checks; callers cannot
+    /// supply or obtain fabricated HTTP header evidence through this constructor.
+    pub fn new_for_stdio(
+        protocol_version_metadata: Option<&str>,
+        client_capabilities_present: bool,
+        body_method: &str,
+        cursor: Option<&str>,
+    ) -> Result<Self, routing::McpToolsListBoundaryError> {
+        let protocol_version_metadata = protocol_version_metadata
+            .ok_or(routing::McpToolsListBoundaryError::MissingProtocolVersionMetadata)?;
+
+        Self::new(
+            Some(protocol_version_metadata),
+            Some(protocol_version_metadata),
+            client_capabilities_present,
+            body_method,
+            body_method,
+            cursor,
+        )
+    }
+}