Skip to main content

maple_sdk/
client.rs

1use crate::{
2    error::{Error, Result},
3    pcr::{Pcr0Environment, Pcr0TrustPolicy},
4    session::{CredentialFence, SessionManager},
5    system_one::{SystemOneRequest, SystemOneResponse},
6    transport_v2::{
7        client::{ResponseEventStream, TransportV2Client, TransportV2Session},
8        envelope::{CacheNamespaceRoot, Credential, CredentialKind, LogicalHeader, LogicalRequest},
9        framing::ResponseEvent,
10        TransportV2Error, ROUTING_KEY_HEADER,
11    },
12    types::*,
13};
14use base64::{
15    engine::general_purpose::{STANDARD as BASE64, URL_SAFE_NO_PAD},
16    Engine,
17};
18use bytes::{Bytes, BytesMut};
19use futures::{Stream, StreamExt};
20use http::{header, HeaderMap as HttpHeaderMap, Request as HttpRequest, Response as HttpResponse};
21use p256::elliptic_curve::rand_core::{OsRng, RngCore};
22use percent_encoding::{utf8_percent_encode, NON_ALPHANUMERIC};
23use serde::{de::DeserializeOwned, Deserialize, Serialize};
24use std::{
25    fmt,
26    pin::Pin,
27    sync::{
28        atomic::{AtomicUsize, Ordering},
29        Arc, RwLock,
30    },
31    time::{SystemTime, UNIX_EPOCH},
32};
33use tokio::sync::Mutex;
34use uuid::Uuid;
35use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
36
37/// A decrypted response body returned by [`OpenSecretClient::send_inference_request`].
38///
39/// Ordinary responses contain one or more raw chunks. Server-sent event
40/// responses remain incremental and are forwarded without interpreting their
41/// payloads as JSON.
42pub type OpenSecretResponseBody = Pin<Box<dyn Stream<Item = Result<Bytes>> + Send + 'static>>;
43
44/// A caller-owned request to an allowed OpenSecret inference endpoint.
45pub type InferenceRequest = HttpRequest<Bytes>;
46
47/// A decrypted HTTP response from an OpenSecret inference endpoint.
48pub type InferenceResponse = HttpResponse<OpenSecretResponseBody>;
49
50/// A cloneable, request-local ceiling on inference HTTP sends.
51///
52/// Attestation, token refresh, and other control-plane requests do not consume
53/// this budget. A permit is reserved only immediately before an inference HTTP
54/// request is sent.
55#[derive(Clone, Debug)]
56pub struct InferenceSendBudget {
57    remaining: Arc<AtomicUsize>,
58}
59
60impl InferenceSendBudget {
61    /// Creates a budget that permits at most `max_sends` inference HTTP sends.
62    pub fn new(max_sends: usize) -> Result<Self> {
63        if max_sends == 0 {
64            return Err(Error::Configuration(
65                "Inference send budget must allow at least one send".to_string(),
66            ));
67        }
68        Ok(Self {
69            remaining: Arc::new(AtomicUsize::new(max_sends)),
70        })
71    }
72
73    /// Returns the number of inference HTTP sends still available.
74    pub fn remaining(&self) -> usize {
75        self.remaining.load(Ordering::Acquire)
76    }
77
78    /// Reserves one inference HTTP send, returning false when exhausted.
79    pub fn try_reserve_send(&self) -> bool {
80        self.remaining
81            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |remaining| {
82                remaining.checked_sub(1)
83            })
84            .is_ok()
85    }
86}
87
88struct LogicalRequestOptions<'a> {
89    include_cache_namespace: bool,
90    inference_send_budget: Option<&'a InferenceSendBudget>,
91}
92
93type TransportSessionSlot = Arc<RwLock<Option<Arc<TransportV2Session>>>>;
94type SessionRetirement = (TransportSessionSlot, Arc<TransportV2Session>);
95
96const MAX_NATIVE_OAUTH_HANDOFF_GRANT_BYTES: usize = 4 * 1024;
97
98/// One exact Transport V2 request reserved for native OAuth redemption.
99///
100/// This handle is intentionally opaque and non-Clone. Its advertised IDs are
101/// public routing values; session keys and the prepared request capability
102/// never leave the SDK.
103pub struct PreparedNativeOAuthHandoff {
104    session: Arc<TransportV2Session>,
105    prepared_request: crate::transport_v2::client::PreparedRequestId,
106    session_id: String,
107    request_id: String,
108    credential_generation: u64,
109}
110
111impl PreparedNativeOAuthHandoff {
112    pub fn session_id(&self) -> &str {
113        &self.session_id
114    }
115
116    pub fn request_id(&self) -> &str {
117        &self.request_id
118    }
119
120    /// Compares the unverified routing hints carried by a handoff grant with
121    /// this prepared request.
122    ///
123    /// This is only a local denial-of-service filter. The enclave remains the
124    /// authority for the grant signature, expiry, principal, and target
125    /// binding before it authenticates the session.
126    pub fn matches_untrusted_grant_target(&self, grant: &NativeOAuthHandoffGrant) -> bool {
127        grant.untrusted_target().is_some_and(|target| {
128            target.session_id == self.session_id && target.request_id == self.request_id
129        })
130    }
131}
132
133impl fmt::Debug for PreparedNativeOAuthHandoff {
134    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
135        formatter
136            .debug_struct("PreparedNativeOAuthHandoff")
137            .field("session_id", &self.session_id)
138            .field("request_id", &self.request_id)
139            .finish_non_exhaustive()
140    }
141}
142
143/// A short-lived signed grant minted by the authenticated hosted browser.
144pub struct NativeOAuthHandoffGrant(Zeroizing<String>);
145
146#[derive(Deserialize)]
147struct UntrustedNativeOAuthHandoffTarget {
148    #[serde(rename = "sid")]
149    session_id: String,
150    #[serde(rename = "rid")]
151    request_id: String,
152}
153
154impl NativeOAuthHandoffGrant {
155    pub fn new(value: impl Into<String>) -> Result<Self> {
156        let value = value.into();
157        if value.is_empty() || value.len() > MAX_NATIVE_OAUTH_HANDOFF_GRANT_BYTES {
158            return Err(Error::Authentication(
159                "Native OAuth handoff grant is invalid".to_string(),
160            ));
161        }
162        let segments = value.split('.').collect::<Vec<_>>();
163        if segments.len() != 3
164            || segments.iter().any(|segment| {
165                segment.is_empty()
166                    || URL_SAFE_NO_PAD
167                        .decode(segment)
168                        .ok()
169                        .is_none_or(|decoded| URL_SAFE_NO_PAD.encode(decoded) != *segment)
170            })
171        {
172            return Err(Error::Authentication(
173                "Native OAuth handoff grant is invalid".to_string(),
174            ));
175        }
176        Ok(Self(Zeroizing::new(value)))
177    }
178
179    fn as_str(&self) -> &str {
180        self.0.as_str()
181    }
182
183    fn untrusted_target(&self) -> Option<UntrustedNativeOAuthHandoffTarget> {
184        let payload = self.0.split('.').nth(1)?;
185        let decoded = Zeroizing::new(URL_SAFE_NO_PAD.decode(payload).ok()?);
186        let target: UntrustedNativeOAuthHandoffTarget =
187            serde_json::from_slice(decoded.as_slice()).ok()?;
188        if !is_canonical_transport_id(&target.session_id)
189            || !is_canonical_transport_id(&target.request_id)
190        {
191            return None;
192        }
193        Some(target)
194    }
195}
196
197fn is_canonical_transport_id(value: &str) -> bool {
198    value.len() == 32
199        && value
200            .bytes()
201            .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
202}
203
204impl fmt::Debug for NativeOAuthHandoffGrant {
205    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
206        formatter.write_str("NativeOAuthHandoffGrant([REDACTED])")
207    }
208}
209
210#[derive(Serialize)]
211struct NativeOAuthHandoffRedeemRequest<'a> {
212    grant: &'a str,
213}
214
215/// Caller-persistable provider-cache namespace root for Transport V2.
216///
217/// Applications that need cache hits across restarts should generate this
218/// once, persist it as a secret, and restore it when constructing the client.
219#[derive(Clone, Eq, PartialEq, Zeroize, ZeroizeOnDrop)]
220pub struct TransportV2CacheNamespaceRoot([u8; 32]);
221
222impl TransportV2CacheNamespaceRoot {
223    pub fn generate() -> Result<Self> {
224        let mut bytes = [0_u8; 32];
225        OsRng
226            .try_fill_bytes(&mut bytes)
227            .map_err(|_| Error::Encryption("Secure randomness was unavailable".to_string()))?;
228        Ok(Self(bytes))
229    }
230
231    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
232        Self(bytes)
233    }
234
235    pub fn from_base64(encoded: &str) -> Result<Self> {
236        let decoded = Zeroizing::new(BASE64.decode(encoded)?);
237        if decoded.len() != 32 || BASE64.encode(decoded.as_slice()) != encoded {
238            return Err(Error::Configuration(
239                "Transport V2 cache namespace root must be canonical padded base64 for exactly 32 bytes"
240                    .to_string(),
241            ));
242        }
243        let mut bytes = [0_u8; 32];
244        bytes.copy_from_slice(decoded.as_slice());
245        Ok(Self(bytes))
246    }
247
248    pub fn to_base64(&self) -> String {
249        BASE64.encode(self.0)
250    }
251
252    fn expose_bytes(&self) -> [u8; 32] {
253        self.0
254    }
255}
256
257impl std::fmt::Debug for TransportV2CacheNamespaceRoot {
258    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
259        formatter.write_str("TransportV2CacheNamespaceRoot([REDACTED])")
260    }
261}
262
263pub struct OpenSecretClient {
264    session_manager: SessionManager,
265    refresh_lock: Mutex<()>,
266    session_gate: Mutex<()>,
267    transport_session: TransportSessionSlot,
268    transport_v2: TransportV2Client,
269    cache_namespace_root: TransportV2CacheNamespaceRoot,
270}
271
272#[derive(Debug, Clone, PartialEq, Eq)]
273struct ResolvedAuth {
274    token: Option<String>,
275    source: CredentialSource,
276}
277
278#[derive(Debug, Clone, Copy, PartialEq, Eq)]
279enum CredentialSource {
280    Anonymous,
281    StoredAccessToken { generation: u64 },
282    StoredApiKey { generation: u64 },
283    StoredRefreshToken { generation: u64 },
284    ExplicitApiKey,
285}
286
287impl Drop for ResolvedAuth {
288    fn drop(&mut self) {
289        if let Some(token) = &mut self.token {
290            token.zeroize();
291        }
292    }
293}
294
295impl ResolvedAuth {
296    fn credential_kind(&self) -> Option<CredentialKind> {
297        match self.source {
298            CredentialSource::Anonymous => None,
299            CredentialSource::StoredAccessToken { .. } => Some(CredentialKind::Bearer),
300            CredentialSource::StoredApiKey { .. } | CredentialSource::ExplicitApiKey => {
301                Some(CredentialKind::ApiKey)
302            }
303            CredentialSource::StoredRefreshToken { .. } => Some(CredentialKind::Resumption),
304        }
305    }
306
307    fn fence(&self) -> Option<CredentialFence<'_>> {
308        let value = self.token.as_deref()?;
309        match self.source {
310            CredentialSource::Anonymous | CredentialSource::ExplicitApiKey => None,
311            CredentialSource::StoredAccessToken { generation } => {
312                Some(CredentialFence::AccessToken { generation, value })
313            }
314            CredentialSource::StoredApiKey { generation } => {
315                Some(CredentialFence::ApiKey { generation, value })
316            }
317            CredentialSource::StoredRefreshToken { generation } => {
318                Some(CredentialFence::RefreshToken { generation, value })
319            }
320        }
321    }
322}
323
324fn append_query_param(query: &mut Vec<String>, key: &str, value: impl ToString) {
325    let encoded = utf8_percent_encode(&value.to_string(), NON_ALPHANUMERIC).to_string();
326    query.push(format!("{}={}", key, encoded));
327}
328
329fn build_agent_items_endpoint(base: &str, params: Option<&AgentItemsListParams>) -> String {
330    let mut endpoint = base.to_string();
331    let mut query = Vec::new();
332
333    if let Some(params) = params {
334        if let Some(limit) = params.limit {
335            append_query_param(&mut query, "limit", limit);
336        }
337        if let Some(after) = params.after {
338            append_query_param(&mut query, "after", after);
339        }
340        if let Some(order) = &params.order {
341            append_query_param(&mut query, "order", order);
342        }
343        if let Some(include) = &params.include {
344            for include_value in include {
345                append_query_param(&mut query, "include", include_value);
346            }
347        }
348    }
349
350    if !query.is_empty() {
351        endpoint.push('?');
352        endpoint.push_str(&query.join("&"));
353    }
354
355    endpoint
356}
357
358fn build_subagents_endpoint(params: Option<&ListSubagentsParams>) -> String {
359    let mut endpoint = "/v1/agent/subagents".to_string();
360    let mut query = Vec::new();
361
362    if let Some(params) = params {
363        if let Some(limit) = params.limit {
364            append_query_param(&mut query, "limit", limit);
365        }
366        if let Some(after) = params.after {
367            append_query_param(&mut query, "after", after);
368        }
369        if let Some(order) = &params.order {
370            append_query_param(&mut query, "order", order);
371        }
372        if let Some(created_by) = &params.created_by {
373            append_query_param(&mut query, "created_by", created_by);
374        }
375    }
376
377    if !query.is_empty() {
378        endpoint.push('?');
379        endpoint.push_str(&query.join("&"));
380    }
381
382    endpoint
383}
384
385fn build_conversations_endpoint(params: Option<&ConversationsListParams>) -> String {
386    let mut endpoint = "/v1/conversations".to_string();
387    let mut query = Vec::new();
388
389    if let Some(params) = params {
390        if let Some(limit) = params.limit {
391            append_query_param(&mut query, "limit", limit);
392        }
393        if let Some(after) = params.after {
394            append_query_param(&mut query, "after", after);
395        }
396        if let Some(order) = &params.order {
397            append_query_param(&mut query, "order", order);
398        }
399        if let Some(project_id) = params.project_id {
400            append_query_param(&mut query, "project_id", project_id);
401        }
402        if let Some(unassigned_project) = params.unassigned_project {
403            append_query_param(&mut query, "unassigned_project", unassigned_project);
404        }
405        if let Some(pinned) = params.pinned {
406            append_query_param(&mut query, "pinned", pinned);
407        }
408    }
409
410    if !query.is_empty() {
411        endpoint.push('?');
412        endpoint.push_str(&query.join("&"));
413    }
414
415    endpoint
416}
417
418fn build_conversation_projects_endpoint(params: Option<&ConversationProjectListParams>) -> String {
419    let mut endpoint = "/v1/conversation-projects".to_string();
420    let mut query = Vec::new();
421
422    if let Some(params) = params {
423        if let Some(limit) = params.limit {
424            append_query_param(&mut query, "limit", limit);
425        }
426        if let Some(after) = params.after {
427            append_query_param(&mut query, "after", after);
428        }
429        if let Some(order) = &params.order {
430            append_query_param(&mut query, "order", order);
431        }
432    }
433
434    if !query.is_empty() {
435        endpoint.push('?');
436        endpoint.push_str(&query.join("&"));
437    }
438
439    endpoint
440}
441
442#[derive(Clone, Copy, PartialEq, Eq)]
443enum AuthHeaderMode {
444    None,
445    Jwt,
446    ApiKeyOrJwt,
447}
448
449/// Builds a JSON inference request for the typed helpers.
450pub(crate) fn json_inference_request<T: Serialize>(
451    endpoint: &str,
452    method: http::Method,
453    data: Option<&T>,
454) -> Result<InferenceRequest> {
455    let body = match data {
456        Some(data) => Bytes::from(serde_json::to_vec(data)?),
457        None => Bytes::new(),
458    };
459    let mut builder = HttpRequest::builder().method(method).uri(endpoint);
460    if !body.is_empty() {
461        builder = builder.header(header::CONTENT_TYPE, "application/json");
462    }
463    builder.body(body).map_err(|error| {
464        Error::Configuration(format!("Failed to build inference request: {error}"))
465    })
466}
467
468/// Decodes a typed helper's response: a non-2xx status becomes [`Error::Api`]
469/// with the backend's body, so its message and `error.code` survive.
470async fn json_inference_response<U: DeserializeOwned>(response: InferenceResponse) -> Result<U> {
471    let status = response.status();
472    let body = collect_response_body(response.into_body()).await?;
473    if !status.is_success() {
474        return Err(Error::Api {
475            status: status.as_u16(),
476            message: String::from_utf8_lossy(&body).into_owned(),
477        });
478    }
479    Ok(serde_json::from_slice(&body)?)
480}
481
482fn is_allowed_inference_endpoint(method: &http::Method, path: &str) -> bool {
483    matches!(
484        (method.as_str(), path),
485        ("GET", "/v1/models")
486            | ("GET", "/v1/models/catalog")
487            | ("POST", "/v1/chat/completions")
488            | ("POST", "/v1/embeddings")
489            | ("POST", "/v1/systemone")
490            | ("POST", "/v1/audio/speech")
491            | ("POST", "/v1/audio/transcriptions")
492    )
493}
494
495fn is_hop_by_hop_header(name: &http::HeaderName) -> bool {
496    matches!(
497        name.as_str(),
498        "connection"
499            | "keep-alive"
500            | "proxy-authenticate"
501            | "proxy-authorization"
502            | "te"
503            | "trailer"
504            | "transfer-encoding"
505            | "upgrade"
506    )
507}
508
509fn sanitize_inference_request_headers(headers: &HttpHeaderMap) -> HttpHeaderMap {
510    let connection_headers = headers
511        .get_all(header::CONNECTION)
512        .iter()
513        .filter_map(|value| value.to_str().ok())
514        .flat_map(|value| value.split(','))
515        .map(str::trim)
516        .filter(|value| !value.is_empty())
517        .filter_map(|value| http::HeaderName::from_bytes(value.as_bytes()).ok())
518        .collect::<Vec<_>>();
519
520    let mut sanitized = HttpHeaderMap::new();
521    for (name, value) in headers {
522        if !is_hop_by_hop_header(name)
523            && !connection_headers.contains(name)
524            && *name != header::HOST
525            && *name != header::AUTHORIZATION
526            && *name != header::COOKIE
527            && *name != header::SET_COOKIE
528            && name.as_str() != "x-session-id"
529            && name.as_str() != ROUTING_KEY_HEADER
530            && name.as_str() != "forwarded"
531            && name.as_str() != "via"
532            && name.as_str() != "x-forwarded-for"
533            && name.as_str() != "x-forwarded-host"
534            && name.as_str() != "x-forwarded-proto"
535            && *name != header::CONTENT_LENGTH
536            && *name != header::CONTENT_ENCODING
537            && *name != header::ACCEPT_ENCODING
538            && name.as_str() != "content-md5"
539            && name.as_str() != "digest"
540        {
541            sanitized.append(name.clone(), value.clone());
542        }
543    }
544    sanitized
545}
546
547fn sanitize_inference_response_headers(headers: &HttpHeaderMap) -> HttpHeaderMap {
548    let connection_headers = headers
549        .get_all(header::CONNECTION)
550        .iter()
551        .filter_map(|value| value.to_str().ok())
552        .flat_map(|value| value.split(','))
553        .map(str::trim)
554        .filter(|value| !value.is_empty())
555        .filter_map(|value| http::HeaderName::from_bytes(value.as_bytes()).ok())
556        .collect::<Vec<_>>();
557
558    let mut sanitized = HttpHeaderMap::new();
559    for (name, value) in headers {
560        if !is_hop_by_hop_header(name)
561            && !connection_headers.contains(name)
562            && *name != header::CONTENT_LENGTH
563            && *name != header::CONTENT_ENCODING
564            && name.as_str() != "content-md5"
565            && name.as_str() != "digest"
566            && *name != header::ETAG
567        {
568            sanitized.append(name.clone(), value.clone());
569        }
570    }
571    sanitized
572}
573
574fn permits_session_recovery(target: &str) -> bool {
575    !matches!(
576        target.split('?').next().unwrap_or(target),
577        "/auth/github/callback"
578            | "/auth/google/callback"
579            | "/auth/apple/callback"
580            | "/auth/native-handoff/redeem"
581    )
582}
583
584async fn collect_response_body(mut body: OpenSecretResponseBody) -> Result<Bytes> {
585    let mut collected = BytesMut::new();
586    while let Some(chunk) = body.next().await {
587        collected.extend_from_slice(&chunk?);
588    }
589    Ok(collected.freeze())
590}
591
592fn transport_error(error: TransportV2Error) -> Error {
593    match error {
594        TransportV2Error::InvalidConfiguration => {
595            Error::Configuration("Transport V2 configuration is invalid".to_string())
596        }
597        TransportV2Error::AttestationRejected => Error::AttestationVerificationFailed(
598            "Transport V2 attestation or PCR policy was rejected".to_string(),
599        ),
600        TransportV2Error::SessionExpired => {
601            Error::Session("Transport V2 session expired".to_string())
602        }
603        TransportV2Error::Http(error) => Error::Http(error),
604        TransportV2Error::UntrustedOuterResponse | TransportV2Error::SessionRecoveryHint(_) => {
605            Error::InvalidResponse(
606                "Transport V2 returned an unauthenticated outer response".to_string(),
607            )
608        }
609        TransportV2Error::Authentication
610        | TransportV2Error::InvalidFrame
611        | TransportV2Error::InvalidRecord
612        | TransportV2Error::InvalidSequence
613        | TransportV2Error::TruncatedResponse
614        | TransportV2Error::PostTerminalData => Error::InvalidResponse(
615            "Transport V2 response authentication or framing failed".to_string(),
616        ),
617        _ => Error::Encryption(error.to_string()),
618    }
619}
620
621fn should_retire_transport_session(error: &TransportV2Error) -> bool {
622    matches!(
623        error,
624        TransportV2Error::SessionExpired
625            | TransportV2Error::Authentication
626            | TransportV2Error::UntrustedOuterResponse
627            | TransportV2Error::SessionRecoveryHint(_)
628            | TransportV2Error::InvalidFrame
629            | TransportV2Error::InvalidRecord
630            | TransportV2Error::InvalidSequence
631            | TransportV2Error::TruncatedResponse
632            | TransportV2Error::PostTerminalData
633    )
634}
635
636fn retire_transport_session_after_stream_failure(retirement: &Option<SessionRetirement>) {
637    let Some((slot, expected)) = retirement else {
638        return;
639    };
640    let Ok(mut current) = slot.write() else {
641        return;
642    };
643    if current
644        .as_ref()
645        .is_some_and(|session| Arc::ptr_eq(session, expected))
646    {
647        *current = None;
648    }
649}
650
651fn response_body_from_events(
652    mut events: ResponseEventStream,
653    retirement: Option<SessionRetirement>,
654) -> OpenSecretResponseBody {
655    Box::pin(async_stream::try_stream! {
656        while let Some(event) = events.next().await {
657            let event = match event {
658                Ok(event) => event,
659                Err(error) => {
660                    if should_retire_transport_session(&error) {
661                        retire_transport_session_after_stream_failure(&retirement);
662                    }
663                    Err(transport_error(error))?
664                }
665            };
666            match event {
667                ResponseEvent::Chunk(bytes) => yield bytes,
668                ResponseEvent::End => return,
669                ResponseEvent::Error { code } => {
670                    Err(Error::InvalidResponse(format!(
671                        "Transport V2 response stream failed ({code})"
672                    )))?;
673                }
674                ResponseEvent::Start { .. } => {
675                    retire_transport_session_after_stream_failure(&retirement);
676                    Err(Error::InvalidResponse(
677                        "Transport V2 response contained more than one start record".to_string(),
678                    ))?;
679                }
680            }
681        }
682        retire_transport_session_after_stream_failure(&retirement);
683        Err(Error::InvalidResponse(
684            "Transport V2 response ended without authenticated finality".to_string(),
685        ))?;
686    })
687}
688
689async fn response_from_events(
690    mut events: ResponseEventStream,
691    retirement: Option<SessionRetirement>,
692) -> Result<InferenceResponse> {
693    let Some(start) = events.next().await else {
694        retire_transport_session_after_stream_failure(&retirement);
695        return Err(Error::InvalidResponse(
696            "Transport V2 response ended before its start record".to_string(),
697        ));
698    };
699    let start = match start {
700        Ok(start) => start,
701        Err(error) => {
702            if should_retire_transport_session(&error) {
703                retire_transport_session_after_stream_failure(&retirement);
704            }
705            return Err(transport_error(error));
706        }
707    };
708    let ResponseEvent::Start { status, headers } = start else {
709        retire_transport_session_after_stream_failure(&retirement);
710        return Err(Error::InvalidResponse(
711            "Transport V2 response did not begin with a start record".to_string(),
712        ));
713    };
714    let status = http::StatusCode::from_u16(status)
715        .map_err(|_| Error::InvalidResponse("Transport V2 status was invalid".to_string()))?;
716    let mut response_headers = HttpHeaderMap::new();
717    for logical in headers {
718        let name = http::HeaderName::from_bytes(logical.name().as_bytes()).map_err(|_| {
719            Error::InvalidResponse("Transport V2 header name was invalid".to_string())
720        })?;
721        let value = http::HeaderValue::from_str(logical.value()).map_err(|_| {
722            Error::InvalidResponse("Transport V2 header value was invalid".to_string())
723        })?;
724        response_headers.append(name, value);
725    }
726    let mut response = HttpResponse::new(response_body_from_events(events, retirement));
727    *response.status_mut() = status;
728    *response.headers_mut() = response_headers;
729    Ok(response)
730}
731
732#[derive(Deserialize)]
733struct JwtTimingClaims {
734    exp: u64,
735}
736
737fn access_token_needs_refresh(token: &str, now: u64) -> bool {
738    let mut segments = token.split('.');
739    let (Some(_header), Some(payload), Some(_signature), None) = (
740        segments.next(),
741        segments.next(),
742        segments.next(),
743        segments.next(),
744    ) else {
745        return false;
746    };
747    URL_SAFE_NO_PAD
748        .decode(payload)
749        .ok()
750        .and_then(|payload| serde_json::from_slice::<JwtTimingClaims>(&payload).ok())
751        .is_some_and(|claims| claims.exp <= now.saturating_add(30))
752}
753
754fn build_chat_completion_stream_request(
755    mut request: ChatCompletionRequest,
756) -> Result<InferenceRequest> {
757    request.stream = Some(true);
758    request.stream_options = Some(StreamOptions {
759        include_usage: true,
760    });
761    HttpRequest::builder()
762        .method(http::Method::POST)
763        .uri("/v1/chat/completions")
764        .header(header::ACCEPT, "text/event-stream")
765        .header(header::CONTENT_TYPE, "application/json")
766        .body(Bytes::from(serde_json::to_vec(&request)?))
767        .map_err(|error| {
768            Error::Configuration(format!("Failed to build inference request: {error}"))
769        })
770}
771
772fn parse_agent_sse_event(event_type: &str, data: &str) -> Option<Result<AgentSseEvent>> {
773    let parsed = match event_type {
774        "agent.message" => serde_json::from_str(data).map(AgentSseEvent::Message),
775        "agent.reaction" => serde_json::from_str(data).map(AgentSseEvent::Reaction),
776        "agent.typing" => serde_json::from_str(data).map(AgentSseEvent::Typing),
777        "agent.done" => serde_json::from_str(data).map(AgentSseEvent::Done),
778        "agent.error" => serde_json::from_str(data).map(AgentSseEvent::Error),
779        _ => return None,
780    };
781    Some(parsed.map_err(|error| Error::Api {
782        status: 0,
783        message: format!("Failed to parse {event_type}: {error}"),
784    }))
785}
786
787impl OpenSecretClient {
788    /// Construct a client using the official production PCR0 trust roots.
789    pub fn new(base_url: impl Into<String>) -> Result<Self> {
790        Self::new_with_pcr0_environment(base_url, Pcr0Environment::default())
791    }
792
793    /// Construct a client using one explicit official PCR0 environment.
794    pub fn new_with_pcr0_environment(
795        base_url: impl Into<String>,
796        pcr0_environment: Pcr0Environment,
797    ) -> Result<Self> {
798        Self::new_with_pcr0_trust_policy(base_url, Pcr0TrustPolicy::official_for(pcr0_environment))
799    }
800
801    /// Construct a client with an explicit PCR0 trust policy.
802    pub fn new_with_pcr0_trust_policy(
803        base_url: impl Into<String>,
804        pcr0_trust_policy: Pcr0TrustPolicy,
805    ) -> Result<Self> {
806        let transport_v2 =
807            TransportV2Client::new(base_url.into(), pcr0_trust_policy).map_err(transport_error)?;
808        Ok(Self {
809            session_manager: SessionManager::new(),
810            refresh_lock: Mutex::new(()),
811            session_gate: Mutex::new(()),
812            transport_session: Arc::new(RwLock::new(None)),
813            transport_v2,
814            cache_namespace_root: TransportV2CacheNamespaceRoot::generate()?,
815        })
816    }
817
818    /// Construct an API-key client using the official production PCR0 trust roots.
819    pub fn new_with_api_key(base_url: impl Into<String>, api_key: String) -> Result<Self> {
820        Self::new_with_api_key_and_pcr0_environment(base_url, api_key, Pcr0Environment::default())
821    }
822
823    /// Construct an API-key client using one explicit official PCR0 environment.
824    pub fn new_with_api_key_and_pcr0_environment(
825        base_url: impl Into<String>,
826        api_key: String,
827        pcr0_environment: Pcr0Environment,
828    ) -> Result<Self> {
829        Self::new_with_api_key_and_pcr0_trust_policy(
830            base_url,
831            api_key,
832            Pcr0TrustPolicy::official_for(pcr0_environment),
833        )
834    }
835
836    /// Construct an API-key client with an explicit PCR0 trust policy.
837    pub fn new_with_api_key_and_pcr0_trust_policy(
838        base_url: impl Into<String>,
839        api_key: String,
840        pcr0_trust_policy: Pcr0TrustPolicy,
841    ) -> Result<Self> {
842        let transport_v2 =
843            TransportV2Client::new(base_url.into(), pcr0_trust_policy).map_err(transport_error)?;
844        Ok(Self {
845            session_manager: SessionManager::new_with_api_key(api_key),
846            refresh_lock: Mutex::new(()),
847            session_gate: Mutex::new(()),
848            transport_session: Arc::new(RwLock::new(None)),
849            transport_v2,
850            cache_namespace_root: TransportV2CacheNamespaceRoot::generate()?,
851        })
852    }
853
854    /// Replace the random per-client provider-cache namespace root.
855    ///
856    /// The root must be generated independently from account identifiers and
857    /// credentials. Persist it when cache continuity across restarts matters.
858    #[must_use]
859    pub fn with_cache_namespace_root(mut self, root: TransportV2CacheNamespaceRoot) -> Self {
860        self.cache_namespace_root = root;
861        self
862    }
863
864    pub fn set_api_key(&self, api_key: String) -> Result<()> {
865        self.session_manager.set_api_key(api_key)
866    }
867
868    pub fn clear_api_key(&self) -> Result<()> {
869        self.session_manager.clear_api_key()
870    }
871
872    pub async fn perform_attestation_handshake(&self) -> Result<()> {
873        let _gate = self.session_gate.lock().await;
874        let session = Arc::new(
875            self.transport_v2
876                .establish_session()
877                .await
878                .map_err(transport_error)?,
879        );
880        let mut current = self
881            .transport_session
882            .write()
883            .map_err(|_| Error::Session("Transport V2 session state is unavailable".to_string()))?;
884        *current = Some(session);
885        Ok(())
886    }
887
888    /// Reserve one exact anonymous request for a hosted native OAuth handoff.
889    ///
890    /// The returned IDs may be sent to the hosted browser so the enclave can
891    /// bind its signed grant to this request. The handle itself must remain in
892    /// the native process and is consumed exactly once by redemption.
893    pub async fn prepare_native_oauth_handoff(&self) -> Result<PreparedNativeOAuthHandoff> {
894        let credential_generation = self.session_manager.anonymous_generation()?;
895        let session = self.ensure_transport_session().await?;
896        let prepared_request = {
897            let current = self.transport_session.read().map_err(|_| {
898                Error::Session("Transport V2 session state is unavailable".to_string())
899            })?;
900            if !current
901                .as_ref()
902                .is_some_and(|current| Arc::ptr_eq(current, &session))
903            {
904                return Err(Error::Session(
905                    "Native OAuth transport session is no longer current".to_string(),
906                ));
907            }
908            self.session_manager
909                .admit_if_anonymous_generation_is_current(credential_generation, || {
910                    session.prepare_request_id().map_err(transport_error)
911                })?
912        };
913        let session_id = session.encoded_id();
914        let request_id = prepared_request.encoded();
915        Ok(PreparedNativeOAuthHandoff {
916            session,
917            prepared_request,
918            session_id,
919            request_id,
920            credential_generation,
921        })
922    }
923
924    /// Redeem a hosted handoff grant through the exact request prepared above.
925    ///
926    /// No credential or cache namespace root is attached. This method sends at
927    /// most once and never allocates a replacement request ID.
928    pub async fn redeem_native_oauth_handoff(
929        &self,
930        prepared: PreparedNativeOAuthHandoff,
931        grant: NativeOAuthHandoffGrant,
932    ) -> Result<LoginResponse> {
933        // Hold the current-session read lock through sealing, and the
934        // credential read lock inside it. A concurrent session replacement or
935        // authentication change must linearize wholly before or after this
936        // exact request becomes eligible for transmission.
937        let sealed = {
938            let current = self.transport_session.read().map_err(|_| {
939                Error::Session("Transport V2 session state is unavailable".to_string())
940            })?;
941            let current = current.as_ref().ok_or_else(|| {
942                Error::Session("Native OAuth transport session is no longer current".to_string())
943            })?;
944            if current.is_expired() || !Arc::ptr_eq(current, &prepared.session) {
945                return Err(Error::Session(
946                    "Native OAuth transport session is no longer current".to_string(),
947                ));
948            }
949            self.session_manager
950                .admit_if_anonymous_generation_is_current(prepared.credential_generation, || {
951                    let body = Bytes::from(serde_json::to_vec(&NativeOAuthHandoffRedeemRequest {
952                        grant: grant.as_str(),
953                    })?);
954                    let request = LogicalRequest::new(
955                        None,
956                        None,
957                        http::Method::POST,
958                        "/auth/native-handoff/redeem".to_string(),
959                        vec![LogicalHeader::new(
960                            header::CONTENT_TYPE.as_str().to_string(),
961                            "application/json".to_string(),
962                        )
963                        .map_err(transport_error)?],
964                        Some(body),
965                    )
966                    .map_err(transport_error)?;
967                    self.transport_v2
968                        .seal_with_id(&prepared.session, prepared.prepared_request, request)
969                        .map_err(transport_error)
970                })?
971        };
972        drop(grant);
973
974        let events = match self.transport_v2.send_sealed(sealed).await {
975            Ok(events) => events,
976            Err(error) => {
977                // Delivery may have happened even when no authenticated
978                // response arrived. The enclave may therefore have bound the
979                // session while this client still appears anonymous.
980                self.clear_transport_session_if(&prepared.session)?;
981                return Err(transport_error(error));
982            }
983        };
984        let response = match response_from_events(
985            events,
986            Some((
987                Arc::clone(&self.transport_session),
988                Arc::clone(&prepared.session),
989            )),
990        )
991        .await
992        {
993            Ok(response) => response,
994            Err(error) => {
995                self.clear_transport_session_if(&prepared.session)?;
996                return Err(error);
997            }
998        };
999        let status = response.status();
1000        let body = match collect_response_body(response.into_body()).await {
1001            Ok(body) => body,
1002            Err(error) => {
1003                self.clear_transport_session_if(&prepared.session)?;
1004                return Err(error);
1005            }
1006        };
1007        if !status.is_success() {
1008            self.clear_transport_session_if(&prepared.session)?;
1009            return Err(Error::Api {
1010                status: status.as_u16(),
1011                message: String::from_utf8_lossy(&body).into_owned(),
1012            });
1013        }
1014        let mut response: LoginResponse = match serde_json::from_slice(&body) {
1015            Ok(response) => response,
1016            Err(error) => {
1017                self.clear_transport_session_if(&prepared.session)?;
1018                return Err(error.into());
1019            }
1020        };
1021        let installed = {
1022            // The response belongs to the retained session. Do not install it
1023            // into a client whose session was replaced while redemption was
1024            // in flight, even if its credential generation is still anonymous.
1025            let current = self.transport_session.read().map_err(|_| {
1026                Error::Session("Transport V2 session state is unavailable".to_string())
1027            })?;
1028            current
1029                .as_ref()
1030                .is_some_and(|current| Arc::ptr_eq(current, &prepared.session))
1031                && self.session_manager.set_tokens_if_anonymous_generation(
1032                    prepared.credential_generation,
1033                    response.access_token.clone(),
1034                    response.refresh_token.clone(),
1035                )?
1036        };
1037        if !installed {
1038            response.access_token.zeroize();
1039            response.refresh_token.zeroize();
1040            self.clear_transport_session_if(&prepared.session)?;
1041            return Err(Error::Authentication(
1042                "Authentication changed during native OAuth handoff".to_string(),
1043            ));
1044        }
1045        Ok(response)
1046    }
1047
1048    async fn ensure_transport_session(&self) -> Result<Arc<TransportV2Session>> {
1049        if let Some(session) = self.current_transport_session()? {
1050            if !session.is_expired() {
1051                return Ok(session);
1052            }
1053            self.clear_transport_session_if(&session)?;
1054        }
1055
1056        let _gate = self.session_gate.lock().await;
1057        if let Some(session) = self.current_transport_session()? {
1058            if !session.is_expired() {
1059                return Ok(session);
1060            }
1061            self.clear_transport_session_if(&session)?;
1062        }
1063
1064        let session = Arc::new(
1065            self.transport_v2
1066                .establish_session()
1067                .await
1068                .map_err(transport_error)?,
1069        );
1070        let mut current = self
1071            .transport_session
1072            .write()
1073            .map_err(|_| Error::Session("Transport V2 session state is unavailable".to_string()))?;
1074        *current = Some(Arc::clone(&session));
1075        Ok(session)
1076    }
1077
1078    fn current_transport_session(&self) -> Result<Option<Arc<TransportV2Session>>> {
1079        self.transport_session
1080            .read()
1081            .map(|session| session.clone())
1082            .map_err(|_| Error::Session("Transport V2 session state is unavailable".to_string()))
1083    }
1084
1085    fn clear_transport_session_if(&self, expected: &Arc<TransportV2Session>) -> Result<()> {
1086        let mut current = self
1087            .transport_session
1088            .write()
1089            .map_err(|_| Error::Session("Transport V2 session state is unavailable".to_string()))?;
1090        if current
1091            .as_ref()
1092            .is_some_and(|session| Arc::ptr_eq(session, expected))
1093        {
1094            *current = None;
1095        }
1096        Ok(())
1097    }
1098
1099    pub fn get_session_id(&self) -> Result<Option<Uuid>> {
1100        let Some(session) = self.current_transport_session()? else {
1101            return Ok(None);
1102        };
1103        if session.is_expired() {
1104            self.clear_transport_session_if(&session)?;
1105            return Ok(None);
1106        }
1107        Ok(Some(Uuid::from_bytes(session.id_bytes())))
1108    }
1109
1110    pub async fn test_connection(&self) -> Result<String> {
1111        let response = self
1112            .send_logical_request(
1113                http::Method::GET,
1114                "/health-check".to_string(),
1115                Vec::new(),
1116                None,
1117                ResolvedAuth {
1118                    token: None,
1119                    source: CredentialSource::Anonymous,
1120                },
1121                false,
1122            )
1123            .await?;
1124        let status = response.status();
1125        let body = collect_response_body(response.into_body()).await?;
1126        if !status.is_success() {
1127            return Err(Error::Api {
1128                status: status.as_u16(),
1129                message: String::from_utf8_lossy(&body).into_owned(),
1130            });
1131        }
1132        String::from_utf8(body.to_vec()).map_err(Into::into)
1133    }
1134
1135    async fn encrypted_api_call<T: Serialize, U: DeserializeOwned>(
1136        &self,
1137        endpoint: &str,
1138        method: &str,
1139        data: Option<T>,
1140    ) -> Result<U> {
1141        let auth = self.resolve_auth(AuthHeaderMode::None)?;
1142        self.json_request(endpoint, method, data, auth).await
1143    }
1144
1145    async fn authenticated_api_call<T: Serialize, U: DeserializeOwned>(
1146        &self,
1147        endpoint: &str,
1148        method: &str,
1149        data: Option<T>,
1150    ) -> Result<U> {
1151        let auth = self
1152            .resolve_auth_after_preflight(AuthHeaderMode::Jwt)
1153            .await?;
1154        self.json_request(endpoint, method, data, auth).await
1155    }
1156
1157    async fn json_request<T: Serialize, U: DeserializeOwned>(
1158        &self,
1159        endpoint: &str,
1160        method: &str,
1161        data: Option<T>,
1162        auth: ResolvedAuth,
1163    ) -> Result<U> {
1164        let method = http::Method::from_bytes(method.as_bytes()).map_err(|error| {
1165            Error::Configuration(format!("Invalid logical HTTP method: {error}"))
1166        })?;
1167        let body = data
1168            .map(|data| serde_json::to_vec(&data).map(Bytes::from))
1169            .transpose()?;
1170        let headers = if body.is_some() {
1171            vec![LogicalHeader::new(
1172                header::CONTENT_TYPE.as_str().to_string(),
1173                "application/json".to_string(),
1174            )
1175            .map_err(transport_error)?]
1176        } else {
1177            Vec::new()
1178        };
1179        let response = self
1180            .send_logical_request(method, endpoint.to_string(), headers, body, auth, false)
1181            .await?;
1182        let status = response.status();
1183        let body = collect_response_body(response.into_body()).await?;
1184        if !status.is_success() {
1185            return Err(Error::Api {
1186                status: status.as_u16(),
1187                message: String::from_utf8_lossy(&body).into_owned(),
1188            });
1189        }
1190        Ok(serde_json::from_slice(&body)?)
1191    }
1192
1193    async fn send_logical_request(
1194        &self,
1195        method: http::Method,
1196        target: String,
1197        headers: Vec<LogicalHeader>,
1198        body: Option<Bytes>,
1199        auth: ResolvedAuth,
1200        include_cache_namespace: bool,
1201    ) -> Result<InferenceResponse> {
1202        self.send_logical_request_with_options(
1203            method,
1204            target,
1205            headers,
1206            body,
1207            auth,
1208            LogicalRequestOptions {
1209                include_cache_namespace,
1210                inference_send_budget: None,
1211            },
1212        )
1213        .await
1214    }
1215
1216    async fn send_logical_request_with_options(
1217        &self,
1218        method: http::Method,
1219        target: String,
1220        headers: Vec<LogicalHeader>,
1221        body: Option<Bytes>,
1222        auth: ResolvedAuth,
1223        options: LogicalRequestOptions<'_>,
1224    ) -> Result<InferenceResponse> {
1225        let permits_recovery = permits_session_recovery(&target);
1226        let anonymous_generation = matches!(auth.source, CredentialSource::Anonymous)
1227            .then(|| self.session_manager.credential_generation())
1228            .transpose()?;
1229        let credential = auth
1230            .credential_kind()
1231            .zip(auth.token.as_ref())
1232            .map(|(kind, token)| Credential::new(kind, token.clone()))
1233            .transpose()
1234            .map_err(transport_error)?;
1235        let cache_namespace_root = (options.include_cache_namespace && credential.is_some())
1236            .then(|| CacheNamespaceRoot::from_bytes(self.cache_namespace_root.expose_bytes()));
1237        let request = LogicalRequest::new(
1238            credential,
1239            cache_namespace_root,
1240            method,
1241            target,
1242            headers,
1243            body,
1244        )
1245        .map_err(transport_error)?;
1246
1247        // Capture once: public inference bodies are owned Bytes, and typed
1248        // request bodies have already been serialized. A recovery must not
1249        // select a new credential or reconstruct any part of the request.
1250        let plaintext = request.encode().map_err(transport_error)?;
1251        drop(request);
1252        let mut recovery_used = false;
1253        loop {
1254            let session = self.ensure_transport_session().await?;
1255            // Fence each admission after session/attestation awaits, then seal
1256            // under the same credential read lock. Explicit per-request API
1257            // keys are immutable and independent of managed defaults.
1258            let sealed = self.session_manager.admit_if_credential_is_current(
1259                auth.fence().or_else(|| {
1260                    anonymous_generation
1261                        .map(|generation| CredentialFence::Generation { generation })
1262                }),
1263                || {
1264                    self.transport_v2
1265                        .seal_encoded(&session, &plaintext)
1266                        .map_err(transport_error)
1267                },
1268            )?;
1269            // Reserve only an actual inference HTTP send. Session recovery
1270            // must share this ceiling with the caller's outer retry layer.
1271            if let Some(send_budget) = options.inference_send_budget {
1272                if !send_budget.try_reserve_send() {
1273                    return Err(Error::Other(
1274                        "Inference request send budget exhausted".to_string(),
1275                    ));
1276                }
1277            }
1278            match self.transport_v2.send_sealed(sealed).await {
1279                Ok(events) => {
1280                    drop(auth);
1281                    drop(plaintext);
1282                    // Once encrypted response processing begins, neither
1283                    // authentication/framing errors nor partial bodies replay.
1284                    return response_from_events(
1285                        events,
1286                        Some((Arc::clone(&self.transport_session), session)),
1287                    )
1288                    .await;
1289                }
1290                Err(error) => {
1291                    if should_retire_transport_session(&error) {
1292                        self.clear_transport_session_if(&session)?;
1293                    }
1294                    if permits_recovery
1295                        && !recovery_used
1296                        && options
1297                            .inference_send_budget
1298                            .is_none_or(|send_budget| send_budget.remaining() > 0)
1299                        && matches!(error, TransportV2Error::SessionRecoveryHint(_))
1300                    {
1301                        recovery_used = true;
1302                        continue;
1303                    }
1304                    return Err(transport_error(error));
1305                }
1306            }
1307        }
1308    }
1309
1310    async fn send_resumption_request(
1311        &self,
1312        endpoint: &str,
1313        auth: ResolvedAuth,
1314        body: Option<Bytes>,
1315    ) -> Result<InferenceResponse> {
1316        let headers = if body.is_some() {
1317            vec![LogicalHeader::new(
1318                header::CONTENT_TYPE.as_str().to_string(),
1319                "application/json".to_string(),
1320            )
1321            .map_err(transport_error)?]
1322        } else {
1323            Vec::new()
1324        };
1325        self.send_logical_request(
1326            http::Method::POST,
1327            endpoint.to_string(),
1328            headers,
1329            body,
1330            auth,
1331            true,
1332        )
1333        .await
1334    }
1335
1336    async fn resolve_auth_after_preflight(
1337        &self,
1338        auth_mode: AuthHeaderMode,
1339    ) -> Result<ResolvedAuth> {
1340        let initial = self.resolve_auth(auth_mode)?;
1341        if matches!(
1342            initial.source,
1343            CredentialSource::StoredApiKey { .. } | CredentialSource::ExplicitApiKey
1344        ) || !self.auth_needs_preflight_refresh(&initial)?
1345        {
1346            return Ok(initial);
1347        }
1348
1349        let _refresh_guard = self.refresh_lock.lock().await;
1350        let current = self.resolve_auth(auth_mode)?;
1351        if current == initial && self.auth_needs_preflight_refresh(&current)? {
1352            self.refresh_token_inner().await?;
1353        }
1354        self.resolve_auth(auth_mode)
1355    }
1356
1357    fn auth_needs_preflight_refresh(&self, auth: &ResolvedAuth) -> Result<bool> {
1358        let Some(token) = auth.token.as_deref() else {
1359            return Ok(false);
1360        };
1361        let now = SystemTime::now()
1362            .duration_since(UNIX_EPOCH)
1363            .map_err(|_| Error::Authentication("System clock is before Unix epoch".to_string()))?
1364            .as_secs();
1365        Ok(access_token_needs_refresh(token, now))
1366    }
1367
1368    /// Sends a lossless request to an allowed OpenSecret inference endpoint.
1369    ///
1370    /// The complete logical request, including its selected credential, is
1371    /// authenticated inside one Transport V2 envelope. No outer credential is
1372    /// emitted. One marked outer session-recovery error may re-establish the
1373    /// attested session and resend the captured request with a fresh request
1374    /// ID. No other failure triggers replay, and there is no V1 downgrade.
1375    pub async fn send_inference_request(
1376        &self,
1377        request: InferenceRequest,
1378    ) -> Result<InferenceResponse> {
1379        self.send_inference_request_with_budget(request, InferenceSendBudget::new(2)?)
1380            .await
1381    }
1382
1383    /// Sends an inference request while sharing a caller-owned send budget.
1384    ///
1385    /// Only inference HTTP sends consume this request-local budget. Attestation
1386    /// and proactive token refresh do not consume it, and callers can share it
1387    /// across their own retry layers.
1388    pub async fn send_inference_request_with_budget(
1389        &self,
1390        request: InferenceRequest,
1391        send_budget: InferenceSendBudget,
1392    ) -> Result<InferenceResponse> {
1393        let auth = self
1394            .resolve_auth_after_preflight(AuthHeaderMode::ApiKeyOrJwt)
1395            .await?;
1396        self.send_inference_request_with_auth(request, auth, send_budget)
1397            .await
1398    }
1399
1400    /// Sends one inference request with an explicit per-request API key.
1401    ///
1402    /// This is intended for multiplexing callers such as maple-proxy. The key
1403    /// is placed only inside the encrypted request and is not retained by the
1404    /// client or installed as its default credential.
1405    pub async fn send_inference_request_with_api_key(
1406        &self,
1407        request: InferenceRequest,
1408        api_key: String,
1409    ) -> Result<InferenceResponse> {
1410        let credential = ResolvedAuth {
1411            token: Some(api_key),
1412            source: CredentialSource::ExplicitApiKey,
1413        };
1414        self.send_inference_request_with_auth(request, credential, InferenceSendBudget::new(2)?)
1415            .await
1416    }
1417
1418    async fn send_inference_request_with_auth(
1419        &self,
1420        request: InferenceRequest,
1421        auth: ResolvedAuth,
1422        send_budget: InferenceSendBudget,
1423    ) -> Result<InferenceResponse> {
1424        let (parts, body) = request.into_parts();
1425        if parts.uri.scheme().is_some() || parts.uri.authority().is_some() {
1426            return Err(Error::Configuration(
1427                "Inference request URI must be relative".to_string(),
1428            ));
1429        }
1430        if !is_allowed_inference_endpoint(&parts.method, parts.uri.path()) {
1431            return Err(Error::Configuration(format!(
1432                "Inference endpoint is not allowed: {} {}",
1433                parts.method,
1434                parts.uri.path()
1435            )));
1436        }
1437        let target = parts
1438            .uri
1439            .path_and_query()
1440            .ok_or_else(|| Error::Configuration("Inference request URI has no path".to_string()))?
1441            .as_str()
1442            .to_string();
1443        let headers = sanitize_inference_request_headers(&parts.headers)
1444            .iter()
1445            .map(|(name, value)| {
1446                let value = value.to_str().map_err(|_| {
1447                    Error::Configuration("Inference header value was not textual".to_string())
1448                })?;
1449                LogicalHeader::new(name.as_str().to_string(), value.to_string())
1450                    .map_err(transport_error)
1451            })
1452            .collect::<Result<Vec<_>>>()?;
1453        let body = if parts.method == http::Method::GET && body.is_empty() {
1454            None
1455        } else {
1456            Some(body)
1457        };
1458        let response = self
1459            .send_logical_request_with_options(
1460                parts.method,
1461                target,
1462                headers,
1463                body,
1464                auth,
1465                LogicalRequestOptions {
1466                    include_cache_namespace: true,
1467                    inference_send_budget: Some(&send_budget),
1468                },
1469            )
1470            .await?;
1471        let (mut parts, body) = response.into_parts();
1472        parts.headers = sanitize_inference_response_headers(&parts.headers);
1473        Ok(HttpResponse::from_parts(parts, body))
1474    }
1475
1476    /// Typed compatibility wrapper over the lossless inference transport.
1477    async fn encrypted_openai_call<T: Serialize, U: DeserializeOwned>(
1478        &self,
1479        endpoint: &str,
1480        method: &str,
1481        data: Option<T>,
1482    ) -> Result<U> {
1483        let method = http::Method::from_bytes(method.as_bytes()).map_err(|error| {
1484            Error::Configuration(format!("Invalid inference HTTP method: {error}"))
1485        })?;
1486        let request = json_inference_request(endpoint, method, data.as_ref())?;
1487        let response = self.send_inference_request(request).await?;
1488        json_inference_response(response).await
1489    }
1490
1491    async fn encrypted_stream_call<T: Serialize>(
1492        &self,
1493        endpoint: &str,
1494        method: &str,
1495        data: Option<T>,
1496        auth_mode: AuthHeaderMode,
1497    ) -> Result<InferenceResponse> {
1498        let method = http::Method::from_bytes(method.as_bytes()).map_err(|error| {
1499            Error::Configuration(format!("Invalid streaming HTTP method: {error}"))
1500        })?;
1501        let body = data
1502            .map(|data| serde_json::to_vec(&data).map(Bytes::from))
1503            .transpose()?;
1504        let mut headers = vec![LogicalHeader::new(
1505            header::ACCEPT.as_str().to_string(),
1506            "text/event-stream".to_string(),
1507        )
1508        .map_err(transport_error)?];
1509        if body.is_some() {
1510            headers.push(
1511                LogicalHeader::new(
1512                    header::CONTENT_TYPE.as_str().to_string(),
1513                    "application/json".to_string(),
1514                )
1515                .map_err(transport_error)?,
1516            );
1517        }
1518        let auth = self.resolve_auth_after_preflight(auth_mode).await?;
1519        self.send_logical_request(method, endpoint.to_string(), headers, body, auth, false)
1520            .await
1521    }
1522
1523    fn resolve_auth(&self, auth_mode: AuthHeaderMode) -> Result<ResolvedAuth> {
1524        let credentials = self.session_manager.get_credential_snapshot()?;
1525        match auth_mode {
1526            AuthHeaderMode::None => Ok(ResolvedAuth {
1527                token: None,
1528                source: CredentialSource::Anonymous,
1529            }),
1530            AuthHeaderMode::Jwt => Ok(ResolvedAuth {
1531                token: credentials
1532                    .tokens
1533                    .as_ref()
1534                    .map(|tokens| tokens.access_token.clone()),
1535                source: CredentialSource::StoredAccessToken {
1536                    generation: credentials.token_generation,
1537                },
1538            }),
1539            AuthHeaderMode::ApiKeyOrJwt => {
1540                if let Some(api_key) = credentials.api_key {
1541                    Ok(ResolvedAuth {
1542                        token: Some(api_key),
1543                        source: CredentialSource::StoredApiKey {
1544                            generation: credentials.api_key_generation,
1545                        },
1546                    })
1547                } else {
1548                    Ok(ResolvedAuth {
1549                        token: credentials.tokens.map(|tokens| tokens.access_token),
1550                        source: CredentialSource::StoredAccessToken {
1551                            generation: credentials.token_generation,
1552                        },
1553                    })
1554                }
1555            }
1556        }
1557    }
1558
1559    // Auth Methods
1560    pub async fn login(
1561        &self,
1562        email: String,
1563        password: String,
1564        client_id: Uuid,
1565    ) -> Result<LoginResponse> {
1566        let credentials = LoginCredentials {
1567            email: Some(email),
1568            id: None,
1569            password,
1570            client_id,
1571        };
1572
1573        let response: LoginResponse = self
1574            .encrypted_api_call("/login", "POST", Some(credentials))
1575            .await?;
1576
1577        // Store the tokens
1578        self.session_manager.set_tokens(
1579            response.access_token.clone(),
1580            Some(response.refresh_token.clone()),
1581        )?;
1582
1583        Ok(response)
1584    }
1585
1586    pub async fn login_with_id(
1587        &self,
1588        id: Uuid,
1589        password: String,
1590        client_id: Uuid,
1591    ) -> Result<LoginResponse> {
1592        let credentials = LoginCredentials {
1593            email: None,
1594            id: Some(id),
1595            password,
1596            client_id,
1597        };
1598
1599        let response: LoginResponse = self
1600            .encrypted_api_call("/login", "POST", Some(credentials))
1601            .await?;
1602
1603        // Store the tokens
1604        self.session_manager.set_tokens(
1605            response.access_token.clone(),
1606            Some(response.refresh_token.clone()),
1607        )?;
1608
1609        Ok(response)
1610    }
1611
1612    pub async fn register(
1613        &self,
1614        email: String,
1615        password: String,
1616        client_id: Uuid,
1617        name: Option<String>,
1618    ) -> Result<LoginResponse> {
1619        let credentials = RegisterCredentials {
1620            email: Some(email),
1621            name,
1622            password,
1623            client_id,
1624        };
1625
1626        let response: LoginResponse = self
1627            .encrypted_api_call("/register", "POST", Some(credentials))
1628            .await?;
1629
1630        // Store the tokens
1631        self.session_manager.set_tokens(
1632            response.access_token.clone(),
1633            Some(response.refresh_token.clone()),
1634        )?;
1635
1636        Ok(response)
1637    }
1638
1639    pub async fn register_guest(&self, password: String, client_id: Uuid) -> Result<LoginResponse> {
1640        let credentials = RegisterCredentials {
1641            email: None,
1642            name: None,
1643            password,
1644            client_id,
1645        };
1646
1647        let response: LoginResponse = self
1648            .encrypted_api_call("/register", "POST", Some(credentials))
1649            .await?;
1650
1651        // Store the tokens
1652        self.session_manager.set_tokens(
1653            response.access_token.clone(),
1654            Some(response.refresh_token.clone()),
1655        )?;
1656
1657        Ok(response)
1658    }
1659
1660    // OAuth Methods
1661
1662    pub async fn initiate_github_auth(
1663        &self,
1664        client_id: Uuid,
1665        invite_code: Option<String>,
1666    ) -> Result<GithubAuthResponse> {
1667        let request = OAuthInitRequest {
1668            client_id,
1669            invite_code,
1670        };
1671        self.encrypted_api_call("/auth/github", "POST", Some(request))
1672            .await
1673    }
1674
1675    pub async fn handle_github_callback(
1676        &self,
1677        code: String,
1678        state: String,
1679        invite_code: String,
1680    ) -> Result<LoginResponse> {
1681        let request = OAuthCallbackRequest {
1682            code,
1683            state,
1684            invite_code,
1685        };
1686
1687        let response: LoginResponse = self
1688            .encrypted_api_call("/auth/github/callback", "POST", Some(request))
1689            .await?;
1690
1691        self.session_manager.set_tokens(
1692            response.access_token.clone(),
1693            Some(response.refresh_token.clone()),
1694        )?;
1695
1696        Ok(response)
1697    }
1698
1699    pub async fn initiate_google_auth(
1700        &self,
1701        client_id: Uuid,
1702        invite_code: Option<String>,
1703    ) -> Result<GoogleAuthResponse> {
1704        let request = OAuthInitRequest {
1705            client_id,
1706            invite_code,
1707        };
1708        self.encrypted_api_call("/auth/google", "POST", Some(request))
1709            .await
1710    }
1711
1712    pub async fn handle_google_callback(
1713        &self,
1714        code: String,
1715        state: String,
1716        invite_code: String,
1717    ) -> Result<LoginResponse> {
1718        let request = OAuthCallbackRequest {
1719            code,
1720            state,
1721            invite_code,
1722        };
1723
1724        let response: LoginResponse = self
1725            .encrypted_api_call("/auth/google/callback", "POST", Some(request))
1726            .await?;
1727
1728        self.session_manager.set_tokens(
1729            response.access_token.clone(),
1730            Some(response.refresh_token.clone()),
1731        )?;
1732
1733        Ok(response)
1734    }
1735
1736    pub async fn initiate_apple_auth(
1737        &self,
1738        client_id: Uuid,
1739        invite_code: Option<String>,
1740    ) -> Result<AppleAuthResponse> {
1741        let request = OAuthInitRequest {
1742            client_id,
1743            invite_code,
1744        };
1745        self.encrypted_api_call("/auth/apple", "POST", Some(request))
1746            .await
1747    }
1748
1749    pub async fn handle_apple_callback(
1750        &self,
1751        code: String,
1752        state: String,
1753        invite_code: String,
1754    ) -> Result<LoginResponse> {
1755        let request = OAuthCallbackRequest {
1756            code,
1757            state,
1758            invite_code,
1759        };
1760
1761        let response: LoginResponse = self
1762            .encrypted_api_call("/auth/apple/callback", "POST", Some(request))
1763            .await?;
1764
1765        self.session_manager.set_tokens(
1766            response.access_token.clone(),
1767            Some(response.refresh_token.clone()),
1768        )?;
1769
1770        Ok(response)
1771    }
1772
1773    #[allow(clippy::too_many_arguments)]
1774    pub async fn handle_apple_native_sign_in(
1775        &self,
1776        user_identifier: String,
1777        identity_token: String,
1778        client_id: Uuid,
1779        email: Option<String>,
1780        given_name: Option<String>,
1781        family_name: Option<String>,
1782        nonce: Option<String>,
1783        invite_code: Option<String>,
1784    ) -> Result<LoginResponse> {
1785        let request = AppleNativeSignInRequest {
1786            user_identifier,
1787            identity_token,
1788            client_id,
1789            email,
1790            given_name,
1791            family_name,
1792            nonce,
1793            invite_code,
1794        };
1795
1796        let response: LoginResponse = self
1797            .encrypted_api_call("/auth/apple/native", "POST", Some(request))
1798            .await?;
1799
1800        self.session_manager.set_tokens(
1801            response.access_token.clone(),
1802            Some(response.refresh_token.clone()),
1803        )?;
1804
1805        Ok(response)
1806    }
1807
1808    async fn refresh_token_inner(&self) -> Result<()> {
1809        let credentials = self.session_manager.get_credential_snapshot()?;
1810        let refresh_token = credentials
1811            .tokens
1812            .as_ref()
1813            .and_then(|tokens| tokens.refresh_token.clone())
1814            .ok_or_else(|| Error::Authentication("No refresh token available".to_string()))?;
1815
1816        // Refresh is authorized by the resumption credential inside the
1817        // encrypted envelope. Its logical body is deliberately absent.
1818        let token_generation = credentials.token_generation;
1819        let auth = ResolvedAuth {
1820            token: Some(refresh_token),
1821            source: CredentialSource::StoredRefreshToken {
1822                generation: token_generation,
1823            },
1824        };
1825        let response = self.send_resumption_request("/refresh", auth, None).await?;
1826        let status = response.status();
1827        let body = collect_response_body(response.into_body()).await?;
1828        self.apply_authenticated_refresh_response(token_generation, status, &body)
1829    }
1830
1831    fn apply_authenticated_refresh_response(
1832        &self,
1833        expected_token_generation: u64,
1834        status: http::StatusCode,
1835        body: &[u8],
1836    ) -> Result<()> {
1837        if !status.is_success() {
1838            if matches!(status.as_u16(), 401 | 403) {
1839                self.session_manager
1840                    .clear_tokens_if_generation(expected_token_generation)?;
1841            }
1842            return Err(Error::Api {
1843                status: status.as_u16(),
1844                message: String::from_utf8_lossy(body).into_owned(),
1845            });
1846        }
1847        let response: RefreshResponse = serde_json::from_slice(body)?;
1848
1849        // A synchronous set_tokens or a logout/clear may have replaced these
1850        // credentials while the HTTP refresh was in flight. Drop this stale
1851        // response instead of reinstalling credentials the caller superseded.
1852        self.session_manager.set_tokens_if_generation(
1853            expected_token_generation,
1854            response.access_token,
1855            Some(response.refresh_token),
1856        )?;
1857
1858        Ok(())
1859    }
1860
1861    pub async fn refresh_token(&self) -> Result<()> {
1862        let _refresh_guard = self.refresh_lock.lock().await;
1863        self.refresh_token_inner().await
1864    }
1865
1866    async fn logout_inner(&self, push_device_id: Option<Uuid>) -> Result<()> {
1867        // Serialize logout with refresh so an internal token rotation cannot
1868        // race the clear. Application-supplied credentials remain lock-free
1869        // and win through the generation check below.
1870        let _refresh_guard = self.refresh_lock.lock().await;
1871        let credentials = self.session_manager.get_credential_snapshot()?;
1872        let refresh_token = credentials
1873            .tokens
1874            .as_ref()
1875            .and_then(|tokens| tokens.refresh_token.clone())
1876            .ok_or_else(|| Error::Authentication("No refresh token available".to_string()))?;
1877
1878        let request = LogoutRequest {
1879            refresh_token: refresh_token.clone(),
1880            push_device_id,
1881        };
1882        let body = Bytes::from(serde_json::to_vec(&request)?);
1883        let auth = ResolvedAuth {
1884            token: Some(refresh_token),
1885            source: CredentialSource::StoredRefreshToken {
1886                generation: credentials.token_generation,
1887            },
1888        };
1889        let response = self
1890            .send_resumption_request("/logout", auth, Some(body))
1891            .await?;
1892        let status = response.status();
1893        let body = collect_response_body(response.into_body()).await?;
1894        if !status.is_success() {
1895            return Err(Error::Api {
1896                status: status.as_u16(),
1897                message: String::from_utf8_lossy(&body).into_owned(),
1898            });
1899        }
1900
1901        // Do not clear credentials installed by the application while the
1902        // logout request was in flight (for example, a rapid account switch).
1903        self.session_manager
1904            .clear_all_if_generation(credentials.generation)?;
1905
1906        Ok(())
1907    }
1908
1909    pub async fn logout(&self) -> Result<()> {
1910        self.logout_inner(None).await
1911    }
1912
1913    pub async fn logout_with_push_device_id(&self, push_device_id: Uuid) -> Result<()> {
1914        self.logout_inner(Some(push_device_id)).await
1915    }
1916
1917    pub fn get_access_token(&self) -> Result<Option<String>> {
1918        self.session_manager.get_access_token()
1919    }
1920
1921    /// Return one coherent snapshot of the current JWT token pair.
1922    ///
1923    /// Prefer this over separate access- and refresh-token reads when the pair
1924    /// will be persisted or copied into another client: an automatic refresh
1925    /// can replace both values between two independent lock acquisitions.
1926    pub fn get_tokens(&self) -> Result<Option<TokenPair>> {
1927        self.session_manager.get_tokens()
1928    }
1929
1930    pub fn get_refresh_token(&self) -> Result<Option<String>> {
1931        self.session_manager.get_refresh_token()
1932    }
1933
1934    pub fn set_tokens(&self, access_token: String, refresh_token: Option<String>) -> Result<()> {
1935        self.session_manager.set_tokens(access_token, refresh_token)
1936    }
1937
1938    // User Profile API
1939    pub async fn get_user(&self) -> Result<UserResponse> {
1940        self.authenticated_api_call("/protected/user", "GET", None::<()>)
1941            .await
1942    }
1943
1944    pub async fn register_push_device(
1945        &self,
1946        request: RegisterPushDeviceRequest,
1947    ) -> Result<PushDevice> {
1948        self.authenticated_api_call("/v1/push/devices", "POST", Some(request))
1949            .await
1950    }
1951
1952    pub async fn list_push_devices(&self) -> Result<PushDeviceListResponse> {
1953        self.authenticated_api_call("/v1/push/devices", "GET", None::<()>)
1954            .await
1955    }
1956
1957    pub async fn revoke_push_device(&self, id: Uuid) -> Result<DeletedPushDeviceResponse> {
1958        self.authenticated_api_call(&format!("/v1/push/devices/{}", id), "DELETE", None::<()>)
1959            .await
1960    }
1961
1962    // API Key Management
1963    pub async fn create_api_key(&self, name: String) -> Result<ApiKeyCreateResponse> {
1964        let request = ApiKeyCreateRequest { name };
1965        self.authenticated_api_call("/protected/api-keys", "POST", Some(request))
1966            .await
1967    }
1968
1969    pub async fn list_api_keys(&self) -> Result<Vec<ApiKey>> {
1970        let response: ApiKeyListResponse = self
1971            .authenticated_api_call("/protected/api-keys", "GET", None::<()>)
1972            .await?;
1973
1974        // Sort by created_at descending (newest first)
1975        let mut keys = response.keys;
1976        keys.sort_by_key(|key| std::cmp::Reverse(key.created_at));
1977
1978        Ok(keys)
1979    }
1980
1981    pub async fn delete_api_key(&self, name: &str) -> Result<()> {
1982        // URL-encode the name to handle special characters
1983        let encoded_name = utf8_percent_encode(name, NON_ALPHANUMERIC).to_string();
1984        let url = format!("/protected/api-keys/{}", encoded_name);
1985        let _: serde_json::Value = self
1986            .authenticated_api_call(&url, "DELETE", None::<()>)
1987            .await?;
1988        Ok(())
1989    }
1990
1991    // Private Key APIs
1992    pub async fn get_private_key(&self, options: Option<KeyOptions>) -> Result<PrivateKeyResponse> {
1993        let mut url = "/protected/private_key".to_string();
1994        if let Some(opts) = &options {
1995            let mut params = Vec::new();
1996            if let Some(path) = &opts.seed_phrase_derivation_path {
1997                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
1998                params.push(format!("seed_phrase_derivation_path={}", encoded));
1999            }
2000            if let Some(path) = &opts.private_key_derivation_path {
2001                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
2002                params.push(format!("private_key_derivation_path={}", encoded));
2003            }
2004            if !params.is_empty() {
2005                url.push('?');
2006                url.push_str(&params.join("&"));
2007            }
2008        }
2009        self.authenticated_api_call(&url, "GET", None::<()>).await
2010    }
2011
2012    pub async fn get_private_key_bytes(
2013        &self,
2014        options: Option<KeyOptions>,
2015    ) -> Result<PrivateKeyBytesResponse> {
2016        let mut url = "/protected/private_key_bytes".to_string();
2017        if let Some(opts) = &options {
2018            let mut params = Vec::new();
2019            if let Some(path) = &opts.seed_phrase_derivation_path {
2020                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
2021                params.push(format!("seed_phrase_derivation_path={}", encoded));
2022            }
2023            if let Some(path) = &opts.private_key_derivation_path {
2024                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
2025                params.push(format!("private_key_derivation_path={}", encoded));
2026            }
2027            if !params.is_empty() {
2028                url.push('?');
2029                url.push_str(&params.join("&"));
2030            }
2031        }
2032        self.authenticated_api_call(&url, "GET", None::<()>).await
2033    }
2034
2035    // Message Signing API
2036    pub async fn sign_message(
2037        &self,
2038        message_bytes: &[u8],
2039        algorithm: SigningAlgorithm,
2040        key_options: Option<KeyOptions>,
2041    ) -> Result<SignMessageResponse> {
2042        let message_base64 = BASE64.encode(message_bytes);
2043        let request = SignMessageRequest {
2044            message_base64,
2045            algorithm,
2046            key_options: key_options.map(|opts| SigningKeyOptions {
2047                private_key_derivation_path: opts.private_key_derivation_path,
2048                seed_phrase_derivation_path: opts.seed_phrase_derivation_path,
2049            }),
2050        };
2051        self.authenticated_api_call("/protected/sign_message", "POST", Some(request))
2052            .await
2053    }
2054
2055    // Public Key API
2056    pub async fn get_public_key(
2057        &self,
2058        algorithm: SigningAlgorithm,
2059        key_options: Option<KeyOptions>,
2060    ) -> Result<PublicKeyResponse> {
2061        let mut url = format!(
2062            "/protected/public_key?algorithm={}",
2063            match algorithm {
2064                SigningAlgorithm::Schnorr => "schnorr",
2065                SigningAlgorithm::Ecdsa => "ecdsa",
2066            }
2067        );
2068        if let Some(opts) = key_options {
2069            if let Some(path) = &opts.private_key_derivation_path {
2070                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
2071                url.push_str(&format!("&private_key_derivation_path={}", encoded));
2072            }
2073            if let Some(path) = &opts.seed_phrase_derivation_path {
2074                let encoded = utf8_percent_encode(path, NON_ALPHANUMERIC).to_string();
2075                url.push_str(&format!("&seed_phrase_derivation_path={}", encoded));
2076            }
2077        }
2078        self.authenticated_api_call(&url, "GET", None::<()>).await
2079    }
2080
2081    // Third Party Token API
2082    pub async fn generate_third_party_token(
2083        &self,
2084        audience: Option<String>,
2085    ) -> Result<ThirdPartyTokenResponse> {
2086        let request = ThirdPartyTokenRequest { audience };
2087        self.authenticated_api_call("/protected/third_party_token", "POST", Some(request))
2088            .await
2089    }
2090
2091    // Encryption/Decryption APIs
2092    pub async fn encrypt_data(
2093        &self,
2094        data: String,
2095        key_options: Option<KeyOptions>,
2096    ) -> Result<EncryptDataResponse> {
2097        let request = EncryptDataRequest {
2098            data,
2099            key_options: key_options.map(|opts| EncryptionKeyOptions {
2100                private_key_derivation_path: opts.private_key_derivation_path,
2101                seed_phrase_derivation_path: opts.seed_phrase_derivation_path,
2102            }),
2103        };
2104        self.authenticated_api_call("/protected/encrypt", "POST", Some(request))
2105            .await
2106    }
2107
2108    pub async fn decrypt_data(
2109        &self,
2110        encrypted_data: String,
2111        key_options: Option<KeyOptions>,
2112    ) -> Result<String> {
2113        let request = DecryptDataRequest {
2114            encrypted_data,
2115            key_options: key_options.map(|opts| EncryptionKeyOptions {
2116                private_key_derivation_path: opts.private_key_derivation_path,
2117                seed_phrase_derivation_path: opts.seed_phrase_derivation_path,
2118            }),
2119        };
2120        self.authenticated_api_call("/protected/decrypt", "POST", Some(request))
2121            .await
2122    }
2123
2124    // Account Management APIs
2125
2126    /// Changes the password for the currently authenticated user
2127    pub async fn change_password(
2128        &self,
2129        current_password: String,
2130        new_password: String,
2131    ) -> Result<()> {
2132        let request = ChangePasswordRequest {
2133            current_password,
2134            new_password,
2135        };
2136        let response: CredentialUpdateResponse = self
2137            .authenticated_api_call("/protected/change_password", "POST", Some(request))
2138            .await?;
2139        if let Some(access_token) = response.access_token {
2140            let refresh_token = match response.refresh_token {
2141                Some(refresh_token) => Some(refresh_token),
2142                None => self.session_manager.get_refresh_token()?,
2143            };
2144            self.session_manager
2145                .set_tokens(access_token, refresh_token)?;
2146        }
2147        Ok(())
2148    }
2149
2150    /// Requests a password reset for the given email
2151    /// Note: This does not require authentication but still uses encryption
2152    pub async fn request_password_reset(
2153        &self,
2154        email: String,
2155        hashed_secret: String,
2156        client_id: Uuid,
2157    ) -> Result<()> {
2158        let request = PasswordResetRequest {
2159            email,
2160            hashed_secret,
2161            client_id,
2162        };
2163        let _: serde_json::Value = self
2164            .encrypted_api_call("/password-reset/request", "POST", Some(request))
2165            .await?;
2166        Ok(())
2167    }
2168
2169    /// Confirms a password reset with the code from email
2170    /// Note: This does not require authentication but still uses encryption
2171    pub async fn confirm_password_reset(
2172        &self,
2173        email: String,
2174        alphanumeric_code: String,
2175        plaintext_secret: String,
2176        new_password: String,
2177        client_id: Uuid,
2178    ) -> Result<()> {
2179        let request = PasswordResetConfirmRequest {
2180            email,
2181            alphanumeric_code,
2182            plaintext_secret,
2183            new_password,
2184            client_id,
2185        };
2186        let _: serde_json::Value = self
2187            .encrypted_api_call("/password-reset/confirm", "POST", Some(request))
2188            .await?;
2189        Ok(())
2190    }
2191
2192    /// Verifies an email address with the code from the verification email
2193    /// Note: This does not require authentication but still uses encryption
2194    pub async fn verify_email(&self, code: String) -> Result<()> {
2195        let _: serde_json::Value = self
2196            .encrypted_api_call(&format!("/verify-email/{}", code), "GET", None::<()>)
2197            .await?;
2198        Ok(())
2199    }
2200
2201    /// Requests a new email verification code
2202    pub async fn request_new_verification_code(&self) -> Result<()> {
2203        let _: serde_json::Value = self
2204            .authenticated_api_call("/protected/request_verification", "POST", None::<()>)
2205            .await?;
2206        Ok(())
2207    }
2208
2209    /// Initiates the account deletion process
2210    pub async fn request_account_deletion(&self, hashed_secret: String) -> Result<()> {
2211        let request = InitiateAccountDeletionRequest { hashed_secret };
2212        let _: serde_json::Value = self
2213            .authenticated_api_call("/protected/delete-account/request", "POST", Some(request))
2214            .await?;
2215        Ok(())
2216    }
2217
2218    /// Confirms account deletion with the code from email
2219    pub async fn confirm_account_deletion(
2220        &self,
2221        confirmation_code: String,
2222        plaintext_secret: String,
2223    ) -> Result<()> {
2224        let request = ConfirmAccountDeletionRequest {
2225            confirmation_code,
2226            plaintext_secret,
2227        };
2228        let _: serde_json::Value = self
2229            .authenticated_api_call("/protected/delete-account/confirm", "POST", Some(request))
2230            .await?;
2231        Ok(())
2232    }
2233
2234    // AI/OpenAI API Methods
2235
2236    /// Creates a new conversation.
2237    pub async fn create_conversation(
2238        &self,
2239        request: ConversationCreateRequest,
2240    ) -> Result<Conversation> {
2241        self.authenticated_api_call("/v1/conversations", "POST", Some(request))
2242            .await
2243    }
2244
2245    /// Lists conversations with optional filters and pagination.
2246    pub async fn list_conversations(
2247        &self,
2248        params: Option<ConversationsListParams>,
2249    ) -> Result<ConversationsListResponse> {
2250        let endpoint = build_conversations_endpoint(params.as_ref());
2251        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2252            .await
2253    }
2254
2255    /// Fetches a single conversation by UUID.
2256    pub async fn get_conversation(&self, conversation_id: Uuid) -> Result<Conversation> {
2257        self.authenticated_api_call(
2258            &format!("/v1/conversations/{}", conversation_id),
2259            "GET",
2260            None::<()>,
2261        )
2262        .await
2263    }
2264
2265    /// Partially updates a conversation.
2266    pub async fn update_conversation(
2267        &self,
2268        conversation_id: Uuid,
2269        request: ConversationUpdateRequest,
2270    ) -> Result<Conversation> {
2271        if request.is_empty() {
2272            return Err(Error::Configuration(
2273                "Conversation update request must include at least one field".to_string(),
2274            ));
2275        }
2276
2277        self.authenticated_api_call(
2278            &format!("/v1/conversations/{}", conversation_id),
2279            "POST",
2280            Some(request),
2281        )
2282        .await
2283    }
2284
2285    /// Deletes a single conversation by UUID.
2286    pub async fn delete_conversation(
2287        &self,
2288        conversation_id: Uuid,
2289    ) -> Result<DeletedObjectResponse> {
2290        self.authenticated_api_call(
2291            &format!("/v1/conversations/{}", conversation_id),
2292            "DELETE",
2293            None::<()>,
2294        )
2295        .await
2296    }
2297
2298    /// Lists items in a conversation.
2299    pub async fn list_conversation_items(
2300        &self,
2301        conversation_id: Uuid,
2302        params: Option<AgentItemsListParams>,
2303    ) -> Result<ConversationItemsResponse> {
2304        let endpoint = build_agent_items_endpoint(
2305            &format!("/v1/conversations/{}/items", conversation_id),
2306            params.as_ref(),
2307        );
2308        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2309            .await
2310    }
2311
2312    /// Fetches a single item from a conversation.
2313    pub async fn get_conversation_item(
2314        &self,
2315        conversation_id: Uuid,
2316        item_id: Uuid,
2317    ) -> Result<ConversationItem> {
2318        self.authenticated_api_call(
2319            &format!("/v1/conversations/{}/items/{}", conversation_id, item_id),
2320            "GET",
2321            None::<()>,
2322        )
2323        .await
2324    }
2325
2326    /// Deletes all conversations
2327    pub async fn delete_conversations(&self) -> Result<ConversationsDeleteResponse> {
2328        self.authenticated_api_call("/v1/conversations", "DELETE", None::<()>)
2329            .await
2330    }
2331
2332    /// Batch deletes multiple conversations by their IDs
2333    pub async fn batch_delete_conversations(
2334        &self,
2335        ids: Vec<String>,
2336    ) -> Result<BatchDeleteConversationsResponse> {
2337        let request = BatchDeleteConversationsRequest { ids };
2338        self.authenticated_api_call("/v1/conversations/batch-delete", "POST", Some(request))
2339            .await
2340    }
2341
2342    /// Batch updates conversation project assignments. Use `None` to clear the project.
2343    pub async fn batch_update_conversation_project(
2344        &self,
2345        ids: Vec<Uuid>,
2346        project_id: Option<Uuid>,
2347    ) -> Result<BatchUpdateConversationProjectResponse> {
2348        let request = BatchUpdateConversationProjectRequest { ids, project_id };
2349        self.authenticated_api_call(
2350            "/v1/conversations/batch-update-project",
2351            "POST",
2352            Some(request),
2353        )
2354        .await
2355    }
2356
2357    /// Creates a new conversation project.
2358    pub async fn create_conversation_project(
2359        &self,
2360        request: ConversationProjectCreateRequest,
2361    ) -> Result<ConversationProject> {
2362        self.authenticated_api_call("/v1/conversation-projects", "POST", Some(request))
2363            .await
2364    }
2365
2366    /// Lists conversation projects with pagination.
2367    pub async fn list_conversation_projects(
2368        &self,
2369        params: Option<ConversationProjectListParams>,
2370    ) -> Result<ConversationProjectsListResponse> {
2371        let endpoint = build_conversation_projects_endpoint(params.as_ref());
2372        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2373            .await
2374    }
2375
2376    /// Fetches a single conversation project by UUID.
2377    pub async fn get_conversation_project(&self, project_id: Uuid) -> Result<ConversationProject> {
2378        self.authenticated_api_call(
2379            &format!("/v1/conversation-projects/{}", project_id),
2380            "GET",
2381            None::<()>,
2382        )
2383        .await
2384    }
2385
2386    /// Updates a conversation project and/or its project instructions.
2387    pub async fn update_conversation_project(
2388        &self,
2389        project_id: Uuid,
2390        request: ConversationProjectUpdateRequest,
2391    ) -> Result<ConversationProject> {
2392        if request.is_empty() {
2393            return Err(Error::Configuration(
2394                "Conversation project update request must include at least one field".to_string(),
2395            ));
2396        }
2397
2398        self.authenticated_api_call(
2399            &format!("/v1/conversation-projects/{}", project_id),
2400            "POST",
2401            Some(request),
2402        )
2403        .await
2404    }
2405
2406    /// Deletes a conversation project by UUID.
2407    pub async fn delete_conversation_project(
2408        &self,
2409        project_id: Uuid,
2410    ) -> Result<DeletedObjectResponse> {
2411        self.authenticated_api_call(
2412            &format!("/v1/conversation-projects/{}", project_id),
2413            "DELETE",
2414            None::<()>,
2415        )
2416        .await
2417    }
2418
2419    /// Fetches available AI models
2420    pub async fn get_models(&self) -> Result<ModelsResponse> {
2421        self.encrypted_openai_call("/v1/models", "GET", None::<()>)
2422            .await
2423    }
2424
2425    /// Fetches the full model catalog with context windows and capabilities.
2426    pub async fn get_model_catalog(&self) -> Result<ModelCatalogResponse> {
2427        self.encrypted_openai_call("/v1/models/catalog", "GET", None::<()>)
2428            .await
2429    }
2430
2431    /// Creates embeddings for the given input text(s)
2432    ///
2433    /// # Example
2434    /// ```ignore
2435    /// let request = EmbeddingRequest {
2436    ///     input: "Hello, world!".into(),
2437    ///     model: "nomic-embed-text".to_string(),
2438    ///     encoding_format: None,
2439    ///     dimensions: None,
2440    ///     user: None,
2441    /// };
2442    /// let response = client.create_embeddings(request).await?;
2443    /// ```
2444    pub async fn create_embeddings(&self, request: EmbeddingRequest) -> Result<EmbeddingResponse> {
2445        self.encrypted_openai_call("/v1/embeddings", "POST", Some(request))
2446            .await
2447    }
2448
2449    /// Answers typed System One questions about a state with calibrated
2450    /// probabilities (`POST /v1/systemone`); see [`crate::system_one`].
2451    ///
2452    /// Uses the client's configured credential: an API key when one is set,
2453    /// otherwise the signed-in session. A rejected request is [`Error::Api`]
2454    /// with the backend's status (422 for schema problems, 413 for size limits,
2455    /// chat's statuses for quota and capacity) and body;
2456    /// [`Error::api_error_code`] reads its `system_one_*` code.
2457    pub async fn system_one(&self, request: SystemOneRequest) -> Result<SystemOneResponse> {
2458        self.encrypted_openai_call("/v1/systemone", "POST", Some(request))
2459            .await
2460    }
2461
2462    /// [`Self::system_one`] with an explicit per-request API key, encrypted
2463    /// inside this one request and not retained by the client.
2464    pub async fn system_one_with_api_key(
2465        &self,
2466        request: SystemOneRequest,
2467        api_key: String,
2468    ) -> Result<SystemOneResponse> {
2469        let request = json_inference_request("/v1/systemone", http::Method::POST, Some(&request))?;
2470        let response = self
2471            .send_inference_request_with_api_key(request, api_key)
2472            .await?;
2473        json_inference_response(response).await
2474    }
2475
2476    /// Creates a chat completion (non-streaming)
2477    pub async fn create_chat_completion(
2478        &self,
2479        mut request: ChatCompletionRequest,
2480    ) -> Result<ChatCompletionResponse> {
2481        request.stream = Some(false);
2482        self.encrypted_openai_call("/v1/chat/completions", "POST", Some(request))
2483            .await
2484    }
2485
2486    /// Creates a streaming chat completion
2487    pub async fn create_chat_completion_stream(
2488        &self,
2489        request: ChatCompletionRequest,
2490    ) -> Result<std::pin::Pin<Box<dyn futures::Stream<Item = Result<ChatCompletionChunk>> + Send>>>
2491    {
2492        use eventsource_stream::Eventsource;
2493        use futures::StreamExt;
2494
2495        let request = build_chat_completion_stream_request(request)?;
2496        let response = self.send_inference_request(request).await?;
2497        let status = response.status();
2498        if !status.is_success() {
2499            let body = collect_response_body(response.into_body()).await?;
2500            return Err(Error::Api {
2501                status: status.as_u16(),
2502                message: String::from_utf8_lossy(&body).into_owned(),
2503            });
2504        }
2505
2506        let stream = response
2507            .into_body()
2508            .map(|result| result.map_err(std::io::Error::other));
2509
2510        let event_stream = stream.eventsource().filter_map(move |event| {
2511            async move {
2512                match event {
2513                    Ok(event) => {
2514                        // Check if this is the [DONE] event
2515                        if event.data == "[DONE]" {
2516                            return None;
2517                        }
2518
2519                        match serde_json::from_str::<ChatCompletionChunk>(&event.data) {
2520                            Ok(chunk) => Some(Ok(chunk)),
2521                            Err(error) => Some(Err(Error::Api {
2522                                status: 0,
2523                                message: format!("Failed to parse chunk: {error}"),
2524                            })),
2525                        }
2526                    }
2527                    Err(error) => Some(Err(Error::Api {
2528                        status: 0,
2529                        message: format!("SSE error: {error}"),
2530                    })),
2531                }
2532            }
2533        });
2534
2535        Ok(Box::pin(event_stream))
2536    }
2537
2538    // Web API Methods
2539
2540    /// Searches the public web through OpenSecret's configured search provider.
2541    pub async fn web_search(&self, request: WebSearchRequest) -> Result<WebSearchResponse> {
2542        self.authenticated_api_call("/v1/web/search", "POST", Some(request))
2543            .await
2544    }
2545
2546    /// Extracts sanitized Markdown from public URLs through OpenSecret's configured provider.
2547    pub async fn web_extract(&self, request: WebExtractRequest) -> Result<WebExtractResponse> {
2548        self.authenticated_api_call("/v1/web/extract", "POST", Some(request))
2549            .await
2550    }
2551
2552    async fn agent_chat_stream(
2553        &self,
2554        endpoint: String,
2555        input: &str,
2556    ) -> Result<std::pin::Pin<Box<dyn futures::Stream<Item = Result<AgentSseEvent>> + Send>>> {
2557        use eventsource_stream::Eventsource;
2558        use futures::StreamExt;
2559
2560        let request = AgentChatRequest {
2561            input: input.to_string(),
2562        };
2563
2564        let response = self
2565            .encrypted_stream_call(&endpoint, "POST", Some(request), AuthHeaderMode::Jwt)
2566            .await?;
2567        let status = response.status();
2568        if !status.is_success() {
2569            let body = collect_response_body(response.into_body()).await?;
2570            return Err(Error::Api {
2571                status: status.as_u16(),
2572                message: String::from_utf8_lossy(&body).into_owned(),
2573            });
2574        }
2575
2576        let stream = response
2577            .into_body()
2578            .map(|result| result.map_err(std::io::Error::other));
2579
2580        let event_stream = stream.eventsource().filter_map(|event| async move {
2581            let event = match event {
2582                Ok(event) => event,
2583                Err(error) => {
2584                    return Some(Err(Error::Api {
2585                        status: 0,
2586                        message: format!("SSE error: {error}"),
2587                    }));
2588                }
2589            };
2590            if event.data == "[DONE]" {
2591                return None;
2592            }
2593
2594            parse_agent_sse_event(&event.event, &event.data)
2595        });
2596
2597        Ok(Box::pin(event_stream))
2598    }
2599
2600    // Agent API Methods
2601
2602    /// Fetches the current user's main agent.
2603    pub async fn get_main_agent(&self) -> Result<MainAgentResponse> {
2604        self.authenticated_api_call("/v1/agent", "GET", None::<()>)
2605            .await
2606    }
2607
2608    /// Explicitly initializes the current user's main agent.
2609    pub async fn init_main_agent(
2610        &self,
2611        request: InitMainAgentRequest,
2612    ) -> Result<InitMainAgentResponse> {
2613        self.authenticated_api_call("/v1/agent/init", "POST", Some(request))
2614            .await
2615    }
2616
2617    /// Deletes the current user's main agent and resets shared agent state.
2618    pub async fn delete_main_agent(&self) -> Result<DeletedObjectResponse> {
2619        self.authenticated_api_call("/v1/agent", "DELETE", None::<()>)
2620            .await
2621    }
2622
2623    /// Lists items in the main agent conversation.
2624    pub async fn list_main_agent_items(
2625        &self,
2626        params: Option<AgentItemsListParams>,
2627    ) -> Result<AgentItemsListResponse> {
2628        let endpoint = build_agent_items_endpoint("/v1/agent/items", params.as_ref());
2629        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2630            .await
2631    }
2632
2633    /// Fetches a single item from the main agent conversation.
2634    pub async fn get_main_agent_item(&self, item_id: Uuid) -> Result<ConversationItem> {
2635        self.authenticated_api_call(&format!("/v1/agent/items/{}", item_id), "GET", None::<()>)
2636            .await
2637    }
2638
2639    /// Sets or replaces the current user's reaction on a main-agent assistant message item.
2640    pub async fn set_main_agent_item_reaction(
2641        &self,
2642        item_id: Uuid,
2643        emoji: impl Into<String>,
2644    ) -> Result<ConversationItem> {
2645        self.authenticated_api_call(
2646            &format!("/v1/agent/items/{}/reaction", item_id),
2647            "POST",
2648            Some(SetMessageReactionRequest {
2649                emoji: emoji.into(),
2650            }),
2651        )
2652        .await
2653    }
2654
2655    /// Clears the current user's reaction on a main-agent assistant message item.
2656    pub async fn clear_main_agent_item_reaction(&self, item_id: Uuid) -> Result<ConversationItem> {
2657        self.authenticated_api_call(
2658            &format!("/v1/agent/items/{}/reaction", item_id),
2659            "DELETE",
2660            None::<()>,
2661        )
2662        .await
2663    }
2664
2665    /// Sends a message to the main agent and returns a stream of SSE events.
2666    pub async fn agent_chat(
2667        &self,
2668        input: &str,
2669    ) -> Result<std::pin::Pin<Box<dyn futures::Stream<Item = Result<AgentSseEvent>> + Send>>> {
2670        self.agent_chat_stream("/v1/agent/chat".to_string(), input)
2671            .await
2672    }
2673
2674    /// Creates a new subagent for the current user.
2675    pub async fn create_subagent(
2676        &self,
2677        request: CreateSubagentRequest,
2678    ) -> Result<SubagentResponse> {
2679        self.authenticated_api_call("/v1/agent/subagents", "POST", Some(request))
2680            .await
2681    }
2682
2683    /// Lists subagents for the current user with pagination and filtering.
2684    pub async fn list_subagents(
2685        &self,
2686        params: Option<ListSubagentsParams>,
2687    ) -> Result<SubagentListResponse> {
2688        let endpoint = build_subagents_endpoint(params.as_ref());
2689        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2690            .await
2691    }
2692
2693    /// Fetches a single subagent by UUID.
2694    pub async fn get_subagent(&self, id: Uuid) -> Result<SubagentResponse> {
2695        self.authenticated_api_call(&format!("/v1/agent/subagents/{}", id), "GET", None::<()>)
2696            .await
2697    }
2698
2699    /// Sends a message to a specific subagent and returns a stream of SSE events.
2700    pub async fn subagent_chat(
2701        &self,
2702        id: Uuid,
2703        input: &str,
2704    ) -> Result<std::pin::Pin<Box<dyn futures::Stream<Item = Result<AgentSseEvent>> + Send>>> {
2705        self.agent_chat_stream(format!("/v1/agent/subagents/{}/chat", id), input)
2706            .await
2707    }
2708
2709    /// Lists items in a subagent conversation.
2710    pub async fn list_subagent_items(
2711        &self,
2712        id: Uuid,
2713        params: Option<AgentItemsListParams>,
2714    ) -> Result<AgentItemsListResponse> {
2715        let endpoint = build_agent_items_endpoint(
2716            &format!("/v1/agent/subagents/{}/items", id),
2717            params.as_ref(),
2718        );
2719        self.authenticated_api_call(&endpoint, "GET", None::<()>)
2720            .await
2721    }
2722
2723    /// Fetches a single item from a subagent conversation.
2724    pub async fn get_subagent_item(&self, id: Uuid, item_id: Uuid) -> Result<ConversationItem> {
2725        self.authenticated_api_call(
2726            &format!("/v1/agent/subagents/{}/items/{}", id, item_id),
2727            "GET",
2728            None::<()>,
2729        )
2730        .await
2731    }
2732
2733    /// Sets or replaces the current user's reaction on a subagent assistant message item.
2734    pub async fn set_subagent_item_reaction(
2735        &self,
2736        id: Uuid,
2737        item_id: Uuid,
2738        emoji: impl Into<String>,
2739    ) -> Result<ConversationItem> {
2740        self.authenticated_api_call(
2741            &format!("/v1/agent/subagents/{}/items/{}/reaction", id, item_id),
2742            "POST",
2743            Some(SetMessageReactionRequest {
2744                emoji: emoji.into(),
2745            }),
2746        )
2747        .await
2748    }
2749
2750    /// Clears the current user's reaction on a subagent assistant message item.
2751    pub async fn clear_subagent_item_reaction(
2752        &self,
2753        id: Uuid,
2754        item_id: Uuid,
2755    ) -> Result<ConversationItem> {
2756        self.authenticated_api_call(
2757            &format!("/v1/agent/subagents/{}/items/{}/reaction", id, item_id),
2758            "DELETE",
2759            None::<()>,
2760        )
2761        .await
2762    }
2763
2764    /// Deletes a subagent by UUID.
2765    pub async fn delete_subagent(&self, id: Uuid) -> Result<DeletedObjectResponse> {
2766        self.authenticated_api_call(&format!("/v1/agent/subagents/{}", id), "DELETE", None::<()>)
2767            .await
2768    }
2769}
2770
2771#[cfg(test)]
2772mod tests {
2773    use super::*;
2774    use crate::transport_v2::client::{SessionResponder, TestV2ServerState};
2775    use futures::stream;
2776    use wiremock::{
2777        matchers::{method, path},
2778        Mock, MockServer, ResponseTemplate,
2779    };
2780
2781    fn encoded_timing_token(exp: u64) -> String {
2782        let payload = URL_SAFE_NO_PAD.encode(serde_json::json!({ "exp": exp }).to_string());
2783        format!("header.{payload}.signature")
2784    }
2785
2786    fn untrusted_handoff_grant(session_id: &str, request_id: &str) -> NativeOAuthHandoffGrant {
2787        let payload = URL_SAFE_NO_PAD
2788            .encode(serde_json::json!({ "sid": session_id, "rid": request_id }).to_string());
2789        NativeOAuthHandoffGrant::new(format!("e30.{payload}.c2ln")).unwrap()
2790    }
2791
2792    fn response_events(
2793        events: Vec<std::result::Result<ResponseEvent, TransportV2Error>>,
2794    ) -> ResponseEventStream {
2795        Box::pin(stream::iter(events))
2796    }
2797
2798    async fn mount_delayed_session_with_no_request(server: &MockServer, server_secret: [u8; 32]) {
2799        Mock::given(method("POST"))
2800            .and(path("/v2/session"))
2801            .respond_with(SessionResponder {
2802                server_secret,
2803                state: None,
2804                delay: Some(std::time::Duration::from_millis(500)),
2805            })
2806            .expect(1)
2807            .mount(server)
2808            .await;
2809        Mock::given(method("POST"))
2810            .and(path("/v2/request"))
2811            .respond_with(ResponseTemplate::new(500))
2812            .expect(0)
2813            .mount(server)
2814            .await;
2815    }
2816
2817    async fn wait_until_session_establishment_is_in_flight(server: &MockServer) {
2818        tokio::time::timeout(std::time::Duration::from_secs(2), async {
2819            loop {
2820                if server.received_requests().await.is_some_and(|requests| {
2821                    requests
2822                        .iter()
2823                        .any(|request| request.url.path() == "/v2/session")
2824                }) {
2825                    return;
2826                }
2827                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
2828            }
2829        })
2830        .await
2831        .expect("session establishment request was not observed");
2832    }
2833
2834    #[test]
2835    fn cache_namespace_root_round_trips_without_debug_disclosure() {
2836        let root = TransportV2CacheNamespaceRoot::from_bytes([42; 32]);
2837        let encoded = root.to_base64();
2838
2839        assert_eq!(
2840            TransportV2CacheNamespaceRoot::from_base64(&encoded).unwrap(),
2841            root
2842        );
2843        assert_eq!(
2844            format!("{root:?}"),
2845            "TransportV2CacheNamespaceRoot([REDACTED])"
2846        );
2847        assert!(!format!("{root:?}").contains(&encoded));
2848    }
2849
2850    #[test]
2851    fn cache_namespace_root_rejects_noncanonical_or_wrong_length_base64() {
2852        let canonical = BASE64.encode([42; 32]);
2853
2854        assert!(
2855            TransportV2CacheNamespaceRoot::from_base64(canonical.trim_end_matches('=')).is_err()
2856        );
2857        assert!(TransportV2CacheNamespaceRoot::from_base64(&BASE64.encode([42; 31])).is_err());
2858    }
2859
2860    #[test]
2861    fn native_handoff_grant_is_canonical_bounded_and_redacted() {
2862        let grant = NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap();
2863        assert_eq!(format!("{grant:?}"), "NativeOAuthHandoffGrant([REDACTED])");
2864        for invalid in [
2865            "",
2866            "one.two",
2867            "one.two.three.four",
2868            "e30=.e30.c2ln",
2869            "e30.e30.bad+alphabet",
2870        ] {
2871            assert!(NativeOAuthHandoffGrant::new(invalid).is_err(), "{invalid}");
2872        }
2873        assert!(NativeOAuthHandoffGrant::new(format!(
2874            "{}.e30.c2ln",
2875            "a".repeat(MAX_NATIVE_OAUTH_HANDOFF_GRANT_BYTES)
2876        ))
2877        .is_err());
2878    }
2879
2880    #[tokio::test]
2881    async fn prepared_handoff_filters_mismatched_untrusted_grant_targets_locally() {
2882        let server = MockServer::start().await;
2883        Mock::given(method("POST"))
2884            .and(path("/v2/session"))
2885            .respond_with(SessionResponder {
2886                server_secret: [0x89; 32],
2887                state: None,
2888                delay: None,
2889            })
2890            .expect(1)
2891            .mount(&server)
2892            .await;
2893
2894        let client = OpenSecretClient::new(server.uri()).unwrap();
2895        let first = client.prepare_native_oauth_handoff().await.unwrap();
2896        let second = client.prepare_native_oauth_handoff().await.unwrap();
2897        let stale_first_grant = untrusted_handoff_grant(first.session_id(), first.request_id());
2898
2899        assert!(first.matches_untrusted_grant_target(&stale_first_grant));
2900        assert!(
2901            !second.matches_untrusted_grant_target(&stale_first_grant),
2902            "an A callback must not consume a newer B request"
2903        );
2904        assert!(
2905            second.matches_untrusted_grant_target(&untrusted_handoff_grant(
2906                second.session_id(),
2907                second.request_id()
2908            ))
2909        );
2910        assert!(!second.matches_untrusted_grant_target(
2911            &NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap()
2912        ));
2913    }
2914
2915    #[tokio::test]
2916    async fn native_handoff_redeems_the_advertised_request_once_without_outer_secrets() {
2917        let server = MockServer::start().await;
2918        let state = TestV2ServerState::new();
2919        let user_id = Uuid::new_v4();
2920        state.queue_json_response(
2921            200,
2922            serde_json::json!({
2923                "id": user_id,
2924                "email": "native@example.com",
2925                "access_token": "native-access",
2926                "refresh_token": "native-refresh",
2927            }),
2928        );
2929        Mock::given(method("POST"))
2930            .and(path("/v2/session"))
2931            .respond_with(SessionResponder {
2932                server_secret: [0x8a; 32],
2933                state: Some(state.clone()),
2934                delay: None,
2935            })
2936            .expect(1)
2937            .mount(&server)
2938            .await;
2939        Mock::given(method("POST"))
2940            .and(path("/v2/request"))
2941            .respond_with(state.request_responder())
2942            .expect(1)
2943            .mount(&server)
2944            .await;
2945
2946        let client = OpenSecretClient::new(server.uri()).unwrap();
2947        let prepared = client.prepare_native_oauth_handoff().await.unwrap();
2948        let advertised_session_id = prepared.session_id().to_string();
2949        let advertised_request_id = prepared.request_id().to_string();
2950        for id in [&advertised_session_id, &advertised_request_id] {
2951            assert_eq!(id.len(), 32);
2952            assert!(id
2953                .bytes()
2954                .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f')));
2955        }
2956
2957        let response = client
2958            .redeem_native_oauth_handoff(
2959                prepared,
2960                NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap(),
2961            )
2962            .await
2963            .unwrap();
2964        assert_eq!(response.id, user_id);
2965        let tokens = client.get_tokens().unwrap().unwrap();
2966        assert_eq!(tokens.access_token, "native-access");
2967        assert_eq!(tokens.refresh_token.as_deref(), Some("native-refresh"));
2968
2969        let logical = state.captured_requests();
2970        assert_eq!(logical.len(), 1);
2971        assert_eq!(logical[0]["version"], 2);
2972        assert_eq!(logical[0]["credential"], serde_json::Value::Null);
2973        assert_eq!(logical[0]["cache_namespace_root"], serde_json::Value::Null);
2974        assert_eq!(logical[0]["method"], "POST");
2975        assert_eq!(logical[0]["target"], "/auth/native-handoff/redeem");
2976        assert_eq!(logical[0]["body_present"], true);
2977        assert_eq!(logical[0]["headers"].as_array().unwrap().len(), 1);
2978        assert_eq!(logical[0]["headers"][0]["name"], "content-type");
2979        assert_eq!(logical[0]["headers"][0]["value"], "application/json");
2980        assert_eq!(state.captured_request_ids(), vec![advertised_request_id]);
2981        let bodies = state.captured_request_bodies();
2982        assert_eq!(bodies.len(), 1);
2983        assert_eq!(
2984            serde_json::from_slice::<serde_json::Value>(&bodies[0]).unwrap(),
2985            serde_json::json!({ "grant": "e30.e30.c2ln" })
2986        );
2987
2988        let outer = server.received_requests().await.unwrap();
2989        assert_eq!(outer.len(), 2);
2990        assert_eq!(outer[1].url.path(), "/v2/request");
2991        assert_eq!(
2992            outer[1].headers.get("x-session-id").unwrap(),
2993            advertised_session_id.as_str()
2994        );
2995        assert!(!outer[1].headers.contains_key(header::AUTHORIZATION));
2996        assert!(!outer[1].headers.contains_key(header::COOKIE));
2997        for secret in ["e30.e30.c2ln", "native-access", "native-refresh"] {
2998            assert!(!outer[1]
2999                .body
3000                .windows(secret.len())
3001                .any(|window| window == secret.as_bytes()));
3002        }
3003    }
3004
3005    #[tokio::test]
3006    async fn native_handoff_rejects_stale_anonymous_generation_before_network_use() {
3007        let server = MockServer::start().await;
3008        Mock::given(method("POST"))
3009            .and(path("/v2/session"))
3010            .respond_with(SessionResponder {
3011                server_secret: [0x8b; 32],
3012                state: None,
3013                delay: None,
3014            })
3015            .expect(1)
3016            .mount(&server)
3017            .await;
3018        Mock::given(method("POST"))
3019            .and(path("/v2/request"))
3020            .respond_with(ResponseTemplate::new(500))
3021            .expect(0)
3022            .mount(&server)
3023            .await;
3024
3025        let client = OpenSecretClient::new(server.uri()).unwrap();
3026        let prepared = client.prepare_native_oauth_handoff().await.unwrap();
3027        client
3028            .set_tokens("new-access".to_string(), Some("new-refresh".to_string()))
3029            .unwrap();
3030        assert!(matches!(
3031            client
3032                .redeem_native_oauth_handoff(
3033                    prepared,
3034                    NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap(),
3035                )
3036                .await,
3037            Err(Error::Authentication(message))
3038                if message == "Authentication changed during native OAuth handoff"
3039        ));
3040        assert_eq!(server.received_requests().await.unwrap().len(), 1);
3041    }
3042
3043    #[tokio::test]
3044    async fn native_handoff_rejects_a_replaced_transport_session_before_network_use() {
3045        let server = MockServer::start().await;
3046        Mock::given(method("POST"))
3047            .and(path("/v2/session"))
3048            .respond_with(SessionResponder {
3049                server_secret: [0x8c; 32],
3050                state: None,
3051                delay: None,
3052            })
3053            .expect(2)
3054            .mount(&server)
3055            .await;
3056        Mock::given(method("POST"))
3057            .and(path("/v2/request"))
3058            .respond_with(ResponseTemplate::new(500))
3059            .expect(0)
3060            .mount(&server)
3061            .await;
3062
3063        let client = OpenSecretClient::new(server.uri()).unwrap();
3064        let prepared = client.prepare_native_oauth_handoff().await.unwrap();
3065        client.perform_attestation_handshake().await.unwrap();
3066        assert!(matches!(
3067            client
3068                .redeem_native_oauth_handoff(
3069                    prepared,
3070                    NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap(),
3071                )
3072                .await,
3073            Err(Error::Session(message))
3074                if message == "Native OAuth transport session is no longer current"
3075        ));
3076        assert_eq!(server.received_requests().await.unwrap().len(), 2);
3077    }
3078
3079    #[tokio::test]
3080    async fn native_handoff_response_cannot_overwrite_credentials_changed_in_flight() {
3081        let server = MockServer::start().await;
3082        let state = TestV2ServerState::new();
3083        state.queue_delayed_json_response(
3084            200,
3085            serde_json::json!({
3086                "id": Uuid::new_v4(),
3087                "email": "stale@example.com",
3088                "access_token": "stale-access",
3089                "refresh_token": "stale-refresh",
3090            }),
3091            std::time::Duration::from_millis(500),
3092        );
3093        Mock::given(method("POST"))
3094            .and(path("/v2/session"))
3095            .respond_with(SessionResponder {
3096                server_secret: [0x8d; 32],
3097                state: Some(state.clone()),
3098                delay: None,
3099            })
3100            .expect(1)
3101            .mount(&server)
3102            .await;
3103        Mock::given(method("POST"))
3104            .and(path("/v2/request"))
3105            .respond_with(state.request_responder())
3106            .expect(1)
3107            .mount(&server)
3108            .await;
3109
3110        let client = Arc::new(OpenSecretClient::new(server.uri()).unwrap());
3111        let prepared = client.prepare_native_oauth_handoff().await.unwrap();
3112        let pending = {
3113            let client = Arc::clone(&client);
3114            tokio::spawn(async move {
3115                client
3116                    .redeem_native_oauth_handoff(
3117                        prepared,
3118                        NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap(),
3119                    )
3120                    .await
3121            })
3122        };
3123        tokio::time::timeout(std::time::Duration::from_secs(2), async {
3124            loop {
3125                if state.captured_requests().len() == 1 {
3126                    return;
3127                }
3128                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
3129            }
3130        })
3131        .await
3132        .expect("native handoff request was not observed");
3133        client
3134            .set_tokens("new-access".to_string(), Some("new-refresh".to_string()))
3135            .unwrap();
3136
3137        assert!(matches!(
3138            pending.await.unwrap(),
3139            Err(Error::Authentication(message))
3140                if message == "Authentication changed during native OAuth handoff"
3141        ));
3142        let tokens = client.get_tokens().unwrap().unwrap();
3143        assert_eq!(tokens.access_token, "new-access");
3144        assert_eq!(tokens.refresh_token.as_deref(), Some("new-refresh"));
3145        assert!(client.current_transport_session().unwrap().is_none());
3146        assert_eq!(server.received_requests().await.unwrap().len(), 2);
3147    }
3148
3149    #[tokio::test]
3150    async fn failed_native_handoff_is_not_retried_and_retires_ambiguous_session() {
3151        let server = MockServer::start().await;
3152        Mock::given(method("POST"))
3153            .and(path("/v2/session"))
3154            .respond_with(SessionResponder {
3155                server_secret: [0x8e; 32],
3156                state: None,
3157                delay: None,
3158            })
3159            .expect(1)
3160            .mount(&server)
3161            .await;
3162        Mock::given(method("POST"))
3163            .and(path("/v2/request"))
3164            .respond_with(ResponseTemplate::new(503))
3165            .expect(1)
3166            .mount(&server)
3167            .await;
3168
3169        let client = OpenSecretClient::new(server.uri()).unwrap();
3170        let prepared = client.prepare_native_oauth_handoff().await.unwrap();
3171        assert!(client
3172            .redeem_native_oauth_handoff(
3173                prepared,
3174                NativeOAuthHandoffGrant::new("e30.e30.c2ln").unwrap(),
3175            )
3176            .await
3177            .is_err());
3178        assert!(client.current_transport_session().unwrap().is_none());
3179        let requests = server.received_requests().await.unwrap();
3180        assert_eq!(requests.len(), 2);
3181        assert_eq!(requests[0].url.path(), "/v2/session");
3182        assert_eq!(requests[1].url.path(), "/v2/request");
3183    }
3184
3185    #[tokio::test]
3186    async fn native_handoff_requires_a_dedicated_anonymous_client() {
3187        let client =
3188            OpenSecretClient::new_with_api_key("http://127.0.0.1:1", "api-key".to_string())
3189                .unwrap();
3190        assert!(matches!(
3191            client.prepare_native_oauth_handoff().await,
3192            Err(Error::Authentication(message))
3193                if message == "Native OAuth handoff requires an anonymous client"
3194        ));
3195    }
3196
3197    #[derive(Serialize)]
3198    struct NativeHandoffGrantIntegrationRequest<'a> {
3199        native_session_id: &'a str,
3200        native_request_id: &'a str,
3201    }
3202
3203    #[derive(Deserialize)]
3204    struct NativeHandoffGrantIntegrationResponse {
3205        grant: String,
3206    }
3207
3208    #[tokio::test]
3209    #[ignore = "Requires the disposable OpenSecret SDK integration backend"]
3210    async fn native_handoff_full_stack_round_trip() -> Result<()> {
3211        let base_url = std::env::var("VITE_OPEN_SECRET_API_URL")
3212            .expect("VITE_OPEN_SECRET_API_URL must identify the disposable backend");
3213        let client_id = std::env::var("VITE_TEST_CLIENT_ID")
3214            .ok()
3215            .and_then(|value| Uuid::parse_str(&value).ok())
3216            .expect("VITE_TEST_CLIENT_ID must be a UUID");
3217
3218        let browser = OpenSecretClient::new(base_url.clone())?;
3219        let registered = browser
3220            .register_guest(
3221                format!("native_handoff_full_stack_{}", Uuid::new_v4()),
3222                client_id,
3223            )
3224            .await?;
3225
3226        let native_a = OpenSecretClient::new(base_url.clone())?;
3227        let native_b = OpenSecretClient::new(base_url)?;
3228        let prepared_a = native_a.prepare_native_oauth_handoff().await?;
3229        let prepared_b = native_b.prepare_native_oauth_handoff().await?;
3230
3231        let minted: NativeHandoffGrantIntegrationResponse = browser
3232            .authenticated_api_call(
3233                "/auth/native-handoff/grant",
3234                "POST",
3235                Some(NativeHandoffGrantIntegrationRequest {
3236                    native_session_id: prepared_a.session_id(),
3237                    native_request_id: prepared_a.request_id(),
3238                }),
3239            )
3240            .await?;
3241
3242        let transplanted = native_b
3243            .redeem_native_oauth_handoff(
3244                prepared_b,
3245                NativeOAuthHandoffGrant::new(minted.grant.clone())?,
3246            )
3247            .await;
3248        assert!(
3249            matches!(transplanted, Err(Error::Api { status: 401, .. })),
3250            "a grant must not authenticate a different native session/request: {transplanted:?}"
3251        );
3252        assert!(native_b.get_tokens()?.is_none());
3253
3254        let redeemed = native_a
3255            .redeem_native_oauth_handoff(prepared_a, NativeOAuthHandoffGrant::new(minted.grant)?)
3256            .await?;
3257        assert_eq!(redeemed.id, registered.id);
3258        let native_user = native_a.get_user().await?;
3259        assert_eq!(native_user.user.id, registered.id);
3260        assert!(native_a.get_tokens()?.is_some());
3261
3262        Ok(())
3263    }
3264
3265    #[test]
3266    fn access_token_expiry_is_only_a_conservative_timing_hint() {
3267        assert!(access_token_needs_refresh(&encoded_timing_token(130), 100));
3268        assert!(access_token_needs_refresh(&encoded_timing_token(129), 100));
3269        assert!(!access_token_needs_refresh(&encoded_timing_token(131), 100));
3270        assert!(!access_token_needs_refresh("not-a-jwt", 100));
3271        assert!(!access_token_needs_refresh("a.invalid-json.c", 100));
3272    }
3273
3274    #[test]
3275    fn typed_stream_request_keeps_sse_and_json_headers_and_v2_stream_flags() {
3276        let request = ChatCompletionRequest {
3277            model: "test-model".to_string(),
3278            messages: vec![ChatMessage {
3279                role: "user".to_string(),
3280                content: serde_json::json!("hello"),
3281                tool_calls: None,
3282                reasoning_content: None,
3283            }],
3284            temperature: None,
3285            max_tokens: None,
3286            stream: Some(false),
3287            stream_options: None,
3288            tools: None,
3289            tool_choice: None,
3290        };
3291        let encoded = build_chat_completion_stream_request(request).unwrap();
3292        assert_eq!(encoded.method(), http::Method::POST);
3293        assert_eq!(encoded.uri(), "/v1/chat/completions");
3294        assert_eq!(encoded.headers()[header::ACCEPT], "text/event-stream");
3295        assert_eq!(encoded.headers()[header::CONTENT_TYPE], "application/json");
3296        let body: serde_json::Value = serde_json::from_slice(encoded.body()).unwrap();
3297        assert_eq!(body["stream"], true);
3298        assert_eq!(body["stream_options"]["include_usage"], true);
3299    }
3300
3301    #[tokio::test]
3302    async fn transport_network_failures_preserve_the_public_http_error_class() {
3303        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
3304        let address = listener.local_addr().unwrap();
3305        drop(listener);
3306        let client = OpenSecretClient::new(format!("http://{address}")).unwrap();
3307
3308        assert!(matches!(
3309            client.perform_attestation_handshake().await,
3310            Err(Error::Http(_))
3311        ));
3312    }
3313
3314    #[test]
3315    fn transient_or_malformed_refresh_response_preserves_credentials() {
3316        let client = OpenSecretClient::new("http://127.0.0.1:1").unwrap();
3317        client
3318            .set_tokens("access".to_string(), Some("refresh".to_string()))
3319            .unwrap();
3320        let generation = client
3321            .session_manager
3322            .get_credential_snapshot()
3323            .unwrap()
3324            .token_generation;
3325
3326        assert!(client
3327            .apply_authenticated_refresh_response(
3328                generation,
3329                http::StatusCode::SERVICE_UNAVAILABLE,
3330                b"temporarily unavailable",
3331            )
3332            .is_err());
3333        assert_eq!(
3334            client.get_access_token().unwrap().as_deref(),
3335            Some("access")
3336        );
3337        assert!(client
3338            .apply_authenticated_refresh_response(generation, http::StatusCode::OK, b"not-json",)
3339            .is_err());
3340        assert_eq!(
3341            client.get_access_token().unwrap().as_deref(),
3342            Some("access")
3343        );
3344    }
3345
3346    #[test]
3347    fn authenticated_refresh_rejection_clears_only_the_rejected_generation() {
3348        let client = OpenSecretClient::new("http://127.0.0.1:1").unwrap();
3349        client
3350            .set_tokens("old-access".to_string(), Some("old-refresh".to_string()))
3351            .unwrap();
3352        let old_generation = client
3353            .session_manager
3354            .get_credential_snapshot()
3355            .unwrap()
3356            .token_generation;
3357        client
3358            .set_tokens("new-access".to_string(), Some("new-refresh".to_string()))
3359            .unwrap();
3360
3361        assert!(client
3362            .apply_authenticated_refresh_response(
3363                old_generation,
3364                http::StatusCode::UNAUTHORIZED,
3365                b"rejected",
3366            )
3367            .is_err());
3368        assert_eq!(
3369            client.get_access_token().unwrap().as_deref(),
3370            Some("new-access")
3371        );
3372
3373        let current_generation = client
3374            .session_manager
3375            .get_credential_snapshot()
3376            .unwrap()
3377            .token_generation;
3378        assert!(client
3379            .apply_authenticated_refresh_response(
3380                current_generation,
3381                http::StatusCode::FORBIDDEN,
3382                b"rejected",
3383            )
3384            .is_err());
3385        assert!(client.get_tokens().unwrap().is_none());
3386    }
3387
3388    #[test]
3389    fn successful_refresh_updates_only_the_generation_that_was_sent() {
3390        let client = OpenSecretClient::new("http://127.0.0.1:1").unwrap();
3391        client
3392            .set_tokens("old-access".to_string(), Some("old-refresh".to_string()))
3393            .unwrap();
3394        let generation = client
3395            .session_manager
3396            .get_credential_snapshot()
3397            .unwrap()
3398            .token_generation;
3399        let body = br#"{"access_token":"rotated-access","refresh_token":"rotated-refresh"}"#;
3400
3401        client
3402            .apply_authenticated_refresh_response(generation, http::StatusCode::OK, body)
3403            .unwrap();
3404        let tokens = client.get_tokens().unwrap().unwrap();
3405        assert_eq!(tokens.access_token, "rotated-access");
3406        assert_eq!(tokens.refresh_token.as_deref(), Some("rotated-refresh"));
3407    }
3408
3409    #[test]
3410    fn inference_allowlist_is_method_and_path_exact() {
3411        assert!(is_allowed_inference_endpoint(
3412            &http::Method::POST,
3413            "/v1/chat/completions"
3414        ));
3415        assert!(is_allowed_inference_endpoint(
3416            &http::Method::GET,
3417            "/v1/models"
3418        ));
3419        assert!(is_allowed_inference_endpoint(
3420            &http::Method::POST,
3421            "/v1/systemone"
3422        ));
3423        assert!(!is_allowed_inference_endpoint(
3424            &http::Method::GET,
3425            "/v1/systemone"
3426        ));
3427        assert!(!is_allowed_inference_endpoint(
3428            &http::Method::POST,
3429            "/v1/models"
3430        ));
3431        assert!(!is_allowed_inference_endpoint(
3432            &http::Method::GET,
3433            "/protected/private_key"
3434        ));
3435        assert!(!is_allowed_inference_endpoint(
3436            &http::Method::POST,
3437            "/v1/chat/completions/extra"
3438        ));
3439    }
3440
3441    #[tokio::test]
3442    async fn inference_budget_excludes_preflight_and_blocks_a_later_send() {
3443        let server = MockServer::start().await;
3444        let state = TestV2ServerState::new();
3445        state.queue_json_response(
3446            200,
3447            serde_json::json!({
3448                "access_token": "fresh-access",
3449                "refresh_token": "fresh-refresh",
3450            }),
3451        );
3452        state.queue_json_response(200, serde_json::json!({ "object": "list", "data": [] }));
3453        Mock::given(method("POST"))
3454            .and(path("/v2/session"))
3455            .respond_with(SessionResponder {
3456                server_secret: [0x75; 32],
3457                state: Some(state.clone()),
3458                delay: None,
3459            })
3460            .expect(1)
3461            .mount(&server)
3462            .await;
3463        Mock::given(method("POST"))
3464            .and(path("/v2/request"))
3465            .respond_with(state.request_responder())
3466            .expect(2)
3467            .mount(&server)
3468            .await;
3469        let client = OpenSecretClient::new(server.uri()).unwrap();
3470        client
3471            .set_tokens(encoded_timing_token(0), Some("refresh-secret".to_string()))
3472            .unwrap();
3473        let send_budget = InferenceSendBudget::new(1).unwrap();
3474        let request = HttpRequest::get("/v1/models").body(Bytes::new()).unwrap();
3475        let response = client
3476            .send_inference_request_with_budget(request, send_budget.clone())
3477            .await
3478            .unwrap();
3479        assert_eq!(response.status(), http::StatusCode::OK);
3480        collect_response_body(response.into_body()).await.unwrap();
3481        assert_eq!(send_budget.remaining(), 0);
3482
3483        let request = HttpRequest::get("/v1/models").body(Bytes::new()).unwrap();
3484        assert!(matches!(
3485            client
3486                .send_inference_request_with_budget(request, send_budget)
3487                .await,
3488            Err(Error::Other(message)) if message == "Inference request send budget exhausted"
3489        ));
3490        let logical = state.captured_requests();
3491        assert_eq!(logical.len(), 2);
3492        assert_eq!(logical[0]["target"], "/refresh");
3493        assert_eq!(logical[1]["target"], "/v1/models");
3494        assert_eq!(logical[1]["credential"]["value"], "fresh-access");
3495        server.verify().await;
3496    }
3497
3498    #[tokio::test]
3499    async fn inference_transport_does_not_follow_redirects_outside_the_send_budget() {
3500        let server = MockServer::start().await;
3501        Mock::given(method("POST"))
3502            .and(path("/v2/session"))
3503            .respond_with(SessionResponder {
3504                server_secret: [0x76; 32],
3505                state: None,
3506                delay: None,
3507            })
3508            .expect(1)
3509            .mount(&server)
3510            .await;
3511        Mock::given(method("POST"))
3512            .and(path("/v2/request"))
3513            .respond_with(ResponseTemplate::new(307).insert_header("location", "/redirected"))
3514            .expect(1)
3515            .mount(&server)
3516            .await;
3517        Mock::given(method("POST"))
3518            .and(path("/redirected"))
3519            .respond_with(ResponseTemplate::new(200))
3520            .expect(0)
3521            .mount(&server)
3522            .await;
3523        let client =
3524            OpenSecretClient::new_with_api_key(server.uri(), "api-key".to_string()).unwrap();
3525        let send_budget = InferenceSendBudget::new(2).unwrap();
3526        let request = HttpRequest::get("/v1/models").body(Bytes::new()).unwrap();
3527        assert!(matches!(
3528            client
3529                .send_inference_request_with_budget(request, send_budget.clone())
3530                .await,
3531            Err(Error::InvalidResponse(_))
3532        ));
3533        assert_eq!(send_budget.remaining(), 1);
3534        server.verify().await;
3535    }
3536
3537    #[tokio::test]
3538    async fn explicit_inference_api_key_is_never_installed_as_client_state() {
3539        let server = MockServer::start().await;
3540        Mock::given(method("POST"))
3541            .and(path("/v2/session"))
3542            .respond_with(SessionResponder {
3543                server_secret: [0x77; 32],
3544                state: None,
3545                delay: None,
3546            })
3547            .expect(1)
3548            .mount(&server)
3549            .await;
3550        Mock::given(method("POST"))
3551            .and(path("/v2/request"))
3552            .respond_with(ResponseTemplate::new(503))
3553            .expect(1)
3554            .mount(&server)
3555            .await;
3556        let client = OpenSecretClient::new(server.uri()).unwrap();
3557        let request = HttpRequest::get("/v1/models").body(Bytes::new()).unwrap();
3558
3559        assert!(client
3560            .send_inference_request_with_api_key(request, "per-request-secret".to_string())
3561            .await
3562            .is_err());
3563        assert!(client.session_manager.get_api_key().unwrap().is_none());
3564        let received = server.received_requests().await.unwrap();
3565        assert_eq!(received.len(), 2);
3566        assert_eq!(received[0].url.path(), "/v2/session");
3567        assert_eq!(received[1].url.path(), "/v2/request");
3568        assert!(!received[1].headers.contains_key(header::AUTHORIZATION));
3569        assert!(!received[1].headers.contains_key(header::COOKIE));
3570        assert!(received[1].headers.contains_key("x-session-id"));
3571        assert!(!received[1]
3572            .body
3573            .windows(b"per-request-secret".len())
3574            .any(|window| window == b"per-request-secret"));
3575    }
3576
3577    #[tokio::test]
3578    async fn superseded_bearer_during_session_establishment_is_never_sent() {
3579        let server = MockServer::start().await;
3580        mount_delayed_session_with_no_request(&server, [0x81; 32]).await;
3581        let client = Arc::new(OpenSecretClient::new(server.uri()).unwrap());
3582        client
3583            .set_tokens("old-access".to_string(), Some("old-refresh".to_string()))
3584            .unwrap();
3585
3586        let pending = {
3587            let client = Arc::clone(&client);
3588            tokio::spawn(async move { client.get_user().await })
3589        };
3590        wait_until_session_establishment_is_in_flight(&server).await;
3591        client
3592            .set_tokens("new-access".to_string(), Some("new-refresh".to_string()))
3593            .unwrap();
3594
3595        assert!(matches!(
3596            pending.await.unwrap(),
3597            Err(Error::Authentication(message))
3598                if message == "Credential changed before Transport V2 request admission"
3599        ));
3600        let requests = server.received_requests().await.unwrap();
3601        assert_eq!(requests.len(), 1);
3602        assert_eq!(requests[0].url.path(), "/v2/session");
3603    }
3604
3605    #[tokio::test]
3606    async fn superseded_stored_api_key_during_session_establishment_is_never_sent() {
3607        let server = MockServer::start().await;
3608        mount_delayed_session_with_no_request(&server, [0x82; 32]).await;
3609        let client = Arc::new(
3610            OpenSecretClient::new_with_api_key(server.uri(), "old-api-key".to_string()).unwrap(),
3611        );
3612
3613        let pending = {
3614            let client = Arc::clone(&client);
3615            tokio::spawn(async move { client.get_models().await })
3616        };
3617        wait_until_session_establishment_is_in_flight(&server).await;
3618        client.set_api_key("new-api-key".to_string()).unwrap();
3619
3620        assert!(matches!(
3621            pending.await.unwrap(),
3622            Err(Error::Authentication(message))
3623                if message == "Credential changed before Transport V2 request admission"
3624        ));
3625        let requests = server.received_requests().await.unwrap();
3626        assert_eq!(requests.len(), 1);
3627        assert_eq!(requests[0].url.path(), "/v2/session");
3628    }
3629
3630    #[tokio::test]
3631    async fn cleared_resumption_during_session_establishment_is_never_sent() {
3632        let server = MockServer::start().await;
3633        mount_delayed_session_with_no_request(&server, [0x83; 32]).await;
3634        let client = Arc::new(OpenSecretClient::new(server.uri()).unwrap());
3635        client
3636            .set_tokens("old-access".to_string(), Some("old-refresh".to_string()))
3637            .unwrap();
3638
3639        let pending = {
3640            let client = Arc::clone(&client);
3641            tokio::spawn(async move { client.refresh_token().await })
3642        };
3643        wait_until_session_establishment_is_in_flight(&server).await;
3644        client.session_manager.clear_tokens().unwrap();
3645
3646        assert!(matches!(
3647            pending.await.unwrap(),
3648            Err(Error::Authentication(message))
3649                if message == "Credential changed before Transport V2 request admission"
3650        ));
3651        let requests = server.received_requests().await.unwrap();
3652        assert_eq!(requests.len(), 1);
3653        assert_eq!(requests[0].url.path(), "/v2/session");
3654    }
3655
3656    #[tokio::test]
3657    async fn concurrent_preflight_refreshes_once_before_sending_each_original_request_once() {
3658        let server = MockServer::start().await;
3659        let state = TestV2ServerState::new();
3660        state.queue_json_response(
3661            200,
3662            serde_json::json!({
3663                "access_token": "fresh-access",
3664                "refresh_token": "fresh-refresh",
3665            }),
3666        );
3667        for _ in 0..2 {
3668            state.queue_json_response(
3669                200,
3670                serde_json::json!({
3671                    "object": "list",
3672                    "data": [],
3673                }),
3674            );
3675        }
3676        Mock::given(method("POST"))
3677            .and(path("/v2/session"))
3678            .respond_with(SessionResponder {
3679                server_secret: [0x78; 32],
3680                state: Some(state.clone()),
3681                delay: None,
3682            })
3683            .expect(1)
3684            .mount(&server)
3685            .await;
3686        Mock::given(method("POST"))
3687            .and(path("/v2/request"))
3688            .respond_with(state.request_responder())
3689            .expect(3)
3690            .mount(&server)
3691            .await;
3692
3693        let client = OpenSecretClient::new(server.uri()).unwrap();
3694        client
3695            .set_tokens(encoded_timing_token(0), Some("refresh-secret".to_string()))
3696            .unwrap();
3697        let (first, second) = tokio::join!(client.get_models(), client.get_models());
3698        assert!(first.is_ok());
3699        assert!(second.is_ok());
3700
3701        let logical = state.captured_requests();
3702        assert_eq!(logical.len(), 3);
3703        assert_eq!(logical[0]["target"], "/refresh");
3704        assert_eq!(logical[0]["credential"]["kind"], "resumption");
3705        assert_eq!(logical[0]["credential"]["value"], "refresh-secret");
3706        for request in &logical[1..] {
3707            assert_eq!(request["target"], "/v1/models");
3708            assert_eq!(request["credential"]["kind"], "bearer");
3709            assert_eq!(request["credential"]["value"], "fresh-access");
3710        }
3711        let outer = server.received_requests().await.unwrap();
3712        assert_eq!(outer.len(), 4);
3713        assert!(outer
3714            .iter()
3715            .all(|request| !request.headers.contains_key(header::AUTHORIZATION)));
3716        assert_eq!(
3717            client.get_access_token().unwrap().as_deref(),
3718            Some("fresh-access")
3719        );
3720    }
3721
3722    #[tokio::test]
3723    async fn authenticated_post_send_failure_is_not_retried_or_repaired() {
3724        let server = MockServer::start().await;
3725        let state = TestV2ServerState::new();
3726        state.queue_json_response(401, serde_json::json!({ "error": "rejected" }));
3727        Mock::given(method("POST"))
3728            .and(path("/v2/session"))
3729            .respond_with(SessionResponder {
3730                server_secret: [0x79; 32],
3731                state: Some(state.clone()),
3732                delay: None,
3733            })
3734            .expect(1)
3735            .mount(&server)
3736            .await;
3737        Mock::given(method("POST"))
3738            .and(path("/v2/request"))
3739            .respond_with(state.request_responder())
3740            .expect(1)
3741            .mount(&server)
3742            .await;
3743
3744        let client =
3745            OpenSecretClient::new_with_api_key(server.uri(), "api-key".to_string()).unwrap();
3746        assert!(matches!(
3747            client.get_models().await,
3748            Err(Error::Api { status: 401, .. })
3749        ));
3750        assert_eq!(state.captured_requests().len(), 1);
3751        let outer = server.received_requests().await.unwrap();
3752        assert_eq!(outer.len(), 2);
3753        assert_eq!(outer[0].url.path(), "/v2/session");
3754        assert_eq!(outer[1].url.path(), "/v2/request");
3755    }
3756
3757    #[test]
3758    fn inference_request_headers_preserve_logical_content_type_but_strip_outer_authority() {
3759        let mut headers = HttpHeaderMap::new();
3760        headers.insert(
3761            header::AUTHORIZATION,
3762            "Bearer outer-secret".parse().unwrap(),
3763        );
3764        headers.insert(
3765            header::CONTENT_TYPE,
3766            "multipart/form-data; boundary=test".parse().unwrap(),
3767        );
3768        headers.insert(header::CONTENT_LENGTH, "123".parse().unwrap());
3769        headers.insert(header::CONTENT_ENCODING, "gzip".parse().unwrap());
3770        headers.insert(header::COOKIE, "session=outer-secret".parse().unwrap());
3771        headers.insert("forwarded", "for=192.0.2.1".parse().unwrap());
3772        headers.insert("via", "1.1 outer-proxy".parse().unwrap());
3773        headers.insert("x-forwarded-for", "192.0.2.1".parse().unwrap());
3774        headers.insert("x-forwarded-host", "outer.example".parse().unwrap());
3775        headers.insert("x-forwarded-proto", "https".parse().unwrap());
3776        headers.insert("x-session-id", "outer-session".parse().unwrap());
3777        headers.insert(ROUTING_KEY_HEADER, "outer-routing-key".parse().unwrap());
3778        headers.insert("x-client-metadata", "kept".parse().unwrap());
3779        headers.append("x-client-metadata", "also-kept".parse().unwrap());
3780
3781        let sanitized = sanitize_inference_request_headers(&headers);
3782
3783        assert_eq!(
3784            sanitized.get(header::CONTENT_TYPE).unwrap(),
3785            "multipart/form-data; boundary=test"
3786        );
3787        assert_eq!(
3788            sanitized
3789                .get_all("x-client-metadata")
3790                .iter()
3791                .map(|value| value.to_str().unwrap())
3792                .collect::<Vec<_>>(),
3793            ["kept", "also-kept"]
3794        );
3795        assert!(!sanitized.contains_key(header::AUTHORIZATION));
3796        assert!(!sanitized.contains_key(header::CONTENT_LENGTH));
3797        assert!(!sanitized.contains_key(header::CONTENT_ENCODING));
3798        assert!(!sanitized.contains_key(header::COOKIE));
3799        assert!(!sanitized.contains_key("forwarded"));
3800        assert!(!sanitized.contains_key("via"));
3801        assert!(!sanitized.contains_key("x-forwarded-for"));
3802        assert!(!sanitized.contains_key("x-forwarded-host"));
3803        assert!(!sanitized.contains_key("x-forwarded-proto"));
3804        assert!(!sanitized.contains_key("x-session-id"));
3805        assert!(!sanitized.contains_key(ROUTING_KEY_HEADER));
3806    }
3807
3808    #[tokio::test]
3809    async fn response_events_reconstruct_status_headers_and_incremental_body() {
3810        let events = response_events(vec![
3811            Ok(ResponseEvent::Start {
3812                status: 206,
3813                headers: vec![LogicalHeader::new(
3814                    "content-type".to_string(),
3815                    "audio/mpeg".to_string(),
3816                )
3817                .unwrap()],
3818            }),
3819            Ok(ResponseEvent::Chunk(Bytes::from_static(b"abc"))),
3820            Ok(ResponseEvent::Chunk(Bytes::from_static(b"def"))),
3821            Ok(ResponseEvent::End),
3822        ]);
3823
3824        let response = response_from_events(events, None).await.unwrap();
3825        assert_eq!(response.status(), http::StatusCode::PARTIAL_CONTENT);
3826        assert_eq!(
3827            response.headers().get(header::CONTENT_TYPE).unwrap(),
3828            "audio/mpeg"
3829        );
3830        assert_eq!(
3831            collect_response_body(response.into_body()).await.unwrap(),
3832            Bytes::from_static(b"abcdef")
3833        );
3834    }
3835
3836    #[tokio::test]
3837    async fn response_error_record_is_not_mistaken_for_clean_eof() {
3838        let events = response_events(vec![
3839            Ok(ResponseEvent::Start {
3840                status: 200,
3841                headers: Vec::new(),
3842            }),
3843            Ok(ResponseEvent::Chunk(Bytes::from_static(b"partial"))),
3844            Ok(ResponseEvent::Error {
3845                code: "provider_failed".to_string(),
3846            }),
3847        ]);
3848
3849        let response = response_from_events(events, None).await.unwrap();
3850        let error = collect_response_body(response.into_body())
3851            .await
3852            .unwrap_err();
3853        assert!(error.to_string().contains("provider_failed"));
3854    }
3855
3856    #[tokio::test]
3857    async fn response_without_authenticated_terminal_is_rejected() {
3858        let events = response_events(vec![
3859            Ok(ResponseEvent::Start {
3860                status: 200,
3861                headers: Vec::new(),
3862            }),
3863            Ok(ResponseEvent::Chunk(Bytes::from_static(b"partial"))),
3864        ]);
3865
3866        let response = response_from_events(events, None).await.unwrap();
3867        let error = collect_response_body(response.into_body())
3868            .await
3869            .unwrap_err();
3870        assert!(error.to_string().contains("authenticated finality"));
3871    }
3872
3873    #[test]
3874    fn endpoint_builders_encode_query_values() {
3875        let params = ConversationsListParams {
3876            limit: Some(25),
3877            after: Some(Uuid::nil()),
3878            order: Some("desc".to_string()),
3879            project_id: None,
3880            unassigned_project: Some(true),
3881            pinned: Some(false),
3882        };
3883        let endpoint = build_conversations_endpoint(Some(&params));
3884
3885        assert!(endpoint.starts_with("/v1/conversations?"));
3886        assert!(endpoint.contains("limit=25"));
3887        assert!(endpoint.contains("after=00000000%2D0000%2D0000%2D0000%2D000000000000"));
3888        assert!(endpoint.contains("order=desc"));
3889        assert!(endpoint.contains("unassigned_project=true"));
3890        assert!(endpoint.contains("pinned=false"));
3891    }
3892
3893    #[tokio::test]
3894    async fn empty_conversation_updates_still_fail_before_network_use() {
3895        let client = OpenSecretClient::new("http://127.0.0.1:1").unwrap();
3896
3897        assert!(matches!(
3898            client
3899                .update_conversation(Uuid::nil(), ConversationUpdateRequest::default())
3900                .await,
3901            Err(Error::Configuration(message))
3902                if message.contains("at least one field")
3903        ));
3904        assert!(matches!(
3905            client
3906                .update_conversation_project(
3907                    Uuid::nil(),
3908                    ConversationProjectUpdateRequest::default(),
3909                )
3910                .await,
3911            Err(Error::Configuration(message))
3912                if message.contains("at least one field")
3913        ));
3914    }
3915
3916    #[test]
3917    fn agent_sse_parser_preserves_typed_message_and_reaction_ids() {
3918        let message_id = Uuid::new_v4();
3919        let message = format!(r#"{{"message_id":"{message_id}","message":"hello"}}"#);
3920        match parse_agent_sse_event("agent.message", &message)
3921            .unwrap()
3922            .unwrap()
3923        {
3924            AgentSseEvent::Message(event) => {
3925                assert_eq!(event.message_id, message_id);
3926                assert_eq!(event.message, "hello");
3927            }
3928            other => panic!("unexpected event: {other:?}"),
3929        }
3930
3931        let item_id = Uuid::new_v4();
3932        let reaction = format!(r#"{{"item_id":"{item_id}","emoji":"👍"}}"#);
3933        match parse_agent_sse_event("agent.reaction", &reaction)
3934            .unwrap()
3935            .unwrap()
3936        {
3937            AgentSseEvent::Reaction(event) => {
3938                assert_eq!(event.item_id, item_id);
3939                assert_eq!(event.emoji, "👍");
3940            }
3941            other => panic!("unexpected event: {other:?}"),
3942        }
3943
3944        assert!(parse_agent_sse_event("unknown", "{}").is_none());
3945    }
3946}
3947
3948#[cfg(test)]
3949mod recovery_tests;