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

3.4 KiB

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.

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?