mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-21 04:17:59 +00:00
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:
parent
b5595b4e85
commit
9838e73403
2 changed files with 300 additions and 40 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue