@lamalibre/create-lamaste 4.4.1 → 4.6.0

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

@@ -27,7 +27,7 @@ Coming from 3.x, upgrade the **agents first**, as 4.0 required: agents from befo
 On each agent machine, after the server:
 
 ```bash
-sudo npm install -g @lamalibre/lamaste-agent@4.4.1
+sudo npm install -g @lamalibre/lamaste-agent@4.6.0
 lamaste-agent update
 ```
 
@@ -35,6 +35,24 @@ lamaste-agent update
 
 A machine that hosts app plugins' agent halves needs the root-owned install shown above and its app host helper enabled once with `sudo lamaste-agent apphost enable` (see [App host](../04-api-reference/app-host.md)); after replacing the server's relay signing key, run `sudo lamaste-agent apphost pin` there. An upgrade of `lamaste-agent` does not replace that helper: when a release raises the app host protocol (4.4 speaks 2), run `sudo lamaste-agent apphost enable` again there — until then the agent refuses to install agent halves and the server does not offer it for hosting (`lamaste-agent apphost status` shows the helper as out of date).
 
+### Upgrading to 4.6
+
+4.6 adds plugins' web surfaces ([Web surface](../04-api-reference/agent-hosted-plugins.md#web-surface)). **Only the relay is upgraded**: the panel's **Update** action, or a `create-lamaste@4.6.0 --yes` redeploy.
+
+- **`state.db` migration `0015`** adds `plugins.user_surface` and `plugins.web_tree_sha256`. Existing plugins declare no web surface: their approval digests are unchanged.
+- **`lamaste-priv` must be the 4.6 one** before the panel writes a web surface's vhost: it now accepts a server-level `auth_request`, named locations and a named location as `try_files`' last argument. The Update action and the redeploy install it; a relay whose `lamaste-priv` is older refuses the vhost (`nginx site write failed … directive "auth_request" is not allowed in server`) and keeps the vhost it had.
+- **Web trees live under `/var/www/lamaste/apps/`.** They are copies of approved package contents, made again at the panel's start when missing: nothing there needs a backup.
+- **What changes for existing setups.** Gatekeeper reads `sites.json` as well as `tunnels.json`. The check that a tunnel and a site never share a hostname now runs under the tunnel lock, for enabling a tunnel too. The sites API serves `sites.json` under a lock, and an upload's size is recorded from the file as it is then.
+
+### Upgrading to 4.5
+
+4.5 adds the user directory and users of agent-hosted plugins ([Users and identity](../04-api-reference/agent-hosted-plugins.md#users-and-identity)). **Only the relay is upgraded**: the panel's **Update** action, or a `create-lamaste@4.5.0 --yes` redeploy.
+
+- **`state.db` migration `0013`.** On its first start the panel creates the user directory (a `directoryId`, a `userId` per user, tombstones), the plugin audiences, the per-plugin feed state and the erasure records, and adds `plugins.identity`. It then reads `users.yml` — without writing it — and gives every existing user a `userId`. Back up `state.db` before upgrading, as before any upgrade: from now on it holds the mapping from usernames to user ids ([Backup and Restore](backup-and-restore.md#backup-considerations)).
+- **The redeploy now touches the IP panel vhost.** Until 4.4 a redeploy left every panel vhost alone. From 4.5 it refreshes `lamalibre-lamaste-panel-ip` — the vhost the installer writes and the panel cannot — when its text differs from the current generator's: written, checked with `nginx -t`, put back on failure, and nginx reloaded; its `sites-enabled` link (which panel 2FA owns) is left as it is. A failure is reported and skipped (`Refreshing the IP panel vhost — Skipped`): the panel keeps working on the vhost it had, which still passes a client's `X-Lamalibre-Relay-Assertion` through to the panel (which accepts only a valid, single-use one Gatekeeper signed) — fix what `nginx -t` names and redeploy. The panel itself rewrites the domain panel, auth portal and tunnel vhosts at start, as since 4.3; each now clears a client's `X-Lamalibre-Relay-Assertion`.
+- **No agent upgrade is needed**, and no agent half must be rebuilt. An agent half built on `@lamalibre/lamaste@4.6.0` 4.4 keeps working and **never receives a user caller**: the panel sends one only after the half has answered the identity feed with protocol 1 for its installed version. A plugin gets users by shipping a version that declares `identity` with a half built on 4.5 — an update that waits for approval — then binding its user surface to a tunnel.
+- **What changes for existing setups.** The admin forwarder no longer reaches an agent half's `/admin/app` or anything under it (on the panel `/api/<route>/app*` is the user surface). The hook preview's `inactiveRoutes` is now `userSurfaceRoutes`. Every write of `users.yml` the panel makes — creating, updating, deleting users, accepting invitations — now runs under one lock, one after the other. Deleting a user keeps a tombstone in the directory and clears the username's grants and group memberships in Gatekeeper. A registry credential must carry the `read` scope as well as `admin` (a `PUT /api/registry-credential` with an admin-only identity is refused).
+
 ### Updating Lamaste (Panel Server and Client)
 
 The Lamaste installer is idempotent — you can re-run it on an existing installation to update the panel server and client without losing your configuration.
@@ -63,7 +81,7 @@ The `@latest` tag ensures you get the newest published version. The `--yes` flag
 - It installs the pinned Chisel and Authelia releases if they are not already installed (a newer Authelia is kept), writes their systemd units, creates the `lamaste-chisel` group and the `lamaste-authelia` account, and sets the ownership described in [Configuration Files](../06-reference/config-files.md#file-permissions-table): `/var/www/lamaste` becomes `lamaste:www-data`, `/etc/authelia` `lamaste:lamaste-authelia`, the Chisel key `lamaste:lamaste-chisel 0640`, and the PKI directory `lamaste`'s. A running Authelia is stopped while its files change hands and started again afterwards
 - It generates the OpenID Connect issuer key `/etc/authelia/oidc-issuer.pem` (0600, `lamaste-authelia`) if it is missing, and the Authelia unit it writes enables the `template` configuration filter. A 4.0 server updating to 4.1 therefore has the key before the new panel starts; plugin OIDC clients and the `--oidc` registry credential need it
 - It upgrades Node.js from NodeSource when the installed version is older than 22.13 — the plugin hook runner's sandbox uses Node's stable permission model — and writes the hook runner's units (`lamalibre-lamaste-hooks@.socket`, `lamalibre-lamaste-hooks@.service`; see [Lifecycle hooks](../04-api-reference/lifecycle-hooks.md))
-- It rewrites the panel's systemd unit and the sudoers rules (checked with `visudo -c` before they replace the old file), installs the root-owned programs in `/usr/local/sbin/` (`lamaste-priv`, `lamaste-certbot`, `lamaste-cert-info`) and removes the retired `lamaste-sign-csr` and `lamaste-pki-rename`, and installs the port-80 redirect site
+- It rewrites the panel's systemd unit and the sudoers rules (checked with `visudo -c` before they replace the old file), installs the root-owned programs in `/usr/local/sbin/` (`lamaste-priv`, `lamaste-certbot`, `lamaste-cert-info`) and removes the retired `lamaste-sign-csr` and `lamaste-pki-rename`, and installs the port-80 redirect site, and refreshes the IP panel vhost when its text differs (from 4.5; `nginx -t`, put back on failure)
 - It restarts Chisel if its binary or unit changed, starts the gatekeeper if it was running, and restarts `lamalibre-lamaste-serverd`, whose startup reconciliation rewrites Chisel's authfile. The first start of a 4.3 panel also creates the relay signing key (`/etc/lamalibre/lamaste/relay-signing-key.json`, 0600) and rewrites existing tunnel, static site and auth portal vhosts; check its log for `Left tunnel vhosts as they are`, `Left site vhosts as they are` and `Failed to rewrite … vhost` (see the [4.3.0 upgrade notes](https://github.com/lamalibre/lamaste/blob/main/CHANGELOG.md))
 
 The panel's **Update** action (`POST /api/system/update`) runs the same redeploy: it asks `sudo lamaste-priv self-update <version>` to start `create-lamaste@<version> --yes` in a transient systemd unit (see [System API](../04-api-reference/system.md)).
@@ -84,7 +102,7 @@ exit
 
 ### Updating Chisel
 
-Chisel is the tunnel server binary at `/usr/local/bin/chisel`. Lamaste pins it: server and agents run Chisel 1.12.0 (`CHISEL_RELEASE` in `@lamalibre/lamaste@4.4.1`), downloaded from the fixed release URL and verified against a pinned SHA-256 before it is unpacked. **Do not replace the binary by hand.** On the server, `create-lamaste` installs it (as root) and replaces a binary that reports any other version; the panel cannot install binaries, and only logs an error at startup when the installed Chisel is not the pinned release (it then restarts Chisel on every authfile change). Each agent's sync replaces its own copy.
+Chisel is the tunnel server binary at `/usr/local/bin/chisel`. Lamaste pins it: server and agents run Chisel 1.12.0 (`CHISEL_RELEASE` in `@lamalibre/lamaste@4.6.0`), downloaded from the fixed release URL and verified against a pinned SHA-256 before it is unpacked. **Do not replace the binary by hand.** On the server, `create-lamaste` installs it (as root) and replaces a binary that reports any other version; the panel cannot install binaries, and only logs an error at startup when the installed Chisel is not the pinned release (it then restarts Chisel on every authfile change). Each agent's sync replaces its own copy.
 
 A new Chisel version therefore arrives with a Lamaste release that changes the pin: re-run the installer, which installs it and restarts Chisel. To check what is running:
 
@@ -98,7 +116,7 @@ Tunnel clients reconnect on their own after the brief interruption (they retry a
 
 ### Updating Authelia
 
-Authelia is the authentication server binary at `/usr/local/bin/authelia`. Lamaste pins it too: Authelia 4.39.28 (`AUTHELIA_RELEASE` in `@lamalibre/lamaste@4.4.1`), downloaded by `create-lamaste` from its fixed release URL and verified against a pinned SHA-256 per architecture. A new Authelia version arrives with a Lamaste release that changes the pin — re-run the installer. It stops Authelia while it replaces the binary and starts it again.
+Authelia is the authentication server binary at `/usr/local/bin/authelia`. Lamaste pins it too: Authelia 4.39.28 (`AUTHELIA_RELEASE` in `@lamalibre/lamaste@4.6.0`), downloaded by `create-lamaste` from its fixed release URL and verified against a pinned SHA-256 per architecture. A new Authelia version arrives with a Lamaste release that changes the pin — re-run the installer. It stops Authelia while it replaces the binary and starts it again.
 
 An installed Authelia **newer** than the pin is kept, never downgraded: its database may already use a schema the pinned release cannot read, and Authelia refuses to start on a database newer than itself. If you install a newer release by hand, stop the service, replace the binary as root with a `root:root 0755` file, and start it again; check the [Authelia changelog](https://github.com/authelia/authelia/blob/master/CHANGELOG.md) first, since the configuration format may change between versions.
 
@@ -237,7 +255,7 @@ The panel server, CLI, client, docs and gatekeeper are always redeployed (files
 
 ### Version Pinning
 
-Chisel and Authelia are pinned by version and SHA-256 in `packages/core/lib/src/constants.ts` (`CHISEL_RELEASE`, `AUTHELIA_RELEASE`); changing a pin means updating the version and every digest there. The downloads are verified by `downloadVerifiedChisel` / `downloadVerifiedAuthelia` (exported from `@lamalibre/lamaste@4.4.1`) before anything is unpacked; the server installer uses them in `packages/provisioners/server/src/lib/binaries.js`. The configuration the panel writes needs Authelia 4.38 or later.
+Chisel and Authelia are pinned by version and SHA-256 in `packages/core/lib/src/constants.ts` (`CHISEL_RELEASE`, `AUTHELIA_RELEASE`); changing a pin means updating the version and every digest there. The downloads are verified by `downloadVerifiedChisel` / `downloadVerifiedAuthelia` (exported from `@lamalibre/lamaste@4.6.0`) before anything is unpacked; the server installer uses them in `packages/provisioners/server/src/lib/binaries.js`. The configuration the panel writes needs Authelia 4.38 or later.
 
 ### Automated Updates
 
@@ -259,7 +277,7 @@ sudo dpkg-reconfigure -plow unattended-upgrades
 | Panel server | `/opt/lamalibre/lamaste/lamaste-serverd/`      | Re-run `npx @lamalibre/create-lamaste@latest`         |
 | Panel client | `/opt/lamalibre/lamaste/lamaste-server-ui/`    | Re-run `npx @lamalibre/create-lamaste@latest`         |
 | Chisel       | `/usr/local/bin/chisel`                        | Pinned; installed by `create-lamaste`                 |
-| Agents       | `sudo npm install -g @lamalibre/lamaste-agent@4.4.1` | Upgrade after the server, then `lamaste-agent update` |
+| Agents       | `sudo npm install -g @lamalibre/lamaste-agent@4.6.0` | Upgrade after the server, then `lamaste-agent update` |
 | Authelia     | `/usr/local/bin/authelia`                      | Pinned; installed by `create-lamaste` (newer is kept) |
 | nginx        | System package                                 | `sudo apt-get update && sudo apt-get upgrade`         |
 | certbot      | System package                                 | `sudo apt-get update && sudo apt-get upgrade`         |

package/vendor/docs/06-reference/config-files.md

@@ -4,72 +4,71 @@
 
 ## File Overview
 
-| File                                                               | Format     | Owner                    | Mode | Purpose                                                                                                                                                                                                                                    |
-| ------------------------------------------------------------------ | ---------- | ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/etc/lamalibre/lamaste/panel.json`                                | JSON       | lamaste:lamaste          | 0600 | Panel server configuration                                                                                                                                                                                                                 |
-| `/etc/lamalibre/lamaste/tunnels.json`                              | JSON       | lamaste:lamaste          | 0600 | Tunnel definitions                                                                                                                                                                                                                         |
-| `/etc/lamalibre/lamaste/sites.json`                                | JSON       | lamaste:lamaste          | 0600 | Static site definitions                                                                                                                                                                                                                    |
-| `/etc/lamalibre/lamaste/chisel-credentials.json`                   | JSON       | lamaste:lamaste          | 0600 | Per-agent Chisel credentials (source of truth for the authfile)                                                                                                                                                                            |
-| `/etc/lamalibre/lamaste/chisel-users`                              | JSON       | lamaste:lamaste-chisel   | 0640 | Chisel `--authfile`: per-agent credentials and port grants (rendered)                                                                                                                                                                      |
-| `/etc/lamalibre/lamaste/chisel-sentinel`                           | text       | lamaste:lamaste          | 0600 | Password of the `lamaste-no-grants` sentinel user                                                                                                                                                                                          |
-| `/etc/lamalibre/lamaste/chisel-server.key`                         | PEM        | lamaste:lamaste-chisel   | 0640 | Chisel SSH host key (`--keyfile`), generated by the panel at onboarding                                                                                                                                                                    |
-| `/etc/authelia/configuration.yml`                                  | YAML       | lamaste:lamaste-authelia | 0640 | Authelia server configuration                                                                                                                                                                                                              |
-| `/etc/authelia/users.yml`                                          | YAML       | lamaste:lamaste-authelia | 0660 | User database (Authelia rewrites it on a password change)                                                                                                                                                                                  |
-| `/etc/authelia/.secrets.json`                                      | JSON       | lamaste:lamaste-authelia | 0600 | Authelia secrets (panel only)                                                                                                                                                                                                              |
-| `/etc/authelia/oidc-issuer.pem`                                    | PEM        | lamaste-authelia         | 0600 | RSA-4096 key Authelia signs OIDC tokens with, written by `create-lamaste`; the panel cannot read it                                                                                                                                        |
-| `/etc/lamalibre/lamaste/registry-credential.json`                  | JSON       | lamaste:lamaste          | 0600 | The panel's registry (Feria) credential: a pasted token, or the `lamaste-server` OIDC client                                                                                                                                               |
-| `/etc/lamalibre/lamaste/oidc-clients.json`                         | JSON       | lamaste:lamaste          | 0600 | Plaintext secrets (and pbkdf2 salts) of confidential OIDC clients                                                                                                                                                                          |
-| `/etc/lamalibre/lamaste/relay-signing-key.json`                    | JSON       | lamaste:lamaste          | 0600 | Ed25519 key relay assertions (panel, Gatekeeper) and agents' app jobs (panel) are signed with                                                                                                                                              |
-| `/etc/lamalibre/lamaste/push-install-config.json`                  | JSON       | lamaste:lamaste          | 0600 | Push install: the switch, the policies, the default policy                                                                                                                                                                                 |
-| `/etc/lamalibre/lamaste/push-install-sessions.json`                | JSON       | lamaste:lamaste          | 0600 | Push install log (last 500 pushes)                                                                                                                                                                                                         |
-| `/etc/lamalibre/lamaste/ticket-scopes.json`                        | JSON       | lamaste:lamaste          | 0600 | Ticket scope registry                                                                                                                                                                                                                      |
-| `/etc/lamalibre/lamaste/tickets.json`                              | JSON       | lamaste:lamaste          | 0600 | Ticket and session store                                                                                                                                                                                                                   |
-| `/etc/lamalibre/lamaste/invitations.json`                          | JSON       | lamaste:lamaste          | 0600 | Pending user invitations                                                                                                                                                                                                                   |
-| `/etc/lamalibre/lamaste/plugins.json`                              | JSON       | lamaste:lamaste          | 0600 | Plugin registry (before 4.2; the registry is now in `state.db`)                                                                                                                                                                            |
-| `/etc/lamalibre/lamaste/state.db`                                  | SQLite     | lamaste:lamaste          | 0600 | Plugins (with their hooks), agents, tickets, enrollment tokens, the audit log, notifications, relay hook approvals, plugin operations, agent jobs, the cache of agent-hosted plugins' settings (never a secret), each agent's last contact |
-| `/etc/lamalibre/lamaste/plugin-hostings.json`                      | JSON       | lamaste:lamaste          | 0600 | Hostings of agent-hosted plugins: agent, port, phase, installation secrets, health                                                                                                                                                         |
-| `/opt/lamalibre/lamaste/hooks/<route>/`                            | directory  | root:root                | 0755 | A plugin's approved relay hook module (`<sha256>.mjs`, 0644) and `runner.env`, written by `lamaste-priv`                                                                                                                                   |
-| `/etc/lamalibre/lamaste/storage-config.json`                       | JSON       | lamaste:lamaste          | 0600 | Storage server registry and plugin bindings (credentials AES-256-GCM encrypted)                                                                                                                                                            |
-| `/etc/lamalibre/lamaste/storage-master.key`                        | Binary     | lamaste:lamaste          | 0600 | 32-byte master key for storage credential encryption                                                                                                                                                                                       |
-| `/etc/lamalibre/lamaste/groups.json`                               | JSON       | lamaste:lamaste          | 0600 | Lamaste group definitions and membership                                                                                                                                                                                                   |
-| `/etc/lamalibre/lamaste/access-grants.json`                        | JSON       | lamaste:lamaste          | 0600 | Generic access grants (principal → resource)                                                                                                                                                                                               |
-| `/etc/lamalibre/lamaste/gatekeeper.json`                           | JSON       | lamaste:lamaste          | 0600 | Gatekeeper settings (cache TTL, admin contact, logging)                                                                                                                                                                                    |
-| `/etc/lamalibre/lamaste/access-request-log.json`                   | JSON       | lamaste:lamaste          | 0600 | Optional denied access log                                                                                                                                                                                                                 |
-| `/etc/lamalibre/lamaste/pki/enrollment-tokens.json`                | JSON       | lamaste:lamaste          | 0600 | One-time enrollment tokens for hardware-bound enrollment                                                                                                                                                                                   |
-| `/etc/lamalibre/lamaste/pki/revoked.json`                          | JSON       | lamaste:lamaste          | 0600 | Revoked certificate serial numbers                                                                                                                                                                                                         |
-| `/etc/lamalibre/lamaste/pki/agents/registry.json`                  | JSON       | lamaste:lamaste          | 0600 | Agent certificate metadata                                                                                                                                                                                                                 |
-| `/etc/nginx/sites-available/lamalibre-lamaste-*`                   | nginx conf | root:root                | 0644 | Vhost configurations (the panel's are installed by `lamaste-priv`)                                                                                                                                                                         |
-| `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`                  | nginx conf | root:root                | 0644 | mTLS snippet                                                                                                                                                                                                                               |
-| `/etc/nginx/snippets/lamalibre-lamaste-authz-cache.conf`           | nginx conf | root:root                | 0644 | Gatekeeper proxy_cache zone                                                                                                                                                                                                                |
-| `/etc/systemd/system/lamalibre-lamaste-gatekeeper.service`         | systemd    | root:root                | 0644 | Gatekeeper systemd unit                                                                                                                                                                                                                    |
-| `/etc/systemd/system/chisel.service`                               | systemd    | root:root                | 0644 | Chisel unit, written by `create-lamaste`                                                                                                                                                                                                   |
-| `/etc/systemd/system/authelia.service`                             | systemd    | root:root                | 0644 | Authelia unit, written by `create-lamaste`                                                                                                                                                                                                 |
-| `/etc/systemd/system/lamalibre-lamaste-hooks@.socket`, `@.service` | systemd    | root:root                | 0644 | Relay hook runner (one instance per plugin with relay hooks), written by `create-lamaste`                                                                                                                                                  |
-| `~/.lamalibre/lamaste/servers.json`                                | JSON       | user                     | 0600 | Desktop app server registry                                                                                                                                                                                                                |
-| `~/.lamalibre/lamaste/agents.json`                                 | JSON       | user                     | 0600 | Multi-agent registry                                                                                                                                                                                                                       |
-| `~/.lamalibre/lamaste/agentd.token`                                | JSON       | user                     | 0600 | Bearer token of lamaste-agentd's owner (the desktop app, scripts run as the user)                                                                                                                                                          |
-| `~/.lamalibre/lamaste/agents/<label>/config.json`                  | JSON       | user                     | 0600 | Per-agent configuration                                                                                                                                                                                                                    |
-| `~/.lamalibre/lamaste/agents/<label>/client.p12`                   | PKCS#12    | user                     | 0600 | Per-agent mTLS certificate                                                                                                                                                                                                                 |
-| `~/.lamalibre/lamaste/agents/<label>/ca.crt`                       | PEM        | user                     | 0644 | Per-agent CA certificate                                                                                                                                                                                                                   |
-| `~/.lamalibre/lamaste/agents/<label>/chisel.json`                  | JSON       | user                     | 0600 | Per-agent Chisel credential (source of truth for the service)                                                                                                                                                                              |
-| `~/.lamalibre/lamaste/agents/<label>/chisel.env`                   | env file   | user                     | 0600 | Linux only: `AUTH=` for the systemd unit's `EnvironmentFile=`                                                                                                                                                                              |
-| `~/.lamalibre/lamaste/agents/<label>/`                             | directory  | user                     | 0700 | Per-agent data directory                                                                                                                                                                                                                   |
-| `~/.lamalibre/lamaste/agents/<label>/sync-state.json`              | JSON       | user                     | 0600 | Outcome of the last `lamaste-agent sync`                                                                                                                                                                                                   |
-| `~/.lamalibre/lamaste/agents/<label>/app-plugins/<route>.json`     | JSON       | user                     | 0600 | Port and installation secret of a plugin hosted on this agent                                                                                                                                                                              |
-| `~/.lamalibre/lamaste/agents/<label>/app-plugin-tunnel-state.json` | JSON       | user                     | 0600 | The tunnel state last delivered to each hosted plugin's agent half                                                                                                                                                                         |
-| `~/.lamalibre/lamaste/agents/<label>/apphost-state.json`           | JSON       | user                     | 0600 | The agent halves the app host helper installed for this agent                                                                                                                                                                              |
-| `~/.lamalibre/lamaste/agents/<label>/host-facts.json`              | JSON       | user                     | 0600 | What the agent last reported about its host, and the helper's last answer                                                                                                                                                                  |
-| `~/.lamalibre/lamaste/agents/<label>/app-job-results.json`         | JSON       | user                     | 0600 | App job results the relay has not taken yet                                                                                                                                                                                                |
-| `~/.lamalibre/lamaste/agents/<label>/logs/`                        | directory  | user                     | 0700 | Per-agent Chisel and sync log files                                                                                                                                                                                                        |
-| `~/.lamalibre/lamaste/agent.json`                                  | JSON       | user                     | 0600 | Legacy single-server config                                                                                                                                                                                                                |
-| `/usr/local/sbin/lamaste-apphost`                                  | Node.js    | root:root                | 0755 | Agent machine: the app host helper — see [Agent machine: the app host](#agent-machine-the-app-host)                                                                                                                                        |
-| `/etc/sudoers.d/lamaste-apphost`                                   | sudoers    | root:root                | 0440 | Agent machine: lets the agent's user run the helper                                                                                                                                                                                        |
-| `/etc/lamalibre/apphost/relays/<label>.json`                       | JSON       | root:root                | 0644 | Agent machine: the relay key pinned for agent `<label>`                                                                                                                                                                                    |
-| `/opt/lamalibre/apps/<route>/`                                     | directory  | root:root                | 0755 | Agent machine: an agent half's installed versions                                                                                                                                                                                          |
-| `/var/lib/lamalibre/apps/<route>/`                                 | directory  | lamaste-app-\<route\>    | 0700 | Agent machine: an agent half's data                                                                                                                                                                                                        |
-| `/etc/lamalibre/apps/<route>/plugin-config.json`                   | JSON       | lamaste-app-\<route\>    | 0600 | Agent machine: an agent half's port and installation secret                                                                                                                                                                                |
-| `/etc/systemd/system/lamalibre-app-<route>.service`                | systemd    | root:root                | 0644 | Agent machine: an agent half's unit                                                                                                                                                                                                        |
-| `/etc/systemd/system/lamalibre-app-<route>.socket`                 | systemd    | root:root                | 0644 | Agent machine: the socket unit holding an agent half's port                                                                                                                                                                                |
+| File                                                               | Format     | Owner                    | Mode | Purpose                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------ | ---------- | ------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/etc/lamalibre/lamaste/panel.json`                                | JSON       | lamaste:lamaste          | 0600 | Panel server configuration                                                                                                                                                                                                                                                                                                                                           |
+| `/etc/lamalibre/lamaste/tunnels.json`                              | JSON       | lamaste:lamaste          | 0600 | Tunnel definitions                                                                                                                                                                                                                                                                                                                                                   |
+| `/etc/lamalibre/lamaste/sites.json`                                | JSON       | lamaste:lamaste          | 0600 | Static site definitions                                                                                                                                                                                                                                                                                                                                              |
+| `/etc/lamalibre/lamaste/chisel-credentials.json`                   | JSON       | lamaste:lamaste          | 0600 | Per-agent Chisel credentials (source of truth for the authfile)                                                                                                                                                                                                                                                                                                      |
+| `/etc/lamalibre/lamaste/chisel-users`                              | JSON       | lamaste:lamaste-chisel   | 0640 | Chisel `--authfile`: per-agent credentials and port grants (rendered)                                                                                                                                                                                                                                                                                                |
+| `/etc/lamalibre/lamaste/chisel-sentinel`                           | text       | lamaste:lamaste          | 0600 | Password of the `lamaste-no-grants` sentinel user                                                                                                                                                                                                                                                                                                                    |
+| `/etc/lamalibre/lamaste/chisel-server.key`                         | PEM        | lamaste:lamaste-chisel   | 0640 | Chisel SSH host key (`--keyfile`), generated by the panel at onboarding                                                                                                                                                                                                                                                                                              |
+| `/etc/authelia/configuration.yml`                                  | YAML       | lamaste:lamaste-authelia | 0640 | Authelia server configuration                                                                                                                                                                                                                                                                                                                                        |
+| `/etc/authelia/users.yml`                                          | YAML       | lamaste:lamaste-authelia | 0660 | User database (Authelia rewrites it on a password change)                                                                                                                                                                                                                                                                                                            |
+| `/etc/authelia/.secrets.json`                                      | JSON       | lamaste:lamaste-authelia | 0600 | Authelia secrets (panel only)                                                                                                                                                                                                                                                                                                                                        |
+| `/etc/authelia/oidc-issuer.pem`                                    | PEM        | lamaste-authelia         | 0600 | RSA-4096 key Authelia signs OIDC tokens with, written by `create-lamaste`; the panel cannot read it                                                                                                                                                                                                                                                                  |
+| `/etc/lamalibre/lamaste/registry-credential.json`                  | JSON       | lamaste:lamaste          | 0600 | The panel's registry (Feria) credential: a pasted token, or the `lamaste-server` OIDC client                                                                                                                                                                                                                                                                         |
+| `/etc/lamalibre/lamaste/oidc-clients.json`                         | JSON       | lamaste:lamaste          | 0600 | Plaintext secrets (and pbkdf2 salts) of confidential OIDC clients                                                                                                                                                                                                                                                                                                    |
+| `/etc/lamalibre/lamaste/relay-signing-key.json`                    | JSON       | lamaste:lamaste          | 0600 | Ed25519 key relay assertions (panel, Gatekeeper) and agents' app jobs (panel) are signed with                                                                                                                                                                                                                                                                        |
+| `/etc/lamalibre/lamaste/push-install-config.json`                  | JSON       | lamaste:lamaste          | 0600 | Push install: the switch, the policies, the default policy                                                                                                                                                                                                                                                                                                           |
+| `/etc/lamalibre/lamaste/push-install-sessions.json`                | JSON       | lamaste:lamaste          | 0600 | Push install log (last 500 pushes)                                                                                                                                                                                                                                                                                                                                   |
+| `/etc/lamalibre/lamaste/ticket-scopes.json`                        | JSON       | lamaste:lamaste          | 0600 | Ticket scope registry                                                                                                                                                                                                                                                                                                                                                |
+| `/etc/lamalibre/lamaste/tickets.json`                              | JSON       | lamaste:lamaste          | 0600 | Ticket and session store                                                                                                                                                                                                                                                                                                                                             |
+| `/etc/lamalibre/lamaste/invitations.json`                          | JSON       | lamaste:lamaste          | 0600 | Pending user invitations                                                                                                                                                                                                                                                                                                                                             |
+| `/etc/lamalibre/lamaste/plugins.json`                              | JSON       | lamaste:lamaste          | 0600 | Plugin registry (before 4.2; the registry is now in `state.db`)                                                                                                                                                                                                                                                                                                      |
+| `/etc/lamalibre/lamaste/state.db`                                  | SQLite     | lamaste:lamaste          | 0600 | Plugins (with their hooks), agents, tickets, enrollment tokens, the audit log, notifications, relay hook approvals, plugin operations, agent jobs, the cache of agent-hosted plugins' settings (never a secret), each agent's last contact, the user directory (each user's `userId`, tombstones, the `directoryId`), plugin audiences and the identity feed's state |
+| `/etc/lamalibre/lamaste/plugin-hostings.json`                      | JSON       | lamaste:lamaste          | 0600 | Hostings of agent-hosted plugins: agent, port, phase, installation secrets, health                                                                                                                                                                                                                                                                                   |
+| `/opt/lamalibre/lamaste/hooks/<route>/`                            | directory  | root:root                | 0755 | A plugin's approved relay hook module (`<sha256>.mjs`, 0644) and `runner.env`, written by `lamaste-priv`                                                                                                                                                                                                                                                             |
+| `/etc/lamalibre/lamaste/storage-config.json`                       | JSON       | lamaste:lamaste          | 0600 | Storage server registry and plugin bindings (credentials AES-256-GCM encrypted)                                                                                                                                                                                                                                                                                      |
+| `/etc/lamalibre/lamaste/storage-master.key`                        | Binary     | lamaste:lamaste          | 0600 | 32-byte master key for storage credential encryption                                                                                                                                                                                                                                                                                                                 |
+| `/etc/lamalibre/lamaste/gatekeeper.db`                             | SQLite     | lamaste:lamaste          | 0600 | Gatekeeper: Lamaste groups and members, access grants (plugin entitlements included), the denied-access log                                                                                                                                                                                                                                                          |
+| `/etc/lamalibre/lamaste/gatekeeper.json`                           | JSON       | lamaste:lamaste          | 0600 | Gatekeeper settings (cache TTL, admin contact, logging)                                                                                                                                                                                                                                                                                                              |
+| `/etc/lamalibre/lamaste/pki/enrollment-tokens.json`                | JSON       | lamaste:lamaste          | 0600 | One-time enrollment tokens for hardware-bound enrollment                                                                                                                                                                                                                                                                                                             |
+| `/etc/lamalibre/lamaste/pki/revoked.json`                          | JSON       | lamaste:lamaste          | 0600 | Revoked certificate serial numbers                                                                                                                                                                                                                                                                                                                                   |
+| `/etc/lamalibre/lamaste/pki/agents/registry.json`                  | JSON       | lamaste:lamaste          | 0600 | Agent certificate metadata                                                                                                                                                                                                                                                                                                                                           |
+| `/etc/nginx/sites-available/lamalibre-lamaste-*`                   | nginx conf | root:root                | 0644 | Vhost configurations (the panel's are installed by `lamaste-priv`)                                                                                                                                                                                                                                                                                                   |
+| `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`                  | nginx conf | root:root                | 0644 | mTLS snippet                                                                                                                                                                                                                                                                                                                                                         |
+| `/etc/nginx/snippets/lamalibre-lamaste-authz-cache.conf`           | nginx conf | root:root                | 0644 | Gatekeeper proxy_cache zone                                                                                                                                                                                                                                                                                                                                          |
+| `/etc/nginx/conf.d/lamalibre-lamaste-backend-cookie.conf`          | nginx conf | root:root                | 0644 | http-level map defining `$lamaste_backend_cookie` — the browser's cookies without `authelia_session`, which every tunnel and agent-panel vhost sends its backend; written by `create-lamaste` (install and redeploy)                                                                                                                                                 |
+| `/etc/systemd/system/lamalibre-lamaste-gatekeeper.service`         | systemd    | root:root                | 0644 | Gatekeeper systemd unit                                                                                                                                                                                                                                                                                                                                              |
+| `/etc/systemd/system/chisel.service`                               | systemd    | root:root                | 0644 | Chisel unit, written by `create-lamaste`                                                                                                                                                                                                                                                                                                                             |
+| `/etc/systemd/system/authelia.service`                             | systemd    | root:root                | 0644 | Authelia unit, written by `create-lamaste`                                                                                                                                                                                                                                                                                                                           |
+| `/etc/systemd/system/lamalibre-lamaste-hooks@.socket`, `@.service` | systemd    | root:root                | 0644 | Relay hook runner (one instance per plugin with relay hooks), written by `create-lamaste`                                                                                                                                                                                                                                                                            |
+| `~/.lamalibre/lamaste/servers.json`                                | JSON       | user                     | 0600 | Desktop app server registry                                                                                                                                                                                                                                                                                                                                          |
+| `~/.lamalibre/lamaste/agents.json`                                 | JSON       | user                     | 0600 | Multi-agent registry                                                                                                                                                                                                                                                                                                                                                 |
+| `~/.lamalibre/lamaste/agentd.token`                                | JSON       | user                     | 0600 | Bearer token of lamaste-agentd's owner (the desktop app, scripts run as the user)                                                                                                                                                                                                                                                                                    |
+| `~/.lamalibre/lamaste/agents/<label>/config.json`                  | JSON       | user                     | 0600 | Per-agent configuration                                                                                                                                                                                                                                                                                                                                              |
+| `~/.lamalibre/lamaste/agents/<label>/client.p12`                   | PKCS#12    | user                     | 0600 | Per-agent mTLS certificate                                                                                                                                                                                                                                                                                                                                           |
+| `~/.lamalibre/lamaste/agents/<label>/ca.crt`                       | PEM        | user                     | 0644 | Per-agent CA certificate                                                                                                                                                                                                                                                                                                                                             |
+| `~/.lamalibre/lamaste/agents/<label>/chisel.json`                  | JSON       | user                     | 0600 | Per-agent Chisel credential (source of truth for the service)                                                                                                                                                                                                                                                                                                        |
+| `~/.lamalibre/lamaste/agents/<label>/chisel.env`                   | env file   | user                     | 0600 | Linux only: `AUTH=` for the systemd unit's `EnvironmentFile=`                                                                                                                                                                                                                                                                                                        |
+| `~/.lamalibre/lamaste/agents/<label>/`                             | directory  | user                     | 0700 | Per-agent data directory                                                                                                                                                                                                                                                                                                                                             |
+| `~/.lamalibre/lamaste/agents/<label>/sync-state.json`              | JSON       | user                     | 0600 | Outcome of the last `lamaste-agent sync`                                                                                                                                                                                                                                                                                                                             |
+| `~/.lamalibre/lamaste/agents/<label>/app-plugins/<route>.json`     | JSON       | user                     | 0600 | Port and installation secret of a plugin hosted on this agent                                                                                                                                                                                                                                                                                                        |
+| `~/.lamalibre/lamaste/agents/<label>/app-plugin-tunnel-state.json` | JSON       | user                     | 0600 | The tunnel state last delivered to each hosted plugin's agent half                                                                                                                                                                                                                                                                                                   |
+| `~/.lamalibre/lamaste/agents/<label>/apphost-state.json`           | JSON       | user                     | 0600 | The agent halves the app host helper installed for this agent                                                                                                                                                                                                                                                                                                        |
+| `~/.lamalibre/lamaste/agents/<label>/host-facts.json`              | JSON       | user                     | 0600 | What the agent last reported about its host, and the helper's last answer                                                                                                                                                                                                                                                                                            |
+| `~/.lamalibre/lamaste/agents/<label>/app-job-results.json`         | JSON       | user                     | 0600 | App job results the relay has not taken yet                                                                                                                                                                                                                                                                                                                          |
+| `~/.lamalibre/lamaste/agents/<label>/logs/`                        | directory  | user                     | 0700 | Per-agent Chisel and sync log files                                                                                                                                                                                                                                                                                                                                  |
+| `~/.lamalibre/lamaste/agent.json`                                  | JSON       | user                     | 0600 | Legacy single-server config                                                                                                                                                                                                                                                                                                                                          |
+| `/usr/local/sbin/lamaste-apphost`                                  | Node.js    | root:root                | 0755 | Agent machine: the app host helper — see [Agent machine: the app host](#agent-machine-the-app-host)                                                                                                                                                                                                                                                                  |
+| `/etc/sudoers.d/lamaste-apphost`                                   | sudoers    | root:root                | 0440 | Agent machine: lets the agent's user run the helper                                                                                                                                                                                                                                                                                                                  |
+| `/etc/lamalibre/apphost/relays/<label>.json`                       | JSON       | root:root                | 0644 | Agent machine: the relay key pinned for agent `<label>`                                                                                                                                                                                                                                                                                                              |
+| `/opt/lamalibre/apps/<route>/`                                     | directory  | root:root                | 0755 | Agent machine: an agent half's installed versions                                                                                                                                                                                                                                                                                                                    |
+| `/var/lib/lamalibre/apps/<route>/`                                 | directory  | lamaste-app-\<route\>    | 0700 | Agent machine: an agent half's data                                                                                                                                                                                                                                                                                                                                  |
+| `/etc/lamalibre/apps/<route>/plugin-config.json`                   | JSON       | lamaste-app-\<route\>    | 0600 | Agent machine: an agent half's port and installation secret                                                                                                                                                                                                                                                                                                          |
+| `/etc/systemd/system/lamalibre-app-<route>.service`                | systemd    | root:root                | 0644 | Agent machine: an agent half's unit                                                                                                                                                                                                                                                                                                                                  |
+| `/etc/systemd/system/lamalibre-app-<route>.socket`                 | systemd    | root:root                | 0644 | Agent machine: the socket unit holding an agent half's port                                                                                                                                                                                                                                                                                                          |
 
 ---
 
@@ -246,20 +245,24 @@ Stores the array of static sites hosted through Lamaste.
 
 **Schema:** Array of site objects.
 
-| Field               | Type                  | Description                                                                                                                 |
-| ------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `id`                | string                | UUID                                                                                                                        |
-| `name`              | string                | Site name (the subdomain for managed sites)                                                                                 |
-| `fqdn`              | string                | Full domain (e.g., `blog.example.com`)                                                                                      |
-| `type`              | string                | `"managed"` (subdomain of the Lamaste domain) or `"custom"` (your own domain)                                               |
-| `spaMode`           | boolean               | If true, `try_files` falls back to `/index.html`                                                                            |
-| `autheliaProtected` | boolean               | If true, requires Authelia authentication                                                                                   |
-| `allowedUsers`      | string[]              | Authelia users allowed when protected (empty: all authenticated users)                                                      |
-| `dnsVerified`       | boolean               | DNS verified (always `true` for managed sites)                                                                              |
-| `certIssued`        | boolean               | TLS certificate issued and vhost live                                                                                       |
-| `aliases`           | string[] \| undefined | Custom sites only: hostnames answered with a 301 to `https://<fqdn>`. One certificate lineage named after `fqdn` covers all |
-| `rootPath`          | string                | Document root (e.g., `/var/www/lamaste/<id>/`)                                                                              |
-| `createdAt`         | string                | ISO 8601 timestamp                                                                                                          |
+| Field               | Type                  | Description                                                                                                                                                                                                    |
+| ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | string                | UUID                                                                                                                                                                                                           |
+| `name`              | string                | Site name (the subdomain for managed sites)                                                                                                                                                                    |
+| `fqdn`              | string                | Full domain (e.g., `blog.example.com`)                                                                                                                                                                         |
+| `type`              | string                | `"managed"` (subdomain of the Lamaste domain) or `"custom"` (your own domain)                                                                                                                                  |
+| `spaMode`           | boolean               | If true, `try_files` falls back to `/index.html`                                                                                                                                                               |
+| `autheliaProtected` | boolean               | If true, requires Authelia authentication                                                                                                                                                                      |
+| `allowedUsers`      | string[]              | Authelia users allowed when protected (empty: all authenticated users)                                                                                                                                         |
+| `dnsVerified`       | boolean               | DNS verified (always `true` for managed sites)                                                                                                                                                                 |
+| `certIssued`        | boolean               | TLS certificate issued and vhost live                                                                                                                                                                          |
+| `aliases`           | string[] \| undefined | Custom sites only: hostnames answered with a 301 to `https://<fqdn>`. One certificate lineage named after `fqdn` covers all                                                                                    |
+| `rootPath`          | string                | Document root (e.g., `/var/www/lamaste/<id>/`)                                                                                                                                                                 |
+| `createdAt`         | string                | ISO 8601 timestamp                                                                                                                                                                                             |
+| `owner`             | object \| undefined   | `{ plugin: <route> }` — a plugin's [web surface](../04-api-reference/agent-hosted-plugins.md#web-surface); its `rootPath` is `/var/www/lamaste/apps/<route>/current` and only the plugin's workflows change it |
+| `accessMode`        | string \| undefined   | A plugin-owned site's: `"authenticated"` or `"restricted"` (a `site` grant in Gatekeeper)                                                                                                                      |
+
+Gatekeeper reads this file too (the hosts of plugins' user surfaces). Every change runs under the panel's sites lock.
 
 **Example:**
 
@@ -457,92 +460,17 @@ Stores active tickets and sessions for agent-to-agent authorization. Created aut
 
 ---
 
-## `/etc/lamalibre/lamaste/groups.json`
+## `/etc/lamalibre/lamaste/gatekeeper.db`
 
-Stores Lamaste group definitions and membership. Separate from Authelia groups — Lamaste groups are used exclusively for Gatekeeper access control without modifying `users.yml`.
+Gatekeeper's SQLite store (WAL; 0600 with its `-wal` and `-shm` files; numbered migrations in `packages/sdks/gatekeeper/src/lib/migrations/gatekeeper/`): Lamaste groups, access grants and the access-request log. Gatekeeper reads it on every authorization check and writes it through its own API — the panel reaches that API through `/api/gatekeeper/*` and its own Gatekeeper client, never by opening the file. The JSON files of earlier versions (`groups.json`, `access-grants.json`, `access-request-log.json`) are no longer read; the installer still creates empty `groups.json` and `access-grants.json`.
 
-**Schema:**
-
-| Field                  | Type     | Description                                             |
-| ---------------------- | -------- | ------------------------------------------------------- |
-| `groups`               | array    | Array of group objects                                  |
-| `groups[].name`        | string   | Group name (unique, lowercase alphanumeric, 2-63 chars) |
-| `groups[].description` | string   | Human-readable description                              |
-| `groups[].members`     | string[] | Array of Authelia usernames                             |
-| `groups[].createdAt`   | string   | ISO 8601 timestamp                                      |
-| `groups[].createdBy`   | string   | Admin who created the group                             |
-
-**Example:**
-
-```json
-{
-  "groups": [
-    {
-      "name": "developers",
-      "description": "Backend and frontend developers",
-      "members": ["alice", "bob"],
-      "createdAt": "2026-04-01T10:00:00.000Z",
-      "createdBy": "admin"
-    }
-  ]
-}
-```
-
-**Write pattern:** Atomic — temp file, `fsync()`, `rename()`. Concurrency controlled by promise-chain mutex.
-
----
-
-## `/etc/lamalibre/lamaste/access-grants.json`
-
-Stores generic access grants mapping principals (users or groups) to resources (tunnel subdomains or other protected endpoints).
-
-**Schema:**
-
-| Field                    | Type           | Description                                     |
-| ------------------------ | -------------- | ----------------------------------------------- |
-| `grants`                 | array          | Array of grant objects                          |
-| `grants[].grantId`       | string         | Unique identifier (e.g., `g_abc123`)            |
-| `grants[].principalType` | string         | `"user"` or `"group"`                           |
-| `grants[].principalId`   | string         | Authelia username or Lamaste group name         |
-| `grants[].resourceType`  | string         | `"tunnel"`, `"plugin"`, or custom resource type |
-| `grants[].resourceId`    | string         | Resource identifier (e.g., tunnel subdomain)    |
-| `grants[].context`       | object         | Optional metadata (empty `{}` by default)       |
-| `grants[].used`          | boolean        | Whether the grant has been consumed             |
-| `grants[].createdAt`     | string         | ISO 8601 timestamp                              |
-| `grants[].usedAt`        | string \| null | ISO 8601 timestamp of consumption, or `null`    |
-
-**Example:**
-
-```json
-{
-  "grants": [
-    {
-      "grantId": "g_b2c3d4e5",
-      "principalType": "user",
-      "principalId": "alice",
-      "resourceType": "tunnel",
-      "resourceId": "myapp",
-      "context": {},
-      "used": false,
-      "createdAt": "2026-04-01T10:05:00.000Z",
-      "usedAt": null
-    },
-    {
-      "grantId": "g_c3d4e5f6",
-      "principalType": "group",
-      "principalId": "developers",
-      "resourceType": "tunnel",
-      "resourceId": "staging",
-      "context": {},
-      "used": false,
-      "createdAt": "2026-04-01T10:10:00.000Z",
-      "usedAt": null
-    }
-  ]
-}
-```
+| Table                | Columns                                                                                                                                                                                                                                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `groups`             | `name` (PK; 2–63 chars, lowercase alphanumeric and `-`), `description`, `members` (JSON array of usernames), `created_at`, `created_by` — at most 200 groups                                                                                                                                               |
+| `access_grants`      | `grant_id` (UUID), `principal_type` (`user` \| `group`), `principal_id`, `resource_type` (`tunnel`, `plugin`, …), `resource_id`, `context` (JSON object — `{ "roles": [...] }` on an agent-hosted plugin's entitlement), `used`, `created_at`, `used_at` — at most 1000 grants, consumed ones kept 90 days |
+| `access_request_log` | `timestamp`, `username`, `resource_type`, `resource_id`, `resource_fqdn` — denied attempts, when `accessLoggingEnabled` is on                                                                                                                                                                              |
 
-**Write pattern:** Atomic — temp file, `fsync()`, `rename()`. Concurrency controlled by promise-chain mutex.
+Removing a user principal (`POST /api/principals/user/remove { username }`, the panel's call when a user is removed or created under a username a removed user held) deletes their grants and their membership of every group in one transaction; erasing a removed user deletes their access-request log rows from before their removal.
 
 ---
 
@@ -579,38 +507,6 @@ Gatekeeper service settings. Controls cache behavior, admin contact information
 
 ---
 
-## `/etc/lamalibre/lamaste/access-request-log.json`
-
-Optional log of denied access attempts. Written by the Gatekeeper when `accessLoggingEnabled` is true. Read by the Panel Server for the admin UI access request review page.
-
-**Schema:** Array of access request entries.
-
-| Field          | Type   | Description                                  |
-| -------------- | ------ | -------------------------------------------- |
-| `timestamp`    | string | ISO 8601 timestamp of the denied request     |
-| `username`     | string | Authelia username of the denied user         |
-| `resourceType` | string | Resource type (e.g., `"tunnel"`, `"plugin"`) |
-| `resourceId`   | string | Resource identifier (e.g., tunnel subdomain) |
-| `resourceFqdn` | string | Full domain the user attempted to access     |
-
-**Example:**
-
-```json
-[
-  {
-    "timestamp": "2026-04-01T14:30:00.000Z",
-    "username": "charlie",
-    "resourceType": "tunnel",
-    "resourceId": "internal",
-    "resourceFqdn": "internal.example.com"
-  }
-]
-```
-
-**Write pattern:** Atomic — temp file, `fsync()`, `rename()`.
-
----
-
 ## `/etc/authelia/configuration.yml`
 
 Authelia server configuration. Written during onboarding provisioning.
@@ -926,7 +822,7 @@ Service files use per-agent names:
 - macOS: `com.lamalibre.lamaste.chisel-<label>` (plist label), `~/Library/LaunchAgents/com.lamalibre.lamaste.chisel-<label>.plist` — mode 0600, because it carries `AUTH` in `EnvironmentVariables`
 - Linux: `lamalibre-lamaste-chisel-<label>` (unit name), `~/.config/systemd/user/lamalibre-lamaste-chisel-<label>.service` — a systemd **user** unit with `EnvironmentFile=` pointing at `chisel.env`; enable lingering (`sudo loginctl enable-linger <user>`) for it to start at boot without a login
 
-Both run `chisel client --max-retry-interval 30s https://tunnel.<domain>:443 R:127.0.0.1:<port>:127.0.0.1:<port> ...` with TLS verification and no credential in argv. They are generated by `@lamalibre/lamaste@4.4.1/agent` (`chisel-service.ts`) and rewritten by `lamaste-agent setup`, `update` and `sync` — do not edit them by hand. An agent carrying no tunnels has its service unloaded (Chisel cannot run without a remote).
+Both run `chisel client --max-retry-interval 30s https://tunnel.<domain>:443 R:127.0.0.1:<port>:127.0.0.1:<port> ...` with TLS verification and no credential in argv. They are generated by `@lamalibre/lamaste@4.6.0/agent` (`chisel-service.ts`) and rewritten by `lamaste-agent setup`, `update` and `sync` — do not edit them by hand. An agent carrying no tunnels has its service unloaded (Chisel cannot run without a remote).
 
 The sync timer, which runs `<node> <installed lamaste-agent> sync --label <label> --quiet` (`<node>` is a stable path such as `/opt/homebrew/bin/node` when one on `PATH` resolves to the running binary, so a Node.js upgrade does not break it):
 
@@ -1127,6 +1023,12 @@ This cache zone is available for nginx-level caching of Gatekeeper authorization
 
 ---
 
+## `/etc/nginx/conf.d/lamalibre-lamaste-backend-cookie.conf`
+
+The http-level map every location proxying to a tunnel or agent backend sets `Cookie` from (`proxy_set_header Cookie $lamaste_backend_cookie;`): the browser's cookies with every `authelia_session` pair removed, at most four, and no `Cookie` at all when one is still there. Rendered by core `renderBackendCookieMap()` from the session cookie name Authelia is configured with, written root-owned 0644 by `create-lamaste` on install and as the first step of every redeploy (`nginx -t`, previous file restored on failure), removed by `lamaste-server uninstall`. Not edited by hand: a redeploy rewrites it. See [nginx Configuration](../03-architecture/nginx-configuration.md#the-backend-cookie-map).
+
+---
+
 ## `/etc/systemd/system/lamalibre-lamaste-gatekeeper.service`
 
 Systemd unit for the Gatekeeper tunnel authorization service. Runs as the `lamaste` user on `127.0.0.1:9294`.
@@ -1179,10 +1081,8 @@ WantedBy=multi-user.target
 | `/etc/lamalibre/lamaste/plugins.json`                                                               | lamaste:lamaste                   | 0600 | Plugin registry                                           |
 | `/etc/lamalibre/lamaste/storage-config.json`                                                        | lamaste:lamaste                   | 0600 | Storage registry                                          |
 | `/etc/lamalibre/lamaste/storage-master.key`                                                         | lamaste:lamaste                   | 0600 | Storage encryption key                                    |
-| `/etc/lamalibre/lamaste/groups.json`                                                                | lamaste:lamaste                   | 0600 | Lamaste groups                                            |
-| `/etc/lamalibre/lamaste/access-grants.json`                                                         | lamaste:lamaste                   | 0600 | Access grants                                             |
+| `/etc/lamalibre/lamaste/gatekeeper.db`                                                              | lamaste:lamaste                   | 0600 | Gatekeeper groups, grants, access log                     |
 | `/etc/lamalibre/lamaste/gatekeeper.json`                                                            | lamaste:lamaste                   | 0600 | Gatekeeper settings                                       |
-| `/etc/lamalibre/lamaste/access-request-log.json`                                                    | lamaste:lamaste                   | 0600 | Denied access log                                         |
 | `/etc/lamalibre/lamaste/pki/enrollment-tokens.json`                                                 | lamaste:lamaste                   | 0600 | Enrollment tokens                                         |
 | `/etc/lamalibre/lamaste/pki/revoked.json`                                                           | lamaste:lamaste                   | 0600 | Revocation list                                           |
 | `/etc/lamalibre/lamaste/pki/agents/registry.json`                                                   | lamaste:lamaste                   | 0600 | Agent cert metadata                                       |
@@ -1232,10 +1132,8 @@ WantedBy=multi-user.target
 | `ticket-scopes.json`         | lamalibre-lamaste-serverd | lamalibre-lamaste-serverd (atomic write + mutex)               | No                                                                        |
 | `tickets.json`               | lamalibre-lamaste-serverd | lamalibre-lamaste-serverd (atomic write + mutex)               | No                                                                        |
 | `storage-config.json`        | lamalibre-lamaste-serverd | lamalibre-lamaste-serverd (atomic write + mutex)               | No                                                                        |
-| `groups.json`                | gatekeeper                | lamalibre-lamaste-serverd (atomic write + mutex)               | No (gatekeeper watches file)                                              |
-| `access-grants.json`         | gatekeeper                | lamalibre-lamaste-serverd (atomic write + mutex)               | No (gatekeeper watches file)                                              |
+| `gatekeeper.db`              | gatekeeper                | gatekeeper (its API; the panel through it)                     | No (read on every check)                                                  |
 | `gatekeeper.json`            | gatekeeper                | lamalibre-lamaste-serverd (atomic write)                       | Yes (`systemctl restart lamalibre-lamaste-gatekeeper`)                    |
-| `access-request-log.json`    | lamalibre-lamaste-serverd | gatekeeper (atomic write)                                      | No                                                                        |
 | `configuration.yml`          | authelia                  | onboarding provisioning                                        | Yes (`systemctl restart authelia`)                                        |
 | `users.yml`                  | authelia                  | lamalibre-lamaste-serverd (atomic rename, no sudo)             | Yes (`systemctl restart authelia`)                                        |
 | `lamalibre-lamaste-*` vhosts | nginx                     | lamalibre-lamaste-serverd (via `sudo lamaste-priv nginx-site`) | Yes (`nginx -t && systemctl reload nginx`)                                |