release: lib-commons v4 — multi-tenant platform, systemplane, outbox, and 20+ new packages

.env.reference

@@ -20,6 +20,7 @@
 #
 # Generated from source scan — 2026-03-23
 # Updated: 2026-03-24 — Added SECURITY_TIER override and fail-closed rate-limit notes
+# Updated: 2026-03-28 — Added systemplane catalog env vars (postgres, redis, rabbitmq, auth, telemetry, cors, server)
 # =============================================================================
 
 # -----------------------------------------------------------------------------
@@ -184,6 +185,26 @@ ENV=
 # Default: "" (stack traces included)
 GO_ENV=
 
+# -----------------------------------------------------------------------------
+# HTTP SERVER TLS — commons/systemplane/catalog (keys_shared.go: appServerKeys)
+# -----------------------------------------------------------------------------
+# These env vars are registered in the systemplane shared catalog under the
+# "server.tls" group (ApplyBootstrapOnly, non-mutable at runtime).
+# They are consumed during service startup to configure HTTPS.
+# Leave empty to disable TLS (plain HTTP mode).
+
+# Path to the PEM-encoded TLS certificate (or certificate chain) file.
+# Required when enabling HTTPS.  Must be a regular file readable by the process.
+# Type: string (file path)
+# Default: (none — TLS disabled when empty)
+SERVER_TLS_CERT_FILE=
+
+# Path to the PEM-encoded TLS private key file.
+# Required when enabling HTTPS.  Must be mode 0600 or stricter.
+# Type: string (file path)
+# Default: (none — TLS disabled when empty)
+SERVER_TLS_KEY_FILE=
+
 # -----------------------------------------------------------------------------
 # HTTP HANDLERS — commons/net/http (commons/net/http/handler.go)
 # -----------------------------------------------------------------------------
@@ -323,6 +344,331 @@ RATE_LIMIT_REDIS_TIMEOUT_MS=500
 # Operational note: if Redis is not configured and strict enforcement is active,
 # the constructor fail-closes and all requests return 503 until Redis is wired.
 
+# -----------------------------------------------------------------------------
+# SYSTEMPLANE SHARED CATALOG — commons/systemplane/catalog (keys_shared.go, keys_postgres.go, keys_redis.go)
+# -----------------------------------------------------------------------------
+# The systemplane catalog defines canonical environment variable mappings for all
+# service components.  Services that adopt the systemplane dynamic config plane
+# register these keys via KeyDef lists; they are applied either at bootstrap time
+# (ApplyBootstrapOnly) or live-read from the running config snapshot
+# (ApplyLiveRead / ApplyBundleRebuild).
+#
+# NOTE: Some vars below overlap with direct env-var reads elsewhere in the library
+# (e.g., OTEL_EXPORTER_OTLP_ENDPOINT, RATE_LIMIT_ENABLED).  The catalog
+# definitions represent the canonical, hot-reloadable control plane equivalent.
+# Deployers only need to set each var once — the systemplane bootstrap picks them
+# up from the same environment.
+
+## -- Application / HTTP Server --
+
+# HTTP server listen address (host:port format).
+# ApplyBehavior: BootstrapOnly (restart required to change)
+# Type: string
+# Default: (none — required for server startup)
+SERVER_ADDRESS=
+
+# Maximum HTTP request body size in bytes.
+# ApplyBehavior: BootstrapOnly
+# Type: int
+# Default: (none — framework default applies)
+HTTP_BODY_LIMIT_BYTES=
+
+## -- CORS (systemplane catalog, live-reloadable) --
+# These catalog keys provide hot-reloadable CORS policy distinct from the static
+# ACCESS_CONTROL_ALLOW_* env vars read by the HTTP middleware at construction time.
+
+# CORS allowed origins (comma-separated), sourced from systemplane catalog.
+# ApplyBehavior: LiveRead (no restart needed)
+# Type: string
+# Default: (none — falls back to ACCESS_CONTROL_ALLOW_ORIGIN)
+CORS_ALLOWED_ORIGINS=
+
+# CORS allowed methods (comma-separated), sourced from systemplane catalog.
+# ApplyBehavior: LiveRead
+# Type: string
+# Default: (none — falls back to ACCESS_CONTROL_ALLOW_METHODS)
+CORS_ALLOWED_METHODS=
+
+# CORS allowed headers (comma-separated), sourced from systemplane catalog.
+# ApplyBehavior: LiveRead
+# Type: string
+# Default: (none — falls back to ACCESS_CONTROL_ALLOW_HEADERS)
+CORS_ALLOWED_HEADERS=
+
+## -- Rate Limiting (systemplane catalog key) --
+
+# Rate limit window duration in seconds when read via systemplane dynamic config.
+# Distinct from RATE_LIMIT_WINDOW_SEC (read directly by the ratelimit middleware).
+# RATE_LIMIT_EXPIRY_SEC feeds the catalog-managed config snapshot; products that
+# adopt systemplane use this key for live-reloadable window adjustment.
+# ApplyBehavior: LiveRead
+# Type: int (seconds)
+# Default: (none — middleware falls back to RATE_LIMIT_WINDOW_SEC default of 60)
+RATE_LIMIT_EXPIRY_SEC=
+
+## -- Authentication --
+# Auth keys use MatchEnvVars (multiple valid variable names per key) because
+# products and plugins follow different naming conventions.
+
+# Enable authentication middleware.
+# ApplyBehavior: BootstrapOnly
+# Accepted variable names: AUTH_ENABLED, PLUGIN_AUTH_ENABLED
+# Type: bool
+# Default: (none — auth disabled when absent)
+AUTH_ENABLED=
+# PLUGIN_AUTH_ENABLED=   (alias — same effect)
+
+# Auth service network address (host:port or URL).
+# ApplyBehavior: BootstrapOnly
+# Accepted variable names: AUTH_ADDRESS, PLUGIN_AUTH_ADDRESS
+# Type: string
+# Default: (none — required when auth is enabled)
+AUTH_ADDRESS=
+# PLUGIN_AUTH_ADDRESS=   (alias — same effect)
+
+# OAuth2 / OIDC client ID for the auth service.
+# ApplyBehavior: BootstrapOnly
+# Accepted variable names: AUTH_CLIENT_ID, PLUGIN_AUTH_CLIENT_ID
+# Type: string
+# Default: (none — required when auth is enabled)
+AUTH_CLIENT_ID=
+# PLUGIN_AUTH_CLIENT_ID=   (alias — same effect)
+
+# OAuth2 / OIDC client secret for the auth service.
+# Secret: true — stored encrypted at rest in systemplane; never logged.
+# ApplyBehavior: BootstrapOnly
+# Accepted variable names: AUTH_CLIENT_SECRET, PLUGIN_AUTH_CLIENT_SECRET
+# Type: string
+# Default: (none — required when auth is enabled)
+AUTH_CLIENT_SECRET=
+# PLUGIN_AUTH_CLIENT_SECRET=   (alias — same effect)
+
+# Auth token/response cache TTL in seconds.
+# ApplyBehavior: BootstrapOnly
+# Accepted variable names: AUTH_CACHE_TTL_SEC
+# Type: int (seconds)
+# Default: (none — no caching when absent)
+AUTH_CACHE_TTL_SEC=
+
+## -- Telemetry (systemplane catalog, bootstrap-only) --
+
+# Enable OpenTelemetry instrumentation.
+# ApplyBehavior: BootstrapOnly
+# Type: bool
+# Default: (none — telemetry disabled when absent)
+ENABLE_TELEMETRY=
+
+# OTEL resource service name (overrides OTEL_SERVICE_NAME SDK default).
+# ApplyBehavior: BootstrapOnly
+# Type: string
+# Default: (none — OTEL SDK default applies)
+OTEL_RESOURCE_SERVICE_NAME=
+
+# OTEL instrumentation library name passed to Tracer/Meter constructors.
+# ApplyBehavior: BootstrapOnly
+# Type: string
+# Default: (none)
+OTEL_LIBRARY_NAME=
+
+# OTEL resource service version (reported in spans and metrics).
+# ApplyBehavior: BootstrapOnly
+# Type: string
+# Default: (none)
+OTEL_RESOURCE_SERVICE_VERSION=
+
+# OTEL deployment environment label (e.g., production, staging).
+# ApplyBehavior: BootstrapOnly
+# Type: string
+# Default: (none)
+OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=
+
+## -- RabbitMQ (systemplane catalog) --
+
+# Enable RabbitMQ integration.  When false, the messaging bundle is not started.
+# ApplyBehavior: BundleRebuildAndReconcile (live toggle)
+# Type: bool
+# Default: (none — disabled when absent)
+RABBITMQ_ENABLED=
+
+# RabbitMQ AMQP connection URL.
+# Secret: true — stored encrypted; never logged.
+# ApplyBehavior: BundleRebuild (triggers connection teardown/reconnect)
+# Type: string (amqp:// or amqps://)
+# Default: (none — required when RabbitMQ is enabled)
+RABBITMQ_URL=
+
+# RabbitMQ exchange name used for publishing events.
+# ApplyBehavior: BundleRebuild
+# Type: string
+# Default: (none — required when RabbitMQ is enabled)
+RABBITMQ_EXCHANGE=
+
+# Prefix prepended to all routing keys (e.g., "org.ledger.").
+# ApplyBehavior: LiveRead
+# Type: string
+# Default: (none)
+RABBITMQ_ROUTING_KEY_PREFIX=
+
+# Per-publish timeout in milliseconds.
+# ApplyBehavior: LiveRead
+# Type: int (milliseconds)
+# Default: (none — framework default applies)
+RABBITMQ_PUBLISH_TIMEOUT_MS=
+
+# Maximum number of publish retries before giving up.
+# ApplyBehavior: LiveRead
+# Type: int
+# Default: (none)
+RABBITMQ_MAX_RETRIES=
+
+# Backoff delay in milliseconds between publish retry attempts.
+# ApplyBehavior: LiveRead
+# Type: int (milliseconds)
+# Default: (none)
+RABBITMQ_RETRY_BACKOFF_MS=
+
+# HMAC secret used to sign outgoing RabbitMQ events.
+# Secret: true — stored encrypted; never logged.
+# ApplyBehavior: LiveRead
+# Type: string
+# Default: (none — event signing disabled when absent)
+RABBITMQ_EVENT_SIGNING_SECRET=
+
+## -- PostgreSQL (systemplane catalog, service-level connection config) --
+# These are the service's own PostgreSQL connection parameters as registered in
+# the systemplane catalog.  Distinct from SYSTEMPLANE_POSTGRES_* which configure
+# systemplane's own metadata storage.
+
+# Primary host
+POSTGRES_HOST=
+
+# Primary port
+# Type: int
+# Default: 5432
+POSTGRES_PORT=5432
+
+# Primary database user
+POSTGRES_USER=
+
+# Primary database password
+# Secret: true
+POSTGRES_PASSWORD=
+
+# Primary database name
+POSTGRES_DB=
+
+# Primary SSL mode (disable, require, verify-ca, verify-full)
+# NOTE: In strict security tier, only require/verify-ca/verify-full are accepted.
+# Type: string
+# Default: (none — driver default is "disable")
+POSTGRES_SSLMODE=
+
+# Replica host (optional — omit to disable read replicas)
+POSTGRES_REPLICA_HOST=
+
+# Replica port
+# Type: int
+POSTGRES_REPLICA_PORT=
+
+# Replica user
+POSTGRES_REPLICA_USER=
+
+# Replica password (Secret: true)
+POSTGRES_REPLICA_PASSWORD=
+
+# Replica database name
+POSTGRES_REPLICA_DB=
+
+# Replica SSL mode
+POSTGRES_REPLICA_SSLMODE=
+
+# Maximum open connections in the pool (LiveRead — applied without restart)
+# Type: int
+# Default: (none — sql.DB default of 0, meaning unlimited)
+POSTGRES_MAX_OPEN_CONNS=
+
+# Maximum idle connections in the pool (LiveRead)
+# Type: int
+# Default: (none — sql.DB default of 2)
+POSTGRES_MAX_IDLE_CONNS=
+
+# Maximum connection lifetime in minutes (LiveRead)
+# Type: int (minutes)
+# Default: (none — no maximum lifetime)
+POSTGRES_CONN_MAX_LIFETIME_MINS=
+
+# Maximum idle time before a connection is closed, in minutes (LiveRead)
+# Type: int (minutes)
+# Default: (none — no maximum idle time)
+POSTGRES_CONN_MAX_IDLE_TIME_MINS=
+
+# Connection timeout in seconds (BundleRebuild)
+# Type: int (seconds)
+# Default: (none — driver default)
+POSTGRES_CONNECT_TIMEOUT_SEC=
+
+# Path to the directory containing SQL migration files.
+# ApplyBehavior: BootstrapOnly
+# Type: string (directory path)
+# Default: (none — migrations disabled when absent)
+MIGRATIONS_PATH=
+
+## -- Redis (systemplane catalog, service-level connection config) --
+
+# Redis server host (or comma-separated sentinel/cluster addresses)
+REDIS_HOST=
+
+# Redis Sentinel master name (required for Sentinel topology)
+REDIS_MASTER_NAME=
+
+# Redis authentication password (Secret: true)
+REDIS_PASSWORD=
+
+# Redis database index (0-based)
+# Type: int
+# Default: 0
+REDIS_DB=0
+
+# Redis protocol version (2 or 3)
+# Type: int
+# Default: (none — client default)
+REDIS_PROTOCOL=
+
+# Enable TLS for Redis connection
+# Type: bool
+# Default: false
+REDIS_TLS=false
+
+# PEM-encoded CA certificate for Redis TLS verification (Secret: true)
+# Type: string
+# Default: (none — system CA bundle used when TLS is enabled)
+REDIS_CA_CERT=
+
+# Redis connection pool size
+# Type: int
+# Default: (none — client default based on CPU count)
+REDIS_POOL_SIZE=
+
+# Minimum idle connections kept open in the pool
+# Type: int
+# Default: (none)
+REDIS_MIN_IDLE_CONNS=
+
+# Read timeout in milliseconds
+# Type: int (milliseconds)
+# Default: (none — client default)
+REDIS_READ_TIMEOUT_MS=
+
+# Write timeout in milliseconds
+# Type: int (milliseconds)
+# Default: (none — client default)
+REDIS_WRITE_TIMEOUT_MS=
+
+# Dial (connect) timeout in milliseconds
+# Type: int (milliseconds)
+# Default: (none — client default)
+REDIS_DIAL_TIMEOUT_MS=
+
 # -----------------------------------------------------------------------------
 # SYSTEMPLANE — commons/systemplane/bootstrap (commons/systemplane/bootstrap/env.go)
 # -----------------------------------------------------------------------------
@@ -403,6 +749,17 @@ SYSTEMPLANE_MONGODB_WATCH_MODE=change_stream
 # Default: 5
 SYSTEMPLANE_MONGODB_POLL_INTERVAL_SEC=5
 
+## -- Secret Encryption --
+
+# AES-256 master key for encrypting/decrypting secret configuration values at
+# rest.  Required when any KeyDef has Secret=true.  Must be exactly 32 raw
+# bytes or a base64-encoded 32-byte value.
+# When unset and secret keys are declared, the secret store is silently
+# skipped — downstream encrypt/decrypt calls will fail with a clear error.
+# Type: string (raw 32 bytes or base64-encoded 32 bytes)
+# Default: (none — required when secret keys are declared)
+SYSTEMPLANE_SECRET_MASTER_KEY=
+
 # -----------------------------------------------------------------------------
 # TENANT-MANAGER CONSUMER — commons/tenant-manager/consumer
 # -----------------------------------------------------------------------------