Update Phase 1 plans with finalized design decisions

Major updates:
- Add authentication model (Forgejo sessions for identity, PAT for data access)
- Add link types (private email-verified, public time-expired)
- Add link creation rules (owner-only)
- Add Docker/deployment guidance (Dockerfile only, Dokploy handles orchestration)
- Add database model (separate DBs on same PostgreSQL instance)
- Add viewer baseline and user dashboard sections
- Add SMTP configuration via post-login setup page

Key architectural decisions:
- Users log in via Forgejo session, no separate Myst login
- Service account PAT used for API calls, not user identity
- Private links require email verification code
- Public links are time-expired for job applications
- Myst provides Dockerfile, operators use Dokploy for deployment
This commit is contained in:
ZTatman 2026-04-02 13:52:48 -04:00
parent b5595b4e85
commit 9838e73403
2 changed files with 300 additions and 40 deletions

View file

@ -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.

View file

@ -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