From df32ce465a54923a3347f7858c51a6c2fa8d7d8c Mon Sep 17 00:00:00 2001
From: Monserrat Mendoza <210256392+M0nsxx@users.noreply.github.com>
Date: Sat, 7 Nov 2026 10:51:27 -0600
Subject: [PATCH] feat(cli): nirium anchor - anchor a hash or small record to
 IPFS

Adds `nirium anchor --file|--hash|--record` against the Audit Trail
node's POST /api/audit/log. --file computes sha-256 locally and sends
only the hash, never the file content. --record mirrors the server's
8KB limit client-side. No --network flag: the agent box decides its own
network, and the server already rejects a client-supplied one.

17 new tests against a local HTTP server standing in for the agent (no
real network, no real IPFS pin), full suite 76/76.

Closes #133

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 packages/cli/CHANGELOG.md        |   4 +
 packages/cli/README.md           |  40 ++++++
 packages/cli/bin/nirium.js       | 140 ++++++++++++++++++++
 packages/cli/package.json        |   2 +-
 packages/cli/test/anchor.test.js | 215 +++++++++++++++++++++++++++++++
 5 files changed, 400 insertions(+), 1 deletion(-)
 create mode 100644 packages/cli/test/anchor.test.js

diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
index 3b07e19..e1dfe84 100644
--- a/packages/cli/CHANGELOG.md
+++ b/packages/cli/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to the `nirium-cli` package are documented here.
 
 ## Unreleased
 
+### Added
+
+- `nirium anchor` ([#133](https://github.com/nirium-protocol/nirium/issues/133)): anchors a sha-256 hash (`--hash`), a file's sha-256 (`--file`, the file itself is never uploaded), or a small JSON record (`--record`, max 8KB, enforced client-side) to IPFS via an Audit Trail node's `POST /api/audit/log`. Optional `--tx`/`--tag`; no `--network` flag by design - the agent box decides its own network. Prints the CID, content hash, gateway URL, and a `nirium verify` suggestion.
+
 ## 3.0.1 - 2026-10-24
 
 ### Fixed
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 0db7131..58aa02a 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -202,6 +202,46 @@ Each line is pass or fail:
 
 `--json` prints the same report (`ok`, `seller`, `network`, `checks`) for CI.
 
+## Anchor a record
+
+```bash
+nirium anchor --file evidence.json
+nirium anchor --hash <64-hex-sha256>
+nirium anchor --record '{"order":"A-12"}'
+```
+
+Anchors a sha-256 hash (or a small JSON object, up to 8KB) to IPFS via an
+Audit Trail node's `POST /api/audit/log`, and prints back the CID.
+
+- `--file <path>` computes the sha-256 of the file locally and sends only
+  the hash - the file's contents are never uploaded. IPFS cannot delete
+  anything once pinned, so hashing locally means raw evidence never
+  leaves your machine.
+- `--hash <hex>` sends a sha-256 you already have (64 hex chars, optional
+  `sha-256:` prefix).
+- `--record <json>` anchors a small JSON object verbatim (max 8KB,
+  enforced here before the request, not just by the server). Don't put
+  personal data in it - an anchored record can never be deleted.
+
+Exactly one of the three is required. `--tx <hash>` and `--tag <label>`
+are optional and attached to the anchor as-is. There is no `--network`
+flag: the agent box anchoring the record decides its own network, and a
+client-supplied network field is rejected server-side anyway.
+
+| Option | Purpose | Default |
+|---|---|---|
+| `--file <path>` | anchor this file's sha-256 | none |
+| `--hash <hex>` | anchor this sha-256 directly | none |
+| `--record <json>` | anchor this small JSON object verbatim | none |
+| `--tx <hash>` | associate a transaction hash | none |
+| `--tag <label>` | free-form label | none |
+| `-u, --url <url>` | agent URL | `http://localhost:3002` |
+| `--json` | machine-readable result | off |
+
+On success, prints the CID, the content hash, the gateway URL, and a
+`nirium verify <cid>` suggestion so the anchor can be independently
+re-checked right away.
+
 ## Verify an audit record
 
 ```bash
diff --git a/packages/cli/bin/nirium.js b/packages/cli/bin/nirium.js
index da04530..49d255f 100755
--- a/packages/cli/bin/nirium.js
+++ b/packages/cli/bin/nirium.js
@@ -188,6 +188,21 @@ program
         }
     });
 
+// --- COMMAND: anchor ---
+program
+    .command('anchor')
+    .description('Anchor a sha-256 hash (or a small JSON record) to IPFS via an Audit Trail node')
+    .option('--file <path>', 'Anchor the sha-256 of this file - the file itself is never uploaded')
+    .option('--hash <hex>', 'sha-256 hex of your evidence (64 chars, optional sha-256: prefix)')
+    .option('--record <json>', 'Small JSON object (max 8KB) to anchor verbatim, e.g. \'{"order":"A-12"}\'')
+    .option('--tx <hash>', 'Transaction hash to associate with this anchor')
+    .option('--tag <tag>', 'Free-form label for this anchor')
+    .option('-u, --url <url>', 'Agent URL', 'http://localhost:3002')
+    .option('--json', 'Output result as JSON')
+    .action(async (options) => {
+        await executeAnchorCommand(options);
+    });
+
 // --- COMMAND: doctor ---
 program
     .command('doctor')
@@ -1650,4 +1665,129 @@ function formatVerifyOutput(result) {
     return lines.join('\n');
 }
 
+// ═══════════════════════════════════════════════════════════════
+// anchor — anchor a hash or small record to IPFS via the Audit Trail node
+// ═══════════════════════════════════════════════════════════════
+
+const ANCHOR_MAX_RECORD_BYTES = 8 * 1024;
+
+// `nirium anchor` deliberately has no `--network` flag: the agent box
+// decides its own network (STELLAR_NETWORK) and the server already
+// rejects a `network` field in the body. A client-side flag here would
+// only ever be ignored, which is worse than not having it.
+async function executeAnchorCommand(options) {
+    const fail = (error, hint) => {
+        if (options.json) {
+            console.log(JSON.stringify({ ok: false, error, ...(hint ? { hint } : {}) }));
+        } else {
+            console.error(`❌ Error: ${error}${hint ? `\n   ${hint}` : ''}`);
+        }
+        process.exit(1);
+    };
+
+    const given = ['file', 'hash', 'record'].filter((k) => options[k] !== undefined);
+    if (given.length === 0) {
+        fail('Provide exactly one of --file, --hash, or --record.');
+        return;
+    }
+    if (given.length > 1) {
+        fail(`--${given[0]} and --${given[1]} were both given - use exactly one.`);
+        return;
+    }
+
+    const body = {};
+    if (options.file !== undefined) {
+        let fileBuf;
+        try {
+            fileBuf = fs.readFileSync(options.file);
+        } catch (err) {
+            fail(`Could not read --file '${options.file}': ${err?.message || String(err)}`);
+            return;
+        }
+        body.hash = crypto.createHash('sha256').update(fileBuf).digest('hex');
+    } else if (options.hash !== undefined) {
+        try {
+            body.hash = normalizeHashInput(options.hash);
+        } catch (err) {
+            fail(err.message);
+            return;
+        }
+    } else {
+        let record;
+        try {
+            record = JSON.parse(options.record);
+        } catch (err) {
+            fail(`--record is not valid JSON: ${err?.message || String(err)}`);
+            return;
+        }
+        if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+            fail('--record must be a JSON object, e.g. \'{"order":"A-12"}\'');
+            return;
+        }
+        // Mirrors the server's own 8KB limit (MAX_RECORD_BYTES in
+        // auditRoutes.ts) so an oversized record fails locally, before any
+        // network call, instead of round-tripping for a 413.
+        const raw = JSON.stringify(record);
+        if (Buffer.byteLength(raw, 'utf8') > ANCHOR_MAX_RECORD_BYTES) {
+            fail(`--record exceeds ${ANCHOR_MAX_RECORD_BYTES / 1024}KB - anchor a sha-256 hash instead (--hash or --file).`);
+            return;
+        }
+        body.record = record;
+    }
+
+    if (options.tx !== undefined) body.txHash = options.tx;
+    if (options.tag !== undefined) body.tag = options.tag;
+
+    const agentAttestation = await maybeBuildAgentAttestation(options, body, fail);
+    if (agentAttestation === 'failed') return; // fail() already called and exited
+    if (agentAttestation) body.agent = agentAttestation;
+
+    let response;
+    try {
+        response = await fetch(`${options.url}/api/audit/log`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(20_000),
+        });
+    } catch (err) {
+        const msg = (err?.name === 'TimeoutError' || err?.name === 'AbortError')
+            ? `Timed out waiting for ${options.url}/api/audit/log`
+            : `Agent unreachable at ${options.url}: ${err?.message || String(err)}`;
+        fail(msg);
+        return;
+    }
+
+    let data = null;
+    try {
+        data = await response.json();
+    } catch { /* empty or non-JSON body */ }
+
+    if (!response.ok) {
+        fail(data?.error || `Agent returned HTTP ${response.status}`, data?.sign ? `Sign this statement instead: ${data.sign}` : undefined);
+        return;
+    }
+
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+        return;
+    }
+
+    console.log('✅ Anchored to IPFS');
+    console.log(`   CID:            ${data.cid}`);
+    console.log(`   Content sha256: ${data.content_sha256}`);
+    if (data.gatewayUrl) console.log(`   Gateway URL:    ${data.gatewayUrl}`);
+    if (data.attestedBy) console.log(`   Attested by:    ${data.attestedBy}`);
+    console.log(`   Anchored at:    ${data.anchoredAt}`);
+    console.log(`\n   Verify independently: nirium verify ${data.cid}`);
+}
+
+// Returns the `agent` object for the request body, `undefined` when
+// `--sign` was not passed, or the string 'failed' when fail() already
+// ran (caller must return without doing anything else — placeholder for
+// #134, which adds `--sign`/`--key-env` on top of this command).
+async function maybeBuildAgentAttestation(_options, _body, _fail) {
+    return undefined;
+}
+
 program.parse();
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 361fc58..8282a9f 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "prepublishOnly": "node --check bin/nirium.js",
-    "test": "node --test test/doctor-seller.test.js test/config-secret.test.js test/serve-api-key.test.js test/verify-hash-only.test.js test/pay-agent-construction.test.js test/pay-status-and-cap.test.js test/status.test.js"
+    "test": "node --test test/doctor-seller.test.js test/config-secret.test.js test/serve-api-key.test.js test/verify-hash-only.test.js test/pay-agent-construction.test.js test/pay-status-and-cap.test.js test/status.test.js test/anchor.test.js"
   },
   "keywords": [
     "stellar",
diff --git a/packages/cli/test/anchor.test.js b/packages/cli/test/anchor.test.js
new file mode 100644
index 0000000..3e6a35d
--- /dev/null
+++ b/packages/cli/test/anchor.test.js
@@ -0,0 +1,215 @@
+/**
+ * `nirium anchor` (#133): --file / --hash / --record against a local
+ * HTTP server standing in for the Audit Trail node's POST /api/audit/log.
+ * No real network, no real IPFS pin.
+ */
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+const cliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cli = path.join(cliRoot, 'bin/nirium.js');
+
+let lastRequest = null;
+let scenario = 'ok';
+const server = http.createServer((req, res) => {
+    let chunks = [];
+    req.on('data', (d) => chunks.push(d));
+    req.on('end', () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { body = null; }
+        lastRequest = { method: req.method, url: req.url, body };
+
+        if (scenario === 'bad-request') {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: '`hash` must be a 64-char sha-256 hex, optionally prefixed "sha-256:"' }));
+            return;
+        }
+        if (scenario === 'unavailable') {
+            res.writeHead(503, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'anchoring temporarily unavailable - try again shortly' }));
+            return;
+        }
+        const contentSha = body?.hash
+            ? String(body.hash).toLowerCase().replace(/^sha-?256:/, '')
+            : crypto.createHash('sha256').update(JSON.stringify(body?.record ?? {})).digest('hex');
+        res.writeHead(201, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({
+            cid: 'QmFakeCidForTests1234567890',
+            gatewayUrl: 'https://gateway.pinata.cloud/ipfs/QmFakeCidForTests1234567890',
+            content_sha256: contentSha,
+            anchoredAt: '2026-11-08T00:00:00.000Z',
+            verify: 'fetch the gatewayUrl and recompute sha-256 over your original evidence',
+        }));
+    });
+});
+
+server.listen(0, '127.0.0.1');
+await once(server, 'listening');
+const base = `http://127.0.0.1:${server.address().port}`;
+
+test.after(() => new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+}));
+
+test.beforeEach(() => { scenario = 'ok'; lastRequest = null; });
+
+function run(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cli, 'anchor', '--url', base, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('timed out')); }, 10_000);
+        child.stdout.on('data', (d) => { stdout += d; });
+        child.stderr.on('data', (d) => { stderr += d; });
+        child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+        child.on('error', reject);
+    });
+}
+
+const HASH = 'f'.repeat(64);
+
+test('--hash anchors the raw hash, no network re-validation of format beyond the server', async () => {
+    const r = await run(['--hash', HASH, '--json']);
+    assert.equal(r.code, 0, r.stdout + r.stderr);
+    const json = JSON.parse(r.stdout);
+    assert.equal(json.ok, true);
+    assert.equal(json.cid, 'QmFakeCidForTests1234567890');
+    assert.equal(json.content_sha256, HASH);
+    assert.equal(lastRequest.body.hash, HASH);
+    assert.equal(lastRequest.body.record, undefined);
+});
+
+test('--hash accepts the sha-256: prefix and uppercase, normalized before sending', async () => {
+    const r = await run(['--hash', `sha-256:${HASH.toUpperCase()}`, '--json']);
+    assert.equal(r.code, 0, r.stdout + r.stderr);
+    assert.equal(lastRequest.body.hash, HASH);
+});
+
+test('invalid --hash is refused locally, never reaches the network', async () => {
+    const r = await run(['--hash', 'not-a-hash']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /Invalid sha-256 hash/);
+    assert.equal(lastRequest, null);
+});
+
+test('--file computes sha-256 locally and sends only the hash, never the file content', async () => {
+    const file = path.join(os.tmpdir(), `nirium-anchor-test-${process.pid}.txt`);
+    fs.writeFileSync(file, 'evidence contents\n');
+    const expected = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    try {
+        const r = await run(['--file', file, '--json']);
+        assert.equal(r.code, 0, r.stdout + r.stderr);
+        assert.equal(lastRequest.body.hash, expected);
+        assert.equal(JSON.stringify(lastRequest.body).includes('evidence contents'), false);
+    } finally {
+        fs.rmSync(file, { force: true });
+    }
+});
+
+test('missing --file is reported clearly, never reaches the network', async () => {
+    const r = await run(['--file', '/nonexistent/path/evidence.json']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /Could not read --file/);
+    assert.equal(lastRequest, null);
+});
+
+test('--record sends the object verbatim', async () => {
+    const r = await run(['--record', '{"order":"A-12"}', '--json']);
+    assert.equal(r.code, 0, r.stdout + r.stderr);
+    assert.deepEqual(lastRequest.body.record, { order: 'A-12' });
+    assert.equal(lastRequest.body.hash, undefined);
+});
+
+test('invalid JSON in --record is refused locally', async () => {
+    const r = await run(['--record', 'not json']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /not valid JSON/);
+    assert.equal(lastRequest, null);
+});
+
+test('--record over 8KB is refused locally, mirroring the server limit', async () => {
+    const big = JSON.stringify({ blob: 'x'.repeat(9000) });
+    const r = await run(['--record', big]);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /exceeds 8KB/);
+    assert.equal(lastRequest, null);
+});
+
+test('--record that is a JSON array is rejected (must be an object)', async () => {
+    const r = await run(['--record', '[1,2,3]']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /must be a JSON object/);
+});
+
+test('exactly one of --file/--hash/--record is required - none given', async () => {
+    const r = await run([]);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /exactly one of --file, --hash, or --record/);
+});
+
+test('exactly one of --file/--hash/--record is required - two given', async () => {
+    const r = await run(['--hash', HASH, '--record', '{}']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /were both given/);
+    assert.equal(lastRequest, null);
+});
+
+test('--tx and --tag are forwarded in the request body', async () => {
+    const r = await run(['--hash', HASH, '--tx', 'abc123', '--tag', 'order-A-12', '--json']);
+    assert.equal(r.code, 0, r.stdout + r.stderr);
+    assert.equal(lastRequest.body.txHash, 'abc123');
+    assert.equal(lastRequest.body.tag, 'order-A-12');
+});
+
+test('--network is never a flag this command accepts - the node decides', async () => {
+    const r = await run(['--hash', HASH, '--network', 'testnet']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /unknown option/i);
+});
+
+test('a 400 from the server is reported as a failure, nothing anchored', async () => {
+    scenario = 'bad-request';
+    const r = await run(['--hash', HASH]);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /64-char sha-256 hex/);
+});
+
+test('human output prints the CID, hash, gateway URL, and a verify suggestion', async () => {
+    const r = await run(['--hash', HASH]);
+    assert.equal(r.code, 0, r.stdout + r.stderr);
+    assert.match(r.stdout, /CID:\s+QmFakeCidForTests1234567890/);
+    assert.match(r.stdout, /Content sha256:\s+f{64}/);
+    assert.match(r.stdout, /Gateway URL:/);
+    assert.match(r.stdout, /nirium verify QmFakeCidForTests1234567890/);
+});
+
+test('a 503 (temporarily unavailable) is a failure, not swallowed', async () => {
+    scenario = 'unavailable';
+    const r = await run(['--hash', HASH, '--json']);
+    assert.equal(r.code, 1);
+    const json = JSON.parse(r.stdout);
+    assert.equal(json.ok, false);
+    assert.match(json.error, /temporarily unavailable/);
+});
+
+test('agent unreachable is reported as a failure, not a hang', async () => {
+    const r = await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cli, 'anchor', '--url', 'http://127.0.0.1:1', '--hash', HASH, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('timed out')); }, 10_000);
+        child.stdout.on('data', (d) => { stdout += d; });
+        child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout }); });
+    });
+    assert.equal(r.code, 1);
+    const json = JSON.parse(r.stdout);
+    assert.equal(json.ok, false);
+    assert.match(json.error, /unreachable/);
+});