fix(mcp): verify internal headers at the sidecar and fail closed on missing scope

[nikola0x0]

Resolves #685 (WALM-372) — the second remediation item from #659, which #665 did not cover.

Problem

The relayer decides what an MCP caller may do and tells the sidecar with x-memwal-internal-oauth-scope. Two defects made the relayer a single point of failure:

1. The sidecar never verified the header's origin. /mcp/* is mounted before sharedSecretAuthMiddleware (because Authorization already carries the end user's delegate key), so it had no shared-secret gate at all. fix(mcp): block inbound internal header injection in reverse proxy #665 stops a client smuggling the header through the relayer; it does nothing about a caller reaching the sidecar directly.
2. A missing scope header failed open. tools/index.ts read const unrestricted = session.oauthScope === undefined, so an absent header granted full write. The intent was legitimate — legacy delegate-key callers have no OAuth scope and should get everything — but the sidecar could not tell "legacy login" from "the header went missing."

Changes

Relayer — apply_oauth_headers → apply_internal_headers, now called on all three proxy handlers including the legacy Passthrough arm that previously set nothing. It states both internal headers explicitly:

Header	Value
x-memwal-internal-sidecar-token	SIDECAR_AUTH_TOKEN
x-memwal-internal-oauth-scope	OAuth: the resolved grant. Legacy: memwal:read memwal:write

Both use insert (overwrite), so a client-supplied value never survives. Header-build failures return 500 instead of being silently skipped — previously that left an authenticated request with no scope, which under the old fail-open meant full write.

Sidecar — new verifyInternalOrigin() (timingSafeEqual, length-guarded) runs first in resolveAuth, so an unverified caller gets 401 before any internal header is read. registerTools drops the unrestricted branch: absent or empty scope now registers no tools.

No new environment variables

SIDECAR_AUTH_TOKEN is already mandatory (the sidecar process.exit(1)s without it), already documented as required in three places, already in both .env.example files and CI, and already inherited by the spawned sidecar from the relayer's environment. Nothing for operators to do.

Verification

	Result
Rust mcp_proxy	14/14 (10 on dev + 4 new)
Rust full unit suite	373 pass / 17 fail — identical to the dev baseline, no regressions
TypeScript	216/216 (205 baseline + 11 new)
rustfmt	clean on mcp_proxy.rs
clippy	no new warnings

Notes for review

• This closes Security Vulnerability Report: Inbound X-MemWal-Internal-Oauth-Scope Header Injection in MCP Proxy Permitting Scope Escalation #659's vector independently of fix(mcp): block inbound internal header injection in reverse proxy #665. Both headers are written with insert, so a forged inbound value is always overwritten. Based on dev rather than stacked on fix(mcp): block inbound internal header injection in reverse proxy #665, so it can merge in either order — the two touch different functions in mcp_proxy.rs.
• Zero tools means no tools capability, not an empty list. The MCP SDK stops advertising tools/list entirely and returns -32601. Correct fail-closed behavior, asserted in tool-scope.test.ts.
• tool-annotations.test.ts was relying on the fail-open — it passed {} as MemWalSession and got all six tools. It now passes an explicit full scope. That test was green because of the bug.
• Three doc comments that claimed /mcp/* had no shared-secret gate are updated (mcp_proxy.rs module header, sidecar/app.ts mount block, auth.ts header contract).

[ducnmm]

Thanks for taking this over — the shared-secret header and explicit legacy scope are the right direction. Two blockers before merge:

1. Bind the granted scope to the MCP session. resolveAuth() still builds sessionKey from only {accountId, delegatePubKey}. Existing SSE/streamable servers keep the tools registered at session creation, so a later request with the same account/delegate but a missing or narrower scope still passes the session-key check and can drive the original write-capable session. This means missing scope does not actually fail closed after initialization. Include the normalized scope in sessionKey, and add a regression test that opens a full-scope session then reuses its session ID with no scope / memwal:read and expects 403.

2. The stdio bridge integration test no longer exercises a successful upstream connection. Its /api test mount bypasses the Rust proxy, so the bridge cannot send x-memwal-internal-sidecar-token or the explicit legacy scope. The test can still pass via the local/auth fallback because it only asserts memwal_login. Add proxy-simulation middleware on the /api router to inject the internal token + full scope, then assert a remote tool such as memwal_recall is present.

Everything else looks solid, and CI is green.

[nikola0x0]

Both fixed in 422d4c6. Verified each one first — the second turned out to be worse than described.

1. Scope bound to the session key

Confirmed and exploitable, not theoretical. I'd previously assumed each grant mints its own delegate keypair, which would have made the session keys differ anyway. That's wrong: routes/oauth.rs:640 calls find_reusable_oauth_delegate(&account_id), keyed on account_id alone, and the comment at :381 says reuse is deliberate. So two grants of differing scope for the same account share a delegate pubkey and produced an identical session key.

sessionKey now includes the normalized scope — deduplicated and sorted, so reordering the same grant doesn't fork a session. Two regression tests: opening with memwal:read memwal:write then reusing the session id with memwal:read, and with the scope header dropped entirely. Both returned 200 before the fix and 403 after. Plus unit tests pinning the normalization, mutation-checked (removing the sort, and removing the scope from the key, each fail a test).

2. Stdio bridge test

Correct, and the assertion couldn't be repaired by swapping in a remote tool name. auth-required.ts now advertises all seven tool names locally (memwal_remember_bulk and memwal_health included), so the bridge's fallback list is name-identical to the relayer's. I confirmed it empirically: forcing the origin check to fail vs. leaving it working produced byte-identical tools/list output.

There was a second cause underneath. Even with the proxy simulation added, the test still passed with the scope injection removed — because tools/list was being answered by the bridge's coldstart path while the upstream SSE was still in flight. The list never came from upstream at all, regardless of auth.

So the fix is three parts:

• The /api mount simulates the relayer's apply_internal_headers, injecting the sidecar token and the granted scope.
• The mount records response status at header-write time (not finish — an SSE response never finishes), and the test waits for /mcp/sse and asserts 200. Before the fix this recorded [{"path":"/mcp/sse","status":401}].
• tools/list is sent only after that 200, so it is answered upstream, and asserts the relayer-registered set.

Mutation-checked: removing either injected header now fails the test. Previously removing the scope changed nothing.

Verification

TS sidecar 221/221, packages/mcp 18/18, Rust mcp_proxy 14/14, Rust full unit suite unchanged from the dev baseline (373 pass / 17 pre-existing failures), rustfmt clean.

[ducnmm]

LGTM! The session key now properly includes the normalized scope to prevent post-init privilege escalation, and the integration tests properly simulate the Rust proxy headers. All CI checks pass.