settld 0.1.2 → 0.2.0

package/src/core/settlement-verifier.js

@@ -0,0 +1,335 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const SETTLEMENT_VERIFICATION_STATUS = Object.freeze({
+  GREEN: "green",
+  AMBER: "amber",
+  RED: "red"
+});
+
+export const SETTLEMENT_VERIFIER_SOURCE = Object.freeze({
+  DETERMINISTIC_LATENCY_THRESHOLD_V1: "verifier://settld/deterministic/latency-threshold-v1",
+  DETERMINISTIC_SCHEMA_CHECK_V1: "verifier://settld/deterministic/schema-check-v1",
+  // Deprecated alias retained for backward compatibility with pre-release adopters.
+  DETERMINISTIC_JSONSCHEMA_V1: "verifier://settld/deterministic/jsonschema-v1"
+});
+
+const ALLOWED_STATUSES = new Set(Object.values(SETTLEMENT_VERIFICATION_STATUS));
+
+const DEFAULT_VERIFIER_REF = Object.freeze({
+  verifierId: "settld.policy-engine",
+  verifierVersion: "v1",
+  verifierHash: null
+});
+
+const DETERMINISTIC_LATENCY_VERIFIER = Object.freeze({
+  source: SETTLEMENT_VERIFIER_SOURCE.DETERMINISTIC_LATENCY_THRESHOLD_V1,
+  verifierId: "settld.deterministic.latency-threshold",
+  verifierVersion: "v1",
+  modality: "deterministic"
+});
+
+const DETERMINISTIC_SCHEMA_CHECK_VERIFIER = Object.freeze({
+  source: SETTLEMENT_VERIFIER_SOURCE.DETERMINISTIC_SCHEMA_CHECK_V1,
+  legacySource: SETTLEMENT_VERIFIER_SOURCE.DETERMINISTIC_JSONSCHEMA_V1,
+  verifierId: "settld.deterministic.schema-check",
+  verifierVersion: "v1",
+  modality: "deterministic"
+});
+
+function normalizeNullableLowerString(value) {
+  if (value === null || value === undefined) return null;
+  const out = String(value).trim().toLowerCase();
+  return out === "" ? null : out;
+}
+
+function normalizeVerificationStatus(value, fallback = SETTLEMENT_VERIFICATION_STATUS.AMBER) {
+  const normalized = normalizeNullableLowerString(value);
+  if (normalized && ALLOWED_STATUSES.has(normalized)) return normalized;
+  return fallback;
+}
+
+function normalizeVerifierSource(value) {
+  const normalized = normalizeNullableLowerString(value);
+  if (!normalized) return null;
+  return normalized.replace(/\/+$/, "");
+}
+
+function normalizeVerifierSourceBase(value) {
+  const normalized = normalizeVerifierSource(value);
+  if (!normalized) return null;
+  const [withoutQuery] = normalized.split("?");
+  const [withoutFragment] = String(withoutQuery ?? "").split("#");
+  return String(withoutFragment ?? "").replace(/\/+$/, "") || null;
+}
+
+function toSafeNonNegativeInt(value) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) return null;
+  return n;
+}
+
+function parseDeterministicSchemaCheckConfig(source) {
+  const defaults = {
+    latencyMaxMs: 1200,
+    requireSettlementReleaseRatePct: false
+  };
+  if (!source) return defaults;
+  try {
+    const parsed = new URL(source);
+    const latencyMaxRaw = parsed.searchParams.get("latencymaxms");
+    const latencyMaxMs = toSafeNonNegativeInt(latencyMaxRaw);
+    const requireReleaseRateRaw = String(parsed.searchParams.get("requiresettlementreleaseratepct") ?? "")
+      .trim()
+      .toLowerCase();
+    const requireSettlementReleaseRatePct =
+      requireReleaseRateRaw === "1" || requireReleaseRateRaw === "true" || requireReleaseRateRaw === "yes";
+    return {
+      latencyMaxMs: latencyMaxMs ?? defaults.latencyMaxMs,
+      requireSettlementReleaseRatePct
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+function computeVerifierHash({ verifierId, verifierVersion, source }) {
+  const descriptor = normalizeForCanonicalJson(
+    {
+      schemaVersion: "SettlementVerifierDescriptor.v1",
+      verifierId: String(verifierId),
+      verifierVersion: String(verifierVersion),
+      source: String(source)
+    },
+    { path: "$" }
+  );
+  return sha256Hex(canonicalJsonStringify(descriptor));
+}
+
+function evaluateDeterministicLatencyThreshold({ run, verification }) {
+  const runStatus = normalizeNullableLowerString(run?.status);
+  if (runStatus === "failed") {
+    return {
+      verificationStatus: SETTLEMENT_VERIFICATION_STATUS.RED,
+      reasonCodes: ["verifier_plugin_run_failed"],
+      summary: { latencyMs: null, thresholdGreenMs: 1000, thresholdRedMs: 4000 }
+    };
+  }
+
+  const latencyMs =
+    toSafeNonNegativeInt(run?.metrics?.latencyMs) ??
+    toSafeNonNegativeInt(verification?.durationMs) ??
+    null;
+  const thresholdGreenMs = 1000;
+  const thresholdRedMs = 4000;
+
+  if (latencyMs === null) {
+    return {
+      verificationStatus: SETTLEMENT_VERIFICATION_STATUS.AMBER,
+      reasonCodes: ["verifier_plugin_latency_missing"],
+      summary: { latencyMs: null, thresholdGreenMs, thresholdRedMs }
+    };
+  }
+
+  if (latencyMs <= thresholdGreenMs) {
+    return {
+      verificationStatus: SETTLEMENT_VERIFICATION_STATUS.GREEN,
+      reasonCodes: [],
+      summary: { latencyMs, thresholdGreenMs, thresholdRedMs }
+    };
+  }
+  if (latencyMs >= thresholdRedMs) {
+    return {
+      verificationStatus: SETTLEMENT_VERIFICATION_STATUS.RED,
+      reasonCodes: ["verifier_plugin_latency_above_red_threshold"],
+      summary: { latencyMs, thresholdGreenMs, thresholdRedMs }
+    };
+  }
+  return {
+    verificationStatus: SETTLEMENT_VERIFICATION_STATUS.AMBER,
+    reasonCodes: ["verifier_plugin_latency_between_thresholds"],
+    summary: { latencyMs, thresholdGreenMs, thresholdRedMs }
+  };
+}
+
+function evaluateDeterministicSchemaCheck({ run, verification, source }) {
+  const cfg = parseDeterministicSchemaCheckConfig(source);
+  const runStatus = normalizeNullableLowerString(run?.status);
+  const latencyMs =
+    toSafeNonNegativeInt(run?.metrics?.latencyMs) ??
+    toSafeNonNegativeInt(verification?.durationMs) ??
+    null;
+  const releaseRatePct = toSafeNonNegativeInt(run?.metrics?.settlementReleaseRatePct);
+  const violations = [];
+
+  if (runStatus !== "completed") {
+    violations.push({
+      path: "$.status",
+      code: "not_completed",
+      message: "run.status must be completed"
+    });
+  }
+
+  if (latencyMs === null) {
+    violations.push({
+      path: "$.metrics.latencyMs",
+      code: "missing_latency",
+      message: "metrics.latencyMs is required and must be a non-negative integer"
+    });
+  } else if (latencyMs > cfg.latencyMaxMs) {
+    violations.push({
+      path: "$.metrics.latencyMs",
+      code: "latency_above_max",
+      message: `metrics.latencyMs must be <= ${cfg.latencyMaxMs}`
+    });
+  }
+
+  if (cfg.requireSettlementReleaseRatePct && releaseRatePct === null) {
+    violations.push({
+      path: "$.metrics.settlementReleaseRatePct",
+      code: "missing_release_rate",
+      message: "metrics.settlementReleaseRatePct is required"
+    });
+  } else if (releaseRatePct !== null && releaseRatePct > 100) {
+    violations.push({
+      path: "$.metrics.settlementReleaseRatePct",
+      code: "release_rate_out_of_range",
+      message: "metrics.settlementReleaseRatePct must be <= 100"
+    });
+  }
+
+  if (violations.length > 0) {
+    return {
+      verificationStatus: SETTLEMENT_VERIFICATION_STATUS.RED,
+      reasonCodes: ["verifier_plugin_schema_check_failed"],
+      summary: {
+        schemaVersion: "DeterministicVerifierSchemaCheck.v1",
+        source,
+        latencyMaxMs: cfg.latencyMaxMs,
+        requireSettlementReleaseRatePct: cfg.requireSettlementReleaseRatePct,
+        violations
+      }
+    };
+  }
+
+  return {
+    verificationStatus: SETTLEMENT_VERIFICATION_STATUS.GREEN,
+    reasonCodes: [],
+    summary: {
+      schemaVersion: "DeterministicVerifierSchemaCheck.v1",
+      source,
+      latencyMaxMs: cfg.latencyMaxMs,
+      requireSettlementReleaseRatePct: cfg.requireSettlementReleaseRatePct,
+      metrics: {
+        latencyMs,
+        settlementReleaseRatePct: releaseRatePct
+      }
+    }
+  };
+}
+
+export function resolveSettlementVerifierRef({ verificationMethod = null } = {}) {
+  const method =
+    verificationMethod && typeof verificationMethod === "object" && !Array.isArray(verificationMethod) ? verificationMethod : null;
+  const source = normalizeVerifierSource(method?.source);
+  const sourceBase = normalizeVerifierSourceBase(source);
+  const modality = normalizeNullableLowerString(method?.mode);
+
+  if (sourceBase === DETERMINISTIC_LATENCY_VERIFIER.source) {
+    return {
+      verifierId: DETERMINISTIC_LATENCY_VERIFIER.verifierId,
+      verifierVersion: DETERMINISTIC_LATENCY_VERIFIER.verifierVersion,
+      verifierHash: computeVerifierHash({
+        verifierId: DETERMINISTIC_LATENCY_VERIFIER.verifierId,
+        verifierVersion: DETERMINISTIC_LATENCY_VERIFIER.verifierVersion,
+        source: source ?? DETERMINISTIC_LATENCY_VERIFIER.source
+      }),
+      modality: DETERMINISTIC_LATENCY_VERIFIER.modality,
+      source,
+      matchedPlugin: DETERMINISTIC_LATENCY_VERIFIER.source
+    };
+  }
+
+  if (sourceBase === DETERMINISTIC_SCHEMA_CHECK_VERIFIER.source || sourceBase === DETERMINISTIC_SCHEMA_CHECK_VERIFIER.legacySource) {
+    return {
+      verifierId: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.verifierId,
+      verifierVersion: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.verifierVersion,
+      verifierHash: computeVerifierHash({
+        verifierId: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.verifierId,
+        verifierVersion: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.verifierVersion,
+        source: source ?? DETERMINISTIC_SCHEMA_CHECK_VERIFIER.source
+      }),
+      modality: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.modality,
+      source,
+      matchedPlugin: DETERMINISTIC_SCHEMA_CHECK_VERIFIER.source
+    };
+  }
+
+  return {
+    verifierId: DEFAULT_VERIFIER_REF.verifierId,
+    verifierVersion: DEFAULT_VERIFIER_REF.verifierVersion,
+    verifierHash: DEFAULT_VERIFIER_REF.verifierHash,
+    modality: modality ?? null,
+    source,
+    matchedPlugin: null
+  };
+}
+
+export function evaluateSettlementVerifierExecution({
+  verificationMethod = null,
+  run = null,
+  verification = null,
+  baseVerificationStatus = null
+} = {}) {
+  const verifierRef = resolveSettlementVerifierRef({ verificationMethod });
+  const defaultStatus = normalizeVerificationStatus(baseVerificationStatus);
+
+  let evaluation = {
+    pluginMatched: false,
+    source: verifierRef.source,
+    reasonCodes: [],
+    summary: null
+  };
+  let verificationStatus = defaultStatus;
+
+  if (verifierRef.matchedPlugin === DETERMINISTIC_LATENCY_VERIFIER.source) {
+    const pluginResult = evaluateDeterministicLatencyThreshold({ run, verification });
+    verificationStatus = normalizeVerificationStatus(pluginResult.verificationStatus, defaultStatus);
+    evaluation = {
+      pluginMatched: true,
+      source: verifierRef.source,
+      reasonCodes: Array.isArray(pluginResult.reasonCodes) ? pluginResult.reasonCodes.map((v) => String(v)) : [],
+      summary:
+        pluginResult.summary && typeof pluginResult.summary === "object" && !Array.isArray(pluginResult.summary)
+          ? pluginResult.summary
+          : null
+    };
+  } else if (verifierRef.matchedPlugin === DETERMINISTIC_SCHEMA_CHECK_VERIFIER.source) {
+    const pluginResult = evaluateDeterministicSchemaCheck({
+      run,
+      verification,
+      source: verifierRef.source ?? DETERMINISTIC_SCHEMA_CHECK_VERIFIER.source
+    });
+    verificationStatus = normalizeVerificationStatus(pluginResult.verificationStatus, defaultStatus);
+    evaluation = {
+      pluginMatched: true,
+      source: verifierRef.source,
+      reasonCodes: Array.isArray(pluginResult.reasonCodes) ? pluginResult.reasonCodes.map((v) => String(v)) : [],
+      summary:
+        pluginResult.summary && typeof pluginResult.summary === "object" && !Array.isArray(pluginResult.summary)
+          ? pluginResult.summary
+          : null
+    };
+  }
+
+  return {
+    verificationStatus,
+    verifierRef: {
+      verifierId: verifierRef.verifierId,
+      verifierVersion: verifierRef.verifierVersion,
+      verifierHash: verifierRef.verifierHash,
+      modality: verifierRef.modality
+    },
+    evaluation
+  };
+}

package/src/core/tool-call-agreement.js

@@ -0,0 +1,112 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const TOOL_CALL_AGREEMENT_SCHEMA_VERSION = "ToolCallAgreement.v1";
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+  return String(value).trim();
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+  return new Date(Date.parse(value)).toISOString();
+}
+
+function normalizeSha256Hex(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeNullableId(value, name) {
+  if (value === null || value === undefined) return null;
+  const out = String(value).trim();
+  return out ? out : null;
+}
+
+export function computeToolCallInputHashV1(input) {
+  const canonical = canonicalJsonStringify(input ?? {});
+  return sha256Hex(canonical);
+}
+
+export function computeToolCallAgreementHashV1(agreementCore) {
+  assertPlainObject(agreementCore, "agreementCore");
+  const copy = { ...agreementCore };
+  delete copy.agreementHash;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildToolCallAgreementV1({
+  toolId,
+  manifestHash,
+  callId,
+  input = {},
+  inputHash = null,
+  acceptanceCriteria = null,
+  settlementTerms = null,
+  payerAgentId = null,
+  payeeAgentId = null,
+  createdAt = new Date().toISOString()
+} = {}) {
+  const at = assertIsoDate(createdAt, "createdAt");
+
+  const computedInputHash = inputHash === null || inputHash === undefined ? computeToolCallInputHashV1(input) : normalizeSha256Hex(inputHash, "inputHash");
+
+  const core = normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_CALL_AGREEMENT_SCHEMA_VERSION,
+      toolId: assertNonEmptyString(String(toolId ?? ""), "toolId"),
+      manifestHash: normalizeSha256Hex(manifestHash, "manifestHash"),
+      callId: assertNonEmptyString(String(callId ?? ""), "callId"),
+      inputHash: computedInputHash,
+      acceptanceCriteria: acceptanceCriteria === undefined ? null : acceptanceCriteria,
+      settlementTerms: settlementTerms === undefined ? null : settlementTerms,
+      payerAgentId: normalizeNullableId(payerAgentId, "payerAgentId"),
+      payeeAgentId: normalizeNullableId(payeeAgentId, "payeeAgentId"),
+      createdAt: at
+    },
+    { path: "$" }
+  );
+  const agreementHash = computeToolCallAgreementHashV1(core);
+  return normalizeForCanonicalJson({ ...core, agreementHash }, { path: "$" });
+}
+
+export function validateToolCallAgreementV1(agreement) {
+  assertPlainObject(agreement, "agreement");
+  if (agreement.schemaVersion !== TOOL_CALL_AGREEMENT_SCHEMA_VERSION) {
+    throw new TypeError(`agreement.schemaVersion must be ${TOOL_CALL_AGREEMENT_SCHEMA_VERSION}`);
+  }
+  assertNonEmptyString(agreement.toolId, "agreement.toolId");
+  normalizeSha256Hex(agreement.manifestHash, "agreement.manifestHash");
+  assertNonEmptyString(agreement.callId, "agreement.callId");
+  normalizeSha256Hex(agreement.inputHash, "agreement.inputHash");
+
+  if (agreement.acceptanceCriteria !== null && agreement.acceptanceCriteria !== undefined) {
+    assertPlainObject(agreement.acceptanceCriteria, "agreement.acceptanceCriteria");
+  }
+  if (agreement.settlementTerms !== null && agreement.settlementTerms !== undefined) {
+    assertPlainObject(agreement.settlementTerms, "agreement.settlementTerms");
+  }
+
+  normalizeNullableId(agreement.payerAgentId ?? null, "agreement.payerAgentId");
+  normalizeNullableId(agreement.payeeAgentId ?? null, "agreement.payeeAgentId");
+
+  assertIsoDate(agreement.createdAt, "agreement.createdAt");
+
+  const agreementHash = normalizeSha256Hex(agreement.agreementHash, "agreement.agreementHash");
+  const computed = computeToolCallAgreementHashV1(agreement);
+  if (computed !== agreementHash) throw new TypeError("agreementHash mismatch");
+  return true;
+}
+

package/src/core/tool-call-evidence.js

@@ -0,0 +1,144 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex, signHashHexEd25519 } from "./crypto.js";
+
+export const TOOL_CALL_EVIDENCE_SCHEMA_VERSION = "ToolCallEvidence.v1";
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+  return String(value).trim();
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+  return new Date(Date.parse(value)).toISOString();
+}
+
+function normalizeSha256Hex(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeNullableString(value) {
+  if (value === null || value === undefined) return null;
+  const out = String(value).trim();
+  return out ? out : null;
+}
+
+export function computeToolCallOutputHashV1(output) {
+  const canonical = canonicalJsonStringify(output ?? {});
+  return sha256Hex(canonical);
+}
+
+export function computeToolCallEvidenceHashV1(evidenceCore) {
+  assertPlainObject(evidenceCore, "evidenceCore");
+  const copy = { ...evidenceCore };
+  delete copy.evidenceHash;
+  delete copy.signature;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildToolCallEvidenceV1({
+  agreementHash,
+  callId,
+  inputHash,
+  output = {},
+  outputHash = null,
+  outputRef = null,
+  metrics = null,
+  startedAt = new Date().toISOString(),
+  completedAt = null,
+  createdAt = null,
+  signerKeyId = null,
+  signerPrivateKeyPem = null
+} = {}) {
+  const startedAtIso = assertIsoDate(startedAt, "startedAt");
+  const completedAtIso = assertIsoDate(completedAt ?? startedAtIso, "completedAt");
+  const createdAtIso = assertIsoDate(createdAt ?? completedAtIso, "createdAt");
+
+  const computedOutputHash =
+    outputHash === null || outputHash === undefined ? computeToolCallOutputHashV1(output) : normalizeSha256Hex(outputHash, "outputHash");
+
+  const core = normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_CALL_EVIDENCE_SCHEMA_VERSION,
+      agreementHash: normalizeSha256Hex(agreementHash, "agreementHash"),
+      callId: assertNonEmptyString(String(callId ?? ""), "callId"),
+      inputHash: normalizeSha256Hex(inputHash, "inputHash"),
+      outputHash: computedOutputHash,
+      outputRef: outputRef === undefined ? null : normalizeNullableString(outputRef),
+      metrics: metrics === undefined ? null : metrics,
+      startedAt: startedAtIso,
+      completedAt: completedAtIso,
+      createdAt: createdAtIso
+    },
+    { path: "$" }
+  );
+
+  const evidenceHash = computeToolCallEvidenceHashV1(core);
+
+  let signature = null;
+  const normalizedSignerKeyId = signerKeyId === null || signerKeyId === undefined ? null : normalizeNullableString(signerKeyId);
+  const normalizedSignerPrivateKeyPem =
+    signerPrivateKeyPem === null || signerPrivateKeyPem === undefined ? null : normalizeNullableString(signerPrivateKeyPem);
+  if (normalizedSignerPrivateKeyPem) {
+    if (!normalizedSignerKeyId) throw new TypeError("signerKeyId is required when signerPrivateKeyPem is provided");
+    signature = {
+      algorithm: "ed25519",
+      signerKeyId: normalizedSignerKeyId,
+      evidenceHash,
+      signature: signHashHexEd25519(evidenceHash, normalizedSignerPrivateKeyPem)
+    };
+  }
+
+  return normalizeForCanonicalJson({ ...core, evidenceHash, ...(signature ? { signature } : {}) }, { path: "$" });
+}
+
+export function validateToolCallEvidenceV1(evidence) {
+  assertPlainObject(evidence, "evidence");
+  if (evidence.schemaVersion !== TOOL_CALL_EVIDENCE_SCHEMA_VERSION) {
+    throw new TypeError(`evidence.schemaVersion must be ${TOOL_CALL_EVIDENCE_SCHEMA_VERSION}`);
+  }
+  normalizeSha256Hex(evidence.agreementHash, "evidence.agreementHash");
+  assertNonEmptyString(evidence.callId, "evidence.callId");
+  normalizeSha256Hex(evidence.inputHash, "evidence.inputHash");
+  normalizeSha256Hex(evidence.outputHash, "evidence.outputHash");
+
+  if (Object.prototype.hasOwnProperty.call(evidence, "outputRef")) {
+    normalizeNullableString(evidence.outputRef ?? null);
+  }
+  if (Object.prototype.hasOwnProperty.call(evidence, "metrics") && evidence.metrics !== null && evidence.metrics !== undefined) {
+    assertPlainObject(evidence.metrics, "evidence.metrics");
+  }
+
+  assertIsoDate(evidence.startedAt, "evidence.startedAt");
+  assertIsoDate(evidence.completedAt, "evidence.completedAt");
+  assertIsoDate(evidence.createdAt, "evidence.createdAt");
+
+  const evidenceHash = normalizeSha256Hex(evidence.evidenceHash, "evidence.evidenceHash");
+  const computed = computeToolCallEvidenceHashV1(evidence);
+  if (computed !== evidenceHash) throw new TypeError("evidenceHash mismatch");
+
+  if (Object.prototype.hasOwnProperty.call(evidence, "signature") && evidence.signature !== null && evidence.signature !== undefined) {
+    const sig = evidence.signature;
+    if (!sig || typeof sig !== "object" || Array.isArray(sig)) throw new TypeError("evidence.signature must be an object");
+    if (sig.algorithm !== "ed25519") throw new TypeError("evidence.signature.algorithm must be ed25519");
+    assertNonEmptyString(sig.signerKeyId, "evidence.signature.signerKeyId");
+    const sigEvidenceHash = normalizeSha256Hex(sig.evidenceHash, "evidence.signature.evidenceHash");
+    if (sigEvidenceHash !== evidenceHash) throw new TypeError("evidence.signature.evidenceHash mismatch");
+    assertNonEmptyString(sig.signature, "evidence.signature.signature");
+  }
+
+  return true;
+}
+

package/src/core/tool-provider-signature.js

@@ -0,0 +1,98 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const TOOL_PROVIDER_SIGNATURE_PAYLOAD_SCHEMA_VERSION = "ToolProviderSignaturePayload.v1";
+export const TOOL_PROVIDER_SIGNATURE_SCHEMA_VERSION = "ToolProviderSignature.v1";
+
+function assertNonEmptyString(v, name) {
+  if (typeof v !== "string" || v.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertIsoDate(v, name) {
+  assertNonEmptyString(v, name);
+  const t = Date.parse(v);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date-time`);
+}
+
+function assertSha256Hex(v, name) {
+  assertNonEmptyString(v, name);
+  const s = v.trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(s)) throw new TypeError(`${name} must be sha256 hex`);
+  return s;
+}
+
+function assertNonceHex(v, name) {
+  assertNonEmptyString(v, name);
+  const s = v.trim().toLowerCase();
+  if (!/^[0-9a-f]{16,128}$/.test(s)) throw new TypeError(`${name} must be hex (16..128 chars)`);
+  return s;
+}
+
+export function buildToolProviderSignaturePayloadV1({ responseHash, nonce, signedAt } = {}) {
+  const payload = normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_PROVIDER_SIGNATURE_PAYLOAD_SCHEMA_VERSION,
+      responseHash: assertSha256Hex(responseHash, "responseHash"),
+      nonce: assertNonceHex(nonce, "nonce"),
+      signedAt: (() => {
+        assertIsoDate(signedAt, "signedAt");
+        return signedAt;
+      })()
+    },
+    { path: "$" }
+  );
+  return payload;
+}
+
+export function computeToolProviderSignaturePayloadHashV1({ responseHash, nonce, signedAt } = {}) {
+  const payload = buildToolProviderSignaturePayloadV1({ responseHash, nonce, signedAt });
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function signToolProviderSignatureV1({ responseHash, nonce, signedAt, publicKeyPem, privateKeyPem } = {}) {
+  assertNonEmptyString(publicKeyPem, "publicKeyPem");
+  assertNonEmptyString(privateKeyPem, "privateKeyPem");
+  const keyId = keyIdFromPublicKeyPem(publicKeyPem);
+  const payloadHashHex = computeToolProviderSignaturePayloadHashV1({ responseHash, nonce, signedAt });
+  const signatureBase64 = signHashHexEd25519(payloadHashHex, privateKeyPem);
+  const sig = normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_PROVIDER_SIGNATURE_SCHEMA_VERSION,
+      algorithm: "ed25519",
+      keyId,
+      signedAt,
+      nonce,
+      responseHash: String(responseHash).trim().toLowerCase(),
+      payloadHash: payloadHashHex,
+      signatureBase64
+    },
+    { path: "$" }
+  );
+  return sig;
+}
+
+export function verifyToolProviderSignatureV1({ signature, publicKeyPem } = {}) {
+  if (!signature || typeof signature !== "object" || Array.isArray(signature)) throw new TypeError("signature must be an object");
+  assertNonEmptyString(publicKeyPem, "publicKeyPem");
+
+  if (signature.schemaVersion !== TOOL_PROVIDER_SIGNATURE_SCHEMA_VERSION) {
+    throw new TypeError(`signature.schemaVersion must be ${TOOL_PROVIDER_SIGNATURE_SCHEMA_VERSION}`);
+  }
+  if (String(signature.algorithm ?? "").toLowerCase() !== "ed25519") {
+    throw new TypeError("signature.algorithm must be ed25519");
+  }
+  const expectedKeyId = keyIdFromPublicKeyPem(publicKeyPem);
+  if (String(signature.keyId ?? "").trim() !== expectedKeyId) return false;
+
+  const payloadHashHex = computeToolProviderSignaturePayloadHashV1({
+    responseHash: signature.responseHash,
+    nonce: signature.nonce,
+    signedAt: signature.signedAt
+  });
+  if (String(signature.payloadHash ?? "").trim().toLowerCase() !== payloadHashHex) return false;
+  const signatureBase64 = String(signature.signatureBase64 ?? "").trim();
+  if (!signatureBase64) return false;
+
+  return verifyHashHexEd25519({ hashHex: payloadHashHex, signatureBase64, publicKeyPem });
+}
+