dsh-email 0.10.7 → 0.11.0

package/lib/mail-client.js

@@ -2,6 +2,7 @@ import { ImapFlow } from 'imapflow';
 import nodemailer from 'nodemailer';
 import { mkdir, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { getFreshAccessToken, OAuth2Error } from './oauth2.js';
 import { flattenAddresses, parseRawMessage, sanitizeFilename } from './parse.js';
 export class MailError extends Error {
     constructor(message) {
@@ -12,6 +13,66 @@ export class MailError extends Error {
 export function messageOf(error, fallback) {
     return error instanceof Error && error.message !== '' ? error.message : fallback;
 }
+/**
+ * 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 function redactCredentials(text) {
+    return text
+        .replace(/[A-Za-z0-9_-]{12,}\.[A-Za-z0-9_-]{12,}\.[A-Za-z0-9_-]{8,}/g, match => `<已隐去 ${match.length} 字符的令牌>`)
+        .replace(/[A-Za-z0-9+/]{40,}={0,2}/g, match => `<已隐去 ${match.length} 字符的凭据>`);
+}
+/**
+ * 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 function imapAuthOf(cfg, accessToken) {
+    return cfg.authKind === 'oauth2'
+        ? { user: cfg.user, accessToken: accessToken ?? '' }
+        : { user: cfg.user, pass: cfg.password };
+}
+/**
+ * Nodemailer consumes an OAuth2 token through accessToken, not pass.
+ * Refresh remains owned by this plugin; no refresh credentials leave here.
+ */
+export function smtpAuthOf(cfg, accessToken) {
+    return cfg.authKind === 'oauth2'
+        ? { type: 'OAuth2', user: cfg.user, accessToken: accessToken ?? '' }
+        : { user: cfg.user, pass: cfg.password };
+}
+/** The message an OAuth2 account gets when the mailbox has to be logged into again. */
+export const OAUTH2_RELOGIN_MESSAGE = '邮箱登录失败：请到设置页重新登录（Microsoft 账号使用设备码登录，不使用授权码）';
+/**
+ * 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 function looksLikeAuthFailure(error) {
+    const raw = messageOf(error, '').toLowerCase();
+    if (raw === '')
+        return false;
+    return raw.includes('authentication')
+        || raw.includes('authenticate')
+        || raw.includes('auth failed')
+        || raw.includes('login')
+        || raw.includes('command failed')
+        || raw.includes('invalid credentials')
+        || raw.includes('xoauth2');
+}
 /** True when any bodyStructure node declares an attachment disposition. */
 function structureHasAttachment(node) {
     if (node === null || node === undefined || typeof node !== 'object')
@@ -209,12 +270,12 @@ export class EmailPool {
         const cfg = this.account(name);
         return this.enqueue(name, () => this.imapRun(name, cfg, folder, readOnly, run, signal), signal);
     }
-    createImap(cfg) {
+    createImap(auth, cfg) {
         const client = new ImapFlow({
             host: cfg.imap.host,
             port: cfg.imap.port,
             secure: cfg.imap.secure,
-            auth: { user: cfg.user, pass: cfg.password },
+            auth,
             logger: false,
             connectionTimeout: cfg.imap.connectionTimeoutMs ?? 30000,
             greetingTimeout: 30000,
@@ -234,6 +295,54 @@ export class EmailPool {
         });
         return client;
     }
+    /**
+     * 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.
+     */
+    async connectImap(name, cfg, forceToken = false) {
+        const oauth2 = cfg.authKind === 'oauth2';
+        const attempt = async (token) => {
+            const client = this.createImap(imapAuthOf(cfg, token), cfg);
+            await client.connect();
+            return client;
+        };
+        let token;
+        if (oauth2) {
+            try {
+                token = await getFreshAccessToken(name, cfg, { force: forceToken });
+            }
+            catch (error) {
+                throw this.oauth2ErrorOf(error);
+            }
+        }
+        try {
+            return await attempt(token);
+        }
+        catch (error) {
+            if (!oauth2 || !looksLikeAuthFailure(error))
+                throw error;
+            try {
+                token = await getFreshAccessToken(name, cfg, { force: true });
+            }
+            catch (refreshError) {
+                throw this.oauth2ErrorOf(refreshError);
+            }
+            return await attempt(token);
+        }
+    }
+    /** The token store's own errors are already actionable; never dress them as IMAP failures. */
+    oauth2ErrorOf(error) {
+        if (error instanceof OAuth2Error)
+            return new MailError(error.message);
+        if (error instanceof MailError)
+            return error;
+        return new MailError(OAUTH2_RELOGIN_MESSAGE + '（' + redactCredentials(messageOf(error, '未知错误')) + '）');
+    }
     async imapRun(name, cfg, folder, readOnly, run, signal) {
         let entry = this.imaps.get(name);
         let activeClient = entry?.client;
@@ -252,11 +361,9 @@ export class EmailPool {
             if (entry === undefined || !entry.client.usable) {
                 if (entry !== undefined)
                     await this.evictImap(name);
-                const client = this.createImap(cfg);
+                const client = await this.connectImap(name, cfg);
                 activeClient = client;
                 signal?.throwIfAborted();
-                await client.connect();
-                signal?.throwIfAborted();
                 entry = { client, selected: null, selectedReadOnly: true, lastUsed: Date.now(), inUse: 0 };
                 this.imaps.set(name, entry);
             }
@@ -279,7 +386,7 @@ export class EmailPool {
         catch (error) {
             await this.evictImap(name);
             signal?.throwIfAborted();
-            throw this.normalizeImapError(error, folder);
+            throw this.normalizeImapError(error, folder, cfg.authKind);
         }
         finally {
             signal?.removeEventListener('abort', onAbort);
@@ -287,11 +394,14 @@ export class EmailPool {
                 entry.inUse = Math.max(0, entry.inUse - 1);
         }
     }
-    normalizeImapError(error, folder) {
+    normalizeImapError(error, folder, authKind = 'password') {
         const raw = messageOf(error, 'IMAP 操作失败');
         const lower = raw.toLowerCase();
         if (lower.includes('authentication') || lower.includes('login')) {
-            return new MailError('邮箱登录失败：' + raw + '（请检查 user 与授权码）');
+            // An OAuth2 account has no 授权码 to check: the only fix is a new login.
+            return new MailError(authKind === 'oauth2'
+                ? OAUTH2_RELOGIN_MESSAGE + '（' + raw + '）'
+                : '邮箱登录失败：' + raw + '（请检查 user 与授权码）');
         }
         if (lower.includes('nonselect') || lower.includes('does not exist') || lower.includes('nonexistent')) {
             return new MailError('找不到邮箱文件夹 "' + (folder ?? '') + '"：' + raw);
@@ -333,7 +443,12 @@ export class EmailPool {
             transporter.close();
         this.smtps.clear();
     }
-    transporter(name, cfg) {
+    /**
+     * 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.
+     */
+    transporter(name, cfg, accessToken) {
         let t = this.smtps.get(name);
         if (t === undefined) {
             t = nodemailer.createTransport({
@@ -341,7 +456,7 @@ export class EmailPool {
                 host: cfg.smtp.host,
                 port: cfg.smtp.port,
                 secure: cfg.smtp.secure,
-                auth: { user: cfg.user, pass: cfg.password },
+                auth: smtpAuthOf(cfg, accessToken),
                 connectionTimeout: 30000,
                 greetingTimeout: 10000,
                 socketTimeout: 60000,
@@ -352,27 +467,62 @@ export class EmailPool {
         }
         return t;
     }
-    /** Send through the pooled transporter while making cancellation close it. */
+    dropTransporter(name, transporter) {
+        if (this.smtps.get(name) === transporter)
+            this.smtps.delete(name);
+        transporter.close();
+    }
+    /**
+     * 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.
+     */
     async sendMail(name, cfg, message, signal) {
         signal?.throwIfAborted();
-        const transporter = this.transporter(name, cfg);
-        const onAbort = () => {
-            if (this.smtps.get(name) === transporter)
-                this.smtps.delete(name);
-            transporter.close();
+        const attempt = async (forceToken) => {
+            const token = cfg.authKind === 'oauth2' ? await getFreshAccessToken(name, cfg, { force: forceToken }) : undefined;
+            const transporter = this.transporter(name, cfg, token);
+            const onAbort = () => {
+                this.dropTransporter(name, transporter);
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                const info = await transporter.sendMail(message);
+                signal?.throwIfAborted();
+                return info;
+            }
+            finally {
+                signal?.removeEventListener('abort', onAbort);
+            }
         };
-        signal?.addEventListener('abort', onAbort, { once: true });
         try {
-            const info = await transporter.sendMail(message);
-            signal?.throwIfAborted();
-            return info;
+            return await attempt(false);
         }
         catch (error) {
             signal?.throwIfAborted();
-            throw error;
-        }
-        finally {
-            signal?.removeEventListener('abort', onAbort);
+            if (cfg.authKind !== 'oauth2')
+                throw error;
+            // A pooled connection that already authenticated can fail for reasons no
+            // token can fix (a rejected recipient, a full mailbox). Only a credential
+            // rejection is worth a second, freshly-tokened attempt — and a token
+            // store that refused outright is reported as itself.
+            if (!looksLikeAuthFailure(error))
+                throw this.oauth2ErrorOf(error);
+            // The cached transporter holds the old token: it has to go, or the retry
+            // would reuse the very credential that was just refused.
+            const stale = this.smtps.get(name);
+            if (stale !== undefined)
+                this.dropTransporter(name, stale);
+            try {
+                return await attempt(true);
+            }
+            catch (retryError) {
+                signal?.throwIfAborted();
+                throw this.oauth2ErrorOf(retryError);
+            }
         }
     }
     async list(accountName, folder, limit, offset, unreadOnly, since, until, signal) {
@@ -416,8 +566,12 @@ export class EmailPool {
         const folderName = folder || cfg.inboxFolder;
         return this.withImap(name, folderName, async (client) => {
             // No nested OR and no TEXT search: several servers (QQ among them)
-            // silently answer those with empty or match-everything results.
-            // subject/from/to/cc searches unioned client-side behave well everywhere.
+            // silently answer those with empty results, and some answer with a
+            // non-empty list that has nothing to do with the query at all (QQ again:
+            // an impossible keyword still「matches」every uid in the folder). The
+            // server's hit list is therefore a hint, not an answer: confirm it
+            // against the envelopes before reporting anything, otherwise scan
+            // locally.
             const dateRange = {};
             if (since !== undefined)
                 dateRange.since = since;
@@ -430,18 +584,45 @@ export class EmailPool {
                 client.search({ cc: query, ...dateRange }, { uid: true }),
             ]);
             signal?.throwIfAborted();
-            const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => a - b);
-            uids.reverse();
-            if (uids.length === 0 && this.settings.bodySearchFallback) {
-                // Server-side search found nothing: fall back to a client-side scan of
-                // the most recent messages (subject/from/body), capped for time.
+            const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => b - a);
+            if (uids.length > 0) {
+                const confirmed = await this.searchHits(client, uids, query, limit, signal);
+                if (confirmed.length > 0) {
+                    // The server's list holds up, so its size is reported as the match
+                    // count; only rows that were confirmed are ever handed out.
+                    return { account: name, query, count: uids.length, folder: folderName, messages: confirmed.slice(0, limit) };
+                }
+            }
+            // Nothing believable came back (empty answer, or hits that did not
+            // survive verification): scan the newest messages locally instead.
+            if (this.settings.bodySearchFallback) {
                 const messages = await this.searchBodies(client, query, folderName, limit, since, until, signal);
                 return { account: name, query, count: messages.length, folder: folderName, messages };
             }
-            const messages = await this.fetchListed(client, uids.slice(0, limit), signal);
-            return { account: name, query, count: uids.length, folder: folderName, messages };
+            return { account: name, query, count: 0, folder: folderName, messages: [] };
         }, true, signal);
     }
+    /**
+     * 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.
+     */
+    async searchHits(client, uids, query, limit, signal) {
+        const sample = uids.slice(0, Math.min(uids.length, Math.max(this.settings.bodySearchLimit, limit)));
+        signal?.throwIfAborted();
+        const fetched = await client.fetchAll(sample, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
+        signal?.throwIfAborted();
+        return fetched
+            .filter(message => {
+            const envelope = message.envelope;
+            const addressText = [envelope?.from, envelope?.to, envelope?.cc].map(flattenAddressText).join(' ');
+            return messageMatchesQuery(envelope?.subject ?? '', addressText, '', query);
+        })
+            .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
+            .sort((a, b) => b.uid - a.uid);
+    }
     /** Client-side scan of the tail of the mailbox, newest first. */
     async searchBodies(client, query, folder, limit, since, until, signal) {
         signal?.throwIfAborted();

package/lib/oauth2.d.ts

@@ -0,0 +1,124 @@
+import { type ResolvedEmailConfig } from './config.js';
+/** The authority that serves both endpoints. `common` accepts any work/school/personal tenant. */
+export declare const OAUTH2_TENANT = "common";
+export declare const DEVICE_CODE_URL: string;
+export declare const TOKEN_URL: string;
+/**
+ * The delegated permissions the plugin needs: offline_access (a refresh token),
+ * IMAP.AccessAsUser.All and SMTP.Send. All three must be granted on the app
+ * registration, otherwise the token request answers AADSTS65001.
+ */
+export declare const OAUTH2_SCOPES: string[];
+export declare const OAUTH2_SCOPE_TEXT: string;
+/** Reuse an access token only while this much of its life is left. */
+export declare const ACCESS_TOKEN_MARGIN_MS: number;
+/** Every request to the authority is bounded: a hung login must not hang a mail tool. */
+export declare const OAUTH2_REQUEST_TIMEOUT_MS = 15000;
+/** The one message every「no token yet」path reports, so the fix is always the same. */
+export declare const NOT_LOGGED_IN_MESSAGE = "\u5C1A\u672A\u767B\u5F55\uFF1A\u8BF7\u5148\u5728\u8BBE\u7F6E\u9875\u5B8C\u6210\u8BBE\u5907\u7801\u767B\u5F55";
+/**
+ * Reported when an OAuth2 account has no application to log in through. The
+ * plugin ships no third-party registration, so this is a setup step, not a
+ * failure — and it says where to go and what to type.
+ */
+export declare const NO_CLIENT_ID_MESSAGE = "\u5C1A\u672A\u914D\u7F6E OAuth2 \u5E94\u7528\uFF1A\u8BF7\u5728\u8BBE\u7F6E\u9875\u8BE5\u8D26\u53F7\u7684\u300C\u5E94\u7528\uFF08\u5BA2\u6237\u7AEF\uFF09ID\u300D\u91CC\u586B\u5165\u4F60\u81EA\u5DF1\u6CE8\u518C\u7684 Azure \u516C\u5171\u5BA2\u6237\u7AEF ID\uFF08\u514D\u8D39\uFF0C\u6CE8\u518C\u6B65\u9AA4\u89C1 README \u7684\u300COutlook OAuth2\u300D\u4E00\u8282\uFF09\u3002\u672C\u63D2\u4EF6\u4E0D\u5185\u7F6E\u4EFB\u4F55\u7B2C\u4E09\u65B9\u5E94\u7528\u6CE8\u518C\uFF0C\u56E0\u6B64\u6CA1\u6709\u5B83\u5C31\u65E0\u6CD5\u5F00\u59CB\u8BBE\u5907\u7801\u767B\u5F55";
+/** Where the refresh/access tokens live. Kept out of the settings namespace on purpose. */
+export declare function oauth2TokenFile(): string;
+export interface OAuth2TokenEntry {
+    /** The mailbox address the token was issued for. */
+    user: string;
+    clientId: string;
+    refreshToken: string;
+    accessToken: string;
+    /** Absolute ms timestamp; 0 means「unknown, treat as expired」. */
+    expiresAt: number;
+}
+export interface OAuth2TokenStore {
+    version: 1;
+    accounts: Record<string, OAuth2TokenEntry>;
+}
+/** The part of a resolved account this module needs. */
+export type OAuth2AccountConfig = Pick<ResolvedEmailConfig, 'user' | 'clientId'>;
+/** Raised for every expected OAuth2 failure; the message is already user-facing Chinese. */
+export declare class OAuth2Error extends Error {
+    constructor(message: string);
+}
+export interface DeviceFlowStart {
+    /** verification_uri: the page the user opens. */
+    url: string;
+    /** user_code: what the user types there. */
+    code: string;
+    /** Seconds between two polls, as the authority asked. */
+    interval: number;
+    /** Seconds until the device code itself expires. */
+    expiresIn: number;
+}
+/** The Chinese guidance for an AADSTS code, or undefined when it is not mapped. */
+export declare function mapAadstsMessage(code: string | number): string | undefined;
+interface OAuthFailure {
+    /** authorization_pending / slow_down: keep polling. */
+    pending: boolean;
+    /** slow_down: the poll interval must grow. */
+    slowDown: boolean;
+    /** invalid_grant: the stored refresh token is dead and must be dropped. */
+    clearToken: boolean;
+    message: string;
+    code: string;
+}
+/**
+ * Turn one failed token/device-code response into a verdict. `pending` is a
+ * normal state, not an error: the user simply has not finished in the browser.
+ */
+export declare function classifyOAuthFailure(payload: unknown, httpStatus?: number): OAuthFailure;
+/** Read the store. A missing or unreadable file is 「no tokens」, never a crash. */
+export declare function readTokenStore(): OAuth2TokenStore;
+/** Persist the store. Owner-only where the platform honours the mode; utf8, no BOM. */
+export declare function writeTokenStore(store: OAuth2TokenStore): void;
+/** Drop one account's tokens (a dead refresh token, or a mailbox that moved). */
+export declare function clearTokenFor(name: string): boolean;
+export type OAuth2State = 'none' | 'pending' | 'logged-in';
+/**
+ * What the settings card shows for one account: logged-in wins over a flow
+ * that is merely in progress, and an expired flow is not「pending」any more.
+ *
+ * `configuredUser` is the address the account is configured with right now.
+ * A token issued for a *different* mailbox is not a login for this account —
+ * reporting it as one would show 「已登录」 on a card whose tools all fail, so
+ * the verdict is「none」and the user is sent through the flow again. An empty
+ * configured address cannot disagree with anything and keeps the token.
+ */
+export declare function oauth2StateOf(name: string, configuredUser?: string, configuredClientId?: string): {
+    state: OAuth2State;
+    user?: string;
+};
+export declare function isDeviceFlowPending(name: string): boolean;
+export declare function clientIdOf(cfg: OAuth2AccountConfig): string;
+/**
+ * Step 1: ask for a device code. One flow per account is kept in memory; two
+ * concurrent calls share the same request instead of creating two codes.
+ */
+export declare function startDeviceFlow(name: string, cfg: OAuth2AccountConfig): Promise<DeviceFlowStart>;
+export type OAuth2PollResult = {
+    status: 'ok';
+    user: string;
+} | {
+    status: 'pending';
+};
+/**
+ * Step 2: one poll. `pending` is the ordinary answer until the user finishes in
+ * the browser; on success the token is persisted before this returns.
+ */
+export declare function pollDeviceFlow(name: string): Promise<OAuth2PollResult>;
+/**
+ * A usable access token for one account: the cached one while more than two
+ * minutes of its life are left, otherwise a refresh. Concurrent callers share a
+ * single refresh request, so a burst of tool calls never mints several tokens
+ * (Microsoft rotates the refresh token, and losing that race logs the user out).
+ *
+ * `force` re-mints even a token that still looks fresh: the only way to tell a
+ * revoked token from a network failure after a server-side rejection.
+ */
+export declare function getFreshAccessToken(name: string, cfg: OAuth2AccountConfig, options?: {
+    force?: boolean;
+}): Promise<string>;
+export {};