nirium 0.19.6 → 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
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.6",
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",