@jsbot-tellus/core 2.5.0 → 2.6.0

package/src/core/web/routes/status.ts

@@ -0,0 +1,191 @@
+import { SqliteSessionStore } from '../../storage/session.js'
+import { logLevels, type LogLevel } from '../../logging/logger.js'
+import type { FeedEventType } from '../event-feed.js'
+import type { WebUiDeps, WebUiRuntime } from '../types.js'
+import { HttpError, sendData, withTimeout } from '../http.js'
+import { clampInt, requireRuntime, type ApiContext } from './shared.js'
+
+interface LoginValue {
+    userId: number
+    nickname: string
+}
+
+const loginCache = new WeakMap<
+    WebUiRuntime,
+    { at: number; value: LoginValue | null }
+>()
+
+async function loginInfo(runtime: WebUiRuntime): Promise<LoginValue | null> {
+    if (!runtime.kernel.isConnected) return null
+
+    const cached = loginCache.get(runtime)
+
+    if (cached && Date.now() - cached.at < 10_000) return cached.value
+
+    let value: LoginValue | null = null
+
+    try {
+        const info = await withTimeout(runtime.api.getLoginInfo(), 2_000)
+
+        if (typeof info.user_id === 'number') {
+            value = {
+                userId: info.user_id,
+                nickname: info.nickname || String(info.user_id),
+            }
+        }
+    } catch {
+        value = null
+    }
+
+    loginCache.set(runtime, { at: Date.now(), value })
+
+    return value
+}
+
+interface RuntimeStatus {
+    generation: number
+    state: string
+    uptimeMs: number
+    connected: boolean
+    login: LoginValue | null
+    counts: {
+        plugins: number
+        loadedPlugins: number
+        enabledPlugins: number
+        sessions: number
+        kvPlugins: number
+    }
+}
+
+function countKvPlugins(database: WebUiRuntime['database']): number {
+    const row = database.connection
+        .prepare('SELECT COUNT(DISTINCT plugin_id) AS count FROM plugin_kv')
+        .get() as { count: number } | undefined
+
+    return row?.count ?? 0
+}
+
+async function runtimeStatus(runtime: WebUiRuntime): Promise<RuntimeStatus> {
+    const statuses = runtime.kernel.listPlugins()
+    const sessions = await new SqliteSessionStore(runtime.database).count()
+
+    return {
+        generation: runtime.generation,
+        state: runtime.kernel.state,
+        uptimeMs: runtime.kernel.uptimeMs,
+        connected: runtime.kernel.isConnected,
+        login: await loginInfo(runtime),
+        counts: {
+            plugins: statuses.length,
+            loadedPlugins: statuses.filter((entry) => entry.loaded).length,
+            enabledPlugins: statuses.filter((entry) => entry.enabled).length,
+            sessions,
+            kvPlugins: countKvPlugins(runtime.database),
+        },
+    }
+}
+
+function pathsInfo(deps: WebUiDeps) {
+    return {
+        config: deps.paths.configPath,
+        data: deps.paths.dataDir,
+        plugins: deps.paths.pluginDir,
+    }
+}
+
+function assertLevel(value: string): LogLevel {
+    if (!(logLevels as readonly string[]).includes(value)) {
+        throw new HttpError(400, `invalid log level: ${value}`)
+    }
+
+    return value as LogLevel
+}
+
+const FEED_TYPES: readonly FeedEventType[] = [
+    'message',
+    'notice',
+    'request',
+    'meta',
+    'other',
+]
+
+function assertFeedType(value: string): FeedEventType {
+    if (!FEED_TYPES.includes(value as FeedEventType)) {
+        throw new HttpError(400, `invalid event type: ${value}`)
+    }
+
+    return value as FeedEventType
+}
+
+export async function handleStatus(ctx: ApiContext): Promise<void> {
+    const { deps, res } = ctx
+    const runtime = deps.getRuntime()
+    const webui = {
+        listening: deps.getListening(),
+        requiresProcessRestart: deps.getRequiresProcessRestart(),
+    }
+
+    if (!runtime) {
+        sendData(res, 200, {
+            restarting: deps.isRestarting(),
+            startupError: deps.getStartupError(),
+            runtime: null,
+            webui,
+            version: deps.version,
+            paths: pathsInfo(deps),
+        })
+
+        return
+    }
+
+    sendData(res, 200, {
+        restarting: deps.isRestarting(),
+        startupError: deps.getStartupError(),
+        runtime: await runtimeStatus(runtime),
+        webui,
+        version: deps.version,
+        paths: pathsInfo(deps),
+    })
+}
+
+export async function handleCommands(ctx: ApiContext): Promise<void> {
+    sendData(ctx.res, 200, requireRuntime(ctx.deps).kernel.listCommands())
+}
+
+export async function handleLogsList(ctx: ApiContext): Promise<void> {
+    const level = ctx.search.get('level')
+
+    if (level) assertLevel(level)
+
+    const scope = ctx.search.get('scope') ?? undefined
+    const query = ctx.search.get('query') ?? undefined
+    const limit = clampInt(ctx.search.get('limit'), 200, 1, 1_000)
+
+    sendData(
+        ctx.res,
+        200,
+        ctx.deps.logs.list({
+            ...(level ? { level: assertLevel(level) } : {}),
+            scope,
+            query,
+            limit,
+        })
+    )
+}
+
+export async function handleEventsList(ctx: ApiContext): Promise<void> {
+    const type = ctx.search.get('type')
+
+    if (type) assertFeedType(type)
+
+    const limit = clampInt(ctx.search.get('limit'), 100, 1, 500)
+
+    sendData(
+        ctx.res,
+        200,
+        ctx.deps.events.list({
+            ...(type ? { type: assertFeedType(type) } : {}),
+            limit,
+        })
+    )
+}

package/src/core/web/server/auth.ts

@@ -0,0 +1,126 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { AuthManager, type AuthSession } from '../auth.js'
+import {
+    clearCookie,
+    clientIp,
+    parseCookies,
+    readJsonBody,
+    sendData,
+    sendError,
+    serializeCookie,
+} from '../http.js'
+import { HttpError } from '../http.js'
+import type { WebUiDeps } from '../types.js'
+
+export const SESSION_COOKIE = 'jsbot_webui'
+
+export function authenticate(
+    auth: AuthManager,
+    req: IncomingMessage
+): AuthSession | null {
+    const cookies = parseCookies(req.headers.cookie)
+
+    return auth.authenticate(cookies[SESSION_COOKIE])
+}
+
+export function tokenOf(req: IncomingMessage): string | undefined {
+    const cookies = parseCookies(req.headers.cookie)
+
+    return cookies[SESSION_COOKIE]
+}
+
+export function isSecure(deps: WebUiDeps, req: IncomingMessage): boolean {
+    if (!deps.getWebUiConfig().trustProxy) return false
+
+    const proto = req.headers['x-forwarded-proto']
+
+    return typeof proto === 'string' && proto.split(',')[0]?.trim() === 'https'
+}
+
+export interface HandleAuthOptions {
+    req: IncomingMessage
+    res: ServerResponse
+    action: string | undefined
+    auth: AuthManager
+    deps: WebUiDeps
+    bodyLimit: number
+}
+
+export async function handleAuth(options: HandleAuthOptions): Promise<void> {
+    const { req, res, action, auth, deps, bodyLimit } = options
+    const method = req.method ?? 'GET'
+
+    if (action === 'login' && method === 'POST') {
+        const body = await readJsonBody(req, bodyLimit)
+        const value =
+            typeof body === 'object' && body !== null
+                ? (body as Record<string, unknown>)
+                : {}
+        const ip = clientIp(req, deps.getWebUiConfig().trustProxy)
+        const result = await auth.login(
+            value['username'],
+            value['password'],
+            ip
+        )
+
+        if (!result.ok || !result.session) {
+            const headers: Record<string, string | undefined> = {}
+
+            if (result.retryAfterSeconds !== undefined) {
+                headers['retry-after'] = String(result.retryAfterSeconds)
+            }
+
+            sendError(
+                res,
+                result.status,
+                result.message ?? 'login failed',
+                undefined,
+                headers
+            )
+
+            return
+        }
+
+        res.setHeader(
+            'set-cookie',
+            serializeCookie(SESSION_COOKIE, result.session.token, {
+                maxAgeSeconds: deps.getWebUiConfig().sessionTtlHours * 3600,
+                secure: isSecure(deps, req),
+            })
+        )
+        sendData(res, result.status, {
+            username: result.session.username,
+            expiresAt: result.session.expiresAt,
+        })
+
+        return
+    }
+
+    if (action === 'logout' && method === 'POST') {
+        const session = authenticate(auth, req)
+
+        auth.logout(tokenOf(req))
+        deps.logger.info(`webui logout: ${session?.username ?? 'unknown'}`)
+        res.setHeader('set-cookie', clearCookie(SESSION_COOKIE))
+        sendData(res, 200, { ok: true })
+
+        return
+    }
+
+    if (action === 'me' && method === 'GET') {
+        const session = authenticate(auth, req)
+
+        if (session === null) {
+            throw new HttpError(401, '未登录或会话已过期')
+        }
+
+        sendData(res, 200, {
+            username: session.username,
+            expiresAt: session.expiresAt,
+        })
+
+        return
+    }
+
+    throw new HttpError(404, `not found: ${method} /api/auth/${action ?? ''}`)
+}

package/src/core/web/server/csp.ts

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * CSP for the WebUI. webui/index.html ships a single authorized inline
+ * script (the no-flash appearance bootstrap for the first paint); its exact
+ * hash is derived from the built index.html on disk so editing the bootstrap
+ * only needs a rebuild, never a source edit. Every other inline script
+ * stays blocked.
+ */
+export function buildCsp(scriptSrc: string): string {
+    return `default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src ${scriptSrc}; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'`
+}
+
+/** Extracts the bootstrap script's sha256 from a built index.html. */
+export function cspForStaticDir(staticDir: string): string | null {
+    try {
+        const html = readFileSync(join(staticDir, 'index.html'), 'utf8')
+        const match = /<script>([\s\S]*?)<\/script>/.exec(html)
+        const bootstrap = match?.[1]
+
+        if (bootstrap === undefined) return null
+
+        const hash = createHash('sha256')
+            .update(bootstrap, 'utf8')
+            .digest('base64')
+
+        return buildCsp(`'self' 'sha256-${hash}'`)
+    } catch {
+        return null
+    }
+}

package/src/core/web/server/request.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage } from 'node:http'
+import type { URLSearchParamsLike } from '../http.js'
+
+export function parseSearch(req: IncomingMessage): URLSearchParamsLike {
+    const index = (req.url ?? '').indexOf('?')
+    const query = index >= 0 ? (req.url ?? '').slice(index + 1) : ''
+
+    return new URLSearchParams(query)
+}
+
+export function segmentsOf(pathname: string): string[] {
+    return pathname
+        .split('/')
+        .filter((segment) => segment.length > 0)
+        .map((segment) => {
+            try {
+                return decodeURIComponent(segment)
+            } catch {
+                return segment
+            }
+        })
+}
+
+export function pathnameOf(req: IncomingMessage): string {
+    const url = req.url ?? '/'
+    const index = url.indexOf('?')
+    const raw = index >= 0 ? url.slice(0, index) : url
+
+    if (raw.includes('%')) {
+        try {
+            return decodeURIComponent(raw)
+        } catch {
+            return raw
+        }
+    }
+
+    return raw
+}

package/src/core/web/server/security.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http'
+
+export const SECURITY_HEADERS: Record<string, string> = {
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'referrer-policy': 'no-referrer',
+    'cross-origin-opener-policy': 'same-origin',
+}
+
+export function applySecurityHeaders(res: ServerResponse): void {
+    for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+        res.setHeader(key, value)
+    }
+}

package/src/core/web/server/sse.ts

@@ -0,0 +1,74 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { HttpError, safeStringify } from '../http.js'
+
+export const SSE_HEARTBEAT_MS = 15_000
+export const DEFAULT_MAX_SSE_CLIENTS = 20
+export const SSE_TIMEOUT_MS = 60_000
+
+export interface SseConnection {
+    res: ServerResponse
+    close(): void
+}
+
+export interface OpenSseOptions {
+    req: IncomingMessage
+    res: ServerResponse
+    subscribe: (listener: (entry: unknown) => void) => () => void
+    openedAt: number
+    maxClients: number
+    connections: Set<SseConnection>
+}
+
+export function openSse(options: OpenSseOptions): void {
+    const { req, res, subscribe, openedAt, maxClients, connections } = options
+
+    if (connections.size >= maxClients) {
+        throw new HttpError(503, '实时连接数量已达上限')
+    }
+
+    res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-store, no-transform',
+        connection: 'keep-alive',
+    })
+    res.write(':ok\n\n')
+
+    const connection: SseConnection = {
+        res,
+        close: () => {
+            unsubscribe()
+            clearInterval(heartbeat)
+            connections.delete(connection)
+
+            try {
+                res.end()
+            } catch {
+                // Already closed.
+            }
+        },
+    }
+
+    let closing = false
+
+    const unsubscribe = subscribe((entry) => {
+        if (closing) return
+
+        res.write(`data: ${safeStringify(entry)}\n\n`)
+    })
+
+    const heartbeat = setInterval(() => {
+        res.write(`:keepalive ${Date.now() - openedAt}\n\n`)
+    }, SSE_HEARTBEAT_MS)
+
+    req.on('close', () => {
+        if (closing) return
+
+        closing = true
+
+        unsubscribe()
+        clearInterval(heartbeat)
+        connections.delete(connection)
+    })
+
+    connections.add(connection)
+}

package/src/core/web/server/static.ts

@@ -0,0 +1,112 @@
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { extname, join, resolve, sep } from 'node:path'
+import { HttpError, isImmutableAsset, mimeType, withTimeout } from '../http.js'
+
+export interface FallbackPageOptions {
+    listening: string
+}
+
+export const FALLBACK_BODY = (
+    options: FallbackPageOptions
+): string => `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<title>JsBot WebUI</title>
+<style>body{font-family:system-ui,sans-serif;max-width:36em;margin:4rem auto;padding:0 1rem;color:#333}</style>
+</head><body>
+<h1>WebUI 前端未构建</h1>
+<p>管理 API 正常运行，但静态资源缺失。请在项目根目录执行：</p>
+<pre><code>npm run build:webui</code></pre>
+<p>然后重启进程，访问 <code>${options.listening}</code>。</p>
+<p>API 仍可通过 <code>/api/health</code>、登录和各接口访问。</p>
+</body></html>
+`
+
+export interface ServeStaticOptions {
+    req: IncomingMessage
+    res: ServerResponse
+    pathname: string
+    staticDir: string | null
+    fallbackBody: string
+}
+
+export async function serveStatic(options: ServeStaticOptions): Promise<void> {
+    const { req, res, pathname, staticDir, fallbackBody } = options
+
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        throw new HttpError(405, `method not allowed: ${req.method}`)
+    }
+
+    if (staticDir === null) {
+        res.setHeader('content-type', 'text/html; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.writeHead(503)
+        res.end(fallbackBody)
+
+        return
+    }
+
+    const cleaned = pathname.replace(/\/+$/, '') || '/'
+    let filePath =
+        cleaned === '/'
+            ? join(staticDir, 'index.html')
+            : resolve(staticDir, `.${cleaned}`)
+
+    if (!filePath.startsWith(staticDir + sep) && filePath !== staticDir) {
+        throw new HttpError(403, 'forbidden')
+    }
+
+    let fileStat = await statOrNull(filePath)
+
+    if (fileStat?.isDirectory()) {
+        filePath = join(filePath, 'index.html')
+        fileStat = await statOrNull(filePath)
+    }
+
+    if (fileStat === null) {
+        // SPA fallback: only routes without a file extension.
+        if (extname(cleaned) === '') {
+            filePath = join(staticDir, 'index.html')
+            fileStat = await statOrNull(filePath)
+        }
+
+        if (fileStat === null) throw new HttpError(404, 'not found')
+    }
+
+    const cacheControl = isImmutableAsset(cleaned)
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache'
+
+    res.setHeader('content-type', mimeType(filePath))
+    res.setHeader('cache-control', cacheControl)
+    res.setHeader('content-length', String(fileStat.size))
+    res.writeHead(200)
+
+    if (req.method === 'HEAD') {
+        res.end()
+
+        return
+    }
+
+    const stream = createReadStream(filePath)
+
+    stream.on('error', () => {
+        try {
+            res.end()
+        } catch {
+            // Already closed.
+        }
+    })
+    stream.pipe(res)
+}
+
+export async function statOrNull(
+    filePath: string
+): Promise<Awaited<ReturnType<typeof stat>> | null> {
+    try {
+        return await withTimeout(stat(filePath), 1_000)
+    } catch {
+        return null
+    }
+}