settld 0.1.2 → 0.2.0

package/src/core/x402-reversal-command.js

@@ -0,0 +1,251 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const X402_REVERSAL_COMMAND_PAYLOAD_SCHEMA_VERSION = "X402ReversalCommandPayload.v1";
+export const X402_REVERSAL_COMMAND_SCHEMA_VERSION = "X402ReversalCommand.v1";
+export const X402_REVERSAL_COMMAND_SIGNATURE_SCHEMA_VERSION = "X402ReversalCommandSignature.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 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 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 assertAction(value, name = "action") {
+  const out = assertNonEmptyString(value, name).toLowerCase();
+  if (out !== "void_authorization" && out !== "request_refund" && out !== "resolve_refund") {
+    throw new TypeError(`${name} must be void_authorization|request_refund|resolve_refund`);
+  }
+  return out;
+}
+
+function assertTarget(value, name = "target") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  const gateId = assertOptionalId(value.gateId, `${name}.gateId`, { max: 200 });
+  const receiptId = assertOptionalId(value.receiptId, `${name}.receiptId`, { max: 200 });
+  if (!gateId) throw new TypeError(`${name}.gateId is required`);
+  if (!receiptId) throw new TypeError(`${name}.receiptId is required`);
+  const quoteId = assertOptionalId(value.quoteId, `${name}.quoteId`, { max: 200 });
+  const requestSha256 = assertOptionalSha256Hex(value.requestSha256, `${name}.requestSha256`);
+  return normalizeForCanonicalJson(
+    {
+      gateId,
+      receiptId,
+      ...(quoteId ? { quoteId } : {}),
+      ...(requestSha256 ? { requestSha256 } : {})
+    },
+    { path: "$" }
+  );
+}
+
+export function buildX402ReversalCommandPayloadV1({
+  commandId,
+  sponsorRef,
+  agentKeyId = null,
+  target,
+  action,
+  nonce,
+  idempotencyKey,
+  exp
+} = {}) {
+  const payload = normalizeForCanonicalJson(
+    {
+      schemaVersion: X402_REVERSAL_COMMAND_PAYLOAD_SCHEMA_VERSION,
+      commandId: assertOptionalId(commandId, "commandId", { max: 200 }) ?? (() => {
+        throw new TypeError("commandId is required");
+      })(),
+      sponsorRef: assertOptionalId(sponsorRef, "sponsorRef", { max: 200 }) ?? (() => {
+        throw new TypeError("sponsorRef is required");
+      })(),
+      ...(assertOptionalId(agentKeyId, "agentKeyId", { max: 200 }) ? { agentKeyId: assertOptionalId(agentKeyId, "agentKeyId", { max: 200 }) } : {}),
+      target: assertTarget(target, "target"),
+      action: assertAction(action, "action"),
+      nonce: assertOptionalId(nonce, "nonce", { max: 256 }) ?? (() => {
+        throw new TypeError("nonce is required");
+      })(),
+      idempotencyKey: assertOptionalId(idempotencyKey, "idempotencyKey", { max: 256 }) ?? (() => {
+        throw new TypeError("idempotencyKey is required");
+      })(),
+      exp: assertIsoDateTime(exp, "exp")
+    },
+    { path: "$" }
+  );
+  return payload;
+}
+
+export function computeX402ReversalCommandPayloadHashV1({ payload } = {}) {
+  const normalizedPayload = buildX402ReversalCommandPayloadV1(payload ?? {});
+  return sha256Hex(canonicalJsonStringify(normalizedPayload));
+}
+
+function normalizeCommandEnvelope(command) {
+  if (!command || typeof command !== "object" || Array.isArray(command)) throw new TypeError("command must be an object");
+  const payload = buildX402ReversalCommandPayloadV1(command);
+  const signature = command.signature;
+  if (!signature || typeof signature !== "object" || Array.isArray(signature)) throw new TypeError("command.signature must be an object");
+  if (String(signature.schemaVersion ?? "") !== X402_REVERSAL_COMMAND_SIGNATURE_SCHEMA_VERSION) {
+    throw new TypeError(`command.signature.schemaVersion must be ${X402_REVERSAL_COMMAND_SIGNATURE_SCHEMA_VERSION}`);
+  }
+  if (String(signature.algorithm ?? "").toLowerCase() !== "ed25519") throw new TypeError("command.signature.algorithm must be ed25519");
+  return {
+    schemaVersion: command.schemaVersion ?? X402_REVERSAL_COMMAND_SCHEMA_VERSION,
+    payload,
+    signature: normalizeForCanonicalJson(
+      {
+        schemaVersion: X402_REVERSAL_COMMAND_SIGNATURE_SCHEMA_VERSION,
+        algorithm: "ed25519",
+        keyId: assertNonEmptyString(signature.keyId, "command.signature.keyId"),
+        signedAt: assertIsoDateTime(signature.signedAt, "command.signature.signedAt"),
+        payloadHash: assertSha256Hex(signature.payloadHash, "command.signature.payloadHash"),
+        signatureBase64: assertNonEmptyString(signature.signatureBase64, "command.signature.signatureBase64")
+      },
+      { path: "$" }
+    )
+  };
+}
+
+export function signX402ReversalCommandV1({ command, signedAt, publicKeyPem, privateKeyPem } = {}) {
+  const payload = buildX402ReversalCommandPayloadV1(command ?? {});
+  const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+  const signerPrivateKeyPem = assertPemString(privateKeyPem, "privateKeyPem");
+  const payloadHash = computeX402ReversalCommandPayloadHashV1({ payload });
+  const signatureBase64 = signHashHexEd25519(payloadHash, signerPrivateKeyPem);
+  const payloadFields = { ...payload };
+  delete payloadFields.schemaVersion;
+  return normalizeForCanonicalJson(
+    {
+      schemaVersion: X402_REVERSAL_COMMAND_SCHEMA_VERSION,
+      ...payloadFields,
+      signature: {
+        schemaVersion: X402_REVERSAL_COMMAND_SIGNATURE_SCHEMA_VERSION,
+        algorithm: "ed25519",
+        keyId: keyIdFromPublicKeyPem(signerPublicKeyPem),
+        signedAt: assertIsoDateTime(signedAt, "signedAt"),
+        payloadHash,
+        signatureBase64
+      }
+    },
+    { path: "$" }
+  );
+}
+
+export function verifyX402ReversalCommandV1({
+  command,
+  publicKeyPem,
+  nowAt = new Date().toISOString(),
+  expectedAction = null,
+  expectedSponsorRef = null,
+  expectedGateId = null,
+  expectedReceiptId = null,
+  expectedQuoteId = null,
+  expectedRequestSha256 = null
+} = {}) {
+  try {
+    const signerPublicKeyPem = assertPemString(publicKeyPem, "publicKeyPem");
+    const normalized = normalizeCommandEnvelope(command);
+    if (String(normalized.schemaVersion ?? "") !== X402_REVERSAL_COMMAND_SCHEMA_VERSION) {
+      return { ok: false, code: "X402_REVERSAL_COMMAND_SCHEMA_INVALID", error: "invalid schemaVersion" };
+    }
+    const expectedKeyId = keyIdFromPublicKeyPem(signerPublicKeyPem);
+    if (normalized.signature.keyId !== expectedKeyId) {
+      return { ok: false, code: "X402_REVERSAL_COMMAND_KEY_ID_MISMATCH", error: "signature keyId mismatch" };
+    }
+
+    const payloadHash = computeX402ReversalCommandPayloadHashV1({ payload: normalized.payload });
+    if (normalized.signature.payloadHash !== payloadHash) {
+      return { ok: false, code: "X402_REVERSAL_COMMAND_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_REVERSAL_COMMAND_SIGNATURE_INVALID", error: "signature invalid" };
+    }
+
+    const nowMs = Date.parse(assertIsoDateTime(nowAt, "nowAt"));
+    const expMs = Date.parse(normalized.payload.exp);
+    if (!Number.isFinite(expMs) || expMs <= nowMs) {
+      return { ok: false, code: "X402_REVERSAL_COMMAND_EXPIRED", error: "command expired" };
+    }
+
+    if (expectedAction !== null && assertAction(expectedAction, "expectedAction") !== normalized.payload.action) {
+      return { ok: false, code: "X402_REVERSAL_COMMAND_ACTION_MISMATCH", error: "action mismatch" };
+    }
+    if (expectedSponsorRef !== null) {
+      const expected = assertOptionalId(expectedSponsorRef, "expectedSponsorRef", { max: 200 });
+      if (expected !== normalized.payload.sponsorRef) {
+        return { ok: false, code: "X402_REVERSAL_COMMAND_SPONSOR_MISMATCH", error: "sponsorRef mismatch" };
+      }
+    }
+    if (expectedGateId !== null) {
+      const expected = assertOptionalId(expectedGateId, "expectedGateId", { max: 200 });
+      if (expected !== normalized.payload.target.gateId) {
+        return { ok: false, code: "X402_REVERSAL_COMMAND_GATE_MISMATCH", error: "target.gateId mismatch" };
+      }
+    }
+    if (expectedReceiptId !== null) {
+      const expected = assertOptionalId(expectedReceiptId, "expectedReceiptId", { max: 200 });
+      if (expected !== normalized.payload.target.receiptId) {
+        return { ok: false, code: "X402_REVERSAL_COMMAND_RECEIPT_MISMATCH", error: "target.receiptId mismatch" };
+      }
+    }
+    if (expectedQuoteId !== null) {
+      const expected = assertOptionalId(expectedQuoteId, "expectedQuoteId", { max: 200 });
+      if (expected !== normalized.payload.target.quoteId) {
+        return { ok: false, code: "X402_REVERSAL_COMMAND_QUOTE_MISMATCH", error: "target.quoteId mismatch" };
+      }
+    }
+    if (expectedRequestSha256 !== null) {
+      const expected = assertOptionalSha256Hex(expectedRequestSha256, "expectedRequestSha256");
+      if (expected !== normalized.payload.target.requestSha256) {
+        return { ok: false, code: "X402_REVERSAL_COMMAND_REQUEST_HASH_MISMATCH", error: "target.requestSha256 mismatch" };
+      }
+    }
+
+    return {
+      ok: true,
+      code: null,
+      error: null,
+      payload: normalized.payload,
+      payloadHash,
+      keyId: normalized.signature.keyId
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "X402_REVERSAL_COMMAND_SCHEMA_INVALID",
+      error: err?.message ?? String(err ?? "")
+    };
+  }
+}

package/src/core/x402-wallet-issuer-decision.js

@@ -0,0 +1,252 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { keyIdFromPublicKeyPem, sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+
+export const X402_WALLET_ISSUER_DECISION_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 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 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 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_WALLET_ISSUER_DECISION_TOKEN_VERSION) {
+    throw new TypeError(`token envelope version must be ${X402_WALLET_ISSUER_DECISION_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 buildX402WalletIssuerDecisionPayloadV1({
+  decisionId,
+  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: "X402WalletIssuerDecisionPayload.v1",
+      decisionId: assertOptionalId(decisionId, "decisionId", { max: 200 }) ?? (() => {
+        throw new TypeError("decisionId 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 computeX402WalletIssuerDecisionPayloadHashV1(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new TypeError("payload must be an object");
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function mintX402WalletIssuerDecisionTokenV1({ payload, keyId = null, publicKeyPem = null, privateKeyPem } = {}) {
+  const normalizedPayload = buildX402WalletIssuerDecisionPayloadV1(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 = computeX402WalletIssuerDecisionPayloadHashV1(normalizedPayload);
+  const signatureBase64 = signHashHexEd25519(payloadHashHex, privatePem);
+  const envelope = normalizeForCanonicalJson(
+    {
+      v: X402_WALLET_ISSUER_DECISION_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 verifyX402WalletIssuerDecisionTokenV1({
+  token,
+  publicKeyPem,
+  nowUnixSeconds = Math.floor(Date.now() / 1000),
+  expected = {}
+} = {}) {
+  try {
+    const { kid, payload, sig } = decodeEnvelope(token);
+    const normalizedPayload = buildX402WalletIssuerDecisionPayloadV1(payload);
+    const expectedKeyId = keyIdFromPublicKeyPem(assertNonEmptyString(publicKeyPem, "publicKeyPem"));
+    if (kid !== expectedKeyId) return { ok: false, code: "X402_WALLET_ISSUER_DECISION_KEY_MISMATCH", kid };
+    const payloadHashHex = computeX402WalletIssuerDecisionPayloadHashV1(normalizedPayload);
+    const signatureBase64 = Buffer.from(sig, "base64url").toString("base64");
+    if (!verifyHashHexEd25519({ hashHex: payloadHashHex, signatureBase64, publicKeyPem })) {
+      return { ok: false, code: "X402_WALLET_ISSUER_DECISION_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_WALLET_ISSUER_DECISION_EXPIRED", kid };
+    }
+
+    const expectedFields = [
+      "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_WALLET_ISSUER_DECISION_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_WALLET_ISSUER_DECISION_SCHEMA_INVALID",
+      error: err?.message ?? String(err ?? "")
+    };
+  }
+}