@zhin.js/host-http 1.0.0

package/src/openapi.ts

@@ -0,0 +1,172 @@
+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 function patternToOpenApiPath(pattern: string): string {
+  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: string, apiBase: string): boolean {
+  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: string, pattern: string): string {
+  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: string, apiBase: string): string | undefined {
+  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: ListedRoute, apiBase: string): Record<string, unknown> {
+  const { method, pattern, meta } = route;
+  const op: Record<string, unknown> = {
+    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' as const,
+    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: readonly ListedRoute[],
+  options: BuildOpenApiOptions = {},
+): Record<string, unknown> {
+  const apiBase = options.apiBase ?? '/api';
+  const paths: Record<string, Record<string, unknown>> = {};
+  const seen = new Set<string>();
+  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: Record<string, unknown> = {
+    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/src/project-files.ts

@@ -0,0 +1,161 @@
+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 type FileTreeNode = {
+  readonly name: string;
+  readonly path: string;
+  readonly type: 'file' | 'directory';
+  readonly children?: readonly FileTreeNode[];
+};
+
+export function isProjectPathAllowed(relativePath: string): boolean {
+  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: string): Promise<FileTreeNode[]> {
+  const tree: FileTreeNode[] = [];
+  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: string,
+  relativePath: string,
+): Promise<{ content: string; size: number }> {
+  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: string,
+  relativePath: string,
+  content: string,
+): Promise<void> {
+  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: string,
+): Promise<readonly { name: string; exists: boolean }[]> {
+  const names = ['.env', '.env.development', '.env.production'] as const;
+  const result = await Promise.all(names.map(async (name) => ({
+    name,
+    exists: await pathExists(path.resolve(projectRoot, name)),
+  })));
+  return Object.freeze(result);
+}
+
+function resolveAllowedPath(projectRoot: string, relativePath: string): string | null {
+  if (!isProjectPathAllowed(relativePath)) return null;
+  return path.resolve(projectRoot, relativePath);
+}
+
+async function buildDirectoryTree(
+  projectRoot: string,
+  relativePath: string,
+  maxDepth: number,
+): Promise<FileTreeNode[]> {
+  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: FileTreeNode[] = [];
+  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: FileTreeNode, b: FileTreeNode): number {
+  if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeStat(filePath: string) {
+  try {
+    return await stat(filePath);
+  } catch {
+    return null;
+  }
+}

package/src/timing-safe-equal.ts

@@ -0,0 +1,9 @@
+/** Constant-time string compare without Node `crypto` (portable). */
+export function timingSafeEqualString(a: string, b: string): boolean {
+  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/src/token-registry.ts

@@ -0,0 +1,58 @@
+import { timingSafeEqualString } from './timing-safe-equal.js';
+
+/** 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 class TokenRegistry {
+  readonly #entries = new Map<string, AuthScope>();
+
+  constructor(config: TokenRegistryConfig = {}) {
+    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: string): AuthScope | null {
+    if (!token) return null;
+    for (const [known, scope] of this.#entries) {
+      if (timingSafeEqualString(known, token)) return scope;
+    }
+    return null;
+  }
+
+  hasAnyToken(): boolean {
+    return this.#entries.size > 0;
+  }
+
+  primaryTokenPrefixForLog(): string {
+    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: string): boolean {
+  return pathname === '/sandbox';
+}
+
+export function extractBearerToken(
+  authorization: string | undefined,
+  queryToken: string | null,
+): string {
+  if (authorization?.startsWith('Bearer ')) return authorization.slice(7).trim();
+  return queryToken?.trim() ?? '';
+}