@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @zhin.js/gateway
+
+Zhin.js 管理网关（[ADR 0054](../../../docs/adr/0054-management-gateway.md)）。网关负责宿主层面的事：Console 账号与权限、终端、
+项目配置与 `.env`、依赖事务、实例监管。它**不依赖 `zhin.js` 与 IM 层**，不加载插件代码（`pnpm check:architecture` 强制）。
+
+网关进程（`zhin start`；前台运行用 `zhin start --foreground`）自己打开项目数据库并持有 `console_*` 表：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
+都在网关里，没有实例时 Console 照样可用；受管实例只按转发的主体做授权。`--standalone`（开发 / 测试，无网关）的实例仍在进程内
+装配 `installConsoleIam` / `installHostConsoleTerminal`。
+
+## 使用
+
+项目不直接调用本包：`@zhin.js/cli` 的 `zhin start` 启动网关，网关再拉起项目里的 `zhin.js/instance`。新项目由 `create-zhin-app` 生成；已有项目与同批的 `zhin.js`、`@zhin.js/cli` 一起安装（网关与实例之间的控制通道带协议版本，必须一起升级）：
+
+```bash
+pnpm add zhin.js@latest @zhin.js/gateway@latest
+pnpm add -D @zhin.js/cli@latest   # 生产安装别用 --prod 剔除它：zhin start 需要 CLI
+pnpm dev                    # zhin start --foreground --watch source config
+zhin start --mode production --no-watch   # 后台；zhin status / logs -f / restart / stop
+zhin start --foreground --mode production --no-watch   # systemd / Docker / PM2（pnpm start）
+zhin console init           # 首次创建 Console 所有者；之后 http.token 失效
+```
+
+运行时文件：`.zhin/gateway.sock`（本地控制套接字，`0600`）、`.zhin/gateway.json`、`.zhin/logs/instance.log`、`.zhin/logs/gateway.log`。
+命令与退出码见 [zhin start](../../../docs/cli/runtime.md)，升级步骤见[升级到管理网关](../../../docs/migrations/management-gateway.md)。
+
+## 子路径
+
+| 子路径 | 内容 |
+|---|---|
+| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc` |
+| `@zhin.js/gateway/terminal` | Console 终端（ADR 0051）：`TerminalService`、`installHostConsoleTerminal`、`parseTerminalConfig` |
+| `@zhin.js/gateway/config` | 原始配置文件与 `.env` 读写：`ConsoleConfigurationStore`、`readEnvFile` / `writeEnvFile`、配置路径与补丁、Console Schema |
+| `@zhin.js/gateway/plugin-management` | 项目级依赖事务：`PluginManagementWorkflow`、`PluginManagementActivity`、插件用例 |
+| `@zhin.js/gateway/project` | 项目文件工具：`findConfigFile`、`loadRuntimeEnvironmentLayers`、`createTsxModuleLoader`、实例声明迁移、旧配置检测、Node 版本要求 |
+| `@zhin.js/gateway/supervisor` | 实例进程监管 `InstanceSupervisor`：IPC 控制通道（`ready` / `shutdown` / `restart-request`）、崩溃重启与风暴保护、日志采集（环形缓冲 + `.zhin/logs/instance.log` 按大小轮转）；`runSupervisedInstance` 供 `zhin start` 使用 |
+| `@zhin.js/gateway/usage` | 用量统计聚合 |
+| `@zhin.js/gateway/onboarding` | Console 引导（ADR 0053）：`.zhin/onboarding.json` 状态（`OnboardingStateStore`、自动识别已配置步骤）、`OnboardingService`、安装白名单与 `authorizeInstall`、流式 `installPackages` |
+| `@zhin.js/gateway/http` | HTML / SSE 响应工具（实例也导入，不加载 Node HTTP 栈） |
+| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（项目数据库、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
+| `@zhin.js/gateway/database` | 网关自己的项目数据库连接（ADR 0054 §7）：`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`） |
+| `@zhin.js/gateway` | 以上全部 |
+
+```ts
+import { ConsoleIamService } from '@zhin.js/gateway/iam';
+import { findConfigFile } from '@zhin.js/gateway/project';
+```
+
+只导入需要的子路径：根入口会加载全部区域（数据库驱动定义、终端、包管理器调用等）。
+
+## 依赖边界
+
+依赖 `@zhin.js/host-http`、`@zhin.js/database`、`@zhin.js/console-protocol`、`@zhin.js/runtime`（仅配置与项目文件工具）、
+`@zhin.js/plugin-runtime`（契约）与 `@zhin.js/scaffold-wizard`。需要 IM 类型时在本包内定义窄接口，不导入 IM 包。
+终端后端 `node-pty` / `ssh2` 是可选依赖，首次使用时才加载。
+
+## 开发
+
+```bash
+pnpm --filter @zhin.js/gateway build
+pnpm vitest run packages/host/gateway
+```

package/lib/config/ai-config-loader.d.ts

@@ -0,0 +1,22 @@
+export type AiConfigUtils = {
+    /** Startup AI consumer validation and retired-authority rejection; no execution or credential IO. */
+    validateModelRuntimeConfig?: (ai: unknown, hostOwnerId: string) => string[];
+    applyAiConfigFixes: (ai: unknown) => {
+        ai: Record<string, unknown> | undefined;
+        fixes: string[];
+    };
+    /** Retired `ai.agent.*` switches (#735); absent on older agent packages. */
+    findDeprecatedAgentConfigKeys?: (agent: unknown) => Array<{
+        key: string;
+        reason: string;
+    }>;
+    findDeprecatedAgentBindingKeys?: (agents: unknown) => Array<{
+        agent: string;
+        key: string;
+        reason: string;
+    }>;
+    /** `ai.multimodal.perception` validation; absent on older agent packages. */
+    resolvePerceptionConfig?: (raw: unknown, providerAliases?: readonly string[]) => unknown;
+};
+/** 从项目 cwd 向上解析；monorepo 开发时回退到仓库根与源码 import。 */
+export declare function loadAiConfigUtils(cwd: string): AiConfigUtils | null;

package/lib/config/ai-config-loader.js

@@ -0,0 +1,96 @@
+import { createRequire } from 'node:module';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const MODULE_ID = '@zhin.js/agent/config';
+const requireFromCli = createRequire(import.meta.url);
+async function loadMonorepoDevUtils() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const repoRoot = path.resolve(here, '../../../../../');
+        const srcPath = path.join(repoRoot, 'packages/im/agent/src/config/index.ts');
+        if (!fs.existsSync(srcPath))
+            return null;
+        return (await import(pathToFileURL(srcPath).href));
+    }
+    catch {
+        return null;
+    }
+}
+/** Vitest 下 createRequire 会因 development 条件解析到 .ts；用 ESM import 预热 monorepo 源码。 */
+const monorepoDevUtils = await loadMonorepoDevUtils();
+function loadFromAgentPackageJson(agentPkgJson) {
+    const agentDir = path.dirname(agentPkgJson);
+    if (monorepoDevUtils && fs.existsSync(path.join(agentDir, 'src/config/index.ts'))) {
+        return monorepoDevUtils;
+    }
+    const libPath = path.join(agentDir, 'lib/config/index.js');
+    if (!fs.existsSync(libPath))
+        return null;
+    try {
+        return requireFromCli(libPath);
+    }
+    catch {
+        return null;
+    }
+}
+function findAgentPackageJson(dir) {
+    const candidates = [
+        path.join(dir, 'node_modules/@zhin.js/agent/package.json'),
+        path.join(dir, 'node_modules/zhin.js/node_modules/@zhin.js/agent/package.json'),
+        path.join(dir, 'packages/im/agent/package.json'),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function tryRequireFromProject(pkgJson) {
+    try {
+        const req = createRequire(pkgJson);
+        return req(MODULE_ID);
+    }
+    catch {
+        const dir = path.dirname(pkgJson);
+        const agentPkg = findAgentPackageJson(dir);
+        if (agentPkg)
+            return loadFromAgentPackageJson(agentPkg);
+        return null;
+    }
+}
+function walkUpForAgentConfig(startDir, maxDepth = 14) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < maxDepth; i++) {
+        const pkgJson = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            const loaded = tryRequireFromProject(pkgJson);
+            if (loaded)
+                return loaded;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** 从项目 cwd 向上解析；monorepo 开发时回退到仓库根与源码 import。 */
+export function loadAiConfigUtils(cwd) {
+    const fromProject = walkUpForAgentConfig(cwd);
+    if (fromProject)
+        return fromProject;
+    if (monorepoDevUtils)
+        return monorepoDevUtils;
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const repoRoot = path.resolve(here, '../../../../../');
+        const fromRepo = walkUpForAgentConfig(repoRoot, 6);
+        if (fromRepo)
+            return fromRepo;
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}

package/lib/config/configuration-chat-policy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Fixed reason codes; a denial never carries a stored value or schema detail.
+ * - `permission`: role/approval fields (C4), never manageable from chat.
+ * - `scope`: outside the chat scope (C3: Host keys beyond `HOST_CONFIG_PATCH_PATHS`, declarations).
+ * - `leaf`: not a single scalar / scalar-array leaf (no object overwrite or deletion).
+ * - `required`: a required leaf cannot be unset.
+ */
+export type ConfigChatAccessKind = 'sensitive' | 'unknown' | 'missing' | 'permission' | 'scope' | 'leaf' | 'required';
+export declare class ConfigChatAccessError extends Error {
+    readonly kind: ConfigChatAccessKind;
+    constructor(kind: ConfigChatAccessKind);
+}
+/**
+ * Role, approval and allow/deny-list vocabulary (C4): `master`, `trusted`,
+ * `endpoints[*].master/trusted`, `ai.trigger.masters/trusted`, `toolHardGate.*`, and
+ * compound names such as `adminIds`, `ownerId`, `masterId`, `trustedUsers`,
+ * `superUsers`, `whitelist`, `allowlist`, `blacklist` or `bypassMasters`.
+ * Matched by contains/prefix/suffix after normalization (like `sensitiveConfigKey`) so
+ * casing, separators or compounds cannot bypass it. Deliberately fail-closed: an
+ * ordinary key that merely contains a role word (e.g. `masterVolume`) is CLI-only.
+ */
+export declare function isChatPermissionSegment(segment: string): boolean;
+/**
+ * Indirect role binding (M2): `endpoints[*].id|name` is the key that binds leaf
+ * `master`/`trusted` to an account, so remapping it from chat is a permission change.
+ */
+export declare function isChatIdentityRemapPath(path: readonly string[]): boolean;
+/**
+ * M1/B1: a chat `set` never plants a new `${…}` or `env://` reference (even with a
+ * non-credential-looking name), since a later `get` or runtime echo would expand it.
+ * Existing references are untouched by unrelated operations.
+ */
+export declare function assertChatValueHasNoEnvironmentReference(value: unknown, depth?: number): void;
+export interface ChatConfigurationScope {
+    /** Host-owned top-level keys (Runtime `HOST_CONFIG_KEYS`). */
+    readonly hostKeys: readonly string[];
+    /** Host chat whitelist; v1 is exactly `HOST_CONFIG_PATCH_PATHS`. */
+    readonly hostPaths: readonly (readonly string[])[];
+    /** Declaration keys owned by source/plugin management. */
+    readonly declarationKeys: ReadonlySet<string>;
+}
+/** C3/C4 scope gate, checked before any schema proof or value read. */
+export declare function assertChatConfigurationScope(path: readonly string[], scope: ChatConfigurationScope): void;
+/** Whitelisted Host roots reachable from a (possibly shorter) `fields` scope. */
+export declare function chatHostRoots(prefix: readonly string[], scope: ChatConfigurationScope): readonly (readonly string[])[];
+/** Raw JSON Schema only. Unknown branches never confer access. No values are expanded. */
+export declare function assertChatConfigurationAccess(schema: unknown, path: readonly string[], values: readonly unknown[], deep?: boolean, absolutePath?: readonly string[]): void;
+/**
+ * Leaf-only chat writes: the target must resolve to scalars or arrays of scalars in
+ * every schema branch. Object targets would let a parent overwrite/removal bypass
+ * per-child checks, so they are rejected as `leaf`.
+ */
+export declare function chatLeafTypes(schema: unknown, path: readonly string[], values?: readonly unknown[]): readonly string[];
+/** `unset` removes only optional leaves; any branch listing the key as required refuses. */
+export declare function assertChatOptionalLeaf(schema: unknown, path: readonly string[]): void;
+/** Declared leaf paths below `path` (properties only), each still re-checked by the store. */
+export declare function chatConfigurationLeaves(schema: unknown, path: readonly string[], limit?: number): readonly (readonly string[])[];