Translation assistance worker and vault

Translation assistance uses the existing PostgreSQL/outbox/pg-boss infrastructure with a separate process and queue. Provider calls do not run in API requests or the transfer/release workers. Read provider setup before granting shared spending authority.

Local setup

Use the repository’s pinned Node/pnpm versions and an existing local database. The commands below create only local private vault configuration; they do not configure production or call a translation provider.

pnpm transfers:prepare
pnpm db:migrate
pnpm db:queue
pnpm assistance:vault prepare
LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose -f compose.yaml -f compose.assistance.yaml up -d openbao
pnpm assistance:vault init
pnpm assistance:vault status

The persistent vault uses verified TLS on loopback port 8210. Its pinned image is OpenBao 2.7.1. Local provisioning creates a private CA, separate API/worker/operator AppRoles and revokes the bootstrap root token. The local operator/unseal.json contains recovery shares; never mount that directory into an application or commit it. A production deployment must distribute recovery shares to separate custodians instead of using this local convenience.

Set ASSISTANCE_VAULT_CONFIG_FILE for the API to the generated .local/assistance/api/host.json. Start the assistance worker with the generated worker host.json instead. Use pnpm dev:assistance or the built pnpm start:assistance. Set ASSISTANCE_HEALTH_PORT explicitly if port 4013 is occupied by another local worker. The process needs the application and restricted queue database URLs.

For containers, use the assistance-worker target in the API Dockerfile and the service in compose.assistance.yaml together with the base Compose file. The API mounts only its API AppRole directory; the worker mounts only its worker directory. Use the generated container.json paths. Preserve your monitoring overrides when composing services. pnpm observability:setup also generates the optional .local/observability/assistance.compose.json override; include it only together with compose.assistance.yaml to enable the worker’s authenticated metrics and verified telemetry.

Permission boundaries

The API AppRole can encrypt provider credentials but cannot decrypt them. The worker AppRole can decrypt but cannot rotate or export Transit keys. Operator rotation/rewrap permissions are separate. Authentication uses short-lived AppRole tokens; no application receives a root token or recovery share.

The Transit key is nonexportable and uses a derived context containing workspace, connection and credential version. PostgreSQL contains only ciphertext. Keep TLS verification enabled. Do not expose OpenBao or its internal control endpoints publicly.

pnpm assistance:vault seal blocks future provider calls. Existing editing and delivery remain usable. After an intentional restart, pnpm assistance:vault unseal restores local access using local recovery material. Production unseal follows your custodian procedure.

Rotation and recovery

pnpm assistance:vault rotate-key advances the Transit encryption key while preserving older ciphertext decryption. Rewrap stored ciphertext with the same context using a separately authorized operator; application roles cannot rewrap. Never retire an old Transit key version until every database backup that depends on it has expired or been rewrapped under a tested recovery plan.

pnpm assistance:vault rotate-identities replaces AppRole SecretIDs and revokes the previous SecretID accessors. Existing short-lived tokens last until their expiry; restart clients to discard cached sessions. Rotate before the 30-day SecretID expiry. Provider-key replacement is a separate panel operation and requires review of queued work.

Back up the product database, OpenBao Raft snapshot, TLS trust/configuration and recovery shares together, storing shares separately from the snapshot. A database backup without its Transit key material cannot recover provider credentials. Restore into an isolated network, wait for the restored vault to seal, restart it to reload the restored seal configuration, and unseal with the original recovery shares. Verify encryption context and role restrictions, then test with a non-customer secret. Do not downgrade by deleting new tables or discard prior recovery material during rotation.

Health and incidents

Worker liveness means the process is running; readiness checks queue access. Vault readiness is deliberately separate from product readiness. A sealed/unreachable vault produces a safe dependency error and stops new calls. Provider keys, prompt bodies and translations must not enter telemetry.

Monitor heartbeat, queue/outbox age, provider latency/outcomes, local limit rejections and unknown paid outcomes. Do not automatically retry an unknown paid attempt from an operational script. The authorized user must review and approve another call.

Apply migrations separately from startup. Stop old writer/cleanup processes before schema transitions, verify counts/content, and retain backups for rollback. CI and production rollout remain separate operations.

Coordinated recovery

Follow the backup and recovery guide to capture the database, credential vault and durable release state together. Restore into quarantine, preserve post-backup revocations and require explicit reconciliation before reopening writes.