Remote-MCP 02: Introduce a transport-neutral bind seam accepting a remote transport #931

New Issue

2026-07-26T00:29:55-05:00

jcwalker3 commented

2026-07-26 00:29:55 -05:00

Parent epic: #929.
Depends on: #930.

Problem

The server binds one transport, by name, at the bottom of the module:

# gitea_mcp_server.py:23750
mcp_daemon_guard.bind_native_mcp_transport(transport="stdio")

Everything that later asks "is this a trusted native session" resolves that question through the value bound here, including assess_transport_for_auth_mint, the decision-lock provenance stamp that defaults to transport: untrusted, and the mutation guards that refuse offline imports. The string is treated as a constant in the guard logic rather than as configuration, so a remote transport currently has no way to be trusted, and no way to be distinguished from an untrusted offline import.

Scope

Introduce a seam so the bound transport is a first-class, validated value rather than a hardcoded literal, without changing what stdio sessions are allowed to do today.

Accept a transport identifier from deployment configuration, defaulting to stdio when unset.
Define the permitted set of transport identifiers and reject anything outside it at bind time, before any tool can dispatch.
Make every guard that currently reasons about "native transport" consult the bound value through one shared accessor instead of assuming stdio.
Record the bound transport in decision-lock provenance and in audit records, so an operator can tell from a durable record which transport performed a mutation.
Keep the fail-closed default: an unbound or unrecognized transport must refuse mutations, exactly as an offline import does today.

Acceptance criteria

The transport identifier is supplied by configuration, and an unset value still yields stdio.
An unrecognized transport identifier fails closed at bind time with a named reason, and no tool dispatches.
No guard reads the literal string stdio outside the shared accessor and the permitted-set definition.
Decision-lock provenance and audit records carry the bound transport identifier.
An offline import with no bind still fails closed on mutations, with the pre-existing reason code.
Behavior for a stdio session is unchanged: the full test suite passes with no new expected-value edits for stdio paths.

Verification

Tests cover: default bind, explicit stdio bind, an accepted non-stdio identifier, an unrecognized identifier, and no bind at all.
A test asserts that the transport identifier reaches a durable decision-lock record.
Full suite compared against the recorded baseline. Run it from a branches/ worktree, not from a temporary directory.

Non-goals

Implementing a remote transport listener. This child only makes the bind pluggable; child 9 stands up the endpoint.
Changing which operations each role may perform.
Changing the client-managed provenance rules. That is child 5, which builds on this seam.

Parent epic: #929. Depends on: #930. ## Problem The server binds one transport, by name, at the bottom of the module: ``` # gitea_mcp_server.py:23750 mcp_daemon_guard.bind_native_mcp_transport(transport="stdio") ``` Everything that later asks "is this a trusted native session" resolves that question through the value bound here, including `assess_transport_for_auth_mint`, the decision-lock provenance stamp that defaults to `transport: untrusted`, and the mutation guards that refuse offline imports. The string is treated as a constant in the guard logic rather than as configuration, so a remote transport currently has no way to be trusted, and no way to be distinguished from an untrusted offline import. ## Scope Introduce a seam so the bound transport is a first-class, validated value rather than a hardcoded literal, without changing what stdio sessions are allowed to do today. - Accept a transport identifier from deployment configuration, defaulting to `stdio` when unset. - Define the permitted set of transport identifiers and reject anything outside it at bind time, before any tool can dispatch. - Make every guard that currently reasons about "native transport" consult the bound value through one shared accessor instead of assuming stdio. - Record the bound transport in decision-lock provenance and in audit records, so an operator can tell from a durable record which transport performed a mutation. - Keep the fail-closed default: an unbound or unrecognized transport must refuse mutations, exactly as an offline import does today. ## Acceptance criteria - The transport identifier is supplied by configuration, and an unset value still yields `stdio`. - An unrecognized transport identifier fails closed at bind time with a named reason, and no tool dispatches. - No guard reads the literal string `stdio` outside the shared accessor and the permitted-set definition. - Decision-lock provenance and audit records carry the bound transport identifier. - An offline import with no bind still fails closed on mutations, with the pre-existing reason code. - Behavior for a stdio session is unchanged: the full test suite passes with no new expected-value edits for stdio paths. ## Verification - Tests cover: default bind, explicit stdio bind, an accepted non-stdio identifier, an unrecognized identifier, and no bind at all. - A test asserts that the transport identifier reaches a durable decision-lock record. - Full suite compared against the recorded baseline. Run it from a `branches/` worktree, not from a temporary directory. ## Non-goals - Implementing a remote transport listener. This child only makes the bind pluggable; child 9 stands up the endpoint. - Changing which operations each role may perform. - Changing the client-managed provenance rules. That is child 5, which builds on this seam.