@zhin.js/host-http 1.2.2 → 1.4.0

package/lib/node/listener.js

@@ -7,13 +7,14 @@ import { createServer as createHttpServer, STATUS_CODES, } from 'node:http';
 import { createServer as createHttpsServer, } from 'node:https';
 import { WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { DEFAULT_HTTP_PORT } from '../port.js';
 import { compileTrustProxy, resolveClientAddress } from '../trust-proxy.js';
 import { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket } from './node-http.js';
 const logger = getLogger('http');
 /** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
 export function createNodeHttpListener(options) {
     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;
     let closed = false;

package/lib/port.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `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 declare const DEFAULT_HTTP_PORT = 8068;
+/** A whole `${VAR}` / `${VAR:-default}` reference (the form the config schema accepts for a port). */
+export declare const ENVIRONMENT_REFERENCE_PATTERN: RegExp;
+export declare class InvalidHttpPortError extends Error {
+    readonly field: string;
+    readonly value: unknown;
+    readonly reason: string;
+    constructor(field: string, value: unknown, reason: string);
+}
+/**
+ * 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 declare function describeInvalidPortValue(value: unknown): string | undefined;
+/**
+ * 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 declare function parseHttpPort(value: unknown, field: string, raw?: unknown): number | undefined;

package/lib/port.js

@@ -0,0 +1,68 @@
+/**
+ * `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 {
+    field;
+    value;
+    reason;
+    constructor(field, value, reason) {
+        super(`${field} 无效：${reason}`);
+        this.field = field;
+        this.value = value;
+        this.reason = reason;
+        this.name = 'InvalidHttpPortError';
+    }
+}
+function show(value) {
+    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) {
+    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, field, raw) {
+    if (value === undefined || value === null)
+        return undefined;
+    const fromReference = typeof raw === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(raw.trim()) ? `（来自 ${raw.trim()}）` : '';
+    let port;
+    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/lib/project-files.d.ts

@@ -7,6 +7,13 @@ export type FileTreeNode = {
     readonly type: 'file' | 'directory';
     readonly children?: readonly FileTreeNode[];
 };
+/** Error text for project-file reads and writes that name a dotenv file (issue #1250). */
+export declare const DOTENV_ACCESS_DENIED_MESSAGE: string;
+/**
+ * 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 declare function isDotenvProjectPath(relativePath: string): boolean;
 export declare function isProjectPathAllowed(relativePath: string): boolean;
 export declare function buildProjectFileTree(projectRoot: string): Promise<FileTreeNode[]>;
 export declare function readProjectFile(projectRoot: string, relativePath: string): Promise<{

package/lib/project-files.js

@@ -26,7 +26,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',
@@ -34,25 +40,82 @@ 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',
     'coverage',
 ]));
+/** Dotenv files the environment page (`/ops/env`, `env:*` RPCs) manages. */
+const ENV_FILE_NAMES = Object.freeze(['.env', '.env.development', '.env.production']);
+/** 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) {
+    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) {
+    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) {
+    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) {
+    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) {
     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)))
+    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}/`));
 }
@@ -84,6 +147,7 @@ export async function buildProjectFileTree(projectRoot) {
     return tree.sort(compareTreeNodes);
 }
 export async function readProjectFile(projectRoot, relativePath) {
+    assertNotDotenv(relativePath);
     const absPath = await resolveAllowedPath(projectRoot, relativePath);
     if (!absPath)
         throw new Error(`Access denied: ${relativePath}`);
@@ -99,6 +163,7 @@ export async function readProjectFile(projectRoot, relativePath) {
     return { content, size: info.size };
 }
 export async function saveProjectFile(projectRoot, relativePath, content) {
+    assertNotDotenv(relativePath);
     const absPath = await resolveAllowedPath(projectRoot, relativePath);
     if (!absPath)
         throw new Error(`Access denied: ${relativePath}`);
@@ -109,16 +174,28 @@ export async function saveProjectFile(projectRoot, relativePath, content) {
     await writeFile(checkedPath, content, 'utf8');
 }
 export async function listEnvFiles(projectRoot) {
-    const names = ['.env', '.env.development', '.env.production'];
-    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) {
+    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) {
+    if (!relativePath || relativePath.startsWith('..') || path.isAbsolute(relativePath))
+        return false;
+    return !relativePath.replace(/\\/gu, '/').split('/').some((segment) => FILE_MANAGER_BLOCKED.has(segment));
+}
+function resolveAllowedPath(projectRoot, relativePath) {
+    return resolveContainedPath(projectRoot, relativePath, isProjectPathAllowed);
+}
 /** Resolve existing links, or the nearest existing parent for a new file. */
-async function resolveAllowedPath(projectRoot, relativePath) {
-    if (!isProjectPathAllowed(relativePath))
+async function resolveContainedPath(projectRoot, relativePath, allowed) {
+    if (!allowed(relativePath))
         return null;
     try {
         const root = await realpath(projectRoot);
@@ -130,7 +207,7 @@ async function resolveAllowedPath(projectRoot, relativePath) {
                 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.code !== 'ENOENT')

package/lib/unknown-rpc.d.ts

@@ -0,0 +1,12 @@
+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 declare function createUnknownRpcLog(log?: (entry: UnknownRpcLogEntry) => void): UnknownRpcLog;
+/** Process-wide log shared by the Host's RPC routes. */
+export declare const unknownRpcLog: UnknownRpcLog;

package/lib/unknown-rpc.js

@@ -0,0 +1,33 @@
+/**
+ * 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;
+export function createUnknownRpcLog(log = entry => logger.debug(formatCompact({ ...entry }))) {
+    const seen = new Map();
+    return Object.freeze({
+        note(type, now = Date.now()) {
+            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 = createUnknownRpcLog();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -25,11 +25,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
+    "@zhin.js/console-protocol": "1.4.0",
     "@zhin.js/host-http-contract": "1.2.0",
-    "@zhin.js/logger": "1.1.3",
-    "@zhin.js/console-protocol": "1.2.2",
+    "@zhin.js/logger": "1.2.0",
     "@zhin.js/schedule": "1.1.5",
-    "@zhin.js/plugin-runtime": "1.2.1"
+    "@zhin.js/plugin-runtime": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/access-control.ts

@@ -1,12 +1,16 @@
 import {
+  CONSOLE_DENIAL_REASONS,
   CONSOLE_PERMISSION_LIST,
+  CONSOLE_UNKNOWN_RPC_CODE,
   CONSOLE_WRITE_PERMISSIONS,
   expandPluginPermissions,
   grantsAllow,
+  grantsAllowAlsoRequired,
   isPluginConsoleRpcType,
   resolveConsoleHttpPermission,
   resolveConsoleRpcPermission,
   resolveConsoleWsPermission,
+  type ConsoleDenialReason,
   type ConsoleGrant,
   type ConsolePermission,
   type ConsolePluginPermissionInfo,
@@ -84,6 +88,25 @@ export function isUserPrincipal(principal: ConsolePrincipal | undefined): princi
   return principal?.kind === 'user' || principal?.kind === 'api-token';
 }
 
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export const LOCAL_SOCKET_USER_ID = 'local';
+export const LOCAL_SOCKET_CREDENTIAL_ID = 'local-socket';
+
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export function isLocalSocketPrincipal(principal: ConsolePrincipal | undefined): boolean {
+  return principal?.kind === 'user' && principal.userId === LOCAL_SOCKET_USER_ID
+    && principal.credentialId === LOCAL_SOCKET_CREDENTIAL_ID;
+}
+
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export function isGlobalOwnerPrincipal(principal: ConsolePrincipal | undefined): boolean {
+  return isUserPrincipal(principal)
+    && principal.grants.some((grant) => grant.role === 'owner' && grant.scope.kind === 'global');
+}
+
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.
@@ -155,30 +178,98 @@ export type ConsoleRpcDecision =
        */
       delegated?: true;
     }>
-  | Readonly<{ allowed: false; code: 'setup_required' | 'unmapped' | 'forbidden'; error: string; permission: ConsolePermission | null }>;
+  | Readonly<{
+      allowed: false;
+      /**
+       * `unknown_rpc`: the Host has no handler and no permission entry for the type (zhinjs/zhin#1250).
+       * Nothing runs; it is not a security refusal and callers do not audit it (see
+       * {@link isAuditedRpcDenial}). Every other code is a refusal that is audited.
+       */
+      code: 'setup_required' | 'unmapped' | 'forbidden' | typeof CONSOLE_UNKNOWN_RPC_CODE;
+      error: string;
+      permission: ConsolePermission | null;
+      /** Audit `detail.reason`; absent for `unknown_rpc`. */
+      reason?: ConsoleDenialReason;
+    }>;
+
+export interface AuthorizeConsoleRpcOptions {
+  /**
+   * Whether this Host has a handler for an RPC type that is missing from the permission map. True
+   * (or no predicate) keeps the audited `unmapped` refusal — a handler without a permission entry
+   * is a development error; false answers `unknown_rpc`. Mapped types never consult it.
+   */
+  readonly registered?: (type: string) => boolean;
+}
+
+/** Whether a refused RPC is written to the audit log (`unknown_rpc` is not). */
+export function isAuditedRpcDenial(decision: ConsoleRpcDecision): boolean {
+  return !decision.allowed && decision.code !== CONSOLE_UNKNOWN_RPC_CODE;
+}
+
+/** Error text of an unknown RPC: the (truncated) type and nothing else. */
+export function unknownConsoleRpcError(type: unknown): string {
+  return `RPC "${String(type ?? '').slice(0, 64)}" 不存在`;
+}
 
 /** RPC authorization for one principal and message (deny by default). */
-export function authorizeConsoleRpc(principal: ConsolePrincipal, message: Readonly<Record<string, unknown>>): ConsoleRpcDecision {
+export function authorizeConsoleRpc(
+  principal: ConsolePrincipal,
+  message: Readonly<Record<string, unknown>>,
+  options: AuthorizeConsoleRpcOptions = {},
+): ConsoleRpcDecision {
   const rule = resolveConsoleRpcPermission(message.type, message);
   const permission = rule ? (rule.kind === 'exact' ? rule.permission : rule.read) : null;
   if (principal.kind === 'bootstrap') {
     if (principal.open) {
       return Object.freeze({ allowed: true, rule, permission, write: rule ? isWriteRule(rule) : true });
     }
-    return Object.freeze({ allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission });
+    return Object.freeze({
+      allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission,
+      reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED,
+    });
   }
   if (!rule) {
-    return Object.freeze({ allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null });
+    const type = typeof message.type === 'string' ? message.type : '';
+    if (options.registered && !options.registered(type)) {
+      return Object.freeze({ allowed: false, code: CONSOLE_UNKNOWN_RPC_CODE, error: unknownConsoleRpcError(message.type), permission: null });
+    }
+    return Object.freeze({
+      allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null,
+      reason: CONSOLE_DENIAL_REASONS.UNMAPPED_PERMISSION,
+    });
   }
   if (isPluginConsoleRpcType(message.type)) {
     return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule), delegated: true });
   }
   if (!grantsAllow(principal.grants, permission!, rule.target)) {
-    return Object.freeze({ allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission });
+    return Object.freeze({
+      allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission,
+      reason: grantsDenialReason(principal.grants, permission!),
+    });
+  }
+  // `alsoRequires` is held globally (same semantics as grantsAllowAlsoRequired): find the first missing one for the denial reason.
+  const missing = rule.kind === 'exact' && !grantsAllowAlsoRequired(principal.grants, rule)
+    ? rule.alsoRequires?.find(extra => !grantsAllowAlsoRequired(principal.grants, { ...rule, alsoRequires: [extra] }))
+    : undefined;
+  if (missing) {
+    return Object.freeze({
+      allowed: false, code: 'forbidden', error: `缺少权限 ${missing}`, permission,
+      reason: grantsDenialReason(principal.grants, missing),
+    });
   }
   return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule) });
 }
 
+/**
+ * Why grants refuse `permission` at a target: `scope_denied` when some binding holds it at another
+ * adapter / endpoint, else `insufficient_permission`.
+ */
+export function grantsDenialReason(grants: readonly ConsoleGrant[], permission: string): ConsoleDenialReason {
+  return grants.some(grant => grant.scope.kind !== 'global' && grant.permissions.includes(permission))
+    ? CONSOLE_DENIAL_REASONS.SCOPE_DENIED
+    : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
+
 function isWriteRule(rule: ConsoleRpcPermissionRule): boolean {
   return rule.kind === 'exact' ? CONSOLE_WRITE_PERMISSIONS.has(rule.permission) : false;
 }
@@ -192,12 +283,16 @@ export function pluginRpcWriteAllowed(principal: ConsolePrincipal, rule: Console
   if (principal.kind === 'bootstrap') return principal.open;
   if (!rule) return false;
   const permission = rule.kind === 'exact' ? rule.permission : rule.write;
-  return grantsAllow(principal.grants, permission, rule.target);
+  return grantsAllow(principal.grants, permission, rule.target) && grantsAllowAlsoRequired(principal.grants, rule);
 }
 
 export type ConsoleHttpDecision =
   | Readonly<{ allowed: true; permission: string | null }>
-  | Readonly<{ allowed: false; status: 401 | 403; code: 'unauthorized' | 'forbidden' | 'setup_required'; error: string; permission: string | null }>;
+  | Readonly<{
+      allowed: false; status: 401 | 403; code: 'unauthorized' | 'forbidden' | 'setup_required'; error: string; permission: string | null;
+      /** Audit `detail.reason`. */
+      reason: ConsoleDenialReason;
+    }>;
 
 /**
  * HTTP authorization of a route under the API base. `principal` is undefined when no valid
@@ -212,24 +307,35 @@ export function authorizeConsoleHttp(
   const permission = rule?.permission ?? null;
   if (rule?.permission === 'public') return Object.freeze({ allowed: true, permission });
   if (!principal) {
-    return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission });
+    return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission, reason: CONSOLE_DENIAL_REASONS.NOT_AUTHENTICATED });
   }
   if (principal.kind === 'bootstrap') {
     if (principal.open || rule?.permission === 'bootstrap') return Object.freeze({ allowed: true, permission });
-    return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission });
+    return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission, reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED });
   }
   if (!rule) {
-    return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null });
+    return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null, reason: CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE });
   }
   if (rule.permission === 'rpc' || rule.permission === 'authenticated' || rule.permission === 'bootstrap') {
     return Object.freeze({ allowed: true, permission });
   }
   // Scoped permissions over plain HTTP have no knowable target: a global binding is required.
   if (grantsAllow(principal.grants, rule.permission)) return Object.freeze({ allowed: true, permission });
-  return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission });
+  return Object.freeze({
+    allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission,
+    reason: CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION,
+  });
 }
 
 /** WebSocket upgrade authorization for non-bootstrap principals. */
+/** Audit `detail.reason` of a WebSocket {@link authorizeConsoleWebSocket} refused. */
+export function webSocketDenialReason(principal: ConsolePrincipal, pathname: string): ConsoleDenialReason {
+  if (principal.kind === 'bootstrap') return CONSOLE_DENIAL_REASONS.SETUP_REQUIRED;
+  return resolveConsoleWsPermission(pathname) === null
+    ? CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE
+    : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
+
 export function authorizeConsoleWebSocket(principal: ConsolePrincipal, pathname: string): boolean {
   // Only the Console's own sockets are host-authenticated; plugin sockets use `auth: 'protocol'`.
   const permission = resolveConsoleWsPermission(pathname);
@@ -317,9 +423,43 @@ export function rpcAuditDetail(
     type: String(message.type ?? '').slice(0, 256),
     keys: Object.freeze([...new Set([...keys, ...data])].slice(0, 64).map(key => key.slice(0, 128))),
     ...databaseStatementDetail(message, reply, options),
+    ...envDetail(message),
   }));
 }
 
+const auditName = (value: unknown, max: number): string | undefined =>
+  typeof value === 'string' && value ? value.slice(0, max) : undefined;
+
+/**
+ * Which dotenv file and variable names an `env:reveal` / `env:save` touched (issue #1250). Never a
+ * value: `changes[].value` and `content` are not read.
+ */
+function envDetail(message: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  if (message.type !== 'env:reveal' && message.type !== 'env:save') return {};
+  const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data) ? message.data as Record<string, unknown> : {};
+  const pick = (key: string) => message[key] ?? data[key];
+  const file = auditName(pick('filename'), 64);
+  if (message.type === 'env:reveal') {
+    const key = auditName(pick('key'), 128);
+    return { ...(file ? { file } : {}), ...(key ? { key } : {}) };
+  }
+  const changes = Array.isArray(pick('changes')) ? pick('changes') as unknown[] : undefined;
+  if (!changes) return { ...(file ? { file } : {}), ...(pick('content') !== undefined ? { mode: 'replace' } : {}) };
+  const set: string[] = [];
+  const deleted: string[] = [];
+  for (const change of changes.slice(0, 64)) {
+    if (!change || typeof change !== 'object') continue;
+    const key = auditName((change as Record<string, unknown>).key, 128);
+    if (key) ((change as Record<string, unknown>).delete === true ? deleted : set).push(key);
+  }
+  return {
+    ...(file ? { file } : {}),
+    set: Object.freeze(set),
+    deleted: Object.freeze(deleted),
+    ...(changes.length > 64 ? { truncated: true } : {}),
+  };
+}
+
 export function rpcAuditTarget(rule: ConsoleRpcPermissionRule | null): string | undefined {
   if (!rule) return undefined;
   const target = rule.target;