dsh-email 0.17.2 → 0.18.0

package/lib/mail-client.d.ts

@@ -1,6 +1,6 @@
 import { ImapFlow } from 'imapflow';
 import type { ResolvedEmailConfig, ResolvedEmailSettings } from './config.js';
-import type { AddressEntry, EmailAttachmentMeta, EmailAttachmentResult, EmailFoldersResult, EmailListResult, EmailMarkAction, EmailMarkResult, EmailReadResult, EmailReplyMode, EmailReplyResult, EmailSearchResult, EmailSendResult, ListedMessage } from './types.js';
+import type { AddressEntry, EmailAttachmentMeta, EmailAttachmentResult, EmailFoldersResult, EmailListResult, EmailMarkAction, EmailMarkResult, EmailReadResult, EmailReplyMode, EmailReplyResult, EmailSearchResult, EmailSearchOptions, EmailSendResult, ListedMessage } from './types.js';
 export declare class MailError extends Error {
     constructor(message: string);
 }
@@ -191,7 +191,8 @@ export declare class EmailPool {
     }>;
     /** Fetch the envelopes for one uid batch: the rows email_watch will report. */
     fetchByUids(accountName: string | undefined, folder: string, uids: number[], signal?: AbortSignal): Promise<ListedMessage[]>;
-    search(accountName: string | undefined, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
+    search(accountName: string | undefined, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal, options?: EmailSearchOptions): Promise<EmailSearchResult>;
+    private searchHeaders;
     /**
      * Confirm server-side hits against the mailbox itself: fetch the envelopes
      * of the newest candidates — the same window the body-scan fallback looks at
@@ -212,7 +213,11 @@ export declare class EmailPool {
     sendPrepared(accountName: string, to: string, subject: string, text: string, cc: string, attachments: Array<{
         filename: string;
         content: Buffer;
-    }>, signal?: AbortSignal): Promise<EmailSendResult>;
+    }>, signal?: AbortSignal, reply?: {
+        uid: number;
+        folder: string;
+        uidValidity?: number;
+    }): Promise<EmailSendResult>;
     reply(accountName: string | undefined, folder: string, uid: number, mode: EmailReplyMode, text: string, forwardTo: string, cc: string | undefined, signal?: AbortSignal): Promise<EmailReplyResult>;
 }
 /** Stat every attachment path up front; total size must stay under the cap. */

package/lib/mail-client.js

@@ -805,7 +805,7 @@ export class EmailPool {
         const folderName = folder || cfg.inboxFolder;
         return this.withImap(name, folderName, (client) => this.fetchListed(client, uids, signal), true, signal);
     }
-    async search(accountName, query, folder, limit, offset, since, until, signal) {
+    async search(accountName, query, folder, limit, offset, since, until, signal, options = {}) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -822,39 +822,80 @@ export class EmailPool {
                 dateRange.since = since;
             if (until !== undefined)
                 dateRange.before = until;
-            const found = await Promise.all([
+            const found = await Promise.allSettled([
                 client.search({ subject: query, ...dateRange }, { uid: true }),
                 client.search({ from: query, ...dateRange }, { uid: true }),
                 client.search({ to: query, ...dateRange }, { uid: true }),
                 client.search({ cc: query, ...dateRange }, { uid: true }),
             ]);
             signal?.throwIfAborted();
-            const uids = [...new Set(found.flatMap(result => Array.isArray(result) ? result : []))].sort((a, b) => b - a);
-            if (uids.length > 0) {
+            const serverSearchFailed = found.some(result => result.status === 'rejected');
+            const uids = [...new Set(found.flatMap(result => result.status === 'fulfilled' && Array.isArray(result.value) ? result.value : []))].sort((a, b) => b - a);
+            if (uids.length > 0 && !serverSearchFailed && !options.headerScanOffset) {
                 // The sample has to cover the requested page (offset + limit) — the same
                 // window the fallback scan looks at — so one FETCH serves both the
                 // verification and the rows that are handed out.
-                const confirmed = await this.searchHits(client, uids, query, offset + limit, signal);
+                const confirmed = await this.searchHits(client, uids, query, offset + limit, signal, since, until);
                 if (confirmed.length > 0) {
                     // The server's list holds up, so its size is reported as the match
                     // count; only rows that were confirmed are ever handed out.
-                    return { account: name, query, count: uids.length, folder: folderName, offset, messages: confirmed.slice(offset, offset + limit) };
+                    return { account: name, query, count: uids.length, folder: folderName, offset, messages: confirmed.slice(offset, offset + limit), searchSource: 'server', serverMatchCount: uids.length };
                 }
             }
-            // Nothing believable came back (empty answer, or hits that did not
-            // survive verification): scan the newest messages locally instead.
-            if (this.settings.bodySearchFallback) {
-                const messages = await this.searchBodies(client, query, folderName, limit, offset, since, until, signal);
+            // Header search is cheap and independent of the much smaller body scan.
+            // Never turn a silent empty SEARCH into a claim about the whole mailbox.
+            const headers = await this.searchHeaders(client, query, options, since, until, signal);
+            const coverage = { headerScan: headers.scan, serverMatchCount: uids.length, serverSearchFailed };
+            if (headers.uids.length > 0) {
+                const messages = await this.fetchListed(client, headers.uids.slice(offset, offset + limit), signal);
+                return { account: name, query, count: headers.uids.length, folder: folderName, offset, messages,
+                    countKind: 'scanned', scannedLimit: headers.scan.scanned, searchSource: 'local-headers', ...coverage };
+            }
+            if (this.settings.bodySearchFallback && !options.headerScanOffset) {
+                const { messages, scanned } = await this.searchBodies(client, query, folderName, limit, offset, since, until, signal);
                 // 本地扫描不知道全文件夹有多少匹配，count 只是本页条数：用 countKind
                 // 让渲染说「本页 N 条（仅扫描最近 bodySearchLimit 封）」，不能说「共 N 条」。
                 return {
                     account: name, query, count: messages.length, folder: folderName, offset, messages,
                     countKind: 'scanned', scannedLimit: this.settings.bodySearchLimit,
+                    searchSource: 'local-body', bodyScan: { scanned, scanLimit: this.settings.bodySearchLimit }, ...coverage,
                 };
             }
-            return { account: name, query, count: 0, folder: folderName, offset, messages: [] };
+            return { account: name, query, count: 0, folder: folderName, offset, messages: [], countKind: 'scanned', scannedLimit: headers.scan.scanned, searchSource: 'local-headers', ...coverage };
         }, true, signal);
     }
+    async searchHeaders(client, query, options, since, until, signal) {
+        const integer = (value, fallback, max) => typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(max, Math.trunc(value))) : fallback;
+        const scanLimit = Math.max(1, integer(options.headerScanLimit, 5000, 20000));
+        const scanOffset = integer(options.headerScanOffset, 0, 1_000_000_000);
+        const mailboxTotal = client.mailbox === false ? 0 : client.mailbox.exists;
+        const end = Math.max(0, mailboxTotal - scanOffset), start = Math.max(1, end - scanLimit + 1);
+        const matches = new Set();
+        let scanned = 0;
+        for (let last = end; last >= start; last -= 500) {
+            signal?.throwIfAborted();
+            const first = Math.max(start, last - 499);
+            const rows = await client.fetchAll(first + ':' + last, { uid: true, envelope: true, internalDate: true });
+            signal?.throwIfAborted();
+            scanned += rows.length;
+            for (const message of rows) {
+                const date = message.internalDate ?? message.envelope?.date;
+                if (since !== undefined && (date === undefined || date < since))
+                    continue;
+                if (until !== undefined && (date === undefined || date >= until))
+                    continue;
+                const addresses = [message.envelope?.from, message.envelope?.to, message.envelope?.cc].map(flattenAddressText).join(' ');
+                if (messageMatchesQuery(message.envelope?.subject ?? '', addresses, '', query))
+                    matches.add(message.uid);
+            }
+        }
+        const currentTotal = client.mailbox === false ? 0 : client.mailbox.exists;
+        return { uids: [...matches].sort((a, b) => b - a), scan: {
+                mailboxTotal, scanned, matched: matches.size, scanOffset, scanLimit,
+                complete: scanOffset === 0 && start === 1 && scanned === mailboxTotal && currentTotal === mailboxTotal,
+                ...(start > 1 && end > 0 ? { nextScanOffset: scanOffset + (end - start + 1) } : {}),
+            } };
+    }
     /**
      * Confirm server-side hits against the mailbox itself: fetch the envelopes
      * of the newest candidates — the same window the body-scan fallback looks at
@@ -862,19 +903,24 @@ export class EmailPool {
      * the four fields the server was asked about. No body is downloaded here,
      * and uids the server made up simply return nothing.
      */
-    async searchHits(client, uids, query, need, signal) {
+    async searchHits(client, uids, query, need, signal, since, until) {
         const sample = uids.slice(0, Math.min(uids.length, Math.max(this.settings.bodySearchLimit, need)));
         signal?.throwIfAborted();
-        const fetched = await client.fetchAll(sample, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
+        const fetched = await client.fetchAll(sample, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true, internalDate: true }, { uid: true });
         signal?.throwIfAborted();
         return fetched
             .filter(message => {
+            const date = message.internalDate ?? message.envelope?.date;
+            if (since !== undefined && (date === undefined || date < since))
+                return false;
+            if (until !== undefined && (date === undefined || date >= until))
+                return false;
             const envelope = message.envelope;
             const addressText = [envelope?.from, envelope?.to, envelope?.cc].map(flattenAddressText).join(' ');
             return messageMatchesQuery(envelope?.subject ?? '', addressText, '', query);
         })
             .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
-            .sort((a, b) => b.uid - a.uid);
+            .sort((a, b) => Number(b.uid) - Number(a.uid));
     }
     /** Client-side scan of the tail of the mailbox, newest first. */
     async searchBodies(client, query, folder, limit, offset, since, until, signal) {
@@ -882,15 +928,17 @@ export class EmailPool {
         const mailbox = client.mailbox;
         const total = mailbox === false ? 0 : mailbox.exists;
         if (total === 0)
-            return [];
+            return { messages: [], scanned: 0 };
         const start = Math.max(1, total - this.settings.bodySearchLimit + 1);
         // 只取信封与 MIME 结构；正文在下面按 text/* 分段下载，附件不进正文匹配。
         const fetched = await client.fetchAll(start + ':*', { uid: true, envelope: true, flags: true, size: true, bodyStructure: true, internalDate: true });
         const out = [];
+        let scanned = 0;
         for (const message of [...fetched].reverse()) {
             signal?.throwIfAborted();
             if (out.length >= offset + limit)
                 break;
+            scanned++;
             const receivedAt = message.internalDate ?? message.envelope?.date;
             if (since !== undefined && (receivedAt === undefined || receivedAt < since))
                 continue;
@@ -925,7 +973,7 @@ export class EmailPool {
                 out.push(listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)));
             }
         }
-        return out.slice(offset, offset + limit);
+        return { messages: out.slice(offset, offset + limit), scanned };
     }
     async fetchListed(client, uids, signal) {
         signal?.throwIfAborted();
@@ -935,7 +983,7 @@ export class EmailPool {
         signal?.throwIfAborted();
         return fetched
             .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
-            .sort((a, b) => b.uid - a.uid);
+            .sort((a, b) => Number(b.uid) - Number(a.uid));
     }
     async read(accountName, uid, folder, signal) {
         const name = this.resolveName(accountName);
@@ -967,6 +1015,7 @@ export class EmailPool {
                             account: name,
                             uid,
                             folder: folderName,
+                            uidValidity: this.uidValidityOf(client),
                             date: envelopeDate instanceof Date ? envelopeDate.toISOString() : '',
                             from: flattenAddresses(message.envelope.from),
                             to: flattenAddresses(message.envelope.to),
@@ -992,7 +1041,7 @@ export class EmailPool {
             const body = await parseRawMessage(full.source, this.settings.maxBodyChars);
             signal?.throwIfAborted();
             this.rememberRead(name, folderName, this.uidValidityOf(client), uid, { attachments: body.attachments, parts: collectAttachmentParts(full.bodyStructure) });
-            return { account: name, uid, folder: folderName, ...body };
+            return { account: name, uid, folder: folderName, uidValidity: this.uidValidityOf(client), ...body };
         }, true, signal);
     }
     async mark(accountName, folder, uid, action, toFolder, signal) {
@@ -1143,11 +1192,25 @@ export class EmailPool {
         };
     }
     /** Send the attachment bytes the human reviewed, without re-reading mutable paths. */
-    async sendPrepared(accountName, to, subject, text, cc, attachments, signal) {
+    async sendPrepared(accountName, to, subject, text, cc, attachments, signal, reply) {
         const name = this.resolveName(accountName), cfg = this.account(name);
         if (attachments.length > 10 || attachments.reduce((sum, file) => sum + file.content.length, 0) > Math.min(this.settings.maxAttachmentBytes, 20 * 1024 * 1024))
             throw new MailError('草稿附件超过大小或数量上限');
-        const info = await this.sendMail(name, cfg, { from: senderOf(cfg), to, cc, subject, text, attachments, disableFileAccess: true, disableUrlAccess: true }, signal);
+        const thread = {};
+        if (reply)
+            await this.withImap(name, reply.folder || cfg.inboxFolder, async (client) => {
+                if (reply.uidValidity !== undefined && reply.uidValidity !== this.uidValidityOf(client))
+                    throw new MailError('原文件夹 UIDVALIDITY 已变化，无法关联旧回复草稿；请重新打开邮件准备回复');
+                const original = await client.fetchOne(reply.uid, { uid: true, headers: ['message-id', 'references'] }, { uid: true });
+                if (!original || !original.headers)
+                    throw new MailError('原邮件不存在或缺少线程头，请重新打开邮件');
+                const ids = extractMessageIds(original.headers);
+                if (!ids.messageId)
+                    throw new MailError('原邮件缺少 Message-ID，无法安全关联回复线程');
+                thread.inReplyTo = '<' + ids.messageId + '>';
+                thread.references = [...(ids.references ?? '').split(' ').filter(Boolean), ids.messageId].map(id => '<' + id + '>');
+            }, true, signal);
+        const info = await this.sendMail(name, cfg, { from: senderOf(cfg), to, cc, subject, text, attachments, ...thread, disableFileAccess: true, disableUrlAccess: true }, signal);
         return { account: name, messageId: String(info.messageId ?? ''), accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [], rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [], response: String(info.response ?? '') };
     }
     async reply(accountName, folder, uid, mode, text, forwardTo, cc, signal) {

package/lib/mail-service.d.ts

@@ -0,0 +1,50 @@
+import { EmailPool } from './mail-client.js';
+import { type MessageRef } from './agentmail.js';
+import type { ResolvedEmailSettings } from './config.js';
+import type { EmailFoldersResult, EmailReplyMode, EmailReplyResult, EmailMarkAction, EmailSearchOptions } from './types.js';
+import type { downloadPublicBytes } from './public-download.js';
+export interface ReplyReference {
+    uid: MessageRef;
+    folder: string;
+    uidValidity?: number;
+}
+export interface MailDependencies {
+    fetch?: typeof fetch;
+    download?: typeof downloadPublicBytes;
+}
+/** Route accounts independently. IMAP's numeric UIDs retain their original meaning. */
+export declare class EmailService {
+    private settings;
+    private imap;
+    private api;
+    constructor(settings: ResolvedEmailSettings, dependencies?: MailDependencies);
+    get withImap(): EmailPool['withImap'];
+    set withImap(run: EmailPool['withImap']);
+    private name;
+    private usesApi;
+    private number;
+    private folder;
+    list(account: string | undefined, folder: string, limit: number, offset: number, unread: boolean, since?: Date, until?: Date, signal?: AbortSignal): Promise<import("./types.js").EmailListResult>;
+    read(account: string | undefined, uid: MessageRef, folder: string, signal?: AbortSignal): Promise<import("./types.js").EmailReadResult>;
+    search(account: string | undefined, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal, options?: EmailSearchOptions): Promise<import("./types.js").EmailSearchResult>;
+    mark(account: string | undefined, folder: string, uid: MessageRef, action: EmailMarkAction, target?: string, signal?: AbortSignal): Promise<import("./types.js").EmailMarkResult>;
+    folders(account: string | undefined, subscribed: boolean, signal?: AbortSignal): Promise<EmailFoldersResult>;
+    downloadAttachment(account: string | undefined, folder: string, uid: MessageRef, index: number, workspace?: string, signal?: AbortSignal): Promise<import("./types.js").EmailAttachmentResult>;
+    send(account: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, paths: string[] | undefined, signal?: AbortSignal): Promise<import("./types.js").EmailSendResult>;
+    sendPrepared(account: string, to: string, subject: string, text: string, cc: string, attachments: Array<{
+        filename: string;
+        content: Buffer;
+    }>, signal?: AbortSignal, reply?: ReplyReference): Promise<import("./types.js").EmailSendResult>;
+    reply(account: string | undefined, folder: string, uid: MessageRef, mode: EmailReplyMode, text: string, to: string, cc: string | undefined, signal?: AbortSignal): Promise<EmailReplyResult>;
+    unseenUids(...args: Parameters<EmailPool['unseenUids']>): Promise<{
+        account: string;
+        folder: string;
+        uidValidity: number;
+        count: number;
+        uids: number[];
+    }>;
+    fetchByUids(...args: Parameters<EmailPool['fetchByUids']>): Promise<import("./types.js").ListedMessage[]>;
+    watchApi(account: string, folder: string, limit: number, scope: string, signal?: AbortSignal): Promise<import("./types.js").EmailWatchResult | undefined>;
+    startIdleSweep(): void;
+    dispose(): void;
+}

package/lib/mail-service.js

@@ -0,0 +1,128 @@
+import { EmailPool, buildReplyMessage, validateAttachmentPaths, } from './mail-client.js';
+import { AgentMailClient } from './agentmail.js';
+/** Route accounts independently. IMAP's numeric UIDs retain their original meaning. */
+export class EmailService {
+    settings;
+    imap;
+    api;
+    constructor(settings, dependencies = {}) {
+        this.settings = settings;
+        this.imap = new EmailPool(settings);
+        this.api = new AgentMailClient(settings, dependencies.fetch, dependencies.download);
+    }
+    get withImap() {
+        return this.imap.withImap.bind(this.imap);
+    }
+    set withImap(run) {
+        this.imap.withImap = run;
+    }
+    name(account) {
+        const name = account || this.settings.defaultAccount;
+        if (!this.settings.accounts.has(name))
+            throw new Error('未知邮件账号');
+        return name;
+    }
+    usesApi(account) {
+        return (this.settings.accounts.get(this.name(account))?.transport === 'agentmail');
+    }
+    number(uid) {
+        if (typeof uid !== 'number' || !Number.isSafeInteger(uid) || uid <= 0)
+            throw new Error('IMAP uid 必须是正整数');
+        return uid;
+    }
+    folder(account, folder) {
+        return folder || this.settings.accounts.get(this.name(account)).inboxFolder;
+    }
+    list(account, folder, limit, offset, unread, since, until, signal) {
+        return this.usesApi(account)
+            ? this.api.list(this.name(account), this.folder(account, folder), limit, offset, unread, since, until, signal)
+            : this.imap.list(account, folder, limit, offset, unread, since, until, signal);
+    }
+    read(account, uid, folder, signal) {
+        return this.usesApi(account)
+            ? this.api.read(this.name(account), uid, this.folder(account, folder), signal)
+            : this.imap.read(account, this.number(uid), folder, signal);
+    }
+    search(account, query, folder, limit, offset, since, until, signal, options = {}) {
+        if (this.usesApi(account) && options.headerScanOffset)
+            throw new Error('AgentMail 搜索使用 offset 分页，不使用 IMAP headerScanOffset');
+        return this.usesApi(account)
+            ? this.api.search(this.name(account), query, this.folder(account, folder), limit, offset, since, until, signal)
+            : this.imap.search(account, query, folder, limit, offset, since, until, signal, options);
+    }
+    mark(account, folder, uid, action, target, signal) {
+        return this.usesApi(account)
+            ? this.api.mark(this.name(account), this.folder(account, folder), uid, action, target, signal)
+            : this.imap.mark(account, folder, this.number(uid), action, target, signal);
+    }
+    async folders(account, subscribed, signal) {
+        if (!this.usesApi(account))
+            return this.imap.folders(account, subscribed, signal);
+        signal?.throwIfAborted();
+        return {
+            account: this.name(account),
+            folders: [
+                ['INBOX', '\\Inbox'],
+                ['Sent', '\\Sent'],
+                ['Starred', '\\Flagged'],
+                ['Archive', '\\Archive'],
+                ['All', '\\All'],
+            ].map(([path, specialUse]) => ({
+                name: path,
+                path,
+                specialUse,
+                subscribed: true,
+            })),
+        };
+    }
+    downloadAttachment(account, folder, uid, index, workspace, signal) {
+        return this.usesApi(account)
+            ? this.api.downloadAttachment(this.name(account), folder, uid, index, workspace, signal)
+            : this.imap.downloadAttachment(account, folder, this.number(uid), index, workspace, signal);
+    }
+    async send(account, to, subject, text, cc, paths, signal) {
+        if (!this.usesApi(account))
+            return this.imap.send(account, to, subject, text, cc, paths, signal);
+        await validateAttachmentPaths(paths ?? [], Math.min(this.settings.maxAttachmentBytes, 4 * 1024 * 1024), signal);
+        return this.api.sendPaths(this.name(account), to, subject, text ?? '', cc ?? '', paths ?? [], signal);
+    }
+    sendPrepared(account, to, subject, text, cc, attachments, signal, reply) {
+        return this.usesApi(account)
+            ? this.api.send(this.name(account), to, subject, text, cc, attachments, signal, reply)
+            : this.imap.sendPrepared(account, to, subject, text, cc, attachments, signal, reply ? { ...reply, uid: this.number(reply.uid) } : undefined);
+    }
+    async reply(account, folder, uid, mode, text, to, cc, signal) {
+        if (!this.usesApi(account))
+            return this.imap.reply(account, folder, this.number(uid), mode, text, to, cc, signal);
+        const name = this.name(account), cfg = this.settings.accounts.get(name), original = await this.api.read(name, uid, this.folder(account, folder), signal), built = buildReplyMessage({ ...original, messageId: String(uid), references: '' }, mode, cfg.user, text, to), sent = await this.api.send(name, built.to, built.subject, built.text, cc ?? '', [], signal, mode === 'forward' ? undefined : { uid, folder });
+        return {
+            ...sent,
+            mode,
+            originalUid: uid,
+            to: built.to.split(','),
+            subject: built.subject,
+        };
+    }
+    unseenUids(...args) {
+        if (this.usesApi(args[0]))
+            throw new Error('AgentMail 使用独立的新邮件游标');
+        return this.imap.unseenUids(...args);
+    }
+    fetchByUids(...args) {
+        if (this.usesApi(args[0]))
+            throw new Error('AgentMail 不支持 IMAP 数字 UID 批量读取，请使用列表中的 message_id');
+        return this.imap.fetchByUids(...args);
+    }
+    async watchApi(account, folder, limit, scope, signal) {
+        return this.usesApi(account)
+            ? this.api.watch(this.name(account), this.folder(account, folder), limit, scope, signal)
+            : undefined;
+    }
+    startIdleSweep() {
+        this.imap.startIdleSweep();
+    }
+    dispose() {
+        this.imap.dispose();
+        this.api.clear();
+    }
+}

package/lib/mailbox-web.d.ts

@@ -0,0 +1,11 @@
+import type { EmailRuntime } from './runtime.js';
+import type { EmailDraftBackend } from './draft-web.js';
+export declare const MAILBOX_ROUTE = "/api/dsh-email/mailbox";
+export declare class EmailMailboxBackend {
+    private runtime;
+    private drafts;
+    constructor(runtime: Pick<EmailRuntime, 'getEffectiveSettings' | 'getPool'>, drafts: EmailDraftBackend);
+    action(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+    fetch(request: Request): Promise<Response>;
+}
+export declare function installEmailMailbox(ctx: any, backend: EmailMailboxBackend): void;

package/lib/mailbox-web.js

@@ -0,0 +1,219 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { buildReplyMessage } from './mail-client.js';
+import { draftFields } from './draft-store.js';
+import { parseEmailDay } from './tool-contract.js';
+import { clampInt } from './config.js';
+export const MAILBOX_ROUTE = '/api/dsh-email/mailbox';
+const json = (status, value) => new Response(JSON.stringify(value), {
+    status,
+    headers: {
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+    },
+});
+export class EmailMailboxBackend {
+    runtime;
+    drafts;
+    constructor(runtime, drafts) {
+        this.runtime = runtime;
+        this.drafts = drafts;
+    }
+    async action(body, signal) {
+        const settings = this.runtime.getEffectiveSettings(), account = typeof body.account === 'string' && body.account
+            ? body.account
+            : settings.defaultAccount, cfg = settings.accounts.get(account);
+        if (!cfg)
+            throw new Error('账号不存在，请重新选择');
+        if (body.action === 'accounts')
+            return {
+                accounts: [...settings.accounts].map(([name, c]) => ({
+                    name,
+                    user: c.user,
+                    api: c.transport === 'agentmail',
+                })),
+                defaultAccount: settings.defaultAccount,
+            };
+        const pool = this.runtime.getPool(), folder = typeof body.folder === 'string' && body.folder
+            ? body.folder
+            : cfg.inboxFolder;
+        if (folder.length > 1024 || /[\r\n\0]/.test(folder))
+            throw new Error('无效文件夹');
+        if (body.action === 'folders')
+            return pool.folders(account, false, signal);
+        if (body.action === 'list') {
+            const limit = clampInt(body.limit, 20, 1, 100), offset = clampInt(body.offset, 0, 0, 10000);
+            const since = typeof body.since === 'string' && body.since
+                ? parseEmailDay(body.since, 'since')
+                : undefined, until = typeof body.until === 'string' && body.until
+                ? parseEmailDay(body.until, 'until', true)
+                : undefined;
+            const query = typeof body.query === 'string' ? body.query.trim() : '';
+            if (query.length > 500)
+                throw new Error('搜索词过长');
+            return query
+                ? pool.search(account, query, folder, limit, offset, since, until, signal, {
+                    headerScanOffset: clampInt(body.headerScanOffset, 0, 0, 1_000_000_000),
+                })
+                : pool.list(account, folder, limit, offset, body.unreadOnly === true, since, until, signal);
+        }
+        const uid = body.uid;
+        if (!((typeof uid === 'number' && Number.isSafeInteger(uid) && uid > 0) ||
+            (typeof uid === 'string' &&
+                uid.length > 0 &&
+                uid.length <= 998 &&
+                !/[\r\n\0]/.test(uid))))
+            throw new Error('请从邮件列表重新选择邮件');
+        if (body.action === 'read')
+            return pool.read(account, uid, folder, signal);
+        if (body.action === 'mark') {
+            if (!['read', 'unread', 'star', 'unstar'].includes(String(body.mark)))
+                throw new Error('不支持的邮件状态操作');
+            return pool.mark(account, folder, uid, body.mark, undefined, signal);
+        }
+        if (body.action === 'replyDraft') {
+            const original = await pool.read(account, uid, folder, signal), mode = body.replyAll === true ? 'reply-all' : 'reply';
+            const built = buildReplyMessage({ ...original, messageId: '', references: '' }, mode, [cfg.user, cfg.authUser], '');
+            const created = await this.drafts.store.create(draftFields({
+                account,
+                to: built.to,
+                cc: '',
+                subject: built.subject,
+                text: built.text,
+            }), [], signal);
+            return this.drafts.store.change(created.id, created.revision, (draft) => {
+                draft.reply = {
+                    uid,
+                    folder,
+                    ...(original.uidValidity
+                        ? { uidValidity: original.uidValidity }
+                        : {}),
+                };
+            }, signal);
+        }
+        throw new Error('不支持的邮箱操作');
+    }
+    async fetch(request) {
+        const fail = (status) => json(status, {
+            ok: false,
+            error: {
+                message: '邮件操作失败，请检查账号、连接或稍后重试 / Email action failed; check the account and connection',
+            },
+        });
+        const origin = request.headers.get('origin'), site = request.headers.get('sec-fetch-site');
+        if (request.method !== 'POST' ||
+            request.headers.get('x-dsh-email-mailbox') !== '1' ||
+            request.headers.get('content-type')?.split(';')[0] !==
+                'application/json' ||
+            (site && !['same-origin', 'none'].includes(site)))
+            return fail(403);
+        // DSH's authenticated connection carrier reconstructs the URL internally;
+        // the original Host header identifies the browser-facing origin.
+        if (origin) {
+            try {
+                const source = new URL(origin);
+                if (!['http:', 'https:'].includes(source.protocol) ||
+                    source.host !==
+                        (request.headers.get('host') || new URL(request.url).host))
+                    return fail(403);
+            }
+            catch {
+                return fail(403);
+            }
+        }
+        const reader = request.body?.getReader();
+        if (!reader)
+            return fail(400);
+        try {
+            const chunks = [];
+            let size = 0;
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 16384) {
+                    await reader.cancel();
+                    return fail(413);
+                }
+                chunks.push(value);
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                return fail(400);
+            const signal = AbortSignal.any([
+                request.signal,
+                AbortSignal.timeout(120000),
+            ]);
+            if (body.action === 'download') {
+                // The authenticated file action owns only the copy created by this call.
+                const settings = this.runtime.getEffectiveSettings(), account = typeof body.account === 'string' && body.account
+                    ? body.account
+                    : settings.defaultAccount, cfg = settings.accounts.get(account), folder = typeof body.folder === 'string' && body.folder
+                    ? body.folder
+                    : (cfg?.inboxFolder ?? '');
+                if (!cfg ||
+                    folder.length > 1024 ||
+                    /[\r\n\0]/.test(folder) ||
+                    !Number.isSafeInteger(body.index) ||
+                    body.index < 0 ||
+                    body.index > 999)
+                    return fail(400);
+                if (!((typeof body.uid === 'number' &&
+                    Number.isSafeInteger(body.uid) &&
+                    body.uid > 0) ||
+                    (typeof body.uid === 'string' &&
+                        body.uid.length > 0 &&
+                        body.uid.length <= 998 &&
+                        !/[\r\n\0]/.test(body.uid))))
+                    return fail(400);
+                const file = await this.runtime
+                    .getPool()
+                    .downloadAttachment(account, folder, body.uid, clampInt(body.index, 0, 0, 999), undefined, signal);
+                try {
+                    const bytes = await readFile(file.path);
+                    if (bytes.length >
+                        this.runtime.getEffectiveSettings().maxAttachmentBytes)
+                        return fail(413);
+                    return new Response(new Uint8Array(bytes), {
+                        headers: {
+                            'content-type': 'application/octet-stream',
+                            'content-disposition': "attachment; filename*=UTF-8''" +
+                                encodeURIComponent(file.filename),
+                            'x-content-type-options': 'nosniff',
+                            'cache-control': 'no-store',
+                        },
+                    });
+                }
+                finally {
+                    await unlink(file.path).catch(() => { });
+                }
+            }
+            return json(200, { ok: true, value: await this.action(body, signal) });
+        }
+        catch (error) {
+            let message = error instanceof Error ? error.message : '邮件操作失败';
+            try {
+                for (const cfg of this.runtime.getEffectiveSettings().accounts.values())
+                    for (const key of [cfg.password, cfg.authPassword])
+                        if (key)
+                            message = message.split(key).join('[已隐藏]');
+            }
+            catch { }
+            return json(400, {
+                ok: false,
+                error: { message: message.slice(0, 1000) },
+            });
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+export function installEmailMailbox(ctx, backend) {
+    ctx.inject?.(['connection'], (host) => host.connection?.fetch?.register?.({
+        path: MAILBOX_ROUTE,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        fetch: (request) => backend.fetch(request),
+    }));
+}

package/lib/public-download.d.ts

@@ -0,0 +1,3 @@
+export declare function publicAddress(address: string): boolean;
+/** Download a signed public HTTPS URL without API credentials; pin the validated DNS answers. */
+export declare function downloadPublicBytes(input: string, cap: number, signal?: AbortSignal, redirects?: number): Promise<Buffer>;