@01.software/init 0.9.2 → 0.10.1

package/dist/create-app-templates/ecommerce/tests/domain.test.ts

@@ -0,0 +1,1632 @@
+import assert from 'node:assert/strict'
+import { createHmac } from 'node:crypto'
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import test from 'node:test'
+
+import { normalizeCartLines } from '../lib/cart/normalize.ts'
+import { getCheckoutErrorStatus } from '../lib/checkout/checkout-errors.ts'
+import { parseCheckoutPayload } from '../lib/checkout/parse-checkout-payload.ts'
+import { startCheckout } from '../lib/checkout/start-checkout.ts'
+import {
+  mapSoftwareProductDetail,
+  mapSoftwareProductDetailResult,
+} from '../lib/commerce/adapters/software-mappers.ts'
+import {
+  buildSoftwareCommerceProvider,
+  getSoftwareCommerceConfig,
+  type SoftwareSdkClientLike,
+} from '../lib/commerce/adapters/software.ts'
+import { summarizeProductAvailability } from '../lib/commerce/product-summary.ts'
+import { resolveVariantFromSelection } from '../lib/commerce/variant-selection.ts'
+import { createMockPaymentProvider } from '../lib/payment/adapters/mock.ts'
+// scaffold:provider:portone:start
+import {
+  createPortOnePaymentProviderForConfig,
+  getPortOneConfig,
+} from '../lib/payment/adapters/portone.ts'
+// scaffold:provider:portone:end
+// scaffold:provider:tosspayments:start
+import {
+  createTossPaymentsProvider,
+  getTossPaymentsConfig,
+} from '../lib/payment/adapters/tosspayments.ts'
+// scaffold:provider:tosspayments:end
+import {
+  AmountMismatchError,
+  assertAmountEquals,
+} from '../lib/payment/amount-gate.ts'
+import { syncOrderPayment } from '../lib/payment/sync-order-payment.ts'
+import type { CommerceProvider } from '../lib/commerce/provider.ts'
+import type { PaymentProvider } from '../lib/payment/provider.ts'
+import type {
+  Order,
+  ProductDetail,
+  ProductVariant,
+} from '../lib/commerce/types.ts'
+
+const variantA: ProductVariant = {
+  id: 'var-shirt-red-s',
+  productId: 'prod-shirt',
+  title: 'Red / Small',
+  sku: 'SHIRT-RED-S',
+  price: 32000,
+  stock: 8,
+  reservedStock: 2,
+  isUnlimited: false,
+  optionValues: [
+    {
+      optionId: 'opt-color',
+      valueId: 'val-red',
+      valueSlug: 'red',
+      value: 'Red',
+    },
+    {
+      optionId: 'opt-size',
+      valueId: 'val-small',
+      valueSlug: 'small',
+      value: 'Small',
+    },
+  ],
+  images: [],
+}
+
+const variantB: ProductVariant = {
+  ...variantA,
+  id: 'var-shirt-blue-s',
+  title: 'Blue / Small',
+  optionValues: [
+    {
+      optionId: 'opt-color',
+      valueId: 'val-blue',
+      valueSlug: 'blue',
+      value: 'Blue',
+    },
+    {
+      optionId: 'opt-size',
+      valueId: 'val-small',
+      valueSlug: 'small',
+      value: 'Small',
+    },
+  ],
+}
+
+const productDetail: ProductDetail = {
+  product: {
+    id: 'prod-shirt',
+    slug: 'daily-shirt',
+    title: 'Daily Shirt',
+    images: [],
+    status: 'published',
+  },
+  variants: [variantA, variantB],
+  options: [
+    {
+      id: 'opt-color',
+      slug: 'color',
+      title: 'Color',
+      values: [
+        { id: 'val-red', slug: 'red', value: 'Red' },
+        { id: 'val-blue', slug: 'blue', value: 'Blue' },
+      ],
+    },
+    {
+      id: 'opt-size',
+      slug: 'size',
+      title: 'Size',
+      values: [{ id: 'val-small', slug: 'small', value: 'Small' }],
+    },
+  ],
+}
+
+const mockPaymentStorePath = join(process.cwd(), '.mock-payments.json')
+
+test('normalizes persisted cart lines into unique positive integer quantities', () => {
+  assert.deepEqual(
+    normalizeCartLines([
+      { variantId: ' var-shirt-red-s ', quantity: 1 },
+      { variantId: 'var-shirt-red-s', quantity: 2.8 },
+      { variantId: '', quantity: 4 },
+      { variantId: 'var-shirt-blue-s', quantity: -1 },
+      { variantId: 'var-shirt-blue-s', quantity: 100 },
+    ]),
+    [
+      { variantId: 'var-shirt-red-s', quantity: 3 },
+      { variantId: 'var-shirt-blue-s', quantity: 99 },
+    ],
+  )
+})
+
+test('resolves a variant only when every product option has a selected value', () => {
+  assert.equal(
+    resolveVariantFromSelection(productDetail, {
+      'opt-color': 'val-blue',
+      'opt-size': 'val-small',
+    })?.id,
+    'var-shirt-blue-s',
+  )
+
+  assert.equal(
+    resolveVariantFromSelection(productDetail, {
+      'opt-color': 'val-blue',
+    }),
+    null,
+  )
+})
+
+test('summarizes products with no variants as unavailable', () => {
+  assert.deepEqual(
+    summarizeProductAvailability({
+      ...productDetail,
+      variants: [],
+    }),
+    {
+      hasVariants: false,
+      available: false,
+      priceLabel: 'Unavailable',
+    },
+  )
+})
+
+test('syncOrderPayment places a verified-paid payment through confirmOrderPayment', async () => {
+  // Pre-placement there is no order; a verified-paid PG payment promotes the
+  // open checkout to a paid order with the provider-re-fetched amount.
+  const commerce = makeCommerceProvider(null)
+  const payment = makePaymentProvider({
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+  })
+
+  const result = await syncOrderPayment({
+    paymentId: 'pay_1',
+    orderNumber: 'ORD-1',
+    commerceProvider: commerce,
+    paymentProvider: payment,
+  })
+
+  assert.equal(result.status, 'paid')
+  assert.equal(commerce.confirmed, true)
+  assert.equal(commerce.confirmedAmount, 99000)
+})
+
+test('syncOrderPayment is idempotent once the order is already placed', async () => {
+  const order = makePendingOrder({ totalAmount: 99000 })
+  const commerce = makeCommerceProvider({ ...order, displayStatus: 'paid' })
+  const payment = makePaymentProvider({
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+  })
+
+  const result = await syncOrderPayment({
+    paymentId: 'pay_1',
+    orderNumber: 'ORD-1',
+    commerceProvider: commerce,
+    paymentProvider: payment,
+  })
+
+  assert.equal(result.status, 'paid')
+  assert.equal(commerce.confirmed, false)
+})
+
+test('syncOrderPayment reports pending while the provider payment is pending', async () => {
+  const commerce = makeCommerceProvider(null)
+  const payment = makePaymentProvider({
+    paymentId: 'pay_1',
+    status: 'pending',
+    amount: 99000,
+  })
+
+  const result = await syncOrderPayment({
+    paymentId: 'pay_1',
+    orderNumber: 'ORD-1',
+    commerceProvider: commerce,
+    paymentProvider: payment,
+  })
+
+  assert.equal(result.status, 'pending')
+  assert.equal(commerce.confirmed, false)
+})
+
+test('parseCheckoutPayload rejects invalid customer and shipping fields', () => {
+  assert.throws(
+    () =>
+      parseCheckoutPayload({
+        lines: [{ variantId: 'var-shirt-red-s', quantity: 1 }],
+        customerSnapshot: { name: 'Ada', email: 'not-an-email', phone: '010' },
+        shippingAddress: {
+          recipientName: 'Ada',
+          phone: '010',
+          postalCode: '04524',
+          address: 'Seoul',
+          detailAddress: '101',
+        },
+      }),
+    /email/,
+  )
+})
+
+test('parseCheckoutPayload accepts missing shipping fields when the cart requires no shipping', () => {
+  assert.deepEqual(
+    parseCheckoutPayload(
+      {
+        customerSnapshot: {
+          name: 'Ada',
+          email: 'ada@example.test',
+          phone: '010',
+        },
+      },
+      { requiresShipping: false },
+    ),
+    {
+      customerSnapshot: {
+        name: 'Ada',
+        email: 'ada@example.test',
+        phone: '010',
+      },
+    },
+  )
+})
+
+test('parseCheckoutPayload still requires shipping fields by default', () => {
+  assert.throws(
+    () =>
+      parseCheckoutPayload({
+        customerSnapshot: {
+          name: 'Ada',
+          email: 'ada@example.test',
+          phone: '010',
+        },
+      }),
+    /shippingAddress/,
+  )
+})
+
+test('startCheckout converts the server cart then requests payment with the cart total', async () => {
+  const order = makePendingOrder({ totalAmount: 99000 })
+  let requestedAmount = 0
+  let checkoutCartToken: string | null = null
+  const commerce: CommerceProvider = {
+    ...makeCommerceProvider(null),
+    async checkoutCart(input) {
+      checkoutCartToken = input.cartToken
+      return {
+        order,
+        paymentId: 'pay_1',
+        paymentName: 'Server cart order',
+        amount: 99000,
+        currency: 'KRW',
+      }
+    },
+  }
+  const payment: PaymentProvider = {
+    ...makePaymentProvider(null),
+    provider: 'tosspayments',
+    async requestPayment(input) {
+      requestedAmount = input.amount
+      return {
+        ok: true,
+        paymentId: input.paymentId,
+        redirectUrl: '/checkout/success?paymentId=pay_1&orderNumber=ORD-1',
+      }
+    },
+  }
+
+  const result = await startCheckout({
+    cartToken: 'tok_1',
+    payload: {
+      customerSnapshot: order.customerSnapshot,
+      shippingAddress: order.shippingAddress,
+    },
+    commerceProvider: commerce,
+    paymentProvider: payment,
+  })
+
+  assert.equal(checkoutCartToken, 'tok_1')
+  assert.equal(requestedAmount, 99000)
+  assert.equal(
+    result.redirectUrl,
+    '/checkout/success?paymentId=pay_1&orderNumber=ORD-1',
+  )
+})
+
+test('startCheckout surfaces a failed payment request', async () => {
+  const order = makePendingOrder({ totalAmount: 99000 })
+  const commerce: CommerceProvider = {
+    ...makeCommerceProvider(null),
+    async checkoutCart() {
+      return {
+        order,
+        paymentId: 'pay_1',
+        paymentName: 'Server cart order',
+        amount: 99000,
+        currency: 'KRW',
+      }
+    },
+  }
+  const payment: PaymentProvider = {
+    ...makePaymentProvider(null),
+    provider: 'tosspayments',
+    async requestPayment() {
+      return { ok: false, paymentId: 'pay_1', reason: 'failed' }
+    },
+  }
+
+  await assert.rejects(
+    startCheckout({
+      cartToken: 'tok_1',
+      payload: {
+        customerSnapshot: order.customerSnapshot,
+        shippingAddress: order.shippingAddress,
+      },
+      commerceProvider: commerce,
+      paymentProvider: payment,
+    }),
+    /failed/,
+  )
+})
+
+test('checkout error status preserves SDK authorization failures', () => {
+  assert.equal(
+    getCheckoutErrorStatus(
+      Object.assign(new Error('Forbidden'), { status: 403 }),
+    ),
+    403,
+  )
+})
+
+test('checkout error status maps payload validation failures to bad request', () => {
+  assert.equal(
+    getCheckoutErrorStatus(new Error('valid email is required')),
+    400,
+  )
+})
+
+test('mock payment provider stores payments independently from mock commerce orders', async () => {
+  clearMockPaymentStore()
+  const payment = createMockPaymentProvider()
+
+  await payment.requestPayment({
+    paymentId: 'pay_independent',
+    orderNumber: 'ORD-INDEPENDENT',
+    orderName: 'Independent order',
+    amount: 12345,
+    currency: 'KRW',
+    customer: {
+      name: 'Ada',
+      email: 'ada@example.com',
+      phone: '010-0000-0000',
+    },
+  })
+
+  assert.deepEqual(await payment.getPayment('pay_independent'), {
+    paymentId: 'pay_independent',
+    status: 'paid',
+    amount: 12345,
+    provider: 'mock',
+    orderNumber: 'ORD-INDEPENDENT',
+  })
+  clearMockPaymentStore()
+})
+
+test('README documents the server-cart architecture, not removed local stores', async () => {
+  const readFile = await import('node:fs/promises')
+  const readme = await readFile.readFile(
+    new URL('../README.md', import.meta.url),
+    'utf8',
+  )
+
+  assert.match(readme, /Server-authoritative cart/i)
+  assert.match(readme, /commerce\.cart\.\*/)
+  assert.match(readme, /HttpOnly cart cookie/i)
+  assert.match(readme, /cartToken/)
+  assert.match(
+    readme,
+    /client\s+JavaScript receives rendered cart views but never owns the authoritative cart\s+or token/i,
+  )
+  assert.match(
+    readme,
+    /no cart contents are persisted in localStorage/i,
+  )
+  assert.match(readme, /orders\.checkout\(\{ cartId \}\)/)
+  assert.match(readme, /orders\.getByPaymentId/i)
+  assert.match(
+    readme,
+    /mock adapter emulates the server cart and checkout flow in memory/i,
+  )
+  assert.match(readme, /zero-backend demos/i)
+  assert.match(readme, /\/api\/checkout\/payment-return/)
+  assert.match(readme, /tampered redirect amount/i)
+  assert.match(readme, /PG-verified amount/i)
+  assert.match(readme, /Success-page\s+reconciliation/i)
+  assert.match(readme, /orders\.confirmPayment/i)
+  const removedLocalCartText = new RegExp(
+    ['Local persisted cart', ' with Zustand'].join(' state'),
+    'i',
+  )
+  const removedMockOrderIndex = new RegExp(
+    ['\\.mock', 'orders\\.json'].join('-'),
+    'i',
+  )
+  const removedSoftwareOrderIndex = new RegExp(
+    ['\\.software', 'orders\\.json'].join('-'),
+    'i',
+  )
+  const removedLegacyCheckoutCall = new RegExp(
+    ['orders', 'create'].join('\\.'),
+    'i',
+  )
+
+  assert.doesNotMatch(readme, removedLocalCartText)
+  assert.doesNotMatch(readme, removedMockOrderIndex)
+  assert.doesNotMatch(readme, removedSoftwareOrderIndex)
+  assert.doesNotMatch(readme, removedLegacyCheckoutCall)
+})
+
+test('software adapter maps SDK product detail responses into storefront product detail', () => {
+  const detail = mapSoftwareProductDetail({
+    product: {
+      id: 42,
+      slug: 'linen-bag',
+      title: 'Linen Bag',
+      description: 'Everyday carry',
+      status: 'published',
+    },
+    images: [{ url: '/media/bag.jpg', alt: 'Bag', width: 800, height: 1000 }],
+    options: [
+      {
+        id: 'color',
+        slug: 'color',
+        title: 'Color',
+        values: [{ id: 'natural', slug: 'natural', value: 'Natural' }],
+      },
+    ],
+    variants: [
+      {
+        id: 100,
+        product: 42,
+        displayName: 'Natural',
+        price: 49000,
+        stock: 5,
+        reservedStock: 1,
+        isUnlimited: false,
+        optionValues: [
+          {
+            optionId: 'color',
+            value: { id: 'natural', slug: 'natural', value: 'Natural' },
+          },
+        ],
+        images: [{ url: '/media/bag-natural.jpg', alt: 'Natural bag' }],
+      },
+    ],
+  })
+
+  assert.equal(detail.product.id, '42')
+  assert.equal(detail.product.thumbnail?.url, '/media/bag.jpg')
+  assert.equal(detail.variants[0]?.id, '100')
+  assert.equal(detail.variants[0]?.price, 49000)
+  assert.equal(detail.variants[0]?.optionValues[0]?.valueSlug, 'natural')
+})
+
+test('software adapter unwraps SDK product detail result before mapping', () => {
+  const detail = mapSoftwareProductDetailResult({
+    found: true,
+    product: {
+      product: {
+        id: 'prod-1',
+        slug: 'daily-mug',
+        title: 'Daily Mug',
+        status: 'published',
+      },
+      variants: [],
+      options: [],
+      images: [],
+    },
+  })
+
+  assert.equal(detail?.product.slug, 'daily-mug')
+  assert.equal(
+    mapSoftwareProductDetailResult({ found: false, reason: 'not_found' }),
+    null,
+  )
+})
+
+test('software adapter requires SDK publishable and secret keys', () => {
+  assert.throws(
+    () =>
+      getSoftwareCommerceConfig({
+        NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY: 'pk_test',
+      }),
+    /SOFTWARE_SECRET_KEY/,
+  )
+
+  assert.deepEqual(
+    getSoftwareCommerceConfig({
+      NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY: 'pk_test',
+      SOFTWARE_SECRET_KEY: 'sk_test',
+      SOFTWARE_API_URL: 'https://console.example.test',
+      SOFTWARE_SHIPPING_AMOUNT: '2500',
+      SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT: '50000',
+    }),
+    {
+      publishableKey: 'pk_test',
+      secretKey: 'sk_test',
+      apiUrl: 'https://console.example.test',
+      shippingPolicy: {
+        currency: 'KRW',
+        baseAmount: 2500,
+        freeAboveAmount: 50000,
+      },
+    },
+  )
+})
+
+// scaffold:provider:tosspayments:start
+test('tosspayments adapter requires secret and client keys', () => {
+  assert.throws(
+    () =>
+      getTossPaymentsConfig({
+        TOSSPAYMENTS_SECRET_KEY: 'test_sk',
+      }),
+    /NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY/,
+  )
+
+  assert.deepEqual(
+    getTossPaymentsConfig({
+      TOSSPAYMENTS_SECRET_KEY: 'test_sk',
+      NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY: 'test_ck',
+      NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY: 'customer_1',
+      TOSSPAYMENTS_API_BASE_URL: 'https://api.example.test/v1/',
+    }),
+    {
+      secretKey: 'test_sk',
+      clientKey: 'test_ck',
+      customerKey: 'customer_1',
+      apiBaseUrl: 'https://api.example.test/v1',
+      webhookSecret: undefined,
+      // Default-allow only outside production (NODE_ENV unset here).
+      allowUnsignedWebhooks: true,
+    },
+  )
+
+  // Production without a webhook secret (and without an explicit opt-in) fails
+  // closed — parity with PortOne's signed-webhook enforcement (#1544 / I6).
+  assert.throws(
+    () =>
+      getTossPaymentsConfig({
+        NODE_ENV: 'production',
+        TOSSPAYMENTS_SECRET_KEY: 'test_sk',
+        NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY: 'test_ck',
+      }),
+    /TOSSPAYMENTS_WEBHOOK_SECRET/,
+  )
+
+  assert.equal(
+    getTossPaymentsConfig({
+      NODE_ENV: 'production',
+      TOSSPAYMENTS_SECRET_KEY: 'test_sk',
+      NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY: 'test_ck',
+      TOSSPAYMENTS_ALLOW_UNSIGNED_WEBHOOKS: 'true',
+    }).allowUnsignedWebhooks,
+    true,
+  )
+})
+
+test('tosspayments adapter confirms payment through official REST API', async () => {
+  const originalFetch = globalThis.fetch
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_API_BASE_URL: process.env.TOSSPAYMENTS_API_BASE_URL,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  process.env.TOSSPAYMENTS_API_BASE_URL = 'https://api.example.test/v1'
+
+  let requestCount = 0
+  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+    requestCount += 1
+    assert.equal(String(input), 'https://api.example.test/v1/payments/confirm')
+    assert.equal(init?.method, 'POST')
+    assert.equal(
+      new Headers(init?.headers).get('Authorization'),
+      `Basic ${Buffer.from('test_sk:').toString('base64')}`,
+    )
+    assert.equal(
+      new Headers(init?.headers).get('Content-Type'),
+      'application/json',
+    )
+    assert.deepEqual(JSON.parse(String(init?.body)), {
+      paymentKey: 'payment_key_1',
+      orderId: 'pay_1',
+      amount: 99000,
+    })
+
+    return new Response(
+      JSON.stringify({
+        paymentKey: 'payment_key_1',
+        orderId: 'pay_1',
+        status: 'DONE',
+        totalAmount: 99000,
+      }),
+      {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      },
+    )
+  }
+
+  try {
+    const payment = createTossPaymentsProvider()
+    assert.deepEqual(
+      await payment.confirmPayment({
+        paymentId: 'pay_1',
+        providerPaymentId: 'payment_key_1',
+        amount: 99000,
+      }),
+      {
+        paymentId: 'pay_1',
+        status: 'paid',
+        amount: 99000,
+        provider: 'tosspayments',
+      },
+    )
+    assert.equal(requestCount, 1)
+  } finally {
+    globalThis.fetch = originalFetch
+    restoreEnv(previousEnv)
+  }
+})
+
+test('tosspayments adapter looks up payment status through official REST API', async () => {
+  const originalFetch = globalThis.fetch
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_API_BASE_URL: process.env.TOSSPAYMENTS_API_BASE_URL,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  process.env.TOSSPAYMENTS_API_BASE_URL = 'https://api.example.test/v1'
+
+  let requestCount = 0
+  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+    requestCount += 1
+    assert.equal(
+      String(input),
+      'https://api.example.test/v1/payments/orders/pay_1',
+    )
+    assert.equal(
+      new Headers(init?.headers).get('Authorization'),
+      `Basic ${Buffer.from('test_sk:').toString('base64')}`,
+    )
+
+    return new Response(
+      JSON.stringify({
+        paymentKey: 'payment_key_1',
+        orderId: 'pay_1',
+        status: 'DONE',
+        totalAmount: 99000,
+      }),
+      {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      },
+    )
+  }
+
+  try {
+    const payment = createTossPaymentsProvider()
+    assert.deepEqual(await payment.getPayment('pay_1'), {
+      paymentId: 'pay_1',
+      status: 'paid',
+      amount: 99000,
+      provider: 'tosspayments',
+    })
+    assert.equal(requestCount, 1)
+  } finally {
+    globalThis.fetch = originalFetch
+    restoreEnv(previousEnv)
+  }
+})
+
+test('tosspayments adapter maps partial cancellation as canceled', async () => {
+  const originalFetch = globalThis.fetch
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_API_BASE_URL: process.env.TOSSPAYMENTS_API_BASE_URL,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  process.env.TOSSPAYMENTS_API_BASE_URL = 'https://api.example.test/v1'
+
+  globalThis.fetch = async () =>
+    new Response(
+      JSON.stringify({
+        orderId: 'pay_1',
+        status: 'PARTIAL_CANCELED',
+        totalAmount: 99000,
+      }),
+      {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      },
+    )
+
+  try {
+    const payment = createTossPaymentsProvider()
+    assert.deepEqual(await payment.getPayment('pay_1'), {
+      paymentId: 'pay_1',
+      status: 'canceled',
+      amount: 99000,
+      provider: 'tosspayments',
+    })
+  } finally {
+    globalThis.fetch = originalFetch
+    restoreEnv(previousEnv)
+  }
+})
+
+test('tosspayments webhook event id falls back to payment-specific keys', async () => {
+  const originalFetch = globalThis.fetch
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_API_BASE_URL: process.env.TOSSPAYMENTS_API_BASE_URL,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  process.env.TOSSPAYMENTS_API_BASE_URL = 'https://api.example.test/v1'
+
+  // verifyWebhook now performs an authoritative server re-fetch (verify-then-
+  // server-refetch parity with PortOne, #1544 / I6), so a lookup must resolve.
+  const lookups: string[] = []
+  globalThis.fetch = async (input: RequestInfo | URL) => {
+    lookups.push(String(input))
+    return new Response(
+      JSON.stringify({ orderId: 'pay_1', status: 'DONE', totalAmount: 99000 }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } },
+    )
+  }
+
+  try {
+    const payment = createTossPaymentsProvider()
+    assert.deepEqual(
+      await payment.verifyWebhook(
+        new Request('https://example.test/webhook', {
+          method: 'POST',
+          body: JSON.stringify({
+            eventType: 'PAYMENT_STATUS_CHANGED',
+            data: {
+              orderId: 'pay_1',
+              paymentKey: 'payment_key_1',
+            },
+          }),
+        }),
+      ),
+      {
+        type: 'payment.updated',
+        paymentId: 'pay_1',
+        eventId: 'payment_key_1',
+      },
+    )
+    // The webhook trusted a server re-fetch, not the request body.
+    assert.deepEqual(lookups, [
+      'https://api.example.test/v1/payments/orders/pay_1',
+    ])
+
+    assert.deepEqual(
+      await payment.verifyWebhook(
+        new Request('https://example.test/webhook', {
+          method: 'POST',
+          body: JSON.stringify({
+            eventType: 'PAYMENT_STATUS_CHANGED',
+            data: {
+              orderId: 'pay_2',
+            },
+          }),
+        }),
+      ),
+      {
+        type: 'payment.updated',
+        paymentId: 'pay_2',
+        eventId: 'PAYMENT_STATUS_CHANGED:pay_2',
+      },
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+    restoreEnv(previousEnv)
+  }
+})
+
+test('tosspayments webhook rejects an unsigned delivery outside development', () => {
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_WEBHOOK_SECRET: process.env.TOSSPAYMENTS_WEBHOOK_SECRET,
+    NODE_ENV: process.env.NODE_ENV,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  delete process.env.TOSSPAYMENTS_WEBHOOK_SECRET
+  ;(process.env as Record<string, string | undefined>).NODE_ENV = 'production'
+
+  try {
+    assert.throws(
+      () => createTossPaymentsProvider(),
+      /TOSSPAYMENTS_WEBHOOK_SECRET/,
+    )
+  } finally {
+    restoreEnv(previousEnv)
+  }
+})
+
+test('tosspayments webhook verifies a configured HMAC signature', async () => {
+  const originalFetch = globalThis.fetch
+  const previousEnv = {
+    TOSSPAYMENTS_SECRET_KEY: process.env.TOSSPAYMENTS_SECRET_KEY,
+    NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY:
+      process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY,
+    TOSSPAYMENTS_WEBHOOK_SECRET: process.env.TOSSPAYMENTS_WEBHOOK_SECRET,
+    TOSSPAYMENTS_API_BASE_URL: process.env.TOSSPAYMENTS_API_BASE_URL,
+    NODE_ENV: process.env.NODE_ENV,
+  }
+
+  process.env.TOSSPAYMENTS_SECRET_KEY = 'test_sk'
+  process.env.NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY = 'test_ck'
+  process.env.TOSSPAYMENTS_WEBHOOK_SECRET = 'whsec_test'
+  process.env.TOSSPAYMENTS_API_BASE_URL = 'https://api.example.test/v1'
+  ;(process.env as Record<string, string | undefined>).NODE_ENV = 'production'
+
+  globalThis.fetch = async () =>
+    new Response(
+      JSON.stringify({ orderId: 'pay_1', status: 'DONE', totalAmount: 99000 }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } },
+    )
+
+  const rawBody = JSON.stringify({
+    eventType: 'PAYMENT_STATUS_CHANGED',
+    data: { orderId: 'pay_1', paymentKey: 'payment_key_1' },
+  })
+  const timestamp = String(Math.floor(Date.now() / 1000))
+  const signature = createHmac('sha256', 'whsec_test')
+    .update(`${timestamp}.${rawBody}`)
+    .digest('base64')
+
+  try {
+    const payment = createTossPaymentsProvider()
+
+    // A valid signature is accepted.
+    assert.deepEqual(
+      await payment.verifyWebhook(
+        new Request('https://example.test/webhook', {
+          method: 'POST',
+          headers: {
+            'Toss-Signature': signature,
+            'Toss-Timestamp': timestamp,
+          },
+          body: rawBody,
+        }),
+      ),
+      {
+        type: 'payment.updated',
+        paymentId: 'pay_1',
+        eventId: 'payment_key_1',
+      },
+    )
+
+    // A tampered signature is rejected before any re-fetch.
+    await assert.rejects(
+      payment.verifyWebhook(
+        new Request('https://example.test/webhook', {
+          method: 'POST',
+          headers: {
+            'Toss-Signature': 'not-the-signature',
+            'Toss-Timestamp': timestamp,
+          },
+          body: rawBody,
+        }),
+      ),
+      /signature/,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+    restoreEnv(previousEnv)
+  }
+})
+
+// scaffold:provider:tosspayments:end
+// scaffold:provider:portone:start
+test('portone adapter requires API secret and browser SDK public keys', () => {
+  assert.throws(
+    () => getPortOneConfig({ PORTONE_API_SECRET: 'secret' }),
+    /NEXT_PUBLIC_PORTONE_STORE_ID/,
+  )
+
+  assert.deepEqual(
+    getPortOneConfig({
+      PORTONE_API_SECRET: 'secret',
+      NEXT_PUBLIC_PORTONE_STORE_ID: 'store_test',
+      NEXT_PUBLIC_PORTONE_CHANNEL_KEY: 'channel_test',
+      NEXT_PUBLIC_PORTONE_PAY_METHOD: 'CARD',
+      PORTONE_WEBHOOK_SECRET: 'webhook_secret',
+    }),
+    {
+      apiSecret: 'secret',
+      storeId: 'store_test',
+      channelKey: 'channel_test',
+      payMethod: 'CARD',
+      webhookSecret: 'webhook_secret',
+      allowUnsignedWebhooks: true,
+    },
+  )
+
+  assert.throws(
+    () =>
+      getPortOneConfig({
+        NODE_ENV: 'production',
+        PORTONE_API_SECRET: 'secret',
+        NEXT_PUBLIC_PORTONE_STORE_ID: 'store_test',
+        NEXT_PUBLIC_PORTONE_CHANNEL_KEY: 'channel_test',
+      }),
+    /PORTONE_WEBHOOK_SECRET/,
+  )
+
+  assert.equal(
+    getPortOneConfig({
+      NODE_ENV: 'production',
+      PORTONE_API_SECRET: 'secret',
+      NEXT_PUBLIC_PORTONE_STORE_ID: 'store_test',
+      NEXT_PUBLIC_PORTONE_CHANNEL_KEY: 'channel_test',
+      PORTONE_ALLOW_UNSIGNED_WEBHOOKS: 'true',
+    }).allowUnsignedWebhooks,
+    true,
+  )
+})
+
+test('portone adapter returns browser SDK payload and maps server SDK payments', async () => {
+  const payment = createPortOnePaymentProviderForConfig(
+    {
+      apiSecret: 'secret',
+      storeId: 'store_test',
+      channelKey: 'channel_test',
+      payMethod: 'CARD',
+      allowUnsignedWebhooks: true,
+    },
+    {
+      async getPayment(options) {
+        assert.deepEqual(options, {
+          paymentId: 'pay_1',
+          storeId: 'store_test',
+        })
+        return {
+          id: 'pay_1',
+          status: 'PAID',
+          amount: {
+            total: 99000,
+            taxFree: 0,
+            discount: 0,
+            paid: 99000,
+            cancelled: 0,
+            cancelledTaxFree: 0,
+          },
+        } as never
+      },
+    },
+  )
+
+  assert.deepEqual(
+    await payment.requestPayment({
+      paymentId: 'pay_1',
+      orderNumber: 'ORD-1',
+      orderName: 'Daily Shirt',
+      amount: 99000,
+      currency: 'KRW',
+      customer: {
+        name: 'Ada',
+        email: 'ada@example.com',
+        phone: '01012345678',
+      },
+    }),
+    {
+      ok: true,
+      paymentId: 'pay_1',
+      clientPayment: {
+        provider: 'portone',
+        storeId: 'store_test',
+        channelKey: 'channel_test',
+        payMethod: 'CARD',
+        paymentId: 'pay_1',
+        orderNumber: 'ORD-1',
+        orderName: 'Daily Shirt',
+        amount: 99000,
+        currency: 'KRW',
+        customer: {
+          name: 'Ada',
+          email: 'ada@example.com',
+          phone: '01012345678',
+        },
+      },
+    },
+  )
+
+  assert.deepEqual(await payment.getPayment('pay_1'), {
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+    provider: 'portone',
+  })
+})
+
+test('portone adapter recovers orderNumber from payment customData', async () => {
+  const payment = createPortOnePaymentProviderForConfig(
+    {
+      apiSecret: 'secret',
+      storeId: 'store_test',
+      channelKey: 'channel_test',
+      payMethod: 'CARD',
+      allowUnsignedWebhooks: true,
+    },
+    {
+      async getPayment() {
+        return {
+          id: 'pay_1',
+          status: 'PAID',
+          amount: { total: 99000, paid: 99000 },
+          // PortOne serializes customData to a JSON string.
+          customData: JSON.stringify({ orderNumber: 'ORD-1' }),
+        } as never
+      },
+    },
+  )
+
+  assert.deepEqual(await payment.getPayment('pay_1'), {
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+    provider: 'portone',
+    orderNumber: 'ORD-1',
+  })
+})
+
+// scaffold:provider:portone:end
+// scaffold:provider:tosspayments:start
+function restoreEnv(values: Record<string, string | undefined>): void {
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      delete process.env[key]
+    } else {
+      process.env[key] = value
+    }
+  }
+}
+// scaffold:provider:tosspayments:end
+
+test('software adapter threads the SDK checkout → confirm round-trip', async () => {
+  const { client, calls, orderNumbers } = makeFakeSdkClient()
+  const provider = buildSoftwareCommerceProvider(Promise.resolve(client), {
+    currency: 'KRW',
+    baseAmount: 3000,
+  })
+
+  // Before placement, a by-payment lookup 404s and resolves to null.
+  assert.equal(
+    await provider.getOrderByPaymentId({
+      paymentId: 'pay_x',
+      provider: 'mock',
+    }),
+    null,
+  )
+
+  // Checkout converts the server cart into a pending order and mints the
+  // pgPaymentId template-side.
+  const pending = await provider.checkoutCart({
+    cartToken: 'tok_1',
+    customerSnapshot: { name: 'Ada', email: 'ada@example.com', phone: '010' },
+    shippingAddress: {
+      recipientName: 'Ada',
+      phone: '010',
+      postalCode: '04524',
+      address: 'Seoul',
+      detailAddress: '101',
+      deliveryMessage: '',
+    },
+  })
+  const orderNumber = pending.order.orderNumber
+  assert.equal(pending.order.displayStatus, 'pending')
+  assert.equal(pending.amount, 53000)
+  assert.match(pending.paymentId, /^pay_/)
+  // The buyer address is passed to checkout with the cart capability token so
+  // Console can persist context and price shipping atomically.
+  assert.ok(calls.includes(`checkout:cart_1:tok_1:04524:${orderNumber}`))
+  assert.equal(orderNumbers[0], orderNumber)
+
+  // Confirm with the minted payment id + provider-verified amount → placed paid
+  // order.
+  const paid = await provider.confirmOrderPayment({
+    paymentId: pending.paymentId,
+    orderNumber,
+    provider: 'mock',
+    amount: pending.amount,
+  })
+  assert.equal(paid.displayStatus, 'paid')
+  assert.equal(paid.transactions[0]?.status, 'paid')
+  assert.equal(paid.transactions[0]?.amount, 53000)
+  assert.ok(calls.includes(`confirm:${orderNumber}:${pending.paymentId}:53000`))
+
+  // The placed order is now resolvable by PG payment id (idempotency key).
+  const resolved = await provider.getOrderByPaymentId({
+    paymentId: pending.paymentId,
+    provider: 'mock',
+  })
+  assert.equal(resolved?.displayStatus, 'paid')
+  assert.equal(resolved?.orderNumber, orderNumber)
+})
+
+function makeFakeSdkClient(): {
+  client: SoftwareSdkClientLike
+  calls: string[]
+  orderNumbers: string[]
+} {
+  const calls: string[] = []
+  const orderNumbers: string[] = []
+  const placed = new Map<
+    string,
+    { order: Record<string, unknown>; transaction: Record<string, unknown> }
+  >()
+
+  const cart = {
+    id: 'cart_1',
+    currency: 'KRW',
+    subtotalAmount: 50000,
+    shippingAmount: 3000,
+    totalAmount: 53000,
+    items: [
+      {
+        id: 'ci_1',
+        product: 'prod-1',
+        variant: 'var-1',
+        quantity: 1,
+        unitPrice: 50000,
+        discountedTotalPrice: 50000,
+      },
+    ],
+  }
+
+  const client: SoftwareSdkClientLike = {
+    collections: {
+      from: (slug) => ({
+        async find() {
+          return { docs: [] }
+        },
+      }),
+    },
+    commerce: {
+      product: {
+        async detail() {
+          return { found: false }
+        },
+        async stockCheck() {
+          return { allAvailable: true, results: [] }
+        },
+      },
+      cart: {
+        async create() {
+          return { cartToken: 'tok_1' }
+        },
+        async get() {
+          return cart
+        },
+        async addItem() {
+          return {}
+        },
+        async updateItem() {
+          return {}
+        },
+        async removeItem() {
+          return {}
+        },
+        async clear() {
+          return {}
+        },
+      },
+      orders: {
+        async checkout(params) {
+          calls.push(
+            `checkout:${params.cartId}:${params.cartToken}:${params.shippingAddress?.postalCode}:${params.orderNumber}`,
+          )
+          orderNumbers.push(params.orderNumber)
+          return {
+            id: 'ord_pending',
+            orderNumber: params.orderNumber,
+            displayFinancialStatus: 'pending',
+            totalAmount: cart.totalAmount,
+            subtotalAmount: cart.subtotalAmount,
+            shippingAmount: cart.shippingAmount,
+            customerSnapshot: params.customerSnapshot,
+            items: [
+              {
+                variant: 'var-1',
+                productTitle: 'Daily Shirt',
+                quantity: 1,
+                unitPrice: 50000,
+                totalPrice: 50000,
+              },
+            ],
+          }
+        },
+        async confirmPaymentReturningOrder(params) {
+          calls.push(
+            `confirm:${params.orderNumber}:${params.pgPaymentId}:${params.amount}`,
+          )
+          const result = {
+            order: {
+              id: 'ord_1',
+              orderNumber: params.orderNumber,
+              displayFinancialStatus: 'paid',
+              totalAmount: params.amount,
+              items: [],
+            },
+            transaction: {
+              pgPaymentId: params.pgPaymentId,
+              pgProvider: params.pgProvider,
+              status: 'paid',
+              amount: params.amount,
+            },
+          }
+          placed.set(params.pgPaymentId, result)
+          return result
+        },
+        async getByPaymentId(params) {
+          const found = placed.get(params.pgPaymentId)
+          if (!found) {
+            const error = new Error('not found') as Error & { status: number }
+            error.status = 404
+            throw error
+          }
+          return found
+        },
+        async updateTransaction() {
+          return {}
+        },
+        async cancelOrder() {
+          return {}
+        },
+      },
+    },
+  }
+
+  return { client, calls, orderNumbers }
+}
+
+function makePendingOrder(input: { totalAmount: number }): Order {
+  return {
+    id: 'order_1',
+    orderNumber: 'ORD-1',
+    displayStatus: 'pending',
+    items: [],
+    customerSnapshot: {
+      name: 'Ada',
+      email: 'ada@example.com',
+      phone: '010-0000-0000',
+    },
+    shippingAddress: {
+      recipientName: 'Ada',
+      phone: '010-0000-0000',
+      postalCode: '04524',
+      address: 'Seoul',
+      detailAddress: '101',
+      deliveryMessage: '',
+    },
+    subtotalAmount: input.totalAmount,
+    shippingAmount: 0,
+    totalAmount: input.totalAmount,
+    transactions: [
+      {
+        paymentId: 'pay_1',
+        provider: 'mock',
+        status: 'pending',
+        amount: input.totalAmount,
+      },
+    ],
+  }
+}
+
+type FakeCommerceProvider = CommerceProvider & {
+  confirmed: boolean
+  confirmedAmount: number | null
+}
+
+function makeCommerceProvider(order: Order | null): FakeCommerceProvider {
+  const emptyCart = {
+    id: 'cart_1',
+    currency: 'KRW',
+    subtotalAmount: 0,
+    shippingAmount: 0,
+    discountAmount: 0,
+    totalAmount: 0,
+    items: [],
+  }
+  return {
+    confirmed: false,
+    confirmedAmount: null,
+    async listProducts() {
+      return { products: [], total: 0 }
+    },
+    async getProductBySlug() {
+      return null
+    },
+    async getVariantsByIds() {
+      return []
+    },
+    async getShippingPolicy() {
+      return { currency: 'KRW', baseAmount: 0 }
+    },
+    async checkStock() {
+      return { ok: true, lines: [] }
+    },
+    async createCart() {
+      return { cartToken: 'tok_1' }
+    },
+    async getCart() {
+      return emptyCart
+    },
+    async addCartItem() {
+      return emptyCart
+    },
+    async updateCartItem() {
+      return emptyCart
+    },
+    async removeCartItem() {
+      return emptyCart
+    },
+    async clearCart() {
+      return emptyCart
+    },
+    async checkoutCart() {
+      throw new Error('not used')
+    },
+    async getOrderByPaymentId({ paymentId }) {
+      return order && paymentId === 'pay_1' ? order : null
+    },
+    async confirmOrderPayment(input) {
+      this.confirmed = true
+      this.confirmedAmount = input.amount
+      return {
+        ...(order ?? makePendingOrder({ totalAmount: input.amount })),
+        displayStatus: 'paid',
+      }
+    },
+    async markPaymentFailed() {
+      return order
+    },
+    async cancelPendingOrder() {
+      return order ? { ...order, displayStatus: 'canceled' } : null
+    },
+  }
+}
+
+function makePaymentProvider(
+  payment: Awaited<ReturnType<PaymentProvider['getPayment']>>,
+): PaymentProvider {
+  return {
+    provider: payment?.provider ?? 'mock',
+    async requestPayment() {
+      return { ok: true, paymentId: payment?.paymentId ?? 'pay_1' }
+    },
+    async getPayment() {
+      return payment
+    },
+    async confirmPayment() {
+      if (!payment) throw new Error('missing payment')
+      return payment
+    },
+    async verifyWebhook() {
+      return {
+        type: 'payment.updated',
+        paymentId: payment?.paymentId ?? 'pay_1',
+        eventId: 'evt_1',
+      }
+    },
+  }
+}
+
+function clearMockPaymentStore(): void {
+  if (existsSync(mockPaymentStorePath)) {
+    rmSync(mockPaymentStorePath)
+  }
+}
+
+// ── #1544 / I6: payment lifecycle hardening ──
+
+test('assertAmountEquals passes when amounts (and currencies) match', () => {
+  assert.doesNotThrow(() =>
+    assertAmountEquals({ context: 'unit', expected: 99000, actual: 99000 }),
+  )
+  assert.doesNotThrow(() =>
+    assertAmountEquals({
+      context: 'unit',
+      expected: 99000,
+      actual: 99000,
+      expectedCurrency: 'KRW',
+      actualCurrency: 'KRW',
+    }),
+  )
+})
+
+test('assertAmountEquals throws AmountMismatchError on any mismatch', () => {
+  assert.throws(
+    () =>
+      assertAmountEquals({ context: 'unit', expected: 99000, actual: 9000 }),
+    (error: unknown) =>
+      error instanceof AmountMismatchError && error.code === 'amount_mismatch',
+  )
+  // Non-finite fails closed.
+  assert.throws(
+    () =>
+      assertAmountEquals({
+        context: 'unit',
+        expected: 99000,
+        actual: Number.NaN,
+      }),
+    AmountMismatchError,
+  )
+  // Currency mismatch even when the numeric amount matches.
+  assert.throws(
+    () =>
+      assertAmountEquals({
+        context: 'unit',
+        expected: 99000,
+        actual: 99000,
+        expectedCurrency: 'KRW',
+        actualCurrency: 'USD',
+      }),
+    AmountMismatchError,
+  )
+})
+
+test('syncOrderPayment recovers the orderNumber from the PG payment on a webhook with none', async () => {
+  const commerce = makeCommerceProvider(null)
+  const payment = makePaymentProvider({
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+    provider: 'mock',
+    orderNumber: 'ORD-1',
+  })
+
+  const result = await syncOrderPayment({
+    paymentId: 'pay_1',
+    providerEventId: 'evt_1',
+    // No orderNumber: the webhook path recovers it from the PG re-fetch.
+    commerceProvider: commerce,
+    paymentProvider: payment,
+  })
+
+  assert.equal(result.status, 'paid')
+  assert.equal(commerce.confirmed, true)
+  assert.equal(commerce.confirmedAmount, 99000)
+})
+
+test('syncOrderPayment amount gate rejects a PG amount that differs from the placed order', async () => {
+  const order = makePendingOrder({ totalAmount: 50000 })
+  const commerce = makeCommerceProvider(order)
+  const payment = makePaymentProvider({
+    paymentId: 'pay_1',
+    status: 'paid',
+    amount: 99000,
+    provider: 'mock',
+  })
+
+  await assert.rejects(
+    syncOrderPayment({
+      paymentId: 'pay_1',
+      orderNumber: 'ORD-1',
+      commerceProvider: commerce,
+      paymentProvider: payment,
+    }),
+    AmountMismatchError,
+  )
+  assert.equal(commerce.confirmed, false)
+})
+
+test('server-only guards are present on runtime-bearing modules', () => {
+  const guarded = [
+    'lib/payment/provider.server.ts',
+    'lib/payment/sync-order-payment.ts',
+    'lib/payment/adapters/mock.ts',
+    'lib/commerce/provider.server.ts',
+    'lib/commerce/adapters/software.ts',
+    'lib/cart/select-provider.ts',
+    'lib/checkout/start-checkout.ts',
+    // scaffold:customer:start
+    'lib/customer/session.ts',
+    'lib/customer/client.server.ts',
+    'lib/customer/auth-actions.ts',
+    'lib/customer/current-customer.ts',
+    // scaffold:customer:end
+    // scaffold:provider:portone:start
+    'lib/payment/adapters/portone.ts',
+    // scaffold:provider:portone:end
+    // scaffold:provider:tosspayments:start
+    'lib/payment/adapters/tosspayments.ts',
+    // scaffold:provider:tosspayments:end
+  ]
+  for (const rel of guarded) {
+    const source = readFileSync(join(process.cwd(), rel), 'utf8')
+    assert.match(
+      source,
+      /server-only-guard/,
+      `${rel} must import the server-only guard`,
+    )
+  }
+})
+
+// Cross-PG parity: each adapter is checked against the SAME security contract,
+// so a fix can never land on one fork only. The registry entries are guarded by
+// scaffold markers, so a scaffolded single-provider app keeps exactly one entry
+// and still asserts the shared contract.
+type ParityProviderCase = {
+  id: string
+  // Minimal valid creds WITHOUT a webhook secret, for the signed-webhook gate.
+  credsWithoutWebhookSecret: Record<string, string | undefined>
+  configFromEnv: (env: Record<string, string | undefined>) => {
+    allowUnsignedWebhooks: boolean
+  }
+}
+
+const PARITY_PROVIDERS: ParityProviderCase[] = [
+  // scaffold:provider:portone:start
+  {
+    id: 'portone',
+    credsWithoutWebhookSecret: {
+      PORTONE_API_SECRET: 'secret',
+      NEXT_PUBLIC_PORTONE_STORE_ID: 'store_test',
+      NEXT_PUBLIC_PORTONE_CHANNEL_KEY: 'channel_test',
+    },
+    configFromEnv: getPortOneConfig,
+  },
+  // scaffold:provider:portone:end
+  // scaffold:provider:tosspayments:start
+  {
+    id: 'tosspayments',
+    credsWithoutWebhookSecret: {
+      TOSSPAYMENTS_SECRET_KEY: 'test_sk',
+      NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY: 'test_ck',
+    },
+    configFromEnv: getTossPaymentsConfig,
+  },
+  // scaffold:provider:tosspayments:end
+]
+
+for (const pg of PARITY_PROVIDERS) {
+  test(`cross-PG parity: ${pg.id} enforces signed webhooks outside development`, () => {
+    // Default-allow only inside local development.
+    assert.equal(
+      pg.configFromEnv({ ...pg.credsWithoutWebhookSecret })
+        .allowUnsignedWebhooks,
+      true,
+    )
+    // No default-allow-unsigned outside development.
+    assert.throws(
+      () =>
+        pg.configFromEnv({
+          ...pg.credsWithoutWebhookSecret,
+          NODE_ENV: 'production',
+        }),
+      /WEBHOOK_SECRET/,
+    )
+  })
+}