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

package/dist/modules/communication_channels/lib/email-mime.js

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+import { EMAIL_MAX_ATTACHMENT_BYTES } from "./email-capabilities.js";
+const TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES = EMAIL_MAX_ATTACHMENT_BYTES * 2;
+function stringOrUndefined(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function toAddressList(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter((v) => v.length > 0);
+  if (typeof value === "string") {
+    return value.split(/[,;]\s*/).map((v) => v.trim()).filter((v) => v.length > 0);
+  }
+  return [];
+}
+function referencesFromMeta(value) {
+  if (!Array.isArray(value)) return void 0;
+  return value.filter((entry) => typeof entry === "string");
+}
+function htmlToText(html) {
+  return html.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, " ").replace(/<script[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<br\s*\/?>(?=\s*)/gi, "\n").replace(/<\/p\s*>/gi, "\n\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/\n{3,}/g, "\n\n").trim();
+}
+function escapeQuotes(value) {
+  return value.replace(/"/g, '\\"');
+}
+function sanitizeHeaderValue(value) {
+  return value.replace(/[\r\n\t]+/g, " ").trim();
+}
+function ensureBrackets(value) {
+  const trimmed = sanitizeHeaderValue(value);
+  if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed;
+  return `<${trimmed}>`;
+}
+function isPureAscii(value) {
+  return /^[\x00-\x7F]*$/.test(value);
+}
+function encodeHeaderWord(value) {
+  if (isPureAscii(value)) return value;
+  return `=?utf-8?B?${Buffer.from(value, "utf-8").toString("base64")}?=`;
+}
+function encodeAddressHeaderWord(value) {
+  if (isPureAscii(value)) return value;
+  const match = value.match(/^(.*?)(\s*<[^>]*>)\s*$/);
+  if (match) {
+    const [, displayPart, addrPart] = match;
+    const displayName = displayPart.replace(/^"|"$/g, "").trim();
+    if (!displayName) return value;
+    return `${encodeHeaderWord(displayName)}${addrPart}`;
+  }
+  return encodeHeaderWord(value);
+}
+function generateMessageId(fromAddress, fallbackDomain = "localhost") {
+  const domain = fromAddress.split("@")[1] ?? fallbackDomain;
+  return `<${crypto.randomUUID()}@${domain}>`;
+}
+function encodeBodyPart(content) {
+  if (isPureAscii(content)) return { cte: "7bit", body: content };
+  const base64 = Buffer.from(content, "utf-8").toString("base64");
+  const wrapped = base64.match(/.{1,76}/g)?.join("\r\n") ?? base64;
+  return { cte: "base64", body: wrapped };
+}
+function assembleRfc2822(input) {
+  const boundary = `omc_${crypto.randomUUID()}`;
+  const headers = [];
+  headers.push(`From: ${encodeAddressHeaderWord(sanitizeHeaderValue(input.from))}`);
+  headers.push(`To: ${input.to.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(", ")}`);
+  if (input.cc.length) headers.push(`Cc: ${input.cc.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(", ")}`);
+  if (input.bcc.length) headers.push(`Bcc: ${input.bcc.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(", ")}`);
+  if (input.subject) headers.push(`Subject: ${encodeHeaderWord(sanitizeHeaderValue(input.subject))}`);
+  headers.push(`Message-ID: ${ensureBrackets(input.messageId)}`);
+  if (input.inReplyTo) headers.push(`In-Reply-To: ${ensureBrackets(input.inReplyTo)}`);
+  if (input.references && input.references.length) {
+    headers.push(`References: ${input.references.map(ensureBrackets).join(" ")}`);
+  }
+  headers.push("MIME-Version: 1.0");
+  headers.push(`Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`);
+  if (input.html && input.text) {
+    headers.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
+    const textPart2 = encodeBodyPart(input.text);
+    const htmlPart = encodeBodyPart(input.html);
+    const body = [
+      "",
+      `--${boundary}`,
+      "Content-Type: text/plain; charset=utf-8",
+      `Content-Transfer-Encoding: ${textPart2.cte}`,
+      "",
+      textPart2.body,
+      `--${boundary}`,
+      "Content-Type: text/html; charset=utf-8",
+      `Content-Transfer-Encoding: ${htmlPart.cte}`,
+      "",
+      htmlPart.body,
+      `--${boundary}--`,
+      ""
+    ].join("\r\n");
+    return Buffer.from(headers.join("\r\n") + body, "utf-8");
+  }
+  if (input.html) {
+    const htmlPart = encodeBodyPart(input.html);
+    headers.push("Content-Type: text/html; charset=utf-8");
+    headers.push(`Content-Transfer-Encoding: ${htmlPart.cte}`);
+    return Buffer.from(headers.join("\r\n") + "\r\n\r\n" + htmlPart.body, "utf-8");
+  }
+  const textPart = encodeBodyPart(input.text ?? "");
+  headers.push("Content-Type: text/plain; charset=utf-8");
+  headers.push(`Content-Transfer-Encoding: ${textPart.cte}`);
+  return Buffer.from(headers.join("\r\n") + "\r\n\r\n" + textPart.body, "utf-8");
+}
+function stripBrackets(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed.slice(1, -1);
+  return trimmed;
+}
+function parseReferences(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map((v) => stripBrackets(v)).filter((v) => Boolean(v));
+  return value.split(/\s+/).map((segment) => stripBrackets(segment)).filter((segment) => Boolean(segment));
+}
+function normalizeAttachments(attachments) {
+  const out = [];
+  let totalBytes = 0;
+  for (const att of attachments) {
+    if (!att.content) continue;
+    const byteLength = att.content.byteLength;
+    if (byteLength > EMAIL_MAX_ATTACHMENT_BYTES) {
+      console.warn(
+        `[email-mime] dropping oversized inbound attachment "${att.filename ?? "attachment"}" (${byteLength} bytes > ${EMAIL_MAX_ATTACHMENT_BYTES} cap)`
+      );
+      continue;
+    }
+    if (totalBytes + byteLength > TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES) {
+      console.warn(
+        `[email-mime] aggregate inbound attachment size exceeded ${TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES} bytes; dropping remaining attachments`
+      );
+      break;
+    }
+    totalBytes += byteLength;
+    const base64 = Buffer.isBuffer(att.content) ? att.content.toString("base64") : Buffer.from(att.content).toString("base64");
+    out.push({
+      url: `data:${att.contentType ?? "application/octet-stream"};base64,${base64}`,
+      mimeType: att.contentType ?? "application/octet-stream",
+      fileName: att.filename ?? "attachment",
+      fileSize: att.size,
+      inline: Boolean(att.contentDisposition && /inline/i.test(att.contentDisposition)) || Boolean(att.cid)
+    });
+  }
+  return out;
+}
+function stringifyHeaderValue(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map((v) => String(v)).join(", ");
+  if (value instanceof Date) return value.toISOString();
+  if (value && typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return void 0;
+    }
+  }
+  if (value === void 0 || value === null) return void 0;
+  return String(value);
+}
+function extractHeaders(headers) {
+  if (!headers) return {};
+  const out = {};
+  if (headers instanceof Map) {
+    for (const [key, value] of headers.entries()) {
+      const stringified = stringifyHeaderValue(value);
+      if (stringified !== void 0) out[String(key)] = stringified;
+    }
+    return out;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    const stringified = stringifyHeaderValue(value);
+    if (stringified !== void 0) out[key] = stringified;
+  }
+  return out;
+}
+function normalizeMimeInbound(options) {
+  const { parsed } = options;
+  const messageId = stripBrackets(parsed.messageId) ?? options.fallbackMessageId;
+  const inReplyTo = stripBrackets(parsed.inReplyTo);
+  const references = parseReferences(parsed.references);
+  const conversationId = options.resolveConversationId({ messageId, references });
+  const from = parsed.from?.value?.[0];
+  const subject = parsed.subject?.trim() || void 0;
+  const bodyHtml = parsed.html && typeof parsed.html === "string" ? parsed.html : void 0;
+  const bodyText = typeof parsed.text === "string" ? parsed.text : void 0;
+  const body = bodyHtml ?? bodyText ?? "";
+  const bodyFormat = bodyHtml ? "html" : "text";
+  const attachments = normalizeAttachments(parsed.attachments ?? []);
+  const channelMetadata = {
+    ...options.channelMetadata?.(parsed) ?? {},
+    messageId,
+    inReplyTo: inReplyTo ?? null,
+    references,
+    headers: extractHeaders(parsed.headers)
+  };
+  const channelPayload = {
+    subject,
+    from: from ? { address: from.address, name: from.name } : null,
+    to: parsed.to?.value ?? [],
+    cc: parsed.cc?.value ?? [],
+    bcc: parsed.bcc?.value ?? [],
+    html: bodyHtml ?? null,
+    text: bodyText ?? null,
+    messageId,
+    ...options.channelPayload?.(parsed) ?? {}
+  };
+  return {
+    externalMessageId: messageId,
+    externalConversationId: conversationId,
+    senderIdentifier: from?.address ?? options.accountIdentifier,
+    senderDisplayName: from?.name?.trim() || void 0,
+    subject,
+    body,
+    bodyFormat,
+    attachments,
+    timestamp: parsed.date ? new Date(parsed.date) : options.fallbackDate ?? /* @__PURE__ */ new Date(),
+    replyToExternalId: inReplyTo ?? void 0,
+    channelPayload,
+    channelContentType: "email/mime",
+    channelMetadata
+  };
+}
+function encodeCursor(state) {
+  return Buffer.from(JSON.stringify(state)).toString("base64");
+}
+function decodeCursor(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(Buffer.from(value, "base64").toString("utf-8"));
+  } catch {
+    return null;
+  }
+}
+export {
+  assembleRfc2822,
+  decodeCursor,
+  encodeAddressHeaderWord,
+  encodeCursor,
+  encodeHeaderWord,
+  ensureBrackets,
+  escapeQuotes,
+  extractHeaders,
+  generateMessageId,
+  htmlToText,
+  normalizeAttachments,
+  normalizeMimeInbound,
+  parseReferences,
+  referencesFromMeta,
+  sanitizeHeaderValue,
+  stringOrUndefined,
+  stripBrackets,
+  toAddressList
+};
+//# sourceMappingURL=email-mime.js.map

package/dist/modules/communication_channels/lib/email-mime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/email-mime.ts"],
+  "sourcesContent": ["import crypto from 'node:crypto'\nimport type { NormalizedInboundMessage, NormalizedAttachment } from './adapter'\nimport { EMAIL_MAX_ATTACHMENT_BYTES } from './email-capabilities'\n\n/**\n * Aggregate ceiling for all attachments on a single inbound message. Inbound\n * mail is untrusted, so without a cap a malicious/large message would be fully\n * base64-buffered in memory (~1.33x raw bytes) and persisted. Allow a small\n * multiple of the per-attachment limit for legitimate multi-file emails.\n */\nconst TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES = EMAIL_MAX_ATTACHMENT_BYTES * 2\n\n/**\n * Shared email MIME helpers for the email channel providers (Gmail, IMAP).\n * Outbound assembly, inbound parsing, header/address normalization,\n * and threading-id extraction all live here so every provider shares one\n * correct implementation instead of copy-pasting (which previously let Gmail's\n * `extractHeaders` drift into a Map-handling bug that IMAP had already fixed).\n *\n * Provider-specific transport (Gmail History API, IMAP UID sync)\n * stays in each package \u2014 this module only owns the format-level plumbing.\n */\n\n// \u2500\u2500 Outbound MIME helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function stringOrUndefined(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nexport function toAddressList(value: unknown): string[] {\n  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter((v) => v.length > 0)\n  if (typeof value === 'string') {\n    return value\n      .split(/[,;]\\s*/)\n      .map((v) => v.trim())\n      .filter((v) => v.length > 0)\n  }\n  return []\n}\n\nexport function referencesFromMeta(value: unknown): string[] | undefined {\n  if (!Array.isArray(value)) return undefined\n  return value.filter((entry): entry is string => typeof entry === 'string')\n}\n\nexport function htmlToText(html: string): string {\n  return html\n    .replace(/<style[^>]*>[\\s\\S]*?<\\/style>/gi, ' ')\n    .replace(/<script[^>]*>[\\s\\S]*?<\\/script>/gi, ' ')\n    .replace(/<br\\s*\\/?>(?=\\s*)/gi, '\\n')\n    .replace(/<\\/p\\s*>/gi, '\\n\\n')\n    .replace(/<[^>]+>/g, '')\n    .replace(/&nbsp;/gi, ' ')\n    .replace(/&amp;/gi, '&')\n    .replace(/&lt;/gi, '<')\n    .replace(/&gt;/gi, '>')\n    .replace(/&quot;/gi, '\"')\n    .replace(/\\n{3,}/g, '\\n\\n')\n    .trim()\n}\n\nexport function escapeQuotes(value: string): string {\n  return value.replace(/\"/g, '\\\\\"')\n}\n\n/**\n * Collapse CR/LF/TAB in an email header value to a single space to prevent\n * RFC 5322 header injection \u2014 e.g. a Subject smuggling an extra\n * `Bcc:`/`Content-Type:` header or splitting the message into a body.\n * Collapsing (rather than folding) is safe for the short structured headers\n * we emit (Subject, addresses, Message-ID, References).\n */\nexport function sanitizeHeaderValue(value: string): string {\n  return value.replace(/[\\r\\n\\t]+/g, ' ').trim()\n}\n\nexport function ensureBrackets(value: string): string {\n  const trimmed = sanitizeHeaderValue(value)\n  if (trimmed.startsWith('<') && trimmed.endsWith('>')) return trimmed\n  return `<${trimmed}>`\n}\n\nfunction isPureAscii(value: string): boolean {\n  // eslint-disable-next-line no-control-regex\n  return /^[\\x00-\\x7F]*$/.test(value)\n}\n\n/**\n * Encode a single header value as an RFC 2047 \"B\" (base64) encoded-word when it\n * contains non-ASCII characters, so 8-bit text like \"Caf\u00E9\" survives strict MTAs\n * that treat header bytes as 7-bit ASCII. Pure-ASCII values are returned\n * unchanged. Apply only AFTER `sanitizeHeaderValue` so the CR/LF injection guard\n * still runs against the raw value.\n */\nexport function encodeHeaderWord(value: string): string {\n  if (isPureAscii(value)) return value\n  return `=?utf-8?B?${Buffer.from(value, 'utf-8').toString('base64')}?=`\n}\n\n/**\n * Encode the display-name part of a single address header value, leaving the\n * `<addr@domain>` untouched (per RFC 2047, encoded-words are not permitted\n * inside the addr-spec). Inputs without a bracketed address are treated as a\n * bare display name / address and encoded only when non-ASCII.\n */\nexport function encodeAddressHeaderWord(value: string): string {\n  if (isPureAscii(value)) return value\n  const match = value.match(/^(.*?)(\\s*<[^>]*>)\\s*$/)\n  if (match) {\n    const [, displayPart, addrPart] = match\n    const displayName = displayPart.replace(/^\"|\"$/g, '').trim()\n    if (!displayName) return value\n    return `${encodeHeaderWord(displayName)}${addrPart}`\n  }\n  return encodeHeaderWord(value)\n}\n\n/**\n * Generate an RFC 5322 Message-ID rooted in the sender's domain. Used as a\n * downstream idempotency key, so entropy comes from `crypto.randomUUID()`\n * rather than `Math.random()`.\n */\nexport function generateMessageId(fromAddress: string, fallbackDomain = 'localhost'): string {\n  const domain = fromAddress.split('@')[1] ?? fallbackDomain\n  return `<${crypto.randomUUID()}@${domain}>`\n}\n\nexport interface AssembleRfc2822Input {\n  from: string\n  to: string[]\n  cc: string[]\n  bcc: string[]\n  subject: string | undefined\n  text: string | undefined\n  html: string | undefined\n  inReplyTo: string | undefined\n  references: string[] | undefined\n  messageId: string\n}\n\n/**\n * Render one MIME body part's CTE header + body content. Non-ASCII bodies are\n * base64-encoded (CRLF-wrapped at 76 cols) and labelled\n * `Content-Transfer-Encoding: base64` so 8-bit text survives strict MTAs;\n * pure-ASCII bodies stay `7bit` and verbatim.\n */\nfunction encodeBodyPart(content: string): { cte: string; body: string } {\n  if (isPureAscii(content)) return { cte: '7bit', body: content }\n  const base64 = Buffer.from(content, 'utf-8').toString('base64')\n  const wrapped = base64.match(/.{1,76}/g)?.join('\\r\\n') ?? base64\n  return { cte: 'base64', body: wrapped }\n}\n\n/**\n * Assemble a raw RFC2822 message (used by transports that send the encoded\n * message directly, e.g. Gmail `users.messages.send`). Emits a\n * `multipart/alternative` body when both html and text are present, otherwise a\n * single-part text or html body.\n */\nexport function assembleRfc2822(input: AssembleRfc2822Input): Buffer {\n  const boundary = `omc_${crypto.randomUUID()}`\n  const headers: string[] = []\n  headers.push(`From: ${encodeAddressHeaderWord(sanitizeHeaderValue(input.from))}`)\n  headers.push(`To: ${input.to.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(', ')}`)\n  if (input.cc.length) headers.push(`Cc: ${input.cc.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(', ')}`)\n  if (input.bcc.length) headers.push(`Bcc: ${input.bcc.map((value) => encodeAddressHeaderWord(sanitizeHeaderValue(value))).join(', ')}`)\n  if (input.subject) headers.push(`Subject: ${encodeHeaderWord(sanitizeHeaderValue(input.subject))}`)\n  headers.push(`Message-ID: ${ensureBrackets(input.messageId)}`)\n  if (input.inReplyTo) headers.push(`In-Reply-To: ${ensureBrackets(input.inReplyTo)}`)\n  if (input.references && input.references.length) {\n    headers.push(`References: ${input.references.map(ensureBrackets).join(' ')}`)\n  }\n  headers.push('MIME-Version: 1.0')\n  headers.push(`Date: ${new Date().toUTCString()}`)\n\n  if (input.html && input.text) {\n    headers.push(`Content-Type: multipart/alternative; boundary=\"${boundary}\"`)\n    const textPart = encodeBodyPart(input.text)\n    const htmlPart = encodeBodyPart(input.html)\n    const body = [\n      '',\n      `--${boundary}`,\n      'Content-Type: text/plain; charset=utf-8',\n      `Content-Transfer-Encoding: ${textPart.cte}`,\n      '',\n      textPart.body,\n      `--${boundary}`,\n      'Content-Type: text/html; charset=utf-8',\n      `Content-Transfer-Encoding: ${htmlPart.cte}`,\n      '',\n      htmlPart.body,\n      `--${boundary}--`,\n      '',\n    ].join('\\r\\n')\n    return Buffer.from(headers.join('\\r\\n') + body, 'utf-8')\n  }\n\n  if (input.html) {\n    const htmlPart = encodeBodyPart(input.html)\n    headers.push('Content-Type: text/html; charset=utf-8')\n    headers.push(`Content-Transfer-Encoding: ${htmlPart.cte}`)\n    return Buffer.from(headers.join('\\r\\n') + '\\r\\n\\r\\n' + htmlPart.body, 'utf-8')\n  }\n\n  const textPart = encodeBodyPart(input.text ?? '')\n  headers.push('Content-Type: text/plain; charset=utf-8')\n  headers.push(`Content-Transfer-Encoding: ${textPart.cte}`)\n  return Buffer.from(headers.join('\\r\\n') + '\\r\\n\\r\\n' + textPart.body, 'utf-8')\n}\n\n// \u2500\u2500 Inbound MIME parsing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface ParsedMail {\n  messageId?: string | null\n  inReplyTo?: string | null\n  references?: string | string[] | null\n  from?: { value?: Array<{ address?: string; name?: string }> }\n  to?: { value?: Array<{ address?: string; name?: string }> }\n  cc?: { value?: Array<{ address?: string; name?: string }> }\n  bcc?: { value?: Array<{ address?: string; name?: string }> }\n  subject?: string | null\n  html?: string | false\n  text?: string\n  date?: string | Date | null\n  attachments?: ParsedAttachment[]\n  headers?: Map<string, unknown> | Record<string, unknown>\n}\n\nexport interface ParsedAttachment {\n  content?: Buffer | Uint8Array\n  contentType?: string\n  filename?: string\n  size?: number\n  contentDisposition?: string\n  cid?: string\n}\n\nexport function stripBrackets(value: string | undefined | null): string | undefined {\n  if (!value) return undefined\n  const trimmed = value.trim()\n  if (!trimmed) return undefined\n  if (trimmed.startsWith('<') && trimmed.endsWith('>')) return trimmed.slice(1, -1)\n  return trimmed\n}\n\nexport function parseReferences(value: string | string[] | undefined | null): string[] {\n  if (!value) return []\n  if (Array.isArray(value)) return value.map((v) => stripBrackets(v)).filter((v): v is string => Boolean(v))\n  return value\n    .split(/\\s+/)\n    .map((segment) => stripBrackets(segment))\n    .filter((segment): segment is string => Boolean(segment))\n}\n\nexport function normalizeAttachments(attachments: ParsedAttachment[]): NormalizedAttachment[] {\n  const out: NormalizedAttachment[] = []\n  let totalBytes = 0\n  for (const att of attachments) {\n    if (!att.content) continue\n    const byteLength = att.content.byteLength\n    if (byteLength > EMAIL_MAX_ATTACHMENT_BYTES) {\n      console.warn(\n        `[email-mime] dropping oversized inbound attachment \"${att.filename ?? 'attachment'}\" (${byteLength} bytes > ${EMAIL_MAX_ATTACHMENT_BYTES} cap)`,\n      )\n      continue\n    }\n    if (totalBytes + byteLength > TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES) {\n      console.warn(\n        `[email-mime] aggregate inbound attachment size exceeded ${TOTAL_INBOUND_ATTACHMENTS_MAX_BYTES} bytes; dropping remaining attachments`,\n      )\n      break\n    }\n    totalBytes += byteLength\n    const base64 = Buffer.isBuffer(att.content)\n      ? att.content.toString('base64')\n      : Buffer.from(att.content).toString('base64')\n    out.push({\n      url: `data:${att.contentType ?? 'application/octet-stream'};base64,${base64}`,\n      mimeType: att.contentType ?? 'application/octet-stream',\n      fileName: att.filename ?? 'attachment',\n      fileSize: att.size,\n      inline: Boolean(att.contentDisposition && /inline/i.test(att.contentDisposition)) || Boolean(att.cid),\n    })\n  }\n  return out\n}\n\nfunction stringifyHeaderValue(value: unknown): string | undefined {\n  if (typeof value === 'string') return value\n  if (Array.isArray(value)) return value.map((v) => String(v)).join(', ')\n  if (value instanceof Date) return value.toISOString()\n  if (value && typeof value === 'object') {\n    try {\n      return JSON.stringify(value)\n    } catch {\n      return undefined\n    }\n  }\n  if (value === undefined || value === null) return undefined\n  return String(value)\n}\n\n/**\n * Flatten parsed MIME headers to a `Record<string, string>`.\n *\n * mailparser returns `headers` as a `Map<string, unknown>`. `Object.entries` on\n * a Map yields an empty array (Maps have no enumerable own properties), so we\n * iterate Map entries directly, with a Record fallback for test fakes.\n */\nexport function extractHeaders(headers: ParsedMail['headers']): Record<string, string> {\n  if (!headers) return {}\n  const out: Record<string, string> = {}\n  if (headers instanceof Map) {\n    for (const [key, value] of headers.entries()) {\n      const stringified = stringifyHeaderValue(value)\n      if (stringified !== undefined) out[String(key)] = stringified\n    }\n    return out\n  }\n  for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {\n    const stringified = stringifyHeaderValue(value)\n    if (stringified !== undefined) out[key] = stringified\n  }\n  return out\n}\n\nexport interface NormalizeMimeInboundOptions {\n  /**\n   * The parsed MIME message. Providers parse with their own `mailparser`\n   * dependency (Gmail/IMAP) and pass the result here, so the hub stays free of a\n   * MIME-parser dependency while still owning the normalization logic.\n   */\n  parsed: ParsedMail\n  /** External identifier of the receiving channel (typically the account's email). */\n  accountIdentifier: string\n  /** Deterministic id used when the MIME message carries no `Message-ID` header. */\n  fallbackMessageId: string\n  /** Compute the conversation grouping id from the resolved message id + references. */\n  resolveConversationId: (context: { messageId: string; references: string[] }) => string\n  /** Fallback timestamp when the parsed message has no Date header. */\n  fallbackDate?: Date\n  /** Provider-specific fields merged into `channelMetadata`. */\n  channelMetadata?: (parsed: ParsedMail) => Record<string, unknown>\n  /** Provider-specific fields merged into `channelPayload`. */\n  channelPayload?: (parsed: ParsedMail) => Record<string, unknown>\n}\n\n/**\n * Build the hub's canonical `NormalizedInboundMessage` from a parsed MIME\n * message. Providers supply the bits that genuinely differ (message-id\n * fallback, conversation grouping, extra metadata) and inherit the shared\n * threading / attachment / header logic.\n */\nexport function normalizeMimeInbound(options: NormalizeMimeInboundOptions): NormalizedInboundMessage {\n  const { parsed } = options\n\n  const messageId = stripBrackets(parsed.messageId) ?? options.fallbackMessageId\n  const inReplyTo = stripBrackets(parsed.inReplyTo)\n  const references = parseReferences(parsed.references)\n  const conversationId = options.resolveConversationId({ messageId, references })\n\n  const from = parsed.from?.value?.[0]\n  const subject = parsed.subject?.trim() || undefined\n  const bodyHtml = parsed.html && typeof parsed.html === 'string' ? parsed.html : undefined\n  const bodyText = typeof parsed.text === 'string' ? parsed.text : undefined\n  const body = bodyHtml ?? bodyText ?? ''\n  const bodyFormat: 'text' | 'html' = bodyHtml ? 'html' : 'text'\n\n  const attachments = normalizeAttachments(parsed.attachments ?? [])\n\n  const channelMetadata: Record<string, unknown> = {\n    ...(options.channelMetadata?.(parsed) ?? {}),\n    messageId,\n    inReplyTo: inReplyTo ?? null,\n    references,\n    headers: extractHeaders(parsed.headers),\n  }\n\n  const channelPayload: Record<string, unknown> = {\n    subject,\n    from: from ? { address: from.address, name: from.name } : null,\n    to: parsed.to?.value ?? [],\n    cc: parsed.cc?.value ?? [],\n    bcc: parsed.bcc?.value ?? [],\n    html: bodyHtml ?? null,\n    text: bodyText ?? null,\n    messageId,\n    ...(options.channelPayload?.(parsed) ?? {}),\n  }\n\n  return {\n    externalMessageId: messageId,\n    externalConversationId: conversationId,\n    senderIdentifier: from?.address ?? options.accountIdentifier,\n    senderDisplayName: from?.name?.trim() || undefined,\n    subject,\n    body,\n    bodyFormat,\n    attachments,\n    timestamp: parsed.date ? new Date(parsed.date) : options.fallbackDate ?? new Date(),\n    replyToExternalId: inReplyTo ?? undefined,\n    channelPayload,\n    channelContentType: 'email/mime',\n    channelMetadata,\n  }\n}\n\n// \u2500\u2500 Provider sync cursor helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/** Encode a provider channel-state object into an opaque base64 sync cursor. */\nexport function encodeCursor(state: unknown): string {\n  return Buffer.from(JSON.stringify(state)).toString('base64')\n}\n\n/** Decode a base64 sync cursor back into its object form, or `null` if malformed. */\nexport function decodeCursor(value: string | null | undefined): unknown {\n  if (!value) return null\n  try {\n    return JSON.parse(Buffer.from(value, 'base64').toString('utf-8'))\n  } catch {\n    return null\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["textPart"]
+}

package/dist/modules/communication_channels/lib/error-classification.js

@@ -0,0 +1,101 @@
+const TRANSIENT_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524]);
+const TRANSIENT_PG_SQLSTATES = /* @__PURE__ */ new Set([
+  "40001",
+  // serialization_failure
+  "40P01",
+  // deadlock_detected
+  "55P03",
+  // lock_not_available
+  "53300",
+  // too_many_connections
+  "53400",
+  // configuration_limit_exceeded
+  "57P01",
+  // admin_shutdown
+  "57P02",
+  // crash_shutdown
+  "57P03",
+  // cannot_connect_now (db starting up)
+  "08000",
+  // connection_exception
+  "08001",
+  // sqlclient_unable_to_establish_sqlconnection
+  "08003",
+  // connection_does_not_exist
+  "08006"
+  // connection_failure
+]);
+const TRANSIENT_CODE_PATTERNS = [
+  /ECONNRESET/i,
+  /ETIMEDOUT/i,
+  /ECONNREFUSED/i,
+  /ENOTFOUND/i,
+  /EAI_AGAIN/i,
+  /socket hang up/i,
+  /network timeout/i,
+  /\btimed?\s*out\b/i,
+  /service unavailable/i,
+  /rate limit/i,
+  /too many requests/i,
+  /temporarily unavailable/i,
+  /try again later/i,
+  // imapflow surfaces these on TLS/socket-level drops that almost always
+  // recover on the next attempt. Treating them as permanent kills the
+  // channel after a single bad packet (regression observed during the demo:
+  // a network hiccup put a freshly-connected mailbox into a non-recoverable
+  // `error` state until the operator manually clicked "Retry").
+  /unexpected close/i,
+  /connection not available/i,
+  /connection closed/i,
+  /server closed connection/i,
+  // Postgres transient failures surfaced as text by the ORM wrapper (the
+  // SQLSTATE on `.code` is the primary signal; these catch wrapped errors that
+  // only carry the message). See TRANSIENT_PG_SQLSTATES.
+  /deadlock detected/i,
+  /could not serialize access/i,
+  /connection terminated/i,
+  /too many clients already/i,
+  /the database system is (starting up|shutting down|in recovery)/i
+];
+function classifyOutboundError(error) {
+  if (!error) {
+    return { transient: false, message: "Unknown error" };
+  }
+  if (error instanceof Error) {
+    const explicit = error.transient;
+    const status = error.status;
+    if (explicit !== void 0) {
+      return { transient: Boolean(explicit), status, message: error.message };
+    }
+    const code = error.code;
+    if (typeof code === "string" && TRANSIENT_PG_SQLSTATES.has(code)) {
+      return { transient: true, status, message: error.message };
+    }
+    if (typeof status === "number") {
+      return {
+        transient: TRANSIENT_STATUS_CODES.has(status),
+        status,
+        message: error.message
+      };
+    }
+    const haystack = `${error.name} ${error.message}`;
+    const matchesPattern = TRANSIENT_CODE_PATTERNS.some((pattern) => pattern.test(haystack));
+    return { transient: matchesPattern, message: error.message };
+  }
+  return { transient: false, message: String(error) };
+}
+function isReauthError(classification) {
+  return classification.status === 401 || /unauthorized|invalid_grant|requires_reauth/i.test(classification.message);
+}
+function computeBackoffMs(attemptNumber) {
+  const base = 1e3 * Math.pow(2, Math.max(0, attemptNumber - 1));
+  const capped = Math.min(base, 6e4);
+  const jitter = Math.floor(Math.random() * 500);
+  return capped + jitter;
+}
+export {
+  classifyOutboundError,
+  computeBackoffMs,
+  isReauthError
+};
+//# sourceMappingURL=error-classification.js.map

package/dist/modules/communication_channels/lib/error-classification.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/error-classification.ts"],
+  "sourcesContent": ["/**\n * Classify provider errors for outbound retry decisions.\n *\n * Transient errors (network, 429, 5xx, timeout) \u2192 retry with backoff.\n * Permanent errors (4xx auth/validation/quota) \u2192 fail fast, no retry.\n *\n * Adapters can also throw classified errors directly by setting `transient: false`\n * on their thrown Error instance. This helper falls back to heuristics when an\n * adapter throws plain Error instances.\n */\n\nexport type ErrorClassification = {\n  transient: boolean\n  /** HTTP status if known; helps with backoff decisions (e.g., `Retry-After`) */\n  status?: number\n  /** Human-readable summary suitable for logging. */\n  message: string\n}\n\nconst TRANSIENT_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524])\n\n/**\n * Postgres SQLSTATEs that are transient (the operation can succeed on retry).\n * These reach the inbound-ingest classifier when a DB blip happens mid-ingest;\n * treating them as permanent would dead-letter the message AND advance the IMAP\n * cursor, silently losing inbound mail (the exact \"cursor drift\" failure the\n * email spec set out to prevent). Driver errors expose the SQLSTATE on `.code`.\n */\nconst TRANSIENT_PG_SQLSTATES = new Set([\n  '40001', // serialization_failure\n  '40P01', // deadlock_detected\n  '55P03', // lock_not_available\n  '53300', // too_many_connections\n  '53400', // configuration_limit_exceeded\n  '57P01', // admin_shutdown\n  '57P02', // crash_shutdown\n  '57P03', // cannot_connect_now (db starting up)\n  '08000', // connection_exception\n  '08001', // sqlclient_unable_to_establish_sqlconnection\n  '08003', // connection_does_not_exist\n  '08006', // connection_failure\n])\n\nconst TRANSIENT_CODE_PATTERNS = [\n  /ECONNRESET/i,\n  /ETIMEDOUT/i,\n  /ECONNREFUSED/i,\n  /ENOTFOUND/i,\n  /EAI_AGAIN/i,\n  /socket hang up/i,\n  /network timeout/i,\n  /\\btimed?\\s*out\\b/i,\n  /service unavailable/i,\n  /rate limit/i,\n  /too many requests/i,\n  /temporarily unavailable/i,\n  /try again later/i,\n  // imapflow surfaces these on TLS/socket-level drops that almost always\n  // recover on the next attempt. Treating them as permanent kills the\n  // channel after a single bad packet (regression observed during the demo:\n  // a network hiccup put a freshly-connected mailbox into a non-recoverable\n  // `error` state until the operator manually clicked \"Retry\").\n  /unexpected close/i,\n  /connection not available/i,\n  /connection closed/i,\n  /server closed connection/i,\n  // Postgres transient failures surfaced as text by the ORM wrapper (the\n  // SQLSTATE on `.code` is the primary signal; these catch wrapped errors that\n  // only carry the message). See TRANSIENT_PG_SQLSTATES.\n  /deadlock detected/i,\n  /could not serialize access/i,\n  /connection terminated/i,\n  /too many clients already/i,\n  /the database system is (starting up|shutting down|in recovery)/i,\n]\n\nexport function classifyOutboundError(error: unknown): ErrorClassification {\n  if (!error) {\n    return { transient: false, message: 'Unknown error' }\n  }\n\n  if (error instanceof Error) {\n    // Explicit hint from a classification-aware adapter.\n    const explicit = (error as Error & { transient?: boolean; status?: number }).transient\n    const status = (error as Error & { status?: number }).status\n    if (explicit !== undefined) {\n      return { transient: Boolean(explicit), status, message: error.message }\n    }\n    // Postgres driver errors expose the SQLSTATE on `.code`. A transient DB\n    // failure during inbound ingest MUST classify as transient so the caller\n    // aborts without advancing the cursor (no mail loss) rather than dead-lettering.\n    const code = (error as Error & { code?: string }).code\n    if (typeof code === 'string' && TRANSIENT_PG_SQLSTATES.has(code)) {\n      return { transient: true, status, message: error.message }\n    }\n    if (typeof status === 'number') {\n      return {\n        transient: TRANSIENT_STATUS_CODES.has(status),\n        status,\n        message: error.message,\n      }\n    }\n    const haystack = `${error.name} ${error.message}`\n    const matchesPattern = TRANSIENT_CODE_PATTERNS.some((pattern) => pattern.test(haystack))\n    return { transient: matchesPattern, message: error.message }\n  }\n\n  return { transient: false, message: String(error) }\n}\n\n/**\n * Decide whether a classified provider error means the channel's stored\n * credentials are no longer valid and the user must re-authorize.\n *\n * A 401, or an `invalid_grant` / `unauthorized` message, is unrecoverable by\n * retry: the access token is rejected and (for OAuth) the refresh token is\n * likely revoked too. Provider adapters may also surface the explicit\n * `requires_reauth` sentinel instead of a status \u2014 e.g. Gmail\n * `sendMessage` returns `{ status: 'failed', error: 'requires_reauth' }` on a\n * 401, which the outbound command rethrows as a status-less `Error`. Match that\n * sentinel too so the channel still flips to `requires_reauth`. Callers flip the\n * channel so the operator gets a clear signal. Kept identical to the inbound\n * poll path so inbound and outbound failures behave consistently.\n */\nexport function isReauthError(classification: ErrorClassification): boolean {\n  return (\n    classification.status === 401 ||\n    /unauthorized|invalid_grant|requires_reauth/i.test(classification.message)\n  )\n}\n\n/**\n * Compute exponential backoff delay (ms) for the given attempt number.\n *\n * Attempt 1 (= first retry) \u2192 1s, attempt 2 \u2192 2s, attempt 3 \u2192 4s, ...\n * Capped at 60s. Plus a small jitter so concurrent failures don't all retry\n * simultaneously.\n */\nexport function computeBackoffMs(attemptNumber: number): number {\n  const base = 1000 * Math.pow(2, Math.max(0, attemptNumber - 1))\n  const capped = Math.min(base, 60_000)\n  const jitter = Math.floor(Math.random() * 500)\n  return capped + jitter\n}\n"],
+  "mappings": "AAmBA,MAAM,yBAAyB,oBAAI,IAAI,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,GAAG,CAAC;AAS9F,MAAM,yBAAyB,oBAAI,IAAI;AAAA,EACrC;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF,CAAC;AAED,MAAM,0BAA0B;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA,EAIA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEO,SAAS,sBAAsB,OAAqC;AACzE,MAAI,CAAC,OAAO;AACV,WAAO,EAAE,WAAW,OAAO,SAAS,gBAAgB;AAAA,EACtD;AAEA,MAAI,iBAAiB,OAAO;AAE1B,UAAM,WAAY,MAA2D;AAC7E,UAAM,SAAU,MAAsC;AACtD,QAAI,aAAa,QAAW;AAC1B,aAAO,EAAE,WAAW,QAAQ,QAAQ,GAAG,QAAQ,SAAS,MAAM,QAAQ;AAAA,IACxE;AAIA,UAAM,OAAQ,MAAoC;AAClD,QAAI,OAAO,SAAS,YAAY,uBAAuB,IAAI,IAAI,GAAG;AAChE,aAAO,EAAE,WAAW,MAAM,QAAQ,SAAS,MAAM,QAAQ;AAAA,IAC3D;AACA,QAAI,OAAO,WAAW,UAAU;AAC9B,aAAO;AAAA,QACL,WAAW,uBAAuB,IAAI,MAAM;AAAA,QAC5C;AAAA,QACA,SAAS,MAAM;AAAA,MACjB;AAAA,IACF;AACA,UAAM,WAAW,GAAG,MAAM,IAAI,IAAI,MAAM,OAAO;AAC/C,UAAM,iBAAiB,wBAAwB,KAAK,CAAC,YAAY,QAAQ,KAAK,QAAQ,CAAC;AACvF,WAAO,EAAE,WAAW,gBAAgB,SAAS,MAAM,QAAQ;AAAA,EAC7D;AAEA,SAAO,EAAE,WAAW,OAAO,SAAS,OAAO,KAAK,EAAE;AACpD;AAgBO,SAAS,cAAc,gBAA8C;AAC1E,SACE,eAAe,WAAW,OAC1B,8CAA8C,KAAK,eAAe,OAAO;AAE7E;AASO,SAAS,iBAAiB,eAA+B;AAC9D,QAAM,OAAO,MAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,gBAAgB,CAAC,CAAC;AAC9D,QAAM,SAAS,KAAK,IAAI,MAAM,GAAM;AACpC,QAAM,SAAS,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG;AAC7C,SAAO,SAAS;AAClB;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/gmail-pubsub-jwt.js

@@ -0,0 +1,185 @@
+import crypto from "node:crypto";
+const GOOGLE_CERTS_URL = "https://www.googleapis.com/oauth2/v1/certs";
+const CERT_CACHE_TTL_MS = 60 * 60 * 1e3;
+const CERT_FETCH_TIMEOUT_MS = 5e3;
+const GOOGLE_ACCEPTED_ISSUERS = /* @__PURE__ */ new Set(["https://accounts.google.com", "accounts.google.com"]);
+class GmailPubSubJwtError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "GmailPubSubJwtError";
+    this.code = code;
+  }
+}
+class FetchGmailPubSubVerifier {
+  constructor() {
+    this.certCache = null;
+  }
+  async verify(input) {
+    const token = extractBearer(input.authorizationHeader);
+    if (!token) throw new GmailPubSubJwtError("Missing Authorization bearer token", "missing_token");
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new GmailPubSubJwtError("JWT must have three dot-separated parts", "invalid_format");
+    }
+    const [headerB64, payloadB64, signatureB64] = parts;
+    let header;
+    let claims;
+    try {
+      header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf-8"));
+      claims = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf-8"));
+    } catch {
+      throw new GmailPubSubJwtError("JWT header/payload not parseable", "invalid_format");
+    }
+    const kid = typeof header.kid === "string" ? header.kid : null;
+    const alg = typeof header.alg === "string" ? header.alg : null;
+    if (!kid || alg !== "RS256") {
+      throw new GmailPubSubJwtError(`Unsupported JWT alg/kid: alg=${alg ?? "?"} kid=${kid ?? "?"}`, "invalid_format");
+    }
+    const certs = await this.getCerts();
+    const cert = certs[kid];
+    if (!cert) {
+      this.certCache = null;
+      const refreshed = await this.getCerts();
+      const fresh = refreshed[kid];
+      if (!fresh) throw new GmailPubSubJwtError(`No cert for kid=${kid}`, "invalid_signature");
+      verifySignature(`${headerB64}.${payloadB64}`, signatureB64, fresh);
+    } else {
+      verifySignature(`${headerB64}.${payloadB64}`, signatureB64, cert);
+    }
+    validateClaims(claims, input);
+    return claims;
+  }
+  async getCerts() {
+    if (this.certCache && Date.now() - this.certCache.fetchedAt < CERT_CACHE_TTL_MS) {
+      return this.certCache.certs;
+    }
+    let res;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CERT_FETCH_TIMEOUT_MS);
+    try {
+      res = await fetch(GOOGLE_CERTS_URL, { signal: controller.signal });
+    } catch (err) {
+      throw new GmailPubSubJwtError(
+        `Failed to fetch Google certs: ${err instanceof Error ? err.message : String(err)}`,
+        "fetch_certs_failed"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      throw new GmailPubSubJwtError(`Google certs endpoint returned ${res.status}`, "fetch_certs_failed");
+    }
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch (err) {
+      throw new GmailPubSubJwtError(
+        `Google certs endpoint returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        "fetch_certs_failed"
+      );
+    }
+    const certs = toCertMap(parsed);
+    if (!certs) {
+      throw new GmailPubSubJwtError("Google certs endpoint returned an unexpected shape", "fetch_certs_failed");
+    }
+    this.certCache = { certs, fetchedAt: Date.now() };
+    return certs;
+  }
+}
+function toCertMap(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return null;
+  const entries = Object.entries(value);
+  if (entries.length === 0) return null;
+  const certs = {};
+  for (const [kid, pem] of entries) {
+    if (typeof pem !== "string" || pem.length === 0) return null;
+    certs[kid] = pem;
+  }
+  return certs;
+}
+function extractBearer(header) {
+  if (!header) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+function verifySignature(input, signatureB64, cert) {
+  const verifier = crypto.createVerify("RSA-SHA256");
+  verifier.update(input);
+  verifier.end();
+  const signature = Buffer.from(signatureB64, "base64url");
+  const ok = verifier.verify(cert, signature);
+  if (!ok) {
+    throw new GmailPubSubJwtError("JWT signature verification failed", "invalid_signature");
+  }
+}
+function validateClaims(claims, input) {
+  const now = Math.floor(Date.now() / 1e3);
+  if (typeof claims.exp !== "number" || claims.exp < now - 5) {
+    throw new GmailPubSubJwtError("JWT expired or missing exp", "expired");
+  }
+  if (typeof claims.iat === "number" && claims.iat > now + 5) {
+    throw new GmailPubSubJwtError("JWT issued in the future", "expired");
+  }
+  if (typeof claims.iss !== "string" || !GOOGLE_ACCEPTED_ISSUERS.has(claims.iss)) {
+    throw new GmailPubSubJwtError(
+      `JWT issuer not accepted (got ${typeof claims.iss === "string" ? claims.iss : "none"})`,
+      "wrong_issuer"
+    );
+  }
+  const audOk = Array.isArray(claims.aud) ? claims.aud.includes(input.expectedAudience) : claims.aud === input.expectedAudience;
+  if (!audOk) {
+    throw new GmailPubSubJwtError(
+      `JWT audience mismatch (expected ${input.expectedAudience})`,
+      "wrong_audience"
+    );
+  }
+  const emailVerified = claims.emailVerified === true || claims.email_verified === true;
+  if (!emailVerified || claims.email !== input.expectedEmail) {
+    throw new GmailPubSubJwtError(
+      `JWT email mismatch (expected ${input.expectedEmail})`,
+      "wrong_email"
+    );
+  }
+}
+let cachedVerifier = null;
+function getGmailPubSubVerifier() {
+  if (!cachedVerifier) cachedVerifier = new FetchGmailPubSubVerifier();
+  return cachedVerifier;
+}
+function setGmailPubSubVerifier(verifier) {
+  cachedVerifier = verifier;
+}
+function decodeGmailPubSubBody(rawBody) {
+  let envelope;
+  try {
+    envelope = JSON.parse(rawBody);
+  } catch {
+    throw new GmailPubSubJwtError("Body is not valid JSON", "invalid_format");
+  }
+  if (!envelope.message?.data) {
+    throw new GmailPubSubJwtError("Envelope missing message.data", "invalid_format");
+  }
+  let payloadText;
+  try {
+    payloadText = Buffer.from(envelope.message.data, "base64").toString("utf-8");
+  } catch {
+    throw new GmailPubSubJwtError("message.data not base64 decodable", "invalid_format");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(payloadText);
+  } catch {
+    throw new GmailPubSubJwtError("message.data JSON not parseable", "invalid_format");
+  }
+  if (!payload.emailAddress || payload.historyId === void 0) {
+    throw new GmailPubSubJwtError("message.data missing emailAddress or historyId", "invalid_format");
+  }
+  return payload;
+}
+export {
+  GmailPubSubJwtError,
+  decodeGmailPubSubBody,
+  getGmailPubSubVerifier,
+  setGmailPubSubVerifier
+};
+//# sourceMappingURL=gmail-pubsub-jwt.js.map