@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.1

package/dist/net/auth.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 凭证的校验与本地凭证的生成/交付（architecture §2 / PRD A5、L11）。
+ *
+ * 真相在库里：`credentials` 表一列存 sha256 摘要，明文只在两处出现 —— 创建时回给创建者的那一次，
+ * 以及本地凭证写进 `<dataRoot>/run/token` 的那一份。于是「多串、带备注、可单独吊销」全部由库承担，
+ * 本文件只做两件事：
+ *
+ *   1. {@link verify}：一串明文 → 库里仍有效的那一行（没命中就是 `null`）。
+ *   2. {@link createLocalCredential}：本地实例首次启动时造一串（备注 `local`）并写进交付文件。
+ *
+ * **所有连接都要凭证**（PRD A5）：本地实例的「无感」来自「凭证已在交付文件里被客户端取走」，
+ * 不是来自「回环地址免检」—— 所以这里没有任何「从 127.0.0.1 来就放行」的分支。
+ */
+import type { HostPaths } from "../config.js";
+import type { Database } from "../storage/Database.js";
+/** 本地凭证的备注：与用户在 `agents-host token create --note` 里自己写的备注区分开 */
+export declare const LOCAL_CREDENTIAL_NOTE = "local";
+/** 校验通过的凭证：只给「哪一串」，不含摘要与明文 */
+export interface VerifiedCredential {
+    id: string;
+    note: string;
+}
+/**
+ * 校验一串凭证。
+ *
+ * 交给接线层的注入形状：`hello` 带上来的是明文，校验方只需要回答「这串还算数吗、是哪一串」。
+ * 用法是「每条连接在 `hello` 时校验一次」，所以吊销对已经握过手的连接不回头生效
+ * （吊销是「以后连不上」，不是「把别人踢下线」）。
+ */
+export interface TokenVerifier {
+    verify(token: string): Promise<VerifiedCredential | null>;
+}
+/**
+ * 一串明文 → 库里仍有效的那一行。
+ *
+ * 空串一律不通过：库里不会存在空串的摘要，但把「客户端漏传 token」与「token 不对」分成两种
+ * 结果没有意义 —— 两者都是「这串不被接受」。
+ */
+export declare function verify(db: Database, token: string): Promise<VerifiedCredential | null>;
+/** 把 {@link verify} 包成注入用的对象（`WsHub` 收的就是这个形状） */
+export declare function createTokenVerifier(db: Database): TokenVerifier;
+/** `createLocalCredential` 的可选项 */
+export interface LocalCredentialOptions {
+    /** 备注，缺省 `local` */
+    note?: string;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+    /** 随机字节数，缺省 32（测试里可以调小） */
+    tokenBytes?: number;
+    /** 强制轮换：不管交付文件里那串是否还有效，都造一串新的并重写文件 */
+    rotate?: boolean;
+}
+/** 本地凭证的生成结果 */
+export interface LocalCredentialResult {
+    /** 库里那一行的 id（吊销时用它） */
+    credentialId: string;
+    /** 明文；此后再也拿不到第二份，除非又读交付文件 */
+    token: string;
+    /** 这次是不是真的新造了一串（`false` 表示复用了交付文件里那串） */
+    created: boolean;
+}
+/**
+ * 取（必要时先生成）本地凭证，并保证 `<dataRoot>/run/token` 里是**当前可用**的那一串。
+ *
+ * 三种情形：
+ *   - 交付文件有内容且库里仍有效 → 直接复用（绝大多数启动走这条，不会每次重启都造新串）；
+ *   - 交付文件有内容但已吊销 / 库里查不到 → 造一串新的并重写文件（旧串已经无效，留着文件只会让人连不上）;
+ *   - 交付文件不在 → 造一串新的并写进去。
+ *
+ * 「库里已有别的有效凭证、但交付文件被用户删了」也会造新串：交付文件是明文的唯一副本，
+ * 删掉之后那串明文无从复原，再造一串是唯一能让本地客户端连上的做法。
+ */
+export declare function createLocalCredential(db: Database, paths: HostPaths, options?: LocalCredentialOptions): Promise<LocalCredentialResult>;

package/dist/net/auth.js

@@ -0,0 +1,74 @@
+/**
+ * 凭证的校验与本地凭证的生成/交付（architecture §2 / PRD A5、L11）。
+ *
+ * 真相在库里：`credentials` 表一列存 sha256 摘要，明文只在两处出现 —— 创建时回给创建者的那一次，
+ * 以及本地凭证写进 `<dataRoot>/run/token` 的那一份。于是「多串、带备注、可单独吊销」全部由库承担，
+ * 本文件只做两件事：
+ *
+ *   1. {@link verify}：一串明文 → 库里仍有效的那一行（没命中就是 `null`）。
+ *   2. {@link createLocalCredential}：本地实例首次启动时造一串（备注 `local`）并写进交付文件。
+ *
+ * **所有连接都要凭证**（PRD A5）：本地实例的「无感」来自「凭证已在交付文件里被客户端取走」，
+ * 不是来自「回环地址免检」—— 所以这里没有任何「从 127.0.0.1 来就放行」的分支。
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { CredentialRepository, hashCredential } from "../storage/CredentialRepository.js";
+import { readLocalToken, writeLocalToken } from "./discovery.js";
+/** 本地凭证的备注：与用户在 `agents-host token create --note` 里自己写的备注区分开 */
+export const LOCAL_CREDENTIAL_NOTE = "local";
+/** 凭证明文（base64url）的随机字节数；32 字节 → 43 个字符 */
+const DEFAULT_TOKEN_BYTES = 32;
+/**
+ * 一串明文 → 库里仍有效的那一行。
+ *
+ * 空串一律不通过：库里不会存在空串的摘要，但把「客户端漏传 token」与「token 不对」分成两种
+ * 结果没有意义 —— 两者都是「这串不被接受」。
+ */
+export async function verify(db, token) {
+    const plain = typeof token === "string" ? token.trim() : "";
+    if (plain === "")
+        return null;
+    const credentials = new CredentialRepository(db);
+    const row = await credentials.findActiveByHash(hashCredential(plain));
+    return row === undefined ? null : { id: row.id, note: row.note };
+}
+/** 把 {@link verify} 包成注入用的对象（`WsHub` 收的就是这个形状） */
+export function createTokenVerifier(db) {
+    return {
+        verify: (token) => verify(db, token),
+    };
+}
+/**
+ * 取（必要时先生成）本地凭证，并保证 `<dataRoot>/run/token` 里是**当前可用**的那一串。
+ *
+ * 三种情形：
+ *   - 交付文件有内容且库里仍有效 → 直接复用（绝大多数启动走这条，不会每次重启都造新串）；
+ *   - 交付文件有内容但已吊销 / 库里查不到 → 造一串新的并重写文件（旧串已经无效，留着文件只会让人连不上）;
+ *   - 交付文件不在 → 造一串新的并写进去。
+ *
+ * 「库里已有别的有效凭证、但交付文件被用户删了」也会造新串：交付文件是明文的唯一副本，
+ * 删掉之后那串明文无从复原，再造一串是唯一能让本地客户端连上的做法。
+ */
+export async function createLocalCredential(db, paths, options = {}) {
+    const credentials = new CredentialRepository(db);
+    const note = options.note ?? LOCAL_CREDENTIAL_NOTE;
+    if (options.rotate !== true) {
+        const existing = await readLocalToken(paths);
+        if (existing !== null) {
+            const verified = await verify(db, existing);
+            if (verified !== null) {
+                return { credentialId: verified.id, token: existing, created: false };
+            }
+        }
+    }
+    const token = randomBytes(options.tokenBytes ?? DEFAULT_TOKEN_BYTES).toString("base64url");
+    const id = randomUUID();
+    await credentials.create({
+        id,
+        note,
+        hash: hashCredential(token),
+        createdAt: (options.now ?? Date.now)(),
+    });
+    await writeLocalToken(paths, token);
+    return { credentialId: id, token, created: true };
+}

package/dist/net/discovery.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 发现文件与本地凭证交付口（architecture §2）。
+ *
+ * 两个文件、两种用途：
+ *
+ * - `<dataRoot>/run/host.json` 是「这台机器上谁在服务」的唯一真相：进程 id、监听的地址与端口、
+ *   版本、是不是本地实例、启动时刻。客户端探活与宿主启动时自查都读它，两边不各写一份。
+ * - `<dataRoot>/run/token` 是**本地凭证的交付口**：内容只有本地那串凭证，客户端首次连接时
+ *   自动取走。凭证自己的真相在库里（可列出、带备注、可单独吊销），这里只是一份「给本机进程读」的副本。
+ *
+ * 目录由本文件按需创建：`run/` 与 `assets/` 都可能在首次启动时还不存在。
+ */
+import type { HostPaths } from "../config.js";
+/**
+ * `run/host.json` 的形状。
+ *
+ * `host` 是**实际监听**的地址（本地实例是 `127.0.0.1`，对外实例是调用方指定的地址），
+ * `port` 是实际端口 —— 端口被占时宿主会退回系统分配的临时端口，所以客户端不能按「启动参数里的端口」
+ * 去连，只能读这个文件。
+ */
+export interface HostFileInfo {
+    /** 宿主进程 id（客户端据此判断「上次那个进程还在不在」） */
+    pid: number;
+    host: string;
+    port: number;
+    /** 宿主版本（升级判定要比对磁盘上的版本，PRD D4） */
+    version: string;
+    /** 是不是本地实例（`true` 只监听回环，`false` 是创建者起的对外实例） */
+    local: boolean;
+    /** 启动时刻，ISO 8601 */
+    startedAt: string;
+}
+/**
+ * 写发现文件。
+ *
+ * 先写同目录的临时文件再 `rename`：读的一方要么看到上一份完整内容，要么看到这一份完整内容，
+ * 不会读到「写了一半的 JSON」（客户端探活正是高频读它的那一个）。
+ */
+export declare function writeHostFile(paths: HostPaths, info: HostFileInfo): Promise<void>;
+/**
+ * 读发现文件。
+ *
+ * 三种结果分开给：文件不存在 → `null`（还没起过宿主）；内容坏了 → 抛 `config_invalid`
+ * （「文件不存在」与「文件坏了」必须能分开，PRD F-F6 对配置文件说的是同一件事）；
+ * 正常 → 解析后的形状。
+ *
+ * 本函数**不判断**那个 pid 是否还活着：探活是调用方的事（这里只有文件，没有进程表）。
+ */
+export declare function readHostFile(paths: HostPaths): Promise<HostFileInfo | null>;
+/**
+ * 清掉发现文件（进程收尾时用）。
+ *
+ * 文件本来就不在时不算失败：收尾动作要能被重复执行，不能因为「已经删过一次」而报错。
+ */
+export declare function clearHostFile(paths: HostPaths): Promise<void>;
+/**
+ * 写本地凭证交付文件（权限尽力而为地设成 `0600`）。
+ *
+ * 关于 `0600`：在 POSIX 上它让「同机其他用户」读不到这串凭证；在 Windows 上 `mode` 与
+ * `chmod` 都不改变 ACL（那里是空操作），实际保护来自用户目录本身的访问控制。
+ * 所以这里是**尽力而为**：设不上不报错，也不构成任何安全保证。
+ */
+export declare function writeLocalToken(paths: HostPaths, token: string): Promise<void>;
+/**
+ * 读本地凭证交付文件。
+ *
+ * 文件不存在 → `null`（还没生成过）；内容为空 → `null`（等同于没有）。其余读写错误向上抛：
+ * 权限问题与「文件不在」是两件事，混成 `null` 会让首次启动悄悄再造一串凭证。
+ */
+export declare function readLocalToken(paths: HostPaths): Promise<string | null>;
+/** 清掉本地凭证交付文件（凭证被吊销 / 轮换时顺手做的事） */
+export declare function clearLocalToken(paths: HostPaths): Promise<void>;

package/dist/net/discovery.js

@@ -0,0 +1,171 @@
+/**
+ * 发现文件与本地凭证交付口（architecture §2）。
+ *
+ * 两个文件、两种用途：
+ *
+ * - `<dataRoot>/run/host.json` 是「这台机器上谁在服务」的唯一真相：进程 id、监听的地址与端口、
+ *   版本、是不是本地实例、启动时刻。客户端探活与宿主启动时自查都读它，两边不各写一份。
+ * - `<dataRoot>/run/token` 是**本地凭证的交付口**：内容只有本地那串凭证，客户端首次连接时
+ *   自动取走。凭证自己的真相在库里（可列出、带备注、可单独吊销），这里只是一份「给本机进程读」的副本。
+ *
+ * 目录由本文件按需创建：`run/` 与 `assets/` 都可能在首次启动时还不存在。
+ */
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { HostError } from "../wire/errors.js";
+/**
+ * 写发现文件。
+ *
+ * 先写同目录的临时文件再 `rename`：读的一方要么看到上一份完整内容，要么看到这一份完整内容，
+ * 不会读到「写了一半的 JSON」（客户端探活正是高频读它的那一个）。
+ */
+export async function writeHostFile(paths, info) {
+    await fs.mkdir(paths.runDir, { recursive: true });
+    const content = `${JSON.stringify(info, null, 2)}\n`;
+    await writeAtomic(paths.hostFile, content);
+}
+/**
+ * 读发现文件。
+ *
+ * 三种结果分开给：文件不存在 → `null`（还没起过宿主）；内容坏了 → 抛 `config_invalid`
+ * （「文件不存在」与「文件坏了」必须能分开，PRD F-F6 对配置文件说的是同一件事）；
+ * 正常 → 解析后的形状。
+ *
+ * 本函数**不判断**那个 pid 是否还活着：探活是调用方的事（这里只有文件，没有进程表）。
+ */
+export async function readHostFile(paths) {
+    let text;
+    try {
+        text = await fs.readFile(paths.hostFile, "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw brokenHostFile(paths.hostFile, "it is not valid JSON", error);
+    }
+    return parseHostFileInfo(value, paths.hostFile);
+}
+/**
+ * 清掉发现文件（进程收尾时用）。
+ *
+ * 文件本来就不在时不算失败：收尾动作要能被重复执行，不能因为「已经删过一次」而报错。
+ */
+export async function clearHostFile(paths) {
+    try {
+        await fs.unlink(paths.hostFile);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return;
+        throw error;
+    }
+}
+/**
+ * 写本地凭证交付文件（权限尽力而为地设成 `0600`）。
+ *
+ * 关于 `0600`：在 POSIX 上它让「同机其他用户」读不到这串凭证；在 Windows 上 `mode` 与
+ * `chmod` 都不改变 ACL（那里是空操作），实际保护来自用户目录本身的访问控制。
+ * 所以这里是**尽力而为**：设不上不报错，也不构成任何安全保证。
+ */
+export async function writeLocalToken(paths, token) {
+    await fs.mkdir(paths.runDir, { recursive: true });
+    await fs.writeFile(paths.tokenFile, `${token}\n`, { mode: 0o600 });
+    // 文件已存在时 `mode` 不生效（它只作用于创建），所以显式再设一次；失败按「尽力而为」忽略
+    await fs.chmod(paths.tokenFile, 0o600).catch(() => undefined);
+}
+/**
+ * 读本地凭证交付文件。
+ *
+ * 文件不存在 → `null`（还没生成过）；内容为空 → `null`（等同于没有）。其余读写错误向上抛：
+ * 权限问题与「文件不在」是两件事，混成 `null` 会让首次启动悄悄再造一串凭证。
+ */
+export async function readLocalToken(paths) {
+    let text;
+    try {
+        text = await fs.readFile(paths.tokenFile, "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+    const token = text.trim();
+    return token === "" ? null : token;
+}
+/** 清掉本地凭证交付文件（凭证被吊销 / 轮换时顺手做的事） */
+export async function clearLocalToken(paths) {
+    await fs.rm(paths.tokenFile, { force: true });
+}
+// ---------------------------------------------------------------------------
+// 内部
+// ---------------------------------------------------------------------------
+function isNotFound(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function brokenHostFile(filePath, reason, cause) {
+    return new HostError("config_invalid", {
+        params: { reason },
+        detail: { path: filePath, reason },
+        cause,
+    });
+}
+/**
+ * 校验发现文件的形状。
+ *
+ * 逐字段检查而不是整块断言：坏文件要能指出是哪一项不对（客户端/运维排查时唯一有用的信息）。
+ */
+function parseHostFileInfo(value, filePath) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw brokenHostFile(filePath, "it is not a JSON object");
+    }
+    const record = value;
+    const pid = record.pid;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+        throw brokenHostFile(filePath, "`pid` is not a process id");
+    }
+    const host = record.host;
+    if (typeof host !== "string" || host.trim() === "") {
+        throw brokenHostFile(filePath, "`host` is missing");
+    }
+    const port = record.port;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 0 || port > 65535) {
+        throw brokenHostFile(filePath, "`port` is not a port number");
+    }
+    const version = record.version;
+    if (typeof version !== "string" || version.trim() === "") {
+        throw brokenHostFile(filePath, "`version` is missing");
+    }
+    const local = record.local;
+    if (typeof local !== "boolean") {
+        throw brokenHostFile(filePath, "`local` is not a boolean");
+    }
+    const startedAt = record.startedAt;
+    if (typeof startedAt !== "string" || startedAt.trim() === "") {
+        throw brokenHostFile(filePath, "`startedAt` is missing");
+    }
+    return { pid, host, port, version, local, startedAt };
+}
+/**
+ * 原子写：先写同目录临时文件，再改名。
+ *
+ * 临时文件放在目标同目录，`rename` 才是同一个文件系统内的改名（跨设备的改名会退化成复制）。
+ */
+async function writeAtomic(filePath, content) {
+    const temp = join(dirname(filePath), `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await fs.writeFile(temp, content, { mode: 0o600 });
+        await fs.rename(temp, filePath);
+    }
+    catch (error) {
+        await fs.rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/net/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 接线层出口：发现文件、凭证、上传接收、WebSocket 总线。
+ *
+ * 这一层只做「进程与外界的边界」：握手、分发、推送、二进制分帧。
+ * 业务逻辑在 `services/` 与 `runtime/`，由单根（`app.ts`）注入进来。
+ */
+export { clearLocalToken, clearHostFile, readLocalToken, readHostFile, writeLocalToken, writeHostFile, } from "./discovery.js";
+export type { HostFileInfo } from "./discovery.js";
+export { createLocalCredential, createTokenVerifier, LOCAL_CREDENTIAL_NOTE, verify } from "./auth.js";
+export type { LocalCredentialOptions, LocalCredentialResult, TokenVerifier, VerifiedCredential } from "./auth.js";
+export { decodeChunkFrame, encodeChunkFrame, formatBytes, UploadReceiver } from "./UploadReceiver.js";
+export type { UploadFinalizeRequest, UploadFinalizer, UploadReceiverOptions, } from "./UploadReceiver.js";
+export { WsHub } from "./WsHub.js";
+export type { ConnectionInfo, EventLocalizer, HandlerTable, HubLogger, MethodCallContext, MethodHandler, WsHubOptions, } from "./WsHub.js";

package/dist/net/index.js

@@ -0,0 +1,10 @@
+/**
+ * 接线层出口：发现文件、凭证、上传接收、WebSocket 总线。
+ *
+ * 这一层只做「进程与外界的边界」：握手、分发、推送、二进制分帧。
+ * 业务逻辑在 `services/` 与 `runtime/`，由单根（`app.ts`）注入进来。
+ */
+export { clearLocalToken, clearHostFile, readLocalToken, readHostFile, writeLocalToken, writeHostFile, } from "./discovery.js";
+export { createLocalCredential, createTokenVerifier, LOCAL_CREDENTIAL_NOTE, verify } from "./auth.js";
+export { decodeChunkFrame, encodeChunkFrame, formatBytes, UploadReceiver } from "./UploadReceiver.js";
+export { WsHub } from "./WsHub.js";