@zhin.js/host-http 1.2.1 → 1.3.0

package/lib/http-host.js

@@ -12,7 +12,7 @@ import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime
 import { HttpBodyError, jsonResponse } from '@zhin.js/host-http-contract';
 import { TokenRegistry, extractBearerToken, } from './token-registry.js';
 import { buildOpenApiDocument, } from './openapi.js';
-import { auditActor, authorizeConsoleHttp, authorizeConsoleWebSocket, requestMeta, } from './access-control.js';
+import { auditActor, authorizeConsoleHttp, authorizeConsoleWebSocket, requestMeta, webSocketDenialReason, } from './access-control.js';
 const logger = getLogger('http');
 export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
 const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
@@ -85,12 +85,12 @@ export function createHttpRouter(options = {}) {
         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;
     }
-    function audit(principal, remoteAddress, action, outcome) {
+    function audit(principal, remoteAddress, action, outcome, reason) {
         const sink = tokenRegistry.accessProvider?.audit;
         if (!sink)
             return;
@@ -99,6 +99,7 @@ export function createHttpRouter(options = {}) {
                 actor: auditActor(principal),
                 action,
                 outcome,
+                ...(reason ? { detail: { reason } } : {}),
                 ...(remoteAddress ? { ip: remoteAddress } : {}),
             });
         }
@@ -282,7 +283,7 @@ export function createHttpRouter(options = {}) {
         const decision = authorizeConsoleHttp(principal, method, relative);
         if (!decision.allowed) {
             if (principal)
-                audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied');
+                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/lib/index.d.ts

@@ -2,7 +2,7 @@ export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN,
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type TokenRegistryConfig, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, type AuthorizeConsoleRpcOptions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type RpcAuditOptions, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken, type ProtocolAuthRequest } from './protocol-auth.js';
 export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, type TrustProxyPredicate, type TrustProxySetting, } from './trust-proxy.js';
@@ -10,9 +10,11 @@ export { createConsoleEventHub, consoleEventHubToken, type ConsoleEventHub, } fr
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, type BuildOpenApiOptions, type ListedRoute, type OpenApiParameter, type RouteMeta, } from './openapi.js';
 export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, type HttpBodyReadOptions, } from './json-body.js';
 export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, type HttpResponseStream, type HttpResponseStreamOptions, } from '@zhin.js/host-http-contract';
-export { dispatchRuntimeConsoleRpc, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
+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, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginInspectOptions, type PluginDependencyCheck, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, type FileTreeNode, } from './project-files.js';
 export { registerConsoleRestPages, type ConsoleAgentIntrospection, type ConsoleAgentRuntime, type ConsoleAgentSessionTree, type ConsoleRestCtx, type ConsoleRestPagesOptions, } from './console-rest-pages.js';
-export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, } from './console-rpc-extended/index.js';
+export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleScheduleTarget, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, type ConsoleLoginAssistPort, type ConsoleEndpointLoginAccess, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
 export * from './host-installer.js';

package/lib/index.js

@@ -1,7 +1,7 @@
 export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
 export { listHttpHostAddresses } from './addresses.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken } from './protocol-auth.js';
 export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, } from './trust-proxy.js';
@@ -9,9 +9,11 @@ export { createConsoleEventHub, consoleEventHubToken, } from './console-events.j
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, } from './openapi.js';
 export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, } from './json-body.js';
 export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, } from '@zhin.js/host-http-contract';
+export { isRuntimeConsoleRpcType, RUNTIME_CONSOLE_RPC_TYPES } from './console-rpc-types.js';
+export { createUnknownRpcLog, unknownRpcLog } from './unknown-rpc.js';
 export { dispatchRuntimeConsoleRpc, pickRpcReply, } from './console-rpc.js';
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, } from './project-files.js';
 export { registerConsoleRestPages, } from './console-rest-pages.js';
-export { dispatchExtendedConsoleRpc, } from './console-rpc-extended/index.js';
+export { dispatchExtendedConsoleRpc, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
 export * from './host-installer.js';

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.1",
+  "version": "1.3.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.2.1",
     "@zhin.js/host-http-contract": "1.2.0",
+    "@zhin.js/console-protocol": "1.3.0",
     "@zhin.js/logger": "1.1.3",
     "@zhin.js/schedule": "1.1.5",
-    "@zhin.js/plugin-runtime": "1.2.0"
+    "@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,
@@ -155,30 +159,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 +264,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 +288,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);
@@ -237,13 +324,121 @@ export function authorizeConsoleWebSocket(principal: ConsolePrincipal, pathname:
   return permission !== null && grantsAllow(principal.grants, permission);
 }
 
-/** Audit detail for an RPC: type, target and parameter key names only. */
-export function rpcAuditDetail(message: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> {
+/**
+ * JSON length of the detail of one audit entry. The gateway stores at most 4096 characters of
+ * JSON detail; statements are cut so the whole detail stays below this budget once serialised
+ * (escapes such as `\n` count twice), so the stored detail always parses.
+ */
+export const AUDIT_DETAIL_JSON_LIMIT = 3_500;
+
+export interface RpcAuditOptions {
+  /**
+   * Replaces literal values in SQL text (`'…'`) before it is recorded, with the dialect's own
+   * lexing (the database Host's `redactSql`). Without it no statement text is recorded at all.
+   */
+  readonly redactSql?: (sql: string) => string;
+}
+
+function statementTexts(message: Readonly<Record<string, unknown>>, reply: Readonly<Record<string, unknown>> | undefined): string[] {
+  if (message.type === 'db:execute' || message.type === 'db:query') return typeof message.sql === 'string' && message.sql ? [message.sql] : [];
+  const data = reply?.data && typeof reply.data === 'object' ? reply.data as Record<string, unknown> : undefined;
+  return (Array.isArray(data?.statements) ? data.statements as unknown[] : []).filter((entry): entry is string => typeof entry === 'string' && !!entry);
+}
+
+/**
+ * Statement text of Console SQL (`db:query` / `db:execute`, the DDL `db:schema:apply` ran or
+ * would have run), literals redacted; result rows are never recorded.
+ */
+function databaseStatementDetail(
+  message: Readonly<Record<string, unknown>>,
+  reply: Readonly<Record<string, unknown>> | undefined,
+  options: RpcAuditOptions | undefined,
+): Record<string, unknown> {
+  if (message.type !== 'db:execute' && message.type !== 'db:query' && message.type !== 'db:schema:apply') return {};
+  const change = message.type === 'db:schema:apply' && message.change && typeof message.change === 'object' ? message.change as Record<string, unknown> : {};
+  const texts = statementTexts(message, reply);
+  const redact = options?.redactSql;
+  return {
+    ...(message.type === 'db:execute' && message.dryRun === true ? { dryRun: true } : {}),
+    ...(typeof change.kind === 'string' ? { change: change.kind.slice(0, 64) } : {}),
+    ...(typeof change.table === 'string' ? { table: change.table.slice(0, 256) } : {}),
+    ...(texts.length && redact
+      ? { statements: texts.map(text => { try { return redact(text); } catch { return '[unavailable]'; } }) }
+      : texts.length ? { statementLength: texts.reduce((total, text) => total + text.length, 0) } : {}),
+  };
+}
+
+/** Cuts the longest statement until the serialised detail fits {@link AUDIT_DETAIL_JSON_LIMIT}. */
+function fitAuditDetail(detail: Record<string, unknown>): Record<string, unknown> {
+  const statements = Array.isArray(detail.statements) ? [...detail.statements as string[]] : undefined;
+  if (!statements) return detail;
+  let truncated = false;
+  for (;;) {
+    const candidate = { ...detail, statements, ...(truncated ? { truncated: true } : {}) };
+    const overflow = JSON.stringify(candidate).length - AUDIT_DETAIL_JSON_LIMIT;
+    if (overflow <= 0) return { ...candidate, statements: Object.freeze(statements) };
+    truncated = true;
+    let longest = 0;
+    for (let index = 1; index < statements.length; index += 1) if (statements[index]!.length > statements[longest]!.length) longest = index;
+    const text = statements[longest]!;
+    if (text.length <= 1) { statements.splice(longest, 1); continue; }
+    statements[longest] = `${text.slice(0, Math.max(0, text.length - overflow - 1))}…`;
+  }
+}
+
+/**
+ * Audit detail for an RPC: type, target and parameter key names only — plus the statement text
+ * of Console database writes (pass the reply so the DDL a schema change ran is recorded), with
+ * literals redacted by `options.redactSql`.
+ */
+export function rpcAuditDetail(
+  message: Readonly<Record<string, unknown>>,
+  reply?: Readonly<Record<string, unknown>>,
+  options?: RpcAuditOptions,
+): Readonly<Record<string, unknown>> {
   const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data)
     ? Object.keys(message.data as Record<string, unknown>).sort()
     : [];
   const keys = Object.keys(message).filter(key => key !== 'type' && key !== 'requestId' && key !== 'data').sort();
-  return Object.freeze({ type: String(message.type ?? ''), keys: Object.freeze([...new Set([...keys, ...data])]) });
+  return Object.freeze(fitAuditDetail({
+    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 {