Environment And Secrets

Copy Markdown View Source

The SDK treats environment access and credential handling as runtime boundaries. Application modules under lib/ do not read or mutate the OS environment directly. config/runtime.exs takes a named allowlist into application config, and the SDK's internal environment wrapper reads that materialized map. Callers can supply explicit env or process_env maps when a bounded operation needs additional values.

Execution boundaries

  • Governed execution requires an explicit authority reference and a materialized child environment. Ambient shell state does not satisfy that authority.
  • Subprocess launchers preserve their clear-environment behavior. They receive only the SDK's allowlisted runtime map plus explicit per-call overrides.
  • A new ambient variable must be added deliberately to the runtime allowlist. Arbitrary deployment credentials should instead be passed through the top-level application's configuration or an explicit call option.
  • Live Codex commands use ~/scripts/with_bash_secrets and must never print a key or token.

Secret-bearing structs

Any struct that can hold a key, token, OAuth verifier or authorization header uses @derive {Inspect, except: [...]} (or a custom Inspect implementation). This protects common implicit inspection paths such as OTP crash reports, logger metadata and error tuples. Redaction changes only inspection; the fields remain available to the runtime code that owns the credential.

Log credential names or the keys of a validated env map, never credential values or an entire unreviewed map. Persisted auth files are written atomically with restrictive permissions. Tests use synthetic marker values and keep live authentication paths behind live-only tags.

Repository policy

Real .env files and files ending in .env are ignored. A checked-in template must end in .env.example. The package must not contain developer auth files, captured keys or token-bearing logs.

Two executable guards backstop review:

  • scripts/atom_guard.sh rejects dynamic atom creation from wire data.
  • scripts/secrets_guard.sh rejects whole-environment runtime snapshots and secret-named struct fields without Inspect redaction. A reviewed false positive may use # secret-safe: on the matching line or immediately above it.

Both guards run in mix ci; the full release gate also runs them directly.