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.jsonindex 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.jsonindex 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.tsindex 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: stringprivate readonly resources: ResourceService- private readonly secrets: SecretService+ private readonly secrets: SecretRepositoryprivate readonly hostOverviews: HostOverviewServiceprivate readonly hostEnvSvc: HostEnvServiceprivate 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?: numbercode?: number | string+ status?: numberhttpStatus?: numberresponse?: { 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.statusCodeif (maybe.response && typeof maybe.response.status === 'number') return maybe.response.status+ if (typeof maybe.status === 'number') return maybe.statusreturn null}diff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.tsindex 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/validateMcpServerSpecimport { 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.llmHooksNamespacelet 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 metadataconst 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 stringconst port = (meta?.port as number) ?? 3000let 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 = nulllet 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 constlet namespace: string | null = null+ let existingRecipe:+ | {+ metadata?: {+ labels?: Record<string, string>+ annotations?: Record<string, string>+ resourceVersion?: string+ }+ spec?: Record<string, unknown>+ }+ | undefinedfor (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 = candidatebreak} 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 registryconst 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: booleantry {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()).orgNameif (!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: booleantry {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.tsindex 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.tsindex 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 = nullres = 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.stringDataif (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.tsindex 58b48e477..3deb6f5c3 100644--- a/control-api/src/types.ts+++ b/control-api/src/types.ts@@ -16,6 +16,7 @@ export interface Metadata {namespace?: stringlabels?: 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.tsnew file mode 100644index 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.tsindex 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?: stringlabels?: 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: stringdata?: 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.nsconst 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: stringnamespace?: 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: stringnamespace?: 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.nsconst key = this.key(req.name, ns)diff --git a/control-api/test/registryClient.test.ts b/control-api/test/registryClient.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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) {