settld 0.1.1 → 0.1.5

package/src/core/settld-pay-token.js

@@ -0,0 +1,344 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+import { keyMapFromSettldKeyset } from "./settld-keys.js";
+
+export const SETTLD_PAY_TOKEN_VERSION = 1;
+export const SETTLD_PAY_TOKEN_TTL_SECONDS = 300;
+
+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 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 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 normalizeHexHash(value, name) {
+  const s = assertNonEmptyString(value, name).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(s)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return s;
+}
+
+function normalizeOptionalHexHash(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  return normalizeHexHash(value, name);
+}
+
+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 normalizeOptionalId(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 normalizeOptionalString(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 normalizeOptionalPositiveSafeInt(value, name) {
+  if (value === null || value === undefined || String(value).trim() === "") return null;
+  return normalizePositiveSafeInt(value, name);
+}
+
+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;
+  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) !== SETTLD_PAY_TOKEN_VERSION) throw new TypeError(`token envelope version must be ${SETTLD_PAY_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 buildSettldPayPayloadV1({
+  iss = "settld",
+  aud,
+  gateId,
+  authorizationRef,
+  amountCents,
+  currency = "USD",
+  payeeProviderId,
+  requestBindingMode = null,
+  requestBindingSha256 = null,
+  quoteId = null,
+  quoteSha256 = null,
+  idempotencyKey = null,
+  nonce = null,
+  sponsorRef = null,
+  sponsorWalletRef = null,
+  agentKeyId = null,
+  delegationRef = null,
+  rootDelegationRef = null,
+  rootDelegationHash = null,
+  effectiveDelegationRef = null,
+  effectiveDelegationHash = null,
+  policyVersion = null,
+  policyFingerprint = null,
+  spendAuthorizationVersion = null,
+  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 = normalizeOptionalHexHash(requestBindingSha256, "requestBindingSha256");
+  const normalizedRequestBindingMode =
+    normalizeOptionalRequestBindingMode(requestBindingMode, "requestBindingMode") ??
+    (normalizedRequestBindingSha256 ? "strict" : null);
+  if (normalizedRequestBindingMode === "strict" && !normalizedRequestBindingSha256) {
+    throw new TypeError("requestBindingSha256 is required when requestBindingMode=strict");
+  }
+  const normalizedQuoteId = normalizeOptionalId(quoteId, "quoteId", { max: 200 });
+  const normalizedQuoteSha256 = normalizeOptionalHexHash(quoteSha256, "quoteSha256");
+  const normalizedIdempotencyKey = normalizeOptionalString(idempotencyKey, "idempotencyKey", { max: 256 });
+  const normalizedNonce = normalizeOptionalString(nonce, "nonce", { max: 256 });
+  const normalizedSponsorRef = normalizeOptionalId(sponsorRef, "sponsorRef", { max: 200 });
+  const normalizedSponsorWalletRef = normalizeOptionalId(sponsorWalletRef, "sponsorWalletRef", { max: 200 });
+  const normalizedAgentKeyId = normalizeOptionalId(agentKeyId, "agentKeyId", { max: 200 });
+  const normalizedDelegationRef = normalizeOptionalId(delegationRef, "delegationRef", { max: 200 });
+  const normalizedRootDelegationRef = normalizeOptionalId(rootDelegationRef, "rootDelegationRef", { max: 200 });
+  const normalizedRootDelegationHash = normalizeOptionalHexHash(rootDelegationHash, "rootDelegationHash");
+  const normalizedEffectiveDelegationRef = normalizeOptionalId(effectiveDelegationRef, "effectiveDelegationRef", { max: 200 });
+  const normalizedEffectiveDelegationHash = normalizeOptionalHexHash(effectiveDelegationHash, "effectiveDelegationHash");
+  const normalizedPolicyVersion = normalizeOptionalPositiveSafeInt(policyVersion, "policyVersion");
+  const normalizedPolicyFingerprint = normalizeOptionalHexHash(policyFingerprint, "policyFingerprint");
+  const normalizedSpendAuthorizationVersion = normalizeOptionalString(spendAuthorizationVersion, "spendAuthorizationVersion", {
+    max: 64
+  });
+  const hasSpendAuthorizationClaims =
+    normalizedQuoteId !== null ||
+    normalizedQuoteSha256 !== null ||
+    normalizedIdempotencyKey !== null ||
+    normalizedNonce !== null ||
+    normalizedSponsorRef !== null ||
+    normalizedSponsorWalletRef !== null ||
+    normalizedAgentKeyId !== null ||
+    normalizedDelegationRef !== null ||
+    normalizedRootDelegationRef !== null ||
+    normalizedRootDelegationHash !== null ||
+    normalizedEffectiveDelegationRef !== null ||
+    normalizedEffectiveDelegationHash !== null ||
+    normalizedPolicyVersion !== null ||
+    normalizedPolicyFingerprint !== null ||
+    normalizedSpendAuthorizationVersion !== null;
+  const spendAuthorizationVersionOut = hasSpendAuthorizationClaims
+    ? normalizedSpendAuthorizationVersion ?? "SpendAuthorization.v1"
+    : null;
+
+  return normalizeForCanonicalJson(
+    {
+      iss: assertNonEmptyString(iss, "iss"),
+      aud: assertNonEmptyString(aud, "aud"),
+      gateId: assertNonEmptyString(gateId, "gateId"),
+      authorizationRef: assertNonEmptyString(authorizationRef, "authorizationRef"),
+      amountCents: normalizePositiveSafeInt(amountCents, "amountCents"),
+      currency: normalizeCurrency(currency, "currency"),
+      payeeProviderId: assertNonEmptyString(payeeProviderId, "payeeProviderId"),
+      ...(normalizedRequestBindingMode ? { requestBindingMode: normalizedRequestBindingMode } : {}),
+      ...(normalizedRequestBindingSha256 ? { requestBindingSha256: normalizedRequestBindingSha256 } : {}),
+      ...(normalizedQuoteId ? { quoteId: normalizedQuoteId } : {}),
+      ...(normalizedQuoteSha256 ? { quoteSha256: normalizedQuoteSha256 } : {}),
+      ...(normalizedIdempotencyKey ? { idempotencyKey: normalizedIdempotencyKey } : {}),
+      ...(normalizedNonce ? { nonce: normalizedNonce } : {}),
+      ...(normalizedSponsorRef ? { sponsorRef: normalizedSponsorRef } : {}),
+      ...(normalizedSponsorWalletRef ? { sponsorWalletRef: normalizedSponsorWalletRef } : {}),
+      ...(normalizedAgentKeyId ? { agentKeyId: normalizedAgentKeyId } : {}),
+      ...(normalizedDelegationRef ? { delegationRef: normalizedDelegationRef } : {}),
+      ...(normalizedRootDelegationRef ? { rootDelegationRef: normalizedRootDelegationRef } : {}),
+      ...(normalizedRootDelegationHash ? { rootDelegationHash: normalizedRootDelegationHash } : {}),
+      ...(normalizedEffectiveDelegationRef ? { effectiveDelegationRef: normalizedEffectiveDelegationRef } : {}),
+      ...(normalizedEffectiveDelegationHash ? { effectiveDelegationHash: normalizedEffectiveDelegationHash } : {}),
+      ...(normalizedPolicyVersion ? { policyVersion: normalizedPolicyVersion } : {}),
+      ...(normalizedPolicyFingerprint ? { policyFingerprint: normalizedPolicyFingerprint } : {}),
+      ...(spendAuthorizationVersionOut ? { spendAuthorizationVersion: spendAuthorizationVersionOut } : {}),
+      iat: normalizedIat,
+      exp: normalizedExp
+    },
+    { path: "$" }
+  );
+}
+
+export function computeSettldPayRequestBindingSha256V1({ method, host, pathWithQuery, bodySha256 } = {}) {
+  const normalizedMethod = assertNonEmptyString(method, "method").toUpperCase();
+  const normalizedHost = assertNonEmptyString(host, "host").toLowerCase();
+  const normalizedPathWithQuery = assertNonEmptyString(pathWithQuery, "pathWithQuery");
+  if (!normalizedPathWithQuery.startsWith("/")) {
+    throw new TypeError("pathWithQuery must start with /");
+  }
+  const normalizedBodySha256 = normalizeHexHash(bodySha256, "bodySha256");
+  return sha256Hex(`${normalizedMethod}\n${normalizedHost}\n${normalizedPathWithQuery}\n${normalizedBodySha256}`);
+}
+
+export function computeSettldPayPayloadHashV1(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("payload must be an object");
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function computeSettldPayTokenSha256(token) {
+  return sha256Hex(assertNonEmptyString(token, "token"));
+}
+
+export function mintSettldPayTokenV1({ payload, keyId = null, publicKeyPem = null, privateKeyPem } = {}) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("payload must be an object");
+  const normalizedPayload = normalizeForCanonicalJson(payload, { path: "$" });
+  const privatePem = assertNonEmptyString(privateKeyPem, "privateKeyPem");
+  const publicPem = (() => {
+    if (publicKeyPem === null || publicKeyPem === undefined) return null;
+    if (typeof publicKeyPem !== "string" || publicKeyPem.trim() === "") throw new TypeError("publicKeyPem must be a non-empty string");
+    return 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 = computeSettldPayPayloadHashV1(normalizedPayload);
+  const signatureBase64 = signHashHexEd25519(payloadHashHex, privatePem);
+  const envelope = normalizeForCanonicalJson(
+    {
+      v: SETTLD_PAY_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,
+    payloadHashHex,
+    tokenSha256: computeSettldPayTokenSha256(token)
+  };
+}
+
+export function parseSettldPayTokenV1(token) {
+  const { envelope, kid, payload, sig } = decodeEnvelope(token);
+  return { envelope, kid, payload, sig };
+}
+
+export function verifySettldPayTokenV1({
+  token,
+  keyset,
+  nowUnixSeconds = Math.floor(Date.now() / 1000),
+  expectedAudience = null,
+  expectedPayeeProviderId = null,
+  expectedRequestBindingSha256 = null
+} = {}) {
+  const { envelope, kid, payload, sig } = decodeEnvelope(token);
+  const keyMap = keyMapFromSettldKeyset(keyset);
+  const keyEntry = keyMap.get(kid) ?? null;
+  if (!keyEntry?.publicKeyPem) return { ok: false, code: "SETTLD_PAY_UNKNOWN_KID", kid };
+
+  const payloadHashHex = computeSettldPayPayloadHashV1(payload);
+  const signatureBase64 = (() => {
+    try {
+      return Buffer.from(sig, "base64url").toString("base64");
+    } catch {
+      return null;
+    }
+  })();
+  if (!signatureBase64) return { ok: false, code: "SETTLD_PAY_SIGNATURE_INVALID", kid };
+
+  let signatureValid = false;
+  try {
+    signatureValid = verifyHashHexEd25519({ hashHex: payloadHashHex, signatureBase64, publicKeyPem: keyEntry.publicKeyPem });
+  } catch {
+    signatureValid = false;
+  }
+  if (!signatureValid) return { ok: false, code: "SETTLD_PAY_SIGNATURE_INVALID", kid };
+
+  let normalizedPayload;
+  try {
+    normalizedPayload = buildSettldPayPayloadV1(payload);
+  } catch (err) {
+    return { ok: false, code: "SETTLD_PAY_PAYLOAD_INVALID", kid, message: err?.message ?? String(err ?? "") };
+  }
+
+  const nowSec = normalizeUnixSeconds(nowUnixSeconds, "nowUnixSeconds");
+  if (nowSec > Number(normalizedPayload.exp)) return { ok: false, code: "SETTLD_PAY_EXPIRED", kid, payload: normalizedPayload };
+  if (expectedAudience !== null && expectedAudience !== undefined && String(expectedAudience) !== String(normalizedPayload.aud)) {
+    return { ok: false, code: "SETTLD_PAY_AUDIENCE_MISMATCH", kid, payload: normalizedPayload };
+  }
+  if (
+    expectedPayeeProviderId !== null &&
+    expectedPayeeProviderId !== undefined &&
+    String(expectedPayeeProviderId) !== String(normalizedPayload.payeeProviderId)
+  ) {
+    return { ok: false, code: "SETTLD_PAY_PAYEE_MISMATCH", kid, payload: normalizedPayload };
+  }
+
+  const expectedRequestBinding =
+    expectedRequestBindingSha256 === null || expectedRequestBindingSha256 === undefined || String(expectedRequestBindingSha256).trim() === ""
+      ? null
+      : normalizeHexHash(expectedRequestBindingSha256, "expectedRequestBindingSha256");
+  const payloadRequestBindingMode =
+    typeof normalizedPayload.requestBindingMode === "string" ? String(normalizedPayload.requestBindingMode).trim().toLowerCase() : null;
+  const payloadRequestBindingSha256 =
+    typeof normalizedPayload.requestBindingSha256 === "string" ? String(normalizedPayload.requestBindingSha256).trim().toLowerCase() : null;
+  if (payloadRequestBindingMode === "strict") {
+    if (!payloadRequestBindingSha256 || !/^[0-9a-f]{64}$/.test(payloadRequestBindingSha256)) {
+      return { ok: false, code: "SETTLD_PAY_REQUEST_BINDING_MISSING", kid, payload: normalizedPayload };
+    }
+    if (!expectedRequestBinding) {
+      return { ok: false, code: "SETTLD_PAY_REQUEST_BINDING_REQUIRED", kid, payload: normalizedPayload };
+    }
+    if (payloadRequestBindingSha256 !== expectedRequestBinding) {
+      return { ok: false, code: "SETTLD_PAY_REQUEST_BINDING_MISMATCH", kid, payload: normalizedPayload };
+    }
+  } else if (expectedRequestBinding && payloadRequestBindingSha256 && payloadRequestBindingSha256 !== expectedRequestBinding) {
+    return { ok: false, code: "SETTLD_PAY_REQUEST_BINDING_MISMATCH", kid, payload: normalizedPayload };
+  }
+
+  return {
+    ok: true,
+    kid,
+    payload: normalizedPayload,
+    envelope,
+    payloadHashHex: normalizeHexHash(payloadHashHex, "payloadHashHex"),
+    tokenSha256: computeSettldPayTokenSha256(token),
+    key: keyEntry
+  };
+}

package/src/core/settlement-kernel.js

@@ -84,6 +84,213 @@ function normalizeHexHash(value, name, { allowNull = false } = {}) {
   return out;
 }
 
+function normalizeNullableString(value, name, { max = 256 } = {}) {
+  if (value === null || value === undefined) return null;
+  const out = String(value);
+  if (out.length > max) throw new TypeError(`${name} must be <= ${max} chars`);
+  return out;
+}
+
+function normalizeNullableBoolean(value, name) {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "boolean") throw new TypeError(`${name} must be boolean`);
+  return value;
+}
+
+function normalizeNullableHttpStatus(value, name) {
+  if (value === null || value === undefined) return null;
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 100 || n > 999) throw new TypeError(`${name} must be a 3-digit integer status code`);
+  return n;
+}
+
+function normalizeNullableSafeInt(value, name, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value === null || value === undefined) return null;
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < min || n > max) {
+    throw new TypeError(`${name} must be an integer in range ${min}..${max}`);
+  }
+  return n;
+}
+
+function normalizeSettlementBindings(value, name, { allowNull = true } = {}) {
+  if (value === null || value === undefined) {
+    if (allowNull) return null;
+    throw new TypeError(`${name} is required`);
+  }
+  assertPlainObject(value, name);
+  return normalizeForCanonicalJson(
+    {
+      authorizationRef: normalizeNullableString(value.authorizationRef, `${name}.authorizationRef`, { max: 200 }),
+      token: value.token
+        ? {
+            kid: normalizeNullableString(value.token.kid, `${name}.token.kid`, { max: 200 }),
+            sha256: normalizeHexHash(value.token.sha256, `${name}.token.sha256`, { allowNull: true }),
+            expiresAt: value.token.expiresAt === null || value.token.expiresAt === undefined ? null : String(value.token.expiresAt)
+          }
+        : null,
+      request: value.request
+        ? {
+            sha256: normalizeHexHash(value.request.sha256, `${name}.request.sha256`, { allowNull: true })
+          }
+        : null,
+      response: value.response
+        ? {
+            status: normalizeNullableHttpStatus(value.response.status, `${name}.response.status`),
+            sha256: normalizeHexHash(value.response.sha256, `${name}.response.sha256`, { allowNull: true })
+          }
+        : null,
+      providerSig: value.providerSig
+        ? {
+            required: normalizeNullableBoolean(value.providerSig.required, `${name}.providerSig.required`),
+            present: normalizeNullableBoolean(value.providerSig.present, `${name}.providerSig.present`),
+            verified: normalizeNullableBoolean(value.providerSig.verified, `${name}.providerSig.verified`),
+            providerKeyId: normalizeNullableString(value.providerSig.providerKeyId, `${name}.providerSig.providerKeyId`, { max: 200 }),
+            keyJwkThumbprintSha256: normalizeHexHash(value.providerSig.keyJwkThumbprintSha256, `${name}.providerSig.keyJwkThumbprintSha256`, {
+              allowNull: true
+            }),
+            error: normalizeNullableString(value.providerSig.error, `${name}.providerSig.error`, { max: 4000 })
+          }
+        : null,
+      providerQuoteSig: value.providerQuoteSig
+        ? {
+            required: normalizeNullableBoolean(value.providerQuoteSig.required, `${name}.providerQuoteSig.required`),
+            present: normalizeNullableBoolean(value.providerQuoteSig.present, `${name}.providerQuoteSig.present`),
+            verified: normalizeNullableBoolean(value.providerQuoteSig.verified, `${name}.providerQuoteSig.verified`),
+            providerKeyId: normalizeNullableString(value.providerQuoteSig.providerKeyId, `${name}.providerQuoteSig.providerKeyId`, {
+              max: 200
+            }),
+            quoteId: normalizeNullableString(value.providerQuoteSig.quoteId, `${name}.providerQuoteSig.quoteId`, { max: 200 }),
+            quoteSha256: normalizeHexHash(value.providerQuoteSig.quoteSha256, `${name}.providerQuoteSig.quoteSha256`, { allowNull: true }),
+            keyJwkThumbprintSha256: normalizeHexHash(
+              value.providerQuoteSig.keyJwkThumbprintSha256,
+              `${name}.providerQuoteSig.keyJwkThumbprintSha256`,
+              { allowNull: true }
+            ),
+            error: normalizeNullableString(value.providerQuoteSig.error, `${name}.providerQuoteSig.error`, { max: 4000 })
+          }
+        : null,
+      reserve: value.reserve
+        ? {
+            adapter: normalizeNullableString(value.reserve.adapter, `${name}.reserve.adapter`, { max: 200 }),
+            mode: normalizeNullableString(value.reserve.mode, `${name}.reserve.mode`, { max: 200 }),
+            reserveId: normalizeNullableString(value.reserve.reserveId, `${name}.reserve.reserveId`, { max: 256 }),
+            status: normalizeNullableString(value.reserve.status, `${name}.reserve.status`, { max: 64 })
+          }
+        : null,
+      quote: value.quote
+        ? {
+            quoteId: normalizeNullableString(value.quote.quoteId, `${name}.quote.quoteId`, { max: 200 }),
+            quoteSha256: normalizeHexHash(value.quote.quoteSha256, `${name}.quote.quoteSha256`, { allowNull: true }),
+            expiresAt: value.quote.expiresAt === null || value.quote.expiresAt === undefined ? null : String(value.quote.expiresAt),
+            requestBindingMode: normalizeNullableString(value.quote.requestBindingMode, `${name}.quote.requestBindingMode`, {
+              max: 32
+            }),
+            requestBindingSha256: normalizeHexHash(value.quote.requestBindingSha256, `${name}.quote.requestBindingSha256`, {
+              allowNull: true
+            })
+          }
+        : null,
+      spendAuthorization: value.spendAuthorization
+        ? {
+            spendAuthorizationVersion: normalizeNullableString(
+              value.spendAuthorization.spendAuthorizationVersion,
+              `${name}.spendAuthorization.spendAuthorizationVersion`,
+              { max: 64 }
+            ),
+            idempotencyKey: normalizeNullableString(value.spendAuthorization.idempotencyKey, `${name}.spendAuthorization.idempotencyKey`, {
+              max: 256
+            }),
+            nonce: normalizeNullableString(value.spendAuthorization.nonce, `${name}.spendAuthorization.nonce`, { max: 256 }),
+            sponsorRef: normalizeNullableString(value.spendAuthorization.sponsorRef, `${name}.spendAuthorization.sponsorRef`, { max: 200 }),
+            sponsorWalletRef: normalizeNullableString(value.spendAuthorization.sponsorWalletRef, `${name}.spendAuthorization.sponsorWalletRef`, {
+              max: 200
+            }),
+            agentKeyId: normalizeNullableString(value.spendAuthorization.agentKeyId, `${name}.spendAuthorization.agentKeyId`, { max: 200 }),
+            delegationRef: normalizeNullableString(value.spendAuthorization.delegationRef, `${name}.spendAuthorization.delegationRef`, { max: 200 }),
+            rootDelegationRef: normalizeNullableString(value.spendAuthorization.rootDelegationRef, `${name}.spendAuthorization.rootDelegationRef`, {
+              max: 200
+            }),
+            rootDelegationHash: normalizeHexHash(value.spendAuthorization.rootDelegationHash, `${name}.spendAuthorization.rootDelegationHash`, {
+              allowNull: true
+            }),
+            effectiveDelegationRef: normalizeNullableString(
+              value.spendAuthorization.effectiveDelegationRef,
+              `${name}.spendAuthorization.effectiveDelegationRef`,
+              { max: 200 }
+            ),
+            effectiveDelegationHash: normalizeHexHash(
+              value.spendAuthorization.effectiveDelegationHash,
+              `${name}.spendAuthorization.effectiveDelegationHash`,
+              { allowNull: true }
+            ),
+            policyVersion: normalizeNullableSafeInt(value.spendAuthorization.policyVersion, `${name}.spendAuthorization.policyVersion`, {
+              min: 1,
+              max: 1_000_000_000
+            }),
+            policyFingerprint: normalizeHexHash(value.spendAuthorization.policyFingerprint, `${name}.spendAuthorization.policyFingerprint`, {
+              allowNull: true
+            })
+          }
+        : null,
+      executionIntent: value.executionIntent
+        ? {
+            schemaVersion: normalizeNullableString(value.executionIntent.schemaVersion, `${name}.executionIntent.schemaVersion`, { max: 64 }),
+            intentId: normalizeNullableString(value.executionIntent.intentId, `${name}.executionIntent.intentId`, { max: 200 }),
+            intentHash: normalizeHexHash(value.executionIntent.intentHash, `${name}.executionIntent.intentHash`, { allowNull: true }),
+            idempotencyKey: normalizeNullableString(value.executionIntent.idempotencyKey, `${name}.executionIntent.idempotencyKey`, {
+              max: 256
+            }),
+            nonce: normalizeNullableString(value.executionIntent.nonce, `${name}.executionIntent.nonce`, { max: 256 }),
+            expiresAt:
+              value.executionIntent.expiresAt === null || value.executionIntent.expiresAt === undefined
+                ? null
+                : String(value.executionIntent.expiresAt),
+            requestSha256: normalizeHexHash(value.executionIntent.requestSha256, `${name}.executionIntent.requestSha256`, {
+              allowNull: true
+            }),
+            policyHash: normalizeHexHash(value.executionIntent.policyHash, `${name}.executionIntent.policyHash`, { allowNull: true }),
+            verificationMethodHash: normalizeHexHash(
+              value.executionIntent.verificationMethodHash,
+              `${name}.executionIntent.verificationMethodHash`,
+              { allowNull: true }
+            )
+          }
+        : null,
+      policyDecisionFingerprint: value.policyDecisionFingerprint
+        ? {
+            fingerprintVersion: normalizeNullableString(
+              value.policyDecisionFingerprint.fingerprintVersion,
+              `${name}.policyDecisionFingerprint.fingerprintVersion`,
+              { max: 64 }
+            ),
+            policyId: normalizeNullableString(value.policyDecisionFingerprint.policyId, `${name}.policyDecisionFingerprint.policyId`, {
+              max: 200
+            }),
+            policyVersion: normalizeNullableSafeInt(value.policyDecisionFingerprint.policyVersion, `${name}.policyDecisionFingerprint.policyVersion`, {
+              min: 1,
+              max: 1_000_000_000
+            }),
+            policyHash: normalizeHexHash(value.policyDecisionFingerprint.policyHash, `${name}.policyDecisionFingerprint.policyHash`, {
+              allowNull: true
+            }),
+            verificationMethodHash: normalizeHexHash(
+              value.policyDecisionFingerprint.verificationMethodHash,
+              `${name}.policyDecisionFingerprint.verificationMethodHash`,
+              { allowNull: true }
+            ),
+            evaluationHash: normalizeHexHash(
+              value.policyDecisionFingerprint.evaluationHash,
+              `${name}.policyDecisionFingerprint.evaluationHash`,
+              { allowNull: true }
+            )
+          }
+        : null
+    },
+    { path: "$" }
+  );
+}
+
 function assertNonNegativeSafeInt(value, name, { min = 0 } = {}) {
   const n = Number(value);
   if (!Number.isSafeInteger(n) || n < min) throw new TypeError(`${name} must be a safe integer >= ${min}`);
@@ -127,7 +334,8 @@ export function buildSettlementDecisionRecord({
   runLastEventId = null,
   runLastChainHash = null,
   resolutionEventId = null,
-  decidedAt
+  decidedAt,
+  bindings = undefined
 } = {}) {
   assertIsoDate(decidedAt, "decidedAt");
   const resolvedSchemaVersion = String(schemaVersion ?? "").trim();
@@ -178,6 +386,7 @@ export function buildSettlementDecisionRecord({
         runLastChainHash: runLastChainHash === null ? null : String(runLastChainHash),
         resolutionEventId: resolutionEventId === null ? null : String(resolutionEventId)
       },
+      ...(bindings === null || bindings === undefined ? {} : { bindings: normalizeSettlementBindings(bindings, "bindings", { allowNull: false }) }),
       decidedAt: String(decidedAt)
     },
     { path: "$" }
@@ -212,7 +421,8 @@ export function buildSettlementReceipt({
   finalityProvider = SETTLEMENT_FINALITY_PROVIDER.INTERNAL_LEDGER,
   finalityState = undefined,
   settledAt = null,
-  createdAt
+  createdAt,
+  bindings = undefined
 } = {}) {
   assertPlainObject(decisionRecord, "decisionRecord");
   assertIsoDate(createdAt, "createdAt");
@@ -245,6 +455,7 @@ export function buildSettlementReceipt({
       finalityProvider: String(finalityProvider ?? SETTLEMENT_FINALITY_PROVIDER.INTERNAL_LEDGER),
       finalityState: resolvedFinalityState,
       settledAt: settledAt === null ? null : String(settledAt),
+      ...(bindings === null || bindings === undefined ? {} : { bindings: normalizeSettlementBindings(bindings, "bindings", { allowNull: false }) }),
       createdAt: String(createdAt)
     },
     { path: "$" }