domma-cms 1.6.38 → 1.6.39

package/plugins/_lib/mail/imapPool.js

@@ -73,6 +73,52 @@ export function createPool(config) {
         };
     }
 
+    /**
+     * Open and sign in one client, renewing an OAuth2 token on the way.
+     *
+     * A password connection is a single attempt, as it always was. A signed-in
+     * (OAuth2) one carries `refresh` from `toConnection()`: the stored token is
+     * taken (renewed first when under a minute is left), and renewed once more -
+     * forced - when the server refuses it anyway (revoked early, a clock out
+     * of step). Never more than once: a second refusal is the answer.
+     *
+     * @param   {object} connection
+     * @param   {(client: ImapFlow) => void} [prepare] - listeners to add before connect
+     * @returns {Promise<ImapFlow>}
+     */
+    async function connectClient(connection, prepare = () => {}) {
+        let auth = connection.auth;
+        const canRenew = typeof connection.refresh === 'function';
+        if (canRenew) {
+            // Asked every time, not only near expiry: it reads the STORED
+            // sign-in (no network while the token is good), so a connection
+            // object built a while ago neither presents a token another
+            // request has since replaced, nor tries one already known dead.
+            const r = await connection.refresh(false);
+            auth = {user: auth.user, accessToken: r.accessToken};
+        }
+
+        const attempt = async (withAuth) => {
+            const client = new ImapFlow(clientOptions({...connection, auth: withAuth}));
+            prepare(client);
+            try {
+                await client.connect();
+                return client;
+            } catch (err) {
+                try { client.close(); } catch { /* already down */ }
+                throw err;
+            }
+        };
+
+        try {
+            return await attempt(auth);
+        } catch (err) {
+            if (!canRenew || !err?.authenticationFailed) throw err;
+            const r = await connection.refresh(true);
+            return attempt({user: auth.user, accessToken: r.accessToken});
+        }
+    }
+
     /**
      * Drop a pooled connection, closing it best-effort.
      *
@@ -115,14 +161,14 @@ export function createPool(config) {
         }
 
         const connect = (async () => {
-            const client = new ImapFlow(clientOptions(connection));
-            // ImapFlow emits 'error' on an already-failed connection; without a
-            // listener that becomes an unhandled event and takes the process out.
-            client.on('error', () => evict(userId));
-            client.on('close', () => {
-                if (pool.get(userId)?.client === client) pool.delete(userId);
+            const client = await connectClient(connection, (c) => {
+                // ImapFlow emits 'error' on an already-failed connection; without a
+                // listener that becomes an unhandled event and takes the process out.
+                c.on('error', () => evict(userId));
+                c.on('close', () => {
+                    if (pool.get(userId)?.client === c) pool.delete(userId);
+                });
             });
-            await client.connect();
             pool.set(userId, {client, fingerprint: fp, lastUsed: Date.now()});
             return client;
         })();
@@ -193,20 +239,19 @@ export function createPool(config) {
      * @returns {Promise<{ok: true, greeting: string|null} | {ok: false, error: string}>}
      */
     async function test(connection) {
-        const client = new ImapFlow(clientOptions(connection));
-        client.on('error', () => {});
+        let client = null;
         try {
-            await client.connect();
+            client = await connectClient(connection, c => c.on('error', () => {}));
             const greeting = client.serverInfo?.greeting ?? null;
             await client.logout();
             return {ok: true, greeting};
         } catch (err) {
             try {
-                client.close();
+                client?.close();
             } catch {
                 // Already down - nothing to close.
             }
-            return {ok: false, error: describeError(err, connection)};
+            return {ok: false, error: err?.needsReconnect ? err.message : describeError(err, connection)};
         }
     }
 
@@ -255,7 +300,7 @@ export function createPool(config) {
     // Never hold the process open on account of an idle mail connection.
     reaper.unref?.();
 
-    return {withClient, withMailbox, test, release, releaseUser, closeAll, get size() {
+    return {withClient, withMailbox, test, release, releaseUser, closeAll, connectClient, get size() {
         return pool.size;
     }};
 }
@@ -276,6 +321,11 @@ export function createPool(config) {
  */
 export function describeError(err, connection = {}) {
     if (!err) return 'Unknown error.';
+    if (err.needsReconnect) return err.message;
+    // A signed-in (OAuth2) mailbox has no password to blame.
+    if ((err.authenticationFailed || err.code === 'EAUTH' || err.code === 'EOAUTH2') && (connection.auth?.accessToken !== undefined || connection.auth?.type === 'OAuth2')) {
+        return 'The mail server refused the sign-in. If it keeps happening, Reconnect the mailbox.';
+    }
     if (err.authenticationFailed || err.code === 'EAUTH') return 'The mail server rejected that username and password.';
 
     const host = connection.host || 'The mail server';

package/plugins/_lib/mail/oauth.js

@@ -0,0 +1,453 @@
+/**
+ * OAuth2 sign-in for mailboxes (XOAUTH2) - Microsoft 365 / Outlook.com and Gmail.
+ *
+ * A mailbox can be signed in with the provider instead of a password: no app
+ * password, and a sign-in the provider can withdraw. The customer registers
+ * THEIR OWN app with the provider (the Docs Pro cloud-copies design) - the
+ * site never holds a client id of ours, so nobody else's app or verification
+ * stands between a customer and their own mail.
+ *
+ * What is kept (sealed with secretbox, the same key as mailbox passwords):
+ * the client secret, the refresh token and the current access token.
+ *
+ * ## Refreshing
+ *
+ * An access token lasts about an hour. It is renewed at the point of use, not
+ * on a timer: IMAP and SMTP only present it when a connection is opened, and
+ * a pooled IMAP connection stays signed in after its token has expired.
+ *
+ *   - before expiry: `toConnection()` carries `expiresAt` and a `refresh`
+ *     function; the pool renews when under a minute is left.
+ *   - on an auth failure: the pool (and nodemailer, through its
+ *     `provisionCallback`) asks for a forced renewal and tries ONCE more.
+ *
+ * A refresh the provider REFUSES (invalid_grant and friends - revoked,
+ * expired, a Google "Testing" app's 7-day limit, a client secret that ran
+ * out) marks the account "needs reconnecting" and tells its owner. From then
+ * on `toConnection()` throws OAuthReconnectError without touching the network,
+ * so the poller cannot hammer a dead sign-in. A refresh that merely could not
+ * be done (network, 5xx) changes nothing and is tried again next time.
+ *
+ * Microsoft ROTATES refresh tokens: every refresh may answer a new one, and the
+ * new one is saved. Google answers none on refresh; the stored one is kept.
+ *
+ * Endpoints and scopes from the vendors' documentation (2026-10):
+ *   - learn.microsoft.com .../v2-oauth2-auth-code-flow and
+ *     .../how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
+ *   - developers.google.com .../oauth2/web-server and .../gmail/imap/xoauth2-protocol
+ *
+ * @module _lib/mail/oauth
+ */
+import {createHash, randomBytes} from 'node:crypto';
+
+import * as accounts from './accounts.js';
+import {OAuthReconnectError} from './accounts.js';
+import {open, seal} from './secretbox.js';
+
+/** The tenant id Microsoft gives every personal (Outlook.com) account in an id_token. */
+const MS_CONSUMER_TENANT = '9188040d-6c67-4c5b-b112-36a304b66dad';
+
+/** Renew when less than this is left, so a token never expires mid-handshake. */
+export const REFRESH_SKEW_MS = 60_000;
+
+const MS_MAIL_SCOPES = ['https://outlook.office.com/IMAP.AccessAsUser.All', 'https://outlook.office.com/SMTP.Send'];
+
+/**
+ * The two providers. Hosts are fixed: the token only works against the
+ * provider's own servers, so there is nothing for the customer to type and no
+ * host to guard.
+ */
+export const PROVIDERS = {
+    microsoft: {
+        id: 'microsoft',
+        label: 'Microsoft 365 / Outlook.com',
+        short: 'Microsoft',
+        needsTenant: true,
+        authorizeUrl: (tenant) => `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/authorize`,
+        tokenUrl: (tenant) => `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`,
+        // openid + email only to learn the address signed in; all the mail
+        // scopes are one resource (outlook.office.com), which Microsoft
+        // requires of a single token.
+        scopes: [...MS_MAIL_SCOPES, 'offline_access', 'openid', 'email'],
+        refreshScope: [...MS_MAIL_SCOPES, 'offline_access'].join(' '),
+        // Recommended for confidential clients too (the auth-code-flow page).
+        pkce: true,
+        extraAuthParams: {response_mode: 'query', prompt: 'select_account'},
+        imap: {host: 'outlook.office365.com', port: 993, secure: true},
+        smtp: {host: 'smtp.office365.com', port: 587, secure: false},
+        // Outlook.com's own outgoing server (support.microsoft.com, Outlook.com settings).
+        smtpPersonal: {host: 'smtp-mail.outlook.com', port: 587, secure: false},
+        // Microsoft offers no endpoint for an app to hand one refresh token back.
+        revokeUrl: null
+    },
+    google: {
+        id: 'google',
+        label: 'Gmail / Google Workspace',
+        short: 'Google',
+        needsTenant: false,
+        authorizeUrl: () => 'https://accounts.google.com/o/oauth2/v2/auth',
+        tokenUrl: () => 'https://oauth2.googleapis.com/token',
+        scopes: ['https://mail.google.com/', 'openid', 'email'],
+        refreshScope: null,
+        // PKCE as well as state + secret (Google accepts S256 code_challenge).
+        pkce: true,
+        // offline + consent, or Google sends no refresh token on a second connect.
+        extraAuthParams: {access_type: 'offline', prompt: 'consent', include_granted_scopes: 'true'},
+        imap: {host: 'imap.gmail.com', port: 993, secure: true},
+        smtp: {host: 'smtp.gmail.com', port: 465, secure: true},
+        smtpPersonal: null,
+        revokeUrl: 'https://oauth2.googleapis.com/revoke'
+    }
+};
+
+/** Token-endpoint errors that no retry will clear: the person has to sign in again. */
+const PERMANENT = new Set(['invalid_grant', 'invalid_client', 'unauthorized_client', 'interaction_required',
+    'consent_required', 'invalid_scope', 'access_denied']);
+
+/** Swappable for tests - nothing real is reachable from a test run. */
+let fetchImpl = (...args) => globalThis.fetch(...args);
+/** Told when an account needs reconnecting, and when it is connected again. */
+let hooks = {};
+
+/**
+ * @param {{fetch?: Function, onNeedsReconnect?: Function, onConnected?: Function}} options
+ * @returns {void}
+ */
+export function configureOAuth({fetch, onNeedsReconnect, onConnected} = {}) {
+    if (fetch) fetchImpl = fetch;
+    if (onNeedsReconnect !== undefined || onConnected !== undefined) {
+        hooks = {...hooks, ...(onNeedsReconnect !== undefined ? {onNeedsReconnect} : {}),
+            ...(onConnected !== undefined ? {onConnected} : {})};
+    }
+}
+
+/** Tests: back to the real network and no listeners. */
+export function _resetOAuth() {
+    fetchImpl = (...args) => globalThis.fetch(...args);
+    hooks = {};
+    inFlight.clear();
+}
+
+/**
+ * A tenant segment for Microsoft's URLs: `common`, `organizations`,
+ * `consumers` or a tenant id/domain. Anything else falls back to `common`
+ * rather than being pasted into a URL.
+ *
+ * @param   {string} value
+ * @returns {string}
+ */
+export function cleanTenant(value) {
+    const t = String(value ?? '').trim();
+    // Dot-separated labels only: no empty label, no `..`, nothing that could
+    // walk a path segment.
+    return t.length >= 2 && t.length <= 100 && /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*$/.test(t) ? t : 'common';
+}
+
+/**
+ * PKCE pair (RFC 7636, S256).
+ *
+ * @returns {{verifier: string, challenge: string}}
+ */
+export function pkcePair() {
+    const verifier = randomBytes(48).toString('base64url');
+    return {verifier, challenge: createHash('sha256').update(verifier).digest('base64url')};
+}
+
+/**
+ * The provider's sign-in address. Pure.
+ *
+ * @param   {{provider: string, clientId: string, tenant?: string, redirectUri: string, state: string,
+ *            codeChallenge?: string, loginHint?: string}} o
+ * @returns {string}
+ */
+export function authorizeUrl({provider, clientId, tenant, redirectUri, state, codeChallenge, loginHint}) {
+    const p = PROVIDERS[provider];
+    if (!p) throw new Error('Unknown provider.');
+    const q = new URLSearchParams({
+        client_id: String(clientId ?? '').trim(),
+        response_type: 'code',
+        redirect_uri: redirectUri,
+        scope: p.scopes.join(' '),
+        state,
+        ...p.extraAuthParams
+    });
+    if (p.pkce && codeChallenge) {
+        q.set('code_challenge', codeChallenge);
+        q.set('code_challenge_method', 'S256');
+    }
+    if (loginHint) q.set('login_hint', loginHint);
+    return `${p.authorizeUrl(cleanTenant(tenant))}?${q}`;
+}
+
+/**
+ * The claims of an id_token. NOT verified: it came straight from the token
+ * endpoint over TLS in answer to our own request (OpenID Connect Core 3.1.3.7
+ * allows that), and it is used only to learn the address signed in.
+ *
+ * @param   {string} idToken
+ * @returns {object}
+ */
+export function idTokenClaims(idToken) {
+    try {
+        const part = String(idToken ?? '').split('.')[1];
+        return part ? JSON.parse(Buffer.from(part, 'base64url').toString('utf8')) : {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The mailbox address and outgoing server a token response points at. Pure.
+ *
+ * @param   {string} provider
+ * @param   {object} claims - idTokenClaims()
+ * @returns {{email: string, smtp: {host: string, port: number, secure: boolean}}}
+ */
+export function mailboxFor(provider, claims) {
+    const p = PROVIDERS[provider];
+    const email = String(claims?.email || claims?.preferred_username || claims?.upn || '').trim().toLowerCase();
+    const personal = provider === 'microsoft' && claims?.tid === MS_CONSUMER_TENANT;
+    return {email: /@/.test(email) ? email : '', smtp: personal && p.smtpPersonal ? p.smtpPersonal : p.smtp};
+}
+
+/**
+ * Does this stored sign-in need renewing before use? Pure.
+ *
+ * @param   {{expiresAt?: number, accessTokenSealed?: string}} oauth
+ * @param   {number} [now]
+ * @returns {boolean}
+ */
+export function needsRefresh(oauth, now = Date.now()) {
+    if (!oauth?.accessTokenSealed) return true;
+    return !(Number(oauth.expiresAt) > now + REFRESH_SKEW_MS);
+}
+
+/**
+ * Sort a token endpoint failure into "sign in again" or "try later". Pure.
+ *
+ * @param   {number} status
+ * @param   {object|null} body
+ * @returns {{permanent: boolean, code: string, message: string}}
+ */
+export function classifyTokenError(status, body) {
+    const code = String(body?.error ?? '').trim();
+    const said = String(body?.error_description ?? '').replace(/[\r\n\t]+/g, ' ').split(/Trace ID:/i)[0].trim().slice(0, 200);
+    const permanent = PERMANENT.has(code) || (status === 400 && !code) || status === 401;
+    let message;
+    if (code === 'invalid_client') message = 'The app\'s client secret was refused - it may have expired. Make a new one, then Reconnect.';
+    else if (code === 'invalid_grant') message = 'The sign-in has expired or was withdrawn. Reconnect to sign in again.';
+    else if (permanent) message = `The provider refused to renew the sign-in${said ? `: ${said}` : ''}. Reconnect to sign in again.`;
+    else message = `The provider could not renew the sign-in just now${said ? ` (${said})` : ` (${status || 'no answer'})`}. It will be tried again.`;
+    return {permanent, code, message};
+}
+
+/**
+ * POST a form to a fixed provider endpoint. Redirects are refused (the hosts
+ * are known; a 3xx is not something to follow with a secret in the body).
+ *
+ * @returns {Promise<{status: number, body: object|null}>}
+ */
+async function postForm(url, params) {
+    const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: {'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json'},
+        body: new URLSearchParams(params).toString(),
+        redirect: 'manual',
+        signal: AbortSignal.timeout(20_000)
+    });
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    return {status: res.status, ok: res.ok, body};
+}
+
+/**
+ * Trade the code from the callback for tokens.
+ *
+ * @param   {{provider: string, clientId: string, clientSecret: string, tenant?: string,
+ *            code: string, redirectUri: string, codeVerifier?: string}} o
+ * @returns {Promise<{accessToken: string, refreshToken: string, expiresAt: number, scope: string, claims: object}>}
+ */
+export async function exchangeCode({provider, clientId, clientSecret, tenant, code, redirectUri, codeVerifier}) {
+    const p = PROVIDERS[provider];
+    const params = {client_id: clientId, client_secret: clientSecret, code, redirect_uri: redirectUri, grant_type: 'authorization_code'};
+    if (p.pkce && codeVerifier) params.code_verifier = codeVerifier;
+    let r;
+    try {
+        r = await postForm(p.tokenUrl(cleanTenant(tenant)), params);
+    } catch (err) {
+        throw new Error(`${p.short} could not be reached to finish the sign-in: ${err.message}`);
+    }
+    if (!r.ok || !r.body?.access_token) {
+        const why = classifyTokenError(r.status, r.body);
+        throw new Error(`${p.short} refused the sign-in${why.code ? ` (${why.code})` : ''}: ${String(r.body?.error_description || r.status).split(/Trace ID:/i)[0].trim().slice(0, 200)}`);
+    }
+    if (!r.body.refresh_token) {
+        throw new Error(provider === 'google'
+            ? 'Google sent no refresh token. Remove the app from your Google account\'s third-party access, then Connect again.'
+            : 'Microsoft sent no refresh token - is offline_access among the app\'s API permissions?');
+    }
+    if (provider === 'google' && r.body.scope && !String(r.body.scope).split(' ').includes('https://mail.google.com/')) {
+        throw new Error('Mail access was not granted - tick it on Google\'s consent screen, then Connect again.');
+    }
+    return {
+        accessToken: r.body.access_token,
+        refreshToken: r.body.refresh_token,
+        expiresAt: Date.now() + (Number(r.body.expires_in) || 3600) * 1000,
+        scope: String(r.body.scope ?? ''),
+        claims: idTokenClaims(r.body.id_token)
+    };
+}
+
+/** One refresh per account at a time - a rotated refresh token must not be spent twice. */
+const inFlight = new Map();
+
+/**
+ * Renew an account's access token (or hand back the stored one while it is
+ * still good, unless `force`). Saves the new token, and a rotated refresh
+ * token. Throws OAuthReconnectError when the provider refuses for good (the
+ * account is marked and its owner told), a plain Error when it merely failed.
+ *
+ * @param   {string} userId
+ * @param   {string} accountId
+ * @param   {{force?: boolean}} [options]
+ * @returns {Promise<{accessToken: string, expiresAt: number, account: object}>}
+ */
+export function refreshAccount(userId, accountId, {force = false} = {}) {
+    const key = `${userId}:${accountId}`;
+    const running = inFlight.get(key);
+    if (running) return running;
+    const job = doRefresh(userId, accountId, force).finally(() => inFlight.delete(key));
+    inFlight.set(key, job);
+    return job;
+}
+
+async function doRefresh(userId, accountId, force) {
+    // Always the stored record: another caller may have rotated the token since
+    // this account object was read.
+    const account = await accounts.getAccount(userId, accountId);
+    if (!account || !accounts.isOAuth(account)) throw new Error('That mailbox is not signed in with a provider.');
+    if (accounts.needsReconnect(account)) throw new OAuthReconnectError(account.oauth?.error || undefined);
+    const o = account.oauth;
+    if (!force && !needsRefresh(o)) {
+        return {accessToken: open(o.accessTokenSealed), expiresAt: Number(o.expiresAt), account};
+    }
+
+    const p = PROVIDERS[o.provider];
+    // The generation this renewal works against - see updateOAuth.
+    const gen = Number(o.gen) || 0;
+    let clientSecret;
+    let refreshToken;
+    try {
+        clientSecret = open(o.clientSecretSealed);
+        refreshToken = open(o.refreshTokenSealed);
+    } catch (err) {
+        // The key moved (MAIL_SECRET added, say): nothing to refresh with.
+        return markBroken(account, err.message);
+    }
+
+    const params = {client_id: o.clientId, client_secret: clientSecret, refresh_token: refreshToken, grant_type: 'refresh_token'};
+    if (p.refreshScope) params.scope = p.refreshScope;
+    let r;
+    try {
+        r = await postForm(p.tokenUrl(cleanTenant(o.tenant)), params);
+    } catch (err) {
+        throw new Error(`${p.short} could not be reached to renew the sign-in: ${err.message}`);
+    }
+    if (!r.ok || !r.body?.access_token) {
+        const why = classifyTokenError(r.status, r.body);
+        if (why.permanent) return markBroken(account, why.message);
+        throw new Error(why.message);
+    }
+
+    const expiresAt = Date.now() + (Number(r.body.expires_in) || 3600) * 1000;
+    const saved = await accounts.updateOAuth(userId, accountId, {
+        accessTokenSealed: seal(r.body.access_token),
+        expiresAt,
+        // Rotation: Microsoft answers a new one and the old must be discarded.
+        ...(r.body.refresh_token && r.body.refresh_token !== refreshToken ? {refreshTokenSealed: seal(r.body.refresh_token)} : {}),
+        refreshedAt: new Date().toISOString(),
+        error: null
+    }, {expectGen: gen, requireOk: true});
+    if (!saved) {
+        // Reconnected or Disconnected while this renewal was on the wire: the
+        // stored state is newer and wins. Answer from it, never over it.
+        const now = await accounts.getAccount(userId, accountId);
+        if (!now || accounts.needsReconnect(now)) throw new OAuthReconnectError(now?.oauth?.error || undefined);
+        try {
+            return {accessToken: open(now.oauth.accessTokenSealed), expiresAt: Number(now.oauth.expiresAt), account: now};
+        } catch {
+            throw new Error('The sign-in changed while it was being renewed. Try again.');
+        }
+    }
+    return {accessToken: r.body.access_token, expiresAt, account: saved};
+}
+
+/** Mark an account as needing a new sign-in, tell its owner, and throw. */
+async function markBroken(account, message) {
+    const wasOk = account.oauth?.status === 'ok';
+    // Only the sign-in that was refused: a fresh one made meanwhile (Reconnect)
+    // is a different generation and must not be marked broken by the old one.
+    const saved = await accounts.updateOAuth(account.userId, account.id,
+        {status: 'reconnect', error: message, accessTokenSealed: null},
+        {expectGen: Number(account.oauth?.gen) || 0});
+    if (!saved) throw new Error('The sign-in changed while it was being renewed. Try again.');
+    if (wasOk) {
+        try { hooks.onNeedsReconnect?.(saved ?? account, message); } catch { /* a notice never breaks mail */ }
+    }
+    throw new OAuthReconnectError(message);
+}
+
+/**
+ * The function `toConnection()` hangs on a connection: renew (or force a
+ * renewal) and answer the new auth for that protocol.
+ *
+ * @param   {object} account
+ * @returns {(force: boolean) => Promise<{accessToken: string, expiresAt: number}>}
+ */
+export function refresherFor(account) {
+    return async (force = false) => {
+        const r = await refreshAccount(account.userId, account.id, {force});
+        return {accessToken: r.accessToken, expiresAt: r.expiresAt};
+    };
+}
+
+/**
+ * Hand the refresh token back to the provider, where it can be (Google).
+ * Best-effort: a sign-in we forget is gone from here either way.
+ *
+ * @param   {object} account
+ * @returns {Promise<{revoked: boolean, supported: boolean}>}
+ */
+export async function revokeAccount(account) {
+    const p = PROVIDERS[account?.oauth?.provider];
+    if (!p?.revokeUrl) return {revoked: false, supported: false};
+    let token;
+    try {
+        token = open(account.oauth.refreshTokenSealed);
+    } catch {
+        return {revoked: false, supported: true};
+    }
+    try {
+        const r = await postForm(p.revokeUrl, {token});
+        return {revoked: r.ok, supported: true};
+    } catch {
+        return {revoked: false, supported: true};
+    }
+}
+
+/** Tell the listener an account is connected again (the callback). */
+export function announceConnected(account) {
+    try { hooks.onConnected?.(account); } catch { /* ditto */ }
+}
+
+/**
+ * What the admin is told about the providers - no secrets.
+ *
+ * @returns {object[]}
+ */
+export function describeProviders() {
+    return Object.values(PROVIDERS).map(p => ({
+        id: p.id, label: p.label, short: p.short, needsTenant: p.needsTenant,
+        imap: p.imap, smtp: p.smtp, scopes: p.scopes, canRevoke: Boolean(p.revokeUrl)
+    }));
+}