firebreak/docs/plans/2026-03-30-phase-1-design.md

95 lines
3.9 KiB
Markdown

# Myst Phase 1 Design
This document captures the approved Phase 1 plan for Myst.
## Scope
Phase 1 delivers:
- CLI setup for attaching Myst to an existing Forgejo deployment
- Myst service foundation
- constrained Forgejo service-account integration
- immutable snapshot grants pinned to `commit_sha`
- owner dashboard and viewer flow
Phase 1 does not deliver:
- Forgejo provisioning
- Forgejo database provisioning
- reverse proxy or DNS automation
- platform-specific hosting orchestration beyond optional templates and docs
## Reviewable Branches
1. `codex/phase1-bootstrap-monorepo`
2. `codex/phase1-cli-init-skeleton`
3. `codex/phase1-service-foundation`
4. `codex/phase1-forgejo-integration`
5. `codex/phase1-grants-viewer`
6. `codex/phase1-dashboard-logs-settings`
## Security Baseline
- service account access is restricted to approved repos
- Myst grant checks are enforced on every Forgejo read
- grants store `repo_id` and pinned `commit_sha`
- viewer requests never choose repo or ref directly
- operators create the Forgejo service account and PAT themselves
- Myst stores only its own app config and metadata in its own database
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
- Myst does not ship built-in admin auth in Phase 1
## Forgejo Service Account Baseline
- the Forgejo service account is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
- the operator creates this user in Forgejo and grants repo access explicitly
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
- recommended PAT scopes are `read:user` and `read:repository`
- `read:organization` may also be required when repo visibility depends on org or team APIs
- Myst must not create Forgejo users, PATs, or repo permissions in Phase 1
## CLI Init Baseline
`myst init` should ask only for:
- public viewer URL, for example `https://share.example.com`
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
- Forgejo base URL, for example `https://git.example.com`
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
- Forgejo service account username, for example `myst-bot`
- Forgejo PAT for that service account
- grant token secret, with secure auto-generation as the default
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
- `.env`
- `myst.config.json`
- any future Myst-only deployment templates, but never Forgejo provisioning files
`myst init` should provide inline guidance that:
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
- the PAT should be created for the dedicated service account user
- the operator can consult Forgejo docs for token creation and scopes if needed
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
## Deployment Baseline
- Forgejo is already deployed and operator-managed
- Myst is deployed independently as its own app
- Myst uses its own Postgres database
- Myst reaches Forgejo via API using a least-privilege service account token
- the CLI validates configuration and connectivity rather than provisioning infrastructure
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
## Forgejo Bootstrap Baseline
`myst forgejo bootstrap` should verify, not provision:
- Forgejo base URL reachability
- service account token validity
- authenticated user matches the configured service account username
- minimum token scopes are sufficient for Myst's read-only API usage
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve