dsh-email 0.14.6 → 0.15.0

package/lib/draft-web.js

@@ -0,0 +1,386 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, open, stat } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { DraftError, DraftStore, draftFields } from './draft-store.js';
+import { matchRecipients, parseRecipientPolicies, serializeRecipientPolicies } from './recipient-policy.js';
+import { messageOf, redactCredentials } from './mail-client.js';
+export const EMAIL_DRAFT_ROUTE = '/api/dsh-email/drafts';
+const MAX_BYTES = 20 * 1024 * 1024;
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const json = (status, value) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } });
+const editable = (draft) => { if (draft.state !== 'draft')
+    throw new DraftError('已提交或结果未确定的邮件不能再次发送；请先去邮箱核对，必要时复制为新草稿', 'draft-submitted'); };
+const view = (draft) => ({ ...draft, attachments: draft.attachments.map(({ id, filename }) => ({ id, filename })) });
+/** All mutations use the host's authenticated fetch carrier and an explicit UI action. */
+export class EmailDraftBackend {
+    runtime;
+    settings;
+    options;
+    store;
+    plans = new Map();
+    constructor(runtime, settings, options = {}) {
+        this.runtime = runtime;
+        this.settings = settings;
+        this.options = options;
+        this.store = options.store ?? new DraftStore();
+    }
+    now() { return this.options.now?.() ?? Date.now(); }
+    prune() { for (const [id, plan] of this.plans)
+        if (this.now() - plan.created > 10 * 60 * 1000)
+            this.plans.delete(id); }
+    invalidate(id) { for (const [key, plan] of this.plans)
+        if (plan.draft.id === id)
+            this.plans.delete(key); }
+    connection(account) {
+        const settings = this.runtime.getEffectiveSettings(), name = account || settings.defaultAccount, config = settings.accounts.get(name);
+        if (!config)
+            throw new DraftError('发件账号不存在，请重新选择账号');
+        const value = this.runtime.getSettingsValue(), policies = parseRecipientPolicies(value.trustedRecipientsYaml);
+        return { name, config, cap: Math.min(settings.maxAttachmentBytes, MAX_BYTES), policy: policies.get(name), key: hash({ name, config, cap: settings.maxAttachmentBytes, policies: value.trustedRecipientsYaml ?? '', approval: value.sendApproval }) };
+    }
+    safe(error) {
+        let message = redactCredentials(messageOf(error, '操作失败，请稍后重试'));
+        try {
+            for (const account of this.runtime.getEffectiveSettings().accounts.values())
+                for (const secret of [account.password, account.authPassword])
+                    if (secret && secret.length >= 4)
+                        message = message.split(secret).join('[已隐藏]');
+        }
+        catch { /* Incomplete account errors are actionable. */ }
+        return message.slice(0, 1200);
+    }
+    async bytes(file, cap, signal) {
+        signal?.throwIfAborted();
+        let stream;
+        try {
+            const info = await stat(file.path);
+            if (!info.isFile() || info.size > cap)
+                throw new Error('size');
+            stream = createReadStream(file.path, { signal });
+            const parts = [];
+            let total = 0;
+            for await (const part of stream) {
+                signal?.throwIfAborted();
+                const chunk = Buffer.from(part);
+                total += chunk.length;
+                if (total > cap)
+                    throw new Error('size');
+                parts.push(chunk);
+            }
+            return Buffer.concat(parts);
+        }
+        catch {
+            signal?.throwIfAborted();
+            throw new DraftError('附件「' + file.filename + '」不可读或超过草稿附件上限，请移除后重新添加');
+        }
+        finally {
+            stream?.destroy();
+        }
+    }
+    async attachments(draft, cap, signal) {
+        const result = [];
+        let used = 0;
+        for (const file of draft.attachments) {
+            const content = await this.bytes(file, cap - used, signal);
+            used += content.length;
+            result.push({ id: file.id, filename: file.filename, content });
+        }
+        return result;
+    }
+    async create(input, signal) {
+        const fields = draftFields(input);
+        if (!fields.account) {
+            try {
+                fields.account = this.runtime.getEffectiveSettings().defaultAccount;
+            }
+            catch { /* A local draft is useful even before the mailbox is configured. */ }
+        }
+        const paths = input.attachments ?? [];
+        if (!Array.isArray(paths) || paths.length > 10 || paths.some(file => typeof file !== 'string' || !file.trim()))
+            throw new DraftError('附件应为最多 10 个本地文件路径');
+        const files = paths.map(path => ({ id: randomUUID(), path: resolve(path), filename: basename(path), owned: false }));
+        if (files.length) {
+            const cap = fields.account ? this.connection(fields.account).cap : MAX_BYTES;
+            await this.attachments({ attachments: files }, cap, signal);
+        }
+        return this.store.create(fields, files, signal);
+    }
+    async recover(signal) {
+        for (const draft of await this.store.list())
+            if (draft.state === 'sending') {
+                try {
+                    await this.store.sendLock(draft.id, async (current) => { await this.store.change(draft.id, draft.revision, value => { if (value.state === 'sending') {
+                        value.state = 'uncertain';
+                        value.error = '上次提交未留下完整回执；请先去邮箱核对，不会自动重发';
+                    } }, current); }, signal);
+                }
+                catch (error) {
+                    if (!(error instanceof DraftError) || !['draft-busy', 'draft-conflict', 'draft-missing'].includes(error.code))
+                        throw error;
+                }
+            }
+    }
+    async action(body, signal) {
+        this.prune();
+        signal?.throwIfAborted();
+        if (body.action === 'list') {
+            await this.recover(signal);
+            const snapshot = await this.settings.snapshot();
+            return { drafts: (await this.store.list()).map(view), accounts: snapshot.accounts, revision: snapshot.settings.revision, writable: snapshot.writable };
+        }
+        if (body.action === 'rules') {
+            const snapshot = await this.settings.snapshot();
+            const policies = parseRecipientPolicies(snapshot.settings.value.trustedRecipientsYaml);
+            return { accounts: snapshot.accounts, revision: snapshot.settings.revision, writable: snapshot.writable, sendApproval: snapshot.settings.value.sendApproval !== false, policies: Object.fromEntries(policies) };
+        }
+        if (body.action === 'saveRules' || body.action === 'matchRules') {
+            if (typeof body.account !== 'string' || !body.account.trim())
+                throw new DraftError('请先选择账号');
+            const snapshot = await this.settings.snapshot();
+            if (!snapshot.accounts.includes(body.account))
+                throw new DraftError('账号已改变，请重新加载规则');
+            const single = parseRecipientPolicies(JSON.stringify({ [body.account]: body.policy })).get(body.account);
+            if (!single)
+                throw new DraftError('请填写完整的收件人规则');
+            if (body.action === 'matchRules')
+                return matchRecipients(String(body.to ?? ''), String(body.cc ?? ''), single);
+            const all = parseRecipientPolicies(snapshot.settings.value.trustedRecipientsYaml);
+            all.set(body.account, single);
+            await this.settings.saveRecipientRules(serializeRecipientPolicies(all), body.revision);
+            return this.action({ action: 'rules' }, signal);
+        }
+        if (body.action === 'create')
+            return view(await this.create({ ...body, attachments: [] }, signal)); // Browser attachments only come from its file chooser.
+        const id = typeof body.id === 'string' ? body.id : '', draft = await this.store.get(id);
+        if (body.action === 'get')
+            return view(draft);
+        if (body.action === 'cancelPreview') {
+            this.invalidate(id);
+            return { cancelled: true };
+        }
+        if (body.action === 'update') {
+            editable(draft);
+            const fields = draftFields(body), keep = body.attachments ?? draft.attachments.map(file => file.id);
+            if (!Array.isArray(keep) || keep.some(key => !draft.attachments.some(file => file.id === key)) || new Set(keep).size !== keep.length)
+                throw new DraftError('附件列表无效，请重新打开草稿');
+            const changed = await this.store.change(id, body.revision, value => { editable(value); Object.assign(value, fields); value.attachments = value.attachments.filter(file => keep.includes(file.id)); }, signal);
+            this.invalidate(id);
+            for (const file of draft.attachments)
+                if (!changed.attachments.some(kept => kept.id === file.id))
+                    await this.store.removeOwnedFile(id, file);
+            return view(changed);
+        }
+        if (body.action === 'delete') {
+            if (body.confirmed !== true)
+                throw new DraftError('请先确认删除本地草稿与上传副本');
+            await this.store.remove(id, body.revision, signal);
+            this.invalidate(id);
+            return { removed: true };
+        }
+        if (body.action === 'copy') {
+            if (draft.revision !== body.revision)
+                throw new DraftError('草稿已改变，请重新打开后复制', 'draft-conflict');
+            if (draft.state === 'sending')
+                throw new DraftError('邮件还在提交，请结束后再复制', 'draft-busy');
+            if (body.confirmed !== true)
+                throw new DraftError('请先核对邮箱，再确认复制为新草稿');
+            const contents = await this.attachments(draft, MAX_BYTES, signal), created = await this.store.create(draftFields(draft), [], signal), files = [];
+            try {
+                for (const file of contents) {
+                    const owned = this.store.uploadPath(created.id, file.filename), stored = { id: randomUUID(), ...owned, owned: true };
+                    files.push(stored);
+                    await this.writeUpload(owned.path, file.content, signal);
+                }
+                const changed = await this.store.change(created.id, created.revision, value => { value.attachments = files; }, signal);
+                return view(changed);
+            }
+            catch (error) {
+                for (const file of files)
+                    await this.store.removeOwnedFile(created.id, file);
+                await this.store.remove(created.id, created.revision).catch(() => { });
+                throw error;
+            }
+        }
+        if (body.action === 'preview') {
+            editable(draft);
+            if (draft.revision !== body.revision)
+                throw new DraftError('草稿已改变，请保存后重新预览', 'draft-conflict');
+            if (!draft.subject)
+                throw new DraftError('请先填写并保存邮件主题');
+            const connection = this.connection(draft.account), matching = await matchRecipients(draft.to, draft.cc, connection.policy), attachments = await this.attachments(draft, connection.cap, signal);
+            if (connection.key !== this.connection(draft.account).key || (await this.store.get(id)).revision !== draft.revision)
+                throw new DraftError('草稿或账号已改变，请重新预览', 'draft-conflict');
+            this.invalidate(id);
+            if (this.plans.size >= 3)
+                this.plans.delete(this.plans.keys().next().value);
+            const plan = { id: randomUUID(), created: this.now(), key: connection.key, draft, attachments };
+            this.plans.set(plan.id, plan);
+            return { id: plan.id, draft: view(draft), from: { address: connection.config.user, name: connection.config.senderName }, matching, attachments: attachments.map(({ id, filename, content }) => ({ id, filename, size: content.length, sha256: createHash('sha256').update(content).digest('hex') })), expiresAt: plan.created + 10 * 60 * 1000 };
+        }
+        if (body.action === 'send') {
+            if (body.confirmed !== true)
+                throw new DraftError('请核对预览后明确确认发送');
+            const plan = typeof body.preview === 'string' ? this.plans.get(body.preview) : undefined;
+            if (!plan || plan.draft.id !== id)
+                throw new DraftError('预览已过期或已用过，请重新预览', 'draft-preview-expired');
+            return this.store.sendLock(id, async (current) => {
+                const before = await this.store.get(id);
+                editable(before);
+                if (before.revision !== plan.draft.revision || plan.key !== this.connection(before.account).key)
+                    throw new DraftError('草稿、账号或规则已改变，请重新预览', 'draft-conflict');
+                const pool = this.runtime.getPool();
+                current.throwIfAborted();
+                const pending = await this.store.change(id, before.revision, value => { editable(value); value.state = 'sending'; value.attemptAt = new Date(this.now()).toISOString(); }, current);
+                this.invalidate(id);
+                let unchanged = false;
+                try {
+                    unchanged = plan.key === this.connection(before.account).key;
+                }
+                catch { /* A now-incomplete account also invalidates this review. */ }
+                if (!unchanged) {
+                    await this.store.change(id, pending.revision, value => { value.state = 'draft'; delete value.attemptAt; });
+                    throw new DraftError('账号或规则已改变，邮件未提交；请重新预览', 'draft-conflict');
+                }
+                let receipt;
+                try {
+                    receipt = await pool.sendPrepared(before.account, before.to, before.subject, before.text, before.cc, plan.attachments.map(({ filename, content }) => ({ filename, content })), current);
+                }
+                catch (error) {
+                    const failed = await this.store.change(id, pending.revision, value => { value.state = 'uncertain'; value.error = '提交结果未确定；请先去邮箱核对，不会自动重发。' + this.safe(error); }).catch(() => null);
+                    if (!failed)
+                        throw new DraftError('提交结果未确定，且回执未能保存；请先去邮箱核对，不要直接重发', 'draft-storage');
+                    return { draft: view(failed) };
+                }
+                // Once SMTP acknowledges, a disconnected browser must not prevent the receipt from being persisted.
+                try {
+                    return { draft: view(await this.store.change(id, pending.revision, value => { value.state = 'sent'; value.receipt = receipt; })) };
+                }
+                catch {
+                    throw new DraftError('SMTP 已返回回执，但本地保存失败；请先核对邮箱，不要再次发送', 'draft-storage');
+                }
+            }, signal);
+        }
+        throw new DraftError('不支持此草稿操作');
+    }
+    async writeUpload(path, content, signal) {
+        signal?.throwIfAborted();
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(content);
+            signal?.throwIfAborted();
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async upload(request, content, signal) {
+        const id = request.headers.get('x-dsh-draft-id') ?? '', revision = Number(request.headers.get('x-dsh-draft-revision')), draft = await this.store.get(id);
+        editable(draft);
+        if (draft.revision !== revision || draft.attachments.length >= 10)
+            throw new DraftError('草稿已改变或附件已达 10 个，请保存并重新打开后添加', 'draft-conflict');
+        let filename;
+        try {
+            filename = decodeURIComponent(request.headers.get('x-dsh-draft-filename') ?? '');
+        }
+        catch {
+            throw new DraftError('附件名称无效');
+        }
+        if (!filename || filename.length > 500)
+            throw new DraftError('附件名称为空或过长');
+        let existingSize = 0;
+        for (const file of draft.attachments) {
+            const info = await stat(file.path).catch(() => null);
+            if (info?.isFile())
+                existingSize += info.size;
+        }
+        const cap = (() => { try {
+            return this.connection(draft.account).cap;
+        }
+        catch {
+            return MAX_BYTES;
+        } })();
+        if (existingSize + content.length > cap)
+            throw new DraftError('草稿附件总大小最多 ' + Math.floor(cap / 1024 / 1024) + ' MiB');
+        const owned = { id: randomUUID(), ...this.store.uploadPath(id, filename), owned: true };
+        try {
+            await this.writeUpload(owned.path, content, signal);
+            const changed = await this.store.change(id, revision, value => { editable(value); value.attachments.push(owned); }, signal);
+            this.invalidate(id);
+            return view(changed);
+        }
+        catch (error) {
+            await this.store.removeOwnedFile(id, owned);
+            throw error;
+        }
+    }
+    async fetch(request) {
+        const site = request.headers.get('sec-fetch-site'), origin = request.headers.get('origin');
+        const fail = (status, error) => json(status, { ok: false, error: { code: error instanceof DraftError ? error.code : error?.code === 'SETTINGS_CONFLICT' ? 'settings-conflict' : 'draft-invalid', message: this.safe(error) } });
+        if (site && !['same-origin', 'none'].includes(site))
+            return fail(403, new DraftError('请从邮件草稿面板操作'));
+        if (origin) {
+            try {
+                const url = new URL(origin);
+                if (!['http:', 'https:'].includes(url.protocol) || url.host !== (request.headers.get('host') || new URL(request.url).host))
+                    return fail(403, new DraftError('拒绝跨源操作'));
+            }
+            catch {
+                return fail(403, new DraftError('无效来源'));
+            }
+        }
+        try {
+            this.prune();
+            if (request.method === 'GET') {
+                const url = new URL(request.url), plan = this.plans.get(url.searchParams.get('preview') ?? ''), file = plan?.attachments.find(file => file.id === url.searchParams.get('attachment'));
+                if (!plan || !file || plan.key !== this.connection(plan.draft.account).key)
+                    return fail(404, new DraftError('附件预览已失效，请重新预览'));
+                return new Response(new Uint8Array(file.content), { headers: { 'content-type': 'application/octet-stream', 'content-disposition': "attachment; filename*=UTF-8''" + encodeURIComponent(file.filename), 'x-content-type-options': 'nosniff', 'cache-control': 'no-store' } });
+            }
+            if (request.method !== 'POST')
+                return fail(405, new DraftError('请使用草稿面板支持的操作'));
+            const type = request.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
+            if (request.headers.get('x-dsh-email-draft') !== '1' || !['application/json', 'application/octet-stream'].includes(type ?? ''))
+                return fail(403, new DraftError('请从邮件草稿面板操作'));
+            const reader = request.body?.getReader();
+            if (!reader)
+                throw new DraftError('请求为空');
+            const limit = type === 'application/octet-stream' ? MAX_BYTES : 256 * 1024, chunks = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.length;
+                    if (size > limit) {
+                        await reader.cancel();
+                        return fail(413, new DraftError('请求超过大小上限'));
+                    }
+                    chunks.push(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const content = Buffer.concat(chunks), signal = AbortSignal.any([request.signal, AbortSignal.timeout(120000)]);
+            if (type === 'application/octet-stream')
+                return json(200, { ok: true, value: await this.upload(request, content, signal) });
+            const body = JSON.parse(content.toString('utf8'));
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                throw new DraftError('请求必须为对象');
+            return json(200, { ok: true, value: await this.action(body, signal) });
+        }
+        catch (error) {
+            return fail(error instanceof DraftError && ['draft-conflict', 'draft-busy', 'draft-submitted'].includes(error.code) || error?.code === 'SETTINGS_CONFLICT' ? 409 : 400, error);
+        }
+    }
+}
+export function installEmailDrafts(ctx, backend) {
+    ctx.inject?.(['connection'], (host) => {
+        host.connection?.fetch?.register?.({ path: EMAIL_DRAFT_ROUTE, methods: ['POST', 'GET'], requestBody: 'buffered', fetch: (request) => backend.fetch(request) });
+        host.connection?.fetch?.register?.({ path: EMAIL_DRAFT_ROUTE + '/upload', methods: ['POST'], requestBody: 'streaming', fetch: (request) => backend.fetch(request) });
+    });
+}

package/lib/host-config.js

@@ -15,6 +15,7 @@ export const Config = z.object({
     maxBodyChars: z.number().volatile(), downloadDir: z.string().volatile(),
     accounts: z.dict(z.any()).role('secret').volatile(), defaultAccount: z.string().volatile(),
     accountsYaml: z.string().role('secret').volatile(), serverPresets: z.string().volatile(),
+    trustedRecipientsYaml: z.string().volatile(),
     maxAttachmentBytes: z.number().volatile(), bodySearchFallback: z.boolean().volatile(),
     bodySearchLimit: z.number().volatile(), idleTimeoutMs: z.number().volatile(),
     legacySettingsImported: z.boolean().volatile(),

package/lib/index.d.ts

@@ -15,3 +15,5 @@ export { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase,
 export { parseEmailDay } from './tool-contract.js';
 export { EmailSettingsBackend, installEmailSettingsWeb, SETTINGS_ROUTE } from './web.js';
 export type { AccountCardData, AccountCardInput } from './web.js';
+export { EmailDraftBackend, installEmailDrafts, EMAIL_DRAFT_ROUTE } from './draft-web.js';
+export { DraftStore, DraftError } from './draft-store.js';

package/lib/index.js

@@ -5,6 +5,7 @@ import { EmailSettingsBackend, installEmailSettingsWeb } from './web.js';
 import { liveConfig, Config as ConfigSchema } from './host-config.js';
 import { installLegacySettingsImport } from './legacy-settings.js';
 import { EmailSettingsSchema, SETTINGS_NAMESPACE } from './settings.js';
+import { EmailDraftBackend, installEmailDrafts } from './draft-web.js';
 export const Config = ConfigSchema;
 export const name = 'tool-email';
 export const inject = ['settings', 'tools'];
@@ -21,7 +22,9 @@ export function apply(ctx, config = {}) {
     const backend = new EmailSettingsBackend(ctx, runtime.settingsScope, config);
     backend.watchImpl = runtime.watch;
     installEmailSettingsWeb(ctx, backend);
-    for (const definition of buildEmailTools(runtime))
+    const drafts = new EmailDraftBackend(runtime, backend);
+    installEmailDrafts(ctx, drafts);
+    for (const definition of buildEmailTools(runtime, drafts))
         ctx.tools.register(definition);
     installSendApproval(ctx, runtime);
 }
@@ -32,3 +35,5 @@ export { flattenAddresses, parseRawMessage, sanitizeFilename, stripHtml, truncat
 export { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
 export { parseEmailDay } from './tool-contract.js';
 export { EmailSettingsBackend, installEmailSettingsWeb, SETTINGS_ROUTE } from './web.js';
+export { EmailDraftBackend, installEmailDrafts, EMAIL_DRAFT_ROUTE } from './draft-web.js';
+export { DraftStore, DraftError } from './draft-store.js';

package/lib/mail-client.d.ts

@@ -208,6 +208,11 @@ export declare class EmailPool {
     folders(accountName: string | undefined, subscribedOnly: boolean, signal?: AbortSignal): Promise<EmailFoldersResult>;
     downloadAttachment(accountName: string | undefined, folder: string, uid: number, index: number, workspaceHint?: string, signal?: AbortSignal): Promise<EmailAttachmentResult>;
     send(accountName: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, attachmentPaths: string[] | undefined, signal?: AbortSignal): Promise<EmailSendResult>;
+    /** Send the attachment bytes the human reviewed, without re-reading mutable paths. */
+    sendPrepared(accountName: string, to: string, subject: string, text: string, cc: string, attachments: Array<{
+        filename: string;
+        content: Buffer;
+    }>, signal?: AbortSignal): 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

@@ -356,7 +356,7 @@ export class EmailPool {
         // 附件索引只需要 MIME 结构：bodyStructure 已经给出每个附件的 part/名称/大小，
         // 不必为了拿它先拉整封 source（第一次就下载附件的邮件也一样）。
         const message = await client.fetchOne(uid, { uid: true, bodyStructure: true }, { uid: true });
-        if (message === false) {
+        if (message === false || message === undefined) {
             throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folder + '"）');
         }
         signal?.throwIfAborted();
@@ -371,7 +371,7 @@ export class EmailPool {
         const full = message.source !== undefined
             ? message
             : await client.fetchOne(uid, { uid: true, source: true, bodyStructure: true }, { uid: true });
-        if (full === false || full.source === undefined) {
+        if (full === false || full === undefined || full.source === undefined) {
             throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folder + '"）');
         }
         const body = await parseRawMessage(full.source, this.settings.maxBodyChars);
@@ -585,7 +585,7 @@ export class EmailPool {
             greetingTimeout: 10000,
             socketTimeout: 60000,
             getSocket: (options, callback) => {
-                const socket = createConnection({ host: options.host ?? cfg.smtp.host, port: options.port ?? cfg.smtp.port });
+                const socket = createConnection({ host: options.host ?? cfg.smtp.host, port: Number(options.port ?? cfg.smtp.port) });
                 onSocket(socket);
                 let settled = false;
                 const finish = (error, socketOptions) => {
@@ -715,6 +715,8 @@ export class EmailPool {
     async downloadPartText(client, uid, part, maxBytes, signal) {
         const dl = await client.download(uid, part.key, { uid: true, maxBytes });
         signal?.throwIfAborted();
+        if (dl.content === undefined)
+            throw new MailError('邮件正文分段已不存在；将尝试重新读取邮件');
         const buf = await collectStream(dl.content, maxBytes, signal);
         signal?.throwIfAborted();
         return buf.toString('utf8');
@@ -757,7 +759,7 @@ export class EmailPool {
                     query.before = until;
                 const found = await client.search(query, { uid: true });
                 signal?.throwIfAborted();
-                uids = found === false ? [] : found;
+                uids = Array.isArray(found) ? found : [];
                 scopeCount = uids.length;
             }
             else if (total > 0) {
@@ -785,7 +787,7 @@ export class EmailPool {
             const uidValidity = mailbox === false ? 0 : Number(mailbox.uidValidity ?? 0);
             const found = await client.search({ seen: false }, { uid: true });
             signal?.throwIfAborted();
-            const uids = (found === false ? [] : found).slice().sort((a, b) => b - a);
+            const uids = (Array.isArray(found) ? found : []).slice().sort((a, b) => b - a);
             return { account: name, folder: folderName, uidValidity, count: uids.length, uids };
         }, true, signal);
     }
@@ -822,7 +824,7 @@ export class EmailPool {
                 client.search({ cc: query, ...dateRange }, { uid: true }),
             ]);
             signal?.throwIfAborted();
-            const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => b - a);
+            const uids = [...new Set(found.flatMap(result => Array.isArray(result) ? result : []))].sort((a, b) => b - a);
             if (uids.length > 0) {
                 // The sample has to cover the requested page (offset + limit) — the same
                 // window the fallback scan looks at — so one FETCH serves both the
@@ -938,7 +940,7 @@ export class EmailPool {
             // 先只要信封与 MIME 结构，正文按 text/* 分段下载：带 20 MiB 附件的邮件
             // 只为看正文时不再整封拉下来，附件元数据直接复用 bodyStructure。
             const message = await client.fetchOne(uid, { uid: true, envelope: true, bodyStructure: true }, { uid: true });
-            if (message === false) {
+            if (message === false || message === undefined) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             signal?.throwIfAborted();
@@ -979,7 +981,7 @@ export class EmailPool {
             const full = message.source !== undefined
                 ? message
                 : await client.fetchOne(uid, { uid: true, source: true, bodyStructure: true }, { uid: true });
-            if (full === false || full.source === undefined) {
+            if (full === false || full === undefined || full.source === undefined) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             const body = await parseRawMessage(full.source, this.settings.maxBodyChars);
@@ -995,7 +997,7 @@ export class EmailPool {
         return this.withImap(name, folderName, async (client) => {
             const before = await client.fetchOne(uid, { uid: true, flags: true }, { uid: true });
             signal?.throwIfAborted();
-            if (before === false) {
+            if (before === false || before === undefined) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             let seen = before.flags?.has('\\Seen') === true;
@@ -1090,8 +1092,10 @@ export class EmailPool {
             }
             const dl = await client.download(uid, att.part, { uid: true, maxBytes: this.settings.maxAttachmentBytes });
             signal?.throwIfAborted();
+            if (dl.content === undefined)
+                throw new MailError('附件分段已不存在，请重新读取邮件后再下载');
             const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes, signal);
-            const safeName = sanitizeFilename(dl.meta.filename ?? att.filename ?? attachments[index].filename);
+            const safeName = sanitizeFilename(dl.meta?.filename ?? att.filename ?? attachments[index].filename);
             // Default the destination to the session workspace so the model can
             // read the file back; an explicit downloadDir always wins.
             const dir = this.settings.downloadDirExplicit
@@ -1127,6 +1131,14 @@ export class EmailPool {
             response: typeof info.response === 'string' ? info.response : String(info.response ?? ''),
         };
     }
+    /** Send the attachment bytes the human reviewed, without re-reading mutable paths. */
+    async sendPrepared(accountName, to, subject, text, cc, attachments, signal) {
+        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);
+        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) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
@@ -1135,7 +1147,7 @@ export class EmailPool {
         // leaves a half-written mailbox state behind.
         const built = await this.withImap(name, folderName, async (client) => {
             const message = await client.fetchOne(uid, { uid: true, source: true }, { uid: true });
-            if (message === false || message.source === undefined) {
+            if (message === false || message === undefined || message.source === undefined) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             const ids = extractMessageIds(message.source);

package/lib/recipient-policy.d.ts

@@ -0,0 +1,26 @@
+export interface RecipientPolicy {
+    skipApproval: boolean;
+    addresses: string[];
+    domains: string[];
+}
+export interface RecipientMatch {
+    field: 'to' | 'cc';
+    address: string;
+    matched: boolean;
+    rule: 'address' | 'domain' | '';
+    value: string;
+}
+export declare function canonicalDomain(value: string): string;
+export declare function canonicalAddress(value: string): string;
+/** The public Nodemailer JSON transport compiles the same recipient envelope without delivery. */
+export declare function normalizeRecipients(to: string, cc?: string): Promise<Array<{
+    field: 'to' | 'cc';
+    address: string;
+}>>;
+export declare function parseRecipientPolicies(text?: string): Map<string, RecipientPolicy>;
+export declare function serializeRecipientPolicies(policies: Map<string, RecipientPolicy>): string;
+export declare function matchRecipients(to: string, cc: string, policy?: RecipientPolicy): Promise<{
+    rows: RecipientMatch[];
+    allTrusted: boolean;
+    skipsApproval: boolean;
+}>;