@mcpmake/core 0.2.5 → 0.3.0

package/dist/emitter/site-templates/browser-manager.ts.hbs

@@ -6,6 +6,7 @@
 import { chromium } from 'playwright';
 import type { Browser, BrowserContext, Page } from 'playwright';
 import type { BrowserConfig } from './config.js';
+import * as telemetry from './telemetry.js';
 
 interface BrowserSession {
   context: BrowserContext;
@@ -177,6 +178,10 @@ async function createSession(id: string): Promise<{ page: Page; sessionId: strin
 
     resetIdleTimer();
 
+    // The browser context is now resident — start billing this session (no-op
+    // unless the host injected telemetry env).
+    telemetry.sessionStarted(id);
+
     return { page, sessionId: id };
   } catch (err) {
     // Release the reserved slot if context creation failed.
@@ -195,6 +200,7 @@ export async function closeSession(sessionId?: string): Promise<void> {
 
   await session.context?.close().catch(() => {});
   sessions.delete(id);
+  telemetry.sessionEnded(id, 'explicit');
 
   // If no sessions remain, close the browser
   if (sessions.size === 0) {
@@ -211,6 +217,7 @@ export async function closeBrowser(): Promise<void> {
   for (const [id, session] of sessions) {
     await session.context?.close().catch(() => {});
     sessions.delete(id);
+    telemetry.sessionEnded(id, 'shutdown');
   }
 
   if (browser) {
@@ -261,6 +268,7 @@ function resetIdleTimer(): void {
       if (now - session.lastAccessedAt > config.idleTimeoutMs) {
         session.context.close().catch(() => {});
         sessions.delete(id);
+        telemetry.sessionEnded(id, 'idle');
       }
     }
     // Close browser if no sessions
@@ -277,6 +285,19 @@ function clearIdleTimer(): void {
   }
 }
 
-// Clean up on process exit
-process.on('SIGTERM', () => closeBrowser());
-process.on('SIGINT', () => closeBrowser());
+// Clean up on process exit. Close the browser (which emits a session_end for
+// every still-resident session), then flush telemetry best-effort so the host
+// sees the final boundary instead of waiting out the heartbeat grace.
+async function shutdown(): Promise<void> {
+  try {
+    await closeBrowser();
+  } finally {
+    await telemetry.flushOnShutdown();
+  }
+}
+process.on('SIGTERM', () => {
+  void shutdown();
+});
+process.on('SIGINT', () => {
+  void shutdown();
+});

package/dist/emitter/site-templates/dockerfile.hbs

@@ -5,8 +5,14 @@
 FROM mcr.microsoft.com/playwright:v1.59.1-noble 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/
 RUN npm run build
@@ -20,8 +26,11 @@ ENV PORT=3000
 ENV HEADLESS=true
 
 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. The Playwright browser
+# binaries ship in the base image, so no install-time download lifecycle is needed.
+RUN npm install --omit=dev --ignore-scripts
 
 COPY --from=builder /app/dist dist/
 

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

@@ -9,6 +9,14 @@ IDLE_TIMEOUT_MS={{browserConfig.idleTimeoutMs}}
 VIEWPORT_WIDTH={{browserConfig.viewport.width}}
 VIEWPORT_HEIGHT={{browserConfig.viewport.height}}
 # USER_AGENT=
+
+# Browser-session telemetry (managed hosting only — leave UNSET to self-host).
+# When the host sets these, the server reports exact browser-session lifetime
+# for metering. It NEVER phones home unless MCPMAKE_TELEMETRY_URL is set.
+# MCPMAKE_TELEMETRY_URL=
+# MCPMAKE_TELEMETRY_TOKEN=
+# MCPMAKE_SERVER_SLUG=
+# MCPMAKE_TELEMETRY_HEARTBEAT_MS=30000
 {{#if (eq transport "http")}}
 
 # Transport: "stdio" or "http"

package/dist/emitter/site-templates/server-main-http.ts.hbs

@@ -1,4 +1,5 @@
 import http from 'node:http';
+import crypto from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -28,6 +29,47 @@ function createMcpServer(): McpServer {
   return server;
 }
 
+/* Bearer authentication — mirrors the API/node server. Constant-time compare of
+ * the `Authorization: Bearer <token>` header against MCP_AUTH_TOKEN.
+ *
+ * Fail CLOSED: when MCP_AUTH_TOKEN is unset, authenticated routes are denied
+ * unless the operator opts in with MCP_ALLOW_UNAUTHENTICATED === 'true' (a
+ * local/dev escape hatch). We warn once so the open posture is loud. The token
+ * is never read from the query string — URLs leak through logs and referrers. */
+let unauthWarned = false;
+function isAuthorized(req: http.IncomingMessage): boolean {
+  const expected = process.env.MCP_AUTH_TOKEN;
+  if (!expected) {
+    if (process.env.MCP_ALLOW_UNAUTHENTICATED === 'true') {
+      if (!unauthWarned) {
+        unauthWarned = true;
+        console.error(
+          'SECURITY: MCP_AUTH_TOKEN is unset and MCP_ALLOW_UNAUTHENTICATED=true — ' +
+            'serving authenticated routes WITHOUT a bearer token. ' +
+            'Set MCP_AUTH_TOKEN before exposing this endpoint.',
+        );
+      }
+      return true;
+    }
+    if (!unauthWarned) {
+      unauthWarned = true;
+      console.error(
+        'SECURITY: MCP_AUTH_TOKEN is unset — denying all authenticated routes. ' +
+          'Set MCP_AUTH_TOKEN, or set MCP_ALLOW_UNAUTHENTICATED=true for local/dev only.',
+      );
+    }
+    return false;
+  }
+  const header = req.headers.authorization;
+  if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
+  const presented = header.slice(7).trim();
+  if (!presented) return false;
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
 let isReady = false;
 
 if (process.env.TRANSPORT === 'http') {
@@ -50,6 +92,17 @@ if (process.env.TRANSPORT === 'http') {
     }
 
     if (url.pathname === '/mcp') {
+      // Bearer auth (in addition to the origin check below). /health and /ready
+      // above stay open for liveness/readiness probes.
+      if (!isAuthorized(req)) {
+        res.writeHead(401, {
+          'Content-Type': 'application/json',
+          'WWW-Authenticate': 'Bearer',
+        });
+        res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid bearer token' }));
+        return;
+      }
+
       if (allowedOrigin) {
         // Compare host-to-host exactly (DNS-rebinding protection). A substring
         // match would let "evil-{ALLOWED_ORIGIN}.attacker.com" through.

package/dist/emitter/site-templates/telemetry.ts.hbs

@@ -0,0 +1,117 @@
+/**
+ * Browser-session telemetry for exact metering on managed hosting.
+ *
+ * NO-OP unless MCPMAKE_TELEMETRY_URL is set — a self-hosted or local server
+ * never phones home. When the cloud injects the ingest URL + token + slug, this
+ * batches session_start / heartbeat / session_end events and POSTs them so the
+ * host can bill the REAL resident browser lifetime instead of approximating it
+ * from request latency.
+ *
+ * Strictly best-effort and isolated: every network/serialization error is
+ * swallowed. Telemetry must NEVER affect the MCP server's behavior. Dropped
+ * events can only ever UNDER-bill (the host applies a heartbeat grace + an
+ * independent proxy-activity clamp), never break a tool call.
+ *
+ * An OPEN session emits a heartbeat on every flush: an open session means a
+ * resident Chromium context, which is the billable cost — independent of how
+ * often tools are called. The host treats "last heartbeat + grace" as the close
+ * time if a session_end is ever lost (e.g. the server is killed).
+ */
+
+type TelemetryEventType = 'session_start' | 'heartbeat' | 'session_end';
+
+interface TelemetryEvent {
+  type: TelemetryEventType;
+  sessionId: string;
+  ts: number;
+  reason?: string;
+}
+
+const TELEMETRY_URL = process.env.MCPMAKE_TELEMETRY_URL;
+const TELEMETRY_TOKEN = process.env.MCPMAKE_TELEMETRY_TOKEN ?? '';
+const SERVER_SLUG = process.env.MCPMAKE_SERVER_SLUG ?? '';
+const HEARTBEAT_MS = (() => {
+  const n = parseInt(process.env.MCPMAKE_TELEMETRY_HEARTBEAT_MS ?? '30000', 10);
+  return Number.isFinite(n) && n >= 1000 ? n : 30000;
+})();
+const POST_TIMEOUT_MS = 5000;
+const MAX_BUFFER = 1000;
+
+const ENABLED = Boolean(TELEMETRY_URL) && Boolean(TELEMETRY_TOKEN) && Boolean(SERVER_SLUG);
+
+const buffer: TelemetryEvent[] = [];
+const openSessions = new Set<string>();
+let flushTimer: ReturnType<typeof setInterval> | undefined;
+
+function pushEvent(ev: TelemetryEvent): void {
+  buffer.push(ev);
+  // Bound memory if the ingest is unreachable for a long time: keep the newest.
+  if (buffer.length > MAX_BUFFER) buffer.splice(0, buffer.length - MAX_BUFFER);
+}
+
+function ensureTimer(): void {
+  if (!ENABLED || flushTimer) return;
+  flushTimer = setInterval(() => {
+    void flush();
+  }, HEARTBEAT_MS);
+  // Never keep the process alive just for telemetry.
+  flushTimer.unref?.();
+}
+
+/** Record that a browser session became resident. */
+export function sessionStarted(sessionId: string): void {
+  if (!ENABLED) return;
+  openSessions.add(sessionId);
+  pushEvent({ type: 'session_start', sessionId, ts: Date.now() });
+  ensureTimer();
+}
+
+/** Record that a browser session was torn down (idle | explicit | shutdown). */
+export function sessionEnded(sessionId: string, reason: string): void {
+  if (!ENABLED) return;
+  openSessions.delete(sessionId);
+  pushEvent({ type: 'session_end', sessionId, ts: Date.now(), reason });
+  // Flush promptly so the host can finalize this session's billing.
+  void flush();
+}
+
+async function flush(): Promise<void> {
+  if (!ENABLED) return;
+  const now = Date.now();
+  // Heartbeat every still-open session — proof the browser is still resident.
+  for (const id of openSessions) {
+    pushEvent({ type: 'heartbeat', sessionId: id, ts: now });
+  }
+  if (buffer.length === 0) return;
+  const events = buffer.splice(0, buffer.length);
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), POST_TIMEOUT_MS);
+    try {
+      await fetch(TELEMETRY_URL as string, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${TELEMETRY_TOKEN}`,
+        },
+        body: JSON.stringify({ v: 1, slug: SERVER_SLUG, events }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    // Swallow: telemetry is best-effort and must never affect the server.
+  }
+}
+
+/** Best-effort final flush on shutdown: end every open session and send. */
+export async function flushOnShutdown(reason = 'shutdown'): Promise<void> {
+  if (!ENABLED) return;
+  const now = Date.now();
+  for (const id of [...openSessions]) {
+    openSessions.delete(id);
+    pushEvent({ type: 'session_end', sessionId: id, ts: now, reason });
+  }
+  await flush();
+}

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

@@ -68,7 +68,9 @@ export function getAuthHeaders(
   }
 {{/if}}
 {{#if (eq type "oauth2")}}
-  // OAuth2 — use token management with refresh
+  // 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({
@@ -76,12 +78,14 @@ export function getAuthHeaders(
         clientSecret: config.oauth2ClientSecret,
         authorizationUrl: config.oauth2AuthorizationUrl ?? '',
         tokenUrl: config.oauth2TokenUrl ?? '',
-        scopes: [],
-        redirectUri: config.oauth2RedirectUri ?? 'http://localhost:3000/callback',
+        scopes: config.oauth2Scopes,
+        redirectUri: config.oauth2RedirectUri ?? '',
       });
       headers['Authorization'] = `Bearer ${token}`;
-    } catch {
-      // Fallback to pre-obtained 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}`;
       }

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

@@ -22,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;
@@ -76,6 +79,24 @@ 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(),
@@ -100,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/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,
   };
 }

package/dist/emitter/templates/server-main-http.ts.hbs

@@ -27,6 +27,11 @@ function log(level: 'info' | 'error', msg: string, extra?: Record<string, unknow
   process.stderr.write(JSON.stringify(entry) + '\n');
 }
 
+/* Local/dev escape hatch: when MCP_AUTH_TOKEN is unset, authenticated routes
+ * stay closed (401) UNLESS the operator explicitly sets this to `true`. Matches
+ * the worker server's MCP_ALLOW_UNAUTHENTICATED so both targets behave alike. */
+const ALLOW_UNAUTHENTICATED = process.env.MCP_ALLOW_UNAUTHENTICATED === 'true';
+
 /* ── MCP 2026-07-28 ─────────────────────────────────────────────────────
  * This server is being migrated toward the 2026-07-28 spec revision (RC).
  * Implemented here (additive, works against the current SDK):
@@ -42,11 +47,14 @@ const PROTOCOL_REVISION = '2026-07-28'; // VERIFY against the final spec
 
 /* ── Bearer authentication ──────────────────────────────────────────────
  * Constant-time check that the request presents the expected bearer token via
- * the `Authorization: Bearer <token>` header. Returns true when no token is
- * configured (auth disabled). The token is never accepted from the query
- * string — URLs leak through logs, history, and referrers. */
+ * the `Authorization: Bearer <token>` header. The token is never accepted from
+ * the query string — URLs leak through logs, history, and referrers.
+ *
+ * Fails CLOSED: when MCP_AUTH_TOKEN is unset, every authenticated route is
+ * denied unless the operator explicitly opts in with MCP_ALLOW_UNAUTHENTICATED=
+ * true (a local/dev escape hatch — see ALLOW_UNAUTHENTICATED below). */
 function isAuthorized(req: http.IncomingMessage, expected: string | undefined): boolean {
-  if (!expected) return true; // auth disabled when MCP_AUTH_TOKEN is unset
+  if (!expected) return ALLOW_UNAUTHENTICATED; // fail closed unless explicitly opted in
 
   const header = req.headers.authorization;
   if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
@@ -166,6 +174,22 @@ if (transportMode === 'http') {
   }
   const allowedOrigin = process.env.ALLOWED_ORIGIN;
   const authToken = process.env.MCP_AUTH_TOKEN;
+  /* Fail closed: with no MCP_AUTH_TOKEN the server denies every authenticated
+   * route (401) unless the operator opted in via MCP_ALLOW_UNAUTHENTICATED=true.
+   * Warn loudly, once, when running wide open so it is never a silent default. */
+  if (!authToken) {
+    if (ALLOW_UNAUTHENTICATED) {
+      console.error(
+        'WARNING: MCP_AUTH_TOKEN is not set and MCP_ALLOW_UNAUTHENTICATED=true — ' +
+          'the server is running UNAUTHENTICATED. Do not use this in production.',
+      );
+    } else {
+      console.error(
+        'MCP_AUTH_TOKEN is not set — authenticated routes will return 401. ' +
+          'Set MCP_AUTH_TOKEN, or MCP_ALLOW_UNAUTHENTICATED=true for local/dev only.',
+      );
+    }
+  }
   /* Stateless by default (2026-07-28). MCP_STATEFUL=true keeps Mcp-Session-Id
    * sessions during the migration / for clients that need resumable streams. */
   const stateful = process.env.MCP_STATEFUL === 'true';
@@ -302,9 +326,10 @@ if (transportMode === 'http') {
 
     /* ── Authentication ─────────────────────────────────────────────
      * Every endpoint except /health, /ready{{#if hasOAuth}}, and the public
-     * OAuth metadata{{/if}} requires a valid bearer token when MCP_AUTH_TOKEN
-     * is set. This is the in-container line of defense; the hosting backend
-     * also validates before proxying. */
+     * OAuth metadata{{/if}} requires a valid bearer token. With MCP_AUTH_TOKEN
+     * unset the server fails closed (401) unless MCP_ALLOW_UNAUTHENTICATED=true.
+     * This is the in-container line of defense; the hosting backend also
+     * validates before proxying. */
     const isPublicPath =
       url.pathname === '/health' ||
       url.pathname === '/ready'{{#if hasOAuth}} ||
@@ -353,7 +378,7 @@ if (transportMode === 'http') {
             clientSecret: config.oauth2ClientSecret,
             authorizationUrl,
             tokenUrl,
-            scopes: [],
+            scopes: config.oauth2Scopes,
             redirectUri: config.oauth2RedirectUri ?? '',
           },
           issuer,

package/dist/emitter/templates/task-handlers.ts.hbs

@@ -18,6 +18,15 @@ const VALID_STATUSES = new Set<string>([
   'working', 'input_required', 'completed', 'failed', 'cancelled',
 ]);
 
+const TERMINAL_STATUSES = new Set<string>(['completed', 'failed', 'cancelled']);
+
+/* Trust model: this server is sessionless and authenticates every caller with a
+ * single shared bearer token, so all authorized callers are one principal — there
+ * is no per-user task ownership. Cross-tenant ownership would require sessions and
+ * is out of scope here. Task IDs are unguessable UUIDv4, so with enumeration
+ * disabled a task ID acts as an effective capability; we therefore (a) gate
+ * list-all behind explicit opt-in and (b) refuse to mutate terminal tasks. */
+
 /* ── MCP Tasks extension (2026-07-28) — JSON-RPC over /mcp ────────────────
  * The 2026-07-28 RC moves Tasks to an extension driven by tasks/get,
  * tasks/update, and tasks/cancel; tasks/list is removed (it can't be scoped
@@ -64,6 +73,12 @@ export function handleTaskRpc(
       return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
     }
     case 'tasks/update': {
+      // Refuse to overwrite a finished task: its result/error/status is final.
+      const existing = getTask(taskId);
+      if (!existing) return rpcError(id, -32001, `Task ${taskId} not found`);
+      if (TERMINAL_STATUSES.has(existing.status)) {
+        return rpcError(id, -32002, 'Task is in a terminal state');
+      }
       const status =
         typeof p.status === 'string' && VALID_STATUSES.has(p.status)
           ? (p.status as TaskStatus)
@@ -76,6 +91,11 @@ export function handleTaskRpc(
       return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
     }
     case 'tasks/cancel': {
+      const existing = getTask(taskId);
+      if (!existing) return rpcError(id, -32001, `Task ${taskId} not found`);
+      if (TERMINAL_STATUSES.has(existing.status)) {
+        return rpcError(id, -32002, 'Task is in a terminal state');
+      }
       const task = cancelTask(taskId);
       return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
     }
@@ -98,8 +118,17 @@ export function handleTaskRoutes(
   const method = req.method ?? 'GET';
   const path = url.pathname;
 
-  // GET /tasks — list tasks
+  // GET /tasks — list tasks. Enumerating every task leaks all in-flight work to
+  // any authorized caller and defeats the unguessable-ID capability model, so it
+  // is disabled unless an operator explicitly opts in.
   if (path === '/tasks' && method === 'GET') {
+    if (process.env.MCP_ENABLE_TASK_LIST !== 'true') {
+      sendJson(res, 403, {
+        error: 'Task listing is disabled. Set MCP_ENABLE_TASK_LIST=true to enable it.',
+      });
+      return true;
+    }
+
     const statusParam = url.searchParams.get('status') ?? undefined;
     const limitParam = url.searchParams.get('limit');
     const limit = limitParam ? parseInt(limitParam, 10) : 50;
@@ -171,6 +200,16 @@ export function handleTaskRoutes(
 
   // POST /tasks/:taskId/cancel — cancel a task
   if (subPath === '/cancel' && method === 'POST') {
+    const existing = getTask(taskId);
+    if (!existing) {
+      sendJson(res, 404, { error: `Task ${taskId} not found` });
+      return true;
+    }
+    // A finished task's outcome is final; don't let a late cancel overwrite it.
+    if (TERMINAL_STATUSES.has(existing.status)) {
+      sendJson(res, 409, { error: 'Task is in a terminal state' });
+      return true;
+    }
     const task = cancelTask(taskId);
     if (!task) {
       sendJson(res, 404, { error: `Task ${taskId} not found` });