@lamalibre/create-lamaste 4.6.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/create-lamaste",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "One-command setup for secure reverse tunnels with a management dashboard",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -43,7 +43,7 @@
     "mtls"
   ],
   "dependencies": {
-    "@lamalibre/lamaste": "^4.6.0",
+    "@lamalibre/lamaste": "^4.7.0",
     "chalk": "^5.3.0",
     "execa": "^9.0.0",
     "listr2": "^8.0.0"

package/scripts/bundle-vendor.js

@@ -13,6 +13,7 @@ import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertProductionBundle } from '../../../../scripts/assert-production-bundle.js';
+import { workspaceVersions, writePinnedManifest } from './pin-release.js';
 
 const thisDir = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(thisDir, '..');
@@ -24,6 +25,10 @@ async function main() {
   await rm(vendorDir, { recursive: true, force: true });
   await mkdir(vendorDir, { recursive: true });
 
+  // Each vendored manifest names this release's own packages exactly
+  // (pin-release.js), so the relay's `npm install` never mixes releases.
+  const versions = await workspaceVersions(monorepoRoot);
+
   // --- lamaste-serverd: package.json + src/ ---
   const serverSrc = join(monorepoRoot, 'packages', 'server', 'daemon');
   if (!existsSync(serverSrc)) {
@@ -32,7 +37,11 @@ async function main() {
 
   const serverDest = join(vendorDir, 'serverd');
   await mkdir(serverDest, { recursive: true });
-  await cp(join(serverSrc, 'package.json'), join(serverDest, 'package.json'));
+  await writePinnedManifest(
+    join(serverSrc, 'package.json'),
+    join(serverDest, 'package.json'),
+    versions,
+  );
   await cp(join(serverSrc, 'src'), join(serverDest, 'src'), {
     recursive: true,
   });
@@ -49,7 +58,11 @@ async function main() {
   }
   const serverCliDest = join(vendorDir, 'server');
   await mkdir(serverCliDest, { recursive: true });
-  await cp(join(serverCliSrc, 'package.json'), join(serverCliDest, 'package.json'));
+  await writePinnedManifest(
+    join(serverCliSrc, 'package.json'),
+    join(serverCliDest, 'package.json'),
+    versions,
+  );
   await cp(join(serverCliSrc, 'bin'), join(serverCliDest, 'bin'), { recursive: true });
   await cp(join(serverCliSrc, 'src'), join(serverCliDest, 'src'), { recursive: true });
   console.error('Bundled vendor/server from lamaste-server CLI (package.json + bin/ + src/)');
@@ -81,7 +94,11 @@ async function main() {
   }
   const gatekeeperDest = join(vendorDir, 'gatekeeper');
   await mkdir(gatekeeperDest, { recursive: true });
-  await cp(join(gatekeeperSrc, 'package.json'), join(gatekeeperDest, 'package.json'));
+  await writePinnedManifest(
+    join(gatekeeperSrc, 'package.json'),
+    join(gatekeeperDest, 'package.json'),
+    versions,
+  );
   await cp(gatekeeperDist, join(gatekeeperDest, 'dist'), { recursive: true });
   console.error('Bundled vendor/gatekeeper (package.json + dist/)');
 

package/scripts/lamaste-priv

@@ -81,21 +81,37 @@ class UsageError extends Error {}
 // ---------------------------------------------------------------------------
 
 const LABEL = '[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?';
+/** A full hostname, lower case, two labels at least — what names a vhost since the multi-domain relay. */
+const HOST = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+';
 const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
 
-/** Vhosts the panel writes. */
+/**
+ * Vhosts the panel writes: the panel's and chisel's (primary domain), one
+ * auth portal per domain, a tunnel's by its full hostname, a site's by id.
+ */
 const PANEL_SITE_RE = new RegExp(
-  `^lamalibre-lamaste-(?:panel-domain|auth|tunnel|app-${LABEL}|agent-panel-${LABEL}|site-${UUID})$`,
+  `^lamalibre-lamaste-(?:panel-domain|tunnel|auth-${HOST}|app-${HOST}|agent-panel-${HOST}|site-${UUID})$`,
 );
 
+/**
+ * Vhost names before the multi-domain relay — the auth portal and tunnels
+ * by subdomain alone. The panel renames them at start; it may still link,
+ * unlink, back up, restore and remove them, but never write one.
+ */
+const LEGACY_SITE_RE = new RegExp(`^lamalibre-lamaste-(?:auth|app-${LABEL}|agent-panel-${LABEL})$`);
+
 /** Vhosts create-lamaste writes that the panel may only switch on and off. */
 const TOGGLE_ONLY_SITES = new Set(['lamalibre-lamaste-panel-ip']);
 
+/** The longest site name: a file name, with room for its `.bak`. */
+const MAX_SITE_NAME = 250;
+
 function assertSiteName(name, action) {
-  if (typeof name !== 'string' || name.length > 128) {
+  if (typeof name !== 'string' || name.length > MAX_SITE_NAME) {
     throw new UsageError('invalid site name');
   }
   if (PANEL_SITE_RE.test(name)) return;
+  if (action !== 'write' && LEGACY_SITE_RE.test(name)) return;
   if ((action === 'enable' || action === 'disable') && TOGGLE_ONLY_SITES.has(name)) return;
   throw new UsageError(`site name not allowed for ${action}: ${name}`);
 }
@@ -335,6 +351,9 @@ const RULES = {
     // rather than the host's mime.types (entries checked below).
     types: { block: 'types', args: argc(0, 0) },
     internal: { args: argc(0, 0) },
+    // The type of a body the location writes itself (a user surface's JSON
+    // refusal): a media type, never a file.
+    default_type: { args: (a) => a.length === 1 && /^[a-z]+\/[a-z0-9.+-]{1,64}$/.test(a[0]) },
     return: { args: argc(1, 2) },
     rewrite: { args: rewriteArgs },
     root: { args: (a) => a.length === 1 && webrootPath(a[0]) },

package/scripts/pin-release.js

@@ -0,0 +1,98 @@
+/**
+ * Pins a vendored package's dependencies on this monorepo's packages to the
+ * exact versions it was built with.
+ *
+ * create-lamaste vendors serverd, the server CLI and Gatekeeper, then runs
+ * `npm install` for them on the relay. Their manifests name the core
+ * library with a caret range (`^4.6.0`), so an install of release X made
+ * after X+1 shipped resolved X+1's core — and 4.6.0's serverd on 4.7.0's
+ * core did not start. Pinned, create-lamaste@X always installs the core,
+ * tickets and identity libraries of release X; third-party dependencies
+ * keep their ranges.
+ */
+
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DEPENDENCY_FIELDS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+
+/**
+ * The name → version of every workspace package (`packages/<group>/<name>`).
+ *
+ * @param {string} monorepoRoot
+ * @returns {Promise<Map<string, string>>}
+ */
+export async function workspaceVersions(monorepoRoot) {
+  const versions = new Map();
+  const packagesDir = join(monorepoRoot, 'packages');
+  for (const group of await readdir(packagesDir, { withFileTypes: true })) {
+    if (!group.isDirectory()) continue;
+    for (const entry of await readdir(join(packagesDir, group.name), { withFileTypes: true })) {
+      const manifestPath = join(packagesDir, group.name, entry.name, 'package.json');
+      if (!entry.isDirectory() || !existsSync(manifestPath)) continue;
+      const { name, version } = JSON.parse(await readFile(manifestPath, 'utf8'));
+      if (typeof name === 'string' && typeof version === 'string') versions.set(name, version);
+    }
+  }
+  return versions;
+}
+
+/**
+ * The manifest with each dependency on a workspace package set to that
+ * package's exact version. Pure; throws on a workspace dependency whose
+ * range the workspace's version does not satisfy as a caret or exact range
+ * (the vendored code would then be pinned to something it was not written
+ * against).
+ *
+ * @param {Record<string, unknown>} manifest
+ * @param {Map<string, string>} versions
+ * @returns {Record<string, unknown>}
+ */
+export function pinWorkspaceDependencies(manifest, versions) {
+  const pinned = { ...manifest };
+  for (const field of DEPENDENCY_FIELDS) {
+    const deps = manifest[field];
+    if (deps === null || typeof deps !== 'object') continue;
+    const next = { ...deps };
+    for (const [name, range] of Object.entries(deps)) {
+      const version = versions.get(name);
+      if (version === undefined) continue;
+      if (range !== version && !caretAdmits(range, version)) {
+        throw new Error(
+          `${manifest.name}: ${field}.${name} is "${range}", the workspace has ${version}`,
+        );
+      }
+      next[name] = version;
+    }
+    pinned[field] = next;
+  }
+  return pinned;
+}
+
+/** Whether `^a.b.c` admits `version` (same major, not lower). */
+function caretAdmits(range, version) {
+  const match = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(String(range));
+  const have = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match || !have) return false;
+  const [want, got] = [match.slice(1).map(Number), have.slice(1).map(Number)];
+  if (want[0] !== got[0]) return false;
+  for (let i = 1; i < 3; i++) if (got[i] !== want[i]) return got[i] > want[i];
+  return true;
+}
+
+/**
+ * Copy `source` (a package.json) to `dest` with its workspace dependencies
+ * pinned.
+ *
+ * @param {string} source
+ * @param {string} dest
+ * @param {Map<string, string>} versions
+ */
+export async function writePinnedManifest(source, dest, versions) {
+  const manifest = JSON.parse(await readFile(source, 'utf8'));
+  await writeFile(
+    dest,
+    `${JSON.stringify(pinWorkspaceDependencies(manifest, versions), null, 2)}\n`,
+  );
+}

package/src/index.js

@@ -12,7 +12,7 @@ import { existsSync } from 'node:fs';
 import { Listr } from 'listr2';
 import chalk from 'chalk';
 import { execa } from 'execa';
-import { detectOS, detectIP, checkRoot } from './lib/env.js';
+import { detectOS, detectIP, checkRoot, installedPanelIp } from './lib/env.js';
 import { printSummary } from './lib/summary.js';
 import { readPanelKeyPin } from './lib/panel-pin.js';
 import { hardenTasks } from './tasks/harden.js';
@@ -485,6 +485,13 @@ export async function main() {
             {
               title: 'Detecting IP address',
               task: async (_ctx, subtask) => {
+                // A redeploy keeps the installed relay's IP (installedPanelIp).
+                const installedIp = flags.forceFull ? null : await installedPanelIp();
+                if (installedIp) {
+                  ctx.ip = installedIp;
+                  subtask.output = `${installedIp} (the installed relay's, from panel.json)`;
+                  return;
+                }
                 ctx.ip = await detectIP({ allowPrivate: flags.dev });
                 if (flags.dev) {
                   subtask.output = `${ctx.ip} (dev mode — private IP accepted)`;

package/src/lib/env.js

@@ -123,6 +123,25 @@ function isPublicIP(ip) {
  * Verify the process is running as root.
  * @throws {Error} if not root
  */
+/**
+ * The IP an installed relay was set up with (`panel.json` `ip`), or null —
+ * no install, no readable file, or no valid IPv4 in it. A redeploy keeps
+ * it: the panel's IP certificate, agents and admins know the relay by it,
+ * and detecting again could change it (or fail, where the installer's
+ * public-IP check does not hold — a dev install on a private address).
+ *
+ * @param {string} [panelJsonPath]
+ * @returns {Promise<string | null>}
+ */
+export async function installedPanelIp(panelJsonPath = '/etc/lamalibre/lamaste/panel.json') {
+  try {
+    const { ip } = JSON.parse(await readFile(panelJsonPath, 'utf8'));
+    return typeof ip === 'string' && isValidIPv4(ip) ? ip : null;
+  } catch {
+    return null;
+  }
+}
+
 export function checkRoot() {
   if (process.getuid() !== 0) {
     throw new Error(

package/src/lib/service-config.js

@@ -265,12 +265,19 @@ WantedBy=multi-user.target
  * Installed by create-lamaste only; onboarding writes the configuration,
  * then enables and starts it.
  *
+ * No start rate limit (`StartLimitIntervalSec=0`): the panel restarts
+ * Authelia for every change of membership, domains or OIDC clients, and
+ * systemd's default (5 starts in 10 s) refused the sixth of a quick series
+ * of admin changes — Authelia then stayed down on every domain until
+ * something started it again. A crash loop stays bounded by `RestartSec=5`.
+ *
  * @returns {string}
  */
 export function generateAutheliaUnit() {
   return `[Unit]
 Description=Authelia Authentication Server
 After=network.target
+StartLimitIntervalSec=0
 
 [Service]
 Type=simple

package/src/tasks/redeploy.js

@@ -24,6 +24,7 @@ import {
   nodeVersionTooNew,
 } from '../lib/node-version.js';
 import { deployGatekeeperPackage } from './gatekeeper.js';
+import { autheliaReady } from '@lamalibre/lamaste/server';
 
 const GATEKEEPER_SERVICE = 'lamalibre-lamaste-gatekeeper';
 
@@ -447,6 +448,13 @@ export function redeployTasks(ctx, task) {
         if (ctx.autheliaWasActive) {
           subtask.output = 'Starting Authelia...';
           await execa('systemctl', ['start', 'authelia']);
+          // systemctl returns when the process is spawned; the panel, which
+          // starts next, talks to Authelia at once.
+          if (!(await autheliaReady(execa))) {
+            throw new Error(
+              'Authelia is not serving requests after the redeploy — see journalctl -u authelia',
+            );
+          }
         }
         if (ctx.gatekeeperWasActive) {
           subtask.output = 'Starting gatekeeper...';

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

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

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

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

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

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

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

@@ -40,7 +40,7 @@ From the Users page in the management panel, you can:
 1. Navigate to the Users page in the management panel
 2. Click "Add User"
 3. Enter a username, display name, email, and password
-4. Lamaste creates the user in `users.yml` and restarts Authelia
+4. Lamaste creates the user in `users.yml`; Authelia reloads it in place
 5. Share the credentials with the user — they enroll in TOTP on first login
 
 ### TOTP enrollment flow
@@ -221,7 +221,7 @@ users:
 
 Lamaste manages this file through the panel server API. All writes are atomic: content is written to a temporary file first, then moved into place. This prevents Authelia from reading a partially written file.
 
-After every write to `users.yml`, the panel server reloads Authelia via `systemctl restart authelia` so the changes take effect.
+Authelia watches `users.yml` (`authentication_backend.file.watch: true`) and reloads it in place; with the watch it re-reads a user's details at each of their requests, so a change applies at the user's next request without a restart and without ending anyone else's session. It skips a reload within 0.5 s of the previous one, so the panel writes the file once more 0.6 s after its last write.
 
 ### Creating users programmatically
 
@@ -420,6 +420,10 @@ Key choices:
 
 See [Registry Credential and OIDC Clients](../04-api-reference/registry-and-oidc.md) for the manifest fields and the API.
 
+### Several domains
+
+On a relay with several domains Authelia carries one `session.cookies` entry per active domain (each `authelia_url: https://auth.<domain>`), so each domain's sign-in sets and reads its own `authelia_session` cookie — same name, scoped by the browser. `access_control` admits each domain's active members on the domain and every host under it (protected sites' rules narrowed to members), then denies; `default_policy` is `deny`. OIDC sign-ins are gated by per-domain `authorization_policies`, since `access_control` does not apply to them, and each domain is an issuer of its own (`https://auth.<domain>`). The panel renders all of it from the directory's memberships ([Domains API](../04-api-reference/domains.md)); on a one-domain relay every user is the domain's member, which admits whom it did before. TOTP is per person, not per domain.
+
 ### Safety rule: never delete the last user
 
 The panel server API prevents deleting the last Authelia user. If only one user exists and you try to delete them, the API returns an error. This prevents a lockout scenario where no one can authenticate to reach the tunneled apps.

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

@@ -102,6 +102,10 @@ From the Gatekeeper dashboard in the admin panel:
 
 Gatekeeper reads groups and grants from its SQLite database (`gatekeeper.db`) on every check, so a group, member or grant created through the admin panel takes effect on the next request — no service restart required. The tunnel list (the panel's `tunnels.json`) and Gatekeeper's settings (`gatekeeper.json`) are watched and reloaded when they change. Changes through the panel also recompute the audiences of agent-hosted plugins at once; edits made with Gatekeeper's own CLI are picked up by the panel within a minute.
 
+### Domains and membership
+
+On a relay with several domains, membership of a host's domain comes before every access mode: `authenticated` means "any signed-in member of this domain", and `restricted` still needs a grant on top. Membership is rendered into Authelia and checked again by Gatekeeper from the panel's `domains.json`; a signed-in non-member gets a "not a member of this domain" page — with the admin contact and a sign-out link — rather than the sign-in page. Members are managed per domain ([Domains API](../04-api-reference/domains.md)); the admin certificate manages every domain, and Authelia's `admins` group needs membership like everyone else (inside a domain it still passes `restricted` sites).
+
 ## For Developers
 
 ### Architecture

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

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

package/vendor/docs/01-concepts/dns-and-domains.md

@@ -260,6 +260,15 @@ Once set during onboarding, the domain is used throughout the system for constru
 | `packages/lamaste-serverd/src/lib/nginx.js`                | Vhost creation with domain-based server_name |
 | `packages/lamaste-serverd/src/lib/state.js`                | Domain storage in panel.json                 |
 
+## Multiple domains
+
+One relay can serve several base domains: the **primary** (set at onboarding — `panel.`, `tunnel.` and agent panels live there) and **added** domains, each with its own sign-in at `auth.<domain>` and its own member list. People have one account across all of them; a person reaches a domain's protected hosts only as a member, and signs in once per domain (browsers never share cookies between domains).
+
+- **DNS for an added domain:** an A record for `auth.<domain>`, and either a wildcard `*.<domain>` or one A record per hostname, all to the relay. Explicit records (apex, `www`, mail) keep precedence over a wildcard. Steps: [Adding a Second Domain](../02-guides/second-domain.md).
+- **Domains never overlap:** `a.samplepark.tr` cannot be added beside `samplepark.tr` — a domain's cookies reach every host under it.
+- **Hostnames:** a tunnel or managed site is `<label>.<domain>`, unique as a whole; the reserved labels hold on every domain; the domain of a hostname is the one it is under (never stored separately). A domain's apex and `www.` may be a custom site or an alias.
+- **Records** live in the panel's `state.db` (`domains`, `domain_members`); `panel.json` `domain` stays the primary.
+
 ## Quick Reference
 
 ### Required DNS records (onboarding)

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

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

package/vendor/docs/01-concepts/security-model.md

@@ -164,7 +164,7 @@ Agents hold only the public key. The daemon fetches it, with the label the relay
 
 The owner's token is as good as the owner: the desktop app hands it to curl on stdin, never in a process's arguments, which other local users can read.
 
-Headers that only claim a caller — `X-SSL-Client-*`, `Remote-*` and the assertion itself — are removed from every request before a route or plugin sees it; `Remote-*` are set again only from a verified user assertion, so a plugin reading identity headers (`@lamalibre/lamaste-identity@4.6.0`) reads the relay's word. Whether a request needs a caller follows the route the daemon matched, not the URL: every route does except the health check, the plugin bundles and the SPA's static files, and so does a path no route matches under an installed plugin's name (a plugin may answer it with its own not-found handler). The claim headers are removed from `rawHeaders` too.
+Headers that only claim a caller — `X-SSL-Client-*`, `Remote-*` and the assertion itself — are removed from every request before a route or plugin sees it; `Remote-*` are set again only from a verified user assertion, so a plugin reading identity headers (`@lamalibre/lamaste-identity@4.7.0`) reads the relay's word. Whether a request needs a caller follows the route the daemon matched, not the URL: every route does except the health check, the plugin bundles and the SPA's static files, and so does a path no route matches under an installed plugin's name (a plugin may answer it with its own not-found handler). The claim headers are removed from `rawHeaders` too.
 
 **What remains.** The relay's loopback is still the relay's trust boundary: the panel itself trusts the `X-SSL-Client-*` headers nginx sends to `127.0.0.1:3100`, so a process on the relay that can forge those can obtain an assertion as well — what it could do to agents before 4.3. With panel 2FA on it reaches further into agents than into the panel: forged (or stolen) admin-certificate headers no longer pass the panel's own management routes, but the agent-panel authorization is exempt from 2FA (the browser on `agent-<label>.<domain>` carries no 2FA cookie), so they still mint admin assertions — full control of every agent with a panel tunnel. Agent panels are guarded by the client certificate alone, as before; authenticating nginx to the panel is the relay-wide fix. An assertion binds the agent, the port, the method and the target, not the request body: a process on the agent machine that holds the daemon's port while the daemon is down receives the relay's requests, and could replay one with another body if the daemon comes back within the assertion's 65 seconds.
 
@@ -194,7 +194,7 @@ An agent-hosted plugin's settings may hold secrets — a data provider's API key
 - **Authenticated answers.** Every answer the agent half gives a verified request carries `X-Lamalibre-Responder`, an HMAC with the secret that verified the request over its nonce, the status and — for Lamaste's own calls — the SHA-256 of the exact answer body. The relay believes nothing without it: a settings call or a hook call fails as `unauthenticated`, the health probe counts the plugin's application as down, and the forwarder answers `502` before a status, header or byte of the answer reaches the client. Every `/admin/*` response of an agent half must carry it; core's handlers, `createHealthHandler` and `responderHeaderFor` produce it.
 - **Sealed secrets.** Each secret of a settings change crosses the tunnel encrypted (AES-256-GCM, key derived with HKDF-SHA256 from the installation secret per plugin) and bound to the plugin, the call's nonce, the field and the revision; the agent half opens it with the secret that verified the call.
 
-Agent halves built against `@lamalibre/lamaste@4.6.0` 4.3 must be rebuilt: one that does not sign its answers is down to the relay.
+Agent halves built against `@lamalibre/lamaste@4.7.0` 4.3 must be rebuilt: one that does not sign its answers is down to the relay.
 
 **What a port's squatter still receives.** These mechanisms authenticate answers and seal secrets; they do not keep the relay from _sending_. A squatter cannot pass a single health probe (it holds no installation secret), so the health monitor marks the hosting down after three failed probes in a row, 10 s apart. From then on **neither forwarder sends anything to the port**: a user's request is answered `503` by the panel, and an administrator's or agent's request on the admin API is answered as a request into a dead tunnel is — the plugin's `tunnel:down` fallback, or `502` with the reason (`tunnel` or `app`) — without a connection being made. So a forwarded request — its method, path, query and body, and the caller assertion with an administrator, an agent, or a user's `userId`, username and roles — can reach a relay-loopback squatter only in the window before the hosting is marked down, about 30 seconds after the agent went away (and, when the agent comes back, a squatter that still holds the port is what the probes find: the hosting stays down). Lamaste's own calls do not go through the forwarders and keep reaching the port — the health probe has to, to see the agent half come back: their bodies are bound to their assertions and a settings change's secrets are sealed, so a squatter learns their non-secret content and nothing it can replay.
 
@@ -242,7 +242,7 @@ Gatekeeper attests the session; the panel issues the identity. Gatekeeper never
 
 **Data minimisation.** A plugin always receives a user's `userId` and **username** — in the caller assertion of every request and in every member and last-known record of its feed — and of the other attributes only those its manifest declares (`displayName`, `email`); widening them waits for an administrator's approval that auto-approve never gives (`identity.changed`). Nothing identity is ever sent to a plugin that does not declare `identity`. A user who leaves keeps, on the plugin's side, only what it last received. The feed's batches travel **sealed**: their changes are encrypted (AES-256-GCM) with a key derived from the hosting's installation secret — domain-separated from the settings secrets' — and bound to the caller assertion's nonce and the batch envelope, so the chisel server and whatever holds a loopback end of the internal tunnel never see a member in clear. Audit entries name users by `userId` alone, and the feed's wire parsers never echo a received value. The panel and Gatekeeper log one metadata line per request — method, **route pattern** (never the URL or its query), status, duration, certificate role, and the client address only for certificate holders, never for a person — instead of Fastify's own request lines; the panel's log lines name users by `userId`; Gatekeeper's principal removal and access-log purge take the username in a request body, never a URL. `users.yml`'s content never reaches a log, even when it cannot be parsed. What nginx's access log, journald and Authelia's log keep, and for how long: [Monitoring](../05-operations/monitoring.md#logs-and-personal-data).
 
-**Offboarding and erasure.** One offboarding function, keyed by `userId`, runs for every user who stops being one — disabled or deleted through the users API, or disabled or removed in `users.yml` outside it (adopted by the minute's reconcile): their desktop sessions end (an epoch keyed by `userId`; sessions are bound to the `userId`, so a username given to someone else revives none), their registry tokens are revoked, Gatekeeper drops its cached session verdicts, and for a removal their legacy plugin-access grants, Gatekeeper principal (every grant and group membership under the username) and Authelia second factors (TOTP configuration, WebAuthn credentials) go. Disabling is effective at once: the directory is written before Authelia restarts, so the user surface refuses them (`403`) before Authelia lets them out, and every audience shows them disabled; a disable that Authelia's own rewrite of `users.yml` undoes is made again, and reported when it does not stick. Deleting keeps a tombstone (the `userId` and the last known name and address, `removed`) so history stays readable. **A re-created username is a new user with a new `userId` and inherits no grant, group, role, second factor or session**: at every creation over a tombstone Gatekeeper drops everything under the username and Authelia its second factors (refused while either cannot), a username a deleted user held and nobody holds takes no grant or membership (`409 username_deleted`), and grants are given under the users lock so none races a deletion. The one exception Lamaste cannot remove is the **OpenID Connect identity**: Authelia's opaque identifier (`sub`) for a username cannot be deleted, so a username Authelia holds one for is never given to a new user (`409 username_has_oidc_identity`). **Erasing** scrubs the tombstone, the user's invitations, Gatekeeper's access-request log rows and Authelia's second factors, and rewrites the user's row to `remove/erased` in every plugin that ever had them — uninstalled plugins whose data an agent keeps and plugins that no longer declare identity included (a plugin's audience is its erasure ledger, dropped only when no agent keeps its data); its agent half scrubs its row and anonymises its own data in one transaction, never takes the user back afterwards (erasure is sticky in its projection), and the panel shows the erasure as pending until each plugin's data has it. Outside Lamaste's reach: Authelia's opaque identifier and authentication log, nginx's access logs, journald's older entries, and backups taken before ([Backup and Restore](../05-operations/backup-and-restore.md) on restoring a relay).
+**Offboarding and erasure.** One offboarding function, keyed by `userId`, runs for every user who stops being one — disabled or deleted through the users API, or disabled or removed in `users.yml` outside it (adopted by the minute's reconcile): their desktop sessions end (an epoch keyed by `userId`; sessions are bound to the `userId`, so a username given to someone else revives none), their registry tokens are revoked, Gatekeeper drops its cached session verdicts, and for a removal their legacy plugin-access grants, Gatekeeper principal (every grant and group membership under the username) and Authelia second factors (TOTP configuration, WebAuthn credentials) go. Disabling is effective at once: the directory is written in the same step, so the user surface refuses them (`403`), Authelia ends their session at their next request, and every audience shows them disabled; a disable that Authelia's own rewrite of `users.yml` undoes is made again, and reported when it does not stick. Deleting keeps a tombstone (the `userId` and the last known name and address, `removed`) so history stays readable. **A re-created username is a new user with a new `userId` and inherits no grant, group, role, second factor or session**: at every creation over a tombstone Gatekeeper drops everything under the username and Authelia its second factors (refused while either cannot), a username a deleted user held and nobody holds takes no grant or membership (`409 username_deleted`), and grants are given under the users lock so none races a deletion. The one exception Lamaste cannot remove is the **OpenID Connect identity**: Authelia's opaque identifier (`sub`) for a username cannot be deleted, so a username Authelia holds one for is never given to a new user (`409 username_has_oidc_identity`). **Erasing** scrubs the tombstone, the user's invitations, Gatekeeper's access-request log rows and Authelia's second factors, and rewrites the user's row to `remove/erased` in every plugin that ever had them — uninstalled plugins whose data an agent keeps and plugins that no longer declare identity included (a plugin's audience is its erasure ledger, dropped only when no agent keeps its data); its agent half scrubs its row and anonymises its own data in one transaction, never takes the user back afterwards (erasure is sticky in its projection), and the panel shows the erasure as pending until each plugin's data has it. Outside Lamaste's reach: Authelia's opaque identifier and authentication log, nginx's access logs, journald's older entries, and backups taken before ([Backup and Restore](../05-operations/backup-and-restore.md) on restoring a relay).
 
 **What remains.** Plain `authenticated` and `restricted` app tunnels still pass the user to their backend as **unsigned** `Remote-User`, `Remote-Groups`, `Remote-Name` and `Remote-Email` headers set from Gatekeeper's answer: nginx replaces whatever the client sent, but the backend's port is reachable on the relay's and the agent's loopback by any local process, which can send any `Remote-*` it likes. Only plugin tunnels (a relay assertion for lamaste-agentd, 5c) and plugin user surfaces carry a signed identity; Gatekeeper-signed identity for plain tunnels is future work. A backend never receives the session cookie (5a), but it answers on a host under the relay's domain and can set cookies there — a second `authelia_session` with another path, which Gatekeeper refuses rather than guess. Until the hosting is marked down, a forwarded request — a user's or an administrator's — can reach a relay-loopback squatter (5e). The relay's loopback stays the relay's trust boundary: a process on the relay that can read the relay signing key can mint assertions for the panel, as it could for agents before.
 
@@ -664,6 +664,31 @@ Configuration files that are read live by services (like Authelia's `users.yml`)
 | `packages/core/lib/src/agent/plugin-settings-store.ts`              | The agent half's settings files and `/admin/settings`  |
 | `packages/server/daemon/src/lib/plugin-settings.js`                 | Settings through the tunnel; the cache without secrets |
 
+## Several domains on one relay
+
+A relay may serve several base domains with one user directory and an explicit member list per domain ([Domains API](../04-api-reference/domains.md)).
+
+- **Membership is enforced twice, from one source** (the panel's `state.db`, and Gatekeeper's grants for external members): Authelia (groups Lamaste owns in `users.yml`, named by `access_control` rules with deny last and `default_policy: deny`, and by one OIDC authorization policy per user-facing client) and Gatekeeper (the `domains.json` projection, fail closed; read again on every cache bust and every minute, whatever its file watcher saw). Either alone keeps a non-member out of tunnels and plugin surfaces; static sites rely on Authelia, OIDC sign-ins on the clients' authorization policies. One lock (`withDomainRendering`) serializes everything that writes what members may do. Both are always rendered — one failing never keeps the other at older members — and a failing rendering is audited (`domain.render.failed`) and raised to the administrators until it succeeds.
+- **A protected site is never served open:** a protected static site whose hostname is under none of the relay's domains (possible since 4.6) answers `403` to everyone, and editing or re-verifying it is refused until it is unprotected or its domain is added.
+- **A user-facing OIDC client is always gated by membership:** a client is either a service (`client_credentials` alone) or user-facing, never both — Authelia gives a `client_credentials` client `one_factor`, never a domain's member policy.
+- **Cookies never cross domains:** domains may not overlap **and may not share a registrable domain** (eTLD+1 by the Public Suffix List; a public suffix is never a domain) — otherwise an application on `cust1.example.net` could set an `authelia_session` on `example.net` that the browser sends to `cust2.example.net` (a planted session, a forced sign-in, a lock-out) and both would be one site for `SameSite`. So one domain's session cookie never reaches another's hosts; the backend cookie map strips `authelia_session` on every domain. Each `auth.<domain>` passes Authelia its own name as `X-Forwarded-Host` / `-Proto` — a client cannot make one domain's portal act as another's issuer or cookie domain.
+- **Nothing lands on a domain as it changes:** adding, activating and removing a domain hold the tunnel and sites locks under which tunnels, sites and plugin moves resolve their domain and sites take hostnames; the registry credential is written under the domains lock. The relay's own hostnames (`auth.`, `panel.`, `tunnel.`, `agent-*`) of a pending domain are kept free, and a domain is added and activated only while no tunnel, site or alias holds one. An invitation grants, at acceptance, only the domains it names that existed when it was made — a domain removed and added again is not one of them.
+- **Registry tokens follow the registry's sign-in**: a user whom none of the registry's own sign-in clients (the user-facing clients whose audience is the registry) admits any more — whatever narrowed them, a revocation with Gatekeeper's own CLI included — loses their Feria tokens (best effort; they sign in again); none such client, or one that cannot be read, revokes (fail closed). Changing the credential's domains revokes those of everyone outside the new ones. Every narrowing is audited (`directory.access.narrowed`, by id).
+- **One issuer per domain:** a token carries the issuer it was obtained at; a relying party trusting one issuer refuses the others.
+- **External members reach only what names them** — `restricted` tunnels and surfaces that grant them, static sites that list them, OIDC clients granted to them — checked by Authelia (an external member's rule admits them only on a host whose name is one of their groups, and the panel gives them a host's group only for a grant on it; an `authenticated` host has none, so it is closed to them from its first request) and again by Gatekeeper (the projection carries the kind). They hold no Authelia group (`admins`, `feria-*`), so no group grants them anything by membership; Lamaste (Gatekeeper) groups in grants apply to them. Making a member external takes effect at their next request.
+- **Who is let in changes without a restart.** Memberships, kinds, grants, users and sites' listed users are groups Lamaste owns in `users.yml`, which Authelia watches and re-reads at each request (`refresh_interval: always`, rendered); if its configuration could not be brought to that, a change of the file restarts it. The panel touches the file 0.6 s after its last write — read again, Lamaste's groups applied again, written — because Authelia skips a reload within 0.5 s of the previous one; the start and the identity tick touch it too. Authelia's own password change and reset, which would write the file from an older copy, are disabled. A write never drops a user it was not told to delete, never gives a user the rendering did not know (a reused username) any of Lamaste's groups, and only narrows after a rendering failed; when the grants cannot be read, external members hold no granted host or client until they can (fail closed). The names of those groups are reserved: an administrator assigns only `[A-Za-z0-9_-]` names, and the panel removes any owned-looking group it did not render — compared folded as Authelia compares (`ſ` is `s`), under every domain and every removed one.
+- **Grants are access, kept until revoked**: Gatekeeper consumes only a local plugin grant (its desktop enrolment), and sweeps only those; tunnel, site, agent-plugin and OIDC-client grants were swept 90 days after creation before 4.7. Uninstalling a plugin revokes the grants on its OIDC clients.
+- **The accepted shared blast radius:** one droplet, nginx, panel, Gatekeeper and Authelia serve every domain, and the admin certificate manages all of them. A compromise of the relay reaches every domain it serves — the normal hosting trade-off, documented rather than engineered around. A customer who must keep its users off the relay needs a relay of its own (or, later, an external identity provider for its domain).
+- **Same-site:** applications on one domain share its registrable domain as before; a customer's applications on their own domain are now a separate site from Code Lama's.
+
+**What remains.**
+
+- **OIDC access tokens already issued.** Authelia checks a client's authorization policy — membership of its domain, or an external member's grant — when a user authorizes it, not afterwards. Plugin clients therefore get no refresh tokens (the manifest refuses the `refresh_token` grant and the `offline` / `offline_access` scopes; a plugin installed before is served without them), and the access and ID tokens of user-facing clients live 15 minutes: a user removed from a domain, or whose grant was revoked, keeps at most those, until they expire. Feria's own tokens are revoked (above).
+- **One session store.** Authelia keeps every domain's sessions in one store; the separation between domains is the browser's cookie scoping plus membership by username — a session value moved to another domain's cookie would be accepted there for a member. The backend cookie map keeps session values away from every backend.
+- **Structural changes restart Authelia** — a domain added, activated or removed, a static site protected, unprotected, created or removed, the set of OIDC clients or a plugin's domain changed — which ends every session on every domain (Authelia keeps sessions in memory): an availability cost, not an access one, and an administrator's action (R3, narrowed in 4.7).
+- **Authelia's device-code flow reads a session's groups as they were** (R5): unlike the authorization-code flow, it checks a client's policy against the groups the session last refreshed. So a change that takes a device-code client (`feria login`) away from someone — a membership ended or made external on a domain serving one, a grant on one revoked — restarts Authelia, ending every session on every domain. External members without such a grant (corral's) never cause it. To be reported upstream.
+- **Lamaste's groups reach an OIDC client that asks for `groups`** (R4): Authelia's standard `groups` claim cannot be filtered, so such a client — one the administrator installed, Feria's `feria login` — sees the user's groups. They are opaque — a random key per domain (`lamaste:m:<key>`, `lamaste:x:<key>`), a site's id — so no domain or site is named; what remains is that two users sharing a key share a domain, the client ids granted to an external member, and an external member's granted hostnames on their own domain. Gatekeeper keeps them from every tunnel backend.
+
 ## Quick Reference
 
 ### Security layers