@intx/mail-memory 0.1.2

package/README.md

@@ -0,0 +1,37 @@
+# @intx/mail-memory
+
+In-memory `MessageTransport` for single-process and test
+environments. A single transport instance hosts every address in
+the process; each registered address gets its own per-recipient
+transport handle that signs outbound mail with the provided
+`CryptoProvider` and delivers inbound mail straight to the
+recipient's INBOX.
+
+Consumed by examples, tests, and the in-process `@intx/agent`
+runtime. The on-the-wire format matches `@intx/mime` so a fixture
+captured here can be replayed against a real transport without
+modification.
+
+```ts
+import { createInMemoryTransport } from "@intx/mail-memory";
+import { createNodeCrypto, generateKeyPair } from "@intx/crypto-node";
+
+const transport = createInMemoryTransport();
+const alpha = createNodeCrypto(await generateKeyPair());
+const beta = createNodeCrypto(await generateKeyPair());
+
+transport.register("alpha@local.interchange", alpha);
+transport.register("beta@local.interchange", beta);
+
+const alphaMail = transport.getTransportFor("alpha@local.interchange");
+await alphaMail.send({
+  to: "beta@local.interchange",
+  type: "conversation.message",
+  content: "hello",
+});
+```
+
+Install a `RemoteSendHandler` via `transport.setRemoteSendHandler`
+to forward outbound mail for addresses the transport does not host
+locally, and add one or more `MessageSentHandler`s via
+`transport.addMessageSentHandler` for post-send observability.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@intx/mail-memory",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/crypto-node": "0.0.0",
+    "@intx/log": "0.0.0",
+    "@intx/mime": "0.0.0",
+    "@intx/types": "0.0.0"
+  }
+}

package/src/fetch.ts

@@ -0,0 +1,215 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- MIME multipart parsing with bounds checks */
+import { type } from "arktype";
+import type {
+  MessageHeaders,
+  BodyStructure,
+  MessagePart,
+  InboundMessage,
+  SignatureStatus,
+  CryptoProvider,
+  MessageRef,
+} from "@intx/types/runtime";
+import { InterchangeType } from "@intx/types/runtime";
+import type { MailboxStore } from "./mailbox";
+import { requireMessage } from "./mailbox";
+import {
+  parseHeaderSection,
+  parseMimePart,
+  extractBoundary,
+  parseMultipart,
+  extractPartByPath,
+} from "@intx/mime";
+import { buildMessageHeaders } from "./headers";
+import { verifyDetachedSignature } from "@intx/crypto-node";
+
+const MessagePayload = type({
+  type: InterchangeType,
+  version: "string",
+  body: "Record<string, unknown>",
+});
+
+/**
+ * Parse raw RFC 2822 headers from a stored message.
+ */
+export function fetchHeaders(
+  ref: MessageRef,
+  store: MailboxStore,
+): MessageHeaders {
+  const msg = requireMessage(store, ref.uid, ref.mailbox);
+  const { headers } = parseHeaderSection(msg.raw);
+  return buildMessageHeaders(headers);
+}
+
+/**
+ * Compute the MIME tree structure (BODYSTRUCTURE) without transferring content.
+ */
+export function fetchStructure(
+  ref: MessageRef,
+  store: MailboxStore,
+): BodyStructure {
+  const msg = requireMessage(store, ref.uid, ref.mailbox);
+  const { headers, bodyOffset } = parseHeaderSection(msg.raw);
+  const body = msg.raw.slice(bodyOffset);
+  const contentType = headers.get("content-type") ?? "application/octet-stream";
+  return buildStructure(body, contentType);
+}
+
+/**
+ * Fetch a single MIME part by dot-separated path.
+ */
+export function fetchPart(
+  ref: MessageRef,
+  partPath: string,
+  store: MailboxStore,
+): MessagePart {
+  const msg = requireMessage(store, ref.uid, ref.mailbox);
+  const partBytes = extractPartByPath(msg.raw, partPath);
+  const part = parseMimePart(partBytes);
+
+  const enc = part.headers.get("content-transfer-encoding") ?? "7bit";
+  let content: Uint8Array;
+
+  if (enc.toLowerCase() === "base64") {
+    const b64 = new TextDecoder().decode(part.body).replace(/\s/g, "");
+    content = new Uint8Array(Buffer.from(b64, "base64"));
+  } else {
+    content = part.body;
+  }
+
+  const result: MessagePart = {
+    contentType: part.contentType,
+    content,
+  };
+  if (enc !== "7bit") result.encoding = enc;
+  return result;
+}
+
+/**
+ * Fetch a complete message, verify its PGP/MIME signature, and return
+ * a fully parsed InboundMessage.
+ */
+export async function fetchFull(
+  ref: MessageRef,
+  store: MailboxStore,
+  getCrypto: (fromAddress: string) => CryptoProvider | undefined,
+): Promise<InboundMessage> {
+  const msg = requireMessage(store, ref.uid, ref.mailbox);
+  const { headers } = parseHeaderSection(msg.raw);
+  const parsedHeaders = buildMessageHeaders(headers);
+
+  const rawType = parsedHeaders.interchangeType;
+  const isConversation =
+    rawType === "conversation.message" ||
+    rawType === "conversation.join" ||
+    rawType === "conversation.leave" ||
+    rawType === undefined;
+
+  const signatureStatus = await verifyMessageSignature(
+    msg.raw,
+    parsedHeaders.from,
+    getCrypto,
+  );
+
+  const result: InboundMessage = {
+    ref,
+    headers: parsedHeaders,
+    flags: Array.from(msg.flags),
+    signatureStatus,
+  };
+
+  try {
+    if (isConversation) {
+      const part1Bytes = extractPartByPath(msg.raw, "1");
+      const part1 = parseMimePart(part1Bytes);
+      result.content = new TextDecoder("utf-8", { fatal: false }).decode(
+        part1.body,
+      );
+    } else {
+      const part11Bytes = extractPartByPath(msg.raw, "1.1");
+      const part11 = parseMimePart(part11Bytes);
+      const jsonText = new TextDecoder("utf-8", { fatal: false }).decode(
+        part11.body,
+      );
+      const validated = MessagePayload(JSON.parse(jsonText));
+      if (validated instanceof type.errors) {
+        throw new Error(`invalid message payload: ${validated.summary}`);
+      }
+      result.payload = validated;
+    }
+  } catch {
+    // If we can't parse the content, return what we have with the signature status.
+  }
+
+  return result;
+}
+
+async function verifyMessageSignature(
+  raw: Uint8Array,
+  fromAddress: string,
+  getCrypto: (fromAddress: string) => CryptoProvider | undefined,
+): Promise<SignatureStatus> {
+  const senderCrypto = getCrypto(fromAddress);
+  if (senderCrypto === undefined) {
+    return "unknown";
+  }
+
+  try {
+    const { headers, bodyOffset } = parseHeaderSection(raw);
+    const body = raw.slice(bodyOffset);
+    const contentType = headers.get("content-type") ?? "";
+
+    if (!contentType.toLowerCase().includes("multipart/signed")) {
+      return "missing";
+    }
+
+    const boundary = extractBoundary(contentType);
+    if (boundary === undefined) return "missing";
+
+    const parts = parseMultipart(body, boundary);
+    if (parts.length < 2) return "missing";
+
+    const signedContentBytes = parts[0]!;
+    const sigPartBytes = parts[1]!;
+    const sigPart = parseMimePart(sigPartBytes);
+
+    if (
+      !sigPart.contentType.toLowerCase().includes("application/pgp-signature")
+    ) {
+      return "missing";
+    }
+
+    const publicKey = senderCrypto.getPublicKey();
+    const valid = await verifyDetachedSignature(
+      signedContentBytes,
+      sigPart.body,
+      publicKey,
+    );
+
+    return valid ? "valid" : "invalid";
+  } catch {
+    return "invalid";
+  }
+}
+
+function buildStructure(body: Uint8Array, contentType: string): BodyStructure {
+  const ct = contentType.toLowerCase();
+  if (!ct.startsWith("multipart/")) {
+    return { contentType, size: body.length };
+  }
+
+  const boundary = extractBoundary(contentType);
+  if (boundary === undefined) {
+    return { contentType, size: body.length };
+  }
+
+  const parts = parseMultipart(body, boundary);
+  const subStructures: BodyStructure[] = parts.map((partBytes) => {
+    const { headers, bodyOffset } = parseHeaderSection(partBytes);
+    const partBody = partBytes.slice(bodyOffset);
+    const partContentType =
+      headers.get("content-type") ?? "application/octet-stream";
+    return buildStructure(partBody, partContentType);
+  });
+
+  return { contentType, parts: subStructures };
+}

package/src/headers.ts

@@ -0,0 +1,87 @@
+import { type } from "arktype";
+import type { MessageHeaders } from "@intx/types/runtime";
+import { InterchangeType } from "@intx/types/runtime";
+
+function isInterchangeType(s: string): s is InterchangeType {
+  return !(InterchangeType(s) instanceof type.errors);
+}
+
+/**
+ * Build a MessageHeaders object from a parsed header map.
+ *
+ * Uses exactOptionalPropertyTypes-safe construction: optional fields are
+ * only included in the returned object when they carry actual values.
+ */
+export function buildMessageHeaders(
+  headers: Map<string, string>,
+): MessageHeaders {
+  const from = headers.get("from") ?? "";
+  const toRaw = headers.get("to") ?? "";
+  const to = toRaw
+    ? toRaw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  const date = headers.get("date") ?? "";
+  const messageId = headers.get("message-id") ?? "";
+
+  const result: MessageHeaders = { from, to, date, messageId };
+
+  const ccRaw = headers.get("cc");
+  if (ccRaw !== undefined) {
+    const cc = ccRaw
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (cc.length > 0) result.cc = cc;
+  }
+
+  const refsRaw = headers.get("references");
+  if (refsRaw !== undefined) {
+    const refs = refsRaw.split(/\s+/).filter(Boolean);
+    if (refs.length > 0) result.references = refs;
+  }
+
+  const inReplyTo = headers.get("in-reply-to");
+  if (inReplyTo !== undefined) result.inReplyTo = inReplyTo;
+
+  const subject = headers.get("subject");
+  if (subject !== undefined) result.subject = subject;
+
+  const listId = headers.get("list-id");
+  if (listId !== undefined) result.listId = listId;
+
+  const rawType = headers.get("interchange-type");
+  if (rawType !== undefined && isInterchangeType(rawType)) {
+    result.interchangeType = rawType;
+  }
+
+  const corrId = headers.get("interchange-correlation-id");
+  if (corrId !== undefined) result.interchangeCorrelationId = corrId;
+
+  const tenantId = headers.get("interchange-tenant-id");
+  if (tenantId !== undefined) result.interchangeTenantId = tenantId;
+
+  const agentId = headers.get("interchange-agent-id");
+  if (agentId !== undefined) result.interchangeAgentId = agentId;
+
+  const sessionId = headers.get("interchange-session-id");
+  if (sessionId !== undefined) result.interchangeSessionId = sessionId;
+
+  const offeringId = headers.get("interchange-offering-id");
+  if (offeringId !== undefined) result.interchangeOfferingId = offeringId;
+
+  const schemaVersion = headers.get("interchange-schema-version");
+  if (schemaVersion !== undefined)
+    result.interchangeSchemaVersion = schemaVersion;
+
+  const traceparent = headers.get("traceparent");
+  if (traceparent !== undefined) result.traceparent = traceparent;
+
+  const tracestate = headers.get("tracestate");
+  if (tracestate !== undefined) result.tracestate = tracestate;
+
+  return result;
+}