Skip to content

fix(security): route the remaining server-payload doors through one redaction rule - #1164

Merged
Dumbris merged 2 commits into
mainfrom
fix/1157-remaining-doors
Sep 1, 2026
Merged

Dumbris merged 2 commits into
mainfrom
fix/1157-remaining-doors

Conversation

@Dumbris

@Dumbris Dumbris commented Sep 1, 2026

Copy link
Copy Markdown
Member

Follow-up to #1157. Those review rounds continued after the branch was merged via #1162, and rounds 8 and 9 never reached main. This carries them, rebased onto current main.

The one that matters: a mask that overwrites the credential it hides

Verified on a clean checkout of main (3e6c4202b) by running the real code:

masked = https://host/mcp?access_token=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2UE+%2825+chars%29
ContainsMaskMarker = false

net/url re-serialises the URL after component-wise masking, so the mask comes back percent-encoded — and ContainsMaskMarker, which is the write-side net (UnmaskLiveURL's residual check and CheckServerWriteMasks), does not recognise its own output. An echoed masked URL that the key-bound revert cannot bind is therefore accepted and persisted over the live credential.

That turns a disclosure bug into silent credential destruction — the failure mode #1142 was about — and it is live on main today. Same probe on this branch returns true.

Fixed by deriving an escaped marker (url.QueryEscape) for every marker, plus registry entries for the two URL renderings.

Read doors that publish credentials in the clear on main

door leaked
internal/server/server.go:1195 GetUpstreamStats url, last_error raw on GET /api/v1/status and every SSE status event — and this is the implementation that actually runs; Manager.GetStats is only its fallback
internal/httpapi/server.go handleGetConfig the entire raw config.Config: every server's env, headers, oauth.client_secret, url credentials, and global docker_isolation.extra_args
internal/httpapi/import.go runImport imported url/command/args raw (its CLI twin was already redacted)
internal/server/mcp.go createDetailedErrorResponse the full upstream request URL, query credentials and all, plus the raw response body
internal/serveredition/api/admin_handlers.go raw []*config.ServerConfig written to JSON
registry source URLs (5 doors) operator-configured endpoints that can carry ?token=
handleGetDockerStatus last_error a docker failure quotes the run command line, -e API_KEY=… and all
GetStats, diagnostics/doctor doors name-rule-only, so a credential under a benign key survived

handleApplyConfig / handlePatchConfig gained the matching bind-or-refuse, which also fixed a pre-existing corruption: PATCH /api/v1/config was persisting an echoed env mask over the live credential. Config reads now fail closed — 500 rather than serve unredacted if the walk cannot round-trip.

Why this needed nine rounds

Every round after the fourth found the same shape: a rule applied at one door and not its sibling. Rounds 8 and 9 stopped fixing doors and built the inventory instead — a scan that derives config-bearing types at a fixpoint and fails when a new unrouted door appears.

That scan immediately proved its worth on the guards themselves:

  • TestRoutedDoors_StillCallASharedRule was vacuous. Deleting redactedServerViews from handleListQuarantinedUpstreams — the original quarantine_security list_quarantined returns env/headers/oauth secrets in plaintext, unauthenticated #1148 door — left it green, because an unrelated mention of liveRedaction elsewhere in the body satisfied it. Each row now names the rules it must route through, demonstrated red.
  • Seven correctly-redacted doors were missing from the pinned inventory, so their redaction could have been deleted later with nothing failing.
  • The renderer-registration gate only discovered package-level functions, while the renderings that reach live doors are methods on Redaction.

Verification

Build, -tags server, go test ./internal/... -race, -tags server ./internal/serveredition/..., golangci-lint v2 → 0 issues.

Every fix was proven red on the unfixed tree first, and each guard was demonstrated going red when the thing it guards regresses.

Final review verdict: readyToMerge: true, four remaining findings all minor (a scan blind to three rarer raw-config shapes; a missing separator in one refusal message; a raw-value fallback in the import view when json.Marshal fails; and one pre-existing design note the reviewer explicitly flagged as not introduced here).

Not fixed here

The server-edition per-user handlers are #1161, handled separately — and the scan found a fifth handler that issue does not name: enableServer. It lists only listServers/getServer/createServer/updateServer. All five are recorded in an openDoors table that requires an issue number per row and goes red once the fix lands, so the rows cannot quietly become permanent exemptions.

…ew one appears

Round 8 of the #1148 review. The four reported defects, plus the exhaustive
door inventory the previous seven rounds needed.

1. upstream_stats (MAJOR). `Manager.GetStats` masked `url` with the name-only
   RedactURLQueryParams and `last_error` with the name-only RedactSensitiveData
   while the server list in the SAME response ran the name rule plus the
   value-shaped detector, so `?opaque=ghp_…` was masked in one half of a
   response and published in the other. Both are now the shared rule, applied
   at one boundary (oauth.RedactUpstreamStats).

   Enumerating the doors found the worse half: `Server.GetUpstreamStats` is a
   SECOND upstream_stats implementation and it is the one that runs (the
   StateView path; Manager.GetStats is only its fallback). It published `url`
   and `last_error` raw on GET /api/v1/status and on every SSE status event.

2. diagnostics/doctor (MAJOR). `health.detail`, `diagnostic.cause` and
   UpstreamErrors.ErrorMessage were scrubbed with RedactSensitiveData alone on
   four doors while RedactServerSecretFields scrubbed the same strings with
   both rules. One rule now — oauth.ScrubUpstreamText — on all of them.

3. command / working_dir (MINOR). One leaf, three doors, three answers: masked
   by the generic MCP view, raw on `upstream_servers list` and on the REST/SSE
   door, and recorded as not-secret in the decision table. The shared leaf rule
   now answers everywhere (an ordinary command or path is byte-identical
   through it), and the decision is `refuse`.

4. mask registration (MINOR). Round 7 replaced a hand-maintained marker list
   with a hand-maintained renderer list. Registration is now enforceable: the
   package's own source is parsed for every exported func(string) string, and
   the test fails unless each is bound and probed against the net or exempted
   with a reason.

   That gate found a live defect on its first run. A URL is re-serialised
   through net/url after masking, so every live read door publishes the mask
   PERCENT-ENCODED — a spelling MaskMarkers did not carry. UnmaskLiveURL's and
   CheckServerWriteMasks' residual check is ContainsMaskMarker, so an echoed
   masked URL the key-bound revert could not bind was ACCEPTED and persisted
   over the credential. The escaped spelling is now derived from each marker.

The inventory. Every function in the door packages that puts a server-derived
string on a client-readable wire is now enumerated by an AST scan and recorded:
routed through the shared rules, or exempted with the reason it needs none.
Newly routed as a result: the server edition's /admin/servers (it wrote the raw
[]*config.ServerConfig to JSON) and its shared-toggle echo, the REST
add-from-registry echo (its MCP twin had been redacted since round 1), the MCP
detailed-error payload (`server_url` was the full upstream URL), registry
source URLs on five doors (with a bind-or-refuse guard on the two write doors),
the docker-status error, the CLI import preview, and GetConnectionDiagnostics.

Two structural tests keep it: one fails when any function publishes a raw
server leaf without an exemption, the other fails when a door that routes stops
calling a shared rule. Both are proven non-vacuous against reintroduced leaks.
Round 9 of the #1148 review. The reported defects were two live doors and
three guards that could not have found them.

The guard first, because it is why the doors were open. The round-8 scan
matched map literals, contracts.* literals, map-index assignments, and
identifiers tainted from an expression whose SOURCE TEXT ended in ".Servers".
Neither of this round's leaks has that shape: one is a named struct that
copies url/command/args out of a config, the other is a whole *config.Config
handed to a publish sink through a call. A guard that cannot see the shape the
real defects have is worse than none, because it reads as coverage.

It no longer judges by source text. It indexes the declared TYPES of the trees
it scans and derives, at a fixpoint: which named types transitively hold a raw
config.Config / config.ServerConfig, which expose a secret-bearing leaf field,
which a value of actually REACHES a publish sink (seeded at the sinks, closed
downward through the field graph), and which functions RETURN a raw config.
Keys are package-qualified, and a function name taints only when every
declaration of it returns a config — a scan whose findings are mostly name
collisions is a scan whose exemption table stops being read.

What it found, beyond the two reported:

1. POST /api/v1/servers/import{,/json,/path} (MAJOR) echoed the operator's
   source file back with url, command and args RAW, while its CLI twin
   (upstream import) was routed through the shared LIVE rule in round 8. Same
   data, two doors, one redacted. Now the same rule, and the same readable
   result: an ordinary command or flag is byte-identical through it.

2. GET /api/v1/config (MAJOR) served the ENTIRE config.Config — every server's
   env, headers, oauth.client_secret and url credentials, the global
   docker_isolation.extra_args and the api_key — with no rule at all. The
   widest door on the tree. It now runs the shared generic walk
   (oauth.RedactedConfig), reveal-gated, failing closed if the walk cannot
   round-trip.

   Masking a read that is round-tripped is only half an answer, so the write
   twins change in the same commit: POST /config/apply and PATCH /config
   resolve the incoming document against the stored one BEFORE anything is
   typed or persisted. Bindings are the ones ServerFieldMaskDecisions already
   records, one level up — a map key or a named field binds, mcpServers binds
   BY NAME, an argv slot binds to nothing and is refused — plus one wider: a
   subtree echoed back byte for byte as the read door rendered it is proof the
   caller changed nothing in it, which is the binding UnmaskLiveURL has taken
   for a whole URL since round 4. That is what keeps the raw-JSON editor and
   the onboarding wizard working (they GET, change one field and POST it
   back) while an argv mask under an EDITED server is still refused.

3. Five server-edition user handlers publish the raw *config.ServerConfig
   through the ServerResponse wrapper. That is issue #1161, fixed separately —
   recorded in a new openDoors table rather than exempted, because an
   exemption reads as "a decision was made". Every row needs an issue number,
   and the row goes stale (and red) when the fix lands. enableServer is a
   fifth handler #1161 does not name; the shape is identical.

The other two guards:

routedDoors — the half of the inventory the raw-leaf scan cannot see — was
written from prose and had holes, including handleListQuarantinedUpstreams,
the original #1148 door. It is now derived: a function that calls a shared
rule AND reaches a publish sink must be pinned, so the two halves cannot
drift. And the pin itself was too weak to be a guard — deleting
redactedServerViews from that door left it green, because the body still
mentioned liveRedaction elsewhere. Each row's prose NAMES the rules it routes
through and every one named must still be present; the documentation is the
assertion. Seven doors were added.

Renderer discovery covered package-level functions only, while the renderings
that reach the live read doors are METHODS on Redaction — Leaf, EnvValue,
HeaderValue, URLValue, Argv — hand-listed with nothing enforcing
registration. Discovery now reaches them, under both policies and under both
a sensitive and a benign key.

Every guard here was demonstrated going red: unpinning a routed door, deleting
a routed door's redaction call (both the pin and the raw-leaf scan catch it),
unbinding a Redaction method, and reverting each of the two door fixes.

Refs #1148
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 2c7f1e4
Status: ✅  Deploy successful!
Preview URL: https://dfb140c5.mcpproxy-docs.pages.dev
Branch Preview URL: https://fix-1157-remaining-doors.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

codecov-commenter commented Sep 1, 2026 •

Copy link
Copy Markdown

@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: fix/1157-remaining-doors

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (26 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 33502494857 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

@Dumbris

Dumbris commented Sep 1, 2026

Copy link
Copy Markdown
Member Author

CodeQL red: pre-existing alert, not introduced here

The CodeQL check reports 1 new alert including 1 critical severity security vulnerability. It is not new, and it is not in this PR's diff. Evidence:

alert 125  go/request-forgery  internal/telemetry/optout.go:135
created: 2026-06-15        (~3 months before this PR)
open on: refs/heads/main
         refs/pull/1164/merge
         refs/pull/684/merge
         refs/pull/784/merge

internal/telemetry/optout.go is not among the 24 files this PR changes; it was last touched by #1037 and #684. The alert is already open on main, so merging this does not change the repo's exposure — CodeQL's "in code changed by this pull request" attribution is what is wrong, most likely because this PR's dataflow-adjacent changes intersect the reported path.

The sink is also already mitigated at that line — an explicit CWE-918 barrier on the same control-flow path:

if u.Scheme != "http" && u.Scheme != "https" { return "", ... }
host := strings.ToLower(u.Hostname())
switch host {
case "localhost", "127.0.0.1", "::1", defaultTelemetryHost():
    return u.String(), nil
default:
    return "", fmt.Errorf("telemetry URL host %q not allowed", host)
}

Scheme is constrained and the host must exactly equal an allowlisted value; the request is only issued on that branch. CodeQL is not recognising the switch as a sanitiser.

Flagging rather than quietly merging past it, since this is a security PR and a red critical check is exactly the thing that should not be waved through on a maintainer's behalf. If you would rather it be green first, the alert wants dismissing as a false positive on main (or the barrier reshaping into a form CodeQL recognises) — either way that is a change to internal/telemetry, which is out of scope here.

@Dumbris
Dumbris merged commit a8e9af7 into main Sep 1, 2026
39 of 40 checks passed
@Dumbris
Dumbris deleted the fix/1157-remaining-doors branch September 1, 2026 12:24
Dumbris added a commit that referenced this pull request Sep 1, 2026
#1161)

Issue #1161 was fixed for the three handlers it named (listServers,
getServer, enableServer, commit ad22f08). This closes the rest of the
same class on the same trust boundary.

The server edition's whole per-user surface leans on ONE entitlement
predicate — `sc.Shared` — because setup.go hands every handler
`deps.Config.Servers`, the admin's WHOLE server list, under the name
`sharedServers`. Two sibling handlers on that door never applied it:

- getDiagnostics iterated the list unfiltered and labelled every entry
  `ownership:"shared"`, so any authenticated user learned the name,
  transport and enablement of admin upstreams the admin did not share.
- The credential surfaces selected on `AuthBroker != nil` alone. A
  non-shared brokered upstream was therefore enumerable AND its per-user
  OAuth connect flow drivable: following the connect path ran the
  gateway's flow against the admin's registered client and persisted a
  per-user credential for a server the caller was never granted. They now
  select through one shared `brokerEntitled` predicate.

Shared servers now mask under AuditRedaction rather than LiveRedaction.
`••••<last2> (<N> chars)` is an affordance for someone editing their OWN
credential; the reader of a shared server is a different tenant who cannot
edit it at all (updateServer and deleteServer answer 403, enableServer
stores only a per-user preference), so it bought them nothing while
publishing the admin credential's exact length and trailing bytes to every
user of the deployment. RedactServerConfigSecrets takes the policy as a
parameter.

getServer's shared branch rendered the caller's own preference as unset,
so the detail read disagreed with listServers and with the .../enable
response. It now threads the stored preference.

Tests: the fail-closed route walk now covers the WHOLE `/user/` prefix and
is driven by RegisterRoutesWithPrefix — the form production actually wires
— rather than `/user/servers` on a router only assembled from
UserHandlers, which is why neither leaking sibling was reachable by it. It
asserts both halves: no shared credential is echoed, and an unentitled
upstream answers exactly as an absent one (no existence oracle). A parity
test pins the two hand-maintained route tables against each other.

CI: `./internal/oauth/...` now runs under `-tags server`. The mask
decisions for the `auth_broker` block live behind that tag, so the canary
enforcing "every text-carrying leaf has a decision" — the guarantee this
whole fix rests on — never compiled in CI.

The fourth leak this branch originally carried — GET /api/v1/config
serving the raw config to any agent-token caller — landed independently in
#1164 (round 9), with a stronger fix: masked for everyone by default with
a matching write-path unmask twin (oauth.UnmaskLiveConfigTree), rather
than gated on caller identity. That work supersedes this branch's version,
which is dropped here along with its now-redundant test.
Dumbris added a commit that referenced this pull request Sep 1, 2026
redactedRegistrySummary (#1164) dereferences its argument, and all three
registry handlers — add, edit and remove — called it on the SUCCESS path with no
nil check. A controller reporting success without an entry therefore panicked
inside the handler, and chi's recoverer turned that into a bare 500 with an
EMPTY body: the caller saw an unexplained server error on a request that had
actually succeeded, and the cause survived only as a stack in the log.

Not hypothetical. MockServerController already returns (nil, nil, nil) from
these methods, so every test driving those routes through it hit the panic. It
surfaced as an intermittent windows-amd64 CI failure where the recovered panic
escaped the test process — intermittent because the recoverer usually swallows
it, which is exactly why it went unnoticed: the package stayed green while three
routes were answering 500 to successful requests.

The guard lives in the renderer rather than at the three call sites so a fourth
caller cannot reintroduce it. A nil entry now renders the zero summary, which
reports no identity and — deliberately — Trusted=false: nothing unknown may be
described as trusted.

Tests assert both that the routes do not panic and that the body is NON-EMPTY,
since an empty 500 is the signature of a recovered panic and a test that only
checked the status code would have passed throughout.
Dumbris added a commit that referenced this pull request Sep 1, 2026
* feat(bench): measure code execution's response-side saving, and fix the three gaps that blocked it

Every savings figure in bench so far is about the MENU — how many tokens of
tool definitions an agent carries. Code execution's menu is already the
smallest of the three surfaces, but the menu is not where it pays: a script
issues several upstream calls inside the sandbox and only the value it returns
enters the model's context. The intermediate responses, which an agent driving
those tools itself would have paid for in full, never appear. Nothing measured
that.

It could not be measured, for three separate reasons, each fixed here:

1. Sandbox sub-calls emitted hardcoded 0,0 byte lengths. In the activity log 0
   means UNKNOWN, not free, so every sub-call was unaccountable — the gap bench
   already names ReasonSubCallZeroBytes.

2. Internal built-in calls never populated the byte fields at all, so the
   code_execution PARENT was unaccountable too. Fixed centrally in the emitter,
   which also closes ReasonInternalNoByteCounts for retrieve_tools and
   describe_tool. The value emitted is the full pre-truncation size, which is
   what response_bytes is defined to mean; the truncation flag travels beside
   it so a consumer can still exclude the row.

3. A PARAMETERLESS tool call records no arguments, so requestCost fell through
   to the byte estimate while its siblings were measured. Colliding bases meant
   the whole script was withheld — and most fleets have several parameterless
   tools. Found on real traffic, not in unit tests.

Measured over 7 scripts and 63 sub-calls on a live 4-server fleet, the saving
ranges from -14.9% (a script that returns its one response verbatim) to +97.0%
(thirty file reads summarised to a count). The negative case is real and is
reported as one: code execution's saving is a function of how much the sandbox
discards, and a script that discards nothing loses tokens.

Accounting rules, each pinned by a test that fails when the guard is removed:

  - never-sum: a measured cost is TOKENS and an estimated cost is BYTES; a call
    mixing them is withheld rather than added into a number in no unit.
  - no silent zeros: a withheld saving carries no figure at all, because a 0
    reads as "saved nothing" when the truth is "nothing was measurable".
  - no double-counting: sub-calls live under their parent, never in Calls.
  - truncation withholds, and does not merely annotate. A truncated component's
    byte length is the full pre-truncation size, but baseline means what an
    agent would have paid, and that agent receives a cut response — so counting
    it overstates the baseline and INFLATES the saving. Caught by cross-model
    review; the test that previously asserted the annotate behaviour is
    inverted rather than deleted.

Also adds breakevencurve, which computes fleet-size break-even by bootstrapping
random orderings of the 527-tool corpus: definition sizes span 145..6485 bytes,
so a single ordering would be one arbitrary curve rather than an answer.

Corrects specs/103 findings/webui-savings-vs-bench.md: BOTH figures in the
+68.4% / -32.5% contradiction were wrong. The Web-UI number is non-deterministic
(map-order sampling, 52.35%-78.80% over an unchanging fleet), and bench's own
proxy menu was overstated because ProxyModeToolDefs pins code execution on. The
sign of the finding survives; its magnitudes did not.

* docs(103): the "40-128 tools" constraint is stale — research the 2026 state

Spec 103's break-even framing inherited a 2025 claim: that above roughly 40-128
tools a user physically cannot connect everything, so mcpproxy's value is
CAPABILITY rather than token saving. Checked it. It mostly does not hold.

  - Cursor's "40-tool cap" is 2025 forum lore, absent from current docs, and
    recharacterized by staff as an upstream per-model limit.
  - Gemini went 128 -> 512. Anthropic, Bedrock, Claude Code, Kiro, Cline and
    Zed document no cap, and the MCP spec caps nothing.
  - The 2026 answer to large tool surfaces was not a raised ceiling but
    DEFERRED LOADING, which Claude Code, Cursor, VS Code and Kiro now ship
    natively — the same mechanism this proxy sells.

The binding constraint moved, and it is far LOWER than any cap: Anthropic
publishes tool-selection degradation past 30-50 available tools, where nothing
errors and quality just falls. Every crossing point on our break-even curve is
above that. Fleet size may be the wrong x-axis — median MCP server is 10 tools
and only 1.2% expose more than 100, so WHICH servers dominates HOW MANY.

Two consequences for what we may claim:

  1. Do not say "you couldn't connect these otherwise" without naming the
     client. On Claude Code in 2026 you could.
  2. Against a deferring client the token baseline is already reduced, so the
     defensible claim is retrieval QUALITY above 30-50, not raw token saving.
     The all-loaded baseline is honest only on non-deferring surfaces.

The document keeps its own completeness critic, which judges the research NOT
thorough and names three holes — tools/list pagination non-compliance, the
gateway/aggregator tier (AWS AgentCore and Docker MCP Gateway have shipped this
design already), and prompt caching. The caching one matters most and is
unresolved: tool definitions are the canonical cacheable prefix, so a proxy that
varies the exposed tool list per turn invalidates that prefix every turn and can
cost MORE than the static baseline it is measured against. Nothing in bench
models this.

* docs(103): prefix-stability audit — caching shrinks the saving 10x but does not move break-even

Step 1 of the caching question: can mcpproxy invalidate the provider's prompt
cache, and does that flip the sign of the savings claim? Static audit of every
tool-list mutation path plus the refresh log of one ordinary 4-server startup.
No API spend.

Pinned to primary source (platform.claude.com, verified today): prefix order is
tools -> system -> messages; writes 1.25x (5m) / 2x (1h); reads 0.1x; and
"modifying tool definitions ... invalidates the entire cache".

Findings:

  - The DEFAULT retrieve_tools surface is cache-stable. It is rebuilt only on
    config.reloaded, never on server churn.
  - The code_execution surface fires notifications/tools/list_changed on every
    servers.changed for a tool list that structurally cannot change —
    buildCodeExecModeTools never iterates upstreams. Measured 9 of 9 broadcasts
    gratuitous on one startup.
  - The direct surface DOES re-write real tool definitions on ordinary churn
    (1 -> 3 -> 18 -> 27 tools across one startup), and that is a genuine full
    invalidation. RefreshDirectModeToolsOnSerializationChange is drift-guarded;
    the servers.changed path calls the UNGUARDED RefreshDirectModeTools.
  - 17 sites emit servers.changed, including server_connected/_disconnected/
    _state_changed. Coalescing is a 50ms window, so a reconnect loop is not
    collapsed.

Two corrections to my own earlier reasoning, both in the write-up:

  1. A gratuitous list_changed is NOT a cache hazard. mcp-go sorts tools/list
     (sort.Strings), so an unchanged set returns byte-identical content and the
     cache still hits. It is wasted client round-trips, not lost cache.
  2. Caching does NOT push break-even further right. Both arms cache the same
     way, so the (B - M) factor divides out and the crossover fleet size is
     roughly invariant. What caching changes is the ABSOLUTE saving: in a cached
     steady state a token bills at 0.1x, so every raw token figure this spec
     publishes overstates money value by about 10x.

The mechanisms that do move the line, both against the proxy: discovery
responses are per-turn cache WRITES at 1.25x while the baseline pays nothing
extra, and direct-mode invalidation re-writes the whole prefix including the
conversation. The latter is the only mechanism found that can plausibly flip the
sign, and it is confined to direct mode with a churning fleet.

Recommends guarding both refresh paths before any paid step-2 measurement, so
the experiment does not price avoidable churn as if it were inherent.

* fix(server): stop the tool surfaces re-registering when nothing changed

mcp-go's SetTools notifies EVERY initialized client unconditionally — it swaps
the registry and sends notifications/tools/list_changed without comparing old
and new content, despite its own comment saying "when the list of available
tools changes". Both routing-mode surfaces rebuilt speculatively on
servers.changed, which has 17 emitters including server_connected,
server_disconnected and server_state_changed. So every reconnect attempt told
every connected client its tool set had moved, and the 50ms coalescer collapses
nothing on that timescale.

Measured on one ordinary 4-server startup, before and after:

  code_execution surface : 9 publishes -> 1
  direct surface         : 10 publishes -> 4

The direct tool_count sequence is the clearest evidence:

  before: 1 1 1 3 3 18 27 27 27 27
  after:  1 3 18 27

Every duplicate gone, every genuine transition preserved. The code-execution
surface could never change at all — buildCodeExecModeTools carries built-ins
only and never iterates upstreams — so all 9 of its publishes were spurious.

Guarded on a content FINGERPRINT rather than by dropping the servers.changed
call, so both stay correct if either surface ever gains fleet-dependent content.

The direct guard compares TWO fingerprints, and the second is the load-bearing
one. Registry and catalog publish as a pair (a handler closes over its catalog
entry), and routing can move while the listing stays byte-identical: a
display-name collision resolving to a different upstream, or a changed
RequiredPermission that gates scoped tokens without appearing in any tool
definition. Guarding on the listing alone breaks three existing tests, including
spec-102's direct_tool_response_mode hot reload — with no upstream tools a
serialization flip changes only the catalog's mode, leaving the listing
identical. A listing-only guard would have silently disabled a shipped feature.

RenderedDescription is deliberately excluded from the routing fingerprint: it is
captured at render time and the signature cache mutates independently of
rebuilds, so including it would report a cache warm or evict as a catalog change
— the distinction D13 rule 5 exists to preserve.

directSurfaceUnchanged is a named predicate rather than an inline && because the
reload harness has no upstreams and so cannot stage a routing-only change; the
requirement is pinned by a test instead of by a comment.

What this does NOT do: it removes wasted client round-trips, not lost provider
cache. mcp-go sorts tools/list, so a re-fetch of an unchanged set returns
byte-identical content and a cached prefix still hits (see
findings/cache-prefix-stability-audit.md). The four remaining direct-mode
publishes are genuine tool-definition changes and are genuine invalidations.

* fix(bench): split code-exec savings by billing direction — tokens saved can be money lost

The saving I shipped two hours ago sums a tool call's ARGUMENTS with its
RESPONSE. They are not the same kind of token. Arguments are text the MODEL
GENERATED (output, billed ~5x input); the response is text it reads (input,
billed 1x, or 0.1x against a cached prefix). Summing them prices a 5x asymmetry
at 1x — a milder form of the never-sum error this file already polices.

It is not academic. Code execution trades the cheap direction for the expensive
one: it replaces N argument-writings with ONE script, whose cost is fixed
however few calls it replaces. Measured on real traffic, filesystem reads of
~700-byte files:

  sub-calls | output base->ce | input base->ce | tokens | USD (uncached / cached in)
      1     |    5 ->  44     |   62 ->  26    |    -3  | -0.000477 / -0.000574
      2     |   24 ->  78     |  210 ->  11    |  +145  | -0.000213 / -0.000750
      3     |   36 ->  78     |  315 ->  11    |  +262  | +0.000282 / -0.000539
      5     |   60 ->  78     |  525 ->  12    |  +495  | +0.001269 / -0.000116
      7     |   84 ->  78     |  735 ->  12    |  +729  | +0.002259 / +0.000307
     30     |  360 ->  78     | 3150 ->  12    | +3420  | +0.013644 / +0.005171

Break-even is ~2 sub-calls in raw tokens but ~6 in money once input is cached.
Between 3 and 5 the token figure reads "+262 to +495 saved" while the wallet
loses. Publishing the token number alone would be exactly the kind of flattering
arithmetic spec 103 exists to stop.

CodeExecSaving now carries BaselineOutput/BaselineInput and ProxyOutput/
ProxyInput beside the existing totals, and PricedSavingUSD converts them.
Pricing REFUSES two cases rather than returning a plausible number: a withheld
saving (0.0 would read as "free" rather than "not measurable") and an estimated
one (those are BYTE lengths, and pricing bytes per token is wrong by the
bytes-per-token ratio while looking entirely correct).

Adds bench/cmd/iosplit, which reports the split straight from an activity export
— that is how the table above was measured.

Response-side totals are unchanged; this only stops them being read as cost.

* fix(bench,runtime): don't bill server-resolved script source, and stop truncated built-ins inflating usage

Three defects from cross-model review of the branch.

HIGH (bench): a stored-script code_execution was charged for a script the model
never wrote. mcpproxy records the RESOLVED source under "code" alongside the
name so the audit trail shows what ran, but the model sent only
{"script": "<name>", "input": {...}}. Billing the recorded arguments as
model-generated output charges ~5,200 output tokens per run for a ~17-token
request, at roughly 5x the input rate — and it does so in exactly the
configuration stored scripts exist to make cheap, so it understated code
execution by the whole size of the script on every invocation.
billableArguments now drops "code" when a non-empty "script" name is present,
and only then; an inline call genuinely did send its source and keeps it.

MEDIUM (bench): PricedSavingUSD accepted NaN, infinity and negative prices and
returned ok=true, so nonsense propagated silently into a confident dollar
figure. Rejected now, the same way a withheld or byte-estimated saving is.

MEDIUM (runtime): countInTimeBucket added ResponseBytes without regard to
ResponseTruncated. That was harmless while internal calls carried no byte counts
at all; this branch gave them some, so a truncated retrieve_tools began
contributing its FULL pre-truncation size to delivered traffic. The direction
differs by record type and that is the point — an upstream tool_call is cut on
the way into the LOG while the agent got the whole response, so its
pre-truncation length is honest; a built-in is the reverse, the log keeps the
full text and the agent consumed the cut one. Counting the second inflates the
usage timeline in the flattering direction.

Each fix is pinned by a test that fails when the guard is removed, verified by
mutation. Also adds a runbook for measuring the "Twenty-Eight Round Trips"
workload on the machine it was recorded on.

* fix(api): registry success payloads must not deref a nil entry

redactedRegistrySummary (#1164) dereferences its argument, and all three
registry handlers — add, edit and remove — called it on the SUCCESS path with no
nil check. A controller reporting success without an entry therefore panicked
inside the handler, and chi's recoverer turned that into a bare 500 with an
EMPTY body: the caller saw an unexplained server error on a request that had
actually succeeded, and the cause survived only as a stack in the log.

Not hypothetical. MockServerController already returns (nil, nil, nil) from
these methods, so every test driving those routes through it hit the panic. It
surfaced as an intermittent windows-amd64 CI failure where the recovered panic
escaped the test process — intermittent because the recoverer usually swallows
it, which is exactly why it went unnoticed: the package stayed green while three
routes were answering 500 to successful requests.

The guard lives in the renderer rather than at the three call sites so a fourth
caller cannot reintroduce it. A nil entry now renders the zero summary, which
reports no identity and — deliberately — Trusted=false: nothing unknown may be
described as trusted.

Tests assert both that the routes do not panic and that the body is NON-EMPTY,
since an empty 500 is the signature of a recovered panic and a test that only
checked the status code would have passed throughout.
Dumbris added a commit that referenced this pull request Sep 1, 2026
#1161) (#1165)

Issue #1161 was fixed for the three handlers it named (listServers,
getServer, enableServer, commit ad22f08). This closes the rest of the
same class on the same trust boundary.

The server edition's whole per-user surface leans on ONE entitlement
predicate — `sc.Shared` — because setup.go hands every handler
`deps.Config.Servers`, the admin's WHOLE server list, under the name
`sharedServers`. Two sibling handlers on that door never applied it:

- getDiagnostics iterated the list unfiltered and labelled every entry
  `ownership:"shared"`, so any authenticated user learned the name,
  transport and enablement of admin upstreams the admin did not share.
- The credential surfaces selected on `AuthBroker != nil` alone. A
  non-shared brokered upstream was therefore enumerable AND its per-user
  OAuth connect flow drivable: following the connect path ran the
  gateway's flow against the admin's registered client and persisted a
  per-user credential for a server the caller was never granted. They now
  select through one shared `brokerEntitled` predicate.

Shared servers now mask under AuditRedaction rather than LiveRedaction.
`••••<last2> (<N> chars)` is an affordance for someone editing their OWN
credential; the reader of a shared server is a different tenant who cannot
edit it at all (updateServer and deleteServer answer 403, enableServer
stores only a per-user preference), so it bought them nothing while
publishing the admin credential's exact length and trailing bytes to every
user of the deployment. RedactServerConfigSecrets takes the policy as a
parameter.

getServer's shared branch rendered the caller's own preference as unset,
so the detail read disagreed with listServers and with the .../enable
response. It now threads the stored preference.

Tests: the fail-closed route walk now covers the WHOLE `/user/` prefix and
is driven by RegisterRoutesWithPrefix — the form production actually wires
— rather than `/user/servers` on a router only assembled from
UserHandlers, which is why neither leaking sibling was reachable by it. It
asserts both halves: no shared credential is echoed, and an unentitled
upstream answers exactly as an absent one (no existence oracle). A parity
test pins the two hand-maintained route tables against each other.

CI: `./internal/oauth/...` now runs under `-tags server`. The mask
decisions for the `auth_broker` block live behind that tag, so the canary
enforcing "every text-carrying leaf has a decision" — the guarantee this
whole fix rests on — never compiled in CI.

The fourth leak this branch originally carried — GET /api/v1/config
serving the raw config to any agent-token caller — landed independently in
#1164 (round 9), with a stronger fix: masked for everyone by default with
a matching write-path unmask twin (oauth.UnmaskLiveConfigTree), rather
than gated on caller identity. That work supersedes this branch's version,
which is dropped here along with its now-redundant test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants