@zhin.js/host-http 1.2.2 → 1.4.0

package/src/console-rpc-types.ts

@@ -0,0 +1,45 @@
+/**
+ * RPC types the runtime Console dispatcher of this package answers (`dispatchRuntimeConsoleRpc`:
+ * shell, configuration, plugin management, project files / environment / database, endpoints,
+ * schedules, inbox, login assist, workrooms). Used to tell an RPC this Host has but forgot to map
+ * (audited `unmapped`) from one it does not have at all (`unknown_rpc`, zhinjs/zhin#1250), and to
+ * build the Host's capability list. `console-rpc-types.test.ts` keeps it in step with the
+ * dispatchers' `case` labels.
+ */
+import { CONFIG_RPC, ENDPOINT_RPC, PLUGIN_RPC } from '@zhin.js/console-protocol';
+
+export const RUNTIME_CONSOLE_RPC_TYPES: ReadonlySet<string> = new Set<string>([
+  // Shell
+  'ping', 'entries:get', 'pages:list',
+  // Configuration
+  ...Object.values(CONFIG_RPC),
+  'workrooms:get', 'workrooms:set',
+  // Plugin management (the global switch is refused with a pointer to the gateway)
+  ...Object.values(PLUGIN_RPC),
+  // Project files / environment / schemas / database / process
+  'files:tree', 'files:read', 'files:save',
+  'env:list', 'env:get', 'env:reveal', 'env:save',
+  'schema:get', 'schema:get-all',
+  'db:info', 'db:tables', 'db:select', 'db:query', 'db:execute',
+  'db:schema:describe', 'db:schema:preview', 'db:schema:apply',
+  'db:insert', 'db:update', 'db:delete', 'db:drop-table',
+  'db:kv:get', 'db:kv:set', 'db:kv:delete', 'db:kv:entries',
+  'system:restart',
+  // Endpoints
+  ...Object.values(ENDPOINT_RPC),
+  // Schedules
+  'schedule:list', 'cron:list', 'cron:validate', 'cron:add', 'cron:remove', 'cron:pause', 'cron:resume',
+  // Requests / notices / inbox
+  'request.list', 'request.approve', 'request.reject', 'request.consumed', 'notice.consumed',
+  'inbox.requests', 'inbox.notices', 'inbox.messages', 'inbox.recent',
+  // Login assist
+  'login.list', 'login.submit', 'login.cancel', 'login.flow.list', 'login.flow.get', 'login.relogin', 'login.refresh',
+  // Workroom profiles / knowledge
+  'workroom.profile.status', 'workroom.profile.bootstrap', 'workroom.profile.pack.publish',
+  'workroom.profile.publish', 'workroom.profile.rollback', 'workroom.profile.policy.publish',
+  'workroom.knowledge.get', 'workroom.knowledge.publish', 'workroom.knowledge.rollback',
+]);
+
+export function isRuntimeConsoleRpcType(type: unknown): type is string {
+  return typeof type === 'string' && RUNTIME_CONSOLE_RPC_TYPES.has(type);
+}

package/src/console-rpc.ts

@@ -3,6 +3,7 @@ import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
 import {
   CONFIG_PATCH_LIMITS,
   CONFIG_RPC,
+  CONSOLE_UNKNOWN_RPC_CODE,
   grantsAllow,
   type ConsoleConfigPatchRequest,
   type ConsoleConfigPatchResult,
@@ -12,6 +13,7 @@ import {
   type ConsoleEndpointSummary,
 } from '@zhin.js/console-protocol';
 import { authorizeConsoleRpc, principalAllows, type ConsolePrincipal } from './access-control.js';
+import { isRuntimeConsoleRpcType } from './console-rpc-types.js';
 import { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import {
@@ -128,9 +130,21 @@ export interface PluginVerificationResult {
   readonly evidenceI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['evidenceI18n'];
 }
 
+/** `inspect` options. `dependencies: 'skip'` leaves the project-wide graph check out (`dependencies: 'unchecked'`). */
+export interface PluginInspectOptions {
+  readonly dependencies?: 'check' | 'skip';
+}
+
+/** Result of the project-wide dependency graph check (the same check `inspect` runs per plugin). */
+export type PluginDependencyCheck =
+  | { readonly status: 'passed' }
+  | { readonly status: 'failed'; readonly error: string };
+
 export interface PluginManagementPort {
   explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
-  inspect?(packageName: string): Promise<PluginManagementState>;
+  inspect?(packageName: string, options?: PluginInspectOptions): Promise<PluginManagementState>;
+  /** Runs the project-wide dependency graph check once, for callers that inspect many plugins. */
+  checkDependencies?(): Promise<PluginDependencyCheck>;
   apply?(packageName: string, expectedProjectRevision?: string): Promise<{ readonly requested: boolean; readonly state: PluginManagementState }>;
   verificationPlan?(packageName: string): Promise<PluginVerificationPlan>;
   verify?(packageName: string, checkId: string, expectedGeneration: number | null, expectedProjectRevision: string, expectedCheckRevision: string): Promise<PluginVerificationResult>;
@@ -209,8 +223,21 @@ export type RuntimeConsoleRpcContext = {
   readProjectFile?(filePath: string): Promise<{ content: string; size: number }>;
   saveProjectFile?(filePath: string, content: string): Promise<void>;
   listEnvFiles?(): Promise<readonly { name: string; exists: boolean }[]>;
+  /**
+   * @deprecated Not used any more: `env:get` answers {@link readEnvFileView} only, so the file as
+   * written never reaches the Console (issue #1250).
+   */
   readEnvFile?(filename: string): Promise<string>;
+  /** @deprecated Not used any more: `env:save` writes through {@link updateEnvVariables} / {@link replaceEnvFile}. */
   writeEnvFile?(filename: string, content: string): Promise<void>;
+  /** `env:get`: masked view (key names, masks, lengths; comments and blank lines in place). */
+  readEnvFileView?(filename: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvFileView>;
+  /** `env:reveal`: one variable as written. The route requires `ops.env.write` + `ops.env.read` and audits. */
+  revealEnvVariable?(filename: string, key: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvRevealResult>;
+  /** `env:save { changes }`: validates and writes only the named keys (mask placeholders refused). */
+  updateEnvVariables?(filename: string, changes: unknown): Promise<{ readonly changed: readonly string[] }>;
+  /** `env:save { content, mode: 'replace' }`: whole file; refused when it holds mask placeholders. */
+  replaceEnvFile?(filename: string, content: string): Promise<void>;
   /** Optional schema accessors (plugin schema.json / Runtime schema registry). */
   getSchema?(pluginName?: string): Promise<unknown>;
   getAllSchemas?(): Promise<Record<string, unknown>>;
@@ -288,9 +315,9 @@ export async function dispatchRuntimeConsoleRpc(
   let canOperateEndpoint: ConsoleRpcExtendedCtx['canOperateEndpoint'];
   if (ctx.principal) {
     const principal = ctx.principal;
-    const decision = authorizeConsoleRpc(principal, message as Record<string, unknown>);
+    const decision = authorizeConsoleRpc(principal, message as Record<string, unknown>, { registered: isRuntimeConsoleRpcType });
     if (!decision.allowed) {
-      emit({ requestId, error: decision.error, code: decision.code });
+      emit({ requestId, error: decision.error, code: decision.code, ...(decision.reason ? { reason: decision.reason } : {}) });
       return payloads;
     }
     authorizedEndpoint = scopedAuthorizedEndpoint(principal, decision);
@@ -507,7 +534,11 @@ export async function dispatchRuntimeConsoleRpc(
     case CONFIG_RPC.PATCH: {
       if (ctx.authScope !== 'full') { emit({ requestId, error: 'Full scope required' }); return payloads; }
       const projectPatch = message.type === CONFIG_RPC.PATCH_PROJECT;
-      const { instanceKey, expectedRevision, patches } = message;
+      const { instanceKey, expectedRevision, patches, secretStorage } = message;
+      if (secretStorage !== undefined && secretStorage !== 'env' && secretStorage !== 'plain') {
+        emit({ requestId, error: 'secretStorage 只能是 env 或 plain' });
+        return payloads;
+      }
       if (projectPatch && instanceKey !== undefined) {
         emit({ requestId, error: 'Project patches must not specify instanceKey' });
         return payloads;
@@ -539,6 +570,7 @@ export async function dispatchRuntimeConsoleRpc(
           ...(instanceKey === undefined ? {} : { instanceKey }),
           expectedRevision,
           patches,
+          ...(secretStorage === undefined ? {} : { secretStorage }),
         });
       } catch (error) {
         emit({
@@ -600,9 +632,11 @@ export async function dispatchRuntimeConsoleRpc(
           },
         });
       } catch (error) {
+        const code = error instanceof Error && 'code' in error && error.code === 'env-write-required' ? { code: 'env-write-required' } : {};
         emit({
           requestId,
           error: `Failed to set config: ${error instanceof Error ? error.message : String(error)}`,
+          ...code,
         });
       }
       return payloads;
@@ -618,7 +652,7 @@ export async function dispatchRuntimeConsoleRpc(
         });
         return payloads;
       }
-      emit({ requestId, error: `Unknown RPC type: ${type || '<empty>'}` });
+      emit({ requestId, error: `Unknown RPC type: ${type.slice(0, 64) || '<empty>'}`, code: CONSOLE_UNKNOWN_RPC_CODE });
       return payloads;
     }
   }

package/src/host-installer.ts

@@ -11,6 +11,7 @@ import { isAbsolute, resolve } from 'node:path';
 import { httpHostToken, type HttpHost } from './http-host.js';
 import type { HttpHostOptions } from './host-options.js';
 import { parseTrustProxy } from './trust-proxy.js';
+import { parseHttpPort } from './port.js';
 
 export interface ResolvedHttpConfig extends HttpHostOptions {
   /** Additional listeners that mirror the primary Host route surface. */
@@ -30,17 +31,19 @@ export async function resolveHttpConfig(
     http,
     (key) => envOverlay?.[key] ?? process.env[key],
   ) as Record<string, unknown>;
+  const stored = http as Record<string, unknown>;
   if (value.tokens !== undefined && value.tokens !== null) throw new Error(HTTP_TOKENS_REMOVED_MESSAGE);
   const primary: HttpHostOptions = Object.freeze({
     host: typeof value.host === 'string' ? value.host : undefined,
-    port: typeof value.port === 'number' ? value.port : undefined,
+    // An invalid port is an error, never a silent fallback to the default (#1250).
+    port: parseHttpPort(value.port, 'http.port', stored.port),
     token: typeof value.token === 'string' ? value.token : undefined,
     corsOrigins: injectDesktopWebviewOrigins(parseStringList(value.corsOrigins), envOverlay),
     apiBase: typeof value.base === 'string' ? value.base : undefined,
     tls: await parseTlsConfig(value.tls, projectRoot),
     trustProxy: parseTrustProxy(value.trustProxy),
   });
-  const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot);
+  const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot, stored.listeners);
   const listeners = await injectDesktopDeviceListener(
     configuredListeners,
     primary,
@@ -110,6 +113,7 @@ async function parseAdditionalListeners(
   value: unknown,
   primary: HttpHostOptions,
   projectRoot: string,
+  stored?: unknown,
 ): Promise<readonly HttpHostOptions[]> {
   if (value === undefined) return Object.freeze([]);
   if (!Array.isArray(value)) throw new Error('http.listeners must be an array');
@@ -123,13 +127,15 @@ async function parseAdditionalListeners(
     if (typeof listener.host !== 'string' || !listener.host) {
       throw new Error(`http.listeners[${index}].host is required`);
     }
-    if (typeof listener.port !== 'number') {
+    const storedPort = Array.isArray(stored) ? (stored[index] as Record<string, unknown> | undefined)?.port : undefined;
+    const port = parseHttpPort(listener.port, `http.listeners[${index}].port`, storedPort);
+    if (port === undefined) {
       throw new Error(`http.listeners[${index}].port is required`);
     }
     listeners.push(Object.freeze({
       ...primary,
       host: listener.host,
-      port: listener.port,
+      port,
       tls: await parseTlsConfig(listener.tls, projectRoot),
     }));
   }

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

@@ -20,6 +20,13 @@ export {
 } from './http-host.js';
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
+export {
+  DEFAULT_HTTP_PORT,
+  ENVIRONMENT_REFERENCE_PATTERN,
+  InvalidHttpPortError,
+  describeInvalidPortValue,
+  parseHttpPort,
+} from './port.js';
 export {
   TokenRegistry,
   extractBearerToken,
@@ -36,8 +43,17 @@ export {
   authorizeConsoleRpc,
   authorizeConsoleWebSocket,
   globalPermissions,
+  grantsDenialReason,
+  isAuditedRpcDenial,
+  unknownConsoleRpcError,
+  webSocketDenialReason,
+  type AuthorizeConsoleRpcOptions,
   isUserPrincipal,
   isExplicitConsolePrincipal,
+  isGlobalOwnerPrincipal,
+  isLocalSocketPrincipal,
+  LOCAL_SOCKET_CREDENTIAL_ID,
+  LOCAL_SOCKET_USER_ID,
   pluginRpcWriteAllowed,
   principalAllows,
   requestMeta,
@@ -93,6 +109,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 +124,8 @@ export {
   type PluginUpdatePlan,
   type PluginManagementPort,
   type PluginManagementState,
+  type PluginInspectOptions,
+  type PluginDependencyCheck,
   type PluginVerificationResult,
   type PluginVerificationPlan,
   type PluginConfigValidation,
@@ -133,6 +153,7 @@ export {
   dispatchExtendedConsoleRpc,
   type ConsoleRpcExtendedCtx,
   type ConsoleScheduleEngine,
+  type ConsoleScheduleTarget,
   type ConsoleWorkroomProfileControlPort,
   type ConsoleWorkroomKnowledgeControlPort,
   type ExtendedRpcResult,

package/src/node/listener.ts

@@ -21,6 +21,7 @@ import { WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { HttpRequestInfo, WsUpgradeDecision, WsUpgradeRequest } from '../http-host.js';
 import type { HttpHostAddress, HttpHostTlsOptions } from '../host-options.js';
+import { DEFAULT_HTTP_PORT } from '../port.js';
 import { compileTrustProxy, resolveClientAddress, type TrustProxySetting } from '../trust-proxy.js';
 import { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket } from './node-http.js';
 
@@ -52,7 +53,7 @@ export interface NodeHttpListener {
 /** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
 export function createNodeHttpListener(options: NodeHttpListenerOptions): NodeHttpListener {
   const host = options.host ?? '127.0.0.1';
-  const port = options.port ?? 8086;
+  const port = options.port ?? DEFAULT_HTTP_PORT;
   const secure = options.tls !== undefined;
   let address: HttpHostAddress | undefined;
   let closed = false;

package/src/port.ts

@@ -0,0 +1,60 @@
+/**
+ * `http.port` (and `http.listeners[].port`): an integer from 1 to 65535, written either as a number
+ * or as a `${VAR}` environment reference that expands to one (#1250); `0` keeps its listener meaning
+ * (the system picks a free port — tests and embedded use). Anything else is a configuration error:
+ * the Host never falls back to the default port for an invalid value.
+ */
+
+/** Port the Host listens on when `http.port` is not configured (same as the scaffold writes). */
+export const DEFAULT_HTTP_PORT = 8068;
+
+/** A whole `${VAR}` / `${VAR:-default}` reference (the form the config schema accepts for a port). */
+export const ENVIRONMENT_REFERENCE_PATTERN = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(?::[-=][^}]*)?\}$/u;
+
+export class InvalidHttpPortError extends Error {
+  constructor(readonly field: string, readonly value: unknown, readonly reason: string) {
+    super(`${field} 无效：${reason}`);
+    this.name = 'InvalidHttpPortError';
+  }
+}
+
+function show(value: unknown): string {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
+/**
+ * Why a stored (unexpanded) port value is invalid, in Chinese; undefined when it is valid.
+ * `undefined` / `null` (not configured) are valid; `${VAR}` references are checked after expansion.
+ */
+export function describeInvalidPortValue(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value)) return `端口必须是整数，当前值 ${value}`;
+    if (value < 0 || value > 65_535) return `端口必须在 1–65535 之间，当前值 ${value}`;
+    return undefined;
+  }
+  if (typeof value === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(value.trim())) return undefined;
+  return `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}`;
+}
+
+/**
+ * The listening port from an expanded config value (`${VAR}` already replaced: a digit string is
+ * accepted). Returns undefined when not configured; throws {@link InvalidHttpPortError} otherwise.
+ * `raw` is the stored value, named in the message when it was an environment reference.
+ */
+export function parseHttpPort(value: unknown, field: string, raw?: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const fromReference = typeof raw === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(raw.trim()) ? `（来自 ${raw.trim()}）` : '';
+  let port: number;
+  if (typeof value === 'number') port = value;
+  else if (typeof value === 'string' && /^\d+$/u.test(value.trim())) port = Number(value.trim());
+  else if (typeof value === 'string' && value.trim() === '' && fromReference) {
+    throw new InvalidHttpPortError(field, value, `环境变量未设置或为空${fromReference}；请在 .env 中设置为 1–65535 的整数`);
+  } else {
+    throw new InvalidHttpPortError(field, value, `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}${fromReference}`);
+  }
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new InvalidHttpPortError(field, value, `端口必须在 1–65535 之间，当前值 ${show(value)}${fromReference}`);
+  }
+  return port;
+}

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();