pi-tsgw 1.5.2 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -1
- package/extensions/email/body.ts +179 -0
- package/extensions/email/cache.ts +94 -0
- package/extensions/email/config.ts +277 -0
- package/extensions/email/file-access.ts +32 -0
- package/extensions/email/imap-session.ts +86 -0
- package/extensions/email/index.ts +23 -0
- package/extensions/email/message.ts +18 -0
- package/extensions/email/mutations.ts +307 -0
- package/extensions/email/query.ts +68 -0
- package/extensions/email/reader.ts +150 -0
- package/extensions/email/runtime.ts +25 -0
- package/extensions/email/schema.ts +65 -0
- package/extensions/email/smtp.ts +199 -0
- package/extensions/email/tools.ts +100 -0
- package/extensions/email/types.ts +71 -0
- package/extensions/provider/config.ts +2 -2
- package/index.ts +2 -0
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# pi-tsgw
|
|
2
2
|
|
|
3
|
-
自用的 Pi 扩展,为 TOSSP AIH gateway
|
|
3
|
+
自用的 Pi 扩展,为 TOSSP AIH gateway 提供模型目录、请求适配、联网搜索、图片生成与编辑、分类模型及配套工作流,并提供可选的 IMAP/SMTP 邮件组件。以 MIT 许可证公开。
|
|
4
4
|
|
|
5
5
|
## 安装
|
|
6
6
|
|
|
@@ -29,4 +29,38 @@ pi install npm:pi-tsgw
|
|
|
29
29
|
|
|
30
30
|
`/insagent` 显式安装标准子代理:覆盖当前定义,删除已退出清单的 `tsgw-*.md`,在代理目录的 `settings.json` 中启用 Agent 并停用 Pi Web 内置代理,最后自动重载当前会话;其他自定义代理和无关设置保留。
|
|
31
31
|
|
|
32
|
+
## 可选邮件配置
|
|
33
|
+
|
|
34
|
+
邮件能力需要 Pi 1.2+。在宿主用户目录新增独立的 `tsgw-email.json`(权限 `0600`),然后 `/reload`;文件不存在就不注册邮件能力。以下地址与密码均为占位内容,`imap`、`smtp` 都支持任意多个自定义 ID:
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"imap": {
|
|
39
|
+
"inbound": {
|
|
40
|
+
"host": "imap.example.invalid",
|
|
41
|
+
"port": 993,
|
|
42
|
+
"tls": "implicit",
|
|
43
|
+
"user": "<登录账号>",
|
|
44
|
+
"password": "<应用密码>",
|
|
45
|
+
"trashMailbox": "<回收站完整路径>",
|
|
46
|
+
"junkMailbox": "<垃圾邮件箱完整路径>"
|
|
47
|
+
}
|
|
48
|
+
},
|
|
49
|
+
"smtp": {
|
|
50
|
+
"outbound": {
|
|
51
|
+
"host": "smtp.example.invalid",
|
|
52
|
+
"port": 587,
|
|
53
|
+
"tls": "starttls",
|
|
54
|
+
"user": "<登录账号>",
|
|
55
|
+
"password": "<应用密码>",
|
|
56
|
+
"fromAddress": "sender@example.invalid",
|
|
57
|
+
"allowSenderOverride": false
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
"defaultSmtp": "outbound"
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`implicit` 表示连接即 TLS;`starttls` 必须成功升级 TLS,均校验证书。SMTP 可选 `fromName` 和 `envelopeFrom`;未配置后者时信封发件人跟随最终 From。邮件工具统一 `tsgw_email_` 前缀,通过 codemode 的 `describeNamespace("tsgw_email")` 按需发现,不直接声明或内联到模型上下文。无后台同步、磁盘缓存、自动重发、出口切换或发送后存档;读取不自动标已读。附件仅允许当前工作目录或系统临时目录,不允许访问宿主配置目录,符号链接按真实路径校验。超出读取预算、原始头部不是合法 UTF-8,或 inline 文本附件会被库转换字符集/flowed 格式时,会明确报告,不把截断或改写内容当作完整原文。
|
|
65
|
+
|
|
32
66
|
开发维护约定见 [AGENTS.md](https://github.com/tossp/pi-tsgw/blob/main/AGENTS.md)。
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
2
|
+
import { TextDecoder } from "node:util";
|
|
3
|
+
import { compile } from "html-to-text";
|
|
4
|
+
import type { ImapFlow, MessageStructureObject } from "imapflow";
|
|
5
|
+
import { EmailCache } from "./cache.ts";
|
|
6
|
+
import { messageCacheKey } from "./message.ts";
|
|
7
|
+
import { EmailError, type ReadInput } from "./types.ts";
|
|
8
|
+
|
|
9
|
+
const BODY_BUDGET = 8 * 1024 * 1024;
|
|
10
|
+
const htmlText = compile({
|
|
11
|
+
wordwrap: false,
|
|
12
|
+
// 输入已受读取预算约束;禁止转换器另行静默截断并向 stderr 写入信息。
|
|
13
|
+
limits: { maxInputLength: undefined },
|
|
14
|
+
selectors: [
|
|
15
|
+
{ selector: "table", format: "dataTable", options: { uppercaseHeaderCells: false, maxColumnWidth: undefined } },
|
|
16
|
+
{ selector: "img", format: "skip" },
|
|
17
|
+
{ selector: "script", format: "skip" },
|
|
18
|
+
{ selector: "style", format: "skip" },
|
|
19
|
+
{ selector: "iframe", format: "skip" },
|
|
20
|
+
],
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
/** MIME 树来自 ImapFlow 的 BODYSTRUCTURE 解析;related 的其他子项不是正文版本。 */
|
|
24
|
+
function bodyCandidates(node: MessageStructureObject | undefined, allGroups = false): MessageStructureObject[] {
|
|
25
|
+
if (!node) return [];
|
|
26
|
+
if (node.disposition?.trim().toLowerCase() === "attachment" || node.dispositionParameters?.filename || node.parameters?.name)
|
|
27
|
+
return [];
|
|
28
|
+
const type = node.type.trim().toLowerCase();
|
|
29
|
+
if (type === "message/rfc822") return [];
|
|
30
|
+
const children = node.childNodes ?? [];
|
|
31
|
+
if (type === "multipart/related") {
|
|
32
|
+
const start = node.parameters?.start;
|
|
33
|
+
const root = start ? children.find(child => child.id === start) : children[0];
|
|
34
|
+
return root ? bodyCandidates(root, allGroups) : [node];
|
|
35
|
+
}
|
|
36
|
+
if (type === "multipart/alternative") return [...children].reverse().flatMap(child => bodyCandidates(child, allGroups));
|
|
37
|
+
if (type.startsWith("multipart/")) {
|
|
38
|
+
// mixed 中的后续内联文本可能是页脚,不能拿它替换或拼接首个正文组。
|
|
39
|
+
const groups = children.filter(child => {
|
|
40
|
+
const kind = child.type.trim().toLowerCase();
|
|
41
|
+
return allGroups || kind.startsWith("text/") || kind.startsWith("multipart/");
|
|
42
|
+
}).map(child => ({ node: child, candidates: bodyCandidates(child, allGroups) })).filter(group => group.candidates.length > 0);
|
|
43
|
+
// 判定全信为空时还需核对未被选作主正文的其他组,不能以空版本代表全信。
|
|
44
|
+
if (allGroups) return groups.flatMap(group => group.candidates);
|
|
45
|
+
const primary = groups[0];
|
|
46
|
+
if (!primary) return [node];
|
|
47
|
+
// 兼容既有 mixed 下直接放 plain/html 的邮件;不能跨嵌套正文组寻找其他版本。
|
|
48
|
+
if (primary.node.type.trim().toLowerCase() !== "text/plain") return primary.candidates;
|
|
49
|
+
const html = groups.find(group => group.node.type.trim().toLowerCase() === "text/html");
|
|
50
|
+
return html ? [...primary.candidates, ...html.candidates] : primary.candidates;
|
|
51
|
+
}
|
|
52
|
+
return [node];
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function partNumber(node: MessageStructureObject, root: MessageStructureObject | undefined): string | undefined {
|
|
56
|
+
return node.part || (node === root && !node.childNodes?.length ? "1" : undefined);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** 解码交给现有 ImapFlow(libmime/mailsplit),不重新实现 MIME、传输编码或字符集。 */
|
|
60
|
+
async function decodedPart(client: ImapFlow, input: ReadInput, node: MessageStructureObject, part: string,
|
|
61
|
+
cache: EmailCache, signal?: AbortSignal): Promise<{ text: string; cacheHit: boolean }> {
|
|
62
|
+
if (node.size === undefined || !Number.isFinite(node.size) || node.size < 0)
|
|
63
|
+
throw new EmailError("BODY_SIZE_UNKNOWN", "正文 MIME 部分缺少可靠大小,无法确认读取完整性。");
|
|
64
|
+
if (node.size > BODY_BUDGET) throw new EmailError("BODY_TOO_LARGE", "正文 MIME 部分超过读取预算,未返回截断内容。");
|
|
65
|
+
const key = messageCacheKey(input, `body:${part}`);
|
|
66
|
+
const hit = cache.get(key);
|
|
67
|
+
if (typeof hit === "string") return { text: hit, cacheHit: true };
|
|
68
|
+
const download = await client.download(String(input.uid), part, { uid: true, maxBytes: BODY_BUDGET + 1 });
|
|
69
|
+
if (!download.content) throw new EmailError("PART_MISSING", "服务器未返回指定正文 MIME 部分。");
|
|
70
|
+
const encoding = download.meta.encoding?.trim().toLowerCase();
|
|
71
|
+
if (encoding && !["7bit", "8bit", "binary", "base64", "quoted-printable"].includes(encoding)) {
|
|
72
|
+
download.content.destroy();
|
|
73
|
+
throw new EmailError("UNSUPPORTED_TRANSFER_ENCODING", "正文传输编码不支持,未将编码内容冒充可读文字。");
|
|
74
|
+
}
|
|
75
|
+
const charset = download.meta.charset?.toLowerCase().replace(/[^a-z0-9]+/g, "");
|
|
76
|
+
if (charset && !["ascii", "usascii", "utf8"].includes(charset)) {
|
|
77
|
+
download.content.destroy();
|
|
78
|
+
throw new EmailError("UNSUPPORTED_CHARSET", "正文字符集无法识别,未将原始字节冒充可读文字。");
|
|
79
|
+
}
|
|
80
|
+
const chunks: Buffer[] = [];
|
|
81
|
+
let bytes = 0;
|
|
82
|
+
const abort = () => download.content.destroy(new EmailError("CANCELLED", "邮件读取已取消。"));
|
|
83
|
+
signal?.addEventListener("abort", abort, { once: true });
|
|
84
|
+
try {
|
|
85
|
+
signal?.throwIfAborted();
|
|
86
|
+
for await (const chunk of download.content) {
|
|
87
|
+
signal?.throwIfAborted();
|
|
88
|
+
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
|
|
89
|
+
bytes += buffer.length;
|
|
90
|
+
if (bytes > BODY_BUDGET) throw new EmailError("BODY_TOO_LARGE", "正文解码后超过读取预算,未返回截断内容。");
|
|
91
|
+
chunks.push(buffer);
|
|
92
|
+
}
|
|
93
|
+
} finally { signal?.removeEventListener("abort", abort); }
|
|
94
|
+
let text: string;
|
|
95
|
+
try { text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks, bytes)); }
|
|
96
|
+
catch { throw new EmailError("BODY_DECODE_FAILED", "正文解码结果不是合法 UTF-8,无法提取可靠文字。"); }
|
|
97
|
+
cache.set(key, text, "content");
|
|
98
|
+
return { text, cacheHit: false };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export async function readMessageBody(client: ImapFlow, input: ReadInput, root: MessageStructureObject | undefined,
|
|
102
|
+
cache: EmailCache, signal?: AbortSignal): Promise<Record<string, unknown>> {
|
|
103
|
+
const candidates = bodyCandidates(root);
|
|
104
|
+
const htmlAvailable = candidates.some(node => node.type.trim().toLowerCase() === "text/html");
|
|
105
|
+
const supported = candidates.filter(node => ["text/plain", "text/html"].includes(node.type.trim().toLowerCase()));
|
|
106
|
+
if (input.refresh) for (const node of supported) {
|
|
107
|
+
const part = partNumber(node, root);
|
|
108
|
+
if (part) cache.delete(messageCacheKey(input, `body:${part}`));
|
|
109
|
+
}
|
|
110
|
+
const ordered = input.format === "html" ? supported.filter(node => node.type.trim().toLowerCase() === "text/html") :
|
|
111
|
+
[...supported.filter(node => node.type.trim().toLowerCase() === "text/plain"),
|
|
112
|
+
...supported.filter(node => node.type.trim().toLowerCase() === "text/html")];
|
|
113
|
+
const base = { body: null, bodySource: null, contentType: null, bodyFormat: input.format ?? "text",
|
|
114
|
+
nextOffset: null, truncated: false, cacheHit: false, htmlAvailable };
|
|
115
|
+
const reasons: { code: string; reason: string; part?: string }[] = [];
|
|
116
|
+
let emptyParts = 0;
|
|
117
|
+
let last: Record<string, unknown> = {};
|
|
118
|
+
for (const node of ordered) {
|
|
119
|
+
const type = node.type.trim().toLowerCase();
|
|
120
|
+
const part = partNumber(node, root);
|
|
121
|
+
last = { part, contentType: type };
|
|
122
|
+
if (!part || !/^\d+(?:\.\d+)*$/.test(part)) {
|
|
123
|
+
reasons.push({ code: "BODY_STRUCTURE_INVALID", reason: "正文 MIME 部分缺少有效编号。" });
|
|
124
|
+
continue;
|
|
125
|
+
}
|
|
126
|
+
try {
|
|
127
|
+
const decoded = await decodedPart(client, input, node, part, cache, signal);
|
|
128
|
+
if (decoded.text.length === 0 && node.size === 0) { emptyParts++; continue; }
|
|
129
|
+
const body = type === "text/html" && input.format !== "html" ? htmlText(decoded.text) : decoded.text;
|
|
130
|
+
if (!body.trim()) {
|
|
131
|
+
reasons.push({ code: "BODY_NO_TEXT", reason: "正文部件非空,但只有空白或无法提取可读文字。", part });
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
const { start, end } = bodyPage(body, input.offset ?? 0, input.maxChars ?? 32768);
|
|
135
|
+
const truncated = end < body.length;
|
|
136
|
+
return { ...base, ...last, bodyStatus: "success", bodySource: type, body: body.slice(start, end),
|
|
137
|
+
offset: start, totalChars: body.length, nextOffset: truncated ? end : null, truncated, cacheHit: decoded.cacheHit,
|
|
138
|
+
message: truncated ? "正文输出已截断,请用 continuation 继续读取当前版本。" : "已提取当前正文版本。",
|
|
139
|
+
pagination: "offset/nextOffset 为 UTF-16 单元;边界按完整 Unicode 字符调整,请用返回的 nextOffset 翻页。",
|
|
140
|
+
...(truncated ? { continuation: { ...input, offset: end, refresh: false } } : {}),
|
|
141
|
+
...(type === "text/plain" && htmlAvailable ? {
|
|
142
|
+
htmlAlternative: { ...input, format: "html", offset: 0, refresh: false },
|
|
143
|
+
versionNotice: "仅提取了纯文本版本,未比较 HTML;若当前内容只有页脚,请按 htmlAlternative 读取 HTML 版本,不能据此断言整封邮件信息已完整读取。",
|
|
144
|
+
} : {}),
|
|
145
|
+
...(reasons.length ? { warnings: reasons } : {}),
|
|
146
|
+
};
|
|
147
|
+
} catch (error) {
|
|
148
|
+
if (signal?.aborted) throw error;
|
|
149
|
+
reasons.push({ code: error instanceof EmailError ? error.code : "BODY_PARSE_FAILED",
|
|
150
|
+
reason: error instanceof EmailError ? error.message : "正文 MIME 下载、解析或 HTML 转换失败,未返回不完整文字。", part });
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
if (ordered.length > 0 && emptyParts === ordered.length && ordered.length === candidates.length &&
|
|
154
|
+
bodyCandidates(root, true).every(node => node.size === 0 && ["text/plain", "text/html"].includes(node.type.trim().toLowerCase())))
|
|
155
|
+
return { ...base, ...last, body: "", bodyStatus: "empty", totalChars: 0, message: "邮件正文为空" };
|
|
156
|
+
if (emptyParts > 0 && !reasons.length)
|
|
157
|
+
reasons.push({ code: "BODY_EMPTY_VERSION", reason: "所选正文版本为空,但其他正文内容尚未确认为空,不能判定整封邮件正文为空。" });
|
|
158
|
+
const unsupported = candidates.filter(node => !supported.includes(node)).map(node => node.type);
|
|
159
|
+
if (input.format !== "html" && unsupported.length)
|
|
160
|
+
reasons.push({ code: "BODY_UNSUPPORTED", reason: `正文 MIME 类型不支持或结构无法提取:${unsupported.join("、")}。` });
|
|
161
|
+
if (!ordered.length && !reasons.length) reasons.push({ code: "BODY_UNSUPPORTED", reason: input.format === "html" ? "没有可读取的 HTML 正文版本。" :
|
|
162
|
+
"缺少可确认的正文结构,不能判定原始正文为空。" });
|
|
163
|
+
return { ...base, ...last, bodyStatus: "unreadable", message: "无法读取邮件正文", reasons,
|
|
164
|
+
...(reasons.some(reason => reason.code === "BODY_TOO_LARGE") ? { bodyTooLarge: true, budgetBytes: BODY_BUDGET,
|
|
165
|
+
guidance: "可通过已有 attachment 工具显式导出返回的 part;转换型文本仍受该工具的无损导出限制。" } : {}),
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** offset/nextOffset 是 UTF-16 单元;页边界不能落在合法代理对中间。 */
|
|
170
|
+
function bodyPage(body: string, offset: number, maxChars: number): { start: number; end: number } {
|
|
171
|
+
const splitsPair = (at: number) => at > 0 && at < body.length &&
|
|
172
|
+
body.charCodeAt(at - 1) >= 0xd800 && body.charCodeAt(at - 1) <= 0xdbff &&
|
|
173
|
+
body.charCodeAt(at) >= 0xdc00 && body.charCodeAt(at) <= 0xdfff;
|
|
174
|
+
let start = Math.min(offset, body.length);
|
|
175
|
+
if (splitsPair(start)) start--;
|
|
176
|
+
let end = Math.min(body.length, start + maxChars);
|
|
177
|
+
if (splitsPair(end)) end += end - start === 1 ? 1 : -1;
|
|
178
|
+
return { start, end };
|
|
179
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
2
|
+
|
|
3
|
+
export const EMAIL_CACHE_MAX_BYTES = 128 * 1024 * 1024;
|
|
4
|
+
export const EMAIL_CACHE_MAX_ENTRY_BYTES = 8 * 1024 * 1024;
|
|
5
|
+
export const EMAIL_CACHE_STATE_TTL_MS = 30_000;
|
|
6
|
+
export const EMAIL_CACHE_CONTENT_TTL_MS = 10 * 60_000;
|
|
7
|
+
export const EMAIL_CACHE_SWEEP_MS = 60_000;
|
|
8
|
+
|
|
9
|
+
export type EmailCacheValue = string | Buffer;
|
|
10
|
+
export type EmailCacheKind = "state" | "content";
|
|
11
|
+
|
|
12
|
+
interface Entry {
|
|
13
|
+
value: EmailCacheValue;
|
|
14
|
+
bytes: number;
|
|
15
|
+
expiresAt: number;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** 单个邮件会话持有;不落盘、不共享,也不在模块加载时启动计时器。 */
|
|
19
|
+
export class EmailCache {
|
|
20
|
+
private readonly entries = new Map<string, Entry>();
|
|
21
|
+
private readonly maxBytes: number;
|
|
22
|
+
private readonly maxEntryBytes: number;
|
|
23
|
+
private timer: ReturnType<typeof setInterval> | undefined;
|
|
24
|
+
private usedBytes = 0;
|
|
25
|
+
|
|
26
|
+
constructor(options: { maxBytes?: number; maxEntryBytes?: number } = {}) {
|
|
27
|
+
this.maxBytes = options.maxBytes ?? EMAIL_CACHE_MAX_BYTES;
|
|
28
|
+
this.maxEntryBytes = options.maxEntryBytes ?? EMAIL_CACHE_MAX_ENTRY_BYTES;
|
|
29
|
+
this.timer = setInterval(() => this.sweepExpired(), EMAIL_CACHE_SWEEP_MS);
|
|
30
|
+
this.timer.unref();
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
get size(): number { return this.entries.size; }
|
|
34
|
+
get bytes(): number { return this.usedBytes; }
|
|
35
|
+
|
|
36
|
+
get(key: string): EmailCacheValue | undefined {
|
|
37
|
+
const entry = this.entries.get(key);
|
|
38
|
+
if (!entry) return undefined;
|
|
39
|
+
if (entry.expiresAt <= Date.now()) {
|
|
40
|
+
this.delete(key);
|
|
41
|
+
return undefined;
|
|
42
|
+
}
|
|
43
|
+
this.entries.delete(key);
|
|
44
|
+
this.entries.set(key, entry);
|
|
45
|
+
return entry.value;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
set(key: string, value: EmailCacheValue, kind: EmailCacheKind = "content"): boolean {
|
|
49
|
+
if (!this.timer) return false;
|
|
50
|
+
this.delete(key);
|
|
51
|
+
const valueBytes = typeof value === "string" ? value.length * 2 : value.byteLength;
|
|
52
|
+
// 字符串按 UTF-16 计费,另计键与条目开销;这是容量估算,不是进程堆内存硬限额。
|
|
53
|
+
const bytes = valueBytes + key.length * 2 + 128;
|
|
54
|
+
if (valueBytes > this.maxEntryBytes || bytes > this.maxBytes) return false;
|
|
55
|
+
const now = Date.now();
|
|
56
|
+
if (this.usedBytes + bytes > this.maxBytes) this.sweepExpired(now);
|
|
57
|
+
while (this.usedBytes + bytes > this.maxBytes) {
|
|
58
|
+
this.delete(this.entries.keys().next().value!);
|
|
59
|
+
}
|
|
60
|
+
this.entries.set(key, {
|
|
61
|
+
// 不让小切片把调用方的大缓冲区一直保留在缓存里。
|
|
62
|
+
value: typeof value === "string" ? value : Buffer.from(value),
|
|
63
|
+
bytes,
|
|
64
|
+
expiresAt: now + (kind === "state" ? EMAIL_CACHE_STATE_TTL_MS : EMAIL_CACHE_CONTENT_TTL_MS),
|
|
65
|
+
});
|
|
66
|
+
this.usedBytes += bytes;
|
|
67
|
+
return true;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
delete(key: string): boolean {
|
|
71
|
+
const entry = this.entries.get(key);
|
|
72
|
+
if (!entry) return false;
|
|
73
|
+
this.entries.delete(key);
|
|
74
|
+
this.usedBytes -= entry.bytes;
|
|
75
|
+
return true;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
clear(): void {
|
|
79
|
+
this.entries.clear();
|
|
80
|
+
this.usedBytes = 0;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
dispose(): void {
|
|
84
|
+
clearInterval(this.timer);
|
|
85
|
+
this.timer = undefined;
|
|
86
|
+
this.clear();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
private sweepExpired(now = Date.now()): void {
|
|
90
|
+
for (const [key, entry] of this.entries) {
|
|
91
|
+
if (entry.expiresAt <= now) this.delete(key);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
import { getAgentDir } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { readFileSync, statSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* 邮件配置只读取宿主 agent 目录下的 `tsgw-email.json`。
|
|
7
|
+
* 文件不存在表示邮件功能关闭;配置无效时只让邮件不可用,不抛错影响其他功能。
|
|
8
|
+
* 文件与返回值都含明文凭据:调用方不得普通记录 ready 的 config 或原始文件内容。
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
export type EmailTls = "implicit" | "starttls";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* IMAP 账户。字段平铺,不设 address/inbox/auth 嵌套。
|
|
15
|
+
* `trashMailbox`、`junkMailbox` 按原样保留(不 trim、不改大小写),仅要求不是 INBOX。
|
|
16
|
+
*/
|
|
17
|
+
export interface ImapAccountConfig {
|
|
18
|
+
host: string;
|
|
19
|
+
port: number;
|
|
20
|
+
tls: EmailTls;
|
|
21
|
+
user: string;
|
|
22
|
+
password: string;
|
|
23
|
+
trashMailbox: string;
|
|
24
|
+
junkMailbox: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* SMTP 账户。字段平铺;`fromName`、`envelopeFrom` 仅在配置了才出现,
|
|
29
|
+
* `allowSenderOverride` 缺省为 false。
|
|
30
|
+
*/
|
|
31
|
+
export interface SmtpConfig {
|
|
32
|
+
host: string;
|
|
33
|
+
port: number;
|
|
34
|
+
tls: EmailTls;
|
|
35
|
+
user: string;
|
|
36
|
+
password: string;
|
|
37
|
+
fromAddress: string;
|
|
38
|
+
fromName?: string;
|
|
39
|
+
allowSenderOverride: boolean;
|
|
40
|
+
envelopeFrom?: string;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** 顶层 `imap`、`smtp` 是账户 ID 映射;`defaultSmtp` 必须是 `smtp` 的自有键。 */
|
|
44
|
+
export interface EmailConfig {
|
|
45
|
+
imap: Record<string, ImapAccountConfig>;
|
|
46
|
+
smtp: Record<string, SmtpConfig>;
|
|
47
|
+
defaultSmtp: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const CONFIG_FILE = "tsgw-email.json";
|
|
51
|
+
const IMAP_FIELDS = [
|
|
52
|
+
"host",
|
|
53
|
+
"port",
|
|
54
|
+
"tls",
|
|
55
|
+
"user",
|
|
56
|
+
"password",
|
|
57
|
+
"trashMailbox",
|
|
58
|
+
"junkMailbox",
|
|
59
|
+
] as const;
|
|
60
|
+
const SMTP_FIELDS = [
|
|
61
|
+
"host",
|
|
62
|
+
"port",
|
|
63
|
+
"tls",
|
|
64
|
+
"user",
|
|
65
|
+
"password",
|
|
66
|
+
"fromAddress",
|
|
67
|
+
"fromName",
|
|
68
|
+
"allowSenderOverride",
|
|
69
|
+
"envelopeFrom",
|
|
70
|
+
] as const;
|
|
71
|
+
const ROOT_FIELDS = ["imap", "smtp", "defaultSmtp"] as const;
|
|
72
|
+
|
|
73
|
+
// 控制字符会污染邮件头或日志,凭据以外的一切字符串都在入口拒绝。
|
|
74
|
+
const CONTROL = /[\u0000-\u001f\u007f]/;
|
|
75
|
+
// 只做基础格式与头注入防护,不实现 RFC 5322 解析器。
|
|
76
|
+
const ADDRESS_FORBIDDEN = /[\s<>(),;:\\"[\]]/;
|
|
77
|
+
|
|
78
|
+
/** 内部错误类型:`readEmailConfig` 只向调用方转发本类型的安全消息。 */
|
|
79
|
+
class EmailConfigError extends Error {}
|
|
80
|
+
|
|
81
|
+
function fail(message: string): never {
|
|
82
|
+
throw new EmailConfigError(`邮件配置无效:${message}`);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
86
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
87
|
+
const prototype = Object.getPrototypeOf(value);
|
|
88
|
+
return prototype === Object.prototype || prototype === null;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function rejectUnknownFields(
|
|
92
|
+
value: Record<string, unknown>,
|
|
93
|
+
allowed: readonly string[],
|
|
94
|
+
where: string,
|
|
95
|
+
): void {
|
|
96
|
+
for (const key of Object.keys(value))
|
|
97
|
+
if (!allowed.includes(key)) fail(`${where}包含不支持的字段。`);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** 非空字符串;`password` 之外的字段额外拒绝控制字符。 */
|
|
101
|
+
function stringField(
|
|
102
|
+
source: Record<string, unknown>,
|
|
103
|
+
key: string,
|
|
104
|
+
where: string,
|
|
105
|
+
options: { secret?: boolean } = {},
|
|
106
|
+
): string {
|
|
107
|
+
const value = source[key];
|
|
108
|
+
if (typeof value !== "string" || value.length === 0)
|
|
109
|
+
fail(`${where}的 ${key} 必须是非空字符串。`);
|
|
110
|
+
// 凭据按原样保留,其余字段拒绝会破坏头部或日志的控制字符。
|
|
111
|
+
if (!options.secret && CONTROL.test(value))
|
|
112
|
+
fail(`${where}的 ${key} 不能包含控制字符。`);
|
|
113
|
+
return value;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function portField(source: Record<string, unknown>, key: string, where: string): number {
|
|
117
|
+
const value = source[key];
|
|
118
|
+
if (!Number.isInteger(value) || (value as number) < 1 || (value as number) > 65535)
|
|
119
|
+
fail(`${where}的 ${key} 必须是 1 到 65535 之间的整数。`);
|
|
120
|
+
return value as number;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function tlsField(source: Record<string, unknown>, key: string, where: string): EmailTls {
|
|
124
|
+
const value = source[key];
|
|
125
|
+
if (value !== "implicit" && value !== "starttls")
|
|
126
|
+
fail(`${where}的 ${key} 必须是 "implicit" 或 "starttls"。`);
|
|
127
|
+
return value;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function booleanField(source: Record<string, unknown>, key: string, where: string): boolean {
|
|
131
|
+
const value = source[key];
|
|
132
|
+
if (typeof value !== "boolean") fail(`${where}的 ${key} 必须是布尔值。`);
|
|
133
|
+
return value;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** 特殊用途文件夹使用服务器上的精确路径,不猜名称、不改写路径。 */
|
|
137
|
+
function mailboxField(source: Record<string, unknown>, key: string, where: string): string {
|
|
138
|
+
const value = stringField(source, key, where);
|
|
139
|
+
if (value.toUpperCase() === "INBOX") fail(`${where}的 ${key} 不能是 INBOX。`);
|
|
140
|
+
return value;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** 基础邮件地址校验:恰一个 @、两侧非空、无空白/控制/分隔符;允许内部域名。 */
|
|
144
|
+
function addressField(source: Record<string, unknown>, key: string, where: string): string {
|
|
145
|
+
const value = stringField(source, key, where);
|
|
146
|
+
const at = value.indexOf("@");
|
|
147
|
+
const domain = at < 0 ? "" : value.slice(at + 1);
|
|
148
|
+
if (at <= 0 || at !== value.lastIndexOf("@") || domain.length === 0
|
|
149
|
+
|| ADDRESS_FORBIDDEN.test(value))
|
|
150
|
+
fail(`${where}的 ${key} 必须是基础格式的邮件地址。`);
|
|
151
|
+
return value;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function accountWhere(channel: string, index: number): string {
|
|
155
|
+
return `${channel} 第 ${index + 1} 个账户`;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function checkAccountId(channel: string, index: number, id: string): void {
|
|
159
|
+
if (id.length === 0 || CONTROL.test(id))
|
|
160
|
+
fail(`${channel} 第 ${index + 1} 个账户的 ID 必须是非空且不含控制字符的字符串。`);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function parseImapAccounts(raw: unknown): Record<string, ImapAccountConfig> {
|
|
164
|
+
if (!isRecord(raw)) fail("imap 必须是账户 ID 到账户配置的映射对象。");
|
|
165
|
+
const ids = Object.keys(raw);
|
|
166
|
+
if (ids.length === 0) fail("imap 至少需要一个账户。");
|
|
167
|
+
const entries: [string, ImapAccountConfig][] = [];
|
|
168
|
+
for (const [index, id] of ids.entries()) {
|
|
169
|
+
checkAccountId("imap", index, id);
|
|
170
|
+
const where = accountWhere("imap", index);
|
|
171
|
+
const value = raw[id];
|
|
172
|
+
if (!isRecord(value)) fail(`${where}必须是对象。`);
|
|
173
|
+
rejectUnknownFields(value, IMAP_FIELDS, where);
|
|
174
|
+
const account: ImapAccountConfig = {
|
|
175
|
+
host: stringField(value, "host", where),
|
|
176
|
+
port: portField(value, "port", where),
|
|
177
|
+
tls: tlsField(value, "tls", where),
|
|
178
|
+
user: stringField(value, "user", where),
|
|
179
|
+
password: stringField(value, "password", where, { secret: true }),
|
|
180
|
+
trashMailbox: mailboxField(value, "trashMailbox", where),
|
|
181
|
+
junkMailbox: mailboxField(value, "junkMailbox", where),
|
|
182
|
+
};
|
|
183
|
+
if (account.trashMailbox === account.junkMailbox)
|
|
184
|
+
fail(`${where}的 trashMailbox 与 junkMailbox 不能相同。`);
|
|
185
|
+
entries.push([id, account]);
|
|
186
|
+
}
|
|
187
|
+
return Object.fromEntries(entries);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function parseSmtpConfigs(raw: unknown): Record<string, SmtpConfig> {
|
|
191
|
+
if (!isRecord(raw)) fail("smtp 必须是账户 ID 到账户配置的映射对象。");
|
|
192
|
+
const ids = Object.keys(raw);
|
|
193
|
+
if (ids.length === 0) fail("smtp 至少需要一个账户。");
|
|
194
|
+
const entries: [string, SmtpConfig][] = [];
|
|
195
|
+
for (const [index, id] of ids.entries()) {
|
|
196
|
+
checkAccountId("smtp", index, id);
|
|
197
|
+
const where = accountWhere("smtp", index);
|
|
198
|
+
const value = raw[id];
|
|
199
|
+
if (!isRecord(value)) fail(`${where}必须是对象。`);
|
|
200
|
+
rejectUnknownFields(value, SMTP_FIELDS, where);
|
|
201
|
+
const config: SmtpConfig = {
|
|
202
|
+
host: stringField(value, "host", where),
|
|
203
|
+
port: portField(value, "port", where),
|
|
204
|
+
tls: tlsField(value, "tls", where),
|
|
205
|
+
user: stringField(value, "user", where),
|
|
206
|
+
password: stringField(value, "password", where, { secret: true }),
|
|
207
|
+
fromAddress: addressField(value, "fromAddress", where),
|
|
208
|
+
allowSenderOverride: "allowSenderOverride" in value
|
|
209
|
+
? booleanField(value, "allowSenderOverride", where)
|
|
210
|
+
: false,
|
|
211
|
+
};
|
|
212
|
+
if ("fromName" in value) config.fromName = stringField(value, "fromName", where);
|
|
213
|
+
if ("envelopeFrom" in value) config.envelopeFrom = addressField(value, "envelopeFrom", where);
|
|
214
|
+
entries.push([id, config]);
|
|
215
|
+
}
|
|
216
|
+
return Object.fromEntries(entries);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* 解析并校验邮件配置值。非法时抛出不含字段值的安全中文错误,
|
|
221
|
+
* 合法的凭据按原样保留,不做 trim、大小写或编码转换。
|
|
222
|
+
*/
|
|
223
|
+
export function parseEmailConfig(raw: unknown): EmailConfig {
|
|
224
|
+
if (!isRecord(raw)) fail("顶层必须是 JSON 对象。");
|
|
225
|
+
rejectUnknownFields(raw, ROOT_FIELDS, "顶层");
|
|
226
|
+
const imap = parseImapAccounts(raw.imap);
|
|
227
|
+
const smtp = parseSmtpConfigs(raw.smtp);
|
|
228
|
+
const defaultSmtp = raw.defaultSmtp;
|
|
229
|
+
if (typeof defaultSmtp !== "string" || defaultSmtp.length === 0)
|
|
230
|
+
fail("defaultSmtp 必须是已定义 SMTP 账户的 ID。");
|
|
231
|
+
// 用自有键判断,避免 toString、constructor 等原型属性冒充已定义账户。
|
|
232
|
+
if (!Object.hasOwn(smtp, defaultSmtp))
|
|
233
|
+
fail("defaultSmtp 必须是 smtp 中已定义的账户 ID。");
|
|
234
|
+
return { imap, smtp, defaultSmtp };
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/**
|
|
238
|
+
* 读取宿主 agent 目录中的邮件配置(测试可显式传入 agentDir)。
|
|
239
|
+
* 只读批准文件:不创建目录或文件、不扫描旧配置、不迁移凭据、不联网。
|
|
240
|
+
*/
|
|
241
|
+
export function readEmailConfig(agentDir?: string):
|
|
242
|
+
| { status: "disabled" }
|
|
243
|
+
| { status: "invalid"; message: string }
|
|
244
|
+
| { status: "ready"; config: EmailConfig } {
|
|
245
|
+
let path: string;
|
|
246
|
+
try {
|
|
247
|
+
path = join(agentDir ?? getAgentDir(), CONFIG_FILE);
|
|
248
|
+
} catch {
|
|
249
|
+
return { status: "invalid", message: "无法定位邮件配置文件。" };
|
|
250
|
+
}
|
|
251
|
+
let text: string;
|
|
252
|
+
try {
|
|
253
|
+
const stats = statSync(path);
|
|
254
|
+
if (!stats.isFile()) return { status: "invalid", message: "邮件配置路径不是普通文件。" };
|
|
255
|
+
if ((stats.mode & 0o777) !== 0o600)
|
|
256
|
+
return { status: "invalid", message: "邮件配置文件权限必须是 0600。" };
|
|
257
|
+
text = readFileSync(path, "utf8");
|
|
258
|
+
} catch (error) {
|
|
259
|
+
// 无文件(含 agent 目录尚不存在)视为关闭,其余读取失败视为配置无效。
|
|
260
|
+
const code = (error as { code?: unknown } | null)?.code;
|
|
261
|
+
if (code === "ENOENT" || code === "ENOTDIR") return { status: "disabled" };
|
|
262
|
+
return { status: "invalid", message: "邮件配置文件无法读取。" };
|
|
263
|
+
}
|
|
264
|
+
let raw: unknown;
|
|
265
|
+
try {
|
|
266
|
+
raw = JSON.parse(text.startsWith("\uFEFF") ? text.slice(1) : text);
|
|
267
|
+
} catch {
|
|
268
|
+
// 不回显 JSON.parse 的原始错误,避免带出文件内容片段。
|
|
269
|
+
return { status: "invalid", message: "邮件配置文件不是有效的 JSON。" };
|
|
270
|
+
}
|
|
271
|
+
try {
|
|
272
|
+
return { status: "ready", config: parseEmailConfig(raw) };
|
|
273
|
+
} catch (error) {
|
|
274
|
+
if (error instanceof EmailConfigError) return { status: "invalid", message: error.message };
|
|
275
|
+
return { status: "invalid", message: "邮件配置无效。" };
|
|
276
|
+
}
|
|
277
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { getAgentDir } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { realpath } from "node:fs/promises";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
5
|
+
import { EmailError } from "./types.ts";
|
|
6
|
+
|
|
7
|
+
function within(path: string, root: string): boolean {
|
|
8
|
+
const difference = relative(root, path);
|
|
9
|
+
return difference === "" || (!isAbsolute(difference) && difference !== ".." && !difference.startsWith(`..${sep}`));
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/** 附件只允许工作目录与临时目录;真实路径检查避免符号链接越出边界。 */
|
|
13
|
+
export async function emailFilePath(input: string, cwd: string, writing = false): Promise<string> {
|
|
14
|
+
const path = resolve(cwd, input);
|
|
15
|
+
const agentDir = resolve(getAgentDir());
|
|
16
|
+
const roots = [resolve(cwd), resolve(tmpdir())];
|
|
17
|
+
let canonical: string;
|
|
18
|
+
let canonicalAgent: string;
|
|
19
|
+
let canonicalRoots: string[];
|
|
20
|
+
try {
|
|
21
|
+
canonical = writing ? join(await realpath(dirname(path)), basename(path)) : await realpath(path);
|
|
22
|
+
canonicalAgent = await realpath(agentDir).catch(() => agentDir);
|
|
23
|
+
canonicalRoots = await Promise.all(roots.map(root => realpath(root)));
|
|
24
|
+
} catch {
|
|
25
|
+
throw new EmailError("FILE_UNAVAILABLE", "附件路径不存在或不可访问;未执行文件操作。");
|
|
26
|
+
}
|
|
27
|
+
// 即使 cwd 本身覆盖配置目录,也不能把凭据作为邮件附件或下载目标。
|
|
28
|
+
if (within(path, agentDir) || within(canonical, canonicalAgent)
|
|
29
|
+
|| !canonicalRoots.some(root => within(canonical, root)))
|
|
30
|
+
throw new EmailError("FILE_NOT_ALLOWED", "附件仅允许当前工作目录或系统临时目录,且不得访问宿主配置目录。");
|
|
31
|
+
return path;
|
|
32
|
+
}
|