Skip to content

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

TypeScript

fix(security): move rollback permits server-side

Alfredo Lopez1897ee151a4c
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 73cd7fa1f..ef2da0e91 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.507",
+ "version": "0.1.508",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.507",
+ "version": "0.1.508",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 7e2fe6f5d..1d80aea3f 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.507",
+ "version": "0.1.508",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/db.ts b/control-api/src/db.ts
index 4d37efad1..1a4b716b5 100644
--- a/control-api/src/db.ts
+++ b/control-api/src/db.ts
@@ -3016,6 +3016,36 @@ async function applyControlAdminSessionVersionDefaultSchema(db: DbClient): Promi
`)
}
+async function applyMcpSecretRollbackPermitSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS mcp_secret_rollback_permits (
+ session_hash BYTEA NOT NULL CHECK (octet_length(session_hash) = 32),
+ namespace TEXT NOT NULL,
+ name TEXT NOT NULL,
+ uid TEXT NOT NULL,
+ resource_version TEXT NOT NULL,
+ expires_at TIMESTAMPTZ NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT statement_timestamp(),
+ claim_token UUID,
+ claim_expires_at TIMESTAMPTZ,
+ PRIMARY KEY (session_hash, namespace, name),
+ CHECK (expires_at > created_at),
+ CHECK (expires_at <= created_at + INTERVAL '120 seconds'),
+ CHECK ((claim_token IS NULL) = (claim_expires_at IS NULL)),
+ CHECK (claim_expires_at IS NULL OR claim_expires_at <= expires_at)
+ );
+
+ CREATE INDEX IF NOT EXISTS mcp_secret_rollback_permits_expires_at_idx
+ ON mcp_secret_rollback_permits (expires_at);
+
+ REVOKE ALL ON TABLE mcp_secret_rollback_permits FROM PUBLIC;
+ GRANT SELECT, INSERT, UPDATE, DELETE
+ ON TABLE mcp_secret_rollback_permits TO control_api_runtime;
+ REVOKE TRUNCATE, REFERENCES, TRIGGER
+ ON TABLE mcp_secret_rollback_permits FROM control_api_runtime;
+ `)
+}
+
// Exported (read-only) so the migration-order invariant test can assert the
// array is monotonic by version-string. Applied strictly in array order and
// tracked by full version-string in `schema_migrations`, so a non-monotonic
@@ -5932,6 +5962,10 @@ export const CONTROL_API_MIGRATIONS: DbMigration[] = [
`)
},
},
+ {
+ version: '0101_mcp_secret_rollback_permits',
+ apply: applyMcpSecretRollbackPermitSchema,
+ },
]
async function consolidateWorkflowAllowedUsersToTriggers(db: DbClient): Promise<void> {
diff --git a/control-api/src/routes/admin/secrets.ts b/control-api/src/routes/admin/secrets.ts
index bb415c79e..fe3186c91 100644
--- a/control-api/src/routes/admin/secrets.ts
+++ b/control-api/src/routes/admin/secrets.ts
@@ -17,27 +17,40 @@ import {
type SecretOwnership,
parseSecretOwnership,
} from '../../secretOwnership.js'
+import {
+ type McpSecretRollbackPermit,
+ type McpSecretRollbackPermitClaim,
+ type McpSecretRollbackPermitClaimBinding,
+ type McpSecretRollbackPermitLookup,
+ claimMcpSecretRollbackPermit,
+ finalizeMcpSecretRollbackPermitClaim,
+ issueMcpSecretRollbackPermit,
+ releaseMcpSecretRollbackPermitClaim,
+} from '../../services/mcpSecretRollbackPermitService.js'
import { invalidSecretDataKeyReason } from '../../services/secretKeys.js'
import { findSecretReferenceState } from '../../services/secretReferenceService.js'
import { secretIdentityPreconditions } from '../../services/secretRepository.js'
import { toPublicDeleteSecretSummary, toPublicSecretSummary } from '../../services/secretService.js'
import { SecretPreconditions, SecretUpsertRequest } from '../../types.js'
-import {
- MCP_SECRET_DELETE_PROOF_TTL_SECONDS,
- createMcpSecretDeleteProof,
- mcpSecretDeleteProofCookieName,
- verifyMcpSecretDeleteProof,
-} from '../../utils/auth/mcpSecretDeleteProof.js'
-import {
- clearHttpOnlySessionCookie,
- readCookie,
- setHttpOnlySessionCookie,
-} from '../../utils/auth/sessionCookies.js'
import { listHostSecrets } from './hostSecrets.js'
import { isLlmHostSecret } from './llmSecretIdentity.js'
const logger = rootLogger
+export type McpSecretRollbackPermitStore = {
+ issue(input: McpSecretRollbackPermit): Promise<void>
+ claim(input: McpSecretRollbackPermitLookup): Promise<McpSecretRollbackPermitClaim | null>
+ release(input: McpSecretRollbackPermitClaimBinding): Promise<void>
+ finalize(input: McpSecretRollbackPermitClaimBinding): Promise<void>
+}
+
+const defaultMcpSecretRollbackPermitStore: McpSecretRollbackPermitStore = {
+ issue: issueMcpSecretRollbackPermit,
+ claim: claimMcpSecretRollbackPermit,
+ release: releaseMcpSecretRollbackPermitClaim,
+ finalize: finalizeMcpSecretRollbackPermitClaim,
+}
+
const mcpSecretDeleteEdgeRateLimit = rateLimit({
windowMs: 60_000,
limit: 60,
@@ -285,7 +298,10 @@ export function validateLlmSecretSlots(body: unknown): string | null {
return null
}
-export function createAdminSecretsRouter(gateway: K8sGateway): Router {
+export function createAdminSecretsRouter(
+ gateway: K8sGateway,
+ rollbackPermits: McpSecretRollbackPermitStore = defaultMcpSecretRollbackPermitStore
+): Router {
const router = Router()
router.get(
@@ -588,21 +604,37 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
res.status(503).json({ error: 'secret_identity_unavailable', outcome: 'repair_required' })
return
}
- const sessionJti = (req as UiAuthedRequest).adminAuth?.jti
- if (sessionJti) {
- setHttpOnlySessionCookie(
- req,
- res,
- mcpSecretDeleteProofCookieName(secretReq.name),
- createMcpSecretDeleteProof({
+ const rollbackPermit: McpSecretRollbackPermit = {
+ sessionJti: (req as UiAuthedRequest).adminAuth?.jti ?? '',
+ name: secretReq.name,
+ namespace: targetNs,
+ uid: completeIdentity.uid,
+ resourceVersion: completeIdentity.resourceVersion,
+ }
+ try {
+ await rollbackPermits.issue(rollbackPermit)
+ } catch (err) {
+ logger.error(
+ {
+ err,
+ module: 'admin-secrets',
+ event: 'mcp-secret-create-rollback-permit-repair-required',
+ name: secretReq.name,
+ namespace: targetNs,
+ },
+ 'MCP Secret create could not persist its rollback permit'
+ )
+ res.status(503).json({
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
name: secretReq.name,
namespace: targetNs,
uid: completeIdentity.uid,
resourceVersion: completeIdentity.resourceVersion,
- sessionJti,
- }),
- MCP_SECRET_DELETE_PROOF_TTL_SECONDS
- )
+ },
+ })
+ return
}
res.status(201).json({
name: name.trim(),
@@ -816,26 +848,80 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
const name = req.params.name.trim()
const requestedPrecondition = requestSecretPreconditions(req.body)
let deletePrecondition: SecretPreconditions | null = requestedPrecondition
- let signedCreateProof: { proof: string; sessionJti: string } | null = null
+ let rollbackClaim: McpSecretRollbackPermitClaimBinding | null = null
+ const settleRollbackClaim = async (mode: 'release' | 'finalize'): Promise<void> => {
+ if (!rollbackClaim) return
+ const binding = rollbackClaim
+ rollbackClaim = null
+ try {
+ await rollbackPermits[mode](binding)
+ } catch (err) {
+ logger.warn(
+ {
+ err,
+ module: 'admin-secrets',
+ event: `mcp-secret-delete-rollback-claim-${mode}-failed`,
+ name,
+ namespace: config.mcpServersNamespace,
+ },
+ `MCP Secret rollback claim could not ${mode}`
+ )
+ }
+ }
if (requestedPrecondition) {
// 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 stateless rollback
- // proof minted during this browser session's successful create. Any
- // other body must use the normal complete identity contract.
+ // 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.
if (!isLegacyMcpSecretDeleteBody(req.body)) {
res.status(428).json({ error: 'secret_identity_precondition_required' })
return
}
const sessionJti = (req as UiAuthedRequest).adminAuth?.jti ?? ''
- const proofCookieName = mcpSecretDeleteProofCookieName(name)
- const proofCookie = readCookie(req, proofCookieName)
- if (!sessionJti || !proofCookie) {
+ if (!sessionJti) {
+ res.status(428).json({ error: 'secret_identity_precondition_required' })
+ return
+ }
+ try {
+ const claimed = await rollbackPermits.claim({
+ sessionJti,
+ name,
+ namespace: config.mcpServersNamespace,
+ })
+ deletePrecondition = claimed
+ ? { uid: claimed.uid, resourceVersion: claimed.resourceVersion }
+ : null
+ if (claimed) {
+ rollbackClaim = {
+ sessionJti,
+ name,
+ namespace: config.mcpServersNamespace,
+ claimToken: claimed.claimToken,
+ }
+ }
+ } catch (err) {
+ logger.error(
+ {
+ err,
+ module: 'admin-secrets',
+ event: 'mcp-secret-delete-rollback-permit-unavailable',
+ name,
+ namespace: config.mcpServersNamespace,
+ },
+ 'MCP Secret delete could not read its rollback permit'
+ )
+ res.status(503).json({
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ })
+ return
+ }
+ if (!deletePrecondition?.uid || !deletePrecondition.resourceVersion) {
res.status(428).json({ error: 'secret_identity_precondition_required' })
return
}
- signedCreateProof = { proof: proofCookie, sessionJti }
}
let existing: {
metadata?: { labels?: Record<string, string>; uid?: string; resourceVersion?: string }
@@ -844,38 +930,24 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
existing = (await gateway.getSecret(name, config.mcpServersNamespace)) as typeof existing
} catch (err) {
if (extractHttpStatus(err) === 404) {
+ await settleRollbackClaim('finalize')
res.status(404).json({ error: `Secret "${name}" not found` })
return
}
+ await settleRollbackClaim('release')
throw err
}
if (!existing) {
+ await settleRollbackClaim('finalize')
res.status(404).json({ error: `Secret "${name}" not found` })
return
}
const currentPrecondition = secretIdentityPreconditions(existing)
if (!currentPrecondition) {
+ await settleRollbackClaim('release')
res.status(503).json({ error: 'secret_identity_unavailable', outcome: 'repair_required' })
return
}
- if (signedCreateProof) {
- const proofVerification = verifyMcpSecretDeleteProof(signedCreateProof.proof, {
- name,
- namespace: config.mcpServersNamespace,
- uid: currentPrecondition.uid!,
- resourceVersion: currentPrecondition.resourceVersion!,
- sessionJti: signedCreateProof.sessionJti,
- })
- if (proofVerification === 'identity-mismatch') {
- res.status(409).json({ error: 'secret_identity_changed', outcome: 'repair_required' })
- return
- }
- if (proofVerification !== 'valid') {
- res.status(428).json({ error: 'secret_identity_precondition_required' })
- return
- }
- deletePrecondition = currentPrecondition
- }
if (!deletePrecondition) {
res.status(428).json({ error: 'secret_identity_precondition_required' })
return
@@ -884,10 +956,12 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
currentPrecondition.uid !== deletePrecondition.uid ||
currentPrecondition.resourceVersion !== deletePrecondition.resourceVersion
) {
+ await settleRollbackClaim('finalize')
res.status(409).json({ error: 'secret_identity_changed', outcome: 'repair_required' })
return
}
if (existing.metadata?.labels?.[RECIPE_SECRET_LABEL_KEY] === RECIPE_SECRET_LABEL_VALUE) {
+ await settleRollbackClaim('release')
res.status(409).json({
error: `Secret "${name}" is owned by a WorkflowRecipe; delete it through /admin/recipe-secrets`,
})
@@ -899,25 +973,27 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
config.mcpServersNamespace
)
if (referenceState === 'referenced') {
+ await settleRollbackClaim('release')
res.status(409).json({ error: 'mcp_secret_in_use', outcome: 'repair_required' })
return
}
if (referenceState === 'unknown') {
+ await settleRollbackClaim('release')
res
.status(503)
.json({ error: 'mcp_secret_reference_check_unavailable', outcome: 'repair_required' })
return
}
- if (signedCreateProof) {
+ if (rollbackClaim) {
logger.warn(
{
module: 'admin-secrets',
- event: 'mcp-secret-delete-legacy-signed-create-proof',
+ event: 'mcp-secret-delete-legacy-server-side-permit',
name,
namespace: config.mcpServersNamespace,
- preconditionSource: 'signed-create-proof',
+ preconditionSource: 'server-side-permit',
},
- 'MCP Secret delete used signed create proof'
+ 'MCP Secret delete used a server-side rollback permit'
)
}
try {
@@ -926,13 +1002,15 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
config.mcpServersNamespace,
deletePrecondition
)
- clearHttpOnlySessionCookie(req, res, mcpSecretDeleteProofCookieName(name))
+ await settleRollbackClaim('finalize')
res.status(200).json(toPublicDeleteSecretSummary(deleted))
} catch (err) {
if (extractHttpStatus(err) === 409) {
+ await settleRollbackClaim('finalize')
res.status(409).json({ error: 'secret_identity_changed', outcome: 'repair_required' })
return
}
+ await settleRollbackClaim('release')
throw err
}
})
diff --git a/control-api/src/services/mcpSecretRollbackPermitService.ts b/control-api/src/services/mcpSecretRollbackPermitService.ts
new file mode 100644
index 000000000..d83783e29
--- /dev/null
+++ b/control-api/src/services/mcpSecretRollbackPermitService.ts
@@ -0,0 +1,160 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { type DbClient, pool } from '../db.js'
+import type { SecretPreconditions } from '../types.js'
+
+export const MCP_SECRET_ROLLBACK_PERMIT_TTL_SECONDS = 120
+export const MCP_SECRET_ROLLBACK_CLAIM_TTL_SECONDS = 15
+
+export type McpSecretRollbackPermit = {
+ sessionJti: string
+ name: string
+ namespace: string
+ uid: string
+ resourceVersion: string
+}
+
+export type McpSecretRollbackPermitLookup = Pick<
+ McpSecretRollbackPermit,
+ 'sessionJti' | 'name' | 'namespace'
+>
+
+export type McpSecretRollbackPermitClaim = SecretPreconditions & {
+ claimToken: string
+}
+
+export type McpSecretRollbackPermitClaimBinding = McpSecretRollbackPermitLookup & {
+ claimToken: string
+}
+
+type QueryClient = Pick<DbClient, 'query'>
+
+const SESSION_HASH_DOMAIN = 'mcp-secret-rollback-permit:v1:'
+
+function requireField(value: string): string {
+ const normalized = value.trim()
+ if (!normalized) throw new Error('invalid_mcp_secret_rollback_permit')
+ return normalized
+}
+
+function sessionJtiHash(sessionJti: string): Buffer {
+ return createHash('sha256')
+ .update(SESSION_HASH_DOMAIN, 'utf8')
+ .update(requireField(sessionJti), 'utf8')
+ .digest()
+}
+
+export async function issueMcpSecretRollbackPermit(
+ permit: McpSecretRollbackPermit,
+ db: QueryClient = pool
+): Promise<void> {
+ const params = [
+ sessionJtiHash(permit.sessionJti),
+ requireField(permit.namespace),
+ requireField(permit.name),
+ requireField(permit.uid),
+ requireField(permit.resourceVersion),
+ MCP_SECRET_ROLLBACK_PERMIT_TTL_SECONDS,
+ ]
+ await db.query(`
+ DELETE FROM mcp_secret_rollback_permits
+ WHERE ctid IN (
+ SELECT ctid
+ FROM mcp_secret_rollback_permits
+ WHERE expires_at <= statement_timestamp()
+ ORDER BY expires_at
+ LIMIT 100
+ )
+ `)
+ await db.query(
+ `INSERT INTO mcp_secret_rollback_permits
+ (session_hash, namespace, name, uid, resource_version, expires_at)
+ VALUES ($1, $2, $3, $4, $5, statement_timestamp() + interval '1 second' * $6)
+ ON CONFLICT (session_hash, namespace, name)
+ DO UPDATE SET
+ uid = EXCLUDED.uid,
+ resource_version = EXCLUDED.resource_version,
+ expires_at = EXCLUDED.expires_at,
+ created_at = statement_timestamp()`,
+ params
+ )
+}
+
+export async function claimMcpSecretRollbackPermit(
+ lookup: McpSecretRollbackPermitLookup,
+ db: QueryClient = pool
+): Promise<McpSecretRollbackPermitClaim | null> {
+ const claimToken = randomUUID()
+ const result = await db.query(
+ `UPDATE mcp_secret_rollback_permits
+ SET claim_token = $4::uuid,
+ claim_expires_at = LEAST(
+ expires_at,
+ statement_timestamp() + interval '1 second' * $5
+ )
+ WHERE session_hash = $1
+ AND namespace = $2
+ AND name = $3
+ AND expires_at > statement_timestamp()
+ AND (claim_token IS NULL OR claim_expires_at <= statement_timestamp())
+ RETURNING uid,
+ resource_version AS "resourceVersion",
+ claim_token::text AS "claimToken"`,
+ [
+ sessionJtiHash(lookup.sessionJti),
+ requireField(lookup.namespace),
+ requireField(lookup.name),
+ claimToken,
+ MCP_SECRET_ROLLBACK_CLAIM_TTL_SECONDS,
+ ]
+ )
+ const row = result.rows[0] as
+ | { uid?: unknown; resourceVersion?: unknown; claimToken?: unknown }
+ | undefined
+ if (
+ typeof row?.uid !== 'string' ||
+ typeof row.resourceVersion !== 'string' ||
+ typeof row.claimToken !== 'string'
+ ) {
+ return null
+ }
+ return { uid: row.uid, resourceVersion: row.resourceVersion, claimToken: row.claimToken }
+}
+
+function claimBindingParams(binding: McpSecretRollbackPermitClaimBinding) {
+ return [
+ sessionJtiHash(binding.sessionJti),
+ requireField(binding.namespace),
+ requireField(binding.name),
+ requireField(binding.claimToken),
+ ]
+}
+
+export async function releaseMcpSecretRollbackPermitClaim(
+ binding: McpSecretRollbackPermitClaimBinding,
+ db: QueryClient = pool
+): Promise<void> {
+ await db.query(
+ `UPDATE mcp_secret_rollback_permits
+ SET claim_token = NULL,
+ claim_expires_at = NULL
+ WHERE session_hash = $1
+ AND namespace = $2
+ AND name = $3
+ AND claim_token = $4::uuid`,
+ claimBindingParams(binding)
+ )
+}
+
+export async function finalizeMcpSecretRollbackPermitClaim(
+ binding: McpSecretRollbackPermitClaimBinding,
+ db: QueryClient = pool
+): Promise<void> {
+ await db.query(
+ `DELETE FROM mcp_secret_rollback_permits
+ WHERE session_hash = $1
+ AND namespace = $2
+ AND name = $3
+ AND claim_token = $4::uuid`,
+ claimBindingParams(binding)
+ )
+}
diff --git a/control-api/src/services/registryClient.ts b/control-api/src/services/registryClient.ts
index 3f05745c4..0873a7231 100644
--- a/control-api/src/services/registryClient.ts
+++ b/control-api/src/services/registryClient.ts
@@ -162,6 +162,7 @@ async function mintTokenForGeneration(
signal: AbortSignal.timeout(READ_TIMEOUT_MS),
})
if (!res.ok) {
+ await discardResponseBody(res)
// Distinguish a rejected credential (rotate the secret) from an origin /
// tunnel outage (page on-call about reachability, do NOT rotate). A 5xx at
// the token endpoint is the registry origin or its tunnel being down, not a
diff --git a/control-api/src/utils/auth/mcpSecretDeleteProof.ts b/control-api/src/utils/auth/mcpSecretDeleteProof.ts
deleted file mode 100644
index 72e0e249e..000000000
--- a/control-api/src/utils/auth/mcpSecretDeleteProof.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import { createHash, timingSafeEqual } from 'node:crypto'
-
-export const MCP_SECRET_DELETE_PROOF_TTL_SECONDS = 120
-
-export type McpSecretDeleteProofInput = {
- name: string
- namespace: string
- uid: string
- resourceVersion: string
- sessionJti: string
-}
-
-export type McpSecretDeleteProofVerification = 'valid' | 'identity-mismatch' | null
-
-const COOKIE_NAME_PREFIX = 'mcp_secret_delete_proof_'
-const PROOF_VERSION = 'v1'
-const DIGEST_RE = /^[a-f0-9]{64}$/
-
-function isNonEmptyString(value: unknown): value is string {
- return typeof value === 'string' && value.trim().length > 0
-}
-
-function digestParts(...parts: string[]): string {
- const hash = createHash('sha256')
- for (const part of parts) {
- hash.update(String(Buffer.byteLength(part, 'utf8')), 'utf8')
- hash.update(':', 'utf8')
- hash.update(part, 'utf8')
- hash.update('|', 'utf8')
- }
- return hash.digest('hex')
-}
-
-function identityDigest(input: Pick<McpSecretDeleteProofInput, 'uid' | 'resourceVersion'>): string {
- return digestParts(PROOF_VERSION, input.uid, input.resourceVersion)
-}
-
-function proofDigest(
- input: McpSecretDeleteProofInput,
- expiresAt: number,
- boundIdentityDigest: string
-): string {
- return digestParts(
- PROOF_VERSION,
- input.sessionJti,
- input.name,
- input.namespace,
- boundIdentityDigest,
- String(expiresAt)
- )
-}
-
-function sameDigest(left: string, right: string): boolean {
- if (!DIGEST_RE.test(left) || !DIGEST_RE.test(right)) return false
- return timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'))
-}
-
-function hasCompleteInput(input: McpSecretDeleteProofInput): boolean {
- return (
- isNonEmptyString(input.name) &&
- isNonEmptyString(input.namespace) &&
- isNonEmptyString(input.uid) &&
- isNonEmptyString(input.resourceVersion) &&
- isNonEmptyString(input.sessionJti)
- )
-}
-
-export function mcpSecretDeleteProofCookieName(name: string): string {
- return `${COOKIE_NAME_PREFIX}${Buffer.from(name, 'utf8').toString('base64url')}`
-}
-
-export function createMcpSecretDeleteProof(input: McpSecretDeleteProofInput): string {
- if (!hasCompleteInput(input)) {
- throw new Error('A complete admin session and Secret identity are required for rollback proof')
- }
- const expiresAt = Math.floor(Date.now() / 1000) + MCP_SECRET_DELETE_PROOF_TTL_SECONDS
- const boundIdentityDigest = identityDigest(input)
- return [expiresAt, boundIdentityDigest, proofDigest(input, expiresAt, boundIdentityDigest)].join(
- '.'
- )
-}
-
-export function verifyMcpSecretDeleteProof(
- proof: string,
- input: McpSecretDeleteProofInput
-): McpSecretDeleteProofVerification {
- if (!proof || !hasCompleteInput(input)) return null
- const [encodedExpiry, boundIdentityDigest, suppliedProofDigest, ...rest] = proof.split('.')
- if (
- rest.length > 0 ||
- !/^\d+$/.test(encodedExpiry) ||
- !DIGEST_RE.test(boundIdentityDigest) ||
- !DIGEST_RE.test(suppliedProofDigest)
- ) {
- return null
- }
- const expiresAt = Number(encodedExpiry)
- if (!Number.isSafeInteger(expiresAt) || expiresAt <= Math.floor(Date.now() / 1000)) return null
- if (!sameDigest(boundIdentityDigest, identityDigest(input))) return 'identity-mismatch'
- return sameDigest(suppliedProofDigest, proofDigest(input, expiresAt, boundIdentityDigest))
- ? 'valid'
- : null
-}
diff --git a/control-api/test/db.migrationsOrder.test.ts b/control-api/test/db.migrationsOrder.test.ts
index 151aec60f..bf84c27a1 100644
--- a/control-api/test/db.migrationsOrder.test.ts
+++ b/control-api/test/db.migrationsOrder.test.ts
@@ -58,4 +58,41 @@ describe('CONTROL_API_MIGRATIONS ordering invariant', () => {
expect(duplicates).toEqual([])
expect(currentCollisions).toEqual([])
})
+
+ it('requires 0101_mcp_secret_rollback_permits to persist expiring rollback permits', async () => {
+ const { CONTROL_API_MIGRATIONS } = await import('../src/db.js')
+ const migration = CONTROL_API_MIGRATIONS.find(
+ candidate => candidate.version === '0101_mcp_secret_rollback_permits'
+ )
+
+ expect(migration).toBeDefined()
+ if (!migration) return
+
+ const query = vi.fn().mockResolvedValue({ rows: [], rowCount: 0 })
+ await migration.apply({ query } as never)
+
+ const sql = query.mock.calls.map(([statement]) => String(statement)).join('\n')
+ expect(sql).toMatch(/CREATE TABLE IF NOT EXISTS mcp_secret_rollback_permits/i)
+ for (const column of [
+ 'session_hash',
+ 'namespace',
+ 'name',
+ 'uid',
+ 'resource_version',
+ 'expires_at',
+ 'claim_token',
+ 'claim_expires_at',
+ ]) {
+ expect(sql).toMatch(new RegExp(`\\b${column}\\b`, 'i'))
+ }
+ expect(sql).toMatch(/session_hash\s+BYTEA/i)
+ expect(sql).toMatch(/octet_length\s*\(\s*session_hash\s*\)\s*=\s*32/i)
+ expect(sql).toMatch(/expires_at\s*<=\s*created_at\s*\+\s*INTERVAL\s*'120 seconds'/i)
+ expect(sql).toMatch(/claim_token\s+UUID/i)
+ expect(sql).toMatch(/claim_expires_at\s+TIMESTAMPTZ/i)
+ expect(sql).toMatch(/claim_token IS NULL[\s\S]+claim_expires_at IS NULL/i)
+ expect(sql).toMatch(
+ /CREATE INDEX IF NOT EXISTS[\s\S]+?ON mcp_secret_rollback_permits\s*\(\s*expires_at\s*\)/i
+ )
+ })
})
diff --git a/control-api/test/registryClient.test.ts b/control-api/test/registryClient.test.ts
index bf5c7c883..653996c58 100644
--- a/control-api/test/registryClient.test.ts
+++ b/control-api/test/registryClient.test.ts
@@ -6,6 +6,7 @@ import {
__resetTokenCacheForTests,
applyPublishScope,
createOrgGrant,
+ downloadBundle,
getCategories,
invalidateRegistryIdentityCaches,
mintToken,
@@ -147,6 +148,16 @@ describe('registryClient — mintToken cache behavior', () => {
expect(err.message).not.toContain('bad creds')
})
+ it('cancels a rejected token response body before throwing', async () => {
+ const response = new Response('bad creds', { status: 401 })
+ const cancel = vi.spyOn(response.body!, 'cancel')
+ vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response))
+
+ await mintToken(ENV_OVERRIDE).catch(() => undefined)
+
+ expect(cancel).toHaveBeenCalledOnce()
+ })
+
it('keeps the "credential rejected" label on 403 (forbidden creds)', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response('forbidden', { status: 403 }))
vi.stubGlobal('fetch', fetchMock)
@@ -171,6 +182,25 @@ describe('registryClient — mintToken cache behavior', () => {
})
})
+describe('registryClient — bundle response lifecycle', () => {
+ it('cancels a non-OK bundle response body before throwing', async () => {
+ const response = new Response('bundle unavailable', { status: 502 })
+ const cancel = vi.spyOn(response.body!, 'cancel')
+ vi.stubGlobal(
+ 'fetch',
+ vi
+ .fn()
+ .mockResolvedValueOnce(fakeTokenResponse('bundle-token'))
+ .mockResolvedValueOnce(response)
+ )
+ Object.assign(process.env, ENV_OVERRIDE)
+
+ await downloadBundle('@clerum/example', '1.0.0').catch(() => undefined)
+
+ expect(cancel).toHaveBeenCalledOnce()
+ })
+})
+
describe('registryClient — mintToken derived auth (no envOverride)', () => {
// Critical: no ENV_OVERRIDE here. That test-only path intentionally bypasses
// the mode-aware resolver.
diff --git a/control-api/test/routes.mcpSecrets.test.ts b/control-api/test/routes.mcpSecrets.test.ts
index 388ecd3e3..905e5619e 100644
--- a/control-api/test/routes.mcpSecrets.test.ts
+++ b/control-api/test/routes.mcpSecrets.test.ts
@@ -107,16 +107,90 @@ function k8sError(statusCode: number, message: string): Error & { statusCode: nu
return Object.assign(new Error(message), { statusCode })
}
-function makeApp(gateway: ReturnType<typeof createGateway>) {
+type RollbackPermit = {
+ sessionJti: string
+ name: string
+ namespace: string
+ uid: string
+ resourceVersion: string
+}
+
+function rollbackPermitKey(input: Pick<RollbackPermit, 'sessionJti' | 'name' | 'namespace'>) {
+ return `${input.sessionJti}:${input.namespace}:${input.name}`
+}
+
+function createRollbackPermitStore() {
+ const permits = new Map<
+ string,
+ {
+ uid: string
+ resourceVersion: string
+ expiresAt: number
+ claimToken?: string
+ claimExpiresAt?: number
+ }
+ >()
+ let claimCounter = 0
+ return {
+ issue: vi.fn(async (input: RollbackPermit) => {
+ permits.set(rollbackPermitKey(input), {
+ uid: input.uid,
+ resourceVersion: input.resourceVersion,
+ expiresAt: Date.now() + 120_000,
+ })
+ }),
+ claim: vi.fn(async (input: Pick<RollbackPermit, 'sessionJti' | 'name' | 'namespace'>) => {
+ const permit = permits.get(rollbackPermitKey(input))
+ if (!permit || permit.expiresAt <= Date.now()) return null
+ if (permit.claimToken && (permit.claimExpiresAt ?? 0) > Date.now()) return null
+ claimCounter += 1
+ permit.claimToken = `00000000-0000-4000-8000-${String(claimCounter).padStart(12, '0')}`
+ permit.claimExpiresAt = Math.min(permit.expiresAt, Date.now() + 15_000)
+ return {
+ uid: permit.uid,
+ resourceVersion: permit.resourceVersion,
+ claimToken: permit.claimToken,
+ }
+ }),
+ release: vi.fn(
+ async (
+ input: Pick<RollbackPermit, 'sessionJti' | 'name' | 'namespace'> & {
+ claimToken: string
+ }
+ ) => {
+ const permit = permits.get(rollbackPermitKey(input))
+ if (permit?.claimToken !== input.claimToken) return
+ permit.claimToken = undefined
+ permit.claimExpiresAt = undefined
+ }
+ ),
+ finalize: vi.fn(
+ async (
+ input: Pick<RollbackPermit, 'sessionJti' | 'name' | 'namespace'> & {
+ claimToken: string
+ }
+ ) => {
+ const key = rollbackPermitKey(input)
+ if (permits.get(key)?.claimToken === input.claimToken) permits.delete(key)
+ }
+ ),
+ }
+}
+
+function makeApp(
+ gateway: ReturnType<typeof createGateway>,
+ rollbackPermits = createRollbackPermitStore(),
+ sessionJti = TEST_ADMIN_SESSION_JTI
+) {
const app = express()
app.use(express.json())
app.use((req, _res, next) => {
;(req as express.Request & { adminAuth?: { jti: string } }).adminAuth = {
- jti: TEST_ADMIN_SESSION_JTI,
+ jti: sessionJti,
}
next()
})
- app.use(createAdminSecretsRouter(gateway as never))
+ app.use(createAdminSecretsRouter(gateway as never, rollbackPermits as never))
// Error handler so gateway errors return 500 instead of crashing
app.use(
(err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
@@ -138,13 +212,6 @@ function createAuthenticatedAgent(app: express.Express) {
return agent
}
-function mcpDeleteProofCookieName(value: unknown): string {
- const cookies = Array.isArray(value) ? value : typeof value === 'string' ? [value] : []
- const proofCookie = cookies.find(cookie => cookie.startsWith('mcp_secret_delete_proof_'))
- if (!proofCookie) throw new Error('Expected MCP Secret delete proof cookie')
- return proofCookie.slice(0, proofCookie.indexOf('='))
-}
-
describe('POST /admin/mcp-secrets', () => {
// ── Happy path ──────────────────────────────────────────────────────────
@@ -174,6 +241,66 @@ describe('POST /admin/mcp-secrets', () => {
expect(arg.stringData).toEqual({ DB_PASSWORD: 's3cret' })
})
+ it('keeps legacy rollback identity server-side without emitting a proof cookie', async () => {
+ const gateway = createGateway()
+ const rollbackPermits = createRollbackPermitStore()
+ const app = makeApp(gateway, rollbackPermits)
+ const agent = createAuthenticatedAgent(app)
+
+ const created = await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+
+ expect(rollbackPermits.issue).toHaveBeenCalledWith({
+ sessionJti: TEST_ADMIN_SESSION_JTI,
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-linear-credentials',
+ resourceVersion: '1',
+ })
+ expect(created.headers['set-cookie'] ?? []).not.toEqual(
+ expect.arrayContaining([expect.stringMatching(/^mcp_secret_delete_proof_/)])
+ )
+
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(200)
+
+ expect(rollbackPermits.claim).toHaveBeenCalledWith({
+ sessionJti: TEST_ADMIN_SESSION_JTI,
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ })
+ expect(rollbackPermits.finalize).toHaveBeenCalledWith({
+ sessionJti: TEST_ADMIN_SESSION_JTI,
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ claimToken: expect.stringMatching(/^[0-9a-f-]{36}$/),
+ })
+ })
+
+ it('fails closed without deleting the created resource when the permit cannot be persisted', async () => {
+ const gateway = createGateway()
+ const rollbackPermits = createRollbackPermitStore()
+ rollbackPermits.issue.mockRejectedValueOnce(new Error('postgres unavailable'))
+
+ const res = await request(makeApp(gateway, rollbackPermits))
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(503)
+
+ expect(res.body).toEqual({
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-linear-credentials',
+ resourceVersion: '1',
+ },
+ })
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
it('trims whitespace from name', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
@@ -901,16 +1028,15 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('supports an old UI POST plus bodyless DELETE with a signed create proof', async () => {
+ it('supports an old UI POST plus bodyless DELETE with a server-side permit', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
const agent = createAuthenticatedAgent(app)
- const created = await agent
+ await agent
.post('/admin/mcp-secrets')
.send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
.expect(201)
- const proofCookieName = mcpDeleteProofCookieName(created.headers['set-cookie'])
const warnSpy = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
try {
@@ -930,23 +1056,23 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(warnSpy).toHaveBeenCalledWith(
expect.objectContaining({
module: 'admin-secrets',
- event: 'mcp-secret-delete-legacy-signed-create-proof',
+ event: 'mcp-secret-delete-legacy-server-side-permit',
name: 'linear-credentials',
namespace: 'mcp-server',
- preconditionSource: 'signed-create-proof',
+ preconditionSource: 'server-side-permit',
}),
- 'MCP Secret delete used signed create proof'
+ 'MCP Secret delete used a server-side rollback permit'
)
expect(JSON.stringify(warnSpy.mock.calls)).not.toContain(TEST_CONTROL_UI_SESSION)
- expect(res.headers['set-cookie']).toEqual(
- expect.arrayContaining([expect.stringMatching(new RegExp(`^${proofCookieName}=`))])
+ expect(res.headers['set-cookie'] ?? []).not.toEqual(
+ expect.arrayContaining([expect.stringMatching(/^mcp_secret_delete_proof_/)])
)
} finally {
warnSpy.mockRestore()
}
})
- it('rejects a bodyless old UI DELETE with no signed create proof', async () => {
+ it('rejects a bodyless old UI DELETE with no server-side rollback permit', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
const agent = createAuthenticatedAgent(app)
@@ -957,6 +1083,41 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
+ it('fails closed when the server-side rollback permit lookup is unavailable', async () => {
+ const gateway = createGateway()
+ const rollbackPermits = createRollbackPermitStore()
+ rollbackPermits.claim.mockRejectedValueOnce(new Error('postgres unavailable'))
+ const agent = createAuthenticatedAgent(makeApp(gateway, rollbackPermits))
+
+ const res = await agent.delete('/admin/mcp-secrets/linear-credentials').expect(503)
+
+ expect(res.body).toEqual({
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ })
+ expect(gateway.getSecret).not.toHaveBeenCalled()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('releases a claim after a transient reference-check failure so the old UI can retry', async () => {
+ const gateway = createGateway()
+ const rollbackPermits = createRollbackPermitStore()
+ const agent = createAuthenticatedAgent(makeApp(gateway, rollbackPermits))
+
+ await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ gateway.listResource.mockRejectedValueOnce(new Error('reference graph unavailable'))
+
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(503)
+ expect(rollbackPermits.release).toHaveBeenCalledOnce()
+
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(200)
+ expect(rollbackPermits.claim).toHaveBeenCalledTimes(2)
+ expect(rollbackPermits.finalize).toHaveBeenCalledOnce()
+ })
+
it('rejects a stale supplied identity before delete', async () => {
const gateway = createGateway()
gateway.getSecret.mockResolvedValueOnce({
@@ -980,7 +1141,7 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('legacy signed proof refuses to delete a Secret referenced by a live connector', async () => {
+ it('server-side rollback permit refuses to delete a Secret referenced by a live connector', async () => {
const gateway = createGateway()
gateway.listResource.mockResolvedValueOnce([
{
@@ -1001,7 +1162,7 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('legacy signed proof refuses to delete a WorkflowRecipe-owned Secret', async () => {
+ it('server-side rollback permit refuses to delete a WorkflowRecipe-owned Secret', async () => {
const gateway = createGateway()
gateway.getSecret.mockResolvedValueOnce({
metadata: {
@@ -1095,25 +1256,26 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('rejects a tampered signed create proof', async () => {
+ it('rejects a bodyless rollback from a different admin session', async () => {
const gateway = createGateway()
- const app = makeApp(gateway)
- const agent = createAuthenticatedAgent(app)
+ const rollbackPermits = createRollbackPermitStore()
+ const agent = createAuthenticatedAgent(makeApp(gateway, rollbackPermits))
- const created = await agent
+ await agent
.post('/admin/mcp-secrets')
.send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
.expect(201)
- const proofCookieName = mcpDeleteProofCookieName(created.headers['set-cookie'])
- agent.jar.setCookie(`${proofCookieName}=tampered; Path=/; HttpOnly`, '127.0.0.1', '/')
+ const otherSessionAgent = createAuthenticatedAgent(
+ makeApp(gateway, rollbackPermits, 'other-admin-session-jti')
+ )
- await agent.delete('/admin/mcp-secrets/linear-credentials').expect(428)
+ await otherSessionAgent.delete('/admin/mcp-secrets/linear-credentials').expect(428)
- expect(gateway.getSecret).toHaveBeenCalledOnce()
+ expect(gateway.getSecret).not.toHaveBeenCalled()
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('rejects an expired signed create proof', async () => {
+ it('rejects an expired server-side rollback permit', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
const agent = createAuthenticatedAgent(app)
@@ -1133,7 +1295,7 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('does not delete a replacement that wins before the legacy proof read', async () => {
+ it('does not delete a replacement that wins before server-side permit consumption', async () => {
const gateway = new MockGateway('mcp-server')
const name = 'linear-credentials'
const app = makeApp(gateway as never)
@@ -1161,7 +1323,7 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
})
})
- it('does not delete a replacement that wins after the legacy proof read', async () => {
+ it('does not delete a replacement that wins after server-side permit consumption', async () => {
const gateway = new MockGateway('mcp-server')
const name = 'linear-credentials'
const app = makeApp(gateway as never)
diff --git a/control-api/test/services.mcpSecretRollbackPermit.realPostgres.integration.test.ts b/control-api/test/services.mcpSecretRollbackPermit.realPostgres.integration.test.ts
new file mode 100644
index 000000000..a485f6d60
--- /dev/null
+++ b/control-api/test/services.mcpSecretRollbackPermit.realPostgres.integration.test.ts
@@ -0,0 +1,221 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { randomBytes } from 'node:crypto'
+import { Pool } from 'pg'
+import { initDb } from '../src/db.js'
+import {
+ claimMcpSecretRollbackPermit,
+ finalizeMcpSecretRollbackPermitClaim,
+ issueMcpSecretRollbackPermit,
+ releaseMcpSecretRollbackPermitClaim,
+} from '../src/services/mcpSecretRollbackPermitService.js'
+
+const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL
+const describeRealPostgres = adminUrl ? describe : describe.skip
+
+function databaseUrl(baseUrl: string, database: string): string {
+ const url = new URL(baseUrl)
+ url.pathname = `/${database}`
+ return url.toString()
+}
+
+function quoteIdent(value: string): string {
+ return `"${value.replace(/"/g, '""')}"`
+}
+
+describeRealPostgres('MCP Secret rollback permits on real PostgreSQL', () => {
+ const database = `mcp_rollback_${randomBytes(6).toString('hex')}`
+ const connectionString = databaseUrl(
+ adminUrl ?? 'postgresql://[email protected]/postgres',
+ database
+ )
+ const basePermit = {
+ sessionJti: `session-${randomBytes(12).toString('hex')}`,
+ namespace: 'mcp-server',
+ name: `credential-${randomBytes(5).toString('hex')}`,
+ uid: `uid-${randomBytes(8).toString('hex')}`,
+ resourceVersion: '17',
+ }
+ let adminPool: Pool
+ let pool: Pool
+
+ beforeAll(async () => {
+ adminPool = new Pool({ connectionString: adminUrl })
+ await adminPool.query(`CREATE DATABASE ${quoteIdent(database)}`)
+ pool = new Pool({ connectionString })
+ await initDb({ connect: () => pool.connect() })
+ }, 60_000)
+
+ afterAll(async () => {
+ if (pool) {
+ // A concurrent consume test opens several pg clients. pg@8 may emit a
+ // late idle-client error while their sockets finish closing, so retain a
+ // pool-level listener through teardown and wait for the backend rows to
+ // disappear before using the administrative fallback below.
+ pool.on('error', () => {})
+ await pool.end()
+ }
+ if (!adminPool) return
+ let activeConnections = 0
+ for (let attempt = 0; attempt < 50; attempt += 1) {
+ const active = await adminPool.query<{ count: string }>(
+ `SELECT COUNT(*)::text AS count
+ FROM pg_stat_activity
+ WHERE datname = $1 AND pid <> pg_backend_pid()`,
+ [database]
+ )
+ activeConnections = Number(active.rows[0]?.count ?? 0)
+ if (activeConnections === 0) break
+ await new Promise<void>(resolve => setImmediate(resolve))
+ }
+ if (activeConnections > 0) {
+ await adminPool.query(
+ `SELECT pg_terminate_backend(pid)
+ FROM pg_stat_activity
+ WHERE datname = $1 AND pid <> pg_backend_pid()`,
+ [database]
+ )
+ }
+ await adminPool.query(`DROP DATABASE IF EXISTS ${quoteIdent(database)}`)
+ await adminPool.end()
+ })
+
+ it('grants the runtime role the exact DML needed to issue and consume a permit', async () => {
+ const client = await pool.connect()
+ const permit = { ...basePermit, name: `${basePermit.name}-runtime` }
+ try {
+ await client.query('BEGIN')
+ await client.query('SET LOCAL ROLE control_api_runtime')
+ await issueMcpSecretRollbackPermit(permit, client)
+ await expect(
+ claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ },
+ client
+ )
+ ).resolves.toMatchObject({ uid: permit.uid, resourceVersion: permit.resourceVersion })
+ await client.query('ROLLBACK')
+ } finally {
+ client.release()
+ }
+ })
+
+ it('allows exactly one winner across concurrent PostgreSQL sessions', async () => {
+ const permit = { ...basePermit, name: `${basePermit.name}-concurrent` }
+ await issueMcpSecretRollbackPermit(permit, pool)
+
+ const results = await Promise.all(
+ Array.from({ length: 16 }, () =>
+ claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ },
+ pool
+ )
+ )
+ )
+
+ const winners = results.filter(result => result !== null)
+ expect(winners).toHaveLength(1)
+ expect(winners[0]).toMatchObject({ uid: permit.uid, resourceVersion: permit.resourceVersion })
+
+ await releaseMcpSecretRollbackPermitClaim(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ claimToken: winners[0]!.claimToken,
+ },
+ pool
+ )
+ const retry = await claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ },
+ pool
+ )
+ expect(retry).not.toBeNull()
+ await finalizeMcpSecretRollbackPermitClaim(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ claimToken: retry!.claimToken,
+ },
+ pool
+ )
+ })
+
+ it('binds the permit to its session and rejects it at the PostgreSQL expiry boundary', async () => {
+ const permit = { ...basePermit, name: `${basePermit.name}-expiry` }
+ await issueMcpSecretRollbackPermit(permit, pool)
+
+ await expect(
+ claimMcpSecretRollbackPermit(
+ {
+ sessionJti: 'different-admin-session',
+ namespace: permit.namespace,
+ name: permit.name,
+ },
+ pool
+ )
+ ).resolves.toBeNull()
+
+ const ttl = await pool.query<{ ttlSeconds: string }>(
+ `SELECT EXTRACT(EPOCH FROM (expires_at - created_at))::text AS "ttlSeconds"
+ FROM mcp_secret_rollback_permits
+ WHERE namespace = $1 AND name = $2`,
+ [permit.namespace, permit.name]
+ )
+ expect(Number(ttl.rows[0]?.ttlSeconds)).toBe(120)
+
+ await pool.query(
+ `UPDATE mcp_secret_rollback_permits
+ SET created_at = statement_timestamp() - interval '121 seconds',
+ expires_at = statement_timestamp() - interval '1 second'
+ WHERE namespace = $1 AND name = $2`,
+ [permit.namespace, permit.name]
+ )
+
+ await expect(
+ claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ },
+ pool
+ )
+ ).resolves.toBeNull()
+ })
+
+ it('allows another replica to reclaim a permit after a crashed claim lease expires', async () => {
+ const permit = { ...basePermit, name: `${basePermit.name}-crash-recovery` }
+ await issueMcpSecretRollbackPermit(permit, pool)
+ const first = await claimMcpSecretRollbackPermit(
+ { sessionJti: permit.sessionJti, namespace: permit.namespace, name: permit.name },
+ pool
+ )
+ expect(first).not.toBeNull()
+
+ await pool.query(
+ `UPDATE mcp_secret_rollback_permits
+ SET claim_expires_at = statement_timestamp() - interval '1 second'
+ WHERE namespace = $1 AND name = $2`,
+ [permit.namespace, permit.name]
+ )
+
+ const reclaimed = await claimMcpSecretRollbackPermit(
+ { sessionJti: permit.sessionJti, namespace: permit.namespace, name: permit.name },
+ pool
+ )
+ expect(reclaimed).not.toBeNull()
+ expect(reclaimed!.claimToken).not.toBe(first!.claimToken)
+ })
+})
diff --git a/control-api/test/services.mcpSecretRollbackPermit.test.ts b/control-api/test/services.mcpSecretRollbackPermit.test.ts
new file mode 100644
index 000000000..406d8f4aa
--- /dev/null
+++ b/control-api/test/services.mcpSecretRollbackPermit.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ MCP_SECRET_ROLLBACK_CLAIM_TTL_SECONDS,
+ MCP_SECRET_ROLLBACK_PERMIT_TTL_SECONDS,
+ claimMcpSecretRollbackPermit,
+ finalizeMcpSecretRollbackPermitClaim,
+ issueMcpSecretRollbackPermit,
+ releaseMcpSecretRollbackPermitClaim,
+} from '../src/services/mcpSecretRollbackPermitService.js'
+
+const permit = {
+ sessionJti: 'admin-session-jti-raw',
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-linear',
+ resourceVersion: '7',
+}
+
+describe('mcpSecretRollbackPermitService', () => {
+ it('rejects incomplete permits before querying PostgreSQL', async () => {
+ const query = vi.fn()
+
+ await expect(
+ issueMcpSecretRollbackPermit({ ...permit, sessionJti: '' }, { query } as never)
+ ).rejects.toThrow('invalid_mcp_secret_rollback_permit')
+ expect(query).not.toHaveBeenCalled()
+ })
+
+ it('stores only a hash of the admin session and a bounded resource identity', async () => {
+ const query = vi
+ .fn()
+ .mockResolvedValueOnce({ rows: [], rowCount: 0 })
+ .mockResolvedValueOnce({ rows: [], rowCount: 1 })
+
+ await issueMcpSecretRollbackPermit(permit, { query } as never)
+
+ const insert = query.mock.calls.find(([sql]) =>
+ String(sql).includes('INSERT INTO mcp_secret_rollback_permits')
+ )
+ expect(insert).toBeDefined()
+ expect(insert?.[1]).toEqual([
+ expect.any(Buffer),
+ 'mcp-server',
+ 'linear-credentials',
+ 'uid-linear',
+ '7',
+ MCP_SECRET_ROLLBACK_PERMIT_TTL_SECONDS,
+ ])
+ expect((insert?.[1] as unknown[])[0]).toHaveLength(32)
+ const cleanupSql = String(query.mock.calls[0]?.[0])
+ expect(cleanupSql).toContain('LIMIT 100')
+ expect(JSON.stringify(query.mock.calls)).not.toContain(permit.sessionJti)
+ })
+
+ it('atomically claims an unexpired permit for the same session and resource name', async () => {
+ const query = vi.fn().mockResolvedValueOnce({
+ rows: [
+ {
+ uid: 'uid-linear',
+ resourceVersion: '7',
+ claimToken: '11111111-1111-4111-8111-111111111111',
+ },
+ ],
+ rowCount: 1,
+ })
+
+ const result = await claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ name: permit.name,
+ namespace: permit.namespace,
+ },
+ { query } as never
+ )
+
+ expect(result).toEqual({
+ uid: 'uid-linear',
+ resourceVersion: '7',
+ claimToken: '11111111-1111-4111-8111-111111111111',
+ })
+ const sql = String(query.mock.calls[0]?.[0])
+ expect(sql).toContain('UPDATE mcp_secret_rollback_permits')
+ expect(sql).toContain('expires_at > statement_timestamp()')
+ expect(sql).toContain('claim_expires_at <= statement_timestamp()')
+ expect(sql).toContain('RETURNING uid')
+ expect(query.mock.calls[0]?.[1]).toEqual([
+ expect.any(Buffer),
+ 'mcp-server',
+ 'linear-credentials',
+ expect.stringMatching(/^[0-9a-f-]{36}$/),
+ MCP_SECRET_ROLLBACK_CLAIM_TTL_SECONDS,
+ ])
+ expect(query).toHaveBeenCalledOnce()
+ expect(JSON.stringify(query.mock.calls)).not.toContain(permit.sessionJti)
+ })
+
+ it('returns null when no active permit exists', async () => {
+ const query = vi.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 })
+
+ await expect(
+ claimMcpSecretRollbackPermit(
+ {
+ sessionJti: permit.sessionJti,
+ name: permit.name,
+ namespace: permit.namespace,
+ },
+ { query } as never
+ )
+ ).resolves.toBeNull()
+ })
+
+ it('releases only the matching claim so a transient failure can retry', async () => {
+ const query = vi.fn().mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ await releaseMcpSecretRollbackPermitClaim(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ claimToken: '11111111-1111-4111-8111-111111111111',
+ },
+ { query } as never
+ )
+ const sql = String(query.mock.calls[0]?.[0])
+ expect(sql).toContain('SET claim_token = NULL')
+ expect(sql).toContain('claim_token = $4')
+ })
+
+ it('finalizes only the matching claim after a terminal result', async () => {
+ const query = vi.fn().mockResolvedValueOnce({ rows: [], rowCount: 1 })
+ await finalizeMcpSecretRollbackPermitClaim(
+ {
+ sessionJti: permit.sessionJti,
+ namespace: permit.namespace,
+ name: permit.name,
+ claimToken: '11111111-1111-4111-8111-111111111111',
+ },
+ { query } as never
+ )
+ const sql = String(query.mock.calls[0]?.[0])
+ expect(sql).toContain('DELETE FROM mcp_secret_rollback_permits')
+ expect(sql).toContain('claim_token = $4')
+ })
+})
diff --git a/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts b/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts
deleted file mode 100644
index 08febd754..000000000
--- a/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import {
- MCP_SECRET_DELETE_PROOF_TTL_SECONDS,
- createMcpSecretDeleteProof,
- mcpSecretDeleteProofCookieName,
- verifyMcpSecretDeleteProof,
-} from '../src/utils/auth/mcpSecretDeleteProof.js'
-
-const claims = {
- name: 'linear-credentials',
- namespace: 'mcp-server',
- uid: 'uid-linear-credentials',
- resourceVersion: '1',
- sessionJti: 'test-admin-session-jti',
-}
-
-describe('MCP Secret delete proof', () => {
- it('binds exactly the Secret identity to the admin session', () => {
- const now = 1_700_000_000_000
- const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(now)
-
- try {
- const proof = createMcpSecretDeleteProof(claims)
-
- expect(verifyMcpSecretDeleteProof(proof, claims)).toBe('valid')
- expect(verifyMcpSecretDeleteProof(proof, { ...claims, uid: 'uid-replacement' })).toBe(
- 'identity-mismatch'
- )
- expect(
- verifyMcpSecretDeleteProof(proof, { ...claims, sessionJti: 'other-session-jti' })
- ).toBeNull()
- } finally {
- nowSpy.mockRestore()
- }
- })
-
- it('rejects a proof when its signature or expiry is invalid', () => {
- const now = 1_700_000_000_000
- const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(now)
-
- try {
- const proof = createMcpSecretDeleteProof(claims)
- const tampered = proof.split('.')
- tampered[2] = `${tampered[2]}x`
-
- expect(verifyMcpSecretDeleteProof(tampered.join('.'), claims)).toBeNull()
-
- nowSpy.mockReturnValue(now + (MCP_SECRET_DELETE_PROOF_TTL_SECONDS + 1) * 1000)
- expect(verifyMcpSecretDeleteProof(proof, claims)).toBeNull()
- } finally {
- nowSpy.mockRestore()
- }
- })
-
- it('uses a deterministic, HTTP-cookie-safe name derived from the Secret name', () => {
- const name = mcpSecretDeleteProofCookieName(claims.name)
-
- expect(name).toMatch(/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/)
- expect(name).not.toBe(mcpSecretDeleteProofCookieName('other-credentials'))
- })
-})
diff --git a/control-ui/components/CreateMcpServerForm/index.tsx b/control-ui/components/CreateMcpServerForm/index.tsx
index 5f1c244da..14b65e8a0 100644
--- a/control-ui/components/CreateMcpServerForm/index.tsx
+++ b/control-ui/components/CreateMcpServerForm/index.tsx
@@ -17,6 +17,7 @@ import {
getContextUsers,
getContexts,
getHosts,
+ getMcpSecretRollbackRepairIdentity,
listOrgImages,
updateContext,
} from '@/lib/api'
@@ -581,13 +582,27 @@ export function CreateMcpServerForm({
onCreated()
}, 600)
} catch (submitError) {
- // Rollback only a Secret this submission created. Legacy create APIs did
- // not return an identity, so this is the one bounded bodyless-delete
- // compatibility path; existing Secret deletes remain identity-bound.
+ // Roll back only a Secret this submission created. A successful legacy
+ // create may use the bounded bodyless-delete compatibility path. A
+ // rejected create is eligible only when its exact repair response gives
+ // us a complete CAS identity; incomplete repair data never falls back to
+ // a bodyless delete.
let cleanupError: unknown
- if (createdSecretName) {
+ let cleanupSecretName = createdSecretName
+ let cleanupSecretIdentity = createdSecretIdentity
+ if (!cleanupSecretName) {
+ const repairIdentity = getMcpSecretRollbackRepairIdentity(submitError, envSecretName.trim())
+ if (repairIdentity) {
+ cleanupSecretName = repairIdentity.name
+ cleanupSecretIdentity = {
+ uid: repairIdentity.uid,
+ resourceVersion: repairIdentity.resourceVersion,
+ }
+ }
+ }
+ if (cleanupSecretName) {
try {
- await deleteMcpSecret(createdSecretName, createdSecretIdentity)
+ await deleteMcpSecret(cleanupSecretName, cleanupSecretIdentity)
} catch (error) {
cleanupError = error
}
diff --git a/control-ui/components/__tests__/CreateMcpServerForm.test.tsx b/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
index ccff30124..f4d21a497 100644
--- a/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
+++ b/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
@@ -6,13 +6,15 @@ import { CreateMcpServerForm } from '../CreateMcpServerForm'
import { ToastProvider } from '../Toast'
// vi.mock is hoisted before imports; factory runs lazily so references to `api` are safe.
-vi.mock('../../lib/api', async () => {
+vi.mock('../../lib/api', async importOriginal => {
+ const actual = await importOriginal<typeof import('../../lib/api')>()
const { buildContextList, buildContextResource } =
await import('../../test/fixtures/contextResource')
const context1 = buildContextResource({
metadata: { name: 'context1', resourceVersion: 'rv-context1' },
})
return {
+ ...actual,
createMcpServer: vi.fn().mockResolvedValue({ metadata: { name: 'test-server' } }),
createMcpSecret: vi.fn().mockResolvedValue({
name: 'test-credentials',
@@ -75,6 +77,21 @@ function chooseNewSecret() {
fireEvent.click(screen.getByRole('radio', { name: /Create Kubernetes Secret/ }))
}
+function mcpSecretRollbackRepairError(created: Record<string, unknown>) {
+ return Object.assign(
+ new Error('503 Service Unavailable - mcp_secret_rollback_permit_unavailable'),
+ {
+ status: 503,
+ code: 'mcp_secret_rollback_permit_unavailable',
+ body: {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created,
+ },
+ }
+ )
+}
+
// ─────────────────────────────────────────────────────────────────────────────
// Rendering
// ─────────────────────────────────────────────────────────────────────────────
@@ -539,6 +556,73 @@ describe('CreateMcpServerForm — envSecret guardrails', () => {
})
})
+ it('rolls back a repaired Secret with CAS when createMcpSecret rejects', async () => {
+ ;(api.createMcpSecret as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+ mcpSecretRollbackRepairError({
+ name: 'requested-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-requested-credentials',
+ resourceVersion: '17',
+ })
+ )
+
+ render(<CreateMcpServerForm onCancel={vi.fn()} onCreated={vi.fn()} />)
+ await fillRequiredBasics()
+ enableEnvSecret('requested-credentials')
+ fireEvent.click(screen.getByRole('button', { name: 'Add Key Mapping' }))
+ fireEvent.change(screen.getByPlaceholderText('api-key'), {
+ target: { value: 'api-key' },
+ })
+ fireEvent.change(screen.getByPlaceholderText('BRAVE_API_KEY'), {
+ target: { value: 'BRAVE_API_KEY' },
+ })
+ fireEvent.change(screen.getByPlaceholderText('sk-...'), {
+ target: { value: 'sk-test-abc' },
+ })
+
+ fireEvent.click(screen.getByRole('button', { name: 'Create connector' }))
+
+ await waitFor(() => {
+ expect(api.deleteMcpSecret).toHaveBeenCalledWith('requested-credentials', {
+ uid: 'uid-requested-credentials',
+ resourceVersion: '17',
+ })
+ })
+ expect(api.createMcpServer).not.toHaveBeenCalled()
+ })
+
+ it('does not use a bodyless rollback when a repair response has incomplete identity', async () => {
+ ;(api.createMcpSecret as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+ mcpSecretRollbackRepairError({
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ })
+ )
+
+ render(<CreateMcpServerForm onCancel={vi.fn()} onCreated={vi.fn()} />)
+ await fillRequiredBasics()
+ enableEnvSecret('requested-credentials')
+ fireEvent.click(screen.getByRole('button', { name: 'Add Key Mapping' }))
+ fireEvent.change(screen.getByPlaceholderText('api-key'), {
+ target: { value: 'api-key' },
+ })
+ fireEvent.change(screen.getByPlaceholderText('BRAVE_API_KEY'), {
+ target: { value: 'BRAVE_API_KEY' },
+ })
+ fireEvent.change(screen.getByPlaceholderText('sk-...'), {
+ target: { value: 'sk-test-abc' },
+ })
+
+ fireEvent.click(screen.getByRole('button', { name: 'Create connector' }))
+
+ await waitFor(() => {
+ expect(screen.getByText(/mcp_secret_rollback_permit_unavailable/)).toBeInTheDocument()
+ })
+ expect(api.deleteMcpSecret).not.toHaveBeenCalled()
+ expect(api.createMcpServer).not.toHaveBeenCalled()
+ })
+
it('uses the legacy bodyless rollback when the create API omits identity fields', async () => {
;(api.createMcpSecret as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
name: 'legacy-credentials',
diff --git a/control-ui/lib/__tests__/mcpIdentity.test.ts b/control-ui/lib/__tests__/mcpIdentity.test.ts
index e37d7de4f..02a191a8e 100644
--- a/control-ui/lib/__tests__/mcpIdentity.test.ts
+++ b/control-ui/lib/__tests__/mcpIdentity.test.ts
@@ -1,5 +1,10 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { createMcpSecret, deleteMcpSecret, formatApiError } from '../api'
+import {
+ createMcpSecret,
+ deleteMcpSecret,
+ formatApiError,
+ getMcpSecretRollbackRepairIdentity,
+} from '../api'
function jsonResponse(body: unknown, status = 200, statusText = 'OK'): Response {
return {
@@ -98,6 +103,117 @@ describe('MCP identity compatibility', () => {
})
})
+describe('MCP Secret rollback repair identity', () => {
+ it('extracts a CAS identity from the exact failed POST repair response', async () => {
+ fetchMock.mockResolvedValueOnce(
+ jsonResponse(
+ {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ resourceVersion: '17',
+ },
+ },
+ 503,
+ 'Service Unavailable'
+ )
+ )
+
+ const failure = await createMcpSecret('repaired-credentials', { fixture: 'fixture' }).catch(
+ error => error
+ )
+
+ expect(getMcpSecretRollbackRepairIdentity(failure, 'repaired-credentials')).toEqual({
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ resourceVersion: '17',
+ })
+ })
+
+ it.each([
+ [
+ 'has a different error code',
+ 503,
+ {
+ error: 'mcp_secret_rollback_permit_expired',
+ outcome: 'repair_required',
+ created: {
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ resourceVersion: '17',
+ },
+ },
+ ],
+ [
+ 'is not a 503 response',
+ 409,
+ {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ resourceVersion: '17',
+ },
+ },
+ ],
+ [
+ 'does not require repair',
+ 503,
+ {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'retry_later',
+ created: {
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ resourceVersion: '17',
+ },
+ },
+ ],
+ [
+ 'omits a CAS field from the created Secret',
+ 503,
+ {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
+ name: 'repaired-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-repaired-credentials',
+ },
+ },
+ ],
+ [
+ 'names a different Secret',
+ 503,
+ {
+ error: 'mcp_secret_rollback_permit_unavailable',
+ outcome: 'repair_required',
+ created: {
+ name: 'other-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-other-credentials',
+ resourceVersion: '17',
+ },
+ },
+ ],
+ ])('does not extract an identity when the response %s', (_, status, body) => {
+ const error = formatApiError(
+ { status, statusText: status === 503 ? 'Service Unavailable' : 'Conflict' } as Response,
+ JSON.stringify(body)
+ )
+
+ expect(getMcpSecretRollbackRepairIdentity(error, 'repaired-credentials')).toBeNull()
+ })
+})
+
describe('MCP delete API errors', () => {
it.each([
[
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index 34873174c..b12408a85 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -1499,6 +1499,11 @@ export type McpSecretCreateResult =
resourceVersion?: undefined
}
+export type McpSecretRollbackRepairIdentity = {
+ name: string
+ namespace: string
+} & SecretIdentity
+
export async function createMcpSecret(
name: string,
data: Record<string, string>
@@ -1660,6 +1665,54 @@ function apiErrorBody(err: unknown): Record<string, unknown> | null {
return body && typeof body === 'object' ? (body as Record<string, unknown>) : null
}
+function readMcpSecretRollbackRepairIdentity(raw: unknown): McpSecretRollbackRepairIdentity | null {
+ if (!raw || typeof raw !== 'object') return null
+ const created = raw as Record<string, unknown>
+ if (
+ typeof created.name !== 'string' ||
+ !created.name.trim() ||
+ typeof created.namespace !== 'string' ||
+ !created.namespace.trim() ||
+ typeof created.uid !== 'string' ||
+ !created.uid.trim() ||
+ typeof created.resourceVersion !== 'string' ||
+ !created.resourceVersion.trim()
+ ) {
+ return null
+ }
+ return {
+ name: created.name,
+ namespace: created.namespace,
+ uid: created.uid,
+ resourceVersion: created.resourceVersion,
+ }
+}
+
+/**
+ * Returns the CAS identity only from the exact MCP Secret repair response.
+ * A rejected create can still have persisted the Secret when the server could
+ * not record its rollback permit; partial or unrelated errors must not unlock
+ * the legacy bodyless-delete compatibility path.
+ */
+export function getMcpSecretRollbackRepairIdentity(
+ err: unknown,
+ expectedName: string
+): McpSecretRollbackRepairIdentity | null {
+ if (!(err instanceof Error) || (err as Error & { status?: unknown }).status !== 503) {
+ return null
+ }
+ const body = apiErrorBody(err)
+ if (
+ !body ||
+ body.error !== 'mcp_secret_rollback_permit_unavailable' ||
+ body.outcome !== 'repair_required'
+ ) {
+ return null
+ }
+ const identity = readMcpSecretRollbackRepairIdentity(body.created)
+ return identity?.name === expectedName ? identity : null
+}
+
function coerceUnpricedModels(raw: unknown): UnpricedModel[] {
if (!Array.isArray(raw)) return []
return raw
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 886a7d583..ecd63b31d 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.460",
+ "version": "0.1.461",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.460",
+ "version": "0.1.461",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/llm-providers": "file:../packages/llm-providers",
diff --git a/control-ui/package.json b/control-ui/package.json
index 94a5d9dd2..e949ea249 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.460",
+ "version": "0.1.461",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/deploy/scripts/control-api-runtime-access-profiles.tsv b/deploy/scripts/control-api-runtime-access-profiles.tsv
index 23bbad444..6a1d61f75 100644
--- a/deploy/scripts/control-api-runtime-access-profiles.tsv
+++ b/deploy/scripts/control-api-runtime-access-profiles.tsv
@@ -34,6 +34,7 @@ llm_allowed_models_audit append
llm_catalog_sync_runs append
llm_model_prices legacy_dml
member_registration_credentials upsert
+mcp_secret_rollback_permits legacy_dml
notification_deliveries legacy_dml
oauth_grants legacy_dml
plugin_workload_sdk_credential_ticket_jtis legacy_dml
diff --git a/docs/how-to/codeql-js-cleartext-storage-kubernetes-secret-proof.md b/docs/how-to/codeql-js-cleartext-storage-kubernetes-secret-proof.md
deleted file mode 100644
index 4fd37ee2f..000000000
--- a/docs/how-to/codeql-js-cleartext-storage-kubernetes-secret-proof.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# CodeQL clear-text storage — Kubernetes Secret rollback proof disposition
-
-This document records the audited disposition for CodeQL alert
-[#1198](https://github.com/evenfire-ai/evenfire/security/code-scanning/1198),
-reported by `js/clear-text-storage-of-sensitive-data` in PR #252.
-
-## Disposition
-
-**False positive.** In this flow, “Secret” is the Kubernetes resource kind; it
-does not describe secret values stored in the browser. The finding's two
-reported sources are the `createMcpSecretDeleteProof` function name and the
-public `MCP_SECRET_DELETE_PROOF_TTL_SECONDS = 120` constant.
-
-The cookie value contains only:
-
-1. an expiry timestamp;
-2. a SHA-256 binding of the resource UID and resourceVersion; and
-3. a SHA-256 binding of the authenticated session JTI, resource name,
- namespace, identity digest, and expiry.
-
-It never contains Kubernetes `data` or `stringData`, credentials, the admin
-JWT, the session JTI, UID, or resourceVersion in clear text.
-
-## Security controls
-
-- The route is behind verified Control UI admin authentication.
-- The proof is bound to the creating admin session, resource name, namespace,
- UID, and resourceVersion.
-- The cookie is `HttpOnly`, `SameSite=Lax`, secure in production or HTTPS,
- scoped to `/`, and expires after 120 seconds.
-- The legacy bodyless rollback re-reads the live resource and verifies the
- proof against its current identity.
-- Deletion still uses Kubernetes UID/resourceVersion preconditions and retains
- the existing reference and ownership guards.
-- Current clients continue to send explicit UID/resourceVersion preconditions;
- the proof exists only for a short rolling-deployment compatibility window
- with an older cached UI.
-
-## Why production code is unchanged
-
-The proof is already one-way protected and contains no confidential payload.
-Moving the binding to PostgreSQL would add a migration, cleanup lifecycle, and
-runtime dependency to solve an analyzer naming ambiguity without improving the
-stated confidentiality boundary. Removing the compatibility path would break
-the supported old-UI/new-API deployment sequence.
-
-The CodeQL query remains enabled globally. Only alert #1198 is eligible for
-false-positive dismissal.
-
-## Re-open triggers
-
-Re-open and redesign this flow if any of the following changes:
-
-- the proof input begins to include Secret `data`, `stringData`, credentials,
- or other confidential values;
-- the cookie begins to carry the session JTI, UID, resourceVersion, or other
- stable identifiers in clear text;
-- the 120-second TTL or cookie security flags are weakened;
-- admin-session binding, live identity verification, reference checks, or
- Kubernetes delete preconditions are removed; or
-- CodeQL gains modeling that distinguishes the Kubernetes resource-kind name
- from confidential values and still reports a real clear-text flow.
-
-## Dismissal comment
-
-```text
-False positive documented in docs/how-to/codeql-js-cleartext-storage-kubernetes-secret-proof.md (alert #1198). “Secret” is the Kubernetes resource kind; the cookie contains only a 120-second expiry and SHA-256 bindings, never Secret data/stringData, credentials, JWT/JTI, UID, or resourceVersion in clear text. The route remains admin-authenticated and delete remains fenced by live UID/resourceVersion preconditions. The query stays enabled globally.
-```
diff --git a/docs/how-to/control-api-mcp-secret-rollback-permits.md b/docs/how-to/control-api-mcp-secret-rollback-permits.md
new file mode 100644
index 000000000..109d157c7
--- /dev/null
+++ b/docs/how-to/control-api-mcp-secret-rollback-permits.md
@@ -0,0 +1,65 @@
+# Control API MCP Secret rollback permits
+
+This runbook covers the short-lived PostgreSQL permits used only by the legacy
+bodyless rollback path of `POST /admin/mcp-secrets` followed by
+`DELETE /admin/mcp-secrets/:name`.
+
+## Deployment contract
+
+1. Run the Control API schema migration job before changing the pod image.
+2. Verify migration `0101_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.
+4. Verify a current client can create and explicitly delete with
+ UID/resourceVersion, and that a bodyless legacy rollback consumes a
+ server-side permit.
+
+The migration is additive and forward-only. It creates no foreign keys and
+does not alter existing rows or tables.
+
+## Runtime invariants
+
+- The browser receives no rollback proof or nonce cookie.
+- PostgreSQL stores a domain-separated SHA-256 digest of the admin session JTI,
+ never the raw JTI.
+- Permits bind namespace, name, UID, and resourceVersion and expire after at
+ most 120 seconds according to the PostgreSQL clock.
+- A 15-second claim lease serializes replicas. Transient failures release the
+ claim; a crashed process becomes retryable after the lease expires.
+- Terminal absence or identity change finalizes the permit. Kubernetes deletion
+ always carries UID and resourceVersion preconditions.
+- Expired rows are authorization-inert even before bounded physical cleanup.
+
+## Image rollback after migration 0101
+
+Rollback is **image-only**:
+
+1. Keep migration `0101`, 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 `0101`; 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.
+
+## Failure outcomes
+
+- Permit persistence failure after Kubernetes create: `503 repair_required`
+ includes the created UID/resourceVersion so the current UI can perform an
+ explicit CAS cleanup. The API never deletes by name as compensation.
+- Missing, expired, already claimed, or wrong-session permit: `428` and no
+ Kubernetes read or mutation.
+- PostgreSQL claim failure: `503 repair_required` and no Kubernetes read or
+ mutation.
+- Live identity change or Kubernetes CAS conflict: `409 repair_required`.
+- Reference graph unavailable: `503 repair_required`; the claim is released so
+ the legacy caller can retry within the original 120-second permit window.
+
+## Re-open triggers
+
+Re-audit this design if Control API changes from one replica plus `Recreate`,
+the permit or claim TTL changes, a caller can bypass admin-session binding, or
+any delete path stops carrying both UID and resourceVersion.
diff --git a/scripts/tests/test-control-api-runtime-access-contract.sh b/scripts/tests/test-control-api-runtime-access-contract.sh
index 41f3dd4b4..df2986cb3 100755
--- a/scripts/tests/test-control-api-runtime-access-contract.sh
+++ b/scripts/tests/test-control-api-runtime-access-contract.sh
@@ -9,11 +9,12 @@ relation_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { count++ } END { print cou
duplicate_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { seen[$1]++ } END { for (name in seen) if (seen[name] > 1) count++ } END { print count + 0 }' "$PROFILE_FILE")"
invalid_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ && (NF != 2 || $1 !~ /^[a-z][a-z0-9_]*$/ || $2 !~ /^(legacy_dml|upsert|append|read|link_lifecycle|none)$/) { count++ } END { print count + 0 }' "$PROFILE_FILE")"
-[[ "$relation_count" == "82" ]]
+[[ "$relation_count" == "85" ]]
[[ "$duplicate_count" == "0" ]]
[[ "$invalid_count" == "0" ]]
grep -qx $'gfs_desktop_operator_links\tlink_lifecycle' "$PROFILE_FILE"
grep -qx $'desktop_user_retirement_operations\tlink_lifecycle' "$PROFILE_FILE"
+grep -qx $'mcp_secret_rollback_permits\tlegacy_dml' "$PROFILE_FILE"
grep -Fq '$2 !~ /^(legacy_dml|upsert|append|read|link_lifecycle|none)$/' "$MIGRATION_SCRIPT"
grep -Fq "('INSERT', expected.access_profile IN ('legacy_dml', 'upsert', 'append', 'link_lifecycle'))" "$MIGRATION_SCRIPT"
diff --git a/scripts/tests/test-gcp-scripts.sh b/scripts/tests/test-gcp-scripts.sh
index a2e5e0110..9ec3173e6 100755
--- a/scripts/tests/test-gcp-scripts.sh
+++ b/scripts/tests/test-gcp-scripts.sh
@@ -1466,11 +1466,12 @@ assert_control_api_runtime_access_contract_is_exact() {
sequence_duplicate_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { seen[$1]++ } END { for (name in seen) if (seen[name] > 1) count++ } END { print count + 0 }' "$sequence_profile_file")"
sequence_invalid_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ && (NF != 2 || $1 !~ /^[a-z][a-z0-9_]*$/ || $2 !~ /^(legacy_rw|consume)$/) { count++ } END { print count + 0 }' "$sequence_profile_file")"
- if [[ "$relation_count" == "82" && "$duplicate_count" == "0" && "$invalid_count" == "0" ]] && \
+ if [[ "$relation_count" == "85" && "$duplicate_count" == "0" && "$invalid_count" == "0" ]] && \
grep -qx $'gfs_upload_parts\tnone' "$profile_file" && \
grep -qx $'gfs_upload_sessions\tnone' "$profile_file" && \
grep -qx $'llm_allowed_models\tlegacy_dml' "$profile_file" && \
grep -qx $'member_registration_credentials\tupsert' "$profile_file" && \
+ grep -qx $'mcp_secret_rollback_permits\tlegacy_dml' "$profile_file" && \
grep -qx $'llm_allowed_models_audit\tappend' "$profile_file" && \
grep -qx $'llm_catalog_sync_runs\tappend' "$profile_file" && \
grep -qx $'plugin_workload_sdk_spend_outcomes\tappend' "$profile_file" && \