@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/dist/daemon/spawn.js

@@ -0,0 +1,227 @@
+// Daemon supervision from the extension side.
+//
+// The extension must never assume a daemon is running: a session can start on a
+// freshly booted machine. `ensureDaemon` probes /health and, if nothing answers,
+// spawns the daemon detached so it outlives this pi session.
+//
+// Detached, with output appended to daemon.log (not stdio:ignore: a silent daemon made the
+// catch-up failures invisible). The daemon owns the mailbox and must outlive the
+// process that started it so another session (or the phone) can still be served. It is not
+// immortal: it exits once every session has stopped pinging.
+import { spawn as nodeSpawn } from "node:child_process";
+import { chmodSync, closeSync, mkdirSync, openSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { API_VERSION, apiCompatible } from "./api.js";
+import { statePath } from "../store/paths.js";
+/** True when a daemon answers /health. Never throws. */
+export async function probeHealth(options) {
+    const health = await probeHealthDetail(options);
+    return health.ok;
+}
+/**
+ * `/health`, with the protocol it speaks.
+ *
+ * `ok` means "something answered"; `apiVersion` says whether *this* build can use it. A daemon
+ * from another protocol is alive but unusable, and reusing it would make a replacement look
+ * successful while the mismatch stayed.
+ */
+export async function probeHealthDetail(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 750);
+    try {
+        const response = await doFetch(`${options.baseUrl}/health`, { signal: controller.signal });
+        if (!response.ok)
+            return { ok: false };
+        const body = (await response.json().catch(() => undefined));
+        return {
+            ok: true,
+            ...(typeof body?.apiVersion === "number" ? { apiVersion: body.apiVersion } : {}),
+        };
+    }
+    catch {
+        return { ok: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Make sure a daemon is running.
+ *
+ * Reuses an existing daemon rather than racing it: `daemon.lock` in the state directory is the
+ * lock (the port is a second guard), and a
+ * second daemon exits 0 on EADDRINUSE, so the worst case is a wasted spawn rather
+ * than two watchers on one mailbox.
+ */
+export async function ensureDaemon(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const found = await probeHealthDetail({ baseUrl: options.baseUrl, fetchImpl: doFetch });
+    if (found.ok) {
+        // Reuse only a daemon this build can talk to. An incompatible one is reported so the
+        // caller can replace it, instead of being adopted and failing on the first request.
+        if (apiCompatible(API_VERSION, found.apiVersion))
+            return { started: false, healthy: true };
+        return { started: false, healthy: false, incompatible: true, apiVersion: found.apiVersion };
+    }
+    const spawn = options.spawnImpl ?? nodeSpawn;
+    const execPath = options.execPath ?? process.execPath;
+    // The port this process probed, so the child cannot pick a different one from its own env -
+    // otherwise two daemons can end up on one state directory, which has no cross-process locks.
+    const probedPort = (() => {
+        try {
+            return new URL(options.baseUrl).port;
+        }
+        catch {
+            return "";
+        }
+    })();
+    // `--experimental-strip-types` only for the TypeScript entry: the published build runs
+    // `dist/daemon/main.js`, and Node refuses type stripping under `node_modules` anyway.
+    const args = [
+        ...(options.scriptPath.endsWith(".ts") ? ["--experimental-strip-types"] : []),
+        options.scriptPath,
+        ...(probedPort ? ["--port", probedPort] : []),
+        ...(options.args ?? []),
+    ];
+    // Detached with output ignored would make failures invisible: a catch-up scan could
+    // fail on every boot with nothing to show for it. Append to a log file instead.
+    const env = options.env ?? process.env;
+    const logPath = statePath(env, "daemon.log");
+    let logHandle;
+    try {
+        mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+        // One rotation at 5 MB: the log grows only when mail is seen, but it grows forever.
+        try {
+            if (statSync(logPath).size > 5 * 1024 * 1024)
+                renameSync(logPath, `${logPath}.1`);
+        }
+        catch {
+            /* no log yet, or cannot rotate - appending is still better than nothing */
+        }
+        logHandle = openSync(logPath, "a", 0o600);
+        // An older build created it 0644; the log carries addresses and session names.
+        try {
+            chmodSync(logPath, 0o600);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    catch {
+        // A read-only state dir must not stop the daemon from starting.
+    }
+    const child = spawn(execPath, args, {
+        detached: true,
+        stdio: logHandle === undefined ? "ignore" : ["ignore", logHandle, logHandle],
+        env,
+    });
+    // A fork failure (EAGAIN under fd pressure, a sandbox denying exec) arrives as an `error`
+    // event. Without a listener Node treats it as an uncaught exception in *pi's* process: the
+    // session dies while the daemon it was trying to start never existed.
+    let spawnError;
+    child.on?.("error", (error) => {
+        spawnError = error;
+    });
+    child.unref?.();
+    if (logHandle !== undefined) {
+        // The child holds its own copy of the descriptor.
+        try {
+            closeSync(logHandle);
+        }
+        catch {
+            /* already closed */
+        }
+    }
+    const sleep = options.sleep ?? defaultSleep;
+    const deadline = Date.now() + (options.waitMs ?? 5_000);
+    while (Date.now() < deadline) {
+        if (spawnError)
+            return { started: true, healthy: false, error: spawnError.message };
+        await sleep(100);
+        if (await probeHealth({ baseUrl: options.baseUrl, fetchImpl: doFetch })) {
+            return { started: true, healthy: true };
+        }
+    }
+    return { started: true, healthy: false };
+}
+/** Default loopback base URL for the configured port. */
+export function daemonBaseUrl(port, host = "127.0.0.1") {
+    return `http://${host}:${port}`;
+}
+/** SMTP transactions with inlined images are slow; be generous rather than lose the mail. */
+const SEND_TIMEOUT_MS = 120_000;
+/** Reload tears down and re-dials IMAP, which can involve a token fetch. */
+const RELOAD_TIMEOUT_MS = 120_000;
+export function createDaemonClient(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const deviceName = options.device ?? "";
+    const headers = { authorization: `Bearer ${options.token}`, "content-type": "application/json" };
+    async function call(method, path, body, timeoutMs = options.timeoutMs ?? 15_000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await doFetch(`${options.baseUrl}${path}`, {
+                method,
+                headers,
+                signal: controller.signal,
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                let code;
+                try {
+                    code = JSON.parse(text).error?.code;
+                }
+                catch {
+                    /* non-JSON error body */
+                }
+                return { ok: false, status: response.status, ...(code ? { code } : {}) };
+            }
+            return { ok: true, data: (text ? JSON.parse(text) : {}) };
+        }
+        catch (error) {
+            // A timeout is reported distinctly: the outcome is unknown, so callers must
+            // treat it like a network failure (retry later) rather than a definite "no".
+            if (error instanceof Error && error.name === "AbortError")
+                return { ok: false, status: 0, code: "timeout" };
+            return { ok: false, status: 0, code: "network" };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        health: () => call("GET", "/health"),
+        pending: () => call("GET", `/pending?device=${encodeURIComponent(deviceName)}`),
+        mode: () => call("GET", "/mode"),
+        setMode: (mode) => call("POST", "/mode", { mode }),
+        claim: (uid, instanceId, uidValidity) => call("POST", "/claim", {
+            uid,
+            instanceId,
+            ...(uidValidity === undefined ? {} : { uidValidity }),
+        }),
+        ack: (uid, instanceId, sessionId, uidValidity) => call("POST", "/ack", {
+            uid,
+            instanceId,
+            sessionId,
+            ...(uidValidity === undefined ? {} : { uidValidity }),
+        }),
+        register: (sessionId) => call("POST", "/register", { sessionId }),
+        release: (sessionId) => call("DELETE", "/register", { sessionId }),
+        // A notification can carry a few hundred KB of inlined images and the daemon awaits
+        // the whole SMTP transaction, so a slow-but-healthy relay must not be cut off: the
+        // generic 15 s ceiling would drop the one mail this product exists to deliver.
+        send: (message) => call("POST", "/send", message, SEND_TIMEOUT_MS),
+        /** Re-read config and restart the watcher (after setup or auth). */
+        // Includes an IMAP logout, an XOAUTH2 token fetch and a fresh dial.
+        reload: () => call("POST", "/reload", undefined, RELOAD_TIMEOUT_MS),
+        /** Ask the daemon to exit, so a fresh process can load updated code. */
+        shutdown: () => call("POST", "/shutdown"),
+        /** Liveness heartbeat; the daemon exits when every client stops pinging. */
+        ping: (instanceId) => call("POST", "/ping", { instanceId }),
+        /** Tell the daemon this session is gone. */
+        bye: (instanceId) => call("POST", "/bye", { instanceId }),
+    };
+}

package/dist/daemon/watcher.js

@@ -0,0 +1,308 @@
+// IMAP IDLE watcher — the read side. Port of opencode-afk `core/watcher.js`.
+//
+// One connection per machine, owned by the daemon, exposed to the scan pipeline
+// as a `MailSource`. Two things make this testable without a socket:
+//   - the client comes from an injectable factory (`ImapClientFactory`)
+//   - body decoding comes from an injectable parser (`BodyParser`)
+//
+// Design notes carried over from the reference implementation:
+//   - IDLE renews well under the server's ~29 minute timeout
+//   - reconnect is exponential and bounded
+//   - credentials are never logged
+//   - errors are summarised from responseStatus/responseText only
+import { simpleParser } from "mailparser";
+import { decodeRfc2047 } from "../core/header-encoding.js";
+export const DEFAULT_IDLE_RENEW_MS = 25 * 60 * 1000;
+/**
+ * Hard ceiling on a message we will parse. The attachment caps (4 x 1 MB) live well inside
+ * it; anything larger is refused before the body is downloaded.
+ */
+export const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+const DEFAULT_BACKOFF_INITIAL_MS = 1_000;
+export const DEFAULT_BACKOFF_MAX_MS = 60_000;
+/** Headers the authorization and routing layers need. */
+export const WANTED_HEADERS = [
+    "authentication-results",
+    "auto-submitted",
+    "precedence",
+    "x-auto-response-suppress",
+    "list-id",
+    "from",
+    "subject",
+    // Our own Message-ID and marker, so a notification that comes back is recognised as an
+    // echo even if the id was never recorded (a send that raced the scan).
+    "message-id",
+    "x-pi-mailbridge",
+    // Reply-chain fallback: threading headers, so a reply reaches the session even
+    // when the subject token was rewritten by a client or a human.
+    "in-reply-to",
+    "references",
+];
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for tests)
+// ---------------------------------------------------------------------------
+/**
+ * IMAP UID range for "everything after `cursor`". UIDs are 32-bit and a server
+ * may assign 0, so `1:*` is the safe floor.
+ */
+export function searchRangeFor(cursor) {
+    return `${Math.max(1, cursor + 1)}:*`;
+}
+/** Bounded exponential backoff. */
+export function nextBackoff(attempt, initial = DEFAULT_BACKOFF_INITIAL_MS, max = DEFAULT_BACKOFF_MAX_MS) {
+    const safeAttempt = Math.max(0, Math.min(attempt, 30));
+    return Math.min(max, initial * 2 ** safeAttempt);
+}
+export function extractHeaders(raw) {
+    const text = typeof raw === "string" ? raw : raw.toString("utf8");
+    // Headers end at the first blank line.
+    const end = text.search(/\r?\n\r?\n/);
+    const head = end === -1 ? text : text.slice(0, end);
+    const unfolded = head.replace(/\r?\n[ \t]+/g, " ");
+    const headerValues = new Map();
+    for (const line of unfolded.split(/\r?\n/)) {
+        const colon = line.indexOf(":");
+        if (colon <= 0)
+            continue;
+        const name = line.slice(0, colon).trim().toLowerCase();
+        const value = line.slice(colon + 1).trim();
+        if (!name)
+            continue;
+        const existing = headerValues.get(name);
+        if (existing)
+            existing.push(value);
+        else
+            headerValues.set(name, [value]);
+    }
+    const pick = (name) => {
+        const values = headerValues.get(name);
+        if (!values)
+            return undefined;
+        // From/Subject are logically single-valued; servers may fold them, so join
+        // rather than silently using only the first instance. Then decode RFC 2047:
+        // a client that encodes a subject makes the routing token unreadable otherwise.
+        return decodeRfc2047(values.join(" "));
+    };
+    return { headerValues, from: pick("from"), subject: pick("subject") };
+}
+/** Map extracted headers onto the shape the authorization layer consumes. */
+export function toHeaderLike(extracted) {
+    const one = (name) => extracted.headerValues.get(name)?.[0];
+    return {
+        from: extracted.from,
+        subject: extracted.subject,
+        authResults: extracted.headerValues.get("authentication-results"),
+        // message-id is what lets the scanner recognise our own notification coming back.
+        ...(one("message-id") ? { messageId: one("message-id") } : {}),
+        ...(one("x-pi-mailbridge") ? { piMailbridge: one("x-pi-mailbridge") } : {}),
+        ...(one("in-reply-to") ? { inReplyTo: one("in-reply-to") } : {}),
+        ...(extracted.headerValues.get("references") ? { references: extracted.headerValues.get("references") } : {}),
+        autoSubmitted: one("auto-submitted"),
+        precedence: one("precedence"),
+        autoResponseSuppress: one("x-auto-response-suppress"),
+        listId: one("list-id"),
+    };
+}
+export const defaultBodyParser = async (raw) => {
+    const parsed = await simpleParser(raw);
+    const attachments = (parsed.attachments ?? []).map((a) => ({
+        ...(a.filename ? { filename: a.filename } : {}),
+        contentType: a.contentType ?? "application/octet-stream",
+        content: a.content,
+    }));
+    return {
+        text: parsed.text ?? "",
+        ...(parsed.html ? { html: parsed.html } : {}),
+        attachments,
+    };
+};
+/** Coarse HTML → text: enough to keep the human's words, not a renderer. */
+export function htmlToText(html) {
+    return html
+        .replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/(p|div|tr|li|h[1-6])>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/[ \t]{2,}/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+const defaultTimers = {
+    setTimeout: (handler, ms) => setTimeout(handler, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+// ---------------------------------------------------------------------------
+// Watcher
+// ---------------------------------------------------------------------------
+/** imapflow reports these as bigint; normalise both to a safe number. */
+function normaliseUid(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = typeof raw === "bigint" ? Number(raw) : raw;
+    return Number.isFinite(value) ? value : undefined;
+}
+export function createImapWatcher(config, options) {
+    const { factory, callbacks } = options;
+    const parser = options.parser ?? defaultBodyParser;
+    const timers = options.timers ?? defaultTimers;
+    const idleRenewMs = config.tuning.idleRenewMs ?? DEFAULT_IDLE_RENEW_MS;
+    let client;
+    let reconnectHandle;
+    let attempt = 0;
+    let stopped = false;
+    let connecting = false;
+    async function teardown(target) {
+        // Take the connection explicitly when the caller still holds it: stop() may already
+        // have nulled `client` (and logged out nothing, because the dial had not finished),
+        // and tearing down `client` again would silently do nothing.
+        const c = target ?? client;
+        // Clear it either way: after a stop during the dial, `client` was assigned the very
+        // connection we are about to close, and leaving it set lets search/fetch reach a
+        // logged-out socket instead of failing fast.
+        if (client === c)
+            client = undefined;
+        if (!c)
+            return;
+        try {
+            await c.logout();
+        }
+        catch {
+            // A dead connection cannot log out; that is expected during reconnect.
+        }
+    }
+    function scheduleReconnect(error) {
+        // A dying connection emits both "close" and "error", and connectOnce's catch adds a
+        // third path. Without this guard each one arms its own timer, so the watcher opens
+        // several connections and leaks all but the last.
+        if (stopped || reconnectHandle !== undefined || connecting)
+            return;
+        const delay = nextBackoff(attempt, config.tuning.backoffInitialMs, config.tuning.backoffMaxMs);
+        attempt++;
+        callbacks.onError?.(error, delay);
+        reconnectHandle = timers.setTimeout(() => {
+            reconnectHandle = undefined;
+            void connectOnce();
+        }, delay);
+    }
+    async function connectOnce() {
+        if (stopped || connecting)
+            return;
+        connecting = true;
+        try {
+            const c = await factory(config, { idleRenewMs });
+            client = c;
+            await c.connect();
+            await c.mailboxOpen(config.mail.imap.folder || "INBOX");
+            // stop() may have run while those were awaited; the entry check cannot see that.
+            // Without this, the connection stays open with handlers attached and nothing
+            // will ever tear it down (isHealthy() would meanwhile report false).
+            if (stopped) {
+                await teardown(c);
+                return;
+            }
+            attempt = 0;
+            c.on("exists", () => callbacks.onMail());
+            c.on("close", () => {
+                if (stopped)
+                    return;
+                scheduleReconnect(new Error("imap connection closed"));
+            });
+            c.on("error", (error) => scheduleReconnect(error instanceof Error ? error : new Error(String(error))));
+            callbacks.onReady();
+        }
+        catch (error) {
+            await teardown();
+            // Clear the in-flight flag first: scheduleReconnect refuses while a connect is
+            // pending, and this catch is one of the legs that must be able to arm it.
+            connecting = false;
+            scheduleReconnect(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            connecting = false;
+        }
+    }
+    return {
+        async start() {
+            stopped = false;
+            await connectOnce();
+        },
+        async stop() {
+            stopped = true;
+            if (reconnectHandle !== undefined) {
+                timers.clearTimeout(reconnectHandle);
+                reconnectHandle = undefined;
+            }
+            await teardown();
+        },
+        /** The open mailbox's UIDVALIDITY, when the client exposes one. */
+        uidValidity() {
+            return normaliseUid(client?.mailbox?.uidValidity);
+        },
+        /** The open mailbox's next UID, when the client exposes one. */
+        uidNext() {
+            return normaliseUid(client?.mailbox?.uidNext);
+        },
+        isHealthy() {
+            return !stopped && client !== undefined && client.usable !== false;
+        },
+        async searchAfter(afterUid) {
+            const c = client;
+            if (!c)
+                throw new Error("imap watcher not connected");
+            const uids = await c.search({ uid: searchRangeFor(afterUid) }, { uid: true });
+            return uids.filter((n) => Number.isFinite(n) && n > afterUid).sort((a, b) => a - b);
+        },
+        async fetch(uid) {
+            const c = client;
+            if (!c)
+                throw new Error("imap watcher not connected");
+            // Ask for the size first: the full source is downloaded before authorization, so
+            // an oversized message from any sender - spam, a 200 MB newsletter - would cost the
+            // one shared daemon a full download and parse. `size` is cheap and needs no body.
+            const meta = (await c.fetchOne(uid, { size: true, envelope: true }, { uid: true }));
+            if (meta && typeof meta.size === "number" && meta.size > MAX_MESSAGE_BYTES) {
+                return {
+                    uid,
+                    from: meta.envelope?.from?.[0]?.address,
+                    subject: meta.envelope?.subject,
+                    text: "",
+                    headers: { subject: meta.envelope?.subject },
+                    receivedAt: Date.now(),
+                    tooLarge: meta.size,
+                };
+            }
+            const fetched = (await c.fetchOne(uid, { source: true, envelope: true, headers: [...WANTED_HEADERS] }, { uid: true }));
+            if (!fetched || !fetched.source)
+                return undefined;
+            const extracted = extractHeaders(fetched.source);
+            const parsed = await parser(fetched.source);
+            // A body with no text content falls back to the HTML part, tag-stripped. Testing for
+            // content, not for undefined: mailparser yields "" for a text/html-only multipart.
+            const bodyText = parsed.text?.trim() ? parsed.text : parsed.html ? htmlToText(parsed.html) : "";
+            const from = extracted.from ?? fetched.envelope?.from?.[0]?.address;
+            const subject = extracted.subject ?? fetched.envelope?.subject;
+            return {
+                uid,
+                from,
+                subject,
+                text: bodyText,
+                ...(parsed.attachments?.length ? { attachments: parsed.attachments } : {}),
+                headers: toHeaderLike(extracted),
+                receivedAt: Date.now(),
+            };
+        },
+        /** Mailbox hygiene, invoked by the daemon's /ack handler only. */
+        async markSeen(uid) {
+            const c = client;
+            if (!c?.messageFlagsAdd)
+                return;
+            await c.messageFlagsAdd(uid, ["\\Seen"], { uid: true });
+        },
+    };
+}