@camstack/system 1.2.381 → 1.2.382

package/dist/builtins/system-backup/system-backup.service.d.ts

@@ -1,4 +1,5 @@
 import { ArchiveSqliteSnapshot, DatabaseSnapshotResult, IScopedLogger } from '@camstack/types';
+import { BACKUP_ENCRYPTION_SCHEME } from './backup-encryption.js';
 /**
  * Thrown when an archive build (or a backup run driving one) is
  * stopped via its `AbortSignal`. Callers use `instanceof` to tell a
@@ -94,11 +95,19 @@ export interface ArchiveManifest {
      */
     sqliteSnapshots?: ArchiveSqliteSnapshot[];
 }
+/** How an archive was encrypted — absent on a plain `.tar.gz`. */
+export interface ArchiveEncryption {
+    readonly scheme: typeof BACKUP_ENCRYPTION_SCHEME;
+    /** The backup key the archive needs to be restored. */
+    readonly keyId: string;
+}
 export interface CreateArchiveResult {
     archivePath: string;
     includedLocations: readonly string[];
-    /** Archive size in bytes (compressed, on disk). */
+    /** Archive size in bytes (compressed — and encrypted, when it is — on disk). */
     sizeBytes: number;
+    /** Present when the archive is encrypted to a backup key. */
+    encryption?: ArchiveEncryption;
     /** Embedded manifest — same shape as `getArchiveManifest()`. */
     manifest: ArchiveManifest;
 }
@@ -197,6 +206,12 @@ export declare class SystemBackupService {
          * because its upload prunes an older archive that HAS it.
          */
         owner?: DatabaseOwner;
+        /**
+         * A backup PUBLIC key: the gzip stream is encrypted to it as it is
+         * written, so no plaintext archive ever touches the staging disk. Parsed
+         * before any work — a bad key builds nothing.
+         */
+        encryptTo?: string;
     }): Promise<CreateArchiveResult>;
     /**
      * Tar `present` (filtered by `excluded`) plus the staged manifest into

package/dist/builtins/system-config/cluster-secret-keeper.d.ts

@@ -17,6 +17,12 @@ export interface ClusterSecretKeeperDeps {
     readonly readSection: () => Promise<Record<string, unknown>>;
     readonly logger: KeeperLogger;
     readonly retryMs?: number;
+    /**
+     * Generate and store a new secret (D802). Called when no marker is stored.
+     * Throws when it cannot (no keychain, locked): the keeper retries on its
+     * timer. Absent → nothing is generated (tests of the D797 states).
+     */
+    readonly generateSecret?: () => Promise<void>;
 }
 export declare class ClusterSecretKeeper {
     private readonly deps;
@@ -29,6 +35,7 @@ export declare class ClusterSecretKeeper {
     stop(): void;
     /** Re-read the row and the keychain; publish the gate. */
     reload(): Promise<void>;
+    private generate;
     private compute;
     private report;
     private scheduleRetry;

package/dist/builtins/system-config/system-config.addon.d.ts

@@ -14,10 +14,20 @@ export declare class SystemConfigAddon extends BaseAddon {
     updateGlobalSettings(patch: Record<string, unknown>): Promise<void>;
     /**
      * The cluster secret's save path: the value goes to the keychain (owner
-     * `system`), the row gets the marker; `''` / a view keeps, `$secretClear`
-     * clears. A value the keychain cannot store is REFUSED — never written
-     * inline (D787, P5).
+     * `system`), the row gets the marker; `''` / a view keeps. `$secretClear` is
+     * REFUSED: the secret is mandatory (D802). A value the keychain cannot store
+     * is REFUSED — never written inline (D787, P5). `meshAuth` is a plain value.
      */
     private writeClusterSection;
+    /** `cluster.meshAuth` (D802), then republish it. */
+    private writeMeshAuthMode;
+    /**
+     * First boot, or a keychain reset that cleared the marker (D802): a fresh
+     * random secret, stored like an operator save. A NEW secret means every
+     * agent must be given it, so the mesh goes (back) to `transition`; on a hub
+     * with no agent yet, the hub's auto-enforce ends it at once.
+     */
+    private generateClusterSecret;
+    private storeClusterSecret;
 }
 export default SystemConfigAddon;

package/dist/builtins/system-config/system-config.addon.js

@@ -3,21 +3,154 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BugrtARh.js");
-const require_cluster_secret = require("../../cluster-secret-BUiG8DCo.js");
+const require_dist = require("../../dist-tnAO12ak.js");
+const require_cluster_secret = require("../../cluster-secret-BEPLh3LL.js");
+let node_crypto = require("node:crypto");
+let node_net = require("node:net");
+//#region src/auth/cidr.ts
+/**
+* CIDR lists for the auth settings that name networks: the trusted reverse
+* proxies whose forwarding headers the hub believes, and the trusted local
+* networks a login may skip its second factor from.
+*
+* Built on `net.BlockList`, so IPv4 and IPv6 are matched by the platform, not
+* by string prefixes. A bare address is read as a single host. Anything that
+* does not parse is REPORTED back (`invalid`) so the settings form can refuse
+* it — a list that silently dropped a typo would quietly trust less than the
+* operator wrote, and one that guessed would trust more.
+*/
+/** Strip an IPv4-mapped IPv6 prefix and a zone id, so ranges see a clean address. */
+function normalizeIp(ip) {
+	let out = ip.trim();
+	if (out.toLowerCase().startsWith("::ffff:") && (0, node_net.isIP)(out.slice(7)) === 4) out = out.slice(7);
+	const pct = out.indexOf("%");
+	if (pct !== -1) out = out.slice(0, pct);
+	return out;
+}
+function parseCidr(raw) {
+	const text = raw.trim();
+	const slash = text.indexOf("/");
+	const address = normalizeIp(slash === -1 ? text : text.slice(0, slash));
+	const version = (0, node_net.isIP)(address);
+	if (version === 0) return null;
+	const max = version === 4 ? 32 : 128;
+	let prefix = max;
+	if (slash !== -1) {
+		const bits = text.slice(slash + 1);
+		if (!/^\d{1,3}$/.test(bits)) return null;
+		prefix = Number.parseInt(bits, 10);
+		if (prefix > max) return null;
+	}
+	return {
+		network: address,
+		prefix,
+		family: version === 4 ? "ipv4" : "ipv6"
+	};
+}
+/** Parse a list of CIDR strings; blanks are skipped, unparseable entries returned. */
+function parseCidrList(entries) {
+	const valid = [];
+	const invalid = [];
+	for (const entry of entries) {
+		if (entry.trim().length === 0) continue;
+		const parsed = parseCidr(entry);
+		if (parsed === null) invalid.push(entry);
+		else valid.push(parsed);
+	}
+	return {
+		valid,
+		invalid
+	};
+}
+/** A stored setting as a string list — accepts a list, or one comma/space separated string. */
+function readCidrSetting(value) {
+	if (Array.isArray(value)) return value.filter((v) => typeof v === "string");
+	if (typeof value === "string") return value.split(/[\s,]+/).filter((v) => v.length > 0);
+	return [];
+}
+/** A matcher over the VALID entries of `entries`; invalid ones match nothing. */
+function createCidrMatcher(entries) {
+	const { valid } = parseCidrList(entries);
+	const list = new node_net.BlockList();
+	for (const cidr of valid) list.addSubnet(cidr.network, cidr.prefix, cidr.family);
+	return {
+		size: valid.length,
+		contains(ip) {
+			if (valid.length === 0) return false;
+			const address = normalizeIp(ip);
+			const version = (0, node_net.isIP)(address);
+			if (version === 0) return false;
+			return list.check(address, version === 4 ? "ipv4" : "ipv6");
+		}
+	};
+}
+//#endregion
+//#region src/kernel/moleculer/mesh-auth-mode.ts
+/** The field key inside the `cluster` section. */
+var MESH_AUTH_MODE_FIELD = "meshAuth";
+function isMeshAuthMode(value) {
+	return value === "transition" || value === "enforced";
+}
+/** A stored value that is not a mode reads as `transition`: never refuse on a typo. */
+function parseMeshAuthMode(value) {
+	return isMeshAuthMode(value) ? value : "transition";
+}
+var MODE_SLOT = Symbol.for("camstack.cluster.mesh-auth-mode");
+var ENFORCER_SLOT = Symbol.for("camstack.cluster.mesh-auth-enforcer");
+var STATUS_SLOT = Symbol.for("camstack.cluster.mesh-auth-status");
+/** Published by `system-config` whenever the stored mode is (re)read. */
+function setProcessMeshAuthMode(mode) {
+	Reflect.set(globalThis, MODE_SLOT, mode);
+}
+/**
+* The hub's mode. Until `system-config` has read it: `transition` — the safe
+* side for an upgrading cluster (nothing that worked before is refused), and
+* exactly what an unread setting means.
+*/
+function getProcessMeshAuthMode() {
+	return parseMeshAuthMode(Reflect.get(globalThis, MODE_SLOT));
+}
+function setProcessMeshEnforcer(enforcer) {
+	if (enforcer === null) Reflect.deleteProperty(globalThis, ENFORCER_SLOT);
+	else Reflect.set(globalThis, ENFORCER_SLOT, enforcer);
+}
+/** Ask the owner of the setting to switch to `enforced`. `false` when nobody can. */
+async function requestProcessMeshEnforcement(reason) {
+	const enforcer = Reflect.get(globalThis, ENFORCER_SLOT);
+	if (typeof enforcer !== "function") return false;
+	await enforcer(reason);
+	return true;
+}
+/** Published by the hub's broker; read by System → Cluster. */
+function setProcessMeshAuthStatusSource(source) {
+	if (source === null) Reflect.deleteProperty(globalThis, STATUS_SLOT);
+	else Reflect.set(globalThis, STATUS_SLOT, source);
+}
+function getProcessMeshAuthStatus() {
+	const source = Reflect.get(globalThis, STATUS_SLOT);
+	return typeof source === "function" ? source() : null;
+}
+//#endregion
 //#region src/builtins/system-config/cluster-secret-keeper.ts
 /**
-* Keeps the hub's cluster-secret gate in step with System → Cluster (D797).
+* Keeps the hub's cluster-secret gate in step with System → Cluster (D797,
+* D802).
 *
 * The field is a `password` of `system-config`: its `system-settings` row
 * (`cluster.clusterSecret`) holds a keychain marker, the value lives in the
-* keychain (owner `system`). The gate the `$hub.registerNode` handler reads:
+* keychain (owner `system`). The gate the mesh join reads:
 *
-*  - no marker            → `off` — every node may register, exactly as a hub
-*                           that never had a secret;
-*  - marker + value       → `on`  — nodes present the matching hash;
+*  - no marker            → the secret is MANDATORY (D802): the keeper asks
+*                           its owner to generate one (`generateSecret`), and
+*                           until that succeeds the gate is `off` — no node can
+*                           authenticate, and only `transition` lets them in;
+*  - marker + value       → `on`  — nodes prove the secret;
 *  - marker, no answer    → `unknown` — refused, retryably, and retried here.
-*    A locked keychain or a value lost to a reset NEVER opens the gate.
+*    A locked keychain or a value lost to a reset NEVER opens the gate, and
+*    never triggers a generation (the operator decides what replaces a value
+*    the keychain lost).
+*
+* It also publishes the mesh mode (`cluster.meshAuth`, `mesh-auth-mode.ts`).
 */
 /** The field key inside the `cluster` section. */
 var CLUSTER_SECRET_FIELD = "clusterSecret";
@@ -46,22 +179,35 @@ var ClusterSecretKeeper = class {
 	/** Re-read the row and the keychain; publish the gate. */
 	async reload() {
 		if (this.stopped) return;
-		const gate = await this.compute();
+		let gate = await this.compute();
+		if (gate.kind === "off" && this.deps.generateSecret !== void 0 && !this.stopped) gate = await this.generate();
 		if (this.stopped) return;
 		require_cluster_secret.setProcessClusterSecretGate(gate);
 		this.report(gate);
-		if (gate.kind === "unknown") this.scheduleRetry();
+		if (gate.kind === "unknown" || gate.kind === "off" && this.deps.generateSecret !== void 0) this.scheduleRetry();
+	}
+	async generate() {
+		try {
+			await this.deps.generateSecret?.();
+		} catch (err) {
+			this.deps.logger.error("The cluster secret is mandatory but could not be generated yet — retrying. Agents cannot authenticate until it exists.", { meta: { error: errText(err) } });
+			return { kind: "off" };
+		}
+		this.deps.logger.info("Generated the cluster secret (none was stored). Reveal it on System → Cluster and enter it in each agent.");
+		return this.compute();
 	}
 	async compute() {
-		let stored;
+		let section;
 		try {
-			stored = (await this.deps.readSection())[CLUSTER_SECRET_FIELD];
+			section = await this.deps.readSection();
 		} catch (err) {
 			return {
 				kind: "unknown",
 				reason: `settings unreadable: ${errText(err)}`
 			};
 		}
+		setProcessMeshAuthMode(parseMeshAuthMode(section[MESH_AUTH_MODE_FIELD]));
+		const stored = section[CLUSTER_SECRET_FIELD];
 		if (stored === void 0 || stored === null || stored === "") return { kind: "off" };
 		if (!require_dist.isSecretMarker(stored)) return {
 			kind: "unknown",
@@ -111,7 +257,7 @@ var ClusterSecretKeeper = class {
 			this.deps.logger.error("Agents cannot register: a cluster secret is set but cannot be read from the keychain. Registrations are refused until it can (no fallback).", { meta: { reason: gate.reason } });
 			return;
 		}
-		if (changed) this.deps.logger.info(gate.kind === "on" ? "Cluster secret set — agents must present it to register" : "No cluster secret set — any node may register");
+		if (changed) this.deps.logger.info(gate.kind === "on" ? "Cluster secret set — agents prove it to join the mesh" : "No cluster secret yet — no node can authenticate to the mesh");
 	}
 	scheduleRetry() {
 		if (this.stopped || this.retryTimer !== null) return;
@@ -138,10 +284,12 @@ function errText(err) {
 *
 * Sections exposed — this list is the whole of it:
 *   - server     (port, host, dataPath — READ-ONLY, loaded from config.yaml at bootstrap)
-*   - auth       (tokenExpiry)
+*   - auth       (tokenExpiry = session lifetime, accessTokenExpiry, trustedProxies,
+*                 trustedNetworks)
 *   - cluster    (clusterSecret — a `password` field: the value goes to the
 *                 keychain, owner `system`; the row keeps a marker. Also drawn
-*                 on System → Cluster. D797)
+*                 on System → Cluster. D797. MANDATORY and generated at first
+*                 boot; `meshAuth` — transition / enforced. D802)
 *
 * Sections NOT exposed (each owned by the addon that implements them):
 *   - logging    → `winston-logging` addon (level + retention)
@@ -182,8 +330,32 @@ var KEY_TO_SECTION = {
 	host: "server",
 	dataPath: "server",
 	tokenExpiry: "auth",
-	[CLUSTER_SECRET_FIELD]: "cluster"
+	accessTokenExpiry: "auth",
+	trustedProxies: "auth",
+	trustedNetworks: "auth",
+	[CLUSTER_SECRET_FIELD]: "cluster",
+	[MESH_AUTH_MODE_FIELD]: "cluster"
+};
+/** Bytes of a generated cluster secret (D802) — 256 bits, base64url (43 chars). */
+var GENERATED_SECRET_BYTES = 32;
+var STATE_LABELS = {
+	authenticated: "authenticated",
+	legacy: "legacy hash only — update the agent",
+	unauthenticated: "not authenticated — enter the cluster secret in this agent"
 };
+/** The Cluster page's live line per node (D802). */
+function describeMeshStatus(status) {
+	if (status === null) return "The mesh status is available on the hub only.";
+	const head = status.mode === "enforced" ? "Enforced: a node that has not authenticated is refused." : "Transition: nodes without the secret are still let in (with a warning). The hub switches to Enforced by itself once every known agent has authenticated.";
+	if (status.nodes.length === 0) return `${head}\nNo other node is connected.`;
+	return `${head}\n${status.nodes.map((n) => `• ${n.nodeId}: ${STATE_LABELS[n.state] ?? n.state}`).join("\n")}`;
+}
+/**
+* Auth keys holding a list of networks (CIDR or single address). A save with
+* an entry that does not parse is REFUSED whole: dropping it would trust less
+* than the operator wrote, guessing would trust more.
+*/
+var CIDR_LIST_KEYS = new Set(["trustedProxies", "trustedNetworks"]);
 /** The section id of the cluster form — System → Cluster renders only this one. */
 var SYSTEM_CONFIG_CLUSTER_SECTION_ID = "system-config-cluster";
 var SystemConfigAddon = class extends require_dist.BaseAddon {
@@ -196,12 +368,18 @@ var SystemConfigAddon = class extends require_dist.BaseAddon {
 		this.clusterSecretKeeper = new ClusterSecretKeeper({
 			secrets: this.systemSecrets(),
 			readSection: async () => await this.ctx.settings?.getSection("cluster") ?? {},
-			logger: this.ctx.logger
+			logger: this.ctx.logger,
+			generateSecret: () => this.generateClusterSecret()
+		});
+		setProcessMeshEnforcer(async (reason) => {
+			await this.writeMeshAuthMode("enforced");
+			this.ctx.logger.info("Mesh authentication is now ENFORCED", { meta: { reason } });
 		});
 		await this.clusterSecretKeeper.start();
 		this.ctx.logger.info("Initialized — exposes yml-backed sections via getGlobalSettings");
 	}
 	async onShutdown() {
+		setProcessMeshEnforcer(null);
 		this.clusterSecretKeeper?.stop();
 		this.clusterSecretKeeper = null;
 	}
@@ -254,26 +432,80 @@ var SystemConfigAddon = class extends require_dist.BaseAddon {
 				title: SECTION_TITLES["auth"],
 				description: "Token and session settings.",
 				columns: 1,
-				fields: [{
-					type: "text",
-					key: "tokenExpiry",
-					label: "Token Expiry",
-					description: "Lifetime of a session token, as a duration string (e.g. 24h, 7d, 30d). A bare number is rejected — it would be read as milliseconds. Applies to tokens issued from the next login or silent refresh; tokens already handed out keep the lifetime they were signed with.",
-					placeholder: "30d",
-					default: "30d"
-				}]
+				fields: [
+					{
+						type: "text",
+						key: "tokenExpiry",
+						label: "Session lifetime",
+						description: "How long a sign-in lasts without being used, as a duration string (e.g. 7d, 30d). Every refresh starts it again, so a device in use stays signed in; one left unopened this long must sign in again. A bare number is rejected — it would be read as milliseconds. Applies from the next sign-in or refresh.",
+						placeholder: "30d",
+						default: "30d"
+					},
+					{
+						type: "text",
+						key: "accessTokenExpiry",
+						label: "Access token lifetime",
+						description: "How long one access token lives before the app silently swaps it for a new one (e.g. 2h; between 5m and 24h, never longer than the session). Shorter limits how long a copied token is useful. Apps that predate refresh tokens get one token for the whole session instead.",
+						placeholder: "2h",
+						default: "2h"
+					},
+					{
+						type: "tags",
+						key: "trustedProxies",
+						label: "Trusted reverse proxies",
+						description: "Addresses or CIDR ranges (e.g. 192.168.1.2 or 10.0.0.0/24) of reverse proxies in front of the hub. Only a request whose direct sender is one of these — or this host itself, as with the Cloudflare tunnel — has its X-Forwarded-For / CF-Connecting-IP read as the real client address for rate limits. Leave empty unless a proxy on another host forwards to the hub.",
+						creatable: true
+					},
+					{
+						type: "info",
+						key: "trustedNetworksWarning",
+						label: "Skipping two-factor authentication",
+						variant: "danger",
+						content: "A sign-in made DIRECTLY from a network listed below skips the second factor (TOTP or passkey): anyone on that network who knows or guesses a password gets in with the password alone — including a compromised camera or a guest device. Requests that come through the Cloudflare tunnel, the public address or any reverse proxy never skip it, whatever address they claim. Every skip is recorded in the authentication audit log. Leave empty (the default) to always ask for the second factor."
+					},
+					{
+						type: "tags",
+						key: "trustedNetworks",
+						label: "Trusted networks (skip the second factor)",
+						description: "Addresses or CIDR ranges, e.g. 192.168.1.0/24. Keep it as narrow as you can — a single trusted VLAN, not the whole LAN.",
+						creatable: true
+					}
+				]
 			},
 			{
 				id: SYSTEM_CONFIG_CLUSTER_SECTION_ID,
 				title: SECTION_TITLES["cluster"],
-				description: "Agents joining this hub. Optional: with no cluster secret, any node that reaches the hub may register.",
+				description: "Agents joining this hub. Every agent proves the cluster secret when it connects (challenge–response; the secret never crosses the network).",
 				columns: 1,
-				fields: [{
-					type: "password",
-					key: CLUSTER_SECRET_FIELD,
-					label: "Cluster secret",
-					description: "When set, an agent must present it to register. Stored in the keychain. To pair an agent: Reveal and copy it here, then enter it in the agent at first run (its status page or the desktop setup window). Changing it disconnects agents that still hold the old one at their next registration."
-				}]
+				fields: [
+					{
+						type: "password",
+						key: CLUSTER_SECRET_FIELD,
+						label: "Cluster secret",
+						description: "Mandatory — generated by the hub at first boot and stored in the keychain. To pair an agent: Reveal and copy it here, then enter it in the agent (its status page, or the desktop setup window). Saving a new value rotates it: every agent must then be given the new one."
+					},
+					{
+						type: "select",
+						key: MESH_AUTH_MODE_FIELD,
+						label: "Agents without the secret",
+						description: "Transition lets an agent that has not authenticated keep working (with a warning) while you give each agent the secret; it ends by itself once every known agent has authenticated. Enforced refuses it.",
+						default: "transition",
+						options: [{
+							value: "transition",
+							label: "Transition — allow, warn"
+						}, {
+							value: "enforced",
+							label: "Enforced — refuse"
+						}]
+					},
+					{
+						type: "info",
+						key: "meshAuthStatus",
+						label: "Mesh authentication",
+						content: describeMeshStatus(getProcessMeshAuthStatus()),
+						variant: "info"
+					}
+				]
 			}
 		] };
 	}
@@ -307,6 +539,10 @@ var SystemConfigAddon = class extends require_dist.BaseAddon {
 				this.ctx.logger.warn("update ignored read-only server-section key", { meta: { key } });
 				continue;
 			}
+			if (CIDR_LIST_KEYS.has(key)) {
+				const { invalid } = parseCidrList(readCidrSetting(value));
+				if (invalid.length > 0) throw new Error(`Not a network address or CIDR range: ${invalid.join(", ")}`);
+			}
 			let bucket = perSection.get(section);
 			if (!bucket) {
 				bucket = {};
@@ -328,13 +564,52 @@ var SystemConfigAddon = class extends require_dist.BaseAddon {
 	}
 	/**
 	* The cluster secret's save path: the value goes to the keychain (owner
-	* `system`), the row gets the marker; `''` / a view keeps, `$secretClear`
-	* clears. A value the keychain cannot store is REFUSED — never written
-	* inline (D787, P5).
+	* `system`), the row gets the marker; `''` / a view keeps. `$secretClear` is
+	* REFUSED: the secret is mandatory (D802). A value the keychain cannot store
+	* is REFUSED — never written inline (D787, P5). `meshAuth` is a plain value.
 	*/
 	async writeClusterSection(patch) {
+		const { [MESH_AUTH_MODE_FIELD]: mode, ...secretPatch } = patch;
+		if (mode !== void 0) {
+			if (!isMeshAuthMode(mode)) throw new Error(`system-config: meshAuth must be 'transition' or 'enforced'`);
+			await this.writeMeshAuthMode(mode);
+		}
+		if (Object.keys(secretPatch).length === 0) return;
+		if (require_dist.isSecretClear(secretPatch["clusterSecret"])) throw new Error("The cluster secret is mandatory and cannot be cleared — save a new value to rotate it");
+		await this.storeClusterSecret(secretPatch);
+		this.ctx.logger.info("Cluster secret updated");
+		await this.clusterSecretKeeper?.reload();
+	}
+	/** `cluster.meshAuth` (D802), then republish it. */
+	async writeMeshAuthMode(mode) {
+		await this.ctx.settings.setSection("cluster", { [MESH_AUTH_MODE_FIELD]: mode });
+		await this.clusterSecretKeeper?.reload();
+	}
+	/**
+	* First boot, or a keychain reset that cleared the marker (D802): a fresh
+	* random secret, stored like an operator save. A NEW secret means every
+	* agent must be given it, so the mesh goes (back) to `transition`; on a hub
+	* with no agent yet, the hub's auto-enforce ends it at once.
+	*/
+	async generateClusterSecret() {
 		const settings = this.ctx.settings;
 		const secrets = this.systemSecrets();
+		if (!settings || secrets === null) throw new Error("system-config: no keychain door — the cluster secret cannot be generated");
+		const existing = (await secrets.resolve([require_cluster_secret.CLUSTER_SECRET_REF]))[require_cluster_secret.CLUSTER_SECRET_REF];
+		if (existing?.kind === "value") {
+			await settings.setSection("cluster", { [CLUSTER_SECRET_FIELD]: require_dist.makeSecretMarker(require_cluster_secret.CLUSTER_SECRET_REF) });
+			this.ctx.logger.warn("The cluster secret row was empty but the keychain holds a value — re-adopted it");
+			return;
+		}
+		if (existing?.kind !== "missing") throw new Error(`the keychain cannot answer for the cluster secret (${existing?.kind ?? "no answer"})`);
+		const value = (0, node_crypto.randomBytes)(GENERATED_SECRET_BYTES).toString("base64url");
+		await this.storeClusterSecret({ [CLUSTER_SECRET_FIELD]: value });
+		await settings.setSection("cluster", { [MESH_AUTH_MODE_FIELD]: "transition" });
+	}
+	async storeClusterSecret(patch) {
+		const settings = this.ctx.settings;
+		if (!settings) throw new Error("system-config: ctx.settings not available");
+		const secrets = this.systemSecrets();
 		if (secrets === null) throw new Error("system-config: no keychain door — the cluster secret cannot be stored");
 		const stored = await settings.getSection("cluster");
 		const result = await require_dist.transformSecretWrite({
@@ -346,12 +621,23 @@ var SystemConfigAddon = class extends require_dist.BaseAddon {
 		});
 		if (Object.keys(result.patch).length > 0) await settings.setSection("cluster", result.patch);
 		const { orphaned } = await result.afterWrite();
-		if (orphaned.length > 0) this.ctx.logger.warn("cluster secret cleared, but its old keychain value could not be deleted", { meta: { refs: orphaned } });
-		this.ctx.logger.info("Cluster secret updated");
-		await this.clusterSecretKeeper?.reload();
+		if (orphaned.length > 0) this.ctx.logger.warn("an old cluster secret value could not be deleted from the keychain", { meta: { refs: orphaned } });
 	}
 };
 //#endregion
+exports.MESH_AUTH_MODE_FIELD = MESH_AUTH_MODE_FIELD;
 exports.SYSTEM_CONFIG_CLUSTER_SECTION_ID = SYSTEM_CONFIG_CLUSTER_SECTION_ID;
 exports.SystemConfigAddon = SystemConfigAddon;
 exports.default = SystemConfigAddon;
+exports.createCidrMatcher = createCidrMatcher;
+exports.getProcessMeshAuthMode = getProcessMeshAuthMode;
+exports.getProcessMeshAuthStatus = getProcessMeshAuthStatus;
+exports.isMeshAuthMode = isMeshAuthMode;
+exports.normalizeIp = normalizeIp;
+exports.parseCidrList = parseCidrList;
+exports.parseMeshAuthMode = parseMeshAuthMode;
+exports.readCidrSetting = readCidrSetting;
+exports.requestProcessMeshEnforcement = requestProcessMeshEnforcement;
+exports.setProcessMeshAuthMode = setProcessMeshAuthMode;
+exports.setProcessMeshAuthStatusSource = setProcessMeshAuthStatusSource;
+exports.setProcessMeshEnforcer = setProcessMeshEnforcer;