@upyo/jmap 0.6.0-dev.318 → 0.6.0-dev.319

package/dist/index.cjs

@@ -22,6 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __upyo_core = __toESM(require("@upyo/core"));
+const __upyo_core_message_id = __toESM(require("@upyo/core/message-id"));
 
 //#region src/errors.ts
 /**
@@ -300,17 +301,44 @@ function getPriorityHeaders(priority) {
 	}
 }
 /**
-* Extracts custom headers from message headers.
+* Header field names that must not be written as a raw header property.
+*
+* RFC 8621 §4.6 forbids two properties representing the same header field, and
+* the `Email` here already carries a structured property for each of these.
+* `Bcc` matters most: it travels in the submission envelope, so writing it into
+* the message would disclose recipients meant to stay hidden.  `Content-*`
+* belongs on an `EmailBodyPart` rather than on the `Email`.
+*/
+const structuredHeaders = new Set([
+	"bcc",
+	"cc",
+	"from",
+	"mime-version",
+	"reply-to",
+	"subject",
+	"to"
+]);
+/**
+* Extracts the custom headers of a message, dropping those the `Email` object
+* expresses through a structured property of its own.
+*
 * @param message The message to extract headers from.
 * @returns Array of JMAP headers.
+* @throws {TypeError} If a header value contains a carriage return or line
+* feed, which would forge further header fields.
 * @since 0.4.0
 */
 function extractCustomHeaders(message) {
 	const headers = [];
-	for (const [name, value] of message.headers.entries()) headers.push({
-		name,
-		value
-	});
+	for (const [name, value] of message.headers.entries()) {
+		const lowered = name.toLowerCase();
+		if (structuredHeaders.has(lowered) || lowered.startsWith("content-")) continue;
+		if (/[\r\n]/.test(value)) throw new TypeError(`Header field ${name} must not contain a carriage return or line feed.`);
+		headers.push({
+			name,
+			value
+		});
+	}
 	return headers;
 }
 /**
@@ -418,13 +446,21 @@ function buildAttachmentParts(attachments, uploadedBlobs) {
 * @param draftMailboxId The mailbox ID to store the draft in.
 * @param uploadedBlobs Map of contentId to blobId for attachments.
 * @returns The JMAP Email/set create object.
+* @throws {TypeError} If the message carries an invalid message identifier or
+* date, or a header value containing a carriage return or line feed.
+* @throws {RangeError} If the year of the date is outside what an RFC 3339
+* date-time can express.
 * @since 0.4.0
 */
 function convertMessage(message, draftMailboxId, uploadedBlobs) {
 	const { bodyStructure, bodyValues } = buildBodyStructure(message, uploadedBlobs);
-	const headers = [];
-	if (message.priority !== "normal") headers.push(...getPriorityHeaders(message.priority));
-	headers.push(...extractCustomHeaders(message));
+	const identity = resolveIdentity(message);
+	const headerProperties = {};
+	for (const { name, value } of getPriorityHeaders(message.priority)) headerProperties[`header:${name}`] = value;
+	for (const { name, value } of extractCustomHeaders(message)) {
+		if (identity.owned.has(name.toLowerCase())) continue;
+		headerProperties[`header:${name}`] = value;
+	}
 	const email = {
 		mailboxIds: { [draftMailboxId]: true },
 		from: [formatAddress(message.sender)],
@@ -435,10 +471,89 @@ function convertMessage(message, draftMailboxId, uploadedBlobs) {
 		...message.ccRecipients.length > 0 && { cc: message.ccRecipients.map(formatAddress) },
 		...message.bccRecipients.length > 0 && { bcc: message.bccRecipients.map(formatAddress) },
 		...message.replyRecipients.length > 0 && { replyTo: message.replyRecipients.map(formatAddress) },
-		...headers.length > 0 && { headers }
+		...identity.properties,
+		...headerProperties
 	};
 	return email;
 }
+/**
+* Works out the identity and threading properties of an `Email` from the typed
+* fields of a message.
+*
+* A field the message leaves unset is not owned, so a header supplied through
+* {@link Message.headers} still reaches the server, and the server falls back
+* to generating an identifier and a date of its own.  A threading field set to
+* an empty list is owned but writes no property, which suppresses such a
+* header.
+*
+* @param message The message being converted.
+* @returns The properties to set, and the field names the message owns.
+* @throws {TypeError} If a message identifier is invalid, or the date is not a
+* valid one.
+* @throws {RangeError} If the year of the date is outside what an RFC 3339
+* date-time can express.
+*/
+function resolveIdentity(message) {
+	const owned = /* @__PURE__ */ new Set();
+	const properties = {};
+	if (message.priority !== "normal") {
+		owned.add("x-priority");
+		owned.add("importance");
+	}
+	if (message.messageId != null) {
+		owned.add("message-id");
+		properties.messageId = [checkMessageId(message.messageId)];
+	}
+	if (message.date != null) {
+		owned.add("date");
+		properties.sentAt = formatSentAt(message.date);
+	}
+	if (message.inReplyTo != null) {
+		owned.add("in-reply-to");
+		if (message.inReplyTo.length > 0) properties.inReplyTo = message.inReplyTo.map(checkMessageId);
+	}
+	if (message.references != null) {
+		owned.add("references");
+		if (message.references.length > 0) properties.references = message.references.map(checkMessageId);
+	}
+	return {
+		properties,
+		owned
+	};
+}
+/**
+* Checks a message identifier a message carries.
+*
+* `createMessage()` validates these, but `Message` is a structural type that a
+* caller can build without it.
+*
+* @param id The identifier to check.
+* @returns The identifier, unchanged.
+* @throws {TypeError} If the value is not a valid message identifier.
+*/
+function checkMessageId(id) {
+	const parsed = (0, __upyo_core_message_id.parseMessageId)(id);
+	if (parsed == null) throw new TypeError(`Invalid message ID: ${JSON.stringify(id)}`);
+	return parsed;
+}
+/**
+* Formats a date as the RFC 3339 date-time JMAP calls a `Date`.
+*
+* RFC 8620 §1.4 omits a fractional-seconds part that is zero, which
+* `Date.toISOString()` always writes.
+*
+* @param date The date to format.
+* @returns The formatted date.
+* @throws {TypeError} If the date is not a valid one.
+* @throws {RangeError} If its year cannot be written as four digits.
+*/
+function formatSentAt(date) {
+	const time = date instanceof Date ? date.getTime() : NaN;
+	if (Number.isNaN(time)) throw new TypeError(`Invalid date: ${JSON.stringify(date)}`);
+	const year = date.getUTCFullYear();
+	if (year < 1 || year > 9999) throw new RangeError(`Year out of range for an RFC 3339 date: ${year}`);
+	return date.toISOString().replace(".000Z", "Z");
+}
 
 //#endregion
 //#region src/session.ts

package/dist/index.js

@@ -1,4 +1,5 @@
 import { combineSignals, createFailedReceipt, parseRetryAfter, readAttachmentContent } from "@upyo/core";
+import { parseMessageId } from "@upyo/core/message-id";
 
 //#region src/errors.ts
 /**
@@ -277,17 +278,44 @@ function getPriorityHeaders(priority) {
 	}
 }
 /**
-* Extracts custom headers from message headers.
+* Header field names that must not be written as a raw header property.
+*
+* RFC 8621 §4.6 forbids two properties representing the same header field, and
+* the `Email` here already carries a structured property for each of these.
+* `Bcc` matters most: it travels in the submission envelope, so writing it into
+* the message would disclose recipients meant to stay hidden.  `Content-*`
+* belongs on an `EmailBodyPart` rather than on the `Email`.
+*/
+const structuredHeaders = new Set([
+	"bcc",
+	"cc",
+	"from",
+	"mime-version",
+	"reply-to",
+	"subject",
+	"to"
+]);
+/**
+* Extracts the custom headers of a message, dropping those the `Email` object
+* expresses through a structured property of its own.
+*
 * @param message The message to extract headers from.
 * @returns Array of JMAP headers.
+* @throws {TypeError} If a header value contains a carriage return or line
+* feed, which would forge further header fields.
 * @since 0.4.0
 */
 function extractCustomHeaders(message) {
 	const headers = [];
-	for (const [name, value] of message.headers.entries()) headers.push({
-		name,
-		value
-	});
+	for (const [name, value] of message.headers.entries()) {
+		const lowered = name.toLowerCase();
+		if (structuredHeaders.has(lowered) || lowered.startsWith("content-")) continue;
+		if (/[\r\n]/.test(value)) throw new TypeError(`Header field ${name} must not contain a carriage return or line feed.`);
+		headers.push({
+			name,
+			value
+		});
+	}
 	return headers;
 }
 /**
@@ -395,13 +423,21 @@ function buildAttachmentParts(attachments, uploadedBlobs) {
 * @param draftMailboxId The mailbox ID to store the draft in.
 * @param uploadedBlobs Map of contentId to blobId for attachments.
 * @returns The JMAP Email/set create object.
+* @throws {TypeError} If the message carries an invalid message identifier or
+* date, or a header value containing a carriage return or line feed.
+* @throws {RangeError} If the year of the date is outside what an RFC 3339
+* date-time can express.
 * @since 0.4.0
 */
 function convertMessage(message, draftMailboxId, uploadedBlobs) {
 	const { bodyStructure, bodyValues } = buildBodyStructure(message, uploadedBlobs);
-	const headers = [];
-	if (message.priority !== "normal") headers.push(...getPriorityHeaders(message.priority));
-	headers.push(...extractCustomHeaders(message));
+	const identity = resolveIdentity(message);
+	const headerProperties = {};
+	for (const { name, value } of getPriorityHeaders(message.priority)) headerProperties[`header:${name}`] = value;
+	for (const { name, value } of extractCustomHeaders(message)) {
+		if (identity.owned.has(name.toLowerCase())) continue;
+		headerProperties[`header:${name}`] = value;
+	}
 	const email = {
 		mailboxIds: { [draftMailboxId]: true },
 		from: [formatAddress(message.sender)],
@@ -412,10 +448,89 @@ function convertMessage(message, draftMailboxId, uploadedBlobs) {
 		...message.ccRecipients.length > 0 && { cc: message.ccRecipients.map(formatAddress) },
 		...message.bccRecipients.length > 0 && { bcc: message.bccRecipients.map(formatAddress) },
 		...message.replyRecipients.length > 0 && { replyTo: message.replyRecipients.map(formatAddress) },
-		...headers.length > 0 && { headers }
+		...identity.properties,
+		...headerProperties
 	};
 	return email;
 }
+/**
+* Works out the identity and threading properties of an `Email` from the typed
+* fields of a message.
+*
+* A field the message leaves unset is not owned, so a header supplied through
+* {@link Message.headers} still reaches the server, and the server falls back
+* to generating an identifier and a date of its own.  A threading field set to
+* an empty list is owned but writes no property, which suppresses such a
+* header.
+*
+* @param message The message being converted.
+* @returns The properties to set, and the field names the message owns.
+* @throws {TypeError} If a message identifier is invalid, or the date is not a
+* valid one.
+* @throws {RangeError} If the year of the date is outside what an RFC 3339
+* date-time can express.
+*/
+function resolveIdentity(message) {
+	const owned = /* @__PURE__ */ new Set();
+	const properties = {};
+	if (message.priority !== "normal") {
+		owned.add("x-priority");
+		owned.add("importance");
+	}
+	if (message.messageId != null) {
+		owned.add("message-id");
+		properties.messageId = [checkMessageId(message.messageId)];
+	}
+	if (message.date != null) {
+		owned.add("date");
+		properties.sentAt = formatSentAt(message.date);
+	}
+	if (message.inReplyTo != null) {
+		owned.add("in-reply-to");
+		if (message.inReplyTo.length > 0) properties.inReplyTo = message.inReplyTo.map(checkMessageId);
+	}
+	if (message.references != null) {
+		owned.add("references");
+		if (message.references.length > 0) properties.references = message.references.map(checkMessageId);
+	}
+	return {
+		properties,
+		owned
+	};
+}
+/**
+* Checks a message identifier a message carries.
+*
+* `createMessage()` validates these, but `Message` is a structural type that a
+* caller can build without it.
+*
+* @param id The identifier to check.
+* @returns The identifier, unchanged.
+* @throws {TypeError} If the value is not a valid message identifier.
+*/
+function checkMessageId(id) {
+	const parsed = parseMessageId(id);
+	if (parsed == null) throw new TypeError(`Invalid message ID: ${JSON.stringify(id)}`);
+	return parsed;
+}
+/**
+* Formats a date as the RFC 3339 date-time JMAP calls a `Date`.
+*
+* RFC 8620 §1.4 omits a fractional-seconds part that is zero, which
+* `Date.toISOString()` always writes.
+*
+* @param date The date to format.
+* @returns The formatted date.
+* @throws {TypeError} If the date is not a valid one.
+* @throws {RangeError} If its year cannot be written as four digits.
+*/
+function formatSentAt(date) {
+	const time = date instanceof Date ? date.getTime() : NaN;
+	if (Number.isNaN(time)) throw new TypeError(`Invalid date: ${JSON.stringify(date)}`);
+	const year = date.getUTCFullYear();
+	if (year < 1 || year > 9999) throw new RangeError(`Year out of range for an RFC 3339 date: ${year}`);
+	return date.toISOString().replace(".000Z", "Z");
+}
 
 //#endregion
 //#region src/session.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/jmap",
-  "version": "0.6.0-dev.318",
+  "version": "0.6.0-dev.319",
   "description": "JMAP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.318+9378b2c8"
+    "@upyo/core": "0.6.0-dev.319+2324fa8c"
   },
   "devDependencies": {
     "jmap-rfc-types": "^0.1.2",