settld 0.1.2 → 0.2.0

package/scripts/vendor-contract-test-lib.mjs

@@ -0,0 +1,182 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { canonicalJsonStringify } from "../packages/artifact-verify/src/canonical-json.js";
+import { sha256HexUtf8, verifyHashHexEd25519 } from "../packages/artifact-verify/src/crypto.js";
+import { unzipToTempSafe } from "../packages/artifact-verify/src/safe-unzip.js";
+import { verifyClosePackBundleDir, verifyInvoiceBundleDir } from "../packages/artifact-verify/src/index.js";
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function sha256Hex(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function cmpString(a, b) {
+  const aa = String(a ?? "");
+  const bb = String(b ?? "");
+  if (aa < bb) return -1;
+  if (aa > bb) return 1;
+  return 0;
+}
+
+function normalizeCodeList(list) {
+  const out = [];
+  for (const it of Array.isArray(list) ? list : []) {
+    if (!it || typeof it !== "object") continue;
+    const code = typeof it.code === "string" ? it.code : null;
+    if (!code) continue;
+    out.push(code);
+  }
+  return [...new Set(out)].sort(cmpString);
+}
+
+function trustToEnv(trustJson) {
+  if (!isPlainObject(trustJson)) return { ok: false, error: "trust must be an object" };
+  const governanceRoots = isPlainObject(trustJson.governanceRoots) ? trustJson.governanceRoots : {};
+  const pricingSigners = isPlainObject(trustJson.pricingSigners) ? trustJson.pricingSigners : {};
+  const timeAuthorities = isPlainObject(trustJson.timeAuthorities) ? trustJson.timeAuthorities : {};
+
+  return {
+    ok: true,
+    trust: { governanceRoots, pricingSigners, timeAuthorities },
+    env: {
+      SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON: JSON.stringify(governanceRoots),
+      SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON: JSON.stringify(pricingSigners),
+      SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON: JSON.stringify(timeAuthorities)
+    }
+  };
+}
+
+async function readJsonBestEffort(fp) {
+  try {
+    return JSON.parse(await fs.readFile(fp, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function pricingSignatureV2Check({ bundleDir, bundleType, trust }) {
+  const invoiceRoot = bundleType === "ClosePack.v1" ? path.join(bundleDir, "payload", "invoice_bundle") : bundleDir;
+  const sigPath = path.join(invoiceRoot, "pricing", "pricing_matrix_signatures.json");
+  const pricingPath = path.join(invoiceRoot, "pricing", "pricing_matrix.json");
+
+  const sigJson = await readJsonBestEffort(sigPath);
+  if (!sigJson) return { ok: false, code: "PRICING_MATRIX_SIGNATURE_MISSING", detail: { path: "pricing/pricing_matrix_signatures.json" } };
+
+  const schemaVersion = String(sigJson.schemaVersion ?? "");
+  if (schemaVersion !== "PricingMatrixSignatures.v2") {
+    return { ok: false, code: "PRICING_MATRIX_SIGNATURE_SCHEMA_UNEXPECTED", detail: { schemaVersion: sigJson.schemaVersion ?? null } };
+  }
+  const declaredHash = typeof sigJson.pricingMatrixCanonicalHash === "string" ? sigJson.pricingMatrixCanonicalHash : null;
+  if (!declaredHash || !/^[0-9a-f]{64}$/.test(declaredHash)) {
+    return { ok: false, code: "PRICING_MATRIX_SIGNATURE_HASH_INVALID", detail: { pricingMatrixCanonicalHash: sigJson.pricingMatrixCanonicalHash ?? null } };
+  }
+
+  const pricingJson = await readJsonBestEffort(pricingPath);
+  if (!pricingJson) return { ok: false, code: "PRICING_MATRIX_MISSING", detail: { path: "pricing/pricing_matrix.json" } };
+  const actualHash = sha256HexUtf8(canonicalJsonStringify(pricingJson));
+  if (actualHash !== declaredHash) {
+    return { ok: false, code: "PRICING_MATRIX_SIGNATURE_PAYLOAD_MISMATCH", detail: { expected: actualHash, actual: declaredHash } };
+  }
+
+  const signatures = Array.isArray(sigJson.signatures) ? sigJson.signatures : [];
+  const trustedPricingSigners = trust && isPlainObject(trust.pricingSigners) ? trust.pricingSigners : {};
+
+  const signerKeyIds = [];
+  let validCount = 0;
+  for (const s of signatures) {
+    if (!s || typeof s !== "object") continue;
+    const signerKeyId = typeof s.signerKeyId === "string" ? s.signerKeyId : null;
+    const signatureBase64 = typeof s.signature === "string" ? s.signature : null;
+    if (!signerKeyId || !signatureBase64) continue;
+    signerKeyIds.push(signerKeyId);
+    const publicKeyPem = typeof trustedPricingSigners[signerKeyId] === "string" ? trustedPricingSigners[signerKeyId] : null;
+    if (!publicKeyPem) continue;
+    if (verifyHashHexEd25519({ hashHex: actualHash, signatureBase64, publicKeyPem })) validCount += 1;
+  }
+  signerKeyIds.sort(cmpString);
+
+  if (validCount < 1) {
+    return { ok: false, code: "PRICING_MATRIX_SIGNATURE_INVALID", detail: { signerKeyIds: [...new Set(signerKeyIds)] } };
+  }
+
+  return { ok: true, schemaVersion, signerKeyIds: [...new Set(signerKeyIds)], validCount };
+}
+
+export async function runVendorContractTest({ bundlePath, trustPath, expect }) {
+  if (!bundlePath || typeof bundlePath !== "string") throw new TypeError("bundlePath is required");
+  if (!trustPath || typeof trustPath !== "string") throw new TypeError("trustPath is required");
+  if (expect !== "strict-pass") throw new Error("unsupported expect (only strict-pass)");
+
+  const trustRaw = JSON.parse(await fs.readFile(trustPath, "utf8"));
+  const trustParsed = trustToEnv(trustRaw);
+  if (!trustParsed.ok) {
+    return { schemaVersion: "VendorContractTest.v1", ok: false, code: "INVALID_TRUST_FILE", detail: trustParsed };
+  }
+
+  const zipBytes = await fs.readFile(bundlePath);
+  const zipSha256 = sha256Hex(zipBytes);
+
+  const unzip = await unzipToTempSafe({ zipPath: path.resolve(process.cwd(), bundlePath) });
+  if (!unzip.ok) return { schemaVersion: "VendorContractTest.v1", ok: false, code: "ZIP_REJECTED", detail: unzip };
+
+  let bundleType = null;
+  let manifestHash = null;
+  let verifyRes = null;
+  let pricingCheck = null;
+
+  try {
+    const header = await readJsonBestEffort(path.join(unzip.dir, "settld.json"));
+    bundleType = typeof header?.type === "string" ? header.type : null;
+
+    const envKeys = [
+      "SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON",
+      "SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON",
+      "SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON"
+    ];
+    const old = {};
+    for (const k of envKeys) old[k] = process.env[k];
+    process.env.SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON = trustParsed.env.SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON;
+    process.env.SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON = trustParsed.env.SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON;
+    process.env.SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON = trustParsed.env.SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON;
+    try {
+      if (bundleType === "ClosePack.v1") verifyRes = await verifyClosePackBundleDir({ dir: unzip.dir, strict: true, hashConcurrency: 16 });
+      else if (bundleType === "InvoiceBundle.v1") verifyRes = await verifyInvoiceBundleDir({ dir: unzip.dir, strict: true, hashConcurrency: 16 });
+      else verifyRes = { ok: false, error: "unsupported bundle type", type: bundleType, warnings: [] };
+    } finally {
+      for (const k of envKeys) {
+        if (old[k] === undefined) delete process.env[k];
+        else process.env[k] = old[k];
+      }
+    }
+
+    manifestHash = typeof verifyRes?.manifestHash === "string" ? verifyRes.manifestHash : null;
+    if (verifyRes && verifyRes.ok === true) pricingCheck = await pricingSignatureV2Check({ bundleDir: unzip.dir, bundleType, trust: trustParsed.trust });
+  } finally {
+    await fs.rm(unzip.dir, { recursive: true, force: true });
+  }
+
+  const warnings = normalizeCodeList(verifyRes?.warnings ?? []);
+  const strictVerifyOk = Boolean(verifyRes && verifyRes.ok === true) && warnings.length === 0;
+  const pricingOk = Boolean(pricingCheck && pricingCheck.ok === true);
+  const ok = strictVerifyOk && pricingOk;
+
+  return {
+    schemaVersion: "VendorContractTest.v1",
+    ok,
+    expect,
+    bundle: { type: bundleType, zipSha256, zipBytes: zipBytes.length, manifestHash },
+    strict: {
+      ok: strictVerifyOk,
+      verificationOk: Boolean(verifyRes && verifyRes.ok === true),
+      error: verifyRes && verifyRes.ok === false ? verifyRes.error ?? "FAILED" : null,
+      warnings
+    },
+    pricingSignatureV2: pricingCheck
+  };
+}
+

package/scripts/vendor-contract-test.mjs

@@ -0,0 +1,55 @@
+import { runVendorContractTest } from "./vendor-contract-test-lib.mjs";
+
+// `node --test` treats `**/*test*.mjs` as a test file. This script is a CLI,
+// so bail out early when invoked without CLI flags.
+if (!process.argv.includes("--bundle") && !process.argv.includes("--trust")) process.exit(0);
+
+function usage() {
+  // eslint-disable-next-line no-console
+  console.error(
+    [
+      "usage:",
+      "  node scripts/vendor-contract-test.mjs --bundle <bundle.zip> --trust <trust.json> --expect strict-pass",
+      "",
+      "outputs:",
+      "  deterministic JSON to stdout; exit code 0 on expectation match."
+    ].join("\n")
+  );
+  process.exit(2);
+}
+
+function parse(argv) {
+  const out = { bundlePath: null, trustPath: null, expect: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--bundle") {
+      out.bundlePath = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a === "--trust") {
+      out.trustPath = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a === "--expect") {
+      out.expect = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a === "--help" || a === "-h") usage();
+    usage();
+  }
+  if (!out.bundlePath || !out.trustPath || !out.expect) usage();
+  if (out.expect !== "strict-pass") usage();
+  return out;
+}
+
+async function main() {
+  const args = parse(process.argv.slice(2));
+  const out = await runVendorContractTest({ bundlePath: args.bundlePath, trustPath: args.trustPath, expect: args.expect });
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  process.exit(out.ok ? 0 : 1);
+}
+
+await main();

package/scripts/vercel/build-mkdocs.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ ! -x ".vercel-venv/bin/mkdocs" ]; then
+  echo "MkDocs venv not found; running install step first..."
+  bash scripts/vercel/install-mkdocs.sh
+fi
+
+.vercel-venv/bin/mkdocs build --strict --config-file mkdocs.yml

package/scripts/vercel/ignore-mkdocs.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Vercel "ignoreCommand" contract:
+# - exit 0 => skip deployment
+# - exit 1 => continue with deployment
+
+if ! git rev-parse --verify HEAD^ >/dev/null 2>&1; then
+  # No parent commit context available; build to stay safe.
+  exit 1
+fi
+
+if git diff --quiet HEAD^ HEAD -- \
+  docs/ \
+  mkdocs.yml \
+  scripts/vercel/ \
+  .github/workflows/release.yml \
+  .github/workflows/tests.yml \
+  .github/pull_request_template.md; then
+  # No docs/mkdocs pipeline changes; skip root docs deployment.
+  exit 0
+fi
+
+# Relevant docs/deploy files changed; run deployment.
+exit 1

package/scripts/vercel/install-mkdocs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+python3 -m venv .vercel-venv
+.vercel-venv/bin/python -m pip install --upgrade pip setuptools wheel
+.vercel-venv/bin/pip install mkdocs mkdocs-material

package/scripts/verify-pg.js

@@ -0,0 +1,217 @@
+import { logger } from "../src/core/log.js";
+import { createPgPool } from "../src/db/pg.js";
+import { keyIdFromPublicKeyPem } from "../src/core/crypto.js";
+import { verifyChainedEvents } from "../src/core/event-chain.js";
+import { verifyArtifactHash, verifySettlementBalances } from "../packages/artifact-verify/src/index.js";
+
+function parsePositiveIntEnv(name, fallback) {
+  const raw = process.env[name] ?? null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function parseNonNegativeIntEnv(name, fallback) {
+  const raw = process.env[name] ?? null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+const databaseUrl = process.env.DATABASE_URL ?? null;
+if (!databaseUrl) {
+  process.stderr.write("DATABASE_URL is required\n");
+  process.exit(2);
+}
+
+const schema = process.env.PROXY_PG_SCHEMA ?? "public";
+const maxStreams = parsePositiveIntEnv("VERIFY_MAX_STREAMS", 100);
+const maxArtifacts = parsePositiveIntEnv("VERIFY_MAX_ARTIFACTS", 100);
+const maxLedgerEntries = parseNonNegativeIntEnv("VERIFY_MAX_LEDGER_ENTRIES", 0); // 0 = all
+
+const pool = await createPgPool({ databaseUrl, schema });
+
+async function loadPublicKeyByKeyId() {
+  const map = new Map();
+
+  try {
+    const signer = await pool.query("SELECT public_key_pem FROM server_signer WHERE id = 1");
+    if (signer.rows.length) {
+      const publicKeyPem = String(signer.rows[0].public_key_pem);
+      const keyId = keyIdFromPublicKeyPem(publicKeyPem);
+      map.set(keyId, publicKeyPem);
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const res = await pool.query("SELECT key_id, public_key_pem FROM public_keys");
+    for (const row of res.rows) {
+      if (!row?.key_id || !row?.public_key_pem) continue;
+      map.set(String(row.key_id), String(row.public_key_pem));
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const res = await pool.query("SELECT key_id, public_key_pem FROM signer_keys");
+    for (const row of res.rows) {
+      if (!row?.key_id || !row?.public_key_pem) continue;
+      map.set(String(row.key_id), String(row.public_key_pem));
+    }
+  } catch {
+    // ignore
+  }
+
+  return map;
+}
+
+function journalEntryBalances(entry) {
+  const postings = Array.isArray(entry?.postings) ? entry.postings : [];
+  let sum = 0;
+  for (const p of postings) {
+    const amt = p?.amountCents;
+    if (!Number.isFinite(amt) || !Number.isSafeInteger(amt)) return { ok: false, error: "invalid posting amount" };
+    sum += amt;
+  }
+  if (sum !== 0) return { ok: false, error: "unbalanced", sum };
+  return { ok: true };
+}
+
+async function verifyLedger() {
+  const balancesByTenant = new Map(); // tenantId -> Map(accountId -> balance)
+  let checked = 0;
+
+  const limitClause = maxLedgerEntries > 0 ? "LIMIT $1" : "";
+  const args = maxLedgerEntries > 0 ? [maxLedgerEntries] : [];
+  const res = await pool.query(
+    `
+      SELECT tenant_id, entry_id, entry_json
+      FROM ledger_entries
+      ORDER BY tenant_id ASC, entry_id ASC
+      ${limitClause}
+    `,
+    args
+  );
+
+  for (const row of res.rows) {
+    const tenantId = String(row.tenant_id ?? "tenant_default");
+    const entryId = String(row.entry_id ?? "");
+    const entry = row.entry_json ?? null;
+    const ok = journalEntryBalances(entry);
+    if (!ok.ok) {
+      throw new Error(`ledger entry ${tenantId}:${entryId} invalid: ${ok.error}${ok.sum !== undefined ? ` sum=${ok.sum}` : ""}`);
+    }
+    checked += 1;
+
+    if (!balancesByTenant.has(tenantId)) balancesByTenant.set(tenantId, new Map());
+    const b = balancesByTenant.get(tenantId);
+    for (const p of entry.postings) {
+      const accountId = String(p.accountId);
+      b.set(accountId, (b.get(accountId) ?? 0) + p.amountCents);
+    }
+  }
+
+  const balances = await pool.query("SELECT tenant_id, account_id, balance_cents FROM ledger_balances");
+  for (const row of balances.rows) {
+    const tenantId = String(row.tenant_id ?? "tenant_default");
+    const accountId = String(row.account_id ?? "");
+    const db = Number(row.balance_cents ?? 0);
+    const expected = balancesByTenant.get(tenantId)?.get(accountId) ?? 0;
+    if (db !== expected) {
+      throw new Error(`ledger_balances mismatch ${tenantId}:${accountId}: expected ${expected}, got ${db}`);
+    }
+  }
+
+  return { checked };
+}
+
+async function verifyArtifacts() {
+  const res = await pool.query(
+    `
+      SELECT tenant_id, artifact_id, artifact_hash, artifact_json
+      FROM artifacts
+      ORDER BY created_at DESC
+      LIMIT $1
+    `,
+    [maxArtifacts]
+  );
+
+  let checked = 0;
+  for (const row of res.rows) {
+    const tenantId = String(row.tenant_id ?? "tenant_default");
+    const artifactId = String(row.artifact_id ?? "");
+    const artifactHash = row.artifact_hash ? String(row.artifact_hash) : null;
+    const artifact = row.artifact_json ?? null;
+    if (!artifact || typeof artifact !== "object") throw new Error(`artifact ${tenantId}:${artifactId} missing artifact_json`);
+    if (artifactHash && String(artifact.artifactHash ?? "") !== artifactHash) {
+      throw new Error(`artifact hash column mismatch for ${tenantId}:${artifactId}`);
+    }
+    const h = verifyArtifactHash(artifact);
+    if (!h.ok) throw new Error(`artifact ${tenantId}:${artifactId} hash verify failed: ${h.error}`);
+    const s = verifySettlementBalances(artifact);
+    if (!s.ok) throw new Error(`artifact ${tenantId}:${artifactId} settlement verify failed: ${s.error}`);
+    checked += 1;
+  }
+
+  return { checked };
+}
+
+async function verifyStreams() {
+  const publicKeyByKeyId = await loadPublicKeyByKeyId();
+
+  const streams = await pool.query(
+    `
+      SELECT tenant_id, aggregate_type, aggregate_id
+      FROM snapshots
+      ORDER BY tenant_id ASC, aggregate_type ASC, aggregate_id ASC
+      LIMIT $1
+    `,
+    [maxStreams]
+  );
+
+  let checked = 0;
+  for (const row of streams.rows) {
+    const tenantId = String(row.tenant_id ?? "tenant_default");
+    const aggregateType = String(row.aggregate_type ?? "");
+    const aggregateId = String(row.aggregate_id ?? "");
+
+    const res = await pool.query(
+      `
+        SELECT event_json
+        FROM events
+        WHERE tenant_id = $1 AND aggregate_type = $2 AND aggregate_id = $3
+        ORDER BY seq ASC
+      `,
+      [tenantId, aggregateType, aggregateId]
+    );
+    const events = res.rows.map((r) => r.event_json).filter(Boolean);
+    const verify = verifyChainedEvents(events, { publicKeyByKeyId });
+    if (!verify.ok) throw new Error(`chain verify failed for ${tenantId}:${aggregateType}:${aggregateId}: ${verify.error}`);
+    checked += 1;
+  }
+
+  return { checked };
+}
+
+const startedMs = Date.now();
+try {
+  const ledger = await verifyLedger();
+  const artifacts = await verifyArtifacts();
+  const streams = await verifyStreams();
+
+  const runtimeMs = Date.now() - startedMs;
+  logger.info("verify.pg.ok", { schema, runtimeMs, ledger, artifacts, streams });
+  process.exit(0);
+} catch (err) {
+  const runtimeMs = Date.now() - startedMs;
+  logger.error("verify.pg.failed", { schema, runtimeMs, err });
+  process.exit(1);
+} finally {
+  await pool.end();
+}
+