@open-mercato/checkout 0.6.8-develop.6963.1.04a6d320e9 → 0.6.8-develop.6964.1.36b364cfd8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/checkout",
-  "version": "0.6.8-develop.6963.1.04a6d320e9",
+  "version": "0.6.8-develop.6964.1.36b364cfd8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -62,18 +62,18 @@
     }
   },
   "dependencies": {
-    "@open-mercato/core": "0.6.8-develop.6963.1.04a6d320e9",
-    "@open-mercato/ui": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/core": "0.6.8-develop.6964.1.36b364cfd8",
+    "@open-mercato/ui": "0.6.8-develop.6964.1.36b364cfd8",
     "bcryptjs": "^3.0.3"
   },
   "peerDependencies": {
     "@mikro-orm/postgresql": "^7.0.14",
-    "@open-mercato/shared": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/shared": "0.6.8-develop.6964.1.36b364cfd8",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/shared": "0.6.8-develop.6964.1.36b364cfd8",
     "@types/jest": "^30.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",

package/src/modules/checkout/api/pay/[slug]/route.ts

@@ -2,12 +2,10 @@ import { NextResponse } from 'next/server'
 import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
-import { checkRateLimit } from '@open-mercato/shared/lib/ratelimit/helpers'
 import { CheckoutLink } from '../../../data/entities'
 import { CHECKOUT_ENTITY_IDS } from '../../../lib/constants'
 import { resolveCheckoutPublicCustomFields } from '../../../lib/customFields'
-import { buildCheckoutRateLimitKey, checkoutPublicViewRateLimitConfig } from '../../../lib/rateLimiter'
+import { checkoutPublicViewRateLimitConfig, enforceCheckoutRateLimit } from '../../../lib/rateLimiter'
 import { handleCheckoutRouteError, readCheckoutAccessCookie, requirePreviewContext } from '../../helpers'
 import {
   isCheckoutLinkPublic,
@@ -30,14 +28,16 @@ export async function GET(req: Request, { params }: { params: Promise<{ slug: st
     const container = await createRequestContainer()
     if (previewRequested) await requirePreviewContext(req)
     if (!previewRequested) {
-      try {
-        const rateLimiter = container.resolve('rateLimiterService') as RateLimiterService
-        const key = buildCheckoutRateLimitKey(req, rateLimiter, 'checkout-public-view')
-        const rateLimitResponse = await checkRateLimit(rateLimiter, checkoutPublicViewRateLimitConfig, key, 'Too many checkout page requests. Please try again later.')
-        if (rateLimitResponse) return rateLimitResponse
-      } catch {
-        // Rate limiting is fail-open
-      }
+      // Fail-open: this endpoint is read-only.
+      const rateLimitResponse = await enforceCheckoutRateLimit({
+        req,
+        container,
+        config: checkoutPublicViewRateLimitConfig,
+        namespace: 'checkout-public-view',
+        errorMessage: 'Too many checkout page requests. Please try again later.',
+        posture: 'fail-open',
+      })
+      if (rateLimitResponse) return rateLimitResponse
     }
     const em = container.resolve('em')
     const link = await findOneWithDecryption(em, CheckoutLink, {

package/src/modules/checkout/api/pay/[slug]/status/[transactionId]/route.ts

@@ -1,11 +1,9 @@
 import { NextResponse } from 'next/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
-import { checkRateLimit } from '@open-mercato/shared/lib/ratelimit/helpers'
 import type { PaymentGatewayService } from '@open-mercato/core/modules/payment_gateways/lib/gateway-service'
 import { CheckoutLink, CheckoutTransaction } from '../../../../../data/entities'
-import { buildCheckoutRateLimitKey, checkoutStatusRateLimitConfig } from '../../../../../lib/rateLimiter'
+import { checkoutStatusRateLimitConfig, enforceCheckoutRateLimit } from '../../../../../lib/rateLimiter'
 import { handleCheckoutRouteError, requireCheckoutPasswordSession } from '../../../../helpers'
 import { checkoutTag } from '../../../../openapi'
 
@@ -18,14 +16,16 @@ export async function GET(req: Request, { params }: { params: Promise<{ slug: st
   try {
     const resolvedParams = await params
     const container = await createRequestContainer()
-    try {
-      const rateLimiter = container.resolve('rateLimiterService') as RateLimiterService
-      const key = buildCheckoutRateLimitKey(req, rateLimiter, 'checkout-status')
-      const rateLimitResponse = await checkRateLimit(rateLimiter, checkoutStatusRateLimitConfig, key, 'Too many checkout status requests. Please try again later.')
-      if (rateLimitResponse) return rateLimitResponse
-    } catch {
-      // Rate limiting is fail-open
-    }
+    // Fail-open: this endpoint is read-only.
+    const rateLimitResponse = await enforceCheckoutRateLimit({
+      req,
+      container,
+      config: checkoutStatusRateLimitConfig,
+      namespace: 'checkout-status',
+      errorMessage: 'Too many checkout status requests. Please try again later.',
+      posture: 'fail-open',
+    })
+    if (rateLimitResponse) return rateLimitResponse
     const em = container.resolve('em')
     const paymentGatewayService = container.resolve('paymentGatewayService') as PaymentGatewayService
     const link = await findOneWithDecryption(em, CheckoutLink, {

package/src/modules/checkout/api/pay/[slug]/submit/__tests__/route.test.ts

@@ -26,6 +26,7 @@ jest.mock('@open-mercato/shared/lib/ratelimit/helpers', () => ({
   checkRateLimit: jest.fn(),
   getClientIp: jest.fn(),
   RATE_LIMIT_FALLBACK_KEY: 'global',
+  RATE_LIMIT_UNAVAILABLE_FALLBACK: 'Service temporarily unavailable. Please try again later.',
 }))
 
 jest.mock('../../../../../events', () => ({
@@ -375,4 +376,102 @@ describe('POST /api/checkout/pay/[slug]/submit', () => {
     const payload = await response.json()
     expect(payload.transactionId).toBe(TRANSACTION_ID)
   })
+
+  describe('rate limiting is fail-closed', () => {
+    function submitRequest() {
+      return POST(
+        new Request('https://merchant.example/api/checkout/pay/donate/submit', {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'Idempotency-Key': 'rate-limit-key1',
+            origin: 'https://merchant.example',
+          },
+          body: JSON.stringify({ customerData: {}, acceptedLegalConsents: {}, amount: 1 }),
+        }),
+        { params: { slug: 'donate' } },
+      )
+    }
+
+    it('asks the limiter to fail closed', async () => {
+      ;(findOneWithDecryption as jest.Mock).mockResolvedValue(createLink())
+
+      await submitRequest()
+
+      expect(checkRateLimit).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        expect.any(String),
+        expect.any(String),
+        expect.objectContaining({ failClosed: true }),
+      )
+    })
+
+    it('returns 503 without creating a payment session when the limiter cannot decide', async () => {
+      ;(findOneWithDecryption as jest.Mock).mockResolvedValue(createLink())
+      ;(checkRateLimit as jest.Mock).mockRejectedValue(new Error('backing store unreachable'))
+
+      const response = await submitRequest()
+
+      expect(response.status).toBe(503)
+      expect(await response.json()).toEqual({
+        error: 'Service temporarily unavailable. Please try again later.',
+      })
+      expect(mockCreatePaymentSession).not.toHaveBeenCalled()
+      expect(mockCommandExecute).not.toHaveBeenCalled()
+    })
+
+    it('passes a 503 the limiter itself produced straight through', async () => {
+      ;(findOneWithDecryption as jest.Mock).mockResolvedValue(createLink())
+      ;(checkRateLimit as jest.Mock).mockResolvedValue(
+        new Response(JSON.stringify({ error: 'unavailable' }), { status: 503 }),
+      )
+
+      const response = await submitRequest()
+
+      expect(response.status).toBe(503)
+      expect(mockCreatePaymentSession).not.toHaveBeenCalled()
+      expect(mockCommandExecute).not.toHaveBeenCalled()
+    })
+
+    // A rate limiter that is not registered at all is a configuration error, not a
+    // transient outage: the request is served (as it was before rate limiting was made
+    // fail-closed) instead of being rejected as "temporarily unavailable" indefinitely.
+    it('serves the request when no rate limiter is registered', async () => {
+      ;(findOneWithDecryption as jest.Mock)
+        .mockResolvedValueOnce(createLink())
+        .mockResolvedValueOnce(createTransaction())
+        .mockResolvedValueOnce(createTransaction())
+        .mockResolvedValueOnce(createTransaction({ gatewayTransactionId: GATEWAY_TRANSACTION_ID }))
+      ;(createRequestContainer as jest.Mock).mockResolvedValue({
+        hasRegistration: (name: string) => name !== 'rateLimiterService',
+        resolve: (name: string) => {
+          if (name === 'rateLimiterService') throw new Error('rate limiter is not registered')
+          if (name === 'em') return { findOne: mockEmFindOne }
+          if (name === 'commandBus') return { execute: mockCommandExecute }
+          if (name === 'paymentGatewayService') {
+            return { createPaymentSession: mockCreatePaymentSession }
+          }
+          throw new Error(`Unknown dependency: ${name}`)
+        },
+      })
+
+      const response = await POST(
+        new Request('https://merchant.example/api/checkout/pay/donate/submit', {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'Idempotency-Key': 'no-limiter-key-1234',
+            origin: 'https://merchant.example',
+          },
+          body: JSON.stringify({ customerData: {}, acceptedLegalConsents: {}, amount: 1 }),
+        }),
+        { params: { slug: 'donate' } },
+      )
+
+      expect(response.status).toBe(201)
+      expect(checkRateLimit).not.toHaveBeenCalled()
+      expect(mockCommandExecute).toHaveBeenCalled()
+    })
+  })
 })

package/src/modules/checkout/api/pay/[slug]/submit/route.ts

@@ -5,8 +5,6 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
-import { checkRateLimit } from '@open-mercato/shared/lib/ratelimit/helpers'
 import type { PaymentGatewayClientSession } from '@open-mercato/shared/modules/payment_gateways/types'
 import type { PaymentGatewayService } from '@open-mercato/core/modules/payment_gateways/lib/gateway-service'
 import { GatewayTransaction } from '@open-mercato/core/modules/payment_gateways/data/entities'
@@ -22,7 +20,8 @@ import {
   validateDescriptorCurrencies,
 } from '../../../../lib/utils'
 import { validateCheckoutCustomerData } from '../../../../lib/customerDataValidation'
-import { buildCheckoutRateLimitKey, checkoutSubmitRateLimitConfig } from '../../../../lib/rateLimiter'
+import { checkoutSubmitRateLimitConfig, enforceCheckoutRateLimit } from '../../../../lib/rateLimiter'
+import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
 import { checkoutTag } from '../../../openapi'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
@@ -274,14 +273,16 @@ export const metadata = {
 export async function POST(req: Request, { params }: { params: Promise<{ slug: string }> | { slug: string } }) {
   try {
     const container = await createRequestContainer()
-    try {
-      const rateLimiter = container.resolve('rateLimiterService') as RateLimiterService
-      const key = buildCheckoutRateLimitKey(req, rateLimiter, 'checkout-submit')
-      const rateLimitResponse = await checkRateLimit(rateLimiter, checkoutSubmitRateLimitConfig, key, 'Too many payment attempts. Please try again later.')
-      if (rateLimitResponse) return rateLimitResponse
-    } catch {
-      // Rate limiting is fail-open
-    }
+    // Fail-closed: this endpoint creates payment sessions that can charge cards.
+    const rateLimitResponse = await enforceCheckoutRateLimit({
+      req,
+      container,
+      config: checkoutSubmitRateLimitConfig,
+      namespace: 'checkout-submit',
+      errorMessage: 'Too many payment attempts. Please try again later.',
+      posture: 'fail-closed',
+    })
+    if (rateLimitResponse) return rateLimitResponse
     const resolvedParams = await params
 
     const allowedOrigins = buildAllowedOrigins()
@@ -593,6 +594,14 @@ export async function POST(req: Request, { params }: { params: Promise<{ slug: s
 
 export const openApi = {
   tags: [checkoutTag],
+  methods: {
+    POST: {
+      errors: [
+        { status: 429, description: 'Too many payment attempts', schema: rateLimitErrorSchema },
+        { status: 503, description: 'Rate limiting could not be enforced, so the payment was rejected', schema: rateLimitErrorSchema },
+      ],
+    },
+  },
 }
 
 export default POST

package/src/modules/checkout/api/pay/[slug]/verify-password/__tests__/route.test.ts

@@ -0,0 +1,121 @@
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { checkRateLimit } from '@open-mercato/shared/lib/ratelimit/helpers'
+import { verifyCheckoutPassword } from '../../../../../lib/utils'
+import { POST } from '../route'
+
+const LINK_ID = '11111111-1111-4111-8111-111111111111'
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: jest.fn(),
+}))
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: jest.fn(),
+}))
+
+jest.mock('@open-mercato/shared/lib/ratelimit/helpers', () => ({
+  checkRateLimit: jest.fn(),
+  getClientIp: jest.fn(() => '127.0.0.1'),
+  RATE_LIMIT_FALLBACK_KEY: 'global',
+  RATE_LIMIT_UNAVAILABLE_FALLBACK: 'Service temporarily unavailable. Please try again later.',
+}))
+
+jest.mock('../../../../../lib/utils', () => ({
+  ...jest.requireActual('../../../../../lib/utils'),
+  verifyCheckoutPassword: jest.fn(),
+  signCheckoutAccessToken: jest.fn(() => 'signed-token'),
+}))
+
+function verifyRequest() {
+  return POST(
+    new Request('https://merchant.example/api/checkout/pay/donate/verify-password', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ password: 'letmein' }),
+    }),
+    { params: { slug: 'donate' } },
+  )
+}
+
+describe('POST /api/checkout/pay/[slug]/verify-password', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    ;(checkRateLimit as jest.Mock).mockResolvedValue(null)
+    ;(verifyCheckoutPassword as jest.Mock).mockResolvedValue(true)
+    ;(createRequestContainer as jest.Mock).mockResolvedValue({
+      resolve: (name: string) => {
+        if (name === 'rateLimiterService') return { trustProxyDepth: 0 }
+        if (name === 'em') return {}
+        throw new Error(`Unknown dependency: ${name}`)
+      },
+    })
+    ;(findOneWithDecryption as jest.Mock).mockResolvedValue({
+      id: LINK_ID,
+      slug: 'donate',
+      status: 'active',
+      passwordHash: 'hashed',
+    })
+  })
+
+  it('accepts a correct password when the limiter allows the request', async () => {
+    const response = await verifyRequest()
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true })
+  })
+
+  it('asks the limiter to fail closed', async () => {
+    await verifyRequest()
+
+    expect(checkRateLimit).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.any(String),
+      expect.any(String),
+      expect.objectContaining({ failClosed: true }),
+    )
+  })
+
+  it('returns 503 without verifying the password when the limiter cannot decide', async () => {
+    ;(checkRateLimit as jest.Mock).mockRejectedValue(new Error('backing store unreachable'))
+
+    const response = await verifyRequest()
+
+    expect(response.status).toBe(503)
+    expect(await response.json()).toEqual({
+      error: 'Service temporarily unavailable. Please try again later.',
+    })
+    expect(verifyCheckoutPassword).not.toHaveBeenCalled()
+  })
+
+  // "Not registered" is a configuration error rather than a transient outage, so the
+  // request is served instead of being rejected as temporarily unavailable forever.
+  it('verifies the password when no rate limiter is registered', async () => {
+    ;(createRequestContainer as jest.Mock).mockResolvedValue({
+      hasRegistration: (name: string) => name !== 'rateLimiterService',
+      resolve: (name: string) => {
+        if (name === 'rateLimiterService') throw new Error('rate limiter is not registered')
+        if (name === 'em') return {}
+        throw new Error(`Unknown dependency: ${name}`)
+      },
+    })
+
+    const response = await verifyRequest()
+
+    expect(response.status).toBe(200)
+    expect(checkRateLimit).not.toHaveBeenCalled()
+    expect(verifyCheckoutPassword).toHaveBeenCalled()
+  })
+
+  it('passes a 503 from the limiter straight through', async () => {
+    ;(checkRateLimit as jest.Mock).mockResolvedValue(
+      new Response(JSON.stringify({ error: 'unavailable' }), { status: 503 }),
+    )
+
+    const response = await verifyRequest()
+
+    expect(response.status).toBe(503)
+    expect(verifyCheckoutPassword).not.toHaveBeenCalled()
+  })
+})

package/src/modules/checkout/api/pay/[slug]/verify-password/route.ts

@@ -1,8 +1,6 @@
 import { NextResponse } from 'next/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
-import { checkRateLimit } from '@open-mercato/shared/lib/ratelimit/helpers'
 import { CheckoutLink } from '../../../../data/entities'
 import { CHECKOUT_PASSWORD_COOKIE } from '../../../../lib/constants'
 import { publicPasswordVerifySchema } from '../../../../data/validators'
@@ -12,7 +10,8 @@ import {
   signCheckoutAccessToken,
   verifyCheckoutPassword,
 } from '../../../../lib/utils'
-import { buildCheckoutRateLimitKey, checkoutPasswordRateLimitConfig } from '../../../../lib/rateLimiter'
+import { checkoutPasswordRateLimitConfig, enforceCheckoutRateLimit } from '../../../../lib/rateLimiter'
+import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
 import { checkoutTag } from '../../../openapi'
 
 export const metadata = {
@@ -23,14 +22,16 @@ export const metadata = {
 export async function POST(req: Request, { params }: { params: Promise<{ slug: string }> | { slug: string } }) {
   try {
     const container = await createRequestContainer()
-    try {
-      const rateLimiter = container.resolve('rateLimiterService') as RateLimiterService
-      const key = buildCheckoutRateLimitKey(req, rateLimiter, 'checkout-password')
-      const rateLimitResponse = await checkRateLimit(rateLimiter, checkoutPasswordRateLimitConfig, key, 'Too many password attempts. Please try again later.')
-      if (rateLimitResponse) return rateLimitResponse
-    } catch {
-      // Rate limiting is fail-open
-    }
+    // Fail-closed: an unenforced limit allows password brute force.
+    const rateLimitResponse = await enforceCheckoutRateLimit({
+      req,
+      container,
+      config: checkoutPasswordRateLimitConfig,
+      namespace: 'checkout-password',
+      errorMessage: 'Too many password attempts. Please try again later.',
+      posture: 'fail-closed',
+    })
+    if (rateLimitResponse) return rateLimitResponse
     const resolvedParams = await params
     const body = publicPasswordVerifySchema.parse(await req.json().catch(() => ({})))
     const em = container.resolve('em')
@@ -64,6 +65,14 @@ export async function POST(req: Request, { params }: { params: Promise<{ slug: s
 
 export const openApi = {
   tags: [checkoutTag],
+  methods: {
+    POST: {
+      errors: [
+        { status: 429, description: 'Too many password attempts', schema: rateLimitErrorSchema },
+        { status: 503, description: 'Rate limiting could not be enforced, so the attempt was rejected', schema: rateLimitErrorSchema },
+      ],
+    },
+  },
 }
 
 export default POST

package/src/modules/checkout/api/pay/__tests__/openapi-rate-limit-responses.test.ts

@@ -0,0 +1,41 @@
+import { buildOpenApiDocument } from '@open-mercato/shared/lib/openapi/generator'
+import type { Module, ModuleApiRouteFile } from '@open-mercato/shared/modules/registry'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
+import { openApi as submitOpenApi } from '../[slug]/submit/route'
+import { openApi as verifyPasswordOpenApi } from '../[slug]/verify-password/route'
+
+type ResponseEntry = { description?: string; content?: Record<string, unknown> }
+
+function operationFor(openApi: unknown, path: string): { responses: Record<string, ResponseEntry> } {
+  const api: ModuleApiRouteFile = {
+    path,
+    handlers: { POST: async () => new Response(null) },
+    docs: openApi as OpenApiRouteDoc,
+  }
+  const module: Module = { id: 'checkout', apis: [api] }
+  return buildOpenApiDocument([module]).paths[path]?.post as { responses: Record<string, ResponseEntry> }
+}
+
+describe('public checkout pay routes document their rate-limit responses', () => {
+  it.each([
+    {
+      name: 'submit',
+      openApi: submitOpenApi,
+      path: '/api/checkout/pay/{slug}/submit',
+      rejected: 'Rate limiting could not be enforced, so the payment was rejected',
+      throttled: 'Too many payment attempts',
+    },
+    {
+      name: 'verify-password',
+      openApi: verifyPasswordOpenApi,
+      path: '/api/checkout/pay/{slug}/verify-password',
+      rejected: 'Rate limiting could not be enforced, so the attempt was rejected',
+      throttled: 'Too many password attempts',
+    },
+  ])('exposes 429 and 503 in the generated document for $name', ({ openApi, path, rejected, throttled }) => {
+    const operation = operationFor(openApi, path)
+
+    expect(operation.responses['429'].description).toBe(throttled)
+    expect(operation.responses['503'].description).toBe(rejected)
+  })
+})

package/src/modules/checkout/lib/__tests__/rateLimiter.test.ts

@@ -1,5 +1,10 @@
+import type { RateLimitResult } from '@open-mercato/shared/lib/ratelimit/types'
 import type { RateLimiterService } from '@open-mercato/shared/lib/ratelimit/service'
-import { buildCheckoutRateLimitKey } from '../rateLimiter'
+import {
+  buildCheckoutRateLimitKey,
+  checkoutSubmitRateLimitConfig,
+  enforceCheckoutRateLimit,
+} from '../rateLimiter'
 
 function makeRateLimiter(trustProxyDepth: number): RateLimiterService {
   return { trustProxyDepth } as RateLimiterService
@@ -45,3 +50,114 @@ describe('buildCheckoutRateLimitKey', () => {
       .toBe('checkout-public-view:global')
   })
 })
+
+describe('enforceCheckoutRateLimit', () => {
+  const allowedResult: RateLimitResult = {
+    allowed: true,
+    remainingPoints: 9,
+    msBeforeNext: 0,
+    consumedPoints: 1,
+  }
+  const degradedResult: RateLimitResult = { ...allowedResult, degraded: true }
+  const rejectedResult: RateLimitResult = {
+    allowed: false,
+    remainingPoints: 0,
+    msBeforeNext: 30_000,
+    consumedPoints: 11,
+  }
+
+  function makeContainer(consume: jest.Mock | null) {
+    return {
+      hasRegistration: (name: string) => name !== 'rateLimiterService' || consume !== null,
+      resolve: (name: string) => {
+        if (name === 'rateLimiterService' && consume) return { trustProxyDepth: 0, consume }
+        throw new Error(`Unknown dependency: ${name}`)
+      },
+    }
+  }
+
+  type TestContainer = {
+    resolve: (name: string) => unknown
+    hasRegistration?: (name: string) => boolean
+  }
+
+  function enforce(container: TestContainer, posture: 'fail-open' | 'fail-closed') {
+    return enforceCheckoutRateLimit({
+      req: new Request('https://merchant.example/api/checkout/pay/donate/submit', { method: 'POST' }),
+      container,
+      config: checkoutSubmitRateLimitConfig,
+      namespace: 'checkout-submit',
+      errorMessage: 'Too many payment attempts. Please try again later.',
+      posture,
+    })
+  }
+
+  it('rejects with 503 when the limiter reports a degraded decision and the endpoint fails closed', async () => {
+    const consume = jest.fn().mockResolvedValue(degradedResult)
+
+    const response = await enforce(makeContainer(consume), 'fail-closed')
+
+    expect(response?.status).toBe(503)
+    expect(await response?.json()).toEqual({
+      error: 'Service temporarily unavailable. Please try again later.',
+    })
+  })
+
+  it('rejects with 503 when the limiter throws and the endpoint fails closed', async () => {
+    const consume = jest.fn().mockRejectedValue(new Error('backing store unreachable'))
+
+    const response = await enforce(makeContainer(consume), 'fail-closed')
+
+    expect(response?.status).toBe(503)
+  })
+
+  // The read-only endpoints deliberately keep the permissive posture: a limiter that
+  // cannot decide must not take the public checkout page or its status polling down.
+  it('serves the request when the limiter is degraded and the endpoint fails open', async () => {
+    const consume = jest.fn().mockResolvedValue(degradedResult)
+
+    expect(await enforce(makeContainer(consume), 'fail-open')).toBeNull()
+  })
+
+  it('serves the request when the limiter throws and the endpoint fails open', async () => {
+    const consume = jest.fn().mockRejectedValue(new Error('backing store unreachable'))
+
+    expect(await enforce(makeContainer(consume), 'fail-open')).toBeNull()
+  })
+
+  // A missing DI registration means the rate-limit configuration is invalid, which lasts
+  // until an operator fixes it. Reporting that as "temporarily unavailable" would take
+  // checkout down indefinitely, so the check is skipped for both postures instead.
+  it('skips the check for both postures when no limiter is registered', async () => {
+    expect(await enforce(makeContainer(null), 'fail-closed')).toBeNull()
+    expect(await enforce(makeContainer(null), 'fail-open')).toBeNull()
+  })
+
+  it('skips the check when resolving the limiter throws', async () => {
+    const container = {
+      resolve: () => {
+        throw new Error('AwilixResolutionError: could not resolve rateLimiterService')
+      },
+    }
+
+    expect(await enforce(container, 'fail-closed')).toBeNull()
+  })
+
+  it('returns the limiter 429 when the quota is exhausted', async () => {
+    const consume = jest.fn().mockResolvedValue(rejectedResult)
+
+    const response = await enforce(makeContainer(consume), 'fail-closed')
+
+    expect(response?.status).toBe(429)
+    expect(await response?.json()).toEqual({
+      error: 'Too many payment attempts. Please try again later.',
+    })
+  })
+
+  it('allows the request when the limiter decides there is quota left', async () => {
+    const consume = jest.fn().mockResolvedValue(allowedResult)
+
+    expect(await enforce(makeContainer(consume), 'fail-closed')).toBeNull()
+    expect(consume).toHaveBeenCalledWith('checkout-submit:global', checkoutSubmitRateLimitConfig)
+  })
+})