From d237d2a2c0f022d23da20d4997447c9754959d13 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Thu, 2 Apr 2026 16:43:38 -0400 Subject: [PATCH] docs: rewrite README with Myst branding and architecture - Add Mermaid architecture diagram - Document two link types (private/public) - Explain authentication model - Provide setup steps - Add example configuration - Include Phase 1 completion checklist --- README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 149 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a61cda1..fcf3da8 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,157 @@ -# Embargo +# Myst -Your code, under embargo. +My stuff, kept private. -Embargo 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 private 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 + + subgraph External["External"] + Owner["Repo Owner
(Browser)"] + Viewer["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 + 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 +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` +## Features -## Core Principles +### Two Link Types -- Embargo runs beside Forgejo and talks to it only through the Forgejo API. -- Share links pin to an immutable `commit_sha`, not a moving branch. -- Embargo uses its own owner auth for MVP. -- 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 Embargo has sharing enabled for it. +| Type | Verification | Use Case | +|------|--------------|----------| +| **Private** | Email verification code required | Share with specific individuals | +| **Public** | No verification, time-expired | Job applications, portfolios | +### Security Model + +- 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) + +### Authentication + +Myst uses two mechanisms: + +| 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 + +### 1. Run `myst init` + +```bash +# On your VPS, in the deployment directory +myst init +``` + +You'll be prompted 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`) +- 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: + +- `read:user` +- `read:repository` + +### 3. Deploy + +Deploy the Myst container using 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" +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" +``` + +### `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 + +- [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 +- [ ] Service foundation (PostgreSQL schema) +- [ ] Forgejo session authentication +- [ ] Repo ownership verification +- [ ] Private link creation (email-verified) +- [ ] Public link creation (time-expired) +- [ ] Web-based code viewer +- [ ] User dashboard +- [ ] SMTP configuration UI +- [ ] Access logs + +## Links + +- [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