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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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