@zhin.js/host-http 1.3.0 → 1.4.0

package/lib/access-control.d.ts

@@ -58,6 +58,16 @@ export interface ConsoleAccessProvider {
     audit?(entry: ConsoleAuditEntry): void;
 }
 export declare function isUserPrincipal(principal: ConsolePrincipal | undefined): principal is ConsoleUserPrincipal;
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export declare const LOCAL_SOCKET_USER_ID = "local";
+export declare const LOCAL_SOCKET_CREDENTIAL_ID = "local-socket";
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export declare function isLocalSocketPrincipal(principal: ConsolePrincipal | undefined): boolean;
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export declare function isGlobalOwnerPrincipal(principal: ConsolePrincipal | undefined): boolean;
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.

package/lib/access-control.js

@@ -3,6 +3,22 @@ import { hasForwardingHeaders } from './trust-proxy.js';
 export function isUserPrincipal(principal) {
     return principal?.kind === 'user' || principal?.kind === 'api-token';
 }
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export const LOCAL_SOCKET_USER_ID = 'local';
+export const LOCAL_SOCKET_CREDENTIAL_ID = 'local-socket';
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export function isLocalSocketPrincipal(principal) {
+    return principal?.kind === 'user' && principal.userId === LOCAL_SOCKET_USER_ID
+        && principal.credentialId === LOCAL_SOCKET_CREDENTIAL_ID;
+}
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export function isGlobalOwnerPrincipal(principal) {
+    return isUserPrincipal(principal)
+        && principal.grants.some((grant) => grant.role === 'owner' && grant.scope.kind === 'global');
+}
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.

package/lib/console-rpc-handlers.js

@@ -1,4 +1,4 @@
-import { CONFIG_PATCH_LIMITS, CONSOLE_SEND_FAILURE_MESSAGES, ENDPOINT_RPC, classifyConsoleSendFailure, } from '@zhin.js/console-protocol';
+import { CONFIG_PATCH_LIMITS, CONSOLE_SEND_FAILURE_MESSAGES, ENDPOINT_RPC, classifyConsoleSendFailure, endpointTransportLabel, } from '@zhin.js/console-protocol';
 /** Canonical Console wire fields → runtime conversation address. */
 export function wireConversation(channelType, channelId, parent) {
     const kind = channelType === 'group' || channelType === 'channel' ? channelType : 'private';
@@ -595,7 +595,7 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
         case 'endpoint.list': {
             try {
                 const endpoints = ctx.listEndpoints ? await ctx.listEndpoints() : [];
-                emit({ requestId, data: { endpoints } });
+                emit({ requestId, data: { endpoints: endpoints.map(withTransportLabel) } });
             }
             catch (error) {
                 emit({
@@ -623,7 +623,7 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
                     emit({ requestId, error: 'endpoint not found' });
                     return true;
                 }
-                emit({ requestId, data: endpoint });
+                emit({ requestId, data: withTransportLabel(endpoint) });
             }
             catch (error) {
                 emit({
@@ -828,3 +828,12 @@ export function configurationSaveMessage(result) {
     }
     return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
+/** Adds the readable `transportLabel` next to the raw `transportState` of an Endpoint row (#1250). */
+function withTransportLabel(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return endpoint;
+    const state = endpoint.transportState;
+    if (typeof state !== 'string')
+        return endpoint;
+    return { ...endpoint, transportLabel: endpointTransportLabel(state) };
+}

package/lib/console-rpc.js

@@ -283,7 +283,11 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 return payloads;
             }
             const projectPatch = message.type === CONFIG_RPC.PATCH_PROJECT;
-            const { instanceKey, expectedRevision, patches } = message;
+            const { instanceKey, expectedRevision, patches, secretStorage } = message;
+            if (secretStorage !== undefined && secretStorage !== 'env' && secretStorage !== 'plain') {
+                emit({ requestId, error: 'secretStorage 只能是 env 或 plain' });
+                return payloads;
+            }
             if (projectPatch && instanceKey !== undefined) {
                 emit({ requestId, error: 'Project patches must not specify instanceKey' });
                 return payloads;
@@ -318,6 +322,7 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                     ...(instanceKey === undefined ? {} : { instanceKey }),
                     expectedRevision,
                     patches,
+                    ...(secretStorage === undefined ? {} : { secretStorage }),
                 });
             }
             catch (error) {
@@ -382,9 +387,11 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 });
             }
             catch (error) {
+                const code = error instanceof Error && 'code' in error && error.code === 'env-write-required' ? { code: 'env-write-required' } : {};
                 emit({
                     requestId,
                     error: `Failed to set config: ${error instanceof Error ? error.message : String(error)}`,
+                    ...code,
                 });
             }
             return payloads;

package/lib/host-installer.js

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
 import { httpHostToken } from './http-host.js';
 import { parseTrustProxy } from './trust-proxy.js';
+import { parseHttpPort } from './port.js';
 export async function resolveHttpConfig(config, envOverlay, projectRoot = process.cwd()) {
     const document = await readConfigDocument(config);
     if (!document || typeof document !== 'object')
@@ -11,18 +12,20 @@ export async function resolveHttpConfig(config, envOverlay, projectRoot = proces
     if (!http || typeof http !== 'object')
         return {};
     const value = expandEnvironmentValue(http, (key) => envOverlay?.[key] ?? process.env[key]);
+    const stored = http;
     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,
+        // An invalid port is an error, never a silent fallback to the default (#1250).
+        port: parseHttpPort(value.port, 'http.port', stored.port),
         token: typeof value.token === 'string' ? value.token : undefined,
         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 configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot, stored.listeners);
     const listeners = await injectDesktopDeviceListener(configuredListeners, primary, envOverlay, projectRoot);
     return Object.freeze({ ...primary, ...(listeners.length > 0 ? { listeners } : {}) });
 }
@@ -71,7 +74,7 @@ async function injectDesktopDeviceListener(configured, primary, envOverlay, proj
     }, projectRoot);
     return Object.freeze([...configured, Object.freeze({ ...primary, host, port, tls })]);
 }
-async function parseAdditionalListeners(value, primary, projectRoot) {
+async function parseAdditionalListeners(value, primary, projectRoot, stored) {
     if (value === undefined)
         return Object.freeze([]);
     if (!Array.isArray(value))
@@ -87,13 +90,15 @@ async function parseAdditionalListeners(value, primary, projectRoot) {
         if (typeof listener.host !== 'string' || !listener.host) {
             throw new Error(`http.listeners[${index}].host is required`);
         }
-        if (typeof listener.port !== 'number') {
+        const storedPort = Array.isArray(stored) ? stored[index]?.port : undefined;
+        const port = parseHttpPort(listener.port, `http.listeners[${index}].port`, storedPort);
+        if (port === undefined) {
             throw new Error(`http.listeners[${index}].port is required`);
         }
         listeners.push(Object.freeze({
             ...primary,
             host: listener.host,
-            port: listener.port,
+            port,
             tls: await parseTlsConfig(listener.tls, projectRoot),
         }));
     }

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpRequestInfo, type HttpRouter, type HttpRouterOptions, type HttpRouteRegistration, type RouteContext, type WsConnection, type WsHandle, type WsRouteOptions, type WsTransport, type WsUpgradeDecision, type WsUpgradeRequest, type ListedWsRoute, } from './http-host.js';
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
+export { DEFAULT_HTTP_PORT, ENVIRONMENT_REFERENCE_PATTERN, InvalidHttpPortError, describeInvalidPortValue, parseHttpPort, } from './port.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type TokenRegistryConfig, } from './token-registry.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 { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, type AuthorizeConsoleRpcOptions, isUserPrincipal, isExplicitConsolePrincipal, isGlobalOwnerPrincipal, isLocalSocketPrincipal, LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID, 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';

package/lib/index.js

@@ -1,7 +1,8 @@
 export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
 export { listHttpHostAddresses } from './addresses.js';
+export { DEFAULT_HTTP_PORT, ENVIRONMENT_REFERENCE_PATTERN, InvalidHttpPortError, describeInvalidPortValue, parseHttpPort, } from './port.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, isUserPrincipal, isExplicitConsolePrincipal, isGlobalOwnerPrincipal, isLocalSocketPrincipal, LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID, 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';

package/lib/node/listener.js

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

package/lib/port.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `http.port` (and `http.listeners[].port`): an integer from 1 to 65535, written either as a number
+ * or as a `${VAR}` environment reference that expands to one (#1250); `0` keeps its listener meaning
+ * (the system picks a free port — tests and embedded use). Anything else is a configuration error:
+ * the Host never falls back to the default port for an invalid value.
+ */
+/** Port the Host listens on when `http.port` is not configured (same as the scaffold writes). */
+export declare const DEFAULT_HTTP_PORT = 8068;
+/** A whole `${VAR}` / `${VAR:-default}` reference (the form the config schema accepts for a port). */
+export declare const ENVIRONMENT_REFERENCE_PATTERN: RegExp;
+export declare class InvalidHttpPortError extends Error {
+    readonly field: string;
+    readonly value: unknown;
+    readonly reason: string;
+    constructor(field: string, value: unknown, reason: string);
+}
+/**
+ * Why a stored (unexpanded) port value is invalid, in Chinese; undefined when it is valid.
+ * `undefined` / `null` (not configured) are valid; `${VAR}` references are checked after expansion.
+ */
+export declare function describeInvalidPortValue(value: unknown): string | undefined;
+/**
+ * The listening port from an expanded config value (`${VAR}` already replaced: a digit string is
+ * accepted). Returns undefined when not configured; throws {@link InvalidHttpPortError} otherwise.
+ * `raw` is the stored value, named in the message when it was an environment reference.
+ */
+export declare function parseHttpPort(value: unknown, field: string, raw?: unknown): number | undefined;

package/lib/port.js

@@ -0,0 +1,68 @@
+/**
+ * `http.port` (and `http.listeners[].port`): an integer from 1 to 65535, written either as a number
+ * or as a `${VAR}` environment reference that expands to one (#1250); `0` keeps its listener meaning
+ * (the system picks a free port — tests and embedded use). Anything else is a configuration error:
+ * the Host never falls back to the default port for an invalid value.
+ */
+/** Port the Host listens on when `http.port` is not configured (same as the scaffold writes). */
+export const DEFAULT_HTTP_PORT = 8068;
+/** A whole `${VAR}` / `${VAR:-default}` reference (the form the config schema accepts for a port). */
+export const ENVIRONMENT_REFERENCE_PATTERN = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(?::[-=][^}]*)?\}$/u;
+export class InvalidHttpPortError extends Error {
+    field;
+    value;
+    reason;
+    constructor(field, value, reason) {
+        super(`${field} 无效：${reason}`);
+        this.field = field;
+        this.value = value;
+        this.reason = reason;
+        this.name = 'InvalidHttpPortError';
+    }
+}
+function show(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+/**
+ * Why a stored (unexpanded) port value is invalid, in Chinese; undefined when it is valid.
+ * `undefined` / `null` (not configured) are valid; `${VAR}` references are checked after expansion.
+ */
+export function describeInvalidPortValue(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value))
+            return `端口必须是整数，当前值 ${value}`;
+        if (value < 0 || value > 65_535)
+            return `端口必须在 1–65535 之间，当前值 ${value}`;
+        return undefined;
+    }
+    if (typeof value === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(value.trim()))
+        return undefined;
+    return `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}`;
+}
+/**
+ * The listening port from an expanded config value (`${VAR}` already replaced: a digit string is
+ * accepted). Returns undefined when not configured; throws {@link InvalidHttpPortError} otherwise.
+ * `raw` is the stored value, named in the message when it was an environment reference.
+ */
+export function parseHttpPort(value, field, raw) {
+    if (value === undefined || value === null)
+        return undefined;
+    const fromReference = typeof raw === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(raw.trim()) ? `（来自 ${raw.trim()}）` : '';
+    let port;
+    if (typeof value === 'number')
+        port = value;
+    else if (typeof value === 'string' && /^\d+$/u.test(value.trim()))
+        port = Number(value.trim());
+    else if (typeof value === 'string' && value.trim() === '' && fromReference) {
+        throw new InvalidHttpPortError(field, value, `环境变量未设置或为空${fromReference}；请在 .env 中设置为 1–65535 的整数`);
+    }
+    else {
+        throw new InvalidHttpPortError(field, value, `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}${fromReference}`);
+    }
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new InvalidHttpPortError(field, value, `端口必须在 1–65535 之间，当前值 ${show(value)}${fromReference}`);
+    }
+    return port;
+}

package/package.json

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

package/src/access-control.ts

@@ -88,6 +88,25 @@ export function isUserPrincipal(principal: ConsolePrincipal | undefined): princi
   return principal?.kind === 'user' || principal?.kind === 'api-token';
 }
 
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export const LOCAL_SOCKET_USER_ID = 'local';
+export const LOCAL_SOCKET_CREDENTIAL_ID = 'local-socket';
+
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export function isLocalSocketPrincipal(principal: ConsolePrincipal | undefined): boolean {
+  return principal?.kind === 'user' && principal.userId === LOCAL_SOCKET_USER_ID
+    && principal.credentialId === LOCAL_SOCKET_CREDENTIAL_ID;
+}
+
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export function isGlobalOwnerPrincipal(principal: ConsolePrincipal | undefined): boolean {
+  return isUserPrincipal(principal)
+    && principal.grants.some((grant) => grant.role === 'owner' && grant.scope.kind === 'global');
+}
+
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.

package/src/console-rpc-handlers.ts

@@ -3,6 +3,7 @@ import {
   CONSOLE_SEND_FAILURE_MESSAGES,
   ENDPOINT_RPC,
   classifyConsoleSendFailure,
+  endpointTransportLabel,
   type ConsoleConfigApplicationStatus,
   type ConsoleSendFailure,
   type ConsoleSendFailureStatus,
@@ -529,7 +530,7 @@ export async function dispatchHostResourceConsoleRpc(
     case 'endpoint.list': {
       try {
         const endpoints = ctx.listEndpoints ? await ctx.listEndpoints() : [];
-        emit({ requestId, data: { endpoints } });
+        emit({ requestId, data: { endpoints: endpoints.map(withTransportLabel) } });
       } catch (error) {
         emit({
           requestId,
@@ -556,7 +557,7 @@ export async function dispatchHostResourceConsoleRpc(
           emit({ requestId, error: 'endpoint not found' });
           return true;
         }
-        emit({ requestId, data: endpoint });
+        emit({ requestId, data: withTransportLabel(endpoint) });
       } catch (error) {
         emit({
           requestId,
@@ -764,3 +765,11 @@ export function configurationSaveMessage(result: { restartRequired: boolean; rev
   return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
 
+
+/** Adds the readable `transportLabel` next to the raw `transportState` of an Endpoint row (#1250). */
+function withTransportLabel<T>(endpoint: T): T {
+  if (!endpoint || typeof endpoint !== 'object') return endpoint;
+  const state = (endpoint as { transportState?: unknown }).transportState;
+  if (typeof state !== 'string') return endpoint;
+  return { ...endpoint, transportLabel: endpointTransportLabel(state) };
+}

package/src/console-rpc.ts

@@ -534,7 +534,11 @@ export async function dispatchRuntimeConsoleRpc(
     case CONFIG_RPC.PATCH: {
       if (ctx.authScope !== 'full') { emit({ requestId, error: 'Full scope required' }); return payloads; }
       const projectPatch = message.type === CONFIG_RPC.PATCH_PROJECT;
-      const { instanceKey, expectedRevision, patches } = message;
+      const { instanceKey, expectedRevision, patches, secretStorage } = message;
+      if (secretStorage !== undefined && secretStorage !== 'env' && secretStorage !== 'plain') {
+        emit({ requestId, error: 'secretStorage 只能是 env 或 plain' });
+        return payloads;
+      }
       if (projectPatch && instanceKey !== undefined) {
         emit({ requestId, error: 'Project patches must not specify instanceKey' });
         return payloads;
@@ -566,6 +570,7 @@ export async function dispatchRuntimeConsoleRpc(
           ...(instanceKey === undefined ? {} : { instanceKey }),
           expectedRevision,
           patches,
+          ...(secretStorage === undefined ? {} : { secretStorage }),
         });
       } catch (error) {
         emit({
@@ -627,9 +632,11 @@ export async function dispatchRuntimeConsoleRpc(
           },
         });
       } catch (error) {
+        const code = error instanceof Error && 'code' in error && error.code === 'env-write-required' ? { code: 'env-write-required' } : {};
         emit({
           requestId,
           error: `Failed to set config: ${error instanceof Error ? error.message : String(error)}`,
+          ...code,
         });
       }
       return payloads;

package/src/host-installer.ts

@@ -11,6 +11,7 @@ import { isAbsolute, resolve } from 'node:path';
 import { httpHostToken, type HttpHost } from './http-host.js';
 import type { HttpHostOptions } from './host-options.js';
 import { parseTrustProxy } from './trust-proxy.js';
+import { parseHttpPort } from './port.js';
 
 export interface ResolvedHttpConfig extends HttpHostOptions {
   /** Additional listeners that mirror the primary Host route surface. */
@@ -30,17 +31,19 @@ export async function resolveHttpConfig(
     http,
     (key) => envOverlay?.[key] ?? process.env[key],
   ) as Record<string, unknown>;
+  const stored = http 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,
+    // An invalid port is an error, never a silent fallback to the default (#1250).
+    port: parseHttpPort(value.port, 'http.port', stored.port),
     token: typeof value.token === 'string' ? value.token : undefined,
     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 configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot, stored.listeners);
   const listeners = await injectDesktopDeviceListener(
     configuredListeners,
     primary,
@@ -110,6 +113,7 @@ async function parseAdditionalListeners(
   value: unknown,
   primary: HttpHostOptions,
   projectRoot: string,
+  stored?: unknown,
 ): Promise<readonly HttpHostOptions[]> {
   if (value === undefined) return Object.freeze([]);
   if (!Array.isArray(value)) throw new Error('http.listeners must be an array');
@@ -123,13 +127,15 @@ async function parseAdditionalListeners(
     if (typeof listener.host !== 'string' || !listener.host) {
       throw new Error(`http.listeners[${index}].host is required`);
     }
-    if (typeof listener.port !== 'number') {
+    const storedPort = Array.isArray(stored) ? (stored[index] as Record<string, unknown> | undefined)?.port : undefined;
+    const port = parseHttpPort(listener.port, `http.listeners[${index}].port`, storedPort);
+    if (port === undefined) {
       throw new Error(`http.listeners[${index}].port is required`);
     }
     listeners.push(Object.freeze({
       ...primary,
       host: listener.host,
-      port: listener.port,
+      port,
       tls: await parseTlsConfig(listener.tls, projectRoot),
     }));
   }

package/src/index.ts

@@ -20,6 +20,13 @@ export {
 } from './http-host.js';
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
+export {
+  DEFAULT_HTTP_PORT,
+  ENVIRONMENT_REFERENCE_PATTERN,
+  InvalidHttpPortError,
+  describeInvalidPortValue,
+  parseHttpPort,
+} from './port.js';
 export {
   TokenRegistry,
   extractBearerToken,
@@ -43,6 +50,10 @@ export {
   type AuthorizeConsoleRpcOptions,
   isUserPrincipal,
   isExplicitConsolePrincipal,
+  isGlobalOwnerPrincipal,
+  isLocalSocketPrincipal,
+  LOCAL_SOCKET_CREDENTIAL_ID,
+  LOCAL_SOCKET_USER_ID,
   pluginRpcWriteAllowed,
   principalAllows,
   requestMeta,

package/src/node/listener.ts

@@ -21,6 +21,7 @@ import { WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { HttpRequestInfo, WsUpgradeDecision, WsUpgradeRequest } from '../http-host.js';
 import type { HttpHostAddress, HttpHostTlsOptions } from '../host-options.js';
+import { DEFAULT_HTTP_PORT } from '../port.js';
 import { compileTrustProxy, resolveClientAddress, type TrustProxySetting } from '../trust-proxy.js';
 import { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket } from './node-http.js';
 
@@ -52,7 +53,7 @@ export interface NodeHttpListener {
 /** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
 export function createNodeHttpListener(options: NodeHttpListenerOptions): NodeHttpListener {
   const host = options.host ?? '127.0.0.1';
-  const port = options.port ?? 8086;
+  const port = options.port ?? DEFAULT_HTTP_PORT;
   const secure = options.tls !== undefined;
   let address: HttpHostAddress | undefined;
   let closed = false;

package/src/port.ts

@@ -0,0 +1,60 @@
+/**
+ * `http.port` (and `http.listeners[].port`): an integer from 1 to 65535, written either as a number
+ * or as a `${VAR}` environment reference that expands to one (#1250); `0` keeps its listener meaning
+ * (the system picks a free port — tests and embedded use). Anything else is a configuration error:
+ * the Host never falls back to the default port for an invalid value.
+ */
+
+/** Port the Host listens on when `http.port` is not configured (same as the scaffold writes). */
+export const DEFAULT_HTTP_PORT = 8068;
+
+/** A whole `${VAR}` / `${VAR:-default}` reference (the form the config schema accepts for a port). */
+export const ENVIRONMENT_REFERENCE_PATTERN = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(?::[-=][^}]*)?\}$/u;
+
+export class InvalidHttpPortError extends Error {
+  constructor(readonly field: string, readonly value: unknown, readonly reason: string) {
+    super(`${field} 无效：${reason}`);
+    this.name = 'InvalidHttpPortError';
+  }
+}
+
+function show(value: unknown): string {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
+/**
+ * Why a stored (unexpanded) port value is invalid, in Chinese; undefined when it is valid.
+ * `undefined` / `null` (not configured) are valid; `${VAR}` references are checked after expansion.
+ */
+export function describeInvalidPortValue(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value)) return `端口必须是整数，当前值 ${value}`;
+    if (value < 0 || value > 65_535) return `端口必须在 1–65535 之间，当前值 ${value}`;
+    return undefined;
+  }
+  if (typeof value === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(value.trim())) return undefined;
+  return `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}`;
+}
+
+/**
+ * The listening port from an expanded config value (`${VAR}` already replaced: a digit string is
+ * accepted). Returns undefined when not configured; throws {@link InvalidHttpPortError} otherwise.
+ * `raw` is the stored value, named in the message when it was an environment reference.
+ */
+export function parseHttpPort(value: unknown, field: string, raw?: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const fromReference = typeof raw === 'string' && ENVIRONMENT_REFERENCE_PATTERN.test(raw.trim()) ? `（来自 ${raw.trim()}）` : '';
+  let port: number;
+  if (typeof value === 'number') port = value;
+  else if (typeof value === 'string' && /^\d+$/u.test(value.trim())) port = Number(value.trim());
+  else if (typeof value === 'string' && value.trim() === '' && fromReference) {
+    throw new InvalidHttpPortError(field, value, `环境变量未设置或为空${fromReference}；请在 .env 中设置为 1–65535 的整数`);
+  } else {
+    throw new InvalidHttpPortError(field, value, `端口必须是 1–65535 的整数或 \${VAR} 形式的环境变量引用，当前值 ${show(value)}${fromReference}`);
+  }
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new InvalidHttpPortError(field, value, `端口必须在 1–65535 之间，当前值 ${show(value)}${fromReference}`);
+  }
+  return port;
+}