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
This commit is contained in:
Yiling-J
2026-11-05 22:21:11 +08:00
committed by GitHub
parent 65e2ac1383
commit f304caea00
12 changed files with 596 additions and 62 deletions
+2
View File
@@ -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
+1 -1
View File
@@ -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:
+1 -1
View File
@@ -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` 的服务器上,请进行如下设置:
+22 -13
View File
@@ -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
}
+175
View File
@@ -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 = '<!DOCTYPE html><html><head><title>Shumai</title></head><body></body></html>'
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('')
})
})
})
+106
View File
@@ -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<string, string>,
isImmutable: boolean,
): (req: Request) => Response {
const bunFile = Bun.file(filePath)
const rawEtag = baseHeaders.etag || baseHeaders.ETag
const normalizedEtag = normalizeEtag(rawEtag)
const headers: Record<string, string> = {
...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<string, string>,
): (req: Request) => Response {
const rawEtag = baseHeaders.etag || baseHeaders.ETag
const etag = normalizeEtag(rawEtag) || `"${Bun.hash(htmlText).toString(16)}"`
const headers: Record<string, string> = {
...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 })
}
}
+1 -1
View File
@@ -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:
@@ -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<any>
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)
})
})
+19 -1
View File
@@ -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<typeof import('@shumai/core/src/operations')>()),
@@ -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,
})
})
})
})
+54 -34
View File
@@ -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<Response> => {
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) => {
+46 -1
View File
@@ -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)
})
})
+69 -10
View File
@@ -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,