Skip to main content

sill_adapter/
lib.rs

1//! The Sill adapter format.
2//!
3//! An adapter answers two questions about one upstream: **where does the credential live
4//! in a request**, and **what must never come back out in a response**. Everything else
5//! about the request — path, method, body — is passed through untouched.
6//!
7//! The format is published and contributable, which is why it lives in the MIT tree. The
8//! CLI validates adapters and the relay executes them from this same crate, so the two
9//! cannot drift in their reading of a file.
10//!
11//! ```toml
12//! schema_version = 1
13//!
14//! [adapter.railway]
15//! upstream = "backboard.railway.com"
16//!
17//! [[adapter.railway.auth]]
18//! location = "header"
19//! name = "authorization"
20//! scheme = "Bearer"
21//!
22//! [adapter.railway.response]
23//! redact = ["$.data.token"]
24//! ```
25//!
26//! # Why this parser is strict
27//!
28//! Unknown fields are rejected. A misspelled `redact` key that parsed successfully would
29//! silently disable response redaction, and the adapter would look like it was enforcing
30//! something it was not. In a credential broker that failure mode is indistinguishable
31//! from working until an incident, so every typo is a hard error.
32
33use std::collections::BTreeMap;
34
35use serde::{Deserialize, Serialize};
36
37mod path;
38
39pub use path::{SlotPath, SlotPathError, SlotSegment};
40
41/// The only schema version this crate understands.
42pub const SCHEMA_VERSION: u32 = 1;
43
44#[derive(Debug, thiserror::Error)]
45pub enum AdapterError {
46    #[error("could not parse adapter file: {0}")]
47    Toml(#[from] toml::de::Error),
48
49    #[error(
50        "adapter file declares schema_version {found}, this build understands {SCHEMA_VERSION}"
51    )]
52    UnsupportedSchema { found: u32 },
53
54    #[error("adapter `{adapter}`: {message}")]
55    Invalid { adapter: String, message: String },
56
57    #[error("adapter `{adapter}`: invalid slot path `{path}`: {source}")]
58    SlotPath {
59        adapter: String,
60        path: String,
61        #[source]
62        source: SlotPathError,
63    },
64}
65
66/// A parsed adapter file. One file may define several upstreams.
67#[derive(Debug, Clone, Serialize, Deserialize)]
68#[serde(deny_unknown_fields)]
69pub struct AdapterFile {
70    pub schema_version: u32,
71
72    #[serde(default, rename = "adapter")]
73    pub adapters: BTreeMap<String, Adapter>,
74}
75
76/// Where a credential lives for one upstream, and what must not come back.
77#[derive(Debug, Clone, Serialize, Deserialize)]
78#[serde(deny_unknown_fields)]
79pub struct Adapter {
80    /// Bare hostname. No scheme, no path, no port — the relay forwards the client's
81    /// original path untouched (§5.1) and adding a second place that can carry a path
82    /// creates ambiguity about which one wins.
83    pub upstream: String,
84
85    #[serde(default)]
86    pub description: Option<String>,
87
88    /// Informational: the client class from the compatibility matrix. Recorded so
89    /// `doctor` can explain a mechanism, never used to decide one.
90    #[serde(default)]
91    pub class: Option<u8>,
92
93    /// What the upstream speaks on the wire.
94    ///
95    /// A property of the API, not of any policy written against it: Railway's Backboard
96    /// is GraphQL whether or not anyone has restricted what an agent may do with it. It
97    /// lives here because the adapter is where a published, contributed fact about an
98    /// upstream belongs — and because the relay needs it before a policy exists.
99    #[serde(default)]
100    pub protocol: Protocol,
101
102    /// Every slot that may carry the credential. Searched in declaration order.
103    ///
104    /// More than one entry is normal: a provider that accepts either a header or a query
105    /// parameter needs both declared, or a handle arriving in the undeclared slot would
106    /// be forwarded to the upstream as-is.
107    pub auth: Vec<AuthSlot>,
108
109    #[serde(default)]
110    pub response: ResponsePolicy,
111
112    /// Positions in a response body that carry a *new* credential the relay should take
113    /// custody of. See [`Capture`].
114    #[serde(default)]
115    pub capture: Vec<Capture>,
116
117    /// Headers to forward verbatim that would otherwise be normalised away. Notion's
118    /// `Notion-Version` is the canonical case — dropping it changes the API's behaviour.
119    #[serde(default)]
120    pub preserve_headers: Vec<String>,
121}
122
123/// The wire protocol an upstream speaks.
124///
125/// Deliberately a small closed set rather than a free string: an unrecognised value would
126/// deserialise into "something", and the safest reading of "something" — treat it as plain
127/// HTTP — is also the one that silently stops reading request bodies. `deny_unknown_fields`
128/// covers misspelled keys; this covers misspelled values.
129#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
130#[serde(rename_all = "snake_case")]
131pub enum Protocol {
132    /// Plain HTTP. Method and path say what the request does.
133    #[default]
134    Http,
135    // Spelled out: `rename_all` would derive `graph_ql` and `json_rpc`, and this is a
136    // published format that contributors write by hand.
137    #[serde(rename = "graphql")]
138    GraphQl,
139    #[serde(rename = "grpc")]
140    Grpc,
141    #[serde(rename = "jsonrpc")]
142    JsonRpc,
143}
144
145/// A place a credential can be carried.
146#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
147#[serde(rename_all = "snake_case")]
148pub enum SlotLocation {
149    Header,
150    Query,
151    /// A declared position inside a JSON request body.
152    ///
153    /// Only declared positions are ever read. The relay does not walk whole request
154    /// payloads looking for something that resembles a credential: an agent's request
155    /// body is arbitrary user data, and scanning it wholesale would mean parsing
156    /// attacker-influenced structures on the hot path for no benefit.
157    JsonBody,
158}
159
160#[derive(Debug, Clone, Serialize, Deserialize)]
161#[serde(deny_unknown_fields)]
162pub struct AuthSlot {
163    pub location: SlotLocation,
164
165    /// Header name, query parameter name, or slot path for `json_body`.
166    /// Header names are compared case-insensitively.
167    pub name: String,
168
169    /// Prefix before the credential, if any: `Bearer`, `Token`, `Basic`.
170    ///
171    /// Absent means the raw value *is* the credential. This distinction is not cosmetic
172    /// — Linear sends an API key with no prefix but its OAuth tokens with `Bearer`, and
173    /// Anthropic's `x-api-key` carries the key bare. Getting it wrong produces a 401 that
174    /// looks like a bad credential rather than a bad adapter.
175    #[serde(default)]
176    pub scheme: Option<String>,
177}
178
179#[derive(Debug, Clone, Default, Serialize, Deserialize)]
180#[serde(deny_unknown_fields)]
181pub struct ResponsePolicy {
182    /// Positions in a JSON response body that carry credential material and must be
183    /// replaced before the response reaches the agent.
184    #[serde(default)]
185    pub redact: Vec<String>,
186
187    /// Whether responses from this upstream may be streamed.
188    ///
189    /// Streaming is handled with an overlap window rather than by refusing to redact, so
190    /// this exists to mark upstreams where that is known not to hold.
191    #[serde(default)]
192    pub streaming: StreamingPolicy,
193}
194
195/// Where a response hands back a credential that did not exist before.
196///
197/// §12 lists this as a residual risk with no mitigation: "Agent calls STS, receives a
198/// fresh token in a response body. Real, never seen before, unredactable." Redaction
199/// cannot help — there is nothing to match against, because the value is new.
200///
201/// So the relay takes custody instead. It lifts the value out, stores it, and writes a
202/// handle into the response in its place. The agent receives `ref_…` where the secret
203/// was, and can pass that handle straight into the next call — `fly secrets set
204/// DATABASE_URL=ref_…` — where outbound substitution puts the real value back. Neither
205/// value is ever in the agent's context.
206///
207/// # Why there is no request matcher here
208///
209/// A capture fires when its `path` is present in a response body, and not otherwise. It
210/// could have been scoped by method and path as well, but that would be a second place to
211/// get a rule wrong for no benefit: a response that does not contain `$.service_role_key`
212/// is not a response we would have captured from anyway. It also costs nothing, because
213/// bodies from an adapter declaring `redact` are already parsed.
214///
215/// # This is a declaration, not a permission
216///
217/// Declaring a capture does not enable it. The scope engine decides whether a given
218/// request may take custody of a credential, and the default is no — an agent allowed to
219/// call an endpoint is not thereby allowed to mint durable credentials in someone's
220/// account.
221#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
222#[serde(deny_unknown_fields)]
223pub struct Capture {
224    /// Where the credential appears, in the same restricted grammar `redact` uses.
225    pub path: String,
226
227    /// The adapter the captured credential will be *used* with — which is usually not the
228    /// adapter that minted it. A Supabase service-role key is issued by the management
229    /// API and then used against the project's own host, so a captured credential filed
230    /// under its minter would be brokered to the wrong upstream.
231    pub adapter: String,
232
233    /// What to call it where a person will read it. "Supabase service role key", not
234    /// `$.service_role_key` — the dashboard has to show what we are holding in words
235    /// somebody recognises, or §8's promise that we are not a secrets store is
236    /// unverifiable in practice.
237    pub label: String,
238}
239
240#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
241#[serde(rename_all = "snake_case")]
242pub enum StreamingPolicy {
243    /// Redact streamed bodies using a boundary-overlap window.
244    #[default]
245    Redact,
246    /// Redaction cannot be guaranteed for this upstream. The relay refuses to stream it
247    /// rather than passing bytes it has not inspected.
248    Unsupported,
249}
250
251impl AdapterFile {
252    /// Parse and validate. Validation is not optional and there is no lenient mode: an
253    /// adapter that does not fully parse is an adapter whose enforcement we cannot
254    /// describe, and shipping one would mean claiming protection we cannot demonstrate.
255    pub fn parse(source: &str) -> Result<Self, AdapterError> {
256        let file: AdapterFile = toml::from_str(source)?;
257        if file.schema_version != SCHEMA_VERSION {
258            return Err(AdapterError::UnsupportedSchema {
259                found: file.schema_version,
260            });
261        }
262        for (name, adapter) in &file.adapters {
263            adapter.validate(name)?;
264        }
265
266        // A capture names the adapter its credential will be brokered through, and that
267        // adapter has to exist. Checked after every adapter is parsed rather than inside
268        // `validate`, because the target is frequently declared *below* the capture that
269        // names it and an ordering-dependent error would be a puzzle.
270        //
271        // Failing here rather than at capture time matters: the alternative is discovering
272        // it at the moment we are holding a freshly captured secret with nowhere to file
273        // it, which is the worst possible time.
274        for (name, adapter) in &file.adapters {
275            for capture in &adapter.capture {
276                if !file.adapters.contains_key(&capture.adapter) {
277                    return Err(AdapterError::Invalid {
278                        adapter: name.to_string(),
279                        message: format!(
280                            "capture `{}` files its credential under adapter `{}`, which \
281                             this file does not define",
282                            capture.label, capture.adapter
283                        ),
284                    });
285                }
286            }
287        }
288
289        Ok(file)
290    }
291}
292
293impl Adapter {
294    fn validate(&self, name: &str) -> Result<(), AdapterError> {
295        let invalid = |message: &str| AdapterError::Invalid {
296            adapter: name.to_string(),
297            message: message.to_string(),
298        };
299
300        if self.upstream.is_empty() {
301            return Err(invalid("upstream must not be empty"));
302        }
303        if self.upstream.contains("://") {
304            return Err(invalid(
305                "upstream must be a bare hostname, not a URL — the client's path is forwarded untouched",
306            ));
307        }
308        if self.upstream.contains('/') {
309            return Err(invalid("upstream must not contain a path"));
310        }
311        if self.upstream.contains(':') {
312            return Err(invalid("upstream must not contain a port"));
313        }
314        if self.auth.is_empty() {
315            return Err(invalid(
316                "at least one auth slot is required; an adapter with none would forward handles to the upstream unchanged",
317            ));
318        }
319
320        for slot in &self.auth {
321            if slot.name.is_empty() {
322                return Err(invalid("auth slot name must not be empty"));
323            }
324            if slot.location == SlotLocation::JsonBody {
325                SlotPath::parse(&slot.name).map_err(|source| AdapterError::SlotPath {
326                    adapter: name.to_string(),
327                    path: slot.name.clone(),
328                    source,
329                })?;
330            }
331        }
332
333        for capture in &self.capture {
334            if capture.adapter.is_empty() {
335                return Err(invalid(
336                    "a capture must name the adapter its credential will be used with; \
337                     without one there is no upstream to broker it to and the capture \
338                     would take custody of a secret nobody could spend",
339                ));
340            }
341            if capture.label.is_empty() {
342                return Err(invalid(
343                    "a capture must carry a label — it is what a person reads in the list \
344                     of credentials we hold on their behalf",
345                ));
346            }
347            SlotPath::parse(&capture.path).map_err(|source| AdapterError::SlotPath {
348                adapter: name.to_string(),
349                path: capture.path.clone(),
350                source,
351            })?;
352        }
353
354        for path in &self.response.redact {
355            SlotPath::parse(path).map_err(|source| AdapterError::SlotPath {
356                adapter: name.to_string(),
357                path: path.clone(),
358                source,
359            })?;
360        }
361
362        Ok(())
363    }
364
365    /// Redaction paths, pre-parsed.
366    pub fn redact_paths(&self) -> Result<Vec<SlotPath>, SlotPathError> {
367        self.response
368            .redact
369            .iter()
370            .map(|p| SlotPath::parse(p))
371            .collect()
372    }
373}
374
375#[cfg(test)]
376mod tests {
377    use super::*;
378
379    const RAILWAY: &str = r#"
380        schema_version = 1
381
382        [adapter.railway]
383        upstream = "backboard.railway.com"
384        class = 2
385
386        [[adapter.railway.auth]]
387        location = "header"
388        name = "authorization"
389        scheme = "Bearer"
390
391        [adapter.railway.response]
392        redact = ["$.data.token"]
393    "#;
394
395    #[test]
396    fn parses_the_documented_example() {
397        let file = AdapterFile::parse(RAILWAY).expect("should parse");
398        let railway = &file.adapters["railway"];
399        assert_eq!(railway.upstream, "backboard.railway.com");
400        assert_eq!(railway.auth.len(), 1);
401        assert_eq!(railway.auth[0].scheme.as_deref(), Some("Bearer"));
402        assert_eq!(railway.response.redact, vec!["$.data.token"]);
403        assert_eq!(railway.response.streaming, StreamingPolicy::Redact);
404    }
405
406    /// Anthropic carries the key bare in `x-api-key`. An adapter that invented a
407    /// `Bearer` prefix here would send `Bearer sk-...` and get a 401 that reads as a bad
408    /// credential rather than a bad adapter.
409    #[test]
410    fn scheme_is_optional_for_raw_key_headers() {
411        let file = AdapterFile::parse(
412            r#"
413            schema_version = 1
414            [adapter.anthropic]
415            upstream = "api.anthropic.com"
416            [[adapter.anthropic.auth]]
417            location = "header"
418            name = "x-api-key"
419        "#,
420        )
421        .expect("should parse");
422        assert!(file.adapters["anthropic"].auth[0].scheme.is_none());
423    }
424
425    #[test]
426    fn rejects_unknown_fields_rather_than_ignoring_them() {
427        // `redakt` would silently disable redaction if unknown fields were tolerated.
428        let err = AdapterFile::parse(
429            r#"
430            schema_version = 1
431            [adapter.x]
432            upstream = "api.example.com"
433            [[adapter.x.auth]]
434            location = "header"
435            name = "authorization"
436            [adapter.x.response]
437            redakt = ["$.token"]
438        "#,
439        )
440        .unwrap_err();
441        assert!(matches!(err, AdapterError::Toml(_)), "got {err:?}");
442    }
443
444    #[test]
445    fn rejects_upstream_that_is_a_url_or_carries_a_path_or_port() {
446        for upstream in [
447            "https://api.example.com",
448            "api.example.com/v1",
449            "api.example.com:443",
450        ] {
451            let source = format!(
452                r#"
453                schema_version = 1
454                [adapter.x]
455                upstream = "{upstream}"
456                [[adapter.x.auth]]
457                location = "header"
458                name = "authorization"
459            "#
460            );
461            assert!(
462                matches!(
463                    AdapterFile::parse(&source),
464                    Err(AdapterError::Invalid { .. })
465                ),
466                "{upstream} should be rejected"
467            );
468        }
469    }
470
471    /// An adapter with no auth slot would pass the handle straight through to the
472    /// upstream, which fails open. Reject the file instead.
473    #[test]
474    fn rejects_adapter_with_no_auth_slot() {
475        let err = AdapterFile::parse(
476            r#"
477            schema_version = 1
478            [adapter.x]
479            upstream = "api.example.com"
480            auth = []
481        "#,
482        )
483        .unwrap_err();
484        assert!(matches!(err, AdapterError::Invalid { .. }), "got {err:?}");
485    }
486
487    #[test]
488    fn rejects_future_schema_version() {
489        let err = AdapterFile::parse(
490            r#"
491            schema_version = 99
492            [adapter.x]
493            upstream = "api.example.com"
494            [[adapter.x.auth]]
495            location = "header"
496            name = "authorization"
497        "#,
498        )
499        .unwrap_err();
500        assert!(matches!(err, AdapterError::UnsupportedSchema { found: 99 }));
501    }
502
503    #[test]
504    fn rejects_malformed_redaction_path() {
505        let err = AdapterFile::parse(
506            r#"
507            schema_version = 1
508            [adapter.x]
509            upstream = "api.example.com"
510            [[adapter.x.auth]]
511            location = "header"
512            name = "authorization"
513            [adapter.x.response]
514            redact = ["data.token"]
515        "#,
516        )
517        .unwrap_err();
518        assert!(matches!(err, AdapterError::SlotPath { .. }), "got {err:?}");
519    }
520}