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