mailfile 0.1.0

package/src/mapi/tags.js

@@ -0,0 +1,147 @@
+/** MAPI property tags, types and code pages — MS-OXPROPS / MS-OXMSG. */
+
+/**
+ * Property identifiers referenced by mailfile. This is deliberately a subset:
+ * use `message.props` to read anything not listed here.
+ * @readonly
+ */
+export const PropId = {
+  SUBJECT: 0x0037,
+  NORMALIZED_SUBJECT: 0x0E1D,
+  BODY: 0x1000,
+  RTF_COMPRESSED: 0x1009,
+  HTML: 0x1013,
+  MESSAGE_CLASS: 0x001A,
+  TRANSPORT_HEADERS: 0x007D,
+  CLIENT_SUBMIT_TIME: 0x0039,
+  DELIVERY_TIME: 0x0E06,
+  LAST_MODIFICATION_TIME: 0x3008,
+  CREATION_TIME: 0x3007,
+  INTERNET_MESSAGE_ID: 0x1035,
+  IN_REPLY_TO_ID: 0x1042,
+  INTERNET_REFERENCES: 0x1039,
+  DISPLAY_TO: 0x0E04,
+  DISPLAY_CC: 0x0E03,
+  DISPLAY_BCC: 0x0E02,
+  SENDER_NAME: 0x0C1A,
+  SENDER_EMAIL: 0x0C1F,
+  SENDER_ADDRTYPE: 0x0C1E,
+  SENDER_SMTP: 0x5D01,
+  SENT_REP_NAME: 0x0042,
+  SENT_REP_EMAIL: 0x0065,
+  SENT_REP_ADDRTYPE: 0x0064,
+  SENT_REP_SMTP: 0x5D02,
+  MESSAGE_FLAGS: 0x0E07,
+  HASATTACH: 0x0E1B,
+  STORE_SUPPORT_MASK: 0x340D,
+  INTERNET_CPID: 0x3FDE,
+  MESSAGE_CODEPAGE: 0x3FFD,
+  PRIORITY: 0x0026,
+  IMPORTANCE: 0x0017,
+  OBJECT_TYPE: 0x0FFE,
+  DISPLAY_TYPE: 0x3900,
+  ROWID: 0x3000,
+  RECIPIENT_TYPE: 0x0C15,
+  DISPLAY_NAME: 0x3001,
+  EMAIL_ADDRESS: 0x3003,
+  ADDRTYPE: 0x3002,
+  SMTP_ADDRESS: 0x39FE,
+  ATTACH_METHOD: 0x3705,
+  ATTACH_DATA_BIN: 0x3701,
+  ATTACH_LONG_FILENAME: 0x3707,
+  ATTACH_FILENAME: 0x3704,
+  ATTACH_EXTENSION: 0x3703,
+  ATTACH_MIME_TAG: 0x370E,
+  ATTACH_CONTENT_ID: 0x3712,
+  ATTACH_SIZE: 0x0E20,
+  ATTACH_NUM: 0x0E21,
+  ATTACH_FLAGS: 0x3714,
+  ATTACHMENT_HIDDEN: 0x7FFE,
+  RENDERING_POSITION: 0x370B
+};
+
+/** MAPI property types. @readonly */
+export const PropType = {
+  SHORT: 0x0002,
+  LONG: 0x0003,
+  FLOAT: 0x0004,
+  DOUBLE: 0x0005,
+  BOOLEAN: 0x000B,
+  I8: 0x0014,
+  STRING8: 0x001E,
+  UNICODE: 0x001F,
+  SYSTIME: 0x0040,
+  BINARY: 0x0102,
+  OBJECT: 0x000D
+};
+
+/** Recipient kinds (PR_RECIPIENT_TYPE). @readonly */
+export const RecipientType = { TO: 1, CC: 2, BCC: 3 };
+
+/** Attachment storage methods (PR_ATTACH_METHOD). @readonly */
+export const AttachMethod = { NONE: 0, BY_VALUE: 1, BY_REFERENCE: 2, EMBEDDED_MSG: 5 };
+
+/** Property stream header sizes, by the object the stream belongs to. @readonly */
+export const HeaderSize = {
+  TOP_LEVEL: 32,
+  EMBEDDED: 24,
+  RECIPIENT: 8,
+  ATTACHMENT: 8
+};
+
+/** CLSID written to the root entry of a .msg file. */
+export const MSG_CLSID = new Uint8Array([
+  0x0B, 0x0D, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46
+]);
+
+/** Windows code page number -> WHATWG encoding label. */
+export const CODEPAGES = {
+  20127: 'us-ascii', 28591: 'iso-8859-1', 28592: 'iso-8859-2', 28595: 'iso-8859-5',
+  28597: 'iso-8859-7', 28598: 'iso-8859-8', 28599: 'iso-8859-9', 28605: 'iso-8859-15',
+  65000: 'utf-7', 65001: 'utf-8', 1250: 'windows-1250', 1251: 'windows-1251',
+  1252: 'windows-1252', 1253: 'windows-1253', 1254: 'windows-1254', 1255: 'windows-1255',
+  1256: 'windows-1256', 1257: 'windows-1257', 1258: 'windows-1258',
+  932: 'shift_jis', 936: 'gbk', 949: 'euc-kr', 950: 'big5', 874: 'windows-874'
+};
+
+/** @param {number} n @returns {string} */
+export function hex4(n) {
+  return ('000' + n.toString(16).toUpperCase()).slice(-4);
+}
+
+/** @param {number} n @returns {string} */
+export function hex8(n) {
+  return ('0000000' + n.toString(16).toUpperCase()).slice(-8);
+}
+
+/**
+ * Stream name for a variable-length property, e.g. `__substg1.0_0037001F`.
+ * @param {number} id
+ * @param {number} type
+ * @returns {string}
+ */
+export function tagName(id, type) {
+  return '__substg1.0_' + hex4(id) + hex4(type);
+}
+
+/**
+ * FILETIME (100ns ticks since 1601-01-01) -> Date.
+ * @param {number} lo @param {number} hi @returns {Date|null}
+ */
+export function filetimeToDate(lo, hi) {
+  if (!lo && !hi) return null;
+  const ft = hi * 4294967296 + lo;
+  const ms = ft / 10000 - 11644473600000;
+  if (!isFinite(ms) || ms < -2208988800000 || ms > 4102444800000) return null;
+  return new Date(ms);
+}
+
+/**
+ * Date -> FILETIME halves.
+ * @param {Date} date @returns {{lo: number, hi: number}}
+ */
+export function dateToFiletime(date) {
+  const ft = Math.round((date.getTime() + 11644473600000) * 10000);
+  return { lo: ft % 4294967296, hi: Math.floor(ft / 4294967296) };
+}

package/src/message.js

@@ -0,0 +1,199 @@
+/** The format-neutral message model that sits between .msg and .eml. */
+import { buildEml } from './mime/build.js';
+import { parseEml } from './mime/parse.js';
+import {
+  Headers, decodeWords, encodeWord, formatAddress, formatDate,
+  parseAddressList, parseDate
+} from './mime/headers.js';
+import { readMsg } from './msg/read.js';
+import { writeMsg } from './msg/write.js';
+
+/**
+ * @typedef {object} Address
+ * @property {string} name
+ * @property {string} email
+ */
+
+/**
+ * @typedef {object} Attachment
+ * @property {string} filename
+ * @property {string} mime
+ * @property {Uint8Array} data
+ * @property {string} [cid] Content-ID, without angle brackets.
+ * @property {boolean} [inline] True when referenced from the HTML body by cid.
+ */
+
+// Content headers are rebuilt from the body structure, so any copies carried
+// over from the source would contradict what we emit.
+const CONTENT_HEADERS = new Set([
+  'mime-version', 'content-type', 'content-transfer-encoding',
+  'content-disposition', 'content-id', 'content-description',
+  'content-language', 'content-location'
+]);
+
+const IMPORTANCE = { low: 0, normal: 1, high: 2 };
+
+/**
+ * A single email message, independent of its on-disk format.
+ *
+ * Fields are plain and mutable: read one in, change what you need, write the
+ * other out.
+ */
+export class Message {
+  /** @param {Partial<Message>} [data] */
+  constructor(data = {}) {
+    /** @type {string} */
+    this.subject = data.subject || '';
+    /** @type {Address} */
+    this.from = data.from || { name: '', email: '' };
+    /** @type {Address[]} */
+    this.to = data.to || [];
+    /** @type {Address[]} */
+    this.cc = data.cc || [];
+    /** @type {Address[]} */
+    this.bcc = data.bcc || [];
+    /** @type {Date|null} */
+    this.date = data.date || null;
+    /** @type {string} */
+    this.messageId = data.messageId || '';
+    /** @type {string} */
+    this.inReplyTo = data.inReplyTo || '';
+    /** @type {string} */
+    this.references = data.references || '';
+    /** @type {number|null} 0 low, 1 normal, 2 high. */
+    this.importance = data.importance == null ? null : data.importance;
+    /** @type {string} MAPI message class, e.g. `IPM.Note`. */
+    this.messageClass = data.messageClass || 'IPM.Note';
+    /** @type {string} Plain-text body. */
+    this.text = data.text || '';
+    /** @type {string} HTML body. */
+    this.html = data.html || '';
+    /** @type {Attachment[]} */
+    this.attachments = data.attachments || [];
+    /** @type {Headers} Original internet headers, when the source had them. */
+    this.headers = data.headers instanceof Headers
+      ? data.headers
+      : new Headers(data.headers || []);
+    /**
+     * Raw MAPI property access — present only for messages read from `.msg`.
+     * Use it to reach properties this model does not surface (appointments,
+     * contacts, custom properties).
+     * @type {import('./mapi/bag.js').PropertyBag|null}
+     */
+    this.props = data.props || null;
+  }
+
+  /**
+   * Parse an Outlook `.msg` file.
+   * @param {Uint8Array} bytes
+   * @param {{lazy?: boolean}} [opts] `lazy` defers attachment byte extraction
+   *   until `.data` is read — useful when you only want headers.
+   * @returns {Message}
+   */
+  static fromMsg(bytes, opts = {}) {
+    const data = readMsg(bytes, opts);
+    // Embedded messages are represented as nested .eml attachments.
+    data.attachments = data.attachments.map((a) => {
+      if (!a.embedded) return a;
+      const { embedded, ...rest } = a;
+      return { ...rest, data: new Message(embedded).toEml() };
+    });
+    return new Message(data);
+  }
+
+  /**
+   * Parse an RFC 5322 `.eml` file.
+   * @param {Uint8Array} bytes
+   * @returns {Message}
+   */
+  static fromEml(bytes) {
+    const parsed = parseEml(bytes);
+    const h = parsed.headers;
+    return new Message({
+      subject: decodeWords(h.get('subject') || ''),
+      from: parseAddressList(h.get('from') || '')[0] || { name: '', email: '' },
+      to: parseAddressList(h.get('to') || ''),
+      cc: parseAddressList(h.get('cc') || ''),
+      bcc: parseAddressList(h.get('bcc') || ''),
+      date: parseDate(h.get('date')),
+      messageId: h.get('message-id') || '',
+      inReplyTo: h.get('in-reply-to') || '',
+      references: h.get('references') || '',
+      importance: IMPORTANCE[(h.get('importance') || '').toLowerCase()] ?? null,
+      text: parsed.text,
+      html: parsed.html,
+      attachments: parsed.attachments,
+      headers: h
+    });
+  }
+
+  /**
+   * Serialise to an RFC 5322 `.eml` document.
+   *
+   * Headers carried in from the source are preserved verbatim — minus the
+   * content headers, which are regenerated to match the body actually written.
+   * @returns {Uint8Array}
+   */
+  toEml() {
+    /** @type {Array<[string, string]>} */
+    const out = [];
+    const seen = new Set();
+    for (const [k, v] of this.headers) {
+      if (CONTENT_HEADERS.has(k.toLowerCase())) continue;
+      out.push([k, v]);
+      seen.add(k.toLowerCase());
+    }
+    const put = (name, value) => {
+      if (!value || seen.has(name.toLowerCase())) return;
+      out.push([name, value]);
+      seen.add(name.toLowerCase());
+    };
+    const list = (addrs) =>
+      addrs.map((a) => formatAddress(a.name, a.email)).filter(Boolean).join(', ');
+
+    if (this.date) put('Date', formatDate(this.date));
+    if (this.from.email || this.from.name) {
+      put('From', formatAddress(this.from.name, this.from.email));
+    }
+    if (this.to.length) put('To', list(this.to));
+    if (this.cc.length) put('Cc', list(this.cc));
+    if (this.bcc.length) put('Bcc', list(this.bcc));
+    if (!seen.has('subject')) put('Subject', encodeWord(this.subject || '') || ' ');
+    put('Message-ID', this.messageId);
+    put('In-Reply-To', this.inReplyTo);
+    put('References', this.references);
+
+    return buildEml({
+      headers: out,
+      text: this.text,
+      html: this.html,
+      attachments: this.attachments
+    });
+  }
+
+  /**
+   * Serialise to an Outlook `.msg` file.
+   * @returns {Uint8Array}
+   */
+  toMsg() {
+    return writeMsg({
+      messageClass: this.messageClass,
+      subject: this.subject,
+      from: this.from,
+      to: this.to,
+      cc: this.cc,
+      bcc: this.bcc,
+      date: this.date,
+      messageId: this.messageId,
+      inReplyTo: this.inReplyTo,
+      references: this.references,
+      importance: this.importance,
+      text: this.text,
+      html: this.html,
+      attachments: this.attachments,
+      // Keeping the original header block lets a later .msg -> .eml
+      // conversion restore the full Received: trail.
+      headersRaw: this.headers.entries.length ? this.headers.raw : ''
+    });
+  }
+}

package/src/mime/build.js

@@ -0,0 +1,100 @@
+/** MIME document generation. */
+import { bytesToBase64, encodeQP, utf8Encode, wrap } from './encodings.js';
+import { encodeParamValue, foldHeader } from './headers.js';
+
+function randomBoundary(tag) {
+  let s = '';
+  for (let i = 0; i < 24; i++) s += '0123456789abcdef'[Math.floor(Math.random() * 16)];
+  return '----=_' + tag + '_' + s;
+}
+
+function textPart(mime, content) {
+  return [
+    'Content-Type: ' + mime + '; charset="utf-8"',
+    'Content-Transfer-Encoding: quoted-printable',
+    '',
+    encodeQP(utf8Encode(content))
+  ].join('\r\n');
+}
+
+function attachmentPart(att) {
+  const mime = att.mime || 'application/octet-stream';
+  const lines = [
+    'Content-Type: ' + mime + '; ' + encodeParamValue('name', att.filename),
+    'Content-Transfer-Encoding: base64'
+  ];
+  if (att.cid) lines.push('Content-ID: <' + att.cid + '>');
+  lines.push('Content-Disposition: ' + (att.inline ? 'inline' : 'attachment') + '; ' +
+    encodeParamValue('filename', att.filename));
+  lines.push('');
+  lines.push(wrap(bytesToBase64(att.data), 76));
+  return lines.join('\r\n');
+}
+
+function multipart(subtype, parts, extraParams) {
+  const b = randomBoundary(subtype.toUpperCase());
+  const head = 'Content-Type: multipart/' + subtype + '; boundary="' + b + '"' +
+    (extraParams || '');
+  let body = '';
+  for (const p of parts) body += '--' + b + '\r\n' + p + '\r\n';
+  body += '--' + b + '--\r\n';
+  return { head, body };
+}
+
+/**
+ * Build an `.eml` document.
+ *
+ * Structure is chosen from what is present: `multipart/alternative` for a
+ * text+html pair, wrapped in `multipart/related` when there are inline
+ * (cid-referenced) parts, wrapped again in `multipart/mixed` for ordinary
+ * attachments.
+ *
+ * @param {object} msg
+ * @param {Array<[string,string]>} [msg.headers] Emitted before the MIME headers.
+ * @param {string} [msg.text]
+ * @param {string} [msg.html]
+ * @param {Array<{filename: string, mime: string, data: Uint8Array, cid?: string, inline?: boolean}>} [msg.attachments]
+ * @returns {Uint8Array}
+ */
+export function buildEml(msg) {
+  const inline = [];
+  const regular = [];
+  for (const a of msg.attachments || []) {
+    if (a.inline && a.cid) inline.push(a);
+    else regular.push(a);
+  }
+
+  const bodyParts = [];
+  if (msg.text) bodyParts.push(textPart('text/plain', msg.text));
+  if (msg.html) bodyParts.push(textPart('text/html', msg.html));
+  if (!bodyParts.length) bodyParts.push(textPart('text/plain', ''));
+
+  let current;
+  if (bodyParts.length > 1) {
+    const alt = multipart('alternative', bodyParts);
+    current = alt.head + '\r\n\r\n' + alt.body;
+  } else {
+    current = bodyParts[0];
+  }
+
+  if (inline.length) {
+    const rel = multipart('related', [current].concat(inline.map(attachmentPart)),
+      '; type="text/html"');
+    current = rel.head + '\r\n\r\n' + rel.body;
+  }
+  if (regular.length) {
+    const mixed = multipart('mixed', [current].concat(regular.map(attachmentPart)));
+    current = mixed.head + '\r\n\r\n' + mixed.body;
+  }
+
+  const idx = current.indexOf('\r\n\r\n');
+  const partHeaders = current.slice(0, idx);
+  const partBody = current.slice(idx + 4);
+
+  const headerLines = [];
+  for (const [k, v] of msg.headers || []) headerLines.push(foldHeader(k, v));
+  headerLines.push('MIME-Version: 1.0');
+  for (const l of partHeaders.split('\r\n')) if (l) headerLines.push(l);
+
+  return utf8Encode(headerLines.join('\r\n') + '\r\n\r\n' + partBody);
+}

package/src/mime/encodings.js

@@ -0,0 +1,188 @@
+/** Base64, quoted-printable and charset helpers. */
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function bytesToBase64(bytes) {
+  let out = '';
+  let i;
+  const len = bytes.length;
+  for (i = 0; i + 2 < len; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63] + B64[(n >> 6) & 63] + B64[n & 63];
+  }
+  const rem = len - i;
+  if (rem === 1) {
+    const a = bytes[i] << 16;
+    out += B64[(a >> 18) & 63] + B64[(a >> 12) & 63] + '==';
+  } else if (rem === 2) {
+    const b = (bytes[i] << 16) | (bytes[i + 1] << 8);
+    out += B64[(b >> 18) & 63] + B64[(b >> 12) & 63] + B64[(b >> 6) & 63] + '=';
+  }
+  return out;
+}
+
+/**
+ * Tolerant base64 decoder: ignores whitespace and any non-alphabet bytes.
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+export function base64ToBytes(str) {
+  let clean = String(str).replace(/[^A-Za-z0-9+/=]/g, '');
+  const pad = clean.indexOf('=');
+  if (pad >= 0) clean = clean.slice(0, pad);
+  const len = clean.length;
+  const out = new Uint8Array(Math.floor((len * 3) / 4));
+  let p = 0;
+  let buf = 0;
+  let bits = 0;
+  for (let i = 0; i < len; i++) {
+    const v = B64.indexOf(clean[i]);
+    if (v < 0) continue;
+    buf = (buf << 6) | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[p++] = (buf >> bits) & 0xFF;
+    }
+  }
+  return out.subarray(0, p);
+}
+
+/**
+ * @param {string} str
+ * @param {number} width
+ * @returns {string}
+ */
+export function wrap(str, width) {
+  const out = [];
+  for (let i = 0; i < str.length; i += width) out.push(str.slice(i, i + width));
+  return out.join('\r\n');
+}
+
+const encoder = new TextEncoder();
+
+/**
+ * @param {string} s
+ * @returns {Uint8Array}
+ */
+export function utf8Encode(s) {
+  return encoder.encode(s);
+}
+
+/**
+ * Decode bytes using a named charset, falling back to windows-1252 for
+ * labels the runtime does not know. Real-world mail mislabels constantly,
+ * so this never throws.
+ * @param {Uint8Array} bytes
+ * @param {string} [charset]
+ * @returns {string}
+ */
+export function decodeBytes(bytes, charset) {
+  let cs = (charset || 'utf-8').toLowerCase().replace(/^["']|["']$/g, '');
+  if (cs === 'us-ascii' || cs === 'ascii' || cs === 'ansi_x3.4-1968') cs = 'utf-8';
+  if (cs === 'cp1252' || cs === 'win-1252') cs = 'windows-1252';
+  if (cs === 'utf8') cs = 'utf-8';
+  try {
+    return new TextDecoder(cs, { fatal: false }).decode(bytes);
+  } catch {
+    try {
+      return new TextDecoder('windows-1252').decode(bytes);
+    } catch {
+      let s = '';
+      for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+      return s;
+    }
+  }
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function utf16Decode(bytes) {
+  try {
+    return new TextDecoder('utf-16le').decode(bytes);
+  } catch {
+    let s = '';
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+      s += String.fromCharCode(bytes[i] | (bytes[i + 1] << 8));
+    }
+    return s;
+  }
+}
+
+/**
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+export function utf16Encode(str) {
+  const out = new Uint8Array(str.length * 2);
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    out[i * 2] = c & 0xFF;
+    out[i * 2 + 1] = c >> 8;
+  }
+  return out;
+}
+
+/**
+ * @param {string} str
+ * @param {boolean} [isHeaderWord] Treat `_` as space (RFC 2047 Q encoding).
+ * @returns {Uint8Array}
+ */
+export function decodeQP(str, isHeaderWord) {
+  const out = [];
+  let i = 0;
+  while (i < str.length) {
+    const ch = str[i];
+    if (ch === '=') {
+      if (str[i + 1] === '\r' && str[i + 2] === '\n') { i += 3; continue; }
+      if (str[i + 1] === '\n') { i += 2; continue; }
+      const hex = str.substr(i + 1, 2);
+      if (/^[0-9A-Fa-f]{2}$/.test(hex)) { out.push(parseInt(hex, 16)); i += 3; continue; }
+      out.push(61);
+      i++;
+    } else if (isHeaderWord && ch === '_') {
+      out.push(32);
+      i++;
+    } else {
+      out.push(str.charCodeAt(i) & 0xFF);
+      i++;
+    }
+  }
+  return new Uint8Array(out);
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function encodeQP(bytes) {
+  let out = '';
+  let lineLen = 0;
+  function push(tok) {
+    if (lineLen + tok.length > 75) { out += '=\r\n'; lineLen = 0; }
+    out += tok;
+    lineLen += tok.length;
+  }
+  const hex = (b) => '=' + ('0' + b.toString(16).toUpperCase()).slice(-2);
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if (b === 13 && bytes[i + 1] === 10) { out += '\r\n'; lineLen = 0; i++; continue; }
+    if (b === 10) { out += '\r\n'; lineLen = 0; continue; }
+    if (b === 32 || b === 9) {
+      const next = bytes[i + 1];
+      // Whitespace at end of line must be encoded or it will be stripped.
+      if (next === 13 || next === 10 || next === undefined) push(hex(b));
+      else push(String.fromCharCode(b));
+      continue;
+    }
+    if (b === 61 || b < 32 || b > 126) push(hex(b));
+    else push(String.fromCharCode(b));
+  }
+  return out;
+}