@ni-c/imap-mcp 0.3.0 → 0.5.0

package/dist/config.js

@@ -1,3 +1,6 @@
+import { realpathSync, statSync } from 'node:fs';
+import { isMediaType } from './attachments.js';
+import { MAILBOX_CONTROL_CHARS } from './schema.js';
 export const DEFAULT_ATTACHMENT_TYPES = [
     'application/pdf',
     'application/json',
@@ -23,7 +26,31 @@ const DEFAULT_MAX_MESSAGES = 100;
 const DEFAULT_MAX_ATTACHMENT_BYTES = 1024 * 1024;
 /** Disk cap: this one protects the filesystem, which is a different concern. */
 const DEFAULT_MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+/** Extraction cap: how much hostile input one parser is asked to chew on. */
+const DEFAULT_MAX_EXTRACT_BYTES = 10 * 1024 * 1024;
+/**
+ * Hard ceiling on `IMAP_MAX_EXTRACT_BYTES`.
+ *
+ * The other two size variables have no maximum because their cost is linear and
+ * paid somewhere visible — a big result, a big file. This one buys a buffer
+ * inside a parser working on bytes a stranger chose, so a typo of "104857600000"
+ * would not produce a big answer, it would produce an operator who believes
+ * there is a limit. 64 MiB is past any document that arrives by mail.
+ */
+const MAX_MAX_EXTRACT_BYTES = 64 * 1024 * 1024;
 const DEFAULT_SEEN_KEYWORD = 'AiSeen';
+/** A hostname is at most 253 characters; an IPv6 literal far fewer. */
+const MAX_HOST_LENGTH = 253;
+/** IMAP allows 255 bytes of mailbox name; the tool parameter says the same. */
+const MAX_MAILBOX_LENGTH = 255;
+/** Matches the `keyword` tool parameter, which is the other place one is typed. */
+const MAX_KEYWORD_LENGTH = 64;
+const MAX_ATTACHMENT_TYPES = 64;
+/**
+ * The rule the `mailbox` tool parameter applies, imported rather than spelled
+ * again: a second copy of a control-character class is how two of them drift.
+ */
+const CONTROL_CHARS = MAILBOX_CONTROL_CHARS;
 /** Shown when the configuration is incomplete — at startup and on every call. */
 export function missingConfigMessage(missing) {
     return (`missing required environment variable(s): ${missing.join(', ')}\n` +
@@ -66,13 +93,20 @@ export function loadConfig(env = process.env) {
     const elicitation = parseElicitation(env.ELICITATION);
     if (host !== undefined)
         assertSafeHost(host, 'IMAP_HOST');
+    // A user name is written into a LOGIN command and into the From header of
+    // every draft. Neither tolerates a line break, and neither is a place for a
+    // value that was meant for the line above it.
+    if (user !== undefined)
+        assertSingleLine(user, 'IMAP_USER');
+    const mailbox = env.IMAP_MAILBOX || 'INBOX';
+    assertMailboxName(mailbox, 'IMAP_MAILBOX');
     const draftsMailbox = env.IMAP_DRAFTS_MAILBOX;
     if (draftsMailbox !== undefined) {
-        assertSingleLine(draftsMailbox, 'IMAP_DRAFTS_MAILBOX');
+        assertMailboxName(draftsMailbox, 'IMAP_DRAFTS_MAILBOX');
     }
     const trustedAuthservId = env.IMAP_TRUSTED_AUTHSERV_ID?.trim() || undefined;
     if (trustedAuthservId !== undefined) {
-        assertSingleLine(trustedAuthservId, 'IMAP_TRUSTED_AUTHSERV_ID');
+        assertSafeHost(trustedAuthservId, 'IMAP_TRUSTED_AUTHSERV_ID');
     }
     const config = {
         imap: {
@@ -82,15 +116,16 @@ export function loadConfig(env = process.env) {
             password,
             tls,
             insecureTls: env.IMAP_INSECURE_TLS === 'true',
-            mailbox: env.IMAP_MAILBOX || 'INBOX',
+            mailbox,
             seenKeyword: parseKeyword(env.IMAP_SEEN_KEYWORD),
             draftsMailbox,
             trustedAuthservId,
             maxMessages: parseCount(env.IMAP_MAX_MESSAGES, DEFAULT_MAX_MESSAGES, 'IMAP_MAX_MESSAGES'),
             maxAttachmentBytes: parseCount(env.IMAP_MAX_ATTACHMENT_BYTES, DEFAULT_MAX_ATTACHMENT_BYTES, 'IMAP_MAX_ATTACHMENT_BYTES'),
             allowedAttachmentTypes: parseTypes(env.IMAP_ATTACHMENT_TYPES),
-            downloadDir: env.IMAP_DOWNLOAD_DIR,
+            downloadDir: parseDownloadDir(env.IMAP_DOWNLOAD_DIR),
             maxDownloadBytes: parseCount(env.IMAP_MAX_DOWNLOAD_BYTES, DEFAULT_MAX_DOWNLOAD_BYTES, 'IMAP_MAX_DOWNLOAD_BYTES'),
+            maxExtractBytes: parseCount(env.IMAP_MAX_EXTRACT_BYTES, DEFAULT_MAX_EXTRACT_BYTES, 'IMAP_MAX_EXTRACT_BYTES', MAX_MAX_EXTRACT_BYTES),
         },
         // Defaults to true, unlike the rest of the family — see the field comment.
         readOnly: env.IMAP_READ_ONLY !== 'false',
@@ -146,10 +181,22 @@ export function parseElicitation(raw) {
         return true;
     if (value === 'false')
         return false;
-    console.error(`imap-mcp: ELICITATION must be "true" or "false" — got "${raw}". ` +
+    // Described, not quoted. The variable is unprefixed and sits in the same
+    // block as IMAP_PASSWORD in every compose file; what lands in it by mistake
+    // is exactly the value that must not be printed into the client's log.
+    console.error(`imap-mcp: ELICITATION must be "true" or "false" — got ${describeValue(raw ?? '')}. ` +
         'Refusing to start rather than guess.');
     process.exit(1);
 }
+/**
+ * A configuration value for an error message: its length and nothing else.
+ *
+ * Every variable this file reads has a neighbour that is a secret, and the
+ * value that fails a shape check is the one most likely to be that neighbour.
+ */
+function describeValue(raw) {
+    return `a ${raw.length}-character value`;
+}
 function parsePort(raw, fallback, name) {
     if (raw === undefined || raw === '')
         return fallback;
@@ -161,7 +208,7 @@ function parsePort(raw, fallback, name) {
     }
     return value;
 }
-function parseCount(raw, fallback, name) {
+function parseCount(raw, fallback, name, max) {
     if (raw === undefined || raw === '')
         return fallback;
     const value = Number(raw);
@@ -169,6 +216,13 @@ function parseCount(raw, fallback, name) {
         console.error(`imap-mcp: ${name} must be a positive integer`);
         process.exit(1);
     }
+    if (max !== undefined && value > max) {
+        // The limit is named rather than clamped to: an operator who asked for more
+        // than the server will do should learn that here, not from a refusal later
+        // that looks like the document was the problem.
+        console.error(`imap-mcp: ${name} must not exceed ${max}`);
+        process.exit(1);
+    }
     return value;
 }
 /**
@@ -180,19 +234,72 @@ function parseKeyword(raw) {
         return DEFAULT_SEEN_KEYWORD;
     if (raw === '')
         return '';
-    if (!/^[A-Za-z0-9$_.-]+$/.test(raw)) {
-        console.error('imap-mcp: IMAP_SEEN_KEYWORD must consist of letters, digits, $, _, . or -');
+    // Bounded like the `keyword` tool parameter. The value is written into a
+    // tool description and into every `get_server_info` answer, so a length has
+    // to be a length and not whatever was pasted.
+    if (raw.length > MAX_KEYWORD_LENGTH || !/^[A-Za-z0-9$_.-]+$/.test(raw)) {
+        console.error('imap-mcp: IMAP_SEEN_KEYWORD must consist of letters, digits, $, _, . or -, ' +
+            `at most ${MAX_KEYWORD_LENGTH} of them (got ${describeValue(raw)})`);
         process.exit(1);
     }
     return raw;
 }
+/**
+ * The attachment allowlist, one media type per entry.
+ *
+ * Every entry is answered back by `get_server_info` as `allowed_attachment_types`
+ * and compared against what messages declare. An entry that is not shaped like
+ * a media type can never match an attachment, so it is either a typo or a value
+ * meant for another variable — and in both cases the operator should hear
+ * about it at startup rather than read it in a tool result.
+ */
 function parseTypes(raw) {
     if (raw === undefined || raw.trim() === '')
         return DEFAULT_ATTACHMENT_TYPES;
-    return raw
+    const entries = raw
         .split(',')
         .map((t) => t.trim().toLowerCase())
         .filter((t) => t !== '');
+    if (entries.length > MAX_ATTACHMENT_TYPES) {
+        console.error(`imap-mcp: IMAP_ATTACHMENT_TYPES lists ${entries.length} entries; at most ${MAX_ATTACHMENT_TYPES} are accepted`);
+        process.exit(1);
+    }
+    const bad = entries.findIndex((entry) => !isMediaType(entry));
+    if (bad >= 0) {
+        console.error(`imap-mcp: IMAP_ATTACHMENT_TYPES entry ${bad + 1} is not a media type ` +
+            `such as application/pdf (got ${describeValue(entries[bad])})`);
+        process.exit(1);
+    }
+    return entries;
+}
+/**
+ * The download directory, resolved and checked before anything can print it.
+ *
+ * The path is answered by `get_server_info` and by every attachment listing,
+ * so it has to be a path — an existing directory, resolved through symlinks so
+ * that the containment check in `download.ts` compares against the place files
+ * really land. A value that is not a directory ends the process, and the
+ * message says how long it was, not what it said.
+ */
+function parseDownloadDir(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return undefined;
+    let resolved;
+    try {
+        resolved = realpathSync(trimmed);
+        if (!statSync(resolved).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        console.error('imap-mcp: IMAP_DOWNLOAD_DIR must name an existing directory ' +
+            `(got ${describeValue(trimmed)} that does not resolve to one). ` +
+            'Create it first, or unset the variable to keep this server off the filesystem.');
+        process.exit(1);
+    }
+    return resolved;
 }
 /**
  * Rejects anything that could break out of the line it is written on. IMAP is a
@@ -203,11 +310,13 @@ function assertSafeHost(value, name) {
     // A hostname or IPv4 address — or an IPv6 address, which is the only place
     // a colon is legal. Allowing ":" everywhere would silently accept
     // "imap.example.net:993", which the error message promises to reject.
+    // The length is checked first: nothing below walks a value longer than a
+    // hostname can be.
     const hostname = /^[A-Za-z0-9._-]+$/.test(value);
     const ipv6 = /^\[?[0-9A-Fa-f:.]*:[0-9A-Fa-f:.]*\]?$/.test(value);
-    if (!hostname && !ipv6) {
+    if (value.length > MAX_HOST_LENGTH || (!hostname && !ipv6)) {
         console.error(`imap-mcp: ${name} must be a plain hostname or IP address without ` +
-            'scheme, port, credentials or whitespace');
+            `scheme, port, credentials or whitespace (got ${describeValue(value)})`);
         process.exit(1);
     }
 }
@@ -218,6 +327,22 @@ function assertSingleLine(value, name) {
         process.exit(1);
     }
 }
+/**
+ * The rule the `mailbox` tool parameter enforces, for a name that arrives
+ * through the environment instead: bounded, no control characters, no LIST
+ * wildcards. The value is answered by every listing tool and printed on the
+ * startup line, so it has to look like a folder before it is printed anywhere.
+ */
+function assertMailboxName(value, name) {
+    if (value.length > MAX_MAILBOX_LENGTH ||
+        CONTROL_CHARS.test(value) ||
+        /[%*]/.test(value)) {
+        console.error(`imap-mcp: ${name} must be a mailbox name of at most ${MAX_MAILBOX_LENGTH} ` +
+            'characters without control characters or the wildcards % and * ' +
+            `(got ${describeValue(value)})`);
+        process.exit(1);
+    }
+}
 function isLoopbackHost(hostname) {
     // URL.hostname keeps the brackets around an IPv6 literal, may carry a %zone
     // suffix, and 'localhost.' with its root label is the same name as
@@ -225,11 +350,19 @@ function isLoopbackHost(hostname) {
     // its bare '::1' branch could never match a hostname taken from a URL.
     if (hostname === undefined)
         return false;
-    const host = hostname
+    let host = hostname
         .toLowerCase()
         .replace(/^\[|]$/g, '')
-        .replace(/%.*$/, '')
-        .replace(/\.+$/, '');
+        .replace(/%.*$/, '');
+    // Trailing root labels, walked from the end rather than matched with `\.+$`:
+    // that pattern is tried from every position of a run of dots and consumes
+    // the run each time, which is quadratic. The host is bounded to 253
+    // characters above, so this is a habit rather than a measured risk here —
+    // the same pattern on an unbounded value is the measured one.
+    let end = host.length;
+    while (end > 0 && host[end - 1] === '.')
+        end -= 1;
+    host = host.slice(0, end);
     return (host === 'localhost' ||
         host.endsWith('.localhost') ||
         host.startsWith('127.') ||

package/dist/extract/child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/extract/child.js

@@ -0,0 +1,83 @@
+/**
+ * The extraction child: the only code in this server that parses a binary a
+ * stranger sent, and the reason it runs in a process of its own.
+ *
+ * A process rather than a worker thread, and that was a lesson rather than a
+ * preference. A worker's `resourceLimits` promise to turn a runaway parse into
+ * `ERR_WORKER_OUT_OF_MEMORY`, and for most allocation patterns they do; for
+ * the one a 3 kB spreadsheet produced they did not, and the whole server died
+ * with `FATAL ERROR: Reached heap limit`. A thread also cannot give back the
+ * memory a terminated parse left behind — a gigabyte stayed resident after
+ * `terminate()`. A process that is killed takes its memory with it, whatever
+ * it was doing, and a process that aborts aborts alone.
+ *
+ * Read the import rules before editing this file. It is started from its own
+ * source — `child.ts` under vitest, which Node runs with type stripping, and
+ * `child.js` from `dist/` in production — so Node loads it and everything it
+ * reaches, without vitest's resolver. Node strips types; it does not rewrite a
+ * `./x.js` specifier to the `./x.ts` sitting beside it. So:
+ *
+ * - static imports here may only be bare specifiers (`node:*`, a package) or
+ *   `import type`, which is erased before it can fail to resolve;
+ * - anything relative is loaded through {@link sibling}, which picks the
+ *   extension from this module's own;
+ * - no enums, no namespaces, no parameter properties — type stripping cannot
+ *   erase syntax that emits code.
+ *
+ * Get this wrong in one direction and every test fails while the build stays
+ * green; get it wrong in the other and every test passes while the published
+ * package throws on first use. The second is why `npm run build` is followed by
+ * a real extraction against `dist/`.
+ */
+const EXTENSION = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+function sibling(path) {
+    return new URL(`${path}.${EXTENSION}`, import.meta.url).href;
+}
+async function run(request) {
+    if (request.kind === 'pdf') {
+        const { extractPdf } = (await import(sibling('./pdf')));
+        return extractPdf(request.bytes, request.maxChars);
+    }
+    const [{ extractZipDocument }, { htmlToText }] = await Promise.all([
+        import(sibling('./ooxml')),
+        import(sibling('../analyze')),
+    ]);
+    return extractZipDocument(request.kind, request.bytes, request.maxChars, htmlToText);
+}
+/** A code for the log, never a message: the message quotes the document. */
+function codeOf(error) {
+    const value = error;
+    if (typeof value?.code === 'string')
+        return value.code;
+    if (typeof value?.name === 'string')
+        return value.name;
+    return 'unknown';
+}
+const send = process.send?.bind(process);
+if (send !== undefined) {
+    // The parent is gone: nothing is waiting for an answer, and a parse that
+    // outlives the server it was started by is a parse nobody asked for.
+    process.on('disconnect', () => {
+        process.exit(0);
+    });
+    process.once('message', (request) => {
+        run(request).then((response) => {
+            send(response, () => {
+                process.exit(0);
+            });
+        }, (error) => {
+            // Never the caught error. pdf.js and fflate quote the document in
+            // their exception messages — byte offsets, object fragments, what they
+            // found where they expected something else. That is text a stranger
+            // wrote, and an error message is read as the server's own voice,
+            // outside the fence every other piece of message content passes
+            // through. A code crosses; the words are the host's.
+            console.error(`imap-mcp: extraction failed: ${codeOf(error)}`);
+            send({ ok: false, reason: 'internal' }, () => {
+                process.exit(0);
+            });
+        });
+    });
+}
+export {};
+//# sourceMappingURL=child.js.map

package/dist/extract/index.d.ts

@@ -0,0 +1,41 @@
+import type { ExtractKind, ExtractRequest, ExtractResponse } from './types.js';
+export type { ExtractKind, ExtractReason, ExtractRequest, ExtractResponse, } from './types.js';
+/**
+ * How long a document may be parsed before the process doing it is killed.
+ *
+ * Generous next to the five seconds a regular expression gets in the sibling
+ * servers, because a hundred-page PDF is honest work — and finite, because a
+ * document that has not finished by now is not going to.
+ */
+export declare const EXTRACT_TIMEOUT_MS = 20000;
+/**
+ * Characters the child may return, before any of the paging below.
+ *
+ * Not a context budget — that is `max_chars` at the tool, and it is much
+ * smaller. This is the ceiling on what is held in memory and paged through,
+ * and the child enforces it for every format: nothing larger is ever built
+ * there, let alone sent back.
+ */
+export declare const MAX_EXTRACT_CHARS = 1000000;
+/** The same set as content types, for `get_server_info`. */
+export declare const EXTRACTABLE_TYPES: string[];
+/** Prose for the refusals, so every one of them names the same set. */
+export declare const EXTRACTABLE_TYPE_NAMES: string;
+export declare function extractKindOf(contentType: string): ExtractKind | undefined;
+export declare function isExtractable(contentType: string): boolean;
+/** The magic-byte verdict an honest container of this kind produces. */
+export declare function expectedSignature(kind: ExtractKind): string;
+export declare function extractDocumentText(request: ExtractRequest, limits?: ChildLimits): Promise<ExtractResponse>;
+/**
+ * Narrowed by the tests, never by the server.
+ *
+ * The timeout and the memory ceiling are the two guards whose whole purpose is
+ * what happens when they fire, and neither can be reached in a test at its real
+ * value without a document engineered to spend twenty seconds or a quarter of a
+ * gigabyte. Making them arguments is what lets the failure paths be exercised
+ * in milliseconds; nothing in `src/` passes them.
+ */
+export interface ChildLimits {
+    timeoutMs?: number;
+    memoryMb?: number;
+}

package/dist/extract/index.js

@@ -0,0 +1,183 @@
+import { fork } from 'node:child_process';
+import { once } from 'node:events';
+/**
+ * How long a document may be parsed before the process doing it is killed.
+ *
+ * Generous next to the five seconds a regular expression gets in the sibling
+ * servers, because a hundred-page PDF is honest work — and finite, because a
+ * document that has not finished by now is not going to.
+ */
+export const EXTRACT_TIMEOUT_MS = 20_000;
+/**
+ * Characters the child may return, before any of the paging below.
+ *
+ * Not a context budget — that is `max_chars` at the tool, and it is much
+ * smaller. This is the ceiling on what is held in memory and paged through,
+ * and the child enforces it for every format: nothing larger is ever built
+ * there, let alone sent back.
+ */
+export const MAX_EXTRACT_CHARS = 1_000_000;
+/**
+ * V8 heap the parsing process may use.
+ *
+ * Best effort, and named as such. It bounds a pathological object graph, and
+ * when it fires the child aborts — on its own, which is the whole reason the
+ * parse is in a process. It does not bound typed arrays, which are external
+ * memory; the deflate pre-scan in `pdf.ts` and the entry caps in `ooxml.ts`
+ * are what cover those.
+ */
+const CHILD_MEMORY_MB = 256;
+/**
+ * Requests admitted at once, running and waiting together.
+ *
+ * Extractions run one at a time (see {@link queue}), so a request that arrives
+ * behind seven others would wait up to seven timeouts for its turn, holding
+ * its mailbox lock throughout. Past this many it is refused outright, which is
+ * an answer the caller can act on.
+ */
+const MAX_IN_FLIGHT = 8;
+/** Content types this server can read text out of, and what each one is. */
+const EXTRACTABLE = new Map([
+    ['application/pdf', 'pdf'],
+    [
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'docx',
+    ],
+    ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'xlsx'],
+    [
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        'pptx',
+    ],
+    ['application/vnd.oasis.opendocument.text', 'odt'],
+    ['application/vnd.oasis.opendocument.spreadsheet', 'ods'],
+]);
+/** The same set as content types, for `get_server_info`. */
+export const EXTRACTABLE_TYPES = [...EXTRACTABLE.keys()];
+/** Prose for the refusals, so every one of them names the same set. */
+export const EXTRACTABLE_TYPE_NAMES = 'PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx) and OpenDocument text ' +
+    'and spreadsheets (.odt, .ods)';
+export function extractKindOf(contentType) {
+    return EXTRACTABLE.get(contentType.toLowerCase());
+}
+export function isExtractable(contentType) {
+    return EXTRACTABLE.has(contentType.toLowerCase());
+}
+/** The magic-byte verdict an honest container of this kind produces. */
+export function expectedSignature(kind) {
+    // Every OOXML and OpenDocument file is a zip, which is why `sniffContent`
+    // reports one for all five of them.
+    return kind === 'pdf' ? 'application/pdf' : 'application/zip';
+}
+/**
+ * Serialises extractions.
+ *
+ * One process per call and no limit would mean N concurrent tool calls holding
+ * N processes of {@link CHILD_MEMORY_MB} each, which is a memory limit that
+ * multiplies by a number the caller chooses. The queue is the whole mechanism:
+ * the next extraction starts when the previous process is gone.
+ */
+let queue = Promise.resolve();
+let inFlight = 0;
+export async function extractDocumentText(request, limits = {}) {
+    if (inFlight >= MAX_IN_FLIGHT)
+        return { ok: false, reason: 'busy' };
+    inFlight += 1;
+    try {
+        const run = queue.then(() => runInChild(request, limits), () => runInChild(request, limits));
+        queue = run.catch(() => undefined);
+        return await run;
+    }
+    finally {
+        inFlight -= 1;
+    }
+}
+/** A code for the log, never a message. */
+function codeOf(error) {
+    const value = error;
+    if (typeof value?.code === 'string')
+        return value.code;
+    if (typeof value?.name === 'string')
+        return value.name;
+    return 'unknown';
+}
+async function runInChild(request, limits = {}) {
+    const timeoutMs = limits.timeoutMs ?? EXTRACT_TIMEOUT_MS;
+    const memoryMb = limits.memoryMb ?? CHILD_MEMORY_MB;
+    const child = fork(new URL(import.meta.url.endsWith('.ts') ? './child.ts' : './child.js', import.meta.url), [], {
+        // Stated rather than inherited. The parent's own flags may be ones a
+        // child cannot take — `--input-type` is one — and an inherited flag that
+        // fails to parse would turn every extraction into a silent `internal`.
+        execArgv: [`--max-old-space-size=${memoryMb}`],
+        // Not tidiness — correctness. The parent's stdout is this server's
+        // JSON-RPC transport, and pdf.js logs. One line from inside the parser
+        // would corrupt the framing and hang the session. Discarded; stderr is
+        // shared, because that is where every other diagnostic in this server
+        // already goes.
+        stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+        // Structured clone rather than JSON: the request carries the document as
+        // a typed array, and JSON would turn it into an array of numbers ten
+        // times its size.
+        serialization: 'advanced',
+    });
+    let timer;
+    try {
+        return await new Promise((resolve) => {
+            // The first answer wins. Everything after it — the exit of a child that
+            // was killed because it had already answered, most of all — is silence,
+            // not a second verdict.
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            timer = setTimeout(() => {
+                settle({ ok: false, reason: 'timeout' });
+            }, timeoutMs);
+            child.once('message', (value) => {
+                settle(value);
+            });
+            child.once('error', (error) => {
+                if (settled)
+                    return;
+                console.error(`imap-mcp: extraction process failed: ${codeOf(error)}`);
+                settle({ ok: false, reason: 'internal' });
+            });
+            child.once('exit', (code, signal) => {
+                // Only reached when the child left without answering. An abort is what
+                // V8 does when the heap limit is hit — and what the process does
+                // *instead of* taking the server with it, which is the property being
+                // bought here.
+                if (settled)
+                    return;
+                if (signal === 'SIGABRT' || code === 134) {
+                    settle({ ok: false, reason: 'out-of-memory' });
+                    return;
+                }
+                console.error(`imap-mcp: extraction process exited early: ${signal ?? `code ${code}`}`);
+                settle({ ok: false, reason: 'internal' });
+            });
+            try {
+                child.send(request);
+            }
+            catch (error) {
+                console.error(`imap-mcp: extraction request failed: ${codeOf(error)}`);
+                settle({ ok: false, reason: 'internal' });
+            }
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        // Unconditional: on the timeout path the process is still inside the parse
+        // and will never exit on its own. SIGKILL, because a parser stuck in native
+        // code does not check for anything gentler — and because a process, unlike
+        // a thread, can be killed from outside whatever it is doing.
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGKILL');
+            await once(child, 'exit');
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/extract/ooxml.d.ts

@@ -0,0 +1,35 @@
+import type { ExtractKind, ExtractResponse } from './types.js';
+/**
+ * Turns markup into readable text. Injected rather than imported.
+ *
+ * `htmlToText` lives in `../analyze.ts`, and this module is reached from the
+ * extraction child, which Node loads directly — where a `../analyze.js`
+ * specifier does not resolve to the `.ts` beside it. Passing the function in
+ * keeps this file free of relative value imports, which is the property that
+ * lets it run in the child at all. It also makes the seam explicit: the tests
+ * hand it the same `htmlToText` the child does.
+ */
+export type MarkupToText = (markup: string, maxChars: number) => string;
+/**
+ * Reads the text of an OOXML or OpenDocument container.
+ *
+ * The whole defence lives in the `filter` callback below, and it is worth
+ * saying why that specific place. `unzipSync` inflates an entry into a buffer
+ * sized by the *declared* uncompressed size out of the central directory — a
+ * number the sender chose, checked against nothing. The filter is the last
+ * point before that allocation, and returning `false` there means the entry is
+ * never inflated and never sized.
+ *
+ * Measured on fflate 0.8.3: a declared size far past the real one does not blow
+ * up resident memory on Linux, because the allocation is virtual and untouched
+ * pages cost nothing; and a declared size *below* the real one truncates the
+ * output to what was declared, because fflate does not grow a caller-sized
+ * buffer. The guard stays regardless — it is free, it is the only thing
+ * standing between an *honest* high-ratio entry and its real expansion, and a
+ * host that does not overcommit would pay the full price.
+ *
+ * This never recurses. An entry that is itself an archive is not in the name
+ * allowlist, so a nested bomb is not descended into; that is a property to keep
+ * rather than an omission to fix.
+ */
+export declare function extractZipDocument(kind: Exclude<ExtractKind, 'pdf'>, bytes: Uint8Array, maxChars: number, toText: MarkupToText): Promise<ExtractResponse>;