Skip to content
Closed
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
2 changes: 1 addition & 1 deletion internal-docs/integrations-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ UI slices show the page in headless Chrome (internal-docs/ui-verification.md), d
- [x] A1: the page lists every connection, read-only. Approved by Reviewer 1 at 6b529a7c, merged as 0122b4d3. GET /api/me/connections; claude.ai connectors kept in memory per sign-in (init message + status read after each turn, source "claudeai" only). With streaming input the init message comes on every turn (Worker 1, 2026-10-13). Codex Apps and OpenCode: none shown.
- [x] A2: remote MCP servers registered once for every engine. Approved by Reviewer 2 at 384b8856, merged as ec337cb2. Static credentials only; OAuth is A2b (plan below, Isomux as the OAuth client: Lead ruling, it is the only design that keeps "once, for every engine"). Claude holds the first message of a session until setMcpServers answers (about 1.5 s, 10 s bound). A credential needs port 443. B2 switch point: credentialFor in server/mcp-servers.ts.
- For B2: `credentialFor` in server/mcp-servers.ts is where the header gets the placeholder instead of the value.
- [x] A2b: OAuth MCP servers. Approved by Reviewer 1 at 72532fe7, merged as 11073dc2. Isomux is the OAuth client (discovery, DCR or pasted client, PKCE, callback on the office origin, refresh every 60 s); refresh token and client secret are secrets the registration owns, kept from agents. Follow-ups: a placeholder for the access token (tonight the raw token goes in the MCP header); a server with no refresh token shows Not signed in after a restart.
- [x] A2b: OAuth MCP servers. Approved by Reviewer 1 at 72532fe7, merged as 11073dc2. Isomux is the OAuth client (discovery, DCR or pasted client, PKCE, callback on the office origin, refresh every 60 s); refresh token and client secret are secrets the registration owns, kept from agents. Follow-ups: a placeholder for the access token - done (task 387a038c: the proxy snapshot carries each cached token, the MCP header a fixed placeholder, so a renewal reaches live sessions; with no proxy listening the header still carries the raw token); a server with no refresh token shows Not signed in after a restart.
- [x] A3: Test button and diagnostics per connection. Approved by Reviewer 1 at 1dfa1c0a, merged as d697f585. Sign-ins rerun the account check; preset secrets one read-only identity call; MCP servers initialize + tools/list. The list gains secret rows and statuses for Claude connectors and Claude-set MCP servers.
- [x] A4: a usage note per connection that agents read. Approved by Reviewer 2 at c7be2c99, merged as b7fe627d. GET /api/agent-connections and the agent-reference page `connections` (B4 extends it). Notes on variables (sidecar files), secrets and MCP servers; sign-ins and claude.ai connectors take none.

Expand Down
2 changes: 2 additions & 0 deletions internal-docs/secrets-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ When a name is set more than once, the order is: personal secret, personal varia

The secrets an OAuth MCP registration owns (its refresh token and client secret, integrations A2b) are the server's own credentials: no placeholder, not in the proxy snapshot, and the flow's rotation of one restarts no agent. The registration lists them (`ownedSecrets` in the MCP servers file); when that file cannot be read, every name of the flow's shape (`MCP_<NAME>_OAUTH`, `MCP_<NAME>_OAUTH_CLIENT`) counts as owned. See server/secret-proxy/runtime.ts, `ownedIn`.

The registration's access token goes the other way (task 387a038c): it is in memory only, no secret of the store, but the proxy snapshot carries each cached token as an entry of its own - the registration's host, the authorization form, the current token as the value - with a fixed placeholder: a fixed generation, a fixed shape, and a NUL in the HMAC input's name that no member secret can carry, so it is stable across renewals and restarts and collides with nothing. An engine's MCP header holds that placeholder while a proxy listens, and every token change pushes a fresh snapshot to the child, so a live session survives a renewal; with no proxy listening, the header carries the token itself. The entry joins no signature and no environment: a renewal restarts no agent and moves no revision. See server/secret-proxy/runtime.ts, `oauthEntries`.

### 2.2 The secret proxy

A server-user process that the server starts and supervises (`server/secret-proxy/`). It runs no code that an agent chose. The server sends it the values over a pipe, so the store has one reader.
Expand Down
11 changes: 11 additions & 0 deletions server/isomux-office.ts
Original file line number Diff line number Diff line change
Expand Up @@ -385,10 +385,12 @@ import { createStepAsks, type StepAsks } from "./step-asks.ts";
import { createInProcessDispatch, officeStepRuns } from "./office-step-runs.ts";
import { mcpServersHandlers } from "./routes/handlers/mcp-servers.ts";
import { createMcpOAuth, type McpOAuth } from "./mcp-oauth.ts";
import { listOAuthAccessTokens } from "./mcp-oauth-tokens.ts";
import { createMcpServerStore } from "./mcp-server-store.ts";
import {
createMcpServerSources,
mcpServerRows,
setMcpOAuthPlaceholderProvider,
setMcpPlaceholderProvider,
} from "./mcp-servers.ts";
import {
Expand Down Expand Up @@ -855,6 +857,9 @@ const secretsRuntime = createSecretsRuntime({
return null;
}
},
// The live access tokens of the OAuth registrations, so a live session's
// placeholder header survives their renewal (task 387a038c).
oauthAccess: () => listOAuthAccessTokens(),
memberUids: memberOsUidTies,
onBundle: () => void writeMemberCaBundles(),
});
Expand Down Expand Up @@ -927,6 +932,9 @@ const isLiveAppGrant = (grant: AppGrant): boolean =>
setMcpPlaceholderProvider((scope, name) =>
secretsRuntime.placeholderOf(scope, name),
);
setMcpOAuthPlaceholderProvider((scope, name, url) =>
secretsRuntime.oauthPlaceholderOf(scope, name, url),
);
// Step asks (task c71cb60f): made with the routes. Every hook that may have
// done a step calls stepsChanged.
let stepAsks: StepAsks | undefined;
Expand Down Expand Up @@ -5432,6 +5440,9 @@ function buildExecutorDeps(
secrets: mcpSources.secrets,
fetch: connectionTestFetch,
redirectUri: () => `${buildPublicOrigin().origin}/api/mcp-oauth/callback`,
// A renewal pushes the proxy's snapshot, so the placeholder a live
// session carries resolves to the new token (task 387a038c).
onTokensChanged: () => secretsRuntime.oauthTokensChanged(),
});
register(
mcpServersHandlers({
Expand Down
32 changes: 32 additions & 0 deletions server/mcp-oauth-tokens.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,38 @@ export function oauthTokenExpiry(
return tokens.get(oauthTokenKey(scope, name, url))?.expiresAt;
}

// Every live access token, for the secret proxy's snapshot (secret-proxy/
// runtime.ts, task 387a038c): a session's header carries a placeholder, and
// the proxy swaps in the token that is current at the request.
export function listOAuthAccessTokens(
now: number = Date.now(),
): { scope: SecretScope; name: string; url: string; accessToken: string }[] {
const out: {
scope: SecretScope;
name: string;
url: string;
accessToken: string;
}[] = [];
for (const [key, cached] of tokens) {
if (cached.expiresAt !== null && cached.expiresAt <= now) continue;
// The key is `${scopeKey}\n${name}\n${url}`: a name has no line break
// (the field rules), and a normalized URL has none either.
const first = key.indexOf("\n");
const second = key.indexOf("\n", first + 1);
const scopeKey = key.slice(0, first);
out.push({
scope:
scopeKey === "office"
? { kind: "office" }
: { kind: "user", userId: scopeKey.slice("user:".length) },
name: key.slice(first + 1, second),
url: key.slice(second + 1),
accessToken: cached.accessToken,
});
}
return out;
}

export function setOAuthAccessToken(
scope: SecretScope,
name: string,
Expand Down
107 changes: 105 additions & 2 deletions server/mcp-oauth.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,12 @@ import {
import { createMcpOAuth } from "./mcp-oauth.ts";
import { oauthSecretNames } from "../shared/mcp-servers.ts";
import { SECRET_MIN_VALUE_LENGTH } from "../shared/secret-hosts.ts";
import { resetOAuthTokens } from "./mcp-oauth-tokens.ts";
import {
listOAuthAccessTokens,
resetOAuthTokens,
setOAuthAccessToken,
} from "./mcp-oauth-tokens.ts";
import { setMcpOAuthPlaceholderProvider } from "./mcp-servers.ts";
import { mcpServersHandlers } from "./routes/handlers/mcp-servers.ts";
import type { RouteHandlerContext } from "./routes/executor.ts";
import {
Expand Down Expand Up @@ -58,14 +63,18 @@ afterEach(() => {
function setup(options: StubOptions = {}) {
const rig = stubRig(options);
const sources = createMcpServerSources(root);
// Every access-token change the flow announces (task 387a038c): the
// office wires this to the proxy's snapshot push.
const tokenChanges: number[] = [];
const oauth = createMcpOAuth({
servers: sources.servers,
secrets: sources.secrets,
fetch: rig.fetch,
redirectUri: () => REDIRECT,
now: () => clock,
onTokensChanged: () => tokenChanges.push(tokenChanges.length + 1),
});
return { rig, sources, oauth };
return { rig, sources, oauth, tokenChanges };
}

function register(
Expand Down Expand Up @@ -368,6 +377,100 @@ describe("the refresh", () => {
});
});

describe("the token a live session carries (task 387a038c)", () => {
it("announces every access-token change, so the proxy's snapshot follows", async () => {
const context = setup();
register(context.oauth);
expect(context.tokenChanges).toEqual([]);
await signIn(context);
expect(context.tokenChanges).toEqual([1]);
clock += 3600_000 - 60_000;
await context.oauth.refreshDue();
expect(context.tokenChanges).toEqual([1, 2]);
context.rig.refuseRefresh = true;
clock += 3600_000;
await context.oauth.refreshDue();
expect(context.tokenChanges).toEqual([1, 2, 3]);
expect(context.oauth.remove(member, "mail")).toBe(true);
expect(context.tokenChanges).toEqual([1, 2, 3, 4]);
});

it("gives every engine a fixed placeholder while a proxy listens, and the token itself while none does", async () => {
const context = setup();
register(context.oauth);
await signIn(context);
// No proxy: the header carries the token, as before this placeholder.
expect(mcpServersForUserId(context.sources, "u1")[0].headers).toEqual({
Authorization: `Bearer ${context.rig.access()}`,
});
const restore = setMcpOAuthPlaceholderProvider((scope, name, url) =>
scope.kind === "user" &&
scope.userId === "u1" &&
name === "mail" &&
url === MCP_URL
? `${LEAK}placeholder-0001`
: null,
);
try {
const header = { Authorization: `Bearer ${LEAK}placeholder-0001` };
expect(mcpServersForUserId(context.sources, "u1")[0].headers).toEqual(
header,
);
const shapes = engineShapes(context.sources);
// Claude, Codex and OpenCode each carry the placeholder, and none
// carries the token - their config files never hold it either.
expect(shapes.split(`Bearer ${LEAK}placeholder-0001`).length - 1).toBe(3);
expect(shapes).not.toContain(context.rig.access());
// The renewal rotates the cached token; the header a live session
// holds stays the same placeholder.
const before = context.rig.access();
clock += 3600_000 - 60_000;
await context.oauth.refreshDue();
expect(context.rig.access()).not.toBe(before);
expect(mcpServersForUserId(context.sources, "u1")[0].headers).toEqual(
header,
);
expect(logs.join("\n")).not.toContain(LEAK);
} finally {
setMcpOAuthPlaceholderProvider(restore);
}
});

it("lists the live tokens with their scope, name and URL; an expired one is not live", () => {
const at = Date.now();
setOAuthAccessToken(
{ kind: "office" },
"harness",
"https://mcp.harness.example/mcp",
{ accessToken: `${LEAK}office-token`, expiresAt: at + 60_000 },
);
setOAuthAccessToken({ kind: "user", userId: "u9" }, "mail", MCP_URL, {
accessToken: `${LEAK}member-token`,
expiresAt: null,
});
setOAuthAccessToken(
{ kind: "user", userId: "u9" },
"gone",
"https://gone.example.test/mcp",
{ accessToken: `${LEAK}gone-token`, expiresAt: at - 1 },
);
expect(listOAuthAccessTokens(at)).toEqual([
{
scope: { kind: "office" },
name: "harness",
url: "https://mcp.harness.example/mcp",
accessToken: `${LEAK}office-token`,
},
{
scope: { kind: "user", userId: "u9" },
name: "mail",
url: MCP_URL,
accessToken: `${LEAK}member-token`,
},
]);
});
});

describe("a refresh with an unreadable file", () => {
it("resolves, logs a fixed line and sends no token, then works once the file is back", async () => {
const context = setup();
Expand Down
14 changes: 12 additions & 2 deletions server/mcp-oauth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ export interface McpOAuthDeps {
redirectUri: () => string;
now?: () => number;
timeoutMs?: number;
// After any change to the in-memory access tokens (a sign-in, a refresh,
// a drop): the secrets runtime pushes its proxy snapshot, so a live
// session's placeholder resolves to the current token (task 387a038c).
onTokensChanged?: () => void;
}

export type McpOAuthReason =
Expand Down Expand Up @@ -607,6 +611,7 @@ export function createMcpOAuth(deps: McpOAuthDeps) {
const urlChanged = before !== null && before.url !== change.server.url;
if (checked?.ok || urlChanged) {
dropOAuthTokens(scope, name);
deps.onTokensChanged?.();
dropPending(scope, name);
}
if (pastedSecret) {
Expand Down Expand Up @@ -639,6 +644,7 @@ export function createMcpOAuth(deps: McpOAuthDeps) {
removeOwnedSecrets(scope, before?.oauth.ownedSecrets ?? []);
if (!deps.servers.remove(scope, name)) return false;
dropOAuthTokens(scope, name);
deps.onTokensChanged?.();
dropPending(scope, name);
return true;
}
Expand Down Expand Up @@ -852,6 +858,7 @@ export function createMcpOAuth(deps: McpOAuthDeps) {
accessToken: token.accessToken,
expiresAt: token.expiresAt,
});
deps.onTokensChanged?.();
});
return result.ok
? { ok: true, scope: flow.scope, name: flow.name, ...ask }
Expand Down Expand Up @@ -884,6 +891,7 @@ export function createMcpOAuth(deps: McpOAuthDeps) {
}
if (!refreshToken) {
markOAuthSignInNeeded(scope, server.name);
deps.onTokensChanged?.();
return;
}
const result = await withTimeout(async (signal) => {
Expand Down Expand Up @@ -914,11 +922,13 @@ export function createMcpOAuth(deps: McpOAuthDeps) {
accessToken: token.accessToken,
expiresAt: token.expiresAt,
});
deps.onTokensChanged?.();
});
if (!result.ok) {
if (result.reason === "token_refused")
if (result.reason === "token_refused") {
markOAuthSignInNeeded(scope, server.name);
else
deps.onTokensChanged?.();
} else
console.warn(
`[mcp] ${server.name}: the access token refresh failed (${result.reason}); it is tried again`,
);
Expand Down
39 changes: 33 additions & 6 deletions server/mcp-servers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@
// A header carries the secret's placeholder, never its value (secrets B2):
// the secret proxy swaps it for the value on the way to the server's host,
// which the secret lists. With no proxy listening, a server with a secret is
// left out.
// left out. An OAuth server's access token travels as a placeholder of its
// own, which the proxy resolves to the token at the request, so a live
// session survives a renewal (task 387a038c); with no proxy listening, its
// header carries the token itself.
//
// Resolution fails closed and quiet: an unreadable file, a missing secret or
// a secret that no longer lists the host leaves servers out with a fixed log
Expand Down Expand Up @@ -123,6 +126,24 @@ export function setMcpPlaceholderProvider(
return previous;
}

// The placeholder for an OAuth registration's access token (task 387a038c),
// from the secrets runtime: the proxy swaps it for the token that is current
// at the request, so a live session survives a renewal. Null: no proxy
// listens or no token is cached, and the header carries the token itself.
let oauthPlaceholderOf: (
scope: SecretScope,
name: string,
url: string,
) => string | null = () => null;

export function setMcpOAuthPlaceholderProvider(
fn: typeof oauthPlaceholderOf,
): typeof oauthPlaceholderOf {
const previous = oauthPlaceholderOf;
oauthPlaceholderOf = fn;
return previous;
}

type CredentialProblem = McpServerProblem | "unreadable";

// A signed-in server with no token yet, before the refresh after a restart:
Expand Down Expand Up @@ -197,16 +218,22 @@ function headersFor(
):
| { ok: true; headers: Record<string, string> }
| { ok: false; problem: CredentialProblem | "no_proxy" } {
// An OAuth server's access token is not a secret of the store, so the
// proxy has no placeholder for it: the header carries the token itself.
// An OAuth server's access token is in memory only, no secret of the
// store: the header carries the token's proxy placeholder, which resolves
// to the token that is current at the request, so a live session survives
// a renewal (task 387a038c). With no proxy listening, it carries the token
// itself, which a renewal leaves stale.
if (server.oauth) {
const token = mcpServerSecret(sources, scope, server);
if (!token.ok) return token;
if (!token.secret) return { ok: true, headers: {} };
const placeholder = oauthPlaceholderOf(scope, server.name, server.url);
return {
ok: true,
headers: token.secret
? credentialHeader(token.secret.form, token.secret.value)
: {},
headers: credentialHeader(
token.secret.form,
placeholder ?? token.secret.value,
),
};
}
const credential = credentialFor(sources, scope, server);
Expand Down
Loading
Loading