@bitpal/checkout 0.1.0 → 0.2.0

package/MIGRATION_v0.2.md

@@ -0,0 +1,135 @@
+# @bitpal/checkout — Migration Guide v0.1.x → v0.2.0
+
+> Audit doc 11 §3 C-01 option 2 (PaymentAuthorization 이중방어) 적용으로 인한 SDK 메이저 bump.
+
+## Why this change
+
+v0.1.x 까지의 `payWithAuthorization` 흐름은 buyer 의 EIP-3009 USDC sig 만 받았다. 이 sig 는
+`(from, to, value, validAfter, validBefore, nonce)` 만 바인딩하므로, **paymentId / merchant /
+amount / fee / reserve / duration** 은 호출자(BitPal gateway)가 자유롭게 지정 가능했다.
+
+→ gateway 키 탈취 시 공격자가 (a) buyer 의 EIP-3009 sig 입수 후 (b) 자기 주소를 merchant 로 설정,
+   (c) `depositWithAuthorization` 호출 → buyer 자금이 attacker merchant 로 흘러간다.
+
+v0.2.0 는 buyer 가 **결제 의도 전체** 에 별도 EIP-712 서명 (`PaymentAuthorization`) 을 한다. gateway
+키 탈취 시에도 buyer 의도 밖 결제 생성 불가 (이중방어).
+
+## Breaking changes
+
+### `BitPal.checkout.payWithAuthorization(sessionId, params)`
+
+`params.payment_auth` 필드가 **필수** 가 됐다.
+
+**Before (v0.1.x):**
+```ts
+await bp.checkout.payWithAuthorization(sessionId, {
+  session_token: 'xyz...',
+  chain: 'base',
+  authorization: {
+    from: buyer.address,
+    validAfter: '0',
+    validBefore: String(Math.floor(Date.now()/1000) + 3600),
+    authNonce: '0x...',
+    v: 27, r: '0x...', s: '0x...',
+  },
+});
+```
+
+**After (v0.2.0):**
+```ts
+import {
+  buildPaymentAuthTypedData,
+  sessionIdToPaymentId,
+} from '@bitpal/checkout';
+
+// 1. PaymentAuthorization nonce 조회 (CheckoutEscrow.paymentAuthNonce)
+const nonce = await escrow.read.paymentAuthNonce([buyer.address]);
+
+// 2. PaymentAuthorization typed-data sig
+const paymentAuthDeadline = Math.floor(Date.now()/1000) + 3600;
+const paymentId = sessionIdToPaymentId(sessionId);
+const paymentAuthTd = buildPaymentAuthTypedData({
+  escrowAddress: escrow.address,
+  chainId: 8453,
+  paymentId,
+  payer: buyer.address,
+  merchant: session.seller_wallet,
+  token: session.token_address,
+  amount: session.amount_total,
+  feeAmount: '0',
+  reserveAmount: '0',
+  duration: '0',
+  deadline: String(paymentAuthDeadline),
+  nonce: String(nonce),
+});
+const paymentAuthSig = await wallet.signTypedData(paymentAuthTd);
+const paymentAuthParsed = parseSignature(paymentAuthSig);  // viem helper
+
+// 3. USDC EIP-3009 sig (변경 없음 — 기존 흐름 그대로)
+const usdcSig = await wallet.signTypedData({ /* TransferWithAuthorization ... */ });
+const usdcParsed = parseSignature(usdcSig);
+
+// 4. payWithAuthorization 호출 — payment_auth 필드 추가
+await bp.checkout.payWithAuthorization(sessionId, {
+  session_token: 'xyz...',
+  chain: 'base',
+  authorization: {
+    from: buyer.address,
+    validAfter: '0',
+    validBefore: String(Math.floor(Date.now()/1000) + 3600),
+    authNonce: '0x...',
+    v: Number(usdcParsed.v), r: usdcParsed.r, s: usdcParsed.s,
+  },
+  // ← 신규 필수
+  payment_auth: {
+    deadline: String(paymentAuthDeadline),
+    duration: '0',
+    v: Number(paymentAuthParsed.v),
+    r: paymentAuthParsed.r,
+    s: paymentAuthParsed.s,
+  },
+});
+```
+
+### 백엔드 응답에서 `payment_auth_nonce` 노출
+
+서버는 `GET /v1/checkout/sessions/:id/public` 응답에 `payment_auth_nonce` 필드를 포함한다
+(Q5 적용 후). buyer UI 가 컨트랙트를 직접 호출하지 않고도 nonce 를 얻을 수 있다. 단,
+`merchant_wallet` (seller_wallet) 도 sig 에 들어가므로 public response 에서 확인할 수 있어야 한다.
+
+## Non-breaking changes
+
+다음 SDK 흐름은 변경 없음:
+
+- `createSession()`, `getSession()`, `listSessions()`, `previewFee()`
+- `refundSession()`, `recordRefund()`, `listRefunds()`
+- `submitExternalPayment()` (Mode A — buyer 가 본인 지갑으로 직접 deposit)
+- Webhook helpers (`verifyWebhookSignature`, `parseWebhookEvent`)
+- Amount helpers (`toAtomicUSDC`, `fromAtomicUSDC`)
+
+## Why `payment_auth` is required (no opt-out)
+
+Q4 PR 적용 후 `CheckoutEscrow.depositWithAuthorization` 가 PaymentAuthorization sig 를 강제한다
+(컨트랙트 require). SDK 가 sig 없이 호출 시 백엔드가 `PAYMENT_AUTH_REQUIRED` (400) 로 거부.
+
+## Compatibility matrix
+
+| SDK version | Backend (CheckoutEscrow contract) | Result |
+|---|---|---|
+| v0.1.x | post-Q5 (PaymentAuthorization 필수) | ❌ `PAYMENT_AUTH_REQUIRED` 400 |
+| v0.2.0 | post-Q5 | ✅ OK |
+| v0.2.0 | pre-Q5 (legacy 미배포 contract) | ❌ contract revert (signature 추가 인자 없음) |
+
+→ SDK v0.2.0 와 컨트랙트 Q4+Q5 적용은 **동시 배포** 가 원칙. testnet 부터 함께 갈아끼움.
+
+## New helpers
+
+- `buildPaymentAuthTypedData(args)` — `signTypedData` 호환 객체 생성
+- `buildConfirmReceiptTypedData(args)` — Q4 H-01 `confirmReceiptWithSignature` 용 (off-chain receipt confirmation 직접 구현 시 사용. 기본 흐름에서는 BitPal hosted page 가 처리)
+- `sessionIdToPaymentId(sessionId)` — 32-byte hex 변환 (= 백엔드 `toBytes32()`)
+
+## See also
+
+- `docs/_dan/b2b-spec/2026-05-14-11-smart-contract-security-audit.md` §3 C-01
+- `docs/_dan/b2b-spec/2026-05-18-14-post-audit-remaining-hardening-plan.md` §4 (PR-C 실행 가이드)
+- README.md §"Gasless lane (Hosted / Gasless)"

package/dist/index.d.ts

@@ -145,6 +145,7 @@ interface SubmitExternalPaymentResult {
 interface PayWithAuthorizationParams {
     chain?: string;
     session_token: string;
+    /** EIP-3009 TransferWithAuthorization sig (USDC). */
     authorization: {
         from: string;
         validAfter?: string;
@@ -154,6 +155,39 @@ interface PayWithAuthorizationParams {
         r: string;
         s: string;
     };
+    /**
+     * Q5 C-01 옵션 2 (SDK v0.2.0): PaymentAuthorization typed-data sig.
+     * Buyer 가 결제 의도 전체 (paymentId, merchant, amount, fee, reserve, duration) 에 서명.
+     * gateway 키 탈취 시에도 buyer 의도 밖 결제 생성 차단.
+     *
+     * 서명 생성: `buildPaymentAuthTypedData()` helper 또는 viem `signTypedData` 직접 호출.
+     * Required for SDK v0.2.x+ — gasless lane 모든 호출에 필수. v0.1.x 는 미지원.
+     */
+    payment_auth: {
+        deadline: string;
+        duration: string;
+        v: number;
+        r: string;
+        s: string;
+    };
+}
+/**
+ * Q5 C-01 옵션 2: buyer 가 서명할 EIP-712 PaymentAuthorization typed-data 의 입력 인자.
+ * `buildPaymentAuthTypedData()` 가 이를 받아 viem 호환 객체를 반환.
+ */
+interface PaymentAuthTypedDataArgs {
+    escrowAddress: string;
+    chainId: number;
+    paymentId: string;
+    payer: string;
+    merchant: string;
+    token: string;
+    amount: string;
+    feeAmount: string;
+    reserveAmount: string;
+    duration: string;
+    deadline: string;
+    nonce: string;
 }
 interface CheckoutPaymentResult {
     status: string;
@@ -344,10 +378,24 @@ declare class BitPalCheckoutClient {
     /**
      * Gasless checkout payment through the BitPal API relayer.
      *
-     * The buyer signs an EIP-3009 authorization and the API calls
-     * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer.
+     * The buyer signs **two** EIP-712 typed-data structures and the API calls
+     * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer:
+     *
+     * 1. **EIP-3009 USDC TransferWithAuthorization** (`params.authorization`) —
+     *    authorizes USDC transfer from buyer to escrow.
+     * 2. **PaymentAuthorization** (`params.payment_auth`, since SDK v0.2.0) —
+     *    binds the entire payment intent (paymentId, merchant, amount, fee,
+     *    reserve, duration) to the buyer's signature. Without this, a compromised
+     *    gateway key could redirect funds to an attacker-controlled merchant.
+     *
+     * Build the PaymentAuthorization typed-data with `buildPaymentAuthTypedData()`.
+     * The PaymentAuthorization nonce comes from `CheckoutEscrow.paymentAuthNonce(payer)`.
+     *
      * Use the returned session/order state only as immediate UX feedback; the
      * merchant backend should finalize fulfillment from signed webhooks.
+     *
+     * @breaking-change v0.2.0 — `payment_auth` field is now required. v0.1.x clients
+     *                          must upgrade their signing flow. See MIGRATION_v0.2.md.
      */
     payWithAuthorization(sessionId: string, params: PayWithAuthorizationParams, opts?: IdempotencyOptions): Promise<ApiResponse<CheckoutPaymentResult>>;
     /**
@@ -485,6 +533,154 @@ declare function toAtomicUSDC(decimal: string): string;
  */
 declare function fromAtomicUSDC(atomic: string): string;
 
+/**
+ * typed-data.ts — Q5 C-01 옵션 2 (SDK v0.2.0).
+ *
+ * BitPal Checkout 의 EIP-712 typed-data helper. SDK 가 모든 typed-data 작업을 직접
+ * 수행하지 않고 (서명은 머천트의 wallet provider 가) **typed-data 객체만 생성** 한다.
+ *
+ * 사용 예 (viem):
+ *
+ * ```ts
+ * import { buildPaymentAuthTypedData } from '@bitpal/checkout';
+ * import { signTypedData } from 'viem/accounts';
+ *
+ * const td = buildPaymentAuthTypedData({
+ *   escrowAddress: '0x...',
+ *   chainId: 8453,
+ *   paymentId: '0x...',     // = toBytes32(sessionId)
+ *   payer: buyer.address,
+ *   merchant: session.seller_wallet,
+ *   token: session.token_address,
+ *   amount: session.amount_total,
+ *   feeAmount: '0',
+ *   reserveAmount: '0',
+ *   duration: '0',
+ *   deadline: String(Math.floor(Date.now()/1000) + 3600),
+ *   nonce: String(await escrow.read.paymentAuthNonce(buyer.address)),
+ * });
+ * const sig = await walletClient.signTypedData(td);
+ * ```
+ *
+ * 사용 예 (wagmi `useSignTypedData`):
+ *
+ * ```tsx
+ * const { signTypedDataAsync } = useSignTypedData();
+ * const td = buildPaymentAuthTypedData({ ... });
+ * const sig = await signTypedDataAsync(td);
+ * ```
+ */
+
+/**
+ * Build EIP-712 typed-data object for PaymentAuthorization signing.
+ * Returns a viem-compatible structure (also compatible with wagmi/ethers v6 signTypedData).
+ */
+declare function buildPaymentAuthTypedData(args: PaymentAuthTypedDataArgs): {
+    readonly domain: {
+        readonly name: "CheckoutEscrow";
+        readonly version: "1";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    readonly types: {
+        readonly PaymentAuthorization: readonly [{
+            readonly name: "paymentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "merchant";
+            readonly type: "address";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "feeAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "reserveAmount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "duration";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }];
+    };
+    readonly primaryType: "PaymentAuthorization";
+    readonly message: {
+        readonly paymentId: `0x${string}`;
+        readonly payer: `0x${string}`;
+        readonly merchant: `0x${string}`;
+        readonly token: `0x${string}`;
+        readonly amount: bigint;
+        readonly feeAmount: bigint;
+        readonly reserveAmount: bigint;
+        readonly duration: bigint;
+        readonly deadline: bigint;
+        readonly nonce: bigint;
+    };
+};
+/**
+ * Args for the EIP-712 ConfirmReceipt typed-data.
+ * Used when buyer signs an off-chain receipt confirmation that BitPal gateway relays
+ * on-chain via `confirmReceiptWithSignature` (Q4 H-01).
+ */
+interface ConfirmReceiptTypedDataArgs {
+    escrowAddress: string;
+    chainId: number;
+    paymentId: string;
+    payer: string;
+    deadline: string;
+    nonce: string;
+}
+/**
+ * Build EIP-712 typed-data object for ConfirmReceipt signing (Q4 H-01).
+ */
+declare function buildConfirmReceiptTypedData(args: ConfirmReceiptTypedDataArgs): {
+    readonly domain: {
+        readonly name: "CheckoutEscrow";
+        readonly version: "1";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    readonly types: {
+        readonly ConfirmReceipt: readonly [{
+            readonly name: "paymentId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }];
+    };
+    readonly primaryType: "ConfirmReceipt";
+    readonly message: {
+        readonly paymentId: `0x${string}`;
+        readonly payer: `0x${string}`;
+        readonly deadline: bigint;
+        readonly nonce: bigint;
+    };
+};
+/**
+ * Convert a session ID string into a 32-byte hex (`paymentId`) suitable for typed-data signing.
+ * Mirrors the backend `toBytes32(sessionId)` helper.
+ */
+declare function sessionIdToPaymentId(sessionId: string): `0x${string}`;
+
 /**
  * @bitpal/checkout — BitPal Checkout SDK
  *
@@ -512,4 +708,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutPaymentResult, type CheckoutSession, type CheckoutWebhookEvent, type CreateSessionParams, type ExternalPaymentConfig, type FeePreview, type IdempotencyOptions, type LineItem, type ListResponse, type PayWithAuthorizationParams, type PaymentObservation, type RecordRefundParams, type RefundEntry, type RefundSessionParams, type RefundSessionResult, type SubmitExternalPaymentParams, type SubmitExternalPaymentResult, WEBHOOK_HEADERS, type WebhookPayload, fromAtomicUSDC, parseWebhookEvent, toAtomicUSDC, verifyWebhookSignature };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutPaymentResult, type CheckoutSession, type CheckoutWebhookEvent, type ConfirmReceiptTypedDataArgs, type CreateSessionParams, type ExternalPaymentConfig, type FeePreview, type IdempotencyOptions, type LineItem, type ListResponse, type PayWithAuthorizationParams, type PaymentAuthTypedDataArgs, type PaymentObservation, type RecordRefundParams, type RefundEntry, type RefundSessionParams, type RefundSessionResult, type SubmitExternalPaymentParams, type SubmitExternalPaymentResult, WEBHOOK_HEADERS, type WebhookPayload, buildConfirmReceiptTypedData, buildPaymentAuthTypedData, fromAtomicUSDC, parseWebhookEvent, sessionIdToPaymentId, toAtomicUSDC, verifyWebhookSignature };

package/dist/index.js

@@ -182,10 +182,24 @@ var BitPalCheckoutClient = class {
   /**
    * Gasless checkout payment through the BitPal API relayer.
    *
-   * The buyer signs an EIP-3009 authorization and the API calls
-   * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer.
+   * The buyer signs **two** EIP-712 typed-data structures and the API calls
+   * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer:
+   *
+   * 1. **EIP-3009 USDC TransferWithAuthorization** (`params.authorization`) —
+   *    authorizes USDC transfer from buyer to escrow.
+   * 2. **PaymentAuthorization** (`params.payment_auth`, since SDK v0.2.0) —
+   *    binds the entire payment intent (paymentId, merchant, amount, fee,
+   *    reserve, duration) to the buyer's signature. Without this, a compromised
+   *    gateway key could redirect funds to an attacker-controlled merchant.
+   *
+   * Build the PaymentAuthorization typed-data with `buildPaymentAuthTypedData()`.
+   * The PaymentAuthorization nonce comes from `CheckoutEscrow.paymentAuthNonce(payer)`.
+   *
    * Use the returned session/order state only as immediate UX feedback; the
    * merchant backend should finalize fulfillment from signed webhooks.
+   *
+   * @breaking-change v0.2.0 — `payment_auth` field is now required. v0.1.x clients
+   *                          must upgrade their signing flow. See MIGRATION_v0.2.md.
    */
   async payWithAuthorization(sessionId, params, opts) {
     return this.request(
@@ -304,6 +318,74 @@ function fromAtomicUSDC(atomic) {
   return fracStr.length > 0 ? `${whole}.${fracStr.padEnd(2, "0")}` : `${whole}.00`;
 }
 
+// src/typed-data.ts
+function buildPaymentAuthTypedData(args) {
+  return {
+    domain: {
+      name: "CheckoutEscrow",
+      version: "1",
+      chainId: args.chainId,
+      verifyingContract: args.escrowAddress
+    },
+    types: {
+      PaymentAuthorization: [
+        { name: "paymentId", type: "bytes32" },
+        { name: "payer", type: "address" },
+        { name: "merchant", type: "address" },
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint256" },
+        { name: "feeAmount", type: "uint256" },
+        { name: "reserveAmount", type: "uint256" },
+        { name: "duration", type: "uint256" },
+        { name: "deadline", type: "uint256" },
+        { name: "nonce", type: "uint256" }
+      ]
+    },
+    primaryType: "PaymentAuthorization",
+    message: {
+      paymentId: args.paymentId,
+      payer: args.payer,
+      merchant: args.merchant,
+      token: args.token,
+      amount: BigInt(args.amount),
+      feeAmount: BigInt(args.feeAmount),
+      reserveAmount: BigInt(args.reserveAmount),
+      duration: BigInt(args.duration),
+      deadline: BigInt(args.deadline),
+      nonce: BigInt(args.nonce)
+    }
+  };
+}
+function buildConfirmReceiptTypedData(args) {
+  return {
+    domain: {
+      name: "CheckoutEscrow",
+      version: "1",
+      chainId: args.chainId,
+      verifyingContract: args.escrowAddress
+    },
+    types: {
+      ConfirmReceipt: [
+        { name: "paymentId", type: "bytes32" },
+        { name: "payer", type: "address" },
+        { name: "deadline", type: "uint256" },
+        { name: "nonce", type: "uint256" }
+      ]
+    },
+    primaryType: "ConfirmReceipt",
+    message: {
+      paymentId: args.paymentId,
+      payer: args.payer,
+      deadline: BigInt(args.deadline),
+      nonce: BigInt(args.nonce)
+    }
+  };
+}
+function sessionIdToPaymentId(sessionId) {
+  const hex = Array.from(new TextEncoder().encode(sessionId)).map((b) => b.toString(16).padStart(2, "0")).join("").padEnd(64, "0");
+  return `0x${hex}`;
+}
+
 // src/index.ts
 var BitPal = class {
   checkout;
@@ -318,8 +400,11 @@ export {
   BitPalError,
   CHECKOUT_WEBHOOK_EVENTS,
   WEBHOOK_HEADERS,
+  buildConfirmReceiptTypedData,
+  buildPaymentAuthTypedData,
   fromAtomicUSDC,
   parseWebhookEvent,
+  sessionIdToPaymentId,
   toAtomicUSDC,
   verifyWebhookSignature
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.1.0",
-  "description": "BitPal Checkout SDK — crypto payment sessions, external on-chain payment verification, gasless checkout, refunds, fee preview.",
+  "version": "0.2.0",
+  "description": "BitPal Checkout SDK — crypto payment sessions, external on-chain payment verification, gasless checkout (with PaymentAuthorization double-defense), refunds, fee preview.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "MIGRATION_v0.2.md"
   ],
   "keywords": [
     "bitpal",
@@ -34,14 +35,15 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "lint": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.5.0",
     "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "release": "pnpm publish --access public --no-git-checks"
   }
-}
+}