Skip to content

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

TypeScript

fix(control-api): map discovery transport failures to 424 instead of 502

Diego Zacarias66da8017d4c4
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index a23a003e7..da592a3cd 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.799",
+ "version": "0.1.800",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.799",
+ "version": "0.1.800",
"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 b5f61f66e..4fba5c351 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.799",
+ "version": "0.1.800",
"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/discoveryHttpStatus.ts b/control-api/src/oauth/discoveryHttpStatus.ts
index 4a17a79ab..2a24ed5e0 100644
--- a/control-api/src/oauth/discoveryHttpStatus.ts
+++ b/control-api/src/oauth/discoveryHttpStatus.ts
@@ -3,22 +3,24 @@ import type { DiscoveryError } from './discovery.js'
/**
* Map a discovery failure to an HTTP status for the OAuth discovery admin endpoints
* (remote `POST /admin/mcp-servers/remote/discover` and generic
- * `POST /admin/oauth/discover`). Extracted here (H-5) so both share ONE mapping.
+ * `POST /admin/oauth/discover`) and for the remote install's own discovery. Extracted
+ * here (H-5) so all of them share ONE mapping.
*
- * `fetch_failed` and `content_encoding_rejected` are upstream transport failures —
- * the AS never returned a usable HTTP response — so they surface as 502, the same
- * way the callback maps provider fetch failures (`provider_token_exchange_failed` /
- * `provider_response_invalid` → 502). Every other kind is either bad operator input
- * (`kernel_rejected`) or a reachable-but-incompatible/misconfigured AS: retrying will
- * not help, and the returned `detail.kind` tells the operator what to fix, so 400 is
- * the operator-actionable signal. The switch is exhaustive over `DiscoveryError` so a
- * newly added kind fails to compile until its status is decided here.
+ * `fetch_failed` and `content_encoding_rejected` mean a dependency failed — the AS or
+ * the remote server never returned a usable response (an unknown Entra tenant answers
+ * its well-known with a 400, for instance) — so they surface as 424 Failed Dependency.
+ * Not a 5xx: the edge proxy (Cloudflare) replaces an origin 5xx with its own page, and
+ * the wizard would lose the typed `detail` that says which dependency failed. Every
+ * other kind is either bad operator input (`kernel_rejected`) or a reachable but
+ * incompatible/misconfigured AS: retrying will not help, and `detail.kind` tells the
+ * operator what to fix, so 400. No kind maps to a 5xx. The switch is exhaustive over
+ * `DiscoveryError` so a newly added kind fails to compile until its status is decided here.
*/
export function discoveryHttpStatus(error: DiscoveryError): number {
switch (error.kind) {
case 'fetch_failed':
case 'content_encoding_rejected':
- return 502
+ return 424
case 'kernel_rejected':
case 'invalid_metadata':
case 'no_s256':
diff --git a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts
index 9ed7d9300..f2c14e96b 100644
--- a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts
+++ b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts
@@ -62,13 +62,13 @@ function buildApp(discover: ReturnType<typeof fetchFailedDiscover>) {
}
describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table', () => {
- // One entry per DiscoveryError.kind. 502 = upstream transport failure (AS gave no
- // usable HTTP response); 400 = operator-actionable (bad input or reachable-but-
- // incompatible AS).
+ // One entry per DiscoveryError.kind. 424 = a dependency failed (the AS or the remote
+ // server gave no usable response); 400 = operator-actionable (bad input or reachable-
+ // but-incompatible AS). Never a 5xx: the edge proxy would replace the typed body.
const cases: Array<{ error: DiscoveryError; status: number }> = [
{
error: { kind: 'fetch_failed', url: 'https://as.example.test/x', detail: 'ECONNREFUSED' },
- status: 502,
+ status: 424,
},
{
error: {
@@ -76,7 +76,7 @@ describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table'
url: 'https://as.example.test/x',
encoding: 'br',
},
- status: 502,
+ status: 424,
},
{ error: { kind: 'kernel_rejected', field: 'baseUrl', errors: [] }, status: 400 },
{
@@ -129,6 +129,33 @@ describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table'
expect(discoveryHttpStatus(error)).toBe(status)
})
}
+
+ it('the table lists every DiscoveryError kind exactly once', () => {
+ const kinds = cases.map(c => c.error.kind)
+ expect(new Set(kinds).size).toBe(kinds.length)
+ expect([...kinds].sort()).toEqual(
+ [
+ 'as_endpoints_cross_site',
+ 'authorization_server_override_rejected',
+ 'content_encoding_rejected',
+ 'fetch_failed',
+ 'invalid_metadata',
+ 'issuer_mismatch',
+ 'kernel_rejected',
+ 'no_authorization_server',
+ 'no_s256',
+ 'prm_resource_mismatch',
+ 'redirect_blocked',
+ 'tenant_required',
+ ].sort()
+ )
+ })
+
+ it('I8: no DiscoveryError kind maps to a 5xx', () => {
+ for (const { error } of cases) {
+ expect(discoveryHttpStatus(error)).toBeLessThan(500)
+ }
+ })
})
describe('POST /admin/mcp-servers/remote/discover — discovery error mapping', () => {
@@ -136,7 +163,7 @@ describe('POST /admin/mcp-servers/remote/discover — discovery error mapping',
vi.clearAllMocks()
})
- it('returns 502 (not 400) when discovery fails with fetch_failed (upstream transport)', async () => {
+ it('returns 424 (not 400, not 5xx) when discovery fails with fetch_failed (upstream transport)', async () => {
const discover = fetchFailedDiscover()
const app = buildApp(discover)
@@ -144,7 +171,7 @@ describe('POST /admin/mcp-servers/remote/discover — discovery error mapping',
.post('/api/v1/admin/mcp-servers/remote/discover')
.send({ baseUrl: BASE_URL })
- expect(res.status).toBe(502)
+ expect(res.status).toBe(424)
expect(res.body.error).toBe('discovery_failed')
expect(res.body.detail.kind).toBe('fetch_failed')
// Never hit the real network: the discovery seam was the only source of the outcome.
diff --git a/control-api/test/routes.adminRemoteMcp.test.ts b/control-api/test/routes.adminRemoteMcp.test.ts
index f5364f91d..342c35fa8 100644
--- a/control-api/test/routes.adminRemoteMcp.test.ts
+++ b/control-api/test/routes.adminRemoteMcp.test.ts
@@ -2687,6 +2687,19 @@ describe('Microsoft Entra ID — authorizationServer override on /discover and i
expect(res.body.detected.issForCallback).toBeUndefined()
})
+ it("row 4: an unknown tenant → 424 fetch_failed carrying Entra's 400 and its URL", async () => {
+ const unknownTenant =
+ 'https://login.microsoftonline.com/00000000-0000-0000-0000-000000000001/v2.0'
+ const res = await request(await entraApp(ENTRA_WORKIQ_PILOT, gatewayWithContext()))
+ .post('/admin/mcp-servers/remote/discover')
+ .send({ baseUrl: ENTRA_WORKIQ_PILOT.mcpUrl, authorizationServer: unknownTenant })
+ expect(res.status).toBe(424)
+ expect(res.body.error).toBe('discovery_failed')
+ expect(res.body.detail.kind).toBe('fetch_failed')
+ expect(res.body.detail.status).toBe(400)
+ expect(res.body.detail.url.startsWith('https://login.microsoftonline.com/')).toBe(true)
+ })
+
it('Agent 365 Mail: offline_access, already in its PRM, is not added twice', async () => {
const res = await request(await entraApp(ENTRA_AGENT365_MAIL_PILOT, gatewayWithContext()))
.post('/admin/mcp-servers/remote/discover')
diff --git a/control-api/test/routes.oauthProviders.test.ts b/control-api/test/routes.oauthProviders.test.ts
index 48efd9554..a369f9aea 100644
--- a/control-api/test/routes.oauthProviders.test.ts
+++ b/control-api/test/routes.oauthProviders.test.ts
@@ -114,7 +114,7 @@ describe('POST /admin/oauth/discover (E-19.5)', () => {
expect(res.body.suggested.supportsRefresh).toBe(true)
})
- it('maps a transport failure to 502 (discoveryHttpStatus)', async () => {
+ it('maps a transport failure to 424 (discoveryHttpStatus)', async () => {
const discover: AdminOauthProvidersDeps['discover'] = async () => ({
ok: false,
error: { kind: 'fetch_failed', url: 'https://mcp.notion.com', detail: 'boom' },
@@ -122,7 +122,7 @@ describe('POST /admin/oauth/discover (E-19.5)', () => {
const res = await request(makeApp({ discover }))
.post('/admin/oauth/discover')
.send({ url: 'https://mcp.notion.com' })
- .expect(502)
+ .expect(424)
expect(res.body.error).toBe('discovery_failed')
expect(res.body.detail.kind).toBe('fetch_failed')
})