hub/tasks/architecture/storage/config-hub-startup-system.md at main

alkdev/hub

Files

glm-5.1 2b63cda1c7 Setup repo: migrate architecture specs, code stubs, and tasks from alkhub_ts

Copy architecture docs, ADRs, storage domain specs, research, reviews,
and 56 storage architecture tasks from the alkhub_ts monorepo. Adapt for
standalone @alkdev/hub repo structure (src/ not packages/hub/).

Sanitize all sensitive information:
- Replace private IPs (10.0.0.1) with localhost defaults
- Remove internal server hostnames (dev1, ns528096)
- Replace /workspace/ private paths with npm package references
- Remove hardcoded credentials from examples
- Rewrite infrastructure.md without private network details

Add Deno project scaffolding: deno.json (pinned deps), .gitignore,
AGENTS.md, entry point. Migrate existing code stubs (crypto, config
types, logger) with updated import paths.

2026-05-25 10:56:32 +00:00

3.8 KiB

Raw Permalink Blame History

id, name, status, depends_on, scope, risk, impact, level

name

status

depends_on

scope

risk

impact

level

config-hub-startup-system

Specify Hub Config System and Startup Sequence

completed

broad

high

project

planning

Summary

Architecture specifications completed 2026-04-23. The original task was split into two concerns:

Config system → docs/architecture/hub-config.md — schemas, file format, two-layer key model (master key via Docker secret + data encryption keys in encrypted config file), _encrypted wrapper pattern, alkhub-config CLI tool.
Startup sequence → docs/architecture/hub-startup.md — 11-step ordered startup, fail-fast on missing prerequisites, health check contract with step-level progress, graceful shutdown mirroring startup.

ADR-008 revised to replace env var pattern with Docker secret + encrypted config file pattern.

Key Decisions

No env vars for secrets — Hard rule. No important keys or config in environment variables. Sensitive values arrive via Docker secret (master key) or encrypted config fields (postgres, redis, data encryption keys).
Two-layer keys — Master key (Docker secret) decrypts config file. Data encryption keys (v1:base64,v2:base64, inside the encrypted config) are used for client_secrets. Independent rotation schedules.
Whole-value encryption — postgres and redis sections are each encrypted as a single EncryptedData blob, not field-by-field. This leaks less topology information.
Fail-fast startup — No retry loops. If Postgres, Redis, or config is unavailable, exit immediately. Container orchestrator handles restarts.
Config read-once — Config file is loaded and validated once at startup. Runtime changes require restart.
Module-scope side effects prohibited — All initialization inside startHub(). No globals, no export const db = drizzle(pool).

Acceptance Criteria — Completed

HubConfig TypeBox schema specified — hub-config.md § Config Schema Hierarchy
SpokeConfig / BaseConfig schema hierarchy specified — hub-config.md
Master key provisioning mechanism documented — Docker secret /run/secrets/hub_master_key, hub-config.md § Master Key Provisioning
Config loading startup sequence specified — hub-startup.md § Startup Sequence (11 steps)
Multi-key encryption format documented — hub-config.md § Multi-Key Format; services.md updated to reference hub-config.md
Naming consistent — "data encryption keys" (in config), not env var references. ADR-008 revised. services.md updated.
crypto.ts bridge documented — hub-config.md § loadConfig (master key → decrypt config → resolveEncryptionKeys for data keys). Master key is a passphrase string consumed by PBKDF2; data encryption keys are base64 values used directly.
Docker deployment notes — hub-config.md § Master Key Provisioning, infrastructure.md updated with Docker secret + config file mounting

Cascade Updates

The following docs were updated to align with the no-env-vars pattern:

docs/architecture/storage/services.md — replaced HUB_ENCRYPTION_KEY env var references with data encryption key ring from hub config
docs/architecture/infrastructure.md — replaced docker run -e DATABASE_URL=... -e REDIS_URL=... with Docker secret + config file mounting
docs/architecture/storage/README.md — removed Deno.env.get() from DB connection code; updated test setup to use test config files
docs/decisions/ADR-008-secrets-encrypted-at-rest-with-key-versioning.md — revised from env var to Docker secret + two-layer key model

Open Items

SpokeConfig.auth field format is blocked on spoke-runner.md WebSocket auth design (hub-config.md Open Question #3)
Both specs are draft-stage — need another review pass before marking stable

3.8 KiB Raw Permalink Blame History