Skip to content

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

TypeScript

fix(control-api): carry the recovery step in identity-gated refusals

Alfredo Lopez908a3d091f73
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 404ca1cdf..c0d3f00d5 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.635",
+ "version": "0.1.636",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.635",
+ "version": "0.1.636",
"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 3199e881b..7bab7053e 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.635",
+ "version": "0.1.636",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/admin/secrets.ts b/control-api/src/routes/admin/secrets.ts
index 8e39b93fb..f4bf989e9 100644
--- a/control-api/src/routes/admin/secrets.ts
+++ b/control-api/src/routes/admin/secrets.ts
@@ -148,6 +148,16 @@ function isLegacyMcpSecretDeleteBody(raw: unknown): boolean {
)
}
+// Every 428 below is reached by a request that could not be fenced, and the
+// operator's remedy is the same in all of them: load the current state and
+// retry. The remedy travels in `message` because the client that most needs it
+// is the one that cannot render the code — a browser tab still running a UI
+// bundle from before this contract existed sends a bodyless delete, and its
+// error formatter prefers a `message` field over the raw `error` code. Newer
+// bundles map the code themselves and ignore this string, so it is additive.
+const SECRET_IDENTITY_PRECONDITION_REMEDY =
+ 'This page is out of date and the Secret was not changed. Reload the page, review the current state, and try again.'
+
// The plaintext data being written, merging base64 `data` and plaintext
// `stringData` (stringData wins, matching Kubernetes Secret semantics).
function effectiveSecretData(body: unknown): Record<string, string> {
@@ -664,10 +674,18 @@ export function createAdminSecretsRouter(
// The Secret exists in the cluster; only its identity is missing. Echo
// what IS known so the operator can name the object that needs repair —
// the sibling permit-unavailable 503 below does the same.
+ //
+ // The code is create-specific on purpose. The shared
+ // `secret_identity_unavailable` reads as "we could not verify the
+ // Secret you are acting on", which is true on a delete and misleading
+ // here: the Secret was created a moment ago and is still in the
+ // cluster, so the operator's next step is removing it, not reviewing
+ // it. Only this route emits the create variant.
res.status(503).json({
- error: 'secret_identity_unavailable',
+ error: 'mcp_secret_identity_unavailable_after_create',
outcome: 'repair_required',
created: { name: name.trim(), namespace: targetNs },
+ message: `Secret "${name.trim()}" was created but the server could not read back its identity, so the connector was not completed. Remove that Secret in "${targetNs}" before retrying.`,
})
return
}
@@ -688,6 +706,13 @@ export function createAdminSecretsRouter(
event: 'mcp-secret-create-rollback-permit-repair-required',
name: secretReq.name,
namespace: targetNs,
+ // The Secret is now an orphan: created, but with no permit that
+ // would let its own session roll it back. Identity is what
+ // distinguishes it from a hand-applied Secret of the same name, so
+ // it belongs in the line an operator reads when repairing. Both
+ // fields are apiserver metadata, never Secret data.
+ uid: completeIdentity.uid,
+ resourceVersion: completeIdentity.resourceVersion,
},
'MCP Secret create could not persist its rollback permit'
)
@@ -952,12 +977,18 @@ export function createAdminSecretsRouter(
// this session's JTI, the name, and the configured namespace — but the
// admitted set is wider than "the historical empty body" alone.
if (!isLegacyMcpSecretDeleteBody(req.body)) {
- res.status(428).json({ error: 'secret_identity_precondition_required' })
+ res.status(428).json({
+ error: 'secret_identity_precondition_required',
+ message: SECRET_IDENTITY_PRECONDITION_REMEDY,
+ })
return
}
const sessionJti = (req as UiAuthedRequest).adminAuth?.jti ?? ''
if (!sessionJti) {
- res.status(428).json({ error: 'secret_identity_precondition_required' })
+ res.status(428).json({
+ error: 'secret_identity_precondition_required',
+ message: SECRET_IDENTITY_PRECONDITION_REMEDY,
+ })
return
}
try {
@@ -1001,7 +1032,10 @@ export function createAdminSecretsRouter(
// the permit stays usable for the caller's retry instead of answering
// 428 for the rest of the lease.
await settleRollbackClaim('release')
- res.status(428).json({ error: 'secret_identity_precondition_required' })
+ res.status(428).json({
+ error: 'secret_identity_precondition_required',
+ message: SECRET_IDENTITY_PRECONDITION_REMEDY,
+ })
return
}
}
@@ -1031,7 +1065,10 @@ export function createAdminSecretsRouter(
return
}
if (!deletePrecondition) {
- res.status(428).json({ error: 'secret_identity_precondition_required' })
+ res.status(428).json({
+ error: 'secret_identity_precondition_required',
+ message: SECRET_IDENTITY_PRECONDITION_REMEDY,
+ })
return
}
if (
@@ -1495,7 +1532,10 @@ export function createAdminSecretsRouter(
}
const requestedPrecondition = requestSecretPreconditions(req.body)
if (!requestedPrecondition) {
- res.status(428).json({ error: 'secret_identity_precondition_required' })
+ res.status(428).json({
+ error: 'secret_identity_precondition_required',
+ message: SECRET_IDENTITY_PRECONDITION_REMEDY,
+ })
return
}
const currentPrecondition = secretIdentityPreconditions(existing)
diff --git a/control-api/test/routes.mcpSecrets.test.ts b/control-api/test/routes.mcpSecrets.test.ts
index 4e594dc40..21b9ca220 100644
--- a/control-api/test/routes.mcpSecrets.test.ts
+++ b/control-api/test/routes.mcpSecrets.test.ts
@@ -302,6 +302,72 @@ describe('POST /admin/mcp-secrets', () => {
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
+ // The Secret reached the cluster and the apiserver did not echo its identity.
+ // The shared `secret_identity_unavailable` code reads as "we could not verify
+ // the Secret you are acting on", which is right on a delete and wrong here:
+ // nothing is left to review, something is left to remove. A create-specific
+ // code plus a message naming the object is what makes the next step legible.
+ it('names the orphaned Secret when the create cannot read back its identity', async () => {
+ const gateway = createGateway()
+ // The one shape that reaches this branch: a create that succeeded but
+ // answered without uid/resourceVersion.
+ gateway.createSecret.mockResolvedValueOnce({
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ keys: ['LINEAR_API_KEY'],
+ } as never)
+
+ const res = await request(makeApp(gateway))
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(503)
+
+ expect(res.body.error).toBe('mcp_secret_identity_unavailable_after_create')
+ expect(res.body.outcome).toBe('repair_required')
+ expect(res.body.created).toEqual({ name: 'linear-credentials', namespace: 'mcp-server' })
+ // The operator must be able to find the object without a second lookup.
+ expect(res.body.message).toContain('linear-credentials')
+ expect(res.body.message).toContain('mcp-server')
+ expect(res.body.message).toMatch(/remove that secret/i)
+ // Witness that this exit ran rather than the create simply not happening:
+ // the Secret was written, and nothing tried to undo it.
+ expect(gateway.createSecret).toHaveBeenCalledOnce()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('logs the orphan identity when the rollback permit cannot be persisted', async () => {
+ const gateway = createGateway()
+ const rollbackPermits = createRollbackPermitStore()
+ rollbackPermits.issue.mockRejectedValueOnce(new Error('postgres unavailable'))
+ const errorSpy = vi.spyOn(rootLogger, 'error').mockImplementation(() => {})
+
+ try {
+ await request(makeApp(gateway, rollbackPermits))
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(503)
+
+ // Without uid/resourceVersion this line cannot distinguish the Secret the
+ // failed create left behind from a hand-applied Secret of the same name,
+ // which is the whole question an operator arrives with.
+ expect(errorSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ module: 'admin-secrets',
+ event: 'mcp-secret-create-rollback-permit-repair-required',
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-linear-credentials',
+ resourceVersion: '1',
+ }),
+ 'MCP Secret create could not persist its rollback permit'
+ )
+ // Kubernetes metadata only: the credential must never reach the log.
+ expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('create-value')
+ } finally {
+ errorSpy.mockRestore()
+ }
+ })
+
it('trims whitespace from name', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
diff --git a/control-api/test/routes.secrets.test.ts b/control-api/test/routes.secrets.test.ts
index a00350a0d..ea97baecb 100644
--- a/control-api/test/routes.secrets.test.ts
+++ b/control-api/test/routes.secrets.test.ts
@@ -510,6 +510,29 @@ describe('routes/secrets', () => {
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
+ // The request above is exactly what a browser tab still running a UI bundle
+ // from before this contract sends, and that bundle cannot map the code: its
+ // error formatter reads `message` first and otherwise renders the raw body.
+ // Without a message the operator is shown
+ // "428 Precondition Required - secret_identity_precondition_required" and is
+ // told nothing about the reload that fixes it. The remedy therefore has to
+ // travel in the response, not in the client that is too old to hold it.
+ it('tells a client too old to map the code how to recover from the 428', async () => {
+ const gateway = createRecipeGateway()
+ const app = express()
+ app.use(express.json())
+ app.use(createAdminSecretsRouter(gateway as never))
+
+ const res = await request(app).delete('/admin/recipe-secrets/r1').expect(428)
+
+ expect(res.body.error).toBe('secret_identity_precondition_required')
+ expect(typeof res.body.message).toBe('string')
+ expect(res.body.message).toMatch(/reload the page/i)
+ // The remedy must not be the only thing this exit produced: the refusal is
+ // still fail-closed and the Secret is untouched.
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
// The 428 above only proves a body is REQUIRED; nothing proved the body is
// COMPARED. Replacing the comparison with `false` — deleting whatever the
// caller named, whoever replaced it in the meantime — left the whole suite