tr-json-chain-tools 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tri@iki.fi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# tr-json-chain-tools
+
+Command-line tools for [`tr-json-chain`](https://www.npmjs.com/package/tr-json-chain)
+— an immutable, append-only, SHA-256 hash-chained JSON event log on PostgreSQL.
+
+Two executables:
+
+| command | what it does |
+|---|---|
+| `tr-json-chain-cli` | record events into a chain and inspect it (interactive or piped) |
+| `tr-json-chain-check` | verify the integrity of a chain exported to CSV — standalone, no database |
+
+## Install
+
+```sh
+npm install -g tr-json-chain-tools
+```
+
+or run without installing:
+
+```sh
+npx -p tr-json-chain-tools tr-json-chain-cli  postgres://… mychain
+npx -p tr-json-chain-tools tr-json-chain-check export.csv
+```
+
+## A PostgreSQL to play with
+
+A throwaway server is handy for trying things out. A compose file ships under
+`dc/`:
+
+```sh
+docker compose -f dc/docker-compose.yml up -d
+# → postgres on localhost:5433, user/password postgres/postgres
+```
+
+## `tr-json-chain-cli`
+
+```
+tr-json-chain-cli --pg-url <uri> [--namespace <ns>] [--verify]
+```
+
+| option | env | description |
+|---|---|---|
+| `--pg-url <uri>` | `OPT_PG_URL` | PostgreSQL connection URI (required) |
+| `--namespace <ns>` | `OPT_NAMESPACE` | chain namespace, so one database can hold several independent chains (`<ns>_event_chain`, …); omit for bare names |
+| `--verify` | `OPT_VERIFY` | on startup, verify the **entire** chain server-side (`{ verifyChain: true }`) instead of only the root-event canary |
+| `-h`, `--help` | | show help and exit |
+
+Every option may be supplied via its environment variable instead of the flag
+(booleans accept `yes`/`no`), which makes the tool convenient to drive from a
+container or service manager. `--help` lists everything.
+
+The schema is created automatically on first use. Each input **line** is either:
+
+- a **JSON object** → recorded as an event; its `event_id` is printed (hex); or
+- a **slash command**:
+
+  | command | action |
+  |---|---|
+  | `/timestamp` | record a `{ "type": "ts", "ts": … }` event |
+  | `/head` | fetch the chain head (appends an empty checkpoint if needed) |
+  | `/root` | print the chain's root event (id + stored data) |
+  | `/lc [<start> [<end>]]` | list the chain (`getEvents()` slice indices; default = all) |
+  | `/cc` | check chain integrity fully **client-side** (re-hash every event) |
+  | `/export <filename>` | export the chain (minus genesis) to a semicolon CSV |
+  | `/help` | list commands |
+  | `/exit` | quit |
+
+When stdin is a **terminal** it runs as an interactive line editor with command
+history (up/down) and TAB completion; with **piped** input it runs as a plain
+batch processor. A non-object line, malformed JSON, or unknown command prints an
+error and sets a non-zero exit code.
+
+```sh
+# interactive
+tr-json-chain-cli --pg-url postgres://postgres:postgres@localhost:5433/postgres --namespace demo
+
+# batch
+printf '%s\n' '{"type":"user.login","user":42}' '/timestamp' '/cc' \
+  | tr-json-chain-cli --pg-url postgres://postgres:postgres@localhost:5433/postgres --namespace demo
+
+# same, configured entirely from the environment
+export OPT_PG_URL=postgres://postgres:postgres@localhost:5433/postgres OPT_NAMESPACE=demo
+tr-json-chain-cli
+```
+
+By convention every event carries a top-level `"type"` discriminator (the
+chain's own root and timestamp events do); it is not required.
+
+### CSV export format
+
+`/export <file>` writes a semicolon-separated CSV, genesis row excluded, in
+sequence order starting at `#1`:
+
+```
+#;event_id;parent_id;data_hash;data
+```
+
+- `#` — the event's sequence number (`event_chain.id`).
+- `event_id` / `parent_id` / `data_hash` — lowercase hex.
+- `data` — the canonical payload text (exactly the bytes that were hashed),
+  RFC-4180 quoted; empty for events with no stored payload.
+
+This is precisely what `tr-json-chain-check` consumes.
+
+## `tr-json-chain-check`
+
+```
+tr-json-chain-check <file.csv>
+```
+
+A **standalone, self-contained** verifier (only Node builtins — no database, no
+`tr-json-chain` dependency). It re-derives every hash from the spec, so it also
+serves as a compact reference implementation of the chain's integrity rules:
+
+- `data_hash == SHA256(utf8(data))` for every row whose payload is present;
+- `event_id  == SHA256(parent_id ‖ data_hash)` for every row;
+- each `parent_id` equals the previous row's `event_id`, and `#` is contiguous.
+
+It accepts a **partial** chain (a contiguous slice not starting at the root):
+the first row then has `# ≠ 1` and a non-zero `parent_id`, and the summary reads
+`Partial chain OK` instead of `Chain OK`.
+
+The `data` column is optional: if absent, no event carries a payload; an empty
+cell means that event's payload is unavailable.
+
+```
+$ tr-json-chain-check export.csv
+Chain OK: 1502 events verified, payload 1501/1501 (100.0%) present, in 12.3 ms
+```
+
+The `n/m` figure is payloads-present over events that have a real (non-zero)
+`data_hash` — head/checkpoint placeholder events are excluded from the
+denominator. Exit code is `0` on success, `1` on an integrity failure (printed
+as `INVALID: <reason>`), `2` on a usage/IO error.
+
+## See also
+
+- [`tr-json-chain`](https://www.npmjs.com/package/tr-json-chain) — the library these
+  tools operate on, including the full hash specification and the
+  language-agnostic verification algorithm.
+
+## License
+
+MIT

package/bin/tr-json-chain-check.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+
+// tr-json-chain-check — verify the integrity of a tr-json-chain CSV export.
+//
+// Standalone and self-contained: only Node builtins, no database and no
+// tr-json-chain dependency. It reproduces the chain's hashing straight from
+// the spec, so it doubles as a compact reference verifier.
+//
+// Usage: tr-json-chain-check <file.csv>            (filename is mandatory)
+//
+// The CSV is semicolon-separated with header:  #;event_id;parent_id;data_hash[;data]
+//   #          sequence number (event_chain.id), strictly increasing by 1
+//   event_id   hex, must equal SHA256(parent_id || data_hash)
+//   parent_id  hex, must equal the previous row's event_id
+//   data_hash  hex, equals SHA256(utf8(data)) when a payload is present
+//   data       OPTIONAL column: canonical payload text; an empty cell means the
+//              payload for that event is unavailable. If the column is absent
+//              entirely, no event carries a payload.
+//
+// A partial chain (a contiguous slice that does not start at the root) is
+// accepted: the first row then has # != 1 and a non-zero parent_id, and the
+// summary says "Partial chain OK" instead of "Chain OK".
+
+const fs = require('node:fs');
+const { createHash } = require('node:crypto');
+const Optist = require('optist');
+
+const ZERO_HEX = '0'.repeat(64);
+const HEX64 = /^[0-9a-f]{64}$/;
+
+function sha256hex(...bufs) {
+  const h = createHash('sha256');
+  for (const b of bufs) h.update(b);
+  return h.digest('hex');
+}
+
+// RFC-4180 CSV parser: ';' delimiter, '"'-quoted fields with '""' escaping.
+// Returns an array of field arrays; blank lines are dropped.
+function parseCSV(text, delim = ';') {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let sawAny = false; // any content/structure on the current line
+  const endField = () => { row.push(field); field = ''; };
+  const endRow = () => { endField(); rows.push(row); row = []; sawAny = false; };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; } else inQuotes = false;
+      } else {
+        field += c;
+      }
+      continue;
+    }
+    if (c === '"') { inQuotes = true; sawAny = true; }
+    else if (c === delim) { endField(); sawAny = true; }
+    else if (c === '\n') { endRow(); }
+    else if (c === '\r') { /* ignore */ }
+    else { field += c; sawAny = true; }
+  }
+  if (sawAny || field !== '' || row.length) endRow();
+  // Drop blank lines (a single empty field).
+  return rows.filter((r) => !(r.length === 1 && r[0] === ''));
+}
+
+function fail(msg) {
+  console.error(`INVALID: ${msg}`);
+  process.exit(1);
+}
+
+function main() {
+  const opt = new Optist()
+    .help('tr-json-chain-check')
+    .additional(1, 1)
+    .describeParam(0, 'file.csv', 'the CSV export to verify')
+    .parse();
+  const file = opt.rest()[0];
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.error(`error: cannot read ${file}: ${err.message}`);
+    return 2;
+  }
+
+  const rows = parseCSV(text);
+  if (rows.length === 0) fail('empty file (no header)');
+
+  const header = rows.shift();
+  const required = ['#', 'event_id', 'parent_id', 'data_hash'];
+  const validHeader =
+    (header.length === 4 && required.every((c, i) => header[i] === c)) ||
+    (header.length === 5 && required.every((c, i) => header[i] === c) && header[4] === 'data');
+  if (!validHeader) {
+    fail(`bad header: expected "#;event_id;parent_id;data_hash[;data]", got "${header.join(';')}"`);
+  }
+  const hasDataColumn = header.length === 5;
+  if (rows.length === 0) fail('no event rows');
+
+  const t0 = process.hrtime.bigint();
+  let prevNum = null;
+  let prevEventId = null;
+  let payloadPresent = 0; // n
+  let realEvents = 0;     // m: rows with data_hash != all-zeros
+  let partial = false;
+
+  for (let r = 0; r < rows.length; r++) {
+    const f = rows[r];
+    const at = `row ${r + 2}`; // +2: 1-based, and the header was row 1
+    if (f.length < 4) fail(`${at}: too few columns (${f.length})`);
+    const numStr = f[0];
+    const eventId = f[1];
+    const parentId = f[2];
+    const dataHash = f[3];
+    const data = hasDataColumn ? (f[4] ?? '') : '';
+
+    if (!/^\d+$/.test(numStr)) fail(`${at}: # is not a non-negative integer ("${numStr}")`);
+    const num = Number(numStr);
+    if (!HEX64.test(eventId)) fail(`${at}: event_id is not 64 lowercase hex chars`);
+    if (!HEX64.test(parentId)) fail(`${at}: parent_id is not 64 lowercase hex chars`);
+    if (!HEX64.test(dataHash)) fail(`${at}: data_hash is not 64 lowercase hex chars`);
+
+    if (r === 0) {
+      if (num === 1) {
+        if (parentId !== ZERO_HEX) fail(`${at}: root event (#=1) must have an all-zero parent_id`);
+      } else {
+        if (parentId === ZERO_HEX) {
+          fail(`${at}: a non-root start (#=${num}) must not have an all-zero parent_id`);
+        }
+        partial = true;
+      }
+    } else {
+      if (num !== prevNum + 1) {
+        fail(`${at}: # jumped from ${prevNum} to ${num} (the chain must be contiguous)`);
+      }
+      if (parentId !== prevEventId) fail(`${at} (#${num}): parent_id does not match the previous event_id`);
+    }
+
+    // Payload hashing: when present, data must hash to data_hash.
+    if (data !== '') {
+      if (sha256hex(Buffer.from(data, 'utf8')) !== dataHash) {
+        fail(`${at} (#${num}): data does not hash to data_hash`);
+      }
+      payloadPresent++;
+    }
+
+    // Every row: event_id == SHA256(parent_id || data_hash).
+    if (sha256hex(Buffer.from(parentId, 'hex'), Buffer.from(dataHash, 'hex')) !== eventId) {
+      fail(`${at} (#${num}): event_id != SHA256(parent_id || data_hash)`);
+    }
+
+    if (dataHash !== ZERO_HEX) realEvents++;
+
+    prevNum = num;
+    prevEventId = eventId;
+  }
+
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+  const pct = realEvents === 0 ? 'n/a' : `${((100 * payloadPresent) / realEvents).toFixed(1)}%`;
+  const label = partial ? 'Partial chain OK' : 'Chain OK';
+  console.log(
+    `${label}: ${rows.length} events verified, ` +
+      `payload ${payloadPresent}/${realEvents} (${pct}) present, in ${ms.toFixed(1)} ms`,
+  );
+  return 0;
+}
+
+process.exitCode = main();

package/bin/tr-json-chain-cli.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+'use strict';
+
+// tr-json-chain-cli — a CLI for recording into and inspecting a tr-json-chain.
+//
+// Reads stdin line by line. Each line is either a JSON object (recorded to
+// the chain) or a slash command; in both cases the resulting event id is
+// printed (hex). When stdin is a TTY it runs as an interactive line editor
+// with in-memory history (up/down) and TAB completion; with piped input it
+// runs as a plain batch processor.
+//
+// Commands:
+//   /timestamp           record a timestamp event (logger.timestamp())
+//   /head                fetch the chain head (may append an empty checkpoint event)
+//   /root                fetch the chain root event (prints its id and stored data)
+//   /lc [<start> [<end>]] list the chain (getEvents() slice indices; default all)
+//   /cc                  check chain integrity (full client-side hash verification)
+//   /export <filename>   export the chain (minus genesis) to a semicolon CSV
+//   /help                show this help
+//   /exit                quit
+//
+// Usage: tr-json-chain-cli [--verify] <postgres-url> [namespace]
+//   e.g. tr-json-chain-cli postgres://postgres:postgres@localhost:5433/postgres demo
+//   --verify passes { verifyChain: true } to the constructor, so init() does a
+//   full server-side verification of the entire chain instead of just the root.
+
+const readline = require('node:readline');
+const fs = require('node:fs');
+const { createHash } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const Optist = require('optist');
+const { Pool } = require('pg');
+const { EventChainLogger, EventChainCsvExport } = require('tr-json-chain');
+
+const ZERO_HEX = '00'.repeat(32);
+
+// SHA-256 over the concatenation of the given buffers, returned as lowercase
+// hex — matching PostgreSQL's encode(sha256(...), 'hex').
+function sha256hex(...bufs) {
+  const h = createHash('sha256');
+  for (const b of bufs) h.update(b);
+  return h.digest('hex');
+}
+
+const COMMANDS = {
+  '/timestamp': 'record a timestamp event',
+  '/head': 'fetch the chain head (may append an empty checkpoint event)',
+  '/root': 'fetch the chain root event (id + stored data)',
+  '/lc': 'list the chain: /lc [<start> [<end>]] (getEvents slice indices)',
+  '/cc': 'check chain: full client-side hash verification',
+  '/export': 'export the chain to a semicolon-CSV file: /export <filename>',
+  '/help': 'show this help',
+  '/exit': 'quit',
+};
+const COMMAND_NAMES = Object.keys(COMMANDS);
+const PROMPT = 'tr-json-chain> ';
+
+// Pure TAB-completion logic, independent of readline so it can be unit-tested.
+// Returns either { completions, completeOn } (real completions readline should
+// insert/list) or { message } (an informational line to show the user).
+function analyzeCompletion(line) {
+  const trimmed = line.trim();
+
+  if (trimmed === '') {
+    return {
+      message:
+        `Commands: ${COMMAND_NAMES.join(' ')}\n` +
+        '  or enter a JSON object, e.g. {"key":"value"}',
+    };
+  }
+
+  if (trimmed.startsWith('/')) {
+    const parts = trimmed.split(/\s+/);
+    const cmd = parts[0];
+    // Past the command word (a space typed) we're into arguments, not names.
+    if (parts.length > 1 || /\s$/.test(line)) {
+      return COMMAND_NAMES.includes(cmd)
+        ? { message: `${cmd} — ${COMMANDS[cmd]}` }
+        : { message: `No such command: ${cmd}` };
+    }
+    const hits = COMMAND_NAMES.filter((c) => c.startsWith(cmd));
+    if (hits.length === 0) {
+      return { message: `No such command. Available: ${COMMAND_NAMES.join(' ')}` };
+    }
+    return { completions: hits, completeOn: cmd };
+  }
+
+  if (trimmed.startsWith('{')) {
+    try {
+      JSON.parse(trimmed); // starts with { → success implies an object
+      return { message: 'Valid JSON object — press ENTER to commit it to the chain.' };
+    } catch {
+      return { message: 'JSON object is invalid or incomplete.' };
+    }
+  }
+
+  return {
+    message:
+      'Invalid input — enter a JSON object {…} or a /command ' +
+      '(TAB on an empty line for help).',
+  };
+}
+
+// Generic one-line rendering of a chain event ({ event_id, data? }):
+//   <event-id>: { <data> }   when a payload is stored
+//   <event-id>: -            when no payload is available
+// event_id is always a hex string in the 0.9.0+ API.
+function formatEvent({ event_id, data }) {
+  return data === undefined ? `${event_id}: -` : `${event_id}: ${JSON.stringify(data)}`;
+}
+
+function helpText() {
+  return [
+    'Enter a JSON object to record it to the chain, or one of:',
+    ...COMMAND_NAMES.map((name) => `  ${name.padEnd(11)}${COMMANDS[name]}`),
+  ].join('\n');
+}
+
+// Lists a (possibly large) slice of the chain. Arguments mirror getEvents():
+//   /lc                -> the whole chain
+//   /lc <start>        -> from index <start> onwards
+//   /lc <start> <end>  -> the [start, end) range
+// getEvents() caps each call at 1000 events; this iterates internally over
+// have_more so the caller sees the entire requested range, one event per line.
+async function listChain(logger, args) {
+  if (args.length > 2) {
+    console.error('usage: /lc [<start> [<end>]]');
+    return { ok: false };
+  }
+  const parseIdx = (tok) => {
+    const n = Number(tok);
+    return Number.isInteger(n) ? n : null;
+  };
+  let start = 0;
+  let end; // undefined => to the end (getEvents default)
+  if (args.length >= 1) {
+    start = parseIdx(args[0]);
+    if (start === null) {
+      console.error('error: start must be an integer');
+      return { ok: false };
+    }
+  }
+  if (args.length >= 2) {
+    end = parseIdx(args[1]);
+    if (end === null) {
+      console.error('error: end must be an integer');
+      return { ok: false };
+    }
+  }
+
+  for (let from = start; ; ) {
+    const page = end === undefined
+      ? await logger.getEvents(from)
+      : await logger.getEvents(from, end);
+    for (const ev of page.events) console.log(formatEvent(ev));
+    if (!page.have_more) break;
+    from = page.end + 1;
+  }
+  return { ok: true };
+}
+
+// Verifies a single event from getEvents() (with includeHashedData /
+// includeDataHash / includeParentId) against the hash-chain rules. `index` is
+// its position (0 = genesis), `prevEventId` the hex event_id of the previous
+// event (null before genesis). Throws Error with a precise reason on any
+// inconsistency.
+function verifyEvent(ev, index, prevEventId) {
+  const at = `event #${index} (${ev.event_id})`;
+
+  if (index === 0) {
+    // Genesis: all-zero data_hash and event_id, and no parent.
+    if (ev.event_id !== ZERO_HEX) throw new Error(`${at}: genesis event_id is not all-zero`);
+    if (ev.data_hash !== ZERO_HEX) throw new Error(`${at}: genesis data_hash is not all-zero`);
+    if (ev.parent_id !== undefined) throw new Error(`${at}: genesis must have no parent_id`);
+    return;
+  }
+
+  // Link: this event's parent must be the previous event's id.
+  if (ev.parent_id === undefined) throw new Error(`${at}: missing parent_id`);
+  if (ev.parent_id !== prevEventId) {
+    throw new Error(`${at}: parent_id ${ev.parent_id} != previous event_id ${prevEventId}`);
+  }
+
+  // data_hash = SHA256(UTF-8 of jsonb::text). Only recomputable when the
+  // payload was stored (hashed_data present); empty / payload-less events keep
+  // a data_hash we cannot independently recompute, but still bind the event_id.
+  if (ev.hashed_data !== undefined) {
+    const dh = sha256hex(Buffer.from(ev.hashed_data, 'utf8'));
+    if (dh !== ev.data_hash) {
+      throw new Error(`${at}: data_hash mismatch (computed ${dh}, returned ${ev.data_hash})`);
+    }
+    // The hashed text must decode to the same object as the returned `data`.
+    if (!isDeepStrictEqual(JSON.parse(ev.hashed_data), ev.data)) {
+      throw new Error(`${at}: hashed_data does not decode to the returned data`);
+    }
+  }
+
+  // event_id = SHA256(parent_event_id || data_hash), raw 32-byte concatenation.
+  const eid = sha256hex(Buffer.from(ev.parent_id, 'hex'), Buffer.from(ev.data_hash, 'hex'));
+  if (eid !== ev.event_id) {
+    throw new Error(`${at}: event_id mismatch (computed ${eid}, returned ${ev.event_id})`);
+  }
+}
+
+// Full client-side integrity check of the entire chain: iterates every event
+// (paginating internally), re-derives data_hash and event_id with node:crypto,
+// and verifies every parent link. Prints chain length and elapsed time, or the
+// first inconsistency found. The point is to confirm — independently of the
+// database — that the chain verifies and that this client hashes compatibly.
+async function checkChain(logger, args) {
+  if (args.length > 0) {
+    console.error('usage: /cc');
+    return { ok: false };
+  }
+  const opts = { includeHashedData: true, includeDataHash: true, includeParentId: true };
+  const t0 = process.hrtime.bigint();
+  let count = 0;
+  let payloadVerified = 0;
+  let prevEventId = null;
+  try {
+    for (let from = 0; ; ) {
+      const page = await logger.getEvents(from, opts);
+      for (const ev of page.events) {
+        verifyEvent(ev, count, prevEventId);
+        if (ev.hashed_data !== undefined) payloadVerified++;
+        prevEventId = ev.event_id;
+        count++;
+      }
+      if (!page.have_more) break;
+      from = page.end + 1;
+    }
+  } catch (err) {
+    console.error(`CHAIN VERIFICATION FAILED: ${err.message}`);
+    return { ok: false };
+  }
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+  console.log(
+    `Chain OK: ${count} events verified ` +
+      `(${payloadVerified} payload hashes recomputed) in ${ms.toFixed(1)} ms`,
+  );
+  return { ok: true };
+}
+
+// Exports the chain (excluding the genesis row) to a semicolon-separated CSV:
+//   #;event_id;parent_id;data_hash;data
+// The format is owned by the library: EventChainCsvExport renders the header and
+// each row (RFC-4180 quoting, `#` = event_chain.id, empty `data` cell for events
+// with no stored payload). We just fetch every column and stream the lines.
+async function exportChain(logger, args) {
+  const filename = args.join(' ');
+  if (!filename) {
+    console.error('usage: /export <filename>');
+    return { ok: false };
+  }
+  const opts = { includeHashedData: true, includeDataHash: true, includeParentId: true };
+  const enc = new EventChainCsvExport();
+  let fd;
+  try {
+    fd = fs.openSync(filename, 'w');
+  } catch (err) {
+    console.error(`error: cannot open ${filename}: ${err.message}`);
+    return { ok: false };
+  }
+  let count = 0;
+  try {
+    fs.writeSync(fd, enc.header() + '\n');
+    for (let from = 1; ; ) {
+      // Start at index 1 to skip the genesis row (index 0).
+      const page = await logger.getEvents(from, opts);
+      for (const ev of page.events) {
+        fs.writeSync(fd, enc.event(ev) + '\n');
+        count++;
+      }
+      if (!page.have_more) break;
+      from = page.end + 1;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  console.log(`exported ${count} events to ${filename}`);
+  return { ok: true };
+}
+
+// Handles a single input line against the chain. Returns { ok, exit }.
+// Printing of event ids / data happens here so both modes behave identically.
+async function handleLine(logger, line) {
+  const trimmed = line.trim();
+  if (trimmed === '') return { ok: true };
+
+  if (trimmed.startsWith('/')) {
+    const [cmd, ...rest] = trimmed.split(/\s+/);
+    switch (cmd) {
+      case '/exit':
+        return { ok: true, exit: true };
+      case '/help':
+        console.log(helpText());
+        return { ok: true };
+      case '/timestamp':
+        console.log(await logger.timestamp());
+        return { ok: true };
+      case '/head':
+        console.log(await logger.getChainHead());
+        return { ok: true };
+      case '/root':
+        console.log(formatEvent(await logger.getRootEvent()));
+        return { ok: true };
+      case '/lc':
+        return listChain(logger, rest);
+      case '/cc':
+        return checkChain(logger, rest);
+      case '/export':
+        return exportChain(logger, rest);
+      default:
+        console.error(`error: unknown command: ${cmd}`);
+        return { ok: false };
+    }
+  }
+
+  let data;
+  try {
+    data = JSON.parse(line);
+  } catch (err) {
+    console.error(`error: invalid JSON: ${err.message}`);
+    return { ok: false };
+  }
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    console.error('error: expected a JSON object');
+    return { ok: false };
+  }
+  console.log(await logger.recordEvent(data));
+  return { ok: true };
+}
+
+async function runInteractive(logger) {
+  let rl;
+  const notify = (message) => {
+    process.stdout.write(`\n${message}\n`);
+    rl.prompt(true); // redraw prompt + current line buffer
+  };
+  const completer = (line) => {
+    const res = analyzeCompletion(line);
+    if (res.completions) return [res.completions, res.completeOn];
+    notify(res.message);
+    return [[], line];
+  };
+
+  rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+    completer,
+    prompt: PROMPT,
+    historySize: 100, // in-memory only; not persisted
+  });
+
+  console.log('Interactive mode — TAB for help, /exit to quit.');
+  let failures = 0;
+  let exited = false;
+  rl.prompt();
+  for await (const line of rl) {
+    let res;
+    try {
+      res = await handleLine(logger, line);
+    } catch (err) {
+      console.error(`error: ${err.message}`);
+      res = { ok: false };
+    }
+    if (!res.ok) failures++;
+    if (res.exit) {
+      exited = true;
+      break;
+    }
+    rl.prompt();
+  }
+  // On EOF (Ctrl-D) readline closes without echoing a newline, which would
+  // leave the shell prompt on the same line as ours; emit one. After /exit
+  // the committed ENTER already moved to a fresh line, so skip it there.
+  if (!exited) process.stdout.write('\n');
+  rl.close();
+  return failures ? 1 : 0;
+}
+
+async function runBatch(logger) {
+  let failures = 0;
+  const rl = readline.createInterface({ input: process.stdin });
+  for await (const line of rl) {
+    const res = await handleLine(logger, line);
+    if (!res.ok) failures++;
+    if (res.exit) break;
+  }
+  return failures ? 1 : 0;
+}
+
+async function main() {
+  const opt = new Optist()
+    .opts([
+      {
+        longName: 'pg-url',
+        description: 'PostgreSQL connection URI',
+        hasArg: true,
+        required: true,
+        environment: 'OPT_PG_URL',
+      },
+      {
+        longName: 'namespace',
+        description: 'chain namespace (default: unprefixed bare names)',
+        hasArg: true,
+        environment: 'OPT_NAMESPACE',
+      },
+      {
+        longName: 'verify',
+        description: 'verify the entire chain server-side on startup',
+        environment: 'OPT_VERIFY',
+      },
+    ])
+    .help('tr-json-chain-cli')
+    .additional(0, 0)
+    .parse();
+
+  const url = opt.value('pg-url');
+  const namespace = opt.value('namespace');
+
+  const options = {};
+  if (namespace) options.namespace = namespace;
+  if (opt.value('verify')) options.verifyChain = true;
+
+  const pool = new Pool({ connectionString: url });
+  try {
+    const logger = new EventChainLogger(pool, options);
+    await logger.init(); // fail fast on bad creds / namespace / schema (full chain if --verify)
+    // Must await here: a bare `return <promise>` would let the finally below
+    // close the pool before the loop finishes.
+    return process.stdin.isTTY ? await runInteractive(logger) : await runBatch(logger);
+  } finally {
+    await pool.end();
+  }
+}
+
+if (require.main === module) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (err) => { console.error(`fatal: ${err.message}`); process.exitCode = 1; },
+  );
+}
+
+module.exports = {
+  analyzeCompletion, helpText, handleLine, formatEvent, listChain,
+  verifyEvent, checkChain, exportChain, sha256hex, COMMAND_NAMES,
+};

package/dc/docker-compose.yml

@@ -0,0 +1,11 @@
+# Optional PostgreSQL for trying out tr-json-chain-tools:
+#   docker compose -f dc/docker-compose.yml up -d
+#   echo '{"type":"hello","msg":"world"}' | \
+#     tr-json-chain-cli --pg-url postgres://postgres:postgres@localhost:5433/postgres --namespace demo
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5433:5432"

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "tr-json-chain-tools",
+    "version": "0.3.0",
+    "description": "Command-line tools for tr-json-chain: a CLI to record into and inspect a hash-chained JSON event log, and a standalone CSV-export integrity verifier.",
+    "keywords": [
+        "tr-json-chain",
+        "audit-log",
+        "hash-chain",
+        "cli",
+        "tamper-evident",
+        "postgresql",
+        "integrity"
+    ],
+    "bin": {
+        "tr-json-chain-cli": "bin/tr-json-chain-cli.js",
+        "tr-json-chain-check": "bin/tr-json-chain-check.js"
+    },
+    "files": [
+        "bin",
+        "dc/docker-compose.yml",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "optist": "^2.0.1",
+        "pg": "^8.11.0",
+        "tr-json-chain": "^0.9.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rinne/node-tr-json-chain-tools.git"
+    },
+    "author": {
+        "name": "Timo J. Rinne",
+        "email": "tri@iki.fi",
+        "url": "https://github.com/rinne/"
+    },
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/rinne/node-tr-json-chain-tools/issues"
+    },
+    "homepage": "https://github.com/rinne/node-tr-json-chain-tools#readme"
+}