blockyard 0.0.9 → 0.1.1

package/docs/SECURITY.md

@@ -5,7 +5,7 @@ page describes the access model, what protects it, and exactly what leaves your
 To report a vulnerability, see [SECURITY.md](../SECURITY.md) at the repository root.
 
 - [Threat model in one paragraph](#threat-model-in-one-paragraph)
-- [Access: open by default, accounts on request](#access-open-by-default-accounts-on-request)
+- [Access: sign-in by default, open on request](#access-sign-in-by-default-open-on-request)
 - [Accounts, sessions and passwords](#accounts-sessions-and-passwords)
 - [Talking to the node](#talking-to-the-node)
 - [Node writes](#node-writes)
@@ -23,13 +23,23 @@ someone using the monitor to make the node do something (prevented: writes are o
 console is read-only behind a default-deny allowlist), someone reading your node's state who
 should not (controlled by where it listens, a CIDR gate, and optional accounts), and the
 monitor leaking information about you to third parties (limited to the on-demand market data
-connections listed below, which you can turn off). The monitor does not hold keys and has no
-wallet access.
+connections listed below, which you can turn off). The monitor does not hold keys, and every
+wallet RPC is refused by name (since 2026-09-16; before that, wallet reads such as
+`listdescriptors` passed the allowlist's `list` prefix, see the audit of that date).
 
-## Access: open by default, accounts on request
+## Access: sign-in by default, open on request
 
-With the default `auth.enabled: false`, anyone who can reach the port reads the monitor
-with the fixed role `viewer`:
+**Out of the box the monitor listens on `127.0.0.1` only and requires sign-in.** The first
+start creates an `admin` account and prints its password once (or takes it from
+`BLOCKYARD_ADMIN_PASSWORD`). Reach it from another machine over an SSH tunnel
+(`ssh -L 21000:127.0.0.1:21000 you@host`), or bind a LAN address with `BLOCKYARD_BIND` /
+`server.hosts` once you have decided who may see it. These are the defaults since
+2026-09-15; 0.0.9 shipped bound to every interface with no sign-in, which the first outside
+review rightly called out.
+
+Open access is still available as a posture you choose: with `auth.enabled: false`
+(`BLOCKYARD_AUTH=0`), anyone who can reach the port reads the monitor with the fixed role
+`viewer`:
 
 | open to anyone who can reach the port | still closed |
 |---|---|
@@ -37,12 +47,13 @@ with the fixed role `viewer`:
 | peer, mempool, block and transaction detail, the explorer | the audit trail |
 | the read-only RPC console (behind the allowlist) | password changes and sessions |
 | the live Server-Sent Events stream | **every node write**, even if actions are enabled |
+| Display settings (they are normalised before use) | the node connection form, except from this machine's loopback address (`auth.openNodeConfigFromNetwork` widens it) |
 
 The `viewer` ceiling cannot be raised by configuration or by any credential while accounts
 are off. The start-up log states which addresses are readable and how to close them, so
 "anyone on the LAN can read your node" is never a surprise.
 
-Set `BLOCKYARD_AUTH=1` (or `"auth": { "enabled": true }`) to require sign-in. Roles:
+With sign-in on (the default; `BLOCKYARD_AUTH=1` restores it after an override), roles:
 
 | role | may |
 |---|---|
@@ -69,19 +80,30 @@ The last enabled admin cannot be demoted, disabled or deleted.
   routes had no cross-site protection at all. An audit proved it with a working exploit against
   the node-connection test. Open mode now refuses any state-changing request whose `Origin` is
   not this server, or whose `Sec-Fetch-Site` says cross-site. A client that sends neither header
-  (curl, a script) is unaffected: it can already reach the port, and this guards against what a
-  *browser* can be made to do on someone's behalf.
+  (curl, a script) is not stopped by that check, which only guards against what a *browser* can be
+  made to do. So the one form where a script could do real harm, the node connection (a saved
+  address decides where the node's cookie goes after a restart, and its test makes the server
+  connect somewhere), answers only a loopback caller while accounts are off (audit 2026-09-16).
+  A save that moves the node to a different host drops the old endpoint's `rpcUser`,
+  `rpcPassword` and `cookieFile`, and a test of a foreign endpoint reports the kind of failure,
+  never what the endpoint answered.
 - **Brute force**: sign-in is locked after 8 failures in 5 minutes per username and per
   address, for 10 minutes, with the same error and the same hashing time for unknown users
   and wrong passwords. A separate throttle limits sign-in attempts per address, because each
   attempt costs a deliberately expensive hash.
 - **Rate limits** apply per client address.
+- **Slow and stalled clients** cannot hold memory or connections: a request, body included, must
+  arrive within 30 seconds; an event stream whose reader stops reading is sent nothing more until
+  it drains, and is dropped when 4 MB is buffered or it stays blocked for a minute; one address
+  (or account) holds at most 16 streams. Free-form audit fields are clamped to 1,024 characters,
+  so a caller cannot rotate real events out of the trail.
 
 ## Talking to the node
 
 - **Read-only allowlist, default deny.** The RPC console and every internal call go through
-  an allowlist: read-shaped methods are allowed; wallet, key-material, spending, peer-control,
-  chain-mutating and very heavy methods are refused by name — including `getnewaddress` and
+  an allowlist: read-shaped methods are allowed; every wallet method (reads included, since some
+  return private keys), spending, peer-control, chain-mutating and very heavy methods are refused
+  by name — including `getnewaddress` and
   `getrawchangeaddress`, which start with "get" but create keys. Unknown methods are refused.
 - **One request at a time.** The node's RPC server is single-threaded, so the monitor runs a
   single serialized request lane with a minimum spacing, batching, priorities and a stale-drop
@@ -124,9 +146,15 @@ Every call and every refusal is appended to the audit trail.
 
 ## Transport security
 
-- HTTPS is built in: name a certificate and key and **every** listener serves HTTPS. A
-  half-configured pair or an expired certificate stops the start-up; a certificate close to
-  expiry starts with a warning, and the log prints its fingerprint.
+- HTTPS is the default on **every** listener. With no certificate named, the server makes its
+  own self-signed one on first start (`server/tls/selfsigned.js`, under `<data>/tls/`, the key
+  mode 600, ECDSA P-256), naming the addresses it is reached on, and remakes it when it nears
+  expiry or stops naming a bound address; the log prints its fingerprint. A certificate of your
+  own replaces it (`BLOCKYARD_TLS_CERT`/`_KEY`); a half-configured pair or an expired
+  certificate stops the start-up. `BLOCKYARD_TLS=0` is plain HTTP, for a proxy in front.
+- A self-signed certificate proves nothing about who you are talking to the first time; it
+  does encrypt the session and pins the fingerprint after that. Compare the fingerprint the
+  log prints with the one the browser shows before trusting it on a network you do not own.
 - Over HTTPS the session cookie is `Secure` and `Strict-Transport-Security` is sent with a
   two-day lifetime, without `includeSubDomains` or `preload` — a LAN address can be reissued,
   and HSTS cannot be withdrawn once a browser has it.
@@ -150,13 +178,15 @@ Everything in the monitor talks only to your node, **except**:
 
 | when | to | what is sent |
 |---|---|---|
-| while someone has the **Markets**, **Kiosk** or **Overview** tab open — Overview's price line is **on by default**, so the landing page reaches out unless you switch it off — and for 10 minutes after the last request | `api.exchange.coinbase.com`, `api.kraken.com`, `www.bitstamp.net`, `api-pub.bitfinex.com`, `www.okx.com` (HTTPS) | public ticker, hourly candle and order-book requests with a `User-Agent` naming the software — nothing about your node |
-| when someone opens an **explorer** page and no fresh market price is at hand | two of the exchanges above, at most once a minute | a public ticker request |
+| only with **Enable market polling** ticked in Display settings (**off by default**), while someone has the **Markets**, **Kiosk** or **Overview** tab open — Overview's price line reads the same feed unless you switch it off — and for 10 minutes after the last request | `api.exchange.coinbase.com`, `api.kraken.com`, `www.bitstamp.net`, `api-pub.bitfinex.com`, `www.okx.com` (HTTPS) | public ticker, hourly candle and order-book requests with a `User-Agent` naming the software — nothing about your node |
+| with polling on, when someone opens an **explorer** page or the **Mining** tab and no fresh market price is at hand | two of the exchanges above, at most once a minute | a public ticker request |
 
-Nothing is fetched when nobody is looking. Your machine's public address is visible to those
-exchanges when a request is made, as with any web request. To make **no** outbound connections
-at all, set `BLOCKYARD_MARKETS=0` (or `"markets": { "enabled": false }`): the Markets and Kiosk
-tabs then say that market data is off, and the explorer shows no dollar figures.
+**Out of the box none of this happens**: polling is off until someone ticks **Display settings → Markets & Price → Enable market polling**, and until then the
+Markets and Kiosk tabs say so and the explorer shows no dollar figures. The switch is a Display
+setting shared by every screen, so anyone who can change settings on this monitor can turn it
+on; `BLOCKYARD_MARKETS=0` (or `"markets": { "enabled": false }`) removes the feed from the
+server so that no checkbox can. With polling on, nothing is fetched when nobody is looking. Your machine's public address is visible to those exchanges
+when a request is made, as with any web request.
 
 The monitor sends no telemetry, checks for no updates, and phones home to no one.
 
@@ -185,11 +215,17 @@ and errors; they never contain passwords, session tokens or RPC credentials.
 ## Hardening checklist
 
 - Run as a dedicated, unprivileged account that can read only the node's cookie and its
-  `blocks/` directory (and log), and write only its own `data/` and the index directory.
+  `blocks/` directory (and log), and write only its own `data/` and the index directory. The
+  shipped systemd unit enforces the write half (`ProtectSystem=strict` with `ReadWritePaths=` for
+  `data/`, `config/` and the index) and drops capabilities, system calls and address families the
+  monitor does not use; add your index directory to it.
+- Point `addressIndex` (or `--out`) at a new or empty directory. The build refuses a symlink, the
+  filesystem root, a home or working directory, the node's blocks directory, and any directory
+  holding files an index does not write; it only ever removes its own files.
 - Bind the narrowest set of addresses that serves your users; add a firewall rule if needed.
 - Turn accounts on if anyone who can reach the port should not see your node.
 - Use HTTPS, a reverse proxy, or an SSH tunnel on untrusted networks.
 - Leave node actions off unless you have a specific need, and then enable only that action.
-- Set `BLOCKYARD_MARKETS=0` on machines that must not make outbound connections.
+- Set `BLOCKYARD_MARKETS=0` on machines that must not make outbound connections: the polling checkbox (off by default) then cannot turn the feed on.
 - Keep `config/local.json` and `data/` readable only by the service account.
 - Keep Node.js current within the 22.x line or later.

package/docs/TROUBLESHOOTING.md

@@ -54,6 +54,10 @@ The Node & RPC page shows the last error. Common causes:
 
 ## The page does not load from another machine
 
+0. Out of the box the monitor binds `127.0.0.1` and answers this machine only. Either reach
+   it over an SSH tunnel (`ssh -L 21000:127.0.0.1:21000 you@host`, then `https://localhost:21000`)
+   or bind a LAN address: `BLOCKYARD_BIND=192.0.2.10` (or `0.0.0.0`), or `server.hosts` in
+   `config/local.json`, and restart.
 1. From the other machine, check how it reaches the server: `ip route get <address>`.
 2. Make sure that address is one the monitor binds — see the start-up log. A LAN-only bind is
    not reachable over a VPN unless the VPN address is also listed in `server.host`.
@@ -159,21 +163,50 @@ so far and an ETA; the address page repeats it. Things it says, and what they me
   [INSTALL](INSTALL.md#bitcoinconf-settings-worth-having), or let it run overnight.
 - **The ETA is wrong at first** — it is computed from the files done so far in the current phase
   and settles after the first few; files are not all the same size.
+- **It stopped one short — "scan 5,720 of 5,721, about 1 s left" for an hour** — a worker
+  died, most likely killed for memory (four workers is about 10 GB beside the node). Since
+  2026-09-15 that fails the build at once with `an index worker exited with code N while on
+  {"type":"scan","file":...}` and the flag turns to *build failed*; before that fix the build
+  hung there for good. Either way: restart BlockYard with fewer workers (`addressIndexWorkers` on
+  the node entry in `config/local.json`). The build resumes with the files it had finished. The flag
+  also says **no progress for N min** whenever nothing has moved for two minutes, so a stall is
+  visible as one rather than as a stale ETA.
 - **Hours, not minutes** — expect **a few hours**: 29 min 45 s is 16 workers on NVMe, and four
   workers (the installer's default) are roughly four times slower; **spinning disks** are slower still whatever the
   number, and there one worker is the fast setting, because parallel readers only seek against
   each other and against the node. Set `addressIndexWorkers` on the node entry in
-  `config/local.json` (the installer writes the number you gave it) and restart: there is no
-  resume, so the build starts over from the first file.
-- **It started over** — stopping BlockYard stops the build, and the next start begins it again
-  from scratch. Leave it running until the notification says it is done.
+  `config/local.json` (the installer writes the number you gave it) and restart: the build resumes with the files already scanned, and only the rest are read with the
+  new number of workers.
+- **It started over** — a stopped build normally resumes: the log says `address index build:
+  resuming the interrupted build in <dir> at block N` with how much was already done. When it
+  says `discarding the interrupted build … and starting over` instead, the reason follows: the
+  node's chain reorganised below the block the build was working to, the node is behind it (a
+  reindex, or another node), the index format changed with an update, or the journal or a bucket
+  file was damaged. Unfinished work that cannot be proven whole is never used, so the build begins
+  again from the first file.
 - **the address index build failed** — the reason is in the events feed and the log; fix it and
   restart (the server builds again), or run `node scripts/index-build.js --out <dir>` by hand.
   A pruned node, unreadable block files and a full disk are the usual causes.
 
+## "getrawmempool verbose dropped as stale" in Events, and the mempool panels look old
+
+The monitor keeps one RPC request in flight and serves the live polls first; the full-pool poll is
+the lowest priority, so when the node's RPC is slow it waits behind them and, past its freshness
+budget, is dropped rather than shown as current. A streak of drops is one warning event when it
+starts, a counter on **Node & RPC → data quality** while it lasts, and one event when the poll
+answers again with the count and the span. The Mempool, Block space and Mining panels show their
+last reading meanwhile and say how old it is.
+
+The cause is the node, not the monitor: look for what else is asking it. On 2026-09-15 an Umbrel
+node answered in seconds for thirteen hours while another BlockYard built its address index
+against it over the LAN, and the drops stopped the moment that build finished. A remote index
+build, a wallet rescan, `gettxoutsetinfo` from another tool, or an initial block download all
+show the same way.
+
 ## Markets or Kiosk show no prices
 
-- **"market data is off"** — `BLOCKYARD_MARKETS=0` or `markets.enabled: false` is set.
+- **"market polling is off"** — the default. Tick **Display settings → Markets & Price → Enable market polling**.
+- **"market data is off on this server"** — `BLOCKYARD_MARKETS=0` or `markets.enabled: false` is set on the server; the checkbox cannot override it.
 - **"asking the exchanges…" for a long time** — the server cannot reach the exchanges. Test
   from the server: `curl -sI https://api.exchange.coinbase.com/products/BTC-USD/ticker`. Check
   outbound firewall rules and DNS.
@@ -289,6 +322,12 @@ browser in kiosk mode pointed at `http://<host>:21000/#kiosk`.
 - **"too many attempts"** — the lockout lasts 10 minutes per username and per address.
 - **Sign-in does not stick** — over plain HTTP, make sure `BLOCKYARD_SECURE_COOKIE` is not set
   (a `Secure` cookie is never sent over HTTP). Behind a TLS proxy, set it.
+- **The browser warns about the certificate** — expected once per address: the monitor's own
+  certificate is self-signed. Compare the fingerprint in the start-up log with the browser's,
+  then accept it. To be rid of the warning, name a certificate of your own (INSTALL §9) or put
+  a proxy with a real one in front (§10).
+- **`https://` says the connection was reset, or `http://` shows nothing** — the port speaks
+  one or the other: HTTPS unless `BLOCKYARD_TLS=0`. Use the scheme the start-up log prints.
 
 ## Tests fail on a fresh clone