@tikoci/centrs 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# centrs
+
+`centrs` is the tikoci RouterOS interaction hub: a Bun/TypeScript library and
+CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
+RouterOS devices through a regularized, validated interface.
+
+It is a **friendly conduit**, not a high-level configuration abstraction. It
+helps humans and agents reach RouterOS over the right protocol, with the right
+credentials and ports, and validates RouterOS-shaped commands before running
+them. It does **not** hide RouterOS behind helpers like `createVlanOnBridge()`
+— you still speak RouterOS. Validation and structured diagnostics are the
+product; without them this would just be a worse `curl`.
+
+> **Status:** early and in active development. The library, device registry, and
+> first MCP server phases are CHR-verified; the CLI is wired (`coded`); encrypted-CDB
+> writes are still blocked, and the TUI/proxy frontends are planned.
+> `docs/MATRIX.md` is the single source of truth for what works today — treat
+> anything not green there as not-yet-shipped.
+
+## What it talks to, and how
+
+- **Frontends:** TypeScript API, CLI, MCP server (Phase 1 + first Phase 2 CDB
+  mutation `CHR-passed` — see `commands/mcp/`), TUI and HTTP proxy/daemon
+  (future).
+- **Protocols:** REST API (preferred), native API, and SNMP for reads;
+  SSH / MAC-Telnet / RoMON / WinBox Terminal for interactive and L2 execute;
+  MNDP for discovery. centrs picks the protocol for you (and lets you pin one
+  with `via=` or `--via`).
+- **Commands:** every command resolves a *target* — a router you name on the
+  CLI — to a real address, credentials, and a protocol, then runs.
+
+| Command    | Purpose |
+| ---------- | ------- |
+| `retrieve` | Read RouterOS state over REST/native API and SNMP OID/MIB values. |
+| `stream`   | Follow live RouterOS output (`print follow`/monitor/sniffer) as an NDJSON stream of envelopes. |
+| `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
+| `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
+| `check`    | Probe reachability and management protocol availability. |
+| `devices`  | View and maintain the CDB-backed device registry (the only writer). |
+| `discover` | Discover MNDP neighbors and optionally save them into the CDB. |
+| `settings` | Manage centrs's own settings (`centrs.env`, `__default__`) and run first-time setup. |
+
+Each command's `commands/<name>/` directory carries its design and the
+executable example list that gates "done".
+
+## Your WinBox address book *is* the device registry
+
+centrs deliberately has **no config store, credential vault, or inventory
+database of its own**. Instead it piggybacks on the one most RouterOS admins
+already keep: the WinBox connection database (CDB), the `winbox.cdb` file that
+WinBox writes when you save a router in its address book.
+
+centrs reads (and, through `devices`, writes) that same file at its well-known
+location, `~/.config/tikoci/winbox.cdb` (override with `--cdb-file` /
+`CENTRS_CDB_FILE`). From each saved entry it takes the fields WinBox already
+stores:
+
+- **`target`** — the address you saved (IPv4, IPv6, MAC, or DNS name); a literal
+  you can type at the CLI to reach the box. centrs *also* resolves a `<router>`
+  against three sanctioned comment lookup keys — `identity=`, `mac=`, and `ip=` —
+  so a router whose `target` is `192.0.2.5` is still reachable as `edge1` when its
+  comment carries `identity=edge1`. Every other comment token stays inert prose.
+  See `commands/devices/README.md` (Identity model) for the full resolution rules.
+- **`user` / `password`** — the credentials centrs connects with. They stay in
+  the CDB and are redacted from MCP results/resources.
+- **`group`, `profile`, `session`, port** — used as-is.
+
+So `centrs retrieve edge1 /ip/address` works with no flags: `edge1` is looked
+up in the CDB, its credentials and address come along for the ride. A target
+that *isn't* in the CDB still works, but then `--username` / `--password` (or
+`CENTRS_USERNAME` / `CENTRS_PASSWORD`) become mandatory.
+
+### Overloading the comment: per-device settings as `key=value`
+
+A WinBox CDB entry has no field for "always use SSH for this box" or "skip
+validation here" — those are centrs concepts WinBox knows nothing about. Rather
+than invent a parallel store, centrs **overlays its own settings onto the one
+free-text field WinBox does have: the comment.** It parses `key=value` tokens
+(the "comment kv-soup") out of that free text and treats the recognized ones as
+per-device defaults. Everything else in the comment stays inert human prose.
+
+A comment like:
+
+```text
+edge1 prod border router   via=ssh validate=false mcp=rw
+```
+
+leaves `edge1 prod border router` as plain text for you and WinBox, while
+centrs reads three settings from it. The recognized keys:
+
+| Key        | Effect                                                                  |
+| ---------- | ----------------------------------------------------------------------- |
+| `via`      | Default transport for this device (`rest-api`, `native-api`, `ssh`, …). |
+| `validate` | `true` / `false`. `false` is the escape hatch; a CLI flag still wins.   |
+| `timeout`  | Default request timeout in ms (per-transport caps still apply).         |
+| `port`     | Non-default transport port.                                            |
+| `ssh-key`  | Path to a per-device SSH private key (a path only — never key material).|
+| `source`   | Provenance marker for discovered/imported records (`mndp`, `dude`, …).  |
+| `mcp`      | MCP write policy: `ro` (default) or `rw`. See below.                    |
+
+The first-class fields WinBox already stores (`user`, `password`, `group`,
+`profile`, `session`) must **not** be written into the comment — they have real
+CDB tags, and `devices set` refuses to put them there. Unknown keys produce a
+`cdb/unknown-option` warning and are ignored, so a stray `=` in human prose
+never breaks anything.
+
+Settings resolve lowest-to-highest: **built-in defaults → project config →
+comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every result envelope
+reports which source won each setting under `meta.settings`, so you can always
+see *why* a given port or transport was chosen.
+
+### Groups, discovery, and the MCP allowlist all ride on the CDB
+
+- **Groups** are CDB-native: an entry's `group` field is just a string, and
+  `--group prod-edge` fans a single command out to every entry that shares it.
+  There is no separate group-definition file.
+- **Discovery** writes back into the CDB: `discover --save` records MNDP
+  neighbors as new entries tagged `group=discovered` with a `source=mndp`
+  marker — hints to curate, not authoritative inventory.
+- **The MCP server uses the CDB as its authorization boundary.** Agents can
+  only reach targets that exist in the CDB; RouterOS write-shaped execution
+  requires the resolved entry to carry `mcp=rw` plus per-call confirmation.
+  `centrs_devices` can also add/set/remove CDB records in-band, and
+  `centrs_discover` can save MNDP neighbors, with `confirm: true`. The allowlist
+  and the write policy are *the same CDB data* you already manage — see
+  `commands/mcp/`.
+
+`devices` is the only command that writes the CDB, and it does so safely
+(timestamped backup, atomic rename, unknown WinBox fields preserved verbatim).
+Encrypted-CDB **reads** work with `--cdb-password` / `CENTRS_CDB_PASSWORD`;
+encrypted **writes** are currently blocked pending a verified WinBox round-trip.
+The full contract — identity resolution, ambiguity handling, write strategy,
+and the comment grammar — lives in `commands/devices/README.md` and
+`docs/CONSTITUTION.md` (Identity and CDB).
+
+## The result envelope, validation, and errors
+
+- **Validation is on by default** (`validate=true`). Reads are checked through
+  `/console/inspect`; CLI-shaped `execute` commands through `[:parse]`. Set
+  `validate=false` (per device or per call) only as a deliberate escape hatch.
+- **Every call returns one envelope:** `{ ok, data?, warnings?, error?, meta }`,
+  with provenance and source-of-truth reporting in `meta`.
+- **Errors are typed values**, not thrown strings, with slash-namespaced codes
+  (`routeros/…`, `transport/…`, `validation/…`, `cdb/…`) and a `details_url`
+  of the form `https://tikoci.github.io/centrs/errors/<code>` for the
+  human-readable explanation.
+
+The load-bearing contract — envelope shape, error model, protocol selection,
+settings precedence, and the "done" definition — lives in
+`docs/CONSTITUTION.md`. The command×protocol status grid is `docs/MATRIX.md`.
+
+## Repository layout
+
+For contributors. An admin only needs the CLI and their CDB; this is where the
+code and authority docs live.
+
+- **`docs/CONSTITUTION.md`** — load-bearing rules (validation, envelope, error
+  model, settings precedence, identity/CDB, protocol selection, done).
+- **`docs/MATRIX.md`** — command×protocol grid; the only status surface.
+- **`commands/<name>/`** — per-command README and executable examples.
+- **`src/`** — Bun/TypeScript source.
+- **`test/`** — unit and CHR-backed integration tests.
+
+There is no `docs/specs/`, no `work/`, no roadmap doc. The matrix is the
+roadmap.
+
+## Development
+
+Requirements:
+
+- Bun 1.3.11 or newer (CI pinned to 1.3.13; Bun 2.x not yet validated).
+- Git.
+- For integration tests: QEMU plus `@tikoci/quickchr` (handles CHR image
+  download and boot).
+
+```bash
+bun install
+bun run lint
+bun run test
+bun run test:integration   # CHR-backed; required before claiming "done" on transport code
+bun run test:integration:long-term  # channel-specific CHR gate
+bun run build
+```
+
+Generated API docs through TypeDoc:
+
+```bash
+bun run build:doc:api
+```
+
+## Done definition (short version)
+
+A feature is done when every line in `commands/<name>/examples.md` is green on
+real CHR via `bun run test:integration`. Code existing is not done. Unit tests
+passing is not done. Full rule:
+`.github/instructions/done-definition.instructions.md`.

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Report privately via [GitHub Security Advisories](https://github.com/tikoci/centrs/security/advisories/new). Do **not** open a public issue for an undisclosed vulnerability.
+
+Please include the affected files or workflow, reproduction details, and impact. Initial response within a few business days; fixes land on `main` and flow into the next published artifact.
+
+## Scope
+
+`centrs` will mediate RouterOS device access, credentials, local discovery data, and optional HTTP/MCP proxy surfaces. Security-sensitive areas include credential import/cache, RouterOS write execution, local network discovery, file transfer, and any daemon that binds a network port.
+
+## Code scanning
+
+The repository's [Security tab](https://github.com/tikoci/centrs/security) is the live source of current alerts and advisories. This section describes *what* checks run and *why*, so the doc stays meaningful even when the badge is at 0.
+
+- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality). Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
+- **Code Quality (AI findings, preview)** — intended to be enabled in GitHub. [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract.
+- **Dependency review** — not enabled. GitHub dependency review follows dependency-graph ecosystem support, and this Bun-only repository currently does not have a supported lockfile for that gate.
+- **Dependabot security updates** — enabled and configured in [`.github/dependabot.yaml`](.github/dependabot.yaml).
+- **Secret scanning** — enabled in GitHub, with push protection.
+- **Private vulnerability reporting** — enabled via GitHub Security Advisories.
+
+Some GitHub Security tab data, especially Code Quality AI findings, is not currently available through stable unauthenticated APIs. Human review in the GitHub UI remains part of the security workflow.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| `main` | yes |

package/commands/AGENTS.md

@@ -0,0 +1,50 @@
+# commands/
+
+Each `commands/<name>/` holds the **executable spec** for one command:
+
+- `README.md` — intent, flags, behavior. The "designed" tier.
+- `examples.md` — numbered, runnable examples. Each example is one assertion in
+  the matching `test/integration/<name>.test.ts`; example N ↔ assertion N. This
+  is what `CHR-passed` is measured against.
+
+Do not restate the constitution here or in a command README — link to
+`docs/CONSTITUTION.md` for envelope, errors, settings precedence, target
+selection, and protocol selection. The identity/CDB **resolution depth** (lookup
+keys, ambiguity, `__default__`, comment-kv allowlist, write strategy) lives in
+`commands/devices/README.md` — the registry command owns it; the constitution
+keeps only the identity/CDB principle. A command file covers only what is
+specific to that command. `docs/MATRIX.md` is the only status surface; a
+README's "Status" line must agree with it.
+
+## Verb vocabulary
+
+Commands are centrs **verbs** (`retrieve`, `stream`, `execute`, `devices`,
+`discover`, `check`, `terminal`, `settings`), never one tool per RouterOS command. Sub-verbs and their
+aliases are canonical across CLI / API / MCP:
+
+| Canonical | Aliases          | Meaning                                  |
+| --------- | ---------------- | ---------------------------------------- |
+| `list`    | `print`          | Read many records. (`print` is RouterOS muscle-memory.) |
+| `show`    | `get`            | Read one resolved record.                |
+| `add`     | —                | Create; refuses an existing target.      |
+| `set`     | —                | Modify an existing record (same flags as `add`). |
+| `remove`  | `rm`, `delete`   | Delete a record.                         |
+| `edit`    | —                | **Reserved** for the future clack/TUI wizard. Not a field-editing verb. |
+| `groups`  | —                | List distinct groups.                    |
+
+Canonical names win in help text and docs; aliases resolve to the canonical verb
+silently. `add` and `set` are symmetric (same flags + `k=v` tokens), differing
+only on existence. There is no `update` verb — RouterOS add/set/remove ride
+`execute` (constitution: protocol selection).
+
+## Help system
+
+Shared across CLI / API / MCP help rendering:
+
+- **Level-aware help.** `<command> <subcommand> --help` is more specific than
+  `<command> --help` — e.g. `centrs devices remove --help` shows the `remove`
+  usage and flags, not the whole `devices` surface.
+- **"Did you mean?"** On an unknown verb/sub-verb or flag, the error
+  (`input/invalid-command` / usage error) lists the closest canonical matches
+  (Levenshtein) plus accepted aliases — extending the invalid-command behavior
+  that already enumerates canonical verbs + aliases.

package/commands/btest/README.md

@@ -0,0 +1,257 @@
+# btest
+
+Run MikroTik's **bandwidth test** as a cross-platform client or server. `btest`
+is centrs's peer-measurement surface: it mirrors `/tool/bandwidth-test` (client)
+and `/tool/bandwidth-server` (server), so it is a drop-in for the Windows-only
+`btest.exe` on macOS/Linux.
+
+Status: server **and** client both `CHR-passed`. The protocol **codec**
+(`src/protocols/btest.ts`), the shared **EC-SRP5** core including the net-new
+server role (`src/protocols/ec-srp5.ts`), the **session state machine + TCP/UDP
+data engines** (`src/protocols/btest-session.ts`), the **orchestrator**
+(`src/btest.ts`), and the **CLI** (`centrs btest client|server`) all exist and are
+unit/loopback-tested. Two gated CHR integration tests **pass on CHR 7.23.1**:
+`test/integration/btest.test.ts` lands a real RouterOS `/tool/bandwidth-test`
+client's TCP-receive, UDP-transmit (with loss accounting), and **EC-SRP5** sessions
+on the centrs **server**; `test/integration/btest-client.test.ts` runs the centrs
+**client** against a real RouterOS `/tool/bandwidth-server` over a host→guest
+`tcp:2000` forward — unauthenticated TCP receive, an **EC-SRP5 client proof
+verified by RouterOS's own verifier**, and a wrong-password reject. TCP
+multi-connection (`connection-count > 1`) data fan-out is a follow-up. See
+`docs/MATRIX.md` ("Peer measurement (`btest`)") for the cell states — that is the
+only status surface. v1 scope: **both** modes (client + server), **EC-SRP5 +
+unauthenticated** auth, **TCP and UDP** tests. Legacy pre-6.43 double-MD5 is out of
+scope.
+
+## Why this is not `execute`
+
+btest is **not** a RouterOS-shaped command — it issues no CLI string and there is
+no `:parse` / `/console/inspect` gate. It is a **peer protocol** (TCP/UDP port
+2000) that centrs speaks directly to a RouterOS bandwidth server/client (or to
+another `btest.exe`/centrs). `docs/CONSTITUTION.md` adds it as a deliberate
+capability axis (*measure*, see Protocol selection): the envelope, identity
+resolution, and friendly-error contract still hold, but the RouterOS-command
+validation gate does not apply. btest is **explicit-only** — never auto-selected,
+never a downgrade target, and no other command rides it.
+
+## Synopsis
+
+```text
+centrs btest client <router> [--protocol udp|tcp] [--direction receive|transmit|both] \
+                    [--duration 15s] [--interval 1s] [--connection-count N] \
+                    [--local-udp-tx-size N] [--remote-udp-tx-size N] \
+                    [--local-tx-speed bps] [--remote-tx-speed bps] [--random-data] \
+                    [--user U] [--password P] [--port 2000] [--csv | --format text|csv|json|yaml]
+
+centrs btest server [--authenticate[=false]] [--user U] [--password P] \
+                    [--bind 127.0.0.1] [--port 2000] \
+                    [--allocate-udp-ports-from 2001] [--max-sessions 100] \
+                    [--duration 1h] [--csv | --format text|csv|json|yaml]
+```
+
+## Intent
+
+- **Speak RouterOS, not an abstraction.** Flag names mirror
+  `/tool/bandwidth-test` and `/tool/bandwidth-server` verbatim (`direction`,
+  `protocol`, `local-udp-tx-size`, `connection-count`, `authenticate`,
+  `allocate-udp-ports-from`, …) so RouterOS muscle memory transfers. centrs adds
+  only `--bind` (a server safety control) and the shared `--format`.
+- **Client** connects to a RouterOS bandwidth server (or a `btest.exe`/centrs
+  server), authenticates if required, runs the test in the requested direction,
+  and streams live throughput reports plus a final summary.
+- **Server** listens on TCP/UDP port 2000, answers the handshake, performs the
+  EC-SRP5 server role when `authenticate=yes`, runs the requested test, and
+  streams session events. It runs in the foreground until `--duration` elapses or
+  Ctrl-C.
+- **Identity resolution (client).** `<router>` resolves through the CDB exactly
+  like every command (constitution: identity and CDB) — `target` and the
+  `identity=`/`mac=`/`ip=` lookup keys yield the host, and `user`/`password` come
+  from the record (or `__default__`, env, CLI). A target not in the CDB still
+  works when `--user`/`--password` (or `CENTRS_USERNAME`/`CENTRS_PASSWORD`) are
+  given. The server takes no target.
+- **Validation is option-grammar validation** (constitution: validation is the
+  product). centrs rejects incoherent option combinations *before* opening a
+  socket — e.g. `connection-count` with `protocol=udp`, `*-udp-tx-size` with
+  `protocol=tcp`, an out-of-range size (28..64000) or direction — with a
+  `validation/*` / `usage/*` error. There is no `:parse` step.
+
+## Flags
+
+### `btest client <router>`
+
+| Flag | RouterOS analog / default | Notes |
+| ---- | ------------------------- | ----- |
+| `--protocol <udp\|tcp>` | `protocol`, default `udp` | UDP measures raw throughput + loss; TCP measures goodput. |
+| `--direction <receive\|transmit\|both>` | `direction`, default `receive` | `receive` = download (server→client), `transmit` = upload. |
+| `--duration <dur>` | `duration` | Bounds the run; reuses `parseDuration`. Omit for open-ended (Ctrl-C). |
+| `--interval <dur>` | `interval`, default `1s` | Report cadence (`20ms`..`5s`). One report frame per interval. |
+| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. |
+| `--local-udp-tx-size <n>` | `local-udp-tx-size` (28..64000) | **UDP only.** Client→server packet size. |
+| `--remote-udp-tx-size <n>` | `remote-udp-tx-size` (28..64000) | **UDP only.** Server→client packet size. |
+| `--local-tx-speed <bps>` | `local-tx-speed` | Cap on client→server rate (bits/sec). |
+| `--remote-tx-speed <bps>` | `remote-tx-speed` | Cap on server→client rate (bits/sec). |
+| `--random-data` | `random-data`, default off | Incompressible payload (defeats link compression; CPU-heavier). |
+| `--user` / `--password` | `user` / `password` | Fall back to CDB / `CENTRS_*`. Required when the server has `authenticate=yes`. |
+| `--port <n>` | — (default `2000`) | Control port override. |
+| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = live human reports; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
+| `--csv` | — | Shortcut for `--format csv`. |
+
+### `btest server`
+
+| Flag | RouterOS analog / default | Notes |
+| ---- | ------------------------- | ----- |
+| `--authenticate[=false]` | `authenticate`, **default `true`** | Require EC-SRP5 auth; `--authenticate=false` accepts anonymous clients. |
+| `--user` / `--password` | — | The accepted credential when `authenticate=true` (v1: one user). Falls back to `CENTRS_*`. |
+| `--bind <addr>` | **centrs-only** | Listen address; **default `127.0.0.1`**. Use `0.0.0.0` to expose on the LAN. |
+| `--port <n>` | — (default `2000`) | Control-connection port. |
+| `--allocate-udp-ports-from <n>` | `allocate-udp-ports-from` | Base of the UDP data-port range; default `2001` (just above the TCP/2000 control port). |
+| `--max-sessions <n>` | `max-sessions` (1..1000), default `100` | Concurrent test cap; further clients get `routeros/btest-too-many-sessions`. |
+| `--duration <dur>` | — | Optional auto-stop; otherwise runs until Ctrl-C. |
+| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = human session log; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
+| `--csv` | — | Shortcut for `--format csv`. |
+
+## How it works
+
+The control channel is TCP on port 2000. The server sends a hello; the client
+replies with a 16-byte command packet (protocol type, direction, data type, TCP
+connection count, UDP tx size, buffer size, remote/local speed limits). For a UDP
+test, data then flows on the server's allocated UDP ports
+(`allocate-udp-ports-from`+) and the client's `+256`-offset ports; loss is derived
+from sequence gaps. For a TCP test, the bulk data rides `connection-count` TCP
+connections and goodput is measured on the data stream (TCP/IP headers excluded,
+matching RouterOS accounting). For multi-connection TCP the server's OK response
+carries a 2-byte **session token**; the extra connections reconnect and present
+that token to join the same test (no re-auth). Throughput and CPU are exchanged
+once per `interval` as a 12-byte **status message** on the TCP channel
+(`[0x07][0x80|cpu][00 00][seq u32 LE][bytesReceived u32 LE]`).
+
+### Authentication (EC-SRP5)
+
+RouterOS ≥ 6.43 (so 7.x, including the 7.23 target) authenticates btest with
+**EC-SRP5** on the Curve25519-in-short-Weierstrass curve — the same curve centrs
+already ships for mac-telnet. The password never crosses the wire. The curve math
+is shared from `src/protocols/ec-srp5.ts` (extracted from `mtwei.ts`); btest adds
+its own control-stream framing on top. The **server** role (generate a keypair,
+accept the client offer, derive the shared secret, and *verify* the client proof)
+is net-new — `mtwei.ts` only implements the client. A bad proof (or a client that
+will not offer EC-SRP5 against an `authenticate=yes` server) maps to
+`transport/auth-failed`. Legacy pre-6.43 double-MD5 is out of scope for v1.
+
+## Output
+
+btest runs over time, so it emits **live records** during the run plus a final
+**summary**. v1 keeps the formats simple and **defers a broader JSON-streaming
+decision** — it does *not* adopt the `stream` command's NDJSON-stream-of-envelopes
+contract yet (see Open questions):
+
+- **`text`** (default) — human-readable live reports during the run
+  (RouterOS / `btest.exe`-style `tx`/`rx` current/average/total; the server
+  prints a session log), then a final summary line.
+- **`--csv`** (shortcut for `--format csv`) — **the streaming format**: one CSV
+  record per `--interval` report (client) or per session event (server), after a
+  header row. Pipe-friendly for logging/plotting.
+- **`--format json` / `yaml`** — a **single summary envelope** emitted at
+  completion (`--duration` elapsed or Ctrl-C): the standard
+  `{ ok, data, warnings, tips, error, meta }` with `meta.via = "btest"`. `data`
+  aggregates the whole run — totals plus `data.reports[]` (client interval
+  samples) / `data.sessions[]` (server) — so it is **lossless** against what
+  `text` and `csv` streamed. It is not itself streamed (one envelope, at the end).
+
+CSV columns — client:
+`seq,direction,protocol,tx_bps,rx_bps,lost_packets,tx_bytes,rx_bytes` (one row per
+interval; `seq` is the status sequence number, `tx_bytes`/`rx_bytes` the per-interval
+byte counts); server:
+`duration_ms,event,client,protocol,direction,user,tx_bps,rx_bps,lost_packets` (one row
+per session; `tx_bps`/`rx_bps` are session averages, `lost_packets` is the UDP loss
+total — 0 for TCP). A mid-run error ends
+the stream and is carried in the summary envelope's `error` (`json`) or a final
+`error` row (`csv`); the process exit code reflects whether the test/server
+*started* cleanly.
+
+## Server is a network listener
+
+`centrs btest server` opens a TCP/UDP listener on port 2000 — a security-sensitive
+surface (`docs/CONSTITUTION.md`, Network listeners). It is an **explicit,
+foreground, user-invoked** command, **not** a daemon and **not** the proxy. It
+**binds `127.0.0.1` by default** (pass `--bind 0.0.0.0` to expose on the LAN) and
+**requires auth by default** (`authenticate=true`, mirroring RouterOS). The
+accepted credential (`--user`/`--password`/`CENTRS_*`) and any client credentials
+are redactable in bug-report output.
+
+## Errors
+
+- `validation/option` — an option is incompatible with the chosen
+  protocol/direction (e.g. `connection-count` with `protocol=udp`,
+  `*-udp-tx-size` with `protocol=tcp`) **or** out of range (UDP size `28..64000`,
+  `connection-count 1..255`, `interval 20ms..5s`, `max-sessions 1..1000`). Caught
+  before any socket opens; `error.context.option` names the offending flag.
+- `transport/connection-refused` — no bandwidth server answered on port 2000
+  (server disabled, firewalled, or wrong host). Fix: enable
+  `/tool/bandwidth-server`, check the port/`--bind`.
+- `transport/auth-failed` — EC-SRP5 proof rejected, or the server requires auth
+  and the client offered none / wrong credentials.
+- `routeros/btest-too-many-sessions` — (server) a client was refused because
+  `max-sessions` is reached.
+- `routeros/btest-protocol` — a malformed/unexpected control packet from the peer.
+
+## Validation policy (CHR + loopback + btest.exe)
+
+Decided with the user. Both cells have direct gated `CHR-passed` evidence:
+
+- **Server cell — CHR client → centrs server** (`test/integration/btest.test.ts`):
+  `@tikoci/quickchr` boots a CHR whose `/tool/bandwidth-test` dials the **host**
+  (the QEMU SLIRP gateway `10.0.2.2`) where the centrs server listens on
+  `--bind 0.0.0.0 --port 2000`. Guest→host needs **no hostfwd**. Proven paths are
+  **TCP** (any direction — TCP is bidirectional on the outbound control connection)
+  and **UDP transmit** (client→server, which the guest originates, so SLIRP NATs it
+  cleanly), with unauth + EC-SRP5 and throughput cross-checked against the CHR's own
+  status. **UDP receive / both** depend on the server's packets reaching the guest's
+  UDP port *back* through SLIRP NAT (a one-shot smoke cycle only — see Open
+  questions).
+- **Client cell — centrs client → CHR `/tool/bandwidth-server`**
+  (`test/integration/btest-client.test.ts`): the CHR boots with a host→guest
+  `extraPorts` forward `{ name: "btest", host: 0, guest: 2000, proto: "tcp" }`, so a host TCP port
+  maps onto the guest bandwidth server on 2000 (the same SLIRP inbound path that
+  already carries REST/SSH — no firewall change). The centrs client dials
+  `127.0.0.1:<host port>` and proves **TCP receive**, unauth and **EC-SRP5** (its
+  client proof verified by RouterOS's real server verifier), plus a wrong-password
+  reject. **TCP only** — UDP would need the server's datagrams to traverse SLIRP
+  back to the host, which this forward does not provide, so UDP client→server stays
+  loopback/transitive.
+
+The fast/deterministic backstop under both is **centrs client ↔ centrs server
+loopback** (`127.0.0.1`, injected sockets) covering the full client↔server matrix,
+EC-SRP5 both roles, and the option-grammar rejects.
+**`btest.exe` (via wine) is a coding-time grounding aid only** — used by hand
+while implementing the EC-SRP5 framing and the server-side verifier; it is **not**
+an integration test (it cannot run in CI) and **not** part of the long-term plan.
+
+**Honest grounding caveat:** both cells are now directly CHR-passed. The remaining
+transitive-only paths are **UDP client→CHR-server** (the SLIRP reverse-NAT path the
+TCP forward does not cover) and TCP **multi-connection** fan-out — both deferred,
+not yet gated.
+
+## Open questions
+
+- **JSON streaming is deliberately deferred.** btest does not adopt the `stream`
+  command's NDJSON-stream-of-envelopes contract yet; v1 streams `text` / `csv` and
+  returns a single summary envelope for `json` / `yaml`. Revisit a streaming-JSON
+  shape — ideally shared with `stream` — once that contract is settled.
+- **UDP receive/both through SLIRP is unproven.** Before the integration suite
+  relies on server→guest UDP, a **one-shot CHR smoke test** must confirm the path
+  works — i.e. that the RouterOS client originates an initial UDP/NAT probe that
+  opens the SLIRP reverse mapping. Until then the gated UDP coverage is
+  **transmit** (guest→host); TCP already covers both directions.
+- **UDP client→CHR-server and TCP multi-connection are not yet gated.** The direct
+  client→CHR-server gate (`test/integration/btest-client.test.ts`) is **TCP only**;
+  a UDP variant needs the server's datagrams to traverse SLIRP back to the host
+  (the reverse-NAT path), and `connection-count > 1` needs the parallel-stream
+  fan-out. Both remain loopback/transitive until gated. `btest.exe` (wine) is the
+  coding-time grounding peer, not CI.
+
+## Out of scope (v1)
+
+Legacy pre-6.43 double-MD5 auth; a UDP client→CHR-server gated test (TCP is gated;
+UDP needs SLIRP reverse-NAT); the ≥3-router "test-through" topology RouterOS
+recommends for measuring a *transit* device (centrs is an endpoint peer); TUI/proxy
+btest frontends (later, over the stable core).