settld 0.1.2 → 0.2.0

package/src/core/event-policy.js

@@ -33,13 +33,22 @@ const OPERATOR_SIGNED_TYPES = new Set([
   "OPERATOR_SHIFT_CLOSED"
 ]);
 
+const OPERATOR_EMERGENCY_SIGNED_TYPES = new Set([
+  "OPERATOR_EMERGENCY_PAUSE",
+  "OPERATOR_EMERGENCY_QUARANTINE",
+  "OPERATOR_EMERGENCY_REVOKE",
+  "OPERATOR_EMERGENCY_REVOKE_DELEGATION",
+  "OPERATOR_EMERGENCY_KILL_SWITCH",
+  "OPERATOR_EMERGENCY_RESUME"
+]);
+
 const ROBOT_OR_OPERATOR_SIGNED_TYPES = new Set(["ACCESS_GRANTED", "ACCESS_DENIED", "SKILL_USED", "ZONE_COVERAGE_REPORTED"]);
 
 const SERVER_OR_OPERATOR_SIGNED_TYPES = new Set(["INCIDENT_REPORTED", "CLAIM_TRIAGED"]);
 
 const SERVER_OR_ROBOT_SIGNED_TYPES = new Set(["EVIDENCE_CAPTURED", "JOB_EXECUTION_ABORTED", "JOB_EXECUTION_RESUMED", "ROBOT_UNHEALTHY"]);
 
-  const SERVER_SIGNED_TYPES = new Set([
+const SERVER_SIGNED_TYPES = new Set([
   "JOB_CREATED",
   "QUOTE_PROPOSED",
   "RISK_SCORED",
@@ -104,6 +113,8 @@ const SERVER_OR_ROBOT_SIGNED_TYPES = new Set(["EVIDENCE_CAPTURED", "JOB_EXECUTIO
 export function requiredSignerKindForEventType(eventType) {
   if (ROBOT_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.ROBOT;
   if (OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.OPERATOR;
+  if (OPERATOR_EMERGENCY_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.OPERATOR;
+  if (typeof eventType === "string" && eventType.startsWith("OPERATOR_EMERGENCY_")) return SIGNER_KIND.OPERATOR;
   if (ROBOT_OR_OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.ROBOT_OR_OPERATOR;
   if (SERVER_OR_OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.SERVER_OR_OPERATOR;
   if (SERVER_OR_ROBOT_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.SERVER_OR_ROBOT;
@@ -113,7 +124,15 @@ export function requiredSignerKindForEventType(eventType) {
 
 export function listKnownEventTypes() {
   const all = new Set();
-  for (const s of [ROBOT_SIGNED_TYPES, OPERATOR_SIGNED_TYPES, ROBOT_OR_OPERATOR_SIGNED_TYPES, SERVER_OR_OPERATOR_SIGNED_TYPES, SERVER_OR_ROBOT_SIGNED_TYPES, SERVER_SIGNED_TYPES]) {
+  for (const s of [
+    ROBOT_SIGNED_TYPES,
+    OPERATOR_SIGNED_TYPES,
+    OPERATOR_EMERGENCY_SIGNED_TYPES,
+    ROBOT_OR_OPERATOR_SIGNED_TYPES,
+    SERVER_OR_OPERATOR_SIGNED_TYPES,
+    SERVER_OR_ROBOT_SIGNED_TYPES,
+    SERVER_SIGNED_TYPES
+  ]) {
     for (const t of s) all.add(t);
   }
   return Array.from(all).sort();

package/src/core/maintenance-locks.js

@@ -1,3 +1,4 @@
 export const RETENTION_CLEANUP_ADVISORY_LOCK_KEY = "settld:maintenance:retention_cleanup:v1";
 export const FINANCE_RECONCILE_ADVISORY_LOCK_KEY = "settld:maintenance:finance_reconcile:v1";
+export const MONEY_RAIL_RECONCILE_ADVISORY_LOCK_KEY = "settld:maintenance:money_rail_reconcile:v1";
 export const MIGRATIONS_ADVISORY_LOCK_KEY = "settld:migrations:v1";

package/src/core/operator-action.js

@@ -0,0 +1,303 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const OPERATOR_ACTION_SCHEMA_VERSION = "OperatorAction.v1";
+export const OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION = "OperatorActionSignature.v1";
+
+const ALLOWED_CASE_KINDS = new Set(["challenge", "dispute", "escalation"]);
+const ALLOWED_ACTIONS = new Set(["APPROVE", "REJECT", "REQUEST_INFO", "OVERRIDE_ALLOW", "OVERRIDE_DENY"]);
+
+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 assertIsoDateTime(value, name) {
+  const out = assertNonEmptyString(value, name);
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(out)) throw new TypeError(`${name} must be an ISO date-time`);
+  if (!Number.isFinite(Date.parse(out))) throw new TypeError(`${name} must be an ISO date-time`);
+  return new Date(out).toISOString();
+}
+
+function assertPemString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty PEM string`);
+  return value;
+}
+
+function assertId(value, name, { max = 200 } = {}) {
+  const out = assertNonEmptyString(value, name);
+  if (out.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  if (!/^[A-Za-z0-9:._/-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:._/-]+$`);
+  return out;
+}
+
+function assertOptionalId(value, name, { max = 200 } = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  return assertId(value, name, { max });
+}
+
+function assertSha256Hex(value, name) {
+  const out = assertNonEmptyString(value, name).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be sha256 hex`);
+  return out;
+}
+
+function assertAction(value, name = "action.action") {
+  const out = assertNonEmptyString(value, name).toUpperCase();
+  if (!ALLOWED_ACTIONS.has(out)) {
+    throw new TypeError(`${name} must be APPROVE|REJECT|REQUEST_INFO|OVERRIDE_ALLOW|OVERRIDE_DENY`);
+  }
+  return out;
+}
+
+function assertJustificationCode(value, name = "action.justificationCode") {
+  const out = assertNonEmptyString(value, name).toUpperCase();
+  if (out.length > 128) throw new TypeError(`${name} must be <= 128 chars`);
+  if (!/^[A-Z][A-Z0-9._:-]*$/.test(out)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9._:-]*$`);
+  return out;
+}
+
+function assertOptionalJustificationText(value, name = "action.justification", { max = 2000 } = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const out = String(value).trim();
+  if (out.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  return out;
+}
+
+function assertOptionalToken(value, name, { max = 128 } = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const out = String(value).trim().toLowerCase();
+  if (out.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  if (!/^[a-z0-9._:-]+$/.test(out)) throw new TypeError(`${name} must match ^[a-z0-9._:-]+$`);
+  return out;
+}
+
+function normalizeCaseRef(action) {
+  const caseRefRaw = action.caseRef;
+  if (!caseRefRaw || typeof caseRefRaw !== "object" || Array.isArray(caseRefRaw)) {
+    throw new TypeError("action.caseRef must be an object");
+  }
+  const caseKind = assertNonEmptyString(caseRefRaw.kind, "action.caseRef.kind").toLowerCase();
+  if (!ALLOWED_CASE_KINDS.has(caseKind)) {
+    throw new TypeError("action.caseRef.kind must be challenge|dispute|escalation");
+  }
+  return normalizeForCanonicalJson(
+    {
+      kind: caseKind,
+      caseId: assertId(caseRefRaw.caseId, "action.caseRef.caseId", { max: 240 })
+    },
+    { path: "$.caseRef" }
+  );
+}
+
+function normalizeActor(actor) {
+  assertPlainObject(actor, "action.actor");
+  const operatorId = assertOptionalId(actor.operatorId ?? actor.id, "action.actor.operatorId", { max: 200 });
+  if (!operatorId) throw new TypeError("action.actor.operatorId is required");
+  const role = assertOptionalToken(actor.role, "action.actor.role", { max: 128 });
+  const tenantId = assertOptionalId(actor.tenantId, "action.actor.tenantId", { max: 128 });
+  const sessionId = assertOptionalId(actor.sessionId, "action.actor.sessionId", { max: 256 });
+  let metadata = null;
+  if (Object.prototype.hasOwnProperty.call(actor, "metadata")) {
+    assertPlainObject(actor.metadata, "action.actor.metadata");
+    metadata = normalizeForCanonicalJson(actor.metadata, { path: "$.actor.metadata" });
+  }
+  return normalizeForCanonicalJson(
+    {
+      operatorId,
+      ...(role ? { role } : {}),
+      ...(tenantId ? { tenantId } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      ...(metadata ? { metadata } : {})
+    },
+    { path: "$.actor" }
+  );
+}
+
+function normalizeOperatorActionSignature(signature) {
+  assertPlainObject(signature, "action.signature");
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: (() => {
+        const schemaVersion = assertNonEmptyString(signature.schemaVersion, "action.signature.schemaVersion");
+        if (schemaVersion !== OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION) {
+          throw new TypeError(`action.signature.schemaVersion must be ${OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION}`);
+        }
+        return schemaVersion;
+      })(),
+      algorithm: (() => {
+        const algorithm = assertNonEmptyString(signature.algorithm, "action.signature.algorithm").toLowerCase();
+        if (algorithm !== "ed25519") throw new TypeError("action.signature.algorithm must be ed25519");
+        return "ed25519";
+      })(),
+      keyId: assertId(signature.keyId, "action.signature.keyId", { max: 256 }),
+      signedAt: assertIsoDateTime(signature.signedAt, "action.signature.signedAt"),
+      actionHash: assertSha256Hex(signature.actionHash, "action.signature.actionHash"),
+      signatureBase64: assertNonEmptyString(signature.signatureBase64, "action.signature.signatureBase64")
+    },
+    { path: "$.signature" }
+  );
+}
+
+export function buildOperatorActionV1(action = {}) {
+  assertPlainObject(action, "action");
+  if (action.schemaVersion !== undefined && action.schemaVersion !== null) {
+    const schemaVersion = assertNonEmptyString(action.schemaVersion, "action.schemaVersion");
+    if (schemaVersion !== OPERATOR_ACTION_SCHEMA_VERSION) {
+      throw new TypeError(`action.schemaVersion must be ${OPERATOR_ACTION_SCHEMA_VERSION}`);
+    }
+  }
+
+  let metadata = null;
+  if (Object.prototype.hasOwnProperty.call(action, "metadata")) {
+    assertPlainObject(action.metadata, "action.metadata");
+    metadata = normalizeForCanonicalJson(action.metadata, { path: "$.metadata" });
+  }
+
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: OPERATOR_ACTION_SCHEMA_VERSION,
+      ...(assertOptionalId(action.actionId, "action.actionId", { max: 240 })
+        ? { actionId: assertOptionalId(action.actionId, "action.actionId", { max: 240 }) }
+        : {}),
+      caseRef: normalizeCaseRef(action),
+      action: assertAction(action.action),
+      justificationCode: assertJustificationCode(action.justificationCode),
+      ...(assertOptionalJustificationText(action.justification) ? { justification: assertOptionalJustificationText(action.justification) } : {}),
+      actor: normalizeActor(action.actor),
+      actedAt: assertIsoDateTime(action.actedAt, "action.actedAt"),
+      ...(metadata ? { metadata } : {})
+    },
+    { path: "$" }
+  );
+
+  return normalized;
+}
+
+function normalizeSignedOperatorActionV1(action = {}) {
+  const normalizedAction = buildOperatorActionV1(action);
+  const signature = normalizeOperatorActionSignature(action.signature);
+  return normalizeForCanonicalJson(
+    {
+      ...normalizedAction,
+      signature
+    },
+    { path: "$" }
+  );
+}
+
+export function computeOperatorActionHashV1({ action } = {}) {
+  const normalizedAction = buildOperatorActionV1(action ?? {});
+  return sha256Hex(canonicalJsonStringify(normalizedAction));
+}
+
+export function signOperatorActionV1({ action, signedAt, publicKeyPem, privateKeyPem } = {}) {
+  const normalizedAction = buildOperatorActionV1(action ?? {});
+  const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+  const signerPrivateKeyPem = assertPemString(privateKeyPem, "privateKeyPem");
+  const actionHash = computeOperatorActionHashV1({ action: normalizedAction });
+  const signatureBase64 = signHashHexEd25519(actionHash, signerPrivateKeyPem);
+  return normalizeForCanonicalJson(
+    {
+      ...normalizedAction,
+      signature: {
+        schemaVersion: OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION,
+        algorithm: "ed25519",
+        keyId: keyIdFromPublicKeyPem(signerPublicKeyPem),
+        signedAt: assertIsoDateTime(signedAt ?? normalizedAction.actedAt, "signedAt"),
+        actionHash,
+        signatureBase64
+      }
+    },
+    { path: "$" }
+  );
+}
+
+export function verifyOperatorActionV1({ action, publicKeyPem } = {}) {
+  try {
+    const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+    assertPlainObject(action, "action");
+
+    const schemaVersion = assertNonEmptyString(action.schemaVersion, "action.schemaVersion");
+    if (schemaVersion !== OPERATOR_ACTION_SCHEMA_VERSION) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_SCHEMA_MISMATCH",
+        error: `action.schemaVersion must be ${OPERATOR_ACTION_SCHEMA_VERSION}`
+      };
+    }
+
+    if (!action.signature || typeof action.signature !== "object" || Array.isArray(action.signature)) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_SCHEMA_INVALID",
+        error: "action.signature must be an object"
+      };
+    }
+
+    if (String(action.signature.schemaVersion ?? "") !== OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_SIGNATURE_SCHEMA_MISMATCH",
+        error: `action.signature.schemaVersion must be ${OPERATOR_ACTION_SIGNATURE_SCHEMA_VERSION}`
+      };
+    }
+
+    const normalized = normalizeSignedOperatorActionV1(action);
+
+    const expectedKeyId = keyIdFromPublicKeyPem(signerPublicKeyPem);
+    if (normalized.signature.keyId !== expectedKeyId) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_KEY_ID_MISMATCH",
+        error: "signature keyId mismatch"
+      };
+    }
+
+    const actionHash = computeOperatorActionHashV1({ action: normalized });
+    if (normalized.signature.actionHash !== actionHash) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_HASH_MISMATCH",
+        error: "action hash mismatch"
+      };
+    }
+
+    const signatureValid = verifyHashHexEd25519({
+      hashHex: actionHash,
+      signatureBase64: normalized.signature.signatureBase64,
+      publicKeyPem: signerPublicKeyPem
+    });
+    if (!signatureValid) {
+      return {
+        ok: false,
+        code: "OPERATOR_ACTION_SIGNATURE_INVALID",
+        error: "signature invalid"
+      };
+    }
+
+    const normalizedAction = buildOperatorActionV1(normalized);
+    return {
+      ok: true,
+      code: null,
+      error: null,
+      actionHash,
+      keyId: normalized.signature.keyId,
+      action: normalizedAction,
+      signedAction: normalized
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "OPERATOR_ACTION_SCHEMA_INVALID",
+      error: err?.message ?? String(err ?? "")
+    };
+  }
+}

package/src/core/paid-tool-manifest.js

@@ -0,0 +1,318 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const PAID_TOOL_MANIFEST_SCHEMA_VERSION_V1 = "PaidToolManifest.v1";
+export const PAID_TOOL_MANIFEST_SCHEMA_VERSION_V2 = "PaidToolManifest.v2";
+export const PAID_TOOL_MANIFEST_SCHEMA_VERSION = PAID_TOOL_MANIFEST_SCHEMA_VERSION_V1;
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+}
+
+function normalizeNonEmptyString(value, name, { max = 256 } = {}) {
+  const text = typeof value === "string" ? value.trim() : "";
+  if (!text) throw new TypeError(`${name} is required`);
+  if (text.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  return text;
+}
+
+function normalizeOptionalString(value, name, { max = 2048 } = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const text = String(value).trim();
+  if (text.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  return text;
+}
+
+function normalizeOptionalAbsoluteHttpUrl(value, name) {
+  const raw = normalizeOptionalString(value, name, { max: 2048 });
+  if (!raw) return null;
+  let parsed = null;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new TypeError(`${name} must be an absolute URL`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new TypeError(`${name} must use http or https`);
+  }
+  return parsed.toString();
+}
+
+function normalizeManifestSchemaVersion(value) {
+  const text = normalizeNonEmptyString(value, "manifest.schemaVersion", { max: 64 });
+  if (text === PAID_TOOL_MANIFEST_SCHEMA_VERSION_V1 || text === PAID_TOOL_MANIFEST_SCHEMA_VERSION_V2) return text;
+  throw new TypeError(
+    `manifest.schemaVersion must be ${PAID_TOOL_MANIFEST_SCHEMA_VERSION_V1} or ${PAID_TOOL_MANIFEST_SCHEMA_VERSION_V2}`
+  );
+}
+
+function normalizeToolClass(value, name) {
+  const raw = normalizeOptionalString(value, name, { max: 32 });
+  const normalized = raw ? raw.toLowerCase() : null;
+  if (normalized === null) return null;
+  if (!["read", "compute", "action"].includes(normalized)) {
+    throw new TypeError(`${name} must be read|compute|action`);
+  }
+  return normalized;
+}
+
+function normalizeRiskLevel(value, name) {
+  const raw = normalizeOptionalString(value, name, { max: 32 });
+  if (!raw) return null;
+  const normalized = raw.toLowerCase() === "med" ? "medium" : raw.toLowerCase();
+  if (!["low", "medium", "high"].includes(normalized)) {
+    throw new TypeError(`${name} must be low|medium|high`);
+  }
+  return normalized;
+}
+
+function normalizeStringArray(value, name, { maxItems = 32, maxLen = 64 } = {}) {
+  if (value === null || value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`);
+  const out = [];
+  const seen = new Set();
+  for (let i = 0; i < value.length; i += 1) {
+    const row = normalizeNonEmptyString(value[i], `${name}[${i}]`, { max: maxLen }).toLowerCase();
+    if (seen.has(row)) continue;
+    seen.add(row);
+    out.push(row);
+    if (out.length > maxItems) throw new TypeError(`${name} must contain <= ${maxItems} items`);
+  }
+  return out;
+}
+
+function normalizeRequiredSignatures(value, name) {
+  const allowed = new Set(["quote", "output", "refund_decision"]);
+  const out = normalizeStringArray(value, name, { maxItems: 8, maxLen: 32 });
+  for (const item of out) {
+    if (!allowed.has(item)) throw new TypeError(`${name} contains unsupported value: ${item}`);
+  }
+  return out;
+}
+
+function normalizeRequestBinding(value, name) {
+  const raw = normalizeOptionalString(value, name, { max: 32 });
+  if (!raw) return null;
+  const normalized = raw.toLowerCase();
+  if (!["strict", "recommended", "none"].includes(normalized)) {
+    throw new TypeError(`${name} must be strict|recommended|none`);
+  }
+  return normalized;
+}
+
+function normalizeHttpMethod(value, name) {
+  const method = normalizeNonEmptyString(value ?? "GET", name, { max: 16 }).toUpperCase();
+  if (!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"].includes(method)) {
+    throw new TypeError(`${name} must be GET|POST|PUT|PATCH|DELETE|HEAD`);
+  }
+  return method;
+}
+
+function normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value.trim().toUpperCase() : "USD";
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(raw)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9_]{2,11}$`);
+  return raw;
+}
+
+function normalizePositiveSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function normalizeRoutePath(value, name) {
+  const text = normalizeNonEmptyString(value, name, { max: 1024 });
+  if (!text.startsWith("/")) throw new TypeError(`${name} must start with /`);
+  if (text.includes("..")) throw new TypeError(`${name} must not contain path traversal`);
+  return text;
+}
+
+function normalizePricing(rawPricing, defaults, fieldPath) {
+  const pricing = rawPricing && typeof rawPricing === "object" && !Array.isArray(rawPricing) ? rawPricing : {};
+  const amountCents = normalizePositiveSafeInt(pricing.amountCents ?? defaults.amountCents ?? 500, `${fieldPath}.amountCents`);
+  const currency = normalizeCurrency(pricing.currency ?? defaults.currency ?? "USD", `${fieldPath}.currency`);
+  return normalizeForCanonicalJson({ amountCents, currency }, { path: "$" });
+}
+
+function normalizeToolSecurity(rawSecurity, defaults, fieldPath) {
+  const security = rawSecurity && typeof rawSecurity === "object" && !Array.isArray(rawSecurity) ? rawSecurity : {};
+  const requiredSignatures = normalizeRequiredSignatures(
+    security.requiredSignatures ?? security.required_signatures ?? defaults.requiredSignatures ?? [],
+    `${fieldPath}.requiredSignatures`
+  );
+  const requestBinding =
+    normalizeRequestBinding(security.requestBinding ?? security.request_binding ?? defaults.requestBinding, `${fieldPath}.requestBinding`) ??
+    "recommended";
+  return normalizeForCanonicalJson(
+    {
+      requiredSignatures,
+      requestBinding
+    },
+    { path: "$" }
+  );
+}
+
+function normalizeTool(rawTool, defaults, { index, schemaVersion }) {
+  assertPlainObject(rawTool, `tools[${index}]`);
+  const toolId = normalizeNonEmptyString(rawTool.toolId, `tools[${index}].toolId`, { max: 128 });
+  const mcpToolName = normalizeOptionalString(rawTool.mcpToolName, `tools[${index}].mcpToolName`, { max: 180 });
+  const description = normalizeOptionalString(rawTool.description, `tools[${index}].description`, { max: 1000 });
+  const method = normalizeHttpMethod(rawTool.method ?? "GET", `tools[${index}].method`);
+  const upstreamPath = normalizeOptionalString(rawTool.upstreamPath, `tools[${index}].upstreamPath`, { max: 1024 });
+  const paidPath = normalizeRoutePath(rawTool.paidPath, `tools[${index}].paidPath`);
+  const idempotency = normalizeOptionalString(rawTool.idempotency, `tools[${index}].idempotency`, { max: 64 }) ?? defaults.idempotency ?? "idempotent";
+  const signatureMode = normalizeOptionalString(rawTool.signatureMode, `tools[${index}].signatureMode`, { max: 64 }) ?? defaults.signatureMode ?? "required";
+  if (!["idempotent", "non_idempotent", "side_effecting"].includes(String(idempotency))) {
+    throw new TypeError(`tools[${index}].idempotency must be idempotent|non_idempotent|side_effecting`);
+  }
+  if (!["required", "optional"].includes(String(signatureMode))) {
+    throw new TypeError(`tools[${index}].signatureMode must be required|optional`);
+  }
+  const pricing = normalizePricing(rawTool.pricing, defaults, `tools[${index}].pricing`);
+  const auth =
+    rawTool.auth && typeof rawTool.auth === "object" && !Array.isArray(rawTool.auth)
+      ? normalizeForCanonicalJson(rawTool.auth, { path: "$" })
+      : normalizeForCanonicalJson({ mode: "none" }, { path: "$" });
+  const metadata =
+    rawTool.metadata && typeof rawTool.metadata === "object" && !Array.isArray(rawTool.metadata)
+      ? normalizeForCanonicalJson(rawTool.metadata, { path: "$" })
+      : null;
+
+  const isV2 = schemaVersion === PAID_TOOL_MANIFEST_SCHEMA_VERSION_V2;
+  const toolClass = normalizeToolClass(
+    rawTool.toolClass ?? rawTool.tool_class ?? defaults.toolClass ?? null,
+    `tools[${index}].toolClass`
+  );
+  const riskLevel = normalizeRiskLevel(
+    rawTool.riskLevel ?? rawTool.risk_level ?? defaults.riskLevel ?? null,
+    `tools[${index}].riskLevel`
+  );
+  const capabilityTags = normalizeStringArray(
+    rawTool.capabilityTags ?? rawTool.capability_tags ?? rawTool.tags ?? [],
+    `tools[${index}].capabilityTags`,
+    { maxItems: 64, maxLen: 80 }
+  );
+  const security = normalizeToolSecurity(rawTool.security ?? null, defaults, `tools[${index}].security`);
+
+  return normalizeForCanonicalJson(
+    {
+      toolId,
+      mcpToolName,
+      description,
+      method,
+      upstreamPath,
+      paidPath,
+      pricing,
+      idempotency,
+      signatureMode,
+      auth,
+      metadata,
+      ...(isV2
+        ? {
+            toolClass: toolClass ?? "read",
+            riskLevel: riskLevel ?? "low",
+            capabilityTags,
+            security
+          }
+        : {})
+    },
+    { path: "$" }
+  );
+}
+
+export function normalizePaidToolManifestV1(manifestInput) {
+  assertPlainObject(manifestInput, "manifest");
+  const schemaVersion = normalizeManifestSchemaVersion(manifestInput.schemaVersion);
+  const isV2 = schemaVersion === PAID_TOOL_MANIFEST_SCHEMA_VERSION_V2;
+  const providerId = normalizeNonEmptyString(manifestInput.providerId, "manifest.providerId", { max: 160 });
+  const upstreamBaseUrl = normalizeOptionalString(manifestInput.upstreamBaseUrl, "manifest.upstreamBaseUrl", { max: 2048 });
+  const publishProofJwksUrl = normalizeOptionalAbsoluteHttpUrl(
+    manifestInput.publishProofJwksUrl,
+    "manifest.publishProofJwksUrl"
+  );
+  const sourceOpenApiPath = normalizeOptionalString(manifestInput.sourceOpenApiPath, "manifest.sourceOpenApiPath", { max: 2048 });
+
+  const defaultsRaw =
+    manifestInput.defaults && typeof manifestInput.defaults === "object" && !Array.isArray(manifestInput.defaults)
+      ? manifestInput.defaults
+      : {};
+  const defaults = normalizeForCanonicalJson(
+    {
+      amountCents: normalizePositiveSafeInt(defaultsRaw.amountCents ?? 500, "manifest.defaults.amountCents"),
+      currency: normalizeCurrency(defaultsRaw.currency ?? "USD", "manifest.defaults.currency"),
+      idempotency: normalizeOptionalString(defaultsRaw.idempotency, "manifest.defaults.idempotency", { max: 64 }) ?? "idempotent",
+      signatureMode: normalizeOptionalString(defaultsRaw.signatureMode, "manifest.defaults.signatureMode", { max: 64 }) ?? "required",
+      ...(isV2
+        ? {
+            toolClass: normalizeToolClass(defaultsRaw.toolClass ?? defaultsRaw.tool_class ?? null, "manifest.defaults.toolClass") ?? "read",
+            riskLevel: normalizeRiskLevel(defaultsRaw.riskLevel ?? defaultsRaw.risk_level ?? null, "manifest.defaults.riskLevel") ?? "low",
+            requiredSignatures: normalizeRequiredSignatures(
+              defaultsRaw.requiredSignatures ?? defaultsRaw.required_signatures ?? ["output"],
+              "manifest.defaults.requiredSignatures"
+            ),
+            requestBinding:
+              normalizeRequestBinding(
+                defaultsRaw.requestBinding ?? defaultsRaw.request_binding ?? null,
+                "manifest.defaults.requestBinding"
+              ) ?? "recommended"
+          }
+        : {})
+    },
+    { path: "$" }
+  );
+  if (!["idempotent", "non_idempotent", "side_effecting"].includes(String(defaults.idempotency))) {
+    throw new TypeError("manifest.defaults.idempotency must be idempotent|non_idempotent|side_effecting");
+  }
+  if (!["required", "optional"].includes(String(defaults.signatureMode))) {
+    throw new TypeError("manifest.defaults.signatureMode must be required|optional");
+  }
+
+  if (!Array.isArray(manifestInput.tools) || manifestInput.tools.length === 0) {
+    throw new TypeError("manifest.tools must be a non-empty array");
+  }
+  const tools = manifestInput.tools.map((row, index) => normalizeTool(row, defaults, { index, schemaVersion }));
+  const seenToolIds = new Set();
+  const seenPaidPaths = new Set();
+  for (const tool of tools) {
+    if (seenToolIds.has(tool.toolId)) throw new TypeError(`manifest.tools contains duplicate toolId: ${tool.toolId}`);
+    if (seenPaidPaths.has(tool.paidPath)) throw new TypeError(`manifest.tools contains duplicate paidPath: ${tool.paidPath}`);
+    seenToolIds.add(tool.toolId);
+    seenPaidPaths.add(tool.paidPath);
+  }
+
+  const capabilityTags = normalizeStringArray(
+    manifestInput.capabilityTags ?? manifestInput.capability_tags ?? manifestInput.tags ?? [],
+    "manifest.capabilityTags",
+    { maxItems: 64, maxLen: 80 }
+  );
+
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion,
+      providerId,
+      upstreamBaseUrl,
+      publishProofJwksUrl,
+      sourceOpenApiPath,
+      defaults,
+      tools,
+      ...(isV2 ? { capabilityTags } : {})
+    },
+    { path: "$" }
+  );
+}
+
+export function validatePaidToolManifestV1(manifestInput) {
+  try {
+    const manifest = normalizePaidToolManifestV1(manifestInput);
+    return { ok: true, manifest };
+  } catch (err) {
+    return { ok: false, code: "PAID_TOOL_MANIFEST_INVALID", message: err?.message ?? String(err ?? "") };
+  }
+}
+
+export function computePaidToolManifestHashV1(manifestInput) {
+  const manifest = normalizePaidToolManifestV1(manifestInput);
+  return sha256Hex(canonicalJsonStringify(manifest));
+}