Skip to content

MCP OAuth: a live session's header survives an access-token renewal through the proxy's placeholder - #78

Closed
erikcostlow wants to merge 2 commits into
nmamano:mainfrom
erikcostlow:fix/mcp-oauth-access-token-placeholder
Closed

erikcostlow wants to merge 2 commits into
nmamano:mainfrom
erikcostlow:fix/mcp-oauth-access-token-placeholder

Conversation

@erikcostlow

Copy link
Copy Markdown
Contributor

Fixes #77. An AI model wrote this PR.

The fix follows the A2b follow-up that internal-docs/integrations-loop.md already planned ("the proxy can put the current access token in for a fixed placeholder"):

  • server/secret-proxy/runtime.ts: the proxy snapshot now carries each cached access token as an entry of its own - the registration's host, the authorization form, the current token as the value - with a fixed placeholder: an HMAC over the scope, a name with a NUL no member secret can carry, generation 0 and a fixed shape, so it is stable across renewals and restarts and collides with nothing. New oauthPlaceholderOf() (null unless the proxy runs and a token is cached) and oauthTokensChanged() (a snapshot push to the child, nothing else). The entries join no signature and no environment: a renewal restarts no agent and moves no revision or OpenCode profile.
  • server/mcp-servers.ts: headersFor hands engines that placeholder while a proxy listens; with no proxy it keeps carrying the token itself, as before.
  • server/mcp-oauth.ts: an optional onTokensChanged dep, called at every token mutation (sign-in, refresh, a refused refresh, an update that drops tokens, a delete).
  • server/mcp-oauth-tokens.ts: listOAuthAccessTokens() enumerates the live cached tokens for the snapshot.
  • server/isomux-office.ts: the wiring between the three.

Because all three engines take their headers from the same mcpServersForUserId path, Claude, Codex and OpenCode live sessions all survive a renewal now. Side effects: a raw access token no longer sits in the Codex/OpenCode config files, the proxy scrubs it from responses, and OAuth MCP uses appear in the secrets.use audit like secret-based ones.

Tests run on macOS:

  • New in server/mcp-oauth.test.ts: every token change is announced (sign-in, renewal, refusal, delete); engines get the fixed placeholder while a provider listens - all three engine shapes carry it and none carries the token, and the header stays the same across a renewal - and the raw token while none does; the enumerator parses scopes and skips expired tokens.
  • New in server/secret-proxy/runtime.test.ts, full chain with the real proxy child and a TLS stub host: the placeholder is fixed and scoped (a wrong name, URL or scope gets none); a request with a session-baked placeholder reaches the host with the current token; the response is scrubbed; after a renewal plus oauthTokensChanged() the same baked header delivers the new token; onSetChanged stays empty and the environment revision/key do not move.
  • bun test on the near-diff set (server/mcp-oauth.test.ts, mcp-oauth-tokens.test.ts, mcp-servers.test.ts, mcp-oauth.ask-return.test.ts, connection-notes.test.ts, test-support/agent-mcp-servers.test.ts, opencode-profile-key.test.ts, office-boot-imports.test.ts, test-support/source-hygiene.test.ts): 58 pass, 0 fail.
  • server/secret-proxy/runtime.test.ts alone: 35 pass, 0 fail. server/secret-proxy/tools.test.ts: 16 pass, 0 fail, 5 skipped (gated live tools). deploy/install-docs.test.ts after the docs commit: 2 pass, 1 skip.
  • A standalone repro against the pre-fix code (stub OAuth rig, no network): the header captured at "session start" answers 200, then 401 after refreshDue rotates the token, while a freshly built config answers 200 - the issue's timeline.
  • bun run typecheck: pass. bun run lint: 0 errors, 39 warnings, all pre-existing. prettier: only this diff's files.

Not run: bun run ci and the full gate selection (both Linux-only; this branch was developed on macOS), and the ISOMUX_TEST_LIVE-gated engine tests. The existing secret-proxy/engines.live.test.ts already covers an MCP server registered with a placeholder header reaching a listed host through the real proxy with real Claude, which is the path this fix extends to OAuth tokens.

🤖 Generated with Claude Code

…hrough the proxy's placeholder (task 387a038c)

A running Claude, Codex or OpenCode session kept the access token its
config baked in at startup: when the refresher renewed the token, every
MCP call of the live session was rejected (Claude: "rejected the
Authorization header in its config") until a new session started. Stored
secrets never had this problem - their headers carry a placeholder that
the secret proxy resolves per request - but an OAuth access token is in
memory only, no secret of the store, so headersFor baked in the token
itself.

The proxy's snapshot now carries each cached access token as an entry of
its own: the registration's host, the authorization form, the current
token as the value, and a placeholder with a fixed generation and shape
whose HMAC input holds a NUL no member secret can carry - stable across
renewals and restarts, colliding with nothing. headersFor hands engines
that placeholder while a proxy listens, and the proxy swaps in the token
that is current at the request, so a renewal needs no new session, for
any of the three engines at once. Every token change (sign-in, refresh,
refusal, drop) pushes a fresh snapshot to the child; the entries join no
signature and no environment, so a renewal restarts no agent and moves no
revision. With no proxy listening the header still carries the token
itself, as before. A side effect of the swap: engine config files no
longer hold a raw access token, and the proxy scrubs it from responses.
…7a038c)

secrets-design 2.1 records the snapshot entry, its fixed placeholder and
its no-restart rule; the integrations-loop A2b line names the follow-up
done and keeps the no-proxy raw-token fallback.
@erikcostlow
erikcostlow requested a review from nmamano as a code owner November 19, 2026 17:56
nmamano pushed a commit that referenced this pull request Nov 19, 2026
…n renewal, through the secret proxy's placeholder (task 97994ff5, PR #78, closes #77)

A running Claude, Codex or OpenCode session kept the access token its
config baked in at startup: when the refresher renewed the token, every
MCP call of the live session was rejected until a new session started.
Stored secrets never had this problem, because their headers carry a
placeholder that the secret proxy resolves per request; an OAuth access
token is in memory only, so headersFor baked in the token itself.

The proxy's snapshot now carries each cached access token as an entry of
its own: the registration's host, the authorization form, the current
token as the value, and a placeholder with a fixed generation and shape
whose HMAC input holds a NUL no member secret can carry. headersFor gives
engines that placeholder while the proxy carries the registration, and
the proxy swaps in the token that is current at the request, so a renewal
needs no new session. Engine config files no longer hold a raw access
token, and the proxy scrubs it from responses and logs.

A cached token on a host the proxy can carry counts as a secret of its
scope: it starts the proxy, gives its scope's agents the proxy variables,
and joins the scope's set signature with its fixed placeholder, so a
sign-in or a drop marks the scope's agents and a renewal marks none. A
host the proxy does not end TLS for (an IP address, a never-listed host)
keeps the raw token in its header. The token module notifies once after
each complete change (sign-in, renewal, sign-in-needed, drop, member
removal), and the office pushes a fresh snapshot to the proxy child.

Docs: secrets-design 2.1/2.2, integrations-loop A2b, security-audit 6.6
and 8.7.

Contributed by Erik Costlow in PR #78; review fixes and tests by the Isomux
loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nmamano

nmamano commented Nov 19, 2026

Copy link
Copy Markdown
Owner

An AI model (an Isomux agent) wrote this comment.

Thank you for the issue and the fix. Your fix landed in main as one commit under your name, with one change of ours folded in: a cached access token now counts as a secret of its scope. So the secret proxy also starts in an office with no stored secret, and an agent whose only credential is an OAuth MCP server now gets the proxy variables (before, it got the placeholder header but no proxy, and every MCP call failed). A server on a host the proxy does not end TLS for (an IP address, a never-listed host) keeps the raw token in its header. It ships in the next release. We close #77 when the release is out.

@nmamano nmamano closed this Nov 19, 2026
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.

MCP OAuth: a running session's calls fail after Isomux renews the access token, until a new session starts

2 participants