Surface.Secrets Schema

Status

This schema is active for file-provider and test-inline secret resolution. Kubernetes Secret configuration is retired from active Stella Ops deployment support.

Secret Document

{
  "type": "cas-access",
  "name": "primary",
  "tenant": "acme",
  "component": "scanner-worker",
  "createdAt": "2026-05-01T00:00:00Z",
  "values": {
    "accessKey": "example",
    "secretKey": "example"
  }
}

Binary values may be base64 encoded and must be marked in metadata before being handed to consumers.

Provider Config

{
  "provider": "file",
  "providers": {
    "file": {
      "root": "/etc/stellaops/secrets",
      "format": "json"
    }
  },
  "requiredSecrets": [
    {"tenant": "acme", "component": "scanner-worker", "secretType": "cas-access"},
    {"tenant": "acme", "component": "scanner-worker", "secretType": "registry", "name": "primary"}
  ]
}

Determinism And Validation

• Providers resolve requests in request order.
• When multiple secrets match tenant/component/type, choose lexicographically smallest name, then earliest createdAt.
• Validation codes: SURFACE_SECRET_PROVIDER_UNKNOWN, SURFACE_SECRET_MISSING, SURFACE_SECRET_STALE, SURFACE_SECRET_FORMAT_INVALID.
• File-provider validation rejects world-readable files.
• Inline payloads are rejected unless explicitly enabled for test/development.

Observability

ISurfaceSecretProvider metadata should include provider id, age in days, and whether the payload contains binary material. It must never expose values.