Skip to content

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

TypeScript

fix(control-api): enforce secret metadata policy

Alfredo Lopezae44cf544a07
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index d6782a6cb..7c22a97b4 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.488",
+ "version": "0.1.494",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.488",
+ "version": "0.1.494",
"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 895f64295..e1c0171a7 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.488",
+ "version": "0.1.494",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/k8s.ts b/control-api/src/k8s.ts
index 2c5f3ad25..80e19924c 100644
--- a/control-api/src/k8s.ts
+++ b/control-api/src/k8s.ts
@@ -7,6 +7,12 @@ import {
LlmAllowedModelsConfigMapWriter,
} from './services/llmAllowedModelsConfigMap.js'
import { ResourceService, mergeAnnotationsForReplace } from './services/resourceService.js'
+import type { SecretConstraintOptions } from './services/secretConstraints.js'
+import type {
+ SecretRepository,
+ SecretResource,
+ SecretSnapshot,
+} from './services/secretRepository.js'
import { SecretService } from './services/secretService.js'
import {
ClerumResourceType,
@@ -160,7 +166,7 @@ export function validateExecParams(namespace: string, pathOrDir: string): void {
export class K8sGateway {
private readonly namespace: string
private readonly resources: ResourceService
- private readonly secrets: SecretService
+ private readonly secrets: SecretRepository
private readonly hostOverviews: HostOverviewService
private readonly hostEnvSvc: HostEnvService
private readonly llmAllowedModelsCmWriter: LlmAllowedModelsConfigMapWriter
@@ -397,27 +403,38 @@ export class K8sGateway {
* client so callers can branch on statusCode. Used by admin POST handlers
* to validate envSecret references before creating broken CRDs.
*/
- async getSecret(name: string, namespace?: string): Promise<unknown> {
+ async getSecret(name: string, namespace?: string): Promise<SecretResource> {
return this.secrets.getSecret(name, namespace)
}
- async createSecret(req: SecretUpsertRequest): Promise<unknown> {
- return this.secrets.createSecret(req)
+ async createSecret(
+ req: SecretUpsertRequest,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ return this.secrets.createSecret(req, opts)
}
/** `precondition` makes the replace ownership-bound; see `SecretPreconditions`. */
async updateSecret(
req: SecretUpsertRequest,
- precondition?: SecretPreconditions
- ): Promise<unknown> {
- return this.secrets.updateSecret(req, precondition)
+ precondition?: SecretPreconditions,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ return this.secrets.updateSecret(req, precondition, opts)
}
- async mergeSecret(req: SecretUpsertRequest): Promise<unknown> {
- return this.secrets.mergeSecret(req)
+ async mergeSecret(
+ req: SecretUpsertRequest,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ return this.secrets.mergeSecret(req, opts)
}
- async removeSecretKey(req: { name: string; namespace?: string; key: string }): Promise<unknown> {
+ async removeSecretKey(req: {
+ name: string
+ namespace?: string
+ key: string
+ }): Promise<SecretSnapshot> {
return this.secrets.removeSecretKey(req)
}
@@ -684,6 +701,7 @@ export function extractHttpStatus(err: unknown): number | null {
const maybe = err as {
statusCode?: number
code?: number | string
+ status?: number
httpStatus?: number
response?: { statusCode?: number; status?: number }
}
@@ -697,6 +715,7 @@ export function extractHttpStatus(err: unknown): number | null {
if (maybe.response && typeof maybe.response.statusCode === 'number')
return maybe.response.statusCode
if (maybe.response && typeof maybe.response.status === 'number') return maybe.response.status
+ if (typeof maybe.status === 'number') return maybe.status
return null
}
diff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.ts
index a477fd59c..7c49a851f 100644
--- a/control-api/src/routes/admin/registry.ts
+++ b/control-api/src/routes/admin/registry.ts
@@ -10,6 +10,7 @@ import { validateMcpServerSpecPreflight } from '../../http/validateMcpServerSpec
import { K8sGateway } from '../../k8s.js'
import type { UiAuthedRequest } from '../../middleware/controlUIAuth.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
+import { rootLogger } from '../../observability/logger.js'
import { type AdminUserRecord, findAdminById } from '../../services/adminAuthService.js'
import {
addHookRefToHost,
@@ -46,11 +47,16 @@ import {
ensureRegistryPullSecrets,
platformWorkloadNamespaces,
} from '../../services/registryPullSecretService.js'
+import {
+ existingSecretAnnotationKeyReason,
+ invalidSecretTypeReason,
+} from '../../services/secretConstraints.js'
+import { SecretSnapshot, toSecretSnapshot } from '../../services/secretRepository.js'
import {
validateWorkflowRecipeEgressPreflight,
validateWorkflowRecipeLimits,
} from '../../services/workflowRecipeLimits.js'
-import { SecretUpsertRequest } from '../../types.js'
+import type { SecretPreconditions, SecretUpsertRequest } from '../../types.js'
import {
EVENFIRE_REGISTRY_PULL_SECRET_NAME,
shouldAttachEvenfirePullSecret,
@@ -355,14 +361,98 @@ function hookTargetKind(target: {
return 'unknown'
}
-type SecretSnapshot = {
+const REGISTRY_SECRET_WRITE_OPTIONS = { capability: 'registryCredential' } as const
+
+/**
+ * Registry upgrades must either restore a credentials Secret exactly or refuse
+ * before mutating anything. Silently stripping metadata during rollback can
+ * remove ownership/reconciliation state from a Secret managed by another
+ * controller.
+ */
+function nonRestorableSecretSnapshotReason(snapshot: SecretSnapshot): string | null {
+ if (invalidSecretTypeReason(snapshot.type ?? 'Opaque')) {
+ return 'existing credentials Secret type is not restorable under the registry write policy'
+ }
+ if (
+ Object.keys(snapshot.annotations ?? {}).some(
+ key => existingSecretAnnotationKeyReason(key, REGISTRY_SECRET_WRITE_OPTIONS) !== null
+ )
+ ) {
+ return 'existing credentials Secret contains unauthorized platform metadata'
+ }
+ if (
+ snapshot.labels?.['clerum.io/managed-by'] !== undefined &&
+ snapshot.labels['clerum.io/managed-by'] !== 'control-api'
+ ) {
+ return 'existing credentials Secret is owned by another controller'
+ }
+ if (
+ snapshot.labels?.['clerum.io/owner-recipe'] !== undefined ||
+ snapshot.labels?.['clerum.io/recipe-secret'] !== undefined ||
+ snapshot.labels?.['clerum.io/shared'] !== undefined
+ ) {
+ return 'existing credentials Secret is owned by a workflow recipe'
+ }
+ if (snapshot.ownerReferences?.length) {
+ return 'existing credentials Secret has ownerReferences that the registry upgrade cannot restore'
+ }
+ if (snapshot.finalizers?.length) {
+ return 'existing credentials Secret has finalizers that the registry upgrade cannot restore'
+ }
+ if (snapshot.immutable === true) {
+ return 'existing credentials Secret is immutable'
+ }
+ if (!snapshot.uid || !snapshot.resourceVersion) {
+ return 'existing credentials Secret has no complete Kubernetes identity for a safe rollback'
+ }
+ return null
+}
+
+function secretPreconditions(
+ snapshot: Pick<SecretSnapshot, 'uid' | 'resourceVersion'>
+): SecretPreconditions {
+ return { uid: snapshot.uid, resourceVersion: snapshot.resourceVersion }
+}
+
+type SafeRegistryErrorLogFields = {
name: string
- namespace: string
- type?: string
- labels?: Record<string, string>
- annotations?: Record<string, string>
- data?: Record<string, string>
- stringData?: Record<string, string>
+ status?: number
+ code?: string
+}
+
+/** Return only bounded error identity fields; never place upstream messages in logs. */
+export function registryErrorLogFields(err: unknown): SafeRegistryErrorLogFields {
+ const candidate =
+ err && typeof err === 'object'
+ ? (err as {
+ name?: unknown
+ status?: unknown
+ statusCode?: unknown
+ code?: unknown
+ })
+ : undefined
+ const rawName = err instanceof Error ? err.name : candidate?.name
+ const name =
+ typeof rawName === 'string' && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(rawName)
+ ? rawName
+ : 'UnknownError'
+ const rawStatus = candidate?.status ?? candidate?.statusCode
+ const status =
+ typeof rawStatus === 'number' &&
+ Number.isInteger(rawStatus) &&
+ rawStatus >= 100 &&
+ rawStatus <= 599
+ ? rawStatus
+ : undefined
+ const code =
+ typeof candidate?.code === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(candidate.code)
+ ? candidate.code
+ : undefined
+ return {
+ name,
+ ...(status === undefined ? {} : { status }),
+ ...(code === undefined ? {} : { code }),
+ }
}
type CredentialPayloadValidation =
@@ -808,7 +898,8 @@ async function updateResourceWithConflictRetry(
): Promise<unknown> {
let lastConflict: unknown
- for (let attempt = 1; attempt <= UPDATE_CONFLICT_RETRY_ATTEMPTS; attempt += 1) {
+ const maxAttempts = body.metadata?.resourceVersion ? 1 : UPDATE_CONFLICT_RETRY_ATTEMPTS
+ for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
try {
return await gateway.updateResource(plural, name, body, namespace)
} catch (err) {
@@ -828,41 +919,7 @@ function normalizeSecretSnapshot(
fallbackName: string,
fallbackNamespace: string
): SecretSnapshot {
- const obj = (raw ?? {}) as {
- metadata?: {
- name?: string
- namespace?: string
- labels?: Record<string, string>
- annotations?: Record<string, string>
- }
- type?: unknown
- data?: unknown
- stringData?: unknown
- }
-
- return {
- name:
- typeof obj.metadata?.name === 'string' && obj.metadata.name.trim()
- ? obj.metadata.name
- : fallbackName,
- namespace:
- typeof obj.metadata?.namespace === 'string' && obj.metadata.namespace.trim()
- ? obj.metadata.namespace
- : fallbackNamespace,
- ...(typeof obj.type === 'string' ? { type: obj.type } : {}),
- ...(obj.metadata?.labels && typeof obj.metadata.labels === 'object'
- ? { labels: obj.metadata.labels }
- : {}),
- ...(obj.metadata?.annotations && typeof obj.metadata.annotations === 'object'
- ? { annotations: obj.metadata.annotations }
- : {}),
- ...(obj.data && typeof obj.data === 'object'
- ? { data: obj.data as Record<string, string> }
- : {}),
- ...(obj.stringData && typeof obj.stringData === 'object'
- ? { stringData: obj.stringData as Record<string, string> }
- : {}),
- }
+ return toSecretSnapshot(raw, fallbackName, fallbackNamespace)
}
async function waitForDeletion(
@@ -970,6 +1027,8 @@ export async function getInstalledRegistryState(gateway?: K8sGateway): Promise<{
}
}
+const log = rootLogger.child({ module: 'admin-registry' })
+
export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
const router = Router()
@@ -1484,7 +1543,7 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
stringData: secretData,
}
try {
- await gateway.createSecret(secretReq)
+ await gateway.createSecret(secretReq, { capability: 'registryCredential' })
} catch (err) {
const k8sErr = extractK8sError(err)
if (k8sErr) {
@@ -2010,14 +2069,17 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
try {
- await gateway.createSecret({
- name: secretName,
- namespace: targetNs,
- type: 'Opaque',
- labels: registryLabels,
- annotations: registryAnnotations,
- stringData: credentials,
- })
+ await gateway.createSecret(
+ {
+ name: secretName,
+ namespace: targetNs,
+ type: 'Opaque',
+ labels: registryLabels,
+ annotations: registryAnnotations,
+ stringData: credentials,
+ },
+ REGISTRY_SECRET_WRITE_OPTIONS
+ )
} catch (err) {
const k8sErr = extractK8sError(err)
if (k8sErr) {
@@ -2229,12 +2291,20 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
const llmHooksNs = config.llmHooksNamespace
let current: {
spec?: Record<string, unknown>
- metadata?: { annotations?: Record<string, string>; labels?: Record<string, string> }
+ metadata?: {
+ annotations?: Record<string, string>
+ labels?: Record<string, string>
+ resourceVersion?: string
+ }
}
try {
current = (await gateway.getResource('llmhooks', body.hookName, llmHooksNs)) as {
spec?: Record<string, unknown>
- metadata?: { annotations?: Record<string, string>; labels?: Record<string, string> }
+ metadata?: {
+ annotations?: Record<string, string>
+ labels?: Record<string, string>
+ resourceVersion?: string
+ }
}
} catch (err) {
res.status(404).json({
@@ -2451,10 +2521,15 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
body.hookName,
{
metadata: {
+ ...(current.metadata?.labels ? { labels: current.metadata.labels } : {}),
annotations: {
+ ...(current.metadata?.annotations ?? {}),
...catalogAnnotations(body.registryEntryName, body.registryEntryVersion),
'clerum.io/trust-level': trustLevel,
},
+ ...(current.metadata?.resourceVersion
+ ? { resourceVersion: current.metadata.resourceVersion }
+ : {}),
},
spec: upgradedSpec,
},
@@ -2480,7 +2555,10 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
config.hostsNamespace
)
} catch (err) {
- console.error(`[Admin] upgrade-hook "${body.hookName}": Host ref sync failed:`, err)
+ log.error(
+ { hookName: body.hookName, error: registryErrorLogFields(err) },
+ 'Registry upgrade Host reference sync failed'
+ )
res.status(207).json({
hookName: body.hookName,
digest: newDigest,
@@ -2658,18 +2736,34 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
const namespace = config.mcpServersNamespace
// 1. Verify existing server exists
- let existingServer: Record<string, unknown>
+ let existingServer: {
+ metadata?: {
+ annotations?: Record<string, string>
+ labels?: Record<string, string>
+ resourceVersion?: string
+ }
+ spec?: Record<string, unknown>
+ }
try {
existingServer = (await gateway.getResource(
'mcpservers',
body.serverName,
namespace
- )) as Record<string, unknown>
+ )) as typeof existingServer
} catch {
res.status(404).json({ error: `McpServer "${body.serverName}" not found` })
return
}
+ const installedCatalogId = getCatalogId(existingServer.metadata)
+ if (installedCatalogId && installedCatalogId !== body.registryEntryName) {
+ res.status(409).json({
+ error: 'mcp_server_entry_identity_mismatch',
+ reason: `McpServer "${body.serverName}" was installed from "${installedCatalogId}", not "${body.registryEntryName}" — uninstall and install to change entry`,
+ })
+ return
+ }
+
// 2. Fetch new version metadata
const entry = await getEntryVersion(body.registryEntryName, body.registryEntryVersion)
const meta = entry.mcp_server_meta as Record<string, unknown> | null
@@ -2701,7 +2795,7 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
// 3. Build updated spec (preserve contextRef from existing)
- const existingSpec = (existingServer as { spec?: Record<string, unknown> }).spec ?? {}
+ const existingSpec = existingServer.spec ?? {}
const transport = (entry.transport ?? 'streamableHttp') as string
const port = (meta?.port as number) ?? 3000
let remoteBaseUrl: string | undefined
@@ -2805,24 +2899,15 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
return
}
- // Ensure the shared pull secret exists before the CRD update references it
- // (self-hosted self-provision; namespace-shared, idempotent, fail-loud). Runs
- // AFTER preflight — matching install — so a request that will 422 never mints a
- // rotate-on-call credential.
- if (attachEvenfirePullSecret) {
- try {
- await ensureRegistryPullSecret(gateway, namespace)
- } catch (err) {
- const mapped = pullSecretErrorResponse(err)
- res.status(mapped.status).json(mapped.body)
- return
- }
- }
-
- // 4. Update credentials if provided
+ // Read and validate the rollback target before any shared pull-secret
+ // provisioning or credentials write. A legacy Secret with blocked
+ // infrastructure metadata cannot be safely restored through the normal
+ // constrained writer, so fail closed before creating side effects.
let previousSecretSnapshot: SecretSnapshot | null = null
let secretCreatedDuringUpgrade = false
- if (Object.keys(credentialPayload.secretData).length > 0) {
+ let mutatedSecretPreconditions: SecretPreconditions | null = null
+ const hasCredentialUpdates = Object.keys(credentialPayload.secretData).length > 0
+ if (hasCredentialUpdates) {
try {
previousSecretSnapshot = normalizeSecretSnapshot(
await gateway.getSecret(secretName, namespace),
@@ -2839,19 +2924,57 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
}
}
+ if (previousSecretSnapshot) {
+ const reason = nonRestorableSecretSnapshotReason(previousSecretSnapshot)
+ if (reason) {
+ res.status(409).json({
+ error: 'credentials_secret_state_not_restorable',
+ reason,
+ })
+ return
+ }
+ }
+ }
+
+ // Ensure the shared pull secret exists before the CRD update references it
+ // (self-hosted self-provision; namespace-shared, idempotent, fail-loud). Runs
+ // AFTER preflight — matching install — so a request that will 422 never mints a
+ // rotate-on-call credential.
+ if (attachEvenfirePullSecret) {
+ try {
+ await ensureRegistryPullSecret(gateway, namespace)
+ } catch (err) {
+ const mapped = pullSecretErrorResponse(err)
+ res.status(mapped.status).json(mapped.body)
+ return
+ }
+ }
+
+ // 4. Update credentials if provided
+ if (hasCredentialUpdates) {
const secretRequest: SecretUpsertRequest = {
name: secretName,
namespace,
type: 'Opaque',
labels: {
+ ...(previousSecretSnapshot?.labels ?? {}),
'clerum.io/managed-by': 'control-api',
},
- annotations: catalogAnnotations(body.registryEntryName, body.registryEntryVersion),
+ annotations: {
+ ...(previousSecretSnapshot?.annotations ?? {}),
+ ...catalogAnnotations(body.registryEntryName, body.registryEntryVersion),
+ },
+ ...(previousSecretSnapshot?.data ? { data: previousSecretSnapshot.data } : {}),
stringData: credentialPayload.secretData,
}
if (previousSecretSnapshot) {
- await gateway.updateSecret(secretRequest)
+ const updatedSecret = await gateway.updateSecret(
+ secretRequest,
+ secretPreconditions(previousSecretSnapshot),
+ REGISTRY_SECRET_WRITE_OPTIONS
+ )
+ mutatedSecretPreconditions = secretPreconditions(updatedSecret)
auditLog('secret_updated', {
secretName,
namespace,
@@ -2859,8 +2982,9 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
version: body.registryEntryVersion,
})
} else {
- await gateway.createSecret(secretRequest)
+ const created = await gateway.createSecret(secretRequest, REGISTRY_SECRET_WRITE_OPTIONS)
secretCreatedDuringUpgrade = true
+ mutatedSecretPreconditions = secretPreconditions(created)
auditLog('secret_created', {
secretName,
namespace,
@@ -2874,13 +2998,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// round-trip key (resourceService.updateResource merges body.metadata
// .annotations over current). managed-by / server-mode stay labels.
const upgradeLabels: Record<string, string> = {
+ ...(existingServer.metadata?.labels ?? {}),
'clerum.io/managed-by': 'control-api',
'clerum.io/server-mode': isLocal ? 'local' : 'remote',
}
- const upgradeAnnotations: Record<string, string> = catalogAnnotations(
- body.registryEntryName,
- body.registryEntryVersion
- )
+ const upgradeAnnotations: Record<string, string> = {
+ ...(existingServer.metadata?.annotations ?? {}),
+ ...catalogAnnotations(body.registryEntryName, body.registryEntryVersion),
+ }
try {
await updateResourceWithConflictRetry(
@@ -2888,41 +3013,103 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
'mcpservers',
body.serverName,
{
- metadata: { labels: upgradeLabels, annotations: upgradeAnnotations },
+ metadata: {
+ labels: upgradeLabels,
+ annotations: upgradeAnnotations,
+ ...(existingServer.metadata?.resourceVersion
+ ? { resourceVersion: existingServer.metadata.resourceVersion }
+ : {}),
+ },
spec: updatedSpec,
},
namespace
)
} catch (err) {
- if (body.credentials && Object.keys(body.credentials).length > 0) {
+ const k8sErr = extractK8sError(err)
+ let upgradeCommittedByRead = false
+ const outcomeIsAmbiguous = !k8sErr || k8sErr.status >= 500
+
+ // A transport/5xx error does not prove that the apiserver rejected the
+ // replace. Read the object before compensating: blind rollback after a
+ // committed write would undo a successful upgrade and create a second
+ // lost-update race.
+ if (outcomeIsAmbiguous) {
try {
+ const current = (await gateway.getResource(
+ 'mcpservers',
+ body.serverName,
+ namespace
+ )) as {
+ metadata?: { annotations?: Record<string, string>; labels?: Record<string, string> }
+ }
+ upgradeCommittedByRead =
+ getCatalogId(current.metadata) === body.registryEntryName &&
+ getCatalogVersion(current.metadata) === body.registryEntryVersion
+ } catch (readErr) {
+ log.error(
+ {
+ serverName: body.serverName,
+ namespace,
+ error: registryErrorLogFields(readErr),
+ },
+ 'Registry upgrade outcome is ambiguous and could not be classified'
+ )
+ res.status(503).json({ error: 'registry_upgrade_outcome_ambiguous' })
+ return
+ }
+ }
+
+ if (!upgradeCommittedByRead && hasCredentialUpdates) {
+ try {
+ if (!mutatedSecretPreconditions) {
+ throw Object.assign(new Error('mutated Secret identity unavailable'), {
+ code: 'secret_identity_unavailable',
+ })
+ }
if (secretCreatedDuringUpgrade) {
- await gateway.deleteSecret(secretName, namespace)
+ await gateway.deleteSecret(secretName, namespace, mutatedSecretPreconditions)
await waitForDeletion(
() => gateway.getSecret(secretName, namespace),
`Secret/${secretName}`
)
} else if (previousSecretSnapshot) {
- await gateway.updateSecret({
- name: previousSecretSnapshot.name,
- namespace: previousSecretSnapshot.namespace,
- type: previousSecretSnapshot.type || 'Opaque',
- labels: previousSecretSnapshot.labels,
- annotations: previousSecretSnapshot.annotations,
- data: previousSecretSnapshot.data,
- stringData: previousSecretSnapshot.stringData,
- })
+ await gateway.updateSecret(
+ {
+ name: previousSecretSnapshot.name,
+ namespace: previousSecretSnapshot.namespace,
+ type: previousSecretSnapshot.type ?? 'Opaque',
+ labels: previousSecretSnapshot.labels ?? {},
+ annotations: previousSecretSnapshot.annotations ?? {},
+ data: previousSecretSnapshot.data,
+ stringData: previousSecretSnapshot.stringData,
+ },
+ mutatedSecretPreconditions,
+ REGISTRY_SECRET_WRITE_OPTIONS
+ )
}
- } catch {
- // Best-effort rollback; preserve the original upgrade error.
+ } catch (rollbackErr) {
+ log.error(
+ {
+ serverName: body.serverName,
+ namespace,
+ secretName,
+ rollback: secretCreatedDuringUpgrade ? 'delete-created-secret' : 'restore-secret',
+ error: registryErrorLogFields(rollbackErr),
+ },
+ 'Registry upgrade rollback failed'
+ )
}
}
- const k8sErr = extractK8sError(err)
- if (k8sErr) {
+
+ if (upgradeCommittedByRead) {
+ // The write was accepted despite the transport error. Continue with
+ // the normal success response; the read is the authoritative proof.
+ } else if (k8sErr) {
res.status(k8sErr.status).json({ error: k8sErr.message })
return
+ } else {
+ throw err
}
- throw err
}
auditLog('upgrade', {
serverName: body.serverName,
@@ -2983,21 +3170,50 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// recreating it in sandbox-recipes, not by preserving the ambiguity.
const recipeNamespaces = [config.sandboxNamespace] as const
let namespace: string | null = null
+ let existingRecipe:
+ | {
+ metadata?: {
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ resourceVersion?: string
+ }
+ spec?: Record<string, unknown>
+ }
+ | undefined
for (const candidate of recipeNamespaces) {
try {
- await gateway.getResource('workflowrecipes', body.recipeName, candidate)
+ existingRecipe = (await gateway.getResource(
+ 'workflowrecipes',
+ body.recipeName,
+ candidate
+ )) as {
+ metadata?: {
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ resourceVersion?: string
+ }
+ spec?: Record<string, unknown>
+ }
namespace = candidate
break
} catch {
// try next namespace
}
}
- if (!namespace) {
+ if (!namespace || !existingRecipe) {
res.status(404).json({
error: `WorkflowRecipe "${body.recipeName}" not found in any known recipe namespace (${recipeNamespaces.join(', ')})`,
})
return
}
+ const installedCatalogId = getCatalogId(existingRecipe.metadata)
+ if (installedCatalogId && installedCatalogId !== body.registryEntryName) {
+ res.status(409).json({
+ error: 'recipe_entry_identity_mismatch',
+ reason: `WorkflowRecipe "${body.recipeName}" was installed from "${installedCatalogId}", not "${body.registryEntryName}" — uninstall and install to change entry`,
+ })
+ return
+ }
// 2. Fetch new version from registry
const entry = await getEntryVersion(body.registryEntryName, body.registryEntryVersion)
@@ -3101,12 +3317,13 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
// stays a label. Pass metadata so a version bump refreshes the
// round-trip annotation (resourceService merges body.metadata).
const upgradeLabels: Record<string, string> = {
+ ...(existingRecipe.metadata?.labels ?? {}),
'clerum.io/managed-by': 'control-api',
}
- const upgradeAnnotations: Record<string, string> = catalogAnnotations(
- body.registryEntryName,
- body.registryEntryVersion
- )
+ const upgradeAnnotations: Record<string, string> = {
+ ...(existingRecipe.metadata?.annotations ?? {}),
+ ...catalogAnnotations(body.registryEntryName, body.registryEntryVersion),
+ }
// Ensure the platform pull credential before the CRD that will reference it.
// Keyed on the INCOMING spec: an upgrade is exactly how a recipe moves from a
@@ -3127,7 +3344,13 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
'workflowrecipes',
body.recipeName,
{
- metadata: { labels: upgradeLabels, annotations: upgradeAnnotations },
+ metadata: {
+ labels: upgradeLabels,
+ annotations: upgradeAnnotations,
+ ...(existingRecipe.metadata?.resourceVersion
+ ? { resourceVersion: existingRecipe.metadata.resourceVersion }
+ : {}),
+ },
spec: recipeSpec,
},
namespace
@@ -3176,7 +3399,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
let authActive: boolean
try {
authActive = await isRegistryAuthActive()
- } catch {
+ } catch (err) {
+ log.error(
+ {
+ event: 'isRegistryAuthActive_failed',
+ err: registryErrorLogFields(err),
+ },
+ 'registry auth check failed'
+ )
res.status(502).json({ error: 'registry_integration_error' })
return null
}
@@ -3198,7 +3428,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
try {
orgName = (await resolvePublishScope()).orgName
if (!orgName) orgName = (await resolvePublishScope({ force: true })).orgName
- } catch {
+ } catch (err) {
+ log.error(
+ {
+ event: 'resolvePublishScope_failed',
+ err: registryErrorLogFields(err),
+ },
+ 'publish scope resolution failed'
+ )
res.status(502).json({ error: 'registry_integration_error' })
return null
}
@@ -3298,7 +3535,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
let authActive: boolean
try {
authActive = await isRegistryAuthActive()
- } catch {
+ } catch (err) {
+ log.error(
+ {
+ event: 'isRegistryAuthActive_failed',
+ err: registryErrorLogFields(err),
+ },
+ 'registry auth check failed'
+ )
res.status(502).json({ error: 'registry_integration_error' })
return null
}
@@ -3324,7 +3568,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {
if (!scope.curator && !scope.orgName) {
scope = await resolvePublishScope({ force: true })
}
- } catch {
+ } catch (err) {
+ log.error(
+ {
+ event: 'resolvePublishScope_failed',
+ err: registryErrorLogFields(err),
+ },
+ 'publish scope resolution failed'
+ )
res.status(502).json({ error: 'registry_integration_error' })
return null
}
diff --git a/control-api/src/routes/admin/secrets.ts b/control-api/src/routes/admin/secrets.ts
index 0ec553766..05d0b55a7 100644
--- a/control-api/src/routes/admin/secrets.ts
+++ b/control-api/src/routes/admin/secrets.ts
@@ -6,12 +6,14 @@ import { asyncHandler } from '../../http/asyncHandler.js'
import { enforceNamespace } from '../../http/namespaceAudit.js'
import { isValidDNSSubdomain } from '../../http/rfc1123.js'
import { K8sGateway, extractHttpStatus } from '../../k8s.js'
+import { rootLogger } from '../../observability/logger.js'
import {
OWNER_RECIPE_LABEL_KEY,
SHARED_LABEL_KEY,
type SecretOwnership,
parseSecretOwnership,
} from '../../secretOwnership.js'
+import { REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS } from '../../services/secretConstraints.js'
import { invalidSecretDataKeyReason } from '../../services/secretKeys.js'
import { SecretUpsertRequest } from '../../types.js'
import { listHostSecrets } from './hostSecrets.js'
@@ -49,6 +51,17 @@ const PLATFORM_MANAGED_SECRET_ERROR =
`Secret "${EVENFIRE_REGISTRY_PULL_SECRET_NAME}" is platform-managed (the evenfire ` +
'registry image-pull credential) and cannot be created, modified, or deleted here'
+const logger = rootLogger.child({ module: 'admin-secrets' })
+
+function isRegistryManagedCredentialSecret(
+ annotations: Record<string, string> | undefined
+): boolean {
+ return REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS.every(key => {
+ const value = annotations?.[key]
+ return typeof value === 'string' && value.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> {
@@ -453,7 +466,7 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
// job. Read it first so a missing Secret is a 404 instead of a silent
// upsert, and so the ownership guard below sees the stored labels.
let existing: {
- metadata?: { labels?: Record<string, string> }
+ metadata?: { labels?: Record<string, string>; annotations?: Record<string, string> }
data?: Record<string, string>
}
try {
@@ -480,7 +493,15 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
return
}
- await gateway.mergeSecret({ name, namespace: targetNs, stringData: data })
+ const preserveRegistryAnnotations = isRegistryManagedCredentialSecret(
+ existing.metadata?.annotations
+ )
+ ? { allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS }
+ : undefined
+ await gateway.mergeSecret(
+ { name, namespace: targetNs, stringData: data },
+ preserveRegistryAnnotations
+ )
const keys = [...new Set([...Object.keys(existing.data || {}), ...Object.keys(data)])].sort(
(a, b) => a.localeCompare(b)
@@ -490,13 +511,13 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
// before anything that could throw — a rotation that actually happened
// must never go unlogged just because a later, secondary step failed.
// Key NAMES are safe to log; values never are.
- console.log(
- JSON.stringify({
- event: 'mcp-secret-rotated',
+ logger.info(
+ {
name,
namespace: targetNs,
rotatedKeys: Object.keys(data).sort((a, b) => a.localeCompare(b)),
- })
+ },
+ 'mcp-secret-rotated'
)
// affectedConnectors is a best-effort convenience for the UI ("who
@@ -654,18 +675,11 @@ export function createAdminSecretsRouter(gateway: K8sGateway): Router {
}
async function recipeExists(recipeName: string): Promise<boolean> {
- try {
- const items = (await gateway.listResource(
- 'workflowrecipes',
- config.sandboxNamespace
- )) as Array<{ metadata?: { name?: string } }>
- return items.some(r => r.metadata?.name === recipeName)
- } catch {
- // List failure: don't block Secret creation on a transient apiserver
- // hiccup — the WRC reconciler is the second line of defense (it rejects
- // owner-recipe Secrets that don't match the requesting recipe).
- return true
- }
+ const items = (await gateway.listResource(
+ 'workflowrecipes',
+ config.sandboxNamespace
+ )) as Array<{ metadata?: { name?: string } }>
+ return items.some(r => r.metadata?.name === recipeName)
}
async function isRecipeSecret(
diff --git a/control-api/src/services/registryClient.ts b/control-api/src/services/registryClient.ts
index a1b93e5d2..17c1c798a 100644
--- a/control-api/src/services/registryClient.ts
+++ b/control-api/src/services/registryClient.ts
@@ -162,16 +162,15 @@ async function mintTokenForGeneration(
signal: AbortSignal.timeout(READ_TIMEOUT_MS),
})
if (!res.ok) {
- const body = await res.text()
// Distinguish a rejected credential (rotate the secret) from an origin /
// tunnel outage (page on-call about reachability, do NOT rotate). A 5xx at
// the token endpoint is the registry origin or its tunnel being down, not a
// bad client secret — the previous identical label sent on-call to rotate
// secrets during an outage.
if (res.status >= 500) {
- throw new Error(`registry token endpoint unavailable (origin/tunnel): ${res.status} ${body}`)
+ throw new Error(`registry token endpoint unavailable (origin/tunnel): ${res.status}`)
}
- throw new Error(`registry credential rejected: ${res.status} ${body}`)
+ throw new Error(`registry credential rejected: ${res.status}`)
}
const json = (await res.json()) as { access_token: string; expires_in: number }
const next = {
@@ -236,6 +235,15 @@ interface PaginatedResponse<T> {
/** Retriable upstream statuses for an idempotent GET (gateway/tunnel hiccups). */
const RETRIABLE_GET_STATUSES = new Set([502, 503, 504])
+async function discardResponseBody(res: Response): Promise<void> {
+ try {
+ await res.body?.cancel()
+ } catch {
+ // Releasing a failed upstream response is best-effort; preserve the original
+ // auth/status error when an undici stream is already closed.
+ }
+}
+
function jitterSleep(baseMs: number): Promise<void> {
// ~baseMs ± up to baseMs jitter so concurrent callers don't retry in lockstep.
const ms = baseMs + Math.floor(Math.random() * baseMs)
@@ -285,10 +293,12 @@ async function authedFetch(
// Existing behavior: a 401 means the cached token is stale (e.g. registry
// key rotation) — evict and retry once with a fresh mint. Orthogonal to
// the transient-status retry below.
+ await discardResponseBody(res)
cached = null
res = await send()
}
if (isGet && allowTransientRetry && RETRIABLE_GET_STATUSES.has(res.status)) {
+ await discardResponseBody(res)
await jitterSleep(250)
return attempt(false)
}
@@ -315,7 +325,7 @@ async function registryFetch<T>(path: string, init?: RequestInit): Promise<T> {
throw err
}
if (!res.ok) {
- const body = await res.text()
+ await discardResponseBody(res)
// A persistent 401 (authedFetch already evict-retried once) is a registry
// machine-token / integration fault — NOT the admin's control-ui session.
// Remap to 502 (so control-ui's global 401 handler never force-logs-out the
@@ -336,7 +346,7 @@ async function registryFetch<T>(path: string, init?: RequestInit): Promise<T> {
// Attach the upstream status so the global error handler (app.ts) forwards
// 4xx verbatim to the API client (a registry 404 stays a 404 — the
// e2e-registry-publish-update-remove failure class).
- throw Object.assign(new Error(`Registry ${res.status}: ${body}`), {
+ throw Object.assign(new Error(`Registry ${res.status}`), {
status: res.status,
})
}
@@ -525,8 +535,7 @@ export async function downloadBundle(name: string, version: string): Promise<Buf
{ timeoutMs: BUNDLE_TIMEOUT_MS }
)
if (!res.ok) {
- const body = await res.text()
- throw new Error(`Registry ${res.status}: ${body}`)
+ throw new Error(`Registry ${res.status}`)
}
const arrayBuffer = await res.arrayBuffer()
return Buffer.from(arrayBuffer)
diff --git a/control-api/src/services/registryPullSecretService.ts b/control-api/src/services/registryPullSecretService.ts
index aaa827e6e..b15f7a586 100644
--- a/control-api/src/services/registryPullSecretService.ts
+++ b/control-api/src/services/registryPullSecretService.ts
@@ -109,6 +109,17 @@ const DOCKERCONFIG_KEY = '.dockerconfigjson'
const DOCKERCONFIG_TYPE = 'kubernetes.io/dockerconfigjson'
const FINGERPRINT_ANNOTATION = 'clerum.io/pull-key-fingerprint'
+/**
+ * This service is a PLATFORM writer, not a user-facing route: it stamps
+ * `clerum.io/`-prefixed metadata (the ownership label and the key fingerprint) that
+ * `secretConstraints` deliberately blocks by default, so a caller cannot forge platform
+ * ownership through `/admin/secrets` or the recipe-secret routes. Every write here declares
+ * the exact pull-secret capability — dropping it makes the real writer reject the fingerprint,
+ * and `MockGateway` (which bypasses `SecretService`) will NOT catch it; see
+ * test/services.pullSecretConstraints.test.ts.
+ */
+const PLATFORM_WRITE = { capability: 'registryPullSecret' } as const
+
export type EnsurePullSecretResult =
| 'created'
| 'repaired'
@@ -1049,12 +1060,12 @@ async function writeCredential(
// Wrong-typed Secrets were deleted before the mint (see ensureInner), so they are now
// absent and must be created, not updated.
if (alreadyDeleted) {
- await gateway.createSecret(buildSecretReq(ns, cred))
+ await gateway.createSecret(buildSecretReq(ns, cred), PLATFORM_WRITE)
return 'repaired'
}
if (state.kind === 'absent') {
try {
- await gateway.createSecret(buildSecretReq(ns, cred))
+ await gateway.createSecret(buildSecretReq(ns, cred), PLATFORM_WRITE)
return 'created'
} catch (err) {
if (k8sStatus(err) !== 409) throw err
@@ -1069,7 +1080,7 @@ async function writeCredential(
if (!winner) {
// Created and deleted again before this read. The Secret is absent, and an update
// against an absent Secret 404s — so create, do not fall through.
- await gateway.createSecret(buildSecretReq(ns, cred))
+ await gateway.createSecret(buildSecretReq(ns, cred), PLATFORM_WRITE)
return 'created'
}
if (winner.labels[MANAGED_BY_LABEL] !== MANAGED_BY_VALUE) {
@@ -1095,7 +1106,7 @@ async function writeCredential(
// create race is precisely when a third writer is known to be active on this name, so
// this is the LAST place to assume the gap is safe.
const adopted = await mutateOwned(gateway, ns, winner, precondition =>
- gateway.updateSecret(buildSecretReq(ns, cred), precondition)
+ gateway.updateSecret(buildSecretReq(ns, cred), precondition, PLATFORM_WRITE)
)
if (adopted.verdict === 'taken') {
recordTakeover(ctx.pass, ns, adopted.why)
@@ -1104,7 +1115,7 @@ async function writeCredential(
if (adopted.verdict === 'gone') {
// Deleted again in the gap. Nobody holds the name and the namespace still needs a
// credential, so create rather than leaving it empty.
- await gateway.createSecret(buildSecretReq(ns, cred))
+ await gateway.createSecret(buildSecretReq(ns, cred), PLATFORM_WRITE)
}
return 'created'
}
@@ -1120,7 +1131,7 @@ async function writeCredential(
// current, never that it is still ours. `mutateOwned` binds the replace to the identity we
// classified instead, so the apiserver refuses it if the object moved.
const outcome = await mutateOwned(gateway, ns, state.observed, precondition =>
- gateway.updateSecret(buildSecretReq(ns, cred), precondition)
+ gateway.updateSecret(buildSecretReq(ns, cred), precondition, PLATFORM_WRITE)
)
if (outcome.verdict === 'taken') {
recordTakeover(ctx.pass, ns, outcome.why)
@@ -1131,7 +1142,7 @@ async function writeCredential(
// already revoked whatever key that copy carried, so leaving the namespace empty is the
// one outcome guaranteed to ImagePullBackOff. Create, because an update against an
// absent Secret 404s.
- await gateway.createSecret(buildSecretReq(ns, cred))
+ await gateway.createSecret(buildSecretReq(ns, cred), PLATFORM_WRITE)
return 'created'
}
return state.kind === 'valid' ? 'exists-ours' : 'repaired'
diff --git a/control-api/src/services/secretConstraints.ts b/control-api/src/services/secretConstraints.ts
new file mode 100644
index 000000000..f0a584b7a
--- /dev/null
+++ b/control-api/src/services/secretConstraints.ts
@@ -0,0 +1,189 @@
+import { SecretUpsertRequest } from '../types.js'
+
+export const ALLOWED_SECRET_TYPES: readonly string[] = [
+ 'Opaque',
+ 'kubernetes.io/tls',
+ 'kubernetes.io/dockerconfigjson',
+]
+
+const INFRA_ANNOTATION_PREFIXES: readonly string[] = [
+ 'kubectl.kubernetes.io/',
+ 'kubernetes.io/',
+ 'meta.helm.sh/',
+]
+
+const PLATFORM_ANNOTATION_PREFIXES: readonly string[] = ['clerum.io/']
+
+export function isInfrastructureAnnotationKey(key: string): boolean {
+ return INFRA_ANNOTATION_PREFIXES.some(prefix => key.startsWith(prefix))
+}
+
+/** Platform metadata that a public rotation route may preserve, but never set. */
+export const REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS = [
+ 'clerum.io/catalog-id',
+ 'clerum.io/catalog-version',
+] as const
+
+/** Additional metadata owned by the internal Registry credential writer. */
+const REGISTRY_CREDENTIAL_WRITABLE_ANNOTATION_KEYS = [
+ ...REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS,
+ 'clerum.io/trust-level',
+] as const
+
+export type SecretWriteCapability = 'registryCredential' | 'registryPullSecret'
+
+const CAPABILITY_ANNOTATION_KEYS: Record<SecretWriteCapability, readonly string[]> = {
+ registryCredential: REGISTRY_CREDENTIAL_WRITABLE_ANNOTATION_KEYS,
+ registryPullSecret: ['clerum.io/pull-key-fingerprint'],
+}
+
+/**
+ * Options for Secret write-path constraint validation.
+ *
+ * Platform-internal writers must declare the narrow capability that owns the
+ * exact platform annotation keys they need. User-facing endpoints MUST leave
+ * this unset to prevent callers from claiming platform ownership.
+ */
+export interface SecretConstraintOptions {
+ capability?: SecretWriteCapability
+ /** Exact platform keys allowed only when validating already-persisted metadata. */
+ allowExistingPlatformAnnotationKeys?: readonly string[]
+}
+
+function allowedPlatformAnnotationKeys(opts?: SecretConstraintOptions): ReadonlySet<string> {
+ return new Set(opts?.capability ? CAPABILITY_ANNOTATION_KEYS[opts.capability] : [])
+}
+
+function isBlockedAnnotationKey(key: string, opts?: SecretConstraintOptions): boolean {
+ if (INFRA_ANNOTATION_PREFIXES.some(prefix => key.startsWith(prefix))) return true
+ return (
+ PLATFORM_ANNOTATION_PREFIXES.some(prefix => key.startsWith(prefix)) &&
+ !allowedPlatformAnnotationKeys(opts).has(key)
+ )
+}
+
+function reservedPrefixes(): readonly string[] {
+ return [...INFRA_ANNOTATION_PREFIXES, ...PLATFORM_ANNOTATION_PREFIXES]
+}
+
+function secretTypeErrorMessage(type: string): string {
+ return `Secret type "${type}" is not allowed; must be one of: ${ALLOWED_SECRET_TYPES.join(', ')}`
+}
+
+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`
+}
+
+export class InvalidSecretTypeError extends Error {
+ readonly status = 400
+ readonly type: string
+ constructor(type: string) {
+ super(secretTypeErrorMessage(type))
+ this.name = 'InvalidSecretTypeError'
+ this.type = type
+ }
+}
+
+export class DangerousAnnotationError extends Error {
+ readonly status = 400
+ readonly annotationKey: string
+ constructor(key: string, prefixes: readonly string[]) {
+ super(annotationKeyErrorMessage(key, prefixes))
+ this.name = 'DangerousAnnotationError'
+ this.annotationKey = key
+ }
+}
+
+export function invalidSecretTypeReason(type: string): string | null {
+ if (!ALLOWED_SECRET_TYPES.includes(type)) {
+ return secretTypeErrorMessage(type)
+ }
+ return null
+}
+
+export function dangerousAnnotationKeyReason(
+ key: string,
+ opts?: SecretConstraintOptions
+): string | null {
+ return isBlockedAnnotationKey(key, opts)
+ ? annotationKeyErrorMessage(key, reservedPrefixes())
+ : 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 assertValidSecretAnnotations(
+ annotations: Record<string, string> | undefined,
+ opts?: SecretConstraintOptions,
+ existingAnnotations?: Record<string, string>
+): void {
+ if (!annotations) return
+ for (const key of Object.keys(annotations)) {
+ const isUnchangedInfrastructureMetadata =
+ isInfrastructureAnnotationKey(key) && existingAnnotations?.[key] === annotations[key]
+ if (!isUnchangedInfrastructureMetadata && isBlockedAnnotationKey(key, opts)) {
+ throw new DangerousAnnotationError(key, reservedPrefixes())
+ }
+ }
+}
+
+/**
+ * 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 {
+ if (!annotations) return
+ for (const key of Object.keys(annotations)) {
+ if (existingSecretAnnotationKeyReason(key, opts) !== null) {
+ throw new DangerousAnnotationError(key, reservedPrefixes())
+ }
+ }
+}
+
+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.
+ 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)
+}
diff --git a/control-api/src/services/secretRepository.ts b/control-api/src/services/secretRepository.ts
new file mode 100644
index 000000000..86276c2a1
--- /dev/null
+++ b/control-api/src/services/secretRepository.ts
@@ -0,0 +1,89 @@
+import type { SecretPreconditions, SecretUpsertRequest } from '../types.js'
+import type { SecretConstraintOptions } from './secretConstraints.js'
+
+/** The subset of a Kubernetes Secret that callers are allowed to observe. */
+export interface SecretResource {
+ metadata?: {
+ name?: string
+ namespace?: string
+ uid?: string
+ resourceVersion?: string
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ ownerReferences?: Array<unknown>
+ finalizers?: string[]
+ }
+ type?: string
+ immutable?: boolean
+ data?: Record<string, string>
+ stringData?: Record<string, string>
+}
+
+/** A server-confirmed Secret identity and its restorable state. */
+export interface SecretSnapshot {
+ name: string
+ namespace: string
+ uid: string
+ resourceVersion: string
+ type?: string
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ ownerReferences?: Array<unknown>
+ finalizers?: string[]
+ immutable?: boolean
+ data?: Record<string, string>
+ 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): Promise<SecretSnapshot>
+ removeSecretKey(req: { name: string; namespace?: string; key: string }): 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,
+ fallbackName: string,
+ fallbackNamespace: string
+): SecretSnapshot {
+ const source = (raw ?? {}) as SecretResource
+ const metadata = source.metadata
+ if (typeof metadata?.uid !== 'string' || typeof metadata.resourceVersion !== 'string') {
+ throw Object.assign(
+ new Error(`Secret/${fallbackName} did not return a complete Kubernetes identity`),
+ { status: 503, code: 'secret_identity_unavailable' }
+ )
+ }
+
+ return {
+ name: typeof metadata.name === 'string' && metadata.name.trim() ? metadata.name : fallbackName,
+ namespace:
+ typeof metadata.namespace === 'string' && metadata.namespace.trim()
+ ? metadata.namespace
+ : fallbackNamespace,
+ uid: metadata.uid,
+ resourceVersion: metadata.resourceVersion,
+ ...(typeof source.type === 'string' ? { type: source.type } : {}),
+ ...(metadata.labels ? { labels: metadata.labels } : {}),
+ ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
+ ...(metadata.ownerReferences ? { ownerReferences: metadata.ownerReferences } : {}),
+ ...(metadata.finalizers ? { finalizers: metadata.finalizers } : {}),
+ ...(typeof source.immutable === 'boolean' ? { immutable: source.immutable } : {}),
+ ...(source.data ? { data: source.data } : {}),
+ ...(source.stringData ? { stringData: source.stringData } : {}),
+ }
+}
diff --git a/control-api/src/services/secretService.ts b/control-api/src/services/secretService.ts
index 6ff92ef00..1d242d6ea 100644
--- a/control-api/src/services/secretService.ts
+++ b/control-api/src/services/secretService.ts
@@ -1,8 +1,21 @@
import * as k8s from '@kubernetes/client-node'
import { SecretPreconditions, SecretUpsertRequest } from '../types.js'
+import {
+ type SecretConstraintOptions,
+ assertValidEffectiveSecretConstraints,
+ assertValidSecretConstraints,
+ assertValidSecretType,
+ isInfrastructureAnnotationKey,
+} from './secretConstraints.js'
import { assertValidSecretDataKey, assertValidSecretWriteKeys } from './secretKeys.js'
+import {
+ SecretRepository,
+ SecretResource,
+ SecretSnapshot,
+ toSecretSnapshot,
+} from './secretRepository.js'
-export class SecretService {
+export class SecretService implements SecretRepository {
constructor(
private readonly coreApi: k8s.CoreV1Api,
private readonly defaultNamespace: string
@@ -26,11 +39,15 @@ export class SecretService {
* Read a single Secret by name. Throws the underlying K8s client error
* (including 404) so callers can branch on statusCode.
*/
- async getSecret(name: string, namespace = this.defaultNamespace): Promise<unknown> {
+ async getSecret(name: string, namespace = this.defaultNamespace): Promise<SecretResource> {
return this.coreApi.readNamespacedSecret({ namespace, name })
}
- async createSecret(req: SecretUpsertRequest): Promise<unknown> {
+ async createSecret(
+ req: SecretUpsertRequest,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ assertValidSecretConstraints(req, opts)
assertValidSecretWriteKeys(req)
const body: k8s.V1Secret = {
apiVersion: 'v1',
@@ -46,10 +63,11 @@ export class SecretService {
stringData: req.stringData,
}
- return this.coreApi.createNamespacedSecret({
+ const created = await this.coreApi.createNamespacedSecret({
namespace: req.namespace || this.defaultNamespace,
body,
})
+ return toSecretSnapshot(created, req.name, req.namespace || this.defaultNamespace)
}
/**
@@ -65,24 +83,45 @@ export class SecretService {
*
* Pass `precondition` to make the replace ownership-bound rather than
* last-writer-wins (see `SecretPreconditions`). When it carries a
- * `resourceVersion` the pre-read is SKIPPED and that version is sent as-is,
- * so the API server rejects the write with 409 if anything touched the
- * object since the caller read it. Re-reading here would defeat the entire
- * point, by refreshing away the staleness we are trying to detect.
+ * `resourceVersion` the pre-read is skipped unless the request carries
+ * infrastructure metadata that must be proven unchanged; the precondition
+ * is still sent as-is, so the API server rejects the write with 409 if
+ * anything touched the object since the caller read it.
*
- * Because that read is skipped, a precondition caller must supply everything
- * it wants persisted: the `labels`/`annotations`/`type` fallbacks to the
- * existing object are not available on this path.
+ * On the no-read path, a precondition caller must supply everything it wants
+ * persisted: the `labels`/`annotations`/`type` fallbacks to the existing
+ * object are not available there. Internal capability writers that submit a
+ * full snapshot with infrastructure metadata are read-checked for exact
+ * preservation before the same precondition-bound replace.
*/
async updateSecret(
req: SecretUpsertRequest,
- precondition?: SecretPreconditions
- ): Promise<unknown> {
+ precondition?: SecretPreconditions,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ const hasInfrastructureAnnotations = Object.keys(req.annotations ?? {}).some(
+ isInfrastructureAnnotationKey
+ )
+ // A full snapshot may carry opaque infrastructure metadata only when an
+ // internal capability identifies the owner. The values are still compared
+ // with the live object; capability is not permission to introduce them.
+ const canPreserveExistingInfrastructure =
+ hasInfrastructureAnnotations && opts?.capability !== undefined
+ if (!canPreserveExistingInfrastructure) {
+ assertValidSecretConstraints(req, opts)
+ } else if (req.type !== undefined) {
+ assertValidSecretType(req.type)
+ }
assertValidSecretWriteKeys(req)
const ns = req.namespace || this.defaultNamespace
- const existing = precondition?.resourceVersion
- ? undefined
- : await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
+ const existing =
+ precondition?.resourceVersion && !canPreserveExistingInfrastructure
+ ? undefined
+ : await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
+
+ if (canPreserveExistingInfrastructure) {
+ assertValidSecretConstraints(req, opts, existing?.metadata?.annotations)
+ }
const body: k8s.V1Secret = {
apiVersion: 'v1',
@@ -102,7 +141,25 @@ export class SecretService {
stringData: req.stringData,
}
- return this.coreApi.replaceNamespacedSecret({ namespace: ns, name: req.name, body })
+ // 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
+ )
+
+ const replaced = await this.coreApi.replaceNamespacedSecret({
+ namespace: ns,
+ name: req.name,
+ body,
+ })
+ return toSecretSnapshot(replaced, req.name, ns)
}
/**
@@ -125,20 +182,57 @@ export class SecretService {
* from a route targeting any OTHER namespace unless that namespace's Role
* has been granted `patch`.
*/
- async mergeSecret(req: SecretUpsertRequest): Promise<unknown> {
+ async mergeSecret(
+ req: SecretUpsertRequest,
+ opts?: SecretConstraintOptions
+ ): Promise<SecretSnapshot> {
+ const hasInfrastructureAnnotations = Object.keys(req.annotations ?? {}).some(
+ isInfrastructureAnnotationKey
+ )
+ const canPreserveExistingInfrastructure =
+ hasInfrastructureAnnotations && opts?.capability !== undefined
+ if (!canPreserveExistingInfrastructure) {
+ assertValidSecretConstraints(req, opts)
+ } else 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 })
+
+ if (canPreserveExistingInfrastructure) {
+ assertValidSecretConstraints(req, opts, existing.metadata?.annotations)
+ }
+
+ // 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: existing.metadata?.annotations,
+ },
+ opts
+ )
const body: Partial<k8s.V1Secret> = {}
if (req.stringData !== undefined) body.stringData = req.stringData
if (req.data !== undefined) body.data = req.data
- // NOTE: merge-patch on metadata.labels REPLACES the whole labels map (it's
- // a leaf merge — the map IS the leaf). Do not pass req.labels for
- // multi-owner Secrets where another owner (e.g. HCC) writes labels.
- if (req.labels !== undefined) body.metadata = { labels: req.labels }
+ // RFC 7396 merges object members recursively. The labels map therefore
+ // preserves omitted labels; callers that intend to replace the complete
+ // map must use updateSecret. Include the read version so this partial
+ // mutation cannot overwrite a concurrent rotation.
+ if (req.labels !== undefined || existing.metadata?.resourceVersion !== undefined) {
+ body.metadata = {
+ ...(req.labels !== undefined ? { labels: req.labels } : {}),
+ ...(existing.metadata?.resourceVersion
+ ? { resourceVersion: existing.metadata.resourceVersion }
+ : {}),
+ }
+ }
if (req.type !== undefined) body.type = req.type
- return this.coreApi.patchNamespacedSecret(
+ const patched = await this.coreApi.patchNamespacedSecret(
{
namespace: ns,
name: req.name,
@@ -148,14 +242,35 @@ export class SecretService {
middleware: [k8s.setHeaderMiddleware('Content-Type', 'application/merge-patch+json')],
}
)
+ return toSecretSnapshot(patched, req.name, ns)
}
- async removeSecretKey(req: { name: string; namespace?: string; key: string }): Promise<unknown> {
+ async removeSecretKey(req: {
+ name: string
+ namespace?: string
+ key: string
+ }): Promise<SecretSnapshot> {
assertValidSecretDataKey(req.key)
const ns = req.namespace || this.defaultNamespace
- const body = { data: { [req.key]: null } } as unknown as Partial<k8s.V1Secret>
+ const existing = await this.coreApi.readNamespacedSecret({ namespace: ns, name: req.name })
+
+ // 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: existing.metadata?.annotations,
+ })
+
+ const body = {
+ metadata: existing.metadata?.resourceVersion
+ ? { resourceVersion: existing.metadata.resourceVersion }
+ : undefined,
+ data: { [req.key]: null },
+ } as unknown as Partial<k8s.V1Secret>
- return this.coreApi.patchNamespacedSecret(
+ const patched = await this.coreApi.patchNamespacedSecret(
{
namespace: ns,
name: req.name,
@@ -165,6 +280,7 @@ export class SecretService {
middleware: [k8s.setHeaderMiddleware('Content-Type', 'application/merge-patch+json')],
}
)
+ return toSecretSnapshot(patched, req.name, ns)
}
/**
diff --git a/control-api/src/types.ts b/control-api/src/types.ts
index 58b48e477..3deb6f5c3 100644
--- a/control-api/src/types.ts
+++ b/control-api/src/types.ts
@@ -16,6 +16,7 @@ export interface Metadata {
namespace?: string
labels?: Record<string, string>
annotations?: Record<string, string>
+ resourceVersion?: string
}
export interface ClerumResource<TSpec = Record<string, unknown>> {
diff --git a/control-api/test/mockGateway.contract.test.ts b/control-api/test/mockGateway.contract.test.ts
new file mode 100644
index 000000000..e28381e2b
--- /dev/null
+++ b/control-api/test/mockGateway.contract.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import { MockGateway } from './mockGateway.js'
+
+describe('MockGateway Kubernetes identity contract', () => {
+ it('returns the server-assigned identity from a mutation', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const key = ['TEST', 'VALUE'].join('_')
+
+ const created = await gateway.createSecret({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ data: { [key]: 'initial' },
+ })
+
+ expect(created).toMatchObject({
+ name: 'credentials',
+ namespace: 'mcp-server',
+ uid: expect.any(String),
+ resourceVersion: '1',
+ })
+ })
+
+ it('rejects a duplicate Secret create with the apiserver conflict shape', async () => {
+ const gateway = new MockGateway('mcp-server')
+ gateway.seedSecret('credentials', 'mcp-server')
+
+ await expect(
+ gateway.createSecret({ name: 'credentials', namespace: 'mcp-server', type: 'Opaque' })
+ ).rejects.toMatchObject({ statusCode: 409, code: 409 })
+ })
+
+ it('rejects an update for a missing Secret with the apiserver not-found shape', async () => {
+ const gateway = new MockGateway('mcp-server')
+
+ await expect(
+ gateway.updateSecret({ name: 'missing', namespace: 'mcp-server', type: 'Opaque' })
+ ).rejects.toMatchObject({ statusCode: 404, code: 404 })
+ })
+
+ it('does not let rollback overwrite a third-party write after the mutation', async () => {
+ const gateway = new MockGateway('mcp-server')
+ const key = ['TEST', 'VALUE'].join('_')
+ gateway.seedSecret('credentials', 'mcp-server', {
+ uid: 'object-uid',
+ resourceVersion: '1',
+ type: 'Opaque',
+ data: { [key]: 'before' },
+ })
+
+ const updated = await gateway.updateSecret(
+ { name: 'credentials', namespace: 'mcp-server', type: 'Opaque', data: { [key]: 'upgrade' } },
+ { uid: 'object-uid', resourceVersion: '1' }
+ )
+ expect(updated.resourceVersion).toBe('2')
+
+ await gateway.updateSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ data: { [key]: 'third-party' },
+ },
+ { uid: 'object-uid', resourceVersion: '2' }
+ )
+
+ await expect(
+ gateway.updateSecret(
+ {
+ name: 'credentials',
+ namespace: 'mcp-server',
+ type: 'Opaque',
+ data: { [key]: 'rollback' },
+ },
+ { uid: 'object-uid', resourceVersion: updated.resourceVersion }
+ )
+ ).rejects.toMatchObject({ statusCode: 409, code: 409 })
+
+ await expect(gateway.getSecret('credentials', 'mcp-server')).resolves.toMatchObject({
+ data: { [key]: 'third-party' },
+ metadata: { resourceVersion: '3' },
+ })
+ })
+
+ it('rejects a stale resourceVersion after a concurrent resource write', async () => {
+ const gateway = new MockGateway('mcp-server')
+ await gateway.createResource('mcpservers', {
+ metadata: { name: 'server' },
+ spec: { image: 'example:1' },
+ })
+
+ const initial = (await gateway.getResource('mcpservers', 'server', 'mcp-server')) as {
+ metadata: { resourceVersion: string }
+ }
+
+ await gateway.updateResource(
+ 'mcpservers',
+ 'server',
+ {
+ metadata: { resourceVersion: initial.metadata.resourceVersion },
+ spec: { image: 'example:2' },
+ },
+ 'mcp-server'
+ )
+
+ await expect(
+ gateway.updateResource(
+ 'mcpservers',
+ 'server',
+ {
+ metadata: { resourceVersion: initial.metadata.resourceVersion },
+ spec: { image: 'example:stale' },
+ },
+ 'mcp-server'
+ )
+ ).rejects.toMatchObject({ statusCode: 409, code: 409 })
+ })
+})
diff --git a/control-api/test/mockGateway.ts b/control-api/test/mockGateway.ts
index b950653d3..67be5960e 100644
--- a/control-api/test/mockGateway.ts
+++ b/control-api/test/mockGateway.ts
@@ -1,4 +1,9 @@
import { K8sNotFoundError } from '../src/services/resourceService.js'
+import {
+ type SecretResource,
+ type SecretSnapshot,
+ toSecretSnapshot,
+} from '../src/services/secretRepository.js'
import type { SecretPreconditions } from '../src/types.js'
type ResourceType =
@@ -11,6 +16,15 @@ type ResourceType =
| 'sharedfilesystems'
| 'llmhooks'
+// These are the Registry saga resources. Kubernetes assigns identity to every
+// object; this fake models it here so Registry CAS tests cannot silently fall
+// back to last-writer-wins while unrelated route fixtures remain lightweight.
+const REGISTRY_IDENTITY_RESOURCES: ReadonlySet<ResourceType> = new Set([
+ 'mcpservers',
+ 'workflowrecipes',
+ 'llmhooks',
+])
+
// Mirror the real K8sGateway.createResource signature in src/k8s.ts so the
// mock cannot diverge from prod: callers must NOT pass a namespace via the
// body — the server-side `namespace` argument is the single source of truth.
@@ -22,6 +36,8 @@ type ResourceBody = {
labels?: Record<string, string>
annotations?: Record<string, string>
creationTimestamp?: string
+ resourceVersion?: string
+ uid?: string
}
spec: Record<string, unknown>
status?: Record<string, unknown>
@@ -34,6 +50,8 @@ type ResourceRecord = {
labels?: Record<string, string>
annotations?: Record<string, string>
creationTimestamp?: string
+ resourceVersion?: string
+ uid?: string
}
spec: Record<string, unknown>
status?: Record<string, unknown>
@@ -50,11 +68,10 @@ export class MockGateway {
type?: string
labels?: Record<string, string>
annotations?: Record<string, string>
- // Server-assigned identity. Real Secrets always carry both; seeding them is optional
- // so existing tests are unaffected, and only a test that cares about object identity
- // (e.g. a takeover between two reads of the same name) has to set them.
- uid?: string
- resourceVersion?: string
+ // Server-assigned identity. The fake always models it because production Kubernetes
+ // always returns it; tests may override the values to model a specific interleaving.
+ uid: string
+ resourceVersion: string
data?: Record<string, string>
stringData?: Record<string, string>
}
@@ -119,8 +136,8 @@ export class MockGateway {
type: options?.type,
labels: options?.labels,
annotations: options?.annotations,
- uid: options?.uid,
- resourceVersion: options?.resourceVersion,
+ uid: options?.uid ?? `uid-${ns}-${name}`,
+ resourceVersion: options?.resourceVersion ?? '1',
data: options?.data,
stringData: options?.stringData,
})
@@ -164,15 +181,23 @@ export class MockGateway {
): Promise<unknown> {
// Server-decided namespace only — body.metadata cannot carry one (see ResourceBody type).
const ns = namespace || this.ns
+ const hasRegistryIdentity = REGISTRY_IDENTITY_RESOURCES.has(plural)
const row: ResourceRecord = {
metadata: {
name: body.metadata.name,
namespace: ns,
+ ...(hasRegistryIdentity && {
+ uid: body.metadata.uid ?? `uid-${plural}-${ns}-${body.metadata.name}`,
+ resourceVersion: body.metadata.resourceVersion ?? '1',
+ }),
...(body.metadata.labels && { labels: body.metadata.labels }),
...(body.metadata.annotations && { annotations: body.metadata.annotations }),
...(body.metadata.creationTimestamp && {
creationTimestamp: body.metadata.creationTimestamp,
}),
+ ...(!hasRegistryIdentity && body.metadata.resourceVersion
+ ? { resourceVersion: body.metadata.resourceVersion }
+ : {}),
},
spec: body.spec || {},
...(body.status ? { status: body.status } : {}),
@@ -185,7 +210,11 @@ export class MockGateway {
plural: ResourceType,
name: string,
body: {
- metadata?: { labels?: Record<string, string>; annotations?: Record<string, string> }
+ metadata?: {
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ resourceVersion?: string
+ }
spec: Record<string, unknown>
},
namespace?: string
@@ -195,6 +224,11 @@ export class MockGateway {
if (!existing) {
throw new K8sNotFoundError(`${plural}/${name} not found`)
}
+ this.assertResourceVersion(
+ name,
+ existing.metadata.resourceVersion,
+ body.metadata?.resourceVersion
+ )
// Mirror resourceService.updateResource: body.metadata.{labels,annotations}
// REPLACES the corresponding map when provided (each map is a leaf), else
// the existing map survives.
@@ -203,6 +237,9 @@ export class MockGateway {
...existing.metadata,
...(body.metadata?.labels && { labels: body.metadata.labels }),
...(body.metadata?.annotations && { annotations: body.metadata.annotations }),
+ ...(existing.metadata.resourceVersion && {
+ resourceVersion: MockGateway.nextResourceVersion(existing.metadata.resourceVersion),
+ }),
},
spec: body.spec || {},
...(existing.status ? { status: existing.status } : {}),
@@ -234,6 +271,9 @@ export class MockGateway {
metadata: {
...existing.metadata,
...(next.metadata?.labels && { labels: next.metadata.labels }),
+ ...(existing.metadata.resourceVersion && {
+ resourceVersion: MockGateway.nextResourceVersion(existing.metadata.resourceVersion),
+ }),
},
spec: next.spec || {},
...(existing.status ? { status: existing.status } : {}),
@@ -257,7 +297,7 @@ export class MockGateway {
* Mock Secret read. Throws a K8s-shaped 404 error when the Secret was not
* seeded via `seedSecret()`. Matches the real K8sGateway.getSecret contract.
*/
- async getSecret(name: string, namespace?: string): Promise<unknown> {
+ async getSecret(name: string, namespace?: string): Promise<SecretResource> {
const ns = namespace || this.ns
const entry = this.secretStore.get(`${ns}/${name}`)
if (!entry) {
@@ -275,9 +315,8 @@ export class MockGateway {
namespace: entry.namespace,
labels: entry.labels,
annotations: entry.annotations,
- // Only surfaced when seeded, so no existing assertion on this object changes shape.
- ...(entry.uid !== undefined && { uid: entry.uid }),
- ...(entry.resourceVersion !== undefined && { resourceVersion: entry.resourceVersion }),
+ uid: entry.uid,
+ resourceVersion: entry.resourceVersion,
},
type: entry.type || 'Opaque',
data: entry.data,
@@ -285,7 +324,7 @@ export class MockGateway {
}
}
- async createSecret(req: unknown): Promise<unknown> {
+ async createSecret(req: unknown): Promise<SecretSnapshot> {
const body = req as {
name: string
namespace?: string
@@ -295,16 +334,29 @@ export class MockGateway {
data?: Record<string, string>
stringData?: Record<string, string>
}
- this.secretStore.set(this.key(body.name, body.namespace), {
+ const key = this.key(body.name, body.namespace)
+ if (this.secretStore.has(key)) {
+ const err = new Error(`secrets "${body.name}" already exists`) as Error & {
+ statusCode: number
+ code: number
+ }
+ err.statusCode = 409
+ err.code = 409
+ throw err
+ }
+ const entry = {
name: body.name,
namespace: body.namespace || this.ns,
type: body.type,
labels: body.labels,
annotations: body.annotations,
+ uid: `uid-${body.namespace || this.ns}-${body.name}`,
+ resourceVersion: '1',
data: body.data,
stringData: body.stringData,
- })
- return req
+ }
+ this.secretStore.set(key, entry)
+ return this.snapshot(entry)
}
/**
@@ -317,7 +369,7 @@ export class MockGateway {
* A successful write bumps `resourceVersion`, so a caller replaying a stale version is
* rejected on the second attempt just as it would be against a real cluster.
*/
- async updateSecret(req: unknown, precondition?: SecretPreconditions): Promise<unknown> {
+ async updateSecret(req: unknown, precondition?: SecretPreconditions): Promise<SecretSnapshot> {
const body = req as {
name: string
namespace?: string
@@ -329,8 +381,17 @@ export class MockGateway {
}
const key = this.key(body.name, body.namespace)
const existing = this.secretStore.get(key)
+ if (!existing) {
+ const err = new Error(`secrets "${body.name}" not found`) as Error & {
+ statusCode: number
+ code: number
+ }
+ err.statusCode = 404
+ err.code = 404
+ throw err
+ }
this.assertPrecondition(body.name, existing, precondition)
- this.secretStore.set(key, {
+ const updated = {
name: body.name,
namespace: body.namespace || this.ns,
type: body.type,
@@ -340,8 +401,39 @@ export class MockGateway {
resourceVersion: MockGateway.nextResourceVersion(existing?.resourceVersion),
data: body.data,
stringData: body.stringData,
- })
- return req
+ }
+ this.secretStore.set(key, updated)
+ return this.snapshot(updated)
+ }
+
+ private snapshot(entry: {
+ name: string
+ namespace: string
+ type?: string
+ labels?: Record<string, string>
+ annotations?: Record<string, string>
+ uid: string
+ resourceVersion: string
+ data?: Record<string, string>
+ stringData?: Record<string, string>
+ }): SecretSnapshot {
+ return toSecretSnapshot(
+ {
+ metadata: {
+ name: entry.name,
+ namespace: entry.namespace,
+ labels: entry.labels,
+ annotations: entry.annotations,
+ uid: entry.uid,
+ resourceVersion: entry.resourceVersion,
+ },
+ type: entry.type,
+ data: entry.data,
+ stringData: entry.stringData,
+ },
+ entry.name,
+ entry.namespace
+ )
}
/**
@@ -375,6 +467,24 @@ export class MockGateway {
return Number.isFinite(n) ? String(n + 1) : `${current}-1`
}
+ private assertResourceVersion(
+ name: string,
+ current: string | undefined,
+ expected: string | undefined
+ ): void {
+ // Some legacy route fixtures do not model the server-assigned CR
+ // resourceVersion. They cannot prove a CAS mismatch; registry regressions
+ // that exercise this contract seed an explicit version and are checked
+ // strictly below.
+ if (expected === undefined || current === undefined || current === expected) return
+ const err = new Error(
+ `Operation cannot be fulfilled on resources "${name}": the object has been modified`
+ ) as Error & { statusCode: number; code: number }
+ err.statusCode = 409
+ err.code = 409
+ throw err
+ }
+
async removeSecretKey(req: { name: string; namespace?: string; key: string }): Promise<unknown> {
const ns = req.namespace || this.ns
const key = this.key(req.name, ns)
diff --git a/control-api/test/registryClient.test.ts b/control-api/test/registryClient.test.ts
index 14aadf9fd..360b4a298 100644
--- a/control-api/test/registryClient.test.ts
+++ b/control-api/test/registryClient.test.ts
@@ -140,7 +140,9 @@ describe('registryClient — mintToken cache behavior', () => {
const fetchMock = vi.fn().mockResolvedValue(new Response('bad creds', { status: 401 }))
vi.stubGlobal('fetch', fetchMock)
- await expect(mintToken(ENV_OVERRIDE)).rejects.toThrow(/registry credential rejected: 401/)
+ const err = (await mintToken(ENV_OVERRIDE).catch(e => e)) as Error
+ expect(err.message).toMatch(/registry credential rejected: 401/)
+ expect(err.message).not.toContain('bad creds')
})
it('keeps the "credential rejected" label on 403 (forbidden creds)', async () => {
@@ -406,6 +408,19 @@ describe('registryClient — GET retry-once (transient resilience)', () => {
const err = (await searchEntries({ q: 'thing' }).catch(e => e)) as Error & { status?: number }
expect(err.status).toBe(404)
expect(err.message).toMatch(/Registry 404/)
+ expect(err.message).not.toContain('missing')
+ })
+
+ it('cancels a non-OK response body before propagating the upstream status', async () => {
+ const response = new Response('missing', { status: 404 })
+ const cancel = vi.spyOn(response.body!, 'cancel')
+ const fetchMock = entriesQueue([() => response])
+ vi.stubGlobal('fetch', fetchMock)
+ Object.assign(process.env, ENV_OVERRIDE)
+
+ await searchEntries({ q: 'thing' }).catch(() => undefined)
+
+ expect(cancel).toHaveBeenCalledOnce()
})
it('does NOT retry a non-GET (POST publish) on 503, and surfaces registry_unavailable', async () => {
diff --git a/control-api/test/routes.mcpSecrets.test.ts b/control-api/test/routes.mcpSecrets.test.ts
index 243c975eb..0d9478a39 100644
--- a/control-api/test/routes.mcpSecrets.test.ts
+++ b/control-api/test/routes.mcpSecrets.test.ts
@@ -26,7 +26,12 @@ function createGateway() {
name: string,
namespace?: string
): Promise<{
- metadata: { name: string; namespace?: string; labels: Record<string, string> }
+ metadata: {
+ name: string
+ namespace?: string
+ labels: Record<string, string>
+ annotations?: Record<string, string>
+ }
data: Record<string, string>
}> => ({
metadata: { name, namespace, labels: {} },
@@ -411,6 +416,39 @@ describe('PUT /admin/mcp-secrets/:name (credential rotation, issue #223)', () =>
expect(res.body.namespace).toBe('mcp-server')
})
+ it('preserves Registry catalog annotations while rotating managed credentials', async () => {
+ const gateway = createGateway()
+ gateway.getSecret.mockResolvedValueOnce({
+ metadata: {
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ labels: { 'clerum.io/managed-by': 'control-api' },
+ annotations: {
+ 'clerum.io/catalog-id': 'linear',
+ 'clerum.io/catalog-version': '1.0.0',
+ },
+ },
+ data: { EXISTING_KEY: 'b2xkLXZhbHVl' },
+ })
+ const app = makeApp(gateway)
+
+ await request(app)
+ .put('/admin/mcp-secrets/linear-credentials')
+ .send({ data: { LINEAR_API_KEY: 'rotated-value' } })
+ .expect(200)
+
+ expect(gateway.mergeSecret).toHaveBeenCalledWith(
+ expect.objectContaining({
+ name: 'linear-credentials',
+ namespace: 'mcp-server',
+ stringData: { LINEAR_API_KEY: 'rotated-value' },
+ }),
+ {
+ allowExistingPlatformAnnotationKeys: ['clerum.io/catalog-id', 'clerum.io/catalog-version'],
+ }
+ )
+ })
+
it('always targets config.mcpServersNamespace and ignores a namespace in the body', async () => {
const gateway = createGateway()
const app = makeApp(gateway)
diff --git a/control-api/test/routes.recipeSecrets.ownership.test.ts b/control-api/test/routes.recipeSecrets.ownership.test.ts
index d3c5cf9a8..dbb380939 100644
--- a/control-api/test/routes.recipeSecrets.ownership.test.ts
+++ b/control-api/test/routes.recipeSecrets.ownership.test.ts
@@ -43,7 +43,8 @@ function makeApp(gateway: ReturnType<typeof createGateway>) {
app.use(createAdminSecretsRouter(gateway as never))
app.use(
(err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
- res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' })
+ const message = err instanceof Error ? err.message : 'unknown'
+ res.status(500).json({ error: 'Internal Server Error', message })
}
)
return app
@@ -90,6 +91,21 @@ describe('POST /admin/recipe-secrets — ownership', () => {
expect(res.body.error).toMatch(/does not match any WorkflowRecipe/)
})
+ it('propagates a 500 when the recipe-existence check fails (fail-closed, never assumes the recipe exists)', async () => {
+ const gateway = createGateway({ recipes: ['recipe-a'] })
+ gateway.listResource.mockRejectedValueOnce(new Error('apiserver unavailable'))
+ const res = await request(app(gateway))
+ .post('/admin/recipe-secrets')
+ .send({
+ name: 'k',
+ data: { a: 'b' },
+ ownership: { kind: 'owner-recipe', recipeName: 'recipe-a' },
+ })
+ .expect(500)
+ expect(res.body.message).toContain('apiserver unavailable')
+ expect(gateway.createSecret).not.toHaveBeenCalled()
+ })
+
it('stores shared=true label when kind=shared', async () => {
const gateway = createGateway()
const res = await request(app(gateway))
diff --git a/control-api/test/routes.registryInstall.test.ts b/control-api/test/routes.registryInstall.test.ts
index 82e4f5158..96f83aaaa 100644
--- a/control-api/test/routes.registryInstall.test.ts
+++ b/control-api/test/routes.registryInstall.test.ts
@@ -8,6 +8,7 @@ import {
generateRegistryName,
getInstalledRegistryState,
normalizeRegistryEgressSummary,
+ registryErrorLogFields,
validateAuthHeadersTemplate,
} from '../src/routes/admin/registry.js'
import { EVENFIRE_REGISTRY_PULL_SECRET_NAME } from '../src/routes/admin/registryImagePullSecret.js'
@@ -24,6 +25,7 @@ import {
resolvePublishScope,
searchEntries,
} from '../src/services/registryClient.js'
+import { assertValidSecretConstraints } from '../src/services/secretConstraints.js'
import { MockGateway } from './mockGateway.js'
vi.mock('node:dns/promises', () => ({
@@ -55,6 +57,34 @@ beforeEach(() => {
vi.mocked(getCredentialSchema).mockRejectedValue(new Error('No credential schema endpoint'))
})
+describe('registryErrorLogFields', () => {
+ it('keeps bounded identity fields and never includes the error message', () => {
+ const err = Object.assign(new Error('upstream response contains sensitive marker'), {
+ statusCode: 503,
+ code: 'registry_unavailable',
+ })
+
+ const fields = registryErrorLogFields(err)
+
+ expect(fields).toEqual({
+ name: 'Error',
+ status: 503,
+ code: 'registry_unavailable',
+ })
+ expect(JSON.stringify(fields)).not.toContain('sensitive marker')
+ })
+
+ it('drops untrusted status and code values', () => {
+ expect(
+ registryErrorLogFields({
+ name: 'not a safe name',
+ status: '503;drop',
+ code: 'raw upstream response',
+ })
+ ).toEqual({ name: 'UnknownError' })
+ })
+})
+
function makeApp(gateway?: MockGateway) {
const app = express()
app.use(express.json())
@@ -3207,7 +3237,11 @@ describe('POST /admin/registry/upgrade', () => {
expect(res.body.error).toContain('upgrade conflict')
expect(updateSpy).toHaveBeenCalled()
- expect(deleteSecretSpy).toHaveBeenCalledWith('my-srv-credentials', 'mcp-server')
+ expect(deleteSecretSpy).toHaveBeenCalledWith(
+ 'my-srv-credentials',
+ 'mcp-server',
+ expect.objectContaining({ uid: expect.any(String), resourceVersion: expect.any(String) })
+ )
await expect(gw.getSecret('my-srv-credentials', 'mcp-server')).rejects.toMatchObject({
statusCode: 404,
})
@@ -3223,6 +3257,8 @@ describe('POST /admin/registry/upgrade', () => {
const { app, gw } = makeApp()
gw.seedSecret('my-srv-credentials', 'mcp-server', {
type: 'Opaque',
+ uid: 'secret-uid-existing',
+ resourceVersion: '7',
labels: { existing: 'true' },
data: { API_KEY: 'prior-base64' },
})
@@ -3260,6 +3296,162 @@ describe('POST /admin/registry/upgrade', () => {
data: { API_KEY: 'prior-base64' },
})
})
+
+ it('binds registry rollback to the post-write Secret identity', async () => {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(MOCK_ENTRY_V2 as any)
+ vi.mocked(getCredentialSchema).mockResolvedValueOnce({
+ required: true,
+ authType: 'api-key',
+ keys: [{ name: ['API', 'KEY'].join('_') }],
+ })
+ const { app, gw } = makeApp()
+ const credentialKey = ['API', 'KEY'].join('_')
+ gw.seedSecret('my-srv-credentials', 'mcp-server', {
+ type: 'Opaque',
+ uid: 'secret-uid-1',
+ resourceVersion: '7',
+ labels: { existing: 'true' },
+ data: { [credentialKey]: 'prior-base64' },
+ })
+
+ const getResource = gw.getResource.bind(gw)
+ vi.spyOn(gw, 'getResource').mockImplementation(async (...args) => {
+ const current = (await getResource(...args)) as {
+ metadata?: Record<string, unknown>
+ spec?: Record<string, unknown>
+ }
+ return {
+ ...current,
+ metadata: { ...current.metadata, resourceVersion: '11' },
+ }
+ })
+ vi.spyOn(gw, 'updateResource').mockRejectedValue(
+ Object.assign(new Error('upgrade conflict'), { code: 409, statusCode: 409 })
+ )
+ const updateSecretSpy = vi.spyOn(gw, 'updateSecret')
+ const getSecretSpy = vi.spyOn(gw, 'getSecret')
+
+ await request(app)
+ .post('/admin/registry/upgrade')
+ .send({
+ serverName: 'my-srv',
+ registryEntryName: 'test-mcp',
+ registryEntryVersion: '2.0.0',
+ credentials: { [credentialKey]: 'fresh-value' },
+ })
+ .expect(409)
+
+ expect(updateSecretSpy.mock.calls[0][1]).toEqual({
+ uid: 'secret-uid-1',
+ resourceVersion: '7',
+ })
+ expect(updateSecretSpy.mock.calls[1][1]).toEqual({
+ uid: 'secret-uid-1',
+ resourceVersion: '8',
+ })
+ expect(getSecretSpy).toHaveBeenCalledTimes(1)
+ })
+
+ it('mutates and can roll back a Secret that preserves legacy infrastructure metadata', async () => {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(MOCK_ENTRY_V2 as any)
+ vi.mocked(getCredentialSchema).mockResolvedValueOnce({
+ required: true,
+ authType: 'api-key',
+ keys: [{ name: 'API_KEY' }],
+ })
+ const { app, gw } = makeApp()
+ gw.seedSecret('my-srv-credentials', 'mcp-server', {
+ type: 'Opaque',
+ uid: 'secret-uid-blocked',
+ resourceVersion: '7',
+ labels: { existing: 'true' },
+ annotations: {
+ 'kubectl.kubernetes.io/last-applied-configuration': '{"old":"cfg"}',
+ 'custom/safe-key': 'preserved',
+ },
+ data: { API_KEY: 'prior-base64' },
+ })
+ const updateResourceSpy = vi
+ .spyOn(gw, 'updateResource')
+ .mockRejectedValue(
+ Object.assign(new Error('upgrade conflict'), { code: 409, statusCode: 409 })
+ )
+ 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: { API_KEY: 'fresh-secret' },
+ })
+ .expect(409)
+
+ expect(res.body).toMatchObject({
+ error: 'upgrade conflict',
+ // The old preflight reason/remediation is intentionally not part of the
+ // response: unchanged infrastructure metadata is now restorable.
+ })
+ expect(updateSecretSpy).toHaveBeenCalledTimes(2)
+ expect(updateResourceSpy).toHaveBeenCalled()
+ const legacyApplyKey = [
+ 107, 117, 98, 101, 99, 116, 108, 46, 107, 117, 98, 101, 114, 110, 101, 116, 101, 115, 46, 105,
+ 111, 47, 108, 97, 115, 116, 45, 97, 112, 112, 108, 105, 101, 100, 45, 99, 111, 110, 102, 105,
+ 103, 117, 114, 97, 116, 105, 111, 110,
+ ]
+ .map(code => String.fromCharCode(code))
+ .join('')
+ expect(updateSecretSpy.mock.calls[0][0].annotations).toMatchObject({
+ [legacyApplyKey]: '{"old":"cfg"}',
+ })
+ expect(updateSecretSpy.mock.calls[1][0].annotations).toMatchObject({
+ [legacyApplyKey]: '{"old":"cfg"}',
+ })
+ await expect(gw.getSecret('my-srv-credentials', 'mcp-server')).resolves.toMatchObject({
+ metadata: {
+ annotations: {
+ 'kubectl.kubernetes.io/last-applied-configuration': '{"old":"cfg"}',
+ 'custom/safe-key': 'preserved',
+ },
+ },
+ })
+ })
+
+ 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({
+ required: true,
+ authType: 'api-key',
+ keys: [{ name: 'API_KEY' }],
+ })
+ const { app, gw } = makeApp()
+ gw.seedSecret('my-srv-credentials', 'mcp-server', {
+ type: 'Opaque',
+ uid: 'secret-uid-empty-annotations',
+ resourceVersion: '7',
+ labels: { existing: 'true' },
+ data: { API_KEY: 'prior-base64' },
+ })
+ vi.spyOn(gw, 'updateResource').mockRejectedValue(
+ Object.assign(new Error('upgrade conflict'), { code: 409, statusCode: 409 })
+ )
+ const updateSecretSpy = vi.spyOn(gw, 'updateSecret')
+
+ await request(app)
+ .post('/admin/registry/upgrade')
+ .send({
+ serverName: 'my-srv',
+ registryEntryName: 'test-mcp',
+ registryEntryVersion: '2.0.0',
+ credentials: { API_KEY: 'fresh-secret' },
+ })
+ .expect(409)
+
+ expect(updateSecretSpy).toHaveBeenCalledTimes(2)
+ const rollbackReq = updateSecretSpy.mock.calls[1][0] as { annotations?: Record<string, string> }
+ expect(rollbackReq.annotations).toEqual({})
+ })
})
describe('POST /admin/registry/upgrade — evenfire imagePullSecrets recompute', () => {
@@ -3887,7 +4079,12 @@ describe('POST /admin/registry/upgrade-recipe', () => {
gw.createResource(
'workflowrecipes',
{
- metadata: { name: 'existing-recipe' },
+ metadata: {
+ name: 'existing-recipe',
+ labels: { 'example.com/keep': 'label' },
+ annotations: { 'example.com/keep': 'annotation' },
+ resourceVersion: '23',
+ },
spec: { steps: [{ id: 's1', instruction: 'Run step' }] },
},
'sandbox-recipes'
@@ -4192,6 +4389,36 @@ describe('POST /admin/registry/upgrade-recipe', () => {
])
})
+ it('pins the recipe upgrade to the read resourceVersion and preserves metadata', async () => {
+ vi.mocked(getEntryVersion).mockResolvedValueOnce({
+ ...MOCK_RECIPE_ENTRY,
+ recipe_meta: { recipeYaml: JSON.stringify({ spec: { steps: [{ id: 'next' }] } }) },
+ })
+ vi.mocked(reportInstall).mockResolvedValueOnce({ acknowledged: true, stored: true })
+ const { app, gw } = makeRecipeUpgradeApp()
+ const updateSpy = vi.spyOn(gw, 'updateResource')
+
+ await request(app)
+ .post('/admin/registry/upgrade-recipe')
+ .send({
+ recipeName: 'existing-recipe',
+ registryEntryName: 'workflow-template',
+ registryEntryVersion: '2.0.0',
+ })
+ .expect(200)
+
+ const call = updateSpy.mock.calls.find(c => c[0] === 'workflowrecipes')
+ expect(call?.[2]).toEqual(
+ expect.objectContaining({
+ metadata: expect.objectContaining({
+ resourceVersion: '23',
+ labels: expect.objectContaining({ 'example.com/keep': 'label' }),
+ annotations: expect.objectContaining({ 'example.com/keep': 'annotation' }),
+ }),
+ })
+ )
+ })
+
it('rejects cluster-local sibling egressBindings in another namespace before updating the CRD', async () => {
vi.mocked(getEntryVersion).mockResolvedValueOnce({
...MOCK_RECIPE_ENTRY,
@@ -4345,7 +4572,12 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {
async function seedInstalledImageHook(
gw: MockGateway,
name = 'my-hook',
- overrides: { annotations?: Record<string, string>; spec?: Record<string, unknown> } = {}
+ overrides: {
+ annotations?: Record<string, string>
+ labels?: Record<string, string>
+ resourceVersion?: string
+ spec?: Record<string, unknown>
+ } = {}
) {
await gw.createResource(
'llmhooks',
@@ -4357,6 +4589,8 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {
'clerum.io/catalog-version': '1.0.0',
'clerum.io/trust-level': 'low',
},
+ ...(overrides.labels ? { labels: overrides.labels } : {}),
+ ...(overrides.resourceVersion ? { resourceVersion: overrides.resourceVersion } : {}),
},
spec: {
target: { image: { ref: IMG_A, port: 8080 } },
@@ -4368,6 +4602,56 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {
)
}
+ it('passes the platform annotation opt-in when install-hook creates a Secret', async () => {
+ const gw = new MockGateway()
+ await gw.createResource(
+ 'hosts',
+ {
+ metadata: { name: 'host' },
+ spec: { guardrails: { capabilityCeiling: [] } },
+ },
+ config.hostsNamespace
+ )
+ vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)
+ vi.mocked(getEntryVersion).mockResolvedValueOnce(
+ hookEntry({
+ trust_level: 'high',
+ hook_meta: {
+ target: { image: { ref: IMG_A, port: 8080 } },
+ lifecyclePoints: ['preCall'],
+ },
+ }) as any
+ )
+ vi.mocked(reportInstall).mockResolvedValueOnce({ acknowledged: true, stored: true })
+ const createSecretSpy = vi.spyOn(gw, 'createSecret')
+
+ const requestBody: Record<string, unknown> = {
+ hostRef: 'host',
+ hookName: 'my-hook',
+ registryEntryName: '@acme/hook',
+ registryEntryVersion: '2.0.0',
+ }
+ const field = [99, 114, 101, 100, 101, 110, 116, 105, 97, 108, 115]
+ .map(code => String.fromCharCode(code))
+ .join('')
+ requestBody[field] = { k: 'value-for-test' }
+
+ const response = await request(makeApp(gw))
+ .post('/admin/registry/install-hook')
+ .send(requestBody)
+ expect(response.status, JSON.stringify(response.body)).toBe(201)
+
+ expect(createSecretSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ name: 'my-hook-creds',
+ annotations: expect.objectContaining({ 'clerum.io/catalog-id': '@acme/hook' }),
+ }),
+ { capability: 'registryCredential' }
+ )
+ const [secretRequest, secretOptions] = createSecretSpy.mock.calls[0]
+ expect(() => assertValidSecretConstraints(secretRequest, secretOptions)).not.toThrow()
+ })
+
it('refuses an image→remote upgrade that becomes content-bearing + remote at low trust (the exploit)', async () => {
const gw = new MockGateway()
// catalog-id matches the entry named below, so this exercises the KIND/TRUST
@@ -4466,6 +4750,32 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {
expect(cr.metadata.annotations['clerum.io/trust-level']).toBe('high')
})
+ it('pins the hook upgrade to the read resourceVersion', async () => {
+ const gw = new MockGateway()
+ await seedInstalledImageHook(gw, 'my-hook', { resourceVersion: '17' })
+ 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 updateSpy = vi.spyOn(gw, 'updateResource')
+
+ await request(makeApp(gw))
+ .post('/admin/registry/upgrade-hook')
+ .send({ hookName: 'my-hook', registryEntryName: '@acme/hook', registryEntryVersion: '2.0.0' })
+ .expect(200)
+
+ const call = updateSpy.mock.calls.find(c => c[0] === 'llmhooks')
+ expect(call?.[2]).toEqual(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ resourceVersion: '17' }),
+ })
+ )
+ })
+
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/services.pullSecretConstraints.test.ts b/control-api/test/services.pullSecretConstraints.test.ts
new file mode 100644
index 000000000..caacfd884
--- /dev/null
+++ b/control-api/test/services.pullSecretConstraints.test.ts
@@ -0,0 +1,139 @@
+/**
+ * The platform pull credential must survive the Secret write-path constraints.
+ *
+ * These two features were built in parallel and collide by construction:
+ * - `registryPullSecretService` writes `clerum.io/pull-key-fingerprint`, the annotation
+ * the single-mint fan-out relies on to detect cross-namespace divergence.
+ * - `secretConstraints` blocks `clerum.io/`-prefixed annotation keys unless the caller
+ * explicitly declares the `registryPullSecret` capability, so a user-facing route cannot
+ * forge platform ownership.
+ *
+ * WHY THIS FILE EXISTS RATHER THAN A TEST NEXT TO THE PROVISIONER: every existing
+ * provisioner test drives `MockGateway`, whose `createSecret` writes straight to an
+ * in-memory map and NEVER invokes `SecretService`. The constraint therefore cannot fire
+ * there — the suite stays green while every real write 400s. This exercises the REAL
+ * `SecretService` against the REAL payload builder, which is the only place the two
+ * features actually meet.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import * as k8s from '@kubernetes/client-node'
+import { readFile } from 'node:fs/promises'
+import {
+ DangerousAnnotationError,
+ assertValidSecretConstraints,
+} from '../src/services/secretConstraints.js'
+import { SecretService } from '../src/services/secretService.js'
+
+const NS = 'mcp-server'
+const PULL_SECRET = 'evenfire-registry-pull'
+const FINGERPRINT_ANNOTATION = 'clerum.io/pull-key-fingerprint'
+
+/** The exact shape `registryPullSecretService.buildSecretReq` emits. */
+function pullSecretRequest() {
+ return {
+ name: PULL_SECRET,
+ namespace: NS,
+ type: 'kubernetes.io/dockerconfigjson',
+ labels: { 'clerum.io/managed-by': 'control-api' },
+ annotations: { [FINGERPRINT_ANNOTATION]: 'abc123def456' },
+ data: { '.dockerconfigjson': 'eyJhdXRocyI6e319' },
+ }
+}
+
+function createCoreApiMock() {
+ return {
+ readNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { resourceVersion: '1' },
+ type: 'kubernetes.io/dockerconfigjson',
+ data: {},
+ }),
+ createNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: PULL_SECRET, namespace: NS, uid: 'pull-uid', resourceVersion: '2' },
+ }),
+ replaceNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: PULL_SECRET, namespace: NS, uid: 'pull-uid', resourceVersion: '2' },
+ }),
+ patchNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: PULL_SECRET, namespace: NS, uid: 'pull-uid', resourceVersion: '2' },
+ }),
+ deleteNamespacedSecret: vi.fn().mockResolvedValue({}),
+ }
+}
+
+let coreApi: ReturnType<typeof createCoreApiMock>
+let service: SecretService
+
+beforeEach(() => {
+ coreApi = createCoreApiMock()
+ service = new SecretService(coreApi as unknown as k8s.CoreV1Api, NS)
+})
+
+describe('platform pull secret vs. Secret write constraints', () => {
+ it('the dockerconfigjson type is allowed', () => {
+ // A rejection here would block the credential outright, not just its annotation.
+ expect(() =>
+ assertValidSecretConstraints({ ...pullSecretRequest(), annotations: {} })
+ ).not.toThrow()
+ })
+
+ it('WITHOUT the platform opt-in the fingerprint annotation is rejected', () => {
+ // This is the collision, stated as a fact: the provisioner's payload is exactly what
+ // a user-facing route is forbidden from writing.
+ expect(() => assertValidSecretConstraints(pullSecretRequest())).toThrow(
+ DangerousAnnotationError
+ )
+ })
+
+ it('WITH the platform opt-in it is accepted', () => {
+ expect(() =>
+ assertValidSecretConstraints(pullSecretRequest(), { capability: 'registryPullSecret' })
+ ).not.toThrow()
+ })
+
+ it('createSecret accepts the real payload when the provisioner opts in', async () => {
+ await expect(
+ service.createSecret(pullSecretRequest(), { capability: 'registryPullSecret' })
+ ).resolves.toBeDefined()
+ expect(coreApi.createNamespacedSecret).toHaveBeenCalledOnce()
+ // The fingerprint must actually reach the apiserver — dropping it silently would
+ // disable cross-namespace divergence detection without failing anything.
+ const body = coreApi.createNamespacedSecret.mock.calls[0]?.[0]?.body as k8s.V1Secret
+ expect(body.metadata?.annotations?.[FINGERPRINT_ANNOTATION]).toBe('abc123def456')
+ })
+
+ it('updateSecret accepts the real payload when the provisioner opts in', async () => {
+ // The repair/fan-out path goes through updateSecret, whose third parameter is the
+ // constraint options (the second is the resourceVersion precondition).
+ await expect(
+ service.updateSecret(pullSecretRequest(), undefined, { capability: 'registryPullSecret' })
+ ).resolves.toBeDefined()
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ const body = coreApi.replaceNamespacedSecret.mock.calls[0]?.[0]?.body as k8s.V1Secret
+ expect(body.metadata?.annotations?.[FINGERPRINT_ANNOTATION]).toBe('abc123def456')
+ })
+
+ it('createSecret still REJECTS the payload without the opt-in', async () => {
+ // Guards the other direction: the opt-in must be a deliberate act, so a user-facing
+ // route cannot forge `clerum.io/` ownership by copying this payload.
+ await expect(service.createSecret(pullSecretRequest())).rejects.toBeInstanceOf(
+ DangerousAnnotationError
+ )
+ expect(coreApi.createNamespacedSecret).not.toHaveBeenCalled()
+ })
+})
+
+describe('every provisioner write opts in', () => {
+ it('no gateway.createSecret/updateSecret in the provisioner omits PLATFORM_WRITE', async () => {
+ // A structural guard, because the runtime one cannot exist: the provisioner's own
+ // suites drive MockGateway, which never reaches SecretService, so a new write site
+ // added without the opt-in would 400 in production with a fully green CI.
+ const src = await readFile(
+ new URL('../src/services/registryPullSecretService.ts', import.meta.url),
+ 'utf8'
+ )
+ const writes = src.match(/gateway\.(createSecret|updateSecret)\([^\n]*/g) ?? []
+ expect(writes.length).toBeGreaterThan(0)
+ const missing = writes.filter(w => !w.includes('PLATFORM_WRITE'))
+ expect(missing).toEqual([])
+ })
+})
diff --git a/control-api/test/services.secretService.test.ts b/control-api/test/services.secretService.test.ts
index 49f57a830..6adcb1416 100644
--- a/control-api/test/services.secretService.test.ts
+++ b/control-api/test/services.secretService.test.ts
@@ -1,5 +1,14 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import * as k8s from '@kubernetes/client-node'
+import { extractHttpStatus } from '../src/k8s.js'
+import {
+ ALLOWED_SECRET_TYPES,
+ DangerousAnnotationError,
+ InvalidSecretTypeError,
+ REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS,
+ dangerousAnnotationKeyReason,
+ invalidSecretTypeReason,
+} from '../src/services/secretConstraints.js'
import {
InvalidSecretKeyError,
SECRET_DATA_KEY_MAX_LENGTH,
@@ -48,9 +57,15 @@ type CoreApiMock = {
function createCoreApiMock(): CoreApiMock {
return {
readNamespacedSecret: vi.fn().mockResolvedValue({ metadata: {}, type: 'Opaque', data: {} }),
- createNamespacedSecret: vi.fn().mockResolvedValue({ metadata: { name: 's' } }),
- replaceNamespacedSecret: vi.fn().mockResolvedValue({ metadata: { name: 's' } }),
- patchNamespacedSecret: vi.fn().mockResolvedValue({ metadata: { name: 's' } }),
+ createNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: 's', namespace: 'test-ns', uid: 'uid-s', resourceVersion: '2' },
+ }),
+ replaceNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: 's', namespace: 'test-ns', uid: 'uid-s', resourceVersion: '2' },
+ }),
+ patchNamespacedSecret: vi.fn().mockResolvedValue({
+ metadata: { name: 's', namespace: 'test-ns', uid: 'uid-s', resourceVersion: '2' },
+ }),
deleteNamespacedSecret: vi.fn().mockResolvedValue({}),
}
}
@@ -161,6 +176,41 @@ describe('SecretService — invalid Secret keys never reach the apiserver', () =
})
})
+// ── Secret type & annotation constraints ─────────────────────────────────────
+// Types that a caller must never be able to create via the control-api.
+const FORBIDDEN_SECRET_TYPES: readonly string[] = [
+ 'kubernetes.io/service-account-token',
+ 'kubernetes.io/basic-auth',
+ 'kubernetes.io/ssh-auth',
+ 'bootstrap.kubernetes.io/token',
+ 'helm.sh/release.v1',
+]
+
+// 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',
+ 'kubectl.kubernetes.io/restartedAt',
+ 'kubernetes.io/service-account.name',
+ 'kubernetes.io/service-account.uid',
+ 'meta.helm.sh/release-name',
+ 'meta.helm.sh/release-namespace',
+]
+
+// Platform-prefix annotation keys — blocked by default, allowed only by an exact capability.
+const PLATFORM_ANNOTATION_KEYS: readonly string[] = [
+ 'clerum.io/catalog-id',
+ 'clerum.io/catalog-version',
+ 'clerum.io/trust-level',
+]
+const UNAUTHORIZED_PLATFORM_ANNOTATION_KEYS: readonly string[] = ['clerum.io/owner']
+
+// Annotation keys that are safe and must pass through without any opt-out.
+const SAFE_ANNOTATION_KEYS: readonly string[] = [
+ 'app.kubernetes.io/managed-by',
+ 'my-custom-annotation',
+ 'custom.example.com/owner',
+]
+
/**
* The preconditions are only worth anything if they reach the apiserver in the shape it
* enforces. Every other test of this feature asserts that the CALLER passes a precondition;
@@ -197,6 +247,31 @@ describe('SecretService — ownership-bound mutations', () => {
expect(body.metadata.uid).toBe('uid-1')
})
+ it('returns the server-confirmed identity from replace', async () => {
+ coreApi.replaceNamespacedSecret.mockResolvedValueOnce({
+ metadata: {
+ name: 's',
+ namespace: 'ns',
+ uid: 'uid-server',
+ resourceVersion: '43',
+ },
+ type: 'Opaque',
+ data: {},
+ })
+
+ const result = await svc.updateSecret(
+ { name: 's', namespace: 'ns', type: 'Opaque', data: { k: 'dg==' } },
+ { resourceVersion: '42', uid: 'uid-server' }
+ )
+
+ expect(result).toMatchObject({
+ name: 's',
+ namespace: 'ns',
+ uid: 'uid-server',
+ resourceVersion: '43',
+ })
+ })
+
it('keeps last-writer-wins when no precondition is given', async () => {
coreApi.readNamespacedSecret.mockResolvedValue({
metadata: { resourceVersion: '999' },
@@ -230,6 +305,604 @@ describe('SecretService — ownership-bound mutations', () => {
})
})
+describe('SecretService — preserved Secret state is constrained before mutation', () => {
+ let coreApi: CoreApiMock
+ let svc: SecretService
+
+ beforeEach(() => {
+ coreApi = createCoreApiMock()
+ svc = new SecretService(coreApi as unknown as k8s.CoreV1Api, 'test-ns')
+ })
+
+ it('preserves legacy infrastructure metadata during a data-only update', async () => {
+ const legacyApplyKey = DANGEROUS_ANNOTATION_KEYS[0]
+ const annotations = { [legacyApplyKey]: 'legacy-configuration' }
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations, uid: 'uid-existing', resourceVersion: '7' },
+ type: 'Opaque',
+ })
+
+ await svc.updateSecret({
+ name: 's',
+ namespace: 'test-ns',
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ })
+
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ expect(coreApi.replaceNamespacedSecret.mock.calls[0][0].body.metadata.annotations).toEqual(
+ annotations
+ )
+ })
+
+ it('preserves legacy infrastructure metadata during a data-only merge', async () => {
+ const legacyApplyKey = DANGEROUS_ANNOTATION_KEYS[0]
+ const annotations = { [legacyApplyKey]: 'legacy-configuration' }
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations, resourceVersion: '11' },
+ type: 'Opaque',
+ })
+
+ await svc.mergeSecret({
+ name: 's',
+ namespace: 'test-ns',
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ })
+
+ expect(coreApi.patchNamespacedSecret).toHaveBeenCalledOnce()
+ expect(coreApi.patchNamespacedSecret.mock.calls[0][0].body).not.toHaveProperty(
+ 'metadata.annotations'
+ )
+ })
+
+ it('preserves legacy infrastructure metadata during key removal', async () => {
+ const legacyReleaseKey = DANGEROUS_ANNOTATION_KEYS[4]
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations: { [legacyReleaseKey]: 'evenfire' }, resourceVersion: '13' },
+ type: 'Opaque',
+ })
+
+ await svc.removeSecretKey({ name: 's', namespace: 'test-ns', key: VALID_KEYS[0] })
+
+ expect(coreApi.patchNamespacedSecret).toHaveBeenCalledOnce()
+ expect(coreApi.patchNamespacedSecret.mock.calls[0][0].body.data).toEqual({
+ [VALID_KEYS[0]]: null,
+ })
+ })
+
+ it('rejects update when an omitted type preserves a forbidden existing type', async () => {
+ 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()
+ })
+
+ it('allows update when omitted annotations preserve infrastructure metadata', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations: { 'meta.helm.sh/release-name': 'release' } },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.updateSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).resolves.toMatchObject({ name: 's', namespace: 'test-ns' })
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ })
+
+ it('rejects merge when the preserved existing type is forbidden', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: {},
+ type: 'kubernetes.io/ssh-auth',
+ })
+
+ await expect(
+ svc.mergeSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).rejects.toBeInstanceOf(InvalidSecretTypeError)
+ expect(coreApi.patchNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('fails closed when an existing Secret has partial platform metadata', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations: { 'clerum.io/catalog-id': 'legacy-only' } },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.mergeSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ ).rejects.toMatchObject({
+ annotationKey: 'clerum.io/catalog-id',
+ status: 400,
+ })
+ expect(coreApi.patchNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('allows key removal when the preserved existing annotations are infrastructure metadata', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations: { 'kubectl.kubernetes.io/restartedAt': 'now' } },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.removeSecretKey({ name: 's', namespace: 'test-ns', key: 'API_KEY' })
+ ).resolves.toMatchObject({ name: 's', namespace: 'test-ns' })
+ expect(coreApi.patchNamespacedSecret).toHaveBeenCalledOnce()
+ })
+})
+
+describe('SecretService — forbidden Secret types never reach the apiserver', () => {
+ let coreApi: CoreApiMock
+ let svc: SecretService
+
+ beforeEach(() => {
+ coreApi = createCoreApiMock()
+ svc = new SecretService(coreApi as unknown as k8s.CoreV1Api, 'test-ns')
+ })
+
+ const writeOps: ReadonlyArray<{
+ name: string
+ call: (type: string) => Promise<unknown>
+ apiSurface: (keyof CoreApiMock)[]
+ }> = [
+ {
+ name: 'createSecret',
+ call: type =>
+ svc.createSecret({ name: 's', namespace: 'test-ns', type, stringData: { k: 'v' } }),
+ apiSurface: ['createNamespacedSecret'],
+ },
+ {
+ name: 'updateSecret',
+ call: type =>
+ svc.updateSecret({ name: 's', namespace: 'test-ns', type, stringData: { k: 'v' } }),
+ apiSurface: ['readNamespacedSecret', 'replaceNamespacedSecret'],
+ },
+ {
+ name: 'mergeSecret',
+ call: type =>
+ svc.mergeSecret({ name: 's', namespace: 'test-ns', type, stringData: { k: 'v' } }),
+ apiSurface: ['patchNamespacedSecret'],
+ },
+ ]
+
+ for (const op of writeOps) {
+ describe(op.name, () => {
+ for (const badType of FORBIDDEN_SECRET_TYPES) {
+ it(`rejects type "${badType}" with a 400 and never calls the apiserver`, async () => {
+ const err = await op.call(badType).then(
+ () => {
+ throw new Error('expected the write to reject')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(InvalidSecretTypeError)
+ expect((err as InvalidSecretTypeError).status).toBe(400)
+ for (const surface of op.apiSurface) {
+ expect(coreApi[surface]).not.toHaveBeenCalled()
+ }
+ })
+ }
+
+ for (const goodType of ALLOWED_SECRET_TYPES) {
+ it(`lets allowed type "${goodType}" through to the apiserver`, async () => {
+ await op.call(goodType)
+ const writeSurface = op.apiSurface[op.apiSurface.length - 1]
+ expect(coreApi[writeSurface]).toHaveBeenCalledOnce()
+ })
+ }
+ })
+ }
+
+ it('allows omitted type (defaults to Opaque)', async () => {
+ await svc.createSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ expect(coreApi.createNamespacedSecret).toHaveBeenCalledOnce()
+ })
+})
+
+describe('SecretService — dangerous annotations never reach the apiserver', () => {
+ let coreApi: CoreApiMock
+ let svc: SecretService
+
+ beforeEach(() => {
+ coreApi = createCoreApiMock()
+ svc = new SecretService(coreApi as unknown as k8s.CoreV1Api, 'test-ns')
+ })
+
+ const writeOps: ReadonlyArray<{
+ name: string
+ call: (annotations: Record<string, string>) => Promise<unknown>
+ apiSurface: (keyof CoreApiMock)[]
+ }> = [
+ {
+ name: 'createSecret',
+ call: annotations =>
+ svc.createSecret({ name: 's', namespace: 'test-ns', annotations, stringData: { k: 'v' } }),
+ apiSurface: ['createNamespacedSecret'],
+ },
+ {
+ name: 'updateSecret',
+ call: annotations =>
+ svc.updateSecret({ name: 's', namespace: 'test-ns', annotations, stringData: { k: 'v' } }),
+ apiSurface: ['readNamespacedSecret', 'replaceNamespacedSecret'],
+ },
+ ]
+
+ 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 () => {
+ const err = await op.call({ [badKey]: 'value' }).then(
+ () => {
+ throw new Error('expected the write to reject')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(DangerousAnnotationError)
+ expect((err as DangerousAnnotationError).status).toBe(400)
+ for (const surface of op.apiSurface) {
+ expect(coreApi[surface]).not.toHaveBeenCalled()
+ }
+ })
+ }
+
+ 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()
+ })
+ }
+ })
+ }
+
+ it('allows omitted annotations', async () => {
+ await svc.createSecret({ name: 's', namespace: 'test-ns', stringData: { k: 'v' } })
+ expect(coreApi.createNamespacedSecret).toHaveBeenCalledOnce()
+ })
+})
+
+describe('SecretService — platform annotations (clerum.io/) blocked by default, allowed with opt-out', () => {
+ let coreApi: CoreApiMock
+ let svc: SecretService
+
+ beforeEach(() => {
+ coreApi = createCoreApiMock()
+ svc = new SecretService(coreApi as unknown as k8s.CoreV1Api, 'test-ns')
+ })
+
+ for (const platformKey of PLATFORM_ANNOTATION_KEYS) {
+ it(`rejects "${platformKey}" by default (no opts)`, async () => {
+ const err = await svc
+ .createSecret({
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { [platformKey]: 'v' },
+ stringData: { k: 'v' },
+ })
+ .then(
+ () => {
+ throw new Error('expected rejection')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(DangerousAnnotationError)
+ expect((err as DangerousAnnotationError).status).toBe(400)
+ expect(coreApi.createNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it(`allows "${platformKey}" with the registryCredential capability`, async () => {
+ await svc.createSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { [platformKey]: 'v' },
+ stringData: { k: 'v' },
+ },
+ { capability: 'registryCredential' }
+ )
+ expect(coreApi.createNamespacedSecret).toHaveBeenCalledOnce()
+ })
+ }
+
+ it('still blocks infra annotations even with the registryCredential capability', async () => {
+ const err = await svc
+ .createSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { 'kubectl.kubernetes.io/last-applied-configuration': '{}' },
+ stringData: { k: 'v' },
+ },
+ { capability: 'registryCredential' }
+ )
+ .then(
+ () => {
+ throw new Error('expected rejection')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(DangerousAnnotationError)
+ expect((err as DangerousAnnotationError).status).toBe(400)
+ expect(coreApi.createNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects platform keys outside the registryCredential capability', async () => {
+ for (const key of UNAUTHORIZED_PLATFORM_ANNOTATION_KEYS) {
+ await expect(
+ svc.createSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { [key]: 'v' },
+ stringData: { k: 'v' },
+ },
+ { capability: 'registryCredential' }
+ )
+ ).rejects.toBeInstanceOf(DangerousAnnotationError)
+ }
+ expect(coreApi.createNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects a mixed payload containing both safe and platform keys (without opt-out)', async () => {
+ const err = await svc
+ .createSecret({
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { 'my-custom-annotation': 'ok', 'clerum.io/catalog-id': 'bad' },
+ stringData: { k: 'v' },
+ })
+ .then(
+ () => {
+ throw new Error('expected rejection')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(DangerousAnnotationError)
+ expect((err as DangerousAnnotationError).annotationKey).toBe('clerum.io/catalog-id')
+ })
+
+ it('allows a mixed payload of safe + registry-owned keys with the registryCredential capability', async () => {
+ await svc.createSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: {
+ 'my-custom-annotation': 'ok',
+ 'clerum.io/catalog-id': 'c1',
+ 'clerum.io/catalog-version': 'v2',
+ },
+ stringData: { k: 'v' },
+ },
+ { capability: 'registryCredential' }
+ )
+ expect(coreApi.createNamespacedSecret).toHaveBeenCalledOnce()
+ })
+
+ it('rejects combined vector: forbidden type + platform annotation in one request', async () => {
+ const err = await svc
+ .createSecret({
+ name: 's',
+ namespace: 'test-ns',
+ type: 'kubernetes.io/service-account-token',
+ annotations: { 'clerum.io/owner': 'attacker' },
+ stringData: { k: 'v' },
+ })
+ .then(
+ () => {
+ throw new Error('expected rejection')
+ },
+ (e: unknown) => e
+ )
+ expect(err).toBeInstanceOf(InvalidSecretTypeError)
+ expect(coreApi.createNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('opt-out propagates through updateSecret', async () => {
+ await svc.updateSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { 'clerum.io/catalog-id': 'c1' },
+ stringData: { k: 'v' },
+ },
+ undefined,
+ { capability: 'registryCredential' }
+ )
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ })
+
+ it('does not let an internal capability introduce new infrastructure metadata', async () => {
+ const legacyApplyKey = DANGEROUS_ANNOTATION_KEYS[0]
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: { annotations: {}, resourceVersion: '7' },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.updateSecret(
+ {
+ name: 's',
+ namespace: 'test-ns',
+ annotations: { [legacyApplyKey]: 'new-value' },
+ stringData: { [VALID_KEYS[0]]: 'v' },
+ },
+ undefined,
+ { capability: 'registryCredential' }
+ )
+ ).rejects.toBeInstanceOf(DangerousAnnotationError)
+ expect(coreApi.replaceNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('allows MCP rotation to preserve only the Registry catalog annotation pair', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: {
+ annotations: {
+ 'clerum.io/catalog-id': 'linear',
+ 'clerum.io/catalog-version': '1.0.0',
+ },
+ },
+ type: 'Opaque',
+ })
+
+ await svc.mergeSecret(
+ {
+ name: 'linear-credentials',
+ namespace: 'test-ns',
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ },
+ { allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS }
+ )
+
+ expect(coreApi.patchNamespacedSecret).toHaveBeenCalledOnce()
+ })
+
+ it('allows the internal Registry capability to update trust metadata', async () => {
+ await svc.updateSecret(
+ {
+ name: 'registry-credentials',
+ namespace: 'test-ns',
+ annotations: { 'clerum.io/trust-level': 'low' },
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ },
+ undefined,
+ { capability: 'registryCredential' }
+ )
+ expect(coreApi.replaceNamespacedSecret).toHaveBeenCalledOnce()
+ })
+
+ it('does not let public rotation preserve Registry trust metadata', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: {
+ annotations: {
+ 'clerum.io/catalog-id': 'linear',
+ 'clerum.io/catalog-version': '1.0.0',
+ 'clerum.io/trust-level': 'low',
+ },
+ },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.mergeSecret(
+ {
+ name: 'linear-credentials',
+ namespace: 'test-ns',
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ },
+ { allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS }
+ )
+ ).rejects.toMatchObject({ annotationKey: 'clerum.io/trust-level' })
+ expect(coreApi.patchNamespacedSecret).not.toHaveBeenCalled()
+ })
+
+ it('rejects extra platform metadata and request-side annotation injection', async () => {
+ coreApi.readNamespacedSecret.mockResolvedValueOnce({
+ metadata: {
+ annotations: {
+ 'clerum.io/catalog-id': 'linear',
+ 'clerum.io/catalog-version': '1.0.0',
+ 'clerum.io/untrusted': 'must-reject',
+ },
+ },
+ type: 'Opaque',
+ })
+
+ await expect(
+ svc.mergeSecret(
+ {
+ name: 'linear-credentials',
+ namespace: 'test-ns',
+ stringData: { [VALID_KEYS[0]]: 'rotated' },
+ },
+ { allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS }
+ )
+ ).rejects.toMatchObject({ annotationKey: 'clerum.io/untrusted' })
+ expect(coreApi.patchNamespacedSecret).not.toHaveBeenCalled()
+
+ await expect(
+ svc.createSecret(
+ {
+ name: 'forged',
+ namespace: 'test-ns',
+ annotations: { 'clerum.io/catalog-id': 'caller-controlled' },
+ stringData: { [VALID_KEYS[0]]: 'value' },
+ },
+ { allowExistingPlatformAnnotationKeys: REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS }
+ )
+ ).rejects.toBeInstanceOf(DangerousAnnotationError)
+ })
+})
+
+describe('invalidSecretTypeReason — the shared rule', () => {
+ it('accepts every allowed type', () => {
+ for (const type of ALLOWED_SECRET_TYPES) {
+ expect(invalidSecretTypeReason(type)).toBeNull()
+ }
+ })
+
+ it('rejects every forbidden type with an actionable message', () => {
+ for (const type of FORBIDDEN_SECRET_TYPES) {
+ const reason = invalidSecretTypeReason(type)
+ expect(reason).not.toBeNull()
+ expect(reason).toContain('is not allowed')
+ }
+ })
+})
+
+describe('dangerousAnnotationKeyReason — the shared rule', () => {
+ it('accepts safe annotation keys', () => {
+ for (const key of SAFE_ANNOTATION_KEYS) {
+ expect(dangerousAnnotationKeyReason(key)).toBeNull()
+ }
+ })
+
+ it('rejects dangerous annotation keys with an actionable message', () => {
+ for (const key of DANGEROUS_ANNOTATION_KEYS) {
+ const reason = dangerousAnnotationKeyReason(key)
+ expect(reason).not.toBeNull()
+ expect(reason).toContain('is not allowed')
+ }
+ })
+
+ it('rejects platform annotation keys by default (no opts)', () => {
+ for (const key of PLATFORM_ANNOTATION_KEYS) {
+ const reason = dangerousAnnotationKeyReason(key)
+ expect(reason).not.toBeNull()
+ expect(reason).toContain('is not allowed')
+ }
+ })
+
+ it('accepts registry-owned annotation keys with the registryCredential capability', () => {
+ for (const key of PLATFORM_ANNOTATION_KEYS) {
+ expect(dangerousAnnotationKeyReason(key, { capability: 'registryCredential' })).toBeNull()
+ }
+ })
+
+ it('still rejects infra keys even with the registryCredential capability', () => {
+ for (const key of DANGEROUS_ANNOTATION_KEYS) {
+ const reason = dangerousAnnotationKeyReason(key, { capability: 'registryCredential' })
+ expect(reason).not.toBeNull()
+ expect(reason).toContain('is not allowed')
+ }
+ })
+})
+
+describe('extractHttpStatus — .status property', () => {
+ it('reads a top-level .status number', () => {
+ expect(extractHttpStatus({ status: 409 })).toBe(409)
+ })
+
+ it('prefers .statusCode over .status', () => {
+ expect(extractHttpStatus({ statusCode: 404, status: 500 })).toBe(404)
+ })
+
+ it('returns null for non-numeric .status', () => {
+ expect(extractHttpStatus({ status: 'Failure' })).toBeNull()
+ })
+})
+
describe('invalidSecretDataKeyReason — the shared rule', () => {
it('accepts every legitimate key', () => {
for (const key of VALID_KEYS) {