settld 0.1.0

package/src/core/reputation-event.js

@@ -0,0 +1,203 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const REPUTATION_EVENT_SCHEMA_VERSION = "ReputationEvent.v1";
+
+export const REPUTATION_EVENT_KIND = Object.freeze({
+  DECISION_APPROVED: "decision_approved",
+  DECISION_REJECTED: "decision_rejected",
+  HOLDBACK_AUTO_RELEASED: "holdback_auto_released",
+  DISPUTE_OPENED: "dispute_opened",
+  VERDICT_ISSUED: "verdict_issued",
+  ADJUSTMENT_APPLIED: "adjustment_applied"
+});
+
+export const REPUTATION_EVENT_ROLE = Object.freeze({
+  PAYEE: "payee",
+  PAYER: "payer",
+  ARBITER: "arbiter",
+  SYSTEM: "system"
+});
+
+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`);
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function normalizeId(value, name, { min = 1, max = 200 } = {}) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim();
+  if (out.length < min || out.length > max) throw new TypeError(`${name} must be length ${min}..${max}`);
+  if (!/^[A-Za-z0-9:_-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:_-]+$`);
+  return out;
+}
+
+function normalizeHexHash(value, name, { allowNull = false } = {}) {
+  if (value === null || value === undefined) {
+    if (allowNull) return null;
+    throw new TypeError(`${name} must be a 64-hex sha256`);
+  }
+  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 normalizeOptionalId(value, name, options = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  return normalizeId(value, name, options);
+}
+
+function normalizeKind(value, name) {
+  const out = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!Object.values(REPUTATION_EVENT_KIND).includes(out)) {
+    throw new TypeError(`${name} must be one of: ${Object.values(REPUTATION_EVENT_KIND).join("|")}`);
+  }
+  return out;
+}
+
+function normalizeRole(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const out = String(value).trim().toLowerCase();
+  if (!Object.values(REPUTATION_EVENT_ROLE).includes(out)) {
+    throw new TypeError(`${name} must be one of: ${Object.values(REPUTATION_EVENT_ROLE).join("|")}`);
+  }
+  return out;
+}
+
+function normalizeSourceRef(sourceRef) {
+  assertPlainObject(sourceRef, "sourceRef");
+  const kind = normalizeId(sourceRef.kind, "sourceRef.kind", { min: 2, max: 64 }).toLowerCase();
+  const normalized = { kind };
+  const maybe = {
+    artifactId: normalizeOptionalId(sourceRef.artifactId, "sourceRef.artifactId", { min: 3, max: 240 }),
+    sourceId: normalizeOptionalId(sourceRef.sourceId, "sourceRef.sourceId", { min: 3, max: 240 }),
+    hash: normalizeHexHash(sourceRef.hash, "sourceRef.hash", { allowNull: true }),
+    agreementHash: normalizeHexHash(sourceRef.agreementHash, "sourceRef.agreementHash", { allowNull: true }),
+    receiptHash: normalizeHexHash(sourceRef.receiptHash, "sourceRef.receiptHash", { allowNull: true }),
+    holdHash: normalizeHexHash(sourceRef.holdHash, "sourceRef.holdHash", { allowNull: true }),
+    decisionHash: normalizeHexHash(sourceRef.decisionHash, "sourceRef.decisionHash", { allowNull: true }),
+    verdictHash: normalizeHexHash(sourceRef.verdictHash, "sourceRef.verdictHash", { allowNull: true }),
+    runId: normalizeOptionalId(sourceRef.runId, "sourceRef.runId", { min: 3, max: 128 }),
+    settlementId: normalizeOptionalId(sourceRef.settlementId, "sourceRef.settlementId", { min: 3, max: 240 }),
+    disputeId: normalizeOptionalId(sourceRef.disputeId, "sourceRef.disputeId", { min: 3, max: 240 }),
+    caseId: normalizeOptionalId(sourceRef.caseId, "sourceRef.caseId", { min: 3, max: 240 }),
+    adjustmentId: normalizeOptionalId(sourceRef.adjustmentId, "sourceRef.adjustmentId", { min: 3, max: 240 })
+  };
+  for (const [key, value] of Object.entries(maybe)) {
+    if (value !== null) normalized[key] = value;
+  }
+  if (
+    !normalized.artifactId &&
+    !normalized.sourceId &&
+    !normalized.hash &&
+    !normalized.agreementHash &&
+    !normalized.runId &&
+    !normalized.settlementId &&
+    !normalized.disputeId &&
+    !normalized.caseId &&
+    !normalized.adjustmentId &&
+    !normalized.decisionHash &&
+    !normalized.receiptHash &&
+    !normalized.holdHash &&
+    !normalized.verdictHash
+  ) {
+    throw new TypeError("sourceRef must include at least one stable reference field");
+  }
+  return normalizeForCanonicalJson(normalized, { path: "$" });
+}
+
+function normalizeSubject(subject) {
+  assertPlainObject(subject, "subject");
+  const normalized = { agentId: normalizeId(subject.agentId, "subject.agentId", { min: 3, max: 128 }) };
+  const toolId = normalizeOptionalId(subject.toolId, "subject.toolId", { min: 1, max: 200 });
+  const counterpartyAgentId = normalizeOptionalId(subject.counterpartyAgentId, "subject.counterpartyAgentId", { min: 3, max: 128 });
+  const role = normalizeRole(subject.role, "subject.role");
+  if (toolId !== null) normalized.toolId = toolId;
+  if (counterpartyAgentId !== null) normalized.counterpartyAgentId = counterpartyAgentId;
+  if (role !== null) normalized.role = role;
+  return normalizeForCanonicalJson(normalized, { path: "$" });
+}
+
+export function computeReputationEventHashV1(eventCore) {
+  assertPlainObject(eventCore, "eventCore");
+  const copy = { ...eventCore };
+  delete copy.eventHash;
+  delete copy.artifactHash;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildReputationEventV1({
+  eventId,
+  tenantId,
+  occurredAt,
+  subject,
+  eventKind,
+  sourceRef,
+  facts = {}
+} = {}) {
+  const at = occurredAt ?? new Date().toISOString();
+  assertIsoDate(at, "occurredAt");
+  const normalizedFacts = facts === null || facts === undefined ? {} : facts;
+  assertPlainObject(normalizedFacts, "facts");
+
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: REPUTATION_EVENT_SCHEMA_VERSION,
+      artifactType: REPUTATION_EVENT_SCHEMA_VERSION,
+      artifactId: normalizeId(eventId, "eventId", { min: 3, max: 240 }),
+      eventId: normalizeId(eventId, "eventId", { min: 3, max: 240 }),
+      tenantId: normalizeId(tenantId, "tenantId", { min: 1, max: 128 }),
+      occurredAt: at,
+      eventKind: normalizeKind(eventKind, "eventKind"),
+      subject: normalizeSubject(subject),
+      sourceRef: normalizeSourceRef(sourceRef),
+      facts: normalizeForCanonicalJson(normalizedFacts, { path: "$" })
+    },
+    { path: "$" }
+  );
+
+  const eventHash = computeReputationEventHashV1(normalized);
+  return normalizeForCanonicalJson(
+    {
+      ...normalized,
+      eventHash
+    },
+    { path: "$" }
+  );
+}
+
+export function validateReputationEventV1(event) {
+  assertPlainObject(event, "event");
+  if (event.schemaVersion !== REPUTATION_EVENT_SCHEMA_VERSION) {
+    throw new TypeError(`event.schemaVersion must be ${REPUTATION_EVENT_SCHEMA_VERSION}`);
+  }
+  if (event.artifactType !== REPUTATION_EVENT_SCHEMA_VERSION) {
+    throw new TypeError(`event.artifactType must be ${REPUTATION_EVENT_SCHEMA_VERSION}`);
+  }
+  const eventId = normalizeId(event.eventId, "event.eventId", { min: 3, max: 240 });
+  const artifactId = normalizeId(event.artifactId, "event.artifactId", { min: 3, max: 240 });
+  if (eventId !== artifactId) throw new TypeError("event.artifactId must equal event.eventId");
+  normalizeId(event.tenantId, "event.tenantId", { min: 1, max: 128 });
+  assertIsoDate(event.occurredAt, "event.occurredAt");
+  normalizeKind(event.eventKind, "event.eventKind");
+  normalizeSubject(event.subject);
+  normalizeSourceRef(event.sourceRef);
+  assertPlainObject(event.facts, "event.facts");
+  const hash = normalizeHexHash(event.eventHash, "event.eventHash");
+  const computed = computeReputationEventHashV1(event);
+  if (computed !== hash) throw new TypeError("eventHash mismatch");
+  return true;
+}

package/src/core/rescheduling.js

@@ -0,0 +1,51 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+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 assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function validateWindow(window, name) {
+  assertPlainObject(window, name);
+  const allowed = new Set(["startAt", "endAt"]);
+  for (const key of Object.keys(window)) {
+    if (!allowed.has(key)) throw new TypeError(`${name} contains unknown field: ${key}`);
+  }
+  assertIsoDate(window.startAt, `${name}.startAt`);
+  assertIsoDate(window.endAt, `${name}.endAt`);
+  if (Date.parse(window.startAt) >= Date.parse(window.endAt)) throw new TypeError(`${name}.startAt must be before endAt`);
+}
+
+const RESCHEDULE_REASONS = new Set(["CUSTOMER_REQUEST", "NO_SUPPLY", "ROBOT_FAILURE", "OPS"]);
+
+export function validateJobRescheduledPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "oldWindow", "newWindow", "reason", "requestedBy", "requiresRequote", "quoteRef"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  validateWindow(payload.oldWindow, "payload.oldWindow");
+  validateWindow(payload.newWindow, "payload.newWindow");
+  assertNonEmptyString(payload.reason, "payload.reason");
+  if (!RESCHEDULE_REASONS.has(payload.reason)) throw new TypeError("payload.reason is not supported");
+
+  if (payload.requestedBy !== undefined && payload.requestedBy !== null) assertNonEmptyString(payload.requestedBy, "payload.requestedBy");
+  if (payload.requiresRequote !== undefined && typeof payload.requiresRequote !== "boolean") {
+    throw new TypeError("payload.requiresRequote must be a boolean");
+  }
+  if (payload.quoteRef !== undefined && payload.quoteRef !== null) assertNonEmptyString(payload.quoteRef, "payload.quoteRef");
+
+  return payload;
+}
+

package/src/core/retention.js

@@ -0,0 +1,32 @@
+function assertSafeInt(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+}
+
+export function clampRetentionDays({ tenantDays = null, defaultDays = 0, maxDays = 0 } = {}) {
+  if (tenantDays !== null && tenantDays !== undefined) assertSafeInt(tenantDays, "tenantDays");
+  assertSafeInt(defaultDays, "defaultDays");
+  assertSafeInt(maxDays, "maxDays");
+  if (tenantDays !== null && tenantDays !== undefined && tenantDays < 0) throw new TypeError("tenantDays must be >= 0");
+  if (defaultDays < 0) throw new TypeError("defaultDays must be >= 0");
+  if (maxDays < 0) throw new TypeError("maxDays must be >= 0");
+
+  let days = tenantDays === null || tenantDays === undefined ? defaultDays : tenantDays;
+
+  // Convention: 0 means "no explicit tenant retention" (infinite) but the platform may cap it.
+  if (maxDays > 0) {
+    if (days === 0) return maxDays;
+    return Math.min(days, maxDays);
+  }
+
+  return days;
+}
+
+export function computeExpiresAtIso({ at, retentionDays }) {
+  if (!Number.isSafeInteger(retentionDays) || retentionDays <= 0) return null;
+  if (typeof at !== "string" || at.trim() === "") throw new TypeError("at must be a non-empty ISO date string");
+  const atMs = Date.parse(at);
+  if (!Number.isFinite(atMs)) throw new TypeError("at must be an ISO date string");
+  const expiresMs = atMs + retentionDays * 24 * 60 * 60_000;
+  return new Date(expiresMs).toISOString();
+}
+

package/src/core/revocation-list.js

@@ -0,0 +1,70 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex, signHashHexEd25519 } from "./crypto.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+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`);
+}
+
+export const REVOCATION_LIST_SCHEMA_V1 = "RevocationList.v1";
+
+function stripRevocationListSig(list) {
+  const { listHash: _h, signature: _sig, ...rest } = list ?? {};
+  return rest;
+}
+
+export function buildRevocationListV1Core({ listId, generatedAt, rotations = [], revocations = [], signerKeyId, signedAt } = {}) {
+  assertNonEmptyString(listId, "listId");
+  assertNonEmptyString(generatedAt, "generatedAt");
+  if (!Array.isArray(rotations)) throw new TypeError("rotations must be an array");
+  if (!Array.isArray(revocations)) throw new TypeError("revocations must be an array");
+  assertNonEmptyString(signerKeyId, "signerKeyId");
+  assertNonEmptyString(signedAt, "signedAt");
+  return {
+    schemaVersion: REVOCATION_LIST_SCHEMA_V1,
+    listId,
+    generatedAt,
+    rotations,
+    revocations,
+    signerKeyId,
+    signedAt
+  };
+}
+
+export function signRevocationListV1({ listCore, signer } = {}) {
+  assertPlainObject(listCore, "listCore");
+  if (!signer || typeof signer !== "object") throw new TypeError("signer is required");
+  assertNonEmptyString(signer.keyId, "signer.keyId");
+  assertNonEmptyString(signer.privateKeyPem, "signer.privateKeyPem");
+
+  const core = { ...listCore, signerKeyId: signer.keyId };
+  const listHash = sha256Hex(canonicalJsonStringify(core));
+  const signature = signHashHexEd25519(listHash, signer.privateKeyPem);
+  return { ...core, listHash, signature };
+}
+
+export function validateRevocationListV1(list) {
+  assertPlainObject(list, "list");
+  if (list.schemaVersion !== REVOCATION_LIST_SCHEMA_V1) throw new TypeError("list.schemaVersion must be RevocationList.v1");
+  assertNonEmptyString(list.listId, "list.listId");
+  assertNonEmptyString(list.generatedAt, "list.generatedAt");
+  if (!Array.isArray(list.rotations)) throw new TypeError("list.rotations must be an array");
+  if (!Array.isArray(list.revocations)) throw new TypeError("list.revocations must be an array");
+  // Signature fields are allowed to be null for non-strict / bootstrap bundles.
+  if (list.signerKeyId !== null) assertNonEmptyString(list.signerKeyId, "list.signerKeyId");
+  if (list.signedAt !== null) assertNonEmptyString(list.signedAt, "list.signedAt");
+  if (list.listHash !== null) assertNonEmptyString(list.listHash, "list.listHash");
+  if (list.signature !== null) assertNonEmptyString(list.signature, "list.signature");
+  return { ok: true };
+}
+
+export function computeRevocationListV1Hash(list) {
+  assertPlainObject(list, "list");
+  const core = stripRevocationListSig(list);
+  return sha256Hex(canonicalJsonStringify(core));
+}
+