@ni-c/imap-mcp 0.3.0 → 0.5.0

package/README.md

@@ -1,14 +1,19 @@
 # imap-mcp
 
+<!-- badges: start -->
+
 [![CI](https://img.shields.io/github/actions/workflow/status/ni-c/imap-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/imap-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/imap-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/imap-mcp)
+<a href="https://socket.dev/npm/package/@ni-c/imap-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/imap-mcp" alt="Socket supply-chain report" height="20"></a>
+[![Glama score](https://glama.ai/mcp/servers/ni-c/imap-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/imap-mcp)
+<br>
 [![npm version](https://img.shields.io/npm/v/%40ni-c%2Fimap-mcp)](https://www.npmjs.com/package/@ni-c/imap-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/%40ni-c%2Fimap-mcp)](https://www.npmjs.com/package/@ni-c/imap-mcp)
-[![node](https://img.shields.io/node/v/%40ni-c%2Fimap-mcp)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/%40ni-c%2Fimap-mcp)](LICENSE)
-[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Fimap--mcp-blue)](https://github.com/ni-c/imap-mcp/pkgs/container/imap-mcp)
-[![docs](https://img.shields.io/badge/docs-imap--mcp.ni--c.de-informational)](https://imap-mcp.ni-c.de)
-[![HTTP • via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-6f42c1)](https://mcp-hub.ni-c.de)
+[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fimap--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/imap-mcp/pkgs/container/imap-mcp)
+[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
+<br>
+[![docs](https://img.shields.io/badge/docs-imap--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://imap-mcp.ni-c.de)
 [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+<!-- badges: end -->
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for any IMAP
 mailbox. It speaks IMAP rather than one vendor's API, so it works with whatever provider you
@@ -116,6 +121,7 @@ guard. See [Asking a person](https://imap-mcp.ni-c.de/guide/approval).
 | `IMAP_MAX_MESSAGES`         | no       | `100`         | Default page size                                            |
 | `IMAP_MAX_ATTACHMENT_BYTES` | no       | `1048576`     | Ceiling for returning an attachment inline                   |
 | `IMAP_MAX_DOWNLOAD_BYTES`   | no       | `26214400`    | Ceiling for writing one to disk                              |
+| `IMAP_MAX_EXTRACT_BYTES`    | no       | `10485760`    | Ceiling for reading a document's text; max `67108864`        |
 | `IMAP_ATTACHMENT_TYPES`     | no       | see below     | Comma-separated content-type allowlist                       |
 | `IMAP_DOWNLOAD_DIR`         | no       | —             | Setting it allows saving attachments there                   |
 | `IMAP_INSECURE_TLS`         | no       | `false`       | Exactly `true` accepts a self-signed certificate             |
@@ -143,6 +149,10 @@ IMAP_ALLOW_TOOLS=list_new_messages,get_message,move_messages
 IMAP_DENY_TOOLS=delete_messages
 ```
 
+One boundary the list cannot draw: `move_messages` copies as well as moves (`mode: "copy"`),
+and the two are one tool. Denying `move_messages` removes both; there is no way to keep moving
+and forbid copying, or the other way round. Both modes ask for confirmation.
+
 An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a
 tool — an absent tool is not something anyone traces back to an environment variable. A
 filtered tool is never registered, so it is absent from `tools/list` and unknown to
@@ -155,8 +165,11 @@ answer — its `/hub` endpoint replaces every server's tools with six meta-tools
 The password is deleted from the process environment as soon as it is read, so it is not
 visible to child processes or in `/proc/<pid>/environ`.
 
-Without `IMAP_DOWNLOAD_DIR` this server never writes to the filesystem. The two size limits are
-separate on purpose: one protects the model's context window, the other protects your disk.
+Without `IMAP_DOWNLOAD_DIR` this server never writes to the filesystem. The three size limits are
+separate on purpose, because they answer three different questions:
+`IMAP_MAX_ATTACHMENT_BYTES` protects the model's context window,
+`IMAP_MAX_DOWNLOAD_BYTES` protects your disk, and `IMAP_MAX_EXTRACT_BYTES` bounds how much
+hostile input one parser is handed. Raising any one of them is not a request to raise the others.
 
 The server starts without credentials on purpose — it completes the handshake and lists its
 tools, and every call then fails with setup instructions instead of reaching a server.
@@ -259,7 +272,7 @@ are in the [client guide](https://imap-mcp.ni-c.de/guide/clients#through-mcp-hub
 | `list_messages`     | Lists and searches: sender, recipient, subject, body, date range, flags                  |
 | `list_new_messages` | Messages not handed over yet; marks them afterwards, `dry_run` to preview                |
 | `get_message`       | Headers and body, fenced untrusted, plus the security assessment; `include_thread`       |
-| `get_attachments`   | Without `part_id` lists them, with `part_id` reads or saves one                          |
+| `get_attachments`   | Without `part_id` lists them, with `part_id` reads, extracts or saves one                |
 
 **Mailbox** — needs `IMAP_READ_ONLY=false`
 
@@ -326,7 +339,8 @@ size limit and magic-byte check as the tool — it is not a second, unguarded do
 ## Not exposed, on purpose
 
 No sending, no SMTP, no raw IMAP passthrough, no `APPEND` of arbitrary MIME, no HTML
-composition, no OAuth2. The first is the whole security argument (see `SECURITY.md`); the
+composition, no OAuth2, and **no OCR** — a scanned PDF has no text to extract and says so
+rather than guessing. The first is the whole security argument (see `SECURITY.md`); the
 second would make every guard here optional; the last is planned but needs a test account
 before it ships.
 
@@ -346,6 +360,17 @@ knowing before concluding that a filtered install reaches less of the mailbox th
   saving to disk, where it would be more dangerous, not less.
 - **A `part_id` must come from a listing call**, so the body cannot be pulled out through the
   attachment tool and escape its framing.
+- **Documents are parsed in a process that can be killed.** `mode: "text"` reads a PDF or
+  Office file with a bundled PDF.js and a ZIP reader — the only place this server parses a
+  binary a stranger sent. It runs in a child process with a heap limit and a timeout, its
+  stdout discarded rather than shared with the JSON-RPC transport, PDF.js's `eval` support
+  off, compressed streams measured against a ceiling _before_ PDF.js inflates them, and an
+  entry allowlist that decides what is decompressed _before_ the buffer is sized. Nothing in
+  that path touches the network or the filesystem.
+- **Extracted text says what it is.** Extraction returns every text-drawing instruction in a
+  file, including text set below one point or drawn in the colour of the paper, and returns
+  nothing that was drawn as a picture. The result says so above the fence, because "the
+  document says X" is otherwise a claim the user has no way to check.
 - **Downloads cannot escape their directory.** The target comes only from the environment, the
   filename is sanitised, the resolved path is re-checked, and the file is opened with `wx` and
   mode `0600` — so nothing is overwritten and no planted symlink is followed.

package/dist/analyze.d.ts

@@ -23,13 +23,33 @@ export interface SecurityAssessment {
     };
 }
 /**
- * Extracts readable text from HTML.
+ * Extracts readable text from HTML — and from the XML inside an OOXML or
+ * OpenDocument attachment, which is the same problem with different tag names.
+ *
+ * Reused there rather than reimplemented, and that is a security decision, not
+ * a tidiness one. The obvious `document.xml` reader is
+ * `/<w:t[^>]*>([\s\S]*?)<\/w:t>/g` — which is the exact shape of the bug
+ * recorded above this function: *n* start tokens each paying for a scan that
+ * never finds its end. A `document.xml` of `'<w:t '` repeated 200 000 times is
+ * a tiny, deflate-friendly ZIP entry. This walk is immune for the reason it was
+ * written, so the second parser is the one not to write.
+ *
+ * It is also why nothing here parses XML properly. A real parser resolves
+ * entities, and would hand a mail attachment billion-laughs expansion and an
+ * `<!ENTITY … SYSTEM "file:///etc/passwd">` that reads a file. Those are not
+ * defended against below; they are simply not implemented. `&lol9;` comes out
+ * as six literal characters, and it must stay that way — reaching for
+ * `fast-xml-parser` here would reintroduce all three at once.
  *
  * Deliberately not `mailparser`'s own `text` fallback: that keeps content the
  * recipient never sees. Anything hidden by inline CSS is a place to park an
  * instruction meant only for the model, so those elements are dropped before
  * the tags are stripped.
  *
+ * `maxChars` overrides the input slice. The default suits a mail body; a
+ * document part needs more, because OOXML spends most of its bytes on
+ * formatting and the readable text is a small fraction of it.
+ *
  * This is one pass over the input. The cursors below only ever move forward,
  * which is the property that makes the whole function linear no matter what the
  * sender writes: a start token that is never closed is answered once and then
@@ -40,7 +60,8 @@ export interface SecurityAssessment {
  * for the same reason it always was: nothing downstream trusts the stripping,
  * and the fencing in {@link wrapUntrusted} is what carries the weight.
  */
-export declare function htmlToText(html: string): string;
+export declare function htmlToText(html: string, maxChars?: number): string;
+export declare function decodeCharacterReferences(text: string): string;
 /**
  * Removes the characters a human reader cannot see but the model can.
  *
@@ -74,7 +95,16 @@ export declare function escapeInvisible(input: string): string;
  * normalising would miss it.
  */
 export declare function sanitizeText(input: string, maxChars?: number): string;
-/** Names of the injection shapes present in `text`. */
+/**
+ * Names of the injection shapes present in `text`.
+ *
+ * Runs in this process on text the sender wrote, up to a million characters
+ * of it for an extracted document — after the parser child has exited, so no
+ * timeout covers it. Every pattern above therefore has to be linear on a
+ * hostile repetition of its own trigger, and `analyze.test.ts` times each one
+ * on such input. A new pattern gets a line in that test before it gets a line
+ * in the list.
+ */
 export declare function detectSuspicious(text: string): string[];
 /**
  * Words that mix Latin with Cyrillic or Greek letters.

package/dist/analyze.js

@@ -45,9 +45,18 @@ const INJECTION_PATTERNS = [
         'role-injection',
         /(?:^|[-\u2014|>\])]\s{0,3})(system|assistant|developer)\s*:/im,
     ],
+    // Anchored at the start of the run. Without the lookbehind, `-{3,}` was
+    // tried from every position inside a run and backtracked once per possible
+    // length each time, which is quadratic on text that is nothing but hyphens:
+    // 40 000 of them took 1.5 s, and the million characters an extracted
+    // document may carry would have held this process — the whole server, its
+    // transport is stdio — for a quarter of an hour. A few kilobytes on the
+    // wire. With it, a run is one attempt from its first character and the
+    // positions inside it fail in constant time: a million hyphens in 5 ms,
+    // and a delimiter of any length is still found.
     [
         'fake-delimiter',
-        /(-{3,}|={3,}|#{3,})\s*(begin|end|system|instruction|prompt)/i,
+        /(?<![-=#])(-{3,}|={3,}|#{3,})\s*(begin|end|system|instruction|prompt)/i,
     ],
     [
         'tool-coercion',
@@ -115,7 +124,16 @@ const MAX_HIDDEN_ELEMENT_CHARS = 10_000;
  */
 const CLOSER_SCAN_BUDGET_FACTOR = 4;
 const CLOSER_SCAN_BUDGET_FLOOR = 100_000;
-/** Elements whose content the recipient never reads. */
+/**
+ * Elements whose content the recipient never reads.
+ *
+ * The `w:`-prefixed names are WordprocessingML, not HTML: this walk is also how
+ * the text of a .docx attachment is read. A Word field code
+ * (`INCLUDEPICTURE "http://…"`, a DDE command) is markup the reader never sees
+ * for exactly the same reason a `<script>` body is, and `w:delText` is text a
+ * tracked change deleted — shown struck through at most, and not at all in the
+ * view a document is read in.
+ */
 const NON_CONTENT_TAGS = new Set([
     'script',
     'style',
@@ -123,8 +141,16 @@ const NON_CONTENT_TAGS = new Set([
     'title',
     'noscript',
     'template',
+    'w:instrtext',
+    'w:deltext',
 ]);
-/** Closing tags that end a visual block, and so earn a line break. */
+/**
+ * Closing tags that end a visual block, and so earn a line break.
+ *
+ * The namespaced names are the OOXML and OpenDocument paragraph, heading and
+ * row elements. Without them a whole .docx comes back as one line, because
+ * nothing else in a document part ever closes a block.
+ */
 const BLOCK_TAGS = new Set([
     'p',
     'div',
@@ -136,8 +162,19 @@ const BLOCK_TAGS = new Set([
     'h4',
     'h5',
     'h6',
+    'w:p',
+    'w:tr',
+    'a:p',
+    'text:p',
+    'text:h',
+    'table:table-row',
 ]);
-const TAG_NAME = /^<\/?([A-Za-z][A-Za-z0-9]*)/;
+// The name may carry a namespace prefix and a hyphen: `</w:p>`, `</text:h>`,
+// `</table:table-row>`. Without the colon and the hyphen this matched `w` for
+// `</w:p>`, so every namespaced entry in the sets above would be dead code.
+// HTML is unaffected — no HTML element name contains either character, and a
+// custom element (`<my-widget>`) is in none of the sets under either reading.
+const TAG_NAME = /^<\/?([A-Za-z][A-Za-z0-9:_.-]*)/;
 const BR_TAG = /^<br\s*\/?$/i;
 const STYLE_ATTRIBUTE = /style\s*=\s*("|')/gi;
 const HIDDEN_VALUE = /display\s*:\s*none|visibility\s*:\s*hidden|opacity\s*:\s*0|font-size\s*:\s*0/i;
@@ -164,13 +201,33 @@ function hasHiddenStyle(tag) {
     return false;
 }
 /**
- * Extracts readable text from HTML.
+ * Extracts readable text from HTML — and from the XML inside an OOXML or
+ * OpenDocument attachment, which is the same problem with different tag names.
+ *
+ * Reused there rather than reimplemented, and that is a security decision, not
+ * a tidiness one. The obvious `document.xml` reader is
+ * `/<w:t[^>]*>([\s\S]*?)<\/w:t>/g` — which is the exact shape of the bug
+ * recorded above this function: *n* start tokens each paying for a scan that
+ * never finds its end. A `document.xml` of `'<w:t '` repeated 200 000 times is
+ * a tiny, deflate-friendly ZIP entry. This walk is immune for the reason it was
+ * written, so the second parser is the one not to write.
+ *
+ * It is also why nothing here parses XML properly. A real parser resolves
+ * entities, and would hand a mail attachment billion-laughs expansion and an
+ * `<!ENTITY … SYSTEM "file:///etc/passwd">` that reads a file. Those are not
+ * defended against below; they are simply not implemented. `&lol9;` comes out
+ * as six literal characters, and it must stay that way — reaching for
+ * `fast-xml-parser` here would reintroduce all three at once.
  *
  * Deliberately not `mailparser`'s own `text` fallback: that keeps content the
  * recipient never sees. Anything hidden by inline CSS is a place to park an
  * instruction meant only for the model, so those elements are dropped before
  * the tags are stripped.
  *
+ * `maxChars` overrides the input slice. The default suits a mail body; a
+ * document part needs more, because OOXML spends most of its bytes on
+ * formatting and the readable text is a small fraction of it.
+ *
  * This is one pass over the input. The cursors below only ever move forward,
  * which is the property that makes the whole function linear no matter what the
  * sender writes: a start token that is never closed is answered once and then
@@ -181,8 +238,8 @@ function hasHiddenStyle(tag) {
  * for the same reason it always was: nothing downstream trusts the stripping,
  * and the fencing in {@link wrapUntrusted} is what carries the weight.
  */
-export function htmlToText(html) {
-    const source = html.slice(0, MAX_HTML_CHARS);
+export function htmlToText(html, maxChars = MAX_HTML_CHARS) {
+    const source = html.slice(0, maxChars);
     const out = [];
     // Forward-only cursors. Each call may advance them, never rewind them, so
     // across the whole document each scans the input at most once — the same
@@ -281,16 +338,47 @@ export function htmlToText(html) {
         }
         i = gt + 1;
     }
-    return (out
-        .join('')
-        .replace(/&nbsp;/gi, ' ')
-        .replace(/&lt;/gi, '<')
-        .replace(/&gt;/gi, '>')
-        .replace(/&quot;/gi, '"')
-        .replace(/&#39;/g, "'")
-        // Last, so a decoded `&amp;lt;` does not turn into a `<` the caller never
-        // received.
-        .replace(/&amp;/gi, '&'));
+    return decodeCharacterReferences(out.join(''));
+}
+/**
+ * The character references a mail client decodes, decoded the way it does.
+ *
+ * One alternation, one pass. It used to be six `replace` calls in sequence,
+ * and a sequence decodes twice: `&#x26;#104;` became `&#104;` in the hex pass
+ * and `h` in the decimal pass, a character no client ever shows. And the digit
+ * runs were bounded (`{1,7}`) with the semicolon required, while the HTML
+ * tokenizer reads *every* digit and takes the semicolon as optional — so
+ * `&#0000000104;` reached the model as eleven literal characters and the
+ * recipient as an `h`. Here a numeric reference is any digit run, with or
+ * without its semicolon; the named ones are the five HTML mail and OOXML use.
+ *
+ * Out-of-range values, zero and surrogates decode to U+FFFD, which is what a
+ * browser renders — a character, and not `''`, which would make `&#0;` an
+ * invisible separator inside a word.
+ */
+const CHARACTER_REFERENCE = /&(?:#[xX]([0-9a-fA-F]+);?|#([0-9]+);?|(nbsp|lt|gt|quot|amp|apos);)/g;
+export function decodeCharacterReferences(text) {
+    return text.replace(CHARACTER_REFERENCE, (_match, hex, decimal, name) => hex !== undefined
+        ? fromCodePoint(parseInt(hex, 16))
+        : decimal !== undefined
+            ? fromCodePoint(Number(decimal))
+            : (NAMED_REFERENCES.get(String(name).toLowerCase()) ?? _match));
+}
+const NAMED_REFERENCES = new Map([
+    ['nbsp', ' '],
+    ['lt', '<'],
+    ['gt', '>'],
+    ['quot', '"'],
+    ['amp', '&'],
+    ['apos', "'"],
+]);
+/** One character from a numeric reference, U+FFFD where no client has one. */
+function fromCodePoint(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 0x10ffff)
+        return String.fromCodePoint(0xfffd);
+    if (value >= 0xd800 && value <= 0xdfff)
+        return String.fromCodePoint(0xfffd);
+    return String.fromCodePoint(value);
 }
 /**
  * Removes the characters a human reader cannot see but the model can.
@@ -312,8 +400,13 @@ export function stripInvisible(input) {
  * not the `Archive` they know.
  */
 export function escapeInvisible(input) {
-    const escape = (match) => `\\u${match.codePointAt(0).toString(16).padStart(4, '0')}`;
-    return input.replace(INVISIBLE_CHARS, escape).replace(CONTROL_CHARS, escape);
+    return input
+        .replace(INVISIBLE_CHARS, escapeCodePoint)
+        .replace(CONTROL_CHARS, escapeCodePoint);
+}
+/** One character as a Unicode escape, for `escapeInvisible`. */
+function escapeCodePoint(match) {
+    return `\\u${match.codePointAt(0).toString(16).padStart(4, '0')}`;
 }
 /**
  * Normalises text before it reaches the model: Unicode-folded, stripped of the
@@ -334,11 +427,24 @@ export function sanitizeText(input, maxChars = MAX_BODY_CHARS) {
         .replace(/[ \t]+/g, ' ')
         .replace(/\n{3,}/g, '\n\n')
         .trim();
-    return normalized.length > maxChars
+    // `toWellFormed` after the cut, which can split a surrogate pair — and on
+    // the whole string either way, because a lone surrogate can arrive decoded
+    // out of a header. JSON carries one as an escape and a Python client then
+    // fails to encode it; U+FFFD is the honest rendering.
+    return (normalized.length > maxChars
         ? `${normalized.slice(0, maxChars)}\n… (truncated at ${maxChars} characters)`
-        : normalized;
+        : normalized).toWellFormed();
 }
-/** Names of the injection shapes present in `text`. */
+/**
+ * Names of the injection shapes present in `text`.
+ *
+ * Runs in this process on text the sender wrote, up to a million characters
+ * of it for an extracted document — after the parser child has exited, so no
+ * timeout covers it. Every pattern above therefore has to be linear on a
+ * hostile repetition of its own trigger, and `analyze.test.ts` times each one
+ * on such input. A new pattern gets a line in that test before it gets a line
+ * in the list.
+ */
 export function detectSuspicious(text) {
     return INJECTION_PATTERNS.filter(([, pattern]) => pattern.test(text)).map(([name]) => name);
 }
@@ -401,7 +507,13 @@ export function parseAuthResults(header, trustedAuthservId) {
         const match = new RegExp(`\\b${name}=([a-z]+)`, 'i').exec(topmost);
         return match?.[1]?.toLowerCase() ?? 'unknown';
     };
-    const authservId = /^\s*([A-Za-z0-9._-]+)/.exec(topmost ?? '')?.[1];
+    // Bounded like a hostname, which is what an authserv-id is. Unbounded, the
+    // id went into the metadata block beside the fence — the one part of a
+    // `get_message` answer with its own budget and nothing array-shaped to
+    // shrink — and a header of sixty thousand letters made the whole message
+    // unreadable through this server. The verdict is what matters; an id past
+    // this length is not an id, and the header is reported as forgeable.
+    const authservId = /^\s*([A-Za-z0-9._-]{1,253})(?![A-Za-z0-9._-])/.exec(topmost ?? '')?.[1];
     return {
         spf: read('spf'),
         dkim: read('dkim'),

package/dist/attachments.d.ts

@@ -10,6 +10,7 @@ import type { MessageStructureObject } from 'imapflow';
  * about reading the two declarations side by side says which is which.
  */
 export declare const EXECUTABLE_EXTENSIONS: Set<string>;
+export declare function isMediaType(value: string): boolean;
 export interface AttachmentCandidate {
     partId: string;
     filename: string;
@@ -24,7 +25,18 @@ export interface AttachmentCandidate {
 }
 export interface AttachmentPolicy {
     allowedTypes: string[];
+    /**
+     * Size ceiling for the destination this check is for.
+     *
+     * Per destination, because there are three of them and they answer different
+     * questions: what may enter the model's context, what may be written to disk,
+     * what a parser may be handed. The caller picks the number; naming it here
+     * keeps the refusal pointing at the variable an operator would actually
+     * change.
+     */
     maxBytes: number;
+    /** Environment variable behind {@link maxBytes}, for the refusal text. */
+    maxBytesName: string;
 }
 /**
  * Strips a filename down to something safe to print and to reason about.

package/dist/attachments.js

@@ -117,6 +117,22 @@ export const EXECUTABLE_EXTENSIONS = new Set([
  * extensions render it as `invoice.pdf`.
  */
 const DOUBLE_EXTENSION_BAIT = /\.(pdf|docx?|xlsx?|pptx?|txt|csv|jpe?g|png|gif|zip|rtf|odt|ods)\.[a-z0-9]{1,5}$/i;
+/**
+ * The shape of a media type — RFC 6838's token characters, bounded on both
+ * sides of the slash.
+ *
+ * The declared type of a part is the sender's string, and it used to travel
+ * as it came: into `content_type`, into the refusal note that quotes it, and
+ * from there into the `get_message` metadata block outside the fence and into
+ * error results the budget never measures. A hundred kilobytes of it in one
+ * `Content-Type` header made the message unreadable. Anything that does not
+ * match here is not a media type, is never on the allowlist, and is reported
+ * as `application/octet-stream` with a note that says so without quoting it.
+ */
+const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]{1,127}\/[a-z0-9!#$&^_.+-]{1,127}$/;
+export function isMediaType(value) {
+    return MEDIA_TYPE.test(value);
+}
 /**
  * Strips a filename down to something safe to print and to reason about.
  *
@@ -127,11 +143,30 @@ const DOUBLE_EXTENSION_BAIT = /\.(pdf|docx?|xlsx?|pptx?|txt|csv|jpe?g|png|gif|zi
 export function sanitizeFilename(raw) {
     if (raw === undefined || raw.trim() === '')
         return '(unnamed)';
+    // Two orderings matter here, and both were wrong.
+    //
+    // The trim runs *before* the leading dots are taken off, and again after. The
+    // other way round, one space defeated the rule: ` .bashrc` has no dot in
+    // first position when the strip runs, and the trim that followed exposed it,
+    // so the name reached the model looking like a dotfile after all.
+    //
+    // And the strip never takes the dot that carries the extension. It used to:
+    // `.exe` came out as `exe`, `extensionOf` then answered `''`, and an empty
+    // extension makes `checkPolicy` skip the executable check entirely rather
+    // than fail it — so the blocklist was bypassed by naming the attachment
+    // `.exe`. That is the same failure `appref-ms` caused, reached by a different
+    // route. The lookahead keeps the leading dots whenever removing them would
+    // consume the last one; a name that has another dot further along loses them
+    // as before.
     const cleaned = defuseAutoFetch(stripInvisible(raw.normalize('NFKC')))
         .replace(/[/\\]/g, '_')
-        .replace(/^\.+/, '')
+        .trim()
+        .replace(/^\.+(?=.*\.)/, '')
         .trim();
-    if (cleaned === '')
+    // A name of nothing but dots is not a name. It carries no extension either,
+    // so keeping it buys the check above nothing and only puts `...` in front of
+    // a reader.
+    if (cleaned === '' || /^\.+$/.test(cleaned))
         return '(unnamed)';
     return cleaned.length > MAX_FILENAME_LENGTH
         ? `${cleaned.slice(0, MAX_FILENAME_LENGTH)}…`
@@ -178,7 +213,10 @@ function walk(node, depth, found) {
             walk(child, depth + 1, found);
         return;
     }
-    const type = (node.type ?? 'application/octet-stream').toLowerCase();
+    const declaredType = (node.type ?? 'application/octet-stream').toLowerCase();
+    const type = isMediaType(declaredType)
+        ? declaredType
+        : 'application/octet-stream';
     const disposition = node.disposition?.toLowerCase();
     const declaredName = node.dispositionParameters?.filename ?? node.parameters?.name;
     // A part is an attachment when it says so, or when it carries a filename, or
@@ -191,6 +229,9 @@ function walk(node, depth, found) {
         return;
     const filename = sanitizeFilename(declaredName);
     const notes = [];
+    if (type !== declaredType) {
+        notes.push('the declared content type is not a valid media type and is reported as application/octet-stream');
+    }
     if (declaredName !== undefined && DOUBLE_EXTENSION_BAIT.test(declaredName)) {
         notes.push('filename has a double extension — it renders as a document but is not one');
     }
@@ -198,7 +239,13 @@ function walk(node, depth, found) {
         partId: node.part,
         filename,
         contentType: type,
-        size: node.size,
+        // imapflow reads the size with `Number(value) || 0`, so a server that
+        // writes `1e400` hands over Infinity — which JSON renders as null, and
+        // null fails the `size: number` the output schema promises for the whole
+        // listing. A size that is not a safe non-negative integer is unknown.
+        size: Number.isSafeInteger(node.size) && node.size >= 0
+            ? node.size
+            : undefined,
         disposition,
         allowed: true,
         notes,
@@ -225,7 +272,7 @@ export function checkPolicy(candidate, policy) {
     }
     if (candidate.size !== undefined && candidate.size > policy.maxBytes) {
         allowed = false;
-        notes.push(`refused: declared size ${candidate.size} exceeds IMAP_MAX_ATTACHMENT_BYTES (${policy.maxBytes})`);
+        notes.push(`refused: declared size ${candidate.size} exceeds ${policy.maxBytesName} (${policy.maxBytes})`);
     }
     return { ...candidate, allowed, notes };
 }

package/dist/config.d.ts

@@ -31,9 +31,27 @@ export interface ImapConfig {
      * Where attachments may be written. Unset means this server never touches the
      * filesystem — setting it is the opt-in, and it is the only source of the
      * target directory. A caller cannot choose where bytes from a stranger land.
+     *
+     * Stored as the resolved real path of a directory that existed at startup.
+     * The value is printed by `get_server_info` and by every attachment listing,
+     * and `IMAP_DOWNLOAD_DIR` sits a few lines below `IMAP_PASSWORD` in every
+     * compose file — so a value that is not a directory is refused before it can
+     * be printed anywhere, and the refusal describes it by length, never by
+     * content.
      */
     downloadDir: string | undefined;
     maxDownloadBytes: number;
+    /**
+     * Ceiling on the bytes handed to the text-extraction worker.
+     *
+     * A third limit because it answers a third question. `maxAttachmentBytes`
+     * bounds what may enter the model's context — extraction does not, since only
+     * the extracted text comes back and `max_chars` bounds that. `maxDownloadBytes`
+     * bounds what may be written to the filesystem. This one bounds how much
+     * hostile input a parser is asked to chew on inside a thread that can be
+     * terminated, which is a memory question and neither of the other two.
+     */
+    maxExtractBytes: number;
 }
 export interface Config {
     imap: ImapConfig;