@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4393.1.de282b5dfd

package/dist/modules/communication_channels/lib/thread-matcher.js

@@ -0,0 +1,263 @@
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { ChannelThreadMapping, ChannelThreadToken } from "../data/entities.js";
+import { extractTokenFromBody, extractTokenFromHeaders } from "./thread-token.js";
+const SUBJECT_PREFIX_PATTERN = /^\s*((?:re|fwd|fw|aw|wg|sv|tr|antw)\s*[:\-]\s*|\[[^\]]+\]\s*)+/i;
+const PARTICIPANT_LOOKBACK_DAYS = 30;
+const MAX_REFERENCES_TO_SCAN = 40;
+function normalizeSubject(subject) {
+  if (typeof subject !== "string") return "";
+  let current = subject.trim();
+  let safety = 16;
+  while (safety > 0 && SUBJECT_PREFIX_PATTERN.test(current)) {
+    current = current.replace(SUBJECT_PREFIX_PATTERN, "").trim();
+    safety -= 1;
+  }
+  return current.toLowerCase();
+}
+async function matchThread(input, deps) {
+  const { em, now } = deps;
+  const tenantId = input.tenantId;
+  const dscope = { tenantId, organizationId: input.organizationId };
+  const headerToken = extractTokenFromHeaders(input.inReplyTo, input.references);
+  if (headerToken) {
+    const threadId = await resolveTokenThread(em, dscope, {
+      tenantId,
+      channelId: input.channelId,
+      token: headerToken,
+      now
+    });
+    if (threadId) {
+      return {
+        messageThreadId: threadId,
+        matchedBy: "token-references",
+        confidence: "high"
+      };
+    }
+  }
+  const bodyToken = extractTokenFromBody(input.bodyHtml, input.bodyPlain);
+  if (bodyToken) {
+    const threadId = await resolveTokenThread(em, dscope, {
+      tenantId,
+      channelId: input.channelId,
+      token: bodyToken,
+      now
+    });
+    if (threadId) {
+      return {
+        messageThreadId: threadId,
+        matchedBy: "token-body",
+        confidence: "high"
+      };
+    }
+  }
+  const candidates = collectReferenceCandidates(input.inReplyTo, input.references);
+  if (candidates.length > 0) {
+    const jwzMatch = await findThreadByMessageIds(em, {
+      tenantId,
+      organizationId: input.organizationId,
+      channelId: input.channelId,
+      messageIds: candidates
+    });
+    if (jwzMatch) {
+      return {
+        messageThreadId: jwzMatch,
+        matchedBy: "jwz-headers",
+        confidence: "medium"
+      };
+    }
+  }
+  const normalizedSubject = normalizeSubject(input.subject);
+  if (normalizedSubject.length > 0) {
+    const cutoff = subtractDays((now ?? (() => /* @__PURE__ */ new Date()))(), PARTICIPANT_LOOKBACK_DAYS);
+    const participants = collectParticipants(input);
+    if (participants.length > 0) {
+      const subjectMatch = await findThreadBySubjectParticipants(em, {
+        tenantId,
+        organizationId: input.organizationId,
+        channelId: input.channelId,
+        normalizedSubject,
+        participants,
+        cutoff
+      });
+      if (subjectMatch) {
+        return {
+          messageThreadId: subjectMatch,
+          matchedBy: "subject-participants",
+          confidence: "low"
+        };
+      }
+    }
+  }
+  return null;
+}
+async function resolveTokenThread(em, dscope, args) {
+  const row = await findOneWithDecryption(
+    em,
+    ChannelThreadToken,
+    {
+      tenantId: args.tenantId,
+      organizationId: dscope.organizationId,
+      token: args.token
+    },
+    void 0,
+    dscope
+  );
+  if (!row) return null;
+  const mapping = await findOneWithDecryption(
+    em,
+    ChannelThreadMapping,
+    {
+      tenantId: args.tenantId,
+      organizationId: dscope.organizationId,
+      messageThreadId: row.messageThreadId,
+      channelId: args.channelId
+    },
+    void 0,
+    dscope
+  );
+  if (!mapping) return null;
+  await em.getConnection().execute(
+    `UPDATE channel_thread_tokens
+        SET last_seen_at = ?
+      WHERE id = ?
+        AND tenant_id = ?
+        AND ((?::uuid IS NULL AND organization_id IS NULL) OR organization_id = ?::uuid)`,
+    [
+      (args.now ?? (() => /* @__PURE__ */ new Date()))(),
+      row.id,
+      args.tenantId,
+      dscope.organizationId,
+      dscope.organizationId
+    ]
+  );
+  return row.messageThreadId;
+}
+function collectReferenceCandidates(inReplyTo, references) {
+  const out = [];
+  const push = (value) => {
+    if (typeof value !== "string") return;
+    const stripped = value.replace(/^<|>$/g, "").trim();
+    if (stripped.length > 0) out.push(stripped);
+  };
+  push(inReplyTo);
+  if (Array.isArray(references)) {
+    for (const ref of references) push(ref);
+  }
+  return Array.from(new Set(out)).slice(0, MAX_REFERENCES_TO_SCAN);
+}
+async function findThreadByMessageIds(em, args) {
+  if (args.messageIds.length === 0) return null;
+  const idArray = `{${args.messageIds.map((id) => `"${id.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(",")}}`;
+  const rows = await em.getConnection().execute(
+    `SELECT link.message_id FROM message_channel_links AS link
+       INNER JOIN external_conversations AS conv
+         ON conv.id = link.external_conversation_id
+      WHERE link.tenant_id = ?
+        AND ((?::uuid IS NULL AND link.organization_id IS NULL) OR link.organization_id = ?::uuid)
+        AND conv.tenant_id = ?
+        AND ((?::uuid IS NULL AND conv.organization_id IS NULL) OR conv.organization_id = ?::uuid)
+        AND conv.channel_id = ?
+        AND link.channel_metadata->>'messageId' = ANY(?::text[])
+      LIMIT 1`,
+    [
+      args.tenantId,
+      args.organizationId,
+      args.organizationId,
+      args.tenantId,
+      args.organizationId,
+      args.organizationId,
+      args.channelId,
+      idArray
+    ]
+  );
+  if (!rows || rows.length === 0) return null;
+  const messageId = rows[0].message_id;
+  const threadRows = await em.getConnection().execute(
+    `SELECT thread_id FROM messages
+      WHERE id = ?
+        AND tenant_id = ?
+        AND ((?::uuid IS NULL AND organization_id IS NULL) OR organization_id = ?::uuid)
+        AND deleted_at IS NULL
+      LIMIT 1`,
+    [messageId, args.tenantId, args.organizationId, args.organizationId]
+  );
+  if (!threadRows || threadRows.length === 0) return null;
+  return threadRows[0].thread_id;
+}
+function collectParticipants(input) {
+  const set = /* @__PURE__ */ new Set();
+  const push = (value) => {
+    if (typeof value !== "string") return;
+    const cleaned = value.trim().toLowerCase();
+    if (cleaned.length > 0) set.add(cleaned);
+  };
+  push(input.fromAddress);
+  for (const addr of input.toAddresses) push(addr);
+  for (const addr of input.ccAddresses) push(addr);
+  return Array.from(set);
+}
+async function findThreadBySubjectParticipants(em, args) {
+  const subjectLowerLike = args.normalizedSubject;
+  const participantList = `{${args.participants.map((p) => `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(",")}}`;
+  const rows = await em.getConnection().execute(
+    `SELECT messages.thread_id
+       FROM message_channel_links AS link
+       INNER JOIN external_conversations AS conv
+         ON conv.id = link.external_conversation_id
+       INNER JOIN messages
+         ON messages.id = link.message_id
+         AND messages.tenant_id = link.tenant_id
+         AND ((link.organization_id IS NULL AND messages.organization_id IS NULL) OR messages.organization_id = link.organization_id)
+         AND messages.deleted_at IS NULL
+      WHERE link.tenant_id = ?
+        AND ((?::uuid IS NULL AND link.organization_id IS NULL) OR link.organization_id = ?::uuid)
+        AND conv.tenant_id = ?
+        AND ((?::uuid IS NULL AND conv.organization_id IS NULL) OR conv.organization_id = ?::uuid)
+        AND conv.channel_id = ?
+        AND link.created_at >= ?
+        AND lower(regexp_replace(coalesce(link.channel_metadata->>'subject', ''),
+              '^\\s*((re|fwd|fw|aw|wg|sv|tr|antw)\\s*[:\\-]\\s*|\\[[^\\]]+\\]\\s*)+',
+              '',
+              'i'
+            )) = ?
+        AND (
+          lower(coalesce(link.channel_metadata->>'from', '')) = ANY(?::text[])
+          OR EXISTS (
+            SELECT 1 FROM jsonb_array_elements_text(coalesce(link.channel_metadata->'to', '[]'::jsonb)) AS t(addr)
+              WHERE lower(t.addr) = ANY(?::text[])
+          )
+          OR EXISTS (
+            SELECT 1 FROM jsonb_array_elements_text(coalesce(link.channel_metadata->'cc', '[]'::jsonb)) AS t(addr)
+              WHERE lower(t.addr) = ANY(?::text[])
+          )
+        )
+      ORDER BY link.created_at DESC
+      LIMIT 1`,
+    [
+      args.tenantId,
+      args.organizationId,
+      args.organizationId,
+      args.tenantId,
+      args.organizationId,
+      args.organizationId,
+      args.channelId,
+      args.cutoff,
+      subjectLowerLike,
+      participantList,
+      participantList,
+      participantList
+    ]
+  );
+  if (!rows || rows.length === 0) return null;
+  return rows[0].thread_id;
+}
+function subtractDays(from, days) {
+  const next = new Date(from);
+  next.setUTCDate(next.getUTCDate() - days);
+  return next;
+}
+export {
+  matchThread,
+  normalizeSubject
+};
+//# sourceMappingURL=thread-matcher.js.map

package/dist/modules/communication_channels/lib/thread-matcher.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/thread-matcher.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { ChannelThreadMapping, ChannelThreadToken, MessageChannelLink } from '../data/entities'\nimport { extractTokenFromBody, extractTokenFromHeaders } from './thread-token'\n\n/**\n * Layered thread-matching for inbound messages. Five ordered strategies;\n * first hit wins.\n *\n *   1. Token in References / In-Reply-To headers  (high confidence)\n *   2. Token in body                              (high confidence)\n *   3. JWZ on Message-Id                          (medium confidence)\n *   4. Subject + participants (last 30 days)      (low confidence)\n *   5. None \u2192 caller creates a new thread\n *\n * All DB queries are tenant-scoped. The matcher returns the resolved\n * thread id (or null) and lets the caller perform the actual ingest. It\n * never flushes the caller's unit of work: the only write is a scoped raw\n * `UPDATE` that bumps a matched token's `last_seen_at` (a future-GC hint),\n * which does not touch the caller's pending entities.\n *\n * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`\n * \u00A7 4 Threading Algorithm.\n */\n\nexport type ThreadMatchInput = {\n  channelId: string\n  tenantId: string\n  organizationId: string | null\n\n  /** RFC 5322 Message-ID of this inbound message (no angle brackets). */\n  messageId: string | null\n  /** In-Reply-To header value (no angle brackets). */\n  inReplyTo: string | null\n  /** References header, ordered root \u2192 most recent. */\n  references: string[]\n\n  /** Already-normalized subject is preferred; we re-normalize defensively. */\n  subject: string\n  fromAddress: string\n  toAddresses: string[]\n  ccAddresses: string[]\n\n  bodyPlain: string | null\n  bodyHtml: string | null\n\n  receivedAt: Date\n}\n\nexport type ThreadMatchStrategy =\n  | 'token-references'\n  | 'token-body'\n  | 'jwz-headers'\n  | 'subject-participants'\n\nexport type ThreadMatchConfidence = 'high' | 'medium' | 'low'\n\nexport type ThreadMatch = {\n  messageThreadId: string\n  matchedBy: ThreadMatchStrategy\n  confidence: ThreadMatchConfidence\n}\n\nexport type ThreadMatcherDeps = {\n  em: EntityManager\n  /** Stable reference for testing \u2014 defaults to `new Date()`. */\n  now?: () => Date\n}\n\nconst SUBJECT_PREFIX_PATTERN = /^\\s*((?:re|fwd|fw|aw|wg|sv|tr|antw)\\s*[:\\-]\\s*|\\[[^\\]]+\\]\\s*)+/i\nconst PARTICIPANT_LOOKBACK_DAYS = 30\nconst MAX_REFERENCES_TO_SCAN = 40\n\n/**\n * Normalize a subject for low-confidence subject+participants matching:\n *   - Trim whitespace\n *   - Strip leading reply/forward prefixes (`Re:`, `RE:`, `Aw:`, `Fwd:`, `Tr:`, `WG:`, `Sv:`, etc.)\n *   - Strip leading bracketed tags (`[EXTERNAL]`, `[Encrypted]`, `[SPAM?]`, \u2026)\n *   - Repeat until the pattern no longer matches\n *   - Lowercase the result\n *\n * Returns an empty string for `null`/empty input \u2014 the caller should\n * skip the subject+participants strategy in that case.\n */\nexport function normalizeSubject(subject: string | null | undefined): string {\n  if (typeof subject !== 'string') return ''\n  let current = subject.trim()\n  // Loop until no prefix matches \u2014 handles `Re: Fwd: [EXTERNAL] Re: \u2026`.\n  let safety = 16\n  while (safety > 0 && SUBJECT_PREFIX_PATTERN.test(current)) {\n    current = current.replace(SUBJECT_PREFIX_PATTERN, '').trim()\n    safety -= 1\n  }\n  return current.toLowerCase()\n}\n\nexport async function matchThread(\n  input: ThreadMatchInput,\n  deps: ThreadMatcherDeps,\n): Promise<ThreadMatch | null> {\n  const { em, now } = deps\n  const tenantId = input.tenantId\n  const dscope = { tenantId, organizationId: input.organizationId }\n\n  // Strategy 1: token in References / In-Reply-To header.\n  const headerToken = extractTokenFromHeaders(input.inReplyTo, input.references)\n  if (headerToken) {\n    const threadId = await resolveTokenThread(em, dscope, {\n      tenantId,\n      channelId: input.channelId,\n      token: headerToken,\n      now,\n    })\n    if (threadId) {\n      return {\n        messageThreadId: threadId,\n        matchedBy: 'token-references',\n        confidence: 'high',\n      }\n    }\n  }\n\n  // Strategy 2: token in body.\n  const bodyToken = extractTokenFromBody(input.bodyHtml, input.bodyPlain)\n  if (bodyToken) {\n    const threadId = await resolveTokenThread(em, dscope, {\n      tenantId,\n      channelId: input.channelId,\n      token: bodyToken,\n      now,\n    })\n    if (threadId) {\n      return {\n        messageThreadId: threadId,\n        matchedBy: 'token-body',\n        confidence: 'high',\n      }\n    }\n  }\n\n  // Strategy 3: JWZ \u2014 find any MessageChannelLink in this channel whose\n  // recorded `channelMetadata.messageId` matches In-Reply-To or any of the\n  // References values. The first hit's `messages.message.threadId` is our\n  // thread. Bounded by MAX_REFERENCES_TO_SCAN.\n  const candidates = collectReferenceCandidates(input.inReplyTo, input.references)\n  if (candidates.length > 0) {\n    const jwzMatch = await findThreadByMessageIds(em, {\n      tenantId,\n      organizationId: input.organizationId,\n      channelId: input.channelId,\n      messageIds: candidates,\n    })\n    if (jwzMatch) {\n      return {\n        messageThreadId: jwzMatch,\n        matchedBy: 'jwz-headers',\n        confidence: 'medium',\n      }\n    }\n  }\n\n  // Strategy 4: subject + participants in the same channel within 30 days.\n  // Low confidence \u2014 never used to overwrite a stronger token-based match\n  // (we already returned above on hits). The caller may still choose to\n  // create a new thread when confidence === 'low'.\n  const normalizedSubject = normalizeSubject(input.subject)\n  if (normalizedSubject.length > 0) {\n    const cutoff = subtractDays((now ?? (() => new Date()))(), PARTICIPANT_LOOKBACK_DAYS)\n    const participants = collectParticipants(input)\n    if (participants.length > 0) {\n      const subjectMatch = await findThreadBySubjectParticipants(em, {\n        tenantId,\n        organizationId: input.organizationId,\n        channelId: input.channelId,\n        normalizedSubject,\n        participants,\n        cutoff,\n      })\n      if (subjectMatch) {\n        return {\n          messageThreadId: subjectMatch,\n          matchedBy: 'subject-participants',\n          confidence: 'low',\n        }\n      }\n    }\n  }\n\n  // No match \u2014 caller creates a new thread.\n  return null\n}\n\n/**\n * Resolve a thread token to its `messageThreadId`, but ONLY when that thread\n * belongs to the channel that received the inbound message.\n *\n * The token is unguessable + HMAC-signed + tenant-scoped, so it cannot leak\n * across tenants. Within a tenant, though, the same external contact may\n * correspond with several users/channels \u2014 and a thread token that ends up in\n * a *different* mailbox (e.g. a forwarded thread) must not graft the inbound\n * message onto another channel's thread. The `ChannelThreadMapping`\n * (thread \u2194 channel) is the authoritative link; if there's no mapping joining\n * this thread to the receiving channel, we treat the token as a non-match and\n * let the lower-confidence strategies (or a fresh thread) take over.\n *\n * Returns the thread id on a verified hit (and bumps `last_seen_at`), else null.\n */\nasync function resolveTokenThread(\n  em: EntityManager,\n  dscope: { tenantId: string; organizationId: string | null },\n  args: { tenantId: string; channelId: string; token: string; now?: () => Date },\n): Promise<string | null> {\n  const row = await findOneWithDecryption(\n    em,\n    ChannelThreadToken,\n    {\n      tenantId: args.tenantId,\n      organizationId: dscope.organizationId,\n      token: args.token,\n    },\n    undefined,\n    dscope,\n  )\n  if (!row) return null\n\n  const mapping = await findOneWithDecryption(\n    em,\n    ChannelThreadMapping,\n    {\n      tenantId: args.tenantId,\n      organizationId: dscope.organizationId,\n      messageThreadId: row.messageThreadId,\n      channelId: args.channelId,\n    },\n    undefined,\n    dscope,\n  )\n  if (!mapping) return null\n\n  // Bump `last_seen_at` (future-GC hint) via a scoped raw UPDATE rather than\n  // `em.flush()`. A flush here would commit the ENTIRE unit of work, including\n  // any pending mutations the caller (`ingest-inbound-message`, shared by all\n  // provider adapters) holds \u2014 turning this \"pure\" matcher into a hidden commit\n  // boundary. The raw UPDATE keeps the matcher side-effect-free w.r.t. the\n  // caller's EntityManager.\n  await em.getConnection().execute(\n    `UPDATE channel_thread_tokens\n        SET last_seen_at = ?\n      WHERE id = ?\n        AND tenant_id = ?\n        AND ((?::uuid IS NULL AND organization_id IS NULL) OR organization_id = ?::uuid)`,\n    [\n      (args.now ?? (() => new Date()))(),\n      row.id,\n      args.tenantId,\n      dscope.organizationId,\n      dscope.organizationId,\n    ],\n  )\n  return row.messageThreadId\n}\n\nfunction collectReferenceCandidates(\n  inReplyTo: string | null,\n  references: string[] | undefined,\n): string[] {\n  const out: string[] = []\n  const push = (value: string | null | undefined): void => {\n    if (typeof value !== 'string') return\n    const stripped = value.replace(/^<|>$/g, '').trim()\n    if (stripped.length > 0) out.push(stripped)\n  }\n  push(inReplyTo)\n  if (Array.isArray(references)) {\n    for (const ref of references) push(ref)\n  }\n  return Array.from(new Set(out)).slice(0, MAX_REFERENCES_TO_SCAN)\n}\n\nasync function findThreadByMessageIds(\n  em: EntityManager,\n  args: { tenantId: string; organizationId: string | null; channelId: string; messageIds: string[] },\n): Promise<string | null> {\n  if (args.messageIds.length === 0) return null\n  // MikroORM v7 dropped the Knex builder; we use raw SQL via\n  // `em.getConnection().execute()` with positional placeholders. The JSONB\n  // lookup compares `channel_metadata->>'messageId'` against a Postgres\n  // text array built from the candidate message-ids.\n  // Escape backslash BEFORE quote \u2014 a Message-ID can legitimately contain `\\`\n  // (RFC 5322), and an unescaped backslash yields a malformed Postgres array\n  // literal that throws and silently defeats threading.\n  const idArray = `{${args.messageIds\n    .map((id) => `\"${id.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"')}\"`)\n    .join(',')}}`\n  const rows = await em.getConnection().execute<Array<{ message_id: string }>>(\n    `SELECT link.message_id FROM message_channel_links AS link\n       INNER JOIN external_conversations AS conv\n         ON conv.id = link.external_conversation_id\n      WHERE link.tenant_id = ?\n        AND ((?::uuid IS NULL AND link.organization_id IS NULL) OR link.organization_id = ?::uuid)\n        AND conv.tenant_id = ?\n        AND ((?::uuid IS NULL AND conv.organization_id IS NULL) OR conv.organization_id = ?::uuid)\n        AND conv.channel_id = ?\n        AND link.channel_metadata->>'messageId' = ANY(?::text[])\n      LIMIT 1`,\n    [\n      args.tenantId,\n      args.organizationId,\n      args.organizationId,\n      args.tenantId,\n      args.organizationId,\n      args.organizationId,\n      args.channelId,\n      idArray,\n    ],\n  )\n  if (!rows || rows.length === 0) return null\n\n  const messageId = rows[0].message_id as string\n  // Translate `messages.message.id` to `messages.message.thread_id`. We\n  // intentionally avoid importing the messages entity (cross-module rule).\n  const threadRows = await em.getConnection().execute<Array<{ thread_id: string | null }>>(\n    `SELECT thread_id FROM messages\n      WHERE id = ?\n        AND tenant_id = ?\n        AND ((?::uuid IS NULL AND organization_id IS NULL) OR organization_id = ?::uuid)\n        AND deleted_at IS NULL\n      LIMIT 1`,\n    [messageId, args.tenantId, args.organizationId, args.organizationId],\n  )\n  if (!threadRows || threadRows.length === 0) return null\n  return threadRows[0].thread_id as string | null\n}\n\nfunction collectParticipants(input: ThreadMatchInput): string[] {\n  const set = new Set<string>()\n  const push = (value: string | null | undefined): void => {\n    if (typeof value !== 'string') return\n    const cleaned = value.trim().toLowerCase()\n    if (cleaned.length > 0) set.add(cleaned)\n  }\n  push(input.fromAddress)\n  for (const addr of input.toAddresses) push(addr)\n  for (const addr of input.ccAddresses) push(addr)\n  return Array.from(set)\n}\n\nasync function findThreadBySubjectParticipants(\n  em: EntityManager,\n  args: {\n    tenantId: string\n    organizationId: string | null\n    channelId: string\n    normalizedSubject: string\n    participants: string[]\n    cutoff: Date\n  },\n): Promise<string | null> {\n  // MikroORM v7 raw SQL \u2014 see `findThreadByMessageIds` for the rationale.\n  // We look at recent links from this channel whose channelMetadata subject\n  // (server-side normalized) equals the inbound subject AND share at least\n  // one participant. The first match wins.\n  const subjectLowerLike = args.normalizedSubject\n  // Escape backslash before quote (see findThreadByMessageIds) \u2014 participant\n  // addresses are attacker-influenced inbound header values.\n  const participantList = `{${args.participants\n    .map((p) => `\"${p.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"')}\"`)\n    .join(',')}}`\n  const rows = await em.getConnection().execute<Array<{ thread_id: string | null }>>(\n    `SELECT messages.thread_id\n       FROM message_channel_links AS link\n       INNER JOIN external_conversations AS conv\n         ON conv.id = link.external_conversation_id\n       INNER JOIN messages\n         ON messages.id = link.message_id\n         AND messages.tenant_id = link.tenant_id\n         AND ((link.organization_id IS NULL AND messages.organization_id IS NULL) OR messages.organization_id = link.organization_id)\n         AND messages.deleted_at IS NULL\n      WHERE link.tenant_id = ?\n        AND ((?::uuid IS NULL AND link.organization_id IS NULL) OR link.organization_id = ?::uuid)\n        AND conv.tenant_id = ?\n        AND ((?::uuid IS NULL AND conv.organization_id IS NULL) OR conv.organization_id = ?::uuid)\n        AND conv.channel_id = ?\n        AND link.created_at >= ?\n        AND lower(regexp_replace(coalesce(link.channel_metadata->>'subject', ''),\n              '^\\\\s*((re|fwd|fw|aw|wg|sv|tr|antw)\\\\s*[:\\\\-]\\\\s*|\\\\[[^\\\\]]+\\\\]\\\\s*)+',\n              '',\n              'i'\n            )) = ?\n        AND (\n          lower(coalesce(link.channel_metadata->>'from', '')) = ANY(?::text[])\n          OR EXISTS (\n            SELECT 1 FROM jsonb_array_elements_text(coalesce(link.channel_metadata->'to', '[]'::jsonb)) AS t(addr)\n              WHERE lower(t.addr) = ANY(?::text[])\n          )\n          OR EXISTS (\n            SELECT 1 FROM jsonb_array_elements_text(coalesce(link.channel_metadata->'cc', '[]'::jsonb)) AS t(addr)\n              WHERE lower(t.addr) = ANY(?::text[])\n          )\n        )\n      ORDER BY link.created_at DESC\n      LIMIT 1`,\n    [\n      args.tenantId,\n      args.organizationId,\n      args.organizationId,\n      args.tenantId,\n      args.organizationId,\n      args.organizationId,\n      args.channelId,\n      args.cutoff,\n      subjectLowerLike,\n      participantList,\n      participantList,\n      participantList,\n    ],\n  )\n  if (!rows || rows.length === 0) return null\n  return rows[0].thread_id as string | null\n}\n\nfunction subtractDays(from: Date, days: number): Date {\n  const next = new Date(from)\n  next.setUTCDate(next.getUTCDate() - days)\n  return next\n}\n\n// Re-export `MessageChannelLink` so callers importing types from this module\n// don't have to reach into `data/entities.ts` indirectly.\nexport type { MessageChannelLink }\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/communication_channels/lib/thread-token.js

@@ -0,0 +1,219 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { ChannelThreadToken } from "../data/entities.js";
+import { isUniqueViolation } from "./pg-errors.js";
+const TOKEN_PREFIX = "om_";
+const RANDOM_BYTES = 16;
+const HMAC_BYTES = 8;
+const HMAC_KEY_ENV = "OM_THREAD_TOKEN_SECRET";
+const HMAC_FALLBACK_KEY_ENV = "KMS_MASTER_KEY";
+const HMAC_KEY_INFO = "thread-token";
+const TOKEN_REGEX = /om_[A-Za-z0-9_-]{22}_[A-Za-z0-9_-]{11}/;
+let cachedKey = null;
+function getKey() {
+  if (cachedKey) return cachedKey;
+  const primary = process.env[HMAC_KEY_ENV];
+  if (primary && primary.length > 0) {
+    cachedKey = Buffer.from(primary, "utf8");
+    return cachedKey;
+  }
+  const fallback = process.env[HMAC_FALLBACK_KEY_ENV];
+  if (fallback && fallback.length > 0) {
+    cachedKey = createHmac("sha256", fallback).update(HMAC_KEY_INFO).digest();
+    return cachedKey;
+  }
+  if (process.env.NODE_ENV === "production") {
+    throw new Error(
+      `[communication_channels] No ${HMAC_KEY_ENV} or ${HMAC_FALLBACK_KEY_ENV} configured \u2014 refusing to sign thread tokens with a static dev key in production.`
+    );
+  }
+  console.warn(
+    `[communication_channels] No ${HMAC_KEY_ENV} or ${HMAC_FALLBACK_KEY_ENV} configured. Thread tokens will use a dev-only static key \u2014 DO NOT USE IN PRODUCTION.`
+  );
+  cachedKey = createHash("sha256").update("open-mercato-thread-token-dev").digest();
+  return cachedKey;
+}
+function _resetThreadTokenKeyCache() {
+  cachedKey = null;
+}
+function base64urlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64urlDecode(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) return null;
+  const padded = value + "=".repeat((4 - value.length % 4) % 4);
+  try {
+    return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+  } catch {
+    return null;
+  }
+}
+function computeHmacBytes(random) {
+  return createHmac("sha256", getKey()).update(random).digest().subarray(0, HMAC_BYTES);
+}
+function generateToken() {
+  const random = randomBytes(RANDOM_BYTES);
+  const hmac = computeHmacBytes(random);
+  return `${TOKEN_PREFIX}${base64urlEncode(random)}_${base64urlEncode(hmac)}`;
+}
+const RANDOM_B64_LEN = Math.ceil(RANDOM_BYTES * 4 / 3);
+const HMAC_B64_LEN = Math.ceil(HMAC_BYTES * 4 / 3);
+const TOKEN_TOTAL_LEN = TOKEN_PREFIX.length + RANDOM_B64_LEN + 1 + HMAC_B64_LEN;
+function verifyToken(token) {
+  if (typeof token !== "string") return false;
+  if (token.length !== TOKEN_TOTAL_LEN) return false;
+  if (!token.startsWith(TOKEN_PREFIX)) return false;
+  const randomStart = TOKEN_PREFIX.length;
+  const randomEnd = randomStart + RANDOM_B64_LEN;
+  const separator = token[randomEnd];
+  if (separator !== "_") return false;
+  const hmacStart = randomEnd + 1;
+  const randomPart = token.slice(randomStart, randomEnd);
+  const hmacPart = token.slice(hmacStart, hmacStart + HMAC_B64_LEN);
+  const random = base64urlDecode(randomPart);
+  if (!random || random.length !== RANDOM_BYTES) return false;
+  const provided = base64urlDecode(hmacPart);
+  if (!provided || provided.length !== HMAC_BYTES) return false;
+  const expected = computeHmacBytes(random);
+  try {
+    return timingSafeEqual(provided, expected);
+  } catch {
+    return false;
+  }
+}
+function buildReferencesId(token) {
+  return `<${token}@open-mercato.invalid>`;
+}
+function buildBodyFooter(token) {
+  return {
+    html: `<span style="display:none">[OM:${token}]</span>`,
+    plain: `
+
+[OM:${token}]`
+  };
+}
+function applyOutboundThreadingToken(payload, token) {
+  if (!verifyToken(token)) {
+    throw new Error("applyOutboundThreadingToken: invalid token format/signature");
+  }
+  const refId = buildReferencesId(token);
+  const footer = buildBodyFooter(token);
+  const headers = { ...payload.headers ?? {} };
+  const existingRefs = headers["references"] ?? headers["References"];
+  let nextRefs;
+  if (Array.isArray(existingRefs)) {
+    nextRefs = existingRefs.includes(refId) ? existingRefs.join(" ") : [...existingRefs, refId].join(" ");
+  } else if (typeof existingRefs === "string" && existingRefs.length > 0) {
+    nextRefs = existingRefs.includes(refId) ? existingRefs : `${existingRefs} ${refId}`;
+  } else {
+    nextRefs = refId;
+  }
+  delete headers["references"];
+  headers["References"] = nextRefs;
+  let bodyHtml = payload.bodyHtml;
+  if (typeof bodyHtml === "string") {
+    if (!bodyHtml.includes(`[OM:${token}]`)) {
+      const closing = bodyHtml.lastIndexOf("</body>");
+      if (closing >= 0) {
+        bodyHtml = `${bodyHtml.slice(0, closing)}${footer.html}${bodyHtml.slice(closing)}`;
+      } else {
+        bodyHtml = `${bodyHtml}${footer.html}`;
+      }
+    }
+  }
+  let bodyText = payload.bodyText;
+  if (typeof bodyText === "string") {
+    if (!bodyText.includes(`[OM:${token}]`)) {
+      bodyText = `${bodyText}${footer.plain}`;
+    }
+  }
+  return {
+    ...payload,
+    headers,
+    ...bodyHtml !== void 0 ? { bodyHtml } : {},
+    ...bodyText !== void 0 ? { bodyText } : {}
+  };
+}
+function extractTokenFromHeaders(inReplyTo, references) {
+  const haystack = [];
+  if (typeof inReplyTo === "string" && inReplyTo.length > 0) haystack.push(inReplyTo);
+  if (Array.isArray(references)) haystack.push(...references);
+  else if (typeof references === "string" && references.length > 0) haystack.push(references);
+  for (const candidate of haystack) {
+    const matches = candidate.match(new RegExp(TOKEN_REGEX, "g"));
+    if (!matches) continue;
+    for (const match of matches) {
+      if (verifyToken(match)) return match;
+    }
+  }
+  return null;
+}
+async function getOrCreateThreadToken(em, args) {
+  const dscope = { tenantId: args.tenantId, organizationId: args.organizationId };
+  const existing = await findOneWithDecryption(
+    em,
+    ChannelThreadToken,
+    {
+      tenantId: args.tenantId,
+      organizationId: args.organizationId,
+      messageThreadId: args.messageThreadId
+    },
+    void 0,
+    dscope
+  );
+  if (existing) {
+    return { token: existing.token, created: false };
+  }
+  const row = em.create(ChannelThreadToken, {
+    tenantId: args.tenantId,
+    organizationId: args.organizationId,
+    messageThreadId: args.messageThreadId,
+    token: generateToken()
+  });
+  em.persist(row);
+  try {
+    await em.flush();
+    return { token: row.token, created: true };
+  } catch (err) {
+    if (!isUniqueViolation(err)) throw err;
+    const winner = await findOneWithDecryption(
+      em.fork(),
+      ChannelThreadToken,
+      {
+        tenantId: args.tenantId,
+        organizationId: args.organizationId,
+        messageThreadId: args.messageThreadId
+      },
+      void 0,
+      dscope
+    );
+    if (winner) return { token: winner.token, created: false };
+    throw err;
+  }
+}
+function extractTokenFromBody(bodyHtml, bodyText) {
+  const haystacks = [bodyHtml, bodyText].filter(
+    (value) => typeof value === "string" && value.length > 0
+  );
+  const pattern = new RegExp(`\\[OM:(${TOKEN_REGEX.source})\\]`, "g");
+  for (const haystack of haystacks) {
+    let match;
+    pattern.lastIndex = 0;
+    while ((match = pattern.exec(haystack)) !== null) {
+      if (verifyToken(match[1])) return match[1];
+    }
+  }
+  return null;
+}
+export {
+  _resetThreadTokenKeyCache,
+  applyOutboundThreadingToken,
+  buildBodyFooter,
+  buildReferencesId,
+  extractTokenFromBody,
+  extractTokenFromHeaders,
+  generateToken,
+  getOrCreateThreadToken,
+  verifyToken
+};
+//# sourceMappingURL=thread-token.js.map

package/dist/modules/communication_channels/lib/thread-token.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/thread-token.ts"],
+  "sourcesContent": ["import { createHash, createHmac, randomBytes, timingSafeEqual } from 'crypto'\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { ChannelThreadToken } from '../data/entities'\nimport { isUniqueViolation } from './pg-errors'\n\n/**\n * Per-thread crypto token used by the layered thread-matcher to attach\n * inbound replies to the originating Open Mercato message thread, even\n * when the recipient's mail client strips RFC 5322 headers.\n *\n * Token format: `om_<22b64url>_<11b64url>` \u2014 16 random bytes followed by\n * 8 bytes of HMAC-SHA256(random, key), each base64url-encoded without\n * padding. Approximately 37 characters total.\n *\n * Tokens are stored on the `channel_thread_tokens` table keyed by\n * `(tenantId, token)` so that even if the HMAC key leaked, tenant\n * isolation still holds at the DB layer.\n *\n * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`.\n */\n\nconst TOKEN_PREFIX = 'om_'\nconst RANDOM_BYTES = 16\nconst HMAC_BYTES = 8\nconst HMAC_KEY_ENV = 'OM_THREAD_TOKEN_SECRET'\nconst HMAC_FALLBACK_KEY_ENV = 'KMS_MASTER_KEY'\nconst HMAC_KEY_INFO = 'thread-token'\n\n/**\n * Pre-validated regex for parsing token candidates extracted from headers\n * or body content. Matches our exact format and rejects anything else\n * before HMAC verification \u2014 defense in depth.\n */\nconst TOKEN_REGEX = /om_[A-Za-z0-9_-]{22}_[A-Za-z0-9_-]{11}/\n\nlet cachedKey: Buffer | null = null\n\n/** Resolve the HMAC key. Falls back through env vars per the spec. */\nfunction getKey(): Buffer {\n  if (cachedKey) return cachedKey\n  const primary = process.env[HMAC_KEY_ENV]\n  if (primary && primary.length > 0) {\n    cachedKey = Buffer.from(primary, 'utf8')\n    return cachedKey\n  }\n  const fallback = process.env[HMAC_FALLBACK_KEY_ENV]\n  if (fallback && fallback.length > 0) {\n    // HKDF-style: derive a per-purpose subkey by HMAC-ing the fallback secret\n    // with a constant info label so different purposes don't share a key.\n    cachedKey = createHmac('sha256', fallback).update(HMAC_KEY_INFO).digest()\n    return cachedKey\n  }\n  // No secret configured. Fail closed in production rather than signing thread\n  // tokens with a public static key (which would let anyone forge a thread\n  // token). In non-production we fall back to a dev-only static key and warn.\n  if (process.env.NODE_ENV === 'production') {\n    throw new Error(\n      `[communication_channels] No ${HMAC_KEY_ENV} or ${HMAC_FALLBACK_KEY_ENV} configured \u2014` +\n        ' refusing to sign thread tokens with a static dev key in production.',\n    )\n  }\n  console.warn(\n    `[communication_channels] No ${HMAC_KEY_ENV} or ${HMAC_FALLBACK_KEY_ENV} configured.` +\n      ' Thread tokens will use a dev-only static key \u2014 DO NOT USE IN PRODUCTION.',\n  )\n  cachedKey = createHash('sha256').update('open-mercato-thread-token-dev').digest()\n  return cachedKey\n}\n\n/** Reset the cached key \u2014 for tests that mutate env vars. */\nexport function _resetThreadTokenKeyCache(): void {\n  cachedKey = null\n}\n\nfunction base64urlEncode(buf: Buffer): string {\n  return buf\n    .toString('base64')\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/g, '')\n}\n\nfunction base64urlDecode(value: string): Buffer | null {\n  if (!/^[A-Za-z0-9_-]+$/.test(value)) return null\n  const padded = value + '='.repeat((4 - (value.length % 4)) % 4)\n  try {\n    return Buffer.from(padded.replace(/-/g, '+').replace(/_/g, '/'), 'base64')\n  } catch {\n    return null\n  }\n}\n\nfunction computeHmacBytes(random: Buffer): Buffer {\n  return createHmac('sha256', getKey()).update(random).digest().subarray(0, HMAC_BYTES)\n}\n\n/**\n * Generate a new HMAC-signed thread token. The 16 random bytes make a token\n * collision astronomically unlikely; the `(tenantId, token)` unique constraint\n * is the backstop. Per-thread deduplication (one token per thread) is handled\n * separately by `getOrCreateThreadToken` via the `(tenantId, messageThreadId)`\n * unique constraint \u2014 not here.\n */\nexport function generateToken(): string {\n  const random = randomBytes(RANDOM_BYTES)\n  const hmac = computeHmacBytes(random)\n  return `${TOKEN_PREFIX}${base64urlEncode(random)}_${base64urlEncode(hmac)}`\n}\n\n// Fixed lengths of the base64url-encoded components, without padding.\n// Computed once: 16 bytes -> 22 chars, 8 bytes -> 11 chars.\nconst RANDOM_B64_LEN = Math.ceil((RANDOM_BYTES * 4) / 3)\nconst HMAC_B64_LEN = Math.ceil((HMAC_BYTES * 4) / 3)\nconst TOKEN_TOTAL_LEN = TOKEN_PREFIX.length + RANDOM_B64_LEN + 1 + HMAC_B64_LEN\n\n/**\n * Verify the HMAC signature on a token. Returns `true` only when the\n * structural form is correct AND the HMAC matches under the current key.\n *\n * Does NOT verify the token exists in the DB \u2014 that lookup is the\n * matcher's responsibility (see `thread-matcher.ts`). Verifying here\n * lets us drop forged tokens before any DB I/O.\n *\n * Parsing note: base64url-encoded random/HMAC portions may themselves\n * contain `_` characters, so `split('_')` is unsafe. We parse positionally\n * using the fixed lengths declared above.\n */\nexport function verifyToken(token: string): boolean {\n  if (typeof token !== 'string') return false\n  if (token.length !== TOKEN_TOTAL_LEN) return false\n  if (!token.startsWith(TOKEN_PREFIX)) return false\n  const randomStart = TOKEN_PREFIX.length\n  const randomEnd = randomStart + RANDOM_B64_LEN\n  const separator = token[randomEnd]\n  if (separator !== '_') return false\n  const hmacStart = randomEnd + 1\n  const randomPart = token.slice(randomStart, randomEnd)\n  const hmacPart = token.slice(hmacStart, hmacStart + HMAC_B64_LEN)\n  const random = base64urlDecode(randomPart)\n  if (!random || random.length !== RANDOM_BYTES) return false\n  const provided = base64urlDecode(hmacPart)\n  if (!provided || provided.length !== HMAC_BYTES) return false\n  const expected = computeHmacBytes(random)\n  try {\n    return timingSafeEqual(provided, expected)\n  } catch {\n    return false\n  }\n}\n\n/**\n * Build the synthetic RFC 5322 Message-ID we inject into outbound\n * `References:` headers. Uses the IANA-reserved `.invalid` TLD (RFC 6761\n * \u00A7 3) so RFC-compliant MTAs MUST accept it as syntactically valid.\n */\nexport function buildReferencesId(token: string): string {\n  return `<${token}@open-mercato.invalid>`\n}\n\n/**\n * Build the hidden HTML body span + plain-text trailer used as the\n * token's secondary attachment point (in case `References` is stripped\n * by the recipient's MUA).\n */\nexport function buildBodyFooter(token: string): { html: string; plain: string } {\n  return {\n    html: `<span style=\"display:none\">[OM:${token}]</span>`,\n    plain: `\\n\\n[OM:${token}]`,\n  }\n}\n\n/**\n * Apply the thread token to an outbound MIME-like payload. Mutates the\n * input shape minimally and idempotently:\n *   - `headers.references`: appends the synthetic `<om_TOKEN@\u2026>` id if not\n *     already present (deduped).\n *   - `bodyHtml`: injects a hidden `<span>` before the last `</body>` tag,\n *     or appends if no `</body>` is present.\n *   - `bodyText`: appends the plain-text trailer.\n *\n * Returns a NEW object \u2014 does not mutate the input. Callers that maintain\n * their own MIME structure can call the building blocks directly.\n */\nexport function applyOutboundThreadingToken<\n  T extends {\n    headers?: Record<string, string | string[] | undefined>\n    bodyHtml?: string\n    bodyText?: string\n  },\n>(payload: T, token: string): T {\n  if (!verifyToken(token)) {\n    throw new Error('applyOutboundThreadingToken: invalid token format/signature')\n  }\n  const refId = buildReferencesId(token)\n  const footer = buildBodyFooter(token)\n\n  const headers = { ...(payload.headers ?? {}) } as Record<string, string | string[] | undefined>\n  const existingRefs = headers['references'] ?? headers['References']\n  let nextRefs: string\n  if (Array.isArray(existingRefs)) {\n    nextRefs = existingRefs.includes(refId) ? existingRefs.join(' ') : [...existingRefs, refId].join(' ')\n  } else if (typeof existingRefs === 'string' && existingRefs.length > 0) {\n    nextRefs = existingRefs.includes(refId) ? existingRefs : `${existingRefs} ${refId}`\n  } else {\n    nextRefs = refId\n  }\n  // Normalise to the canonical RFC 5322 header name and drop any duplicate\n  // lowercase entry so the MTA sees a single `References` header.\n  delete headers['references']\n  headers['References'] = nextRefs\n\n  let bodyHtml = payload.bodyHtml\n  if (typeof bodyHtml === 'string') {\n    if (!bodyHtml.includes(`[OM:${token}]`)) {\n      const closing = bodyHtml.lastIndexOf('</body>')\n      if (closing >= 0) {\n        bodyHtml = `${bodyHtml.slice(0, closing)}${footer.html}${bodyHtml.slice(closing)}`\n      } else {\n        bodyHtml = `${bodyHtml}${footer.html}`\n      }\n    }\n  }\n\n  let bodyText = payload.bodyText\n  if (typeof bodyText === 'string') {\n    if (!bodyText.includes(`[OM:${token}]`)) {\n      bodyText = `${bodyText}${footer.plain}`\n    }\n  }\n\n  return {\n    ...payload,\n    headers,\n    ...(bodyHtml !== undefined ? { bodyHtml } : {}),\n    ...(bodyText !== undefined ? { bodyText } : {}),\n  }\n}\n\n/**\n * Extract token candidates from a `References` / `In-Reply-To` header\n * value (string or string[]) and return the FIRST one that HMAC-verifies.\n * Returns `null` if no valid token is present.\n */\nexport function extractTokenFromHeaders(\n  inReplyTo: string | null | undefined,\n  references: string[] | string | null | undefined,\n): string | null {\n  const haystack: string[] = []\n  if (typeof inReplyTo === 'string' && inReplyTo.length > 0) haystack.push(inReplyTo)\n  if (Array.isArray(references)) haystack.push(...references)\n  else if (typeof references === 'string' && references.length > 0) haystack.push(references)\n  for (const candidate of haystack) {\n    const matches = candidate.match(new RegExp(TOKEN_REGEX, 'g'))\n    if (!matches) continue\n    for (const match of matches) {\n      if (verifyToken(match)) return match\n    }\n  }\n  return null\n}\n\n/**\n * Idempotent get-or-create: return the existing `ChannelThreadToken` for the\n * given thread, or create + return a new one. Idempotency is enforced by the\n * `channel_thread_tokens_thread_uq` unique constraint on\n * `(tenant_id, message_thread_id)`: a concurrent double-create loses the race\n * with a unique violation, which we catch and resolve by re-selecting the\n * winner \u2014 so callers always converge on exactly one token per thread.\n *\n * Reads via the standard EntityManager (no encryption needed \u2014 the token\n * column itself is the HMAC-signed value, not encrypted at rest).\n *\n * Use cases:\n *   - Outbound subscriber: get or create a token before injecting it\n *     into the outbound MIME (`applyOutboundThreadingToken`).\n *   - Future \"reset\" UI for tenant admins: explicit rotation by deleting\n *     the row + calling this helper again.\n */\nexport async function getOrCreateThreadToken(\n  em: EntityManager,\n  args: {\n    tenantId: string\n    organizationId: string | null\n    messageThreadId: string\n  },\n): Promise<{ token: string; created: boolean }> {\n  const dscope = { tenantId: args.tenantId, organizationId: args.organizationId }\n  const existing = await findOneWithDecryption(\n    em,\n    ChannelThreadToken,\n    {\n      tenantId: args.tenantId,\n      organizationId: args.organizationId,\n      messageThreadId: args.messageThreadId,\n    },\n    undefined,\n    dscope,\n  )\n  if (existing) {\n    return { token: existing.token, created: false }\n  }\n  const row = em.create(ChannelThreadToken, {\n    tenantId: args.tenantId,\n    organizationId: args.organizationId,\n    messageThreadId: args.messageThreadId,\n    token: generateToken(),\n  })\n  // MikroORM v7 removed `persistAndFlush` \u2014 split into persist + flush.\n  em.persist(row)\n  try {\n    await em.flush()\n    return { token: row.token, created: true }\n  } catch (err) {\n    // A concurrent create for the same (tenant, thread) won the race; the\n    // unique constraint rejected ours. Re-select the winner on a clean fork so\n    // we never return a half-persisted row or surface a spurious error.\n    if (!isUniqueViolation(err)) throw err\n    const winner = await findOneWithDecryption(\n      em.fork(),\n      ChannelThreadToken,\n      {\n        tenantId: args.tenantId,\n        organizationId: args.organizationId,\n        messageThreadId: args.messageThreadId,\n      },\n      undefined,\n      dscope,\n    )\n    if (winner) return { token: winner.token, created: false }\n    throw err\n  }\n}\n\n/**\n * Extract a token candidate from an inbound body (HTML or plain text).\n * Scans for `[OM:om_\u2026]` markers and returns the first that HMAC-verifies.\n */\nexport function extractTokenFromBody(\n  bodyHtml: string | null | undefined,\n  bodyText: string | null | undefined,\n): string | null {\n  const haystacks = [bodyHtml, bodyText].filter(\n    (value): value is string => typeof value === 'string' && value.length > 0,\n  )\n  const pattern = new RegExp(`\\\\[OM:(${TOKEN_REGEX.source})\\\\]`, 'g')\n  for (const haystack of haystacks) {\n    let match: RegExpExecArray | null\n    pattern.lastIndex = 0\n    while ((match = pattern.exec(haystack)) !== null) {\n      if (verifyToken(match[1])) return match[1]\n    }\n  }\n  return null\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/communication_channels/lib/use-connect-channel.js

@@ -0,0 +1,61 @@
+"use client";
+import * as React from "react";
+import { useT } from "@open-mercato/shared/lib/i18n/context";
+import { flash } from "@open-mercato/ui/backend/FlashMessages";
+import { useGuardedMutation } from "@open-mercato/ui/backend/injection/useGuardedMutation";
+import { apiCall } from "@open-mercato/ui/backend/utils/apiCall";
+function useConnectChannel(options) {
+  const { providerKey } = options;
+  const returnUrl = options.returnUrl ?? "/backend/profile/communication-channels";
+  const t = useT();
+  const [pending, setPending] = React.useState(false);
+  const { runMutation, retryLastMutation } = useGuardedMutation({
+    contextId: `channel-${providerKey}-connect`,
+    blockedMessage: t("communication_channels.profile.connect.blocked", "Connection blocked by validation")
+  });
+  const mutationContext = React.useMemo(
+    () => ({ providerKey, retryLastMutation }),
+    [providerKey, retryLastMutation]
+  );
+  const connect = React.useCallback(async () => {
+    if (pending) return;
+    setPending(true);
+    try {
+      const response = await runMutation({
+        context: mutationContext,
+        mutationPayload: { providerKey },
+        operation: () => apiCall(`/api/communication_channels/oauth/${providerKey}/initiate`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ returnUrl })
+        })
+      });
+      const body = response.result;
+      if (!response.ok || !body?.authorizeUrl) {
+        if (body?.code === "oauth_client_not_configured") {
+          flash(
+            t(
+              "communication_channels.profile.connect.notConfigured",
+              "This provider is not configured yet. Ask an administrator to add the OAuth Client ID and Secret under Integrations before connecting a mailbox."
+            ),
+            "error"
+          );
+          return;
+        }
+        flash(
+          body?.error ?? t("communication_channels.profile.connect.oauthFailed", "Could not start OAuth connection."),
+          "error"
+        );
+        return;
+      }
+      window.location.assign(body.authorizeUrl);
+    } finally {
+      setPending(false);
+    }
+  }, [mutationContext, pending, providerKey, returnUrl, runMutation, t]);
+  return { connect, pending };
+}
+export {
+  useConnectChannel
+};
+//# sourceMappingURL=use-connect-channel.js.map

package/dist/modules/communication_channels/lib/use-connect-channel.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/use-connect-channel.ts"],
+  "sourcesContent": ["'use client'\n\nimport * as React from 'react'\nimport { useT } from '@open-mercato/shared/lib/i18n/context'\nimport { flash } from '@open-mercato/ui/backend/FlashMessages'\nimport { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'\nimport { apiCall } from '@open-mercato/ui/backend/utils/apiCall'\n\ntype InitiateResponse = { authorizeUrl?: string; error?: string; code?: string }\n\n/**\n * Shared OAuth \"connect\" flow for email channel provider widgets (Gmail and\n * other OAuth providers). Wraps the guarded-mutation contract + `/oauth/<provider>/initiate`\n * call + redirect, so each provider widget only supplies its own button chrome.\n */\nexport function useConnectChannel(options: {\n  providerKey: string\n  returnUrl?: string\n}): { connect: () => Promise<void>; pending: boolean } {\n  const { providerKey } = options\n  const returnUrl = options.returnUrl ?? '/backend/profile/communication-channels'\n  const t = useT()\n  const [pending, setPending] = React.useState(false)\n  const { runMutation, retryLastMutation } = useGuardedMutation({\n    contextId: `channel-${providerKey}-connect`,\n    blockedMessage: t('communication_channels.profile.connect.blocked', 'Connection blocked by validation'),\n  })\n  const mutationContext = React.useMemo(\n    () => ({ providerKey, retryLastMutation }),\n    [providerKey, retryLastMutation],\n  )\n\n  const connect = React.useCallback(async () => {\n    if (pending) return\n    setPending(true)\n    try {\n      const response = await runMutation({\n        context: mutationContext,\n        mutationPayload: { providerKey },\n        operation: () =>\n          apiCall<InitiateResponse>(`/api/communication_channels/oauth/${providerKey}/initiate`, {\n            method: 'POST',\n            headers: { 'content-type': 'application/json' },\n            body: JSON.stringify({ returnUrl }),\n          }),\n      })\n      const body = response.result as InitiateResponse | undefined\n      if (!response.ok || !body?.authorizeUrl) {\n        if (body?.code === 'oauth_client_not_configured') {\n          flash(\n            t(\n              'communication_channels.profile.connect.notConfigured',\n              'This provider is not configured yet. Ask an administrator to add the OAuth Client ID and Secret under Integrations before connecting a mailbox.',\n            ),\n            'error',\n          )\n          return\n        }\n        flash(\n          body?.error ??\n            t('communication_channels.profile.connect.oauthFailed', 'Could not start OAuth connection.'),\n          'error',\n        )\n        return\n      }\n      window.location.assign(body.authorizeUrl)\n    } finally {\n      setPending(false)\n    }\n  }, [mutationContext, pending, providerKey, returnUrl, runMutation, t])\n\n  return { connect, pending }\n}\n"],
+  "mappings": ";AAEA,YAAY,WAAW;AACvB,SAAS,YAAY;AACrB,SAAS,aAAa;AACtB,SAAS,0BAA0B;AACnC,SAAS,eAAe;AASjB,SAAS,kBAAkB,SAGqB;AACrD,QAAM,EAAE,YAAY,IAAI;AACxB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,IAAI,KAAK;AACf,QAAM,CAAC,SAAS,UAAU,IAAI,MAAM,SAAS,KAAK;AAClD,QAAM,EAAE,aAAa,kBAAkB,IAAI,mBAAmB;AAAA,IAC5D,WAAW,WAAW,WAAW;AAAA,IACjC,gBAAgB,EAAE,kDAAkD,kCAAkC;AAAA,EACxG,CAAC;AACD,QAAM,kBAAkB,MAAM;AAAA,IAC5B,OAAO,EAAE,aAAa,kBAAkB;AAAA,IACxC,CAAC,aAAa,iBAAiB;AAAA,EACjC;AAEA,QAAM,UAAU,MAAM,YAAY,YAAY;AAC5C,QAAI,QAAS;AACb,eAAW,IAAI;AACf,QAAI;AACF,YAAM,WAAW,MAAM,YAAY;AAAA,QACjC,SAAS;AAAA,QACT,iBAAiB,EAAE,YAAY;AAAA,QAC/B,WAAW,MACT,QAA0B,qCAAqC,WAAW,aAAa;AAAA,UACrF,QAAQ;AAAA,UACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,UAC9C,MAAM,KAAK,UAAU,EAAE,UAAU,CAAC;AAAA,QACpC,CAAC;AAAA,MACL,CAAC;AACD,YAAM,OAAO,SAAS;AACtB,UAAI,CAAC,SAAS,MAAM,CAAC,MAAM,cAAc;AACvC,YAAI,MAAM,SAAS,+BAA+B;AAChD;AAAA,YACE;AAAA,cACE;AAAA,cACA;AAAA,YACF;AAAA,YACA;AAAA,UACF;AACA;AAAA,QACF;AACA;AAAA,UACE,MAAM,SACJ,EAAE,sDAAsD,mCAAmC;AAAA,UAC7F;AAAA,QACF;AACA;AAAA,MACF;AACA,aAAO,SAAS,OAAO,KAAK,YAAY;AAAA,IAC1C,UAAE;AACA,iBAAW,KAAK;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,iBAAiB,SAAS,aAAa,WAAW,aAAa,CAAC,CAAC;AAErE,SAAO,EAAE,SAAS,QAAQ;AAC5B;",
+  "names": []
+}