@lamalibre/create-lamaste 4.0.0

package/vendor/docs/02-guides/managing-users.md

@@ -0,0 +1,255 @@
+# Managing Users
+
+> Add, update, and remove Authelia users who can access your tunneled apps through TOTP two-factor authentication.
+
+## In Plain English
+
+Every tunneled app in Lamaste is protected by Authelia, a login system that requires a username, password, and a one-time code from an authenticator app. When you create a user in the Lamaste panel, that person can log in to any of your tunneled apps. This guide covers the full lifecycle: creating users, enrolling them in two-factor authentication, changing passwords, and safely removing users.
+
+## Prerequisites
+
+- A completed [Lamaste onboarding](onboarding.md)
+- Access to the Lamaste admin panel
+- An authenticator app for TOTP enrollment (Google Authenticator, Authy, 1Password, etc.)
+
+## Step-by-Step
+
+### 1. Open the Users Page
+
+Log in to the Lamaste admin panel at `https://<ip>:9292`.
+
+Click **Users** in the sidebar navigation.
+
+You see a list of existing users. After onboarding, there is one user: `admin` — the account created during provisioning.
+
+### 2. Add a New User
+
+Click the **Add User** button.
+
+A form appears with these fields:
+
+| Field            | Required | Rules                                                                                            | Example                   |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------- |
+| **Username**     | Yes      | 2-32 chars, lowercase alphanumeric with underscores and hyphens, starting with a letter or digit | `alice`                   |
+| **Display Name** | Yes      | 1-100 characters                                                                                 | `Alice Johnson`           |
+| **Email**        | Yes      | Valid email address                                                                              | `alice@example.com`       |
+| **Password**     | Yes      | 8-128 characters                                                                                 | A strong, unique password |
+| **Groups**       | No       | Optional list of group names                                                                     | `admins`, `developers`    |
+
+Fill in the form and click **Create User**.
+
+**What happens behind the scenes:**
+
+1. The panel validates all fields against the schema.
+2. The password is hashed with **bcrypt** (not argon2id — argon2id uses ~93 MB per hash and causes OOM kills on 512 MB droplets).
+3. The user record is written to `/etc/authelia/users.yml` using an atomic write (write to temp file, then rename) to prevent corruption.
+4. Authelia is reloaded to pick up the new user.
+
+**Expected result:** The new user appears in the list. Share the username and password with the person — they need these to log in to your tunneled apps.
+
+### 3. TOTP Enrollment
+
+When a new user visits a Lamaste-protected app for the first time:
+
+1. They are redirected to `auth.example.com`.
+2. They enter their username and password.
+3. Authelia presents a QR code for TOTP enrollment.
+4. They scan the QR code with their authenticator app.
+5. They enter the 6-digit code to verify.
+6. TOTP is now active. Every future login requires the code.
+
+**Walk a new user through this process:**
+
+1. Share the tunnel URL (e.g., `https://app.example.com`) and their credentials.
+2. Tell them to open the URL in their browser.
+3. They log in with the username and password you provided.
+4. They scan the QR code with Google Authenticator, Authy, 1Password, or any TOTP-compatible app.
+5. They enter the verification code.
+6. They are logged in and can access the app.
+
+### 4. Reset a User's TOTP Secret
+
+If a user loses access to their authenticator app (lost phone, new device), you can reset their TOTP secret so they can re-enroll.
+
+1. Go to the **Users** page.
+2. Find the user in the list.
+3. Click the **Reset TOTP** button next to the user.
+4. The panel generates a new TOTP secret and returns a TOTP URI.
+5. A QR code is displayed — the user scans it with their authenticator app.
+
+**What happens behind the scenes:**
+
+1. The panel generates a new base32-encoded TOTP secret.
+2. The secret is written to Authelia's SQLite database (`/etc/authelia/db.sqlite3`) via the `authelia storage user totp generate` CLI command. TOTP secrets are stored in the database, not in `users.yml` (the `totp_secret` field in `users.yml` is deprecated and ignored in Authelia v4.38+).
+3. The TOTP URI is returned in the format `otpauth://totp/Lamaste:<username>?secret=<secret>&issuer=Lamaste&algorithm=SHA1&digits=6&period=30`.
+
+On their next login, the user enters a code from the new TOTP entry in their authenticator app. The old entry no longer works.
+
+### 5. Change a User's Password
+
+1. Go to the **Users** page.
+2. Find the user and click **Edit** (or the edit icon).
+3. Enter a new password in the password field.
+4. Click **Save**.
+
+The new password is hashed with bcrypt and written to `users.yml`. Authelia is reloaded. The user must use the new password on their next login.
+
+You can also update the display name, email, and groups in the same edit form.
+
+### 6. Update User Details
+
+To change a user's display name, email, or group membership:
+
+1. Go to the **Users** page.
+2. Click **Edit** on the user.
+3. Modify the fields you want to change.
+4. Click **Save**.
+
+Only the fields you change are updated — the password and TOTP secret remain the same unless explicitly changed.
+
+### 7. Remove a User
+
+1. Go to the **Users** page.
+2. Click the **Delete** button next to the user you want to remove.
+3. Confirm the deletion.
+
+**Safety rule:** You cannot delete the last user. Lamaste enforces this to prevent locking everyone out of the tunneled apps. If you try to delete the last user, the panel returns an error: "Cannot delete the last user."
+
+**What happens behind the scenes:**
+
+1. The panel removes the user from `users.yml` (atomic write).
+2. Authelia is reloaded.
+3. Any active sessions for that user expire naturally (Authelia does not have a "force logout" mechanism, but sessions have a timeout).
+
+After deletion, the user can no longer log in to any tunneled app.
+
+## For Developers
+
+### User Storage
+
+Users are stored in Authelia's `users.yml` file at `/etc/authelia/users.yml`. The file format is:
+
+```yaml
+users:
+  admin:
+    displayname: Admin
+    email: admin@example.com
+    password: $2b$12$... # bcrypt hash
+    groups:
+      - admins
+  alice:
+    displayname: Alice Johnson
+    email: alice@example.com
+    password: $2b$12$...
+    groups: []
+```
+
+Note: TOTP secrets are stored in Authelia's SQLite database (`/etc/authelia/db.sqlite3`), not in `users.yml`. The `totp_secret` field in `users.yml` is deprecated and ignored in Authelia v4.38+.
+
+All writes to this file are atomic: write to a temp file, then rename. This prevents Authelia from reading a partially-written file.
+
+### API Endpoints
+
+| Method   | Path                              | Purpose                                                     |
+| -------- | --------------------------------- | ----------------------------------------------------------- |
+| `GET`    | `/api/users`                      | List all users (sorted alphabetically, no sensitive fields) |
+| `POST`   | `/api/users`                      | Create a new user                                           |
+| `PUT`    | `/api/users/:username`            | Update user fields                                          |
+| `DELETE` | `/api/users/:username`            | Delete a user (not the last one)                            |
+| `POST`   | `/api/users/:username/reset-totp` | Generate a new TOTP secret                                  |
+
+### Create User Request
+
+```json
+POST /api/users
+{
+  "username": "alice",
+  "displayname": "Alice Johnson",
+  "email": "alice@example.com",
+  "password": "securepassword123",
+  "groups": ["developers"]
+}
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "user": {
+    "username": "alice",
+    "displayname": "Alice Johnson",
+    "email": "alice@example.com",
+    "groups": ["developers"]
+  }
+}
+```
+
+### Update User Request
+
+```json
+PUT /api/users/alice
+{
+  "displayname": "Alice J.",
+  "password": "newpassword456"
+}
+```
+
+Only provided fields are updated. At least one field must be present.
+
+### Reset TOTP Response
+
+```json
+POST /api/users/alice/reset-totp
+
+{
+  "ok": true,
+  "totpUri": "otpauth://totp/Lamaste:alice?secret=JBSWY3DPEHPK3PXP&issuer=Lamaste"
+}
+```
+
+The `totpUri` is used to generate a QR code that the user scans with their authenticator app.
+
+### Validation Rules (Zod Schema)
+
+| Field         | Rules                                     |
+| ------------- | ----------------------------------------- |
+| `username`    | 2-32 chars, regex `^[a-z0-9][a-z0-9_-]*$` |
+| `displayname` | 1-100 chars                               |
+| `email`       | Valid email format                        |
+| `password`    | 8-128 chars                               |
+| `groups`      | Optional array of strings                 |
+
+### Password Hashing
+
+Passwords are hashed with bcrypt at cost factor 12. The `hashPassword()` function in `lib/authelia.js` handles this. Argon2id is explicitly avoided because a single hash operation consumes ~93 MB of memory, which causes OOM kills on the 512 MB target droplet.
+
+### Authelia Reload
+
+After every write to `users.yml`, the panel restarts Authelia:
+
+```bash
+sudo systemctl restart authelia
+```
+
+Authelia reads `users.yml` on restart. If the restart fails, a warning is logged but the API request still succeeds — the user data is persisted and the next Authelia restart picks it up.
+
+## Quick Reference
+
+| Action              | Steps                                             |
+| ------------------- | ------------------------------------------------- |
+| **Add user**        | Users page, "Add User", fill form, "Create User"  |
+| **Edit user**       | Users page, "Edit" on user, modify fields, "Save" |
+| **Change password** | Edit user, enter new password, "Save"             |
+| **Reset TOTP**      | Users page, "Reset TOTP" on user, share QR code   |
+| **Delete user**     | Users page, "Delete" on user, confirm             |
+
+| Constraint       | Value                                           |
+| ---------------- | ----------------------------------------------- |
+| Username format  | `^[a-z0-9][a-z0-9_-]*$` (users and invitations) |
+| Username length  | 2-32 characters                                 |
+| Password length  | 8-128 characters                                |
+| Password hashing | bcrypt (cost 12)                                |
+| Minimum users    | 1 (cannot delete last user)                     |
+| TOTP algorithm   | SHA1, 6 digits, 30-second period                |
+| User file        | `/etc/authelia/users.yml`                       |

package/vendor/docs/02-guides/onboarding.md

@@ -0,0 +1,244 @@
+# Onboarding
+
+> Walk through the onboarding wizard to configure your domain, verify DNS, and provision the full Lamaste stack.
+
+## In Plain English
+
+After installing Lamaste, the server is accessible only by IP address. The onboarding wizard connects your domain, verifies that DNS is pointing correctly, and starts all the services needed to run secure tunnels — Chisel for tunneling, Authelia for two-factor authentication, and Let's Encrypt for proper TLS certificates. The Chisel and Authelia programs themselves were already installed by the installer; onboarding configures and starts them. When it finishes, you have a fully operational platform.
+
+## Prerequisites
+
+- A completed [Lamaste installation](installation.md) with the admin panel accessible at `https://<ip>:9292`
+- A **domain name** you control (e.g., `example.com`)
+- Access to your domain's **DNS management** (registrar dashboard, Cloudflare, Route 53, etc.)
+- An **email address** for Let's Encrypt certificate registration
+
+## Step-by-Step
+
+### 1. Open the Admin Panel
+
+Navigate to `https://<ip>:9292` in your browser. Your browser presents the client certificate you imported during installation — select the "admin" certificate.
+
+You see the onboarding wizard with the first step: **Configure your domain**.
+
+### 2. Enter Domain and Email
+
+The first step asks for two pieces of information:
+
+| Field      | Example           | Purpose                                         |
+| ---------- | ----------------- | ----------------------------------------------- |
+| **Domain** | `example.com`     | Base domain for your Lamaste installation       |
+| **Email**  | `you@example.com` | Used for Let's Encrypt certificate registration |
+
+Enter your domain name (without `www.` or any prefix — just the base domain) and your email address, then click **Save & Continue**.
+
+The domain must be a valid fully qualified domain name. The email is registered with Let's Encrypt and receives expiry warnings if auto-renewal fails. It must start with a letter or digit (for example `admin@example.com`) — the panel applies the same rule as the certificate tooling, so an address it accepts here never fails later at issuance.
+
+**What happens behind the scenes:** The panel sends a `POST /api/onboarding/domain` request. The server validates the domain format and email, stores them in `/etc/lamalibre/lamaste/panel.json`, and advances the onboarding status from `FRESH` to `DOMAIN_SET`.
+
+### 3. Configure DNS Records
+
+The wizard now shows the DNS records you need to create at your domain registrar or DNS provider.
+
+The wizard lists two A records:
+
+| Type  | Name            | Value          |
+| ----- | --------------- | -------------- |
+| **A** | `*.example.com` | `203.0.113.42` |
+| **A** | `example.com`   | `203.0.113.42` |
+
+The wildcard record covers the three subdomains Lamaste itself serves (`panel.`, `auth.` and `tunnel.`) and lets it create subdomains (like `app.example.com`, `blog.example.com`) without adding individual DNS records each time. Without a wildcard, add an A record for each of `panel.example.com`, `auth.example.com` and `tunnel.example.com`.
+
+The record for the base domain is optional. It is only needed to serve a site on `example.com` itself, so if another host serves that name today, leave it where it is — onboarding does not require it.
+
+**How to add these records** (varies by provider):
+
+**Cloudflare:**
+
+1. Go to your domain's DNS settings.
+2. Click "Add Record".
+3. Type: A, Name: `@`, Content: your server IP, Proxy: DNS only (gray cloud).
+4. Add another: Type: A, Name: `*`, Content: your server IP, Proxy: DNS only.
+
+**DigitalOcean DNS:**
+
+1. Go to Networking and select your domain.
+2. Add an A record: Hostname `@`, Directs to: your droplet.
+3. Add an A record: Hostname `*`, Directs to: your droplet.
+
+**Namecheap:**
+
+1. Go to Domain List and click Manage next to your domain.
+2. Go to Advanced DNS.
+3. Add: Type A Record, Host `@`, Value: your server IP.
+4. Add: Type A Record, Host `*`, Value: your server IP.
+
+**GoDaddy:**
+
+1. Go to My Products and click DNS next to your domain.
+2. Add Record: Type A, Name `@`, Value: your server IP.
+3. Add Record: Type A, Name `*`, Value: your server IP.
+
+DNS propagation usually takes a few minutes but can take up to 48 hours in some cases.
+
+### 4. Verify DNS
+
+After adding the records, click **Verify DNS** in the wizard.
+
+The server checks:
+
+1. **Required** — Do `panel.example.com`, `auth.example.com` and `tunnel.example.com` resolve to your server's IP? Provisioning issues certificates for exactly these names.
+2. **Optional: wildcard** — Does `*.example.com` resolve to your server's IP?
+3. **Optional: base domain** — Does `example.com` itself resolve to your server's IP?
+
+**If the three required names pass:** You see a green checkmark for each and the message "DNS is correctly configured. panel, auth and tunnel resolve to your server." Click **Continue**.
+
+**If the wildcard or the base domain does not point here:** You see a yellow warning for it and can still continue. Without a wildcard you add an A record manually for each tunnel subdomain. The base domain only has to point here once you serve a site on it.
+
+**If a required name fails:** You see a red X next to it. The message tells you what IP the name resolves to (or that it does not resolve yet). Wait a few minutes and click **Verify DNS** again.
+
+**If something goes wrong:** DNS propagation delays are the most common issue. Use a tool like `dig example.com` or [dnschecker.org](https://dnschecker.org) to verify your records are propagating. Some registrars cache aggressively — try clearing the DNS cache or waiting longer.
+
+### 5. Start Provisioning
+
+After DNS verification succeeds, click **Continue** to reach the provisioning step. Click **Start Provisioning** to begin.
+
+The wizard displays a real-time progress view with six tasks:
+
+**Task 1 — Starting Chisel**
+
+Chisel is the tunneling engine. The installer already put the pinned Chisel release and its systemd unit in place; the provisioner checks the binary is there, creates the Chisel server key and the authfile, and starts the service. Chisel listens on `127.0.0.1:9090` for WebSocket connections from your machine.
+
+**Task 2 — Configuring Authelia**
+
+Authelia provides two-factor authentication for your tunneled apps. The installer already put the pinned Authelia release, its systemd unit and its `lamaste-authelia` service account in place; the provisioner checks the binary is there, writes the configuration file (using your domain), creates the initial admin user with a random password, and starts the service. Authelia listens on `127.0.0.1:9091`.
+
+Onboarding downloads nothing. If either task fails with "… is not installed. Run `npx @lamalibre/create-lamaste@4.0.0` on the server to repair the installation.", re-run the installer on the server (it is idempotent) and start provisioning again.
+
+Authelia uses **bcrypt** for password hashing (not argon2id) because argon2id uses approximately 93 MB per hash, which causes out-of-memory kills on a 512 MB droplet.
+
+**Task 3 — Issuing TLS certificates**
+
+The provisioner runs certbot to obtain Let's Encrypt certificates for `panel.example.com`, `auth.example.com`, and `tunnel.example.com`. It also sets up the certbot auto-renewal timer.
+
+**Task 4 — Configuring nginx**
+
+Three new nginx vhosts are written and enabled:
+
+| Vhost  | Domain               | Purpose                   |
+| ------ | -------------------- | ------------------------- |
+| Panel  | `panel.example.com`  | Admin panel with mTLS     |
+| Auth   | `auth.example.com`   | Authelia login portal     |
+| Tunnel | `tunnel.example.com` | Chisel WebSocket endpoint |
+
+nginx is tested with `nginx -t` and reloaded.
+
+**Task 5 — Verifying services**
+
+The provisioner checks that Chisel, Authelia, nginx, and the panel server are all running and healthy.
+
+**Task 6 — Finalizing setup**
+
+The onboarding status is set to `COMPLETED` in `panel.json`. Management routes become available and onboarding routes return `410 Gone`.
+
+### 6. Save Your Credentials
+
+After provisioning completes, the wizard shows the completion screen with:
+
+- **Admin username:** `admin`
+- **Admin password:** A randomly generated password (click the eye icon to reveal, click copy to copy)
+- **Panel URL:** `https://panel.example.com`
+- **Auth Portal URL:** `https://auth.example.com`
+- **IP Access URL:** `https://203.0.113.42:9292` (always works, requires client certificate)
+
+**Save the admin credentials immediately.** The password is generated during provisioning and is not shown again. You use these credentials to log into the Authelia portal when accessing your tunneled apps.
+
+### 7. Set Up Two-Factor Authentication
+
+On your first login to `auth.example.com`, Authelia prompts you to enroll in TOTP two-factor authentication:
+
+1. Open an authenticator app (Google Authenticator, Authy, 1Password, etc.).
+2. Scan the QR code displayed by Authelia.
+3. Enter the 6-digit code from your authenticator to verify.
+
+After enrollment, every login to a tunneled app requires your username, password, and a TOTP code.
+
+### 8. Go to the Dashboard
+
+Click **Go to Dashboard** to enter the management interface. You now have access to:
+
+- **Dashboard** — System stats and service health
+- **Tunnels** — Create and manage tunnels
+- **Users** — Manage Authelia users
+- **Certificates** — View and renew TLS certificates
+- **Sites** — Host static websites
+- **Services** — Start, stop, and restart services
+
+Proceed to [Creating Your First Tunnel](first-tunnel.md) to expose your first local app.
+
+## For Developers
+
+### Onboarding State Machine
+
+The onboarding follows a strict state progression stored in `panel.json`:
+
+```
+FRESH → DOMAIN_SET → DNS_READY → PROVISIONING → COMPLETED
+```
+
+Each transition is enforced by the API:
+
+| Endpoint                          | Required State              | New State                       |
+| --------------------------------- | --------------------------- | ------------------------------- |
+| `POST /api/onboarding/domain`     | `FRESH` or `DOMAIN_SET`     | `DOMAIN_SET`                    |
+| `POST /api/onboarding/verify-dns` | `DOMAIN_SET` or `DNS_READY` | `DNS_READY`                     |
+| `POST /api/onboarding/provision`  | `DNS_READY`                 | `PROVISIONING` then `COMPLETED` |
+
+After `COMPLETED`, all onboarding endpoints return `410 Gone`. Management endpoints return `503 Service Unavailable` before `COMPLETED`.
+
+### Provisioning Internals
+
+Provisioning runs asynchronously — the `POST /api/onboarding/provision` endpoint returns `202 Accepted` immediately and starts the provisioning sequence in the background. Progress is streamed to the client via a WebSocket connection at `/api/onboarding/provision/stream`.
+
+Each provisioning task calls library functions in `packages/lamaste-serverd/src/lib/`:
+
+| Task               | Library           | Key Function                                                     |
+| ------------------ | ----------------- | ---------------------------------------------------------------- |
+| Start Chisel       | `lib/chisel.js`   | `isChiselInstalled()`, `ensureChiselKey()`, `startChisel()`      |
+| Configure Authelia | `lib/authelia.js` | `isAutheliaInstalled()`, `writeAutheliaConfig()`, `createUser()` |
+| Issue certs        | `lib/certbot.js`  | `issueCoreCerts()`, `setupAutoRenew()`                           |
+| Configure nginx    | `lib/nginx.js`    | `writePanelVhost()`, `writeAuthVhost()`, `writeTunnelVhost()`    |
+
+### DNS Verification Logic
+
+The DNS check resolves these hostnames using Node's `dns.resolve4()`:
+
+1. `panel.example.com`, `auth.example.com`, `tunnel.example.com` — must resolve to the server IP (required; `CORE_SUBDOMAINS` in `@lamalibre/lamaste@4.0.0`)
+2. `test-lamaste-check.example.com` — tests wildcard resolution (optional)
+3. `example.com` — reported, not required
+
+The test subdomain `test-lamaste-check` is chosen to be unlikely to have an explicit A record, so resolution only succeeds if a wildcard record is present.
+
+## Quick Reference
+
+| Step            | Action           | Expected Duration |
+| --------------- | ---------------- | ----------------- |
+| Domain + email  | Enter in wizard  | 30 seconds        |
+| DNS records     | Add at registrar | 2-5 minutes       |
+| DNS propagation | Wait and verify  | 1-30 minutes      |
+| Provisioning    | Automatic        | 2-5 minutes       |
+| TOTP enrollment | Scan QR code     | 1 minute          |
+
+| URL                         | Purpose           | Auth Method                |
+| --------------------------- | ----------------- | -------------------------- |
+| `https://panel.example.com` | Admin panel       | mTLS client certificate    |
+| `https://auth.example.com`  | Authelia login    | Username + password + TOTP |
+| `https://203.0.113.42:9292` | IP fallback panel | mTLS client certificate    |
+
+| Onboarding Status | Meaning                          |
+| ----------------- | -------------------------------- |
+| `FRESH`           | No domain configured yet         |
+| `DOMAIN_SET`      | Domain saved, DNS not verified   |
+| `DNS_READY`       | DNS verified, ready to provision |
+| `PROVISIONING`    | Stack installation in progress   |
+| `COMPLETED`       | Fully operational                |