Remote-MCP 05: Define remote-session provenance to replace the stdio client-managed guard #934

New Issue

2026-07-26T00:31:41-05:00

jcwalker3 commented

2026-07-26 00:31:41 -05:00

Parent epic: #929.
Depends on: #931, #932.

Problem

The server refuses to mutate unless it can prove it was launched by a real client. The proof is physical: the process must carry GITEA_CLIENT_MANAGED, must hold live stdio pipes, and must not be a duplicate role process discovered by scanning peer processes on the same machine. The refusal text states the assumption directly, that manually launched processes cannot receive IDE stdio and so cannot serve mutations.

Every clause of that proof is unavailable to a remote host. There are no client-owned pipes, no peer process list that means anything, and no launcher environment to inspect. Without a defined replacement, a remote deployment either fails closed on every mutation forever, or the guard is weakened into uselessness. The guard exists for a real reason, so it needs a real remote equivalent rather than an exemption.

Scope

Define and implement what "a sanctioned session" means when the transport is not stdio.

State the property the current guard actually protects: that a mutating session was established through the sanctioned client path, and that exactly one authority is serving a given role for a given caller.
Specify the remote equivalent in terms available to a remote host: an authenticated session established through the endpoint's own handshake, bound to a principal, with a server-issued session identity.
Implement provenance as a per-transport strategy selected by the bound transport from child 2, with the existing stdio checks kept intact as the stdio strategy.
Replace the duplicate-role peer process scan with a check meaningful on the remote transport, based on server-tracked sessions rather than on operating-system process inspection.
Preserve fail-closed behavior. An unproven session refuses mutations with a named blocker, performs no mutation, and keeps the transport alive.
Ensure the refusal message names the actual missing proof for the transport in use, rather than telling a remote caller to check stdio pipes.

Acceptance criteria

Provenance strategy is selected by the bound transport identifier.
The stdio strategy passes the existing client-managed and duplicate-launch tests unchanged.
A remote session with a valid server-issued session identity is sanctioned for mutations.
A remote session with no session identity, an expired one, or a forged one is refused, with no mutation performed.
The duplicate-authority check operates on server-tracked sessions under the remote strategy and does not consult the operating-system process list.
Refusal reasons and the safe next action are specific to the transport in use.
Provenance status appears in audit records and in decision-lock provenance.

Verification

Tests cover, per strategy: sanctioned session, missing proof, expired proof, forged proof, and duplicate authority.
A test asserts that the remote strategy performs no process scan.
A test asserts a refusal leaves the transport alive and performs no mutation.
Full suite compared against the recorded baseline, run from a branches/ worktree.

Non-goals

Implementing the endpoint handshake itself. This child defines what proof the guard demands; child 9 issues it.
Relaxing any stdio guard.
Changing the parity gate, which is child 6.

Parent epic: #929. Depends on: #931, #932. ## Problem The server refuses to mutate unless it can prove it was launched by a real client. The proof is physical: the process must carry `GITEA_CLIENT_MANAGED`, must hold live stdio pipes, and must not be a duplicate role process discovered by scanning peer processes on the same machine. The refusal text states the assumption directly, that manually launched processes cannot receive IDE stdio and so cannot serve mutations. Every clause of that proof is unavailable to a remote host. There are no client-owned pipes, no peer process list that means anything, and no launcher environment to inspect. Without a defined replacement, a remote deployment either fails closed on every mutation forever, or the guard is weakened into uselessness. The guard exists for a real reason, so it needs a real remote equivalent rather than an exemption. ## Scope Define and implement what "a sanctioned session" means when the transport is not stdio. - State the property the current guard actually protects: that a mutating session was established through the sanctioned client path, and that exactly one authority is serving a given role for a given caller. - Specify the remote equivalent in terms available to a remote host: an authenticated session established through the endpoint's own handshake, bound to a principal, with a server-issued session identity. - Implement provenance as a per-transport strategy selected by the bound transport from child 2, with the existing stdio checks kept intact as the stdio strategy. - Replace the duplicate-role peer process scan with a check meaningful on the remote transport, based on server-tracked sessions rather than on operating-system process inspection. - Preserve fail-closed behavior. An unproven session refuses mutations with a named blocker, performs no mutation, and keeps the transport alive. - Ensure the refusal message names the actual missing proof for the transport in use, rather than telling a remote caller to check stdio pipes. ## Acceptance criteria - Provenance strategy is selected by the bound transport identifier. - The stdio strategy passes the existing client-managed and duplicate-launch tests unchanged. - A remote session with a valid server-issued session identity is sanctioned for mutations. - A remote session with no session identity, an expired one, or a forged one is refused, with no mutation performed. - The duplicate-authority check operates on server-tracked sessions under the remote strategy and does not consult the operating-system process list. - Refusal reasons and the safe next action are specific to the transport in use. - Provenance status appears in audit records and in decision-lock provenance. ## Verification - Tests cover, per strategy: sanctioned session, missing proof, expired proof, forged proof, and duplicate authority. - A test asserts that the remote strategy performs no process scan. - A test asserts a refusal leaves the transport alive and performs no mutation. - Full suite compared against the recorded baseline, run from a `branches/` worktree. ## Non-goals - Implementing the endpoint handshake itself. This child defines what proof the guard demands; child 9 issues it. - Relaxing any stdio guard. - Changing the parity gate, which is child 6.