@zhin.js/host-http 1.2.2 → 1.3.0

package/src/http-host.ts

@@ -30,8 +30,10 @@ import {
   authorizeConsoleHttp,
   authorizeConsoleWebSocket,
   requestMeta,
+  webSocketDenialReason,
   type ConsolePrincipal,
 } from './access-control.js';
+import type { ConsoleDenialReason } from '@zhin.js/console-protocol';
 import type { HttpHostAddress } from './host-options.js';
 
 export type { HttpHostAddress } from './host-options.js';
@@ -301,7 +303,7 @@ export function createHttpRouter(options: HttpRouterOptions = {}): HttpRouter {
       );
     if (!principal) return undefined;
     if (!authorizeConsoleWebSocket(principal, pathname)) {
-      audit(principal, remoteAddress, `ws:${pathname}`, 'denied');
+      audit(principal, remoteAddress, `ws:${pathname}`, 'denied', webSocketDenialReason(principal, pathname));
       return undefined;
     }
     return principal;
@@ -312,6 +314,7 @@ export function createHttpRouter(options: HttpRouterOptions = {}): HttpRouter {
     remoteAddress: string | undefined,
     action: string,
     outcome: 'ok' | 'denied' | 'error',
+    reason?: ConsoleDenialReason,
   ): void {
     const sink = tokenRegistry.accessProvider?.audit;
     if (!sink) return;
@@ -320,6 +323,7 @@ export function createHttpRouter(options: HttpRouterOptions = {}): HttpRouter {
         actor: auditActor(principal),
         action,
         outcome,
+        ...(reason ? { detail: { reason } } : {}),
         ...(remoteAddress ? { ip: remoteAddress } : {}),
       });
     } catch { /* audit never breaks a request */ }
@@ -508,7 +512,7 @@ export function createHttpRouter(options: HttpRouterOptions = {}): HttpRouter {
     const relative = pathname === apiBase ? '/' : pathname.slice(apiBase.length);
     const decision = authorizeConsoleHttp(principal, method, relative);
     if (!decision.allowed) {
-      if (principal) audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied');
+      if (principal) audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied', decision.reason);
       return { ok: false, status: decision.status, code: decision.code, error: decision.error };
     }
     return { ok: true, ...(principal ? { principal } : {}) };

package/src/index.ts

@@ -36,6 +36,11 @@ export {
   authorizeConsoleRpc,
   authorizeConsoleWebSocket,
   globalPermissions,
+  grantsDenialReason,
+  isAuditedRpcDenial,
+  unknownConsoleRpcError,
+  webSocketDenialReason,
+  type AuthorizeConsoleRpcOptions,
   isUserPrincipal,
   isExplicitConsolePrincipal,
   pluginRpcWriteAllowed,
@@ -93,6 +98,8 @@ export {
   type HttpResponseStream,
   type HttpResponseStreamOptions,
 } from '@zhin.js/host-http-contract';
+export { isRuntimeConsoleRpcType, RUNTIME_CONSOLE_RPC_TYPES } from './console-rpc-types.js';
+export { createUnknownRpcLog, unknownRpcLog, type UnknownRpcLog, type UnknownRpcLogEntry } from './unknown-rpc.js';
 export {
   dispatchRuntimeConsoleRpc,
   pickRpcReply,
@@ -106,6 +113,8 @@ export {
   type PluginUpdatePlan,
   type PluginManagementPort,
   type PluginManagementState,
+  type PluginInspectOptions,
+  type PluginDependencyCheck,
   type PluginVerificationResult,
   type PluginVerificationPlan,
   type PluginConfigValidation,
@@ -133,6 +142,7 @@ export {
   dispatchExtendedConsoleRpc,
   type ConsoleRpcExtendedCtx,
   type ConsoleScheduleEngine,
+  type ConsoleScheduleTarget,
   type ConsoleWorkroomProfileControlPort,
   type ConsoleWorkroomKnowledgeControlPort,
   type ExtendedRpcResult,

package/src/project-files.ts

@@ -27,7 +27,13 @@ export const FILE_MANAGER_ALLOWED = Object.freeze([
   'plugin.mjs',
   'plugin.cjs',
   'schema.json',
+  // Agent workspace bootstrap files (`@zhin.js/agent` bootstrap.ts, timer heartbeat) and the
+  // conventional knowledge base directory (`ai.knowledge.baseDir`).
   'AGENTS.md',
+  'SOUL.md',
+  'TOOLS.md',
+  'HEARTBEAT.md',
+  'knowledge',
   'tsconfig.json',
   'zhin.config.yml',
   'zhin.config.yaml',
@@ -35,16 +41,12 @@ export const FILE_MANAGER_ALLOWED = Object.freeze([
   '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',
@@ -58,10 +60,73 @@ export type FileTreeNode = {
   readonly children?: readonly FileTreeNode[];
 };
 
+/** Dotenv files the environment page (`/ops/env`, `env:*` RPCs) manages. */
+const ENV_FILE_NAMES = Object.freeze(['.env', '.env.development', '.env.production'] as const);
+
+/** Error text for project-file reads and writes that name a dotenv file (issue #1250). */
+export const DOTENV_ACCESS_DENIED_MESSAGE =
+  'Access denied: .env files are not available in the project file manager; '
+  + 'manage environment variables on the Environment variables page (/ops/env)';
+
+// Control characters (NUL included) never name a project file and can truncate a path in native code.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+
+/**
+ * Strips trailing dots and spaces (what Windows drops from a file name). A linear scan: the
+ * equivalent `/[. ]+$/` backtracks quadratically on long runs of spaces (CodeQL js/polynomial-redos).
+ */
+function trimTrailingDotsAndSpaces(value: string): string {
+  let end = value.length;
+  while (end > 0 && (value[end - 1] === '.' || value[end - 1] === ' ')) end -= 1;
+  return value.slice(0, end);
+}
+
+/**
+ * Whether one path segment names a dotenv file (`.env`, `.env.*`), in every spelling a
+ * filesystem may resolve to it: any letter case, trailing dots / spaces (stripped by Windows),
+ * an NTFS stream suffix (`.env::$DATA`) and percent-encoding.
+ */
+function isDotenvSegment(segment: string): boolean {
+  const variants = [segment];
+  try {
+    const decoded = decodeURIComponent(segment);
+    if (decoded !== segment) variants.push(decoded);
+  } catch { /* not percent-encoded */ }
+  return variants.some((variant) => {
+    const name = trimTrailingDotsAndSpaces(variant.split(':')[0]!).toLowerCase();
+    return name === '.env' || name.startsWith('.env.');
+  });
+}
+
+/**
+ * Whether a project-relative path names a dotenv file or goes through one. Dotenv files hold
+ * secrets: the project file manager never lists, reads or writes them (`/ops/env` does).
+ */
+export function isDotenvProjectPath(relativePath: string): boolean {
+  return relativePath.replace(/\\/gu, '/').split('/').some(isDotenvSegment);
+}
+
+/**
+ * Whether one path segment names a dot file or dot directory (`.envrc`, `.npmrc`, `.ssh`, …), also
+ * percent-encoded. Such files commonly hold credentials; no entry of {@link FILE_MANAGER_ALLOWED}
+ * is one, so the project file manager never reads or writes them (the tree already skips them).
+ */
+function isDotSegment(segment: string): boolean {
+  const variants = [segment];
+  try {
+    const decoded = decodeURIComponent(segment);
+    if (decoded !== segment) variants.push(decoded);
+  } catch { /* not percent-encoded */ }
+  return variants.some(variant => variant.startsWith('.') && variant !== '.');
+}
+
 export function isProjectPathAllowed(relativePath: string): boolean {
   if (relativePath.includes('..') || path.isAbsolute(relativePath)) return false;
+  if (CONTROL_CHARACTERS.test(relativePath) || isDotenvProjectPath(relativePath)) return false;
   const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\//u, '');
-  if (normalized.split('/').some((segment) => FILE_MANAGER_BLOCKED.has(segment))) return false;
+  const segments = normalized.split('/');
+  if (segments.some((segment) => FILE_MANAGER_BLOCKED.has(segment) || isDotSegment(segment))) return false;
   return FILE_MANAGER_ALLOWED.some(
     (allowed) => normalized === allowed || normalized.startsWith(`${allowed}/`),
   );
@@ -94,6 +159,7 @@ export async function readProjectFile(
   projectRoot: string,
   relativePath: string,
 ): Promise<{ content: string; size: number }> {
+  assertNotDotenv(relativePath);
   const absPath = await resolveAllowedPath(projectRoot, relativePath);
   if (!absPath) throw new Error(`Access denied: ${relativePath}`);
   if (!(await pathExists(absPath))) throw new Error(`File not found: ${relativePath}`);
@@ -111,6 +177,7 @@ export async function saveProjectFile(
   relativePath: string,
   content: string,
 ): Promise<void> {
+  assertNotDotenv(relativePath);
   const absPath = await resolveAllowedPath(projectRoot, relativePath);
   if (!absPath) throw new Error(`Access denied: ${relativePath}`);
   await mkdir(path.dirname(absPath), { recursive: true });
@@ -122,17 +189,34 @@ export async function saveProjectFile(
 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) => {
-    const resolved = await resolveAllowedPath(projectRoot, name);
+  const result = await Promise.all(ENV_FILE_NAMES.map(async (name) => {
+    const resolved = await resolveContainedPath(projectRoot, name, isEnvInventoryTarget);
     return { name, exists: resolved !== null && await pathExists(resolved) };
   }));
   return Object.freeze(result);
 }
 
+function assertNotDotenv(relativePath: string): void {
+  if (isDotenvProjectPath(relativePath)) throw new Error(DOTENV_ACCESS_DENIED_MESSAGE);
+}
+
+/** The env inventory only counts a dotenv file (or link) that stays inside the project and off blocked paths. */
+function isEnvInventoryTarget(relativePath: string): boolean {
+  if (!relativePath || relativePath.startsWith('..') || path.isAbsolute(relativePath)) return false;
+  return !relativePath.replace(/\\/gu, '/').split('/').some((segment) => FILE_MANAGER_BLOCKED.has(segment));
+}
+
+function resolveAllowedPath(projectRoot: string, relativePath: string): Promise<string | null> {
+  return resolveContainedPath(projectRoot, relativePath, isProjectPathAllowed);
+}
+
 /** Resolve existing links, or the nearest existing parent for a new file. */
-async function resolveAllowedPath(projectRoot: string, relativePath: string): Promise<string | null> {
-  if (!isProjectPathAllowed(relativePath)) return null;
+async function resolveContainedPath(
+  projectRoot: string,
+  relativePath: string,
+  allowed: (relativePath: string) => boolean,
+): Promise<string | null> {
+  if (!allowed(relativePath)) return null;
   try {
     const root = await realpath(projectRoot);
     let candidate = path.resolve(root, relativePath);
@@ -143,7 +227,7 @@ async function resolveAllowedPath(projectRoot: string, relativePath: string): Pr
         await lstat(candidate);
         const resolved = path.resolve(await realpath(candidate), ...missing);
         const relative = path.relative(root, resolved);
-        return isProjectPathAllowed(relative) ? resolved : null;
+        return allowed(relative) ? resolved : null;
       } catch (error) {
         if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return null;
         // lstat succeeds for dangling symlinks even though realpath fails.

package/src/unknown-rpc.ts

@@ -0,0 +1,44 @@
+/**
+ * Unknown Console RPC (zhinjs/zhin#1250): not a security refusal, so it is never audited. A
+ * Console that polls an RPC this Host lacks would otherwise fill the audit log; instead each type
+ * is logged at debug level at most once per window, with how often it was seen meanwhile.
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('console-rpc');
+const WINDOW_MS = 10 * 60_000;
+const MAX_TYPES = 256;
+
+interface Seen { at: number; suppressed: number }
+
+export interface UnknownRpcLog {
+  /** Records one unknown RPC; returns true when it was logged (not suppressed). */
+  note(type: unknown, now?: number): boolean;
+}
+
+export type UnknownRpcLogEntry = Readonly<{ op: 'console_rpc_unknown'; type: string; repeated?: number }>;
+
+export function createUnknownRpcLog(log: (entry: UnknownRpcLogEntry) => void = entry => logger.debug(formatCompact({ ...entry }))): UnknownRpcLog {
+  const seen = new Map<string, Seen>();
+  return Object.freeze({
+    note(type: unknown, now = Date.now()): boolean {
+      const name = String(type ?? '').slice(0, 64) || '<empty>';
+      const entry = seen.get(name);
+      if (entry && now - entry.at < WINDOW_MS) {
+        entry.suppressed += 1;
+        return false;
+      }
+      if (!entry && seen.size >= MAX_TYPES) {
+        const oldest = seen.keys().next().value;
+        if (oldest !== undefined) seen.delete(oldest);
+      }
+      seen.delete(name);
+      seen.set(name, { at: now, suppressed: 0 });
+      log({ op: 'console_rpc_unknown', type: name, ...(entry?.suppressed ? { repeated: entry.suppressed } : {}) });
+      return true;
+    },
+  });
+}
+
+/** Process-wide log shared by the Host's RPC routes. */
+export const unknownRpcLog: UnknownRpcLog = createUnknownRpcLog();