mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-19 14:16:29 +00:00
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:
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
}
|
||||
|
||||
@@ -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('')
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -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 })
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
})
|
||||
})
|
||||
@@ -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,
|
||||
})
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
@@ -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) => {
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
})
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user