pub fn generate_agent_key_material() -> Result<GeneratedAgentKeyMaterial> { // 生成 agent 身份密钥对：私钥本地保管，公钥上报服务端    let mut seed_material = [0u8; AGENT_IDENTITY_KEY_SEED_BYTES]; // 先准备 64 字节随机种子（常量=64），比 Ed25519 需要的 32 字节多一倍    OsRng.try_fill_bytes(&mut seed_material) // 用操作系统 CSPRNG 填充；身份密钥绝不允许降级到弱随机源        .context("failed to generate agent identity private key seed material")?; // 失败直接报错，错误信息写明意图便于排查    let mut digest = Sha512::new(); // SHA-512 输出 64 字节：一次派生同时喂饱 Ed25519 种子和 Curve25519 密钥    digest.update(AGENT_IDENTITY_KEY_DERIVATION_CONTEXT); // 混入固定上下文串 "codex-agent-identity-ed25519-v1"——将来换算法/版本时改串即可隔离旧派生结果    digest.update(seed_material); // 再混入随机种子，摘要即确定性派生结果    let digest = digest.finalize(); // 完成哈希计算    let mut secret_key_bytes = [0u8; 32]; // Ed25519 只取前 32 字节当签名种子    secret_key_bytes.copy_from_slice(&digest[..32]); // 截取摘要前半段作为私钥种子    let signing_key = SigningKey::from_bytes(&secret_key_bytes); // 从 32 字节种子构造 Ed25519 私钥（公钥由它确定性推出）    let private_key_pkcs8 = signing_key.to_pkcs8_der() // PKCS#8 DER：标准密钥容器，任何语言/库都能解析        .context("failed to encode agent identity private key as PKCS#8")?; // 编码失败视为致命错误    Ok(GeneratedAgentKeyMaterial { // 返回两种形态：base64 私钥（落盘）+ SSH 公钥（上报服务端）        private_key_pkcs8_base64: BASE64_STANDARD.encode(private_key.as_bytes()), // 私钥 base64 化后存进 auth record，随账号持久化复用        public_key_ssh: encode_ssh_ed25519_public_key(&signing_key.verifying_key()) // 公钥编码成 ssh-ed25519 格式——服务端按 SSH key 惯例存储和展示    })}

pub async fn register_agent_identity( // 把"这个 agent 运行时"注册到 OpenAI 身份服务，返回可复用的 runtime_id    client: &HttpClient, // 复用调用方构造的 HTTP client（已带代理/CA 策略）    agent_identity_authapi_base_url: &str, // auth API base URL：prod=auth.openai.com / staging=auth.api.openai.org    access_token: &str, // ChatGPT 账号的 access token——注册动作本身要证明"这个账号授权了这个 agent"    is_fedramp_account: bool, // FedRAMP 合规账号走独立路由，需要显式标记    key_material: &GeneratedAgentKeyMaterial, // 刚生成的密钥对：公钥上报、私钥留下    abom: AgentBillOfMaterials, // "物料清单"：agent 版本 + harness id + 运行位置——服务端审计用    capabilities: Vec<String>, // 能力声明（如 responsesapi）——服务端据此决定给这个 agent 开哪些权限) -> Result<String> {    let url = agent_registration_url(agent_identity_authapi_base_url); // 拼出 /v1/agent/register 端点    let request = RegisterAgentRequest { // 请求体：ABOM + SSH 公钥 + 能力列表，ttl=None 表示长期有效        abom, // 物料清单原样上报（build_abom 从 CARGO_PKG_VERSION + SessionSource 生成）        agent_public_key: key_material.public_key_ssh.clone(), // 只上报公钥——私钥永远不出本地        capabilities, // 能力声明随注册固化，后续请求不再重复携带        ttl: None, // 不传 TTL：agent 身份是长效的，会过期的是 task 不是 identity    };    let mut request_builder = client.post(&url) // POST 注册端点        .bearer_auth(access_token) // Bearer token 证明账号授权——没有有效登录态根本走不到这一步        .json(&request) // JSON 序列化请求体        .timeout(AGENT_REGISTRATION_TIMEOUT); // 15s 超时（常量）——注册在启动路径上，不能无限等    if is_fedramp_account { // FedRAMP 合规账号：加专用头走合规路由        request_builder = request_builder.header("X-OpenAI-Fedramp", "true"); // 服务端凭这个头把请求切到 FedRAMP 集群    }    let response = request_builder.send().await // 发出请求        .with_context(|| format!("failed to send agent identity registration request to {url}"))? // 网络层失败带 URL 上下文，方便定位是哪个端点挂了        .error_for_status() // 非 2xx 直接转错误——注册失败没有静默降级空间        .with_context(|| format!("agent identity registration failed for {url}"))?; // 业务层失败同样带 URL    Ok(response.agent_runtime_id) // 成功：返回服务端分配的 runtime_id，后续所有签名都锚定它}

pub fn decrypt_task_id_response( // 解密服务端返回的加密 task_id——只有持有私钥的 agent 自己能解开    key: AgentIdentityKey<'_>, // 密钥材料：runtime_id + PKCS#8 私钥（借用，不拷贝）    encrypted_task_id: &str, // base64 密文：Curve25519 sealed box 格式) -> Result<String> {    let signing_key = signing_key_from_private_key_pkcs8_base64(key.private_key_pkcs8_base64)?; // 从 PKCS#8 DER 还原 Ed25519 私钥（base64 → DER → SigningKey）    let ciphertext = BASE64_STANDARD.decode(encrypted_task_id) // base64 解码出密文        .context("encrypted task id is not valid base64")?; // 不是合法 base64 直接报错，不猜    let plaintext = curve25519_secret_key_from_signing_key(&signing_key) // 从 Ed25519 私钥派生 Curve25519 解密密钥——同一把种子，两种用途（第 2 节）        .unseal(&ciphertext) // sealed box 开盒：失败说明密文根本不是发给这把密钥的        .map_err(|_| anyhow::anyhow!("failed to decrypt encrypted task id"))?; // 解密失败统一成业务错误，不泄露底层细节    String::from_utf8(plaintext).context("decrypted task id is not valid UTF-8") // 明文必须是合法 UTF-8——task_id 是字符串标识符}

pub fn authorization_header_for_agent_task( // 为单个请求生成 Authorization 头：每次现签，不缓存任何 token    key: AgentIdentityKey<'_>, // runtime_id + 私钥（借用视图）    task_id: &str, // 本次运行的 task id——把"哪个 agent 的哪次运行"绑进签名) -> Result<String> {    let timestamp = Utc::now().to_rfc3339_opts(SecondsFormat::Secs, true); // RFC3339 秒级时间戳：参与签名，服务端用它做重放窗口校验    let envelope = AgentAssertionEnvelope { // 断言信封：四个字段全部随请求传输，其中三个被签名覆盖        agent_runtime_id: key.agent_runtime_id.to_string(), // 哪个 agent（长效身份）        task_id: task_id.to_string(), // 哪次运行（一次性任务）——身份和任务同时绑定进签名        timestamp: timestamp.clone(), // 何时发起——防重放的关键字段，服务端可拒绝窗口外的旧断言        signature: sign_agent_assertion_payload(key, task_id, &timestamp)?, // Ed25519 签 "{runtime_id}:{task_id}:{timestamp}"（第 521-529 行）    };    let serialized_assertion = serialize_agent_assertion(&envelope)?; // JSON 序列化（BTreeMap 保证字段序稳定）→ base64url 无填充编码    Ok(format!("AgentAssertion {serialized_assertion}")) // 自定义 scheme "AgentAssertion" + 断言——服务端按此解析并验签}

impl AuthProvider for AgentIdentityAuthProvider { // Agent 身份走独立的 AuthProvider——与 ChatGPT Bearer token 完全平行的另一条认证路径    fn add_auth_headers(&self, headers: &mut HeaderMap) { // 每次请求发出前调用，往 HeaderMap 里塞认证头        let record = self.auth.record(); // 取出持久化的身份记录（runtime_id + 私钥 + 账号信息）        let header_value = authorization_header_for_agent_task( // 现场生成 AgentAssertion——每个请求一个新鲜时间戳+签名            AgentIdentityKey { // 借用式密钥视图：不拷贝私钥字符串，零额外分配                agent_runtime_id: &record.agent_runtime_id, // 长效身份 id                private_key_pkcs8_base64: &record.agent_private_key, // PKCS#8 私钥（base64）            },            self.auth.run_task_id(), // 本次运行的 task id——构造时保证非空，这里直接取        ).map_err(std::io::Error::other); // 签名失败转 io error；注意下面会静默跳过而不是炸掉整个请求        if let Ok(header_value) = header_value && let Ok(header) = HeaderValue::from_str(&header_value) { // 双保险：生成成功且是合法 HTTP 头值才写入            let _ = headers.insert(http::header::AUTHORIZATION, header); // Authorization: AgentAssertion <base64url>——核心认证头        }        if let Ok(header) = HeaderValue::from_str(self.auth.account_id()) { // ChatGPT-Account-ID：告诉服务端这笔请求归属哪个账号（计费/配额锚点）            let _ = headers.insert("ChatGPT-Account-ID", header); // 身份断言之外再给一个粗粒度账号标识，方便服务端快速路由        }        if self.auth.is_fedramp_account() { // FedRAMP 合规账号：每个请求都带标记，持续走合规集群            let _ = headers.insert("X-OpenAI-Fedramp", HeaderValue::from_static("true")); // 静态值用 from_static——避免每次请求做字符串分配        }    }}

/// Returns whether workload identity was selected through process configuration. // 文档注释：workload identity 是否被进程级配置选中pub fn is_workload_identity_selected() -> bool { // 登录管理器启动时问这一句——决定走哪条凭证路径（fail loud，不静默回退）    ProcessEnvironment::read().has_marker() // 读环境变量并检查"标记位"是否存在}impl ProcessEnvironment { // 进程环境快照：三个变量一次性读进来，避免多次 env 读取之间被外部修改导致不一致    fn read() -> Self { // 从 std::env 抓取三个 workload identity 相关变量（OsString 容忍非 UTF-8 值）        Self {            federation_rule_id: std::env::var_os(OPENAI_FEDERATION_RULE_ID_ENV_VAR), // OPENAI_FEDERATION_RULE_ID：联邦规则 id——服务端据此匹配信任策略            identity_token_file: std::env::var_os(OPENAI_IDENTITY_TOKEN_FILE_ENV_VAR), // OPENAI_IDENTITY_TOKEN_FILE：JWT assertion 文件路径（由外部身份系统写入/轮换）            workload_identity_context: std::env::var_os(OPENAI_WORKLOAD_IDENTITY_CONTEXT_ENV_VAR), // 可选上下文串：附加审计信息，非必填        }    }    fn has_marker(&self) -> bool { // "任一核心标记存在"即选中——部分配置会在后续校验阶段 fail loud（第 131-168 行 resolve_config）        self.federation_rule_id.is_some() || self.identity_token_file.is_some() // 两个核心变量有一个就算启用；只设 context 不算数，防止误触发    }}

/// Reopens the assertion file for each exchange so its owner can rotate the credential. // 文档注释：每次交换都重新打开文件——让外部系统能随时轮换凭证而无需重启 Codexpub(crate) async fn read_assertion(path: &Path) -> Result<String, WorkloadIdentityError> { // 读取 JWT assertion 文件，带大小和内容双重校验    let file = tokio::fs::File::open(path).await.map_err(|source| { // 异步打开；失败时把路径和原始错误一起包进类型化错误        WorkloadIdentityError::AssertionFile { path: path.to_path_buf(), source: source.into() } // 调用方可以区分"文件不存在/不可读"和其他 IO 问题，给出准确提示    })?;    let mut bytes = Vec::new(); // 缓冲读取的字节    file.take(MAX_ASSERTION_BYTES + 1) // take(16KB+1)：多读 1 字节用来探测超限——比读完整个文件再判断省内存        .read_to_end(&mut bytes).await.map_err(|source| WorkloadIdentityError::AssertionFile { path: path.to_path_buf(), source: source.into() })?; // 读到上限即停；IO 错误同样类型化包装    if bytes.len() as u64 > MAX_ASSERTION_BYTES { // 超过 16KB 直接拒绝——assertion 是 JWT，正常远小于此，超限说明文件被污染或配错路径        return Err(WorkloadIdentityError::AssertionTooLarge); // 专用错误变体：只报"太大"，不泄露文件内容    }    let assertion = String::from_utf8(bytes).map_err(|_| WorkloadIdentityError::InvalidAssertion)?; // 必须是合法 UTF-8——JWT 是纯文本格式    let assertion = assertion.trim(); // 去掉首尾空白（文件末尾换行很常见，POST 前必须清掉）    if assertion.is_empty() || assertion.as_bytes().contains(&0) { // 空内容或含 NUL 字节都拒绝——NUL 说明混进了二进制垃圾        return Err(WorkloadIdentityError::InvalidAssertion); // 统一归为 InvalidAssertion，不区分细节避免给攻击者探测面    }    Ok(assertion.to_string()) // 校验通过：返回干净的 assertion 字符串交给交换流程}

impl CachedToken { // 缓存的 token + 两个时间锚点：何时必须刷新、何时彻底过期    fn new(token: WorkloadIdentityToken, valid_from: Instant) -> Self { // 用"生效时刻"为基准计算两个时间点（单调时钟，不受系统时间回拨影响）        let lifetime = Duration::from_secs(token.expires_in); // 服务端声明的 token 寿命（秒）        let refresh_margin = std::cmp::min(Duration::from_secs(120), lifetime / 2); // 提前刷新窗口：最多 120s，且不超过寿命的一半——短命 token 也要留足余量        Self {            expires_at: valid_from + lifetime, // 硬过期点：过了这个时刻 token 一律作废，必须重新交换            refresh_at: valid_from + lifetime.saturating_sub(refresh_margin), // 软刷新点：到点就主动换新，不等下游拒绝才被动刷新            token, // token 本体（access_token / account_id / user_id / plan_type）        }    }    fn token_at(&self, now: Instant) -> Option<WorkloadIdentityToken> { // 按"当前时刻"取可用 token——过期返回 None，未过期返回修正过 expires_in 的副本        let remaining = self.expires_at.checked_duration_since(now)?; // 已过期 → checked 运算返回 None → ? 直接短路传播（优雅失败）        if remaining.is_zero() { // 边界情况：恰好到期也视为不可用——宁早勿晚，不给竞态留缝            return None; // 强制走重新交换路径        }        let mut token = self.token.clone(); // 克隆一份再改——缓存本体保持原样，并发调用方拿到一致的快照        token.expires_in = remaining.as_secs().saturating_add(u64::from(remaining.subsec_nanos() != 0)); // expires_in 改成"剩余秒数（向上取整）"——下游按这个值做自己的过期判断不会超发        Some(token) // 返回修正后的 token：同一个凭证，但寿命字段反映真实剩余时间    }}

/// Host integration boundary for just-in-time attestation header values. // 文档注释：宿主集成边界——"要不要带 attestation、值是什么"由宿主决定，core 只留接口pub trait AttestationProvider: std::fmt::Debug + Send + Sync { // trait 要求 Debug+Send+Sync：可跨线程共享、可被日志打印（实现方负责不泄露敏感字段）    fn header_for_request(&self, context: AttestationContext) -> GenerateAttestationFuture<'_>; // 每次上游请求前调用一次，返回 future——实现方自己决定同步还是异步取 token}

impl AttestationProvider for AppServerAttestationProvider { // app-server 的实现：向"有 attestation 能力的客户端连接"要一个即时 token    fn header_for_request(&self, context: AttestationContext) -> GenerateAttestationFuture<'_> { // 返回 future，不阻塞请求准备路径        let Some(outgoing) = self.outgoing.upgrade() else { // Weak 引用升级失败说明发送器已销毁——直接放弃 attestation            return Box::pin(async { None }); // 优雅降级：没有 attestation 头，但请求照常发出（core 的契约就是 Option）        };        let thread_state_manager = self.thread_state_manager.clone(); // 克隆线程状态管理器（内部 Arc），用于查"哪个连接能出 token"        Box::pin(async move { // 异步块：真正发起 RPC + 超时控制            request_attestation_header_value_with_timeout( // 带超时的 attestation 请求封装（100ms，常量 ATTESTATION_GENERATE_TIMEOUT）                outgoing, thread_state_manager, context.thread_id, ATTESTATION_GENERATE_TIMEOUT, // 参数：发送器 / 线程状态 / 目标线程 id / 超时时长            ).await.and_then(|value| HeaderValue::from_bytes(value.as_bytes()).ok()) // 拿到字符串后转 HTTP header；非法字节序列 → None（静默降级，不炸请求）        })    }}#[derive(Serialize)] // attestation 头的 JSON 信封——成功失败都发，让服务端能区分"没有 attestation"和"attestation 失败了"struct AppServerAttestationEnvelope<'a> { // v=协议版本 s=状态码 t=token（可选）——三个字段全部单字母，头越小越好    v: u8, // 协议版本号：当前固定 1，将来信封结构变化时递增，服务端按版本解析    s: u8, // 状态码：0=成功 1=超时 2=请求失败 3=被取消 4=响应畸形——服务端据此做风控/审计（第 139-149 行）    #[serde(skip_serializing_if = "Option::is_none")] // token 为 None 时整个字段不出现——失败信封更短，也避免空串歧义    t: Option<&'a str>, // 成功时的 attestation token（opaque payload：app-server 不理解内容，服务端自己解析）}

Agent Identity bootstrap 路径（托管 agent）

▼

▼

▼

Workload Identity 交换路径（企业联邦）

▼

▼

▼