From f304caea00a7d076548c726988d456da4d0d1ae3 Mon Sep 17 00:00:00 2001 From: Yiling-J Date: Thu, 5 Nov 2026 22:21:11 +0800 Subject: [PATCH] fix(auth,web): gracefully degrade MCP on remote HTTP and cache production static assets (#519) * fix: gracefully handle remote HTTP URLs for MCP and cache production static assets * test(mcp): add remote http mcp integration test and fix static etag normalization and fallback error --- CHANGELOG.md | 2 + README.md | 2 +- README_CN.md | 2 +- apps/web/src/index.ts | 35 ++-- apps/web/src/static.test.ts | 175 ++++++++++++++++++ apps/web/src/static.ts | 106 +++++++++++ docs/getting-started/quickstart.mdx | 2 +- .../api/src/mcp-server.remote-http.test.ts | 100 ++++++++++ packages/api/src/mcp-server.test.ts | 20 +- packages/api/src/mcp-server.ts | 88 +++++---- packages/core/src/auth/auth.test.ts | 47 ++++- packages/core/src/auth/auth.ts | 79 +++++++- 12 files changed, 596 insertions(+), 62 deletions(-) create mode 100644 apps/web/src/static.test.ts create mode 100644 apps/web/src/static.ts create mode 100644 packages/api/src/mcp-server.remote-http.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bb934da..9951402a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Fixed - **security**: ⚠️ Several security improvements and access control hardenings. Upgrading to this release is strongly recommended. +- **mcp**: Gracefully disable MCP OAuth 2.1 with an error log when deploying on remote HTTP IP addresses without breaking the main server or API token MCP access +- **web**: Add immutable cache headers and conditional 304 Not Modified support for production JavaScript and CSS chunks to prevent unnecessary refetches on page reload ### Changed diff --git a/README.md b/README.md index c835f303..f69ac925 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon > By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](https://docs.shumai.one/configuration/hardware-transcoding). 3. Configure environment variables: - * `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. + * `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. Note: Remote deployments must use HTTPS for MCP OAuth 2.1; if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional. * `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files. For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set: diff --git a/README_CN.md b/README_CN.md index 39da1f36..6820e79a 100644 --- a/README_CN.md +++ b/README_CN.md @@ -127,7 +127,7 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA 3. 配置环境变量: - * `BETTER_AUTH_URL`:Shumai 服务的外部公开访问地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。在远程服务器或生产环境中部署时必须配置该变量。 + * `BETTER_AUTH_URL`:Shumai 服务的外部公开访问地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。在远程服务器或生产环境中部署时必须配置该变量。注意:MCP OAuth 2.1 依赖 HTTPS(本地 loopback 除外);若远程部署使用 HTTP,系统会优雅禁用 MCP OAuth 2.1 并记录日志,Web UI 与基于 API Token 的 MCP 访问不受影响。 * `AWS_ENDPOINT_URL_S3`:默认情况下指向 `http://localhost:{SHUMAI_SERVER_PORT}`。当你使用本地存储(即默认配置 `STORAGE_BACKEND: local`)并在远程服务器、自定义域名或自定义端口上公开访问 Shumai 时,请将 `AWS_ENDPOINT_URL_S3` 设置为客户端浏览器上传和下载文件所使用的外部 URL。 例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置: diff --git a/apps/web/src/index.ts b/apps/web/src/index.ts index c2ec12e4..c43e36d4 100644 --- a/apps/web/src/index.ts +++ b/apps/web/src/index.ts @@ -21,6 +21,7 @@ import { embeddingService } from '@shumai/core/src/search/embedding-service' import { sandboxService } from '@shumai/core' import { notificationJobService } from '@shumai/core/src/notification/notification-job' import { autoArchiveJobService } from '@shumai/core/src/asset/auto-archive-job' +import { createHtmlHandler, createStaticFileHandler } from './static' if (process.argv.includes('--check')) { console.log('✅ Web app evaluated successfully!') @@ -151,7 +152,8 @@ async function run() { for (const file of bundle.files) { const routePath = file.path.startsWith('.') ? file.path.slice(1) : file.path const filePath = join(import.meta.dir, file.path) - routes[routePath] = () => new Response(Bun.file(filePath), { headers: file.headers }) + const isHtml = file.loader === 'html' || file.path.endsWith('.html') + routes[routePath] = createStaticFileHandler(filePath, file.headers, !isHtml) } const sampleFile = bundle.files[0]?.path || bundle.index || '' @@ -163,13 +165,14 @@ async function run() { const routePath = '/' + pdfWorkerFile const filePath = join(bundleDir, pdfWorkerFile) const bunFile = Bun.file(filePath) - routes[routePath] = () => - new Response(bunFile, { - headers: { - 'content-type': 'text/javascript;charset=utf-8', - etag: `"${bunFile.size}-${bunFile.lastModified}"`, - }, - }) + routes[routePath] = createStaticFileHandler( + filePath, + { + 'content-type': 'text/javascript;charset=utf-8', + etag: `"${bunFile.size}-${bunFile.lastModified}"`, + }, + true, + ) } } catch (err) { console.warn('Failed to register pdf.worker route:', err) @@ -185,16 +188,22 @@ async function run() { .replaceAll('href="./', 'href="/') .replaceAll('src="./', 'src="/') .replaceAll('content="./', 'content="/') - const serveMainHtml = () => new Response(mainHtmlText, { headers: mainHtmlHeaders }) + const serveMainHtml = createHtmlHandler(mainHtmlText, mainHtmlHeaders) routes['/'] = serveMainHtml routes['/*'] = serveMainHtml } else { const fallbackHtmlPath = join(import.meta.dir, 'shumai-app.html') - const serveFallbackHtml = () => - new Response(Bun.file(fallbackHtmlPath), { - headers: { 'content-type': 'text/html;charset=utf-8' }, - }) + const fallbackHtmlFile = Bun.file(fallbackHtmlPath) + if (!(await fallbackHtmlFile.exists())) { + throw new Error( + `Production HTML bundle is missing: neither bundle.files nor ${fallbackHtmlPath} exists.`, + ) + } + const fallbackRaw = await fallbackHtmlFile.text() + const serveFallbackHtml = createHtmlHandler(fallbackRaw, { + 'content-type': 'text/html;charset=utf-8', + }) routes['/'] = serveFallbackHtml routes['/*'] = serveFallbackHtml } diff --git a/apps/web/src/static.test.ts b/apps/web/src/static.test.ts new file mode 100644 index 00000000..0376db62 --- /dev/null +++ b/apps/web/src/static.test.ts @@ -0,0 +1,175 @@ +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { writeFileSync, unlinkSync } from 'node:fs' +import { join } from 'node:path' +import { tmpdir } from 'node:os' +import { createHtmlHandler, createStaticFileHandler, isEtagMatching, normalizeEtag } from './static' + +describe('Static Asset Serving & Caching', () => { + const tempChunkPath = join(tmpdir(), `test-chunk-${Date.now()}.js`) + const chunkContent = 'console.log("chunk loaded");' + + beforeAll(() => { + writeFileSync(tempChunkPath, chunkContent, 'utf8') + }) + + afterAll(() => { + try { + unlinkSync(tempChunkPath) + } catch { + // Ignore cleanup error if already deleted + } + }) + + describe('normalizeEtag', () => { + it('quotes unquoted ETags according to RFC 9110', () => { + expect(normalizeEtag('hHRmXFeFVSk')).toBe('"hHRmXFeFVSk"') + expect(normalizeEtag('ACJrxcts9Iw')).toBe('"ACJrxcts9Iw"') + }) + + it('preserves already-quoted strong and weak ETags', () => { + expect(normalizeEtag('"hHRmXFeFVSk"')).toBe('"hHRmXFeFVSk"') + expect(normalizeEtag('W/"hHRmXFeFVSk"')).toBe('W/"hHRmXFeFVSk"') + }) + + it('returns undefined for empty or missing ETags', () => { + expect(normalizeEtag(undefined)).toBeUndefined() + expect(normalizeEtag('')).toBeUndefined() + expect(normalizeEtag(' ')).toBeUndefined() + }) + }) + + describe('isEtagMatching', () => { + it('matches exact etag string', () => { + expect(isEtagMatching('"12345"', '"12345"')).toBe(true) + }) + + it('matches weak etag to strong or weak candidates', () => { + expect(isEtagMatching('W/"12345"', '"12345"')).toBe(true) + expect(isEtagMatching('"12345"', 'W/"12345"')).toBe(true) + expect(isEtagMatching('W/"12345"', 'W/"12345"')).toBe(true) + }) + + it('matches wildcard *', () => { + expect(isEtagMatching('"12345"', '*')).toBe(true) + }) + + it('matches comma-separated candidate lists', () => { + expect(isEtagMatching('"12345"', '"old-etag", "12345", "other"')).toBe(true) + expect(isEtagMatching('"12345"', '"old-etag", "mismatch"')).toBe(false) + }) + + it('returns false when etag or ifNoneMatch is missing or empty', () => { + expect(isEtagMatching(undefined, '"12345"')).toBe(false) + expect(isEtagMatching('"12345"', null)).toBe(false) + expect(isEtagMatching('', '"12345"')).toBe(false) + expect(isEtagMatching('"12345"', '')).toBe(false) + }) + }) + + describe('createStaticFileHandler', () => { + it('sets immutable Cache-Control for immutable content-hashed assets', async () => { + const handler = createStaticFileHandler( + tempChunkPath, + { 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' }, + true, + ) + + const req = new Request('http://localhost/chunk-123.js') + const res = handler(req) + + expect(res.status).toBe(200) + expect(res.headers.get('content-type')).toBe('text/javascript;charset=utf-8') + expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable') + expect(res.headers.get('etag')).toBe('"chunk-hash-1"') + expect(await res.text()).toBe(chunkContent) + }) + + it('returns 304 Not Modified when If-None-Match matches the file etag', async () => { + const handler = createStaticFileHandler( + tempChunkPath, + { 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' }, + true, + ) + + const req = new Request('http://localhost/chunk-123.js', { + headers: { 'if-none-match': '"chunk-hash-1"' }, + }) + const res = handler(req) + + expect(res.status).toBe(304) + expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable') + expect(res.headers.get('etag')).toBe('"chunk-hash-1"') + expect(await res.text()).toBe('') + }) + + it('sets no-cache Cache-Control for non-immutable static assets', async () => { + const handler = createStaticFileHandler( + tempChunkPath, + { 'content-type': 'text/plain', etag: '"plain-1"' }, + false, + ) + + const req = new Request('http://localhost/robots.txt') + const res = handler(req) + + expect(res.status).toBe(200) + expect(res.headers.get('cache-control')).toBe('no-cache') + }) + + it('normalizes unquoted manifest ETags to quoted RFC 9110 strings', async () => { + const handler = createStaticFileHandler( + tempChunkPath, + { 'content-type': 'text/javascript;charset=utf-8', etag: 'hHRmXFeFVSk' }, + true, + ) + + const req = new Request('http://localhost/chunk-123.js') + const res = handler(req) + + expect(res.status).toBe(200) + expect(res.headers.get('etag')).toBe('"hHRmXFeFVSk"') + + const revalidateRes = handler( + new Request('http://localhost/chunk-123.js', { + headers: { 'if-none-match': '"hHRmXFeFVSk"' }, + }), + ) + expect(revalidateRes.status).toBe(304) + expect(revalidateRes.headers.get('etag')).toBe('"hHRmXFeFVSk"') + }) + }) + + describe('createHtmlHandler', () => { + const htmlText = 'Shumai' + + it('sets no-cache and generates deterministic ETag for HTML', async () => { + const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' }) + + const req = new Request('http://localhost/') + const res = handler(req) + + expect(res.status).toBe(200) + expect(res.headers.get('content-type')).toBe('text/html;charset=utf-8') + expect(res.headers.get('cache-control')).toBe('no-cache') + const etag = res.headers.get('etag') + expect(etag).toBeTruthy() + expect(await res.text()).toBe(htmlText) + }) + + it('returns 304 Not Modified when HTML If-None-Match matches', async () => { + const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' }) + + const initialRes = handler(new Request('http://localhost/')) + const etag = initialRes.headers.get('etag')! + + const revalidateReq = new Request('http://localhost/', { + headers: { 'if-none-match': etag }, + }) + const revalidateRes = handler(revalidateReq) + + expect(revalidateRes.status).toBe(304) + expect(revalidateRes.headers.get('cache-control')).toBe('no-cache') + expect(await revalidateRes.text()).toBe('') + }) + }) +}) diff --git a/apps/web/src/static.ts b/apps/web/src/static.ts new file mode 100644 index 00000000..abddbb0f --- /dev/null +++ b/apps/web/src/static.ts @@ -0,0 +1,106 @@ +/** + * Helpers for serving static production assets with caching headers and ETag revalidation. + */ + +/** + * Checks whether an incoming `If-None-Match` header matches the asset's ETag. + * Supports weak ETags (`W/"..."`), exact matches, and comma-separated lists. + */ +export function isEtagMatching(etag: string | undefined, ifNoneMatch: string | null): boolean { + if (!etag || !ifNoneMatch) { + return false + } + + const cleanTarget = etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '') + if (!cleanTarget) { + return false + } + + const candidates = ifNoneMatch + .split(',') + .map((candidate) => candidate.trim().replace(/^W\//, '').replace(/^"|"$/g, '')) + + return candidates.includes(cleanTarget) || candidates.includes('*') +} + +/** + * Normalizes an ETag to ensure it is enclosed in quotes according to RFC 9110. + * Preserves weak validators (`W/"..."`). + */ +export function normalizeEtag(etag: string | undefined): string | undefined { + if (!etag) { + return undefined + } + const trimmed = etag.trim() + if (!trimmed) { + return undefined + } + if (trimmed.startsWith('W/"') && trimmed.endsWith('"')) { + return trimmed + } + if (trimmed.startsWith('"') && trimmed.endsWith('"')) { + return trimmed + } + return `"${trimmed.replace(/^"|"$/g, '')}"` +} + +/** + * Creates a route handler for a static file on disk. + * Content-hashed assets (e.g. `chunk-*.js`, `chunk-*.css`) should be marked `isImmutable: true` + * to be aggressively cached locally by browsers across page reloads. + */ +export function createStaticFileHandler( + filePath: string, + baseHeaders: Record, + isImmutable: boolean, +): (req: Request) => Response { + const bunFile = Bun.file(filePath) + const rawEtag = baseHeaders.etag || baseHeaders.ETag + const normalizedEtag = normalizeEtag(rawEtag) + const headers: Record = { + ...baseHeaders, + ...(normalizedEtag ? { etag: normalizedEtag } : {}), + 'cache-control': isImmutable ? 'public, max-age=31536000, immutable' : 'no-cache', + } + const etag = headers.etag + + return (req: Request): Response => { + const ifNoneMatch = req.headers.get('if-none-match') + if (etag && isEtagMatching(etag, ifNoneMatch)) { + return new Response(null, { + status: 304, + headers, + }) + } + return new Response(bunFile, { headers }) + } +} + +/** + * Creates a route handler for in-memory transformed HTML entry points. + * Sets `cache-control: no-cache` with a deterministic ETag, allowing browsers to cache locally + * while always revalidating to ensure new chunk hashes are picked up immediately after deployment. + */ +export function createHtmlHandler( + htmlText: string, + baseHeaders: Record, +): (req: Request) => Response { + const rawEtag = baseHeaders.etag || baseHeaders.ETag + const etag = normalizeEtag(rawEtag) || `"${Bun.hash(htmlText).toString(16)}"` + const headers: Record = { + ...baseHeaders, + etag, + 'cache-control': 'no-cache', + } + + return (req: Request): Response => { + const ifNoneMatch = req.headers.get('if-none-match') + if (isEtagMatching(etag, ifNoneMatch)) { + return new Response(null, { + status: 304, + headers, + }) + } + return new Response(htmlText, { headers }) + } +} diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index fdb4033a..4cecdfd3 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -44,7 +44,7 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon 3. **Configure Environment Variables**: Open `docker-compose.yaml` to adjust environment variables for your deployment: - - `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. + - `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. Note: Remote deployments must use HTTPS for MCP OAuth 2.1; if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional. - `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files. For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set: diff --git a/packages/api/src/mcp-server.remote-http.test.ts b/packages/api/src/mcp-server.remote-http.test.ts new file mode 100644 index 00000000..d0beab97 --- /dev/null +++ b/packages/api/src/mcp-server.remote-http.test.ts @@ -0,0 +1,100 @@ +import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest' +import { Hono } from 'hono' +import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client' +import { prisma, type User } from '@shumai/db' +import { setupTestDbHooks } from '@shumai/db/test' +import { apiTokenService } from '@shumai/core/src/user/api-token' +import { projectService } from '@shumai/core/src/project/project' + +describe('MCP server on remote HTTP BETTER_AUTH_URL', () => { + setupTestDbHooks() + + const originalEnv = process.env.BETTER_AUTH_URL + let user: User + let token: string + // eslint-disable-next-line @typescript-eslint/no-explicit-any + let app: Hono + let isMcpOauthEnabled: boolean + + beforeAll(async () => { + process.env.BETTER_AUTH_URL = 'http://43.133.100.178:3000' + vi.resetModules() + + const authModule = await import('@shumai/core/src/auth/auth') + isMcpOauthEnabled = authModule.isMcpOauthEnabled + const mcpServerModule = await import('./mcp-server') + + app = new Hono().route('/', mcpServerModule.default) + + user = await prisma.user.create({ + data: { name: 'Remote HTTP User', email: `remote-http-${Date.now()}@test.com` }, + }) + const team = await prisma.team.create({ data: { name: 'Remote HTTP Team' } }) + await prisma.teamMember.create({ data: { teamId: team.id, userId: user.id, role: 'owner' } }) + await projectService.createProject(user, { teamId: team.id, name: 'Remote HTTP Project' }) + + const tokenRes = await apiTokenService.createToken(user.id, 'remote-http-test') + token = tokenRes.token + }) + + afterAll(() => { + if (originalEnv !== undefined) { + process.env.BETTER_AUTH_URL = originalEnv + } else { + delete process.env.BETTER_AUTH_URL + } + vi.resetModules() + }) + + it('omits MCP OAuth plugin and disables isMcpOauthEnabled', () => { + expect(isMcpOauthEnabled).toBe(false) + }) + + it('returns 503 Service Unavailable for unauthenticated requests to /mcp', async () => { + const res = await app.request('/mcp', { method: 'POST' }) + expect(res.status).toBe(503) + const body = await res.json() + expect(body).toMatchObject({ + jsonrpc: '2.0', + error: { + code: -32000, + message: expect.stringContaining( + 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS', + ), + }, + id: null, + }) + }) + + it('allows valid API tokens to access /mcp and execute tools even when OAuth is disabled', async () => { + const transport = new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), { + fetch: async (input, init) => { + const headers = new Headers(init?.headers) + headers.set('Authorization', `Bearer ${token}`) + return app.request(String(input), { + ...init, + headers, + }) + }, + }) + const client = new Client({ name: 'remote-http-client', version: '1.0.0' }) + await client.connect(transport) + + expect(client.getServerVersion()).toMatchObject({ name: 'shumai' }) + const { tools } = await client.listTools() + expect(tools.length).toBeGreaterThan(0) + expect(tools.map((t) => t.name)).toContain('list_projects') + + await client.close() + }) + + it('rejects invalid API tokens with 401 Unauthorized', async () => { + const res = await app.request('/mcp', { + method: 'POST', + headers: { + Authorization: 'Bearer shumai_invalidtoken1234567890', + }, + }) + expect(res.status).toBe(401) + }) +}) diff --git a/packages/api/src/mcp-server.test.ts b/packages/api/src/mcp-server.test.ts index b82c9126..f53f0432 100644 --- a/packages/api/src/mcp-server.test.ts +++ b/packages/api/src/mcp-server.test.ts @@ -6,7 +6,7 @@ import { teamService } from '@shumai/core/src/team/team' import { s3Service } from '@shumai/core/src/s3/s3' import { createFolderOp, readAssetOp, runOperation } from '@shumai/core/src/operations' import { MAX_INLINE_IMAGE_BYTES, MAX_INLINE_IMAGES } from './mcp-extensions/read-asset' -import mcpServerRoute, { MCP_SERVER_INSTRUCTIONS } from './mcp-server' +import mcpServerRoute, { disabledOauthHandler, MCP_SERVER_INSTRUCTIONS } from './mcp-server' vi.mock('@shumai/core/src/operations', async (importOriginal) => ({ ...(await importOriginal()), @@ -402,4 +402,22 @@ describe('MCP server', () => { ]) }) }) + + describe('Disabled OAuth Fallback', () => { + it('returns 503 Service Unavailable with standard JSON-RPC error payload', async () => { + const res = await disabledOauthHandler() + expect(res.status).toBe(503) + expect(res.headers.get('content-type')).toContain('application/json') + const body = await res.json() + expect(body).toEqual({ + jsonrpc: '2.0', + error: { + code: -32000, + message: + 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS or a loopback address. Please configure HTTPS or authenticate with a Shumai API token.', + }, + id: null, + }) + }) + }) }) diff --git a/packages/api/src/mcp-server.ts b/packages/api/src/mcp-server.ts index 9e791e69..ad9ff3d8 100644 --- a/packages/api/src/mcp-server.ts +++ b/packages/api/src/mcp-server.ts @@ -5,7 +5,7 @@ import type { z } from 'zod' import type { Prisma } from '@shumai/db' import { dropNullOptionals } from '@shumai/operations' import { getOperationsForSurface, runOperation, type Operation } from '@shumai/core/src/operations' -import { auth, authBaseUrl, mcpResource } from '@shumai/core/src/auth/auth' +import { auth, authBaseUrl, isMcpOauthEnabled, mcpResource } from '@shumai/core/src/auth/auth' import { apiTokenService } from '@shumai/core/src/user/api-token' import { mcpExtensions, type McpToolExtension } from './mcp-extensions' import { assertWritableInDemoMode, describeOperationError } from './operation-support' @@ -134,40 +134,60 @@ const mcpHandler = createMcpHandler(({ authInfo }) => { return buildMcpServer(userId) }) -const oauthHandler = requireMcpAuth( - auth, - (req, claims) => { - const userId = claims.sub - if (!userId) { - throw new Error('OAuth token has no sub claim') - } - const clientId = (claims.azp as string) ?? (claims.client_id as string) ?? '' - const scopes = - typeof claims.scope === 'string' - ? claims.scope.split(' ') - : ((claims.scopes as string[]) ?? []) - return mcpHandler.fetch(req, { - authInfo: { - token: '', - clientId, - scopes, - extra: { userId }, +export const disabledOauthHandler = async (): Promise => { + return new Response( + JSON.stringify({ + jsonrpc: '2.0', + error: { + code: -32000, + message: + 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS or a loopback address. Please configure HTTPS or authenticate with a Shumai API token.', }, - }) - }, - { - resource: mcpResource, - // In-process verification: avoids HTTP loopback round-trip and works even in test environments - // where no HTTP port is bound. - jwksUrl: (async () => { - const res = await auth.handler(new Request(`${authBaseUrl}/api/auth/jwks`)) - if (!res.ok) { - throw new Error(`Failed to load JWKS in-process: ${res.statusText}`) - } - return await res.json() - }) as unknown as string, - }, -) + id: null, + }), + { + status: 503, + headers: { 'Content-Type': 'application/json' }, + }, + ) +} + +const oauthHandler = isMcpOauthEnabled + ? requireMcpAuth( + auth, + (req, claims) => { + const userId = claims.sub + if (!userId) { + throw new Error('OAuth token has no sub claim') + } + const clientId = (claims.azp as string) ?? (claims.client_id as string) ?? '' + const scopes = + typeof claims.scope === 'string' + ? claims.scope.split(' ') + : ((claims.scopes as string[]) ?? []) + return mcpHandler.fetch(req, { + authInfo: { + token: '', + clientId, + scopes, + extra: { userId }, + }, + }) + }, + { + resource: mcpResource, + // In-process verification: avoids HTTP loopback round-trip and works even in test environments + // where no HTTP port is bound. + jwksUrl: (async () => { + const res = await auth.handler(new Request(`${authBaseUrl}/api/auth/jwks`)) + if (!res.ok) { + throw new Error(`Failed to load JWKS in-process: ${res.statusText}`) + } + return await res.json() + }) as unknown as string, + }, + ) + : disabledOauthHandler /** Shumai's MCP server (Streamable HTTP). Mounted at `/mcp` with dual API token and OAuth 2.1 auth. */ const route = new Hono<{ Variables: { user: User } }>().all('/mcp', async (c) => { diff --git a/packages/core/src/auth/auth.test.ts b/packages/core/src/auth/auth.test.ts index b471279e..9dd3584c 100644 --- a/packages/core/src/auth/auth.test.ts +++ b/packages/core/src/auth/auth.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest' import { prisma } from '@shumai/db' import { setupTestDbHooks } from '@shumai/db/test' -import { auth, authService } from './auth' +import { auth, authService, isLoopbackHost, isMcpResourceValid } from './auth' import { userMetadataService } from '../user-metadata/user-metadata' import { teamService } from '@shumai/core/src/team/team' @@ -326,3 +326,48 @@ describe('AuthService Password Reset', () => { } }) }) + +describe('MCP Resource Validation & Loopback Checking', () => { + it('correctly identifies loopback hostnames', () => { + expect(isLoopbackHost('localhost')).toBe(true) + expect(isLoopbackHost('127.0.0.1')).toBe(true) + expect(isLoopbackHost('127.0.0.254')).toBe(true) + expect(isLoopbackHost('[::1]')).toBe(true) + + expect(isLoopbackHost('43.133.100.178')).toBe(false) + expect(isLoopbackHost('192.168.1.100')).toBe(false) + expect(isLoopbackHost('10.0.0.1')).toBe(false) + expect(isLoopbackHost('example.com')).toBe(false) + expect(isLoopbackHost('128.0.0.1')).toBe(false) + }) + + it('validates MCP resource URLs according to RFC 9728 and MCP security rules', () => { + // Loopback HTTP URLs are allowed for development + expect(isMcpResourceValid('http://localhost:3000/mcp')).toEqual({ valid: true }) + expect(isMcpResourceValid('http://127.0.0.1:3000/mcp')).toEqual({ valid: true }) + expect(isMcpResourceValid('http://[::1]:3000/mcp')).toEqual({ valid: true }) + + // HTTPS is allowed for any host (including domains and remote IPs) + expect(isMcpResourceValid('https://shumai.example.com/mcp')).toEqual({ valid: true }) + expect(isMcpResourceValid('https://43.133.100.178:3000/mcp')).toEqual({ valid: true }) + + // Remote HTTP IPs and hostnames are rejected (the user issue) + const remoteIpResult = isMcpResourceValid('http://43.133.100.178:3000/mcp') + expect(remoteIpResult.valid).toBe(false) + expect(remoteIpResult.error).toContain( + 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs', + ) + + const remoteDomainResult = isMcpResourceValid('http://shumai.example.com/mcp') + expect(remoteDomainResult.valid).toBe(false) + expect(remoteDomainResult.error).toContain( + 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs', + ) + + // Invalid URL formats + expect(isMcpResourceValid('not-a-url').valid).toBe(false) + expect(isMcpResourceValid('http://user:pass@localhost:3000/mcp').valid).toBe(false) + expect(isMcpResourceValid('http://localhost:3000/mcp#frag').valid).toBe(false) + expect(isMcpResourceValid('http://localhost:3000/mcp?query=1').valid).toBe(false) + }) +}) diff --git a/packages/core/src/auth/auth.ts b/packages/core/src/auth/auth.ts index 4d38114d..ad63eb41 100644 --- a/packages/core/src/auth/auth.ts +++ b/packages/core/src/auth/auth.ts @@ -8,6 +8,7 @@ import { teamService } from '@shumai/core/src/team/team' import { inviteService } from '@shumai/core/src/invite/invite' import { createAuthMiddleware } from 'better-auth/api' import { userMetadataService } from '@shumai/core/src/user-metadata/user-metadata' +import { logger } from '@shumai/core/src/logger' interface GeneratedResetLink { url: string @@ -22,22 +23,80 @@ export const authBaseUrl = ( export const mcpResource = `${authBaseUrl}/mcp` export { hashPassword } from 'better-auth/crypto' +/** + * Checks whether a host is a loopback address (localhost, 127.0.0.0/8, or [::1]). + */ +export function isLoopbackHost(hostname: string): boolean { + const ipv4Octets = hostname.split('.') + const isIpv4Loopback = + ipv4Octets.length === 4 && + ipv4Octets[0] === '127' && + ipv4Octets.every((octet) => /^\d+$/.test(octet) && Number(octet) <= 255) + return hostname === 'localhost' || hostname === '[::1]' || isIpv4Loopback +} + +/** + * Validates whether an MCP resource URL meets RFC 9728 and MCP security requirements + * (HTTPS required unless using a localhost or loopback IP address). + */ +export function isMcpResourceValid(resource: string): { valid: boolean; error?: string } { + if (typeof resource !== 'string' || !resource) { + return { valid: false, error: 'MCP resource must be a non-empty string URL' } + } + let url: URL + try { + url = new URL(resource) + } catch { + return { valid: false, error: 'MCP resource must be an absolute URL' } + } + if (url.username || url.password) { + return { valid: false, error: 'MCP resource URL must not contain credentials' } + } + if (resource.includes('#')) { + return { valid: false, error: 'MCP resource URL must not contain a fragment' } + } + if (resource.includes('?')) { + return { valid: false, error: 'MCP resource URL must not contain a query' } + } + if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHost(url.hostname))) { + return { + valid: false, + error: + 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs', + } + } + return { valid: true } +} + +const mcpValidation = isMcpResourceValid(mcpResource) +export const isMcpOauthEnabled = mcpValidation.valid +if (!isMcpOauthEnabled) { + logger.error( + { mcpResource, error: mcpValidation.error }, + 'MCP OAuth 2.1 is disabled: resource URL must use HTTPS for remote hosts. The main server and Web UI will continue running normally, but MCP OAuth clients cannot connect until HTTPS is configured.', + ) +} + export const auth = betterAuth({ database: prismaAdapter(prisma, { provider: 'postgresql', }), plugins: [ jwt(), - mcp({ - loginPage: '/login', - consentPage: '/consent', - resource: mcpResource, - resources: [{ identifier: mcpResource, allowedScopes: ['mcp'] }], - scopes: ['openid', 'profile', 'email', 'offline_access', 'mcp'], - allowDynamicClientRegistration: true, - allowUnauthenticatedClientRegistration: true, - clientRegistrationDefaultApplicationType: 'infer', - }), + ...(isMcpOauthEnabled + ? [ + mcp({ + loginPage: '/login', + consentPage: '/consent', + resource: mcpResource, + resources: [{ identifier: mcpResource, allowedScopes: ['mcp'] }], + scopes: ['openid', 'profile', 'email', 'offline_access', 'mcp'], + allowDynamicClientRegistration: true, + allowUnauthenticatedClientRegistration: true, + clientRegistrationDefaultApplicationType: 'infer', + }), + ] + : []), ], emailAndPassword: { enabled: true,