dsh-email 0.10.7 → 0.11.0

package/lib/config.d.ts

@@ -1,4 +1,45 @@
+/** The 8 built-in provider ids. A `provider` may also name a custom preset. */
 export type ProviderName = 'qq' | '163' | '126' | 'sina' | 'aliyun' | 'gmail' | 'outlook' | 'icloud';
+/**
+ * A provider id as an account stores it: one of the built-in names, or the name
+ * of a custom `serverPresets` entry. The union keeps autocomplete for the
+ * built-ins while admitting a preset name the schema cannot know in advance.
+ */
+export type ProviderRef = ProviderName | (string & {});
+/**
+ * The provider that authenticates with OAuth2 instead of a password.
+ *
+ * Microsoft retired basic authentication for Exchange Online, so `outlook` is
+ * not a password provider with different endpoints — it is the same endpoints
+ * (imap/smtp.office365.com, straight out of PROVIDER_PRESETS) behind a
+ * completely different authentication scheme. `authKind` below is that fact.
+ */
+export declare const OUTLOOK_PROVIDER = "outlook";
+/** The Exchange Online IMAP host. Any account dialling it is an OAuth2 account. */
+export declare const OUTLOOK_IMAP_HOST = "outlook.office365.com";
+/**
+ * The built-in default client id for the device-code flow: deliberately empty.
+ *
+ * An earlier revision shipped a registration belonging to a contributor. That
+ * cannot be right for a package thousands of strangers install: the Microsoft
+ * consent screen would name someone else's application (which enterprise
+ * security teams refuse), the sign-in logs and telemetry would land in their
+ * tenant along with the user's UPN, and their deleting the app would break
+ * every login at once — with an error that only says the client id「可能填错了」,
+ * so no user could diagnose it.
+ *
+ * Nothing third-party is baked in, so an account supplies its own `clientId`
+ * (a free Entra public-client registration; the README walks through it) and
+ * `startDeviceFlow` refuses with an actionable message until one is set. A
+ * maintainer who registers an application for this project restores the
+ * out-of-box experience by filling in this one constant.
+ */
+export declare const OUTLOOK_OAUTH2_CLIENT_ID = "";
+/**
+ * How an account proves who it is. `password` covers every existing provider
+ * (an app password / 授权码) and is the default, so nothing about them changes.
+ */
+export type AuthKind = 'oauth2' | 'password';
 export interface ImapConfig {
     host?: string;
     port?: number;
@@ -13,9 +54,25 @@ export interface SmtpConfig {
 }
 /** One mailbox account. Top-level shorthand fields act as shared defaults. */
 export interface AccountConfig {
-    provider?: ProviderName;
+    /** Built-in provider name, or a custom serverPresets name. */
+    provider?: ProviderRef;
     user?: string;
     password?: string;
+    /**
+     * Public-client id used by the OAuth2 device-code flow. Only read for an
+     * OAuth2 account, where it overrides OUTLOOK_OAUTH2_CLIENT_ID.
+     */
+    clientId?: string;
+    /**
+     * Escape hatch over the derived authentication scheme. Left unset, an account
+     * pointed at the `outlook` provider or the Exchange Online IMAP host is an
+     * OAuth2 account and its password is dropped. Set `password` to keep using an
+     * app password there — a tenant that still accepts basic auth (hybrid or
+     * on-prem, SMTP AUTH left enabled), or a mailbox that worked before this
+     * derivation existed, must not be told「尚未登录」after an upgrade. Set
+     * `oauth2` to opt in from a custom host.
+     */
+    authKind?: AuthKind;
     imap?: ImapConfig;
     smtp?: SmtpConfig;
     inboxFolder?: string;
@@ -29,6 +86,12 @@ export interface EmailConfig extends AccountConfig {
     accounts?: Record<string, AccountConfig>;
     /** YAML text of the accounts map, editable from the settings page. Wins over accounts when non-empty. */
     accountsYaml?: string;
+    /**
+     * YAML text of the reusable server presets (connection endpoints only).
+     * Deliberately never part of ResolvedEmailSettings: editing a preset must not
+     * change the pool fingerprint and tear down live IMAP connections.
+     */
+    serverPresets?: string;
     /** Which account tools use when the call omits account. Required with 2+ accounts. */
     defaultAccount?: string;
     /** Directory email_attachment writes into. Default: the session workspace's .dsh-email-downloads (falls back to $DSH_HOME/email-downloads). */
@@ -54,13 +117,42 @@ export interface ProviderPreset {
         secure: boolean;
     };
 }
+/**
+ * Anything that can stand in for a provider: a built-in preset, or a custom
+ * `serverPresets` entry (whose port/secure are optional and whose label is
+ * editor-facing only). Both are looked up the same way.
+ */
+export interface EndpointPreset {
+    imap: {
+        host: string;
+        port?: number;
+        secure?: boolean;
+    };
+    smtp: {
+        host: string;
+        port?: number;
+        secure?: boolean;
+    };
+    label?: string;
+}
 export declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
 export declare const PROVIDER_NAMES: string[];
 export declare const EMAIL_PASSWORD_ENV = "DSH_EMAIL_PASSWORD";
 /** Fully resolved, validated configuration for one account. */
 export interface ResolvedEmailConfig {
     user: string;
+    /**
+     * The app password / 授权码. Empty for an OAuth2 account — that is the point:
+     * nothing is stored, the token store holds the credential instead.
+     */
     password: string;
+    /**
+     * How this account authenticates. Derived from `provider` / the IMAP host
+     * unless the account pins it with an explicit `authKind`.
+     */
+    authKind: AuthKind;
+    /** Public-client id for the device-code flow (OAuth2 accounts only). */
+    clientId?: string;
     imap: ImapConfig & {
         host: string;
         port: number;
@@ -73,6 +165,16 @@ export interface ResolvedEmailConfig {
     };
     inboxFolder: string;
 }
+/**
+ * True when an account authenticates with OAuth2 rather than a password.
+ *
+ * Two ways in, and only these two: the built-in `outlook` provider, or an
+ * account pointed at the Exchange Online IMAP host by hand (a custom preset or
+ * an explicit `imap.host`). The host test is what keeps a custom preset to
+ * outlook.office365.com from silently demanding a password Microsoft no longer
+ * accepts — the endpoints are identical, only the credentials are not.
+ */
+export declare function isOAuth2Account(provider: string | undefined, imapHost: string | undefined): boolean;
 /** Fully resolved plugin settings: the account map plus shared policy. */
 export interface ResolvedEmailSettings {
     accounts: Map<string, ResolvedEmailConfig>;
@@ -96,12 +198,50 @@ export declare function parseAccountsYaml(text: string): {
     map: Record<string, AccountConfig>;
     defaultAccount?: string;
 };
+/** Reusable IMAP/SMTP endpoints. Credentials are never stored in a preset. */
+export interface ServerPreset {
+    label?: string;
+    imap: {
+        host: string;
+        port?: number;
+        secure?: boolean;
+    };
+    smtp: {
+        host: string;
+        port?: number;
+        secure?: boolean;
+    };
+}
+/**
+ * Parse the settings-page server presets: a name -> endpoints map, e.g.
+ * `corp: { imap: { host: imap.corp }, smtp: { host: smtp.corp } }`.
+ * Blank text means "no presets"; a malformed document fails loud, because a
+ * silently dropped preset would only resurface later as an unresolvable
+ * account reference.
+ */
+export declare function parseServerPresets(text: string): Record<string, ServerPreset>;
+/**
+ * Serialize a raw accounts mapping (account name -> account config, optionally
+ * carrying a defaultAccount key) back into accountsYaml text.
+ *
+ * Returns '' when no account is left: resolveEmailSettings decides "is the YAML
+ * authoritative" with `.trim()`, so an empty list must never become '{}'.
+ */
+export declare function serializeAccountsYaml(raw: unknown, defaultAccount?: string): string;
 /**
  * Resolve and validate the raw row config. Throws with an actionable message
  * (in Chinese, since it is what the user and the model both read) when the
  * account is not fully specified.
  */
 export declare function resolveEmailSettings(config: EmailConfig | undefined): ResolvedEmailSettings;
+/** Every name a `provider:` may legally use, built-ins first. */
+export declare function providerNames(custom?: Record<string, ServerPreset>): string[];
+/**
+ * The custom preset names in a serverPresets text, best-effort: a malformed
+ * text yields no names instead of throwing. Callers use this to answer "may
+ * this provider name be written?", where a broken table can only mean "no".
+ */
+export declare function presetNamesIn(text: string | undefined): string[];
 /** v0.1-compatible wrapper: resolve the single (or default) account. */
 export declare function resolveEmailConfig(config: EmailConfig | undefined): ResolvedEmailConfig;
 export declare function clampInt(value: unknown, fallback: number, min: number, max: number): number;

package/lib/config.js

@@ -1,6 +1,35 @@
 import { homedir } from 'node:os';
-import { parse as parseYaml } from 'yaml';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { join } from 'node:path';
+/**
+ * The provider that authenticates with OAuth2 instead of a password.
+ *
+ * Microsoft retired basic authentication for Exchange Online, so `outlook` is
+ * not a password provider with different endpoints — it is the same endpoints
+ * (imap/smtp.office365.com, straight out of PROVIDER_PRESETS) behind a
+ * completely different authentication scheme. `authKind` below is that fact.
+ */
+export const OUTLOOK_PROVIDER = 'outlook';
+/** The Exchange Online IMAP host. Any account dialling it is an OAuth2 account. */
+export const OUTLOOK_IMAP_HOST = 'outlook.office365.com';
+/**
+ * The built-in default client id for the device-code flow: deliberately empty.
+ *
+ * An earlier revision shipped a registration belonging to a contributor. That
+ * cannot be right for a package thousands of strangers install: the Microsoft
+ * consent screen would name someone else's application (which enterprise
+ * security teams refuse), the sign-in logs and telemetry would land in their
+ * tenant along with the user's UPN, and their deleting the app would break
+ * every login at once — with an error that only says the client id「可能填错了」,
+ * so no user could diagnose it.
+ *
+ * Nothing third-party is baked in, so an account supplies its own `clientId`
+ * (a free Entra public-client registration; the README walks through it) and
+ * `startDeviceFlow` refuses with an actionable message until one is set. A
+ * maintainer who registers an application for this project restores the
+ * out-of-box experience by filling in this one constant.
+ */
+export const OUTLOOK_OAUTH2_CLIENT_ID = '';
 export const PROVIDER_PRESETS = {
     qq: { imap: { host: 'imap.qq.com', port: 993, secure: true }, smtp: { host: 'smtp.qq.com', port: 465, secure: true } },
     '163': { imap: { host: 'imap.163.com', port: 993, secure: true }, smtp: { host: 'smtp.163.com', port: 465, secure: true } },
@@ -15,6 +44,20 @@ export const PROVIDER_NAMES = Object.keys(PROVIDER_PRESETS);
 export const EMAIL_PASSWORD_ENV = 'DSH_EMAIL_PASSWORD';
 const DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
 const DEFAULT_IDLE_TIMEOUT_MS = 60000;
+/**
+ * True when an account authenticates with OAuth2 rather than a password.
+ *
+ * Two ways in, and only these two: the built-in `outlook` provider, or an
+ * account pointed at the Exchange Online IMAP host by hand (a custom preset or
+ * an explicit `imap.host`). The host test is what keeps a custom preset to
+ * outlook.office365.com from silently demanding a password Microsoft no longer
+ * accepts — the endpoints are identical, only the credentials are not.
+ */
+export function isOAuth2Account(provider, imapHost) {
+    if (provider === OUTLOOK_PROVIDER)
+        return true;
+    return (imapHost ?? '').trim().toLowerCase() === OUTLOOK_IMAP_HOST;
+}
 export function defaultDownloadDir() {
     const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
     return join(home, 'email-downloads');
@@ -46,6 +89,110 @@ export function parseAccountsYaml(text) {
     }
     return { map, defaultAccount };
 }
+/**
+ * Parse the settings-page server presets: a name -> endpoints map, e.g.
+ * `corp: { imap: { host: imap.corp }, smtp: { host: smtp.corp } }`.
+ * Blank text means "no presets"; a malformed document fails loud, because a
+ * silently dropped preset would only resurface later as an unresolvable
+ * account reference.
+ */
+export function parseServerPresets(text) {
+    if (text.trim() === '')
+        return {};
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch (error) {
+        throw new Error('dsh-email：serverPresets 不是合法的 YAML：' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new Error('dsh-email：serverPresets 不是合法的对象映射');
+    }
+    const presets = {};
+    for (const [name, value] of Object.entries(doc)) {
+        presets[name] = parseServerPreset(name, value);
+    }
+    return presets;
+}
+/** Validate one preset entry. Both endpoints are required; port/secure optional. */
+function parseServerPreset(name, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`dsh-email：服务器预设 "${name}" 必须是含 imap 与 smtp 的对象`);
+    }
+    const raw = value;
+    if (raw.label !== undefined && typeof raw.label !== 'string') {
+        throw new Error(`dsh-email：服务器预设 "${name}" 的 label 必须是字符串`);
+    }
+    return {
+        ...(raw.label !== undefined ? { label: raw.label } : {}),
+        imap: parseServerPresetEndpoint(name, 'imap', raw.imap),
+        smtp: parseServerPresetEndpoint(name, 'smtp', raw.smtp),
+    };
+}
+function parseServerPresetEndpoint(name, kind, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`dsh-email：服务器预设 "${name}" 缺少 ${kind}（需为含 host 的对象）`);
+    }
+    const raw = value;
+    const host = typeof raw.host === 'string' ? raw.host.trim() : '';
+    if (host === '')
+        throw new Error(`dsh-email：服务器预设 "${name}" 的 ${kind}.host 未填写`);
+    if (raw.port !== undefined && (typeof raw.port !== 'number' || !Number.isFinite(raw.port))) {
+        throw new Error(`dsh-email：服务器预设 "${name}" 的 ${kind}.port 必须是数字`);
+    }
+    if (raw.secure !== undefined && typeof raw.secure !== 'boolean') {
+        throw new Error(`dsh-email：服务器预设 "${name}" 的 ${kind}.secure 必须是布尔值`);
+    }
+    return {
+        host,
+        ...(raw.port !== undefined ? { port: raw.port } : {}),
+        ...(raw.secure !== undefined ? { secure: raw.secure } : {}),
+    };
+}
+/**
+ * Serialize a raw accounts mapping (account name -> account config, optionally
+ * carrying a defaultAccount key) back into accountsYaml text.
+ *
+ * Returns '' when no account is left: resolveEmailSettings decides "is the YAML
+ * authoritative" with `.trim()`, so an empty list must never become '{}'.
+ */
+export function serializeAccountsYaml(raw, defaultAccount) {
+    const doc = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    const accounts = {};
+    for (const [name, value] of Object.entries(doc)) {
+        if (name === 'defaultAccount')
+            continue;
+        accounts[name] = normalizeAccountForYaml(value);
+    }
+    if (Object.keys(accounts).length === 0)
+        return '';
+    const stored = typeof doc.defaultAccount === 'string' ? doc.defaultAccount.trim() : '';
+    const chosen = (defaultAccount ?? '').trim() || stored;
+    const out = { ...accounts };
+    if (chosen !== '')
+        out.defaultAccount = chosen;
+    return stringifyYaml(out, { aliasDuplicateObjects: false, lineWidth: 0 });
+}
+/**
+ * Prepare one account entry for the YAML writer.
+ *
+ * `provider` disappears when unset or '' — the settings page uses '' for
+ * "custom server", and writing it back would make resolution throw
+ * 「provider "" 未知」 (same normalization as toEmailConfig). A numeric
+ * password is coerced to a string so the writer quotes it: YAML would
+ * otherwise read `password: 123456` back as a number.
+ */
+function normalizeAccountForYaml(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value ?? {};
+    const account = { ...value };
+    if (account.provider === undefined || account.provider === '')
+        delete account.provider;
+    if (typeof account.password === 'number' || typeof account.password === 'boolean')
+        account.password = String(account.password);
+    return account;
+}
 /**
  * Resolve and validate the raw row config. Throws with an actionable message
  * (in Chinese, since it is what the user and the model both read) when the
@@ -57,6 +204,8 @@ export function resolveEmailSettings(config) {
         provider: raw.provider,
         user: raw.user,
         password: raw.password,
+        clientId: raw.clientId,
+        authKind: raw.authKind,
         imap: raw.imap,
         smtp: raw.smtp,
         inboxFolder: raw.inboxFolder,
@@ -65,13 +214,26 @@ export function resolveEmailSettings(config) {
     const entries = parsedYaml !== undefined
         ? parsedYaml.map
         : (raw.accounts === undefined || Object.keys(raw.accounts).length === 0 ? undefined : raw.accounts);
+    // The custom preset table is read once, here, and never stored on the result:
+    // it is a lookup source for provider names, not part of the resolved config.
+    // A broken preset text degrades to "no custom presets" — the account-level
+    // error below stays explicit about which name could not be resolved.
+    let customPresets = {};
+    try {
+        customPresets = parseServerPresets(raw.serverPresets ?? '');
+    }
+    catch {
+        customPresets = {};
+    }
+    const providers = providerTable(customPresets);
+    const known = providerNames(customPresets);
     const accounts = new Map();
     if (entries === undefined) {
-        accounts.set('default', resolveAccount('default', common, {}, true));
+        accounts.set('default', resolveAccount('default', common, {}, true, providers, known));
     }
     else {
         for (const [name, acc] of Object.entries(entries)) {
-            accounts.set(name, resolveAccount(name, common, acc ?? {}, false));
+            accounts.set(name, resolveAccount(name, common, acc ?? {}, false, providers, known));
         }
     }
     let defaultName;
@@ -106,11 +268,52 @@ export function resolveEmailSettings(config) {
         bodySearchLimit: clampInt(raw.bodySearchLimit, 30, 5, 200),
     };
 }
+/**
+ * The provider lookup order: the 8 built-ins first, then the custom presets.
+ * A built-in name always wins, so a custom preset cannot shadow `qq` — and an
+ * inherited Object member (`constructor`, `toString`) is never a provider.
+ *
+ * The table has a null prototype on purpose: a plain `{}` answers
+ * `table['constructor']` with Object's own constructor through the prototype
+ * chain, which would be mistaken for a preset and then blow up on `.imap.host`.
+ */
+function providerTable(custom) {
+    const table = Object.create(null);
+    for (const [name, preset] of Object.entries(PROVIDER_PRESETS))
+        table[name] = preset;
+    for (const [name, preset] of Object.entries(custom)) {
+        if (table[name] === undefined)
+            table[name] = preset;
+    }
+    return table;
+}
+/** Every name a `provider:` may legally use, built-ins first. */
+export function providerNames(custom = {}) {
+    const names = [...PROVIDER_NAMES];
+    for (const name of Object.keys(custom))
+        if (!names.includes(name))
+            names.push(name);
+    return names;
+}
+/**
+ * The custom preset names in a serverPresets text, best-effort: a malformed
+ * text yields no names instead of throwing. Callers use this to answer "may
+ * this provider name be written?", where a broken table can only mean "no".
+ */
+export function presetNamesIn(text) {
+    try {
+        return Object.keys(parseServerPresets(text ?? ''));
+    }
+    catch {
+        return [];
+    }
+}
 /** Merge one account over the shared shorthand and validate it. */
-function resolveAccount(name, common, acc, allowEnvPassword) {
-    const preset = acc.provider === undefined ? PROVIDER_PRESETS[common.provider ?? ''] : PROVIDER_PRESETS[acc.provider];
-    if ((acc.provider ?? common.provider) !== undefined && preset === undefined) {
-        throw new Error(`dsh-email：账号 "${name}" 的 provider "${acc.provider ?? common.provider}" 未知，可选：${PROVIDER_NAMES.join('/')}；或省略 provider 直接填 imap.host 与 smtp.host`);
+function resolveAccount(name, common, acc, allowEnvPassword, providers, known) {
+    const requested = acc.provider ?? common.provider;
+    const preset = requested === undefined ? undefined : providers[requested];
+    if (requested !== undefined && preset === undefined) {
+        throw new Error(`dsh-email：账号 "${name}" 的 provider "${requested}" 未知，可选：${known.join('/')}；或省略 provider 直接填 imap.host 与 smtp.host`);
     }
     const user = (acc.user ?? common.user ?? '').trim();
     // The settings form uses '' for an empty password. In single-account mode
@@ -131,18 +334,36 @@ function resolveAccount(name, common, acc, allowEnvPassword) {
     const problems = [];
     if (user === '')
         problems.push(`账号 "${name}" 的 user（邮箱地址）未填写`);
-    if (password === '')
+    // An explicit `authKind` outranks the derivation: a tenant that still accepts
+    // an app password for Exchange Online, or a mailbox that worked before the
+    // derivation existed, keeps working instead of being told「尚未登录」.
+    const forcedAuthKind = String(acc.authKind ?? common.authKind ?? '').trim().toLowerCase();
+    if (forcedAuthKind !== '' && forcedAuthKind !== 'oauth2' && forcedAuthKind !== 'password') {
+        problems.push(`账号 "${name}" 的 authKind 只能是 oauth2 或 password，当前是 "${forcedAuthKind}"`);
+    }
+    const oauth2 = forcedAuthKind === 'password'
+        ? false
+        : forcedAuthKind === 'oauth2' || isOAuth2Account(requested, imap.host);
+    // An OAuth2 account has no password on purpose: its credential is the token
+    // in the OAuth2 store, and requiring a password would demand a secret
+    // Microsoft no longer accepts for Exchange Online.
+    if (!oauth2 && password === '')
         problems.push(`账号 "${name}" 的 password 未填写（单账号可用环境变量 ${EMAIL_PASSWORD_ENV}）`);
     if (imap.host === undefined || imap.host === '')
-        problems.push(`账号 "${name}" 的 imap.host 未填写（可填 provider 预设：${PROVIDER_NAMES.join('/')}）`);
+        problems.push(`账号 "${name}" 的 imap.host 未填写（可填 provider 预设：${known.join('/')}）`);
     if (smtp.host === undefined || smtp.host === '')
         problems.push(`账号 "${name}" 的 smtp.host 未填写（同上）`);
     if (problems.length > 0) {
         throw new Error(`dsh-email 未配置：${problems.join('；')}。请在 profile 的 cordis.patch.yml 中覆盖 tool-email 行并重启（见插件 README）`);
     }
+    const clientId = (acc.clientId ?? common.clientId ?? '').trim();
     return {
         user,
-        password,
+        // An OAuth2 account never carries a password: a stale one left in the YAML
+        // from before the provider changed must not travel into the pool.
+        password: oauth2 ? '' : password,
+        authKind: oauth2 ? 'oauth2' : 'password',
+        ...(clientId !== '' ? { clientId } : {}),
         imap: { ...imap, host: imap.host, port: imap.port, secure: imap.secure },
         smtp: { ...smtp, host: smtp.host, port: smtp.port, secure: smtp.secure },
         inboxFolder: (acc.inboxFolder ?? common.inboxFolder ?? '').trim() || 'INBOX',

package/lib/index.d.ts

@@ -4,9 +4,13 @@ export declare const inject: string[];
 export type Config = EmailConfig;
 /** Compose settings/pool lifecycle, tools, browser routes and the outgoing-mail gate. */
 export declare function apply(ctx: any, config?: Config): void;
-export { clampInt, defaultDownloadDir, EMAIL_PASSWORD_ENV, parseAccountsYaml, PROVIDER_NAMES, resolveEmailConfig, resolveEmailSettings } from './config.js';
-export { buildReplyMessage, EmailPool, extractMessageIds, MailError, messageMatchesQuery, messageOf, selectAttachmentPart, validateAttachmentPaths } from './mail-client.js';
+export { clampInt, defaultDownloadDir, EMAIL_PASSWORD_ENV, isOAuth2Account, OUTLOOK_OAUTH2_CLIENT_ID, OUTLOOK_PROVIDER, parseAccountsYaml, parseServerPresets, presetNamesIn, providerNames, PROVIDER_NAMES, resolveEmailConfig, resolveEmailSettings, serializeAccountsYaml } from './config.js';
+export type { AuthKind, ResolvedEmailConfig } from './config.js';
+export { ACCESS_TOKEN_MARGIN_MS, classifyOAuthFailure, clearTokenFor, DEVICE_CODE_URL, getFreshAccessToken, mapAadstsMessage, NO_CLIENT_ID_MESSAGE, NOT_LOGGED_IN_MESSAGE, oauth2StateOf, oauth2TokenFile, OAUTH2_SCOPES, OAuth2Error, pollDeviceFlow, readTokenStore, startDeviceFlow, TOKEN_URL, writeTokenStore, } from './oauth2.js';
+export type { DeviceFlowStart, OAuth2PollResult, OAuth2State, OAuth2TokenEntry, OAuth2TokenStore } from './oauth2.js';
+export { buildReplyMessage, EmailPool, extractMessageIds, imapAuthOf, looksLikeAuthFailure, MailError, messageMatchesQuery, messageOf, OAUTH2_RELOGIN_MESSAGE, redactCredentials, selectAttachmentPart, smtpAuthOf, validateAttachmentPaths } from './mail-client.js';
 export { flattenAddresses, parseRawMessage, sanitizeFilename, stripHtml, truncateText } from './parse.js';
 export { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
 export { parseEmailDay } from './tool-contract.js';
 export { EmailSettingsBackend, installEmailSettingsWeb, SETTINGS_ROUTE } from './web.js';
+export type { AccountCardData, AccountCardInput } from './web.js';

package/lib/index.js

@@ -14,8 +14,9 @@ export function apply(ctx, config = {}) {
         ctx.tools.register(definition);
     installSendApproval(ctx, runtime);
 }
-export { clampInt, defaultDownloadDir, EMAIL_PASSWORD_ENV, parseAccountsYaml, PROVIDER_NAMES, resolveEmailConfig, resolveEmailSettings } from './config.js';
-export { buildReplyMessage, EmailPool, extractMessageIds, MailError, messageMatchesQuery, messageOf, selectAttachmentPart, validateAttachmentPaths } from './mail-client.js';
+export { clampInt, defaultDownloadDir, EMAIL_PASSWORD_ENV, isOAuth2Account, OUTLOOK_OAUTH2_CLIENT_ID, OUTLOOK_PROVIDER, parseAccountsYaml, parseServerPresets, presetNamesIn, providerNames, PROVIDER_NAMES, resolveEmailConfig, resolveEmailSettings, serializeAccountsYaml } from './config.js';
+export { ACCESS_TOKEN_MARGIN_MS, classifyOAuthFailure, clearTokenFor, DEVICE_CODE_URL, getFreshAccessToken, mapAadstsMessage, NO_CLIENT_ID_MESSAGE, NOT_LOGGED_IN_MESSAGE, oauth2StateOf, oauth2TokenFile, OAUTH2_SCOPES, OAuth2Error, pollDeviceFlow, readTokenStore, startDeviceFlow, TOKEN_URL, writeTokenStore, } from './oauth2.js';
+export { buildReplyMessage, EmailPool, extractMessageIds, imapAuthOf, looksLikeAuthFailure, MailError, messageMatchesQuery, messageOf, OAUTH2_RELOGIN_MESSAGE, redactCredentials, selectAttachmentPart, smtpAuthOf, validateAttachmentPaths } from './mail-client.js';
 export { flattenAddresses, parseRawMessage, sanitizeFilename, stripHtml, truncateText } from './parse.js';
 export { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
 export { parseEmailDay } from './tool-contract.js';

package/lib/mail-client.d.ts

@@ -5,6 +5,62 @@ export declare class MailError extends Error {
     constructor(message: string);
 }
 export declare function messageOf(error: unknown, fallback: string): string;
+/**
+ * Replace anything credential-shaped in a server's own error text before it
+ * reaches a user.
+ *
+ * IMAP and SMTP servers routinely quote back the authentication string they
+ * rejected. For XOAUTH2 that string is `user=…\x01auth=Bearer <token>\x01\x01`,
+ * usually base64'd — so the raw message carries a live access token, and these
+ * messages are rendered in the settings panel, returned by the mail tools, and
+ * pasted into bug reports.
+ *
+ * Two shapes are masked: a JWT (three base64url segments, which is what every
+ * OAuth2 access token looks like) and a long base64 run (the quoted XOAUTH2
+ * blob). The replacement keeps the length so a report still says how big the
+ * thing was, without saying what it was.
+ */
+export declare function redactCredentials(text: string): string;
+/** The IMAP auth shape imapflow accepts: a password, or an OAuth2 access token. */
+export interface ImapAuth {
+    user: string;
+    pass?: string;
+    accessToken?: string;
+}
+/**
+ * The SMTP auth shape nodemailer accepts. `type` is the literal union
+ * nodemailer's typings model, not a loose string: anything wider makes the
+ * whole transport options object fail to match and silently degrades the type.
+ */
+export type SmtpAuth = {
+    user: string;
+    pass: string;
+} | {
+    type: 'OAuth2';
+    user: string;
+    accessToken: string;
+};
+/**
+ * The IMAP `auth` block for one account. Pure so the shape the library
+ * receives is testable without a socket: an OAuth2 account authenticates with
+ * `accessToken` (imapflow then runs AUTHENTICATE XOAUTH2) and a password
+ * account with `pass`, exactly as before.
+ */
+export declare function imapAuthOf(cfg: Pick<ResolvedEmailConfig, 'user' | 'password' | 'authKind'>, accessToken?: string): ImapAuth;
+/**
+ * Nodemailer consumes an OAuth2 token through accessToken, not pass.
+ * Refresh remains owned by this plugin; no refresh credentials leave here.
+ */
+export declare function smtpAuthOf(cfg: Pick<ResolvedEmailConfig, 'user' | 'password' | 'authKind'>, accessToken?: string): SmtpAuth;
+/** The message an OAuth2 account gets when the mailbox has to be logged into again. */
+export declare const OAUTH2_RELOGIN_MESSAGE = "\u90AE\u7BB1\u767B\u5F55\u5931\u8D25\uFF1A\u8BF7\u5230\u8BBE\u7F6E\u9875\u91CD\u65B0\u767B\u5F55\uFF08Microsoft \u8D26\u53F7\u4F7F\u7528\u8BBE\u5907\u7801\u767B\u5F55\uFF0C\u4E0D\u4F7F\u7528\u6388\u6743\u7801\uFF09";
+/**
+ * True for the errors both libraries report when the server rejects the
+ * credentials. An expired access token is indistinguishable from a wrong
+ * password at this level, so the connection retries once with a forced refresh
+ * before it believes the token is really dead.
+ */
+export declare function looksLikeAuthFailure(error: unknown): boolean;
 interface AttachmentPart {
     part: string;
     filename: string;
@@ -68,17 +124,50 @@ export declare class EmailPool {
     private enqueue;
     withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>, readOnly?: boolean, signal?: AbortSignal): Promise<T>;
     private createImap;
+    /**
+     * Dial and authenticate one fresh IMAP connection.
+     *
+     * A password account connects once. An OAuth2 account connects with a fresh
+     * access token and, when the server rejects it, refreshes once and tries
+     * again: a token that expired between the freshness check and the dial is
+     * indistinguishable from a wrong password at the socket, and guessing wrong
+     * would send the user through a browser login for nothing.
+     */
+    private connectImap;
+    /** The token store's own errors are already actionable; never dress them as IMAP failures. */
+    private oauth2ErrorOf;
     private imapRun;
     private normalizeImapError;
     private evictImap;
     /** Reap IMAP connections idle for longer than idleTimeoutMs. */
     startIdleSweep(): void;
     dispose(): void;
+    /**
+     * A pooled transporter for one account. The token is captured when the
+     * transporter is built; an OAuth2 token that turns out to be stale is
+     * re-minted in sendMail, which rebuilds the transporter.
+     */
     private transporter;
-    /** Send through the pooled transporter while making cancellation close it. */
+    private dropTransporter;
+    /**
+     * Send through the pooled transporter while making cancellation close it.
+     *
+     * An OAuth2 transporter carries a token that was minted when it was built,
+     * so a rejection is retried once against a freshly built one (and a fresh
+     * form of whatever stored token state exists). Password accounts keep the
+     * single attempt they always had.
+     */
     private sendMail;
     list(accountName: string | undefined, folder: string, limit: number, offset: number, unreadOnly: boolean, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailListResult>;
     search(accountName: string | undefined, query: string, folder: string, limit: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
+    /**
+     * Confirm server-side hits against the mailbox itself: fetch the envelopes
+     * of the newest candidates — the same window the body-scan fallback looks at
+     * — and keep only those that really carry the query in subject/from/to/cc,
+     * the four fields the server was asked about. No body is downloaded here,
+     * and uids the server made up simply return nothing.
+     */
+    private searchHits;
     /** Client-side scan of the tail of the mailbox, newest first. */
     private searchBodies;
     private fetchListed;