Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(control-api): require decl.remote on the reserved callback segment (RP-R4-SC2-01)

Diego Zacariasb6584429557a
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 4e2244a6d..298bf1c70 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.671",
+ "version": "0.1.672",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.671",
+ "version": "0.1.672",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 727501af4..c71904398 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.671",
+ "version": "0.1.672",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/oauth/callback.ts b/control-api/src/oauth/callback.ts
index 136263fa8..66d80c33d 100644
--- a/control-api/src/oauth/callback.ts
+++ b/control-api/src/oauth/callback.ts
@@ -380,7 +380,7 @@ export async function handleOAuthCallback(
// Dispatch by the signed subject. mcp subjects go to their own handler; the
// recipe path below is unchanged (byte-identical grant persistence).
if (claims.subjectKind === 'mcp') {
- return handleMcpOAuthCallback(claims, input, deps)
+ return handleMcpOAuthCallback(claims, input, deps, isRemoteStableSegment)
}
const recipeNamespace = claims.recipeNamespace
@@ -482,7 +482,8 @@ export async function handleOAuthCallback(
async function handleMcpOAuthCallback(
claims: OAuthMcpStateClaims,
input: CallbackInput,
- deps: CallbackDeps
+ deps: CallbackDeps,
+ isRemoteStableSegment: boolean
): Promise<CallbackResult> {
// Fail closed: an mcp state cannot be processed without an mcp reader wired.
if (!deps.mcpServerReader) return { kind: 'server_not_found' }
@@ -505,6 +506,15 @@ async function handleMcpOAuthCallback(
if (subject.decl.id !== claims.oauthClientId) {
return { kind: 'invalid_state', reason: 'binding_mismatch' }
}
+ // The segment==id waiver above is only sound for remote subjects, whose issuer
+ // check below replaces it. A baked/generic state delivered here would bypass
+ // both, leaving the AS's own redirect_uri comparison as the only binding — and
+ // the generic lane exists precisely for ASes that may not enforce it. A
+ // non-remote server that nonetheless owns the reserved id (e.g. written straight
+ // to the apiserver) fails closed here instead of completing consent.
+ if (isRemoteStableSegment && !subject.decl.remote) {
+ return { kind: 'invalid_state', reason: 'binding_mismatch' }
+ }
// ─── RFC 9207 issuer check (remote lane only) ─────────────────────────────
// Authorization-server mix-up defence: an attacker who controls one AS in a
diff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.ts
index 96c386c54..119630ad0 100644
--- a/control-api/src/routes/admin/registry.ts
+++ b/control-api/src/routes/admin/registry.ts
@@ -12,6 +12,7 @@ import { validateMcpServerSpecPreflight } from '../../http/validateMcpServerSpec
import { K8sGateway } from '../../k8s.js'
import type { UiAuthedRequest } from '../../middleware/controlUIAuth.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
+import { REMOTE_CALLBACK_CLIENT_SEGMENT } from '../../oauth/callback.js'
import { deriveOAuthEncryptionKey } from '../../oauth/encryption.js'
import { GenericConfigSuggestionSchema } from '../../oauth/genericKnobs.js'
import {
@@ -852,6 +853,23 @@ export function deriveOAuthClientId(serverName: string): string {
.replace(/-+$/, '')
}
+/**
+ * The oauth.id equal to the shared remote callback segment is reserved for the
+ * remote lane: the callback waives the segment==id check on that segment and only
+ * a remote subject (with its issuer pin) may use it, so a baked/generic server
+ * owning this id could never complete consent.
+ */
+function isReservedOAuthClientId(oauthId: string): boolean {
+ return oauthId === REMOTE_CALLBACK_CLIENT_SEGMENT
+}
+
+function reservedOAuthClientIdError(oauthId: string): { error: string; message: string } {
+ return {
+ error: 'oauth_id_reserved',
+ message: `oauth: serverName derives the reserved oauth.id "${oauthId}" (the shared remote OAuth callback segment); choose a different serverName`,
+ }
+}
+
/**
* Resolve the effective OAuth scopes for an install (D-B6/GAP-6). Precedence:
* operator-edited scopes → catalog prefill → the baked adapter's defaultScopes.
@@ -2297,6 +2315,10 @@ export function createAdminRegistryRouter(
.json({ error: 'oauth: could not derive a valid oauth.id from serverName' })
return
}
+ if (isReservedOAuthClientId(oauthId)) {
+ res.status(400).json(reservedOAuthClientIdError(oauthId))
+ return
+ }
if (await oauthClientIdInUse(gateway, targetNs, oauthId)) {
res.status(409).json({
error: `oauth.id "${oauthId}" is already in use by another server; choose a different serverName`,
@@ -2435,6 +2457,10 @@ export function createAdminRegistryRouter(
.json({ error: 'oauth: could not derive a valid oauth.id from serverName' })
return
}
+ if (isReservedOAuthClientId(oauthId)) {
+ res.status(400).json(reservedOAuthClientIdError(oauthId))
+ return
+ }
if (await oauthClientIdInUse(gateway, targetNs, oauthId)) {
res.status(409).json({
error: `oauth.id "${oauthId}" is already in use by another server; choose a different serverName`,
diff --git a/control-api/test/oauth.callback.reservedRemoteSegment.test.ts b/control-api/test/oauth.callback.reservedRemoteSegment.test.ts
new file mode 100644
index 000000000..c4a80f76f
--- /dev/null
+++ b/control-api/test/oauth.callback.reservedRemoteSegment.test.ts
@@ -0,0 +1,403 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import express from 'express'
+import request from 'supertest'
+import { config } from '../src/config.js'
+import type { PinnedRawResponse } from '../src/http/pinnedFetch.js'
+import { buildAuthorizeUrl } from '../src/oauth/authorizeUrlHelper.js'
+import {
+ type CallbackDeps,
+ type McpServerOAuthReader,
+ type McpServerOAuthSubject,
+ REMOTE_CALLBACK_CLIENT_SEGMENT,
+ type SecretReader,
+ handleOAuthCallback,
+} from '../src/oauth/callback.js'
+import { deriveOAuthEncryptionKey } from '../src/oauth/encryption.js'
+import { resolveServerOAuthSubject } from '../src/oauth/mcpServerOAuthSpec.js'
+import { createAdminRegistryRouter } from '../src/routes/admin/registry.js'
+import {
+ getCredentialSchema,
+ getDigest,
+ getEntryVersion,
+ reportInstall,
+} from '../src/services/registryClient.js'
+import { MockGateway } from './mockGateway.js'
+
+/**
+ * RP-R4-SC2-01 — the stable remote callback segment (`/oauth-callback/remote`)
+ * waives the segment==id check, so it must only accept states of REMOTE subjects.
+ * A baked/generic state delivered there is a `binding_mismatch`, rejected BEFORE
+ * the single-use code is exchanged (T4: no token-endpoint call, nothing persisted).
+ *
+ * T1: nothing here is hand-built wire data. The CRs come from the real registry
+ * install route (MockGateway), the subject from `resolveServerOAuthSubject`, and
+ * the state from `buildAuthorizeUrl` — the same minter the consent route uses.
+ */
+
+vi.mock('node:dns/promises', () => ({
+ lookup: vi.fn(async () => [{ address: '93.184.216.34', family: 4 }]),
+}))
+
+vi.mock('../src/services/registryClient.js', () => ({
+ searchEntries: vi.fn(),
+ getEntry: vi.fn(),
+ getEntryVersion: vi.fn(),
+ getCredentialSchema: vi.fn(),
+ getCategories: vi.fn(),
+ reportInstall: vi.fn(),
+ downloadBundle: vi.fn(),
+ getDigest: vi.fn(),
+ uploadArtifacts: vi.fn(),
+ updateVersionMetadata: vi.fn(),
+ deleteVersion: vi.fn(),
+ publishEntry: vi.fn(),
+ resolvePublishScope: vi.fn(),
+ applyPublishScope: vi.fn((name: string | undefined) => name),
+}))
+
+const MCP_NS = 'mcp-server'
+const CONTEXT = 'default-context'
+const STATE_SECRET = 'test-state-hmac-secret-32-bytes-padding'
+const ENCRYPTION_KEY = deriveOAuthEncryptionKey(
+ '00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff'
+)
+const USER_ID = 'user-9'
+const GENERIC_KNOBS = {
+ authorizationEndpoint: 'https://idp.example.com/authorize',
+ tokenEndpoint: 'https://idp.example.com/token',
+ tokenRequestFormat: 'form',
+ tokenAuthMethod: 'body',
+ scopeSeparator: 'space',
+ sendScope: true,
+ usePkce: true,
+ includeResponseType: true,
+ supportsRefresh: true,
+}
+
+let savedCallbackBaseUrl: string
+
+beforeEach(() => {
+ vi.resetAllMocks()
+ vi.mocked(getDigest).mockResolvedValue({ digest: null })
+ vi.mocked(getCredentialSchema).mockRejectedValue(new Error('No credential schema endpoint'))
+ vi.mocked(reportInstall).mockResolvedValue({ acknowledged: true, stored: true })
+ savedCallbackBaseUrl = config.oauthCallbackBaseUrl
+ config.oauthCallbackBaseUrl = 'https://control.example.com'
+})
+
+afterEach(() => {
+ config.oauthCallbackBaseUrl = savedCallbackBaseUrl
+})
+
+function catalogEntry(oauth: Record<string, unknown>) {
+ return {
+ id: '1',
+ name: 'some-mcp',
+ version: '1.0.0',
+ entry_type: 'mcp-server',
+ description: 'OAuth MCP server',
+ author: 'clerum',
+ origin: 'official',
+ category: 'productivity',
+ tags: [],
+ trust_level: 'high',
+ quality_tier: 'verified',
+ status: 'published',
+ server_mode: 'local',
+ transport: 'streamableHttp',
+ recipe_type: null,
+ mcp_server_meta: { imageRef: 'clerum/some-mcp:1.0.0', port: 3000, oauth },
+ recipe_meta: null,
+ artifact_refs: null,
+ downloads: 0,
+ installs: 0,
+ created_at: '2026-03-01T00:00:00Z',
+ }
+}
+
+function makeInstallApp() {
+ const gw = new MockGateway(MCP_NS)
+ gw.createResource('contexts', {
+ metadata: { name: CONTEXT },
+ spec: { contextId: CONTEXT, mcpServers: [] },
+ })
+ const app = express()
+ app.use(express.json())
+ app.use(
+ createAdminRegistryRouter(gw as unknown as import('../src/k8s.js').K8sGateway, {
+ uninstallDb: { query: async () => ({ rows: [], rowCount: 0 }) },
+ })
+ )
+ app.use(
+ (err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+ res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' })
+ }
+ )
+ return { app, gw }
+}
+
+type Lane = 'generic' | 'baked'
+
+/** Install a server through the REAL registry route and return its stored CR. */
+async function installServer(lane: Lane, serverName: string) {
+ const { app, gw } = makeInstallApp()
+ if (lane === 'generic') {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(catalogEntry({ provider: 'generic' }))
+ await request(app)
+ .post('/admin/registry/install')
+ .send({
+ serverName,
+ contextRef: CONTEXT,
+ registryEntryName: 'some-mcp',
+ registryEntryVersion: '1.0.0',
+ oauth: { scopes: ['read'], generic: GENERIC_KNOBS },
+ })
+ .expect(201)
+ } else {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(catalogEntry({ provider: 'google' }))
+ await request(app)
+ .post('/admin/registry/install')
+ .send({
+ serverName,
+ contextRef: CONTEXT,
+ registryEntryName: 'some-mcp',
+ registryEntryVersion: '1.0.0',
+ oauth: {
+ scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+ secret: { mode: 'managed', clientId: 'cid-value', clientSecret: 'csec-value' },
+ },
+ })
+ .expect(201)
+ }
+ const cr = (await gw.getResource('mcpservers', serverName, MCP_NS)) as Parameters<
+ typeof resolveServerOAuthSubject
+ >[0]
+ return { gw, cr }
+}
+
+function gatewaySecretReader(gw: MockGateway): SecretReader {
+ return {
+ read: async (name, namespace) => {
+ const secret = (await gw.getSecret(name, namespace)) as { data?: Record<string, string> }
+ return Object.fromEntries(
+ Object.entries(secret.data ?? {}).map(([k, v]) => [k, Buffer.from(v, 'base64').toString()])
+ )
+ },
+ }
+}
+
+const TOKEN_RESPONSE = JSON.stringify({
+ access_token: 'AT',
+ refresh_token: 'RT',
+ expires_in: 3600,
+ token_type: 'Bearer',
+})
+
+/**
+ * Mint a state with the real minter for the installed server, then hand it to the
+ * callback on the given URL segment. Every token-endpoint path (baked `fetchFn`,
+ * generic/remote `pinnedTransport`) is observable.
+ */
+async function deliverState(lane: Lane, serverName: string, segment: string) {
+ const { gw, cr } = await installServer(lane, serverName)
+ const resolved = resolveServerOAuthSubject(cr)
+ if (!resolved) throw new Error('installed CR must resolve to an OAuth subject')
+ const mcpServerReader: McpServerOAuthReader = {
+ read: vi.fn(async () => ({ namespace: MCP_NS, ...resolved }) as McpServerOAuthSubject),
+ }
+ const secretReader = gatewaySecretReader(gw)
+
+ const minted = await buildAuthorizeUrl(
+ {
+ subjectKind: 'mcp',
+ mcpServerName: serverName,
+ oauthClientId: resolved.decl.id,
+ userId: USER_ID,
+ grantKind: 'user',
+ background: false,
+ redirectUri: `https://control.example.com/api/v1/oauth-callback/${resolved.decl.id}`,
+ },
+ {
+ recipeReader: { read: vi.fn(async () => null) },
+ mcpServerReader,
+ secretReader,
+ stateSecret: STATE_SECRET,
+ }
+ )
+ if (minted.kind !== 'ok') throw new Error(`authorize url not minted: ${minted.kind}`)
+ const state = new URL(minted.authorizeUrl).searchParams.get('state')
+ if (!state) throw new Error('minted authorize url carries no state')
+
+ const fetchFn = vi.fn(
+ async () =>
+ new Response(TOKEN_RESPONSE, {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ const pinnedTransport = vi.fn(
+ async (): Promise<PinnedRawResponse> => ({
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ bodyText: TOKEN_RESPONSE,
+ })
+ )
+ const db = { query: vi.fn().mockResolvedValue({ rows: [{ id: 'grant-1' }], rowCount: 1 }) }
+ const deps: CallbackDeps = {
+ db: db as unknown as CallbackDeps['db'],
+ recipeReader: { read: vi.fn(async () => null) },
+ secretReader,
+ mcpServerReader,
+ userContextsReader: vi.fn(async () => ({ contextIds: [CONTEXT] })),
+ fetchFn: fetchFn as unknown as typeof fetch,
+ stateSecret: STATE_SECRET,
+ encryptionKey: ENCRYPTION_KEY,
+ resolveDns: async () => ['93.184.216.34'],
+ pinnedTransport,
+ }
+
+ const result = await handleOAuthCallback(
+ {
+ oauthClientId: segment,
+ code: 'AUTH_CODE',
+ state,
+ redirectUri: `https://control.example.com/api/v1/oauth-callback/${segment}`,
+ },
+ deps
+ )
+ return { result, fetchFn, pinnedTransport, db }
+}
+
+describe('handleOAuthCallback — reserved remote segment requires a remote subject (RP-R4-SC2-01)', () => {
+ it.each<Lane>(['generic', 'baked'])(
+ 'rejects a %s state delivered on /oauth-callback/remote WITHOUT exchanging the code',
+ async lane => {
+ const { result, fetchFn, pinnedTransport, db } = await deliverState(
+ lane,
+ 'my-idp',
+ REMOTE_CALLBACK_CLIENT_SEGMENT
+ )
+
+ expect(result).toEqual({ kind: 'invalid_state', reason: 'binding_mismatch' })
+ expect(fetchFn).not.toHaveBeenCalled()
+ expect(pinnedTransport).not.toHaveBeenCalled()
+ expect(db.query).not.toHaveBeenCalled()
+ }
+ )
+
+ it.each<Lane>(['generic', 'baked'])(
+ 'still completes a %s state delivered on its own client-id segment',
+ async lane => {
+ const { result, fetchFn, pinnedTransport, db } = await deliverState(lane, 'my-idp', 'my-idp')
+
+ expect(result.kind).toBe('ok')
+ expect(fetchFn.mock.calls.length + pinnedTransport.mock.calls.length).toBe(1)
+ expect(String(db.query.mock.calls[0]?.[0])).toContain('INSERT INTO oauth_grants')
+ }
+ )
+})
+
+describe('POST /admin/registry/install — reserved oauth.id (RP-R4-SC2-01)', () => {
+ it.each<Lane>(['generic', 'baked'])(
+ 'rejects a %s install whose serverName derives the reserved oauth.id, before any write',
+ async lane => {
+ const { app, gw } = makeInstallApp()
+ const createSecretSpy = vi.spyOn(gw, 'createSecret')
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(
+ catalogEntry({ provider: lane === 'generic' ? 'generic' : 'google' })
+ )
+ const oauth =
+ lane === 'generic'
+ ? {
+ scopes: ['read'],
+ secret: { mode: 'managed', clientId: 'cid', clientSecret: 'csec' },
+ generic: GENERIC_KNOBS,
+ }
+ : {
+ scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+ secret: { mode: 'managed', clientId: 'cid', clientSecret: 'csec' },
+ }
+
+ const res = await request(app).post('/admin/registry/install').send({
+ serverName: REMOTE_CALLBACK_CLIENT_SEGMENT,
+ contextRef: CONTEXT,
+ registryEntryName: 'some-mcp',
+ registryEntryVersion: '1.0.0',
+ oauth,
+ })
+
+ expect(res.status).toBe(400)
+ expect(res.body.error).toBe('oauth_id_reserved')
+ expect(createSecretSpy).not.toHaveBeenCalled()
+ await expect(
+ gw.getResource('mcpservers', REMOTE_CALLBACK_CLIENT_SEGMENT, MCP_NS)
+ ).rejects.toThrow()
+ }
+ )
+})
+
+describe('handleOAuthCallback — recipe clients are outside the reservation (RP-R4-SC2-01)', () => {
+ // A recipe's `oauthClients[]` is operator-authored CR data (admin CRUD passes it
+ // through verbatim), so there is no control-api producer to derive it from. The
+ // waiver is mcp-only, so a recipe client literally named `remote` still takes the
+ // segment==id path and must keep working.
+ it("completes a recipe client whose id is 'remote' on /oauth-callback/remote", async () => {
+ const recipe = {
+ metadata: { name: 'crm', namespace: 'sandbox-recipes' },
+ spec: {
+ oauthClients: [
+ {
+ id: REMOTE_CALLBACK_CLIENT_SEGMENT,
+ provider: 'salesforce',
+ clientIdRef: { name: 'sf-creds', key: 'client-id' },
+ clientSecretRef: { name: 'sf-creds', key: 'client-secret' },
+ scopes: ['api'],
+ },
+ ],
+ },
+ }
+ const recipeReader = { read: vi.fn(async () => recipe) }
+ const secretReader: SecretReader = {
+ read: vi.fn(async () => ({ 'client-id': 'CID', 'client-secret': 'CSEC' })),
+ }
+ const redirectUri = `https://control.example.com/api/v1/oauth-callback/${REMOTE_CALLBACK_CLIENT_SEGMENT}`
+ const minted = await buildAuthorizeUrl(
+ {
+ recipeNamespace: 'sandbox-recipes',
+ recipeName: 'crm',
+ oauthClientId: REMOTE_CALLBACK_CLIENT_SEGMENT,
+ userId: USER_ID,
+ grantKind: 'user',
+ background: false,
+ redirectUri,
+ },
+ { recipeReader, secretReader, stateSecret: STATE_SECRET }
+ )
+ if (minted.kind !== 'ok') throw new Error(`authorize url not minted: ${minted.kind}`)
+ const state = new URL(minted.authorizeUrl).searchParams.get('state') ?? ''
+
+ const fetchFn = vi.fn(
+ async () =>
+ new Response(TOKEN_RESPONSE, {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ const db = { query: vi.fn().mockResolvedValue({ rows: [], rowCount: 1 }) }
+ const result = await handleOAuthCallback(
+ { oauthClientId: REMOTE_CALLBACK_CLIENT_SEGMENT, code: 'AUTH_CODE', state, redirectUri },
+ {
+ db: db as unknown as CallbackDeps['db'],
+ recipeReader,
+ secretReader,
+ fetchFn: fetchFn as unknown as typeof fetch,
+ stateSecret: STATE_SECRET,
+ encryptionKey: ENCRYPTION_KEY,
+ } as CallbackDeps
+ )
+
+ expect(result.kind).toBe('ok')
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(String(db.query.mock.calls[0]?.[0])).toContain('INSERT INTO oauth_grants')
+ })
+})