@bitpal/checkout 0.3.0 → 0.6.0

package/MIGRATION_v0.2.md

@@ -1,135 +0,0 @@
-# @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)"