@lamalibre/create-lamaste 4.4.0 → 4.5.0

package/src/tasks/nginx.js

@@ -1,7 +1,9 @@
 import { execa } from 'execa';
 import { writeFile, unlink } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { ensureBackendCookieMap } from '../lib/backend-cookie.js';
 import { ensureHttpRedirect } from '../lib/http-redirect.js';
+import { IP_PANEL_SITE, generateIpPanelVhost } from '../lib/ip-panel-vhost.js';
 
 /**
  * nginx IP-based mTLS configuration subtasks.
@@ -63,140 +65,10 @@ ssl_verify_client optional;
     {
       title: 'Writing IP-based panel vhost',
       task: async (_ctx, subtask) => {
-        const vhostConfig = `# Rate limit zone for public enrollment endpoint (5 requests/minute per IP)
-limit_req_zone $binary_remote_addr zone=enroll:1m rate=5r/m;
+        const vhostPath = `/etc/nginx/sites-available/${IP_PANEL_SITE}`;
+        await writeFile(vhostPath, generateIpPanelVhost(pkiDir));
 
-map $http_upgrade $connection_upgrade {
-    default upgrade;
-    ''      close;
-}
-
-server {
-    listen 9292 ssl;
-    server_name _;
-
-    ssl_certificate ${pkiDir}/self-signed.pem;
-    ssl_certificate_key ${pkiDir}/self-signed-key.pem;
-
-    include /etc/nginx/snippets/lamalibre-lamaste-mtls.conf;
-
-    # SSL settings
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_ciphers HIGH:!aNULL:!MD5;
-    ssl_prefer_server_ciphers on;
-
-    # Show certificate help page when client cert is missing or invalid
-    error_page 495 496 /cert-help.html;
-    location = /cert-help.html {
-        root /opt/lamalibre/lamaste/lamaste-server-ui;
-        internal;
-    }
-
-    # Proxy to serverd (mTLS required — reject if cert missing or invalid)
-    location / {
-        if ($ssl_client_verify != SUCCESS) {
-            return 496;
-        }
-        proxy_pass http://127.0.0.1:3100;
-
-        # Client cert headers — set from nginx TLS variables, never passed through from client
-        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
-        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
-        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
-
-        # Strip Authelia identity headers — not trusted on mTLS vhost
-        proxy_set_header Remote-User "";
-        proxy_set_header Remote-Groups "";
-        proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
-
-        # Standard proxy headers
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Public API paths (no mTLS verification check).
-    # ssl_verify_client is 'optional' at server level, so TLS handshake
-    # succeeds without a cert. These locations skip the $ssl_client_verify
-    # check and clear cert headers so the backend sees no client identity.
-    location /api/enroll {
-        limit_req zone=enroll burst=5 nodelay;
-        proxy_pass http://127.0.0.1:3100;
-        proxy_http_version 1.1;
-
-        # Clear cert headers so the backend sees no client cert
-        proxy_set_header X-SSL-Client-Verify "";
-        proxy_set_header X-SSL-Client-DN "";
-        proxy_set_header X-SSL-Client-Serial "";
-
-        # Strip Authelia identity headers — not trusted on public endpoint
-        proxy_set_header Remote-User "";
-        proxy_set_header Remote-Groups "";
-        proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
-
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    location /api/invite {
-        proxy_pass http://127.0.0.1:3100;
-        proxy_http_version 1.1;
-
-        proxy_set_header X-SSL-Client-Verify "";
-        proxy_set_header X-SSL-Client-DN "";
-        proxy_set_header X-SSL-Client-Serial "";
-
-        # Strip Authelia identity headers — not trusted on public endpoint
-        proxy_set_header Remote-User "";
-        proxy_set_header Remote-Groups "";
-        proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
-
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # API paths with WebSocket upgrade support (mTLS required)
-    location /api {
-        if ($ssl_client_verify != SUCCESS) {
-            return 496;
-        }
-        proxy_pass http://127.0.0.1:3100;
-        proxy_http_version 1.1;
-
-        # Client cert headers — set from nginx TLS variables, never passed through from client
-        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
-        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
-        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
-
-        # Strip Authelia identity headers — not trusted on mTLS vhost
-        proxy_set_header Remote-User "";
-        proxy_set_header Remote-Groups "";
-        proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
-
-        # Standard proxy headers
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        # WebSocket: only upgrade when client requests it
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-    }
-}
-`;
-        await writeFile('/etc/nginx/sites-available/lamalibre-lamaste-panel-ip', vhostConfig);
-
-        subtask.output = 'Vhost written to /etc/nginx/sites-available/lamalibre-lamaste-panel-ip';
+        subtask.output = `Vhost written to ${vhostPath}`;
       },
       rendererOptions: { persistentOutput: true },
     },
@@ -206,8 +78,8 @@ server {
         // Create symlink
         await execa('ln', [
           '-sf',
-          '/etc/nginx/sites-available/lamalibre-lamaste-panel-ip',
-          '/etc/nginx/sites-enabled/lamalibre-lamaste-panel-ip',
+          `/etc/nginx/sites-available/${IP_PANEL_SITE}`,
+          `/etc/nginx/sites-enabled/${IP_PANEL_SITE}`,
         ]);
 
         // Remove only the default site from sites-enabled (preserve other existing sites)
@@ -221,6 +93,17 @@ server {
       },
       rendererOptions: { persistentOutput: true },
     },
+    {
+      title: "Keeping Authelia's session cookie from tunnel backends",
+      task: async (_ctx, subtask) => {
+        // Before the panel writes its first tunnel vhost, each of which sets
+        // the backend's Cookie from this map's variable. nginx is
+        // (re)started by the last task; no reload here.
+        await ensureBackendCookieMap({ reload: false });
+        subtask.output = 'nginx map installed: backends never receive the authelia_session cookie';
+      },
+      rendererOptions: { persistentOutput: true },
+    },
     {
       title: 'Redirecting plain HTTP to HTTPS',
       task: async (_ctx, subtask) => {

package/src/tasks/redeploy.js

@@ -7,7 +7,9 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { generateServiceUnit, generateSudoersContent } from '../lib/service-config.js';
 import { lookupId } from '../lib/accounts.js';
+import { ensureBackendCookieMap } from '../lib/backend-cookie.js';
 import { ensureHttpRedirect } from '../lib/http-redirect.js';
+import { refreshIpPanelVhost } from '../lib/ip-panel-vhost.js';
 import { generateCertHelpPage } from '../lib/cert-help-page.js';
 import { ensureRootOwnedInstallDir, removeTree, writeFileNoFollow } from '../lib/ownership.js';
 import { provisionRelayServices } from '../lib/relay-services.js';
@@ -67,7 +69,13 @@ async function getLatestNpmVersion() {
  * self-update (`lamaste-priv self-update`). Updates the panel, CLI, UI, docs
  * and gatekeeper; installs the pinned chisel and Authelia releases, their
  * units, the sudoers rules and the programs they name; restarts what
- * changed. Does not touch OS hardening, mTLS certs or the panel's vhosts.
+ * changed. Does not touch OS hardening or mTLS certs. Of the panel's
+ * vhosts it refreshes only the IP-based one, which it installed and the
+ * panel cannot write (its text; the panel's 2FA owns its link) — the panel
+ * reconciles the others itself when it starts. Before anything else
+ * changes, it installs the nginx map those vhosts take the backends'
+ * `Cookie` from (Authelia's session cookie stripped): a relay whose nginx
+ * refuses it stops here, with the running panel untouched.
  *
  * Runs as root and may be started by a compromised panel, so it never
  * writes through a path the lamaste user controls (see lib/ownership.js).
@@ -96,6 +104,21 @@ export function redeployTasks(ctx, task) {
       },
       rendererOptions: { persistentOutput: true },
     },
+    {
+      title: "Keeping Authelia's session cookie from tunnel backends",
+      task: async (_ctx, subtask) => {
+        // First, while the running panel is untouched: the panel this
+        // redeploy starts renders every tunnel and agent-panel vhost with
+        // `proxy_set_header Cookie $lamaste_backend_cookie;`, which nginx
+        // refuses without the map. Fatal — a relay whose nginx rejects it
+        // keeps the version it runs.
+        const { changed } = await ensureBackendCookieMap();
+        subtask.output = changed
+          ? 'nginx map installed: backends never receive the authelia_session cookie'
+          : 'nginx map already in place';
+      },
+      rendererOptions: { persistentOutput: true },
+    },
     {
       title: 'Stopping panel services',
       task: async (_ctx, subtask) => {
@@ -393,6 +416,21 @@ export function redeployTasks(ctx, task) {
       },
       rendererOptions: { persistentOutput: true },
     },
+    {
+      title: 'Refreshing the IP panel vhost',
+      task: async (_ctx, subtask) => {
+        // Not fatal: the panel keeps working on the vhost it had.
+        try {
+          const { changed } = await refreshIpPanelVhost(ctx.pkiDir);
+          subtask.output = changed
+            ? 'IP panel vhost brought up to date'
+            : 'IP panel vhost already up to date (or not installed)';
+        } catch (err) {
+          subtask.skip(`Skipped — ${err.message}`);
+        }
+      },
+      rendererOptions: { persistentOutput: true },
+    },
     {
       title: 'Reloading systemd and restarting panel',
       task: async (_ctx, subtask) => {

package/vendor/docs/00-introduction/how-it-works.md

@@ -55,14 +55,14 @@ SSH into a fresh Ubuntu droplet and run one command:
 
 ```bash
 apt install -y npm
-npx @lamalibre/create-lamaste@4.4.0
+npx @lamalibre/create-lamaste@4.5.0
 ```
 
 This installs everything the relay needs: nginx, Node.js, firewall rules, certificates, and the management panel. At the end, it prints a client certificate file and password. You download the certificate, import it into your browser, and disconnect SSH. You never SSH in again.
 
 **Option B: Desktop app (cloud provisioning)**
 
-Install the desktop app (`npx @lamalibre/create-lamaste-desktop@4.4.0`) and use the Servers tab to create a DigitalOcean droplet. The app handles everything — droplet creation, Lamaste installation, certificate download, and connection — without you ever touching SSH. Cloud API tokens are stored in your OS credential store (macOS Keychain or Linux libsecret), never in plaintext. See the [Cloud Provisioning guide](../02-guides/cloud-provisioning.md) for a step-by-step walkthrough.
+Install the desktop app (`npx @lamalibre/create-lamaste-desktop@4.5.0`) and use the Servers tab to create a DigitalOcean droplet. The app handles everything — droplet creation, Lamaste installation, certificate download, and connection — without you ever touching SSH. Cloud API tokens are stored in your OS credential store (macOS Keychain or Linux libsecret), never in plaintext. See the [Cloud Provisioning guide](../02-guides/cloud-provisioning.md) for a step-by-step walkthrough.
 
 **Phase 2: Onboarding (10 minutes, browser)**
 

package/vendor/docs/00-introduction/quickstart.md

@@ -59,7 +59,7 @@ Once connected:
 
 ```bash
 apt install -y npm
-npx @lamalibre/create-lamaste@4.4.0
+npx @lamalibre/create-lamaste@4.5.0
 ```
 
 The installer displays a confirmation banner showing what it will do:
@@ -253,7 +253,7 @@ Every tunnel is carried by one **agent** — the machine that runs the app. Enro
 Install the Lamaste Desktop app, which provides a GUI with automatic service discovery and one-click tunnel creation:
 
 ```bash
-npx @lamalibre/create-lamaste-desktop@4.4.0
+npx @lamalibre/create-lamaste-desktop@4.5.0
 ```
 
 The app auto-detects local services (Ollama, ComfyUI, PostgreSQL, Docker containers, etc.) and lets you expose them with one click. See the [Desktop App Setup](../02-guides/desktop-app-setup.md) guide for details.
@@ -263,7 +263,7 @@ The app auto-detects local services (Ollama, ComfyUI, PostgreSQL, Docker contain
 In the panel, go to **Certificates → Enrollment Token** and create a token for a label such as `laptop`. Then, on the machine that runs your app, install the agent globally and run setup:
 
 ```bash
-npm install -g @lamalibre/lamaste-agent@4.4.0
+npm install -g @lamalibre/lamaste-agent@4.5.0
 LAMALIBRE_LAMASTE_ENROLLMENT_TOKEN=<token> \
   lamaste-agent setup --label laptop --panel-url https://203.0.113.42:9292
 ```
@@ -345,7 +345,7 @@ Your Mac                          DigitalOcean Droplet            Internet
 The installer accepts optional flags:
 
 ```bash
-npx @lamalibre/create-lamaste@4.4.0 [flags]
+npx @lamalibre/create-lamaste@4.5.0 [flags]
 ```
 
 | Flag            | Effect                                          |
@@ -435,7 +435,7 @@ In development mode (`NODE_ENV=development` or `NODE_ENV` unset), the panel serv
 # 2. SSH in and install
 ssh root@203.0.113.42
 apt install -y npm
-npx @lamalibre/create-lamaste@4.4.0
+npx @lamalibre/create-lamaste@4.5.0
 
 # 3. Download cert (from your local machine)
 scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .

package/vendor/docs/00-introduction/what-is-lamaste.md

@@ -36,7 +36,7 @@ Lamaste solves the problem of exposing local services to the internet securely.
 **Option A: Manual setup (SSH)**
 
 1. Create a fresh Ubuntu 24.04 droplet on DigitalOcean
-2. SSH in once and run `npx @lamalibre/create-lamaste@4.4.0`
+2. SSH in once and run `npx @lamalibre/create-lamaste@4.5.0`
 3. Download the client certificate it prints
 4. Import the certificate into your browser
 5. Open `https://<droplet-ip>:9292` — you are in the admin panel
@@ -46,7 +46,7 @@ Lamaste solves the problem of exposing local services to the internet securely.
 
 **Option B: Desktop app cloud provisioning**
 
-1. Install the desktop app (`npx @lamalibre/create-lamaste-desktop@4.4.0`)
+1. Install the desktop app (`npx @lamalibre/create-lamaste-desktop@4.5.0`)
 2. Go to the Servers tab and click "Create a new server"
 3. Enter your DigitalOcean API token — the app validates scopes and stores it securely in your OS credential store
 4. Pick a region (the app measures latency to each) and a domain name
@@ -93,14 +93,14 @@ All backend services bind `127.0.0.1` only — nginx is the sole public-facing s
 
 State is stored in JSON files (`/etc/lamalibre/lamaste/panel.json`, `tunnels.json`) with atomic writes (write to temp → fsync → rename). No database is needed at this scale.
 
-The installer (`npx @lamalibre/create-lamaste@4.4.0`) is completely non-interactive — it detects the environment, provisions everything, and prints a summary. All configuration happens through the browser-based onboarding wizard after installation.
+The installer (`npx @lamalibre/create-lamaste@4.5.0`) is completely non-interactive — it detects the environment, provisions everything, and prints a summary. All configuration happens through the browser-based onboarding wizard after installation.
 
 ## Quick Reference
 
 | Item                 | Value                           |
 | -------------------- | ------------------------------- |
 | **Minimum VPS**      | 512MB RAM, Ubuntu 24.04         |
-| **Install command**  | `npx @lamalibre/create-lamaste@4.4.0` |
+| **Install command**  | `npx @lamalibre/create-lamaste@4.5.0` |
 | **Admin panel**      | `https://<ip>:9292` (mTLS)      |
 | **Auth for admin**   | Client certificate (zero-login) |
 | **Auth for apps**    | TOTP 2FA via Authelia           |
@@ -108,5 +108,5 @@ The installer (`npx @lamalibre/create-lamaste@4.4.0`) is completely non-interact
 | **TLS certificates** | Let's Encrypt (auto-renewing)   |
 | **State storage**    | JSON files (no database)        |
 | **RAM usage**        | ~245MB total (all services)     |
-| **npm package**      | `@lamalibre/create-lamaste@4.4.0`     |
+| **npm package**      | `@lamalibre/create-lamaste@4.5.0`     |
 | **License**          | Polyform Noncommercial 1.0.0    |

package/vendor/docs/01-concepts/authentication.md

@@ -362,7 +362,7 @@ export async function writeUsers(usersData) {
 
 The `writeAutheliaFile` helper writes a random temp file in `/etc/authelia/`, `fsync`s it and renames it over the target. Since a rename on the same filesystem is atomic at the kernel level, Authelia never sees a half-written file. No sudo is involved: `/etc/authelia` belongs to the panel's `lamaste` user with group `lamaste-authelia` and the setgid bit, so new files belong to Authelia's group. Authelia itself runs as the unprivileged `lamaste-authelia` account, not root.
 
-Storing a user's TOTP secret is the one Authelia operation the panel cannot do itself — the secret lives in Authelia's database, which is that account's file. The panel runs `sudo lamaste-priv authelia-totp <username>` with the secret on stdin (never on a command line), and the root helper runs `authelia storage user totp generate` as `lamaste-authelia`.
+What lives in Authelia's database — that account's file — the panel cannot touch itself. Storing a user's TOTP secret: the panel runs `sudo lamaste-priv authelia-totp <username>` with the secret on stdin (never on a command line), and the root helper runs `authelia storage user totp generate` as `lamaste-authelia`. Deleting a removed user's second factors: `lamaste-priv authelia-user purge-second-factors <username>` (`authelia storage user totp delete` and `webauthn delete --all`). Telling whether a username has an OpenID Connect identity — an opaque identifier Authelia gave a relying party, which it cannot delete, so the username is never given to a new user: `lamaste-priv authelia-user has-oidc-identifier <username>` (the identifiers exported as `lamaste-authelia` into a `/run` directory only that account and root can enter, read, overwritten and removed; it prints `yes` or `no` and nothing else). See [Users API — Reused usernames](../04-api-reference/users.md#reused-usernames).
 
 ### Secrets management
 

package/vendor/docs/01-concepts/authorization.md

@@ -30,7 +30,7 @@ Lamaste has two separate group systems that serve different purposes:
 | `internal` | Internal team members                      |
 | `external` | External collaborators, clients, or guests |
 
-**Lamaste groups** are access-control groups stored in `groups.json` and managed through the Gatekeeper dashboard. These are project-oriented groups that describe what a user can access:
+**Lamaste groups** are access-control groups stored in Gatekeeper's database (`gatekeeper.db`) and managed through the Gatekeeper dashboard. These are project-oriented groups that describe what a user can access:
 
 | Example group  | Members           |
 | -------------- | ----------------- |
@@ -56,6 +56,17 @@ When a group is the principal, the grant expands to all members of that group at
 
 Grants are not tunnel-specific. The resource model is generic: each grant has a resource type (e.g., `tunnel`, `plugin`) and a resource identifier. This means the same grant system works for tunnels, plugins, and any future resource types.
 
+### Plugin roles (entitlements)
+
+An agent-hosted plugin that declares `identity` has roles of its own — `viewer`, `editor`, whatever its manifest names. A grant on such a plugin (`resourceType: "plugin"`, `resourceId: <route>`) whose `context.roles` lists some of them is an **entitlement**: the user — or every member of the group — holds those roles in the plugin. The panel checks the roles against the plugin's manifest, keeps each plugin's **audience** (who holds which role) and sends it to the plugin's agent half, and on every request a user makes to the plugin's user surface tells the agent half who is calling, with which roles. A plugin grant without roles never makes anyone a plugin user. Manage entitlements from the plugin's **People** panel on the Plugins page, or `lamaste-server plugins entitlements` — see [Agent-Hosted Plugins](../04-api-reference/agent-hosted-plugins.md#users-and-identity).
+
+### Who attests what
+
+Gatekeeper authenticates the Authelia session; it does not tell applications who the user is. For a plain app tunnel nginx sets `Remote-User`, `Remote-Groups`, `Remote-Name` and `Remote-Email` from Gatekeeper's answer — replacing what the client sent, but **unsigned**: anything else that reaches the backend's loopback port can send them too. Signed identity exists in two places:
+
+- **Plugin tunnels** (`type: 'plugin'`, into an agent's lamaste-agentd): Gatekeeper signs a relay assertion for the agent with the session's user ([Security Model](security-model.md#5c-the-agent-daemon-lamaste-agentd-and-relay-assertions)).
+- **Plugin user surfaces** (`/api/<route>/app/*` on a host bound to an agent-hosted plugin): Gatekeeper **attests the session** — a relay assertion for the panel naming the username alone, bound to the method and the raw request path — and the **panel issues the identity** the application sees: the directory's `userId`, the username and the user's roles in the plugin, in the caller assertion it signs for the agent half ([Security Model](security-model.md#5f-users-of-agent-hosted-plugins-who-attests-what)).
+
 ### Access modes for tunnels
 
 Each tunnel can be configured with one of three access modes:
@@ -89,7 +100,7 @@ From the Gatekeeper dashboard in the admin panel:
 
 ### How changes take effect
 
-Gatekeeper watches its state files (`groups.json`, `access-grants.json`) for changes. When you create a group, add a member, or create a grant through the admin panel, the change takes effect immediately — no service restart required.
+Gatekeeper reads groups and grants from its SQLite database (`gatekeeper.db`) on every check, so a group, member or grant created through the admin panel takes effect on the next request — no service restart required. The tunnel list (the panel's `tunnels.json`) and Gatekeeper's settings (`gatekeeper.json`) are watched and reloaded when they change. Changes through the panel also recompute the audiences of agent-hosted plugins at once; edits made with Gatekeeper's own CLI are picked up by the panel within a minute.
 
 ## For Developers
 
@@ -105,22 +116,30 @@ The request flow for a restricted tunnel:
    (127.0.0.1:9294/authz/tunnel/staging.example.com) with
    - X-Original-URL https://staging.example.com<request URI> and
      Host staging.example.com — the vhost's own hostname, from its configuration
-   - X-Original-Method and the visitor's Cookie header
+   - X-Original-Method, X-Forwarded-For (the visitor's address, as nginx
+     accepted it) and the visitor's Cookie header
 3. Gatekeeper takes the tunnel named in the path (X-Original-URL and Host
-   must agree) and validates the Authelia session cookie with Authelia for
-   that URL:
+   must agree), takes the visitor's authelia_session cookie — refusing a
+   request with more than one — and validates it with Authelia for that
+   URL, sending Authelia that cookie alone:
    a. No valid session -> 401 -> nginx redirects to
       auth.example.com/?rd=https://staging.example.com<request URI>
-   b. Valid session -> the user (cached, see Session caching)
+   b. Valid session -> the user (cached per session and host, see Session caching)
 4. Gatekeeper checks for a matching grant:
    a. Grant exists (user or group match) -> 200 with Remote-User, Remote-Groups,
       Remote-Name and Remote-Email
-   b. No grant -> 403 with access request HTML page
-5. On 200 nginx proxies to the tunnel backend with those identity headers
+   b. No grant -> 403 with access request HTML page (logged with the tunnel
+      and the reason, never the username)
+5. On 200 nginx proxies to the tunnel backend with those identity headers —
+   and the visitor's cookies without authelia_session
 ```
 
+The backend never receives Authelia's session cookie: nginx sets its `Cookie` from a map that removes every `authelia_session` pair, or sends none when it cannot ([nginx Configuration](../03-architecture/nginx-configuration.md#the-backend-cookie-map)). Gatekeeper's authorization routes are rate-limited per visitor address and tunnel host (6000 a minute each): nginx is their only caller and sets `X-Forwarded-For` to the visitor's address, which Gatekeeper trusts from `127.0.0.1` only, so one visitor exhausting its bucket leaves every other visitor theirs.
+
 Public tunnel vhosts have no `auth_request`. For authenticated tunnels Gatekeeper answers 200 for any valid session without looking for a grant.
 
+A tunnel bound as an agent-hosted plugin's user surface has a second subrequest for `/api/<route>/app*` — `/authz/user-surface/<fqdn>` — where Gatekeeper checks that the tunnel's agent hosts the plugin (it carries the plugin's internal tunnel, as `tunnels.json` records it), the session (and, on a restricted tunnel, the grant) as above, then answers with a single-use relay assertion for the panel instead of `Remote-*` headers, and a missing session with a JSON 401 instead of a login redirect ([Gatekeeper API](../04-api-reference/gatekeeper.md#user-surface-authorization-nginx-auth-request)).
+
 ### Which tunnel is authorized
 
 Gatekeeper authorizes the tunnel the vhost names, never one the client names. nginx selects the vhost from the request line when a request is in absolute form (`GET https://staging.example.com/ HTTP/1.1`) and from `Host` otherwise, so a client can send the request line of one tunnel with the `Host` header of another. Vhosts written before 4.3 called `/authz/check` with `X-Original-URL` and `Host` built from the client's `Host` header (`$http_host`): an Authelia user allowed on any tunnel — and every user is allowed on an `authenticated` one — reached any `restricted` tunnel, app or plugin, by naming the allowed tunnel in `Host`, without a grant, and Authelia evaluated that other URL as well.
@@ -138,7 +157,7 @@ The grant model is generic, not tunnel-specific:
   principalId: 'alice',          // username or group name
   resourceType: 'tunnel',        // 'tunnel', 'plugin', or custom
   resourceId: 'staging-app',     // resource identifier
-  context: {},                   // optional metadata
+  context: {},                   // optional metadata; { roles: [...] } on a plugin entitlement
   used: false,                   // whether grant has been consumed
   createdAt: '2026-04-01T...',
   usedAt: null                   // consumption timestamp, or null
@@ -158,24 +177,17 @@ Authorization checks happen on every request to a restricted tunnel. A page load
 
 Gatekeeper uses an in-memory session cache to solve this:
 
-**Gatekeeper in-memory session cache.** When Gatekeeper receives a request, it extracts the user identity from the Authelia session. Validated sessions are cached in memory for 30 seconds (configurable via `sessionCacheTtlMs` in `gatekeeper.json`), keyed by the session cookie value. This means repeated Gatekeeper calls for the same session do not re-validate against Authelia.
+**Gatekeeper in-memory session cache.** When Gatekeeper receives a request, it extracts the user identity from the Authelia session. Validated sessions are cached in memory for 30 seconds (configurable via `sessionCacheTtlMs` in `gatekeeper.json`), keyed by the session cookie value **and the tunnel host** (an HMAC under a per-process key). Repeated Gatekeeper calls for the same session on the same host do not re-validate against Authelia; on another host they do — Authelia decides per host (a static site's or plugin tunnel's rules name users), so a session it accepted for one host proves nothing on another.
 
 > **Note:** The installer also writes an nginx `proxy_cache_path` snippet (`/etc/nginx/snippets/lamalibre-lamaste-authz-cache.conf`) for optional nginx-level caching, but the generated vhosts do not currently include `proxy_cache` directives. All authorization caching relies on the Gatekeeper's in-memory session cache.
 
-**Effect:** On a warm cache, repeated subrequests for the same session are resolved from the in-memory cache without re-validating against Authelia. The 30-second default TTL ensures that revoked grants and expired sessions take effect within half a minute.
-
-### File watching
-
-Gatekeeper watches its state files using `fs.watch`:
+**Effect:** On a warm cache, repeated subrequests for the same session are resolved from the in-memory cache without re-validating against Authelia. Grants and groups are read on every check, so a revoked grant takes effect at once; the session itself — a user disabled or deleted in Authelia, a session that expired — is noticed within the 30-second TTL. (A plugin's user surface does not wait for it: the panel refuses a disabled or removed user on the next request.)
 
-| File                 | Contains                         |
-| -------------------- | -------------------------------- |
-| `groups.json`        | Lamaste groups and their members |
-| `access-grants.json` | All grants (user and group)      |
+### State and change propagation
 
-When a file changes, Gatekeeper reloads its in-memory state and invalidates the session cache. This means changes made through the admin panel API (which writes to these files atomically) take effect immediately without restarting the Gatekeeper service.
+Groups, grants and the access-request log live in Gatekeeper's SQLite database, `/etc/lamalibre/lamaste/gatekeeper.db` (0600 with its WAL and SHM files; numbered migrations under `src/lib/migrations/gatekeeper/`). Every check reads it, and every write through Gatekeeper's API runs under the groups and grants locks and invalidates the session cache. Gatekeeper watches two JSON files with `fs.watch` (on their parent directory, since they are replaced by rename): the panel's `tunnels.json` — tunnels, access modes, plugin targets and user-surface bindings — and its own settings, `gatekeeper.json`.
 
-State files use the same atomic write pattern as the rest of Lamaste (temp file with `O_EXCL` + mode `0600` -> `fsync` -> rename).
+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`. The legacy `user-plugin-access.json` grants are not migrated into Gatekeeper (`migrateFromLegacy` exists but nothing calls it): they stay where the desktop's user-access flow reads them, and never make anyone a plugin user.
 
 ### Access request page generation
 
@@ -190,37 +202,43 @@ The HTML is self-contained (inline CSS, no external dependencies) so it renders
 
 ### State files
 
-| File                                        | Purpose                    | Format |
-| ------------------------------------------- | -------------------------- | ------ |
-| `/etc/lamalibre/lamaste/groups.json`        | Lamaste groups and members | JSON   |
-| `/etc/lamalibre/lamaste/access-grants.json` | All grants                 | JSON   |
+| File                                                        | Purpose                                                     | Format |
+| ----------------------------------------------------------- | ----------------------------------------------------------- | ------ |
+| `/etc/lamalibre/lamaste/gatekeeper.db`                      | Groups and members, grants, the access-request log          | SQLite |
+| `/etc/lamalibre/lamaste/gatekeeper.json`                    | Settings                                                    | JSON   |
+| `/etc/lamalibre/lamaste/gatekeeper-secret.json`             | The secret the panel calls Gatekeeper's management API with | JSON   |
+| `/etc/lamalibre/lamaste/tunnels.json` (read only)           | The panel's tunnels and their user-surface bindings         | JSON   |
+| `/etc/lamalibre/lamaste/relay-signing-key.json` (read only) | The relay signing key Gatekeeper signs assertions with      | JSON   |
 
 ### Source files
 
-| File                                                                 | Purpose                                               |
-| -------------------------------------------------------------------- | ----------------------------------------------------- |
-| `packages/lamaste-gatekeeper/src/server/index.ts`                    | Fastify server setup, file watching                   |
-| `packages/lamaste-gatekeeper/src/server/routes/authz.ts`             | Authorization check endpoint (nginx auth_request)     |
-| `packages/lamaste-gatekeeper/src/server/routes/grants.ts`            | Grant CRUD API                                        |
-| `packages/lamaste-gatekeeper/src/server/routes/groups.ts`            | Group CRUD API                                        |
-| `packages/lamaste-gatekeeper/src/server/routes/access-request.ts`    | Access request submission and listing                 |
-| `packages/lamaste-gatekeeper/src/lib/authz.ts`                       | Authorization logic (grant matching, group expansion) |
-| `packages/lamaste-gatekeeper/src/lib/grants.ts`                      | Grant storage and atomic writes                       |
-| `packages/lamaste-gatekeeper/src/lib/groups.ts`                      | Group storage and atomic writes                       |
-| `packages/lamaste-gatekeeper/src/lib/templates.ts`                   | Access request HTML page generation                   |
-| `packages/lamaste-serverd/src/routes/management/gatekeeper-proxy.js` | Admin panel proxy to Gatekeeper API                   |
-| `packages/lamaste-serverd/src/lib/nginx.js`                          | Vhost generation with Gatekeeper auth_request block   |
+| File                                                               | Purpose                                                    |
+| ------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `packages/sdks/gatekeeper/src/server/index.ts`                     | Fastify server setup, file watching                        |
+| `packages/sdks/gatekeeper/src/server/routes/authz.ts`              | Tunnel and user-surface authorization (nginx auth_request) |
+| `packages/sdks/gatekeeper/src/server/routes/grants.ts`             | Grant CRUD API                                             |
+| `packages/sdks/gatekeeper/src/server/routes/groups.ts`             | Group CRUD API                                             |
+| `packages/sdks/gatekeeper/src/server/routes/principals.ts`         | Removing a user principal everywhere                       |
+| `packages/sdks/gatekeeper/src/server/routes/diagnostic.ts`         | Access check, settings, cache bust, access-request log     |
+| `packages/sdks/gatekeeper/src/server/routes/access-request.ts`     | Access request submission and listing                      |
+| `packages/sdks/gatekeeper/src/lib/authz.ts`                        | Authorization logic (grant matching, group expansion)      |
+| `packages/sdks/gatekeeper/src/lib/state-db.ts`                     | `gatekeeper.db` and its migrations                         |
+| `packages/sdks/gatekeeper/src/lib/grants.ts`, `groups.ts`          | Grant and group storage                                    |
+| `packages/sdks/gatekeeper/src/lib/tunnels.ts`                      | What Gatekeeper reads of `tunnels.json`                    |
+| `packages/sdks/gatekeeper/src/lib/templates.ts`                    | Access request HTML page generation                        |
+| `packages/server/daemon/src/routes/management/gatekeeper-proxy.js` | Admin panel proxy to Gatekeeper API (role grants checked)  |
+| `packages/server/daemon/src/lib/nginx.js`                          | Vhost generation with Gatekeeper auth_request blocks       |
 
 ## Quick Reference
 
 ### Service
 
-| Property    | Value                                                            |
-| ----------- | ---------------------------------------------------------------- |
-| Listen      | `127.0.0.1:9294`                                                 |
-| Runtime     | Fastify (TypeScript)                                             |
-| State files | `groups.json`, `access-grants.json` in `/etc/lamalibre/lamaste/` |
-| RAM usage   | Minimal (in-process)                                             |
+| Property  | Value                                                                    |
+| --------- | ------------------------------------------------------------------------ |
+| Listen    | `127.0.0.1:9294`                                                         |
+| Runtime   | Fastify (TypeScript)                                                     |
+| State     | `gatekeeper.db` (SQLite), `gatekeeper.json` in `/etc/lamalibre/lamaste/` |
+| RAM usage | Minimal (in-process)                                                     |
 
 ### Access modes
 
@@ -232,16 +250,16 @@ The HTML is self-contained (inline CSS, no external dependencies) so it renders
 
 ### Cache TTLs
 
-| Layer                        | TTL | Key                  |
-| ---------------------------- | --- | -------------------- |
-| Gatekeeper in-memory session | 30s | Session cookie value |
+| Layer                        | TTL | Key                                  |
+| ---------------------------- | --- | ------------------------------------ |
+| Gatekeeper in-memory session | 30s | Session cookie value and tunnel host |
 
 ### Group comparison
 
 | Property    | Authelia groups                  | Lamaste groups                         |
 | ----------- | -------------------------------- | -------------------------------------- |
 | Purpose     | Identity classification          | Access control                         |
-| Storage     | `users.yml`                      | `groups.json`                          |
+| Storage     | `users.yml`                      | `gatekeeper.db`                        |
 | Managed by  | Authelia (via panel Users page)  | Gatekeeper (via panel Gatekeeper page) |
 | Examples    | `admins`, `internal`, `external` | `developers`, `design-team`            |
 | Granularity | Broad (who you are)              | Fine (what you access)                 |

package/vendor/docs/01-concepts/certificates.md

@@ -29,7 +29,7 @@ For the IP-based admin panel (`https://<ip>:9292`), there is no domain to verify
 
 ### When certificates are issued
 
-- **Self-signed + mTLS certs** — created during `npx @lamalibre/create-lamaste@4.4.0` installation
+- **Self-signed + mTLS certs** — created during `npx @lamalibre/create-lamaste@4.5.0` installation
 - **Core Let's Encrypt certs** — issued during onboarding for `panel`, `auth`, and `tunnel` subdomains
 - **App Let's Encrypt certs** — issued when you create a new tunnel or a managed static site
 - **Custom-domain site certs** — issued when a custom-domain site's DNS is verified: one certificate lineage, named after the site's domain, covering the domain and every redirect alias (re-issued when aliases change)
@@ -82,7 +82,7 @@ The most critical scenario is the mTLS CA expiring, but it has a 10-year validit
 
 ### Let's Encrypt implementation
 
-Lamaste uses certbot with the nginx plugin for certificate issuance. The implementation lives in `@lamalibre/lamaste@4.4.0/server` (`packages/core/lib/src/server/certbot.ts`), wrapped by `packages/server/daemon/src/lib/certbot.js`.
+Lamaste uses certbot with the nginx plugin for certificate issuance. The implementation lives in `@lamalibre/lamaste@4.5.0/server` (`packages/core/lib/src/server/certbot.ts`), wrapped by `packages/server/daemon/src/lib/certbot.js`.
 
 The panel runs as the unprivileged `lamaste` user and never runs `certbot` or `openssl` on Let's Encrypt files directly. It calls two root-owned wrapper scripts through sudo:
 
@@ -193,7 +193,7 @@ This three-step check prevents unnecessary certificate issuance and respects rat
 
 #### Custom-domain site certificate issuance
 
-A custom-domain static site may have redirect aliases (e.g. `www.myblog.net`). `issueSiteCert(fqdn, aliases, email)` in `@lamalibre/lamaste@4.4.0/server` keeps them on **one** lineage named after the primary domain:
+A custom-domain static site may have redirect aliases (e.g. `www.myblog.net`). `issueSiteCert(fqdn, aliases, email)` in `@lamalibre/lamaste@4.5.0/server` keeps them on **one** lineage named after the primary domain:
 
 ```bash
 sudo /usr/local/sbin/lamaste-certbot issue admin@example.com myblog.net myblog.net www.myblog.net

package/vendor/docs/01-concepts/mtls.md

@@ -25,7 +25,7 @@ You encounter mTLS during two moments:
 
 ### Importing the certificate
 
-After running `npx @lamalibre/create-lamaste@4.4.0`, the installer prints something like:
+After running `npx @lamalibre/create-lamaste@4.5.0`, the installer prints something like:
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -101,7 +101,7 @@ When connecting a machine to Lamaste using `lamaste-agent`, you should **not** u
 2. Click "Generate" and enter a label (e.g., `macbook-pro`)
 3. Save the displayed password — it cannot be retrieved later
 4. Download the `.p12` file
-5. Share the `.p12` file and password with the agent machine through a secure channel, then install the agent there (`npm install -g @lamalibre/lamaste-agent@4.4.0`) and run `lamaste-agent setup` (an enrollment token avoids moving the key at all — see [Agent Setup](../02-guides/agent-setup.md))
+5. Share the `.p12` file and password with the agent machine through a secure channel, then install the agent there (`npm install -g @lamalibre/lamaste-agent@4.5.0`) and run `lamaste-agent setup` (an enrollment token avoids moving the key at all — see [Agent Setup](../02-guides/agent-setup.md))
 
 Agent certificates have capability-based access. By default, a new agent can only read tunnel configuration. Admins can grant additional capabilities per-agent from the panel UI: