@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/dist/core/settle.js

@@ -0,0 +1,122 @@
+// Settle notification: the email you get when the agent stops.
+//
+// Three rules earn this module its existence:
+//   1. It fires on `agent_settled` only. `agent_end` precedes retries,
+//      compaction and queued follow-ups, so mailing there would send you a
+//      "finished" message for work that is still running.
+//   2. It is debounced. Settle → you type again → settle would otherwise mail
+//      you a half-finished answer.
+//   3. An aborted settle (Escape) is not "finished" and is skipped by default.
+import { stampSubject } from "./token.js";
+export const REPLY_HINT = "Reply above this line to continue the session.";
+/**
+ * Subject: which session, on which device, with the routing id that makes the
+ * reply land back here. Both facts are in the subject because that is all a
+ * notification preview shows on a phone, tablet or another PC.
+ */
+export function buildSettleSubject(context, secret, tag, tokenTtlHours) {
+    const label = context.sessionName?.trim() || context.cwd.split("/").filter(Boolean).pop() || "session";
+    const device = context.device?.trim();
+    const where = device ? ` @ ${device}` : "";
+    const body = `pi: ${label}${where} is waiting for you`;
+    // A short local id keeps the subject readable; the signed token remains the
+    // fallback for callers that have no store to register against.
+    if (tag)
+        return `[pi:${tag}] ${body}`;
+    return stampSubject(context.sessionId, body, secret, {
+        ...(device ? { device } : {}),
+        ...(tokenTtlHours === undefined ? {} : { ttlHours: tokenTtlHours }),
+    });
+}
+/** Cap on the quoted agent text, so a long answer cannot become a 200-line email. */
+export const MAX_BODY_CHARS = 4_000;
+function quoteAnswer(text) {
+    const trimmed = text?.trim();
+    if (!trimmed)
+        return "(the agent produced no text this turn)";
+    if (trimmed.length <= MAX_BODY_CHARS)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_BODY_CHARS)}\n\n…truncated (${trimmed.length - MAX_BODY_CHARS} more characters)`;
+}
+/** Plain-text body. Deliberately boring: it must survive arbitrary mail clients. */
+export function buildSettleBody(context) {
+    const lines = [];
+    lines.push(quoteAnswer(context.lastAssistantText));
+    lines.push("");
+    lines.push("--");
+    if (context.device?.trim())
+        lines.push(`device: ${context.device.trim()}`);
+    // Only name the session when it has a name; otherwise this line repeated the id.
+    if (context.sessionName?.trim())
+        lines.push(`session: ${context.sessionName.trim()}`);
+    lines.push(`session id: ${context.sessionId}`);
+    lines.push(`project: ${context.cwd}`);
+    if (typeof context.turns === "number")
+        lines.push(`turns: ${context.turns}`);
+    lines.push("");
+    lines.push(REPLY_HINT);
+    return lines.join("\n");
+}
+export function createSettleNotifier(deps) {
+    let handle;
+    let pendingContext;
+    async function deliver(context) {
+        const secret = deps.secret();
+        try {
+            await deps.send({
+                to: "", // the daemon fills in mail.to
+                subject: buildSettleSubject(context, secret, deps.tagFor?.(context), deps.config.tokenTtlHours),
+                text: buildSettleBody(context),
+            });
+        }
+        catch (error) {
+            deps.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    function cancel() {
+        if (handle !== undefined) {
+            deps.timers.clearTimeout(handle);
+            handle = undefined;
+        }
+        pendingContext = undefined;
+    }
+    return {
+        settled(event) {
+            if (deps.mode() !== "on")
+                return "mode-off";
+            if (event?.aborted && !deps.config.notifyOnAborted)
+                return "aborted";
+            if (!deps.config.onSettled)
+                return "disabled";
+            const context = deps.context();
+            if (!context)
+                return "no-context";
+            // Debounce: a later settle replaces the earlier one entirely.
+            cancel();
+            pendingContext = context;
+            const delay = Math.max(0, deps.config.debounceMs);
+            handle = deps.timers.setTimeout(() => {
+                handle = undefined;
+                const pending = pendingContext;
+                pendingContext = undefined;
+                // The mode can change during the debounce (a `/mailbridge off` typed at t+4s, a
+                // timer firing at t+10s). Scheduling proved nothing about when it fires.
+                if (pending && deps.mode() === "on")
+                    void deliver(pending);
+            }, delay);
+            return "scheduled";
+        },
+        async flush() {
+            const context = pendingContext;
+            cancel();
+            // The same gate the debounce callback applies, for the same reason: the mode can have
+            // been turned off during the window, and a flush must not bypass that.
+            if (context && deps.mode() === "on")
+                await deliver(context);
+        },
+        isPending() {
+            return pendingContext !== undefined;
+        },
+        cancel,
+    };
+}

package/dist/core/setup.js

@@ -0,0 +1,100 @@
+// Setup: address in, runnable config out.
+//
+// Shared by `/mailbridge setup` (inside pi) and `--setup` (headless), so the two
+// entry points cannot drift. It writes the config file and reports what it did;
+// it never starts a process and never prompts.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { shortHostname } from "./config.js";
+import { buildSetupConfig, discoverDomain, domainOf } from "./discover.js";
+import { configPath } from "../store/paths.js";
+export async function runSetup(options) {
+    const env = options.env ?? process.env;
+    const steps = [];
+    const address = options.address.trim();
+    const to = (options.to ?? address).trim();
+    const domain = domainOf(address);
+    if (!domain)
+        return { ok: false, steps: [`not an email address: ${address}`] };
+    if (!domain.includes(".")) {
+        return {
+            ok: false,
+            steps: [`"${domain}" is not a domain — it has no dot`],
+            next: `addresses need a full domain — write something@${domain}.com`,
+        };
+    }
+    // The human's address is where every notification goes and the only sender the allowlist
+    // accepts. A typo here is a config that mails nowhere and rejects every reply, so check it
+    // rather than writing it.
+    if (!domainOf(to)) {
+        return { ok: false, steps: [`not an email address: ${to}`], next: "pass `to <your-address>`" };
+    }
+    const target = configPath(env);
+    // A device name is an identity, not a mail setting: `force` must not rename the machine,
+    // because records already scanned under the old name would never be offered again.
+    const previousDevice = (() => {
+        try {
+            const parsed = JSON.parse(readFileSync(target, "utf8"));
+            const name = parsed?.device?.name;
+            return typeof name === "string" && name.trim() ? name.trim() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (existsSync(target) && !options.force) {
+        return {
+            ok: false,
+            steps: [`${target} already exists`],
+            path: target,
+            next: "run `/mailbridge setup … force` to overwrite",
+        };
+    }
+    steps.push(`discovering ${domain}…`);
+    const discovered = await discoverDomain(domain, options.fetchImpl ? { fetchImpl: options.fetchImpl } : {});
+    if (!discovered) {
+        return {
+            ok: false,
+            steps: [...steps, `no published mail settings for ${domain}`],
+            next: "the domain is not in the autoconfig database; write config.json by hand (config.example.json)",
+        };
+    }
+    steps.push(`imap ${discovered.imap.host}:${discovered.imap.port} (${discovered.imap.secure ? "TLS" : "STARTTLS"})`);
+    steps.push(`smtp ${discovered.smtp.host}:${discovered.smtp.port} (${discovered.smtp.secure ? "TLS" : "STARTTLS"})`);
+    steps.push(`auth ${discovered.authType}${discovered.provider !== "other" ? ` (${discovered.provider})` : ""}`);
+    const built = buildSetupConfig(address, to, discovered);
+    const config = {
+        ...built,
+        device: { name: previousDevice ?? shortHostname() },
+        daemon: { host: "127.0.0.1", port: 4177 },
+        notify: { onSettled: true, debounceMs: 10_000, notifyOnAborted: false },
+        tuning: { idleRenewMs: 25 * 60 * 1000, backoffInitialMs: 1000, backoffMaxMs: 60_000 },
+    };
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    // Written atomically: an automatic reload can read this file at any moment, and a torn
+    // write parses as {} (readJson falls back to defaults), which would silently replace the
+    // user's config with an empty mailbox.
+    const tmp = `${target}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, target);
+    steps.push(`wrote ${target}`);
+    if (built.security.allowSelfReplies) {
+        steps.push(`one mailbox for both roles — replies from ${to} are accepted only when they are real replies`);
+        steps.push("if this mailbox has other addresses that reach it (a QQ number, a foxmail alias), add each " +
+            "one to security.allowFrom - the allowlist matches the exact address you reply from");
+        steps.push("if the mailbox already has mail you do not want the agent to read, run /mailbridge prime " +
+            "before your first /mailbridge on");
+        steps.push("DMARC checks are off for this shape: a message from your address to the same address is " +
+            "delivered by your own provider and may carry no Authentication-Results header, so requiring " +
+            "one rejects every reply. The sender allowlist and the self-echo guards still apply.");
+    }
+    return {
+        ok: true,
+        steps,
+        path: target,
+        discovered,
+        next: discovered.authType === "XOAUTH2"
+            ? "put your app client id in the oauth block, then `/mailbridge auth`"
+            : "put the account app password (QQ/163 call it 授权码) in the mail block, then `/mailbridge smoke`",
+    };
+}

package/dist/core/smoke.js

@@ -0,0 +1,164 @@
+// 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 { sendMail } from "./mailer.js";
+import { createImapflowFactory } from "../daemon/imapflow.js";
+import { messageIdFromHeaders, stampedIdFromHeaders } from "./sent-index.js";
+const defaultConnect = 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) => {
+            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 = [];
+            for (const uid of newest) {
+                const fetched = (await client.fetchOne(uid, { source: true }, { uid: true }));
+                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) {
+    return /authenticated but not connected|smtpclientauthentication is disabled|535 authentication unsuccessful/i.test(message);
+}
+export async function runSmoke(config, deps = {}) {
+    const steps = [];
+    const send = deps.send ?? sendMail;
+    /** The Message-ID we stamped, so the echo probe can look for it. */
+    let lastMessageId;
+    // --- 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.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;
+    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) => new Promise((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";
+            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",
+                        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", detail: "our marker header survives delivery" };
+                }
+                if (seen === "id") {
+                    return {
+                        ok: true,
+                        step: "echo",
+                        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",
+                    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.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/dist/core/status.js

@@ -0,0 +1,56 @@
+// 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.
+/**
+ * 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) {
+    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) => 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/dist/core/token-source.js

@@ -0,0 +1,27 @@
+// 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 { createCommandTokenProvider } from "./oauth.js";
+import { createDeviceCodeProvider } from "./oauth-device.js";
+import { createOpenidClient } from "./oauth-openid.js";
+import { fileTokenStore } from "../store/oauth-store.js";
+/**
+ * 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, env = process.env) {
+    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/dist/core/token.js

@@ -0,0 +1,196 @@
+// 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 const TOKEN_RE = /\[\s*pi:([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\s*\]/i;
+function mac(secret, payload, bytes) {
+    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) {
+    const hex = sessionId.replace(/-/g, "");
+    if (!/^[0-9a-fA-F]{32}$/.test(hex))
+        return undefined;
+    return Buffer.from(hex, "hex");
+}
+function bytesToUuid(bytes) {
+    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) {
+    return createHash("sha256").update(device.toLowerCase()).digest().subarray(0, 2);
+}
+const NO_DEVICE = Buffer.alloc(2);
+export function signToken(sessionId, secret, opts = {}) {
+    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 = { 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)}`;
+}
+function splitToken(token) {
+    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, expected) {
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function verifyToken(token, secret, now = Date.now(), device) {
+    const parts = splitToken(token);
+    if (!parts)
+        return { ok: false, reason: "malformed" };
+    const { payload, given } = parts;
+    let bytes;
+    try {
+        bytes = Buffer.from(payload, "base64url");
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    const fingerprintOf = (at) => 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;
+    try {
+        body = JSON.parse(bytes.toString("utf8"));
+    }
+    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, subject, secret, opts) {
+    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, secret, now, device) {
+    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, secret, now) {
+    return tokenFromSubject(subject, secret, now)?.sessionId;
+}
+/** Shared secret material. 32 bytes. */
+export function newSecret() {
+    return randomBytes(32);
+}