@zhin.js/host-http 1.1.17 → 1.2.0

package/lib/console-rest-pages.js

@@ -4,14 +4,17 @@
  * 统一提供日志、市场、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 { readJsonBody } from './json-body.js';
-import { MarketplaceRegistry } from './marketplace-registry.js';
-import { clampPositiveInt, decodePathParam, normalizeBase, parsePositiveInt, registerAgentSessionRoutes, registerIntrospectionRoutes, requireWriteScope, trimTrailingSlashes, writeJson, } from './console-rest-pages-helpers.js';
+import { jsonResponse } from '@zhin.js/host-http-contract';
+import { MarketplaceDetailCache, MarketplaceRegistry, isValidNpmPackageName, } from './marketplace-registry.js';
+import { clampPositiveInt, decodePathParam, logInternalError, normalizeBase, parsePositiveInt, registerAgentSessionRoutes, registerIntrospectionRoutes, requireWriteScope, trimTrailingSlashes, } from './console-rest-pages-helpers.js';
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
+const PACKAGE_DETAIL_CACHE_TTL = 5 * 60 * 1000;
+const PACKAGE_DETAIL_CACHE_MAX_ENTRIES = 64;
 /**
  * 注册 Console 页面 REST 路由。返回注销函数（注销全部已注册路由）。
  */
@@ -52,7 +55,7 @@ function registerLogsRoutes(route, base, ctx) {
         }
     };
     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');
@@ -64,8 +67,7 @@ function registerLogsRoutes(route, base, ctx) {
         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.
@@ -93,7 +95,7 @@ function registerLogsRoutes(route, base, ctx) {
                 continue;
             counts.set(name, (counts.get(name) ?? 0) + 1);
         }
-        writeJson(response, 200, {
+        return jsonResponse(200, {
             success: true,
             data: logs.map((log) => ({
                 id: log.id,
@@ -107,19 +109,20 @@ function registerLogsRoutes(route, base, ctx) {
             sources: [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([source, count]) => ({ source, count })),
         });
     }, { 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,
@@ -128,7 +131,6 @@ function registerLogsRoutes(route, base, ctx) {
                 },
                 note: unavailableNote,
             });
-            return;
         }
         // 计数走 DB 侧聚合（count）；模型未实现 count 时降级为 select('id') 只取主键列
         const countRows = async (where) => {
@@ -152,23 +154,23 @@ function registerLogsRoutes(route, base, ctx) {
                 ? oldestLog[0].timestamp.toISOString()
                 : (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) ?? {});
         const { days, maxRecords } = body;
@@ -193,7 +195,7 @@ function registerLogsRoutes(route, base, ctx) {
                 }
             }
         }
-        writeJson(response, 200, {
+        return jsonResponse(200, {
             success: true,
             message: `已清理 ${deletedCount} 条日志`,
             deletedCount,
@@ -209,7 +211,42 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
         url: pluginRegistryUrl,
         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({
+        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());
+            const latest = meta['dist-tags']?.latest;
+            const versions = meta.versions;
+            const latestInfo = latest && versions ? versions[latest] : undefined;
+            const time = meta.time;
+            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?.url ||
+                    latestInfo?.repository?.url ||
+                    '',
+                author: typeof meta.author === 'string'
+                    ? meta.author
+                    : meta.author?.name || '',
+                keywords: latestInfo?.keywords || [],
+                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(100, Math.max(1, parseInt(url.searchParams.get('size') ?? url.searchParams.get('limit') ?? '20', 10) || 20));
@@ -251,7 +288,7 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
             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,
@@ -260,22 +297,25 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
             });
         }
         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 {
@@ -288,51 +328,25 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
             catch {
                 /* 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());
-            const latest = meta['dist-tags']?.latest;
-            const versions = meta.versions;
-            const latestInfo = latest && versions ? versions[latest] : undefined;
-            const time = meta.time;
-            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?.url ||
-                        latestInfo?.repository?.url ||
-                        '',
-                    author: typeof meta.author === 'string'
-                        ? meta.author
-                        : meta.author?.name || '',
-                    keywords: latestInfo?.keywords || [],
-                    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 }) => {
                 try {
@@ -352,12 +366,13 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
                     return null;
                 }
             }));
-            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/lib/console-rpc-extended/dispatcher.js

@@ -1,16 +1,11 @@
-import { assertDemoConsoleRpcAllowed } from '@zhin.js/console-protocol';
 import { addCron, listSchedule, mutateCron, validateCron } from './schedule-rpc.js';
 import { actOnRequest, listInbox, listInboxMessages, listPendingRequests, listRecentInboxMessages, mapNoticeRow, mapRequestRow, markInboxConsumed, TABLE_NOTICE, TABLE_REQUEST, } from './inbox-rpc.js';
 import { cancelLogin, listLoginPending, submitLogin } from './login-rpc.js';
 import { deleteFriend, groupWriteOp, listChannels, listFriends, listGroupMembers, listGroups, } from './endpoint-rpc.js';
 import { mutateWorkroomKnowledge, mutateWorkroomProfile } from './workroom-rpc.js';
 export async function dispatchExtendedConsoleRpc(type, data, ctx) {
+    // 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/lib/console-rpc-handlers.d.ts

@@ -13,8 +13,6 @@ export declare function recordField(value: unknown): Record<string, unknown> | u
 export declare function positiveInteger(value: unknown, fallback: number): number;
 export declare function errorMessage(error: unknown): string;
 export declare function errorReply(payloads: RuntimeConsoleRpcReply[], requestId: number | string | undefined, error: string): RuntimeConsoleRpcReply[];
-/** HTTP paths under apiBase that demo scope may call (ADR 0016). */
-export declare function isDemoHttpAllowed(method: string, pathname: string, apiBase: string): boolean;
 export declare function configurationSaveMessage(result: {
     restartRequired: boolean;
     revision?: string;

package/lib/console-rpc-handlers.js

@@ -230,7 +230,8 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
                     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({
@@ -596,35 +597,6 @@ export function errorReply(payloads, requestId, error) {
     payloads.push({ requestId, error });
     return payloads;
 }
-/** HTTP paths under apiBase that demo scope may call (ADR 0016). */
-export function isDemoHttpAllowed(method, pathname, apiBase) {
-    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) {
     if (result.applicationError === 'superseded')
         return '配置已保存，但该次生效申请已被替代';
@@ -647,13 +619,3 @@ export function configurationSaveMessage(result) {
     }
     return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
-const DEMO_INTROSPECTION_PATHS = new Set([
-    '/introspection/commands',
-    '/introspection/middlewares',
-    '/introspection/components',
-    '/introspection/endpoints',
-    '/introspection/bindings',
-    '/introspection/tools',
-    '/introspection/prompt-sections',
-    '/introspection/mcp',
-]);

package/lib/console-rpc.d.ts

@@ -1,8 +1,8 @@
 import type { AuthScope } from './token-registry.js';
 import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
 import { type ConsoleConfigPatchRequest, type ConsoleConfigPatchResult, type ConsoleConfigProjectPatchResult, type ConsoleConfigSource, type ConsoleConfigExplanation, type ConsoleEndpointSummary } from '@zhin.js/console-protocol';
+import { type ConsolePrincipal } from './access-control.js';
 import { type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
-export { isDemoHttpAllowed } from './console-rpc-handlers.js';
 /**
  * Console RPC 请求结构：未锚定 endpoint 的会话地址（结构对齐
  * `Omit<ConversationRef,'endpoint'>`；host/http 架构分层不允许依赖
@@ -111,21 +111,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 {
     /** False means only environment-reference checks ran; Runtime must validate TS-only declarations. */
@@ -148,6 +135,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>;

package/lib/console-rpc.js

@@ -1,8 +1,8 @@
-import { CONFIG_PATCH_LIMITS, CONFIG_RPC, assertDemoConsoleRpcAllowed, } from '@zhin.js/console-protocol';
+import { CONFIG_PATCH_LIMITS, CONFIG_RPC, } from '@zhin.js/console-protocol';
+import { authorizeConsoleRpc } from './access-control.js';
 import { dispatchExtendedConsoleRpc } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import { configurationSaveMessage, dispatchHostResourceConsoleRpc, invalidProjectPatchOperations, } from './console-rpc-handlers.js';
-export { isDemoHttpAllowed } from './console-rpc-handlers.js';
 export function pickRpcReply(message, payloads) {
     const requestId = message.requestId;
     return ((requestId != null ? payloads.find((payload) => payload.requestId === requestId) : undefined)
@@ -16,10 +16,10 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
     };
     const type = String(message.type ?? '');
     const requestId = message.requestId;
-    if (ctx.authScope === 'demo') {
-        const denied = assertDemoConsoleRpcAllowed(type);
-        if (denied) {
-            emit({ requestId, error: denied });
+    if (ctx.principal) {
+        const decision = authorizeConsoleRpc(ctx.principal, message);
+        if (!decision.allowed) {
+            emit({ requestId, error: decision.error, code: decision.code });
             return payloads;
         }
     }

package/lib/host-installer.d.ts

@@ -1,8 +1,11 @@
-import { type ConfigDocumentPort, type RootResourceInstaller, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
-import { type HttpHostOptions, type ProcessHttpHost } from './http-host.js';
+import { type ConfigDocumentPort, type GenerationAdmissionBindable, type RootResourceInstaller, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+import { type HttpHost } from './http-host.js';
+import type { HttpHostOptions } from './host-options.js';
 export interface ResolvedHttpConfig extends HttpHostOptions {
     /** Additional listeners that mirror the primary Host route surface. */
     readonly listeners?: readonly HttpHostOptions[];
 }
 export declare function resolveHttpConfig(config: RuntimeConfigDocument | ConfigDocumentPort, envOverlay?: Readonly<Record<string, string | undefined>>, projectRoot?: string): Promise<ResolvedHttpConfig>;
-export declare function installHttpHost(host: ProcessHttpHost): RootResourceInstaller;
+export declare function installHttpHost(host: HttpHost & GenerationAdmissionBindable<HttpHost>): RootResourceInstaller;
+/** `http.tokens` was removed by ADR 0049; the Host refuses to start rather than ignore it. */
+export declare const HTTP_TOKENS_REMOVED_MESSAGE: string;

package/lib/host-installer.js

@@ -1,7 +1,8 @@
 import { bindGenerationAdmission, expandEnvironmentValue, } from '@zhin.js/plugin-runtime';
 import { readFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
-import { httpHostToken, } from './http-host.js';
+import { httpHostToken } from './http-host.js';
+import { parseTrustProxy } from './trust-proxy.js';
 export async function resolveHttpConfig(config, envOverlay, projectRoot = process.cwd()) {
     const document = await readConfigDocument(config);
     if (!document || typeof document !== 'object')
@@ -10,14 +11,16 @@ export async function resolveHttpConfig(config, envOverlay, projectRoot = proces
     if (!http || typeof http !== 'object')
         return {};
     const value = expandEnvironmentValue(http, (key) => envOverlay?.[key] ?? process.env[key]);
+    if (value.tokens !== undefined && value.tokens !== null)
+        throw new Error(HTTP_TOKENS_REMOVED_MESSAGE);
     const primary = 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(configuredListeners, primary, envOverlay, projectRoot);
@@ -154,44 +157,11 @@ export function installHttpHost(host) {
         resources.provide(httpHostToken, bindGenerationAdmission(port, admission));
     };
 }
-function parseScopedTokens(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const tokens = [];
-    for (const entry of value) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const record = entry;
-        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) {
-    if (!Array.isArray(value))
-        return undefined;
-    const result = value
-        .filter((item) => 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) {
     if (!Array.isArray(value))
         return undefined;

package/lib/host-options.d.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;
+}
+export {};

package/lib/host-options.js

@@ -0,0 +1 @@
+export {};