dsh-email 0.1.0 → 0.2.0

package/lib/mail-client.js

@@ -1,7 +1,8 @@
 import { ImapFlow } from 'imapflow';
 import nodemailer from 'nodemailer';
-import { flattenAddresses } from './parse.js';
-import { parseRawMessage } from './parse.js';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { flattenAddresses, parseRawMessage, sanitizeFilename } from './parse.js';
 export class MailError extends Error {
     constructor(message) {
         super(message);
@@ -20,6 +21,25 @@ function structureHasAttachment(node) {
     const children = Array.isArray(node.childNodes) ? node.childNodes : [];
     return children.some(structureHasAttachment);
 }
+/** Walk a bodyStructure tree collecting attachment parts (DFS, same order as mailparser). */
+function collectAttachmentParts(node, out = []) {
+    if (node === null || node === undefined || typeof node !== 'object')
+        return out;
+    const isEmbedded = typeof node.type === 'string' && node.type.startsWith('message/rfc822');
+    if (node.part !== undefined && (node.disposition === 'attachment' || (isEmbedded && node.disposition !== 'inline'))) {
+        const filename = node.dispositionParameters?.filename ?? node.parameters?.name ?? 'part-' + node.part;
+        out.push({
+            part: String(node.part),
+            filename: String(filename),
+            contentType: typeof node.type === 'string' ? node.type : 'application/octet-stream',
+            size: typeof node.size === 'number' ? node.size : 0,
+        });
+    }
+    const children = Array.isArray(node.childNodes) ? node.childNodes : [];
+    for (const child of children)
+        collectAttachmentParts(child, out);
+    return out;
+}
 function toIso(date) {
     return date instanceof Date ? date.toISOString() : '';
 }
@@ -35,52 +55,153 @@ function listedFrom(envelope, size, hasAttachments) {
         hasAttachments,
     };
 }
-/** One IMAP account; every operation opens its own short-lived connection. */
-export class MailClient {
-    config;
-    constructor(config) {
-        this.config = config;
+/**
+ * One mailbox pool for the whole plugin: pooled IMAP connections per
+ * account plus pooled SMTP transporters, with idle sweep and error eviction.
+ */
+export class EmailPool {
+    settings;
+    imaps = new Map();
+    smtps = new Map();
+    queues = new Map();
+    idleTimer;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    account(name) {
+        const cfg = this.settings.accounts.get(name);
+        if (cfg === undefined) {
+            throw new MailError('未知账号 "' + name + '"，可用：' + [...this.settings.accounts.keys()].join('、'));
+        }
+        return cfg;
+    }
+    resolveName(name) {
+        return name?.trim() || this.settings.defaultAccount;
+    }
+    /** Serialize operations per account: one IMAP connection serves one op at a time. */
+    enqueue(name, task) {
+        const prev = this.queues.get(name) ?? Promise.resolve();
+        const next = prev.then(task, task);
+        this.queues.set(name, next.then(() => undefined, () => undefined));
+        return next;
     }
-    createImap() {
+    async withImap(accountName, folder, run) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        return this.enqueue(name, () => this.imapRun(name, cfg, folder, run));
+    }
+    createImap(cfg) {
         return new ImapFlow({
-            host: this.config.imap.host,
-            port: this.config.imap.port,
-            secure: this.config.imap.secure,
-            auth: { user: this.config.user, pass: this.config.password },
+            host: cfg.imap.host,
+            port: cfg.imap.port,
+            secure: cfg.imap.secure,
+            auth: { user: cfg.user, pass: cfg.password },
             logger: false,
-            connectionTimeout: this.config.imap.connectionTimeoutMs ?? 30000,
+            connectionTimeout: cfg.imap.connectionTimeoutMs ?? 30000,
             greetingTimeout: 30000,
-            socketTimeout: this.config.imap.socketTimeoutMs ?? 60000,
+            socketTimeout: cfg.imap.socketTimeoutMs ?? 60000,
         });
     }
-    /** Open the mailbox read-only, run the operation, always close. */
-    async withImap(folder, run) {
-        const client = this.createImap();
+    async imapRun(name, cfg, folder, run) {
+        let entry = this.imaps.get(name);
         try {
-            await client.connect();
-            await client.mailboxOpen(folder, { readOnly: true });
-            return await run(client);
-        }
-        catch (error) {
-            const raw = messageOf(error, 'IMAP 操作失败');
-            if (raw.toLowerCase().includes('authentication') || raw.toLowerCase().includes('login')) {
-                throw new MailError(`邮箱登录失败：${raw}（请检查 user 与授权码）`);
+            if (entry === undefined || !entry.client.usable) {
+                if (entry !== undefined)
+                    await this.evictImap(name);
+                const client = this.createImap(cfg);
+                await client.connect();
+                entry = { client, selected: null, lastUsed: Date.now(), inUse: 0 };
+                this.imaps.set(name, entry);
             }
-            if (raw.toLowerCase().includes('nonselect') || raw.toLowerCase().includes('does not exist')) {
-                throw new MailError(`找不到邮箱文件夹 "${folder}"：${raw}`);
+            entry.lastUsed = Date.now();
+            entry.inUse += 1;
+            if (folder !== null && entry.selected !== folder) {
+                await entry.client.mailboxOpen(folder, { readOnly: true });
+                entry.selected = folder;
             }
-            throw new MailError(raw);
+            const result = await run(entry.client);
+            entry.lastUsed = Date.now();
+            return result;
+        }
+        catch (error) {
+            await this.evictImap(name);
+            throw this.normalizeImapError(error, folder);
         }
         finally {
-            try {
-                await client.logout();
+            if (entry !== undefined)
+                entry.inUse = Math.max(0, entry.inUse - 1);
+        }
+    }
+    normalizeImapError(error, folder) {
+        const raw = messageOf(error, 'IMAP 操作失败');
+        const lower = raw.toLowerCase();
+        if (lower.includes('authentication') || lower.includes('login')) {
+            return new MailError('邮箱登录失败：' + raw + '（请检查 user 与授权码）');
+        }
+        if (lower.includes('nonselect') || lower.includes('does not exist') || lower.includes('nonexistent')) {
+            return new MailError('找不到邮箱文件夹 "' + (folder ?? '') + '"：' + raw);
+        }
+        return new MailError(raw);
+    }
+    async evictImap(name) {
+        const entry = this.imaps.get(name);
+        if (entry === undefined)
+            return;
+        this.imaps.delete(name);
+        try {
+            await entry.client.logout();
+        }
+        catch { /* already closed */ }
+    }
+    /** Reap IMAP connections idle for longer than idleTimeoutMs. */
+    startIdleSweep() {
+        if (this.idleTimer !== undefined)
+            return;
+        const intervalMs = Math.max(5000, Math.min(this.settings.idleTimeoutMs / 2, 30000));
+        this.idleTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [name, entry] of this.imaps) {
+                if (entry.inUse === 0 && now - entry.lastUsed > this.settings.idleTimeoutMs) {
+                    void this.evictImap(name);
+                }
             }
-            catch { /* already closed */ }
+        }, intervalMs);
+        this.idleTimer.unref();
+    }
+    dispose() {
+        if (this.idleTimer !== undefined)
+            clearInterval(this.idleTimer);
+        this.idleTimer = undefined;
+        for (const name of [...this.imaps.keys()])
+            void this.evictImap(name);
+        for (const transporter of this.smtps.values())
+            transporter.close();
+        this.smtps.clear();
+    }
+    transporter(name, cfg) {
+        let t = this.smtps.get(name);
+        if (t === undefined) {
+            t = nodemailer.createTransport({
+                pool: true,
+                host: cfg.smtp.host,
+                port: cfg.smtp.port,
+                secure: cfg.smtp.secure,
+                auth: { user: cfg.user, pass: cfg.password },
+                connectionTimeout: 30000,
+                greetingTimeout: 10000,
+                socketTimeout: 60000,
+                maxConnections: 2,
+                maxMessages: 50,
+            });
+            this.smtps.set(name, t);
         }
+        return t;
     }
-    static fetchQuery = { uid: true, envelope: true, flags: true, size: true, bodyStructure: true };
-    async list(folder, limit, offset, unreadOnly) {
-        return this.withImap(folder, async (client) => {
+    async list(accountName, folder, limit, offset, unreadOnly) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const folderName = folder || cfg.inboxFolder;
+        return this.withImap(name, folderName, async (client) => {
             const mailbox = client.mailbox;
             const total = mailbox === false ? 0 : mailbox.exists;
             let scopeCount = total;
@@ -92,18 +213,20 @@ export class MailClient {
             }
             else if (total > 0) {
                 const start = Math.max(1, total - (limit + offset) + 1);
-                const fetched = await client.fetchAll(`${start}:*`, { uid: true }, { uid: true });
+                const fetched = await client.fetchAll(start + ':*', { uid: true }, { uid: true });
                 uids = fetched.map(message => message.uid);
             }
-            // newest first, then the requested window
             uids.reverse();
             const window = uids.slice(offset, offset + limit);
             const messages = await this.fetchListed(client, window);
-            return { count: scopeCount, folder, messages };
+            return { account: name, count: scopeCount, folder: folderName, messages };
         });
     }
-    async search(query, folder, limit) {
-        return this.withImap(folder, async (client) => {
+    async search(accountName, query, folder, limit) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const folderName = folder || cfg.inboxFolder;
+        return this.withImap(name, folderName, async (client) => {
             // No nested OR and no TEXT search: several servers (QQ among them)
             // silently answer those with empty or match-everything results. Three
             // independent searches unioned client-side behave well everywhere.
@@ -115,7 +238,7 @@ export class MailClient {
             const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => a - b);
             uids.reverse();
             const messages = await this.fetchListed(client, uids.slice(0, limit));
-            return { query, count: uids.length, folder, messages };
+            return { account: name, query, count: uids.length, folder: folderName, messages };
         });
     }
     async fetchListed(client, uids) {
@@ -124,47 +247,138 @@ export class MailClient {
         const fetched = await client.fetchAll(uids, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
         return fetched.map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)));
     }
-    async read(uid, folder) {
-        return this.withImap(folder, async (client) => {
+    async read(accountName, uid, folder) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const folderName = folder || cfg.inboxFolder;
+        return this.withImap(name, folderName, async (client) => {
             const message = await client.fetchOne(uid, { uid: true, source: true }, { uid: true });
             if (message === false || message.source === undefined) {
-                throw new MailError(`找不到 uid=${uid} 的邮件（可能已被删除，或不在文件夹 "${folder}"；可用 email_list 重新获取 uid）`);
+                throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
+            }
+            const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
+            return { account: name, uid, folder: folderName, ...body };
+        });
+    }
+    async folders(accountName, subscribedOnly) {
+        const name = this.resolveName(accountName);
+        return this.withImap(name, null, async (client) => {
+            const list = await client.list();
+            const folders = list
+                .filter(row => !subscribedOnly || row.subscribed !== false)
+                .map(row => ({
+                name: row.name ?? row.path,
+                path: row.path,
+                specialUse: row.specialUse ?? '',
+                subscribed: row.subscribed !== false,
+            }));
+            return { account: name, folders };
+        });
+    }
+    async downloadAttachment(accountName, folder, uid, index) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const folderName = folder || cfg.inboxFolder;
+        return this.withImap(name, folderName, async (client) => {
+            const message = await client.fetchOne(uid, { uid: true, bodyStructure: true }, { uid: true });
+            if (message === false) {
+                throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"）');
+            }
+            const attachments = collectAttachmentParts(message.bodyStructure);
+            if (attachments.length === 0)
+                throw new MailError('该邮件没有附件');
+            const att = attachments[index];
+            if (att === undefined) {
+                throw new MailError('附件序号 ' + index + ' 越界：共 ' + attachments.length + ' 个附件（序号从 0 开始，与 email_read 返回的 attachments 顺序一致）');
+            }
+            if (att.size > this.settings.maxAttachmentBytes) {
+                throw new MailError('附件 "' + att.filename + '" 大小 ' + att.size + ' 字节，超过上限 maxAttachmentBytes=' + this.settings.maxAttachmentBytes);
             }
-            const body = await parseRawMessage(message.source, this.config.maxBodyChars);
-            return { uid, folder, ...body };
+            const dl = await client.download(uid, att.part, { uid: true, maxBytes: this.settings.maxAttachmentBytes });
+            const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes);
+            const safeName = sanitizeFilename(dl.meta.filename ?? att.filename);
+            const dir = this.settings.downloadDir;
+            await mkdir(dir, { recursive: true });
+            const dest = await uniquePath(join(dir, safeName));
+            await writeFile(dest, buf);
+            return { account: name, uid, filename: safeName, contentType: att.contentType, size: buf.length, path: dest };
         });
     }
-    async send(to, subject, text, cc) {
-        const transporter = nodemailer.createTransport({
-            host: this.config.smtp.host,
-            port: this.config.smtp.port,
-            secure: this.config.smtp.secure,
-            auth: { user: this.config.user, pass: this.config.password },
-            connectionTimeout: 30000,
-            greetingTimeout: 10000,
-            socketTimeout: 60000,
+    async send(accountName, to, subject, text, cc, attachmentPaths) {
+        const name = this.resolveName(accountName);
+        const cfg = this.account(name);
+        const attachments = await validateAttachmentPaths(attachmentPaths ?? [], this.settings.maxAttachmentBytes);
+        const info = await this.transporter(name, cfg).sendMail({
+            from: cfg.user,
+            to,
+            cc,
+            subject,
+            text: text ?? '',
+            attachments,
         });
+        return {
+            account: name,
+            messageId: info.messageId,
+            accepted: info.accepted.map(String),
+            rejected: info.rejected.map(String),
+            response: info.response,
+        };
+    }
+}
+/** Stat every attachment path up front; total size must stay under the cap. */
+export async function validateAttachmentPaths(paths, maxBytes) {
+    const out = [];
+    let total = 0;
+    for (const path of paths) {
+        let info;
         try {
-            const info = await transporter.sendMail({
-                from: this.config.user,
-                to,
-                cc,
-                subject,
-                text: text ?? '',
-            });
-            return {
-                messageId: info.messageId,
-                accepted: info.accepted.map(String),
-                rejected: info.rejected.map(String),
-                response: info.response,
-            };
+            info = await stat(path);
         }
-        catch (error) {
-            const raw = messageOf(error, 'SMTP 发送失败');
-            throw new MailError(raw.toLowerCase().includes('auth') ? `SMTP 登录失败：${raw}（请检查 user 与授权码）` : raw);
+        catch {
+            throw new MailError('附件路径不存在或不可读：' + path);
         }
-        finally {
-            transporter.close();
+        if (!info.isFile())
+            throw new MailError('附件路径不是文件：' + path);
+        total += info.size;
+        if (total > maxBytes) {
+            throw new MailError('附件总大小超过上限 maxAttachmentBytes=' + maxBytes + ' 字节');
+        }
+        out.push({ path });
+    }
+    return out;
+}
+/** Drain a download stream into a Buffer with a hard byte cap. */
+async function collectStream(stream, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes)
+            throw new MailError('附件超过上限 maxAttachmentBytes=' + maxBytes + ' 字节，下载中止');
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+/** Avoid overwriting: append -1, -2, ... before the extension. */
+async function uniquePath(path) {
+    try {
+        await stat(path);
+    }
+    catch {
+        return path;
+    }
+    const dot = path.lastIndexOf('.');
+    const base = dot > 0 ? path.slice(0, dot) : path;
+    const ext = dot > 0 ? path.slice(dot) : '';
+    for (let i = 1; i < 1000; i++) {
+        const candidate = base + '-' + i + ext;
+        try {
+            await stat(candidate);
+        }
+        catch {
+            return candidate;
         }
     }
+    return base + '-' + Date.now() + ext;
 }

package/lib/parse.d.ts

@@ -6,5 +6,10 @@ export declare function truncateText(text: string, maxChars: number): {
     text: string;
     truncated: boolean;
 };
+/**
+ * Turn an untrusted attachment filename into a safe basename: no directory
+ * separators, no traversal, no control characters, bounded length.
+ */
+export declare function sanitizeFilename(raw: unknown, fallback?: string): string;
 /** Parse a raw RFC822 message source into the read-result body. */
 export declare function parseRawMessage(source: Buffer, maxBodyChars: number): Promise<ReadMessageBody>;

package/lib/parse.js

@@ -39,7 +39,24 @@ export function truncateText(text, maxChars) {
         return { text, truncated: false };
     const cut = text.slice(0, maxChars);
     const lastBreak = Math.max(cut.lastIndexOf('\n'), cut.lastIndexOf(' '), 0);
-    return { text: cut.slice(0, lastBreak) + `\n\n…[正文过长，已截断，共 ${text.length} 字符]`, truncated: true };
+    return { text: cut.slice(0, lastBreak) + '\n\n…[正文过长，已截断，共 ' + text.length + ' 字符]', truncated: true };
+}
+/**
+ * Turn an untrusted attachment filename into a safe basename: no directory
+ * separators, no traversal, no control characters, bounded length.
+ */
+export function sanitizeFilename(raw, fallback = 'attachment.bin') {
+    let name = String(raw ?? '').replace(/\\/g, '/').split('/').pop() ?? '';
+    // eslint-disable-next-line no-control-regex
+    name = name.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+    if (name === '' || name === '.' || name === '..')
+        name = fallback;
+    if (name.length > 120) {
+        const dot = name.lastIndexOf('.');
+        const ext = dot > 0 && dot >= name.length - 12 ? name.slice(dot) : '';
+        name = name.slice(0, 120 - ext.length) + ext;
+    }
+    return name;
 }
 /** Parse a raw RFC822 message source into the read-result body. */
 export async function parseRawMessage(source, maxBodyChars) {
@@ -49,6 +66,12 @@ export async function parseRawMessage(source, maxBodyChars) {
         text = stripHtml(parsed.html);
     }
     const limited = truncateText(text, maxBodyChars);
+    const attachments = (parsed.attachments ?? []).map((att, index) => ({
+        filename: att.filename ?? '(unnamed)',
+        contentType: att.contentType,
+        size: att.size,
+        part: 'attachment-' + index,
+    }));
     return {
         date: parsed.date instanceof Date ? parsed.date.toISOString() : '',
         from: flattenAddresses(parsed.from),
@@ -56,11 +79,7 @@ export async function parseRawMessage(source, maxBodyChars) {
         cc: flattenAddresses(parsed.cc),
         subject: parsed.subject ?? '',
         text: limited.text,
-        attachments: (parsed.attachments ?? []).map(att => ({
-            filename: att.filename ?? '(unnamed)',
-            contentType: att.contentType,
-            size: att.size,
-        })),
+        attachments,
         truncated: limited.truncated,
     };
 }

package/lib/types.d.ts

@@ -15,6 +15,14 @@ export interface ListedMessage {
     size: number;
     hasAttachments: boolean;
 }
+/** One attachment of a read message (metadata only). */
+export interface EmailAttachmentMeta {
+    filename: string;
+    contentType: string;
+    size: number;
+    /** IMAP body part identifier used by email_attachment. */
+    part: string;
+}
 /** One fully read message body. */
 export interface ReadMessageBody {
     date: string;
@@ -24,52 +32,86 @@ export interface ReadMessageBody {
     subject: string;
     /** Plain-text body; HTML mail is converted. Truncated at maxBodyChars. */
     text: string;
-    attachments: Array<{
-        filename: string;
-        contentType: string;
-        size: number;
-    }>;
+    attachments: EmailAttachmentMeta[];
     truncated: boolean;
 }
 export interface EmailListResult {
+    account: string;
     count: number;
     folder: string;
     messages: ListedMessage[];
 }
 export interface EmailReadResult extends ReadMessageBody {
+    account: string;
     uid: number;
     folder: string;
 }
 export interface EmailSearchResult {
+    account: string;
     query: string;
     count: number;
     folder: string;
     messages: ListedMessage[];
 }
 export interface EmailSendResult {
+    account: string;
     messageId: string;
     accepted: string[];
     rejected: string[];
     response: string;
 }
-export interface EmailListArgs {
+export interface EmailFolderRow {
+    name: string;
+    path: string;
+    specialUse: string;
+    subscribed: boolean;
+}
+export interface EmailFoldersResult {
+    account: string;
+    folders: EmailFolderRow[];
+}
+export interface EmailAttachmentResult {
+    account: string;
+    uid: number;
+    filename: string;
+    contentType: string;
+    size: number;
+    /** Absolute path the attachment was written to. */
+    path: string;
+}
+/** Every tool accepts an optional account selector. */
+export interface AccountArg {
+    account?: string;
+}
+export interface EmailListArgs extends AccountArg {
     folder?: string;
     limit?: number;
     offset?: number;
     unreadOnly?: boolean;
 }
-export interface EmailReadArgs {
+export interface EmailReadArgs extends AccountArg {
     uid: number;
     folder?: string;
 }
-export interface EmailSearchArgs {
+export interface EmailSearchArgs extends AccountArg {
     query: string;
     folder?: string;
     limit?: number;
 }
-export interface EmailSendArgs {
+export interface EmailSendArgs extends AccountArg {
     to: string;
     subject: string;
     text?: string;
     cc?: string;
+    /** Absolute paths (or paths relative to the dsh process cwd) to attach. */
+    attachments?: string[];
+}
+export interface EmailFoldersArgs extends AccountArg {
+    subscribedOnly?: boolean;
+}
+export interface EmailAttachmentArgs extends AccountArg {
+    uid: number;
+    /** 0-based index into the attachments of email_read. Default 0. */
+    index?: number;
+    folder?: string;
 }