diff --git a/.planning/phases/01-core-infrastructure-security/01-CONTEXT.md b/.planning/phases/01-core-infrastructure-security/01-CONTEXT.md new file mode 100644 index 0000000..f40aa6e --- /dev/null +++ b/.planning/phases/01-core-infrastructure-security/01-CONTEXT.md @@ -0,0 +1,69 @@ +# Phase 1: Core Infrastructure & Security - Context + +**Gathered:** 2026-01-25 +**Status:** Ready for planning + + +## Phase Boundary + +Production-ready backend infrastructure with security-hardened build environment. FastAPI backend, PostgreSQL database, HTTPS, rate limiting, CSRF protection, and sandboxed ISO builds using systemd-nspawn with deterministic output. + + + + +## Implementation Decisions + +### Sandbox Strictness +- Network access via whitelist: official Arch mirrors + our own package server +- Private overlays can require external packages (user's SSH keys, shell configs, etc.) +- Resource limits: generous (8GB RAM, 4 cores) — prioritize build speed over concurrent capacity +- No direct host filesystem access (Claude's discretion on read-only cache mounts if beneficial) + +### Determinism Approach +- **Critical constraint:** Same speech must produce identical ISO hash — caching depends on this +- Fixed build locale: en_US.UTF-8 + UTC timezone for all builds +- Package versioning and timestamp strategy: Claude's discretion based on archiso best practices +- Cache invalidation strategy: Claude's discretion + +### Error Visibility +- Friendly summary + expandable "Show full log" for power users +- Private builds = private logs (only the triggering user can see their logs) +- Admin access to logs requires explicit user consent ("share logs with support") +- Log retention: 30 days + +### Backup & Recovery +- Backup frequency: Claude's discretion +- Backup retention: Claude's discretion +- Recovery testing: Claude's discretion +- Storage: same infrastructure (no offsite requirement for v1) + +### Claude's Discretion +- Build timeout handling (soft warning vs hard kill, duration) +- Host path access for caching (if beneficial for performance) +- Timestamp strategy for deterministic builds (SOURCE_DATE_EPOCH or alternative) +- Package version locking mechanism +- Cache invalidation strategy when packages update +- Database backup frequency and retention +- Automated recovery testing approach + + + + +## Specific Ideas + +- "Caching of ISOs will take up too much space if we aren't able to reproduce the same hash for an ISO with the same speech" — determinism is a hard requirement, not a nice-to-have +- Private overlays are a real use case: user's SSH keys, default shell setup, personal configs + + + + +## Deferred Ideas + +- Locale management tool for installed systems — "a single tool they run and get a menu to select and it does everything in the background" — future phase (user experience enhancement) + + + +--- + +*Phase: 01-core-infrastructure-security* +*Context gathered: 2026-01-25*