proton-mail-bridge-client 2.16.3 → 2.17.1

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { execFile } from "node:child_process";
 import { accessSync, constants as fsConstants, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 import { homedir, release as osRelease } from "node:os";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -10,8 +11,10 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { buildConfigFromEnv, createServer, withAudit } from "./index.js";
 import { isMainModule } from "./is-main.js";
 import { isLikelyAuthenticationError, isLikelyCertificateError, isLikelyConnectionError, isLikelyTlsMismatchError, SimpleIMAPService } from "./services/simple-imap-service.js";
+import { GrantService, grantStatus } from "./services/grant-service.js";
+import { GRANTABLE_TOOLS, MAX_GRANT_DAYS, MAX_GRANT_USES } from "./utils/delegation.js";
 import { ensureDestructiveConfirmed, ensureEmailActionAllowed, ensureMailboxWriteAllowed, sanitizeRuntimeConfig } from "./utils/runtime-policy.js";
-import { isValidEmail, parseEmails } from "./utils/helpers.js";
+import { InvalidArgumentError, isValidEmail, parseEmails } from "./utils/helpers.js";
 import { checkForUpdate } from "./utils/update-check.js";
 import { healthProblems } from "./utils/health.js";
 import { bridgeVersionNote } from "./utils/bridge-version.js";
@@ -176,6 +179,9 @@ function printHelp() {
         "  draft-send <id>        Send a saved draft",
         "  draft-delete <id>      Delete a saved draft",
         "  draft-thread-reply <id> Create a reply draft for a thread",
+        "  grant-create           Give the assistant a narrow, expiring permission to send (--tools --recipients --expires --uses --note); asks you to confirm at a terminal",
+        "  grant-list             List the delegation grants in force (--all, --account)",
+        "  grant-revoke <id>      Revoke a delegation grant",
         "  tools                  List every MCP tool exposed by the server",
         "  tool <name>            Call any MCP tool with JSON arguments",
         "",
@@ -300,6 +306,9 @@ export const COMMAND_SPECS = {
     "draft-send": { usage: "draft-send <id> [--args '{...}']", description: "Send a saved draft (dryRun etc. via --args)", flags: ["id", "args", "args-file"] },
     "draft-delete": { usage: "draft-delete <id>", description: "Delete a saved draft", flags: ["id"] },
     "draft-thread-reply": { usage: "draft-thread-reply <threadId> (--body <text> | stdin) [--reply-all]", description: "Create a reply draft for a thread", flags: ["id", ...BODY_FLAGS, "reply-all", "all", ...DRAFT_COPY_FLAGS] },
+    "grant-create": { usage: "grant-create --tools <a,b> --recipients <addr|@domain,...> --expires <30m|12h|7d|ISO> [--uses <n>] [--note <text>] [--account <slug|address>]", description: `Give the assistant a narrow, expiring permission to send (tools: ${GRANTABLE_TOOLS.join(", ")}; every To/Cc/Bcc must match; at most ${MAX_GRANT_USES} uses and ${MAX_GRANT_DAYS} days). Honoured only by a server started with PROTONMAIL_DELEGATION=on`, flags: ["tools", "recipients", "expires", "uses", "note", "account"] },
+    "grant-list": { usage: "grant-list [--all] [--account <slug|address>]", description: "List the delegation grants in force (--all also shows used up, expired and revoked ones)", flags: ["all", "account"] },
+    "grant-revoke": { usage: "grant-revoke <id> [--account <slug|address>]", description: "Revoke a delegation grant at once", flags: ["account"] },
     tools: { usage: "tools", description: "List every MCP tool exposed by the server", flags: [] },
     tool: { usage: "tool <name> [--args '{...}' | --args-file <path>]", description: "Call any MCP tool with JSON arguments", flags: ["args", "args-file"] },
 };
@@ -1725,7 +1734,20 @@ async function runNotify(parsed) {
     let running = true;
     let previousCount;
     let problemCause;
-    const shutdown = () => { running = false; };
+    // Exit from the handler itself: the loop may be parked in a connect, an IDLE or a retry wait that would otherwise
+    // outlast launchd's/systemd's stop timeout.
+    // `stopping` makes this the only place that prints "Stopped." and exits, and ignores a second signal.
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        running = false;
+        void Promise.race([imapService.disconnect().catch(() => undefined), new Promise((resolve) => setTimeout(resolve, 500))]).then(() => {
+            process.stderr.write("[notify] Stopped.\n");
+            process.exit(0);
+        });
+    };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     process.stderr.write(`[notify] Watching ${folder} for new mail (IMAP IDLE). Ctrl+C to stop.\n`);
@@ -1787,7 +1809,8 @@ async function runNotify(parsed) {
     catch {
         // ignore
     }
-    process.stderr.write("[notify] Stopped.\n");
+    if (!stopping)
+        process.stderr.write("[notify] Stopped.\n");
 }
 async function runTestEmail(parsed) {
     const to = parsed.positionals[0] || getStringFlag(parsed.flags, "to");
@@ -1967,6 +1990,154 @@ async function runDraftDelete(parsed) {
         printToolCallResult(result, wantJson);
     });
 }
+// Delegation grants are made and revoked here and nowhere else: they are read and written straight from the account's data
+// directory, never through an MCP tool, so a model that has only MCP tools cannot grant itself anything.
+function grantStores(parsed, options) {
+    const { accounts } = buildConfigFromEnv();
+    const wanted = getStringFlag(parsed.flags, "account");
+    const chosen = wanted ? accounts.filter((account) => account.address.toLowerCase() === wanted.toLowerCase() || account.slug === wanted) : accounts;
+    if (chosen.length === 0)
+        throw new CliUsageError(`Unknown account "${wanted}". Configured: ${accounts.map((account) => account.slug).join(", ")}`);
+    if (options.single && !wanted && chosen.length > 1)
+        throw new CliUsageError(`Several accounts are configured; name one with --account (${accounts.map((account) => account.slug).join(", ")}).`);
+    return chosen.map((account) => ({ account, grants: new GrantService({ dataDir: account.dataDir, smtp: account.smtp }, account.address) }));
+}
+const GRANT_SPAN_MS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
+// "30m", "12h", "7d" from now, or a timestamp (a bare date is midnight UTC).
+export function parseGrantExpiry(value, now = new Date()) {
+    const span = /^(\d{1,4})([mhd])$/.exec(value.trim());
+    const date = span
+        ? new Date(now.getTime() + Number(span[1]) * GRANT_SPAN_MS[span[2]])
+        : /^\d{4}-\d{2}-\d{2}/.test(value.trim())
+            ? new Date(value.trim())
+            : new Date(Number.NaN);
+    if (Number.isNaN(date.getTime()))
+        throw new CliUsageError(`--expires must be like 30m, 12h, 7d or a timestamp such as 2026-11-05T18:00:00Z, got "${value}".`);
+    return date;
+}
+const grantLine = (grant, now) => [
+    grant.id,
+    grant.account,
+    grant.tools.join(","),
+    grant.recipients.join(","),
+    `${grant.maxUses - grant.usedCount}/${grant.maxUses} uses left`,
+    `expires ${grant.expiresAt}`,
+    ...(grantStatus(grant, now) === "active" ? [] : [grantStatus(grant, now)]),
+    JSON.stringify(grant.note),
+].join(" | ");
+// A grant is made or revoked only by a person at a terminal: both stdin and stdout must be one, the whole grant is shown, and
+// a phrase that names its recipient count (or id) is typed back. There is no flag, variable or argument that answers for the
+// person, so a model that can run shell commands is stopped here (one that can write grants.json itself is not: the file is not signed).
+export const isInteractiveTerminal = (input = process.stdin, output = process.stdout) => Boolean(input?.isTTY && output?.isTTY);
+export const grantCreatePhrase = (recipientCount) => `grant ${recipientCount} recipient${recipientCount === 1 ? "" : "s"}`;
+export const grantRevokePhrase = (id) => `revoke ${id}`;
+const grantTerminal = {
+    isInteractive: () => isInteractiveTerminal(),
+    ask: (text) => {
+        const lines = createInterface({ input: process.stdin, output: process.stdout });
+        return new Promise((resolve) => {
+            lines.once("close", () => resolve(""));
+            lines.question(text, resolve);
+        }).finally(() => lines.close());
+    },
+    write: (text) => void process.stdout.write(text),
+};
+function requireTerminal(terminal, what) {
+    if (!terminal.isInteractive()) {
+        throw new Error(`${what} needs an interactive terminal (stdin and stdout) and a person to confirm it; it cannot be run from a script or by the assistant. Nothing was changed.`);
+    }
+}
+async function confirmAtTerminal(terminal, summary, phrase) {
+    const answer = await terminal.ask(`${summary}\nTo confirm, type exactly: ${phrase}\n> `);
+    if (answer.trim() !== phrase)
+        throw new Error("Not confirmed. Nothing was changed.");
+}
+export async function runGrantCreate(parsed, terminal = grantTerminal) {
+    const [{ account, grants }] = grantStores(parsed, { single: true });
+    const split = (key) => (getStringFlag(parsed.flags, key) ?? "").split(/[,\s]+/).filter(Boolean);
+    const tools = split("tools");
+    const recipients = split("recipients");
+    const expires = getStringFlag(parsed.flags, "expires");
+    if (tools.length === 0)
+        throw new CliUsageError(`--tools is required: ${GRANTABLE_TOOLS.join(", ")} (comma-separated).`);
+    if (recipients.length === 0)
+        throw new CliUsageError("--recipients is required: exact addresses and/or @domain entries (comma-separated).");
+    if (!expires)
+        throw new CliUsageError(`--expires is required (30m, 12h, 7d or a timestamp; at most ${MAX_GRANT_DAYS} days).`);
+    const maxUses = parseIntegerFlag(parsed.flags, "uses", 1, `a whole number from 1 to ${MAX_GRANT_USES}`) ?? 1;
+    const input = { note: getTextFlag(parsed.flags, "note"), tools, recipients, maxUses, expiresAt: parseGrantExpiry(expires) };
+    let plan;
+    try {
+        plan = grants.planGrant(input);
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+    requireTerminal(terminal, "grant-create");
+    await confirmAtTerminal(terminal, [
+        `New grant for ${account.address}:`,
+        `  tools:      ${plan.tools.join(", ")}`,
+        `  recipients: ${plan.recipients.join(", ")} (every To, Cc and Bcc must match)`,
+        `  uses:       ${plan.maxUses}`,
+        `  expires:    ${plan.expiresAt.toISOString()}`,
+        `  note:       ${JSON.stringify(plan.note)}`,
+        "With PROTONMAIL_DELEGATION=on the assistant can then send these without asking you again.",
+    ].join("\n"), grantCreatePhrase(plan.recipients.length));
+    let grant;
+    try {
+        grant = await grants.createGrant({ ...input, expiresAt: plan.expiresAt });
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+    if (isTruthyFlag(parsed.flags.json)) {
+        terminal.write(json(grant));
+        return;
+    }
+    terminal.write([
+        `Grant ${grant.id} created for ${account.address}.`,
+        `  tools:      ${grant.tools.join(", ")}`,
+        `  recipients: ${grant.recipients.join(", ")} (every To, Cc and Bcc must match)`,
+        `  uses:       ${grant.maxUses}`,
+        `  expires:    ${grant.expiresAt}`,
+        `  note:       ${JSON.stringify(grant.note)}`,
+        "Only a server started with PROTONMAIL_DELEGATION=on honours it. Revoke it with: grant-revoke " + grant.id,
+        "",
+    ].join("\n"));
+}
+async function runGrantList(parsed) {
+    const now = new Date();
+    const all = isTruthyFlag(parsed.flags.all);
+    const found = (await Promise.all(grantStores(parsed, { single: false }).map(({ grants }) => grants.list()))).flat();
+    const shown = found
+        .filter((grant) => all || grantStatus(grant, now) === "active")
+        .sort((left, right) => Date.parse(left.expiresAt) - Date.parse(right.expiresAt));
+    if (isTruthyFlag(parsed.flags.json)) {
+        process.stdout.write(json(shown.map((grant) => ({ ...grant, status: grantStatus(grant, now) }))));
+        return;
+    }
+    process.stdout.write(shown.length === 0 ? `No ${all ? "" : "active "}grants.\n` : `${shown.map((grant) => grantLine(grant, now)).join("\n")}\n`);
+}
+export async function runGrantRevoke(parsed, terminal = grantTerminal) {
+    const id = parsed.positionals[0];
+    if (!id)
+        throw new CliUsageError("grant-revoke requires a grant id (see grant-list).");
+    requireTerminal(terminal, "grant-revoke");
+    for (const { account, grants } of grantStores(parsed, { single: false })) {
+        const grant = (await grants.list()).find((candidate) => candidate.id === id);
+        if (!grant)
+            continue;
+        await confirmAtTerminal(terminal, `Revoke this grant for ${account.address}:\n  ${grantLine(grant, new Date())}`, grantRevokePhrase(grant.id));
+        const result = await grants.revokeGrant(id);
+        terminal.write(isTruthyFlag(parsed.flags.json) ? json({ id, account: account.address, revoked: true, alreadyRevoked: result.alreadyRevoked }) : `${result.alreadyRevoked ? "Already revoked" : "Revoked"}: ${id} (${account.address})\n`);
+        return;
+    }
+    throw new Error(`No grant ${JSON.stringify(id.slice(0, 40))} found.`);
+}
 async function runTools(parsed) {
     const wantJson = isTruthyFlag(parsed.flags.json);
     await withMcpClient(async (client) => {
@@ -2031,17 +2202,27 @@ export const TOOL_ONLY_COMMANDS = [
     { command: "rules", tool: "get_rules", positionals: [], help: "Show the mailbox rules, the proposals waiting and what the rules did (--account)" },
     { command: "set-rule", tool: "set_rule", positionals: [], help: "Create, change or accept a proposal as a rule (--proposalId, --id, --name, --enabled, --when, --actions, --confirmed)" },
     { command: "delete-rule", tool: "delete_rule", positionals: ["id"], help: "Delete a rule, or dismiss a proposal" },
+    { command: "export-sieve", tool: "export_sieve", positionals: [], help: "Turn the rules into a Sieve script for Proton's own filters, listing what cannot be expressed (--ruleId, --account)" },
     { command: "apply-rules", tool: "apply_rules", positionals: [], help: "Run the rules on mail already in the index; a preview unless --dryRun false (--ruleId, --limit, --confirmed)" },
     { command: "plan-inbox", tool: "plan_inbox", positionals: [], help: "Prepare a batch of mailbox changes to approve at once (--args '{\"scan\":true,\"limit\":30}')" },
     { command: "approve-plan", tool: "approve_plan", positionals: ["planId"], help: "Apply a plan from plan-inbox (--args '{\"exclude\":[3]}')" },
     { command: "undo-plan", tool: "undo_plan", positionals: ["planId"], help: "Put back what an approved plan changed" },
+    { command: "define-category", tool: "define_category", positionals: ["name"], help: "Define or change an inbox category of your own (--args '{\"keywords\":[\"invoice\"],\"label\":\"Receipts\"}'; '{\"starter\":true}' for the starter set)" },
+    { command: "categories", tool: "list_categories", positionals: [], help: "Your inbox categories and what corrections taught them (--account)" },
+    { command: "categorize-inbox", tool: "categorize_inbox", positionals: [], help: "Sort recent INBOX mail into your categories with the reasons; a preview unless --args '{\"dryRun\":false}' (then a plan for approve-plan)" },
+    { command: "correct-category", tool: "correct_category", positionals: ["emailId", "category"], help: "Teach the categories where a message belongs; shows what else would change" },
     { command: "find-commitments", tool: "find_commitments", positionals: [], help: "Find sentences that look like promises in recent mail (--args '{\"days\":7,\"direction\":\"both\"}')" },
     { command: "set-commitment", tool: "set_commitment", positionals: [], help: "Record a commitment, or close one (--args '{\"text\":\"...\",\"direction\":\"mine\",\"due\":\"2026-11-05\"}')" },
     { command: "commitments", tool: "list_commitments", positionals: [], help: "The commitment ledger: overdue, due today, open, probably done (--args '{\"status\":\"all\"}')" },
+    { command: "find-contact", tool: "find_contact", positionals: ["query"], help: "A person by name or address: addresses, organisation, tags, notes, counts both ways, last subjects" },
+    { command: "set-contact", tool: "set_contact", positionals: ["address"], help: "Tag, name, annotate, merge or unmerge a contact (--args '{\"addTags\":[\"vip\"]}' or '{\"mergeWith\":\"other@example.com\"}' or '{\"unmerge\":true}')" },
+    { command: "import-contacts", tool: "import_contacts", positionals: ["path"], help: "Import people from a local .vcf file into the contact store" },
     { command: "style-profile", tool: "get_style_profile", positionals: [], help: "How you write, from your sent mail: language, greeting, closing, tone (--args '{\"recipient\":\"pat@client.example\",\"refresh\":true}')" },
     { command: "get-brief", tool: "get_brief", positionals: [], help: "(tool form; see also `brief`)" },
     { command: "autoresponder", tool: "get_autoresponder", positionals: [], help: "Show the automatic reply of an address (--account)" },
     { command: "set-autoresponder", tool: "set_autoresponder", positionals: [], help: "Set up or switch off the automatic reply of an address (--enabled, --body, --subject, --startsAt, --endsAt, --outgoingNote, --mode, --timezone, --rules, --confirmed)" },
+    { command: "list-grants", tool: "list_grants", positionals: [], help: "(tool form; see also `grant-list`)" },
+    { command: "events", tool: "get_events", positionals: [], help: "What happened while nobody asked: new mail, snoozes, reminders, sends, rules, plans (--args '{\"sinceCursor\":\"<nextCursor>\",\"types\":[\"mail\"],\"limit\":50}')" },
     { command: "list-templates", tool: "list_templates", positionals: [], help: "List saved email templates" },
     { command: "get-template", tool: "get_template", positionals: ["id"], help: "Get a saved template by id" },
     { command: "delete-template", tool: "delete_template", positionals: ["id"], help: "Delete a saved template" },
@@ -2080,6 +2261,7 @@ export const TOOL_ONLY_COMMANDS = [
     { command: "import-email", tool: "import_email", positionals: [], fileFieldBase64: "rawBase64", help: "Import a .eml message via IMAP APPEND (--file <path.eml>)" },
     { command: "clear-index", tool: "clear_index", positionals: [], help: "Delete the local SQLite mailbox index" },
     { command: "get-audit-logs", tool: "get_audit_logs", positionals: [], help: "Recent write-operation audit log entries" },
+    { command: "verify-audit-log", tool: "verify_audit_log", positionals: [], help: "Check the audit log hash chain and print its head hash" },
 ];
 async function runToolOnlyCommand(entry, parsed) {
     const wantJson = isTruthyFlag(parsed.flags.json);
@@ -2376,6 +2558,15 @@ export async function main() {
         case "draft-thread-reply":
             await runDraftThreadReply(parsed);
             return;
+        case "grant-create":
+            await runGrantCreate(parsed);
+            return;
+        case "grant-list":
+            await runGrantList(parsed);
+            return;
+        case "grant-revoke":
+            await runGrantRevoke(parsed);
+            return;
         case "tools":
             await runTools(parsed);
             return;