@lamalibre/create-lamaste 4.0.0

package/vendor/docs/03-architecture/state-management.md

@@ -0,0 +1,529 @@
+# State Management Architecture
+
+> Lamaste stores all state in JSON and YAML files on disk — no database, no external services. State changes use atomic writes to prevent corruption from crashes or power loss.
+
+## In Plain English
+
+Lamaste does not use a database. All configuration and state is stored in plain files on the VPS:
+
+- `panel.json` holds the system configuration (IP address, domain, onboarding progress)
+- `tunnels.json` holds the list of configured tunnels
+- `sites.json` holds the list of configured static sites
+- `invitations.json` holds pending user invitations
+- `users.yml` holds the Authelia user database (usernames, password hashes, TOTP secrets)
+
+These files are small (a few kilobytes each) and are read/written atomically — meaning the system writes to a temporary file first, then renames it into place. If the server crashes mid-write, the old file is preserved intact. You never end up with a half-written, corrupted file.
+
+This approach works because Lamaste manages a small amount of state (one admin, a handful of tunnels and users). A database would add RAM overhead and operational complexity for no benefit at this scale.
+
+## Overview
+
+```
+/etc/lamalibre/lamaste/
+├── panel.json              ← Central config (IP, domain, onboarding state)
+├── tunnels.json            ← Tunnel definitions
+├── sites.json              ← Static site definitions
+├── chisel-credentials.json ← Per-agent Chisel credentials
+├── chisel-users            ← Chisel authfile, rendered from credentials + tunnels.json (0640, group lamaste-chisel)
+├── chisel-sentinel         ← Password of the no-grants sentinel Chisel user
+├── invitations.json        ← Pending user invitations
+├── plugins.json            ← Plugin registry (installed plugins, enabled state)
+├── ticket-scopes.json      ← Ticket scope registry (scopes, instances, assignments)
+├── tickets.json            ← Ticket and session store
+├── storage-config.json     ← Storage server registry and plugin bindings
+├── storage-master.key      ← 32-byte master key for storage credential encryption
+├── groups.json             ← Lamaste groups (separate from Authelia groups)
+├── access-grants.json      ← Generic access grants (principal → resource)
+├── gatekeeper.json         ← Gatekeeper settings (cache TTL, admin contact, logging)
+├── access-request-log.json ← Optional denied access log (for admin review)
+└── pki/
+    ├── ca.key              ← CA private key
+    ├── ca.crt              ← CA certificate
+    ├── client.key          ← Client private key
+    ├── client.crt          ← Client certificate
+    ├── client.p12          ← PKCS12 bundle for browser import
+    ├── .p12-password       ← PKCS12 password
+    ├── self-signed.pem     ← Self-signed TLS cert for IP vhost
+    ├── self-signed-key.pem ← Self-signed TLS key for IP vhost
+    ├── revoked.json        ← Revoked certificate serial numbers
+    ├── enrollment-tokens.json ← One-time enrollment tokens
+    └── agents/             ← Agent certificate storage
+        ├── registry.json   ← Metadata for all agent certs
+        └── <label>/        ← Per-agent directory
+            ├── client.key  ← Agent private key
+            ├── client.crt  ← Agent certificate
+            └── client.p12  ← Agent PKCS12 bundle
+
+/etc/authelia/
+├── configuration.yml       ← Authelia main config
+├── users.yml               ← User database (usernames, bcrypt hashes, groups)
+├── .secrets.json           ← JWT + session + storage encryption secrets
+├── db.sqlite3              ← Authelia session/TOTP storage
+└── notifications.txt       ← Notification log (filesystem notifier)
+
+/var/www/lamaste/
+└── <site-uuid>/            ← Static site file roots (one per site)
+    ├── index.html
+    └── ...
+```
+
+## Atomic Writes Pattern
+
+All JSON state files use the same atomic write pattern, implemented in `packages/lamaste-serverd/src/lib/state.js` and `packages/lamaste-serverd/src/lib/config.js`:
+
+```
+1. Serialize data to JSON string
+2. Write to <path>.tmp in the same directory
+3. Open the temp file and call fd.sync() (fsync)
+4. Rename temp file to final path
+```
+
+In code:
+
+```javascript
+export async function writeTunnels(tunnels) {
+  const filePath = tunnelsPath();
+  const tmpPath = `${filePath}.tmp`;
+
+  const content = JSON.stringify(tunnels, null, 2) + '\n';
+  await writeFile(tmpPath, content, 'utf-8');
+
+  // fsync: flush data to disk before rename
+  const fd = await open(tmpPath, 'r');
+  await fd.sync();
+  await fd.close();
+
+  await rename(tmpPath, filePath);
+}
+```
+
+**Why this works:**
+
+- `rename()` is atomic on POSIX filesystems — it either completes fully or not at all
+- `fd.sync()` ensures the data is flushed to the physical disk before the rename
+- If the process crashes during `writeFile`, only the `.tmp` file is affected — the original state file is untouched
+- If the process crashes after `fd.sync()` but before `rename()`, the `.tmp` file has valid data and the original is untouched
+- The worst case is losing the most recent write, which preserves the previous consistent state
+
+**Why the temp file is in the same directory:**
+
+- `rename()` is only atomic within the same filesystem
+- `/etc/lamalibre/lamaste/tunnels.json.tmp` and `/etc/lamalibre/lamaste/tunnels.json` are on the same filesystem, so the rename is guaranteed to be atomic
+
+## Config Schema (`panel.json`)
+
+The central configuration file, validated by Zod on every load and update.
+
+**Location:** `/etc/lamalibre/lamaste/panel.json` (production) or `dev/panel.json` (development)
+
+**Schema:**
+
+```json
+{
+  "ip": "203.0.113.42",
+  "domain": "example.com",
+  "email": "admin@example.com",
+  "dataDir": "/etc/lamalibre/lamaste",
+  "staticDir": "/opt/lamalibre/lamaste/lamaste-server-ui/dist",
+  "maxSiteSize": 524288000,
+  "onboarding": {
+    "status": "COMPLETED"
+  }
+}
+```
+
+**Field definitions:**
+
+| Field               | Type                     | Required | Description                                                             |
+| ------------------- | ------------------------ | -------- | ----------------------------------------------------------------------- |
+| `ip`                | `string`                 | Yes      | VPS public IP address (detected during install)                         |
+| `domain`            | `string \| null`         | Yes      | Base domain (set during onboarding, null before)                        |
+| `email`             | `string (email) \| null` | Yes      | Admin email for Let's Encrypt (set during onboarding)                   |
+| `dataDir`           | `string`                 | Yes      | Path to state directory (`/etc/lamalibre/lamaste`)                      |
+| `serverId`          | `string (uuid)`          | No       | Auto-generated UUIDv4, bucket prefix for multi-server storage isolation |
+| `staticDir`         | `string`                 | No       | Path to lamaste-server-ui dist (overrides default resolution)           |
+| `maxSiteSize`       | `number`                 | No       | Maximum static site size in bytes (default: 500 MB)                     |
+| `adminAuthMode`     | `enum`                   | No       | `"p12"` (default) or `"hardware-bound"`                                 |
+| `panel2fa`          | `object`                 | No       | Built-in TOTP 2FA configuration                                         |
+| `sessionSecret`     | `string \| null`         | No       | HMAC key for signed session cookies (default: null)                     |
+| `onboarding.status` | `enum`                   | Yes      | Current onboarding state                                                |
+
+**Zod validation:**
+
+```javascript
+const ConfigSchema = z.object({
+  ip: z.string().min(1),
+  domain: z.string().nullable(),
+  email: z.string().email().nullable(),
+  dataDir: z.string().min(1),
+  serverId: z.string().uuid().optional(),
+  staticDir: z.string().optional(),
+  maxSiteSize: z
+    .number()
+    .optional()
+    .default(500 * 1024 * 1024),
+  adminAuthMode: z.enum(['p12', 'hardware-bound']).optional().default('p12'),
+  panel2fa: z
+    .object({
+      enabled: z.boolean(),
+      secret: z.string().nullable(),
+      setupComplete: z.boolean(),
+    })
+    .optional()
+    .default({ enabled: false, secret: null, setupComplete: false }),
+  sessionSecret: z.string().nullable().optional().default(null),
+  onboarding: z.object({
+    status: z.enum(['FRESH', 'DOMAIN_SET', 'DNS_READY', 'PROVISIONING', 'COMPLETED']),
+  }),
+});
+```
+
+Validation runs:
+
+- At server startup (`loadConfig()`)
+- Before every config update (`updateConfig()`)
+- Invalid data throws a Zod error, caught by the error handler and returned as a 400
+
+**Config loading chain:**
+
+```
+1. Check LAMALIBRE_LAMASTE_CONFIG environment variable → use if set
+2. Check NODE_ENV:
+   - "development" (or unset) → dev/panel.json relative to package root
+   - "production" → /etc/lamalibre/lamaste/panel.json
+3. Read and parse JSON
+4. Validate with Zod schema
+5. Cache in module-level variable
+```
+
+**Config updates (`updateConfig`):**
+
+```javascript
+export async function updateConfig(patch) {
+  // Deep clone current config
+  const merged = structuredClone(config);
+
+  // Merge patch (onboarding and panel2fa are merged as sub-objects, others replaced)
+  for (const key of Object.keys(patch)) {
+    if (key === 'onboarding' && typeof patch.onboarding === 'object' && patch.onboarding !== null) {
+      merged.onboarding = { ...merged.onboarding, ...patch.onboarding };
+    } else if (
+      key === 'panel2fa' &&
+      typeof patch.panel2fa === 'object' &&
+      patch.panel2fa !== null
+    ) {
+      merged.panel2fa = { ...merged.panel2fa, ...patch.panel2fa };
+    } else {
+      merged[key] = patch[key];
+    }
+  }
+
+  // Re-validate
+  const validated = ConfigSchema.parse(merged);
+
+  // Atomic write
+  const tmpPath = `${configPath}.tmp`;
+  await writeFile(tmpPath, JSON.stringify(validated, null, 2) + '\n', {
+    encoding: 'utf-8',
+    mode: 0o600,
+  });
+
+  // fsync: flush data to disk before rename
+  const fd = await open(tmpPath, 'r');
+  await fd.sync();
+  await fd.close();
+
+  await rename(tmpPath, configPath);
+
+  // Update cache
+  config = validated;
+  return structuredClone(config);
+}
+```
+
+The `onboarding` and `panel2fa` fields get special merge treatment — updating `{ onboarding: { status: 'COMPLETED' } }` or `{ panel2fa: { enabled: true } }` preserves other sub-fields rather than replacing the entire object.
+
+All reads via `getConfig()` return a `structuredClone`, preventing callers from accidentally mutating the cached config.
+
+## Onboarding State Machine
+
+The onboarding process follows a linear state progression stored in `panel.json`:
+
+```
+FRESH ──────────► DOMAIN_SET ──────────► DNS_READY
+  │                    │                      │
+  │ POST /domain       │ POST /verify-dns     │ POST /provision
+  │ Sets domain+email  │ Confirms DNS ok      │ Starts provisioning
+  │                    │                      │
+  │                    │                      ▼
+  │                    │               PROVISIONING
+  │                    │                      │
+  │                    │                      │ Background task completes
+  │                    │                      │
+  │                    │                      ▼
+  │                    │                 COMPLETED
+  │                    │                      │
+  └────────────────────┘──────────────────────┘
+                                              │
+                                   Onboarding routes → 410 Gone
+                                   Management routes → accessible
+```
+
+State transitions are enforced at multiple levels:
+
+1. **Route guards** — `onboardingOnly()` returns 410 for any onboarding route when status is `COMPLETED`; `managementOnly()` returns 503 when status is not `COMPLETED`
+2. **Provisioning endpoint** — validates that status is `DNS_READY` or `PROVISIONING` before starting
+3. **Domain endpoint** — validates that status is `FRESH`
+4. **DNS endpoint** — validates that status is `DOMAIN_SET`
+
+Once provisioning completes and status is set to `COMPLETED`, onboarding routes are permanently locked out (410 Gone). The only way to re-run onboarding would be to manually edit `panel.json`, which is an intentional safety measure.
+
+## Tunnel State (`tunnels.json`)
+
+Stored at `/etc/lamalibre/lamaste/tunnels.json`. An array of tunnel objects.
+
+**Example:**
+
+```json
+[
+  {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "subdomain": "myapp",
+    "fqdn": "myapp.example.com",
+    "port": 3000,
+    "description": "My Web App",
+    "type": "app",
+    "accessMode": "restricted",
+    "agentLabel": "laptop",
+    "maxBodySizeMb": 10,
+    "enabled": true,
+    "createdAt": "2024-03-14T10:30:00.000Z"
+  },
+  {
+    "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
+    "subdomain": "api",
+    "fqdn": "api.example.com",
+    "port": 8080,
+    "description": "API Server",
+    "type": "app",
+    "accessMode": "authenticated",
+    "agentLabel": "build-server",
+    "maxBodySizeMb": 100,
+    "enabled": true,
+    "createdAt": "2024-03-14T11:00:00.000Z"
+  }
+]
+```
+
+**Operations:**
+
+- `readTunnels()` — returns the array, or `[]` if the file does not exist
+- `writeTunnels(tunnels)` — atomic write of the full array
+
+Read returns `[]` for missing files (ENOENT), enabling the system to start with no tunnels defined.
+
+**Tunnel lifecycle:**
+
+1. `POST /api/tunnels` — issues TLS cert, writes nginx vhost, adds the tunnel object (with its `agentLabel`)
+2. `PATCH /api/tunnels/:id` — moves the tunnel to another agent, re-renders its vhost (access mode, body limit), or enables/disables it
+3. `DELETE /api/tunnels/:id` — removes nginx vhost, removes the tunnel object
+4. On all: the full array is written atomically, **then** Chisel is synced — `chisel-users` is re-rendered from the new state (each agent may bind only its enabled tunnels' ports). Chisel reloads the file itself; it is restarted only when a grant or password was withdrawn. The authfile is derived state; `tunnels.json` and `chisel-credentials.json` are the sources of truth
+5. `DELETE /api/certs/agent/:label` (revocation) — the agent's app and plugin tunnels lose their `agentLabel` (unassigned), and its `agent-<label>` panel tunnel is removed
+6. At startup (background, fail closed): an ownerless `agent-<label>` panel tunnel is bound to the agent it names when that agent is active; other ownerless tunnels (from versions before tunnel ownership) are bound to the sole active agent, or left unassigned when there are several. Then the pinned Chisel binary, the unit and the authfile are re-established — and Chisel is stopped if they cannot be
+
+Every one of these workflows runs under the single tunnel lock (`withTunnelLock` in `@lamalibre/lamaste@4.0.0/server`), with its validation inside the lock.
+
+## Site State (`sites.json`)
+
+Stored at `/etc/lamalibre/lamaste/sites.json`. An array of site objects.
+
+**Example:**
+
+```json
+[
+  {
+    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "name": "blog",
+    "fqdn": "blog.example.com",
+    "type": "managed",
+    "spaMode": false,
+    "autheliaProtected": false,
+    "rootPath": "/var/www/lamaste/b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "createdAt": "2024-03-14T12:00:00.000Z"
+  }
+]
+```
+
+**Operations:**
+
+- `readSites()` — returns the array, or `[]` if the file does not exist
+- `writeSites(sites)` — atomic write of the full array
+
+Same atomic write pattern and ENOENT handling as tunnels.
+
+Custom-domain sites may also carry `aliases` (hostnames redirected with a 301 to the site's `fqdn`); see the [Sites API](../04-api-reference/sites.md). The full field list is in [Config Files](../06-reference/config-files.md).
+
+## YAML Writes for Authelia (`users.yml`)
+
+Authelia reads its user database from `/etc/authelia/users.yml` at runtime. Lamaste writes this file when creating, updating, or deleting users.
+
+**Format:**
+
+```yaml
+users:
+  admin:
+    displayname: admin
+    password: $2b$12$... # bcrypt hash
+    email: admin@lamaste.local
+    groups:
+      - admins
+  alice:
+    displayname: alice
+    password: $2b$12$...
+    email: alice@example.com
+    groups:
+      - admins
+```
+
+**Write pattern:**
+
+The Panel Server writes Authelia's files itself, without sudo (`writeAutheliaFile()` in `packages/core/lib/src/server/authelia.ts`): `/etc/authelia` is owned by `lamaste` with group `lamaste-authelia` and the setgid bit (`2770`), so the panel can create files there and every new file belongs to Authelia's group.
+
+1. Writes a temp file in `/etc/authelia/` (`open(..., 'wx')`), sets its mode, `fsync()`s it
+2. `rename()`s it over the destination — atomic on the same filesystem, so Authelia never reads a partial file
+3. The mode decides Authelia's access: `users.yml` `0660` (Authelia rewrites it when a user changes a password), `configuration.yml` `0640`, `.secrets.json` `0600` (the panel only)
+
+**Critical invariant:** After writing `users.yml`, the Authelia service must be restarted to pick up changes. Authelia does not watch the file for changes. The Panel Server calls `reloadAuthelia()` (which runs `systemctl restart authelia`) after every user modification.
+
+**Safety rule:** The Panel Server prevents deleting the last user in the Authelia database. Without at least one user, no one could authenticate to access tunneled apps.
+
+## Storage Server Registry (`storage-config.json`)
+
+The storage system manages S3-compatible object storage servers and their bindings to plugins. Storage credentials (access key, secret key) are encrypted at rest using AES-256-GCM with scrypt key derivation.
+
+**Encryption scheme:**
+
+1. A 32-byte master key is generated once and stored at `/etc/lamalibre/lamaste/storage-master.key` (mode 0600)
+2. For each credential, a random 16-byte salt is generated
+3. The master key is passed through scrypt (N=16384, r=8, p=1) with the salt to derive a 32-byte encryption key
+4. The credential is encrypted with AES-256-GCM using a random 12-byte IV
+5. The output is packed as `[salt (16)] [iv (12)] [authTag (16)] [ciphertext (...)]` and base64-encoded
+
+**State file (`storage-config.json`):**
+
+```json
+{
+  "servers": [
+    {
+      "id": "uuid",
+      "label": "my-storage",
+      "provider": "digitalocean",
+      "region": "fra1",
+      "bucket": "my-bucket",
+      "endpoint": "https://fra1.digitaloceanspaces.com",
+      "accessKeyEncrypted": "<base64-encoded encrypted credential>",
+      "secretKeyEncrypted": "<base64-encoded encrypted credential>",
+      "registeredAt": "2026-03-30T10:00:00.000Z"
+    }
+  ],
+  "bindings": [
+    {
+      "pluginName": "sync",
+      "storageServerId": "uuid",
+      "boundAt": "2026-03-30T10:05:00.000Z"
+    }
+  ]
+}
+```
+
+**Concurrency:** All read-modify-write operations are serialized via a promise-chain mutex. Writes use the same atomic pattern (temp file, fsync, rename).
+
+## Config Path Resolution
+
+Different config files are resolved through different mechanisms:
+
+| File               | Resolution                                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `panel.json`       | `LAMALIBRE_LAMASTE_CONFIG` env var → `dev/panel.json` (dev) → `/etc/lamalibre/lamaste/panel.json` (prod) |
+| `tunnels.json`     | `LAMALIBRE_LAMASTE_STATE_DIR` env var → `/etc/lamalibre/lamaste` + `/tunnels.json`                       |
+| `sites.json`       | `LAMALIBRE_LAMASTE_STATE_DIR` env var → `/etc/lamalibre/lamaste` + `/sites.json`                         |
+| `invitations.json` | `LAMALIBRE_LAMASTE_STATE_DIR` env var → `/etc/lamalibre/lamaste` + `/invitations.json`                   |
+| `users.yml`        | Hardcoded: `/etc/authelia/users.yml`                                                                     |
+| PKI files          | `LAMALIBRE_LAMASTE_PKI_DIR` env var → `/etc/lamalibre/lamaste/pki`                                       |
+
+Environment variables allow overriding paths for development and testing without modifying code.
+
+## File Permissions
+
+| File                      | Mode   | Owner                      | Rationale                                                            |
+| ------------------------- | ------ | -------------------------- | -------------------------------------------------------------------- |
+| `panel.json`              | `0600` | `lamaste:lamaste`          | Contains sensitive config, owner-only access                         |
+| `tunnels.json`            | `0600` | `lamaste:lamaste`          | Written by Panel Server                                              |
+| `sites.json`              | `0600` | `lamaste:lamaste`          | Written by Panel Server                                              |
+| `chisel-credentials.json` | `0600` | `lamaste:lamaste`          | Per-agent Chisel passwords                                           |
+| `chisel-users`            | `0640` | `lamaste:lamaste-chisel`   | Chisel authfile (read by the Chisel process, group `lamaste-chisel`) |
+| `chisel-sentinel`         | `0600` | `lamaste:lamaste`          | Sentinel Chisel user password                                        |
+| `invitations.json`        | `0600` | `lamaste:lamaste`          | Written by Panel Server                                              |
+| `storage-config.json`     | `0600` | `lamaste:lamaste`          | Storage registry (credentials AES-256-GCM encrypted)                 |
+| `storage-master.key`      | `0600` | `lamaste:lamaste`          | 32-byte master key for storage encryption                            |
+| `groups.json`             | `0600` | `lamaste:lamaste`          | Lamaste group definitions and membership                             |
+| `access-grants.json`      | `0600` | `lamaste:lamaste`          | Generic access grants (principal → resource)                         |
+| `gatekeeper.json`         | `0600` | `lamaste:lamaste`          | Gatekeeper settings (cache TTL, logging)                             |
+| `access-request-log.json` | `0600` | `lamaste:lamaste`          | Optional denied access log                                           |
+| `pki/ca.key`              | `0600` | `lamaste:lamaste`          | CA private key — most sensitive file                                 |
+| `pki/ca.crt`              | `0644` | `lamaste:lamaste`          | CA cert — needs to be readable by nginx                              |
+| `pki/client.key`          | `0600` | `lamaste:lamaste`          | Client private key                                                   |
+| `pki/client.crt`          | `0644` | `lamaste:lamaste`          | Client cert                                                          |
+| `pki/client.p12`          | `0600` | `lamaste:lamaste`          | PKCS12 bundle with private key                                       |
+| `pki/.p12-password`       | `0600` | `lamaste:lamaste`          | Password for PKCS12 bundle                                           |
+| `users.yml`               | `0660` | `lamaste:lamaste-authelia` | Contains bcrypt password hashes; Authelia rewrites it                |
+| `configuration.yml`       | `0640` | `lamaste:lamaste-authelia` | Contains JWT and session secrets; Authelia reads it                  |
+| `.secrets.json`           | `0600` | `lamaste:lamaste-authelia` | Encryption keys; the panel only                                      |
+
+The PKI directory belongs to `lamaste` because the panel is the CA (it signs agent certificates itself); the installer creates it as root and hands it over, and every redeploy re-applies that ownership. Authelia's files belong to `lamaste` with the `lamaste-authelia` group, so the panel reads and writes them directly and Authelia (running as `lamaste-authelia`) reads them through its group. Nothing here is read or written with `sudo`.
+
+## Concurrency Safety
+
+The Panel Server is a single-process Node.js application, but a single-threaded event loop does not serialize asynchronous workflows: two requests that each read `tunnels.json`, await a certificate or an nginx test, and then write it back would interleave, and both could pass the same uniqueness check. Serialization is therefore explicit:
+
+**Tunnel state** is guarded by one promise-chain lock, `withTunnelLock` in `@lamalibre/lamaste@4.0.0/server`'s `tunnels.ts`. Every tunnel workflow — create, delete, toggle, assign, reconfigure, the combined `PATCH /api/tunnels/:id`, releasing a revoked agent's tunnels, and startup reconciliation — takes it for its whole duration, and does its validation (subdomain and port uniqueness, reserved ports, agent checks, authorization against the current entry) inside it.
+
+**Chisel authfile renders** are serialized by a promise-chain mutex in `chisel-users.ts`, keyed by the credentials file, around every render (enroll, revoke, rotate, tunnel change). The daemon's `syncChisel()` renders after the tunnel state is written and restarts Chisel (`systemctl try-restart`) only when the render withdrew something.
+
+This ensures that concurrent tunnel or credential operations never interleave state or authfile writes.
+
+## Key Files
+
+| File                                            | Role                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `packages/lamaste-serverd/src/lib/storage.js`   | Storage server registry, plugin bindings, AES-256-GCM encryption |
+| `packages/lamaste-gatekeeper/src/lib/groups.ts` | Lamaste group read/write with atomic writes                      |
+| `packages/lamaste-gatekeeper/src/lib/grants.ts` | Access grant read/write with atomic writes                       |
+| `packages/lamaste-serverd/src/lib/config.js`    | Config loading, Zod validation, atomic updates                   |
+| `packages/lamaste-serverd/src/lib/state.js`     | tunnels.json + sites.json atomic read/write                      |
+| `packages/core/lib/src/server/authelia.ts`      | users.yml / configuration.yml read and atomic write (no sudo)    |
+| `packages/lamaste-serverd/src/lib/files.js`     | Static site file operations                                      |
+| `packages/create-lamaste/src/tasks/panel.js`    | Initial panel.json creation                                      |
+| `packages/create-lamaste/src/tasks/mtls.js`     | Initial PKI file creation                                        |
+
+## Design Decisions
+
+### Why JSON instead of SQLite?
+
+SQLite would work, but adds a binary dependency and ~1 MB of RAM for the database engine. JSON files can be read with `cat`, edited with any text editor, and backed up with `cp`. At the current scale (tens of entries), JSON parsing is effectively free. The atomic write pattern provides the same crash-safety guarantees as SQLite's WAL journal.
+
+### Why not watch files for changes?
+
+File watching (via `fs.watch` or inotify) adds complexity and platform-specific behavior. Since all state modifications go through the Panel Server API, the in-memory cache is always consistent with the disk. Authelia is the exception — it reads `users.yml` independently — which is why a restart is required after modifications.
+
+### Why structuredClone for getConfig?
+
+Without cloning, `getConfig()` would return a reference to the cached config object. Any modification to the returned object (even accidental) would corrupt the cache. `structuredClone` creates a deep copy, making the config effectively immutable from the caller's perspective. This is a small performance cost that prevents a class of subtle bugs.
+
+### Why fsync before rename?
+
+On Linux, `writeFile` may return before data is flushed to the physical disk (the data may be in the kernel's page cache). If power is lost at this point, the temp file could be empty or corrupted. `fd.sync()` forces the data to disk, ensuring the rename always produces a valid file. This is the standard pattern for durable writes in database systems.
+
+### Why YAML for Authelia users instead of JSON?
+
+Authelia's file-based authentication backend expects YAML format. This is an external constraint, not a choice. The Panel Server uses the `js-yaml` library for serialization and reads the file directly (it owns it).