@zhin.js/host-http 1.1.17 → 1.2.0

package/src/console-rest-pages.ts

@@ -4,24 +4,29 @@
  * 统一提供日志、市场、Runtime snapshot 内省和 Agent session tree 页面。
  *
  * 数据源不可用时降级：读操作返回空数组 + `note` 说明，session tree 返回 503；
- * 写操作要求 `ctx.fullScope && authScope === 'full'`，否则 403。
+ * 写操作要求 `ctx.fullScope`，否则 403。
  */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { HttpHost } from './http-host.js';
 import { readJsonBody } from './json-body.js';
-import { MarketplaceRegistry } from './marketplace-registry.js';
+import { jsonResponse } from '@zhin.js/host-http-contract';
+import {
+  MarketplaceDetailCache,
+  MarketplaceRegistry,
+  isValidNpmPackageName,
+} from './marketplace-registry.js';
 import type { ConsoleMessageEventData } from '@zhin.js/console-protocol';
 import {
   clampPositiveInt,
   decodePathParam,
+  logInternalError,
   normalizeBase,
   parsePositiveInt,
   registerAgentSessionRoutes,
   registerIntrospectionRoutes,
   requireWriteScope,
   trimTrailingSlashes,
-  writeJson,
 } from './console-rest-pages-helpers.js';
 
 /** 与 basic/cli 接线方对齐的上下文约定。 */
@@ -135,6 +140,8 @@ type LogRow = {
 };
 
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
+const PACKAGE_DETAIL_CACHE_TTL = 5 * 60 * 1000;
+const PACKAGE_DETAIL_CACHE_MAX_ENTRIES = 64;
 
 /**
  * 注册 Console 页面 REST 路由。返回注销函数（注销全部已注册路由）。
@@ -188,7 +195,7 @@ function registerLogsRoutes(
   };
   const unavailableNote = 'SystemLog 模型不可用（Database 未启动或未注册 DatabaseLogTransport）';
 
-  route('GET', `${base}/logs`, async (_request, response, url) => {
+  route('GET', `${base}/logs`, async (_request, { url }) => {
     const pageSize = clampPositiveInt(parsePositiveInt(url.searchParams.get('pageSize') ?? url.searchParams.get('limit'), 100), 100, 1000);
     const requestedPage = clampPositiveInt(parsePositiveInt(url.searchParams.get('page'), 1), 1, Number.MAX_SAFE_INTEGER);
     const level = url.searchParams.get('level');
@@ -200,8 +207,7 @@ function registerLogsRoutes(
     const where = { ...baseWhere, ...(source ? { source } : {}) };
     const LogModel = getModel();
     if (!LogModel) {
-      writeJson(response, 200, { success: true, data: [], total: 0, page: 1, pageSize, totalPages: 1, sources: [], note: unavailableNote });
-      return;
+      return jsonResponse(200, { success: true, data: [], total: 0, page: 1, pageSize, totalPages: 1, sources: [], note: unavailableNote });
     }
     // Database $like has no portable ESCAPE contract. Keep q literal (including
     // %/_ and Unicode) and filter actual retained rows on the Host, not wildcard SQL.
@@ -228,7 +234,7 @@ function registerLogsRoutes(
       if (!name || !matchesQuery(row)) continue;
       counts.set(name, (counts.get(name) ?? 0) + 1);
     }
-    writeJson(response, 200, {
+    return jsonResponse(200, {
       success: true,
       data: logs.map((log) => ({
         id: log.id,
@@ -243,19 +249,20 @@ function registerLogsRoutes(
     });
   }, { summary: 'List system logs', tags: ['console', 'logs'] });
 
-  route('DELETE', `${base}/logs`, async (_request, response, _url, authScope) => {
-    if (!requireWriteScope(response, ctx, authScope)) return;
+  route('DELETE', `${base}/logs`, async () => {
+    const denied = requireWriteScope(ctx);
+    if (denied) return denied;
     const LogModel = getModel();
     if (LogModel) {
       await LogModel.delete({});
     }
-    writeJson(response, 200, { success: true, message: '日志已清空' });
+    return jsonResponse(200, { success: true, message: '日志已清空' });
   }, { summary: 'Clear system logs', tags: ['console', 'logs'] });
 
-  route('GET', `${base}/logs/stats`, async (_request, response) => {
+  route('GET', `${base}/logs/stats`, async () => {
     const LogModel = getModel();
     if (!LogModel) {
-      writeJson(response, 200, {
+      return jsonResponse(200, {
         success: true,
         data: {
           total: 0,
@@ -264,7 +271,6 @@ function registerLogsRoutes(
         },
         note: unavailableNote,
       });
-      return;
     }
 
     // 计数走 DB 侧聚合（count）；模型未实现 count 时降级为 select('id') 只取主键列
@@ -293,23 +299,23 @@ function registerLogsRoutes(
           : (oldestLog[0].timestamp ?? null)
         : null;
 
-    writeJson(response, 200, {
+    return jsonResponse(200, {
       success: true,
       data: { total, byLevel: levelCounts, oldestTimestamp },
     });
   }, { summary: 'System log stats', tags: ['console', 'logs'] });
 
-  route('POST', `${base}/logs/cleanup`, async (request, response, _url, authScope) => {
-    if (!requireWriteScope(response, ctx, authScope)) return;
+  route('POST', `${base}/logs/cleanup`, async (request) => {
+    const denied = requireWriteScope(ctx);
+    if (denied) return denied;
     const LogModel = getModel();
     if (!LogModel) {
-      writeJson(response, 200, {
+      return jsonResponse(200, {
         success: true,
         message: '已清理 0 条日志',
         deletedCount: 0,
         note: unavailableNote,
       });
-      return;
     }
 
     const body = (await readJsonBody(request) ?? {}) as {
@@ -342,7 +348,7 @@ function registerLogsRoutes(
       }
     }
 
-    writeJson(response, 200, {
+    return jsonResponse(200, {
       success: true,
       message: `已清理 ${deletedCount} 条日志`,
       deletedCount,
@@ -368,7 +374,47 @@ function registerMarketplaceRoutes(
     ttlMs: PLUGINS_CACHE_TTL,
   });
 
-  route('GET', '/pub/marketplace/search', async (_request, response, url) => {
+  // The detail route is unauthenticated: cache the projected packument so repeated
+  // requests cannot be used to hammer the npm registry.
+  const details = new MarketplaceDetailCache<Record<string, unknown>>({
+    ttlMs: PACKAGE_DETAIL_CACHE_TTL,
+    maxEntries: PACKAGE_DETAIL_CACHE_MAX_ENTRIES,
+    load: async (pkgName) => {
+      const metaResp = await fetchFn(
+        `${npmRegistryUrl}/${encodeURIComponent(pkgName)}`,
+        { signal: AbortSignal.timeout(30_000) },
+      );
+      if (!metaResp.ok) throw new Error(`Package not found: ${metaResp.status}`);
+      const meta = (await metaResp.json()) as Record<string, unknown>;
+      const latest = (meta['dist-tags'] as Record<string, string> | undefined)?.latest;
+      const versions = meta.versions as Record<string, Record<string, unknown>> | undefined;
+      const latestInfo = latest && versions ? versions[latest] : undefined;
+      const time = meta.time as Record<string, string> | undefined;
+      return {
+        name: meta.name,
+        version: latest,
+        description: meta.description || '',
+        readme: meta.readme || '',
+        license: meta.license || latestInfo?.license || '',
+        homepage: meta.homepage || latestInfo?.homepage || '',
+        repository:
+          (meta.repository as { url?: string } | undefined)?.url ||
+          (latestInfo?.repository as { url?: string } | undefined)?.url ||
+          '',
+        author:
+          typeof meta.author === 'string'
+            ? meta.author
+            : (meta.author as { name?: string } | undefined)?.name || '',
+        keywords: (latestInfo?.keywords as string[]) || [],
+        engines: latestInfo?.engines || {},
+        peerDependencies: latestInfo?.peerDependencies || {},
+        versions: Object.keys(versions || {}),
+        lastPublish: (latest && time?.[latest]) || '',
+      };
+    },
+  });
+
+  route('GET', '/pub/marketplace/search', async (_request, { url }) => {
     const q = url.searchParams.get('q') ?? url.searchParams.get('keyword') ?? '';
     const pageNum = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10) || 1);
     const pageSize = Math.min(
@@ -413,7 +459,7 @@ function registerMarketplaceRoutes(
       const total = plugins.length;
       const start = (pageNum - 1) * pageSize;
       const items = plugins.slice(start, start + pageSize);
-      writeJson(response, 200, {
+      return jsonResponse(200, {
         success: true,
         data: items,
         total,
@@ -421,23 +467,26 @@ function registerMarketplaceRoutes(
         size: pageSize,
       });
     } catch (err) {
-      writeJson(response, 502, {
+      logInternalError('marketplace_search_failed', err);
+      return jsonResponse(502, {
         success: false,
-        error: err instanceof Error ? err.message : 'Search failed',
+        error: 'Search failed',
       });
     }
   }, { summary: 'Search plugin marketplace', tags: ['pub', 'marketplace'] });
 
-  route('GET', '/pub/marketplace/detail/*', async (_request, response, url) => {
+  route('GET', '/pub/marketplace/detail/*', async (_request, { url }) => {
     const prefix = '/pub/marketplace/detail/';
     const rawName = url.pathname.startsWith(prefix)
       ? url.pathname.slice(prefix.length).replace(/\/+$/u, '')
       : '';
     if (!rawName) {
-      writeJson(response, 404, { success: false, error: 'Package name is required' });
-      return;
+      return jsonResponse(404, { success: false, error: 'Package name is required' });
     }
     const pkgName = decodePathParam(rawName);
+    if (!isValidNpmPackageName(pkgName)) {
+      return jsonResponse(400, { success: false, error: 'Invalid package name' });
+    }
     try {
       let cachedDownloads = { weekly: 0, monthly: 0 };
       try {
@@ -453,55 +502,25 @@ function registerMarketplaceRoutes(
         /* ignore cache miss */
       }
 
-      const metaResp = await fetchFn(
-        `${npmRegistryUrl}/${encodeURIComponent(pkgName)}`,
-        { signal: AbortSignal.timeout(30_000) },
-      );
-      if (!metaResp.ok) throw new Error(`Package not found: ${metaResp.status}`);
-      const meta = (await metaResp.json()) as Record<string, unknown>;
-      const latest = (meta['dist-tags'] as Record<string, string> | undefined)?.latest;
-      const versions = meta.versions as Record<string, Record<string, unknown>> | undefined;
-      const latestInfo = latest && versions ? versions[latest] : undefined;
-      const time = meta.time as Record<string, string> | undefined;
-      writeJson(response, 200, {
+      const detail = await details.get(pkgName);
+      return jsonResponse(200, {
         success: true,
-        data: {
-          name: meta.name,
-          version: latest,
-          description: meta.description || '',
-          readme: meta.readme || '',
-          license: meta.license || latestInfo?.license || '',
-          homepage: meta.homepage || latestInfo?.homepage || '',
-          repository:
-            (meta.repository as { url?: string } | undefined)?.url ||
-            (latestInfo?.repository as { url?: string } | undefined)?.url ||
-            '',
-          author:
-            typeof meta.author === 'string'
-              ? meta.author
-              : (meta.author as { name?: string } | undefined)?.name || '',
-          keywords: (latestInfo?.keywords as string[]) || [],
-          engines: latestInfo?.engines || {},
-          peerDependencies: latestInfo?.peerDependencies || {},
-          downloads: cachedDownloads,
-          versions: Object.keys(versions || {}),
-          lastPublish: (latest && time?.[latest]) || '',
-        },
+        data: { ...detail, downloads: cachedDownloads },
       });
     } catch (err) {
-      writeJson(response, 502, {
+      logInternalError('marketplace_detail_failed', err);
+      return jsonResponse(502, {
         success: false,
-        error: err instanceof Error ? err.message : 'Detail fetch failed',
+        error: 'Detail fetch failed',
       });
     }
   }, { summary: 'Plugin marketplace detail', tags: ['pub', 'marketplace'] });
 
-  route('GET', `${base}/marketplace/updates`, async (_request, response) => {
+  route('GET', `${base}/marketplace/updates`, async () => {
     try {
       const installed = await listInstalledPluginPackages(ctx.projectRoot);
       if (!installed.length) {
-        writeJson(response, 200, { success: true, data: [] });
-        return;
+        return jsonResponse(200, { success: true, data: [] });
       }
       const updates = await Promise.all(
         installed.map(async ({ name, current }) => {
@@ -524,11 +543,12 @@ function registerMarketplaceRoutes(
           }
         }),
       );
-      writeJson(response, 200, { success: true, data: updates.filter(Boolean) });
+      return jsonResponse(200, { success: true, data: updates.filter(Boolean) });
     } catch (err) {
-      writeJson(response, 500, {
+      logInternalError('marketplace_updates_failed', err);
+      return jsonResponse(500, {
         success: false,
-        error: err instanceof Error ? err.message : 'Update check failed',
+        error: 'Update check failed',
       });
     }
   }, { summary: 'Check installed plugin updates', tags: ['console', 'marketplace'] });

package/src/console-rpc-extended/dispatcher.ts

@@ -1,4 +1,3 @@
-import { assertDemoConsoleRpcAllowed } from '@zhin.js/console-protocol';
 import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
 import { addCron, listSchedule, mutateCron, validateCron } from './schedule-rpc.js';
 import {
@@ -16,13 +15,9 @@ export async function dispatchExtendedConsoleRpc(
   data: Record<string, unknown> | undefined,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult | undefined> {
+  // Callers authorize every message against the ADR 0049 permission map before dispatch.
   const d = data ?? {};
 
-  if (!ctx.fullScope) {
-    const denied = assertDemoConsoleRpcAllowed(type);
-    if (denied) return { error: denied };
-  }
-
   switch (type) {
     case 'schedule:list':
     case 'cron:list':

package/src/console-rpc-handlers.ts

@@ -241,7 +241,8 @@ export async function dispatchHostResourceConsoleRpc(
           return true;
         }
         const tables = ctx.dbTables ? await ctx.dbTables() : [];
-        emit({ requestId, data: tables });
+        // Same `{ tables }` envelope as the database branch above; clients read `.tables`.
+        emit({ requestId, data: { tables } });
       } catch (error) {
         emit({
           requestId,
@@ -560,26 +561,6 @@ export function errorReply(
   return payloads;
 }
 
-/** HTTP paths under apiBase that demo scope may call (ADR 0016). */
-export function isDemoHttpAllowed(method: string, pathname: string, apiBase: string): boolean {
-  const normalizedBase = apiBase.replace(/\/$/u, '') || '/api';
-  const m = method.toUpperCase();
-  // Each inference handler resolves a static authenticated personal binding before reading or mutating anything.
-  if (m === 'GET' && ['', '/owners', '/export', '/mutation', '/sessions', '/session'].some(path => pathname === `${normalizedBase}/agent/inference${path}`)) return true;
-  if (m === 'PUT' && pathname === `${normalizedBase}/agent/inference/session`) return true;
-  if (m === 'POST' && ['/plan', '/apply', '/key/prepare', '/discover', '/profile-schema'].some(path => pathname === `${normalizedBase}/agent/inference${path}`)) return true;
-  if (m === 'GET' && pathname === `${normalizedBase}/events`) return true;
-  if (m === 'GET' && pathname === `${normalizedBase}/events/history`) return true;
-  if (m === 'GET' && DEMO_INTROSPECTION_PATHS.has(pathname.slice(normalizedBase.length))) return true;
-  if (m === 'POST' && pathname === `${normalizedBase}/console/request`) return true;
-  // Read-only dashboard / plugin inspection routes (legacy host-api parity).
-  if (m === 'GET' && pathname === `${normalizedBase}/system/status`) return true;
-  if (m === 'GET' && pathname === `${normalizedBase}/stats`) return true;
-  if (m === 'GET' && (pathname === `${normalizedBase}/plugins`
-    || pathname.startsWith(`${normalizedBase}/plugins/`))) return true;
-  return false;
-}
-
 export function configurationSaveMessage(result: { restartRequired: boolean; revision?: string }
   & ConsoleConfigApplicationStatus): string {
   if (result.applicationError === 'superseded') return '配置已保存，但该次生效申请已被替代';
@@ -596,13 +577,3 @@ export function configurationSaveMessage(result: { restartRequired: boolean; rev
   return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
 
-const DEMO_INTROSPECTION_PATHS: ReadonlySet<string> = new Set([
-  '/introspection/commands',
-  '/introspection/middlewares',
-  '/introspection/components',
-  '/introspection/endpoints',
-  '/introspection/bindings',
-  '/introspection/tools',
-  '/introspection/prompt-sections',
-  '/introspection/mcp',
-]);

package/src/console-rpc.ts

@@ -9,8 +9,8 @@ import {
   type ConsoleConfigSource,
   type ConsoleConfigExplanation,
   type ConsoleEndpointSummary,
-  assertDemoConsoleRpcAllowed,
 } from '@zhin.js/console-protocol';
+import { authorizeConsoleRpc, type ConsolePrincipal } from './access-control.js';
 import { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import {
@@ -19,7 +19,6 @@ import {
   invalidProjectPatchOperations,
 } from './console-rpc-handlers.js';
 
-export { isDemoHttpAllowed } from './console-rpc-handlers.js';
 
 /**
  * Console RPC 请求结构：未锚定 endpoint 的会话地址（结构对齐
@@ -135,21 +134,8 @@ export interface PluginManagementPort {
   verificationPlan?(packageName: string): Promise<PluginVerificationPlan>;
   verify?(packageName: string, checkId: string, expectedGeneration: number | null, expectedProjectRevision: string, expectedCheckRevision: string): Promise<PluginVerificationResult>;
   planInstall(packageName: string): Promise<PluginInstallPlan>;
-  install?(packageName: string, expectedRevision?: string, expectedProjectRevision?: string): Promise<Readonly<{
-    readonly plan: PluginInstallPlan;
-    readonly restartRequired: boolean;
-  }>>;
   planUninstall?(packageName: string): Promise<PluginUninstallPlan>;
-  uninstall?(packageName: string, expectedRevision?: string, expectedProjectRevision?: string): Promise<Readonly<{
-    readonly plan: PluginUninstallPlan;
-    readonly restartRequired: boolean;
-  }>>;
   planUpdate?(packageName: string, targetVersion: string): Promise<PluginUpdatePlan>;
-  update?(packageName: string, targetVersion: string, expectedRevision?: string, expectedProjectRevision?: string): Promise<Readonly<{
-    readonly plan: PluginUpdatePlan;
-    readonly installedVersion: string;
-    readonly restartRequired: boolean;
-  }>>;
 }
 
 export interface PluginConfigValidation {
@@ -172,6 +158,11 @@ export type RuntimeConsolePage = {
 
 export type RuntimeConsoleRpcContext = {
   readonly authScope: AuthScope;
+  /**
+   * Caller principal. When set, every message is checked against the ADR 0049 permission map
+   * before dispatch (defence in depth; the route also checks).
+   */
+  readonly principal?: ConsolePrincipal;
   listPages(): Promise<readonly RuntimeConsolePage[]>;
   /** Optional project config accessors for read-only config RPCs. */
   readConfigSource?(): Promise<ConsoleConfigSource>;
@@ -282,10 +273,10 @@ export async function dispatchRuntimeConsoleRpc(
   const type = String(message.type ?? '');
   const requestId = message.requestId as number | string | undefined;
 
-  if (ctx.authScope === 'demo') {
-    const denied = assertDemoConsoleRpcAllowed(type);
-    if (denied) {
-      emit({ requestId, error: denied });
+  if (ctx.principal) {
+    const decision = authorizeConsoleRpc(ctx.principal, message as Record<string, unknown>);
+    if (!decision.allowed) {
+      emit({ requestId, error: decision.error, code: decision.code });
       return payloads;
     }
   }

package/src/host-installer.ts

@@ -2,18 +2,15 @@ import {
   bindGenerationAdmission,
   expandEnvironmentValue,
   type ConfigDocumentPort,
+  type GenerationAdmissionBindable,
   type RootResourceInstaller,
   type RuntimeConfigDocument,
 } from '@zhin.js/plugin-runtime';
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
-import {
-  httpHostToken,
-  type HttpHost,
-  type HttpHostOptions,
-  type ProcessHttpHost,
-} from './http-host.js';
-import type { ScopedTokenConfig } from './token-registry.js';
+import { httpHostToken, type HttpHost } from './http-host.js';
+import type { HttpHostOptions } from './host-options.js';
+import { parseTrustProxy } from './trust-proxy.js';
 
 export interface ResolvedHttpConfig extends HttpHostOptions {
   /** Additional listeners that mirror the primary Host route surface. */
@@ -33,14 +30,15 @@ export async function resolveHttpConfig(
     http,
     (key) => envOverlay?.[key] ?? process.env[key],
   ) as Record<string, unknown>;
+  if (value.tokens !== undefined && value.tokens !== null) throw new Error(HTTP_TOKENS_REMOVED_MESSAGE);
   const primary: HttpHostOptions = Object.freeze({
     host: typeof value.host === 'string' ? value.host : undefined,
     port: typeof value.port === 'number' ? value.port : undefined,
     token: typeof value.token === 'string' ? value.token : undefined,
-    tokens: parseScopedTokens(value.tokens),
     corsOrigins: injectDesktopWebviewOrigins(parseStringList(value.corsOrigins), envOverlay),
     apiBase: typeof value.base === 'string' ? value.base : undefined,
     tls: await parseTlsConfig(value.tls, projectRoot),
+    trustProxy: parseTrustProxy(value.trustProxy),
   });
   const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot);
   const listeners = await injectDesktopDeviceListener(
@@ -190,48 +188,18 @@ function resolveTlsPath(projectRoot: string, value: string): string {
   return isAbsolute(value) ? value : resolve(projectRoot, value);
 }
 
-export function installHttpHost(host: ProcessHttpHost): RootResourceInstaller {
+export function installHttpHost(host: HttpHost & GenerationAdmissionBindable<HttpHost>): RootResourceInstaller {
   return ({ resources, admission }) => {
     const port: HttpHost = host;
     resources.provide(httpHostToken, bindGenerationAdmission(port, admission));
   };
 }
 
-function parseScopedTokens(value: unknown): readonly ScopedTokenConfig[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const tokens: ScopedTokenConfig[] = [];
-  for (const entry of value) {
-    if (!entry || typeof entry !== 'object') continue;
-    const record = entry as Record<string, unknown>;
-    if (typeof record.token !== 'string' || !record.token) continue;
-    // `user` is an alias of `demo` (an ordinary Console user); anything but `full` is never the operator.
-    const scope = record.scope === 'full' ? 'full' : 'demo';
-    const principalId = typeof record.principalId === 'string' && record.principalId.trim() === record.principalId
-      && record.principalId.length > 0
-      ? record.principalId
-      : undefined;
-    const permissions = parseAccessList(record.permissions);
-    const roles = parseAccessList(record.roles);
-    tokens.push(Object.freeze({
-      token: record.token,
-      scope,
-      ...(principalId ? { principalId } : {}),
-      ...(permissions ? { permissions } : {}),
-      ...(roles ? { roles } : {}),
-    }));
-  }
-  return tokens.length > 0 ? Object.freeze(tokens) : undefined;
-}
-
-/** Console permissions / roles of a scoped token; blank or non-string entries are dropped. */
-function parseAccessList(value: unknown): readonly string[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const result = value
-    .filter((item): item is string => typeof item === 'string')
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-  return result.length > 0 ? Object.freeze([...new Set(result)]) : undefined;
-}
+/** `http.tokens` was removed by ADR 0049; the Host refuses to start rather than ignore it. */
+export const HTTP_TOKENS_REMOVED_MESSAGE = 'http.tokens 已移除（ADR 0049）：请删除该配置，'
+  + '改为 Console 用户（`zhin console user create`）与用户签发的 API 令牌；'
+  + '`http.token` 只作为首次初始化令牌使用。'
+  + ' / http.tokens was removed: delete it and use Console users and their API tokens instead.';
 
 function parseStringList(value: unknown): readonly string[] | undefined {
   if (!Array.isArray(value)) return undefined;

package/src/host-options.ts

@@ -0,0 +1,47 @@
+import type { TokenRegistry } from './token-registry.js';
+import type { TrustProxySetting } from './trust-proxy.js';
+
+export interface HttpHostAddress {
+  readonly host: string;
+  readonly port: number;
+  readonly protocol: 'http' | 'https';
+  readonly secure: boolean;
+  readonly origin: string;
+}
+
+type TlsMaterial = string | Uint8Array | ReadonlyArray<string | Uint8Array | { readonly pem: string | Uint8Array; readonly passphrase?: string }>;
+
+export interface HttpHostTlsOptions {
+  readonly key: TlsMaterial;
+  readonly cert: TlsMaterial;
+  readonly ca?: string | Uint8Array | ReadonlyArray<string | Uint8Array>;
+  readonly passphrase?: string;
+  readonly minVersion?: 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1';
+  readonly ciphers?: string;
+}
+
+/** Listener configuration (`http.*`) for the in-process Node server and the gateway. */
+export interface HttpHostOptions {
+  readonly host?: string;
+  readonly port?: number;
+  /** Bootstrap Bearer token (`http.token`), accepted only until the first owner exists. */
+  readonly token?: string;
+  /** CORS allowlist; always merged with Remote Console origin. */
+  readonly corsOrigins?: readonly string[];
+  /**
+   * Paths under this prefix require Bearer auth when a token registry is configured.
+   * Defaults to `/api`. `/pub/*`, Console shell, and page routes stay public.
+   */
+  readonly apiBase?: string;
+  /** Extra HTTP path prefixes that skip auth even under `apiBase`. */
+  readonly authExemptPaths?: readonly string[];
+  /** Enables HTTPS and WSS on this listener. Certificate lifecycle belongs to the process composition root. */
+  readonly tls?: HttpHostTlsOptions;
+  /**
+   * `http.trustProxy`: which TCP peers are reverse proxies whose `X-Forwarded-For` / `Forwarded`
+   * names the client. Off by default (the peer address is the client address).
+   */
+  readonly trustProxy?: TrustProxySetting;
+  /** @internal Shared registry for listener groups; `token` is ignored when set. */
+  readonly tokenRegistry?: TokenRegistry;
+}