stygian_graph/adapters/
signing.rs

1//! Request signing adapters.
2//!
3//! Provides concrete [`crate::ports::signing::SigningPort`] implementations:
4//!
5//! | Adapter | Use case |
6//! |---|---|
7//! | [`crate::adapters::signing::NoopSigningAdapter`] | Testing / no-op passthrough |
8//! | [`crate::adapters::signing::HttpSigningAdapter`] | Delegate to any external signing sidecar over HTTP |
9//!
10//! # Frida RPC bridge example
11//!
12//! Run a Frida sidecar that exposes a POST /sign endpoint, then wire it in:
13//!
14//! ```no_run
15//! use stygian_graph::adapters::signing::{HttpSigningAdapter, HttpSigningConfig};
16//!
17//! let signer = HttpSigningAdapter::new(HttpSigningConfig {
18//!     endpoint: "http://localhost:27042/sign".to_string(),
19//!     ..Default::default()
20//! });
21//! ```
22//!
23//! # AWS Signature V4 / custom HMAC
24//!
25//! Implement [`crate::ports::signing::SigningPort`] directly, or point [`crate::adapters::signing::HttpSigningAdapter`] at a
26//! lightweight signing sidecar that handles key material and algorithm details.
27
28use std::collections::HashMap;
29use std::time::Duration;
30
31use reqwest::Client;
32use serde::{Deserialize, Serialize};
33
34use crate::ports::signing::{SigningError, SigningInput, SigningOutput, SigningPort};
35
36#[cfg(test)]
37use crate::ports::signing::ErasedSigningPort;
38
39// ─────────────────────────────────────────────────────────────────────────────
40// NoopSigningAdapter
41// ─────────────────────────────────────────────────────────────────────────────
42
43/// A no-op [`SigningPort`] that passes requests through unsigned.
44///
45/// Useful as a default when an adapter accepts an optional signer, and as a
46/// stand-in during testing.
47///
48/// # Example
49///
50/// ```rust
51/// use stygian_graph::adapters::signing::NoopSigningAdapter;
52/// use stygian_graph::ports::signing::{SigningPort, SigningInput};
53/// use serde_json::json;
54///
55/// # tokio::runtime::Runtime::new().unwrap().block_on(async {
56/// let signer = NoopSigningAdapter;
57/// let output = signer.sign(SigningInput {
58///     method: "GET".to_string(),
59///     url: "https://example.com".to_string(),
60///     headers: Default::default(),
61///     body: None,
62///     context: json!({}),
63/// }).await.unwrap();
64/// assert!(output.headers.is_empty());
65/// # });
66/// ```
67pub struct NoopSigningAdapter;
68
69impl SigningPort for NoopSigningAdapter {
70    async fn sign(&self, _input: SigningInput) -> Result<SigningOutput, SigningError> {
71        Ok(SigningOutput::default())
72    }
73}
74
75// ─────────────────────────────────────────────────────────────────────────────
76// HttpSigningAdapter
77// ─────────────────────────────────────────────────────────────────────────────
78
79/// Configuration for [`HttpSigningAdapter`].
80///
81/// # Example
82///
83/// ```rust
84/// use stygian_graph::adapters::signing::HttpSigningConfig;
85/// use std::time::Duration;
86///
87/// let config = HttpSigningConfig {
88///     endpoint: "http://localhost:27042/sign".to_string(),
89///     timeout: Duration::from_secs(5),
90///     bearer_token: Some("my-sidecar-auth-token".to_string()),
91///     extra_headers: Default::default(),
92/// };
93/// ```
94#[derive(Debug, Clone)]
95pub struct HttpSigningConfig {
96    /// Full URL of the signing sidecar endpoint (e.g. `http://localhost:27042/sign`)
97    pub endpoint: String,
98    /// Request timeout to the signing sidecar (default: 10 seconds)
99    pub timeout: Duration,
100    /// Optional bearer token to authenticate with the sidecar itself
101    pub bearer_token: Option<String>,
102    /// Additional static headers to send to the sidecar
103    pub extra_headers: HashMap<String, String>,
104}
105
106impl Default for HttpSigningConfig {
107    fn default() -> Self {
108        Self {
109            endpoint: "http://localhost:27042/sign".to_string(),
110            timeout: Duration::from_secs(10),
111            bearer_token: None,
112            extra_headers: HashMap::new(),
113        }
114    }
115}
116
117/// Wire format for the signing request sent to the sidecar.
118#[derive(Debug, Serialize)]
119struct SignRequest {
120    method: String,
121    url: String,
122    headers: HashMap<String, String>,
123    #[serde(skip_serializing_if = "Option::is_none")]
124    body_b64: Option<String>,
125    context: serde_json::Value,
126}
127
128/// Wire format for the signing response received from the sidecar.
129#[derive(Debug, Deserialize)]
130struct SignResponse {
131    #[serde(default)]
132    headers: HashMap<String, String>,
133    #[serde(default)]
134    query_params: Vec<(String, String)>,
135    #[serde(default)]
136    body_b64: Option<String>,
137}
138
139/// A [`SigningPort`] that delegates to an external HTTP signing sidecar.
140///
141/// The sidecar receives a JSON payload describing the outbound request and
142/// returns the headers / query params / body override to apply. This pattern
143/// works for:
144///
145/// - **Frida RPC bridges** — a Python/Node sidecar attached to a running mobile
146///   app that calls the native `.so` signing function and exposes the result
147/// - **AWS Signature V4** — a lightweight server that knows your AWS credentials
148/// - **OAuth 1.0a** — sign Twitter/X API v1 requests via a sidecar that holds
149///   the consumer secret
150/// - **Any custom HMAC scheme** — keep key material out of the main process
151///
152/// # Example
153///
154/// ```no_run
155/// use stygian_graph::adapters::signing::{HttpSigningAdapter, HttpSigningConfig};
156/// use stygian_graph::ports::signing::{SigningPort, SigningInput};
157/// use serde_json::json;
158///
159/// # tokio::runtime::Runtime::new().unwrap().block_on(async {
160/// let signer = HttpSigningAdapter::new(HttpSigningConfig {
161///     endpoint: "http://localhost:27042/sign".to_string(),
162///     ..Default::default()
163/// });
164///
165/// let output = signer.sign(SigningInput {
166///     method: "GET".to_string(),
167///     url: "https://api.tinder.com/v2/profile".to_string(),
168///     headers: Default::default(),
169///     body: None,
170///     context: json!({}),
171/// }).await.unwrap();
172///
173/// for (k, v) in &output.headers {
174///     println!("{k}: {v}");
175/// }
176/// # });
177/// ```
178pub struct HttpSigningAdapter {
179    config: HttpSigningConfig,
180    client: Client,
181}
182
183impl HttpSigningAdapter {
184    /// Create a new `HttpSigningAdapter` with the given configuration.
185    ///
186    /// # Example
187    ///
188    /// ```no_run
189    /// use stygian_graph::adapters::signing::{HttpSigningAdapter, HttpSigningConfig};
190    ///
191    /// let signer = HttpSigningAdapter::new(HttpSigningConfig::default());
192    /// ```
193    pub fn new(config: HttpSigningConfig) -> Self {
194        let client = Client::builder()
195            .timeout(config.timeout)
196            .build()
197            .unwrap_or_default();
198        Self { config, client }
199    }
200}
201
202impl SigningPort for HttpSigningAdapter {
203    async fn sign(&self, input: SigningInput) -> Result<SigningOutput, SigningError> {
204        let body_b64 = input.body.as_deref().map(base64_encode);
205
206        let req_body = SignRequest {
207            method: input.method,
208            url: input.url,
209            headers: input.headers,
210            body_b64,
211            context: input.context,
212        };
213
214        let mut req = self.client.post(&self.config.endpoint).json(&req_body);
215
216        if let Some(token) = &self.config.bearer_token {
217            req = req.bearer_auth(token);
218        }
219        for (k, v) in &self.config.extra_headers {
220            req = req.header(k, v);
221        }
222
223        let response = req.send().await.map_err(|e| {
224            if e.is_timeout() {
225                SigningError::Timeout(
226                    self.config
227                        .timeout
228                        .as_millis()
229                        .try_into()
230                        .unwrap_or(u64::MAX),
231                )
232            } else {
233                SigningError::BackendUnavailable(e.to_string())
234            }
235        })?;
236
237        if !response.status().is_success() {
238            let status = response.status().as_u16();
239            let body = response.text().await.unwrap_or_default();
240            return Err(SigningError::InvalidResponse(format!(
241                "sidecar returned HTTP {status}: {body}"
242            )));
243        }
244
245        let sign_resp: SignResponse = response
246            .json()
247            .await
248            .map_err(|e| SigningError::InvalidResponse(e.to_string()))?;
249
250        let body_override = sign_resp
251            .body_b64
252            .map(|b64| base64_decode(&b64))
253            .transpose()
254            .map_err(|e| SigningError::InvalidResponse(format!("base64 decode failed: {e}")))?;
255
256        Ok(SigningOutput {
257            headers: sign_resp.headers,
258            query_params: sign_resp.query_params,
259            body_override,
260        })
261    }
262}
263
264// ─────────────────────────────────────────────────────────────────────────────
265// Base64 helpers (std-only, no extra deps)
266// ─────────────────────────────────────────────────────────────────────────────
267
268fn base64_encode(input: &[u8]) -> String {
269    use std::fmt::Write;
270    const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
271    let mut out = String::with_capacity(input.len().div_ceil(3) * 4);
272    for chunk in input.chunks(3) {
273        let b0 = usize::from(*chunk.first().unwrap_or(&0));
274        let b1 = if chunk.len() > 1 {
275            usize::from(*chunk.get(1).unwrap_or(&0))
276        } else {
277            0
278        };
279        let b2 = if chunk.len() > 2 {
280            usize::from(*chunk.get(2).unwrap_or(&0))
281        } else {
282            0
283        };
284        let first = TABLE.get(b0 >> 2).copied().unwrap_or_default();
285        let second = TABLE
286            .get(((b0 & 3) << 4) | (b1 >> 4))
287            .copied()
288            .unwrap_or_default();
289        let _ = write!(out, "{}", char::from(first));
290        let _ = write!(out, "{}", char::from(second));
291        if chunk.len() > 1 {
292            let third = TABLE
293                .get(((b1 & 0xf) << 2) | (b2 >> 6))
294                .copied()
295                .unwrap_or_default();
296            let _ = write!(out, "{}", char::from(third));
297        } else {
298            out.push('=');
299        }
300        if chunk.len() > 2 {
301            let fourth = TABLE.get(b2 & 0x3f).copied().unwrap_or_default();
302            let _ = write!(out, "{}", char::from(fourth));
303        } else {
304            out.push('=');
305        }
306    }
307    out
308}
309
310fn base64_decode(input: &str) -> Result<Vec<u8>, String> {
311    let input = input.trim_end_matches('=');
312    let mut out = Vec::with_capacity(input.len() * 3 / 4 + 1);
313    let decode_char = |c: u8| -> Result<u8, String> {
314        match c {
315            b'A'..=b'Z' => Ok(c - b'A'),
316            b'a'..=b'z' => Ok(c - b'a' + 26),
317            b'0'..=b'9' => Ok(c - b'0' + 52),
318            b'+' => Ok(62),
319            b'/' => Ok(63),
320            _ => Err(format!("invalid base64 char: {c}")),
321        }
322    };
323    let bytes = input.as_bytes();
324    let mut i = 0;
325    while i + 1 < bytes.len() {
326        let v0 = decode_char(*bytes.get(i).unwrap_or(&0))?;
327        let v1 = decode_char(*bytes.get(i + 1).unwrap_or(&0))?;
328        out.push((v0 << 2) | (v1 >> 4));
329        if i + 2 < bytes.len() {
330            let v2 = decode_char(*bytes.get(i + 2).unwrap_or(&0))?;
331            out.push(((v1 & 0xf) << 4) | (v2 >> 2));
332            if i + 3 < bytes.len() {
333                let v3 = decode_char(*bytes.get(i + 3).unwrap_or(&0))?;
334                out.push(((v2 & 3) << 6) | v3);
335            }
336        }
337        i += 4;
338    }
339    Ok(out)
340}
341
342// ─────────────────────────────────────────────────────────────────────────────
343// Tests
344// ─────────────────────────────────────────────────────────────────────────────
345
346#[cfg(test)]
347mod tests {
348    use super::*;
349    use serde_json::json;
350
351    #[tokio::test]
352    async fn noop_returns_empty_output() -> std::result::Result<(), Box<dyn std::error::Error>> {
353        let signer = NoopSigningAdapter;
354        let output = signer
355            .sign(SigningInput {
356                method: "GET".to_string(),
357                url: "https://example.com".to_string(),
358                headers: HashMap::new(),
359                body: None,
360                context: json!({}),
361            })
362            .await?;
363        assert!(output.headers.is_empty());
364        assert!(output.query_params.is_empty());
365        assert!(output.body_override.is_none());
366        Ok(())
367    }
368
369    #[tokio::test]
370    async fn noop_is_erased_signing_port() -> std::result::Result<(), Box<dyn std::error::Error>> {
371        let signer: std::sync::Arc<dyn ErasedSigningPort> = std::sync::Arc::new(NoopSigningAdapter);
372        let output = signer
373            .erased_sign(SigningInput {
374                method: "POST".to_string(),
375                url: "https://api.example.com/data".to_string(),
376                headers: HashMap::new(),
377                body: Some(b"{\"key\":\"val\"}".to_vec()),
378                context: json!({"session": "abc"}),
379            })
380            .await?;
381        assert!(output.headers.is_empty());
382        Ok(())
383    }
384
385    #[test]
386    fn base64_roundtrip() -> std::result::Result<(), Box<dyn std::error::Error>> {
387        let input = b"Hello, Stygian signing!";
388        let encoded = base64_encode(input);
389        let decoded = base64_decode(&encoded)
390            .map_err(|e| std::io::Error::other(format!("base64 decode failed: {e}")))?;
391        assert_eq!(decoded, input);
392        Ok(())
393    }
394
395    #[test]
396    fn base64_encode_known_value() {
397        // RFC 4648 test vector
398        assert_eq!(base64_encode(b"Man"), "TWFu");
399        assert_eq!(base64_encode(b"Ma"), "TWE=");
400        assert_eq!(base64_encode(b"M"), "TQ==");
401    }
402}
stygian_graph/adapters/signing.rs

stygian_graph/adapters/
signing.rs
