chore: rename all references from myst/embargo to firebreak

This commit is contained in:
ZTatman 2026-08-16 13:13:02 -04:00
parent 29687c8878
commit 1f20e64960
17 changed files with 149 additions and 155 deletions

3
.gitignore vendored
View file

@ -19,3 +19,6 @@ web/*.py[cod]
# Tailwind standalone CLI # Tailwind standalone CLI
web/tailwindcss web/tailwindcss
web/app/static/css/output.css web/app/static/css/output.css
# Playwright
.playwright-mcp/

View file

@ -13,7 +13,7 @@ RUN pnpm install --frozen-lockfile
COPY . . COPY . .
RUN pnpm -r --filter @myst/service build RUN pnpm -r --filter @firebreak/service build
ENV PORT=3000 ENV PORT=3000
@ -21,4 +21,4 @@ EXPOSE 3000
USER node USER node
CMD ["pnpm", "--filter", "@myst/service", "start"] CMD ["pnpm", "--filter", "@firebreak/service", "start"]

View file

@ -1,4 +1,4 @@
# Myst UI Design # Firebreak UI Design
## Purpose ## Purpose
@ -7,7 +7,7 @@ Web application for creating secure, time-limited, view-only links to self-hoste
## Pages ## Pages
### Landing Page (`GET /`) ### Landing Page (`GET /`)
- Explains Myst - Explains Firebreak
- "Sign in with Forgejo" button - "Sign in with Forgejo" button
- Nav shows Sign in (anonymous) or Dashboard/Logout (authenticated) - Nav shows Sign in (anonymous) or Dashboard/Logout (authenticated)

View file

@ -1,21 +1,21 @@
# Myst Auth and Deployment Design # Firebreak Auth and Deployment Design
This document captures current decisions about deployment topology, authentication, and CLI scope for Phase 1. This document captures current decisions about deployment topology, authentication, and CLI scope for Phase 1.
## Goals ## Goals
- Keep Myst self-hosted and private by default. - Keep Firebreak self-hosted and private by default.
- Let operators attach Myst to an existing Forgejo deployment. - Let operators attach Firebreak to an existing Forgejo deployment.
- Expose only the read-only share-link viewer and Myst UI routes the operator chooses to publish. - Expose only the read-only share-link viewer and Firebreak UI routes the operator chooses to publish.
- Make the CLI responsible for Myst-specific configuration, validation, and Forgejo integration checks. - Make the CLI responsible for Firebreak-specific configuration, validation, and Forgejo integration checks.
- Keep Phase 1 scope minimal and shippable. - Keep Phase 1 scope minimal and shippable.
- Prevent code theft and scraping by controlling who can view shared links and how. - Prevent code theft and scraping by controlling who can view shared links and how.
## Non-Goals ## Non-Goals
- Built-in admin authentication in Myst for Phase 1. - Built-in admin authentication in Firebreak for Phase 1.
- Provisioning Forgejo for operators. - Provisioning Forgejo for operators.
- Provisioning PostgreSQL for Forgejo or Myst. - Provisioning PostgreSQL for Forgejo or Firebreak.
- Owning reverse proxy, DNS, TLS, backup, or firewall setup. - Owning reverse proxy, DNS, TLS, backup, or firewall setup.
- Replacing Dokploy, Coolify, or any other hosting platform. - Replacing Dokploy, Coolify, or any other hosting platform.
- Adding a SaaS control plane. - Adding a SaaS control plane.
@ -24,7 +24,7 @@ This document captures current decisions about deployment topology, authenticati
## Core Architecture ## Core Architecture
Myst is a companion service deployed beside an existing Forgejo instance. It owns its own UI/API app and its own database, and it integrates with Forgejo only through the Forgejo API. Firebreak is a companion service deployed beside an existing Forgejo instance. It owns its own UI/API app and its own database, and it integrates with Forgejo only through the Forgejo API.
```ascii ```ascii
Public Internet Public Internet
@ -38,55 +38,55 @@ Myst is a companion service deployed beside an existing Forgejo instance. It own
(Dokploy, Caddy, Nginx, etc.) (Dokploy, Caddy, Nginx, etc.)
| |
v v
Myst App (Viewer + Dashboard) Firebreak App (Viewer + Dashboard)
| |
------------------- -------------------
| | | |
v v v v
Myst Database Forgejo API Firebreak Database Forgejo API
(Postgres) (existing instance) (Postgres) (existing instance)
```ascii ```ascii
Deployment boundaries: Deployment boundaries:
- Forgejo is already running and is managed by the operator. - Forgejo is already running and is managed by the operator.
- Myst is deployed independently from Forgejo. - Firebreak is deployed independently from Forgejo.
- Myst never reads or writes Forgejo's database directly. - Firebreak never reads or writes Forgejo's database directly.
- Myst uses a PAT created for a dedicated Forgejo user to call the Forgejo API. - Firebreak uses a PAT created for a dedicated Forgejo user to call the Forgejo API.
- Myst uses Forgejo sessions to identify logged-in users. - Firebreak 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. - Firebreak 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. - VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface in Phase 1.
## Authentication ## Authentication
Myst uses two authentication mechanisms for different purposes: Firebreak uses two authentication mechanisms for different purposes:
### User Identity: Forgejo Sessions ### User Identity: Forgejo Sessions
Users log in via Forgejo's existing session system: Users log in via Forgejo's existing session system:
1. User visits Myst dashboard 1. User visits Firebreak dashboard
2. Myst redirects to Forgejo login page 2. Firebreak redirects to Forgejo login page
3. User authenticates with Forgejo credentials 3. User authenticates with Forgejo credentials
4. Forgejo sets a session cookie 4. Forgejo sets a session cookie
5. Myst validates the session via Forgejo API 5. Firebreak validates the session via Forgejo API
6. Myst knows the user's identity without maintaining its own user database 6. Firebreak knows the user's identity without maintaining its own user database
**Benefits:** **Benefits:**
- No separate Myst login — users use their existing Forgejo account - No separate Firebreak login — users use their existing Forgejo account
- All Forgejo users with an account are trusted Myst users - All Forgejo users with an account are trusted Firebreak users
- No separate user management in Myst - No separate user management in Firebreak
### Data Access: Dedicated Forgejo User PAT ### Data Access: Dedicated Forgejo User PAT
Myst uses an operator-created PAT to call the Forgejo API: Firebreak uses an operator-created PAT to call the Forgejo API:
1. Verify repo ownership when owner creates a view link 1. Verify repo ownership when owner creates a view link
2. Fetch code content when serving view links to viewers 2. Fetch code content when serving view links to viewers
**Why both mechanisms?** **Why both mechanisms?**
- Sessions identify the user (zach@me.com is logged in) - 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 authorizes Firebreak's server-to-server API calls (fetch repo data, verify ownership)
- PAT is not used for user identity — that's the session's job - PAT is not used for user identity — that's the session's job
## Link Types ## Link Types
@ -99,12 +99,12 @@ Intended for sharing with specific individuals via email.
- Owner selects repo and commit_sha - Owner selects repo and commit_sha
- Owner enters recipient's email address - Owner enters recipient's email address
- Owner sets expiration time - Owner sets expiration time
- Myst generates a unique link token - Firebreak generates a unique link token
**Viewer flow:** **Viewer flow:**
1. Owner shares the link with the recipient (via email or copy) 1. Owner shares the link with the recipient (via email or copy)
2. Recipient clicks the link 2. Recipient clicks the link
3. Recipient enters email verification code from Myst's email 3. Recipient enters email verification code from Firebreak's email
4. On successful verification, recipient can view the code snapshot 4. On successful verification, recipient can view the code snapshot
**Protections:** **Protections:**
@ -133,7 +133,7 @@ Intended for job applications, portfolios, and public sharing.
## Anti-Scraping Protections ## Anti-Scraping Protections
Myst is designed to prevent code theft and scraping: Firebreak is designed to prevent code theft and scraping:
- No public listing of repositories - No public listing of repositories
- No profile exposure - No profile exposure
@ -144,7 +144,7 @@ Myst is designed to prevent code theft and scraping:
## Deployment ## Deployment
Myst should be deployable anywhere an operator can run a normal web app and Postgres database. Firebreak should be deployable anywhere an operator can run a normal web app and Postgres database.
Recommended v1 deployment environments: Recommended v1 deployment environments:
@ -154,31 +154,31 @@ Recommended v1 deployment environments:
### Docker and Deployment ### Docker and Deployment
Myst provides a Dockerfile for containerized deployment: Firebreak provides a Dockerfile for containerized deployment:
- Myst includes a `Dockerfile` in its repository for building the container image - Firebreak 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 - Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Firebreak container
- Myst does not generate Docker Compose files for Forgejo or other infrastructure - Firebreak does not generate Docker Compose files for Forgejo or other infrastructure
- Myst does not provision containers, images, or hosting resources - Firebreak does not provision containers, images, or hosting resources
- Operators manage their own container orchestration - Operators manage their own container orchestration
For Dokploy users, deploying Myst is similar to deploying any other containerized application: For Dokploy users, deploying Firebreak is similar to deploying any other containerized application:
1. Build or import the Myst image using Dokploy's Docker Compose support 1. Build or import the Firebreak image using Dokploy's Docker Compose support
2. Configure environment variables from `.env` generated by `myst init` 2. Configure environment variables from `.env` generated by `firebreak init`
3. Set up the public and admin domains in Dokploy's domain configuration 3. Set up the public and admin domains in Dokploy's domain configuration
4. Dokploy handles Traefik routing, TLS, and container restarts 4. Dokploy handles Traefik routing, TLS, and container restarts
### Database Configuration ### Database Configuration
Myst uses its own Postgres database on the same DB server as Forgejo: Firebreak uses its own Postgres database on the same DB server as Forgejo:
- Separate databases (e.g., `forgejo` and `myst`) - Separate databases (e.g., `forgejo` and `firebreak`)
- NOT shared tables or schemas - NOT shared tables or schemas
- Operators can run both on a small VPS efficiently - Operators can run both on a small VPS efficiently
- Independent backups and migrations - 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. Admin access security is the operator's responsibility (VPN, firewall rules, SSO, host access, etc). Firebreak does not enforce or scaffold this in Phase 1.
Recommended admin protection modes: Recommended admin protection modes:
@ -193,7 +193,7 @@ Recommended hostname split:
## CLI Responsibilities ## CLI Responsibilities
The CLI is the primary way to configure and validate Myst against an existing Forgejo deployment. The CLI is the primary way to configure and validate Firebreak against an existing Forgejo deployment.
### `init` ### `init`
@ -202,36 +202,36 @@ The CLI is the primary way to configure and validate Myst against an existing Fo
- prompt for the public viewer URL, for example `https://share.example.com` - prompt for the public viewer URL, for example `https://share.example.com`
- prompt for the private admin URL, for example `https://admin.example.com` - prompt for the private admin URL, for example `https://admin.example.com`
- prompt for the Forgejo base URL, for example `https://git.example.com` - prompt for the Forgejo base URL, for example `https://git.example.com`
- collect the dedicated Forgejo username Myst should use for API access, for example `myst-bot` - collect the dedicated Forgejo username Firebreak should use for API access, for example `firebreak-bot`
- collect a user-created Forgejo PAT for that dedicated Forgejo user - collect a user-created Forgejo PAT for that dedicated Forgejo user
- collect Myst Postgres connection details, for example `postgresql://myst:password@db.example.com:5432/myst` - collect Firebreak Postgres connection details, for example `postgresql://firebreak:password@db.example.com:5432/firebreak`
- generate a grant token secret by default unless the operator pastes one - generate a grant token secret by default unless the operator pastes one
- generate all Myst-owned config files needed for deployment in Phase 1 - generate all Firebreak-owned config files needed for deployment in Phase 1
- write `.env` - write `.env`
- print manual follow-up actions for admin URL protection, app deployment, and Forgejo validation - print manual follow-up actions for admin URL protection, app deployment, and Forgejo validation
- show links to Forgejo docs for API usage, token scopes, repo permissions, and the admin CLI - 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 - remind operators to run `firebreak init` in the directory where Firebreak 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. **Setup is manual** — operators enter all values directly. No auto-detection of Forgejo configuration.
Suggested `init` prompt guidance: Suggested `init` prompt guidance:
- Public viewer URL: "What public URL should viewers use for shared links?" Example: `https://share.example.com` - Public viewer URL: "What public URL should viewers use for shared links?" Example: `https://share.example.com`
- Private admin URL: "What private URL should operators use for the Myst admin UI?" Example: `https://admin.example.com` - Private admin URL: "What private URL should operators use for the Firebreak admin UI?" Example: `https://admin.example.com`
- Forgejo base URL: "What is the base URL of your existing Forgejo instance?" Example: `https://git.example.com` - Forgejo base URL: "What is the base URL of your existing Forgejo instance?" Example: `https://git.example.com`
- Myst database URL: "What Postgres connection string should Myst use?" Example: `postgresql://myst:password@db.example.com:5432/myst` - Firebreak database URL: "What Postgres connection string should Firebreak use?" Example: `postgresql://firebreak:password@db.example.com:5432/firebreak`
- Dedicated Forgejo username: "What Forgejo username should Myst use for API access?" Example: `myst-bot` - Dedicated Forgejo username: "What Forgejo username should Firebreak use for API access?" Example: `firebreak-bot`
- Forgejo PAT: "Paste the Forgejo personal access token for that dedicated Forgejo user" Example: `fgp_...` - Forgejo PAT: "Paste the Forgejo personal access token for that dedicated Forgejo user" Example: `fgp_...`
- Grant token secret: "Paste a grant token secret, or press enter to generate one automatically" - Grant token secret: "Paste a grant token secret, or press enter to generate one automatically"
Suggested `init` prompt notes: Suggested `init` prompt notes:
- "Protect the admin URL upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth. Myst does not provide admin auth in Phase 1." - "Protect the admin URL upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth. Firebreak does not provide admin auth in Phase 1."
- "Use a dedicated Forgejo user for Myst and create the PAT as that user." - "Use a dedicated Forgejo user for Firebreak and create the PAT as that user."
- "Recommended PAT scopes: `read:user`, `read:repository`; add `read:organization` only if your org or team setup requires it." - "Recommended PAT scopes: `read:user`, `read:repository`; add `read:organization` only if your org or team setup requires it."
- "Do not point Myst at Forgejo's database tables." - "Do not point Firebreak at Forgejo's database tables."
- "Bare hostnames such as `share.example.com` are accepted and default to `https://`. Enter the full URL only if you need `http://` or a custom path." - "Bare hostnames such as `share.example.com` are accepted and default to `https://`. Enter the full URL only if you need `http://` or a custom path."
- "Run `myst init` in the directory where you plan to deploy Myst so the generated files are already in place on the target host." - "Run `firebreak init` in the directory where you plan to deploy Firebreak so the generated files are already in place on the target host."
Forgejo docs to link directly from CLI output: Forgejo docs to link directly from CLI output:
@ -247,18 +247,18 @@ Forgejo docs to link directly from CLI output:
- validate Forgejo connectivity - validate Forgejo connectivity
- validate the provided dedicated Forgejo user token - validate the provided dedicated Forgejo user token
- verify minimum required scopes and permissions - verify minimum required scopes and permissions
- confirm Myst can resolve the repos it needs - confirm Firebreak can resolve the repos it needs
- confirm the authenticated user matches the configured dedicated Forgejo username - confirm the authenticated user matches the configured dedicated Forgejo username
- confirm Myst can resolve a branch or ref to a pinned `commit_sha` - confirm Firebreak can resolve a branch or ref to a pinned `commit_sha`
- confirm Myst can read tree and file data for a pinned commit - confirm Firebreak can read tree and file data for a pinned commit
- verify Myst can confirm repo ownership for the operator's user account - verify Firebreak can confirm repo ownership for the operator's user account
- never create Forgejo users, PATs, or repo permissions - never create Forgejo users, PATs, or repo permissions
### `doctor` ### `doctor`
`doctor` should: `doctor` should:
- validate the local Myst config - validate the local Firebreak config
- validate database connectivity - validate database connectivity
- validate Forgejo API reachability - validate Forgejo API reachability
- validate token/scopes/permissions - validate token/scopes/permissions
@ -268,7 +268,7 @@ Forgejo docs to link directly from CLI output:
`config print` should: `config print` should:
- show resolved Myst configuration - show resolved Firebreak configuration
- redact secrets by default - redact secrets by default
- help operators debug misconfiguration without touching infrastructure - help operators debug misconfiguration without touching infrastructure
@ -284,11 +284,11 @@ Forgejo docs to link directly from CLI output:
Expected outputs from `init`: Expected outputs from `init`:
- `.env` - `.env`
- optional platform templates for Myst only (e.g., Docker Compose for Dokploy) - optional platform templates for Firebreak only (e.g., Docker Compose for Dokploy)
## Data Model ## Data Model
Myst stores its metadata in its own Postgres database (separate from Forgejo's database). Firebreak stores its metadata in its own Postgres database (separate from Forgejo's database).
Minimum v1 data model: Minimum v1 data model:
@ -352,8 +352,8 @@ Active surfaces:
Next implementation work: Next implementation work:
1. Narrow `init` to Myst-only config generation for an existing Forgejo deployment 1. Narrow `init` to Firebreak-only config generation for an existing Forgejo deployment
2. Add config types for Forgejo connection details, Myst base URL, database, and SMTP settings 2. Add config types for Forgejo connection details, Firebreak base URL, database, and SMTP settings
3. Implement `forgejo bootstrap` and `doctor` 3. Implement `forgejo bootstrap` and `doctor`
4. Add Postgres-backed service foundation using the data model 4. Add Postgres-backed service foundation using the data model
5. Wire the service to load generated config and validate required env at startup 5. Wire the service to load generated config and validate required env at startup

View file

@ -1,13 +1,13 @@
# Myst Phase 1 Design # Firebreak Phase 1 Design
This document captures the approved Phase 1 plan for Myst. This document captures the approved Phase 1 plan for Firebreak.
## Scope ## Scope
Phase 1 delivers: Phase 1 delivers:
- CLI setup for attaching Myst to an existing Forgejo deployment - CLI setup for attaching Firebreak to an existing Forgejo deployment
- Myst service foundation - Firebreak service foundation
- constrained Forgejo service-account integration - constrained Forgejo service-account integration
- immutable snapshot grants pinned to `commit_sha` - immutable snapshot grants pinned to `commit_sha`
- owner dashboard and viewer flow - owner dashboard and viewer flow
@ -48,46 +48,46 @@ Phase 1 does not deliver:
## Security Baseline ## Security Baseline
- dedicated Forgejo user access is restricted to approved repos - dedicated Forgejo user access is restricted to approved repos
- Myst grant checks are enforced on every Forgejo read - Firebreak grant checks are enforced on every Forgejo read
- grants store `repo_id` and pinned `commit_sha` - grants store `repo_id` and pinned `commit_sha`
- viewer requests never choose repo or ref directly - viewer requests never choose repo or ref directly
- operators create the dedicated Forgejo user and PAT themselves - operators create the dedicated Forgejo user and PAT themselves
- Myst stores only its own app config and metadata in its own database - Firebreak stores only its own app config and metadata in its own database
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls - 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 - Firebreak does not ship built-in admin auth in Phase 1
## Authentication Model ## Authentication Model
Myst uses two authentication mechanisms: Firebreak uses two authentication mechanisms:
**User Identity (Forgejo Sessions)** **User Identity (Forgejo Sessions)**
- Users log in via Forgejo's session system - Users log in via Forgejo's session system
- Myst redirects to Forgejo login and validates the session - Firebreak redirects to Forgejo login and validates the session
- Users use their existing Forgejo accounts — no separate Myst login - Users use their existing Forgejo accounts — no separate Firebreak login
- All Forgejo users with an account are trusted Myst users - All Forgejo users with an account are trusted Firebreak users
**Data Access (Dedicated Forgejo User PAT)** **Data Access (Dedicated Forgejo User PAT)**
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API - Firebreak uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
- PAT is used to verify repo ownership and fetch code for viewers - PAT is used to verify repo ownership and fetch code for viewers
- PAT is never used for user identity (that's handled by sessions) - PAT is never used for user identity (that's handled by sessions)
**Why both?** **Why both?**
- Sessions identify who the user is (zach@me.com logged in) - 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 Firebreak 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) - PAT allows Firebreak to fetch code content for the viewer (get the pinned commit's files)
## Dedicated Forgejo User Baseline ## Dedicated Forgejo User Baseline
- the dedicated Forgejo user is a normal Forgejo user account dedicated to Myst, such as `myst-bot` - the dedicated Forgejo user is a normal Forgejo user account dedicated to Firebreak, such as `firebreak-bot`
- the operator creates this user in Forgejo and grants repo access explicitly - the operator creates this user in Forgejo and grants repo access explicitly
- the operator creates the PAT for this user through the Forgejo UI or admin CLI - the operator creates the PAT for this user through the Forgejo UI or admin CLI
- recommended PAT scopes are `read:user` and `read:repository` - recommended PAT scopes are `read:user` and `read:repository`
- `read:organization` may also be required when repo visibility depends on org or team APIs - `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 - Firebreak must not create Forgejo users, PATs, or repo permissions in Phase 1
## Link Types ## Link Types
Myst supports two types of view links: Firebreak supports two types of view links:
### Private Links (Email-Verified) ### Private Links (Email-Verified)
@ -96,7 +96,7 @@ Myst supports two types of view links:
- Requires email verification code to view - Requires email verification code to view
- Tied to a specific email address - Tied to a specific email address
- Owner specifies the recipient's email when creating the link - Owner specifies the recipient's email when creating the link
- Myst sends an email with a verification code - Firebreak sends an email with a verification code
- Viewer enters the code to access the snapshot - Viewer enters the code to access the snapshot
### Public Links (Time-Expired) ### Public Links (Time-Expired)
@ -112,32 +112,32 @@ Myst supports two types of view links:
Only repo owners can create view links for their repos. Only repo owners can create view links for their repos.
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT - Firebreak verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
- Collaborators or read-access users cannot create view links - Collaborators or read-access users cannot create view links
- Site admins are treated as regular users for this purpose (details to be finalized) - Site admins are treated as regular users for this purpose (details to be finalized)
## CLI Init Baseline ## CLI Init Baseline
`myst init` should ask only for: `firebreak init` should ask only for:
- public viewer URL, for example `https://share.example.com` - public viewer URL, for example `https://share.example.com`
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net` - private admin URL, for example `https://admin.example.com` or `https://firebreak-admin.tailnet.ts.net`
- Forgejo base URL, for example `https://git.example.com` - Forgejo base URL, for example `https://git.example.com`
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst` - Firebreak Postgres URL, for example `postgresql://firebreak:password@db.example.com:5432/firebreak`
- Forgejo bot username, for example `myst-bot` - Forgejo bot username, for example `firebreak-bot`
- Forgejo PAT for that dedicated Forgejo user - Forgejo PAT for that dedicated Forgejo user
- grant token secret, with secure auto-generation as the default - grant token secret, with secure auto-generation as the default
`myst init` should generate all Myst-owned deployment config needed for Phase 1: `firebreak init` should generate all Firebreak-owned deployment config needed for Phase 1:
- `.env` (environment variables for Docker/container deployment) - `.env` (environment variables for Docker/container deployment)
- any future Myst-only deployment templates, but never Forgejo provisioning files - any future Firebreak-only deployment templates, but never Forgejo provisioning files
`myst init` should provide inline guidance that: `firebreak init` should provide inline guidance that:
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace - it should be run in the directory where Firebreak will be deployed, usually on the target VPS or server workspace
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1 - the admin URL must be protected upstream because Firebreak does not provide admin auth in Phase 1
- the database URL must point to Myst's own Postgres database, not Forgejo's tables - the database URL must point to Firebreak's own Postgres database, not Forgejo's tables
- the PAT should be created for the dedicated Forgejo user - the PAT should be created for the dedicated Forgejo user
- the operator can consult Forgejo docs for token creation and scopes if needed - the operator can consult Forgejo docs for token creation and scopes if needed
- bare hostnames such as `share.example.com` are accepted and should default to `https://` - bare hostnames such as `share.example.com` are accepted and should default to `https://`
@ -145,35 +145,35 @@ Only repo owners can create view links for their repos.
## Deployment Baseline ## Deployment Baseline
- Forgejo is already deployed and operator-managed - Forgejo is already deployed and operator-managed
- Myst is deployed independently as its own app - Firebreak is deployed independently as its own app
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables) - Firebreak 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 PAT for the dedicated Forgejo user - Firebreak reaches Forgejo via API using a least-privilege PAT for the dedicated Forgejo user
- the CLI validates configuration and connectivity rather than provisioning infrastructure - 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 - the Firebreak admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
### Docker and Deployment ### Docker and Deployment
Myst provides a Dockerfile for containerized deployment: Firebreak provides a Dockerfile for containerized deployment:
- Myst includes a `Dockerfile` in its repository for building the container image - Firebreak 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 - Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Firebreak container
- Myst does not generate Docker Compose files for Forgejo or other infrastructure - Firebreak does not generate Docker Compose files for Forgejo or other infrastructure
- Myst does not provision containers, images, or hosting resources - Firebreak does not provision containers, images, or hosting resources
- Operators manage their own container orchestration (Dokploy handles this for most users) - 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: For Dokploy users, deploying Firebreak is similar to deploying any other containerized application:
1. Build or import the Myst image using Dokploy's Docker Compose support 1. Build or import the Firebreak image using Dokploy's Docker Compose support
2. Configure environment variables from `.env` generated by `myst init` 2. Configure environment variables from `.env` generated by `firebreak init`
3. Set up the public and admin domains in Dokploy's domain configuration 3. Set up the public and admin domains in Dokploy's domain configuration
4. Dokploy handles Traefik routing, TLS, and container restarts 4. Dokploy handles Traefik routing, TLS, and container restarts
## Database Model ## Database Model
Myst uses its own Postgres database on the same DB server as Forgejo: Firebreak uses its own Postgres database on the same DB server as Forgejo:
- separate databases (not shared tables with Forgejo) - separate databases (not shared tables with Forgejo)
- recommended: same PostgreSQL instance with `forgejo` and `myst` databases - recommended: same PostgreSQL instance with `forgejo` and `firebreak` databases
- clean schema separation prevents coupling to Forgejo's database schema - clean schema separation prevents coupling to Forgejo's database schema
- independent backups and migrations - independent backups and migrations
- operators can run both databases on a small VPS efficiently - operators can run both databases on a small VPS efficiently
@ -187,14 +187,14 @@ Minimum v1 data model:
## Forgejo Bootstrap Baseline ## Forgejo Bootstrap Baseline
`myst forgejo bootstrap` should verify, not provision: `firebreak forgejo bootstrap` should verify, not provision:
- Forgejo base URL reachability - Forgejo base URL reachability
- dedicated Forgejo user token validity - dedicated Forgejo user token validity
- authenticated user matches the configured Forgejo bot username - authenticated user matches the configured Forgejo bot username
- minimum token scopes are sufficient for Myst's read-only API usage - minimum token scopes are sufficient for Firebreak's read-only API usage
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve - Firebreak 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 - Firebreak can verify repo ownership for the operator's user account
## Viewer Baseline ## Viewer Baseline

View file

@ -1,8 +1,8 @@
# Application # Application
APP_NAME=Myst APP_NAME=Firebreak
# Database (Docker Compose auto-configures this) # Database (Docker Compose auto-configures this)
DATABASE_URL=postgresql+asyncpg://myst:myst@db:5432/myst_db DATABASE_URL=postgresql+asyncpg://firebreak:firebreak@db:5432/firebreak_db
# Forgejo # Forgejo
FORGEJO_BASE_URL= FORGEJO_BASE_URL=

View file

@ -1,5 +1,5 @@
{ {
"name": "myst", "name": "firebreak",
"private": true, "private": true,
"version": "0.1.0", "version": "0.1.0",
"packageManager": "pnpm@10.33.0", "packageManager": "pnpm@10.33.0",

View file

@ -1,19 +1,19 @@
{ {
"name": "@myst/cli", "name": "@firebreak/cli",
"description": "CLI for configuring and verifying Myst with Forgejo", "description": "CLI for configuring and verifying Firebreak with Forgejo",
"version": "0.1.0", "version": "0.1.0",
"author": { "author": {
"name": "Zach Tatman", "name": "Zach Tatman",
"email": "zach.tatman.dev@gmail.com" "email": "zach.tatman.dev@gmail.com"
}, },
"bugs": { "bugs": {
"url": "https://github.com/ZTatman/myst/issues" "url": "https://github.com/ZTatman/firebreak/issues"
}, },
"homepage": "https://github.com/ZTatman/myst#readme", "homepage": "https://github.com/ZTatman/firebreak#readme",
"private": true, "private": true,
"type": "module", "type": "module",
"bin": { "bin": {
"myst": "./dist/index.js" "firebreak": "./dist/index.js"
}, },
"scripts": { "scripts": {
"build": "tsc -p tsconfig.json", "build": "tsc -p tsconfig.json",

View file

@ -53,12 +53,12 @@ function showHelp(registry: CommandRegistry, description: string): void {
const colWidth = Math.max(...allRows.map((r) => r.name.length)) + PADDING; const colWidth = Math.max(...allRows.map((r) => r.name.length)) + PADDING;
const lines: string[] = []; const lines: string[] = [];
lines.push(c.yellow("myst")); lines.push(c.yellow("firebreak"));
lines.push(""); lines.push("");
lines.push(`${INDENT}${description}`); lines.push(`${INDENT}${description}`);
lines.push(""); lines.push("");
lines.push(c.bold("Usage:")); lines.push(c.bold("Usage:"));
lines.push(`${INDENT}myst <command> [options]`); lines.push(`${INDENT}firebreak <command> [options]`);
lines.push(""); lines.push("");
lines.push(c.bold("Commands:")); lines.push(c.bold("Commands:"));
@ -99,7 +99,7 @@ function showCommandHelp(
const lines: string[] = []; const lines: string[] = [];
const fullName = subcommand ? `${command} ${subcommand}` : command; const fullName = subcommand ? `${command} ${subcommand}` : command;
lines.push(c.yellow("myst " + fullName)); lines.push(c.yellow("firebreak " + fullName));
lines.push(""); lines.push("");
if (targetConf.description) { if (targetConf.description) {
@ -112,8 +112,8 @@ function showCommandHelp(
const usageCmd = subcommand ? `${command} ${subcommand}` : command; const usageCmd = subcommand ? `${command} ${subcommand}` : command;
const usageLine = const usageLine =
hasSubcommands && !subcommand hasSubcommands && !subcommand
? `myst ${command} <subcommand> [options]` ? `firebreak ${command} <subcommand> [options]`
: `myst ${usageCmd} [options]`; : `firebreak ${usageCmd} [options]`;
lines.push(c.bold("Usage:")); lines.push(c.bold("Usage:"));
lines.push(`${INDENT}${usageLine}`); lines.push(`${INDENT}${usageLine}`);
lines.push(""); lines.push("");
@ -201,7 +201,7 @@ export async function runCli(
const subcommand = argv[1] ?? ""; const subcommand = argv[1] ?? "";
const remainingArgs = argv.slice(2); const remainingArgs = argv.slice(2);
// If user types myst -h or --help with a command // If user types firebreak -h or --help with a command
const wantsCommandHelp = const wantsCommandHelp =
isHelpFlag(subcommand) || remainingArgs.some(isHelpFlag); isHelpFlag(subcommand) || remainingArgs.some(isHelpFlag);

View file

@ -36,10 +36,10 @@ function validateHttpUrlOrHost(
} }
async function init(opts: { output?: string }) { async function init(opts: { output?: string }) {
p.intro(c.bold("myst config init")); p.intro(c.bold("firebreak config init"));
p.note( p.note(
[ [
`${c.bold("Run this in the directory where you plan to deploy Myst.")}`, `${c.bold("Run this in the directory where you plan to deploy Firebreak.")}`,
"", "",
c.bold("Forgejo docs:"), c.bold("Forgejo docs:"),
"", "",
@ -116,7 +116,7 @@ async function init(opts: { output?: string }) {
forgejoBaseUrl: () => forgejoBaseUrl: () =>
p.text({ p.text({
message: message:
"Forgejo API URL (how Myst reaches Forgejo, not your browser URL)?", "Forgejo API URL (how Firebreak reaches Forgejo, not your browser URL)?",
placeholder: "http://forgejo:3000", placeholder: "http://forgejo:3000",
validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"), validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"),
}), }),
@ -171,19 +171,19 @@ async function init(opts: { output?: string }) {
[ [
`${c.bold("Forgejo API URL:")} ${c.cyan(forgejoBaseUrl)}`, `${c.bold("Forgejo API URL:")} ${c.cyan(forgejoBaseUrl)}`,
"", "",
`Myst will use this URL to call Forgejo's API.`, `Firebreak will use this URL to call Forgejo's API.`,
`- Docker (same Compose network): http://forgejo:3000`, `- Docker (same Compose network): http://forgejo:3000`,
`- Bare metal / non-container: http://localhost:3000`, `- Bare metal / non-container: http://localhost:3000`,
`- Cross-host deployment: https://git.example.com`, `- Cross-host deployment: https://git.example.com`,
].join("\n"), ].join("\n"),
); );
p.log.success( p.log.success(
"Done. Verify myst's connection using the 'verify' command.\nOnce verified, deploy!", "Done. Verify firebreak's connection using the 'verify' command.\nOnce verified, deploy!",
); );
} catch (error) { } catch (error) {
s.stop(); s.stop();
p.cancel( p.cancel(
error instanceof Error ? error.message : "Failed to initialize Myst", error instanceof Error ? error.message : "Failed to initialize Firebreak",
); );
process.exitCode = 1; process.exitCode = 1;
} }

View file

@ -4,7 +4,7 @@ import * as c from "yoctocolors";
import { import {
ENV_MAPPING, ENV_MAPPING,
MystEnvironmentVariables, FirebreakEnvironmentVariables,
parseEnvFile, parseEnvFile,
SECRET_KEYS, SECRET_KEYS,
} from "../../utils/config.js"; } from "../../utils/config.js";
@ -15,7 +15,7 @@ export const commandConfig: CommandConfig = {
handler: async () => { handler: async () => {
const envPath = path.join(process.cwd(), ".env"); const envPath = path.join(process.cwd(), ".env");
let config: Partial<MystEnvironmentVariables>; let config: Partial<FirebreakEnvironmentVariables>;
try { try {
config = parseEnvFile(envPath); config = parseEnvFile(envPath);
@ -31,7 +31,7 @@ export const commandConfig: CommandConfig = {
throw error; throw error;
} }
process.stdout.write(c.bold("Myst Configuration\n")); process.stdout.write(c.bold("Firebreak Configuration\n"));
process.stdout.write(`${c.dim("─".repeat(40))}\n`); process.stdout.write(`${c.dim("─".repeat(40))}\n`);
for (const [envKey, configKey] of Object.entries(ENV_MAPPING)) { for (const [envKey, configKey] of Object.entries(ENV_MAPPING)) {

View file

@ -162,7 +162,7 @@ async function runForgejoChecks(
async function verifyCommand(opts: VerifyOptions): Promise<void> { async function verifyCommand(opts: VerifyOptions): Promise<void> {
const isDiagnostic = opts.diagnostic ?? false; const isDiagnostic = opts.diagnostic ?? false;
p.intro(c.bold("myst verify")); p.intro(c.bold("firebreak verify"));
const config = loadConfig(); const config = loadConfig();
if (!config) { if (!config) {
@ -179,7 +179,7 @@ async function verifyCommand(opts: VerifyOptions): Promise<void> {
} }
export const commandConfig: CommandConfig = { export const commandConfig: CommandConfig = {
description: "Verify Myst configuration and connection to Forgejo", description: "Verify Firebreak configuration and connection to Forgejo",
options: { options: {
diagnostic: { diagnostic: {
type: "boolean", type: "boolean",

View file

@ -1,6 +1,6 @@
import fs from "node:fs"; import fs from "node:fs";
export interface MystEnvironmentVariables { export interface FirebreakEnvironmentVariables {
forgejoBaseUrl: string; forgejoBaseUrl: string;
forgejoPat: string; forgejoPat: string;
} }
@ -18,8 +18,8 @@ export const SECRET_ENV_KEYS = ["FORGEJO_PAT"] as const;
export function parseEnvFile( export function parseEnvFile(
envPath: string, envPath: string,
): Partial<MystEnvironmentVariables> { ): Partial<FirebreakEnvironmentVariables> {
const config: Partial<MystEnvironmentVariables> = {}; const config: Partial<FirebreakEnvironmentVariables> = {};
const content = fs.readFileSync(envPath, "utf-8"); const content = fs.readFileSync(envPath, "utf-8");
const lines = content.split("\n"); const lines = content.split("\n");
@ -41,9 +41,9 @@ export function parseEnvFile(
return config; return config;
} }
export function generateEnvFile(options: MystEnvironmentVariables): string { export function generateEnvFile(options: FirebreakEnvironmentVariables): string {
const lines = [ const lines = [
`# Forgejo API endpoint that Myst calls.`, `# Forgejo API endpoint that Firebreak calls.`,
`# Docker (same Compose network): http://forgejo:3000`, `# Docker (same Compose network): http://forgejo:3000`,
`# Bare metal / non-container: http://localhost:3000`, `# Bare metal / non-container: http://localhost:3000`,
`# Cross-host: https://git.example.com`, `# Cross-host: https://git.example.com`,

View file

@ -1,5 +1,5 @@
{ {
"name": "@myst/shared", "name": "@firebreak/shared",
"version": "0.1.0", "version": "0.1.0",
"private": true, "private": true,
"type": "module", "type": "module",

View file

@ -1 +1 @@
export const MYST_DEFAULT_SERVICE_PORT = 4000; export const FIREBREAK_DEFAULT_SERVICE_PORT = 4000;

9
pnpm-lock.yaml generated
View file

@ -20,19 +20,10 @@ importers:
'@clack/prompts': '@clack/prompts':
specifier: ^1.2.0 specifier: ^1.2.0
version: 1.2.0 version: 1.2.0
'@myst/shared':
specifier: workspace:*
version: link:../shared
yoctocolors: yoctocolors:
specifier: ^2.1.2 specifier: ^2.1.2
version: 2.1.2 version: 2.1.2
packages/service:
dependencies:
'@myst/shared':
specifier: workspace:*
version: link:../shared
packages/shared: {} packages/shared: {}
packages: packages:

View file

@ -6,7 +6,7 @@
"lib": ["ES2022"], "lib": ["ES2022"],
"baseUrl": ".", "baseUrl": ".",
"paths": { "paths": {
"@myst/shared": ["packages/shared/src/index.ts"] "@firebreak/shared": ["packages/shared/src/index.ts"]
}, },
"strict": true, "strict": true,
"skipLibCheck": true, "skipLibCheck": true,