@lamalibre/create-lamaste 4.0.0

package/vendor/docs/00-introduction/quickstart.md

@@ -0,0 +1,472 @@
+# Quick Start
+
+> Go from zero to your first publicly accessible tunnel in about 10 minutes, using a $4 DigitalOcean droplet and your Mac or Linux machine.
+
+## In Plain English
+
+This guide walks you through the entire process of setting up Lamaste. By the end, you will have a web app running on your machine that anyone on the internet can access through your own domain, protected by two-factor authentication.
+
+Think of it as three steps: rent a storefront (create a droplet), set up the store (run the installer), and open for business (create a tunnel). The whole process takes about as long as making a cup of coffee.
+
+## For Users
+
+> **Alternative:** If you prefer a graphical experience, the [Desktop App](../02-guides/desktop-app-setup.md) can provision a DigitalOcean droplet and set up everything automatically — no SSH required. See the [Cloud Provisioning guide](../02-guides/cloud-provisioning.md) for a step-by-step walkthrough. The guide below covers the manual SSH approach.
+
+### Prerequisites
+
+Before you start, make sure you have:
+
+| Requirement                | Details                                                                                            |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| **DigitalOcean account**   | Any cloud provider works, but this guide uses DigitalOcean. You need a fresh Ubuntu 24.04 droplet. |
+| **Domain name**            | A domain you control (e.g., `example.com`). You need access to its DNS settings.                   |
+| **Mac (or Linux machine)** | The computer running the web apps you want to expose. Must have outbound internet access.          |
+| **SSH key**                | An SSH key pair for accessing the droplet. DigitalOcean can generate one during droplet creation.  |
+| **A local web app**        | Something listening on a port — a dev server, a blog engine, any HTTP service.                     |
+
+**Cost:** $4/month for the smallest DigitalOcean droplet (512MB RAM, 1 vCPU). That is all you need.
+
+---
+
+### Step 1: Create a Droplet
+
+Log in to DigitalOcean and create a new droplet:
+
+| Setting        | Value                                      |
+| -------------- | ------------------------------------------ |
+| Image          | Ubuntu 24.04 (LTS)                         |
+| Plan           | Basic, $4/mo (512MB RAM, 1 vCPU, 10GB SSD) |
+| Region         | Closest to your users                      |
+| Authentication | SSH key (not password)                     |
+
+Wait for the droplet to boot. Note its public IP address (e.g., `203.0.113.42`).
+
+```
+Droplet created: 203.0.113.42
+```
+
+---
+
+### Step 2: Run the Installer
+
+SSH into the droplet and run the Lamaste installer:
+
+```bash
+ssh root@203.0.113.42
+```
+
+Once connected:
+
+```bash
+apt install -y npm
+npx @lamalibre/create-lamaste@4.0.0
+```
+
+The installer displays a confirmation banner showing what it will do:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Lamaste Installer                                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  This will install Lamaste on this machine.                │
+│                                                             │
+│  The following changes will be made:                         │
+│                                                             │
+│    * Reset UFW firewall (allow ports 22, 443, 9292 only)    │
+│    * Harden SSH (disable password authentication)           │
+│    * Install fail2ban, Node.js 20, nginx, certbot           │
+│    * Generate mTLS certificates for browser access          │
+│    * Create lamaste user and systemd service               │
+│    * Deploy panel to /opt/lamalibre/lamaste/                         │
+│                                                             │
+│  Designed for a fresh Ubuntu 24.04 droplet.                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Press Enter to continue. The installer runs for 2-3 minutes:
+
+```
+  ✔ Checking environment
+    ✔ Verifying root access
+    ✔ Detecting operating system → Ubuntu 24.04.1 LTS
+    ✔ Detecting IP address → 203.0.113.42
+  ✔ Hardening operating system
+    ✔ Creating swap file
+    ✔ Configuring UFW firewall
+    ✔ Installing and configuring fail2ban
+    ✔ Hardening SSH configuration
+    ✔ Installing system dependencies
+  ✔ Installing Node.js 20
+  ✔ Generating mTLS certificates
+    ✔ Creating PKI directory
+    ✔ Generating CA private key and certificate
+    ✔ Generating client key and CSR
+    ✔ Signing client certificate with CA
+    ✔ Creating PKCS12 bundle
+  ✔ Configuring nginx
+  ✔ Deploying Lamaste panel
+  ✔ Installation complete
+```
+
+At the end, a summary box appears with everything you need:
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                                                              ║
+║   Lamaste installed successfully!                           ║
+║                                                              ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                              ║
+║   1. Download your client certificate:                       ║
+║                                                              ║
+║      scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .   ║
+║                                                              ║
+║   2. Import client.p12 into your browser                     ║
+║                                                              ║
+║   3. Certificate password:                                   ║
+║                                                              ║
+║      a1b2c3d4e5f6g7h8i9j0k1l2                               ║
+║                                                              ║
+║   4. Open the Lamaste panel:                                ║
+║                                                              ║
+║      https://203.0.113.42:9292                               ║
+║                                                              ║
+║   You can now disconnect from SSH.                           ║
+║                                                              ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+### Step 3: Download the Client Certificate
+
+On your local machine (not the droplet), open a new terminal and run the SCP command from the summary:
+
+```bash
+scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .
+```
+
+This downloads `client.p12` to your current directory. This file is your admin credential — it proves to the panel that you are the owner.
+
+---
+
+### Step 4: Import the Certificate
+
+The import process varies by operating system:
+
+**macOS:**
+
+1. Double-click `client.p12`
+2. Keychain Access opens. Select the **System** keychain (not "login")
+3. Enter the certificate password from the installer summary
+4. Find the certificate in the System keychain, double-click it
+5. Expand **Trust**, set to **Always Trust**
+6. Close and enter your macOS password to confirm
+
+If you see an error about "Local Items" — ignore it. The System keychain import is what matters.
+
+**Linux (Chrome/Chromium):**
+
+1. Open Chrome Settings, then Privacy and Security, then Security
+2. Click Manage certificates, then Import
+3. Select `client.p12` and enter the password
+
+**Windows:**
+
+1. Double-click `client.p12`
+2. The Certificate Import Wizard opens
+3. Enter the password and follow the prompts
+
+After importing, **restart your browser** to ensure it picks up the new certificate.
+
+---
+
+### Step 5: Open the Admin Panel
+
+Navigate to the URL from the installer summary:
+
+```
+https://203.0.113.42:9292
+```
+
+Your browser will show two prompts:
+
+1. **Self-signed certificate warning**: Click "Advanced" then "Proceed" (this is expected — the panel uses a self-signed TLS certificate for the IP-based URL)
+2. **Client certificate selection**: Your browser asks which certificate to use. Select the Lamaste certificate you just imported.
+
+You are now in the admin panel. The onboarding wizard starts automatically.
+
+---
+
+### Step 6: Complete Onboarding
+
+The onboarding wizard has three steps:
+
+**Step 6a: Domain and Email**
+
+Enter your domain name and email address:
+
+```
+Domain:  example.com
+Email:   admin@example.com
+```
+
+The email is used for Let's Encrypt certificate notifications. The domain is where your tunneled apps will be accessible.
+
+**Step 6b: DNS Verification**
+
+The wizard shows the DNS records you need to create:
+
+```
+Type    Name              Value
+A       example.com       203.0.113.42
+A       *.example.com     203.0.113.42
+```
+
+Go to your domain registrar's DNS settings and create these records. The wildcard (`*`) record allows you to create tunnels like `app.example.com`, `blog.example.com`, etc., without adding DNS records for each one.
+
+Click "Verify DNS" in the wizard. It checks that the records resolve correctly. DNS propagation can take a few minutes — the wizard retries automatically.
+
+**Step 6c: Provisioning**
+
+Click "Provision" and watch the progress. The wizard:
+
+1. Downloads and installs Chisel (tunnel server)
+2. Downloads and installs Authelia (2FA authentication)
+3. Creates the first admin user with TOTP 2FA
+4. Issues a Let's Encrypt TLS certificate for your domain
+5. Writes nginx vhost configurations
+6. Starts all services
+
+This takes 1-2 minutes. When it finishes, onboarding is complete. The page shows your first user's TOTP QR code — scan it with Google Authenticator, Authy, or any TOTP app.
+
+---
+
+### Step 7: Enroll Your Machine as an Agent
+
+Every tunnel is carried by one **agent** — the machine that runs the app. Enroll that machine first.
+
+**Option A — Desktop App (recommended):**
+
+Install the Lamaste Desktop app, which provides a GUI with automatic service discovery and one-click tunnel creation:
+
+```bash
+npx @lamalibre/create-lamaste-desktop@4.0.0
+```
+
+The app auto-detects local services (Ollama, ComfyUI, PostgreSQL, Docker containers, etc.) and lets you expose them with one click. See the [Desktop App Setup](../02-guides/desktop-app-setup.md) guide for details.
+
+**Option B — Agent CLI (macOS, Linux servers and VMs):**
+
+In the panel, go to **Certificates → Enrollment Token** and create a token for a label such as `laptop`. Then, on the machine that runs your app, install the agent globally and run setup:
+
+```bash
+npm install -g @lamalibre/lamaste-agent@4.0.0
+LAMALIBRE_LAMASTE_ENROLLMENT_TOKEN=<token> \
+  lamaste-agent setup --label laptop --panel-url https://203.0.113.42:9292
+```
+
+Setup refuses to run from `npx`: it installs a timer that runs the installed agent every 30 seconds, and an `npx` copy can vanish from npm's cache. Setup generates the agent's key locally, prepares the Chisel client as a background service (launchd on macOS, a systemd user unit on Linux) that connects to `https://tunnel.example.com:443`, verifying the server's TLS certificate, and installs the sync timer that picks up tunnel changes from the panel. Until a tunnel is assigned to the agent the Chisel client stays stopped — it has nothing to carry. See the [Agent Setup](../02-guides/agent-setup.md) guide for details, including the one-time `loginctl enable-linger` step on headless Linux machines.
+
+---
+
+### Step 8: Create Your First Tunnel
+
+In the management panel, navigate to **Tunnels** and click **Add Tunnel**.
+
+Fill in the tunnel details:
+
+| Field       | Example      | Description                                  |
+| ----------- | ------------ | -------------------------------------------- |
+| Subdomain   | `myapp`      | Creates `myapp.example.com`                  |
+| Port        | `8001`       | The port your app listens on (on the agent)  |
+| Agent       | `laptop`     | The agent that carries the tunnel (required) |
+| Description | `My web app` | Optional label                               |
+
+Click **Add Tunnel**. The panel:
+
+1. Issues a TLS certificate for `myapp.example.com`
+2. Writes an nginx vhost for `myapp.example.com` and reloads nginx
+3. Grants the agent `laptop` — and only that agent — port 8001 on the Chisel server
+
+There is nothing to run on the agent: its sync timer picks up the new tunnel within about 30 seconds and starts the Chisel client. (To apply it at once, run `lamaste-agent update` on the agent.)
+
+The agent's Chisel client then reverse-forwards `127.0.0.1:8001` on the server to `127.0.0.1:8001` on your machine.
+
+---
+
+### Step 9: Test It
+
+Open a browser and go to:
+
+```
+https://myapp.example.com
+```
+
+You will see the Authelia login page. Log in with the credentials created during onboarding (username + TOTP code from your authenticator app).
+
+After authenticating, you see your local web app, served through the tunnel.
+
+---
+
+### Step 10: Disconnect SSH
+
+Go back to your SSH terminal and type:
+
+```bash
+exit
+```
+
+You are done with SSH. Everything from here on is managed through the browser panel at `https://203.0.113.42:9292`.
+
+If you ever need SSH again (disaster recovery, manual debugging), it is still available on port 22 with key-based authentication. But for normal operations, you will never need it.
+
+---
+
+### What You Have Now
+
+```
+Your Mac                          DigitalOcean Droplet            Internet
+┌──────────┐   WebSocket tunnel   ┌──────────────────┐          ┌─────────┐
+│ Web app  │◄────────────────────►│ nginx + Chisel   │◄─────────│ Visitors│
+│ :8001    │   (encrypted, auto-  │ + Authelia (2FA) │  HTTPS   │         │
+│          │    reconnecting)     │ + Let's Encrypt  │          │         │
+└──────────┘                      └──────────────────┘          └─────────┘
+                                  Admin: https://203.0.113.42:9292 (mTLS)
+                                  App:   https://myapp.example.com (2FA)
+```
+
+## For Developers
+
+### Installer CLI Flags
+
+The installer accepts optional flags:
+
+```bash
+npx @lamalibre/create-lamaste@4.0.0 [flags]
+```
+
+| Flag            | Effect                                          |
+| --------------- | ----------------------------------------------- |
+| `--help`, `-h`  | Print help message and exit                     |
+| `--yes`, `-y`   | Skip the confirmation prompt                    |
+| `--skip-harden` | Skip OS hardening (swap, UFW, fail2ban, SSH)    |
+| `--dev`         | Allow private/non-routable IP addresses         |
+| `--force-full`  | Run full installation even on existing installs |
+| `--uninstall`   | Print manual removal guide and exit             |
+
+The `--dev` flag is useful for testing on local VMs that do not have public IP addresses.
+
+The `--skip-harden` flag is useful when re-running the installer on a machine that was already hardened, or when you want to manage hardening separately.
+
+### Re-running the Installer
+
+The installer is idempotent. Running it again on an existing installation:
+
+- Preserves `panel.json` configuration (merges, does not overwrite)
+- Skips mTLS certificate generation if certificates already exist
+- Skips swap creation if swap is already active
+- Skips UFW configuration if all required ports are already allowed
+- Skips fail2ban if already configured and running
+- Updates lamalibre-lamaste-serverd and lamaste-server-ui files
+- Restarts the panel service
+
+This means you can safely re-run the installer after an update to the `create-lamaste` package without losing your configuration or certificates.
+
+### Development Mode
+
+For local development without a VPS:
+
+```bash
+# Terminal 1: Start panel backend
+cd packages/lamalibre-lamaste-serverd
+CONFIG_FILE=../../dev/panel.json NODE_ENV=development node src/index.js
+
+# Terminal 2: Start panel frontend (Vite dev server, proxies /api to :3100)
+cd packages/lamaste-server-ui
+npx vite
+```
+
+In development mode (`NODE_ENV=development` or `NODE_ENV` unset), the panel server skips mTLS client certificate verification, so you can access it without importing a certificate.
+
+### Troubleshooting
+
+**Browser does not prompt for certificate:**
+
+- Make sure you imported the `.p12` into the correct keychain (System on macOS)
+- Restart the browser completely (not just the tab)
+- Check that the certificate is trusted (macOS: Keychain Access, find cert, Trust, Always Trust)
+
+**Installer fails at "Detecting IP address":**
+
+- The droplet must have a public IP address
+- Use `--dev` flag for testing on private networks
+
+**DNS verification fails:**
+
+- DNS propagation can take up to 48 hours (usually minutes)
+- Verify records with `dig example.com` or `nslookup example.com`
+- Make sure you created both the `A` record and the wildcard `*.example.com` record
+
+**Panel service fails to start:**
+
+- Check logs: `journalctl -u lamalibre-lamaste-serverd -n 50`
+- Verify config: `cat /etc/lamalibre/lamaste/panel.json`
+- Check if port 3100 is in use: `ss -tlnp sport = :3100`
+
+## Quick Reference
+
+### Prerequisites Checklist
+
+```
+[ ] DigitalOcean account (or any cloud provider)
+[ ] Domain name with DNS access
+[ ] SSH key pair
+[ ] Mac or Linux machine with outbound internet
+[ ] A local web app running on some port
+```
+
+### Command Sequence
+
+```bash
+# 1. Create droplet (Ubuntu 24.04, 512MB, $4/mo)
+# 2. SSH in and install
+ssh root@203.0.113.42
+apt install -y npm
+npx @lamalibre/create-lamaste@4.0.0
+
+# 3. Download cert (from your local machine)
+scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .
+
+# 4. Import cert into browser, open panel
+#    https://203.0.113.42:9292
+
+# 5. Complete onboarding wizard (domain, DNS, provision)
+# 6. Enroll your machine as an agent (desktop app or lamaste-agent setup)
+# 7. Create tunnel in management panel, carried by that agent (applied within ~30 s)
+# 8. Visit https://myapp.example.com
+# 9. Disconnect SSH forever
+```
+
+### Time Estimates
+
+| Step                | Time                                     |
+| ------------------- | ---------------------------------------- |
+| Create droplet      | 1 minute                                 |
+| Run installer       | 2-3 minutes                              |
+| Import certificate  | 1 minute                                 |
+| Onboarding wizard   | 3-5 minutes (depends on DNS propagation) |
+| Create first tunnel | 1 minute                                 |
+| **Total**           | **~10 minutes**                          |
+
+### Related Documentation
+
+- [What is Lamaste?](./what-is-lamaste.md) — overview and use cases
+- [How It Works](./how-it-works.md) — architecture and data flow
+- [Installation Guide](../02-guides/installation.md) — detailed installation reference
+- [First Tunnel Guide](../02-guides/first-tunnel.md) — in-depth tunnel creation walkthrough
+- [Agent Setup](../02-guides/agent-setup.md) — enroll macOS and Linux agents, boot persistence
+- [Troubleshooting](../06-reference/troubleshooting.md) — common issues and solutions
+- [Glossary](../06-reference/glossary.md) — A-Z term definitions

package/vendor/docs/00-introduction/what-is-lamaste.md

@@ -0,0 +1,112 @@
+# What is Lamaste?
+
+> Lamaste is a self-hosted secure tunneling platform that exposes web apps running behind a firewall through a cheap VPS, with zero-login admin access via client certificates.
+
+## In Plain English
+
+Imagine you have a computer at home running a web app — maybe a side project, a blog engine, or an internal tool. You want people on the internet to access it, but your home network is behind a router that blocks incoming connections.
+
+The traditional solution is to rent a server in the cloud and deploy your app there. But that means maintaining a server, managing deployments, and paying for compute you might not need.
+
+Lamaste takes a different approach. You rent the cheapest possible server (a $4/month DigitalOcean droplet) and use it as a **relay**. Your home computer connects _out_ to the relay through a secure tunnel, and when someone visits your domain, the relay forwards the request back through the tunnel to your app.
+
+Think of it like a postal forwarding service. Your app stays at home, but mail gets forwarded to the right address.
+
+The clever part: after the initial 5-minute setup, you never need to SSH into the server again. Everything — domain setup, user management, certificate renewal, tunnel configuration — happens through a browser-based admin panel protected by a client certificate (like a digital ID card that your browser presents automatically).
+
+## For Users
+
+Lamaste solves the problem of exposing local services to the internet securely. Here is what you get:
+
+**What it does:**
+
+- Exposes local web apps (any port) through HTTPS on your own domain
+- Protects each app with TOTP two-factor authentication (Google Authenticator, Authy, etc.)
+- Manages TLS certificates automatically via Let's Encrypt
+- Provides a browser-based admin panel for everything — no SSH needed after setup
+
+**What you need:**
+
+- A Mac (or Linux machine) running the web apps you want to expose
+- A $4/month DigitalOcean droplet (Ubuntu 24.04, 512MB RAM)
+- A domain name (or use a managed subdomain)
+
+**How setup works:**
+
+**Option A: Manual setup (SSH)**
+
+1. Create a fresh Ubuntu 24.04 droplet on DigitalOcean
+2. SSH in once and run `npx @lamalibre/create-lamaste@4.0.0`
+3. Download the client certificate it prints
+4. Import the certificate into your browser
+5. Open `https://<droplet-ip>:9292` — you are in the admin panel
+6. Complete the onboarding wizard (domain, DNS, stack provisioning)
+7. Create tunnels, add users, manage everything from the browser
+8. Disconnect SSH. You never need it again.
+
+**Option B: Desktop app cloud provisioning**
+
+1. Install the desktop app (`npx @lamalibre/create-lamaste-desktop@4.0.0`)
+2. Go to the Servers tab and click "Create a new server"
+3. Enter your DigitalOcean API token — the app validates scopes and stores it securely in your OS credential store
+4. Pick a region (the app measures latency to each) and a domain name
+5. Click "Provision" — the app creates the droplet, installs Lamaste, downloads your certificate, and connects automatically
+6. Manage everything from the desktop app or the browser panel
+
+See the [Cloud Provisioning guide](../02-guides/cloud-provisioning.md) for a detailed walkthrough.
+
+**Key design choices:**
+
+- The admin panel always works via IP address (`:9292`), even if your domain goes down
+- Client certificate authentication means zero-login — your browser proves identity at the TLS level
+- All services run on the cheapest possible VPS (512MB RAM budget, carefully tuned)
+
+## For Developers
+
+Lamaste is a monorepo with several packages:
+
+| Package                     | Technology                 | Purpose                                                               |
+| --------------------------- | -------------------------- | --------------------------------------------------------------------- |
+| `create-lamaste`            | Node.js ESM, Listr2, execa | Zero-prompt installer CLI                                             |
+| `lamalibre-lamaste-serverd` | Fastify 5, Node.js ESM     | REST API + WebSocket backend                                          |
+| `lamaste-server-ui`         | React 18, Vite, Tailwind   | Management UI (SPA) + shared admin components for desktop             |
+| `lamaste-agent`             | Node.js ESM                | Tunnel agent CLI (macOS & Linux)                                      |
+| `lamaste-desktop`           | Tauri v2 (Rust + React)    | Desktop app with service discovery, multi-server & cloud provisioning |
+| `lamaste-agent-ui`          | React 18                   | Shared agent UI (pages, context, components) for desktop agent mode   |
+| `create-lamaste-desktop`    | Node.js ESM                | npx installer for the desktop app                                     |
+| `lamaste-tickets`           | TypeScript, undici         | SDK for agent-to-agent authorization                                  |
+| `lamaste-cloud`             | TypeScript, undici         | Cloud provider abstraction for server provisioning                    |
+
+**Architecture summary:**
+
+```
+Internet → nginx (TLS + mTLS) → Panel Server (Fastify, :3100)
+                               → Authelia (TOTP 2FA, :9091)
+                               → Chisel Server (WebSocket tunnels, :9090)
+                                    ↑
+                               Chisel Client (on your machine, auto-reconnect)
+                                    ↑
+                               Your local web app (:8001, :3000, etc.)
+```
+
+All backend services bind `127.0.0.1` only — nginx is the sole public-facing service. The panel is protected by mTLS (client certificates), while tunneled apps are protected by Authelia (TOTP 2FA).
+
+State is stored in JSON files (`/etc/lamalibre/lamaste/panel.json`, `tunnels.json`) with atomic writes (write to temp → fsync → rename). No database is needed at this scale.
+
+The installer (`npx @lamalibre/create-lamaste@4.0.0`) is completely non-interactive — it detects the environment, provisions everything, and prints a summary. All configuration happens through the browser-based onboarding wizard after installation.
+
+## Quick Reference
+
+| Item                 | Value                           |
+| -------------------- | ------------------------------- |
+| **Minimum VPS**      | 512MB RAM, Ubuntu 24.04         |
+| **Install command**  | `npx @lamalibre/create-lamaste@4.0.0` |
+| **Admin panel**      | `https://<ip>:9292` (mTLS)      |
+| **Auth for admin**   | Client certificate (zero-login) |
+| **Auth for apps**    | TOTP 2FA via Authelia           |
+| **Tunnel protocol**  | WebSocket-over-HTTPS (Chisel)   |
+| **TLS certificates** | Let's Encrypt (auto-renewing)   |
+| **State storage**    | JSON files (no database)        |
+| **RAM usage**        | ~245MB total (all services)     |
+| **npm package**      | `@lamalibre/create-lamaste@4.0.0`     |
+| **License**          | Polyform Noncommercial 1.0.0    |