diff --git a/README.md b/README.md index 56b6a3c..d8e11b2 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,131 @@ # Myst -My stuff, kept private. +> 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. +Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots. -## Phase 1 PR Breakdown +## Architecture -Phase 1 is split into these reviewable branches: +```mermaid +flowchart TB + subgraph VPS["VPS / Self-Hosted"] + subgraph Docker["Docker Network"] + Forgejo["Forgejo (Git Server)"] + Postgres["PostgreSQL (2 Databases)"] + Myst["Myst (This Service)"] + Traefik["Traefik (Reverse Proxy)"] + end + Tailscale["Tailscale (Admin Access)"] + end -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` + subgraph External["External"] + Owner["Repo Owner"] + Viewer["Link Recipient"] + end -## 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 - -```bash -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 + Owner -->|"Login via Forgejo Session"| Myst + Owner -->|"Create View Link (PAT)"| Forgejo + Myst -->|"Read-only API (PAT)"| Forgejo + Myst -->|"Store Grants"| Postgres + Forgejo -->|"Sessions"| Postgres + Myst -->|"Public Viewer"| Viewer + Myst -->|"Admin UI (Protected)"| Owner + Tailscale -->|"Private Admin Access"| Myst + Traefik -->|"Route HTTPS Traffic"| Myst ``` -The CLI is intended to wire Myst into an existing Forgejo deployment. It should not provision Forgejo, Postgres, TLS, or reverse proxies for operators. +## Features -- `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. +### Two Link Types -The Phase 1 pull requests are intentionally stacked so each review focuses on one layer of the system at a time. +| Type | Verification | Use Case | +|------|--------------|----------| +| **Private** | Email verification code required | Share with specific individuals | +| **Public** | No verification, time-expired | Job applications, portfolios | + +### Security + +- Links pinned to immutable `commit_sha` — not moving branches +- Email verification prevents unauthorized access +- Time-expiration and revocation give owners control +- No public repo listing — anti-scraping by design +- Admin access protected upstream (Tailscale, VPN, Cloudflare Access) + +### Authentication + +| Purpose | Method | +|---------|--------| +| User Identity | Forgejo Sessions | +| Data Access | Service Account PAT | + +### Tech Stack + +- **Backend**: Python + FastAPI +- **Frontend**: Jinja2 templates + HTMX (no build step) +- **Database**: PostgreSQL + +HTMX provides interactivity (filtering, form submissions) with minimal JavaScript. Jinja2 handles server-side rendering for fast page loads. + +## Quick Start + +### 1. Run `myst init` + +```bash +myst init +``` + +Prompts for: + +- Public viewer URL (`share.example.com`) +- Private admin URL (`admin.example.com`) +- Forgejo base URL (`git.example.com`) +- PostgreSQL connection string +- Forgejo service account username and PAT +- Grant token secret + +### 2. Configure Service Account + +Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT: + +- `read:user` +- `read:repository` + +### 3. Deploy + +Deploy via Dokploy, Coolify, or your preferred platform. + +## Example Configuration + +```env +MYST_PUBLIC_URL="https://share.example.com" +MYST_ADMIN_URL="https://admin.example.com" +DATABASE_URL="postgresql://myst:secret@localhost:5432/myst" +FORGEJO_BASE_URL="https://git.example.com" +FORGEJO_SERVICE_ACCOUNT_USERNAME="myst-bot" +FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx" +GRANT_TOKEN_SECRET="your-secret-here" +``` + +## Phase 1 Progress + +- [x] Project renamed from Embargo to Myst +- [x] CLI scaffold (`myst init`) +- [x] Config generation (`.env`, `myst.config.json`) +- [ ] Service foundation (FastAPI + PostgreSQL) +- [ ] `myst forgejo bootstrap` — verify Forgejo connectivity +- [ ] `myst doctor` — validate configuration +- [ ] `myst config print` — show current config +- [ ] Forgejo session authentication +- [ ] Repo ownership verification +- [ ] Private link creation (email-verified) +- [ ] Public link creation (time-expired) +- [ ] Web-based code viewer (Jinja2 + HTMX) +- [ ] User dashboard +- [ ] SMTP configuration UI +- [ ] Access logs + +## Resources + +- [Forgejo Docs](https://forgejo.org/docs/) +- [API Usage](https://forgejo.org/docs/latest/user/api-usage/) +- [Token Scopes](https://forgejo.org/docs/latest/user/token-scope/) diff --git a/docs/plans/2026-03-30-phase-1-design.md b/docs/plans/2026-03-30-phase-1-design.md index 5df9d3c..742759c 100644 --- a/docs/plans/2026-03-30-phase-1-design.md +++ b/docs/plans/2026-03-30-phase-1-design.md @@ -21,6 +21,21 @@ Phase 1 does not deliver: - 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`