Skip to main content

aios_spec/
bridge.rs

1//! Android localhost bridge 线协议(IPC schema,归属 SSOT)。
2//!
3//! `execute` 请求把一个已封存的 `AuthorizedAction`(在 `aios-action` 侧序列化为
4//! canonical 字符串)连同 freshness window,以及覆盖 freshness window 与 action
5//! 字节的 HMAC-SHA256 认证标签发往设备侧 bridge;设备执行后回送结构化的
6//! [`BridgeExecuteResponse`]。
7//!
8//! 设计要点:
9//! - 认证标签 (`auth.hmac_sha256`) 放在 envelope 上,而非塞进 action JSON 内部,
10//!   使每次授权与一个**具体的 action 字节序列和有效期**绑定 —— 捕获到的旧标签
11//!   无法重放到另一个 action 或过期窗口(替换静态 bearer token 的关键改进)。
12//! - `action` 以**字符串**形式承载(即 `AuthorizedAction` 序列化后的逐字节内容),
13//!   HMAC 输入使用 length-prefixed action 字节和 freshness window。两侧都对
14//!   "收发的同一段字节"做 HMAC,规避跨语言 JSON key 排序导致的
15//!   canonicalization 漂移。
16//!
17//! 注意:本 crate 零内部依赖,这里只定义协议数据;HMAC 计算与 TCP 收发在
18//! `aios-action` 侧实现。设备(Kotlin)侧的 responder 是 Tier 2 工作,须遵循本契约。
19
20use serde::{Deserialize, Serialize};
21
22/// `execute` 请求的 `message_type` 取值。与健康检查的 `"ping"` 区分。
23pub const BRIDGE_MESSAGE_TYPE_EXECUTE: &str = "execute";
24
25/// 设备侧执行请求 envelope。
26#[derive(Debug, Clone, Serialize, Deserialize)]
27pub struct BridgeExecuteRequest {
28    /// 固定为 [`BRIDGE_MESSAGE_TYPE_EXECUTE`]。
29    pub message_type: String,
30    /// 请求签发时间(epoch milliseconds)。
31    pub issued_at_ms: i64,
32    /// 请求过期时间(epoch milliseconds)。
33    pub expires_at_ms: i64,
34    /// 认证标签,绑定到 `action` 字节。
35    pub auth: BridgeAuth,
36    /// canonical 序列化后的 `AuthorizedAction`。
37    pub action: String,
38}
39
40/// envelope 级认证标签。
41#[derive(Debug, Clone, Serialize, Deserialize)]
42pub struct BridgeAuth {
43    /// 对 freshness window 和 [`BridgeExecuteRequest::action`] 字节的 HMAC-SHA256,小写 hex。
44    pub hmac_sha256: String,
45}
46
47/// 设备侧执行状态。
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
49#[serde(rename_all = "snake_case")]
50pub enum BridgeStatus {
51    /// 设备已真实执行成功。
52    Ok,
53    /// 设备侧二次治理拒绝(token/whitelist/PII 复检未通过)。
54    Rejected,
55    /// 设备侧执行过程中出错。
56    Error,
57}
58
59/// 设备侧执行结果。`summary`/`latency_us` 仅在 `status == Ok` 时有意义。
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct BridgeExecuteResponse {
62    pub status: BridgeStatus,
63    #[serde(default)]
64    pub summary: Option<String>,
65    #[serde(default)]
66    pub latency_us: Option<u64>,
67    #[serde(default)]
68    pub error: Option<String>,
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74
75    #[test]
76    fn execute_request_roundtrips() {
77        let request = BridgeExecuteRequest {
78            message_type: BRIDGE_MESSAGE_TYPE_EXECUTE.into(),
79            issued_at_ms: 1000,
80            expires_at_ms: 2000,
81            auth: BridgeAuth {
82                hmac_sha256: "deadbeef".into(),
83            },
84            action: r#"{"intent_id":"x"}"#.into(),
85        };
86        let json = serde_json::to_string(&request).unwrap();
87        let parsed: BridgeExecuteRequest = serde_json::from_str(&json).unwrap();
88        assert_eq!(parsed.message_type, BRIDGE_MESSAGE_TYPE_EXECUTE);
89        assert_eq!(parsed.issued_at_ms, 1000);
90        assert_eq!(parsed.expires_at_ms, 2000);
91        assert_eq!(parsed.auth.hmac_sha256, "deadbeef");
92        assert_eq!(parsed.action, request.action);
93    }
94
95    #[test]
96    fn response_status_serializes_snake_case() {
97        let response = BridgeExecuteResponse {
98            status: BridgeStatus::Ok,
99            summary: Some("prefetched".into()),
100            latency_us: Some(1234),
101            error: None,
102        };
103        let json = serde_json::to_string(&response).unwrap();
104        assert!(json.contains("\"status\":\"ok\""), "got {json}");
105        let parsed: BridgeExecuteResponse = serde_json::from_str(&json).unwrap();
106        assert_eq!(parsed.status, BridgeStatus::Ok);
107        assert_eq!(parsed.latency_us, Some(1234));
108    }
109
110    #[test]
111    fn response_tolerates_missing_optional_fields() {
112        let parsed: BridgeExecuteResponse =
113            serde_json::from_str(r#"{"status":"rejected"}"#).unwrap();
114        assert_eq!(parsed.status, BridgeStatus::Rejected);
115        assert_eq!(parsed.summary, None);
116        assert_eq!(parsed.error, None);
117    }
118}