blockyard 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 BobClawblaw and contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+BlockYard
+Copyright 2026 BobClawblaw and contributors
+
+This product is licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,6 +1,193 @@
-# blockyard
+# BlockYard
 
-This package name is reserved for **Blockyard**, a self-hosted monitor for a Bitcoin
-node: live charts, a 3D block-space viewer, a block explorer and a markets view.
+A live, multi-user web monitor and block explorer for
+[Bitcoin Core](https://github.com/bitcoin/bitcoin).
 
-Nothing is published here yet. Source: https://github.com/BobClawblaw/blockyard
+Point it at your node and open a browser: live charts, a 3D block-space viewer,
+a block / transaction / address explorer, exchange prices with order-book depth, and a
+kiosk view for a wall screen. No dependencies to install, no CDN, no telemetry, no outbound
+connection but to your node out of the box, and read-only toward your node by default.
+
+**This is 100% machine-generated code, directed by a human operator.** Every line of the
+server, the browser app, the 3D engine, the tests and these documents was written by an AI
+under a human's direction, and all auditing has been performed by AI and is published in this
+repository ([docs/SECURITY-AUDIT.md](docs/SECURITY-AUDIT.md), [docs/SECURITY-AUDIT-2026-09-14.md](docs/SECURITY-AUDIT-2026-09-14.md), [docs/DEFECTS.md](docs/DEFECTS.md),
+[docs/MEASUREMENTS.md](docs/MEASUREMENTS.md)). It is **experimental pre-release software: expect
+bugs.**
+
+![Overview](docs/images/overview.jpg)
+
+## Highlights
+
+| | |
+|---|---|
+| **Block space, in 3D.** The next block's worth of the mempool as a board of glowing tiles: area is vbytes, colour is feerate. Refreshes are choreographed — blocks lift, travel in collision-free lanes and land under gravity — and the board comes alive at rest with **34 idle effects**, from ripples and light cycles to a lightning ball, ball lightning, a UFO's tractor beam, Missile Command, fireworks, code rain and a demoscene plasma. Two viewer modes: **Simple** (the richest few hundred transactions as cubes) and **Detailed** (every transaction in the block). | ![Block space, Detailed mode](docs/images/block-space-mode2.jpg) |
+| **A board you can tune.** Neon-tube blocks, a metallic sheen or a chrome finish that mirrors a horizon, a movable lamp, a touch of perspective, a spiral galaxy behind the board, and a switch for every one of the 34 effects — in a tabbed settings panel. Stored on the server (`config/blockyard.json`), so every screen sees the same board; they change how things are *drawn*, never what is measured. | ![Neon blocks and the metallic sheen](docs/images/block-space-neon.jpg) |
+| **An explorer that looks the part.** Search a height, block hash, txid or address. Transaction pages with fee, fee rate and dollar value, feature badges, a flow diagram from inputs to outputs, and links to where every coin came from and went. **Address pages with full history and balance** — Bitcoin Core has no address index, so BlockYard builds its own from the node's block files (**a few hours** on first start, 124 GB) and keeps it current as blocks arrive. | ![Explorer transaction](docs/images/explorer-tx.jpg) |
+| **Markets.** Five exchanges' public prices: a 3D candle chart with a neon price line, a precise flat candlestick chart, an exchange table, and a bitcoinity-style order-book depth chart with change bars. Off until you tick **Enable market polling** — it is the one thing that talks to anyone but your node — and, once on, fetched by the server only while someone is looking. | ![Markets](docs/images/markets.jpg) |
+| **Kiosk.** The 3D markets board, a price panel and the block-space board side by side, full screen with one click. | ![Kiosk](docs/images/kiosk.jpg) |
+| **Tetrust, Blockout and Blockanoid.** Three playable games built on the same 3D engine — trust, but verify. Tetrust is Tetris: the well is the block-space board and the music is synthesised in the browser. Blockout is Breakout, where the wall is made of block-space stones and the bat follows your mouse. Blockanoid is Arkanoid: a different wall every level, silver bricks that take more than one hit, gold that takes none, and capsules that fall out of what you break — laser, wide, catch, slow, three balls, a life. All three pause when you look away and keep high scores per browser. And **Wolfenstein 3D**, **DOOM** and **Quake**: the real shareware `WOLF3D.EXE` (1992), `DOOM.EXE` (1993) and `QUAKE.EXE` (1996), unmodified, on a PC emulated in the browser — processor in real and protected mode, FPU, DOS and both extenders, VGA and Sound Blaster written from scratch, still with no dependencies. So if anyone asks *"well, can it run DOOM?"*, the answer is an emphatic **"Naturally. What sort of AI slop generator do you take me for?"** | ![Tetrust](docs/images/tetrust.jpg) |
+
+Also on board: a sync viewer with an honest ETA, Block flow (projected blocks, the block
+being built, recent blocks), mempool and fee charts, a peer table, bandwidth, the node's
+event stream, a provenance table for every figure, a read-only RPC console behind a
+default-deny allowlist, and a tabbed **Display settings** panel (the gear) that tunes every
+board without a reload and picks the layout's colours — light or dark, the shipped look, Mono,
+Nous, GitHub, Catppuccin, or nine colours of your own.
+
+## Quick start
+
+You need **Node.js 22 or newer** and a running **Bitcoin Core 25.0 or later** with `server=1`
+and `txindex=1`, **on the same machine** — BlockYard reads the node's block files to build the
+explorer's address index, and a node on another machine is not supported. Without `txindex` the
+explorer cannot look a confirmed transaction up by id; everything else works without it (see
+[Requirements](docs/INSTALL.md#1-requirements)). Plan for disk: the index is about **125 GB**, on
+top of the node's own ~875 GB of block files.
+
+```bash
+git clone https://github.com/BobClawblaw/blockyard.git
+cd blockyard
+npm test            # optional: 945 unit tests, all built in
+npm run setup       # reads the node's bitcoin.conf, checks the node, writes config/local.json
+npm start           # builds the address index in the background (a few hours); open https://127.0.0.1:21000
+                    # and sign in as admin with the password the first start prints once
+```
+
+`npm run setup` asks for the node's data directory, reads its `bitcoin.conf` for the rest,
+proves the credentials, the chain, `txindex`, the block files and how fast the node answers,
+writes `config/local.json`, and offers to start BlockYard there and then. The address index is
+built **by BlockYard itself, in the background**, the first time it starts, and **it takes a few
+hours** — about two on the default four workers on NVMe, longer on spinning disks (30 minutes on
+16 workers) — with progress on the Overview and a notification when it is done; every other page
+works meanwhile, and address pages fill in once it finishes. Step by step for macOS and Linux: **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)**.
+To try it first without a node: `npm run dev` runs against a built-in fake one on port 18088.
+To check a setup again later: `npm run check`.
+
+**Why the same machine?** Running BlockYard elsewhere and reading a node over RPC alone was
+tried (2026-09-13) and abandoned: the charts filled in, but the explorer could not be made to
+work in real time over RPC — Core has no address index, and the one RPC that can answer a
+balance holds the node's RPC thread for tens of seconds per query. The address data has to be
+rebuilt from the block files and stored locally, the way mempool.space's `electrs` does it, so
+BlockYard lives next to the node. See
+[It runs on the node's machine](docs/INSTALL.md#it-runs-on-the-nodes-machine).
+
+The full walkthrough — service install, network exposure, accounts, TLS, a reverse proxy —
+is in **[docs/INSTALL.md](docs/INSTALL.md)**.
+
+## Documentation
+
+| document | what it covers |
+|---|---|
+| [Getting started](docs/GETTING-STARTED.md) | macOS or Linux, from a command prompt: Core settings, Node 22, `npm run setup`, the background index build, running it |
+| [Install](docs/INSTALL.md) | requirements, first run, systemd service, exposure, accounts, TLS, reverse proxy, updating |
+| [Configuration](docs/CONFIGURATION.md) | every config key and environment variable, with examples |
+| [User guide](docs/USER-GUIDE.md) | a tour of every tab and panel, and how to read them |
+| [API](docs/API.md) | the JSON HTTP API and the Server-Sent Events stream |
+| [Architecture](docs/ARCHITECTURE.md) | server, RPC lane, collectors, browser app and the 3D engine |
+| [Security & privacy](docs/SECURITY.md) | the access model, hardening, and every outbound connection |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | the problems people actually hit, and the fixes |
+| [Contributing](CONTRIBUTING.md) | development setup, tests, and the project's rules |
+| [Changelog](CHANGELOG.md) | release history |
+
+Deeper reference material: [docs/RULES.md](docs/RULES.md) (the rules, each with the defect
+that produced it), [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md) (the node measurements the
+design rests on) and [docs/DEFECTS.md](docs/DEFECTS.md) (known limits).
+
+## Design principles
+
+- **Read-only by default.** The monitor never writes to your node unless you enable
+  individual actions, with accounts on and a typed confirmation per call.
+- **A good guest.** Every request goes through one serialized, prioritised, batched lane,
+  so the monitor never opens a burst of parallel calls against your node's RPC threads.
+  It would rather skip a poll than slow your node down.
+- **Honest data.** A missing figure is shown as missing, never as zero; stale data looks
+  stale; inferred numbers are labelled as inferences; every figure's source is listed on
+  the Node & RPC page.
+- **Zero dependencies.** Node built-ins on the server; vanilla ES modules and hand-written
+  canvas rendering in the browser. No build step, no CDN, nothing fetched from third
+  parties by your browser.
+
+## Security at a glance
+
+- **Hardened out of the box** — it listens on `127.0.0.1` only and requires sign-in: the
+  first start creates an `admin` account and prints its password once. Accounts, roles,
+  sessions, CSRF protection and a per-user audit trail are on. Reach it from another machine
+  over an SSH tunnel, or bind a LAN address (`BLOCKYARD_BIND`) when you decide the LAN may
+  see it; open, read-only access with no account is a choice (`BLOCKYARD_AUTH=0`), announced
+  at boot.
+- **HTTPS by default** — the first start makes the monitor its own certificate (no
+  dependencies: the X.509 is written by hand), and every listener serves it; a certificate of
+  your own with `BLOCKYARD_TLS_CERT` / `BLOCKYARD_TLS_KEY`, or `BLOCKYARD_TLS=0` behind a
+  proxy that terminates TLS.
+- **Where it listens is your decision** — `127.0.0.1`, a LAN address, a VPN address, or
+  several.
+- **No outbound connections out of the box**: a fresh install talks to nothing but your node.
+  The one exception is opt-in — a checkbox, **Display settings → Markets & Price → Enable
+  market polling**, turns on the exchange feed for the Markets and Kiosk tabs, Overview's price
+  line and the explorer's dollar figures, and even then the server asks the exchanges only while
+  someone is looking. `BLOCKYARD_MARKETS=0` removes the feed so that no checkbox can turn it on.
+
+Details in [docs/SECURITY.md](docs/SECURITY.md). To report a vulnerability, see
+[SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+npm run dev          # fake node doing a simulated sync, port 18088
+npm run setup        # interactive install: read bitcoin.conf, check the node, write config/local.json
+npm run check        # the same checks (every call timed) against every configured node; exits 1 on a FAIL
+npm test             # 945 unit tests (node:test, no dependencies)
+npm run smoke        # boots the real server and checks the HTTP contract
+npm run counts:fix   # keep the documented test count in step with the suite
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project's rules (CSP, canvas, privacy,
+RPC etiquette) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how it fits together.
+
+## Status
+
+Version **0.1.0** — the first minor release, two days after the initial 0.0.9, and pre-release
+software: the word is meant literally. Published 2026-09-16: on [npm](https://www.npmjs.com/package/blockyard)
+as `blockyard`, as a [GitHub release](https://github.com/BobClawblaw/blockyard/releases/tag/v0.1.0),
+and announced on
+[bitcointalk](https://bitcointalk.org/index.php?topic=5594141.msg67144312) — questions, bug
+reports and reviews are welcome there and in [issues](https://github.com/BobClawblaw/blockyard/issues).
+It ships **hardened**: bound to this machine, sign-in on, HTTPS with a certificate it makes itself,
+and **zero telemetry** — no outbound connection to anyone but your node until you tick the market
+polling switch yourself.
+The test suite is
+comprehensive (945 tests, plus a live smoke run), the monitoring side is solid, and the
+explorer's biggest gap is closed: **address history and balances**, which Bitcoin Core cannot
+answer at any setting, now come from an **address index BlockYard builds itself** from the
+node's block and undo files and keeps current as blocks arrive. It is checked against the node
+(every balance equal to `scantxoutset`, to the satoshi) and costs a few hours on the default four
+workers (~30 minutes on 16) and 124 GB of disk, built in the background the first time BlockYard starts and paced so the node's
+RPC stays responsive; without one, the address page says *not indexed* rather than showing a
+zero. An address's unspent outputs are listed too (for a history of up to 100 transactions).
+What it does not yet have: an address's mempool transactions.
+
+Everything here was written by an AI directed by a human, and audited by AI:
+[docs/SECURITY-AUDIT.md](docs/SECURITY-AUDIT.md) and
+[docs/SECURITY-AUDIT-2026-09-14.md](docs/SECURITY-AUDIT-2026-09-14.md) are the audits, findings
+and remediation included. The test suite runs in CI on Ubuntu, macOS and Windows (Node 22 and 24);
+a real install has been done on macOS (Core 29.1) and Linux, and Windows has only the test suite.
+[docs/DEFECTS.md](docs/DEFECTS.md) lists five open items, honestly stated, with the
+measurements behind each. Read it before deploying: several are node-capability limits
+rather than bugs, and knowing which is which matters.
+
+## Acknowledgements
+
+The block-space view and the explorer are inspired by the look of
+[mempool.space](https://mempool.space); the markets tab by
+[bitcoinity.org](https://data.bitcoinity.org). Market data comes from the public APIs of
+Coinbase, Kraken, Bitstamp, Bitfinex and OKX. The mining-pool labels shipped in
+`config/pool-map.json` are mempool.space's curated
+[mining-pools](https://github.com/mempool/mining-pools) list (MIT, 151 pools).
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). The block-space packer and feerate palette are an original implementation (public/js/blockpack.js, public/js/feepalette.js), inspired by the look of mempool.space but containing none of its code.
+
+---
+
+<sub>If BlockYard is useful to you: `bc1q249cv27lc2q7y0x53vkczgfvvgsjzhwxwv42gc`</sub>

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Supported versions
+
+| version | supported |
+|---|---|
+| 0.0.9 | yes |
+| anything else | no (never released) |
+
+## Reporting a vulnerability
+
+Please report security problems **privately**, not in a public issue:
+
+1. On GitHub, open the repository's **Security** tab and choose **Report a vulnerability**
+   (private vulnerability reporting), or
+2. contact the maintainer through their GitHub profile and ask for a private channel.
+
+Include what you found, the version or commit, how to reproduce it, and the impact you
+expect. If you have a fix in mind, describe it — but please do not open a public pull request
+for an unpatched vulnerability.
+
+What to expect:
+
+- an acknowledgement within a few days;
+- an assessment and, if confirmed, a fix and a release with credit to you (unless you prefer
+  otherwise);
+- coordinated disclosure once a fixed release is available.
+
+## Scope
+
+In scope: the monitor's server and browser code in this repository — authentication and
+sessions, the RPC allowlist and node-write gates, the HTTP API, the CSP and other headers, and
+anything that could leak node data or credentials.
+
+Out of scope: vulnerabilities in the Bitcoin node itself (report those to the node's project),
+in Node.js, or in the exchanges whose public APIs the Markets tab reads; and deployments that
+deliberately expose an open (no-accounts) monitor to untrusted networks — that is a
+configuration choice described in [docs/SECURITY.md](docs/SECURITY.md).

package/bin/blockyard.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// THE COMMAND, for an install from npm (`npm install -g blockyard`):
+//
+//   blockyard setup          ask where the node is, check it, write the config, build the index
+//   blockyard start          run the monitor
+//   blockyard check          the same checks as setup, any time
+//   blockyard index-build    build the address index by hand (--out <dir> [--workers N])
+//   blockyard users          manage accounts (list / create / passwd / role)
+//
+// A global install lives wherever npm puts packages, which is nowhere to keep a config or 124 GB
+// of index; so unless the environment says otherwise, this command keeps everything under
+// ~/.blockyard: local.json (the config), data/ (state, and the index at data/index). A checkout
+// run with `npm run …` keeps config/ and data/ inside the checkout, as before, because it does
+// not come through here.
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const home = process.env.BLOCKYARD_HOME ?? path.join(os.homedir(), '.blockyard');
+process.env.BLOCKYARD_CONFIG ??= path.join(home, 'local.json');
+process.env.BLOCKYARD_DATA ??= path.join(home, 'data');
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const COMMANDS = {
+  setup: 'scripts/setup.js',
+  check: 'scripts/check.js',
+  start: 'server/main.js',
+  'index-build': 'scripts/index-build.js',
+  users: 'scripts/manage-users.js',
+  tls: 'scripts/tls.js',
+};
+const cmd = process.argv[2];
+if (!COMMANDS[cmd]) {
+  const version = JSON.parse((await import('node:fs')).readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+  process.stdout.write(`BlockYard ${version}\n\n  blockyard setup          ask where the node is, check it, write the config, build the index\n  blockyard start          run the monitor\n  blockyard check          the same checks as setup, any time\n  blockyard index-build    build the address index by hand (--out <dir> [--workers N])\n  blockyard users          manage accounts\n  blockyard tls            remake this monitor's own HTTPS certificate (--san to add names)\n\nconfig ${process.env.BLOCKYARD_CONFIG}\ndata   ${process.env.BLOCKYARD_DATA}\n`);
+  process.exit(cmd ? 2 : 0);
+}
+// the scripts decide "am I being run directly?" by comparing argv[1] to their own path, so hand
+// them the path they expect rather than this file's
+process.argv.splice(1, 2, path.join(root, COMMANDS[cmd]));
+await import(path.join(root, COMMANDS[cmd]));