@armory-sh/base 0.2.28 → 0.2.29

package/src/eip712.ts

@@ -0,0 +1,108 @@
+export type TypedDataDomain = {
+  name?: string;
+  version?: string;
+  chainId?: number;
+  verifyingContract?: `0x${string}`;
+  salt?: `0x${string}`;
+};
+
+export interface EIP712Domain {
+  name: string;
+  version: string;
+  chainId: number;
+  verifyingContract: `0x${string}`;
+}
+
+export interface TransferWithAuthorization {
+  from: `0x${string}`;
+  to: `0x${string}`;
+  value: bigint;
+  validAfter: bigint;
+  validBefore: bigint;
+  nonce: `0x${string}`;
+}
+
+export type TransferWithAuthorizationRecord = TransferWithAuthorization &
+  Record<string, unknown>;
+
+export type TypedDataField = { name: string; type: string };
+
+export type EIP712Types = {
+  TransferWithAuthorization: TypedDataField[];
+};
+
+export const EIP712_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ] as const,
+} as const satisfies EIP712Types;
+
+export const USDC_DOMAIN = {
+  NAME: "USD Coin",
+  VERSION: "2",
+} as const;
+
+export const createEIP712Domain = (
+  chainId: number,
+  contractAddress: `0x${string}`,
+): EIP712Domain => ({
+  name: USDC_DOMAIN.NAME,
+  version: USDC_DOMAIN.VERSION,
+  chainId,
+  verifyingContract: contractAddress,
+});
+
+export const createTransferWithAuthorization = (
+  params: Omit<
+    TransferWithAuthorization,
+    "value" | "validAfter" | "validBefore" | "nonce"
+  > & {
+    value: bigint | number;
+    validAfter: bigint | number;
+    validBefore: bigint | number;
+    nonce: `0x${string}`;
+  },
+): TransferWithAuthorizationRecord => ({
+  from: params.from,
+  to: params.to,
+  value: BigInt(params.value),
+  validAfter: BigInt(params.validAfter),
+  validBefore: BigInt(params.validBefore),
+  nonce: params.nonce,
+});
+
+const isAddress = (value: string): boolean => /^0x[a-fA-F0-9]{40}$/.test(value);
+
+const isBytes32 = (value: string): boolean => /^0x[a-fA-F0-9]{64}$/.test(value);
+
+export const validateTransferWithAuthorization = (
+  message: TransferWithAuthorization,
+): boolean => {
+  if (!isAddress(message.from))
+    throw new Error(`Invalid "from" address: ${message.from}`);
+  if (!isAddress(message.to))
+    throw new Error(`Invalid "to" address: ${message.to}`);
+  if (message.value < 0n)
+    throw new Error(`"value" must be non-negative: ${message.value}`);
+  if (message.validAfter < 0n)
+    throw new Error(`"validAfter" must be non-negative: ${message.validAfter}`);
+  if (message.validBefore < 0n)
+    throw new Error(
+      `"validBefore" must be non-negative: ${message.validBefore}`,
+    );
+  if (message.validAfter >= message.validBefore) {
+    throw new Error(
+      `"validAfter" (${message.validAfter}) must be before "validBefore" (${message.validBefore})`,
+    );
+  }
+  if (!isBytes32(message.nonce))
+    throw new Error(
+      `"nonce" must be a valid bytes32 hex string: ${message.nonce}`,
+    );
+  return true;
+};

package/src/encoding/x402.ts

@@ -0,0 +1,205 @@
+/**
+ * X402 Protocol Encoding - V2 Only (Coinbase Compatible)
+ *
+ * Payment payloads are JSON-encoded for transport in HTTP headers.
+ * Matches the Coinbase x402 v2 SDK format.
+ */
+
+import { V2_HEADERS } from "../types/v2";
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+  SettlementResponse,
+  X402Response,
+} from "../types/x402";
+import { isPaymentPayload } from "../types/x402";
+import {
+  decodeBase64ToUtf8,
+  encodeUtf8ToBase64,
+  normalizeBase64Url,
+  toBase64Url,
+} from "../utils/base64";
+
+/**
+ * Safe Base64 encode (URL-safe, no padding)
+ */
+export function safeBase64Encode(str: string): string {
+  return toBase64Url(encodeUtf8ToBase64(str));
+}
+
+/**
+ * Safe Base64 decode (handles URL-safe format)
+ */
+export function safeBase64Decode(str: string): string {
+  return decodeBase64ToUtf8(normalizeBase64Url(str));
+}
+
+/**
+ * Encode payment payload to JSON string
+ */
+export function encodePayment(payload: PaymentPayload): string {
+  if (!isPaymentPayload(payload)) {
+    throw new Error("Invalid payment payload format");
+  }
+  // Convert any bigint values to strings for JSON serialization
+  const safePayload = JSON.parse(
+    JSON.stringify(payload, (_, value) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      return value;
+    }),
+  );
+
+  return safeBase64Encode(JSON.stringify(safePayload));
+}
+
+/**
+ * Decode payment payload from JSON string
+ */
+export function decodePayment(encoded: string): PaymentPayload {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(encoded);
+  } catch {
+    const decoded = safeBase64Decode(encoded);
+    parsed = JSON.parse(decoded);
+  }
+
+  if (!isPaymentPayload(parsed)) {
+    throw new Error("Invalid payment payload format");
+  }
+
+  return parsed;
+}
+
+/**
+ * Encode settlement response to JSON string
+ */
+export function encodeSettlementResponse(response: SettlementResponse): string {
+  const safeResponse = JSON.parse(
+    JSON.stringify(response, (_, value) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      return value;
+    }),
+  );
+
+  return safeBase64Encode(JSON.stringify(safeResponse));
+}
+
+/**
+ * Decode settlement response from JSON string
+ */
+export function decodeSettlementResponse(encoded: string): SettlementResponse {
+  try {
+    return JSON.parse(encoded);
+  } catch {
+    const decoded = safeBase64Decode(encoded);
+    return JSON.parse(decoded);
+  }
+}
+
+/**
+ * Encode X402 error response
+ */
+export function encodeX402Response(response: X402Response): string {
+  return safeBase64Encode(JSON.stringify(response));
+}
+
+/**
+ * Decode X402 error response
+ */
+export function decodeX402Response(encoded: string): X402Response {
+  try {
+    return JSON.parse(encoded);
+  } catch {
+    const decoded = safeBase64Decode(encoded);
+    return JSON.parse(decoded);
+  }
+}
+
+/**
+ * Detect payment version from headers
+ * Returns null if no payment header found
+ *
+ * V2-only: checks for PAYMENT-SIGNATURE header
+ */
+export function detectPaymentVersion(headers: Headers): number | null {
+  if (headers.has("PAYMENT-SIGNATURE")) {
+    return 2;
+  }
+
+  return null;
+}
+
+/**
+ * Extract payment from V2 headers
+ */
+export function extractPaymentFromHeaders(
+  headers: Headers,
+): PaymentPayload | null {
+  const encoded = headers.get("PAYMENT-SIGNATURE");
+  if (!encoded) return null;
+
+  try {
+    return decodePayment(encoded);
+  } catch {
+    return null;
+  }
+}
+
+export interface PaymentRequiredOptions {
+  error?: string;
+  resource?: {
+    url: string;
+    description?: string;
+    mimeType?: string;
+  };
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Create payment required headers (V2 format)
+ */
+export function createPaymentRequiredHeaders(
+  requirements: PaymentRequirements | PaymentRequirements[],
+  options?: PaymentRequiredOptions,
+): Record<string, string> {
+  const accepts = Array.isArray(requirements) ? requirements : [requirements];
+
+  const response = {
+    x402Version: 2,
+    error: options?.error ?? "Payment required",
+    resource: options?.resource ?? { url: "", mimeType: "application/json" },
+    accepts,
+    extensions: options?.extensions ?? {},
+  };
+
+  return {
+    [V2_HEADERS.PAYMENT_REQUIRED]: safeBase64Encode(JSON.stringify(response)),
+  };
+}
+
+/**
+ * Create settlement response headers (V2 format)
+ */
+export function createSettlementHeaders(
+  settlement: SettlementResponse,
+): Record<string, string> {
+  return {
+    [V2_HEADERS.PAYMENT_RESPONSE]: encodeSettlementResponse(settlement),
+  };
+}
+
+/**
+ * Decode settlement from headers (V2 only)
+ */
+export function decodeSettlement(headers: Headers): SettlementResponse {
+  const encoded = headers.get(V2_HEADERS.PAYMENT_RESPONSE);
+  if (!encoded) {
+    throw new Error(`No ${V2_HEADERS.PAYMENT_RESPONSE} header found`);
+  }
+  return decodeSettlementResponse(encoded);
+}

package/src/encoding.ts

@@ -0,0 +1,98 @@
+import type { PaymentPayloadV2, SettlementResponseV2 } from "./types/v2";
+import { V2_HEADERS } from "./types/v2";
+import {
+  decodeBase64ToUtf8,
+  encodeUtf8ToBase64,
+  normalizeBase64Url,
+  toBase64Url,
+} from "./utils/base64";
+
+export { V2_HEADERS };
+
+export type PaymentPayload = PaymentPayloadV2;
+export type SettlementResponse = SettlementResponseV2;
+
+/**
+ * Safe Base64 decode (handles URL-safe format)
+ */
+function safeBase64Decode(str: string): string {
+  return decodeBase64ToUtf8(normalizeBase64Url(str));
+}
+
+/**
+ * Safe Base64 encode (URL-safe, no padding)
+ */
+function safeBase64Encode(str: string): string {
+  return toBase64Url(encodeUtf8ToBase64(str));
+}
+
+/**
+ * JSON encode/decode for V2 (Base64URL-encoded JSON for x402 compatibility)
+ */
+const jsonEncode = (data: unknown): string => JSON.stringify(data);
+
+const base64JsonEncode = (data: unknown): string =>
+  safeBase64Encode(JSON.stringify(data));
+
+const base64JsonDecode = <T>(encoded: string): T =>
+  JSON.parse(safeBase64Decode(encoded)) as T;
+
+export const encodePaymentV2 = (payload: PaymentPayloadV2): string =>
+  base64JsonEncode(payload);
+export const decodePaymentV2 = (encoded: string): PaymentPayloadV2 =>
+  base64JsonDecode(encoded);
+
+export const encodeSettlementV2 = (response: SettlementResponseV2): string =>
+  base64JsonEncode(response);
+export const decodeSettlementV2 = (encoded: string): SettlementResponseV2 =>
+  base64JsonDecode(encoded);
+
+/**
+ * Always returns 2 for V2-only mode
+ */
+export const detectPaymentVersion = (headers: Headers): 2 | null => {
+  if (headers.has(V2_HEADERS.PAYMENT_SIGNATURE)) return 2;
+  return null;
+};
+
+/**
+ * Decode payment from headers (V2 only)
+ */
+export const decodePayment = (headers: Headers): PaymentPayload => {
+  const encoded = headers.get(V2_HEADERS.PAYMENT_SIGNATURE);
+  if (!encoded) {
+    throw new Error(`No ${V2_HEADERS.PAYMENT_SIGNATURE} header found`);
+  }
+  return decodePaymentV2(encoded);
+};
+
+/**
+ * Decode settlement from headers (V2 only)
+ */
+export const decodeSettlement = (headers: Headers): SettlementResponse => {
+  const v2Response = headers.get(V2_HEADERS.PAYMENT_RESPONSE);
+  if (v2Response) return decodeSettlementV2(v2Response);
+
+  throw new Error(`No ${V2_HEADERS.PAYMENT_RESPONSE} header found`);
+};
+
+/**
+ * Type guard for V2 payload
+ */
+export const isPaymentV2 = (
+  payload: PaymentPayload,
+): payload is PaymentPayloadV2 =>
+  "x402Version" in payload &&
+  (payload as PaymentPayloadV2).x402Version === 2 &&
+  "accepted" in payload &&
+  "payload" in payload;
+
+/**
+ * Type guard for V2 settlement
+ */
+export const isSettlementV2 = (
+  response: SettlementResponse,
+): response is SettlementResponseV2 =>
+  "success" in response &&
+  typeof (response as SettlementResponseV2).success === "boolean" &&
+  "network" in response;

package/src/errors.ts

@@ -0,0 +1,23 @@
+export class X402ClientError extends Error {
+  override readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "X402ClientError";
+    this.cause = cause;
+  }
+}
+
+export class SigningError extends X402ClientError {
+  constructor(message: string, cause?: unknown) {
+    super(`Signing failed: ${message}`, cause);
+    this.name = "SigningError";
+  }
+}
+
+export class PaymentException extends X402ClientError {
+  constructor(message: string, cause?: unknown) {
+    super(`Payment failed: ${message}`, cause);
+    this.name = "PaymentException";
+  }
+}