yihe-verify 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# yihe-verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+验证一个「AI 能力节点」的**能力声明是否被篡改**，并列出一眼看清它能做什么、入口在哪、多少钱。
+
+**零依赖**（只用 Node 内置 `crypto` / `fetch`），Node >= 18。
+
+```bash
+npx yihe-verify https://<节点地址>
+```
+
+输出示例：
+
+```
+  节点        : https://node.example.com
+  验签结果    : ✅ 通过  (ok)
+  算法/keyId  : ed25519 / 8c34dda1
+  被签字节    : 11113  sha256=089432d8b35f3483…
+
+  该节点声明的能力（8 个）:
+  ------------------------------------------------------------------------
+  [1] broadcast (live)
+      广播节点（broadcast）
+      https://node.example.com/ai-broadcast.md
+  [3] core (live)
+      认知核心（core / YiHe 认知核心）
+      https://node.example.com/ask
+  ...
+```
+
+## 为什么需要验签
+
+AI 能力节点把「我能干什么、入口在哪、怎么计费」写成一份**机器可读的能力声明**（`ai-broadcast.md`），
+任何 AI 读完就能直接调用。
+
+问题在于：**如果这份声明能被改写，攻击者就能把入口换成自己的** ——
+调用方的请求（将来还有凭据和钱）就送到攻击者手里。
+
+所以节点用 **ed25519** 给声明签名，并公开公钥：**任何人**都能离线验签，
+证明「这份声明确实是这个节点发出的、且一个字节都没被改」。
+
+## 它验证了什么
+
+| 步骤 | 请求 |
+|---|---|
+| 1 | `GET /ai-broadcast.md` —— 能力声明（被签名的正文） |
+| 2 | `GET /ai-broadcast.md.sig` —— 分离式签名（base64） |
+| 3 | `GET /pubkey` —— 公钥（PEM）与 `keyId` |
+| 4 | 用公钥对「**签名区块之前**的正文」做 ed25519 验签 |
+
+> **签名范围**刻意不做任何 trim：正文一个字节变了就验不过。这正是防篡改要的。
+
+## 作为库使用
+
+```js
+import { verifyNode } from 'yihe-verify';
+
+const r = await verifyNode('https://node.example.com');
+if (!r.ok) throw new Error(`广播验签失败: ${r.reason}`);
+
+console.log(r.keyId, r.services.map((s) => s.name));
+```
+
+返回：
+
+```js
+{
+  ok: true, base, algorithm: 'ed25519', keyId: '8c34dda1',
+  payloadBytes, sha256, services: [{ index, name, kind, title, description, entry, call, returns, status }]
+}
+```
+
+## 安全提示（别过度信任）
+
+1. **验签通过 ≠ 合规、≠ 服务质量**：只说明「是这把钥签的、内容没被改」。
+2. **首次获取仍有 TOFU 问题**：公钥也是从该节点取的。若攻击者能在你首次获取时同时替换清单与公钥，首次仍可能被骗。
+   **建议固定 `keyId`**：同一节点 `keyId` 变了就该警觉。
+3. **签名保护内容，TLS 保护传输**：两者互补 —— 签名让声明**被镜像/转发到别处**也照样能验真。
+
+## 自己运营一个节点？
+
+这套东西是「AI 能力网络」的一部分：任何人都能把自己的服务变成一个**AI 可直接调用的入口**，
+调用方充值走**运营者自己的收款账户**（平台不在调用上抽成），平台费 ¥1/天（满月封顶 ¥29）。
+
+```bash
+curl -fsSL https://<平台地址>/install.sh | sudo bash
+```
+
+谈清楚再决定：`https://<平台地址>/join`（含**不承诺流量与收入**等如实说明）。
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * yihe-verify · 验证「AI 能力节点」广播清单的 ed25519 签名，并列出它声明的能力。
+ *
+ * 为什么需要它：AI 能力节点把「我能干什么、入口在哪、多少钱」写在广播清单（ai-broadcast.md）里。
+ * 如果这份声明能被改写，攻击者就能把入口换成自己的 —— 调用方的请求（甚至凭据）就送到别人手里。
+ * 所以节点用 ed25519 给清单签名；**任何人**都能用它的公钥离线验签。
+ *
+ * 零依赖（只用 Node 内置 crypto / fetch），Node >= 18。
+ *
+ * 用法：
+ *   npx yihe-verify https://<节点地址>
+ *   npx yihe-verify https://<节点地址> --json
+ *
+ * 作为库：
+ *   import { verifyNode } from 'yihe-verify';
+ *   const r = await verifyNode('https://<节点地址>');
+ *   if (!r.ok) throw new Error('广播验签失败');
+ */
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+/** 清单里签名区块的起始标题（签名范围 = 该行**之前**的全部文本） */
+export const SIG_HEADING = '## 签名（出生即带）';
+
+/** 把清单切成「被签名的正文」与「签名区块」。 */
+export function splitManifest(markdown) {
+  const i = markdown.indexOf(SIG_HEADING);
+  return { body: i >= 0 ? markdown.slice(0, i) : markdown, signed: i >= 0 };
+}
+
+/** 从正文里取出机器可读的能力清单（```json 区块）。 */
+export function parseServices(body) {
+  const m = body.match(/```json\s*([\s\S]*?)```/);
+  if (!m) return [];
+  try {
+    return JSON.parse(m[1]).services || [];
+  } catch {
+    return [];
+  }
+}
+
+async function get(url, timeout) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeout) });
+  if (!res.ok) throw new Error(`${url} -> HTTP ${res.status}`);
+  return res.text();
+}
+
+/**
+ * 验证一个节点的广播清单。
+ * @param {string} base 节点地址，如 https://node.example.com
+ * @param {{timeout?: number}} [opts]
+ * @returns {Promise<{ok: boolean, reason?: string, base: string, keyId?: string,
+ *   payloadBytes?: number, sha256?: string, services?: any[]}>}
+ */
+export async function verifyNode(base, opts = {}) {
+  const timeout = opts.timeout ?? 10000;
+  const b = String(base).replace(/\/+$/, '');
+  if (!/^https?:\/\//.test(b)) return { ok: false, base: b, reason: '地址必须以 http(s):// 开头' };
+  let md, sigText, key;
+  try {
+    md = await get(b + '/ai-broadcast.md', timeout);
+    sigText = (await get(b + '/ai-broadcast.md.sig', timeout)).trim();
+    key = JSON.parse(await get(b + '/pubkey', timeout));
+  } catch (e) {
+    return { ok: false, base: b, reason: `取清单/签名/公钥失败: ${e.message}` };
+  }
+  const { body, signed } = splitManifest(md);
+  if (!signed) return { ok: false, base: b, reason: '清单没有签名区块（该节点未签名）' };
+  if (!key.publicKeyPem) return { ok: false, base: b, reason: '公钥缺失' };
+
+  let ok = false;
+  try {
+    const sig = Buffer.from(sigText, 'base64');
+    ok = crypto.verify(null, Buffer.from(body), crypto.createPublicKey(key.publicKeyPem), sig);
+  } catch (e) {
+    return { ok: false, base: b, reason: `验签异常: ${e.message}` };
+  }
+  return {
+    ok,
+    base: b,
+    reason: ok ? 'ok' : '签名不匹配（清单被改过，或公钥不是签发者）',
+    algorithm: key.algorithm || 'ed25519',
+    keyId: key.keyId || '',
+    payloadBytes: Buffer.byteLength(body, 'utf8'),
+    sha256: crypto.createHash('sha256').update(body).digest('hex'),
+    services: parseServices(body),
+  };
+}
+
+// ------------------------------- CLI -------------------------------
+function usage() {
+  console.log(`yihe-verify · 验证 AI 能力节点广播签名（ed25519，零依赖）
+
+用法:
+  npx yihe-verify <节点地址> [--json]
+
+例:
+  npx yihe-verify https://node.example.com
+  npx yihe-verify https://node.example.com --json
+
+它验证什么:
+  1. GET <节点>/ai-broadcast.md      能力声明（被签名）
+  2. GET <节点>/ai-broadcast.md.sig  分离式签名
+  3. GET <节点>/pubkey               公钥
+  4. 用公钥对「签名区块之前的正文」做 ed25519 验签 → 一个字节改动即失败
+
+安全提示: 验签通过只说明「是这把钥签的、内容没被改」，
+  不代表内容合规，也不代表服务质量。首次获取公钥仍有 TOFU 问题 ——
+  建议固定 keyId（变了就该警觉）。`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
+    usage();
+    process.exit(argv.length ? 0 : 2);
+  }
+  const json = argv.includes('--json');
+  const target = argv.find((a) => !a.startsWith('-'));
+  const r = await verifyNode(target);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    process.exit(r.ok ? 0 : 1);
+  }
+  console.log(`\n  节点        : ${r.base}`);
+  console.log(`  验签结果    : ${r.ok ? '✅ 通过' : '❌ 失败'}  (${r.reason})`);
+  if (r.keyId) {
+    console.log(`  算法/keyId  : ${r.algorithm} / ${r.keyId}`);
+    console.log(`  被签字节    : ${r.payloadBytes}  sha256=${String(r.sha256).slice(0, 16)}…`);
+  }
+  if (r.services?.length) {
+    console.log(`\n  该节点声明的能力（${r.services.length} 个）:`);
+    console.log('  ' + '-'.repeat(72));
+    for (const s of r.services) {
+      console.log(`  [${s.index}] ${s.name} (${s.status})`);
+      console.log(`      ${String(s.title || '').slice(0, 60)}`);
+      console.log(`      ${s.entry || ''}`);
+    }
+  }
+  if (r.ok) console.log('\n  提示: 验签通过只说明「是这把钥签的、内容没被改」，不代表服务质量。\n');
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch((e) => {
+    console.error('出错:', e.message);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "yihe-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "验证 AI 能力节点（Agent 互联网）广播清单的 ed25519 签名，并列出其声明的能力、入口与定价。零依赖，Node >= 18。",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "yihe-verify": "index.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-agent",
+    "agent",
+    "agents",
+    "capability-discovery",
+    "agent-internet",
+    "ed25519",
+    "signature",
+    "verify",
+    "llm-tools"
+  ],
+  "author": "YiHe",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}