@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/src/core/attachments.ts

@@ -0,0 +1,129 @@
+// 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"] as const
+/** Text-like attachments we inline as text. */
+export const ALLOWED_TEXT_MIMES = ["text/plain", "text/markdown", "application/json"] as const
+
+export const MAX_ATTACHMENTS = 4
+export const MAX_TOTAL_BYTES = 1_000_000
+
+export type UserContent =
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string }
+
+/** What the MIME parser hands us. */
+export interface RawAttachment {
+	filename?: string
+	contentType: string
+	content: Buffer
+}
+
+/** What we store in the pending record (base64, so JSON keeps it). */
+export interface InboundAttachment {
+	name: string
+	mimeType: string
+	size: number
+	data: string
+}
+
+export interface DroppedAttachment {
+	name: string
+	reason: "mime-not-allowed" | "too-many" | "too-large" | "empty"
+}
+
+export interface SelectResult {
+	accepted: InboundAttachment[]
+	dropped: DroppedAttachment[]
+}
+
+function isImage(mime: string): boolean {
+	return (ALLOWED_IMAGE_MIMES as readonly string[]).includes(mime)
+}
+
+function isText(mime: string): boolean {
+	return (ALLOWED_TEXT_MIMES as readonly string[]).includes(mime)
+}
+
+/** Lowercase, strip parameters (`text/plain; charset=utf-8` → `text/plain`). */
+export function normalizeMime(contentType: string | undefined): string {
+	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: RawAttachment[],
+	limits: { maxCount?: number; maxTotalBytes?: number } = {},
+): SelectResult {
+	const maxCount = limits.maxCount ?? MAX_ATTACHMENTS
+	const maxTotalBytes = limits.maxTotalBytes ?? MAX_TOTAL_BYTES
+
+	const accepted: InboundAttachment[] = []
+	const dropped: DroppedAttachment[] = []
+	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: string, attachments: InboundAttachment[] = []): string | UserContent[] {
+	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: UserContent[] = 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/src/core/authz.ts

@@ -0,0 +1,87 @@
+// 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 type { ResolvedConfig } from "./config.ts"
+import { dmarcPasses, findTrustedAuthResults, isAutoGenerated, normalizeAddress, type HeaderLike } from "./reply-parse.ts"
+
+export type AuthzDenial =
+	| "no-from"
+	| "self"
+	| "self-echo"
+	| "no-reply-evidence"
+	| "auto-generated"
+	| "not-allowlisted"
+	| "allowlist-empty"
+	| "dmarc-missing"
+	| "dmarc-failed"
+
+export type AuthzResult =
+	| { ok: true; from: string }
+	| { ok: false; reason: AuthzDenial }
+
+export interface AuthzInput {
+	/** Raw `From:` header value, display name included. */
+	from: string | undefined
+	headers: HeaderLike
+}
+
+export function authorize(input: AuthzInput, config: ResolvedConfig): AuthzResult {
+	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): a is string => 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/src/core/commands.ts

@@ -0,0 +1,99 @@
+// `/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 type MailbridgeSubcommand =
+	| "on"
+	| "off"
+	| "status"
+	| "setup"
+	| "check"
+	| "auth"
+	| "smoke"
+	| "prime"
+	| "restart"
+	| "help"
+
+export interface ParsedCommand {
+	sub: MailbridgeSubcommand
+	/** Setup: the pi address. */
+	address?: string
+	/** Setup: where the human reads mail. */
+	to?: string
+	/** Setup: overwrite an existing config. */
+	force: boolean
+}
+
+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: readonly MailbridgeSubcommand[] = [
+	"on",
+	"off",
+	"status",
+	"setup",
+	"check",
+	"auth",
+	"smoke",
+	"prime",
+	"restart",
+	"help",
+]
+
+export function isSubcommand(value: string): value is MailbridgeSubcommand {
+	return (SUBCOMMANDS as readonly string[]).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: string): ParsedCommand {
+	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: ParsedCommand = { sub: first, force: false }
+	if (first !== "setup") return parsed
+
+	const rest = tokens.slice(1)
+	const addresses: string[] = []
+	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/src/core/config-freshness.ts

@@ -0,0 +1,33 @@
+// 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 interface Freshness {
+	/**
+	 * The mtime of the config file the daemon is running on (NOT the time it read it), or 0
+	 * when it loaded with no file, or null/undefined if it did not report one.
+	 */
+	configLoadedAt: number | null | undefined
+	/** The config file's mtime, or null when there is no file (built-in defaults). */
+	configMtimeMs: number | null | undefined
+}
+
+export function shouldReloadConfig({ configLoadedAt, configMtimeMs }: Freshness): boolean {
+	// 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
+}