myst/README.md

2.6 KiB

Myst

My stuff, kept private.

Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for private code snapshots.

Phase 1 PR Breakdown

Phase 1 is split into these 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

Core Principles

  • Myst runs beside Forgejo and talks to it only through the Forgejo API.
  • Share links pin to an immutable commit_sha, not a moving branch.
  • Myst keeps the admin surface private through operator-managed network or reverse-proxy protection.
  • Myst does not provide built-in admin authentication in Phase 1; VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface.
  • Forgejo access is performed by a constrained service account with minimum PAT scopes.
  • A repo is shareable only if the service account can see it and Myst has sharing enabled for it.

Forgejo Integration Requirements

  • A Forgejo "service account" for Myst is a normal Forgejo user created by the operator, such as myst-bot.
  • The operator creates the PAT for that user and grants repo access explicitly.
  • Recommended PAT scopes are read:user and read:repository.
  • Some organization or team-based setups may also require read:organization.
  • Myst validates the account and token; it does not create Forgejo users, PATs, or repo permissions.

Helpful Forgejo docs:

  • API usage: https://forgejo.org/docs/latest/user/api-usage/
  • Token scopes: https://forgejo.org/docs/latest/user/token-scope/
  • Repo permissions: https://forgejo.org/docs/latest/user/repo-permissions/
  • Admin CLI: https://forgejo.org/docs/latest/admin/command-line/

Planned CLI Surface

pnpm --filter @myst/cli build
node packages/cli/dist/index.js init
node packages/cli/dist/index.js forgejo bootstrap
node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js config print

The CLI is intended to wire Myst into an existing Forgejo deployment. It should not provision Forgejo, Postgres, TLS, or reverse proxies for operators.

  • myst init generates the Myst-owned configuration files needed for deployment, including .env and myst.config.json.
  • myst forgejo bootstrap verifies Forgejo reachability, service-account identity, token scopes, and read access to the repo data Myst needs.

The Phase 1 pull requests are intentionally stacked so each review focuses on one layer of the system at a time.