@open-mercato/shared 0.6.7-develop.6795.1.8a3f27921c → 0.6.7-develop.6814.1.0627c7e9f1

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)

package/src/modules/widgets/extension-points.ts

@@ -232,11 +232,108 @@ export function resolveExtensionPointPattern(
   return pattern.replace(/\{([^}]+)\}/g, (token, parameterName: string) => parameters[parameterName] ?? token)
 }
 
+/**
+ * Portable, structural copy of the CLI provenance source reference
+ * (`ModuleFactSourceRef` in `packages/cli/.../module-facts.ts`). Redefined here
+ * — rather than imported — so `@open-mercato/shared` keeps zero dependency on
+ * `@open-mercato/cli`. Field names are kept byte-identical so the two are
+ * assignable across the package boundary.
+ */
+export type ModuleFactSourceRef = {
+  sourcePath: string
+  exportName?: string
+  line?: number
+}
+
+/** Portable, structural copy of the CLI provenance fact reference. */
+export type ModuleFactRef = {
+  factSection: string
+  factKey: string
+}
+
+export type ModuleExtensionContributionKind = ModuleExtensionContributionFact['kind']
+
+export type ModuleExtensionActivationKind =
+  | 'crud-response-enricher'
+  | 'query-enricher'
+  | 'mutation-guard'
+  | 'api-interceptor-bridge'
+  | 'command-interceptor-bridge'
+  | 'widget-injection-consumer'
+  | 'component-extension-consumer'
+  | 'dashboard-host-consumer'
+
+export type ModuleExtensionTargetRef = {
+  kind:
+    | 'module'
+    | 'entity'
+    | 'api-route'
+    | 'command'
+    | 'widget-spot'
+    | 'component'
+    | 'event'
+    | 'notification'
+    | 'wildcard'
+  id: string
+  moduleId?: string
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+}
+
+export type ModuleExtensionActivation = {
+  id: string
+  kind: ModuleExtensionActivationKind
+  host: ModuleExtensionTargetRef
+  contributionKinds: ModuleExtensionContributionKind[]
+  phases?: string[]
+  /**
+   * Mutation operations the call site guards, when statically declared. A
+   * contribution declaring only other operations is not bound by this activation.
+   */
+  operations?: string[]
+  source: ModuleFactSourceRef
+  bridge?: ModuleFactRef
+}
+
+export type ModuleExtensionResolution =
+  | 'bound'
+  | 'capability-only'
+  | 'optional-target-missing'
+  | 'wildcard'
+  | 'unresolved'
+
+export type ModuleIncomingExtensionRef = {
+  contributionId: string
+  contributionKind: ModuleExtensionContributionKind
+  contributorModuleId: string
+  target: ModuleExtensionTargetRef
+  activationId?: string
+  resolution: ModuleExtensionResolution
+  source: ModuleFactSourceRef
+}
+
+export type ModuleContributionResolution = {
+  contributionId: string
+  target: ModuleExtensionTargetRef
+  resolution: ModuleExtensionResolution
+  activationIds: string[]
+}
+
+/**
+ * Additive, optional bidirectional-topology fields layered on top of the
+ * existing extension-surface facts. Every field is optional so legacy consumers
+ * and pre-existing generated output remain byte-compatible.
+ */
+export type ModuleExtensionSurfaceFactsAdditions = {
+  activations?: ModuleExtensionActivation[]
+  incoming?: ModuleIncomingExtensionRef[]
+  contributionResolutions?: ModuleContributionResolution[]
+}
+
 export type ModuleExtensionSurfaceFacts = {
   hosts: ModuleExtensionHostFact[]
   contributions: ModuleExtensionContributionFact[]
   unresolved: ModuleExtensionUnresolvedFact[]
-}
+} & ModuleExtensionSurfaceFactsAdditions
 
 export type ModuleExtensionHostFact = {
   key: string
@@ -390,6 +487,12 @@ export type ModuleExtensionContributionFact = ModuleExtensionContributionBase &
         audienceScopeContract: string
         maxPayloadBytes?: number
         dedupWindowMs?: number
+        /**
+         * Statically declared handler id. Runtime keys `notifications.handlers`
+         * overrides by it, so it is absent when the module declares no id (such a
+         * handler cannot be overridden).
+         */
+        overrideKey?: string
       }
     }
   | {