@lamalibre/create-lamaste 4.0.0

package/vendor/docs/02-guides/certificate-management.md

@@ -0,0 +1,341 @@
+# Certificate Management
+
+> View, renew, and rotate the TLS and mTLS certificates that secure your Lamaste installation.
+
+## In Plain English
+
+Lamaste uses two types of certificates. The first type, Let's Encrypt certificates, encrypts the connection between visitors and your server — the padlock icon in your browser. These renew automatically. The second type, mTLS client certificates, is your digital ID card for accessing the admin panel. This guide covers how to monitor both types, force a renewal when needed, rotate the client certificate, and import a new one into your browser.
+
+## Prerequisites
+
+- A completed [Lamaste onboarding](onboarding.md)
+- Access to the Lamaste admin panel
+- For mTLS rotation: access to the browser where you import certificates
+
+## Step-by-Step
+
+### 1. Open the Certificates Page
+
+Log in to the Lamaste admin panel at `https://panel.example.com` (or `https://<ip>:9292`).
+
+Click **Certificates** in the sidebar navigation.
+
+The page displays two sections: Let's Encrypt certificates and mTLS certificates. All certificates are sorted by expiry date (soonest first).
+
+### 2. Understanding Certificate Types
+
+**Let's Encrypt certificates** secure the HTTPS connection for your domains:
+
+| Certificate | Domain               | Purpose                         |
+| ----------- | -------------------- | ------------------------------- |
+| Panel       | `panel.example.com`  | Admin panel HTTPS               |
+| Auth        | `auth.example.com`   | Authelia login portal HTTPS     |
+| Tunnel      | `tunnel.example.com` | Chisel WebSocket endpoint HTTPS |
+| Per-tunnel  | `app.example.com`    | Individual tunnel HTTPS         |
+| Per-site    | `blog.example.com`   | Static site HTTPS               |
+
+These are issued during onboarding and when you create tunnels or static sites. They have a 90-day validity and renew automatically via the certbot timer.
+
+**mTLS certificates** authenticate access to the panel:
+
+| Certificate        | Subject            | Purpose                                                |
+| ------------------ | ------------------ | ------------------------------------------------------ |
+| CA certificate     | `CN=Lamaste CA`    | Signs all client certificates (10-year validity)       |
+| Admin certificate  | `CN=admin`         | Full panel access via browser (2-year validity)        |
+| Agent certificates | `CN=agent:<label>` | Scoped access for Mac tunnel clients (2-year validity) |
+| Self-signed TLS    | `CN=<server-ip>`   | IP-based panel HTTPS (10-year validity)                |
+
+The admin certificate is generated during installation. Agent certificates are created on demand through the panel. Neither type auto-renews — you rotate them manually when needed.
+
+### 3. Check Certificate Status
+
+Each certificate in the list shows:
+
+- **Domain or subject** — Which domain the cert covers
+- **Type** — `letsencrypt`, `mtls-ca`, or `mtls-client`
+- **Expires** — The expiry date
+- **Days remaining** — How many days until expiry
+- **Status indicator** — Green (healthy), yellow (expiring within 30 days), red (expired)
+
+The **auto-renewal status** section at the top shows whether the certbot timer is active:
+
+- **Active** — The certbot timer is running and checks for renewals twice daily
+- **Next run** — When the next renewal check is scheduled
+- **Last run** — When the last renewal check occurred
+
+### 4. Renew a Let's Encrypt Certificate
+
+Let's Encrypt certificates renew automatically. You only need to force a renewal if:
+
+- Auto-renewal failed (check the dashboard for certbot timer status)
+- You want to renew immediately rather than waiting
+- A certificate expired and needs reissuing
+
+To force-renew a certificate:
+
+1. Find the certificate in the list.
+2. Click the **Renew** button next to it.
+3. The panel runs `certbot renew --cert-name <domain> --force-renewal --no-random-sleep-on-renew` (through its root-owned `lamaste-certbot` wrapper). The renewal starts immediately — certbot's usual random delay before a non-interactive renewal is skipped.
+4. After renewal, nginx is reloaded to use the new certificate.
+
+**Expected duration:** 10-30 seconds. Certbot contacts Let's Encrypt to verify domain ownership and issue a new certificate.
+
+**If renewal fails:**
+
+- **DNS issue:** The domain must still resolve to your server. Verify with `dig <domain>`.
+- **Rate limit:** Let's Encrypt has rate limits (50 certificates per registered domain per week). If you hit a limit, wait and try again later.
+- **Port 80 blocked:** Certbot's nginx plugin validates with HTTP-01 challenges on port 80, for renewals as well as first issuance. Lamaste's UFW rules allow port 80; check that no provider-level firewall blocks it. The port-80 redirect site Lamaste installs does not interfere — certbot answers its challenges ahead of the redirect.
+
+### 5. Rotate the mTLS Client Certificate
+
+The client certificate has a 2-year validity. When it approaches expiry, or if you want to revoke access from a previously exported certificate, rotate it.
+
+**Before rotating:** Understand that rotation generates a new client certificate. The old certificate stops working immediately after you rotate. Make sure you are prepared to import the new certificate into your browser right away.
+
+The panel does not issue admin certificates: it runs unprivileged and signs only agent certificates, so a compromised panel cannot mint an admin credential. **Rotate Client Certificate** in the panel (`POST /api/certs/mtls/rotate`) answers `503` with this instruction. Rotate on the server console instead:
+
+```bash
+sudo lamaste-server reset-admin
+```
+
+**What happens during rotation:**
+
+1. A new 4096-bit RSA key and a CSR for `/CN=admin/O=Lamaste` are generated, and the CA signs the new certificate (2-year validity). These `openssl` steps run as the `lamaste` user, which owns the PKI directory.
+2. A new PKCS12 bundle is created with a new random password.
+3. The current key, certificate and `.p12` are backed up (`.bak` suffix) and replaced.
+4. The old admin certificate is revoked, panel 2FA is cleared and the IP vhost re-enabled if 2FA had disabled it, and `adminAuthMode` is set back to `p12`.
+5. The panel is restarted, nginx is reloaded, and the new `.p12` password and an `scp` command are printed.
+
+### 6. Download the New Certificate
+
+After rotation, download the new `.p12` file:
+
+1. Click the **Download** button on the Certificates page.
+2. Save the `client.p12` file.
+
+Alternatively, use SCP from the command line (requires SSH access):
+
+```bash
+scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .
+```
+
+The new `.p12` password is printed by `lamaste-server reset-admin`. Save it.
+
+### 7. Import the New Certificate into Your Browser
+
+Remove the old certificate first, then import the new one.
+
+**macOS:**
+
+1. Open **Keychain Access** (Applications, Utilities, Keychain Access).
+2. Select the **System** keychain.
+3. Find the old "admin" certificate under "My Certificates".
+4. Right-click and delete it.
+5. Double-click the new `client.p12` file.
+6. Select the **System** keychain.
+7. Enter the new certificate password.
+8. Find the new certificate, double-click it, expand Trust, set to **Always Trust**.
+
+**Chrome on Linux:**
+
+1. Navigate to `chrome://settings/certificates`.
+2. Under "Your Certificates", find and delete the old Lamaste certificate.
+3. Click **Import** and select the new `client.p12` file.
+4. Enter the password.
+
+**Windows:**
+
+1. Open the Certificate Manager (`certmgr.msc`).
+2. Navigate to Personal, Certificates.
+3. Find and delete the old admin certificate.
+4. Double-click the new `client.p12` file.
+5. Follow the Certificate Import Wizard.
+
+After importing, refresh the panel page. Your browser presents the new certificate automatically.
+
+### 8. Verify the New Certificate
+
+After importing:
+
+1. Close and reopen your browser (recommended for macOS).
+2. Navigate to `https://panel.example.com` or `https://<ip>:9292`.
+3. Your browser prompts you to select a certificate — choose the new "admin" certificate.
+4. The panel loads normally.
+
+If the panel does not load, the most likely cause is that the old certificate is still being presented. Clear the SSL state in your browser:
+
+- **Chrome:** Settings, Privacy and Security, Security, Manage Certificates
+- **Firefox:** Preferences, Privacy & Security, View Certificates
+- **Safari:** Restart Safari (it picks up Keychain changes automatically)
+
+## Agent Certificates
+
+Agent certificates provide scoped access for Mac tunnel clients. Instead of sharing the admin certificate (which grants full panel access), generate a dedicated agent certificate with only the capabilities the agent needs.
+
+### Why Agent Certificates?
+
+The admin certificate (`CN=admin`) has unrestricted access to all panel endpoints. Giving it to a Mac running the Chisel tunnel client is a security risk — if the Mac is compromised, the attacker has full admin access. Agent certificates solve this by limiting what each client can do.
+
+### Generate an Agent Certificate
+
+1. Go to the **Certificates** page in the panel.
+2. Scroll to the **Agent Certificates** section.
+3. Click **Generate**.
+4. Enter a label (e.g., `macbook-pro`, `office-imac`). Labels must be lowercase letters, numbers, and hyphens only.
+5. Select capabilities:
+   - **tunnels:read** — always enabled, cannot be removed. Allows listing the agent's own tunnels and fetching its Chisel configuration.
+   - **tunnels:write** — create, update and delete tunnels the agent carries (restricted access mode only; moving a tunnel between agents stays admin-only).
+   - **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.
+6. Click **Generate**.
+7. **Save the P12 password immediately** — it is only shown once and cannot be retrieved later.
+8. Click **Download** to save the `.p12` file.
+
+### Distribute to the Agent Machine
+
+Send the `.p12` file and password to the agent machine (macOS or Linux) securely, and install the agent there with `npm install -g @lamalibre/lamaste-agent@4.0.0` and run `lamaste-agent setup --label <label>` — or import it into the Desktop App. An enrollment token is preferable where possible, because the private key is then generated on the agent and never travels. See [Agent Setup](agent-setup.md) for details.
+
+### Update Capabilities
+
+Capabilities are stored server-side, not in the certificate. You can change what an agent is allowed to do without reissuing the certificate:
+
+1. Find the agent in the **Agent Certificates** table.
+2. Click the **Edit** (pencil) icon.
+3. Check or uncheck capabilities.
+4. Click **Save**.
+
+The change takes effect on the agent's next API request.
+
+### Revoke an Agent Certificate
+
+If a Mac is lost, stolen, or no longer needs access:
+
+1. Find the agent in the **Agent Certificates** table.
+2. Click the **Revoke** (trash) icon.
+3. Confirm the revocation.
+
+Revocation is immediate — the certificate serial is added to a revocation list checked on every request. The agent's P12 files are deleted from the server.
+
+## For Developers
+
+### Certificate File Locations
+
+| File                | Path                                                   | Permission      |
+| ------------------- | ------------------------------------------------------ | --------------- |
+| CA key              | `/etc/lamalibre/lamaste/pki/ca.key`                    | 600             |
+| CA certificate      | `/etc/lamalibre/lamaste/pki/ca.crt`                    | 644             |
+| Client key          | `/etc/lamalibre/lamaste/pki/client.key`                | 600             |
+| Client certificate  | `/etc/lamalibre/lamaste/pki/client.crt`                | 644             |
+| PKCS12 bundle       | `/etc/lamalibre/lamaste/pki/client.p12`                | 600             |
+| P12 password        | `/etc/lamalibre/lamaste/pki/.p12-password`             | 600             |
+| Self-signed key     | `/etc/lamalibre/lamaste/pki/self-signed-key.pem`       | 600             |
+| Self-signed cert    | `/etc/lamalibre/lamaste/pki/self-signed.pem`           | 644             |
+| Let's Encrypt certs | `/etc/letsencrypt/live/<domain>/`                      | certbot-managed |
+| Revocation list     | `/etc/lamalibre/lamaste/pki/revoked.json`              | 600             |
+| Agent registry      | `/etc/lamalibre/lamaste/pki/agents/registry.json`      | 600             |
+| Agent certs         | `/etc/lamalibre/lamaste/pki/agents/<label>/client.p12` | 600             |
+
+### API Endpoints
+
+| Method   | Path                                         | Purpose                            |
+| -------- | -------------------------------------------- | ---------------------------------- |
+| `GET`    | `/api/certs`                                 | List all certificates (LE + mTLS)  |
+| `GET`    | `/api/certs/auto-renew-status`               | Certbot timer status               |
+| `POST`   | `/api/certs/:domain/renew`                   | Force-renew a Let's Encrypt cert   |
+| `POST`   | `/api/certs/mtls/rotate`                     | Rotate the mTLS client certificate |
+| `GET`    | `/api/certs/mtls/download`                   | Download client.p12                |
+| `POST`   | `/api/certs/agent`                           | Generate agent certificate         |
+| `GET`    | `/api/certs/agent`                           | List agent certificates            |
+| `GET`    | `/api/certs/agent/:label/download`           | Download agent .p12                |
+| `PATCH`  | `/api/certs/agent/:label/capabilities`       | Update agent capabilities          |
+| `PATCH`  | `/api/certs/agent/:label/allowed-sites`      | Update agent site access           |
+| `DELETE` | `/api/certs/agent/:label`                    | Revoke agent certificate           |
+| `POST`   | `/api/certs/agent/enroll`                    | Generate enrollment token (admin)  |
+| `POST`   | `/api/enroll`                                | Enroll agent with token (public)   |
+| `POST`   | `/api/certs/admin/upgrade-to-hardware-bound` | Upgrade admin auth (admin)         |
+| `GET`    | `/api/certs/admin/auth-mode`                 | Get admin auth mode (admin)        |
+
+### Certificate Response Format
+
+```json
+{
+  "certs": [
+    {
+      "type": "letsencrypt",
+      "domain": "panel.example.com",
+      "expiresAt": "2024-04-15T00:00:00.000Z",
+      "daysUntilExpiry": 75,
+      "path": "/etc/letsencrypt/live/panel.example.com/fullchain.pem",
+      "expiringSoon": false
+    },
+    {
+      "type": "mtls-ca",
+      "domain": null,
+      "expiresAt": "2034-01-15T00:00:00.000Z",
+      "daysUntilExpiry": 3650,
+      "path": "/etc/lamalibre/lamaste/pki/ca.crt",
+      "expiringSoon": false
+    },
+    {
+      "type": "mtls-client",
+      "domain": null,
+      "expiresAt": "2028-01-15T00:00:00.000Z",
+      "daysUntilExpiry": 730,
+      "path": "/etc/lamalibre/lamaste/pki/client.crt",
+      "expiringSoon": false
+    }
+  ]
+}
+```
+
+### mTLS Rotation Internals
+
+Admin certificate rotation lives only in `lamaste-server reset-admin` (`packages/server/cli/src/commands/reset-admin.js`), run as root on the server. The panel's `rotateClientCert()` in `lib/mtls.js` is a stub that returns `503` with that instruction; `@lamalibre/lamaste@4.0.0/server` no longer exports a rotation function. The PKI directory belongs to `lamaste`, so `reset-admin` runs every file operation inside it (`openssl genrsa`/`req`/`x509 -req`/`pkcs12`, `cp`, `chmod`) as `lamaste`, and writes `panel.json` and `revoked.json` as fresh files renamed into place — root never writes through a path the panel could have replaced with a symlink.
+
+The PKCS12 bundle uses legacy encryption settings (`-keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1`) because newer OpenSSL defaults produce files that macOS Keychain Access cannot import.
+
+### Auto-Renewal Architecture
+
+Certbot auto-renewal uses a systemd timer (`certbot.timer` or `certbot-renew.timer`, depending on the distribution). The timer runs twice daily and checks all managed certificates. Certificates within 30 days of expiry are renewed. After renewal, the certbot deploy hook reloads nginx to use the new certificate.
+
+### nginx mTLS Snippet
+
+The mTLS configuration is in `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`:
+
+```nginx
+ssl_client_certificate /etc/lamalibre/lamaste/pki/ca.crt;
+ssl_verify_client on;
+```
+
+This tells nginx to require a client certificate signed by the Lamaste CA. No certificate means the TLS handshake is rejected before HTTP — the browser never reaches the panel server.
+
+## Quick Reference
+
+| Certificate Type  | Validity | Renewal                                   |
+| ----------------- | -------- | ----------------------------------------- |
+| Let's Encrypt     | 90 days  | Automatic (certbot timer)                 |
+| mTLS CA           | 10 years | Manual (rarely needed)                    |
+| Admin client cert | 2 years  | Manual: `sudo lamaste-server reset-admin` |
+| Agent certs       | 2 years  | Generate new, revoke old                  |
+| Self-signed TLS   | 10 years | Manual (rarely needed)                    |
+
+| Action                  | How                                                |
+| ----------------------- | -------------------------------------------------- |
+| **View all certs**      | Certificates page in panel                         |
+| **Force renew LE cert** | Click "Renew" next to the certificate              |
+| **Rotate mTLS cert**    | `sudo lamaste-server reset-admin` on the server    |
+| **Download new .p12**   | Click "Download" after rotation                    |
+| **Check auto-renewal**  | View "Auto-Renewal Status" section                 |
+| **Generate agent cert** | Agent Certificates section, click "Generate"       |
+| **Update agent caps**   | Click edit icon next to agent, toggle capabilities |
+| **Revoke agent cert**   | Click revoke icon next to agent, confirm           |
+
+| Warning Sign             | Action                                  |
+| ------------------------ | --------------------------------------- |
+| Yellow badge (< 30 days) | Monitor — auto-renewal should handle it |
+| Red badge (expired)      | Force-renew immediately                 |
+| Auto-renewal inactive    | Check certbot timer with Services page  |
+| mTLS < 90 days           | Plan rotation, download new cert        |