@lamalibre/create-lamaste 4.0.0

package/vendor/docs/04-api-reference/services.md

@@ -0,0 +1,267 @@
+# Services API
+
+> Monitor and control the systemd services that make up the Lamaste stack, with live log streaming via WebSocket.
+
+## In Plain English
+
+Lamaste runs several background services on the droplet: nginx (the reverse proxy), Chisel (the tunnel server), Authelia (the login system for tunneled apps), and the panel server itself. The services API lets you check whether each service is running, start or stop them, restart them, and watch their log output in real time.
+
+Think of it as a simplified version of the `systemctl` and `journalctl` commands, accessible from your browser.
+
+## Authentication
+
+All service endpoints require a valid mTLS client certificate and a completed onboarding. See the [API Overview](./overview.md) for details.
+
+If onboarding is not complete, all endpoints return `503 Service Unavailable`.
+
+In addition to admin certificates, agent certificates with the appropriate capabilities can access these endpoints:
+
+- `services:read` — grants access to `GET /api/services` (list statuses)
+- `services:write` — grants access to `POST /api/services/:name/:action` (control services)
+
+## Service Whitelist
+
+Only these services can be managed through the API:
+
+| Service Name                | Description                                      |
+| --------------------------- | ------------------------------------------------ |
+| `nginx`                     | Reverse proxy, TLS termination, mTLS enforcement |
+| `chisel`                    | WebSocket tunnel server                          |
+| `authelia`                  | TOTP two-factor authentication                   |
+| `lamalibre-lamaste-serverd` | The panel server itself (Fastify)                |
+
+Requests for any other service name are rejected with a 400 error. This whitelist prevents arbitrary systemd service manipulation.
+
+## Safety Rules
+
+- **Cannot stop the panel from the UI.** Calling `POST /api/services/lamalibre-lamaste-serverd/stop` returns a 400 error because stopping the panel would terminate the API session — you would lose the ability to restart it without SSH access.
+- **All actions use sudo.** The panel runs as the `lamaste` user. Service control commands use `sudo systemctl` via sudoers rules that restrict which services and actions are permitted.
+
+## Endpoints
+
+### `GET /api/services`
+
+Returns the status and uptime of all managed services. Statuses are queried in parallel from systemd.
+
+**Request:**
+
+No request body.
+
+```bash
+curl -s --cert client.p12:password \
+  https://203.0.113.42:9292/api/services | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "services": [
+    {
+      "name": "nginx",
+      "status": "active",
+      "uptime": "5d 3h 20m"
+    },
+    {
+      "name": "chisel",
+      "status": "active",
+      "uptime": "5d 3h 19m"
+    },
+    {
+      "name": "authelia",
+      "status": "active",
+      "uptime": "5d 3h 18m"
+    },
+    {
+      "name": "lamalibre-lamaste-serverd",
+      "status": "active",
+      "uptime": "2h 45m"
+    }
+  ]
+}
+```
+
+| Field    | Type             | Description                                                          |
+| -------- | ---------------- | -------------------------------------------------------------------- |
+| `name`   | `string`         | systemd service name                                                 |
+| `status` | `string`         | One of: `active`, `inactive`, `failed`, `unknown`                    |
+| `uptime` | `string \| null` | Human-readable uptime (e.g., `"2d 5h 30m"`), or `null` if not active |
+
+The uptime is calculated from the `ActiveEnterTimestamp` reported by systemd and formatted as a human-readable duration. If the timestamp cannot be read, uptime is `null` even for active services.
+
+---
+
+### `POST /api/services/:name/:action`
+
+Executes a systemctl action on a managed service. The command runs with a 30-second timeout.
+
+**URL parameters:**
+
+| Parameter | Type     | Validation                                   | Description        |
+| --------- | -------- | -------------------------------------------- | ------------------ |
+| `:name`   | `string` | Must be in the service whitelist             | Service to control |
+| `:action` | `string` | One of: `start`, `stop`, `restart`, `reload` | Action to execute  |
+
+```bash
+curl -s --cert client.p12:password \
+  -X POST \
+  https://203.0.113.42:9292/api/services/nginx/restart | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "ok": true,
+  "name": "nginx",
+  "action": "restart"
+}
+```
+
+**Errors:**
+
+| Status | Body                                                                                      | When                                           |
+| ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| 400    | `{"error":"Unknown service"}`                                                             | Service name not in whitelist                  |
+| 400    | `{"error":"Invalid action"}`                                                              | Action not one of start/stop/restart/reload    |
+| 400    | `{"error":"Cannot stop the panel service from the UI — it would terminate this session"}` | Attempting to stop `lamalibre-lamaste-serverd` |
+| 400    | `{"error":"chisel does not support reload — use restart"}`                                | `reload` for `chisel` or the panel service     |
+| 400    | `{"error":"Validation failed","details":{"issues":[...]}}`                                | Zod validation of params failed                |
+| 500    | `{"error":"Failed to restart nginx","details":"..."}`                                     | systemctl command failed                       |
+
+### Available Actions
+
+| Action    | systemctl Command               | Notes                                                                       |
+| --------- | ------------------------------- | --------------------------------------------------------------------------- |
+| `start`   | `sudo systemctl start <name>`   | Start a stopped service                                                     |
+| `stop`    | `sudo systemctl stop <name>`    | Stop a running service (blocked for `lamalibre-lamaste-serverd`)            |
+| `restart` | `sudo systemctl restart <name>` | Stop then start a service                                                   |
+| `reload`  | `sudo systemctl reload <name>`  | Reload configuration without full restart (supported by nginx and authelia) |
+
+---
+
+### `WS /api/services/:name/logs`
+
+WebSocket endpoint that streams live logs from journalctl for a specific service. The connection tails the last 100 log lines and then follows new output in real time.
+
+**URL parameters:**
+
+| Parameter | Type     | Validation                       | Description              |
+| --------- | -------- | -------------------------------- | ------------------------ |
+| `:name`   | `string` | Must be in the service whitelist | Service to tail logs for |
+
+If the service name is not in the whitelist, the WebSocket is closed immediately with code 1008 ("Policy Violation") and the reason "Unknown service".
+
+**Connection:**
+
+```javascript
+const ws = new WebSocket('wss://203.0.113.42:9292/api/services/nginx/logs');
+
+ws.onmessage = (event) => {
+  const entry = JSON.parse(event.data);
+  console.log(`[${entry.timestamp}] ${entry.message}`);
+};
+
+ws.onclose = (event) => {
+  console.log(`Log stream closed: ${event.reason}`);
+};
+```
+
+**Message format:**
+
+Each message is a JSON object with a timestamp and message:
+
+```json
+{
+  "timestamp": "2026-03-13T14:30:45+0000",
+  "message": "hostname nginx[1234]: 203.0.113.42 - - [13/Mar/2026:14:30:45 +0000] \"GET /api/health HTTP/1.1\" 200 32"
+}
+```
+
+| Field       | Type     | Description                                                    |
+| ----------- | -------- | -------------------------------------------------------------- |
+| `timestamp` | `string` | ISO timestamp from journalctl `--output=short-iso` format      |
+| `message`   | `string` | The rest of the log line (hostname, process, PID, and message) |
+
+If the timestamp cannot be parsed from the log line, `timestamp` is an empty string and `message` contains the entire raw line.
+
+**Special messages:**
+
+```json
+{
+  "timestamp": "2026-03-13T14:30:45.000Z",
+  "message": "[Error: Failed to start log stream for nginx]"
+}
+```
+
+```json
+{
+  "timestamp": "2026-03-13T14:30:45.000Z",
+  "message": "[Log stream ended]"
+}
+```
+
+**Close codes:**
+
+| Code | Reason                     | When                                   |
+| ---- | -------------------------- | -------------------------------------- |
+| 1000 | Log stream ended           | journalctl process exited normally     |
+| 1008 | Unknown service            | Service name not in whitelist          |
+| 1011 | Failed to spawn journalctl | Could not start the journalctl process |
+
+**Implementation details:**
+
+- Uses `journalctl -u <name> -f -n 100 --output=short-iso`
+- The `-n 100` flag sends the last 100 log lines on connect (backfill)
+- The `-f` flag follows new output in real time
+- The journalctl process is killed (SIGTERM) when the WebSocket closes
+- All active journalctl processes are cleaned up on server shutdown
+
+## Quick Reference
+
+| Method | Path                          | Description                           |
+| ------ | ----------------------------- | ------------------------------------- |
+| GET    | `/api/services`               | List all service statuses and uptimes |
+| POST   | `/api/services/:name/:action` | Execute start/stop/restart/reload     |
+| WS     | `/api/services/:name/logs`    | Stream live logs via WebSocket        |
+
+### Service Status Object Shape
+
+```json
+{
+  "name": "nginx",
+  "status": "active",
+  "uptime": "5d 3h 20m"
+}
+```
+
+### Allowed Combinations
+
+| Service                     | start | stop   | restart | reload |
+| --------------------------- | ----- | ------ | ------- | ------ |
+| `nginx`                     | Yes   | Yes    | Yes     | Yes    |
+| `chisel`                    | Yes   | Yes    | Yes     | **No** |
+| `authelia`                  | Yes   | Yes    | Yes     | Yes    |
+| `lamalibre-lamaste-serverd` | Yes   | **No** | Yes     | **No** |
+
+### curl Cheat Sheet
+
+```bash
+# List service statuses
+curl -s --cert client.p12:password \
+  https://203.0.113.42:9292/api/services | jq
+
+# Restart nginx
+curl -s --cert client.p12:password \
+  -X POST \
+  https://203.0.113.42:9292/api/services/nginx/restart | jq
+
+# Reload Authelia (after manual config changes)
+curl -s --cert client.p12:password \
+  -X POST \
+  https://203.0.113.42:9292/api/services/authelia/reload | jq
+
+# Stream nginx logs (requires wscat or similar)
+wscat -c wss://203.0.113.42:9292/api/services/nginx/logs \
+  --cert client.pem --key client-key.pem
+```

package/vendor/docs/04-api-reference/settings.md

@@ -0,0 +1,343 @@
+# Settings API
+
+> Two-factor authentication (2FA) configuration for the admin panel. All endpoints are admin-only and fall under the management route group.
+
+## In Plain English
+
+The settings API lets you enable, configure, and manage TOTP-based two-factor authentication for the admin panel. When 2FA is enabled, every admin request must carry both a valid mTLS client certificate and a valid session cookie. The session cookie is issued after the admin verifies a TOTP code and lasts for 12 hours (or 2 hours of inactivity, whichever comes first).
+
+The lifecycle is:
+
+1. **Check status** — `GET /api/settings/2fa` tells you whether 2FA is enabled.
+2. **Setup** — `POST /api/settings/2fa/setup` generates a TOTP secret and returns a `otpauth://` URI for scanning with an authenticator app.
+3. **Confirm** — `POST /api/settings/2fa/confirm` verifies the first code from the authenticator app, enabling 2FA and disabling the IP-based vhost.
+4. **Verify (ongoing)** — `POST /api/settings/2fa/verify` is called at the start of each admin session to exchange a TOTP code for a session cookie.
+5. **Disable** — `POST /api/settings/2fa/disable` turns off 2FA and re-enables the IP-based vhost. Requires a valid 2FA session and a TOTP code.
+
+## Authentication
+
+All endpoints require a valid mTLS admin certificate. The **status** (`GET /api/settings/2fa`) and **verify** (`POST /api/settings/2fa/verify`) endpoints are exempt from the 2FA session requirement — they must be accessible before the admin has a session cookie. All other endpoints require a valid 2FA session when 2FA is enabled.
+
+**Note:** Agent certificates bypass 2FA entirely — the 2FA session middleware skips all requests where `certRole` is `agent`. Only admin certificate holders are subject to the 2FA requirement.
+
+## Rate Limiting
+
+The `/confirm`, `/verify`, and `/disable` endpoints enforce per-IP rate limiting:
+
+- **5 attempts** per 2-minute sliding window
+- **5-minute ban** once the limit is exceeded
+
+Rate-limited requests receive:
+
+**Response (429):**
+
+```json
+{
+  "error": "Too many attempts. Try again later.",
+  "retryAfter": 300
+}
+```
+
+| Field        | Type     | Description                   |
+| ------------ | -------- | ----------------------------- |
+| `retryAfter` | `number` | Seconds until the ban expires |
+
+## Session Cookie
+
+When `POST /api/settings/2fa/verify` succeeds, the server sets a `lamaste_2fa_session` cookie:
+
+| Property     | Value                 |
+| ------------ | --------------------- |
+| Name         | `lamaste_2fa_session` |
+| Signing      | HMAC-SHA256           |
+| HttpOnly     | Yes                   |
+| Secure       | Yes                   |
+| SameSite     | Strict                |
+| Absolute TTL | 12 hours              |
+| Inactivity   | 2 hours               |
+
+If a request arrives with a valid mTLS certificate but without a valid 2FA session cookie (when 2FA is enabled), the API returns:
+
+**Response (401):**
+
+```json
+{
+  "error": "2fa_required"
+}
+```
+
+## Endpoints
+
+### `GET /api/settings/2fa`
+
+Returns the current 2FA status. This endpoint is exempt from the 2FA session requirement, so the UI can check whether to show the verification prompt.
+
+**Request:**
+
+No request body.
+
+```bash
+curl -s --cert client.p12:password \
+  https://203.0.113.42:9292/api/settings/2fa | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "enabled": false,
+  "setupComplete": false
+}
+```
+
+| Field           | Type      | Description                                        |
+| --------------- | --------- | -------------------------------------------------- |
+| `enabled`       | `boolean` | Whether 2FA is currently active                    |
+| `setupComplete` | `boolean` | Whether the initial setup and confirmation is done |
+
+---
+
+### `POST /api/settings/2fa/setup`
+
+Generates a new TOTP secret and returns the provisioning URI for scanning with an authenticator app (Google Authenticator, 1Password, etc.) and a manual entry key for apps that do not support QR scanning.
+
+Requires that a domain has been configured on the panel (enabling 2FA disables IP:9292 access, so a domain is required for continued access).
+
+**Request:**
+
+No request body.
+
+```bash
+curl -s -X POST --cert client.p12:password \
+  https://203.0.113.42:9292/api/settings/2fa/setup | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "uri": "otpauth://totp/Lamaste%20Panel:admin?secret=JBSWY3DPEHPK3PXP&issuer=Lamaste%20Panel",
+  "manualKey": "JBSWY3DPEHPK3PXP"
+}
+```
+
+| Field       | Type     | Description                                            |
+| ----------- | -------- | ------------------------------------------------------ |
+| `uri`       | `string` | `otpauth://` URI — encode as QR code for scanning      |
+| `manualKey` | `string` | Base32-encoded secret for manual entry in the auth app |
+
+**Errors:**
+
+| Status | Body                                                                                     | When                           |
+| ------ | ---------------------------------------------------------------------------------------- | ------------------------------ |
+| 400    | `{"error": "Domain must be configured before enabling 2FA", "details": {"hint": "..."}}` | No domain has been provisioned |
+| 409    | `{"error": "2FA is already enabled"}`                                                    | 2FA is already active          |
+
+---
+
+### `POST /api/settings/2fa/confirm`
+
+Verifies the first TOTP code after setup, completing the 2FA activation. Once confirmed, 2FA is enabled and the IP-based vhost is disabled (all access goes through the domain vhost). This is a one-time operation during setup.
+
+**Request:**
+
+```json
+{
+  "code": "123456"
+}
+```
+
+| Field  | Type     | Required | Description                              |
+| ------ | -------- | -------- | ---------------------------------------- |
+| `code` | `string` | Yes      | 6-digit TOTP code from authenticator app |
+
+```bash
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  https://203.0.113.42:9292/api/settings/2fa/confirm | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "enabled": true
+}
+```
+
+The response also sets the `lamaste_2fa_session` cookie (see [Session Cookie](#session-cookie)), so no separate `/verify` call is needed for the initial session.
+
+**Errors:**
+
+| Status | Body                                                                          | When                              |
+| ------ | ----------------------------------------------------------------------------- | --------------------------------- |
+| 400    | `{"error": "Code must be exactly 6 digits"}`                                  | Code format invalid               |
+| 400    | `{"error": "No 2FA setup in progress. Call POST /settings/2fa/setup first."}` | No secret has been generated yet  |
+| 401    | `{"error": "Invalid TOTP code"}`                                              | TOTP code is incorrect or expired |
+| 409    | `{"error": "2FA is already enabled"}`                                         | 2FA is already active             |
+| 429    | `{"error": "Too many attempts. Try again later."}`                            | Rate limit exceeded               |
+| 500    | `{"error": "Failed to disable IP vhost. 2FA was not enabled."}`               | nginx config update failed        |
+
+---
+
+### `POST /api/settings/2fa/verify`
+
+Verifies a TOTP code and issues a session cookie. Called at the start of each admin session when 2FA is enabled. This endpoint is exempt from the 2FA session requirement.
+
+**Request:**
+
+```json
+{
+  "code": "123456"
+}
+```
+
+| Field  | Type     | Required | Description                              |
+| ------ | -------- | -------- | ---------------------------------------- |
+| `code` | `string` | Yes      | 6-digit TOTP code from authenticator app |
+
+```bash
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  https://203.0.113.42:9292/api/settings/2fa/verify | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "verified": true
+}
+```
+
+The response also sets the `lamaste_2fa_session` cookie (see [Session Cookie](#session-cookie) above).
+
+**Errors:**
+
+| Status | Body                                               | When                              |
+| ------ | -------------------------------------------------- | --------------------------------- |
+| 400    | `{"error": "Code must be exactly 6 digits"}`       | Code format invalid               |
+| 400    | `{"error": "2FA is not enabled"}`                  | 2FA has not been activated        |
+| 401    | `{"error": "Invalid TOTP code"}`                   | TOTP code is incorrect or expired |
+| 429    | `{"error": "Too many attempts. Try again later."}` | Rate limit exceeded               |
+
+---
+
+### `POST /api/settings/2fa/disable`
+
+Disables 2FA. Requires both a valid 2FA session cookie and a TOTP code for confirmation. After disabling, the IP-based vhost is re-enabled and the session cookie requirement is removed.
+
+**Note:** If re-enabling the IP vhost fails (e.g., nginx config error), 2FA is still disabled and the endpoint returns `200`. The failure is logged server-side. The admin would need to manually fix the nginx configuration or run `sudo lamaste-reset-admin` to restore the IP vhost.
+
+**Request:**
+
+```json
+{
+  "code": "123456"
+}
+```
+
+| Field  | Type     | Required | Description                              |
+| ------ | -------- | -------- | ---------------------------------------- |
+| `code` | `string` | Yes      | 6-digit TOTP code from authenticator app |
+
+```bash
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  https://203.0.113.42:9292/api/settings/2fa/disable | jq
+```
+
+**Response (200):**
+
+```json
+{
+  "enabled": false
+}
+```
+
+**Errors:**
+
+| Status | Body                                               | When                              |
+| ------ | -------------------------------------------------- | --------------------------------- |
+| 400    | `{"error": "Code must be exactly 6 digits"}`       | Code format invalid               |
+| 400    | `{"error": "2FA is not enabled"}`                  | 2FA was not active                |
+| 401    | `{"error": "Invalid TOTP code"}`                   | TOTP code is incorrect or expired |
+| 401    | `{"error": "2fa_required"}`                        | No valid 2FA session cookie       |
+| 429    | `{"error": "Too many attempts. Try again later."}` | Rate limit exceeded               |
+
+## Quick Reference
+
+| Method | Path                        | Auth                                 | Rate Limited | Description                       |
+| ------ | --------------------------- | ------------------------------------ | ------------ | --------------------------------- |
+| GET    | `/api/settings/2fa`         | mTLS (exempt from 2FA session)       | No           | Get 2FA status                    |
+| POST   | `/api/settings/2fa/setup`   | mTLS (2FA not yet active during use) | No           | Generate TOTP secret              |
+| POST   | `/api/settings/2fa/confirm` | mTLS (2FA not yet active during use) | Yes          | Confirm initial code, enable 2FA  |
+| POST   | `/api/settings/2fa/verify`  | mTLS (exempt from 2FA session)       | Yes          | Verify code, issue session cookie |
+| POST   | `/api/settings/2fa/disable` | mTLS + 2FA session                   | Yes          | Disable 2FA                       |
+
+### Response Shapes
+
+**Status:**
+
+```json
+{ "enabled": false, "setupComplete": false }
+```
+
+**Setup:**
+
+```json
+{ "uri": "otpauth://totp/...", "manualKey": "JBSWY3DPEHPK3PXP" }
+```
+
+**Confirm:**
+
+```json
+{ "enabled": true }
+```
+
+**Verify:**
+
+```json
+{ "verified": true }
+```
+
+**Disable:**
+
+```json
+{ "enabled": false }
+```
+
+### curl Cheat Sheet
+
+```bash
+# Check 2FA status
+curl -s --cert client.p12:password \
+  https://203.0.113.42:9292/api/settings/2fa | jq
+
+# Start 2FA setup
+curl -s -X POST --cert client.p12:password \
+  https://203.0.113.42:9292/api/settings/2fa/setup | jq
+
+# Confirm setup with first code
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  https://203.0.113.42:9292/api/settings/2fa/confirm | jq
+
+# Verify code to get session cookie
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  -c cookies.txt \
+  https://203.0.113.42:9292/api/settings/2fa/verify | jq
+
+# Disable 2FA (requires session cookie)
+curl -s -X POST --cert client.p12:password \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"123456"}' \
+  -b cookies.txt \
+  https://203.0.113.42:9292/api/settings/2fa/disable | jq
+```