@zhin.js/host-http 1.1.14 → 1.1.16

package/lib/host-installer.js

@@ -0,0 +1,211 @@
+import { bindGenerationAdmission, expandEnvironmentValue, } from '@zhin.js/plugin-runtime';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { httpHostToken, } from './http-host.js';
+export async function resolveHttpConfig(config, envOverlay, projectRoot = process.cwd()) {
+    const document = await readConfigDocument(config);
+    if (!document || typeof document !== 'object')
+        return {};
+    const http = document.http;
+    if (!http || typeof http !== 'object')
+        return {};
+    const value = expandEnvironmentValue(http, (key) => envOverlay?.[key] ?? process.env[key]);
+    const primary = Object.freeze({
+        host: typeof value.host === 'string' ? value.host : undefined,
+        port: typeof value.port === 'number' ? value.port : undefined,
+        token: typeof value.token === 'string' ? value.token : undefined,
+        tokens: parseScopedTokens(value.tokens),
+        corsOrigins: injectDesktopWebviewOrigins(parseStringList(value.corsOrigins), envOverlay),
+        apiBase: typeof value.base === 'string' ? value.base : undefined,
+        tls: await parseTlsConfig(value.tls, projectRoot),
+    });
+    const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot);
+    const listeners = await injectDesktopDeviceListener(configuredListeners, primary, envOverlay, projectRoot);
+    return Object.freeze({ ...primary, ...(listeners.length > 0 ? { listeners } : {}) });
+}
+const DESKTOP_WEBVIEW_ORIGINS = Object.freeze([
+    'tauri://localhost',
+    'http://tauri.localhost',
+    'https://tauri.localhost',
+]);
+function injectDesktopWebviewOrigins(configured, envOverlay) {
+    const origin = envOverlay?.ZHIN_DESKTOP_WEBVIEW_ORIGIN
+        ?? process.env.ZHIN_DESKTOP_WEBVIEW_ORIGIN;
+    if (origin === undefined)
+        return configured;
+    if (!DESKTOP_WEBVIEW_ORIGINS.includes(origin)) {
+        throw new Error('ZHIN_DESKTOP_WEBVIEW_ORIGIN is not a trusted Tauri origin');
+    }
+    return Object.freeze([...new Set([...(configured ?? []), ...DESKTOP_WEBVIEW_ORIGINS])]);
+}
+/**
+ * Desktop releases before the dual-listener migration may already have a
+ * user-owned zhin.config.yml without http.listeners. The native shell passes
+ * these trusted variables on every launch, so append the secure Device
+ * listener without replacing the user's persisted configuration.
+ */
+async function injectDesktopDeviceListener(configured, primary, envOverlay, projectRoot) {
+    const environment = (key) => envOverlay?.[key] ?? process.env[key];
+    if (!parseEnabled(environment('ZHIN_DESKTOP_DEVICE_LISTENER_ENABLED') ?? false, 'ZHIN_DESKTOP_DEVICE_LISTENER_ENABLED'))
+        return configured;
+    const host = environment('ZHIN_DESKTOP_DEVICE_HOST')?.trim() || '0.0.0.0';
+    const portValue = environment('ZHIN_DESKTOP_DEVICE_PORT')?.trim();
+    const port = portValue === undefined || portValue === '' ? 17_889 : Number(portValue);
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+        throw new Error('ZHIN_DESKTOP_DEVICE_PORT must be a valid TCP port');
+    }
+    const existing = configured.find(listener => listener.host === host && listener.port === port);
+    if (existing?.tls)
+        return configured;
+    if (existing) {
+        throw new Error('Desktop Device listener conflicts with a non-TLS http.listeners entry');
+    }
+    const tls = await parseTlsConfig({
+        enabled: true,
+        keyFile: environment('ZHIN_DESKTOP_TLS_KEY_FILE'),
+        certFile: environment('ZHIN_DESKTOP_TLS_CERT_FILE'),
+        minVersion: 'TLSv1.2',
+    }, projectRoot);
+    return Object.freeze([...configured, Object.freeze({ ...primary, host, port, tls })]);
+}
+async function parseAdditionalListeners(value, primary, projectRoot) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new Error('http.listeners must be an array');
+    const listeners = [];
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error(`http.listeners[${index}] must be an object`);
+        }
+        const listener = entry;
+        if (!parseEnabled(listener.enabled, `http.listeners[${index}].enabled`))
+            continue;
+        if (typeof listener.host !== 'string' || !listener.host) {
+            throw new Error(`http.listeners[${index}].host is required`);
+        }
+        if (typeof listener.port !== 'number') {
+            throw new Error(`http.listeners[${index}].port is required`);
+        }
+        listeners.push(Object.freeze({
+            ...primary,
+            host: listener.host,
+            port: listener.port,
+            tls: await parseTlsConfig(listener.tls, projectRoot),
+        }));
+    }
+    return Object.freeze(listeners);
+}
+async function parseTlsConfig(value, projectRoot) {
+    if (value === undefined || value === null || value === false)
+        return undefined;
+    if (!value || typeof value !== 'object')
+        throw new Error('http.tls must be an object');
+    const tls = value;
+    const enabled = parseTlsEnabled(tls.enabled);
+    if (!enabled)
+        return undefined;
+    if (typeof tls.keyFile !== 'string' || !tls.keyFile
+        || typeof tls.certFile !== 'string' || !tls.certFile) {
+        throw new Error('http.tls.keyFile and http.tls.certFile are required');
+    }
+    const minVersion = tls.minVersion;
+    if (minVersion !== undefined
+        && !['TLSv1.2', 'TLSv1.3'].includes(String(minVersion))) {
+        throw new Error('http.tls.minVersion must be TLSv1.2 or TLSv1.3');
+    }
+    const [key, cert, ca] = await Promise.all([
+        readFile(resolveTlsPath(projectRoot, tls.keyFile)),
+        readFile(resolveTlsPath(projectRoot, tls.certFile)),
+        typeof tls.caFile === 'string' && tls.caFile
+            ? readFile(resolveTlsPath(projectRoot, tls.caFile)) : undefined,
+    ]);
+    return Object.freeze({
+        key, cert,
+        ...(ca ? { ca } : {}),
+        ...(typeof tls.passphrase === 'string' ? { passphrase: tls.passphrase } : {}),
+        ...(minVersion ? { minVersion: minVersion } : {}),
+        ...(typeof tls.ciphers === 'string' && tls.ciphers ? { ciphers: tls.ciphers } : {}),
+    });
+}
+function parseTlsEnabled(value) {
+    return parseEnabled(value, 'http.tls.enabled');
+}
+function parseEnabled(value, field) {
+    if (value === undefined || value === true)
+        return true;
+    if (value === false)
+        return false;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', '1', 'on'].includes(normalized))
+            return true;
+        if (['false', '0', 'off', ''].includes(normalized))
+            return false;
+    }
+    throw new Error(`${field} must be a boolean`);
+}
+function resolveTlsPath(projectRoot, value) {
+    return isAbsolute(value) ? value : resolve(projectRoot, value);
+}
+export function installHttpHost(host) {
+    return ({ resources, admission }) => {
+        const port = host;
+        resources.provide(httpHostToken, bindGenerationAdmission(port, admission));
+    };
+}
+function parseScopedTokens(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tokens = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        if (typeof record.token !== 'string' || !record.token)
+            continue;
+        // `user` is an alias of `demo` (an ordinary Console user); anything but `full` is never the operator.
+        const scope = record.scope === 'full' ? 'full' : 'demo';
+        const principalId = typeof record.principalId === 'string' && record.principalId.trim() === record.principalId
+            && record.principalId.length > 0
+            ? record.principalId
+            : undefined;
+        const permissions = parseAccessList(record.permissions);
+        const roles = parseAccessList(record.roles);
+        tokens.push(Object.freeze({
+            token: record.token,
+            scope,
+            ...(principalId ? { principalId } : {}),
+            ...(permissions ? { permissions } : {}),
+            ...(roles ? { roles } : {}),
+        }));
+    }
+    return tokens.length > 0 ? Object.freeze(tokens) : undefined;
+}
+/** Console permissions / roles of a scoped token; blank or non-string entries are dropped. */
+function parseAccessList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const result = value
+        .filter((item) => typeof item === 'string')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return result.length > 0 ? Object.freeze([...new Set(result)]) : undefined;
+}
+function parseStringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const result = value.filter((item) => typeof item === 'string' && item.length > 0);
+    return result.length > 0 ? Object.freeze(result) : undefined;
+}
+async function readConfigDocument(config) {
+    if (!isConfigDocumentPort(config))
+        return config;
+    return (await config.read()).document;
+}
+function isConfigDocumentPort(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.read === 'function';
+}

package/lib/index.d.ts

@@ -10,3 +10,4 @@ export { dispatchPluginConsoleRpc } from './console-plugin-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';
 export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, } from './console-rpc-extended/index.js';
+export * from './host-installer.js';

package/lib/index.js

@@ -10,3 +10,4 @@ export { dispatchPluginConsoleRpc } from './console-plugin-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';
 export { dispatchExtendedConsoleRpc, } from './console-rpc-extended/index.js';
+export * from './host-installer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,11 +17,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.13",
+    "@zhin.js/console-protocol": "1.1.14",
     "@zhin.js/host-http-contract": "1.1.1",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/schedule": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.1.20"
+    "@zhin.js/schedule": "1.1.4",
+    "@zhin.js/plugin-runtime": "1.1.22"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",