@open-mercato/core 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/modules/communication_channels/lib/oauth-state.ts

@@ -0,0 +1,228 @@
+import crypto from 'node:crypto'
+
+/**
+ * OAuth state-cookie helper for the communication_channels hub.
+ *
+ * **Ported (re-implemented locally), NOT imported, from `packages/enterprise/src/modules/sso/lib/state-cookie.ts`.**
+ * Root `AGENTS.md` rule: `@open-mercato/core` MUST NOT import from `@open-mercato/enterprise`.
+ *
+ * Design (per email integration spec § OSS Independence + § Hub Deltas → Delta 7):
+ *   - AES-256-GCM payload encryption.
+ *   - HKDF (SHA-256) key derivation from `OM_HUB_OAUTH_STATE_KEY` (falling back to
+ *     `KMS_MASTER_KEY`). In production those dedicated keys are required; only in
+ *     dev/test do we fall back to `JWT_SECRET` so envs that configure one secret
+ *     still work. Production refuses the `JWT_SECRET` fallback so a session-secret
+ *     leak cannot also forge OAuth-state cookies.
+ *   - 5-minute TTL — short window to bound replay surface.
+ *   - Payload binds the initiating `userId` so the callback rejects state cookies
+ *     used by a different session.
+ *
+ * The output is a base64url string that we set on an HttpOnly + SameSite=Lax cookie.
+ * Forgery requires the encryption key (KMS-managed in production).
+ */
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_LENGTH = 12
+const TAG_LENGTH = 16
+export const COMMUNICATION_CHANNELS_OAUTH_STATE_TTL_MS = 5 * 60 * 1000
+const HKDF_SALT = Buffer.from('open-mercato-channels-oauth-state-v1')
+const HKDF_INFO = Buffer.from('communication_channels-oauth-state-cookie')
+
+export const COMMUNICATION_CHANNELS_OAUTH_STATE_COOKIE_NAME =
+  'om_cc_oauth_state'
+
+export const DEFAULT_OAUTH_RETURN_URL = '/backend/profile/communication-channels'
+
+/** Errors thrown by the helpers. Stable for tests + route mapping. */
+export class OAuthStateError extends Error {
+  override name = 'OAuthStateError'
+  constructor(
+    message: string,
+    readonly code:
+      | 'missing_secret'
+      | 'invalid_cookie'
+      | 'expired'
+      | 'user_mismatch'
+      | 'decrypt_failed',
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * Canonical state-cookie payload — provider-agnostic. Each OAuth provider
+ * adapter (Gmail, …) packs its own per-flow nonce / verifier into
+ * the `extra` field rather than extending this shape.
+ */
+export interface OAuthStatePayload {
+  /** Nonce-like opaque value mirrored into the OAuth `state` query parameter. */
+  state: string
+  /** Per-flow CSRF nonce, returned alongside the OAuth response. */
+  nonce: string
+  /** Tenant-scoped user that initiated the flow. Validated on callback. */
+  userId: string
+  /** Tenant scope so the callback can pin the channel to the same tenant. */
+  tenantId: string
+  /** Optional organization id for multi-org tenants. */
+  organizationId?: string | null
+  /** Provider key (e.g. `gmail`) — routes the callback. */
+  providerKey: string
+  /** Where to redirect on success. Defaults to the profile page in the route. */
+  returnUrl?: string
+  /** Wall-clock expiry (ms since epoch). */
+  expiresAt: number
+  /** Provider-specific extras (PKCE code_verifier, scopes, login_hint, …). */
+  extra?: Record<string, unknown>
+}
+
+export function isSafeOAuthReturnUrl(value: string | null | undefined): value is string {
+  if (typeof value !== 'string') return false
+  if (value.length === 0 || value.length > 2048) return false
+  if (!value.startsWith('/') || value.startsWith('//')) return false
+  if (value.includes('\\')) return false
+  try {
+    const base = new URL('https://open-mercato.local')
+    const parsed = new URL(value, base)
+    return parsed.origin === base.origin && parsed.pathname.startsWith('/')
+  } catch {
+    return false
+  }
+}
+
+export function normalizeOAuthReturnUrl(
+  value: string | null | undefined,
+  fallback: string = DEFAULT_OAUTH_RETURN_URL,
+): string {
+  return isSafeOAuthReturnUrl(value) ? value : fallback
+}
+
+function deriveKey(secret: string): Buffer {
+  return Buffer.from(crypto.hkdfSync('sha256', secret, HKDF_SALT, HKDF_INFO, 32))
+}
+
+function getSecret(): string {
+  const dedicated = process.env.OM_HUB_OAUTH_STATE_KEY ?? process.env.KMS_MASTER_KEY
+  if (dedicated) return dedicated
+  // No dedicated key configured. Fail closed in production rather than deriving
+  // the state-cookie key from JWT_SECRET (the platform session-signing secret) —
+  // sharing that key means a JWT_SECRET leak also lets an attacker forge OAuth
+  // state cookies, bypassing the userId/tenant binding. In non-production we fall
+  // back to JWT_SECRET so dev/test envs that only configure one secret still work.
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('[internal] OM_HUB_OAUTH_STATE_KEY or KMS_MASTER_KEY required in production')
+  }
+  const fallback = process.env.JWT_SECRET
+  if (!fallback) {
+    throw new OAuthStateError(
+      'OM_HUB_OAUTH_STATE_KEY (or fallback KMS_MASTER_KEY / JWT_SECRET) must be set',
+      'missing_secret',
+    )
+  }
+  return fallback
+}
+
+/** Encrypt + sign a state payload. Output is a base64url string suitable for a cookie. */
+export function encryptOAuthState(payload: OAuthStatePayload): string {
+  const key = deriveKey(getSecret())
+  const iv = crypto.randomBytes(IV_LENGTH)
+  const json = JSON.stringify(payload)
+
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv)
+  const ciphertext = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+
+  return Buffer.concat([iv, tag, ciphertext]).toString('base64url')
+}
+
+/**
+ * Decrypt + verify a state cookie. Returns the payload or `null` if the cookie
+ * is malformed / tampered. Returns the payload (NOT null) when the cookie has
+ * expired — callers should check `expiresAt` themselves with the verification
+ * helper below for stable status codes.
+ */
+export function decryptOAuthState(cookie: string): OAuthStatePayload | null {
+  try {
+    const key = deriveKey(getSecret())
+    const combined = Buffer.from(cookie, 'base64url')
+    if (combined.length < IV_LENGTH + TAG_LENGTH) return null
+
+    const iv = combined.subarray(0, IV_LENGTH)
+    const tag = combined.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH)
+    const ciphertext = combined.subarray(IV_LENGTH + TAG_LENGTH)
+
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv)
+    decipher.setAuthTag(tag)
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')
+
+    return JSON.parse(decrypted) as OAuthStatePayload
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Verify a state cookie against the current session.
+ *
+ * Throws an {@link OAuthStateError} with a stable `code` field on any check
+ * failure so route handlers can map to consistent HTTP responses + redirect
+ * flash codes.
+ */
+export function verifyOAuthState(input: {
+  cookie: string | null | undefined
+  expectedUserId: string
+  expectedProviderKey?: string
+  expectedState?: string
+  now?: number
+}): OAuthStatePayload {
+  if (!input.cookie) {
+    throw new OAuthStateError('Missing state cookie', 'invalid_cookie')
+  }
+  const payload = decryptOAuthState(input.cookie)
+  if (!payload) {
+    throw new OAuthStateError('Invalid state cookie', 'decrypt_failed')
+  }
+  const now = input.now ?? Date.now()
+  if (payload.expiresAt < now) {
+    throw new OAuthStateError('State cookie expired', 'expired')
+  }
+  if (payload.userId !== input.expectedUserId) {
+    throw new OAuthStateError('State cookie userId mismatch', 'user_mismatch')
+  }
+  if (input.expectedProviderKey && payload.providerKey !== input.expectedProviderKey) {
+    throw new OAuthStateError('State cookie providerKey mismatch', 'invalid_cookie')
+  }
+  if (input.expectedState && payload.state !== input.expectedState) {
+    throw new OAuthStateError('State cookie state nonce mismatch', 'invalid_cookie')
+  }
+  return payload
+}
+
+/**
+ * Create a fresh state payload + matching `state` query parameter. PKCE
+ * verifiers are NOT generated here — the provider adapter decides whether it
+ * needs PKCE and packs the verifier into `extra` itself.
+ */
+export function createOAuthState(params: {
+  userId: string
+  tenantId: string
+  organizationId?: string | null
+  providerKey: string
+  returnUrl?: string
+  extra?: Record<string, unknown>
+}): { payload: OAuthStatePayload; cookie: string; stateParam: string } {
+  const state = crypto.randomBytes(32).toString('base64url')
+  const nonce = crypto.randomBytes(16).toString('base64url')
+  const payload: OAuthStatePayload = {
+    state,
+    nonce,
+    userId: params.userId,
+    tenantId: params.tenantId,
+    organizationId: params.organizationId ?? null,
+    providerKey: params.providerKey,
+    returnUrl: params.returnUrl,
+    extra: params.extra,
+    expiresAt: Date.now() + COMMUNICATION_CHANNELS_OAUTH_STATE_TTL_MS,
+  }
+  const cookie = encryptOAuthState(payload)
+  return { payload, cookie, stateParam: state }
+}

package/src/modules/communication_channels/lib/oauth-token.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared OAuth2 token primitives for email channel providers. The authorize-URL
+ * shape, PKCE usage, and userinfo handling differ per provider (e.g. Gmail)
+ * and stay in each package — but the token response shape, the
+ * form-urlencoded token POST, and the expiry computation are identical, so they
+ * live here.
+ */
+
+export interface OAuthTokenResponse {
+  access_token: string
+  refresh_token?: string
+  expires_in?: number
+  scope?: string
+  token_type?: string
+  id_token?: string
+  error?: string
+  error_description?: string
+}
+
+/** Compute the absolute access-token expiry from `expires_in`, or `undefined` when absent. */
+export function tokenResponseToExpiresAt(
+  token: OAuthTokenResponse,
+  nowMs: number = Date.now(),
+): Date | undefined {
+  if (typeof token.expires_in !== 'number') return undefined
+  return new Date(nowMs + token.expires_in * 1000)
+}
+
+/** Hard timeout for a token endpoint round-trip (ms). Overridable via env. */
+const DEFAULT_OAUTH_TOKEN_TIMEOUT_MS = 10_000
+
+function resolveTokenTimeoutMs(): number {
+  const fromEnv = Number.parseInt(process.env.OM_OAUTH_TOKEN_TIMEOUT_MS ?? '', 10)
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : DEFAULT_OAUTH_TOKEN_TIMEOUT_MS
+}
+
+/**
+ * POST a form-urlencoded body to an OAuth token endpoint and return the parsed
+ * token response. Throws `${errorLabel}: <reason>` when the endpoint returns a
+ * non-2xx status, an `error` field, a non-JSON body, or does not respond within
+ * the timeout. Bounding the request matters because token refresh sits on the
+ * critical path of every poll/send — a hung token endpoint must fail fast, not
+ * block the worker, and a proxy HTML error page must surface the real status
+ * rather than a confusing JSON `SyntaxError`.
+ */
+export async function requestOAuthToken(
+  tokenUrl: string,
+  params: URLSearchParams,
+  options: { errorLabel: string },
+): Promise<OAuthTokenResponse> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), resolveTokenTimeoutMs())
+  let res: Response
+  try {
+    res = await fetch(tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: params.toString(),
+      signal: controller.signal,
+    })
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      throw new Error(`${options.errorLabel}: token endpoint timed out`)
+    }
+    throw new Error(`${options.errorLabel}: ${err instanceof Error ? err.message : String(err)}`)
+  } finally {
+    clearTimeout(timeout)
+  }
+
+  const raw = await res.text()
+  let body: OAuthTokenResponse
+  try {
+    body = JSON.parse(raw) as OAuthTokenResponse
+  } catch {
+    throw new Error(`${options.errorLabel}: non-JSON response (status ${res.status})`)
+  }
+  if (!res.ok || body.error) {
+    throw new Error(`${options.errorLabel}: ${body.error_description ?? body.error ?? res.statusText}`)
+  }
+  return body
+}

package/src/modules/communication_channels/lib/pg-errors.ts

@@ -0,0 +1,12 @@
+/**
+ * Detect a Postgres unique-constraint violation (SQLSTATE 23505) regardless of
+ * the ORM/driver layer that surfaces it. Shared across the hub's commands and
+ * lib helpers so duplicate-insert handling stays consistent module-wide.
+ */
+export function isUniqueViolation(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false
+  const code = (err as { code?: string }).code
+  if (code === '23505') return true // Postgres unique_violation
+  const message = (err as { message?: string }).message
+  return typeof message === 'string' && /duplicate key value|unique constraint/i.test(message)
+}

package/src/modules/communication_channels/lib/provider-health.ts

@@ -0,0 +1,47 @@
+import type { ZodType } from 'zod'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+
+export type EmailHealthStatus = 'healthy' | 'degraded' | 'unhealthy'
+
+export interface EmailHealthCheckResult {
+  status: EmailHealthStatus
+  message?: string
+  details?: Record<string, unknown>
+}
+
+export interface EmailHealthCheck {
+  check: (credentials: Record<string, unknown> | null, scope: IntegrationScope) => Promise<EmailHealthCheckResult>
+}
+
+/**
+ * Build a liveness probe for an OAuth-client-config integration. There is no
+ * access token at this layer (the hub passes the tenant-scoped OAuth client
+ * config, not per-user channel tokens), so a network call would always 401. The
+ * cheap, deterministic probe is: confirm the client config is present and
+ * well-formed. Per-user token validity is exercised on the channel itself
+ * (send / poll surface `requires_reauth`).
+ */
+export function makeClientConfigHealthCheck<T>(options: {
+  schema: ZodType<T>
+  providerLabel: string
+  healthyDetails?: (parsed: T) => Record<string, unknown>
+}): EmailHealthCheck {
+  return {
+    async check(credentials) {
+      const parsed = options.schema.safeParse(credentials ?? {})
+      if (!parsed.success) {
+        const first = parsed.error.issues[0]
+        return {
+          status: 'unhealthy',
+          message: `${options.providerLabel} OAuth client config invalid: ${first?.message ?? 'unknown validation error'}`,
+          details: { reason: 'invalid_oauth_client' },
+        }
+      }
+      return {
+        status: 'healthy',
+        message: `${options.providerLabel} OAuth client configured`,
+        details: { clientIdConfigured: true, ...(options.healthyDetails?.(parsed.data) ?? {}) },
+      }
+    },
+  }
+}

package/src/modules/communication_channels/lib/push-state.ts

@@ -0,0 +1,38 @@
+/**
+ * Channel-state keys owned by the push-delivery lifecycle (Spec C), written by the
+ * push register/renew commands rather than the sync cursor. They must survive a
+ * sync-cursor replacement so watch/subscription renewal keeps working.
+ */
+export const PUSH_STATE_KEYS = [
+  'pushStatus',
+  'watchExpirationMs',
+  'pubsubTopic',
+  'lastPushError',
+] as const
+
+/**
+ * Replace the channel sync-cursor state with the adapter's freshly decoded cursor
+ * while carrying forward the hub-owned push keys the cursor does not manage.
+ *
+ * This MUST be a full replace, never a `{ ...previous, ...next }` spread: adapters
+ * signal "drain finished" by OMITTING the mid-drain resumption tokens
+ * (`pendingHistoryPageToken`, `pendingMessagesPageToken`) from
+ * `next` (they are set to `undefined`, which `JSON.stringify` drops from the encoded
+ * cursor). A spread would retain a stale token from `previous` and mis-route the
+ * next push/poll cycle, so the poll worker and both push-sync workers share this
+ * helper to stay consistent.
+ */
+export function preservePushState(
+  previous: unknown,
+  next: Record<string, unknown>,
+): Record<string, unknown> {
+  const prev =
+    previous && typeof previous === 'object' && !Array.isArray(previous)
+      ? (previous as Record<string, unknown>)
+      : {}
+  const merged: Record<string, unknown> = { ...next }
+  for (const key of PUSH_STATE_KEYS) {
+    if (!(key in merged) && key in prev) merged[key] = prev[key]
+  }
+  return merged
+}

package/src/modules/communication_channels/lib/queue.ts

@@ -0,0 +1,66 @@
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+
+/**
+ * Queue helper for the communication_channels hub. Mirrors the
+ * shipping_carriers pattern (`getShippingCarrierQueue`) so the route
+ * and the worker share the same queue instance.
+ *
+ * Worker concurrency is also tunable via env (`COMMUNICATION_CHANNELS_QUEUE_CONCURRENCY`)
+ * with a sensible default of 10 (per SPEC-045d §6 inbound flow) and a hard ceiling of
+ * 20 (ARCHITECTURE §19 caps queue/worker concurrency at 20).
+ */
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export function getCommunicationChannelsQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const concurrency = Math.min(
+    20,
+    Math.max(
+      1,
+      Number.parseInt(process.env.COMMUNICATION_CHANNELS_QUEUE_CONCURRENCY ?? '10', 10) || 10,
+    ),
+  )
+  const created = createModuleQueue<Record<string, unknown>>(queueName, { concurrency })
+  queues.set(queueName, created)
+  return created
+}
+
+/** Canonical queue names exposed by the hub. */
+export const COMMUNICATION_CHANNELS_QUEUES = {
+  inbound: 'communication-channels-inbound',
+  outbound: 'communication-channels-outbound',
+  reactions: 'communication-channels-reactions',
+  /**
+   * Per-channel polling queue (email integration spec — Phase 0 Delta 6).
+   * Populated by `poll-tick` every scheduler tick; one entry per due channel.
+   * Processed by `workers/poll-channel.ts`.
+   */
+  poll: 'communication-channels-poll',
+  /**
+   * Hub-internal tick queue (email integration spec — Phase 0 Delta 6).
+   * One job per scheduler tick (60s default); worker enumerates due channels
+   * and fans out to the `poll` queue.
+   */
+  pollTick: 'communication-channels-poll-tick',
+  /**
+   * Operator-triggered channel-history import queue (Spec B § Phase B6).
+   * One job per `/import-history` call; worker `channel-import-history` runs
+   * with concurrency 1 to avoid hammering the provider with parallel scans.
+   */
+  importHistory: 'communication-channels-import-history',
+  /**
+   * Spec C § Phase C2 — Gmail Pub/Sub push delivery. The webhook enqueues
+   * one job per verified notification; the worker calls
+   * `adapter.applyPushNotification` (which delegates to `history.list`).
+   */
+  gmailHistorySync: 'communication-channels-gmail-history-sync',
+  /**
+   * Spec C § Phase C4 — Renewal cron queues (daily / 2h cadence).
+   */
+  gmailRenewWatch: 'communication-channels-gmail-renew-watch',
+} as const
+
+export type CommunicationChannelsQueueName =
+  (typeof COMMUNICATION_CHANNELS_QUEUES)[keyof typeof COMMUNICATION_CHANNELS_QUEUES]

package/src/modules/communication_channels/lib/reaction-processor-types.ts

@@ -0,0 +1,51 @@
+import type { InboundReactionEvent } from './adapter'
+
+/**
+ * Discriminated union of reaction-queue job payloads.
+ *
+ * Split into its own file so command modules can reference these types without
+ * forming a circular import with the worker module (which references commands).
+ */
+
+export type ReactionScope = {
+  tenantId: string
+  organizationId: string | null
+}
+
+export type ReactionJobBase = {
+  providerKey: string
+  channelId: string
+  scope: ReactionScope
+  /** Attempt number, 1-based. */
+  attempt?: number
+}
+
+export type ReactionInboundJob = ReactionJobBase & {
+  kind: 'inbound'
+  channelType: string
+  event: InboundReactionEvent
+}
+
+export type ReactionOutboundSendJob = ReactionJobBase & {
+  kind: 'outbound_send'
+  messageId: string
+  reactionId: string
+  emoji: string
+  /** External conversation reference for the provider call (e.g. Slack thread_ts). */
+  conversationId?: string
+}
+
+export type ReactionOutboundRemoveJob = ReactionJobBase & {
+  kind: 'outbound_remove'
+  messageId: string
+  emoji: string
+  externalReactionId: string | null
+  conversationId?: string
+}
+
+export type ReactionProcessorPayload =
+  | ReactionInboundJob
+  | ReactionOutboundSendJob
+  | ReactionOutboundRemoveJob
+
+export const REACTION_PROCESSOR_MAX_ATTEMPTS = 3

package/src/modules/communication_channels/lib/reaction-semantics.ts

@@ -0,0 +1,48 @@
+import type { ChannelCapabilities } from './adapter'
+
+/**
+ * Reaction semantics — capability-driven decisions about how the hub applies an
+ * incoming or outgoing reaction.
+ *
+ * The platform-side `MessageReaction` table can record any number of rows per
+ * (messageId, reactor); the channel-specific semantics decide whether to keep
+ * existing reactions when a new one arrives:
+ *
+ *   - **Multi-per-user** (Slack default; `multiReactionPerUser: true`):
+ *     keep all existing reactions from the same reactor; just insert the new one.
+ *
+ *   - **Single-per-user** (WhatsApp default; `multiReactionPerUser: false`):
+ *     delete all existing reactions from the same reactor for the same message,
+ *     then insert the new one. This matches WhatsApp's "one reaction per user"
+ *     UI behaviour.
+ *
+ * The helper functions here are pure — they don't talk to the database. The
+ * command layer that consumes them is responsible for the actual DELETE/INSERT.
+ */
+
+/**
+ * Returns true when the channel's capabilities allow multiple reactions from
+ * the same reactor on the same message (Slack-like).
+ */
+export function allowsMultipleReactionsPerUser(
+  capabilities: Pick<ChannelCapabilities, 'multiReactionPerUser'> | null | undefined,
+): boolean {
+  // Default to false for safety — a missing capability declaration should not
+  // accidentally enable multi-reactions. Real adapters explicitly declare both
+  // booleans per SPEC-045d §1.1.
+  return capabilities?.multiReactionPerUser === true
+}
+
+/**
+ * Computes what mutation a new inbound `added` reaction implies, given the
+ * channel's capabilities. Pure — no DB calls. The caller maps the result to
+ * SQL.
+ *
+ * @returns `'insert'` to just persist the new reaction; `'replace'` to delete
+ *   every reaction from the same reactor for the same message before inserting.
+ */
+export function resolveInboundAddMutation(
+  capabilities: Pick<ChannelCapabilities, 'multiReactionPerUser'> | null | undefined,
+): 'insert' | 'replace' {
+  return allowsMultipleReactionsPerUser(capabilities) ? 'insert' : 'replace'
+}

package/src/modules/communication_channels/lib/registry.ts

@@ -0,0 +1,99 @@
+import type { ChannelAdapter } from './adapter'
+import { validateAdapterCapabilities } from './adapter-compat'
+
+/**
+ * Channel adapter registry — process-level singleton backed by `globalThis`.
+ *
+ * Mirrors the `shipping_carriers/lib/adapter-registry.ts` pattern so that
+ * unauthenticated webhook routes (which have not yet built a tenant-scoped DI
+ * container) can resolve adapters by `providerKey`. DI consumers continue to
+ * resolve the same registry via the `channelAdapterRegistry` binding declared
+ * in `di.ts` — that binding is a thin proxy over these functions.
+ *
+ * The registry validates each adapter at registration time (see
+ * `validateAdapterCapabilities`) and refuses duplicate `providerKey` registrations.
+ */
+
+const CHANNEL_ADAPTER_REGISTRY_KEY = Symbol.for('@open-mercato/communication-channels/adapter-registry')
+
+type GlobalWithChannelRegistry = typeof globalThis & {
+  [CHANNEL_ADAPTER_REGISTRY_KEY]?: Map<string, ChannelAdapter>
+}
+
+function getRegistryMap(): Map<string, ChannelAdapter> {
+  const scope = globalThis as GlobalWithChannelRegistry
+  if (!scope[CHANNEL_ADAPTER_REGISTRY_KEY]) {
+    scope[CHANNEL_ADAPTER_REGISTRY_KEY] = new Map<string, ChannelAdapter>()
+  }
+  return scope[CHANNEL_ADAPTER_REGISTRY_KEY]!
+}
+
+export function registerChannelAdapter(adapter: ChannelAdapter): () => void {
+  validateAdapterCapabilities(adapter)
+  const map = getRegistryMap()
+  if (map.has(adapter.providerKey)) {
+    throw new Error(
+      `ChannelAdapter '${adapter.providerKey}' is already registered. ` +
+        'Each provider package must declare a unique providerKey.',
+    )
+  }
+  map.set(adapter.providerKey, adapter)
+  return () => {
+    map.delete(adapter.providerKey)
+  }
+}
+
+export function getChannelAdapter(providerKey: string): ChannelAdapter | undefined {
+  return getRegistryMap().get(providerKey)
+}
+
+export function listChannelAdapters(): ChannelAdapter[] {
+  return Array.from(getRegistryMap().values())
+}
+
+export function listChannelAdapterProviderKeys(): string[] {
+  return Array.from(getRegistryMap().keys())
+}
+
+export function hasChannelAdapter(providerKey: string): boolean {
+  return getRegistryMap().has(providerKey)
+}
+
+/**
+ * Clear the registry. Primarily for tests that need a fresh registry between cases.
+ * NOT for production use — at runtime, adapters are registered once at boot.
+ */
+export function clearChannelAdapters(): void {
+  getRegistryMap().clear()
+}
+
+/**
+ * Class wrapper kept for DI consumers and test ergonomics. All instances back
+ * onto the same `globalThis` storage so DI consumers and direct module callers
+ * see the same registry.
+ */
+export class ChannelAdapterRegistry {
+  register(adapter: ChannelAdapter): void {
+    registerChannelAdapter(adapter)
+  }
+
+  get(providerKey: string): ChannelAdapter | undefined {
+    return getChannelAdapter(providerKey)
+  }
+
+  list(): ChannelAdapter[] {
+    return listChannelAdapters()
+  }
+
+  providerKeys(): string[] {
+    return listChannelAdapterProviderKeys()
+  }
+
+  has(providerKey: string): boolean {
+    return hasChannelAdapter(providerKey)
+  }
+
+  clear(): void {
+    clearChannelAdapters()
+  }
+}