@agentunion/fastaun 0.4.12 → 0.4.13

package/CHANGELOG.md

@@ -6,6 +6,33 @@
 
 ---
 
+## 0.4.13 — 2026-06-09
+
+### 新功能
+- **发送结果回填 envelope**：`message.send` / `group.send` / `message.thought.put` / `group.thought.put` 的返回结果新增规范化 `envelope` 字段，使发送方回执与接收端信封元数据一致；新增 `APP_SEND_ENVELOPE_METHODS` 与 `sendResultEnvelope()` / `attachSendResultEnvelope()`，rpc-pipeline 在 `postprocess` 后统一附加，V2 加密路径经 `_skipSendResultEnvelope` 标志跳过明文附加、由外层 V2 协调器在加密后补挂避免重复（四语言对齐）
+
+### 修复
+- **refresh_token 失效自愈**：新增需重登判定（命中 `relogin_required` 或 `missing refresh_token` / `invalid_or_expired_refresh_token` / `refresh not supported`）与清缓存逻辑；刷新失败需重登时清空本地 `access_token`/`refresh_token`/`kite_token` 并持久化，client 层 token 刷新循环检测到需重登时发布 `token.refresh_exhausted` 事件（带 `relogin_required: true`）、断连触发重连，下次 `connectSession` 因无可用 token 自动走两步登录；refresh RPC 补传 `aid`/`device_id`/`slot_id`/`access_token`/`sdk_lang`/`sdk_version`，`AuthError` 携带 `data` 透传服务端响应（四语言对齐）
+- **重连状态位修复**：断连分支补齐 `_reconnectActive = false`，token 循环中 `publish`/`_handleTransportDisconnect` 改为 `await`，避免重连标志残留导致后续重连被跳过
+- **protected_headers 类型归一**：V2 发送方法的 envelope 元数据归一时识别 `ProtectedHeaders` 对象（经 `toObject()` 探测）并转 dict，修复传入对象（非 dict）时 protected_headers 被丢弃的问题（四语言对齐）
+
+### 优化
+- **app_message_envelope 字段收窄**：envelope 键收窄为可转发元数据（`from`/`to`/`group_id`/`type`/`kind`/`version`/`timestamp`/`encrypted`/`context`/`protected_headers`/`payload_type`），移除 `message_id`/`seq`/`device_id`/`slot_id` 等本地与传输层字段，不再向应用层泄漏内部字段并剔除 `_auth`（四语言对齐）
+- **RPC 日志 token 脱敏**：短 RPC 请求/响应 debug 日志对 `access_token`/`refresh_token`/`kite_token`/`token` 及 `_token` 结尾键递归脱敏（`<redacted len=.. sha256=..>`），避免明文 token 落日志（四语言对齐）
+
+### 测试
+- `refresh 业务失败且要求重登时应清掉本地 token 缓存`
+- `connectSession 在 refresh 失败后应继续走两步登录`
+- `应用层消息 envelope 只保留可转发字段并归一化 headers`
+- 更新 `publishAppEvent` 与群撤回相关用例断言 envelope 收窄、不含 `message_id`/`seq`/`device_id`/`slot_id`
+
+### 服务端协同（本版本配套）
+- **`auth.refresh_token` 响应结构化**：新增 `relogin_required` / `retryable` / `diagnostic` / `aid` / `refresh_count` 字段，SDK 据 `relogin_required`/`retryable` 区分"重新登录"与"退避重试"，不再单纯按 `error` 字符串判断
+- **JWT 老 SDK 兼容与即时吊销**：`AUN_JWT_LEGACY_ACCESS_TOKEN_COMPAT`（默认开）放行合法 JWT 避免迁移期重连风暴；`auth.token.revoked` 事件携带 `jti`/`expires_at`，gateway 按真实 TTL 缓存吊销
+- **V2 P2P 写入幂等**：服务端 `v2_write_peer_message`/`v2_write_peer_wrap` 捕获唯一键冲突逐字段比对，重发相同 message_id 幂等返回、不再产生 seq 空洞；自发自收跳过重复 self-sync 推送
+
+---
+
 ## 0.4.12 — 2026-06-08
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,33 @@
 
 ---
 
+## 0.4.13 — 2026-06-09
+
+### 新功能
+- **发送结果回填 envelope**：`message.send` / `group.send` / `message.thought.put` / `group.thought.put` 的返回结果新增规范化 `envelope` 字段，使发送方回执与接收端信封元数据一致；新增 `APP_SEND_ENVELOPE_METHODS` 与 `sendResultEnvelope()` / `attachSendResultEnvelope()`，rpc-pipeline 在 `postprocess` 后统一附加，V2 加密路径经 `_skipSendResultEnvelope` 标志跳过明文附加、由外层 V2 协调器在加密后补挂避免重复（四语言对齐）
+
+### 修复
+- **refresh_token 失效自愈**：新增需重登判定（命中 `relogin_required` 或 `missing refresh_token` / `invalid_or_expired_refresh_token` / `refresh not supported`）与清缓存逻辑；刷新失败需重登时清空本地 `access_token`/`refresh_token`/`kite_token` 并持久化，client 层 token 刷新循环检测到需重登时发布 `token.refresh_exhausted` 事件（带 `relogin_required: true`）、断连触发重连，下次 `connectSession` 因无可用 token 自动走两步登录；refresh RPC 补传 `aid`/`device_id`/`slot_id`/`access_token`/`sdk_lang`/`sdk_version`，`AuthError` 携带 `data` 透传服务端响应（四语言对齐）
+- **重连状态位修复**：断连分支补齐 `_reconnectActive = false`，token 循环中 `publish`/`_handleTransportDisconnect` 改为 `await`，避免重连标志残留导致后续重连被跳过
+- **protected_headers 类型归一**：V2 发送方法的 envelope 元数据归一时识别 `ProtectedHeaders` 对象（经 `toObject()` 探测）并转 dict，修复传入对象（非 dict）时 protected_headers 被丢弃的问题（四语言对齐）
+
+### 优化
+- **app_message_envelope 字段收窄**：envelope 键收窄为可转发元数据（`from`/`to`/`group_id`/`type`/`kind`/`version`/`timestamp`/`encrypted`/`context`/`protected_headers`/`payload_type`），移除 `message_id`/`seq`/`device_id`/`slot_id` 等本地与传输层字段，不再向应用层泄漏内部字段并剔除 `_auth`（四语言对齐）
+- **RPC 日志 token 脱敏**：短 RPC 请求/响应 debug 日志对 `access_token`/`refresh_token`/`kite_token`/`token` 及 `_token` 结尾键递归脱敏（`<redacted len=.. sha256=..>`），避免明文 token 落日志（四语言对齐）
+
+### 测试
+- `refresh 业务失败且要求重登时应清掉本地 token 缓存`
+- `connectSession 在 refresh 失败后应继续走两步登录`
+- `应用层消息 envelope 只保留可转发字段并归一化 headers`
+- 更新 `publishAppEvent` 与群撤回相关用例断言 envelope 收窄、不含 `message_id`/`seq`/`device_id`/`slot_id`
+
+### 服务端协同（本版本配套）
+- **`auth.refresh_token` 响应结构化**：新增 `relogin_required` / `retryable` / `diagnostic` / `aid` / `refresh_count` 字段，SDK 据 `relogin_required`/`retryable` 区分"重新登录"与"退避重试"，不再单纯按 `error` 字符串判断
+- **JWT 老 SDK 兼容与即时吊销**：`AUN_JWT_LEGACY_ACCESS_TOKEN_COMPAT`（默认开）放行合法 JWT 避免迁移期重连风暴；`auth.token.revoked` 事件携带 `jti`/`expires_at`，gateway 按真实 TTL 缓存吊销
+- **V2 P2P 写入幂等**：服务端 `v2_write_peer_message`/`v2_write_peer_wrap` 捕获唯一键冲突逐字段比对，重发相同 message_id 幂等返回、不再产生 seq 空洞；自发自收跳过重复 self-sync 推送
+
+---
+
 ## 0.4.12 — 2026-06-08
 
 ### 新功能

package/_packed_docs/sdk/09-group-rpc-manual.md

@@ -2082,11 +2082,9 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
 {
     "envelope": {
         "group_id": "g-abc123.agentid.pub",
-        "seq": 42,
-        "message_id": "uuid",
-        "sender_aid": "alice.agentid.pub",
-        "message_type": "group.message",
-        "dispatch_mode": "broadcast"
+        "from": "alice.agentid.pub",
+        "type": "text",
+        "timestamp": 1234567890000
     },
     "group_id": "g-abc123.agentid.pub",
     "seq": 42,
@@ -2098,7 +2096,7 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `msg["envelope"]["message_id"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
 
 ### event/group.message_recalled
 
@@ -2109,11 +2107,11 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 ```json
 {
     "envelope": {
-        "module_id": "group",
         "group_id": "g-abc123.agentid.pub",
-        "seq": 43,
-        "message_id": "grm-uuid",
-        "sender_aid": "alice.agentid.pub"
+        "from": "alice.agentid.pub",
+        "type": "group.message_recalled",
+        "kind": "group.message_recalled",
+        "timestamp": 1234567890000
     },
     "module_id": "group",
     "group_id": "g-abc123.agentid.pub",
@@ -2130,11 +2128,11 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 }
 ```
 
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `module_id`、`group_id`、`seq`、`message_id`、`sender_aid`、`device_id`、`slot_id` 等存在的字段 |
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
 | `module_id` | string | 固定 `"group"` |
 | `group_id` | string | 群组 ID |
 | `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |

package/_packed_docs/sdk/09-message-rpc-manual.md

@@ -513,10 +513,9 @@ result = await client.call("message.ack", {"seq": 150})
 ```json
 {
     "envelope": {
-        "message_id": "uuid-1",
         "from": "alice.agentid.pub",
         "to": "bob.agentid.pub",
-        "seq": 42,
+        "type": "text",
         "timestamp": 1234567890000,
         "encrypted": false
     },
@@ -531,7 +530,7 @@ result = await client.call("message.ack", {"seq": 150})
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `msg["envelope"]["seq"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
 
 ### 订阅
 
@@ -550,10 +549,10 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 ```json
 {
     "envelope": {
-        "message_id": "recall-uuid",
         "from": "alice.agentid.pub",
         "to": "bob.agentid.pub",
-        "seq": 43,
+        "type": "message.recalled",
+        "kind": "message.recalled",
         "timestamp": 1234567890000
     },
     "message_id": "recall-uuid",
@@ -565,11 +564,11 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 }
 ```
 
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示撤回 tombstone / 通知自身的信封，不是被撤回原消息的信封；被撤回的原消息继续通过 `message_ids` 表达。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示撤回 tombstone / 通知自身的信封，不是被撤回原消息的信封；被撤回的原消息继续通过 `message_ids` 表达。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `message_id`、`from`、`to`、`seq`、`timestamp`、`device_id`、`slot_id` 等存在的字段 |
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `from`、`to`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
 | `message_id` | string | 撤回 tombstone / 通知自身的 message_id |
 | `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
 | `from` | string | 发送方（撤回者）AID |

package/dist/auth.d.ts

@@ -302,6 +302,8 @@ export declare class AuthFlow {
      * 与 Python SDK 的 _remember_tokens 对齐。
      */
     private static _rememberTokens;
+    private _refreshFailureRequiresRelogin;
+    private _clearCachedTokens;
     /**
      * 获取缓存的 access_token（30 秒提前过期余量）。
      * 返回空字符串表示 token 不可用。

package/dist/auth.js

@@ -27,6 +27,35 @@ const _noopLogger = {
     debug: () => { },
 };
 const AUN_SDK_LANG = 'typescript';
+const SENSITIVE_RPC_LOG_KEYS = new Set([
+    'access_token',
+    'refresh_token',
+    'kite_token',
+    'token',
+]);
+function _redactRpcLogPayload(value, key = '', depth = 0) {
+    const keyLower = key.toLowerCase();
+    if (SENSITIVE_RPC_LOG_KEYS.has(keyLower) || keyLower.endsWith('_token')) {
+        const text = String(value ?? '');
+        if (!text)
+            return '';
+        const digest = crypto.createHash('sha256').update(text).digest('hex').slice(0, 12);
+        return `<redacted len=${text.length} sha256=${digest}>`;
+    }
+    if (depth >= 6)
+        return '<max-depth>';
+    if (Array.isArray(value)) {
+        return value.map((item) => _redactRpcLogPayload(item, '', depth + 1));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            out[childKey] = _redactRpcLogPayload(childValue, childKey, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
 // ── 签名验证辅助 ──────────────────────────────────────────────
 /**
  * 验证签名：支持 ECDSA P-256 (SHA256)、ECDSA P-384 (SHA384)、Ed25519。
@@ -447,11 +476,12 @@ export class AuthFlow {
         const refreshToken = String(identity.refresh_token || '');
         if (!refreshToken) {
             this._logger.error(`token refresh failed: missing refresh_token, aid=${identity.aid}`);
+            this._clearCachedTokens(identity, 'missing refresh_token');
             throw new AuthError('missing refresh_token');
         }
         this._logger.debug(`refreshCachedTokens enter: aid=${identity.aid}`);
         try {
-            const refreshed = await this._refreshAccessToken(gatewayUrl, refreshToken);
+            const refreshed = await this._refreshAccessToken(gatewayUrl, refreshToken, identity);
             AuthFlow._rememberTokens(identity, refreshed);
             await this._validateNewCert(identity, gatewayUrl);
             this._persistIdentity(identity);
@@ -459,6 +489,9 @@ export class AuthFlow {
             return identity;
         }
         catch (err) {
+            if (this._refreshFailureRequiresRelogin(err)) {
+                this._clearCachedTokens(identity, err instanceof Error ? err.message : String(err));
+            }
             this._logger.debug(`refreshCachedTokens exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
@@ -596,6 +629,9 @@ export class AuthFlow {
                 catch (exc) {
                     if (!(exc instanceof AuthError))
                         throw exc;
+                    if (this._refreshFailureRequiresRelogin(exc)) {
+                        this._clearCachedTokens(identity, exc.message);
+                    }
                     this._logger.debug(`refresh_token auth failed, will re-login: ${exc.message}`);
                 }
             }
@@ -701,12 +737,12 @@ export class AuthFlow {
                 method,
                 params,
             });
-            this._logger.debug(`short RPC request full: ${payload}`);
+            this._logger.debug(`short RPC request full: ${JSON.stringify(_redactRpcLogPayload(JSON.parse(payload)))}`);
             ws.send(payload);
             // 接收响应
             const raw = await this._wsRecv(ws);
             const message = typeof raw === 'string' ? JSON.parse(raw) : raw;
-            this._logger.debug(`short RPC response full: method=${method} ${JSON.stringify(message)}`);
+            this._logger.debug(`short RPC response full: method=${method} ${JSON.stringify(_redactRpcLogPayload(message))}`);
             if (message.error) {
                 throw mapRemoteError(message.error);
             }
@@ -715,7 +751,7 @@ export class AuthFlow {
                 throw new ValidationError(`invalid pre-auth response for ${method}`);
             }
             if (result.success === false) {
-                throw new AuthError(String(result.error || `${method} failed`));
+                throw new AuthError(String(result.error || `${method} failed`), { data: result });
             }
             return result;
         }
@@ -793,15 +829,35 @@ export class AuthFlow {
         }
     }
     /** 刷新 access_token */
-    async _refreshAccessToken(gatewayUrl, refreshToken) {
+    async _refreshAccessToken(gatewayUrl, refreshToken, identity) {
         const tStart = Date.now();
         this._logger.debug(`_refreshAccessToken enter`);
         try {
-            const result = await this._shortRpc(gatewayUrl, 'auth.refresh_token', {
+            const params = {
                 refresh_token: refreshToken,
-            });
+                sdk_lang: AUN_SDK_LANG,
+                sdk_version: AUN_SDK_VERSION,
+            };
+            if (identity) {
+                const aid = String(identity.aid ?? '').trim();
+                const deviceId = String(identity.device_id ?? '').trim();
+                const slotId = String(identity.slot_id ?? '').trim();
+                const accessToken = String(identity.access_token ?? '').trim();
+                if (aid)
+                    params.aid = aid;
+                if (deviceId)
+                    params.device_id = deviceId;
+                if (slotId)
+                    params.slot_id = slotId;
+                if (accessToken)
+                    params.access_token = accessToken;
+                if (typeof identity.access_token_expires_at === 'number') {
+                    params.access_token_expires_at = identity.access_token_expires_at;
+                }
+            }
+            const result = await this._shortRpc(gatewayUrl, 'auth.refresh_token', params);
             if (!result.success) {
-                throw new AuthError(String(result.error || 'refresh failed'));
+                throw new AuthError(String(result.error || 'refresh failed'), { data: result });
             }
             this._logger.debug(`_refreshAccessToken exit: elapsed=${Date.now() - tStart}ms`);
             return result;
@@ -1714,6 +1770,41 @@ export class AuthFlow {
             identity._pending_active_cert = activeCert;
         }
     }
+    _refreshFailureRequiresRelogin(err) {
+        if (!(err instanceof AuthError))
+            return false;
+        const data = err.data;
+        if (isJsonObject(data)) {
+            if (data.relogin_required === true)
+                return true;
+            const error = String(data.error ?? '').trim().toLowerCase();
+            return ['missing refresh_token', 'invalid_or_expired_refresh_token', 'refresh not supported'].includes(error);
+        }
+        const message = err.message.trim().toLowerCase();
+        return ['missing refresh_token', 'invalid_or_expired_refresh_token', 'refresh not supported'].includes(message);
+    }
+    _clearCachedTokens(identity, reason = '') {
+        const aid = String(identity.aid ?? '');
+        const hadToken = Boolean(identity.access_token ||
+            identity.refresh_token ||
+            identity.kite_token ||
+            identity.token ||
+            identity.access_token_expires_at);
+        if (!hadToken)
+            return;
+        identity.access_token = '';
+        identity.refresh_token = '';
+        identity.kite_token = '';
+        identity.token = '';
+        identity.access_token_expires_at = 0;
+        try {
+            this._persistIdentity(identity);
+            this._logger.warn(`cleared cached tokens after refresh failure: aid=${aid} reason=${reason}`);
+        }
+        catch (persistErr) {
+            this._logger.warn(`failed to persist token cleanup: aid=${aid} err=${persistErr instanceof Error ? persistErr.message : String(persistErr)}`);
+        }
+    }
     /**
      * 获取缓存的 access_token（30 秒提前过期余量）。
      * 返回空字符串表示 token 不可用。