@lamalibre/create-lamaste 4.2.0 → 4.3.0

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

@@ -274,117 +274,143 @@ There are two exceptions:
 
 ### 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)     |
-| GET    | `/api/agents/me/registry-credential`                      | Management | One-hour registry token for the 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/:name/oidc-clients`                         | Management | A plugin's OIDC clients (no secrets)     |
-| POST   | `/api/plugins/:name/oidc-clients/:clientId/rotate-secret` | Management | New secret for a confidential client     |
-| GET    | `/api/registry-credential`                                | Management | Registry credential summary              |
-| PUT    | `/api/registry-credential`                                | Management | Set the registry credential (verified)   |
-| DELETE | `/api/registry-credential`                                | Management | Remove the registry credential           |
-| 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               |
+| 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)       |
+| GET    | `/api/agents/me/registry-credential`                      | Management | One-hour registry token for the agent      |
+| GET    | `/api/agents/me/relay-keys`                               | Management | Relay assertion keys, caller's relay label |
+| GET    | `/api/agents/me/plugin-config/:route`                     | Management | Hosting agent: its plugin's port, secret   |
+| POST   | `/api/agents/me/plugin-config/:route/ack`                 | Management | Hosting agent holds the secret issued      |
+| POST   | `/api/agents/me/jobs/:id/result`                          | Management | Report an agent job's result (agent)       |
+| PUT    | `/api/agents/me/host-facts`                               | Management | Report the agent's host facts (agent)      |
+| GET    | `/api/agent-panel/authz/:label`                           | Management | Agent-panel vhost `auth_request` (nginx)   |
+| 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/:name/oidc-clients`                         | Management | A plugin's OIDC clients (no secrets)       |
+| POST   | `/api/plugins/:name/oidc-clients/:clientId/rotate-secret` | Management | New secret for a confidential client       |
+| GET    | `/api/plugins/:name/hosting`                              | Management | Which agent hosts the plugin, its health   |
+| POST   | `/api/plugins/:name/hosting`                              | Management | Host the plugin on an agent (operation)    |
+| DELETE | `/api/plugins/:name/hosting`                              | Management | Remove the hosting (operation)             |
+| POST   | `/api/plugins/:name/hosting/rotate-secret`                | Management | New installation secret                    |
+| GET    | `/api/plugins/:name/hosting/eligibility`                  | Management | Which agents can host the plugin, and why  |
+| GET    | `/api/plugins/:name/retained-data`                        | Management | Data agents keep of its agent half         |
+| DELETE | `/api/plugins/:name/retained-data`                        | Management | Purge it on an agent, or forget the record |
+| GET    | `/api/plugins/:name/hooks`                                | Management | Lifecycle hooks, what needs approval       |
+| POST   | `/api/plugins/:name/hooks/approve`                        | Management | Approve with the approval digest           |
+| PUT    | `/api/plugins/:name/hooks/auto-approve`                   | Management | Auto-approve what later versions bring     |
+| POST   | `/api/plugins/:name/update`                               | Management | Update an agent-hosted plugin in place     |
+| DELETE | `/api/plugins/:name/update`                               | Management | Discard an update waiting for approval     |
+| GET    | `/api/plugins/:name/operations`                           | Management | The plugin's recent operations             |
+| GET    | `/api/plugins/:name/operations/:id`                       | Management | One operation and its steps                |
+| ANY    | `/api/<route>`, `/api/<route>/*`                          | Management | Forwarded to the agent half's `/admin/*`   |
+| GET    | `/api/audit`                                              | Management | Audit log                                  |
+| GET    | `/api/notifications`                                      | Management | Panel notifications                        |
+| POST   | `/api/notifications/read`                                 | Management | Mark notifications read                    |
+| GET    | `/api/registry-credential`                                | Management | Registry credential summary                |
+| PUT    | `/api/registry-credential`                                | Management | Set the registry credential (verified)     |
+| DELETE | `/api/registry-credential`                                | Management | Remove the registry credential             |
+| 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 | Record a push-install command (legacy)     |
+| 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                 |
+
+`POST /api/plugins/push-install/:label` checks the push-install gates and records the command in the push-install log; nothing delivers it to the agent. What Lamaste does push to an agent — installing, updating and removing an agent half — runs as plugin operations under the same gates ([Agent-Hosted Plugins](agent-hosted-plugins.md#push-install-gates)). The agent-hosted plugin endpoints are described in [Agent-Hosted Plugins](agent-hosted-plugins.md), [Lifecycle Hooks](lifecycle-hooks.md) and [Audit Log and Notifications](audit-and-notifications.md).
 
 ### Agent Capabilities
 

package/vendor/docs/04-api-reference/registry-and-oidc.md

@@ -53,7 +53,9 @@ What the panel writes for a public client: `public: true`, `token_endpoint_auth_
 
 ### Secrets of confidential clients
 
-The panel mints a 32-byte secret when a confidential client first appears (at install — the secret belongs to an installed plugin, enabled or not), stores the plaintext in `/etc/lamalibre/lamaste/oidc-clients.json` (0600) and writes only the digest into Authelia. The plaintext is shown exactly once: in the response of the `POST /api/plugins/install` (or `enable`) call that created it, as `oidcClients: [{ id, secret }]`, and again by `rotate-secret`. Uninstalling the plugin deletes the secret; disabling keeps it.
+The panel mints a 32-byte secret when a confidential client first appears (at install — the secret belongs to an installed plugin, enabled or not), stores the plaintext in `/etc/lamalibre/lamaste/oidc-clients.json` (0600) and writes only the digest into Authelia. The plaintext is shown exactly once: in the response of the `POST /api/plugins/install` (or `enable`) call that created it, as `oidcClients: [{ id, secret }]` — or, when an update of an agent-hosted plugin adds the client, on the first read of the finished update operation ([Operations](lifecycle-hooks.md#operations)) — and again by `rotate-secret`. Uninstalling the plugin deletes the secret; disabling keeps it.
+
+The panel's Plugins page — and the desktop app, which reuses it — shows the secrets an install, enable or update created in a dialog the administrator must acknowledge: each client id with its secret and a copy button, and the warning that it is shown once. The secrets go from the response to that dialog only: not into the page's query cache, the browser's storage or a log, and they are gone once acknowledged. An update started from the page is read as it ends. One started elsewhere — another panel, `lamaste-server`, or the page before a reload — is offered on the plugin's card (**Show the secrets**) instead of read unasked, so the CLI following its own update still prints them.
 
 ### Where the clients are served
 
@@ -82,10 +84,12 @@ An application that runs on its own agent, behind a Lamaste tunnel, still needs
 }
 ```
 
-It is installed like any plugin (`POST /api/plugins/install` runs `npm install --ignore-scripts` and reads `<package>/lamaste-plugin.json`), but Lamaste never imports the package — not the panel, and not an agent's plugin host if the package is installed there. Nothing is mounted under `/api/<name>/` (requests there answer `404`), no panel bundle is served, and no storage can be bound to it (`400`). A `panel` declaration is a manifest error (`400` on install). What takes effect is what the manifest declares: its `oidcClients` are written to Authelia on enable and removed on disable or uninstall, confidential-client secrets are minted and shown exactly as above, and its `capabilities` can be granted to agents. `GET /api/plugins` reports each plugin's `hosting`; a plugin installed before 4.2 is `"server"`.
+It is installed like any plugin (`POST /api/plugins/install` runs `npm install --ignore-scripts` and reads `<package>/lamaste-plugin.json`), but Lamaste never imports the package — not the panel, and not an agent's plugin host if the package is installed there. Nothing is mounted under `/api/<name>/` (requests there answer `404`), no panel bundle is served, and no storage can be bound to it (`400`). A `panel` declaration on such an identity-only plugin is a manifest error (`400` on install). What takes effect is what the manifest declares: its `oidcClients` are written to Authelia on enable and removed on disable or uninstall, confidential-client secrets are minted and shown exactly as above, and its `capabilities` can be granted to agents. `GET /api/plugins` reports each plugin's `hosting`; a plugin installed before 4.2 is `"server"`.
 
 The application's own tunnel (`feria.<domain>`) is created by the administrator as for any app; Lamaste does not create it from the manifest.
 
+An agent-hosted plugin whose manifest also has an `agent` block has an _agent half_ the panel connects to: it can be hosted on an agent, which gives it an internal plugin tunnel, an installation secret and a forwarded admin API, and it may declare panel pages. See [Agent-Hosted Plugins](agent-hosted-plugins.md).
+
 ## Plugin OIDC client endpoints
 
 ### `GET /api/plugins/:name/oidc-clients`
@@ -160,7 +164,7 @@ Admin only, 10 per minute. Verifies the whole chain against the registry, then s
 ```
 
 - `auth.kind: "token"` — a long-lived Feria token. The registry's `/-/whoami` must report the `admin` scope (the broker route requires it).
-- `auth.kind: "oidc"` — the panel's own service principal. The panel first makes sure Authelia carries the confidential client `lamaste-server` (grant `client_credentials`, `token_endpoint_auth_method: client_secret_basic`, scope `lamaste.registry` — defined under `identity_providers.oidc.scopes` —, audience = the registry URL without a trailing slash, RS256 JWT access tokens; secret in `oidc-clients.json`). It then obtains a JWT from Authelia's token endpoint (`grant_type=client_credentials&scope=lamaste.registry&audience=<registryUrl>`), posts it to `<registryUrl>/-/feria/login`, and checks that `/-/whoami` reports `admin`. If any step fails the client is removed again and the error says what is missing — typically that Feria's `auth.json` needs a `rules` issuer for `https://auth.<domain>` with audience `<registryUrl>` granting the `admin` scope when the `client_id` claim (or `sub`, which carries the same value) is `lamaste-server`.
+- `auth.kind: "oidc"` — the panel's own service principal. The panel first makes sure Authelia carries the confidential client `lamaste-server` (grant `client_credentials`, `token_endpoint_auth_method: client_secret_basic`, scope `lamaste.registry` — defined under `identity_providers.oidc.scopes` —, audience = the registry URL without a trailing slash, RS256 JWT access tokens; secret in `oidc-clients.json`). It then obtains a JWT from Authelia's token endpoint (`grant_type=client_credentials&scope=lamaste.registry&audience=<registryUrl>`), posts it to `<registryUrl>/-/feria/login`, and checks that `/-/whoami` reports `admin`. If any step fails the client is removed again and the error says what is missing — typically that Feria's `auth.json` needs, on its `groups` issuer for `https://auth.<domain>` (audience `<registryUrl>`), a `workloads` rule granting the `admin` scope when the `client_id` claim (or `sub`, which carries the same value) is `lamaste-server`. Feria keys issuers by `iss` and the relay's users log in through the same Authelia, so the rule cannot be a second `rules` issuer; `workloads` needs Feria 0.3.2 or later.
 
 Response: as `GET`. Errors: `400` (no admin scope), `502` (registry or Authelia refused or unreachable), `503` (no domain yet).
 

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

@@ -53,19 +53,20 @@ curl -s --cert client.p12:password \
 }
 ```
 
-| Field           | Type             | Description                                                                                                                                                                                |
-| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`            | `string`         | UUID v4 identifier                                                                                                                                                                         |
-| `subdomain`     | `string`         | The subdomain portion (e.g., `app`)                                                                                                                                                        |
-| `fqdn`          | `string`         | Fully qualified domain name (e.g., `app.example.com`)                                                                                                                                      |
-| `port`          | `number`         | Port the carrying agent forwards; bound on `127.0.0.1` on both the server and the agent                                                                                                    |
-| `description`   | `string \| null` | Optional human-readable description                                                                                                                                                        |
-| `type`          | `string`         | `'app'` (default), `'panel'` (agent web panel), or `'plugin'`                                                                                                                              |
-| `accessMode`    | `string`         | `'restricted'` (default), `'authenticated'`, or `'public'` — absent on panel tunnels                                                                                                       |
-| `agentLabel`    | `string`         | The agent that carries the tunnel. Absent only on an unassigned legacy tunnel (see below)                                                                                                  |
-| `maxBodySizeMb` | `number`         | Largest request body nginx accepts, in MiB. Absent on panel tunnels and on tunnels created before the setting existed, which keep nginx's built-in 1 MiB until a body limit is set on them |
-| `enabled`       | `boolean`        | Whether the tunnel is active (defaults to `true`)                                                                                                                                          |
-| `createdAt`     | `string`         | ISO 8601 timestamp                                                                                                                                                                         |
+| Field           | Type             | Description                                                                                                                                                                                                                                             |
+| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`            | `string`         | UUID v4 identifier                                                                                                                                                                                                                                      |
+| `subdomain`     | `string`         | The subdomain portion (e.g., `app`)                                                                                                                                                                                                                     |
+| `fqdn`          | `string`         | Fully qualified domain name (e.g., `app.example.com`)                                                                                                                                                                                                   |
+| `port`          | `number`         | Port the carrying agent forwards; bound on `127.0.0.1` on both the server and the agent                                                                                                                                                                 |
+| `description`   | `string \| null` | Optional human-readable description                                                                                                                                                                                                                     |
+| `type`          | `string`         | `'app'` (default), `'panel'` (agent web panel), or `'plugin'`                                                                                                                                                                                           |
+| `accessMode`    | `string`         | `'restricted'` (default), `'authenticated'`, or `'public'` — absent on panel tunnels                                                                                                                                                                    |
+| `agentLabel`    | `string`         | The agent that carries the tunnel. Absent only on an unassigned legacy tunnel (see below)                                                                                                                                                               |
+| `exposure`      | `string`         | `'internal'` on the internal tunnel of a hosted agent-hosted plugin: no `subdomain`, `fqdn` or `accessMode`, only the chisel grant on a relay-loopback port. Absent (public) on every other tunnel. See [Agent-Hosted Plugins](agent-hosted-plugins.md) |
+| `maxBodySizeMb` | `number`         | Largest request body nginx accepts, in MiB. Absent on panel tunnels and on tunnels created before the setting existed, which keep nginx's built-in 1 MiB until a body limit is set on them                                                              |
+| `enabled`       | `boolean`        | Whether the tunnel is active (defaults to `true`)                                                                                                                                                                                                       |
+| `createdAt`     | `string`         | ISO 8601 timestamp                                                                                                                                                                                                                                      |
 
 ---
 
@@ -370,6 +371,7 @@ Revoking an agent's certificate releases its tunnels: its app and plugin tunnels
 - Minimum: 1024 (no privileged ports)
 - Maximum: 65535
 - Must not be a reserved port: `3100` (panel server), `9090` (Chisel server), `9091` (Authelia), `9292` (IP-based panel listener), `9294` (Gatekeeper)
+- Must not be in `21000`–`21999`, the range Lamaste assigns to the internal tunnels of hosted agent-hosted plugins (a tunnel created before 4.3 on such a port keeps it)
 - Must be unique across all tunnels — Chisel binds the same port on the server and on the agent
 
 A tunnel's vhost proxies to `127.0.0.1:<port>` on the relay, so a tunnel on one of Lamaste's own ports would publish that internal service on the internet. For the panel ports that would be an administrator takeover, not a leak: the panel trusts the client-certificate headers nginx sets. The reserved ports are rejected by the request schema, again inside the tunnel workflow, and never granted in the Chisel authfile.

package/vendor/docs/05-operations/backup-and-restore.md

@@ -197,7 +197,7 @@ sudo chown lamaste-authelia:lamaste-authelia /etc/authelia/db.sqlite3* /etc/auth
 sudo chmod 600 /etc/authelia/db.sqlite3* /etc/authelia/notifications.txt
 ```
 
-A backup taken on a version before the privilege boundary holds root-owned Authelia files and older unit files. After restoring one, re-run `npx @lamalibre/create-lamaste@4.2.0 --yes`: the redeploy rewrites the `chisel` and `authelia` units and converts the ownership of `/etc/authelia`, the Chisel key and the PKI directory (see [Upgrades](upgrades.md)).
+A backup taken on a version before the privilege boundary holds root-owned Authelia files and older unit files. After restoring one, re-run `npx @lamalibre/create-lamaste@4.3.0 --yes`: the redeploy rewrites the `chisel` and `authelia` units and converts the ownership of `/etc/authelia`, the Chisel key and the PKI directory (see [Upgrades](upgrades.md)).
 
 The panel re-applies the authfile's group and mode itself on every start, so a Chisel that fails to read it before the panel is up is started again by the panel's reconciliation.
 

package/vendor/docs/05-operations/uninstalling.md

@@ -29,7 +29,7 @@ It stops and disables the panel, gatekeeper, Chisel and Authelia; removes their
 The manual guide is also available from the CLI:
 
 ```bash
-npx @lamalibre/create-lamaste@4.2.0 --uninstall
+npx @lamalibre/create-lamaste@4.3.0 --uninstall
 ```
 
 This prints the same steps listed below.

package/vendor/docs/05-operations/upgrades.md

@@ -18,18 +18,22 @@ Always follow these steps before upgrading any component:
 2. **Note what is currently working** — check the dashboard, verify services are active
 3. **Plan for a brief outage** — most upgrades require a service restart (seconds, not minutes)
 
-### Upgrade Order: Agents First
+### Upgrade Order: Server First
 
-When a release changes both sides, upgrade every **agent before the server**. Agents from before this version reject the new shape of the relay's Chisel arguments; a current agent works against an older server and keeps its Chisel credential until the server offers rotation.
+Upgrade the **server before the agents**. Since 4.3 an agent's daemon (`lamaste-agentd`) accepts a request from the relay only with a signed relay assertion, which a 4.3 server sends and an older one does not: a 4.3 agent behind an older server refuses its agent-panel and plugin-tunnel requests (401) until the server is upgraded. An older agent keeps working behind a 4.3 server, which still sends the headers older daemons read.
 
-On each agent machine:
+Coming from 3.x, upgrade the **agents first**, as 4.0 required: agents from before 4.0 reject the 4.0 server's Chisel arguments and lose their tunnels, while a 4.3 agent behind a 3.x server keeps its tunnels and only its agent panel answers 401 until the server is upgraded.
+
+On each agent machine, after the server:
 
 ```bash
-npm install -g @lamalibre/lamaste-agent@4.2.0
+sudo npm install -g @lamalibre/lamaste-agent@4.3.0
 lamaste-agent update
 ```
 
-`update` applies the panel's configuration, restarts the tunnel client, and installs the sync timer (which applies later tunnel changes within 30 seconds). An agent originally set up with `npx` must be installed globally first — the sync timer runs the installed program. On its first sync after the upgrade an agent from before this version rotates its Chisel credential once, because older versions exposed it in process arguments and 0644 unit files. The Desktop App updates the agents it manages.
+`update` applies the panel's configuration, restarts the tunnel client, and installs the sync timer (which applies later tunnel changes within 30 seconds). An agent originally set up with `npx` must be installed globally first — the sync timer runs the installed program. On Linux it also rewrites the agent panel's user unit so the panel starts at boot. An agent from before 4.0 rotates its Chisel credential once on its first sync, because older versions exposed it in process arguments and 0644 unit files. The Desktop App updates the agents it manages.
+
+A machine that hosts app plugins' agent halves needs the root-owned install shown above and its app host helper enabled once with `sudo lamaste-agent apphost enable` (see [App host](../04-api-reference/app-host.md)); after replacing the server's relay signing key, run `sudo lamaste-agent apphost pin` there.
 
 ### Updating Lamaste (Panel Server and Client)
 
@@ -58,8 +62,9 @@ The `@latest` tag ensures you get the newest published version. The `--yes` flag
 - It rewrites `panel.json` (merged, as a fresh file renamed into place — root never writes through a path the `lamaste` user controls)
 - It installs the pinned Chisel and Authelia releases if they are not already installed (a newer Authelia is kept), writes their systemd units, creates the `lamaste-chisel` group and the `lamaste-authelia` account, and sets the ownership described in [Configuration Files](../06-reference/config-files.md#file-permissions-table): `/var/www/lamaste` becomes `lamaste:www-data`, `/etc/authelia` `lamaste:lamaste-authelia`, the Chisel key `lamaste:lamaste-chisel 0640`, and the PKI directory `lamaste`'s. A running Authelia is stopped while its files change hands and started again afterwards
 - It generates the OpenID Connect issuer key `/etc/authelia/oidc-issuer.pem` (0600, `lamaste-authelia`) if it is missing, and the Authelia unit it writes enables the `template` configuration filter. A 4.0 server updating to 4.1 therefore has the key before the new panel starts; plugin OIDC clients and the `--oidc` registry credential need it
+- It upgrades Node.js from NodeSource when the installed version is older than 22.13 — the plugin hook runner's sandbox uses Node's stable permission model — and writes the hook runner's units (`lamalibre-lamaste-hooks@.socket`, `lamalibre-lamaste-hooks@.service`; see [Lifecycle hooks](../04-api-reference/lifecycle-hooks.md))
 - It rewrites the panel's systemd unit and the sudoers rules (checked with `visudo -c` before they replace the old file), installs the root-owned programs in `/usr/local/sbin/` (`lamaste-priv`, `lamaste-certbot`, `lamaste-cert-info`) and removes the retired `lamaste-sign-csr` and `lamaste-pki-rename`, and installs the port-80 redirect site
-- It restarts Chisel if its binary or unit changed, starts the gatekeeper if it was running, and restarts `lamalibre-lamaste-serverd`, whose startup reconciliation rewrites Chisel's authfile
+- It restarts Chisel if its binary or unit changed, starts the gatekeeper if it was running, and restarts `lamalibre-lamaste-serverd`, whose startup reconciliation rewrites Chisel's authfile. The first start of a 4.3 panel also creates the relay signing key (`/etc/lamalibre/lamaste/relay-signing-key.json`, 0600) and rewrites existing tunnel, static site and auth portal vhosts; check its log for `Left tunnel vhosts as they are`, `Left site vhosts as they are` and `Failed to rewrite … vhost` (see the [4.3.0 upgrade notes](https://github.com/lamalibre/lamaste/blob/main/CHANGELOG.md))
 
 The panel's **Update** action (`POST /api/system/update`) runs the same redeploy: it asks `sudo lamaste-priv self-update <version>` to start `create-lamaste@<version> --yes` in a transient systemd unit (see [System API](../04-api-reference/system.md)).
 
@@ -79,7 +84,7 @@ exit
 
 ### Updating Chisel
 
-Chisel is the tunnel server binary at `/usr/local/bin/chisel`. Lamaste pins it: server and agents run Chisel 1.12.0 (`CHISEL_RELEASE` in `@lamalibre/lamaste@4.2.0`), downloaded from the fixed release URL and verified against a pinned SHA-256 before it is unpacked. **Do not replace the binary by hand.** On the server, `create-lamaste` installs it (as root) and replaces a binary that reports any other version; the panel cannot install binaries, and only logs an error at startup when the installed Chisel is not the pinned release (it then restarts Chisel on every authfile change). Each agent's sync replaces its own copy.
+Chisel is the tunnel server binary at `/usr/local/bin/chisel`. Lamaste pins it: server and agents run Chisel 1.12.0 (`CHISEL_RELEASE` in `@lamalibre/lamaste@4.3.0`), downloaded from the fixed release URL and verified against a pinned SHA-256 before it is unpacked. **Do not replace the binary by hand.** On the server, `create-lamaste` installs it (as root) and replaces a binary that reports any other version; the panel cannot install binaries, and only logs an error at startup when the installed Chisel is not the pinned release (it then restarts Chisel on every authfile change). Each agent's sync replaces its own copy.
 
 A new Chisel version therefore arrives with a Lamaste release that changes the pin: re-run the installer, which installs it and restarts Chisel. To check what is running:
 
@@ -93,7 +98,7 @@ Tunnel clients reconnect on their own after the brief interruption (they retry a
 
 ### Updating Authelia
 
-Authelia is the authentication server binary at `/usr/local/bin/authelia`. Lamaste pins it too: Authelia 4.39.28 (`AUTHELIA_RELEASE` in `@lamalibre/lamaste@4.2.0`), downloaded by `create-lamaste` from its fixed release URL and verified against a pinned SHA-256 per architecture. A new Authelia version arrives with a Lamaste release that changes the pin — re-run the installer. It stops Authelia while it replaces the binary and starts it again.
+Authelia is the authentication server binary at `/usr/local/bin/authelia`. Lamaste pins it too: Authelia 4.39.28 (`AUTHELIA_RELEASE` in `@lamalibre/lamaste@4.3.0`), downloaded by `create-lamaste` from its fixed release URL and verified against a pinned SHA-256 per architecture. A new Authelia version arrives with a Lamaste release that changes the pin — re-run the installer. It stops Authelia while it replaces the binary and starts it again.
 
 An installed Authelia **newer** than the pin is kept, never downgraded: its database may already use a schema the pinned release cannot read, and Authelia refuses to start on a database newer than itself. If you install a newer release by hand, stop the service, replace the binary as root with a `root:root 0755` file, and start it again; check the [Authelia changelog](https://github.com/authelia/authelia/blob/master/CHANGELOG.md) first, since the configuration format may change between versions.
 
@@ -232,7 +237,7 @@ The panel server, CLI, client, docs and gatekeeper are always redeployed (files
 
 ### Version Pinning
 
-Chisel and Authelia are pinned by version and SHA-256 in `packages/core/lib/src/constants.ts` (`CHISEL_RELEASE`, `AUTHELIA_RELEASE`); changing a pin means updating the version and every digest there. The downloads are verified by `downloadVerifiedChisel` / `downloadVerifiedAuthelia` (exported from `@lamalibre/lamaste@4.2.0`) before anything is unpacked; the server installer uses them in `packages/provisioners/server/src/lib/binaries.js`. The configuration the panel writes needs Authelia 4.38 or later.
+Chisel and Authelia are pinned by version and SHA-256 in `packages/core/lib/src/constants.ts` (`CHISEL_RELEASE`, `AUTHELIA_RELEASE`); changing a pin means updating the version and every digest there. The downloads are verified by `downloadVerifiedChisel` / `downloadVerifiedAuthelia` (exported from `@lamalibre/lamaste@4.3.0`) before anything is unpacked; the server installer uses them in `packages/provisioners/server/src/lib/binaries.js`. The configuration the panel writes needs Authelia 4.38 or later.
 
 ### Automated Updates
 
@@ -249,17 +254,17 @@ sudo dpkg-reconfigure -plow unattended-upgrades
 
 ## Quick Reference
 
-| Component    | Location                                    | Update Method                                          |
-| ------------ | ------------------------------------------- | ------------------------------------------------------ |
-| Panel server | `/opt/lamalibre/lamaste/lamaste-serverd/`   | Re-run `npx @lamalibre/create-lamaste@latest`          |
-| Panel client | `/opt/lamalibre/lamaste/lamaste-server-ui/` | Re-run `npx @lamalibre/create-lamaste@latest`          |
-| Chisel       | `/usr/local/bin/chisel`                     | Pinned; installed by `create-lamaste`                  |
-| Agents       | `npm install -g @lamalibre/lamaste-agent@4.2.0`   | Upgrade before the server, then `lamaste-agent update` |
-| Authelia     | `/usr/local/bin/authelia`                   | Pinned; installed by `create-lamaste` (newer is kept)  |
-| nginx        | System package                              | `sudo apt-get update && sudo apt-get upgrade`          |
-| certbot      | System package                              | `sudo apt-get update && sudo apt-get upgrade`          |
-| Node.js      | System package                              | Managed by installer (NodeSource repo)                 |
-| Ubuntu       | System packages                             | `sudo apt-get update && sudo apt-get upgrade`          |
+| Component    | Location                                       | Update Method                                         |
+| ------------ | ---------------------------------------------- | ----------------------------------------------------- |
+| Panel server | `/opt/lamalibre/lamaste/lamaste-serverd/`      | Re-run `npx @lamalibre/create-lamaste@latest`         |
+| Panel client | `/opt/lamalibre/lamaste/lamaste-server-ui/`    | Re-run `npx @lamalibre/create-lamaste@latest`         |
+| Chisel       | `/usr/local/bin/chisel`                        | Pinned; installed by `create-lamaste`                 |
+| Agents       | `sudo npm install -g @lamalibre/lamaste-agent@4.3.0` | Upgrade after the server, then `lamaste-agent update` |
+| Authelia     | `/usr/local/bin/authelia`                      | Pinned; installed by `create-lamaste` (newer is kept) |
+| nginx        | System package                                 | `sudo apt-get update && sudo apt-get upgrade`         |
+| certbot      | System package                                 | `sudo apt-get update && sudo apt-get upgrade`         |
+| Node.js      | System package                                 | Managed by installer (NodeSource repo)                |
+| Ubuntu       | System packages                                | `sudo apt-get update && sudo apt-get upgrade`         |
 
 | Post-Upgrade Check   | Command                                                                 |
 | -------------------- | ----------------------------------------------------------------------- |