apple-mail-mcp 2.10.27 → 2.10.29

package/README.md

@@ -311,7 +311,7 @@ Send a new email immediately.
 | `cc` | string[] | No | CC recipients |
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Mail.app account label, or an email-form SMTP From override. An SMTP override must match `APPLE_MAIL_MCP_SMTP_USER`, `APPLE_MAIL_MCP_SMTP_FROM`, or an address in `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` |
-| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths (e.g., `"/Users/me/report.pdf"`) and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
+| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths inside the configured read roots (e.g., `"/Users/me/Documents/report.pdf"`) and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
 | `transport` | `"applescript"` \| `"smtp"` | No | Send transport. If omitted, **SMTP is used automatically when configured** (otherwise AppleScript). Pass `"smtp"` to require clean MIME, or `"applescript"` to force the Mail.app path — see [SMTP transport](#smtp-transport) |
 
 **Example:**
@@ -358,12 +358,19 @@ fallback.
 Configure SMTP via environment variables on the MCP server. The password is
 read from the macOS **Keychain** by default, so no secret goes in config:
 
+Non-implicit-TLS SMTP connections fail closed if STARTTLS is unavailable.
+`APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT=1` is a deliberate escape hatch for a
+trusted isolated server or test fixture; it disables the upgrade requirement and
+can expose credentials and message content. The server emits a warning when it
+is used. Keep the default unset.
+
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `APPLE_MAIL_MCP_SMTP_HOST` | Yes | — | SMTP server hostname (e.g. `smtp.fastmail.com`) |
 | `APPLE_MAIL_MCP_SMTP_USER` | Yes | — | SMTP username |
 | `APPLE_MAIL_MCP_SMTP_PORT` | No | `465` if secure, else `587` | SMTP port |
 | `APPLE_MAIL_MCP_SMTP_SECURE` | No | `false` | `true` for implicit TLS (port 465); otherwise STARTTLS |
+| `APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
 | `APPLE_MAIL_MCP_SMTP_FROM` | No | = user | From address |
 | `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` | No | — | Comma-separated sender aliases permitted as per-message From overrides |
 | `APPLE_MAIL_MCP_SMTP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
@@ -480,6 +487,7 @@ for an explicitly-named IMAP account, never on an omitted account.
 | `APPLE_MAIL_MCP_IMAP_ACCOUNT` | No | = user | Mail account name to match for routing |
 | `APPLE_MAIL_MCP_IMAP_HOST` | No | `imap.gmail.com` | IMAP server hostname |
 | `APPLE_MAIL_MCP_IMAP_PORT` | No | `993` | IMAP port (993 = implicit TLS) |
+| `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
 | `APPLE_MAIL_MCP_IMAP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | No | — | Keychain item service/server name |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
@@ -495,6 +503,12 @@ Each entry accepts `account`, `user`, `host`, `port`, `password`, `keychainServi
 `keychainAccount`. Calls route to the account matching their `account` argument (or the
 decoded `imap:` id), and each account keeps its own pooled connection.
 
+Non-implicit-TLS IMAP connections require STARTTLS and fail closed when the server
+does not offer a usable upgrade. `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT=1` is a
+deliberate escape hatch for a trusted isolated server or test fixture; it disables
+the upgrade requirement and can expose credentials and message content. Keep the
+default unset.
+
 As with SMTP, the password is read from the macOS **Keychain** by default (use
 an app-specific password for Gmail/Workspace/iCloud), so no secret goes in
 config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
@@ -651,7 +665,7 @@ Save an email to Drafts without sending.
 | `cc` | string[] | No | CC recipients |
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Account for draft |
-| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
+| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths inside the configured read roots and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
 
 **Returns:** Confirmation that draft was created.
 
@@ -1590,6 +1604,16 @@ The entrypoint is written as:
 - **Permission required** - macOS will prompt for automation permission on first use.
 - **No credential storage** - The server doesn't store any passwords or authentication tokens.
 - **Email safety** - Use `create-draft` to review emails before sending.
+- **Attachment read boundary** - Outbound file attachments may come from
+  ordinary files under the home directory, `/Volumes`, or temporary directories
+  by default. Hidden files and known credential/configuration locations
+  (including `.ssh`, `.aws`, `.config/gh`, Keychains, and
+  application `config.json` files) are denied. Set
+  `APPLE_MAIL_MCP_ATTACHMENT_READ_ROOTS` to a colon-separated list of explicit
+  absolute additional roots when a deliberate other location is required.
+  Paths are canonicalized before use, so symlink escapes are rejected. `/tmp`
+  is world-writable and is a convenience root, not a user-content trust
+  boundary. Inline base64 attachments are unaffected.
 
 ---
 
@@ -1599,7 +1623,7 @@ The entrypoint is written as:
 |------------|--------|
 | macOS only | Apple Mail and AppleScript are macOS-specific |
 | MCP `send-email` is plain-text | The `send-email` tool sends plain text (reading HTML content is supported). To send HTML, use the bundled `apple-mail-send` CLI with `--html-body-file` (sends `multipart/alternative` via SMTP) |
-| Attachments require absolute paths | File attachments must use full absolute paths (e.g., `/Users/me/file.pdf`) |
+| Attachment read path restrictions | Outbound file attachments must use full absolute paths inside the default home-directory, `/Volumes`, or temporary roots, except hidden files and protected credential/configuration locations. Set `APPLE_MAIL_MCP_ATTACHMENT_READ_ROOTS` to add an explicit absolute root for another deliberate location; symlink escapes are rejected. |
 | Smart mailboxes need Mail quit | Smart mailboxes are supported (see [Smart Mailbox Operations](#smart-mailbox-operations-intelligente-postfächer)), but `create-`/`delete-smart-mailbox` edit `SyncedSmartMailboxes.plist` directly — a running Mail may not show a new one until relaunched, and can overwrite plist edits it didn't make. Quit Mail first. Reading them needs Full Disk Access for the Node runtime |
 | Very large mailboxes not searchable *via AppleScript* | Apple Mail's AppleScript bridge times out on mailboxes with tens of thousands of messages, so unscoped `search-messages` skips mailboxes above `APPLE_MAIL_MAX_SEARCH_MAILBOX` (default 5000) and reports them as a partial result. Scope with `mailbox` + a date window — or configure the [IMAP backend](#imap-backend--opt-in), which searches these server-side in well under a second. ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)) |
 | Can't delete/rename server-side mailboxes or mutate drafts *via AppleScript* | Mail.app's AppleScript bridge can only `delete`/`rename` **local "On My Mac"** mailboxes and cannot delete/move drafts — it throws `AppleEvent handler failed` for IMAP/Gmail/Workspace/iCloud/Exchange mailboxes (the GUI can do it). Without IMAP configured, `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` return a clear "do it in Mail.app directly" error instead of a generic failure. With the [IMAP backend](#imap-backend--opt-in) configured for the account, these operations run via IMAP and succeed. ([#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) |

package/build/cli.js

@@ -48,7 +48,7 @@ var require_punycode = __commonJS({
     var damp = 700;
     var initialBias = 72;
     var initialN = 128;
-    var delimiter = "-";
+    var delimiter2 = "-";
     var regexPunycode = /^xn--/;
     var regexNonASCII = /[^\0-\x7F]/;
     var regexSeparators = /[\x2E\u3002\uFF0E\uFF61]/g;
@@ -139,7 +139,7 @@ var require_punycode = __commonJS({
       let i = 0;
       let n = initialN;
       let bias = initialBias;
-      let basic = input.lastIndexOf(delimiter);
+      let basic = input.lastIndexOf(delimiter2);
       if (basic < 0) {
         basic = 0;
       }
@@ -199,7 +199,7 @@ var require_punycode = __commonJS({
       const basicLength = output.length;
       let handledCPCount = basicLength;
       if (basicLength) {
-        output.push(delimiter);
+        output.push(delimiter2);
       }
       while (handledCPCount < inputLength) {
         let m = maxInt;
@@ -954,7 +954,7 @@ var require_shared = __commonJS({
       }
       return Object.keys(ifaces).map((key) => ifaces[key]).reduce((acc, val) => acc.concat(val), []).filter((i) => !i.internal || allowInternal).some((i) => i.family === "IPv" + family || i.family === family);
     };
-    var resolve = (family, hostname, options, callback) => {
+    var resolve2 = (family, hostname, options, callback) => {
       options = options || {};
       if (!isFamilySupported(family, options.allowInternalNetworkInterfaces)) {
         return callback(null, []);
@@ -1041,13 +1041,13 @@ var require_shared = __commonJS({
       let ipv6Addresses = [];
       let ipv4Error = null;
       let ipv6Error = null;
-      resolve(4, options.host, options, (err, addresses) => {
+      resolve2(4, options.host, options, (err, addresses) => {
         if (err) {
           ipv4Error = err;
         } else {
           ipv4Addresses = addresses || [];
         }
-        resolve(6, options.host, options, (err2, addresses2) => {
+        resolve2(6, options.host, options, (err2, addresses2) => {
           if (err2) {
             ipv6Error = err2;
           } else {
@@ -1236,13 +1236,13 @@ var require_shared = __commonJS({
       });
       return response;
     };
-    module.exports.callbackPromise = (resolve2, reject) => function() {
+    module.exports.callbackPromise = (resolve3, reject) => function() {
       const args = Array.from(arguments);
       const err = args.shift();
       if (err) {
         reject(err);
       } else {
-        resolve2(...args);
+        resolve3(...args);
       }
     };
     module.exports.parseDataURI = (uri) => {
@@ -1309,8 +1309,8 @@ var require_shared = __commonJS({
       options = options || {};
       let promise;
       if (!callback) {
-        promise = new Promise((resolve2, reject) => {
-          callback = module.exports.callbackPromise(resolve2, reject);
+        promise = new Promise((resolve3, reject) => {
+          callback = module.exports.callbackPromise(resolve3, reject);
         });
       }
       resolveContentValue(data, key, options, callback);
@@ -4981,8 +4981,8 @@ var require_mime_node = __commonJS({
       build(callback) {
         let promise;
         if (!callback) {
-          promise = new Promise((resolve, reject) => {
-            callback = shared.callbackPromise(resolve, reject);
+          promise = new Promise((resolve2, reject) => {
+            callback = shared.callbackPromise(resolve2, reject);
           });
         }
         const stream = this.createReadStream();
@@ -7211,8 +7211,8 @@ var require_mailer = __commonJS({
       sendMail(data, callback = null) {
         let promise;
         if (!callback) {
-          promise = new Promise((resolve, reject) => {
-            callback = shared.callbackPromise(resolve, reject);
+          promise = new Promise((resolve2, reject) => {
+            callback = shared.callbackPromise(resolve2, reject);
           });
         }
         if (typeof this.getSocket === "function") {
@@ -7920,7 +7920,7 @@ var require_smtp_connection = __commonJS({
           const handler = this.customAuth.get(this._authMethod);
           let lastResponse;
           let returned = false;
-          const resolve = () => {
+          const resolve2 = () => {
             if (returned) {
               return;
             }
@@ -7954,8 +7954,8 @@ var require_smtp_connection = __commonJS({
             sendCommand: (cmd, done) => {
               let promise;
               if (!done) {
-                promise = new Promise((resolve2, reject2) => {
-                  done = shared.callbackPromise(resolve2, reject2);
+                promise = new Promise((resolve3, reject2) => {
+                  done = shared.callbackPromise(resolve3, reject2);
                 });
               }
               this._responseActions.push((str) => {
@@ -7980,11 +7980,11 @@ var require_smtp_connection = __commonJS({
               setImmediate(() => this._sendCommand(cmd));
               return promise;
             },
-            resolve,
+            resolve: resolve2,
             reject
           });
           if (handlerResponse && typeof handlerResponse.catch === "function") {
-            handlerResponse.then(resolve).catch(reject);
+            handlerResponse.then(resolve2).catch(reject);
           }
           return;
         }
@@ -10695,8 +10695,8 @@ var require_smtp_pool = __commonJS({
       verify(callback) {
         let promise;
         if (!callback) {
-          promise = new Promise((resolve, reject) => {
-            callback = shared.callbackPromise(resolve, reject);
+          promise = new Promise((resolve2, reject) => {
+            callback = shared.callbackPromise(resolve2, reject);
           });
         }
         const auth = new PoolResource(this).auth;
@@ -11043,8 +11043,8 @@ var require_smtp_transport = __commonJS({
       verify(callback) {
         let promise;
         if (!callback) {
-          promise = new Promise((resolve, reject) => {
-            callback = shared.callbackPromise(resolve, reject);
+          promise = new Promise((resolve2, reject) => {
+            callback = shared.callbackPromise(resolve2, reject);
           });
         }
         this.getSocket(this.options, (err, socketOptions) => {
@@ -11697,8 +11697,8 @@ var require_ses_transport = __commonJS({
       verify(callback) {
         let promise;
         if (!callback) {
-          promise = new Promise((resolve, reject) => {
-            callback = shared.callbackPromise(resolve, reject);
+          promise = new Promise((resolve2, reject) => {
+            callback = shared.callbackPromise(resolve2, reject);
           });
         }
         const cb = (err) => {
@@ -11799,8 +11799,8 @@ var require_nodemailer = __commonJS({
         apiUrl = false;
       }
       if (!callback) {
-        promise = new Promise((resolve, reject) => {
-          callback = shared.callbackPromise(resolve, reject);
+        promise = new Promise((resolve2, reject) => {
+          callback = shared.callbackPromise(resolve2, reject);
         });
       }
       if (ETHEREAL_CACHE && testAccount) {
@@ -11877,15 +11877,13 @@ var require_nodemailer = __commonJS({
 });
 
 // src/cli.ts
-import { readFileSync, realpathSync } from "fs";
+import { readFileSync, realpathSync as realpathSync2 } from "fs";
 import { fileURLToPath } from "url";
 import { parseArgs } from "util";
 
 // src/services/smtpMailer.ts
 var import_nodemailer = __toESM(require_nodemailer(), 1);
 import { execFileSync } from "child_process";
-import { isAbsolute } from "path";
-import { existsSync } from "fs";
 
 // src/utils/attachmentLimits.ts
 var MAX_INLINE_ATTACHMENT_BYTES = 25 * 1024 * 1024;
@@ -11910,6 +11908,99 @@ function decodeInlineAttachment(contentBase64) {
   return content;
 }
 
+// src/utils/attachmentReadPolicy.ts
+import { realpathSync, statSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { delimiter, isAbsolute, join, resolve, sep } from "path";
+var ATTACHMENT_READ_ROOTS_ENV = "APPLE_MAIL_MCP_ATTACHMENT_READ_ROOTS";
+var DEFAULT_ATTACHMENT_READ_ROOTS = [homedir(), "/Volumes", tmpdir(), "/tmp", "/private/tmp"];
+var SENSITIVE_HOME_ROOTS = [
+  join(homedir(), ".ssh"),
+  join(homedir(), ".aws"),
+  join(homedir(), ".config", "gh"),
+  join(homedir(), "Library", "Keychains")
+];
+function canonicalize(path) {
+  return realpathSync.native(path);
+}
+function sensitiveRoots() {
+  return SENSITIVE_HOME_ROOTS.map((root) => {
+    try {
+      return canonicalize(root);
+    } catch {
+      return root;
+    }
+  });
+}
+function isWithinRoot(candidate, root) {
+  return candidate === root || candidate.startsWith(root + sep);
+}
+function hasHiddenPathSegment(candidate) {
+  return candidate.split(sep).some((segment) => segment.startsWith(".") && segment.length > 1);
+}
+function isProtectedPath(candidate) {
+  if (hasHiddenPathSegment(candidate)) return true;
+  if (sensitiveRoots().some((root) => isWithinRoot(candidate, root))) return true;
+  let home;
+  try {
+    home = canonicalize(homedir());
+  } catch {
+    home = resolve(homedir());
+  }
+  if (!isWithinRoot(candidate, home)) return false;
+  const relative = candidate.slice(home.length).split(sep).filter(Boolean);
+  return relative.length >= 4 && relative[0].toLowerCase() === "library" && relative[1].toLowerCase() === "application support" && relative.at(-1)?.toLowerCase() === "config.json";
+}
+function configuredRoots(env) {
+  const raw = env[ATTACHMENT_READ_ROOTS_ENV];
+  const extraRoots = raw === void 0 ? [] : raw.split(delimiter).map((root) => root.trim()).filter(Boolean);
+  const requested = [...DEFAULT_ATTACHMENT_READ_ROOTS, ...extraRoots];
+  for (const root of requested) {
+    if (!isAbsolute(root)) {
+      throw new Error(`${ATTACHMENT_READ_ROOTS_ENV} entries must be absolute paths.`);
+    }
+  }
+  const resolved = [];
+  for (const root of requested) {
+    try {
+      const canonical = canonicalize(resolve(root));
+      if (!resolved.includes(canonical)) resolved.push(canonical);
+    } catch {
+    }
+  }
+  return resolved;
+}
+function resolveAttachmentReadPath(filePath, env = process.env) {
+  if (!isAbsolute(filePath)) {
+    throw new Error(`Attachment path must be absolute: "${filePath}"`);
+  }
+  let canonical;
+  try {
+    canonical = canonicalize(filePath);
+  } catch {
+    throw new Error(`Attachment file not found: "${filePath}"`);
+  }
+  try {
+    if (!statSync(canonical).isFile()) {
+      throw new Error(`Attachment path is not a regular file: "${filePath}"`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not a regular file")) throw error;
+    throw new Error(`Attachment file not found: "${filePath}"`);
+  }
+  if (isProtectedPath(canonical)) {
+    throw new Error(
+      `Attachment path is in a protected location: "${filePath}". Hidden files and credential/configuration locations cannot be sent as attachments.`
+    );
+  }
+  if (!configuredRoots(env).some((root) => isWithinRoot(canonical, root))) {
+    throw new Error(
+      `Attachment path is outside the allowed read roots: "${filePath}". Use an ordinary home-directory, /Volumes, or temporary path, or configure ${ATTACHMENT_READ_ROOTS_ENV} for an additional explicit root.`
+    );
+  }
+  return canonical;
+}
+
 // src/utils/docsUrls.ts
 var SETUP_GUIDE_URL = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
 var SETUP_HINT = `Setup guide: ${SETUP_GUIDE_URL} \u2014 run the "doctor" tool to check your setup.`;
@@ -11919,6 +12010,7 @@ var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
   secure: "APPLE_MAIL_MCP_SMTP_SECURE",
+  allowPlaintext: "APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT",
   user: "APPLE_MAIL_MCP_SMTP_USER",
   from: "APPLE_MAIL_MCP_SMTP_FROM",
   allowedFrom: "APPLE_MAIL_MCP_SMTP_ALLOWED_FROM",
@@ -11969,15 +12061,23 @@ function resolveSmtpConfig(env = process.env) {
       `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}". ` + SETUP_HINT
     );
   }
-  return { host, port, secure, user, pass, from, allowedFrom };
+  const allowPlaintext = /^(1|true|yes|on)$/i.test(env[SMTP_ENV.allowPlaintext]?.trim() ?? "");
+  return {
+    host,
+    port,
+    secure,
+    allowPlaintext,
+    user,
+    pass,
+    from,
+    allowedFrom
+  };
 }
 function buildAttachments(attachments) {
   if (!attachments || attachments.length === 0) return void 0;
   return attachments.map((a) => {
     if (typeof a === "string") {
-      if (!isAbsolute(a)) throw new Error(`Attachment path must be absolute: "${a}"`);
-      if (!existsSync(a)) throw new Error(`Attachment file not found: "${a}"`);
-      return { path: a };
+      return { path: resolveAttachmentReadPath(a) };
     }
     if (!a.filename || !a.contentBase64) {
       throw new Error("Inline attachment requires both filename and contentBase64.");
@@ -12008,10 +12108,19 @@ async function sendViaSmtp(opts, config, createTransport = import_nodemailer.def
   } catch (error) {
     return { success: false, error: error instanceof Error ? error.message : String(error) };
   }
+  const requireTLS = !cfg.secure && !cfg.allowPlaintext;
+  if (!cfg.secure && cfg.allowPlaintext) {
+    console.warn(
+      `SMTP plaintext explicitly enabled via ${SMTP_ENV.allowPlaintext}; credentials and message content may be exposed.`
+    );
+  }
   const transporter = createTransport({
     host: cfg.host,
     port: cfg.port,
     secure: cfg.secure,
+    // Port 587/143-style configurations must not silently downgrade to
+    // plaintext when the server advertises no usable TLS upgrade.
+    requireTLS,
     auth: { user: cfg.user, pass: cfg.pass }
   });
   const html = opts.htmlBody?.trim() ? opts.htmlBody : void 0;
@@ -12032,9 +12141,11 @@ async function sendViaSmtp(opts, config, createTransport = import_nodemailer.def
     });
     return { success: true, messageId: info.messageId };
   } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const tlsHint = requireTLS ? ` STARTTLS is required for non-implicit TLS; to explicitly allow plaintext (not recommended), set ${SMTP_ENV.allowPlaintext}=1.` : "";
     return {
       success: false,
-      error: `SMTP send failed: ${error instanceof Error ? error.message : String(error)}`
+      error: `SMTP send failed: ${detail}.${tlsHint}`
     };
   } finally {
     transporter.close();
@@ -12149,7 +12260,7 @@ async function runCli(argv, deps = {}) {
 function isInvokedDirectly() {
   if (typeof process === "undefined" || !process.argv?.[1]) return false;
   try {
-    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    return realpathSync2(process.argv[1]) === fileURLToPath(import.meta.url);
   } catch {
     return false;
   }