@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/src/core/smoke.ts

@@ -0,0 +1,207 @@
+// Live connectivity probe, shared by `/mailbridge smoke` and the headless
+// `--smoke` entry point so the two can never drift.
+//
+// Deliberately does NOT touch the cursor, the journal or any pending record: a
+// smoke test must never disturb real deliveries.
+
+import type { ResolvedConfig } from "./config.ts"
+import { sendMail } from "./mailer.ts"
+import { createImapflowFactory } from "../daemon/imapflow.ts"
+import { messageIdFromHeaders, stampedIdFromHeaders } from "./sent-index.ts"
+
+export interface SmokeStep {
+	ok: boolean
+	/** What was attempted, e.g. "smtp". */
+	step: "smtp" | "imap" | "echo"
+	/** Human-readable outcome. */
+	detail: string
+	/** Hint shown when the failure looks like the personal-Outlook problem. */
+	hint?: string
+}
+
+export interface SmokeResult {
+	ok: boolean
+	steps: SmokeStep[]
+}
+
+export interface SmokeDeps {
+	getAccessToken?: () => Promise<string>
+	/** Injected for tests. */
+	send?: typeof sendMail
+	connect?: (config: ResolvedConfig, getAccessToken?: () => Promise<string>) => Promise<{
+		count(): Promise<number>
+		/** Raw source of the messages seen since `sinceMs`, for the echo probe. */
+		recentSources?(sinceMs: number): Promise<Buffer[]>
+		close(): Promise<void>
+	}>
+	/** Retry delays for the echo probe: the provider delivers the copy asynchronously. */
+	echoRetryDelaysMs?: readonly number[]
+	sleep?: (ms: number) => Promise<void>
+}
+
+const defaultConnect: NonNullable<SmokeDeps["connect"]> = async (config, getAccessToken) => {
+	const factory = createImapflowFactory({ getAccessToken })
+	const client = await factory(config, { idleRenewMs: config.tuning.idleRenewMs })
+	await client.connect()
+	await client.mailboxOpen(config.mail.imap.folder || "INBOX")
+	return {
+		count: async () => (await client.search({ uid: "1:*" }, { uid: true })).length,
+		recentSources: async (sinceMs: number) => {
+			const uids = await client.search({ since: new Date(sinceMs) }, { uid: true })
+			const newest = uids.slice().sort((a, b) => b - a).slice(0, 20)
+			const sources: Buffer[] = []
+			for (const uid of newest) {
+				const fetched = (await client.fetchOne(uid, { source: true }, { uid: true })) as
+					| { source?: Buffer }
+					| false
+					| undefined
+				if (fetched && fetched.source) sources.push(fetched.source)
+			}
+			return sources
+		},
+		close: async () => {
+			try {
+				await client.logout()
+			} catch {
+				/* already gone */
+			}
+		},
+	}
+}
+
+/** The personal-Outlook failure modes, which mean "use Graph", not "retry". */
+export function looksLikeOutlookRefusal(message: string): boolean {
+	return /authenticated but not connected|smtpclientauthentication is disabled|535 authentication unsuccessful/i.test(message)
+}
+
+export async function runSmoke(config: ResolvedConfig, deps: SmokeDeps = {}): Promise<SmokeResult> {
+	const steps: SmokeStep[] = []
+	const send = deps.send ?? sendMail
+	/** The Message-ID we stamped, so the echo probe can look for it. */
+	let lastMessageId: string | undefined
+
+	// --- SMTP ---
+	try {
+		const stamp = new Date().toISOString()
+		const sent = await send(
+			config,
+			{
+				to: config.mail.to,
+				subject: `pi-mailbridge smoke test ${stamp}`,
+				text: `This is a smoke test from ${config.device.name}.\n\nIf you can read this, SMTP works.\n`,
+			},
+			{ getAccessToken: deps.getAccessToken },
+		)
+		lastMessageId = sent.messageId
+		steps.push({
+			ok: true,
+			step: "smtp",
+			detail: `sent to ${config.mail.to}${sent.messageId ? ` (${sent.messageId})` : ""}`,
+		})
+	} catch (error) {
+		const detail = (error as Error).message
+		steps.push({
+			ok: false,
+			step: "smtp",
+			detail,
+			...(looksLikeOutlookRefusal(detail) ? { hint: "the account refuses SMTP AUTH; the Graph transport is the fix — see docs/OAUTH.md" } : {}),
+		})
+		return { ok: false, steps }
+	}
+
+	// --- IMAP ---
+	const folder = config.mail.imap.folder || "INBOX"
+	let connection:
+		| { count(): Promise<number>; recentSources?(sinceMs: number): Promise<Buffer[]>; close(): Promise<void> }
+		| undefined
+	try {
+		connection = await (deps.connect ?? defaultConnect)(config, deps.getAccessToken)
+		const count = await connection.count()
+		steps.push({ ok: true, step: "imap", detail: `${count} message(s) visible in ${folder}` })
+
+		// --- echo probe ---
+		//
+		// Only meaningful in the single-mailbox layout: there the notification is delivered into
+		// the folder we watch, so we can see what the provider did to our headers. In layout A it
+		// goes to the human's mailbox and anything found here is unrelated.
+		//
+		// The copy arrives asynchronously (QQ: 20-30 s) and is identified by the
+		// `X-Pi-Mailbridge-Id` we stamped — reading "the newest message" once produced a false
+		// alarm on a live account.
+		const sameMailbox =
+			Boolean(config.mail.to) &&
+			config.mail.to.trim().toLowerCase() === (config.mail.imap.user ?? "").trim().toLowerCase()
+		if (sameMailbox && lastMessageId && connection.recentSources) {
+			const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+			const delays = deps.echoRetryDelaysMs ?? [2_000, 5_000, 15_000, 30_000]
+			const wanted = lastMessageId.replace(/[<>]/g, "")
+			const since = Date.now() - 15 * 60_000
+			let seen: "none" | "marker" | "id" | "rewritten" = "none"
+			for (const delay of delays) {
+				await sleep(delay)
+				for (const source of await connection.recentSources(since)) {
+					const head = (source.toString("utf8").split(/\r?\n\r?\n/)[0] ?? "").replace(/\r?\n[ \t]+/g, " ")
+					// The stamp is how we find the copy, but a provider can strip it while leaving
+					// our marker. Treat that copy as ours too, or the probe reports "did not come
+					// back" for a notification the scanner would recognise perfectly well.
+					const stamped = stampedIdFromHeaders(head)
+					const marked = /^x-pi-mailbridge:\s*notification/im.test(head)
+					if (stamped !== wanted && !(marked && stamped === undefined)) continue
+					// Classify on what the scanner actually uses: the marker, then our
+					// Message-ID. Claiming the Message-ID survived without checking it was the
+					// bug the live account exposed.
+					if (/^x-pi-mailbridge:\s*notification/im.test(head)) seen = "marker"
+					else if (messageIdFromHeaders(head) === wanted) seen = "id"
+					else seen = "rewritten"
+					break
+				}
+				if (seen !== "none") break
+			}
+			steps.push(
+				(() => {
+					if (seen === "none") {
+						return {
+							ok: false,
+							step: "echo" as const,
+							detail:
+								"our notification did not come back to this folder — single-mailbox mode relies on it returning with a header it can recognise",
+						}
+					}
+					if (seen === "marker") {
+						return { ok: true, step: "echo" as const, detail: "our marker header survives delivery" }
+					}
+					if (seen === "id") {
+						return {
+							ok: true,
+							step: "echo" as const,
+							detail: "marker header was stripped, but our Message-ID survived — the guard still holds",
+						}
+					}
+					// The provider rewrote both. Whether that is safe depends entirely on the
+					// sent-copy read-back, which is what then records the delivered id.
+					const covered = Boolean(config.mail.imap.sentFolder)
+					return {
+						ok: covered,
+						step: "echo" as const,
+						detail: covered
+							? "the provider rewrote both our headers; the sentFolder read-back records the delivered id, so the registry still catches our own mail"
+							: "the provider rewrote both our headers and mail.imap.sentFolder is not set — our own mail is not recognisable; set it",
+					}
+				})(),
+			)
+		}
+
+	} catch (error) {
+		const detail = (error as Error).message
+		steps.push({
+			ok: false,
+			step: "imap",
+			detail,
+			...(looksLikeOutlookRefusal(detail) ? { hint: "the account refuses IMAP for this token; the Graph transport is the fix — see docs/OAUTH.md" } : {}),
+		})
+	} finally {
+		await connection?.close()
+	}
+
+	return { ok: steps.every((s) => s.ok), steps }
+}

package/src/core/status.ts

@@ -0,0 +1,75 @@
+// Turning a scan summary into the lines `/mailbridge status` shows.
+//
+// Pure on purpose: this is the answer to "why did my reply not arrive", and it lived inline
+// in the extension where no test could reach it - which is how an unconditional "queue full"
+// line shipped in its first version.
+
+export interface ScanSummary {
+	/** When the last scan that saw mail ran; absent until one has. */
+	at?: number
+	/** When the daemon last *checked*, which is later than `at` on a quiet mailbox. */
+	checkedAt?: number
+	examined?: number
+	persisted?: number
+	rejected?: number
+	reasons?: Record<string, number>
+}
+
+/**
+ * Counter keys that are not refusals.
+ *
+ * `routed` / `threaded` / `journaled` / `vanished` are successful paths. `route-miss` is a
+ * miss on the subject id that still routed by token or chain. `attachment-*` drops one file
+ * but keeps the reply.
+ */
+const HANDLED = new Set([
+	"routed",
+	"threaded",
+	"journaled",
+	"vanished",
+	"route-miss",
+	// In single-mailbox mode our own notifications come back on every send. Rejecting them is
+	// the system working, so counting them as rejections made a healthy install look broken.
+	"self-echo",
+])
+
+/** Deferred, not dropped: the queue was full and the same UID is retried. */
+const DEFERRED = new Set(["pending-full"])
+
+export function formatScan(summary: ScanSummary | null | undefined): string[] {
+	if (!summary) return ["last scan: (never — is the daemon running?)"]
+	if (summary.at === undefined) {
+		// No scan has seen mail yet. Say when we last looked: otherwise a healthy quiet
+		// mailbox is indistinguishable from a dead poll loop.
+		const checked = summary.checkedAt ? new Date(summary.checkedAt).toLocaleTimeString() : "unknown"
+		return [`no mail yet — last checked ${checked}`]
+	}
+
+	const entries = Object.entries(summary.reasons ?? {}).filter(([, n]) => Number(n) > 0)
+	const list = (pick: (reason: string) => boolean): string =>
+		entries
+			.filter(([reason]) => pick(reason))
+			.map(([reason, n]) => `${reason} ${n}`)
+			.join(", ")
+
+	const refused = list((r) => !HANDLED.has(r) && !DEFERRED.has(r) && !r.startsWith("attachment-"))
+	const handled = list((r) => HANDLED.has(r))
+	const dropped = list((r) => r.startsWith("attachment-"))
+	const deferred = entries.some(([reason]) => DEFERRED.has(reason))
+
+	// Freshness stays visible after the first message: "last scan with mail: 10:00" alone cannot
+	// tell a live poll loop from one that died at 10:05.
+	const checked =
+		summary.checkedAt && summary.checkedAt - summary.at > 60_000
+			? ` (last checked ${new Date(summary.checkedAt).toLocaleTimeString()})`
+			: ""
+
+	return [
+		`last scan with mail: ${new Date(summary.at).toLocaleTimeString()}${checked} — examined ${summary.examined}, kept ${summary.persisted}, rejected ${summary.rejected}`,
+		`rejections: ${refused || "none"}`,
+		...(handled ? [`handled: ${handled}`] : []),
+		...(dropped ? [`attachments dropped: ${dropped}`] : []),
+		// Conditional, and it says what the reader should do about it.
+		...(deferred ? ["queue full: replies are deferred, not dropped — start a session so they drain"] : []),
+	]
+}

package/src/core/token-source.ts

@@ -0,0 +1,34 @@
+// Which token source this installation uses.
+//
+// Shared by the daemon and the in-pi commands so `/mailbridge smoke` and the
+// background daemon can never authenticate differently.
+
+import type { ResolvedConfig } from "./config.ts"
+import { createCommandTokenProvider, type TokenProvider } from "./oauth.ts"
+import { createDeviceCodeProvider } from "./oauth-device.ts"
+import { createOpenidClient } from "./oauth-openid.ts"
+import { fileTokenStore } from "../store/oauth-store.ts"
+
+/**
+ * Precedence: built-in device-code OAuth2 (self-refreshing) -> a configured
+ * command -> none (the account uses LOGIN).
+ * Returning undefined is not an error: it means XOAUTH2 is not in play.
+ */
+export async function buildTokenProvider(
+	config: ResolvedConfig,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<TokenProvider | undefined> {
+	if (config.oauth?.issuer && config.oauth.clientId) {
+		const client = await createOpenidClient(config.oauth)
+		return createDeviceCodeProvider({ client, store: fileTokenStore(env) })
+	}
+
+	// An empty array is not nullish: the shipped example has `mail.smtp.tokenCommand: []`, so
+	// `??` picked the empty SMTP list and ignored a perfectly good IMAP command - XOAUTH2 then
+	// failed at connect time while `--check` said the config was fine.
+	const smtp = config.mail.smtp.tokenCommand ?? []
+	const command = smtp.length > 0 ? smtp : (config.mail.imap.tokenCommand ?? [])
+	if (command.length > 0) return createCommandTokenProvider({ command })
+
+	return undefined
+}

package/src/core/token.ts

@@ -0,0 +1,240 @@
+// HMAC-signed routing tokens.
+//
+// A signed token is the fallback routing form: it is minted when no local route id is
+// available (see store/routes.ts), and lifted back out of replies. It answers exactly one question: "which session did this mail come from?"
+// It is ROUTING, not AUTHORIZATION — see docs/SECURITY.md §2.2.
+//
+// Two wire formats, because subjects are user-visible and the first one was ugly:
+//
+//   v2 (current)  [pi:<payload>.<mac>]
+//     payload = base64url( [0x02][16 session uuid][3 expiry minutes][2 device hash] )
+//     mac     = base64url(HMAC-SHA256(secret, payload)) truncated to 6 bytes
+//     → 30 + 1 + 8 = 39 characters, so a whole subject stays under ~90
+//
+//   v2-legacy (21-byte payload, minted before expiry went minute-granular)
+//     payload = base64url( [0x02][16 session uuid][2 expiry days][2 device hash] )
+//     → 28 + 1 + 8 = 37 characters. Still verified: a notification sent minutes before
+//       an upgrade keeps working.
+//
+//   v1 (legacy)   base64url(JSON {s,e,d}) + '.' + 16-byte mac
+//     → ~130 characters. Still verified, so tokens already in flight keep working.
+//
+// A non-UUID session id (tests, synthetic sessions) has no compact form, so those
+// keep using v1.
+
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto"
+
+/** MAC length for v2. 48 bits is ample for an online-verifiable routing token. */
+const MAC_BYTES_V2 = 6
+/** MAC length for v1, kept for compatibility with tokens already sent. */
+const MAC_BYTES_V1 = 16
+/** Tokens older than this are refused even when the MAC is valid. */
+export const DEFAULT_TOKEN_TTL_HOURS = 30 * 24
+
+const V2 = 0x02
+/**
+ * [version][16 session][3 expiry][2 device]
+ *
+ * Expiry is minutes since the epoch: three bytes covers ~31 years, and a day of
+ * granularity (two bytes) let a token expire up to 24 h earlier than configured.
+ */
+const V2_PAYLOAD_BYTES = 1 + 16 + 3 + 2
+/**
+ * Expiry is minutes since 2020, not since 1970: three bytes reaches ~2052 from here, where
+ * minutes since 1970 topped out in 2001 and silently clamped every token to "expired".
+ */
+const MINUTE_EPOCH = Date.UTC(2020, 0, 1)
+
+export interface TokenBody {
+	/** session id */
+	s: string
+	/** expiry, epoch ms */
+	e: number
+	/** minting device, when known */
+	d?: string
+}
+
+export const TOKEN_RE = /\[\s*pi:([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\s*\]/i
+
+function mac(secret: Buffer, payload: string, bytes: number): string {
+	return createHmac("sha256", secret).update(payload).digest().subarray(0, bytes).toString("base64url")
+}
+
+/** 32 hex characters (with or without dashes) → 16 bytes, else undefined. */
+function uuidToBytes(sessionId: string): Buffer | undefined {
+	const hex = sessionId.replace(/-/g, "")
+	if (!/^[0-9a-fA-F]{32}$/.test(hex)) return undefined
+	return Buffer.from(hex, "hex")
+}
+
+function bytesToUuid(bytes: Buffer): string {
+	const hex = bytes.toString("hex")
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+/**
+ * Stable 2-byte fingerprint of a device name; enough to route, not to identify.
+ * All-zero means "no device claim", which must not read as a mismatch.
+ */
+function deviceHash(device: string): Buffer {
+	return createHash("sha256").update(device.toLowerCase()).digest().subarray(0, 2)
+}
+
+const NO_DEVICE = Buffer.alloc(2)
+
+export interface SignOptions {
+	ttlHours?: number
+	now?: number
+	device?: string
+}
+
+export function signToken(sessionId: string, secret: Buffer, opts: SignOptions = {}): string {
+	const now = opts.now ?? Date.now()
+	const expiresAt = now + (opts.ttlHours ?? DEFAULT_TOKEN_TTL_HOURS) * 3600_000
+
+	const compactSession = uuidToBytes(sessionId)
+	if (compactSession) {
+		const payload = Buffer.alloc(V2_PAYLOAD_BYTES)
+		payload[0] = V2
+		compactSession.copy(payload, 1)
+		const minutes = Math.floor((expiresAt - MINUTE_EPOCH) / 60_000)
+		payload.writeUIntBE(Math.max(0, Math.min(0xffffff, minutes)), 17, 3)
+		;(opts.device ? deviceHash(opts.device) : NO_DEVICE).copy(payload, 20)
+		const encoded = payload.toString("base64url")
+		return `${encoded}.${mac(secret, encoded, MAC_BYTES_V2)}`
+	}
+
+	// v1: no compact form for an arbitrary session id.
+	const body: TokenBody = { s: sessionId, e: expiresAt, ...(opts.device ? { d: opts.device } : {}) }
+	const payload = Buffer.from(JSON.stringify(body)).toString("base64url")
+	return `${payload}.${mac(secret, payload, MAC_BYTES_V1)}`
+}
+
+export type VerifyResult =
+	| {
+			ok: true
+			sessionId: string
+			/** Full device name, when the format carries one (v1). */
+			device?: string
+			/**
+			 * True/false when the caller supplied its own device to compare against;
+			 * undefined when the token or the caller carries no device, meaning "no
+			 * opinion" rather than "mismatch".
+			 */
+			deviceMatches?: boolean
+	  }
+	| { ok: false; reason: "malformed" | "bad-mac" | "expired" }
+
+function splitToken(token: string): { payload: string; given: string } | undefined {
+	const dot = token.lastIndexOf(".")
+	if (dot <= 0 || dot === token.length - 1) return undefined
+	return { payload: token.slice(0, dot), given: token.slice(dot + 1) }
+}
+
+function macMatches(given: string, expected: string): boolean {
+	const a = Buffer.from(given)
+	const b = Buffer.from(expected)
+	return a.length === b.length && timingSafeEqual(a, b)
+}
+
+export function verifyToken(token: string, secret: Buffer, now: number = Date.now(), device?: string): VerifyResult {
+	const parts = splitToken(token)
+	if (!parts) return { ok: false, reason: "malformed" }
+	const { payload, given } = parts
+
+	let bytes: Buffer
+	try {
+		bytes = Buffer.from(payload, "base64url")
+	} catch {
+		return { ok: false, reason: "malformed" }
+	}
+
+	const fingerprintOf = (at: number): Buffer => bytes.subarray(at, at + 2)
+
+	// --- v2: compact binary payload ---
+	if (bytes.length === V2_PAYLOAD_BYTES && bytes[0] === V2) {
+		if (!macMatches(given, mac(secret, payload, MAC_BYTES_V2))) return { ok: false, reason: "bad-mac" }
+		const expiresAt = MINUTE_EPOCH + bytes.readUIntBE(17, 3) * 60_000
+		if (expiresAt <= now) return { ok: false, reason: "expired" }
+		const fingerprint = fingerprintOf(20)
+		const claimsDevice = !fingerprint.equals(NO_DEVICE)
+		const deviceMatches = device && claimsDevice ? fingerprint.equals(deviceHash(device)) : undefined
+		return {
+			ok: true,
+			sessionId: bytesToUuid(bytes.subarray(1, 17)),
+			...(deviceMatches === undefined ? {} : { deviceMatches }),
+		}
+	}
+
+	// --- v2-legacy: same shape with two-byte day expiry, minted before the layout change ---
+	if (bytes.length === 21 && bytes[0] === V2) {
+		if (!macMatches(given, mac(secret, payload, MAC_BYTES_V2))) return { ok: false, reason: "bad-mac" }
+		const expiresAt = bytes.readUInt16BE(17) * 86_400_000
+		if (expiresAt <= now) return { ok: false, reason: "expired" }
+		const fingerprint = fingerprintOf(19)
+		const claimsDevice = !fingerprint.equals(NO_DEVICE)
+		const deviceMatches = device && claimsDevice ? fingerprint.equals(deviceHash(device)) : undefined
+		return {
+			ok: true,
+			sessionId: bytesToUuid(bytes.subarray(1, 17)),
+			...(deviceMatches === undefined ? {} : { deviceMatches }),
+		}
+	}
+
+	// --- v1: JSON payload ---
+	if (!macMatches(given, mac(secret, payload, MAC_BYTES_V1))) return { ok: false, reason: "bad-mac" }
+	let body: TokenBody
+	try {
+		body = JSON.parse(bytes.toString("utf8")) as TokenBody
+	} catch {
+		return { ok: false, reason: "malformed" }
+	}
+	if (typeof body?.s !== "string" || typeof body?.e !== "number") return { ok: false, reason: "malformed" }
+	if (body.e <= now) return { ok: false, reason: "expired" }
+	const claimedDevice = typeof body.d === "string" && body.d ? body.d : undefined
+	const deviceMatches = claimedDevice && device ? claimedDevice === device : undefined
+	return {
+		ok: true,
+		sessionId: body.s,
+		...(claimedDevice ? { device: claimedDevice } : {}),
+		...(deviceMatches === undefined ? {} : { deviceMatches }),
+	}
+}
+
+/** Prefix a human subject with the signed token. */
+export function stampSubject(sessionId: string, subject: string, secret: Buffer, opts?: SignOptions): string {
+	return `[pi:${signToken(sessionId, secret, opts)}] ${subject}`
+}
+
+/**
+ * Pull a verified routing token out of a subject line.
+ * Tolerates client prefixes (`Re:`, `RE:`, `AW:`, `Re[2]:`) because the token is
+ * matched anywhere in the subject, not anchored.
+ */
+export function tokenFromSubject(
+	subject: string | undefined | null,
+	secret: Buffer,
+	now?: number,
+	device?: string,
+): { sessionId: string; device?: string; deviceMatches?: boolean } | undefined {
+	if (!subject) return undefined
+	const m = TOKEN_RE.exec(subject)
+	if (!m?.[1]) return undefined
+	const result = verifyToken(m[1], secret, now, device)
+	if (!result.ok) return undefined
+	return {
+		sessionId: result.sessionId,
+		...(result.device ? { device: result.device } : {}),
+		...(result.deviceMatches === undefined ? {} : { deviceMatches: result.deviceMatches }),
+	}
+}
+
+/** Convenience wrapper for callers that only need the session id. */
+export function sessionIdFromSubject(subject: string | undefined | null, secret: Buffer, now?: number): string | undefined {
+	return tokenFromSubject(subject, secret, now)?.sessionId
+}
+
+/** Shared secret material. 32 bytes. */
+export function newSecret(): Buffer {
+	return randomBytes(32)
+}

package/src/core/version.ts

@@ -0,0 +1,45 @@
+// Which build is this? Diagnostic only - compatibility is `daemon/api.ts` (API_VERSION).
+//
+// The extension is loaded by pi and the daemon is a child process; after `pi update` the child
+// can still be executing the previous build. `/health` carries this string so a session can
+// notice and replace it, instead of talking to a daemon that mints routing ids it cannot resolve.
+
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const cache = new Map<string, string>()
+
+/**
+ * The version from the package.json that owns this module.
+ *
+ * `dist/daemon/main.js` and `src/daemon/main.ts` are both two levels below the package root, so
+ * one lookup works for a checkout and for an installed build. Unknown is reported as `"unknown"`
+ * rather than guessing: a caller that cannot compare should do nothing.
+ */
+export function packageVersion(moduleUrl: string | URL): string {
+	const key = String(moduleUrl)
+	const cached = cache.get(key)
+	if (cached !== undefined) return cached
+
+	// Walk up rather than assuming a depth: `src/extension.ts` is one level below the package
+	// root, `src/daemon/main.ts` and its compiled twin are two, and a test file is one.
+	let version = "unknown"
+	let dir = dirname(fileURLToPath(moduleUrl))
+	for (let depth = 0; depth < 5; depth += 1) {
+		try {
+			const parsed = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version?: unknown }
+			if (typeof parsed.version === "string" && parsed.version.length > 0) {
+				version = parsed.version
+				break
+			}
+		} catch {
+			/* keep walking */
+		}
+		const parent = dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	cache.set(key, version)
+	return version
+}

package/src/daemon/api.ts

@@ -0,0 +1,52 @@
+// The wire contract between the extension and the daemon.
+//
+// Two numbers, two clocks, deliberately separate (AGENTS.md "Compatibility"):
+//
+//   API_VERSION  - the HTTP surface: endpoints, payload fields, semantics. Bumped by any
+//                  breaking change to it; additive changes are gated by CAPABILITIES instead.
+//   package version (version.ts) - diagnostic only: which build someone is running.
+//
+// The daemon and the extension are spawned from one package, so a mismatch is recovered by
+// replacing the process rather than negotiating - but the *number* compared must be the
+// protocol, not the build, or a harmless patch bump would restart a working daemon.
+
+/** Bumped only for a breaking change to an endpoint, a payload shape, or a meaning. */
+export const API_VERSION = 1
+
+/**
+ * Additive features inside API_VERSION.
+ *
+ * A client must check for a capability before using anything newer than the base contract, and
+ * must not fake it when absent (no fallback paths: tell the user to update, or skip the feature).
+ */
+export const CAPABILITIES = ["health", "version", "pending", "claim", "ack", "send"] as const
+
+export type Capability = (typeof CAPABILITIES)[number]
+
+/** Every endpoint, in one place, so the schema test can freeze the surface. */
+export const ENDPOINTS = [
+	"GET /events",
+	"GET /health",
+	"GET /pending",
+	"GET /mode",
+	"POST /claim",
+	"POST /ack",
+	"POST /register",
+	"DELETE /register",
+	"POST /ping",
+	"POST /bye",
+	"POST /shutdown",
+	"POST /reload",
+	"POST /mode",
+	"POST /send",
+] as const
+
+/**
+ * Is a daemon speaking `theirs` usable by this build?
+ *
+ * Missing means "from before the field existed" - that is protocol 0, which this build cannot
+ * assume anything about.
+ */
+export function apiCompatible(mine: number, theirs: number | undefined): boolean {
+	return typeof theirs === "number" && theirs === mine
+}