ration/.env.example
caelum0x 5bb6bc92f2 fix(card-issuance): persist card metadata — a restart silently lost every issued card forever
cardsvc.Service's own `cards map[string]*cardissuancepb.Card` was the
only place this repo stores Card metadata (ledger-core's proto has no
Card message), and it was pure in-memory state with zero durability.
A card-issuance restart lost every issued card's id/cardholder/limit/
status while the ledger HOLD backing its limit lived on in ledger-core
forever, unreachable by GetCard/AdjustCardLimit/CloseCard ever again
(all three look the card up by id first). card_issuance.proto's own
service comment also claimed this service was "stateless... safe to
run as N replicas" — false given this in-memory map; corrected.

Adds a file-backed store (services/card-issuance/internal/cardsvc/
store.go): atomic write-then-fsync-then-rename JSON file, loaded on
startup via a new EnablePersistence(path) method (opt-in, so existing
unit tests that never call it are unaffected) and written after every
IssueCard/AdjustCardLimit/CloseCard. New RATION_CARD_ISSUANCE_DATA_DIR
env var (default ./data, same convention as RATION_AUDIT_LOG_DATA_DIR),
wired in main.go.

Verified live against the real bare-metal stack: issued a card,
confirmed data/cards.json held it, killed and restarted card-issuance,
and confirmed `ration card get`/`ration status` still found the card
(pre-fix this would have been NotFound). go build/vet/test clean for
card-issuance (0 regressions), full `make build` clean.

Does not make this service safe to run as N replicas (each replica
would still load/save its own independent copy of the file) — that
needs a real shared store, the same class of gap already named and
left open for services/auth's apikey.Store; documented, not attempted,
in this round.
2026-10-29 13:53:46 +03:00

257 lines
12 KiB
Plaintext

# --- Airwallex (see docs/AIRWALLEX-SETUP.md) ---
# AIRWALLEX_MODE/CLIENT_ID/API_KEY/BASE_URL belong to services/card-issuance
# since the section-1 split (docs/SCALE-EXPANSION.md section 1,
# docs/adr/0004) — AIRWALLEX_WEBHOOK_SECRET belongs to
# services/webhook-ingestion instead. Neither the gateway BFF nor any
# other service reads these anymore.
AIRWALLEX_MODE=mock
AIRWALLEX_CLIENT_ID=
AIRWALLEX_API_KEY=
AIRWALLEX_BASE_URL=https://api-demo.airwallex.com
AIRWALLEX_WEBHOOK_SECRET=
# --- Agent LLM ---
ANTHROPIC_API_KEY=
RATION_AGENT_MODEL=claude-sonnet-5
# --- Agent LLM gateway routing (optional, see docs/AGENT-DESIGN.md) ---
# Leave RATION_LLM_GATEWAY_URL unset to call Anthropic directly (the
# original, tested path) — that is the default and requires no changes
# here. Set it to route every agent LLM call through Railyard's Relay
# gateway instead (sibling product, ~/products/railyard/apps/relay),
# which makes per-call metering/budget enforcement via Relay's Abacus
# integration possible. There is no confirmed-reachable production Relay
# URL for this deployment, so there is no non-empty default — set this to
# your own Relay deployment's base URL. For a local Relay quickstart
# (`docker compose -f docker-compose.quickstart.yml up --build` from
# ~/products/railyard/apps/relay), that is:
# RATION_LLM_GATEWAY_URL=http://localhost:3000/openai/v1
RATION_LLM_GATEWAY_URL=
# Relay/TensorZero model or function selector, e.g.
# "tensorzero::function_name::chat" — only meaningful against the
# operator's own deployed tensorzero.toml. Falls back to
# RATION_AGENT_MODEL if unset, which is a best-effort default, not a
# verified mapping. Required in practice for any real Relay deployment.
RATION_LLM_GATEWAY_MODEL=
# Sent as "Authorization: Bearer <value>" to Relay. Leave unset only
# against a Relay instance running with [gateway.auth] enabled = false
# (e.g. the quickstart config above) — any real deployment needs this.
RATION_LLM_GATEWAY_API_KEY=
# --- Agent LLM circuit breaker (see services/agent/internal/llm/breaker.go,
# docs/AGENT-DESIGN.md) ---
# Trips after this many consecutive provider failures/timeouts within
# the failure window below, short-circuiting every subsequent call
# with llm.ErrCircuitOpen (no provider call made at all) until the
# cooldown elapses — never blocking or delaying the already-safe
# deterministic hard-rule envelope internal/loop.Runner executes
# directly once tripped. All three are optional; unset/unparseable
# falls back to the documented default in breaker.go.
RATION_AGENT_LLM_BREAKER_FAILURE_THRESHOLD=3
RATION_AGENT_LLM_BREAKER_FAILURE_WINDOW_SECONDS=300
RATION_AGENT_LLM_BREAKER_COOLDOWN_SECONDS=60
# --- Services ---
LEDGER_CORE_ADDR=localhost:7001
LEDGER_CORE_METRICS_ADDR=localhost:9099
GATEWAY_GRPC_ADDR=localhost:7002
GATEWAY_METRICS_ADDR=localhost:9091
# internal/httpapi's REST/JSON facade over gateway.proto's Gateway
# service (docs/SCALE-EXPANSION.md section 7, docs/adr/0003).
# GATEWAY_GRPC_DIAL_ADDR is where that facade dials *this same*
# process's own gRPC listener above (GATEWAY_GRPC_ADDR) — see
# services/gateway/internal/config's doc comment for why that is a
# separate setting from the bind address.
GATEWAY_GRPC_DIAL_ADDR=localhost:7002
GATEWAY_HTTP_ADDR=localhost:8082
# --- Section-1 split services (see docs/SCALE-EXPANSION.md section 1,
# docs/adr/0004): auth, tenant-registry, card-issuance and
# webhook-ingestion are each their own deployable, dialed by the gateway
# BFF (AUTH_ADDR/CARD_ISSUANCE_ADDR/WEBHOOK_INGESTION_ADDR below).
# tenant-registry is still not yet wired into any caller — gateway.proto
# never exposed tenant CRUD, so that one remains new capability the
# split adds, not an extraction of an existing gateway RPC (see
# docs/adr/0004). auth *is* now wired into gateway, via
# internal/tenantauth — see RATION_GATEWAY_REQUIRE_TENANT_AUTH below
# and docs/THREAT-MODEL.md's "Known gaps" item 1. ---
AUTH_GRPC_ADDR=localhost:7010
AUTH_METRICS_ADDR=localhost:9098
# Required, no default (services/auth/internal/config) — never commit a
# real value here. Generate one with: openssl rand -base64 32
AUTH_JWT_SIGNING_KEY=
# Optional: persist auth's runtime-issuance CA (internal/servicecertca)
# across restarts instead of generating a fresh in-memory one each boot.
# Point both of these at infra/dev-ca/out/ca.{pem,key} (the exact same
# dev CA infra/dev-ca/generate-dev-ca.sh issued and every service's own
# *_MTLS_CA_FILE below already trusts) to enable scripts/rotate-dev-ca.sh:
# auth then signs rotated leaves against that identical trust root, so a
# rotated cert validates everywhere with no new CA to redistribute.
AUTH_CA_CERT_FILE=
AUTH_CA_KEY_FILE=
# What the gateway dials to verify a caller-presented API key/JWT
# before a tenant-scoped RPC (services/gateway/internal/tenantauth) —
# same value as AUTH_GRPC_ADDR above in a single-host/local setup.
AUTH_ADDR=localhost:7010
TENANT_REGISTRY_GRPC_ADDR=localhost:7011
TENANT_REGISTRY_METRICS_ADDR=localhost:9095
CARD_ISSUANCE_GRPC_ADDR=localhost:7012
CARD_ISSUANCE_METRICS_ADDR=localhost:9096
# What the gateway dials to reach card-issuance — same value as
# CARD_ISSUANCE_GRPC_ADDR above in a single-host/local setup; a real
# deployment's gateway task would point this at card-issuance's
# load-balanced service address instead.
CARD_ISSUANCE_ADDR=localhost:7012
# Where card-issuance persists its own card metadata (cardsvc.Service's
# file-backed store — see its EnablePersistence doc comment). Without
# this, a process restart used to lose every issued card while the
# ledger HOLD backing its limit lived on forever, unreachable. Same
# "RATION_<SERVICE>_DATA_DIR, default ./data" convention as
# RATION_AUDIT_LOG_DATA_DIR below.
RATION_CARD_ISSUANCE_DATA_DIR=./data
WEBHOOK_INGESTION_GRPC_ADDR=localhost:7013
WEBHOOK_INGESTION_HTTP_ADDR=localhost:8081
WEBHOOK_INGESTION_METRICS_ADDR=localhost:9097
# What the gateway dials to merge webhook-ingestion's normalized event
# stream into its own activity feed (internal/webhookeventsclient).
WEBHOOK_INGESTION_ADDR=localhost:7013
# --- audit-log (see proto/audit.proto, docs/THREAT-MODEL.md) ---
AUDIT_LOG_GRPC_ADDR=localhost:7003
RATION_AUDIT_LOG_DATA_DIR=./data
AUDIT_LOG_METRICS_ADDR=localhost:9092
# ledger-core mirrors ApplyEntry/RecordAgentDecision into audit-log on a
# best-effort basis when this is set; leave unset to disable mirroring
# entirely (e.g. running ledger-core alone without audit-log up).
AUDIT_LOG_ADDR=
# --- Policy defaults (see docs/AGENT-DESIGN.md) ---
# Read by services/card-issuance since the section-1 split (the gateway
# BFF no longer has bridge-funding policy of its own).
RATION_BRIDGE_MAX_FRACTION=0.6
RATION_BRIDGE_MIN_GRANT_MINOR_UNITS=500
RATION_BRIDGE_VELOCITY_WINDOW_HOURS=24
# --- Rate limiting (see services/gateway/internal/ratelimit) ---
RATION_RATELIMIT_RPS=20
RATION_RATELIMIT_BURST=40
RATION_RATELIMIT_SWEEP_INTERVAL_MINUTES=10
# --- Tenant-scoped authorization (see services/gateway/internal/tenantauth,
# docs/THREAT-MODEL.md's "Known gaps" item 1) ---
# On by default: services/cli, services/tui and services/agent each now
# mint an operator-scoped credential from auth at startup (see each
# service's internal/authclient and proto/auth.proto's is_operator
# field) and attach it to every gateway call, so a bare `make run-demo`
# is a credentialed demo, not an all-requests-rejected one. Gateway
# rejects any tenant-scoped RPC whose verified credential doesn't match
# the request's own tenant_id (an operator credential is exempt from
# that match — see internal/tenantauth's doc comment). Set to false only
# for a deployment that genuinely has no caller wired for this yet.
RATION_GATEWAY_REQUIRE_TENANT_AUTH=true
# RATION_LEDGER_REQUIRE_TENANT_AUTH (see services/ledger-core/src/
# tenantauth.rs) is ledger-core's OWN, independent enforcement of the
# identical check — docs/THREAT-MODEL.md item 1's own words call this
# "the biggest one" sub-gap: cli/tui/agent (and gateway's own
# forwarding, and card-issuance) dial ledger-core directly, bypassing
# RATION_GATEWAY_REQUIRE_TENANT_AUTH entirely. On by default; ledger-core
# dials AUTH_GRPC_ADDR (above) to verify every credential itself, and
# refuses to start if this is true but AUTH_GRPC_ADDR resolves to
# nothing reachable configured. Set to false only for a deployment that
# genuinely wants ledger-core runnable standalone with no Auth present.
RATION_LEDGER_REQUIRE_TENANT_AUTH=true
# RATION_TENANT_REGISTRY_REQUIRE_OPERATOR_AUTH (see
# services/tenant-registry/internal/operatorauth) is tenant-registry's
# OWN inbound check — a real gap neither RATION_GATEWAY_REQUIRE_TENANT_AUTH
# nor RATION_LEDGER_REQUIRE_TENANT_AUTH ever covered: CreateTenant/
# GetTenant/ListTenants are operator-only RPCs (no tenant_id to check a
# caller against), and tenant-registry's inbound gRPC server had no
# auth check at all until this existed — any caller reaching its port
# (published in docker-compose.yml) could onboard or list every tenant
# on the platform using tenant-registry's own pre-provisioned operator
# credential, regardless of who asked. On by default; `ration tenant
# create`/`ration tenant list` already mint and attach their own
# operator credential (services/cli/cmd/ration/tenant.go), so this is a
# credentialed demo by default too, not an all-requests-rejected one.
RATION_TENANT_REGISTRY_REQUIRE_OPERATOR_AUTH=true
# --- Encryption at rest (see services/ledger-core/src/wal_crypto.rs,
# docs/THREAT-MODEL.md's "Known gaps" #6) ---
# Disabled by default (ledger-core runs exactly as before this existed
# when unset). Set to a base64-encoded 32-byte key
# (openssl rand -base64 32) to encrypt every WAL frame with AES-256-GCM
# before it ever touches disk. This is a dev stand-in for a real
# KMS/Secrets Manager key (see infra/terraform/modules/service's
# existing Secrets Manager wiring for the pattern a real deployment
# would use instead of a plaintext env var) — and NOT a live migration
# path: setting this against an existing plaintext
# RATION_LEDGER_WAL_PATH, or changing it against an existing encrypted
# one, fails WAL recovery loudly (every frame fails to decrypt) rather
# than silently corrupting or losing data. Start from a fresh WAL/db
# path whenever first enabling this or rotating the key.
RATION_LEDGER_ENCRYPTION_KEY=
# --- mTLS between internal services (see pkg/mtls, infra/dev-ca/) ---
# Disabled by default. Run infra/dev-ca/generate-dev-ca.sh and source
# the dev-ca.env it writes to populate every *_MTLS_* var below at once,
# for every service it issues an identity for (ledger-core, gateway,
# audit-log, agent, cli, tui, auth, tenant-registry, card-issuance,
# webhook-ingestion).
GATEWAY_MTLS_ENABLED=false
GATEWAY_MTLS_CERT_FILE=
GATEWAY_MTLS_KEY_FILE=
GATEWAY_MTLS_CA_FILE=
LEDGER_CORE_MTLS_ENABLED=false
LEDGER_CORE_MTLS_CERT_FILE=
LEDGER_CORE_MTLS_KEY_FILE=
LEDGER_CORE_MTLS_CA_FILE=
AUDIT_LOG_MTLS_ENABLED=false
AUDIT_LOG_MTLS_CERT_FILE=
AUDIT_LOG_MTLS_KEY_FILE=
AUDIT_LOG_MTLS_CA_FILE=
AGENT_MTLS_ENABLED=false
AGENT_MTLS_CERT_FILE=
AGENT_MTLS_KEY_FILE=
AGENT_MTLS_CA_FILE=
CLI_MTLS_ENABLED=false
CLI_MTLS_CERT_FILE=
CLI_MTLS_KEY_FILE=
CLI_MTLS_CA_FILE=
AUTH_MTLS_ENABLED=false
AUTH_MTLS_CERT_FILE=
AUTH_MTLS_KEY_FILE=
AUTH_MTLS_CA_FILE=
TENANT_REGISTRY_MTLS_ENABLED=false
TENANT_REGISTRY_MTLS_CERT_FILE=
TENANT_REGISTRY_MTLS_KEY_FILE=
TENANT_REGISTRY_MTLS_CA_FILE=
CARD_ISSUANCE_MTLS_ENABLED=false
CARD_ISSUANCE_MTLS_CERT_FILE=
CARD_ISSUANCE_MTLS_KEY_FILE=
CARD_ISSUANCE_MTLS_CA_FILE=
WEBHOOK_INGESTION_MTLS_ENABLED=false
WEBHOOK_INGESTION_MTLS_CERT_FILE=
WEBHOOK_INGESTION_MTLS_KEY_FILE=
WEBHOOK_INGESTION_MTLS_CA_FILE=
TUI_MTLS_ENABLED=false
TUI_MTLS_CERT_FILE=
TUI_MTLS_KEY_FILE=
TUI_MTLS_CA_FILE=
# --- Observability (see docs/SCALE-EXPANSION.md section 2, pkg/telemetry,
# services/ledger-core/src/telemetry.rs, infra/otel-collector/) ---
# Every service's OTLP/gRPC trace exporter targets this collector
# endpoint; unset defaults to "localhost:4317" (Go) / "http://localhost:4317"
# (Rust) — infra/otel-collector's docker-compose port. A collector that
# isn't running never blocks service startup or the request path: span
# export calls just fail silently in the background (see pkg/telemetry's
# and telemetry.rs's doc comments).
OTEL_EXPORTER_OTLP_ENDPOINT=
RATION_OTEL_EXPORTER_ENDPOINT=