@algovoi/audit-verifier 0.1.0

package/src/extractors.ts

@@ -0,0 +1,87 @@
+/**
+ * Per-chain canonical-field extractors.
+ *
+ * Each chain (audit_log / screening_hits / compliance_events /
+ * negotiation_trace_events) commits a different set of fields to its
+ * content_hash. These functions MUST byte-for-byte match the Python
+ * sibling (verify_audit_bundle.py) and the emitter side, otherwise every
+ * row will fail verification on the auditor side.
+ */
+import type { AuditRow, FieldExtractor } from './types.js';
+
+function auditLogCanonicalFields(row: AuditRow): Record<string, unknown> {
+  return {
+    trace_id:       row.trace_id ?? null,
+    actor:          row.actor ?? null,
+    action:         row.action ?? null,
+    target_type:    row.target_type ?? null,
+    target_id:      row.target_id ?? null,
+    tenant_id:      row.tenant_id ?? null,
+    before_state:   row.before_state ?? null,
+    after_state:    row.after_state ?? null,
+    ip_address:     row.ip_address ?? null,
+    user_agent:     row.user_agent ?? null,
+    created_at:     row.created_at ?? null,
+    chain_position: row.chain_position ?? null,
+    prev_hash:      row.prev_hash ?? null,
+  };
+}
+
+function screeningHitCanonicalFields(row: AuditRow): Record<string, unknown> {
+  return {
+    screened_at:        row.screened_at ?? null,
+    subject_type:       row.subject_type ?? null,
+    wallet_address:     row.wallet_address ?? null,
+    tenant_id:          row.tenant_id ?? null,
+    payment_ledger_id:  row.payment_ledger_id ?? null,
+    sanctions_entry_id: row.sanctions_entry_id ?? null,
+    action_taken:       row.action_taken ?? null,
+    screening_context:  row.screening_context ?? null,
+    chain_position:     row.chain_position ?? null,
+    prev_hash:          row.prev_hash ?? null,
+  };
+}
+
+function complianceEventCanonicalFields(row: AuditRow): Record<string, unknown> {
+  return {
+    id:                     row.id ?? null,
+    tenant_id:              row.tenant_id ?? null,
+    rule_id:                row.rule_id ?? null,
+    payment_ledger_id:      row.payment_ledger_id ?? null,
+    payer_address_snapshot: row.payer_address_snapshot ?? null,
+    review_of_event_id:     row.review_of_event_id ?? null,
+    event_type:             row.event_type ?? null,
+    metric_value:           row.metric_value ?? null,
+    threshold_value:        row.threshold_value ?? null,
+    created_at:             row.created_at ?? null,
+    chain_position:         row.chain_position ?? null,
+    prev_hash:              row.prev_hash ?? null,
+  };
+}
+
+function negotiationTraceCanonicalFields(row: AuditRow): Record<string, unknown> {
+  return {
+    trace_id:          row.trace_id ?? null,
+    session_id:        row.session_id ?? null,
+    tenant_id:         row.tenant_id ?? null,
+    counterparty_a:    row.counterparty_a ?? null,
+    counterparty_b:    row.counterparty_b ?? null,
+    protocol:          row.protocol ?? null,
+    message_seq:       row.message_seq ?? null,
+    message_role:      row.message_role ?? null,
+    message_payload:   row.message_payload ?? null,
+    payment_ledger_id: row.payment_ledger_id ?? null,
+    created_at:        row.created_at ?? null,
+    chain_position:    row.chain_position ?? null,
+    prev_hash:         row.prev_hash ?? null,
+  };
+}
+
+export const FIELD_EXTRACTORS: Record<string, FieldExtractor> = {
+  audit_log:                auditLogCanonicalFields,
+  screening_hits:           screeningHitCanonicalFields,
+  compliance_events:        complianceEventCanonicalFields,
+  negotiation_trace_events: negotiationTraceCanonicalFields,
+};
+
+export const KNOWN_CHAIN_NAMES = Object.keys(FIELD_EXTRACTORS).sort();

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @algovoi/audit-verifier
+ *
+ * TypeScript reference verifier for AlgoVoi selective-disclosure audit
+ * bundles. Byte-for-byte parity with the Python sibling
+ * algovoi-audit-verifier (PyPI).
+ *
+ * The hosted version is at https://verify.algovoi.co.uk; the offline /
+ * embedded version is this package.
+ */
+
+export {
+  canonicalize,
+  canonicaliseToBytes,
+  sha256Hex,
+  sha256JcsHex,
+} from './canonicalize.js';
+
+export { FIELD_EXTRACTORS, KNOWN_CHAIN_NAMES } from './extractors.js';
+export { CheckReport } from './check-report.js';
+export {
+  checkPerRowContentHash,
+  checkContinuity,
+  checkBundleSignature,
+  checkSelectionCriteriaMatch,
+  checkOffVmAnchor,
+  parseObjectKeyShaPrefix,
+} from './checks.js';
+export { verifyBundle, SUPPORTED_CHAIN_FORMAT_VERSIONS } from './verify.js';
+export { buildDemoBundle } from './demo.js';
+
+export type {
+  AuditBundle,
+  AuditRow,
+  BundleSignature,
+  ChainAnchor,
+  CheckEntry,
+  CheckReportJSON,
+  CheckResult,
+  FieldExtractor,
+  OffVmAnchor,
+  SelectionCriteria,
+  VerifyBundleOptions,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Public type surface for the audit-verifier.
+ */
+
+export type AuditRow = Record<string, unknown>;
+
+export type FieldExtractor = (row: AuditRow) => Record<string, unknown>;
+
+export interface BundleSignature {
+  hex: string;
+  algorithm?: string;
+  canonicalisation?: string;
+  key_id?: string;
+}
+
+export interface OffVmAnchor {
+  bucket_name?: string;
+  object_key?: string;
+  region?: string;
+  object_lock_until?: string;
+}
+
+export interface ChainAnchor {
+  current_head?: {
+    chain_position?: number;
+    content_hash?: string;
+  };
+}
+
+export interface SelectionCriteria {
+  [key: string]: unknown;
+  since?: string;
+  until?: string;
+}
+
+export interface BridgingMeta {
+  included?: boolean;
+}
+
+export interface AuditBundle {
+  chain_format_version?: number;
+  chain_name?: string;
+  rows?: AuditRow[];
+  bridging_rows?: AuditRow[];
+  bridging?: BridgingMeta;
+  bundle_signature?: BundleSignature | null;
+  off_vm_anchor?: OffVmAnchor;
+  chain_anchor?: ChainAnchor;
+  selection_criteria?: SelectionCriteria;
+  [key: string]: unknown;
+}
+
+export type CheckResult = 'ok' | 'fail' | 'skip';
+
+export interface CheckEntry {
+  name: string;
+  passed: boolean | null;  // true=ok, false=fail, null=skip
+  detail: string;
+}
+
+export interface VerifyBundleOptions {
+  signingKey?: string | null;
+  manifestDir?: string | null;
+}
+
+export interface CheckReportJSON {
+  all_passed: boolean;
+  fatal: string[];
+  checks: CheckEntry[];
+}

package/src/verify.ts

@@ -0,0 +1,66 @@
+/**
+ * verifyBundle -- run all checks against a parsed bundle, return CheckReport.
+ *
+ * Behaviour byte-for-byte parity with the Python sibling verify_bundle().
+ */
+import { CheckReport } from './check-report.js';
+import {
+  checkPerRowContentHash,
+  checkContinuity,
+  checkBundleSignature,
+  checkSelectionCriteriaMatch,
+  checkOffVmAnchor,
+} from './checks.js';
+import { KNOWN_CHAIN_NAMES } from './extractors.js';
+import type { AuditBundle, VerifyBundleOptions } from './types.js';
+
+export const SUPPORTED_CHAIN_FORMAT_VERSIONS = new Set<number>([1]);
+
+export async function verifyBundle(
+  bundle: AuditBundle,
+  options: VerifyBundleOptions = {},
+): Promise<CheckReport> {
+  const report = new CheckReport();
+
+  // Version check first.
+  const version = bundle.chain_format_version;
+  if (version === undefined || version === null) {
+    report.addFatal(
+      "bundle is missing required field 'chain_format_version' " +
+      '-- bundle is malformed or was not emitted by AlgoVoi',
+    );
+    return report;
+  }
+  if (!SUPPORTED_CHAIN_FORMAT_VERSIONS.has(version)) {
+    const supported = Array.from(SUPPORTED_CHAIN_FORMAT_VERSIONS).sort();
+    report.addFatal(
+      `bundle.chain_format_version=${JSON.stringify(version)} is not supported by ` +
+      `this verifier (supported: ${JSON.stringify(supported)}). ` +
+      'Pull a fresh verifier from https://github.com/chopmob-cloud/algovoi-audit-verifier ' +
+      '-- running an older verifier against a newer bundle risks a false PASS.',
+    );
+    return report;
+  }
+
+  const chainName = bundle.chain_name;
+  if (!chainName || !KNOWN_CHAIN_NAMES.includes(chainName)) {
+    report.addFatal(
+      `bundle.chain_name='${chainName}' is not recognised ` +
+      `(expected one of: ${JSON.stringify(KNOWN_CHAIN_NAMES)})`,
+    );
+    return report;
+  }
+
+  if (!('rows' in bundle)) {
+    report.addFatal("bundle is missing required field 'rows'");
+    return report;
+  }
+
+  checkPerRowContentHash(bundle, report);
+  checkContinuity(bundle, report);
+  checkSelectionCriteriaMatch(bundle, report);
+  checkBundleSignature(bundle, options.signingKey ?? null, report);
+  await checkOffVmAnchor(bundle, options.manifestDir ?? null, report);
+
+  return report;
+}