@intx/mail-memory 0.1.2

package/src/mailbox.ts

@@ -0,0 +1,113 @@
+import type { CryptoProvider, MailboxEvent } from "@intx/types/runtime";
+
+/**
+ * Pre-parsed envelope extracted from MIME headers at delivery time.
+ * Avoids re-parsing raw bytes for every search operation.
+ */
+export type StoredEnvelope = {
+  messageId: string;
+  from: string;
+  to: string[];
+  subject: string;
+  date: Date;
+  inReplyTo: string | undefined;
+  references: string[];
+  interchangeType: string | undefined;
+  interchangeCorrelationId: string | undefined;
+};
+
+/**
+ * A single message stored in memory. The `raw` field contains the complete
+ * RFC 2822 message bytes (headers + MIME body). All fetch operations parse
+ * from these bytes, guaranteeing byte-exact signature verification.
+ */
+export type StoredMessage = {
+  uid: number;
+  modseq: number;
+  flags: Set<string>;
+  raw: Uint8Array;
+  envelope: StoredEnvelope;
+};
+
+export type MailboxStore = {
+  messages: StoredMessage[];
+  uidCounter: number;
+  modseqCounter: number;
+  uidValidity: number;
+};
+
+export type AddressEntry = {
+  mailboxes: Map<string, MailboxStore>;
+  watchCallbacks: Map<string, Set<(event: MailboxEvent) => void>>;
+  crypto: CryptoProvider;
+};
+
+export const DEFAULT_MAILBOXES = [
+  "INBOX",
+  "Sent",
+  "Drafts",
+  "Archive",
+  "Trash",
+] as const;
+
+export function createMailboxStore(): MailboxStore {
+  return {
+    messages: [],
+    uidCounter: 1,
+    modseqCounter: 1,
+    uidValidity: Date.now(),
+  };
+}
+
+export function createAddressEntry(crypto: CryptoProvider): AddressEntry {
+  const mailboxes = new Map<string, MailboxStore>();
+  for (const name of DEFAULT_MAILBOXES) {
+    mailboxes.set(name, createMailboxStore());
+  }
+  return {
+    mailboxes,
+    watchCallbacks: new Map(),
+    crypto,
+  };
+}
+
+/**
+ * Append a message to a mailbox store. Assigns UID and MODSEQ, returns the
+ * assigned UID.
+ */
+export function appendToMailbox(
+  store: MailboxStore,
+  raw: Uint8Array,
+  envelope: StoredEnvelope,
+  flags: string[],
+): number {
+  const uid = store.uidCounter++;
+  const modseq = store.modseqCounter++;
+  store.messages.push({
+    uid,
+    modseq,
+    flags: new Set(flags),
+    raw,
+    envelope,
+  });
+  return uid;
+}
+
+export function findMessage(
+  store: MailboxStore,
+  uid: number,
+): StoredMessage | undefined {
+  return store.messages.find((m) => m.uid === uid);
+}
+
+export function requireMessage(
+  store: MailboxStore,
+  uid: number,
+  mailboxName: string,
+): StoredMessage {
+  const msg = findMessage(store, uid);
+  if (msg === undefined) {
+    throw new Error(`Message UID ${uid} not found in mailbox "${mailboxName}"`);
+  }
+  return msg;
+}

package/src/search.ts

@@ -0,0 +1,170 @@
+import type { SearchQuery, MessageRef } from "@intx/types/runtime";
+import type { MailboxStore, StoredMessage } from "./mailbox";
+import { parseHeaderSection } from "@intx/mime";
+
+/**
+ * Execute an IMAP SEARCH-equivalent query over an in-memory mailbox.
+ *
+ * Supports: from, to, cc, bcc, header (field match), before/after/on,
+ * sentBefore/sentAfter/sentOn, hasFlags, missingFlags, body, text,
+ * largerThan, smallerThan, and boolean and/or/not composition.
+ *
+ * Returns MessageRef[] for all matching messages, ordered by UID.
+ */
+export function executeSearch(
+  mailboxName: string,
+  store: MailboxStore,
+  query: SearchQuery,
+): MessageRef[] {
+  const results: MessageRef[] = [];
+  for (const msg of store.messages) {
+    if (matchMessage(msg, query)) {
+      results.push({ uid: msg.uid, mailbox: mailboxName });
+    }
+  }
+  return results;
+}
+
+function matchMessage(msg: StoredMessage, query: SearchQuery): boolean {
+  if (query.from !== undefined) {
+    if (!msg.envelope.from.toLowerCase().includes(query.from.toLowerCase())) {
+      return false;
+    }
+  }
+
+  if (query.to !== undefined) {
+    const queryTo = query.to;
+    const toMatch = msg.envelope.to.some((addr) =>
+      addr.toLowerCase().includes(queryTo.toLowerCase()),
+    );
+    if (!toMatch) return false;
+  }
+
+  if (query.cc !== undefined) {
+    const headers = lazyHeaders(msg);
+    const ccHeader = headers.get("cc") ?? "";
+    if (!ccHeader.toLowerCase().includes(query.cc.toLowerCase())) {
+      return false;
+    }
+  }
+
+  if (query.bcc !== undefined) {
+    const headers = lazyHeaders(msg);
+    const bccHeader = headers.get("bcc") ?? "";
+    if (!bccHeader.toLowerCase().includes(query.bcc.toLowerCase())) {
+      return false;
+    }
+  }
+
+  if (query.header !== undefined) {
+    const { field, contains } = query.header;
+    const headers = lazyHeaders(msg);
+    const value = headers.get(field.toLowerCase()) ?? "";
+    if (!value.toLowerCase().includes(contains.toLowerCase())) {
+      return false;
+    }
+  }
+
+  if (query.before !== undefined) {
+    if (msg.envelope.date >= query.before) return false;
+  }
+  if (query.after !== undefined) {
+    if (msg.envelope.date <= query.after) return false;
+  }
+  if (query.on !== undefined) {
+    const d = msg.envelope.date;
+    const q = query.on;
+    if (
+      d.getUTCFullYear() !== q.getUTCFullYear() ||
+      d.getUTCMonth() !== q.getUTCMonth() ||
+      d.getUTCDate() !== q.getUTCDate()
+    ) {
+      return false;
+    }
+  }
+
+  // Sent date filters use the Date header (same as envelope date here).
+  if (query.sentBefore !== undefined) {
+    if (msg.envelope.date >= query.sentBefore) return false;
+  }
+  if (query.sentAfter !== undefined) {
+    if (msg.envelope.date <= query.sentAfter) return false;
+  }
+  if (query.sentOn !== undefined) {
+    const d = msg.envelope.date;
+    const q = query.sentOn;
+    if (
+      d.getUTCFullYear() !== q.getUTCFullYear() ||
+      d.getUTCMonth() !== q.getUTCMonth() ||
+      d.getUTCDate() !== q.getUTCDate()
+    ) {
+      return false;
+    }
+  }
+
+  if (query.hasFlags !== undefined) {
+    for (const flag of query.hasFlags) {
+      if (!msg.flags.has(flag)) return false;
+    }
+  }
+
+  if (query.missingFlags !== undefined) {
+    for (const flag of query.missingFlags) {
+      if (msg.flags.has(flag)) return false;
+    }
+  }
+
+  if (query.largerThan !== undefined) {
+    if (msg.raw.length <= query.largerThan) return false;
+  }
+  if (query.smallerThan !== undefined) {
+    if (msg.raw.length >= query.smallerThan) return false;
+  }
+
+  if (query.body !== undefined || query.text !== undefined) {
+    const rawText = new TextDecoder("utf-8", { fatal: false }).decode(msg.raw);
+    if (query.body !== undefined) {
+      const { bodyOffset } = parseHeaderSection(msg.raw);
+      const bodyText = new TextDecoder("utf-8", { fatal: false }).decode(
+        msg.raw.slice(bodyOffset),
+      );
+      if (!bodyText.toLowerCase().includes(query.body.toLowerCase())) {
+        return false;
+      }
+    }
+    if (query.text !== undefined) {
+      if (!rawText.toLowerCase().includes(query.text.toLowerCase())) {
+        return false;
+      }
+    }
+  }
+
+  if (query.and !== undefined) {
+    for (const sub of query.and) {
+      if (!matchMessage(msg, sub)) return false;
+    }
+  }
+
+  if (query.or !== undefined) {
+    if (query.or.length > 0) {
+      const anyMatch = query.or.some((sub) => matchMessage(msg, sub));
+      if (!anyMatch) return false;
+    }
+  }
+
+  if (query.not !== undefined) {
+    if (matchMessage(msg, query.not)) return false;
+  }
+
+  return true;
+}
+
+const headerCache = new WeakMap<StoredMessage, Map<string, string>>();
+
+function lazyHeaders(msg: StoredMessage): Map<string, string> {
+  const cached = headerCache.get(msg);
+  if (cached !== undefined) return cached;
+  const { headers } = parseHeaderSection(msg.raw);
+  headerCache.set(msg, headers);
+  return headers;
+}

package/src/send.ts

@@ -0,0 +1,293 @@
+import type {
+  OutboundMessage,
+  SendReceipt,
+  MailboxEvent,
+} from "@intx/types/runtime";
+import type { AddressEntry, StoredEnvelope } from "./mailbox";
+import { appendToMailbox } from "./mailbox";
+import {
+  assembleSignedContent,
+  assembleMessage,
+  generateMessageId,
+  parseHeaderSection,
+  createDetachedSignatureFromProvider,
+  type MessageHeaders as MimeMessageHeaders,
+  type ConversationContent,
+  type StructuredContent,
+} from "@intx/mime";
+import { buildMessageHeaders } from "./headers";
+
+const CONVERSATION_TYPES = new Set([
+  "conversation.message",
+  "conversation.join",
+  "conversation.leave",
+]);
+
+/**
+ * Callback for delivering messages to recipients not registered on this
+ * transport. The federation layer provides this to forward messages to
+ * the hub for remote routing.
+ */
+export type RemoteSendHandler = (
+  rawMessage: Uint8Array,
+  recipients: string[],
+) => Promise<void>;
+
+/**
+ * Context passed to MessageSentHandler callbacks after a message is fully
+ * assembled and delivered.
+ */
+export type MessageSentContext = {
+  senderAddress: string;
+  rawMessage: Uint8Array;
+  messageId: string;
+  /** Deduplicated union of to and cc — the full routing set. */
+  recipients: string[];
+  /** To addresses only (before merging with cc). */
+  to: string[];
+  /** CC addresses only. Empty array when no CC recipients. */
+  cc: string[];
+  /** True when all recipients were delivered locally (no remote leg). */
+  localOnly: boolean;
+};
+
+/**
+ * Callback fired after a message is fully assembled and delivered. The
+ * send is already complete when this fires — a handler rejection does
+ * not mean the message was not delivered.
+ *
+ * Used by the sidecar to commit outbound wire messages to the git audit
+ * trail and forward metadata to the hub.
+ */
+export type MessageSentHandler = (ctx: MessageSentContext) => Promise<void>;
+
+/**
+ * Execute the send() flow:
+ * 1. Validate sender registration, split recipients into local/remote
+ * 2. Build signed content part (MIME bytes to sign)
+ * 3. Sign with sender's CryptoProvider
+ * 4. Assemble the complete RFC 2822 message
+ * 5. Append to each local recipient's INBOX and sender's Sent mailbox
+ * 6. Forward to remote recipients via onRemoteSend
+ * 7. Schedule watch callbacks asynchronously via queueMicrotask
+ * 8. Fire onMessageSent callback (fire-and-forget)
+ *
+ * If onRemoteSend is not provided and there are remote recipients, send()
+ * throws. If onRemoteSend rejects, the error propagates — local delivery
+ * that already completed is not rolled back. This is a known limitation:
+ * partial delivery is possible when a message has both local and remote
+ * recipients and the remote leg fails.
+ */
+export async function executeSend(
+  senderAddress: string,
+  message: OutboundMessage,
+  entries: Map<string, AddressEntry>,
+  onRemoteSend?: RemoteSendHandler,
+  onMessageSent?: MessageSentHandler,
+): Promise<SendReceipt> {
+  const senderEntry = entries.get(senderAddress);
+  if (senderEntry === undefined) {
+    throw new Error(
+      `Sender "${senderAddress}" is not registered with this transport`,
+    );
+  }
+  const senderCrypto = senderEntry.crypto;
+
+  const recipients = Array.isArray(message.to) ? message.to : [message.to];
+  if (recipients.length === 0) {
+    throw new Error("OutboundMessage must have at least one recipient");
+  }
+
+  const ccAddressList =
+    message.cc !== undefined
+      ? Array.isArray(message.cc)
+        ? message.cc
+        : [message.cc]
+      : [];
+
+  const allAddressees = [...new Set([...recipients, ...ccAddressList])];
+  const remoteRecipients = allAddressees.filter((addr) => !entries.has(addr));
+
+  if (remoteRecipients.length > 0 && onRemoteSend === undefined) {
+    throw new Error(
+      `Recipient "${remoteRecipients[0]}" is not registered with this transport`,
+    );
+  }
+
+  const isConversation = CONVERSATION_TYPES.has(message.type);
+
+  if (isConversation && message.payload !== undefined) {
+    throw new Error(
+      "Conversation messages must not carry a structured payload",
+    );
+  }
+  if (!isConversation && message.content !== undefined) {
+    throw new Error("Structured messages must not carry a text content field");
+  }
+
+  const messageId = generateMessageId(senderAddress);
+  const now = new Date();
+
+  let content: ConversationContent | StructuredContent;
+  if (isConversation) {
+    content = {
+      kind: "conversation",
+      text: message.content ?? "",
+    };
+  } else {
+    const payload = message.payload ?? {};
+    const envelope = {
+      type: message.type,
+      version: "1",
+      body: payload,
+    };
+    const structured: StructuredContent = {
+      kind: "structured",
+      json: envelope,
+    };
+    if (message.summary !== undefined) structured.summary = message.summary;
+    content = structured;
+  }
+
+  const signedContentBytes = assembleSignedContent(content);
+  const signatureBytes = await createDetachedSignatureFromProvider(
+    signedContentBytes,
+    senderCrypto,
+  );
+
+  const ccAddresses = ccAddressList.length > 0 ? ccAddressList : undefined;
+
+  const refs = buildReferences(message.inReplyTo, undefined);
+
+  const mimeHeaders: MimeMessageHeaders = {
+    from: senderAddress,
+    to: recipients,
+    cc: ccAddresses,
+    date: now,
+    messageId,
+    subject: message.subject,
+    inReplyTo: message.inReplyTo,
+    references: refs,
+    mimeVersion: "1.0",
+    interchangeType: message.type,
+    interchangeCorrelationId: message.correlationId,
+    interchangeTenantId: message.tenantId,
+    interchangeAgentId: undefined,
+    interchangeSessionId: message.sessionId,
+    interchangeOfferingId: undefined,
+    interchangeSchemaVersion: undefined,
+    traceparent: undefined,
+    tracestate: undefined,
+  };
+
+  const rawBytes = assembleMessage(
+    mimeHeaders,
+    signedContentBytes,
+    signatureBytes,
+  );
+  const envelope: StoredEnvelope = {
+    messageId,
+    from: senderAddress,
+    to: recipients,
+    subject: message.subject ?? "",
+    date: now,
+    inReplyTo: message.inReplyTo,
+    references: refs ?? [],
+    interchangeType: message.type,
+    interchangeCorrelationId: message.correlationId,
+  };
+
+  // Deliver to each local recipient's INBOX.
+  const deliveredUids: { address: string; uid: number }[] = [];
+  for (const recipient of allAddressees) {
+    const entry = entries.get(recipient);
+    if (entry === undefined) continue;
+    const inbox = entry.mailboxes.get("INBOX");
+    if (inbox === undefined) {
+      throw new Error(
+        `Mailbox "INBOX" does not exist for recipient "${recipient}"`,
+      );
+    }
+    const uid = appendToMailbox(inbox, rawBytes, envelope, []);
+    deliveredUids.push({ address: recipient, uid });
+  }
+
+  // Append copy to sender's Sent mailbox.
+  const sentStore = senderEntry.mailboxes.get("Sent");
+  if (sentStore === undefined) {
+    throw new Error(
+      `Mailbox "Sent" does not exist for sender "${senderAddress}"`,
+    );
+  }
+  appendToMailbox(sentStore, rawBytes, envelope, ["\\Seen"]);
+
+  // Fire local recipient watch callbacks ASYNCHRONOUSLY (per MESSAGE.md
+  // requirement). queueMicrotask ensures callbacks never run synchronously
+  // on the sender's call stack, preserving real IMAP IDLE async delivery
+  // semantics. Scheduled before the remote send so local delivery
+  // notifications are not delayed by network latency.
+  const { headers: parsedHeaders } = parseHeaderSection(rawBytes);
+  const msgHeaders = buildMessageHeaders(parsedHeaders);
+
+  for (const { address, uid } of deliveredUids) {
+    const entry = entries.get(address);
+    if (entry === undefined) {
+      throw new Error(
+        `Entry for "${address}" disappeared between delivery and callback dispatch`,
+      );
+    }
+    const callbacks = entry.watchCallbacks.get("INBOX");
+    if (callbacks === undefined || callbacks.size === 0) continue;
+
+    const event: MailboxEvent = {
+      type: "exists",
+      uid,
+      headers: msgHeaders,
+    };
+
+    for (const cb of callbacks) {
+      queueMicrotask(() => cb(event));
+    }
+  }
+
+  // Forward to remote recipients via federation hook.
+  if (remoteRecipients.length > 0 && onRemoteSend !== undefined) {
+    await onRemoteSend(rawBytes, remoteRecipients);
+  }
+
+  if (onMessageSent !== undefined) {
+    const localOnly = remoteRecipients.length === 0;
+    onMessageSent({
+      senderAddress,
+      rawMessage: rawBytes,
+      messageId,
+      recipients: allAddressees,
+      to: recipients,
+      cc: ccAddressList,
+      localOnly,
+    }).catch((err: unknown) => {
+      queueMicrotask(() => {
+        throw err instanceof Error
+          ? err
+          : new Error(`MessageSentHandler failed: ${String(err)}`);
+      });
+    });
+  }
+
+  return {
+    messageId,
+    status: remoteRecipients.length > 0 ? "queued" : "delivered",
+  };
+}
+
+function buildReferences(
+  inReplyTo: string | undefined,
+  existingReferences: string[] | undefined,
+): string[] | undefined {
+  if (inReplyTo === undefined) return existingReferences;
+  const refs = existingReferences ?? [];
+  if (!refs.includes(inReplyTo)) {
+    return [...refs, inReplyTo];
+  }
+  return refs;
+}