From d237d2a2c0f022d23da20d4997447c9754959d13 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Thu, 2 Apr 2026 16:43:38 -0400 Subject: [PATCH 1/3] 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 From c6ae37e5177b89dfa4306063d10fdeba0e0ebc41 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Thu, 2 Apr 2026 16:49:01 -0400 Subject: [PATCH 2/3] fix: correct Mermaid diagram syntax --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fcf3da8..4525a88 100644 --- a/README.md +++ b/README.md @@ -15,27 +15,26 @@ flowchart TB 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 ``` ## Features From d3f7e9f620ec209cf5835e2da954a310a4a9af46 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Thu, 2 Apr 2026 17:01:50 -0400 Subject: [PATCH 3/3] refactor: streamline README per create-readme skill guidelines - Use blockquote for tagline - Simplify architecture diagram labels - Remove redundant sections (Setup, Example Config, License) - Keep checklist as primary tracking mechanism - Use tables for features and auth - Reduce verbosity throughout --- README.md | 107 +++++++++++++++++++----------------------------------- 1 file changed, 37 insertions(+), 70 deletions(-) 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