imapkit 5.2.0 → 5.3.0

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;