myst/docs/plans/2026-03-31-embargit-auth-and-deployment-design.md

136 lines
3.4 KiB
Markdown

# EmbarGit Auth and Deployment Design
This document captures current decisions about deployment topology and CLI scope for Phase 1.
## Goals
- Keep EmbarGit self-hosted and private by default.
- Expose only the read-only share-link viewer to the public internet.
- Make the CLI responsible for generating deployment files and setup scaffolding.
- Keep Phase 1 scope minimal and shippable.
## Non-Goals
- Any admin authentication layer (no Tailscale, no Pocket ID, no login screen).
- Reverse proxy generation or examples.
- Cloudflare integration or documentation.
- Replacing Forgejo.
- 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 deployment scaffolding exist.
## Core Architecture
EmbarGit has two distinct surfaces:
- Public viewer surface for read-only share links.
- Private admin and operational surface for owners/operators.
The security boundary is the public/private split, not an auth layer.
```ascii
Public internet
|
v
Read-only viewer endpoint
|
+--> Embargo/EmbarGit app
|
+--> Private Forgejo API
|
+--> Private database
Admin/operator access
|
v
Direct host or VPN (operator's responsibility)
|
v
Private admin panel
|
+--> Forgejo admin
+--> Postgres
+--> Logs / backups / host access
```
## Deployment
Single deployment mode: Docker Compose.
- EmbarGit service
- Forgejo service
- PostgreSQL service
- Network definitions for private/public separation
Admin access security is the operator's responsibility (VPN, firewall rules, etc). EmbarGit does not enforce or scaffold this in Phase 1.
## Public Viewer Rules
- Share links are public resources by design.
- Public access must be read-only.
- Public access must not expose admin routes, 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 scaffold a deployment.
### `init`
`init` should:
- prompt for domain / hostnames
- generate `.env`
- generate `docker-compose.yml`
- generate Forgejo and Embargo service defaults
### `start`, `stop`, `status`
Thin wrappers around Docker Compose.
### CLI UX
- Use spinners for long-running steps.
- Use prompts for interactive configuration.
- Keep output terse and actionable.
- Present generated files clearly after initialization.
## Configuration Outputs
Expected outputs from `init`:
- `.env`
- `docker-compose.yml`
## Data and Auth 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.
## Repo Implementation Impact
Active surfaces:
- CLI entrypoint: `packages/cli/src/index.ts`
- Command stubs: `packages/cli/src/commands/*`
- Config generators: `packages/cli/src/generators/*`
- Shared constants/types: `packages/shared/src/*`
- Service entrypoint: `packages/service/src/index.ts`
Next implementation work:
1. Make `init` generate configs via interactive prompts
2. Add a CLI prompt/spinner library
3. Expand shared types for deployment config
4. Wire the service to use the generated config
## Open Questions
- Should the public viewer be mounted at a fixed path like `/share/*` or a dedicated hostname?