@lamalibre/create-lamaste 4.4.1 → 4.5.0

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

@@ -6,7 +6,9 @@
 
 When someone visits one of your tunneled apps (like `app.example.com`), they are prompted to log in through Authelia with a username, password, and a TOTP code from an authenticator app. The users API lets you create those login accounts, update their details, reset their TOTP secrets, and delete accounts you no longer need.
 
-These are not admin panel users — the panel itself is protected by mTLS client certificates with no login screen. These users are for the apps you expose through tunnels.
+These are not admin panel users — the panel itself is protected by mTLS client certificates with no login screen. These users are for the apps you expose through tunnels, and for the agent-hosted plugins that declare users of their own ([Agent-Hosted Plugins](agent-hosted-plugins.md#users-and-identity)).
+
+Authelia keys users by username, which anyone can reuse. The panel therefore keeps a **user directory** beside Authelia's `users.yml`: every user gets a stable `userId` (a UUID v4) the moment their username appears, plugins key their data on it, and the directory keeps the row for good. A user is `active`, `disabled` (cannot sign in — the one offboarding action) or `removed` (deleted). A deleted user leaves a **tombstone** — the `userId` and the last known name and address — so a plugin's history stays readable, until an administrator **erases** it. A username that comes back after a deletion is a new user with a new `userId`.
 
 ## Authentication
 
@@ -17,9 +19,14 @@ 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 — a warning is logged but no error is returned to the client. 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.
+- **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.
 - **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.
+- **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.
+- **Last administrator protection:** You cannot disable the last enabled member of the `admins` group.
 
 ## Endpoints
 
@@ -45,24 +52,35 @@ curl -s --cert client.p12:password \
       "username": "admin",
       "displayname": "Admin User",
       "email": "admin@example.com",
-      "groups": []
+      "groups": ["admins"],
+      "disabled": false,
+      "userId": "0b6c2f4e-8a1d-4f3b-9c55-1e2d3f4a5b6c",
+      "status": "active"
     },
     {
       "username": "alice",
       "displayname": "Alice Smith",
       "email": "alice@example.com",
-      "groups": ["developers"]
+      "groups": ["developers"],
+      "disabled": true,
+      "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+      "status": "disabled"
     }
   ]
 }
 ```
 
-| Field         | Type       | Description                 |
-| ------------- | ---------- | --------------------------- |
-| `username`    | `string`   | Unique login identifier     |
-| `displayname` | `string`   | Human-readable display name |
-| `email`       | `string`   | User's email address        |
-| `groups`      | `string[]` | Authelia group memberships  |
+| Field         | Type             | Description                                                                                                                              |
+| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `username`    | `string`         | Unique login identifier                                                                                                                  |
+| `displayname` | `string`         | Human-readable display name                                                                                                              |
+| `email`       | `string`         | User's email address                                                                                                                     |
+| `groups`      | `string[]`       | Authelia group memberships                                                                                                               |
+| `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`                                                                                                                   |
+
+Users deleted from `users.yml` are not listed here; the [directory](#get-api-identity-directory) keeps their tombstones.
 
 **Errors:**
 
@@ -96,7 +114,7 @@ Creates a new Authelia user. The password is hashed with bcrypt before being sto
 | `password`    | `string`   | 8-128 chars                                                                                 | Plain-text password (hashed before storage) |
 | `groups`      | `string[]` | Optional, defaults to `[]`                                                                  | Authelia group memberships                  |
 
-**Username regex** (the same rule applies to invitations — a leading `-` would read as a flag to Authelia's CLI when a TOTP secret is stored):
+**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):
 
 ```
 ^[a-z0-9][a-z0-9_-]*$
@@ -119,20 +137,28 @@ curl -s --cert client.p12:password \
     "username": "alice",
     "displayname": "Alice Smith",
     "email": "alice@example.com",
-    "groups": []
+    "groups": [],
+    "disabled": false,
+    "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+    "status": "active"
   }
 }
 ```
 
+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`.
+
 **Errors:**
 
-| Status | Body                                                       | When                                        |
-| ------ | ---------------------------------------------------------- | ------------------------------------------- |
-| 400    | `{"error":"Validation failed","details":{"issues":[...]}}` | Invalid username, email, or password length |
-| 409    | `{"error":"Username already exists"}`                      | A user with this username already exists    |
-| 500    | `{"error":"Failed to read user database"}`                 | Cannot read `users.yml`                     |
-| 500    | `{"error":"Failed to hash password"}`                      | bcrypt hashing failed                       |
-| 500    | `{"error":"Failed to update user database"}`               | Cannot write `users.yml`                    |
+| Status | Body                                                                                          | When                                                                                                                                                                                                   |
+| ------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 400    | `{"error":"Validation failed","details":{"issues":[...]}}`                                    | Invalid username, email, or password length                                                                                                                                                            |
+| 409    | `{"error":"Username already exists"}`                                                         | A user with this username already exists                                                                                                                                                               |
+| 409    | `{"error":"Authelia holds an OpenID Connect identity …","code":"username_has_oidc_identity"}` | Authelia holds an OpenID Connect opaque identifier for the username: every relying party would take the new user for the earlier one ([Reused usernames](#reused-usernames)) — choose another username |
+| 503    | `{"error":"A removed user's grants …","code":"gatekeeper_unavailable"}`                       | An earlier user with this username left grants or groups in Gatekeeper, and Gatekeeper cannot remove them now                                                                                          |
+| 503    | `{"error":"Authelia's storage could not …","code":"authelia_storage_unavailable"}`            | Authelia's storage could not be checked for an OpenID Connect identity of the username, or an earlier user's second factors under it could not be deleted                                              |
+| 500    | `{"error":"Failed to read user database"}`                                                    | Cannot read `users.yml`                                                                                                                                                                                |
+| 500    | `{"error":"Failed to hash password"}`                                                         | bcrypt hashing failed                                                                                                                                                                                  |
+| 500    | `{"error":"Failed to update user database"}`                                                  | Cannot write `users.yml`                                                                                                                                                                               |
 
 ---
 
@@ -153,12 +179,13 @@ 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) |
+| 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)) |
 
 All fields are optional, but at least one must be provided (validated by a Zod `.refine()`).
 
@@ -179,47 +206,95 @@ curl -s --cert client.p12:password \
     "username": "alice",
     "displayname": "Alice J. Smith",
     "email": "alice.smith@example.com",
-    "groups": ["developers", "admins"]
+    "groups": ["developers", "admins"],
+    "disabled": false,
+    "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+    "status": "active"
   }
 }
 ```
 
+`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.
+
+#### 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:
+
+- 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;
+- the user is [offboarded](#offboarding): their desktop app sessions end and their registry tokens are revoked (best effort — `warnings` on failure).
+
+The user keeps their `userId`, grants and group memberships; `{ "disabled": false }` enables them again with everything as it was — except desktop sessions, which stay ended. A disabled user still counts as a user (they can be deleted). The last enabled member of the `admins` group cannot be disabled. A user disabled by editing `users.yml` is offboarded the same way when the next reconcile sees it.
+
+#### Offboarding
+
+One function, keyed by `userId`, for every way a user stops being one — disabled or deleted through this API, and disabled or gone from `users.yml` outside it (adopted by the minute's reconcile):
+
+| Step                                                                                              | Disabled | Removed |
+| ------------------------------------------------------------------------------------------------- | -------- | ------- |
+| Desktop app sessions end: the user's session epoch (`panel.json` `userEpochs`, keyed by `userId`) | ✓        | ✓       |
+| Registry (Feria) tokens revoked                                                                   | ✓        | ✓       |
+| Grants in the legacy `user-plugin-access.json` removed                                            |          | ✓       |
+| Gatekeeper drops every grant and group membership under the username (pending until it can)       |          | ✓       |
+| Authelia deletes the user's TOTP configuration and WebAuthn credentials                           |          | ✓       |
+| Gatekeeper's cached session verdicts dropped                                                      | ✓        | ✓       |
+
+Desktop sessions are bound to the `userId` as well as the username: one is valid only while its user still holds the username and is enabled, so a username given to someone else never revives a session. Sessions issued before 4.5 carry no `userId` and are refused — desktop users sign in again once after the upgrade. An epoch older than a session's longest life (12 hours) can reject nothing and is dropped; `panel.json` names nobody.
+
 **Errors:**
 
-| Status | Body                                                       | When                                             |
-| ------ | ---------------------------------------------------------- | ------------------------------------------------ |
-| 400    | `{"error":"Validation failed","details":{"issues":[...]}}` | No fields provided, or invalid field values      |
-| 404    | `{"error":"User not found"}`                               | No user with this username                       |
-| 500    | `{"error":"Failed to read user database"}`                 | Cannot read `users.yml`                          |
-| 500    | `{"error":"Failed to hash password"}`                      | bcrypt hashing failed (when password is updated) |
-| 500    | `{"error":"Failed to update user database"}`               | Cannot write `users.yml`                         |
+| Status | Body                                                                            | When                                             |
+| ------ | ------------------------------------------------------------------------------- | ------------------------------------------------ |
+| 400    | `{"error":"Validation failed","details":{"issues":[...]}}`                      | No fields provided, or invalid field values      |
+| 400    | `{"error":"Cannot disable the last enabled administrator","code":"last_admin"}` | Disabling the last enabled member of `admins`    |
+| 404    | `{"error":"User not found"}`                                                    | No user with this username                       |
+| 500    | `{"error":"Failed to read user database"}`                                      | Cannot read `users.yml`                          |
+| 500    | `{"error":"Failed to hash password"}`                                           | bcrypt hashing failed (when password is updated) |
+| 500    | `{"error":"Failed to update user database"}`                                    | Cannot write `users.yml`                         |
 
 ---
 
 ### `DELETE /api/users/:username`
 
-Deletes an Authelia user. The user is removed from `users.yml` and Authelia is reloaded.
+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.
 
 You cannot delete the last remaining user. This safety check prevents accidentally locking out all users from tunneled applications.
 
+Then, never rolled back — what fails is reported in `warnings` — the user is [offboarded](#offboarding):
+
+1. Gatekeeper drops every grant naming the username (any resource type) and its membership of every Lamaste group, in one transaction ([Usernames and Gatekeeper](#usernames-and-gatekeeper)). When Gatekeeper cannot, the cleanup stays **pending** on the tombstone and is retried every minute; until it succeeds the username holds no role in any plugin and cannot be given to a new user.
+2. Authelia deletes the user's TOTP configuration and WebAuthn credentials. When it cannot, the username cannot be given to a new user until it can ([Reused usernames](#reused-usernames)).
+3. The user's registry (Feria) tokens are revoked, their grants in the legacy `user-plugin-access.json` removed, and their desktop app sessions ended.
+4. Every plugin that had the user as a member is sent `remove` with reason `deleted` and what it last received about them.
+
 **Request:**
 
-No request body.
+No request body. Query: `erase` — `true` to erase the tombstone in the same call.
 
 ```bash
 curl -s --cert client.p12:password \
   -X DELETE \
-  https://203.0.113.42:9292/api/users/alice | jq
+  "https://203.0.113.42:9292/api/users/alice?erase=true" | jq
 ```
 
 **Response (200):**
 
 ```json
 {
-  "ok": true
+  "ok": true,
+  "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+  "principalCleared": true,
+  "erased": true
 }
 ```
 
+| Field              | Type             | Description                                                                                                |
+| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| `userId`           | `string \| null` | The tombstone's id; `null` when the directory held no row for the user (nothing to erase then — a warning) |
+| `principalCleared` | `boolean`        | Gatekeeper dropped the grants and memberships under the username; `false`: pending, retried every minute   |
+| `erased`           | `boolean`        | Only with `?erase=true`: whether the tombstone was erased (`false` with a warning — erase it later by id)  |
+| `warnings`         | `array`          | What did not happen: `{ step, message }` (or a sentence)                                                   |
+
 **Errors:**
 
 | Status | Body                                         | When                       |
@@ -269,15 +344,118 @@ 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 |
 
+## 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.
+
+### `GET /api/identity/directory`
+
+Every user the directory knows — members by username, then the removed, then the erased — with who erased each erased one and the plugins that have not yet acknowledged an erasure.
+
+```json
+{
+  "directoryId": "3b0e5c1a-7f2d-4c8e-9a1b-2c3d4e5f6a7b",
+  "users": [
+    {
+      "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+      "username": "alice",
+      "displayName": "Alice Smith",
+      "email": "alice@example.com",
+      "status": "removed",
+      "removedReason": "deleted",
+      "removedAt": "2026-10-22T08:00:00.000Z",
+      "erasedAt": null,
+      "principalClearedAt": "2026-10-22T08:00:00.120Z",
+      "version": 4,
+      "createdAt": "2026-10-01T10:00:00.000Z",
+      "updatedAt": "2026-10-22T08:00:00.000Z",
+      "erasure": null,
+      "pendingErasures": []
+    }
+  ]
+}
+```
+
+| Field                              | Description                                                                                                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `userId`                           | Stable id (UUID v4); never reused                                                                                                                                                                                        |
+| `username`, `displayName`, `email` | As `users.yml` last had them; all `null` once erased                                                                                                                                                                     |
+| `status`                           | `active`, `disabled` or `removed`                                                                                                                                                                                        |
+| `removedReason`                    | `deleted` (through Lamaste) or `deleted-outside` (gone from `users.yml` without it); `null` unless removed                                                                                                               |
+| `removedAt`, `erasedAt`            | When the user was removed, and erased                                                                                                                                                                                    |
+| `principalClearedAt`               | When Gatekeeper dropped what it held under the removed user's username; `null` on a removed user: **cleanup pending**                                                                                                    |
+| `version`                          | 1 at creation, + 1 on every change                                                                                                                                                                                       |
+| `erasure`                          | `{ requestedAt, requestedBy }` for an erased user, else `null`                                                                                                                                                           |
+| `pendingErasures`                  | Names of the plugins that have not yet acknowledged this user's erasure — their hosting's agent half, or an agent that retains their data                                                                                |
+| `pendingErasuresInactive`          | Among them, the plugins the feed does not reach now (uninstalled, or no longer declaring identity) whose data an agent keeps: the erasure reaches it when the plugin comes back, or goes with the data when it is purged |
+
+### Erasing a removed user
+
+Deleting keeps the tombstone; **erasing** scrubs it. An erasure of a removed user, in this order — anything that fails before the scrub leaves the tombstone as it was, still naming the username a later attempt needs:
+
+1. Gatekeeper's principal cleanup, if it is still pending.
+2. Gatekeeper's **access-request log**: the user's rows logged before they were removed (and those still queued for the log) are deleted.
+3. Authelia's **second factors** for the username (TOTP, WebAuthn) are deleted, should their deletion at removal have failed.
+4. The user's **invitations** made before they were removed are deleted from `invitations.json`.
+5. The directory row is scrubbed to the bare `userId` (`username`, display name and email `NULL`, `erasedAt` set), who asked is recorded, and `directory.user.erased` is audited (`userId`, counts).
+6. The audiences are recomputed: **every** plugin that ever had the user as a member — including one uninstalled while an agent keeps its data, or one that no longer declares identity — has the user's row rewritten to `remove` with reason `erased` and no attributes. A plugin that takes the feed is sent it: its agent half scrubs its own row and anonymises what the plugin keeps in the same transaction, and its cursor passing the change is the acknowledgement. One that does not now replays it when it comes back. Until then the plugin is listed in the user's `pendingErasures` (marked in `pendingErasuresInactive` when the feed does not reach it now) and the user in the plugin's — [Agent-Hosted Plugins](agent-hosted-plugins.md#erasure). Delivery takes seconds while the hosting agent is online, and happens when it reconnects otherwise. An agent half never takes an erased user back: an erasure is sticky in its projection.
+
+**Outside Lamaste's reach:** Authelia keeps the username's OpenID Connect **opaque identifier** (Authelia 4.39 cannot delete one — which is why the username is never given to anyone again while it exists) and its own **authentication log**; nginx access logs and journald keep what they logged before (see [Monitoring](../05-operations/monitoring.md#logs-and-personal-data) for their retention); backups taken before the erasure keep everything. Plugins replay erasures at their daily reconcile, which is how an erasure reaches an agent half's data restored from an older backup; restoring the relay itself is covered in [Backup and Restore](../05-operations/backup-and-restore.md).
+
+### `POST /api/identity/directory/:userId/erase`
+
+Erases a removed user. 30 a minute.
+
+**Response (200):**
+
+```json
+{
+  "ok": true,
+  "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+  "erasedAt": "2026-10-22T08:05:00.000Z",
+  "invitationsPurged": 1,
+  "accessLogPurged": 3
+}
+```
+
+**Errors:**
+
+| Status | `code`                         | When                                                                                                                           |
+| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| 400    |                                | `userId` is not a UUID v4                                                                                                      |
+| 404    | `user_not_found`               | No user with this id                                                                                                           |
+| 409    | `user_not_removed`             | The user is active or disabled — delete them first, or delete and erase in one step (`DELETE /api/users/:username?erase=true`) |
+| 409    | `already_erased`               | Erased already                                                                                                                 |
+| 503    | `gatekeeper_unavailable`       | Gatekeeper could not clear the principal or purge its log — nothing was erased; try again                                      |
+| 503    | `authelia_storage_unavailable` | Authelia's storage could not delete the second factors — nothing was erased; try again                                         |
+
+### Usernames and Gatekeeper
+
+Gatekeeper keys users by username too: the grants naming a user and their memberships of Lamaste groups would pass to anyone who later holds the username. So every removed user's **principal** is cleared in Gatekeeper — every grant naming the username, of any resource type, and its membership of every group, in one Gatekeeper transaction (`POST /api/principals/user/remove { username }` on Gatekeeper's own API, which only the panel calls; the username travels in the body, never in a URL) — when the user is removed (through Lamaste or outside it), every minute while that is pending (Gatekeeper was down), before an erasure, and **whenever a user is created under the username** — always then, pending or not: a restored `gatekeeper.db`, or a grant that raced the deletion, may have brought something back. Each cleanup is audited as `directory.user.principal-cleared` with the user ids.
+
+A grant or a group membership given to a username through the panel (an entitlement, the Gatekeeper proxy) is given holding the users lock, so no deletion runs between the checks and the grant. A username a deleted user held and nobody holds now takes **nothing** — `409 username_deleted` (whatever it was given would pass to whoever is given the username next); a pending cleanup under a username is completed first (`503 gatekeeper_unavailable` while it cannot be). While a username's cleanup is pending it holds no role in any plugin. A username the directory never saw goes through: Gatekeeper may hold grants for a user still to come.
+
+### Reused usernames
+
+A new user under a username an earlier user held inherits **nothing**: not their `userId` (a new one), not their grants, group memberships or plugin roles (Gatekeeper's principal cleared at creation), not their second factors (Authelia's TOTP configuration and WebAuthn credentials deleted at removal and again at creation — `503 authelia_storage_unavailable` while they cannot be), not their desktop sessions (bound to the `userId`).
+
+One thing Lamaste cannot take away: the **OpenID Connect identity**. Authelia gives each user an opaque identifier (the `sub` claim relying parties see — plugins that sign users in through Lamaste's OpenID Connect provider, a registry) the first time they sign in to one, keyed by username, and Authelia 4.39 has no way to delete it. A new user under that username would be the old user to every relying party. So **a username Authelia holds an opaque identifier for is never given to a new user**: creating a user (or accepting an invitation) under it is refused with `409 username_has_oidc_identity` — choose another username. The panel checks with Authelia's own CLI (`lamaste-priv authelia-user has-oidc-identifier`, which answers yes or no and nothing else).
+
+---
+
 ## Quick Reference
 
-| Method | Path                              | Description                                        |
-| ------ | --------------------------------- | -------------------------------------------------- |
-| GET    | `/api/users`                      | List all users (alphabetical, no sensitive fields) |
-| POST   | `/api/users`                      | Create user (bcrypt hash + Authelia reload)        |
-| PUT    | `/api/users/:username`            | Update user fields (partial update)                |
-| DELETE | `/api/users/:username`            | Delete user (not the last one)                     |
-| POST   | `/api/users/:username/reset-totp` | Generate new TOTP secret                           |
+| Method | Path                                    | Description                                                                              |
+| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------- |
+| GET    | `/api/users`                            | List all users (alphabetical, no sensitive fields), with `userId` and `status`           |
+| POST   | `/api/users`                            | Create user (bcrypt hash + Authelia reload); a username with an OIDC identity is refused |
+| PUT    | `/api/users/:username`                  | Update user fields (partial update); `disabled` disables/enables                         |
+| DELETE | `/api/users/:username[?erase=true]`     | Delete user (not the last one); a tombstone stays unless erased                          |
+| POST   | `/api/users/:username/reset-totp`       | Generate new TOTP secret                                                                 |
+| GET    | `/api/identity/directory`               | Every user the directory knows, tombstones and erasures included                         |
+| POST   | `/api/identity/directory/:userId/erase` | Erase a removed user                                                                     |
+
+From the CLI (through the running panel, `--json` for NDJSON): `lamaste-server users list`, `users disable <username>`, `users enable <username>`, `users delete <username> [--erase]`, `users erase <userId>`, `users directory`. The panel's Users page and the desktop app (`AdminClient` `getUsers`, `disableUser`, `enableUser`, `deleteUser(username, { erase })`, `getUserDirectory`, `eraseDirectoryUser`) do the same — see [Managing Users](../02-guides/managing-users.md).
 
 ### User Object Shape
 
@@ -288,7 +466,10 @@ Returned by list and mutation endpoints (sensitive fields excluded):
   "username": "alice",
   "displayname": "Alice Smith",
   "email": "alice@example.com",
-  "groups": ["developers"]
+  "groups": ["developers"],
+  "disabled": false,
+  "userId": "7d9e1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
+  "status": "active"
 }
 ```
 
@@ -326,6 +507,21 @@ curl -s --cert client.p12:password \
   -X DELETE \
   https://203.0.113.42:9292/api/users/bob | jq
 
+# Disable a user (offboarding); {"disabled":false} enables them again
+curl -s --cert client.p12:password \
+  -X PUT -H "Content-Type: application/json" \
+  -d '{"disabled":true}' \
+  https://203.0.113.42:9292/api/users/bob | jq
+
+# Delete a user and erase what the directory keeps of them
+curl -s --cert client.p12:password \
+  -X DELETE \
+  "https://203.0.113.42:9292/api/users/bob?erase=true" | jq
+
+# The directory, tombstones included
+curl -s --cert client.p12:password \
+  https://203.0.113.42:9292/api/identity/directory | jq
+
 # Reset TOTP
 curl -s --cert client.p12:password \
   -X POST \

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

@@ -18,24 +18,26 @@ Lamaste's state is spread across four directories. All of them matter.
 
 This is the most important directory. It contains:
 
-| File                      | Purpose                                                                                                                                                                                                   |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `panel.json`              | Server configuration (IP, domain, email, onboarding status)                                                                                                                                               |
-| `tunnels.json`            | Tunnel definitions (subdomain, port, carrying agent, enabled state)                                                                                                                                       |
-| `sites.json`              | Static site definitions (including custom-domain aliases)                                                                                                                                                 |
-| `chisel-credentials.json` | Per-agent Chisel credentials. If lost, the panel mints a new credential for every active agent at its next start, and each agent's sync timer fetches it within about 30 seconds (the issue time changed) |
-| `chisel-users`            | Chisel authfile — derived; rewritten from the two files above, with mode `0640` and group `lamaste-chisel`, at every panel start                                                                          |
-| `chisel-sentinel`         | Password of the no-grants sentinel Chisel user                                                                                                                                                            |
-| `invitations.json`        | Pending user invitations                                                                                                                                                                                  |
-| `pki/revoked.json`        | Revoked certificate tracking                                                                                                                                                                              |
-| `pki/ca.key`              | Certificate Authority private key                                                                                                                                                                         |
-| `pki/ca.crt`              | Certificate Authority certificate                                                                                                                                                                         |
-| `pki/client.key`          | Client certificate private key                                                                                                                                                                            |
-| `pki/client.crt`          | Client certificate                                                                                                                                                                                        |
-| `pki/client.p12`          | PKCS12 bundle (imported into browsers)                                                                                                                                                                    |
-| `pki/.p12-password`       | Password for the PKCS12 bundle                                                                                                                                                                            |
-| `pki/self-signed.pem`     | Self-signed TLS cert for IP:9292 access                                                                                                                                                                   |
-| `pki/self-signed-key.pem` | Self-signed TLS key for IP:9292 access                                                                                                                                                                    |
+| File                      | Purpose                                                                                                                                                                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `panel.json`              | Server configuration (IP, domain, email, onboarding status)                                                                                                                                                                                            |
+| `tunnels.json`            | Tunnel definitions (subdomain, port, carrying agent, enabled state)                                                                                                                                                                                    |
+| `sites.json`              | Static site definitions (including custom-domain aliases)                                                                                                                                                                                              |
+| `chisel-credentials.json` | Per-agent Chisel credentials. If lost, the panel mints a new credential for every active agent at its next start, and each agent's sync timer fetches it within about 30 seconds (the issue time changed)                                              |
+| `chisel-users`            | Chisel authfile — derived; rewritten from the two files above, with mode `0640` and group `lamaste-chisel`, at every panel start                                                                                                                       |
+| `chisel-sentinel`         | Password of the no-grants sentinel Chisel user                                                                                                                                                                                                         |
+| `invitations.json`        | Pending user invitations                                                                                                                                                                                                                               |
+| `state.db`                | The panel's SQLite store (WAL): plugins and their hostings' state, agents, audit log, notifications, settings cache — and the **user directory**: every user's `userId`, tombstones, the `directoryId`, plugin audiences and the identity feed's state |
+| `gatekeeper.db`           | Gatekeeper's SQLite store (WAL): Lamaste groups and members, grants (plugin entitlements included), the access-request log                                                                                                                             |
+| `pki/revoked.json`        | Revoked certificate tracking                                                                                                                                                                                                                           |
+| `pki/ca.key`              | Certificate Authority private key                                                                                                                                                                                                                      |
+| `pki/ca.crt`              | Certificate Authority certificate                                                                                                                                                                                                                      |
+| `pki/client.key`          | Client certificate private key                                                                                                                                                                                                                         |
+| `pki/client.crt`          | Client certificate                                                                                                                                                                                                                                     |
+| `pki/client.p12`          | PKCS12 bundle (imported into browsers)                                                                                                                                                                                                                 |
+| `pki/.p12-password`       | Password for the PKCS12 bundle                                                                                                                                                                                                                         |
+| `pki/self-signed.pem`     | Self-signed TLS cert for IP:9292 access                                                                                                                                                                                                                |
+| `pki/self-signed-key.pem` | Self-signed TLS key for IP:9292 access                                                                                                                                                                                                                 |
 
 **If you lose the PKI files**, every browser that imported the client certificate will need a new one. This is the single most important directory to back up.
 
@@ -197,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.4.1 --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.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)).
 
 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.
 
@@ -304,13 +306,15 @@ The existing client certificate (`.p12` file) will still work because the CA key
 
 All Lamaste state is stored as flat files with atomic writes:
 
-| File                                      | Format | Write Pattern                                                 |
-| ----------------------------------------- | ------ | ------------------------------------------------------------- |
-| `/etc/lamalibre/lamaste/panel.json`       | JSON   | Write `.tmp` then `rename()`                                  |
-| `/etc/lamalibre/lamaste/tunnels.json`     | JSON   | Write `.tmp`, `fsync()`, then `rename()`                      |
-| `/etc/lamalibre/lamaste/sites.json`       | JSON   | Write `.tmp`, `fsync()`, then `rename()`                      |
-| `/etc/lamalibre/lamaste/invitations.json` | JSON   | Write `.tmp`, `fsync()`, then `rename()`                      |
-| `/etc/authelia/users.yml`                 | YAML   | Temp file in `/etc/authelia`, `fsync()`, `rename()` (no sudo) |
+| File                                      | Format | Write Pattern                                                       |
+| ----------------------------------------- | ------ | ------------------------------------------------------------------- |
+| `/etc/lamalibre/lamaste/panel.json`       | JSON   | Write `.tmp` then `rename()`                                        |
+| `/etc/lamalibre/lamaste/tunnels.json`     | JSON   | Write `.tmp`, `fsync()`, then `rename()`                            |
+| `/etc/lamalibre/lamaste/sites.json`       | JSON   | Write `.tmp`, `fsync()`, then `rename()`                            |
+| `/etc/lamalibre/lamaste/invitations.json` | JSON   | Write `.tmp`, `fsync()`, then `rename()`                            |
+| `/etc/authelia/users.yml`                 | YAML   | Temp file in `/etc/authelia`, `fsync()`, `rename()` (no sudo)       |
+| `/etc/lamalibre/lamaste/state.db`         | SQLite | WAL, transactions; numbered migrations (`0013`: the user directory) |
+| `/etc/lamalibre/lamaste/gatekeeper.db`    | SQLite | WAL, transactions; numbered migrations                              |
 
 The atomic write pattern (write to temporary file, sync, rename) ensures that a crash during a write does not corrupt the primary file. The `rename()` system call is atomic on POSIX filesystems.
 
@@ -320,6 +324,11 @@ The atomic write pattern (write to temporary file, sync, rename) ensures that a
 - **`/etc/authelia/.secrets.json`** contains the JWT secret. If this changes, all active Authelia sessions are invalidated and users must re-authenticate.
 - **`/etc/authelia/db.sqlite3`** contains Authelia session data and TOTP registration states. It can be regenerated (users re-enroll TOTP), but this is disruptive.
 - **Let's Encrypt account credentials** in `/etc/letsencrypt/accounts/` are tied to the email address used during registration. If lost, certbot creates a new account on next run.
+- **`state.db` holds the user directory.** Each user's `userId` — what agent-hosted plugins key their data on — exists only there; `users.yml` has none. **Losing `state.db` re-keys every user**: the panel rebuilds the directory from `users.yml` with new user ids and a new `directoryId`, and every plugin's agent half, seeing another directory, replays its audience from 0 — its old rows are marked removed and the same people arrive under new ids, so their history in the plugin is no longer joined to them. Tombstones and erasure records are lost too. Keep `state.db` in every backup.
+- **Restoring an older `state.db`** keeps the `directoryId` but moves the audiences back: an agent half whose cursor is now ahead of the panel's head is sent a full replay, which brings it in line with the restored audiences (users created since the backup come back from `users.yml` with new ids).
+- **Erasures survive a relay restore in the agent halves.** An erasure made after the backup is lost from the relay — the restored directory has the user's tombstone again, perhaps a live user, and its audiences may send the user as a member or with their last name. An agent half that applied the erasure never writes the user back: an erasure is **sticky** in its projection (a later `upsert` or `remove` for an erased user leaves the row the bare id, calls none of the plugin's hooks, and counts as a mismatch at the daily reconcile — `identity.reconcile.mismatches` in the audit log is how a restore shows up). The relay does not know the user was erased: **erase the user again** to record it (and to scrub what the restore brought back on the relay: the tombstone, invitations, Gatekeeper's access-request log). A restored `gatekeeper.db` may bring grants back under a deleted user's username; the panel clears them before the username is given to anyone. A restored Authelia database may bring a deleted user's second factors back; they are deleted before the username is given to anyone, too. Telling a restored relay from the live one — rotating the `directoryId` on restore so every agent half replays against the restored directory — is **not done yet** (future work); until then, after restoring `state.db`, erase again every user erased since the backup.
+- **A plugin's audience is its erasure ledger.** Its rows stay when the plugin is uninstalled while an agent keeps its data, or when it stops declaring identity; they go only when no data of the plugin is left anywhere (uninstall with purge, retained data purged or forgotten). A backup of `state.db` therefore carries the erasures every such plugin still owes.
+- **SQLite files** (`state.db`, `gatekeeper.db`) run in WAL mode: for a consistent copy, stop `lamalibre-lamaste-serverd` and `lamalibre-lamaste-gatekeeper` while the archive is made, and restore the `-wal` and `-shm` files with the database (or neither). Both are `0600`, owned by `lamaste`.
 - **Settings of agent-hosted plugins** are kept by each plugin's agent half on its hosting agent — `settings.json` and `secrets.json` in its data directory (`/var/lib/lamalibre/apps/<route>/` for an agent half Lamaste installs) — not on the relay. The relay's `state.db` holds a cache of the non-secret values only, which it reads again from the agent half whenever the settings are read while the hosting is up. A relay backup therefore restores no plugin secret: back them up with the agent half's data. An agent half reads its restored files when it starts ([Agent-Hosted Plugins](../04-api-reference/agent-hosted-plugins.md#settings)); since restored files carry another revision than the one Lamaste last wrote, the relay's next read records the restore as a change made outside Lamaste (`plugin.settings.changed-outside-lamaste`, with the names of the settings that differ) and warns the administrators — expected after a restore you made.
 
 ## Quick Reference

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

@@ -136,6 +136,45 @@ Each log line contains an ISO timestamp and the log message:
 - **authelia** logs show authentication attempts, including failed TOTP entries
 - **lamalibre-lamaste-serverd** logs show API requests and any server-side errors
 
+### Logs and Personal Data
+
+What each log on the server keeps about people, and for how long — what an [erasure](../04-api-reference/users.md#erasing-a-removed-user) cannot reach:
+
+| Log                                               | What it keeps                                                                                                                                                                                                                                                                                                            | Retention                                                              |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Panel and Gatekeeper (journald)                   | One metadata line per request: method, the **route pattern** (`/api/users/:username` — never the URL, never a query), status, duration, the caller's certificate role. The client address only for certificate holders (administrators, agents) — never for a person. The panel's own lines name users by `userId` alone | journald's limits (below)                                              |
+| nginx access log (`/var/log/nginx/access.log`)    | Every request's client address and full URL — an administrator's request names the user it changes (`/api/users/alice`), a desktop user's or a tunneled app's request is logged with its address                                                                                                                         | Ubuntu's logrotate: daily, 14 files (`/etc/logrotate.d/nginx`)         |
+| Authelia (`/var/log/authelia/authelia.log`)       | Sign-in attempts with the username and the client address; Authelia also keeps an authentication log in its database                                                                                                                                                                                                     | **Not rotated** by Lamaste: the file grows until you rotate it (below) |
+| Other units (journald: chisel, the agents' sync…) | Connections by agent label; no user data                                                                                                                                                                                                                                                                                 | journald's limits (below)                                              |
+
+**journald** keeps entries until its size limit (by default 10% of the file system, at most 4 GiB) — on a small droplet that can be months. To keep at most two weeks:
+
+```bash
+sudo mkdir -p /etc/systemd/journald.conf.d
+printf '[Journal]\nMaxRetentionSec=14day\n' | sudo tee /etc/systemd/journald.conf.d/lamaste-retention.conf
+sudo systemctl restart systemd-journald
+sudo journalctl --vacuum-time=14d    # drop what is older now
+```
+
+**nginx**: shorten `rotate 14` in `/etc/logrotate.d/nginx` to keep fewer days, or `sudo truncate -s 0 /var/log/nginx/access.log.*` after an erasure that must reach them now.
+
+**Authelia's log file**: rotate it, e.g. `/etc/logrotate.d/authelia`:
+
+```
+/var/log/authelia/authelia.log {
+    daily
+    rotate 14
+    missingok
+    notifempty
+    compress
+    delaycompress
+    copytruncate
+    su lamaste-authelia lamaste-authelia
+}
+```
+
+Backups taken before an erasure keep everything they copied; age them out on the same schedule.
+
 ### What Metrics to Watch
 
 For day-to-day monitoring, these are the most important signals:

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.4.1 --uninstall
+npx @lamalibre/create-lamaste@4.5.0 --uninstall
 ```
 
 This prints the same steps listed below.
@@ -295,6 +295,7 @@ For reference, here is a complete list of everything the installer and onboardin
 - `/etc/nginx/sites-available/lamalibre-lamaste-agent-panel-*`
 - Corresponding symlinks in `/etc/nginx/sites-enabled/`
 - `/etc/nginx/snippets/lamalibre-lamaste-mtls.conf`, `lamalibre-lamaste-authz-cache.conf`
+- `/etc/nginx/conf.d/lamalibre-lamaste-backend-cookie.conf` (the map the tunnel vhosts take the backends' `Cookie` from — remove it after the vhosts that use it)
 
 **System configuration:**