@bulolo/hermes-link 0.2.0 → 0.2.2

package/README.md

@@ -1,103 +1,120 @@
 # @bulolo/hermes-link
 
-Local companion service and CLI for connecting [Hermes Agent](https://github.com/nousresearch/hermes-agent) to your devices through zhiji.
+本地伴随服务，为 [Hermes Agent](https://github.com/nousresearch/hermes-agent) 提供移动端接入能力，支持局域网直连。
 
-## Requirements
+## 环境要求
 
 - Node.js >= 20
-- A running [Hermes Agent](https://github.com/nousresearch/hermes-agent) installation
+- 已安装并运行的 [Hermes Agent](https://github.com/nousresearch/hermes-agent)
 
-## Installation
+## 安装
 
 ```bash
-npm install -g @bulolo/hermes-link
+npm install -g @bulolo/hermes-link --registry https://registry.npmjs.org
 ```
 
-## Quick Start
+## 快速开始
 
 ```bash
-# Start the background daemon
+# 启动后台服务
 hermeslink start
 
-# Check status
+# 生成配对二维码（手机扫码连接）
+hermeslink pair
+
+# 查看状态
 hermeslink status
 
-# View logs
+# 查看日志
 hermeslink logs
 ```
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `hermeslink start` | Start the background daemon |
-| `hermeslink stop` | Stop the daemon |
-| `hermeslink restart` | Restart the daemon |
-| `hermeslink status` | Show daemon and service status |
-| `hermeslink pair` | Generate a pairing URL for your device |
-| `hermeslink config get` | Show current configuration |
-| `hermeslink config set <key> <value>` | Set a configuration value |
-| `hermeslink autostart` | Show autostart status |
-| `hermeslink autostart enable` | Enable autostart on login |
-| `hermeslink autostart disable` | Disable autostart |
-| `hermeslink logs` | Show recent log entries |
-| `hermeslink logs --gateway` | Show Hermes gateway logs |
-| `hermeslink version` | Print version |
-
-## Configuration
+## 配对流程
+
+```
+1. 运行 hermeslink pair
+        │
+        ▼
+   终端显示二维码
+        │
+        ▼
+   手机 App 扫码
+        │
+        ▼
+   直连本地服务 (局域网 / 127.0.0.1)
+```
+
+配对完成后，手机 App 获得访问令牌，后续请求直接连接本地服务，无需经过外部服务器。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `hermeslink start` | 启动后台守护进程 |
+| `hermeslink stop` | 停止守护进程 |
+| `hermeslink restart` | 重启守护进程 |
+| `hermeslink status` | 查看运行状态 |
+| `hermeslink pair` | 生成配对二维码 |
+| `hermeslink config get` | 查看当前配置 |
+| `hermeslink config set <key> <value>` | 修改配置 |
+| `hermeslink autostart enable` | 开机自启 |
+| `hermeslink autostart disable` | 关闭自启 |
+| `hermeslink logs` | 查看日志 |
+| `hermeslink logs --gateway` | 查看 Hermes 网关日志 |
+| `hermeslink version` | 查看版本 |
+
+## 配置
 
 ```bash
-hermeslink config set port 52379          # Change listen port
-hermeslink config set lan-host 192.168.1.10  # Set LAN IP manually
-hermeslink config set language zh-CN      # Set language (auto/en/zh-CN)
-hermeslink config set log-level debug     # Set log level (debug/info/warn/error)
+hermeslink config set port 52379              # 修改监听端口
+hermeslink config set lan-host 192.168.1.10   # 手动指定局域网 IP
+hermeslink config set language zh-CN          # 语言 (auto/en/zh-CN)
+hermeslink config set log-level debug         # 日志级别 (debug/info/warn/error)
 ```
 
-Config is stored at `~/.hermeslink/config.json`.
+配置文件位于 `~/.hermeslink/config.json`。
 
-## How It Works
+## 工作原理
 
 ```
-Hermes App (mobile)
-       │
-       ▼
-hermes-relay.catwiki.ai  ──────────────────┐
-                                           │ WebSocket tunnel
-                                    hermeslink (this service)
-                                           │
-                                           ▼
-                                   Hermes Agent (local)
-                                   localhost:8642
+手机 App
+   │
+   └──→ hermeslink (本地, 端口 52379)
+              │
+              └──→ Hermes Agent (localhost:8642)
 ```
 
-`hermeslink` runs a local HTTP server (default port `52379`) and maintains a persistent WebSocket connection to the relay server. The mobile app connects through the relay and proxies requests to your local Hermes Agent.
+`hermeslink` 在本地运行一个 HTTP 服务，手机 App 通过局域网直接访问。对话、文件、指令均在本地处理，数据不经过外部服务器。
 
-## Runtime Files
+## 运行时文件
 
-All runtime files are stored in `~/.hermeslink/`:
+所有文件存储于 `~/.hermeslink/`：
 
-| Path | Description |
-|------|-------------|
-| `config.json` | User configuration |
-| `identity.json` | Device identity (ed25519 keypair) |
-| `link.db` | SQLite database (stats, usage) |
-| `logs/` | Log files |
-| `daemon.pid` | Daemon PID file |
+| 路径 | 说明 |
+|------|------|
+| `config.json` | 用户配置 |
+| `identity.json` | 设备身份（ed25519 密钥对）|
+| `credentials.json` | 已配对设备的访问令牌 |
+| `conversations/` | 对话数据 |
+| `blobs/` | 文件附件 |
+| `pairing/` | 配对会话 |
+| `link.db` | SQLite 数据库（统计信息）|
+| `logs/` | 日志文件 |
 
-## Environment Variables
+## 环境变量
 
-| Variable | Description |
-|----------|-------------|
-| `HERMESLINK_HOME` | Override runtime directory (default `~/.hermeslink`) |
-| `HERMESLINK_LOG_LEVEL` | Override log level |
-| `HERMESLINK_LANG` | Override language |
-| `HERMES_BIN` | Path to `hermes` binary (default: `hermes`) |
+| 变量 | 说明 |
+|------|------|
+| `HERMESLINK_HOME` | 覆盖运行时目录（默认 `~/.hermeslink`）|
+| `HERMESLINK_LOG_LEVEL` | 覆盖日志级别 |
+| `HERMESLINK_LANG` | 覆盖语言 |
+| `HERMES_BIN` | `hermes` 二进制路径（默认 `hermes`）|
 
-## Autostart
+## 开机自启
 
-On macOS, autostart is managed via launchd (`~/Library/LaunchAgents/com.hermes.link.plist`).  
-On Linux, via systemd user service or XDG autostart.  
-On Windows, via the Startup folder.
+- **macOS**：通过 launchd（`~/Library/LaunchAgents/com.hermes.link.plist`）
+- **Linux**：通过 systemd 用户服务或 XDG autostart
+- **Windows**：通过 Startup 文件夹
 
 ```bash
 hermeslink autostart enable

package/dist/{chunk-CCKWZNLX.js → chunk-QL5SEM7J.js}

@@ -12,8 +12,11 @@ import path2 from "path";
 import pino from "pino";
 
 // src/constants.ts
+import { createRequire } from "module";
+var _require = createRequire(import.meta.url);
+var _pkg = _require("../package.json");
 var LINK_COMMAND = "hermeslink";
-var LINK_VERSION = "0.1.0";
+var LINK_VERSION = _pkg.version;
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
 var DEFAULT_LOG_FILE = "hermeslink.log";
@@ -797,9 +800,6 @@ async function dismissUpdate(paths) {
   await updateLinkState({ updateDismissedAt: (/* @__PURE__ */ new Date()).toISOString() }, runtimePaths);
 }
 
-// src/http/auth.ts
-import { createPublicKey, verify } from "crypto";
-
 // src/security/credentials.ts
 import { randomBytes, randomUUID as randomUUID2, timingSafeEqual, createHash } from "crypto";
 var ACCESS_TOKEN_TTL_MS = 15 * 60 * 1e3;
@@ -1072,133 +1072,50 @@ async function renameDeviceById(deviceId, label, paths = resolveRuntimePaths())
   return formatDeviceListItem(device);
 }
 
-// src/identity/identity.ts
-import { generateKeyPairSync, randomUUID as randomUUID3, sign } from "crypto";
-import { chmod as chmod2, mkdir as mkdir4 } from "fs/promises";
-import { z } from "zod";
-var linkIdentitySchema = z.object({
-  install_id: z.string().min(1),
-  link_id: z.string().min(1).nullable().optional(),
-  public_key_pem: z.string().min(1),
-  private_key_pem: z.string().min(1),
-  created_at: z.string().min(1),
-  updated_at: z.string().min(1)
-});
-async function loadIdentity(paths = resolveRuntimePaths()) {
-  const value = await readJsonFile(paths.identityFile);
-  if (value === null) {
-    return null;
-  }
-  return linkIdentitySchema.parse(value);
-}
-async function ensureIdentity(paths = resolveRuntimePaths()) {
-  const existing = await loadIdentity(paths);
-  if (existing) {
-    return existing;
-  }
-  await mkdir4(paths.homeDir, { recursive: true, mode: 448 });
-  await chmod2(paths.homeDir, 448).catch(() => void 0);
-  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const identity = {
-    install_id: `install_${randomUUID3().replaceAll("-", "")}`,
-    link_id: null,
-    public_key_pem: publicKey.export({ type: "spki", format: "pem" }).toString(),
-    private_key_pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
-    created_at: now,
-    updated_at: now
-  };
-  await writeJsonFile(paths.identityFile, identity);
-  return identity;
+// src/security/app-connect-token.ts
+import crypto from "crypto";
+import path6 from "path";
+var TOKENS_FILE = "app-connect-tokens.json";
+var TOKEN_EXPIRY_MS = 5 * 60 * 1e3;
+function tokensFilePath(paths) {
+  return path6.join(paths.homeDir, TOKENS_FILE);
+}
+async function readTokens(paths) {
+  const raw = await readJsonFile(tokensFilePath(paths));
+  if (!Array.isArray(raw)) return [];
+  const now = /* @__PURE__ */ new Date();
+  return raw.filter(isValidToken).filter((t) => new Date(t.expiresAt) > now);
 }
-async function saveAssignedLinkId(linkId, paths = resolveRuntimePaths()) {
-  const identity = await ensureIdentity(paths);
-  const next = {
-    ...identity,
-    link_id: linkId,
-    updated_at: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await writeJsonFile(paths.identityFile, next);
-  return next;
+function isValidToken(value) {
+  if (!value || typeof value !== "object") return false;
+  const t = value;
+  return typeof t.token === "string" && typeof t.createdAt === "string" && typeof t.expiresAt === "string";
 }
-function signRelayNonce(identity, nonce) {
-  return signIdentityPayload(identity, nonce);
+async function saveTokens(tokens, paths) {
+  await writeJsonFile(tokensFilePath(paths), tokens);
 }
-function signIdentityPayload(identity, payload) {
-  const signature = sign(null, Buffer.from(payload, "utf8"), identity.private_key_pem);
-  return signature.toString("base64url");
-}
-
-// src/config/config.ts
-var defaultLinkConfig = {
-  port: LINK_DEFAULT_PORT,
-  lanHost: null,
-  serverBaseUrl: "https://hermes-server.catwiki.ai",
-  relayBaseUrl: "https://hermes-relay.catwiki.ai",
-  appConnectTokenIssuer: "https://hermes-server.catwiki.ai",
-  appConnectTokenAudience: "hermes-link",
-  language: "auto",
-  logLevel: "warn"
-};
-async function loadConfig(paths = resolveRuntimePaths()) {
-  const existing = await readJsonFile(paths.configFile);
-  const language = normalizeConfiguredLanguage(existing?.language);
-  const lanHost = normalizeLanHost(existing?.lanHost);
-  const logLevel = normalizeLogLevel(existing?.logLevel ?? process.env.HERMESLINK_LOG_LEVEL);
-  return {
-    ...defaultLinkConfig,
-    ...existing ?? {},
-    language,
-    lanHost,
-    logLevel
-  };
-}
-async function saveConfig(patch, paths = resolveRuntimePaths()) {
-  const current = await loadConfig(paths);
-  const next = {
-    ...current,
-    ...patch,
-    logLevel: patch.logLevel === void 0 ? current.logLevel : normalizeLogLevel(patch.logLevel)
+async function generateAppConnectToken(paths) {
+  const runtimePaths = paths ?? resolveRuntimePaths();
+  const now = /* @__PURE__ */ new Date();
+  const token = {
+    token: crypto.randomBytes(32).toString("base64url"),
+    createdAt: now.toISOString(),
+    usedAt: null,
+    expiresAt: new Date(now.getTime() + TOKEN_EXPIRY_MS).toISOString()
   };
-  await writeJsonFile(paths.configFile, next);
-  return next;
-}
-function normalizeConfiguredLanguage(language) {
-  if (language === "zh-CN" || language === "en" || language === "auto") {
-    return language;
-  }
-  return defaultLinkConfig.language;
-}
-function normalizeLogLevel(level) {
-  if (level === "debug" || level === "info" || level === "warn" || level === "error") {
-    return level;
-  }
-  return defaultLinkConfig.logLevel;
-}
-function normalizeLanHost(value) {
-  if (value === null || value === void 0) {
-    return null;
-  }
-  if (typeof value !== "string") {
-    return null;
-  }
-  const host = value.trim().replace(/^\[/u, "").replace(/\]$/u, "");
-  if (!host) {
-    return null;
-  }
-  if (!isUsableLanIpv4(host)) {
-    return null;
-  }
-  return host;
+  const tokens = await readTokens(runtimePaths);
+  tokens.push(token);
+  await saveTokens(tokens, runtimePaths);
+  return token;
 }
-function isUsableLanIpv4(value) {
-  const parts = value.split(".").map((part) => Number.parseInt(part, 10));
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
-    return false;
-  }
-  const [first, second, , fourth] = parts;
-  const privateRange = first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168;
-  return privateRange && fourth !== 0 && fourth !== 255;
+async function consumeAppConnectToken(tokenValue, paths) {
+  const runtimePaths = paths ?? resolveRuntimePaths();
+  const tokens = await readTokens(runtimePaths);
+  const index = tokens.findIndex((t) => t.token === tokenValue && !t.usedAt);
+  if (index === -1) return null;
+  tokens[index].usedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await saveTokens(tokens, runtimePaths);
+  return tokens[index];
 }
 
 // src/core/errors.ts
@@ -1213,7 +1130,6 @@ var LinkHttpError = class extends Error {
 };
 
 // src/http/auth.ts
-var cachedJwks = null;
 async function authenticateRequest(ctx, paths = resolveRuntimePaths()) {
   const token = readBearerToken(ctx.get("authorization"));
   if (!token) {
@@ -1226,21 +1142,11 @@ async function authenticateRequest(ctx, paths = resolveRuntimePaths()) {
   if (token.startsWith("hpat_")) {
     throw new LinkHttpError(401, "device_access_token_invalid", "Device access token is invalid or expired");
   }
-  const [identity, config] = await Promise.all([loadRequiredIdentity(paths), loadConfig(paths)]);
-  const claims = await verifyAppConnectToken(token, { config, linkId: identity.link_id ?? null });
-  return {
-    kind: "app-connect",
-    accountId: typeof claims.sub === "string" ? claims.sub : null,
-    scopes: normalizeScopes(claims.scope),
-    appInstanceId: normalizeAppInstanceId2(claims.app_instance_id)
-  };
-}
-async function loadRequiredIdentity(paths) {
-  const identity = await loadIdentity(paths);
-  if (!identity?.link_id) {
-    throw new LinkHttpError(409, "link_not_paired", "Hermes Link is not paired");
+  const localToken = await consumeAppConnectToken(token, paths);
+  if (localToken) {
+    return { kind: "app-connect", accountId: null, scopes: [], appInstanceId: null };
   }
-  return identity;
+  throw new LinkHttpError(401, "auth_invalid", "Token is invalid or expired");
 }
 function readBearerToken(value) {
   const trimmed = value.trim();
@@ -1248,67 +1154,6 @@ function readBearerToken(value) {
   const token = trimmed.slice(7).trim();
   return token || null;
 }
-function normalizeScopes(value) {
-  if (Array.isArray(value)) return value.filter((i) => typeof i === "string").map((i) => i.trim()).filter(Boolean);
-  if (typeof value === "string") return value.split(/\s+/u).map((i) => i.trim()).filter(Boolean);
-  return [];
-}
-function normalizeAppInstanceId2(value) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  return /^appi_[A-Za-z0-9_-]{16,96}$/u.test(trimmed) ? trimmed : null;
-}
-async function verifyAppConnectToken(token, options) {
-  const segments = token.split(".");
-  if (segments.length !== 3) {
-    throw new LinkHttpError(401, "app_connect_token_invalid", "App connect token is malformed");
-  }
-  const [encodedHeader, encodedPayload, encodedSignature] = segments;
-  const header = decodeJwtPart(encodedHeader);
-  const payload = decodeJwtPart(encodedPayload);
-  if (header.alg !== "ES256" || header.typ !== "JWT") {
-    throw new LinkHttpError(401, "app_connect_token_invalid", "App connect token algorithm is unsupported");
-  }
-  if (payload.token_type !== "hermes_app_connect" || payload.iss !== options.config.appConnectTokenIssuer || payload.aud !== options.config.appConnectTokenAudience || payload.link_id !== options.linkId || !Number.isFinite(payload.exp) || payload.exp <= Math.floor(Date.now() / 1e3)) {
-    throw new LinkHttpError(401, "app_connect_token_invalid", "App connect token claims are invalid");
-  }
-  const jwks = await getJwks(options.config.serverBaseUrl);
-  const key = jwks.find((k) => k.kid === header.kid) ?? jwks[0];
-  if (!key) {
-    throw new LinkHttpError(503, "app_connect_jwks_unavailable", "App connect token key is unavailable");
-  }
-  const publicKey = createPublicKey({ key, format: "jwk" });
-  const ok = verify(
-    "sha256",
-    Buffer.from(`${encodedHeader}.${encodedPayload}`),
-    { key: publicKey, dsaEncoding: "ieee-p1363" },
-    Buffer.from(base64UrlToBase64(encodedSignature), "base64")
-  );
-  if (!ok) {
-    throw new LinkHttpError(401, "app_connect_token_invalid", "App connect token signature is invalid");
-  }
-  return payload;
-}
-async function getJwks(serverBaseUrl) {
-  if (cachedJwks && cachedJwks.expiresAt > Date.now()) return cachedJwks.keys;
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}/api/v1/app-connect/jwks.json`, {
-    headers: { accept: "application/json" }
-  });
-  if (!response.ok) {
-    throw new LinkHttpError(503, "app_connect_jwks_unavailable", "Unable to load app connect JWKS");
-  }
-  const payload = await response.json();
-  const keys = Array.isArray(payload.keys) ? payload.keys : [];
-  cachedJwks = { keys, expiresAt: Date.now() + 5 * 60 * 1e3 };
-  return keys;
-}
-function decodeJwtPart(value) {
-  return JSON.parse(Buffer.from(base64UrlToBase64(value), "base64").toString("utf8"));
-}
-function base64UrlToBase64(value) {
-  const n = value.replace(/-/g, "+").replace(/_/g, "/");
-  return n + "=".repeat((4 - n.length % 4) % 4);
-}
 function readAppInstanceIdHeader(ctx) {
   const value = ctx.get("x-hermes-app-instance-id").trim();
   return /^appi_[A-Za-z0-9_-]{16,96}$/u.test(value) ? value : null;
@@ -1513,6 +1358,135 @@ function createStatisticsRouter(options) {
 // src/http/routes/bootstrap.ts
 import Router3 from "@koa/router";
 
+// src/identity/identity.ts
+import { generateKeyPairSync, randomUUID as randomUUID3, sign } from "crypto";
+import { chmod as chmod2, mkdir as mkdir4 } from "fs/promises";
+import { z } from "zod";
+var linkIdentitySchema = z.object({
+  install_id: z.string().min(1),
+  link_id: z.string().min(1).nullable().optional(),
+  public_key_pem: z.string().min(1),
+  private_key_pem: z.string().min(1),
+  created_at: z.string().min(1),
+  updated_at: z.string().min(1)
+});
+async function loadIdentity(paths = resolveRuntimePaths()) {
+  const value = await readJsonFile(paths.identityFile);
+  if (value === null) {
+    return null;
+  }
+  return linkIdentitySchema.parse(value);
+}
+async function ensureIdentity(paths = resolveRuntimePaths()) {
+  const existing = await loadIdentity(paths);
+  if (existing) {
+    return existing;
+  }
+  await mkdir4(paths.homeDir, { recursive: true, mode: 448 });
+  await chmod2(paths.homeDir, 448).catch(() => void 0);
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const identity = {
+    install_id: `install_${randomUUID3().replaceAll("-", "")}`,
+    link_id: null,
+    public_key_pem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    private_key_pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    created_at: now,
+    updated_at: now
+  };
+  await writeJsonFile(paths.identityFile, identity);
+  return identity;
+}
+async function saveAssignedLinkId(linkId, paths = resolveRuntimePaths()) {
+  const identity = await ensureIdentity(paths);
+  const next = {
+    ...identity,
+    link_id: linkId,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeJsonFile(paths.identityFile, next);
+  return next;
+}
+function signRelayNonce(identity, nonce) {
+  return signIdentityPayload(identity, nonce);
+}
+function signIdentityPayload(identity, payload) {
+  const signature = sign(null, Buffer.from(payload, "utf8"), identity.private_key_pem);
+  return signature.toString("base64url");
+}
+
+// src/config/config.ts
+var defaultLinkConfig = {
+  port: LINK_DEFAULT_PORT,
+  lanHost: null,
+  serverBaseUrl: "https://hermes-server.catwiki.ai",
+  relayBaseUrl: "https://hermes-relay.catwiki.ai",
+  appConnectTokenIssuer: "https://hermes-server.catwiki.ai",
+  appConnectTokenAudience: "hermes-link",
+  language: "auto",
+  logLevel: "warn"
+};
+async function loadConfig(paths = resolveRuntimePaths()) {
+  const existing = await readJsonFile(paths.configFile);
+  const language = normalizeConfiguredLanguage(existing?.language);
+  const lanHost = normalizeLanHost(existing?.lanHost);
+  const logLevel = normalizeLogLevel(existing?.logLevel ?? process.env.HERMESLINK_LOG_LEVEL);
+  return {
+    ...defaultLinkConfig,
+    ...existing ?? {},
+    language,
+    lanHost,
+    logLevel
+  };
+}
+async function saveConfig(patch, paths = resolveRuntimePaths()) {
+  const current = await loadConfig(paths);
+  const next = {
+    ...current,
+    ...patch,
+    logLevel: patch.logLevel === void 0 ? current.logLevel : normalizeLogLevel(patch.logLevel)
+  };
+  await writeJsonFile(paths.configFile, next);
+  return next;
+}
+function normalizeConfiguredLanguage(language) {
+  if (language === "zh-CN" || language === "en" || language === "auto") {
+    return language;
+  }
+  return defaultLinkConfig.language;
+}
+function normalizeLogLevel(level) {
+  if (level === "debug" || level === "info" || level === "warn" || level === "error") {
+    return level;
+  }
+  return defaultLinkConfig.logLevel;
+}
+function normalizeLanHost(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value !== "string") {
+    return null;
+  }
+  const host = value.trim().replace(/^\[/u, "").replace(/\]$/u, "");
+  if (!host) {
+    return null;
+  }
+  if (!isUsableLanIpv4(host)) {
+    return null;
+  }
+  return host;
+}
+function isUsableLanIpv4(value) {
+  const parts = value.split(".").map((part) => Number.parseInt(part, 10));
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  const [first, second, , fourth] = parts;
+  const privateRange = first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168;
+  return privateRange && fourth !== 0 && fourth !== 255;
+}
+
 // src/network/topology.ts
 import os5 from "os";
 var VIRTUAL_INTERFACE_NAME_PATTERN = /(docker|veth|vmnet|vmenet|vbox|virtualbox|vmware|tailscale|zerotier|wireguard|utun|virbr|hyper-v|vethernet|loopback|\blo\b|^lo\d*$|^br-|^bridge\d+$|^zt|^tun|^tap|awdl|llw|anpi|gif|stf|ipsec|ppp)/iu;
@@ -2237,7 +2211,7 @@ function createConversationsRouter(options) {
 
 // src/http/routes/pairing.ts
 import Router7 from "@koa/router";
-import path6 from "path";
+import path7 from "path";
 function readString4(body, ...keys) {
   if (!body || typeof body !== "object") return null;
   for (const key of keys) {
@@ -2264,10 +2238,10 @@ async function readJsonBody4(req) {
   });
 }
 function pairingSessionPath(sessionId, paths) {
-  return path6.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
+  return path7.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
 }
 function pairingClaimPath(sessionId, paths) {
-  return path6.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
+  return path7.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
 }
 async function readPairingSession(sessionId, paths) {
   const record = await readJsonFile(pairingSessionPath(sessionId, paths));
@@ -2312,35 +2286,18 @@ function createPairingRouter(options) {
     if (!sessionId || !claimToken) {
       throw new LinkHttpError(400, "pairing_claim_invalid", "session_id and claim_token are required");
     }
-    const [identity, config, localSession] = await Promise.all([
+    const [identity, localSession] = await Promise.all([
       loadIdentity(paths),
-      loadConfig(paths),
       readPairingSession(sessionId, paths)
     ]);
     if (!identity?.link_id) throw new LinkHttpError(409, "link_not_paired", "Hermes Link is not paired");
     if (!localSession) throw new LinkHttpError(404, "pairing_session_not_found", "Pairing session was not found");
     if (isPairingSessionExpired(localSession)) throw new LinkHttpError(404, "pairing_session_expired", "Pairing session has expired");
     if (localSession.link_id !== identity.link_id) throw new LinkHttpError(409, "pairing_claim_mismatch", "Pairing claim does not match this Link");
-    let verified;
-    try {
-      const resp = await fetch(`${config.serverBaseUrl.replace(/\/+$/u, "")}/api/v1/link-pairings/${sessionId}/claim/verify`, {
-        method: "POST",
-        headers: { accept: "application/json", "content-type": "application/json" },
-        body: JSON.stringify({ claim_token: claimToken, app_instance_id: readString4(body, "app_instance_id", "appInstanceId") ?? void 0 })
-      });
-      if (!resp.ok) {
-        const errBody = await resp.json().catch(() => ({}));
-        throw new LinkHttpError(resp.status, "pairing_claim_verify_failed", String(errBody.message ?? "Pairing claim verification failed"));
-      }
-      verified = await resp.json();
-    } catch (err) {
-      if (err instanceof LinkHttpError) throw err;
-      throw new LinkHttpError(503, "pairing_server_unreachable", `Unable to verify pairing claim: ${err.message}`);
+    if (localSession.code !== claimToken) {
+      throw new LinkHttpError(409, "pairing_claim_mismatch", "Pairing claim token does not match");
     }
-    if (verified.ok !== true || verified.linkId !== identity.link_id) {
-      throw new LinkHttpError(409, "pairing_claim_mismatch", "Pairing claim does not match this Link");
-    }
-    const appInstanceId = typeof verified.appInstanceId === "string" ? verified.appInstanceId : null;
+    const appInstanceId = readString4(body, "app_instance_id", "appInstanceId");
     const deviceLabel = readString4(body, "device_label", "deviceLabel") ?? "HermesPilot App";
     const devicePlatform = readString4(body, "device_platform", "devicePlatform") ?? "unknown";
     const session = await createDeviceSession(
@@ -2598,9 +2555,9 @@ function openSqliteDatabase(filePath, options = {}) {
 
 // src/storage/link-database.ts
 import { mkdir as mkdir5 } from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 async function initLinkDatabase(paths) {
-  await mkdir5(path7.dirname(paths.databaseFile), { recursive: true, mode: 448 });
+  await mkdir5(path8.dirname(paths.databaseFile), { recursive: true, mode: 448 });
   const db = openDb(paths);
   try {
     db.exec(`
@@ -2696,35 +2653,35 @@ function openDb(paths) {
 
 // src/conversations/service.ts
 import { EventEmitter as EventEmitter2 } from "events";
-import crypto3 from "crypto";
+import crypto4 from "crypto";
 
 // src/conversations/store.ts
 import { mkdir as mkdir6, readFile as readFile4, rm as rm4, writeFile as writeFile2 } from "fs/promises";
-import path8 from "path";
-import crypto from "crypto";
+import path9 from "path";
+import crypto2 from "crypto";
 function createConversationId() {
-  return `conv_${crypto.randomUUID().replaceAll("-", "")}`;
+  return `conv_${crypto2.randomUUID().replaceAll("-", "")}`;
 }
 function createMessageId() {
-  return `msg_${crypto.randomUUID().replaceAll("-", "")}`;
+  return `msg_${crypto2.randomUUID().replaceAll("-", "")}`;
 }
 function createRunId() {
-  return `run_${crypto.randomUUID().replaceAll("-", "")}`;
+  return `run_${crypto2.randomUUID().replaceAll("-", "")}`;
 }
 function conversationDir(paths, conversationId) {
-  return path8.join(paths.conversationsDir, conversationId);
+  return path9.join(paths.conversationsDir, conversationId);
 }
 function manifestPath(paths, conversationId) {
-  return path8.join(conversationDir(paths, conversationId), "manifest.json");
+  return path9.join(conversationDir(paths, conversationId), "manifest.json");
 }
 function snapshotPath(paths, conversationId) {
-  return path8.join(conversationDir(paths, conversationId), "snapshot.json");
+  return path9.join(conversationDir(paths, conversationId), "snapshot.json");
 }
 function eventsPath(paths, conversationId) {
-  return path8.join(conversationDir(paths, conversationId), "events.json");
+  return path9.join(conversationDir(paths, conversationId), "events.json");
 }
 function blobPath(paths, blobId) {
-  return path8.join(paths.blobsDir, blobId);
+  return path9.join(paths.blobsDir, blobId);
 }
 async function readJson(filePath, fallback) {
   try {
@@ -2735,7 +2692,7 @@ async function readJson(filePath, fallback) {
   }
 }
 async function writeJson(filePath, data) {
-  await mkdir6(path8.dirname(filePath), { recursive: true, mode: 448 });
+  await mkdir6(path9.dirname(filePath), { recursive: true, mode: 448 });
   await writeFile2(filePath, JSON.stringify(data), { mode: 384 });
 }
 function assertValidConversationId(id) {
@@ -2792,8 +2749,8 @@ async function listConversationIds(paths) {
 
 // src/conversations/blobs.ts
 import { mkdir as mkdir7, readFile as readFile5, rm as rm5, writeFile as writeFile3 } from "fs/promises";
-import path9 from "path";
-import crypto2 from "crypto";
+import path10 from "path";
+import crypto3 from "crypto";
 var MAX_BLOB_UPLOAD_BYTES2 = 50 * 1024 * 1024;
 function blobManifestPath(paths, blobId) {
   return `${blobPath(paths, blobId)}.json`;
@@ -2801,7 +2758,7 @@ function blobManifestPath(paths, blobId) {
 function normalizeMime(mime, filename) {
   if (mime && mime !== "application/octet-stream") return mime;
   if (filename) {
-    const ext = path9.extname(filename).toLowerCase();
+    const ext = path10.extname(filename).toLowerCase();
     const mimeMap = {
       ".jpg": "image/jpeg",
       ".jpeg": "image/jpeg",
@@ -2821,7 +2778,7 @@ function normalizeMime(mime, filename) {
 }
 function sanitizeFilename(filename, fallback) {
   if (!filename) return fallback;
-  return path9.basename(filename).replace(/[^\w.\-]/gu, "_").slice(0, 255) || fallback;
+  return path10.basename(filename).replace(/[^\w.\-]/gu, "_").slice(0, 255) || fallback;
 }
 async function writeBlob(paths, conversationId, input) {
   assertValidConversationId(conversationId);
@@ -2831,9 +2788,9 @@ async function writeBlob(paths, conversationId, input) {
   if (input.bytes.byteLength > MAX_BLOB_UPLOAD_BYTES2) {
     throw new LinkHttpError(413, "blob_too_large", "Blob is too large");
   }
-  const id = `blob_${crypto2.randomUUID().replaceAll("-", "")}`;
+  const id = `blob_${crypto3.randomUUID().replaceAll("-", "")}`;
   const filePath = blobPath(paths, id);
-  await mkdir7(path9.dirname(filePath), { recursive: true, mode: 448 });
+  await mkdir7(path10.dirname(filePath), { recursive: true, mode: 448 });
   await writeFile3(filePath, input.bytes, { mode: 384 });
   const blob = {
     id,
@@ -3206,7 +3163,7 @@ var ConversationService = class extends EventEmitter2 {
     return { deleted_count: count };
   }
   async prepareClearAllConversationPlan() {
-    const planId = `plan_${crypto3.randomUUID().replaceAll("-", "")}`;
+    const planId = `plan_${crypto4.randomUUID().replaceAll("-", "")}`;
     const ids = await listConversationIds(this.paths);
     const activeIds = [];
     for (const id of ids) {
@@ -3284,7 +3241,7 @@ import { promisify as promisify3 } from "util";
 
 // src/hermes/config.ts
 import os6 from "os";
-import path10 from "path";
+import path11 from "path";
 import YAML from "yaml";
 var PROFILE_PERMISSION_TOOLSETS = [
   {
@@ -3414,19 +3371,19 @@ var profileApiServerPortAssignmentQueue = Promise.resolve();
 function resolveHermesProfilesDir() {
   const hermesHome = process.env.HERMES_HOME?.trim();
   if (hermesHome) {
-    return path10.join(
-      resolveDefaultHermesRoot(path10.resolve(hermesHome)),
+    return path11.join(
+      resolveDefaultHermesRoot(path11.resolve(hermesHome)),
       "profiles"
     );
   }
-  return path10.join(os6.homedir(), ".hermes", "profiles");
+  return path11.join(os6.homedir(), ".hermes", "profiles");
 }
 function isValidProfileName(value) {
   return typeof value === "string" && /^[a-zA-Z0-9._-]{1,64}$/.test(value);
 }
 function resolveDefaultHermesRoot(hermesHome) {
-  if (path10.basename(path10.dirname(hermesHome)) === "profiles") {
-    return path10.dirname(path10.dirname(hermesHome));
+  if (path11.basename(path11.dirname(hermesHome)) === "profiles") {
+    return path11.dirname(path11.dirname(hermesHome));
   }
   return hermesHome;
 }
@@ -3638,7 +3595,6 @@ export {
   LINK_VERSION,
   DAEMON_LOG_FILE,
   resolveRuntimePaths,
-  readJsonFile,
   writeJsonFile,
   loadConfig,
   saveConfig,
@@ -3655,5 +3611,6 @@ export {
   readRecentLogEntries,
   readRecentGatewayLogEntries,
   bootstrapWithRelay,
+  generateAppConnectToken,
   startLinkService
 };

package/dist/cli/index.js

@@ -10,11 +10,11 @@ import {
   disableAutostart,
   enableAutostart,
   ensureIdentity,
+  generateAppConnectToken,
   getAutostartStatus,
   loadConfig,
   loadIdentity,
   normalizeLanHost,
-  readJsonFile,
   readRecentGatewayLogEntries,
   readRecentLogEntries,
   resolveRuntimePaths,
@@ -22,10 +22,10 @@ import {
   saveConfig,
   startLinkService,
   writeJsonFile
-} from "../chunk-CCKWZNLX.js";
+} from "../chunk-QL5SEM7J.js";
 
 // src/cli/index.ts
-import { mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir3 } from "fs/promises";
 import qrcode from "qrcode-terminal";
 
 // src/daemon/process.ts
@@ -190,42 +190,9 @@ async function runDaemonSupervisor(options) {
   await cleanup();
 }
 
-// src/security/app-connect-token.ts
-import crypto from "crypto";
+// src/pairing/preflight.ts
 import path2 from "path";
-var TOKENS_FILE = "app-connect-tokens.json";
-var TOKEN_EXPIRY_MS = 5 * 60 * 1e3;
-function tokensFilePath(paths) {
-  return path2.join(paths.homeDir, TOKENS_FILE);
-}
-async function readTokens(paths) {
-  const raw = await readJsonFile(tokensFilePath(paths));
-  if (!Array.isArray(raw)) return [];
-  const now = /* @__PURE__ */ new Date();
-  return raw.filter(isValidToken).filter((t) => new Date(t.expiresAt) > now);
-}
-function isValidToken(value) {
-  if (!value || typeof value !== "object") return false;
-  const t = value;
-  return typeof t.token === "string" && typeof t.createdAt === "string" && typeof t.expiresAt === "string";
-}
-async function saveTokens(tokens, paths) {
-  await writeJsonFile(tokensFilePath(paths), tokens);
-}
-async function generateAppConnectToken(paths) {
-  const runtimePaths = paths ?? resolveRuntimePaths();
-  const now = /* @__PURE__ */ new Date();
-  const token = {
-    token: crypto.randomBytes(32).toString("base64url"),
-    createdAt: now.toISOString(),
-    usedAt: null,
-    expiresAt: new Date(now.getTime() + TOKEN_EXPIRY_MS).toISOString()
-  };
-  const tokens = await readTokens(runtimePaths);
-  tokens.push(token);
-  await saveTokens(tokens, runtimePaths);
-  return token;
-}
+import { mkdir as mkdir2 } from "fs/promises";
 
 // src/runtime/browser.ts
 import { spawn as spawn2 } from "child_process";
@@ -261,28 +228,48 @@ async function spawnDetached(command2, args2) {
 }
 
 // src/pairing/preflight.ts
+function pairingSessionPath(sessionId, paths) {
+  return path2.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
+}
 async function runPairingPreflight(options) {
   const token = await generateAppConnectToken(options.paths);
-  const baseUrl = (options.serverBaseUrl ?? options.config.serverBaseUrl).replace(/\/+$/u, "");
-  const pairingUrl = buildPairingUrl(baseUrl, {
+  const localApiUrl = `http://127.0.0.1:${options.config.port}`;
+  const sessionId = `ps_${token.token.slice(0, 16)}`;
+  const session = {
+    session_id: sessionId,
+    code: token.token,
+    link_id: options.identity.link_id ?? "",
+    display_name: "Hermes Link",
+    local_api_url: localApiUrl,
+    server_base_url: options.config.serverBaseUrl,
+    relay_base_url: options.config.relayBaseUrl,
+    preferred_urls: [localApiUrl],
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    expires_at: token.expiresAt
+  };
+  await mkdir2(options.paths.pairingDir, { recursive: true, mode: 448 }).catch(() => void 0);
+  await writeJsonFile(pairingSessionPath(sessionId, options.paths), session);
+  const pairingUrl = buildPairingUrl({
     linkId: options.identity.link_id ?? "",
     installId: options.identity.install_id,
     connectToken: token.token,
-    port: options.config.port
+    port: options.config.port,
+    localApiUrl
   });
   if (options.openBrowser !== false) {
     await openSystemBrowser(pairingUrl).catch(() => void 0);
   }
   return { pairingUrl, connectToken: token.token };
 }
-function buildPairingUrl(serverBaseUrl, params) {
+function buildPairingUrl(params) {
   const qs = new URLSearchParams({
     link_id: params.linkId,
     install_id: params.installId,
     connect_token: params.connectToken,
-    port: String(params.port)
+    port: String(params.port),
+    local_url: params.localApiUrl
   });
-  return `${serverBaseUrl}/link/pair?${qs.toString()}`;
+  return `hermesapp://pair?${qs.toString()}`;
 }
 
 // src/cli/index.ts
@@ -308,7 +295,7 @@ async function main() {
     return;
   }
   const paths = resolveRuntimePaths();
-  await mkdir2(paths.homeDir, { recursive: true, mode: 448 });
+  await mkdir3(paths.homeDir, { recursive: true, mode: 448 });
   switch (command) {
     case "start":
       await cmdStart(paths);

package/dist/http/app.js

@@ -1,6 +1,6 @@
 import {
   startLinkService
-} from "../chunk-CCKWZNLX.js";
+} from "../chunk-QL5SEM7J.js";
 export {
   startLinkService
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bulolo/hermes-link",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Hermes Link companion service and CLI for connecting hermes-agent through zhiji",
   "license": "MIT",
   "type": "module",