@algovoi/substrate 0.1.0

package/src/audit-chain.ts

@@ -0,0 +1,118 @@
+/**
+ * Audit chain primitive: monotonic per-row hash chain.
+ *
+ * Each row carries:
+ * - content_hash: SHA-256(JCS(payload))
+ * - prev_hash: previous row's content_hash, or null for the head row
+ * - chain_position: monotonically increasing integer starting at 0
+ *
+ * This is the structure AlgoVoi's production /compliance/attestation chain
+ * exposes (Object Lock COMPLIANCE retention to 2033-05-04).
+ */
+
+import { sha256Jcs } from './canonicalize.js';
+
+export class AuditChainError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuditChainError';
+  }
+}
+
+export interface AuditChainRow {
+  chain_position: number;
+  content_hash: string;
+  prev_hash: string | null;
+  payload: unknown;
+}
+
+/**
+ * Build the next row in an audit chain.
+ *
+ * If prevRow is null, the new row becomes the head (chain_position = 0,
+ * prev_hash = null). Otherwise chain_position increments and prev_hash
+ * links to prevRow.content_hash.
+ */
+export function appendToChain(
+  payload: unknown,
+  prevRow: AuditChainRow | null,
+): AuditChainRow {
+  let chainPosition: number;
+  let prevHash: string | null;
+
+  if (prevRow === null) {
+    chainPosition = 0;
+    prevHash = null;
+  } else {
+    if (
+      typeof prevRow.chain_position !== 'number' ||
+      !Number.isInteger(prevRow.chain_position) ||
+      prevRow.chain_position < 0
+    ) {
+      throw new AuditChainError(
+        'prevRow.chain_position must be a non-negative integer',
+      );
+    }
+    if (
+      typeof prevRow.content_hash !== 'string' ||
+      prevRow.content_hash.length === 0
+    ) {
+      throw new AuditChainError(
+        'prevRow.content_hash must be a non-empty string',
+      );
+    }
+    chainPosition = prevRow.chain_position + 1;
+    prevHash = prevRow.content_hash;
+  }
+
+  return {
+    chain_position: chainPosition,
+    content_hash: sha256Jcs(payload),
+    prev_hash: prevHash,
+    payload,
+  };
+}
+
+/**
+ * Verify a chain of audit rows is well-formed and linkage-consistent.
+ *
+ * Throws AuditChainError on any violation; otherwise returns void.
+ */
+export function verifyAuditChain(rows: readonly AuditChainRow[]): void {
+  let expectedPosition = 0;
+  let prevContentHash: string | null = null;
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]!;
+
+    if (row.chain_position !== expectedPosition) {
+      throw new AuditChainError(
+        `row ${i}: chain_position ${row.chain_position} != expected ${expectedPosition}`,
+      );
+    }
+
+    const recomputed = sha256Jcs(row.payload);
+    if (row.content_hash !== recomputed) {
+      throw new AuditChainError(
+        `row ${i}: content_hash mismatch -- stored ${row.content_hash} vs recomputed ${recomputed}`,
+      );
+    }
+
+    if (expectedPosition === 0) {
+      if (row.prev_hash !== null) {
+        throw new AuditChainError(
+          `row 0 (head): prev_hash must be null, got ${JSON.stringify(row.prev_hash)}`,
+        );
+      }
+    } else {
+      if (row.prev_hash !== prevContentHash) {
+        throw new AuditChainError(
+          `row ${i}: prev_hash ${JSON.stringify(row.prev_hash)} != previous content_hash ${JSON.stringify(prevContentHash)}`,
+        );
+      }
+    }
+
+    prevContentHash = row.content_hash;
+    expectedPosition += 1;
+  }
+}

package/src/canonicalize.ts

@@ -0,0 +1,106 @@
+/**
+ * JCS RFC 8785 canonicalisation with the AlgoVoi-discipline rules.
+ *
+ * The canonicalisation discipline is the shared normative substrate for
+ * x402, AP2, A2A, and MPP receipts, formalised in PR #2436 in
+ * x402-foundation/x402 (three-voice coalition co-signed). This module
+ * wraps the `canonicalize` npm package (v3.0.0) with the discipline's
+ * pre-canonicalisation rules.
+ *
+ * Reference matrix: https://gist.github.com/chopmob-cloud/b327814c4e17ed9fc7b4f29c8bda523c
+ */
+
+import canonicalizeLib from 'canonicalize';
+import { createHash } from 'node:crypto';
+
+/**
+ * Pin the discipline version. Receipts emitted under this substrate carry
+ * this string in their canon_version field so a year-five verifier can pick
+ * the correct re-canonicalisation rule from the retained bytes alone.
+ */
+export const CANON_VERSION = 'jcs-rfc8785-v1' as const;
+
+export class CanonicalizationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CanonicalizationError';
+  }
+}
+
+/**
+ * Walk obj and enforce AlgoVoi-discipline pre-canonicalisation type rules:
+ * - object keys must be strings
+ * - only JSON-canonicalisable types are accepted (null, boolean, number,
+ *   string, array, plain object)
+ *
+ * Strict-integer-fields enforcement (timestamp_ms etc.) is done at the
+ * per-schema layer rather than universally here.
+ */
+function validateTypes(obj: unknown, path = '$'): void {
+  if (obj === null) return;
+  if (typeof obj === 'boolean') return;
+  if (typeof obj === 'number') return;
+  if (typeof obj === 'string') return;
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      validateTypes(obj[i], `${path}[${i}]`);
+    }
+    return;
+  }
+  if (typeof obj === 'object') {
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+      // Object.entries always yields string keys; this guard is for safety
+      // around prototype-pollution edge cases in user-supplied objects.
+      if (typeof k !== 'string') {
+        throw new CanonicalizationError(
+          `non-string object key at ${path}: ${typeof k}`,
+        );
+      }
+      validateTypes(v, `${path}.${k}`);
+    }
+    return;
+  }
+  throw new CanonicalizationError(
+    `non-canonicalisable type at ${path}: ${typeof obj}`,
+  );
+}
+
+/**
+ * Return the canonical JCS string representation of obj.
+ *
+ * Applies AlgoVoi-discipline pre-canonicalisation type validation, then
+ * delegates to canonicalize (RFC 8785) for the canonical bytes.
+ *
+ * Throws CanonicalizationError on type-validation failure.
+ */
+export function canonicalize(obj: unknown): string {
+  validateTypes(obj);
+  const out = canonicalizeLib(obj);
+  if (out === undefined) {
+    // canonicalize() returns undefined for values that JSON.stringify would
+    // also drop (e.g. functions, undefined values at the root). The
+    // discipline does not allow those at any level; this is belt-and-braces.
+    throw new CanonicalizationError(
+      'object is not JCS-canonicalisable (canonicalize returned undefined)',
+    );
+  }
+  return out;
+}
+
+/**
+ * Return the canonical JCS UTF-8 bytes of obj as a Uint8Array.
+ */
+export function canonicalizeBytes(obj: unknown): Uint8Array {
+  return new TextEncoder().encode(canonicalize(obj));
+}
+
+/**
+ * Return the lowercase hex SHA-256 of the JCS canonical bytes of obj.
+ *
+ * This is the substrate primitive used by action_ref, compliance receipts,
+ * audit chain entries, and the composite trust-query algorithm. The string
+ * is plain hex without an algorithm prefix.
+ */
+export function sha256Jcs(obj: unknown): string {
+  return createHash('sha256').update(canonicalize(obj)).digest('hex');
+}

package/src/compliance-receipt.ts

@@ -0,0 +1,119 @@
+/**
+ * Compliance receipt shape matching AlgoVoi's production /compliance/screen.
+ *
+ * The categorical outcome (ALLOW / REFER / DENY) is load-bearing for the
+ * retention layer (UK POCA 2002 s.330 SAR distinction). A score/tier
+ * projection would lose that property and break year-five auditability.
+ */
+
+import { CANON_VERSION } from './canonicalize.js';
+
+export const SCREEN_RESULTS = ['ALLOW', 'REFER', 'DENY'] as const;
+export type ScreenResult = (typeof SCREEN_RESULTS)[number];
+
+export class ComplianceReceiptError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ComplianceReceiptError';
+  }
+}
+
+export interface ComplianceReceipt {
+  payer_ref: string;
+  screen_result: ScreenResult;
+  screen_timestamp_ms: number;
+  screen_provider_did: string;
+  jurisdiction_flags: string[];
+  canon_version: string;
+}
+
+export interface BuildComplianceReceiptInput {
+  payer_ref: string;
+  screen_result: string;
+  screen_timestamp_ms: number;
+  screen_provider_did: string;
+  jurisdiction_flags: string[];
+  canon_version?: string;
+}
+
+function requireNonEmptyString(field: string, value: unknown): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new ComplianceReceiptError(
+      `${field} must be a non-empty string`,
+    );
+  }
+  return value;
+}
+
+function requireIntTimestampMs(value: unknown): number {
+  if (typeof value !== 'number') {
+    throw new ComplianceReceiptError(
+      `screen_timestamp_ms must be epoch-millisecond integer (Substrate Rule 1), got ${typeof value}`,
+    );
+  }
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new ComplianceReceiptError(
+      `screen_timestamp_ms must be epoch-millisecond integer (Substrate Rule 1), got ${value}`,
+    );
+  }
+  if (value < 0) {
+    throw new ComplianceReceiptError(
+      `screen_timestamp_ms must be non-negative, got ${value}`,
+    );
+  }
+  return value;
+}
+
+function requireJurisdictionFlags(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new ComplianceReceiptError(
+      `jurisdiction_flags must be array, got ${typeof value}`,
+    );
+  }
+  for (let i = 0; i < value.length; i++) {
+    const code = value[i];
+    if (typeof code !== 'string' || code.length === 0) {
+      throw new ComplianceReceiptError(
+        `jurisdiction_flags[${i}] must be a non-empty string`,
+      );
+    }
+  }
+  return [...value] as string[];
+}
+
+/**
+ * Build a validated compliance receipt object.
+ *
+ * screen_result must be one of ALLOW, REFER, DENY -- the categorical
+ * outcome is load-bearing for downstream regulatory obligations.
+ *
+ * payer_ref is expected to be a content-addressed identity reference
+ * (e.g. "sha256:<hex>") rather than cleartext identity content.
+ *
+ * jurisdiction_flags is treated as ordered -- ["UK","EU"] and ["EU","UK"]
+ * produce distinct canonical bytes per RFC 8785 §3.2.3.
+ */
+export function buildComplianceReceipt(
+  input: BuildComplianceReceiptInput,
+): ComplianceReceipt {
+  if (!SCREEN_RESULTS.includes(input.screen_result as ScreenResult)) {
+    throw new ComplianceReceiptError(
+      `screen_result must be one of ${JSON.stringify([...SCREEN_RESULTS])}, got ${JSON.stringify(input.screen_result)}`,
+    );
+  }
+
+  return {
+    payer_ref: requireNonEmptyString('payer_ref', input.payer_ref),
+    screen_result: input.screen_result as ScreenResult,
+    screen_timestamp_ms: requireIntTimestampMs(input.screen_timestamp_ms),
+    screen_provider_did: requireNonEmptyString(
+      'screen_provider_did',
+      input.screen_provider_did,
+    ),
+    jurisdiction_flags: requireJurisdictionFlags(input.jurisdiction_flags),
+    canon_version: requireNonEmptyString(
+      'canon_version',
+      input.canon_version ?? CANON_VERSION,
+    ),
+  };
+}

package/src/composite-trust-query.ts

@@ -0,0 +1,84 @@
+/**
+ * Composite trust-query algorithm (PR #2440 in x402-foundation/x402).
+ *
+ * composite_hash = SHA-256(JCS([emitter_rows sorted by source_id, sig excluded]))
+ *
+ * Aggregates trust evidence from multiple emitters into a single canonical
+ * hash. Properties:
+ * - Row ordering invariance (sort-by-source_id).
+ * - Set semantics (subset rows produce a distinct hash).
+ * - Signature exclusion (sig field dropped before serialisation).
+ *
+ * 5-implementation cross-validation:
+ * https://gist.github.com/chopmob-cloud/f2e9f0877b7d9fff70c8eca46e4ce636
+ */
+
+import { sha256Jcs } from './canonicalize.js';
+
+export class CompositeTrustQueryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CompositeTrustQueryError';
+  }
+}
+
+export interface EmitterRow {
+  source_id: string;
+  // Arbitrary additional fields (score, tier, jurisdictions, etc.)
+  [key: string]: unknown;
+  // sig is optional; when present it is stripped before hashing.
+  sig?: unknown;
+}
+
+function stripSig(row: Record<string, unknown>): Record<string, unknown> {
+  const { sig, ...rest } = row;
+  void sig;
+  return rest;
+}
+
+function requireSourceId(row: Record<string, unknown>): string {
+  const src = row['source_id'];
+  if (typeof src !== 'string' || src.length === 0) {
+    throw new CompositeTrustQueryError(
+      'every emitter row must carry a non-empty string source_id',
+    );
+  }
+  return src;
+}
+
+/**
+ * Return the lowercase hex composite_hash for a set of emitter rows.
+ *
+ * Steps (per PR #2440 §composite-hash):
+ *   1. Strip the sig field from each row.
+ *   2. Sort rows by source_id (lexicographic).
+ *   3. JCS-canonicalise the resulting array.
+ *   4. SHA-256 the canonical bytes.
+ *
+ * Output is plain hex without an algorithm prefix.
+ */
+export function compositeTrustQueryHash(rows: readonly EmitterRow[]): string {
+  if (rows.length === 0) {
+    throw new CompositeTrustQueryError(
+      'composite trust-query requires at least one emitter row',
+    );
+  }
+
+  const stripped: Record<string, unknown>[] = [];
+  for (const row of rows) {
+    if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+      throw new CompositeTrustQueryError(
+        `emitter row must be an object, got ${Array.isArray(row) ? 'array' : typeof row}`,
+      );
+    }
+    requireSourceId(row as Record<string, unknown>);
+    stripped.push(stripSig(row as Record<string, unknown>));
+  }
+
+  stripped.sort((a, b) => {
+    const sa = a['source_id'] as string;
+    const sb = b['source_id'] as string;
+    return sa < sb ? -1 : sa > sb ? 1 : 0;
+  });
+  return sha256Jcs(stripped);
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @algovoi/substrate
+ *
+ * AlgoVoi agentic-payments substrate reference implementation.
+ *
+ * - JCS RFC 8785 canonicalisation with the AlgoVoi-discipline rules
+ *   (type-validation pre-canonicalisation, in-band canon_version pin).
+ * - action_ref atomic primitive:
+ *   SHA-256(JCS({agent_id, action_type, scope, timestamp_ms})).
+ * - Composite trust-query algorithm (PR #2440 in x402-foundation/x402).
+ * - Compliance receipt shape matching AlgoVoi's production
+ *   /compliance/screen emission.
+ * - Audit chain primitive: monotonic per-row hash chain with content_hash +
+ *   prev_hash linking, year-five auditability under canon_version pin.
+ *
+ * The substrate runs in production at https://api.algovoi.co.uk/compliance.
+ * Licensed under Apache 2.0.
+ */
+
+export {
+  CANON_VERSION,
+  CanonicalizationError,
+  canonicalize,
+  canonicalizeBytes,
+  sha256Jcs,
+} from './canonicalize.js';
+
+export {
+  ActionRefError,
+  type ActionRefInput,
+  type ActionRefObject,
+  actionRef,
+  actionRefObject,
+} from './action-ref.js';
+
+export {
+  CompositeTrustQueryError,
+  type EmitterRow,
+  compositeTrustQueryHash,
+} from './composite-trust-query.js';
+
+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';