gaze_proxy/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! Multi-provider pass-through proxy for Gaze pseudonymization.
4//!
5//! The proxy does not transcode provider wire formats. Provider adapters only
6//! identify native PII-bearing JSON surfaces; the server applies the supplied
7//! [`gaze::Pipeline`] and session manifest.
8
9pub mod adapter;
10pub mod adapters;
11#[allow(
12    dead_code,
13    reason = "constructors are consumed by the next server integration checkpoint"
14)]
15pub mod codec;
16#[allow(
17    dead_code,
18    reason = "codec probes are consumed by the next server integration checkpoint"
19)]
20pub mod codecs;
21pub(crate) use codecs::anthropic;
22#[cfg(feature = "proxy-daemon")]
23pub mod daemon;
24pub mod error;
25pub mod inspection;
26pub mod principal;
27pub mod server;
28#[allow(
29    dead_code,
30    reason = "finite registry is integrated by the serialized P3/P4 checkpoints"
31)]
32pub(crate) mod session_registry;
33
34use std::net::SocketAddr;
35use std::sync::Arc;
36use std::time::Duration;
37
38use adapters::AnthropicAdapter;
39use gaze::{DictionaryBundle, LocaleChain, LocaleTag, Pipeline};
40
41pub use adapter::{
42    AdapterContract, CoveragePolicy, FormatPolicy, HeaderPolicy, PiiSurface, ProtocolContract,
43    ProviderAdapter, RedirectPolicy, RoutePolicy, SessionPolicy, SessionRegistryConfig,
44    SessionRegistryConfigError, SseEvent,
45};
46pub use codec::{
47    BodyCodec, CodecError, CodecErrorCode, CodecLimits, CodecPhase, OpaqueCarrierLocation,
48    OpaqueCarrierScheme, OutputProvenance, ProvedRequestBody, ProvedResponseBody,
49    RequestPseudonymizer, RequestTransformContext, ResponseResidualValidator,
50    ResponseTransformContext, WireFormat,
51};
52pub use codecs::anthropic::{
53    AnthropicMessagesCodec, ANTHROPIC_PROXY_ERROR_FRAME, ANTHROPIC_PROXY_PING_FRAME,
54};
55pub use error::{
56    DirectProxyError, HeaderRejectionReason, ProxyError, ProxyErrorCode, ProxyErrorPhase,
57};
58pub use inspection::{install_proxy_inspection_v1, ProxyInspectionProducerV1};
59pub use principal::{
60    AuthenticatedPrincipal, ListenerScope, LocalAuthCredential, PeerScope, PrincipalContext,
61    PrincipalResolveError, PrincipalResolver, ProcessLocalLoopbackResolver,
62    TlsClientCertificateHash, MAX_AUTHENTICATED_PRINCIPAL_BYTES, MAX_LOCAL_AUTH_CREDENTIAL_BYTES,
63};
64pub use server::{
65    classify_upstream_status, parse_request_stream_format, serve, validate_declared_body,
66    validate_direct_response_head, DirectResponseHead, HealthSnapshot, DIRECT_PROXY_ERROR_FRAME,
67    DIRECT_PROXY_PING_FRAME,
68};
69
70#[derive(Clone)]
71#[non_exhaustive]
72pub struct ProxyConfig {
73    pub bind: SocketAddr,
74    pub adapters: Vec<Arc<dyn ProviderAdapter>>,
75    pub session_ttl: Duration,
76    pub body_limit_bytes: u64,
77    pub(crate) locale_chain: LocaleChain,
78    pub(crate) dictionaries: DictionaryBundle,
79    pub(crate) direct_anthropic: Option<Arc<AnthropicAdapter>>,
80    pub(crate) inspection: Option<Arc<ProxyInspectionProducerV1>>,
81}
82
83impl ProxyConfig {
84    pub fn new(bind: SocketAddr, adapters: Vec<Arc<dyn ProviderAdapter>>) -> Self {
85        Self {
86            bind,
87            adapters,
88            session_ttl: Duration::from_secs(30 * 60),
89            body_limit_bytes: 2 * 1024 * 1024,
90            locale_chain: default_locale_chain(),
91            dictionaries: DictionaryBundle::default(),
92            direct_anthropic: None,
93            inspection: None,
94        }
95    }
96
97    /// Constructs the strict direct Anthropic profile without a generic trait-object handoff.
98    ///
99    /// This preserves builder-only settings such as continuity, allowlists, timeouts, and an
100    /// optional trusted principal resolver. [`Self::new`] remains source-compatible for legacy
101    /// multi-provider configurations and uses the direct profile's frozen defaults.
102    #[must_use]
103    pub fn anthropic_direct(bind: SocketAddr, adapter: AnthropicAdapter) -> Self {
104        let adapter = Arc::new(adapter);
105        let dynamic: Arc<dyn ProviderAdapter> = adapter.clone();
106        Self {
107            bind,
108            adapters: vec![dynamic],
109            session_ttl: Duration::from_secs(30 * 60),
110            body_limit_bytes: 2 * 1024 * 1024,
111            locale_chain: default_locale_chain(),
112            dictionaries: DictionaryBundle::default(),
113            direct_anthropic: Some(adapter),
114            inspection: None,
115        }
116    }
117
118    /// Sets the locale chain every detection pass on this proxy runs under.
119    ///
120    /// # Why this is explicit
121    ///
122    /// Recognizers declare `locales = [...]` and only run when the active chain intersects
123    /// that list. Before this setting existed the proxy pinned `[LocaleTag::Global]`, so an
124    /// adopter who had already configured `de-DE` silently got no `postal.de` and no DE
125    /// national-phone detection on proxied traffic — an axis-1 leak the adopter had no way to
126    /// observe. The chain is now adopter-supplied rather than inherited from a system default,
127    /// so what activates is a stated configuration decision.
128    ///
129    /// # Derivation
130    ///
131    /// Callers derive the value from the canonical 4-tier chain
132    /// (CLI > policy > rulepack default > system default) with
133    /// [`gaze::LocaleChain::merge_cli_policy_rulepack_default`], or read it straight off a
134    /// `gaze_assembly::CorePipeline::locale_chain`, and pass the result here. It MUST be the
135    /// same chain the supplied [`gaze::Pipeline`] was assembled under: assembly decides which
136    /// recognizers are REGISTERED, this chain decides which of them are allowed to FIRE.
137    ///
138    /// Omitting this call leaves the chain at `[LocaleTag::Global]`, which reproduces the
139    /// pre-existing behavior exactly. [`gaze::LocaleChain`] always appends `Global` as its
140    /// final tier, so configuring a locale can only widen detection, never narrow it.
141    ///
142    /// Both the primary surface pass and the outbound residual re-scan read this one field,
143    /// which is what keeps the residual neither weaker nor stronger than the primary pass.
144    #[must_use]
145    pub fn with_locale_chain(mut self, locale_chain: LocaleChain) -> Self {
146        self.locale_chain = locale_chain;
147        self
148    }
149
150    /// Returns the locale chain detection runs under on this proxy.
151    #[must_use]
152    pub fn locale_chain(&self) -> &[LocaleTag] {
153        self.locale_chain.as_slice()
154    }
155
156    /// Sets the dictionary values every primary and residual detection pass uses.
157    ///
158    /// Omitting this call preserves the pre-existing empty-bundle behavior. The
159    /// same immutable bundle is shared across request protection and residual
160    /// validation so the fail-closed pass cannot know fewer terms than the
161    /// primary pass.
162    #[must_use]
163    pub fn with_dictionaries(mut self, dictionaries: DictionaryBundle) -> Self {
164        self.dictionaries = dictionaries;
165        self
166    }
167
168    /// Returns the dictionary values used by every proxy detection pass.
169    #[must_use]
170    pub fn dictionaries(&self) -> &DictionaryBundle {
171        &self.dictionaries
172    }
173
174    /// Installs the immutable provider-neutral inspection producer for this launch.
175    ///
176    /// The producer can be created only by [`install_proxy_inspection_v1`], which atomically
177    /// binds it to the adopter-supplied pending consumer half. Omitting this method constructs no
178    /// inspection registration or runtime.
179    #[must_use]
180    pub fn with_inspection(mut self, inspection: ProxyInspectionProducerV1) -> Self {
181        self.inspection = Some(Arc::new(inspection));
182        self
183    }
184}
185
186/// The locale chain used when an adopter configures none.
187///
188/// Deliberately `[LocaleTag::Global]`: it is exactly the chain the proxy pinned before
189/// [`ProxyConfig::with_locale_chain`] existed, so adopters who configure nothing observe no
190/// behavior change. Widening this default would activate `postal.us` / `postal.de` for every
191/// adopter at once and is a separate decision (Solo todo #2400, values-vs-bounds).
192fn default_locale_chain() -> LocaleChain {
193    LocaleChain::from_tags(vec![LocaleTag::Global])
194}
195
196pub async fn serve_foreground(
197    config: ProxyConfig,
198    pipeline: Arc<Pipeline>,
199) -> Result<(), ProxyError> {
200    serve(config, pipeline).await
201}
gaze_proxy/lib.rs

gaze_proxy/
lib.rs
