home-hosted 0.7.2 → 0.7.3

package/docs/DDNS.md

@@ -68,9 +68,10 @@ and the guess is wrong (`home.example.co.uk` is handled; an unusual suffix may n
 | **Dynu** | A, AAAA | Username + password | `password` may be the SHA-256 hash. |
 | **Hurricane Electric** | A, AAAA | Per-host DDNS key | `dyn.dns.he.net`. |
 | **FreeDNS (afraid.org)** | A, AAAA | The per-record "Direct URL" | Paste the whole URL or just its hash. |
+| **Namecheap (API)** | — | API user + key + whitelisted IP | For **DNS-01 only**: it answers a challenge through the XML API, which rewrites the whole zone per write. It updates no addresses — use the Dynamic DNS provider above for that. The client IP must be whitelisted under Profile → Tools → Namecheap API Access, and error `1017105` means it is not. |
 
-Not supported: **Route 53** (AWS SigV4 signing, a much larger dependency), **DreamHost** (no public
-DNS API), and the Namecheap XML API (a full zone rewrite per update).
+Not supported: **Route 53** (AWS SigV4 signing, a much larger dependency) and **DreamHost** (no
+public DNS API).
 
 ## Notifications
 

package/docs/REVERSE_PROXY.md

@@ -12,8 +12,8 @@ Setup is **Others → Reverse Proxy** in the sidebar.
 
 ## Quick start
 
-1. **Install the engine** — one button, a pinned Caddy release (~46 MB) into
-   `$HHOSTED_HOME/.hh/.proxy/bin/`. The version and its SHA-256 are shown afterwards.
+1. **Install the engine** — one button, the current Caddy release (~46 MB) into
+   `$HHOSTED_HOME/.hh/.proxy/bin/`. The version the binary reports is shown afterwards.
 2. **Set the ports** — `80` and `443` by default, plus the ACME account e-mail.
 3. **Add a route** — a hostname and a target.
 4. Point the hostname's DNS at this machine (Dynamic DNS can do that) and switch the
@@ -68,6 +68,9 @@ panel did not start is ever killed.
 | `path` | Optional prefix, so one hostname can serve several apps. |
 | `tls` | `auto` (default), `off`, `manual`. |
 
+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.
@@ -93,6 +96,35 @@ The challenge is the part that catches people out: with the proxy on 4480/4443,
 to reach 4480 and 443 has to reach 4443**, or the CA never sees the challenge and the name
 never gets its certificate.
 
+A name the CA will not issue for falls back to the engine's own CA. The route reads
+**Fell back to Local CA**: the name answers, but with an untrusted certificate, and the
+engine keeps trying on its own. certmagic renews once a third of a certificate's lifetime
+is left, and the engine's own CA issues 12 hours by default, so the next attempt is about
+**8 hours** away — no restart, no downtime.
+
+**Force retry certificate** appears on that row only, and asks the CA again immediately.
+The engine is **not** restarted: a certificate the engine holds cannot be cleared by
+deleting the file or by reloading the configuration, but it *is* released when the name
+leaves the configuration — so the panel reloads without that one route, drops the stored
+pair while it is out, and puts the route back. Every other route keeps serving; the name
+itself has no certificate until the CA answers. It is not offered while a name is still
+*pending*, because there the engine is already mid-ACME.
+
+A **removed** route has its stored certificate dropped on the next apply, so adding it
+back asks the CA instead of serving the old pair. A **disabled** route keeps its
+certificate: it is still configured, and switching it back on should not cost a new
+issuance.
+
+The wait can be shortened by giving the engine's own issuer a shorter `lifetime` in the
+generated policy; the row reads the interval from the certificate, so the confirmation
+follows whatever is configured.
+
+A hostname **no route claims** gets a page saying so, on both ports — not a redirect into
+a handshake that cannot finish. A visitor with no hostname at all (a bare IP on the HTTPS
+port) is answered by the engine's own CA under `hh-fallback.invalid`, so the page appears
+after the browser's warning. A hostname that is neither routed nor covered by a
+certificate still fails its handshake: there is nothing to present a certificate for.
+
 **A name with no certificate yet is still reachable.** The engine's own CA is the last
 issuer in the policy, so the handshake completes with an untrusted certificate — the
 browser offers to continue instead of failing with `ERR_SSL_PROTOCOL_ERROR` — and over
@@ -120,17 +152,63 @@ Certificates are managed by the engine, inside `.hh/.proxy/engine/`, and nothing
 the machine is touched: the generated configuration pins its storage root, and the
 panel passes the engine no `$HOME` of its own to write into.
 
-**Not yet: DNS-01.** Wildcard certificates, and issuing with no inbound port at all,
-need a Caddy build with the registrar's plugin compiled in — every registrar is a
-separate Go module, and the stock binary ships none. The engine download path already
-takes a plugin list, so this is the next step, not a redesign.
+**DNS-01** is the way round a router that will not forward 80 and 443. A route is one
+hostname, so there is no wildcard to issue; what DNS-01 buys is a certificate with
+**no inbound port at all** — behind CGNAT, or on a host only reachable over VPN.
+Turn it on in the page and point each route at a DNS account:
+
+```json
+{
+  "proxy": {
+    "dns01": { "enabled": true, "resolvers": [] },
+    "routes": [
+      { "id": "gitea", "host": "git.example.com", "target": "server", "workspace": "default", "server": "gitea", "dnsAccount": "default/cf" }
+    ]
+  }
+}
+```
+
+The account is the one from **Workspace Settings → Dynamic DNS** — same credentials,
+same workspace, same notification routing. It does not need the hostname in its
+hostname list: the account names the zone, the route names the subject. A route may
+name a different account from its neighbour, so names in two zones at two registrars
+each get the right one; the panel gives each account a policy of its own.
+
+Leave a route on **Automatic** and it uses the only account that can answer a
+challenge. With more than one account, Automatic cannot choose: pick one per route, or
+those names keep using the port challenges. A local-only name (`.lan`, an IP) is never
+challenged — it is signed by the engine's own CA.
+
+The account is checked when you save, not when the certificate is due: unknown, an
+account whose provider cannot write a `TXT` record (the router-style Dynamic DNS
+password providers), or one with no credentials stored yet is refused there.
+
+Which accounts can answer: any whose provider writes a `TXT` record. Today that is
+Cloudflare and **Namecheap (API)** — the latter is a separate provider from Namecheap's
+Dynamic DNS entry, because its credentials differ (API user, key and a whitelisted
+client IP) and it rewrites the whole zone per write. Namecheap's Dynamic DNS password
+cannot write a TXT record at all, so that account is refused with the reason.
+
+The engine holds no DNS credentials. It asks the panel over the ACMEProxy protocol on
+loopback, with credentials the panel generated for it, and the panel writes the
+`_acme-challenge` record through that account. `resolvers` overrides the nameservers
+the engine checks the record against, which is what split-horizon DNS needs.
+
+Setting it up needs no inbound port, but the record has to be **published** before the
+CA looks: the panel writes it, the CA reads it, and the panel removes it again. A
+provider that can only write a whole record set — Namecheap's XML API is the one —
+is read-modify-write, so the panel rewrites records it did not create, and refuses
+rather than adding a 151st record to a zone already at the limit.
 
 ## The engine
 
 | | |
 | --- | --- |
-| Comes from | Caddy's own build service (`caddyserver.com/api/download`), at a version the panel pins — never "latest" by accident. |
-| Installed at | `.hh/.proxy/bin/hh-caddy` + `engine.json` (version, URL, SHA-256, size). |
+| Comes from | Caddy's own build service (`caddyserver.com/api/download`), at **its current release** — the panel pins no version, so **Update engine** is how a security fix reaches you. |
+| Verified against | **Caddy 2.11.6.** That is the release this build was tested with; a newer one is installed anyway, and the panel reports the version that actually arrived. A release that changes the JSON schema may need a panel update first. |
+| Carries | The `acmeproxy` DNS provider, compiled in for every install so the binary does not depend on a setting. `DNS-01` is offered because of it; an engine installed by an older release is refused with *update the engine* rather than failing inside Caddy. |
+| Installed at | `.hh/.proxy/bin/hh-caddy` + `engine.json` (version, URL, size, when). |
+| Replaceable | Drop any `hh-caddy` build at that path and the panel runs it: it reports *a path configured by hand* and probes no version. Installing or updating is refused while the engine is up — **Stop** it first, because the binary is replaced on disk. |
 | Runs as | A child of the panel's own nanny, exactly like a `persistent: true` entry. |
 | Supervised by | The panel. The admin API is opened on the panel side only: a unix socket in a `0700` directory (loopback TCP plus Caddy's origin check on Windows). |
 | Reloaded by | `POST /load` — atomic, and the revision that applied is kept on disk so a change can be reverted in one click (the first one has nothing to go back to). A reload onto a port something else holds is refused with that pid before the engine is touched, and the panel keeps reporting the ports the engine is really on. |
@@ -145,9 +223,11 @@ internet: the engine keeps serving, and the panel reattaches to it on the next b
 | --- | --- |
 | `GET /api/proxy` | Policy, engine, live state and every route with its resolved upstream. |
 | `PATCH /api/proxy` | Change the settings or replace the route list, then apply. |
-| `POST /api/proxy/engine` | Install or update the engine (`{ "version": "" }` = the pinned one). |
+| `POST /api/proxy/engine` | Install or update the engine (`{ "version": "" }` = the current release). |
 | `PUT` \| `DELETE /api/proxy/certificates/:id` | Store or remove one uploaded pair (`{ label, certificate, privateKey }`). |
 | `POST /api/proxy/start` \| `stop` \| `apply` \| `revert` | Engine lifecycle and configuration. |
+| `POST /api/proxy/routes/:id/retry-certificate` | Ask the CA again for one route, without restarting the engine. |
+| `POST /_acme/present` \| `cleanup` | The engine's DNS-01 channel: loopback only, and behind credentials the panel generated. Not part of `/api`, so it needs no session. |
 
 
 ## Files
@@ -155,7 +235,8 @@ internet: the engine keeps serving, and the panel reattaches to it on the next b
 | Path | What |
 | --- | --- |
 | `.hh/.proxy/bin/` | The engine binary and the record of what was installed. |
-| `.hh/.proxy/engine/current.json` | The generated configuration; `previous.json` is the revision before it. |
+| `.hh/.proxy/engine/current.json` | The generated configuration; `previous.json` is the revision before it. Both are `0600`: with DNS-01 on they carry the challenge credentials the engine authenticates with. |
 | `.hh/.proxy/state/` | The nanny's spec and state, and `admin.json` (how to reach a running engine). |
+| `.hh/.proxy/state/challenge.json` | The credentials the engine presents to `/_acme`, `0600`; written only when DNS-01 is on. |
 | `.hh/.proxy/tls/<id>.crt.pem` \| `<id>.key.pem` | One uploaded pair per entry (the key is `0600`). |
 | `.hh/.logs/proxy.log` | The engine's own JSON output, as the nanny captures it. |

package/docs/UI_CREATION.md

@@ -90,6 +90,21 @@ must never lock you out of your own machine.
    drive letters.
 7. **Offline and plain-http friendly.** Assume a LAN over `http://`: no `Secure`-only cookies, no
    hard-coded port, no https-only APIs.
+8. **Give each page its own path.** An SPA with canonical URLs is the best default: a path is what
+   makes a page bookmarkable, shareable, and reachable with back/forward — and matching the stock
+   paths keeps two UIs of the same panel feeling alike. Those are:
+
+   | page | path |
+   | --- | --- |
+   | workspace: overview · servers · logs · settings | `/w/<workspace>` · `/w/<workspace>/servers` · `/w/<workspace>/logs` · `/w/<workspace>/settings` |
+   | one server | `/w/<workspace>/servers/<id>` |
+   | panel-wide: overview · settings | `/global/overview` · `/global/settings` |
+   | reverse proxy | `/proxy` |
+
+   Keep the workspace id in the URL (a link then opens the same workspace in a browser that never
+   selected it), and rewrite bare or unknown paths onto the canonical one (`/` → Global Overview) so an
+   old bookmark still lands somewhere sensible. **Not a hard rule** — a different direction may route
+   however it fits; just keep deep links working.
 
 ## The API
 
@@ -247,7 +262,7 @@ with an installed panel on the default 3999; override with `--port`/`--ui-port`
 - [ ] only `/api/...` calls, no absolute origins, no hard-coded port
 - [ ] `401 { code: 'AUTH_REQUIRED' }` handled with a login screen
 - [ ] live data from SSE — a panel that only polls feels broken
-- [ ] deep links render (the server falls back to `index.html`)
+- [ ] deep links render (the server falls back to `index.html`) and each page has its own path
 - [ ] assets self-hosted, no CDN
 - [ ] works over plain http on a LAN
 - [ ] `ui.json` with a name and version, so Global settings can tell you what is installed — plus `repo`/`tag`/`asset` if you want `ui-update` to follow your releases

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "home-hosted",
   "type": "module",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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>",
@@ -133,7 +133,7 @@
     "vue-tsc": "^3.3.11"
   },
   "simple-git-hooks": {
-    "pre-commit": "pnpm lint-staged"
+    "pre-commit": "pnpm lint-staged && node scripts/stamp-uis.mjs"
   },
   "lint-staged": {
     "*": "eslint --fix"