@zhin.js/host-http 1.0.0

package/lib/openapi.js

@@ -0,0 +1,136 @@
+export function patternToOpenApiPath(pattern) {
+    return pattern
+        .replace(/\/\*$/u, '/{path}')
+        .replace(/:([A-Za-z0-9_]+)\+/gu, '{$1}')
+        .replace(/\*([A-Za-z0-9_]+)/gu, '{$1}')
+        .replace(/:([A-Za-z0-9_]+)/gu, '{$1}');
+}
+export function routeRequiresBearerAuth(pathname, apiBase) {
+    if (pathname.startsWith('/pub/') || pathname === '/pub')
+        return false;
+    if (pathname.includes('/webhook'))
+        return false;
+    if (!pathname.startsWith(`${apiBase}/`) && pathname !== apiBase)
+        return false;
+    return true;
+}
+function defaultOperationId(method, pattern) {
+    const slug = pattern
+        .replace(/^\//u, '')
+        .replace(/[{}]/gu, '')
+        .replace(/[/:*]/gu, '_')
+        .replace(/[^a-zA-Z0-9_]/gu, '_')
+        .replace(/_+/gu, '_')
+        .replace(/^_|_$/gu, '');
+    return `${method.toLowerCase()}_${slug || 'root'}`;
+}
+function inferTag(pattern, apiBase) {
+    const rest = pattern.startsWith(`${apiBase}/`)
+        ? pattern.slice(apiBase.length + 1)
+        : pattern.replace(/^\//u, '');
+    const seg = rest.split('/')[0];
+    if (!seg || seg === 'pub')
+        return undefined;
+    if (seg === 'console')
+        return 'console';
+    return seg;
+}
+function buildOperation(route, apiBase) {
+    const { method, pattern, meta } = route;
+    const op = {
+        operationId: meta?.operationId ?? defaultOperationId(method, pattern),
+        summary: meta?.summary ?? `${method} ${pattern}`,
+        responses: {
+            '200': {
+                description: 'Success',
+                content: {
+                    'application/json': {
+                        schema: { type: 'object', additionalProperties: true },
+                    },
+                },
+            },
+        },
+    };
+    if (meta?.description)
+        op.description = meta.description;
+    if (meta?.deprecated)
+        op.deprecated = true;
+    const tags = meta?.tags?.length
+        ? [...meta.tags]
+        : [inferTag(pattern, apiBase)].filter(Boolean);
+    if (tags.length)
+        op.tags = tags;
+    if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+        op.requestBody = {
+            content: {
+                'application/json': {
+                    schema: { type: 'object', additionalProperties: true },
+                },
+            },
+        };
+    }
+    const pathParams = [...pattern.matchAll(/:([A-Za-z0-9_]+)/gu)].map((match) => ({
+        name: match[1],
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+    }));
+    if (pattern.endsWith('/*')) {
+        pathParams.push({
+            name: 'path',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+        });
+    }
+    const allParams = [...pathParams, ...(meta?.parameters ?? [])];
+    if (allParams.length)
+        op.parameters = allParams;
+    if (meta?.responses)
+        op.responses = meta.responses;
+    if (meta?.requestBody)
+        op.requestBody = meta.requestBody;
+    if (routeRequiresBearerAuth(pattern.replace(/\/\*$/u, ''), apiBase)
+        || routeRequiresBearerAuth(pattern, apiBase)) {
+        op.security = [{ bearerAuth: [] }];
+    }
+    return op;
+}
+export function buildOpenApiDocument(routes, options = {}) {
+    const apiBase = options.apiBase ?? '/api';
+    const paths = {};
+    const seen = new Set();
+    const sorted = [...routes].sort((left, right) => left.pattern.localeCompare(right.pattern)
+        || left.method.localeCompare(right.method));
+    for (const route of sorted) {
+        const key = `${route.method}\0${route.pattern}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const oaPath = patternToOpenApiPath(route.pattern);
+        if (!paths[oaPath])
+            paths[oaPath] = {};
+        paths[oaPath][route.method.toLowerCase()] = buildOperation(route, apiBase);
+    }
+    const doc = {
+        openapi: '3.1.0',
+        info: {
+            title: options.title ?? 'Zhin Plugin Runtime Host',
+            version: options.version ?? '0.0.0',
+            description: 'Runtime route catalog for @zhin.js/host-http. Register routes via HttpHost.route().',
+        },
+        paths,
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    description: 'Set `Authorization: Bearer <http.token>` for paths under the API base.',
+                },
+            },
+        },
+    };
+    if (options.serverUrl)
+        doc.servers = [{ url: options.serverUrl }];
+    return doc;
+}

package/lib/project-files.d.ts

@@ -0,0 +1,20 @@
+/** Align with Remote Console file manager (paths relative to project root). */
+export declare const FILE_MANAGER_ALLOWED: readonly string[];
+export declare const FILE_MANAGER_BLOCKED: Readonly<Set<string>>;
+export type FileTreeNode = {
+    readonly name: string;
+    readonly path: string;
+    readonly type: 'file' | 'directory';
+    readonly children?: readonly FileTreeNode[];
+};
+export declare function isProjectPathAllowed(relativePath: string): boolean;
+export declare function buildProjectFileTree(projectRoot: string): Promise<FileTreeNode[]>;
+export declare function readProjectFile(projectRoot: string, relativePath: string): Promise<{
+    content: string;
+    size: number;
+}>;
+export declare function saveProjectFile(projectRoot: string, relativePath: string, content: string): Promise<void>;
+export declare function listEnvFiles(projectRoot: string): Promise<readonly {
+    name: string;
+    exists: boolean;
+}[]>;

package/lib/project-files.js

@@ -0,0 +1,145 @@
+import { access, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/** Align with Remote Console file manager (paths relative to project root). */
+export const FILE_MANAGER_ALLOWED = Object.freeze([
+    'src',
+    'plugins',
+    'client',
+    'package.json',
+    'tsconfig.json',
+    'zhin.config.yml',
+    'config.yml',
+    'config.yaml',
+    'config.json',
+    '.env',
+    '.env.development',
+    '.env.production',
+    'README.md',
+]);
+export const FILE_MANAGER_BLOCKED = Object.freeze(new Set([
+    'node_modules',
+    '.git',
+    '.env.local',
+    'data',
+    'lib',
+    'dist',
+    'coverage',
+]));
+export function isProjectPathAllowed(relativePath) {
+    if (relativePath.includes('..') || path.isAbsolute(relativePath))
+        return false;
+    const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\//u, '');
+    const firstSegment = normalized.split('/')[0] ?? '';
+    if (FILE_MANAGER_BLOCKED.has(firstSegment))
+        return false;
+    return FILE_MANAGER_ALLOWED.some((allowed) => normalized === allowed || normalized.startsWith(`${allowed}/`));
+}
+export async function buildProjectFileTree(projectRoot) {
+    const tree = [];
+    for (const entry of FILE_MANAGER_ALLOWED) {
+        if (entry.includes('/'))
+            continue;
+        const absPath = path.resolve(projectRoot, entry);
+        if (!(await pathExists(absPath)))
+            continue;
+        const info = await safeStat(absPath);
+        if (!info)
+            continue;
+        if (info.isDirectory()) {
+            tree.push({
+                name: entry,
+                path: entry,
+                type: 'directory',
+                children: await buildDirectoryTree(projectRoot, entry, 3),
+            });
+        }
+        else if (info.isFile()) {
+            tree.push({ name: entry, path: entry, type: 'file' });
+        }
+    }
+    return tree.sort(compareTreeNodes);
+}
+export async function readProjectFile(projectRoot, relativePath) {
+    const absPath = resolveAllowedPath(projectRoot, relativePath);
+    if (!absPath)
+        throw new Error(`Access denied: ${relativePath}`);
+    if (!(await pathExists(absPath)))
+        throw new Error(`File not found: ${relativePath}`);
+    const info = await safeStat(absPath);
+    if (!info?.isFile())
+        throw new Error(`Not a file: ${relativePath}`);
+    if (info.size > 1024 * 1024) {
+        throw new Error(`File too large: ${(info.size / 1024).toFixed(0)}KB (max 1MB)`);
+    }
+    const content = await readFile(absPath, 'utf8');
+    return { content, size: info.size };
+}
+export async function saveProjectFile(projectRoot, relativePath, content) {
+    const absPath = resolveAllowedPath(projectRoot, relativePath);
+    if (!absPath)
+        throw new Error(`Access denied: ${relativePath}`);
+    await mkdir(path.dirname(absPath), { recursive: true });
+    await writeFile(absPath, content, 'utf8');
+}
+export async function listEnvFiles(projectRoot) {
+    const names = ['.env', '.env.development', '.env.production'];
+    const result = await Promise.all(names.map(async (name) => ({
+        name,
+        exists: await pathExists(path.resolve(projectRoot, name)),
+    })));
+    return Object.freeze(result);
+}
+function resolveAllowedPath(projectRoot, relativePath) {
+    if (!isProjectPathAllowed(relativePath))
+        return null;
+    return path.resolve(projectRoot, relativePath);
+}
+async function buildDirectoryTree(projectRoot, relativePath, maxDepth) {
+    if (maxDepth <= 0)
+        return [];
+    const absDir = path.resolve(projectRoot, relativePath);
+    const info = await safeStat(absDir);
+    if (!info?.isDirectory())
+        return [];
+    const entries = await readdir(absDir, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries) {
+        if (FILE_MANAGER_BLOCKED.has(entry.name) || entry.name.startsWith('.'))
+            continue;
+        const childRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            result.push({
+                name: entry.name,
+                path: childRelative,
+                type: 'directory',
+                children: await buildDirectoryTree(projectRoot, childRelative, maxDepth - 1),
+            });
+        }
+        else if (entry.isFile()) {
+            result.push({ name: entry.name, path: childRelative, type: 'file' });
+        }
+    }
+    return result.sort(compareTreeNodes);
+}
+function compareTreeNodes(a, b) {
+    if (a.type !== b.type)
+        return a.type === 'directory' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeStat(filePath) {
+    try {
+        return await stat(filePath);
+    }
+    catch {
+        return null;
+    }
+}

package/lib/timing-safe-equal.d.ts

@@ -0,0 +1,2 @@
+/** Constant-time string compare without Node `crypto` (portable). */
+export declare function timingSafeEqualString(a: string, b: string): boolean;

package/lib/timing-safe-equal.js

@@ -0,0 +1,10 @@
+/** Constant-time string compare without Node `crypto` (portable). */
+export function timingSafeEqualString(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let out = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        out |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return out === 0;
+}

package/lib/token-registry.d.ts

@@ -0,0 +1,20 @@
+/** Demo Host token scope (ADR 0016 subset for Plugin Runtime Host). */
+export type AuthScope = 'full' | 'demo';
+export type ScopedTokenConfig = {
+    readonly token: string;
+    readonly scope: AuthScope;
+};
+export type TokenRegistryConfig = {
+    readonly primaryToken?: string;
+    readonly scopedTokens?: readonly ScopedTokenConfig[];
+};
+export declare class TokenRegistry {
+    #private;
+    constructor(config?: TokenRegistryConfig);
+    resolve(token: string): AuthScope | null;
+    hasAnyToken(): boolean;
+    primaryTokenPrefixForLog(): string;
+}
+/** WebSocket upgrade paths allowed for demo scope. */
+export declare function isDemoWebSocketPath(pathname: string): boolean;
+export declare function extractBearerToken(authorization: string | undefined, queryToken: string | null): string;

package/lib/token-registry.js

@@ -0,0 +1,41 @@
+import { timingSafeEqualString } from './timing-safe-equal.js';
+export class TokenRegistry {
+    #entries = new Map();
+    constructor(config = {}) {
+        if (config.primaryToken)
+            this.#entries.set(config.primaryToken, 'full');
+        for (const { token, scope } of config.scopedTokens ?? []) {
+            if (token)
+                this.#entries.set(token, scope);
+        }
+    }
+    resolve(token) {
+        if (!token)
+            return null;
+        for (const [known, scope] of this.#entries) {
+            if (timingSafeEqualString(known, token))
+                return scope;
+        }
+        return null;
+    }
+    hasAnyToken() {
+        return this.#entries.size > 0;
+    }
+    primaryTokenPrefixForLog() {
+        for (const [tok, scope] of this.#entries) {
+            if (scope === 'full')
+                return tok.slice(0, 6);
+        }
+        const first = this.#entries.keys().next().value;
+        return first ? first.slice(0, 6) : '';
+    }
+}
+/** WebSocket upgrade paths allowed for demo scope. */
+export function isDemoWebSocketPath(pathname) {
+    return pathname === '/sandbox';
+}
+export function extractBearerToken(authorization, queryToken) {
+    if (authorization?.startsWith('Bearer '))
+        return authorization.slice(7).trim();
+    return queryToken?.trim() ?? '';
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@zhin.js/host-http",
+  "version": "1.0.0",
+  "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "ws": "^8.21.0",
+    "@zhin.js/logger": "1.0.74",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/host/http"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/host/http/tests"
+  }
+}