@lamalibre/create-lamaste 4.0.0

package/vendor/docs/06-reference/glossary.md

@@ -0,0 +1,528 @@
+# Glossary
+
+> A-Z definitions of every term used in Lamaste documentation, each explained at three levels of depth.
+
+## In Plain English
+
+This page is a dictionary for Lamaste. Every technical term you encounter in the documentation is defined here. Each entry has three parts:
+
+- **Plain English**: A non-technical explanation anyone can understand
+- **Technical**: The precise definition for developers
+- **Where it appears**: Where you encounter this term in Lamaste
+
+If you are reading documentation and hit an unfamiliar term, this is the place to look.
+
+---
+
+## Terms
+
+### Agent
+
+**Plain English:** A machine you have connected to your Lamaste server — a laptop, a build server, a VM. The agent holds the actual apps; the server only relays visitors to it.
+
+**Technical:** A machine enrolled with an agent certificate (`CN=agent:<label>`) that runs the Chisel client as a user-level service (a LaunchAgent on macOS, a systemd user unit on Linux), set up with `lamaste-agent setup` or the Desktop App. Every tunnel belongs to exactly one agent (its `agentLabel`); the agent is told only about its own tunnels, and the Chisel authfile lets its `agent-<label>` user bind only those tunnels' ports.
+
+**Where it appears:**
+
+- Enrolled from the panel (**Certificates → Enrollment Token**) and `lamaste-agent setup` (installed globally with `npm install -g @lamalibre/lamaste-agent@4.0.0`)
+- Agent registry: `/etc/lamalibre/lamaste/agents.json` on the server; `~/.lamalibre/lamaste/agents/<label>/` on the agent
+- The **Agent** column and field on the panel's Tunnels page
+
+---
+
+### Atomic Write
+
+**Plain English:** A way of saving a file that guarantees it is either fully saved or not saved at all — never half-written.
+
+**Technical:** A write pattern where data is first written to a temporary file (`.tmp`), flushed to disk (`fsync`), and then renamed over the target file. The `rename` system call is atomic on POSIX filesystems, so readers never see a partially written file. This prevents corruption if the process crashes mid-write.
+
+**Where it appears:** Lamaste uses atomic writes for `panel.json`, `tunnels.json`, and Authelia's `users.yml`. This is critical because Authelia reads `users.yml` on every authentication request — a half-written file would break login.
+
+---
+
+### Authelia
+
+**Plain English:** The bouncer at the door of your tunneled apps. When someone visits your app through the tunnel, Authelia asks for a username and a time-based code from their phone before letting them in.
+
+**Technical:** Authelia is a lightweight open-source authentication server written in Go. It implements forward authentication — nginx delegates auth decisions to Authelia before proxying requests to the backend. Lamaste uses Authelia's file-based user store (`users.yml`) with bcrypt password hashing and TOTP (Time-based One-Time Password) for two-factor authentication. It runs as a systemd service under its own unprivileged account (`lamaste-authelia`), binding `127.0.0.1:9091`, and uses approximately 25MB of RAM. The installer installs a pinned release (4.39.28, SHA-256 verified); onboarding writes its configuration and starts it.
+
+**Where it appears:**
+
+- Installed during the onboarding provisioning step
+- Manages user authentication for all tunneled apps on port 443
+- Users are created and managed through the panel's Users page
+- Configuration lives at `/etc/authelia/configuration.yml`
+- User database lives at `/etc/authelia/users.yml`
+
+---
+
+### bcrypt
+
+**Plain English:** A way of scrambling passwords so that even if someone steals the password file, they cannot figure out the original passwords.
+
+**Technical:** A password hashing function based on the Blowfish cipher. It is intentionally slow (configurable cost factor) to resist brute-force attacks. Each hash uses approximately 4KB of RAM. Lamaste mandates bcrypt over argon2id because argon2id uses ~93MB per hash, which causes out-of-memory kills on the 512MB droplet.
+
+**Where it appears:**
+
+- Authelia's `users.yml` stores bcrypt-hashed passwords
+- The panel server generates bcrypt hashes when creating or updating users
+- This is a hard constraint — argon2id must never be used on the 512MB droplet
+
+---
+
+### CA (Certificate Authority)
+
+**Plain English:** A trusted stamp-maker. The CA creates a master stamp, and any certificate it stamps is considered trustworthy. In Lamaste, the CA is self-created and exists only on your droplet.
+
+**Technical:** A Certificate Authority issues and signs digital certificates. Lamaste generates a self-signed CA during installation (4096-bit RSA key, 10-year validity) stored at `/etc/lamalibre/lamaste/pki/ca.key` and `/etc/lamalibre/lamaste/pki/ca.crt`. This CA signs client certificates for mTLS admin authentication. nginx is configured to trust only certificates signed by this CA. The CA is distinct from Let's Encrypt, which is used for public-facing TLS.
+
+**Where it appears:**
+
+- Generated by the installer's mTLS certificate task
+- Referenced in `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf` as `ssl_client_certificate`
+- Used to sign client certificates for admin panel access
+- Can issue additional client certificates through the panel's Certificates page
+
+---
+
+### certbot
+
+**Plain English:** A robot that automatically gets and renews free HTTPS certificates from Let's Encrypt, so your domain shows the padlock icon in browsers.
+
+**Technical:** The official ACME client for Let's Encrypt. Lamaste uses certbot with the nginx plugin (`python3-certbot-nginx`) to obtain and auto-renew TLS certificates for the configured domain and its wildcard subdomains. Certificates are stored in `/etc/letsencrypt/`. A systemd timer (`certbot.timer`) runs renewal checks twice daily.
+
+**Where it appears:**
+
+- Installed by the installer as a system package
+- Runs during onboarding provisioning to issue the first certificate
+- Auto-renews via `certbot.timer` systemd timer
+- Monitored on the panel's Certificates page
+
+---
+
+### Chisel
+
+**Plain English:** A program that creates a secret tunnel between your machine and the droplet. Web traffic goes through this tunnel disguised as normal HTTPS traffic, so firewalls and ISP filters do not block it.
+
+**Technical:** Chisel is an open-source tunneling tool written in Go that creates TCP tunnels over WebSocket connections. In Lamaste, the Chisel server runs on the droplet (binding `127.0.0.1:9090`) and the Chisel client runs on your machine (macOS or Linux). The tunnel is established as a WebSocket upgrade inside a standard HTTPS connection, making it indistinguishable from normal web traffic to deep packet inspection (DPI) systems. The server uses approximately 20MB of RAM.
+
+**Where it appears:**
+
+- Server binary: `/usr/local/bin/chisel`; agent binary: `~/.lamalibre/lamaste/bin/chisel`
+- Pinned to Chisel 1.12.0 on server and agents, verified against a pinned SHA-256; any other version is replaced (on the server by the installer, on agents by their sync)
+- Server systemd unit: `chisel.service` (`User=nobody`, `Group=lamaste-chisel`)
+- Installed on the server by `create-lamaste`; started during onboarding provisioning
+- Client runs on each agent (launchd on macOS, a systemd user unit on Linux) and verifies the server's TLS certificate
+- Authfile `/etc/lamalibre/lamaste/chisel-users` grants each agent only the ports of the tunnels it carries
+- Re-rendered when tunnels or agents change; Chisel reloads it for additions and is restarted for revocations
+
+---
+
+### Client Certificate
+
+**Plain English:** A digital ID card that lives in your browser. When you visit the admin panel, your browser shows this ID card to prove you are the admin. No username or password needed — the ID card is the proof.
+
+**Technical:** An X.509 certificate installed in the browser's certificate store. During TLS handshake, the server requests the client's certificate (`ssl_verify_client on`), and the browser presents it. If the certificate is signed by the trusted CA, the connection proceeds. If not, the TLS handshake fails before any HTTP traffic occurs. Lamaste generates a PKCS12 (`.p12`) bundle containing the client certificate, private key, and CA certificate for easy browser import.
+
+**Where it appears:**
+
+- Generated during installation as `/etc/lamalibre/lamaste/pki/client.p12`
+- Imported into the admin's browser during setup
+- Verified by nginx on every request to port 9292
+- Rotated on the server with `sudo lamaste-server reset-admin` (the panel does not issue admin certificates)
+
+See also: [mTLS](#mtls-mutual-tls), [CA](#ca-certificate-authority), [PKCS12](#pkcs12)
+
+---
+
+### DNS (Domain Name System)
+
+**Plain English:** The internet's phone book. When you type `example.com` in your browser, DNS looks up the phone number (IP address) of the server that hosts that domain.
+
+**Technical:** A hierarchical naming system that translates human-readable domain names to IP addresses. Lamaste requires two DNS records: an `A` record for the base domain and a wildcard `A` record (`*.example.com`) pointing to the droplet's IP. The wildcard allows creating tunnels like `app.example.com` without adding individual DNS records for each subdomain.
+
+**Where it appears:**
+
+- Configured during the onboarding DNS verification step
+- The panel verifies DNS resolution before proceeding with provisioning
+- Required records: `A example.com → <droplet-ip>` and `A *.example.com → <droplet-ip>`
+
+---
+
+### Droplet
+
+**Plain English:** DigitalOcean's name for a virtual server in the cloud. Lamaste uses the cheapest one available as a relay point.
+
+**Technical:** A virtual machine instance on DigitalOcean's infrastructure. Lamaste requires the $4/month tier (512MB RAM, 1 vCPU, 10GB SSD) running Ubuntu 24.04 LTS. While DigitalOcean is the reference platform, Lamaste works on any VPS provider with a public IP and Ubuntu 24.04.
+
+**Where it appears:**
+
+- Created by the user as the first step of setup
+- Hosts all Lamaste server-side components
+- Referenced throughout documentation as "the droplet" or "the VPS"
+
+---
+
+### execa
+
+**Plain English:** A helper library that lets Node.js run system commands (like `nginx -t` or `systemctl restart`) in a safe, reliable way.
+
+**Technical:** A Node.js library for executing external processes. It replaces `child_process.exec/spawn` with a promise-based API, proper error handling, and array-based argument passing (preventing shell injection). Lamaste uses execa exclusively for all system command execution — `child_process` is never used directly.
+
+**Where it appears:**
+
+- Used throughout `create-lamaste` installer tasks
+- Used in `lamalibre-lamaste-serverd` business logic (`lib/`) for nginx, certbot, systemctl operations
+- Always called with array arguments: `execa('nginx', ['-t'])`, never string interpolation
+
+---
+
+### fail2ban
+
+**Plain English:** A security guard that watches log files. If someone tries to guess passwords too many times, fail2ban blocks their IP address for an hour.
+
+**Technical:** An intrusion prevention framework that monitors log files for patterns indicating brute-force attacks and temporarily bans offending IP addresses using firewall rules. Lamaste configures two jails: `sshd` (monitors `/var/log/auth.log`) and `nginx-http-auth` (monitors `/var/log/nginx/error.log`). Both jails ban IPs for 3600 seconds (1 hour) after 5 failed attempts. Uses approximately 35MB of RAM.
+
+**Where it appears:**
+
+- Installed and configured during the installer's hardening step
+- Configuration: `/etc/fail2ban/jail.d/lamaste.conf`
+- Runs as a systemd service: `fail2ban.service`
+
+---
+
+### Fastify
+
+**Plain English:** The engine that powers the Lamaste admin panel's backend. It receives requests from your browser and responds with data, like a restaurant kitchen receiving orders and sending out dishes.
+
+**Technical:** A high-performance Node.js web framework. Lamaste uses Fastify for the panel server REST API because it provides built-in schema validation (used with Zod), native WebSocket support (for live log streaming), and a structured plugin system. The panel server binds to `127.0.0.1:3100` and is accessed only through the nginx reverse proxy. Routes handle HTTP concerns only; business logic lives in `lib/` modules.
+
+**Where it appears:**
+
+- Panel server entry point: `packages/lamaste-serverd/src/index.js`
+- Routes: `packages/lamaste-serverd/src/routes/`
+- Business logic: `packages/lamaste-serverd/src/lib/`
+- Runs as the `lamalibre-lamaste-serverd` systemd service
+
+---
+
+### Forward Auth
+
+**Plain English:** A security checkpoint. Before nginx lets a visitor reach your app, it first asks Authelia: "Is this person allowed in?" If Authelia says no, the visitor sees a login page instead of your app.
+
+**Technical:** An authentication pattern where the reverse proxy (nginx) makes a subrequest to an authentication service before proxying the original request. If the auth service returns a success status code (2xx), nginx proceeds with the proxy. If it returns a 401/403, nginx redirects the client to a login page. nginx implements this with the `auth_request` directive pointing to Authelia's `/api/verify` endpoint.
+
+**Where it appears:**
+
+- Configured in nginx vhost files for tunneled apps (port 443)
+- Authelia handles the verification at `127.0.0.1:9091`
+- Not used for the admin panel (which uses mTLS instead)
+
+---
+
+### FQDN (Fully Qualified Domain Name)
+
+**Plain English:** The complete address of a website, including all its parts. Like a full postal address compared to just a street name.
+
+**Technical:** A domain name that specifies its exact location in the DNS hierarchy, including all labels up to the root. For example, `myapp.example.com.` is an FQDN (the trailing dot is the root, often omitted). In Lamaste, each tunnel gets an FQDN like `myapp.example.com` that resolves to the droplet's IP through the wildcard DNS record.
+
+**Where it appears:**
+
+- Each tunnel creates a subdomain FQDN (e.g., `myapp.example.com`)
+- Used in nginx vhost `server_name` directives
+- Used in Let's Encrypt certificate Subject Alternative Names
+
+---
+
+### launchd
+
+**Plain English:** The macOS system that automatically starts programs when your Mac boots up and restarts them if they crash. Lamaste uses it to keep the tunnel client running permanently.
+
+**Technical:** The macOS init system and service manager (equivalent to systemd on Linux). `lamaste-agent setup` (or the Desktop App) writes a per-agent LaunchAgent property list (`.plist`) for the Chisel client that starts it at login, restarts it on failure, and runs it in the background. The plist carries the agent's Chisel credential in `EnvironmentVariables`, so it is written with mode 0600.
+
+**Where it appears:**
+
+- Generated by `lamaste-agent setup` / `update` (implementation in `@lamalibre/lamaste@4.0.0/agent`)
+- Installed to `~/Library/LaunchAgents/com.lamalibre.lamaste.chisel-<label>.plist` on the agent
+- Manages the Chisel client process lifecycle
+
+---
+
+### Let's Encrypt
+
+**Plain English:** A free service that gives your domain an official HTTPS certificate, so browsers show the padlock icon and trust your site. Certificates renew automatically every 90 days.
+
+**Technical:** A nonprofit Certificate Authority providing free, automated TLS certificates via the ACME protocol. Lamaste uses Let's Encrypt through certbot to issue certificates for the configured domain and wildcard subdomains. Certificates have a 90-day validity period and are auto-renewed by the `certbot.timer` systemd timer. Let's Encrypt certificates are used for public-facing port 443 traffic; the admin panel on port 9292 uses a self-signed certificate instead.
+
+**Where it appears:**
+
+- Certificates issued during onboarding provisioning
+- Stored in `/etc/letsencrypt/live/<domain>/`
+- Referenced in nginx vhost configurations for port 443
+- Monitored on the Certificates management page
+- Auto-renewed by `certbot.timer`
+
+---
+
+### Listr2
+
+**Plain English:** A library that shows progress bars and checkmarks in the terminal while the installer runs, so you can see what is happening at each step.
+
+**Technical:** A Node.js library for building terminal task lists with nested subtasks, progress indicators, and concurrent execution support. The Lamaste installer uses Listr2 to orchestrate all installation tasks in a visually structured pipeline. Each task can have skip guards (for idempotency) and persistent output messages.
+
+**Where it appears:**
+
+- Used exclusively in `create-lamaste` (`packages/create-lamaste/src/index.js`)
+- Each installer phase is a Listr2 task with nested subtasks
+- Task files in `packages/create-lamaste/src/tasks/` return Listr2 subtask arrays
+
+---
+
+### mTLS (Mutual TLS)
+
+**Plain English:** A two-way ID check. Normally, only the website proves its identity to your browser (one-way TLS). With mTLS, your browser also proves its identity to the website using a client certificate. It is like both people showing ID at a door, not just the person entering.
+
+**Technical:** Mutual Transport Layer Security extends standard TLS by requiring both parties to present certificates during the handshake. In Lamaste, nginx on port 9292 is configured with `ssl_verify_client on`, meaning the TLS handshake fails before any HTTP traffic if the client does not present a valid certificate signed by the Lamaste CA. This provides authentication at the transport layer — there is no login form to brute-force, no session cookies to steal, and no credentials transmitted over the wire.
+
+**Where it appears:**
+
+- Configured in `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`
+- Enforced on the admin panel vhost (port 9292)
+- Client certificates generated during installation and importable as `.p12` files
+- LXD (the Linux container manager) uses the same pattern, which inspired Lamaste's approach
+
+See also: [Client Certificate](#client-certificate), [CA](#ca-certificate-authority)
+
+---
+
+### nginx
+
+**Plain English:** The traffic director. nginx sits at the front door of the droplet and decides where each request goes — admin panel requests go to the panel server, app requests go through the tunnel, and everything else gets blocked.
+
+**Technical:** A high-performance HTTP reverse proxy, load balancer, and web server. In Lamaste, nginx is the only process binding to public ports. It handles TLS termination (both Let's Encrypt and self-signed), mTLS client certificate verification, forward authentication with Authelia, WebSocket upgrades for Chisel and the panel API, and static file serving. It uses approximately 15MB of RAM.
+
+**Where it appears:**
+
+- Installed by the installer as a system package
+- Listens on port 443 (tunnel vhosts) and port 9292 (admin panel)
+- Vhost files: `/etc/nginx/sites-available/lamaste-*`
+- mTLS snippet: `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`
+- Always validated with `nginx -t` before reloading
+
+---
+
+### Onboarding
+
+**Plain English:** The setup wizard that runs the first time you open the admin panel. It walks you through connecting your domain and installing the remaining components.
+
+**Technical:** A multi-step wizard in the panel UI that transitions the system from `FRESH` state to `COMPLETED` state. The onboarding flow is: domain input, DNS verification, stack provisioning (starting Chisel, configuring Authelia — both installed beforehand by `create-lamaste` — certbot, nginx vhosts). Onboarding API endpoints are guarded by an onboarding middleware — they return `410 Gone` after completion, while management endpoints return `503 Service Unavailable` before completion.
+
+**Where it appears:**
+
+- Panel client: `packages/lamaste-server-ui/src/pages/onboarding/`
+- Panel server routes: `packages/lamaste-serverd/src/routes/onboarding/`
+- State tracked in `panel.json` under `onboarding.status`
+- States: `FRESH` → `DOMAIN_SET` → `DNS_READY` → `PROVISIONING` → `COMPLETED`
+
+---
+
+### PKCS12
+
+**Plain English:** A file format (ending in `.p12`) that bundles a certificate and its private key together in one password-protected file. It is the format browsers understand for importing client certificates.
+
+**Technical:** A binary archive format (also known as PFX) defined by RFC 7292 for storing a private key, certificate, and optionally the CA certificate chain, all encrypted with a password. Lamaste generates the `.p12` bundle using OpenSSL with legacy-compatible encryption (`PBE-SHA1-3DES`) and MAC algorithm (`sha1`) to ensure compatibility with macOS Keychain, which does not support newer encryption modes for PKCS12 import.
+
+**Where it appears:**
+
+- Generated during installation at `/etc/lamalibre/lamaste/pki/client.p12`
+- Password stored at `/etc/lamalibre/lamaste/pki/.p12-password` (mode 0600)
+- Downloaded by the admin via SCP after installation
+- Imported into the browser for mTLS authentication
+
+---
+
+### Panel (Panel Server / Panel Client)
+
+**Plain English:** The admin control center. The panel server is the backend brain that manages everything, and the panel client is the visual interface you see in your browser.
+
+**Technical:** The panel consists of two packages. The **panel server** is a Fastify REST API running as the `lamalibre-lamaste-serverd` systemd service, binding `127.0.0.1:3100`. It handles all business logic: nginx vhost management, Chisel tunnel configuration, Authelia user management, certbot operations, and system monitoring. The **panel client** is a React 18 SPA built with Vite and Tailwind CSS, served as static files from `/opt/lamalibre/lamaste/lamaste-server-ui/dist/`. It communicates with the panel server via `/api/*` routes proxied through nginx.
+
+**Where it appears:**
+
+- Server: `packages/lamaste-serverd/`, deployed to `/opt/lamalibre/lamaste/lamaste-serverd/`
+- Client: `packages/lamaste-server-ui/`, built to `/opt/lamalibre/lamaste/lamaste-server-ui/dist/`
+- Accessible at `https://<ip>:9292` (through nginx mTLS proxy)
+
+---
+
+### TOTP (Time-based One-Time Password)
+
+**Plain English:** The six-digit code that changes every 30 seconds on your phone (in apps like Google Authenticator or Authy). It is the second factor in two-factor authentication — even if someone knows your password, they also need your phone.
+
+**Technical:** An algorithm defined in RFC 6238 that generates short-lived codes from a shared secret and the current time. The server and the client (authenticator app) independently compute the same code because they share the same secret and clock. Lamaste uses TOTP through Authelia for all tunneled app authentication. The shared secret is provisioned via QR code during user creation.
+
+**Where it appears:**
+
+- Authelia manages TOTP enrollment and verification
+- QR codes shown during onboarding completion and user creation in the panel
+- Used for logging into tunneled apps (not the admin panel, which uses mTLS)
+
+---
+
+### Sync Timer
+
+**Plain English:** A small scheduled job on every agent that checks with the panel every 30 seconds and adjusts the tunnel client when the agent's tunnels changed — so tunnels created, disabled or moved in the panel reach the agent without anyone running a command on it.
+
+**Technical:** Runs `lamaste-agent sync --label <label>`, which fetches `GET /api/tunnels/agent-config` and converges the agent's Chisel client with it (relay URL, credential, pinned binary, granted remotes, running or stopped). It exists because Chisel rejects a client's whole session when one requested remote is not granted: an agent must drop a revoked tunnel promptly or all its other tunnels go dark. Requires a global install of `@lamalibre/lamaste-agent@4.0.0`.
+
+**Where it appears:**
+
+- Linux: systemd user service + timer `lamalibre-lamaste-sync-<label>`
+- macOS: LaunchAgent `com.lamalibre.lamaste.sync-<label>` (`StartInterval` 30)
+- Log `~/.lamalibre/lamaste/agents/<label>/logs/sync.log`, state `sync-state.json`, the **Sync** line of `lamaste-agent status`
+- Installed by `lamaste-agent setup` and `update`
+
+---
+
+### Tunnel
+
+**Plain English:** A private passage between your machine and the droplet. Web traffic travels through this passage so your local app is accessible from the internet, even though your machine is behind a firewall.
+
+**Technical:** A reverse TCP tunnel established by the Chisel client connecting outbound from your machine to the Chisel server on the droplet via a WebSocket-over-HTTPS connection. The "reverse" means the server-side port is forwarded to the client-side port. Each tunnel maps a subdomain (e.g., `myapp.example.com`) to a port on one agent's loopback (e.g., `127.0.0.1:8001`) and is carried by exactly that agent. The tunnel is persistent — the Chisel client automatically reconnects on network interruptions.
+
+**Where it appears:**
+
+- Created and managed through the panel's Tunnels page
+- Definitions stored in `/etc/lamalibre/lamaste/tunnels.json`
+- Each tunnel gets an nginx vhost (with its own `client_max_body_size`) and a Chisel port grant for its agent
+- Client-side managed by the carrying agent's Chisel client (launchd on macOS, systemd user unit on Linux)
+
+---
+
+### UFW (Uncomplicated Firewall)
+
+**Plain English:** A lock on the droplet's doors. UFW closes all doors except the three Lamaste needs: SSH (port 22), web traffic (port 443), and the admin panel (port 9292). Everything else is blocked.
+
+**Technical:** A frontend for Linux's iptables/nftables firewall. Lamaste configures UFW to deny all incoming traffic by default and allow only four ports: 22/tcp (SSH), 80/tcp (Let's Encrypt HTTP-01 challenges; every other request is redirected to HTTPS), 443/tcp (HTTPS for tunneled apps), and 9292/tcp (admin panel). Outgoing traffic is unrestricted (needed for package updates, Let's Encrypt validation, etc.).
+
+**Where it appears:**
+
+- Configured during the installer's hardening step
+- Rules: `ufw allow 22/tcp`, `ufw allow 443/tcp`, `ufw allow 9292/tcp`
+- Status viewable with `ufw status`
+
+---
+
+### Vhost (Virtual Host)
+
+**Plain English:** A way for nginx to serve different websites from the same server. Each tunnel gets its own vhost, so `blog.example.com` and `app.example.com` are handled differently even though they share the same IP address.
+
+**Technical:** An nginx `server` block that matches requests by `server_name` (the `Host` header). Lamaste creates one vhost per tunnel at `/etc/nginx/sites-available/lamalibre-lamaste-app-<subdomain>` and symlinks it to `/etc/nginx/sites-enabled/`. The admin panel also has its own vhost at `/etc/nginx/sites-available/lamalibre-lamaste-panel-ip`. After any vhost change, the panel server runs `nginx -t` to validate the configuration before reloading — if validation fails, the change is rolled back.
+
+**Where it appears:**
+
+- Created automatically when tunnels are added through the panel
+- Files: `/etc/nginx/sites-available/lamaste-*`
+- Enabled via symlinks in `/etc/nginx/sites-enabled/`
+- Always validated with `nginx -t` before activation
+
+---
+
+### WebSocket
+
+**Plain English:** A persistent two-way communication channel between a browser (or program) and a server. Unlike normal web requests where you ask and get a response, a WebSocket stays open so both sides can send messages at any time.
+
+**Technical:** A protocol defined in RFC 6455 that provides full-duplex communication over a single TCP connection, initiated via an HTTP upgrade handshake. Lamaste uses WebSockets in two places: (1) Chisel tunnels use WebSocket-over-HTTPS to carry TCP traffic between the local client and the droplet server, and (2) the panel server uses WebSockets for real-time features like live log streaming and provisioning progress. The key advantage of WebSocket-over-HTTPS for tunneling is that it is indistinguishable from normal web traffic, bypassing DPI and corporate firewalls.
+
+**Where it appears:**
+
+- Chisel client-server communication (tunnel data transport)
+- Panel server API (live log streaming, provisioning progress)
+- nginx is configured with `proxy_http_version 1.1` and `Upgrade` headers to support WebSocket proxying
+
+---
+
+### Zod
+
+**Plain English:** A validation library that checks whether incoming data has the right shape and type before the server processes it. Like a form that rejects submissions with missing fields.
+
+**Technical:** A TypeScript-first schema validation library. Lamaste uses Zod at the Fastify route level to validate all incoming API request bodies, query parameters, and URL parameters. Schemas are defined inline in route files and used with Fastify's schema-first validation hooks. This ensures that business logic in `lib/` modules receives well-typed, validated data.
+
+**Where it appears:**
+
+- Used in `packages/lamaste-serverd/src/routes/` for request validation
+- Every API endpoint validates inputs before processing
+- Error responses follow a consistent `{ error: string }` format for validation failures
+
+---
+
+## Quick Reference
+
+### Alphabetical Index
+
+| Term                                                         | One-Line Summary                                              |
+| ------------------------------------------------------------ | ------------------------------------------------------------- |
+| [Agent](#agent)                                              | Enrolled machine that carries its own tunnels                 |
+| [Atomic Write](#atomic-write)                                | Write to temp file, then rename — never half-written          |
+| [Authelia](#authelia)                                        | TOTP 2FA authentication server for tunneled apps              |
+| [bcrypt](#bcrypt)                                            | Password hashing algorithm (~4KB RAM per hash)                |
+| [CA](#ca-certificate-authority)                              | Self-signed certificate authority for mTLS                    |
+| [certbot](#certbot)                                          | ACME client for free Let's Encrypt certificates               |
+| [Chisel](#chisel)                                            | WebSocket-over-HTTPS tunnel (Go binary)                       |
+| [Client Certificate](#client-certificate)                    | Browser-based digital ID for admin panel access               |
+| [DNS](#dns-domain-name-system)                               | Maps domain names to IP addresses                             |
+| [Droplet](#droplet)                                          | DigitalOcean virtual machine ($4/mo minimum)                  |
+| [execa](#execa)                                              | Node.js library for safe shell command execution              |
+| [fail2ban](#fail2ban)                                        | Brute-force protection (bans IPs after failed attempts)       |
+| [Fastify](#fastify)                                          | Node.js web framework powering the panel API                  |
+| [Forward Auth](#forward-auth)                                | nginx delegates auth checks to Authelia                       |
+| [FQDN](#fqdn-fully-qualified-domain-name)                    | Complete domain name (e.g., `myapp.example.com`)              |
+| [launchd](#launchd)                                          | macOS service manager for Chisel client                       |
+| [Let's Encrypt](#lets-encrypt)                               | Free TLS certificate authority (auto-renewing)                |
+| [Listr2](#listr2)                                            | Terminal task runner for the installer                        |
+| [mTLS](#mtls-mutual-tls)                                     | Two-way TLS — both server and client prove identity           |
+| [nginx](#nginx)                                              | Reverse proxy, TLS termination, sole public-facing service    |
+| [Onboarding](#onboarding)                                    | First-run wizard: domain, DNS, provisioning                   |
+| [PKCS12](#pkcs12)                                            | `.p12` file format for client certificate + key bundle        |
+| [Panel](#panel-lamalibre-lamaste-serverd--lamaste-server-ui) | Admin UI (React SPA) + REST API (Fastify)                     |
+| [Sync Timer](#sync-timer)                                    | Agent job applying tunnel changes every 30 s                  |
+| [TOTP](#totp-time-based-one-time-password)                   | Six-digit codes from authenticator apps                       |
+| [Tunnel](#tunnel)                                            | Reverse TCP tunnel from an agent to the droplet via WebSocket |
+| [UFW](#ufw-uncomplicated-firewall)                           | Firewall allowing only ports 22, 80, 443, 9292                |
+| [Vhost](#vhost-virtual-host)                                 | nginx server block routing by domain name                     |
+| [WebSocket](#websocket)                                      | Full-duplex communication protocol (RFC 6455)                 |
+| [Zod](#zod)                                                  | Schema validation for API inputs                              |
+
+### Port Quick Reference
+
+| Port | Service       | Auth Method                     |
+| ---- | ------------- | ------------------------------- |
+| 22   | SSH           | Key-based (fail2ban protected)  |
+| 80   | HTTP redirect | None (`301` to HTTPS)           |
+| 443  | Tunneled apps | Authelia (username + TOTP)      |
+| 9292 | Admin panel   | mTLS (client certificate)       |
+| 3100 | Panel server  | Localhost only (no auth needed) |
+| 9090 | Chisel server | Localhost only                  |
+| 9091 | Authelia      | Localhost only                  |
+
+### Key File Paths
+
+| Path                                   | Contents                        |
+| -------------------------------------- | ------------------------------- |
+| `/etc/lamalibre/lamaste/panel.json`    | Main configuration              |
+| `/etc/lamalibre/lamaste/tunnels.json`  | Tunnel definitions              |
+| `/etc/lamalibre/lamaste/pki/`          | All certificates and keys       |
+| `/opt/lamalibre/lamaste/`              | Panel server + client           |
+| `/var/www/lamaste/`                    | Static site files               |
+| `/etc/nginx/sites-available/lamaste-*` | nginx vhosts                    |
+| `/etc/authelia/`                       | Authelia config + user database |
+
+### Related Documentation
+
+- [What is Lamaste?](../00-introduction/what-is-lamaste.md) — project overview
+- [How It Works](../00-introduction/how-it-works.md) — architecture and data flow
+- [Quick Start](../00-introduction/quickstart.md) — from zero to first tunnel
+- [Tunneling](../01-concepts/tunneling.md) — deep dive on Chisel tunnels
+- [mTLS](../01-concepts/mtls.md) — client certificate authentication
+- [Authentication](../01-concepts/authentication.md) — Authelia and TOTP
+- [Security Model](../01-concepts/security-model.md) — defense-in-depth layers