@the-ai-company/cbio-node-runtime 1.42.0 → 1.45.2

package/docs/zh/PROCESS_ISOLATION.md

@@ -0,0 +1,58 @@
+# 进程隔离 (A/B 架构)
+
+`@the-ai-company/cbio-node-runtime` 原生支持**进程隔离**架构（通常被称为 "A/B" 或 "中枢控制" 模型）。
+
+在此模型下，敏感操作被拆分到两个独立的操作系统进程中：
+
+1.  **进程 B (Vault Server)**：持有 Vault 根密钥并管理加密存储。它作为一个“具备身份验证感知能力的代理服务器”运行。
+2.  **进程 A (Agent/LLM)**：执行业务逻辑或大模型推理。它们可以**发起签名请求**，但**全程接触不到 Vault 的机密或根密钥**。
+
+## 核心组件
+
+### `AgentDispatchHttpTransport` (客户端)
+
+此组件运行在 **进程 A** 中。它实现了 `AgentDispatchTransport` 接口，但不是调用本地 Vault，而是将带签名的请求序列化为 JSON 载荷，并通过 HTTP 发送到远程端点。
+
+```typescript
+import { createAgentClient, AgentDispatchHttpTransport } from '@the-ai-company/cbio-node-runtime';
+
+// 进程 A 只需要知道远程 Vault 的 URL
+const transport = new AgentDispatchHttpTransport('http://localhost:3000/dispatch');
+
+const agent = createAgentClient({
+  agentIdentity, // 进程 A 仅持有自己的身份私钥
+  capability,    // 进程 A 仅了解被授予的权限
+  transport,
+});
+
+// A 进程请求代发，机密明文全程不进入 A 的内存
+await agent.dispatch({
+  secretAlias: 'api-token',
+  targetUrl: 'https://api.example.com/data',
+  method: 'POST',
+});
+```
+
+### `handleVaultHttpDispatch` (服务端)
+
+此辅助函数运行在 **进程 B** 中。它提供了将传入的 HTTP 请求体传递给 `VaultService` 的标准方法。它处理的是完全 JSON 安全的 `VaultAgentDispatchRequest` 格式。
+
+```typescript
+import { createVaultService, handleVaultHttpDispatch } from '@the-ai-company/cbio-node-runtime';
+
+// 在任何 Node.js HTTP 服务器（如 Express/Fastify）中：
+server.post('/dispatch', async (req, res) => {
+  const result = await handleVaultHttpDispatch(vaultService, req.body);
+  res.json(result);
+});
+```
+
+## 安全优势
+
+- **零机密暴露**：即使进程 A（如 LLM 进程）由于提示词注入（Prompt Injection）或内存检查被攻破，攻击者也无法提取 Vault 中的机密，因为它们物理上存储在进程 B 中。
+- **受控出口面**：进程 B 强制执行 **权限表 (Capabilities)**。它只会在请求目的地匹配 Owner 预设的白名单 URL 时，才会注入机密并代发请求。
+- **审计追踪**：进程 B 维护一份独立的、追加式审计日志，记录每个 Agent 发起的所有敏感请求。
+
+## 示例
+
+查看 [examples/process-isolation.ts](../examples/process-isolation.ts) 获取该架构的完整运行示例。

package/docs/zh/README.md

@@ -2,6 +2,11 @@
 
 cbio 权限核心运行时。仅库，无 CLI 或 TUI。
 
+## 文档
+
+- [进程隔离 (A/B 架构)](PROCESS_ISOLATION.md)
+- [根目录文档](../../README.md)
+
 主入口现在围绕四个模块：
 - `vault-core`
 - `clients/owner`

package/examples/process-isolation.ts

@@ -0,0 +1,155 @@
+import http from "node:http";
+import {
+  createIdentity,
+  createVault,
+  createAgentClient,
+  createVaultService,
+  handleVaultHttpDispatch,
+  AgentDispatchHttpTransport,
+  MemoryStorageProvider,
+} from "../src/runtime/index.js";
+import { LocalSigner } from "../src/protocol/crypto.js";
+
+/**
+ * This example demonstrates the A/B Process Architecture (Process Isolation).
+ * 
+ * - Process B (The Vault): Hosts the actual secrets and performs the HTTP dispatch.
+ * - Process A (The Agent): Signs requests and sends them to Process B. A never sees the secret.
+ */
+
+// --- Process B: The Vault Server Logic ---
+async function startVaultServer(port: number) {
+  const ownerIdentity = createIdentity({ nickname: "vault-owner" });
+  const storage = new MemoryStorageProvider();
+  
+  // Create a real vault in memory
+  const { core } = await createVault(storage, {
+    vaultId: "vault-isolated-server",
+    ownerIdentity,
+  });
+  
+  // Wrap as a Service
+  const service = createVaultService((core as any)._deps); 
+
+  const server = http.createServer(async (req, res) => {
+    if (req.method === "POST" && req.url === "/dispatch") {
+      let body = "";
+      for await (const chunk of req) body += chunk;
+      
+      console.log("[Process B] Received dispatch request from Agent");
+      
+      try {
+        const result = await handleVaultHttpDispatch(service, JSON.parse(body));
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        res.writeHead(500);
+        res.end(JSON.stringify({ ok: false, error: { code: "SERVER_ERROR", message } }));
+      }
+    } else {
+      res.writeHead(404).end();
+    }
+  });
+
+  return new Promise<{ server: http.Server; ownerIdentity: any; vault: any }>((resolve) => {
+    server.listen(port, () => {
+      console.log(`[Process B] Vault Server listening on port ${port}`);
+      resolve({ server, ownerIdentity, vault: core });
+    });
+  });
+}
+
+// --- Process A: The LLM Agent Logic ---
+async function runAgentDemo(port: number, agentIdentity: any, capability: any) {
+  // Process A ONLY knows the remote URL and its own Agent Identity.
+  // It has NO access to the Vault's master key or storage.
+  const transport = new AgentDispatchHttpTransport(`http://localhost:${port}/dispatch`);
+  
+  const agentClient = createAgentClient({
+    agentIdentity,
+    capability,
+    transport,
+    signer: new LocalSigner(agentIdentity),
+  });
+
+  console.log("[Process A] LLM Agent requesting secret-backed dispatch...");
+  
+  try {
+    const result = await agentClient.dispatch({
+      secretAlias: "api-token",
+      targetUrl: "https://httpbin.org/post",
+      method: "POST",
+      body: JSON.stringify({ message: "Hello from isolated Process A" }),
+    });
+
+    console.log("[Process A] Dispatch Result Status:", result.status);
+    console.log("[Process A] (Secret was injected by Process B and never touched Process A's memory)");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[Process A] Dispatch failed:", message);
+  }
+}
+
+// --- Orchestration ---
+async function main() {
+  const PORT = 3456;
+  
+  // 1. Start the "Vault Server" (Process B)
+  const { ownerIdentity, vault, server } = await startVaultServer(PORT);
+  
+  // 2. Setup: Owner (in Process B's context) grants permission to an Agent
+  const agentIdentity = createIdentity({ nickname: "llm-agent-1" });
+  
+  // Owner registers the agent and a capability (simulated local call for setup)
+  await vault.registerAgentIdentity({
+    vaultId: vault.vaultId,
+    owner: { kind: "owner", id: ownerIdentity.identityId },
+    agentIdentity: {
+      vaultId: vault.vaultId,
+      agentId: agentIdentity.identityId,
+      publicKey: agentIdentity.publicKey,
+    },
+    proof: { signature: "setup-proof", ownerId: ownerIdentity.identityId, requestedAt: new Date().toISOString() },
+  });
+
+  // Owner writes a secret (simulated local call for setup)
+  const secret = await vault.writeSecret({
+    kind: "owner.write_secret",
+    vaultId: vault.vaultId,
+    owner: { kind: "owner", id: ownerIdentity.identityId },
+    alias: "api-token",
+    plaintext: "SK-PROD-12345",
+    targetBindings: [{ kind: "site", targetId: "httpbin.org", targetUrl: "https://httpbin.org/post", methods: ["POST"] }],
+    requestedAt: new Date().toISOString(),
+    proof: { signature: "setup-proof", ownerId: ownerIdentity.identityId, requestedAt: new Date().toISOString() },
+  });
+
+  const capability = {
+    vaultId: vault.vaultId,
+    capabilityId: "cap-llm-1",
+    agentId: agentIdentity.identityId,
+    secretIds: [secret.secretId.value],
+    secretAliases: ["api-token"],
+    operation: "dispatch_http" as const,
+    allowedTargets: ["https://httpbin.org/post"],
+    allowedMethods: ["POST"],
+    issuedAt: new Date().toISOString(),
+  };
+
+  await vault.registerCapability({
+    vaultId: vault.vaultId,
+    owner: { kind: "owner", id: ownerIdentity.identityId },
+    capability,
+    proof: { signature: "setup-proof", ownerId: ownerIdentity.identityId, requestedAt: new Date().toISOString() },
+  });
+
+  // 3. Run the "LLM Agent" (Process A)
+  await runAgentDemo(PORT, agentIdentity, capability);
+
+  // 4. Cleanup
+  server.close();
+  console.log("Demo finished.");
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@the-ai-company/cbio-node-runtime",
-  "version": "1.42.0",
+  "version": "1.45.2",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Node.js runtime for cbio identity and credential vault. Library only, no CLI or TUI.",
   "type": "module",
   "main": "./dist/runtime/index.js",
@@ -24,7 +27,9 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepare": "npm run build",
+    "build:docs": "npx typedoc --options typedoc.json",
+    "release": "npx standard-version && npm publish",
+    "prepare": "npm run build && npm run build:docs",
     "test": "npm run build && npm run test:acceptance",
     "test:acceptance": "node tests/smoke/runtime-surface.js && node tests/smoke/policy-and-persistence.js && node tests/smoke/replay-guard.js && node tests/smoke/security-guards.js"
   },
@@ -41,6 +46,9 @@
   "repository": "https://github.com/TheAICompany/cbio-node-runtime",
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "standard-version": "^9.5.0",
+    "typedoc": "^0.28.18",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.0.0"
   },
   "engines": {