firebreak/docs/plans/phase-1-design.md
ZTatman 5187fd8de9 Organize docs and examples
- Centralize examples in /examples folder
- Fix README broken reference to docker-compose.example.yml
- Rename design docs (remove date prefixes)
2026-04-24 13:39:00 -04:00

222 lines
8.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
- two link types: private (email-verified) and public (time-expired)
- web-based code viewer (not git clone URLs)
Phase 1 does not deliver:
- Forgejo provisioning
- Forgejo database provisioning
- reverse proxy or DNS automation
- platform-specific hosting orchestration beyond optional templates and docs
## Tech Stack
- **Backend**: Python 3.11+ with FastAPI
- **Frontend**: Jinja2 templates with HTMX for interactivity
- **Database**: PostgreSQL
- **Async**: Uses `async/await` with asyncpg for database access
### Why This Stack?
**FastAPI**: Lightweight async framework, automatic OpenAPI docs, Pydantic for validation.
**Jinja2 + HTMX**: Server-side rendering with minimal JavaScript. HTMX handles dynamic updates (filtering, form submissions) without a build step or heavy SPA framework.
**PostgreSQL**: Reliable, well-supported by async libraries (asyncpg, SQLModel).
## 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
- dedicated Forgejo user 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 dedicated Forgejo user 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
## Authentication Model
Myst uses two authentication mechanisms:
**User Identity (Forgejo Sessions)**
- Users log in via Forgejo's session system
- Myst redirects to Forgejo login and validates the session
- Users use their existing Forgejo accounts — no separate Myst login
- All Forgejo users with an account are trusted Myst users
**Data Access (Dedicated Forgejo User PAT)**
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
- PAT is used to verify repo ownership and fetch code for viewers
- PAT is never used for user identity (that's handled by sessions)
**Why both?**
- Sessions identify who the user is (zach@me.com logged in)
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
## Dedicated Forgejo User Baseline
- the dedicated Forgejo user 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
## Link Types
Myst supports two types of view links:
### Private Links (Email-Verified)
- Time expired (configurable duration)
- Revocable by the owner
- Requires email verification code to view
- Tied to a specific email address
- Owner specifies the recipient's email when creating the link
- Myst sends an email with a verification code
- Viewer enters the code to access the snapshot
### Public Links (Time-Expired)
- Time expired (configurable duration)
- Revocable by the owner
- No verification required
- Anyone with the link can view
- Suitable for job application portfolio fields
- Owner copies the link and shares it directly
## Link Creation Rules
Only repo owners can create view links for their repos.
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
- Collaborators or read-access users cannot create view links
- Site admins are treated as regular users for this purpose (details to be finalized)
## 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 bot username, for example `myst-bot`
- Forgejo PAT for that dedicated Forgejo user
- grant token secret, with secure auto-generation as the default
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
- `.env` (environment variables for Docker/container deployment)
- 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 Forgejo 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 on the same DB server as Forgejo (separate database, not shared tables)
- Myst reaches Forgejo via API using a least-privilege PAT for the dedicated Forgejo user
- 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
### Docker and Deployment
Myst provides a Dockerfile for containerized deployment:
- Myst includes a `Dockerfile` in its repository for building the container image
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Myst container
- Myst does not generate Docker Compose files for Forgejo or other infrastructure
- Myst does not provision containers, images, or hosting resources
- Operators manage their own container orchestration (Dokploy handles this for most users)
For Dokploy users, deploying Myst is similar to deploying any other containerized application:
1. Build or import the Myst image using Dokploy's Docker Compose support
2. Configure environment variables from `.env` generated by `myst init`
3. Set up the public and admin domains in Dokploy's domain configuration
4. Dokploy handles Traefik routing, TLS, and container restarts
## Database Model
Myst uses its own Postgres database on the same DB server as Forgejo:
- separate databases (not shared tables with Forgejo)
- recommended: same PostgreSQL instance with `forgejo` and `myst` databases
- clean schema separation prevents coupling to Forgejo's database schema
- independent backups and migrations
- operators can run both databases on a small VPS efficiently
Minimum v1 data model:
- `grants`: view link metadata (repo, commit_sha, type, expiration, email, revoked)
- `verification_codes`: email verification codes for private links
- `sessions`: user sessions (validated against Forgejo)
- `smtp_config`: SMTP settings (encrypted)
## Forgejo Bootstrap Baseline
`myst forgejo bootstrap` should verify, not provision:
- Forgejo base URL reachability
- dedicated Forgejo user token validity
- authenticated user matches the configured Forgejo bot 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
- Myst can verify repo ownership for the operator's user account
## Viewer Baseline
The web-based viewer is the public-facing code display surface:
- displays code with syntax highlighting
- read-only, no raw git access
- validates link token, expiration, and revoked state
- for private links: requires valid email verification code
- for public links: accessible immediately with the link
- never exposes Forgejo admin surfaces or database ports
- pinned to immutable commit_sha (not moving branches)
## User Dashboard
The owner dashboard allows repo owners to manage their view links:
- list of created links (public and private)
- link status (active, expired, revoked)
- view count and access logs (details to be finalized)
- create new link flow
- revoke/delete existing links
- SMTP configuration page
First-time users see a quick setup page to configure SMTP credentials before accessing the full dashboard.