@lamalibre/create-lamaste 4.4.0 → 4.5.0

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

@@ -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.4.0   # a root-owned install
+sudo npm install -g @lamalibre/lamaste-agent@4.5.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.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.
+`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.5.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:
 
@@ -357,7 +357,7 @@ The contract:
 
   ```js
   import Fastify from 'fastify';
-  import { agentHalfListenTarget, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.4.0/agent'; // bundled
+  import { agentHalfListenTarget, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.5.0/agent'; // bundled
 
   const verifier = createCallerAssertionVerifier({
     configPath: process.env.LAMASTE_APP_CONFIG,

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

@@ -4,7 +4,9 @@
 
 ## Authentication
 
-All Gatekeeper endpoints proxied through the panel require admin mTLS authentication. The internal `authz/tunnel/<fqdn>` endpoint on `127.0.0.1:9294` is called by nginx only and is not exposed externally.
+All Gatekeeper endpoints proxied through the panel require admin mTLS authentication. The internal `authz/tunnel/<fqdn>` and `authz/user-surface/<fqdn>` endpoints on `127.0.0.1:9294` are called by nginx only and are not exposed externally; Gatekeeper's own management API (`127.0.0.1:9294/api/*`, the shared secret in `gatekeeper-secret.json`) is called by the panel only.
+
+**Grants and groups decide who uses agent-hosted plugins.** A plugin grant whose `context` names `roles` is an **entitlement** ([Agent-Hosted Plugins](agent-hosted-plugins.md#entitlements-and-the-audience)): every grant or group change that goes through the proxy is followed by a recompute of the plugins' audiences before the answer goes back, and anything given to a username — a user grant, a group membership — first clears what a removed user who held that username left in Gatekeeper ([Users API](users.md#usernames-and-gatekeeper)); when that cannot complete, the proxy answers `503` with `code: "gatekeeper_unavailable"`. Gatekeeper's own CLI writes the same database without telling the panel; the panel's minute-long recompute picks such edits up.
 
 If the Gatekeeper service is unavailable, proxied endpoints return `503 Service Unavailable`.
 
@@ -195,7 +197,7 @@ Add one or more members to a group.
 }
 ```
 
-**Errors:** 400 (invalid or empty usernames array), 404 (group not found)
+**Errors:** 400 (invalid or empty usernames array), 404 (group not found), 503 (a removed user's principal under one of the usernames cannot be cleared — `code: "gatekeeper_unavailable"`)
 
 ---
 
@@ -268,7 +270,9 @@ Create a new authorization grant linking a principal (user or group) to a resour
 }
 ```
 
-**Errors:** 400 (invalid body), 409 (duplicate grant), 503 (Gatekeeper unavailable)
+**Plugin role grants.** For `resourceType: "plugin"` with `context.roles`, the panel checks the grant before Gatekeeper sees it: `resourceId` must be the route of an installed plugin that declares `identity` (`400`, `code: "no_identity"`) and `roles` a non-empty list of its role ids (`400`, `code: "invalid_roles"`, or `"unknown_roles"` with the `unknown` ones); they go on sorted and without repeats. The plugin's **People** panel and `lamaste-server plugins entitlements` manage these grants one principal at a time (`PUT /api/plugins/:name/entitlements` replaces a principal's role grants) — prefer them to creating one here. A plugin grant without `roles` (the desktop's local-install grants) never makes anyone a plugin user.
+
+**Errors:** 400 (invalid body; a role grant as above), 409 (duplicate grant), 503 (Gatekeeper unavailable, or a removed user's principal under `principalId` cannot be cleared — `code: "gatekeeper_unavailable"`)
 
 ---
 
@@ -555,16 +559,31 @@ DELETE /api/gatekeeper/access-log
 
 **Auth:** Admin only
 
-Delete all access log entries.
+Delete all access log entries. It takes no query: Gatekeeper refuses one (`400`), so a narrowing query from an older caller never clears the whole log instead.
 
 **Response (200):**
 
 ```json
 {
-  "ok": true
+  "ok": true,
+  "removed": 142
 }
 ```
 
+### Purge One User's Access-Log Entries
+
+```
+POST /api/gatekeeper/access-log/purge
+```
+
+**Auth:** Admin only
+
+```json
+{ "username": "alice", "before": "2026-10-22T08:00:00.000Z" }
+```
+
+Deletes only that user's entries — logged before `before` (ISO 8601 UTC, optional) when given, since a later user may have the same username — and the entries still queued for the log, so none of them is written afterwards. `{ "ok": true, "removed": 3 }`; `400` for a body that is not `{ username, before? }`. The username travels in the body, never in a URL that request logs keep. The panel calls Gatekeeper's `POST /api/access-log/purge` itself when it [erases](users.md#erasing-a-removed-user) a removed user.
+
 ---
 
 ## Internal Endpoints
@@ -581,6 +600,12 @@ GET /authz/tunnel/:fqdn
 
 This is the nginx `auth_request` target. nginx calls this endpoint on every request to a Gatekeeper-protected resource. The tunnel vhost names its tunnel in the path (`proxy_pass http://127.0.0.1:9294/authz/tunnel/<fqdn>;`) and sends the same hostname in `X-Original-URL` (with the request's path and query) and `Host`; a request whose `X-Original-URL` or `Host` names another hostname, or has no `Host`, is refused with 401. Gatekeeper validates the user's Authelia session cookie for that URL and checks the corresponding grant.
 
+**The session cookie.** Of the browser's `Cookie` header Gatekeeper reads the `authelia_session` pair alone (core `autheliaSessionCookies`: a pair whose name, spaces and tabs trimmed, is exactly `authelia_session`) and sends Authelia `Cookie: authelia_session=<value>` — never the browser's other cookies. A request carrying **more than one** `authelia_session` is refused with `401` before Authelia is asked (logged `duplicate_authelia_cookie`): another host under the domain can plant a second one under another path, and which one Authelia would read is not Gatekeeper's to guess. A validated session is cached for `sessionCacheTtlMs` (30 s) under an HMAC of the cookie value **and the tunnel host** — Authelia decides per host, so a session accepted on one host is asked about again on another.
+
+**Rate limit.** Every authorization route (`/authz/tunnel/:fqdn`, `/authz/user-surface/:fqdn`, `/authz/user-surface-unauthenticated`, `/authz/check`) allows 6000 requests a minute per client address and tunnel host (`AUTHZ_RATE_LIMIT_PER_CLIENT`), `429` past it. The client address is `X-Forwarded-For`, which nginx sets to `$remote_addr` on every subrequest and Gatekeeper trusts from `127.0.0.1` only (`trustProxy`) — one client exhausting its bucket leaves the others theirs. The management API keeps one shared bucket (1000 a minute): only the panel and local tooling reach it.
+
+**Logs.** A refusal is logged with the tunnel, the reason and the request id — never the username (`no_matching_grant` included). The access-request log (`accessLoggingEnabled`) is the one place Gatekeeper records who asked.
+
 `GET /authz/check` — what tunnel vhosts written before 4.3 call, with `X-Original-URL` and `Host` taken from the client's `Host` header — answers `403` (logged as `vhost_predates_host_binding`): such a vhost closes its tunnel until the panel rewrites it, which it does at startup. See [nginx Configuration](../03-architecture/nginx-configuration.md#authorization-subrequests-name-their-own-hostname).
 
 **Response codes:**
@@ -592,3 +617,33 @@ This is the nginx `auth_request` target. nginx calls this endpoint on every requ
 | 403    | Denied  | User is authenticated but lacks a grant; returns an HTML body with denial details |
 
 This endpoint is bound to `127.0.0.1` only. External traffic never reaches it directly -- nginx forwards the subrequest internally.
+
+### User-Surface Authorization (nginx auth_request)
+
+```
+GET /authz/user-surface/:fqdn
+```
+
+**Host:** `127.0.0.1:9294`
+
+The `auth_request` target of a plugin's user surface — `/api/<route>/app` and everything under it on the host of a tunnel bound to the plugin ([Tunnels API](tunnels.md#user-surface-binding)). The vhost names its tunnel in the path, `X-Original-URL` and `Host`, as for `/authz/tunnel/:fqdn`, and sends `X-Original-Method`. Gatekeeper checks, in order: the hostnames agree; the tunnel is known, enabled, not public and has a user surface; the raw request target — what follows `https://<fqdn>` in `X-Original-URL`, never re-encoded by a URL parser — lies on the user surface of a route bound to the tunnel, with no `.` or `..` segment, backslash, percent-encoded `.`, `/`, `\` or `%` (`%25`), or escape that does not decode; the tunnel's agent hosts the plugin — it carries the plugin's internal tunnel, the one `tunnels.json` records for the route (core `tunnelServedUserSurfaceRoutes`; refused `not_hosting_agent` otherwise: the tunnel moved or its agent revoked, the plugin hosted elsewhere or not at all); the Authelia session, read as for `/authz/tunnel/:fqdn` (one `authelia_session` only); on a `restricted` tunnel, the user's grant for the tunnel. Then it signs a **relay assertion for the panel**: Ed25519 with the relay signing key, audience `@panel`, port 3100, caller `{ type: "user", username }` — the username alone; the panel takes everything else about the user from its directory — bound to the method and the raw target (`{ route, path }`).
+
+| Status | Meaning                                                                                                                                                                                                                   |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 200    | `X-Lamalibre-Relay-Assertion` for this one request; `Cache-Control: no-store`; no `Remote-*` headers                                                                                                                      |
+| 401    | No valid session (or more than one session cookie) — nginx answers with `GET /authz/user-surface-unauthenticated`: a JSON `401 { "error": "unauthenticated" }`, never a redirect (the caller is an application's request) |
+| 403    | Anything else refused, with an empty body — never the access-request page; the reason is logged (`user-surface authz denied`)                                                                                             |
+| 503    | The relay signing key is unusable                                                                                                                                                                                         |
+
+### Principals (Gatekeeper's own API)
+
+```
+POST /api/principals/user/remove
+{ "username": "alice" }
+```
+
+**Host:** `127.0.0.1:9294`, with the panel's secret. Not proxied.
+
+Removes a user principal everywhere — every grant naming the username, of any resource type, and its membership of every group — in one transaction, holding the groups lock and then the grants lock. Idempotent. `{ "ok": true, "grantsRemoved": 2, "groupsLeft": 1 }`; `400` for a body that is not `{ username }` (1–100 characters), never echoing it. The username travels in the body, never in a URL that request logs keep (the `DELETE /api/principals/user/:username` of earlier 4.5 builds is gone). The panel calls it when a user is removed, retries it every minute while it is pending, and calls it before it creates a user under a username a removed user held — always then — and before it gives a grant or a membership to a username whose cleanup is pending ([Usernames and Gatekeeper](users.md#usernames-and-gatekeeper)).
+
+**Request logging.** Gatekeeper logs one metadata line per request — method, route pattern (`/authz/tunnel/:fqdn`, never the URL), status, duration — and no client address; Fastify's own request lines are off.

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

@@ -60,18 +60,19 @@ Only a plugin with `"hosting": "agent"` and an `agent` block may declare hooks.
 
 ### Route patterns
 
-`"<METHOD> <path>"` or `"<path>"` (any method). The method is `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS` or `*`; `GET` also matches `HEAD`. The path starts with `/admin` (the forwarded admin API) or `/app` (the user surface — accepted, not active until the plugin gateway exists). A segment is a literal or `*`: one segment, except as the last, where it matches one or more.
+`"<METHOD> <path>"` or `"<path>"` (any method). The method is `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS` or `*`; `GET` also matches `HEAD`. The path starts with `/admin` (the forwarded admin API) or `/app` (the user surface — requests of the plugin's users, which only a plugin that declares `identity` receives; listed as `userSurfaceRoutes` in the preview). A segment is a literal or `*`: one segment, except as the last, where it matches one or more.
 
 Matching errs towards running the hook: literal segments match case-insensitively, segments are compared percent-decoded (`/admin/%69mport` is `/admin/import`), and empty segments are ignored. The forwarder refuses a path with an encoded `/` or `\`.
 
 ## Approval
 
-Relay hooks are code Lamaste runs on the relay, and an [agent half Lamaste installs](app-host.md) is code it has an agent's root helper install, so an administrator approves both first. What is approved is one **digest**: SHA-256 over the canonical JSON of the normalised relay declarations (defaults applied, shared-hook settings included) with the SHA-256 of the entry module, and of the agent half pinned for the version — its package, version, tarball integrity, service (`entry`, `memoryMax`) and system packages (`{ v: 2, relay, agentHalf }`, either part `null` when the version brings none). A version whose declarations, module or agent half differ by one byte has another digest. The runner records the relay part's own digest, so a new agent half with an unchanged relay module leaves the runner current.
+Relay hooks are code Lamaste runs on the relay, and an [agent half Lamaste installs](app-host.md) is code it has an agent's root helper install, so an administrator approves both first. What is approved is one **digest**: SHA-256 over the canonical JSON of the normalised relay declarations (defaults applied, shared-hook settings included) with the SHA-256 of the entry module, and of the agent half pinned for the version — its package, version, tarball integrity, service (`entry`, `memoryMax`) and system packages (`{ v: 2, relay, agentHalf }`, either part `null` when the version brings none) — and, only when the plugin declares one, its normalized [identity block](agent-hosted-plugins.md#the-identity-block) (`identity`: the roles its users hold and the attributes it receives about them), so a plugin without one keeps the digest it had before 4.5. A version whose declarations, module, agent half or identity block differ by one byte has another digest. The runner records the relay part's own digest, so a new agent half with an unchanged relay module leaves the runner current.
 
-- 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.
+- Installing a plugin with relay hooks, an agent half Lamaste installs or an identity block leaves them **pending**: the plugin can be enabled, but not hosted, its forwarded API answers `503 { code: "hooks_not_approved" }`, and its users are neither sent to its agent half nor served on its user surface 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)).
 - 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.
+- A version that **adds or removes a role or widens the attributes** of its identity block waits for an administrator too (`identity.changed`) — a new role is a new power over the plugin's users, a new attribute more about them — and auto-approve never covers it. Narrowing the attributes and editing labels only change the digest.
 - 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.
@@ -98,7 +99,7 @@ Every approval, auto-approve change and auto-approval is recorded in the [audit
           "use": null,
           "settings": null,
           "failOpen": [],
-          "inactiveRoutes": []
+          "userSurfaceRoutes": []
         }
       ],
       "effects": ["audit", "notify-admins"],
@@ -117,6 +118,7 @@ Every approval, auto-approve change and auto-approval is recorded in the [audit
       "unitName": "lamalibre-app-fx.service",
       "dataDir": "/var/lib/lamalibre/apps/fx"
     },
+    "identity": { "declared": false, "approved": false, "block": null },
     "approval": {
       "required": true,
       "state": "pending",
@@ -133,7 +135,7 @@ 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, 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):
+`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, `agentHalf` — the agent half Lamaste installs, `null` when there is none or it is installed by hand ([App Host](app-host.md)) — and the identity block (`identity.block`, normalized; `identity.approved` once the installed version is). `pendingUpdate` is `{ version, digest, stagedAt, relay, agentHalf, settings, identity, approvalRequired, autoApproveWithheld }` while an update waits — `digest` is the one to approve it with (`null` when it brings no relay hooks, no agent half and no identity block: it is approved by its version), `identity` how it changes the identity block (`{ before, after, rolesAdded, rolesRemoved, attributesAdded, attributesRemoved, labelsChanged }`, `null` when neither version declares one), `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": [
@@ -145,7 +147,7 @@ Every approval, auto-approve change and auto-approval is recorded in the [audit
 ]
 ```
 
-`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.
+`digest.unapproved`: what it brings — relay hooks, an agent half Lamaste installs, an identity block — 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. `identity.changed`: it adds or removes roles, or receives more about its users (`it adds roles (editor) and receives more about its users (email)`) — always an administrator's call.
 
 ### `POST /api/plugins/:name/hooks/approve`
 
@@ -163,10 +165,10 @@ Approving a pending update approves everything it waits for (`approvalRequired`)
 
 ### `POST /api/plugins/:name/update`
 
-`{ "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:
+`{ "version"?: "1.2.3" | "latest" }` (default `latest`). For agent-hosted plugins. The panel fetches the version with `npm pack` (from the registry its [registry credential](registry-and-oidc.md) names, authenticated as the panel, when one is configured) 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, 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 { pendingUpdate }` — what it brings (relay hook set, agent half, identity block) differs from what was approved and auto-approve is off or withheld, or it turns a secret setting into a plain one or adds or removes a role or widens the attributes (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.
@@ -236,7 +238,7 @@ What a request hook sees: method, path (on the agent half), query, the caller (`
 
 ### Tunnel state
 
-When the [health monitor](agent-hosted-plugins.md#health) sees a hosting go `down` (reason `tunnel` or `app`), Lamaste runs the relay's `tunnel:down`; its `fallback` (`{ status, retryAfter?, contentType?, body? }`) answers forwarded requests that fail while the plugin is down. `tunnel:up` runs when it is back after a `down` (not on the first `up`), and clears the fallback.
+When the [health monitor](agent-hosted-plugins.md#health) sees a hosting go `down` (reason `tunnel` or `app`), Lamaste runs the relay's `tunnel:down`; its `fallback` (`{ status, retryAfter?, contentType?, body? }`) answers the plugin's admin API while the plugin is down — no request is forwarded to the port then (without a fallback: `502` with the reason). `tunnel:up` runs when it is back after a `down` (not on the first `up`), and clears the fallback.
 
 The agent cannot see its own chisel session; `agent-config` carries the relay's view (`appPlugins[].health`), and the agent's sync calls the agent half's `tunnel:down` / `tunnel:up` once per change. The panel unreachable for 90 s counts as `tunnel` down on the agent.
 
@@ -250,13 +252,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.4.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.5.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.4.0/hooks';
+import { defineRelayHooks } from '@lamalibre/lamaste@4.5.0/hooks';
 
 export default defineRelayHooks({
   'install:pre-tunnel': async (input) =>
@@ -285,10 +287,10 @@ Every decision may carry `effects` (at most 10): `{ type: 'audit', event, data?
 
 ### 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.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):
+The agent half answers `POST /admin/hooks/<stage>` (body `{ stage, input }`, answer `{ ok: true, output? }` or `{ ok: false, reason }`). `createAgentHookHandler` from `@lamalibre/lamaste@4.5.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.4.0/agent';
+import { createAgentHookHandler, createCallerAssertionVerifier } from '@lamalibre/lamaste@4.5.0/agent';
 
 const hooks = createAgentHookHandler({
   verifier: createCallerAssertionVerifier({ configPath, plugin: 'fx' }),

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.4.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.5.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.
 

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

@@ -6,6 +6,8 @@ Two generic mechanisms a plugin can build on, first used by Feria (the Lamalibre
 
 Agents install plugins with `npm install` from the Lamalibre registry. A networked registry accepts nothing anonymously, and an agent must never hold a long-lived registry credential. So the panel holds one credential for the registry and, each time an agent is about to install a plugin, asks the registry for a one-hour read-only token owned by that agent. The agent writes it to a throw-away npm configuration file for that one install and deletes it afterwards.
 
+The panel's own npm calls use the same credential: installing a plugin, fetching a version to stage an update, and reading an agent package's integrity to pin it all run with npm routed to the credential's registry for its scope and authenticated with the panel's service token — through a throw-away userconfig of the same kind (0600 in a private temporary directory, named to npm as `npm_config_userconfig`, removed once npm has run), never the service account's `~/.npmrc`. A registry that answers `401` has the token obtained again once; a token still refused, or `403`, fails the operation naming the registry and the status. Without a credential the panel's npm runs as the machine configures it (the public registry by default).
+
 The panel itself can authenticate to the registry in two ways: with a long-lived token an administrator pasted in, or — the recommended way — as its own **service principal**: an OpenID Connect client on the relay's Authelia named `lamaste-server`. In that mode nothing long-lived is pasted anywhere; the panel proves its identity to Authelia with a secret it generated itself, Authelia issues a short-lived JWT, and the registry exchanges that JWT for a registry token.
 
 Plugins use the same Authelia to let people and programs log in. A plugin's manifest declares its OIDC clients — a CLI that logs in with the device-code flow, a service that authenticates with client credentials — and the panel writes them into Authelia's configuration when the plugin is enabled.
@@ -156,17 +158,17 @@ Admin only. What is configured — never a token.
 
 ### `PUT /api/registry-credential`
 
-Admin only, 10 per minute. Verifies the whole chain against the registry, then stores the credential at `/etc/lamalibre/lamaste/registry-credential.json` (0600).
+Admin only, 10 per minute. Verifies the whole chain against the registry, then stores the credential at `/etc/lamalibre/lamaste/registry-credential.json` (0600). From then on the panel's own installs, update staging and agent-half pinning authenticate to `registryUrl` for `scope` with the service token (see In Plain English); a package published only there installs from the panel.
 
 ```json
 { "registryUrl": "https://feria.example.com", "auth": { "kind": "oidc" } }
 { "registryUrl": "https://feria.example.com", "auth": { "kind": "token", "token": "feria_…" }, "scope": "@lamalibre" }
 ```
 
-- `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, 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.
+- `auth.kind: "token"` — a long-lived Feria token. The registry's `/-/whoami` must report the `read` scope (the panel's own installs, update staging and agent-half pinning) and 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 `read` and `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 scopes `read` and `admin` 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).
+Response: as `GET`. Errors: `400` (the `read` or `admin` scope is missing; the message names which), `502` (registry or Authelia refused or unreachable), `503` (no domain yet).
 
 The Authelia call goes to `127.0.0.1:9091` with `X-Forwarded-Proto: https` and `X-Forwarded-Host: auth.<domain>`, which is how Authelia derives the issuer — the JWT says `iss: https://auth.<domain>`, exactly as it would through nginx. In the JWT, Authelia sets both `sub` and `client_id` to the client id for the client-credentials flow (there is no end user).
 

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

@@ -53,20 +53,22 @@ 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)                                                                                                                                                               |
-| `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                                                                                                                                                                                                                                      |
+| 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`)                                                                                                                                                                                                       |
+| `userSurface`       | `object`         | `{ routes: string[] }` — the agent-hosted plugins whose user surface this host serves ([User Surface Binding](#user-surface-binding)). Absent when none                                                                                                 |
+| `userSurfaceStatus` | `object[]`       | With `userSurface`: how each bound route is served — `{ route, served, reason }`, `reason` `null` when served, else `not_installed`, `no_identity` or `not_approved`                                                                                    |
+| `createdAt`         | `string`         | ISO 8601 timestamp                                                                                                                                                                                                                                      |
 
 ---
 
@@ -205,8 +207,8 @@ Return 201 with tunnel object
 Changes any of: carrying agent, access mode, request body limit, enabled state. All of them are applied in one workflow under the tunnel lock, in that order — ownership first, so a later failure still leaves the tunnel with the agent the caller asked for; access mode and body limit next; the enabled state last, so a tunnel being disabled is never re-enabled by the vhost rewrite before it. Authorization is checked against the tunnel as it is when the lock is taken.
 
 - **`enabled`** — when disabled, the tunnel's nginx vhost symlink is removed (the config file is kept) and the owner's Chisel grant for the port is withdrawn (Chisel restarts, which ends sessions still holding it). Re-enabling restores both. Only enabled tunnels appear in an agent's config, and the owner's sync timer drops or adds the remote within about 30 seconds.
-- **`agentLabel`** (admin only) — moves the tunnel to another active agent. The previous owner loses the port grant in the same Chisel sync that gives it to the new owner. Both agents' sync timers apply the move within about 30 seconds; `lamaste-agent update` applies it at once. Agent panel tunnels (`type: 'panel'`) belong to the agent they expose and cannot be moved.
-- **`accessMode`** and **`maxBodySizeMb`** — both live in the tunnel's nginx vhost, which is re-rendered and tested (nginx keeps the previous vhost if the test fails). Gatekeeper watches the tunnel state and picks up an access-mode change on its own. A disabled tunnel stays disabled. `public` and `authenticated` are admin-only, as on creation. Agent panel tunnels have a fixed mTLS vhost and cannot be reconfigured.
+- **`agentLabel`** (admin only) — moves the tunnel to another active agent. The previous owner loses the port grant in the same Chisel sync that gives it to the new owner. Both agents' sync timers apply the move within about 30 seconds; `lamaste-agent update` applies it at once. Agent panel tunnels (`type: 'panel'`) belong to the agent they expose and cannot be moved. A tunnel bound as a plugin's [user surface](#user-surface-binding) keeps its binding, but serves a route only while the new agent hosts the plugin: when that changes what it serves, its vhost is re-rendered first (and restored if the state cannot be saved).
+- **`accessMode`** and **`maxBodySizeMb`** — both live in the tunnel's nginx vhost, which is re-rendered and tested (nginx keeps the previous vhost if the test fails). Gatekeeper watches the tunnel state and picks up an access-mode change on its own. A disabled tunnel stays disabled. `public` and `authenticated` are admin-only, as on creation. A tunnel bound as a plugin's [user surface](#user-surface-binding) cannot be made public (`409`), and its re-rendered vhost keeps the user-surface locations it serves. Agent panel tunnels have a fixed mTLS vhost and cannot be reconfigured.
 
 **Request:**
 
@@ -252,7 +254,7 @@ curl -s --cert client.p12:password \
 
 ### `DELETE /api/tunnels/:id`
 
-Deletes a tunnel by its UUID: removes the nginx vhost, removes the tunnel from the state file, and syncs Chisel so the owner's grant for the port is withdrawn.
+Deletes a tunnel by its UUID: removes the nginx vhost, removes the tunnel from the state file, and syncs Chisel so the owner's grant for the port is withdrawn. Its [user-surface bindings](#user-surface-binding) go with it.
 
 The TLS certificate is not deleted (it is harmless to keep and may be reused if the subdomain is recreated).
 
@@ -316,7 +318,7 @@ curl -s --cert client.p12:password \
 | `chiselArgs`               | `string[]`       | Chisel client arguments: `client`, the server URL, and one `R:127.0.0.1:<port>:127.0.0.1:<port>` remote per tunnel. No `--tls-skip-verify` (the agent verifies the relay's certificate) and no credential — the agent supplies its own through the service environment, never argv                                                                                                                                                                                                                                                                             |
 | `chiselCredentialIssuedAt` | `string \| null` | When the agent's current Chisel credential was issued — a timestamp, never the credential. An agent holding a credential with a different issue time (an administrator rotated it) fetches the current one from `GET /api/agents/me/chisel-credential`                                                                                                                                                                                                                                                                                                         |
 | `tunnels`                  | `array`          | The agent's enabled tunnels with port and subdomain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `hostFactsHash`            | `string \| null` | Agent certificates only: the SHA-256 of the [host facts](agent-hosted-plugins.md#host-facts) the relay stores for the agent, computed as the agent computes it over its own (`hostFactsHash` in `@lamalibre/lamaste@4.4.0`); `null` when it stores none. The agent's sync reports its facts again when this is not the hash of its own, so a record replaced since its last report — the agent enrolled again on its label, the relay restored from a backup — has them again after one sync, not a day. An agent behind a relay without the field reports as before |
+| `hostFactsHash`            | `string \| null` | Agent certificates only: the SHA-256 of the [host facts](agent-hosted-plugins.md#host-facts) the relay stores for the agent, computed as the agent computes it over its own (`hostFactsHash` in `@lamalibre/lamaste@4.5.0`); `null` when it stores none. The agent's sync reports its facts again when this is not the hash of its own, so a record replaced since its last report — the agent enrolled again on its label, the relay restored from a backup — has them again after one sync, not a day. An agent behind a relay without the field reports as before |
 
 **Errors:**
 
@@ -325,6 +327,40 @@ curl -s --cert client.p12:password \
 | 400    | `{"error":"Domain not configured"}`           | Domain has not been set  |
 | 500    | `{"error":"Failed to generate agent config"}` | Config generation failed |
 
+## User Surface Binding
+
+An app tunnel can be **bound** as the user surface of an agent-hosted plugin: its host then serves the plugin's users at `/api/<route>/app` and everything under it — Gatekeeper authenticates the Authelia session and vouches for the user to the panel, and the panel forwards the request to the plugin's agent half with the directory's `userId`, username and the user's roles ([Agent-Hosted Plugins](agent-hosted-plugins.md#the-user-surface)). Every other path of the host goes down the tunnel as before. Admin only, 30 a minute.
+
+**What can be bound.** An enabled app tunnel (`type` `app`, not internal), with access mode `authenticated` or `restricted` — a public host has no signed-in user to vouch for — **carried by the agent that hosts the plugin** (`400` otherwise: "Plugin '…' is hosted on agent '…', but this tunnel is carried by '…'", or "… is not hosted on an agent" before it is hosted). The host whose sessions reach the plugin's users is never another agent's: whatever answers on its other paths — another agent's application — would share the user surface's origin. On a `restricted` tunnel the user also needs a grant for the tunnel. The route must be held by an installed agent-hosted plugin; a plugin's user surface is on one host at most, and one host serves at most 16 plugins' user surfaces. A bound tunnel cannot be made public (`PATCH` answers `409` "… cannot be made public — unbind it first").
+
+**When it is served.** A plugin may be bound before it declares `identity`: its host serves the route — locations that ask Gatekeeper and pass the request to the panel ([nginx Configuration](../03-architecture/nginx-configuration.md#user-surface-locations)) — only while the plugin's installed, approved version declares it **and the tunnel's agent is the plugin's hosting agent**. Until then its requests go down the tunnel as before, so a plugin moves its users' API to the relay with a plain update: bind first, then update and approve. A binding stays when the tunnel moves to another agent, its agent is revoked, or the plugin is unhosted or hosted elsewhere — but the host serves none of it then (`userSurfaceStatus` reason `not_hosting_agent`): its vhost loses the locations, Gatekeeper refuses to vouch for the route, and the panel refuses a request for it even with an assertion. The vhosts of the bound tunnels are re-rendered whenever that can change — the plugin's approval, update or its revert, hosting and unhosting, a move of the tunnel, its agent's revocation — and at the panel's start. Uninstalling the plugin releases its binding everywhere — and any binding left for a route no installed plugin holds, should a bind have raced the uninstall (a bind that finds its plugin gone once the binding is written undoes it and answers `409`); deleting a tunnel releases its bindings. Every change is audited: `tunnel.user-surface.bound`, `tunnel.user-surface.unbound` (with `reason`: `unbound`, `tunnel-deleted`, `plugin-uninstalled`).
+
+`userSurfaceStatus` lists each bound route as `{ route, served, reason }`; `reason` is `not_installed`, `no_identity`, `not_approved` or `not_hosting_agent`, and null when served.
+
+### `PUT /api/tunnels/:id/user-surface`
+
+```json
+{ "route": "market-indicators" }
+```
+
+Binds the plugin route to the tunnel's host. Idempotent. **Response (200):** `{ "ok": true, "changed": true, "tunnel": { ... } }` — the tunnel with its `userSurface` and `userSurfaceStatus`; `changed: false` when the route was bound there already.
+
+### `DELETE /api/tunnels/:id/user-surface/:route`
+
+Unbinds it: requests for the route go down the tunnel again. **Response (200):** `{ "ok": true, "tunnel": { ... } }`.
+
+**Errors** (both):
+
+| Status | Body                                                                                                       | When                                                                                                                                                                                                                                   |
+| ------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 400    | `{"error":"…"}`                                                                                            | Not an app tunnel's host, disabled, unassigned, public; no installed agent-hosted plugin holds the route; the plugin not hosted, or hosted by another agent than the tunnel's; 16 routes bound already; domain or email not configured |
+| 404    | `{"error":"Tunnel not found"}` / `{"error":"This tunnel does not serve the user surface of '…'"}`          | No such tunnel; unbinding a route that is not bound there                                                                                                                                                                              |
+| 409    | `{"error":"The user surface of '…' is already served on …","code":"user_surface_conflict"}`                | The route is bound to another tunnel                                                                                                                                                                                                   |
+| 409    | `{"error":"The plugin holding the route '…' was uninstalled while it was being bound — nothing is bound"}` | The plugin was uninstalled while the binding was written (released again)                                                                                                                                                              |
+| 500    | `{"error":"Failed to bind the user surface","details":"…"}`                                                | nginx or state operation failed (the previous vhost is restored)                                                                                                                                                                       |
+
+From the CLI: `lamaste-server tunnels bind-user-surface <tunnel> <plugin>` and `tunnels unbind-user-surface <tunnel> <plugin>` (the tunnel by id, subdomain or FQDN; the plugin by name or route). In the panel: the Tunnels page's **User surface** action on an eligible tunnel, which shows each bound route's status; the desktop app through `AdminClient` `bindTunnelUserSurface(id, route)` and `unbindTunnelUserSurface(id, route)`.
+
 ## Chisel Grants
 
 The Chisel server authenticates every client against `/etc/lamalibre/lamaste/chisel-users`. That file is rendered by the panel from two persisted inputs — the per-agent credential store and the tunnel state — and re-rendered whenever either changes:
@@ -355,7 +391,7 @@ Tunnels on a reserved port, or two tunnels on the same port, are granted to no a
 
 ### When an agent certificate is revoked
 
-Revoking an agent's certificate releases its tunnels: its app and plugin tunnels become unassigned (their hostnames stay reserved and dark until an administrator assigns them), and its `agent-<label>` panel tunnel is removed with its vhost. A later enrollment that reuses the label therefore inherits nothing.
+Revoking an agent's certificate releases its tunnels: its app and plugin tunnels become unassigned (their hostnames stay reserved and dark until an administrator assigns them), and its `agent-<label>` panel tunnel is removed with its vhost. A later enrollment that reuses the label therefore inherits nothing. A released tunnel bound as a plugin's user surface keeps its binding but serves none of it, and its vhost is re-rendered without those locations.
 
 ## Validation Rules
 
@@ -386,16 +422,18 @@ A tunnel's vhost proxies to `127.0.0.1:<port>` on the relay, so a tunnel on one
 
 ## Quick Reference
 
-| Method | Path                              | Description                                                                                                         |
-| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| GET    | `/api/tunnels`                    | List tunnels (an agent sees only its own)                                                                           |
-| POST   | `/api/tunnels`                    | Create a tunnel carried by an agent                                                                                 |
-| PATCH  | `/api/tunnels/:id`                | Move (admin), access mode, body limit, enable/disable                                                               |
-| DELETE | `/api/tunnels/:id`                | Delete a tunnel by UUID                                                                                             |
-| GET    | `/api/tunnels/agent-config`       | One agent's Chisel client config (macOS & Linux)                                                                    |
-| GET    | `/api/tunnels/agent-panel-status` | Check if agent has an exposed panel tunnel                                                                          |
-| POST   | `/api/tunnels/expose-panel`       | Create mTLS panel tunnel for requesting agent (refused when a static site or alias serves `agent-<label>.<domain>`) |
-| DELETE | `/api/tunnels/retract-panel`      | Remove the panel tunnel for requesting agent                                                                        |
+| Method | Path                                   | Description                                                                                                         |
+| ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/api/tunnels`                         | List tunnels (an agent sees only its own)                                                                           |
+| POST   | `/api/tunnels`                         | Create a tunnel carried by an agent                                                                                 |
+| PATCH  | `/api/tunnels/:id`                     | Move (admin), access mode, body limit, enable/disable                                                               |
+| DELETE | `/api/tunnels/:id`                     | Delete a tunnel by UUID                                                                                             |
+| PUT    | `/api/tunnels/:id/user-surface`        | Bind a plugin route as the tunnel host's user surface (admin)                                                       |
+| DELETE | `/api/tunnels/:id/user-surface/:route` | Unbind it (admin)                                                                                                   |
+| GET    | `/api/tunnels/agent-config`            | One agent's Chisel client config (macOS & Linux)                                                                    |
+| GET    | `/api/tunnels/agent-panel-status`      | Check if agent has an exposed panel tunnel                                                                          |
+| POST   | `/api/tunnels/expose-panel`            | Create mTLS panel tunnel for requesting agent (refused when a static site or alias serves `agent-<label>.<domain>`) |
+| DELETE | `/api/tunnels/retract-panel`           | Remove the panel tunnel for requesting agent                                                                        |
 
 ### curl Cheat Sheet