Skip to content

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

TypeScript

fix(control-api): key MCP Secret delete limits on the admin principal

Alfredo Lopez4f91d758cc62
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 42e274bd2..f535df78c 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.633",
+ "version": "0.1.634",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.633",
+ "version": "0.1.634",
"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 69a52a844..a6d907f97 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.633",
+ "version": "0.1.634",
"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 3192fcbe3..6155fd06f 100644
--- a/control-api/src/routes/admin/secrets.ts
+++ b/control-api/src/routes/admin/secrets.ts
@@ -61,10 +61,15 @@ const mcpSecretDeleteEdgeRateLimit = rateLimit({
limit: 60,
standardHeaders: 'draft-7',
legacyHeaders: false,
+ // Keyed on `sub`, not `jti`: `signAdminToken` mints a fresh `jti` on every
+ // login (utils/auth/adminAuthToken.ts:21), so a per-`jti` budget resets each
+ // time the same admin re-authenticates. `sub` is the stable principal, which
+ // is what the sibling admin buckets use (registry.ts:4420, :4556) and what
+ // pluginWorkloadSdkRateLimits.ts:63-66 already did.
keyGenerator: req => {
- const sessionJti = (req as UiAuthedRequest).adminAuth?.jti
- return sessionJti
- ? `admin-session:${createHash('sha256').update(sessionJti).digest('hex')}`
+ const adminSub = (req as UiAuthedRequest).adminAuth?.sub
+ return adminSub
+ ? `admin-session:${createHash('sha256').update(adminSub).digest('hex')}`
: ipKeyGenerator(req.ip ?? '127.0.0.1')
},
})
@@ -72,9 +77,11 @@ const mcpSecretDeleteEdgeRateLimit = rateLimit({
const mcpSecretDeleteRateLimit = rateLimitMiddleware({
bucketType: 'admin_mcp_secret_delete',
maxPerMinute: 30,
+ // Same reasoning as mcpSecretDeleteEdgeRateLimit: the stable principal, so
+ // re-authenticating does not hand the caller a fresh delete budget.
getBucketKey: req => {
- const sessionJti = (req as UiAuthedRequest).adminAuth?.jti
- const caller = sessionJti || req.ip || 'unknown-admin'
+ const adminSub = (req as UiAuthedRequest).adminAuth?.sub
+ const caller = adminSub || req.ip || 'unknown-admin'
return `admin-mcp-secret-delete:${createHash('sha256').update(caller).digest('hex')}`
},
// Required by RateLimitEnforcerOptions since dev made the choice explicit; the
@@ -932,9 +939,18 @@ export function createAdminSecretsRouter(
// Current clients send the identity returned by POST and retain the
// established compare-and-delete contract.
} else {
- // Only the historical empty DELETE body can use the short-lived
- // server-side permit issued during this admin session's successful
- // create. Any other body must use the complete identity contract.
+ // Only a body that carries no caller-supplied field can use the
+ // short-lived server-side permit issued during this admin session's
+ // successful create. Any other body must use the complete identity
+ // contract.
+ //
+ // "No field" is what reaches this check, not what the client sent:
+ // enforceNamespace (registered on this route above) deletes a
+ // top-level `namespace` before the handler runs, so `{"namespace":…}`
+ // arrives as `{}` and also takes the permit path. That grants nothing
+ // — the namespace is server-determined, and the permit is bound to
+ // 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' })
return
diff --git a/control-api/test/db.migrationsOrder.test.ts b/control-api/test/db.migrationsOrder.test.ts
index 08a93da70..61f5f25c0 100644
--- a/control-api/test/db.migrationsOrder.test.ts
+++ b/control-api/test/db.migrationsOrder.test.ts
@@ -59,10 +59,14 @@ describe('CONTROL_API_MIGRATIONS ordering invariant', () => {
expect(currentCollisions).toEqual([])
})
- it('requires 0109_mcp_secret_rollback_permits to persist expiring rollback permits', async () => {
+ it('requires 0116_mcp_secret_rollback_permits to persist expiring rollback permits', async () => {
const { CONTROL_API_MIGRATIONS } = await import('../src/db.js')
+ // Renumbered twice while syncing onto dev: 0101 -> 0109 -> 0116. The earlier
+ // names survive only in this migration's legacyVersions, and the test above
+ // forbids an alias from colliding with a current version, so looking one up
+ // here by its old name can only ever find nothing.
const migration = CONTROL_API_MIGRATIONS.find(
- candidate => candidate.version === '0109_mcp_secret_rollback_permits'
+ candidate => candidate.version === '0116_mcp_secret_rollback_permits'
)
expect(migration).toBeDefined()
diff --git a/control-api/test/routes.recipeSecrets.ownership.test.ts b/control-api/test/routes.recipeSecrets.ownership.test.ts
index a1fa3000a..c2bc24733 100644
--- a/control-api/test/routes.recipeSecrets.ownership.test.ts
+++ b/control-api/test/routes.recipeSecrets.ownership.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from 'vitest'
import express from 'express'
import request from 'supertest'
+import { clerumErrorHandler } from '../src/http/errorHandler.js'
import { createAdminSecretsRouter } from '../src/routes/admin/secrets.js'
interface MockSecret {
@@ -85,12 +86,11 @@ function makeApp(gateway: ReturnType<typeof createGateway>) {
const app = express()
app.use(express.json())
app.use(createAdminSecretsRouter(gateway as never))
- app.use(
- (err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
- const message = err instanceof Error ? err.message : 'unknown'
- res.status(500).json({ error: 'Internal Server Error', message })
- }
- )
+ // The production handler, not a local stand-in. A hand-written handler here
+ // would let a test assert a response shape the real app never emits, so the
+ // 500-propagation test below would be verifying this file instead of
+ // src/http/errorHandler.ts.
+ app.use(clerumErrorHandler)
return app
}
diff --git a/docs/how-to/control-api-mcp-secret-rollback-permits.md b/docs/how-to/control-api-mcp-secret-rollback-permits.md
index 793699ec3..78825d096 100644
--- a/docs/how-to/control-api-mcp-secret-rollback-permits.md
+++ b/docs/how-to/control-api-mcp-secret-rollback-permits.md
@@ -7,7 +7,7 @@ bodyless rollback path of `POST /admin/mcp-secrets` followed by
## Deployment contract
1. Run the Control API schema migration job before changing the pod image.
-2. Verify migration `0109_mcp_secret_rollback_permits` and the runtime-access
+2. Verify migration `0116_mcp_secret_rollback_permits` and the runtime-access
profile before starting Control API.
3. Deploy Control API with its repository-owned `Recreate` strategy and one
replica. Old and new API writers must not overlap.
@@ -37,24 +37,24 @@ Run the database-migration job **before** rolling the Control API image. The
Control API deployment is `strategy: Recreate` with a single replica
(`deploy/base/control-plane/control-api.yaml`), so the old pod is terminated
before the new one starts. A new image deployed against a database that has not
-yet applied `0109` fails `assertDbReady` on startup with
-`missing migrations 0109_mcp_secret_rollback_permits` — and because the previous
+yet applied `0116` fails `assertDbReady` on startup with
+`missing migrations 0116_mcp_secret_rollback_permits` — and because the previous
pod is already gone, that is a full control-plane outage, not a stalled
rollout. The CRD apply is independent of this ordering: control-api reads the
Secret-reference contract from a compiled-in constant, not from the CRD
annotation, so the charts may be applied before or after the image.
-## Image rollback after migration 0109
+## Image rollback after migration 0116
Rollback is **image-only**:
-1. Keep migration `0109`, the new table, and the current runtime-access profile.
+1. Keep migration `0116`, the new table, and the current runtime-access profile.
2. Use the current checkout's deployment and database-migration tooling.
3. Change only the Control API image to the previously verified image.
4. Re-run the current runtime-access reconciliation and exact privilege check.
The previous Control API binary ignores the additive table. Do not run an old
-checkout's exact-schema verifier after `0109`; it does not know the new public
+checkout's exact-schema verifier after `0116`; it does not know the new public
relation and will correctly refuse to certify it. Never drop the table as part
of an application-image rollback.