@rndmjoker/proton-mcp 0.4.11 → 0.4.13

package/dist/mail/saved-attachments.js

@@ -0,0 +1,448 @@
+/**
+ * Attachments saved to this machine, and taking them away again.
+ *
+ * Saving means writing what Proton keeps encrypted, decrypted, to a disk. That
+ * is worth doing so an assistant can open a PDF or a spreadsheet rather than
+ * only say it exists, and it is bounded on every side:
+ *
+ * - **Only into a directory the user named**, in PROTON_MCP_ATTACHMENT_DIR, and
+ *   only through the environment: a setting in the web interface would be
+ *   within reach of an assistant, which gets that page's address. Without the
+ *   variable nothing is written and the tool says how to set it up.
+ * - **Nothing outside it.** A folder is checked after it is resolved, `..` is
+ *   refused, and so is a symbolic link anywhere on the way.
+ * - **The name comes from the sender** and is reduced to a plain one, with the
+ *   rule in mime/filenames.ts. An existing file is never replaced: the file is
+ *   created with O_EXCL, which also refuses to follow a link in its place.
+ * - **Readable by the user only**, 0600, and folders created here 0700.
+ * - **Gone again within the hour.** Decided by Tobi on 2026-11-02: a file lies
+ *   unattended for at most one hour, and is deleted when the server stops.
+ *   Better the assistant fetches it again than that it lies around for days.
+ *   A server that was killed leaves its files to the next one to start.
+ *
+ * What may be deleted is recorded per process, in this server's own
+ * configuration directory rather than in the directory the files go to. Each
+ * running server writes only its own record, so two of them never overwrite
+ * each other's. Before anything is deleted it is checked to be the very file
+ * that was saved: the same inode, size and modification time, a plain file and
+ * not a link. A file replaced or changed since is left where it is, because in
+ * the directory there may be files that are not ours.
+ *
+ * A folder created for a file goes again once it is empty, decided by Tobi on
+ * 2026-11-02: its name can say what was in it. Recorded like the files, with
+ * its inode, and removed with rmdir, which takes an empty folder and nothing
+ * else. A folder that was there before is never recorded and never removed.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, parse as parsePath, relative, resolve, sep } from 'node:path';
+import { BridgeError } from '../bridge/errors.js';
+import { plainFileName } from '../mime/filenames.js';
+/** How long a saved file may lie, fixed. */
+export const KEEP_MS = 60 * 60 * 1000;
+/** Proton accepts up to 25 MB per message, so no real attachment is larger. */
+export const MAX_SAVE_BYTES = 25 * 1024 * 1024;
+/** How long past its hour a file of a server that still runs is left to it. */
+const GRACE_MS = 10 * 60 * 1000;
+/** The variable that names the directory. */
+export const ATTACHMENT_DIR_VARIABLE = 'PROTON_MCP_ATTACHMENT_DIR';
+/** A refusal to save or delete, explained. Reported like any explained failure. */
+export class SaveRefused extends BridgeError {
+    name = 'SaveRefused';
+}
+/** Where the records live unless told otherwise. */
+export function defaultRecordDir() {
+    return join(homedir(), '.config', 'proton-mcp', 'saved-attachments');
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: it exists, it is merely not ours to signal.
+        return error.code === 'EPERM';
+    }
+}
+/** A file whose identity no longer matches the record is not ours to delete. */
+function deleteIfSame(entry) {
+    let info;
+    try {
+        info = lstatSync(entry.path);
+    }
+    catch {
+        return 'missing';
+    }
+    const same = info.isFile() &&
+        info.dev === entry.dev &&
+        info.ino === entry.ino &&
+        info.size === entry.size &&
+        info.mtimeMs === entry.mtimeMs;
+    if (!same)
+        return 'left';
+    try {
+        unlinkSync(entry.path);
+    }
+    catch {
+        // Not deletable, permissions for instance. Left and reported rather than
+        // letting one file stop the clearing up of all the others.
+        return 'left';
+    }
+    return 'deleted';
+}
+/**
+ * Removes the folders this server created that are empty now, deepest first,
+ * so that a parent can follow its child.
+ *
+ * rmdir and nothing stronger: whatever someone put into a folder keeps it
+ * standing. And only while it is still the folder that was created, the same
+ * inode, never a link in its place. Returns what went and what is left to
+ * watch; a folder that is gone or no longer ours is neither.
+ *
+ * The limit of that: a folder deleted and made again under the same name can
+ * get the same inode back, as it did on the CI's file system on 2026-11-02,
+ * and is then taken for the one created here. rmdir removes it only if it is
+ * empty. The time a folder was made would tell them apart, but where the file
+ * system does not keep it, Node reports the ctime instead, which changes as
+ * soon as a file inside goes, and no folder would ever be removed.
+ */
+function pruneFolders(folders) {
+    const removed = [];
+    const kept = [];
+    const deepestFirst = [...folders].sort((a, b) => b.path.split(sep).length - a.path.split(sep).length);
+    for (const folder of deepestFirst) {
+        let info;
+        try {
+            info = lstatSync(folder.path);
+        }
+        catch {
+            continue;
+        }
+        if (!info.isDirectory() || info.dev !== folder.dev || info.ino !== folder.ino)
+            continue;
+        try {
+            rmdirSync(folder.path);
+            removed.push(folder.path);
+        }
+        catch {
+            // Not empty, or not removable: watched until this server stops.
+            kept.push(folder);
+        }
+    }
+    return { removed, kept };
+}
+export class SavedAttachments {
+    #root;
+    #recordDir;
+    #now;
+    #pid;
+    #isAlive;
+    #startedAt;
+    #timers = new Map();
+    #entries = [];
+    #folders = [];
+    constructor(options) {
+        this.#root = options.root?.trim() || undefined;
+        this.#recordDir = options.recordDir ?? defaultRecordDir();
+        this.#now = options.now ?? Date.now;
+        this.#pid = options.pid ?? process.pid;
+        this.#isAlive = options.isAlive ?? processAlive;
+        this.#startedAt = new Date(this.#now()).toISOString();
+    }
+    /** Whether the user set a directory at all. */
+    get configured() {
+        return this.#root !== undefined;
+    }
+    /**
+     * Throws the explanation when nothing can be saved: no directory set, or one
+     * that is not there. Called before a message is fetched, so that nothing is
+     * decrypted only to be thrown away.
+     */
+    assertUsable() {
+        this.#realRoot();
+    }
+    /** This process's own record, named so that no two processes share one. */
+    get #recordPath() {
+        return join(this.#recordDir, `${this.#pid}-${Date.parse(this.#startedAt)}.json`);
+    }
+    /** The directory, resolved, or the reason it cannot be used. */
+    #realRoot() {
+        const root = this.#root;
+        if (root === undefined) {
+            throw new SaveRefused(`Saving attachments is not set up. The user has to set ${ATTACHMENT_DIR_VARIABLE} to a ` +
+                'directory, in the configuration this MCP server is started with, and restart the client. ' +
+                'Files are saved there and nowhere else. Until then an attachment can only be read with ' +
+                'get_attachment, and only when it is text.');
+        }
+        if (!isAbsolute(root)) {
+            throw new SaveRefused(`${ATTACHMENT_DIR_VARIABLE} has to be an absolute path, and "${root}" is not.`);
+        }
+        let real;
+        try {
+            real = realpathSync(root);
+        }
+        catch {
+            throw new SaveRefused(`${ATTACHMENT_DIR_VARIABLE} names "${root}", which does not exist. It is not created ` +
+                'here, so that a mistyped path does not quietly become a new place for mail to land.');
+        }
+        if (!statSync(real).isDirectory()) {
+            throw new SaveRefused(`${ATTACHMENT_DIR_VARIABLE} names "${root}", which is not a directory.`);
+        }
+        return real;
+    }
+    /**
+     * The folder to write into, inside the directory and nowhere else.
+     *
+     * Missing folders are created one level at a time, each checked before the
+     * next, so that no folder is ever created through a link pointing out.
+     */
+    #targetDir(folder) {
+        const real = this.#realRoot();
+        if (!folder)
+            return real;
+        const requested = resolve(isAbsolute(folder) ? folder : join(real, folder));
+        // Compared with the directory as given and as resolved: a directory that
+        // is itself reached through a link reads differently from either side.
+        const inside = [this.#root, real]
+            .map((base) => relative(base, requested))
+            .find((rel) => rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)));
+        if (inside === undefined) {
+            throw new SaveRefused(`"${folder}" is outside the directory set for attachments, ${this.#root}. Files are saved ` +
+                'there or in a folder inside it, never anywhere else.');
+        }
+        let current = real;
+        for (const part of inside.split(sep).filter(Boolean)) {
+            current = join(current, part);
+            let info;
+            try {
+                info = lstatSync(current);
+            }
+            catch {
+                mkdirSync(current, { mode: 0o700 });
+                const made = lstatSync(current);
+                this.#folders.push({ path: current, dev: made.dev, ino: made.ino });
+                continue;
+            }
+            if (info.isSymbolicLink()) {
+                throw new SaveRefused(`"${current}" is a symbolic link, and a folder reached through one is refused.`);
+            }
+            if (!info.isDirectory())
+                throw new SaveRefused(`"${current}" is not a folder.`);
+        }
+        return current;
+    }
+    /** Writes the record of this process, atomically, or removes it once empty. */
+    #writeRecord() {
+        if (this.#entries.length === 0 && this.#folders.length === 0) {
+            rmSync(this.#recordPath, { force: true });
+            return;
+        }
+        mkdirSync(this.#recordDir, { recursive: true, mode: 0o700 });
+        const record = {
+            pid: this.#pid,
+            startedAt: this.#startedAt,
+            entries: this.#entries,
+            folders: this.#folders,
+        };
+        const temporary = `${this.#recordPath}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, this.#recordPath);
+    }
+    /**
+     * Saves one attachment. Synchronous on purpose: the file and its record are
+     * written in one step, with nothing in between that could stop halfway.
+     */
+    save(name, content, contentType, folder) {
+        if (content.length > MAX_SAVE_BYTES) {
+            throw new SaveRefused(`The attachment is ${content.length} bytes, more than the ${MAX_SAVE_BYTES} this server saves.`);
+        }
+        try {
+            return this.#write(name, content, contentType, folder);
+        }
+        catch (error) {
+            // A folder made for a file that never arrived is not left behind.
+            this.#settleFolders();
+            throw error;
+        }
+    }
+    #write(name, content, contentType, folder) {
+        const directory = this.#targetDir(folder);
+        const plain = plainFileName(name, 'attachment');
+        const { name: stem, ext } = parsePath(plain);
+        for (let n = 1; n <= 100; n++) {
+            const path = join(directory, n === 1 ? plain : `${stem} (${n})${ext}`);
+            let fd;
+            try {
+                // O_EXCL: never an existing file, and never through a link in its place.
+                fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+            }
+            catch (error) {
+                if (error.code === 'EEXIST')
+                    continue;
+                throw error;
+            }
+            let ino;
+            try {
+                writeSync(fd, content);
+                ino = fstatSync(fd).ino;
+            }
+            finally {
+                closeSync(fd);
+            }
+            const info = lstatSync(path);
+            if (info.ino !== ino)
+                throw new SaveRefused(`"${path}" was replaced while it was being written.`);
+            const savedAt = this.#now();
+            const expiresAt = savedAt + KEEP_MS;
+            this.#entries.push({
+                path,
+                dev: info.dev,
+                ino: info.ino,
+                size: info.size,
+                mtimeMs: info.mtimeMs,
+                savedAt: new Date(savedAt).toISOString(),
+                expiresAt: new Date(expiresAt).toISOString(),
+            });
+            this.#writeRecord();
+            // Exactly on the hour rather than on the next sweep. Unref'd, so a
+            // waiting deletion never keeps the process alive.
+            this.#timers.set(path, setTimeout(() => this.#expire(path), KEEP_MS).unref());
+            return {
+                path,
+                size: info.size,
+                contentType,
+                sha256: createHash('sha256').update(content).digest('hex'),
+                expiresAt: new Date(expiresAt),
+            };
+        }
+        throw new SaveRefused(`There are already a hundred files named like "${plain}" in "${directory}".`);
+    }
+    /** Deletes one file whose hour is up, if it is still the one that was saved. */
+    #expire(path) {
+        this.#timers.delete(path);
+        const entry = this.#entries.find((e) => e.path === path);
+        if (!entry)
+            return;
+        deleteIfSame(entry);
+        this.#entries = this.#entries.filter((e) => e !== entry);
+        this.#settleFolders();
+    }
+    /** Removes the empty ones among the folders created here, and writes the record. */
+    #settleFolders() {
+        const { removed, kept } = pruneFolders(this.#folders);
+        this.#folders = kept;
+        this.#writeRecord();
+        return removed;
+    }
+    /** The record a path stands for, read the way save wrote it. */
+    #entryFor(path) {
+        const absolute = resolve(path);
+        const exact = this.#entries.find((e) => e.path === absolute);
+        if (exact)
+            return exact;
+        // The same file reached through a link in its folder's path.
+        try {
+            const real = join(realpathSync(dirname(absolute)), basename(absolute));
+            return this.#entries.find((e) => e.path === real);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Deletes what this server saved: everything, or the files named.
+     *
+     * A path it did not save is not touched, whatever it is.
+     */
+    delete(paths) {
+        const report = { deleted: [], left: [], missing: [], unknown: [], folders: [] };
+        const chosen = [];
+        if (paths === undefined) {
+            chosen.push(...this.#entries);
+        }
+        else {
+            for (const path of paths) {
+                const entry = this.#entryFor(path);
+                if (entry)
+                    chosen.push(entry);
+                else
+                    report.unknown.push(path);
+            }
+        }
+        for (const entry of chosen) {
+            const outcome = deleteIfSame(entry);
+            report[outcome === 'deleted' ? 'deleted' : outcome === 'left' ? 'left' : 'missing'].push(entry.path);
+            clearTimeout(this.#timers.get(entry.path));
+            this.#timers.delete(entry.path);
+        }
+        this.#entries = this.#entries.filter((e) => !chosen.includes(e));
+        report.folders = this.#settleFolders();
+        return report;
+    }
+    /**
+     * Clears up after other servers: everything of one that no longer runs, and
+     * what one that still runs has left lying well past its hour.
+     */
+    sweepOthers() {
+        let names;
+        try {
+            names = readdirSync(this.#recordDir);
+        }
+        catch {
+            return;
+        }
+        const own = basename(this.#recordPath);
+        for (const name of names) {
+            if (!name.endsWith('.json') || name === own)
+                continue;
+            const path = join(this.#recordDir, name);
+            let record;
+            try {
+                record = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            const dead = !this.#isAlive(record.pid);
+            const keep = [];
+            for (const entry of record.entries ?? []) {
+                const stale = this.#now() > Date.parse(entry.expiresAt) + GRACE_MS;
+                if (dead || stale)
+                    deleteIfSame(entry);
+                else
+                    keep.push(entry);
+            }
+            // The folders of a server that still runs stay its own business: it may
+            // be about to save into one of them.
+            if (dead)
+                pruneFolders(record.folders ?? []);
+            if (keep.length === 0) {
+                rmSync(path, { force: true });
+            }
+            else if (keep.length !== (record.entries ?? []).length) {
+                const temporary = `${path}.tmp`;
+                writeFileSync(temporary, `${JSON.stringify({ ...record, entries: keep }, null, 2)}\n`, { mode: 0o600 });
+                renameSync(temporary, path);
+            }
+        }
+    }
+    /** Called once at start: clears up what earlier servers left. */
+    start() {
+        this.sweepOthers();
+    }
+    /** Called on the way out: deletes everything this server saved. */
+    stop() {
+        for (const timer of this.#timers.values())
+            clearTimeout(timer);
+        this.#timers.clear();
+        if (this.#entries.length || this.#folders.length)
+            this.delete();
+        rmSync(this.#recordPath, { force: true });
+    }
+    /** What this server has saved and not yet deleted. */
+    get entries() {
+        return this.#entries;
+    }
+}
+//# sourceMappingURL=saved-attachments.js.map

package/dist/mail/saved-attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-attachments.js","sourceRoot":"","sources":["../../src/mail/saved-attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,UAAU,EACV,aAAa,EACb,SAAS,GACV,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,IAAI,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAC3G,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAErC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE9C,+EAA+E;AAC/E,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE/B,6CAA6C;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAA;AAElE,mFAAmF;AACnF,MAAM,OAAO,WAAY,SAAQ,WAAW;IACjC,IAAI,GAAG,aAAa,CAAA;CAC9B;AA6DD,oDAAoD;AACpD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAA;AACtE,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qDAAqD;QACrD,OAAQ,KAA2B,CAAC,IAAI,KAAK,OAAO,CAAA;IACtD,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,SAAS,YAAY,CAAC,KAAiB;IACrC,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,EAAE;QACb,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QACtB,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QACtB,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QACxB,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAAA;IAChC,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAA;IACxB,IAAI,CAAC;QACH,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,2DAA2D;QAC3D,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,YAAY,CAAC,OAAiC;IACrD,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,MAAM,IAAI,GAAoB,EAAE,CAAA;IAChC,MAAM,YAAY,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;IACrG,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAClC,IAAI,IAAI,CAAA;QACR,IAAI,CAAC;YACH,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;YAAE,SAAQ;QACvF,IAAI,CAAC;YACH,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;YAChE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACnB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,OAAO,gBAAgB;IAClB,KAAK,CAAoB;IACzB,UAAU,CAAQ;IAClB,IAAI,CAAc;IAClB,IAAI,CAAQ;IACZ,QAAQ,CAA0B;IAClC,UAAU,CAAQ;IAClB,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IACpD,QAAQ,GAAiB,EAAE,CAAA;IAC3B,QAAQ,GAAoB,EAAE,CAAA;IAE9B,YAAY,OAAgC;QAC1C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,CAAA;QAC9C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,EAAE,CAAA;QACzD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;QACnC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAA;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,YAAY,CAAA;QAC/C,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IACvD,CAAC;IAED,+CAA+C;IAC/C,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAA;IACjC,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,IAAI,CAAC,SAAS,EAAE,CAAA;IAClB,CAAC;IAED,2EAA2E;IAC3E,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;IAClF,CAAC;IAED,gEAAgE;IAChE,SAAS;QACP,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CACnB,yDAAyD,uBAAuB,QAAQ;gBACtF,2FAA2F;gBAC3F,yFAAyF;gBACzF,2CAA2C,CAC9C,CAAA;QACH,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,WAAW,CAAC,GAAG,uBAAuB,qCAAqC,IAAI,WAAW,CAAC,CAAA;QACvG,CAAC;QACD,IAAI,IAAI,CAAA;QACR,IAAI,CAAC;YACH,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,WAAW,CACnB,GAAG,uBAAuB,WAAW,IAAI,6CAA6C;gBACpF,qFAAqF,CACxF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAClC,MAAM,IAAI,WAAW,CAAC,GAAG,uBAAuB,WAAW,IAAI,8BAA8B,CAAC,CAAA;QAChG,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,MAA0B;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;QAC7B,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QAExB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,KAAe,EAAE,IAAI,CAAC;aACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;aACxC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC3E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,WAAW,CACnB,IAAI,MAAM,mDAAmD,IAAI,CAAC,KAAK,oBAAoB;gBACzF,sDAAsD,CACzD,CAAA;QACH,CAAC;QAED,IAAI,OAAO,GAAG,IAAI,CAAA;QAClB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAC7B,IAAI,IAAI,CAAA;YACR,IAAI,CAAC;gBACH,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;gBACnC,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;gBAC/B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;gBACnE,SAAQ;YACV,CAAC;YACD,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC1B,MAAM,IAAI,WAAW,CAAC,IAAI,OAAO,oEAAoE,CAAC,CAAA;YACxG,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,WAAW,CAAC,IAAI,OAAO,oBAAoB,CAAC,CAAA;QACjF,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,+EAA+E;IAC/E,YAAY;QACV,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACzC,OAAM;QACR,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC5D,MAAM,MAAM,GAAe;YACzB,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,OAAO,EAAE,IAAI,CAAC,QAAQ;YACtB,OAAO,EAAE,IAAI,CAAC,QAAQ;SACvB,CAAA;QACD,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,WAAW,MAAM,CAAA;QAC3C,aAAa,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QACjF,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;IACzC,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAY,EAAE,OAAe,EAAE,WAAmB,EAAE,MAAe;QACtE,IAAI,OAAO,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YACpC,MAAM,IAAI,WAAW,CACnB,qBAAqB,OAAO,CAAC,MAAM,yBAAyB,cAAc,qBAAqB,CAChG,CAAA;QACH,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,CAAA;QACxD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,kEAAkE;YAClE,IAAI,CAAC,cAAc,EAAE,CAAA;YACrB,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,OAAe,EAAE,WAAmB,EAAE,MAA0B;QACnF,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QACzC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;QAC/C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;QAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;YACtE,IAAI,EAAE,CAAA;YACN,IAAI,CAAC;gBACH,yEAAyE;gBACzE,EAAE,GAAG,QAAQ,CACX,IAAI,EACJ,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,EACvF,KAAK,CACN,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAK,KAA2B,CAAC,IAAI,KAAK,QAAQ;oBAAE,SAAQ;gBAC5D,MAAM,KAAK,CAAA;YACb,CAAC;YACD,IAAI,GAAG,CAAA;YACP,IAAI,CAAC;gBACH,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;gBACtB,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,GAAG,CAAA;YACzB,CAAC;oBAAS,CAAC;gBACT,SAAS,CAAC,EAAE,CAAC,CAAA;YACf,CAAC;YACD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;YAC5B,IAAI,IAAI,CAAC,GAAG,KAAK,GAAG;gBAAE,MAAM,IAAI,WAAW,CAAC,IAAI,IAAI,4CAA4C,CAAC,CAAA;YAEjG,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAC3B,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;YACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACjB,IAAI;gBACJ,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE;gBACxC,SAAS,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;aAC7C,CAAC,CAAA;YACF,IAAI,CAAC,YAAY,EAAE,CAAA;YACnB,mEAAmE;YACnE,kDAAkD;YAClD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;YAE7E,OAAO;gBACL,IAAI;gBACJ,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW;gBACX,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC1D,SAAS,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC;aAC/B,CAAA;QACH,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,iDAAiD,KAAK,SAAS,SAAS,IAAI,CAAC,CAAA;IACrG,CAAC;IAED,gFAAgF;IAChF,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;QACxD,IAAI,CAAC,KAAK;YAAE,OAAM;QAClB,YAAY,CAAC,KAAK,CAAC,CAAA;QACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAA;QACxD,IAAI,CAAC,cAAc,EAAE,CAAA;IACvB,CAAC;IAED,oFAAoF;IACpF,cAAc;QACZ,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACrD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,IAAI,CAAC,YAAY,EAAE,CAAA;QACnB,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,gEAAgE;IAChE,SAAS,CAAC,IAAY;QACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAA;QAC5D,IAAI,KAAK;YAAE,OAAO,KAAK,CAAA;QACvB,6DAA6D;QAC7D,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;YACtE,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAgB;QACrB,MAAM,MAAM,GAAiB,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;QAC7F,MAAM,MAAM,GAAiB,EAAE,CAAA;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/B,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;gBAClC,IAAI,KAAK;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;;oBACxB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAChC,CAAC;QACH,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;YACnC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACpG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;YAC1C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACjC,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;QAChE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;QACtC,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,IAAI,KAAe,CAAA;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,GAAG;gBAAE,SAAQ;YACrD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;YACxC,IAAI,MAAkB,CAAA;YACtB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAe,CAAA;YAC/D,CAAC;YAAC,MAAM,CAAC;gBACP,SAAQ;YACV,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACvC,MAAM,IAAI,GAAiB,EAAE,CAAA;YAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAA;gBAClE,IAAI,IAAI,IAAI,KAAK;oBAAE,YAAY,CAAC,KAAK,CAAC,CAAA;;oBACjC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACvB,CAAC;YACD,wEAAwE;YACxE,qCAAqC;YACrC,IAAI,IAAI;gBAAE,YAAY,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;YAC5C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YAC/B,CAAC;iBAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;gBACzD,MAAM,SAAS,GAAG,GAAG,IAAI,MAAM,CAAA;gBAC/B,aAAa,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;gBACvG,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,KAAK;QACH,IAAI,CAAC,WAAW,EAAE,CAAA;IACpB,CAAC;IAED,mEAAmE;IACnE,IAAI;QACF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,YAAY,CAAC,KAAK,CAAC,CAAA;QAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,EAAE,CAAA;QAC/D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3C,CAAC;IAED,sDAAsD;IACtD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;CACF"}

package/dist/mail/search.d.ts

@@ -12,10 +12,32 @@
  *
  * Metadata queries are cheap by comparison: unread came back in 3 ms, a size
  * filter in 437 ms.
+ *
+ * Text is the exception to "the Bridge searches". Measured on 2026-11-02 and
+ * read in the source of gluon, its IMAP library: SUBJECT, FROM and TO compare
+ * against the header as it is stored, and a header with one letter outside
+ * ASCII is stored encoded, "Mit Anhang" as "Mit_Anhang", or in base64, where no
+ * word is legible at all. Up to 0.4.11 a subject search for "Mit Anhang" found
+ * nothing, and the answer read like a search without matches. So the Bridge
+ * now filters by everything but those three, and this server compares them
+ * against the envelope, which imapflow decodes. Full text stays with the
+ * Bridge, which compares the raw bytes; a word outside ASCII is also asked for
+ * in the form a quoted-printable part carries it, and a part sent as base64
+ * stays out of reach, which every answer says.
  */
 import type { SearchObject } from 'imapflow';
 import type { Connection } from '../bridge/connection.js';
-import { type MessageHeader, type OrderingCost } from './messages.js';
+import { type EnvelopeEntry, type MessageHeader, type OrderingCost } from './messages.js';
+/**
+ * How many envelopes a search compares itself, at most.
+ *
+ * Without other criteria a subject search reads the envelope of every message
+ * in the mailbox. Reading one per hit is what the ordering has always cost, and
+ * a common word matched 6803 messages in a mailbox of 26816, but there has to
+ * be an end. Past it, the most recently added messages are compared and the
+ * answer says so; there is no silent cut.
+ */
+export declare const MAX_COMPARED = 20000;
 export interface SearchCriteria {
     /** Free text, searched in the body and in headers. The expensive part. */
     text?: string;
@@ -58,9 +80,51 @@ export interface SearchResult {
     ordering: OrderingCost;
     /** True when the search included a full-text term, which is the slow case. */
     fullText: boolean;
+    /** True when a full-text word was also asked for in its quoted-printable form. */
+    encodedForms: boolean;
+    /** Set when not every candidate was compared, see MAX_COMPARED. */
+    compared?: {
+        compared: number;
+        of: number;
+    };
+}
+/** What this server compares itself, against the decoded envelope. */
+export interface LocalMatch {
+    subject?: string;
+    from?: string;
+    to?: string;
 }
-/** Translates the criteria into what imapflow expects. */
-export declare function buildQuery(criteria: SearchCriteria): SearchObject;
+/** What the Bridge is asked, and what is left to compare here. */
+export interface PlannedSearch {
+    query: SearchObject;
+    local: LocalMatch;
+}
+/**
+ * A word as a quoted-printable part carries it: every byte of its UTF-8 form
+ * outside printable ASCII, and the equals sign, as =XX.
+ */
+export declare function quotedPrintable(text: string): string;
+/**
+ * The forms a full-text word is asked for in.
+ *
+ * The Bridge compares the raw bytes of a message, lower cased, so a word with a
+ * letter outside ASCII is found only where a part carries it unencoded. Most
+ * text with umlauts travels as quoted-printable, where a u with umlaut is the
+ * six characters "=C3=BC" and an a with umlaut "=C3=A4". Lower casing does not reach into
+ * that encoding, so the usual spellings of a word are each asked for: as given,
+ * in lower case, and capitalised. Forms that differ only in the case of ASCII
+ * letters are asked once, since the Bridge lower cases both sides. A word
+ * broken across a line by the encoding is still missed, and so is anything in
+ * base64.
+ */
+export declare function textForms(term: string): string[];
+/** Whether a message passes what this server compares itself. */
+export declare function matchesLocally(entry: EnvelopeEntry, local: LocalMatch): boolean;
+/**
+ * Splits the criteria into what the Bridge is asked and what this server
+ * compares itself.
+ */
+export declare function planSearch(criteria: SearchCriteria): PlannedSearch;
 /** Whether a query contains the expensive full-text part. */
 export declare function isFullText(criteria: SearchCriteria): boolean;
 export interface SearchOptions extends SearchCriteria {