cellos-broker-file 0.5.1

Filesystem SecretBroker for CellOS — resolves spec secretRefs from on-disk files (Kubernetes-mounted secrets, systemd credentials).
Documentation

cellos-broker-file

SecretBroker that reads secret values from filesystem paths — the Kubernetes / Docker secrets / systemd-credentials / Vault Agent path.

What it is

Implements cellos_core::ports::SecretBroker. For each secretRef, the broker looks up an env var of the form CELLOS_SECRET_FILE_<UPPER_KEY> to find the file path, reads the file at resolve time, strips a trailing newline, and returns the bytes as a SecretView (ZeroizeOnDrop).

Selected in cellos-supervisor::composition::build_secret_broker when CELLOS_BROKER=file. Production-friendly for runtimes that deliver secrets as files on tmpfs:

  • Kubernetes mounted Secrets (/run/secrets/<name>)
  • Docker secrets (/run/secrets/<name>)
  • systemd credentials (/run/credentials/<unit>/<name>)
  • HashiCorp Vault Agent rendered templates
  • CI systems that materialise secrets to tmpfs before the job runs

What it does NOT do:

  • It does not cache — each resolve is a fresh open() + read().
  • It does not implement revoke_for_cell; isolation is the cell model's teardown, plus the file's own lifecycle on the host (tmpfs unmount, short-TTL renders).
  • It does not follow symlinks on the final path component (O_NOFOLLOW on Unix). An attacker swapping the configured file for a symlink to /etc/shadow gets an open() error, not exfiltration. Windows lacks an O_NOFOLLOW analogue in std, so the fallback is plain tokio::fs::read_to_string.

Public API surface

Symbol Purpose
FileSecretBroker The broker. new() / default().
FileSecretBroker::path_env_var(key) Pure helper: "db-password" → "CELLOS_SECRET_FILE_DB_PASSWORD".

Source: src/lib.rs.

Configuration

For each secret key referenced by the cell spec, point the env var at the on-disk path:

CELLOS_SECRET_FILE_<UPPER_KEY>=<absolute-path>

Selection:

CELLOS_BROKER=file

Trailing newlines in the file are stripped. The path is operator- controlled via env — the broker reads only what is configured. Nothing is cached between calls.

Examples

authority:
  secretRefs:
    - DB_PASSWORD
    - API_TOKEN

export CELLOS_BROKER=file
export CELLOS_SECRET_FILE_DB_PASSWORD=/run/secrets/db-password
export CELLOS_SECRET_FILE_API_TOKEN=/run/credentials/myapp.service/api-token
cellos-supervisor --spec cell.yaml

Testing

cargo test -p cellos-broker-file

Related crates

  • cellos-broker-env — simpler dev/CI default.
  • cellos-broker-oidc — GitHub Actions OIDC token exchange.
  • cellos-broker-vault — HashiCorp Vault AppRole.
  • cellos-supervisor — selects this broker via CELLOS_BROKER.
  • cellos-core — defines the SecretBroker port and SecretView.

ADRs

  • ADR-0007 — RBAC and secretRef admission contract.
  • SEC-15b — O_NOFOLLOW-on-final-component pattern mirrored from cellos-core::trust_keys::load_trust_verify_keys_file.