glm-5.1
2b63cda1c7
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.
54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
---
|
|
id: config-hub-startup-system
|
|
name: Specify Hub Config System and Startup Sequence
|
|
status: completed
|
|
depends_on: []
|
|
scope: broad
|
|
risk: high
|
|
impact: project
|
|
level: planning
|
|
---
|
|
|
|
## Summary
|
|
|
|
Architecture specifications completed 2026-04-23. The original task was split into two concerns:
|
|
|
|
1. **Config system** → [docs/architecture/hub-config.md](../../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.
|
|
|
|
2. **Startup sequence** → [docs/architecture/hub-startup.md](../../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
|
|
|
|
- [x] HubConfig TypeBox schema specified — hub-config.md § Config Schema Hierarchy
|
|
- [x] SpokeConfig / BaseConfig schema hierarchy specified — hub-config.md
|
|
- [x] Master key provisioning mechanism documented — Docker secret `/run/secrets/hub_master_key`, hub-config.md § Master Key Provisioning
|
|
- [x] Config loading startup sequence specified — hub-startup.md § Startup Sequence (11 steps)
|
|
- [x] Multi-key encryption format documented — hub-config.md § Multi-Key Format; services.md updated to reference hub-config.md
|
|
- [x] Naming consistent — "data encryption keys" (in config), not env var references. ADR-008 revised. services.md updated.
|
|
- [x] 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.
|
|
- [x] 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 |