@bolloon/bolloon-agent 0.4.29 → 0.4.31

package/dist/agents/contacts/policy.js

@@ -0,0 +1,264 @@
+/**
+ * contacts/policy.ts — 联系方式调用策略门 (2026-09-19, Phase 6)
+ *
+ * 联系方式是高风险动作, **不许直接暴露给 Agent**。调用链固定:
+ *   Agent → PiAgentHarness → contact policy → consent → recipient → rate → preview → provider → send → evidence
+ *
+ * 本文件只做"能不能发/要不要人批"的判定 + 可审计预览, 不碰 provider、不写盘。
+ * 判定顺序固定, 每种拒绝都给出**机器可读的 blockKind** (供测试与审计), 不返回泛泛的"不允许"。
+ */
+import { readGoal } from '../goal-store.js';
+import { evaluateGrant, categoriesOf } from './grants.js';
+import { scanForbidden } from './types.js';
+import { scanSensitive } from './types.js';
+const CHANNEL_LABEL = {
+    'local-sink': '本地落盘 (未真实外发)',
+    'http-webhook': '短信网关 HTTP (真实外发)',
+    smtp: 'SMTP 邮件 (真实外发)',
+};
+function reallySentFor(provider) {
+    return provider === 'smtp' || provider === 'http-webhook';
+}
+/** 任务级 auto_send 授权: 用户明确给某个 Goal 开过才行 (默认没有) */
+export function taskAutoAuthorized(goal, contact) {
+    if (!goal)
+        return false;
+    const flag = goal.continuation?.autoSendContacts;
+    if (flag !== true)
+        return false;
+    if (contact.policy !== 'auto_send' && contact.policy !== 'send_after_approval')
+        return false;
+    if (contact.limits.requireApprovalEachTime)
+        return false;
+    return true;
+}
+export async function decideContactAction(input, ctx) {
+    const now = ctx.now ? ctx.now() : Date.now();
+    const base = {
+        allowed: false, requiresApproval: false, sensitive: [], firstContact: false, reallySent: false,
+        authorizationMode: 'one_time', approvalSkipped: false, policyDecision: 'not_evaluated', forbiddenCategories: [],
+    };
+    if (input.action === 'list')
+        return { ...base, allowed: true };
+    if (!input.contactId)
+        return { ...base, blockKind: 'not_found', reason: '缺少 contactId (禁止按模糊姓名自动发送)' };
+    const contact = await ctx.store.getContact(input.contactId);
+    if (!contact)
+        return { ...base, blockKind: 'not_found', reason: `contactId=${input.contactId} 不存在` };
+    // 1) 验证状态
+    if (contact.revokedAt || contact.verificationStatus === 'revoked') {
+        return { ...base, blockKind: 'consent_revoked', reason: '授权已被撤销 —— 历史证据保留, 但后续调用一律拒绝' };
+    }
+    if (contact.verificationStatus === 'blocked')
+        return { ...base, blockKind: 'contact_blocked', reason: '该联系方式已被标记 blocked' };
+    if (contact.verificationStatus === 'expired')
+        return { ...base, blockKind: 'verification_expired', reason: '验证已过期, 需重新验证' };
+    if (contact.verificationStatus !== 'verified') {
+        return { ...base, blockKind: 'unverified_contact', reason: `未验证的联系方式不能用于真实发送 (当前 ${contact.verificationStatus})` };
+    }
+    // 2) 通道是否配置好
+    const reallySent = reallySentFor(contact.provider);
+    if (reallySent && contact.secretRef && !(await ctx.store.secrets.has(contact.secretRef))) {
+        return { ...base, reallySent, blockKind: 'provider_not_configured', reason: `通道 ${contact.provider} 需要 secretRef=${contact.secretRef}, 但 Secret Store 里没有` };
+    }
+    // 3) 批量永远禁止
+    const recipients = input.recipients || [input.contactId];
+    if (recipients.length > 1) {
+        return { ...base, reallySent, blockKind: 'batch_forbidden', reason: `批量发送永远禁止 (收到 ${recipients.length} 个收件人)` };
+    }
+    // 4) 正常发送才要求正文
+    if ((input.action === 'send' || input.action === 'preview') && !input.body) {
+        return { ...base, reallySent, blockKind: 'missing_content', reason: '缺少正文' };
+    }
+    // 7) 频率限制
+    const limits = contact.limits || { dailyMax: 5, perTaskMax: 3, requireApprovalEachTime: false };
+    const today = await ctx.store.countSentToday(contact.contactId, now);
+    const forGoal = input.goalId ? await ctx.store.countSentForGoal(input.goalId) : 0;
+    const usage = { today, todayMax: limits.dailyMax, forGoal, goalMax: limits.perTaskMax };
+    // 7.5) 持久授权判定 (Phase 5): Grant 是否存在/有效/覆盖 channel·contact·task·content
+    const forbidden = scanForbidden(`${input.subject || ''}\n${input.body || ''}`);
+    base.forbiddenCategories = forbidden;
+    const sensitiveEarly = scanSensitive(`${input.subject || ''}\n${input.body || ''}`);
+    const scope0 = contact.consentScope || { kinds: [], taskRefs: [], grantedAt: '', grantedBy: '' };
+    const limits0 = contact.limits || { dailyMax: 5, perTaskMax: 3, requireApprovalEachTime: false };
+    const usage0 = {
+        today: await ctx.store.countSentToday(contact.contactId, now),
+        todayMax: limits0.dailyMax,
+        forGoal: input.goalId ? await ctx.store.countSentForGoal(input.goalId) : 0,
+        goalMax: limits0.perTaskMax,
+    };
+    let grantEval = null;
+    if (ctx.grants?.ready)
+        await ctx.grants.ready();
+    if (ctx.grants?.corrupt) {
+        // Grant 存储读不出来 → **拒绝自动发送**, 且大声说出来 (不静默当成"无权限"或"已授权")
+        base.grantBlock = 'grant_store_unreadable';
+        base.policyDecision = 'grant_store_unreadable:refuse_auto_send';
+        base.authorizationMode = 'one_time';
+        return { ...base, reallySent, usage: usage0, allowed: true, requiresApproval: true,
+            approvalReason: 'policy',
+            reason: '联系方式授权文件损坏/不可读 → 已拒绝自动发送, 需要人工批准并修复 grants.json (不会静默当成无权限或已授权)' };
+    }
+    if (ctx.grants) {
+        // 优先拿"管辖 Grant"(含撤销/暂停) 以给出精确原因; 拿不到再退到 activeFor
+        const g = ctx.grants.latestFor
+            ? await ctx.grants.latestFor(contact.ownerDid)
+            : await ctx.grants.activeFor(contact.ownerDid, now);
+        grantEval = evaluateGrant(g, {
+            ownerDid: contact.ownerDid,
+            channel: contact.kind,
+            contactId: contact.contactId,
+            contactVerified: contact.verificationStatus === 'verified',
+            contactRevoked: !!contact.revokedAt,
+            taskBoundToGoal: !!input.goalId && scope0.taskRefs.includes(input.goalId),
+            goalId: input.goalId,
+            goalMatchesGrant: ctx.goalMatchesGrant,
+            sensitiveCategories: categoriesOf(sensitiveEarly),
+            hasForbiddenContent: forbidden.length > 0,
+            deviceTrusted: ctx.deviceTrusted,
+        }, now);
+        if (grantEval.grant)
+            base.grant = { grantId: grantEval.grant.grantId, level: grantEval.grant.level, version: grantEval.grant.grantVersion };
+        base.authorizationMode = grantEval.authorizationMode;
+        base.approvalSkipped = grantEval.approvalSkipped;
+        base.policyDecision = grantEval.policyDecision;
+        if (!grantEval.ok) {
+            // 硬拒 (撤销/暂停/范围外/禁放行类别/设备不可信) → 直接不允许
+            // 例外: grant_missing / grant_suspended / grant_sensitive_content_denied → 退回人工批准 (不是"不允许")
+            const soft = grantEval.needsHumanApproval && (grantEval.block === 'grant_missing' || grantEval.block === 'grant_suspended' || grantEval.block === 'grant_sensitive_content_denied');
+            base.grantBlock = grantEval.block;
+            base.grantMissing = grantEval.block === 'grant_missing';
+            if (!soft) {
+                return { ...base, reallySent, usage: usage0,
+                    blockKind: grantEval.block === 'forbidden_content_category' ? 'forbidden_content_category' : 'grant_denied',
+                    reason: grantEval.reason };
+            }
+            base.approvalReason = grantEval.block === 'grant_sensitive_content_denied' ? 'sensitive_content' : 'policy';
+        }
+    }
+    // 8) contact 级硬禁 (与任务无关): draft_only
+    if (contact.policy === 'draft_only' && input.action === 'send') {
+        return { ...base, reallySent, usage, blockKind: 'policy_draft_only', reason: '该联系方式策略为 draft_only (只允许起草, 不允许发送)' };
+    }
+    // 8.5) 同一 requestId 不得重复发送 (幂等)
+    if (input.action === 'send' && input.requestId) {
+        const prior = await ctx.store.findSend(input.requestId);
+        if (prior && prior.status === 'sent') {
+            return { ...base, reallySent, usage, blockKind: 'duplicate_request', reason: `requestId=${input.requestId} 已经发送过 (状态 ${prior.status}), 不重复发送` };
+        }
+        if (ctx.hasPendingConsent && await ctx.hasPendingConsent(input.requestId)) {
+            return { ...base, reallySent, usage, blockKind: 'duplicate_request', reason: `requestId=${input.requestId} 已有待批准请求, 不重复排队` };
+        }
+    }
+    // 8.6) 频率限制 (contact 级 + 任务级)
+    if (input.action === 'send' && today >= limits.dailyMax) {
+        return { ...base, reallySent, usage, blockKind: 'rate_limited', reason: `今日已发 ${today}/${limits.dailyMax} 条, 超出发送频率` };
+    }
+    if (input.action === 'send' && input.goalId && forGoal >= limits.perTaskMax) {
+        return { ...base, reallySent, usage, blockKind: 'rate_limited', reason: `本任务已发 ${forGoal}/${limits.perTaskMax} 条, 超出任务上限` };
+    }
+    // 8.7) 任务边界: 是否绑定到这个任务 (发送必须有任务归属)
+    let goal = null;
+    if (input.goalId) {
+        goal = await readGoal(input.goalId);
+        if (!goal)
+            return { ...base, reallySent, blockKind: 'not_bound_to_task', reason: `goalId=${input.goalId} 不存在` };
+        if (goal.status === 'completed' || goal.status === 'failed') {
+            return { ...base, reallySent, usage, blockKind: 'goal_closed', reason: `任务已 ${goal.status}, 不允许再对外发送` };
+        }
+    }
+    const scope = contact.consentScope || { kinds: [], taskRefs: [], grantedAt: '', grantedBy: '' };
+    const boundToTask = !!input.goalId && (scope.taskRefs.includes(input.goalId) || (!!input.taskKind && scope.kinds.includes(input.taskKind)) || scope.kinds.includes('any'));
+    // "范围被授权覆盖" = 授权有效, 或只是内容敏感/暂停这类**软**情形 (软情形退回一次性人工批准,
+    //   而不是报"未绑定任务"这种会误导人的原因)
+    const SOFT_GRANT_COVER = new Set(['grant_sensitive_content_denied', 'grant_suspended']);
+    const coveredByGrant = !!(grantEval && (grantEval.ok || (!!grantEval.block && SOFT_GRANT_COVER.has(grantEval.block))));
+    if (input.action === 'send' && !boundToTask && !coveredByGrant) {
+        return { ...base, reallySent, usage, blockKind: 'not_bound_to_task',
+            reason: `该联系方式没有授权给任务 ${input.goalId || '(未指定)'} (未绑定任务联系人, 也没有覆盖它的长期授权)` };
+    }
+    // 9) 需要人工批准的几种情况
+    const sensitive = sensitiveEarly;
+    const firstContact = !(ctx.hasSentBefore ? await ctx.hasSentBefore(contact.contactId) : (await ctx.store.listSends()).some((s) => s.contactId === contact.contactId && s.status === 'sent'));
+    let requiresApproval = false;
+    let approvalReason;
+    // 持久授权命中且允许自动发送 → 跳过人工批准 (但下面的检查一个都不少)
+    if (grantEval && grantEval.ok && grantEval.approvalSkipped) {
+        requiresApproval = false;
+        approvalReason = undefined;
+    }
+    else if (firstContact && !(grantEval && grantEval.needsHumanApproval)) {
+        requiresApproval = true;
+        approvalReason = 'first_contact';
+    }
+    else if (grantEval && !grantEval.ok && grantEval.needsHumanApproval) {
+        requiresApproval = true;
+        approvalReason = base.approvalReason || 'policy';
+    }
+    else if (sensitive.length > 0) {
+        requiresApproval = true;
+        approvalReason = 'sensitive_content';
+    }
+    else if (limits.requireApprovalEachTime) {
+        requiresApproval = true;
+        approvalReason = 'each_time';
+    }
+    else if (contact.policy === 'send_after_approval' && !taskAutoAuthorized(goal, contact)) {
+        requiresApproval = true;
+        approvalReason = 'policy';
+    }
+    return {
+        allowed: true,
+        requiresApproval,
+        approvalReason,
+        sensitive,
+        firstContact,
+        reallySent,
+        usage,
+        grant: base.grant,
+        grantBlock: base.grantBlock,
+        grantMissing: base.grantMissing,
+        authorizationMode: base.authorizationMode,
+        approvalSkipped: requiresApproval ? false : base.approvalSkipped,
+        policyDecision: base.policyDecision,
+        forbiddenCategories: base.forbiddenCategories,
+        preview: buildPreview({ contact, input, reallySent, sensitive, firstContact, requiresApproval, approvalReason, usage, goal }),
+    };
+}
+export function buildPreview(b) {
+    const name = (b.contact.aliases && b.contact.aliases[0]) || b.contact.displayValue;
+    return {
+        contactName: name,
+        channel: b.contact.kind,
+        provider: b.contact.provider,
+        channelLabel: CHANNEL_LABEL[b.contact.provider] || b.contact.provider,
+        reallySent: b.reallySent,
+        recipient: b.contact.displayValue, // 只有脱敏值
+        subject: b.input.subject,
+        goalId: b.input.goalId,
+        goalObjective: b.goal?.objective,
+        permission: '单条发送 (批量永远禁止)',
+        usage: b.usage,
+        replyExpected: undefined,
+        firstContact: b.firstContact,
+        requiresApproval: b.requiresApproval,
+        approvalReason: b.approvalReason,
+        sensitive: b.sensitive.map((s) => `${s.kind}: ${s.hint}`),
+        lines: [
+            '将联系:',
+            `  联系人: ${name}`,
+            `  通道: ${b.contact.kind === 'phone' ? '手机号' : '邮箱'} · ${CHANNEL_LABEL[b.contact.provider] || b.contact.provider}`,
+            `  收件人: ${b.contact.displayValue} (脱敏)`,
+            b.input.subject ? `  主题: ${b.input.subject}` : '  主题: (无)',
+            `  任务: ${b.input.goalId || '(未绑定任务)'}${b.goal?.objective ? ` — ${String(b.goal.objective).slice(0, 60)}` : ''}`,
+            `  权限: 单条发送 (今日 ${b.usage.today}/${b.usage.todayMax} · 本任务 ${b.usage.forGoal}/${b.usage.goalMax})`,
+            `  首次联系: ${b.firstContact ? '是 (必须人工批准)' : '否'}`,
+            `  敏感内容: ${b.sensitive.length ? b.sensitive.map((s) => s.kind).join(', ') + ' (必须人工批准)' : '无'}`,
+            `  是否需要批准: ${b.requiresApproval ? `是 (${b.approvalReason || 'policy'})` : '否'}`,
+        ],
+    };
+}
+/** 人读渲染 (CLI / Web 卡片 / 审批流程都用这一份) */
+export function renderPreview(p) {
+    return p.lines.join('\n');
+}

package/dist/agents/contacts/preview-types.js

@@ -0,0 +1,6 @@
+/**
+ * contacts/preview-types.ts — 预览/限额的共享类型 (2026-09-19)
+ *
+ * 单独一个文件是为了断开 types.ts ↔ policy.ts 的循环引用: 两边都要用这两个形状。
+ */
+export {};

package/dist/agents/contacts/providers.js

@@ -0,0 +1,341 @@
+/**
+ * contacts/providers.ts — 通道适配器 + 验证码挑战 (2026-09-19, Phase 2/3)
+ *
+ * 三种通道, 各自**如实**：
+ *   local-sink     本地落盘 (outbox/*.json) —— 真写文件, 但**没有真外发**; 预览/证据里必须
+ *                  标成"本地落盘(非真实外发)", 不许让用户以为对方收到了。
+ *   http-webhook   真 HTTP POST (短信网关/自建服务), 需要 secretRef (Bearer token)
+ *   smtp           真 SMTP 会话 (net/tls, AUTH LOGIN), 需要 secretRef (host/port/user/pass/from)
+ *
+ * 未配置 = 明确报 `provider_not_configured` 并拒绝发送, **绝不假装成功**。
+ *
+ * 验证码挑战 (Phase 2/3):
+ *   验证码只以 sha256(salt+code) 落盘, 明文只在"投递那一刻"存在; 有次数上限、有过期、一次性。
+ */
+import * as fsp from 'fs/promises';
+import * as net from 'net';
+import * as tls from 'tls';
+import * as path from 'path';
+import * as crypto from 'crypto';
+// ── 本地落盘 (真写文件, 但明确不是真外发) ────────────────────────────────────
+export const localSinkProvider = {
+    id: 'local-sink',
+    kind: 'phone', // kind 仅作声明; 实际两种都能落
+    emulatesRealSend: false,
+    async configured() { return true; },
+    async deliver(msg, ctx) {
+        const file = path.join(ctx.store.dir, 'outbox', `${msg.requestId}.json`);
+        await fsp.mkdir(path.dirname(file), { recursive: true });
+        await fsp.writeFile(file, JSON.stringify({
+            // 明文收件人只落在这个本地文件里 (它就是"发件箱"), 不进 evidence/ledger
+            to: msg.to, kind: msg.kind, subject: msg.subject, body: msg.body,
+            threadToken: msg.threadToken, requestId: msg.requestId, at: new Date().toISOString(),
+            channel: 'local-sink', note: '本地落盘通道: 未真实外发 (仅供开发/验收)',
+        }, null, 2), 'utf8');
+        return { ok: true, providerMessageId: `local-${msg.requestId}`, reallySent: false };
+    },
+};
+// ── HTTP 网关 (真外发, 需要 secret) ─────────────────────────────────────────
+export const httpWebhookProvider = {
+    id: 'http-webhook',
+    kind: 'phone',
+    emulatesRealSend: true,
+    async configured(store, secretRef) { return !!(secretRef && await store.secrets.has(secretRef)); },
+    async deliver(msg, ctx) {
+        const secret = await ctx.store.secrets.get(ctx.secretRef);
+        if (!secret)
+            return { ok: false, reallySent: false, error: `provider_not_configured: 缺少 secretRef=${ctx.secretRef}`, errorClass: 'provider_not_configured' };
+        let cfg;
+        try {
+            cfg = JSON.parse(secret.value);
+        }
+        catch {
+            return { ok: false, reallySent: false, error: 'secret 不是合法 JSON', errorClass: 'provider_not_configured' };
+        }
+        if (!cfg?.endpoint)
+            return { ok: false, reallySent: false, error: 'secret 缺 endpoint', errorClass: 'provider_not_configured' };
+        try {
+            const res = await fetch(cfg.endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...(cfg.token ? { authorization: `Bearer ${cfg.token}` } : {}) },
+                body: JSON.stringify({ to: msg.to, text: msg.body, threadToken: msg.threadToken, requestId: msg.requestId }),
+            });
+            const text = await res.text().catch(() => '');
+            if (!res.ok) {
+                const cls = res.status === 401 || res.status === 403 ? 'provider_auth_failed' : 'provider_rejected';
+                return { ok: false, reallySent: false, error: `HTTP ${res.status}: ${text.slice(0, 120)}`, errorClass: cls };
+            }
+            let id = '';
+            try {
+                id = String(JSON.parse(text)?.id || JSON.parse(text)?.sid || '');
+            }
+            catch { /* 网关没给 id 就不编 */ }
+            return { ok: true, reallySent: true, providerMessageId: id || `http-${msg.requestId}` };
+        }
+        catch (err) {
+            return { ok: false, reallySent: false, error: String(err?.message || err), errorClass: 'provider_unreachable' };
+        }
+    },
+};
+class SmtpSession {
+    sock;
+    buf = '';
+    /** 已收但还没被读走的完整行 —— 必须排队, 不能"没人等就丢" */
+    lines = [];
+    waiters = [];
+    closed = false;
+    constructor(sock) {
+        this.sock = sock;
+        sock.setEncoding('utf8');
+        sock.on('data', (d) => {
+            this.buf += d;
+            let idx;
+            while ((idx = this.buf.indexOf('\r\n')) >= 0) {
+                const line = this.buf.slice(0, idx);
+                this.buf = this.buf.slice(idx + 2);
+                const w = this.waiters.shift();
+                if (w)
+                    w(line);
+                else
+                    this.lines.push(line); // 2026-09-19: 排队而不是丢弃
+            }
+        });
+        sock.on('error', (err) => this.fail(new Error(err?.message || 'smtp_socket_error')));
+        sock.on('close', () => this.fail(new Error('smtp_connection_closed')));
+    }
+    fail(err) {
+        this.closed = true;
+        const ws = this.waiters;
+        this.waiters = [];
+        for (const w of ws)
+            w(`__ERROR__${err.message}`);
+    }
+    /**
+     * 读一条"完整"应答 (SMTP 多行应答: `250-续行` 到 `250 最后一行` 才算完)。
+     * 2026-09-19 真跑抓到: 一条 chunk 里带多行时, 早先的实现只喂第一个等待者、**其余行被丢掉** →
+     *   客户端死等超时 (表现就是"一发 EHLO 就 smtp_timeout")。
+     */
+    async readReply(timeoutMs = 15000) {
+        const lines = [];
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const line = await this.nextLine(deadline - Date.now());
+            if (line.startsWith('__ERROR__'))
+                throw new Error(line.slice('__ERROR__'.length));
+            lines.push(line);
+            if (/^\d{3} /.test(line))
+                break; // 空格 = 最后一行
+        }
+        return lines.join('\n');
+    }
+    nextLine(timeoutMs) {
+        if (this.lines.length)
+            return Promise.resolve(this.lines.shift());
+        if (this.closed)
+            return Promise.reject(new Error('smtp_connection_closed'));
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => {
+                this.waiters = this.waiters.filter((w) => w !== fn);
+                reject(new Error('smtp_timeout'));
+            }, Math.max(1, timeoutMs));
+            const fn = (l) => { clearTimeout(t); resolve(l); };
+            this.waiters.push(fn);
+        });
+    }
+    async cmd(text) {
+        this.sock.write(text + '\r\n');
+        return this.readReply();
+    }
+    write(text) { this.sock.write(text); }
+    end() { try {
+        this.sock.end();
+    }
+    catch { /* 已断 */ } }
+}
+function classifySmtpError(err, code) {
+    const msg = String(err?.message || err || '').toLowerCase();
+    if (msg.includes('smtp_timeout'))
+        return 'provider_unreachable';
+    if (msg.includes('econnrefused') || msg.includes('etimedout') || msg.includes('enotfound') || code === 'ECONNREFUSED')
+        return 'provider_unreachable';
+    return 'unknown';
+}
+/** 真 SMTP 发送 (net / tls, AUTH LOGIN)。信封里的收件人只在这里出现。 */
+export async function smtpDeliver(cfg, msg) {
+    let sock;
+    let s;
+    try {
+        sock = cfg.secure
+            ? tls.connect({ host: cfg.host, port: cfg.port, servername: cfg.tlsServername || cfg.host })
+            : net.connect({ host: cfg.host, port: cfg.port });
+        // 2026-09-19: **先挂监听再等连接** —— 服务器可能在 TCP 建好那一刻就把 "220 ..." 发过来,
+        //   监听器挂晚了会丢问候语, 表现是"客户端干等到超时"(真跑 SMTP 时抓到过)。
+        s = new SmtpSession(sock);
+        await new Promise((resolve, reject) => {
+            const onErr = (e) => reject(e);
+            if (sock.connecting === false) {
+                resolve();
+                return;
+            }
+            sock.once('error', onErr);
+            const ev = cfg.secure ? 'secureConnect' : 'connect';
+            sock.once(ev, () => { sock.off('error', onErr); resolve(); });
+            setTimeout(() => reject(new Error('connect_timeout')), 12000).unref?.();
+        });
+    }
+    catch (err) {
+        return { ok: false, reallySent: false, error: String(err?.message || err), errorClass: 'provider_unreachable' };
+    }
+    try {
+        const greet = await s.readReply();
+        if (!/^220/.test(greet))
+            return { ok: false, reallySent: false, error: `SMTP 问候异常: ${greet.slice(0, 80)}`, errorClass: 'provider_rejected' };
+        const ehlo = await s.cmd(`EHLO bolloon.local`);
+        if (!/^250/.test(ehlo))
+            return { ok: false, reallySent: false, error: `EHLO 被拒: ${ehlo.slice(0, 80)}`, errorClass: 'provider_rejected' };
+        if (cfg.user && cfg.pass) {
+            const a1 = await s.cmd('AUTH LOGIN');
+            if (!/^334/.test(a1))
+                return { ok: false, reallySent: false, error: `AUTH LOGIN 不支持: ${a1.slice(0, 80)}`, errorClass: 'provider_auth_failed' };
+            const a2 = await s.cmd(Buffer.from(cfg.user).toString('base64'));
+            if (!/^334/.test(a2))
+                return { ok: false, reallySent: false, error: `用户名被拒: ${a2.slice(0, 80)}`, errorClass: 'provider_auth_failed' };
+            const a3 = await s.cmd(Buffer.from(cfg.pass).toString('base64'));
+            if (!/^235/.test(a3))
+                return { ok: false, reallySent: false, error: `认证失败: ${a3.slice(0, 80)}`, errorClass: 'provider_auth_failed' };
+        }
+        const mf = await s.cmd(`MAIL FROM:<${cfg.from}>`);
+        if (!/^250/.test(mf))
+            return { ok: false, reallySent: false, error: `MAIL FROM 被拒: ${mf.slice(0, 80)}`, errorClass: 'provider_rejected' };
+        const rc = await s.cmd(`RCPT TO:<${msg.to}>`);
+        if (!/^250/.test(rc))
+            return { ok: false, reallySent: false, error: `RCPT TO 被拒: ${rc.slice(0, 80)}`, errorClass: 'invalid_recipient' };
+        const dt = await s.cmd('DATA');
+        if (!/^354/.test(dt))
+            return { ok: false, reallySent: false, error: `DATA 被拒: ${dt.slice(0, 80)}`, errorClass: 'provider_rejected' };
+        const body = msg.body.replace(/\r?\n/g, '\r\n').replace(/^\./gm, '..');
+        const headers = [
+            `From: ${msg.fromName ? `"${msg.fromName}" <${cfg.from}>` : cfg.from}`,
+            `To: <${msg.to}>`,
+            `Subject: ${msg.subject || '(无主题)'}`,
+            `Date: ${new Date().toUTCString()}`,
+            `Message-ID: <${msg.requestId}@bolloon>`,
+            `X-Bolloon-Thread: ${msg.threadToken}`,
+            `X-Bolloon-Request: ${msg.requestId}`,
+            'MIME-Version: 1.0',
+            'Content-Type: text/plain; charset=utf-8',
+        ].join('\r\n');
+        const sent = await s.cmd(`${headers}\r\n\r\n${body}\r\n.`);
+        if (!/^250/.test(sent))
+            return { ok: false, reallySent: false, error: `发送被拒: ${sent.slice(0, 120)}`, errorClass: 'provider_rejected' };
+        s.cmd('QUIT').catch(() => { });
+        const id = (sent.match(/250[ -](?:2\.0\.0\s+)?(?:Ok\s+)?(?:queued as\s+)?(\S+)/i)?.[1]) || `smtp-${msg.requestId}`;
+        return { ok: true, reallySent: true, providerMessageId: id };
+    }
+    catch (err) {
+        return { ok: false, reallySent: false, error: String(err?.message || err), errorClass: classifySmtpError(err, err?.code) };
+    }
+    finally {
+        s.end();
+    }
+}
+export const smtpProvider = {
+    id: 'smtp',
+    kind: 'email',
+    emulatesRealSend: true,
+    async configured(store, secretRef) { return !!(secretRef && await store.secrets.has(secretRef)); },
+    async deliver(msg, ctx) {
+        const secret = await ctx.store.secrets.get(ctx.secretRef);
+        if (!secret)
+            return { ok: false, reallySent: false, error: `provider_not_configured: 缺少 secretRef=${ctx.secretRef}`, errorClass: 'provider_not_configured' };
+        let cfg;
+        try {
+            cfg = JSON.parse(secret.value);
+        }
+        catch {
+            return { ok: false, reallySent: false, error: 'secret 不是合法 JSON', errorClass: 'provider_not_configured' };
+        }
+        if (!cfg?.host || !cfg?.from)
+            return { ok: false, reallySent: false, error: 'secret 缺 host/from', errorClass: 'provider_not_configured' };
+        return smtpDeliver({ ...cfg, port: cfg.port || 587 }, msg);
+    },
+};
+const PROVIDERS = {
+    'local-sink': localSinkProvider,
+    'http-webhook': httpWebhookProvider,
+    smtp: smtpProvider,
+};
+export function getProvider(id) {
+    return PROVIDERS[id] || null;
+}
+export function listProviders() {
+    return Object.values(PROVIDERS).map((p) => ({ id: p.id, kind: p.kind, reallySent: p.emulatesRealSend }));
+}
+const OTP_TTL_MS = 10 * 60_000;
+const OTP_MAX_ATTEMPTS = 5;
+export function generateOtp() {
+    return String(crypto.randomInt(0, 1_000_000)).padStart(6, '0');
+}
+export function hashCode(code, salt) {
+    return crypto.createHash('sha256').update(`${salt}:${code}`).digest('hex');
+}
+export class OtpStore {
+    dir;
+    file;
+    constructor(dir) {
+        this.dir = dir;
+        this.file = path.join(dir, 'otp.json');
+    }
+    async list() {
+        try {
+            return JSON.parse(await fsp.readFile(this.file, 'utf8'));
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+    async write(all) {
+        const tmp = `${this.file}.tmp-${process.pid}`;
+        await fsp.mkdir(this.dir, { recursive: true });
+        await fsp.writeFile(tmp, JSON.stringify(all.slice(-200), null, 2), 'utf8');
+        await fsp.rename(tmp, this.file);
+    }
+    /** 生成挑战 —— 返回明文 once (调用方马上投递, 不落盘) */
+    async issue(opts) {
+        const now = opts.now ?? Date.now();
+        const code = generateOtp();
+        const salt = crypto.randomBytes(8).toString('hex');
+        const challenge = {
+            challengeId: `otp-${now.toString(36)}-${crypto.randomBytes(3).toString('hex')}`,
+            contactId: opts.contactId, kind: opts.kind, provider: opts.provider,
+            salt, codeHash: hashCode(code, salt), attempts: 0, maxAttempts: OTP_MAX_ATTEMPTS,
+            createdAt: new Date(now).toISOString(), expiresAt: new Date(now + OTP_TTL_MS).toISOString(),
+        };
+        const all = await this.list();
+        all.push(challenge);
+        await this.write(all);
+        return { challenge, code };
+    }
+    async verify(challengeId, code, now = Date.now()) {
+        const all = await this.list();
+        const c = all.find((x) => x.challengeId === challengeId);
+        if (!c)
+            return { ok: false, reason: 'challenge_not_found' };
+        if (c.usedAt)
+            return { ok: false, reason: 'already_used' };
+        if (Date.parse(c.expiresAt) < now)
+            return { ok: false, reason: 'expired' };
+        if (c.attempts >= c.maxAttempts)
+            return { ok: false, reason: 'too_many_attempts' };
+        c.attempts += 1;
+        if (hashCode(String(code).trim(), c.salt) !== c.codeHash) {
+            await this.write(all);
+            return { ok: false, reason: 'wrong_code' };
+        }
+        c.usedAt = new Date(now).toISOString();
+        await this.write(all);
+        return { ok: true };
+    }
+}