@lamalibre/create-lamaste 4.3.0 → 4.4.0

package/vendor/docs/04-api-reference/app-host.md

@@ -1,12 +1,12 @@
 # App Host
 
-When an [agent-hosted plugin](agent-hosted-plugins.md)'s manifest names an agent package (`agent.package`), Lamaste installs the plugin's **agent half** onto the hosting agent itself: a system account, a hardened systemd unit, its directories and the system packages it declares. Installing them needs root, and `lamaste-agent` runs as an unprivileged user — so it goes through one root program on the agent, **`lamaste-apphost`**, which the agent's user may run through one sudoers rule. This page is the agent machine's side: enabling the helper, what it creates, the unit, the relay-signed jobs it runs, and the contract an agent half is written to. The relay's side — hosting, approval, updates, removal — is in [Agent-Hosted Plugins](agent-hosted-plugins.md#hosting-with-an-agent-half). The design is `plugin-development/design/agent-hosted-app-plugins.md` (Slice 3).
+When an [agent-hosted plugin](agent-hosted-plugins.md)'s manifest names an agent package (`agent.package`), Lamaste installs the plugin's **agent half** onto the hosting agent itself: a system account, a hardened systemd unit with a socket unit that holds its port, its directories and the system packages it declares. Installing them needs root, and `lamaste-agent` runs as an unprivileged user — so it goes through one root program on the agent, **`lamaste-apphost`**, which the agent's user may run through one sudoers rule. This page is the agent machine's side: enabling the helper, what it creates, the unit and its socket, the relay-signed jobs it runs, and the contract an agent half is written to. The relay's side — hosting, approval, updates, removal — is in [Agent-Hosted Plugins](agent-hosted-plugins.md#hosting-with-an-agent-half). The design is `plugin-development/design/agent-hosted-app-plugins.md` (Slice 3).
 
 It is a page of its own because it documents another machine and another trust boundary: a root program, its files and its unit on the agent, which the relay's API pages only refer to.
 
 ## In Plain English
 
-The operator of an agent machine says once: _the panel may install plugins here_ (`sudo lamaste-agent apphost enable`). From then on, hosting a plugin from the panel installs its agent half on that machine with nothing done by hand: the agent's sync timer downloads exactly the package version the relay pinned, checks it byte for byte, and hands it to the helper, which unpacks it read-only under `/opt`, gives it an account of its own and a data directory under `/var/lib`, and starts it as a locked-down service. Plugin code never runs as root.
+The operator of an agent machine says once: _the panel may install plugins here_ (`sudo lamaste-agent apphost enable`). From then on, hosting a plugin from the panel installs its agent half on that machine with nothing done by hand: the agent's sync timer downloads exactly the package version the relay pinned, checks it byte for byte, and hands it to the helper, which unpacks it read-only under `/opt`, gives it an account of its own and a data directory under `/var/lib`, and starts it as a locked-down service on a port systemd holds for it. Plugin code never runs as root.
 
 The helper does only what the relay **signed**. When it is enabled it remembers (pins) the relay's public key; every install, version switch and removal the relay asks for carries the relay's signature over exactly that job, and the helper refuses anything else — so a compromised agent account cannot make it install, switch or delete anything the relay did not ask for.
 
@@ -15,12 +15,12 @@ The helper does only what the relay **signed**. When it is enabled it remembers
 Once per agent machine (Linux with systemd; macOS agents cannot host an agent half Lamaste installs):
 
 ```bash
-sudo npm install -g @lamalibre/lamaste-agent@4.3.0   # a root-owned install
+sudo npm install -g @lamalibre/lamaste-agent@4.4.0   # a root-owned install
 sudo lamaste-agent apphost enable              # the agent runs as the user who ran sudo
 sudo lamaste-agent apphost enable --user root  # the agent runs as root: no sudoers rule
 ```
 
-`enable` refuses to act from an install another user could have changed: the package, the helper it ships and the core library it loads — and every directory above them — must be root-owned and writable by no group or other user. A user-level install (`nvm`, a home-directory prefix) is not; install it root-owned with `sudo npm install -g @lamalibre/lamaste-agent@4.3.0` and run `enable` from that install. It also needs `/usr/bin/node` (the helper's interpreter and the Node.js every agent half runs on — from the distribution or NodeSource), systemd as the system manager (`/run/systemd/system`), and `sudo` and `visudo` unless the agent runs as root.
+`enable` refuses to act from an install another user could have changed: the package, the helper it ships and the core library it loads — and every directory above them — must be root-owned and writable by no group or other user. A user-level install (`nvm`, a home-directory prefix) is not; install it root-owned with `sudo npm install -g @lamalibre/lamaste-agent@4.4.0` and run `enable` from that install. It also needs `/usr/bin/node` (the helper's interpreter and the Node.js every agent half runs on — from the distribution or NodeSource), systemd as the system manager (`/run/systemd/system`), and `sudo` and `visudo` unless the agent runs as root.
 
 What `enable` does:
 
@@ -29,7 +29,7 @@ What `enable` does:
 3. Checks that the helper answers (`status`) and that the agent's user can run it with `sudo -n`.
 4. Pins the relay key of every agent of that user on the machine (see [Pinning the relay key](#pinning-the-relay-key)), printing each label's key id to compare with the relay's. A failure here leaves the helper enabled — it runs no job until `sudo lamaste-agent apphost pin` succeeds.
 
-The agent's next sync reports the helper to the relay in its [host facts](agent-hosted-plugins.md#host-facts); from then on the panel lists the agent as able to host plugins whose agent half Lamaste installs.
+The agent's next sync reports the helper to the relay in its [host facts](agent-hosted-plugins.md#host-facts); from then on the panel lists the agent as able to host plugins whose agent half Lamaste installs. A relay that loses them — the agent enrolled again on its label, the relay restored from a backup — has them again after the agent's next sync: its agent-config answer tells the agent the hash of the facts it holds (`hostFactsHash`), and the agent reports when that is not the hash of its own.
 
 ### The sudoers rule
 
@@ -60,17 +60,17 @@ All are Linux only. `enable`, `pin`, `remove` and `disable` refuse to run from a
 
 `/usr/local/sbin/lamaste-apphost` is a self-contained CommonJS script (Node.js built-ins only, `#!/usr/bin/node`) that reads nothing the agent's user can write. Every name and path derives from validated arguments; content — a tarball, a service spec, a plugin config, a signature — arrives on stdin, so neither a tarball nor a secret is in the sudo log, and nothing read from stdin is ever echoed. One mutating command runs at a time (`/run/lamaste-apphost.lock`, holding the owner's PID; a lock whose process is gone is taken over).
 
-| Command                                         | stdin                                                                                          | Signed | Does                                                                                                                                                                             |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `install <label> <route> <version> <integrity>` | the signature (one line of JSON), the service spec (one line of JSON), then the package `.tgz` | yes    | Install that version of the agent half and make it current                                                                                                                       |
-| `config <label> <route>`                        | the plugin config (JSON)                                                                       | no     | Write the service's copy of the plugin config; start the unit, restart it when the port changed (a rotated secret needs no restart). Exit 3 when the agent half is not installed |
-| `activate <label> <route> <version>`            | the signature                                                                                  | yes    | Point `current` at a kept version, restore that version's unit, restart                                                                                                          |
-| `remove <label> <route> [--purge]`              | the signature                                                                                  | yes    | Stop and disable the unit; remove unit, code and config. `--purge` also deletes the data directory, the account and the owner record                                             |
-| `status [<route>]`                              | —                                                                                              | no     | `{ protocol, node, apps: { <route>: { versions, current, previous, unit, owner } } }` — `node` is the Node.js the helper, and so every agent half, runs on                       |
+| Command                                         | stdin                                                                                          | Signed | Does                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `install <label> <route> <version> <integrity>` | the signature (one line of JSON), the service spec (one line of JSON), then the package `.tgz` | yes    | Install that version of the agent half and make it current                                                                                                                                                                                                                                           |
+| `config <label> <route>`                        | the plugin config (JSON)                                                                       | no     | Write the service's copy of the plugin config; write the [socket unit](#the-socket-unit) for its port, start the socket and the unit. A new port moves the socket (the unit restarts on it); a rotated secret changes nothing else and restarts nothing. Exit 3 when the agent half is not installed |
+| `activate <label> <route> <version>`            | the signature                                                                                  | yes    | Point `current` at a kept version, restore that version's unit, restart                                                                                                                                                                                                                              |
+| `remove <label> <route> [--purge]`              | the signature                                                                                  | yes    | Stop and disable the unit and its socket; remove both unit files (and the unit's drop-in directory), code and config. `--purge` also deletes the data directory, the account and the owner record                                                                                                    |
+| `status [<route>]`                              | —                                                                                              | no     | `{ protocol, node, apps: { <route>: { versions, current, previous, unit, socket, owner } } }` — `node` is the Node.js the helper, and so every agent half, runs on; `socket` the socket unit's state (`active`, `inactive`, `absent` until the config is there)                                      |
 
 `<label>` is the agent's label on this machine. `config` and `status` are not signed: the agent's user holds the plugin config already, and `status` changes nothing. An operator's `sudo lamaste-agent apphost remove|disable` loads the helper into its own root process and calls its removal directly — operator authority comes only from code already running as root, never from the helper's command line.
 
-The mutating commands print `{ "ok": true, "version": "1.2.0", "unit": "active" }` (`version`: what `current` points at, `null` after `remove`; `unit`: `active`, `inactive` or `absent`). Errors are one line on stderr, `lamaste-apphost: …`.
+The mutating commands print `{ "ok": true, "version": "1.2.0", "unit": "active" }` (`version`: what `current` points at, `null` after `remove`; `unit`: the service's state, `active`, `inactive` or `absent`). Errors are one line on stderr, `lamaste-apphost: …`.
 
 | Exit | Meaning                                                                                                                                                             |
 | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -94,7 +94,7 @@ In this order; nothing of the agent half is written before they pass:
 7. At most 50 agent halves per machine; enough free space in `/opt/lamalibre/apps` for the unpacked package, 4 KiB per entry and a 64 MiB margin.
 8. **The bundled rule**, on the unpacked tree: `package.json` names the spec's package at the version; no non-empty `dependencies` or `optionalDependencies`, no `bundleDependencies`; no `preinstall`, `install` or `postinstall` script; no `binding.gyp`; the service entry is a file in the package. Every file becomes root-owned 0644, every directory 0755 — no executable or set-id bit, nothing the agent half can change.
 
-Then: the approved system packages it lacks are installed (`apt-get install -y --no-install-recommends`, Debian and Ubuntu only), the account, the owner record, the data and config directories are created, the version is moved into place, the unit is written, `current` switched, systemd reloaded and the unit (re)started — once its plugin config is there. A failure before the version is in place takes back what this run created; a failure after it restores the version that ran before, or for a first install removes everything. The current and previous versions are kept; older ones are deleted.
+Then: the approved system packages it lacks are installed (`apt-get install -y --no-install-recommends`, Debian and Ubuntu only), the account, the owner record, the data and config directories are created, the version is moved into place, the unit is written, `current` switched, systemd reloaded and the unit (re)started — once its plugin config is there, with the socket unit that holds its port (see [The socket unit](#the-socket-unit)). A failure before the version is in place takes back what this run created; a failure after it restores the version that ran before, or for a first install removes everything. The current and previous versions are kept; older ones are deleted.
 
 ### What it creates
 
@@ -107,6 +107,7 @@ Then: the approved system packages it lacks are installed (`apt-get install -y -
 | `/etc/lamalibre/apps/<route>/`                      | root:\<account's group\>, 0750   | The agent half's configuration directory                                                                                              |
 | `/etc/lamalibre/apps/<route>/plugin-config.json`    | the account, 0600                | Port and installation secret (`LAMASTE_APP_CONFIG`)                                                                                   |
 | `/etc/systemd/system/lamalibre-app-<route>.service` | root, 0644                       | The unit (below)                                                                                                                      |
+| `/etc/systemd/system/lamalibre-app-<route>.socket`  | root, 0644                       | The socket unit holding the agent half's port (below) — written once its plugin config is there                                       |
 | `/var/lib/lamalibre/apps/.owners/<route>.json`      | root 0644, directory root 0755   | The owner record: `{ route, package, label, since }` — outside the data the agent half can write. Kept on removal, deleted by a purge |
 | `/var/lib/lamalibre/apps/.jobs/used.json`           | root 0600, directory root 0700   | The ids of the signed jobs that ran, each kept until its signature expires                                                            |
 | `/var/lib/lamalibre/apps/.trash/`                   | root, 0700                       | A purged data directory is moved here, out of its account's reach, and deleted                                                        |
@@ -123,13 +124,17 @@ For plugin `market-indicators`, with `memoryMax: "256M"`:
 
 ```ini
 # Managed by lamaste-apphost: the agent half of Lamaste app plugin market-indicators.
+# It listens on the socket systemd holds for it (lamalibre-app-market-indicators.socket), passed as descriptor 3.
 [Unit]
 Description=Lamaste app plugin market-indicators (agent half)
+Requires=lamalibre-app-market-indicators.socket
+After=lamalibre-app-market-indicators.socket
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
+Sockets=lamalibre-app-market-indicators.socket
 User=lamaste-app-market-indicators
 Group=lamaste-app-market-indicators
 ExecStart=/usr/bin/node /opt/lamalibre/apps/market-indicators/current/package/dist/agentd.mjs
@@ -137,7 +142,7 @@ Environment=LAMASTE_APP_CONFIG=/etc/lamalibre/apps/market-indicators/plugin-conf
 Environment=LAMASTE_APP_DATA_DIR=/var/lib/lamalibre/apps/market-indicators
 Environment=NODE_ENV=production
 WorkingDirectory=/var/lib/lamalibre/apps/market-indicators
-Restart=on-failure
+Restart=always
 RestartSec=5
 NoNewPrivileges=yes
 ProtectSystem=strict
@@ -166,6 +171,7 @@ SystemCallFilter=@system-service
 SystemCallErrorNumber=EPERM
 CapabilityBoundingSet=
 UMask=0077
+LimitCORE=0
 MemoryMax=256M
 StandardOutput=journal
 StandardError=journal
@@ -174,31 +180,67 @@ StandardError=journal
 WantedBy=multi-user.target
 ```
 
-The unit is written from a fixed template; it holds paths, never a secret.
-
-| Directive                                                                                                                       | Why                                                                                                                                                                                                                                                       |
-| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `User=` / `Group=` the agent half's account                                                                                     | Plugin code never runs as root or as the agent's user                                                                                                                                                                                                     |
-| `NoNewPrivileges`, `CapabilityBoundingSet=` (empty), `RestrictSUIDSGID`                                                         | No privilege gained through set-id binaries or capabilities; no privileged port, no `chown`                                                                                                                                                               |
-| `ProtectSystem=strict`, `ReadWritePaths=` the data directory, `ReadOnlyPaths=/run`, `ProtectHome`, `PrivateTmp`, `UMask=0077`   | The whole file system read-only but the data directory and a private `/tmp`; `/run` too (strict leaves it writable, and `/run/lock` is world-writable); homes invisible; new files private                                                                |
-| `PrivateDevices`, `TemporaryFileSystem=/dev/shm`, `PrivateIPC`, `RemoveIPC`                                                     | No device nodes, an empty `/dev/shm` it cannot write (PrivateDevices alone binds the machine's, which every user can write; a bundled Node agent half has no use for POSIX shared memory), no shared IPC namespace, its IPC objects removed when it stops |
-| `ProtectProc=invisible`                                                                                                         | Other users' processes are not visible in `/proc`                                                                                                                                                                                                         |
-| `ProtectKernelTunables`, `ProtectKernelModules`, `ProtectKernelLogs`, `ProtectControlGroups`, `ProtectClock`, `ProtectHostname` | The kernel's tunables and modules, the cgroup tree, the clock and the hostname cannot be changed; the kernel log cannot be read                                                                                                                           |
-| `RestrictRealtime`, `RestrictNamespaces`, `LockPersonality`, `SystemCallArchitectures=native`                                   | No realtime scheduling, no new namespaces, no personality or foreign-ABI tricks                                                                                                                                                                           |
-| `SystemCallFilter=@system-service`, `SystemCallErrorNumber=EPERM`                                                               | Only the system calls services need; a call outside the set fails with `EPERM` instead of killing the process (libuv probes `io_uring` and falls back to its thread pool)                                                                                 |
-| `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX`                                                                              | IP and Unix sockets only. Outbound network stays the application's (an agent half fetches what it must); it binds loopback                                                                                                                                |
-| `MemoryMax=`                                                                                                                    | From `agent.service.memoryMax`; left out when the manifest sets none                                                                                                                                                                                      |
-| `Restart=on-failure`, `WantedBy=multi-user.target`                                                                              | Restarted 5 s after a crash; started at boot                                                                                                                                                                                                              |
+The unit is written from a fixed template; it holds paths, never a secret — and no port: that is in its [socket unit](#the-socket-unit), written once the plugin config is there.
+
+| Directive                                                                                                                       | Why                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `User=` / `Group=` the agent half's account                                                                                     | Plugin code never runs as root or as the agent's user                                                                                                                                                                                                                                                                                                                                |
+| `Requires=`, `After=`, `Sockets=` its socket unit                                                                               | The socket listens before the agent half starts, and systemd passes it on every start — at boot, on `start` or `restart`, after a crash, or on a connection while it was stopped — as descriptor 3 (`LISTEN_PID`, `LISTEN_FDS`). Stopping or restarting the socket stops or restarts the agent half                                                                                  |
+| `NoNewPrivileges`, `CapabilityBoundingSet=` (empty), `RestrictSUIDSGID`                                                         | No privilege gained through set-id binaries or capabilities; no privileged port, no `chown`                                                                                                                                                                                                                                                                                          |
+| `ProtectSystem=strict`, `ReadWritePaths=` the data directory, `ReadOnlyPaths=/run`, `ProtectHome`, `PrivateTmp`, `UMask=0077`   | The whole file system read-only but the data directory and a private `/tmp`; `/run` too (strict leaves it writable, and `/run/lock` is world-writable); homes invisible; new files private                                                                                                                                                                                           |
+| `PrivateDevices`, `TemporaryFileSystem=/dev/shm`, `PrivateIPC`, `RemoveIPC`                                                     | No device nodes, an empty `/dev/shm` it cannot write (PrivateDevices alone binds the machine's, which every user can write; a bundled Node agent half has no use for POSIX shared memory), no shared IPC namespace, its IPC objects removed when it stops                                                                                                                            |
+| `ProtectProc=invisible`                                                                                                         | Other users' processes are not visible in `/proc`                                                                                                                                                                                                                                                                                                                                    |
+| `ProtectKernelTunables`, `ProtectKernelModules`, `ProtectKernelLogs`, `ProtectControlGroups`, `ProtectClock`, `ProtectHostname` | The kernel's tunables and modules, the cgroup tree, the clock and the hostname cannot be changed; the kernel log cannot be read                                                                                                                                                                                                                                                      |
+| `RestrictRealtime`, `RestrictNamespaces`, `LockPersonality`, `SystemCallArchitectures=native`                                   | No realtime scheduling, no new namespaces, no personality or foreign-ABI tricks                                                                                                                                                                                                                                                                                                      |
+| `SystemCallFilter=@system-service`, `SystemCallErrorNumber=EPERM`                                                               | Only the system calls services need; a call outside the set fails with `EPERM` instead of killing the process (libuv probes `io_uring` and falls back to its thread pool)                                                                                                                                                                                                            |
+| `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX`                                                                              | IP and Unix sockets only. Outbound network stays the application's (an agent half fetches what it must); it listens on loopback                                                                                                                                                                                                                                                      |
+| `LimitCORE=0`                                                                                                                   | No core dump of a process that holds the installation secret; the hard limit too, so the agent half cannot raise it                                                                                                                                                                                                                                                                  |
+| `MemoryMax=`                                                                                                                    | From `agent.service.memoryMax`; left out when the manifest sets none                                                                                                                                                                                                                                                                                                                 |
+| `Restart=always`, `WantedBy=multi-user.target`                                                                                  | Restarted 5 s after it exits, whatever its exit status; started at boot. A stopped service whose socket still listens would be started by every connection, and five starts within ten seconds trip systemd's start limit — which fails the socket and lets go of the port; restarted on its own, it is never left stopped for a connection to start. Only `systemctl stop` stops it |
 
 Not used, on purpose:
 
 - **`MemoryDenyWriteExecute`** — V8's JIT writes the machine code it runs, which the setting forbids.
 - **`ProcSubset=pid`** — Node.js reads `/proc/cpuinfo`, `/proc/stat` and `/proc/meminfo` for `os.cpus()`, `os.totalmem()` and `os.freemem()`, which applications use to size worker pools; hiding them breaks them quietly.
-- **`AF_NETLINK`** is not among the address families, so `os.networkInterfaces()` fails. An agent half binds `127.0.0.1` and needs no interface list.
+- **`AF_NETLINK`** is not among the address families, so `os.networkInterfaces()` fails. An agent half listens on `127.0.0.1` and needs no interface list.
 - **`IPAddressDeny`** — the application's own outbound calls are its business (market data, a mail relay).
+- **`SocketBindAllow=` / `SocketBindDeny=`** — systemd enforces them only when built with its BPF framework, which the systemd of Ubuntu 22.04 and 24.04 and of Debian 12 is not (they are ignored there, silently), and where they are enforced they deny all UDP from Node.js (`dgram` binds port 0 before its first send). The socket unit keeps the port for the agent half on every distribution instead, and its UDP works.
 
 The journal has the agent half's output: `journalctl -u lamalibre-app-<route>`.
 
+### The socket unit
+
+The agent half never binds its port: systemd does, in a socket unit beside the unit, and passes it the listening socket. For plugin `market-indicators` on port 21007:
+
+```ini
+# Managed by lamaste-apphost: the port of the agent half of Lamaste app plugin market-indicators.
+[Unit]
+Description=Lamaste app plugin market-indicators (agent half socket)
+
+[Socket]
+ListenStream=127.0.0.1:21007
+Accept=no
+NoDelay=true
+Service=lamalibre-app-market-indicators.service
+
+[Install]
+WantedBy=sockets.target
+```
+
+`Accept=no`: one listening socket for one long-running process, not a process per connection. `NoDelay=true` sets `TCP_NODELAY`, as Node.js's own HTTP server does. No `ReusePort=`, so nobody else may bind the port beside it. `sockets.target` wants it, so it listens from early boot; the agent half is still started at boot by `multi-user.target`, not on its first connection.
+
+**Why.** While systemd holds the socket the port stays bound — while the agent half restarts, is updated, crashes or is stopped — so no other local process (another agent half, the agent's user, any account on the machine) can take it in between: there is no window to squat it and answer in its place, nor to hold it and keep the agent half from starting. It works the same on every distribution with systemd, and leaves the agent half's own UDP untouched. (What reaches the port is authenticated as well — see [Security Model](../01-concepts/security-model.md#5d-the-app-host-on-agents).)
+
+**When it is written.** Root-owned 0644, atomically, from the validated plugin config — so not by `install` when the config has not arrived yet: the socket and the unit are first started together by the `config` that brings it (or by an `install` or `activate` once it is there). After that:
+
+- **The same port** (a rotated secret, an update, an activation): the file is left as it is and the socket keeps listening; the unit restarts on it (an update or activation) or not at all (a rotation).
+- **Another port**: the socket moves. The unit is stopped, then the socket — the old port is let go — the file is written, systemd reloaded, the socket started on the new port, and only then the unit. The socket never listens while its file names another port: a daemon-reload would then close its descriptor and leave it active with nothing open. A run cut short leaves the socket stopped or its file not loaded, which the next start puts right. If another process holds the new port, the socket does not start and neither does the unit (`Requires=`), and the helper reports the failure.
+- **The same port in another template** (a newer helper): written and loaded in place — systemd keeps a listening socket across a reload when its address is unchanged — so the port is never let go for it.
+
+Enabling uses `systemctl enable --no-reload`; systemd is reloaded only when a unit file changed (also when systemd reports a unit file it has not loaded, `NeedDaemonReload`).
+
+**On removal** both units are stopped and disabled and both files deleted — the port is released — along with any drop-in directory of the unit (`lamalibre-app-<route>.service.d/`, an operator's overrides), followed by one daemon-reload. A route installed later inherits none of them.
+
 ## Signed app jobs
 
 The helper runs as root on the agent's behalf, so whatever the agent's user could hand it — a service spec naming system packages, a version to activate, a purge — it would otherwise do as root. Approval of what an agent half brings happens on the relay ([approval](lifecycle-hooks.md#approval)); the relay therefore **signs** every app job when it creates it, and the helper refuses anything it did not sign. The agent carries the signature from `agent-config` to the helper and can neither make nor change one.
@@ -281,7 +323,7 @@ The helper reads a pin only from a root-owned file (opened without following lin
 The relay lists app jobs in `GET /api/tunnels/agent-config` (`agentJobs`, see [Agent-Hosted Plugins](agent-hosted-plugins.md#what-the-agent-does-with-it)). The agent's sync timer runs them one after another after converge, outside the agent lock:
 
 - **A job is checked first.** An app job without a signature, with a malformed one, or whose signature does not describe exactly that job (id, route, kind, deadline, payload) is never run and is reported failed.
-- **`app-install`** waits for the next sync until the plugin config has arrived (the relay issues it before it lists the job). Then the agent checks the helper — enabled, answering, protocol ≥ 1, the route not another agent's — fetches a registry token from the panel (`GET /api/agents/me/registry-credential`), runs `npm pack <package>@<version> --ignore-scripts` into a fresh 0700 directory under `~/.lamalibre/lamaste/tmp/agent/` with that token in a throw-away userconfig, refuses a tarball over 128 MiB or one whose SHA-512 is not the pinned integrity, and pipes signature, spec and tarball to `lamaste-apphost install`. Under the agent lock it then records the route in `apphost-state.json` and hands the service its plugin config (`lamaste-apphost config`).
+- **`app-install`** waits for the next sync until the plugin config has arrived (the relay issues it before it lists the job). Then the agent checks the helper — enabled, answering, protocol ≥ 2 (a 4.3 helper speaks 1: `sudo lamaste-agent apphost enable` installs the current one), the route not another agent's — fetches a registry token from the panel (`GET /api/agents/me/registry-credential`), runs `npm pack <package>@<version> --ignore-scripts` into a fresh 0700 directory under `~/.lamalibre/lamaste/tmp/agent/` with that token in a throw-away userconfig, refuses a tarball over 128 MiB or one whose SHA-512 is not the pinned integrity, and pipes signature, spec and tarball to `lamaste-apphost install`. Under the agent lock it then records the route in `apphost-state.json` and hands the service its plugin config (`lamaste-apphost config`).
 - **`app-activate`** and **`app-remove`** hand the signature to `activate` / `remove`. Removing with the helper disabled succeeds (`disable` removed every agent half first) unless it is a purge.
 - **Failures are reported, never undone here.** The agent cannot sign, so it never removes or switches an agent half on its own: the relay, which recovers from every install it dispatched, sends the signed removal or activation. A result is kept in `app-job-results.json` until the relay took it — the helper runs a signed job once, so a report that failed is made again on the next sync without running the job again.
 - **Plugin configs.** For a route recorded in `apphost-state.json`, converge hands a fetched config to the service (`lamaste-apphost config`) **before** acknowledging it, so the relay never signs with a secret the service does not hold; a rotation therefore needs no restart. When the record cannot be read nothing is delivered or acknowledged until the sync rebuilds it from the helper's owner records.
@@ -310,22 +352,29 @@ The contract:
 - **The entry** is a relative `.js`, `.mjs` or `.cjs` path in the package, run as `/usr/bin/node <entry>` — the Node.js of the helper, which `agent.requires.node` is checked against.
 - **Files are read-only.** Every file is installed root-owned 0644 — no executable bit, so the agent half spawns no program of its own package directly; directories 0755.
 - **It writes only its data directory**, `LAMASTE_APP_DATA_DIR` (also its working directory, 0700), and its private `/tmp`. Use `node:sqlite` for a database.
-- **Its config** is `LAMASTE_APP_CONFIG` (0600): `{ plugin, port, secret, issuedAt, previousSecret?, previousIssuedAt?, fetchedAt, acknowledged }`. Listen on `127.0.0.1:<port>` and verify every `/admin/*` request:
+- **Its config** is `LAMASTE_APP_CONFIG` (0600): `{ plugin, port, secret, issuedAt, previousSecret?, previousIssuedAt?, fetchedAt, acknowledged }`. Verify every `/admin/*` request with it.
+- **Listen on the socket systemd passes — never bind a port yourself.** `agentHalfListenTarget()` answers `{ fd: 3, host: '127.0.0.1' }` under the helper's unit; systemd holds the port, so binding it fails with `EADDRINUSE`. Give it the config's port so the same code also runs as an agent half installed by hand (no socket: it answers `{ host: '127.0.0.1', port }`):
 
   ```js
-  import { createCallerAssertionVerifier } from '@lamalibre/lamaste@4.3.0/agent'; // bundled
+  import Fastify from 'fastify';
+  import { agentHalfListenTarget, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.4.0/agent'; // bundled
 
   const verifier = createCallerAssertionVerifier({
     configPath: process.env.LAMASTE_APP_CONFIG,
     plugin: 'market-indicators',
   });
-  const port = await verifier.port();
+  const target = agentHalfListenTarget({ port: await verifier.port() });
+
+  const app = Fastify();
+  // …routes
+  await app.listen(target); // or, with node:http: http.createServer(handler).listen(target)
   ```
 
-  The verifier re-reads the file when a signature does not verify, so a rotated secret needs no restart; a changed port restarts the unit.
+  Pass the target to Fastify as it is: with `fd`, its `host` keeps Fastify from opening a second server on the descriptor for `::1` (its default host is `localhost`). Call it once, at start-up: it reads systemd's `LISTEN_PID`, `LISTEN_FDS` and `LISTEN_FDNAMES` and removes them from `process.env`, so no process the agent half starts takes the socket for its own. Any number of sockets but one is refused. The verifier re-reads the config when a signature does not verify, so a rotated secret needs no restart; a changed port moves the socket and restarts the unit on it.
 
 - **Lifecycle hooks** are answered at `POST /admin/hooks/<stage>` ([agent hooks](lifecycle-hooks.md#agent-hooks)); the agent's own `install:pre-tunnel` reaches the service on its loopback once it runs.
-- **Limits of the sandbox:** no capabilities (no port below 1024), IP and Unix sockets only, no `os.networkInterfaces()`, only its own processes in `/proc`. Its output goes to the journal; `NODE_ENV=production`.
+- **Settings**, when the manifest declares them, are kept with `createSettingsStore` over `LAMASTE_APP_DATA_DIR` — `settings.json` and `secrets.json`, 0600 — and answered at `/admin/settings` with `createSettingsHandler` ([Settings](agent-hosted-plugins.md#in-the-agent-half)); they stay with the retained data and a purge deletes them.
+- **Limits of the sandbox:** no capabilities (no port below 1024), IP and Unix sockets only, no `os.networkInterfaces()`, only its own processes in `/proc`, no core dumps. Its output goes to the journal; `NODE_ENV=production`.
 - **System packages** (`agent.requires.systemPackages`) are installed with `apt-get` after approval, on Debian and Ubuntu only.
 - **Name** the plugin by its route: a plugin with an agent half is named exactly its route (its packages keep their names), and the route starts and ends with a letter or digit.
 
@@ -355,6 +404,6 @@ Removing an agent half without purge — unhosting, uninstalling, a rolled-back
 - **System packages are never removed** — not on removal, not on purge.
 - **No other package managers:** system packages are installed on Debian and Ubuntu only; elsewhere a plugin that declares them cannot be hosted.
 - **macOS agents** cannot host an agent half Lamaste installs; an agent half installed by hand is still hosted the 2a way.
-- **Settings and secrets** of an agent half (slice 4) are not delivered yet; the plugin config carries the port and the installation secret only.
+- **No settings in the plugin config:** it carries the port and the installation secret only. A plugin's settings and secrets reach its agent half over the tunnel (`PUT /admin/settings`, secrets sealed to the installation secret), never as a file Lamaste writes on the agent — see [Agent-Hosted Plugins](agent-hosted-plugins.md).
 
 See [Config Files](../06-reference/config-files.md#agent-machine-the-app-host) for every file with its owner and mode, and [Security Model](../01-concepts/security-model.md#5d-the-app-host-on-agents) for the trust model.

package/vendor/docs/04-api-reference/audit-and-notifications.md

@@ -1,6 +1,6 @@
 # Audit Log & Notifications
 
-The panel keeps an **audit log** of administrative decisions — approving a plugin's relay hooks, switching auto-approve, hosting and removing a hosting, installing, updating and uninstalling a plugin — and of what plugins' [lifecycle hooks](lifecycle-hooks.md) report through the `audit` effect. **Notifications** are messages for the relay's administrators: a hook's `notify-admins` effect, an update waiting for approval (with why auto-approve did not cover it), a rule pack updated with Lamaste. Both live in `state.db` and hold metadata only — never a request or response body or a secret.
+The panel keeps an **audit log** of administrative decisions — approving a plugin's relay hooks, switching auto-approve, hosting and removing a hosting, installing, updating and uninstalling a plugin — and of what plugins' [lifecycle hooks](lifecycle-hooks.md) report through the `audit` effect. **Notifications** are messages for the relay's administrators: a hook's `notify-admins` effect, an update waiting for approval (with why auto-approve did not cover it), a plugin's settings changed outside Lamaste, a rule pack updated with Lamaste. Both live in `state.db` and hold metadata only — never a request or response body or a secret.
 
 All endpoints are admin only.
 
@@ -31,16 +31,16 @@ Newest first. Query: `plugin`, `action` (exact, or a prefix ending in `.` such a
 | `auto-approve`   | a plugin's auto-approve                                      |
 | `lamaste`        | the panel itself                                             |
 
-Actions written by Lamaste: `plugin.installed`, `plugin.uninstalled`, `plugin.hosted`, `plugin.unhosted`, `plugin.updated`, `plugin.update.reverted`, `plugin.update.awaiting-approval`, `plugin.update.discarded`, `hooks.approved`, `hooks.auto-approve.enabled|disabled`, `hooks.auto-approve.withheld`, `hooks.rules-updated`, `hooks.effects-dropped`, and for an [agent half Lamaste installs](app-host.md):
+Actions written by Lamaste: `plugin.installed`, `plugin.uninstalled`, `plugin.hosted`, `plugin.unhosted`, `plugin.updated`, `plugin.update.reverted`, `plugin.update.awaiting-approval`, `plugin.update.discarded`, `hooks.approved`, `hooks.auto-approve.enabled|disabled`, `hooks.auto-approve.withheld`, `hooks.rules-updated`, `hooks.effects-dropped`, `plugin.settings.updated` (a change of a plugin's [settings](agent-hosted-plugins.md#settings), by key name only — `changed`, `cleared`, `secretsSet`, `secretsCleared`, the new `revision` — never a value; `confirmedLater: true` when its answer was lost and a later read found it stored), `plugin.settings.changed-outside-lamaste` (actor `lamaste`: a read found the agent half at a revision Lamaste did not write — `changed` and `secretsChanged`, the names of the settings that differ from the relay's cache, `fromRevision`, `revision`, `agentLabel`; never a value; the administrators are warned too), and for an [agent half Lamaste installs](app-host.md):
 
-| Action                                      | When                                                                                                                                                 |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plugin.agent-half.installed`               | The agent reported the pinned version installed and its unit active — `agentLabel`, `package`, `version`, `integrity`, `phase`, `retainedDataReused` |
-| `plugin.agent-half.activated`               | A failed update switched the agent back to the version before — `version`, `from`                                                                    |
-| `plugin.agent-half.removed`                 | Removed from the agent — `version`, `purge`, `phase` (`uninstall` or `rollback`)                                                                     |
-| `plugin.agent-half.purged`                  | Retained data purged on the agent — `route`, `package`                                                                                               |
-| `plugin.agent-half.retained-data.forgotten` | The relay's record of retained data dropped without touching the agent                                                                               |
-| `hooks.auto-approve.withheld`               | Auto-approve did not cover an update because its agent half changes what runs as root — `reasons`                                                    |
+| Action                                      | When                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plugin.agent-half.installed`               | The agent reported the pinned version installed and its unit active — `agentLabel`, `package`, `version`, `integrity`, `phase`, `retainedDataReused`                                                                                                                                                                       |
+| `plugin.agent-half.activated`               | A failed update switched the agent back to the version before — `version`, `from`                                                                                                                                                                                                                                          |
+| `plugin.agent-half.removed`                 | Removed from the agent — `version`, `purge`, `phase` (`uninstall` or `rollback`)                                                                                                                                                                                                                                           |
+| `plugin.agent-half.purged`                  | Retained data purged on the agent — `route`, `package`                                                                                                                                                                                                                                                                     |
+| `plugin.agent-half.retained-data.forgotten` | The relay's record of retained data dropped without touching the agent                                                                                                                                                                                                                                                     |
+| `hooks.auto-approve.withheld`               | Auto-approve did not cover an update because its agent half changes what runs as root, or it turns a secret setting into a plain one — `reasons` (sentences) and `codes` (`agent-half.added`, `agent-half.package`, `agent-half.system-packages`, `agent-half.entry`, `agent-half.memory-max`, `settings.secret-to-plain`) |
 
 Details are capped at 4 KiB (strings at 300 characters, three levels deep). Entries are kept 180 days, at most 50 000.
 

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

@@ -369,6 +369,7 @@ curl -s --cert client.p12:password \
         "apphost": null
       },
       "hostFactsAt": "2026-10-16T09:00:00.000Z",
+      "lastSeenAt": "2026-10-16T10:04:51.000Z",
       "pushInstallEnabledUntil": "2026-10-16T10:30:00.000Z",
       "pushInstallPolicy": "default"
     },
@@ -384,30 +385,32 @@ curl -s --cert client.p12:password \
       "expiringSoon": false,
       "status": "revoked",
       "hostFacts": null,
-      "hostFactsAt": null
+      "hostFactsAt": null,
+      "lastSeenAt": null
     }
   ]
 }
 ```
 
-| Field                     | Type                  | Description                                                                                                                                                                                     |
-| ------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label`                   | `string`              | Agent identifier (matches certificate CN `agent:<label>`)                                                                                                                                       |
-| `serial`                  | `string`              | Certificate serial number                                                                                                                                                                       |
-| `capabilities`            | `string[]`            | Granted capabilities                                                                                                                                                                            |
-| `allowedSites`            | `string[]`            | Site names this agent can access for file operations                                                                                                                                            |
-| `enrollmentMethod`        | `string`              | `"p12"`, `"hardware-bound"`, or `"delegated"` — how the agent certificate was issued                                                                                                            |
-| `delegatedBy`             | `string \| undefined` | For delegated certs: the label of the delegating agent                                                                                                                                          |
-| `certType`                | `string \| undefined` | `"plugin-agent"` for delegated certs, absent for regular agents                                                                                                                                 |
-| `createdAt`               | `string`              | ISO 8601 creation timestamp                                                                                                                                                                     |
-| `expiresAt`               | `string`              | ISO 8601 expiry timestamp                                                                                                                                                                       |
-| `revoked`                 | `boolean`             | Whether the certificate has been revoked                                                                                                                                                        |
-| `expiringSoon`            | `boolean`             | `true` if the certificate is not revoked and fewer than 30 days remain until expiry                                                                                                             |
-| `status`                  | `string`              | `"revoked"`, `"expired"`, `"expiring-soon"` (within 30 days) or `"active"`, in that order                                                                                                       |
-| `hostFacts`               | `object \| null`      | What the agent last reported about its host (OS, distribution, architecture, Node.js, systemd, its app host helper) — see [Host facts](agent-hosted-plugins.md#host-facts); `null` until it has |
-| `hostFactsAt`             | `string \| null`      | When it reported them                                                                                                                                                                           |
-| `pushInstallEnabledUntil` | `string \| undefined` | End of the agent's last push-install window (open while in the future); absent once it is closed                                                                                                |
-| `pushInstallPolicy`       | `string \| undefined` | The push-install policy of that window                                                                                                                                                          |
+| Field                     | Type                  | Description                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`                   | `string`              | Agent identifier (matches certificate CN `agent:<label>`)                                                                                                                                                                                                                                                                                                         |
+| `serial`                  | `string`              | Certificate serial number                                                                                                                                                                                                                                                                                                                                         |
+| `capabilities`            | `string[]`            | Granted capabilities                                                                                                                                                                                                                                                                                                                                              |
+| `allowedSites`            | `string[]`            | Site names this agent can access for file operations                                                                                                                                                                                                                                                                                                              |
+| `enrollmentMethod`        | `string`              | `"p12"`, `"hardware-bound"`, or `"delegated"` — how the agent certificate was issued                                                                                                                                                                                                                                                                              |
+| `delegatedBy`             | `string \| undefined` | For delegated certs: the label of the delegating agent                                                                                                                                                                                                                                                                                                            |
+| `certType`                | `string \| undefined` | `"plugin-agent"` for delegated certs, absent for regular agents                                                                                                                                                                                                                                                                                                   |
+| `createdAt`               | `string`              | ISO 8601 creation timestamp                                                                                                                                                                                                                                                                                                                                       |
+| `expiresAt`               | `string`              | ISO 8601 expiry timestamp                                                                                                                                                                                                                                                                                                                                         |
+| `revoked`                 | `boolean`             | Whether the certificate has been revoked                                                                                                                                                                                                                                                                                                                          |
+| `expiringSoon`            | `boolean`             | `true` if the certificate is not revoked and fewer than 30 days remain until expiry                                                                                                                                                                                                                                                                               |
+| `status`                  | `string`              | `"revoked"`, `"expired"`, `"expiring-soon"` (within 30 days) or `"active"`, in that order                                                                                                                                                                                                                                                                         |
+| `hostFacts`               | `object \| null`      | What the agent last reported about its host (OS, distribution, architecture, Node.js, systemd, its app host helper) — see [Host facts](agent-hosted-plugins.md#host-facts); `null` until it has                                                                                                                                                                   |
+| `hostFactsAt`             | `string \| null`      | When it reported them                                                                                                                                                                                                                                                                                                                                             |
+| `lastSeenAt`              | `string \| null`      | When the agent last contacted the relay — its sync's `GET /api/tunnels/agent-config`, every 30 seconds (written to `state.db` at most once a minute, so a panel restart loses at most that minute). `null` until its first such call, and for a revoked agent. See [When the hosting agent is offline](agent-hosted-plugins.md#when-the-hosting-agent-is-offline) |
+| `pushInstallEnabledUntil` | `string \| undefined` | End of the agent's last push-install window (open while in the future); absent once it is closed                                                                                                                                                                                                                                                                  |
+| `pushInstallPolicy`       | `string \| undefined` | The push-install policy of that window                                                                                                                                                                                                                                                                                                                            |
 
 ---
 

package/vendor/docs/04-api-reference/lifecycle-hooks.md

@@ -70,7 +70,8 @@ Relay hooks are code Lamaste runs on the relay, and an [agent half Lamaste insta
 
 - Installing a plugin with relay hooks or an agent half Lamaste installs leaves them **pending**: the plugin can be enabled, but not hosted, and its forwarded API answers `503 { code: "hooks_not_approved" }` until the approval.
 - **Approving** names the digest the administrator saw; if what the version brings changed meanwhile the panel answers `409` with the current digest.
-- **Updating** a plugin whose new version brings another hook set or agent half waits for approval; the installed version stays live. **Auto-approve**, off by default and per plugin, approves such changes automatically — each use is in the audit log — except an agent half change that runs more as root: an agent half where there was none, another agent package, added system packages, another service entry or memory limit ([withheld](agent-hosted-plugins.md#approval)).
+- **Updating** a plugin whose new version brings another hook set or agent half waits for approval; the installed version stays live. **Auto-approve**, off by default and per plugin, approves such changes automatically — each use is in the audit log — except an agent half change that runs more as root (an agent half where there was none, another agent package, added system packages, another service entry or memory limit; [withheld](agent-hosted-plugins.md#approval)).
+- A version that turns a secret setting into a plain one — whose next value the relay would keep in clear — **always waits for an administrator**: settings are outside the digest, so this is a gate of its own, held even when the digest is already approved, when the plugin brings neither relay hooks nor an agent half, and whatever auto-approve says. The pending update says why it waits (`approvalRequired`), and its approval covers both.
 - Agent hooks are the plugin's own code on its own agent and need no approval. Shared hooks are part of the approved set by name and settings; their rules ride Lamaste releases (see below).
 
 Every approval, auto-approve change and auto-approval is recorded in the [audit log](audit-and-notifications.md) with the administrator certificate's serial.
@@ -132,11 +133,27 @@ Every approval, auto-approve change and auto-approval is recorded in the [audit
 }
 ```
 
-`failOpen` lists a hook's fail-open settings (`onError`, `onOversize`, `onUnscannable`); the panel highlights them. `relay.digest` is the relay hook set's own digest (what the runner holds); `approval.digest` is the one to approve, covering the relay hooks and `agentHalf` — the agent half Lamaste installs, `null` when there is none or it is installed by hand ([App Host](app-host.md)). `pendingUpdate` is `{ version, digest, stagedAt, relay, agentHalf, autoApproveWithheld }` while an update waits — `autoApproveWithheld` lists why auto-approve did not cover it (`null` otherwise).
+`failOpen` lists a hook's fail-open settings (`onError`, `onOversize`, `onUnscannable`); the panel highlights them. `relay.digest` is the relay hook set's own digest (what the runner holds); `approval.digest` is the one to approve, covering the relay hooks and `agentHalf` — the agent half Lamaste installs, `null` when there is none or it is installed by hand ([App Host](app-host.md)). `pendingUpdate` is `{ version, digest, stagedAt, relay, agentHalf, settings, approvalRequired, autoApproveWithheld }` while an update waits — `digest` is the one to approve it with (`null` when it brings neither relay hooks nor an agent half: it is approved by its version), `settings` lists how the version changes the plugin's [settings schema](agent-hosted-plugins.md#in-the-plugin-list-and-the-update-preview) (`{ added: [{ key, type }], removed: [{ key, type }], retyped: [{ key, from, to }], newRequired: [key], secretToPlain: [key] }`, `null` when neither version declares settings; not part of the digest), `approvalRequired` why it waits for an administrator, and `autoApproveWithheld` why auto-approve, when on, did not cover it, in sentences (`null` otherwise):
+
+```json
+"approvalRequired": [
+  { "code": "digest.unapproved", "reason": "its agent half is not what was approved" },
+  {
+    "code": "settings.secret-to-plain",
+    "reason": "it turns secret settings into plain ones (apiKey) — what is typed into them next is kept on the relay and shown in clear"
+  }
+]
+```
+
+`digest.unapproved`: what it brings — relay hooks, an agent half Lamaste installs — is not what was approved (auto-approve may stand in for an administrator on it). `settings.secret-to-plain`: it turns secret settings into plain ones — always an administrator's call, its digest approved or not.
 
 ### `POST /api/plugins/:name/hooks/approve`
 
-`{ "digest": "…" }` — the installed set's digest (`200 { ok, hooks }`) or a pending update's (the update is applied: `202 { ok, operation }`). `409` when the set changed since it was shown.
+`{ "digest": "…" }` — the installed set's digest (`200 { ok, hooks }`) or a pending update's (the update is applied: `202 { ok, operation }`). `409` with `currentDigest` when the set changed since it was shown.
+
+`{ "digest": "…" | null, "version": "1.2.3" }` — the pending update to that version, named by its version and its digest (`null`, or left out, when it has none: an update that brings neither relay hooks nor an agent half and waits only because it turns a secret setting into a plain one). `409` when another version waits, or its digest changed (`currentDigest`, possibly `null`); `400` when it has a digest and none is given. The panel and `lamaste-server plugins approve-hooks` always name the version of an update they approve.
+
+Approving a pending update approves everything it waits for (`approvalRequired`), whether its digest changed or is the one already approved. The version is fetched again and must still have the approved digest and turn no other secret setting plain than those shown — `409` otherwise, and nothing is applied. The approval is recorded once the update starts under it: `hooks.approved` with `for: "update"` and the `codes` it covered.
 
 ### `PUT /api/plugins/:name/hooks/auto-approve`
 
@@ -149,7 +166,7 @@ Every approval, auto-approve change and auto-approval is recorded in the [audit
 `{ "version"?: "1.2.3" | "latest" }` (default `latest`). For agent-hosted plugins. The panel fetches the version with `npm pack` and reads its manifest and relay module **in memory** — nothing of it is installed yet. Then:
 
 - `200 { upToDate: true }` — nothing to do;
-- `202 { pendingUpdate }` — what it brings (relay hook set, agent half) differs from what was approved and auto-approve is off or withheld; approve it with the digest shown;
+- `202 { pendingUpdate }` — what it brings (relay hook set, agent half) differs from what was approved and auto-approve is off or withheld, or it turns a secret setting into a plain one (always); `approvalRequired` says which, and the administrators are notified. Approve it with the digest shown, or by its version;
 - `202 { operation }` — the update runs: the new hook module goes into the runner, the install pipeline runs with `phase: "upgrade"` around installing the package (agent stages through the tunnel), and a failure restores the previous package, row and module.
 
 The agent half of a hosted plugin whose agent half Lamaste installs is pinned when the version is staged and installed on the agent **first**, after the agent's pre stage; a failure after that activates the version that ran before ([Hosting with an agent half](agent-hosted-plugins.md#the-pipelines)). That is a push: the hosting agent must be eligible for the new version and push install must allow `update` — checked when the update starts, not while it waits for approval.
@@ -233,13 +250,13 @@ Relay hooks run in `lamalibre-lamaste-hooks@<route>.service`, started by its soc
 
 `lamaste-priv hooks install <route> <sha256|none>` (module on stdin, checked against the approved digest) writes the module root-owned to `/opt/lamalibre/lamaste/hooks/<route>/<sha256>.mjs` and enables the socket; `hooks activate` points back at the previous module (an update's revert); `hooks restart` stops a stuck runner; `hooks remove` disables it and deletes its modules. The panel reinstalls an approved runner at start-up if it is missing.
 
-The protocol between the panel and the runner is one length-prefixed JSON frame each way per connection (`@lamalibre/lamaste@4.3.0/hooks`, `protocol.ts`).
+The protocol between the panel and the runner is one length-prefixed JSON frame each way per connection (`@lamalibre/lamaste@4.4.0/hooks`, `protocol.ts`).
 
 ## Writing hooks
 
 ```js
 // hooks/relay.mjs — bundled into one file (esbuild), Node built-ins only
-import { defineRelayHooks } from '@lamalibre/lamaste@4.3.0/hooks';
+import { defineRelayHooks } from '@lamalibre/lamaste@4.4.0/hooks';
 
 export default defineRelayHooks({
   'install:pre-tunnel': async (input) =>
@@ -262,14 +279,16 @@ export default defineRelayHooks({
 | `request:post-forward`      | `status`, `headers`, `request`, `route`, `body?`                                                                                        | `{ action: 'pass' }` / `{ action: 'replace', body, contentType?, setHeaders? }` / `{ action: 'block', status?, reasonId }` |
 | `tunnel:down` / `tunnel:up` | `state`, `reason`, `since`, `lastError?`                                                                                                | `{ fallback? }` (down) / `{}`                                                                                              |
 
+`settings` in a relay hook's input is the plugin's effective non-secret [settings](agent-hosted-plugins.md#settings) — each stored value or its default, from the relay's cache (`{}` while it never read them); an agent hook gets `{}`, since the agent half holds the settings itself. Neither ever gets a secret.
+
 Every decision may carry `effects` (at most 10): `{ type: 'audit', event, data? }`, `{ type: 'notify-admins', message, level? }`, `{ type: 'log', message, level?, data? }` — rate-limited per plugin (60, 6 and 120 a minute). Header edits may not touch `Host`, framing, `Cookie`/`Set-Cookie`, `Authorization`, `X-Forwarded-*`, `X-Lamalibre-*`, `X-SSL-Client-*`, `Remote-*` or `X-Accel-*`.
 
 ### Agent hooks
 
-The agent half answers `POST /admin/hooks/<stage>` (body `{ stage, input }`, answer `{ ok: true, output? }` or `{ ok: false, reason }`). `createAgentHookHandler` from `@lamalibre/lamaste@4.3.0/agent` does the checking — the caller assertion must name Lamaste itself (`{ type: 'lamaste' }`), which no forwarded caller can, and the forwarder never reaches `/admin/hooks`:
+The agent half answers `POST /admin/hooks/<stage>` (body `{ stage, input }`, answer `{ ok: true, output? }` or `{ ok: false, reason }`). `createAgentHookHandler` from `@lamalibre/lamaste@4.4.0/agent` does the checking — the caller assertion must name Lamaste itself (`{ type: 'lamaste' }`), which no forwarded caller can, and bind the SHA-256 of the exact body (`wrong_body` otherwise), so it needs the body **as received** (a `Buffer` or a string; a parsed object is refused `400` "The body must be passed as received"); the forwarder never reaches `/admin/hooks*`. Send the `status`, `headers` and `bodyText` it returns, `bodyText` byte for byte: its `X-Lamalibre-Responder` header signs those bytes, and the relay counts a hook answer without a valid one as a failure (`unauthenticated`) — see [Authentication between the relay and the agent half](agent-hosted-plugins.md#authentication-between-the-relay-and-the-agent-half):
 
 ```js
-import { createAgentHookHandler, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.3.0/agent';
+import { createAgentHookHandler, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.4.0/agent';
 
 const hooks = createAgentHookHandler({
   verifier: createCallerAssertionVerifier({ configPath, plugin: 'fx' }),
@@ -279,8 +298,9 @@ const hooks = createAgentHookHandler({
     'tunnel:down': () => queueLocally(),
   },
 });
-// in the agent half's router, for POST /admin/hooks/*:
-const { status, body } = await hooks.handle({ method, url, headers, body: rawBody });
+// in the agent half's router, for POST /admin/hooks/* (the body as received):
+const out = await hooks.handle({ method, url, headers, body: rawBody });
+res.writeHead(out.status, out.headers).end(out.bodyText);
 ```
 
 The relay calls agent hooks through the tunnel while it exists. Before the tunnel is granted and after it is removed, the relay lists an **agent job** in `GET /api/tunnels/agent-config` (`agentJobs: [{ id, route, kind: "hook", stage, input, timeoutMs, deadlineAt }]`); the agent's sync calls the agent half on its own loopback with the installation secret it holds and reports `POST /api/agents/me/jobs/:id/result` (`{ ok: true, decision }` or `{ ok: false, error }`; hosting agent only, once). A job whose agent half does not answer yet waits for the next sync, until its deadline (timeout plus 90 s).
@@ -311,7 +331,9 @@ Matching runs on the raw text: a JSON-escaped PEM key is found, and nothing but
 
 ```
 lamaste-server plugins hooks <name>                         # the relay hook set, its digest and approval
-lamaste-server plugins approve-hooks <name> --digest <sha>  # approve (or approve a pending update)
+lamaste-server plugins approve-hooks <name> --digest <sha> [--version <v>]
+                                                            # approve; a pending update by its version too
+                                                            # (--version alone when it has no digest)
 lamaste-server plugins auto-approve <name> on|off
 lamaste-server plugins update <name> [--version <v>]
 lamaste-server plugins discard-update <name>

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

@@ -255,7 +255,7 @@ The wildcard check probes `test-lamaste-check.<domain>`. Wildcard DNS is optiona
 
 ### `POST /api/onboarding/provision`
 
-Starts the full stack provisioning process in the background. This configures and starts Chisel and Authelia, issues certbot certificates, and writes nginx vhosts. The Chisel and Authelia binaries and units are installed by `create-lamaste`, not here: if one is missing, the task fails with the error "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.3.0` on the server to repair the installation." (likewise for Authelia). Task IDs are unchanged from earlier versions; only the titles changed.
+Starts the full stack provisioning process in the background. This configures and starts Chisel and Authelia, issues certbot certificates, and writes nginx vhosts. The Chisel and Authelia binaries and units are installed by `create-lamaste`, not here: if one is missing, the task fails with the error "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.4.0` on the server to repair the installation." (likewise for Authelia). Task IDs are unchanged from earlier versions; only the titles changed.
 
 Provisioning runs asynchronously. This endpoint returns immediately with a 202 status. Use the WebSocket stream endpoint to follow progress in real time.