@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/dist/daemon/service.js

@@ -0,0 +1,455 @@
+// Daemon HTTP service.
+//
+// Transport-neutral: construction takes its collaborators, so tests boot the real
+// server against fake mail/source and assert the whole contract over HTTP.
+//
+// Auth: every route except /health requires `Authorization: Bearer <token>`,
+// compared in constant time. Loopback is not authorization.
+//
+// Bounds: request body, SSE clients, registry entries. A local process should not
+// be able to exhaust the daemon.
+import http from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { CAPABILITIES } from "./api.js";
+import { createSendBudget } from "./send-budget.js";
+import { ackPending, claimPending, listPending } from "../store/pending-store.js";
+import { journal } from "../store/journal.js";
+import { recordOutbound, removeOutbound, sessionThread } from "../store/threads.js";
+import { generateMessageId } from "../core/mailer.js";
+import { readMode, writeMode, isMode } from "../store/mode-store.js";
+import { createRegistry } from "../store/registry.js";
+export const MAX_BODY_BYTES = 1_000_000;
+/** A body that is not JSON: the caller's fault, and the only 400 the handler emits. */
+class BadBodyError extends Error {
+}
+async function readJson(req) {
+    const text = await readBody(req);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new BadBodyError("body is not valid JSON");
+    }
+}
+export const MAX_SSE_CLIENTS = 100;
+/** Heartbeat entries kept; sessions that vanished are pruned on /health anyway. */
+export const MAX_PINGS = 256;
+function constantTimeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+export function createDaemonService(deps) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? (() => Date.now());
+    const registry = deps.registry ?? createRegistry();
+    /** live SSE response objects */
+    const streams = new Set();
+    // Sliding one-minute budget for outbound mail. Ten notifications a minute is far above any
+    // human-answered flow; the point is that a loop cannot spend the account's quota.
+    const sendBudget = createSendBudget({ limit: 10, windowMs: 60_000 });
+    // Liveness of pi sessions. A session pings on its poll tick; when every session has gone quiet
+    // the daemon stops - always, and by design: an updated package cannot leave an orphan running
+    // old code, and nothing reads a mailbox no session will consume. A daemon nobody ever pings
+    // (started by hand, and pi never attached) stops on the same clock.
+    const pings = new Map();
+    // Idleness is measured from the daemon's own start when nobody has pinged yet, so a fresh
+    // daemon gets the full grace period rather than looking infinitely stale.
+    const startedAt = Date.now();
+    const idleTimeout = deps.idleTimeoutMs ?? 120_000;
+    const idleCheck = setInterval(() => {
+        const newest = Math.max(startedAt, ...pings.values());
+        if (Date.now() - newest <= idleTimeout)
+            return;
+        deps.shutdown?.(`idle: no ping for ${Math.round(idleTimeout / 1000)}s`);
+    }, Math.min(15_000, Math.max(1_000, Math.floor(idleTimeout / 4))));
+    // Never hold the process open just for this timer.
+    if (typeof idleCheck.unref === "function")
+        idleCheck.unref();
+    function broadcast(event) {
+        const payload = `data: ${JSON.stringify(event)}\n\n`;
+        for (const res of streams) {
+            try {
+                res.write(payload);
+            }
+            catch {
+                streams.delete(res);
+            }
+        }
+    }
+    // The handler is a separate function so a throw anywhere in it - including the URL parse,
+    // which runs before authentication - becomes a 500 rather than an unhandled rejection that
+    // kills the daemon. Node accepts absolute-form request targets, so `new URL` can throw on a
+    // single unauthenticated request.
+    const dispatch = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const send = (status, body) => {
+            const payload = JSON.stringify(body);
+            res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(payload) });
+            res.end(payload);
+        };
+        const fail = (status, code, extra) => send(status, { error: { code, ...extra } });
+        // Liveness is unauthenticated so a supervisor can probe without a secret.
+        if (url.pathname === "/health") {
+            // Prune here as well as on /bye: a crashed session never sends one, and an
+            // unbounded map plus a spread into Math.max is its own failure mode.
+            const nowMs = now();
+            const stale = nowMs - (deps.idleTimeoutMs ?? 120_000) * 4;
+            for (const [id, at] of pings)
+                if (at < stale)
+                    pings.delete(id);
+            // Track the maximum by iteration: spreading an unbounded map into Math.max throws
+            // RangeError (and kills the daemon) long before the map is "large".
+            let newestPing = 0;
+            for (const at of pings.values())
+                if (at > newestPing)
+                    newestPing = at;
+            return send(200, {
+                ok: true,
+                mode: readMode(env),
+                pending: listPending(env).length,
+                // `sessions` is the decision registry (sessions that were told about a
+                // notification), not connected clients — a raw payload showed `sessions: 0`
+                // next to `clients: 2`. Both keys, so neither reading is wrong.
+                sessions: registry.list().length,
+                registry: registry.list().length,
+                sseClients: streams.size,
+                // Liveness: how many sessions are pinging, and how long ago the last one did.
+                clients: pings.size,
+                lastPingAgoMs: newestPing ? Math.max(0, now() - newestPing) : null,
+                lastScan: deps.scanSummary?.() ?? null,
+                // Diagnostic (which build), and the contract (which protocol). The session
+                // replaces a daemon whose apiVersion differs; the version is for the panel.
+                version: deps.version,
+                apiVersion: deps.apiVersion,
+                capabilities: CAPABILITIES,
+                configLoadedAt: deps.configLoadedAt?.() ?? null,
+                imap: deps.imapHealthy ? (deps.imapHealthy() ? "connected" : "disconnected") : "unknown",
+            });
+        }
+        const header = req.headers.authorization ?? "";
+        const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+        if (!constantTimeEqual(presented, deps.token))
+            return fail(401, "unauthorized");
+        const route = `${req.method} ${url.pathname}`;
+        try {
+            switch (route) {
+                case "GET /events": {
+                    if (streams.size >= MAX_SSE_CLIENTS)
+                        return fail(503, "too_many_clients");
+                    res.writeHead(200, {
+                        "content-type": "text/event-stream",
+                        "cache-control": "no-cache",
+                        connection: "keep-alive",
+                    });
+                    res.write(": connected\n\n");
+                    // Tell a fresh client the current mode immediately.
+                    res.write(`data: ${JSON.stringify({ type: "mode", mode: readMode(env) })}\n\n`);
+                    streams.add(res);
+                    req.on("close", () => streams.delete(res));
+                    return undefined;
+                }
+                case "GET /pending": {
+                    // Filtered: a whole-file payload of another machine's mail is both wrong to
+                    // deliver and wastefully large. The daemon's own live config is the authority -
+                    // the same one /claim uses - so a client holding a stale device name (renamed,
+                    // or rewritten by `setup`) cannot ask for records it will then be refused.
+                    const mine = deps.getConfig?.()?.device.name;
+                    const all = listPending(env);
+                    const offered = mine ? all.filter((r) => r.device === undefined || r.device === mine) : all;
+                    return send(200, {
+                        pending: offered,
+                        // A count, never the content: these are another device's replies, and after a
+                        // rename they are the user's own mail sitting here invisible.
+                        withheld: all.length - offered.length,
+                    });
+                }
+                case "GET /mode":
+                    return send(200, { mode: readMode(env) });
+                case "POST /claim": {
+                    const body = asRecord(await readJson(req));
+                    const uid = Number(body?.uid);
+                    const instanceId = typeof body?.instanceId === "string" ? body.instanceId : "";
+                    if (!Number.isInteger(uid) || !instanceId)
+                        return fail(400, "bad_request");
+                    const uidValidity = typeof body?.uidValidity === "number" && Number.isFinite(body.uidValidity) ? body.uidValidity : undefined;
+                    const result = claimPending(env, uid, instanceId, now(), uidValidity, deps.source.uidValidity?.(), deps.getConfig?.()?.device.name);
+                    if (!result.ok)
+                        return fail(result.reason === "not-found" ? 404 : 409, result.reason);
+                    return send(200, { ok: true });
+                }
+                case "POST /ack": {
+                    const body = asRecord(await readJson(req));
+                    const uid = Number(body?.uid);
+                    const instanceId = typeof body?.instanceId === "string" ? body.instanceId : "";
+                    if (!Number.isInteger(uid) || !instanceId)
+                        return fail(400, "bad_request");
+                    // Remove the record, THEN journal, then touch the mail. The order looks
+                    // backwards but is the safe one: the journal is read at scan time, so
+                    // journalling while the record still exists would leave a window where a
+                    // polling session claims and injects the same reply twice. Losing the
+                    // journal write after a successful ack only re-opens dedupe for a UID that
+                    // is no longer in `pending`, which the scanner never reads again.
+                    const uidValidity = typeof body?.uidValidity === "number" && Number.isFinite(body.uidValidity) ? body.uidValidity : undefined;
+                    const acked = ackPending(env, uid, instanceId, uidValidity, deps.source.uidValidity?.());
+                    if (!acked.ok)
+                        return fail(acked.reason === "not-found" ? 404 : 409, acked.reason);
+                    // The record's space, never the watcher's: after a renumbering the two differ,
+                    // and journaling under the live space would suppress a brand-new message at
+                    // that UID. A record predating UIDVALIDITY carries none, and journal() then
+                    // keeps the space the file already records.
+                    journal(env, uid, acked.uidValidity);
+                    // The record's session, never the request body's: a client that acks
+                    // another session's mail must not also free its decision slot.
+                    registry.release(acked.sessionId);
+                    // Mailbox hygiene only. A failure here must not resurrect the delivery.
+                    try {
+                        await deps.source.markSeen?.(uid);
+                    }
+                    catch {
+                        /* logged by the caller in production; delivery is already acked */
+                    }
+                    return send(200, { ok: true });
+                }
+                case "POST /register": {
+                    const body = asRecord(await readJson(req));
+                    const sessionId = typeof body?.sessionId === "string" ? body.sessionId : "";
+                    if (!sessionId)
+                        return fail(400, "bad_request");
+                    const result = registry.register(sessionId);
+                    if (result.full)
+                        return fail(503, "registry_full");
+                    return send(200, result);
+                }
+                case "DELETE /register": {
+                    const body = asRecord(await readJson(req));
+                    const sessionId = typeof body?.sessionId === "string" ? body.sessionId : "";
+                    if (!sessionId)
+                        return fail(400, "bad_request");
+                    registry.release(sessionId);
+                    return send(200, { ok: true });
+                }
+                case "POST /ping": {
+                    const body = asRecord(await readJson(req));
+                    const instanceId = typeof body?.instanceId === "string" ? body.instanceId : "";
+                    if (!instanceId)
+                        return fail(400, "bad_request");
+                    pings.set(instanceId, now());
+                    // Bounded: a client that keeps changing its id must not grow this map without
+                    // limit. Oldest entries are dropped first.
+                    while (pings.size > MAX_PINGS) {
+                        const oldest = pings.keys().next().value;
+                        if (oldest === undefined)
+                            break;
+                        pings.delete(oldest);
+                    }
+                    return send(200, { ok: true, clients: pings.size });
+                }
+                case "POST /bye": {
+                    const body = asRecord(await readJson(req));
+                    const instanceId = typeof body?.instanceId === "string" ? body.instanceId : "";
+                    if (!instanceId)
+                        return fail(400, "bad_request");
+                    pings.delete(instanceId);
+                    return send(200, { ok: true, clients: pings.size });
+                }
+                case "POST /shutdown": {
+                    if (!deps.shutdown)
+                        return fail(501, "not_supported");
+                    // Answer first, then exit: a client that got no response would report
+                    // a failure for a restart that actually worked.
+                    send(200, { ok: true });
+                    setTimeout(() => deps.shutdown?.(), 50);
+                    return undefined;
+                }
+                case "POST /reload": {
+                    if (!deps.reload)
+                        return fail(501, "not_supported");
+                    try {
+                        const result = await deps.reload();
+                        if (!result.ok)
+                            return fail(500, "reload_failed", { message: result.error ?? "unknown" });
+                        return send(200, { ok: true, ...(result.warning ? { warning: result.warning } : {}) });
+                    }
+                    catch (error) {
+                        return fail(500, "reload_failed", { message: error.message });
+                    }
+                }
+                case "POST /mode": {
+                    const body = asRecord(await readJson(req));
+                    if (!isMode(body?.mode))
+                        return fail(400, "bad_request");
+                    const mode = writeMode(env, body.mode, now());
+                    broadcast({ type: "mode", mode });
+                    deps.onModeChange?.(mode);
+                    return send(200, { mode });
+                }
+                case "POST /send": {
+                    const body = asRecord(await readJson(req));
+                    const subject = typeof body?.subject === "string" ? body.subject : "";
+                    const text = typeof body?.text === "string" ? body.text : "";
+                    const config = deps.getConfig?.() ?? deps.config;
+                    const to = typeof body?.to === "string" && body.to ? body.to : config.mail.to;
+                    // cwd lets the mailer resolve relative image paths from the agent's project.
+                    const cwd = typeof body?.cwd === "string" ? body.cwd : undefined;
+                    // sessionId lets the sender thread this mail into the session's conversation.
+                    const sessionId = typeof body?.sessionId === "string" ? body.sessionId : undefined;
+                    if (!subject || !text)
+                        return fail(400, "bad_request");
+                    // A budget, not a rate limiter: an injected agent can ask for unbounded mail.
+                    // A settle notification is exempt - it is the one mail that says the agent is
+                    // waiting, and a legitimate `notify_user` burst must not silence it.
+                    const kind = body?.kind === "settle" ? "settle" : body?.kind === "decision" ? "decision" : "notification";
+                    // Only unbounded, model-driven notifications are budgeted: a settle says the
+                    // agent is waiting, and a decision is already capped at one outstanding per
+                    // session by the registry.
+                    if (kind === "notification" && !sendBudget.take(Date.now())) {
+                        return fail(429, "send_budget");
+                    }
+                    // Thread every notification for a session into one conversation: reply to
+                    // the previous message, reference the session root. Read BEFORE sending,
+                    // because recording happens after.
+                    // Mint and record BEFORE calling deps.send. The scan can see the mail come
+                    // back into INBOX as soon as SMTP accepts it, so an id recorded after the
+                    // send leaves the self-echo guard empty for exactly that window.
+                    // Read the thread BEFORE recording: recording moves lastMessageId to the new
+                    // id, and a message must answer its predecessor, not itself.
+                    const thread = sessionId ? sessionThread(env, sessionId) : {};
+                    const messageId = generateMessageId(config.mail.smtp.user ?? "");
+                    if (sessionId) {
+                        recordOutbound(env, {
+                            messageId,
+                            sessionId,
+                            device: config.device.name,
+                            subject,
+                        });
+                    }
+                    const threading = {
+                        ...(thread.lastMessageId ? { inReplyTo: `<${thread.lastMessageId}>` } : {}),
+                        ...(thread.rootMessageId ? { references: [`<${thread.rootMessageId}>`] } : {}),
+                    };
+                    try {
+                        const result = await deps.send({
+                            to,
+                            subject,
+                            text,
+                            ...(cwd ? { cwd } : {}),
+                            ...(sessionId ? { sessionId } : {}),
+                            messageId,
+                            ...threading,
+                        });
+                        // Sends were invisible in daemon.log: "did my notification go out?" had no
+                        // answer. Kind and size only - never the subject, per AGENTS invariant 8.
+                        deps.log?.(`send ok (${kind}, ${text.length} chars)`);
+                        // Record the outbound id so a reply reaches this session even if a
+                        // client or a human rewrites the subject token away.
+                    }
+                    catch (error) {
+                        // The id was recorded before the send, because the mail can come back
+                        // before the transport resolves. It will not come back now, so drop it:
+                        // otherwise the next notification threads against a parent that never
+                        // existed.
+                        removeOutbound(env, messageId);
+                        return fail(502, "send_failed", { message: error.message });
+                    }
+                    // Bookkeeping only, and outside the failure path: a recording error here must
+                    // not report a delivered mail as undelivered.
+                    try {
+                        deps.onSent?.({ messageId, subject, ...(sessionId ? { sessionId } : {}) });
+                    }
+                    catch {
+                        /* the thread store is an optimisation; the mail is already gone */
+                    }
+                    return send(200, { ok: true });
+                }
+                default:
+                    return fail(404, "not_found");
+            }
+        }
+        catch (error) {
+            const message = error.message;
+            if (message === "request body too large")
+                return fail(413, "body_too_large");
+            // Classified by cause, not by prose: a store write failure mentions `threads.json`,
+            // and a substring match on "json" reported it as the client's fault.
+            if (error instanceof BadBodyError)
+                return fail(400, "bad_request", { message });
+            return fail(500, "internal", { message });
+        }
+    };
+    const server = http.createServer((req, res) => {
+        void dispatch(req, res).catch(() => {
+            // A malformed request must not take the process down with it.
+            try {
+                if (!res.headersSent) {
+                    res.writeHead(500, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: { code: "internal" } }));
+                }
+                else {
+                    res.destroy();
+                }
+            }
+            catch {
+                /* the socket is already gone */
+            }
+        });
+    });
+    // Unparseable HTTP never reaches the handler at all.
+    server.on("clientError", (_error, socket) => {
+        socket.destroy();
+    });
+    return {
+        server,
+        get sseClients() {
+            return streams.size;
+        },
+        broadcast,
+        // Never fall back to the unspecified address: `undefined` binds 0.0.0.0, and the port is
+        // what keeps one daemon per machine. loadConfig repairs this, so this is a belt.
+        listen(port = deps.config.daemon.port, host = deps.config.daemon.host || "127.0.0.1") {
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(port, host, () => {
+                    server.removeListener("error", reject);
+                    const address = server.address();
+                    resolve({ port: typeof address === "object" && address ? address.port : port, host });
+                });
+            });
+        },
+        close() {
+            clearInterval(idleCheck);
+            return new Promise((resolve) => {
+                for (const res of streams) {
+                    try {
+                        res.end();
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+                streams.clear();
+                server.close(() => resolve());
+            });
+        },
+    };
+}

package/dist/daemon/source-proxy.js

@@ -0,0 +1,64 @@
+// The MailSource the daemon actually hands to the scanner and the HTTP service.
+//
+// This is a seam, not a convenience: it exists so a test can exercise exactly what production
+// wires up. Three rounds of "the guard is inert in production" came from code that was only
+// ever tested through a hand-built fixture, so the proxy and the UIDVALIDITY bookkeeping live
+// here, in one small file, where they can be driven directly.
+import { dropPendingFromOtherSpaces, listPending } from "../store/pending-store.js";
+import { syncUidValidity } from "../store/uid-cursor.js";
+export function createSourceProxy(deps) {
+    const target = () => {
+        const watcher = deps.watcher();
+        if (!watcher)
+            throw new Error("pi-mailbridge: imap watcher not started");
+        return watcher;
+    };
+    return {
+        searchAfter: (uid) => target().searchAfter(uid),
+        fetch: (uid) => target().fetch(uid),
+        markSeen: async (uid) => {
+            await deps.watcher()?.markSeen?.(uid);
+        },
+        // Every call reads the live watcher: the daemon swaps watchers on reload, and a
+        // captured reference would answer from the old connection.
+        uidValidity: () => deps.watcher()?.uidValidity(),
+    };
+}
+/**
+ * Compare the mailbox's UIDVALIDITY with the recorded one, and reset what a renumbering
+ * invalidates.
+ *
+ * Called on every successful connect. A renumbering cannot be detected by the cursor alone,
+ * so this is the only place it is noticed - and the only place its consequences are undone.
+ */
+export function applyUidValidity(env, watcher, onDropped) {
+    const validity = watcher?.uidValidity();
+    if (validity === undefined)
+        return { reset: false, validity, dropped: 0 };
+    const reset = syncUidValidity(env, validity, watcher?.uidNext());
+    // Drop on EVERY connect, not only on a reset: a crash between the cursor write and the
+    // drop leaves records from another space that nothing can claim (the guard refuses them)
+    // and nothing would ever remove, because the cursor already carries the new validity.
+    // Queued records from the wrong numbering could collide with new UIDs and be replaced
+    // silently. Dropping them is safe: they were never acked, so the mail is still unread.
+    // On a reset the cursor re-reads it; on the orphan path (no reset) the message is behind
+    // an already-advanced cursor, which is why the drop runs every connect. Their decision
+    // slots are freed, or that session would be told it has an outstanding decision for a day.
+    // Only records from another UID space are dropped here. Age-based expiry used to run on every
+    // connect, which deleted replies for sessions that were merely quiet - a user on `off` for a
+    // week came home to nothing to drain, with the cursor already past the mail. Expiry now
+    // happens under queue pressure only (see process.ts).
+    // On a reset, unknown-space records go too: see dropPendingFromOtherSpaces.
+    const dropped = dropPendingFromOtherSpaces(env, validity, { includeUnknown: reset });
+    if (dropped.length > 0) {
+        // Only free a slot the dropped record was holding: a session that still has a live
+        // record in the current space must keep its reservation, or it could be granted a
+        // second decision while the first is unanswered.
+        const stillQueued = new Set(listPending(env).map((r) => r.sessionId));
+        for (const record of dropped) {
+            if (!stillQueued.has(record.sessionId))
+                onDropped?.(record.sessionId);
+        }
+    }
+    return { reset, validity, dropped: dropped.length };
+}