Skip to content

Secrets

Configure secrets, connections and connectionRules in sanoma.config.ts; workflow code names a connection and resource data files contain secret references. See the runtime’s configuration and connection examples for the exported types and ownership rules. The default is encrypted rows in the company’s Postgres. A configured SecretStore or runtime-bound store factory replaces that storage; the Supabase Vault adapter supports BYOC. The app’s connection forms verify and save accounts through this selected store. Going live uses explicitly declared default connections for vendors with named authentication.

For managed Cloud configuration, import { managedKmsStore } from "sanoma/secrets" supplies the KMS-backed Postgres store from a fixed company/key reference and broker { endpoint, credential }. The runtime uses its existing database pool and opens and closes the KMS client itself. Keep the credential reader in trusted deployment config; workflow code uses logical secret references. This helper does not provision infrastructure or establish deployed Cloud readiness.

SANOMA_SIGNING_KEY signs app sessions and authorization state. SANOMA_SECRETS_KEY protects the built-in encrypted rows. Both are independent random 32-byte values encoded as base64. Supply a key directly or use SANOMA_SIGNING_KEY_FILE / SANOMA_SECRETS_KEY_FILE for a mounted file, never both sources for one key. First local start generates missing keys in ignored .env, creating the file with owner-only permissions. Direct and mounted inputs are validated before startup; conflicting sources, unreadable files and malformed values fail without printing their contents. External-store configurations need the signing key and the provider’s bootstrap identity, but no Sanoma row-encryption key.

The template declares explicit { bootstrap: "SANOMA_SIGNING_KEY" } and { bootstrap: "SANOMA_SECRETS_KEY" } bindings so a host resource can deliver these values without putting them in code or the database. Keep matching encryption material with a separate recovery backup of database ciphertext and metadata. Preserve signing material across ordinary restarts; replacing it invalidates signed sessions, and on a host the staff sign-in’s token keys, which are encrypted with it: clear them as Agents signing in says. Encryption-key rotation requires re-encrypting retained rows, while vendor-token rotation replaces the value in the store. See bootstrap keys.

Never put a secret in a workflow’s input or an operation’s input or output. They are persisted verbatim: DBOS keeps every step’s input and output in Postgres, the ledger records each call’s input and output, an approval a policy asks for carries the held call’s input, and the app shows all of it to anyone who can reach it. A driver reads its credentials when it is called (from the environment or a secret store), and an operation that creates a secret (an API key, a password reset link) returns a reference to where it is stored, not the secret.

A secret a resource needs is named, never written. A data file gives secret("NAME") (from sanoma/resources; NAME upper case, as a variable’s; sanoma’s own, SANOMA_…, only in a host’s secrets) at a write-only field (or an entry of a write-only map), and secret("NAME", { generate: true }) for one apply makes when none is stored: database_password: secret("SUPABASE_DB_PASSWORD", { generate: true }). Declarations, checkpoints and the ledger hold its marker, { "$secret": "NAME", "generate": true }; the resource type refuses one at any other field, and its schema does not judge it. The driver resolves the markers just before the vendor call, await resolveSecrets(input, call.secrets): each is replaced by the stored value, a generate one with none stored first made (32 random bytes, base64url) and stored, and one with nothing stored fails the call for good, before the vendor call, with the vendorCode secret_not_set (the run’s ledger then says nothing changed at the vendor). call.secrets is { get(name), ensure(name, make), delete?(name) }, resolved through the configured store and explicit bindings (see Credentials); a fake’s and a sandbox run’s are in memory (memorySecrets(), which a driver’s tests use too).

These pages describe sanoma 0.11.24.