settld 0.1.2 → 0.2.0

package/src/core/provider-publish-proof.js

@@ -0,0 +1,396 @@
+import { createPublicKey, verify as nodeVerify, sign as nodeSign } from "node:crypto";
+
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { checkUrlSafety } from "./url-safety.js";
+import { keyIdFromPublicKeyPem, sha256Hex } from "./crypto.js";
+import { keyMapFromSettldKeyset } from "./settld-keys.js";
+
+export const PROVIDER_PUBLISH_PROOF_AUDIENCE = "settld.marketplace.publish";
+export const PROVIDER_PUBLISH_PROOF_TYPE = "settld.marketplace.publish_proof.v1";
+export const PROVIDER_PUBLISH_PROOF_SCHEMA_VERSION = "ProviderPublishProofPayload.v1";
+
+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 assertNonEmptyPem(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+  return String(value);
+}
+
+function normalizeUnixSeconds(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer unix timestamp`);
+  return n;
+}
+
+function normalizeSha256Hex(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 normalizeOptionalText(value, name, { max = 256 } = {}) {
+  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 b64urlJson(value) {
+  return Buffer.from(canonicalJsonStringify(normalizeForCanonicalJson(value, { path: "$" })), "utf8").toString("base64url");
+}
+
+function parseCompactJws(token) {
+  const raw = assertNonEmptyString(token, "publishProof");
+  const parts = raw.split(".");
+  if (parts.length !== 3) throw new TypeError("publishProof must be compact JWS with 3 segments");
+  const [headerB64, payloadB64, sigB64] = parts;
+  if (!headerB64 || !payloadB64 || !sigB64) throw new TypeError("publishProof contains empty JWS segment");
+
+  let header = null;
+  let payload = null;
+  let signature = null;
+  try {
+    header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+  } catch (err) {
+    throw new TypeError(`publishProof header is invalid: ${err?.message ?? String(err ?? "")}`);
+  }
+  try {
+    payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+  } catch (err) {
+    throw new TypeError(`publishProof payload is invalid: ${err?.message ?? String(err ?? "")}`);
+  }
+  try {
+    signature = Buffer.from(sigB64, "base64url");
+  } catch (err) {
+    throw new TypeError(`publishProof signature is invalid: ${err?.message ?? String(err ?? "")}`);
+  }
+  if (!header || typeof header !== "object" || Array.isArray(header)) throw new TypeError("publishProof header must be an object");
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("publishProof payload must be an object");
+  if (signature.length === 0) throw new TypeError("publishProof signature must be non-empty");
+  return {
+    token: raw,
+    header,
+    payload,
+    signature,
+    signingInput: `${headerB64}.${payloadB64}`
+  };
+}
+
+function normalizeOkpEd25519Jwk(input, fieldPath = "jwk") {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError(`${fieldPath} must be an object`);
+  const kty = assertNonEmptyString(input.kty, `${fieldPath}.kty`);
+  const crv = assertNonEmptyString(input.crv, `${fieldPath}.crv`);
+  const x = assertNonEmptyString(input.x, `${fieldPath}.x`);
+  if (kty !== "OKP") throw new TypeError(`${fieldPath}.kty must be OKP`);
+  if (crv !== "Ed25519") throw new TypeError(`${fieldPath}.crv must be Ed25519`);
+  return normalizeForCanonicalJson({ kty: "OKP", crv: "Ed25519", x }, { path: "$" });
+}
+
+function keyEntryToKeyEvidence(keyEntry, expectedKid) {
+  if (!keyEntry || typeof keyEntry !== "object" || Array.isArray(keyEntry)) {
+    throw new TypeError("keyEntry must be an object");
+  }
+  const publicKeyPem = assertNonEmptyPem(keyEntry.publicKeyPem, "keyEntry.publicKeyPem");
+  const derivedKid = keyIdFromPublicKeyPem(publicKeyPem);
+  const kid = expectedKid ? assertNonEmptyString(expectedKid, "kid") : derivedKid;
+  if (kid !== derivedKid) throw new TypeError("publish proof kid does not match resolved public key");
+
+  let jwk = null;
+  if (keyEntry.kty || keyEntry.crv || keyEntry.x) {
+    jwk = normalizeOkpEd25519Jwk(keyEntry, "jwks.keys[]");
+  } else {
+    const exported = createPublicKey(publicKeyPem).export({ format: "jwk" });
+    jwk = normalizeOkpEd25519Jwk(exported, "publicKeyPem.jwk");
+  }
+  const jwkThumbprintSha256 = sha256Hex(canonicalJsonStringify(jwk));
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: "VerificationKeyEvidence.v1",
+      keyId: kid,
+      publicKeyPem,
+      jwk,
+      jwkThumbprintSha256
+    },
+    { path: "$" }
+  );
+}
+
+export function computeProviderRefFromPublishProofJwk(jwkInput) {
+  const jwk = normalizeOkpEd25519Jwk(jwkInput, "jwk");
+  const thumbprint = sha256Hex(canonicalJsonStringify(jwk));
+  return `jwk:${thumbprint}`;
+}
+
+export function buildProviderPublishProofPayloadV1({
+  aud = PROVIDER_PUBLISH_PROOF_AUDIENCE,
+  typ = PROVIDER_PUBLISH_PROOF_TYPE,
+  manifestHash,
+  providerId,
+  iat,
+  exp,
+  nonce = null
+} = {}) {
+  const normalizedIat = normalizeUnixSeconds(iat, "iat");
+  const normalizedExp = normalizeUnixSeconds(exp, "exp");
+  if (normalizedExp <= normalizedIat) throw new TypeError("exp must be greater than iat");
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: PROVIDER_PUBLISH_PROOF_SCHEMA_VERSION,
+      aud: assertNonEmptyString(aud, "aud"),
+      typ: assertNonEmptyString(typ, "typ"),
+      manifestHash: normalizeSha256Hex(manifestHash, "manifestHash"),
+      providerId: assertNonEmptyString(providerId, "providerId"),
+      iat: normalizedIat,
+      exp: normalizedExp,
+      ...(normalizeOptionalText(nonce, "nonce", { max: 256 }) ? { nonce: normalizeOptionalText(nonce, "nonce", { max: 256 }) } : {})
+    },
+    { path: "$" }
+  );
+}
+
+export function mintProviderPublishProofTokenV1({ payload, keyId = null, publicKeyPem = null, privateKeyPem } = {}) {
+  const normalizedPayload = buildProviderPublishProofPayloadV1(payload ?? {});
+  const privatePem = assertNonEmptyPem(privateKeyPem, "privateKeyPem");
+  const normalizedPublicKeyPem =
+    publicKeyPem === null || publicKeyPem === undefined ? null : assertNonEmptyPem(publicKeyPem, "publicKeyPem");
+  const derivedKid = normalizedPublicKeyPem ? keyIdFromPublicKeyPem(normalizedPublicKeyPem) : null;
+  const normalizedKid = keyId === null || keyId === undefined || String(keyId).trim() === "" ? derivedKid : String(keyId).trim();
+  if (!normalizedKid) throw new TypeError("keyId is required (or provide publicKeyPem)");
+  if (derivedKid && normalizedKid !== derivedKid) throw new TypeError("keyId does not match publicKeyPem");
+
+  const header = normalizeForCanonicalJson(
+    {
+      alg: "EdDSA",
+      kid: normalizedKid,
+      typ: "JWT"
+    },
+    { path: "$" }
+  );
+  const headerB64 = b64urlJson(header);
+  const payloadB64 = b64urlJson(normalizedPayload);
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signature = nodeSign(null, Buffer.from(signingInput, "utf8"), privatePem);
+  const token = `${signingInput}.${signature.toString("base64url")}`;
+
+  return {
+    token,
+    tokenSha256: sha256Hex(token),
+    header,
+    payload: normalizedPayload,
+    kid: normalizedKid
+  };
+}
+
+export function verifyProviderPublishProofTokenV1({
+  token,
+  jwks,
+  expectedManifestHash,
+  expectedProviderId,
+  expectedAudience = PROVIDER_PUBLISH_PROOF_AUDIENCE,
+  expectedType = PROVIDER_PUBLISH_PROOF_TYPE,
+  nowUnixSeconds = Math.floor(Date.now() / 1000)
+} = {}) {
+  try {
+    const parsed = parseCompactJws(token);
+    const alg = assertNonEmptyString(parsed.header.alg, "publishProof.header.alg");
+    if (alg !== "EdDSA") {
+      return { ok: false, code: "PROVIDER_PUBLISH_PROOF_ALG_INVALID", message: "publishProof.header.alg must be EdDSA" };
+    }
+    const kid = assertNonEmptyString(parsed.header.kid, "publishProof.header.kid");
+    if (!Number.isSafeInteger(nowUnixSeconds) || nowUnixSeconds <= 0) {
+      throw new TypeError("nowUnixSeconds must be a positive safe integer");
+    }
+
+    const payload = buildProviderPublishProofPayloadV1(parsed.payload);
+    if (payload.aud !== expectedAudience) {
+      return {
+        ok: false,
+        code: "PROVIDER_PUBLISH_PROOF_AUD_MISMATCH",
+        message: "publish proof aud mismatch",
+        expected: expectedAudience,
+        actual: payload.aud
+      };
+    }
+    if (payload.typ !== expectedType) {
+      return {
+        ok: false,
+        code: "PROVIDER_PUBLISH_PROOF_TYPE_MISMATCH",
+        message: "publish proof typ mismatch",
+        expected: expectedType,
+        actual: payload.typ
+      };
+    }
+
+    const expectedManifest = normalizeSha256Hex(expectedManifestHash, "expectedManifestHash");
+    if (payload.manifestHash !== expectedManifest) {
+      return {
+        ok: false,
+        code: "PROVIDER_PUBLISH_PROOF_MANIFEST_HASH_MISMATCH",
+        message: "publish proof manifest hash mismatch",
+        expected: expectedManifest,
+        actual: payload.manifestHash
+      };
+    }
+
+    const expectedProvider = assertNonEmptyString(expectedProviderId, "expectedProviderId");
+    if (payload.providerId !== expectedProvider) {
+      return {
+        ok: false,
+        code: "PROVIDER_PUBLISH_PROOF_PROVIDER_MISMATCH",
+        message: "publish proof providerId mismatch",
+        expected: expectedProvider,
+        actual: payload.providerId
+      };
+    }
+
+    if (payload.exp <= nowUnixSeconds) {
+      return { ok: false, code: "PROVIDER_PUBLISH_PROOF_EXPIRED", message: "publish proof is expired" };
+    }
+    if (payload.iat > nowUnixSeconds + 300) {
+      return { ok: false, code: "PROVIDER_PUBLISH_PROOF_IAT_FUTURE", message: "publish proof iat is too far in the future" };
+    }
+
+    const keyMap = keyMapFromSettldKeyset(jwks);
+    const keyEntry = keyMap.get(kid) ?? null;
+    if (!keyEntry?.publicKeyPem) {
+      return { ok: false, code: "PROVIDER_PUBLISH_PROOF_UNKNOWN_KID", message: "publish proof kid not found in jwks", kid };
+    }
+    if (keyEntry.alg && String(keyEntry.alg).trim() !== "" && String(keyEntry.alg).trim() !== "EdDSA") {
+      return {
+        ok: false,
+        code: "PROVIDER_PUBLISH_PROOF_KEY_ALG_INVALID",
+        message: "jwks key alg must be EdDSA when provided",
+        kid
+      };
+    }
+
+    const signatureValid = nodeVerify(
+      null,
+      Buffer.from(parsed.signingInput, "utf8"),
+      keyEntry.publicKeyPem,
+      parsed.signature
+    );
+    if (!signatureValid) {
+      return { ok: false, code: "PROVIDER_PUBLISH_PROOF_SIGNATURE_INVALID", message: "publish proof signature verification failed", kid };
+    }
+
+    const keyEvidence = keyEntryToKeyEvidence(keyEntry, kid);
+    const providerRef = computeProviderRefFromPublishProofJwk(keyEvidence.jwk);
+    return {
+      ok: true,
+      code: null,
+      header: parsed.header,
+      payload,
+      kid,
+      keyEvidence,
+      providerRef,
+      tokenSha256: sha256Hex(assertNonEmptyString(token, "token"))
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "PROVIDER_PUBLISH_PROOF_INVALID",
+      message: err?.message ?? String(err ?? "")
+    };
+  }
+}
+
+function makeProofError(code, message, details = null, { statusCode = 400 } = {}) {
+  const err = new Error(message);
+  err.code = code;
+  err.statusCode = statusCode;
+  if (details !== null && details !== undefined) err.details = details;
+  return err;
+}
+
+export async function fetchProviderPublishProofJwks({
+  jwksUrl,
+  fetchFn = globalThis.fetch,
+  timeoutMs = 8_000,
+  maxBytes = 256 * 1024,
+  allowHttp = false,
+  allowPrivate = false,
+  allowLoopback = false
+} = {}) {
+  const urlText = assertNonEmptyString(jwksUrl, "publishProofJwksUrl");
+  const safe = await checkUrlSafety(urlText, {
+    allowHttp,
+    allowPrivate,
+    allowLoopback,
+    allowedSchemes: ["https"]
+  });
+  if (!safe.ok) {
+    throw makeProofError(
+      "PROVIDER_PUBLISH_PROOF_JWKS_URL_UNSAFE",
+      "publish proof jwks url is unsafe",
+      { code: safe.code, message: safe.message, hostname: safe.hostname ?? null }
+    );
+  }
+
+  if (typeof fetchFn !== "function") {
+    throw makeProofError("PROVIDER_PUBLISH_PROOF_FETCH_UNAVAILABLE", "fetch is unavailable in this runtime");
+  }
+
+  const timeout = Number(timeoutMs);
+  const controller = new AbortController();
+  const timer = Number.isFinite(timeout) && timeout > 0 ? setTimeout(() => controller.abort(), timeout) : null;
+  let response = null;
+  try {
+    response = await fetchFn(urlText, {
+      method: "GET",
+      headers: {
+        accept: "application/json"
+      },
+      redirect: "error",
+      signal: controller.signal
+    });
+  } catch (err) {
+    throw makeProofError(
+      "PROVIDER_PUBLISH_PROOF_JWKS_FETCH_FAILED",
+      `publish proof jwks fetch failed: ${err?.message ?? String(err ?? "")}`,
+      null,
+      { statusCode: 502 }
+    );
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+
+  if (!response?.ok) {
+    throw makeProofError(
+      "PROVIDER_PUBLISH_PROOF_JWKS_FETCH_FAILED",
+      `publish proof jwks fetch returned ${Number(response?.status ?? 0)}`,
+      { statusCode: Number(response?.status ?? 0) || null },
+      { statusCode: 502 }
+    );
+  }
+
+  let text = "";
+  try {
+    text = await response.text();
+  } catch (err) {
+    throw makeProofError(
+      "PROVIDER_PUBLISH_PROOF_JWKS_BODY_INVALID",
+      `publish proof jwks body read failed: ${err?.message ?? String(err ?? "")}`
+    );
+  }
+  if (Buffer.byteLength(text, "utf8") > Number(maxBytes)) {
+    throw makeProofError("PROVIDER_PUBLISH_PROOF_JWKS_BODY_TOO_LARGE", `publish proof jwks body must be <= ${Number(maxBytes)} bytes`);
+  }
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw makeProofError("PROVIDER_PUBLISH_PROOF_JWKS_JSON_INVALID", `publish proof jwks must be valid JSON: ${err?.message ?? String(err ?? "")}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw makeProofError("PROVIDER_PUBLISH_PROOF_JWKS_JSON_INVALID", "publish proof jwks must be an object");
+  }
+  if (!Array.isArray(parsed.keys) || parsed.keys.length === 0) {
+    throw makeProofError("PROVIDER_PUBLISH_PROOF_JWKS_KEYS_MISSING", "publish proof jwks.keys must be a non-empty array");
+  }
+  return normalizeForCanonicalJson(parsed, { path: "$" });
+}

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

@@ -0,0 +1,170 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const TOOL_PROVIDER_QUOTE_PAYLOAD_SCHEMA_VERSION = "ToolProviderQuotePayload.v1";
+export const TOOL_PROVIDER_QUOTE_SIGNATURE_SCHEMA_VERSION = "ToolProviderQuoteSignature.v1";
+
+function assertNonEmptyString(v, name) {
+  if (typeof v !== "string" || v.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+  return v.trim();
+}
+
+function assertIsoDate(v, name) {
+  const value = assertNonEmptyString(v, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date-time`);
+  return value;
+}
+
+function assertPositiveSafeInt(v, name) {
+  const n = Number(v);
+  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function assertOptionalId(v, name) {
+  if (v === null || v === undefined || String(v).trim() === "") return null;
+  const out = String(v).trim();
+  if (!/^[A-Za-z0-9:._/-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:._/-]+$`);
+  if (out.length > 200) throw new TypeError(`${name} must be <= 200 chars`);
+  return out;
+}
+
+function assertCurrency(v, name) {
+  const out = assertNonEmptyString(v, name).toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(out)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9_]{2,11}$`);
+  return out;
+}
+
+function assertRequestBindingMode(v, name) {
+  const out = assertNonEmptyString(v, name).toLowerCase();
+  if (out !== "none" && out !== "strict") throw new TypeError(`${name} must be none|strict`);
+  return out;
+}
+
+function assertOptionalSha256Hex(v, name) {
+  if (v === null || v === undefined || String(v).trim() === "") return null;
+  const out = String(v).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be sha256 hex`);
+  return out;
+}
+
+function assertSha256Hex(v, name) {
+  const out = assertNonEmptyString(v, name).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be sha256 hex`);
+  return out;
+}
+
+function assertNonceHex(v, name) {
+  const out = assertNonEmptyString(v, name).toLowerCase();
+  if (!/^[0-9a-f]{16,128}$/.test(out)) throw new TypeError(`${name} must be hex (16..128 chars)`);
+  return out;
+}
+
+function normalizeBoolean(v) {
+  if (v === true) return true;
+  if (v === false) return false;
+  if (v === null || v === undefined) return false;
+  const raw = String(v).trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
+export function buildToolProviderQuotePayloadV1({
+  providerId,
+  toolId,
+  amountCents,
+  currency,
+  address,
+  network,
+  requestBindingMode = "none",
+  requestBindingSha256 = null,
+  quoteRequired = false,
+  quoteId = null,
+  spendAuthorizationMode = "optional",
+  quotedAt,
+  expiresAt
+} = {}) {
+  const normalizedRequestBindingMode = assertRequestBindingMode(requestBindingMode, "requestBindingMode");
+  const normalizedRequestBindingSha256 = assertOptionalSha256Hex(requestBindingSha256, "requestBindingSha256");
+  if (normalizedRequestBindingMode === "strict" && !normalizedRequestBindingSha256) {
+    throw new TypeError("requestBindingSha256 is required when requestBindingMode=strict");
+  }
+  const normalizedSpendAuthorizationMode = assertNonEmptyString(spendAuthorizationMode, "spendAuthorizationMode").toLowerCase();
+  if (normalizedSpendAuthorizationMode !== "optional" && normalizedSpendAuthorizationMode !== "required") {
+    throw new TypeError("spendAuthorizationMode must be optional|required");
+  }
+  const normalizedQuoteId = assertOptionalId(quoteId, "quoteId");
+  const payload = normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_PROVIDER_QUOTE_PAYLOAD_SCHEMA_VERSION,
+      providerId: assertOptionalId(providerId, "providerId") ?? (() => {
+        throw new TypeError("providerId is required");
+      })(),
+      toolId: assertOptionalId(toolId, "toolId") ?? (() => {
+        throw new TypeError("toolId is required");
+      })(),
+      amountCents: assertPositiveSafeInt(amountCents, "amountCents"),
+      currency: assertCurrency(currency, "currency"),
+      address: assertNonEmptyString(address, "address"),
+      network: assertNonEmptyString(network, "network"),
+      requestBindingMode: normalizedRequestBindingMode,
+      ...(normalizedRequestBindingSha256 ? { requestBindingSha256: normalizedRequestBindingSha256 } : {}),
+      quoteRequired: normalizeBoolean(quoteRequired),
+      ...(normalizedQuoteId ? { quoteId: normalizedQuoteId } : {}),
+      spendAuthorizationMode: normalizedSpendAuthorizationMode,
+      quotedAt: assertIsoDate(quotedAt, "quotedAt"),
+      expiresAt: assertIsoDate(expiresAt, "expiresAt")
+    },
+    { path: "$" }
+  );
+  if (Date.parse(payload.expiresAt) <= Date.parse(payload.quotedAt)) {
+    throw new TypeError("expiresAt must be after quotedAt");
+  }
+  return payload;
+}
+
+export function computeToolProviderQuotePayloadHashV1({ quote } = {}) {
+  const payload = buildToolProviderQuotePayloadV1(quote);
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function signToolProviderQuoteSignatureV1({ quote, nonce, signedAt, publicKeyPem, privateKeyPem } = {}) {
+  assertNonEmptyString(publicKeyPem, "publicKeyPem");
+  assertNonEmptyString(privateKeyPem, "privateKeyPem");
+  const keyId = keyIdFromPublicKeyPem(publicKeyPem);
+  const payload = buildToolProviderQuotePayloadV1(quote);
+  const payloadHashHex = computeToolProviderQuotePayloadHashV1({ quote: payload });
+  const signatureBase64 = signHashHexEd25519(payloadHashHex, privateKeyPem);
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: TOOL_PROVIDER_QUOTE_SIGNATURE_SCHEMA_VERSION,
+      algorithm: "ed25519",
+      keyId,
+      signedAt: assertIsoDate(signedAt, "signedAt"),
+      nonce: assertNonceHex(nonce, "nonce"),
+      payloadHash: payloadHashHex,
+      signatureBase64
+    },
+    { path: "$" }
+  );
+}
+
+export function verifyToolProviderQuoteSignatureV1({ quote, 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_QUOTE_SIGNATURE_SCHEMA_VERSION) {
+    throw new TypeError(`signature.schemaVersion must be ${TOOL_PROVIDER_QUOTE_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 = computeToolProviderQuotePayloadHashV1({ quote });
+  if (assertSha256Hex(signature.payloadHash, "signature.payloadHash") !== payloadHashHex) return false;
+  const signatureBase64 = assertNonEmptyString(signature.signatureBase64, "signature.signatureBase64");
+
+  return verifyHashHexEd25519({ hashHex: payloadHashHex, signatureBase64, publicKeyPem });
+}

package/src/core/settld-keys.js

@@ -0,0 +1,112 @@
+import { createPublicKey } from "node:crypto";
+
+import { normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem } from "./crypto.js";
+
+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-time`);
+}
+
+function normalizeKeyId({ keyId, publicKeyPem, fieldName = "keyId" } = {}) {
+  const derived = keyIdFromPublicKeyPem(publicKeyPem);
+  if (keyId === null || keyId === undefined || String(keyId).trim() === "") return derived;
+  const normalized = assertNonEmptyString(keyId, fieldName);
+  if (normalized !== derived) throw new TypeError(`${fieldName} does not match publicKeyPem`);
+  return normalized;
+}
+
+export function publicKeyPemToEd25519X(publicKeyPem) {
+  if (typeof publicKeyPem !== "string" || publicKeyPem.trim() === "") throw new TypeError("publicKeyPem must be a non-empty string");
+  const pem = publicKeyPem;
+  let jwk;
+  try {
+    jwk = createPublicKey(pem).export({ format: "jwk" });
+  } catch (err) {
+    throw new TypeError(`publicKeyPem is not a valid Ed25519 key: ${err?.message ?? String(err ?? "")}`);
+  }
+  if (!jwk || typeof jwk !== "object") throw new TypeError("publicKeyPem did not export as JWK");
+  if (String(jwk.kty ?? "") !== "OKP") throw new TypeError("publicKeyPem must export to JWK kty=OKP");
+  if (String(jwk.crv ?? "") !== "Ed25519") throw new TypeError("publicKeyPem must export to JWK crv=Ed25519");
+  const x = assertNonEmptyString(jwk.x, "jwk.x");
+  return x;
+}
+
+export function ed25519XToPublicKeyPem(x) {
+  const normalizedX = assertNonEmptyString(x, "x");
+  try {
+    const keyObj = createPublicKey({
+      key: { kty: "OKP", crv: "Ed25519", x: normalizedX },
+      format: "jwk"
+    });
+    return keyObj.export({ format: "pem", type: "spki" }).toString();
+  } catch (err) {
+    throw new TypeError(`x is not a valid Ed25519 JWK coordinate: ${err?.message ?? String(err ?? "")}`);
+  }
+}
+
+export function buildSettldPayKeysetV1({ activeKey, fallbackKeys = [], refreshedAt = new Date().toISOString() } = {}) {
+  if (!activeKey || typeof activeKey !== "object" || Array.isArray(activeKey)) {
+    throw new TypeError("activeKey must be an object");
+  }
+  assertIsoDate(refreshedAt, "refreshedAt");
+
+  const keyRows = [activeKey, ...(Array.isArray(fallbackKeys) ? fallbackKeys : [])];
+  const byKid = new Map();
+  for (const row of keyRows) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (typeof row.publicKeyPem !== "string" || row.publicKeyPem.trim() === "") throw new TypeError("publicKeyPem must be a non-empty string");
+    const publicKeyPem = row.publicKeyPem;
+    const kid = normalizeKeyId({ keyId: row.keyId ?? row.kid ?? null, publicKeyPem, fieldName: "keyId" });
+    if (byKid.has(kid)) continue;
+    byKid.set(
+      kid,
+      normalizeForCanonicalJson(
+        {
+          kty: "OKP",
+          crv: "Ed25519",
+          x: publicKeyPemToEd25519X(publicKeyPem),
+          kid,
+          use: "sig",
+          alg: "EdDSA"
+        },
+        { path: "$" }
+      )
+    );
+  }
+
+  return normalizeForCanonicalJson(
+    {
+      keys: Array.from(byKid.values()),
+      refreshedAt
+    },
+    { path: "$" }
+  );
+}
+
+export function publicKeyPemFromSettldKeysetEntry(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new TypeError("entry must be an object");
+  if (typeof entry.publicKeyPem === "string" && entry.publicKeyPem.trim() !== "") return entry.publicKeyPem;
+  const kty = assertNonEmptyString(entry.kty, "entry.kty");
+  const crv = assertNonEmptyString(entry.crv, "entry.crv");
+  if (kty !== "OKP" || crv !== "Ed25519") throw new TypeError("entry must be an Ed25519 OKP key");
+  return ed25519XToPublicKeyPem(entry.x);
+}
+
+export function keyMapFromSettldKeyset(keyset) {
+  if (!keyset || typeof keyset !== "object" || Array.isArray(keyset)) throw new TypeError("keyset must be an object");
+  const rows = Array.isArray(keyset.keys) ? keyset.keys : [];
+  const out = new Map();
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const kid = assertNonEmptyString(row.kid, "keyset.keys[].kid");
+    const publicKeyPem = publicKeyPemFromSettldKeysetEntry(row);
+    out.set(kid, { ...row, kid, publicKeyPem });
+  }
+  return out;
+}