nirium 0.19.5 → 0.19.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -77,6 +77,22 @@ const anchor = await agent.anchorAuditRecord({
77
77
  console.log(anchor.cid, anchor.attestedBy);
78
78
  ```
79
79
 
80
+ ### Keep your own copy
81
+
82
+ The receipt lives on IPFS only while someone pins it. `anchorAuditRecord()` returns the exact `document` that was pinned (nodes deployed after 21 Nov 2026); save it, and `receiptCid()` shows any time that your copy is the original. If IPFS ever loses it, add the same bytes again (`ipfs add --cid-version=0`) and you get the same CID.
83
+
84
+ ```typescript
85
+ import { receiptCid } from 'nirium';
86
+ import fs from 'node:fs';
87
+
88
+ const anchor = await agent.anchorAuditRecord({ hash, tag: 'invoice-batch-jul' });
89
+ if (anchor.document) {
90
+ const bytes = JSON.stringify(anchor.document); // exactly what was pinned, no trailing newline
91
+ fs.writeFileSync('receipt.json', bytes);
92
+ console.log(receiptCid(fs.readFileSync('receipt.json')) === anchor.cid); // true
93
+ }
94
+ ```
95
+
80
96
  ### Verify any receipt, without trusting Nirium
81
97
 
82
98
  ```bash
@@ -85,6 +101,8 @@ npx nirium-cli verify <cid> --hash <64-hex-sha256>
85
101
 
86
102
  `nirium verify` fetches the document from IPFS, recomputes the hash and checks the ed25519 signature against the declared Stellar key. You can also paste a CID at [nirium.xyz/verify](https://nirium.xyz/verify), with no account. More in [docs/verify-audit-cid.md](https://github.com/nirium-protocol/nirium/blob/main/docs/verify-audit-cid.md).
87
103
 
104
+ **What a receipt adds over the ledger:** a Stellar payment is already public, so a receipt that only repeats payer, payee and amount proves nothing new; link the transaction instead. Receipts are for what the ledger doesn't hold: policy decisions (including refused payments that were never signed), what a payment was for, off-chain records, and who declared them. More in the [design FAQ](https://github.com/nirium-protocol/nirium/blob/main/docs/DESIGN-FAQ.md).
105
+
88
106
  ## API Coverage
89
107
 
90
108
  | Category | Methods |
package/dist/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type X402GuardConfig } from './x402-guard';
2
2
  import { type X402PolicyHook } from './x402-policy';
3
+ export { receiptCid } from './receipt-cid';
3
4
  export interface AgentConfig {
4
5
  apiKey: string;
5
6
  baseUrl?: string;
@@ -338,6 +339,12 @@ export interface AuditAnchor {
338
339
  anchoredAt: string;
339
340
  /** Present when the anchor carried a verified agent attestation. */
340
341
  attestedBy?: string;
342
+ /**
343
+ * The exact document pinned to IPFS (nodes deployed after 21 Nov 2026).
344
+ * Keep it: `JSON.stringify(document)`, with no trailing newline, gives back
345
+ * the same CID if you ever add it to IPFS again.
346
+ */
347
+ document?: Record<string, unknown>;
341
348
  [key: string]: unknown;
342
349
  }
343
350
  export interface ReportingPeriod {
package/dist/index.js CHANGED
@@ -41,7 +41,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
41
41
  return (mod && mod.__esModule) ? mod : { "default": mod };
42
42
  };
43
43
  Object.defineProperty(exports, "__esModule", { value: true });
44
- exports.ResilientSignalClient = exports.createUpstashX402GuardStore = exports.x402Metrics = exports.X402SpendCapError = exports.X402PolicyError = exports.Agent = void 0;
44
+ exports.ResilientSignalClient = exports.createUpstashX402GuardStore = exports.x402Metrics = exports.X402SpendCapError = exports.X402PolicyError = exports.Agent = exports.receiptCid = void 0;
45
45
  exports.x402Serve = x402Serve;
46
46
  const ws_1 = __importDefault(require("ws"));
47
47
  const node_crypto_1 = require("node:crypto");
@@ -58,6 +58,8 @@ const client_3 = require("@stellar/mpp/charge/client");
58
58
  const x402_guard_1 = require("./x402-guard");
59
59
  const x402_policy_1 = require("./x402-policy");
60
60
  const x402_spend_cap_1 = require("./x402-spend-cap");
61
+ var receipt_cid_1 = require("./receipt-cid");
62
+ Object.defineProperty(exports, "receiptCid", { enumerable: true, get: function () { return receipt_cid_1.receiptCid; } });
61
63
  /** Validates and normalizes `maxAmountPerPayment` at initX402 time ("$5" form). */
62
64
  function normalizeMaxAmountPerPayment(v) {
63
65
  if (v === undefined)
@@ -0,0 +1,13 @@
1
+ /**
2
+ * CIDv0 of an Audit Trail receipt, computed locally (no IPFS node, no library).
3
+ *
4
+ * A receipt is one IPFS block: a dag-pb node wrapping a UnixFS File whose data
5
+ * is the whole document (anything up to 256 KiB fits in one block). Its CIDv0
6
+ * is base58btc(0x12 0x20 || sha256(node)), the same result `ipfs add` gives with
7
+ * its defaults. Checked on 21 Nov 2026 against three real mainnet receipts.
8
+ *
9
+ * Use it to show that a copy you kept is the original: pass the exact bytes you
10
+ * saved, or the `document` object from `anchorAuditRecord()` (it is serialized
11
+ * with `JSON.stringify`, which is what the node pinned).
12
+ */
13
+ export declare function receiptCid(document: string | Uint8Array | Record<string, unknown>): string;
@@ -0,0 +1,62 @@
1
+ "use strict";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ // Copyright 2026 Nirium Protocol Contributors
4
+ Object.defineProperty(exports, "__esModule", { value: true });
5
+ exports.receiptCid = receiptCid;
6
+ const node_crypto_1 = require("node:crypto");
7
+ /**
8
+ * CIDv0 of an Audit Trail receipt, computed locally (no IPFS node, no library).
9
+ *
10
+ * A receipt is one IPFS block: a dag-pb node wrapping a UnixFS File whose data
11
+ * is the whole document (anything up to 256 KiB fits in one block). Its CIDv0
12
+ * is base58btc(0x12 0x20 || sha256(node)), the same result `ipfs add` gives with
13
+ * its defaults. Checked on 21 Nov 2026 against three real mainnet receipts.
14
+ *
15
+ * Use it to show that a copy you kept is the original: pass the exact bytes you
16
+ * saved, or the `document` object from `anchorAuditRecord()` (it is serialized
17
+ * with `JSON.stringify`, which is what the node pinned).
18
+ */
19
+ function receiptCid(document) {
20
+ const bytes = typeof document === 'string'
21
+ ? Buffer.from(document, 'utf8')
22
+ : document instanceof Uint8Array
23
+ ? Buffer.from(document)
24
+ : Buffer.from(JSON.stringify(document), 'utf8');
25
+ if (bytes.length === 0)
26
+ throw new Error('receiptCid: the document is empty');
27
+ if (bytes.length > UNIXFS_BLOCK_BYTES) {
28
+ throw new Error(`receiptCid: ${bytes.length} bytes is more than one IPFS block (${UNIXFS_BLOCK_BYTES}); every Audit Trail receipt fits`);
29
+ }
30
+ const unixfs = Buffer.concat([Buffer.from([0x08, 0x02]), bytesField(0x12, bytes), Buffer.from([0x18]), varint(bytes.length)]);
31
+ const node = bytesField(0x0a, unixfs);
32
+ const digest = (0, node_crypto_1.createHash)('sha256').update(node).digest();
33
+ return base58btc(Buffer.concat([Buffer.from([0x12, 0x20]), digest]));
34
+ }
35
+ const UNIXFS_BLOCK_BYTES = 262144;
36
+ const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
37
+ function varint(n) {
38
+ const out = [];
39
+ while (n >= 0x80) {
40
+ out.push((n & 0x7f) | 0x80);
41
+ n = Math.floor(n / 128);
42
+ }
43
+ out.push(n);
44
+ return Buffer.from(out);
45
+ }
46
+ function bytesField(tag, buf) {
47
+ return Buffer.concat([Buffer.from([tag]), varint(buf.length), buf]);
48
+ }
49
+ function base58btc(buf) {
50
+ let n = BigInt('0x' + buf.toString('hex'));
51
+ let out = '';
52
+ while (n > 0n) {
53
+ out = BASE58_ALPHABET[Number(n % 58n)] + out;
54
+ n /= 58n;
55
+ }
56
+ for (const b of buf) {
57
+ if (b !== 0)
58
+ break;
59
+ out = '1' + out;
60
+ }
61
+ return out;
62
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium",
3
- "version": "0.19.5",
3
+ "version": "0.19.7",
4
4
  "description": "Charge or pay per request in USDC on Stellar (x402), with receipts anyone can verify. For apps, backends and AI agents. Non-custodial.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",