Skip to content

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

TypeScript

fix(external-rest-api): expose the CIMD client metadata document publicly

Jose Gabriel Ramirez Encinase9a53e61dddd
diff --git a/deploy/base/profiles/configmaps.yaml b/deploy/base/profiles/configmaps.yaml
index ef5064e0b..740ed168b 100644
--- a/deploy/base/profiles/configmaps.yaml
+++ b/deploy/base/profiles/configmaps.yaml
@@ -73,6 +73,22 @@ data:
proxy_set_header X-Forwarded-Proto $scheme;
}
+ # Public CIMD (SEP-991) document: the remote MCP-OAuth client_id is
+ # <public origin>/api/v1/.well-known/evenfire-mcp-client, fetched by the
+ # remote Authorization Server via external-rest-api. Exact path only,
+ # read-only (limit_except GET also admits HEAD), no query forwarded.
+ location = /api/v1/.well-known/evenfire-mcp-client {
+ limit_except GET {
+ deny all;
+ }
+ set $control_api_origin control-api.control-plane.svc.cluster.local:8090;
+ proxy_pass http://$control_api_origin/api/v1/.well-known/evenfire-mcp-client;
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+
location / {
return 403;
}
diff --git a/external-rest-api/package-lock.json b/external-rest-api/package-lock.json
index a2e4bc4f5..dd9f4c6a3 100644
--- a/external-rest-api/package-lock.json
+++ b/external-rest-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"dependencies": {
"@clerum/jwt-key-policy": "file:../packages/jwt-key-policy",
"cors": "^2.8.5",
diff --git a/external-rest-api/package.json b/external-rest-api/package.json
index 88323b742..4b1a80ddc 100644
--- a/external-rest-api/package.json
+++ b/external-rest-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.100",
+ "version": "0.1.101",
"description": "External REST API for profile, team management, and RPC token brokerage",
"main": "dist/main.js",
"engines": {
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index 3fe2d55e2..9ef40b16b 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -8,7 +8,7 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.11.0',
- externalRestApiVersion: '0.1.100',
+ externalRestApiVersion: '0.1.101',
rpcProxyVersion: '0.1.126',
desktopVersion: '0.11.0',
minimumDesktopVersion: '0.1.252',
diff --git a/external-rest-api/src/routes/oauthCallback.ts b/external-rest-api/src/routes/oauthCallback.ts
index bd2f47f89..5c5023462 100644
--- a/external-rest-api/src/routes/oauthCallback.ts
+++ b/external-rest-api/src/routes/oauthCallback.ts
@@ -7,6 +7,11 @@ const REMOTE_SERVER_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
// Lowercase only: control-api mints the nonce with crypto.randomUUID(), which is
// always lowercase, so any other casing is not a redirect URI it ever registered.
const INSTALL_NONCE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+// Client ID Metadata Document (SEP-991) for the remote MCP-OAuth lane. Must equal
+// control-api's CIMD_ROUTE_PATH (control-api/src/oauth/cimdIdentity.ts): the CIMD
+// client_id is `<public origin>/api/v1` + this path, and a remote Authorization Server
+// fetches that URL through this gateway.
+const CIMD_ROUTE_PATH = '/.well-known/evenfire-mcp-client'
function rawQueryOf(req: Request): string {
const queryStart = req.originalUrl.indexOf('?')
@@ -21,9 +26,9 @@ function rawQueryOf(req: Request): string {
* untouched so the signed `state` and `code` are never re-encoded — and relay its
* response, including the HTML success page that bounces to clerum://oauth-completed.
*
- * This is the only public, unauthenticated route in this gateway, so it MUST stay a
- * thin passthrough: never read or trust anything beyond the validated path segments
- * and the opaque query string.
+ * These, together with the CIMD document below, are the only public, unauthenticated
+ * routes in this gateway, so they MUST stay thin passthroughs: never read or trust
+ * anything beyond the validated path segments and the opaque query string.
*/
export function createOauthCallbackRouter(): Router {
const router = Router()
@@ -66,5 +71,18 @@ export function createOauthCallbackRouter(): Router {
}
})
+ // PUBLIC CIMD document: a remote Authorization Server fetches our OAuth client
+ // identity here. Fixed path, no caller-controlled segment and no query string are
+ // forwarded (the forward carries this gateway's service token). Express answers
+ // HEAD through this GET handler.
+ router.get(CIMD_ROUTE_PATH, async (_req, res, next) => {
+ try {
+ const result = await controlApiPassthroughGet(CIMD_ROUTE_PATH, '')
+ res.status(result.status).type(result.contentType).send(result.body)
+ } catch (err) {
+ next(err)
+ }
+ })
+
return router
}
diff --git a/external-rest-api/test/routes.cimd.test.ts b/external-rest-api/test/routes.cimd.test.ts
new file mode 100644
index 000000000..84d5f66ff
--- /dev/null
+++ b/external-rest-api/test/routes.cimd.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import request from 'supertest'
+import { createApp } from '../src/app.js'
+import { config } from '../src/config.js'
+
+// The remote MCP-OAuth CIMD client_id is `<public origin>/api/v1/.well-known/evenfire-mcp-client`
+// (control-api/src/oauth/cimdIdentity.ts). A remote Authorization Server fetches it over
+// the public internet, and this gateway is the public hop in front of control-api, so the
+// document must be relayed here without a user session.
+const CIMD_PATH = '/api/v1/.well-known/evenfire-mcp-client'
+
+const CIMD_BODY = JSON.stringify({
+ client_id: `https://example.test${CIMD_PATH}`,
+ client_name: 'Evenfire',
+ redirect_uris: ['https://example.test/api/v1/oauth-callback/remote'],
+ token_endpoint_auth_method: 'none',
+ grant_types: ['authorization_code', 'refresh_token'],
+ response_types: ['code'],
+ application_type: 'web',
+})
+
+function stubControlApi() {
+ const fetchMock = vi.fn().mockResolvedValue(
+ new Response(CIMD_BODY, {
+ status: 200,
+ headers: { 'content-type': 'application/json; charset=utf-8' },
+ })
+ )
+ vi.stubGlobal('fetch', fetchMock)
+ return fetchMock
+}
+
+describe('CIMD document passthrough', () => {
+ afterEach(() => {
+ vi.unstubAllGlobals()
+ })
+
+ it('relays the control-api document to an unauthenticated GET', async () => {
+ const fetchMock = stubControlApi()
+ const res = await request(createApp()).get(CIMD_PATH).expect(200)
+
+ expect(res.headers['content-type']).toContain('application/json')
+ expect(res.body).toEqual(JSON.parse(CIMD_BODY))
+ expect(fetchMock).toHaveBeenCalledTimes(1)
+ const base = config.controlApiBaseUrl.replace(/\/+$/, '')
+ expect(fetchMock.mock.calls[0][0]).toBe(`${base}/.well-known/evenfire-mcp-client`)
+ expect(fetchMock.mock.calls[0][1]).toMatchObject({ method: 'GET' })
+ })
+
+ it('never forwards a caller-supplied query string', async () => {
+ const fetchMock = stubControlApi()
+ await request(createApp()).get(`${CIMD_PATH}?x=1&redirect=../admin`).expect(200)
+
+ const base = config.controlApiBaseUrl.replace(/\/+$/, '')
+ expect(fetchMock.mock.calls[0][0]).toBe(`${base}/.well-known/evenfire-mcp-client`)
+ })
+
+ it('relays a control-api failure status verbatim', async () => {
+ const fetchMock = vi.fn().mockResolvedValue(
+ new Response(JSON.stringify({ error: 'cimd_base_url_unconfigured' }), {
+ status: 503,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ vi.stubGlobal('fetch', fetchMock)
+
+ const res = await request(createApp()).get(CIMD_PATH).expect(503)
+ expect(res.body).toEqual({ error: 'cimd_base_url_unconfigured' })
+ })
+
+ it('does not expose any other method or sibling path', async () => {
+ const fetchMock = stubControlApi()
+ const app = createApp()
+
+ await request(app).post(CIMD_PATH).send({}).expect(404)
+ await request(app).get('/api/v1/.well-known/evenfire-mcp-client/extra').expect(404)
+ await request(app).get('/api/v1/.well-known/other').expect(404)
+ expect(fetchMock).not.toHaveBeenCalled()
+ })
+})
diff --git a/scripts/tests/test-profile-control-funnel-nginx-contract.sh b/scripts/tests/test-profile-control-funnel-nginx-contract.sh
new file mode 100755
index 000000000..06a78a8b4
--- /dev/null
+++ b/scripts/tests/test-profile-control-funnel-nginx-contract.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Pins the public surface of the profile-control-funnel nginx (the hop between
+# external-rest-api and control-api). Everything not listed here must stay 403.
+#
+# The remote MCP-OAuth CIMD client_id is <public origin>/api/v1/.well-known/evenfire-mcp-client
+# (control-api/src/oauth/cimdIdentity.ts). A remote Authorization Server fetches it
+# through external-rest-api and this funnel, so the funnel must forward that exact
+# path, read-only, and nothing broader under /.well-known/.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CONFIG="${1:-${ROOT}/deploy/base/profiles/configmaps.yaml}"
+CIMD_PATH='/api/v1/.well-known/evenfire-mcp-client'
+
+failed=0
+fail() {
+ echo "FAIL: $*" >&2
+ failed=1
+}
+
+# Print the body of the first nginx block whose opening line matches $1 exactly
+# (after trimming leading whitespace), up to its matching closing brace.
+block_of() {
+ awk -v want="$1" '
+ !inside {
+ line = $0
+ sub(/^[ \t]+/, "", line)
+ if (line == want) { inside = 1; depth = 1; next }
+ next
+ }
+ {
+ line = $0
+ depth += gsub(/\{/, "", line)
+ depth -= gsub(/\}/, "", line)
+ if (depth == 0) exit
+ print
+ }
+ ' "${CONFIG}"
+}
+
+[[ -f "${CONFIG}" ]] || {
+ echo "FAIL: missing ${CONFIG}" >&2
+ exit 1
+}
+
+# 1. Exact-match CIMD location, GET/HEAD only, fixed upstream URI.
+cimd_block="$(block_of "location = ${CIMD_PATH} {")"
+if [[ -z "${cimd_block}" ]]; then
+ fail "no exact-match 'location = ${CIMD_PATH}' block"
+else
+ grep -Eq '^[[:space:]]*limit_except GET \{' <<<"${cimd_block}" ||
+ fail "CIMD location must restrict methods with 'limit_except GET'"
+ grep -Eq '^[[:space:]]*deny all;' <<<"${cimd_block}" ||
+ fail "CIMD location limit_except must 'deny all'"
+ grep -Fq "proxy_pass http://\$control_api_origin${CIMD_PATH};" <<<"${cimd_block}" ||
+ fail "CIMD location must proxy to the fixed control-api CIMD path"
+ if grep -Fq '$request_uri' <<<"${cimd_block}"; then
+ fail "CIMD location must not forward the caller's request URI or query"
+ fi
+fi
+
+# 2. No other location may expose anything under /.well-known/.
+other_well_known="$(grep -E '^[[:space:]]*location[[:space:]]' "${CONFIG}" |
+ grep -F '.well-known' |
+ grep -vF "location = ${CIMD_PATH} {" || true)"
+if [[ -n "${other_well_known}" ]]; then
+ fail "unexpected /.well-known location(s): ${other_well_known}"
+fi
+
+# 3. The existing public surface and the deny-all fallback stay in place.
+grep -Eq '^[[:space:]]*location ~ \^/api/v1/external/ \{' "${CONFIG}" ||
+ fail "missing /api/v1/external/ location"
+grep -Eq '^[[:space:]]*location ~ \^/api/v1/oauth-callback/ \{' "${CONFIG}" ||
+ fail "missing /api/v1/oauth-callback/ location"
+fallback_block="$(block_of 'location / {')"
+grep -Eq '^[[:space:]]*return 403;' <<<"${fallback_block}" ||
+ fail "fallback 'location /' must return 403"
+
+if [[ "${failed}" -ne 0 ]]; then
+ exit 1
+fi
+echo "PASS: profile-control-funnel nginx public surface"