@ultimatelemon-eu/mcp-http 2.2.0 → 2.3.0

package/README.md

@@ -43,6 +43,7 @@ process.once('SIGTERM', () => {
 | `basePath`        | `''`        | Also serve MCP on `<basePath>` and `<basePath>/mcp`, and `<basePath>/healthz` |
 | `health`          | always ok   | Return `false` for a 503 on `/healthz`                                        |
 | `apiKey`          | off         | Require the caller's key; `hint` is added to the 401 message                  |
+| `oauth`           | off         | Let callers sign in with the upstream service; see [OAuth](#oauth)            |
 | `logger`          | silent      | Anything with `error(obj, msg)`, such as pino                                 |
 
 It returns `{ url, port, close() }`.
@@ -57,9 +58,67 @@ before building an MCP server. The key reaches `createMcpServer` as
 as headers of their own, read from `headers` in the same context.
 
 This suits public servers where each user brings their own credentials: no
-OAuth, no sessions, no database. In claude.ai, add the connector with
+sessions, no database. In claude.ai, add the connector with
 "No sign-in" and the key as a request header.
 
+## OAuth
+
+With `oauth` set, the server is also an OAuth 2.1 authorization server in front
+of an upstream provider, so a client such as claude.ai can connect with a
+sign-in instead of a pasted key. It needs `ENCRYPTION_KEY` (32 bytes, base64)
+and keeps no state: client registrations, codes and tokens are sealed with that
+key, and the upstream token travels inside the access token.
+
+```ts
+import { oauth2Upstream, startMcpHttpServer } from '@ultimatelemon-eu/mcp-http';
+
+await startMcpHttpServer({
+  createMcpServer: ({ apiKey, oauth }) => buildServer(apiKey, oauth?.settings),
+  port: 3000,
+  basePath: '/example',
+  apiKey: {},
+  oauth: {
+    publicUrl: 'https://mcp.example.com',
+    name: 'Example',
+    upstream: oauth2Upstream({
+      authorizeUrl: 'https://example.com/oauth/authorize',
+      tokenUrl: 'https://example.com/oauth/token',
+      clientId: process.env.EXAMPLE_CLIENT_ID ?? '',
+      clientSecret: process.env.EXAMPLE_CLIENT_SECRET ?? '',
+      scopes: ['read']
+    }),
+    settings: async (accessToken) => ({
+      title: 'Choose an account',
+      fields: [
+        {
+          name: 'account',
+          label: 'Account',
+          options: await accountsOf(accessToken)
+        }
+      ]
+    })
+  }
+});
+```
+
+- Register `<publicUrl><basePath>/oauth/callback` as the redirect URI at the
+  upstream provider.
+- Clients register dynamically (RFC 7591) and must use PKCE (S256).
+- `settings` is optional: a form shown once after the upstream sign-in, with
+  radio or checkbox fields. Submitted values are checked against the options,
+  and the answers reach `createMcpServer` as `oauth.settings` on every request.
+- In `createMcpServer`, `apiKey` holds the upstream access token for both
+  callers who signed in and callers who sent a key.
+- Metadata is served on `<basePath>/.well-known/...` and on
+  `/.well-known/oauth-authorization-server<basePath>` (and the protected
+  resource equivalent). Behind a path-routing proxy, route those root paths to
+  the server too.
+- Access tokens last an hour, or less when the upstream token expires sooner;
+  refresh tokens last 90 days and renew the upstream token when needed.
+- Nothing can be revoked server-side: a user revokes the app at the upstream
+  provider, and rotating `ENCRYPTION_KEY` signs everyone out. A code can be
+  redeemed once per process.
+
 ## Why stateless
 
 A new server per request means no session table, so it does not matter which

package/dist/index.d.ts

@@ -1 +1,4 @@
 export { startMcpHttpServer, type ApiKeyOptions, type Logger, type McpHttpOptions, type McpHttpServer, type RequestContext } from './server.js';
+export { type OAuthGrant, type OAuthHandler, type OAuthOptions } from './oauth.js';
+export { type SettingsField, type SettingsForm, type SettingsOption } from './pages.js';
+export { oauth2Upstream, UpstreamError, type OAuth2UpstreamOptions, type OAuthUpstream, type UpstreamTokens } from './upstream.js';

package/dist/index.js

@@ -1 +1,2 @@
 export { startMcpHttpServer } from './server.js';
+export { oauth2Upstream, UpstreamError } from './upstream.js';

package/dist/oauth.d.ts

@@ -0,0 +1,25 @@
+import { type SettingsForm } from './pages.js';
+import type { OAuthUpstream } from './upstream.js';
+export interface OAuthOptions {
+    /** Public origin, e.g. `https://mcp.example.com`. The issuer is this plus the base path. */
+    publicUrl: string;
+    /** Upstream service name for the pages, e.g. `Moneybird`. */
+    name: string;
+    upstream: OAuthUpstream;
+    /** Asked once after the upstream sign-in; the answers travel inside the issued tokens. */
+    settings?: (accessToken: string) => Promise<SettingsForm | undefined>;
+}
+export interface OAuthGrant {
+    /** The upstream access token. */
+    accessToken: string;
+    settings: Record<string, string>;
+}
+export interface OAuthHandler {
+    owns(path: string): boolean;
+    handle(request: Request): Promise<Response>;
+    /** Opens an access token this server issued; undefined when it is not one, or expired. */
+    authenticate(token: string): OAuthGrant | undefined;
+    /** `WWW-Authenticate` value that points a client at the metadata. */
+    challenge(error?: string): string;
+}
+export declare function createOAuthHandler(options: OAuthOptions, basePath: string): OAuthHandler;

package/dist/oauth.js

@@ -0,0 +1,446 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { decrypt, encrypt, isEncrypted } from '@ultimatelemon-eu/crypto';
+import { errorPage, htmlResponse, settingsPage } from './pages.js';
+const STATE_TTL_MS = 10 * 60 * 1000;
+const CODE_TTL_MS = 60 * 1000;
+const ACCESS_TTL_MS = 60 * 60 * 1000;
+const REFRESH_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+const UPSTREAM_LEEWAY_MS = 5 * 60 * 1000;
+const COOKIE = 'mcp_oauth_state';
+function sealer(issuer) {
+    return {
+        seal(value, ttlMs) {
+            const sealed = {
+                ...value,
+                i: issuer,
+                ...(ttlMs === undefined ? {} : { x: Date.now() + ttlMs })
+            };
+            return encrypt(JSON.stringify(sealed));
+        },
+        open(value, type) {
+            if (!value || !isEncrypted(value))
+                return undefined;
+            try {
+                const parsed = JSON.parse(decrypt(value));
+                if (parsed.t !== type || parsed.i !== issuer)
+                    return undefined;
+                if (parsed.x !== undefined && parsed.x < Date.now())
+                    return undefined;
+                return parsed;
+            }
+            catch {
+                return undefined;
+            }
+        }
+    };
+}
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            'content-type': 'application/json',
+            'cache-control': 'no-store',
+            'access-control-allow-origin': '*'
+        }
+    });
+}
+function oauthError(error, description, status = 400) {
+    return json({ error, error_description: description }, status);
+}
+function redirect(location, cookie) {
+    const headers = new Headers({ location, 'cache-control': 'no-store' });
+    if (cookie)
+        headers.append('set-cookie', cookie);
+    return new Response(null, { status: 302, headers });
+}
+function readCookie(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === name)
+            return rest.join('=');
+    }
+    return undefined;
+}
+const LOOPBACK = ['127.0.0.1', '[::1]', 'localhost'];
+function isAllowedRedirectUri(value) {
+    try {
+        const url = new URL(value);
+        if (url.hash)
+            return false;
+        if (url.protocol === 'https:')
+            return true;
+        return url.protocol === 'http:' && LOOPBACK.includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+// Exact match, except that a loopback http uri may use any port (RFC 8252 7.3).
+function redirectUriMatches(registered, presented) {
+    if (registered === presented)
+        return true;
+    try {
+        const left = new URL(registered);
+        const right = new URL(presented);
+        return (left.protocol === 'http:' &&
+            right.protocol === 'http:' &&
+            LOOPBACK.includes(left.hostname) &&
+            left.hostname === right.hostname &&
+            left.pathname === right.pathname &&
+            left.search === right.search);
+    }
+    catch {
+        return false;
+    }
+}
+function verifyPkce(verifier, challenge) {
+    const computed = Buffer.from(createHash('sha256').update(verifier).digest('base64url'));
+    const expected = Buffer.from(challenge);
+    return (computed.length === expected.length && timingSafeEqual(computed, expected));
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+async function readForm(request) {
+    return new URLSearchParams(await request.text());
+}
+/** Validates submitted settings against the form; returns an error message instead when invalid. */
+function readSettings(form, body) {
+    const settings = {};
+    for (const field of form.fields) {
+        const allowed = new Set(field.options.map((option) => option.value));
+        const values = body.getAll(field.name);
+        if (values.some((value) => !allowed.has(value))) {
+            return `"${field.label}" has a value that is not on the list.`;
+        }
+        if (!field.multiple && values.length !== 1) {
+            return `Choose one option for "${field.label}".`;
+        }
+        settings[field.name] = values.join(',');
+    }
+    return settings;
+}
+export function createOAuthHandler(options, basePath) {
+    // Fails at startup rather than at the first sign-in when ENCRYPTION_KEY is missing or malformed.
+    decrypt(encrypt('check'));
+    const origin = options.publicUrl.replace(/\/+$/, '');
+    const issuer = `${origin}${basePath}`;
+    const { seal, open } = sealer(issuer);
+    const resourceMetadataUrl = `${issuer}/.well-known/oauth-protected-resource`;
+    const callbackUri = `${issuer}/oauth/callback`;
+    const paths = {
+        register: `${basePath}/register`,
+        authorize: `${basePath}/authorize`,
+        token: `${basePath}/token`,
+        callback: `${basePath}/oauth/callback`,
+        settings: `${basePath}/oauth/settings`
+    };
+    const resourcePaths = [
+        `${basePath}/.well-known/oauth-protected-resource`,
+        `/.well-known/oauth-protected-resource${basePath}`
+    ];
+    const serverPaths = new Set([
+        `${basePath}/.well-known/oauth-authorization-server`,
+        `${basePath}/.well-known/openid-configuration`,
+        `/.well-known/oauth-authorization-server${basePath}`,
+        `/.well-known/openid-configuration${basePath}`
+    ]);
+    const endpoints = new Set(Object.values(paths));
+    // Codes are sealed, not stored, so this is what keeps one from being redeemed twice.
+    const redeemed = new Map();
+    function remember(code) {
+        const now = Date.now();
+        for (const [key, expires] of redeemed) {
+            if (expires < now)
+                redeemed.delete(key);
+        }
+        const key = sha256(code);
+        if (redeemed.has(key))
+            return false;
+        redeemed.set(key, now + CODE_TTL_MS);
+        return true;
+    }
+    function isResourcePath(path) {
+        return resourcePaths.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+    }
+    function owns(path) {
+        return isResourcePath(path) || serverPaths.has(path) || endpoints.has(path);
+    }
+    function authorizationServerMetadata() {
+        return {
+            issuer,
+            authorization_endpoint: `${origin}${paths.authorize}`,
+            token_endpoint: `${origin}${paths.token}`,
+            registration_endpoint: `${origin}${paths.register}`,
+            response_types_supported: ['code'],
+            response_modes_supported: ['query'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['none'],
+            code_challenge_methods_supported: ['S256']
+        };
+    }
+    async function register(request) {
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return oauthError('invalid_client_metadata', 'Body must be JSON.');
+        }
+        const uris = body.redirect_uris;
+        if (!Array.isArray(uris) ||
+            uris.length === 0 ||
+            !uris.every((uri) => typeof uri === 'string' && isAllowedRedirectUri(uri))) {
+            return oauthError('invalid_redirect_uri', 'redirect_uris must be https uris or loopback http uris.');
+        }
+        return json({
+            client_id: seal({ t: 'client', r: uris }),
+            client_id_issued_at: Math.floor(Date.now() / 1000),
+            redirect_uris: uris,
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+            ...(typeof body.client_name === 'string'
+                ? { client_name: body.client_name }
+                : {})
+        }, 201);
+    }
+    function redirectWithError(flow, error, description) {
+        const url = new URL(flow.r);
+        url.searchParams.set('error', error);
+        url.searchParams.set('error_description', description);
+        if (flow.s !== undefined)
+            url.searchParams.set('state', flow.s);
+        return redirect(url.toString());
+    }
+    // Until the client and redirect uri check out, errors render here: redirecting
+    // to an unverified uri would make this an open redirector.
+    function authorize(url) {
+        const params = url.searchParams;
+        const clientId = params.get('client_id');
+        const redirectUri = params.get('redirect_uri');
+        const client = open(clientId, 'client');
+        if (!clientId || !client) {
+            return htmlResponse(errorPage('Unknown client', 'This client is not registered here. Remove the connector and add it again.'), 400);
+        }
+        if (!redirectUri ||
+            !client.r.some((registered) => redirectUriMatches(registered, redirectUri))) {
+            return htmlResponse(errorPage('Invalid redirect uri', 'The client did not register this redirect uri.'), 400);
+        }
+        const state = params.get('state') ?? undefined;
+        const flow = {
+            r: redirectUri,
+            ...(state !== undefined ? { s: state } : {})
+        };
+        if (params.get('response_type') !== 'code') {
+            return redirectWithError(flow, 'unsupported_response_type', 'Only the authorization code flow is supported.');
+        }
+        const challenge = params.get('code_challenge');
+        if (!challenge || params.get('code_challenge_method') !== 'S256') {
+            return redirectWithError(flow, 'invalid_request', 'PKCE with code_challenge_method=S256 is required.');
+        }
+        const sealed = seal({ t: 'state', c: clientId, p: challenge, ...flow }, STATE_TTL_MS);
+        // The cookie covers an upstream that does not echo `state` back.
+        return redirect(options.upstream.authorizeUrl({
+            redirectUri: callbackUri,
+            state: sealed
+        }), `${COOKIE}=${sealed}; Path=${basePath}/oauth; HttpOnly; Secure; SameSite=Lax; Max-Age=${String(STATE_TTL_MS / 1000)}`);
+    }
+    function finish(flow, tokens, settings) {
+        const code = seal({
+            t: 'code',
+            c: flow.c,
+            r: flow.r,
+            p: flow.p,
+            u: tokens,
+            a: settings,
+            ...(flow.s !== undefined ? { s: flow.s } : {})
+        }, CODE_TTL_MS);
+        const target = new URL(flow.r);
+        target.searchParams.set('code', code);
+        if (flow.s !== undefined)
+            target.searchParams.set('state', flow.s);
+        return redirect(target.toString(), `${COOKIE}=; Path=${basePath}/oauth; HttpOnly; Secure; Max-Age=0`);
+    }
+    async function askSettings(flow, tokens) {
+        const form = await options.settings?.(tokens.accessToken);
+        if (!form || form.fields.length === 0)
+            return finish(flow, tokens, {});
+        const pending = seal({
+            t: 'pending',
+            c: flow.c,
+            r: flow.r,
+            p: flow.p,
+            u: tokens,
+            ...(flow.s !== undefined ? { s: flow.s } : {})
+        }, STATE_TTL_MS);
+        return htmlResponse(settingsPage(form, `${origin}${paths.settings}`, pending), 200);
+    }
+    async function callback(request, url) {
+        const failure = url.searchParams.get('error');
+        if (failure) {
+            return htmlResponse(errorPage(`${options.name} refused the sign-in`, url.searchParams.get('error_description') ?? failure), 400);
+        }
+        const state = open(url.searchParams.get('state'), 'state') ??
+            open(readCookie(request, COOKIE), 'state');
+        const code = url.searchParams.get('code');
+        if (!state || !code) {
+            return htmlResponse(errorPage('Sign-in expired', 'This sign-in is unknown or took too long. Start again from your client.'), 400);
+        }
+        try {
+            const tokens = await options.upstream.exchangeCode({
+                code,
+                redirectUri: callbackUri
+            });
+            return await askSettings(state, tokens);
+        }
+        catch (error) {
+            return htmlResponse(errorPage(`Could not finish signing in to ${options.name}`, error instanceof Error ? error.message : String(error)), 502);
+        }
+    }
+    async function settings(request) {
+        const body = await readForm(request);
+        const pending = open(body.get('pending'), 'pending');
+        if (!pending) {
+            return htmlResponse(errorPage('Sign-in expired', 'This took too long. Start again from your client.'), 400);
+        }
+        let form;
+        try {
+            // Asked again rather than trusted from the page, so only offered values pass.
+            form = await options.settings?.(pending.u.accessToken);
+        }
+        catch (error) {
+            return htmlResponse(errorPage(`Could not reach ${options.name}`, error instanceof Error ? error.message : String(error)), 502);
+        }
+        const answers = form ? readSettings(form, body) : {};
+        if (typeof answers === 'string') {
+            return htmlResponse(errorPage('Invalid choice', answers), 400);
+        }
+        return finish(pending, pending.u, answers);
+    }
+    function issue(clientId, tokens, settings) {
+        // Expire before the upstream token does, so the client refreshes both in time.
+        const ttl = tokens.expiresAt === undefined
+            ? ACCESS_TTL_MS
+            : Math.max(60_000, Math.min(ACCESS_TTL_MS, tokens.expiresAt - Date.now() - UPSTREAM_LEEWAY_MS));
+        return json({
+            access_token: seal({ t: 'access', u: tokens.accessToken, a: settings }, ttl),
+            token_type: 'Bearer',
+            expires_in: Math.floor(ttl / 1000),
+            refresh_token: seal({ t: 'refresh', c: clientId, u: tokens, a: settings }, REFRESH_TTL_MS)
+        });
+    }
+    function exchangeCode(body) {
+        const raw = body.get('code');
+        const verifier = body.get('code_verifier');
+        const code = open(raw, 'code');
+        if (!raw || !code || !verifier) {
+            return oauthError('invalid_grant', 'The code is unknown or expired, or code_verifier is missing.');
+        }
+        const clientId = body.get('client_id');
+        if (clientId !== null && clientId !== code.c) {
+            return oauthError('invalid_grant', 'This code belongs to another client.');
+        }
+        const redirectUri = body.get('redirect_uri');
+        if (redirectUri !== null && redirectUri !== code.r) {
+            return oauthError('invalid_grant', 'redirect_uri does not match.');
+        }
+        if (!verifyPkce(verifier, code.p)) {
+            return oauthError('invalid_grant', 'The PKCE verifier does not match.');
+        }
+        if (!remember(raw)) {
+            return oauthError('invalid_grant', 'This code was already used.');
+        }
+        return issue(code.c, code.u, code.a);
+    }
+    async function exchangeRefresh(body) {
+        const refresh = open(body.get('refresh_token'), 'refresh');
+        if (!refresh) {
+            return oauthError('invalid_grant', 'The refresh token is unknown or expired.');
+        }
+        const clientId = body.get('client_id');
+        if (clientId !== null && clientId !== refresh.c) {
+            return oauthError('invalid_grant', 'This refresh token belongs to another client.');
+        }
+        let tokens = refresh.u;
+        if (tokens.expiresAt !== undefined &&
+            tokens.expiresAt - UPSTREAM_LEEWAY_MS <= Date.now()) {
+            if (!tokens.refreshToken || !options.upstream.refresh) {
+                return oauthError('invalid_grant', `The ${options.name} sign-in expired. Sign in again.`);
+            }
+            try {
+                const renewed = await options.upstream.refresh(tokens.refreshToken);
+                tokens = {
+                    ...renewed,
+                    refreshToken: renewed.refreshToken ?? tokens.refreshToken
+                };
+            }
+            catch (error) {
+                return oauthError('invalid_grant', error instanceof Error ? error.message : String(error));
+            }
+        }
+        return issue(refresh.c, tokens, refresh.a);
+    }
+    async function token(request) {
+        const body = await readForm(request);
+        const grantType = body.get('grant_type');
+        if (grantType === 'authorization_code')
+            return exchangeCode(body);
+        if (grantType === 'refresh_token')
+            return exchangeRefresh(body);
+        return oauthError('unsupported_grant_type', 'Use authorization_code or refresh_token.');
+    }
+    async function handle(request) {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        const method = request.method;
+        if (method === 'OPTIONS') {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    'access-control-allow-origin': '*',
+                    'access-control-allow-methods': 'GET, POST, OPTIONS',
+                    'access-control-allow-headers': 'authorization, content-type, mcp-protocol-version',
+                    'access-control-max-age': '86400'
+                }
+            });
+        }
+        if (method === 'GET' && isResourcePath(path)) {
+            return json({
+                resource: issuer,
+                authorization_servers: [issuer],
+                bearer_methods_supported: ['header'],
+                resource_name: options.name
+            });
+        }
+        if (method === 'GET' && serverPaths.has(path)) {
+            return json(authorizationServerMetadata());
+        }
+        if (method === 'POST' && path === paths.register)
+            return register(request);
+        if (method === 'GET' && path === paths.authorize)
+            return authorize(url);
+        if (method === 'GET' && path === paths.callback) {
+            return callback(request, url);
+        }
+        if (method === 'POST' && path === paths.settings)
+            return settings(request);
+        if (method === 'POST' && path === paths.token)
+            return token(request);
+        return json({ error: 'Method not allowed' }, 405);
+    }
+    return {
+        owns,
+        handle,
+        authenticate(token) {
+            const access = open(token, 'access');
+            return access ? { accessToken: access.u, settings: access.a } : undefined;
+        },
+        challenge(error) {
+            const parts = [`resource_metadata="${resourceMetadataUrl}"`];
+            if (error)
+                parts.unshift(`error="${error}"`);
+            return `Bearer ${parts.join(', ')}`;
+        }
+    };
+}

package/dist/pages.d.ts

@@ -0,0 +1,24 @@
+export interface SettingsOption {
+    value: string;
+    label: string;
+    hint?: string;
+}
+export interface SettingsField {
+    name: string;
+    label: string;
+    hint?: string;
+    options: SettingsOption[];
+    /** Checkboxes instead of radio buttons; the answer is the checked values joined by commas. */
+    multiple?: boolean;
+    /** Values checked when the page opens. */
+    defaults?: string[];
+}
+export interface SettingsForm {
+    title: string;
+    intro?: string;
+    fields: SettingsField[];
+}
+export declare function escapeHtml(value: string): string;
+export declare function htmlResponse(body: string, status: number): Response;
+export declare function errorPage(title: string, detail: string): string;
+export declare function settingsPage(form: SettingsForm, action: string, pending: string): string;

package/dist/pages.js

@@ -0,0 +1,85 @@
+const STYLE = `
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: #fbfbfa; color: #1a1a18;
+  }
+  main { width: min(30rem, calc(100vw - 2rem)); padding: 2rem 0; }
+  h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+  p { margin: 0 0 1.5rem; color: #5c5c56; }
+  fieldset { border: 0; margin: 0 0 1.5rem; padding: 0; display: grid; gap: .5rem; }
+  legend { font-weight: 600; margin-bottom: .25rem; }
+  legend small { display: block; font-weight: 400; color: #5c5c56; }
+  label {
+    display: flex; gap: .75rem; align-items: baseline; padding: .75rem 1rem;
+    border: 1px solid #dcdcd6; border-radius: .5rem; background: #fff; cursor: pointer;
+  }
+  label:has(input:checked) { border-color: #1a1a18; }
+  .hint { display: block; color: #5c5c56; font-size: .875rem; }
+  button {
+    width: 100%; padding: .875rem 1rem; font: inherit; font-weight: 600; cursor: pointer;
+    background: #1a1a18; color: #fbfbfa; border: 0; border-radius: .5rem;
+  }
+  @media (prefers-color-scheme: dark) {
+    body { background: #171715; color: #f2f2ef; }
+    p, .hint, legend small { color: #a3a39c; }
+    label { background: #201f1d; border-color: #35342f; }
+    label:has(input:checked) { border-color: #f2f2ef; }
+    button { background: #f2f2ef; color: #171715; }
+  }
+`;
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function page(title, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body><main>${body}</main></body>
+</html>`;
+}
+export function htmlResponse(body, status) {
+    return new Response(body, {
+        status,
+        headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+            'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'",
+            'x-frame-options': 'DENY'
+        }
+    });
+}
+export function errorPage(title, detail) {
+    return page(title, `<h1>${escapeHtml(title)}</h1><p>${escapeHtml(detail)}</p>`);
+}
+function fieldHtml(field) {
+    const type = field.multiple ? 'checkbox' : 'radio';
+    const checked = new Set(field.defaults ?? (field.multiple ? [] : [field.options[0]?.value ?? '']));
+    const options = field.options
+        .map((option) => `<label>
+        <input type="${type}" name="${escapeHtml(field.name)}" value="${escapeHtml(option.value)}"${checked.has(option.value) ? ' checked' : ''}>
+        <span>${escapeHtml(option.label)}${option.hint ? `<span class="hint">${escapeHtml(option.hint)}</span>` : ''}</span>
+      </label>`)
+        .join('\n');
+    const hint = field.hint ? `<small>${escapeHtml(field.hint)}</small>` : '';
+    return `<fieldset><legend>${escapeHtml(field.label)}${hint}</legend>${options}</fieldset>`;
+}
+export function settingsPage(form, action, pending) {
+    const intro = form.intro ? `<p>${escapeHtml(form.intro)}</p>` : '';
+    return page(form.title, `<h1>${escapeHtml(form.title)}</h1>${intro}
+     <form method="post" action="${escapeHtml(action)}">
+       <input type="hidden" name="pending" value="${escapeHtml(pending)}">
+       ${form.fields.map(fieldHtml).join('\n')}
+       <button type="submit">Connect</button>
+     </form>`);
+}

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { type McpServer } from '@modelcontextprotocol/server';
+import { type OAuthOptions } from './oauth.js';
 /** The slice of a pino-style logger this package calls. */
 export interface Logger {
     error(obj: object, msg?: string): void;
@@ -8,6 +9,10 @@ export interface RequestContext {
     apiKey?: string;
     /** Headers of the HTTP request, for per-caller settings beyond the key. */
     headers: Headers;
+    /** Set when the caller signed in through `oauth`; `apiKey` then holds the upstream token. */
+    oauth?: {
+        settings: Record<string, string>;
+    };
 }
 export interface ApiKeyOptions {
     /** Added to the 401 message, e.g. where to get a key. */
@@ -25,6 +30,8 @@ export interface McpHttpOptions {
     health?: () => boolean | Promise<boolean>;
     /** Require every MCP request to carry the caller's key in `X-Api-Key` or `Authorization: Bearer`. */
     apiKey?: ApiKeyOptions;
+    /** Sign in with the upstream service instead of pasting a key. Needs `ENCRYPTION_KEY`. */
+    oauth?: OAuthOptions;
     logger?: Logger;
 }
 export interface McpHttpServer {

package/dist/server.js

@@ -1,6 +1,8 @@
 import { createServer } from 'node:http';
 import { toNodeHandler } from '@modelcontextprotocol/node';
 import { createMcpHandler } from '@modelcontextprotocol/server';
+import { isEncrypted } from '@ultimatelemon-eu/crypto';
+import { createOAuthHandler } from './oauth.js';
 const silent = { error: () => { } };
 // PKG-10: Node's `Server.close()` waits for every still-open connection to go
 // idle on its own; a keep-alive client that goes idle (or stays busy) *after*
@@ -35,14 +37,51 @@ function jsonRpcError(res, status, message) {
         id: null
     });
 }
-function apiKeyFrom(req) {
+function headerKey(req) {
     const header = req.headers['x-api-key'];
-    const direct = (Array.isArray(header) ? header[0] : header)?.trim();
-    if (direct)
-        return direct;
+    return (Array.isArray(header) ? header[0] : header)?.trim() || undefined;
+}
+function bearerFrom(req) {
     const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? '');
     return bearer?.[1]?.trim() || undefined;
 }
+const MAX_OAUTH_BODY_BYTES = 64 * 1024;
+async function toRequest(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_OAUTH_BODY_BYTES)
+            throw new Error('Request body too large');
+        chunks.push(chunk);
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value !== undefined) {
+            headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+        }
+    }
+    const method = req.method ?? 'GET';
+    return new Request(new URL(req.url ?? '/', 'http://localhost'), {
+        method,
+        headers,
+        ...(method === 'GET' || method === 'HEAD'
+            ? {}
+            : { body: Buffer.concat(chunks) })
+    });
+}
+async function sendResponse(res, response) {
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        if (name !== 'set-cookie')
+            headers[name] = value;
+    });
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length > 0)
+        headers['set-cookie'] = cookies;
+    res.writeHead(response.status, headers);
+    res.end(Buffer.from(await response.arrayBuffer()));
+}
 // PKG-10: closes `http`, letting in-flight requests finish normally. A
 // one-off `closeIdleConnections()` call only catches connections that are
 // already idle at the exact moment close() runs; any connection that is
@@ -80,10 +119,20 @@ export async function startMcpHttpServer(options) {
     if (base)
         mcpPaths.add(base);
     const healthPaths = new Set([`${base}/healthz`, '/healthz']);
+    const oauth = options.oauth
+        ? createOAuthHandler(options.oauth, base)
+        : undefined;
     // The key travels as pass-through authInfo, the SDK's channel from the
     // HTTP request to the per-request factory.
     const mcpHandler = createMcpHandler(({ authInfo, requestInfo }) => options.createMcpServer({
         ...(authInfo ? { apiKey: authInfo.token } : {}),
+        ...(authInfo?.extra?.['settings']
+            ? {
+                oauth: {
+                    settings: authInfo.extra['settings']
+                }
+            }
+            : {}),
         headers: requestInfo?.headers ?? new Headers()
     }), {
         onerror: (error) => {
@@ -102,15 +151,36 @@ export async function startMcpHttpServer(options) {
             jsonRpcError(res, 405, 'Method not allowed');
             return;
         }
-        if (!options.apiKey) {
+        if (!options.apiKey && !oauth) {
             await nodeHandler(req, res);
             return;
         }
-        const apiKey = apiKeyFrom(req);
+        const bearer = bearerFrom(req);
+        // Tokens this server issued are sealed; an upstream key never looks like one.
+        if (oauth && bearer && isEncrypted(bearer) && !headerKey(req)) {
+            const grant = oauth.authenticate(bearer);
+            if (!grant) {
+                res.setHeader('www-authenticate', oauth.challenge('invalid_token'));
+                jsonRpcError(res, 401, 'The access token is invalid or expired.');
+                return;
+            }
+            await nodeHandler(Object.assign(req, {
+                auth: {
+                    token: grant.accessToken,
+                    clientId: 'oauth',
+                    scopes: [],
+                    extra: { settings: grant.settings }
+                }
+            }), res);
+            return;
+        }
+        const apiKey = options.apiKey ? (headerKey(req) ?? bearer) : undefined;
         if (!apiKey) {
-            const hint = options.apiKey.hint ? ` ${options.apiKey.hint}` : '';
-            res.setHeader('www-authenticate', 'Bearer');
-            jsonRpcError(res, 401, `Missing API key: send it in the X-Api-Key header or as Authorization: Bearer <key>.${hint}`);
+            const hint = options.apiKey?.hint ? ` ${options.apiKey.hint}` : '';
+            res.setHeader('www-authenticate', oauth ? oauth.challenge() : 'Bearer');
+            jsonRpcError(res, 401, options.apiKey
+                ? `Missing API key: send it in the X-Api-Key header or as Authorization: Bearer <key>.${hint}`
+                : 'Sign in to use this server.');
             return;
         }
         await nodeHandler(Object.assign(req, {
@@ -128,6 +198,10 @@ export async function startMcpHttpServer(options) {
             await handleMcp(req, res);
             return;
         }
+        if (oauth?.owns(path)) {
+            await sendResponse(res, await oauth.handle(await toRequest(req)));
+            return;
+        }
         sendJson(res, 404, { error: 'Not found' });
     }
     const http = createServer((req, res) => {

package/dist/upstream.d.ts

@@ -0,0 +1,31 @@
+export interface UpstreamTokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds; unset when the upstream token does not expire. */
+    expiresAt?: number;
+}
+/** The OAuth provider behind the server, to which this server is a confidential client. */
+export interface OAuthUpstream {
+    authorizeUrl(params: {
+        redirectUri: string;
+        state: string;
+    }): string;
+    exchangeCode(params: {
+        code: string;
+        redirectUri: string;
+    }): Promise<UpstreamTokens>;
+    refresh?(refreshToken: string): Promise<UpstreamTokens>;
+}
+export interface OAuth2UpstreamOptions {
+    authorizeUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes: readonly string[];
+    fetch?: typeof globalThis.fetch;
+}
+export declare class UpstreamError extends Error {
+    constructor(message: string);
+}
+/** A standard authorization code provider that takes its client secret in the request body. */
+export declare function oauth2Upstream(options: OAuth2UpstreamOptions): OAuthUpstream;

package/dist/upstream.js

@@ -0,0 +1,65 @@
+export class UpstreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UpstreamError';
+    }
+}
+/** A standard authorization code provider that takes its client secret in the request body. */
+export function oauth2Upstream(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    async function token(params) {
+        const response = await fetchImpl(options.tokenUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json'
+            },
+            body: new URLSearchParams({
+                client_id: options.clientId,
+                client_secret: options.clientSecret,
+                ...params
+            })
+        });
+        let body = {};
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // Handled below as a response without an access token.
+        }
+        if (!response.ok || typeof body.access_token !== 'string') {
+            const reason = typeof body.error_description === 'string'
+                ? body.error_description
+                : typeof body.error === 'string'
+                    ? body.error
+                    : `HTTP ${String(response.status)}`;
+            throw new UpstreamError(`Token request failed: ${reason}`);
+        }
+        return {
+            accessToken: body.access_token,
+            ...(typeof body.refresh_token === 'string'
+                ? { refreshToken: body.refresh_token }
+                : {}),
+            ...(typeof body.expires_in === 'number'
+                ? { expiresAt: Date.now() + body.expires_in * 1000 }
+                : {})
+        };
+    }
+    return {
+        authorizeUrl({ redirectUri, state }) {
+            const url = new URL(options.authorizeUrl);
+            url.searchParams.set('client_id', options.clientId);
+            url.searchParams.set('redirect_uri', redirectUri);
+            url.searchParams.set('response_type', 'code');
+            url.searchParams.set('scope', options.scopes.join(' '));
+            url.searchParams.set('state', state);
+            return url.toString();
+        },
+        exchangeCode: ({ code, redirectUri }) => token({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri
+        }),
+        refresh: (refreshToken) => token({ grant_type: 'refresh_token', refresh_token: refreshToken })
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ultimatelemon-eu/mcp-http",
-  "version": "2.2.0",
-  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, the caller's own API key per request, and errors that never leak a stack trace.",
+  "version": "2.3.0",
+  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, the caller's own API key or a stateless OAuth sign-in, and errors that never leak a stack trace.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -41,5 +41,8 @@
   "peerDependencies": {
     "@modelcontextprotocol/node": "^2.1.0",
     "@modelcontextprotocol/server": "^2.3.0"
+  },
+  "dependencies": {
+    "@ultimatelemon-eu/crypto": "^1.0.0"
   }
 }