@agentunion/fastaun-browser 0.2.19 → 0.3.0

package/_packed_docs/protocol//351/231/204/345/275/225J-/345/256/242/346/210/267/347/253/257/346/216/245/345/205/245/347/244/272/344/276/213.md

@@ -0,0 +1,402 @@
+## 12. 完整示例
+
+> 以下示例以说明协议顺序和字段结构为主，属于最小接入样例。辅助函数如 `loadCert()`、`verifyPeerHelloReply()`、`signWithPrivateKey()` 仅为伪代码占位，实际 SDK 或生产实现需补充错误处理、超时控制、证书校验策略与连接重试。
+
+### 12.1 Gateway 模式：浏览器应用完整流程
+
+```javascript
+// 1. 连接 Gateway
+const ws = new WebSocket('wss://gateway.example.com/aun');
+let msgId = 1;
+let token = null;
+let gatewayNonce = null;
+let savedClientNonce = null;  // 保存 client_nonce 用于验证 Auth 服务签名
+let savedRequestId = null;
+
+ws.onopen = () => {
+  // Gateway 会先推送 challenge；收到后再发 auth.* / auth.connect
+};
+
+// 处理响应和事件
+ws.onmessage = async (event) => {
+  const msg = JSON.parse(event.data);
+
+  // challenge：保存 Gateway nonce，然后开始 auth.* 两阶段登录
+  if (msg.method === 'challenge') {
+    gatewayNonce = msg.params.nonce;
+
+    // 步骤1：发送 login_aid1（必需字段：aid, cert, request_id, client_nonce）
+    savedRequestId = `req-${Date.now()}`;
+    savedClientNonce = crypto.randomUUID();
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'auth.aid_login1',
+      params: {
+        aid: 'alice.aid.pub',
+        cert: loadCert(),               // PEM 格式证书（必需）
+        request_id: savedRequestId,     // 关联两阶段登录（必需）
+        client_nonce: savedClientNonce   // 客户端随机 nonce（必需）
+      }
+    }));
+    return;
+  }
+
+  // login_aid1 响应：返回 nonce + client_nonce_signature + auth_cert
+  if (msg.result && msg.result.nonce && msg.result.client_nonce_signature) {
+    // 验证 Auth 服务身份：用 auth_cert 公钥验证 client_nonce_signature
+    const authVerified = await verifyAuthSignature(
+      msg.result.auth_cert, savedClientNonce, msg.result.client_nonce_signature
+    );
+    if (!authVerified) throw new Error('Auth 服务身份验证失败');
+
+    // 步骤2：对 server nonce 签名，提交 login_aid2
+    const signature = await signWithPrivateKey(msg.result.nonce);
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'auth.aid_login2',
+      params: {
+        aid: 'alice.aid.pub',
+        request_id: savedRequestId,
+        nonce: msg.result.nonce,
+        signature: signature,
+        cert: loadCert()
+      }
+    }));
+  }
+
+  // login_aid2 响应（获得 token，但连接状态未变）
+  if (msg.result && msg.result.token && !msg.result.authenticated) {
+    token = msg.result.token;
+
+    // 步骤3：用 token 调用 auth.connect 完成 Gateway 模式会话初始化
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'auth.connect',
+      params: {
+        nonce: gatewayNonce,
+        auth: { method: 'kite_token', token },
+        protocol: {min: '1.0', max: '1.0'},
+        device: {id: 'browser-dev-001', type: 'browser'},
+        client: {name: 'MyApp', version: '1.0.0'},
+        capabilities: {e2ee: true, group_e2ee: true}
+      }
+    }));
+  }
+
+  // auth.connect 响应（连接已认证）
+  if (msg.result && msg.result.authenticated) {
+    console.log('Authenticated as:', msg.result.identity.aid);
+
+    // 现在可以调用所有方法
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'message.send',
+      params: {
+        to: 'bob.aid.pub',
+        type: 'text',
+        payload: {type: 'text', text: 'Hello Bob!'}
+      }
+    }));
+  }
+
+  // 收到消息事件
+  if (msg.method === 'event/message.received') {
+    console.log('Message from', msg.params.from, ':', msg.params.payload?.text);
+  }
+};
+```
+
+发送附件时，不应在 `payload` 中直接嵌入文件二进制，而应携带 `storage.*` 返回的对象引用：
+
+```javascript
+ws.send(JSON.stringify({
+  jsonrpc: '2.0',
+  id: msgId++,
+  method: 'message.send',
+  params: {
+    to: 'bob.aid.pub',
+    payload: {
+      type: 'file',
+      text: '请查收附件',
+      attachments: [
+        {
+          url: 'https://storage.example.com/objects/default/docs/report.pdf',
+          bucket: 'default',
+          object_key: 'docs/report.pdf',
+          filename: 'report.pdf',
+          size: 245678,
+          sha256: '3d8e577bddb17db339eae0b3d9bcf180f48c3f1a12f5f7ddce9f4ea7d3c1af4a',
+          content_type: 'application/pdf'
+        }
+      ]
+    }
+  }
+}));
+```
+
+### 12.2 Gateway 模式：移动应用完整流程（iOS）
+
+```swift
+// 1. 连接 Gateway
+var request = URLRequest(url: URL(string: "wss://gateway.example.com/aun")!)
+let ws = WebSocket(request: request)
+var msgId = 1
+var token: String?
+var gatewayNonce: String?
+var savedClientNonce: String?
+var savedRequestId: String?
+
+// 2. 连接成功后，等待 Gateway challenge，再调用 auth.* 获取 token
+ws.onConnected = {
+    // no-op: Gateway 会主动推送 challenge
+}
+
+// 3. 处理响应和事件
+ws.onMessage = { message in
+    if let challenge = message as? ChallengeMessage {
+        gatewayNonce = challenge.nonce
+        savedRequestId = UUID().uuidString
+        savedClientNonce = UUID().uuidString
+        ws.send(jsonrpc: "2.0", id: msgId, method: "auth.aid_login1",
+               params: [
+                   "aid": "alice.aid.pub",
+                   "cert": loadCert(),                    // PEM 格式证书（必需）
+                   "request_id": savedRequestId!,         // 关联两阶段登录（必需）
+                   "client_nonce": savedClientNonce!       // 客户端随机 nonce（必需）
+               ])
+        msgId += 1
+        return
+    }
+
+    // login_aid1 响应：返回 nonce + client_nonce_signature + auth_cert
+    if let loginResp = message as? LoginAid1Response {
+        // 验证 Auth 服务身份：用 auth_cert 公钥验证 client_nonce_signature
+        guard verifyAuthSignature(
+            authCert: loginResp.authCert,
+            clientNonce: savedClientNonce!,
+            signature: loginResp.clientNonceSignature
+        ) else { fatalError("Auth 服务身份验证失败") }
+
+        // 对 server nonce 签名，提交 login_aid2
+        let signature = signWithPrivateKey(loginResp.nonce)
+        ws.send(jsonrpc: "2.0", id: msgId, method: "auth.aid_login2",
+               params: [
+                   "aid": "alice.aid.pub",
+                   "request_id": savedRequestId!,
+                   "nonce": loginResp.nonce,
+                   "signature": signature,
+                   "cert": loadCert()
+               ])
+        msgId += 1
+    }
+
+    // login_aid2 响应（获得 token，但连接状态未变）
+    if let loginResp = message as? LoginAid2Response {
+        token = loginResp.token
+
+        // 用 token 调用 auth.connect 完成 Gateway 模式会话初始化
+        let connectParams: [String: Any] = [
+            "nonce": gatewayNonce!,
+            "auth": ["method": "kite_token", "token": token!],
+            "protocol": ["min": "1.0", "max": "1.0"],
+            "device": ["id": "ios-dev-001", "type": "mobile"],
+            "client": ["name": "MyApp", "version": "1.0.0"],
+            "capabilities": ["e2ee": true, "group_e2ee": true]
+        ]
+        ws.send(jsonrpc: "2.0", id: msgId, method: "auth.connect", params: connectParams)
+        msgId += 1
+    }
+
+    // auth.connect 响应（连接已认证）
+    if let response = message as? AuthConnectResponse, response.authenticated {
+        print("Authenticated as: \(response.identity.aid)")
+
+        // 现在可以调用所有方法
+        ws.send(jsonrpc: "2.0", id: msgId, method: "message.send",
+               params: [
+                   "to": "bob.aid.pub",
+                   "payload": ["type": "text", "text": "Hello Bob!"]
+               ])
+        msgId += 1
+    }
+
+    // 收到消息事件
+    if let event = message as? MessageReceivedEvent {
+        print("Message from \(event.from): \(event.payload["text"] ?? "")")
+    }
+}
+```
+
+### 12.3 Peer 模式：最小直连接入示例
+
+```javascript
+const ws = new WebSocket('wss://bob.company.com:9900/acp');
+let msgId = 1;
+let localNonce = crypto.randomUUID();
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: msgId++,
+    method: 'initialize',
+    params: {
+      mode: 'peer',
+      protocol: {min: '1.0', max: '1.0'},
+      clientInfo: {name: 'PeerClient', version: '1.0.0'}
+    }
+  }));
+
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: msgId++,
+    method: 'peer.hello',
+    params: {
+      aid: 'alice.aid.pub',
+      cert: loadCert(),
+      nonce: localNonce,
+      protocol: {min: '1.0', max: '1.0'}
+    }
+  }));
+};
+
+ws.onmessage = async (event) => {
+  const msg = JSON.parse(event.data);
+
+  if (msg.result?.nonce && msg.result?.nonce_signature && msg.result?.cert) {
+    const peerOk = await verifyPeerHelloReply(
+      msg.result.cert,
+      localNonce,
+      msg.result.nonce_signature
+    );
+    if (!peerOk) throw new Error('Peer 身份验证失败');
+
+    const replySignature = await signWithPrivateKey(msg.result.nonce);
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'peer.confirm',
+      params: {
+        nonce_signature: replySignature
+      }
+    }));
+  }
+
+  if (msg.result?.authenticated) {
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'message.send',
+      params: {
+        to: 'bob.company.com',
+        type: 'text',
+        payload: {type: 'text', text: 'Hello from peer mode'}
+      }
+    }));
+  }
+};
+```
+
+### 12.4 Relay 模式：最小中继接入示例
+
+```javascript
+const ws = new WebSocket('wss://relay.aun.network:9800/relay');
+let msgId = 1;
+let localNonce = crypto.randomUUID();
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: msgId++,
+    method: 'initialize',
+    params: {
+      mode: 'relay',
+      protocol: {min: '1.0', max: '1.0'},
+      clientInfo: {name: 'RelayClient', version: '1.0.0'}
+    }
+  }));
+
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: msgId++,
+    method: 'relay.register',
+    params: {
+      aid: 'alice.aid.pub'
+    }
+  }));
+
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: msgId++,
+    method: 'relay.forward',
+    params: {
+      to: 'bob.company.com',
+      message: {
+        jsonrpc: '2.0',
+        id: msgId++,
+        method: 'peer.hello',
+        params: {
+          aid: 'alice.aid.pub',
+          cert: loadCert(),
+          nonce: localNonce,
+          protocol: {min: '1.0', max: '1.0'}
+        }
+      }
+    }
+  }));
+};
+
+ws.onmessage = async (event) => {
+  const msg = JSON.parse(event.data);
+
+  if (msg.method === 'event/relay.message' && msg.params?.message?.result?.nonce_signature) {
+    const inner = msg.params.message.result;
+    const peerOk = await verifyPeerHelloReply(inner.cert, localNonce, inner.nonce_signature);
+    if (!peerOk) throw new Error('Relay 上的对端身份验证失败');
+
+    const replySignature = await signWithPrivateKey(inner.nonce);
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'relay.forward',
+      params: {
+        to: 'bob.company.com',
+        message: {
+          jsonrpc: '2.0',
+          id: msgId++,
+          method: 'peer.confirm',
+          params: {
+            nonce_signature: replySignature
+          }
+        }
+      }
+    }));
+  }
+
+  if (msg.method === 'event/relay.message' && msg.params?.message?.result?.authenticated) {
+    ws.send(JSON.stringify({
+      jsonrpc: '2.0',
+      id: msgId++,
+      method: 'relay.forward',
+      params: {
+        to: 'bob.company.com',
+        message: {
+          jsonrpc: '2.0',
+          id: msgId++,
+          method: 'message.send',
+          params: {
+            to: 'bob.company.com',
+            type: 'text',
+            payload: {type: 'text', text: 'Hello from relay mode'}
+          }
+        }
+      }
+    }));
+  }
+};
+```
+
+---

package/_packed_docs/protocol//351/231/204/345/275/225K-Agent_Web/345/217/221/347/216/260/345/215/217/350/256/256.md

@@ -0,0 +1,130 @@
+# 13. 泛域名与 Agent Web 访问约定
+
+本章说明 Issuer 配置泛域名解析（`*.{issuer_domain}`）的作用，以及 `https://{aid}.{issuer_domain}` 的默认访问行为。
+
+> **术语说明**：
+> - `{issuer_domain}`：Issuer 的域名，如 `aid.pub`
+> - `{aid}`：完整的 Agent Identifier，如 `alice.aid.pub`
+> - `https://{aid}.{issuer_domain}`：本文用于描述 Agent 的标准 Web 入口；具体主机名生成规则由 Issuer 的 AID 编排方式决定
+
+## 13.1 设计目标
+
+Issuer CA 申请流程要求配置泛域名解析 `*.{issuer_domain}`，其核心目的不是证书签发本身，而是为 Issuer 下的每个 Agent 提供统一、稳定、可预测的 Web 访问入口。
+
+这样做有几个直接收益：
+
+- **统一入口**：每个 Agent 天然拥有一个可访问的专属 URL，无需额外登记路由
+- **发现友好**：人类用户和其他 Agent 可以直接通过 AID 对应的域名访问 Agent 描述或首页
+- **实现简化**：服务端只需接收所有 `*.{issuer_domain}` 请求，再按 Host 头解析目标 Agent
+- **扩展友好**：在不改变 AID 和基础路由规则的前提下，可为 Agent 挂载更多页面和内置服务
+
+## 13.2 泛域名的作用
+
+泛域名解析的主要作用是让 Issuer 统一承接所有 Agent 子域名请求：
+
+```text
+*.{issuer_domain}  ->  Agent Web Gateway / 站点入口 / 反向代理
+```
+
+请求到达入口服务后，实现者通常按以下步骤处理：
+
+1. 从 HTTP Host 提取目标主机名
+2. 将主机名映射到目标 AID 或目标 Agent 资源
+3. 根据访问路径、访问方类型和部署策略返回 `agent.md`、`index.html` 或某个内置服务页面
+
+## 13.3 实现建议（非规范性）
+
+以下内容主要是实现建议，不是协议强制要求：
+
+- **DNS**：推荐将 `*.{issuer_domain}` 解析到统一的入口层（CDN、LB、反向代理或 Web Gateway）
+- **TLS**：推荐为 `*.{issuer_domain}` 配置泛域名证书，或在入口层统一终止 TLS
+- **路由**：推荐由统一入口按 Host 头解析目标 Agent，而不是为每个 Agent 单独配置站点
+- **静态资源**：推荐将 `agent.md` 和 `index.html` 视为 Agent 的两个标准 Web 资源
+- **访问方识别**：如需区分“Agent 访问”和“人类访问”，推荐基于 User-Agent、Accept 头、显式客户端标识或上层调用约定实现
+- **缓存**：推荐对 `agent.md` 使用较短缓存时间，避免 Agent 描述信息长期陈旧；首页可按产品需求设置缓存策略
+
+## 13.4 标准访问路径与默认行为（规范性）
+
+本节定义 Agent Web 访问的**强制行为**。
+
+### 13.4.1 根路径访问
+
+当访问：
+
+```text
+https://{aid}.{issuer_domain}
+```
+
+服务端必须根据访问方类型返回不同的默认资源：
+
+- **Agent（无头浏览器、程序化客户端、协议消费者）访问时**：
+  - **必须**等价于访问：
+    ```text
+    https://{aid}.{issuer_domain}/agent.md
+    ```
+  - 返回该 Agent 的 `agent.md` 文档内容
+
+- **人类用户（有头浏览器）访问时**：
+  - **必须**等价于访问：
+    ```text
+    https://{aid}.{issuer_domain}/index.html
+    ```
+  - 返回该 Agent 的首页内容
+
+这里的 `agent.md` 指 Agent 的标准描述文档，其格式和字段定义已提升到主协议 [06-服务协议](06-服务协议.md) 的 `search.*` 章节统一规定。完整规格见 [agent.md/SCHEMA.md](agent.md/SCHEMA.md)，示例见 [human-developer.md](agent.md/examples/human-developer.md)、[openclaw-lobster.md](agent.md/examples/openclaw-lobster.md)、[codeagent-claudecode.md](agent.md/examples/codeagent-claudecode.md)。附录 K 只负责定义 Web 访问入口和默认路径行为，不再重复承载 `agent.md` 结构规范。
+
+### 13.4.2 显式访问 `agent.md`
+
+当显式访问：
+
+```text
+https://{aid}.{issuer_domain}/agent.md
+```
+
+无论访问方是人还是 Agent，服务端都**必须**返回该 Agent 的 `agent.md` 内容，不得再根据访问方类型改写为其他资源。
+
+### 13.4.3 显式访问 `index.html`
+
+当显式访问：
+
+```text
+https://{aid}.{issuer_domain}/index.html
+```
+
+无论访问方是人还是 Agent，服务端都**必须**返回该 Agent 的首页内容，不得再根据访问方类型改写为 `agent.md`。
+
+> 说明：协议的规范 URL 为 HTTPS。如部署方额外开放 HTTP 入口，可返回相同内容，或重定向到对应的 HTTPS URL。
+
+### 13.4.4 内置服务页面
+
+当访问：
+
+```text
+https://{aid}.{issuer_domain}/{svc}
+```
+
+表示访问该 Agent 的某个内置服务页面，其中 `{svc}` 代表系统内置服务标识。
+
+此时：
+
+- 该路径**必须**被解释为“指定 Agent 的指定内置服务页面”
+- 页面或资源的具体内容**由实现者决定**
+- 如该服务不存在，服务端应返回标准 HTTP 错误（如 `404 Not Found`）
+
+### 13.4.5 路径优先级
+
+服务端处理优先级必须如下：
+
+1. 显式路径优先：`/agent.md`、`/index.html`、`/{svc}` 按显式路径处理
+2. 仅当访问根路径 `/` 或无路径时，才根据访问方类型选择默认资源
+
+## 13.5 与 AID 和 Issuer 的关系
+
+该约定意味着：
+
+- 每个 AID 不只是一个通信身份，也是一个标准 Web 可访问对象
+- Issuer 不仅负责证书签发和身份管理，也通常负责该 AID 对应 Web 入口的承接
+- `agent.md` 是 Agent 面向其他 Agent 的默认公开描述文档，也是 `search.*` 的基础索引对象
+- `index.html` 是 Agent 面向人类用户的默认首页
+
+这使 AUN 在保持去中心化身份体系的同时，也为 Agent 的公开发现、说明页、服务页和后续生态扩展提供了统一入口。