settld 0.1.2 → 0.2.0

package/src/core/x402-escalation-override.js

@@ -0,0 +1,258 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const X402_ESCALATION_OVERRIDE_TOKEN_VERSION = 1;
+
+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 assertOptionalId(value, name, { max = 200 } = {}) {
+  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`);
+  if (!/^[A-Za-z0-9:._/-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:._/-]+$`);
+  return out;
+}
+
+function assertOptionalSha256Hex(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be sha256 hex`);
+  return out;
+}
+
+function assertPositiveSafeInt(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 normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value : "USD";
+  const out = raw.trim().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 normalizeOptionalRequestBindingMode(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  const mode = String(value).trim().toLowerCase();
+  if (mode !== "strict") throw new TypeError(`${name} must be strict when provided`);
+  return mode;
+}
+
+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 decodeEnvelope(token) {
+  const raw = assertNonEmptyString(token, "token");
+  let decoded = null;
+  try {
+    decoded = Buffer.from(raw, "base64url").toString("utf8");
+  } catch (err) {
+    throw new TypeError(`token is not valid base64url: ${err?.message ?? String(err ?? "")}`);
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch (err) {
+    throw new TypeError(`token is not valid JSON envelope: ${err?.message ?? String(err ?? "")}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("token envelope must be an object");
+  if (Number(parsed.v) !== X402_ESCALATION_OVERRIDE_TOKEN_VERSION) {
+    throw new TypeError(`token envelope version must be ${X402_ESCALATION_OVERRIDE_TOKEN_VERSION}`);
+  }
+  const kid = assertNonEmptyString(parsed.kid, "token.kid");
+  if (!parsed.payload || typeof parsed.payload !== "object" || Array.isArray(parsed.payload)) {
+    throw new TypeError("token.payload must be an object");
+  }
+  const sig = assertNonEmptyString(parsed.sig, "token.sig");
+  return { envelope: parsed, kid, payload: parsed.payload, sig };
+}
+
+export function buildX402EscalationOverridePayloadV1({
+  overrideId,
+  escalationId,
+  gateId,
+  sponsorRef,
+  sponsorWalletRef,
+  policyRef,
+  policyVersion,
+  policyFingerprint,
+  amountCents,
+  currency = "USD",
+  payeeProviderId,
+  quoteId = null,
+  quoteSha256 = null,
+  requestBindingMode = null,
+  requestBindingSha256 = null,
+  idempotencyKey,
+  nonce,
+  iat,
+  exp
+} = {}) {
+  const normalizedIat = normalizeUnixSeconds(iat, "iat");
+  const normalizedExp = normalizeUnixSeconds(exp, "exp");
+  if (normalizedExp <= normalizedIat) throw new TypeError("exp must be greater than iat");
+  const normalizedRequestBindingSha256 = assertOptionalSha256Hex(requestBindingSha256, "requestBindingSha256");
+  const normalizedRequestBindingMode =
+    normalizeOptionalRequestBindingMode(requestBindingMode, "requestBindingMode") ??
+    (normalizedRequestBindingSha256 ? "strict" : null);
+  if (normalizedRequestBindingMode === "strict" && !normalizedRequestBindingSha256) {
+    throw new TypeError("requestBindingSha256 is required when requestBindingMode=strict");
+  }
+
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: "X402EscalationOverridePayload.v1",
+      overrideId: assertOptionalId(overrideId, "overrideId", { max: 200 }) ?? (() => {
+        throw new TypeError("overrideId is required");
+      })(),
+      escalationId: assertOptionalId(escalationId, "escalationId", { max: 200 }) ?? (() => {
+        throw new TypeError("escalationId is required");
+      })(),
+      gateId: assertOptionalId(gateId, "gateId", { max: 200 }) ?? (() => {
+        throw new TypeError("gateId is required");
+      })(),
+      sponsorRef: assertOptionalId(sponsorRef, "sponsorRef", { max: 200 }) ?? (() => {
+        throw new TypeError("sponsorRef is required");
+      })(),
+      sponsorWalletRef: assertOptionalId(sponsorWalletRef, "sponsorWalletRef", { max: 200 }) ?? (() => {
+        throw new TypeError("sponsorWalletRef is required");
+      })(),
+      policyRef: assertOptionalId(policyRef, "policyRef", { max: 200 }) ?? (() => {
+        throw new TypeError("policyRef is required");
+      })(),
+      policyVersion: assertPositiveSafeInt(policyVersion, "policyVersion"),
+      policyFingerprint: assertOptionalSha256Hex(policyFingerprint, "policyFingerprint") ?? (() => {
+        throw new TypeError("policyFingerprint is required");
+      })(),
+      amountCents: assertPositiveSafeInt(amountCents, "amountCents"),
+      currency: normalizeCurrency(currency, "currency"),
+      payeeProviderId: assertOptionalId(payeeProviderId, "payeeProviderId", { max: 200 }) ?? (() => {
+        throw new TypeError("payeeProviderId is required");
+      })(),
+      ...(assertOptionalId(quoteId, "quoteId", { max: 200 }) ? { quoteId: assertOptionalId(quoteId, "quoteId", { max: 200 }) } : {}),
+      ...(assertOptionalSha256Hex(quoteSha256, "quoteSha256") ? { quoteSha256: assertOptionalSha256Hex(quoteSha256, "quoteSha256") } : {}),
+      ...(normalizedRequestBindingMode ? { requestBindingMode: normalizedRequestBindingMode } : {}),
+      ...(normalizedRequestBindingSha256 ? { requestBindingSha256: normalizedRequestBindingSha256 } : {}),
+      idempotencyKey: assertOptionalId(idempotencyKey, "idempotencyKey", { max: 256 }) ?? (() => {
+        throw new TypeError("idempotencyKey is required");
+      })(),
+      nonce: assertOptionalId(nonce, "nonce", { max: 256 }) ?? (() => {
+        throw new TypeError("nonce is required");
+      })(),
+      iat: normalizedIat,
+      exp: normalizedExp
+    },
+    { path: "$" }
+  );
+}
+
+export function computeX402EscalationOverridePayloadHashV1(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("payload must be an object");
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function mintX402EscalationOverrideTokenV1({ payload, keyId = null, publicKeyPem = null, privateKeyPem } = {}) {
+  const normalizedPayload = buildX402EscalationOverridePayloadV1(payload ?? {});
+  const privatePem = assertNonEmptyString(privateKeyPem, "privateKeyPem");
+  const publicPem = publicKeyPem === null || publicKeyPem === undefined ? null : assertNonEmptyString(publicKeyPem, "publicKeyPem");
+  const derivedKeyId = publicPem ? keyIdFromPublicKeyPem(publicPem) : null;
+  const normalizedKeyId = keyId === null || keyId === undefined || String(keyId).trim() === "" ? derivedKeyId : String(keyId).trim();
+  if (!normalizedKeyId) throw new TypeError("keyId is required (or provide publicKeyPem)");
+  if (derivedKeyId && normalizedKeyId !== derivedKeyId) throw new TypeError("keyId does not match publicKeyPem");
+
+  const payloadHashHex = computeX402EscalationOverridePayloadHashV1(normalizedPayload);
+  const signatureBase64 = signHashHexEd25519(payloadHashHex, privatePem);
+  const envelope = normalizeForCanonicalJson(
+    {
+      v: X402_ESCALATION_OVERRIDE_TOKEN_VERSION,
+      kid: normalizedKeyId,
+      payload: normalizedPayload,
+      sig: Buffer.from(signatureBase64, "base64").toString("base64url")
+    },
+    { path: "$" }
+  );
+  const token = Buffer.from(canonicalJsonStringify(envelope), "utf8").toString("base64url");
+  return {
+    token,
+    envelope,
+    kid: normalizedKeyId,
+    payload: normalizedPayload,
+    payloadHashHex,
+    tokenSha256: sha256Hex(token)
+  };
+}
+
+export function verifyX402EscalationOverrideTokenV1({
+  token,
+  publicKeyPem,
+  nowUnixSeconds = Math.floor(Date.now() / 1000),
+  expected = {}
+} = {}) {
+  try {
+    const { kid, payload, sig } = decodeEnvelope(token);
+    const normalizedPayload = buildX402EscalationOverridePayloadV1(payload);
+    const expectedKeyId = keyIdFromPublicKeyPem(assertNonEmptyString(publicKeyPem, "publicKeyPem"));
+    if (kid !== expectedKeyId) return { ok: false, code: "X402_ESCALATION_OVERRIDE_KEY_MISMATCH", kid };
+    const payloadHashHex = computeX402EscalationOverridePayloadHashV1(normalizedPayload);
+    const signatureBase64 = Buffer.from(sig, "base64url").toString("base64");
+    if (!verifyHashHexEd25519({ hashHex: payloadHashHex, signatureBase64, publicKeyPem })) {
+      return { ok: false, code: "X402_ESCALATION_OVERRIDE_SIGNATURE_INVALID", kid };
+    }
+    if (!Number.isSafeInteger(nowUnixSeconds) || nowUnixSeconds <= 0) {
+      throw new TypeError("nowUnixSeconds must be a positive safe integer");
+    }
+    if (normalizedPayload.exp <= nowUnixSeconds) {
+      return { ok: false, code: "X402_ESCALATION_OVERRIDE_EXPIRED", kid };
+    }
+
+    const expectedFields = [
+      "overrideId",
+      "escalationId",
+      "gateId",
+      "sponsorRef",
+      "sponsorWalletRef",
+      "policyRef",
+      "policyVersion",
+      "policyFingerprint",
+      "amountCents",
+      "currency",
+      "payeeProviderId",
+      "quoteId",
+      "quoteSha256",
+      "requestBindingMode",
+      "requestBindingSha256"
+    ];
+    for (const field of expectedFields) {
+      if (!Object.prototype.hasOwnProperty.call(expected, field)) continue;
+      const expectedValueRaw = expected[field];
+      const expectedValue = expectedValueRaw === null ? null : String(expectedValueRaw);
+      const actualValue = normalizedPayload[field] === undefined || normalizedPayload[field] === null ? null : String(normalizedPayload[field]);
+      if (expectedValue !== actualValue) {
+        return { ok: false, code: "X402_ESCALATION_OVERRIDE_MISMATCH", field, expected: expectedValue, actual: actualValue, kid };
+      }
+    }
+
+    return {
+      ok: true,
+      code: null,
+      kid,
+      payload: normalizedPayload,
+      payloadHashHex,
+      tokenSha256: sha256Hex(assertNonEmptyString(token, "token"))
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "X402_ESCALATION_OVERRIDE_SCHEMA_INVALID",
+      error: err?.message ?? String(err ?? "")
+    };
+  }
+}

package/src/core/x402-gate.js

@@ -0,0 +1,118 @@
+import { normalizeForCanonicalJson } from "./canonical-json.js";
+
+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 normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value : "USD";
+  const out = raw.trim().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 normalizeNonNegativeSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+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 parseKeyValueHeader(text) {
+  const out = {};
+  for (const part of String(text ?? "")
+    .split(";")
+    .map((s) => s.trim())
+    .filter(Boolean)) {
+    const idx = part.indexOf("=");
+    if (idx < 0) continue;
+    const k = part.slice(0, idx).trim();
+    const v = part.slice(idx + 1).trim();
+    if (!k) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+export function buildX402SettlementTerms({
+  amountCents,
+  currency = "USD",
+  disputeWindowDays = 0,
+  disputeWindowMs = null,
+  holdbackBps = 0,
+  evidenceRequirements = null,
+  slaPolicy = null
+} = {}) {
+  const normalizedDisputeWindowMs =
+    disputeWindowMs === null || disputeWindowMs === undefined ? null : normalizeNonNegativeSafeInt(disputeWindowMs, "disputeWindowMs");
+  const normalizedDisputeWindowDays =
+    normalizedDisputeWindowMs !== null ? Math.ceil(normalizedDisputeWindowMs / 86_400_000) : normalizeNonNegativeSafeInt(disputeWindowDays, "disputeWindowDays");
+  const normalizedHoldbackBps = normalizeNonNegativeSafeInt(holdbackBps, "holdbackBps");
+  if (normalizedHoldbackBps > 10_000) throw new TypeError("holdbackBps must be within 0..10000");
+  const terms = {
+    amountCents: normalizePositiveSafeInt(amountCents, "amountCents"),
+    currency: normalizeCurrency(currency, "currency"),
+    disputeWindowDays: normalizedDisputeWindowDays,
+    disputeWindowMs: normalizedDisputeWindowMs,
+    holdbackBps: normalizedHoldbackBps,
+    evidenceRequirements: evidenceRequirements && typeof evidenceRequirements === "object" ? evidenceRequirements : null,
+    slaPolicy: slaPolicy && typeof slaPolicy === "object" ? slaPolicy : null
+  };
+  return normalizeForCanonicalJson(terms, { path: "$" });
+}
+
+// Best-effort parsing of upstream x402-style 402 metadata.
+// This does not attempt to be the x402 spec; it normalizes common "key=value; ..." or JSON payloads.
+export function parseX402PaymentRequired(response402Headers) {
+  if (response402Headers === null || response402Headers === undefined) return { ok: false, error: "missing headers" };
+
+  const headerValue = (() => {
+    if (typeof response402Headers === "string") return response402Headers;
+    if (response402Headers && typeof response402Headers === "object") {
+      const raw =
+        response402Headers["x-payment-required"] ??
+        response402Headers["X-Payment-Required"] ??
+        response402Headers["payment-required"] ??
+        response402Headers["Payment-Required"] ??
+        null;
+      return raw === null || raw === undefined ? "" : String(Array.isArray(raw) ? raw[0] : raw);
+    }
+    return "";
+  })();
+
+  const text = String(headerValue ?? "").trim();
+  if (!text) return { ok: false, error: "missing x-payment-required" };
+
+  // JSON payload case.
+  if (text.startsWith("{") && text.endsWith("}")) {
+    try {
+      const parsed = JSON.parse(text);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { ok: false, error: "invalid json header" };
+      return { ok: true, raw: text, fields: normalizeForCanonicalJson(parsed, { path: "$" }) };
+    } catch (err) {
+      return { ok: false, error: "invalid json header", message: err?.message ?? String(err ?? "") };
+    }
+  }
+
+  const fields = parseKeyValueHeader(text);
+  return { ok: true, raw: text, fields: normalizeForCanonicalJson(fields, { path: "$" }) };
+}
+
+// Placeholder: the "gate" middleware wiring is environment-specific (proxy framework, upstream fetch, etc.).
+// Keep it as an explicit adapter surface rather than baking a single HTTP stack into the kernel.
+export function createX402GateMiddleware() {
+  throw new Error("createX402GateMiddleware is not implemented in this repo (use API endpoints or build an adapter)");
+}

package/src/core/x402-provider-refund-decision.js

@@ -0,0 +1,220 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const X402_PROVIDER_REFUND_DECISION_PAYLOAD_SCHEMA_VERSION = "X402ProviderRefundDecisionPayload.v1";
+export const X402_PROVIDER_REFUND_DECISION_SCHEMA_VERSION = "X402ProviderRefundDecision.v1";
+export const X402_PROVIDER_REFUND_DECISION_SIGNATURE_SCHEMA_VERSION = "X402ProviderRefundDecisionSignature.v1";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+  return value.trim();
+}
+
+function assertPemString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty PEM string`);
+  return value;
+}
+
+function assertOptionalString(value, name, { max = 1000 } = {}) {
+  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 assertOptionalId(value, name, { max = 200 } = {}) {
+  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`);
+  if (!/^[A-Za-z0-9:._/-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:._/-]+$`);
+  return out;
+}
+
+function assertIsoDateTime(value, name) {
+  const out = assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(out))) throw new TypeError(`${name} must be an ISO date-time`);
+  return new Date(out).toISOString();
+}
+
+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 assertOptionalSha256Hex(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  return assertSha256Hex(value, name);
+}
+
+function assertDecision(value, name = "decision") {
+  const out = assertNonEmptyString(value, name).toLowerCase();
+  if (out !== "accepted" && out !== "denied") throw new TypeError(`${name} must be accepted|denied`);
+  return out;
+}
+
+export function buildX402ProviderRefundDecisionPayloadV1({
+  decisionId = null,
+  receiptId,
+  gateId,
+  quoteId = null,
+  requestSha256 = null,
+  decision,
+  reason = null,
+  decidedAt
+} = {}) {
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: X402_PROVIDER_REFUND_DECISION_PAYLOAD_SCHEMA_VERSION,
+      ...(assertOptionalId(decisionId, "decisionId", { max: 200 }) ? { decisionId: assertOptionalId(decisionId, "decisionId", { max: 200 }) } : {}),
+      receiptId: assertOptionalId(receiptId, "receiptId", { max: 200 }) ?? (() => {
+        throw new TypeError("receiptId is required");
+      })(),
+      gateId: assertOptionalId(gateId, "gateId", { max: 200 }) ?? (() => {
+        throw new TypeError("gateId is required");
+      })(),
+      ...(assertOptionalId(quoteId, "quoteId", { max: 200 }) ? { quoteId: assertOptionalId(quoteId, "quoteId", { max: 200 }) } : {}),
+      ...(assertOptionalSha256Hex(requestSha256, "requestSha256") ? { requestSha256: assertOptionalSha256Hex(requestSha256, "requestSha256") } : {}),
+      decision: assertDecision(decision, "decision"),
+      ...(assertOptionalString(reason, "reason", { max: 1000 }) ? { reason: assertOptionalString(reason, "reason", { max: 1000 }) } : {}),
+      decidedAt: assertIsoDateTime(decidedAt, "decidedAt")
+    },
+    { path: "$" }
+  );
+}
+
+export function computeX402ProviderRefundDecisionPayloadHashV1({ payload } = {}) {
+  const normalizedPayload = buildX402ProviderRefundDecisionPayloadV1(payload ?? {});
+  return sha256Hex(canonicalJsonStringify(normalizedPayload));
+}
+
+function normalizeDecisionEnvelope(decision) {
+  if (!decision || typeof decision !== "object" || Array.isArray(decision)) throw new TypeError("decision must be an object");
+  const payload = buildX402ProviderRefundDecisionPayloadV1(decision);
+  const signature = decision.signature;
+  if (!signature || typeof signature !== "object" || Array.isArray(signature)) throw new TypeError("decision.signature must be an object");
+  if (String(signature.schemaVersion ?? "") !== X402_PROVIDER_REFUND_DECISION_SIGNATURE_SCHEMA_VERSION) {
+    throw new TypeError(`decision.signature.schemaVersion must be ${X402_PROVIDER_REFUND_DECISION_SIGNATURE_SCHEMA_VERSION}`);
+  }
+  if (String(signature.algorithm ?? "").toLowerCase() !== "ed25519") throw new TypeError("decision.signature.algorithm must be ed25519");
+  return {
+    schemaVersion: decision.schemaVersion ?? X402_PROVIDER_REFUND_DECISION_SCHEMA_VERSION,
+    payload,
+    signature: normalizeForCanonicalJson(
+      {
+        schemaVersion: X402_PROVIDER_REFUND_DECISION_SIGNATURE_SCHEMA_VERSION,
+        algorithm: "ed25519",
+        keyId: assertNonEmptyString(signature.keyId, "decision.signature.keyId"),
+        signedAt: assertIsoDateTime(signature.signedAt, "decision.signature.signedAt"),
+        payloadHash: assertSha256Hex(signature.payloadHash, "decision.signature.payloadHash"),
+        signatureBase64: assertNonEmptyString(signature.signatureBase64, "decision.signature.signatureBase64")
+      },
+      { path: "$" }
+    )
+  };
+}
+
+export function signX402ProviderRefundDecisionV1({ decision, signedAt, publicKeyPem, privateKeyPem } = {}) {
+  const payload = buildX402ProviderRefundDecisionPayloadV1(decision ?? {});
+  const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+  const signerPrivateKeyPem = assertPemString(privateKeyPem, "privateKeyPem");
+  const payloadHash = computeX402ProviderRefundDecisionPayloadHashV1({ payload });
+  const signatureBase64 = signHashHexEd25519(payloadHash, signerPrivateKeyPem);
+  const payloadFields = { ...payload };
+  delete payloadFields.schemaVersion;
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: X402_PROVIDER_REFUND_DECISION_SCHEMA_VERSION,
+      ...payloadFields,
+      signature: {
+        schemaVersion: X402_PROVIDER_REFUND_DECISION_SIGNATURE_SCHEMA_VERSION,
+        algorithm: "ed25519",
+        keyId: keyIdFromPublicKeyPem(signerPublicKeyPem),
+        signedAt: assertIsoDateTime(signedAt, "signedAt"),
+        payloadHash,
+        signatureBase64
+      }
+    },
+    { path: "$" }
+  );
+}
+
+export function verifyX402ProviderRefundDecisionV1({
+  decision,
+  publicKeyPem,
+  expectedReceiptId = null,
+  expectedGateId = null,
+  expectedQuoteId = null,
+  expectedRequestSha256 = null,
+  expectedDecision = null
+} = {}) {
+  try {
+    const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+    const normalized = normalizeDecisionEnvelope(decision);
+    if (String(normalized.schemaVersion ?? "") !== X402_PROVIDER_REFUND_DECISION_SCHEMA_VERSION) {
+      return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_SCHEMA_INVALID", error: "invalid schemaVersion" };
+    }
+    const expectedKeyId = keyIdFromPublicKeyPem(signerPublicKeyPem);
+    if (normalized.signature.keyId !== expectedKeyId) {
+      return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_KEY_ID_MISMATCH", error: "signature keyId mismatch" };
+    }
+    const payloadHash = computeX402ProviderRefundDecisionPayloadHashV1({ payload: normalized.payload });
+    if (normalized.signature.payloadHash !== payloadHash) {
+      return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_PAYLOAD_HASH_MISMATCH", error: "payload hash mismatch" };
+    }
+    const signatureValid = verifyHashHexEd25519({
+      hashHex: payloadHash,
+      signatureBase64: normalized.signature.signatureBase64,
+      publicKeyPem: signerPublicKeyPem
+    });
+    if (!signatureValid) {
+      return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_SIGNATURE_INVALID", error: "signature invalid" };
+    }
+
+    if (expectedReceiptId !== null) {
+      const expected = assertOptionalId(expectedReceiptId, "expectedReceiptId", { max: 200 });
+      if (expected !== normalized.payload.receiptId) {
+        return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_RECEIPT_MISMATCH", error: "receiptId mismatch" };
+      }
+    }
+    if (expectedGateId !== null) {
+      const expected = assertOptionalId(expectedGateId, "expectedGateId", { max: 200 });
+      if (expected !== normalized.payload.gateId) {
+        return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_GATE_MISMATCH", error: "gateId mismatch" };
+      }
+    }
+    if (expectedQuoteId !== null) {
+      const expected = assertOptionalId(expectedQuoteId, "expectedQuoteId", { max: 200 });
+      if (expected !== normalized.payload.quoteId) {
+        return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_QUOTE_MISMATCH", error: "quoteId mismatch" };
+      }
+    }
+    if (expectedRequestSha256 !== null) {
+      const expected = assertOptionalSha256Hex(expectedRequestSha256, "expectedRequestSha256");
+      if (expected !== normalized.payload.requestSha256) {
+        return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_REQUEST_HASH_MISMATCH", error: "requestSha256 mismatch" };
+      }
+    }
+    if (expectedDecision !== null) {
+      const expected = assertDecision(expectedDecision, "expectedDecision");
+      if (expected !== normalized.payload.decision) {
+        return { ok: false, code: "X402_PROVIDER_REFUND_DECISION_VALUE_MISMATCH", error: "decision mismatch" };
+      }
+    }
+
+    return {
+      ok: true,
+      code: null,
+      error: null,
+      payload: normalized.payload,
+      payloadHash,
+      keyId: normalized.signature.keyId
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "X402_PROVIDER_REFUND_DECISION_SCHEMA_INVALID",
+      error: err?.message ?? String(err ?? "")
+    };
+  }
+}