Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/api/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,51 @@ preserved) and the [`config-to-secret`](#post-apiv1serversnameconfig-to-secret)
endpoint reads the real value server-side. Flip the flag only if you
need to inspect a raw value through the API for debugging.

On the MCP channel the flag also requires an **authenticated** caller
(issue #1148): an unauthenticated `/mcp` client is admin only for backward
compatibility, and gets the masked values regardless of the flag. The REST
API always requires an API key, so it is unaffected.

Redaction is not limited to headers. The same responses — and the `/events`
SSE `servers.changed` payloads, which go through the identical redactor — also
mask env values, URL query credentials, `oauth.extra_params`, `oauth.scopes`
and credential-shaped **argv tokens** (`--api-key sk-…`, `--endpoint=ghp_…`),
using one shared rule set so the REST, SSE and MCP doors cannot drift.

Two rules decide, in that order, and **both** run on every field:

1. The **field name** — `Authorization`, `GITHUB_TOKEN`, `?access_token=`,
`--api-key`. This is what keeps a payload readable: it says *which*
credential is configured without revealing it.
2. The **value's own shape** — an AWS key, a GitHub token, a PEM block, a
high-entropy blob — wherever it sits. A credential under a benign name
(`env: {BUILD_ID: ghp_…}`, `?opaque=ghp_…`, a custom header) is invisible to
rule 1 and obvious to rule 2, so rule 2 runs over everything rule 1 left
alone. In a URL it runs per component, so the readable
`scheme://user:••••(N chars)@host/db` rendering survives while a second
credential elsewhere in the same URL is still masked.

Three consequences for clients:

- A masked value **echoed back on a write** is reverted only when it can be
bound to a key it cannot be moved away from — a map key for `env` / `headers`
/ `oauth.extra_params`, a query-parameter name plus the stored scheme and
`host:port` for `url`, a field name for `oauth.client_secret` /
`client_id` / `redirect_uri`. So a read-modify-write that edits one field
never persists another field's mask over the real secret.
- Everything else is **refused** with `400`, never reverted: `args`,
`oauth.scopes`, `isolation.extra_args`, a mask moved to a different key or
host, and any field added to the server config later. An argv slot (like a
scope) has no key to bind a stored secret to — only its index and its
neighbours, all of them caller-supplied in the same request — so an echoed
mask is refused rather than reverted. Resend the real value, or omit the
field to leave the stored one unchanged. `POST /api/v1/servers` refuses
*every* echoed mask, since on create there is no stored value to bind one to.
See [Upstream servers](../configuration/upstream-servers.md#how-you-edit-them).
- `GET /api/v1/servers/{id}/logs` scrubs credentials out of the returned log
lines (mcpproxy logs the upstream URL with its query string, and a child MCP
server may print its own API key), matching the MCP `tail_log` operation.

The MCP `upstream_servers` tool was the original motivator for redaction
(see [PR #425](https://github.com/smart-mcp-proxy/mcpproxy-go/pull/425)) —
a prompt-injected agent could otherwise read another upstream's PAT via
Expand Down
76 changes: 76 additions & 0 deletions docs/configuration/upstream-servers.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,75 @@ To disable redaction (for debugging only), set `reveal_secret_headers: true`
in `mcp_config.json`. **It's not normally needed**: the editing flow
described below works without ever exposing the plaintext to the client.

Since v0.64 (issue #1148) the flag additionally requires an **authenticated**
caller. `/mcp` is deliberately unprotected by default
(`require_mcp_auth: false`), so an unauthenticated MCP client is treated as
admin for backward compatibility — but that is not an identity, and it no
longer satisfies a check that hands back raw credentials. With the flag on,
raw values are returned to a caller presenting the API key or an admin agent
token, to a tray/socket connection (authenticated by OS-level socket
permissions), and over stdio; an unauthenticated TCP `/mcp` caller gets the
masked values. Nothing else changes: every other operation an unauthenticated
MCP client can perform today still works.

Argument vectors are masked too: a credential passed as `--api-key sk-…` in
`args` is masked by flag name, by value shape and — since the review round on
the same issue — by URL shape in every spelling (`--flag <url>`, `--flag=<url>`
and a bare positional token all mask `?token=…` and `https://user:pass@host`).

For the **keyed** fields, a masked value echoed back on the write path is
reverted to the stored value rather than persisted over it, and every revert is
**bound to where the value was read from**:

| Field | Bound by |
|-------|----------|
| `env_json` / `headers_json` | the map key |
| `url` | the stored scheme and host:port (per query parameter, and the userinfo username) |
| `oauth_json` → `client_secret`, `client_id`, `redirect_uri` | the field |
| `oauth_json` → `extra_params` | the parameter name |
| `oauth_json` → `scopes`, and any future oauth field | *nothing — **refused**, never reverted* |
| `args_json` | *nothing — an argv mask is **refused**, never reverted* |

A mask that none of those bindings can reach is refused rather than written
through. For `url` that covers a URL whose scheme/host changed and a credential
that does not sit in a query parameter; for `oauth_json` it covers a scope (its
only context is a position in a caller-supplied slice) and any field added to
the oauth block later, which fails closed instead of silently persisting its own
mask.

**`args_json` is different: an echoed mask is rejected with an error, not
restored.** An argv token has no key to bind a secret to — only its index and
its neighbours — and `args_json` replaces the whole vector while the same patch
also chooses `command`. Every candidate binding is therefore caller-controlled:
an index can be picked, a preceding flag copied verbatim, and a byte-identical
argv means nothing once `command` moves from `mcp-foo` to `curl`. Any revert
rule would let a caller relocate a stored credential into a command line of its
own choosing.

So a write whose `args_json` still carries a mask this proxy rendered fails
with:

```
args_json[2] is a redaction placeholder, not an argument value: credential-shaped
argv tokens are masked on read and are never restored on write, because an argv
slot carries no key to bind the secret to. Resend the real value for that
argument, or omit args_json to leave the stored arguments unchanged
```

Do not build a read-modify-write loop that feeds a masked `args` list back in:
**resend the real values**, or omit `args_json` entirely when you are not
changing the arguments (omitting it leaves the stored vector untouched).
Rejecting is deliberate rather than silently keeping the stored vector —
`args_json` replaces the vector, so ignoring it would make the write look
applied when it was not.

The same contract applies on REST. `GET /api/v1/servers` masks `args` and
`oauth.extra_params` with the same rules (they are one shared implementation in
`internal/oauth`, so the two doors cannot drift), and `POST`/`PATCH
/api/v1/servers` refuse an echoed `args` mask with `400` for the same reason the
MCP path does — `args` replaces the vector there too. The `oauth` block is
read-only over REST, so no REST write can echo its mask back.

### How you edit them

#### Web UI / macOS tray
Expand Down Expand Up @@ -209,6 +278,13 @@ curl -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
- key absent from body → preserve (this is how the UI sends a diff
against the masked view without overwriting unchanged values)

A client that sends the **whole** map back is safe too: a value that is exactly
the mask the read path rendered for that key is reverted to the stored secret,
bound to the key it was read from. What cannot be bound to a key is **refused**
with `400` rather than written through — `args`, `oauth.scopes`,
`isolation.extra_args`, a mask moved to a different key, and a URL mask whose
scheme/host changed. Resend the real value, or omit the field.

See [REST API › PATCH](../api/rest-api.md#patch-apiv1serversname) for the
full reference, including the
[`/config-to-secret`](../api/rest-api.md#post-apiv1serversnameconfig-to-secret)
Expand Down
45 changes: 45 additions & 0 deletions internal/auth/context.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@ type AuthContext struct {
DisplayName string // User's display name
Role string // "admin" or "user" (empty for API key / agent token auth)
Provider string // OAuth provider used (e.g., "google", "github")

// Anonymous marks a context that was NOT authenticated and only carries
// admin type for backward compatibility (issue #1148).
//
// /mcp is deliberately unprotected by default (require_mcp_auth=false) so
// MCP clients that cannot send an API key keep working, and the middleware
// therefore hands an unauthenticated request an admin context. That is
// fine for the operations those clients need — and it is NOT an identity,
// so it must not satisfy a check that hands back raw credentials. See
// CanRevealSecrets.
Anonymous bool
}

// contextKey is an unexported type used as context key to avoid collisions.
Expand Down Expand Up @@ -106,6 +117,40 @@ func AdminContext() *AuthContext {
}
}

// AnonymousContext returns the back-compat admin context for an
// UNAUTHENTICATED MCP request (issue #1148).
//
// Type stays AuthTypeAdmin on purpose: every existing IsAdmin()-based
// allowance — ordinary tool calls, retrieve_tools, server add/update/patch,
// quarantine approvals — behaves exactly as it did, so no MCP client that
// works today stops working. The only thing the Anonymous bit changes is
// CanRevealSecrets.
func AnonymousContext() *AuthContext {
return &AuthContext{
Type: AuthTypeAdmin,
Anonymous: true,
}
}

// CanRevealSecrets reports whether this caller may be handed RAW credential
// values (issue #1148) — today, `upstream_servers list` under the opt-in
// `reveal_secret_headers` flag.
//
// It is deliberately stricter than IsAdmin and deliberately nil-safe:
//
// - an unauthenticated /mcp caller is admin for back-compat but has proved no
// identity, so it gets masked values like everyone else;
// - a nil context (the stdio transport before it installs one, an in-process
// caller, a test) is unprivileged rather than admin-by-absence — the
// opposite of the `authCtx != nil && !authCtx.IsAdmin()` shape, which lets
// the ABSENCE of a token pass a gate that a scoped token fails.
//
// Authenticated admins — the API key, a tray/socket connection, stdio, an
// OAuth admin user in the server edition — are unaffected.
func (ac *AuthContext) CanRevealSecrets() bool {
return ac != nil && ac.IsAdmin() && !ac.Anonymous
}

// UserContext returns an AuthContext for a regular OAuth-authenticated user.
func UserContext(userID, email, displayName, provider string) *AuthContext {
return &AuthContext{
Expand Down
34 changes: 34 additions & 0 deletions internal/auth/context_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -310,3 +310,37 @@ func TestUserContext_NoImplicitAccess(t *testing.T) {
assert.False(t, ac.CanAccessServer("github"))
assert.False(t, ac.HasPermission(PermRead))
}

// TestAnonymousContext_CanRevealSecrets pins the distinction issue #1148 turns
// on: an unauthenticated /mcp caller is still treated as admin for every
// operation that worked before (that back-compat is deliberate), but it is NOT
// an identity, so it cannot ask for raw secrets. A nil context — the stdio
// transport before it installs one, an in-process caller, a test — must fail
// the same way rather than inheriting admin by absence.
func TestAnonymousContext_CanRevealSecrets(t *testing.T) {
anon := AnonymousContext()
if !anon.IsAdmin() {
t.Fatal("AnonymousContext must stay admin so existing unauthenticated MCP operations keep working")
}
if anon.CanRevealSecrets() {
t.Error("anonymous caller must not be allowed to reveal secrets")
}

if !AdminContext().CanRevealSecrets() {
t.Error("an authenticated admin must still be allowed to reveal secrets")
}

var nilCtx *AuthContext
if nilCtx.CanRevealSecrets() {
t.Error("a nil auth context must not be treated as a secret-revealing admin")
}

agent := &AuthContext{Type: AuthTypeAgent, AgentName: "bot", AllowedServers: []string{"*"}}
if agent.CanRevealSecrets() {
t.Error("agent tokens must not be allowed to reveal secrets")
}

if !AdminUserContext("u1", "a@b.c", "A", "google").CanRevealSecrets() {
t.Error("an OAuth-authenticated admin user must be allowed to reveal secrets")
}
}
72 changes: 72 additions & 0 deletions internal/httpapi/redact_args_oauth_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
package httpapi

import (
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"

"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/oauth"
)

// Issue #1148, round 4 finding 3: the REST twin of the MCP surface. The
// `upstream_servers list` payload masks credential-shaped argv tokens and
// oauth extra_params; GET /api/v1/servers returned both in the clear.
//
// Passing a credential as an argv token (`uvx mcp-foo --api-key sk-…`) is one
// of the commonest MCP server config shapes, and an RFC 8707 resource
// indicator routinely carries a signed URL.
func TestRedactServerSecretFields_MasksArgsAndOAuthExtraParams(t *testing.T) {
srv := &contracts.Server{
Name: "alpha",
Command: "uvx",
Args: []string{
"mcp-foo",
"--api-key", "sk-argv-secret-777",
"--endpoint=ghp_16Cabcdefghijklmnopqrstuvwxyz0123456789",
"--port", "8080",
},
OAuth: &contracts.OAuthConfig{
ClientID: "client-abc",
ExtraParams: map[string]string{
"resource": "https://api.example.com/mcp?sig=urlsecret999&region=eu",
"audience": "tenant-a",
},
},
}

redactServerSecretFields(srv)

joined := srv.Args
assert.NotContains(t, joined, "sk-argv-secret-777", "a flag-named argv credential must be masked")
for _, a := range joined {
assert.NotContains(t, a, "ghp_16Cabcdefghijklmnopqrstuvwxyz0123456789",
"a value-shaped argv credential must be masked")
}
assert.Contains(t, joined, "mcp-foo", "ordinary arguments must stay readable")
assert.Contains(t, joined, "--api-key", "the flag is the audit signal and must survive")
assert.Contains(t, joined, "8080")

assert.NotContains(t, srv.OAuth.ExtraParams["resource"], "urlsecret999",
"a signed resource URL in extra_params must be masked")
assert.Equal(t, "tenant-a", srv.OAuth.ExtraParams["audience"], "non-secret params round-trip verbatim")
}

// The write half of the same contract. REST PATCH REPLACES `args` outright and
// the MCP surface established that argv masks are REFUSED, not reverted (an
// argv slot has no key to bind a stored secret to). Masking args on the REST
// read without refusing them on the REST write would reintroduce exactly the
// read-modify-write corruption the MCP side closed.
func TestRESTArgs_RefuseEchoedMask(t *testing.T) {
stored := []string{"mcp-foo", "--api-key", "sk-argv-secret-777"}
masked := oauth.LiveRedaction.Argv(stored)
require.NotEqual(t, stored[2], masked[2], "precondition: the read path masks the credential")

assert.Error(t, oauth.CheckArgvMaskEcho("args", masked, stored),
"an echoed mask must be refused, never persisted over the credential")
assert.Error(t, oauth.CheckArgvMaskEcho("args", masked, nil),
"a mask sent on create has nothing to bind to either")
assert.NoError(t, oauth.CheckArgvMaskEcho("args", stored, stored))
assert.NoError(t, oauth.CheckArgvMaskEcho("args", nil, stored))
}
45 changes: 45 additions & 0 deletions internal/httpapi/redact_secrets_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,48 @@ func TestRedactServerSecretFields_NoSecrets(t *testing.T) {
assert.Equal(t, "info", srv.Env["LOG_LEVEL"])
assert.Nil(t, srv.Health)
}

// Issue #1148, round 7 finding 2: the REST/SSE door skipped the isolation
// blocks entirely, so `isolation.extra_args` — free text an operator puts
// `-e API_KEY=<token>` into — was masked on the MCP door and published in the
// clear here and on every /events servers.changed payload.
//
// `isolation_defaults` is included because it is RESOLVED FROM the global
// docker_isolation block: a credential in the global `extra_args` lands in it
// verbatim (internal/management/service.go). Round 7 finding 4 re-judged it
// from "not secret" for exactly that reason.
func TestRedactServerSecretFields_MasksIsolationBlocks(t *testing.T) {
const token = "ghp_1234567890abcdefghijABCDEFGHIJ123456"
srv := &contracts.Server{
Name: "alpha",
Isolation: &contracts.IsolationConfig{
Enabled: true,
Image: "python:3.12",
ExtraArgs: []string{"-e", "SERVER_API_KEY=" + token},
},
IsolationDefaults: &contracts.IsolationDefaults{
RuntimeType: "uvx",
Image: "ghcr.io/astral-sh/uv:python3.13-alpine",
ExtraArgs: []string{"-e", "GLOBAL_API_KEY=" + token},
},
}

redactServerSecretFields(srv)

for _, arg := range srv.Isolation.ExtraArgs {
assert.NotContains(t, arg, token, "isolation.extra_args published a credential")
}
for _, arg := range srv.IsolationDefaults.ExtraArgs {
assert.NotContains(t, arg, token, "isolation_defaults.extra_args published a credential")
}

// Masked-but-PRESENT: the UI renders these as override placeholders, so the
// non-secret values must survive byte for byte.
assert.True(t, srv.Isolation.Enabled)
assert.Equal(t, "python:3.12", srv.Isolation.Image)
assert.Equal(t, "ghcr.io/astral-sh/uv:python3.13-alpine", srv.IsolationDefaults.Image)
assert.Equal(t, "uvx", srv.IsolationDefaults.RuntimeType)
assert.Equal(t, "-e", srv.Isolation.ExtraArgs[0])
assert.Contains(t, srv.Isolation.ExtraArgs[1], "SERVER_API_KEY",
"the variable NAME is the audit signal and must survive")
}
Loading
Loading