@open-mercato/core 0.8.1-develop.7261.1.5d42353f61 → 0.8.1-develop.7266.1.8e520bbe03

package/src/modules/communication_channels/lib/email-mime.ts

@@ -414,7 +414,19 @@ export interface NormalizeMimeInboundOptions {
   fallbackMessageId: string
   /** Compute the conversation grouping id from the resolved message id + references. */
   resolveConversationId: (context: { messageId: string; references: string[] }) => string
-  /** Fallback timestamp when the parsed message has no Date header. */
+  /**
+   * When the provider received the message (Gmail `internalDate`, IMAP
+   * `INTERNALDATE`). Preferred over the MIME `Date` header for the message
+   * timestamp: the header is written by the sender's client and can be forged
+   * or skewed, and since #6095 the timestamp also dates the platform message
+   * and the CRM interaction, so a bad header would pin a message in the future
+   * or hide it in the past.
+   */
+  receivedAt?: Date
+  /**
+   * Fallback timestamp when neither `receivedAt` nor a usable Date header is
+   * available.
+   */
   fallbackDate?: Date
   /** Provider-specific fields merged into `channelMetadata`. */
   channelMetadata?: (parsed: ParsedMail) => Record<string, unknown>
@@ -422,6 +434,40 @@ export interface NormalizeMimeInboundOptions {
   channelPayload?: (parsed: ParsedMail) => Record<string, unknown>
 }
 
+/**
+ * A MIME `Date` header this far ahead of the clock is treated as bogus. Clock
+ * skew between real mail servers is seconds to minutes; a day of tolerance
+ * keeps legitimate mail while stopping a forged header from pinning a message
+ * to the top of a `sent_at`-sorted inbox for weeks.
+ */
+const MAX_MIME_DATE_FUTURE_SKEW_MS = 24 * 60 * 60 * 1000
+
+function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime())
+}
+
+/**
+ * Pick the timestamp for an inbound message.
+ *
+ * Order: the provider's receipt time; then the sender's MIME `Date` header,
+ * unless it is unparsable or more than a day in the future; then the caller's
+ * fallback; then now. Exported for tests.
+ */
+export function resolveInboundTimestamp(input: {
+  receivedAt?: Date
+  mimeDate?: Date
+  fallbackDate?: Date
+  now?: Date
+}): Date {
+  if (isValidDate(input.receivedAt)) return input.receivedAt
+  const now = input.now ?? new Date()
+  if (isValidDate(input.mimeDate) && input.mimeDate.getTime() <= now.getTime() + MAX_MIME_DATE_FUTURE_SKEW_MS) {
+    return input.mimeDate
+  }
+  if (isValidDate(input.fallbackDate)) return input.fallbackDate
+  return now
+}
+
 /**
  * Build the hub's canonical `NormalizedInboundMessage` from a parsed MIME
  * message. Providers supply the bits that genuinely differ (message-id
@@ -474,7 +520,11 @@ export function normalizeMimeInbound(options: NormalizeMimeInboundOptions): Norm
     body,
     bodyFormat,
     attachments,
-    timestamp: parsed.date ? new Date(parsed.date) : options.fallbackDate ?? new Date(),
+    timestamp: resolveInboundTimestamp({
+      receivedAt: options.receivedAt,
+      mimeDate: parsed.date ? new Date(parsed.date) : undefined,
+      fallbackDate: options.fallbackDate,
+    }),
     replyToExternalId: inReplyTo ?? undefined,
     channelPayload,
     channelContentType: 'email/mime',

package/src/modules/customers/lib/link-channel-message-handler.ts

@@ -34,6 +34,13 @@ type LinkChannelMessagePayload = {
   organizationId?: string | null
   providerKey?: string | null
   direction?: 'inbound' | 'outbound' | null
+  /**
+   * The provider's own receive/send time, carried by the hub on the event
+   * (#6095). An ISO string when the event rode the queue, a Date for an
+   * in-process emit. Absent on events enqueued before the field existed and on
+   * adapters that supply no timestamp.
+   */
+  providerTimestamp?: string | Date | null
 }
 
 type SubscriberContext = {
@@ -88,6 +95,17 @@ export default async function handler(
   const metaJson = (link.channelMetadata ?? null) as Record<string, unknown> | null
   const payloadJson = (link.channelPayload ?? null) as Record<string, unknown> | null
 
+  // ── (1b) Resolve when the email actually happened ─────────────────────
+  //
+  // `link.createdAt` is when the hub ingested the message, which for a history
+  // import is the import minute, not the day the mail arrived (#6095). The hub
+  // carries the provider's own timestamp on the event payload, so take it from
+  // there: reading the communication_channels ExternalMessage row here would
+  // cross the storage boundary (Cross-Module Coupling in AGENTS.md) and add a
+  // peer-table query per event. Resolved once and threaded through every branch
+  // below so the address-match and threading-inheritance paths agree.
+  const occurredAt = resolveOccurredAt(payload, link)
+
   // ── (2) Resolve the channel to get its owner userId ───────────────────
   //
   // The channel.userId is needed for two purposes:
@@ -172,7 +190,7 @@ export default async function handler(
   // Early exit: no addresses AND no hint → nothing to link.
   if (normalized.length === 0 && !crmPersonId) {
     // Before giving up, try threading-inheritance (TC-CRM-EMAIL-005).
-    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson)
+    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson, occurredAt)
     return
   }
 
@@ -183,7 +201,7 @@ export default async function handler(
 
   if (personIdSet.size === 0) {
     // Try threading-inheritance before giving up.
-    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson)
+    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson, occurredAt)
     return
   }
 
@@ -211,7 +229,6 @@ export default async function handler(
         ? (payloadJson!.text as string)
         : null
 
-  const occurredAt = link.createdAt instanceof Date ? link.createdAt : new Date()
   const providerKey =
     typeof link.providerKey === 'string' ? (link.providerKey as string) : null
 
@@ -257,6 +274,7 @@ async function handleThreadingInheritance(
   channelUserId: string | null,
   metaJson: Record<string, unknown> | null,
   payloadJson: Record<string, unknown> | null,
+  occurredAt: Date,
 ): Promise<void> {
   // ── Primary: inherit Person(s) from the hub's authoritative thread ──────
   //
@@ -325,7 +343,6 @@ async function handleThreadingInheritance(
           : typeof metaJson?.bodyText === 'string'
             ? (metaJson.bodyText as string)
             : null
-      const occurredAt = _link.createdAt instanceof Date ? (_link.createdAt as Date) : new Date()
       const providerKey = typeof _link.providerKey === 'string' ? (_link.providerKey as string) : null
       await persistInteractions(em, threadPersonIds, {
         linkId,
@@ -420,7 +437,6 @@ async function handleThreadingInheritance(
   const inheritedMeta = (link.channelMetadata ?? null) as Record<string, unknown> | null
   const subject =
     typeof inheritedMeta?.subject === 'string' ? (inheritedMeta.subject as string) : null
-  const occurredAt = link.createdAt instanceof Date ? (link.createdAt as Date) : new Date()
   const providerKey =
     typeof link.providerKey === 'string' ? (link.providerKey as string) : null
 
@@ -444,6 +460,33 @@ async function handleThreadingInheritance(
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
+/**
+ * When the linked email happened, for `CustomerInteraction.occurredAt` (#6095).
+ *
+ * Preference order:
+ *   1. `payload.providerTimestamp` — the provider's own receive/send time, put
+ *      on the hub event by ingest / delivery;
+ *   2. `MessageChannelLink.createdAt` — the ingest time, the only date this
+ *      handler knew before #6095, and the compatibility path for events that
+ *      were enqueued before the field existed;
+ *   3. now, for a link row with no usable `createdAt` (test stubs).
+ */
+function resolveOccurredAt(
+  payload: LinkChannelMessagePayload,
+  link: Record<string, unknown>,
+): Date {
+  const ingestedAt = link.createdAt instanceof Date ? link.createdAt : new Date()
+  const carried = payload.providerTimestamp
+  if (carried instanceof Date) {
+    return Number.isNaN(carried.getTime()) ? ingestedAt : carried
+  }
+  if (typeof carried === 'string' && carried) {
+    const parsed = new Date(carried)
+    if (!Number.isNaN(parsed.getTime())) return parsed
+  }
+  return ingestedAt
+}
+
 interface InteractionData {
   linkId: string
   tenantId: string

package/src/modules/messages/api/route.ts

@@ -470,12 +470,15 @@ export async function POST(req: Request) {
         sourceHint.data,
       )
     : undefined
-  // `inboundFromChannel` is likewise server-only (#6093): channel ingest sets
-  // it so an inbound message can be addressed to the conversation's assignee,
-  // and a request body must not be able to waive the recipients rule with it.
+  // `inboundFromChannel` and `sentAt` are likewise server-only (#6093, #6095):
+  // channel ingest sets them so an inbound message can be addressed to the
+  // conversation's assignee and stamped with the provider's receive time, but
+  // a request body must not be able to waive the recipients rule or backdate
+  // a message with them.
   const {
     sourceChannelType: _clientSuppliedChannelType,
     inboundFromChannel: _clientSuppliedInboundFlag,
+    sentAt: _clientSuppliedSentAt,
     ...clientBody
   } = (body ?? {}) as Record<string, unknown>
   const input = composeMessageSchema.parse({

package/src/modules/messages/commands/messages.ts

@@ -333,7 +333,9 @@ const composeMessageCommand: CommandHandler<unknown, { id: string; threadId: str
         priority: input.priority,
         status: input.isDraft ? 'draft' : 'sent',
         isDraft: input.isDraft ?? false,
-        sentAt: input.isDraft ? null : new Date(),
+        // #6095: channel ingest passes the provider's timestamp so an imported
+        // mailbox sorts by when the mail was received, not when it was imported.
+        sentAt: input.isDraft ? null : input.sentAt ?? new Date(),
         actionData: input.actionData as MessageActionData | undefined,
         sendViaEmail,
         idempotencyKey: input.idempotencyKey ?? null,

package/src/modules/messages/data/validators.ts

@@ -138,12 +138,20 @@ const composeMessageBaseSchema = z.object({
   sendViaEmail: z.boolean().optional().default(false),
   parentMessageId: z.string().uuid().optional(),
   isDraft: z.boolean().optional().default(false),
+  /**
+   * When the message was actually sent, if the caller knows better than "now"
+   * (#6095). Channel ingest sets it to the provider's timestamp so an imported
+   * mailbox keeps its real chronology instead of collapsing onto the import
+   * minute. Server-only: the HTTP route strips any client-sent value, so a
+   * browser caller cannot backdate a message. Ignored for drafts.
+   */
+  sentAt: z.coerce.date().optional(),
 })
 
 type ComposeMessageRefinementValue = Omit<
   z.infer<typeof composeMessageBaseSchema>,
-  'sourceChannelType'
-> & { sourceChannelType?: string }
+  'sourceChannelType' | 'sentAt'
+> & { sourceChannelType?: string; sentAt?: Date }
 
 function refineComposeMessage(value: ComposeMessageRefinementValue, ctx: z.RefinementCtx): void {
   const isDraft = value.isDraft ?? false
@@ -213,23 +221,24 @@ function refineComposeMessage(value: ComposeMessageRefinementValue, ctx: z.Refin
 }
 
 /**
- * Full compose contract, including the server-resolved `sourceChannelType` and
- * the ingest-only `inboundFromChannel`. Used by the `messages.messages.compose`
- * command and by the HTTP route AFTER it has resolved the channel type itself.
+ * Full compose contract, including the server-resolved `sourceChannelType`,
+ * the ingest-only `inboundFromChannel`, and the server-supplied `sentAt`. Used
+ * by the `messages.messages.compose` command and by the HTTP route AFTER it
+ * has resolved the channel type itself.
  */
 export const composeMessageSchema = composeMessageBaseSchema.superRefine(refineComposeMessage)
 
 /**
  * Client-facing compose contract — the same rules minus the server-only fields:
- * `sourceChannelType` is never accepted from a request body (#4975) and neither
- * is `inboundFromChannel` (#6093). Published in OpenAPI so the documented
- * request shape matches what `POST /api/messages` actually reads: the route
- * discards any client-sent value for these, resolves the real channel type from
- * the referenced conversation or parent message, and only then validates
- * against {@link composeMessageSchema}.
+ * `sourceChannelType` is never accepted from a request body (#4975), neither is
+ * `inboundFromChannel` (#6093) nor `sentAt` (#6095). Published in OpenAPI so the
+ * documented request shape matches what `POST /api/messages` actually reads:
+ * the route discards any client-sent value for these, resolves the real
+ * channel type from the referenced conversation or parent message, and only
+ * then validates against {@link composeMessageSchema}.
  */
 export const composeMessageRequestSchema = composeMessageBaseSchema
-  .omit({ sourceChannelType: true, inboundFromChannel: true })
+  .omit({ sourceChannelType: true, inboundFromChannel: true, sentAt: true })
   .superRefine(refineComposeMessage)
 
 export const updateDraftSchema = z.object({