@mcpmake/core 0.2.4 → 0.3.0

package/dist/emitter/templates/auth-provider.ts.hbs

@@ -3,51 +3,92 @@ import type { AppConfig } from './config.js';
 import { getAccessToken } from './oauth.js';
 {{/if}}
 
+/**
+ * Per-operation outbound-auth requirement (D-H2), forwarded from the tool
+ * handler. Mirrors the generator's ToolAuthRequirement:
+ *   - undefined            → apply every configured scheme (global default).
+ *   - { mode: 'public' }   → apply NO auth (operation declared `security: []`).
+ *   - { mode: 'schemes' }  → apply ONLY the listed OpenAPI scheme names.
+ */
+export type AuthRequirement =
+  | { mode: 'public' }
+  | { mode: 'schemes'; schemeNames: string[] };
+
+/** Whether the scheme named `name` should be applied for this requirement. */
+function schemeApplies(req: AuthRequirement | undefined, name: string): boolean {
+  if (!req) return true; // no per-op requirement → legacy global behavior
+  if (req.mode === 'public') return false; // explicit `security: []`
+  return req.schemeNames.includes(name);
+}
+
 {{#if hasOAuth}}
-export async function getAuthHeaders(config: AppConfig): Promise<Record<string, string>> {
+export async function getAuthHeaders(
+  config: AppConfig,
+  requirement?: AuthRequirement,
+): Promise<Record<string, string>> {
 {{else}}
-export function getAuthHeaders(config: AppConfig): Record<string, string> {
+export function getAuthHeaders(
+  config: AppConfig,
+  requirement?: AuthRequirement,
+): Record<string, string> {
 {{/if}}
   const headers: Record<string, string> = {};
 
 {{#each authSchemes}}
 {{#if (eq type "apiKey")}}
 {{#if (eq in "header")}}
-  if (config.apiKey) {
+  if (config.apiKey && schemeApplies(requirement, {{{json schemeName}}})) {
     headers['{{headerName}}'] = config.apiKey;
   }
 {{/if}}
+{{#if (eq in "cookie")}}
+  // API key sent as a cookie — appended to the Cookie header so it survives
+  // alongside any per-operation cookie parameters set by the handler.
+  if (config.apiKey && schemeApplies(requirement, {{{json schemeName}}})) {
+    const existing = headers['Cookie'];
+    const pair = '{{headerName}}=' + encodeURIComponent(config.apiKey);
+    headers['Cookie'] = existing ? existing + '; ' + pair : pair;
+  }
+{{/if}}
 {{#if (eq in "query")}}
-  // API key sent as query parameter — handled in request URL construction
+  // API key is sent as a query parameter (`{{headerName}}`). Query-string auth is
+  // applied during URL construction (apiKeyQueryName/apiKeyQueryValue in config),
+  // not as a header, so there is nothing to add here.
 {{/if}}
 {{/if}}
 {{#if (eq type "http-bearer")}}
-  if (config.bearerToken) {
+  if (config.bearerToken && schemeApplies(requirement, {{{json schemeName}}})) {
     headers['Authorization'] = `Bearer ${config.bearerToken}`;
   }
 {{/if}}
 {{#if (eq type "http-basic")}}
-  if (config.basicUsername && config.basicPassword) {
+  if (config.basicUsername && config.basicPassword && schemeApplies(requirement, {{{json schemeName}}})) {
     const encoded = Buffer.from(`${config.basicUsername}:${config.basicPassword}`).toString('base64');
     headers['Authorization'] = `Basic ${encoded}`;
   }
 {{/if}}
 {{#if (eq type "oauth2")}}
-  // OAuth2 — use token management with refresh
-  try {
-    const token = await getAccessToken({
-      clientId: config.oauth2ClientId ?? '',
-      clientSecret: config.oauth2ClientSecret,
-      authorizationUrl: config.oauth2AuthorizationUrl ?? '',
-      tokenUrl: config.oauth2TokenUrl ?? '',
-      scopes: [],
-      redirectUri: config.oauth2RedirectUri ?? 'http://localhost:3000/callback',
-    });
-    headers['Authorization'] = `Bearer ${token}`;
-  } catch {
-    // Fallback to pre-obtained token
-    if (config.oauth2Token) {
-      headers['Authorization'] = `Bearer ${config.oauth2Token}`;
+  // OAuth2 — non-interactive grants only (client credentials / refresh /
+  // pre-obtained OAUTH2_TOKEN). The interactive authorization-code flow is
+  // unsupported: a headless server has no /callback route — see oauth.ts.
+  if (schemeApplies(requirement, {{{json schemeName}}})) {
+    try {
+      const token = await getAccessToken({
+        clientId: config.oauth2ClientId ?? '',
+        clientSecret: config.oauth2ClientSecret,
+        authorizationUrl: config.oauth2AuthorizationUrl ?? '',
+        tokenUrl: config.oauth2TokenUrl ?? '',
+        scopes: config.oauth2Scopes,
+        redirectUri: config.oauth2RedirectUri ?? '',
+      });
+      headers['Authorization'] = `Bearer ${token}`;
+    } catch (err) {
+      // Token fetch failed — fall back to a pre-obtained token if present.
+      // Surface the cause (never the token/secret) so it is not swallowed.
+      console.error('OAuth token fetch failed, falling back to OAUTH2_TOKEN:', String(err));
+      if (config.oauth2Token) {
+        headers['Authorization'] = `Bearer ${config.oauth2Token}`;
+      }
     }
   }
 {{/if}}
@@ -55,3 +96,27 @@ export function getAuthHeaders(config: AppConfig): Record<string, string> {
 
   return headers;
 }
+
+/**
+ * Query-string auth parameters (apiKey-in-query schemes), keyed by query-param
+ * name. Applied by the tool handler during URL construction — a query parameter
+ * cannot be sent as a request header (D-H2). Respects the same per-operation
+ * requirement as the headers: a public operation gets none, a scheme-scoped one
+ * gets only its scheme(s).
+ */
+export function getAuthQueryParams(
+  config: AppConfig,
+  requirement?: AuthRequirement,
+): Record<string, string> {
+  const params: Record<string, string> = {};
+{{#each authSchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "query")}}
+  if (config.apiKey && config.apiKeyQueryName && schemeApplies(requirement, {{{json schemeName}}})) {
+    params[config.apiKeyQueryName] = config.apiKey;
+  }
+{{/if}}
+{{/if}}
+{{/each}}
+  return params;
+}

package/dist/emitter/templates/config.ts.hbs

@@ -3,6 +3,10 @@ export interface AppConfig {
 {{#each authSchemes}}
 {{#if (eq type "apiKey")}}
   apiKey?: string;
+{{#if (eq in "query")}}
+  /** Query-parameter name the API key is appended under (apiKey-in-query auth). */
+  apiKeyQueryName?: string;
+{{/if}}
 {{/if}}
 {{#if (eq type "http-bearer")}}
   bearerToken?: string;
@@ -18,6 +22,9 @@ export interface AppConfig {
   oauth2AuthorizationUrl?: string;
   oauth2TokenUrl?: string;
   oauth2RedirectUri?: string;
+  /** OAuth scopes requested on token grants. Defaults to the spec-declared
+   * scopes; override at runtime with OAUTH2_SCOPES (space-separated). */
+  oauth2Scopes: string[];
 {{/if}}
 {{/each}}
   maxRetries: number;
@@ -72,12 +79,33 @@ function loadDefaultHeaders(): Record<string, string> {
   }
 }
 
+{{#each authSchemes}}
+{{#if (eq type "oauth2")}}
+/**
+ * Resolve the OAuth scopes requested on token grants. Defaults to the
+ * spec-declared scopes baked in at generation time; `OAUTH2_SCOPES`
+ * (space-separated) overrides them at runtime. Empty/whitespace tokens are
+ * dropped so a stray space never sends an empty scope.
+ */
+function resolveOAuthScopes(): string[] {
+  const raw = process.env.OAUTH2_SCOPES;
+  if (raw !== undefined) {
+    return raw.split(/\s+/).filter((s) => s.length > 0);
+  }
+  return {{#if scopes}}{{{json scopes}}}{{else}}[]{{/if}};
+}
+
+{{/if}}
+{{/each}}
 export function loadConfig(): AppConfig {
   return {
     baseUrl: resolveBaseUrl(),
 {{#each authSchemes}}
 {{#if (eq type "apiKey")}}
     apiKey: process.env.{{envVarName}},
+{{#if (eq in "query")}}
+    apiKeyQueryName: {{{json headerName}}},
+{{/if}}
 {{/if}}
 {{#if (eq type "http-bearer")}}
     bearerToken: process.env.{{envVarName}},
@@ -93,6 +121,7 @@ export function loadConfig(): AppConfig {
     oauth2AuthorizationUrl: process.env.OAUTH2_AUTHORIZATION_URL,
     oauth2TokenUrl: process.env.OAUTH2_TOKEN_URL,
     oauth2RedirectUri: process.env.OAUTH2_REDIRECT_URI,
+    oauth2Scopes: resolveOAuthScopes(),
 {{/if}}
 {{/each}}
     maxRetries: parseInt(process.env.MAX_RETRIES ?? '3', 10),

package/dist/emitter/templates/dockerfile.hbs

@@ -2,8 +2,14 @@ FROM node:20-alpine AS builder
 
 WORKDIR /app
 
-COPY package.json package-lock.json ./
-RUN npm ci
+COPY package.json ./
+# The generator does not emit a package-lock.json, so use `npm install` (not
+# `npm ci`, which fails without a lockfile). --ignore-scripts: a malicious
+# transitive dependency's install lifecycle hook (preinstall/install/postinstall)
+# would otherwise run as root at build time — install-time RCE in the build
+# container. The server's own compile is an explicit `npm run build` step below,
+# so it does not depend on install hooks.
+RUN npm install --ignore-scripts
 
 COPY tsconfig.json ./
 COPY src/ src/
@@ -19,8 +25,10 @@ ENV PORT=3000
 
 WORKDIR /app
 
-COPY package.json package-lock.json ./
-RUN npm ci --omit=dev
+COPY package.json ./
+# Runtime deps only (no lockfile emitted → `npm install`); --ignore-scripts
+# blocks dependency install hooks from running as root in the final image.
+RUN npm install --omit=dev --ignore-scripts
 
 COPY --from=builder /app/dist dist/
 

package/dist/emitter/templates/env.example.hbs

@@ -49,4 +49,10 @@ MCP_AUTH_TOKEN=
 # — any request can hit any instance). Set to "true" for stateful per-session
 # (Mcp-Session-Id) mode if a client needs resumable streams.
 MCP_STATEFUL=
+# Stateful-session bounds (only used when MCP_STATEFUL=true). The server caps the
+# number of live sessions, evicts ones idle past MCP_SESSION_IDLE_MS, and sweeps
+# on a MCP_SESSION_REAP_MS timer so abandoned sessions can't exhaust memory.
+# MCP_MAX_SESSIONS=1000
+# MCP_SESSION_IDLE_MS=300000
+# MCP_SESSION_REAP_MS=60000
 {{/if}}

package/dist/emitter/templates/http-executor.ts.hbs

@@ -1,4 +1,4 @@
-import { getAuthHeaders } from './auth.js';
+import { getAuthHeaders, type AuthRequirement } from './auth.js';
 import { traceHeaders } from './trace.js';
 import type { AppConfig } from './config.js';
 
@@ -7,6 +7,14 @@ export interface RequestOptions {
   url: string;
   body?: unknown;
   contentType?: string;
+  /**
+   * How to serialize `body` for the upstream request:
+   *   - `json` (default): JSON.stringify, Content-Type stays as given.
+   *   - `form`: URLSearchParams (application/x-www-form-urlencoded).
+   *   - `multipart`: FormData (the runtime sets multipart Content-Type + boundary;
+   *     a per-field { __file__, content, filename } object is sent as a file part).
+   */
+  bodyEncoding?: 'json' | 'form' | 'multipart';
   headers: Record<string, string>;
   config: AppConfig;
   /**
@@ -14,6 +22,71 @@ export interface RequestOptions {
    * absent and `MCP_IDEMPOTENCY_AUTO=true`, a UUID is generated automatically.
    */
   idempotencyKey?: string;
+  /**
+   * Per-operation outbound-auth requirement (D-H2). Forwarded to getAuthHeaders
+   * so a public operation (`security: []`) sends no auth and a scheme-scoped
+   * operation sends only its scheme(s). Omitted → every configured scheme.
+   */
+  authRequirement?: AuthRequirement;
+}
+
+/**
+ * Hard per-request deadline (ms). Without it a stalled upstream keeps a tool
+ * call (and, in async-task mode, the background promise) alive indefinitely.
+ * Override with MCP_REQUEST_TIMEOUT_MS; defaults to 30s.
+ */
+const REQUEST_TIMEOUT_MS = (() => {
+  const raw = typeof process !== 'undefined' ? process.env?.MCP_REQUEST_TIMEOUT_MS : undefined;
+  const n = raw ? Number(raw) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 30_000;
+})();
+
+/**
+ * Maximum upstream response body size (bytes). A malicious or runaway upstream
+ * can otherwise exhaust memory in a single response. Override with
+ * MCP_MAX_RESPONSE_BYTES; defaults to 10 MiB.
+ */
+const MAX_RESPONSE_BYTES = (() => {
+  const raw = typeof process !== 'undefined' ? process.env?.MCP_MAX_RESPONSE_BYTES : undefined;
+  const n = raw ? Number(raw) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : 10 * 1024 * 1024;
+})();
+
+/** Serialize a request body according to its declared encoding. */
+function serializeBody(
+  body: unknown,
+  encoding: 'json' | 'form' | 'multipart' | undefined,
+): { body: string | URLSearchParams | FormData; setContentType: boolean } {
+  if (encoding === 'form') {
+    const params = new URLSearchParams();
+    if (body && typeof body === 'object') {
+      for (const [k, v] of Object.entries(body as Record<string, unknown>)) {
+        if (v !== undefined && v !== null) params.append(k, String(v));
+      }
+    }
+    return { body: params, setContentType: true };
+  }
+  if (encoding === 'multipart') {
+    const form = new FormData();
+    if (body && typeof body === 'object') {
+      for (const [k, v] of Object.entries(body as Record<string, unknown>)) {
+        if (v === undefined || v === null) continue;
+        if (
+          typeof v === 'object' &&
+          '__file__' in (v as Record<string, unknown>) &&
+          'content' in (v as Record<string, unknown>)
+        ) {
+          const f = v as { content: string; filename?: string };
+          form.append(k, new Blob([f.content]), f.filename ?? k);
+        } else {
+          form.append(k, String(v));
+        }
+      }
+    }
+    // Let the runtime set multipart/form-data with the correct boundary.
+    return { body: form, setContentType: false };
+  }
+  return { body: JSON.stringify(body), setContentType: true };
 }
 
 export interface ApiResponse {
@@ -75,7 +148,7 @@ export async function executeRequest(options: RequestOptions): Promise<ApiRespon
   }
   lastRequestTime = Date.now();
 
-  const authHeaders = await getAuthHeaders(config);
+  const authHeaders = await getAuthHeaders(config, options.authRequirement);
   // Header precedence (lowest → highest): auth, runtime default headers
   // (MCP_DEFAULT_HEADERS), W3C Trace Context, then per-call headers.
   // Propagate W3C Trace Context to the upstream API (no-op outside an HTTP
@@ -88,8 +161,15 @@ export async function executeRequest(options: RequestOptions): Promise<ApiRespon
     ...options.headers,
   };
 
-  if (options.body && options.contentType) {
-    headers['Content-Type'] = options.contentType;
+  // Serialize the body for its declared encoding. FormData must NOT carry a
+  // manual Content-Type — the runtime appends the multipart boundary itself.
+  let serializedBody: string | URLSearchParams | FormData | undefined;
+  if (options.body !== undefined && options.body !== null) {
+    const { body, setContentType } = serializeBody(options.body, options.bodyEncoding);
+    serializedBody = body;
+    if (setContentType && options.contentType) {
+      headers['Content-Type'] = options.contentType;
+    }
   }
 
   // Idempotency-Key for mutating requests (explicit per-call, or auto when enabled).
@@ -101,11 +181,16 @@ export async function executeRequest(options: RequestOptions): Promise<ApiRespon
   let lastError: Error | undefined;
 
   for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    // Per-attempt hard deadline. AbortError is not retryable — a timed-out
+    // upstream should fail fast rather than multiply the wait by the retry count.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     try {
       const response = await fetch(options.url, {
         method,
         headers,
-        body: options.body ? JSON.stringify(options.body) : undefined,
+        body: serializedBody,
+        signal: controller.signal,
       });
 
       if (RETRYABLE_STATUS_CODES.includes(response.status) && attempt < config.maxRetries) {
@@ -134,24 +219,82 @@ export async function executeRequest(options: RequestOptions): Promise<ApiRespon
       };
     } catch (error) {
       lastError = error as Error;
+      // A request that hit the hard deadline is cancelled, not retried.
+      const isAbort =
+        error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError');
+      if (isAbort) {
+        throw new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`);
+      }
       if (error instanceof ApiError && !RETRYABLE_STATUS_CODES.includes(error.status)) {
         throw error;
       }
       if (attempt < config.maxRetries) {
         await sleep(1000 * Math.pow(2, attempt));
       }
+    } finally {
+      clearTimeout(timer);
     }
   }
 
   throw lastError ?? new Error('Request failed after retries');
 }
 
+/**
+ * Read a response body with a hard byte cap. Streaming the body lets us abort as
+ * soon as the cap is exceeded instead of buffering an unbounded (or dishonest
+ * Content-Length) payload into memory.
+ */
+async function readBounded(response: Response): Promise<string> {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    throw new Error(`Response too large (${declared} bytes > ${MAX_RESPONSE_BYTES} cap)`);
+  }
+  if (!response.body) {
+    return response.text();
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > MAX_RESPONSE_BYTES) {
+          await reader.cancel();
+          throw new Error(`Response exceeded ${MAX_RESPONSE_BYTES}-byte cap (truncated)`);
+        }
+        chunks.push(value);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return new TextDecoder().decode(concatChunks(chunks, total));
+}
+
+function concatChunks(chunks: Uint8Array[], total: number): Uint8Array {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
 async function parseResponseBody(response: Response): Promise<unknown> {
   const contentType = response.headers.get('content-type') ?? '';
+  const text = await readBounded(response);
   if (contentType.includes('application/json')) {
-    return response.json();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
   }
-  return response.text();
+  return text;
 }
 
 function sleep(ms: number): Promise<void> {

package/dist/emitter/templates/oauth.ts.hbs

@@ -1,10 +1,16 @@
 /**
  * OAuth 2.1 token management.
- * Supports Authorization Code + PKCE and Client Credentials flows.
+ *
+ * Supports the non-interactive grants a headless generated server can actually
+ * complete: Client Credentials (machine-to-machine), refresh-token rotation,
+ * and a pre-obtained token supplied via OAUTH2_TOKEN.
+ *
+ * The interactive Authorization-Code + PKCE flow is NOT supported: a generated
+ * server has no /callback route, no browser, and no way to drive a user consent
+ * redirect. Operators authenticate by providing OAUTH2_TOKEN, or
+ * OAUTH2_CLIENT_ID + OAUTH2_CLIENT_SECRET for the client-credentials grant.
  */
 
-import crypto from 'node:crypto';
-
 export interface OAuthConfig {
   clientId: string;
   clientSecret?: string;
@@ -38,8 +44,10 @@ export async function getAccessToken(config: OAuthConfig): Promise<string> {
       const token = await refreshToken(config, cachedToken.refreshToken);
       cacheToken(token);
       return token.access_token;
-    } catch {
-      // Refresh failed — fall through to re-authenticate
+    } catch (err) {
+      // Refresh failed — fall through to re-authenticate. Surface the cause
+      // (never the token/secret) so the failure is observable, not silent.
+      console.error('OAuth token refresh failed, re-authenticating:', String(err));
     }
   }
 
@@ -108,62 +116,6 @@ async function refreshToken(config: OAuthConfig, refreshTokenValue: string): Pro
   return response.json() as Promise<TokenResponse>;
 }
 
-/**
- * Generate PKCE code verifier and challenge for Authorization Code flow.
- */
-export function generatePkce(): { codeVerifier: string; codeChallenge: string } {
-  const codeVerifier = crypto.randomBytes(32).toString('base64url');
-  const codeChallenge = crypto
-    .createHash('sha256')
-    .update(codeVerifier)
-    .digest('base64url');
-  return { codeVerifier, codeChallenge };
-}
-
-/**
- * Build the authorization URL for the Authorization Code + PKCE flow.
- */
-export function buildAuthorizationUrl(config: OAuthConfig, state: string, codeChallenge: string): string {
-  const params = new URLSearchParams({
-    response_type: 'code',
-    client_id: config.clientId,
-    redirect_uri: config.redirectUri,
-    state,
-    code_challenge: codeChallenge,
-    code_challenge_method: 'S256',
-    ...(config.scopes.length > 0 ? { scope: config.scopes.join(' ') } : {}),
-  });
-  return `${config.authorizationUrl}?${params.toString()}`;
-}
-
-/**
- * Exchange an authorization code for tokens (PKCE flow).
- */
-export async function exchangeCode(config: OAuthConfig, code: string, codeVerifier: string): Promise<TokenResponse> {
-  const params = new URLSearchParams({
-    grant_type: 'authorization_code',
-    client_id: config.clientId,
-    code,
-    redirect_uri: config.redirectUri,
-    code_verifier: codeVerifier,
-  });
-
-  const response = await fetch(config.tokenUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-    body: params.toString(),
-  });
-
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`OAuth code exchange failed (${response.status}): ${body}`);
-  }
-
-  const token = await response.json() as TokenResponse;
-  cacheToken(token);
-  return token;
-}
-
 function cacheToken(token: TokenResponse): void {
   cachedToken = {
     accessToken: token.access_token,
@@ -174,15 +126,17 @@ function cacheToken(token: TokenResponse): void {
 
 /**
  * OAuth Authorization Server Metadata (RFC 8414).
+ *
+ * Advertises only the grants this server can actually complete: client
+ * credentials and refresh-token (plus a pre-obtained OAUTH2_TOKEN). The
+ * interactive authorization-code flow is intentionally omitted — there is no
+ * /callback route to complete it (see the file header).
  */
 export function getAuthServerMetadata(config: OAuthConfig, issuer: string): Record<string, unknown> {
   return {
     issuer,
-    authorization_endpoint: config.authorizationUrl,
     token_endpoint: config.tokenUrl,
-    response_types_supported: ['code'],
-    grant_types_supported: ['authorization_code', 'client_credentials', 'refresh_token'],
-    code_challenge_methods_supported: ['S256'],
+    grant_types_supported: ['client_credentials', 'refresh_token'],
     scopes_supported: config.scopes,
   };
 }