@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/dist/store/journal.js

@@ -0,0 +1,92 @@
+// Acked UIDs — durable replay protection.
+//
+// The cursor says what we have *seen*; the journal says what a session has *acked*. A crash
+// between the two is why this file exists.
+//
+// UIDs are only meaningful within one UIDVALIDITY, so the journal stores the one it belongs
+// to. A re-indexed mailbox renumbers from 1, and an old journal then suppresses brand-new
+// mail as "already acked" - so a validity mismatch means the journal is not consulted.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { statePath } from "./paths.js";
+import { StateVersionError, checkStateVersion, stamp } from "./schema.js";
+/** Keep the last N acked UIDs. */
+export const JOURNAL_CAP = 5_000;
+function path(env) {
+    return statePath(env, "journal.json");
+}
+function loadFile(env) {
+    const p = path(env);
+    try {
+        if (!existsSync(p))
+            return { uids: [] };
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        checkStateVersion("journal.json", parsed);
+        return {
+            uids: Array.isArray(parsed?.uids) ? parsed.uids.filter((n) => typeof n === "number") : [],
+            ...(typeof parsed?.uidValidity === "number" ? { uidValidity: parsed.uidValidity } : {}),
+        };
+    }
+    catch (error) {
+        if (error instanceof StateVersionError)
+            throw error;
+        return { uids: [] };
+    }
+}
+function save(env, file) {
+    const p = path(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    const tmp = `${p}.${process.pid}.tmp`;
+    const trimmed = file.uids.length > JOURNAL_CAP ? file.uids.slice(file.uids.length - JOURNAL_CAP) : file.uids;
+    writeFileSync(tmp, JSON.stringify({ ...stamp(), ...file, uids: trimmed }), { mode: 0o600 });
+    renameSync(tmp, p);
+}
+/**
+ * Has this UID been acked?
+ *
+ * When the caller knows the mailbox's UIDVALIDITY and it differs from the journal's, the
+ * answer is "no": those UIDs belonged to a different numbering and say nothing about this one.
+ */
+export function isJournaled(env, uid, uidValidity) {
+    const file = loadFile(env);
+    if (uidValidity !== undefined) {
+        // The caller knows the live numbering. A journal tagged with a different space cannot
+        // answer for it - and neither can an untagged one, written before the field existed:
+        // after a renumbering its old UIDs are reused, and "already seen" would let the cursor
+        // advance past genuinely new mail.
+        if (file.uidValidity === undefined)
+            return false;
+        if (file.uidValidity !== uidValidity)
+            return false;
+    }
+    return file.uids.includes(uid);
+}
+/** Append `uid` (idempotent). Returns false when it was already journaled. */
+export function journal(env, uid, uidValidity) {
+    const file = loadFile(env);
+    // A new numbering starts a new journal: keeping old entries would suppress new mail.
+    const sameSpace = uidValidity === undefined || file.uidValidity === undefined || file.uidValidity === uidValidity;
+    const uids = sameSpace ? file.uids : [];
+    // Never erase a validity we already know: an ack from a caller that could not report one
+    // must not blind the next comparison.
+    // The caller's space wins, because claim/ack refuse a record from another space: an ack
+    // that reaches here is for the live numbering, and the file must adopt it. (Preferring the
+    // file's space made it write-once - after the first renumbering every later ack was
+    // journaled under the dead numbering and dedupe was permanently inert.)
+    const known = uidValidity ?? file.uidValidity;
+    const next = { uids, ...(known === undefined ? {} : { uidValidity: known }) };
+    if (uids.includes(uid)) {
+        save(env, next);
+        return false;
+    }
+    uids.push(uid);
+    save(env, next);
+    return true;
+}
+export function journalSize(env) {
+    return loadFile(env).uids.length;
+}
+/** Test helper: forget every ack. */
+export function resetJournal(env) {
+    save(env, { uids: [] });
+}

package/dist/store/mode-store.js

@@ -0,0 +1,47 @@
+// Global email mode: "am I away from the keyboard?"
+//
+// One human, one mailbox, one switch. It is deliberately global rather than
+// per-session: you are either at the desk or you are not, and pretending
+// otherwise makes the agent guess.
+//
+// Persisted so a daemon restart cannot silently re-enable emailing, and default
+// OFF so installing the package never starts mailing you unprompted.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { statePath } from "./paths.js";
+export const DEFAULT_MODE = "off";
+function path(env) {
+    return statePath(env, "mode.json");
+}
+export function isMode(value) {
+    return value === "on" || value === "off";
+}
+/** Current mode; a missing or corrupt file means off. */
+export function readMode(env = process.env) {
+    const p = path(env);
+    try {
+        if (!existsSync(p))
+            return DEFAULT_MODE;
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        return isMode(parsed?.mode) ? parsed.mode : DEFAULT_MODE;
+    }
+    catch {
+        return DEFAULT_MODE;
+    }
+}
+/** Persist the mode. Returns the value actually stored. */
+export function writeMode(env, mode, now = Date.now()) {
+    const p = path(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ mode, updatedAt: now }), { mode: 0o600 });
+    renameSync(tmp, p);
+    return mode;
+}
+/**
+ * The single rule for whether the daemon may touch the mailbox. `/mailbridge off` is documented as
+ * closing the control channel, so this is the gate that makes that true.
+ */
+export function scanningEnabled(mode) {
+    return mode === "on";
+}

package/dist/store/oauth-store.js

@@ -0,0 +1,50 @@
+// Persistence for OAuth tokens.
+//
+// Only the refresh token is precious: access tokens are short-lived and cheap to
+// re-mint. The file is 0600 inside the 0700 state dir, and it is never logged.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { statePath } from "./paths.js";
+function path(env) {
+    return statePath(env, "oauth.json");
+}
+/** File-backed token store. Atomic replace, mode 0600. */
+export function fileTokenStore(env = process.env) {
+    const file = path(env);
+    return {
+        read() {
+            try {
+                if (!existsSync(file))
+                    return undefined;
+                const parsed = JSON.parse(readFileSync(file, "utf8"));
+                if (typeof parsed?.refreshToken !== "string" && typeof parsed?.accessToken !== "string")
+                    return undefined;
+                return parsed;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write(tokens) {
+            mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+            const tmp = `${file}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(tokens), { mode: 0o600 });
+            renameSync(tmp, file);
+        },
+    };
+}
+/** In-memory store for tests and for `--auth` dry runs. */
+export function memoryTokenStore(initial) {
+    let tokens = initial;
+    return {
+        read: () => tokens,
+        write(next) {
+            tokens = next;
+        },
+        value: () => tokens,
+    };
+}
+/** True when a refresh token is on disk, i.e. login already happened. */
+export function hasStoredRefreshToken(env = process.env) {
+    return Boolean(fileTokenStore(env).read()?.refreshToken);
+}

package/dist/store/paths.js

@@ -0,0 +1,33 @@
+// State + config locations. Everything the package writes lives under one
+// directory so a user can inspect or delete it in one step.
+//
+//   $XDG_STATE_HOME/pi-mailbridge/   (default ~/.local/state/pi-mailbridge)
+//     secret.key        shared HMAC + daemon bearer key, mode 0600
+//     uid-cursor.json   IMAP UID cursor + the mailbox UIDVALIDITY it belongs to
+//     pending.json      durable pending deliveries
+//     journal.json      UIDs already acked (replay protection)
+//     mode.json         global on/off
+//     routes.json       short routing ids (TTL-bounded)
+//     threads.json      outbound Message-IDs: threading + reply chain
+//     oauth.json        refresh token, 0600
+//
+// Config is read from, in order, each deep-merged over the previous:
+//   1. built-in defaults
+//   2. $XDG_CONFIG_HOME/pi-mailbridge/config.json
+//   3. PI_MAILBRIDGE_* environment variables
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function stateDir(env = process.env) {
+    const base = env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+    return join(base, "pi-mailbridge");
+}
+export function configDir(env = process.env) {
+    const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "pi-mailbridge");
+}
+export function statePath(env, ...parts) {
+    return join(stateDir(env), ...parts);
+}
+export function configPath(env = process.env) {
+    return join(configDir(env), "config.json");
+}

package/dist/store/pending-store.js

@@ -0,0 +1,212 @@
+// Durable pending deliveries.
+//
+// Written by the daemon immediately after a message is parsed and authorized —
+// *before* any session is told about it. That ordering is the whole point: a
+// crash after this write still leaves the reply available for redelivery, while
+// the mail stays unseen on the server.
+//
+// Single-writer model: only the daemon mutates this file, so no inter-process
+// lock is required. Atomic rename protects against torn reads.
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { statePath } from "./paths.js";
+import { StateVersionError, checkStateVersion, stamp } from "./schema.js";
+/** Bound the store so a stuck mailbox cannot grow it without limit. */
+export const PENDING_CAP = 1_000;
+/** A claim older than this is considered abandoned and may be re-taken. */
+export const CLAIM_TTL_MS = 120_000;
+function path(env) {
+    return statePath(env, "pending.json");
+}
+/**
+ * Parsed-file cache, keyed by the file's mtime+size.
+ *
+ * /health is unauthenticated and reads the queue length on every request; every poll tick
+ * and every claim/ack re-reads it too. Without a cache, one large queued reply is re-parsed
+ * (and re-serialised to JSON) many times a minute.
+ */
+let cached;
+function load(env) {
+    const p = path(env);
+    try {
+        if (!existsSync(p))
+            return [];
+        const stat = statSync(p);
+        const stamp = `${stat.mtimeMs}:${stat.size}`;
+        if (cached && cached.path === p && cached.stamp === stamp)
+            return cached.items;
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        // Refuses a file from a newer schema rather than filtering records it cannot read.
+        checkStateVersion("pending.json", parsed);
+        if (!Array.isArray(parsed?.items))
+            return [];
+        const items = parsed.items.filter((r) => typeof r?.uid === "number" && typeof r?.sessionId === "string" && typeof r?.body === "string");
+        cached = { path: p, stamp, items };
+        return items;
+    }
+    catch (error) {
+        if (error instanceof StateVersionError)
+            throw error;
+        // Unparsable is not empty. Returning [] lets the next addPending rewrite the file with a
+        // single record, discarding a queue whose replies the cursor has already passed. Keep the
+        // bytes where a human can recover them and start clean.
+        try {
+            renameSync(p, `${p}.corrupt-${Date.now()}`);
+        }
+        catch {
+            /* if it cannot be moved, the caller still gets an empty queue rather than a crash */
+        }
+        return [];
+    }
+}
+function save(env, items) {
+    const p = path(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    const tmp = `${p}.${process.pid}.tmp`;
+    // Never trim here. These records were accepted and the cursor has already moved past
+    // them, so dropping one is silent, unrecoverable mail loss. The cap is enforced at
+    // insertion instead, where the caller can refuse and leave the cursor alone.
+    writeFileSync(tmp, JSON.stringify({ ...stamp(), items }), { mode: 0o600 });
+    renameSync(tmp, p);
+    // The process that wrote knows the truth; an mtime+size stamp can collide when two writes
+    // land in the same millisecond with the same length (measured on ext4).
+    try {
+        const stat = statSync(p);
+        cached = { path: p, stamp: `${stat.mtimeMs}:${stat.size}`, items };
+    }
+    catch {
+        cached = undefined;
+    }
+}
+export function listPending(env = process.env) {
+    return load(env);
+}
+/** Only the records this device scanned; absent device means "from before the field". */
+export function listPendingForDevice(env, device) {
+    return load(env).filter((r) => r.device === undefined || r.device === device);
+}
+export function listPendingForSession(env, sessionId) {
+    return load(env).filter((r) => r.sessionId === sessionId);
+}
+export function getPending(env, uid) {
+    return load(env).find((r) => r.uid === uid);
+}
+/**
+ * Add or replace the record for `uid`. Idempotent on replay.
+ *
+ * Refuses a NEW record once the store is full rather than making room by discarding an
+ * older one: every record here was already accepted, and the caller's cursor is about to
+ * move past it. Replacing an existing uid (replay) is always allowed.
+ */
+export function addPending(env, record) {
+    const existing = load(env);
+    const without = existing.filter((r) => r.uid !== record.uid);
+    if (without.length >= PENDING_CAP)
+        return { ok: false, reason: "full" };
+    without.push(record);
+    save(env, without);
+    return { ok: true, record };
+}
+/**
+ * Claim a delivery for `instanceId`.
+ *
+ * Succeeds when the record is unclaimed, already claimed by this same instance,
+ * or its claim has expired (abandoned instance).
+ */
+export function claimPending(env, uid, instanceId, now = Date.now(), uidValidity, liveValidity, device) {
+    const items = load(env);
+    const record = items.find((r) => r.uid === uid);
+    if (!record)
+        return { ok: false, reason: "not-found" };
+    // Defence in depth for a shared state directory: /pending already filters by device, but a
+    // caller that names a uid it should not have (an older client, or a direct POST) is refused.
+    if (record.device !== undefined && device !== undefined && record.device !== device) {
+        return { ok: false, reason: "foreign-device" };
+    }
+    // A caller holding a record from a previous UID numbering must not act on whatever now
+    // occupies that UID: after a renumbering it is a different message.
+    if (record.uidValidity !== undefined && uidValidity !== undefined && record.uidValidity !== uidValidity) {
+        return { ok: false, reason: "stale-space" };
+    }
+    // Also compare against the mailbox itself: a caller and a record can agree with each other
+    // while both belong to a numbering the mailbox has already left.
+    if (record.uidValidity !== undefined && liveValidity !== undefined && record.uidValidity !== liveValidity) {
+        return { ok: false, reason: "stale-space" };
+    }
+    if (record.claimedBy && record.claimedBy !== instanceId) {
+        const age = now - (record.claimedAt ?? 0);
+        if (age < CLAIM_TTL_MS)
+            return { ok: false, reason: "claimed-by-other" };
+    }
+    record.claimedBy = instanceId;
+    record.claimedAt = now;
+    save(env, items);
+    return { ok: true };
+}
+export function ackPending(env, uid, instanceId, uidValidity, liveValidity) {
+    const items = load(env);
+    const record = items.find((r) => r.uid === uid);
+    if (!record)
+        return { ok: false, reason: "not-found" };
+    // Same rule as claim: an ack from another UID space would journal a UID that now means
+    // something else.
+    if (record.uidValidity !== undefined && uidValidity !== undefined && record.uidValidity !== uidValidity) {
+        return { ok: false, reason: "stale-space" };
+    }
+    if (record.uidValidity !== undefined && liveValidity !== undefined && record.uidValidity !== liveValidity) {
+        return { ok: false, reason: "stale-space" };
+    }
+    if (record.claimedBy !== instanceId)
+        return { ok: false, reason: "not-claimed" };
+    save(env, items.filter((r) => r.uid !== uid));
+    return { ok: true, sessionId: record.sessionId, ...(record.uidValidity === undefined ? {} : { uidValidity: record.uidValidity }) };
+}
+/**
+ * Drop queued records that belong to a different UID numbering.
+ *
+ * A re-indexed mailbox renumbers from 1, so an old UID can collide with a new one and
+ * `addPending` would silently replace a queued reply. The dropped mail is *not* lost: it was
+ * never acked, so it is still unread in the mailbox, and the cursor reset that accompanies
+ * this re-reads it.
+ *
+ * @returns how many records were dropped.
+ */
+export function dropPendingFromOtherSpaces(env, uidValidity, options = {}) {
+    const items = load(env);
+    // On a detected renumbering, a record that carries no space cannot be shown to belong to the
+    // new numbering - and a live review caught one being claimed there and injecting a different
+    // message's body. Its mail is unread and the reset cursor re-reads it.
+    const keep = (r) => r.uidValidity === uidValidity || (r.uidValidity === undefined && !options.includeUnknown);
+    const kept = items.filter(keep);
+    const dropped = items.filter((r) => !keep(r));
+    if (dropped.length > 0)
+        save(env, kept);
+    // Returned, not just counted: the caller releases exactly these sessions' decision slots,
+    // and a second pass over the file could disagree with what was actually removed.
+    return dropped;
+}
+/** Records older than this, for sessions that are gone, are expired under queue pressure only
+ * (see `process.ts`): never on connect, where a `/mailbridge off` plus a holiday would delete replies. */
+export const PENDING_MAX_AGE_MS = 7 * 24 * 3600_000;
+/**
+ * Drop records nothing can deliver any more.
+ *
+ * A record whose session never comes back is refused by every runner (`foreign-session`) and
+ * removed by nothing else, so a handful of them can fill `PENDING_CAP` - and at the cap the
+ * scanner stops advancing the cursor, which stalls *all* inbound mail. Expiring them is a
+ * deliberate, bounded loss: their mail stays unread in the mailbox, but the cursor has moved
+ * past it, so it will not be re-read.
+ *
+ * @returns the dropped records, so the caller can release their decision slots.
+ */
+export function expirePending(env, maxAgeMs = PENDING_MAX_AGE_MS, now = Date.now()) {
+    const items = load(env);
+    const expired = items.filter((r) => now - r.receivedAt > maxAgeMs);
+    if (expired.length === 0)
+        return [];
+    save(env, items.filter((r) => now - r.receivedAt <= maxAgeMs));
+    return expired;
+}
+export function pendingSize(env) {
+    return load(env).length;
+}

package/dist/store/registry.js

@@ -0,0 +1,61 @@
+// One-outstanding-decision registry.
+//
+// Why this exists: `request_decision` emails the human and ends the turn. If the
+// agent calls it twice for the same session, the human gets two emails for one
+// decision and can only answer one of them. The registry reserves a slot per
+// session so the second call is refused before any mail is sent.
+//
+// Scope note: this is intentionally **in memory**, owned by the daemon. A daemon
+// restart drops reservations — that is acceptable, because a reply is keyed by
+// its own UID in the pending store, not by a reservation. A dropped reservation
+// can therefore never lose a reply; it can only allow a duplicate *question*.
+//
+// Bounds: entries expire by TTL and the map has a hard cap, because the
+// /register endpoint is reachable by any local session.
+export const REGISTRY_TTL_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_MAX_ENTRIES = 10_000;
+export function createRegistry(options = {}) {
+    const ttlMs = options.ttlMs ?? REGISTRY_TTL_MS;
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const now = options.now ?? (() => Date.now());
+    /** sessionId -> last refresh time */
+    const entries = new Map();
+    /** Lazy prune: a dead entry can never be served after its TTL. */
+    function prune() {
+        const cutoff = now() - ttlMs;
+        for (const [id, at] of entries) {
+            if (at < cutoff)
+                entries.delete(id);
+        }
+    }
+    return {
+        register(sessionId) {
+            prune();
+            const existing = entries.get(sessionId);
+            if (existing !== undefined) {
+                entries.set(sessionId, now()); // refresh TTL
+                return { alreadyPending: true, full: false };
+            }
+            if (entries.size >= maxEntries) {
+                return { alreadyPending: false, full: true };
+            }
+            entries.set(sessionId, now());
+            return { alreadyPending: false, full: false };
+        },
+        release(sessionId) {
+            entries.delete(sessionId);
+        },
+        has(sessionId) {
+            prune();
+            return entries.has(sessionId);
+        },
+        size() {
+            prune();
+            return entries.size;
+        },
+        list() {
+            prune();
+            return [...entries.keys()];
+        },
+    };
+}