diff --git a/docs/plans/2026-03-30-phase-1-design.md b/docs/plans/2026-03-30-phase-1-design.md index aed247a..5df9d3c 100644 --- a/docs/plans/2026-03-30-phase-1-design.md +++ b/docs/plans/2026-03-30-phase-1-design.md @@ -11,6 +11,8 @@ Phase 1 delivers: - 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: @@ -39,6 +41,26 @@ Phase 1 does not deliver: - 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 (Service Account PAT)** +- Myst uses an operator-created service account PAT 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) + ## Forgejo Service Account Baseline - the Forgejo service account is a normal Forgejo user account dedicated to Myst, such as `myst-bot` @@ -48,6 +70,37 @@ Phase 1 does not deliver: - `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 service account 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: @@ -79,11 +132,45 @@ Phase 1 does not deliver: - Forgejo is already deployed and operator-managed - Myst is deployed independently as its own app -- Myst uses its own Postgres database +- 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 service account token - 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: @@ -93,3 +180,29 @@ Phase 1 does not deliver: - authenticated user matches the configured service account 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. diff --git a/docs/plans/2026-03-31-myst-auth-and-deployment-design.md b/docs/plans/2026-03-31-myst-auth-and-deployment-design.md index 8a3f824..242e377 100644 --- a/docs/plans/2026-03-31-myst-auth-and-deployment-design.md +++ b/docs/plans/2026-03-31-myst-auth-and-deployment-design.md @@ -1,6 +1,6 @@ # Myst Auth and Deployment Design -This document captures current decisions about deployment topology and CLI scope for Phase 1. +This document captures current decisions about deployment topology, authentication, and CLI scope for Phase 1. ## Goals @@ -9,6 +9,7 @@ This document captures current decisions about deployment topology and CLI scope - Expose only the read-only share-link viewer and Myst UI routes the operator chooses to publish. - Make the CLI responsible for Myst-specific configuration, validation, and Forgejo integration checks. - Keep Phase 1 scope minimal and shippable. +- Prevent code theft and scraping by controlling who can view shared links and how. ## Non-Goals @@ -16,7 +17,7 @@ This document captures current decisions about deployment topology and CLI scope - Provisioning Forgejo for operators. - Provisioning PostgreSQL for Forgejo or Myst. - Owning reverse proxy, DNS, TLS, backup, or firewall setup. -- Replacing Coolify or any other hosting platform. +- Replacing Dokploy, Coolify, or any other hosting platform. - Adding a SaaS control plane. - Requiring end users to join Tailscale in order to view shared code. - Designing a browser-based admin UX before the backend and integration flow exist. @@ -29,14 +30,15 @@ Myst is a companion service deployed beside an existing Forgejo instance. It own Public Internet | v - DNS: myst.example.com + DNS: share.example.com (viewer) + DNS: admin.example.com (dashboard, protected) | v - Reverse Proxy / Platform Router - (Coolify, Caddy, Nginx, etc.) + Reverse Proxy / Platform Router + (Dokploy, Caddy, Nginx, etc.) | v - Myst App (UI + API) + Myst App (Viewer + Dashboard) | ------------------- | | @@ -50,20 +52,132 @@ Deployment boundaries: - Forgejo is already running and is managed by the operator. - Myst is deployed independently from Forgejo. - Myst never reads or writes Forgejo's database directly. -- Myst authenticates to Forgejo with an operator-created service account token. +- Myst uses a service account PAT to call the Forgejo API. +- Myst uses Forgejo sessions to identify logged-in users. - Myst admin access is protected upstream rather than by an in-app login system in Phase 1. - VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface in Phase 1. +## Authentication + +Myst uses two authentication mechanisms for different purposes: + +### User Identity: Forgejo Sessions + +Users log in via Forgejo's existing session system: + +1. User visits Myst dashboard +2. Myst redirects to Forgejo login page +3. User authenticates with Forgejo credentials +4. Forgejo sets a session cookie +5. Myst validates the session via Forgejo API +6. Myst knows the user's identity without maintaining its own user database + +**Benefits:** +- No separate Myst login — users use their existing Forgejo account +- All Forgejo users with an account are trusted Myst users +- No separate user management in Myst + +### Data Access: Service Account PAT + +Myst uses an operator-created PAT to call the Forgejo API: + +1. Verify repo ownership when owner creates a view link +2. Fetch code content when serving view links to viewers + +**Why both mechanisms?** +- Sessions identify the user (zach@me.com is logged in) +- PAT authorizes Myst's server-to-server API calls (fetch repo data, verify ownership) +- PAT is not used for user identity — that's the session's job + +## Link Types + +### Private Links (Email-Verified) + +Intended for sharing with specific individuals via email. + +**Creation:** +- Owner selects repo and commit_sha +- Owner enters recipient's email address +- Owner sets expiration time +- Myst generates a unique link token + +**Viewer flow:** +1. Owner shares the link with the recipient (via email or copy) +2. Recipient clicks the link +3. Recipient enters email verification code from Myst's email +4. On successful verification, recipient can view the code snapshot + +**Protections:** +- Link is useless to anyone without the verification code +- Cannot scrape or index the content +- Owner can revoke access at any time + +### Public Links (Time-Expired) + +Intended for job applications, portfolios, and public sharing. + +**Creation:** +- Owner selects repo and commit_sha +- Owner sets expiration time (e.g., 7 days) +- No email required + +**Viewer flow:** +1. Owner copies the link +2. Pastes into a job application field or shares publicly +3. Anyone with the link can view immediately (no verification) + +**Protections:** +- Link expires automatically +- Owner can revoke at any time +- No public listing of repos or profiles + +## Anti-Scraping Protections + +Myst is designed to prevent code theft and scraping: + +- No public listing of repositories +- No profile exposure +- Private links require email verification +- Public links are time-limited and revocable +- Links are tied to immutable commit snapshots +- Cannot dig through repo list or browse content without a valid link + ## Deployment Myst should be deployable anywhere an operator can run a normal web app and Postgres database. Recommended v1 deployment environments: -1. Same VPS or host as Forgejo -2. Same Coolify project or private network as Forgejo +1. Same VPS or host as Forgejo (via Dokploy) +2. Same Dokploy project or private network as Forgejo 3. Separate host on the same trusted network as Forgejo +### 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 + +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 Configuration + +Myst uses its own Postgres database on the same DB server as Forgejo: + +- Separate databases (e.g., `forgejo` and `myst`) +- NOT shared tables or schemas +- Operators can run both on a small VPS efficiently +- Independent backups and migrations + Admin access security is the operator's responsibility (VPN, firewall rules, SSO, host access, etc). Myst does not enforce or scaffold this in Phase 1. Recommended admin protection modes: @@ -77,19 +191,6 @@ Recommended hostname split: - `https://share.example.com` for the public viewer - `https://admin.example.com` for the private admin UI -## Public Viewer Rules - -- Share links are public resources by design. -- Public access must be read-only. -- Public access must not expose database ports or Forgejo admin surfaces. -- Viewer requests must validate: - - link token - - expiration - - revoked state - - snapshot binding - -The viewer should be the only public application surface that emits code content. - ## CLI Responsibilities The CLI is the primary way to configure and validate Myst against an existing Forgejo deployment. @@ -112,6 +213,8 @@ The CLI is the primary way to configure and validate Myst against an existing Fo - show links to Forgejo docs for API usage, token scopes, repo permissions, and the admin CLI - remind operators to run `myst init` in the directory where Myst will be deployed, usually on the target VPS or server workspace +**Setup is manual** — operators enter all values directly. No auto-detection of Forgejo configuration. + Suggested `init` prompt guidance: - Public viewer URL: "What public URL should viewers use for shared links?" Example: `https://share.example.com` @@ -149,6 +252,7 @@ Forgejo docs to link directly from CLI output: - confirm the authenticated user matches the configured service account username - confirm Myst can resolve a branch or ref to a pinned `commit_sha` - confirm Myst can read tree and file data for a pinned commit +- verify Myst can confirm repo ownership for the operator's user account - never create Forgejo users, PATs, or repo permissions ### `doctor` @@ -182,18 +286,59 @@ Expected outputs from `init`: - `.env` - `myst.config.json` -- optional platform templates for Myst only +- optional platform templates for Myst only (e.g., Docker Compose for Dokploy) -## Data and Auth Model +## Data Model -- Share links are tied to immutable snapshots. -- Grants must resolve to a specific `commit_sha`. -- Viewer endpoints must never accept arbitrary repo/ref selection. -- Myst stores its metadata in its own Postgres database. -- Minimum v1 data model is `repos` and `grants`. -- Operators create the Forgejo service account and PAT themselves. -- Myst does not maintain a separate in-app admin user database in Phase 1. -- Admin access is delegated to operator-managed network or reverse-proxy controls. +Myst stores its metadata in its own Postgres database (separate from Forgejo's database). + +Minimum v1 data model: + +- `grants`: view link metadata (repo_id, commit_sha, type, expiration, email, revoked, created_by) +- `verification_codes`: email verification codes for private links (code, email, grant_id, expires_at) +- `sessions`: user sessions (session_token, forgejo_user_id, created_at, expires_at) +- `smtp_config`: SMTP settings (encrypted, configured via dashboard) + +Key constraints: + +- grants are tied to immutable commit snapshots +- viewer endpoints never accept arbitrary repo/ref selection +- link tokens are unique and unguessable +- verification codes expire quickly (e.g., 15 minutes) + +## User Dashboard + +The owner dashboard provides: + +- 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: + - Select repo (fetched via service account PAT, filtered to owned repos) + - Select commit (branch/tag to SHA resolution) + - Choose link type (public or private) + - Set expiration + - For private: enter recipient email +- Revoke/delete existing links +- SMTP configuration page + +**First-time setup:** +- After logging in via Forgejo, users see a quick setup page to configure SMTP credentials +- Once configured, full dashboard access is granted + +## Viewer Rules + +The viewer is the only public application surface that emits code content. + +- Share links are tied to immutable snapshots (commit_sha) +- Viewer requests must validate: + - link token + - expiration + - revoked state + - snapshot binding + - for private links: valid email verification code +- Public access must be read-only +- Public access must not expose database ports or Forgejo admin surfaces ## Repo Implementation Impact @@ -204,16 +349,18 @@ Active surfaces: - Config generators: `packages/cli/src/generators/*` - Shared constants/types: `packages/shared/src/*` - Service entrypoint: `packages/service/src/index.ts` +- Viewer routes: `packages/service/src/viewer/*` +- Dashboard routes: `packages/service/src/dashboard/*` Next implementation work: 1. Narrow `init` to Myst-only config generation for an existing Forgejo deployment -2. Add config types for Forgejo connection details, Myst base URL, and database settings +2. Add config types for Forgejo connection details, Myst base URL, database, and SMTP settings 3. Implement `forgejo bootstrap` and `doctor` -4. Add Postgres-backed service foundation using the minimum `repos` and `grants` schema +4. Add Postgres-backed service foundation using the data model 5. Wire the service to load generated config and validate required env at startup - -## Open Questions - -- Should the public viewer be mounted at a fixed path like `/share/*` or a dedicated hostname? -- Should the admin UI and viewer share a single Myst origin in v1, or should the docs recommend separate admin and public origins? +6. Implement Forgejo session authentication for the dashboard +7. Build the link creation flow with repo ownership verification +8. Implement the web-based code viewer +9. Build the user dashboard with access logs +10. Implement email sending for private link verification codes