@algovoi/substrate 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -22,4 +22,5 @@ export { CompositeTrustQueryError, type EmitterRow, compositeTrustQueryHash, } f
 export { SCREEN_RESULTS, type ScreenResult, ComplianceReceiptError, type ComplianceReceipt, type BuildComplianceReceiptInput, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, type AuditChainRow, appendToChain, verifyAuditChain, } from './audit-chain.js';
 export { TransactionalError, type TransitionPreimage, type TransitionInput, type TransitionRecord, type TransactionalChain, type TransactionalChainInput, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
+export { SettlementBindingError, type SettlementBindingPreimage, settlementBindingPreimage, settlementActionBinding, } from './settlement-binding.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -22,4 +22,5 @@ export { CompositeTrustQueryError, compositeTrustQueryHash, } from './composite-
 export { SCREEN_RESULTS, ComplianceReceiptError, buildComplianceReceipt, } from './compliance-receipt.js';
 export { AuditChainError, appendToChain, verifyAuditChain, } from './audit-chain.js';
 export { TransactionalError, transitionPreimage, transitionHash, buildTransactionalActionChain, } from './transactional.js';
+export { SettlementBindingError, settlementBindingPreimage, settlementActionBinding, } from './settlement-binding.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAMlB,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAGd,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EAEd,sBAAsB,EAGtB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAMlB,kBAAkB,EAClB,cAAc,EACd,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,sBAAsB,EAEtB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/settlement-binding.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+export declare class SettlementBindingError extends Error {
+    constructor(message: string);
+}
+export interface SettlementBindingPreimage {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export declare function settlementBindingPreimage(input: {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}): SettlementBindingPreimage;
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export declare function settlementActionBinding(input: {
+    action_ref: string;
+    transition_hash: string;
+    settlement_ref: string;
+    retention_chain_ref: string;
+}): string;
+//# sourceMappingURL=settlement-binding.d.ts.map

package/dist/settlement-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-binding.d.ts","sourceRoot":"","sources":["../src/settlement-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AA8BD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,yBAAyB,CAO5B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,MAAM,CAGT"}

package/dist/settlement-binding.js

@@ -0,0 +1,79 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+import { sha256Jcs } from './canonicalize.js';
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const SHA256_REF_RE = /^sha256:[0-9a-f]{64}$/;
+export class SettlementBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SettlementBindingError';
+    }
+}
+function requireHex64(field, value) {
+    if (typeof value !== 'string') {
+        throw new SettlementBindingError(`${field} must be string, got ${typeof value}`);
+    }
+    if (!HEX64_RE.test(value)) {
+        throw new SettlementBindingError(`${field} must be a lowercase 64-character SHA-256 hex string`);
+    }
+    return value;
+}
+function requireChainRef(value) {
+    if (typeof value !== 'string') {
+        throw new SettlementBindingError(`retention_chain_ref must be string, got ${typeof value}`);
+    }
+    if (!SHA256_REF_RE.test(value)) {
+        throw new SettlementBindingError("retention_chain_ref must be of the form 'sha256:<lowercase 64-char hex>'");
+    }
+    return value;
+}
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export function settlementBindingPreimage(input) {
+    return {
+        action_ref: requireHex64('action_ref', input.action_ref),
+        transition_hash: requireHex64('transition_hash', input.transition_hash),
+        settlement_ref: requireHex64('settlement_ref', input.settlement_ref),
+        retention_chain_ref: requireChainRef(input.retention_chain_ref),
+    };
+}
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export function settlementActionBinding(input) {
+    const obj = settlementBindingPreimage(input);
+    return `sha256:${sha256Jcs(obj)}`;
+}
+//# sourceMappingURL=settlement-binding.js.map

package/dist/settlement-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-binding.js","sourceRoot":"","sources":["../src/settlement-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAClC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAE9C,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AASD,SAAS,YAAY,CAAC,KAAa,EAAE,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,wBAAwB,OAAO,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAC9B,GAAG,KAAK,sDAAsD,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,sBAAsB,CAC9B,2CAA2C,OAAO,KAAK,EAAE,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,sBAAsB,CAC9B,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAKzC;IACC,OAAO;QACL,UAAU,EAAE,YAAY,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC;QACxD,eAAe,EAAE,YAAY,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC;QACvE,cAAc,EAAE,YAAY,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC;QACpE,mBAAmB,EAAE,eAAe,CAAC,KAAK,CAAC,mBAAmB,CAAC;KAChE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAKvC;IACC,MAAM,GAAG,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@algovoi/substrate",
-  "version": "0.3.1",
-  "description": "AlgoVoi agentic-payments substrate -- JCS canonicalisation, action_ref, composite trust-query, compliance receipts, audit chain",
+  "version": "0.4.0",
+  "description": "AlgoVoi agentic-payments substrate -- JCS canonicalisation, action_ref, composite trust-query, compliance receipts, audit chain, settlement-action binding",
   "keywords": [
     "x402",
     "ap2",

package/src/index.ts

@@ -66,3 +66,10 @@ export {
   transitionHash,
   buildTransactionalActionChain,
 } from './transactional.js';
+
+export {
+  SettlementBindingError,
+  type SettlementBindingPreimage,
+  settlementBindingPreimage,
+  settlementActionBinding,
+} from './settlement-binding.js';

package/src/settlement-binding.ts

@@ -0,0 +1,110 @@
+/**
+ * Settlement-action binding (non-normative substrate extension).
+ *
+ * An x402/AP2/A2A settlement attestation proves a *payment* occurred. It does
+ * not, on its own, prove *which verified agent action* the payment corresponds
+ * to, nor that the correspondence is recorded in a tamper-evident chain. This
+ * module closes that post-settlement accountability gap with a single canonical
+ * reference binding four already-published substrate artifacts into one record:
+ *
+ *   binding_ref = "sha256:" + SHA-256(JCS({
+ *       action_ref,            // the verified agent-action identity
+ *       transition_hash,       // the COMMITTED lifecycle transition (the "once")
+ *       settlement_ref,        // the settlement attestation content_hash
+ *       retention_chain_ref,   // the tamper-evident chain position recording it
+ *   }))
+ *
+ * No new hashing primitive is introduced: the binding is the substrate's
+ * existing JCS + SHA-256 over the four references. Because action_ref and
+ * transition_hash are themselves computed from epoch-millisecond-integer
+ * preimages (Substrate Rule 2), any upstream RFC 3339 string timestamp produces
+ * a different action_ref, hence a different binding -- a non-conformant lineage
+ * cannot reproduce the binding bytes.
+ *
+ * The output carries the "sha256:" algorithm prefix, consistent with
+ * retention_chain_ref, signalling a content-addressed reference.
+ */
+
+import { sha256Jcs } from './canonicalize.js';
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const SHA256_REF_RE = /^sha256:[0-9a-f]{64}$/;
+
+export class SettlementBindingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SettlementBindingError';
+  }
+}
+
+export interface SettlementBindingPreimage {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}
+
+function requireHex64(field: string, value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new SettlementBindingError(
+      `${field} must be string, got ${typeof value}`,
+    );
+  }
+  if (!HEX64_RE.test(value)) {
+    throw new SettlementBindingError(
+      `${field} must be a lowercase 64-character SHA-256 hex string`,
+    );
+  }
+  return value;
+}
+
+function requireChainRef(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new SettlementBindingError(
+      `retention_chain_ref must be string, got ${typeof value}`,
+    );
+  }
+  if (!SHA256_REF_RE.test(value)) {
+    throw new SettlementBindingError(
+      "retention_chain_ref must be of the form 'sha256:<lowercase 64-char hex>'",
+    );
+  }
+  return value;
+}
+
+/**
+ * Return the validated four-field binding preimage object.
+ *
+ * The shape is fixed at the substrate layer; each field cryptographically
+ * contributes to the binding so that no one component can be substituted
+ * without changing the binding_ref.
+ */
+export function settlementBindingPreimage(input: {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}): SettlementBindingPreimage {
+  return {
+    action_ref: requireHex64('action_ref', input.action_ref),
+    transition_hash: requireHex64('transition_hash', input.transition_hash),
+    settlement_ref: requireHex64('settlement_ref', input.settlement_ref),
+    retention_chain_ref: requireChainRef(input.retention_chain_ref),
+  };
+}
+
+/**
+ * Return the binding_ref as a "sha256:"-prefixed content-addressed reference.
+ *
+ * binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
+ *                                        settlement_ref, retention_chain_ref}))
+ */
+export function settlementActionBinding(input: {
+  action_ref: string;
+  transition_hash: string;
+  settlement_ref: string;
+  retention_chain_ref: string;
+}): string {
+  const obj = settlementBindingPreimage(input);
+  return `sha256:${sha256Jcs(obj)}`;
+}