@upyo/smtp 0.4.0-dev.65 → 0.4.0-dev.68

package/README.md

@@ -31,6 +31,7 @@ Features
  -  TypeScript support
  -  Cross-runtime compatibility (Node.js, Bun, Deno)
  -  STARTTLS support for secure connection upgrade
+ -  DKIM signing support (RSA-SHA256 and Ed25519-SHA256)
 
 
 Installation
@@ -111,6 +112,7 @@ Configuration options
 | `localName`         | `string`         | `"localhost"` | Local hostname for `HELO`/`EHLO` |
 | `pool`              | `boolean`        | `true`        | Enable connection pooling        |
 | `poolSize`          | `number`         | `5`           | Maximum pool connections         |
+| `dkim`              | `DkimConfig`     |               | DKIM signing configuration       |
 
 ### `SmtpAuth`
 
@@ -121,6 +123,51 @@ Configuration options
 | `method` | `"plain" \| "login" \| "cram-md5"` | `"plain"` | Auth method |
 
 
+DKIM signing
+------------
+
+DKIM (DomainKeys Identified Mail) signing is supported for improved email
+deliverability and authentication:
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { SmtpTransport } from "@upyo/smtp";
+import { readFileSync } from "node:fs";
+
+const transport = new SmtpTransport({
+  host: "smtp.example.com",
+  port: 587,
+  secure: false,
+  auth: { user: "user@example.com", pass: "password" },
+  dkim: {
+    signatures: [{
+      signingDomain: "example.com",
+      selector: "mail",
+      privateKey: readFileSync("./dkim-private.pem", "utf8"),
+    }],
+  },
+});
+~~~~
+
+### `DkimConfig`
+
+| Option             | Type                           | Default   | Description                           |
+|--------------------|--------------------------------|-----------|---------------------------------------|
+| `signatures`       | `DkimSignature[]`              |           | Array of DKIM signature configs       |
+| `onSigningFailure` | `"throw" \| "send-unsigned"`   | `"throw"` | Action when signing fails             |
+
+### `DkimSignature`
+
+| Option             | Type                               | Default             | Description                             |
+|--------------------|------------------------------------|---------------------|-----------------------------------------|
+| `signingDomain`    | `string`                           |                     | Domain for DKIM key (d= tag)            |
+| `selector`         | `string`                           |                     | DKIM selector (s= tag)                  |
+| `privateKey`       | `string \| CryptoKey`              |                     | Private key (PEM string or `CryptoKey`) |
+| `algorithm`        | `"rsa-sha256" \| "ed25519-sha256"` | `"rsa-sha256"`      | Signing algorithm                       |
+| `canonicalization` | `string`                           | `"relaxed/relaxed"` | Header/body canonicalization            |
+| `headerFields`     | `string[]`                         | From, To, ...       | Headers to sign                         |
+
+
 Testing
 -------
 

package/dist/index.cjs

@@ -48,7 +48,8 @@ function createSmtpConfig(config) {
 		socketTimeout: config.socketTimeout ?? 6e4,
 		localName: config.localName ?? "localhost",
 		pool: config.pool ?? true,
-		poolSize: config.poolSize ?? 5
+		poolSize: config.poolSize ?? 5,
+		dkim: config.dkim
 	};
 }
 
@@ -297,9 +298,286 @@ var SmtpConnection = class {
 	}
 };
 
+//#endregion
+//#region src/dkim/canonicalize.ts
+/**
+* DKIM Canonicalization algorithms per RFC 6376 Section 3.4.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6376#section-3.4
+* @since 0.4.0
+*/
+/**
+* Simple header canonicalization.
+*
+* The "simple" header canonicalization algorithm does not change header
+* fields in any way. Header fields are presented to the signing or
+* verification algorithm exactly as they are in the message.
+*
+* @param name - The header field name
+* @param value - The header field value
+* @returns The canonicalized header line (name:value)
+* @see RFC 6376 Section 3.4.1
+* @since 0.4.0
+*/
+function canonicalizeHeaderSimple(name, value) {
+	return `${name}:${value}`;
+}
+/**
+* Relaxed header canonicalization.
+*
+* The "relaxed" header canonicalization algorithm:
+* - Convert header field names to lowercase
+* - Unfold header field continuation lines
+* - Collapse whitespace sequences to a single space
+* - Remove leading and trailing whitespace from header field values
+*
+* @param name - The header field name
+* @param value - The header field value
+* @returns The canonicalized header line (name:value)
+* @see RFC 6376 Section 3.4.2
+* @since 0.4.0
+*/
+function canonicalizeHeaderRelaxed(name, value) {
+	const canonicalName = name.toLowerCase();
+	const canonicalValue = value.replace(/\r\n[\t ]+/g, " ").replace(/[\t ]+/g, " ").trim();
+	return `${canonicalName}:${canonicalValue}`;
+}
+/**
+* Simple body canonicalization.
+*
+* The "simple" body canonicalization algorithm:
+* - Ignores all empty lines at the end of the message body
+* - If the body is empty, a single CRLF is appended
+* - If there is no trailing CRLF on the body, a CRLF is added
+*
+* @param body - The message body
+* @returns The canonicalized body
+* @see RFC 6376 Section 3.4.3
+* @since 0.4.0
+*/
+function canonicalizeBodySimple(body) {
+	if (body === "") return "\r\n";
+	let result = body.replace(/(\r\n)+$/, "");
+	if (!result.endsWith("\r\n")) result += "\r\n";
+	return result;
+}
+/**
+* Relaxed body canonicalization.
+*
+* The "relaxed" body canonicalization algorithm:
+* - Reduce all sequences of WSP within a line to a single SP
+* - Remove all trailing WSP at the end of each line (before CRLF)
+* - Ignore all empty lines at the end of the message body
+* - If the body is non-empty and doesn't end with CRLF, add CRLF
+*
+* @param body - The message body
+* @returns The canonicalized body
+* @see RFC 6376 Section 3.4.4
+* @since 0.4.0
+*/
+function canonicalizeBodyRelaxed(body) {
+	if (body === "") return "";
+	let processedBody = body;
+	if (!processedBody.endsWith("\r\n")) processedBody += "\r\n";
+	const lines = processedBody.split("\r\n");
+	const canonicalizedLines = [];
+	for (let i = 0; i < lines.length - 1; i++) {
+		let line = lines[i];
+		line = line.replace(/[\t ]+/g, " ");
+		line = line.replace(/[\t ]+$/, "");
+		canonicalizedLines.push(line);
+	}
+	while (canonicalizedLines.length > 0 && canonicalizedLines[canonicalizedLines.length - 1] === "") canonicalizedLines.pop();
+	if (canonicalizedLines.length === 0) return "";
+	return canonicalizedLines.join("\r\n") + "\r\n";
+}
+
+//#endregion
+//#region src/dkim/types.ts
+/**
+* Default header fields to sign if not specified.
+*
+* @since 0.4.0
+*/
+const DEFAULT_SIGNED_HEADERS = [
+	"from",
+	"to",
+	"subject",
+	"date"
+];
+/**
+* Default DKIM algorithm.
+*
+* @since 0.4.0
+*/
+const DEFAULT_ALGORITHM = "rsa-sha256";
+/**
+* Default canonicalization method.
+*
+* @since 0.4.0
+*/
+const DEFAULT_CANONICALIZATION = "relaxed/relaxed";
+
+//#endregion
+//#region src/dkim/sign.ts
+/**
+* Signs a raw email message with DKIM.
+*
+* @param rawMessage - The complete raw email message (headers + body)
+* @param config - DKIM signature configuration
+* @returns The DKIM-Signature header result
+* @throws Error if signing fails (e.g., invalid private key)
+* @since 0.4.0
+*/
+async function signMessage(rawMessage, config) {
+	const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+	const canonicalization = config.canonicalization ?? DEFAULT_CANONICALIZATION;
+	const headerFields = config.headerFields ?? DEFAULT_SIGNED_HEADERS;
+	const { headers, body } = parseMessage(rawMessage);
+	const [headerCanon, bodyCanon] = canonicalization.split("/");
+	const privateKey = await getPrivateKey(config.privateKey, algorithm);
+	const bodyHash = await computeBodyHash(body, bodyCanon);
+	const dkimHeaderValue = buildDkimHeaderValue({
+		algorithm,
+		canonicalization,
+		signingDomain: config.signingDomain,
+		selector: config.selector,
+		headerFields,
+		bodyHash
+	});
+	const signatureData = buildSignatureData(headers, headerFields, headerCanon, dkimHeaderValue);
+	const signature = await signData(signatureData, privateKey, algorithm);
+	return {
+		headerName: "DKIM-Signature",
+		signature: `${dkimHeaderValue} b=${signature}`
+	};
+}
+/**
+* Parses a raw email message into headers and body.
+*/
+function parseMessage(rawMessage) {
+	const separatorIndex = rawMessage.indexOf("\r\n\r\n");
+	if (separatorIndex === -1) return {
+		headers: parseHeaders(rawMessage),
+		body: ""
+	};
+	const headerSection = rawMessage.substring(0, separatorIndex);
+	const body = rawMessage.substring(separatorIndex + 4);
+	return {
+		headers: parseHeaders(headerSection),
+		body
+	};
+}
+/**
+* Parses header section into a map of header name to value.
+* Handles folded headers (continuation lines).
+*/
+function parseHeaders(headerSection) {
+	const headers = /* @__PURE__ */ new Map();
+	const lines = headerSection.split("\r\n");
+	let currentName = "";
+	let currentValue = "";
+	for (const line of lines) if (line.startsWith(" ") || line.startsWith("	")) currentValue += "\r\n" + line;
+	else {
+		if (currentName) headers.set(currentName.toLowerCase(), currentValue);
+		const colonIndex = line.indexOf(":");
+		if (colonIndex > 0) {
+			currentName = line.substring(0, colonIndex);
+			currentValue = line.substring(colonIndex + 1);
+		}
+	}
+	if (currentName) headers.set(currentName.toLowerCase(), currentValue);
+	return headers;
+}
+/**
+* Gets the private key, either using a provided CryptoKey or importing from PEM.
+*/
+function getPrivateKey(key, algorithm) {
+	if (typeof key !== "string") return key;
+	return importPrivateKey(key, algorithm);
+}
+/**
+* Imports a PEM-encoded private key for use with Web Crypto API.
+*/
+async function importPrivateKey(pem, algorithm) {
+	try {
+		const pemContents = pem.replace(/-----BEGIN (?:RSA )?PRIVATE KEY-----/, "").replace(/-----END (?:RSA )?PRIVATE KEY-----/, "").replace(/\s/g, "");
+		const binaryString = atob(pemContents);
+		const bytes = new Uint8Array(binaryString.length);
+		for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+		const keyAlgorithm = algorithm === "ed25519-sha256" ? { name: "Ed25519" } : {
+			name: "RSASSA-PKCS1-v1_5",
+			hash: "SHA-256"
+		};
+		return await crypto.subtle.importKey("pkcs8", bytes, keyAlgorithm, false, ["sign"]);
+	} catch (error) {
+		throw new Error(`Failed to import private key: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Computes the body hash (bh= tag value).
+*/
+async function computeBodyHash(body, canonMethod) {
+	const canonicalBody = canonMethod === "relaxed" ? canonicalizeBodyRelaxed(body) : canonicalizeBodySimple(body);
+	const encoder = new TextEncoder();
+	const data = encoder.encode(canonicalBody);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	return arrayBufferToBase64(hashBuffer);
+}
+/**
+* Builds the DKIM-Signature header value without the b= signature.
+*/
+function buildDkimHeaderValue(params) {
+	const parts = [
+		"v=1",
+		`a=${params.algorithm}`,
+		`c=${params.canonicalization}`,
+		`d=${params.signingDomain}`,
+		`s=${params.selector}`,
+		`h=${params.headerFields.join(":")}`,
+		`bh=${params.bodyHash};`
+	];
+	return parts.join("; ");
+}
+/**
+* Builds the data to be signed (canonicalized headers + DKIM-Signature header).
+*/
+function buildSignatureData(headers, headerFields, canonMethod, dkimHeaderValue) {
+	const lines = [];
+	for (const field of headerFields) {
+		const value = headers.get(field.toLowerCase());
+		if (value !== void 0) {
+			const canonicalized = canonMethod === "relaxed" ? canonicalizeHeaderRelaxed(field, value) : canonicalizeHeaderSimple(field, value);
+			lines.push(canonicalized);
+		}
+	}
+	const dkimHeader = canonMethod === "relaxed" ? canonicalizeHeaderRelaxed("DKIM-Signature", " " + dkimHeaderValue + " b=") : canonicalizeHeaderSimple("DKIM-Signature", " " + dkimHeaderValue + " b=");
+	lines.push(dkimHeader);
+	return lines.join("\r\n");
+}
+/**
+* Signs data using the appropriate algorithm.
+*/
+async function signData(data, privateKey, algorithm) {
+	const encoder = new TextEncoder();
+	const dataBuffer = encoder.encode(data);
+	const signAlgorithm = algorithm === "ed25519-sha256" ? "Ed25519" : "RSASSA-PKCS1-v1_5";
+	const signature = await crypto.subtle.sign(signAlgorithm, privateKey, dataBuffer);
+	return arrayBufferToBase64(signature);
+}
+/**
+* Converts an ArrayBuffer to a Base64 string.
+*/
+function arrayBufferToBase64(buffer) {
+	const bytes = new Uint8Array(buffer);
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+
 //#endregion
 //#region src/message-converter.ts
-async function convertMessage(message) {
+async function convertMessage(message, dkimConfig) {
 	const envelope = {
 		from: message.sender.address,
 		to: [
@@ -308,7 +586,16 @@ async function convertMessage(message) {
 			...message.bccRecipients.map((r) => r.address)
 		]
 	};
-	const raw = await buildRawMessage(message);
+	let raw = await buildRawMessage(message);
+	if (dkimConfig) try {
+		for (const sig of dkimConfig.signatures) {
+			const result = await signMessage(raw, sig);
+			raw = `${result.headerName}: ${result.signature}\r\n${raw}`;
+		}
+	} catch (error) {
+		if (dkimConfig.onSigningFailure === "send-unsigned") console.warn("DKIM signing failed, sending unsigned:", error);
+		else throw error;
+	}
 	return {
 		envelope,
 		raw
@@ -547,7 +834,7 @@ var SmtpTransport = class {
 		const connection = await this.getConnection(options?.signal);
 		try {
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message);
+			const smtpMessage = await convertMessage(message, this.config.dkim);
 			options?.signal?.throwIfAborted();
 			const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -607,7 +894,7 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message);
+					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -632,7 +919,7 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message);
+					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {

package/dist/index.d.cts

@@ -1,7 +1,108 @@
 import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
 
-//#region src/config.d.ts
+//#region src/dkim/types.d.ts
 
+/**
+ * Supported DKIM signing algorithms.
+ *
+ * - `rsa-sha256`: RSA with SHA-256, most widely used (RFC 6376)
+ * - `ed25519-sha256`: Ed25519 with SHA-256, shorter keys (RFC 8463)
+ *
+ * @since 0.4.0
+ */
+type DkimAlgorithm = "rsa-sha256" | "ed25519-sha256";
+/**
+ * DKIM canonicalization methods for header and body.
+ *
+ * Format: "header-method/body-method"
+ *
+ * - `simple`: No modifications (preserves exact content)
+ * - `relaxed`: Normalizes whitespace and case
+ *
+ * @see RFC 6376 Section 3.4
+ * @since 0.4.0
+ */
+type DkimCanonicalization = "relaxed/relaxed" | "relaxed/simple" | "simple/relaxed" | "simple/simple";
+/**
+ * Configuration for a single DKIM signature.
+ *
+ * Each signature represents one DKIM-Signature header that will be added
+ * to the email. Multiple signatures can be used for different domains
+ * or selectors.
+ *
+ * @since 0.4.0
+ */
+interface DkimSignature {
+  /**
+   * The domain name for the DKIM key (d= tag).
+   * This is the domain claiming responsibility for the message.
+   */
+  readonly signingDomain: string;
+  /**
+   * The DKIM selector (s= tag).
+   * Used to locate the public key in DNS: `selector._domainkey.signingDomain`
+   */
+  readonly selector: string;
+  /**
+   * The private key for signing.
+   *
+   * Can be either:
+   * - A PEM-encoded private key string (PKCS#8 format)
+   * - A `CryptoKey` object from Web Crypto API
+   *
+   * For RSA keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   * For Ed25519 keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   */
+  readonly privateKey: string | CryptoKey;
+  /**
+   * The signing algorithm (a= tag).
+   * @default "rsa-sha256"
+   */
+  readonly algorithm?: DkimAlgorithm;
+  /**
+   * The canonicalization method for header and body (c= tag).
+   * @default "relaxed/relaxed"
+   */
+  readonly canonicalization?: DkimCanonicalization;
+  /**
+   * Header fields to include in the signature (h= tag).
+   * @default ["from", "to", "subject", "date"]
+   */
+  readonly headerFields?: readonly string[];
+}
+/**
+ * Action to take when DKIM signing fails.
+ *
+ * - `throw`: Throw an error and abort sending (default)
+ * - `send-unsigned`: Log a warning and send the email without DKIM signature
+ *
+ * @since 0.4.0
+ */
+type DkimSigningFailureAction = "throw" | "send-unsigned";
+/**
+ * Configuration for DKIM signing in SMTP transport.
+ *
+ * @since 0.4.0
+ */
+interface DkimConfig {
+  /**
+   * Array of DKIM signature configurations.
+   * Each configuration will result in one DKIM-Signature header.
+   */
+  readonly signatures: readonly DkimSignature[];
+  /**
+   * Action to take when DKIM signing fails.
+   * @default "throw"
+   */
+  readonly onSigningFailure?: DkimSigningFailureAction;
+}
+/**
+ * Result of DKIM signing operation.
+ *
+ * @since 0.4.0
+ */
+//#endregion
+//#region src/config.d.ts
 /**
  * Configuration interface for SMTP transport connection settings.
  *
@@ -71,6 +172,12 @@ interface SmtpConfig {
    * @default 5
    */
   readonly poolSize?: number;
+  /**
+   * DKIM signing configuration.
+   * When provided, all outgoing emails will be signed with DKIM.
+   * @since 0.4.0
+   */
+  readonly dkim?: DkimConfig;
 }
 /**
  * Authentication configuration for SMTP connections.
@@ -295,4 +402,4 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
   [Symbol.asyncDispose](): Promise<void>;
 }
 //#endregion
-export { SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };

package/dist/index.d.ts

@@ -1,7 +1,108 @@
 import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
 
-//#region src/config.d.ts
+//#region src/dkim/types.d.ts
 
+/**
+ * Supported DKIM signing algorithms.
+ *
+ * - `rsa-sha256`: RSA with SHA-256, most widely used (RFC 6376)
+ * - `ed25519-sha256`: Ed25519 with SHA-256, shorter keys (RFC 8463)
+ *
+ * @since 0.4.0
+ */
+type DkimAlgorithm = "rsa-sha256" | "ed25519-sha256";
+/**
+ * DKIM canonicalization methods for header and body.
+ *
+ * Format: "header-method/body-method"
+ *
+ * - `simple`: No modifications (preserves exact content)
+ * - `relaxed`: Normalizes whitespace and case
+ *
+ * @see RFC 6376 Section 3.4
+ * @since 0.4.0
+ */
+type DkimCanonicalization = "relaxed/relaxed" | "relaxed/simple" | "simple/relaxed" | "simple/simple";
+/**
+ * Configuration for a single DKIM signature.
+ *
+ * Each signature represents one DKIM-Signature header that will be added
+ * to the email. Multiple signatures can be used for different domains
+ * or selectors.
+ *
+ * @since 0.4.0
+ */
+interface DkimSignature {
+  /**
+   * The domain name for the DKIM key (d= tag).
+   * This is the domain claiming responsibility for the message.
+   */
+  readonly signingDomain: string;
+  /**
+   * The DKIM selector (s= tag).
+   * Used to locate the public key in DNS: `selector._domainkey.signingDomain`
+   */
+  readonly selector: string;
+  /**
+   * The private key for signing.
+   *
+   * Can be either:
+   * - A PEM-encoded private key string (PKCS#8 format)
+   * - A `CryptoKey` object from Web Crypto API
+   *
+   * For RSA keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   * For Ed25519 keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   */
+  readonly privateKey: string | CryptoKey;
+  /**
+   * The signing algorithm (a= tag).
+   * @default "rsa-sha256"
+   */
+  readonly algorithm?: DkimAlgorithm;
+  /**
+   * The canonicalization method for header and body (c= tag).
+   * @default "relaxed/relaxed"
+   */
+  readonly canonicalization?: DkimCanonicalization;
+  /**
+   * Header fields to include in the signature (h= tag).
+   * @default ["from", "to", "subject", "date"]
+   */
+  readonly headerFields?: readonly string[];
+}
+/**
+ * Action to take when DKIM signing fails.
+ *
+ * - `throw`: Throw an error and abort sending (default)
+ * - `send-unsigned`: Log a warning and send the email without DKIM signature
+ *
+ * @since 0.4.0
+ */
+type DkimSigningFailureAction = "throw" | "send-unsigned";
+/**
+ * Configuration for DKIM signing in SMTP transport.
+ *
+ * @since 0.4.0
+ */
+interface DkimConfig {
+  /**
+   * Array of DKIM signature configurations.
+   * Each configuration will result in one DKIM-Signature header.
+   */
+  readonly signatures: readonly DkimSignature[];
+  /**
+   * Action to take when DKIM signing fails.
+   * @default "throw"
+   */
+  readonly onSigningFailure?: DkimSigningFailureAction;
+}
+/**
+ * Result of DKIM signing operation.
+ *
+ * @since 0.4.0
+ */
+//#endregion
+//#region src/config.d.ts
 /**
  * Configuration interface for SMTP transport connection settings.
  *
@@ -71,6 +172,12 @@ interface SmtpConfig {
    * @default 5
    */
   readonly poolSize?: number;
+  /**
+   * DKIM signing configuration.
+   * When provided, all outgoing emails will be signed with DKIM.
+   * @since 0.4.0
+   */
+  readonly dkim?: DkimConfig;
 }
 /**
  * Authentication configuration for SMTP connections.
@@ -295,4 +402,4 @@ declare class SmtpTransport implements Transport, AsyncDisposable {
   [Symbol.asyncDispose](): Promise<void>;
 }
 //#endregion
-export { SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, SmtpAuth, SmtpConfig, SmtpTlsOptions, SmtpTransport };

package/dist/index.js

@@ -25,7 +25,8 @@ function createSmtpConfig(config) {
 		socketTimeout: config.socketTimeout ?? 6e4,
 		localName: config.localName ?? "localhost",
 		pool: config.pool ?? true,
-		poolSize: config.poolSize ?? 5
+		poolSize: config.poolSize ?? 5,
+		dkim: config.dkim
 	};
 }
 
@@ -274,9 +275,286 @@ var SmtpConnection = class {
 	}
 };
 
+//#endregion
+//#region src/dkim/canonicalize.ts
+/**
+* DKIM Canonicalization algorithms per RFC 6376 Section 3.4.
+*
+* @see https://www.rfc-editor.org/rfc/rfc6376#section-3.4
+* @since 0.4.0
+*/
+/**
+* Simple header canonicalization.
+*
+* The "simple" header canonicalization algorithm does not change header
+* fields in any way. Header fields are presented to the signing or
+* verification algorithm exactly as they are in the message.
+*
+* @param name - The header field name
+* @param value - The header field value
+* @returns The canonicalized header line (name:value)
+* @see RFC 6376 Section 3.4.1
+* @since 0.4.0
+*/
+function canonicalizeHeaderSimple(name, value) {
+	return `${name}:${value}`;
+}
+/**
+* Relaxed header canonicalization.
+*
+* The "relaxed" header canonicalization algorithm:
+* - Convert header field names to lowercase
+* - Unfold header field continuation lines
+* - Collapse whitespace sequences to a single space
+* - Remove leading and trailing whitespace from header field values
+*
+* @param name - The header field name
+* @param value - The header field value
+* @returns The canonicalized header line (name:value)
+* @see RFC 6376 Section 3.4.2
+* @since 0.4.0
+*/
+function canonicalizeHeaderRelaxed(name, value) {
+	const canonicalName = name.toLowerCase();
+	const canonicalValue = value.replace(/\r\n[\t ]+/g, " ").replace(/[\t ]+/g, " ").trim();
+	return `${canonicalName}:${canonicalValue}`;
+}
+/**
+* Simple body canonicalization.
+*
+* The "simple" body canonicalization algorithm:
+* - Ignores all empty lines at the end of the message body
+* - If the body is empty, a single CRLF is appended
+* - If there is no trailing CRLF on the body, a CRLF is added
+*
+* @param body - The message body
+* @returns The canonicalized body
+* @see RFC 6376 Section 3.4.3
+* @since 0.4.0
+*/
+function canonicalizeBodySimple(body) {
+	if (body === "") return "\r\n";
+	let result = body.replace(/(\r\n)+$/, "");
+	if (!result.endsWith("\r\n")) result += "\r\n";
+	return result;
+}
+/**
+* Relaxed body canonicalization.
+*
+* The "relaxed" body canonicalization algorithm:
+* - Reduce all sequences of WSP within a line to a single SP
+* - Remove all trailing WSP at the end of each line (before CRLF)
+* - Ignore all empty lines at the end of the message body
+* - If the body is non-empty and doesn't end with CRLF, add CRLF
+*
+* @param body - The message body
+* @returns The canonicalized body
+* @see RFC 6376 Section 3.4.4
+* @since 0.4.0
+*/
+function canonicalizeBodyRelaxed(body) {
+	if (body === "") return "";
+	let processedBody = body;
+	if (!processedBody.endsWith("\r\n")) processedBody += "\r\n";
+	const lines = processedBody.split("\r\n");
+	const canonicalizedLines = [];
+	for (let i = 0; i < lines.length - 1; i++) {
+		let line = lines[i];
+		line = line.replace(/[\t ]+/g, " ");
+		line = line.replace(/[\t ]+$/, "");
+		canonicalizedLines.push(line);
+	}
+	while (canonicalizedLines.length > 0 && canonicalizedLines[canonicalizedLines.length - 1] === "") canonicalizedLines.pop();
+	if (canonicalizedLines.length === 0) return "";
+	return canonicalizedLines.join("\r\n") + "\r\n";
+}
+
+//#endregion
+//#region src/dkim/types.ts
+/**
+* Default header fields to sign if not specified.
+*
+* @since 0.4.0
+*/
+const DEFAULT_SIGNED_HEADERS = [
+	"from",
+	"to",
+	"subject",
+	"date"
+];
+/**
+* Default DKIM algorithm.
+*
+* @since 0.4.0
+*/
+const DEFAULT_ALGORITHM = "rsa-sha256";
+/**
+* Default canonicalization method.
+*
+* @since 0.4.0
+*/
+const DEFAULT_CANONICALIZATION = "relaxed/relaxed";
+
+//#endregion
+//#region src/dkim/sign.ts
+/**
+* Signs a raw email message with DKIM.
+*
+* @param rawMessage - The complete raw email message (headers + body)
+* @param config - DKIM signature configuration
+* @returns The DKIM-Signature header result
+* @throws Error if signing fails (e.g., invalid private key)
+* @since 0.4.0
+*/
+async function signMessage(rawMessage, config) {
+	const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+	const canonicalization = config.canonicalization ?? DEFAULT_CANONICALIZATION;
+	const headerFields = config.headerFields ?? DEFAULT_SIGNED_HEADERS;
+	const { headers, body } = parseMessage(rawMessage);
+	const [headerCanon, bodyCanon] = canonicalization.split("/");
+	const privateKey = await getPrivateKey(config.privateKey, algorithm);
+	const bodyHash = await computeBodyHash(body, bodyCanon);
+	const dkimHeaderValue = buildDkimHeaderValue({
+		algorithm,
+		canonicalization,
+		signingDomain: config.signingDomain,
+		selector: config.selector,
+		headerFields,
+		bodyHash
+	});
+	const signatureData = buildSignatureData(headers, headerFields, headerCanon, dkimHeaderValue);
+	const signature = await signData(signatureData, privateKey, algorithm);
+	return {
+		headerName: "DKIM-Signature",
+		signature: `${dkimHeaderValue} b=${signature}`
+	};
+}
+/**
+* Parses a raw email message into headers and body.
+*/
+function parseMessage(rawMessage) {
+	const separatorIndex = rawMessage.indexOf("\r\n\r\n");
+	if (separatorIndex === -1) return {
+		headers: parseHeaders(rawMessage),
+		body: ""
+	};
+	const headerSection = rawMessage.substring(0, separatorIndex);
+	const body = rawMessage.substring(separatorIndex + 4);
+	return {
+		headers: parseHeaders(headerSection),
+		body
+	};
+}
+/**
+* Parses header section into a map of header name to value.
+* Handles folded headers (continuation lines).
+*/
+function parseHeaders(headerSection) {
+	const headers = /* @__PURE__ */ new Map();
+	const lines = headerSection.split("\r\n");
+	let currentName = "";
+	let currentValue = "";
+	for (const line of lines) if (line.startsWith(" ") || line.startsWith("	")) currentValue += "\r\n" + line;
+	else {
+		if (currentName) headers.set(currentName.toLowerCase(), currentValue);
+		const colonIndex = line.indexOf(":");
+		if (colonIndex > 0) {
+			currentName = line.substring(0, colonIndex);
+			currentValue = line.substring(colonIndex + 1);
+		}
+	}
+	if (currentName) headers.set(currentName.toLowerCase(), currentValue);
+	return headers;
+}
+/**
+* Gets the private key, either using a provided CryptoKey or importing from PEM.
+*/
+function getPrivateKey(key, algorithm) {
+	if (typeof key !== "string") return key;
+	return importPrivateKey(key, algorithm);
+}
+/**
+* Imports a PEM-encoded private key for use with Web Crypto API.
+*/
+async function importPrivateKey(pem, algorithm) {
+	try {
+		const pemContents = pem.replace(/-----BEGIN (?:RSA )?PRIVATE KEY-----/, "").replace(/-----END (?:RSA )?PRIVATE KEY-----/, "").replace(/\s/g, "");
+		const binaryString = atob(pemContents);
+		const bytes = new Uint8Array(binaryString.length);
+		for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+		const keyAlgorithm = algorithm === "ed25519-sha256" ? { name: "Ed25519" } : {
+			name: "RSASSA-PKCS1-v1_5",
+			hash: "SHA-256"
+		};
+		return await crypto.subtle.importKey("pkcs8", bytes, keyAlgorithm, false, ["sign"]);
+	} catch (error) {
+		throw new Error(`Failed to import private key: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Computes the body hash (bh= tag value).
+*/
+async function computeBodyHash(body, canonMethod) {
+	const canonicalBody = canonMethod === "relaxed" ? canonicalizeBodyRelaxed(body) : canonicalizeBodySimple(body);
+	const encoder = new TextEncoder();
+	const data = encoder.encode(canonicalBody);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	return arrayBufferToBase64(hashBuffer);
+}
+/**
+* Builds the DKIM-Signature header value without the b= signature.
+*/
+function buildDkimHeaderValue(params) {
+	const parts = [
+		"v=1",
+		`a=${params.algorithm}`,
+		`c=${params.canonicalization}`,
+		`d=${params.signingDomain}`,
+		`s=${params.selector}`,
+		`h=${params.headerFields.join(":")}`,
+		`bh=${params.bodyHash};`
+	];
+	return parts.join("; ");
+}
+/**
+* Builds the data to be signed (canonicalized headers + DKIM-Signature header).
+*/
+function buildSignatureData(headers, headerFields, canonMethod, dkimHeaderValue) {
+	const lines = [];
+	for (const field of headerFields) {
+		const value = headers.get(field.toLowerCase());
+		if (value !== void 0) {
+			const canonicalized = canonMethod === "relaxed" ? canonicalizeHeaderRelaxed(field, value) : canonicalizeHeaderSimple(field, value);
+			lines.push(canonicalized);
+		}
+	}
+	const dkimHeader = canonMethod === "relaxed" ? canonicalizeHeaderRelaxed("DKIM-Signature", " " + dkimHeaderValue + " b=") : canonicalizeHeaderSimple("DKIM-Signature", " " + dkimHeaderValue + " b=");
+	lines.push(dkimHeader);
+	return lines.join("\r\n");
+}
+/**
+* Signs data using the appropriate algorithm.
+*/
+async function signData(data, privateKey, algorithm) {
+	const encoder = new TextEncoder();
+	const dataBuffer = encoder.encode(data);
+	const signAlgorithm = algorithm === "ed25519-sha256" ? "Ed25519" : "RSASSA-PKCS1-v1_5";
+	const signature = await crypto.subtle.sign(signAlgorithm, privateKey, dataBuffer);
+	return arrayBufferToBase64(signature);
+}
+/**
+* Converts an ArrayBuffer to a Base64 string.
+*/
+function arrayBufferToBase64(buffer) {
+	const bytes = new Uint8Array(buffer);
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+
 //#endregion
 //#region src/message-converter.ts
-async function convertMessage(message) {
+async function convertMessage(message, dkimConfig) {
 	const envelope = {
 		from: message.sender.address,
 		to: [
@@ -285,7 +563,16 @@ async function convertMessage(message) {
 			...message.bccRecipients.map((r) => r.address)
 		]
 	};
-	const raw = await buildRawMessage(message);
+	let raw = await buildRawMessage(message);
+	if (dkimConfig) try {
+		for (const sig of dkimConfig.signatures) {
+			const result = await signMessage(raw, sig);
+			raw = `${result.headerName}: ${result.signature}\r\n${raw}`;
+		}
+	} catch (error) {
+		if (dkimConfig.onSigningFailure === "send-unsigned") console.warn("DKIM signing failed, sending unsigned:", error);
+		else throw error;
+	}
 	return {
 		envelope,
 		raw
@@ -524,7 +811,7 @@ var SmtpTransport = class {
 		const connection = await this.getConnection(options?.signal);
 		try {
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message);
+			const smtpMessage = await convertMessage(message, this.config.dkim);
 			options?.signal?.throwIfAborted();
 			const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -584,7 +871,7 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message);
+					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
@@ -609,7 +896,7 @@ var SmtpTransport = class {
 					continue;
 				}
 				try {
-					const smtpMessage = await convertMessage(message);
+					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.4.0-dev.65+62f075a4",
+  "version": "0.4.0-dev.68+c6f685e9",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.4.0-dev.65+62f075a4"
+    "@upyo/core": "0.4.0-dev.68+c6f685e9"
   },
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.47.3",