home-hosted 0.7.16 → 0.7.18

package/docs/DDNS.md

@@ -30,7 +30,9 @@ credentials button saves on its own, being a secret. Provider credentials never
 
 Credentials live in the workspace's `.secrets.json` (0600), keyed by the account `id` and sealed with
 AES-256-GCM under `HHOSTED_DDNS_SECRET` — set your own, or the default `hh` only stops a casual
-read. The block above is the workspace's `.hh/<workspace>/settings.json`; the credentials are cached
+read. The panel logs a warning when it seals credentials under that default, so a copied state
+directory is not the first time you hear about it. The block above is the workspace's
+`.hh/<workspace>/settings.json`; the credentials are cached
 separately in `.secrets.json`, both beside that workspace's `servers.config.json`. The account does
 not have to be saved first, and the provider is stored with the entry, so an id that later changes
 provider does not silently keep the old secret. Removing an account drops its credentials on the next
@@ -49,7 +51,9 @@ Header fields:
 | `domains[]` | — | `host`, `account`, `types` (`A`/`AAAA`, default `A`), `proxied` (default off; Cloudflare only), optional `ttl`, `zone`, `enabled`. |
 
 Per-hostname `zone` pins the registered domain — only needed where a provider has to be told the apex
-and the guess is wrong (`home.example.co.uk` is handled; an unusual suffix may not be).
+and the guess is wrong (`home.example.co.uk` is handled; an unusual suffix may not be). It must be a
+domain the host is **inside**: a typo is refused on save, because the record name would otherwise become
+the whole hostname and the write would go to a domain that is not yours.
 
 ## Providers
 

package/docs/REVERSE_PROXY.md

@@ -67,13 +67,18 @@ panel did not start is ever killed.
 | `url` | For `target: "external"`, e.g. `http://10.0.0.5:8080`. The port is optional: without one the scheme's own default is used (`:80` for `http:`, `:443` for `https:`). An `https://` upstream is dialled with TLS, and **its certificate is not verified** — a homelab upstream behind a self-signed certificate works, and so does an impostor. |
 | `path` | Optional prefix, so one hostname can serve several apps. |
 | `tls` | `auto` (default), `off`, `manual`. |
+| `dnsAccount` | Optional `workspace/account` for a DNS-01 challenge, referencing a DNS account from Settings. Empty picks the workspace's only account that can write TXT records, so a single-account setup needs nothing here. |
 
 The list's hostname is a link to where the route answers — `https://host:<https port>`, or
 the plain port for `tls: "off"`, path included. A route that is switched off is plain text.
 
 A route pointing at the panel is exposure, and answers to the same rule as binding the
 listener beyond loopback: authentication on and a non-default password, or the save is
-refused.
+refused. `tls` does not change that bar — it is about who can reach the panel, not whether
+the hop is encrypted, and `tls: "off"` is if anything the worse case. The engine upstreams a
+panel route to `127.0.0.1`, which the panel's own guard reads as a local request, so a
+plain-HTTP route with no password set would serve the panel to anyone who reached that
+hostname.
 
 ## HTTPS
 
@@ -143,9 +148,11 @@ route still serves it — so the two can never disagree.
 
 Certificates are read, never edited: the panel reports each pair's subject, issuer,
 expiry and the hostnames it covers (from its SANs, wildcards included), and marks a pair
-no route would be served from. An expired pair is never served — the route that asks for
-it is refused with the reason. An uploaded pair is re-read as soon as its file changes,
-so editing or replacing one outside the panel is picked up on the next look; the engine's
+no route would be served from. A pair outside its validity window — expired, or not valid
+yet — is never served, and the route that asks for it is refused with the reason; a pair
+whose key does not match its certificate is refused the same way. An uploaded pair is
+re-read as soon as its file changes, so editing or replacing one outside the panel is
+picked up on the next look; the engine's
 own certificate store (the issued certificates) is read at most every 15 seconds.
 
 Certificates are managed by the engine, inside `.hh/.proxy/engine/`, and nothing else on

package/docs/SERVERS.md

@@ -31,14 +31,16 @@ servers and its state together.
 | --- | --- |
 | `command`, `args`, `cwd` | what to run, with `{placeholders}` resolved per entry |
 | `env`, `dataEnvs`, `envFile` | environment; `dataEnvs` also marks data directories for backups, `envFile` keeps secrets out of the config |
+| `enabled` | `true` (default) starts it; `false` keeps the entry in the config but refuses to start it, stops it if it is running, and leaves a disabled `persistent` entry unattached at boot |
 | `port`, `bind` | enables the readiness wait, health checks and the conflict preflight; `local` keeps it on `127.0.0.1` |
 | `onPortConflict` | `block` (default), `warn`, `follow`, `reclaim`, or `kill` — see below |
 | `persistent` | run it under its own nanny so it survives the panel — see below |
-| `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body) |
+| `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body — a `HEAD` carries no body, so it is warned about and the body check is skipped) |
 | `health.unhealthyThreshold`, `forceRestartAfterMs` | how many failed probes before the card warns, and when to restart anyway |
 | `restart.*` | backoff: `maxRetries`, `baseDelayMs`, `factor`, `maxDelayMs`, `resetAfterMs` |
 | `stop.*` | `signal`, `killGroup`, `graceMs`, and `killPortHolders` to sweep a leftover listener |
-| `dependsOn` | ids that must be healthy first; stopped in reverse order |
+| `dependsOn` | ids that must be healthy first. `stop-all`/`down` stop dependents before their dependencies; stopping **one** server does not cascade — the log names any dependent it left running |
+| `logBufferLines` | how many lines of live output the panel keeps in memory per entry (50–100000, default 500). The file on disk is separate: this is the buffer the Logs page streams from |
 | `resources.maxRssBytes` | restart when the process tree grows past a limit |
 | `bootstrap` | one command to run once before the first start (migrations, warmups) |
 | `backupPaths`, `backupIgnoreGenerated` | extra paths this entry owns, included in backups; the flag (on by default) skips the known build and dependency directories inside them — `node_modules`, `dist`, `.next`, framework caches |
@@ -167,7 +169,10 @@ What that changes:
   workspace's `.logs/`, because there is no pipe to carry the output.
 - **A crash while the panel is away is reported, not restarted.** Retries and backoff remain the
   panel's job, so an entry that dies with nobody watching shows up as **crashed** on the next boot
-  with the exit code in its log.
+  with the reason in its log — the exit code, explained when it has a conventional meaning
+  (`code 137 (SIGKILL — which the kernel sends when memory runs out)`), because that is the one an
+  operator would otherwise have to look up. `home-hosted status` prints the directory those files
+  live in, and names the `<id>.log` convention once there is one to read.
 - **Port policies still apply, as a fallback.** A persistent entry reattaches from its state file
   before any preflight runs, so `onPortConflict` matters only when that state is gone — and `follow`
   is then the policy that adopts instead of blocking.

package/docs/UI_CREATION.md

@@ -133,6 +133,7 @@ naming one that does not exist is a `404 UNKNOWN_WORKSPACE`, never a silent fall
 | `GET /api/servers/:id/stream` | one server's `server` + `log` frames |
 | `POST /api/servers/:id/{start,stop,restart}`, `/api/servers/{start-all,stop-all}` | lifecycle (workspace-scoped) |
 | `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop (`409` when nothing can be freed — a supervised listener is refused, never killed) |
+| `POST /api/servers/:id/clear-logs` | forget the buffered lines; the file on disk is cleared separately through `DELETE /api/logs/:id` |
 | `GET` / `POST /api/servers`, `PATCH` / `DELETE /api/servers/:id` | the entries themselves, in one workspace |
 | `GET /api/logs`, `/api/logs/:id?tail=&search=`, `/api/logs/:id/download?file=` | persisted logs, for one workspace |
 | `GET` / `PATCH /api/settings` | the panel-wide settings (`control.label`, host thresholds, backups, UI) |
@@ -141,7 +142,9 @@ naming one that does not exist is a `404 UNKNOWN_WORKSPACE`, never a silent fall
 | `POST` / `DELETE /api/settings/tls` | upload or clear a PEM pair |
 | `GET` / `PATCH /api/proxy`, `POST /api/proxy/{engine,start,stop,apply,revert}`, `PUT` / `DELETE /api/proxy/certificates/:id`, `POST /api/proxy/routes/:id/retry-certificate` | the panel-wide reverse proxy: engine, route table, its uploaded PEM pairs. Its live view also rides in the state frame as an optional `proxy` — read it defensively |
 | `GET` / `POST /api/backups`, `/api/backups/restore`, `/api/backups/:name/download` | archives; entries are global (`global:settings`, `global:secrets`, `global:tls`) or per workspace, whose leaves are `workspace:<id>:settings`, `:servers`, `:secrets` plus `data:<path>`; a create/restore body `include` selects them |
+| `POST` / `DELETE /api/auth/password` | set the panel password, or clear it and disable auth. `POST` needs the current one unless none is set; an empty password is refused |
 | `POST` / `DELETE /api/notifications/token`, `/api/notifications/test`, `/detect-chats` | Telegram, per workspace |
+| `GET` / `PUT /api/ddns`, `PUT` / `DELETE /api/ddns/credentials/:id`, `POST /api/ddns/check` | dynamic DNS, per workspace: the policy plus live per-record state, one account's sealed credentials (write-only — the view exposes ids and whether each is set, never the values), and a pass run now |
 | `POST /api/auth/login`, `GET /api/auth/session`, `POST /api/auth/logout` | the session |
 | `GET /healthz` | liveness — **no session**, and `503` when an autostart server has crashed |
 | `GET /api/metrics` | Prometheus text (needs a session) |
@@ -185,10 +188,14 @@ session, 403 bad token or origin, 404 unknown id, 409 conflict, 413 too large.
 | --- | --- |
 | `hello` | `{ ts, state }` — the first frame, the complete snapshot |
 | `state` | `{ ts, state }` — anything changed: a status, a resource sample, host vitals, a workspace |
-| `server` | `{ ts, serverId, server }` — one entry, `server.workspaceId` says which workspace |
-| `log` | `{ ts, serverId, lines }` — new output (dropped under backpressure, never state) |
+| `server` | `{ ts, workspaceId, serverId, server }` — one entry |
+| `log` | `{ ts, workspaceId, serverId, lines }` — new output (dropped under backpressure, never state) |
 | `ping` | the current time, every 15 s |
 
+`workspaceId` is on every `server` and `log` frame the panel sends, and the schema marks it optional only
+so an **older** panel still parses: treat a frame without it as ambiguous and look the id up rather than
+guessing, because a server id is unique only inside its workspace.
+
 `GET /api/events` takes `?logs=0` to skip log frames and `?serverId=<id>` to follow one server — but
 it matches on the id alone, so an id used in two workspaces mixes their frames. Use
 `GET /api/servers/:id/stream?workspace=<id>` for one server: it validates the pair and replays the
@@ -233,8 +240,10 @@ pnpm run build:uis                        # every UI, zipped; releases attach th
 
 Only `stock` ships inside the npm package; the rest are release assets you install from Global
 settings.
-`pnpm run quickcheck` type-checks every UI, and `pnpm test` picks up any `test/*.test.ts` you add
-(use relative imports — the `@` alias points at `stock`).
+`pnpm run quickcheck` type-checks every UI, and `pnpm test` picks up any `test/*.test.ts` you add.
+`@/…` resolves from the UI that asks — each UI's own `src`, so a test can import its own components
+and logic directly; use `@shared/…` for what the panel and the UIs genuinely share
+(`src/shared/`), and never import runtime server code (`@server` is types only).
 
 ## A worked example
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "home-hosted",
   "type": "module",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "packageManager": "pnpm@12.5.1",
   "description": "Self-hosted control panel that keeps your home-server processes alive: supervision, restarts, port conflicts, logs — and a UI you can replace.",
   "author": "NamesMT <dangquoctrung123@gmail.com>",
@@ -80,9 +80,10 @@
     "set-token": "tsx src/cli.ts set-token",
     "migrate": "tsx src/cli.ts migrate",
     "lint": "eslint .",
+    "test:docs": "node scripts/check-doc-links.mjs",
     "test": "vitest",
     "test:types": "tsc --noEmit && node scripts/typecheck-uis.mjs",
-    "quickcheck": "pnpm run lint && pnpm run test:types",
+    "quickcheck": "pnpm run lint && pnpm run test:types && pnpm run test:docs",
     "check": "pnpm run quickcheck && vitest run --coverage",
     "prepare": "simple-git-hooks",
     "prepack": "pnpm run build",