Skip to content

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

TypeScript

fix(secrets): close PR 252 adversarial findings

Alfredo Lopeza06ef3fc99c0
diff --git a/charts/clerum-crds/crds/communicationchannel.yaml b/charts/clerum-crds/crds/communicationchannel.yaml
index 4466b1079..f0be8d5d9 100644
--- a/charts/clerum-crds/crds/communicationchannel.yaml
+++ b/charts/clerum-crds/crds/communicationchannel.yaml
@@ -2,6 +2,18 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: communicationchannels.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "communicationchannels",
+ "fields": [
+ {
+ "path": "spec.credentialsSecretRef",
+ "namespaceBinding": "resource"
+ }
+ ]
+ }
labels:
app.kubernetes.io/name: communicationchannel
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/context.yaml b/charts/clerum-crds/crds/context.yaml
index 974af4acb..dcfeb64a9 100644
--- a/charts/clerum-crds/crds/context.yaml
+++ b/charts/clerum-crds/crds/context.yaml
@@ -2,6 +2,13 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: contexts.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "contexts",
+ "fields": []
+ }
labels:
app.kubernetes.io/name: context
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/globalfilesystem.yaml b/charts/clerum-crds/crds/globalfilesystem.yaml
index 955ddfeaa..23ba9cabc 100644
--- a/charts/clerum-crds/crds/globalfilesystem.yaml
+++ b/charts/clerum-crds/crds/globalfilesystem.yaml
@@ -2,6 +2,13 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: globalfilesystems.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "globalfilesystems",
+ "fields": []
+ }
labels:
app.kubernetes.io/name: globalfilesystem
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/host.yaml b/charts/clerum-crds/crds/host.yaml
index 8599faceb..00bc14097 100644
--- a/charts/clerum-crds/crds/host.yaml
+++ b/charts/clerum-crds/crds/host.yaml
@@ -2,6 +2,18 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: hosts.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "hosts",
+ "fields": [
+ {
+ "path": "spec.secretRef",
+ "namespaceBinding": "host-secret"
+ }
+ ]
+ }
labels:
app.kubernetes.io/name: host
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/llmhook.yaml b/charts/clerum-crds/crds/llmhook.yaml
index 6c02f0271..13f2fedb0 100644
--- a/charts/clerum-crds/crds/llmhook.yaml
+++ b/charts/clerum-crds/crds/llmhook.yaml
@@ -2,6 +2,26 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: llmhooks.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "llmhooks",
+ "fields": [
+ {
+ "path": "spec.target.image.imagePullSecrets",
+ "namespaceBinding": "resource"
+ },
+ {
+ "path": "spec.target.image.envSecret",
+ "namespaceBinding": "resource"
+ },
+ {
+ "path": "spec.target.remote.authHeadersSecret",
+ "namespaceBinding": "resource"
+ }
+ ]
+ }
labels:
app.kubernetes.io/name: llmhook
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/mcpserver.yaml b/charts/clerum-crds/crds/mcpserver.yaml
index af2fbfc4f..1a557f3fb 100644
--- a/charts/clerum-crds/crds/mcpserver.yaml
+++ b/charts/clerum-crds/crds/mcpserver.yaml
@@ -2,6 +2,26 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: mcpservers.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "mcpservers",
+ "fields": [
+ {
+ "path": "spec.auth.secretRef",
+ "namespaceBinding": "resource"
+ },
+ {
+ "path": "spec.envSecret",
+ "namespaceBinding": "resource"
+ },
+ {
+ "path": "spec.imagePullSecrets",
+ "namespaceBinding": "resource"
+ }
+ ]
+ }
labels:
app.kubernetes.io/name: mcpserver
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/sharedfilesystem.yaml b/charts/clerum-crds/crds/sharedfilesystem.yaml
index c47151ef4..7656bc6e9 100644
--- a/charts/clerum-crds/crds/sharedfilesystem.yaml
+++ b/charts/clerum-crds/crds/sharedfilesystem.yaml
@@ -2,6 +2,13 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: sharedfilesystems.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "sharedfilesystems",
+ "fields": []
+ }
labels:
app.kubernetes.io/name: sharedfilesystem
app.kubernetes.io/part-of: clerum
diff --git a/charts/clerum-crds/crds/workflowrecipe.yaml b/charts/clerum-crds/crds/workflowrecipe.yaml
index ec1bae3ab..3fd6bd884 100644
--- a/charts/clerum-crds/crds/workflowrecipe.yaml
+++ b/charts/clerum-crds/crds/workflowrecipe.yaml
@@ -2,6 +2,46 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: workflowrecipes.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "workflowrecipes",
+ "fields": [
+ {
+ "path": "spec.agent.secretRef",
+ "namespaceBinding": "reference-value"
+ },
+ {
+ "path": "spec.steps[].run.capabilities.secrets[].secretRef",
+ "namespaceBinding": "workflow-recipe"
+ },
+ {
+ "path": "spec.workloads[].envSecret",
+ "namespaceBinding": "workflow-workload"
+ },
+ {
+ "path": "spec.workloads[].imagePullSecrets",
+ "namespaceBinding": "workflow-workload"
+ },
+ {
+ "path": "spec.oauthClients[].clientIdRef",
+ "namespaceBinding": "workflow-recipe"
+ },
+ {
+ "path": "spec.oauthClients[].clientSecretRef",
+ "namespaceBinding": "workflow-recipe"
+ },
+ {
+ "path": "spec.webhooks[].verification.secretRef",
+ "namespaceBinding": "workflow-recipe"
+ },
+ {
+ "path": "spec.webhooks[].verification.setupHandshake.secretRef",
+ "namespaceBinding": "workflow-recipe"
+ }
+ ]
+ }
labels:
app.kubernetes.io/name: workflowrecipe
app.kubernetes.io/part-of: clerum
@@ -396,6 +436,9 @@ spec:
secretRef:
type: object
required: [name, key]
+ description: >-
+ Reference to a Secret in the recipe namespace
+ containing the snippet capability value.
properties:
name:
type: string
diff --git a/charts/clerum-crds/crds/workflowrecipepolicy.yaml b/charts/clerum-crds/crds/workflowrecipepolicy.yaml
index 8db97a969..c1275421e 100644
--- a/charts/clerum-crds/crds/workflowrecipepolicy.yaml
+++ b/charts/clerum-crds/crds/workflowrecipepolicy.yaml
@@ -2,6 +2,13 @@ apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: workflowrecipepolicies.clerum.io
+ annotations:
+ clerum.io/secret-reference-contract: |-
+ {
+ "version": 1,
+ "plural": "workflowrecipepolicies",
+ "fields": []
+ }
labels:
app.kubernetes.io/name: workflowrecipepolicy
app.kubernetes.io/part-of: clerum
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index b2ce7fe8d..b73f8aa11 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.503",
+ "version": "0.1.504",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.503",
+ "version": "0.1.504",
"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 c60946ab6..9adeb7ea7 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.503",
+ "version": "0.1.504",
"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/registry.ts b/control-api/src/routes/admin/registry.ts
index 6e42ee7bd..ab00c0274 100644
--- a/control-api/src/routes/admin/registry.ts
+++ b/control-api/src/routes/admin/registry.ts
@@ -47,7 +47,6 @@ import {
REGISTRY_SPEC_DIGEST_ANNOTATION,
type RegistryMutationOutcome,
type RegistryResourceSnapshot,
- classifyCreatedRegistryMutationReadback,
classifyRegistryAssociationReadback,
classifyRegistryMutationReadback,
registrySpecDigest,
@@ -1020,13 +1019,28 @@ async function fenceSecretAtSnapshot(
snapshot.name,
snapshot.namespace
)
- if (fenced.uid !== snapshot.uid || !fenced.resourceVersion) return 'ambiguous'
+ if (fenced.uid !== snapshot.uid || !fenced.resourceVersion) {
+ logRegistryFenceFailure({
+ resourceKind: 'Secret',
+ resourceName: snapshot.name,
+ namespace: snapshot.namespace,
+ failure: 'identity-mismatch',
+ })
+ return 'ambiguous'
+ }
// The successful CAS write consumed the exact prior UID/RV. An ambiguous
// Registry write carrying that same precondition cannot commit afterwards.
return 'not-committed'
- } catch {
+ } catch (error) {
// A rejected fence proves only that the object changed or the fence itself
// was uncertain. The prior GET state is never promoted to no-commit.
+ logRegistryFenceFailure({
+ resourceKind: 'Secret',
+ resourceName: snapshot.name,
+ namespace: snapshot.namespace,
+ failure: registryFenceFailure(error),
+ error,
+ })
return 'ambiguous'
}
}
@@ -1034,22 +1048,10 @@ async function fenceSecretAtSnapshot(
async function readSecretMutationOutcome(
gateway: K8sGateway,
snapshotBefore: SecretSnapshot | null
-): Promise<{
- outcome: 'committed' | 'not-committed' | 'ambiguous'
- snapshot: SecretSnapshot | null
- identityProven: boolean
-}> {
- if (snapshotBefore) {
- const fenceOutcome = await fenceSecretAtSnapshot(gateway, snapshotBefore)
- if (fenceOutcome === 'not-committed') {
- return { outcome: fenceOutcome, snapshot: null, identityProven: false }
- }
- }
- // A GET after a failed fence is never a receipt of this write. The observed
- // resourceVersion may belong to a same-UID writer that raced with us, so do
- // not adopt it as a compensation precondition. The caller must preserve the
- // state and surface repair_required.
- return { outcome: 'ambiguous', snapshot: null, identityProven: false }
+): Promise<'not-committed' | 'ambiguous'> {
+ // A Secret has no immutable request marker that can turn a readback into a
+ // receipt. Only consuming the exact pre-write UID/RV proves no commit.
+ return snapshotBefore ? fenceSecretAtSnapshot(gateway, snapshotBefore) : 'ambiguous'
}
export type CreatedSecretAfterDeleteFailure =
@@ -1185,45 +1187,6 @@ async function readResourceForRollback(
}
}
-type CreatedResourceReadbackOutcome = {
- outcome: 'committed' | 'not-committed' | 'ambiguous'
- snapshot: RegistryResourceSnapshot | null
-}
-
-async function readCreatedResourceOutcome(
- gateway: K8sGateway,
- plural: Parameters<K8sGateway['getResource']>[0],
- name: string,
- namespace: string,
- desired: {
- spec: Record<string, unknown>
- metadata: { labels?: Record<string, string>; annotations?: Record<string, string> }
- specDigest: string
- },
- operationId: string
-): Promise<CreatedResourceReadbackOutcome> {
- for (let attempt = 1; attempt <= 3; attempt += 1) {
- try {
- const current = normalizeRegistryResourceSnapshot(
- await gateway.getResource(plural, name, namespace),
- name,
- namespace
- )
- if (
- classifyCreatedRegistryMutationReadback({ current, desired, operationId }) === 'committed'
- ) {
- return { outcome: 'committed', snapshot: current }
- }
- } catch {
- // A failed read cannot prove that a create did not commit. This includes
- // repeated 404s: the original request may still be in flight or the
- // read path may be stale, and a create has no pre-write UID/RV fence.
- }
- if (attempt < 3) await sleep(UPDATE_CONFLICT_RETRY_DELAY_MS * attempt)
- }
- return { outcome: 'ambiguous', snapshot: null }
-}
-
async function fenceRegistryResourceAtSnapshot(
gateway: K8sGateway,
plural: Parameters<K8sGateway['getResource']>[0],
@@ -1233,7 +1196,15 @@ async function fenceRegistryResourceAtSnapshot(
): Promise<'not-committed' | 'ambiguous'> {
const uid = snapshot.metadata?.uid
const resourceVersion = snapshot.metadata?.resourceVersion
- if (!uid || !resourceVersion) return 'ambiguous'
+ if (!uid || !resourceVersion) {
+ logRegistryFenceFailure({
+ resourceKind: plural,
+ resourceName: name,
+ namespace,
+ failure: 'identity-unavailable',
+ })
+ return 'ambiguous'
+ }
try {
const fenced = normalizeRegistryResourceSnapshot(
@@ -1257,15 +1228,28 @@ async function fenceRegistryResourceAtSnapshot(
namespace
)
if (fenced.metadata?.uid !== uid || typeof fenced.metadata?.resourceVersion !== 'string') {
+ logRegistryFenceFailure({
+ resourceKind: plural,
+ resourceName: name,
+ namespace,
+ failure: 'identity-mismatch',
+ })
return 'ambiguous'
}
// A successful replacement fenced the old UID/RV. Any in-flight Registry
// write carrying that same precondition can no longer commit afterwards.
return 'not-committed'
- } catch {
+ } catch (error) {
// A rejected fence means the object changed, but does not identify whether
// this operation or another writer won. The caller must read and classify
// the current state; the prior state alone is never proof of no-commit.
+ logRegistryFenceFailure({
+ resourceKind: plural,
+ resourceName: name,
+ namespace,
+ failure: registryFenceFailure(error),
+ error,
+ })
return 'ambiguous'
}
}
@@ -1543,6 +1527,34 @@ export async function getInstalledRegistryState(gateway?: K8sGateway): Promise<{
const log = rootLogger.child({ module: 'admin-registry' })
+type RegistryFenceFailure = 'identity-mismatch' | 'identity-unavailable' | 'rejected' | 'unresolved'
+
+function registryFenceFailure(
+ error: unknown
+): Extract<RegistryFenceFailure, 'rejected' | 'unresolved'> {
+ const status = extractK8sError(error)?.status
+ return status === 409 || isDeterministicRegistryNoCommit(error) ? 'rejected' : 'unresolved'
+}
+
+function logRegistryFenceFailure(input: {
+ resourceKind: string
+ resourceName: string
+ namespace: string
+ failure: RegistryFenceFailure
+ error?: unknown
+}): void {
+ log.warn(
+ {
+ resourceKind: input.resourceKind,
+ resourceName: input.resourceName,
+ namespace: input.namespace,
+ fenceFailure: input.failure,
+ ...(input.error === undefined ? {} : { error: registryErrorLogFields(input.error) }),
+ },
+ 'Registry mutation identity fence did not establish no-commit'
+ )
+}
+
export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
const router = Router()
@@ -2052,7 +2064,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// ── Step 3: Create K8s Secret if credentials provided ─────────────
let createdSecretSnapshot: SecretSnapshot | null = null
- let createdSecretIdentityProven = false
if (credRequired) {
const secretData = credentialPayload.secretData
if (Object.keys(secretData).length > 0) {
@@ -2068,7 +2079,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
createdSecretSnapshot = await gateway.createSecret(secretReq, {
capability: 'registryCredential',
})
- createdSecretIdentityProven = true
} catch (err) {
const k8sErr = extractK8sError(err)
if (k8sErr && k8sErr.status < 500) {
@@ -2077,34 +2087,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
.json({ error: `Secret creation failed: ${k8sErr.message}` })
return
}
- const recovered = await readSecretMutationOutcome(gateway, null)
- if (recovered.outcome === 'not-committed') {
- res.status(503).json({
- error: 'registry_secret_outcome_not_committed',
- outcome: 'not_committed',
- })
- return
- }
- if (recovered.outcome !== 'committed' || !recovered.snapshot) {
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- if (!recovered.identityProven) {
- // A create has no pre-write UID to compare against. The
- // readback may be a same-name replacement that copied the
- // operation marker, so it cannot be reported as this request's
- // commit or used as a compensation target.
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- createdSecretSnapshot = recovered.snapshot
- createdSecretIdentityProven = recovered.identityProven
+ // A create has no pre-write UID/RV to fence. Its response cannot
+ // be recovered into a compensable success, even if the named
+ // Secret later looks like the requested intent.
+ res.status(503).json({
+ error: 'registry_secret_outcome_ambiguous',
+ outcome: 'repair_required',
+ })
+ return
}
auditLog('secret_created', {
secretName,
@@ -2117,11 +2107,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// ── Step 4: Create McpServer CRD (rollback by UID on failure) ────
let createdMcpServerSnapshot: RegistryResourceSnapshot | null = null
- const desiredMcpServerMutation = {
- spec: mcpServerSpec,
- metadata: { labels: registryLabels, annotations: registryAnnotations },
- specDigest: registrySpecDigest(mcpServerSpec),
- }
try {
const created = await gateway.createResource(
'mcpservers',
@@ -2148,106 +2133,39 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
} catch (err) {
const k8sErr = extractK8sError(err)
- const ambiguousCreate =
- err instanceof RegistryInstallRollbackError || !k8sErr || k8sErr.status >= 500
- if (ambiguousCreate) {
- const recovered = await readCreatedResourceOutcome(
- gateway,
- 'mcpservers',
- serverName,
- targetNs,
- desiredMcpServerMutation,
- resourceOperationId
- )
- if (recovered.outcome === 'not-committed') {
- if (createdSecretSnapshot && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- let rollbackFailed = false
- if (createdSecretSnapshot) {
- try {
- await rollbackCreatedSecret(gateway, createdSecretSnapshot)
- } catch {
- rollbackFailed = true
- }
- }
- if (rollbackFailed) {
- res.status(500).json({
- error: 'registry_install_rollback_incomplete',
- outcome: 'compensation_failed',
- })
- return
- }
- res.status(k8sErr?.status ?? 503).json({
- error: 'registry_resource_outcome_not_committed',
- outcome: 'not_committed',
- })
- return
- }
- if (recovered.outcome !== 'committed' || !recovered.snapshot) {
- res.status(503).json({
- error: 'registry_resource_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- // A create readback has no pre-write UID to compare with. Even a
- // perfect operation marker/spec match can belong to a same-name
- // replacement that copied the mutable intent. It is safe to leave
- // the observed object for repair, but not to report it as this
- // request's commit or to make it compensable.
+ if (
+ err instanceof RegistryInstallRollbackError ||
+ !isDeterministicRegistryNoCommit(err)
+ ) {
res.status(503).json({
error: 'registry_resource_outcome_ambiguous',
outcome: 'repair_required',
})
return
- } else {
- // A conflict, timeout, or throttling response is not a proof that
- // the named CR is absent. It may identify a live CR or follow an
- // accepted create, so preserve the Secret for repair instead of
- // deleting a dependency we cannot disassociate atomically.
- if (!isDeterministicRegistryNoCommit(err)) {
- res.status(503).json({
- error: 'registry_resource_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
+ }
- // A deterministic create rejection proves there is no CR to
- // compensate; only the earlier credential object needs rollback.
- if (createdSecretSnapshot && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- let rollbackFailed = false
- if (createdSecretSnapshot) {
- try {
- await rollbackCreatedSecret(gateway, createdSecretSnapshot)
- } catch {
- rollbackFailed = true
- }
- }
- if (rollbackFailed) {
- res.status(500).json({
- error: 'registry_install_rollback_incomplete',
- outcome: 'compensation_failed',
- })
- return
- }
- if (k8sErr) {
- res.status(k8sErr.status).json({ error: k8sErr.message })
- return
+ // A deterministic create rejection proves there is no CR to
+ // compensate; only the earlier credential object needs rollback.
+ let rollbackFailed = false
+ if (createdSecretSnapshot) {
+ try {
+ await rollbackCreatedSecret(gateway, createdSecretSnapshot)
+ } catch {
+ rollbackFailed = true
}
- throw err
}
+ if (rollbackFailed) {
+ res.status(500).json({
+ error: 'registry_install_rollback_incomplete',
+ outcome: 'compensation_failed',
+ })
+ return
+ }
+ if (k8sErr) {
+ res.status(k8sErr.status).json({ error: k8sErr.message })
+ return
+ }
+ throw err
}
// ── Step 5: Update Context allowlist ──────────────────────────────
@@ -2311,13 +2229,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
if (associationOutcome !== 'committed') {
- if (createdSecretSnapshot && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
let resourceRollbackFailed = false
try {
await rollbackCreatedResource(
@@ -2784,7 +2695,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
const credentials = body.credentials ?? {}
const secretName = `${crName}-creds`
let secretCreated = false
- let createdSecretIdentityProven = false
let createdSecretSnapshot: SecretSnapshot | null = null
if (Object.keys(credentials).length > 0) {
const schemaKeys = new Set((credSchema?.keys ?? []).map(k => k.name))
@@ -2809,40 +2719,19 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
},
REGISTRY_SECRET_WRITE_OPTIONS
)
- createdSecretIdentityProven = true
} catch (err) {
const k8sErr = extractK8sError(err)
if (k8sErr && k8sErr.status < 500) {
res.status(k8sErr.status).json({ error: `Secret creation failed: ${k8sErr.message}` })
return
}
- const recovered = await readSecretMutationOutcome(gateway, null)
- if (recovered.outcome === 'not-committed') {
- res.status(503).json({
- error: 'registry_secret_outcome_not_committed',
- outcome: 'not_committed',
- })
- return
- }
- if (recovered.outcome !== 'committed' || !recovered.snapshot) {
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- if (!recovered.identityProven) {
- // A create readback cannot prove the UID was issued for this
- // request. Leave the object for repair rather than treating it
- // as a successful, compensable install.
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- createdSecretSnapshot = recovered.snapshot
- createdSecretIdentityProven = recovered.identityProven
+ // A create has no pre-write UID/RV to fence. Its response cannot
+ // be recovered into a compensable success.
+ res.status(503).json({
+ error: 'registry_secret_outcome_ambiguous',
+ outcome: 'repair_required',
+ })
+ return
}
secretCreated = true
}
@@ -2858,13 +2747,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
try {
await ensureRegistryPullSecret(gateway, targetNs)
} catch (err) {
- if (secretCreated && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
if (secretCreated && createdSecretSnapshot) {
try {
await rollbackCreatedSecret(gateway, createdSecretSnapshot)
@@ -2913,11 +2795,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
registryAnnotations[REGISTRY_SPEC_DIGEST_ANNOTATION] = registrySpecDigest(hookSpec)
let createdHookSnapshot: RegistryResourceSnapshot | null = null
- const desiredHookMutation = {
- spec: hookSpec,
- metadata: { labels: registryLabels, annotations: registryAnnotations },
- specDigest: registrySpecDigest(hookSpec),
- }
try {
const created = await gateway.createResource(
'llmhooks',
@@ -2933,101 +2810,37 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
} catch (err) {
const k8sErr = extractK8sError(err)
- const ambiguousCreate =
- err instanceof RegistryInstallRollbackError || !k8sErr || k8sErr.status >= 500
- if (ambiguousCreate) {
- const recovered = await readCreatedResourceOutcome(
- gateway,
- 'llmhooks',
- crName,
- targetNs,
- desiredHookMutation,
- resourceOperationId
- )
- if (recovered.outcome === 'not-committed') {
- if (secretCreated && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- let rollbackFailed = false
- if (secretCreated && createdSecretSnapshot) {
- try {
- await rollbackCreatedSecret(gateway, createdSecretSnapshot)
- } catch {
- rollbackFailed = true
- }
- }
- if (rollbackFailed) {
- res.status(500).json({
- error: 'registry_install_rollback_incomplete',
- outcome: 'compensation_failed',
- })
- return
- }
- res.status(k8sErr?.status ?? 503).json({
- error: 'registry_resource_outcome_not_committed',
- outcome: 'not_committed',
- })
- return
- }
- if (recovered.outcome !== 'committed' || !recovered.snapshot) {
- res.status(503).json({
- error: 'registry_resource_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- // A create readback cannot prove that the observed UID was issued
- // for this request. Do not turn a mutable marker/spec match into a
- // successful install or a later compensation target.
+ if (
+ err instanceof RegistryInstallRollbackError ||
+ !isDeterministicRegistryNoCommit(err)
+ ) {
res.status(503).json({
error: 'registry_resource_outcome_ambiguous',
outcome: 'repair_required',
})
return
- } else {
- // A conflict, timeout, or throttling response is not a proof that
- // the named hook is absent. Preserve its Secret for repair because
- // no cross-resource transaction can prove dependency safety.
- if (!isDeterministicRegistryNoCommit(err)) {
- res.status(503).json({
- error: 'registry_resource_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
+ }
- if (secretCreated && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
- let rollbackFailed = false
- if (secretCreated && createdSecretSnapshot) {
- try {
- await rollbackCreatedSecret(gateway, createdSecretSnapshot)
- } catch {
- rollbackFailed = true
- }
- }
- if (rollbackFailed) {
- res.status(500).json({
- error: 'registry_install_rollback_incomplete',
- outcome: 'compensation_failed',
- })
- return
- }
- if (k8sErr) {
- res.status(k8sErr.status).json({ error: k8sErr.message })
- return
+ let rollbackFailed = false
+ if (secretCreated && createdSecretSnapshot) {
+ try {
+ await rollbackCreatedSecret(gateway, createdSecretSnapshot)
+ } catch {
+ rollbackFailed = true
}
- throw err
}
+ if (rollbackFailed) {
+ res.status(500).json({
+ error: 'registry_install_rollback_incomplete',
+ outcome: 'compensation_failed',
+ })
+ return
+ }
+ if (k8sErr) {
+ res.status(k8sErr.status).json({ error: k8sErr.message })
+ return
+ }
+ throw err
}
// Step 10 — reference the hook from Host.spec.guardrails.hooks[phase] as
@@ -3089,13 +2902,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
if (associationOutcome !== 'committed') {
- if (secretCreated && createdSecretSnapshot && !createdSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_install_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
let resourceRollbackFailed = false
try {
await rollbackCreatedResource(
@@ -4009,7 +3815,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// constrained writer, so fail closed before creating side effects.
let previousSecretSnapshot: SecretSnapshot | null = null
let secretCreatedDuringUpgrade = false
- let mutatedSecretIdentityProven = false
let mutatedSecretPreconditions: SecretPreconditions | null = null
let mutatedSecretSnapshot: SecretSnapshot | null = null
const hasCredentialUpdates = Object.keys(credentialPayload.secretData).length > 0
@@ -4087,7 +3892,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
REGISTRY_SECRET_WRITE_OPTIONS
)
mutatedSecretSnapshot = updatedSecret
- mutatedSecretIdentityProven = true
mutatedSecretPreconditions = secretPreconditions(updatedSecret)
auditLog('secret_updated', {
secretName,
@@ -4101,7 +3905,6 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
REGISTRY_SECRET_WRITE_OPTIONS
)
mutatedSecretSnapshot = created
- mutatedSecretIdentityProven = true
secretCreatedDuringUpgrade = true
mutatedSecretPreconditions = secretPreconditions(created)
auditLog('secret_created', {
@@ -4117,52 +3920,28 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
- const recovered = await readSecretMutationOutcome(gateway, previousSecretSnapshot)
- if (recovered.outcome === 'not-committed') {
+ const secretOutcome = await readSecretMutationOutcome(gateway, previousSecretSnapshot)
+ if (secretOutcome === 'not-committed') {
res.status(503).json({
error: 'registry_secret_outcome_not_committed',
outcome: 'not_committed',
})
return
}
- if (recovered.outcome !== 'committed' || !recovered.snapshot) {
- log.error(
- {
- serverName: body.serverName,
- namespace,
- secretName,
- error: registryErrorLogFields(err),
- },
- 'Registry credential write outcome is ambiguous'
- )
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
-
- if (!recovered.identityProven) {
- // `previousSecretSnapshot === null` means this was a create.
- // A post-error readback has no pre-write UID proof, so returning
- // success would allow an old/replaced object to masquerade as
- // this upgrade's credential commit.
- res.status(503).json({
- error: 'registry_secret_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
-
- mutatedSecretSnapshot = recovered.snapshot
- mutatedSecretIdentityProven = recovered.identityProven
- secretCreatedDuringUpgrade = previousSecretSnapshot === null
- mutatedSecretPreconditions = secretPreconditions(recovered.snapshot)
- auditLog('secret_write_recovered_after_ambiguous_response', {
- secretName,
- namespace,
- registryEntry: body.registryEntryName,
+ log.error(
+ {
+ serverName: body.serverName,
+ namespace,
+ secretName,
+ error: registryErrorLogFields(err),
+ },
+ 'Registry credential write outcome is ambiguous'
+ )
+ res.status(503).json({
+ error: 'registry_secret_outcome_ambiguous',
+ outcome: 'repair_required',
})
+ return
}
}
@@ -4210,12 +3989,7 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
)
if (mutation.outcome !== 'committed') {
const err = mutation.error
- const k8sErr = extractK8sError(err)
- const outcomeIsAmbiguous = mutation.outcome !== 'rejected'
- const upgradeOutcome: RegistryMutationOutcome | null =
- mutation.outcome === 'rejected' ? null : mutation.outcome
-
- if (outcomeIsAmbiguous && upgradeOutcome === 'ambiguous') {
+ if (mutation.outcome === 'ambiguous') {
log.error(
{
serverName: body.serverName,
@@ -4231,35 +4005,11 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
- // An ambiguous CR response is not made safe for cross-resource
- // compensation merely because the identity fence proves that the
- // requested CR replace did not commit. The live CR may still depend
- // on the Secret, and the failed request may have been accepted by a
- // different apiserver path. Preserve the credential state and make
- // repair explicit until the caller can reconcile both resources.
- if (upgradeOutcome === 'ambiguous' && hasCredentialUpdates) {
- res.status(503).json({
- error: 'registry_upgrade_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
-
- if (hasCredentialUpdates && mutatedSecretSnapshot && !mutatedSecretIdentityProven) {
- res.status(503).json({
- error: 'registry_upgrade_outcome_ambiguous',
- outcome: 'repair_required',
- })
- return
- }
-
- if (upgradeOutcome !== 'ambiguous' && hasCredentialUpdates) {
+ // An ambiguous CR response never reaches compensation. The live CR
+ // may still depend on the credential, so repair remains the only
+ // safe outcome until the caller can reconcile both resources.
+ if (hasCredentialUpdates) {
try {
- if (!mutatedSecretPreconditions) {
- throw Object.assign(new Error('mutated Secret identity unavailable'), {
- code: 'secret_identity_unavailable',
- })
- }
if (secretCreatedDuringUpgrade) {
const createdSecret = mutatedSecretSnapshot
if (!createdSecret) {
@@ -4269,6 +4019,11 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
await rollbackCreatedSecret(gateway, createdSecret)
} else if (previousSecretSnapshot) {
+ if (!mutatedSecretPreconditions) {
+ throw Object.assign(new Error('mutated Secret identity unavailable'), {
+ code: 'secret_identity_unavailable',
+ })
+ }
await gateway.updateSecret(
{
name: previousSecretSnapshot.name,
@@ -4302,18 +4057,20 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
}
- if (upgradeOutcome === 'not-committed') {
+ if (mutation.outcome === 'not-committed') {
res.status(503).json({
error: 'registry_upgrade_outcome_not_committed',
outcome: 'not_committed',
})
return
- } else if (k8sErr) {
+ }
+
+ const k8sErr = extractK8sError(err)
+ if (k8sErr) {
res.status(k8sErr.status).json({ error: k8sErr.message })
return
- } else {
- throw err
}
+ throw err
}
auditLog('upgrade', {
serverName: body.serverName,
diff --git a/control-api/src/routes/admin/secrets.ts b/control-api/src/routes/admin/secrets.ts
index 7c86873a0..58c5f274a 100644
--- a/control-api/src/routes/admin/secrets.ts
+++ b/control-api/src/routes/admin/secrets.ts
@@ -13,15 +13,24 @@ import {
type SecretOwnership,
parseSecretOwnership,
} from '../../secretOwnership.js'
-import {
- REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS,
- REGISTRY_SECRET_ROTATION_PRESERVED_ANNOTATION_KEYS,
-} from '../../services/secretConstraints.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,
+ type McpSecretDeleteProofClaims,
+ createMcpSecretDeleteProof,
+ mcpSecretDeleteProofCookieName,
+ verifyMcpSecretDeleteProof,
+} from '../../utils/auth/mcpSecretDeleteProof.js'
+import {
+ CONTROL_UI_ADMIN_SESSION_COOKIE,
+ clearHttpOnlySessionCookie,
+ readCookie,
+ setHttpOnlySessionCookie,
+} from '../../utils/auth/sessionCookies.js'
import { listHostSecrets } from './hostSecrets.js'
import { isLlmHostSecret } from './llmSecretIdentity.js'
@@ -76,6 +85,22 @@ function requestSecretPreconditions(raw: unknown): SecretPreconditions | null {
return { uid: body.uid, resourceVersion: body.resourceVersion }
}
+function hasRequestedSecretIdentity(raw: unknown): boolean {
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false
+ return (
+ Object.prototype.hasOwnProperty.call(raw, 'uid') ||
+ Object.prototype.hasOwnProperty.call(raw, 'resourceVersion')
+ )
+}
+
+function isLegacyMcpSecretDeleteBody(raw: unknown): boolean {
+ return (
+ raw === undefined ||
+ raw === null ||
+ (typeof raw === 'object' && !Array.isArray(raw) && Object.keys(raw).length === 0)
+ )
+}
+
// The plaintext data being written, merging base64 `data` and plaintext
// `stringData` (stringData wins, matching Kubernetes Secret semantics).
function effectiveSecretData(body: unknown): Record<string, string> {
@@ -538,15 +563,37 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
const created = await gateway.createSecret(secretReq)
const identity = secretIdentityPreconditions(created)
- if (!identity) {
+ const completeIdentity =
+ identity?.uid && identity.resourceVersion
+ ? { uid: identity.uid, resourceVersion: identity.resourceVersion }
+ : null
+ if (!completeIdentity) {
res.status(503).json({ error: 'secret_identity_unavailable', outcome: 'repair_required' })
return
}
+ const sessionToken = readCookie(req, CONTROL_UI_ADMIN_SESSION_COOKIE)
+ if (sessionToken) {
+ setHttpOnlySessionCookie(
+ req,
+ res,
+ mcpSecretDeleteProofCookieName(secretReq.name),
+ createMcpSecretDeleteProof(
+ {
+ name: secretReq.name,
+ namespace: targetNs,
+ uid: completeIdentity.uid,
+ resourceVersion: completeIdentity.resourceVersion,
+ },
+ sessionToken
+ ),
+ MCP_SECRET_DELETE_PROOF_TTL_SECONDS
+ )
+ }
res.status(201).json({
name: name.trim(),
namespace: targetNs,
- uid: identity.uid,
- resourceVersion: identity.resourceVersion,
+ uid: completeIdentity.uid,
+ resourceVersion: completeIdentity.resourceVersion,
created: true,
})
})
@@ -667,18 +714,11 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
res.status(503).json({ error: 'secret_identity_unavailable', outcome: 'repair_required' })
return
}
- const existingAnnotations = existing.metadata?.annotations
- const isRegistryManaged = REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS.every(
- key => typeof existingAnnotations?.[key] === 'string'
- )
- const preserveRegistryAnnotations = isRegistryManaged
- ? {
- allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_ROTATION_PRESERVED_ANNOTATION_KEYS,
- }
- : undefined
const merged = await gateway.mergeSecret(
{ name, namespace: targetNs, stringData: data },
- preserveRegistryAnnotations,
+ // Public rotation has no metadata capability; the optional constraints
+ // parameter precedes the UID fence in the gateway contract.
+ undefined,
precondition
)
@@ -758,10 +798,42 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
}
const name = req.params.name.trim()
const requestedPrecondition = requestSecretPreconditions(req.body)
- if (!requestedPrecondition) {
+ if (hasRequestedSecretIdentity(req.body) && !requestedPrecondition) {
res.status(428).json({ error: 'secret_identity_precondition_required' })
return
}
+ let deletePrecondition: SecretPreconditions
+ let signedCreateProof: McpSecretDeleteProofClaims | null = null
+ if (requestedPrecondition) {
+ // Current clients send the identity returned by POST and retain the
+ // established compare-and-delete contract.
+ deletePrecondition = requestedPrecondition
+ } 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.
+ if (!isLegacyMcpSecretDeleteBody(req.body)) {
+ res.status(428).json({ error: 'secret_identity_precondition_required' })
+ return
+ }
+ const sessionToken = readCookie(req, CONTROL_UI_ADMIN_SESSION_COOKIE)
+ const proofCookieName = mcpSecretDeleteProofCookieName(name)
+ const proofCookie = readCookie(req, proofCookieName)
+ const candidateProof =
+ sessionToken && proofCookie ? verifyMcpSecretDeleteProof(proofCookie, sessionToken) : null
+ signedCreateProof =
+ candidateProof?.name === name && candidateProof.namespace === config.mcpServersNamespace
+ ? candidateProof
+ : null
+ if (!signedCreateProof) {
+ res.status(428).json({ error: 'secret_identity_precondition_required' })
+ return
+ }
+ deletePrecondition = {
+ uid: signedCreateProof.uid,
+ resourceVersion: signedCreateProof.resourceVersion,
+ }
+ }
let existing: {
metadata?: { labels?: Record<string, string>; uid?: string; resourceVersion?: string }
} | null
@@ -784,8 +856,8 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
return
}
if (
- currentPrecondition.uid !== requestedPrecondition.uid ||
- currentPrecondition.resourceVersion !== requestedPrecondition.resourceVersion
+ currentPrecondition.uid !== deletePrecondition.uid ||
+ currentPrecondition.resourceVersion !== deletePrecondition.resourceVersion
) {
res.status(409).json({ error: 'secret_identity_changed', outcome: 'repair_required' })
return
@@ -811,12 +883,33 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
.json({ error: 'mcp_secret_reference_check_unavailable', outcome: 'repair_required' })
return
}
- const deleted = await gateway.deleteSecret(
- name,
- config.mcpServersNamespace,
- requestedPrecondition
- )
- res.status(200).json(toPublicDeleteSecretSummary(deleted))
+ if (signedCreateProof) {
+ logger.warn(
+ {
+ module: 'admin-secrets',
+ event: 'mcp-secret-delete-legacy-signed-create-proof',
+ name,
+ namespace: config.mcpServersNamespace,
+ preconditionSource: 'signed-create-proof',
+ },
+ 'MCP Secret delete used signed create proof'
+ )
+ }
+ try {
+ const deleted = await gateway.deleteSecret(
+ name,
+ config.mcpServersNamespace,
+ deletePrecondition
+ )
+ clearHttpOnlySessionCookie(req, res, mcpSecretDeleteProofCookieName(name))
+ res.status(200).json(toPublicDeleteSecretSummary(deleted))
+ } catch (err) {
+ if (extractHttpStatus(err) === 409) {
+ res.status(409).json({ error: 'secret_identity_changed', outcome: 'repair_required' })
+ return
+ }
+ throw err
+ }
})
)
diff --git a/control-api/src/services/registryClient.ts b/control-api/src/services/registryClient.ts
index 17c1c798a..3f05745c4 100644
--- a/control-api/src/services/registryClient.ts
+++ b/control-api/src/services/registryClient.ts
@@ -599,44 +599,76 @@ export async function publishEntry(body: Record<string, unknown>): Promise<unkno
// These proxy the registry's per-org owner surface (delivered by the machine-
// grant + owner-entries registry PRs). Unlike registryFetch, this helper:
// • is 204/empty-aware (revokes return 204 with no body — res.json() would 500),
-// • throws a RegistryProxyError carrying BOTH the upstream status AND the parsed
-// { error: <code> } body, so the admin route can forward it verbatim to the UI
-// (status alone can't disambiguate self_grant / grantee_reserved / plugin_public,
-// all 400). Mirrors routes/admin/workflows/grants.routes.ts's typed passthrough.
+// • throws a RegistryProxyError carrying the upstream status plus a narrowly
+// allowlisted error code, so the admin route can preserve the UI's typed
+// grant errors without reflecting arbitrary upstream diagnostics.
// Built on authedFetch (machine Bearer + 401-evict-retry), same as registryFetch.
-/** Upstream registry error carrying the status + parsed body for verbatim proxy forwarding. */
+export type RegistryProxyErrorBody = { error: string }
+
+/** Upstream registry error carrying a status plus a safe, bounded error code. */
export class RegistryProxyError extends Error {
constructor(
readonly status: number,
- readonly body: unknown
+ readonly body: RegistryProxyErrorBody
) {
super(`Registry ${status}`)
this.name = 'RegistryProxyError'
}
}
+// These are the only registry-owned codes that the current publisher UI renders
+// specially. Keeping the values as an explicit allowlist means an upstream error
+// cannot turn a raw message, HTML page, token, or credential into API output.
+const SAFE_REGISTRY_PROXY_ERROR_CODES = new Set([
+ 'grantee_not_found',
+ 'self_grant',
+ 'plugin_public',
+ 'grantee_reserved',
+ 'plugin_not_found',
+])
+
+function registryProxyFallbackError(status: number): RegistryProxyErrorBody {
+ return { error: status >= 400 && status <= 599 ? `registry_${status}` : 'registry_error' }
+}
+
+function isJsonResponse(res: Response): boolean {
+ const contentType = res.headers.get('content-type')
+ if (!contentType) return false
+ const mediaType = contentType.split(';', 1)[0]?.trim().toLowerCase()
+ return mediaType === 'application/json' || mediaType?.endsWith('+json') === true
+}
+
+async function registryProxyErrorBody(res: Response): Promise<RegistryProxyErrorBody> {
+ const fallback = registryProxyFallbackError(res.status)
+ if (!isJsonResponse(res)) {
+ await discardResponseBody(res)
+ return fallback
+ }
+ try {
+ const parsed = (await res.json()) as unknown
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return fallback
+ const error = (parsed as { error?: unknown }).error
+ if (typeof error !== 'string' || !SAFE_REGISTRY_PROXY_ERROR_CODES.has(error)) return fallback
+ return { error }
+ } catch {
+ return fallback
+ }
+}
+
async function orgRegistryFetch<T>(path: string, init?: RequestInit): Promise<T> {
const res = await authedFetch(path, init)
if (!res.ok) {
// A persistent 401 (authedFetch already evict-retried once) is a machine-token /
// integration fault, NOT the admin's session — remap to 502 at the transport so
// every caller is protected and control-ui never force-logs-out on it. A 403
- // (e.g. tenant client lacks registry:grant) is a real authz signal, forwarded verbatim.
+ // (e.g. tenant client lacks registry:grant) keeps its status and, when known,
+ // its safe typed code.
if (res.status === 401) {
+ await discardResponseBody(res)
throw new RegistryProxyError(502, { error: 'registry_integration_error' })
}
- const text = await res.text()
- let body: unknown
- try {
- // Preserve the registry's typed { error:<code> } body verbatim; a non-JSON error
- // body (HTML gateway page, plaintext) collapses to a synthetic code rather than
- // reflecting arbitrary upstream markup as the machine-readable error.
- body = text ? JSON.parse(text) : { error: `registry_${res.status}` }
- } catch {
- body = { error: `registry_${res.status}` }
- }
- throw new RegistryProxyError(res.status, body)
+ throw new RegistryProxyError(res.status, await registryProxyErrorBody(res))
}
// Empty body (204 or any empty 2xx) → undefined. A non-empty non-JSON 2xx body is an
// integration fault, surfaced as a typed 502 rather than a raw SyntaxError → 500.
diff --git a/control-api/src/services/registryMutation.ts b/control-api/src/services/registryMutation.ts
index 420f3f597..d19ca285d 100644
--- a/control-api/src/services/registryMutation.ts
+++ b/control-api/src/services/registryMutation.ts
@@ -4,6 +4,7 @@ export const REGISTRY_OPERATION_ID_ANNOTATION = 'clerum.io/registry-operation-id
export const REGISTRY_SPEC_DIGEST_ANNOTATION = 'clerum.io/registry-spec-sha256'
export type RegistryMutationOutcome = 'committed' | 'not-committed' | 'ambiguous'
+export type RegistryMutationReadbackOutcome = 'committed' | 'ambiguous'
export type RegistryResourceSnapshot = {
metadata?: {
@@ -48,38 +49,6 @@ export function registrySpecDigest(spec: Record<string, unknown>): string {
return createHash('sha256').update(canonicalRegistryJson(spec)).digest('hex')
}
-/**
- * Classify a create response that may have been lost after the object committed.
- *
- * `committed` here means that the observed object carries this operation's complete
- * intent. A create readback has no pre-write UID to compare against, so it does NOT
- * prove that the observed UID is the object created by this request. Callers may use
- * the result to finish an idempotent success, but must mark the snapshot as
- * non-compensable until a direct create response supplied its identity.
- */
-export function classifyCreatedRegistryMutationReadback(input: {
- current: RegistryResourceSnapshot | null
- desired: RegistryMutationDesired
- operationId: string
-}): RegistryMutationOutcome {
- const metadata = input.current?.metadata
- if (
- !metadata ||
- typeof metadata.uid !== 'string' ||
- typeof metadata.resourceVersion !== 'string'
- ) {
- return 'ambiguous'
- }
- if (metadata.annotations?.[REGISTRY_OPERATION_ID_ANNOTATION] !== input.operationId) {
- return 'ambiguous'
- }
- if (registrySpecDigest(input.current?.spec ?? {}) !== input.desired.specDigest) {
- return 'ambiguous'
- }
- if (!metadataSubsetMatches(metadata, input.desired.metadata)) return 'ambiguous'
- return 'committed'
-}
-
function metadataSubsetMatches(
current: RegistryResourceSnapshot['metadata'],
expected: RegistryResourceSnapshot['metadata']
@@ -105,7 +74,7 @@ export function classifyRegistryMutationReadback(input: {
desired: RegistryMutationDesired
current: RegistryResourceSnapshot
operationId: string
-}): RegistryMutationOutcome {
+}): RegistryMutationReadbackOutcome {
const beforeMeta = input.before.metadata
const currentMeta = input.current.metadata
if (!beforeMeta?.uid || !beforeMeta.resourceVersion || !currentMeta?.uid) return 'ambiguous'
@@ -135,7 +104,7 @@ export function classifyRegistryAssociationReadback(input: {
before: RegistryResourceSnapshot
current: RegistryResourceSnapshot | null
isCommitted: (spec: Record<string, unknown>) => boolean
-}): RegistryMutationOutcome {
+}): RegistryMutationReadbackOutcome {
const beforeMeta = input.before.metadata
const currentMeta = input.current?.metadata
if (
@@ -153,11 +122,5 @@ export function classifyRegistryAssociationReadback(input: {
) {
return 'committed'
}
- if (
- currentMeta.resourceVersion === beforeMeta.resourceVersion &&
- registrySpecDigest(input.current?.spec ?? {}) === registrySpecDigest(input.before.spec ?? {})
- ) {
- return 'not-committed'
- }
return 'ambiguous'
}
diff --git a/control-api/src/services/resourceService.ts b/control-api/src/services/resourceService.ts
index 9aa4925ad..723e864bf 100644
--- a/control-api/src/services/resourceService.ts
+++ b/control-api/src/services/resourceService.ts
@@ -333,9 +333,11 @@ export class ResourceService {
const intent = await persistHostIntent({ plural, action: 'update', namespace: ns, name })
const readerUid = body.metadata?.uid || undefined
const readerResourceVersion = body.metadata?.resourceVersion || undefined
- // With a reader-supplied precondition a retry can never succeed with the
- // same payload, so the loop collapses to a single attempt.
- const maxAttempts = readerResourceVersion || readerUid ? 1 : 3
+ // A reader resourceVersion freezes the caller's edit and must not be retried:
+ // re-reading then replaying that stale payload would lose a concurrent update.
+ // A UID alone guards only against same-name delete/recreate, so it keeps the
+ // legacy bounded retry contract while every fresh read revalidates identity.
+ const maxAttempts = readerResourceVersion ? 1 : 3
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
const current = (
attempt === 1 && options?.preReadCurrent
@@ -382,7 +384,7 @@ export class ResourceService {
metadata: {
name,
namespace: ns,
- ...(readerUid && current.metadata?.uid ? { uid: current.metadata.uid } : {}),
+ ...(readerUid ? { uid: readerUid } : {}),
...(current.metadata?.labels && { labels: current.metadata.labels }),
...(sanitizedMetadata?.labels && { labels: sanitizedMetadata.labels }),
...(annotations && { annotations }),
diff --git a/control-api/src/services/secretConstraints.ts b/control-api/src/services/secretConstraints.ts
index a606ab38d..d07eeb432 100644
--- a/control-api/src/services/secretConstraints.ts
+++ b/control-api/src/services/secretConstraints.ts
@@ -1,4 +1,5 @@
import { SecretUpsertRequest } from '../types.js'
+import { REGISTRY_OPERATION_ID_ANNOTATION } from './registryMutation.js'
export const ALLOWED_SECRET_TYPES: readonly string[] = [
'Opaque',
@@ -6,6 +7,18 @@ export const ALLOWED_SECRET_TYPES: readonly string[] = [
'kubernetes.io/dockerconfigjson',
]
+/**
+ * Existing Secret types are normally safe to preserve. These are the narrow
+ * exceptions whose lifecycle is owned by Kubernetes bootstrap controllers or
+ * Helm, so control-api must not mutate their data or metadata. In particular,
+ * basic-auth, ssh-auth, and custom types remain valid preserved state.
+ */
+const NON_MUTABLE_PRESERVED_SECRET_TYPES: readonly string[] = [
+ 'kubernetes.io/service-account-token',
+ 'bootstrap.kubernetes.io/token',
+ 'helm.sh/release.v1',
+]
+
const INFRA_ANNOTATION_PREFIXES: readonly string[] = [
'kubectl.kubernetes.io/',
'kubernetes.io/',
@@ -29,7 +42,7 @@ export const REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS = [
] as const
/** Operation marker used only by the internal Registry mutation capability. */
-export const REGISTRY_SECRET_OPERATION_ID_ANNOTATION = 'clerum.io/registry-operation-id'
+export const REGISTRY_SECRET_OPERATION_ID_ANNOTATION = REGISTRY_OPERATION_ID_ANNOTATION
/** Platform keys a public Registry credential rotation may preserve, never assign. */
export const REGISTRY_SECRET_ROTATION_PRESERVED_ANNOTATION_KEYS = [
@@ -84,6 +97,10 @@ function secretTypeErrorMessage(type: string): string {
return `Secret type "${type}" is not allowed; must be one of: ${ALLOWED_SECRET_TYPES.join(', ')}`
}
+function managedSecretTypeErrorMessage(type: string): string {
+ return `Secret type "${type}" is managed by Kubernetes or Helm and cannot be mutated`
+}
+
function annotationKeyErrorMessage(key: string, prefixes: readonly string[]): string {
return `annotation key "${key}" is not allowed: keys starting with ${prefixes.map(p => `"${p}"`).join(' or ')} are reserved`
}
@@ -91,8 +108,8 @@ function annotationKeyErrorMessage(key: string, prefixes: readonly string[]): st
export class InvalidSecretTypeError extends Error {
readonly status = 400
readonly type: string
- constructor(type: string) {
- super(secretTypeErrorMessage(type))
+ constructor(type: string, message = secretTypeErrorMessage(type)) {
+ super(message)
this.name = 'InvalidSecretTypeError'
this.type = type
}
@@ -124,27 +141,18 @@ export function dangerousAnnotationKeyReason(
: null
}
-/**
- * Existing infrastructure metadata is preserved as an opaque server-owned
- * value. It is not a caller assignment, so it is safe to carry through a
- * mutation; platform metadata remains constrained by capability or an exact
- * preservation allowlist.
- */
-export function existingSecretAnnotationKeyReason(
- key: string,
- opts?: SecretConstraintOptions
-): string | null {
- if (isInfrastructureAnnotationKey(key)) return null
- if (opts?.allowExistingPlatformAnnotationKeys?.includes(key)) return null
- return dangerousAnnotationKeyReason(key, opts)
-}
-
export function assertValidSecretType(type: string): void {
if (invalidSecretTypeReason(type) !== null) {
throw new InvalidSecretTypeError(type)
}
}
+export function assertMutablePreservedSecretType(type: string | undefined): void {
+ if (type !== undefined && NON_MUTABLE_PRESERVED_SECRET_TYPES.includes(type)) {
+ throw new InvalidSecretTypeError(type, managedSecretTypeErrorMessage(type))
+ }
+}
+
export function assertValidSecretAnnotations(
annotations: Record<string, string> | undefined,
opts?: SecretConstraintOptions,
@@ -166,55 +174,23 @@ export function assertValidSecretAnnotations(
}
}
-/**
- * Validate metadata already present on an existing Secret. Public mutation
- * routes may preserve a narrow, verified platform-owned annotation pair, but
- * their request payloads remain subject to assertValidSecretAnnotations().
- */
-export function assertValidExistingSecretAnnotations(
- annotations: Record<string, string> | undefined,
- opts?: SecretConstraintOptions
-): void {
- // Existing platform metadata is opaque state owned by the component that
- // wrote it. A data-only mutation does not claim or rewrite that metadata, so
- // an unknown/future `clerum.io/` key must not brick future rotations. The
- // transition validator above still rejects a caller that introduces or
- // changes a reserved key; this function intentionally validates no existing
- // key in isolation.
- void annotations
- void opts
-}
-
export function assertValidSecretConstraints(
req: SecretUpsertRequest,
opts?: SecretConstraintOptions,
existingAnnotations?: Record<string, string>
): void {
- // Type validation fires only on explicit type assignment. When req.type is
- // undefined, the write method defaults to 'Opaque' (create) or preserves
- // the existing type (update/merge) — no attacker-controlled type enters.
+ // The allowlist applies only to an explicit caller assignment. A preserved
+ // type is checked separately against the narrow controller-owned denylist.
if (req.type !== undefined) {
assertValidSecretType(req.type)
}
assertValidSecretAnnotations(req.annotations, opts, existingAnnotations)
}
-/** Validate the complete state that a mutation will leave behind. */
-export function assertValidEffectiveSecretConstraints(
- req: SecretUpsertRequest,
- opts?: SecretConstraintOptions
-): void {
- if (req.type !== undefined) {
- assertValidSecretType(req.type)
- }
- assertValidExistingSecretAnnotations(req.annotations, opts)
-}
-
/**
* Resolve the annotation map a full replacement is allowed to leave behind.
- * Caller-owned keys retain full-replace semantics. Infrastructure metadata is
- * transport-only, while platform metadata is either capability-owned or an
- * exact existing-key preservation granted to a narrow partial writer.
+ * Requested reserved keys must match the live value; omitted protected keys
+ * are carried forward. Caller-owned keys retain full-replace semantics.
*/
export function resolveSecretAnnotationsForReplace(
existingAnnotations: Record<string, string> | undefined,
@@ -226,7 +202,6 @@ export function resolveSecretAnnotationsForReplace(
}
assertValidSecretAnnotations(requestedAnnotations, opts, existingAnnotations)
- assertValidExistingSecretAnnotations(existingAnnotations, opts)
const resolved: Record<string, string> = { ...requestedAnnotations }
for (const [key, value] of Object.entries(existingAnnotations ?? {})) {
diff --git a/control-api/src/services/secretReferenceService.ts b/control-api/src/services/secretReferenceService.ts
index 4601e0be6..f5bdce767 100644
--- a/control-api/src/services/secretReferenceService.ts
+++ b/control-api/src/services/secretReferenceService.ts
@@ -7,84 +7,288 @@ export type SecretReferenceReader = {
listResource: (plural: ClerumResourceType, namespace?: string) => Promise<unknown[]>
}
+export const SECRET_REFERENCE_CONTRACT_ANNOTATION = 'clerum.io/secret-reference-contract'
+export const SECRET_REFERENCE_CONTRACT_VERSION = 1
+
+/**
+ * Namespace resolution is part of a Secret reference's meaning. A matching
+ * name in another namespace is not a dependency and must not block a safe
+ * rollback.
+ */
+export type SecretReferenceNamespaceBinding =
+ | 'resource'
+ | 'host-secret'
+ | 'reference-value'
+ | 'workflow-recipe'
+ | 'workflow-workload'
+
+export type SecretReferenceFieldContract = {
+ path: string
+ namespaceBinding: SecretReferenceNamespaceBinding
+}
+
+export type SecretReferenceCrdContract = {
+ plural: string
+ fields: readonly SecretReferenceFieldContract[]
+}
+
+/**
+ * Runtime source of truth for Secret consumers. Each CRD carries the same
+ * versioned contract in metadata.annotations so schema changes cannot silently
+ * expand or shrink this cleanup boundary.
+ *
+ * Do not add a generic `*Ref` traversal here. Some CRDs expose ordinary
+ * resource references with the same shape, and treating those as Secret
+ * consumers would retain unrelated objects during compensation.
+ */
+export const SECRET_REFERENCE_CRD_CONTRACTS = [
+ {
+ plural: 'communicationchannels',
+ fields: [{ path: 'spec.credentialsSecretRef', namespaceBinding: 'resource' }],
+ },
+ { plural: 'contexts', fields: [] },
+ { plural: 'globalfilesystems', fields: [] },
+ {
+ plural: 'hosts',
+ fields: [{ path: 'spec.secretRef', namespaceBinding: 'host-secret' }],
+ },
+ {
+ plural: 'llmhooks',
+ fields: [
+ { path: 'spec.target.image.imagePullSecrets', namespaceBinding: 'resource' },
+ { path: 'spec.target.image.envSecret', namespaceBinding: 'resource' },
+ { path: 'spec.target.remote.authHeadersSecret', namespaceBinding: 'resource' },
+ ],
+ },
+ {
+ plural: 'mcpservers',
+ fields: [
+ { path: 'spec.auth.secretRef', namespaceBinding: 'resource' },
+ { path: 'spec.envSecret', namespaceBinding: 'resource' },
+ { path: 'spec.imagePullSecrets', namespaceBinding: 'resource' },
+ ],
+ },
+ { plural: 'sharedfilesystems', fields: [] },
+ { plural: 'workflowrecipepolicies', fields: [] },
+ {
+ plural: 'workflowrecipes',
+ fields: [
+ {
+ path: 'spec.agent.secretRef',
+ namespaceBinding: 'reference-value',
+ },
+ {
+ path: 'spec.steps[].run.capabilities.secrets[].secretRef',
+ namespaceBinding: 'workflow-recipe',
+ },
+ { path: 'spec.workloads[].envSecret', namespaceBinding: 'workflow-workload' },
+ {
+ path: 'spec.workloads[].imagePullSecrets',
+ namespaceBinding: 'workflow-workload',
+ },
+ {
+ path: 'spec.oauthClients[].clientIdRef',
+ namespaceBinding: 'workflow-recipe',
+ },
+ {
+ path: 'spec.oauthClients[].clientSecretRef',
+ namespaceBinding: 'workflow-recipe',
+ },
+ {
+ path: 'spec.webhooks[].verification.secretRef',
+ namespaceBinding: 'workflow-recipe',
+ },
+ {
+ path: 'spec.webhooks[].verification.setupHandshake.secretRef',
+ namespaceBinding: 'workflow-recipe',
+ },
+ ],
+ },
+] as const satisfies readonly SecretReferenceCrdContract[]
+
type ReferenceScope = {
plural: ClerumResourceType
resourceNamespace: string
- secretNamespace: string
+ fields: readonly SecretReferenceFieldContract[]
+}
+
+function fieldsFor(plural: string): readonly SecretReferenceFieldContract[] {
+ const contract = SECRET_REFERENCE_CRD_CONTRACTS.find(candidate => candidate.plural === plural)
+ if (!contract) throw new Error(`Missing Secret reference contract for CRD plural "${plural}"`)
+ return contract.fields
}
export const SECRET_REFERENCE_SCOPES = [
{
plural: 'mcpservers',
resourceNamespace: config.mcpServersNamespace,
- secretNamespace: config.mcpServersNamespace,
+ fields: fieldsFor('mcpservers'),
},
{
plural: 'llmhooks',
resourceNamespace: config.llmHooksNamespace,
- secretNamespace: config.llmHooksNamespace,
+ fields: fieldsFor('llmhooks'),
},
{
plural: 'workflowrecipes',
resourceNamespace: config.sandboxNamespace,
- secretNamespace: config.sandboxNamespace,
+ fields: fieldsFor('workflowrecipes'),
},
{
plural: 'hosts',
resourceNamespace: config.hostsNamespace,
- secretNamespace: config.secretsNamespace,
+ fields: fieldsFor('hosts'),
},
{
plural: 'communicationchannels',
resourceNamespace: config.communicationChannelsNamespace,
- secretNamespace: config.communicationChannelsNamespace,
+ fields: fieldsFor('communicationchannels'),
},
] as const satisfies readonly ReferenceScope[]
-const REFERENCE_SCOPES: readonly ReferenceScope[] = SECRET_REFERENCE_SCOPES
+const WORKFLOW_WORKLOAD_PATH_PREFIX = 'spec.workloads[].'
-// Explicitly enumerate every Secret-bearing field in the deployed CRD schemas.
-// A generic "*Ref" fallback would turn unrelated resource references into false
-// dependencies and make compensation behavior implicit. Keep this list aligned
-// with charts/clerum-crds/crds/{mcpserver,llmhook,workflowrecipe,communicationchannel,host}.yaml.
-export const SECRET_REFERENCE_FIELDS = [
- 'authHeadersSecret',
- 'credentialsSecretRef',
- 'envSecret',
- 'secretRef',
- 'imagePullSecrets',
- 'clientIdRef',
- 'clientSecretRef',
-] as const
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
-const REFERENCE_KEYS: ReadonlySet<string> = new Set(SECRET_REFERENCE_FIELDS)
+function valuesAtPath(value: unknown, path: string): unknown[] {
+ let values: unknown[] = [value]
-function isRecord(value: unknown): value is Record<string, unknown> {
- return typeof value === 'object' && value !== null
+ for (const token of path.split('.')) {
+ const isArray = token.endsWith('[]')
+ const key = isArray ? token.slice(0, -2) : token
+
+ values = values.flatMap(current => {
+ if (!isRecord(current) || !Object.hasOwn(current, key)) return []
+ const child = current[key]
+ if (isArray) return Array.isArray(child) ? child : []
+ return [child]
+ })
+ }
+
+ return values
}
function referenceValueMatches(value: unknown, name: string): boolean {
if (typeof value === 'string') return value === name
if (Array.isArray(value)) return value.some(item => referenceValueMatches(item, name))
- if (!isRecord(value)) return false
- return value.name === name
+ return isRecord(value) && value.name === name
}
-function containsSecretReference(value: unknown, name: string, seen = new Set<object>()): boolean {
- if (typeof value !== 'object' || value === null) return false
- if (seen.has(value)) return false
- seen.add(value)
+function workflowWorkloadNamespace(
+ workload: Record<string, unknown>,
+ uiWorkloadRef: string | undefined
+): string {
+ // Keep this three-way split aligned with the WorkflowRecipe runtime's
+ // resolveWorkloadNamespace contract: transport → mcp-server, UI →
+ // sandbox-ui, all other workloads → sandbox-recipes.
+ if (workload.transport !== undefined && workload.transport !== null) {
+ return config.mcpServersNamespace
+ }
+ if (uiWorkloadRef && workload.id === uiWorkloadRef) return config.sandboxUiNamespace
+ return config.sandboxNamespace
+}
- if (Array.isArray(value)) {
- return value.some(item => containsSecretReference(item, name, seen))
+function workflowWorkloadReferenceMatches(
+ resource: unknown,
+ field: SecretReferenceFieldContract,
+ name: string,
+ namespace: string
+): boolean {
+ if (!field.path.startsWith(WORKFLOW_WORKLOAD_PATH_PREFIX)) {
+ throw new Error(`Invalid workflow-workload Secret reference path "${field.path}"`)
}
- return Object.entries(value).some(([key, child]) => {
- if (REFERENCE_KEYS.has(key) && referenceValueMatches(child, name)) return true
- return containsSecretReference(child, name, seen)
+ const [uiWorkloadRef] = valuesAtPath(resource, 'spec.ui.workloadRef')
+ const uiRef = typeof uiWorkloadRef === 'string' ? uiWorkloadRef : undefined
+ const relativePath = field.path.slice(WORKFLOW_WORKLOAD_PATH_PREFIX.length)
+
+ return valuesAtPath(resource, 'spec.workloads[]').some(workload => {
+ if (!isRecord(workload) || workflowWorkloadNamespace(workload, uiRef) !== namespace)
+ return false
+ return valuesAtPath(workload, relativePath).some(value => referenceValueMatches(value, name))
})
}
+function namespaceBindingApplies(
+ binding: SecretReferenceNamespaceBinding,
+ resourceNamespace: string,
+ namespace: string
+): boolean {
+ switch (binding) {
+ case 'resource':
+ return resourceNamespace === namespace
+ case 'host-secret':
+ return config.secretsNamespace === namespace
+ case 'reference-value':
+ return [
+ config.secretsNamespace,
+ config.sandboxNamespace,
+ config.mcpServersNamespace,
+ config.sandboxUiNamespace,
+ config.llmHooksNamespace,
+ config.communicationChannelsNamespace,
+ ].includes(namespace)
+ case 'workflow-recipe':
+ return config.sandboxNamespace === namespace
+ case 'workflow-workload':
+ return (
+ namespace === config.sandboxNamespace ||
+ namespace === config.mcpServersNamespace ||
+ namespace === config.sandboxUiNamespace
+ )
+ }
+}
+
+function fieldReferencesSecret(
+ resource: unknown,
+ field: SecretReferenceFieldContract,
+ name: string,
+ namespace: string
+): boolean {
+ if (field.namespaceBinding === 'reference-value') {
+ return valuesAtPath(resource, field.path).some(value => {
+ if (typeof value === 'string') {
+ return value === name && namespace === config.secretsNamespace
+ }
+ if (!isRecord(value) || value.name !== name) return false
+ const referencedNamespace =
+ typeof value.namespace === 'string' && value.namespace.trim()
+ ? value.namespace
+ : config.secretsNamespace
+ return referencedNamespace === namespace
+ })
+ }
+ if (field.namespaceBinding === 'workflow-workload') {
+ return workflowWorkloadReferenceMatches(resource, field, name, namespace)
+ }
+ return valuesAtPath(resource, field.path).some(value => referenceValueMatches(value, name))
+}
+
+function validateRuntimeContract(): void {
+ const declaredPlurals = new Set<string>()
+ for (const contract of SECRET_REFERENCE_CRD_CONTRACTS) {
+ if (declaredPlurals.has(contract.plural)) {
+ throw new Error(`Duplicate Secret reference contract for CRD plural "${contract.plural}"`)
+ }
+ declaredPlurals.add(contract.plural)
+ }
+
+ for (const scope of SECRET_REFERENCE_SCOPES) {
+ for (const field of scope.fields) {
+ if (
+ field.namespaceBinding === 'workflow-workload' &&
+ !field.path.startsWith(WORKFLOW_WORKLOAD_PATH_PREFIX)
+ ) {
+ throw new Error(`Invalid workflow-workload Secret reference path "${field.path}"`)
+ }
+ }
+ }
+}
+
+validateRuntimeContract()
+
/**
* Check every CRD family that can consume a namespaced Secret. A failed list is
* deliberately `unknown`: compensation must preserve the object when the
@@ -95,17 +299,24 @@ export async function findSecretReferenceState(
name: string,
namespace: string
): Promise<SecretReferenceState> {
- const scopes = REFERENCE_SCOPES.filter(scope => scope.secretNamespace === namespace)
- if (scopes.length === 0) return 'unknown'
+ const applicableScopes = SECRET_REFERENCE_SCOPES.map(scope => ({
+ ...scope,
+ fields: scope.fields.filter(field =>
+ namespaceBindingApplies(field.namespaceBinding, scope.resourceNamespace, namespace)
+ ),
+ })).filter(scope => scope.fields.length > 0)
+
+ if (applicableScopes.length === 0) return 'unknown'
try {
const resourceLists = await Promise.all(
- scopes.map(scope => reader.listResource(scope.plural, scope.resourceNamespace))
+ applicableScopes.map(scope => reader.listResource(scope.plural, scope.resourceNamespace))
)
- for (const resources of resourceLists) {
+ for (const [index, resources] of resourceLists.entries()) {
+ const { fields } = applicableScopes[index]
if (
resources.some(resource =>
- containsSecretReference((resource as { spec?: unknown }).spec, name)
+ fields.some(field => fieldReferencesSecret(resource, field, name, namespace))
)
) {
return 'referenced'
diff --git a/control-api/src/services/secretRepository.ts b/control-api/src/services/secretRepository.ts
index 3a187be6c..bde2b5e8e 100644
--- a/control-api/src/services/secretRepository.ts
+++ b/control-api/src/services/secretRepository.ts
@@ -1,5 +1,4 @@
-import type { SecretPreconditions, SecretUpsertRequest } from '../types.js'
-import type { SecretConstraintOptions } from './secretConstraints.js'
+import type { SecretPreconditions } from '../types.js'
/** The subset of a Kubernetes Secret that callers are allowed to observe. */
export interface SecretResource {
@@ -35,32 +34,6 @@ export interface SecretSnapshot {
stringData?: Record<string, string>
}
-/** Typed boundary for every Secret mutation used by control-api. */
-export interface SecretRepository {
- listSecrets(namespace?: string): Promise<unknown[]>
- getSecret(name: string, namespace?: string): Promise<SecretResource>
- createSecret(req: SecretUpsertRequest, opts?: SecretConstraintOptions): Promise<SecretSnapshot>
- updateSecret(
- req: SecretUpsertRequest,
- precondition?: SecretPreconditions,
- opts?: SecretConstraintOptions
- ): Promise<SecretSnapshot>
- mergeSecret(
- req: SecretUpsertRequest,
- opts?: SecretConstraintOptions,
- precondition?: SecretPreconditions
- ): Promise<SecretSnapshot>
- removeSecretKey(
- req: { name: string; namespace?: string; key: string },
- precondition?: SecretPreconditions
- ): Promise<SecretSnapshot>
- deleteSecret(
- name: string,
- namespace?: string,
- precondition?: SecretPreconditions
- ): Promise<unknown>
-}
-
/** Convert an apiserver response into the only mutation result callers may use for CAS. */
export function toSecretSnapshot(
raw: unknown,
diff --git a/control-api/src/services/secretService.ts b/control-api/src/services/secretService.ts
index a9afbcfac..034916fa8 100644
--- a/control-api/src/services/secretService.ts
+++ b/control-api/src/services/secretService.ts
@@ -2,10 +2,10 @@ import * as k8s from '@kubernetes/client-node'
import { SecretPreconditions, SecretUpsertRequest } from '../types.js'
import {
type SecretConstraintOptions,
- assertValidEffectiveSecretConstraints,
+ assertMutablePreservedSecretType,
+ assertValidSecretAnnotations,
assertValidSecretConstraints,
assertValidSecretType,
- isInfrastructureAnnotationKey,
resolveSecretAnnotationsForReplace,
} from './secretConstraints.js'
import { assertValidSecretDataKey, assertValidSecretWriteKeys } from './secretKeys.js'
@@ -167,19 +167,12 @@ export class SecretService {
precondition?: SecretPreconditions,
opts?: SecretConstraintOptions
): Promise<unknown> {
- const hasInfrastructureAnnotations = Object.keys(req.annotations ?? {}).some(
- isInfrastructureAnnotationKey
- )
- const carriesInternalInfrastructure =
- hasInfrastructureAnnotations && opts?.capability !== undefined
- if (!carriesInternalInfrastructure) {
- assertValidSecretConstraints(req, opts)
- } else if (req.type !== undefined) {
- assertValidSecretType(req.type)
- }
+ if (req.type !== undefined) assertValidSecretType(req.type)
assertValidSecretWriteKeys(req)
const ns = req.namespace || this.defaultNamespace
const existing = await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
+ assertMutablePreservedSecretType(existing.type)
+ assertValidSecretAnnotations(req.annotations, opts, existing.metadata?.annotations)
const effectiveAnnotations = resolveSecretAnnotationsForReplace(
existing?.metadata?.annotations,
req.annotations,
@@ -203,25 +196,14 @@ export class SecretService {
: {}),
...(existing?.metadata?.finalizers ? { finalizers: existing.metadata.finalizers } : {}),
},
- type: req.type || existing?.type || 'Opaque',
+ type: req.type ?? existing?.type ?? 'Opaque',
data: req.data,
stringData: req.stringData,
...(typeof existing?.immutable === 'boolean' ? { immutable: existing.immutable } : {}),
}
- // Validate the complete replacement state, not only fields explicitly
- // supplied by the caller. An existing Secret may predate these constraints;
- // allowing an omitted type/annotation field to preserve a forbidden value
- // would make updateSecret a write-path bypass.
- assertValidEffectiveSecretConstraints(
- {
- name: req.name,
- type: body.type,
- annotations: body.metadata?.annotations,
- },
- opts
- )
-
+ // Explicit types passed the write allowlist above. A preserved type is
+ // mutable unless it belongs to a Kubernetes or Helm-managed Secret.
const replaced = await this.coreApi.replaceNamespacedSecret({
namespace: ns,
name: req.name,
@@ -279,23 +261,14 @@ export class SecretService {
assertValidSecretWriteKeys(req)
const ns = req.namespace || this.defaultNamespace
const existing = await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
+ assertMutablePreservedSecretType(existing.type)
+ assertValidSecretAnnotations(req.annotations, opts, existing.metadata?.annotations)
const effectiveAnnotations = resolveSecretAnnotationsForReplace(
existing.metadata?.annotations,
req.annotations,
opts
)
- // Merge-patch preserves fields omitted from the patch. Validate those
- // preserved fields as part of the effective target state before mutating.
- assertValidEffectiveSecretConstraints(
- {
- name: req.name,
- type: req.type ?? existing.type ?? 'Opaque',
- annotations: effectiveAnnotations,
- },
- opts
- )
-
const body: Partial<k8s.V1Secret> = {}
if (req.stringData !== undefined) body.stringData = req.stringData
if (req.data !== undefined) body.data = req.data
@@ -371,19 +344,10 @@ export class SecretService {
assertValidSecretDataKey(req.key)
const ns = req.namespace || this.defaultNamespace
const existing = await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
- const effectiveAnnotations = resolveSecretAnnotationsForReplace(
- existing.metadata?.annotations,
- undefined
- )
- // Removing one data key still mutates the Secret. Preserve unchanged
- // infrastructure metadata while applying the same effective-state checks
- // as the other mutation paths.
- assertValidEffectiveSecretConstraints({
- name: req.name,
- type: existing.type ?? 'Opaque',
- annotations: effectiveAnnotations,
- })
+ // Removing one data key still mutates the Secret, so controller-owned
+ // Secret types remain off limits here too.
+ assertMutablePreservedSecretType(existing.type ?? 'Opaque')
const body = {
...(precondition && {
diff --git a/control-api/src/utils/auth/mcpSecretDeleteProof.ts b/control-api/src/utils/auth/mcpSecretDeleteProof.ts
new file mode 100644
index 000000000..16bbf8deb
--- /dev/null
+++ b/control-api/src/utils/auth/mcpSecretDeleteProof.ts
@@ -0,0 +1,124 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+export const MCP_SECRET_DELETE_PROOF_TTL_SECONDS = 120
+
+export type McpSecretDeleteProofInput = {
+ name: string
+ namespace: string
+ uid: string
+ resourceVersion: string
+}
+
+export type McpSecretDeleteProofClaims = McpSecretDeleteProofInput & {
+ exp: number
+}
+
+const CLAIM_KEYS = ['name', 'namespace', 'uid', 'resourceVersion', 'exp'] as const
+const COOKIE_NAME_PREFIX = 'mcp_secret_delete_proof_'
+
+function isNonEmptyString(value: unknown): value is string {
+ return typeof value === 'string' && value.trim().length > 0
+}
+
+function encodeClaims(claims: McpSecretDeleteProofClaims): string {
+ return Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url')
+}
+
+function sign(encodedClaims: string, sessionKey: string): Buffer {
+ return createHmac('sha256', sessionKey).update(encodedClaims, 'utf8').digest()
+}
+
+function parseClaims(encodedClaims: string): McpSecretDeleteProofClaims | null {
+ if (!/^[A-Za-z0-9_-]+$/.test(encodedClaims)) return null
+
+ let raw: unknown
+ try {
+ const decoded = Buffer.from(encodedClaims, 'base64url')
+ if (decoded.toString('base64url') !== encodedClaims) return null
+ raw = JSON.parse(decoded.toString('utf8'))
+ } catch {
+ return null
+ }
+
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+ const claims = raw as Record<string, unknown>
+ if (
+ Object.keys(claims).length !== CLAIM_KEYS.length ||
+ !CLAIM_KEYS.every(key => Object.prototype.hasOwnProperty.call(claims, key)) ||
+ !isNonEmptyString(claims.name) ||
+ !isNonEmptyString(claims.namespace) ||
+ !isNonEmptyString(claims.uid) ||
+ !isNonEmptyString(claims.resourceVersion) ||
+ typeof claims.exp !== 'number' ||
+ !Number.isSafeInteger(claims.exp)
+ ) {
+ return null
+ }
+
+ return {
+ name: claims.name,
+ namespace: claims.namespace,
+ uid: claims.uid,
+ resourceVersion: claims.resourceVersion,
+ exp: claims.exp,
+ }
+}
+
+export function mcpSecretDeleteProofCookieName(name: string): string {
+ return `${COOKIE_NAME_PREFIX}${Buffer.from(name, 'utf8').toString('base64url')}`
+}
+
+export function createMcpSecretDeleteProof(
+ input: McpSecretDeleteProofInput,
+ sessionKey: string
+): string {
+ if (!sessionKey) throw new Error('Admin session is required to issue an MCP Secret delete proof')
+
+ const claims: McpSecretDeleteProofClaims = {
+ name: input.name,
+ namespace: input.namespace,
+ uid: input.uid,
+ resourceVersion: input.resourceVersion,
+ exp: Math.floor(Date.now() / 1000) + MCP_SECRET_DELETE_PROOF_TTL_SECONDS,
+ }
+ const encodedClaims = encodeClaims(claims)
+ return `${encodedClaims}.${sign(encodedClaims, sessionKey).toString('base64url')}`
+}
+
+export function verifyMcpSecretDeleteProof(
+ proof: string,
+ sessionKey: string
+): McpSecretDeleteProofClaims | null {
+ if (!proof || !sessionKey) return null
+
+ const [encodedClaims, encodedSignature, ...rest] = proof.split('.')
+ if (
+ !encodedClaims ||
+ !encodedSignature ||
+ rest.length > 0 ||
+ !/^[A-Za-z0-9_-]+$/.test(encodedSignature)
+ ) {
+ return null
+ }
+
+ const claims = parseClaims(encodedClaims)
+ if (!claims) return null
+
+ let suppliedSignature: Buffer
+ try {
+ suppliedSignature = Buffer.from(encodedSignature, 'base64url')
+ } catch {
+ return null
+ }
+ const expectedSignature = sign(encodedClaims, sessionKey)
+ if (
+ suppliedSignature.length !== expectedSignature.length ||
+ suppliedSignature.toString('base64url') !== encodedSignature ||
+ !timingSafeEqual(suppliedSignature, expectedSignature)
+ ) {
+ return null
+ }
+
+ if (claims.exp <= Math.floor(Date.now() / 1000)) return null
+ return claims
+}
diff --git a/control-api/test/crd.secretReferenceCoverage.test.ts b/control-api/test/crd.secretReferenceCoverage.test.ts
index 6bdea7a56..43b9e81f7 100644
--- a/control-api/test/crd.secretReferenceCoverage.test.ts
+++ b/control-api/test/crd.secretReferenceCoverage.test.ts
@@ -4,15 +4,55 @@ import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { parse } from 'yaml'
import {
- SECRET_REFERENCE_FIELDS,
+ SECRET_REFERENCE_CONTRACT_ANNOTATION,
+ SECRET_REFERENCE_CONTRACT_VERSION,
+ SECRET_REFERENCE_CRD_CONTRACTS,
SECRET_REFERENCE_SCOPES,
+ type SecretReferenceCrdContract,
+ type SecretReferenceFieldContract,
+ type SecretReferenceNamespaceBinding,
} from '../src/services/secretReferenceService.js'
const crdsDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../charts/clerum-crds/crds')
+const namespaceBindings = new Set<SecretReferenceNamespaceBinding>([
+ 'resource',
+ 'host-secret',
+ 'reference-value',
+ 'workflow-recipe',
+ 'workflow-workload',
+])
+
+/**
+ * Every schema field whose name looks reference/credential-related must be
+ * classified. These paths are explicitly non-Secret references (or keys
+ * inside an already-contracted Secret reference). A new `*Ref`, `*Secret`, or
+ * `*Credential*` field therefore fails closed until a reviewer puts it in the
+ * runtime contract or this narrow exclusion inventory.
+ */
+const NON_SECRET_REFERENCE_PATHS = new Set([
+ 'communicationchannel.yaml:spec.hostRef',
+ 'host.yaml:spec.contextRef',
+ 'host.yaml:spec.llmPolicy.fallbacks[].credentialSlot',
+ 'llmhook.yaml:spec.target.image.ref',
+ 'mcpserver.yaml:spec.auth.secretKey',
+ 'mcpserver.yaml:spec.contextRef',
+ 'mcpserver.yaml:spec.envSecret.keys[].secretKey',
+ 'workflowrecipe.yaml:spec.agent.soulRef',
+ 'workflowrecipe.yaml:spec.agent.soulRef.storageRef',
+ 'workflowrecipe.yaml:spec.contextRef',
+ 'workflowrecipe.yaml:spec.security.allowContextRef',
+ 'workflowrecipe.yaml:spec.steps[].run.capabilities.secrets',
+ 'workflowrecipe.yaml:spec.ui.egress.internal[].workloadRef',
+ 'workflowrecipe.yaml:spec.ui.workloadRef',
+ 'workflowrecipe.yaml:spec.webhooks[].workloadRef',
+ 'workflowrecipe.yaml:spec.workloads[].envSecret.keys[].secretKey',
+ 'workflowrecipe.yaml:status.pluginWorkloadSdk.defaultTargetRef',
+ 'workflowrecipepolicy.yaml:spec.allowContextRef',
+])
+
type OpenApiSchema = {
description?: unknown
- type?: unknown
properties?: unknown
items?: unknown
allOf?: unknown
@@ -20,73 +60,382 @@ type OpenApiSchema = {
oneOf?: unknown
}
+type CrdSource = {
+ file: string
+ document: Record<string, unknown>
+}
+
+type ParsedCrd = CrdSource & {
+ plural: string
+ schemas: OpenApiSchema[]
+}
+
function asRecord(value: unknown): Record<string, unknown> | undefined {
return value && typeof value === 'object' && !Array.isArray(value)
? (value as Record<string, unknown>)
: undefined
}
-function schemaDeclaresSecretReference(fieldName: string, schema: OpenApiSchema): boolean {
- if (fieldName === 'imagePullSecrets') return true
+function normalizeContracts(
+ contracts: readonly SecretReferenceCrdContract[]
+): Array<{ plural: string; fields: SecretReferenceFieldContract[] }> {
+ return contracts
+ .map(contract => ({
+ plural: contract.plural,
+ fields: [...contract.fields].sort(
+ (left, right) =>
+ left.path.localeCompare(right.path) ||
+ left.namespaceBinding.localeCompare(right.namespaceBinding)
+ ),
+ }))
+ .sort((left, right) => left.plural.localeCompare(right.plural))
+}
- const description = typeof schema.description === 'string' ? schema.description : ''
- if (!/\bSecret\b/.test(description) || /secret.*key$/i.test(fieldName)) return false
- if (/secret/i.test(fieldName)) return true
- if (!fieldName.endsWith('Ref')) return false
+function loadCrdSources(): CrdSource[] {
+ return readdirSync(crdsDir)
+ .filter(file => file.endsWith('.yaml'))
+ .sort()
+ .map(file => {
+ const document = asRecord(parse(readFileSync(resolve(crdsDir, file), 'utf8')))
+ if (!document) throw new Error(`Invalid CRD document: ${file}`)
+ return { file, document }
+ })
+}
+
+function parseCrd(source: CrdSource, errors: string[]): ParsedCrd | undefined {
+ const metadata = asRecord(source.document.metadata)
+ const spec = asRecord(source.document.spec)
+ const names = asRecord(spec?.names)
+ const plural = typeof names?.plural === 'string' ? names.plural : undefined
+ const versions = spec?.versions
+ if (!metadata || !spec || !plural || !Array.isArray(versions)) {
+ errors.push(`${source.file}: invalid CRD metadata, names.plural, or versions`)
+ return undefined
+ }
- const properties = asRecord(schema.properties)
- return schema.type === 'string' || properties?.name !== undefined
+ const schemas = versions.flatMap((version, index) => {
+ const schema = asRecord(asRecord(asRecord(version)?.schema)?.openAPIV3Schema)
+ if (!schema) {
+ errors.push(`${source.file}: version ${index} has no openAPIV3Schema`)
+ return []
+ }
+ return [schema]
+ })
+
+ return { ...source, plural, schemas }
}
-function collectSecretReferenceFields(schema: unknown, fields: Set<string>): void {
- const record = asRecord(schema)
- if (!record) return
+function isContractPath(path: string): boolean {
+ return /^spec(?:\.[A-Za-z][A-Za-z0-9]*(?:\[\])?)+$/.test(path)
+}
- const properties = asRecord(record.properties)
- if (properties) {
- for (const [fieldName, value] of Object.entries(properties)) {
- const fieldSchema = asRecord(value) as OpenApiSchema | undefined
- if (fieldSchema && schemaDeclaresSecretReference(fieldName, fieldSchema)) {
- fields.add(fieldName)
- }
- collectSecretReferenceFields(value, fields)
+function isNamespaceBinding(value: unknown): value is SecretReferenceNamespaceBinding {
+ return (
+ typeof value === 'string' && namespaceBindings.has(value as SecretReferenceNamespaceBinding)
+ )
+}
+
+function parseCrdContract(
+ crd: ParsedCrd,
+ errors: string[]
+): SecretReferenceCrdContract | undefined {
+ const annotations = asRecord(asRecord(crd.document.metadata)?.annotations)
+ const rawContract = annotations?.[SECRET_REFERENCE_CONTRACT_ANNOTATION]
+ if (typeof rawContract !== 'string') {
+ errors.push(`${crd.file}: missing ${SECRET_REFERENCE_CONTRACT_ANNOTATION} annotation`)
+ return undefined
+ }
+
+ let value: unknown
+ try {
+ value = JSON.parse(rawContract)
+ } catch {
+ errors.push(`${crd.file}: ${SECRET_REFERENCE_CONTRACT_ANNOTATION} must contain JSON`)
+ return undefined
+ }
+
+ const contract = asRecord(value)
+ if (!contract || contract.version !== SECRET_REFERENCE_CONTRACT_VERSION) {
+ errors.push(
+ `${crd.file}: ${SECRET_REFERENCE_CONTRACT_ANNOTATION} must declare version ${SECRET_REFERENCE_CONTRACT_VERSION}`
+ )
+ return undefined
+ }
+ if (typeof contract.plural !== 'string' || contract.plural.length === 0) {
+ errors.push(`${crd.file}: Secret reference contract must declare a plural`)
+ return undefined
+ }
+ if (!Array.isArray(contract.fields)) {
+ errors.push(`${crd.file}: Secret reference contract fields must be an array`)
+ return undefined
+ }
+
+ const fields: SecretReferenceFieldContract[] = []
+ const paths = new Set<string>()
+ contract.fields.forEach((value, index) => {
+ const field = asRecord(value)
+ const path = field?.path
+ const namespaceBinding = field?.namespaceBinding
+ if (
+ typeof path !== 'string' ||
+ !isContractPath(path) ||
+ !isNamespaceBinding(namespaceBinding)
+ ) {
+ errors.push(`${crd.file}: invalid Secret reference contract field at index ${index}`)
+ return
+ }
+ if (paths.has(path)) {
+ errors.push(`${crd.file}: duplicate Secret reference contract path ${path}`)
+ return
}
+ paths.add(path)
+ fields.push({ path, namespaceBinding })
+ })
+
+ return { plural: contract.plural, fields }
+}
+
+function schemaAtPath(schema: OpenApiSchema, path: string): OpenApiSchema | undefined {
+ let current: OpenApiSchema | undefined = schema
+ for (const token of path.split('.')) {
+ const isArray = token.endsWith('[]')
+ const fieldName = isArray ? token.slice(0, -2) : token
+ const properties = asRecord(current?.properties)
+ const field = asRecord(properties?.[fieldName])
+ if (!field) return undefined
+ current = isArray ? (asRecord(field.items) as OpenApiSchema | undefined) : field
+ if (!current) return undefined
}
+ return current
+}
+
+function hasDescription(schema: OpenApiSchema): boolean {
+ return typeof schema.description === 'string' && schema.description.trim().length > 0
+}
+
+/**
+ * The contract is the source of truth; this narrow structural check only keeps
+ * an obvious new credential-shaped object from being added without a contract.
+ * It deliberately ignores generic `{ name, key }` objects whose field name has
+ * no Secret/credential meaning, avoiding broad `*Ref` false positives.
+ */
+function isSecretReferenceCandidate(fieldName: string, schema: OpenApiSchema): boolean {
+ void schema
+ return /(secret|credential)/i.test(fieldName) || /ref$/i.test(fieldName)
+}
+
+function collectSecretReferenceCandidates(schema: OpenApiSchema, path = ''): string[] {
+ const candidates = new Set<string>()
+
+ const walk = (current: OpenApiSchema, prefix: string): void => {
+ const properties = asRecord(current.properties)
+ if (properties) {
+ for (const [fieldName, value] of Object.entries(properties)) {
+ const field = asRecord(value) as OpenApiSchema | undefined
+ if (!field) continue
+ const fieldPath = prefix ? `${prefix}.${fieldName}` : fieldName
+ if (isSecretReferenceCandidate(fieldName, field)) candidates.add(fieldPath)
+ walk(field, fieldPath)
+ }
+ }
- collectSecretReferenceFields(record.items, fields)
- for (const branch of [record.allOf, record.anyOf, record.oneOf]) {
- if (Array.isArray(branch)) branch.forEach(item => collectSecretReferenceFields(item, fields))
+ const items = asRecord(current.items) as OpenApiSchema | undefined
+ if (items) walk(items, `${prefix}[]`)
+ for (const branches of [current.allOf, current.anyOf, current.oneOf]) {
+ if (Array.isArray(branches)) {
+ branches.forEach(branch => {
+ const branchSchema = asRecord(branch) as OpenApiSchema | undefined
+ if (branchSchema) walk(branchSchema, prefix)
+ })
+ }
+ }
}
+
+ walk(schema, path)
+ return [...candidates].sort()
}
-function collectCrdSecretReferences(): Array<{ plural: string; field: string }> {
- const references: Array<{ plural: string; field: string }> = []
- for (const file of readdirSync(crdsDir).filter(name => name.endsWith('.yaml')).sort()) {
- const document = asRecord(parse(readFileSync(resolve(crdsDir, file), 'utf8')))
- const crdName = asRecord(document?.metadata)?.name
- const plural = typeof crdName === 'string' ? crdName.split('.', 1)[0] : undefined
- const versions = asRecord(document?.spec)?.versions
- if (!plural || !Array.isArray(versions)) throw new Error(`Invalid CRD schema: ${file}`)
+function auditCrdContracts(
+ sources: readonly CrdSource[],
+ runtimeContracts: readonly SecretReferenceCrdContract[] = SECRET_REFERENCE_CRD_CONTRACTS
+): string[] {
+ const errors: string[] = []
+ const contracts: SecretReferenceCrdContract[] = []
+ const crdPlurals = new Set<string>()
+ const seenNonSecretPaths = new Set<string>()
+
+ for (const source of sources) {
+ const crd = parseCrd(source, errors)
+ if (!crd) continue
+ if (crdPlurals.has(crd.plural)) {
+ errors.push(`${crd.file}: duplicate CRD plural ${crd.plural}`)
+ continue
+ }
+ crdPlurals.add(crd.plural)
+
+ const contract = parseCrdContract(crd, errors)
+ if (!contract) continue
+ if (contract.plural !== crd.plural) {
+ errors.push(
+ `${crd.file}: contract plural ${contract.plural} does not match CRD plural ${crd.plural}`
+ )
+ }
+
+ const contractPaths = new Set(contract.fields.map(field => field.path))
+ for (const field of contract.fields) {
+ crd.schemas.forEach((schema, versionIndex) => {
+ const fieldSchema = schemaAtPath(schema, field.path)
+ if (!fieldSchema) {
+ errors.push(
+ `${crd.file}: contract path ${field.path} does not resolve in version ${versionIndex}`
+ )
+ return
+ }
+ if (!hasDescription(fieldSchema)) {
+ errors.push(`${crd.file}: contract path ${field.path} must have a non-empty description`)
+ }
+ })
+ }
+
+ for (const schema of crd.schemas) {
+ for (const candidatePath of collectSecretReferenceCandidates(schema)) {
+ if (contractPaths.has(candidatePath)) continue
+ const inventoryKey = `${crd.file}:${candidatePath}`
+ if (NON_SECRET_REFERENCE_PATHS.has(inventoryKey)) {
+ seenNonSecretPaths.add(inventoryKey)
+ } else {
+ errors.push(
+ `${crd.file}: secret-shaped field ${candidatePath} is absent from the explicit contract`
+ )
+ }
+ }
+ }
+
+ contracts.push(contract)
+ }
+
+ if (
+ JSON.stringify(normalizeContracts(contracts)) !==
+ JSON.stringify(normalizeContracts(runtimeContracts))
+ ) {
+ errors.push(
+ 'CRD Secret reference contracts do not match the runtime plural, field, and namespace-binding contract'
+ )
+ }
- const fields = new Set<string>()
- for (const version of versions) {
- const openApiSchema = asRecord(asRecord(asRecord(version)?.schema)?.openAPIV3Schema)
- collectSecretReferenceFields(openApiSchema, fields)
+ for (const inventoryKey of NON_SECRET_REFERENCE_PATHS) {
+ if (!seenNonSecretPaths.has(inventoryKey)) {
+ errors.push(`stale non-Secret reference classification: ${inventoryKey}`)
}
- for (const field of fields) references.push({ plural, field })
}
- return references
+
+ return errors
+}
+
+function cloneSources(): CrdSource[] {
+ return JSON.parse(JSON.stringify(loadCrdSources())) as CrdSource[]
+}
+
+function workflowRecipeSchema(sources: readonly CrdSource[]): OpenApiSchema {
+ const source = sources.find(candidate => candidate.file === 'workflowrecipe.yaml')
+ if (!source) throw new Error('WorkflowRecipe CRD fixture is missing')
+ const spec = asRecord(source.document.spec)
+ const versions = spec?.versions
+ if (!Array.isArray(versions)) throw new Error('WorkflowRecipe CRD versions are missing')
+ const schema = asRecord(asRecord(asRecord(versions[0])?.schema)?.openAPIV3Schema)
+ if (!schema) throw new Error('WorkflowRecipe CRD schema is missing')
+ return schema
}
describe('Secret reference CRD coverage', () => {
- it('keeps every schema-declared Secret reference covered by the safety scanner', () => {
- const references = collectCrdSecretReferences()
+ it('keeps the explicit CRD contracts in parity with the runtime scanner', () => {
+ expect(auditCrdContracts(loadCrdSources())).toEqual([])
- expect([...new Set(references.map(reference => reference.field))].sort()).toEqual(
- [...SECRET_REFERENCE_FIELDS].sort()
+ expect(
+ normalizeContracts(SECRET_REFERENCE_SCOPES.map(({ plural, fields }) => ({ plural, fields })))
+ ).toEqual(
+ normalizeContracts(
+ SECRET_REFERENCE_CRD_CONTRACTS.filter(contract => contract.fields.length > 0)
+ )
)
- expect([...new Set(references.map(reference => reference.plural))].sort()).toEqual(
- [...new Set(SECRET_REFERENCE_SCOPES.map(scope => scope.plural))].sort()
+ })
+
+ it('rejects lowercase paths, missing descriptions, uncontracted credentials, and new CRDs without a contract', () => {
+ const lowercasePath = cloneSources()
+ const lowercaseProperties = asRecord(
+ schemaAtPath(workflowRecipeSchema(lowercasePath), 'spec.steps[].run.capabilities.secrets[]')
+ ?.properties
+ )
+ if (!lowercaseProperties?.secretRef)
+ throw new Error('WorkflowRecipe secretRef fixture is missing')
+ lowercaseProperties.secretref = lowercaseProperties.secretRef
+ delete lowercaseProperties.secretRef
+ expect(auditCrdContracts(lowercasePath)).toContain(
+ 'workflowrecipe.yaml: contract path spec.steps[].run.capabilities.secrets[].secretRef does not resolve in version 0'
+ )
+
+ const missingDescription = cloneSources()
+ const envSecretSchema = schemaAtPath(
+ workflowRecipeSchema(missingDescription),
+ 'spec.workloads[].envSecret'
+ )
+ if (!envSecretSchema) throw new Error('WorkflowRecipe envSecret fixture is missing')
+ delete envSecretSchema.description
+ expect(auditCrdContracts(missingDescription)).toContain(
+ 'workflowrecipe.yaml: contract path spec.workloads[].envSecret must have a non-empty description'
+ )
+
+ const uncontractedTokenRef = cloneSources()
+ const tokenRefSpecProperties = asRecord(workflowRecipeSchema(uncontractedTokenRef).properties)
+ const tokenRefRecipeProperties = asRecord(asRecord(tokenRefSpecProperties?.spec)?.properties)
+ if (!tokenRefRecipeProperties) throw new Error('WorkflowRecipe properties fixture is missing')
+ tokenRefRecipeProperties.tokenRef = {
+ type: 'string',
+ description: 'a lowercase secret reference',
+ }
+ expect(auditCrdContracts(uncontractedTokenRef)).toContain(
+ 'workflowrecipe.yaml: secret-shaped field spec.tokenRef is absent from the explicit contract'
+ )
+
+ const extraCredentials = cloneSources()
+ const workflowSpecProperties = asRecord(workflowRecipeSchema(extraCredentials).properties)
+ if (!workflowSpecProperties?.spec) throw new Error('WorkflowRecipe spec fixture is missing')
+ const recipeProperties = asRecord(asRecord(workflowSpecProperties.spec)?.properties)
+ if (!recipeProperties) throw new Error('WorkflowRecipe properties fixture is missing')
+ recipeProperties.extraCredentials = {
+ type: 'object',
+ description: 'Extra credential reference.',
+ properties: {
+ name: { type: 'string' },
+ key: { type: 'string' },
+ },
+ }
+ expect(auditCrdContracts(extraCredentials)).toContain(
+ 'workflowrecipe.yaml: secret-shaped field spec.extraCredentials is absent from the explicit contract'
+ )
+
+ const missingContract = cloneSources()
+ missingContract.push({
+ file: 'newresource.yaml',
+ document: {
+ metadata: { name: 'newresources.clerum.io' },
+ spec: {
+ names: { plural: 'newresources' },
+ versions: [
+ {
+ schema: {
+ openAPIV3Schema: {
+ type: 'object',
+ properties: { spec: { type: 'object' } },
+ },
+ },
+ },
+ ],
+ },
+ },
+ })
+ expect(auditCrdContracts(missingContract)).toContain(
+ `newresource.yaml: missing ${SECRET_REFERENCE_CONTRACT_ANNOTATION} annotation`
)
})
})
diff --git a/control-api/test/mockGateway.contract.test.ts b/control-api/test/mockGateway.contract.test.ts
index 87dedc948..4d8ec0e63 100644
--- a/control-api/test/mockGateway.contract.test.ts
+++ b/control-api/test/mockGateway.contract.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, it } from 'vitest'
import { MockGateway } from './mockGateway.js'
+const b64 = (value: string): string => Buffer.from(value).toString('base64')
+
describe('MockGateway Kubernetes identity contract', () => {
it('returns the server-assigned identity from a mutation', async () => {
const gateway = new MockGateway('mcp-server')
@@ -197,6 +199,210 @@ describe('MockGateway Kubernetes identity contract', () => {
})
})
+ it('materializes stringData over data as base64 on Secret create', async () => {
+ const gateway = new MockGateway('mcp-server')
+
+ const created = await gateway.createSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ data: { KEEP: b64('encoded'), OVERRIDE: b64('stale') },
+ stringData: { OVERRIDE: 'plain' },
+ })
+
+ expect(created).toMatchObject({
+ data: { KEEP: b64('encoded'), OVERRIDE: b64('plain') },
+ })
+ expect(created).not.toHaveProperty('stringData')
+
+ const stored = await gateway.getSecret('credentials', 'mcp-server')
+ expect(stored).toMatchObject({ data: { KEEP: b64('encoded'), OVERRIDE: b64('plain') } })
+ expect(stored).not.toHaveProperty('stringData')
+ })
+
+ it('materializes stringData over data as base64 on Secret replace', async () => {
+ const gateway = new MockGateway('mcp-server')
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'Opaque',
+ data: { PRIOR: b64('prior') },
+ })
+
+ const updated = await gateway.updateSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ data: { DATA_ONLY: b64('encoded'), OVERRIDE: b64('stale') },
+ stringData: { OVERRIDE: 'plain' },
+ })
+
+ expect(updated).toMatchObject({
+ data: { DATA_ONLY: b64('encoded'), OVERRIDE: b64('plain') },
+ })
+ expect(updated).not.toHaveProperty('stringData')
+ })
+
+ it('applies merge-patch deletions before materializing stringData over data', async () => {
+ const gateway = new MockGateway('mcp-server')
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'Opaque',
+ labels: { keep: 'yes', remove: 'yes' },
+ annotations: { 'safe.example/keep': 'yes', 'safe.example/remove': 'yes' },
+ data: { KEEP: b64('keep'), REMOVE: b64('remove'), OVERRIDE: b64('stale') },
+ })
+
+ const merged = await gateway.mergeSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ labels: { remove: null },
+ annotations: { 'safe.example/remove': null },
+ data: { REMOVE: null, DATA_ONLY: b64('encoded'), OVERRIDE: b64('stale-data') },
+ stringData: { DATA_ONLY: 'plain', OVERRIDE: 'plain-override', UNUSED: null },
+ } as unknown)
+
+ expect(merged).toMatchObject({
+ labels: { keep: 'yes' },
+ annotations: { 'safe.example/keep': 'yes' },
+ data: {
+ KEEP: b64('keep'),
+ DATA_ONLY: b64('plain'),
+ OVERRIDE: b64('plain-override'),
+ },
+ })
+ expect(merged.data).not.toHaveProperty('REMOVE')
+ expect(merged.data).not.toHaveProperty('UNUSED')
+ expect(merged).not.toHaveProperty('stringData')
+
+ const stored = await gateway.getSecret('credentials', 'mcp-server')
+ expect(stored).toMatchObject({
+ metadata: {
+ labels: { keep: 'yes' },
+ annotations: { 'safe.example/keep': 'yes' },
+ },
+ data: {
+ KEEP: b64('keep'),
+ DATA_ONLY: b64('plain'),
+ OVERRIDE: b64('plain-override'),
+ },
+ })
+ expect(stored.data).not.toHaveProperty('REMOVE')
+ expect(stored.data).not.toHaveProperty('UNUSED')
+ expect(stored).not.toHaveProperty('stringData')
+ })
+
+ it('preserves an identical future clerum.io annotation through a Secret merge', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const futureKey = 'clerum.io/future-controller-state'
+ const futureValue = 'opaque-v1'
+ const constraints = { allowExistingPlatformAnnotationKeys: [futureKey] }
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'Opaque',
+ annotations: { [futureKey]: futureValue },
+ })
+
+ await expect(
+ gateway.mergeSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ annotations: { [futureKey]: futureValue },
+ stringData: { VALUE: 'rotated' },
+ },
+ constraints
+ )
+ ).resolves.toMatchObject({ annotations: { [futureKey]: futureValue } })
+
+ await expect(gateway.getSecret('credentials', 'mcp-server')).resolves.toMatchObject({
+ metadata: { annotations: { [futureKey]: futureValue } },
+ })
+ })
+
+ it('rejects changed or injected future clerum.io annotations after reading a Secret', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const futureKey = 'clerum.io/future-controller-state'
+ const constraints = { allowExistingPlatformAnnotationKeys: [futureKey] }
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'Opaque',
+ annotations: { [futureKey]: 'opaque-v1' },
+ })
+
+ await expect(
+ gateway.mergeSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ annotations: { [futureKey]: 'caller-controlled' },
+ },
+ constraints
+ )
+ ).rejects.toThrow()
+
+ await expect(
+ gateway.mergeSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ annotations: { [futureKey]: null },
+ } as unknown,
+ constraints
+ )
+ ).rejects.toThrow()
+
+ await expect(
+ gateway.mergeSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ annotations: { 'clerum.io/another-future-key': 'caller-controlled' },
+ },
+ constraints
+ )
+ ).rejects.toThrow()
+
+ await expect(gateway.getSecret('credentials', 'mcp-server')).resolves.toMatchObject({
+ metadata: { annotations: { [futureKey]: 'opaque-v1' } },
+ })
+ })
+
+ it('applies the current type policy when a Secret merge preserves its type', async () => {
+ const gateway = new MockGateway('mcp-server')
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'kubernetes.io/service-account-token',
+ })
+
+ await expect(
+ gateway.mergeSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ stringData: { VALUE: 'rotated' },
+ })
+ ).rejects.toThrow(/Secret type/)
+ })
+
+ it('does not let an explicit safe type mask a controller-managed live type', async () => {
+ const gateway = new MockGateway('mcp-server')
+ gateway.seedSecret('credentials', 'mcp-server', {
+ type: 'kubernetes.io/service-account-token',
+ })
+
+ await expect(
+ gateway.updateSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ stringData: { VALUE: 'rotated' },
+ })
+ ).rejects.toThrow(/managed by Kubernetes/)
+
+ await expect(
+ gateway.mergeSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ stringData: { VALUE: 'rotated' },
+ })
+ ).rejects.toThrow(/managed by Kubernetes/)
+ })
+
it('stores a dynamic map key as data without changing the object prototype', async () => {
const gateway = new MockGateway('mcp-server')
gateway.seedSecret('credentials', 'mcp-server', { type: 'Opaque' })
diff --git a/control-api/test/mockGateway.ts b/control-api/test/mockGateway.ts
index 64c5e3ab7..8313e9748 100644
--- a/control-api/test/mockGateway.ts
+++ b/control-api/test/mockGateway.ts
@@ -1,9 +1,8 @@
import { K8sNotFoundError } from '../src/services/resourceService.js'
import {
type SecretConstraintOptions,
- assertValidEffectiveSecretConstraints,
+ assertMutablePreservedSecretType,
assertValidSecretConstraints,
- assertValidSecretType,
resolveSecretAnnotationsForReplace,
} from '../src/services/secretConstraints.js'
import { assertValidSecretDataKey, assertValidSecretWriteKeys } from '../src/services/secretKeys.js'
@@ -85,6 +84,22 @@ function mergePatchMap(
return Object.fromEntries([...retainedEntries, ...replacementEntries])
}
+/**
+ * Kubernetes materializes write-only stringData into data after applying a
+ * Secret payload or merge patch. The API server returns only the resulting
+ * base64 data map, never stringData.
+ */
+function materializeSecretData(
+ data: Record<string, string> | undefined,
+ stringData: Record<string, unknown> | undefined
+): Record<string, string> | undefined {
+ if (data === undefined && stringData === undefined) return undefined
+ const stringDataEntries = Object.entries(stringData ?? {})
+ .filter(([, value]): value is string => typeof value === 'string')
+ .map(([key, value]) => [key, Buffer.from(value).toString('base64')] as const)
+ return Object.fromEntries([...Object.entries(data ?? {}), ...stringDataEntries])
+}
+
export type MockGatewaySecretWriteFault = (input: {
operation: 'create' | 'update' | 'merge'
snapshot: SecretSnapshot
@@ -121,7 +136,6 @@ export class MockGateway {
uid: string
resourceVersion: string
data?: Record<string, string>
- stringData?: Record<string, string>
}
>
@@ -194,8 +208,7 @@ export class MockGateway {
annotations: options?.annotations,
uid: options?.uid ?? this.allocateUid('secret', ns, name),
resourceVersion: options?.resourceVersion ?? '1',
- data: options?.data,
- stringData: options?.stringData,
+ data: materializeSecretData(options?.data, options?.stringData),
})
}
@@ -421,7 +434,6 @@ export class MockGateway {
},
type: entry.type || 'Opaque',
data: entry.data,
- stringData: entry.stringData,
}
}
@@ -447,8 +459,7 @@ export class MockGateway {
annotations: body.annotations,
uid: this.allocateUid('secret', body.namespace || this.ns, body.name),
resourceVersion: '1',
- data: body.data,
- stringData: body.stringData,
+ data: materializeSecretData(body.data, body.stringData),
}
this.secretStore.set(key, entry)
const snapshot = this.snapshot(entry)
@@ -485,6 +496,7 @@ export class MockGateway {
err.code = 404
throw err
}
+ assertMutablePreservedSecretType(existing.type)
assertValidSecretConstraints(body, opts, existing.annotations)
assertValidSecretWriteKeys(body)
this.assertPrecondition(body.name, existing, precondition)
@@ -494,10 +506,6 @@ export class MockGateway {
opts
)
const effectiveType = body.type ?? existing.type ?? 'Opaque'
- assertValidEffectiveSecretConstraints(
- { name: body.name, type: effectiveType, annotations: effectiveAnnotations },
- opts
- )
const updated = {
name: body.name,
namespace: body.namespace || this.ns,
@@ -506,8 +514,7 @@ export class MockGateway {
annotations: effectiveAnnotations,
uid: existing?.uid,
resourceVersion: MockGateway.nextResourceVersion(existing?.resourceVersion),
- data: body.data,
- stringData: body.stringData,
+ data: materializeSecretData(body.data, body.stringData),
}
this.secretStore.set(key, updated)
const snapshot = this.snapshot(updated)
@@ -534,30 +541,22 @@ export class MockGateway {
err.code = 404
throw err
}
- this.assertPrecondition(body.name, existing, precondition)
- if (body.type !== undefined) assertValidSecretType(body.type)
+ assertMutablePreservedSecretType(existing.type)
+ assertValidSecretConstraints(body, opts, existing.annotations)
assertValidSecretWriteKeys(body)
- const effectiveAnnotations = resolveSecretAnnotationsForReplace(
+ this.assertPrecondition(body.name, existing, precondition)
+ const effectiveAnnotations = mergePatchMap(
existing.annotations,
- body.annotations,
- opts
+ body.annotations as Record<string, unknown> | undefined
)
const effectiveType = body.type ?? existing.type ?? 'Opaque'
- assertValidEffectiveSecretConstraints(
- { name: body.name, type: effectiveType, annotations: effectiveAnnotations },
- opts
- )
const updated = {
...existing,
type: effectiveType,
labels: mergePatchMap(existing.labels, body.labels as Record<string, unknown> | undefined),
- annotations: mergePatchMap(
- existing.annotations,
- body.annotations as Record<string, unknown> | undefined
- ),
- data: mergePatchMap(existing.data, body.data as Record<string, unknown> | undefined),
- stringData: mergePatchMap(
- existing.stringData,
+ annotations: effectiveAnnotations,
+ data: materializeSecretData(
+ mergePatchMap(existing.data, body.data as Record<string, unknown> | undefined),
body.stringData as Record<string, unknown> | undefined
),
resourceVersion:
@@ -580,9 +579,8 @@ export class MockGateway {
uid: string
resourceVersion: string
data?: Record<string, string>
- stringData?: Record<string, string>
}): SecretSnapshot {
- return toSecretSnapshot(
+ const snapshot = toSecretSnapshot(
{
metadata: {
name: entry.name,
@@ -594,11 +592,12 @@ export class MockGateway {
},
type: entry.type,
data: entry.data,
- stringData: entry.stringData,
},
entry.name,
entry.namespace
)
+ delete (snapshot as { stringData?: unknown }).stringData
+ return snapshot
}
/**
@@ -692,20 +691,14 @@ export class MockGateway {
}
this.assertPrecondition(req.name, existing, precondition)
const effectiveAnnotations = resolveSecretAnnotationsForReplace(existing.annotations, undefined)
- assertValidEffectiveSecretConstraints({
- name: existing.name,
- type: existing.type ?? 'Opaque',
- annotations: effectiveAnnotations,
- })
+ assertMutablePreservedSecretType(existing.type ?? 'Opaque')
const updated = {
...existing,
...(existing.data ? { data: { ...existing.data } } : {}),
- ...(existing.stringData ? { stringData: { ...existing.stringData } } : {}),
resourceVersion:
MockGateway.nextResourceVersion(existing.resourceVersion) ?? existing.resourceVersion,
}
delete updated.data?.[req.key]
- delete updated.stringData?.[req.key]
this.secretStore.set(key, updated)
return this.snapshot(updated)
}
diff --git a/control-api/test/registryClient.test.ts b/control-api/test/registryClient.test.ts
index 360b4a298..bf5c7c883 100644
--- a/control-api/test/registryClient.test.ts
+++ b/control-api/test/registryClient.test.ts
@@ -1,9 +1,11 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
type PublishScope,
+ RegistryProxyError,
__resetScopeCacheForTests,
__resetTokenCacheForTests,
applyPublishScope,
+ createOrgGrant,
getCategories,
invalidateRegistryIdentityCaches,
mintToken,
@@ -1073,3 +1075,66 @@ describe('registryClient — catalog read-through cache', () => {
expect(entryGets.length).toBe(2)
})
})
+
+describe('registryClient — safe registry proxy errors', () => {
+ it('keeps only an allowlisted JSON error code from an upstream error response', async () => {
+ const fetchMock = vi.fn().mockImplementation((url: string) => {
+ if (url.endsWith('/oauth/token')) return Promise.resolve(fakeTokenResponse('tok', 600))
+ return Promise.resolve(
+ new Response(
+ JSON.stringify({
+ error: 'self_grant',
+ message: 'untrusted diagnostic text',
+ extra: { source: 'upstream' },
+ }),
+ { status: 400, headers: { 'Content-Type': 'application/json; charset=utf-8' } }
+ )
+ )
+ })
+ vi.stubGlobal('fetch', fetchMock)
+ Object.assign(process.env, ENV_OVERRIDE)
+
+ const err = (await createOrgGrant('acme', {
+ pluginName: '@acme/plugin',
+ granteeOrg: 'other-org',
+ actingUserId: 'operator-1',
+ }).catch(error => error)) as RegistryProxyError
+
+ expect(err).toBeInstanceOf(RegistryProxyError)
+ expect(err.status).toBe(400)
+ expect(err.body).toEqual({ error: 'self_grant' })
+ })
+
+ it('uses a synthetic code for unallowlisted JSON and non-JSON upstream errors', async () => {
+ const upstreamResponses = [
+ new Response(JSON.stringify({ error: 'unreviewed_code', detail: 'untrusted diagnostic' }), {
+ status: 409,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ new Response('<html><body>upstream diagnostic</body></html>', {
+ status: 502,
+ headers: { 'Content-Type': 'text/html' },
+ }),
+ ]
+ const fetchMock = vi.fn().mockImplementation((url: string) => {
+ if (url.endsWith('/oauth/token')) return Promise.resolve(fakeTokenResponse('tok', 600))
+ return Promise.resolve(upstreamResponses.shift()!)
+ })
+ vi.stubGlobal('fetch', fetchMock)
+ Object.assign(process.env, ENV_OVERRIDE)
+
+ const jsonErr = (await createOrgGrant('acme', {
+ pluginName: '@acme/plugin',
+ granteeOrg: 'other-org',
+ actingUserId: 'operator-1',
+ }).catch(error => error)) as RegistryProxyError
+ const htmlErr = (await createOrgGrant('acme', {
+ pluginName: '@acme/plugin',
+ granteeOrg: 'other-org',
+ actingUserId: 'operator-1',
+ }).catch(error => error)) as RegistryProxyError
+
+ expect(jsonErr.body).toEqual({ error: 'registry_409' })
+ expect(htmlErr.body).toEqual({ error: 'registry_502' })
+ })
+})
diff --git a/control-api/test/routes.adminRecipes.test.ts b/control-api/test/routes.adminRecipes.test.ts
index 98d105ff8..55697ef3d 100644
--- a/control-api/test/routes.adminRecipes.test.ts
+++ b/control-api/test/routes.adminRecipes.test.ts
@@ -19,6 +19,15 @@ const WORKFLOW_TEAM_ID = '11111111-1111-4111-8111-111111111111'
const NON_TRANSPORT_PUBLIC_WEB_MESSAGE =
'public-web is only supported on MCP transport workloads; non-transport workloads must use exact-host egressBindings'
+function decodeKubernetesData(snapshot: { data?: Record<string, string> }): Record<string, string> {
+ return Object.fromEntries(
+ Object.entries(snapshot.data ?? {}).map(([key, value]) => [
+ key,
+ Buffer.from(value, 'base64').toString('utf8'),
+ ])
+ )
+}
+
const VALID_RECIPE = {
metadata: { name: 'my-recipe' },
spec: {
@@ -1554,8 +1563,10 @@ describe.sequential('routes/admin/recipes', () => {
})
expect(JSON.stringify(res.body)).not.toContain('CG-test-secret')
const stored = (await gateway.getSecret('coingecko-api', SANDBOX_NS)) as {
+ data?: Record<string, string>
stringData?: Record<string, string>
}
+ stored.stringData = decodeKubernetesData(stored)
expect(stored.stringData?.apiKey).toBe('CG-test-secret')
await expect(gateway.getSecret('coingecko-api', MCP_NS)).rejects.toThrow()
})
@@ -1580,8 +1591,10 @@ describe.sequential('routes/admin/recipes', () => {
})
expect(JSON.stringify(res.body)).not.toContain('transport-secret')
const stored = (await gateway.getSecret('workflow-api-credentials', MCP_NS)) as {
+ data?: Record<string, string>
stringData?: Record<string, string>
}
+ stored.stringData = decodeKubernetesData(stored)
expect(stored.stringData?.apiKey).toBe('transport-secret')
await expect(gateway.getSecret('workflow-api-credentials', SANDBOX_NS)).rejects.toThrow()
})
@@ -1619,6 +1632,7 @@ describe.sequential('routes/admin/recipes', () => {
data?: Record<string, string>
stringData?: Record<string, string>
}
+ stored.stringData = decodeKubernetesData(stored)
expect(stored.data?.existingKey).toBe('ZXhpc3Rpbmc=')
expect(stored.stringData?.apiKey).toBe('CG-test-secret')
})
diff --git a/control-api/test/routes.adminRegistryGrants.test.ts b/control-api/test/routes.adminRegistryGrants.test.ts
index 960405ead..783abc01c 100644
--- a/control-api/test/routes.adminRegistryGrants.test.ts
+++ b/control-api/test/routes.adminRegistryGrants.test.ts
@@ -397,7 +397,13 @@ describe('wire shape (real wrappers, stubbed registry fetch)', () => {
)
vi.mocked(createOrgGrant).mockImplementationOnce(real.createOrgGrant)
real.__resetTokenCacheForTests()
- stubFetch(() => new Response(JSON.stringify({ error: 'self_grant' }), { status: 400 }))
+ stubFetch(
+ () =>
+ new Response(JSON.stringify({ error: 'self_grant' }), {
+ status: 400,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
const res = await request(makeApp())
.post('/admin/registry/grants')
.send({ pluginName: '@acme/p', granteeOrg: 'acme' })
diff --git a/control-api/test/routes.mcpSecrets.test.ts b/control-api/test/routes.mcpSecrets.test.ts
index ec46a7457..e138503a6 100644
--- a/control-api/test/routes.mcpSecrets.test.ts
+++ b/control-api/test/routes.mcpSecrets.test.ts
@@ -3,6 +3,8 @@ import express from 'express'
import request from 'supertest'
import { rootLogger } from '../src/observability/logger.js'
import { createAdminSecretsRouter } from '../src/routes/admin/secrets.js'
+import { CONTROL_UI_ADMIN_SESSION_COOKIE } from '../src/utils/auth/sessionCookies.js'
+import { MockGateway } from './mockGateway.js'
/** The write shape the admin routes hand to the gateway. */
type SecretWrite = {
@@ -104,6 +106,25 @@ function makeApp(gateway: ReturnType<typeof createGateway>) {
return app
}
+const TEST_CONTROL_UI_SESSION = 'test-control-ui-session'
+
+function createAuthenticatedAgent(app: express.Express) {
+ const agent = request.agent(app)
+ agent.jar.setCookie(
+ `${CONTROL_UI_ADMIN_SESSION_COOKIE}=${TEST_CONTROL_UI_SESSION}; Path=/; HttpOnly`,
+ '127.0.0.1',
+ '/'
+ )
+ 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 ──────────────────────────────────────────────────────────
@@ -511,7 +532,7 @@ describe('PUT /admin/mcp-secrets/:name (credential rotation, issue #223)', () =>
expect(res.body.resourceVersion).toBe('2')
})
- it('preserves Registry catalog annotations while rotating managed credentials', async () => {
+ it('does not grant public rotation a registry annotation capability', async () => {
const gateway = createGateway()
gateway.getSecret.mockResolvedValueOnce({
metadata: {
@@ -540,13 +561,7 @@ describe('PUT /admin/mcp-secrets/:name (credential rotation, issue #223)', () =>
namespace: 'mcp-server',
stringData: { LINEAR_API_KEY: 'rotated-value' },
}),
- {
- allowExistingPlatformAnnotationKeys: [
- 'clerum.io/catalog-id',
- 'clerum.io/catalog-version',
- 'clerum.io/registry-operation-id',
- ],
- },
+ undefined,
{
uid: 'uid-linear-credentials',
}
@@ -835,16 +850,97 @@ describe('PUT /admin/mcp-secrets/:name (credential rotation, issue #223)', () =>
})
describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () => {
- it('requires both server-issued identity values', async () => {
+ it('requires both server-issued identity values when a client supplies either one', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
- await request(app).delete('/admin/mcp-secrets/linear-credentials').send({}).expect(428)
+ for (const body of [{ uid: 'uid-linear-credentials' }, { resourceVersion: '1' }]) {
+ await request(app).delete('/admin/mcp-secrets/linear-credentials').send(body).expect(428)
+ }
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
- it('refuses to delete a Secret referenced by a live connector', async () => {
+ it('supports an old UI POST plus bodyless DELETE with a signed create proof', async () => {
+ const gateway = createGateway()
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ const created = 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 {
+ const res = await agent.delete('/admin/mcp-secrets/linear-credentials').expect(200)
+
+ expect(res.body).toEqual({
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ deleted: true,
+ })
+ expect(res.status).toBe(200)
+ expect(gateway.getSecret).toHaveBeenCalledWith('linear-credentials', 'mcp-server')
+ expect(gateway.deleteSecret).toHaveBeenCalledWith('linear-credentials', 'mcp-server', {
+ uid: 'uid-linear-credentials',
+ resourceVersion: '1',
+ })
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ module: 'admin-secrets',
+ event: 'mcp-secret-delete-legacy-signed-create-proof',
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ preconditionSource: 'signed-create-proof',
+ }),
+ 'MCP Secret delete used signed create proof'
+ )
+ 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}=`))])
+ )
+ } finally {
+ warnSpy.mockRestore()
+ }
+ })
+
+ it('rejects a bodyless old UI DELETE with no signed create proof', async () => {
+ const gateway = createGateway()
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(428)
+
+ expect(gateway.getSecret).not.toHaveBeenCalled()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects a stale supplied identity before delete', async () => {
+ const gateway = createGateway()
+ gateway.getSecret.mockResolvedValueOnce({
+ metadata: {
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-current',
+ resourceVersion: '2',
+ labels: {},
+ },
+ data: {},
+ })
+ const app = makeApp(gateway)
+
+ const res = await request(app)
+ .delete('/admin/mcp-secrets/linear-credentials')
+ .send({ uid: 'uid-linear-credentials', resourceVersion: '1' })
+ .expect(409)
+
+ expect(res.body).toMatchObject({ error: 'secret_identity_changed', outcome: 'repair_required' })
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('legacy signed proof refuses to delete a Secret referenced by a live connector', async () => {
const gateway = createGateway()
gateway.listResource.mockResolvedValueOnce([
{
@@ -853,16 +949,43 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
},
])
const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
- const res = await request(app)
- .delete('/admin/mcp-secrets/linear-credentials')
- .send({ uid: 'uid-linear-credentials', resourceVersion: '1' })
- .expect(409)
+ await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ const res = await agent.delete('/admin/mcp-secrets/linear-credentials').expect(409)
expect(res.body).toMatchObject({ error: 'mcp_secret_in_use', outcome: 'repair_required' })
expect(gateway.deleteSecret).not.toHaveBeenCalled()
})
+ it('legacy signed proof refuses to delete a WorkflowRecipe-owned Secret', async () => {
+ const gateway = createGateway()
+ gateway.getSecret.mockResolvedValueOnce({
+ metadata: {
+ name: 'recipe-creds',
+ namespace: 'mcp-server',
+ uid: 'uid-recipe-creds',
+ resourceVersion: '1',
+ labels: { 'clerum.io/recipe-secret': 'true' },
+ },
+ data: {},
+ })
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'recipe-creds', data: { RECIPE_KEY: 'create-value' } })
+ .expect(201)
+ const res = await agent.delete('/admin/mcp-secrets/recipe-creds').expect(409)
+
+ expect(res.body.error).toContain('WorkflowRecipe')
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
it('refuses to delete a Secret used as a live connector image pull Secret', async () => {
const gateway = createGateway()
gateway.listResource.mockResolvedValueOnce([
@@ -913,4 +1036,128 @@ describe('DELETE /admin/mcp-secrets/:name (identity and dependency guard)', () =
resourceVersion: '1',
})
})
+
+ it('rejects a malformed fallback body even when a signed proof exists', async () => {
+ const gateway = createGateway()
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ await agent
+ .delete('/admin/mcp-secrets/linear-credentials')
+ .send({ unexpected: true })
+ .expect(428)
+
+ expect(gateway.getSecret).not.toHaveBeenCalled()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects a tampered signed create proof', async () => {
+ const gateway = createGateway()
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ const created = 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', '/')
+
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(428)
+
+ expect(gateway.getSecret).not.toHaveBeenCalled()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects an expired signed create proof', async () => {
+ const gateway = createGateway()
+ const app = makeApp(gateway)
+ const agent = createAuthenticatedAgent(app)
+
+ await agent
+ .post('/admin/mcp-secrets')
+ .send({ name: 'linear-credentials', data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ const dateNowSpy = vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 121_000)
+ try {
+ await agent.delete('/admin/mcp-secrets/linear-credentials').expect(428)
+ } finally {
+ dateNowSpy.mockRestore()
+ }
+
+ expect(gateway.getSecret).not.toHaveBeenCalled()
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
+ it('does not delete a replacement that wins before the legacy proof read', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const name = 'linear-credentials'
+ const app = makeApp(gateway as never)
+ const agent = createAuthenticatedAgent(app)
+
+ const created = await agent
+ .post('/admin/mcp-secrets')
+ .send({ name, data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ const originalIdentity = {
+ uid: created.body.uid as string,
+ resourceVersion: created.body.resourceVersion as string,
+ }
+ await gateway.deleteSecret(name, 'mcp-server', originalIdentity)
+ gateway.seedSecret(name, 'mcp-server', {
+ uid: 'uid-linear-replacement',
+ resourceVersion: '1',
+ })
+
+ const res = await agent.delete(`/admin/mcp-secrets/${name}`).expect(409)
+
+ expect(res.body).toMatchObject({ error: 'secret_identity_changed', outcome: 'repair_required' })
+ await expect(gateway.getSecret(name, 'mcp-server')).resolves.toMatchObject({
+ metadata: { uid: 'uid-linear-replacement', resourceVersion: '1' },
+ })
+ })
+
+ it('does not delete a replacement that wins after the legacy proof read', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const name = 'linear-credentials'
+ const app = makeApp(gateway as never)
+ const agent = createAuthenticatedAgent(app)
+
+ const created = await agent
+ .post('/admin/mcp-secrets')
+ .send({ name, data: { LINEAR_API_KEY: 'create-value' } })
+ .expect(201)
+ const originalIdentity = {
+ uid: created.body.uid as string,
+ resourceVersion: created.body.resourceVersion as string,
+ }
+
+ const deleteSpy = vi.spyOn(gateway, 'deleteSecret')
+ const listResources = gateway.listResource.bind(gateway)
+ let replacementCreated = false
+ vi.spyOn(gateway, 'listResource').mockImplementation(async (...args) => {
+ if (!replacementCreated && args[0] === 'mcpservers' && args[1] === 'mcp-server') {
+ replacementCreated = true
+ await gateway.deleteSecret(name, 'mcp-server', originalIdentity)
+ gateway.seedSecret(name, 'mcp-server', {
+ uid: 'uid-linear-replacement',
+ resourceVersion: '1',
+ })
+ }
+ return listResources(...args)
+ })
+
+ const res = await agent.delete(`/admin/mcp-secrets/${name}`).expect(409)
+
+ expect(res.body).toMatchObject({ error: 'secret_identity_changed', outcome: 'repair_required' })
+ expect(replacementCreated).toBe(true)
+ expect(deleteSpy).toHaveBeenLastCalledWith(name, 'mcp-server', originalIdentity)
+ await expect(gateway.getSecret(name, 'mcp-server')).resolves.toMatchObject({
+ metadata: { uid: 'uid-linear-replacement', resourceVersion: '1' },
+ })
+ })
})
diff --git a/control-api/test/routes.registryInstall.test.ts b/control-api/test/routes.registryInstall.test.ts
index 4953f295b..9289f654c 100644
--- a/control-api/test/routes.registryInstall.test.ts
+++ b/control-api/test/routes.registryInstall.test.ts
@@ -4091,7 +4091,7 @@ describe('POST /admin/registry/upgrade', () => {
}
expect(current.spec?.image).toBe('test:2.0')
await expect(gw.getSecret('my-srv-credentials', 'mcp-server')).resolves.toMatchObject({
- stringData: { [field]: nextValue },
+ data: { [field]: Buffer.from(nextValue).toString('base64') },
})
})
@@ -4263,7 +4263,7 @@ describe('POST /admin/registry/upgrade', () => {
})
const current = await gw.getSecret(secretName, 'mcp-server')
expect(current.metadata?.uid).toBe('uid-existing-credentials')
- expect(current.stringData).toEqual({ [field]: concurrentValue })
+ expect(current.data).toEqual({ [field]: Buffer.from(concurrentValue).toString('base64') })
})
it('does not compensate after a same-UID metadata-only concurrent mutation', async () => {
@@ -4395,7 +4395,9 @@ describe('POST /admin/registry/upgrade', () => {
const current = await gw.getSecret(secretName, 'mcp-server')
expect(current.metadata?.uid).toBe('uid-existing-credentials')
expect(current.metadata?.resourceVersion).not.toBe('1')
- expect(current.stringData).toEqual({ [field]: ['registry', 'value'].join('-') })
+ expect(current.data).toEqual({
+ [field]: Buffer.from(['registry', 'value'].join('-')).toString('base64'),
+ })
})
it('requires repair when an upgrade credential create response is lost after commit', async () => {
@@ -4856,6 +4858,62 @@ describe('POST /admin/registry/upgrade', () => {
})
})
+ it('restores a future platform annotation after a not-committed CR fence', async () => {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(MOCK_ENTRY_V2 as any)
+ const credentialKey = ['API', 'KEY'].join('_')
+ vi.mocked(getCredentialSchema).mockResolvedValueOnce({
+ required: true,
+ authType: 'api-key',
+ keys: [{ name: credentialKey }],
+ })
+ const { app, gw } = makeApp()
+ const futureKey = 'clerum.io/future-controller-state'
+ const priorValue = ['fixture', 'prior'].join('-')
+ gw.seedSecret('my-srv-credentials', 'mcp-server', {
+ type: 'Opaque',
+ uid: 'secret-uid-fenced-future-platform',
+ resourceVersion: '7',
+ annotations: { [futureKey]: 'opaque-v1' },
+ data: { [credentialKey]: priorValue },
+ })
+ const originalUpdate = gw.updateResource.bind(gw)
+ let firstServerUpdate = true
+ vi.spyOn(gw, 'updateResource').mockImplementation(async (...args) => {
+ if (args[0] === 'mcpservers' && firstServerUpdate) {
+ firstServerUpdate = false
+ throw Object.assign(new Error('response lost before CR commit'), {
+ code: 503,
+ statusCode: 503,
+ })
+ }
+ return originalUpdate(...args)
+ })
+ const updateSecretSpy = vi.spyOn(gw, 'updateSecret')
+
+ const res = await request(app)
+ .post('/admin/registry/upgrade')
+ .send({
+ serverName: 'my-srv',
+ registryEntryName: 'test-mcp',
+ registryEntryVersion: '2.0.0',
+ credentials: { [credentialKey]: ['fixture', 'next'].join('-') },
+ })
+ .expect(503)
+
+ expect(res.body).toMatchObject({
+ error: 'registry_upgrade_outcome_not_committed',
+ outcome: 'not_committed',
+ })
+ expect(updateSecretSpy).toHaveBeenCalledTimes(2)
+ expect(updateSecretSpy.mock.calls[1][0].annotations).toMatchObject({
+ [futureKey]: 'opaque-v1',
+ })
+ await expect(gw.getSecret('my-srv-credentials', 'mcp-server')).resolves.toMatchObject({
+ metadata: { annotations: { [futureKey]: 'opaque-v1' } },
+ data: { [credentialKey]: priorValue },
+ })
+ })
+
it('sets annotations to empty object on rollback when the original secret had no annotations', async () => {
vi.mocked(getEntryVersion).mockResolvedValueOnce(MOCK_ENTRY_V2 as any)
vi.mocked(getCredentialSchema).mockResolvedValueOnce({
@@ -5935,6 +5993,39 @@ describe('POST /admin/registry/upgrade-recipe', () => {
expect(recipe.spec).toEqual({ steps: [{ id: 's1', instruction: 'Run step' }] })
})
+ it('requires repair when a recipe write and identity fence remain ambiguous', async () => {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce({
+ ...MOCK_RECIPE_ENTRY,
+ recipe_meta: { recipeYaml: JSON.stringify({ spec: { steps: [{ id: 'ambiguous' }] } }) },
+ })
+ const { app, gw } = makeRecipeUpgradeApp()
+ const originalUpdate = gw.updateResource.bind(gw)
+ vi.spyOn(gw, 'updateResource').mockImplementation(async (plural, name, body, namespace) => {
+ if (plural === 'workflowrecipes') {
+ throw Object.assign(new Error('recipe update and fence response lost'), {
+ statusCode: 503,
+ code: 503,
+ })
+ }
+ return originalUpdate(plural, name, body, namespace)
+ })
+
+ const response = await request(app).post('/admin/registry/upgrade-recipe').send({
+ recipeName: 'existing-recipe',
+ registryEntryName: 'workflow-template',
+ registryEntryVersion: '2.0.0',
+ })
+
+ expect(response.status, JSON.stringify(response.body)).toBe(503)
+ expect(response.body).toMatchObject({
+ error: 'registry_upgrade_outcome_ambiguous',
+ outcome: 'repair_required',
+ })
+ await expect(
+ gw.getResource('workflowrecipes', 'existing-recipe', 'sandbox-recipes')
+ ).resolves.toMatchObject({ spec: { steps: [{ id: 's1', instruction: 'Run step' }] } })
+ })
+
it('rejects cluster-local sibling egressBindings in another namespace before updating the CRD', async () => {
vi.mocked(getEntryVersion).mockResolvedValueOnce({
...MOCK_RECIPE_ENTRY,
@@ -6491,6 +6582,44 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {
expect(hook.spec.target.image.ref).toBe(IMG_A)
})
+ it('requires repair when a hook write and identity fence remain ambiguous', async () => {
+ const gw = new MockGateway()
+ await seedInstalledImageHook(gw, 'my-hook')
+ vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)
+ vi.mocked(getEntryVersion).mockResolvedValue(
+ hookEntry({
+ name: '@acme/hook',
+ trust_level: 'low',
+ hook_meta: { target: { image: { ref: IMG_B, port: 8080 } }, lifecyclePoints: ['preCall'] },
+ })
+ )
+ const originalUpdate = gw.updateResource.bind(gw)
+ vi.spyOn(gw, 'updateResource').mockImplementation(async (plural, name, body, namespace) => {
+ if (plural === 'llmhooks') {
+ throw Object.assign(new Error('hook update and fence response lost'), {
+ statusCode: 503,
+ code: 503,
+ })
+ }
+ return originalUpdate(plural, name, body, namespace)
+ })
+
+ const response = await request(makeApp(gw))
+ .post('/admin/registry/upgrade-hook')
+ .send({ hookName: 'my-hook', registryEntryName: '@acme/hook', registryEntryVersion: '2.0.0' })
+
+ expect(response.status, JSON.stringify(response.body)).toBe(503)
+ expect(response.body).toMatchObject({
+ error: 'registry_upgrade_outcome_ambiguous',
+ outcome: 'repair_required',
+ })
+ await expect(
+ gw.getResource('llmhooks', 'my-hook', config.llmHooksNamespace)
+ ).resolves.toMatchObject({
+ spec: { target: { image: { ref: IMG_A } } },
+ })
+ })
+
it('refuses an upgrade that names a different entry than the one installed', async () => {
const gw = new MockGateway()
await seedInstalledImageHook(gw)
diff --git a/control-api/test/routes.resources.test.ts b/control-api/test/routes.resources.test.ts
index 676be6d3a..99d30c283 100644
--- a/control-api/test/routes.resources.test.ts
+++ b/control-api/test/routes.resources.test.ts
@@ -8,6 +8,15 @@ import { createAdminResourcesRouter } from '../src/routes/admin/resources.js'
import { K8sConflictError, ResourceService } from '../src/services/resourceService.js'
import { MockGateway } from './mockGateway.js'
+function decodeKubernetesData(snapshot: { data?: Record<string, string> }): Record<string, string> {
+ return Object.fromEntries(
+ Object.entries(snapshot.data ?? {}).map(([key, value]) => [
+ key,
+ Buffer.from(value, 'base64').toString('utf8'),
+ ])
+ )
+}
+
vi.mock('node:dns/promises', () => ({
lookup: vi.fn(),
}))
@@ -341,8 +350,10 @@ describe('routes/resources', () => {
name: 'cc-teams-channel-credentials',
})
const secret = (await gateway.getSecret('cc-teams-channel-credentials', 'channels')) as {
+ data?: Record<string, string>
stringData?: Record<string, string>
}
+ secret.stringData = decodeKubernetesData(secret)
expect(secret.stringData?.['teams-app-password']).toBe('secret-value')
})
diff --git a/control-api/test/routes.secrets.test.ts b/control-api/test/routes.secrets.test.ts
index eb837447d..b602cdf81 100644
--- a/control-api/test/routes.secrets.test.ts
+++ b/control-api/test/routes.secrets.test.ts
@@ -493,6 +493,18 @@ describe('routes/secrets', () => {
})
})
+ it('keeps recipe Secret DELETE identity-gated for clients without a body', 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).toMatchObject({ error: 'secret_identity_precondition_required' })
+ expect(gateway.deleteSecret).not.toHaveBeenCalled()
+ })
+
it('deletes a recipe secret from an allowed runtime namespace', async () => {
const gateway = createRecipeGateway()
gateway.getSecret.mockImplementation(async (name: string, namespace?: string) => {
diff --git a/control-api/test/services.registryMutation.test.ts b/control-api/test/services.registryMutation.test.ts
index 2aed18cb6..87a828516 100644
--- a/control-api/test/services.registryMutation.test.ts
+++ b/control-api/test/services.registryMutation.test.ts
@@ -4,7 +4,7 @@ import {
REGISTRY_SPEC_DIGEST_ANNOTATION,
type RegistryMutationDesired,
type RegistryResourceSnapshot,
- classifyCreatedRegistryMutationReadback,
+ classifyRegistryAssociationReadback,
classifyRegistryMutationReadback,
registrySpecDigest,
} from '../src/services/registryMutation.js'
@@ -61,6 +61,16 @@ describe('registry mutation readback classifier', () => {
).toBe('ambiguous')
})
+ it('keeps a stable unchanged association ambiguous until the caller fences it', () => {
+ expect(
+ classifyRegistryAssociationReadback({
+ before,
+ current: current({}),
+ isCommitted: spec => spec.image === 'plugin:new',
+ })
+ ).toBe('ambiguous')
+ })
+
it('requires the current operation identity, desired digest, labels and an advanced RV', () => {
expect(
classifyRegistryMutationReadback({
@@ -143,54 +153,3 @@ describe('registry mutation readback classifier', () => {
).toBe('ambiguous')
})
})
-
-describe('created resource readback classifier', () => {
- const desiredSpec = { image: 'example:new', transport: { port: 3000 } }
- const desired = {
- spec: desiredSpec,
- metadata: {
- labels: { 'clerum.io/managed-by': 'control-api' },
- annotations: {
- [REGISTRY_OPERATION_ID_ANNOTATION]: operationId,
- [REGISTRY_SPEC_DIGEST_ANNOTATION]: registrySpecDigest(desiredSpec),
- },
- },
- specDigest: registrySpecDigest(desiredSpec),
- }
-
- it('requires operation identity, exact intent digest, and server identity', () => {
- expect(
- classifyCreatedRegistryMutationReadback({
- current: {
- metadata: {
- uid: 'uid-created',
- resourceVersion: '1',
- labels: desired.metadata.labels,
- annotations: desired.metadata.annotations,
- },
- spec: desiredSpec,
- },
- desired,
- operationId,
- })
- ).toBe('committed')
- expect(
- classifyCreatedRegistryMutationReadback({
- current: {
- metadata: {
- uid: 'uid-created',
- resourceVersion: '1',
- labels: desired.metadata.labels,
- annotations: {
- ...desired.metadata.annotations,
- [REGISTRY_OPERATION_ID_ANNOTATION]: 'other',
- },
- },
- spec: desiredSpec,
- },
- desired,
- operationId,
- })
- ).toBe('ambiguous')
- })
-})
diff --git a/control-api/test/services.resourceService.test.ts b/control-api/test/services.resourceService.test.ts
index 5da2da662..dde8a7c4f 100644
--- a/control-api/test/services.resourceService.test.ts
+++ b/control-api/test/services.resourceService.test.ts
@@ -253,6 +253,7 @@ describe('ResourceService.updateResource — AP-6 reader-version precondition',
function makeCustomApi(
overrides: {
currentAnnotations?: Record<string, string>
+ currentUid?: string
replace?: ReturnType<typeof vi.fn>
} = {}
) {
@@ -263,6 +264,7 @@ describe('ResourceService.updateResource — AP-6 reader-version precondition',
namespace: 'mcp-host',
resourceVersion: '11',
...(overrides.currentAnnotations && { annotations: overrides.currentAnnotations }),
+ ...(overrides.currentUid && { uid: overrides.currentUid }),
},
spec: { contextRef: 'live' },
}),
@@ -275,14 +277,14 @@ describe('ResourceService.updateResource — AP-6 reader-version precondition',
}
}
- it('uses the caller-provided resourceVersion as the replace precondition (not the server current one)', async () => {
- const customApi = makeCustomApi()
+ it('uses the caller-provided identity and resourceVersion in the replacement', async () => {
+ const customApi = makeCustomApi({ currentUid: 'uid-reader' })
const service = new ResourceService(customApi as never, 'control-plane', { hosts: 'mcp-host' })
await service.updateResource(
'hosts',
'host-a',
- { metadata: { resourceVersion: '10' }, spec: { contextRef: 'edited' } },
+ { metadata: { uid: 'uid-reader', resourceVersion: '10' }, spec: { contextRef: 'edited' } },
'mcp-host'
)
@@ -291,18 +293,22 @@ describe('ResourceService.updateResource — AP-6 reader-version precondition',
// The precondition is the READER's version ('10'), not the fresher
// server version ('11') harvested by the internal read.
expect(replaceArgs.body.metadata.resourceVersion).toBe('10')
+ expect(replaceArgs.body.metadata.uid).toBe('uid-reader')
})
it('surfaces a 409 as K8sConflictError WITHOUT retrying when the reader version is stale', async () => {
const replace = vi.fn().mockRejectedValue(makeConflictError())
- const customApi = makeCustomApi({ replace })
+ const customApi = makeCustomApi({ replace, currentUid: 'uid-reader' })
const service = new ResourceService(customApi as never, 'control-plane', { hosts: 'mcp-host' })
await expect(
service.updateResource(
'hosts',
'host-a',
- { metadata: { resourceVersion: '10' }, spec: { contextRef: 'stale-edit' } },
+ {
+ metadata: { uid: 'uid-reader', resourceVersion: '10' },
+ spec: { contextRef: 'stale-edit' },
+ },
'mcp-host'
)
).rejects.toBeInstanceOf(K8sConflictError)
@@ -311,6 +317,78 @@ describe('ResourceService.updateResource — AP-6 reader-version precondition',
// re-apply the same stale payload over the concurrent write.
expect(customApi.getNamespacedCustomObject).toHaveBeenCalledTimes(1)
expect(replace).toHaveBeenCalledTimes(1)
+ expect(replace.mock.calls[0][0].body.metadata).toMatchObject({
+ uid: 'uid-reader',
+ resourceVersion: '10',
+ })
+ })
+
+ it('retries a UID-only legacy write after a 409 while the refetched object keeps that UID', async () => {
+ const customApi = {
+ getNamespacedCustomObject: vi
+ .fn()
+ .mockResolvedValueOnce({
+ metadata: { uid: 'uid-original', resourceVersion: '1' },
+ spec: {},
+ })
+ .mockResolvedValueOnce({
+ metadata: { uid: 'uid-original', resourceVersion: '2' },
+ spec: {},
+ }),
+ replaceNamespacedCustomObject: vi
+ .fn()
+ .mockRejectedValueOnce(makeConflictError())
+ .mockResolvedValueOnce({ metadata: { uid: 'uid-original', resourceVersion: '3' } }),
+ listNamespacedCustomObject: vi.fn(),
+ }
+ const service = new ResourceService(customApi as never, 'control-plane', { hosts: 'mcp-host' })
+
+ await service.updateResource(
+ 'hosts',
+ 'host-a',
+ { metadata: { uid: 'uid-original' }, spec: { contextRef: 'edited' } },
+ 'mcp-host'
+ )
+
+ expect(customApi.getNamespacedCustomObject).toHaveBeenCalledTimes(2)
+ const attempts = customApi.replaceNamespacedCustomObject.mock.calls.map(
+ call => call[0].body.metadata
+ )
+ expect(attempts).toEqual([
+ expect.objectContaining({ uid: 'uid-original', resourceVersion: '1' }),
+ expect.objectContaining({ uid: 'uid-original', resourceVersion: '2' }),
+ ])
+ })
+
+ it('does not write a same-name replacement after a UID-only retry observes a different UID', async () => {
+ const replace = vi.fn().mockRejectedValueOnce(makeConflictError())
+ const customApi = {
+ getNamespacedCustomObject: vi
+ .fn()
+ .mockResolvedValueOnce({
+ metadata: { uid: 'uid-original', resourceVersion: '1' },
+ spec: {},
+ })
+ .mockResolvedValueOnce({
+ metadata: { uid: 'uid-replacement', resourceVersion: '2' },
+ spec: {},
+ }),
+ replaceNamespacedCustomObject: replace,
+ listNamespacedCustomObject: vi.fn(),
+ }
+ const service = new ResourceService(customApi as never, 'control-plane', { hosts: 'mcp-host' })
+
+ await expect(
+ service.updateResource(
+ 'hosts',
+ 'host-a',
+ { metadata: { uid: 'uid-original' }, spec: { contextRef: 'edited' } },
+ 'mcp-host'
+ )
+ ).rejects.toBeInstanceOf(K8sConflictError)
+
+ expect(customApi.getNamespacedCustomObject).toHaveBeenCalledTimes(2)
+ expect(replace).toHaveBeenCalledTimes(1)
})
it('AP-6 + concurrent wake bump: a stale reader version is rejected 409 while the newer clerum.io/wake-requested on the server is left untouched (no retry re-applies the stale spec)', async () => {
diff --git a/control-api/test/services.secretReferenceService.test.ts b/control-api/test/services.secretReferenceService.test.ts
index f819b3e52..cf45cecc2 100644
--- a/control-api/test/services.secretReferenceService.test.ts
+++ b/control-api/test/services.secretReferenceService.test.ts
@@ -5,53 +5,251 @@ import { findSecretReferenceState } from '../src/services/secretReferenceService
const referencedName = 'referenced-credential'
describe('findSecretReferenceState', () => {
- it('recognizes every current CRD reference shape that can retain a Secret', async () => {
+ it('recognizes every explicitly contracted CRD reference shape', async () => {
const cases = [
{
+ label: 'McpServer auth secret',
namespace: config.mcpServersNamespace,
plural: 'mcpservers',
+ resourceNamespace: config.mcpServersNamespace,
+ resource: { spec: { auth: { secretRef: referencedName } } },
+ },
+ {
+ label: 'McpServer environment secret',
+ namespace: config.mcpServersNamespace,
+ plural: 'mcpservers',
+ resourceNamespace: config.mcpServersNamespace,
+ resource: { spec: { envSecret: { name: referencedName } } },
+ },
+ {
+ label: 'McpServer image pull secret',
+ namespace: config.mcpServersNamespace,
+ plural: 'mcpservers',
+ resourceNamespace: config.mcpServersNamespace,
resource: { spec: { imagePullSecrets: [{ name: referencedName }] } },
},
{
+ label: 'LlmHook image pull secret',
+ namespace: config.llmHooksNamespace,
+ plural: 'llmhooks',
+ resourceNamespace: config.llmHooksNamespace,
+ resource: { spec: { target: { image: { imagePullSecrets: [referencedName] } } } },
+ },
+ {
+ label: 'LlmHook environment secret',
+ namespace: config.llmHooksNamespace,
+ plural: 'llmhooks',
+ resourceNamespace: config.llmHooksNamespace,
+ resource: { spec: { target: { image: { envSecret: referencedName } } } },
+ },
+ {
+ label: 'LlmHook remote auth headers secret',
+ namespace: config.llmHooksNamespace,
+ plural: 'llmhooks',
+ resourceNamespace: config.llmHooksNamespace,
+ resource: { spec: { target: { remote: { authHeadersSecret: referencedName } } } },
+ },
+ {
+ label: 'Host Secret',
+ namespace: config.secretsNamespace,
+ plural: 'hosts',
+ resourceNamespace: config.hostsNamespace,
+ resource: { spec: { secretRef: referencedName } },
+ },
+ {
+ label: 'CommunicationChannel credential Secret',
+ namespace: config.communicationChannelsNamespace,
+ plural: 'communicationchannels',
+ resourceNamespace: config.communicationChannelsNamespace,
+ resource: { spec: { credentialsSecretRef: { name: referencedName } } },
+ },
+ {
+ label: 'WorkflowRecipe agent Secret with an explicit namespace',
namespace: config.sandboxNamespace,
plural: 'workflowrecipes',
- resource: { spec: { workloads: [{ imagePullSecrets: [referencedName] }] } },
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ agent: {
+ secretRef: { name: referencedName, namespace: config.sandboxNamespace },
+ },
+ },
+ },
},
{
+ label: 'WorkflowRecipe snippet Secret',
namespace: config.sandboxNamespace,
plural: 'workflowrecipes',
- resource: { spec: { oauth: { clientIdRef: { name: referencedName, key: 'client-id' } } } },
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ steps: [
+ {
+ run: {
+ capabilities: {
+ secrets: [{ secretRef: { name: referencedName, key: 'api-key' } }],
+ },
+ },
+ },
+ ],
+ },
+ },
},
{
+ label: 'WorkflowRecipe regular workload environment Secret',
namespace: config.sandboxNamespace,
plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: { spec: { workloads: [{ id: 'worker', envSecret: { name: referencedName } }] } },
+ },
+ {
+ label: 'WorkflowRecipe transport workload environment Secret',
+ namespace: config.mcpServersNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
resource: {
- spec: { oauth: { clientSecretRef: { name: referencedName, key: 'client-secret' } } },
+ spec: {
+ workloads: [
+ { id: 'transport', transport: { type: 'sse' }, envSecret: { name: referencedName } },
+ ],
+ },
},
},
{
- namespace: config.llmHooksNamespace,
- plural: 'llmhooks',
- resource: { spec: { target: { image: { imagePullSecrets: [referencedName] } } } },
+ label: 'WorkflowRecipe UI workload environment Secret',
+ namespace: config.sandboxUiNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ ui: { workloadRef: 'ui' },
+ workloads: [{ id: 'ui', envSecret: { name: referencedName } }],
+ },
+ },
},
{
- namespace: config.llmHooksNamespace,
- plural: 'llmhooks',
- resource: { spec: { target: { remote: { authHeadersSecret: referencedName } } } },
+ label: 'WorkflowRecipe UI workload image pull Secret',
+ namespace: config.sandboxUiNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ ui: { workloadRef: 'ui' },
+ workloads: [{ id: 'ui', imagePullSecrets: [referencedName] }],
+ },
+ },
+ },
+ {
+ label: 'WorkflowRecipe OAuth client ID Secret',
+ namespace: config.sandboxNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: { oauthClients: [{ clientIdRef: { name: referencedName, key: 'client-id' } }] },
+ },
+ },
+ {
+ label: 'WorkflowRecipe OAuth client Secret',
+ namespace: config.sandboxNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ oauthClients: [{ clientSecretRef: { name: referencedName, key: 'client-secret' } }],
+ },
+ },
+ },
+ {
+ label: 'WorkflowRecipe webhook verification Secret',
+ namespace: config.sandboxNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ webhooks: [{ verification: { secretRef: { name: referencedName, key: 'signing' } } }],
+ },
+ },
+ },
+ {
+ label: 'WorkflowRecipe webhook setup handshake Secret',
+ namespace: config.sandboxNamespace,
+ plural: 'workflowrecipes',
+ resourceNamespace: config.sandboxNamespace,
+ resource: {
+ spec: {
+ webhooks: [
+ {
+ verification: {
+ setupHandshake: { secretRef: { name: referencedName, key: 'verify' } },
+ },
+ },
+ ],
+ },
+ },
},
]
- for (const { namespace, plural, resource } of cases) {
+ for (const { label, namespace, plural, resourceNamespace, resource } of cases) {
const reader = {
listResource: vi.fn(async (requestedPlural: string, requestedNamespace?: string) =>
- requestedPlural === plural && requestedNamespace === namespace ? [resource] : []
+ requestedPlural === plural && requestedNamespace === resourceNamespace ? [resource] : []
),
}
- await expect(findSecretReferenceState(reader as never, referencedName, namespace)).resolves.toBe(
- 'referenced'
- )
- expect(reader.listResource).toHaveBeenCalledWith(plural, namespace)
+ await expect(
+ findSecretReferenceState(reader as never, referencedName, namespace),
+ label
+ ).resolves.toBe('referenced')
+ expect(reader.listResource).toHaveBeenCalledWith(plural, resourceNamespace)
+ }
+ })
+
+ it('does not treat uncontracted reference-shaped values as Secret dependencies', async () => {
+ const reader = {
+ listResource: vi.fn(async (plural: string, namespace?: string) =>
+ plural === 'workflowrecipes' && namespace === config.sandboxNamespace
+ ? [
+ {
+ spec: {
+ extraCredentials: { name: referencedName, key: 'api-key' },
+ },
+ },
+ ]
+ : []
+ ),
+ }
+
+ await expect(
+ findSecretReferenceState(reader as never, referencedName, config.sandboxNamespace)
+ ).resolves.toBe('not-referenced')
+ })
+
+ it('binds ordinary WorkflowRecipe workloads to sandbox-recipes, not every workflow Secret namespace', async () => {
+ const reader = {
+ listResource: vi.fn(async (plural: string, namespace?: string) =>
+ plural === 'workflowrecipes' && namespace === config.sandboxNamespace
+ ? [{ spec: { workloads: [{ id: 'worker', envSecret: { name: referencedName } }] } }]
+ : []
+ ),
+ }
+
+ await expect(
+ findSecretReferenceState(reader as never, referencedName, config.mcpServersNamespace)
+ ).resolves.toBe('not-referenced')
+ })
+
+ it('fails closed when no contract applies or a required CRD list cannot be read', async () => {
+ const reader = { listResource: vi.fn(async () => []) }
+ await expect(
+ findSecretReferenceState(reader as never, referencedName, 'untracked-namespace')
+ ).resolves.toBe('unknown')
+ expect(reader.listResource).not.toHaveBeenCalled()
+
+ const unavailableReader = {
+ listResource: vi.fn(async () => Promise.reject(new Error('unavailable'))),
}
+ await expect(
+ findSecretReferenceState(unavailableReader as never, referencedName, config.sandboxNamespace)
+ ).resolves.toBe('unknown')
})
})
diff --git a/control-api/test/services.secretService.test.ts b/control-api/test/services.secretService.test.ts
index 49e796502..9eb7d0335 100644
--- a/control-api/test/services.secretService.test.ts
+++ b/control-api/test/services.secretService.test.ts
@@ -555,6 +555,18 @@ const FORBIDDEN_SECRET_TYPES: readonly string[] = [
'helm.sh/release.v1',
]
+const NON_MUTABLE_PRESERVED_SECRET_TYPES: readonly string[] = [
+ 'kubernetes.io/service-account-token',
+ 'bootstrap.kubernetes.io/token',
+ 'helm.sh/release.v1',
+]
+
+const MUTABLE_PRESERVED_SECRET_TYPES: readonly string[] = [
+ 'kubernetes.io/basic-auth',
+ 'kubernetes.io/ssh-auth',
+ 'example.com/custom',
+]
+
// Annotation keys that must be stripped/rejected on write (infra tier — always blocked).
const DANGEROUS_ANNOTATION_KEYS: readonly string[] = [
'kubectl.kubernetes.io/last-applied-configuration',
@@ -854,18 +866,67 @@ describe('SecretService — preserved Secret state is constrained before mutatio
expect(body).not.toHaveProperty('metadata.annotations')
})
- it('rejects update when an omitted type preserves a forbidden existing type', async () => {
+ it.each(NON_MUTABLE_PRESERVED_SECRET_TYPES)(
+ 'rejects update when an omitted type preserves the managed %s type',
+ async type => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: {},
+ type,
+ })
+
+ await expect(
+ svc.updateSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).rejects.toBeInstanceOf(InvalidSecretTypeError)
+ expect(coreApi.replaceNamespacedSecret).not.toHaveBeenCalled()
+ }
+ )
+
+ it.each([
+ {
+ operation: 'update',
+ call: () =>
+ svc.updateSecret({
+ name: 's',
+ namespace: 'test-ns',
+ type: 'Opaque',
+ stringData: { k: 'v' },
+ }),
+ write: () => coreApi.replaceNamespacedSecret,
+ },
+ {
+ operation: 'merge',
+ call: () =>
+ svc.mergeSecret({
+ name: 's',
+ namespace: 'test-ns',
+ type: 'Opaque',
+ stringData: { k: 'v' },
+ }),
+ write: () => coreApi.patchNamespacedSecret,
+ },
+ ])('rejects $operation when an explicit safe type masks a managed live type', async testCase => {
coreApi.readNamespacedSecret.mockResolvedValueOnce({
metadata: {},
type: 'kubernetes.io/service-account-token',
})
- await expect(
- svc.updateSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
- ).rejects.toBeInstanceOf(InvalidSecretTypeError)
- expect(coreApi.replaceNamespacedSecret).not.toHaveBeenCalled()
+ await expect(testCase.call()).rejects.toBeInstanceOf(InvalidSecretTypeError)
+ expect(testCase.write()).not.toHaveBeenCalled()
})
+ it.each(MUTABLE_PRESERVED_SECRET_TYPES)(
+ 'allows update when an omitted type preserves the non-managed %s type',
+ async type => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({ metadata: {}, type })
+
+ await expect(
+ svc.updateSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).resolves.toMatchObject({ name: 's', namespace: 'test-ns' })
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ expect(coreApi.replaceNamespacedSecret.mock.calls[0][0].body.type).toBe(type)
+ }
+ )
+
it('allows update when omitted annotations preserve infrastructure metadata', async () => {
coreApi.readNamespacedSecret.mockResolvedValueOnce({
metadata: { annotations: { 'meta.helm.sh/release-name': 'release' } },
@@ -878,16 +939,76 @@ describe('SecretService — preserved Secret state is constrained before mutatio
expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
})
- it('rejects merge when the preserved existing type is forbidden', async () => {
+ it.each(MUTABLE_PRESERVED_SECRET_TYPES)(
+ 'allows merge when an omitted type preserves the non-managed %s type',
+ async type => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({ metadata: {}, type })
+
+ await expect(
+ svc.mergeSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).resolves.toMatchObject({ name: 's', namespace: 'test-ns' })
+ expect(coreApi.patchNamespacedSecret).toHaveBeenCalledOnce()
+ expect(coreApi.patchNamespacedSecret.mock.calls[0][0].body.type).toBeUndefined()
+ }
+ )
+
+ it.each([
+ { kind: 'infrastructure', key: 'meta.helm.sh/release-name' },
+ { kind: 'platform', key: 'clerum.io/catalog-id' },
+ ])('allows update to preserve an unchanged live $kind annotation', async ({ key }) => {
+ const annotations = { [key]: 'server-owned' }
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations, resourceVersion: '15' },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.updateSecret({
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { ...annotations },
+ stringData: { k: 'v' },
+ })
+ ).resolves.toMatchObject({ name: 's', namespace: 'test-ns' })
+
+ expect(coreApi.readNamespacedSecret).toHaveBeenCalledWith({ namespace: 'test-ns', name: 's' })
+ expect(coreApi.replaceNamespacedSecret.mock.calls[0][0].body.metadata.annotations).toEqual(
+ annotations
+ )
+ })
+
+ it.each([
+ { kind: 'introduces', key: 'meta.helm.sh/release-name', existing: {}, requested: 'release-a' },
+ {
+ kind: 'changes',
+ key: 'meta.helm.sh/release-name',
+ existing: { 'meta.helm.sh/release-name': 'release-a' },
+ requested: 'release-b',
+ },
+ { kind: 'introduces', key: 'clerum.io/catalog-id', existing: {}, requested: 'catalog-a' },
+ {
+ kind: 'changes',
+ key: 'clerum.io/catalog-id',
+ existing: { 'clerum.io/catalog-id': 'catalog-a' },
+ requested: 'catalog-b',
+ },
+ ])('rejects update that $kind a reserved annotation', async ({ key, existing, requested }) => {
coreApi.readNamespacedSecret.mockResolvedValueOnce({
- metadata: {},
- type: 'kubernetes.io/ssh-auth',
+ metadata: { annotations: existing, resourceVersion: '16' },
+ type: 'Opaque',
})
await expect(
- svc.mergeSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
- ).rejects.toBeInstanceOf(InvalidSecretTypeError)
- expect(coreApi.patchNamespacedSecret).not.toHaveBeenCalled()
+ svc.updateSecret({
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { [key]: requested },
+ stringData: { k: 'v' },
+ })
+ ).rejects.toBeInstanceOf(DangerousAnnotationError)
+
+ expect(coreApi.readNamespacedSecret).toHaveBeenCalledWith({ namespace: 'test-ns', name: 's' })
+ expect(coreApi.replaceNamespacedSecret).not.toHaveBeenCalled()
})
it('preserves unknown platform metadata without locking data-only rotation', async () => {
@@ -939,7 +1060,7 @@ describe('SecretService — forbidden Secret types never reach the apiserver', (
name: 'updateSecret',
call: type =>
svc.updateSecret({ name: 's', namespace: 'test-ns', type, stringData: { k: 'v' } }),
- apiSurface: ['readNamespacedSecret', 'replaceNamespacedSecret'],
+ apiSurface: ['replaceNamespacedSecret'],
},
{
name: 'mergeSecret',
@@ -983,7 +1104,7 @@ describe('SecretService — forbidden Secret types never reach the apiserver', (
})
})
-describe('SecretService — dangerous annotations never reach the apiserver', () => {
+describe('SecretService — dangerous annotations never reach a mutation endpoint', () => {
let coreApi: CoreApiMock
let svc: SecretService
@@ -995,26 +1116,29 @@ describe('SecretService — dangerous annotations never reach the apiserver', ()
const writeOps: ReadonlyArray<{
name: string
call: (annotations: Record<string, string>) => Promise<unknown>
- apiSurface: (keyof CoreApiMock)[]
+ writeSurface: keyof CoreApiMock
+ readsLiveSecret: boolean
}> = [
{
name: 'createSecret',
call: annotations =>
svc.createSecret({ name: 's', namespace: 'test-ns', annotations, stringData: { k: 'v' } }),
- apiSurface: ['createNamespacedSecret'],
+ writeSurface: 'createNamespacedSecret',
+ readsLiveSecret: false,
},
{
name: 'updateSecret',
call: annotations =>
svc.updateSecret({ name: 's', namespace: 'test-ns', annotations, stringData: { k: 'v' } }),
- apiSurface: ['readNamespacedSecret', 'replaceNamespacedSecret'],
+ writeSurface: 'replaceNamespacedSecret',
+ readsLiveSecret: true,
},
]
for (const op of writeOps) {
describe(op.name, () => {
for (const badKey of DANGEROUS_ANNOTATION_KEYS) {
- it(`rejects annotation "${badKey}" with a 400 and never calls the apiserver`, async () => {
+ it(`rejects annotation "${badKey}" with a 400 and never calls a mutation endpoint`, async () => {
const err = await op.call({ [badKey]: 'value' }).then(
() => {
throw new Error('expected the write to reject')
@@ -1023,17 +1147,15 @@ describe('SecretService — dangerous annotations never reach the apiserver', ()
)
expect(err).toBeInstanceOf(DangerousAnnotationError)
expect((err as DangerousAnnotationError).status).toBe(400)
- for (const surface of op.apiSurface) {
- expect(coreApi[surface]).not.toHaveBeenCalled()
- }
+ expect(coreApi[op.writeSurface]).not.toHaveBeenCalled()
+ if (op.readsLiveSecret) expect(coreApi.readNamespacedSecret).toHaveBeenCalledOnce()
})
}
for (const safeKey of SAFE_ANNOTATION_KEYS) {
it(`lets safe annotation "${safeKey}" through to the apiserver`, async () => {
await op.call({ [safeKey]: 'value' })
- const writeSurface = op.apiSurface[op.apiSurface.length - 1]
- expect(coreApi[writeSurface]).toHaveBeenCalledOnce()
+ expect(coreApi[op.writeSurface]).toHaveBeenCalledOnce()
})
}
})
diff --git a/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts b/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts
new file mode 100644
index 000000000..6a546bb77
--- /dev/null
+++ b/control-api/test/utils.auth.mcpSecretDeleteProof.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ MCP_SECRET_DELETE_PROOF_TTL_SECONDS,
+ createMcpSecretDeleteProof,
+ mcpSecretDeleteProofCookieName,
+ verifyMcpSecretDeleteProof,
+} from '../src/utils/auth/mcpSecretDeleteProof.js'
+
+const adminSession = 'test-admin-session'
+const claims = {
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ uid: 'uid-linear-credentials',
+ resourceVersion: '1',
+}
+
+describe('MCP Secret delete proof', () => {
+ it('binds exactly the Secret identity claims to the admin session', () => {
+ const now = 1_700_000_000_000
+ const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(now)
+
+ try {
+ const proof = createMcpSecretDeleteProof(claims, adminSession)
+
+ expect(verifyMcpSecretDeleteProof(proof, adminSession)).toEqual({
+ ...claims,
+ exp: Math.floor(now / 1000) + MCP_SECRET_DELETE_PROOF_TTL_SECONDS,
+ })
+ expect(Object.keys(verifyMcpSecretDeleteProof(proof, adminSession) ?? {}).sort()).toEqual([
+ 'exp',
+ 'name',
+ 'namespace',
+ 'resourceVersion',
+ 'uid',
+ ])
+ } finally {
+ nowSpy.mockRestore()
+ }
+ })
+
+ it('rejects a proof when its session binding, 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, adminSession)
+ const [payload, signature] = proof.split('.')
+
+ expect(verifyMcpSecretDeleteProof(proof, 'different-admin-session')).toBeNull()
+ expect(verifyMcpSecretDeleteProof(`${payload}.${signature}x`, adminSession)).toBeNull()
+
+ nowSpy.mockReturnValue(now + (MCP_SECRET_DELETE_PROOF_TTL_SECONDS + 1) * 1000)
+ expect(verifyMcpSecretDeleteProof(proof, adminSession)).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 1b6df4f24..5f1c244da 100644
--- a/control-ui/components/CreateMcpServerForm/index.tsx
+++ b/control-ui/components/CreateMcpServerForm/index.tsx
@@ -533,11 +533,16 @@ export function CreateMcpServerForm({
const willCreateSecret =
useEnvSecret && envSecretName.trim().length > 0 && Object.keys(secretData).length > 0
- let createdSecretIdentity: SecretIdentity | null = null
+ let createdSecretName: string | null = null
+ let createdSecretIdentity: SecretIdentity | undefined
try {
if (willCreateSecret) {
- const created = await createMcpSecret(envSecretName.trim(), secretData)
- createdSecretIdentity = { uid: created.uid, resourceVersion: created.resourceVersion }
+ const secretName = envSecretName.trim()
+ const created = await createMcpSecret(secretName, secretData)
+ createdSecretName = secretName
+ if (created.uid && created.resourceVersion) {
+ createdSecretIdentity = { uid: created.uid, resourceVersion: created.resourceVersion }
+ }
}
await createMcpServer({
@@ -576,17 +581,25 @@ export function CreateMcpServerForm({
onCreated()
}, 600)
} catch (submitError) {
- // Rollback: if we created the Secret but the CRD (or anything after)
- // failed, the Secret is orphan — best-effort delete.
- if (createdSecretIdentity) {
+ // 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.
+ let cleanupError: unknown
+ if (createdSecretName) {
try {
- await deleteMcpSecret(envSecretName.trim(), createdSecretIdentity)
- } catch {
- // best-effort rollback; swallow — the operator already sees the
- // primary error below.
+ await deleteMcpSecret(createdSecretName, createdSecretIdentity)
+ } catch (error) {
+ cleanupError = error
}
}
- setError(formatCreateError(submitError))
+ const primaryError = formatCreateError(submitError)
+ setError(
+ cleanupError
+ ? `${primaryError} Cleanup of the created Secret also failed: ${formatCreateError(
+ cleanupError
+ )}. Refresh the page and review the Secret before taking further action.`
+ : primaryError
+ )
} finally {
setSubmitting(false)
}
diff --git a/control-ui/components/SecretsTable.tsx b/control-ui/components/SecretsTable.tsx
index a79ba6317..bab15bce1 100644
--- a/control-ui/components/SecretsTable.tsx
+++ b/control-ui/components/SecretsTable.tsx
@@ -358,7 +358,12 @@ export function SecretsTable({
async function deleteRecipeSecretRow(row: RecipeSecretRow) {
const { name, namespace, uid, resourceVersion } = row
if (!uid || !resourceVersion) {
- setRecipeError(`Secret ${name} has no current identity; refresh before deleting it.`)
+ // Existing Secret deletes never use the legacy bodyless path. It is
+ // reserved for the create form's rollback immediately after an older
+ // create endpoint omitted identity fields.
+ setRecipeError(
+ `Secret ${name} has no current identity. Refresh the page and review the latest state before deleting it.`
+ )
return
}
const ok = await confirm({
@@ -841,10 +846,7 @@ export function SecretsTable({
? 'Deleting…'
: 'Delete',
danger: true,
- disabled:
- !row.uid ||
- !row.resourceVersion ||
- recipeDeletingName === `${row.namespace}/${row.name}`,
+ disabled: recipeDeletingName === `${row.namespace}/${row.name}`,
onClick: () => void deleteRecipeSecretRow(row),
},
]}
diff --git a/control-ui/components/__tests__/CreateMcpServerForm.test.tsx b/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
index c9ea205cd..ccff30124 100644
--- a/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
+++ b/control-ui/components/__tests__/CreateMcpServerForm.test.tsx
@@ -539,6 +539,76 @@ describe('CreateMcpServerForm — envSecret guardrails', () => {
})
})
+ 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',
+ namespace: 'mcp-server',
+ })
+ ;(api.createMcpServer as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+ new Error('Connector create failed')
+ )
+
+ render(<CreateMcpServerForm onCancel={vi.fn()} onCreated={vi.fn()} />)
+ await fillRequiredBasics()
+ enableEnvSecret('legacy-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: 'test-value' },
+ })
+
+ fireEvent.click(screen.getByRole('button', { name: 'Create connector' }))
+
+ await waitFor(() => {
+ expect(api.deleteMcpSecret).toHaveBeenCalledWith('legacy-credentials', undefined)
+ })
+ expect(screen.getByText('Connector create failed')).toBeInTheDocument()
+ })
+
+ it('preserves the primary error when legacy rollback fails against a newer delete API', async () => {
+ ;(api.createMcpSecret as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+ name: 'mixed-version-credentials',
+ namespace: 'mcp-server',
+ })
+ ;(api.createMcpServer as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+ new Error('Connector create failed')
+ )
+ ;(api.deleteMcpSecret as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+ new Error('428 Precondition Required - current identity required')
+ )
+
+ render(<CreateMcpServerForm onCancel={vi.fn()} onCreated={vi.fn()} />)
+ await fillRequiredBasics()
+ enableEnvSecret('mixed-version-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: 'test-value' },
+ })
+
+ fireEvent.click(screen.getByRole('button', { name: 'Create connector' }))
+
+ await waitFor(() => {
+ expect(api.deleteMcpSecret).toHaveBeenCalledWith('mixed-version-credentials', undefined)
+ })
+ expect(screen.getByText(/Connector create failed/)).toBeInTheDocument()
+ expect(
+ screen.getByText(
+ /Cleanup of the created Secret also failed: 428 Precondition Required - current identity required\. Refresh the page and review the Secret before taking further action\./
+ )
+ ).toBeInTheDocument()
+ })
+
it('happy path: creates Secret then CRD, no rollback', async () => {
const onCreated = vi.fn()
render(<CreateMcpServerForm onCancel={vi.fn()} onCreated={onCreated} />)
diff --git a/control-ui/components/__tests__/SecretsTable.test.tsx b/control-ui/components/__tests__/SecretsTable.test.tsx
index fd084a260..4963c6c99 100644
--- a/control-ui/components/__tests__/SecretsTable.test.tsx
+++ b/control-ui/components/__tests__/SecretsTable.test.tsx
@@ -8,7 +8,13 @@ import {
waitFor,
within,
} from '@testing-library/react'
-import { apiSend, getMcpServers, getRecipeSecrets, getRecipes } from '../../lib/api'
+import {
+ apiSend,
+ deleteRecipeSecret,
+ getMcpServers,
+ getRecipeSecrets,
+ getRecipes,
+} from '../../lib/api'
import { buildSecretSummary } from '../../test/fixtures/secretSummary'
import { SecretsTable } from '../SecretsTable'
import { ToastProvider } from '../Toast'
@@ -25,6 +31,7 @@ vi.mock('../../lib/api', async () => {
return {
...actual,
apiSend: vi.fn(),
+ deleteRecipeSecret: vi.fn(),
getMcpServers: vi.fn(),
getRecipeSecrets: vi.fn(),
getRecipes: vi.fn(),
@@ -32,6 +39,7 @@ vi.mock('../../lib/api', async () => {
})
const apiSendMock = vi.mocked(apiSend)
+const deleteRecipeSecretMock = vi.mocked(deleteRecipeSecret)
const getMcpServersMock = vi.mocked(getMcpServers)
const getRecipeSecretsMock = vi.mocked(getRecipeSecrets)
const getRecipesMock = vi.mocked(getRecipes)
@@ -41,6 +49,8 @@ const getRecipesMock = vi.mocked(getRecipes)
beforeEach(() => {
apiSendMock.mockReset()
apiSendMock.mockResolvedValue(undefined as never)
+ deleteRecipeSecretMock.mockReset()
+ deleteRecipeSecretMock.mockResolvedValue(undefined as never)
})
function renderTable(
@@ -377,6 +387,85 @@ describe('SecretsTable — connector marketplace source', () => {
})
})
+describe('SecretsTable — recipe deletion identity', () => {
+ beforeEach(() => {
+ getMcpServersMock.mockReset()
+ getRecipeSecretsMock.mockReset()
+ getRecipesMock.mockReset()
+ mockReplace.mockClear()
+ mockPush.mockClear()
+ })
+
+ afterEach(() => {
+ cleanup()
+ })
+
+ it('requires a refresh before deleting a legacy row without identity', async () => {
+ getRecipeSecretsMock.mockResolvedValue({
+ items: [
+ {
+ name: 'legacy-recipe-credentials',
+ namespace: 'sandbox-recipes',
+ keys: ['api-key'],
+ ownership: { kind: 'shared' },
+ },
+ ],
+ })
+ getRecipesMock.mockResolvedValue({ items: [] })
+
+ renderTable('recipe')
+
+ const trigger = await screen.findByRole('button', {
+ name: 'Actions for recipe secret legacy-recipe-credentials',
+ })
+ fireEvent.click(trigger)
+ const deleteAction = screen.getByRole('menuitem', { name: 'Delete' })
+ expect(deleteAction).not.toBeDisabled()
+ fireEvent.click(deleteAction)
+
+ expect(
+ await screen.findByText(
+ 'Secret legacy-recipe-credentials has no current identity. Refresh the page and review the latest state before deleting it.'
+ )
+ ).toBeInTheDocument()
+ expect(deleteRecipeSecretMock).not.toHaveBeenCalled()
+ })
+
+ it('sends the listed identity when deleting a current recipe Secret', async () => {
+ getRecipeSecretsMock.mockResolvedValue({
+ items: [
+ {
+ name: 'current-recipe-credentials',
+ namespace: 'sandbox-recipes',
+ keys: ['api-key'],
+ ownership: { kind: 'shared' },
+ uid: 'uid-current-recipe-credentials',
+ resourceVersion: '7',
+ },
+ ],
+ })
+ getRecipesMock.mockResolvedValue({ items: [] })
+
+ renderTable('recipe')
+
+ const trigger = await screen.findByRole('button', {
+ name: 'Actions for recipe secret current-recipe-credentials',
+ })
+ fireEvent.click(trigger)
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Delete' }))
+ const dialog = await screen.findByRole('alertdialog', { name: 'Delete Recipe Secret' })
+ fireEvent.click(within(dialog).getByRole('button', { name: 'Delete' }))
+
+ await waitFor(() => {
+ expect(deleteRecipeSecretMock).toHaveBeenCalledWith(
+ 'current-recipe-credentials',
+ 'sandbox-recipes',
+ { uid: 'uid-current-recipe-credentials', resourceVersion: '7' }
+ )
+ })
+ })
+})
+
describe('SecretsTable — recipe pending refs', () => {
beforeEach(() => {
getMcpServersMock.mockReset()
diff --git a/control-ui/e2e/qa-recorder-connector-edit.spec.ts b/control-ui/e2e/qa-recorder-connector-edit.spec.ts
index 1117c2a6a..51b40a404 100644
--- a/control-ui/e2e/qa-recorder-connector-edit.spec.ts
+++ b/control-ui/e2e/qa-recorder-connector-edit.spec.ts
@@ -5,7 +5,7 @@
// egress. Guarded by QA_RECORDER_CONFIRM_MUTATIONS; connector then context are
// deleted via the Control API in a finally.
import { type Page, expect, test } from '@playwright/test'
-import { requireSecretIdentity, type SecretIdentity } from '../test-utils/secretIdentity'
+import { type SecretIdentity, requireSecretIdentity } from '../test-utils/secretIdentity'
import {
CONTROL_API_URL,
CONTROL_UI_URL,
@@ -28,7 +28,11 @@ const MOCK_MCP_IMAGE = process.env.TEST_MOCK_MCP_IMAGE ?? 'clerum/mock-mcp-serve
// The connector-form's Transport Type and Managed selects are not label-associated,
// so use their visible field label as the stable local scope for those controls.
async function fieldSelect(page: Page, fieldLabelText: string, value: string): Promise<void> {
- await page.getByText(fieldLabelText, { exact: true }).locator('..').getByRole('combobox').selectOption(value)
+ await page
+ .getByText(fieldLabelText, { exact: true })
+ .locator('..')
+ .getByRole('combobox')
+ .selectOption(value)
}
async function createEmptyContext(page: Page, contextName: string): Promise<void> {
@@ -78,9 +82,6 @@ async function createDiscoveryConnector(
await fieldSelect(page, 'Transport Type', 'stdio')
await expect(page.locator('input[type="number"]')).toHaveCount(0)
await fieldSelect(page, 'Managed', 'false')
- await page.getByLabel('Egress mode').selectOption('exact-cidr')
- await page.getByLabel('Allowed CIDRs/IPs').fill('8.8.8.8/32')
- await page.getByLabel('Allowed ports').fill('443')
await page.getByRole('button', { name: 'Continue', exact: true }).click()
@@ -94,9 +95,9 @@ async function createDiscoveryConnector(
await page.getByRole('button', { name: 'Continue', exact: true }).click()
- await expect(
- page.getByRole('radio', { name: /^No credentials required/ })
- ).toBeVisible({ timeout: 20_000 })
+ await expect(page.getByRole('radio', { name: /^No credentials required/ })).toBeVisible({
+ timeout: 20_000,
+ })
await page.getByRole('radio', { name: /^No credentials required/ }).check()
await page.getByRole('button', { name: 'Create connector', exact: true }).click()
@@ -156,6 +157,10 @@ test.describe('optional QA recorder: Control UI connector edit', () => {
await expect(meta.getByText('qa-recorder/example:dev')).toBeVisible()
await expect(meta.getByText(contextName)).toBeVisible()
+ // The connector starts closed, so the following persistence check proves a
+ // real edit rather than re-reading setup data.
+ await expect(page.getByLabel('Egress mode')).toHaveValue('none')
+
// External Egress: switch to exact-CIDR mode and add one public CIDR + port.
// 8.8.8.8/32 is a valid public target; the model rejects private/doc ranges.
await page.getByLabel('Egress mode').selectOption('exact-cidr')
@@ -167,6 +172,20 @@ test.describe('optional QA recorder: Control UI connector edit', () => {
page.getByText(`Connector ${connectorName} updated.`, { exact: true })
).toBeVisible({ timeout: 20_000 })
+ await test.step('reopen the connector and read its persisted egress through the UI', async () => {
+ await expect(page).toHaveURL(/\/connectors$/, { timeout: 20_000 })
+ await expect(
+ page.getByRole('button', { name: `Expand connector ${connectorName}` })
+ ).toBeVisible({ timeout: 20_000 })
+ await openConnectorEditor(page, connectorName)
+ await expect(
+ page.getByRole('heading', { name: `Edit Connector: ${connectorName}`, exact: true })
+ ).toBeVisible({ timeout: 20_000 })
+ await expect(page.getByLabel('Egress mode')).toHaveValue('exact-cidr')
+ await expect(page.getByLabel('Allowed CIDRs/IPs')).toHaveValue('8.8.8.8/32')
+ await expect(page.getByLabel('Allowed ports')).toHaveValue('443')
+ })
+
await screenshotAndLog(page, testInfo, 'control-ui-connector-edit')
} finally {
await directApi(
@@ -263,7 +282,9 @@ test.describe('optional QA recorder: Control UI connector edit', () => {
// The connector edit screen is split into tabs; the rotation flow lives
// on the Credentials tab — navigate there via the visible tab.
await page.getByRole('tab', { name: 'Credentials', exact: true }).click()
- await expect(page.getByRole('heading', { name: 'Update credentials', exact: true })).toBeVisible({
+ await expect(
+ page.getByRole('heading', { name: 'Update credentials', exact: true })
+ ).toBeVisible({
timeout: 20_000,
})
diff --git a/control-ui/e2e/registry-install.spec.ts b/control-ui/e2e/registry-install.spec.ts
index d02a7d459..dc21c07a3 100644
--- a/control-ui/e2e/registry-install.spec.ts
+++ b/control-ui/e2e/registry-install.spec.ts
@@ -47,6 +47,7 @@
*/
import { type Page, expect, test } from '@playwright/test'
import { setTimeout as delay } from 'node:timers/promises'
+import { type SecretIdentity, requireSecretIdentity } from '../test-utils/secretIdentity'
const BASE_API = process.env.CONTROL_API_URL || 'http://localhost:8090'
const REGISTRY_BASE = process.env.REGISTRY_URL || 'http://localhost:8085'
@@ -91,16 +92,6 @@ async function api(
return { status: resp.status, data }
}
-type ObjectIdentity = { uid: string; resourceVersion: string }
-
-function requireObjectIdentity(value: unknown, operation: string): ObjectIdentity {
- const record = value as { uid?: unknown; resourceVersion?: unknown }
- if (typeof record?.uid !== 'string' || typeof record.resourceVersion !== 'string') {
- throw new Error(`${operation} did not return a complete object identity`)
- }
- return { uid: record.uid, resourceVersion: record.resourceVersion }
-}
-
async function login(page: Page) {
// Public authentication entry; never a terminal/deep-link state.
await page.goto('/')
@@ -1720,9 +1711,9 @@ test.describe('J. Operator Egress Editor Journeys', () => {
const deferredEnvSecretName = uniqueE2EName('e2e-deferred-creds')
const deferredSandboxUiEntryName = uniqueE2EName('e2e-sandbox-ui-secret')
const deferredSandboxUiSecretName = uniqueE2EName('e2e-sandbox-ui-creds')
- let manualPendingIdentity: ObjectIdentity | null = null
- let deferredEnvIdentity: ObjectIdentity | null = null
- let deferredSandboxUiIdentity: ObjectIdentity | null = null
+ let manualPendingIdentity: SecretIdentity | null = null
+ let deferredEnvIdentity: SecretIdentity | null = null
+ let deferredSandboxUiIdentity: SecretIdentity | null = null
const overLimitEntryName = uniqueE2EName('e2e-overlimit')
let installedRegistryRecipeName = ''
let installedDeferredEnvSecretRecipeName = ''
@@ -2010,7 +2001,11 @@ test.describe('J. Operator Egress Editor Journeys', () => {
const pendingManifestEditor = page.locator('textarea')
await expect(pendingManifestEditor).toHaveCount(1)
await pendingManifestEditor.fill(
- JSON.stringify(manualPendingSecretRecipe(manualPendingRecipeName, manualPendingSecretName), null, 2)
+ JSON.stringify(
+ manualPendingSecretRecipe(manualPendingRecipeName, manualPendingSecretName),
+ null,
+ 2
+ )
)
await page.getByRole('button', { name: 'Review manifest' }).click()
await expect(page.getByText(/Manifest review passed/)).toBeVisible()
@@ -2105,7 +2100,7 @@ test.describe('J. Operator Egress Editor Journeys', () => {
await page.getByRole('button', { name: 'Create secret' }).click()
const createdManualPending = await createRecipeSecretResponse
expect(createdManualPending.status()).toBe(201)
- manualPendingIdentity = requireObjectIdentity(
+ manualPendingIdentity = requireSecretIdentity(
await createdManualPending.json(),
'create manual pending recipe credential'
)
@@ -2471,7 +2466,7 @@ test.describe('J. Operator Egress Editor Journeys', () => {
await page.getByRole('button', { name: 'Create secret' }).click()
const createdDeferredEnv = await createRecipeSecretResponse
expect(createdDeferredEnv.status()).toBe(201)
- deferredEnvIdentity = requireObjectIdentity(
+ deferredEnvIdentity = requireSecretIdentity(
await createdDeferredEnv.json(),
'create deferred recipe credential'
)
@@ -2603,7 +2598,7 @@ test.describe('J. Operator Egress Editor Journeys', () => {
await page.getByRole('button', { name: 'Create secret' }).click()
const createdDeferredSandboxUi = await createRecipeSecretResponse
expect(createdDeferredSandboxUi.status()).toBe(201)
- deferredSandboxUiIdentity = requireObjectIdentity(
+ deferredSandboxUiIdentity = requireSecretIdentity(
await createdDeferredSandboxUi.json(),
'create sandbox-ui recipe credential'
)
diff --git a/control-ui/lib/__tests__/mcpIdentity.test.ts b/control-ui/lib/__tests__/mcpIdentity.test.ts
new file mode 100644
index 000000000..e37d7de4f
--- /dev/null
+++ b/control-ui/lib/__tests__/mcpIdentity.test.ts
@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createMcpSecret, deleteMcpSecret, formatApiError } from '../api'
+
+function jsonResponse(body: unknown, status = 200, statusText = 'OK'): Response {
+ return {
+ ok: status >= 200 && status < 300,
+ status,
+ statusText,
+ text: async () => JSON.stringify(body),
+ } as unknown as Response
+}
+
+let fetchMock: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+ fetchMock = vi.fn()
+ vi.stubGlobal('fetch', fetchMock)
+})
+
+afterEach(() => {
+ vi.unstubAllGlobals()
+ vi.restoreAllMocks()
+})
+
+describe('MCP identity compatibility', () => {
+ it('accepts a legacy create response without identity and rolls it back without a body', async () => {
+ fetchMock
+ .mockResolvedValueOnce(
+ jsonResponse({ name: 'legacy-object', namespace: 'mcp-server' }, 201, 'Created')
+ )
+ .mockResolvedValueOnce(jsonResponse({ name: 'legacy-object', namespace: 'mcp-server' }))
+
+ const created = await createMcpSecret('legacy-object', { fixture: 'fixture' })
+
+ expect(created).toEqual({ name: 'legacy-object', namespace: 'mcp-server' })
+
+ await deleteMcpSecret(created.name, undefined)
+
+ expect(fetchMock).toHaveBeenNthCalledWith(
+ 2,
+ '/control-api/api/v1/admin/mcp-secrets/legacy-object',
+ expect.objectContaining({
+ method: 'DELETE',
+ body: undefined,
+ })
+ )
+ })
+
+ it('preserves and sends a complete identity returned by a current API', async () => {
+ fetchMock
+ .mockResolvedValueOnce(
+ jsonResponse(
+ {
+ name: 'current-object',
+ namespace: 'mcp-server',
+ uid: 'uid-current-object',
+ resourceVersion: '9',
+ },
+ 201,
+ 'Created'
+ )
+ )
+ .mockResolvedValueOnce(jsonResponse({ name: 'current-object', namespace: 'mcp-server' }))
+
+ const created = await createMcpSecret('current-object', { fixture: 'fixture' })
+
+ expect(created).toEqual({
+ name: 'current-object',
+ namespace: 'mcp-server',
+ uid: 'uid-current-object',
+ resourceVersion: '9',
+ })
+
+ await deleteMcpSecret(created.name, {
+ uid: created.uid!,
+ resourceVersion: created.resourceVersion!,
+ })
+
+ const deleteRequest = fetchMock.mock.calls[1]?.[1] as RequestInit
+ expect(JSON.parse(String(deleteRequest.body))).toEqual({
+ uid: 'uid-current-object',
+ resourceVersion: '9',
+ })
+ })
+
+ it('fails closed when a create response returns only part of an identity', async () => {
+ fetchMock.mockResolvedValueOnce(
+ jsonResponse(
+ { name: 'partial-object', namespace: 'mcp-server', uid: 'uid-partial-object' },
+ 201,
+ 'Created'
+ )
+ )
+
+ await expect(createMcpSecret('partial-object', { fixture: 'fixture' })).rejects.toThrow(
+ /incomplete Secret identity/
+ )
+ })
+})
+
+describe('MCP delete API errors', () => {
+ it.each([
+ [
+ 'secret_identity_precondition_required',
+ 'A current Secret identity is required before it can be deleted.',
+ ],
+ ['secret_identity_unavailable', 'The server could not verify the current Secret identity.'],
+ ['secret_identity_changed', 'This Secret changed since it was loaded.'],
+ ['mcp_secret_in_use', 'This Secret is still in use by one or more connectors.'],
+ [
+ 'mcp_secret_reference_check_unavailable',
+ 'The server could not verify whether this Secret is in use.',
+ ],
+ ])('maps %s to an operator-safe remediation', (code, message) => {
+ const error = formatApiError(
+ { status: 409, statusText: 'Conflict' } as Response,
+ JSON.stringify({ error: code })
+ )
+
+ expect(error.message).toContain(message)
+ expect((error as Error & { code?: string }).code).toBe(code)
+ })
+})
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index 1634a25e4..34873174c 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -13,8 +13,11 @@ export type SecretIdentity = {
resourceVersion: string
}
-function requireSecretIdentity(raw: unknown, operation: string): SecretIdentity {
+function readSecretIdentity(raw: unknown, operation: string): SecretIdentity | undefined {
const value = (raw ?? {}) as { uid?: unknown; resourceVersion?: unknown }
+ const hasUid = value.uid !== undefined
+ const hasResourceVersion = value.resourceVersion !== undefined
+ if (!hasUid && !hasResourceVersion) return undefined
if (
typeof value.uid !== 'string' ||
!value.uid.trim() ||
@@ -26,6 +29,19 @@ function requireSecretIdentity(raw: unknown, operation: string): SecretIdentity
return { uid: value.uid, resourceVersion: value.resourceVersion }
}
+const SECRET_ERROR_MESSAGES: Record<string, string> = {
+ secret_identity_precondition_required:
+ 'A current Secret identity is required before it can be deleted. Refresh the page and review the latest state before taking further action.',
+ secret_identity_unavailable:
+ 'The server could not verify the current Secret identity. Refresh the page and review the Secret before taking further action.',
+ secret_identity_changed:
+ 'This Secret changed since it was loaded. Refresh the page and review the latest state before taking further action.',
+ mcp_secret_in_use:
+ 'This Secret is still in use by one or more connectors. Remove or update its references before deleting it.',
+ mcp_secret_reference_check_unavailable:
+ 'The server could not verify whether this Secret is in use. Refresh the page and review its references before taking further action.',
+}
+
// Global error handler for 401s - managed by AuthContext
let globalHandleAuthError: (() => void) | null = null
@@ -118,8 +134,10 @@ export function formatApiError(res: Response, text: string): Error {
} catch {
detail = text
}
+ const errorCode = typeof parsedBody?.error === 'string' ? parsedBody.error : undefined
const friendlyDetail =
- detail === 'duplicate_username'
+ (errorCode ? SECRET_ERROR_MESSAGES[errorCode] : undefined) ??
+ (detail === 'duplicate_username'
? 'That username is already taken.'
: detail === 'duplicate_email'
? 'That email is already registered.'
@@ -144,15 +162,14 @@ export function formatApiError(res: Response, text: string): Error {
? "Invitations are unavailable — the member-registration service isn't configured or can't be reached. Check the server logs for details."
: detail === 'member_registration_misconfigured'
? 'Invitations are unavailable — member registration is misconfigured. Check the server logs for details.'
- : detail
+ : detail)
const error = new Error(`${res.status} ${res.statusText} - ${friendlyDetail}`)
;(error as Error & { status?: number }).status = res.status
// Preserve the machine-readable error code and full JSON body so callers can
// render structured, actionable errors (e.g. unpriced_models, price_in_use_by_budget)
// instead of the generic message string.
if (parsedBody) {
- ;(error as Error & { code?: string }).code =
- typeof parsedBody.error === 'string' ? (parsedBody.error as string) : undefined
+ ;(error as Error & { code?: string }).code = errorCode
;(error as Error & { body?: Record<string, unknown> }).body = parsedBody
}
return error
@@ -1470,25 +1487,41 @@ export async function updateMcpServer(name: string, payload: { spec: Record<stri
) as Promise<McpServerResource>
}
-export async function createMcpSecret(name: string, data: Record<string, string>) {
- const response = await apiSend('POST', '/api/v1/admin/mcp-secrets', { name, data })
- const identity = requireSecretIdentity(response, 'createMcpSecret')
- return {
- ...(response as { name: string; namespace: string }),
- ...identity,
- } as {
+export type McpSecretCreateResult =
+ | ({
+ name: string
+ namespace: string
+ } & SecretIdentity)
+ | {
+ name: string
+ namespace: string
+ uid?: undefined
+ resourceVersion?: undefined
+ }
+
+export async function createMcpSecret(
+ name: string,
+ data: Record<string, string>
+): Promise<McpSecretCreateResult> {
+ const response = (await apiSend('POST', '/api/v1/admin/mcp-secrets', { name, data })) as {
name: string
namespace: string
- } & SecretIdentity
+ }
+ const identity = readSecretIdentity(response, 'createMcpSecret')
+ return identity ? { ...response, ...identity } : response
}
/**
* Deletes a Secret in the MCP-servers namespace (hardcoded server-side to
* `config.mcpServersNamespace`). Used by the Create MCP Server flow to roll
- * back a just-created Secret when the subsequent McpServer CRD creation fails,
- * so we never leave orphan Secrets behind.
+ * back a just-created Secret when the subsequent McpServer CRD creation fails.
+ *
+ * Current API versions require the server-issued identity. `undefined` is a
+ * narrow compatibility path for that rollback only: older create endpoints
+ * succeeded without returning identity and accepted the original bodyless
+ * DELETE. Primary delete flows must keep their identity precondition.
*/
-export async function deleteMcpSecret(name: string, identity: SecretIdentity) {
+export async function deleteMcpSecret(name: string, identity: SecretIdentity | undefined) {
return apiSend(
'DELETE',
`/api/v1/admin/mcp-secrets/${encodeURIComponent(name)}`,
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 9371562e4..c7cda9813 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.458",
+ "version": "0.1.459",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.458",
+ "version": "0.1.459",
"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 6feb28a82..29e399255 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.458",
+ "version": "0.1.459",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",