@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/commands/devices/examples.md

@@ -651,7 +651,7 @@ centrs devices add 192.0.2.1 --user robot-reader --cdb-file ./lab/winbox.cdb --j
 ```
 
 Creates missing parent directories and an empty open CDB with mode `0600`.
-`data` is `{ cdbFile, created: true, recordCount: 0 }`. The `add` then succeeds.
+`data` is `{ cdbFile, created: true, encrypted: false, recordCount: 0 }`. The `add` then succeeds.
 
 ### 55. `init` never clobbers
 
@@ -660,8 +660,63 @@ centrs devices init --cdb-file ./lab/winbox.cdb --json
 ```
 
 On an existing, readable CDB: `ok: true`, `data.created: false`,
+`data.encrypted` reports the actual encryption mode,
 `data.recordCount` is the current count, and a `cdb/file-exists` warning says
 nothing was written. As with `git init`, re-running is safe. An existing file that
 does not load fails with that load error (`cdb/parse-failed`,
 `cdb/password-required`) and is left untouched. A location that cannot be
 written fails with `cdb/create-failed`.
+
+### 56. Initialize encrypted from the start
+
+```bash
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices init --encrypt --cdb-file ./prod.cdb --json
+```
+
+Creates a complete encrypted empty CDB with mode `0600`; subsequent loads require
+that password. `data.encrypted` is `true`. Re-running verifies the password
+and reports `created: false`, `encrypted: true`.
+Test: `centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 57. Convert a lab CDB to encrypted
+
+```bash
+centrs devices init --cdb-file ./lab.cdb
+centrs devices add 192.0.2.1 --user reader --cdb-file ./lab.cdb
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices encrypt --cdb-file ./lab.cdb --json
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices list --cdb-file ./lab.cdb --json
+```
+
+Conversion reports `encrypted: true`, `changed: true`, `recordCount: 1`, and
+`backupPath`. Records survive a password-protected reload; loading without a
+password fails. All backups remain, including the plaintext pre-conversion file;
+`cdb/plaintext-backups` warns explicitly. Repeating with the same password returns
+`changed: false`; a wrong password fails without writing. Without `--json`,
+text reports conversion or verified unchanged, the record count, and the
+plaintext snapshot path when created; the warning remains visible.
+Test: `centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 58. Encryption intent fails closed
+
+`init --encrypt` and `encrypt` refuse a missing or empty CDB password before
+creating anything. `init --encrypt` refuses an existing open CDB without changing
+it. `--encrypt` on other subcommands and positional targets on `encrypt` are
+invalid commands. Record, selection, and provenance flags (`--user`, `--group`,
+`--password`, `--via`, …) on `init`/`encrypt`, and `--no-backup` on anything but
+`encrypt`, are `input/invalid-command` rather than silently ignored. Test:
+`centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 59. Convert without a plaintext snapshot
+
+```bash
+centrs devices init --cdb-file ./lab-fresh.cdb
+centrs devices add 192.0.2.1 --user reader --cdb-file ./lab-fresh.cdb
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices encrypt --no-backup --cdb-file ./lab-fresh.cdb --json
+```
+
+A fresh path, so it does not depend on example 57 having already converted
+`./lab.cdb`. Conversion reports `changed: true`, `recordCount: 1`, and no
+`backupPath`, and no new `.bak.*` file appears. The backup the `add` wrote
+is retained, so
+`cdb/plaintext-backups` still warns. Test: `centrs devices encryption (#558)`
+in `test/integration/devices.test.ts`.

package/commands/execute/README.md

@@ -44,7 +44,14 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   `isWriteShaped` is deliberately independent: script fallback for `[find]`, a
   positional id, or other non-`key=value` input never bypasses confirmation.
   Known read verbs are allowlisted; an unknown menu verb fails closed as a
-  write-shaped operation. In script mode every command head in a statement
+  write-shaped operation. A truly bare known-menu path (`/system/identity`,
+  example W6) is the one exception: structured mode proves the input is a
+  single path token, so it is console navigation — a no-op read — rather than
+  a command. The device still answers truthfully (`no such command` on the
+  APIs) and the envelope carries a steering tip naming the read that answers.
+  A bare no-argument *command* (`/system/reboot`) stays gated, as does
+  script-branch navigation (#387), where a later line may carry a relative
+  verb. In script mode every command head in a statement
   (the statement start and each `[…]` or `{…}` body) must be a read: its verb
   is the first word past the known menu prefix, so `/ip address print` is a
   read and `/user expire-password print` is not (examples W3). Script
@@ -283,7 +290,14 @@ A sent write is **never retried** (#448). Fan-out retries a target only for
 when the failure came before the request was sent (for example while it was
 being validated). A write that failed after it was sent may have run, so its
 error envelope, single-target or fan-out, carries the warning
-`transport/write-outcome-unknown`.
+`transport/write-outcome-unknown`. A multi-statement write refused with
+`routeros/permission-denied` carries the same warning: statements before the
+refused one may already have run (#549). Statements inside executed control
+scopes (`:if … do={…}`) and command substitutions (`[…]`) count; stored bodies
+(`source={…}`, `:global f do={…}`) do not, and a `/menu { … }` prefix is
+navigation, not a statement. A single refused statement did not
+run and stays silent, including one fed by a lone substitution
+(`remove [find …]`) or wrapped in a menu block.
 
 ## CMR clients through their controller (`--cmr`)
 
@@ -361,8 +375,9 @@ when the target is itself a CMR client.
   controller's own row through `run-script`, and rebooted a client through
   both. So a "reader" login on a 7.26beta1 controller is not read-only, and
   centrs' write gate (and `mcp=ro` on MCP) is the only gate. MikroTik
-  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; that is not yet
-  checked on a beta2 build. For a write,
+  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; #527 now carries
+  direct 7.26beta3 evidence that a restricted caller is refused, with the
+  first refusing release still unbracketed. For a write,
   centrs reads the login's own `/user` row and `/user/group` once (both are
   readable with just `read` + `api`). When the login lacks `write`, `test` or
   `reboot`, the result and the confirmation error carry
@@ -514,14 +529,30 @@ How it is wired:
   but rejects the MD5 proof, so centrs advertises MTWEI (`src/protocols/mtwei.ts`)
   by default. `END_AUTH` ≠ success (a failed login emits `END_AUTH` then "Login
   failed" + `END`) → `transport/auth-failed`.
+- **MTWEI hash encoding (grounded, #565):** RouterOS hashes shared `z` and the
+  REDP1 loop seed minimal-length; `haakonnessjoen/MAC-Telnet`'s `mtwei.c` pads
+  both to 32 bytes. When they differ, the padded proof fails. On CHR 7.25 over
+  the L2 harness (2026-10-31): short-`z` logins accepted the minimal proof 8 of
+  8 and rejected the padded proof 1 of 1 (about 700 logins). The `z` edge hits
+  about 1 in 256 logins. The REDP1 edge depends on the salt RouterOS generates
+  at each password change, about 1 in 317 changes; it fails every login until
+  the next change. A password-rotation scan over raw handshakes to PASSSALT
+  found divergent salts, and on one the minimal proof was accepted 3 of 3 while
+  the padded proof was rejected 3 of 3, all with a clean 32-byte `z` to isolate
+  the edge. The shared core is `src/protocols/ec-srp5.ts`.
 - **Console quirks to know:** a successful write **prints no output** (no `.id`,
   unlike REST/native — `data.ret` is empty on a successful add); and there is a
   ~10s terminal-negotiation stall on every login (a latency cost, not a
   correctness issue — see `commands/terminal/README.md` for the optional fix).
 - **Delivery:** the UDP transport sends to `--host`/`--port` (default L2 broadcast
   `255.255.255.255:20561`); the device replies to our source IP:port, and the
-  in-packet MACs do the addressing. The CHR test points `--host`/`--port` at the
-  loopback L2 bridge.
+  in-packet MACs do the addressing. The device answers only broadcast delivery
+  (unicast gets no reply), and only when the in-packet *source* MAC is the
+  egress interface's real MAC — a synthetic source gets no reply on hardware
+  (CHR answers it, so the suite cannot catch a wrong source). With the default
+  host centrs sprays per-interface discovery with real MACs; with an explicit
+  `--host <directed-broadcast>` it resolves the owning interface's MAC. The CHR
+  test points `--host`/`--port` at the loopback L2 bridge.
 
 Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
 `test/unit/execute.test.ts`); callers wanting IP-level execution opt into ARP

package/commands/execute/examples.md

@@ -67,9 +67,9 @@ centrs execute $R ':local a true; :if ($a = true) do={:put [/system/identity/get
 
 Envelope: `ok: true`, `data` is string-shaped (`data.output` or `data.ret`) and
 contains the CHR identity name, `meta.via=rest-api`, and
-`meta.validation.syntax=true`. `meta.validation.semantic` is absent or marked
-`not-applicable` because `/console/inspect` validates path-shaped commands, not
-arbitrary script expressions. The `$a` variable must survive the validation
+`meta.validation.syntax=true`. `meta.validation.semantic` is absent because
+`/console/inspect` validates path-shaped commands, not arbitrary script
+expressions (#535). The `$a` variable must survive the validation
 wrapper: if that outer string expands it before `:parse`, this example fails even
 though RouterOS accepts the original command.
 
@@ -490,8 +490,8 @@ Envelope: `ok: false`, `error.code=validation/package-missing`,
 `error.context.packages` names the published package, the remediation points at
 `/system/package/print` and never at the syntax, and `error.position` and
 `error.context.detail` keep RouterOS's own column and words. V5–V7 all report
-`meta.validation.syntax=false`. `semantic` is absent, or `not-applicable` for
-the script-shaped `/container print` (GH#435).
+`meta.validation.syntax=false`, and `semantic` is absent because the
+name-level check was never asked (GH#435, #535).
 
 ### V6. A menu no RouterOS build has is an unknown path
 
@@ -633,6 +633,25 @@ This is a grounding version, not an introduction boundary. Unknown or
 ambiguous output-file prefixes stay write-shaped until the device resolves
 them.
 
+### W6. A bare menu path needs no confirmation and answers with a steering tip
+
+```bash
+centrs execute $R '/system/identity' --via rest-api --username $U --password $P
+```
+
+No `--yes` gate: a truly bare known-menu path is console navigation, a no-op
+read, and structured mode proves the input is a single path token with no
+follow-up. The device still answers truthfully — REST reports
+`routeros/request-failed`, native API `routeros/api-trap`, both carrying
+RouterOS's own `no such command` — and the envelope carries
+`tip/execute-bare-menu-path`, naming `/system/identity/print` (or
+`centrs retrieve $R /system/identity`) as the read that answers. A bare
+no-argument *command* such as `/system/reboot` stays write-shaped and still
+requires confirmation.
+
+`test/integration/execute-write-gate.test.ts` proves the gate stays open for
+navigation and shut for no-arg writes, on REST and native API.
+
 ### R1. A post-validation `/execute` rejection fails the overall envelope
 
 ```bash