feat: require tokens for hosted MCP access

Author: GarethManning

.gitignore

@@ -3,3 +3,4 @@ node_modules/
 test-results/
 playwright-report/
 skills/curriculum-assessment/threshold-concept-kud-translator/
+.vercel

mcp-server/api/mcp.ts

@@ -1,5 +1,6 @@
 import { createServer } from "../src/server.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { getAuthorizedTokenPrefix, getUnauthorizedResponse } from "../src/http-auth.js";
 import type { LoadedSkill } from "../src/types.js";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
@@ -17,15 +18,32 @@ export default async function handler(
   // CORS headers for cross-origin MCP clients
   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id, mcp-protocol-version");
-  res.setHeader("Access-Control-Expose-Headers", "mcp-session-id");
+  res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, mcp-session-id, mcp-protocol-version");
+  res.setHeader("Access-Control-Expose-Headers", "mcp-session-id, WWW-Authenticate");
 
   if (req.method === "OPTIONS") {
     res.writeHead(204);
     res.end();
     return;
   }
 
+  const tokenPrefix = getAuthorizedTokenPrefix({
+    url: req.url,
+    authorization: req.headers.authorization,
+  });
+
+  if (!tokenPrefix) {
+    const unauthorized = getUnauthorizedResponse(req.url ?? "/mcp", req.method);
+    for (const [key, value] of Object.entries(unauthorized.headers)) {
+      res.setHeader(key, value);
+    }
+    res.writeHead(unauthorized.status);
+    res.end(unauthorized.body);
+    return;
+  }
+
+  res.setHeader("X-MCP-Access", "token");
+
   const server = createServer(skills);
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined, // stateless

mcp-server/package-lock.json

@@ -0,0 +1,113 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+export type AuthEnv = Record<string, string | undefined>;
+
+export type AuthCheckInput = {
+  url?: string;
+  authorization?: string | string[];
+  env?: AuthEnv;
+};
+
+export type HttpAuthResponse = {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+};
+
+const TOKEN_PREFIX_LENGTH = 18;
+
+export function hasConfiguredAuth(env: AuthEnv = process.env): boolean {
+  return Boolean(
+    env.MCP_TOKEN_SIGNING_SECRET?.trim() ||
+      env.MCP_ACCESS_TOKEN_HASHES?.trim() ||
+      env.MCP_ACCESS_TOKENS?.trim(),
+  );
+}
+
+export function getUnauthorizedResponse(originUrl: string, method = "POST"): HttpAuthResponse {
+  const isGet = method.toUpperCase() === "GET";
+  return {
+    status: 401,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "www-authenticate": `Bearer realm="education-agent-skills", error="invalid_token", error_description="Hosted MCP access token required"`,
+      "x-mcp-auth": isGet ? "required-fast-fail" : "required",
+    },
+    body: JSON.stringify({
+      error: "Hosted MCP access token required",
+      message:
+        "This hosted MCP endpoint now requires an access token. Request one via the hosted access form, or use the free local/plugin installation options.",
+      requestAccess: "https://docs.google.com/forms/d/e/1FAIpQLSdW1EdcmtjSPPq68Hx-bdth5hO2KNyjhAwEV9Ld0EwWL1Gr8Q/viewform",
+      resource: originUrl,
+    }),
+  };
+}
+
+export function getAuthorizedTokenPrefix(input: AuthCheckInput): string | null {
+  const env = input.env ?? process.env;
+  const token = extractToken(input.url, input.authorization);
+  if (!token || !hasConfiguredAuth(env)) return null;
+  if (isSignedTokenValid(token, env.MCP_TOKEN_SIGNING_SECRET)) {
+    return token.slice(0, TOKEN_PREFIX_LENGTH);
+  }
+  if (isHashTokenValid(token, env.MCP_ACCESS_TOKEN_HASHES)) {
+    return token.slice(0, TOKEN_PREFIX_LENGTH);
+  }
+  if (isPlainTokenValid(token, env.MCP_ACCESS_TOKENS)) {
+    return token.slice(0, TOKEN_PREFIX_LENGTH);
+  }
+  return null;
+}
+
+export function extractToken(url?: string, authorization?: string | string[]): string | null {
+  const header = Array.isArray(authorization) ? authorization[0] : authorization;
+  const bearer = header?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim();
+  if (bearer) return bearer;
+  if (!url) return null;
+  try {
+    const parsed = new URL(url, "https://example.invalid");
+    return parsed.searchParams.get("token")?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function isSignedTokenValid(token: string, secret?: string): boolean {
+  const cleanSecret = secret?.trim();
+  if (!cleanSecret) return false;
+  const dot = token.lastIndexOf(".");
+  if (dot < 1) return false;
+  const payload = token.slice(0, dot);
+  const signature = token.slice(dot + 1);
+  if (!payload.startsWith("eas_live_") || !signature) return false;
+  const expected = createHmac("sha256", cleanSecret).update(payload).digest("base64url");
+  return safeEqual(signature, expected);
+}
+
+function isHashTokenValid(token: string, hashes?: string): boolean {
+  const allowed = splitList(hashes);
+  if (allowed.length === 0) return false;
+  const digest = createHash("sha256").update(token).digest("hex");
+  return allowed.some((hash) => safeEqual(digest, hash));
+}
+
+function isPlainTokenValid(token: string, tokens?: string): boolean {
+  const allowed = splitList(tokens);
+  if (allowed.length === 0) return false;
+  return allowed.some((allowedToken) => safeEqual(token, allowedToken));
+}
+
+function splitList(raw?: string): string[] {
+  return (raw ?? "")
+    .split(/[\n,]/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const aBuffer = Buffer.from(a);
+  const bBuffer = Buffer.from(b);
+  if (aBuffer.length !== bBuffer.length) return false;
+  return timingSafeEqual(aBuffer, bBuffer);
+}

mcp-server/src/http-auth.ts

@@ -0,0 +1,74 @@
+import { test, expect } from "@playwright/test";
+import { createHmac, createHash } from "node:crypto";
+import {
+  getAuthorizedTokenPrefix,
+  getUnauthorizedResponse,
+  hasConfiguredAuth,
+} from "../src/http-auth.js";
+
+function signedToken(secret: string, nonce = "test-nonce") {
+  const payload = `eas_live_${nonce}`;
+  const signature = createHmac("sha256", secret).update(payload).digest("base64url");
+  return `${payload}.${signature}`;
+}
+
+test.describe("HTTP MCP auth", () => {
+  test("fast-fails anonymous requests before the MCP transport can open SSE", () => {
+    const response = getUnauthorizedResponse("https://example.com/mcp", "GET");
+
+    expect(response.status).toBe(401);
+    expect(response.headers["www-authenticate"]).toContain("Bearer");
+    expect(response.headers["content-type"]).toContain("application/json");
+    expect(response.body).toContain("Hosted MCP access token required");
+  });
+
+  test("accepts a signed bearer token generated from the shared signing secret", () => {
+    const token = signedToken("test-secret");
+    const prefix = getAuthorizedTokenPrefix({
+      url: "https://example.com/mcp",
+      authorization: `Bearer ${token}`,
+      env: { MCP_TOKEN_SIGNING_SECRET: "test-secret" },
+    });
+
+    expect(prefix).toBe("eas_live_test-nonc");
+  });
+
+  test("accepts a token query parameter for clients that cannot set auth headers", () => {
+    const token = signedToken("test-secret", "query-token");
+    const prefix = getAuthorizedTokenPrefix({
+      url: `https://example.com/mcp?token=${encodeURIComponent(token)}`,
+      authorization: undefined,
+      env: { MCP_TOKEN_SIGNING_SECRET: "test-secret" },
+    });
+
+    expect(prefix).toBe("eas_live_query-tok");
+  });
+
+  test("rejects invalid signed tokens", () => {
+    const token = signedToken("wrong-secret");
+    const prefix = getAuthorizedTokenPrefix({
+      url: "https://example.com/mcp",
+      authorization: `Bearer ${token}`,
+      env: { MCP_TOKEN_SIGNING_SECRET: "test-secret" },
+    });
+
+    expect(prefix).toBeNull();
+  });
+
+  test("accepts pre-hashed tokens for emergency/manual issuance", () => {
+    const token = "eas_live_manual_token";
+    const hash = createHash("sha256").update(token).digest("hex");
+    const prefix = getAuthorizedTokenPrefix({
+      url: "https://example.com/mcp",
+      authorization: `Bearer ${token}`,
+      env: { MCP_ACCESS_TOKEN_HASHES: hash },
+    });
+
+    expect(prefix).toBe("eas_live_manual_to");
+  });
+
+  test("requires at least one configured auth source", () => {
+    expect(hasConfiguredAuth({})).toBe(false);
+    expect(hasConfiguredAuth({ MCP_TOKEN_SIGNING_SECRET: "test-secret" })).toBe(true);
+  });
+});