@lamalibre/create-lamaste 4.3.0 → 4.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/scripts/bundle-vendor.js +13 -8
- package/src/index.js +4 -0
- package/src/lib/panel-pin.js +41 -0
- package/src/lib/service-config.js +6 -0
- package/vendor/docs/00-introduction/how-it-works.md +2 -2
- package/vendor/docs/00-introduction/quickstart.md +5 -5
- package/vendor/docs/00-introduction/what-is-lamaste.md +5 -5
- package/vendor/docs/01-concepts/certificates.md +3 -3
- package/vendor/docs/01-concepts/mtls.md +2 -2
- package/vendor/docs/01-concepts/security-model.md +50 -2
- package/vendor/docs/01-concepts/tickets.md +2 -2
- package/vendor/docs/01-concepts/tunneling.md +4 -4
- package/vendor/docs/02-guides/agent-setup.md +6 -6
- package/vendor/docs/02-guides/certificate-management.md +2 -2
- package/vendor/docs/02-guides/cloud-provisioning.md +4 -4
- package/vendor/docs/02-guides/desktop-app-setup.md +12 -11
- package/vendor/docs/02-guides/installation.md +3 -3
- package/vendor/docs/02-guides/onboarding.md +2 -2
- package/vendor/docs/02-guides/standalone-plugin-with-tickets.md +2 -2
- package/vendor/docs/03-architecture/installer-flow.md +2 -2
- package/vendor/docs/03-architecture/installer.md +4 -4
- package/vendor/docs/03-architecture/management-flow.md +1 -1
- package/vendor/docs/03-architecture/overview.md +5 -5
- package/vendor/docs/03-architecture/panel-client.md +7 -7
- package/vendor/docs/03-architecture/panel-server.md +2 -2
- package/vendor/docs/03-architecture/state-management.md +2 -2
- package/vendor/docs/03-architecture/system-overview.md +1 -1
- package/vendor/docs/04-api-reference/agent-hosted-plugins.md +393 -33
- package/vendor/docs/04-api-reference/app-host.md +87 -38
- package/vendor/docs/04-api-reference/audit-and-notifications.md +10 -10
- package/vendor/docs/04-api-reference/certificates.md +22 -19
- package/vendor/docs/04-api-reference/lifecycle-hooks.md +33 -11
- package/vendor/docs/04-api-reference/onboarding.md +1 -1
- package/vendor/docs/04-api-reference/overview.md +137 -135
- package/vendor/docs/04-api-reference/registry-and-oidc.md +1 -1
- package/vendor/docs/04-api-reference/tunnels.md +14 -10
- package/vendor/docs/05-operations/backup-and-restore.md +4 -1
- package/vendor/docs/05-operations/uninstalling.md +1 -1
- package/vendor/docs/05-operations/upgrades.md +6 -6
- package/vendor/docs/06-reference/config-files.md +94 -84
- package/vendor/docs/06-reference/glossary.md +3 -3
- package/vendor/docs/06-reference/installer-flags.md +13 -13
- package/vendor/docs/06-reference/ports-and-services.md +1 -1
- package/vendor/docs/06-reference/troubleshooting.md +8 -8
- package/vendor/docs/gatekeeper-design.md +8 -8
- package/vendor/docs/identity-directory-design.md +2 -2
- package/vendor/docs/package.json +1 -1
- package/vendor/docs/todo/lib-cli-desktop-refactor.md +27 -27
- package/vendor/gatekeeper/dist/cli/index.js +0 -0
- package/vendor/gatekeeper/package.json +2 -2
- package/vendor/server/bin/lamaste-server.js +11 -1
- package/vendor/server/package.json +4 -3
- package/vendor/server/src/commands/panel-pin.js +40 -0
- package/vendor/server/src/commands/plugin-settings.js +541 -0
- package/vendor/server/src/commands/plugins.js +94 -27
- package/vendor/server/src/panel-api.js +281 -34
- package/vendor/server/src/panel-identity.js +165 -0
- package/vendor/server/src/plugin-approval.js +78 -0
- package/vendor/server/src/plugin-settings.js +699 -0
- package/vendor/server-ui/dist/assets/index-25wo_8av.css +1 -0
- package/vendor/server-ui/dist/assets/index-CESyyK8V.js +84 -0
- package/vendor/server-ui/dist/index.html +2 -2
- package/vendor/serverd/package.json +2 -2
- package/vendor/serverd/src/index.js +9 -0
- package/vendor/serverd/src/lib/agent-presence.js +106 -0
- package/vendor/serverd/src/lib/hook-pipelines.js +20 -4
- package/vendor/serverd/src/lib/migrations/state/0012_plugin_settings_and_presence.sql +62 -0
- package/vendor/serverd/src/lib/mtls.js +44 -4
- package/vendor/serverd/src/lib/plugin-hooks.js +120 -20
- package/vendor/serverd/src/lib/plugin-hosting.js +35 -14
- package/vendor/serverd/src/lib/plugin-lifecycle.js +267 -83
- package/vendor/serverd/src/lib/plugin-settings.js +1101 -0
- package/vendor/serverd/src/lib/plugins.js +73 -22
- package/vendor/serverd/src/lib/tunnel-hooks.js +11 -0
- package/vendor/serverd/src/routes/management/plugins.js +166 -19
- package/vendor/serverd/src/routes/management/tunnels.js +21 -1
- package/vendor/server-ui/dist/assets/index-Bc5NCMSv.css +0 -1
- package/vendor/server-ui/dist/assets/index-DBp3cmaU.js +0 -84
|
@@ -26,7 +26,7 @@ The Lamaste Desktop app is a native application (built with Tauri) that wraps th
|
|
|
26
26
|
Run the installer:
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
npx @lamalibre/create-lamaste-desktop@4.
|
|
29
|
+
npx @lamalibre/create-lamaste-desktop@4.4.0
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
The installer:
|
|
@@ -56,11 +56,11 @@ After the app launches, it shows a setup screen with two options:
|
|
|
56
56
|
Install the agent globally and run its setup command:
|
|
57
57
|
|
|
58
58
|
```bash
|
|
59
|
-
npm install -g @lamalibre/lamaste-agent@4.
|
|
59
|
+
npm install -g @lamalibre/lamaste-agent@4.4.0
|
|
60
60
|
lamaste-agent setup --label my-server
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
The agent must be a global install — setup installs a sync timer that runs it every 30 seconds to pick up tunnel changes, and refuses to run from `npx`. (When the app sets up an agent itself, it installs `@lamalibre/lamaste-agent@4.
|
|
63
|
+
The agent must be a global install — setup installs a sync timer that runs it every 30 seconds to pick up tunnel changes, and refuses to run from `npx`. (When the app sets up an agent itself, it installs `@lamalibre/lamaste-agent@4.4.0` globally for you.) The `--label` flag names this agent connection (used for multi-agent support). This command connects to your VPS panel using the agent certificate and configures the local Chisel client. During setup, the client certificate and key are extracted from the P12 bundle for mTLS client authentication. Once setup completes, the app detects the configuration and switches to the main interface.
|
|
64
64
|
|
|
65
65
|
**Option B: Create a new server**
|
|
66
66
|
|
|
@@ -72,7 +72,7 @@ The desktop app has two modes, toggled via a pill switch in the sidebar header.
|
|
|
72
72
|
|
|
73
73
|
### Agent Mode (default)
|
|
74
74
|
|
|
75
|
-
Agent mode provides local agent management. The agent-mode pages (Dashboard, Tunnels, Services, Plugins, Logs, Settings) are imported from the shared `@lamalibre/lamaste-agent-ui@4.
|
|
75
|
+
Agent mode provides local agent management. The agent-mode pages (Dashboard, Tunnels, Services, Plugins, Logs, Settings) are imported from the shared `@lamalibre/lamaste-agent-ui@4.4.0` package. The landing page is the **Agents** list, showing all configured agents with their connection status. Click an agent to drill into its management pages:
|
|
76
76
|
|
|
77
77
|
- **Agents** (landing) — list of all configured agents with start/stop controls and status
|
|
78
78
|
- **Dashboard** — per-agent connection status, Chisel version, start/stop/restart controls
|
|
@@ -84,7 +84,7 @@ Agent mode provides local agent management. The agent-mode pages (Dashboard, Tun
|
|
|
84
84
|
|
|
85
85
|
### Server Mode
|
|
86
86
|
|
|
87
|
-
Server mode provides the full admin panel — the same management pages available in the browser-based panel UI. These pages are imported from the shared `@lamalibre/lamaste-server-ui@4.
|
|
87
|
+
Server mode provides the full admin panel — the same management pages available in the browser-based panel UI. These pages are imported from the shared `@lamalibre/lamaste-server-ui@4.4.0` package:
|
|
88
88
|
|
|
89
89
|
- **Dashboard** — system stats (CPU, RAM, disk, uptime) + service health
|
|
90
90
|
- **Tunnels** — tunnel CRUD, carrying agent, access mode, body limit
|
|
@@ -93,7 +93,7 @@ Server mode provides the full admin panel — the same management pages availabl
|
|
|
93
93
|
- **Users** — Authelia user CRUD + TOTP enrollment
|
|
94
94
|
- **Certificates** — Let's Encrypt + mTLS cert listing + renewal + rotation
|
|
95
95
|
- **Tickets** — agent-to-agent authorization scope and session management
|
|
96
|
-
- **Plugins** — plugin management + push install UI
|
|
96
|
+
- **Plugins** — plugin management + push install UI + agent-hosted plugins' hosting, retained data and settings (secrets are sent to the panel in the request body on curl's stdin, never as arguments)
|
|
97
97
|
- **Logs** — live journald log streaming
|
|
98
98
|
- **Settings** — panel configuration, 2FA, admin auth mode
|
|
99
99
|
|
|
@@ -149,6 +149,7 @@ The multi-server management page:
|
|
|
149
149
|
- **Add existing server** — connect to a server you already set up manually by providing the panel URL and certificate
|
|
150
150
|
- **Server switching** — switch the active server; the app reloads configuration and reconnects
|
|
151
151
|
- **Server removal** — remove a server from the registry (cloud-provisioned servers can also be destroyed)
|
|
152
|
+
- **Panel TLS key** — a panel reached at its IP address (`https://<ip>:9292`) has a self-signed certificate, so the app pins its public key: read from the server over SSH when the app provisioned it, otherwise on the first connection. The card shows the pin (`sha256//…`) and where it came from; compare it with `sudo lamaste-server panel-pin` on the server. Every call to the panel must present that key — a different one is refused before anything is sent. After reinstalling a server or replacing its certificate, **Re-pin** shows the key the panel presents now next to the pinned one and replaces it only when you accept. A panel reached at its domain is verified by its Let's Encrypt certificate instead
|
|
152
153
|
|
|
153
154
|
**Cloud provider tokens** are stored in your OS credential store (macOS Keychain or Linux libsecret) — never in plaintext files or process arguments. P12 passwords for each server are also stored in the credential store.
|
|
154
155
|
|
|
@@ -169,7 +170,7 @@ Stopping an agent's tunnels from the app is remembered: the agent's sync timer k
|
|
|
169
170
|
Run the installer again to get the latest version:
|
|
170
171
|
|
|
171
172
|
```bash
|
|
172
|
-
npx @lamalibre/create-lamaste-desktop@4.
|
|
173
|
+
npx @lamalibre/create-lamaste-desktop@4.4.0
|
|
173
174
|
```
|
|
174
175
|
|
|
175
176
|
If a new release is available, it downloads and installs the update. The previous version is replaced.
|
|
@@ -202,9 +203,9 @@ Deleting `~/.lamalibre/lamaste/` by hand instead would leave the agents' service
|
|
|
202
203
|
|
|
203
204
|
| Action | Command / Location |
|
|
204
205
|
| -------------------- | ------------------------------------------------------------------------------------ |
|
|
205
|
-
| **Install** | `npx @lamalibre/create-lamaste-desktop@4.
|
|
206
|
-
| **Update** | `npx @lamalibre/create-lamaste-desktop@4.
|
|
207
|
-
| **Agent setup** | `npm install -g @lamalibre/lamaste-agent@4.
|
|
206
|
+
| **Install** | `npx @lamalibre/create-lamaste-desktop@4.4.0` |
|
|
207
|
+
| **Update** | `npx @lamalibre/create-lamaste-desktop@4.4.0` |
|
|
208
|
+
| **Agent setup** | `npm install -g @lamalibre/lamaste-agent@4.4.0`, then `lamaste-agent setup --label <name>` |
|
|
208
209
|
| **App location** | `/Applications/Lamaste.app` (macOS) |
|
|
209
210
|
| **Agent registry** | `~/.lamalibre/lamaste/agents.json` |
|
|
210
211
|
| **Per-agent data** | `~/.lamalibre/lamaste/agents/<label>/` |
|
|
@@ -215,7 +216,7 @@ Deleting `~/.lamalibre/lamaste/` by hand instead would leave the agents' service
|
|
|
215
216
|
| **Chisel logs** | `~/.lamalibre/lamaste/agents/<label>/logs/chisel.log` |
|
|
216
217
|
| **Cloud tokens** | OS credential store (`com.lamalibre.cloud`) |
|
|
217
218
|
| **P12 passwords** | OS credential store (`com.lamalibre.lamaste.server`) |
|
|
218
|
-
| **npm package** | `@lamalibre/create-lamaste-desktop@4.
|
|
219
|
+
| **npm package** | `@lamalibre/create-lamaste-desktop@4.4.0` |
|
|
219
220
|
|
|
220
221
|
### Related Documentation
|
|
221
222
|
|
|
@@ -62,7 +62,7 @@ Execute the Lamaste installer:
|
|
|
62
62
|
|
|
63
63
|
```bash
|
|
64
64
|
apt install -y npm
|
|
65
|
-
npx @lamalibre/create-lamaste@4.
|
|
65
|
+
npx @lamalibre/create-lamaste@4.4.0
|
|
66
66
|
```
|
|
67
67
|
|
|
68
68
|
The installer displays a confirmation banner before making any changes:
|
|
@@ -90,7 +90,7 @@ The installer displays a confirmation banner before making any changes:
|
|
|
90
90
|
Press Enter to continue or Ctrl+C to abort...
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
-
Press **Enter** to proceed. To skip the confirmation prompt, use `npx @lamalibre/create-lamaste@4.
|
|
93
|
+
Press **Enter** to proceed. To skip the confirmation prompt, use `npx @lamalibre/create-lamaste@4.4.0 --yes`.
|
|
94
94
|
|
|
95
95
|
### 4. What the Installer Does
|
|
96
96
|
|
|
@@ -380,7 +380,7 @@ The service includes security hardening: `ProtectHome=true`, `PrivateTmp=true`,
|
|
|
380
380
|
|
|
381
381
|
| Item | Value |
|
|
382
382
|
| ------------------------ | ------------------------------------------------------------ |
|
|
383
|
-
| **Install command** | `npx @lamalibre/create-lamaste@4.
|
|
383
|
+
| **Install command** | `npx @lamalibre/create-lamaste@4.4.0` |
|
|
384
384
|
| **Minimum VPS** | Ubuntu 24.04, 512 MB RAM |
|
|
385
385
|
| **Required ports** | 22 (SSH), 80 (HTTP/Let's Encrypt), 443 (HTTPS), 9292 (panel) |
|
|
386
386
|
| **Certificate location** | `/etc/lamalibre/lamaste/pki/client.p12` |
|
|
@@ -113,7 +113,7 @@ Chisel is the tunneling engine. The installer already put the pinned Chisel rele
|
|
|
113
113
|
|
|
114
114
|
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`.
|
|
115
115
|
|
|
116
|
-
Onboarding downloads nothing. If either task fails with "… is not installed. Run `npx @lamalibre/create-lamaste@4.
|
|
116
|
+
Onboarding downloads nothing. If either task fails with "… is not installed. Run `npx @lamalibre/create-lamaste@4.4.0` on the server to repair the installation.", re-run the installer on the server (it is idempotent) and start provisioning again.
|
|
117
117
|
|
|
118
118
|
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.
|
|
119
119
|
|
|
@@ -213,7 +213,7 @@ Each provisioning task calls library functions in `packages/lamaste-serverd/src/
|
|
|
213
213
|
|
|
214
214
|
The DNS check resolves these hostnames using Node's `dns.resolve4()`:
|
|
215
215
|
|
|
216
|
-
1. `panel.example.com`, `auth.example.com`, `tunnel.example.com` — must resolve to the server IP (required; `CORE_SUBDOMAINS` in `@lamalibre/lamaste@4.
|
|
216
|
+
1. `panel.example.com`, `auth.example.com`, `tunnel.example.com` — must resolve to the server IP (required; `CORE_SUBDOMAINS` in `@lamalibre/lamaste@4.4.0`)
|
|
217
217
|
2. `test-lamaste-check.example.com` — tests wildcard resolution (optional)
|
|
218
218
|
3. `example.com` — reported, not required
|
|
219
219
|
|
|
@@ -27,7 +27,7 @@ Using the desktop app's cloud provisioning wizard:
|
|
|
27
27
|
|
|
28
28
|
- Enter your DigitalOcean API token
|
|
29
29
|
- Select a region and droplet size
|
|
30
|
-
- The wizard calls `@lamalibre/lamaste-cloud@4.
|
|
30
|
+
- The wizard calls `@lamalibre/lamaste-cloud@4.4.0` to create the droplet
|
|
31
31
|
- Progress streams back as NDJSON events in the desktop UI
|
|
32
32
|
- Complete onboarding in the browser panel
|
|
33
33
|
|
|
@@ -96,7 +96,7 @@ The Sync server now runs as a local service on the Mac. It operates independentl
|
|
|
96
96
|
|
|
97
97
|
### 5. Register Sync Scopes and Instance on Lamaste
|
|
98
98
|
|
|
99
|
-
The Sync server detects that the Mac has a Lamaste agent certificate. Using that cert (mTLS), it registers a ticket scope and instance with the Lamaste panel. This is handled automatically by `TicketInstanceManager` from `@lamalibre/lamaste-tickets@4.
|
|
99
|
+
The Sync server detects that the Mac has a Lamaste agent certificate. Using that cert (mTLS), it registers a ticket scope and instance with the Lamaste panel. This is handled automatically by `TicketInstanceManager` from `@lamalibre/lamaste-tickets@4.4.0` — the admin does not need to do anything.
|
|
100
100
|
|
|
101
101
|
```mermaid
|
|
102
102
|
sequenceDiagram
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Installer Flow
|
|
2
2
|
|
|
3
|
-
## What `npx @lamalibre/create-lamaste@4.
|
|
3
|
+
## What `npx @lamalibre/create-lamaste@4.4.0` Does
|
|
4
4
|
|
|
5
5
|
The installer is a **zero-prompt, fire-and-forget** command. It assumes:
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@ It requires **no user input**. All configuration happens later through the brows
|
|
|
13
13
|
## Execution Flow
|
|
14
14
|
|
|
15
15
|
```
|
|
16
|
-
$ npx @lamalibre/create-lamaste@4.
|
|
16
|
+
$ npx @lamalibre/create-lamaste@4.4.0
|
|
17
17
|
|
|
18
18
|
Lamaste Installer v1.0.0
|
|
19
19
|
|
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
## In Plain English
|
|
6
6
|
|
|
7
|
-
When you run `npx @lamalibre/create-lamaste@4.
|
|
7
|
+
When you run `npx @lamalibre/create-lamaste@4.4.0` on a fresh VPS, the installer takes over and does everything automatically: hardens the OS, installs dependencies, generates security certificates, configures nginx, deploys the panel, and starts the service. It prints a summary with instructions for downloading your client certificate and accessing the panel. No prompts, no questions, no configuration files to edit.
|
|
8
8
|
|
|
9
9
|
The installer is deliberately limited in scope. It sets up just enough to serve the panel UI over a secure connection. Everything else — domain configuration, tunnel setup, user management — happens through the browser-based onboarding wizard after the installer finishes.
|
|
10
10
|
|
|
11
11
|
## Overview
|
|
12
12
|
|
|
13
13
|
```
|
|
14
|
-
npx @lamalibre/create-lamaste@4.
|
|
14
|
+
npx @lamalibre/create-lamaste@4.4.0
|
|
15
15
|
│
|
|
16
16
|
├── bin/create-lamaste.js ← CLI entry point
|
|
17
17
|
│ └── calls main() from src/index.js
|
|
@@ -181,7 +181,7 @@ Six task groups run sequentially through Listr2:
|
|
|
181
181
|
**Chisel and Authelia** (`lib/relay-services.js`, run on install and on every redeploy):
|
|
182
182
|
|
|
183
183
|
- Creates the `lamaste-chisel` group (and adds `lamaste` to it) and the `lamaste-authelia` system account (no login shell, no home)
|
|
184
|
-
- Installs Chisel 1.12.0 and Authelia 4.39.28 to `/usr/local/bin` (`lib/binaries.js`): downloaded from fixed release URLs, verified against the SHA-256 digests pinned in `@lamalibre/lamaste@4.
|
|
184
|
+
- Installs Chisel 1.12.0 and Authelia 4.39.28 to `/usr/local/bin` (`lib/binaries.js`): downloaded from fixed release URLs, verified against the SHA-256 digests pinned in `@lamalibre/lamaste@4.4.0` (`CHISEL_RELEASE`, `AUTHELIA_RELEASE`) before anything is unpacked, staged in a `mkdtemp` directory and renamed into place. A binary already at the pinned version is left alone; an Authelia **newer** than the pin is kept, never downgraded (its database may use a schema the pinned release cannot read)
|
|
185
185
|
- Writes `/etc/systemd/system/chisel.service` (`User=nobody`, `Group=lamaste-chisel`) and `/etc/systemd/system/authelia.service` (`User=lamaste-authelia`, `UMask=027`, `Environment=X_AUTHELIA_CONFIG_FILTERS=template`, `ProtectSystem=strict` with `ReadWritePaths=/etc/authelia /var/log/authelia`, `SystemCallFilter=@system-service`, empty `CapabilityBoundingSet`, `NoNewPrivileges`); both are enabled and started later by onboarding
|
|
186
186
|
- Generates the OpenID Connect issuer key `/etc/authelia/oidc-issuer.pem` if it is missing (`lib/oidc-issuer-key.js`): RSA 4096 generated in the installer process, written by a child process running as `lamaste-authelia` (`wx`, 0600, renamed into place) so root never writes through `/etc/authelia`. The panel references it from Authelia's configuration with a `{{ secret "…" }}` template expression — which is why the unit and `lamaste-priv authelia-totp` set the `template` configuration filter — and can never read it. A key owned by anyone else is replaced; one owned by the Authelia account is kept (its mode fixed through a descriptor if it drifted)
|
|
187
187
|
- Sets ownership (`lib/ownership.js`): `/var/www/lamaste` `lamaste:www-data 2750`; `/etc/authelia` `lamaste:lamaste-authelia 2770` (setgid) with `configuration.yml` `0640`, `users.yml` `0660`, `.secrets.json` `0600` (lamaste), `db.sqlite3*` and `notifications.txt` `lamaste-authelia 0600`; `/var/log/authelia` `lamaste-authelia 0750`; `chisel-server.key` (if present) `lamaste:lamaste-chisel 0640`; the PKI directory `lamaste:lamaste` (the panel is the CA)
|
|
@@ -253,7 +253,7 @@ When the installer detects an existing Lamaste installation (`/etc/lamalibre/lam
|
|
|
253
253
|
|
|
254
254
|
Redeploy mode stops the panel and gatekeeper, secures the install directory (a non-root-owned tree is moved aside and removed at the end), redeploys the panel server, `lamaste-server` CLI, UI, docs, gatekeeper and cert help page, merges `panel.json`, runs the same Chisel/Authelia step as a fresh install (stopping a running Authelia while its files change hands), rewrites the panel's systemd unit, the root-owned programs and the sudoers rules, ensures the port-80 redirect, then restarts Chisel if its binary or unit changed, starts Authelia and the gatekeeper if they were running, and restarts the panel. It does not touch OS hardening, mTLS certificates or the panel's vhosts. The panel's self-update (`sudo lamaste-priv self-update <version>`) runs this path as root, so it never writes through a path the `lamaste` user controls.
|
|
255
255
|
|
|
256
|
-
This provides a fast upgrade path: re-running `npx @lamalibre/create-lamaste@4.
|
|
256
|
+
This provides a fast upgrade path: re-running `npx @lamalibre/create-lamaste@4.4.0` on an existing installation updates the code and the pinned services while preserving all configuration and certificates. Use `--force-full` to bypass this and run the complete installer.
|
|
257
257
|
|
|
258
258
|
The redeploy logic lives in `tasks/redeploy.js`, with shared systemd unit and sudoers content generators in `lib/service-config.js`.
|
|
259
259
|
|
|
@@ -276,7 +276,7 @@ Everything else the panel does needs no rule: the PKI directory (agent CSR signi
|
|
|
276
276
|
|
|
277
277
|
The certbot wrappers accept only lowercase DNS hostnames (no wildcards or path characters, at most 100 per certificate) and a syntactically valid email address. Renewals the panel triggers pass `--no-random-sleep-on-renew`, because certbot otherwise sleeps up to about 8 minutes before a non-interactive renewal (a delay meant for `certbot.timer`) while an operator waits.
|
|
278
278
|
|
|
279
|
-
Redeploying (`npx @lamalibre/create-lamaste@4.
|
|
279
|
+
Redeploying (`npx @lamalibre/create-lamaste@4.4.0` on an existing install) reinstalls the programs, removes retired ones (`lamaste-sign-csr`, `lamaste-pki-rename`), and replaces this file atomically after `visudo -c` accepts it, so upgrades pick up new rules.
|
|
280
280
|
|
|
281
281
|
## File Operation Safety
|
|
282
282
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
Lamaste has three main pieces:
|
|
8
8
|
|
|
9
|
-
1. **The Installer** (`npx @lamalibre/create-lamaste@4.
|
|
9
|
+
1. **The Installer** (`npx @lamalibre/create-lamaste@4.4.0`) — a one-shot script you run once on a fresh VPS. It sets up nginx, generates security certificates, and deploys a web-based control panel. After it finishes, you never SSH into the server again.
|
|
10
10
|
|
|
11
11
|
2. **The Panel** (browser UI + backend API) — a management interface protected by a client certificate. Through it, you configure your domain, create tunnels, manage users, and monitor services.
|
|
12
12
|
|
|
@@ -321,7 +321,7 @@ lamaste/
|
|
|
321
321
|
│ │ ├── files.js ← Static site file operations (upload, delete, list)
|
|
322
322
|
│ │ └── app-error.js ← Operational error class (AppError)
|
|
323
323
|
│ │
|
|
324
|
-
│ ├── lamaste-server-ui/ ← React 18 + Vite + Tailwind SPA + shared admin components (@lamalibre/lamaste-server-ui@4.
|
|
324
|
+
│ ├── lamaste-server-ui/ ← React 18 + Vite + Tailwind SPA + shared admin components (@lamalibre/lamaste-server-ui@4.4.0)
|
|
325
325
|
│ │ └── src/
|
|
326
326
|
│ │ ├── index.js ← Package exports (pages, context, utilities)
|
|
327
327
|
│ │ ├── context/
|
|
@@ -337,7 +337,7 @@ lamaste/
|
|
|
337
337
|
│ │ │ └── formatters.js ← Byte, uptime, relative time formatters
|
|
338
338
|
│ │ └── pages/ ← Admin pages (Dashboard, Tunnels, Sites, Users, Certs, Services, Plugins, Tickets, Settings)
|
|
339
339
|
│ │
|
|
340
|
-
│ ├── lamaste-agent-ui/ ← Shared React agent UI (pages, context, components) (@lamalibre/lamaste-agent-ui@4.
|
|
340
|
+
│ ├── lamaste-agent-ui/ ← Shared React agent UI (pages, context, components) (@lamalibre/lamaste-agent-ui@4.4.0)
|
|
341
341
|
│ │
|
|
342
342
|
│ ├── lamaste-tickets/ ← Agent-to-agent authorization SDK (mTLS, undici)
|
|
343
343
|
│ │ └── src/
|
|
@@ -377,7 +377,7 @@ lamaste/
|
|
|
377
377
|
│ │ │ └── CompleteStep.jsx ← Credentials + TOTP QR + next steps
|
|
378
378
|
│ │ ├── management/ ← Legacy standalone implementations (kept for reference)
|
|
379
379
|
│ │ │ ├── Certificates.jsx ← Standalone certificates page (dead code)
|
|
380
|
-
│ │ │ ├── Dashboard.jsx ← Standalone dashboard (not imported — App.jsx uses @lamalibre/lamaste-server-ui@4.
|
|
380
|
+
│ │ │ ├── Dashboard.jsx ← Standalone dashboard (not imported — App.jsx uses @lamalibre/lamaste-server-ui@4.4.0)
|
|
381
381
|
│ │ │ ├── Plugins.jsx ← Standalone plugins page (dead code)
|
|
382
382
|
│ │ │ ├── Services.jsx ← Standalone services page (dead code)
|
|
383
383
|
│ │ │ ├── Settings.jsx ← Standalone settings page (dead code)
|
|
@@ -486,7 +486,7 @@ The Panel Server runs as the `lamaste` user with minimal privileges and cannot b
|
|
|
486
486
|
The full lifecycle of a Lamaste installation:
|
|
487
487
|
|
|
488
488
|
```
|
|
489
|
-
Phase 1: Installation (npx @lamalibre/create-lamaste@4.
|
|
489
|
+
Phase 1: Installation (npx @lamalibre/create-lamaste@4.4.0)
|
|
490
490
|
└─ OS hardening, Node.js, mTLS certs, nginx, panel deploy
|
|
491
491
|
└─ Result: Panel accessible at https://<ip>:9292
|
|
492
492
|
|
|
@@ -10,9 +10,9 @@ The client has two modes. On first visit, it shows an onboarding wizard that wal
|
|
|
10
10
|
|
|
11
11
|
## Shared Panel Packages
|
|
12
12
|
|
|
13
|
-
The management-mode admin pages (Dashboard, Tunnels, Sites, Users, Certificates, Services, Plugins, Tickets, Logs, Settings) live in `@lamalibre/lamaste-server-ui@4.
|
|
13
|
+
The management-mode admin pages (Dashboard, Tunnels, Sites, Users, Certificates, Services, Plugins, Tickets, Logs, Settings) live in `@lamalibre/lamaste-server-ui@4.4.0`. This package provides both the browser SPA build and the shared admin components consumed by `lamaste-desktop` (Tauri app).
|
|
14
14
|
|
|
15
|
-
The agent-mode pages (Dashboard, Tunnels, Services, Plugins, Logs, Settings) are extracted into a separate shared package: `@lamalibre/lamaste-agent-ui@4.
|
|
15
|
+
The agent-mode pages (Dashboard, Tunnels, Services, Plugins, Logs, Settings) are extracted into a separate shared package: `@lamalibre/lamaste-agent-ui@4.4.0`. This package is consumed by `lamaste-desktop` for agent mode.
|
|
16
16
|
|
|
17
17
|
The shared package exposes an `AdminClientContext` abstraction that decouples admin UI pages from their data transport. Each host provides its own client implementation:
|
|
18
18
|
|
|
@@ -118,7 +118,7 @@ The shell renders the appropriate step component and shows a progress indicator
|
|
|
118
118
|
|
|
119
119
|
### Management Mode
|
|
120
120
|
|
|
121
|
-
React Router handles navigation within the `Layout` component (sidebar + content area). Management page components are imported from the shared `@lamalibre/lamaste-server-ui@4.
|
|
121
|
+
React Router handles navigation within the `Layout` component (sidebar + content area). Management page components are imported from the shared `@lamalibre/lamaste-server-ui@4.4.0` package and wrapped with the `AdminClientProvider` (which supplies the web-specific data client):
|
|
122
122
|
|
|
123
123
|
| Path | Component | Description |
|
|
124
124
|
| ------------------------ | ------------------- | ------------------------------------------------------------------- |
|
|
@@ -327,7 +327,7 @@ const baseNavItems = [
|
|
|
327
327
|
];
|
|
328
328
|
```
|
|
329
329
|
|
|
330
|
-
The sidebar dynamically appends navigation items for enabled plugins. Plugins with a `panel.pages` array get a section header followed by per-page links; plugins with a single `panel.label` get one link. Plugin nav items
|
|
330
|
+
The sidebar dynamically appends navigation items for enabled plugins. Plugins with a `panel.pages` array get a section header followed by per-page links; plugins with a single `panel.label` get one link. Plugin nav items come from the plugin list — fetched via the `AdminClientContext` under the `['plugins']` query, which the Plugins page and the plugin loader share — and are appended after the base items. The items of an agent-hosted plugin whose hosting is down are marked with why: the hosting agent offline since when, and its last sync, or the agent half not responding ([Agent-Hosted Plugins](../04-api-reference/agent-hosted-plugins.md#when-the-hosting-agent-is-offline)); the plugin loader then shows that instead of fetching the bundle.
|
|
331
331
|
|
|
332
332
|
Each item renders a `SidebarLink` component with active-state highlighting via React Router's `useLocation`.
|
|
333
333
|
|
|
@@ -350,9 +350,9 @@ The app root wraps all content in five providers:
|
|
|
350
350
|
```
|
|
351
351
|
|
|
352
352
|
1. **QueryClientProvider** — react-query cache with global defaults (`retry: 1`, `refetchOnWindowFocus: false`)
|
|
353
|
-
2. **AdminClientProvider** — from `@lamalibre/lamaste-server-ui@4.
|
|
354
|
-
3. **ToastProvider** — from `@lamalibre/lamaste-server-ui@4.
|
|
355
|
-
4. **TwoFaProvider** — from `@lamalibre/lamaste-server-ui@4.
|
|
353
|
+
2. **AdminClientProvider** — from `@lamalibre/lamaste-server-ui@4.4.0`, supplies the host-specific data client (`webAdminClient` for browser fetch, Tauri `invoke` for desktop)
|
|
354
|
+
3. **ToastProvider** — from `@lamalibre/lamaste-server-ui@4.4.0`, notification toast system
|
|
355
|
+
4. **TwoFaProvider** — from `@lamalibre/lamaste-server-ui@4.4.0`, handles 2FA verification prompts when the panel has 2FA enabled
|
|
356
356
|
5. **BrowserRouter** — React Router for client-side navigation
|
|
357
357
|
|
|
358
358
|
## Documentation Viewer
|
|
@@ -453,7 +453,7 @@ See [nginx-configuration.md](./nginx-configuration.md) for detailed coverage.
|
|
|
453
453
|
|
|
454
454
|
### chisel-users.js — Chisel Credentials and Grants
|
|
455
455
|
|
|
456
|
-
- Thin shim over `@lamalibre/lamaste@4.
|
|
456
|
+
- Thin shim over `@lamalibre/lamaste@4.4.0/server`: per-agent credentials in `chisel-credentials.json` (0600)
|
|
457
457
|
- Renders the authfile `chisel-users` from the credentials and `tunnels.json`: each `agent-<label>` may bind exactly `^R:127\.0\.0\.1:<port>$` for its enabled tunnels
|
|
458
458
|
- Adds the `lamaste-no-grants` sentinel user (password in `chisel-sentinel`, 0600) so the authfile is never empty — Chisel disables authentication on an empty authfile
|
|
459
459
|
- Never grants a reserved port (3100, 9090, 9091, 9292, 9294) or a port claimed by two tunnels
|
|
@@ -535,7 +535,7 @@ Agent-to-agent authorization with scopes, instances, tickets, and sessions. Prov
|
|
|
535
535
|
- **Periodic cleanup** — stale/dead instances, expired tickets, dead sessions
|
|
536
536
|
- **Concurrency** — promise-chain mutex with atomic file writes (temp → fsync → rename)
|
|
537
537
|
|
|
538
|
-
Client SDK: `@lamalibre/lamaste-tickets@4.
|
|
538
|
+
Client SDK: `@lamalibre/lamaste-tickets@4.4.0` (TypeScript, undici) provides `TicketClient`, `TicketInstanceManager` (source side), and `TicketSessionManager` (target side) for plugin integration.
|
|
539
539
|
|
|
540
540
|
State files: `/etc/lamalibre/lamaste/ticket-scopes.json` (scopes, instances, assignments) and `/etc/lamalibre/lamaste/tickets.json` (tickets, sessions).
|
|
541
541
|
|
|
@@ -331,7 +331,7 @@ Read returns `[]` for missing files (ENOENT), enabling the system to start with
|
|
|
331
331
|
5. `DELETE /api/certs/agent/:label` (revocation) — the agent's app and plugin tunnels lose their `agentLabel` (unassigned), and its `agent-<label>` panel tunnel is removed
|
|
332
332
|
6. At startup (background, fail closed): an ownerless `agent-<label>` panel tunnel is bound to the agent it names when that agent is active; other ownerless tunnels (from versions before tunnel ownership) are bound to the sole active agent, or left unassigned when there are several. Then the pinned Chisel binary, the unit and the authfile are re-established — and Chisel is stopped if they cannot be
|
|
333
333
|
|
|
334
|
-
Every one of these workflows runs under the single tunnel lock (`withTunnelLock` in `@lamalibre/lamaste@4.
|
|
334
|
+
Every one of these workflows runs under the single tunnel lock (`withTunnelLock` in `@lamalibre/lamaste@4.4.0/server`), with its validation inside the lock.
|
|
335
335
|
|
|
336
336
|
## Site State (`sites.json`)
|
|
337
337
|
|
|
@@ -486,7 +486,7 @@ The PKI directory belongs to `lamaste` because the panel is the CA (it signs age
|
|
|
486
486
|
|
|
487
487
|
The Panel Server is a single-process Node.js application, but a single-threaded event loop does not serialize asynchronous workflows: two requests that each read `tunnels.json`, await a certificate or an nginx test, and then write it back would interleave, and both could pass the same uniqueness check. Serialization is therefore explicit:
|
|
488
488
|
|
|
489
|
-
**Tunnel state** is guarded by one promise-chain lock, `withTunnelLock` in `@lamalibre/lamaste@4.
|
|
489
|
+
**Tunnel state** is guarded by one promise-chain lock, `withTunnelLock` in `@lamalibre/lamaste@4.4.0/server`'s `tunnels.ts`. Every tunnel workflow — create, delete, toggle, assign, reconfigure, the combined `PATCH /api/tunnels/:id`, releasing a revoked agent's tunnels, and startup reconciliation — takes it for its whole duration, and does its validation (subdomain and port uniqueness, reserved ports, agent checks, authorization against the current entry) inside it.
|
|
490
490
|
|
|
491
491
|
**Chisel authfile renders** are serialized by a promise-chain mutex in `chisel-users.ts`, keyed by the credentials file, around every render (enroll, revoke, rotate, tunnel change). The daemon's `syncChisel()` renders after the tunnel state is written and restarts Chisel (`systemctl try-restart`) only when the render withdrew something.
|
|
492
492
|
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
│ │ │ │
|
|
59
59
|
│ │ Lamaste Desktop (Tauri v2) — dual mode │ │
|
|
60
60
|
│ │ ├─ Agent mode: service discovery + tunnel management │ │
|
|
61
|
-
│ │ │ (pages from @lamalibre/lamaste-agent-ui@4.
|
|
61
|
+
│ │ │ (pages from @lamalibre/lamaste-agent-ui@4.4.0) │ │
|
|
62
62
|
│ │ ├─ Server mode: full admin panel (via lamaste-server-ui) │ │
|
|
63
63
|
│ │ ├─ Multi-server registry (~/.lamalibre/lamaste/servers.json) │ │
|
|
64
64
|
│ │ ├─ Cloud provisioning (DigitalOcean via lamaste-cloud) │ │
|