Skip to content

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

TypeScript
8.5 KB
Raw Blame
import { SecretUpsertRequest } from '../types.js'
import { REGISTRY_OPERATION_ID_ANNOTATION } from './registryMutation.js'

export const ALLOWED_SECRET_TYPES: readonly string[] = [
  'Opaque',
  'kubernetes.io/tls',
  'kubernetes.io/dockerconfigjson',
]

/**
 * Existing Secret types are normally safe to preserve. These are the narrow
 * exceptions whose lifecycle is owned by Kubernetes bootstrap controllers or
 * Helm, so control-api must not mutate their data or metadata. In particular,
 * basic-auth, ssh-auth, and custom types remain valid preserved state.
 */
const NON_MUTABLE_PRESERVED_SECRET_TYPES: readonly string[] = [
  'kubernetes.io/service-account-token',
  'bootstrap.kubernetes.io/token',
  'helm.sh/release.v1',
]

const INFRA_ANNOTATION_PREFIXES: readonly string[] = [
  'kubectl.kubernetes.io/',
  'kubernetes.io/',
  '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))
}

export function isPlatformAnnotationKey(key: string): boolean {
  return PLATFORM_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

/** Operation marker used only by the internal Registry mutation capability. */
export const REGISTRY_SECRET_OPERATION_ID_ANNOTATION = REGISTRY_OPERATION_ID_ANNOTATION

/** Platform keys a public Registry credential rotation may preserve, never assign. */
export const REGISTRY_SECRET_ROTATION_PRESERVED_ANNOTATION_KEYS = [
  ...REGISTRY_SECRET_PRESERVED_ANNOTATION_KEYS,
  REGISTRY_SECRET_OPERATION_ID_ANNOTATION,
] 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',
  REGISTRY_SECRET_OPERATION_ID_ANNOTATION,
] as const

export type SecretWriteCapability = 'registryCredential' | 'registryPullSecret'

/**
 * The EXACT platform annotation keys each capability grants, and nothing more.
 * Narrowness is the security property here: a capability exists so one internal
 * writer may set the specific keys it owns, never the `clerum.io/` prefix at
 * large. Exported so a test can pin the whole map — a per-key denylist can only
 * ever enumerate keys someone already thought of, and stays green when a new
 * one is added here.
 */
export 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 managedSecretTypeErrorMessage(type: string): string {
  return `Secret type "${type}" is managed by Kubernetes or Helm and cannot be mutated`
}

function annotationKeyErrorMessage(key: string, prefixes: readonly string[]): string {
  return `annotation key "${key}" is not allowed: keys starting with ${prefixes.map(p => `"${p}"`).join(' or ')} are reserved`
}

export class InvalidSecretTypeError extends Error {
  readonly status = 400
  readonly type: string
  constructor(type: string, message = secretTypeErrorMessage(type)) {
    super(message)
    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
}

export function assertValidSecretType(type: string): void {
  if (invalidSecretTypeReason(type) !== null) {
    throw new InvalidSecretTypeError(type)
  }
}

export function assertMutablePreservedSecretType(type: string | undefined): void {
  if (type !== undefined && NON_MUTABLE_PRESERVED_SECRET_TYPES.includes(type)) {
    throw new InvalidSecretTypeError(type, managedSecretTypeErrorMessage(type))
  }
}

export function assertValidSecretAnnotations(
  annotations: Record<string, string> | undefined,
  opts?: SecretConstraintOptions,
  existingAnnotations?: Record<string, string>
): void {
  if (!annotations) return
  for (const key of Object.keys(annotations)) {
    const isUnchangedInfrastructureMetadata =
      isInfrastructureAnnotationKey(key) && existingAnnotations?.[key] === annotations[key]
    const isUnchangedPlatformMetadata =
      isPlatformAnnotationKey(key) && existingAnnotations?.[key] === annotations[key]
    if (
      !isUnchangedInfrastructureMetadata &&
      !isUnchangedPlatformMetadata &&
      isBlockedAnnotationKey(key, opts)
    ) {
      throw new DangerousAnnotationError(key, reservedPrefixes())
    }
  }
}

export function assertValidSecretConstraints(
  req: SecretUpsertRequest,
  opts?: SecretConstraintOptions,
  existingAnnotations?: Record<string, string>
): void {
  // The allowlist applies only to an explicit caller assignment. A preserved
  // type is checked separately against the narrow controller-owned denylist.
  if (req.type !== undefined) {
    assertValidSecretType(req.type)
  }
  assertValidSecretAnnotations(req.annotations, opts, existingAnnotations)
}

/**
 * Resolve the annotation map a full replacement is allowed to leave behind.
 * Requested reserved keys must match the live value; omitted protected keys
 * are carried forward. Caller-owned keys retain full-replace semantics.
 */
export function resolveSecretAnnotationsForReplace(
  existingAnnotations: Record<string, string> | undefined,
  requestedAnnotations: Record<string, string> | undefined,
  opts?: SecretConstraintOptions
): Record<string, string> | undefined {
  if (requestedAnnotations === undefined) {
    return existingAnnotations
  }

  assertValidSecretAnnotations(requestedAnnotations, opts, existingAnnotations)

  const resolved: Record<string, string> = { ...requestedAnnotations }
  for (const [key, value] of Object.entries(existingAnnotations ?? {})) {
    if (isInfrastructureAnnotationKey(key)) {
      if (requestedAnnotations[key] === undefined) resolved[key] = value
      continue
    }

    if (isPlatformAnnotationKey(key) && requestedAnnotations[key] === undefined) {
      const allowPreserve = opts?.allowExistingPlatformAnnotationKeys?.includes(key)
      const capabilityOwnsKey = allowedPlatformAnnotationKeys(opts).has(key)
      // Unknown/future platform metadata is immutable to public writers and is
      // carried forward. A declared capability may explicitly remove only its
      // own keys; a preservation allowlist keeps the narrow partial-writer
      // contract for the public rotation path.
      if (allowPreserve || !capabilityOwnsKey) resolved[key] = value
    }
  }
  return resolved
}