@lamalibre/create-lamaste 4.5.0 → 4.7.0

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

@@ -19,10 +19,10 @@ If onboarding is not complete, all endpoints return `503 Service Unavailable`.
 ## Important Behavior
 
 - **Password hashing:** Passwords are hashed with bcrypt (not argon2id — argon2id uses ~93MB per hash and causes OOM kills on a 512MB droplet).
-- **Authelia restart:** After every user change that modifies `users.yml` (create, update, delete), Authelia is restarted via `systemctl restart authelia` to pick up the changes. If the restart fails, the operation still succeeds — the failure is logged and listed in the response's `warnings`. Note: TOTP reset does **not** restart Authelia — it writes directly to Authelia's SQLite database via the `authelia storage user totp generate` CLI command, which takes effect immediately.
+- **No Authelia restart:** Authelia watches `users.yml` (`authentication_backend.file.watch: true`) and re-reads a user's details at each of their requests, so a user change (create, update, disable, delete) applies without a restart and without ending anyone else's session: a disabled or deleted user's session ends at their next request. Authelia skips a reload within 0.5 s of its previous one, so the panel writes the file once more 0.6 s after its last write — the change is always picked up. TOTP reset writes directly to Authelia's SQLite database via the `authelia storage user totp generate` CLI command, which takes effect immediately.
 - **Atomic writes:** The `users.yml` file is written atomically (write to temp file, then rename) to prevent Authelia from reading a partially written file.
-- **One lock for every user write:** creating, updating, disabling and deleting users, and accepting an invitation, are read-modify-writes of `users.yml` under one lock in the panel. Under the same lock the panel brings the directory in line with the file **before** Authelia restarts — so a disabled user is refused by plugins at once — [offboards](#offboarding) every user that stopped being one, then restarts Authelia, then recomputes the plugins' audiences. Concurrent user changes therefore run one after the other.
-- **A change must stick:** Authelia's own password reset rewrites `users.yml` from what Authelia read when it started, so a change written just before its restart can be lost. After the restart the panel reads `users.yml` again and checks that it holds the change (the fields set, the user created or gone); when it does not, the change is made once more (and Authelia restarted again). When it still does not, the answer carries `"ok": false`, `"persisted": false` and a `persist` warning — never a silent success.
+- **One lock for every user write:** creating, updating, disabling and deleting users, and accepting an invitation, are read-modify-writes of `users.yml` under one lock in the panel. Under the same lock the panel brings the directory in line with the file — so a disabled user is refused by plugins at once — [offboards](#offboarding) every user that stopped being one, renders who may reach each domain, drops Gatekeeper's cached sessions, then recomputes the plugins' audiences. Concurrent user changes therefore run one after the other.
+- **A change must stick:** Authelia's own password reset rewrites `users.yml` from what it holds in memory, so a change written in the instant before can be lost. The panel reads `users.yml` again and checks that it holds the change (the fields set, the user created or gone); when it does not, the change is made once more. When it still does not, the answer carries `"ok": false`, `"persisted": false` and a `persist` warning — never a silent success.
 - **The directory follows `users.yml`, read only:** at start, after onboarding and every minute the panel reconciles the directory with the file without writing it (Authelia's own password reset rewrites it; an operator may edit it): an unknown username gets a new `userId`, a changed display name, email or `disabled` is adopted, and a username gone from the file — seen missing in two reads, so a half-written file never tombstones anyone — is removed as `deleted-outside`. A user the reconcile sees disabled or removed is offboarded exactly as one disabled or deleted through the API. Every change is audited (`directory.user.created`, `.updated`, `.removed`) by `userId` alone; audit entries never name a user.
 - **Audit:** besides the directory's own entries, the users API records `user.password.set` (a password set through `PUT`), `user.groups.changed` (`added`, `removed` group names) and `user.totp.reset` — each by `userId` alone.
 - **Last user protection:** You cannot delete the last remaining user. At least one user must always exist.
@@ -75,10 +75,11 @@ curl -s --cert client.p12:password \
 | `username`    | `string`         | Unique login identifier                                                                                                                  |
 | `displayname` | `string`         | Human-readable display name                                                                                                              |
 | `email`       | `string`         | User's email address                                                                                                                     |
-| `groups`      | `string[]`       | Authelia group memberships                                                                                                               |
+| `groups`      | `string[]`       | Authelia group memberships an administrator assigned — never the groups Lamaste owns ([Domains](#domains))                               |
 | `disabled`    | `boolean`        | Authelia's `disabled: true` — the user cannot sign in                                                                                    |
 | `userId`      | `string \| null` | The user's directory id; `null` until the directory has seen the user (within a minute of an edit of `users.yml` made outside the panel) |
 | `status`      | `string`         | `active` or `disabled`                                                                                                                   |
+| `domains`     | `object[]`       | Domain memberships, `{ name, kind }` — `kind` `member` or `external` ([Domains](#domains))                                               |
 
 Users deleted from `users.yml` are not listed here; the [directory](#get-api-identity-directory) keeps their tombstones.
 
@@ -106,13 +107,14 @@ Creates a new Authelia user. The password is hashed with bcrypt before being sto
 }
 ```
 
-| Field         | Type       | Validation                                                                                  | Description                                 |
-| ------------- | ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `username`    | `string`   | 2-32 chars, lowercase alphanumeric + underscores + hyphens, starting with a letter or digit | Login identifier                            |
-| `displayname` | `string`   | 1-100 chars                                                                                 | Display name                                |
-| `email`       | `string`   | Valid email format                                                                          | Email address                               |
-| `password`    | `string`   | 8-128 chars                                                                                 | Plain-text password (hashed before storage) |
-| `groups`      | `string[]` | Optional, defaults to `[]`                                                                  | Authelia group memberships                  |
+| Field         | Type       | Validation                                                                                      | Description                                                                                |
+| ------------- | ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `username`    | `string`   | 2-32 chars, lowercase alphanumeric + underscores + hyphens, starting with a letter or digit     | Login identifier                                                                           |
+| `displayname` | `string`   | 1-100 chars                                                                                     | Display name                                                                               |
+| `email`       | `string`   | Valid email format                                                                              | Email address                                                                              |
+| `password`    | `string`   | 8-128 chars                                                                                     | Plain-text password (hashed before storage)                                                |
+| `groups`      | `string[]` | Optional, defaults to `[]`                                                                      | Authelia group memberships                                                                 |
+| `domains`     | array      | Names or `{ name, kind }`, at most 50; required once the relay has two (400 `domains_required`) | Memberships ([Domains](#domains)); with one domain, a member of it unless named `external` |
 
 **Username regex** (the same rule applies to invitations — a leading `-` would read as a flag to Authelia's CLI, which the panel runs per username for TOTP secrets, second factors and OpenID Connect identities):
 
@@ -145,7 +147,7 @@ curl -s --cert client.p12:password \
 }
 ```
 
-A new user gets a new `userId`, even when an earlier, deleted user had the same username. Before the new user is created ([Reused usernames](#reused-usernames)): the username is refused when Authelia holds an OpenID Connect identity for it; and when a deleted user held it, Gatekeeper drops everything it holds under the username (grants, group memberships) and Authelia the second factors (TOTP, WebAuthn) — always, not only when a cleanup was pending — so a reused username inherits no grant, group, role or second factor. `warnings` (`[{ step, message }]`) lists what went wrong after `users.yml` was written — the directory not updated, Authelia not restarted; a change that did not stick answers `200` with `"ok": false`, `"persisted": false`.
+A new user gets a new `userId`, even when an earlier, deleted user had the same username. Before the new user is created ([Reused usernames](#reused-usernames)): the username is refused when Authelia holds an OpenID Connect identity for it; and when a deleted user held it, Gatekeeper drops everything it holds under the username (grants, group memberships) and Authelia the second factors (TOTP, WebAuthn) — always, not only when a cleanup was pending — so a reused username inherits no grant, group, role or second factor. `warnings` (`[{ step, message }]`) lists what went wrong after `users.yml` was written — the directory not updated, domain access not rendered; a change that did not stick answers `200` with `"ok": false`, `"persisted": false`.
 
 **Errors:**
 
@@ -179,13 +181,14 @@ If a new password is provided, it is hashed with bcrypt before storage.
 }
 ```
 
-| Field         | Type       | Validation            | Description                                                                 |
-| ------------- | ---------- | --------------------- | --------------------------------------------------------------------------- |
-| `displayname` | `string`   | 1-100 chars, optional | New display name                                                            |
-| `email`       | `string`   | Valid email, optional | New email address                                                           |
-| `password`    | `string`   | 8-128 chars, optional | New password (hashed before storage)                                        |
-| `groups`      | `string[]` | Optional              | New group memberships (replaces entire list)                                |
-| `disabled`    | `boolean`  | Optional              | `true` disables the user, `false` enables them ([below](#disabling-a-user)) |
+| Field         | Type       | Validation            | Description                                                                       |
+| ------------- | ---------- | --------------------- | --------------------------------------------------------------------------------- |
+| `displayname` | `string`   | 1-100 chars, optional | New display name                                                                  |
+| `email`       | `string`   | Valid email, optional | New email address                                                                 |
+| `password`    | `string`   | 8-128 chars, optional | New password (hashed before storage)                                              |
+| `groups`      | `string[]` | Optional              | New group memberships (replaces entire list; Lamaste's own groups are kept)       |
+| `domains`     | array      | Optional              | Memberships afterwards, exactly — names or `{ name, kind }` ([Domains](#domains)) |
+| `disabled`    | `boolean`  | Optional              | `true` disables the user, `false` enables them ([below](#disabling-a-user))       |
 
 All fields are optional, but at least one must be provided (validated by a Zod `.refine()`).
 
@@ -214,11 +217,11 @@ curl -s --cert client.p12:password \
 }
 ```
 
-`warnings` lists what did not happen after the write (the directory, Authelia's restart, the steps of [offboarding](#offboarding)); `"ok": false` with `"persisted": false` and a `persist` warning says the change did not stick ([above](#important-behavior)). A change of `groups` revokes the user's registry (Feria) tokens, whose scopes were granted from `feria-*` groups at login.
+`warnings` lists what did not happen after the write (the directory, rendering domain access, the steps of [offboarding](#offboarding)); `"ok": false` with `"persisted": false` and a `persist` warning says the change did not stick ([above](#important-behavior)). A change of `groups` revokes the user's registry (Feria) tokens, whose scopes were granted from `feria-*` groups at login.
 
 #### Disabling a user
 
-`{ "disabled": true }` is the offboarding action. It sets Authelia's `disabled: true` — the user can no longer sign in — and, before Authelia restarts:
+`{ "disabled": true }` is the offboarding action. It sets Authelia's `disabled: true` — the user can no longer sign in, and their session ends at their next request — and:
 
 - the directory marks the user `disabled`, so every plugin's [user surface](agent-hosted-plugins.md#the-user-surface) refuses them at once (`403`);
 - every plugin audience that holds them shows them `disabled`, and their agent halves are told;
@@ -256,7 +259,7 @@ Desktop sessions are bound to the `userId` as well as the username: one is valid
 
 ### `DELETE /api/users/:username`
 
-Deletes an Authelia user: the user is removed from `users.yml`, the directory turns their row into a **tombstone** (`removed`, reason `deleted`, keeping the `userId`, the username and the last display name and email, so plugins' history stays readable), and Authelia restarts. With `?erase=true` the tombstone is [erased](#erasing-a-removed-user) at once as well.
+Deletes an Authelia user: the user is removed from `users.yml`, the directory turns their row into a **tombstone** (`removed`, reason `deleted`, keeping the `userId`, the username and the last display name and email, so plugins' history stays readable); their session ends at their next request. With `?erase=true` the tombstone is [erased](#erasing-a-removed-user) at once as well.
 
 You cannot delete the last remaining user. This safety check prevents accidentally locking out all users from tunneled applications.
 
@@ -344,6 +347,14 @@ The `totpUri` follows the [Key Uri Format](https://github.com/google/google-auth
 | 500    | `{"error":"Failed to read user database"}`       | Cannot read `users.yml`                                |
 | 500    | `{"error":"Failed to write TOTP configuration"}` | Cannot write TOTP secret to Authelia's SQLite database |
 
+### Domains
+
+Every user listed by `GET /api/users` carries `domains`: their memberships, `{ name, kind }` — `kind` `member` or `external` (empty until the directory has seen them). `PUT /api/users/:username` takes `domains` too — the memberships afterwards, exactly: the difference is applied in one change, each membership audited (409 `user_not_in_directory` until the directory has seen the user, 400 `unknown_domain`, 400 `conflicting_membership` for one domain named twice with two kinds); one membership at a time is the [Domains API](domains.md) (`PUT`/`DELETE /api/domains/:name/members/:user`, by `userId` or username). Wherever a request names memberships, a domain name is a `member` and `{ "name": "…", "kind": "external" }` an external member. On a relay with two domains or more, `POST /api/users` needs a non-empty `domains` (400 `domains_required`). `POST /api/invitations` takes `domains` exactly as `POST /api/users` does, and `GET /api/invitations` lists each invitation's `domains` as `{ name, kind }`; the invitation link is on the sign-in page of the first domain it names (`https://auth.<domain>/invite/<token>`). Disabling a user keeps their memberships (they are let in nowhere while disabled); deleting ends them.
+
+**External members** reach only what names them — `restricted` hosts that grant them, static sites that list them, OIDC clients granted to them — and **hold no Authelia groups**: a user who is an external member of any domain cannot be given a group (409 `external_member_groups`), a user with groups cannot be made external (409), and a new user or an invitation asking for both is refused (400 `external_member_groups`).
+
+**Groups Lamaste owns.** Who may reach what is written into each user's `groups` in `users.yml` as groups Lamaste owns — `lamaste:m:<key>`, `lamaste:x:<key>` (a random key per domain), `lamaste:s:<site id>`, hostnames (external members' granted hosts), `lamaste:oidc@<client id>` ([Domains API](domains.md#where-membership-is-enforced)). The users and identity APIs never show them and an edit keeps them; an administrator assigns only names of letters, digits, `-` and `_` (400 `reserved_group` for a name with `.`, `:` or `@` the user does not hold already).
+
 ## The User Directory
 
 The directory lives in the panel's `state.db` (migration `0013`): one row per user it ever knew, never deleted, and the directory's own id (`directoryId`, a UUID v4 made with the store), which tells a plugin's agent half when the store it follows was replaced. Admin only.
@@ -475,13 +486,14 @@ Returned by list and mutation endpoints (sensitive fields excluded):
 
 ### Validation Summary
 
-| Field         | Rules                                         |
-| ------------- | --------------------------------------------- |
-| `username`    | 2-32 chars, `/^[a-z0-9][a-z0-9_-]*$/`, unique |
-| `displayname` | 1-100 chars                                   |
-| `email`       | Valid email format                            |
-| `password`    | 8-128 chars                                   |
-| `groups`      | Array of strings, optional                    |
+| Field         | Rules                                                                               |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `username`    | 2-32 chars, `/^[a-z0-9][a-z0-9_-]*$/`, unique                                       |
+| `displayname` | 1-100 chars                                                                         |
+| `email`       | Valid email format                                                                  |
+| `password`    | 8-128 chars                                                                         |
+| `groups`      | Array of strings, optional; `[A-Za-z0-9_-]{1,64}` each; none for an external member |
+| `domains`     | Names or `{ name, kind }`, at most 50                                               |
 
 ### curl Cheat Sheet
 

package/vendor/docs/05-operations/backup-and-restore.md

@@ -199,7 +199,7 @@ sudo chown lamaste-authelia:lamaste-authelia /etc/authelia/db.sqlite3* /etc/auth
 sudo chmod 600 /etc/authelia/db.sqlite3* /etc/authelia/notifications.txt
 ```
 
-A backup taken on a version before the privilege boundary holds root-owned Authelia files and older unit files. After restoring one, re-run `npx @lamalibre/create-lamaste@4.5.0 --yes`: the redeploy rewrites the `chisel` and `authelia` units and converts the ownership of `/etc/authelia`, the Chisel key and the PKI directory (see [Upgrades](upgrades.md)).
+A backup taken on a version before the privilege boundary holds root-owned Authelia files and older unit files. After restoring one, re-run `npx @lamalibre/create-lamaste@4.7.0 --yes`: the redeploy rewrites the `chisel` and `authelia` units and converts the ownership of `/etc/authelia`, the Chisel key and the PKI directory (see [Upgrades](upgrades.md)).
 
 The panel re-applies the authfile's group and mode itself on every start, so a Chisel that fails to read it before the panel is up is started again by the panel's reconciliation.
 

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

@@ -29,7 +29,7 @@ It stops and disables the panel, gatekeeper, Chisel and Authelia; removes their
 The manual guide is also available from the CLI:
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --uninstall
+npx @lamalibre/create-lamaste@4.7.0 --uninstall
 ```
 
 This prints the same steps listed below.

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.5.0
+sudo npm install -g @lamalibre/lamaste-agent@4.7.0
 lamaste-agent update
 ```
 
@@ -35,13 +35,22 @@ 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.5.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.
+- **No agent upgrade is needed**, and no agent half must be rebuilt. An agent half built on `@lamalibre/lamaste@4.7.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)
@@ -93,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.5.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.
+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.7.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:
 
@@ -107,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.5.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.
+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.7.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.
 
@@ -246,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.5.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.
+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.7.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
 
@@ -268,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.5.0` | Upgrade after the server, then `lamaste-agent update` |
+| Agents       | `sudo npm install -g @lamalibre/lamaste-agent@4.7.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

@@ -245,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:**
 
@@ -818,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.5.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).
+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.7.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):
 

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

@@ -24,7 +24,7 @@ If you are reading documentation and hit an unfamiliar term, this is the place t
 
 **Where it appears:**
 
-- Enrolled from the panel (**Certificates → Enrollment Token**) and `lamaste-agent setup` (installed globally with `npm install -g @lamalibre/lamaste-agent@4.5.0`)
+- Enrolled from the panel (**Certificates → Enrollment Token**) and `lamaste-agent setup` (installed globally with `npm install -g @lamalibre/lamaste-agent@4.7.0`)
 - Agent registry: `/etc/lamalibre/lamaste/agents.json` on the server; `~/.lamalibre/lamaste/agents/<label>/` on the agent
 - The **Agent** column and field on the panel's Tunnels page
 
@@ -242,7 +242,7 @@ See also: [mTLS](#mtls-mutual-tls), [CA](#ca-certificate-authority), [PKCS12](#p
 
 **Where it appears:**
 
-- Generated by `lamaste-agent setup` / `update` (implementation in `@lamalibre/lamaste@4.5.0/agent`)
+- Generated by `lamaste-agent setup` / `update` (implementation in `@lamalibre/lamaste@4.7.0/agent`)
 - Installed to `~/Library/LaunchAgents/com.lamalibre.lamaste.chisel-<label>.plist` on the agent
 - Manages the Chisel client process lifecycle
 
@@ -373,7 +373,7 @@ See also: [Client Certificate](#client-certificate), [CA](#ca-certificate-author
 
 **Plain English:** A small scheduled job on every agent that checks with the panel every 30 seconds and adjusts the tunnel client when the agent's tunnels changed — so tunnels created, disabled or moved in the panel reach the agent without anyone running a command on it.
 
-**Technical:** Runs `lamaste-agent sync --label <label>`, which fetches `GET /api/tunnels/agent-config` and converges the agent's Chisel client with it (relay URL, credential, pinned binary, granted remotes, running or stopped). It exists because Chisel rejects a client's whole session when one requested remote is not granted: an agent must drop a revoked tunnel promptly or all its other tunnels go dark. Requires a global install of `@lamalibre/lamaste-agent@4.5.0`.
+**Technical:** Runs `lamaste-agent sync --label <label>`, which fetches `GET /api/tunnels/agent-config` and converges the agent's Chisel client with it (relay URL, credential, pinned binary, granted remotes, running or stopped). It exists because Chisel rejects a client's whole session when one requested remote is not granted: an agent must drop a revoked tunnel promptly or all its other tunnels go dark. Requires a global install of `@lamalibre/lamaste-agent@4.7.0`.
 
 **Where it appears:**
 

package/vendor/docs/06-reference/installer-flags.md

@@ -1,11 +1,11 @@
 # Installer Flags
 
-> CLI flags, environment variables, and exit codes for `npx @lamalibre/create-lamaste@4.5.0`.
+> CLI flags, environment variables, and exit codes for `npx @lamalibre/create-lamaste@4.7.0`.
 
 ## Usage
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 [flags]
+npx @lamalibre/create-lamaste@4.7.0 [flags]
 ```
 
 The installer runs as root on a fresh Ubuntu 24.04 server. It is completely non-interactive by default — all configuration happens later through the browser-based onboarding wizard.
@@ -26,7 +26,7 @@ The installer runs as root on a fresh Ubuntu 24.04 server. It is completely non-
 Prints a description of what the installer does, lists all flags, and exits with code 0. Does not modify anything on the system.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --help
+npx @lamalibre/create-lamaste@4.7.0 --help
 ```
 
 ### `--yes`, `-y`
@@ -34,7 +34,7 @@ npx @lamalibre/create-lamaste@4.5.0 --help
 Skips the interactive confirmation prompt that appears before installation begins. Useful for automated deployments or scripts where you cannot press Enter.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --yes
+npx @lamalibre/create-lamaste@4.7.0 --yes
 ```
 
 Without this flag, the installer displays a banner listing all changes it will make and waits for the user to press Enter or Ctrl+C.
@@ -51,7 +51,7 @@ Skips all OS hardening tasks:
 Everything else (Node.js, nginx, mTLS, panel deployment) still runs.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --skip-harden
+npx @lamalibre/create-lamaste@4.7.0 --skip-harden
 ```
 
 Use this if you manage your own firewall rules, already have fail2ban configured, or are running on a platform that handles security at a different layer.
@@ -61,7 +61,7 @@ Use this if you manage your own firewall rules, already have fail2ban configured
 Allows the installer to run on a machine with a private or non-routable IP address (e.g., `192.168.x.x`, `10.x.x.x`). By default, the installer requires a public IP.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --dev
+npx @lamalibre/create-lamaste@4.7.0 --dev
 ```
 
 This is useful for:
@@ -76,7 +76,7 @@ When `--dev` is active, the installer prints the detected IP with a note: `(dev
 Forces the installer to run the complete installation pipeline, ignoring skip guards that would normally detect an existing installation. This is useful when an installation is in an inconsistent state and you want to ensure all components are fully deployed.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --force-full
+npx @lamalibre/create-lamaste@4.7.0 --force-full
 ```
 
 Use this if:
@@ -90,7 +90,7 @@ Use this if:
 Prints a step-by-step guide for manually removing Lamaste from the server, then exits with code 0. Does not modify anything on the system.
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --uninstall
+npx @lamalibre/create-lamaste@4.7.0 --uninstall
 ```
 
 The printed guide first points to the automated removal, `sudo lamaste-server uninstall`, then covers:
@@ -207,25 +207,25 @@ Components that are always redeployed on re-run:
 
 ```bash
 ssh root@203.0.113.42
-npx @lamalibre/create-lamaste@4.5.0
+npx @lamalibre/create-lamaste@4.7.0
 ```
 
 **Automated install (no confirmation prompt):**
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --yes
+npx @lamalibre/create-lamaste@4.7.0 --yes
 ```
 
 **Install without OS hardening:**
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --yes --skip-harden
+npx @lamalibre/create-lamaste@4.7.0 --yes --skip-harden
 ```
 
 **Test in a local VM:**
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --dev
+npx @lamalibre/create-lamaste@4.7.0 --dev
 ```
 
 **Update an existing installation:**
@@ -237,7 +237,7 @@ npx @lamalibre/create-lamaste@latest --yes
 **View the uninstall guide:**
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --uninstall
+npx @lamalibre/create-lamaste@4.7.0 --uninstall
 ```
 
 ## Quick Reference

package/vendor/docs/06-reference/ports-and-services.md

@@ -34,7 +34,7 @@ A tunnel's port is also a loopback port on the relay: its vhost proxies to `127.
 | 9292 | IP-based panel listener |
 | 9294 | Gatekeeper              |
 
-A tunnel on one of them would publish that internal service on a public hostname. For the panel that is an administrator takeover, not a leak: the panel trusts the client-certificate headers nginx sets. `RESERVED_TUNNEL_PORTS` in `@lamalibre/lamaste@4.5.0` is enforced by the request schema, inside the tunnel workflow, and again when the Chisel grants are rendered. Tunnel ports must also be 1024–65535.
+A tunnel on one of them would publish that internal service on a public hostname. For the panel that is an administrator takeover, not a leak: the panel trusts the client-certificate headers nginx sets. `RESERVED_TUNNEL_PORTS` in `@lamalibre/lamaste@4.7.0` is enforced by the request schema, inside the tunnel workflow, and again when the Chisel grants are rendered. Tunnel ports must also be 1024–65535.
 
 ## Systemd Units
 

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

@@ -217,7 +217,7 @@ The agent's sync timer applies tunnel changes within about 30 seconds. If that d
 lamaste-agent update     # apply now and (re)install the sync timer
 ```
 
-`update` needs the agent installed globally (`npm install -g @lamalibre/lamaste-agent@4.5.0`); an agent originally set up with `npx` must be installed first.
+`update` needs the agent installed globally (`npm install -g @lamalibre/lamaste-agent@4.7.0`); an agent originally set up with `npx` must be installed first.
 
 **Cause 3: The agent does not carry the tunnel.**
 
@@ -320,7 +320,7 @@ ls -la /usr/local/bin/authelia
 | Missing `panel.json`            | `Config file not found`                 | Re-run installer or create the file manually                                                                                   |
 | Invalid JSON in `panel.json`    | `contains invalid JSON`                 | Fix the JSON syntax                                                                                                            |
 | Port 3100 in use                | `EADDRINUSE`                            | Find and stop the conflicting process: `sudo ss -tlnp sport = :3100`                                                           |
-| Missing Node.js modules         | `Cannot find module`                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.5.0 --yes`); `/opt/lamalibre/lamaste` is root-owned and redeployed as a whole |
+| Missing Node.js modules         | `Cannot find module`                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.7.0 --yes`); `/opt/lamalibre/lamaste` is root-owned and redeployed as a whole |
 | Permission denied writing state | `EACCES` under `/etc/lamalibre/lamaste` | Re-run the installer; the redeploy re-applies the ownership of the config and PKI directories                                  |
 
 ### chisel fails to start
@@ -329,7 +329,7 @@ ls -la /usr/local/bin/authelia
 
 | Cause                      | Log Message                                                                           | Fix                                                                                                                                                                                                                               |
 | -------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Binary missing             | `exec format error` or `not found`                                                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.5.0 --yes`) — it installs the pinned, checksum-verified release for the server's architecture; the panel cannot install binaries                                                 |
+| Binary missing             | `exec format error` or `not found`                                                    | Re-run the installer (`npx @lamalibre/create-lamaste@4.7.0 --yes`) — it installs the pinned, checksum-verified release for the server's architecture; the panel cannot install binaries                                                 |
 | Not the pinned release     | (panel log) `The installed chisel is not the pinned release — run create-lamaste ...` | Re-run the installer. Until then the panel restarts Chisel on every authfile change                                                                                                                                               |
 | Authfile or key unreadable | `permission denied` on `chisel-users` or `chisel-server.key`                          | Both must be `0640 lamaste:lamaste-chisel` and the unit `Group=lamaste-chisel`; restart the panel, which re-applies the authfile's. If the group, the unit or the key's ownership is wrong, re-run the installer in redeploy mode |
 | Stopped by the panel       | (panel log) `Chisel stopped: ...`; unit disabled, `chisel-failed-closed` present      | Reconciliation failed closed; see [Tunnel Client Cannot Connect](#tunnel-client-cannot-connect), Cause 1                                                                                                                          |
@@ -343,7 +343,7 @@ ls -la /usr/local/bin/authelia
 | --------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Invalid `configuration.yml` | `configuration: error`                  | Check YAML syntax with `authelia validate-configuration --config /etc/authelia/configuration.yml`                                                                                                                                                                                                                                                         |
 | Missing `users.yml`         | `cannot open file`                      | Create an initial users file (see [Config Files](config-files.md))                                                                                                                                                                                                                                                                                        |
-| Binary missing              | `not found`                             | Re-run the installer (`npx @lamalibre/create-lamaste@4.5.0 --yes`); it installs the pinned release                                                                                                                                                                                                                                                              |
+| Binary missing              | `not found`                             | Re-run the installer (`npx @lamalibre/create-lamaste@4.7.0 --yes`); it installs the pinned release                                                                                                                                                                                                                                                              |
 | Wrong permissions           | `permission denied`                     | Authelia runs as `lamaste-authelia`: `/etc/authelia` must be `lamaste:lamaste-authelia 2770`, `configuration.yml` `0640`, `users.yml` `0660`, `db.sqlite3` owned by `lamaste-authelia`. Re-run the installer to re-apply (a root-owned `/etc/authelia` from an older version is converted), or see [Config Files](config-files.md#file-permissions-table) |
 | Database newer than binary  | storage schema version error at startup | A newer Authelia ran against this database and was replaced by an older one; the installer never downgrades an installed Authelia, so reinstall that newer release by hand                                                                                                                                                                                |
 
@@ -516,14 +516,14 @@ sudo systemctl restart authelia
 
 ## Onboarding Fails: "Chisel is not installed" / "Authelia is not installed"
 
-**Symptom:** The **Starting Chisel** or **Configuring Authelia** provisioning task fails with "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.5.0` on the server to repair the installation." (or the same for Authelia).
+**Symptom:** The **Starting Chisel** or **Configuring Authelia** provisioning task fails with "Chisel is not installed. Run `npx @lamalibre/create-lamaste@4.7.0` on the server to repair the installation." (or the same for Authelia).
 
 **Cause:** Onboarding downloads nothing: the installer installs both binaries (pinned releases), their systemd units and the `lamaste-authelia` account. The binary at `/usr/local/bin/chisel` or `/usr/local/bin/authelia` is missing — the installer was interrupted, or the file was removed.
 
 **Fix:** Re-run the installer on the server, then start provisioning again from the wizard:
 
 ```bash
-npx @lamalibre/create-lamaste@4.5.0 --yes
+npx @lamalibre/create-lamaste@4.7.0 --yes
 ```
 
 If provisioning then fails writing Authelia's configuration with `/etc/authelia is not writable by the panel — run create-lamaste to repair the installation`, the directory's ownership is wrong; the same command repairs it.
@@ -538,7 +538,7 @@ If provisioning then fails writing Authelia's configuration with `/etc/authelia
 
 **Fix:**
 
-1. Re-run the installer so the helper matches the panel: `npx @lamalibre/create-lamaste@4.5.0 --yes`
+1. Re-run the installer so the helper matches the panel: `npx @lamalibre/create-lamaste@4.7.0 --yes`
 2. If it persists on a current install, it is a bug: the vhost generators (`packages/server/daemon/src/lib/nginx.js`) and the allow-list (`packages/provisioners/server/scripts/lamaste-priv`) must change together — `npm test` checks every generated vhost against the allow-list. Do not work around it by editing files in `/etc/nginx` by hand.
 
 `sudo: a password is required` for `lamaste-priv` means the helper or the sudoers file is missing or outdated: re-run the installer.
@@ -621,7 +621,7 @@ df -h /
 
 **Cause 3: The web root is not writable by the panel (`EACCES`).**
 
-The panel writes `/var/www/lamaste` itself: it must be `lamaste:www-data`, directories `2750`, files `0640`. An install from before this layout had it owned by `www-data`. Re-run the installer (`npx @lamalibre/create-lamaste@4.5.0 --yes`); the redeploy converts the tree.
+The panel writes `/var/www/lamaste` itself: it must be `lamaste:www-data`, directories `2750`, files `0640`. An install from before this layout had it owned by `www-data`. Re-run the installer (`npx @lamalibre/create-lamaste@4.7.0 --yes`); the redeploy converts the tree.
 
 ---