mcp-auth-wrapper 1.0.0

package/dist/oauth-provider.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrapperOAuthProvider = void 0;
+const node_crypto_1 = require("node:crypto");
+const ACCESS_TOKEN_TTL_MS = 3_600_000; // 1 hour
+const REFRESH_TOKEN_TTL_MS = 30 * 24 * 3_600_000; // 30 days — must be > ACCESS_TOKEN_TTL_MS, otherwise refresh is useless
+const AUTH_CODE_TTL_MS = 300_000; // 5 minutes
+const PENDING_AUTH_TTL_MS = 600_000; // 10 minutes — must be >= AUTH_CODE_TTL_MS, as pending auth spans upstream login + param collection
+/** Encrypt + authenticate a JSON payload. Returns a URL-safe base64 string. */
+const seal = (payload, key) => {
+    const iv = (0, node_crypto_1.randomBytes)(12);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    const plaintext = Buffer.from(JSON.stringify(payload));
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]).toString('base64url');
+};
+/** Decrypt + verify a sealed payload. Returns undefined if tampered or expired. */
+const unseal = (sealed, key) => {
+    try {
+        const buf = Buffer.from(sealed, 'base64url');
+        const iv = buf.subarray(0, 12);
+        const tag = buf.subarray(12, 28);
+        const encrypted = buf.subarray(28);
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+        const payload = JSON.parse(decrypted.toString());
+        if (payload.expiresAt < Date.now()) {
+            return undefined;
+        }
+        return payload;
+    }
+    catch {
+        return undefined;
+    }
+};
+class WrapperOAuthProvider {
+    oidcClient;
+    config;
+    clientsStore;
+    key;
+    constructor(oidcClient, config) {
+        this.oidcClient = oidcClient;
+        this.config = config;
+        this.key = config.secret
+            ? (0, node_crypto_1.createHash)('sha256').update(config.secret).digest()
+            : (0, node_crypto_1.randomBytes)(32);
+        this.clientsStore = {
+            // Always return a synthetic client — we handle /authorize ourselves
+            // and only need this for the SDK's /token client authentication.
+            getClient: (clientId) => ({
+                client_id: clientId,
+                redirect_uris: [],
+                token_endpoint_auth_method: 'none',
+            }),
+            registerClient: (metadata) => ({
+                ...metadata,
+                client_id: metadata.client_id || (0, node_crypto_1.randomUUID)(),
+                client_id_issued_at: Math.floor(Date.now() / 1000),
+            }),
+        };
+    }
+    async authorize(client, params, res) {
+        const { codeVerifier, codeChallenge } = this.oidcClient.generateCodeVerifierAndChallenge();
+        const payload = {
+            upstreamCodeVerifier: codeVerifier,
+            clientId: client.client_id,
+            redirectUri: params.redirectUri,
+            codeChallenge: params.codeChallenge,
+            scopes: params.scopes ?? [],
+            expiresAt: Date.now() + PENDING_AUTH_TTL_MS,
+        };
+        if (params.state) {
+            payload.state = params.state;
+        }
+        const sealedState = seal(payload, this.key);
+        const issuerUrl = this.config.issuerUrl ?? `http://localhost:${this.config.port ?? 3000}`;
+        const callbackUrl = `${issuerUrl}/callback`;
+        const url = await this.oidcClient.buildAuthorizeUrl({
+            redirectUri: callbackUrl,
+            state: sealedState,
+            codeChallenge,
+        });
+        res.redirect(url);
+    }
+    /** Unseal the state returned from the upstream callback. */
+    unsealState(sealedState) {
+        return unseal(sealedState, this.key);
+    }
+    /** Re-seal a modified payload (e.g. after adding userId). */
+    sealState(payload) {
+        return seal(payload, this.key);
+    }
+    completeAuthorization(pending, userId) {
+        const code = seal({
+            clientId: pending.clientId,
+            userId,
+            codeChallenge: pending.codeChallenge,
+            redirectUri: pending.redirectUri,
+            scopes: pending.scopes,
+            expiresAt: Date.now() + AUTH_CODE_TTL_MS,
+        }, this.key);
+        const redirectUrl = new URL(pending.redirectUri);
+        redirectUrl.searchParams.set('code', code);
+        if (pending.state) {
+            redirectUrl.searchParams.set('state', pending.state);
+        }
+        return { redirectUrl: redirectUrl.toString() };
+    }
+    async challengeForAuthorizationCode(_client, authorizationCode) {
+        const ac = unseal(authorizationCode, this.key);
+        if (!ac) {
+            throw new Error('Invalid authorization code');
+        }
+        return ac.codeChallenge;
+    }
+    // Note: we don't validate redirect_uri here. OAuth 2.1 requires it, but since we
+    // don't enforce client registration (any client_id + redirect_uri is accepted), there's
+    // nothing meaningful to check against. PKCE prevents code interception regardless.
+    async exchangeAuthorizationCode(client, authorizationCode) {
+        const ac = unseal(authorizationCode, this.key);
+        if (!ac) {
+            throw new Error('Invalid authorization code');
+        }
+        if (ac.clientId !== client.client_id) {
+            throw new Error('Authorization code was not issued to this client');
+        }
+        const accessToken = seal({
+            type: 'access',
+            clientId: client.client_id,
+            userId: ac.userId,
+            scopes: ac.scopes,
+            expiresAt: Date.now() + ACCESS_TOKEN_TTL_MS,
+        }, this.key);
+        const refreshToken = seal({
+            type: 'refresh',
+            clientId: client.client_id,
+            userId: ac.userId,
+            scopes: ac.scopes,
+            expiresAt: Date.now() + REFRESH_TOKEN_TTL_MS,
+        }, this.key);
+        return {
+            access_token: accessToken,
+            token_type: 'bearer',
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: refreshToken,
+            scope: ac.scopes.join(' '),
+        };
+    }
+    async exchangeRefreshToken(client, refreshToken) {
+        const rt = unseal(refreshToken, this.key);
+        if (!rt || rt.type !== 'refresh') {
+            throw new Error('Invalid refresh token');
+        }
+        if (rt.clientId !== client.client_id) {
+            throw new Error('Refresh token was not issued to this client');
+        }
+        const newAccessToken = seal({
+            type: 'access',
+            clientId: client.client_id,
+            userId: rt.userId,
+            scopes: rt.scopes,
+            expiresAt: Date.now() + ACCESS_TOKEN_TTL_MS,
+        }, this.key);
+        const newRefreshToken = seal({
+            type: 'refresh',
+            clientId: client.client_id,
+            userId: rt.userId,
+            scopes: rt.scopes,
+            expiresAt: Date.now() + REFRESH_TOKEN_TTL_MS,
+        }, this.key);
+        return {
+            access_token: newAccessToken,
+            token_type: 'bearer',
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: newRefreshToken,
+            scope: rt.scopes.join(' '),
+        };
+    }
+    async verifyAccessToken(token) {
+        const td = unseal(token, this.key);
+        if (!td || td.type !== 'access') {
+            throw new Error('Invalid or expired access token');
+        }
+        return {
+            token,
+            clientId: td.clientId,
+            scopes: td.scopes,
+            expiresAt: Math.floor(td.expiresAt / 1000),
+            extra: { userId: td.userId },
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- required by OAuthServerProvider interface
+    async revokeToken(client, request) {
+        // Tokens are stateless sealed blobs — revocation is a no-op.
+        // Tokens remain valid until their TTL expires.
+    }
+}
+exports.WrapperOAuthProvider = WrapperOAuthProvider;

package/dist/pages.d.ts

@@ -0,0 +1,3 @@
+import type { EnvParam } from './types.js';
+export declare const renderParamsForm: (params: EnvParam[], sessionId: string, existingValues?: Record<string, string>) => string;
+export declare const renderReconfigurePage: (params: EnvParam[], token: string, existingValues: Record<string, string>, saved?: boolean) => string;

package/dist/pages.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReconfigurePage = exports.renderParamsForm = void 0;
+const escapeHtml = (s) => s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+const renderParamsForm = (params, sessionId, existingValues) => `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Configure MCP Server</title>
+<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:40px auto;padding:0 20px}
+label{display:block;margin:16px 0 4px;font-weight:600}
+input{width:100%;padding:8px;box-sizing:border-box;border:1px solid #ccc;border-radius:4px}
+button{margin-top:20px;padding:10px 24px;background:#0066cc;color:#fff;border:none;border-radius:4px;cursor:pointer;font-size:16px}
+.desc{font-size:13px;color:#666;margin-top:2px}</style>
+</head><body>
+<h1>Configure MCP Server</h1>
+<p>Enter your credentials to complete setup.</p>
+<form method="POST">
+<input type="hidden" name="session" value="${escapeHtml(sessionId)}">
+${params.map((p) => `<label for="${escapeHtml(p.name)}">${escapeHtml(p.label)}</label>
+${p.description ? `<div class="desc">${escapeHtml(p.description)}</div>` : ''}
+<input id="${escapeHtml(p.name)}" name="${escapeHtml(p.name)}" type="${p.secret ? 'password' : 'text'}" value="${escapeHtml(existingValues?.[p.name] ?? '')}">`).join('\n')}
+<button type="submit">Save &amp; Continue</button>
+</form></body></html>`;
+exports.renderParamsForm = renderParamsForm;
+const renderReconfigurePage = (params, token, existingValues, saved) => `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Reconfigure MCP Server</title>
+<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:40px auto;padding:0 20px}
+label{display:block;margin:16px 0 4px;font-weight:600}
+input{width:100%;padding:8px;box-sizing:border-box;border:1px solid #ccc;border-radius:4px}
+button{margin-top:20px;padding:10px 24px;background:#0066cc;color:#fff;border:none;border-radius:4px;cursor:pointer;font-size:16px}
+.desc{font-size:13px;color:#666;margin-top:2px}
+.success{background:#d4edda;border:1px solid #c3e6cb;padding:12px;border-radius:4px;margin-bottom:16px}</style>
+</head><body>
+<h1>Reconfigure MCP Server</h1>
+${saved ? '<div class="success">Settings saved. Your MCP server will use the new configuration on the next request.</div>' : ''}
+<p>Update your credentials below.</p>
+<form method="POST">
+<input type="hidden" name="token" value="${escapeHtml(token)}">
+${params.map((p) => `<label for="${escapeHtml(p.name)}">${escapeHtml(p.label)}</label>
+${p.description ? `<div class="desc">${escapeHtml(p.description)}</div>` : ''}
+<input id="${escapeHtml(p.name)}" name="${escapeHtml(p.name)}" type="${p.secret ? 'password' : 'text'}" value="${escapeHtml(existingValues[p.name] ?? '')}">`).join('\n')}
+<button type="submit">Save</button>
+</form></body></html>`;
+exports.renderReconfigurePage = renderReconfigurePage;

package/dist/process-pool.d.ts

@@ -0,0 +1,15 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Store } from './store.js';
+export declare class ProcessPool {
+    private readonly command;
+    private readonly args;
+    private readonly baseEnv;
+    private readonly store;
+    private readonly processes;
+    private readonly reapInterval;
+    constructor(command: string, args: string[], baseEnv: Record<string, string>, store: Store);
+    getClient(userId: string): Promise<Client>;
+    invalidateUser(userId: string): void;
+    shutdown(): Promise<void>;
+    private reapIdle;
+}

package/dist/process-pool.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessPool = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const IDLE_TIMEOUT_MS = 300_000;
+const noop = () => { };
+class ProcessPool {
+    command;
+    args;
+    baseEnv;
+    store;
+    processes = new Map();
+    reapInterval;
+    constructor(command, args, baseEnv, store) {
+        this.command = command;
+        this.args = args;
+        this.baseEnv = baseEnv;
+        this.store = store;
+        this.reapInterval = setInterval(() => {
+            this.reapIdle();
+        }, 60_000);
+    }
+    async getClient(userId) {
+        const existing = this.processes.get(userId);
+        if (existing) {
+            existing.lastUsed = Date.now();
+            return existing.client;
+        }
+        const userParams = this.store.getUser(userId);
+        if (!userParams) {
+            throw new Error(`Unknown user: ${userId}`);
+        }
+        const transport = new stdio_js_1.StdioClientTransport({
+            command: this.command,
+            args: this.args,
+            env: { ...process.env, ...this.baseEnv, ...userParams },
+        });
+        const client = new index_js_1.Client({ name: 'mcp-auth-wrapper', version: '1.0.0' });
+        await client.connect(transport);
+        this.processes.set(userId, { client, transport, lastUsed: Date.now() });
+        // Remove stale entry if the child process dies unexpectedly
+        transport.onclose = () => {
+            this.processes.delete(userId);
+        };
+        transport.onerror = () => {
+            this.processes.delete(userId);
+        };
+        return client;
+    }
+    invalidateUser(userId) {
+        const entry = this.processes.get(userId);
+        if (entry) {
+            entry.client.close().catch(noop);
+            this.processes.delete(userId);
+        }
+    }
+    async shutdown() {
+        if (this.reapInterval) {
+            clearInterval(this.reapInterval);
+        }
+        await Promise.all([...this.processes.values()].map(async (entry) => entry.client.close().catch(noop)));
+        this.processes.clear();
+    }
+    reapIdle() {
+        const now = Date.now();
+        for (const [userId, entry] of this.processes) {
+            if (now - entry.lastUsed > IDLE_TIMEOUT_MS) {
+                entry.client.close().catch(noop);
+                this.processes.delete(userId);
+            }
+        }
+    }
+}
+exports.ProcessPool = ProcessPool;

package/dist/reconfigure-tool.d.ts

@@ -0,0 +1,44 @@
+import type { EnvParam } from './types.js';
+import type { Store } from './store.js';
+import type { ProcessPool } from './process-pool.js';
+export declare const RECONFIGURE_TOOL_NAME = "mcp_auth_wrapper__reconfigure";
+export declare const getReconfigureTool: (reconfigureUrl: string, envParams: EnvParam[]) => {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            [k: string]: {
+                type: "string";
+                description: string;
+            };
+        };
+    };
+};
+export declare const handleReconfigureCall: (args: Record<string, unknown>, { store, pool, userId, envPerUser, reconfigureUrl }: {
+    store: Store;
+    pool: ProcessPool;
+    userId: string;
+    envPerUser: EnvParam[];
+    reconfigureUrl: string;
+}) => {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: string;
+        validParameters: string[];
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        status: string;
+        message: string;
+    };
+    isError?: never;
+};

package/dist/reconfigure-tool.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleReconfigureCall = exports.getReconfigureTool = exports.RECONFIGURE_TOOL_NAME = void 0;
+exports.RECONFIGURE_TOOL_NAME = 'mcp_auth_wrapper__reconfigure';
+const getReconfigureTool = (reconfigureUrl, envParams) => ({
+    name: exports.RECONFIGURE_TOOL_NAME,
+    description: 'Update your configuration for this MCP server. Call with parameter values to update directly, or call with no arguments to get a browser URL for configuration.',
+    inputSchema: {
+        type: 'object',
+        properties: Object.fromEntries(envParams.map((p) => [
+            p.name,
+            { type: 'string', description: p.description ?? p.label },
+        ])),
+    },
+});
+exports.getReconfigureTool = getReconfigureTool;
+const handleReconfigureCall = (args, { store, pool, userId, envPerUser, reconfigureUrl }) => {
+    const knownNames = new Set(envPerUser.map((p) => p.name));
+    const unknownKeys = Object.keys(args).filter((k) => !knownNames.has(k));
+    if (unknownKeys.length > 0) {
+        const result = {
+            error: `Unknown parameter(s): ${unknownKeys.join(', ')}`,
+            validParameters: envPerUser.map((p) => p.name),
+        };
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    }
+    const hasValues = envPerUser.some((p) => typeof args[p.name] === 'string' && args[p.name] !== '');
+    if (hasValues) {
+        const params = {};
+        for (const p of envPerUser) {
+            const val = args[p.name];
+            if (typeof val === 'string' && val !== '') {
+                params[p.name] = val;
+            }
+        }
+        try {
+            store.upsertUser(userId, params);
+            pool.invalidateUser(userId);
+            const result = {
+                status: 'updated',
+                message: 'Configuration updated. Your MCP server will use the new settings on the next request.',
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch {
+            // Storage is read-only (inline config) — fall through to URL mode
+        }
+    }
+    const result = {
+        status: 'reconfigure',
+        url: reconfigureUrl,
+        message: 'To update your configuration, open this URL in your browser. After saving changes, your MCP server process will restart with the new settings.',
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        structuredContent: result,
+    };
+};
+exports.handleReconfigureCall = handleReconfigureCall;

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import express from 'express';
+import type { WrapperOAuthProvider } from './oauth-provider.js';
+import type { OidcClient } from './auth.js';
+import type { Store } from './store.js';
+import type { ProcessPool } from './process-pool.js';
+import type { WrapperConfig } from './types.js';
+export declare const createApp: (config: WrapperConfig, pool: ProcessPool, provider: WrapperOAuthProvider, oidcClient: OidcClient, store: Store) => express.Express;