home-hosted 0.6.7 → 0.6.8

package/AGENTS.md

@@ -6,11 +6,12 @@ and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port con
 `docs/NOTIFICATIONS.md`, `docs/DDNS.md`; UI authors: `docs/UI_CREATION.md`.
 
 State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
-`.control-secrets.json` (0600: password hash, API token hash, Telegram bot token, DDNS credentials),
-`.logs/`, `.tls/`, `.backups/`, `.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600
-spawn spec until the nanny reads it, plus `ddns.json` — the last address each target confirmed), and
-`run.json` — the live daemon's pid/url/token, 0600. The package ships **no servers**: never commit a
-config, a seed entry, or a path that names one.
+`.control-secrets.json` (0600: password hash, API token hash, Telegram bot token, and DDNS
+credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`), `.logs/`, `.tls/`, `.backups/`,
+`.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600 spawn spec until the nanny reads
+it, plus `ddns.json` — the last address each target confirmed), and `run.json` — the live daemon's
+pid/url/token, 0600. The package ships **no servers**: never commit a config, a seed entry, or a path
+that names one.
 
 ## Commands
 
@@ -149,7 +150,9 @@ a minor without one.
   envelope `{ message, code, detail }`. Never hand-roll `c.json({ error })`.
 - Document routes with `describeRoute` + `jsonBody(schema)`; `jsonBody` needs a real schema.
 - Patch schemas carry no defaults; nested groups (`restart`/`health`/`stop`/`auth`/`tls`/`telegram`/
-  `http`) merge key-by-key, and an explicit `null` clears a key.
+  `http`) merge key-by-key, and an explicit `null` clears a key. `ddns` is the exception: its
+  `accounts`/`domains` lists are **replaced** (a merge cannot express removing a hostname), and only
+  `ipv4`/`ipv6` merge.
 - Two-sided bounds read inclusively (`'1 <= number.integer <= 512'`). `test/shared/contracts.test.ts`
   pins every boundary and the patch/schema parity — update it with any schema change.
 - A new field in a **response** DTO is optional (`'x?'`) and its clients read it defensively. An
@@ -165,6 +168,12 @@ a minor without one.
 - A destructive action that is one click away confirms in a **popover** (`KillPortButton.vue`),
   never by arming the same button for a second press: an impatient double click on an arming
   button fires it. Keep the safe choice first in the popover's tab order.
+- **Docs ship with the change.** A user-visible change updates the docs that describe it
+  (`README.md`, `docs/*.md`) in the same commit — do not forget them; a stale doc is a bug like
+  stale code.
+- **UIs move together.** `uis/stock` is not the only client: a change to it — or to a shared
+  contract it reads — lands in every other UI under `uis/`, and each altered UI bumps its
+  `ui.json` per the rule above.
 
 ## Compatibility
 
@@ -194,6 +203,9 @@ either is a last resort, and never an accidental one.
 - **Unknown keys are dropped from the resolved config, kept on disk, and listed in a startup
   warning.** Dropping one is the normal way a newer config looks here, so it must never fail the
   group it sits in (that used to reset `control` — port, bind, auth policy — to schema defaults).
+  A *write* to a group validates the same tolerant way (`parseTolerant` via the store), so a key this
+  release does not know never blocks a save — removing a key from a schema must not brick the page
+  that writes it.
 - **Migrations ship inside the package** (`src/config/migrations.ts`), are ordered, idempotent and
   described in one line each. `home-hosted migrate` prints the plan, keeps `servers.config.json.bak`,
   refuses to write a config it cannot read, and needs consent: `--yes`, `HHOSTED_MIGRATE=allow`, or a
@@ -348,7 +360,8 @@ either is a last resort, and never an accidental one.
 - **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/store.ts` when
   nested, the form in `uis/stock/src/components/settings/`, and the contract tests.
 - **UI**: a new `uis/<name>/` with a `vite.config.ts` from the shared factory;
-  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`.
+  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`. A change to one
+  UI (`stock`, `noc-console`) is carried to the others in the same commit.
 - **Capability**: a stateless `src/providers/*` returning plain data; a DDNS provider is one file plus
   a registry line (`src/providers/ddns/index.ts`), and the settings form, credentials and validation
   follow from its metadata — see `docs/DDNS.md`.

package/README.md

@@ -375,8 +375,10 @@ Everything binds `127.0.0.1` until you say otherwise.
   never taken from the message, and anything the panel supervises is refused, not killed. A server
   that [restarts itself](./docs/SERVERS.md#when-a-program-restarts-itself) can be followed, or replaced
   with a supervised copy.
-- **Secrets never enter the config**: the password hash, the API token hash and the Telegram bot
-  token live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the TLS pair in `.tls/`.
+- **Secrets never enter the config**: the password hash, the API token hash, the Telegram bot
+  token and the DDNS credentials live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the
+  TLS pair in `.tls/`. DDNS credentials are sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`
+  (default `hh` — set your own).
 - **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https, or
   upload a PEM pair and let home-hosted terminate TLS itself.
 
@@ -403,9 +405,11 @@ tokens stay in the secrets file. **Providers and the config shape: [DDNS.md](./d
 ## 💾 Backups
 
 **Settings → Backups** archives the config, secrets, TLS pair and every data directory your entries
-declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path. Known build output
-and dependency directories (`node_modules`, `dist`, `.next`, framework caches) are skipped per entry;
-`backupIgnoreGenerated: false` captures them anyway.
+declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path. *Create backup…*
+lists what the archive will hold and lets you drop any item; *Restore…* shows the same list from an
+archive before anything is written. Known build output and dependency directories (`node_modules`,
+`dist`, `.next`, framework caches) are skipped per entry; `backupIgnoreGenerated: false` captures them
+anyway.
 
 <details>
 <summary><b>🚚 One archive is a whole setup</b></summary>
@@ -416,7 +420,9 @@ archive and restore. Definitions come back, data lands where *this* machine's co
 
 It works because an archive carries its own `servers.config.json` and paths are matched by the
 **declaration** (`omniroute:DATA_DIR`), not by an absolute path from the source machine. A restore never
-writes where no config declares.
+writes where no config declares. A declaration using `{projectDir}`, `{dataRoot}` or `{home}` follows
+the restoring panel (`{projectDir}` is `HHOSTED_PROJECT` or the panel's cwd, not `HHOSTED_HOME`); a
+literal absolute path is restored to that same path.
 
 </details>