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

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

  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