diff --git a/README.md b/README.md index 4525a88..e8f1320 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 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. ## Architecture @@ -10,31 +10,28 @@ Myst is a companion service for Forgejo that lets repo owners create expiring, r 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)"] + Forgejo["Forgejo (Git Server)"] + Postgres["PostgreSQL (2 Databases)"] + Myst["Myst (This Service)"] + Traefik["Traefik (Reverse Proxy)"] end - - Tailscale["Tailscale
(Admin Access)"] + Tailscale["Tailscale (Admin Access)"] end subgraph External["External"] - Owner["Repo Owner
(Browser)"] - Viewer["Viewer
(Link Recipient)"] + Owner["Repo Owner"] + Viewer["Link Recipient"] end - Owner -->|"Login via Forgejo
Session"| Myst - Owner -->|"Create View Link
API calls w/ PAT"| Forgejo - Myst -->|"Read-only API
Service Account PAT"| Forgejo - Myst -->|"Store Grants
Own Database"| Postgres + 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
share.example.com"| Viewer - Myst -->|"Admin UI
admin.example.com
(Protected)"| Owner - - Tailscale -->|"Private Admin
Access"| Myst - Traefik -->|"Route HTTPS
Traffic"| Myst + Myst -->|"Public Viewer"| Viewer + Myst -->|"Admin UI (Protected)"| Owner + Tailscale -->|"Private Admin Access"| Myst + Traefik -->|"Route HTTPS Traffic"| Myst ``` ## Features @@ -46,63 +43,51 @@ flowchart TB | **Private** | Email verification code required | Share with specific individuals | | **Public** | No verification, time-expired | Job applications, portfolios | -### Security Model +### Security -- Share links are **pinned to `commit_sha`** — immutable, not moving branches -- **Email-verified links** prevent unauthorized access -- **Time-expiration and revocation** give owners control -- **No public repo listing** — anti-scraping by design -- Admin access protected by **upstream controls** (Tailscale, VPN, Cloudflare Access) +- 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 -Myst uses two mechanisms: +| Purpose | Method | +|---------|--------| +| User Identity | Forgejo Sessions | +| Data Access | Service Account PAT | -| Purpose | Method | Who | -|---------|--------|-----| -| User Identity | Forgejo Sessions | Repo owners log in via Forgejo | -| Data Access | Service Account PAT | Myst fetches code from Forgejo API | - -## Setup - -### Prerequisites - -- Forgejo instance (self-hosted or managed) -- PostgreSQL database -- Domain names for viewer and admin -- SMTP server for email verification +## Quick Start ### 1. Run `myst init` ```bash -# On your VPS, in the deployment directory myst init ``` -You'll be prompted for: +Prompts for: -- Public viewer URL (e.g., `share.example.com`) -- Private admin URL (e.g., `admin.example.com`) -- Forgejo base URL (e.g., `git.example.com`) +- 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`) and generate a PAT with: +Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT: - `read:user` - `read:repository` ### 3. Deploy -Deploy the Myst container using Dokploy, Coolify, or your preferred platform. +Deploy via Dokploy, Coolify, or your preferred platform. ## Example Configuration -### `.env` (generated) - ```env MYST_PUBLIC_URL="https://share.example.com" MYST_ADMIN_URL="https://admin.example.com" @@ -110,27 +95,14 @@ 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="generate-or-paste-a-secret" +GRANT_TOKEN_SECRET="your-secret-here" ``` -### `myst.config.json` (generated) - -```json -{ - "publicUrl": "https://share.example.com", - "adminUrl": "https://admin.example.com", - "forgejoBaseUrl": "https://git.example.com", - "forgejoServiceAccountUsername": "myst-bot" -} -``` - -## Phase 1 Checklist +## Phase 1 Progress - [x] Project renamed from Embargo to Myst - [x] CLI scaffold (`myst init`) - [x] Config generation (`.env`, `myst.config.json`) -- [x] URL validation and normalization -- [x] Docker Compose generator removed (out of scope) - [ ] `myst forgejo bootstrap` — verify Forgejo connectivity - [ ] `myst doctor` — validate configuration - [ ] `myst config print` — show current config @@ -144,13 +116,8 @@ GRANT_TOKEN_SECRET="generate-or-paste-a-secret" - [ ] SMTP configuration UI - [ ] Access logs -## Links +## 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/) -- [Repo Permissions](https://forgejo.org/docs/latest/user/repo-permissions/) - -## License - -Apache 2.0