@rndmjoker/proton-mcp 0.4.4

package/dist/mail/ids.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Stable message identifiers.
+ *
+ * Measured against the Bridge: UIDs are per mailbox and change when a message
+ * is moved, while the Message-ID stays stable. A UID is therefore a throwaway
+ * address and never handed out as an identifier.
+ *
+ * Every identifier this server hands out is the Message-ID. Resolving it back
+ * to a UID happens on demand, which costs a search but survives a message
+ * being moved between two calls of a conversation.
+ */
+import type { ImapFlow } from 'imapflow';
+import type { Connection } from '../bridge/connection.js';
+/** Mailbox that holds every message, including trash. The fallback for lookups. */
+export declare const ALL_MAIL = "All Mail";
+/**
+ * Brings a Message-ID into the shape the IMAP header uses.
+ *
+ * Callers paste identifiers from earlier answers, sometimes without the angle
+ * brackets. Both forms have to work, otherwise a lookup fails for a reason
+ * nobody can see.
+ */
+export declare function normaliseMessageId(id: string): string;
+/**
+ * The identifier as this server hands it out.
+ *
+ * Every answer uses this, so that the same message has the same name whichever
+ * tool named it. It did not, and the difference was invisible until it was not:
+ * a listing reads the IMAP envelope, which repeats the header as it stands,
+ * while reading a message goes through a MIME parser that adds the brackets RFC
+ * 5322 requires. For a header written correctly both agree. For one written
+ * without brackets the same message came back under two names.
+ *
+ * An empty identifier stays empty rather than becoming `<>`. A message without
+ * one cannot be addressed at all, and pretending otherwise would only move the
+ * failure further away from its cause.
+ */
+export declare function presentMessageId(raw: string): string;
+export interface ResolvedMessage {
+    messageId: string;
+    /** The mailbox the message was found in. */
+    path: string;
+    /** Valid only together with `path`, and only until the message is moved. */
+    uid: number;
+    /** Changes when the Bridge renumbers UIDs. Cached UIDs are void afterwards. */
+    uidValidity: string;
+}
+/**
+ * Searches one mailbox for a Message-ID and returns the UID if present.
+ *
+ * Two attempts, and the second one exists because of a real message.
+ *
+ * RFC 5322 requires the angle brackets, so `normaliseMessageId` puts them back
+ * on and the first search asks for the bracketed form. That search is exact in
+ * practice even though the comparison is a substring one: `<abc>` cannot occur
+ * inside `<xyzabc>`, because the bracket has to sit immediately before the
+ * identifier.
+ *
+ * Real mail does not always obey. A message was found whose header carries the
+ * identifier bare, and the envelope hands it out exactly as it stands, so
+ * everything this server had already reported for that message was unfindable:
+ * the bracketed search never matched, and it was the only search there was.
+ * Marking 67 messages as read left that one behind with no way to reach it.
+ *
+ * The second attempt therefore drops the brackets, which finds both spellings,
+ * and every hit is verified because that search can also match a message that
+ * merely contains the identifier. It only runs when the first one came back
+ * empty, so nothing normal pays for it.
+ */
+export declare function findByMessageId(client: ImapFlow, messageId: string): Promise<number | undefined>;
+/**
+ * Resolves a Message-ID to a mailbox and UID.
+ *
+ * `hint` is a mailbox to try first. It is a shortcut, not a requirement: if the
+ * message is not there, the search falls back to "All Mail", which holds
+ * everything. That is what makes the identifier survive a move.
+ */
+export declare function resolveMessageId(connection: Connection, rawId: string, hint?: string): Promise<ResolvedMessage>;

package/dist/mail/ids.js

@@ -0,0 +1,135 @@
+/**
+ * Stable message identifiers.
+ *
+ * Measured against the Bridge: UIDs are per mailbox and change when a message
+ * is moved, while the Message-ID stays stable. A UID is therefore a throwaway
+ * address and never handed out as an identifier.
+ *
+ * Every identifier this server hands out is the Message-ID. Resolving it back
+ * to a UID happens on demand, which costs a search but survives a message
+ * being moved between two calls of a conversation.
+ */
+import { BridgeError } from '../bridge/errors.js';
+/** Mailbox that holds every message, including trash. The fallback for lookups. */
+export const ALL_MAIL = 'All Mail';
+/**
+ * Brings a Message-ID into the shape the IMAP header uses.
+ *
+ * Callers paste identifiers from earlier answers, sometimes without the angle
+ * brackets. Both forms have to work, otherwise a lookup fails for a reason
+ * nobody can see.
+ */
+export function normaliseMessageId(id) {
+    const trimmed = id.trim();
+    if (!trimmed)
+        throw new BridgeError('An empty message id cannot be resolved.');
+    const bare = trimmed.replace(/^<|>$/g, '');
+    return `<${bare}>`;
+}
+/**
+ * The identifier as this server hands it out.
+ *
+ * Every answer uses this, so that the same message has the same name whichever
+ * tool named it. It did not, and the difference was invisible until it was not:
+ * a listing reads the IMAP envelope, which repeats the header as it stands,
+ * while reading a message goes through a MIME parser that adds the brackets RFC
+ * 5322 requires. For a header written correctly both agree. For one written
+ * without brackets the same message came back under two names.
+ *
+ * An empty identifier stays empty rather than becoming `<>`. A message without
+ * one cannot be addressed at all, and pretending otherwise would only move the
+ * failure further away from its cause.
+ */
+export function presentMessageId(raw) {
+    const trimmed = raw.trim();
+    return trimmed ? normaliseMessageId(trimmed) : '';
+}
+/** The identifier without its angle brackets, whether it had any or not. */
+function bareForm(messageId) {
+    return messageId.replace(/^<|>$/g, '');
+}
+/**
+ * Checks that a hit really carries this identifier.
+ *
+ * Needed because the IMAP header search is a **substring** comparison, measured
+ * against the Bridge on 31.07.2026: searching for a fragment of an identifier
+ * returns the message. So a search for `abc@example.com` also matches a message
+ * whose header reads `<xyzabc@example.com>`, and taking that hit would mark the
+ * wrong message. Silently, which is the part that matters for a write.
+ *
+ * The envelope is read rather than the raw header, because that is the same
+ * source list_messages hands its identifiers out from. Comparing against
+ * anything else could agree with the header and disagree with what the caller
+ * was given.
+ */
+async function carriesId(client, uid, bare) {
+    const message = await client.fetchOne(String(uid), { envelope: true }, { uid: true });
+    const actual = message && message.envelope ? (message.envelope.messageId ?? '') : '';
+    return bareForm(actual.trim()) === bare;
+}
+/**
+ * Searches one mailbox for a Message-ID and returns the UID if present.
+ *
+ * Two attempts, and the second one exists because of a real message.
+ *
+ * RFC 5322 requires the angle brackets, so `normaliseMessageId` puts them back
+ * on and the first search asks for the bracketed form. That search is exact in
+ * practice even though the comparison is a substring one: `<abc>` cannot occur
+ * inside `<xyzabc>`, because the bracket has to sit immediately before the
+ * identifier.
+ *
+ * Real mail does not always obey. A message was found whose header carries the
+ * identifier bare, and the envelope hands it out exactly as it stands, so
+ * everything this server had already reported for that message was unfindable:
+ * the bracketed search never matched, and it was the only search there was.
+ * Marking 67 messages as read left that one behind with no way to reach it.
+ *
+ * The second attempt therefore drops the brackets, which finds both spellings,
+ * and every hit is verified because that search can also match a message that
+ * merely contains the identifier. It only runs when the first one came back
+ * empty, so nothing normal pays for it.
+ */
+export async function findByMessageId(client, messageId) {
+    const exact = await client.search({ header: { 'message-id': messageId } }, { uid: true });
+    if (exact && exact.length > 0) {
+        // Several hits mean duplicates of the same message inside one mailbox.
+        // The highest UID is the most recent copy.
+        return Math.max(...exact);
+    }
+    const bare = bareForm(messageId);
+    const loose = await client.search({ header: { 'message-id': bare } }, { uid: true });
+    if (!loose || loose.length === 0)
+        return undefined;
+    // Newest first, so a duplicate resolves to the more recent copy like above.
+    for (const uid of [...loose].sort((a, b) => b - a)) {
+        if (await carriesId(client, uid, bare))
+            return uid;
+    }
+    return undefined;
+}
+/**
+ * Resolves a Message-ID to a mailbox and UID.
+ *
+ * `hint` is a mailbox to try first. It is a shortcut, not a requirement: if the
+ * message is not there, the search falls back to "All Mail", which holds
+ * everything. That is what makes the identifier survive a move.
+ */
+export async function resolveMessageId(connection, rawId, hint) {
+    const messageId = normaliseMessageId(rawId);
+    const candidates = hint && hint !== ALL_MAIL ? [hint, ALL_MAIL] : [ALL_MAIL];
+    for (const path of candidates) {
+        const found = await connection.withMailbox(path, async (client, status) => {
+            if (status.messages === 0)
+                return undefined;
+            const uid = await findByMessageId(client, messageId);
+            return uid === undefined ? undefined : { uid, uidValidity: status.uidValidity };
+        });
+        if (found) {
+            return { messageId, path, uid: found.uid, uidValidity: found.uidValidity };
+        }
+    }
+    throw new BridgeError(`No message with the id ${messageId} was found${hint ? ` in "${hint}" or in "${ALL_MAIL}"` : ` in "${ALL_MAIL}"`}. ` +
+        'The message may have been deleted, or the id may be incomplete. ' +
+        'Identifiers come from list_messages or search_messages and have to be passed on unchanged.');
+}
+//# sourceMappingURL=ids.js.map

package/dist/mail/ids.js.map

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

package/dist/mail/labels.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Applying and removing labels.
+ *
+ * The first thing in this server that writes to a mailbox. Everything here
+ * follows from four measurements against the Bridge:
+ *
+ * 1. `COPY` into a mailbox under `Labels/` applies the label. The message stays
+ *    in its folder and no second message appears: "All Mail" holds every message
+ *    exactly once and its count did not change.
+ * 2. The same `COPY` into a mailbox under `Folders/` **moves** the message
+ *    instead. One command, two meanings, told apart by the prefix alone.
+ * 3. A label is removed with `\Deleted` plus `EXPUNGE` inside the label mailbox.
+ *    The message keeps its folder, keeps its other labels and does not go to
+ *    trash.
+ * 4. **A copy into a mailbox that does not exist reports success and does
+ *    nothing.** No error, no TRYCREATE, and the destination is not created
+ *    either. There is nothing to react to afterwards, so the label has to be
+ *    verified to exist before the call, not after it.
+ *
+ * Point 2 and point 3 together are why this module refuses to touch anything
+ * outside `Labels/`. Removing a label is an EXPUNGE, and an EXPUNGE aimed at a
+ * folder deletes mail. That guard is the most important line in this file.
+ */
+import type { Connection } from '../bridge/connection.js';
+/** The prefix Proton exposes labels under. Anything else is not a label. */
+export declare const LABEL_PREFIX = "Labels/";
+/**
+ * Brings a label name into its full path.
+ *
+ * Callers say "Test1" or "Labels/Test1" and mean the same thing. What they must
+ * not be able to say is a path that leaves the label namespace, so this rejects
+ * rather than repairs anything else.
+ */
+export declare function labelPath(name: string): string;
+/** The labels that exist, as full paths. */
+export declare function listLabels(connection: Connection): Promise<string[]>;
+export interface LabelChange {
+    messageId: string;
+    label: string;
+    /** The mailbox the message was found in, for the answer. */
+    path: string;
+}
+/**
+ * Applies a label to a message.
+ *
+ * The result is deliberately not verified afterwards. Measured: right after a
+ * write the Bridge reports an intermediate state, and a check run immediately
+ * describes something that is not the outcome.
+ */
+export declare function addLabel(connection: Connection, readOnly: boolean, messageId: string, label: string, hint?: string): Promise<LabelChange>;
+/**
+ * Removes a label from a message.
+ *
+ * The message is looked up **inside the label mailbox**, not through the
+ * ordinary resolver. A label is a mailbox of its own with its own uids, so a uid
+ * from anywhere else would address a different message here, and this operation
+ * expunges what it addresses.
+ */
+export declare function removeLabel(connection: Connection, readOnly: boolean, messageId: string, label: string): Promise<LabelChange & {
+    wasApplied: boolean;
+}>;

package/dist/mail/labels.js

@@ -0,0 +1,139 @@
+/**
+ * Applying and removing labels.
+ *
+ * The first thing in this server that writes to a mailbox. Everything here
+ * follows from four measurements against the Bridge:
+ *
+ * 1. `COPY` into a mailbox under `Labels/` applies the label. The message stays
+ *    in its folder and no second message appears: "All Mail" holds every message
+ *    exactly once and its count did not change.
+ * 2. The same `COPY` into a mailbox under `Folders/` **moves** the message
+ *    instead. One command, two meanings, told apart by the prefix alone.
+ * 3. A label is removed with `\Deleted` plus `EXPUNGE` inside the label mailbox.
+ *    The message keeps its folder, keeps its other labels and does not go to
+ *    trash.
+ * 4. **A copy into a mailbox that does not exist reports success and does
+ *    nothing.** No error, no TRYCREATE, and the destination is not created
+ *    either. There is nothing to react to afterwards, so the label has to be
+ *    verified to exist before the call, not after it.
+ *
+ * Point 2 and point 3 together are why this module refuses to touch anything
+ * outside `Labels/`. Removing a label is an EXPUNGE, and an EXPUNGE aimed at a
+ * folder deletes mail. That guard is the most important line in this file.
+ */
+import { BridgeError } from '../bridge/errors.js';
+import { normaliseMessageId, resolveMessageId } from './ids.js';
+/** The prefix Proton exposes labels under. Anything else is not a label. */
+export const LABEL_PREFIX = 'Labels/';
+/**
+ * Brings a label name into its full path.
+ *
+ * Callers say "Test1" or "Labels/Test1" and mean the same thing. What they must
+ * not be able to say is a path that leaves the label namespace, so this rejects
+ * rather than repairs anything else.
+ */
+export function labelPath(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        throw new BridgeError('An empty label name cannot be used.');
+    const full = trimmed.startsWith(LABEL_PREFIX) ? trimmed : `${LABEL_PREFIX}${trimmed}`;
+    const bare = full.slice(LABEL_PREFIX.length);
+    if (!bare) {
+        throw new BridgeError(`"${name}" names the label container itself rather than a label. Pass the label name, for example "Work".`);
+    }
+    // A nested path would let a caller aim at a folder from inside what looks
+    // like a label name. Labels have no hierarchy in Proton, so nothing is lost.
+    if (bare.includes('/')) {
+        throw new BridgeError(`"${name}" is not a label name. Labels have no sub-levels; pass a single name such as "Work".`);
+    }
+    return full;
+}
+/** Guard for every write in this module. Nothing outside Labels/ is touched. */
+function assertLabelMailbox(path) {
+    if (!path.startsWith(LABEL_PREFIX) || path.slice(LABEL_PREFIX.length).includes('/')) {
+        throw new BridgeError(`Refusing to operate on "${path}". This code only ever touches mailboxes under ${LABEL_PREFIX}, ` +
+            'because removing a label expunges messages and doing that to a folder would delete mail.');
+    }
+}
+/** The labels that exist, as full paths. */
+export async function listLabels(connection) {
+    const boxes = await connection.listMailboxes();
+    return boxes.filter((b) => b.kind === 'label' && b.selectable).map((b) => b.path);
+}
+/**
+ * Checks that a label exists, and says what to do when it does not.
+ *
+ * Not a nicety. Measurement 4 above means a missing label produces a successful
+ * copy that changes nothing, so without this check the tool would report having
+ * applied a label that was never applied.
+ */
+async function requireLabel(connection, path) {
+    const labels = await listLabels(connection);
+    if (labels.includes(path))
+        return;
+    const names = labels.map((l) => l.slice(LABEL_PREFIX.length));
+    throw new BridgeError(`There is no label "${path.slice(LABEL_PREFIX.length)}". ` +
+        (names.length
+            ? `The labels of this account are: ${names.join(', ')}.`
+            : 'This account has no labels yet.') +
+        ' Labels have to be created in Proton itself; this server does not create them, ' +
+        'and the Bridge accepts a copy into a label that does not exist without applying anything.');
+}
+/** Refuses every write while the server runs read-only. */
+function assertWritable(readOnly, what) {
+    if (readOnly) {
+        throw new BridgeError(`The server is running read-only, so ${what} is refused. ` +
+            'This is set by PROTON_MCP_READ_ONLY and the web interface reports it as the current mode.');
+    }
+}
+/**
+ * Applies a label to a message.
+ *
+ * The result is deliberately not verified afterwards. Measured: right after a
+ * write the Bridge reports an intermediate state, and a check run immediately
+ * describes something that is not the outcome.
+ */
+export async function addLabel(connection, readOnly, messageId, label, hint) {
+    assertWritable(readOnly, 'applying a label');
+    const path = labelPath(label);
+    assertLabelMailbox(path);
+    await requireLabel(connection, path);
+    const id = normaliseMessageId(messageId);
+    const resolved = await resolveMessageId(connection, id, hint);
+    await connection.withMailbox(resolved.path, async (client) => {
+        await client.messageCopy(String(resolved.uid), path, { uid: true });
+    });
+    return { messageId: resolved.messageId, label: path, path: resolved.path };
+}
+/**
+ * Removes a label from a message.
+ *
+ * The message is looked up **inside the label mailbox**, not through the
+ * ordinary resolver. A label is a mailbox of its own with its own uids, so a uid
+ * from anywhere else would address a different message here, and this operation
+ * expunges what it addresses.
+ */
+export async function removeLabel(connection, readOnly, messageId, label) {
+    assertWritable(readOnly, 'removing a label');
+    const path = labelPath(label);
+    assertLabelMailbox(path);
+    await requireLabel(connection, path);
+    const id = normaliseMessageId(messageId);
+    const wasApplied = await connection.withMailbox(path, async (client, status) => {
+        // The Bridge answers FETCH on an empty mailbox with BAD, and a search there
+        // is pointless anyway.
+        if (status.messages === 0)
+            return false;
+        const hits = await client.search({ header: { 'message-id': id } }, { uid: true });
+        if (!Array.isArray(hits) || hits.length === 0)
+            return false;
+        // Guarded again, immediately before the expunge. The path cannot have
+        // changed between the check above and here, but this is the line that
+        // deletes, and it should not depend on a check twenty lines away.
+        assertLabelMailbox(status.path);
+        await client.messageDelete(String(Math.max(...hits)), { uid: true });
+        return true;
+    });
+    return { messageId: id, label: path, path, wasApplied };
+}
+//# sourceMappingURL=labels.js.map

package/dist/mail/labels.js.map

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

package/dist/mail/markup.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Which markup a message may contain, and what has to be shown before it is sent.
+ *
+ * ## The measurement this is built on
+ *
+ * The obvious worry about formatted mail is CSS that hides text, and it is the
+ * wrong worry. Measured on 31.07.2026 against this server's own conversion:
+ * `display:none`, `font-size:0` and white-on-white all appear in the text
+ * preview, because the conversion reads the markup and does not apply styling.
+ * The preview therefore shows *more* than the recipient will see, which is the
+ * harmless direction: a person confirming reads everything.
+ *
+ * What is dangerous is the other direction, where the preview shows **less**
+ * than the recipient reads, and the same measurement found it:
+ *
+ * | Written | In the preview | What the recipient sees |
+ * | :--- | :--- | :--- |
+ * | `<img src="..." alt="TEXT">` | **nothing** | the alt text, because clients block remote images by default |
+ * | `<span title="TEXT">` | nothing | the title on hover |
+ * | `<style>p::before{content:"TEXT"}</style>` | nothing | generated text, in clients that keep style blocks |
+ * | `<noscript>`, `<textarea>` | the text | nothing, or something else |
+ *
+ * The first row is a working way past the confirmation. An assistant that has
+ * read a stranger's message could compose an image whose alt text carries the
+ * request, and the person confirming would see an empty message. Remote images
+ * are blocked by default in Proton and elsewhere, so the alt text is not a
+ * fallback, it is what actually arrives.
+ *
+ * Two conclusions, and they shape everything below:
+ *
+ * 1. **A list of what is permitted, not a filter for what is not.** `<style>`,
+ *    `<script>`, `<noscript>`, `<textarea>` and `<head>` are absent from the
+ *    list, so they are refused without anyone having had to think of them. That
+ *    is the whole argument for a positive list: what nobody anticipated does not
+ *    get through.
+ * 2. **Every piece of text a recipient can read is put in front of the person
+ *    confirming**, including the ones the preview drops: alt text, titles, and
+ *    every address behind a link or an image.
+ *
+ * The hiding properties are refused as well. Not because they defeat the
+ * preview, measured they do not, but because they let a message be delivered
+ * looking different from how it was written, and nothing is lost by saying no.
+ */
+/**
+ * The elements a message may use.
+ *
+ * Absent by design and worth naming, because the reason is the measurement
+ * above rather than taste: `style`, `script`, `noscript`, `textarea`, `head`,
+ * `title`, `meta`, `link`, `iframe`, `object`, `form`, `input`, `button`.
+ */
+export declare const PERMITTED_TAGS: Set<string>;
+/** Style properties a message may set. */
+export declare const PERMITTED_STYLES: Set<string>;
+/** One reason a message was refused. */
+export interface MarkupProblem {
+    /** What was found, in the caller's own markup. */
+    found: string;
+    /** Why it cannot be sent, and what to do instead. */
+    reason: string;
+}
+/** An address the message points at, which a person has to see before sending. */
+export interface MarkupUrl {
+    kind: 'link' | 'image';
+    url: string;
+    /** The text a reader sees for a link, or the alt text of an image. */
+    label: string;
+}
+export interface MarkupReading {
+    problems: MarkupProblem[];
+    urls: MarkupUrl[];
+    /** Text a recipient can read that the text preview leaves out. */
+    hiddenText: string[];
+    /** Content ids an image refers to, which have to be provided as parts. */
+    contentIds: string[];
+}
+/**
+ * Reads a message's markup: what is wrong with it, and what has to be shown.
+ *
+ * One pass, because the two questions are the same walk over the document and
+ * answering them separately is how they drift apart.
+ */
+export declare function readMarkup(html: string): MarkupReading;
+/**
+ * Refuses markup this server will not send.
+ *
+ * Refused rather than repaired, deliberately. Stripping what is not permitted
+ * would mean the message that goes out is not the message that was written, and
+ * nobody would find out: not the caller, whose formatting quietly vanishes, and
+ * not the person confirming, who has nothing to compare against.
+ */
+export declare function assertSendableMarkup(html: string): MarkupReading;