@zhin.js/host-http 1.2.1 → 1.3.0

package/src/console-rpc-handlers.ts

@@ -1,7 +1,11 @@
 import {
   CONFIG_PATCH_LIMITS,
+  CONSOLE_SEND_FAILURE_MESSAGES,
   ENDPOINT_RPC,
+  classifyConsoleSendFailure,
   type ConsoleConfigApplicationStatus,
+  type ConsoleSendFailure,
+  type ConsoleSendFailureStatus,
 } from '@zhin.js/console-protocol';
 import type {
   ConversationAddress,
@@ -30,6 +34,43 @@ export function wireConversation(
   };
 }
 
+const SEND_FAILURE_STATUSES: ReadonlySet<string> = new Set(['failed', 'rejected', 'unsupported', 'suppressed']);
+
+/**
+ * Structural read of an outbound failure (#1250): Core's `EndpointDeliveryError` carries `code`,
+ * `disposition` and the canonical receipt; host/http must not import Core, so only those fields are
+ * read. `endpoint not found` is the Endpoint directory's plain error. An error counts as a send
+ * failure only when its `code` is a known delivery code or it carries a `disposition` / `receipt`;
+ * anything else (a Node `ENOENT`, a database error, …) is unclassified and keeps its own message.
+ */
+export function consoleSendFailure(error: unknown): ConsoleSendFailure | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const record = error as Error & { code?: unknown; disposition?: unknown; receipt?: unknown };
+  if (typeof record.code !== 'string' || !record.code) {
+    return error.message === 'endpoint not found'
+      ? { code: 'endpoint_not_found', reason: 'endpoint_not_found', status: 'failed' }
+      : undefined;
+  }
+  // Every known delivery code maps to a reason other than the catch-all `failed`.
+  const knownCode = classifyConsoleSendFailure(record.code) !== 'failed';
+  const delivery = typeof record.disposition === 'string' || (!!record.receipt && typeof record.receipt === 'object');
+  if (!knownCode && !delivery) return undefined;
+  const receipt = record.receipt && typeof record.receipt === 'object'
+    ? record.receipt as { status?: unknown; failure?: { retryable?: unknown; deliveryUnknown?: unknown } }
+    : undefined;
+  const status: ConsoleSendFailureStatus = record.disposition === 'unknown' || receipt?.failure?.deliveryUnknown === true
+    ? 'unknown'
+    : typeof receipt?.status === 'string' && SEND_FAILURE_STATUSES.has(receipt.status)
+      ? receipt.status as ConsoleSendFailureStatus
+      : record.disposition === 'rejected' ? 'rejected' : 'failed';
+  return {
+    code: record.code,
+    reason: classifyConsoleSendFailure(record.code, status),
+    status,
+    ...(receipt?.failure?.retryable === true ? { retryable: true } : {}),
+  };
+}
+
 const FORBIDDEN_PATCH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
 
 /**
@@ -145,12 +186,12 @@ export async function dispatchHostResourceConsoleRpc(
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (!ctx.readEnvFile) {
+        // Masked only (issue #1250): the file as written is never answered here.
+        if (!ctx.readEnvFileView) {
           emit({ requestId, error: 'Env read is not configured' });
           return true;
         }
-        const content = await ctx.readEnvFile(filename);
-        emit({ requestId, data: { content } });
+        emit({ requestId, data: await ctx.readEnvFileView(filename) });
       } catch (error) {
         emit({
           requestId,
@@ -159,23 +200,70 @@ export async function dispatchHostResourceConsoleRpc(
       }
       return true;
     }
+    case 'env:reveal': {
+      try {
+        const filename = String(message.filename ?? '');
+        const key = message.key;
+        if (!filename) {
+          emit({ requestId, error: 'filename is required' });
+          return true;
+        }
+        if (typeof key !== 'string' || !key) {
+          emit({ requestId, error: 'key is required' });
+          return true;
+        }
+        if (!ctx.revealEnvVariable) {
+          emit({ requestId, error: 'Env reveal is not configured' });
+          return true;
+        }
+        emit({ requestId, data: await ctx.revealEnvVariable(filename, key) });
+      } catch (error) {
+        emit({
+          requestId,
+          error: `Failed to reveal env variable: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+      return true;
+    }
     case 'env:save': {
       try {
         const filename = String(message.filename ?? '');
-        const content = message.content;
         if (!filename) {
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (typeof content !== 'string') {
-          emit({ requestId, error: 'content field is required' });
+        const hasChanges = message.changes !== undefined;
+        const hasContent = message.content !== undefined;
+        if (hasChanges && hasContent) {
+          emit({ requestId, error: 'changes 与 content 只能提供一个' });
           return true;
         }
-        if (!ctx.writeEnvFile) {
+        if (hasChanges) {
+          if (!ctx.updateEnvVariables) {
+            emit({ requestId, error: 'Env write is not configured' });
+            return true;
+          }
+          const { changed } = await ctx.updateEnvVariables(filename, message.changes);
+          emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}`, changed } });
+          return true;
+        }
+        if (typeof message.content !== 'string') {
+          emit({ requestId, error: 'changes field is required' });
+          return true;
+        }
+        // The whole-file form must be asked for: an older Console sends back what `env:get` showed it.
+        if (message.mode !== 'replace') {
+          emit({
+            requestId,
+            error: '此 Host 只接受逐键保存（changes）；整文件保存需显式声明 mode: "replace"。请升级 Console 后重试',
+          });
+          return true;
+        }
+        if (!ctx.replaceEnvFile) {
           emit({ requestId, error: 'Env write is not configured' });
           return true;
         }
-        await ctx.writeEnvFile(filename, content);
+        await ctx.replaceEnvFile(filename, message.content);
         emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}` } });
       } catch (error) {
         emit({
@@ -257,14 +345,71 @@ export async function dispatchHostResourceConsoleRpc(
       const page = positiveInteger(message.page, 1);
       const pageSize = Math.min(positiveInteger(message.pageSize, 50), 500);
       const where = recordField(message.where);
+      const order = recordField(message.orderBy);
+      if (message.orderBy !== undefined && message.orderBy !== null
+        && (!order || typeof order.column !== 'string' || (order.direction !== 'asc' && order.direction !== 'desc'))) {
+        errorReply(payloads, requestId, 'orderBy must be { column, direction: "asc" | "desc" }');
+        return true;
+      }
       if (!ctx.database) {
         emit({ requestId, data: { rows: [], total: 0, page, pageSize } });
         return true;
       }
       try {
-        emit({ requestId, data: await ctx.database.select(table, page, pageSize, where) });
+        const orderBy = order ? { column: order.column as string, direction: order.direction as 'asc' | 'desc' } : undefined;
+        emit({ requestId, data: await ctx.database.select(table, page, pageSize, where, orderBy) });
+      } catch (error) {
+        emit({ requestId, error: `Failed to select: ${errorMessage(error)}`, ...refusalData(error) });
+      }
+      return true;
+    }
+    case 'db:query': {
+      const sql = sqlField(message);
+      if (!sql) { errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`); return true; }
+      if (!ctx.database?.query) { unsupportedDatabaseFeature(payloads, requestId, 'SQL query'); return true; }
+      try {
+        const maxRows = typeof message.maxRows === 'number' ? message.maxRows : undefined;
+        emit({ requestId, data: await ctx.database.query(sql, maxRows ? { maxRows } : undefined) });
+      } catch (error) {
+        emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+      }
+      return true;
+    }
+    case 'db:execute': {
+      const sql = sqlField(message);
+      if (!sql) { errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`); return true; }
+      if (!ctx.database?.execute) { unsupportedDatabaseFeature(payloads, requestId, 'SQL execution'); return true; }
+      try {
+        emit({ requestId, data: await ctx.database.execute(sql, { dryRun: message.dryRun === true }) });
+      } catch (error) {
+        emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+      }
+      return true;
+    }
+    case 'db:schema:describe': {
+      const table = stringField(message, 'table');
+      if (!table) { errorReply(payloads, requestId, 'table is required'); return true; }
+      if (!ctx.database?.describe) { unsupportedDatabaseFeature(payloads, requestId, 'Schema inspection'); return true; }
+      try {
+        emit({ requestId, data: await ctx.database.describe(table) });
+      } catch (error) {
+        emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+      }
+      return true;
+    }
+    case 'db:schema:preview':
+    case 'db:schema:apply': {
+      const change = recordField(message.change);
+      if (!change) { errorReply(payloads, requestId, 'change is required'); return true; }
+      const database = ctx.database;
+      if (!database?.previewSchema || !database.applySchema) { unsupportedDatabaseFeature(payloads, requestId, 'Schema editing'); return true; }
+      try {
+        const plan = type === 'db:schema:apply'
+          ? await database.applySchema(change, typeof message.confirm === 'string' ? message.confirm : undefined)
+          : await database.previewSchema(change);
+        emit({ requestId, data: plan });
       } catch (error) {
-        emit({ requestId, error: `Failed to select: ${errorMessage(error)}` });
+        emit({ requestId, error: errorMessage(error), ...refusalData(error) });
       }
       return true;
     }
@@ -498,9 +643,11 @@ export async function dispatchHostResourceConsoleRpc(
         });
         emit({ requestId, data: { messageId: result.messageId } });
       } catch (error) {
+        const failure = consoleSendFailure(error);
         emit({
           requestId,
-          error: error instanceof Error ? error.message : String(error),
+          error: failure ? CONSOLE_SEND_FAILURE_MESSAGES[failure.reason] : error instanceof Error ? error.message : String(error),
+          ...(failure ? { data: failure } : {}),
         });
       }
       return true;
@@ -532,6 +679,46 @@ export async function dispatchHostResourceConsoleRpc(
   }
 }
 
+/** Longest statement text the Console SQL editor sends. */
+export const MAX_CONSOLE_SQL_LENGTH = 100_000;
+
+function sqlField(message: RuntimeConsoleRpcMessage): string {
+  const value = message.sql;
+  return typeof value === 'string' && value.trim() && value.length <= MAX_CONSOLE_SQL_LENGTH ? value : '';
+}
+
+const REFUSAL_NAMES: ReadonlySet<string> = new Set(['ConsoleSqlRefusal', 'ConsoleSchemaRefusal', 'ConsoleSelectRefusal', 'SqliteQueryTimeoutError']);
+
+/**
+ * `data.code` of a refusal by the database port (`read_only`, `protected_table`, …), and the DDL a
+ * failed `db:schema:apply` attempted (`data.statements`, for the audit log).
+ */
+/** SQLSTATE of a driver error (PostgreSQL `code`, mysql2 `sqlState`), e.g. `42501` insufficient privilege. */
+function sqlStateOf(error: Error): string | undefined {
+  const record = error as { code?: unknown; sqlState?: unknown };
+  for (const candidate of [record.sqlState, record.code]) {
+    if (typeof candidate === 'string' && /^[0-9A-Z]{5}$/u.test(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function refusalData(error: unknown): { data?: { code?: string; statements?: readonly string[]; sqlState?: string } } {
+  if (!(error instanceof Error)) return {};
+  const attempted = (error as { statements?: unknown }).statements;
+  const statements = Array.isArray(attempted) && attempted.every(entry => typeof entry === 'string') ? { statements: attempted as string[] } : {};
+  if (error.name === 'GatewayOwnedTableError') return { data: { code: 'protected_table', ...statements } };
+  const code = (error as { code?: unknown }).code;
+  const refused = REFUSAL_NAMES.has(error.name) && typeof code === 'string';
+  // The server's SQLSTATE lets the Console explain e.g. 42501 from the restricted account (ADR 0059 §4).
+  const sqlState = refused ? undefined : sqlStateOf(error);
+  const data = { ...(refused ? { code } : {}), ...(sqlState ? { sqlState } : {}), ...statements };
+  return Object.keys(data).length ? { data } : {};
+}
+
+function unsupportedDatabaseFeature(payloads: RuntimeConsoleRpcReply[], requestId: number | string | undefined, feature: string): void {
+  payloads.push({ requestId, error: `${feature} is not supported by this database Host`, data: { code: 'unsupported' } });
+}
+
 export function stringField(message: RuntimeConsoleRpcMessage, key: string): string {
   const value = message[key];
   return typeof value === 'string' ? value.trim() : '';

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,8 @@ import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
 import {
   CONFIG_PATCH_LIMITS,
   CONFIG_RPC,
+  CONSOLE_UNKNOWN_RPC_CODE,
+  grantsAllow,
   type ConsoleConfigPatchRequest,
   type ConsoleConfigPatchResult,
   type ConsoleConfigProjectPatchResult,
@@ -10,7 +12,8 @@ import {
   type ConsoleConfigExplanation,
   type ConsoleEndpointSummary,
 } from '@zhin.js/console-protocol';
-import { authorizeConsoleRpc, type ConsolePrincipal } from './access-control.js';
+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 {
@@ -127,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>;
@@ -208,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>>;
@@ -257,6 +285,21 @@ export function pickRpcReply(
   );
 }
 
+/**
+ * The Endpoint a principal was admitted for when only an adapter / endpoint-scoped grant covers the
+ * call (B-1): handlers must then stay inside it. `undefined` when a global grant covers it.
+ */
+function scopedAuthorizedEndpoint(
+  principal: ConsolePrincipal,
+  decision: Extract<ReturnType<typeof authorizeConsoleRpc>, { allowed: true }>,
+): ConsoleRpcExtendedCtx['authorizedEndpoint'] {
+  if (principal.kind === 'bootstrap' || !decision.permission || !decision.rule) return undefined;
+  if (grantsAllow(principal.grants, decision.permission)) return undefined;
+  const target = decision.rule.target;
+  if (target.kind !== 'endpoint') return undefined;
+  return Object.freeze({ adapter: target.adapter, endpointKey: target.endpoint });
+}
+
 export async function dispatchRuntimeConsoleRpc(
   message: RuntimeConsoleRpcMessage,
   ctx: RuntimeConsoleRpcContext,
@@ -268,12 +311,20 @@ export async function dispatchRuntimeConsoleRpc(
   const type = String(message.type ?? '');
   const requestId = message.requestId as number | string | undefined;
 
+  let authorizedEndpoint: ConsoleRpcExtendedCtx['authorizedEndpoint'];
+  let canOperateEndpoint: ConsoleRpcExtendedCtx['canOperateEndpoint'];
   if (ctx.principal) {
-    const decision = authorizeConsoleRpc(ctx.principal, message as Record<string, unknown>);
+    const principal = ctx.principal;
+    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);
+    // Same grant check the map applies to `login.submit` for that Endpoint (ADR 0058 §8).
+    canOperateEndpoint = (adapter, endpointKey) => principalAllows(
+      principal, 'endpoint.operate', Object.freeze({ kind: 'endpoint', adapter, endpoint: endpointKey }),
+    );
   }
 
   // Extended RPC surface (cron/schedule、endpoint 社交/inbox)
@@ -281,11 +332,16 @@ export async function dispatchRuntimeConsoleRpc(
     const extended = await dispatchExtendedConsoleRpc(
       type,
       message as Record<string, unknown>,
-      { ...ctx.extended, fullScope: ctx.authScope === 'full' },
+      {
+        ...ctx.extended,
+        fullScope: ctx.authScope === 'full',
+        ...(authorizedEndpoint ? { authorizedEndpoint } : {}),
+        ...(canOperateEndpoint ? { canOperateEndpoint } : {}),
+      },
     );
     if (extended !== undefined) {
       emit('error' in extended
-        ? { requestId, error: extended.error }
+        ? { requestId, error: extended.error, ...(extended.data !== undefined ? { data: extended.data } : {}) }
         : { requestId, data: extended.data });
       return payloads;
     }
@@ -589,7 +645,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/http-host.ts

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

package/src/index.ts

@@ -36,6 +36,11 @@ export {
   authorizeConsoleRpc,
   authorizeConsoleWebSocket,
   globalPermissions,
+  grantsDenialReason,
+  isAuditedRpcDenial,
+  unknownConsoleRpcError,
+  webSocketDenialReason,
+  type AuthorizeConsoleRpcOptions,
   isUserPrincipal,
   isExplicitConsolePrincipal,
   pluginRpcWriteAllowed,
@@ -43,6 +48,7 @@ export {
   requestMeta,
   rpcAuditDetail,
   rpcAuditTarget,
+  type RpcAuditOptions,
   type ConsoleAccessProvider,
   type ConsoleAuditEntry,
   type ConsoleBootstrapPrincipal,
@@ -92,6 +98,8 @@ export {
   type HttpResponseStream,
   type HttpResponseStreamOptions,
 } from '@zhin.js/host-http-contract';
+export { isRuntimeConsoleRpcType, RUNTIME_CONSOLE_RPC_TYPES } from './console-rpc-types.js';
+export { createUnknownRpcLog, unknownRpcLog, type UnknownRpcLog, type UnknownRpcLogEntry } from './unknown-rpc.js';
 export {
   dispatchRuntimeConsoleRpc,
   pickRpcReply,
@@ -105,6 +113,8 @@ export {
   type PluginUpdatePlan,
   type PluginManagementPort,
   type PluginManagementState,
+  type PluginInspectOptions,
+  type PluginDependencyCheck,
   type PluginVerificationResult,
   type PluginVerificationPlan,
   type PluginConfigValidation,
@@ -132,9 +142,14 @@ 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';