@zhin.js/host-http 1.0.0

package/lib/http-host.d.ts

@@ -0,0 +1,50 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type WebSocket } from 'ws';
+import { TokenRegistry, type AuthScope, type ScopedTokenConfig } from './token-registry.js';
+import { type ListedRoute, type RouteMeta } from './openapi.js';
+export declare const REMOTE_CONSOLE_ORIGIN = "https://console.zhin.dev";
+export interface WsConnection {
+    readonly socket: WebSocket;
+    readonly request: IncomingMessage;
+    readonly authScope: AuthScope;
+}
+export interface WsHandle {
+    onConnection(listener: (connection: WsConnection) => void): () => void;
+    close(): void;
+}
+export interface HttpHostAddress {
+    readonly host: string;
+    readonly port: number;
+}
+export interface HttpHostOptions {
+    readonly host?: string;
+    readonly port?: number;
+    /** Primary full-scope Bearer token (`http.token`). */
+    readonly token?: string;
+    /** Additional scoped tokens (`http.tokens`). */
+    readonly tokens?: readonly ScopedTokenConfig[];
+    /** CORS allowlist; always merged with Remote Console origin. */
+    readonly corsOrigins?: readonly string[];
+    /**
+     * Paths under this prefix require Bearer auth when a token registry is configured.
+     * Defaults to `/api`. `/pub/*`, Console shell, and page routes stay public.
+     */
+    readonly apiBase?: string;
+    /** Extra HTTP path prefixes that skip auth even under `apiBase`. */
+    readonly authExemptPaths?: readonly string[];
+}
+export type HttpHandler = (request: IncomingMessage, response: ServerResponse, url: URL, authScope: AuthScope) => void | Promise<void>;
+export interface HttpRouteRegistration {
+    (): void;
+}
+export interface HttpHost {
+    ws(path: string): WsHandle;
+    route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
+    listRoutes(): readonly ListedRoute[];
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+    get address(): HttpHostAddress | undefined;
+    get tokenRegistry(): TokenRegistry;
+}
+export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
+export declare function createHttpHost(options?: HttpHostOptions): HttpHost;

package/lib/http-host.js

@@ -0,0 +1,410 @@
+import { createServer, } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createToken } from '@zhin.js/plugin-runtime';
+import { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
+import { buildOpenApiDocument, } from './openapi.js';
+import { isDemoHttpAllowed } from './console-rpc.js';
+const logger = getLogger('HttpHost');
+export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
+const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
+export const httpHostToken = createToken('zhin.host.http');
+export function createHttpHost(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 8086;
+    const apiBase = normalizePath(options.apiBase ?? '/api');
+    const corsOrigins = Object.freeze([
+        ...new Set([...DEFAULT_CORS_ORIGINS, ...(options.corsOrigins ?? [])]),
+    ]);
+    const authExempt = Object.freeze((options.authExemptPaths ?? []).map((path) => normalizePath(path)));
+    const tokenRegistry = new TokenRegistry({
+        primaryToken: options.token,
+        scopedTokens: options.tokens,
+    });
+    const wsRoutes = new Map();
+    const httpRoutes = [];
+    let address;
+    let closed = false;
+    const server = createServer((request, response) => {
+        void dispatchHttp(request, response);
+    });
+    // Track live TCP sockets so close() can destroy long-lived connections
+    // (SSE /api/events, keep-alive) that would otherwise block server.close().
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => {
+            sockets.delete(socket);
+        });
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    // Built-in public health probe (parity with host-router `/pub/health`).
+    httpRoutes.push(Object.freeze({
+        method: 'GET',
+        path: '/pub/health',
+        pattern: '/pub/health',
+        prefix: false,
+        meta: Object.freeze({ summary: 'Health probe', tags: ['pub'] }),
+        handler: (_request, response) => {
+            writeJson(response, 200, {
+                success: true,
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+            });
+        },
+    }));
+    // OpenAPI catalog (parity with host-router `/pub/openapi.json`).
+    httpRoutes.push(Object.freeze({
+        method: 'GET',
+        path: '/pub/openapi.json',
+        pattern: '/pub/openapi.json',
+        prefix: false,
+        meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
+        handler: (request, response) => {
+            const hostHeader = headerValue(request.headers.host) ?? 'localhost';
+            const proto = headerValue(request.headers['x-forwarded-proto']) ?? 'http';
+            writeJson(response, 200, buildOpenApiDocument(listListedRoutes(), {
+                apiBase,
+                serverUrl: `${proto}://${hostHeader}`,
+                version: process.env.npm_package_version ?? '0.0.0',
+            }));
+        },
+    }));
+    server.on('upgrade', (request, socket, head) => {
+        if (closed) {
+            socket.destroy();
+            return;
+        }
+        const pathname = upgradePath(request.url);
+        const listeners = wsRoutes.get(pathname);
+        if (!listeners || listeners.size === 0) {
+            logger.debug(formatCompact({ op: 'ws_upgrade_unmatched', path: pathname }));
+            socket.destroy();
+            return;
+        }
+        const auth = authenticateUpgrade(request, pathname);
+        if (!auth.ok) {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        try {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                const connection = Object.freeze({
+                    socket: ws,
+                    request,
+                    authScope: auth.scope,
+                });
+                for (const listener of listeners)
+                    listener(connection);
+            });
+        }
+        catch (err) {
+            logger.warn(formatCompact({
+                op: 'ws_upgrade_failed',
+                path: pathname,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+            try {
+                socket.destroy();
+            }
+            catch {
+                /* already destroyed */
+            }
+        }
+    });
+    function authenticateUpgrade(request, pathname) {
+        if (!tokenRegistry.hasAnyToken())
+            return { ok: true, scope: 'full' };
+        let url;
+        try {
+            url = new URL(request.url ?? '/', 'http://localhost');
+        }
+        catch {
+            return { ok: false };
+        }
+        const token = extractBearerToken(headerValue(request.headers.authorization), url.searchParams.get('token'));
+        const scope = tokenRegistry.resolve(token);
+        if (!scope)
+            return { ok: false };
+        if (scope === 'demo' && !isDemoWebSocketPath(pathname))
+            return { ok: false };
+        return { ok: true, scope };
+    }
+    async function dispatchHttp(request, response) {
+        if (closed) {
+            response.writeHead(503);
+            response.end();
+            return;
+        }
+        const method = (request.method ?? 'GET').toUpperCase();
+        let url;
+        try {
+            url = new URL(request.url ?? '/', 'http://localhost');
+        }
+        catch {
+            response.writeHead(400);
+            response.end();
+            return;
+        }
+        const pathname = normalizePath(url.pathname);
+        const origin = headerValue(request.headers.origin);
+        const corsOk = corsMatch(origin, corsOrigins);
+        if (method === 'OPTIONS') {
+            if (corsOk && origin)
+                applyCors(response, origin, corsOrigins);
+            response.writeHead(204);
+            response.end();
+            return;
+        }
+        const auth = authenticateHttp(request, url, pathname);
+        if (!auth.ok) {
+            if (corsOk && origin)
+                applyCors(response, origin, corsOrigins);
+            writeJson(response, 401, { success: false, error: 'Invalid or missing token' });
+            return;
+        }
+        const route = matchHttpRoute(httpRoutes, method, pathname);
+        if (!route) {
+            if (corsOk && origin)
+                applyCors(response, origin, corsOrigins);
+            response.writeHead(404);
+            response.end();
+            return;
+        }
+        try {
+            if (corsOk && origin)
+                applyCors(response, origin, corsOrigins);
+            response.setHeader('X-Content-Type-Options', 'nosniff');
+            response.setHeader('X-Frame-Options', 'SAMEORIGIN');
+            await route.handler(request, response, url, auth.scope);
+        }
+        catch (err) {
+            logger.warn(formatCompact({
+                op: 'http_handler_failed',
+                path: pathname,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+            if (!response.headersSent) {
+                response.writeHead(500);
+                response.end();
+            }
+        }
+    }
+    function authenticateHttp(request, url, pathname) {
+        if (!requiresHttpAuth(pathname, apiBase, authExempt)) {
+            return { ok: true, scope: 'full' };
+        }
+        if (!tokenRegistry.hasAnyToken()) {
+            return { ok: true, scope: 'full' };
+        }
+        const token = extractBearerToken(headerValue(request.headers.authorization), url.searchParams.get('token'));
+        const scope = tokenRegistry.resolve(token);
+        if (!scope)
+            return { ok: false };
+        if (scope === 'demo') {
+            const method = (request.method ?? 'GET').toUpperCase();
+            if (!isDemoHttpAllowed(method, pathname, apiBase))
+                return { ok: false };
+        }
+        return { ok: true, scope };
+    }
+    function listListedRoutes() {
+        return Object.freeze(httpRoutes.map((route) => Object.freeze({
+            method: route.method,
+            pattern: route.pattern,
+            meta: route.meta,
+        })));
+    }
+    return {
+        ws(pathname) {
+            const normalized = normalizePath(pathname);
+            let listeners = wsRoutes.get(normalized);
+            if (!listeners) {
+                listeners = new Set();
+                wsRoutes.set(normalized, listeners);
+            }
+            const owned = new Set();
+            return {
+                onConnection(listener) {
+                    listeners.add(listener);
+                    owned.add(listener);
+                    return () => {
+                        listeners.delete(listener);
+                        owned.delete(listener);
+                    };
+                },
+                close() {
+                    for (const listener of owned)
+                        listeners.delete(listener);
+                    owned.clear();
+                },
+            };
+        },
+        route(method, path, handler, meta) {
+            const normalizedMethod = method.toUpperCase();
+            const prefix = path.endsWith('/*');
+            const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
+            const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
+            const entry = Object.freeze({
+                method: normalizedMethod,
+                path: normalizedPath,
+                pattern,
+                prefix,
+                handler,
+                meta,
+            });
+            httpRoutes.push(entry);
+            return () => {
+                const index = httpRoutes.indexOf(entry);
+                if (index >= 0)
+                    httpRoutes.splice(index, 1);
+            };
+        },
+        listRoutes() {
+            return listListedRoutes();
+        },
+        get address() {
+            return address;
+        },
+        get tokenRegistry() {
+            return tokenRegistry;
+        },
+        listen() {
+            if (address)
+                return Promise.resolve(address);
+            return new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen({ host, port }, () => {
+                    server.off('error', reject);
+                    const bound = server.address();
+                    const listenPort = typeof bound === 'object' && bound ? bound.port : port;
+                    const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+                    address = Object.freeze({ host: publicHost, port: listenPort });
+                    logger.info(formatCompact({
+                        http: `http://${publicHost}:${listenPort}`,
+                        token: tokenRegistry.hasAnyToken()
+                            ? `${tokenRegistry.primaryTokenPrefixForLog()}…`
+                            : '(none)',
+                        cors: corsOrigins.join(','),
+                        ws_routes: [...wsRoutes.keys()].join(',') || '(none)',
+                        http_routes: httpRoutes.length,
+                    }));
+                    resolve(address);
+                });
+            });
+        },
+        close() {
+            if (closed)
+                return Promise.resolve();
+            closed = true;
+            wsRoutes.clear();
+            httpRoutes.length = 0;
+            // Rollback paths dispose a host whose generation never reached listen().
+            if (!server.listening) {
+                address = undefined;
+                return Promise.resolve();
+            }
+            return new Promise((resolve, reject) => {
+                // Long-lived connections (SSE, keep-alive, WS) never end on their own:
+                // destroy tracked sockets and terminate WS clients before close(),
+                // otherwise the close callbacks would never fire.
+                for (const socket of sockets)
+                    socket.destroy();
+                sockets.clear();
+                for (const client of wss.clients)
+                    client.terminate();
+                wss.close((wssError) => {
+                    if (wssError) {
+                        reject(wssError);
+                        return;
+                    }
+                    server.close((serverError) => {
+                        if (serverError) {
+                            reject(serverError);
+                            return;
+                        }
+                        logger.debug(formatCompact({ op: 'http_host_closed' }));
+                        address = undefined;
+                        resolve();
+                    });
+                });
+            });
+        },
+    };
+}
+function requiresHttpAuth(pathname, apiBase, authExempt) {
+    if (pathname === '/pub' || pathname.startsWith('/pub/'))
+        return false;
+    if (authExempt.some((path) => pathname === path || pathname.startsWith(`${path}/`))) {
+        return false;
+    }
+    return pathname === apiBase || pathname.startsWith(`${apiBase}/`);
+}
+function corsMatch(origin, allowed) {
+    if (!origin || allowed.length === 0)
+        return false;
+    return allowed.includes('*')
+        || allowed.some((entry) => (entry === origin
+            || (entry.endsWith('*') && origin.startsWith(entry.slice(0, -1)))));
+}
+function applyCors(response, origin, allowed) {
+    response.setHeader('Access-Control-Allow-Origin', allowed.includes('*') ? '*' : origin);
+    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    response.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Accept');
+    response.setHeader('Access-Control-Max-Age', '86400');
+}
+function writeJson(response, status, body) {
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+    });
+    response.end(payload);
+}
+function headerValue(value) {
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+function matchHttpRoute(routes, method, pathname) {
+    let best;
+    let bestLength = -1;
+    for (const route of routes) {
+        if (route.method !== method && route.method !== 'ALL')
+            continue;
+        if (route.prefix) {
+            const matches = route.path === '/'
+                ? pathname.startsWith('/')
+                : pathname === route.path || pathname.startsWith(`${route.path}/`);
+            if (matches && route.path.length > bestLength) {
+                best = route;
+                bestLength = route.path.length;
+            }
+            continue;
+        }
+        if (pathname === route.path && route.path.length >= bestLength) {
+            best = route;
+            bestLength = route.path.length;
+        }
+    }
+    return best;
+}
+function normalizePath(pathname) {
+    if (!pathname.startsWith('/'))
+        return `/${pathname}`;
+    // 线性裁剪尾部斜杠（等价于 /\/+$/u，但避免长串 `/` 无匹配时的
+    // 二次方回溯 — js/polynomial-redos）。
+    let end = pathname.length;
+    while (end > 0 && pathname[end - 1] === '/')
+        end -= 1;
+    return pathname.slice(0, end) || '/';
+}
+function upgradePath(url) {
+    try {
+        return normalizePath(new URL(url ?? '/', 'http://localhost').pathname);
+    }
+    catch {
+        return '/';
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
+export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, type AuthScope, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
+export { timingSafeEqualString } from './timing-safe-equal.js';
+export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, type BuildOpenApiOptions, type ListedRoute, type OpenApiParameter, type RouteMeta, } from './openapi.js';
+export { HttpBodyError, readJsonBody, } from './json-body.js';
+export { dispatchRuntimeConsoleRpc, isDemoHttpAllowed, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type RuntimeEndpointSummary, } from './console-rpc.js';
+export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, type FileTreeNode, } from './project-files.js';
+export { registerConsoleRestPages, type ConsoleAgentIntrospection, type ConsoleAgentRuntime, type ConsoleAgentSessionTree, type ConsoleRestCtx, type ConsoleRestPagesOptions, } from './console-rest-pages.js';

package/lib/index.js

@@ -0,0 +1,8 @@
+export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
+export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
+export { timingSafeEqualString } from './timing-safe-equal.js';
+export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, } from './openapi.js';
+export { HttpBodyError, readJsonBody, } from './json-body.js';
+export { dispatchRuntimeConsoleRpc, isDemoHttpAllowed, pickRpcReply, } from './console-rpc.js';
+export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, } from './project-files.js';
+export { registerConsoleRestPages, } from './console-rest-pages.js';

package/lib/json-body.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage } from 'node:http';
+export declare class HttpBodyError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Read and parse a JSON request body with a size limit (default 1 MiB).
+ * Empty bodies become `undefined`.
+ */
+export declare function readJsonBody<T = unknown>(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<T | undefined>;

package/lib/json-body.js

@@ -0,0 +1,37 @@
+export class HttpBodyError extends Error {
+    statusCode;
+    constructor(message, statusCode = 400) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'HttpBodyError';
+    }
+}
+/**
+ * Read and parse a JSON request body with a size limit (default 1 MiB).
+ * Empty bodies become `undefined`.
+ */
+export async function readJsonBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new HttpBodyError(`Request body exceeds ${limit} bytes`, 413);
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new HttpBodyError('Invalid JSON body', 400);
+    }
+}

package/lib/openapi.d.ts

@@ -0,0 +1,31 @@
+export type OpenApiParameter = {
+    readonly name: string;
+    readonly in: 'query' | 'path' | 'header';
+    readonly required?: boolean;
+    readonly description?: string;
+    readonly schema?: Record<string, unknown>;
+};
+export type RouteMeta = {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly operationId?: string;
+    readonly deprecated?: boolean;
+    readonly parameters?: readonly OpenApiParameter[];
+    readonly responses?: Record<string, unknown>;
+    readonly requestBody?: Record<string, unknown>;
+};
+export type ListedRoute = {
+    readonly method: string;
+    readonly pattern: string;
+    readonly meta?: RouteMeta;
+};
+export type BuildOpenApiOptions = {
+    readonly title?: string;
+    readonly version?: string;
+    readonly apiBase?: string;
+    readonly serverUrl?: string;
+};
+export declare function patternToOpenApiPath(pattern: string): string;
+export declare function routeRequiresBearerAuth(pathname: string, apiBase: string): boolean;
+export declare function buildOpenApiDocument(routes: readonly ListedRoute[], options?: BuildOpenApiOptions): Record<string, unknown>;