blockyard 0.0.1 → 0.0.9

package/docs/SECURITY.md

@@ -0,0 +1,195 @@
+# Security and privacy
+
+BlockYard watches a Bitcoin node and shows what it sees to the people you let in. This
+page describes the access model, what protects it, and exactly what leaves your machine.
+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)
+- [Accounts, sessions and passwords](#accounts-sessions-and-passwords)
+- [Talking to the node](#talking-to-the-node)
+- [Node writes](#node-writes)
+- [Network exposure](#network-exposure)
+- [Transport security](#transport-security)
+- [Browser security](#browser-security)
+- [Outbound connections](#outbound-connections)
+- [What is stored, and where](#what-is-stored-and-where)
+- [Hardening checklist](#hardening-checklist)
+
+## Threat model in one paragraph
+
+The monitor is a **reader**. It holds your node's RPC credentials, so the main risks are:
+someone using the monitor to make the node do something (prevented: writes are off, the RPC
+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.
+
+## Access: open by default, accounts on request
+
+With the default `auth.enabled: false`, anyone who can reach the port reads the monitor
+with the fixed role `viewer`:
+
+| open to anyone who can reach the port | still closed |
+|---|---|
+| every chart, the sync view, the event stream | user administration |
+| 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 |
+
+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:
+
+| role | may |
+|---|---|
+| `viewer` | read everything above |
+| `operator` | also run node actions that have been explicitly enabled |
+| `admin` | also manage users and read the audit trail |
+
+The last enabled admin cannot be demoted, disabled or deleted.
+
+## Accounts, sessions and passwords
+
+- **Passwords** are hashed with scrypt (N=16384, r=8, p=1 by default), with a per-user salt;
+  a 12-character minimum and common breach-corpus shapes are refused. Passwords are never
+  logged, never returned by any API, and stored only as hashes. Each user's scrypt
+  parameters are stored with the hash; raising them in the configuration upgrades an
+  account on its next successful sign-in.
+- **Sessions** use 32-byte random tokens, stored hashed, in an `HttpOnly`, `SameSite=Strict`
+  cookie (`Secure` over HTTPS). A session ends 8 hours after its last request, and 72 hours
+  after sign-in whatever happens.
+  Roles are re-read on every request, so a demotion takes effect immediately.
+- **CSRF**: every state-changing request must carry an `X-CSRF-Token` header matching the
+  session; the cookie alone is never accepted as proof. With accounts off there is no session
+  to ride, so the token check has nothing to compare -- and until 2026-09-13 that meant those
+  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.
+- **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.
+
+## 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
+  `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
+  rule. It cannot be used to flood your node. The one exception is the address index build,
+  which makes its few cheap calls (block hashes) over a second connection so that the pages are
+  not queued behind it — and which pauses itself whenever the first lane sees the node failing
+  or answering slowly.
+- **The block files are read directly** (`<datadir>/blocks`), once, to build the address
+  index; the node is not asked for them. The index directory is written by the build and by the
+  follower, and nothing else in the node's data directory is ever written.
+- **Credentials** are read from the cookie file on demand (it changes on every node restart)
+  or from the configured user and password. They are never sent to the browser.
+
+## Node writes
+
+Node actions (for example `savemempool`) are **off**. Enabling one requires all of:
+
+1. `BLOCKYARD_ENABLE_ACTIONS=1`,
+2. the action named in `BLOCKYARD_ACTIONS` (a comma-separated list),
+3. accounts on and a role of at least `operator` — or the deliberate
+   `BLOCKYARD_ALLOW_WRITES_WITHOUT_AUTH=1`, which exists so that the combination can only ever
+   be chosen on purpose,
+4. a typed confirmation that matches the action's name, per call.
+
+Every call and every refusal is appended to the audit trail.
+
+## Network exposure
+
+- **Bind** only the addresses you mean to serve (`server.host`, a string or a list). See
+  [INSTALL.md](INSTALL.md#7-decide-who-can-reach-it) for the options and their consequences.
+- A bind chooses a destination address, not an incoming interface; use a firewall if "LAN
+  only" must hold against containers or tunnels on the same machine.
+- **CIDR gate**: `server.allowCidrs` refuses clients outside the listed IPv4/IPv6 networks.
+  Membership is computed on the address bytes, and a malformed entry stops the start-up
+  rather than silently admitting or refusing everyone.
+- `/api/health` needs no sign-in, so an uptime probe works. It reveals the node inventory,
+  version, tip and health to anyone who can reach the port.
+- Behind a reverse proxy, set `server.trustProxy` so rate limits and the CIDR gate see the
+  real client address — and only then.
+
+## 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.
+- 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.
+- Plain HTTP is acceptable for a trusted LAN or behind a tunnel; the start-up log says when
+  it is serving plain HTTP.
+
+## Browser security
+
+- **Content Security Policy**: `default-src 'self'`, `frame-ancestors 'none'`, scripts only
+  from the monitor itself plus a per-response nonce, and **no inline styles at all**
+  (`style-src 'self'` with no attribute exception). Every data-driven style is applied through
+  the CSSOM instead of `style="…"` attributes.
+- Also sent: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`,
+  `Referrer-Policy: no-referrer`.
+- The browser loads nothing from third parties: no CDN, no web fonts, no analytics. Market
+  data reaches the browser only through the monitor's own API.
+
+## Outbound connections
+
+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 |
+
+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.
+
+The monitor sends no telemetry, checks for no updates, and phones home to no one.
+
+## What is stored, and where
+
+Everything the monitor writes lives in its data directory (`./data` by default,
+`BLOCKYARD_DATA` to move it):
+
+| file | contents | sensitivity |
+|---|---|---|
+| `users.json` | account names, roles, scrypt hashes and salts | **secret** (mode 0600) |
+| `sessions.json` | hashed session tokens | **secret** |
+| `audit.jsonl` (+ rotations) | who called what and when; rotated by size (8 MiB, 5 kept) | private |
+| history snapshots | chart time series for the retention window (72 h by default) | private |
+| `pool-aliases.json`, `pool-map.json` | optional mining-pool labels: `pool-aliases.json` is human-edited; `data/pool-map.json` is what `node scripts/pool-map.js` fetches, and it overrides the curated `config/pool-map.json` that ships with the code (mempool.space/mining-pools, MIT, 151 pools) | not secret |
+| the address index (`addressIndex`, `data/index` by default) | the explorer's address index: ~124 GB of sorted rows built from the node's block files, plus the follower's `live.log` and `layers/` | public chain data, not secret |
+
+`config/local.json` may hold an RPC password; keep it readable only by the service account.
+Both it and `data/` are git-ignored. Display settings (the gear) are stored in
+`config/blockyard.json`, so every browser sees the same board; they change how things are drawn,
+never what is measured.
+
+Logs go to standard output (the systemd journal). They record requests, node state changes
+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.
+- 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.
+- 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/STATE-2026-09-09.md

@@ -0,0 +1,200 @@
+# State of the project — 2026-09-09 (handoff for an agent with a real browser)
+
+> **Superseded 2026-09-14, names only.** This is a dated record and its measurements stand as
+> written. The names in it are the ones in use that day and are no longer current: the project
+> is **BlockYard** (`/storage/blockyard`, systemd `blockyard.service`, env vars `BLOCKYARD_*`,
+> default web port 21000), and the node it watches is Bitcoin Core. `bmc-port-guard.sh` and
+> `/etc/ssl/bmc-local/ca.crt` are real artefacts on the operator's machine and keep their names.
+
+Written by the session that built the mining/visualisation layer. Everything below was
+run on this box; the things I could **not** do are listed explicitly at the end. Read
+`AGENTS.md` first for the rules (zero dependencies, RPC-only sources, never fabricate a
+figure, a chart never erases itself).
+
+## What is running
+
+| Thing | Where | Note |
+|---|---|---|
+| bmcmonitor | `https://<LAN address>:8088` | systemd `bmcmonitor.service`, TLS via a **local CA** (`/etc/ssl/bmc-local/ca.crt`), binds the **LAN address only** — loopback, docker bridges and the tailnet address all refuse, by design |
+| Node watched | `bmc-main`, RPC `127.0.0.1:8331` | the node's own esplora REST is on `127.0.0.1:3005` |
+| Log tailing | **OFF** (default since today) | the UI reads RPC only. `BMC_MON_LOG_SOURCE=1` re-enables it for parser work; do not add panels that need it |
+| Block-chain node under dev | `/storage/bitcoinmachinecode` | a *different* session works there; do not restart or reindex it casually |
+
+Import the CA or the browser will refuse the certificate. After any deploy, hard-reload:
+asset URLs are stamped `?v=<build>` and the stamp changes when files change, so a tab
+holding an old tab keeps running old code — that has already produced one false report
+today ("still renders nothing" while the fix was on disk and undeployed).
+
+## Verify, don't trust this document
+
+```bash
+cd /storage/bmcmonitor
+npm test                      # unit + render + contract tests
+bash scripts/smoke.sh         # 109 checks against a real server
+npm run counts                # do the documented counts match the suite?
+LAN=$(python3 -c "import json;print(json.load(open('config/local.json'))['server']['hosts'][0])")
+BMC_MON_BASE=https://$LAN:8088 BMC_MON_CA=/etc/ssl/bmc-local/ca.crt npm run render:live
+sudo systemctl restart bmcmonitor          # deploy after editing public/** or server/**
+sudo journalctl -u bmcmonitor -f           # server-side view; the UI records to it
+```
+
+`render:live` renders **every page** under the DOM stub against the running monitor and
+fails if an asserted card is empty. Today it caught, in order: an uncaught `ReferenceError`
+that killed the entire Overview (two cards "rendered nothing" because one line above them
+threw), a `fmt is not defined` crash on the Node page, and a card that no test had ever
+reached.
+
+## What was built today (mining + visualisation)
+
+- **Mining page** (`#mining`): block flow (construction → tip → history, the tip explicitly
+  labelled `current tip`, colour = age verdict), ghost cards for the next blocks marked
+  `not yet assembled`/`estimate`, ancestor-package table (CPFP shape from
+  `getblocktemplate…depends`, with `depends` being **indices into the array**, not txids),
+  and two treemaps.
+- **Treemaps** (`public/js/goggles.js`): one rectangle per transaction, area = vbytes,
+  colour = the feerate it pays, richest-first. The canvas is **the block**: a 14%-full block
+  looks 14% full and the rest is drawn blank and labelled. Cells are bounded (400) and the
+  remainder collapses into ONE aggregate cell so the block is always whole.
+- **Tip freshness** is judged against the chain's own measured block interval, not a fixed
+  clock: amber past ~1× the average gap, red past ~1.5×, floors at 4/8 min. Arrival is only
+  counted when the page **witnessed** the height change — a first paint must not claim a
+  fresh tip (that bug coloured a 14-minute-old block green).
+- **Overview** gained a compact copy of the block map (`ovGnTreemap`, `w4`, `.treemap.sm`).
+
+## Bugs I fixed, so you don't re-diagnose them
+
+- `rows` TDZ in `renderOverview` — two `rows` in one function; killed the whole Overview
+  render (the Fees card and the "mempool vs blocks" card were collateral).
+- `fmt is not defined` in `panels.js:drawSelf` — the Node page crashed.
+- Treemap `drawFrame` referenced `label` without destructuring → **every partly-filled
+  block threw at paint time and the canvas stayed blank**.
+- The treemap tween re-requested animation frames whenever the clock failed to advance
+  (hidden/throttled tab) → unbounded loop. Now a frame budget + stalled-clock check, and
+  the settled layout always draws.
+- **CSP**: the policy is `style-src 'self'` with no `style-src-attr` allowance (correct,
+  tightened earlier today). My new markup emitted `style="..."` and the browser blocked
+  **several hundred** applications, so the train and maps lost every colour. All of it now
+  travels as `data-pool` / `data-rate` / `data-w` / `data-delay` / `data-rail` and lands on
+  `el.style` through the CSSOM (`applyMiningStyles` in `mining.js`, `applyDataSizes` in
+  `app.js`). The palette index comes from our own array — a pool name from the node cannot
+  become CSS. `test/csp.test.js` now fails if any JS-built markup carries a style attribute.
+- **The Fees card** was found with `getElementById('ovFees').closest('.card')`, and the DOM
+  stub answers `closest()` with `null` — so **no test ever exercised that card**. It is now
+  `#ovFeesCard`, addressed by id, and asserted in `test/web-contract.test.js`.
+
+## Known, open, or unverified — this is what a browser is for
+
+1. **Nothing has been seen rendered.** No real-browser harness exists. Layout, colour
+   legibility, overlap, and "does the treemap read as a block" are unverified by me.
+2. **Treemaps at `w4`** (33%) on Mining, `w4` on Overview: is 168px/240px high enough for
+   the labels, and is the "block unfilled" band legible at that width?
+3. **Legend/label collisions** inside rectangles (rate + `k` vbytes text) at small cell
+   sizes, and the `selection ends` / `everything fits in one block` label near the right
+   edge.
+4. **Hover tooltips** (`.goggles-tip`) are positioned `left/bottom` — check they don't
+   cover the cursor's cell or overflow the card.
+5. **Motion**: the map tweens only when the Mining page is open and the template refetches
+   (on load + every 20 s). Confirm the tween is visible, and that `prefers-reduced-motion`
+   snaps without losing information.
+6. **`app.js` boot throws under the DOM stub** (`TypeError` at `boot()`, harness-only). Real
+   browsers don't hit it; it means a stub element is missing, and it will keep biting anyone
+   extending the harness.
+7. Ghost-card forward capacity numbers are **queue-depth estimates**, not node data.
+8. No TLS certificate automation (self-signed local CA), and `:8999` (mempool-backend API)
+   is loopback-only by a netfilter rule — separate from this app.
+
+## Guardrails that will bite if you ignore them
+
+- **Zero dependencies.** No `npm install`. Node builtins and hand-written canvas only.
+- **No host identity in committed files.** `test/privacy.test.js` derives the username,
+  hostname forms and interface addresses at run time and fails on them — it caught a
+  hardcoded LAN address in one of my scripts today. Use RFC 5737 documentation ranges in
+  docs and tests, and read addresses from config/env at run time.
+- **Test counts are generated** (`npm run counts:fix`). Never type them.
+- **Every claim in a comment must be a measurement** with a number and a date. "Seems" is
+  not a justification, and this project has twice been burned by a check that passed for
+  the wrong reason (a vacuous assertion, a stub that answered `null`).
+- A chart **never erases itself** to show a status; absence renders as `–` with a reason,
+  and stale data renders visibly stale.
+- Absent data is **never** filled with a guess: no per-tx `depends` in
+  `getrawmempool` on this node, so cluster analysis is only drawn from
+  `getblocktemplate`, and the panel says which of the two it is.
+
+---
+
+## Measured in a real browser (2026-09-10, headless Chromium over CDP)
+
+`scripts/browser-check.mjs` drives Chromium over CDP with Node's built-in WebSocket: it
+loads the page, samples **canvas pixels with getImageData**, reads inline vs computed CSSOM
+values, measures element rects, collects console/exceptions, and can pass the screenshot to
+the local vision model. This is the first time any of this has been looked at rather than
+inferred. It found five defects that 349 passing tests did not.
+
+### Found and fixed
+1. **Shared animation handle.** `goggles.js` kept one module-level `raf` for both maps, so
+   each canvas's render cancelled the *other* one's pending frame — and the first frame was
+   drawn only inside that callback. The loser painted **nothing**: `__hasData: true`, 401
+   rects laid out, 68% of the canvas covered on paper, **zero painted pixels**. Now the
+   handle is per-canvas (`c.__raf`) and the settled layout is painted before any animation.
+2. **Tween grew cells from zero size.** With a snapshot arriving every second, the chart
+   spent most of its life mostly-cleared with 1px rectangles. Now position interpolates and
+   **size never does**; new cells fade in with alpha. A tween must be the difference between
+   two visible states, not the thing that makes pixels exist.
+3. **`style-src` was silently vetoing my own markup** (several hundred blocked
+   applications): all `style="..."` removed in favour of `data-pool` / `data-rate` /
+   `data-w` / `data-h` / `data-delay` / `data-rail` + CSSOM. Guarded by a test that fails if
+   any JS-built markup carries a style attribute.
+4. **`.closest('.card')`** made the Fees card invisible to every test (the DOM stub answers
+   `null`), so it could render nothing forever. Now addressed by `#ovFeesCard`.
+5. **`rows` TDZ** in `renderOverview` killed the whole Overview. Also: the earlier "fixed"
+   report was false because the fix was never **deployed** — deploy is part of a fix.
+
+### Still broken, with the measurements
+- **The Mining page block map still paints nothing** (`gnTreemap`: `rects: 401`,
+  `distinctColours: 0`, `paintedPixelsPct: 0`) while the mempool map on the same page paints
+  100% with the identical code path and the same rect count. I did not find the cause. Start
+  by comparing what differs at `drawFrame` time between the two — `geom.unused` is set for
+  the block map and absent for the mempool map, which changes `region`; instrument
+  `drawFrame` with a counter and a sample of the first rect's `fillStyle`.
+- **The style pass is only half applying.** In the browser: `.bdot` inline style is
+  `background: rgb(95, 176, 201)` with **no `--pool`**, and `.bfill span` has `background`
+  but **no width**, while `document.querySelectorAll('[data-w]')` counts 27 of which **2**
+  have an inline width (the sync hero's, applied by app.js). So `applyMiningStyles` is
+  running an older code path than the one on disk and served (`setProperty` and
+  `applySizes` are both present in the served bytes, and `Cache-Control: no-cache`). That
+  contradiction is unresolved — check whether the module the browser evaluates is the
+  module the server sent (compare `import.meta` resolution / a marker constant), before
+  touching the style code again.
+- **The flow row overflows its card** and is cut off: `.flow` scrollWidth 2236 inside
+  clientWidth 1369. I added `.flow { width: max-content }` + `.flowwrap { overflow-x: auto }`;
+  the browser still measured clipping after the change, so either the CSS did not apply as
+  written or the grid parent constrains it. Re-measure `.flowwrap` rather than `.flow`.
+
+> **Superseded 2026-09-14:** the first two readings above were the harness measuring the
+> previous build, not the page — `Page.navigate` to a URL differing only in its fragment does not
+> reload the document (`docs/RULES.md` rule 25). Re-run against the current build on 2026-09-10,
+> `gnTreemap` and `gnMempoolTreemap` both painted 100% of their pixels.
+
+### Notes on the harness itself
+- Chromium only survives inside one shell invocation, so launch + check must run together:
+  `rm -rf /tmp/cp; (setsid /usr/bin/chromium-browser --headless=new --no-sandbox
+  --user-data-dir=/tmp/cp --remote-debugging-port=9333 --ignore-certificate-errors
+  about:blank &) ; until curl -s 127.0.0.1:9333/json/version >/dev/null; do sleep 2; done;
+  BMC_MON_BASE=https://<lan>:8088 node scripts/browser-check.mjs mining`
+- Quote `--remote-allow-origins=*` or the shell globs it into filenames.
+- **`Page.navigate` to a URL differing only in `#fragment` does not reload the document.**
+  Reusing a warm browser therefore re-measures whatever was loaded before the last deploy:
+  `public/**` changes, the page does not, and every reading is of the previous build. The
+  harness now appends `?t=<ms>` for this reason. Rule 25: prove the browser is running the
+  bytes you served before believing anything it says about them.
+- Do not assert `document.body.firstChild` is an element. Leading whitespace before
+  `<header>` is a `#text` node in every ordinary document; a probe that checked this
+  "proved" the Overview rendered nothing when it had rendered fine throughout.
+- `Page.loadEventFired` is not reliably seen by the current waiter; the probe's
+  **load guard** (abort unless `#nav` and body children exist) is what stops a broken
+  invocation being reported as "the page is blank" — that happened once and the vision
+  model confidently confirmed a blank white page that was only my own bad URL.
+- Vision: this deployment answers with `content: null` and the text in `reasoning`; reading
+  only `content` silently yields an empty review.
+- `mempool-backend.service` has been `failed` since 2026-09-09 16:58 (start-limit hit after
+  12 restarts; its own stdout is not in the journal). Unrelated to the above, untouched.