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.jsonindex 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.jsonindex 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.tsindex 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 adiff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.tsindex 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/validateMcpServerSpecimport { 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.tsnew file mode 100644index 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')+ })+})