Secrets

Top-level secrets block defines app-wide generated values shared across components via $secrets.<name>.

Field	Type	Required	Description
`generator`	`enum`	yes	Generation strategy (see below)
`description`	`string`	no	Human description

Generator strategies:

Generator	Produces	Example
`secret`	Cryptographically random hex string (suitable for signing keys, tokens). Use `\|base64` pipe for base64 encoding.	`a3f8b2c1d9e7...`
`uuid`	UUID v4	`550e8400-e29b-41d4-a716-446655440000`
`port`	Allocates an available port on the host	`8432`

secrets:
  secret-key-base:
    generator: secret
  jwt-secret:
    generator: uuid
    description: "JWT signing key"

components:
  api:
    env:
      SECRET_KEY_BASE: "$secrets.secret-key-base"
  worker:
    env:
      SECRET_KEY_BASE: "$secrets.secret-key-base"

Both components receive the same generated value.

Pipe transforms

Any resolved value can be piped through encoding transforms using the | operator, following the same convention as Unix pipes, Jinja2 filters, and Helm template pipelines:

Expression	Output	Notes
`$secrets.key`	`a3f8b2c1d9e7...`	Default (hex)
`$secrets.key\|hex`	`a3f8b2c1d9e7...`	Explicit hex, same as default
`$secrets.key\|base64`	`o/iywd6X...`	Base64-encoded (standard, with padding)
`$host\|base64`	`ZGIuZXhhbXBsZS5jb20=`	Works on any reference, not just secrets

Transforms compose with string interpolation for literal prefixes:

secrets:
  app-key:
    generator: secret

env:
  # Raw hex (default)
  SESSION_SECRET: "$secrets.app-key"
  # Base64 with Laravel's required prefix
  APP_KEY: "base64:${secrets.app-key|base64}"

The | is unambiguous — dots navigate paths, pipes apply transforms. This distinction matters for future extensibility (e.g., key pair properties like $secrets.key.private are navigation, not transforms).

Currently defined transforms: base64, hex. The pipeline is extensible — future spec versions may add transforms like urlsafe or sha256.

base64 encoding behavior: When the input is a hex string (even-length, all hex characters — as produced by generator: secret), |base64 decodes the hex to raw bytes first, then base64-encodes the bytes. For non-hex inputs, |base64 encodes the raw string directly. This means $secrets.key|base64 produces compact base64 from the secret's underlying bytes, not a base64 encoding of the hex text.