@camstack/system 1.2.357 → 1.2.359

package/dist/builtins/local-auth/local-auth.addon.mjs

@@ -1,8 +1,11 @@
 import { i as __require, o as __toESM, t as __commonJSMin } from "../../chunk-CNf5ZN-e.mjs";
-import { An as userManagementCapability, H as UserRecordSchema, L as ScopedTokenSchema, Qn as BaseAddon, q as authProviderCapability, r as ApiKeyRecordSchema } from "../../dist-B7WRgEZY.mjs";
+import { H as UserRecordSchema, In as userManagementCapability, L as ScopedTokenSchema, ar as BaseAddon, q as authProviderCapability, r as ApiKeyRecordSchema } from "../../dist-pTfD_M-U.mjs";
+import { z } from "zod";
 import * as crypto$2 from "node:crypto";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import nodeCrypto from "crypto";
+import * as path$1 from "node:path";
+import * as fs from "node:fs";
 //#region src/auth/parse-record.ts
 function parseRecord(kind, schema, data) {
 	try {
@@ -6700,15 +6703,44 @@ var UserManager = class {
 			}
 		});
 	}
-	async ensureAdminExists() {
+	/**
+	* Seed the configured admin (`auth.adminUsername` / `auth.adminPassword`,
+	* i.e. `CAMSTACK_ADMIN_USER` / `CAMSTACK_ADMIN_PASS`) — on FIRST boot only.
+	*
+	* The configured password is a seed, never an authority. Once any admin
+	* exists, this never writes a password: the operator's own change in the
+	* admin UI is the truth from then on. This method used to compare the stored
+	* hash with the configured password on every boot and rewrite it when they
+	* differed, so a password changed in the UI went back to the configured one
+	* (`changeme` on a Mac hub and on any container without `CAMSTACK_ADMIN_PASS`)
+	* at the next restart.
+	*
+	* `resetPassword: true` is the one explicit exception — the operator's
+	* one-shot recovery request (see `admin-password-reset.ts`): the configured
+	* admin's password is set back to the configured one.
+	*/
+	async ensureAdminExists(options = {}) {
 		const adminUsername = this.config.get("auth.adminUsername");
 		const adminPassword = this.config.get("auth.adminPassword");
-		if (!adminUsername || !adminPassword) return;
+		if (!adminUsername || !adminPassword) return { kind: "not-configured" };
 		const existing = await this.findByUsername(adminUsername);
 		if (existing) {
-			if (!await this.auth.comparePassword(adminPassword, existing.passwordHash)) await this.resetPassword(existing.id, adminPassword);
-			return;
+			if (options.resetPassword === true) {
+				await this.resetPassword(existing.id, adminPassword);
+				return {
+					kind: "reset",
+					username: adminUsername
+				};
+			}
+			return {
+				kind: "exists",
+				username: adminUsername
+			};
 		}
+		if ((await this.listAll()).some((u) => u.isAdmin)) return {
+			kind: "other-admin-exists",
+			username: adminUsername
+		};
 		await this.create({
 			username: adminUsername,
 			password: adminPassword,
@@ -6716,6 +6748,19 @@ var UserManager = class {
 			allowedProviders: "*",
 			allowedDevices: {}
 		});
+		return {
+			kind: "seeded",
+			username: adminUsername
+		};
+	}
+	/**
+	* Does `username` still sign in with `password`? A hash comparison — the
+	* password is never logged or stored. `false` when the user does not exist.
+	*/
+	async hasPassword(username, password) {
+		const user = await this.findByUsername(username);
+		if (!user) return false;
+		return this.auth.comparePassword(password, user.passwordHash);
 	}
 }, i$2 = class extends Error {
 	constructor(e, t) {
@@ -7395,7 +7440,7 @@ function alphabet(letters) {
 /**
 * @__NO_SIDE_EFFECTS__
 */
-function join(separator = "") {
+function join$1(separator = "") {
 	astr("join", separator);
 	return {
 		encode: (from) => {
@@ -7505,7 +7550,7 @@ function unsafeWrapper(fn) {
 		} catch (e) {}
 	};
 }
-chain(radix2(4), alphabet("0123456789ABCDEF"), join(""));
+chain(radix2(4), alphabet("0123456789ABCDEF"), join$1(""));
 /**
 * base32 encoding from RFC 4648. Has padding.
 * RFC 4648 §6 Table 3 uses uppercase letters, and RFC 4648 §3.4 allows applications to choose
@@ -7520,17 +7565,17 @@ chain(radix2(4), alphabet("0123456789ABCDEF"), join(""));
 * // => Uint8Array.from([0x12, 0xab])
 * ```
 */
-var base32 = /* @__PURE__ */ Object.freeze(chain(radix2(5), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), padding(5), join("")));
-chain(radix2(5), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), join(""));
-chain(radix2(5), alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), padding(5), join(""));
-chain(radix2(5), alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), join(""));
-chain(radix2(5), alphabet("0123456789ABCDEFGHJKMNPQRSTVWXYZ"), join(""), normalize((s) => s.toUpperCase().replace(/O/g, "0").replace(/[IL]/g, "1")));
+var base32 = /* @__PURE__ */ Object.freeze(chain(radix2(5), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), padding(5), join$1("")));
+chain(radix2(5), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"), join$1(""));
+chain(radix2(5), alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), padding(5), join$1(""));
+chain(radix2(5), alphabet("0123456789ABCDEFGHIJKLMNOPQRSTUV"), join$1(""));
+chain(radix2(5), alphabet("0123456789ABCDEFGHJKMNPQRSTVWXYZ"), join$1(""), normalize((s) => s.toUpperCase().replace(/O/g, "0").replace(/[IL]/g, "1")));
 var hasBase64Builtin = /* @__PURE__ */ (() => typeof Uint8Array.from([]).toBase64 === "function" && typeof Uint8Array.fromBase64 === "function")();
-hasBase64Builtin || chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), padding(6), join(""));
-chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), join(""));
-hasBase64Builtin || chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), padding(6), join(""));
-chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), join(""));
-var BECH_ALPHABET = chain(alphabet("qpzry9x8gf2tvdw0s3jn54khce6mua7l"), join(""));
+hasBase64Builtin || chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), padding(6), join$1(""));
+chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"), join$1(""));
+hasBase64Builtin || chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), padding(6), join$1(""));
+chain(radix2(6), alphabet("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"), join$1(""));
+var BECH_ALPHABET = chain(alphabet("qpzry9x8gf2tvdw0s3jn54khce6mua7l"), join$1(""));
 var POLYMOD_GENERATORS = [
 	996825010,
 	642813549,
@@ -7624,7 +7669,7 @@ function genBech32(encoding) {
 }
 genBech32("bech32");
 genBech32("bech32m");
-/* @__PURE__ */ (() => typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function")() || chain(radix2(4), alphabet("0123456789abcdef"), join(""), normalize((s) => {
+/* @__PURE__ */ (() => typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function")() || chain(radix2(4), alphabet("0123456789abcdef"), join$1(""), normalize((s) => {
 	if (typeof s !== "string" || s.length % 2 !== 0) throw new TypeError(`hex.decode: expected string, got ${typeof s} with length ${s.length}`);
 	return s.toLowerCase();
 }));
@@ -9023,6 +9068,204 @@ var TotpManager = class {
 	}
 };
 //#endregion
+//#region src/kernel/config-schema.ts
+/** Default data directory — used when CAMSTACK_DATA env var is not set */
+var DEFAULT_DATA_PATH = "camstack-data";
+/**
+* A list of browser origins from config.yaml (a YAML list) or from the
+* `CAMSTACK_CORS_ORIGINS` env var (one comma-separated string — env carries
+* only strings). Validation of each entry is the CORS policy's job
+* (`server/backend/src/api/cors/cors-policy.ts`), which logs what it rejects;
+* the schema only fixes the SHAPE so a typo cannot stop the hub from booting.
+*/
+var originListSchema = z.preprocess((value) => typeof value === "string" ? value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0) : value, z.array(z.string()));
+var serverSchema = z.object({
+	port: z.number().default(4443),
+	host: z.string().default("0.0.0.0"),
+	dataPath: z.string().default(DEFAULT_DATA_PATH),
+	/**
+	* EXTRA browser origins allowed to call this hub cross-origin (D707), on
+	* top of the built-ins: the hub's own origin, the hosted viewer PWA and the
+	* native app's opaque `null` origin. Bootstrap-owned on purpose — widening
+	* who may read hub responses in a browser is a security decision, and the
+	* policy is live from the first request, before the settings store exists.
+	*/
+	corsOrigins: originListSchema.default([])
+});
+var authSchema = z.object({
+	jwtSecret: z.string().nullable().default(null),
+	adminUsername: z.string().default("admin"),
+	adminPassword: z.string().default("changeme")
+});
+var hubSchema = z.object({
+	url: z.string().default("ws://localhost:4443/agent"),
+	token: z.string().default("")
+});
+var agentSchema = z.object({
+	name: z.string().default(""),
+	/** Port for the agent status page (minimal HTML) */
+	statusPort: z.number().default(4444)
+});
+var tlsSchema = z.object({ 
+/**
+* Enable HTTPS (default: true). The certificate itself is never configured
+* here: the admin UI (Network → Local access) generates or uploads it
+* (D726), and boot serves whatever `tls/mode` says.
+*/
+enabled: z.boolean().default(true) });
+/**
+* Bootstrap-time addon configuration — read PURELY from YAML, before the
+* kernel can talk to the settings-store. This breaks the chicken-and-egg
+* where the settings store itself is implemented by an addon: the kernel
+* needs to know WHICH addon to load first to provide the store, and that
+* decision can't itself live in the store.
+*
+* Backward-compatible: every field is optional + defaults reproduce the
+* current hard-coded behavior. Existing config.yaml files keep working.
+*/
+var bootstrapAddonsSchema = z.object({
+	/**
+	* Addon implementing the `settings-store` capability. Loaded FIRST,
+	* before any other addon is enabled — every other addon's enable
+	* state, settings, and ordering lives in the store it provides.
+	*
+	* Default: '@camstack/addon-sqlite-storage' (the workspace's
+	* default SQLite-backed store). Future alternatives could swap this
+	* for postgres/redis without touching kernel code.
+	*/
+	settingsStoreAddon: z.string().default("@camstack/addon-sqlite-storage"),
+	/**
+	* How the launcher provisions REQUIRED_PACKAGES into `data/addons/`
+	* on startup.
+	*
+	*   - `'npm'`     — pull from the npm registry (production default).
+	*   - `'local'`   — copy `packages/<X>/` from the workspace into
+	*                   `data/addons/<X>/`. Use for the Electron-
+	*                   packaged bundle and the e2e harness.
+	*   - `'symlink'` — point `data/addons/<X>` at the workspace source
+	*                   dir via a directory symlink. Dev-only: a
+	*                   workspace rebuild (`npm run build -w <X>`) is
+	*                   immediately reflected at the next addon load,
+	*                   no copy step. Falls back to `'local'` on
+	*                   platforms that reject symlink creation (Windows
+	*                   without developer-mode).
+	*
+	* The `CAMSTACK_INSTALL_SOURCE` env var, when set, wins over this
+	* field. Leave undefined to keep the launcher's default behaviour
+	* (npm when no workspace, local when a bundled addons dir is
+	* present, …).
+	*/
+	installSource: z.enum([
+		"npm",
+		"local",
+		"symlink"
+	]).optional(),
+	/**
+	* Override the kernel's hard-coded `AddonInstaller.REQUIRED_PACKAGES`.
+	* Passing an array here REPLACES the default list entirely — useful
+	* for stripped-down deployments (only the bundle of addons the
+	* operator actually wants) and for forcing a different storage
+	* backend at first boot.
+	*
+	* Leave undefined to use the kernel-shipped defaults.
+	*/
+	requiredAddons: z.array(z.string()).optional(),
+	/**
+	* Disable list applied AFTER the settings-store reports the enabled
+	* set. Operator escape hatch — boot without a known-broken addon
+	* without having to mutate the store.
+	*/
+	forceDisable: z.array(z.string()).default([])
+});
+/** Bootstrap config -- loaded from config.yaml ONLY at startup.
+*  All other settings live in SQL (system_settings table). */
+var bootstrapSchema = z.object({
+	/** Server mode: 'hub' (full server) or 'agent' (worker node) */
+	mode: z.enum(["hub", "agent"]).default("hub"),
+	server: serverSchema.default(serverSchema.parse({})),
+	auth: authSchema.default(authSchema.parse({})),
+	/** Hub connection config — only used when mode='agent' */
+	hub: hubSchema.default(hubSchema.parse({})),
+	/** Agent-specific config — only used when mode='agent' */
+	agent: agentSchema.default(agentSchema.parse({})),
+	/** TLS configuration */
+	tls: tlsSchema.default(tlsSchema.parse({})),
+	/**
+	* Addon bootstrap directives — minimum addon set needed before the
+	* kernel can reach the settings-store. See bootstrapAddonsSchema.
+	* Spec: docs/superpowers/specs/2026-05-15-yaml-bootstrap-expansion.md
+	*/
+	bootstrap: bootstrapAddonsSchema.default(bootstrapAddonsSchema.parse({}))
+});
+//#endregion
+//#region src/builtins/local-auth/admin-account-boot.ts
+/**
+* The admin account at boot: seed it once, reset it only on the operator's
+* explicit one-shot request, and say so when it still has the default password.
+*
+* ## Why a trigger FILE, not a variable
+*
+* The configured password (`CAMSTACK_ADMIN_PASS` / `auth.adminPassword`) seeds
+* the admin on first boot and is never applied again — a password the operator
+* changes in the admin UI survives every restart. Recovering a forgotten
+* password therefore needs an explicit request, and that request must be
+* ONE-SHOT: an environment flag stays set in a container template until someone
+* remembers to remove it, and while it is set it reverts the password on every
+* boot — the very defect this replaced. A file the hub DELETES after acting on
+* it cannot be left armed: create `RESET_ADMIN_PASSWORD` in the node's data
+* directory (`/data` in the container), restart, and the configured admin's
+* password is set back to the configured one, once.
+*/
+/** The trigger's name, at the root of the node's data directory. */
+var ADMIN_PASSWORD_RESET_TRIGGER = "RESET_ADMIN_PASSWORD";
+async function reconcileAdminAccountAtBoot(input) {
+	const { users, fs, logger } = input;
+	const triggerPath = path$1.join(input.dataDir, ADMIN_PASSWORD_RESET_TRIGGER);
+	const resetRequested = fs.exists(triggerPath);
+	const outcome = await users.ensureAdminExists({ resetPassword: resetRequested });
+	logOutcome(outcome, logger);
+	if (resetRequested) consumeTrigger(triggerPath, outcome, input);
+	const username = "username" in outcome ? outcome.username : null;
+	const usesDefaultPassword = username !== null && await users.hasPassword(username, "changeme");
+	if (usesDefaultPassword && username !== null) logger.warn("The admin account still uses the default password — change it in the admin UI (the first sign-in with it asks for a new one)", { meta: { username } });
+	return {
+		outcome,
+		usesDefaultPassword
+	};
+}
+function logOutcome(outcome, logger) {
+	switch (outcome.kind) {
+		case "seeded":
+			logger.info("Admin account seeded from the configured credentials (first boot)", { meta: { username: outcome.username } });
+			return;
+		case "reset":
+			logger.warn("Admin password reset to the configured password, as requested", { meta: { username: outcome.username } });
+			return;
+		case "other-admin-exists":
+			logger.info("Configured admin username not seeded: another admin account already exists", { meta: { username: outcome.username } });
+			return;
+		case "not-configured":
+			logger.warn("No admin username/password configured — no admin account seeded");
+			return;
+		case "exists": return;
+	}
+}
+/** Delete the trigger after acting on it — a reset must never repeat by itself. */
+function consumeTrigger(triggerPath, outcome, input) {
+	if (outcome.kind !== "reset") input.logger.warn("Admin password reset requested, but no configured admin account to reset", { meta: {
+		trigger: triggerPath,
+		outcome: outcome.kind
+	} });
+	try {
+		input.fs.remove(triggerPath);
+	} catch (err) {
+		input.logger.error("Could not delete the admin password reset trigger — delete it by hand, or every restart resets the admin password again", { meta: {
+			trigger: triggerPath,
+			error: err instanceof Error ? err.message : String(err)
+		} });
+	}
+}
+//#endregion
 //#region src/builtins/local-auth/auth-config-reader.ts
 /**
 * Every config path this reader can answer. Anything else resolves to
@@ -9058,8 +9301,9 @@ function narrow(value) {
 //#region src/builtins/local-auth/auth-schema.ts
 /**
 * @durable class=config owner=local-auth
-*   write="an operator creates a user, or `ensureAdminExists` seeds/re-syncs the
-*     configured admin at boot; updated on scope, isAdmin and password edits"
+*   write="an operator creates a user, or `ensureAdminExists` seeds the configured
+*     admin on first boot (or resets its password on the operator's one-shot
+*     RESET_ADMIN_PASSWORD trigger); updated on scope, isAdmin and password edits"
 *   retention="none — a row goes only when an operator deletes the user. A
 *     `declareCollection` that adds a PK/UNIQUE/NOT-NULL-without-default column
 *     REBUILDS the table: every account is wiped and only the configured admin
@@ -9667,6 +9911,23 @@ var OauthSessionManager = class {
 };
 //#endregion
 //#region src/builtins/local-auth/local-auth.addon.ts
+/**
+* Local Auth Addon — owns user accounts, API keys, scoped tokens,
+* and local password authentication.
+*
+* Capabilities registered:
+*   - `auth-provider` (collection) — local password authentication
+*   - `user-management` (singleton) — user CRUD, API keys, scoped tokens
+*
+* This addon owns the OAuth grant MACHINERY (codes, sessions, refresh) but
+* declares no `oauth-integration` client of its own, and must not start: which
+* clients exist is integration-specific knowledge and belongs to the addon that
+* owns the integration (D101). `homeassistant` moved to `homeassistant-export`;
+* `export-alexa` was always there.
+*
+* Extension: an OIDC addon can register another `auth-provider` entry.
+* The server's login flow iterates the `auth-provider` collection.
+*/
 /** How often the auth tables are swept for dead rows. */
 var AUTH_REAP_INTERVAL_MS = 24 * 36e5;
 /**
@@ -9724,7 +9985,15 @@ var LocalAuthAddon = class extends BaseAddon {
 			this.oauthSessionManager = new OauthSessionManager(store);
 			this.totpManager = new TotpManager(store);
 			try {
-				await this.userManager.ensureAdminExists();
+				await reconcileAdminAccountAtBoot({
+					users: this.userManager,
+					dataDir: this.ctx.nodeDataDir,
+					fs: {
+						exists: (filePath) => fs.existsSync(filePath),
+						remove: (filePath) => fs.rmSync(filePath, { force: true })
+					},
+					logger: this.ctx.logger
+				});
 				const liveUsers = await this.userManager.listAll();
 				const liveIds = new Set(liveUsers.map((u) => u.id));
 				const removed = await this.scopedTokenManager.cleanupOrphans(liveIds);
@@ -9976,4 +10245,4 @@ var LocalAuthAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { LocalAuthAddon, LocalAuthAddon as default, isSettingsReadUnavailable as a, ApiKeyManager as c, SettingsReadUnavailableError as i, ScopedTokenManager as n, require_ms as o, AuthManager as r, require_safe_buffer as s, UserManager as t };
+export { LocalAuthAddon, LocalAuthAddon as default, AuthManager as a, require_ms as c, ScopedTokenManager as i, require_safe_buffer as l, bootstrapSchema as n, SettingsReadUnavailableError as o, UserManager as r, isSettingsReadUnavailable as s, DEFAULT_DATA_PATH as t, ApiKeyManager as u };

package/dist/builtins/local-network/address-book.d.ts

@@ -0,0 +1,69 @@
+import { ConnectionEndpoint, HubAddressBook, HubAddressFlags, HubAddressRole } from '@camstack/types';
+export interface CustomAddress {
+    readonly baseUrl: string;
+    readonly label: string;
+}
+/** The address-book keys of the addon's stored settings. */
+export interface StoredAddressSettings {
+    readonly customAddresses: unknown;
+    readonly viewerBaseUrls: readonly string[];
+    readonly notificationBaseUrl: string;
+    readonly agentBaseUrl: string;
+    readonly signInBaseUrl: string;
+}
+export interface AddressBookState {
+    readonly custom: readonly CustomAddress[];
+    readonly flags: HubAddressFlags;
+}
+/** Parse the stored custom list; a malformed store reads as empty, never throws. */
+export declare function parseCustomAddresses(raw: unknown): readonly CustomAddress[];
+/**
+ * The address book as it stands: stored custom addresses, plus every
+ * single-valued flag that names neither a detected address, a custom one nor
+ * the app link, promoted to a custom address (see the module doc).
+ */
+export declare function normalizeAddressBook(stored: StoredAddressSettings, detectedUrls: ReadonlySet<string>): AddressBookState;
+/** The stored-settings patch that persists `state`. */
+export declare function addressBookPatch(state: AddressBookState): {
+    readonly customAddresses: readonly CustomAddress[];
+    readonly viewerBaseUrls: readonly string[];
+    readonly notificationBaseUrl: string;
+    readonly agentBaseUrl: string;
+    readonly signInBaseUrl: string;
+};
+export declare function withCustomAddress(state: AddressBookState, entry: CustomAddress): AddressBookState;
+/** Drop a custom address and every flag it carried (those roles turn automatic). */
+export declare function withoutCustomAddress(state: AddressBookState, baseUrl: string): AddressBookState;
+/** Every role back to automatic for `role`. */
+export declare function withRoleAutomatic(state: AddressBookState, role: HubAddressRole): AddressBookState;
+/**
+ * Flag or unflag `baseUrl` for `role`. A single-valued role flagged here moves
+ * off every other address (it is one URL); unflagging the address that carries
+ * it returns the role to automatic. The app link flagged for notifications IS
+ * the automatic answer, stored as automatic — one representation. `viewer`
+ * toggles inside the set; toggling while automatic starts from the automatic
+ * set (`autoViewer`) so the other addresses keep racing.
+ */
+export declare function withRoleFlag(state: AddressBookState, role: HubAddressRole, baseUrl: string, enabled: boolean, autoViewer: readonly string[]): AddressBookState;
+/** What a row may be flagged with. */
+export declare function eligibleRoles(endpoint: ConnectionEndpoint): readonly HubAddressRole[];
+export declare const CUSTOM_ADDRESS_PRIORITY = 200;
+/** A custom address as a palette entry (`kind: 'custom'`). */
+export declare function customEndpoint(entry: CustomAddress): ConnectionEndpoint;
+/**
+ * The palette a client races: the detected endpoints plus the custom
+ * addresses flagged `viewer` (a detected URL is never listed twice).
+ */
+export declare function withViewerCustomEndpoints(detected: readonly ConnectionEndpoint[], state: AddressBookState): ConnectionEndpoint[];
+export interface AddressBookInputs {
+    /** Detected endpoints in the scheme the rows are shown in. */
+    readonly rowsPalette: readonly ConnectionEndpoint[];
+    /** Detected endpoints over HTTPS — what agents and sign-in resolve over. */
+    readonly httpsPalette: readonly ConnectionEndpoint[];
+    readonly appLink: ConnectionEndpoint;
+    readonly appLinkHub: string | null;
+}
+/** Every role's answer — the resolvers from `@camstack/types`, nothing else. */
+export declare function resolveRoles(state: AddressBookState, viewerPalette: readonly ConnectionEndpoint[], httpsPalette: readonly ConnectionEndpoint[]): HubAddressBook['roles'];
+/** The Addresses table: app link, detected rows, then custom-only rows. */
+export declare function buildAddressBook(state: AddressBookState, inputs: AddressBookInputs): HubAddressBook;

package/dist/builtins/local-network/local-network.addon.d.ts

@@ -1,4 +1,5 @@
 import { AdvertisedLocalPort, ConnectionEndpoint, LocalInterface, ProviderRegistration, BaseAddon } from '@camstack/types';
+import { CustomAddress } from './address-book.js';
 /**
  * Cached mesh-reachable endpoint, learned from the `mesh-network`
  * provider via the `MeshNetworkChanged` event-tail + pull-reconcile.
@@ -32,24 +33,30 @@ interface LocalNetworkConfig {
      *  allowlist" (true + empty → respect operator's choice). */
     readonly bootSeeded: boolean;
     /**
-     * The endpoint outbound artifacts (notification attachment links, deep
-     * links) must be addressed by. Empty = AUTO: the first public candidate,
-     * never loopback. Stored VERBATIM rather than as an index into the candidate
-     * list — interfaces come and go, and an index would silently re-point at a
-     * different address after a reboot.
+     * Role flag `notifications` (D709): the ONE address notification links are
+     * addressed by. Empty = automatic (the CamStack app link). Stored VERBATIM
+     * rather than as an index into the candidate list — interfaces come and go,
+     * and an index would silently re-point after a reboot. See `address-book.ts`.
      */
     readonly notificationBaseUrl: string;
-    /**
-     * Base URLs the SDK / viewer should race. Empty = AUTO (LAN IPv4 + public
-     * tunnel). Stored verbatim, same contract as `notificationBaseUrl`.
-     */
+    /** Role flag `viewer`: the addresses the apps race. Empty = automatic. */
     readonly viewerBaseUrls: readonly string[];
+    /** Operator-entered custom addresses (`address-book.ts`). Parsed on read. */
+    readonly customAddresses: readonly CustomAddress[];
     /** LAN HTTP listener. Default true — native apps skip the private cert. */
     readonly httpEnabled: boolean;
     /** Dedicated HTTP port. Must not equal the HTTPS listen port. */
     readonly httpPort: number;
     /** Operator-declared DNS name advertised instead of the raw LAN IP. Empty = none. */
     readonly localHostname: string;
+    /**
+     * Role flag `agents`: the ONE address agents and LAN devices pull from.
+     * Empty = automatic. The key is the D729 amendment's override, kept so a
+     * rolled-back hub reads it with the meaning it knew.
+     */
+    readonly agentBaseUrl: string;
+    /** Role flag `signIn`: the ONE sign-in address. Empty = automatic. Same key story. */
+    readonly signInBaseUrl: string;
 }
 export declare class LocalNetworkAddon extends BaseAddon<LocalNetworkConfig> {
     private pollTimer;
@@ -68,27 +75,42 @@ export declare class LocalNetworkAddon extends BaseAddon<LocalNetworkConfig> {
     private meshEndpoint;
     constructor();
     /**
-     * The effective flagged notification address: the operator's explicit
-     * choice, else AUTO — the CamStack app link (D709, operator decision
-     * 2026-10-06; before it AUTO was the tunnel, then the mesh). The app link is
-     * not a hub address: the NC's signed media and buttons keep their own hub
-     * ladder when it is flagged; only viewer taps take the app form.
+     * The detected palettes, with the mesh reconciled once: `https` (what agents
+     * and sign-in resolve over, and the app link's `hub=`) and `http` (what the
+     * viewer race resolves over, as before).
      */
-    private resolveNotificationEndpoint;
+    private palettes;
+    /** The stored address book, normalised against what is detected now. */
+    private addressState;
+    /** The role flags alone — they do not depend on what is detected. */
+    private storedFlags;
+    /** `getAddresses`: the Addresses table and every role's answer. */
+    private addressBook;
     /**
-     * The `hub=` an app link carries: the best public HTTPS address in this
-     * cap's own palette (tunnel, then mesh) — so it can never disagree with
-     * what the Network page lists. See `pickAppLinkHub`.
+     * Apply one change to the address book and persist it, normalised (a flag
+     * naming an address in no row becomes a custom address in the same write).
      */
-    private resolveAppLinkHub;
+    private changeAddressBook;
+    /** The deprecated `getHubAddresses` shape, from the role resolvers. */
+    private snapshotHubAddresses;
+    /**
+     * Flag / unflag `baseUrl` for `role`, or (`baseUrl: null`) return the role
+     * to automatic. Validated: the address must be a row (detected, custom, or
+     * the app link for notifications), never loopback, and `signIn` on plain
+     * http only when accepted. A refusal stores nothing.
+     */
+    private setRole;
     private notificationEndpointSnapshot;
     private snapshotViewerEndpoints;
     /**
-     * Palette shown in the Network tab: LAN IPv4, stable LAN IPv6, public,
-     * mesh. The viewer HTTP/WS race is a subset (`selectViewerEndpoints`) —
-     * IPv6 stays in this list because ICE/WebRTC gathers it regardless.
+     * Palette shown to clients: LAN IPv4, stable LAN IPv6, public, mesh, and
+     * the custom addresses flagged `viewer` (`kind: 'custom'`). The viewer
+     * HTTP/WS race is a subset (`selectViewerEndpoints`) — IPv6 stays in this
+     * list because ICE/WebRTC gathers it regardless.
      */
     private buildAdvertisedEndpoints;
+    /** The DETECTED palette from the cached interface/tunnel/mesh state. */
+    private endpointsNow;
     protected onInitialize(): Promise<ProviderRegistration[]>;
     protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
     protected onConfigChanged(): Promise<void>;
@@ -228,16 +250,6 @@ export interface LanHttpAdvertisement {
  */
 export declare function appLinkEndpoint(): ConnectionEndpoint;
 export declare function buildEndpoints(interfaces: readonly LocalInterface[], port: number, includeLoopback: boolean, ipv4Only: boolean, publicHostname: string, scheme?: 'http' | 'https', meshEndpoint?: MeshEndpointCache | null, lanHttp?: LanHttpAdvertisement | null): ConnectionEndpoint[];
-/** AUTO viewer race: LAN IPv4 + the public tunnel. Never IPv6, mesh, or loopback. */
-export declare function isDefaultViewerEndpoint(endpoint: ConnectionEndpoint): boolean;
-/**
- * The URLs the SDK should race for API / viewer access.
- *
- * Empty `viewerBaseUrls` = AUTO (IPv4 + public tunnel). A non-empty list is
- * the operator's pin; if none of those URLs are in the current palette,
- * fall back to AUTO rather than racing an empty set.
- */
-export declare function selectViewerEndpoints(endpoints: readonly ConnectionEndpoint[], viewerBaseUrls: readonly string[]): ConnectionEndpoint[];
 /**
  * First-boot heuristic: which addresses should the allowlist start
  * with? Includes LAN + Wi-Fi IPv4 addresses + plausible IPv6: