Skip to main content

acosmi/agent_runs/
byok.rs

1//! CrabCode 远控 BYO 模型密钥管理面(契约 §18.2)。端口自 `agent-runs/byok.ts`。
2//!
3//! 端点: /api/v4/crabcode/byok-credentials(wire snake_case; remote-control 平面)。
4//! 守卫: AuthOrDesktopScope("remote_control")。
5//!
6//! 安全红线(契约 §6 附录 A):
7//!   - 任何端点不回 plaintext / ciphertext; 列表一律 masked 视图;
8//!   - credentialRef 是唯一可持有引用 —— 传给 `create_remote_run({ byok_credential_ref })`(仅 runner='cloud');
9//!   - SDK 不缓存、不打印明文。
10
11use crate::core::client::Client;
12use crate::shared::{ApiResponse, Result};
13use serde::Deserialize;
14use serde_json::json;
15use tokio_util::sync::CancellationToken;
16
17/// 允许的第三方提供商(与网关 byokAllowedProviders 对齐)。常量集合(open union)。
18pub const BYOK_PROVIDER_ANTHROPIC: &str = "anthropic";
19pub const BYOK_PROVIDER_OPENAI: &str = "openai";
20pub const BYOK_PROVIDER_DEEPSEEK: &str = "deepseek";
21pub const BYOK_PROVIDER_DASHSCOPE: &str = "dashscope";
22pub const BYOK_PROVIDER_ZHIPU: &str = "zhipu";
23pub const BYOK_PROVIDER_VOLCENGINE: &str = "volcengine";
24pub const BYOK_PROVIDER_CUSTOM: &str = "custom";
25
26/// BYOK 密钥状态。
27pub const BYOK_STATUS_ACTIVE: &str = "active";
28pub const BYOK_STATUS_REVOKED: &str = "revoked";
29
30/// BYOK 密钥 masked 视图 —— 永不含明文/密文。对应 TS `ByokCredential`。
31#[derive(Debug, Clone, Default)]
32pub struct ByokCredential {
33    pub credential_ref: String,
34    pub provider: String,
35    pub name: Option<String>,
36    /// 仅 provider='custom' 时存在(https:// 起始)。
37    pub base_url: Option<String>,
38    /// 明文指纹(轮换后变化)。
39    pub fingerprint: Option<String>,
40    pub status: String,
41    pub created_at: Option<String>,
42    pub last_used_at: Option<String>,
43}
44
45/// `create()` 请求。明文一次性提交,服务端加密落库后即弃。对应 TS `ByokCreateRequest`。
46#[derive(Debug, Clone, Default)]
47pub struct ByokCreateRequest {
48    pub provider: String,
49    /// API key 明文; ≤4KB,不得含换行。
50    pub plaintext: String,
51    /// 显示名; ≤100 字符。
52    pub name: Option<String>,
53    /// 仅 provider='custom' 必填(必须 https://)。
54    pub base_url: Option<String>,
55}
56
57#[derive(Debug, Clone, Default, Deserialize)]
58struct WireByokCredential {
59    #[serde(default)]
60    credential_ref: Option<String>,
61    #[serde(default)]
62    provider: Option<String>,
63    #[serde(default)]
64    name: Option<String>,
65    #[serde(default)]
66    base_url: Option<String>,
67    #[serde(default)]
68    fingerprint: Option<String>,
69    #[serde(default)]
70    status: Option<String>,
71    #[serde(default)]
72    created_at: Option<String>,
73    #[serde(default)]
74    last_used_at: Option<String>,
75}
76
77#[derive(Debug, Clone, Default, Deserialize)]
78struct WireByokList {
79    #[serde(default)]
80    items: Option<Vec<WireByokCredential>>,
81}
82
83fn non_empty(s: Option<String>) -> Option<String> {
84    s.filter(|v| !v.is_empty())
85}
86
87fn from_wire_byok(v: WireByokCredential) -> ByokCredential {
88    ByokCredential {
89        credential_ref: v.credential_ref.unwrap_or_default(),
90        provider: v.provider.unwrap_or_default(),
91        name: non_empty(v.name),
92        base_url: non_empty(v.base_url),
93        fingerprint: non_empty(v.fingerprint),
94        status: v.status.unwrap_or_default(),
95        created_at: non_empty(v.created_at),
96        last_used_at: non_empty(v.last_used_at),
97    }
98}
99
100/// CrabCode 远控 BYO 模型密钥管理面子客户端。对应 TS `CrabCodeByokClient`。
101///
102/// 经 [`Client::crabcode_byok`] getter 获取(无状态,持 [`Client`] clone)。
103pub struct CrabCodeByokClient {
104    client: Client,
105}
106
107impl CrabCodeByokClient {
108    pub(crate) fn new(client: Client) -> Self {
109        Self { client }
110    }
111
112    /// 列出调用者自己的密钥(masked; 新→旧,服务端上限 100 条)。对应 TS `list`。
113    pub async fn list(&self, signal: Option<CancellationToken>) -> Result<Vec<ByokCredential>> {
114        let env: ApiResponse<WireByokList> = self
115            .client
116            .agent_runs_request_api("GET", "/crabcode/byok-credentials", None, signal, true)
117            .await?;
118        Ok(env
119            .data
120            .items
121            .unwrap_or_default()
122            .into_iter()
123            .map(from_wire_byok)
124            .collect())
125    }
126
127    /// 创建密钥 —— 明文一次性提交,返回 masked 视图。对应 TS `create`。
128    pub async fn create(
129        &self,
130        req: &ByokCreateRequest,
131        signal: Option<CancellationToken>,
132    ) -> Result<ByokCredential> {
133        let body = json!({
134            "provider": req.provider,
135            "name": req.name,
136            "base_url": req.base_url,
137            "plaintext": req.plaintext,
138        })
139        .to_string();
140        let env: ApiResponse<WireByokCredential> = self
141            .client
142            .agent_runs_request_api(
143                "POST",
144                "/crabcode/byok-credentials",
145                Some(&body),
146                signal,
147                false,
148            )
149            .await?;
150        Ok(from_wire_byok(env.data))
151    }
152
153    /// 轮换密钥明文 —— credentialRef 不变,fingerprint 更新。对应 TS `rotate`。
154    pub async fn rotate(
155        &self,
156        credential_ref: &str,
157        new_plaintext: &str,
158        signal: Option<CancellationToken>,
159    ) -> Result<ByokCredential> {
160        let path = format!(
161            "/crabcode/byok-credentials/{}/rotate",
162            crate::billing::entitlements::urlencoding(credential_ref)
163        );
164        let body = json!({ "new_plaintext": new_plaintext }).to_string();
165        let env: ApiResponse<WireByokCredential> = self
166            .client
167            .agent_runs_request_api("POST", &path, Some(&body), signal, false)
168            .await?;
169        Ok(from_wire_byok(env.data))
170    }
171
172    /// 吊销密钥(软状态 + 服务端抹密文,不可恢复; 幂等)。对应 TS `revoke`。
173    pub async fn revoke(
174        &self,
175        credential_ref: &str,
176        signal: Option<CancellationToken>,
177    ) -> Result<ByokCredential> {
178        let path = format!(
179            "/crabcode/byok-credentials/{}/revoke",
180            crate::billing::entitlements::urlencoding(credential_ref)
181        );
182        let env: ApiResponse<WireByokCredential> = self
183            .client
184            .agent_runs_request_api("POST", &path, Some("{}"), signal, false)
185            .await?;
186        Ok(from_wire_byok(env.data))
187    }
188}
189
190impl Client {
191    /// CrabCode 远控 BYO 模型密钥管理面(契约 §18.2)。对应 TS `client.crabcodeByok` getter。
192    pub fn crabcode_byok(&self) -> CrabCodeByokClient {
193        CrabCodeByokClient::new(self.clone())
194    }
195}