openpay-x402-sdk 0.1.0

package/src/guards.mjs

@@ -0,0 +1,443 @@
+import { formatUnits, isHex } from 'viem';
+import { normalizePaymentRequirements } from './payment.mjs';
+import {
+  parseSignerOptions,
+  readSignerMode,
+  SIGNER_MODES,
+} from './signer.mjs';
+
+export const JPYC_DECIMALS = 18;
+export const DEFAULT_MAX_PER_CALL_JPYC = '10';
+export const DEFAULT_MAX_SESSION_JPYC = '100';
+export const DEFAULT_ALLOWED_HOSTS = 'open-pay.jp';
+// カタログ信頼 (既定 ON): OpenPay の審査済みカタログ (/api/discovery) に載っている URL への
+// 支払いを、ALLOWED_HOSTS への手動追加なしで許可する。掲載は 402 ゲート実在 + OpenPay 方式
+// (forwarder-split) の検証を通過したものだけで、金額の防御 (per-call/session/maxTotalJpyc) は
+// 本設定と無関係に常に効く。CATALOG_TRUST=false で無効化できる。
+export const DEFAULT_CATALOG_TRUST = true;
+export const DEFAULT_DISCOVERY_URL = 'https://open-pay.jp/api/discovery';
+
+export const REASONS = {
+  invalidUrl: 'invalid_url',
+  hostNotAllowed: 'host_not_allowed',
+  unsupportedScheme: 'unsupported_scheme',
+  unsupportedNetwork: 'unsupported_network',
+  invalidOpenpayMode: 'invalid_openpay_mode',
+  amountMismatch: 'amount_mismatch',
+  invalidJpycAsset: 'invalid_jpyc_asset',
+  resourceMismatch: 'resource_mismatch',
+  invalidAccept: 'invalid_accept',
+  maxTotalRequired: 'max_total_required',
+  maxTotalInvalid: 'max_total_invalid',
+  totalExceedsMaxTotal: 'total_exceeds_max_total',
+  maxTotalAbovePerCallLimit: 'max_total_above_per_call_limit',
+  perCallLimitExceeded: 'per_call_limit_exceeded',
+  sessionLimitExceeded: 'session_limit_exceeded',
+  buyerPrivateKeyMissing: 'buyer_private_key_missing',
+  stewardSignerUnconfigured: 'steward_signer_unconfigured',
+  // catalog trust 経由 (第三者ドメイン) の URL で、支払い時にライブ fetch した accept が
+  // discovery 掲載 accept (OpenPay サーバー生成の権威値) と食い違う = bait-and-switch。
+  catalogAcceptMismatch: 'catalog_accept_mismatch',
+};
+
+export const SUPPORTED_NETWORKS = new Set([
+  'eip155:137',
+  'eip155:80002',
+  'eip155:8217',
+  'eip155:1001',
+  'eip155:43114',
+  'eip155:43113',
+]);
+
+function nonEmpty(raw) {
+  return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+export function parseJpycToAtomic(value, label) {
+  const raw = typeof value === 'number' ? String(value) : value;
+  if (typeof raw !== 'string' || !/^[0-9]+(?:\.[0-9]{1,18})?$/.test(raw)) {
+    throw new Error(`${label} must be a JPYC decimal with up to 18 decimals`);
+  }
+  const [whole, fraction = ''] = raw.split('.');
+  const atomic = BigInt(whole) * 10n ** 18n + BigInt(fraction.padEnd(18, '0'));
+  if (atomic <= 0n) throw new Error(`${label} must be greater than 0`);
+  return atomic;
+}
+
+export function formatAtomicJpyc(value) {
+  return formatUnits(value, JPYC_DECIMALS);
+}
+
+function parseAllowedHosts(raw) {
+  const source = nonEmpty(raw) ?? DEFAULT_ALLOWED_HOSTS;
+  const hosts = source.split(',').map((part) => part.trim()).filter(Boolean);
+  if (hosts.length === 0) throw new Error('ALLOWED_HOSTS must include at least one host');
+  return unique(
+    hosts.map((host) => {
+      if (host.includes('://')) {
+        throw new Error('ALLOWED_HOSTS entries must be bare hosts, not URLs');
+      }
+      let parsed;
+      try {
+        parsed = new URL(`http://${host}`);
+      } catch {
+        throw new Error(`ALLOWED_HOSTS entry is invalid: ${host}`);
+      }
+      if (parsed.pathname !== '/' || parsed.search || parsed.hash) {
+        throw new Error(`ALLOWED_HOSTS entry is invalid: ${host}`);
+      }
+      return parsed.hostname.toLowerCase();
+    }),
+  );
+}
+
+function parseOptionalPrivateKey(raw) {
+  const key = nonEmpty(raw);
+  if (key === undefined) return null;
+  if (!isHex(key) || key.length !== 66) {
+    throw new Error('BUYER_PRIVATE_KEY must be a 32-byte 0x-prefixed hex string');
+  }
+  return key;
+}
+
+function parseHttpUrl(raw, label) {
+  if (typeof raw !== 'string') return null;
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function requireHttpUrl(raw, label) {
+  const url = parseHttpUrl(raw, label);
+  if (url === null) throw new Error(`${label} must be an http(s) URL`);
+  return url.toString();
+}
+
+export function readMoneyConfig(env = process.env) {
+  return {
+    signerMode: readSignerMode(env),
+    buyerPrivateKey: parseOptionalPrivateKey(env.BUYER_PRIVATE_KEY),
+    stewardApiKey: nonEmpty(env.STEWARD_API_KEY) ?? null,
+    stewardSignerSecret: nonEmpty(env.STEWARD_SIGNER_SECRET) ?? null,
+    maxPerCallAtomic: parseJpycToAtomic(
+      nonEmpty(env.MAX_PER_CALL_JPYC) ?? DEFAULT_MAX_PER_CALL_JPYC,
+      'MAX_PER_CALL_JPYC',
+    ),
+    maxSessionAtomic: parseJpycToAtomic(
+      nonEmpty(env.MAX_SESSION_JPYC) ?? DEFAULT_MAX_SESSION_JPYC,
+      'MAX_SESSION_JPYC',
+    ),
+    allowedHosts: parseAllowedHosts(env.ALLOWED_HOSTS),
+    catalogTrust:
+      env.CATALOG_TRUST === undefined || env.CATALOG_TRUST === ''
+        ? DEFAULT_CATALOG_TRUST
+        : env.CATALOG_TRUST === 'true',
+  };
+}
+
+export function readRuntimeConfig(env = process.env) {
+  return {
+    ...readMoneyConfig(env),
+    discoveryUrl: requireHttpUrl(
+      nonEmpty(env.DISCOVERY_URL) ?? DEFAULT_DISCOVERY_URL,
+      'DISCOVERY_URL',
+    ),
+  };
+}
+
+function optionAmount(value, fallback) {
+  return value === undefined || value === '' ? fallback : value;
+}
+
+export function parseClientOptions(options = {}) {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new Error('client options must be an object');
+  }
+  const parsedSigner = parseSignerOptions(options);
+  if (
+    options.allowedHosts !== undefined &&
+    typeof options.allowedHosts !== 'string'
+  ) {
+    throw new Error('ALLOWED_HOSTS must be a comma-separated string');
+  }
+  if (
+    options.catalogTrust !== undefined &&
+    typeof options.catalogTrust !== 'boolean'
+  ) {
+    throw new Error('catalogTrust must be a boolean');
+  }
+
+  return {
+    signerMode:
+      parsedSigner.kind === 'steward' || parsedSigner.kind === 'custom'
+        ? SIGNER_MODES.steward
+        : SIGNER_MODES.envKey,
+    buyerPrivateKey:
+      parsedSigner.kind === 'private-key' ? parsedSigner.privateKey : null,
+    stewardApiKey:
+      parsedSigner.kind === 'steward' ? parsedSigner.config.apiKey : null,
+    stewardSignerSecret:
+      parsedSigner.kind === 'steward' ? parsedSigner.config.signerSecret : null,
+    maxPerCallAtomic: parseJpycToAtomic(
+      optionAmount(options.maxPerCallJpyc, DEFAULT_MAX_PER_CALL_JPYC),
+      'MAX_PER_CALL_JPYC',
+    ),
+    maxSessionAtomic: parseJpycToAtomic(
+      optionAmount(options.maxSessionJpyc, DEFAULT_MAX_SESSION_JPYC),
+      'MAX_SESSION_JPYC',
+    ),
+    allowedHosts: parseAllowedHosts(options.allowedHosts),
+    catalogTrust: options.catalogTrust ?? DEFAULT_CATALOG_TRUST,
+    discoveryUrl: requireHttpUrl(
+      nonEmpty(options.discoveryUrl) ?? DEFAULT_DISCOVERY_URL,
+      'DISCOVERY_URL',
+    ),
+  };
+}
+
+export function createPaymentSession(initialSpentAtomic = 0n) {
+  if (initialSpentAtomic < 0n) {
+    throw new Error('initialSpentAtomic must be non-negative');
+  }
+  return { spentAtomic: initialSpentAtomic };
+}
+
+export function recordSuccessfulPayment(session, amountAtomic) {
+  session.spentAtomic += amountAtomic;
+  return session.spentAtomic;
+}
+
+export function isHostAllowed(url, allowedHosts) {
+  const parsed = parseHttpUrl(url, 'url');
+  if (parsed === null) return false;
+  return allowedHosts.includes(parsed.hostname.toLowerCase());
+}
+
+function reasonFromNormalizeError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.startsWith('unsupported scheme')) return REASONS.unsupportedScheme;
+  if (message.startsWith('unsupported network') || message === 'network must be a string') {
+    return REASONS.unsupportedNetwork;
+  }
+  if (message === 'extra.openpay.forwarder-split is required') {
+    return REASONS.invalidOpenpayMode;
+  }
+  if (message === 'maxAmountRequired must equal merchantValue + feeValue') {
+    return REASONS.amountMismatch;
+  }
+  return REASONS.invalidAccept;
+}
+
+function addAssetReasons(reasons, rawAccept) {
+  const extra = isObject(rawAccept) ? rawAccept.extra : undefined;
+  if (
+    !isObject(extra) ||
+    extra.name !== 'JPY Coin' ||
+    extra.decimals !== JPYC_DECIMALS
+  ) {
+    reasons.push(REASONS.invalidJpycAsset);
+  }
+}
+
+function addResourceReason(reasons, rawAccept, requestUrl) {
+  const requested = parseHttpUrl(requestUrl, 'url');
+  const resource =
+    isObject(rawAccept) && typeof rawAccept.resource === 'string'
+      ? parseHttpUrl(rawAccept.resource, 'accept.resource')
+      : null;
+  if (
+    requested === null ||
+    resource === null ||
+    resource.hostname.toLowerCase() !== requested.hostname.toLowerCase() ||
+    resource.toString() !== requested.toString()
+  ) {
+    reasons.push(REASONS.resourceMismatch);
+  }
+}
+
+export function summarizeAccept(accept) {
+  const merchantValue = accept.extra.openpay.merchantValue;
+  const feeValue = accept.extra.openpay.feeValue;
+  const total = merchantValue + feeValue;
+  return {
+    priceAtomic: merchantValue,
+    feeAtomic: feeValue,
+    totalAtomic: total,
+    priceJpyc: formatAtomicJpyc(merchantValue),
+    feeJpyc: formatAtomicJpyc(feeValue),
+    totalJpyc: formatAtomicJpyc(total),
+    network: accept.network,
+    asset: accept.asset,
+    description: undefined,
+  };
+}
+
+export function validateAcceptForPayment(rawAccept, requestUrl) {
+  const reasons = [];
+  let accept = null;
+  let summary = null;
+
+  try {
+    accept = normalizePaymentRequirements(rawAccept);
+    summary = summarizeAccept(accept);
+  } catch (error) {
+    reasons.push(reasonFromNormalizeError(error));
+  }
+
+  if (accept !== null && !SUPPORTED_NETWORKS.has(accept.network)) {
+    reasons.push(REASONS.unsupportedNetwork);
+  }
+  addAssetReasons(reasons, rawAccept);
+  addResourceReason(reasons, rawAccept, requestUrl);
+
+  return {
+    ok: reasons.length === 0,
+    reasons: unique(reasons),
+    accept,
+    summary,
+  };
+}
+
+// catalog trust の掲載 accept (discovery = OpenPay サーバー権威) とライブ accept が、金銭に効く
+// 全フィールド (asset/forwarder/受取先/各金額/commit) まで一致するかを照合する。第三者ドメインが
+// 掲載時と別の forwarder/asset を bait-and-switch して buyer に攻撃者宛の署名を作らせる P0 を塞ぐ。
+// どちらかが正規化不能なら不一致 (fail-close)。
+function catalogAcceptConsistent(liveRawAccept, listedRawAccept) {
+  try {
+    const a = normalizePaymentRequirements(liveRawAccept);
+    const b = normalizePaymentRequirements(listedRawAccept);
+    return (
+      a.network === b.network &&
+      a.asset === b.asset &&
+      a.extra.openpay.forwarder === b.extra.openpay.forwarder &&
+      a.extra.openpay.merchant === b.extra.openpay.merchant &&
+      a.extra.openpay.merchantValue === b.extra.openpay.merchantValue &&
+      a.extra.openpay.feeReceiver === b.extra.openpay.feeReceiver &&
+      a.extra.openpay.feeValue === b.extra.openpay.feeValue &&
+      a.extra.openpay.commitVersion === b.extra.openpay.commitVersion
+    );
+  } catch {
+    return false;
+  }
+}
+
+function parseMaxTotalArg(value, reasons) {
+  if (value === undefined || value === null) {
+    reasons.push(REASONS.maxTotalRequired);
+    return null;
+  }
+  try {
+    return parseJpycToAtomic(value, 'maxTotalJpyc');
+  } catch {
+    reasons.push(REASONS.maxTotalInvalid);
+    return null;
+  }
+}
+
+export function evaluatePaymentGuards({
+  url,
+  accept,
+  config,
+  sessionSpentAtomic = 0n,
+  maxTotalJpyc,
+  requireMaxTotal = false,
+  requirePrivateKey = false,
+  requireSigner = false,
+  signerAvailable = false,
+  // Map<string, rawAccept> | null。カタログ信頼用に呼び出し側が解決した「掲載 URL → 掲載 accept
+  // (OpenPay サーバー生成の権威値)」。URL 一致で支払いを許可し、accept を bait-and-switch 照合に使う。
+  catalogListings = null,
+}) {
+  const reasons = [];
+  const parsedUrl = parseHttpUrl(url, 'url');
+  if (parsedUrl === null) {
+    reasons.push(REASONS.invalidUrl);
+  } else {
+    const hostAllowed = config.allowedHosts.includes(parsedUrl.hostname.toLowerCase());
+    // カタログ信頼はホストでなく **URL 完全一致** — allowlist より狭い単位で許可する。
+    const listedAccept =
+      config.catalogTrust && catalogListings instanceof Map
+        ? catalogListings.get(parsedUrl.toString())
+        : undefined;
+    const catalogListed = listedAccept !== undefined;
+    if (!hostAllowed && !catalogListed) {
+      reasons.push(REASONS.hostNotAllowed);
+    } else if (!hostAllowed && catalogListed) {
+      // ALLOWED_HOSTS 直 (open-pay.jp) はサーバー権威ゆえ照合不要。catalog trust 経由 (第三者
+      // ドメイン) でのみ、ライブ accept が掲載 accept と金銭フィールドまで一致するか照合する。
+      if (!catalogAcceptConsistent(accept, listedAccept)) {
+        reasons.push(REASONS.catalogAcceptMismatch);
+      }
+    }
+  }
+
+  const acceptValidation = validateAcceptForPayment(accept, url);
+  reasons.push(...acceptValidation.reasons);
+
+  let maxTotalAtomic = null;
+  if (requireMaxTotal) {
+    maxTotalAtomic = parseMaxTotalArg(maxTotalJpyc, reasons);
+    if (maxTotalAtomic !== null && maxTotalAtomic > config.maxPerCallAtomic) {
+      reasons.push(REASONS.maxTotalAbovePerCallLimit);
+    }
+  }
+
+  if (acceptValidation.summary !== null) {
+    const total = acceptValidation.summary.totalAtomic;
+    if (maxTotalAtomic !== null && total > maxTotalAtomic) {
+      reasons.push(REASONS.totalExceedsMaxTotal);
+    }
+    if (!requireMaxTotal && total > config.maxPerCallAtomic) {
+      reasons.push(REASONS.perCallLimitExceeded);
+    }
+    if (sessionSpentAtomic + total > config.maxSessionAtomic) {
+      reasons.push(REASONS.sessionLimitExceeded);
+    }
+  }
+
+  if (requirePrivateKey || requireSigner) {
+    if (config.signerMode === SIGNER_MODES.steward) {
+      if (!signerAvailable) reasons.push(REASONS.stewardSignerUnconfigured);
+    } else if (config.buyerPrivateKey === null) {
+      reasons.push(REASONS.buyerPrivateKeyMissing);
+    }
+  }
+
+  return {
+    ok: reasons.length === 0,
+    reasons: unique(reasons),
+    accept: acceptValidation.accept,
+    summary: acceptValidation.summary,
+  };
+}
+
+export function redactSensitiveText(text, secrets = []) {
+  let out = String(text);
+  for (const secret of secrets) {
+    if (typeof secret === 'string' && secret.length > 0) {
+      out = out.split(secret).join('[redacted_private_key]');
+    }
+  }
+  return out.replace(/\b0x[0-9a-fA-F]{130}\b/g, '[redacted_signature]');
+}
+
+export function safeErrorMessage(error, config = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  return redactSensitiveText(message, [
+    config.buyerPrivateKey,
+    config.stewardApiKey,
+    config.stewardSignerSecret,
+  ]);
+}

package/src/index.mjs

@@ -0,0 +1,6 @@
+export * from './catalog.mjs';
+export * from './client.mjs';
+export * from './executor.mjs';
+export * from './guards.mjs';
+export * from './payment.mjs';
+export * from './signer.mjs';

package/src/payment.mjs

@@ -0,0 +1,232 @@
+import { randomBytes } from 'node:crypto';
+import {
+  bytesToHex,
+  encodeAbiParameters,
+  getAddress,
+  isAddress,
+  keccak256,
+} from 'viem';
+
+export const RECEIVE_WITH_AUTHORIZATION_TYPES = {
+  ReceiveWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+};
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+function requireDec(value, label) {
+  if (typeof value !== 'string' || !/^[0-9]+$/.test(value)) {
+    throw new Error(`${label} must be a decimal string`);
+  }
+  return value;
+}
+
+function requireAddress(value, label) {
+  if (typeof value !== 'string' || !isAddress(value)) {
+    throw new Error(`${label} must be an EVM address`);
+  }
+  return getAddress(value);
+}
+
+function requireBytes32(value, label) {
+  if (typeof value !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(value)) {
+    throw new Error(`${label} must be bytes32`);
+  }
+  return value;
+}
+
+export function chainIdFromNetwork(network) {
+  if (typeof network !== 'string') throw new Error('network must be a string');
+  const match = /^eip155:([0-9]+)$/.exec(network);
+  if (!match) throw new Error(`unsupported network: ${network}`);
+  return Number(match[1]);
+}
+
+export function normalizePaymentRequirements(raw) {
+  if (!isObject(raw)) throw new Error('accepts[0] must be an object');
+  if (raw.scheme !== 'exact') throw new Error(`unsupported scheme: ${raw.scheme}`);
+  const chainId = chainIdFromNetwork(raw.network);
+  const asset = requireAddress(raw.asset, 'asset');
+  const payTo = requireAddress(raw.payTo, 'payTo');
+  const maxAmountRequired = BigInt(
+    requireDec(raw.maxAmountRequired, 'maxAmountRequired'),
+  );
+  const extra = raw.extra;
+  if (!isObject(extra)) throw new Error('extra is required');
+  if (extra.assetTransferMethod !== 'eip3009') {
+    throw new Error(`unsupported assetTransferMethod: ${extra.assetTransferMethod}`);
+  }
+  if (typeof extra.name !== 'string' || extra.name.length === 0) {
+    throw new Error('extra.name is required');
+  }
+  if (typeof extra.version !== 'string' || extra.version.length === 0) {
+    throw new Error('extra.version is required');
+  }
+  const openpay = extra.openpay;
+  if (!isObject(openpay) || openpay.mode !== 'forwarder-split') {
+    throw new Error('extra.openpay.forwarder-split is required');
+  }
+  const forwarder = requireAddress(openpay.forwarder, 'extra.openpay.forwarder');
+  if (payTo !== forwarder) throw new Error('payTo must match extra.openpay.forwarder');
+  const merchant = requireAddress(openpay.merchant, 'extra.openpay.merchant');
+  const merchantValue = BigInt(
+    requireDec(openpay.merchantValue, 'extra.openpay.merchantValue'),
+  );
+  const feeReceiver = requireAddress(openpay.feeReceiver, 'extra.openpay.feeReceiver');
+  const feeValue = BigInt(requireDec(openpay.feeValue, 'extra.openpay.feeValue'));
+  const commitVersion = requireBytes32(
+    openpay.commitVersion,
+    'extra.openpay.commitVersion',
+  );
+  const total = merchantValue + feeValue;
+  if (maxAmountRequired !== total) {
+    throw new Error('maxAmountRequired must equal merchantValue + feeValue');
+  }
+  return {
+    scheme: raw.scheme,
+    network: raw.network,
+    chainId,
+    asset,
+    maxTimeoutSeconds: requirePositiveInteger(
+      raw.maxTimeoutSeconds,
+      'maxTimeoutSeconds',
+    ),
+    extra: {
+      name: extra.name,
+      version: extra.version,
+      openpay: {
+        forwarder,
+        merchant,
+        merchantValue,
+        feeReceiver,
+        feeValue,
+        commitVersion,
+      },
+    },
+  };
+}
+
+function requirePositiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+export function buildForwarderNonce(params, chainId, forwarder, commitVersion) {
+  return keccak256(
+    encodeAbiParameters(
+      [
+        { type: 'bytes32' },
+        { type: 'address' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'bytes32' },
+        { type: 'uint256' },
+        { type: 'address' },
+      ],
+      [
+        commitVersion,
+        params.from,
+        params.merchant,
+        params.merchantValue,
+        params.feeReceiver,
+        params.feeValue,
+        params.validAfter,
+        params.validBefore,
+        params.intentSalt,
+        BigInt(chainId),
+        forwarder,
+      ],
+    ),
+  );
+}
+
+export function buildTypedDataFromPaymentRequirements(rawAccept, authorization) {
+  const accept = normalizePaymentRequirements(rawAccept);
+  const params = {
+    from: requireAddress(authorization.from, 'authorization.from'),
+    merchant: accept.extra.openpay.merchant,
+    merchantValue: accept.extra.openpay.merchantValue,
+    feeReceiver: accept.extra.openpay.feeReceiver,
+    feeValue: accept.extra.openpay.feeValue,
+    validAfter: BigInt(requireDec(authorization.validAfter, 'authorization.validAfter')),
+    validBefore: BigInt(requireDec(authorization.validBefore, 'authorization.validBefore')),
+    intentSalt: requireBytes32(authorization.intentSalt, 'authorization.intentSalt'),
+  };
+  const forwarder = accept.extra.openpay.forwarder;
+  const value = params.merchantValue + params.feeValue;
+  return {
+    accept,
+    params,
+    typedData: {
+      domain: {
+        name: accept.extra.name,
+        version: accept.extra.version,
+        chainId: accept.chainId,
+        verifyingContract: accept.asset,
+      },
+      types: RECEIVE_WITH_AUTHORIZATION_TYPES,
+      primaryType: 'ReceiveWithAuthorization',
+      message: {
+        from: params.from,
+        to: forwarder,
+        value,
+        validAfter: params.validAfter,
+        validBefore: params.validBefore,
+        nonce: buildForwarderNonce(
+          params,
+          accept.chainId,
+          forwarder,
+          accept.extra.openpay.commitVersion,
+        ),
+      },
+    },
+  };
+}
+
+export function createAuthorization(
+  from,
+  maxTimeoutSeconds,
+  nowSec = Math.floor(Date.now() / 1000),
+) {
+  return {
+    from: getAddress(from),
+    validAfter: '0',
+    validBefore: String(nowSec + maxTimeoutSeconds),
+    intentSalt: bytesToHex(randomBytes(32)),
+  };
+}
+
+export function encodePaymentPayload(payload) {
+  return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+}
+
+export function decodePaymentResponse(raw) {
+  if (!raw) return null;
+  return JSON.parse(Buffer.from(raw, 'base64').toString('utf8'));
+}
+
+export function paymentPayloadFor(accept, authorization, signature) {
+  return {
+    x402Version: 1,
+    scheme: accept.scheme,
+    network: accept.network,
+    payload: {
+      signature,
+      authorization,
+    },
+  };
+}