@rndmjoker/proton-mcp 0.4.4

package/dist/bridge/certificate.js

@@ -0,0 +1,176 @@
+/**
+ * Pinning the Bridge's self-signed certificate.
+ *
+ * The problem: the Bridge generates its own certificate and keeps it inside its
+ * encrypted vault rather than on disk, so it cannot be trusted in advance. The
+ * lazy answer is to switch verification off and never look again, which means
+ * anything that manages to listen on the port gets the Bridge password.
+ *
+ * The answer here is trust on first use. On the first connection the certificate
+ * is fetched and its fingerprint recorded. From then on it is pinned: Node
+ * verifies against that one certificate and nothing else. A changed certificate
+ * stops the server with an explanation instead of being waved through.
+ *
+ * Fetching needs a STARTTLS handshake of our own, because imapflow does not hand
+ * the certificate out. Verified against Bridge 03.25.00: checkServerIdentity is
+ * never invoked while verification is off, and the certificate is not attached
+ * to the verification error either.
+ */
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { BridgeError } from './errors.js';
+/** Where the pinned certificate is stored. Next to the credentials file. */
+export function pinPath(env = process.env) {
+    if (env.PROTON_MCP_CERT_FILE)
+        return env.PROTON_MCP_CERT_FILE;
+    return join(homedir(), '.config', 'proton-mcp', 'known-certificate.json');
+}
+/** Turns a DER certificate into the PEM form Node expects as a CA. */
+export function toPem(der) {
+    const base64 = der.toString('base64');
+    const lines = base64.match(/.{1,64}/g) ?? [];
+    return `-----BEGIN CERTIFICATE-----\n${lines.join('\n')}\n-----END CERTIFICATE-----\n`;
+}
+/**
+ * Fetches the certificate by doing the STARTTLS dance manually.
+ *
+ * Deliberately minimal: it reads the greeting, sends STARTTLS, waits for the OK
+ * and upgrades. It does not log in, so no credentials are involved at this
+ * point.
+ */
+export function fetchCertificate(host, port, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const socket = netConnect({ host, port });
+        let settled = false;
+        let stage = 'greeting';
+        let buffer = '';
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else if (value)
+                resolve(value);
+        };
+        const timer = setTimeout(() => {
+            finish(new BridgeError(`The Bridge at ${host}:${port} did not answer within ${timeoutMs} ms while reading its certificate. ` +
+                'Check that it is running and unlocked.'));
+        }, timeoutMs);
+        socket.on('error', (error) => finish(error));
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            if (stage === 'greeting') {
+                // The greeting is a single untagged line.
+                if (!buffer.includes('\r\n'))
+                    return;
+                if (!/^\* (OK|PREAUTH)/i.test(buffer)) {
+                    finish(new BridgeError(`${host}:${port} did not answer like an IMAP server. Received: ${buffer.slice(0, 80).trim()}`));
+                    return;
+                }
+                buffer = '';
+                stage = 'starttls';
+                socket.write('A1 STARTTLS\r\n');
+                return;
+            }
+            if (!/^A1 /m.test(buffer))
+                return;
+            if (!/^A1 OK/im.test(buffer)) {
+                finish(new BridgeError(`${host}:${port} refused STARTTLS. Received: ${buffer.slice(0, 80).trim()}. ` +
+                    'The Bridge normally requires STARTTLS, so this port may belong to something else.'));
+                return;
+            }
+            // Encoding was set for the plaintext part, and it has to go before the
+            // socket is handed to the TLS layer.
+            socket.setEncoding(null);
+            const secure = tlsConnect({
+                socket,
+                // The point of this connection is to look at the certificate, so it
+                // cannot be validated beforehand. Nothing is sent over it.
+                rejectUnauthorized: false,
+            }, () => {
+                const cert = secure.getPeerCertificate();
+                if (!cert || !cert.raw) {
+                    finish(new BridgeError(`${host}:${port} presented no certificate.`));
+                    return;
+                }
+                // A certificate may carry several common names, in which case Node
+                // hands over an array.
+                const cn = cert.subject?.CN;
+                const value = {
+                    fingerprint256: cert.fingerprint256,
+                    pem: toPem(cert.raw),
+                    subject: Array.isArray(cn) ? cn.join(', ') : (cn ?? JSON.stringify(cert.subject ?? {})),
+                    validTo: cert.valid_to ?? '',
+                };
+                secure.destroy();
+                finish(undefined, value);
+            });
+            secure.on('error', (error) => finish(error));
+        });
+    });
+}
+/** Reads the pinned certificate. Absence means nothing has been pinned yet. */
+export function loadPinned(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed.fingerprint256 || !parsed.pem)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Records a certificate as trusted. */
+export function savePinned(path, entry) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+}
+/** The message shown when the certificate no longer matches. */
+export function mismatchMessage(pinned, actual, path) {
+    return (`The certificate of the Bridge at ${pinned.host}:${pinned.port} has changed. Refusing to connect.\n\n` +
+        `  expected: ${pinned.fingerprint256}\n` +
+        `  received: ${actual.fingerprint256}\n\n` +
+        `The expected one was recorded on ${pinned.firstSeen.slice(0, 10)}.\n\n` +
+        'If you reinstalled Proton Mail Bridge or moved to a different machine, this is expected. ' +
+        `Delete ${path} and the next connection will record the new certificate.\n\n` +
+        'If you did not change anything, do not delete it. Something else may be listening on that port, ' +
+        'and it would receive your Bridge password.');
+}
+/**
+ * Makes sure the certificate is known, and returns it for use as a CA.
+ *
+ * On first use it records what it finds, which is the only moment this is
+ * open to a machine-in-the-middle. Every later connection is pinned.
+ */
+export async function ensurePinned(host, port, options = {}) {
+    const path = options.path ?? pinPath();
+    const pinned = loadPinned(path);
+    const actual = await (options.fetch ?? fetchCertificate)(host, port);
+    if (!pinned || pinned.host !== host || pinned.port !== port) {
+        const entry = {
+            host,
+            port,
+            fingerprint256: actual.fingerprint256,
+            pem: actual.pem,
+            subject: actual.subject,
+            validTo: actual.validTo,
+            firstSeen: (options.now?.() ?? new Date()).toISOString(),
+        };
+        savePinned(path, entry);
+        options.onFirstUse?.(entry);
+        return entry;
+    }
+    if (pinned.fingerprint256 !== actual.fingerprint256) {
+        throw new BridgeError(mismatchMessage(pinned, actual, path));
+    }
+    return pinned;
+}
+//# sourceMappingURL=certificate.js.map

package/dist/bridge/certificate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate.js","sourceRoot":"","sources":["../../src/bridge/certificate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,UAAU,CAAA;AAChD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAwB,MAAM,UAAU,CAAA;AACtE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAiBzC,4EAA4E;AAC5E,MAAM,UAAU,OAAO,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC1D,IAAI,GAAG,CAAC,oBAAoB;QAAE,OAAO,GAAG,CAAC,oBAAoB,CAAA;IAC7D,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,wBAAwB,CAAC,CAAA;AAC3E,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAA;IAC5C,OAAO,gCAAgC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,+BAA+B,CAAA;AACxF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,IAAY,EACZ,SAAS,GAAG,MAAM;IAElB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QACzC,IAAI,OAAO,GAAG,KAAK,CAAA;QACnB,IAAI,KAAK,GAA4B,UAAU,CAAA;QAC/C,IAAI,MAAM,GAAG,EAAE,CAAA;QAEf,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,KAAoD,EAAE,EAAE;YACrF,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,IAAI,KAAK;gBAAE,MAAM,CAAC,KAAK,CAAC,CAAA;iBACnB,IAAI,KAAK;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC,CAAA;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CACJ,IAAI,WAAW,CACb,iBAAiB,IAAI,IAAI,IAAI,0BAA0B,SAAS,qCAAqC;gBACnG,wCAAwC,CAC3C,CACF,CAAA;QACH,CAAC,EAAE,SAAS,CAAC,CAAA;QAEb,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAC5C,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;QAE1B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,MAAM,IAAI,KAAK,CAAA;YAEf,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzB,0CAA0C;gBAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAAE,OAAM;gBACpC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtC,MAAM,CACJ,IAAI,WAAW,CACb,GAAG,IAAI,IAAI,IAAI,kDAAkD,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAC9F,CACF,CAAA;oBACD,OAAM;gBACR,CAAC;gBACD,MAAM,GAAG,EAAE,CAAA;gBACX,KAAK,GAAG,UAAU,CAAA;gBAClB,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAA;gBAC/B,OAAM;YACR,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,OAAM;YACjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,MAAM,CACJ,IAAI,WAAW,CACb,GAAG,IAAI,IAAI,IAAI,gCAAgC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI;oBAC3E,mFAAmF,CACtF,CACF,CAAA;gBACD,OAAM;YACR,CAAC;YAED,uEAAuE;YACvE,qCAAqC;YACrC,MAAM,CAAC,WAAW,CAAC,IAAiC,CAAC,CAAA;YAErD,MAAM,MAAM,GAAG,UAAU,CACvB;gBACE,MAAM;gBACN,oEAAoE;gBACpE,2DAA2D;gBAC3D,kBAAkB,EAAE,KAAK;aAC1B,EACD,GAAG,EAAE;gBACH,MAAM,IAAI,GAAoB,MAAM,CAAC,kBAAkB,EAAE,CAAA;gBACzD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;oBACvB,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,IAAI,IAAI,IAAI,4BAA4B,CAAC,CAAC,CAAA;oBACpE,OAAM;gBACR,CAAC;gBACD,mEAAmE;gBACnE,uBAAuB;gBACvB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,CAAA;gBAC3B,MAAM,KAAK,GAAG;oBACZ,cAAc,EAAE,IAAI,CAAC,cAAc;oBACnC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;oBACpB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;oBACvF,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE;iBAC7B,CAAA;gBACD,MAAM,CAAC,OAAO,EAAE,CAAA;gBAChB,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YAC1B,CAAC,CACF,CAAA;YACD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QAC9C,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAsB,CAAA;QAC1E,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,GAAG;YAAE,OAAO,SAAS,CAAA;QAC3D,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAwB;IAC/D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1D,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;AAC7E,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAC7B,MAAyB,EACzB,MAAmD,EACnD,IAAY;IAEZ,OAAO,CACL,oCAAoC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,wCAAwC;QACtG,eAAe,MAAM,CAAC,cAAc,IAAI;QACxC,eAAe,MAAM,CAAC,cAAc,MAAM;QAC1C,oCAAoC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO;QACxE,2FAA2F;QAC3F,UAAU,IAAI,+DAA+D;QAC7E,kGAAkG;QAClG,4CAA4C,CAC7C,CAAA;AACH,CAAC;AAcD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,IAAY,EACZ,OAAO,GAAkB,EAAE;IAE3B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,EAAE,CAAA;IACtC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAEpE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAsB;YAC/B,IAAI;YACJ,IAAI;YACJ,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE;SACzD,CAAA;QACD,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACvB,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;QAC3B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc,EAAE,CAAC;QACpD,MAAM,IAAI,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IAC9D,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/bridge/connection.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Connection to the Bridge's IMAP interface.
+ *
+ * One connection is held for the whole process rather than opened per call:
+ * the Bridge dislikes connection churn and the handshake costs time. If the
+ * Bridge was restarted or the socket died in between, the next call rebuilds
+ * it transparently.
+ */
+import { ImapFlow } from 'imapflow';
+import type { Config, BridgeCredentials } from '../config.js';
+import { BridgeError } from './errors.js';
+/** Thrown when a tool is used before anyone has signed in. */
+export declare class NotSignedInError extends BridgeError {
+    name: string;
+}
+/** A mailbox as reported by the Bridge. */
+export interface Mailbox {
+    /** The full IMAP path, for example "Folders/Receipts/Invoices". */
+    path: string;
+    /** The last path segment, for example "Invoices". */
+    name: string;
+    /** Which kind of mailbox this is. Proton treats folders and labels as different things. */
+    kind: 'system' | 'folder' | 'label';
+    /** For system mailboxes, the IMAP special-use attribute, for example "\\Inbox". */
+    specialUse?: string;
+    /** Whether the mailbox can hold messages. The "Folders" and "Labels" containers cannot. */
+    selectable: boolean;
+}
+/** Counters for a mailbox, cheap to obtain. */
+export interface MailboxStatus {
+    path: string;
+    messages: number;
+    unseen: number;
+    /** Changes when the Bridge renumbers UIDs, which invalidates every cached UID. */
+    uidValidity: string;
+    uidNext: number;
+}
+/**
+ * Maps an IMAP path onto what it means in Proton.
+ *
+ * Proton exposes user folders below "Folders/" and labels below "Labels/".
+ * Everything else is a system mailbox.
+ */
+export declare function determineKind(path: string): Mailbox['kind'];
+/** Whether an address keeps traffic on this machine. */
+export declare function isLocal(host: string): boolean;
+/**
+ * Decides whether a failure is worth one retry on a fresh connection.
+ *
+ * Only transport-level problems qualify. A rejected login or a missing
+ * mailbox would fail again on a new connection, and retrying would only
+ * double the waiting time before the user sees the real reason.
+ */
+export declare function isTransportFailure(error: unknown): boolean;
+export declare class Connection {
+    #private;
+    private readonly config;
+    /**
+     * Supplies the credentials, or nothing when no one has signed in.
+     *
+     * A function rather than a value: they can arrive through the web interface
+     * long after the server started, and they can be revoked while it runs.
+     */
+    private readonly getCredentials;
+    /** Where notices go. stderr, never stdout, which carries the protocol. */
+    private readonly notify;
+    constructor(config: Config, 
+    /**
+     * Supplies the credentials, or nothing when no one has signed in.
+     *
+     * A function rather than a value: they can arrive through the web interface
+     * long after the server started, and they can be revoked while it runs.
+     */
+    getCredentials: () => Promise<BridgeCredentials | undefined>, 
+    /** Where notices go. stderr, never stdout, which carries the protocol. */
+    notify?: (message: string) => void);
+    /** Opens the connection unless a usable one is already there. */
+    open(): Promise<ImapFlow>;
+    /** Lists every mailbox. */
+    listMailboxes(): Promise<Mailbox[]>;
+    /**
+     * Counters for a mailbox without selecting it.
+     *
+     * Needed before every fetch: the Bridge answers `FETCH 1:*` on an empty
+     * mailbox with `BAD no such message` instead of an empty result, so the
+     * count has to be known in advance.
+     */
+    status(path: string): Promise<MailboxStatus>;
+    /**
+     * Opens a mailbox, runs `operation` and releases the lock afterwards.
+     *
+     * A single IMAP connection has exactly one selected mailbox, so concurrent
+     * calls would otherwise pull the rug out from under each other. imapflow
+     * serialises this via a lock, and every mailbox access goes through here.
+     */
+    withMailbox<T>(path: string, operation: (client: ImapFlow, status: MailboxStatus) => Promise<T>): Promise<T>;
+    /** Closes the connection if one is open. */
+    close(): Promise<void>;
+}

package/dist/bridge/connection.js

@@ -0,0 +1,244 @@
+/**
+ * Connection to the Bridge's IMAP interface.
+ *
+ * One connection is held for the whole process rather than opened per call:
+ * the Bridge dislikes connection churn and the handshake costs time. If the
+ * Bridge was restarted or the socket died in between, the next call rebuilds
+ * it transparently.
+ */
+import { ImapFlow } from 'imapflow';
+import { explainError, BridgeError } from './errors.js';
+import { ensurePinned } from './certificate.js';
+/** Thrown when a tool is used before anyone has signed in. */
+export class NotSignedInError extends BridgeError {
+    name = 'NotSignedInError';
+}
+/**
+ * Maps an IMAP path onto what it means in Proton.
+ *
+ * Proton exposes user folders below "Folders/" and labels below "Labels/".
+ * Everything else is a system mailbox.
+ */
+export function determineKind(path) {
+    if (path === 'Folders' || path.startsWith('Folders/'))
+        return 'folder';
+    if (path === 'Labels' || path.startsWith('Labels/'))
+        return 'label';
+    return 'system';
+}
+/** Whether an address keeps traffic on this machine. */
+export function isLocal(host) {
+    return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+}
+/**
+ * Decides whether a failure is worth one retry on a fresh connection.
+ *
+ * Only transport-level problems qualify. A rejected login or a missing
+ * mailbox would fail again on a new connection, and retrying would only
+ * double the waiting time before the user sees the real reason.
+ */
+export function isTransportFailure(error) {
+    const e = error;
+    const code = e?.code ?? '';
+    if (['ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ECONNREFUSED', 'ERR_STREAM_DESTROYED'].includes(code)) {
+        return true;
+    }
+    return /socket|connection closed|not connected|disconnected/i.test(e?.message ?? '');
+}
+export class Connection {
+    config;
+    getCredentials;
+    notify;
+    #client;
+    /** Guards against several callers opening a connection at the same time. */
+    #opening;
+    constructor(config, 
+    /**
+     * Supplies the credentials, or nothing when no one has signed in.
+     *
+     * A function rather than a value: they can arrive through the web interface
+     * long after the server started, and they can be revoked while it runs.
+     */
+    getCredentials, 
+    /** Where notices go. stderr, never stdout, which carries the protocol. */
+    notify = (m) => process.stderr.write(`proton-mcp: ${m}\n`)) {
+        this.config = config;
+        this.getCredentials = getCredentials;
+        this.notify = notify;
+    }
+    /** Opens the connection unless a usable one is already there. */
+    async open() {
+        if (this.#client?.usable)
+            return this.#client;
+        // A second caller waits for the first attempt instead of starting its own.
+        if (this.#opening)
+            return this.#opening;
+        this.#opening = this.#connect().finally(() => {
+            this.#opening = undefined;
+        });
+        return this.#opening;
+    }
+    async #connect() {
+        const credentials = await this.getCredentials();
+        if (!credentials) {
+            throw new NotSignedInError('No Bridge credentials are available yet, so there is nothing to connect with.');
+        }
+        // The Bridge only ever listens on the loopback interface. A different host
+        // means either a tunnel or a misconfiguration, and in the second case the
+        // Bridge password would go somewhere it does not belong.
+        if (!isLocal(this.config.host)) {
+            this.notify(`BRIDGE_HOST is "${this.config.host}", which is not this machine. ` +
+                'Proton Mail Bridge only listens on 127.0.0.1, so this only makes sense if you ' +
+                'deliberately put a tunnel in front of it. Otherwise correct BRIDGE_HOST.');
+        }
+        // Pin the certificate before handing over any credentials. On first use this
+        // records what it finds, afterwards it verifies. A changed certificate stops
+        // us here rather than after the password has gone out.
+        const pinned = await ensurePinned(this.config.host, this.config.imapPort, {
+            onFirstUse: (entry) => this.notify(`recorded the Bridge certificate on first use, fingerprint ${entry.fingerprint256}. ` +
+                'Further connections are verified against it.'),
+        });
+        const client = new ImapFlow({
+            host: this.config.host,
+            port: this.config.imapPort,
+            // The Bridge expects a plaintext connection upgraded via STARTTLS,
+            // not a direct TLS handshake.
+            secure: false,
+            auth: { user: credentials.user, pass: credentials.pass },
+            tls: {
+                // Verified against exactly one certificate: the pinned one. This is
+                // stricter than the public trust store, which would accept any
+                // certificate signed by any recognised authority.
+                rejectUnauthorized: true,
+                ca: [pinned.pem],
+                // The Bridge's certificate does not carry 127.0.0.1 as a name, so the
+                // hostname check has to be skipped. It adds nothing on top of pinning:
+                // matching a specific certificate is a stronger statement than matching
+                // a name inside it.
+                checkServerIdentity: () => undefined,
+            },
+            // No logging: the library would otherwise write headers and subject
+            // lines to stderr.
+            logger: false,
+        });
+        // Without a listener, a socket error after a successful connect would
+        // become an unhandled event and take down the process.
+        client.on('error', () => {
+            // The state is checked via client.usable before every use, so the next
+            // call rebuilds the connection. Nothing to do here beyond not crashing.
+        });
+        try {
+            await client.connect();
+        }
+        catch (error) {
+            throw explainError(error, this.config.host, this.config.imapPort);
+        }
+        this.#client = client;
+        return client;
+    }
+    /**
+     * Runs an operation and retries it once on a fresh connection if the
+     * transport failed. That is the case when the Bridge was restarted between
+     * two calls, which is common: it goes down with the machine and comes back
+     * locked.
+     */
+    async #withRetry(operation) {
+        const client = await this.open();
+        try {
+            return await operation(client);
+        }
+        catch (error) {
+            if (!isTransportFailure(error)) {
+                throw error instanceof BridgeError
+                    ? error
+                    : explainError(error, this.config.host, this.config.imapPort);
+            }
+            // Drop the dead connection and try exactly once more.
+            this.#client = undefined;
+            const fresh = await this.open();
+            try {
+                return await operation(fresh);
+            }
+            catch (again) {
+                throw explainError(again, this.config.host, this.config.imapPort);
+            }
+        }
+    }
+    /** Lists every mailbox. */
+    async listMailboxes() {
+        const raw = await this.#withRetry((client) => client.list());
+        return raw.map((box) => {
+            const path = box.path;
+            const segments = path.split('/');
+            const entry = {
+                path,
+                name: segments[segments.length - 1] ?? path,
+                kind: determineKind(path),
+                selectable: !box.flags.has('\\Noselect'),
+            };
+            if (box.specialUse)
+                entry.specialUse = box.specialUse;
+            return entry;
+        });
+    }
+    /**
+     * Counters for a mailbox without selecting it.
+     *
+     * Needed before every fetch: the Bridge answers `FETCH 1:*` on an empty
+     * mailbox with `BAD no such message` instead of an empty result, so the
+     * count has to be known in advance.
+     */
+    async status(path) {
+        const st = await this.#withRetry((client) => client.status(path, { messages: true, unseen: true, uidValidity: true, uidNext: true }));
+        return {
+            path,
+            messages: st.messages ?? 0,
+            unseen: st.unseen ?? 0,
+            // uidValidity arrives as a BigInt and is only ever compared, never
+            // calculated with, so a string is the honest representation.
+            uidValidity: String(st.uidValidity ?? ''),
+            uidNext: st.uidNext ?? 0,
+        };
+    }
+    /**
+     * Opens a mailbox, runs `operation` and releases the lock afterwards.
+     *
+     * A single IMAP connection has exactly one selected mailbox, so concurrent
+     * calls would otherwise pull the rug out from under each other. imapflow
+     * serialises this via a lock, and every mailbox access goes through here.
+     */
+    async withMailbox(path, operation) {
+        const status = await this.status(path);
+        return this.#withRetry(async (client) => {
+            let lock;
+            try {
+                lock = await client.getMailboxLock(path);
+            }
+            catch (error) {
+                throw new BridgeError(`The mailbox "${path}" could not be opened. Check the exact spelling; ` +
+                    'user folders live below "Folders/" and labels below "Labels/". ' +
+                    'Use list_folders to see the available paths.', 'none', { cause: error });
+            }
+            try {
+                return await operation(client, status);
+            }
+            finally {
+                lock.release();
+            }
+        });
+    }
+    /** Closes the connection if one is open. */
+    async close() {
+        const client = this.#client;
+        this.#client = undefined;
+        if (!client)
+            return;
+        try {
+            await client.logout();
+        }
+        catch {
+            // While shutting down, a failed logout attempt does not matter.
+        }
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/bridge/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/bridge/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAA6C,MAAM,UAAU,CAAA;AAE9E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE/C,8DAA8D;AAC9D,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IACtC,IAAI,GAAG,kBAAkB,CAAA;CACnC;AA0BD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,QAAQ,CAAA;IACtE,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,OAAO,CAAA;IACnE,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,WAAW,CAAA;AACvE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,CAAC,GAAG,KAA4C,CAAA;IACtD,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,CAAA;IAC1B,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAChG,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,sDAAsD,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC,CAAA;AACtF,CAAC;AAED,MAAM,OAAO,UAAU;IAMF,MAAM;IAON,cAAc;IAEd,MAAM;IAdzB,OAAO,CAAsB;IAC7B,4EAA4E;IAC5E,QAAQ,CAA+B;IAEvC,YACmB,MAAc;IAC/B;;;;;OAKG;IACc,cAA4D;IAC7E,0EAA0E;IACzD,MAAM,GAA8B,CAAC,CAAC,EAAE,EAAE,CACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC;sBAV3B,MAAM;8BAON,cAAc;sBAEd,MAAM;IAEtB,CAAC;IAEJ,iEAAiE;IACjE,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM;YAAE,OAAO,IAAI,CAAC,OAAO,CAAA;QAC7C,2EAA2E;QAC3E,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAA;QAEvC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC3C,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;QAC3B,CAAC,CAAC,CAAA;QACF,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAA;QAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,gBAAgB,CACxB,+EAA+E,CAChF,CAAA;QACH,CAAC;QAED,2EAA2E;QAC3E,0EAA0E;QAC1E,yDAAyD;QACzD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CACT,mBAAmB,IAAI,CAAC,MAAM,CAAC,IAAI,gCAAgC;gBACjE,gFAAgF;gBAChF,0EAA0E,CAC7E,CAAA;QACH,CAAC;QAED,6EAA6E;QAC7E,6EAA6E;QAC7E,uDAAuD;QACvD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;YACxE,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CACpB,IAAI,CAAC,MAAM,CACT,6DAA6D,KAAK,CAAC,cAAc,IAAI;gBACnF,8CAA8C,CACjD;SACJ,CAAC,CAAA;QAEF,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YAC1B,mEAAmE;YACnE,8BAA8B;YAC9B,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE;YACxD,GAAG,EAAE;gBACH,oEAAoE;gBACpE,+DAA+D;gBAC/D,kDAAkD;gBAClD,kBAAkB,EAAE,IAAI;gBACxB,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC;gBAChB,sEAAsE;gBACtE,uEAAuE;gBACvE,wEAAwE;gBACxE,oBAAoB;gBACpB,mBAAmB,EAAE,GAAG,EAAE,CAAC,SAAS;aACrC;YACD,oEAAoE;YACpE,mBAAmB;YACnB,MAAM,EAAE,KAAK;SACd,CAAC,CAAA;QAEF,sEAAsE;QACtE,uDAAuD;QACvD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,uEAAuE;YACvE,wEAAwE;QAC1E,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACnE,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAI,SAA2C;QAC7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAA;QAChC,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,YAAY,WAAW;oBAChC,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YACjE,CAAC;YACD,sDAAsD;YACtD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;YACxB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAA;YAC/B,IAAI,CAAC;gBACH,OAAO,MAAM,SAAS,CAAC,KAAK,CAAC,CAAA;YAC/B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YACnE,CAAC;QACH,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,aAAa;QACjB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAiB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;QAE5E,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACrB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAA;YACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAChC,MAAM,KAAK,GAAY;gBACrB,IAAI;gBACJ,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI;gBAC3C,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC;gBACzB,UAAU,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC;aACzC,CAAA;YACD,IAAI,GAAG,CAAC,UAAU;gBAAE,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAA;YACrD,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,EAAE,CAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CACxF,CAAA;QACD,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE,EAAE,CAAC,QAAQ,IAAI,CAAC;YAC1B,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC;YACtB,mEAAmE;YACnE,6DAA6D;YAC7D,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC;YACzC,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC;SACzB,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,SAAkE;QAElE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACtC,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YACtC,IAAI,IAAuB,CAAA;YAC3B,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;YAC1C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,WAAW,CACnB,gBAAgB,IAAI,mDAAmD;oBACrE,iEAAiE;oBACjE,8CAA8C,EAChD,MAAM,EACN,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;YACH,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YACxC,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,OAAO,EAAE,CAAA;YAChB,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAA;QAC3B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;QACxB,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAA;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;CACF"}

package/dist/bridge/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turns technical failures into sentences a language model can act on.
+ *
+ * For an MCP server the error message is part of the interface: it ends up in
+ * the model's context, which then has to work out what to do next.
+ * "ECONNREFUSED 127.0.0.1:1143" does not help with that.
+ */
+/**
+ * What would fix it, as a category rather than as a sentence.
+ *
+ * The sentence needs the address of the configuration page, and this module has
+ * no business knowing that. So the diagnosis happens here, where the error codes
+ * are, and the remedy is written where the address is known. See describeFailure.
+ */
+export type BridgeRemedy = 
+/** Nothing is listening. The Bridge is not running, or the port is wrong. */
+'unreachable'
+/** It answered and refused the login. The stored password is stale. */
+ | 'credentials'
+/** It is there but not ready: starting up, or locked. */
+ | 'not-ready'
+/** Nothing the user can do from the interface. */
+ | 'none';
+export declare class BridgeError extends Error {
+    name: string;
+    readonly remedy: BridgeRemedy;
+    constructor(message: string, remedy?: BridgeRemedy, options?: ErrorOptions);
+}
+/**
+ * Builds an understandable message from an arbitrary failure.
+ *
+ * `host` and `port` appear in the text because the ports are configurable and
+ * a wrong port is the second most common cause.
+ */
+export declare function explainError(error: unknown, host: string, port: number): BridgeError;

package/dist/bridge/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Turns technical failures into sentences a language model can act on.
+ *
+ * For an MCP server the error message is part of the interface: it ends up in
+ * the model's context, which then has to work out what to do next.
+ * "ECONNREFUSED 127.0.0.1:1143" does not help with that.
+ */
+export class BridgeError extends Error {
+    name = 'BridgeError';
+    remedy;
+    constructor(message, remedy = 'none', options) {
+        super(message, options);
+        this.remedy = remedy;
+    }
+}
+/**
+ * Builds an understandable message from an arbitrary failure.
+ *
+ * `host` and `port` appear in the text because the ports are configurable and
+ * a wrong port is the second most common cause.
+ */
+export function explainError(error, host, port) {
+    const e = error;
+    const address = `${host}:${port}`;
+    if (e?.code === 'ECONNREFUSED') {
+        return new BridgeError(`Nothing is accepting connections on ${address}. Proton Mail Bridge is most likely not ` +
+            'running: it is a desktop application that has to be started and unlocked by the person ' +
+            'using it, and this server can neither start it nor unlock it. If it is running, it may ' +
+            'be listening on a different port, which the Bridge shows under Settings, Advanced.', 'unreachable', { cause: error });
+    }
+    if (e?.code === 'ETIMEDOUT' || e?.code === 'ECONNRESET') {
+        return new BridgeError(`The connection to ${address} did not come up, or it was dropped. That happens while the ` +
+            'Bridge is starting up and while it is locked, both of which pass on their own once the ' +
+            'person at the machine has unlocked it.', 'not-ready', { cause: error });
+    }
+    if (e?.code === 'ENOTFOUND' || e?.code === 'EAI_AGAIN') {
+        return new BridgeError(`The address "${host}" could not be resolved. Unless the Bridge was deliberately put on ` +
+            'another machine, BRIDGE_HOST should be 127.0.0.1.', 'unreachable', { cause: error });
+    }
+    // imapflow reports rejected logins as AUTHENTICATIONFAILED.
+    const text = `${e?.responseText ?? ''} ${e?.message ?? ''}`;
+    if (/AUTHENTICATIONFAILED|Invalid credentials|LOGIN failed/i.test(text)) {
+        return new BridgeError('The Bridge answered and refused the login, so it is running and the stored password is no ' +
+            'longer the right one. The Bridge generates a new password whenever an account is removed ' +
+            'and added again, and it can be regenerated at any time, so a password that worked ' +
+            'yesterday can be wrong today. It is not the Proton account password: the current one is ' +
+            'shown in the Bridge application under the account.', 'credentials', { cause: error });
+    }
+    if (/certificate|self.signed|DEPTH_ZERO/i.test(text)) {
+        return new BridgeError('The Bridge certificate was rejected. The Bridge uses a self-signed certificate, ' +
+            'which is only accepted for connections to 127.0.0.1.', 'none', { cause: error });
+    }
+    const raw = e?.message ?? String(error);
+    return new BridgeError(`The Bridge reported an error: ${raw}`, 'none', { cause: error });
+}
+//# sourceMappingURL=errors.js.map

package/dist/bridge/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/bridge/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,GAAG,aAAa,CAAA;IACpB,MAAM,CAAc;IAE7B,YAAY,OAAe,EAAE,MAAM,GAAiB,MAAM,EAAE,OAAsB;QAChF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAQD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,IAAY,EAAE,IAAY;IACrE,MAAM,CAAC,GAAG,KAAsB,CAAA;IAChC,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAA;IAEjC,IAAI,CAAC,EAAE,IAAI,KAAK,cAAc,EAAE,CAAC;QAC/B,OAAO,IAAI,WAAW,CACpB,uCAAuC,OAAO,0CAA0C;YACtF,yFAAyF;YACzF,yFAAyF;YACzF,oFAAoF,EACtF,aAAa,EACb,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,IAAI,CAAC,EAAE,IAAI,KAAK,WAAW,IAAI,CAAC,EAAE,IAAI,KAAK,YAAY,EAAE,CAAC;QACxD,OAAO,IAAI,WAAW,CACpB,qBAAqB,OAAO,8DAA8D;YACxF,yFAAyF;YACzF,wCAAwC,EAC1C,WAAW,EACX,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,IAAI,CAAC,EAAE,IAAI,KAAK,WAAW,IAAI,CAAC,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;QACvD,OAAO,IAAI,WAAW,CACpB,gBAAgB,IAAI,qEAAqE;YACvF,mDAAmD,EACrD,aAAa,EACb,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,4DAA4D;IAC5D,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE,YAAY,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,IAAI,EAAE,EAAE,CAAA;IAC3D,IAAI,wDAAwD,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,IAAI,WAAW,CACpB,4FAA4F;YAC1F,2FAA2F;YAC3F,oFAAoF;YACpF,0FAA0F;YAC1F,oDAAoD,EACtD,aAAa,EACb,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,IAAI,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO,IAAI,WAAW,CACpB,kFAAkF;YAChF,sDAAsD,EACxD,MAAM,EACN,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAA;IACvC,OAAO,IAAI,WAAW,CAAC,iCAAiC,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;AAC1F,CAAC"}