dsh-email 0.10.7 → 0.11.0

package/lib/settings.js

@@ -16,6 +16,10 @@ export const EmailSettingsSchema = z.object({
     maxBodyChars: z.number().default(20000),
     downloadDir: z.string().default(''),
     accountsYaml: z.string().role('secret').default(''),
+    // Reusable IMAP/SMTP endpoints for the account cards. No credentials, so no
+    // role('secret') — and deliberately not projected into EmailConfig, or
+    // editing a preset would change the pool fingerprint and drop live sessions.
+    serverPresets: z.string().default(''),
     imap: z.object({
         host: z.string().default(''),
         port: z.number().default(993),
@@ -37,6 +41,7 @@ export function toSettingsBase(config) {
         ...(config.sendApproval !== undefined ? { sendApproval: config.sendApproval } : {}),
         ...(config.maxBodyChars !== undefined ? { maxBodyChars: config.maxBodyChars } : {}),
         ...(config.downloadDir !== undefined && config.downloadDir !== '' ? { downloadDir: config.downloadDir } : {}),
+        ...(config.serverPresets !== undefined && config.serverPresets !== '' ? { serverPresets: config.serverPresets } : {}),
         ...(config.imap !== undefined ? {
             imap: {
                 host: config.imap.host ?? '',
@@ -53,6 +58,31 @@ export function toSettingsBase(config) {
         } : {}),
     };
 }
+/** True for a field the draft really carries: absent, undefined and null all mean 「未设置」. */
+function isSet(field) {
+    return field !== undefined && field !== null;
+}
+/**
+ * The port an endpoint object carries, or undefined when the endpoint is absent
+ * or carries no port key.
+ */
+function endpointPort(endpoint) {
+    if (endpoint === null || typeof endpoint !== 'object' || Array.isArray(endpoint))
+        return undefined;
+    return endpoint.port;
+}
+/**
+ * Is this port outside 1-65535? A missing port is not a violation (「未设置」),
+ * but anything present is compared loosely — exactly the `<`/`>` coercion the
+ * previous `value.imap.port < 1` used, so a numeric string is still judged
+ * rather than waved through.
+ */
+function portOutOfRange(port) {
+    if (!isSet(port))
+        return false;
+    const n = port;
+    return n < 1 || n > 65535;
+}
 /**
  * Project a settings value back into EmailConfig shape.
  *
@@ -60,65 +90,123 @@ export function toSettingsBase(config) {
  * are projected, so schema defaults never shadow the row config or the
  * provider presets (choosing outlook must NOT force smtp port 465 over the
  * preset's 587). Pass `null` to project every field (draft paths).
+ *
+ * The value may also be *partial*: the settings page posts a draft, and the card
+ * editor posts its own control bundle, from which JSON.stringify drops every key
+ * it does not model — `provider` above all. A field the draft does not carry
+ * means 「未设置」 and must be left out entirely: assigning `out.provider =
+ * undefined` is NOT the same as omitting it, because an own key holding undefined
+ * still wins in `{ ...rowConfig, ...toEmailConfig(value, null) }` and would erase
+ * the row's provider (that produced 「未知的邮件服务商 undefined」 on a card whose
+ * provider was plainly selected). Same normalization as toSettingsBase.
  */
 export function toEmailConfig(value, user) {
+    const draft = (value ?? {});
     const has = (key) => user === null || user?.[key] !== undefined;
     const out = {};
-    if (has('provider'))
-        out.provider = value.provider === '' ? undefined : value.provider;
+    const set = (key, field) => {
+        if (isSet(field))
+            out[key] = field;
+    };
+    // provider is the one field where '' is a *value* rather than an absence: the
+    // settings page uses it for 「自定义服务器」, so it must still clear the row
+    // provider even though every other unset field is now omitted.
+    if (has('provider') && isSet(draft.provider)) {
+        out.provider = draft.provider === '' ? undefined : draft.provider;
+    }
     if (has('user'))
-        out.user = value.user;
+        set('user', draft.user);
     if (has('password'))
-        out.password = value.password;
+        set('password', draft.password);
     if (has('inboxFolder'))
-        out.inboxFolder = value.inboxFolder;
+        set('inboxFolder', draft.inboxFolder);
     if (has('sendApproval'))
-        out.sendApproval = value.sendApproval;
+        set('sendApproval', draft.sendApproval);
     if (has('maxBodyChars'))
-        out.maxBodyChars = value.maxBodyChars;
+        set('maxBodyChars', draft.maxBodyChars);
     if (has('downloadDir'))
-        out.downloadDir = value.downloadDir;
+        set('downloadDir', draft.downloadDir);
     if (has('accountsYaml'))
-        out.accountsYaml = value.accountsYaml;
-    if (user === null || user?.imap !== undefined) {
-        const fields = user === null ? value.imap : (user.imap ?? {});
+        set('accountsYaml', draft.accountsYaml);
+    // serverPresets is intentionally NOT projected: it is UI-side metadata that
+    // resolution never reads, and projecting it would put it into the resolved
+    // fingerprint, so saving a preset would dispose every live IMAP connection.
+    const imapValue = draft.imap;
+    const imapKeys = user === null ? imapValue : user?.imap;
+    if (isSet(imapKeys) && isSet(imapValue)) {
         const imap = {};
         // Empty host means "use the provider preset" — never project it, or the
         // preset gets shadowed by '' (issues #3 / #6).
-        if (fields.host !== undefined && value.imap.host !== '')
-            imap.host = value.imap.host;
-        if (fields.port !== undefined)
-            imap.port = value.imap.port;
-        if (fields.secure !== undefined)
-            imap.secure = value.imap.secure;
+        if (isSet(imapKeys.host) && isSet(imapValue.host) && imapValue.host !== '')
+            imap.host = imapValue.host;
+        if (isSet(imapKeys.port) && isSet(imapValue.port))
+            imap.port = imapValue.port;
+        if (isSet(imapKeys.secure) && isSet(imapValue.secure))
+            imap.secure = imapValue.secure;
         out.imap = imap;
     }
-    if (user === null || user?.smtp !== undefined) {
-        const fields = user === null ? value.smtp : (user.smtp ?? {});
+    const smtpValue = draft.smtp;
+    const smtpKeys = user === null ? smtpValue : user?.smtp;
+    if (isSet(smtpKeys) && isSet(smtpValue)) {
         const smtp = {};
-        if (fields.host !== undefined && value.smtp.host !== '')
-            smtp.host = value.smtp.host;
-        if (fields.port !== undefined)
-            smtp.port = value.smtp.port;
-        if (fields.secure !== undefined)
-            smtp.secure = value.smtp.secure;
+        if (isSet(smtpKeys.host) && isSet(smtpValue.host) && smtpValue.host !== '')
+            smtp.host = smtpValue.host;
+        if (isSet(smtpKeys.port) && isSet(smtpValue.port))
+            smtp.port = smtpValue.port;
+        if (isSet(smtpKeys.secure) && isSet(smtpValue.secure))
+            smtp.secure = smtpValue.secure;
         out.smtp = smtp;
     }
     return out;
 }
+/**
+ * Render a rejected value for an error message. The old code concatenated the
+ * raw value into the sentence, which turned an absent field into the baffling
+ * 「未知的邮件服务商undefined」 — a JSON form at least admits that no value was
+ * there.
+ */
+function describeValue(value) {
+    if (typeof value === 'string')
+        return '"' + value + '"';
+    if (value === undefined)
+        return 'undefined';
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 /**
  * Gentle write-path validation: structural mistakes fail loudly, but an
  * incomplete account is allowed (tools report the actionable hint at call
  * time, so an unconfigured install never breaks boot).
+ *
+ * The value may be partial — the web route validates whatever the page posted,
+ * and the card editor's own POST never carries the form fields. 「Missing」 is
+ * 「未设置」 for every one of them, exactly as toEmailConfig projects them, so a
+ * partial draft is validated only for the fields it actually has.
+ *
+ * `extraProviders` are the custom preset names in effect: the settings page's
+ * provider dropdown offers them beside the 8 built-ins, so a value naming one
+ * is a legal choice, not an unknown provider.
  */
-export function validateSettingsValue(value) {
-    if (value.provider !== '' && !PROVIDER_NAMES.includes(value.provider)) {
-        throw new Error('未知的邮箱服务商 "' + value.provider + '"，可选：' + PROVIDER_NAMES.join('/') + '（或留空手填 IMAP/SMTP 主机）');
+export function validateSettingsValue(value, extraProviders = []) {
+    const draft = (value ?? {});
+    const provider = draft.provider;
+    if (isSet(provider) && provider !== '' && !PROVIDER_NAMES.includes(provider) && !extraProviders.includes(provider)) {
+        const names = [...PROVIDER_NAMES, ...extraProviders];
+        throw new Error('未知的邮箱服务商 ' + describeValue(provider) + '，可选：' + names.join('/') + '（或留空手填 IMAP/SMTP 主机）');
+    }
+    const imapPort = endpointPort(draft.imap);
+    if (portOutOfRange(imapPort)) {
+        throw new Error('IMAP 端口必须在 1-65535 之间，收到 ' + describeValue(imapPort));
+    }
+    const smtpPort = endpointPort(draft.smtp);
+    if (portOutOfRange(smtpPort)) {
+        throw new Error('SMTP 端口必须在 1-65535 之间，收到 ' + describeValue(smtpPort));
+    }
+    if (isSet(draft.maxBodyChars) && (draft.maxBodyChars < 1000 || draft.maxBodyChars > 200000)) {
+        throw new Error('正文截断上限必须在 1000-200000 之间，收到 ' + describeValue(draft.maxBodyChars));
     }
-    if (value.imap.port < 1 || value.imap.port > 65535)
-        throw new Error('IMAP 端口必须在 1-65535 之间');
-    if (value.smtp.port < 1 || value.smtp.port > 65535)
-        throw new Error('SMTP 端口必须在 1-65535 之间');
-    if (value.maxBodyChars < 1000 || value.maxBodyChars > 200000)
-        throw new Error('正文截断上限必须在 1000-200000 之间');
 }

package/lib/tool-contract.js

@@ -279,7 +279,7 @@ export const descriptions = {
     "email_list": 'List recent emails in a mailbox folder (newest first). Returns uid, date, sender, subject and flags without message bodies; use email_read with a uid to fetch the full text. Optional since/until (dates like 2026-08-01) filter by received date.',
     "email_read": 'Read one full email message by its uid (from email_list or email_search). Returns the plain-text body (HTML mail is converted; oversized bodies are truncated) plus attachment metadata; use email_attachment to download one.',
     "email_mark": 'Change an existing message: mark it read/unread, star/unstar it, or move it to another folder. Use after email_list/email_search when the user wants to tidy the mailbox (archive, clear unread, flag important mail). Moving uses the server MOVE/COPY so the uid changes; the new uid is reported when the server provides it.',
-    "email_search": 'Search emails by a keyword. The server first searches sender, recipients and subject; when that finds nothing and bodySearchFallback is enabled, recent messages are scanned locally including their body. since/until still constrain both paths. Returns the same compact rows as email_list.',
+    "email_search": 'Search emails by a keyword. The server first searches sender, recipients and subject; those hits are re-verified against the envelopes and, when none of them really carries the keyword (some servers answer every search with the same uids), recent messages are scanned locally including their body while bodySearchFallback is enabled. since/until still constrain both paths. Returns the same compact rows as email_list.',
     "email_send": 'Send an email from a configured account, optionally with file attachments (absolute paths, or relative to the dsh process cwd). Sending asks the user for approval (recipient, subject and attachment count are shown) unless sendApproval is disabled; in Full Access mode the approval policy never asks, so the send is refused with an explanation instead. Never invent recipients or content without the user\'s instruction.',
     "email_reply": 'Reply to, reply-all to, or forward an existing message (mode: reply | reply-all | forward). Recipients come from the original message (your own address is excluded automatically), the subject gets a single Re:/Fwd: prefix, the original text is quoted underneath, and In-Reply-To/References headers keep mail clients threading correctly. mode=forward needs the to parameter. Like email_send, this asks the user for approval before sending. Never invent recipients or content without the user\'s instruction.',
     "email_folders": 'List the mailbox folders of an account (INBOX, Sent, Trash, custom folders, ...). Use the returned path values as the folder argument of the other email tools.',

package/lib/tools.js

@@ -1,5 +1,6 @@
 import { clampInt, PROVIDER_PRESETS } from './config.js';
 import { messageOf } from './mail-client.js';
+import { NOT_LOGGED_IN_MESSAGE, oauth2StateOf } from './oauth2.js';
 import { descriptions, parameters, MAX_LIMIT, MARK_ACTIONS, REPLY_MODES, executionSignal, normalizeAttachmentPaths, parseEmailDay, attachmentSchema, foldersSchema, listSchema, markSchema, readSchema, replySchema, sendSchema, watchSchema, renderAttachment, renderFolders, renderHealth, renderList, renderMark, renderRead, renderReply, renderSearch, renderSend, renderWatch, } from './tool-contract.js';
 export function buildEmailTools(runtime) {
     const { getPool, getEffectiveSettings, watch: watchCore } = runtime;
@@ -144,11 +145,25 @@ export function buildEmailTools(runtime) {
                     const entries = [...effective.accounts.entries()];
                     for (const [accountName, account] of entries.slice(0, 8)) {
                         const provider = Object.entries(PROVIDER_PRESETS).find(([, preset]) => (preset.imap.host === account.imap.host && preset.smtp.host === account.smtp.host))?.[0] ?? 'custom';
-                        checks.push({
-                            name: '账号 ' + accountName,
-                            ok: true,
-                            detail: provider + ' / ' + account.user + ' / IMAP ' + account.imap.host + ' / SMTP ' + account.smtp.host,
-                        });
+                        const base = provider + ' / ' + account.user + ' / IMAP ' + account.imap.host + ' / SMTP ' + account.smtp.host;
+                        // An OAuth2 account with no token is configured, not broken: the
+                        // missing piece is a browser login, and saying so is the whole
+                        // point of this check.
+                        if (account.authKind === 'oauth2') {
+                            // The address is passed along so a token belonging to a different
+                            // mailbox is not reported as a working login.
+                            const state = oauth2StateOf(accountName, account.user);
+                            const loggedIn = state.state === 'logged-in';
+                            checks.push({
+                                name: '账号 ' + accountName,
+                                ok: true,
+                                detail: loggedIn
+                                    ? base + ' / OAuth2 已登录' + (state.user !== undefined ? '（' + state.user + '）' : '')
+                                    : base + ' / OAuth2 ' + NOT_LOGGED_IN_MESSAGE,
+                            });
+                            continue;
+                        }
+                        checks.push({ name: '账号 ' + accountName, ok: true, detail: base });
                     }
                     return { ok: true, plugin: 'dsh-email', accountCount: entries.length, checks };
                 }

package/lib/web.d.ts

@@ -1,10 +1,141 @@
 import { type EmailSettingsValue } from './settings.js';
-import { type EmailConfig } from './config.js';
+import { type EmailConfig, type ProviderPreset, type ServerPreset } from './config.js';
+import { type OAuth2State } from './oauth2.js';
 import type { EmailWatchResult } from './types.js';
 /** Same-origin route the browser settings section talks to. */
 export declare const SETTINGS_ROUTE = "/_dsh/dsh-email/settings";
 /** Same-origin route serving the whale-girl courier image to the widget. */
 export declare const WHALE_ASSET_ROUTE = "/_dsh/dsh-email/assets/whale";
+/**
+ * One account as the settings page renders it: resolved connection parameters
+ * plus whether a password exists. Passwords themselves never cross this
+ * boundary — the card only needs to know if the field is filled.
+ */
+export interface AccountCardData {
+    name: string;
+    /** undefined = 自定义服务器（无 provider 预设） */
+    provider?: string;
+    /** 预设自带的显示名；没有 label 时省略，前端回退显示 provider 名 */
+    providerLabel?: string;
+    user: string;
+    hasPassword: boolean;
+    /**
+     * How this account authenticates. An `oauth2` card shows the device-code
+     * login button instead of a 授权码, because Microsoft no longer accepts one.
+     */
+    authKind: 'oauth2' | 'password';
+    /**
+     * The `authKind` the account itself pins, when it pins one. `authKind` above
+     * is the effective verdict (which pane the editor shows); this is whether the
+     * user chose it, which is what the three-way selector has to render back —
+     * without it「自动」and「显式密码」look identical and the escape hatch is
+     * unreachable from the panel.
+     */
+    authKindDeclared?: 'oauth2' | 'password';
+    /**
+     * The application (client) id this account logs in through. Unlike a password
+     * this is not a secret — a public-client id travels in every device-code
+     * request — so the card carries the value itself and the editor can prefill
+     * it. Omitted when the account has none, which for an OAuth2 account is
+     * exactly the state that has to be fixed before login can start.
+     */
+    clientId?: string;
+    /** Login state of an OAuth2 account: none / a device code in flight / logged in. */
+    oauthState: OAuth2State;
+    /** The mailbox address the stored token belongs to (OAuth2 accounts only). */
+    oauthUser?: string;
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        secure: boolean;
+    };
+    inboxFolder: string;
+    isDefault: boolean;
+}
+/** One account card as the editor sends it back; every field is optional. */
+export interface AccountCardInput {
+    name?: string;
+    /** Persisted account key before a UI rename. */
+    originalName?: string;
+    provider?: string;
+    user?: string;
+    /**
+     * 授权码，三态契约：undefined = 本卡片没提供（保留 YAML 里已存的 password 键），
+     * '' = 明确清除（用户在 UI 里清空了密码框），非空 = 写入（数字/布尔先转字符串）。
+     * 卡片永远拿不到明文（snapshot 只给 hasPassword），所以「没提供」绝不能当成
+     * 「删除」：那会让每一次无关的卡片保存都静默清掉用户已存的授权码。
+     */
+    password?: string | number | boolean;
+    /**
+     * OAuth2 应用（客户端）ID，三态契约与 password 相同：undefined = 本卡片没提供
+     * （保留 YAML 里已存的 clientId 键），'' = 明确清除，非空 = 写入。插件不内置任何
+     * 第三方应用注册，所以这是 OAuth2 账号的必填项，而设置面板是用户唯一的常规入口。
+     */
+    clientId?: string;
+    /**
+     * 认证方式覆盖，三态契约同上：undefined = 本卡片没提供（保留已存的 authKind 键），
+     * '' = 明确恢复「自动」（删掉该键，回到按 provider/主机派生），非空 = 钉住。
+     * 这是给仍能用应用密码连 Exchange Online 的租户（混合/本地部署、SMTP AUTH 未关）
+     * 留的退路，没有它，这类账号升级后只会看到「尚未登录」且无处可改。
+     */
+    authKind?: string;
+    inboxFolder?: string;
+    imap?: {
+        host?: string;
+        port?: number;
+        secure?: boolean;
+    };
+    smtp?: {
+        host?: string;
+        port?: number;
+        secure?: boolean;
+    };
+}
+/**
+ * Verdict on the `Host` header: `undefined` to proceed, otherwise the reason to
+ * refuse.
+ *
+ * The localhost gate on `socket.remoteAddress` proves where the packets came
+ * from, not which name the browser believes it is talking to. A page the user
+ * visits can point a domain at 127.0.0.1 (DNS rebinding); that request looks
+ * same-origin to the browser, carries no `Origin`, and would make the snapshot
+ * readable — and the snapshot carries `accountsYaml`, plaintext 授权码 included.
+ * Requiring a localhost `Host` closes it.
+ *
+ * A request with no `Host` at all did not come from a browser (HTTP/1.0, curl,
+ * the test harness), and the remote-address gate still applies to it.
+ */
+export declare function hostVerdict(host: unknown): string | undefined;
+/**
+ * Verdict on a state-changing POST: `undefined` to proceed, otherwise the status
+ * and reason to refuse.
+ *
+ * Cross-origin writes are the hole the remote-address gate cannot see: a browser
+ * page may POST here as a「simple request」(text/plain, no preflight) and change
+ * settings or trigger a dial. Three independent checks close it:
+ *
+ * - `application/json` is not a simple-request content type, so a cross-origin
+ *   caller is forced into a preflight, which this route never answers with
+ *   `Access-Control-Allow-Origin`.
+ * - `Origin`, when it names an http(s) page, must be a localhost origin. Other
+ *   schemes are left to the next check: the host may load its UI through a
+ *   custom protocol, and a hostile page cannot produce one.
+ * - `Sec-Fetch-Site`, when present, must be `same-origin` (or `none`, a
+ *   user-initiated navigation with no referrer). This is what catches an opaque
+ *   `Origin: null` from a sandboxed iframe.
+ *
+ * Headers a non-browser client omits are not fabricatable by page script, so
+ * their absence is allowed rather than treated as a rejection.
+ */
+export declare function postVerdict(headers: Record<string, unknown>): {
+    status: number;
+    message: string;
+} | undefined;
 /**
  * Browser-facing backend: snapshot the settings namespace, save it with
  * optimistic concurrency, and test a draft account over a live IMAP login.
@@ -27,6 +158,16 @@ export declare class EmailSettingsBackend {
         };
         writable: boolean;
         accounts: string[];
+        accountsDetail: {
+            error?: string | undefined;
+            list: AccountCardData[];
+            defaultAccount?: string | undefined;
+        };
+        presets: {
+            custom: Record<string, ServerPreset>;
+            error?: string;
+            builtin: Record<string, ProviderPreset>;
+        };
         whale: {
             url: string;
             skin: boolean;
@@ -42,16 +183,59 @@ export declare class EmailSettingsBackend {
         };
         writable: boolean;
         accounts: string[];
+        accountsDetail: {
+            error?: string | undefined;
+            list: AccountCardData[];
+            defaultAccount?: string | undefined;
+        };
+        presets: {
+            custom: Record<string, ServerPreset>;
+            error?: string;
+            builtin: Record<string, ProviderPreset>;
+        };
         whale: {
             url: string;
             skin: boolean;
             credit: string;
         };
     }>;
-    test(value: EmailSettingsValue): Promise<{
+    /**
+     * Test one account (by name, defaulting to the draft's default account) over
+     * a live IMAP login. Returns the endpoint it dialled so the panel can show
+     * what was actually tried — including on failure.
+     */
+    test(value: EmailSettingsValue, accountName?: string): Promise<{
+        account: string;
+        imapHost: string;
+        imapPort: number;
         ok: boolean;
         ms: number;
     }>;
+    /**
+     * Resolve one named account of the *stored* settings — the same accounts the
+     * tools and the card list see. A login is not a draft operation: the settings
+     * page saves the card before it starts one, so the account being logged into
+     * is by definition already persisted.
+     */
+    private oauthAccount;
+    /**
+     * Start (or report) the device-code login for one OAuth2 account.
+     *
+     * An account that already holds a token answers `already` — the card shows
+     * 「已登录」and there is no second code to hand out. Otherwise the authority's
+     * device code is returned verbatim: url = verification_uri, code = user_code,
+     * and both interval and expires_in in seconds, which is the unit the page
+     * schedules its polling with.
+     */
+    oauthLogin(name: unknown): Promise<Record<string, unknown>>;
+    /**
+     * One poll of an in-flight device-code login.
+     *
+     * `authorization_pending` is the ordinary answer for as long as the user has
+     * not finished in the browser, so it is reported as a state rather than an
+     * error: only a refused or expired flow comes back as ok:false.
+     */
+    oauthPoll(name: unknown): Promise<Record<string, unknown>>;
     responseJson(res: any, status: number, body: unknown): void;
     handle(req: any, res: any): Promise<void>;
     /** GET-only localhost route serving the whale-girl courier image. */