imapkit 5.1.0 → 5.3.0

package/dist/cjs/types.d.ts

@@ -1,5 +1,7 @@
 import type { IMAPServer, IMAPConnection } from './server.js';
 import type { ScriptRule } from './script.js';
+import type { OAuthOptions } from './oauth/provider.js';
+import type { ConsentPolicy } from './oauth/policy.js';
 export type { IMAPServer, IMAPConnection };
 /**
  * A value of the parsed command or of a response, as imap-handler parses and compiles it: an
@@ -210,6 +212,12 @@ export interface MailboxStatus {
 }
 export interface UserData {
     password?: string | undefined;
+    /** the display name, the `name` claim of the OAuth provider */
+    displayName?: string | undefined;
+    /** OAuth provider settings of the user: the consent policy of sign-ins that name the user in login_hint */
+    oauth?: {
+        consent?: ConsentPolicy | undefined;
+    } | undefined;
     xoauth2?: {
         accessToken?: string | undefined;
         /**
@@ -228,6 +236,12 @@ export interface IMAPServerOptions {
     plugins?: (string | Plugin)[] | string | Plugin | undefined;
     users?: Record<string, UserData> | undefined;
     secureConnection?: boolean | undefined;
+    /** starts a second IMAP listener for implicit TLS (IMAPS) with `server.start()`, its sessions share the storage
+     * with the main listener. Without a host it listens on the host given to `start()` */
+    tls?: {
+        port?: number | undefined;
+        host?: string | undefined;
+    } | undefined;
     /** starts an SMTP server with `server.start()` that appends every received message to INBOX, needs the optional
      * smtp-server package */
     smtp?: {
@@ -240,6 +254,8 @@ export interface IMAPServerOptions {
         host?: string | undefined;
         token?: string | undefined;
     } | undefined;
+    /** starts the OAuth 2.0 / OpenID Connect provider with `server.start()`, see src/oauth/provider.ts */
+    oauth?: OAuthOptions | undefined;
     credentials?: {
         key: string | Buffer;
         cert: string | Buffer;

package/dist/esm/control.d.ts

@@ -8,6 +8,7 @@
  */
 import { ImapKitError } from './store-operations.js';
 import type { FlagMode, UidValidityOptions } from './store-operations.js';
+import type { ConsentPolicy } from './oauth/policy.js';
 import type { IMAPConnection, IMAPServer, Mailbox, Message, StorageMailbox, StorageNamespace, UserData } from './types.js';
 /** A mailbox as `getMailbox()` and `listMailboxes()` describe it */
 interface MailboxInfo {
@@ -68,7 +69,7 @@ interface NewMessage {
     internaldate?: Date | string | undefined;
 }
 /** The credentials of a user, see UserData */
-type UserOptions = Pick<UserData, 'password' | 'xoauth2'>;
+type UserOptions = Pick<UserData, 'password' | 'xoauth2' | 'displayName' | 'oauth'>;
 /** What a REST route handler gets, see src/rest.ts */
 interface RouteRequest {
     params: Record<string, string>;
@@ -89,6 +90,16 @@ type SessionFilter = number | {
     session?: number | undefined;
     user?: string | undefined;
 };
+/**
+ * Checks the `oauth` settings of a user
+ *
+ * @param {*} value `{ consent }`
+ * @param {String} what Setting name for the error message
+ * @return {Object} a copy
+ */
+declare function checkUserOAuth(value: unknown, what: string): {
+    consent?: ConsentPolicy;
+};
 declare class Control {
     [key: string]: any;
     server: IMAPServer;
@@ -364,14 +375,14 @@ declare class Control {
      * Adds a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout } }`
+     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout }, displayName, oauth: { consent } }`
      */
     addUser(name: string, options: UserOptions): void;
     /**
-     * Changes the password or the XOAUTH2 token of a user
+     * Changes the password, the XOAUTH2 token, the display name or the OAuth consent policy of a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2 }`, null xoauth2 removes the token
+     * @param {Object} options `{ password, xoauth2, displayName, oauth }`, null xoauth2, displayName or oauth removes it
      */
     updateUser(name: string, options: UserOptions): void;
     /**
@@ -421,5 +432,5 @@ declare class Control {
         graceful?: boolean | undefined;
     }): Promise<void>;
 }
-export { Control, ImapKitError };
+export { Control, ImapKitError, checkUserOAuth };
 export type { MailboxInfo, MessageInfo, SessionInfo, NewMessage, UserOptions, SessionFilter, ControlRoute, RouteRequest };

package/dist/esm/control.js

@@ -8,6 +8,7 @@
  */
 import validateMailboxName from './mailbox-name.js';
 import { DEFAULT_SESSION_TIMEOUT, ImapKitError, expungeMessages, checkFlags, changeFlags, createMailbox, deleteMailbox, renameMailbox, resetUidValidity, subscribeMailbox, unsubscribeMailbox } from './store-operations.js';
+import { checkOutcome } from './oauth/policy.js';
 /**
  * Copies a value of a plugin into the snapshot as JSON data, values that JSON can not hold are left out
  *
@@ -43,6 +44,20 @@ const NAMESPACE_SKIP = new Set(['folders']);
 // properties the server derives when it loads a mailbox, a snapshot leaves them out
 const DERIVED_MAILBOX_KEYS = new Set(['path', 'namespace', 'messages', 'folders', 'subscribed', 'flags']);
 const DERIVED_FLAGS = new Set(['\\HasChildren', '\\HasNoChildren']);
+/**
+ * Checks the `oauth` settings of a user
+ *
+ * @param {*} value `{ consent }`
+ * @param {String} what Setting name for the error message
+ * @return {Object} a copy
+ */
+function checkUserOAuth(value, what) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ImapKitError(what + ' must be { consent }', 'INVALID');
+    }
+    const { consent } = value;
+    return consent === undefined ? {} : { consent: checkOutcome(consent, what + '.consent') };
+}
 class Control {
     constructor(server) {
         this.server = server;
@@ -494,7 +509,7 @@ class Control {
      * Adds a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout } }`
+     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout }, displayName, oauth: { consent } }`
      */
     addUser(name, options) {
         if (typeof name !== 'string' || !name) {
@@ -506,10 +521,10 @@ class Control {
         this.server.users[name] = this.userData({}, options);
     }
     /**
-     * Changes the password or the XOAUTH2 token of a user
+     * Changes the password, the XOAUTH2 token, the display name or the OAuth consent policy of a user
      *
      * @param {String} name User name
-     * @param {Object} options `{ password, xoauth2 }`, null xoauth2 removes the token
+     * @param {Object} options `{ password, xoauth2, displayName, oauth }`, null xoauth2, displayName or oauth removes it
      */
     updateUser(name, options) {
         this.server.users[name] = this.userData(this.requireUser(name), options);
@@ -534,8 +549,23 @@ class Control {
         return this.server.users[name];
     }
     userData(user, options) {
-        const { password, xoauth2 } = options || {};
+        const { password, xoauth2, displayName, oauth } = options || {};
         const result = Object.assign({}, user);
+        if (displayName === null) {
+            delete result.displayName;
+        }
+        else if (displayName !== undefined) {
+            if (typeof displayName !== 'string') {
+                throw new ImapKitError('displayName must be a string', 'INVALID');
+            }
+            result.displayName = displayName;
+        }
+        if (oauth === null) {
+            delete result.oauth;
+        }
+        else if (oauth !== undefined) {
+            result.oauth = checkUserOAuth(oauth, 'oauth');
+        }
         if (password !== undefined) {
             if (typeof password !== 'string') {
                 throw new ImapKitError('Password must be a string', 'INVALID');
@@ -622,9 +652,9 @@ class Control {
             }
             else {
                 this.server.closeListeners(false);
-                this.server.server.close(done);
+                this.server.closeImapListeners(done);
             }
         });
     }
 }
-export { Control, ImapKitError };
+export { Control, ImapKitError, checkUserOAuth };

package/dist/esm/oauth/http.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The HTTP server of the OAuth provider (`oauth` option, `--oauth-port`), on node:http or node:https only.
+ * Routes: `/` (index), `/.well-known/openid-configuration` and `/.well-known/oauth-authorization-server`
+ * (discovery), `/authorize` (GET and POST, OpenID Connect Core 1.0 section 3.1.2.1), `/authorize/decision` (the
+ * consent page form), `/token`, `/revoke`, `/userinfo` and `/jwks`.
+ *
+ * Bound to a loopback address (the default), it only answers requests for a loopback host name or the host of the
+ * `issuer` option, so a web page can not rebind its DNS name to it. The JSON endpoints allow cross-origin requests,
+ * like real providers do for browser-based clients; the pages are never framed and run no script.
+ */
+import http from 'node:http';
+import type { OAuthProvider } from './provider.js';
+/**
+ * Creates the HTTP server of the provider, it does not listen yet
+ *
+ * @param {Object} provider OAuth provider
+ * @param {Object} options `{ secure, host, credentials }`, credentials are the TLS key and certificate of `secure`
+ * @return {Object} HTTP or HTTPS server
+ */
+declare function createOAuthServer(provider: OAuthProvider, options: {
+    secure?: boolean | undefined;
+    host: string;
+    credentials: {
+        key: string | Buffer;
+        cert: string | Buffer;
+    };
+}): http.Server;
+export { createOAuthServer };

package/dist/esm/oauth/http.js

@@ -0,0 +1,211 @@
+/**
+ * The HTTP server of the OAuth provider (`oauth` option, `--oauth-port`), on node:http or node:https only.
+ * Routes: `/` (index), `/.well-known/openid-configuration` and `/.well-known/oauth-authorization-server`
+ * (discovery), `/authorize` (GET and POST, OpenID Connect Core 1.0 section 3.1.2.1), `/authorize/decision` (the
+ * consent page form), `/token`, `/revoke`, `/userinfo` and `/jwks`.
+ *
+ * Bound to a loopback address (the default), it only answers requests for a loopback host name or the host of the
+ * `issuer` option, so a web page can not rebind its DNS name to it. The JSON endpoints allow cross-origin requests,
+ * like real providers do for browser-based clients; the pages are never framed and run no script.
+ */
+import http from 'node:http';
+import https from 'node:https';
+import { consentPage, indexPage, messagePage } from './pages.js';
+import { isLoopback, readRaw } from '../rest.js';
+// a form of a mail client sign-in is small, larger bodies are refused
+const BODY_LIMIT = 64 * 1024;
+class HttpError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Reads an application/x-www-form-urlencoded body
+ *
+ * @param {Object} req HTTP request
+ * @return {Promise<URLSearchParams>} the form
+ */
+async function readForm(req) {
+    // RFC 6749 sections 3.2 and 4.1.3: the parameters are form encoded
+    if (!/^application\/x-www-form-urlencoded\b/i.test(req.headers['content-type'] || '')) {
+        req.resume();
+        throw new HttpError(415, 'The body must be application/x-www-form-urlencoded (RFC 6749 section 4.1.3)');
+    }
+    const body = await readRaw(req, BODY_LIMIT, () => new HttpError(413, 'The body is larger than 64 KiB'));
+    return new URLSearchParams(body.toString('utf-8'));
+}
+const SECURITY_HEADERS = {
+    'Cache-Control': 'no-store',
+    Pragma: 'no-cache',
+    'X-Content-Type-Options': 'nosniff',
+    'Referrer-Policy': 'no-referrer'
+};
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
+};
+/**
+ * The form-action sources of the consent page. Browsers check form-action on the redirect after the form too,
+ * so the origin of the client's redirect URI must be allowed
+ *
+ * @param {Object} request Pending request
+ * @return {String} CSP source list
+ */
+function formActionSources(request) {
+    try {
+        const url = new URL(request.redirectUri);
+        return "'self' " + (url.origin !== 'null' ? url.origin : url.protocol);
+    }
+    catch {
+        return "'self'";
+    }
+}
+function sendHtml(res, status, html, formAction = "'none'") {
+    res.writeHead(status, {
+        ...SECURITY_HEADERS,
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Length': Buffer.byteLength(html),
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'; form-action " + formAction,
+        'X-Frame-Options': 'DENY'
+    });
+    res.end(html);
+}
+function sendJson(res, result) {
+    if (result.htmlError) {
+        // like a provider behind a broken proxy
+        sendHtml(res, result.status, '<!doctype html><title>Error</title><h1>Something went wrong</h1>');
+        return;
+    }
+    const json = JSON.stringify(result.body);
+    res.writeHead(result.status, {
+        ...SECURITY_HEADERS,
+        ...CORS_HEADERS,
+        ...(result.headers || {}),
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(json)
+    });
+    res.end(json);
+}
+/**
+ * Checks the Origin of the consent form: the issuer, or the loopback name the page was opened on. A browser that
+ * sends no Origin, or "null" (Referrer-Policy: no-referrer), is let through; the request ID protects the form then
+ *
+ * @param {String} [origin] Origin header
+ * @param {String} issuer Issuer URL
+ * @param {String} [host] Host header
+ * @return {Boolean} true if the form may come from there
+ */
+function sameSite(origin, issuer, host) {
+    if (!origin || origin === 'null' || origin === new URL(issuer).origin) {
+        return true;
+    }
+    try {
+        const url = new URL(origin);
+        return isLoopback(url.hostname) && url.host === host;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates the HTTP server of the provider, it does not listen yet
+ *
+ * @param {Object} provider OAuth provider
+ * @param {Object} options `{ secure, host, credentials }`, credentials are the TLS key and certificate of `secure`
+ * @return {Object} HTTP or HTTPS server
+ */
+function createOAuthServer(provider, options) {
+    const answerAuthorize = (res, result, status) => {
+        if (result.type === 'redirect') {
+            res.writeHead(status, { ...SECURITY_HEADERS, Location: result.location, 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Redirecting to ' + result.location + '\n');
+        }
+        else if (result.type === 'page') {
+            sendHtml(res, result.page.status, messagePage(result.page, provider.issuer));
+        }
+        else {
+            const html = consentPage({ request: result.request, users: provider.pageUsers(), scopes: provider.scopes, issuer: provider.issuer });
+            sendHtml(res, 200, html, formActionSources(result.request));
+        }
+    };
+    const checkHost = (req) => {
+        if (!isLoopback(options.host)) {
+            return;
+        }
+        const host = (req.headers.host || '').replace(/:\d+$/, '');
+        let issuerHost = '';
+        try {
+            issuerHost = new URL(provider.issuer).hostname;
+        }
+        catch {
+            // no issuer yet
+        }
+        if (!isLoopback(host) && host.replace(/^\[|\]$/g, '') !== issuerHost.replace(/^\[|\]$/g, '')) {
+            // a page that rebinds its DNS name to 127.0.0.1 sends its own host name
+            throw new HttpError(421, 'Requests must use a loopback host name or the host of the issuer');
+        }
+    };
+    const handle = async (req, res) => {
+        checkHost(req);
+        const url = new URL(req.url || '/', 'http://localhost');
+        const method = (req.method || 'GET').toUpperCase();
+        const route = method + ' ' + url.pathname;
+        if (method === 'OPTIONS') {
+            res.writeHead(204, { ...CORS_HEADERS, 'Access-Control-Max-Age': '600' });
+            return res.end();
+        }
+        switch (route) {
+            case 'GET /':
+                return sendHtml(res, 200, indexPage({
+                    issuer: provider.issuer,
+                    consent: provider.consent,
+                    clients: [...provider.clients.values()],
+                    users: provider.pageUsers(),
+                    mailScope: provider.mailScope
+                }));
+            case 'GET /.well-known/openid-configuration':
+            case 'GET /.well-known/oauth-authorization-server':
+                return sendJson(res, { status: 200, body: provider.metadata() });
+            case 'GET /jwks':
+                return sendJson(res, { status: 200, body: provider.jwks() });
+            case 'GET /authorize':
+                return answerAuthorize(res, provider.authorize(url.searchParams), 302);
+            case 'POST /authorize':
+                // RFC 9700 section 4.12: 303 turns the POST into a GET, never 307
+                return answerAuthorize(res, provider.authorize(await readForm(req)), 303);
+            case 'POST /authorize/decision': {
+                if (!sameSite(req.headers.origin, provider.issuer, req.headers.host)) {
+                    throw new HttpError(403, 'The consent form must come from the consent page');
+                }
+                return answerAuthorize(res, provider.answerConsent(await readForm(req)), 303);
+            }
+            case 'POST /token':
+                return sendJson(res, await provider.token(await readForm(req), req.headers.authorization));
+            case 'POST /revoke':
+                return sendJson(res, provider.revoke(await readForm(req), req.headers.authorization));
+            case 'GET /userinfo':
+                return sendJson(res, provider.userinfo(req.headers.authorization));
+            case 'POST /userinfo':
+                req.resume();
+                return sendJson(res, provider.userinfo(req.headers.authorization));
+            default: {
+                const known = ['/', '/authorize', '/authorize/decision', '/token', '/revoke', '/userinfo', '/jwks'];
+                const wellKnown = url.pathname.startsWith('/.well-known/');
+                throw new HttpError(known.includes(url.pathname) || wellKnown ? 405 : 404, known.includes(url.pathname) ? 'Method not allowed' : 'Not found');
+            }
+        }
+    };
+    const listener = (req, res) => {
+        handle(req, res).catch((err) => {
+            const status = err instanceof HttpError ? err.status : 500;
+            if (!res.headersSent) {
+                // the token and revocation endpoints answer errors in JSON (RFC 6749 section 5.2)
+                sendJson(res, { status, body: { error: status === 500 ? 'server_error' : 'invalid_request', error_description: err.message } });
+            }
+        });
+    };
+    return options.secure ? https.createServer(options.credentials, listener) : http.createServer(listener);
+}
+export { createOAuthServer };

package/dist/esm/oauth/jwt.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Signs the ID tokens of the OAuth provider: RS256 JSON Web Tokens (RFC 7519, RFC 7515) and the JWK Set of the
+ * public key (RFC 7517), with the RFC 7638 thumbprint as the key ID
+ */
+import crypto from 'node:crypto';
+/** An RSA signing key with its public JWK */
+export interface SigningKey {
+    privateKey: crypto.KeyObject;
+    jwk: Record<string, string>;
+    kid: string;
+}
+/**
+ * Loads or makes the signing key
+ *
+ * @param {String|Buffer} [pem] PKCS#8 or PKCS#1 private key in PEM, a new 2048 bit key if not set (see defaultSigningKey())
+ * @return {Object} the key, its public JWK and key ID
+ * @throws {Error} for a key that is not RSA
+ */
+export declare function loadSigningKey(pem?: string | Buffer): SigningKey;
+/**
+ * The shared signing key of the providers without the signingKey option, made when the first one needs it
+ *
+ * @return {Object} signing key
+ */
+export declare function defaultSigningKey(): SigningKey;
+/**
+ * Signs a JWT with RS256
+ *
+ * @param {Object} key Signing key
+ * @param {Object} claims JWT claims
+ * @return {String} compact serialization
+ */
+export declare function signJwt(key: SigningKey, claims: Record<string, unknown>): string;

package/dist/esm/oauth/jwt.js

@@ -0,0 +1,50 @@
+/**
+ * Signs the ID tokens of the OAuth provider: RS256 JSON Web Tokens (RFC 7519, RFC 7515) and the JWK Set of the
+ * public key (RFC 7517), with the RFC 7638 thumbprint as the key ID
+ */
+import crypto from 'node:crypto';
+const base64url = (data) => Buffer.from(data).toString('base64url');
+/**
+ * Loads or makes the signing key
+ *
+ * @param {String|Buffer} [pem] PKCS#8 or PKCS#1 private key in PEM, a new 2048 bit key if not set (see defaultSigningKey())
+ * @return {Object} the key, its public JWK and key ID
+ * @throws {Error} for a key that is not RSA
+ */
+export function loadSigningKey(pem) {
+    const privateKey = pem ? crypto.createPrivateKey(pem) : crypto.generateKeyPairSync('rsa', { modulusLength: 2048 }).privateKey;
+    if (privateKey.asymmetricKeyType !== 'rsa') {
+        throw new Error('oauth.signingKey must be an RSA private key, ID tokens are signed with RS256');
+    }
+    const { n, e } = crypto.createPublicKey(privateKey).export({ format: 'jwk' });
+    // RFC 7638 section 3.2: the required members in lexicographic order, no white space
+    const kid = base64url(crypto
+        .createHash('sha256')
+        .update(JSON.stringify({ e, kty: 'RSA', n }))
+        .digest());
+    return { privateKey, kid, jwk: { kty: 'RSA', use: 'sig', alg: 'RS256', kid, n, e } };
+}
+// the key of every provider without a signingKey option, made once: a 2048 bit RSA key takes a moment
+let defaultKey = null;
+/**
+ * The shared signing key of the providers without the signingKey option, made when the first one needs it
+ *
+ * @return {Object} signing key
+ */
+export function defaultSigningKey() {
+    if (!defaultKey) {
+        defaultKey = loadSigningKey();
+    }
+    return defaultKey;
+}
+/**
+ * Signs a JWT with RS256
+ *
+ * @param {Object} key Signing key
+ * @param {Object} claims JWT claims
+ * @return {String} compact serialization
+ */
+export function signJwt(key, claims) {
+    const input = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT', kid: key.kid })) + '.' + base64url(JSON.stringify(claims));
+    return input + '.' + base64url(crypto.sign('sha256', Buffer.from(input), key.privateKey));
+}

package/dist/esm/oauth/pages.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The pages of the OAuth provider: the consent page, error and info pages, and the index page at `/`. They are a
+ * test tool's pages and say so (a striped "test server" ribbon, ImapKit's own mark, no password field), so that
+ * nobody takes them for a real provider's sign-in. They run no script and load nothing, src/oauth/http.ts sends
+ * them with a strict Content-Security-Policy.
+ */
+import type { OAuthClient, PageData, PendingRequest } from './provider.js';
+import type { ConsentPolicy } from './policy.js';
+/** A user on the consent page */
+export interface PageUser {
+    name: string;
+    displayName: string | undefined;
+    consent: ConsentPolicy | undefined;
+}
+/**
+ * The consent page: pick an account, Allow or Deny
+ *
+ * @param {Object} data `{ request, users, scopes, issuer }`
+ * @return {String} HTML
+ */
+export declare function consentPage(data: {
+    request: PendingRequest;
+    users: PageUser[];
+    scopes: Record<string, string>;
+    issuer: string;
+}): string;
+/**
+ * An error or info page, instead of a redirect
+ *
+ * @param {Object} page Page data
+ * @param {String} issuer Issuer URL
+ * @return {String} HTML
+ */
+export declare function messagePage(page: PageData, issuer: string): string;
+/**
+ * The index page at `/`: issuer, clients and endpoints
+ *
+ * @param {Object} data `{ issuer, consent, clients, users, mailScope }`
+ * @return {String} HTML
+ */
+export declare function indexPage(data: {
+    issuer: string;
+    consent: ConsentPolicy;
+    clients: OAuthClient[];
+    users: PageUser[];
+    mailScope: string;
+}): string;