@open-mercato/shared 0.6.7-develop.6788.1.c2a1520a30 → 0.6.7-develop.6814.1.0627c7e9f1

package/src/lib/search/availability.ts

@@ -0,0 +1,232 @@
+import { sql } from 'kysely'
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+
+export type OrganizationScope = { ids: string[]; includeNull: boolean }
+
+export type SearchTokenSourceRef = { entity: string; recordIdColumn?: string }
+
+type ProbeExpression = object | string | readonly string[] | null
+
+export type SearchTokenProbeQueryBuilder = {
+  select: (selection: ProbeExpression) => SearchTokenProbeQueryBuilder
+  where: (column: ProbeExpression, operator?: string, value?: ProbeExpression) => SearchTokenProbeQueryBuilder
+  limit: (count: number) => SearchTokenProbeQueryBuilder
+  executeTakeFirst: () => Promise<object | undefined>
+}
+
+export type SearchTokenProbeDb = { selectFrom: (table: string) => SearchTokenProbeQueryBuilder }
+
+export type SearchTokenAvailabilityDebugPayload = {
+  entity: string
+  tenantId: string | null
+  organizationScope?: OrganizationScope | null
+  recordIdColumn?: string
+  hasTokens?: boolean
+  error?: string
+}
+
+export type SearchTokenAvailabilityDeps = {
+  getDb: () => SearchTokenProbeDb
+  getConfig: () => { enabled: boolean }
+  applyOrganizationScope: (
+    query: SearchTokenProbeQueryBuilder,
+    column: string,
+    scope: OrganizationScope,
+  ) => SearchTokenProbeQueryBuilder
+  logDebug: (event: string, payload: SearchTokenAvailabilityDebugPayload) => void
+}
+
+export type SearchTokenAvailability = {
+  /**
+   * The cheap, statically-known half of the decision: search is configured on
+   * AND the `search_tokens` table exists. Safe to resolve eagerly (consumers
+   * like custom-field source attachment need it before any filter is
+   * inspected); the table probe is memoized per instance.
+   */
+  staticEnabled: () => Promise<boolean>
+  /**
+   * The expensive half: does `search_tokens` hold any row for this
+   * (entity, tenant, organization scope)? Historically the `LIMIT 1` probe
+   * could degenerate into a seq scan on a large table (#4723), so callers MUST
+   * only ask when the query actually carries a like/ilike filter — use
+   * `hasSearchFilter` for the gate. Three layers keep it cheap for the end
+   * user: index-usable predicates (no `IS NOT DISTINCT FROM`) served by the
+   * dedicated `search_tokens_presence_idx (entity_type, tenant_id,
+   * organization_id)` prefix — which makes the MISS as cheap as the hit — a
+   * per-request instance memo, and a process-level TTL cache
+   * (`OM_SEARCH_TOKEN_PRESENCE_CACHE_MS`, default 30s) that amortizes the
+   * probe across requests. Probe errors log `search:has-tokens-error`,
+   * resolve to `false`, and are never TTL-cached.
+   */
+  hasTokens: (entity: string, tenantId: string | null, orgScope?: OrganizationScope | null) => Promise<boolean>
+  /** First-hit sweep over token sources; logs `search:source-has-tokens` per probed source. */
+  anySourceHasTokens: (
+    sources: SearchTokenSourceRef[],
+    tenantId: string | null,
+    orgScope?: OrganizationScope | null,
+  ) => Promise<boolean>
+}
+
+export function isSearchFilterOp(op: string | null | undefined): boolean {
+  return op === 'like' || op === 'ilike'
+}
+
+/**
+ * The single definition of "this query actually searches". Every consumer of
+ * the token-availability answer sits behind a like/ilike guard, so when this
+ * returns `false` the `hasTokens` probe's answer would never be read — gate
+ * the probe on it.
+ */
+export function hasSearchFilter(filters: ReadonlyArray<{ op?: string | null }>): boolean {
+  return filters.some((filter) => isSearchFilterOp(filter.op))
+}
+
+function orgScopeKey(scope: OrganizationScope | null | undefined): string {
+  if (!scope) return 'none'
+  return `${scope.includeNull ? '1' : '0'}:${[...scope.ids].sort((left, right) => left.localeCompare(right)).join(',')}`
+}
+
+const PRESENCE_CACHE_DEFAULT_TTL_MS = 30_000
+const PRESENCE_CACHE_MAX_ENTRIES = 10_000
+
+// Process-level TTL cache for the token-presence answer. Module-level (process-global) on
+// purpose: `createRequestContainer` builds fresh engines — and with them fresh resolver
+// instances — per request, so an instance-scoped memo alone re-pays the probe on every
+// request. On a large `search_tokens` one probe can be pathologically expensive (#4723),
+// so the answer is amortized across requests here and only re-checked once per TTL.
+// Staleness contract: a stale `false` keeps like/ilike on the plain-column fallback for up
+// to the TTL after an entity's first tokens are written; a stale `true` routes search
+// through an emptied token set for up to the TTL after a purge. Both converge within the
+// TTL; set OM_SEARCH_TOKEN_PRESENCE_CACHE_MS=0 to disable and probe per request again.
+const presenceCache = new Map<string, { value: boolean; expiresAt: number }>()
+
+function resolvePresenceCacheTtlMs(): number {
+  return parseNumberWithDefault(process.env.OM_SEARCH_TOKEN_PRESENCE_CACHE_MS, PRESENCE_CACHE_DEFAULT_TTL_MS, { integer: true, min: 0 })
+}
+
+function storePresence(key: string, value: boolean, ttlMs: number): void {
+  if (presenceCache.size >= PRESENCE_CACHE_MAX_ENTRIES) {
+    const now = Date.now()
+    for (const [entryKey, entry] of presenceCache) {
+      if (entry.expiresAt <= now) presenceCache.delete(entryKey)
+    }
+    if (presenceCache.size >= PRESENCE_CACHE_MAX_ENTRIES) presenceCache.clear()
+  }
+  presenceCache.set(key, { value, expiresAt: Date.now() + ttlMs })
+}
+
+export function clearSearchTokenPresenceCache(): void {
+  presenceCache.clear()
+}
+
+/**
+ * One place that answers "is token search usable here?" for both query
+ * engines, instead of each hand-assembling config + table-existence +
+ * token-presence probes with private duplicate helpers and ad-hoc memo maps.
+ *
+ * Memoization is per instance; engines are constructed per request
+ * (`createRequestContainer`), so entries never outlive a request — the same
+ * staleness contract the engines' previous per-query join maps had. A
+ * rejected table probe is evicted so the next call retries instead of
+ * observing a poisoned cache entry.
+ */
+export function createSearchTokenAvailability(deps: SearchTokenAvailabilityDeps): SearchTokenAvailability {
+  const tablePresence = new Map<string, Promise<boolean>>()
+  const tokenPresence = new Map<string, Promise<boolean>>()
+
+  const tableExists = (table: string): Promise<boolean> => {
+    const cached = tablePresence.get(table)
+    if (cached) return cached
+    const probe = (async () => {
+      const row = await deps.getDb()
+        .selectFrom('information_schema.tables')
+        .select(sql<number>`1`.as('one'))
+        .where('table_name', '=', table)
+        .limit(1)
+        .executeTakeFirst()
+      return !!row
+    })()
+    tablePresence.set(table, probe)
+    probe.catch(() => tablePresence.delete(table))
+    return probe
+  }
+
+  const probeTokens = async (
+    entity: string,
+    tenantId: string | null,
+    orgScope?: OrganizationScope | null,
+  ): Promise<boolean> => {
+    let query = deps.getDb()
+      .selectFrom('search_tokens')
+      .select(sql<number>`1`.as('one'))
+      .where('entity_type', '=', entity)
+    // Deliberately `= / IS NULL` instead of `IS NOT DISTINCT FROM` (identical semantics
+    // for a string|null tenant): the latter cannot serve as an index condition, which is
+    // part of why the planner degraded this probe to a seq scan on large tables (#4723).
+    // With plain predicates the probe is a pure prefix seek on
+    // `search_tokens_presence_idx (entity_type, tenant_id, organization_id)`, making the
+    // miss as cheap as the hit.
+    query = tenantId == null
+      ? query.where('tenant_id', 'is', null)
+      : query.where('tenant_id', '=', tenantId)
+    if (orgScope) {
+      query = deps.applyOrganizationScope(query, 'search_tokens.organization_id', orgScope)
+    }
+    const row = await query.limit(1).executeTakeFirst()
+    return !!row
+  }
+
+  const hasTokens = (
+    entity: string,
+    tenantId: string | null,
+    orgScope?: OrganizationScope | null,
+  ): Promise<boolean> => {
+    const key = `${entity}|${tenantId ?? '__null__'}|${orgScopeKey(orgScope)}`
+    const ttlMs = resolvePresenceCacheTtlMs()
+    if (ttlMs > 0) {
+      const entry = presenceCache.get(key)
+      if (entry && entry.expiresAt > Date.now()) return Promise.resolve(entry.value)
+    }
+    const cached = tokenPresence.get(key)
+    if (cached) return cached
+    const probe = (async () => {
+      try {
+        const value = await probeTokens(entity, tenantId, orgScope)
+        // Only genuine probe results enter the process-level cache — caching an
+        // error-driven `false` would pin degraded search for a full TTL after a
+        // transient DB failure.
+        if (ttlMs > 0) storePresence(key, value, ttlMs)
+        return value
+      } catch (err) {
+        deps.logDebug('search:has-tokens-error', {
+          entity,
+          tenantId,
+          organizationScope: orgScope,
+          error: err instanceof Error ? err.message : String(err),
+        })
+        return false
+      }
+    })()
+    tokenPresence.set(key, probe)
+    return probe
+  }
+
+  return {
+    staticEnabled: async () => deps.getConfig().enabled && await tableExists('search_tokens'),
+    hasTokens,
+    anySourceHasTokens: async (sources, tenantId, orgScope) => {
+      for (const source of sources) {
+        const ok = await hasTokens(source.entity, tenantId, orgScope)
+        deps.logDebug('search:source-has-tokens', {
+          entity: source.entity,
+          recordIdColumn: source.recordIdColumn,
+          tenantId,
+          organizationScope: orgScope,
+          hasTokens: ok,
+        })
+        if (ok) return true
+      }
+      return false
+    },
+  }
+}

package/src/lib/search/config.ts

@@ -10,9 +10,21 @@ export type SearchConfig = {
   storeRawTokens: boolean
   blocklistedFields: string[]
   entityBlocklistedFields?: Record<string, string[]>
+  maxFieldChars?: number
+  maxTokensPerField?: number
+  maxTokensPerRecord?: number
 }
 
 export const DEFAULT_SEARCH_MIN_TOKEN_LENGTH = 3
+export const DEFAULT_SEARCH_MAX_FIELD_CHARS = 20_000
+export const DEFAULT_SEARCH_MAX_TOKENS_PER_FIELD = 5_000
+export const DEFAULT_SEARCH_MAX_TOKENS_PER_RECORD = 20_000
+
+export type SearchTokenLimits = {
+  maxFieldChars: number
+  maxTokensPerField: number
+  maxTokensPerRecord: number
+}
 
 const DEFAULT_BLOCKLIST = ['password', 'token', 'secret', 'hash']
 
@@ -26,6 +38,19 @@ function parseNumber(raw: string | undefined, fallback: number, min = 1): number
   return parseNumberWithDefault(raw, fallback, { integer: true, min })
 }
 
+export function resolveSearchTokenLimits(config: SearchConfig): SearchTokenLimits {
+  const resolveLimit = (value: number | undefined, fallback: number): number => {
+    if (value === undefined) return fallback
+    if (!Number.isFinite(value) || value < 0) return fallback
+    return Math.trunc(value)
+  }
+  return {
+    maxFieldChars: resolveLimit(config.maxFieldChars, DEFAULT_SEARCH_MAX_FIELD_CHARS),
+    maxTokensPerField: resolveLimit(config.maxTokensPerField, DEFAULT_SEARCH_MAX_TOKENS_PER_FIELD),
+    maxTokensPerRecord: resolveLimit(config.maxTokensPerRecord, DEFAULT_SEARCH_MAX_TOKENS_PER_RECORD),
+  }
+}
+
 function parseHashAlgorithm(raw: string | undefined): 'sha256' | 'sha1' | 'md5' {
   const value = (raw ?? '').trim().toLowerCase()
   if (value === 'sha1') return 'sha1'
@@ -89,6 +114,9 @@ export function resolveSearchConfig(): SearchConfig {
     storeRawTokens: parseBoolean(process.env.OM_SEARCH_STORE_RAW_TOKENS, false),
     blocklistedFields: blocklist.global,
     entityBlocklistedFields: blocklist.byEntity,
+    maxFieldChars: parseNumber(process.env.OM_SEARCH_MAX_FIELD_CHARS, DEFAULT_SEARCH_MAX_FIELD_CHARS, 0),
+    maxTokensPerField: parseNumber(process.env.OM_SEARCH_MAX_TOKENS_PER_FIELD, DEFAULT_SEARCH_MAX_TOKENS_PER_FIELD, 0),
+    maxTokensPerRecord: parseNumber(process.env.OM_SEARCH_MAX_TOKENS_PER_RECORD, DEFAULT_SEARCH_MAX_TOKENS_PER_RECORD, 0),
   }
 }
 

package/src/lib/search/tokenize.ts

@@ -1,5 +1,5 @@
 import crypto from 'crypto'
-import { resolveSearchConfig, type SearchConfig } from './config'
+import { resolveSearchConfig, resolveSearchTokenLimits, type SearchConfig } from './config'
 
 export type TokenizationResult = {
   tokens: string[]
@@ -20,13 +20,28 @@ function splitTokens(text: string, minLength: number): string[] {
     .filter((token) => token.length >= minLength)
 }
 
-function expandToken(token: string, config: SearchConfig): string[] {
-  if (!config.enablePartials) return [token]
-  const results: string[] = []
-  for (let i = config.minTokenLength; i <= token.length; i += 1) {
-    results.push(token.slice(0, i))
+function appendExpandedToken(
+  token: string,
+  config: SearchConfig,
+  seen: Set<string>,
+  tokens: string[],
+  limit: number,
+): void {
+  const append = (candidate: string): boolean => {
+    if (seen.has(candidate)) return tokens.length < limit
+    seen.add(candidate)
+    tokens.push(candidate)
+    return tokens.length < limit
+  }
+
+  if (!config.enablePartials) {
+    append(token)
+    return
+  }
+
+  for (let length = config.minTokenLength; length <= token.length; length += 1) {
+    if (!append(token.slice(0, length))) return
   }
-  return results
 }
 
 export function hashToken(token: string, config?: SearchConfig): string {
@@ -36,10 +51,17 @@ export function hashToken(token: string, config?: SearchConfig): string {
 
 export function tokenizeText(text: string, config?: SearchConfig): TokenizationResult {
   const cfg = config ?? resolveSearchConfig()
-  const baseTokens = splitTokens(text, cfg.minTokenLength)
-  const expanded = baseTokens.flatMap((token) => expandToken(token, cfg))
-  const unique = Array.from(new Set(expanded))
-  const tokens = unique.filter((token) => token.length >= cfg.minTokenLength)
+  const limits = resolveSearchTokenLimits(cfg)
+  const boundedText = limits.maxFieldChars > 0 ? text.slice(0, limits.maxFieldChars) : text
+  const tokenLimit = limits.maxTokensPerField > 0 ? limits.maxTokensPerField : Number.POSITIVE_INFINITY
+  const seen = new Set<string>()
+  const tokens: string[] = []
+
+  for (const token of splitTokens(boundedText, cfg.minTokenLength)) {
+    if (tokens.length >= tokenLimit) break
+    appendExpandedToken(token, cfg, seen, tokens, tokenLimit)
+  }
+
   const hashes = tokens.map((token) => hashToken(token, cfg))
   return { tokens, hashes }
 }

package/src/lib/webhooks/__tests__/body.test.ts

@@ -0,0 +1,95 @@
+/** @jest-environment node */
+import {
+  DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+  readBoundedRequestBody,
+  resolveWebhookBodyLimitBytes,
+  WebhookBodyTooLargeError,
+} from '../body'
+
+function makeStreamingRequest(chunks: Uint8Array[], headers?: HeadersInit) {
+  let index = 0
+  const cancel = jest.fn()
+  const body = new ReadableStream<Uint8Array>({
+    pull(controller) {
+      const chunk = chunks[index]
+      index += 1
+      if (chunk) controller.enqueue(chunk)
+      else controller.close()
+    },
+    cancel,
+  })
+  const request = new Request('http://localhost/webhook', {
+    method: 'POST',
+    headers,
+    body,
+    duplex: 'half',
+  } as RequestInit & { duplex: 'half' })
+  return { request, cancel }
+}
+
+describe('readBoundedRequestBody', () => {
+  const encoder = new TextEncoder()
+
+  it('rejects an oversized declared length before reading the body', async () => {
+    const request = new Request('http://localhost/webhook', {
+      method: 'POST',
+      headers: { 'content-length': '6' },
+      body: 'ok',
+    })
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toEqual(
+      expect.objectContaining<WebhookBodyTooLargeError>({ limitBytes: 5 }),
+    )
+  })
+
+  it('stops a chunked body when its actual byte count crosses the limit', async () => {
+    const { request, cancel } = makeStreamingRequest([
+      encoder.encode('abc'),
+      encoder.encode('def'),
+      encoder.encode('never-read'),
+    ])
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+    expect(cancel).toHaveBeenCalled()
+  })
+
+  it.each([
+    ['invalid', 'not-a-number'],
+    ['lying', '3'],
+  ])('does not let a %s Content-Length bypass the streamed cap', async (_case, contentLength) => {
+    const { request } = makeStreamingRequest(
+      [encoder.encode('abc'), encoder.encode('def')],
+      { 'content-length': contentLength },
+    )
+
+    await expect(readBoundedRequestBody(request, { maxBytes: 5 })).rejects.toBeInstanceOf(
+      WebhookBodyTooLargeError,
+    )
+  })
+
+  it('preserves the exact decoded body at the byte boundary', async () => {
+    const bytes = encoder.encode('a€')
+    const { request } = makeStreamingRequest([bytes.slice(0, 2), bytes.slice(2)])
+
+    await expect(readBoundedRequestBody(request, { maxBytes: bytes.byteLength })).resolves.toBe('a€')
+  })
+})
+
+describe('resolveWebhookBodyLimitBytes', () => {
+  it('uses the documented default for missing or invalid configuration', () => {
+    expect(resolveWebhookBodyLimitBytes(undefined)).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+    expect(resolveWebhookBodyLimitBytes('invalid')).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+    expect(resolveWebhookBodyLimitBytes('0')).toBe(DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+  })
+
+  it('accepts a positive safe integer override', () => {
+    expect(resolveWebhookBodyLimitBytes('2097152')).toBe(2 * 1024 * 1024)
+  })
+
+  it('supports a source-specific fallback without weakening validation', () => {
+    expect(resolveWebhookBodyLimitBytes(undefined, 2 * 1024 * 1024)).toBe(2 * 1024 * 1024)
+    expect(resolveWebhookBodyLimitBytes('invalid', 2 * 1024 * 1024)).toBe(2 * 1024 * 1024)
+  })
+})

package/src/lib/webhooks/__tests__/verify.test.ts

@@ -1,7 +1,26 @@
 import { signWebhookPayload } from '../sign'
-import { verifyWebhookSignature } from '../verify'
+import { isWebhookTimestampWithinTolerance, verifyWebhookSignature } from '../verify'
 import { generateWebhookSecret } from '../secrets'
 
+describe('isWebhookTimestampWithinTolerance', () => {
+  it('accepts timestamps inside the configured tolerance', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000000', 300, 1700000299)).toBe(true)
+  })
+
+  it('rejects stale timestamps outside the configured tolerance', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000000', 300, 1700000301)).toBe(false)
+  })
+
+  it('rejects timestamps too far in the future', () => {
+    expect(isWebhookTimestampWithinTolerance('1700000601', 300, 1700000000)).toBe(false)
+  })
+
+  it('rejects malformed timestamps', () => {
+    expect(isWebhookTimestampWithinTolerance('not-a-timestamp', 300, 1700000000)).toBe(false)
+    expect(isWebhookTimestampWithinTolerance('1700000000abc', 300, 1700000000)).toBe(false)
+  })
+})
+
 describe('verifyWebhookSignature', () => {
   const msgId = 'msg_test123'
   const body = '{"type":"test.event","data":{}}'

package/src/lib/webhooks/body.ts

@@ -0,0 +1,70 @@
+import { parseNumberWithDefault } from '../number'
+
+export const DEFAULT_WEBHOOK_BODY_LIMIT_BYTES = 1024 * 1024
+
+export class WebhookBodyTooLargeError extends Error {
+  readonly limitBytes: number
+
+  constructor(limitBytes: number) {
+    super(`Webhook body exceeds the ${limitBytes}-byte limit`)
+    this.name = 'WebhookBodyTooLargeError'
+    this.limitBytes = limitBytes
+  }
+}
+
+export function resolveWebhookBodyLimitBytes(
+  raw = typeof process === 'undefined' ? undefined : process.env.OM_WEBHOOK_MAX_BODY_BYTES,
+  fallbackBytes = DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+): number {
+  const fallback = Number.isSafeInteger(fallbackBytes) && fallbackBytes > 0
+    ? fallbackBytes
+    : DEFAULT_WEBHOOK_BODY_LIMIT_BYTES
+  const parsed = parseNumberWithDefault(raw, fallback, { min: 1 })
+  return Number.isSafeInteger(parsed) ? parsed : fallback
+}
+
+export async function readBoundedRequestBody(
+  request: Request,
+  options?: { maxBytes?: number },
+): Promise<string> {
+  const configuredLimit = options?.maxBytes ?? resolveWebhookBodyLimitBytes()
+  const maxBytes = Number.isSafeInteger(configuredLimit) && configuredLimit > 0
+    ? configuredLimit
+    : DEFAULT_WEBHOOK_BODY_LIMIT_BYTES
+  const declaredLength = request.headers.get('content-length')?.trim()
+  if (declaredLength && /^\d+$/.test(declaredLength)) {
+    const declaredBytes = Number(declaredLength)
+    if (!Number.isSafeInteger(declaredBytes) || declaredBytes > maxBytes) {
+      throw new WebhookBodyTooLargeError(maxBytes)
+    }
+  }
+
+  if (!request.body) return ''
+
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let totalBytes = 0
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      totalBytes += value.byteLength
+      if (totalBytes > maxBytes) {
+        await reader.cancel().catch(() => undefined)
+        throw new WebhookBodyTooLargeError(maxBytes)
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const body = new Uint8Array(totalBytes)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(body)
+}

package/src/lib/webhooks/index.ts

@@ -1,6 +1,12 @@
 export { signWebhookPayload, buildWebhookHeaders, generateMessageId } from './sign'
-export { verifyWebhookSignature } from './verify'
+export { WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, isWebhookTimestampWithinTolerance, verifyWebhookSignature } from './verify'
 export { generateWebhookSecret, parseWebhookSecret, isValidWebhookSecret } from './secrets'
+export {
+  DEFAULT_WEBHOOK_BODY_LIMIT_BYTES,
+  readBoundedRequestBody,
+  resolveWebhookBodyLimitBytes,
+  WebhookBodyTooLargeError,
+} from './body'
 export type { StandardWebhookHeaders, WebhookSigningKey, WebhookVerificationResult, StandardWebhookPayload } from './types'
 export type {
   InboundWebhookRequest,

package/src/lib/webhooks/verify.ts

@@ -2,7 +2,21 @@ import { timingSafeEqual, createHmac } from 'node:crypto'
 import { parseWebhookSecret } from './secrets'
 import type { WebhookVerificationResult } from './types'
 
-const TOLERANCE_SECONDS = 5 * 60 // 5 minutes
+export const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 5 * 60 // 5 minutes
+
+export function isWebhookTimestampWithinTolerance(
+  timestamp: string,
+  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): boolean {
+  const normalizedTimestamp = timestamp.trim()
+  if (!/^\d+$/.test(normalizedTimestamp)) {
+    return false
+  }
+
+  const timestampNum = Number.parseInt(normalizedTimestamp, 10)
+  return Math.abs(nowSeconds - timestampNum) <= toleranceSeconds
+}
 
 /**
  * Verify a Standard Webhooks signature against one or more secrets.
@@ -14,15 +28,9 @@ export function verifyWebhookSignature(
   body: string,
   signatureHeader: string,
   secrets: string[],
-  toleranceSeconds: number = TOLERANCE_SECONDS,
+  toleranceSeconds: number = WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
 ): WebhookVerificationResult {
-  const timestampNum = parseInt(timestamp, 10)
-  if (isNaN(timestampNum)) {
-    return { valid: false }
-  }
-
-  const now = Math.floor(Date.now() / 1000)
-  if (Math.abs(now - timestampNum) > toleranceSeconds) {
+  if (!isWebhookTimestampWithinTolerance(timestamp, toleranceSeconds)) {
     return { valid: false }
   }
 

package/src/modules/payment_gateways/__tests__/types.test.ts

@@ -0,0 +1,37 @@
+import {
+  clearWebhookHandlers,
+  getWebhookHandler,
+  registerWebhookHandler,
+  type VerifyWebhookInput,
+  type WebhookEvent,
+} from '../types'
+
+const handler = async (_input: VerifyWebhookInput): Promise<WebhookEvent> => ({
+  eventType: 'payment.updated',
+  eventId: 'evt-1',
+  data: {},
+  idempotencyKey: 'evt-1',
+  timestamp: new Date(0),
+})
+
+describe('payment gateway webhook registration', () => {
+  beforeEach(() => {
+    clearWebhookHandlers()
+  })
+
+  it('preserves an optional valid body limit on the registration', () => {
+    registerWebhookHandler('limited', handler, { maxBodyBytes: 64 * 1024 })
+
+    expect(getWebhookHandler('limited')?.maxBodyBytes).toBe(64 * 1024)
+  })
+
+  it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER])(
+    'rejects an invalid body limit: %s',
+    (maxBodyBytes) => {
+      expect(() => registerWebhookHandler('invalid', handler, { maxBodyBytes })).toThrow(
+        '[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer',
+      )
+      expect(getWebhookHandler('invalid')).toBeUndefined()
+    },
+  )
+})

package/src/modules/payment_gateways/types.ts

@@ -1,3 +1,5 @@
+import { DEFAULT_WEBHOOK_BODY_LIMIT_BYTES } from '../../lib/webhooks/body'
+
 // ── Unified Payment Status ──────────────────────────────────────────────────
 
 export type UnifiedPaymentStatus =
@@ -251,6 +253,7 @@ export interface WebhookHandlerRegistration {
   handler: (input: VerifyWebhookInput) => Promise<WebhookEvent>
   queue?: string
   readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+  maxBodyBytes?: number
 }
 
 // ── Adapter Registry Options ────────────────────────────────────────────────
@@ -345,13 +348,25 @@ export function registerWebhookHandler(
   options?: {
     queue?: string
     readSessionIdHint?: (payload: Record<string, unknown> | null) => string | null
+    maxBodyBytes?: number
   },
 ): () => void {
+  if (
+    options?.maxBodyBytes !== undefined
+    && (!Number.isSafeInteger(options.maxBodyBytes)
+      || options.maxBodyBytes <= 0
+      || options.maxBodyBytes > DEFAULT_WEBHOOK_BODY_LIMIT_BYTES)
+  ) {
+    throw new Error(
+      `[internal] Payment gateway webhook maxBodyBytes must be a positive safe integer no greater than ${DEFAULT_WEBHOOK_BODY_LIMIT_BYTES}`,
+    )
+  }
   const webhookHandlerRegistry = getWebhookHandlerRegistry()
   webhookHandlerRegistry.set(providerKey, {
     handler,
     queue: options?.queue,
     readSessionIdHint: options?.readSessionIdHint,
+    maxBodyBytes: options?.maxBodyBytes,
   })
   return () => {
     webhookHandlerRegistry.delete(providerKey)