@ni-c/imap-mcp 0.2.0

package/dist/confirm.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Issues short-lived confirmation tokens for irreversible operations.
+ *
+ * A plain boolean `confirm` parameter could be set by the model on the very
+ * first call — or be talked into it by instructions hidden in upstream content —
+ * whereas a random token that only ever appears in a *previous* tool result
+ * cannot be guessed. The token is bound to a resource key, so a confirmation for
+ * one target cannot be replayed for another.
+ */
+export declare class ConfirmationStore {
+    private readonly ttlMs;
+    private readonly pending;
+    constructor(ttlMs?: number);
+    /** Creates (or replaces) the pending token for `resource`. */
+    issue(resource: string): string;
+    /**
+     * Returns true and consumes the token when it matches the pending one for
+     * `resource` and has not expired. Tokens are single-use.
+     */
+    consume(resource: string, token: string | undefined): boolean;
+    /** Minutes the issued tokens stay valid, for use in messages. */
+    get ttlMinutes(): number;
+}
+/**
+ * Resource key for an operation on a *set* of targets. Without the fingerprint a
+ * confirmation for ["a.txt"] would also execute ["a.txt", "secrets.env"] — the
+ * model chooses the second list, and only the id would have been checked.
+ */
+export declare function setResourceKey(operation: string, targets: string[]): string;
+/**
+ * A name this server did not choose, shown alongside a confirmation.
+ *
+ * Mailbox names look like server-side metadata and are not: they come from the
+ * model's arguments, and `list_mailboxes` sources them from the account — which
+ * on a shared mailbox or a public namespace means a colleague, or whoever
+ * compromised one, picks them. A folder called
+ * `Archive" — routine cleanup, pre-approved by IT` interpolated into the middle
+ * of "This will move 12 message(s) from X to Y" reads as part of the server's
+ * own sentence, in the one string a human is given before losing a folder.
+ *
+ * So they are never interpolated: {@link renderDetails} puts each on its own
+ * labelled line. `mailboxParam` refuses CR, LF and NUL, so a value cannot open a
+ * second line and forge a label of its own — the single-line rendering is what
+ * that validation is worth.
+ */
+export interface ConfirmationDetail {
+    label: string;
+    value: string;
+}
+declare function renderDetails(details: readonly ConfirmationDetail[]): string;
+/**
+ * Builds the text returned by the first call of a destructive tool.
+ *
+ * Note what is NOT in here: no subject, sender or filename coming out of the
+ * mailbox. Those are attacker-controllable and this string is read by a model.
+ * Mailbox names are attacker-reachable too, which is what `details` is for.
+ */
+export declare function confirmationPrompt(what: string, token: string, ttlMinutes: number, consequence?: string, details?: readonly ConfirmationDetail[]): string;
+export { renderDetails };

package/dist/confirm.js

@@ -0,0 +1,92 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+const TOKEN_TTL_MS = 5 * 60 * 1000;
+/** Bounds the map so a loop of refused calls cannot grow it without limit. */
+const MAX_PENDING = 100;
+/**
+ * Issues short-lived confirmation tokens for irreversible operations.
+ *
+ * A plain boolean `confirm` parameter could be set by the model on the very
+ * first call — or be talked into it by instructions hidden in upstream content —
+ * whereas a random token that only ever appears in a *previous* tool result
+ * cannot be guessed. The token is bound to a resource key, so a confirmation for
+ * one target cannot be replayed for another.
+ */
+export class ConfirmationStore {
+    ttlMs;
+    pending = new Map();
+    constructor(ttlMs = TOKEN_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    /** Creates (or replaces) the pending token for `resource`. */
+    issue(resource) {
+        if (this.pending.size >= MAX_PENDING) {
+            const oldest = this.pending.keys().next();
+            if (!oldest.done)
+                this.pending.delete(oldest.value);
+        }
+        const token = randomBytes(16).toString('hex');
+        this.pending.set(resource, { token, expiresAt: Date.now() + this.ttlMs });
+        return token;
+    }
+    /**
+     * Returns true and consumes the token when it matches the pending one for
+     * `resource` and has not expired. Tokens are single-use.
+     */
+    consume(resource, token) {
+        const entry = this.pending.get(resource);
+        if (entry === undefined || token === undefined)
+            return false;
+        const supplied = Buffer.from(token);
+        const expected = Buffer.from(entry.token);
+        // Constant-time comparison. Guessing 128 random bits through a timing
+        // side channel is not a realistic attack on a local tool, but the safe
+        // comparison costs one line and removes the question.
+        const matches = supplied.length === expected.length &&
+            timingSafeEqual(supplied, expected);
+        if (!matches)
+            return false;
+        // Delete on any match, expired or not. Leaving a matched-but-dead entry
+        // behind kept it competing for space with live ones, and the eviction in
+        // issue() is insertion-order rather than LRU, so a long-lived key could be
+        // dropped ahead of a token that was already spent.
+        this.pending.delete(resource);
+        return Date.now() < entry.expiresAt;
+    }
+    /** Minutes the issued tokens stay valid, for use in messages. */
+    get ttlMinutes() {
+        return Math.round(this.ttlMs / 60_000);
+    }
+}
+/**
+ * Resource key for an operation on a *set* of targets. Without the fingerprint a
+ * confirmation for ["a.txt"] would also execute ["a.txt", "secrets.env"] — the
+ * model chooses the second list, and only the id would have been checked.
+ */
+export function setResourceKey(operation, targets) {
+    const fingerprint = createHash('sha256')
+        .update(JSON.stringify([...targets].sort()))
+        .digest('hex')
+        .slice(0, 16);
+    return `${operation}:${fingerprint}`;
+}
+function renderDetails(details) {
+    if (details.length === 0)
+        return '';
+    return ('\n\nNames below are supplied by the caller, not by this server:\n' +
+        details.map((d) => `  ${d.label}: ${d.value}`).join('\n'));
+}
+/**
+ * Builds the text returned by the first call of a destructive tool.
+ *
+ * Note what is NOT in here: no subject, sender or filename coming out of the
+ * mailbox. Those are attacker-controllable and this string is read by a model.
+ * Mailbox names are attacker-reachable too, which is what `details` is for.
+ */
+export function confirmationPrompt(what, token, ttlMinutes, consequence = 'The operation is irreversible.', details = []) {
+    return (`This will ${what}. ${consequence}` +
+        `${renderDetails(details)}\n\n` +
+        `To proceed, call this tool again with confirm_token="${token}".\n` +
+        `The token is valid for ${ttlMinutes} minutes and can be used once.`);
+}
+export { renderDetails };
+//# sourceMappingURL=confirm.js.map

package/dist/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../src/confirm.ts"],"names":[],"mappings":"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"}

package/dist/download.d.ts

@@ -0,0 +1,23 @@
+export interface SavedAttachment {
+    path: string;
+    bytes: number;
+}
+/**
+ * Writes an attachment into the configured download directory.
+ *
+ * Everything here exists because this is the first point in the server where
+ * bytes from a stranger get a name in the filesystem:
+ *
+ * - The directory comes only from `IMAP_DOWNLOAD_DIR`. A caller — and therefore
+ *   a message that talked the model into a tool call — cannot choose where
+ *   anything lands.
+ * - The filename is already stripped of path separators and directional
+ *   overrides by `sanitizeFilename`, but the resolved path is checked against
+ *   the directory anyway, because one guard is not a guard.
+ * - `wx` refuses to open an existing path. That covers two attacks at once:
+ *   overwriting a file the user cares about, and following a symlink somebody
+ *   planted under a predictable attachment name.
+ * - Mode 0600, because the content is untrusted and possibly confidential at
+ *   the same time.
+ */
+export declare function saveAttachment(directory: string, filename: string, content: Buffer): Promise<SavedAttachment>;

package/dist/download.js

@@ -0,0 +1,65 @@
+import { open } from 'node:fs/promises';
+import { extname, join, resolve, sep } from 'node:path';
+import { ToolInputError } from './errors.js';
+/** How many `name (2).pdf`, `name (3).pdf` … variants are tried. */
+const MAX_COLLISION_ATTEMPTS = 50;
+/**
+ * Writes an attachment into the configured download directory.
+ *
+ * Everything here exists because this is the first point in the server where
+ * bytes from a stranger get a name in the filesystem:
+ *
+ * - The directory comes only from `IMAP_DOWNLOAD_DIR`. A caller — and therefore
+ *   a message that talked the model into a tool call — cannot choose where
+ *   anything lands.
+ * - The filename is already stripped of path separators and directional
+ *   overrides by `sanitizeFilename`, but the resolved path is checked against
+ *   the directory anyway, because one guard is not a guard.
+ * - `wx` refuses to open an existing path. That covers two attacks at once:
+ *   overwriting a file the user cares about, and following a symlink somebody
+ *   planted under a predictable attachment name.
+ * - Mode 0600, because the content is untrusted and possibly confidential at
+ *   the same time.
+ */
+export async function saveAttachment(directory, filename, content) {
+    const base = resolve(directory);
+    const extension = extname(filename);
+    const stem = extension === '' ? filename : filename.slice(0, -extension.length);
+    for (let attempt = 1; attempt <= MAX_COLLISION_ATTEMPTS; attempt += 1) {
+        const candidate = attempt === 1 ? filename : `${stem} (${attempt})${extension}`;
+        const target = resolve(join(base, candidate));
+        // The sanitizer should already have made this impossible; if it ever stops
+        // being true, the write must not be the place where that is discovered.
+        if (target !== base && !target.startsWith(base + sep)) {
+            throw new ToolInputError('imap-mcp: refused to write outside the configured download directory.');
+        }
+        let handle;
+        try {
+            handle = await open(target, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                continue;
+            throw new ToolInputError(`imap-mcp: could not write to the download directory: ${describe(error)}`);
+        }
+        try {
+            await handle.write(content);
+            return { path: target, bytes: content.length };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    throw new ToolInputError(`imap-mcp: ${MAX_COLLISION_ATTEMPTS} files with this name already exist in the download directory.`);
+}
+function describe(error) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'the directory does not exist';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'permission denied';
+    if (code === 'ENOSPC')
+        return 'no space left on the device';
+    return code ?? 'unknown error';
+}
+//# sourceMappingURL=download.js.map

package/dist/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,oEAAoE;AACpE,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAOlC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,QAAgB,EAChB,OAAe;IAEf,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,IAAI,GACR,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAErE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,sBAAsB,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,SAAS,GACb,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,IAAI,SAAS,EAAE,CAAC;QAChE,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAE9C,2EAA2E;QAC3E,wEAAwE;QACxE,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,cAAc,CACtB,uEAAuE,CACxE,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,SAAS;YACjE,MAAM,IAAI,cAAc,CACtB,wDAAwD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAC1E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACjD,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,cAAc,CACtB,aAAa,sBAAsB,gEAAgE,CACpG,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,MAAM,IAAI,GAAI,KAAsC,EAAE,IAAI,CAAC;IAC3D,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,8BAA8B,CAAC;IAC7D,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,mBAAmB,CAAC;IACtE,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,6BAA6B,CAAC;IAC5D,OAAO,IAAI,IAAI,eAAe,CAAC;AACjC,CAAC"}

package/dist/draft.d.ts

@@ -0,0 +1,34 @@
+/** Headers linking a draft into an existing conversation. */
+export interface ThreadHeaders {
+    messageId: string | undefined;
+    references: string[];
+}
+export interface DraftInput {
+    from: string | undefined;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    body: string;
+    thread?: ThreadHeaders;
+    /** Injected by the tests; real calls stamp the current time. */
+    date?: Date;
+}
+/**
+ * Builds an RFC 5322 message for `APPEND`.
+ *
+ * Written by hand rather than pulled from a library because the only consumer
+ * is this one path, and because every field here needs the same treatment: a
+ * bare CR or LF in a header value would let the caller append headers of its
+ * own — a Bcc, a Reply-To pointing elsewhere — to a message a human will later
+ * send under their own name. The schemas reject line breaks already; this is
+ * the second lock on the same door.
+ */
+export declare function buildDraft(input: DraftInput): Buffer;
+/**
+ * Encodes a header value as MIME encoded-words when it is not plain ASCII.
+ *
+ * A raw UTF-8 subject is rejected or mangled by a fair number of servers, and
+ * the draft has to survive being opened in whatever mail client the person uses.
+ */
+export declare function encodeHeaderValue(value: string): string;

package/dist/draft.js

@@ -0,0 +1,119 @@
+import { randomUUID } from 'node:crypto';
+import { ToolInputError } from './errors.js';
+/** Encoded-words must not exceed 75 characters including the delimiters. */
+const ENCODED_WORD_PAYLOAD = 45;
+/**
+ * Builds an RFC 5322 message for `APPEND`.
+ *
+ * Written by hand rather than pulled from a library because the only consumer
+ * is this one path, and because every field here needs the same treatment: a
+ * bare CR or LF in a header value would let the caller append headers of its
+ * own — a Bcc, a Reply-To pointing elsewhere — to a message a human will later
+ * send under their own name. The schemas reject line breaks already; this is
+ * the second lock on the same door.
+ */
+export function buildDraft(input) {
+    const from = input.from;
+    if (from === undefined || from === '') {
+        throw new ToolInputError('imap-mcp: no sender address available — IMAP_USER is not set.');
+    }
+    const headers = [
+        ['From', from],
+        ['To', input.to.join(', ')],
+    ];
+    if (input.cc !== undefined && input.cc.length > 0) {
+        headers.push(['Cc', input.cc.join(', ')]);
+    }
+    if (input.bcc !== undefined && input.bcc.length > 0) {
+        headers.push(['Bcc', input.bcc.join(', ')]);
+    }
+    headers.push(['Subject', encodeHeaderValue(input.subject)]);
+    headers.push(['Date', (input.date ?? new Date()).toUTCString()]);
+    headers.push(['Message-ID', `<${randomUUID()}@imap-mcp.invalid>`]);
+    if (input.thread?.messageId !== undefined) {
+        headers.push(['In-Reply-To', input.thread.messageId]);
+    }
+    if (input.thread !== undefined && input.thread.references.length > 0) {
+        headers.push(['References', foldReferences(input.thread.references)]);
+    }
+    headers.push(['MIME-Version', '1.0']);
+    headers.push(['Content-Type', 'text/plain; charset=utf-8']);
+    headers.push(['Content-Transfer-Encoding', 'base64']);
+    const lines = headers.map(([name, value]) => {
+        assertHeaderSafe(name, value);
+        return `${name}: ${value}`;
+    });
+    // base64 for the body: it survives any charset, cannot contain a line that
+    // looks like a header, and keeps lines inside the 998-octet limit.
+    const encoded = Buffer.from(input.body, 'utf-8')
+        .toString('base64')
+        .replace(/(.{76})/g, '$1\r\n');
+    return Buffer.from(`${lines.join('\r\n')}\r\n\r\n${encoded}\r\n`, 'utf-8');
+}
+/** Keep every folded header line under the RFC 5322 hard limit of 998 octets. */
+const MAX_HEADER_LINE = 900;
+/**
+ * Joins the References chain, folding onto continuation lines as needed.
+ *
+ * Twenty Message-IDs of up to 257 characters each on a single line would pass
+ * 5 kB — five times the 998-octet line limit, which some servers answer by
+ * refusing the APPEND and others by mangling the header. Folding (CRLF
+ * followed by a space) is how RFC 5322 says a long header is written.
+ */
+function foldReferences(references) {
+    const lines = [];
+    let line = '';
+    for (const reference of references) {
+        if (line === '') {
+            line = reference;
+        }
+        else if (line.length + 1 + reference.length > MAX_HEADER_LINE) {
+            lines.push(line);
+            line = reference;
+        }
+        else {
+            line = `${line} ${reference}`;
+        }
+    }
+    if (line !== '')
+        lines.push(line);
+    return lines.join('\r\n ');
+}
+/**
+ * A CRLF is only legal in a header when the next line starts with whitespace —
+ * that is folding. Anything else ends the header and starts a new one, which is
+ * exactly the injection this guards against.
+ */
+function assertHeaderSafe(name, value) {
+    if (/\r(?!\n)|(?<!\r)\n|\r\n(?![ \t])/.test(value)) {
+        throw new ToolInputError(`imap-mcp: the ${name} header must not contain line breaks.`);
+    }
+}
+/**
+ * Encodes a header value as MIME encoded-words when it is not plain ASCII.
+ *
+ * A raw UTF-8 subject is rejected or mangled by a fair number of servers, and
+ * the draft has to survive being opened in whatever mail client the person uses.
+ */
+export function encodeHeaderValue(value) {
+    if (!/[^ -~]/.test(value))
+        return value;
+    const words = [];
+    let chunk = '';
+    for (const character of value) {
+        const candidate = chunk + character;
+        if (Buffer.byteLength(candidate, 'utf-8') > ENCODED_WORD_PAYLOAD) {
+            words.push(chunk);
+            chunk = character;
+        }
+        else {
+            chunk = candidate;
+        }
+    }
+    if (chunk !== '')
+        words.push(chunk);
+    return words
+        .map((word) => `=?UTF-8?B?${Buffer.from(word, 'utf-8').toString('base64')}?=`)
+        .join('\r\n ');
+}
+//# sourceMappingURL=draft.js.map

package/dist/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/** Errors that come from the caller's arguments rather than from the server. */
+export declare class ToolInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * An IMAP failure, carrying whatever the server said.
+ *
+ * `responseText` is upstream output and gets the same truncation treatment as
+ * any other remote string before it reaches the model.
+ */
+export declare class MailError extends Error {
+    readonly code: string | undefined;
+    readonly responseText: string;
+    constructor(message: string, code?: string | undefined, responseText?: string);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/** Errors that come from the caller's arguments rather than from the server. */
+export class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolInputError';
+    }
+}
+/**
+ * An IMAP failure, carrying whatever the server said.
+ *
+ * `responseText` is upstream output and gets the same truncation treatment as
+ * any other remote string before it reaches the model.
+ */
+export class MailError extends Error {
+    code;
+    responseText;
+    constructor(message, code = undefined, responseText = '') {
+        super(message);
+        this.code = code;
+        this.responseText = responseText;
+        this.name = 'MailError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGvB;IACA;IAHX,YACE,OAAe,EACN,OAA2B,SAAS,EACpC,eAAuB,EAAE;QAElC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAgC;QACpC,iBAAY,GAAZ,YAAY,CAAa;QAGlC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/imap.d.ts

@@ -0,0 +1,161 @@
+import type { FetchMessageObject, FetchQueryObject, ListResponse, SearchObject, StatusObject } from 'imapflow';
+import { type Config, type ImapConfig } from './config.js';
+import { MailError } from './errors.js';
+/**
+ * Everything this server needs from an IMAP connection.
+ *
+ * Narrowing imapflow to an interface is what makes the tools testable: the unit
+ * tests inject a fake through {@link ImapClientFactory} instead of standing up a
+ * real server, and the surface stays small enough that the fake cannot silently
+ * drift away from the real thing.
+ */
+export interface ImapConnection {
+    connect(): Promise<void>;
+    logout(): Promise<void>;
+    close(): void;
+    noop(): Promise<void>;
+    list(options?: {
+        statusQuery?: {
+            messages?: boolean;
+            unseen?: boolean;
+            uidNext?: boolean;
+        };
+    }): Promise<ListResponse[]>;
+    status(path: string, query: Record<string, boolean>): Promise<StatusObject>;
+    getMailboxLock(path: string, options?: {
+        readOnly?: boolean;
+    }): Promise<{
+        path: string;
+        release(): void;
+    }>;
+    search(query: SearchObject, options?: {
+        uid?: boolean;
+    }): Promise<number[] | false>;
+    fetch(range: number[] | string, query: FetchQueryObject, options?: {
+        uid?: boolean;
+    }): AsyncIterableIterator<FetchMessageObject>;
+    download(range: string, part?: string, options?: {
+        uid?: boolean;
+        maxBytes?: number;
+    }): Promise<{
+        meta: {
+            contentType: string;
+            charset?: string;
+            filename?: string;
+        };
+        content: NodeJS.ReadableStream;
+    }>;
+    messageFlagsAdd(range: number[], flags: string[], options?: {
+        uid?: boolean;
+    }): Promise<boolean>;
+    messageFlagsRemove(range: number[], flags: string[], options?: {
+        uid?: boolean;
+    }): Promise<boolean>;
+    messageMove(range: number[], destination: string, options?: {
+        uid?: boolean;
+    }): Promise<unknown>;
+    messageCopy(range: number[], destination: string, options?: {
+        uid?: boolean;
+    }): Promise<unknown>;
+    messageDelete(range: number[], options?: {
+        uid?: boolean;
+    }): Promise<boolean>;
+    append(path: string, content: string | Buffer, flags?: string[], date?: Date): Promise<unknown>;
+    mailboxCreate(path: string): Promise<unknown>;
+    mailboxRename(path: string, newPath: string): Promise<unknown>;
+    mailboxDelete(path: string): Promise<unknown>;
+    readonly capabilities: Map<string, boolean | number>;
+    readonly mailbox: false | {
+        path: string;
+        permanentFlags: Set<string>;
+    };
+}
+export type ImapClientFactory = (config: ImapConfig) => ImapConnection;
+export interface MailboxSummary {
+    path: string;
+    name: string;
+    delimiter: string;
+    specialUse: string | undefined;
+    subscribed: boolean;
+    selectable: boolean;
+    messages: number | undefined;
+    unseen: number | undefined;
+    uidNext: number | undefined;
+}
+/**
+ * Connection manager around a single IMAP account.
+ *
+ * Reads take the mailbox lock read-only and use BODY.PEEK throughout, so
+ * fetching a message never changes what the human sees as unread. The only
+ * exception is deliberate and explicit: {@link tagSeen}, which writes the
+ * server's own bookkeeping keyword.
+ */
+export declare class ImapClient {
+    private readonly config;
+    private readonly factory;
+    private connection;
+    private connecting;
+    constructor(config: Config, factory?: ImapClientFactory);
+    /** Credentials are checked per call, not at startup. */
+    private assertConfigured;
+    private connection_;
+    /**
+     * Runs `fn` with the mailbox open and the lock held.
+     *
+     * A dropped connection is retried exactly once: IMAP sessions are long-lived
+     * and idle ones get reaped by servers and NAT gateways alike, so the first
+     * call after a pause routinely fails for reasons that have nothing to do with
+     * the request.
+     */
+    withMailbox<T>(mailbox: string | undefined, readOnly: boolean, fn: (client: ImapConnection, path: string) => Promise<T>): Promise<T>;
+    private run;
+    /** Runs `fn` without selecting a mailbox, for LIST/STATUS/CREATE style calls. */
+    withConnection<T>(fn: (client: ImapConnection) => Promise<T>): Promise<T>;
+    private forget;
+    listMailboxes(): Promise<MailboxSummary[]>;
+    /**
+     * Whether the account can store the bookkeeping keyword.
+     *
+     * `\*` in PERMANENTFLAGS means the server accepts arbitrary keywords. Some
+     * providers accept none at all, and there the new-mail tracking cannot work —
+     * better to say so than to tag silently into the void.
+     */
+    keywordSupported(permanentFlags: Set<string>): boolean;
+    get seenKeyword(): string;
+    get defaultMailbox(): string;
+    get maxMessages(): number;
+    get user(): string | undefined;
+    /**
+     * Reads the threading headers of one message, for linking a draft into an
+     * existing conversation.
+     *
+     * Only the Message-ID and the References chain are taken; nothing the sender
+     * wrote as prose comes back from here.
+     */
+    threadHeaders(mailbox: string | undefined, uid: number): Promise<{
+        messageId: string | undefined;
+        references: string[];
+    }>;
+    search(client: ImapConnection, query: SearchObject): Promise<number[]>;
+    /** Envelope-level fetch, newest UID first. */
+    fetchSummaries(client: ImapConnection, uids: number[]): Promise<FetchMessageObject[]>;
+    /**
+     * Adds the bookkeeping keyword to the given UIDs.
+     *
+     * This is the one write the server performs on its own initiative, and it
+     * stays available under the default IMAP_READ_ONLY: without it `list_new_messages`
+     * would return the same mail forever. It touches no flag a human interacts
+     * with — `\Seen` in particular is left alone.
+     */
+    tagSeen(client: ImapConnection, uids: number[]): Promise<void>;
+    close(): Promise<void>;
+}
+/** Rejects a promise that outlives the command timeout. */
+export declare function withTimeout<T>(promise: Promise<T>, command: string, ms?: number): Promise<T>;
+/**
+ * Normalises whatever imapflow threw into a {@link MailError}.
+ *
+ * Only the response text is carried over, never the whole error object: it
+ * holds the command that was sent, and for a LOGIN that means the password.
+ */
+export declare function asMailError(error: unknown): MailError;