settld 0.1.2 → 0.2.0

package/src/core/zk-verifier.js

@@ -0,0 +1,300 @@
+const SUPPORTED_X402_ZK_PROTOCOLS = new Set(["groth16", "plonk", "stark"]);
+const CRYPTOGRAPHIC_ZK_PROTOCOLS = new Set(["groth16", "plonk"]);
+
+let snarkJsPromise = null;
+
+function normalizeOptionalSha256(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "string") return null;
+  const normalized = value.trim().toLowerCase();
+  return /^[0-9a-f]{64}$/.test(normalized) ? normalized : null;
+}
+
+function normalizeOptionalRef(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+}
+
+async function loadSnarkJs() {
+  if (!snarkJsPromise) {
+    snarkJsPromise = import("snarkjs");
+  }
+  return await snarkJsPromise;
+}
+
+async function terminateSnarkCurves() {
+  const candidates = [globalThis?.curve_bn128, globalThis?.curve_bls12381];
+  for (const curve of candidates) {
+    if (curve && typeof curve.terminate === "function") {
+      try {
+        await curve.terminate();
+      } catch {
+        // Best-effort cleanup to prevent lingering worker MessagePorts.
+      }
+    }
+  }
+}
+
+export function listSupportedX402ZkProofProtocols() {
+  return Array.from(SUPPORTED_X402_ZK_PROTOCOLS.values());
+}
+
+export async function verifyX402ExecutionProofV1({
+  proof = null,
+  verificationKey = null,
+  expectedVerificationKeyRef = null,
+  requiredProtocol = null,
+  expectedBindings = null,
+  requireBindings = false,
+  protocolAdapters = null
+} = {}) {
+  if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+    return {
+      present: false,
+      status: "not_provided",
+      verified: null,
+      code: null,
+      message: null
+    };
+  }
+
+  const protocol = typeof proof.protocol === "string" ? proof.protocol.trim().toLowerCase() : "";
+  if (!protocol || !SUPPORTED_X402_ZK_PROTOCOLS.has(protocol)) {
+    return {
+      present: true,
+      protocol: protocol || null,
+      status: "unsupported_protocol",
+      verified: false,
+      code: "X402_ZK_PROOF_PROTOCOL_UNSUPPORTED",
+      message: "proof.protocol is not supported"
+    };
+  }
+
+  const requiredProtocolNormalized = typeof requiredProtocol === "string" ? requiredProtocol.trim().toLowerCase() : null;
+  if (requiredProtocolNormalized && protocol !== requiredProtocolNormalized) {
+    return {
+      present: true,
+      protocol,
+      status: "protocol_mismatch",
+      verified: false,
+      code: "X402_ZK_PROOF_PROTOCOL_MISMATCH",
+      message: "proof protocol does not match required policy protocol",
+      details: {
+        requiredProtocol: requiredProtocolNormalized
+      }
+    };
+  }
+
+  if (!CRYPTOGRAPHIC_ZK_PROTOCOLS.has(protocol)) {
+    return {
+      present: true,
+      protocol,
+      status: "unsupported_protocol",
+      verified: false,
+      code: "X402_ZK_PROOF_PROTOCOL_UNSUPPORTED",
+      message: "proof protocol is not supported by verifier"
+    };
+  }
+
+  const proofVerificationKey =
+    proof.verificationKey && typeof proof.verificationKey === "object" && !Array.isArray(proof.verificationKey)
+      ? proof.verificationKey
+      : null;
+  const policyVerificationKey =
+    verificationKey && typeof verificationKey === "object" && !Array.isArray(verificationKey) ? verificationKey : null;
+  const effectiveVerificationKey = policyVerificationKey ?? proofVerificationKey;
+  if (!effectiveVerificationKey) {
+    return {
+      present: true,
+      protocol,
+      status: "verification_key_missing",
+      verified: false,
+      code: "X402_ZK_PROOF_VERIFICATION_KEY_MISSING",
+      message: "proof verification key is required"
+    };
+  }
+
+  const proofVerificationKeyRef = normalizeOptionalRef(proof.verificationKeyRef ?? null);
+  const expectedVerificationKeyRefNormalized = normalizeOptionalRef(expectedVerificationKeyRef);
+  if (
+    expectedVerificationKeyRefNormalized &&
+    proofVerificationKeyRef &&
+    proofVerificationKeyRef !== expectedVerificationKeyRefNormalized
+  ) {
+    return {
+      present: true,
+      protocol,
+      status: "verification_key_ref_mismatch",
+      verified: false,
+      code: "X402_ZK_PROOF_VERIFICATION_KEY_REF_MISMATCH",
+      message: "proof verification key ref does not match policy",
+      details: {
+        expectedVerificationKeyRef: expectedVerificationKeyRefNormalized,
+        verificationKeyRef: proofVerificationKeyRef
+      }
+    };
+  }
+  if (expectedVerificationKeyRefNormalized && !proofVerificationKeyRef && !proofVerificationKey) {
+    return {
+      present: true,
+      protocol,
+      status: "verification_key_ref_missing",
+      verified: false,
+      code: "X402_ZK_PROOF_VERIFICATION_KEY_REF_REQUIRED",
+      message: "proof verification key ref is required by policy",
+      details: {
+        expectedVerificationKeyRef: expectedVerificationKeyRefNormalized
+      }
+    };
+  }
+
+  const expected = expectedBindings && typeof expectedBindings === "object" && !Array.isArray(expectedBindings) ? expectedBindings : null;
+  if (expected) {
+    const checks = [
+      {
+        proofField: "statementHashSha256",
+        expectedField: "statementHashSha256",
+        mismatchCode: "X402_ZK_PROOF_STATEMENT_HASH_MISMATCH",
+        missingCode: "X402_ZK_PROOF_STATEMENT_HASH_REQUIRED"
+      },
+      {
+        proofField: "inputDigestSha256",
+        expectedField: "inputDigestSha256",
+        mismatchCode: "X402_ZK_PROOF_INPUT_DIGEST_MISMATCH",
+        missingCode: "X402_ZK_PROOF_INPUT_DIGEST_REQUIRED"
+      },
+      {
+        proofField: "outputDigestSha256",
+        expectedField: "outputDigestSha256",
+        mismatchCode: "X402_ZK_PROOF_OUTPUT_DIGEST_MISMATCH",
+        missingCode: "X402_ZK_PROOF_OUTPUT_DIGEST_REQUIRED"
+      }
+    ];
+    for (const check of checks) {
+      const expectedValue = normalizeOptionalSha256(expected[check.expectedField]);
+      if (!expectedValue) continue;
+      const proofValue = normalizeOptionalSha256(proof[check.proofField]);
+      if (!proofValue) {
+        if (requireBindings) {
+          return {
+            present: true,
+            protocol,
+            status: "binding_missing",
+            verified: false,
+            code: check.missingCode,
+            message: `${check.proofField} is required for binding`
+          };
+        }
+        continue;
+      }
+      if (proofValue !== expectedValue) {
+        return {
+          present: true,
+          protocol,
+          status: "binding_mismatch",
+          verified: false,
+          code: check.mismatchCode,
+          message: `${check.proofField} does not match expected binding`,
+          details: {
+            expectedField: check.expectedField
+          }
+        };
+      }
+    }
+  }
+
+  if (!Array.isArray(proof.publicSignals)) {
+    return {
+      present: true,
+      protocol,
+      status: "malformed",
+      verified: false,
+      code: "X402_ZK_PROOF_PUBLIC_SIGNALS_INVALID",
+      message: "proof.publicSignals must be an array"
+    };
+  }
+  if (!proof.proofData || typeof proof.proofData !== "object" || Array.isArray(proof.proofData)) {
+    return {
+      present: true,
+      protocol,
+      status: "malformed",
+      verified: false,
+      code: "X402_ZK_PROOF_DATA_INVALID",
+      message: "proof.proofData must be an object"
+    };
+  }
+
+  const adapterMap =
+    protocolAdapters && typeof protocolAdapters === "object" && !Array.isArray(protocolAdapters) ? protocolAdapters : null;
+  let verifierFn = adapterMap && typeof adapterMap[protocol] === "function" ? adapterMap[protocol] : null;
+  if (!verifierFn) {
+    let snarkjs;
+    try {
+      snarkjs = await loadSnarkJs();
+    } catch (err) {
+      return {
+        present: true,
+        protocol,
+        status: "verifier_unavailable",
+        verified: false,
+        code: "X402_ZK_VERIFIER_UNAVAILABLE",
+        message: "snarkjs verifier is unavailable",
+        details: {
+          error: err?.message ?? String(err ?? "")
+        }
+      };
+    }
+    if (protocol === "groth16") verifierFn = snarkjs?.groth16?.verify;
+    if (protocol === "plonk") verifierFn = snarkjs?.plonk?.verify;
+  }
+  if (typeof verifierFn !== "function") {
+    return {
+      present: true,
+      protocol,
+      status: "verifier_unavailable",
+      verified: false,
+      code: "X402_ZK_VERIFIER_UNAVAILABLE",
+      message: `no verifier is configured for protocol ${protocol}`
+    };
+  }
+
+  try {
+    const ok = await verifierFn(effectiveVerificationKey, proof.publicSignals, proof.proofData);
+    if (ok === true) {
+      return {
+        present: true,
+        protocol,
+        status: "verified",
+        verified: true,
+        code: null,
+        message: null
+      };
+    }
+    return {
+      present: true,
+      protocol,
+      status: "invalid",
+      verified: false,
+      code: "X402_ZK_PROOF_INVALID",
+      message: "proof verification failed"
+    };
+  } catch (err) {
+    return {
+      present: true,
+      protocol,
+      status: "invalid",
+      verified: false,
+      code: "X402_ZK_PROOF_INVALID",
+      message: "proof verification failed",
+      details: {
+        error: err?.message ?? String(err ?? "")
+      }
+    };
+  } finally {
+    if (!adapterMap) {
+      await terminateSnarkCurves();
+    }
+  }
+}

package/src/db/migrations/029_reputation_event_index.sql

@@ -0,0 +1,54 @@
+-- ReputationEvent.v1 index table for fast `(tenant, agent, tool?, occurredAt)` queries.
+-- Keeps immutable artifact payload in `artifacts`, while indexing query-critical keys.
+
+CREATE TABLE IF NOT EXISTS reputation_event_index (
+  tenant_id TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  artifact_hash TEXT NOT NULL,
+  subject_agent_id TEXT NOT NULL,
+  subject_tool_id TEXT,
+  occurred_at TIMESTAMPTZ NOT NULL,
+  event_kind TEXT NOT NULL,
+  source_kind TEXT NOT NULL,
+  source_hash TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, artifact_id),
+  FOREIGN KEY (tenant_id, artifact_id) REFERENCES artifacts (tenant_id, artifact_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS reputation_event_index_by_subject_tool_time
+  ON reputation_event_index (tenant_id, subject_agent_id, subject_tool_id, occurred_at DESC, artifact_id DESC);
+
+CREATE INDEX IF NOT EXISTS reputation_event_index_by_subject_time
+  ON reputation_event_index (tenant_id, subject_agent_id, occurred_at DESC, artifact_id DESC);
+
+CREATE INDEX IF NOT EXISTS reputation_event_index_by_tenant_time
+  ON reputation_event_index (tenant_id, occurred_at DESC, artifact_id DESC);
+
+-- Backfill index rows from already-persisted ReputationEvent artifacts.
+INSERT INTO reputation_event_index (
+  tenant_id,
+  artifact_id,
+  artifact_hash,
+  subject_agent_id,
+  subject_tool_id,
+  occurred_at,
+  event_kind,
+  source_kind,
+  source_hash
+)
+SELECT
+  a.tenant_id,
+  a.artifact_id,
+  a.artifact_hash,
+  a.artifact_json->'subject'->>'agentId' AS subject_agent_id,
+  NULLIF(a.artifact_json->'subject'->>'toolId', '') AS subject_tool_id,
+  a.created_at AS occurred_at,
+  lower(COALESCE(a.artifact_json->>'eventKind', 'unknown')) AS event_kind,
+  lower(COALESCE(a.artifact_json->'sourceRef'->>'kind', 'unknown')) AS source_kind,
+  NULLIF(lower(a.artifact_json->'sourceRef'->>'hash'), '') AS source_hash
+FROM artifacts a
+WHERE a.artifact_type = 'ReputationEvent.v1'
+  AND jsonb_typeof(a.artifact_json) = 'object'
+  AND COALESCE(a.artifact_json->'subject'->>'agentId', '') <> ''
+ON CONFLICT (tenant_id, artifact_id) DO NOTHING;

package/src/db/migrations/030_artifacts_source_event_unique_job_only.sql

@@ -0,0 +1,15 @@
+-- v1.??: fix artifact uniqueness to apply only to job-scoped artifacts.
+--
+-- The original unique index enforced one artifact per (tenant_id, job_id, artifact_type, source_event_id) whenever
+-- source_event_id <> ''. For non-job artifacts we persist with job_id = '' (for example PartyStatement.v1 and
+-- PayoutInstruction.v1 during month-close), this incorrectly blocks multiple artifacts of the same type generated from
+-- the same month-close event.
+--
+-- The invariant we actually want is: for job-scoped artifacts (job_id <> ''), prevent duplicates per source event.
+
+DROP INDEX IF EXISTS artifacts_unique_by_job_type_source_event;
+
+CREATE UNIQUE INDEX IF NOT EXISTS artifacts_unique_by_job_type_source_event
+  ON artifacts (tenant_id, job_id, artifact_type, source_event_id)
+  WHERE source_event_id <> '' AND job_id <> '';
+

package/src/db/pg.js

@@ -93,13 +93,24 @@ export async function createPgPool({ databaseUrl, schema = "public" } = {}) {
   const pool = new Pool({ connectionString: databaseUrl });
 
   if (schema !== "public") {
-    try {
-      await pool.query(`CREATE SCHEMA ${quoteIdent(schema)}`);
-    } catch (err) {
-      const duplicateSchema = err?.code === "42P06" || err?.code === "23505";
-      if (!duplicateSchema) throw err;
-      const existsRes = await pool.query("SELECT 1 FROM pg_namespace WHERE nspname = $1 LIMIT 1", [schema]);
-      if (!existsRes.rows.length) throw err;
+    const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    const createSchemaSql = `CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`;
+    // Concurrency-safe: docker-compose may start multiple processes (api + maintenance)
+    // that race to initialize the same schema.
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+      try {
+        await pool.query(createSchemaSql);
+        break;
+      } catch (err) {
+        // Postgres documents that IF NOT EXISTS can still raise errors under concurrent creation.
+        // In practice we can see 23505 (unique violation on pg_namespace) or 42P06 (duplicate schema).
+        const code = typeof err?.code === "string" ? err.code : "";
+        if (code !== "23505" && code !== "42P06") throw err;
+        const exists = await pool.query("SELECT 1 FROM pg_namespace WHERE nspname = $1 LIMIT 1", [schema]);
+        if (exists?.rowCount) break;
+        if (attempt === 5) throw err;
+        await wait(25 * (attempt + 1));
+      }
     }
   }