@tbox.cn/app-contracts 0.10.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/identity.d.ts
CHANGED
|
@@ -2,18 +2,20 @@
|
|
|
2
2
|
* 统一用户授权鉴权契约(006):身份 / Token / 换发 / 运行上下文。
|
|
3
3
|
* TIER0 types-only(+ 错误码常量),双端共享:服务端签发/校验、客户端消费。
|
|
4
4
|
*
|
|
5
|
-
* 设计要点(006 §2 / D1-D4
|
|
5
|
+
* 设计要点(006 §2 / D1-D4 + 2026-09 四源修订):
|
|
6
6
|
* - 自有 JWT 唯一形态;外部一律内置换发(三态收敛),原始 token 嵌 `external` claim。
|
|
7
|
-
* - userId
|
|
8
|
-
*
|
|
7
|
+
* - userId 命名:local/guest 由平台生成,强制前缀 local_/guest_(guest = 服务端随机访客身份,
|
|
8
|
+
* `guest_<32hex>`);**external 原样保留(外部系统自管命名空间,不加前缀/不归一化)**;
|
|
9
|
+
* anonymous 服务端生成、不签发 JWT。
|
|
10
|
+
* - 身份唯一服务端决定:客户端不产生身份(会话 β 前提)。
|
|
9
11
|
* - RequestContext 单一运行上下文(identity + conversationId + credentials + attributes),
|
|
10
12
|
* 显式通道读取(0.11.0 上下文统一化:handle 第四参 / 工具 execute 第二参读取器——ctx.auth 已拆除)。
|
|
11
13
|
*/
|
|
12
|
-
export type UserIdSource = 'local' | 'external' | '
|
|
14
|
+
export type UserIdSource = 'local' | 'external' | 'guest' | 'anonymous';
|
|
13
15
|
export interface Identity {
|
|
14
|
-
/** 全局唯一 userId
|
|
16
|
+
/** 全局唯一 userId(local_/guest_ 强制前缀;external 原样;anonymous 不签发) */
|
|
15
17
|
userId: string;
|
|
16
|
-
/** 来源(主区分;local/external/
|
|
18
|
+
/** 来源(主区分;local/external/guest 都可能带名字与头像) */
|
|
17
19
|
source: UserIdSource;
|
|
18
20
|
displayName?: string;
|
|
19
21
|
avatar?: string;
|
|
@@ -59,30 +61,44 @@ export interface RequestContext {
|
|
|
59
61
|
attributes?: Record<string, unknown>;
|
|
60
62
|
}
|
|
61
63
|
/**
|
|
62
|
-
*
|
|
64
|
+
* 换发请求(0.11.0 对象化,append-only 永久扩展点):
|
|
65
|
+
* - 新字段恒可选;实现方宽容未知字段(禁全量校验,只取所需键);
|
|
66
|
+
* - previousIdentity:previousToken 已验签的上一身份(续签轨;code 轨透传——mock 换码器
|
|
67
|
+
* 复用身份,真实厂商忽略,authCode 即真相)。
|
|
68
|
+
*/
|
|
69
|
+
export interface ExchangeRequest {
|
|
70
|
+
/** 授权码(必填;browser 轨不经过本接口) */
|
|
71
|
+
code: string;
|
|
72
|
+
/** 换码路由键(缺省 'alipay';registry 按 provider 键 + scoped 谓词路由) */
|
|
73
|
+
platform?: string;
|
|
74
|
+
/** 域中性业务上下文槽位(对齐 HelloEvent.context 先例:消费方自定键,TIER0 零领域语义) */
|
|
75
|
+
context?: Readonly<Record<string, unknown>>;
|
|
76
|
+
/** 已验签的上一身份(续签透传;实现方可选消费) */
|
|
77
|
+
previousIdentity?: Identity;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* 换码器接口:ExchangeRequest → ExchangeResult(identity + 可选外部凭据)。
|
|
63
81
|
* 本地实现(支付宝/微信)与外部实现(ExternalIdentityExchange)均实现本接口。
|
|
64
82
|
*/
|
|
65
83
|
export interface IdentityExchange {
|
|
66
84
|
readonly provider: string;
|
|
67
|
-
/**
|
|
68
|
-
|
|
69
|
-
* @param context 域中性业务上下文槽位(对齐 HelloEvent.context 先例:消费方自定键,TIER0 零领域语义;
|
|
70
|
-
* 路由层保证 plain object 且体积约束,实现方可宽松读取所需键)
|
|
71
|
-
*/
|
|
72
|
-
exchangeByCode(code: string, platform?: string, context?: Readonly<Record<string, unknown>>): Promise<ExchangeResult>;
|
|
85
|
+
/** 换发(对象化请求;调用方保证 code 必填、context 归一化 plain object) */
|
|
86
|
+
exchangeByCode(request: ExchangeRequest): Promise<ExchangeResult>;
|
|
73
87
|
}
|
|
74
88
|
export declare const AUTH_ERROR_CODES: {
|
|
75
89
|
/** 401:凭证缺失/非法 */
|
|
76
90
|
readonly UNAUTHORIZED: "AUTH_UNAUTHORIZED";
|
|
77
91
|
/** 401:token 过期(客户端应重登录后重试) */
|
|
78
92
|
readonly TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED";
|
|
79
|
-
/** 403
|
|
93
|
+
/** 403:身份不足以执行(匿名写操作等) */
|
|
80
94
|
readonly FORBIDDEN: "AUTH_FORBIDDEN";
|
|
81
|
-
/**
|
|
82
|
-
readonly
|
|
95
|
+
/** 400:登录请求缺 method 判别('code'|'browser') */
|
|
96
|
+
readonly METHOD_REQUIRED: "AUTH_METHOD_REQUIRED";
|
|
97
|
+
/** 403:browser 轴被禁(off 档 / prod mock 档 / auto 无可用形态) */
|
|
98
|
+
readonly BROWSER_LOGIN_DISABLED: "AUTH_BROWSER_LOGIN_DISABLED";
|
|
83
99
|
/** 502:外部 provider 错误 */
|
|
84
100
|
readonly EXTERNAL_ERROR: "AUTH_EXTERNAL_ERROR";
|
|
85
|
-
/** 503:密钥链缺失(prod fail-fast
|
|
101
|
+
/** 503:密钥链缺失(prod fail-fast)/ 登录槽配置缺失(显式 mock 档无物料) */
|
|
86
102
|
readonly MISSING_SECRET: "AUTH_MISSING_SECRET";
|
|
87
103
|
};
|
|
88
104
|
export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[keyof typeof AUTH_ERROR_CODES];
|
package/dist/protocol.d.ts
CHANGED
|
@@ -10,6 +10,13 @@ type RunScopedErrorEvent = RunErrorEvent & {
|
|
|
10
10
|
threadId?: string;
|
|
11
11
|
runId?: string;
|
|
12
12
|
};
|
|
13
|
+
/**
|
|
14
|
+
* 会话未建立严格拒绝(会话 β):连接无当前会话时收到 RUN → 本错误终态(不自动修复、
|
|
15
|
+
* 不静默建会话——协议不变量「无会话即拒」,防不落库审计绕过)。
|
|
16
|
+
*/
|
|
17
|
+
type RunNotEstablishedErrorEvent = RunErrorEvent & {
|
|
18
|
+
code: 'CONVERSATION_NOT_ESTABLISHED';
|
|
19
|
+
};
|
|
13
20
|
/**
|
|
14
21
|
* 工具执行失败终态(2026-09-03 tool-error 断链修复):
|
|
15
22
|
* - isError: true 标记该 RESULT 为错误终态(模型路径工具 execute 抛错 / 模块工具
|
|
@@ -23,7 +30,7 @@ type ToolCallResultErrorEvent = ToolCallResultEvent & {
|
|
|
23
30
|
errorMessage?: string;
|
|
24
31
|
};
|
|
25
32
|
/** 所有服务端 → 客户端事件 */
|
|
26
|
-
export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultErrorEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent
|
|
33
|
+
export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | RunNotEstablishedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultErrorEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent
|
|
27
34
|
/** HELLO 鉴权成功应答(011 F4) */
|
|
28
35
|
| HelloAckEvent
|
|
29
36
|
/** 传输层业务保活(双向对称;连接级事件,无身份/顺序语义) */
|
|
@@ -35,15 +42,14 @@ export interface SendMessageMediaItem {
|
|
|
35
42
|
mimeType?: string;
|
|
36
43
|
}
|
|
37
44
|
/**
|
|
38
|
-
* 客户端 →
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
* fallback 键(连接级身份 + 本轮 run)处理,不落库。
|
|
45
|
+
* 客户端 → 服务端会话键(会话 β 改造):conversationId 从客户端协议面退役——
|
|
46
|
+
* 会话由服务端建立(NEW/RESUME)并绑定为连接当前会话,运行/持久化/取消恒取连接当前会话。
|
|
47
|
+
* 历史字段保留一个发布周期(@deprecated ignore 化):服务端一律忽略,客户端不提供即不可伪造。
|
|
42
48
|
*/
|
|
43
49
|
export interface SendMessageEvent {
|
|
44
50
|
type: 'SEND_MESSAGE';
|
|
45
51
|
content: string;
|
|
46
|
-
/** 会话
|
|
52
|
+
/** @deprecated 会话 β:服务端恒取连接当前会话,本字段忽略(一个发布周期后删除) */
|
|
47
53
|
conversationId?: string;
|
|
48
54
|
/** 用户上传的媒体文件(仅携带 fileId,SDK 直传后的引用) */
|
|
49
55
|
mediaItems?: SendMessageMediaItem[];
|
|
@@ -52,11 +58,24 @@ export interface SendMessageEvent {
|
|
|
52
58
|
}
|
|
53
59
|
export interface CancelRunEvent {
|
|
54
60
|
type: 'CANCEL_RUN';
|
|
55
|
-
/** 会话
|
|
61
|
+
/** @deprecated 会话 β:服务端恒取连接当前会话,本字段忽略(一个发布周期后删除) */
|
|
56
62
|
conversationId?: string;
|
|
57
63
|
/** 当前 runId,用于避免迟到的取消事件误取消同会话的下一轮回答 */
|
|
58
64
|
runId?: string;
|
|
59
65
|
}
|
|
66
|
+
/**
|
|
67
|
+
* 会话建立指令(会话 β:「不提供即不可伪造」——conversationId 从客户端协议面整体退役):
|
|
68
|
+
* - NEW_CONVERSATION:bootstrap 恒发。服务端建新会话(防御性取消在飞 run)并绑定为
|
|
69
|
+
* 连接当前会话;失败走 notice 通道。无 ACK——串行队列已保序(后续 RUN 恒晚于本事件处理)。
|
|
70
|
+
* - RESUME_CONVERSATION:同页重连续接。服务端 getOrCreate(连接身份) 绑定连接当前会话。
|
|
71
|
+
* - 裸 RUN 无会话 → RUN_ERROR{code:'CONVERSATION_NOT_ESTABLISHED'} 严格拒绝(不自动修复)。
|
|
72
|
+
*/
|
|
73
|
+
export interface NewConversationEvent {
|
|
74
|
+
type: 'NEW_CONVERSATION';
|
|
75
|
+
}
|
|
76
|
+
export interface ResumeConversationEvent {
|
|
77
|
+
type: 'RESUME_CONVERSATION';
|
|
78
|
+
}
|
|
60
79
|
/**
|
|
61
80
|
* WS 连接握手事件。客户端在 onOpen 时发送一次,**只做鉴权**(006 D6/D12):
|
|
62
81
|
* - 携带自有 JWT(消息体传输,不拼 URL,防泄漏);
|
|
@@ -147,7 +166,7 @@ export type UiClientAction = {
|
|
|
147
166
|
};
|
|
148
167
|
export interface UiActionEvent {
|
|
149
168
|
type: 'UI_ACTION';
|
|
150
|
-
/** 会话
|
|
169
|
+
/** @deprecated 会话 β:服务端恒取连接当前会话,本字段忽略(一个发布周期后删除) */
|
|
151
170
|
conversationId?: string;
|
|
152
171
|
/** 卡片实例 id(协议字段名沿用历史 surfaceId) */
|
|
153
172
|
surfaceId: string;
|
|
@@ -155,7 +174,7 @@ export interface UiActionEvent {
|
|
|
155
174
|
/** submitForm 时携带的表单数据(由 client React 卡片构造) */
|
|
156
175
|
formData?: Record<string, unknown>;
|
|
157
176
|
}
|
|
158
|
-
export type ClientEvent = SendMessageEvent | CancelRunEvent | UiActionEvent | HelloEvent | PingEvent | PongEvent;
|
|
177
|
+
export type ClientEvent = SendMessageEvent | CancelRunEvent | UiActionEvent | NewConversationEvent | ResumeConversationEvent | HelloEvent | PingEvent | PongEvent;
|
|
159
178
|
/** 保活漏检上限:timeout = intervalMs × KEEPALIVE_MISS_LIMIT(对齐 nextAuthFailState 的 max=3 惯例) */
|
|
160
179
|
export declare const KEEPALIVE_MISS_LIMIT = 3;
|
|
161
180
|
export type KeepaliveAction = 'none' | 'ping' | 'dead';
|
package/dist/runtime.js
CHANGED
|
@@ -12,13 +12,15 @@ var AUTH_ERROR_CODES = {
|
|
|
12
12
|
UNAUTHORIZED: "AUTH_UNAUTHORIZED",
|
|
13
13
|
/** 401:token 过期(客户端应重登录后重试) */
|
|
14
14
|
TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED",
|
|
15
|
-
/** 403
|
|
15
|
+
/** 403:身份不足以执行(匿名写操作等) */
|
|
16
16
|
FORBIDDEN: "AUTH_FORBIDDEN",
|
|
17
|
-
/**
|
|
18
|
-
|
|
17
|
+
/** 400:登录请求缺 method 判别('code'|'browser') */
|
|
18
|
+
METHOD_REQUIRED: "AUTH_METHOD_REQUIRED",
|
|
19
|
+
/** 403:browser 轴被禁(off 档 / prod mock 档 / auto 无可用形态) */
|
|
20
|
+
BROWSER_LOGIN_DISABLED: "AUTH_BROWSER_LOGIN_DISABLED",
|
|
19
21
|
/** 502:外部 provider 错误 */
|
|
20
22
|
EXTERNAL_ERROR: "AUTH_EXTERNAL_ERROR",
|
|
21
|
-
/** 503:密钥链缺失(prod fail-fast
|
|
23
|
+
/** 503:密钥链缺失(prod fail-fast)/ 登录槽配置缺失(显式 mock 档无物料) */
|
|
22
24
|
MISSING_SECRET: "AUTH_MISSING_SECRET"
|
|
23
25
|
};
|
|
24
26
|
function authCodeToStatus(code) {
|
|
@@ -27,8 +29,10 @@ function authCodeToStatus(code) {
|
|
|
27
29
|
case AUTH_ERROR_CODES.TOKEN_EXPIRED:
|
|
28
30
|
return 401;
|
|
29
31
|
case AUTH_ERROR_CODES.FORBIDDEN:
|
|
30
|
-
case AUTH_ERROR_CODES.
|
|
32
|
+
case AUTH_ERROR_CODES.BROWSER_LOGIN_DISABLED:
|
|
31
33
|
return 403;
|
|
34
|
+
case AUTH_ERROR_CODES.METHOD_REQUIRED:
|
|
35
|
+
return 400;
|
|
32
36
|
case AUTH_ERROR_CODES.EXTERNAL_ERROR:
|
|
33
37
|
return 502;
|
|
34
38
|
case AUTH_ERROR_CODES.MISSING_SECRET:
|
package/package.json
CHANGED