mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-21 12:27:59 +00:00
95 lines
3.9 KiB
Markdown
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
|