@lamalibre/create-lamaste 4.2.0 → 4.3.0

package/vendor/docs/06-reference/troubleshooting.md

@@ -217,7 +217,7 @@ The agent's sync timer applies tunnel changes within about 30 seconds. If that d
 lamaste-agent update     # apply now and (re)install the sync timer
 ```
 
-`update` needs the agent installed globally (`npm install -g @lamalibre/lamaste-agent@4.2.0`); an agent originally set up with `npx` must be installed first.
+`update` needs the agent installed globally (`npm install -g @lamalibre/lamaste-agent@4.3.0`); an agent originally set up with `npx` must be installed first.
 
 **Cause 3: The agent does not carry the tunnel.**
 
@@ -320,7 +320,7 @@ ls -la /usr/local/bin/authelia
 | Missing `panel.json`            | `Config file not found`                 | Re-run installer or create the file manually                                                                                   |
 | Invalid JSON in `panel.json`    | `contains invalid JSON`                 | Fix the JSON syntax                                                                                                            |
 | Port 3100 in use                | `EADDRINUSE`                            | Find and stop the conflicting process: `sudo ss -tlnp sport = :3100`                                                           |
-| Missing Node.js modules         | `Cannot find module`                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.2.0 --yes`); `/opt/lamalibre/lamaste` is root-owned and redeployed as a whole |
+| Missing Node.js modules         | `Cannot find module`                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.3.0 --yes`); `/opt/lamalibre/lamaste` is root-owned and redeployed as a whole |
 | Permission denied writing state | `EACCES` under `/etc/lamalibre/lamaste` | Re-run the installer; the redeploy re-applies the ownership of the config and PKI directories                                  |
 
 ### chisel fails to start
@@ -329,7 +329,7 @@ ls -la /usr/local/bin/authelia
 
 | Cause                      | Log Message                                                                           | Fix                                                                                                                                                                                                                               |
 | -------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Binary missing             | `exec format error` or `not found`                                                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.2.0 --yes`) — it installs the pinned, checksum-verified release for the server's architecture; the panel cannot install binaries                                                 |
+| Binary missing             | `exec format error` or `not found`                                                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.3.0 --yes`) — it installs the pinned, checksum-verified release for the server's architecture; the panel cannot install binaries                                                 |
 | Not the pinned release     | (panel log) `The installed chisel is not the pinned release — run create-lamaste ...` | Re-run the installer. Until then the panel restarts Chisel on every authfile change                                                                                                                                               |
 | Authfile or key unreadable | `permission denied` on `chisel-users` or `chisel-server.key`                          | Both must be `0640 lamaste:lamaste-chisel` and the unit `Group=lamaste-chisel`; restart the panel, which re-applies the authfile's. If the group, the unit or the key's ownership is wrong, re-run the installer in redeploy mode |
 | Stopped by the panel       | (panel log) `Chisel stopped: ...`; unit disabled, `chisel-failed-closed` present      | Reconciliation failed closed; see [Tunnel Client Cannot Connect](#tunnel-client-cannot-connect), Cause 1                                                                                                                          |
@@ -343,7 +343,7 @@ ls -la /usr/local/bin/authelia
 | --------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Invalid `configuration.yml` | `configuration: error`                  | Check YAML syntax with `authelia validate-configuration --config /etc/authelia/configuration.yml`                                                                                                                                                                                                                                                         |
 | Missing `users.yml`         | `cannot open file`                      | Create an initial users file (see [Config Files](config-files.md))                                                                                                                                                                                                                                                                                        |
-| Binary missing              | `not found`                             | Re-run the installer (`npx @lamalibre/create-lamaste@4.2.0 --yes`); it installs the pinned release                                                                                                                                                                                                                                                              |
+| Binary missing              | `not found`                             | Re-run the installer (`npx @lamalibre/create-lamaste@4.3.0 --yes`); it installs the pinned release                                                                                                                                                                                                                                                              |
 | Wrong permissions           | `permission denied`                     | Authelia runs as `lamaste-authelia`: `/etc/authelia` must be `lamaste:lamaste-authelia 2770`, `configuration.yml` `0640`, `users.yml` `0660`, `db.sqlite3` owned by `lamaste-authelia`. Re-run the installer to re-apply (a root-owned `/etc/authelia` from an older version is converted), or see [Config Files](config-files.md#file-permissions-table) |
 | Database newer than binary  | storage schema version error at startup | A newer Authelia ran against this database and was replaced by an older one; the installer never downgrades an installed Authelia, so reinstall that newer release by hand                                                                                                                                                                                |
 
@@ -516,14 +516,14 @@ sudo systemctl restart authelia
 
 ## Onboarding Fails: "Chisel is not installed" / "Authelia is not installed"
 
-**Symptom:** The **Starting Chisel** or **Configuring Authelia** provisioning task fails with "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.2.0` on the server to repair the installation." (or the same for Authelia).
+**Symptom:** The **Starting Chisel** or **Configuring Authelia** provisioning task fails with "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.3.0` on the server to repair the installation." (or the same for Authelia).
 
 **Cause:** Onboarding downloads nothing: the installer installs both binaries (pinned releases), their systemd units and the `lamaste-authelia` account. The binary at `/usr/local/bin/chisel` or `/usr/local/bin/authelia` is missing — the installer was interrupted, or the file was removed.
 
 **Fix:** Re-run the installer on the server, then start provisioning again from the wizard:
 
 ```bash
-npx @lamalibre/create-lamaste@4.2.0 --yes
+npx @lamalibre/create-lamaste@4.3.0 --yes
 ```
 
 If provisioning then fails writing Authelia's configuration with `/etc/authelia is not writable by the panel — run create-lamaste to repair the installation`, the directory's ownership is wrong; the same command repairs it.
@@ -538,7 +538,7 @@ If provisioning then fails writing Authelia's configuration with `/etc/authelia
 
 **Fix:**
 
-1. Re-run the installer so the helper matches the panel: `npx @lamalibre/create-lamaste@4.2.0 --yes`
+1. Re-run the installer so the helper matches the panel: `npx @lamalibre/create-lamaste@4.3.0 --yes`
 2. If it persists on a current install, it is a bug: the vhost generators (`packages/server/daemon/src/lib/nginx.js`) and the allow-list (`packages/provisioners/server/scripts/lamaste-priv`) must change together — `npm test` checks every generated vhost against the allow-list. Do not work around it by editing files in `/etc/nginx` by hand.
 
 `sudo: a password is required` for `lamaste-priv` means the helper or the sudoers file is missing or outdated: re-run the installer.
@@ -621,7 +621,7 @@ df -h /
 
 **Cause 3: The web root is not writable by the panel (`EACCES`).**
 
-The panel writes `/var/www/lamaste` itself: it must be `lamaste:www-data`, directories `2750`, files `0640`. An install from before this layout had it owned by `www-data`. Re-run the installer (`npx @lamalibre/create-lamaste@4.2.0 --yes`); the redeploy converts the tree.
+The panel writes `/var/www/lamaste` itself: it must be `lamaste:www-data`, directories `2750`, files `0640`. An install from before this layout had it owned by `www-data`. Re-run the installer (`npx @lamalibre/create-lamaste@4.3.0 --yes`); the redeploy converts the tree.
 
 ---
 
@@ -642,6 +642,31 @@ curl -s --cert client.p12:password \
 
 ---
 
+## Agent Panel or Plugin Tunnel Answers 401 Through the Relay
+
+**Symptom:** `https://agent-<label>.<domain>/` (with a valid certificate) or a plugin tunnel (after the Authelia login) answers `401 {"error":"Unauthorized"}`, while the agent's own desktop app works.
+
+**Cause:** From 4.3, lamaste-agentd accepts a request from the relay only with a relay assertion it can verify (see [Security Model](../01-concepts/security-model.md#5c-the-agent-daemon-lamaste-agentd-and-relay-assertions)). The daemon's log (`~/.lamalibre/lamaste/agents/<label>/logs/panel.log`) names the reason:
+
+- `Failed to fetch relay verification keys` — the daemon cannot reach `GET /api/agents/me/relay-keys` on the panel: the relay is older than 4.3 (upgrade the relay — it is the side that must be upgraded first), or the panel is unreachable from the agent.
+- `Relay assertion refused` with `reason: "future"` or `"expired"` — the agent's clock differs from the relay's by more than a few seconds. Assertions are valid for 60 seconds with 5 seconds of skew; enable NTP on both.
+- `reason: "unknown_key"` — the relay's key was replaced less than 30 seconds ago; the daemon fetches the new one on the next request after that.
+- Nothing logged but the `401` itself — no assertion arrived: the vhost predates 4.3 and the panel's startup reconcile could not rewrite it (the panel log at startup names it: `Failed to rewrite tunnel vhost`). On the server, `grep -c 'auth_request /internal/lamaste/agent-panel-authz;' /etc/nginx/sites-available/lamalibre-lamaste-agent-panel-agent-<label>` must print `1`.
+
+A request sent straight to the daemon's port with `X-SSL-Client-*` or `Remote-User` headers is refused by design: those headers prove nothing.
+
+---
+
+## A Tunnel Answers 403 for Everyone After the Upgrade to 4.3
+
+**Symptom:** an `authenticated` or `restricted` tunnel answers `403` to every user — grantees included — and a restricted tunnel shows "This tunnel is unavailable until the relay rewrites its configuration." Gatekeeper's log (`journalctl -u lamalibre-lamaste-gatekeeper`) has `authz refused` with `reason: "vhost_predates_host_binding"`.
+
+**Cause:** the tunnel's vhost was written before 4.3 and still asks Gatekeeper's `/authz/check` with the client's `Host` header, which let a user allowed on one tunnel into another (see [nginx Configuration](../03-architecture/nginx-configuration.md#authorization-subrequests-name-their-own-hostname)). Gatekeeper 4.3 refuses that subrequest, so such a vhost closes its tunnel. The panel rewrites tunnel vhosts when it starts; this one was not rewritten.
+
+**Fix:** the panel's startup log (`journalctl -u lamalibre-lamaste-serverd`) names the tunnel under `Left tunnel vhosts as they are` (with the reason) or `Failed to rewrite tunnel vhost` (with the `nginx -t` or certificate error). Fix that, then `sudo systemctl restart lamalibre-lamaste-serverd`. On the server, `grep -c 'authz/tunnel/<fqdn>;' /etc/nginx/sites-available/lamalibre-lamaste-app-<subdomain>` must print `1`. The same log lines name static sites (`Left site vhosts as they are`, `Failed to rewrite site vhost`): a site vhost that was not rewritten still names the client's `Host` to Authelia, so treat those first.
+
+---
+
 ## Quick Reference: Diagnostic Commands
 
 | What to Check        | Command                                                                 |

package/vendor/docs/_index.json

@@ -196,6 +196,26 @@
           "title": "Registry Credential & OIDC Clients",
           "slug": "api-registry-and-oidc",
           "file": "04-api-reference/registry-and-oidc.md"
+        },
+        {
+          "title": "Agent-Hosted Plugins",
+          "slug": "api-agent-hosted-plugins",
+          "file": "04-api-reference/agent-hosted-plugins.md"
+        },
+        {
+          "title": "App Host (Agent Halves)",
+          "slug": "api-app-host",
+          "file": "04-api-reference/app-host.md"
+        },
+        {
+          "title": "Lifecycle Hooks",
+          "slug": "api-lifecycle-hooks",
+          "file": "04-api-reference/lifecycle-hooks.md"
+        },
+        {
+          "title": "Audit Log & Notifications",
+          "slug": "api-audit-and-notifications",
+          "file": "04-api-reference/audit-and-notifications.md"
         }
       ]
     },

package/vendor/docs/gatekeeper-design.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-`@lamalibre/lamaste-gatekeeper@4.2.0` is a standalone authorization package for Lamaste. It manages **groups** and **grants**, enforces tunnel access control via a lightweight Fastify service, and serves user-friendly "request access" pages when access is denied.
+`@lamalibre/lamaste-gatekeeper@4.3.0` is a standalone authorization package for Lamaste. It manages **groups** and **grants**, enforces tunnel access control via a lightweight Fastify service, and serves user-friendly "request access" pages when access is denied.
 
-It follows the same architectural pattern as `@lamalibre/lamaste-tickets@4.2.0` — a solid library at the core, with a service, CLI, and desktop as consumers.
+It follows the same architectural pattern as `@lamalibre/lamaste-tickets@4.3.0` — a solid library at the core, with a service, CLI, and desktop as consumers.
 
 ---
 
@@ -78,7 +78,7 @@ packages/lamaste-gatekeeper/
     server/
       index.js             # Fastify service entry point (127.0.0.1:9294)
       routes/
-        authz.js           # GET /authz/check — nginx auth_request target
+        authz.js           # GET /authz/tunnel/:fqdn — nginx auth_request target
         access-request.js  # GET /access-request — denial page with message templates
         groups.js          # REST API for group management
         grants.js          # REST API for grant management
@@ -204,7 +204,7 @@ The grant system is resource-agnostic. It doesn't know what a "tunnel" or "plugi
 
 ```js
 import { createGroup, listGroups, getGroup, updateGroup, deleteGroup,
-         addMembers, removeMembers, getGroupsForUser } from '@lamalibre/lamaste-gatekeeper@4.2.0';
+         addMembers, removeMembers, getGroupsForUser } from '@lamalibre/lamaste-gatekeeper@4.3.0';
 
 createGroup(name, { description?, createdBy? })
   // → { name, description, members: [], createdAt, createdBy }
@@ -240,7 +240,7 @@ getGroupsForUser(username)
 ### Grants
 
 ```js
-import { createGrant, listGrants, getGrant, revokeGrant } from '@lamalibre/lamaste-gatekeeper@4.2.0';
+import { createGrant, listGrants, getGrant, revokeGrant } from '@lamalibre/lamaste-gatekeeper@4.3.0';
 
 createGrant({ principalType, principalId, resourceType, resourceId, context? })
   // → grant object
@@ -267,7 +267,7 @@ revokeGrant(grantId)
 ### Authorization
 
 ```js
-import { checkAccess } from '@lamalibre/lamaste-gatekeeper@4.2.0';
+import { checkAccess } from '@lamalibre/lamaste-gatekeeper@4.3.0';
 
 checkAccess(username, resourceType, resourceId);
 // 1. Find direct user grants: principalType='user', principalId=username
@@ -282,7 +282,7 @@ checkAccess(username, resourceType, resourceId);
 ### Templates
 
 ```js
-import { getAccessRequestTemplates } from '@lamalibre/lamaste-gatekeeper@4.2.0';
+import { getAccessRequestTemplates } from '@lamalibre/lamaste-gatekeeper@4.3.0';
 
 getAccessRequestTemplates(username, resourceName, { adminContact?, domain? })
   // → {
@@ -316,9 +316,9 @@ proxy_cache_path /var/cache/nginx/authz levels=1:2
 
 location /internal/lamaste/authz {
     internal;
-    proxy_pass http://127.0.0.1:9294/authz/check;
+    proxy_pass http://127.0.0.1:9294/authz/tunnel/gitlab.example.com;
     proxy_cache authz_cache;
-    proxy_cache_key "$cookie_authelia_session$http_host";
+    proxy_cache_key "$server_name|$cookie_authelia_session";  # the vhost, never the client's Host
     proxy_cache_valid 200 30s;   # cache successful auth for 30s
     proxy_cache_valid 403 10s;   # cache denial for 10s (shorter — revocations take effect faster)
     # Never cache 401 — user needs fresh login redirect
@@ -416,10 +416,13 @@ server {
     # Gatekeeper auth (handles both authentication via Authelia + authorization via grants)
     location /internal/lamaste/authz {
         internal;
-        proxy_pass http://127.0.0.1:9294/authz/check;
-        proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
+        # The tunnel in the path and the vhost's own hostname in the headers,
+        # never $http_host: an absolute-form request line selects this vhost
+        # while the client's Host names another tunnel
+        proxy_pass http://127.0.0.1:9294/authz/tunnel/gitlab.example.com;
+        proxy_set_header X-Original-URL https://gitlab.example.com$request_uri;
         proxy_set_header X-Forwarded-For $remote_addr;
-        proxy_set_header Host $http_host;
+        proxy_set_header Host gitlab.example.com;
         proxy_pass_request_body off;
         proxy_set_header Content-Length "";
         # Forward cookies so gatekeeper can validate Authelia session
@@ -434,10 +437,10 @@ server {
         auth_request_set $remote_email $upstream_http_remote_email;
 
         # Authentication failure → Authelia login
-        error_page 401 =302 https://auth.example.com/?rd=$scheme://$http_host$request_uri;
+        error_page 401 =302 https://auth.example.com/?rd=https://gitlab.example.com$request_uri;
 
         # Authorization failure → access request page
-        error_page 403 =302 https://auth.example.com/access-request?tunnel=$http_host;
+        error_page 403 =302 https://auth.example.com/access-request?tunnel=gitlab.example.com;
 
         # Set headers for backend
         proxy_set_header Remote-User $remote_user;
@@ -456,13 +459,13 @@ server {
 
 ### Authz Check Endpoint
 
-`GET /authz/check`
+`GET /authz/tunnel/:fqdn` (vhosts before 4.3 called `GET /authz/check`, which is now refused — see [nginx Configuration](03-architecture/nginx-configuration.md#authorization-subrequests-name-their-own-hostname))
 
-1. Read `Cookie` and `X-Original-URL` headers from nginx
+1. Read `Cookie` and `X-Original-URL` headers from nginx; the tunnel is the one named in the path, and `X-Original-URL` and `Host` must name it too
 2. Forward cookie to Authelia's verification endpoint (`http://127.0.0.1:9091/api/authz/forward-auth`)
 3. If Authelia returns 401 → return 401 (not authenticated)
 4. If Authelia returns 200 → extract `Remote-User`, `Remote-Groups`, `Remote-Name`, `Remote-Email` from Authelia response headers
-5. Parse hostname from `X-Original-URL` → look up tunnel
+5. Look up the tunnel named in the path
 6. Check tunnel's `accessMode`:
    - `public` → return 200 (should not reach here, but safe fallback)
    - `authenticated` → return 200 (Authelia passed = sufficient)
@@ -861,14 +864,14 @@ On first startup, gatekeeper checks for legacy files:
 
 ### Panel-Server Refactoring
 
-- `lib/user-access.js` → delegates to gatekeeper library (import from `@lamalibre/lamaste-gatekeeper@4.2.0`)
+- `lib/user-access.js` → delegates to gatekeeper library (import from `@lamalibre/lamaste-gatekeeper@4.3.0`)
 - `lib/access-control-sync.js` → removed (gatekeeper handles authorization at nginx layer, no more Authelia config rewriting for per-user access rules)
 - `routes/user-access.js` → simplified, delegates grant CRUD to gatekeeper
 - Tunnel creation/update routes → call gatekeeper for access mode changes
 
 ### Installer Updates (create-lamaste)
 
-- Install `@lamalibre/lamaste-gatekeeper@4.2.0` package
+- Install `@lamalibre/lamaste-gatekeeper@4.3.0` package
 - Create `/etc/lamalibre/lamaste/groups.json` (empty initial state)
 - Create `/etc/lamalibre/lamaste/access-grants.json` (empty or migrated)
 - Create `lamalibre-lamaste-gatekeeper.service` systemd unit

package/vendor/docs/identity-directory-design.md

@@ -1,7 +1,7 @@
 # Lamaste Identity Directory — Design Document
 
 > **Status:** design, 2026-10-13. Nothing here is implemented yet.
-> **Package:** `@lamalibre/lamaste-identity@4.2.0` (completes the existing SDK).
+> **Package:** `@lamalibre/lamaste-identity@4.3.0` (completes the existing SDK).
 > **Companions:** `gatekeeper-design.md` (authorization),
 > `plugin-development/design/agent-hosted-app-plugins.md` (app plugins).
 
@@ -28,15 +28,15 @@ copy to follow Lamaste.
 
 ## What exists today
 
-| Piece | State |
-|---|---|
-| User store | Authelia's `users.yml`, keyed by **username**. No stable id. |
-| `GET /api/identity/users`, `/users/:username`, `/groups` | Read `users.yml`; admin or agent with `identity:query`. |
-| `GET /api/identity/self` | Echoes `Remote-*` headers; only meaningful behind Authelia. |
-| SDK `IdentityClient` | `listUsers`, `getUser`, `listGroups` over mTLS. |
-| SDK `parseIdentity` + Fastify plugin | Parses `Remote-User/Name/Email/Groups` headers. |
-| Tunnel vhosts | **Blank** `Remote-User` and `Remote-Groups` before proxying — apps receive no identity. |
-| Entitlements | Two models: per-plugin grants (`user-plugin-access.json`, by username) and Gatekeeper grants (groups → resources). |
+| Piece                                                    | State                                                                                                              |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| User store                                               | Authelia's `users.yml`, keyed by **username**. No stable id.                                                       |
+| `GET /api/identity/users`, `/users/:username`, `/groups` | Read `users.yml`; admin or agent with `identity:query`.                                                            |
+| `GET /api/identity/self`                                 | Echoes `Remote-*` headers; only meaningful behind Authelia.                                                        |
+| SDK `IdentityClient`                                     | `listUsers`, `getUser`, `listGroups` over mTLS.                                                                    |
+| SDK `parseIdentity` + Fastify plugin                     | Parses `Remote-User/Name/Email/Groups` headers.                                                                    |
+| Tunnel vhosts                                            | **Blank** `Remote-User` and `Remote-Groups` before proxying — apps receive no identity.                            |
+| Entitlements                                             | Two models: per-plugin grants (`user-plugin-access.json`, by username) and Gatekeeper grants (groups → resources). |
 
 So the SDK can list users, but nothing gives an application a stable key, a
 scoped user list, a change feed, or a trustworthy identity on a request.
@@ -53,15 +53,15 @@ The directory record Lamaste owns:
 
 ```ts
 interface DirectoryUser {
-  userId: string;            // UUID, never reused
-  username: string;          // login name, unique, may change
+  userId: string; // UUID, never reused
+  username: string; // login name, unique, may change
   displayName: string;
   email: string;
-  groups: string[];          // Lamaste groups (Gatekeeper tier), not raw Authelia groups
+  groups: string[]; // Lamaste groups (Gatekeeper tier), not raw Authelia groups
   status: 'active' | 'disabled';
-  canSignIn: boolean;        // false = directory-only person (see "People who never sign in")
+  canSignIn: boolean; // false = directory-only person (see "People who never sign in")
   updatedAt: string;
-  version: number;           // per-record, increments on every change
+  version: number; // per-record, increments on every change
 }
 ```
 
@@ -75,9 +75,9 @@ An **entitlement** says a user may use a plugin, optionally with roles:
 
 ```ts
 interface Entitlement {
-  plugin: string;            // "pdks", "apsiyon", …
+  plugin: string; // "pdks", "apsiyon", …
   userId: string;
-  roles: string[];           // plugin-declared roles, e.g. ["viewer"], ["manager"]
+  roles: string[]; // plugin-declared roles, e.g. ["viewer"], ["manager"]
   source: 'direct' | `group:${string}`;
 }
 ```
@@ -111,9 +111,9 @@ only the declared attributes and the plugin's roles.
 interface AudienceMember {
   userId: string;
   username: string;
-  displayName?: string;      // only if declared
-  email?: string;            // only if declared
-  roles: string[];           // this plugin's roles only
+  displayName?: string; // only if declared
+  email?: string; // only if declared
+  roles: string[]; // this plugin's roles only
   status: 'active' | 'disabled';
   version: number;
 }
@@ -178,7 +178,7 @@ and compares it with the local projection (by `userId` and `version`). It
 applies differences and logs how many it found — a non-zero count on a
 healthy system is a bug in the change feed and is reported to the panel.
 
-## SDK (`@lamalibre/lamaste-identity@4.2.0`)
+## SDK (`@lamalibre/lamaste-identity@4.3.0`)
 
 Today's surface stays; three pieces are added.
 
@@ -187,9 +187,10 @@ Today's surface stays; three pieces are added.
 ```ts
 const subscriber = new IdentitySubscriber({
   plugin: 'pdks',
-  client,                                  // existing IdentityClient (mTLS)
-  cursorStore,                             // where the subscriber keeps { directoryId, seq }
-  apply: async (changes, tx) => {          // the plugin decides what to do with each change
+  client, // existing IdentityClient (mTLS)
+  cursorStore, // where the subscriber keeps { directoryId, seq }
+  apply: async (changes, tx) => {
+    // the plugin decides what to do with each change
     for (const c of changes) {
       if (c.kind === 'upsert') upsertPerson(tx, c.member);
       else markRemoved(tx, c.userId, c.reason);
@@ -197,8 +198,8 @@ const subscriber = new IdentitySubscriber({
   },
   reconcileEvery: '24h',
 });
-await subscriber.start();                  // initial snapshot or catch-up, then waits for notify()
-subscriber.notify(seq);                    // called by the plugin's /admin/identity/notify route
+await subscriber.start(); // initial snapshot or catch-up, then waits for notify()
+subscriber.notify(seq); // called by the plugin's /admin/identity/notify route
 ```
 
 Guarantees:
@@ -217,8 +218,8 @@ Requests reach applications with a **signed identity assertion** instead of
 bare `Remote-*` headers:
 
 - **Through the app-plugin forwarder:** the server half adds the caller to
-  the caller assertion it already signs (app-plugin design, *Authentication
-  between the halves*).
+  the caller assertion it already signs (app-plugin design, _Authentication
+  between the halves_).
 - **Through a plain tunnel** (`authenticated` / `restricted`): Gatekeeper,
   already the `auth_request` target, returns
   `X-Lamalibre-Identity: <JWT>` on allow; nginx copies it to the upstream
@@ -272,11 +273,11 @@ entitlement to end one thing).
 A user can hold several **credentials**, each of which proves "this is that
 user" in a different place:
 
-| Credential | Where it is presented | Verified by |
-|---|---|---|
-| Password + TOTP | Browser (Authelia) | Authelia |
-| Badges (card ids) | Card readers at kiosks, the portal, doors | The site agent, from its local projection |
-| Registry / API tokens | Terminals, machines | The service that issued them (e.g. Feria) |
+| Credential            | Where it is presented                     | Verified by                               |
+| --------------------- | ----------------------------------------- | ----------------------------------------- |
+| Password + TOTP       | Browser (Authelia)                        | Authelia                                  |
+| Badges (card ids)     | Card readers at kiosks, the portal, doors | The site agent, from its local projection |
+| Registry / API tokens | Terminals, machines                       | The service that issued them (e.g. Feria) |
 
 Badges are managed in Lamaste on the user's page: enrol (scan or type the
 id), label (e.g. "13.56 MHz", "125 kHz"), revoke. A person may hold several —
@@ -315,13 +316,13 @@ card read ─► site agent: badge id → userId (local projection)
 "One action ends everything" is only true once the change reaches each
 place that enforces it:
 
-| Enforcer | Reached by | Typical latency |
-|---|---|---|
-| Authelia (web sign-in) | Lamaste writes it directly | immediate |
-| Tunnelled web apps | Gatekeeper, per request | immediate (within its cache lifetime) |
-| Agent-hosted app plugins | Notify through the internal tunnel | seconds |
-| Site agents (badges, doors) | Notify, else next 30 s sync | seconds; **unbounded while the site is offline** |
-| GitLab | Connector (below) | seconds |
+| Enforcer                    | Reached by                         | Typical latency                                  |
+| --------------------------- | ---------------------------------- | ------------------------------------------------ |
+| Authelia (web sign-in)      | Lamaste writes it directly         | immediate                                        |
+| Tunnelled web apps          | Gatekeeper, per request            | immediate (within its cache lifetime)            |
+| Agent-hosted app plugins    | Notify through the internal tunnel | seconds                                          |
+| Site agents (badges, doors) | Notify, else next 30 s sync        | seconds; **unbounded while the site is offline** |
+| GitLab                      | Connector (below)                  | seconds                                          |
 
 Offline sites are the hard case. A badge decision taken from a projection
 that has not heard about a revocation will allow a dismissed employee in.
@@ -373,7 +374,7 @@ HR system — each is a subscriber with its own projection and its own idea of
 "block".
 
 **Feria** is one too. Its design (`feria/docs/design/networked-registry-and-login.md`)
-asks Lamaste for a *group-change hook* that revokes or downgrades a person's
+asks Lamaste for a _group-change hook_ that revokes or downgrades a person's
 registry tokens when their `feria-*` membership changes. In this model that
 hook is Feria's identity subscription: Feria declares the roles `reader`,
 `publisher` and `admin`, entitlements grant them, and a `remove` or a role
@@ -412,24 +413,24 @@ directory and one out of it.
 
 ## Lamaste changes required
 
-| # | Change |
-|---|---|
-| 1 | Directory store in SQLite with `userId`, versions, `seq` triggers, `directoryId`; `users.yml` becomes derived. Migration assigns ids to existing users. |
-| 2 | One entitlement model: migrate `user-plugin-access.json` into Gatekeeper grants with roles. |
-| 3 | `identity` block in the plugin manifest (roles, attributes). |
-| 4 | Audience snapshot and change-feed endpoints, scoped per plugin. |
-| 5 | Notification fan-out: app-plugin forwarder, in-process event, `seq` in agent sync responses. |
-| 6 | Identity assertions: signing key, JWKS endpoint, Gatekeeper returns the assertion, nginx forwards it. |
-| 7 | Bulk user import (CSV) and a directory import API for external systems of record. |
-| 8 | SDK: `IdentitySubscriber`, `verifyIdentity` plugin, SQLite projection helpers. |
-| 9 | Badges as user credentials: enrol, label, revoke; `badges` attribute for card-reading plugins. |
-| 10 | Audit log: events forwarded by plugins and agents (`userId`, credential, action, result). |
-| 11 | Projection age reported by agents; offline policy declared by badge-reading plugins. |
-| 12 | Authelia OIDC provider (shared with Feria) and a GitLab connector plugin. |
+| #   | Change                                                                                                                                                  |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Directory store in SQLite with `userId`, versions, `seq` triggers, `directoryId`; `users.yml` becomes derived. Migration assigns ids to existing users. |
+| 2   | One entitlement model: migrate `user-plugin-access.json` into Gatekeeper grants with roles.                                                             |
+| 3   | `identity` block in the plugin manifest (roles, attributes).                                                                                            |
+| 4   | Audience snapshot and change-feed endpoints, scoped per plugin.                                                                                         |
+| 5   | Notification fan-out: app-plugin forwarder, in-process event, `seq` in agent sync responses.                                                            |
+| 6   | Identity assertions: signing key, JWKS endpoint, Gatekeeper returns the assertion, nginx forwards it.                                                   |
+| 7   | Bulk user import (CSV) and a directory import API for external systems of record.                                                                       |
+| 8   | SDK: `IdentitySubscriber`, `verifyIdentity` plugin, SQLite projection helpers.                                                                          |
+| 9   | Badges as user credentials: enrol, label, revoke; `badges` attribute for card-reading plugins.                                                          |
+| 10  | Audit log: events forwarded by plugins and agents (`userId`, credential, action, result).                                                               |
+| 11  | Projection age reported by agents; offline policy declared by badge-reading plugins.                                                                    |
+| 12  | Authelia OIDC provider (shared with Feria) and a GitLab connector plugin.                                                                               |
 
 ## Open questions
 
-1. *(Decided 2026-10-13: employees are Lamaste users; badges are credentials on the user.)*
+1. _(Decided 2026-10-13: employees are Lamaste users; badges are credentials on the user.)_
 2. **PDKS's source of truth:** samplepark pushes into Lamaste, or Lamaste
    mirrors samplepark?
 3. **Erasure:** which plugins hold data that must be anonymised on request,

package/vendor/docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/lamaste-docs",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "private": true,
   "description": "Lamaste documentation — markdown files served by the panel and published to GitHub Pages",
   "type": "module",

package/vendor/docs/todo/lib-cli-desktop-refactor.md

@@ -29,7 +29,7 @@ feria                        dev registry — OUT OF SCOPE, do not touch
 
 ### Naming Rules
 
-- **`lamaste`** is the core lib. You `import { ... } from '@lamalibre/lamaste@4.2.0'`. No `-lib` suffix.
+- **`lamaste`** is the core lib. You `import { ... } from '@lamalibre/lamaste@4.3.0'`. No `-lib` suffix.
 - **`-d` suffix** for daemons — Unix convention (`httpd`, `sshd`, `mongod`). Instantly signals "long-running process".
 - **`-ui`** for React component libraries — universal term, avoids "serverd serves the panel" tautology.
 - **`create-*`** for all npx one-shot tools — the one npm convention everyone knows.
@@ -74,24 +74,24 @@ lamaste                              core library (types, constants, schemas, pl
 
 | #   | Package (npm name)                  | Type        | Depends on | Purpose                                                                                                             |
 | --- | ----------------------------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
-| 1   | `@lamalibre/lamaste@4.2.0`                | core lib    | nothing    | Types, constants, Zod schemas, plugin host Fastify plugin, atomic file helpers, client interfaces                   |
-|     |                                     |             |            | Subpath: `@lamalibre/lamaste@4.2.0/agent` — agent domain logic                                                            |
-|     |                                     |             |            | Subpath: `@lamalibre/lamaste@4.2.0/server` — server domain logic                                                          |
-| 2   | `@lamalibre/lamaste-agent@4.2.0`          | CLI         | `lamaste`  | Thin agent CLI. No Fastify, no HTTP                                                                                 |
-| 3   | `@lamalibre/lamaste-agentd@4.2.0`         | daemon      | `lamaste`  | Agent REST API on :9393. No CLI argument parsing                                                                    |
-| 4   | `@lamalibre/lamaste-agent-ui@4.2.0`       | UI lib      | `lamaste`  | Agent React components + browser SPA build. Used by desktop and agentd                                              |
-| 5   | `@lamalibre/lamaste-server@4.2.0`         | CLI         | `lamaste`  | **NEW.** Thin server CLI. No Fastify, no HTTP                                                                       |
-| 6   | `@lamalibre/lamaste-serverd@4.2.0`        | daemon      | `lamaste`  | Server REST API on :3100. No CLI argument parsing. Renamed from `serverd`                                           |
-| 7   | `@lamalibre/lamaste-server-ui@4.2.0`      | UI lib      | `lamaste`  | Server/admin React components + browser SPA build. Replaces both `panel-client` and `lamaste-admin-panel`           |
-| 8   | `@lamalibre/lamaste@4.2.0-desktop`        | desktop     | `lamaste`  | Unified Tauri app. Multi-target: full, agent-only, server-only. Credentials, tray, deep links                       |
-| 9   | `@lamalibre/lamaste-cloud@4.2.0`          | lib + CLI   | —          | Cloud provider abstraction (already correct pattern)                                                                |
-| 10  | `@lamalibre/lamaste-tickets@4.2.0`        | SDK         | —          | Agent-to-agent authorization                                                                                        |
-| 11  | `@lamalibre/lamaste-identity@4.2.0`       | SDK         | —          | Authelia identity parsing and query                                                                                 |
-| 12  | `@lamalibre/create-lamaste@4.2.0`         | provisioner | `lamaste`  | Server provisioner: OS hardening, nginx, Authelia, certs. `npx create-lamaste`                                      |
-| 13  | `@lamalibre/create-lamaste-agent@4.2.0`   | provisioner | `lamaste`  | Agent provisioner: cert enrollment, service setup. `npx create-lamaste-agent`. Renamed from `install-lamaste-agent` |
-| 14  | `@lamalibre/create-lamaste-desktop@4.2.0` | installer   | —          | Desktop app installer. `npx create-lamaste-desktop`. Renamed from `install-lamaste-desktop`                         |
-| 15  | `@lamalibre/create-lamaste-admin@4.2.0`   | provisioner | `lamaste`  | Admin cert upgrade to hardware-bound. `npx create-lamaste-admin`. Renamed from `install-lamaste-admin`              |
-| 16  | `@lamalibre/create-lamaste-e2e@4.2.0`     | test infra  | —          | E2E test MCP server. `npx create-lamaste-e2e`. Renamed from `install-lamaste-e2e-mcp`                               |
+| 1   | `@lamalibre/lamaste@4.3.0`                | core lib    | nothing    | Types, constants, Zod schemas, plugin host Fastify plugin, atomic file helpers, client interfaces                   |
+|     |                                     |             |            | Subpath: `@lamalibre/lamaste@4.3.0/agent` — agent domain logic                                                            |
+|     |                                     |             |            | Subpath: `@lamalibre/lamaste@4.3.0/server` — server domain logic                                                          |
+| 2   | `@lamalibre/lamaste-agent@4.3.0`          | CLI         | `lamaste`  | Thin agent CLI. No Fastify, no HTTP                                                                                 |
+| 3   | `@lamalibre/lamaste-agentd@4.3.0`         | daemon      | `lamaste`  | Agent REST API on :9393. No CLI argument parsing                                                                    |
+| 4   | `@lamalibre/lamaste-agent-ui@4.3.0`       | UI lib      | `lamaste`  | Agent React components + browser SPA build. Used by desktop and agentd                                              |
+| 5   | `@lamalibre/lamaste-server@4.3.0`         | CLI         | `lamaste`  | **NEW.** Thin server CLI. No Fastify, no HTTP                                                                       |
+| 6   | `@lamalibre/lamaste-serverd@4.3.0`        | daemon      | `lamaste`  | Server REST API on :3100. No CLI argument parsing. Renamed from `serverd`                                           |
+| 7   | `@lamalibre/lamaste-server-ui@4.3.0`      | UI lib      | `lamaste`  | Server/admin React components + browser SPA build. Replaces both `panel-client` and `lamaste-admin-panel`           |
+| 8   | `@lamalibre/lamaste@4.3.0-desktop`        | desktop     | `lamaste`  | Unified Tauri app. Multi-target: full, agent-only, server-only. Credentials, tray, deep links                       |
+| 9   | `@lamalibre/lamaste-cloud@4.3.0`          | lib + CLI   | —          | Cloud provider abstraction (already correct pattern)                                                                |
+| 10  | `@lamalibre/lamaste-tickets@4.3.0`        | SDK         | —          | Agent-to-agent authorization                                                                                        |
+| 11  | `@lamalibre/lamaste-identity@4.3.0`       | SDK         | —          | Authelia identity parsing and query                                                                                 |
+| 12  | `@lamalibre/create-lamaste@4.3.0`         | provisioner | `lamaste`  | Server provisioner: OS hardening, nginx, Authelia, certs. `npx create-lamaste`                                      |
+| 13  | `@lamalibre/create-lamaste-agent@4.3.0`   | provisioner | `lamaste`  | Agent provisioner: cert enrollment, service setup. `npx create-lamaste-agent`. Renamed from `install-lamaste-agent` |
+| 14  | `@lamalibre/create-lamaste-desktop@4.3.0` | installer   | —          | Desktop app installer. `npx create-lamaste-desktop`. Renamed from `install-lamaste-desktop`                         |
+| 15  | `@lamalibre/create-lamaste-admin@4.3.0`   | provisioner | `lamaste`  | Admin cert upgrade to hardware-bound. `npx create-lamaste-admin`. Renamed from `install-lamaste-admin`              |
+| 16  | `@lamalibre/create-lamaste-e2e@4.3.0`     | test infra  | —          | E2E test MCP server. `npx create-lamaste-e2e`. Renamed from `install-lamaste-e2e-mcp`                               |
 | 17  | `@lamalibre/feria`                  | dev tool    | —          | Dev registry + release runner. **Out of scope — do not touch in this refactor**                                     |
 
 ### Rename Map (1.x → 2.0.0)
@@ -116,7 +116,7 @@ The core library uses **subpath exports** to provide domain-specific entry point
 
 ```json
 {
-  "name": "@lamalibre/lamaste@4.2.0",
+  "name": "@lamalibre/lamaste@4.3.0",
   "exports": {
     ".": "./dist/index.js",
     "./agent": "./dist/agent/index.js",
@@ -126,9 +126,9 @@ The core library uses **subpath exports** to provide domain-specific entry point
 ```
 
 ```typescript
-import { RESERVED_API_PREFIXES, pluginManifestSchema } from '@lamalibre/lamaste@4.2.0';
-import { loadRegistry, loadAgent, isAgentLoaded } from '@lamalibre/lamaste@4.2.0/agent';
-import { createTunnel, rotateCert } from '@lamalibre/lamaste@4.2.0/server';
+import { RESERVED_API_PREFIXES, pluginManifestSchema } from '@lamalibre/lamaste@4.3.0';
+import { loadRegistry, loadAgent, isAgentLoaded } from '@lamalibre/lamaste@4.3.0/agent';
+import { createTunnel, rotateCert } from '@lamalibre/lamaste@4.3.0/server';
 ```
 
 **Why subpath exports instead of three packages (`lamaste-lib`, `lamaste-lib-agent`, `lamaste-lib-server`):**
@@ -149,7 +149,7 @@ import { createTunnel, rotateCert } from '@lamalibre/lamaste@4.2.0/server';
 
 | Layer                    | Agent side                                      | Server side                                    |
 | ------------------------ | ----------------------------------------------- | ---------------------------------------------- |
-| **Domain logic**         | `@lamalibre/lamaste@4.2.0/agent`                      | `@lamalibre/lamaste@4.2.0/server`                    |
+| **Domain logic**         | `@lamalibre/lamaste@4.3.0/agent`                      | `@lamalibre/lamaste@4.3.0/server`                    |
 | **Operational CLI**      | `lamaste-agent`                                 | `lamaste-server` (new)                         |
 | **Long-running daemon**  | `lamalibre-lamaste-agentd` on :9393 (extracted) | `lamalibre-lamaste-serverd` on :3100 (renamed) |
 | **UI components**        | `lamaste-agent-ui` (renamed)                    | `lamaste-server-ui` (merged)                   |
@@ -471,7 +471,7 @@ The Rust backend has both `commands.rs` (legacy) and `agents.rs` (multi-agent).
 
 Create `packages/lamaste/` (TypeScript) with subpath exports:
 
-**Root (`@lamalibre/lamaste@4.2.0`):**
+**Root (`@lamalibre/lamaste@4.3.0`):**
 
 - Types: `AdminClient`, `AgentClient` TypeScript interfaces, plugin manifest types, capability types
 - Constants: Reserved API prefixes, curated plugin list, capability names
@@ -479,7 +479,7 @@ Create `packages/lamaste/` (TypeScript) with subpath exports:
 - Plugin Host: Fastify plugin for plugin route mounting, bundle serving, disabled handler (unified from three routers)
 - File Helpers: Atomic write (temp → fsync → rename), promise-chain mutex
 
-**Agent subpath (`@lamalibre/lamaste@4.2.0/agent`):**
+**Agent subpath (`@lamalibre/lamaste@4.3.0/agent`):**
 
 - Platform: Path helpers, platform detection (from `platform.js`)
 - Registry: Agent registry CRUD, label validation, legacy migration (from `registry.js`)
@@ -491,7 +491,7 @@ Create `packages/lamaste/` (TypeScript) with subpath exports:
 - Server Registry: servers.json and storage-servers.json CRUD (new — from Rust `cloud.rs`)
 - Mode: Server mode and admin cert file operations (new — from Rust `mode.rs`)
 
-**Server subpath (`@lamalibre/lamaste@4.2.0/server`):**
+**Server subpath (`@lamalibre/lamaste@4.3.0/server`):**
 
 - Plugins: Server-side plugin lifecycle (uses shared schema from root)
 - Tunnels: Tunnel creation workflow with rollback (from `routes/tunnels.js`)