pactium 0.2.0

package/src/index.d.ts

@@ -0,0 +1,244 @@
+export type PactiumCanonicalValue =
+  | null
+  | boolean
+  | number
+  | string
+  | PactiumCanonicalValue[]
+  | { [key: string]: PactiumCanonicalValue };
+
+export type PactiumRecord = Record<string, unknown>;
+
+export interface PactiumDataDirOptions {
+  dataDir?: string;
+  userDataPath?: string;
+  inMemory?: boolean;
+}
+
+export interface PactiumStoragePort {
+  protocol: string;
+  schema: string;
+  dataDir: string;
+  inMemory: boolean;
+  initialize(): Promise<void>;
+  putBlock(value: unknown, options?: PactiumRecord): Promise<PactiumRecord>;
+  getBlock(cid: string): Promise<(PactiumRecord & { bytes?: Uint8Array }) | null>;
+  hasBlock(cid: string): Promise<boolean>;
+  walk(rootCid: string): Promise<PactiumRecord>;
+  putProtocolObject(scope: string, key: string, value: unknown): Promise<PactiumCanonicalValue>;
+  getProtocolObject(scope: string, key: string, fallback?: unknown): Promise<unknown>;
+  clearCache?(): void;
+  withWriteLock?<T>(
+    task: () => T | Promise<T>,
+    options?: { name?: string; timeoutMs?: number; retryMs?: number; staleMs?: number }
+  ): Promise<T>;
+  pruneBlocks?(predicate?: (record: PactiumRecord) => boolean): number;
+  pruneProtocolObjects?(predicate?: (record: PactiumRecord & { scope: string; key: string; value: unknown }) => boolean): number;
+}
+
+export interface PactiumLedgerHead {
+  protocol: string;
+  schema: string;
+  size: number;
+  rootHash: string;
+  root: string;
+  headId?: string;
+  previousHeadId?: string;
+  createdAt?: string;
+  signatureRef?: string;
+  signatureHash?: string;
+  verifierManifest?: PactiumRecord;
+  verifierManifestRef?: string;
+  signatures?: PactiumRecord[];
+}
+
+export interface PactiumProofEnvelope {
+  protocol: string;
+  schema: string;
+  envelopeType: "pactium.proof-envelope";
+  envelopeKind: string;
+  envelopeId: string;
+  factType: string;
+  factId: string;
+  factRef: PactiumRecord;
+  ledgerHead: PactiumLedgerHead;
+  proofRefs: PactiumRecord[];
+  extensions: PactiumRecord[];
+  criticalExtensions: string[];
+  relatedEnvelopeIds: string[];
+  replayed: boolean;
+  createdAt: string;
+}
+
+export interface PactiumVerificationFailure {
+  protocol: string;
+  layer: string;
+  code: string;
+  severity: string;
+  message?: string;
+  evidenceRef?: string;
+  repairable?: boolean;
+  details?: PactiumRecord;
+}
+
+export interface PactiumVerificationResult {
+  protocol: string;
+  ok: boolean;
+  envelopeId?: string;
+  failures: PactiumVerificationFailure[];
+  checked?: string[];
+}
+
+export interface PactiumProofBundle {
+  protocol: string;
+  schema: string;
+  bundleType: "pactium.proof-bundle.indexed";
+  manifest: PactiumRecord;
+  envelope: PactiumProofEnvelope;
+  index?: PactiumRecord[];
+  blocksEncoding?: string;
+  binaryBase64?: string;
+  byteLength?: number;
+  bundleHash: string;
+}
+
+export interface PactiumIndexScanOptions extends PactiumRecord {
+  min?: string;
+  max?: string;
+  limit?: number;
+  after?: string;
+}
+
+export interface PactiumIndexEngine {
+  protocol: string;
+  engine: string;
+  domain: string;
+  createIndex(entries?: PactiumRecord[], options?: PactiumRecord): Promise<PactiumRecord>;
+  put(root: string, key: string, value: unknown, options?: PactiumRecord): Promise<PactiumRecord>;
+  delete(root: string, key: string, options?: PactiumRecord): Promise<PactiumRecord>;
+  get(root: string, key: string): Promise<PactiumRecord | null>;
+  prove(root: string, key: string): Promise<PactiumRecord>;
+  verifyProof(proof: PactiumRecord): boolean;
+  scan(root: string, options?: PactiumIndexScanOptions): Promise<PactiumRecord[]>;
+  prefix(root: string, keyPrefix?: string, options?: PactiumIndexScanOptions): Promise<PactiumRecord[]>;
+  diff(leftRoot: string, rightRoot: string): Promise<PactiumRecord[]>;
+  readSnapshot(root: string): Promise<PactiumRecord>;
+  readIndexRoot(root: string): Promise<PactiumRecord>;
+  readNode(root: string): Promise<PactiumRecord>;
+}
+
+export interface PactiumLedgerPageOptions extends PactiumRecord {
+  start?: number;
+  limit?: number;
+}
+
+export interface PactiumLedgerPage extends PactiumRecord {
+  protocol: string;
+  start: number;
+  limit: number;
+  entries: PactiumRecord[];
+  nextPosition: number;
+  head: PactiumLedgerHead;
+}
+
+export interface PactiumLedger extends PactiumRecord {
+  append(entry?: PactiumRecord): Promise<PactiumRecord>;
+  head(): Promise<PactiumLedgerHead>;
+  entries(): Promise<PactiumRecord[]>;
+  pageEntries(options?: PactiumLedgerPageOptions): Promise<PactiumLedgerPage>;
+}
+
+export interface PactiumProofBundleVerificationOptions extends PactiumRecord {
+  verifyAllBlocks?: boolean;
+}
+
+export interface PactiumProofBundleExportOptions extends PactiumRecord {
+  format?: "indexed";
+}
+
+export interface PactiumCore {
+  protocol: string;
+  schema: string;
+  dataDir: string;
+  storage: PactiumStoragePort;
+  ledger: PactiumLedger;
+  indexEngine: PactiumIndexEngine;
+  beginOperationIntent(input?: PactiumRecord): Promise<PactiumProofEnvelope>;
+  appendOperationOutcome(input?: PactiumRecord): Promise<PactiumProofEnvelope>;
+  recordOperation(input?: PactiumRecord): Promise<PactiumProofEnvelope>;
+  lookupOpenIntent(intentId: string): Promise<PactiumRecord>;
+  lookupOutcome(intentId: string): Promise<PactiumRecord>;
+  createAppendCondition(input?: PactiumRecord): PactiumRecord;
+  getLedgerCursor(input?: PactiumRecord): Promise<PactiumRecord>;
+  getWorkspaceCursor(input?: PactiumRecord): Promise<PactiumRecord>;
+  verifyCursor(cursor: PactiumRecord, context?: PactiumRecord): boolean;
+  advanceTrustedHead(input?: PactiumRecord): PactiumRecord;
+  planRecovery(input?: PactiumRecord): PactiumRecord;
+  getWorkspaceProjection(workspaceId?: string): Promise<PactiumRecord>;
+  proveWorkspaceMembership(input?: PactiumRecord): Promise<PactiumRecord>;
+  verifyEnvelope(envelope: PactiumProofEnvelope, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+  exportProofBundle(envelopeOrId: PactiumProofEnvelope | string, options?: PactiumProofBundleExportOptions): Promise<PactiumProofBundle>;
+  createExtension(extension: PactiumRecord): Promise<PactiumRecord>;
+  storeEnvelope(envelope: PactiumProofEnvelope): Promise<PactiumProofEnvelope>;
+  protocolCatalog(): Promise<PactiumRecord>;
+  doctor(): Promise<PactiumRecord & { ok: boolean; dataDir: string }>;
+}
+
+export const PACTIUM_PROTOCOL: "pactium.v0.2";
+export const PACTIUM_SCHEMA_VERSION: "pactium.v0.2.schema.latest";
+export const PACTIUM_PACKAGE_VERSION: "0.2.0";
+export const PACTIUM_INDEX_ENGINE: "pactium.verifiable-index-engine";
+export const PACTIUM_INDEX_SPLITTER: "pactium-cdc-boundary";
+export const PACTIUM_PROOF_BUNDLE_TYPE: "pactium.proof-bundle.indexed";
+export const PACTIUM_BUNDLE_ENCODING: "pactium.bundle.indexed-record-stream";
+export const PACTIUM_PROOF_TYPES: Readonly<{
+  ledgerInclusion: "ledger.inclusion.audit-path";
+  ledgerConsistency: "ledger.consistency.audit-path";
+  indexMembership: "index.membership.prolly-path";
+  indexNonMembership: "index.non-membership.prolly-path";
+}>;
+export const PACTIUM_PROTOCOL_PROFILE: PactiumRecord;
+export const HASH_DOMAINS: Record<string, string>;
+
+export function defaultPactiumDataDir(): string;
+export function resolveDataDir(dataDir?: string): string;
+export function resolveWithin(root: string, ...segments: string[]): string;
+export function normalizeCanonicalValue(value: unknown): PactiumCanonicalValue;
+export function canonicalString(value: unknown): string;
+export function canonicalEncode(value: unknown): Uint8Array;
+export function canonicalDecode(bytes: Uint8Array | ArrayBuffer | string): PactiumCanonicalValue;
+export function protocolHashHex(domain: string, value: unknown): string;
+export function protocolHash(domain: string, value: unknown): string;
+export function cidForBytes(bytes: Uint8Array | ArrayBuffer | string): string;
+export function cidForCanonical(value: unknown): string;
+export function createVerificationFailure(input?: PactiumRecord): PactiumVerificationFailure;
+export function createStoragePort(options?: PactiumDataDirOptions): PactiumStoragePort;
+export function ledgerLeafHash(leaf: unknown): string;
+export function ledgerNodeHash(leftHash: string, rightHash: string): string;
+export function emptyTreeHash(): string;
+export function createCompactRange(input?: PactiumRecord): PactiumRecord;
+export function createLedgerInclusionProof(input?: PactiumRecord): PactiumRecord;
+export function verifyLedgerInclusionProof(input?: PactiumRecord): boolean;
+export function createLedgerConsistencyProof(input?: PactiumRecord): PactiumRecord;
+export function verifyLedgerConsistencyProof(input?: PactiumRecord): boolean;
+export function createLedgerTransparencyLog(options?: PactiumRecord): PactiumLedger;
+export function createVerifierManifest(input?: PactiumRecord): PactiumRecord;
+export function ledgerHeadSigningPayload(head?: PactiumRecord): PactiumRecord;
+export function signLedgerHead(head?: PactiumRecord, options?: PactiumRecord): PactiumRecord;
+export function verifyLedgerHeadSignature(head?: PactiumRecord, manifest?: PactiumRecord, options?: PactiumRecord): PactiumVerificationResult & { accepted?: number };
+export function advanceTrustedHead(input?: PactiumRecord): PactiumRecord;
+export function createVerifiableIndexEngine(options?: PactiumRecord): PactiumIndexEngine;
+export function verifyIndexProof(proof: PactiumRecord): boolean;
+export function createAppendCondition(input?: PactiumRecord): PactiumRecord;
+export function createTrackingCursor(input?: PactiumRecord): PactiumRecord;
+export function covers(cursor: PactiumRecord, position: number): boolean;
+export function advanceTo(cursor: PactiumRecord, position: number, options?: PactiumRecord): PactiumRecord;
+export function samePositionAs(left: PactiumRecord, right: PactiumRecord): boolean;
+export function verifyTrackingCursor(cursor: PactiumRecord, context?: PactiumRecord): boolean;
+export function createPactium(options?: PactiumDataDirOptions & { storage?: PactiumStoragePort | null }): PactiumCore;
+export function verifyProofEnvelope(envelope: PactiumProofEnvelope, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+export function verifyProofBundle(bundle: PactiumProofBundle, options?: PactiumProofBundleVerificationOptions): Promise<PactiumVerificationResult & { bundleHash?: string }>;
+export function createDefaultProofVerifierRegistry(extraVerifiers?: PactiumRecord): Map<string, (...args: unknown[]) => unknown>;
+export function createRepairPlanner(): PactiumRecord;
+export function createMaintenanceTaskEngine(options?: PactiumRecord): PactiumRecord;
+export function envelopeSigningHash(envelope: PactiumProofEnvelope): string;
+export function runPactiumQualityGateProfile(options?: PactiumRecord): Promise<PactiumRecord>;

package/src/index.js

@@ -0,0 +1,73 @@
+export {
+  HASH_DOMAINS,
+  PACTIUM_BUNDLE_ENCODING,
+  PACTIUM_INDEX_ENGINE,
+  PACTIUM_INDEX_SPLITTER,
+  PACTIUM_PACKAGE_VERSION,
+  PACTIUM_PROOF_BUNDLE_TYPE,
+  PACTIUM_PROOF_TYPES,
+  PACTIUM_PROTOCOL,
+  PACTIUM_PROTOCOL_PROFILE,
+  PACTIUM_SCHEMA_VERSION
+} from "./protocol/constants.js";
+export {
+  canonicalDecode,
+  canonicalEncode,
+  canonicalString,
+  normalizeCanonicalValue
+} from "./canonical/value.js";
+export {
+  cidForBytes,
+  cidForCanonical,
+  protocolHash,
+  protocolHashHex
+} from "./protocol/hashing.js";
+export {
+  createStoragePort,
+  defaultPactiumDataDir,
+  resolveDataDir,
+  resolveWithin
+} from "./storage/local-json-storage-port.js";
+export { createVerificationFailure } from "./verification/failure.js";
+export {
+  createLedgerConsistencyProof,
+  createLedgerInclusionProof,
+  createLedgerTransparencyLog,
+  createCompactRange,
+  emptyTreeHash,
+  ledgerLeafHash,
+  ledgerNodeHash,
+  verifyLedgerConsistencyProof,
+  verifyLedgerInclusionProof
+} from "./ledger/transparency-log.js";
+export {
+  advanceTrustedHead,
+  createVerifierManifest,
+  ledgerHeadSigningPayload,
+  signLedgerHead,
+  verifyLedgerHeadSignature
+} from "./ledger/signed-head.js";
+export {
+  createVerifiableIndexEngine,
+  verifyIndexProof
+} from "./index-engine/snapshot-merkle-index.js";
+export {
+  createAppendCondition
+} from "./core/append-condition.js";
+export {
+  advanceTo,
+  covers,
+  createTrackingCursor,
+  samePositionAs,
+  verifyTrackingCursor
+} from "./core/tracking-cursor.js";
+export { createPactium } from "./core/pactium-core.js";
+export {
+  envelopeSigningHash,
+  verifyProofEnvelope
+} from "./proof/envelope.js";
+export { createDefaultProofVerifierRegistry } from "./proof/registry.js";
+export { verifyProofBundle } from "./proof/bundle.js";
+export { createRepairPlanner } from "./repair/planner.js";
+export { createMaintenanceTaskEngine } from "./maintenance/task-engine.js";
+export { runPactiumQualityGateProfile } from "./quality/profile-runner.js";

package/src/ledger/signed-head.js

@@ -0,0 +1,204 @@
+import crypto from "node:crypto";
+
+import { PACTIUM_PROTOCOL, PACTIUM_SCHEMA_VERSION } from "../protocol/constants.js";
+import { canonicalEncode, normalizeCanonicalValue } from "../canonical/value.js";
+import { createId, protocolHash } from "../protocol/hashing.js";
+import { asArray, asRecord, nowIso, safeText } from "../shared/records.js";
+import { createVerificationFailure } from "../verification/failure.js";
+import { verifyLedgerConsistencyProof } from "./transparency-log.js";
+
+export function createVerifierManifest(input = {}) {
+  const payload = {
+    protocol: PACTIUM_PROTOCOL,
+    schema: PACTIUM_SCHEMA_VERSION,
+    manifestType: "pactium.verifier-manifest",
+    signers: asArray(input.signers).map((signer) => ({
+      signerId: safeText(signer.signerId),
+      algorithm: safeText(signer.algorithm, "ed25519"),
+      publicKey: safeText(signer.publicKey),
+      validFrom: safeText(signer.validFrom),
+      validTo: safeText(signer.validTo),
+      roles: asArray(signer.roles).map(String)
+    })).filter((signer) => signer.signerId && signer.publicKey),
+    quorum: Math.max(1, Number(input.quorum || 1))
+  };
+  return {
+    ...payload,
+    manifestId: input.manifestId || createId("verifier_manifest", payload),
+    manifestHash: protocolHash("verifier.manifest", payload)
+  };
+}
+
+export function ledgerHeadSigningPayload(head = {}) {
+  return normalizeCanonicalValue({
+    protocol: PACTIUM_PROTOCOL,
+    schema: PACTIUM_SCHEMA_VERSION,
+    ledgerId: head.ledgerId || "pactium-operation-ledger",
+    size: Number(head.size || 0),
+    rootHash: safeText(head.rootHash),
+    root: safeText(head.root),
+    headId: safeText(head.headId),
+    previousHeadId: safeText(head.previousHeadId),
+    createdAt: safeText(head.createdAt)
+  });
+}
+
+export function signLedgerHead(head = {}, {
+  privateKey = "",
+  signerId = "",
+  manifest = null,
+  createdAt = nowIso()
+} = {}) {
+  const resolvedManifest = manifest ? createVerifierManifest(manifest) : null;
+  const payload = ledgerHeadSigningPayload(head);
+  const signature = crypto.sign(null, Buffer.from(canonicalEncode(payload)), privateKey).toString("base64");
+  return {
+    protocol: PACTIUM_PROTOCOL,
+    schema: PACTIUM_SCHEMA_VERSION,
+    signatureType: "pactium.ledger-head-signature",
+    signerId: safeText(signerId),
+    algorithm: "ed25519",
+    manifestId: resolvedManifest?.manifestId || safeText(manifest?.manifestId),
+    manifestHash: resolvedManifest?.manifestHash || safeText(manifest?.manifestHash),
+    headId: safeText(head.headId),
+    signedPayloadHash: protocolHash("ledger.head.signing", payload),
+    signature,
+    createdAt
+  };
+}
+
+export function verifyLedgerHeadSignature(head = {}, manifest = {}, options = {}) {
+  const verifierManifest = manifest?.manifestType === "pactium.verifier-manifest"
+    ? manifest
+    : createVerifierManifest(manifest);
+  const signatures = asArray(options.signatures || head.signatures || (head.signature ? [head.signature] : []));
+  const failures = [];
+  let accepted = 0;
+  const acceptedSigners = new Set();
+  const payload = ledgerHeadSigningPayload(head);
+  const payloadBytes = Buffer.from(canonicalEncode(payload));
+  for (const signature of signatures) {
+    const record = asRecord(signature);
+    const signer = asArray(verifierManifest.signers).find((candidate) => candidate.signerId === record.signerId);
+    if (!signer) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "unknown_signer",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (record.manifestId && record.manifestId !== verifierManifest.manifestId) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "signature_manifest_mismatch",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (record.manifestHash && record.manifestHash !== verifierManifest.manifestHash) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "signature_manifest_mismatch",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (acceptedSigners.has(record.signerId)) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "duplicate_signature_signer",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (signer.algorithm !== "ed25519" || record.algorithm !== "ed25519") {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "unsupported_signature_algorithm",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (!asArray(signer.roles).includes("ledger-head")) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "signer_role_missing",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    if (record.signedPayloadHash !== protocolHash("ledger.head.signing", payload)) {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "bad_signed_head_payload",
+        evidenceRef: record.signerId || ""
+      }));
+      continue;
+    }
+    const ok = crypto.verify(
+      null,
+      payloadBytes,
+      signer.publicKey,
+      Buffer.from(String(record.signature || ""), "base64")
+    );
+    if (ok) {
+      accepted += 1;
+      acceptedSigners.add(record.signerId);
+    }
+    else {
+      failures.push(createVerificationFailure({
+        layer: "ledger-head-signature",
+        code: "bad_head_signature",
+        evidenceRef: record.signerId || ""
+      }));
+    }
+  }
+  if (accepted < Number(verifierManifest.quorum || 1)) {
+    failures.push(createVerificationFailure({
+      layer: "ledger-head-signature",
+      code: "manifest_quorum_not_met",
+      details: { accepted, quorum: verifierManifest.quorum || 1 }
+    }));
+  }
+  return {
+    protocol: PACTIUM_PROTOCOL,
+    ok: failures.length === 0,
+    accepted,
+    failures
+  };
+}
+
+export function advanceTrustedHead({
+  oldHead = {},
+  newHead = {},
+  proof = {},
+  manifest = null,
+  signatures = []
+} = {}) {
+  const failures = [];
+  if (!verifyLedgerConsistencyProof({ oldHead, newHead, proof })) {
+    failures.push(createVerificationFailure({
+      layer: "trusted-head",
+      code: "bad_trusted_head_consistency",
+      message: "New Ledger head does not extend the old trusted head."
+    }));
+  }
+  if (manifest) {
+    const signatureResult = verifyLedgerHeadSignature(newHead, manifest, { signatures });
+    failures.push(...signatureResult.failures);
+  }
+  if (failures.length > 0) {
+    return { protocol: PACTIUM_PROTOCOL, ok: false, failures };
+  }
+  return {
+    protocol: PACTIUM_PROTOCOL,
+    ok: true,
+    trustStoreType: "pactium.trusted-head-store",
+    ledgerId: newHead.ledgerId || oldHead.ledgerId || "pactium-operation-ledger",
+    lastTrustedHead: newHead,
+    verifierManifestRef: manifest?.manifestId || "",
+    updatedAt: nowIso(),
+    failures: []
+  };
+}