Context7 Platform -- Up-to-date docs for AI agents
fix(mcp): advertise Clerk as OAuth issuer (#3050)
Fahreddin Özcan7d877a46f2d9
diff --git a/.env.example b/.env.exampleindex fef8ef38..4a1be529 100644--- a/.env.example+++ b/.env.example@@ -4,6 +4,9 @@ CONTEXT7_API_URL=https://context7.com/api# MCP HTTP serverRESOURCE_URL=+OAUTH_AUTH_SERVER_URL=+OAUTH_JWKS_URL=+EMA_ISSUER=AUTH_SERVER_URL=OPENAI_APPS_CHALLENGE_TOKEN=CLIENT_IP_ENCRYPTION_KEY=diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex fc2301da..4f834761 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -19,7 +19,8 @@ import { randomUUID } from "node:crypto";import {SERVER_VERSION,RESOURCE_URL,- AUTH_SERVER_URL,+ OAUTH_AUTH_SERVER_URL,+ EMA_ISSUER,OPENAI_APPS_CHALLENGE_TOKEN,} from "./lib/constants.js";import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js";@@ -473,7 +474,10 @@ async function main() {(_req: express.Request, res: express.Response) => {res.json({resource: RESOURCE_URL,- authorization_servers: [AUTH_SERVER_URL],+ // Each entry is an independent authorization server. Clerk handles+ // regular authorization-code flows; Context7 handles only the+ // enterprise-managed id-jag exchange.+ authorization_servers: Array.from(new Set([OAUTH_AUTH_SERVER_URL, EMA_ISSUER])),scopes_supported: ["profile", "email"],bearer_methods_supported: ["header"],});@@ -483,7 +487,7 @@ async function main() {app.get("/.well-known/oauth-authorization-server",async (_req: express.Request, res: express.Response) => {- const authServerUrl = AUTH_SERVER_URL;+ const authServerUrl = OAUTH_AUTH_SERVER_URL;try {const response = await fetch(`${authServerUrl}/.well-known/oauth-authorization-server`);diff --git a/packages/mcp/src/lib/constants.ts b/packages/mcp/src/lib/constants.tsindex fa99be62..f22cc9c3 100644--- a/packages/mcp/src/lib/constants.ts+++ b/packages/mcp/src/lib/constants.ts@@ -9,14 +9,27 @@ export const SERVER_VERSION: string = pkg.version;const CONTEXT7_BASE_URL = "https://context7.com";const MCP_RESOURCE_URL = "https://mcp.context7.com";+const DEFAULT_OAUTH_AUTH_SERVER_URL = "https://clerk.context7.com";-export const CLERK_DOMAIN = "clerk.context7.com";export const CONTEXT7_API_BASE_URL = process.env.CONTEXT7_API_URL || `${CONTEXT7_BASE_URL}/api`;export const RESOURCE_URL = process.env.RESOURCE_URL || MCP_RESOURCE_URL;-export const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL || CONTEXT7_BASE_URL;++// Clerk owns the interactive OAuth flow and is the issuer returned in the+// authorization response. Advertising Clerk directly keeps RFC 8414 discovery+// and RFC 9207 response-issuer validation on the same authorization-server+// identity.+export const OAUTH_AUTH_SERVER_URL = (+ process.env.OAUTH_AUTH_SERVER_URL || DEFAULT_OAUTH_AUTH_SERVER_URL+).replace(/\/+$/, "");+export const OAUTH_JWKS_URL =+ process.env.OAUTH_JWKS_URL || `${OAUTH_AUTH_SERVER_URL}/.well-known/jwks.json`;// Enterprise-Managed Auth (id-jag): access tokens minted by the Context7// authorization server, validated against its public JWKS.-export const EMA_ISSUER = AUTH_SERVER_URL;+// AUTH_SERVER_URL remains a backwards-compatible alias for local EMA setups;+// it does not move interactive user OAuth. Local end-to-end OAuth environments+// must set OAUTH_AUTH_SERVER_URL separately when Clerk is not the intended issuer.+export const EMA_ISSUER =+ process.env.EMA_ISSUER || process.env.AUTH_SERVER_URL || CONTEXT7_BASE_URL;export const EMA_JWKS_URL = process.env.EMA_JWKS_URL || `${CONTEXT7_API_BASE_URL}/oauth/ema-jwks`;export const OPENAI_APPS_CHALLENGE_TOKEN = process.env.OPENAI_APPS_CHALLENGE_TOKEN;diff --git a/packages/mcp/src/lib/jwt.ts b/packages/mcp/src/lib/jwt.tsindex a1bce84c..6c461c4c 100644--- a/packages/mcp/src/lib/jwt.ts+++ b/packages/mcp/src/lib/jwt.ts@@ -1,14 +1,14 @@import * as jose from "jose";import {- CLERK_DOMAIN,CONTEXT7_API_BASE_URL,EMA_ISSUER,EMA_JWKS_URL,+ OAUTH_AUTH_SERVER_URL,+ OAUTH_JWKS_URL,RESOURCE_URL,} from "./constants.js";-const CLERK_ISSUER = `https://${CLERK_DOMAIN}`;-const clerkJwks = jose.createRemoteJWKSet(new URL(`https://${CLERK_DOMAIN}/.well-known/jwks.json`));+const oauthJwks = jose.createRemoteJWKSet(new URL(OAUTH_JWKS_URL));const emaJwks = jose.createRemoteJWKSet(new URL(EMA_JWKS_URL));@@ -103,7 +103,7 @@ export async function validateJWT(token: string): Promise<JWTValidationResult> {return { valid: true };}- await jose.jwtVerify(token, clerkJwks, { issuer: CLERK_ISSUER });+ await jose.jwtVerify(token, oauthJwks, { issuer: OAUTH_AUTH_SERVER_URL });return { valid: true };} catch (error) {if (error instanceof jose.errors.JWTExpired) {diff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex 0c9d6840..06d2a9cc 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -122,6 +122,19 @@ async function connect(transportKind: "http" | "stdio", era: "modern" | "legacy"return client;}+describe("OAuth discovery", () => {+ test("advertises Clerk for user OAuth and Context7 for enterprise auth", async () => {+ const metadataUrl = new URL("/.well-known/oauth-protected-resource", httpUrl);+ const response = await fetch(metadataUrl);++ expect(response.status).toBe(200);+ expect(await response.json()).toMatchObject({+ resource: "https://mcp.context7.com",+ authorization_servers: ["https://clerk.context7.com", "https://context7.com"],+ });+ });+});+describe.each([["http", "modern"],["http", "legacy"],diff --git a/packages/mcp/test/jwt.test.ts b/packages/mcp/test/jwt.test.tsindex 4abd8cc0..d03183b6 100644--- a/packages/mcp/test/jwt.test.ts+++ b/packages/mcp/test/jwt.test.ts@@ -15,6 +15,8 @@ vi.mock("jose", async () => {const TENANT_ID = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa";const ENTRA_ISSUER = `https://login.microsoftonline.com/${TENANT_ID}/v2.0`;const AUDIENCE = "6ff6a635-03d9-472d-a7f1-dc98a4e5fde2";+const originalOAuthAuthServerUrl = process.env.OAUTH_AUTH_SERVER_URL;+const originalOAuthJwksUrl = process.env.OAUTH_JWKS_URL;async function loadModule() {vi.resetModules();@@ -42,6 +44,16 @@ beforeEach(() => {});afterEach(() => {+ if (originalOAuthAuthServerUrl === undefined) {+ delete process.env.OAUTH_AUTH_SERVER_URL;+ } else {+ process.env.OAUTH_AUTH_SERVER_URL = originalOAuthAuthServerUrl;+ }+ if (originalOAuthJwksUrl === undefined) {+ delete process.env.OAUTH_JWKS_URL;+ } else {+ process.env.OAUTH_JWKS_URL = originalOAuthJwksUrl;+ }vi.unstubAllGlobals();vi.clearAllMocks();});@@ -190,4 +202,36 @@ describe("validateJWT - Clerk path", () => {expect(result.valid).toBe(false);expect(result.error).toBe("Token expired");});++ test("uses the configured OAuth issuer and its JWKS for verification", async () => {+ process.env.OAUTH_AUTH_SERVER_URL = "https://supreme-foal-19.clerk.accounts.dev/";+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: {},+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const result = await validateJWT(+ makeEntraToken({ iss: "https://supreme-foal-19.clerk.accounts.dev" })+ );++ expect(result.valid).toBe(true);+ expect(jose.createRemoteJWKSet).toHaveBeenCalledWith(+ new URL("https://supreme-foal-19.clerk.accounts.dev/.well-known/jwks.json")+ );+ expect(jose.jwtVerify).toHaveBeenCalledWith(expect.any(String), "fake-jwks", {+ issuer: "https://supreme-foal-19.clerk.accounts.dev",+ });+ });++ test("allows an explicit JWKS URL without changing the OAuth issuer", async () => {+ process.env.OAUTH_AUTH_SERVER_URL = "https://oauth.example.com";+ process.env.OAUTH_JWKS_URL = "https://keys.example.com/oauth/jwks.json";++ await loadModule();++ expect(jose.createRemoteJWKSet).toHaveBeenCalledWith(+ new URL("https://keys.example.com/oauth/jwks.json")+ );+ });});