@lamalibre/create-lamaste 4.0.0

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

@@ -0,0 +1,404 @@
+# API Overview
+
+> Nearly every interaction between the Lamaste management UI and the backend happens through a JSON REST API protected by mTLS client certificates. The exceptions are the invitation acceptance flow (`/api/invite/*`) and the agent enrollment endpoint (`/api/enroll`), which are public.
+
+## In Plain English
+
+When you open the Lamaste management panel in your browser, the page you see is a single-page application (SPA) built with React. Every button you click — creating a tunnel, adding a user, renewing a certificate — sends a request to the panel server's REST API running on the same machine. The server processes the request, makes changes to the system (writing config files, reloading services), and sends back a JSON response.
+
+The API sits behind nginx, which enforces mTLS on the panel vhost — meaning your browser must present a valid client certificate before the connection is even established. Without that certificate, the TLS handshake fails and no HTTP traffic reaches the API at all.
+
+There are two exceptions to the mTLS requirement. The `/api/invite/*` routes are registered in a public context without mTLS middleware, so that invited users can accept their invitation and set a password without needing a client certificate. The `/api/enroll` endpoint is also public, allowing agents to complete hardware-bound certificate enrollment using a token previously generated by an admin.
+
+## Base URL
+
+The API is served by the Fastify panel server at `127.0.0.1:3100`. In production, nginx reverse-proxies to this address. You never call port 3100 directly — all requests go through nginx on port 9292.
+
+```
+https://<droplet-ip>:9292/api/...
+```
+
+If a domain has been configured and provisioned:
+
+```
+https://panel.<your-domain>/api/...
+```
+
+Both URLs reach the same server. The IP-based URL always works, even if DNS is misconfigured.
+
+## Authentication
+
+### mTLS Client Certificates
+
+All API endpoints except `/api/invite/*` and `/api/enroll` require a valid mTLS client certificate. nginx verifies the certificate at the TLS layer and forwards the result to the panel server via the `X-SSL-Client-Verify` header.
+
+```
+Browser ──HTTPS + client cert──▶ nginx (port 9292)
+  nginx checks ssl_client_verify
+    ✓ SUCCESS → proxies to 127.0.0.1:3100 with X-SSL-Client-Verify: SUCCESS
+    ✗ FAILED  → TLS handshake rejected, no HTTP traffic reaches the API
+```
+
+In development mode (`NODE_ENV=development`), the mTLS check is bypassed. A warning is logged once on startup.
+
+**Rejection response (403):**
+
+```json
+{
+  "error": "mTLS certificate required",
+  "details": {
+    "hint": "Access to the Lamaste panel requires a valid client certificate."
+  }
+}
+```
+
+### No Session Tokens (with One Exception)
+
+The client certificate is the primary authentication mechanism — there are no login endpoints and no bearer tokens. If the certificate is valid, every request is authorized. This is the same model used by LXD.
+
+The one exception is the optional **two-factor authentication (2FA)** feature. When 2FA is enabled, admin requests must also carry a valid `lamaste_2fa_session` cookie. This cookie is issued by `POST /api/settings/2fa/verify` after the admin presents a correct TOTP code, and it is HMAC-SHA256 signed, HttpOnly, Secure, SameSite=Strict with a 12-hour absolute expiry and 2-hour inactivity timeout. If a request arrives with a valid mTLS certificate but without a valid 2FA session cookie, the API returns:
+
+```json
+{
+  "error": "2fa_required"
+}
+```
+
+with HTTP 401. The 2FA status and verification endpoints are themselves exempt from the 2FA session requirement so that the admin can check status and submit a code without already having a session.
+
+## Content Type
+
+All request and response bodies use `application/json` unless explicitly noted otherwise:
+
+- **File downloads** (certificates) return their native MIME type
+- **File uploads** use `multipart/form-data`
+- **WebSocket connections** use the standard WebSocket upgrade handshake
+
+Requests with a JSON body must include the `Content-Type: application/json` header.
+
+## Error Format
+
+Every error response follows a consistent contract:
+
+```json
+{
+  "error": "Human-readable error summary",
+  "details": {}
+}
+```
+
+| Field     | Type     | Presence | Description                                       |
+| --------- | -------- | -------- | ------------------------------------------------- |
+| `error`   | `string` | Always   | A short, human-readable error message             |
+| `details` | `object` | Optional | Additional structured information about the error |
+
+### Validation Errors (400)
+
+All request bodies are validated with [Zod](https://zod.dev/) schemas at the route level. When validation fails, the error handler returns a 400 with the Zod issues:
+
+```json
+{
+  "error": "Validation failed",
+  "details": {
+    "issues": [
+      {
+        "path": ["subdomain"],
+        "message": "Subdomain must be lowercase alphanumeric with optional hyphens, cannot start or end with a hyphen"
+      },
+      {
+        "path": ["port"],
+        "message": "Port must be at least 1024"
+      }
+    ]
+  }
+}
+```
+
+### Operational Errors (4xx)
+
+Business logic errors return appropriate HTTP status codes with descriptive messages:
+
+```json
+{
+  "error": "Cannot delete the last user"
+}
+```
+
+Common status codes:
+
+| Code | Meaning                             | Example                                      |
+| ---- | ----------------------------------- | -------------------------------------------- |
+| 400  | Bad request / validation failed     | Invalid subdomain format                     |
+| 401  | 2FA session required                | Valid mTLS cert but no 2FA session cookie    |
+| 403  | mTLS certificate missing or invalid | No client cert presented                     |
+| 404  | Resource not found                  | Tunnel ID does not exist                     |
+| 409  | Conflict                            | Username already exists                      |
+| 410  | Gone                                | Onboarding endpoint called after completion  |
+| 503  | Service unavailable                 | Management endpoint called before onboarding |
+
+### Internal Errors (500)
+
+Unexpected errors return a generic message in production to avoid leaking internal details:
+
+```json
+{
+  "error": "Internal server error"
+}
+```
+
+In development mode, the response includes a `details` object with the error message and stack trace.
+
+## Onboarding Guard
+
+The API is split into two groups with mutual exclusion enforced by middleware:
+
+| Route Group    | Prefix                                                   | Available When        | Otherwise Returns         |
+| -------------- | -------------------------------------------------------- | --------------------- | ------------------------- |
+| **Onboarding** | `/api/onboarding/*`                                      | `status != COMPLETED` | `410 Gone`                |
+| **Management** | `/api/*` (except health, onboarding, invite, and enroll) | `status == COMPLETED` | `503 Service Unavailable` |
+| **Public**     | `/api/invite/*`, `/api/enroll`                           | Always (no mTLS)      | N/A                       |
+
+The `GET /api/onboarding/status` endpoint is always accessible regardless of onboarding state. The `GET /api/health` endpoint is also always accessible — it is registered outside both guards. The `/api/invite/*` and `/api/enroll` routes are registered in a separate public context with no mTLS middleware and no onboarding guard.
+
+**410 response (onboarding complete):**
+
+```json
+{
+  "error": "Onboarding already completed"
+}
+```
+
+**503 response (onboarding incomplete):**
+
+```json
+{
+  "error": "Onboarding not complete",
+  "onboardingStatus": "FRESH"
+}
+```
+
+### Onboarding States
+
+The onboarding progresses through a linear state machine:
+
+```
+FRESH → DOMAIN_SET → DNS_READY → PROVISIONING → COMPLETED
+```
+
+Each state transition is triggered by a specific API call and validated server-side. You cannot skip states.
+
+## CORS Policy
+
+Cross-Origin Resource Sharing is configured to accept requests from the panel UI origins:
+
+- **Before domain setup:** `https://<droplet-ip>:9292`
+- **After domain setup:** both `https://<droplet-ip>:9292` and `https://panel.<domain>`
+
+Requests from other origins are rejected by the CORS policy.
+
+## WebSocket Connections
+
+Two endpoints use WebSocket for real-time streaming:
+
+| Endpoint                              | Purpose                  | Protocol      |
+| ------------------------------------- | ------------------------ | ------------- |
+| `WS /api/onboarding/provision/stream` | Provisioning progress    | JSON messages |
+| `WS /api/services/:name/logs`         | Live service log tailing | JSON messages |
+
+WebSocket connections follow the standard upgrade handshake over the same HTTPS connection. The `wss://` protocol is used in production since all traffic goes through nginx with TLS.
+
+WebSocket messages are always JSON objects. There is no binary framing.
+
+## Common Response Patterns
+
+### Success with Data
+
+Most GET endpoints return the requested resource directly:
+
+```json
+{
+  "tunnels": [{ "id": "...", "subdomain": "app", "port": 8080 }]
+}
+```
+
+### Success with Confirmation
+
+Mutating endpoints typically return an `ok` field:
+
+```json
+{
+  "ok": true,
+  "tunnel": { "id": "...", "subdomain": "app", "port": 8080 }
+}
+```
+
+### Success with Warning
+
+Some operations succeed but produce a non-fatal warning (for example, nginx reload failure after certificate renewal):
+
+```json
+{
+  "ok": true,
+  "domain": "app.example.com",
+  "newExpiry": "2026-06-11T00:00:00.000Z",
+  "warning": "Certificate renewed but nginx reload failed"
+}
+```
+
+## File Upload Limits
+
+The server accepts multipart file uploads up to 50 MB per file, used by the static sites file management endpoints.
+
+## Rate Limiting
+
+There is no general application-level rate limiting. The mTLS requirement means only authenticated administrators can reach the API, and the expected number of concurrent users is one or two. If you are self-hosting and want rate limits, configure them in nginx.
+
+There are two exceptions:
+
+- **2FA endpoints** (`/confirm`, `/verify`, `/disable`) enforce per-IP rate limiting: 5 attempts per 2-minute window, with a 5-minute ban once the limit is exceeded. This protects against brute-force TOTP guessing even though the caller already holds a valid mTLS certificate.
+- **Ticket requests** (`POST /api/tickets`) enforce per-agent rate limiting: 10 tickets per minute per agent. This protects against resource exhaustion from automated ticket generation.
+
+## Quick Reference
+
+| Item                        | Value                                  |
+| --------------------------- | -------------------------------------- |
+| **Base URL (IP)**           | `https://<ip>:9292/api`                |
+| **Base URL (domain)**       | `https://panel.<domain>/api`           |
+| **Authentication**          | mTLS client certificate                |
+| **Content-Type**            | `application/json` (default)           |
+| **Validation**              | Zod schemas at route level             |
+| **Error format**            | `{ "error": "...", "details": {...} }` |
+| **WebSocket protocol**      | `wss://` with JSON messages            |
+| **Max upload size**         | 50 MB per file                         |
+| **Internal listen address** | `127.0.0.1:3100`                       |
+
+### Endpoint Summary
+
+| Method | Path                                                  | Group      | Description                              |
+| ------ | ----------------------------------------------------- | ---------- | ---------------------------------------- |
+| GET    | `/api/health`                                         | Always     | Health check                             |
+| GET    | `/api/onboarding/status`                              | Always     | Onboarding state                         |
+| POST   | `/api/onboarding/domain`                              | Onboarding | Set domain and email                     |
+| POST   | `/api/onboarding/verify-dns`                          | Onboarding | Verify DNS records                       |
+| POST   | `/api/onboarding/provision`                           | Onboarding | Start provisioning                       |
+| WS     | `/api/onboarding/provision/stream`                    | Onboarding | Provisioning progress                    |
+| GET    | `/api/invite/:token`                                  | Public     | Get invitation details                   |
+| POST   | `/api/invite/:token/accept`                           | Public     | Accept invitation                        |
+| POST   | `/api/enroll`                                         | Public     | Enroll agent with token (hardware-bound) |
+| GET    | `/api/system/stats`                                   | Management | System statistics                        |
+| POST   | `/api/system/update`                                  | Management | Trigger background server update         |
+| POST   | `/api/agents/plugins/report`                          | Management | Report agent plugin capabilities         |
+| GET    | `/api/agents/me/chisel-credential`                    | Management | The calling agent's Chisel credential    |
+| POST   | `/api/agents/me/chisel-credential/rotate`             | Management | Rotate own Chisel credential (agent)     |
+| POST   | `/api/agents/:label/chisel-credential/rotate`         | Management | Rotate an agent's Chisel credential      |
+| GET    | `/api/tunnels/agent-config`                           | Management | One agent's tunnel configuration         |
+| GET    | `/api/tunnels`                                        | Management | List tunnels                             |
+| POST   | `/api/tunnels`                                        | Management | Create tunnel                            |
+| PATCH  | `/api/tunnels/:id`                                    | Management | Move, access mode, body limit, enable    |
+| DELETE | `/api/tunnels/:id`                                    | Management | Delete tunnel                            |
+| GET    | `/api/sites`                                          | Management | List static sites                        |
+| POST   | `/api/sites`                                          | Management | Create static site                       |
+| DELETE | `/api/sites/:id`                                      | Management | Delete static site                       |
+| PATCH  | `/api/sites/:id`                                      | Management | Update site settings                     |
+| POST   | `/api/sites/:id/verify-dns`                           | Management | Verify site DNS                          |
+| GET    | `/api/sites/:id/files`                                | Management | List site files                          |
+| POST   | `/api/sites/:id/files`                                | Management | Upload site files                        |
+| DELETE | `/api/sites/:id/files`                                | Management | Delete site file                         |
+| GET    | `/api/invitations`                                    | Management | List invitations                         |
+| POST   | `/api/invitations`                                    | Management | Create invitation                        |
+| DELETE | `/api/invitations/:id`                                | Management | Revoke invitation                        |
+| GET    | `/api/users`                                          | Management | List users                               |
+| POST   | `/api/users`                                          | Management | Create user                              |
+| PUT    | `/api/users/:username`                                | Management | Update user                              |
+| DELETE | `/api/users/:username`                                | Management | Delete user                              |
+| POST   | `/api/users/:username/reset-totp`                     | Management | Reset TOTP secret                        |
+| GET    | `/api/certs`                                          | Management | List certificates                        |
+| GET    | `/api/certs/auto-renew-status`                        | Management | Auto-renew timer status                  |
+| POST   | `/api/certs/:domain/renew`                            | Management | Force-renew certificate                  |
+| POST   | `/api/certs/mtls/rotate`                              | Management | Rotate mTLS cert                         |
+| GET    | `/api/certs/mtls/download`                            | Management | Download client.p12                      |
+| POST   | `/api/certs/agent`                                    | Management | Generate agent certificate               |
+| GET    | `/api/certs/agent`                                    | Management | List agent certificates                  |
+| GET    | `/api/certs/agent/:label/download`                    | Management | Download agent .p12                      |
+| PATCH  | `/api/certs/agent/:label/capabilities`                | Management | Update agent capabilities                |
+| PATCH  | `/api/certs/agent/:label/allowed-sites`               | Management | Update agent site access                 |
+| DELETE | `/api/certs/agent/:label`                             | Management | Revoke agent certificate                 |
+| POST   | `/api/certs/agent/enroll`                             | Management | Generate enrollment token                |
+| DELETE | `/api/certs/agent/enroll/:label`                      | Management | Revoke unused enrollment token           |
+| POST   | `/api/certs/agent/upgrade-cert`                       | Management | Upgrade agent cert to hardware-bound     |
+| POST   | `/api/certs/admin/upgrade-to-hardware-bound`          | Management | Upgrade admin to hardware-bound          |
+| GET    | `/api/certs/admin/auth-mode`                          | Management | Get admin auth mode                      |
+| GET    | `/api/settings/2fa`                                   | Management | Get 2FA status                           |
+| POST   | `/api/settings/2fa/setup`                             | Management | Generate TOTP secret                     |
+| POST   | `/api/settings/2fa/confirm`                           | Management | Confirm initial code, enable 2FA         |
+| POST   | `/api/settings/2fa/verify`                            | Management | Verify code, issue session cookie        |
+| POST   | `/api/settings/2fa/disable`                           | Management | Disable 2FA                              |
+| GET    | `/api/services`                                       | Management | List service statuses                    |
+| POST   | `/api/services/:name/:action`                         | Management | Control a service (start/stop/restart)   |
+| WS     | `/api/services/:name/logs`                            | Management | Stream service logs                      |
+| GET    | `/api/plugins`                                        | Management | List installed plugins                   |
+| GET    | `/api/plugins/:name`                                  | Management | Get plugin details                       |
+| POST   | `/api/plugins/install`                                | Management | Install a plugin                         |
+| POST   | `/api/plugins/:name/enable`                           | Management | Enable a plugin                          |
+| POST   | `/api/plugins/:name/disable`                          | Management | Disable a plugin                         |
+| DELETE | `/api/plugins/:name`                                  | Management | Uninstall a plugin                       |
+| GET    | `/api/plugins/push-install/config`                    | Management | Get push install configuration           |
+| PATCH  | `/api/plugins/push-install/config`                    | Management | Update push install configuration        |
+| GET    | `/api/plugins/push-install/policies`                  | Management | List push install policies               |
+| POST   | `/api/plugins/push-install/policies`                  | Management | Create push install policy               |
+| PATCH  | `/api/plugins/push-install/policies/:id`              | Management | Update push install policy               |
+| DELETE | `/api/plugins/push-install/policies/:id`              | Management | Delete push install policy               |
+| POST   | `/api/plugins/push-install/enable/:label`             | Management | Enable push install for agent            |
+| DELETE | `/api/plugins/push-install/enable/:label`             | Management | Disable push install for agent           |
+| GET    | `/api/plugins/push-install/agent-status`              | Management | Agent checks own push install status     |
+| POST   | `/api/plugins/push-install/:label`                    | Management | Send push install command to agent       |
+| GET    | `/api/plugins/push-install/sessions`                  | Management | List push install audit log              |
+| POST   | `/api/tickets/scopes`                                 | Management | Register ticket scope                    |
+| GET    | `/api/tickets/scopes`                                 | Management | List scopes, instances, assignments      |
+| DELETE | `/api/tickets/scopes/:name`                           | Management | Delete ticket scope                      |
+| POST   | `/api/tickets/instances`                              | Management | Register instance                        |
+| DELETE | `/api/tickets/instances/:instanceId`                  | Management | Deregister instance                      |
+| POST   | `/api/tickets/instances/:instanceId/heartbeat`        | Management | Instance heartbeat                       |
+| POST   | `/api/tickets/assignments`                            | Management | Assign agent to instance                 |
+| DELETE | `/api/tickets/assignments/:agentLabel/:instanceScope` | Management | Remove assignment                        |
+| GET    | `/api/tickets/assignments`                            | Management | List assignments                         |
+| POST   | `/api/tickets`                                        | Management | Request ticket                           |
+| GET    | `/api/tickets/inbox`                                  | Management | Check ticket inbox                       |
+| POST   | `/api/tickets/validate`                               | Management | Validate and consume ticket              |
+| GET    | `/api/tickets`                                        | Management | List all tickets (admin)                 |
+| DELETE | `/api/tickets/:ticketId`                              | Management | Revoke ticket                            |
+| POST   | `/api/tickets/sessions`                               | Management | Create session from ticket               |
+| POST   | `/api/tickets/sessions/:sessionId/heartbeat`          | Management | Session heartbeat                        |
+| PATCH  | `/api/tickets/sessions/:sessionId`                    | Management | Update session status                    |
+| DELETE | `/api/tickets/sessions/:sessionId`                    | Management | Kill session                             |
+| GET    | `/api/tickets/sessions`                               | Management | List sessions                            |
+| POST   | `/api/storage/servers`                                | Management | Register a storage server                |
+| GET    | `/api/storage/servers`                                | Management | List registered storage servers          |
+| DELETE | `/api/storage/servers/:id`                            | Management | Remove a storage server                  |
+| POST   | `/api/storage/bindings`                               | Management | Bind storage to plugin                   |
+| GET    | `/api/storage/bindings`                               | Management | List all bindings                        |
+| GET    | `/api/storage/bindings/:pluginName`                   | Management | Get binding for plugin                   |
+| DELETE | `/api/storage/bindings/:pluginName`                   | Management | Unbind storage from plugin               |
+
+### Agent Capabilities
+
+Agent certificates use capability-based access control. Base capabilities are always available; plugins can declare additional capabilities in their manifest.
+
+**Base capabilities:**
+
+| Capability       | Description                                                              |
+| ---------------- | ------------------------------------------------------------------------ |
+| `tunnels:read`   | List own tunnels, fetch own Chisel config (always-on, cannot be removed) |
+| `tunnels:write`  | Create, update and delete tunnels the agent carries                      |
+| `services:read`  | View service status                                                      |
+| `services:write` | Start, stop, and restart services                                        |
+| `system:read`    | View system stats (CPU, RAM, disk)                                       |
+| `sites:read`     | List sites and browse files                                              |
+| `sites:write`    | Upload and delete files on assigned sites                                |
+| `panel:expose`   | Expose agent management panel at `agent-<label>.<domain>`                |
+| `identity:read`  | Parse Authelia identity headers on plugin routes                         |
+| `identity:query` | Query panel for Authelia user metadata                                   |
+
+**Plugin-declared capabilities:** Plugins can declare additional capabilities in their `lamaste-plugin.json` manifest using either a flat array (`"capabilities": ["scope:action"]`) or a nested object (`"capabilities": { "agent": ["scope:action"] }`). Both formats are normalized to a flat array internally. These are merged with base capabilities and available for assignment to agent certificates. Capabilities are validated dynamically via `getValidCapabilities()`.
+
+**Ticket scope capabilities:** Ticket scopes (registered via `POST /api/tickets/scopes`) declare capabilities that are dynamically merged with base and plugin capabilities. For example, a scope named `shell` declaring `scopes: [{ name: "shell:connect" }]` makes `shell:connect` available for assignment to agent certificates. See the [Tickets API](tickets.md) for details.