@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/config.example.json

@@ -0,0 +1,54 @@
+{
+  "mail": {
+    "imap": {
+      "host": "imap.example.com",
+      "port": 993,
+      "secure": true,
+      "user": "pi@example.com",
+      "password": "<PASSWORD>",
+      "folder": "INBOX",
+      "authType": "LOGIN",
+      "tokenCommand": [],
+      "sentFolder": ""
+    },
+    "smtp": {
+      "host": "smtp.example.com",
+      "port": 465,
+      "secure": true,
+      "user": "pi@example.com",
+      "password": "<PASSWORD>",
+      "authType": "LOGIN",
+      "tokenCommand": []
+    },
+    "to": "you@example.com"
+  },
+  "device": {
+    "name": ""
+  },
+  "security": {
+    "allowFrom": [
+      "you@example.com"
+    ],
+    "requireDmarcPass": true,
+    "allowHeaderThreading": true,
+    "allowSelfReplies": false,
+    "tokenTtlHours": 720
+  },
+  "daemon": {
+    "host": "127.0.0.1",
+    "port": 4177,
+    "idleTimeoutSecs": 120,
+    "scanIntervalSecs": 60
+  },
+  "notify": {
+    "onSettled": true,
+    "debounceMs": 10000,
+    "notifyOnAborted": false,
+    "maxAttachmentMb": 18
+  },
+  "tuning": {
+    "idleRenewMs": 1500000,
+    "backoffInitialMs": 1000,
+    "backoffMaxMs": 60000
+  }
+}

package/dist/core/attachments.js

@@ -0,0 +1,87 @@
+// Inbound attachments.
+//
+// The point: reply to a pi notification from your phone with an image or a log
+// and have the agent actually see it.
+//
+// Deliberately restrictive. An attachment that reaches the model is untrusted
+// input from a mail server, so:
+//   - MIME allowlist, not a denylist
+//   - hard caps on count and total bytes, enforced before anything is stored
+//   - anything dropped is reported with a reason rather than silently ignored
+/** Images the model can actually consume. */
+export const ALLOWED_IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/** Text-like attachments we inline as text. */
+export const ALLOWED_TEXT_MIMES = ["text/plain", "text/markdown", "application/json"];
+export const MAX_ATTACHMENTS = 4;
+export const MAX_TOTAL_BYTES = 1_000_000;
+function isImage(mime) {
+    return ALLOWED_IMAGE_MIMES.includes(mime);
+}
+function isText(mime) {
+    return ALLOWED_TEXT_MIMES.includes(mime);
+}
+/** Lowercase, strip parameters (`text/plain; charset=utf-8` → `text/plain`). */
+export function normalizeMime(contentType) {
+    return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
+/**
+ * Apply the allowlist and the caps.
+ * Order matters: mime first (cheap), then count, then size.
+ */
+export function selectAttachments(raw, limits = {}) {
+    const maxCount = limits.maxCount ?? MAX_ATTACHMENTS;
+    const maxTotalBytes = limits.maxTotalBytes ?? MAX_TOTAL_BYTES;
+    const accepted = [];
+    const dropped = [];
+    let total = 0;
+    for (const item of raw) {
+        const mimeType = normalizeMime(item.contentType);
+        const name = (item.filename ?? "").trim() || `attachment-${accepted.length + dropped.length + 1}`;
+        if (!isImage(mimeType) && !isText(mimeType)) {
+            dropped.push({ name, reason: "mime-not-allowed" });
+            continue;
+        }
+        if (accepted.length >= maxCount) {
+            dropped.push({ name, reason: "too-many" });
+            continue;
+        }
+        if (item.content.length === 0) {
+            dropped.push({ name, reason: "empty" });
+            continue;
+        }
+        if (total + item.content.length > maxTotalBytes) {
+            dropped.push({ name, reason: "too-large" });
+            continue;
+        }
+        total += item.content.length;
+        accepted.push({
+            name,
+            mimeType,
+            size: item.content.length,
+            data: item.content.toString("base64"),
+        });
+    }
+    return { accepted, dropped };
+}
+/**
+ * Build the payload for `pi.sendUserMessage`.
+ *
+ * Returns a plain string when there is nothing to attach: that keeps the common
+ * case identical to a typed message, so no client special-cases it.
+ */
+export function toUserContent(text, attachments = []) {
+    if (attachments.length === 0)
+        return text;
+    // An attachment-only reply has no prose; an empty text block ahead of the image is noise
+    // the model has to read past.
+    const content = text ? [{ type: "text", text }] : [];
+    for (const attachment of attachments) {
+        if (isImage(attachment.mimeType)) {
+            content.push({ type: "image", data: attachment.data, mimeType: attachment.mimeType });
+        }
+        else {
+            content.push({ type: "text", text: Buffer.from(attachment.data, "base64").toString("utf8") });
+        }
+    }
+    return content;
+}

package/dist/core/authz.js

@@ -0,0 +1,65 @@
+// Authorization for inbound mail.
+//
+// Order matters and is fail-closed at every step:
+//   1. loop guard      — never act on our own outbound address
+//   2. auto-generated  — no replies to robots (that is how loops start)
+//   3. allowlist       — exact addr-spec after RFC 5322-ish normalization
+//   4. DMARC           — dmarc=pass; authserv-id pinned only when configured
+//
+// The routing token is NOT consulted here. It routes; it does not authorize.
+// See docs/SECURITY.md §2.2.
+import { dmarcPasses, findTrustedAuthResults, isAutoGenerated, normalizeAddress } from "./reply-parse.js";
+export function authorize(input, config) {
+    const from = normalizeAddress(input.from);
+    if (!from)
+        return { ok: false, reason: "no-from" };
+    // 1. Loop guard: the pi account must never be treated as the human.
+    //    `mail.to` is the HUMAN's address, so it must not be used here — doing so
+    //    rejected every genuine reply (the human is the one writing to us).
+    //
+    //    Single-mailbox mode (`security.allowSelfReplies`): one address is both the
+    //    mailbox and the human, which is the normal case for a personal Hotmail or
+    //    Gmail. Then `from === self` is expected — but we still must not treat our
+    //    OWN outbound notification as a reply. The discriminator is `In-Reply-To`:
+    //    a reply carries it - but so does every threaded notification we send, so this
+    //    header alone is not enough. process.ts rejects our own Message-IDs first, using
+    //    the outbound registry; this check remains as the cheap early gate.
+    const self = normalizeAddress(config.mail.smtp.user) ?? normalizeAddress(config.mail.imap.user);
+    if (self && from === self) {
+        if (!config.security.allowSelfReplies)
+            return { ok: false, reason: "self" };
+        // Reply evidence is either header the router accepts. Requiring only In-Reply-To
+        // killed genuine replies from clients that set References alone (or a
+        // forward-then-reply), because the router would have routed them by chain.
+        const threaded = Boolean(input.headers.inReplyTo?.trim()) || Boolean(input.headers.references?.some((r) => r.trim()));
+        // Distinct from the self-echo guards (marker header, outbound Message-ID): this is a
+        // message from your own address with no reply evidence at all. The two are different
+        // problems for the user, so they get different names.
+        if (!threaded)
+            return { ok: false, reason: "no-reply-evidence" };
+    }
+    // 2. Never answer robots, and never act on a bounce: a null sender or a postmaster
+    //    address is a delivery failure report, not a human.
+    if (!from.includes("@") || /^(mailer-daemon|postmaster|mail-daemon)$/i.test(from.split("@")[0] ?? "")) {
+        return { ok: false, reason: "auto-generated" };
+    }
+    if (isAutoGenerated(input.headers))
+        return { ok: false, reason: "auto-generated" };
+    // 3. Allowlist. An empty list denies everything.
+    const allow = config.security.allowFrom.map((a) => normalizeAddress(a)).filter((a) => Boolean(a));
+    if (allow.length === 0)
+        return { ok: false, reason: "allowlist-empty" };
+    if (!allow.includes(from))
+        return { ok: false, reason: "not-allowlisted" };
+    // 4. DMARC pinned to our relay.
+    if (config.security.requireDmarcPass) {
+        // Unset means "trust the topmost header, i.e. the delivering relay's".
+        // Pinned means "only that authserv-id".
+        const ar = findTrustedAuthResults(input.headers, config.security.trustedAuthservId);
+        if (!ar)
+            return { ok: false, reason: "dmarc-missing" };
+        if (!dmarcPasses(ar))
+            return { ok: false, reason: "dmarc-failed" };
+    }
+    return { ok: true, from };
+}

package/dist/core/commands.js

@@ -0,0 +1,72 @@
+// `/mailbridge` argument routing.
+//
+// Pure, so the command surface is testable without pi. Keeping the parse separate
+// from the handlers is also what lets the same subcommand set back both the in-pi
+// command and (where it makes sense) the headless entry point.
+export const USAGE = [
+    "/mailbridge                 status",
+    "/mailbridge on              email mode on: decisions mail you",
+    "/mailbridge off             email mode off: decisions ask in this terminal",
+    "/mailbridge setup <pi-address> [to <your-address>] [force]",
+    "/mailbridge check           validate config, and that credentials are present",
+    "/mailbridge auth            approve OAuth2 device login",
+    "/mailbridge smoke           send one real mail, then read the folder back",
+    "/mailbridge prime           start watching from now, ignoring existing mail",
+    "/mailbridge restart         replace the daemon process (picks up new code, not just config)",
+    "/mailbridge help            this list",
+].join("\n");
+const SUBCOMMANDS = [
+    "on",
+    "off",
+    "status",
+    "setup",
+    "check",
+    "auth",
+    "smoke",
+    "prime",
+    "restart",
+    "help",
+];
+export function isSubcommand(value) {
+    return SUBCOMMANDS.includes(value);
+}
+/**
+ * Parse the text after `/mailbridge`.
+ *
+ * Accepts both `--to` and bare `to` because a TUI prompt is not a shell and people
+ * type either. Unknown words that are not addresses are ignored rather than
+ * treated as errors, so a stray flag cannot silently change the target address.
+ */
+export function parseMailbridgeCommand(args) {
+    const tokens = args.trim().split(/\s+/).filter(Boolean);
+    const first = tokens[0]?.toLowerCase();
+    if (!first || !isSubcommand(first)) {
+        return { sub: first ? "help" : "status", force: false };
+    }
+    const parsed = { sub: first, force: false };
+    if (first !== "setup")
+        return parsed;
+    const rest = tokens.slice(1);
+    const addresses = [];
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        const lower = token.toLowerCase();
+        if (lower === "force" || lower === "--force") {
+            parsed.force = true;
+            continue;
+        }
+        if (lower === "to" || lower === "--to") {
+            const next = rest[i + 1];
+            if (next && !next.startsWith("-") && next.toLowerCase() !== "force") {
+                parsed.to = next;
+                i++;
+            }
+            continue;
+        }
+        if (token.includes("@"))
+            addresses.push(token);
+    }
+    if (addresses[0])
+        parsed.address = addresses[0];
+    return parsed;
+}

package/dist/core/config-freshness.js

@@ -0,0 +1,24 @@
+// Should a session tell the running daemon to re-read its config?
+//
+// A session that attaches to an already-running daemon inherits whatever config that daemon
+// read - which may predate a hand-edited config.json or a headless `--setup`. Sending mail
+// with a replaced address is the failure this exists to prevent.
+//
+// The daemon reports the *mtime of the file it is running on*, and the extension compares it
+// with the file's current mtime. mtime-to-mtime deliberately: a clock reading would make a
+// preserved/backdated mtime reload forever, and would hide a write that landed between the
+// read and the timestamp.
+export function shouldReloadConfig({ configLoadedAt, configMtimeMs }) {
+    // No file: nothing changed, leave the daemon alone.
+    if (!configMtimeMs)
+        return false;
+    // The daemon reports 0 when it loaded while there was no config file. That is not
+    // "nothing to compare" - it is a daemon running on defaults, and a file that has since
+    // appeared must be picked up. Treating 0 as absent made this state permanent.
+    if (!configLoadedAt)
+        return true;
+    // Strictly newer. No slack: a re-trigger is impossible when both sides are the same
+    // file's mtime, and a tolerance would permanently miss a save that lands within it
+    // (an editor that writes twice), which is the failure this check exists to prevent.
+    return configMtimeMs > configLoadedAt;
+}

package/dist/core/config.js

@@ -0,0 +1,286 @@
+// Layered configuration. Later layers win; invalid values are reported rather
+// than thrown, so a typo never takes a session down mid-run.
+import { existsSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { configPath } from "../store/paths.js";
+/** Marks a warning produced by repairing a malformed section: the config still works. */
+export const REPAIRED_PREFIX = "repaired: ";
+const DEFAULTS = {
+    mail: {
+        imap: { host: "", port: 993, secure: true, user: "", password: "", folder: "INBOX" },
+        smtp: { host: "", port: 465, secure: true, user: "", password: "", authType: "LOGIN" },
+        to: "",
+    },
+    device: { name: "" }, // resolved below: hostname() unless configured
+    security: {
+        allowFrom: [],
+        requireDmarcPass: true,
+        allowHeaderThreading: true,
+        allowSelfReplies: false,
+        tokenTtlHours: 30 * 24,
+    },
+    daemon: { host: "127.0.0.1", port: 4177, idleTimeoutSecs: 120, scanIntervalSecs: 60 },
+    notify: {
+        onSettled: true,
+        debounceMs: 10_000,
+        notifyOnAborted: false,
+        // 18 MB raw is about 24 MB once base64-encoded, under the 25 MB ceiling that Gmail and
+        // Outlook.com enforce. A provider that allows more (QQ: 50 MB) can raise it.
+        maxAttachmentMb: 18,
+    },
+    tuning: {
+        idleRenewMs: 25 * 60 * 1000,
+        backoffInitialMs: 1000,
+        backoffMaxMs: 60_000,
+    },
+};
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** First label of the hostname, lowercased: `dev-box-7.local` -> `dev-box-7`. */
+export function shortHostname() {
+    try {
+        const full = hostname().toLowerCase();
+        return full.split(".")[0] || "unknown-device";
+    }
+    catch {
+        return "unknown-device";
+    }
+}
+/** Parse a token command from env: JSON array, or comma-separated argv. */
+function parseArgv(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed))
+                return parsed.map(String);
+        }
+        catch {
+            /* fall through to comma splitting */
+        }
+    }
+    return trimmed
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Shallow-by-section merge: enough for this config shape, and predictable. */
+function merge(base, over) {
+    if (!isRecord(base) || !isRecord(over))
+        return over ?? base;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over)) {
+        out[k] = isRecord(v) && isRecord(base[k]) ? merge(base[k], v) : v;
+    }
+    return out;
+}
+function readJson(path, warnings) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch (error) {
+        warnings.push(`${path}: ${error.message}`);
+        return {};
+    }
+}
+function envOverrides(env) {
+    const o = {};
+    const set = (path, value) => {
+        if (value === undefined)
+            return;
+        let cur = o;
+        for (const key of path.slice(0, -1)) {
+            cur[key] ??= {};
+            cur = cur[key];
+        }
+        cur[path[path.length - 1]] = value;
+    };
+    set(["mail", "imap", "host"], env.PI_MAILBRIDGE_IMAP_HOST);
+    set(["mail", "imap", "user"], env.PI_MAILBRIDGE_IMAP_USER);
+    set(["mail", "imap", "password"], env.PI_MAILBRIDGE_IMAP_PASS);
+    set(["mail", "smtp", "host"], env.PI_MAILBRIDGE_SMTP_HOST);
+    set(["mail", "smtp", "user"], env.PI_MAILBRIDGE_SMTP_USER);
+    set(["mail", "smtp", "password"], env.PI_MAILBRIDGE_SMTP_PASS);
+    set(["mail", "to"], env.PI_MAILBRIDGE_TO);
+    set(["daemon", "port"], env.PI_MAILBRIDGE_PORT);
+    set(["device", "name"], env.PI_MAILBRIDGE_DEVICE);
+    // Token commands are argv lists; accept JSON or a comma-separated argv.
+    if (env.PI_MAILBRIDGE_IMAP_TOKEN_CMD)
+        set(["mail", "imap", "tokenCommand"], parseArgv(env.PI_MAILBRIDGE_IMAP_TOKEN_CMD));
+    if (env.PI_MAILBRIDGE_SMTP_TOKEN_CMD)
+        set(["mail", "smtp", "tokenCommand"], parseArgv(env.PI_MAILBRIDGE_SMTP_TOKEN_CMD));
+    return o;
+}
+export function loadConfig(env = process.env) {
+    const warnings = [];
+    let cfg = DEFAULTS;
+    cfg = merge(cfg, readJson(configPath(env), warnings));
+    cfg = merge(cfg, envOverrides(env));
+    const resolved = { ...cfg, warnings };
+    // Every check below dereferences these sections, and loadConfig's contract is that it never
+    // throws. A JSON `null` is not a record, and the env merge runs after the file merge - so a
+    // null section can come back as a *partial* record (e.g. `{"daemon": null}` plus
+    // A daemon env var over a null section leaves a record with no host and no port, which would bind an
+    // ephemeral port and drop the single-instance guard). Repair by filling the defaults
+    // underneath whatever survived, rather than replacing it.
+    const sections = resolved;
+    for (const key of Object.keys(DEFAULTS)) {
+        const section = sections[key];
+        const defaults = DEFAULTS[key];
+        if (!isRecord(section)) {
+            warnings.push(`${REPAIRED_PREFIX}${key} must be an object — using the defaults`);
+            sections[key] = structuredClone(defaults);
+            continue;
+        }
+        const repaired = { ...defaults, ...section };
+        // The schema nests exactly one level (mail.imap, mail.smtp).
+        for (const [sub, subDefaults] of Object.entries(defaults)) {
+            if (!isRecord(subDefaults))
+                continue;
+            const value = section[sub];
+            if (!isRecord(value)) {
+                warnings.push(`${REPAIRED_PREFIX}${key}.${sub} must be an object — using the defaults`);
+                repaired[sub] = structuredClone(subDefaults);
+            }
+            else {
+                repaired[sub] = { ...subDefaults, ...value };
+            }
+        }
+        sections[key] = repaired;
+    }
+    // Device identity: a short, stable name so a notification says which machine
+    // the session is on. Hostname is the sensible default; it can be overridden
+    // when hostnames are opaque (e.g. `dev-box-7`).
+    const configuredDevice = String(resolved.device?.name ?? "").trim();
+    resolved.device = { name: configuredDevice || shortHostname() };
+    // Validation that must not throw in-process.
+    // allowFrom is checked with .length below, which a string also satisfies - and then
+    // every message throws in the allowlist check, killing the scan silently forever.
+    const rawAllow = resolved.security?.allowFrom;
+    if (!Array.isArray(rawAllow)) {
+        warnings.push("security.allowFrom must be an array of addresses — ignoring it (fail closed)");
+        resolved.security = { ...resolved.security, allowFrom: [] };
+    }
+    else {
+        resolved.security = { ...resolved.security, allowFrom: rawAllow.map((v) => String(v).trim()).filter(Boolean) };
+    }
+    // A quoted or non-numeric delay silently disables debouncing (setTimeout coerces it).
+    const rawDebounce = resolved.notify?.debounceMs;
+    const debounce = typeof rawDebounce === "number" ? rawDebounce : Number.NaN;
+    if (!Number.isFinite(debounce) || debounce < 0) {
+        if (rawDebounce !== undefined)
+            warnings.push("notify.debounceMs must be a non-negative number — using 10000");
+        resolved.notify = { ...resolved.notify, debounceMs: 10_000 };
+    }
+    // `listen("abc")` is a UNIX socket path in Node, and a float is not a port. The env var is
+    // documented, and injected as a string, so coerce it rather than trusting it.
+    const rawPort = resolved.daemon.port;
+    const port = typeof rawPort === "number" ? rawPort : Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        if (rawPort !== undefined)
+            warnings.push("daemon.port must be an integer 1-65535 — using 4177");
+        resolved.daemon = { ...resolved.daemon, port: 4177 };
+    }
+    else {
+        resolved.daemon = { ...resolved.daemon, port };
+    }
+    // Attachments are encoded ~4/3, and an over-limit send fails at the provider with the whole
+    // notification lost. Keep the default under the 25 MB Gmail/Outlook ceiling; cap the ceiling
+    // at what the largest common provider (QQ: 50 MB) accepts.
+    const rawMaxMb = resolved.notify.maxAttachmentMb;
+    if (rawMaxMb !== undefined) {
+        const mb = typeof rawMaxMb === "number" ? rawMaxMb : Number.NaN;
+        if (!Number.isFinite(mb) || mb < 1 || mb > 45) {
+            warnings.push("notify.maxAttachmentMb must be a number between 1 and 45 — using 18");
+            resolved.notify = { ...resolved.notify, maxAttachmentMb: 18 };
+        }
+        else {
+            resolved.notify = { ...resolved.notify, maxAttachmentMb: mb };
+        }
+    }
+    // A zero or NaN idle timeout makes the daemon exit ~1 s after the first ping, which looks
+    // like a crash-loop; a NaN token TTL makes a route never expire. Both fail closed. The floor
+    // is 3x the session poll interval: a timeout shorter than the ping period reaps the daemon
+    // between ticks, so it would flap instead of serving.
+    const rawIdle = resolved.daemon.idleTimeoutSecs;
+    const idle = typeof rawIdle === "number" ? rawIdle : Number.NaN;
+    if (!Number.isFinite(idle) || idle < 30) {
+        if (rawIdle !== undefined) {
+            warnings.push("daemon.idleTimeoutSecs must be at least 30 (three poll intervals) — using 120");
+        }
+        resolved.daemon = { ...resolved.daemon, idleTimeoutSecs: 120 };
+    }
+    const rawTtl = resolved.security.tokenTtlHours;
+    const ttl = typeof rawTtl === "number" ? rawTtl : Number.NaN;
+    if (!Number.isFinite(ttl) || ttl < 1) {
+        if (rawTtl !== undefined)
+            warnings.push("security.tokenTtlHours must be a positive number — using 720");
+        resolved.security = { ...resolved.security, tokenTtlHours: 30 * 24 };
+    }
+    // A negative, null or non-numeric interval would silently disable the safety net.
+    // `Number(null)` is 0, which would read as "the user disabled the sweep" — only a real
+    // number counts.
+    const rawInterval = resolved.daemon.scanIntervalSecs;
+    if (rawInterval !== undefined) {
+        const n = typeof rawInterval === "number" ? rawInterval : Number.NaN;
+        if (!Number.isFinite(n) || n < 0) {
+            warnings.push("daemon.scanIntervalSecs must be a non-negative number — using 60");
+            resolved.daemon = { ...resolved.daemon, scanIntervalSecs: 60 };
+        }
+        else {
+            resolved.daemon = { ...resolved.daemon, scanIntervalSecs: n };
+        }
+    }
+    const imap = resolved.mail.imap;
+    if (!imap.host || !imap.user)
+        warnings.push("mail.imap.host and mail.imap.user are required");
+    if (!resolved.mail.to)
+        warnings.push("mail.to is required");
+    // Setup validates this now; a hand-edited config still can be a typo, and every notification
+    // would go nowhere while the daemon reported itself healthy.
+    else if (!String(resolved.mail.to).includes("@")) {
+        warnings.push("mail.to does not look like an email address — notifications cannot be delivered");
+    }
+    if (resolved.security.allowFrom.length === 0) {
+        warnings.push("security.allowFrom is empty — every sender will be rejected (fail closed)");
+    }
+    // An unset authserv-id is a legitimate configuration now: authorization falls
+    // back to the topmost Authentication-Results header. Reported as a note by
+    // `--check`, not as a warning, because it is not a problem. Never a hard failure.
+    // XOAUTH2 needs exactly one token source: a built-in device-code flow or a command.
+    for (const side of ["imap", "smtp"]) {
+        const account = resolved.mail[side];
+        if (account.authType !== "XOAUTH2")
+            continue;
+        const hasCommand = Boolean(account.tokenCommand?.length);
+        const hasOAuth = Boolean(resolved.oauth?.issuer && resolved.oauth?.clientId);
+        if (!hasCommand && !hasOAuth) {
+            warnings.push(`mail.${side}.authType is XOAUTH2 but neither mail.${side}.tokenCommand nor oauth.issuer/oauth.clientId is set`);
+        }
+        if (hasOAuth && /(partner\.microsoftonline\.cn|chinacloudapi\.cn)/i.test(resolved.oauth?.issuer ?? "")) {
+            warnings.push("oauth.issuer points at the Azure China (21Vianet) sovereign cloud — apps registered there cannot authenticate against global Outlook.com; use login.microsoftonline.com");
+        }
+        if (hasOAuth && !/\boffline_access\b/.test(resolved.oauth?.scope ?? "")) {
+            warnings.push("oauth.scope should include offline_access, otherwise no refresh token is issued");
+        }
+        if (account.password) {
+            warnings.push(`mail.${side}.password is set but authType is XOAUTH2 — the password will be ignored`);
+        }
+    }
+    // A LOGIN account with no password cannot authenticate, and saying "config ok"
+    // in that state sends the user straight into a confusing smoke failure.
+    for (const side of ["imap", "smtp"]) {
+        const account = resolved.mail[side];
+        if (account.authType !== "XOAUTH2" && !account.password) {
+            warnings.push(`mail.${side}.password is empty — paste the provider's app password there (QQ/163 call it 授权码)`);
+        }
+    }
+    return resolved;
+}
+export function hasUsableMailConfig(c) {
+    return Boolean(c.mail.imap.host && c.mail.imap.user && c.mail.smtp.host && c.mail.to);
+}