Saltar a contenido

Brun-E Global Config Design (SUPER_ADMIN)

Date: 2026-03-20
Status: Approved
Scope: Brun-E + shared security/operation env variables with global behavior control

1) Goal

Move selected Brun-E runtime configuration from ENV to a global admin configuration owned by SUPER_ADMIN, without exposing secrets and without breaking active sessions.

Hard decisions already approved:

  • Configuration is global for all tenants (not per company).
  • Changes apply to new sessions only.
  • Strategy is DB-only strict (Approach 1):
  • Editable keys are resolved from DB only.
  • No ENV fallback for editable keys at runtime.
  • Secrets remain in ENV/Secret Manager only.

2) Alternatives considered

A) DB-only strict (selected)

  • Runtime resolver: DB only for editable keys.
  • Only allowlisted keys are editable.
  • No secret moves to DB.

Pros:

  • Single source of truth from day 1.
  • No ENV/DB drift for business config.
  • Lower operational ambiguity.

Cons:

  • Requires complete seed before enabling runtime.
  • Missing required key can block start flow (fail-fast by design).

B) Conservative fallback (DB -> ENV) (rejected)

  • Keep dual source until stabilization.

Pros:

  • Lower migration friction.

Cons:

  • Ambiguous source of truth during rollout.
  • Drift risk between ENV and DB.

C) Versioned release model (phase 2 candidate)

  • Explicit config versions + scheduled activation.

Pros:

  • Strong governance and traceability.

Cons:

  • More initial complexity.

3) Security boundary (non-negotiable)

3.1 Never editable in admin panel

Keep only in ENV/Secret Manager:

  • OPENAI_API_KEY
  • JWT_SECRET
  • INTERNAL_API_KEY
  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • POSTGRES_HOST
  • POSTGRES_PORT
  • POSTGRES_DB
  • DISCORD_WEBHOOK_URL
  • NODE_ENV
  • PORT
  • E_TALENT_BASE_URL (integration endpoint; infra-controlled)
  • BRUNE_OPENAI_BASE_URL (prevent request routing abuse/SSRF)

3.2 Editable by SUPER_ADMIN (global)

Approved v1 editable set:

  • BRUNE_COOLDOWN_MINUTES
  • BRUNE_MAX_SESSIONS_PER_DAY
  • BRUNE_ELIGIBILITY_REQUIRE_PLAN
  • BRUNE_ELIGIBILITY_ALLOWED_LEVELS
  • BRUNE_PROMPT_ID
  • BRUNE_PROMPT_VERSION
  • BRUNE_OPENAI_REALTIME_MODEL
  • BRUNE_OPENAI_REALTIME_MODEL_ALLOWLIST
  • BRUNE_SESSION_MAX_MINUTES

3.3 Keep in ENV (global technical controls)

  • BRUNE_OUTBOX_WORKER_ENABLED
  • BRUNE_OUTBOX_WORKER_INTERVAL_MS
  • BRUNE_OUTBOX_WORKER_BATCH_SIZE
  • BRUNE_OUTBOX_WORKER_LEASE_MS
  • BRUNE_OUTBOX_MAX_RETRIES
  • BRUNE_OUTBOX_RETRY_BASE_MS
  • BRUNE_EXPIRY_WORKER_ENABLED
  • BRUNE_EXPIRY_WORKER_INTERVAL_MS
  • BRUNE_EXPIRY_WORKER_BATCH_SIZE
  • BRUNE_START_RATE_LIMIT_PER_MINUTE
  • LOG_LEVEL
  • LOG_DISCORD_LEVELS

These remain Terraform/infra-managed and are not part of editable DB settings.

4) Data model

Use 3 tables for controlled global configuration.

4.1 app_global_settings

  • key (PK/unique)
  • value_json (jsonb)
  • value_type (string|number|boolean|string_array)
  • updated_by (user id)
  • updated_at (timestamp)
  • version (int, optimistic lock)

4.2 app_global_setting_schema

  • key (PK)
  • category (brune_business|brune_prompt|brune_runtime)
  • editable (boolean)
  • constraints_json (min/max/enum/regex/maxItems)
  • default_source (seed|hardcoded)

4.3 app_global_setting_audit

  • id (uuid PK)
  • key
  • old_value_json
  • new_value_json
  • changed_by
  • reason
  • request_id
  • changed_at

5) Runtime resolution and session behavior

5.1 Resolution order

For editable keys:

  1. Read from DB (app_global_settings)
  2. If missing, fail-fast (runtime/config error)
  3. Validate parsed value against schema
  4. On invalid value, reject write path; never use invalid config at runtime

5.2 Apply to new sessions only

  • On POST /brun-e/start, resolve effective config snapshot once.
  • Calculate expires_at with BRUNE_SESSION_MAX_MINUTES.
  • Persist prompt/model/session-time values in created session metadata.
  • Active sessions do not mutate after config changes.

5.3 Model allowlist behavior

  • BRUNE_OPENAI_REALTIME_MODEL_ALLOWLIST is editable by SUPER_ADMIN.
  • BRUNE_OPENAI_REALTIME_MODEL must exist in allowlist.
  • If invalid, API rejects update with 400 and clear validation error.

6) Admin API contract (global)

6.1 Read

  • GET /admin/global-settings
  • Returns allowlisted keys only.
  • Includes source (db) and version.

6.2 Update

  • PATCH /admin/global-settings
  • Batch update of editable keys.
  • Requires reason.
  • Transactional write + audit rows.
  • Uses optimistic lock (version) to avoid lost updates.

6.3 History and rollback

  • GET /admin/global-settings/history?key=...
  • POST /admin/global-settings/rollback
  • Restores previous value/version.
  • Writes audit row with rollback reason.

7) Validation rules (initial)

  • BRUNE_COOLDOWN_MINUTES: integer, 0..240
  • BRUNE_MAX_SESSIONS_PER_DAY: integer, 1..20
  • BRUNE_ELIGIBILITY_REQUIRE_PLAN: boolean
  • BRUNE_ELIGIBILITY_ALLOWED_LEVELS: string array, max 20 values
  • BRUNE_PROMPT_ID: string, regex ^pmpt_[A-Za-z0-9_-]+$, max 128
  • BRUNE_PROMPT_VERSION: string, max 32
  • BRUNE_OPENAI_REALTIME_MODEL_ALLOWLIST: string array, min 1, max 30
  • BRUNE_OPENAI_REALTIME_MODEL: string, must be in allowlist
  • BRUNE_SESSION_MAX_MINUTES: integer, 1..120

8) Execution plan (phased)

Phase 0 - Foundation

  1. Create DB tables (settings, schema, audit).
  2. Seed schema for v1 editable keys.
  3. Seed initial values for all required editable keys.
  4. Add migration with strict startup preconditions (no fallback assumptions).

Phase 1 - Runtime read path (DB-only)

  1. Implement GlobalSettingsService (getString/getNumber/getBool/getArray) with required-key guarantees.
  2. Integrate resolver in:
  3. eligibility validator
  4. start session expiration logic
  5. openai realtime adapter (prompt/model)
  6. Remove ENV fallback from editable-key runtime path.

Phase 2 - Admin control plane

  1. Add secure admin endpoints.
  2. Add strict validation and optimistic locking.
  3. Add audit and history retrieval.
  4. Add rollback endpoint.

Phase 3 - Hardening and rollout

  1. Add alerts for config change events.
  2. Add smoke tests + regression tests.
  3. Release behind feature flag if needed.

9) Testing plan

Unit

  • Resolver strict behavior (DB-only)
  • Missing-key fail-fast behavior
  • Type/range validation per key
  • Model allowlist enforcement
  • New-session-only behavior for session max time

Integration

  • Admin endpoints auth/role guard (SUPER_ADMIN only)
  • Update + audit row creation in one transaction
  • Optimistic lock conflict flow
  • Rollback flow

Security

  • Non-editable keys cannot be updated
  • Secret keys never returned in read endpoint
  • Logs redact sensitive values in payloads

10) Risks and mitigations

  • Risk: invalid runtime config causes start-session failures
    Mitigation: reject invalid writes; fail-fast with clear error and required seed checklist.
  • Risk: accidental high-impact change by admin
    Mitigation: reason required, audit trail, rollback endpoint.
  • Risk: incomplete bootstrap seed for required keys
    Mitigation: migration seed + startup guard + CI smoke test for required editable keys.

11) Done criteria

  • Editable key set works end-to-end via admin API.
  • New sessions consume updated config without restart.
  • Active sessions remain stable.
  • Secret boundary is preserved.
  • Audit and rollback are operational.