Replace manual .env configuration with a browser-based setup wizard. New users deploy with `docker compose up` and configure Forgejo OAuth credentials through /setup on first visit. Existing users can reconfigure via the same page (auth-gated post-setup). Key changes: Rename (Myst → Firebreak): - Config fields, env vars, session cookie, templates, docker-compose, README all renamed from Myst to Firebreak Setup wizard (/setup): - New AppSettings single-row DB table stores Forgejo config - Auto-generates Fernet encryption key on first setup - SetupRequiredMiddleware redirects all routes to /setup pre-config - Reconfigure mode pre-fills existing values, requires auth - Landing page links to /setup for recovery if OAuth breaks Settings page (/settings): - PAT registration moved out of dashboard into dedicated page - Token card with registration date, delete, and update actions - Dashboard shows CTA linking to settings when no PAT registered Auth updates: - Routes use AppSettings from DB instead of env-based Settings - OAuth callback redirects new users to /settings for PAT setup - Forgejo API errors no longer leak upstream response bodies - Decrypt failures return actionable 503 instead of unhandled 500 Code quality: - Extracted templating.py to eliminate circular import hacks - AppSettings.get_fernet() caches Fernet cipher instance - User.has_pat property replaces scattered None checks - lookup_session promoted to public API - Dead code removed, return type annotations added - PAT input fields use type="password" - CSRF gap documented in agents.md for future addressing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| .vscode | ||
| .zed | ||
| docs | ||
| examples | ||
| packages | ||
| web | ||
| .dockerignore | ||
| .gitignore | ||
| agents.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.base.json | ||
| tsconfig.json | ||
Firebreak
Fight fire with fire. Your code. Your rules.
Firebreak is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.
System Diagram
This diagram shows how traffic moves through the public internet, the VPS or self-hosted server, the host firewall, the platform router, Firebreak, Forgejo, and Postgres.
Click the diagram to open the full-size SVG.
Features
Two Link Types
| Type | Verification | Use Case |
|---|---|---|
| Private | Email verification code required | Share with specific individuals |
| Public | No verification, time-expired | Job applications, portfolios |
Security
- Links pinned to immutable
commit_sha— not moving branches - Email verification prevents unauthorized access
- Time-expiration and revocation give owners control
- No public repo listing — anti-scraping by design
- Admin access protected upstream (Tailscale, VPN, Cloudflare Access)
Authentication
| Purpose | Method |
|---|---|
| User Identity | Forgejo OAuth |
| Data Access | User's Forgejo PAT |
Tech Stack
- Backend: Python + FastAPI
- Frontend: Jinja2 templates + HTMX (no build step)
- Database: PostgreSQL
HTMX provides interactivity (filtering, form submissions) with minimal JavaScript. Jinja2 handles server-side rendering for fast page loads.
Quick Start
1. Deploy with Docker Compose
docker compose up -d
2. Run the Setup Wizard
Open http://localhost:8000 in your browser. On first boot, Firebreak redirects to a setup wizard where you configure:
- Forgejo instance URL — where your Forgejo server lives
- OAuth credentials — register an OAuth application in Forgejo first (Settings → Applications → Create OAuth2 Application), then paste the Client ID and Client Secret
- Public base URL (optional) — your production domain for OAuth redirects
The setup wizard auto-generates an encryption key for token storage.
3. Sign In and Register Your Token
After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a read:repository-scoped Personal Access Token (PAT) to enable share link viewing.
4. Alternative Deployments
For non-Docker deployments, supply DATABASE_URL yourself:
- VPS deployment: Hostinger or another VPS with Dokploy, Traefik, UFW, Firebreak, Forgejo, and a shared Postgres instance that contains separate
forgejoandfirebreakdatabases. - Self-hosted server deployment: a home server, mini PC, NAS, or other self-hosted Linux machine running Firebreak with Docker, Podman, Docker Compose, Coolify, Caddy, Nginx, or another reverse proxy.
Firebreak should not assume a VPS-only environment. The requirement is an existing Forgejo instance, Firebreak's own database, and a way to route the public and admin hostnames to the Firebreak app.
Phase 1 Progress
- Project renamed from Embargo to Firebreak
- CLI scaffold (
firebreak config init) - Config generation (
.env) - Service foundation (FastAPI + PostgreSQL)
firebreak config verify— verify Forgejo connectivityfirebreak config verify --diagnostic— comprehensive diagnosticsfirebreak config view— show current config- Forgejo OAuth authentication
- Repo ownership verification
- Private link creation (email-verified)
- Public link creation (time-expired)
- Web-based code viewer
- User dashboard
- SMTP configuration UI
- Access logs