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}