3.9 KiB
3.9 KiB
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
codex/phase1-bootstrap-monorepocodex/phase1-cli-init-skeletoncodex/phase1-service-foundationcodex/phase1-forgejo-integrationcodex/phase1-grants-viewercodex/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_idand pinnedcommit_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:userandread:repository read:organizationmay 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.comorhttps://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:
.envmyst.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.comare accepted and should default tohttps://
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