1use std::collections::HashMap;
5use std::sync::{Arc, Condvar, Mutex};
6use std::thread;
7use std::time::{Duration, Instant};
8
9use serde_json::{json, Map, Value};
10
11use crate::error::{err, SamlError};
12use crate::events::{default_ending_events, default_events_requested, event, string_of, subject_of};
13use crate::http::{send, TlsOptions};
14use crate::jws::verify_compact_jws;
15use crate::response::SamlLogin;
16use crate::session::{tracked_from, MemorySessionIndex};
17
18const POLL_METHOD: &str = "urn:ietf:rfc:8936";
19
20pub trait Logger: Send + Sync {
22 fn info(&self, message: &str);
23 fn warn(&self, message: &str);
24 fn error(&self, message: &str);
25}
26
27struct PrintLogger;
28impl Logger for PrintLogger {
29 fn info(&self, message: &str) { println!("{message}"); }
30 fn warn(&self, message: &str) { println!("{message}"); }
31 fn error(&self, message: &str) { println!("{message}"); }
32}
33
34#[derive(Clone, Debug)]
36pub struct SignalEvent {
37 pub event_type: String,
38 pub payload: Map<String, Value>,
39 pub subject: HashMap<String, String>,
40 pub jti: String,
41 pub sessions: Vec<String>,
42 pub ended: bool,
43 pub iat: Option<f64>,
44 pub txn: Option<String>,
45}
46
47type Handler = Arc<dyn Fn(&SignalEvent) -> Result<(), SamlError> + Send + Sync>;
48type EndFn = Arc<dyn Fn(&[String], &SignalEvent) -> Result<(), SamlError> + Send + Sync>;
49
50pub struct ReceiverOptions {
52 pub transmitter: String,
53 pub on_end_sessions: Option<EndFn>,
54 pub tls: Option<TlsOptions>,
55 pub headers: Option<Arc<dyn Fn() -> Vec<(String, String)> + Send + Sync>>,
56 pub events_requested: Option<Vec<String>>,
57 pub end_on: Option<Vec<String>>,
58 pub session_index: Option<Arc<MemorySessionIndex>>,
59 pub subject_attribute: String,
60 pub description: String,
61 pub poll_interval_ms: u64,
62 pub max_events: u64,
63 pub log: Option<Arc<dyn Logger>>,
64}
65
66impl Default for ReceiverOptions {
67 fn default() -> Self {
68 Self {
69 transmitter: String::new(),
70 on_end_sessions: None,
71 tls: None,
72 headers: None,
73 events_requested: None,
74 end_on: None,
75 session_index: None,
76 subject_attribute: String::new(),
77 description: String::new(),
78 poll_interval_ms: 0,
79 max_events: 0,
80 log: None,
81 }
82 }
83}
84
85struct Flight {
86 result: Mutex<Option<Result<bool, SamlError>>>,
87 cv: Condvar,
88}
89
90struct Gate {
91 count: Mutex<i32>,
92 cv: Condvar,
93}
94
95impl Gate {
96 fn new() -> Self { Self { count: Mutex::new(0), cv: Condvar::new() } }
97 fn add(&self) { *self.count.lock().expect("gate") += 1; }
98 fn done(&self) {
99 let mut count = self.count.lock().expect("gate");
100 *count -= 1;
101 if *count == 0 { self.cv.notify_all(); }
102 }
103 fn wait(&self) {
104 let mut count = self.count.lock().expect("gate");
105 while *count > 0 {
106 count = self.cv.wait(count).expect("gate");
107 }
108 }
109}
110
111struct State {
112 config: Map<String, Value>,
113 stream: Map<String, Value>,
114 keys: Vec<Map<String, Value>>,
115 keys_at: Option<Instant>,
116 ack: Vec<String>,
117 errs: Map<String, Value>,
118 handlers: HashMap<String, Vec<Handler>>,
119}
120
121struct Sched {
122 running: bool,
123 generation: u64,
124 inflight: Option<Arc<Flight>>,
125}
126
127struct Inner {
128 transmitter: String,
129 on_end: EndFn,
130 tls: Option<TlsOptions>,
131 headers: Option<Arc<dyn Fn() -> Vec<(String, String)> + Send + Sync>>,
132 events_requested: Vec<String>,
133 end_on: HashMap<String, bool>,
134 index: Arc<MemorySessionIndex>,
135 subject_attribute: String,
136 description: String,
137 poll_interval: Duration,
138 max_events: u64,
139 log: Arc<dyn Logger>,
140 state: Mutex<State>,
141 sched: Mutex<Sched>,
142 gate: Gate,
143}
144
145#[derive(Clone)]
147pub struct SignalsReceiver {
148 inner: Arc<Inner>,
149}
150
151impl SignalsReceiver {
152 pub fn new(opt: ReceiverOptions) -> Result<Self, SamlError> {
154 let on_end = opt.on_end_sessions.ok_or_else(|| err("config", "onEndSessions is required"))?;
155 if !(opt.transmitter.starts_with("http://") || opt.transmitter.starts_with("https://")) {
156 return Err(err("config", "transmitter must be an http(s) URL"));
157 }
158 let interval = if opt.poll_interval_ms == 0 { 5000 } else { opt.poll_interval_ms };
159 let max_events = if opt.max_events == 0 { 50 } else { opt.max_events };
160 let requested = opt.events_requested.unwrap_or_else(default_events_requested);
161 let ending = opt.end_on.unwrap_or_else(default_ending_events);
162 let mut end_on = HashMap::new();
163 for item in ending {
164 end_on.insert(item, true);
165 }
166 let index = opt.session_index.unwrap_or_else(|| Arc::new(MemorySessionIndex::new(0)));
167 let log = opt.log.unwrap_or_else(|| Arc::new(PrintLogger));
168 Ok(Self {
169 inner: Arc::new(Inner {
170 transmitter: opt.transmitter.trim_end_matches('/').to_string(),
171 on_end,
172 tls: opt.tls,
173 headers: opt.headers,
174 events_requested: requested,
175 end_on,
176 index,
177 subject_attribute: opt.subject_attribute,
178 description: opt.description,
179 poll_interval: Duration::from_millis(interval),
180 max_events,
181 log,
182 state: Mutex::new(State {
183 config: Map::new(),
184 stream: Map::new(),
185 keys: Vec::new(),
186 keys_at: None,
187 ack: Vec::new(),
188 errs: Map::new(),
189 handlers: HashMap::new(),
190 }),
191 sched: Mutex::new(Sched { running: false, generation: 0, inflight: None }),
192 gate: Gate::new(),
193 }),
194 })
195 }
196
197 pub fn track(&self, local_id: &str, login: &SamlLogin, expires_at_ms: Option<i64>) {
198 self.inner.index.add(tracked_from(local_id, login, &self.inner.subject_attribute, expires_at_ms));
199 }
200
201 pub fn untrack(&self, local_id: &str) {
202 self.inner.index.remove(local_id);
203 }
204
205 pub fn on<F>(&self, event_type: &str, handler: F) -> &Self
206 where
207 F: Fn(&SignalEvent) -> Result<(), SamlError> + Send + Sync + 'static,
208 {
209 self.inner.state.lock().expect("state").handlers.entry(event_type.to_string()).or_default().push(Arc::new(handler));
210 self
211 }
212
213 pub fn stream(&self) -> Map<String, Value> {
214 self.inner.state.lock().expect("state").stream.clone()
215 }
216
217 pub fn start(&self) -> Result<(), SamlError> {
219 {
220 let sched = self.inner.sched.lock().expect("sched");
221 if sched.running {
222 return Ok(());
223 }
224 }
225 let config = self.discover()?;
226 self.inner.state.lock().expect("state").config = config;
227 self.jwks(true)?;
228 let stream = self.ensure_stream()?;
229 let endpoint = stream.get("delivery").and_then(|d| d.get("endpoint_url")).and_then(|v| v.as_str()).unwrap_or("");
230 if endpoint.is_empty() {
231 return Err(err("ssf", "the stream has no poll endpoint_url"));
232 }
233 {
234 let mut sched = self.inner.sched.lock().expect("sched");
235 if sched.running {
236 return Ok(());
237 }
238 self.inner.state.lock().expect("state").stream = stream.clone();
239 sched.running = true;
240 }
241 let delivered = stream.get("events_delivered").and_then(|v| v.as_array()).map(|a| a.len()).unwrap_or(0);
242 let stream_id = string_of(stream.get("stream_id").unwrap_or(&Value::Null));
243 self.inner.log.info(&format!("ssf: polling stream {stream_id} at {endpoint}, delivering {delivered} event type(s)"));
244 self.iteration();
245 Ok(())
246 }
247
248 pub fn stop(&self) {
250 {
251 let mut sched = self.inner.sched.lock().expect("sched");
252 sched.running = false;
253 sched.generation += 1;
254 }
255 self.inner.gate.wait();
256 }
257
258 fn iteration(&self) {
259 {
260 let sched = self.inner.sched.lock().expect("sched");
261 if !sched.running {
262 return;
263 }
264 self.inner.gate.add();
265 }
266 let mut delay = self.inner.poll_interval;
267 match self.poll_once() {
268 Err(error) => {
269 self.inner.log.warn(&format!("ssf: poll failed: {error}"));
270 delay = (self.inner.poll_interval * 4).min(Duration::from_secs(60));
271 }
272 Ok(true) => delay = Duration::ZERO,
273 Ok(false) => {}
274 }
275 let generation = {
276 let mut sched = self.inner.sched.lock().expect("sched");
277 if !sched.running {
278 self.inner.gate.done();
279 return;
280 }
281 sched.generation += 1;
282 sched.generation
283 };
284 let again = self.clone();
285 thread::spawn(move || {
286 if !delay.is_zero() {
287 thread::sleep(delay);
288 }
289 let go = {
290 let sched = again.inner.sched.lock().expect("sched");
291 sched.running && sched.generation == generation
292 };
293 if go {
294 again.iteration();
295 }
296 });
297 self.inner.gate.done();
298 }
299
300 pub fn poll_once(&self) -> Result<bool, SamlError> {
302 let existing = {
303 let mut sched = self.inner.sched.lock().expect("sched");
304 if let Some(current) = &sched.inflight {
305 Some(current.clone())
306 } else {
307 let flight = Arc::new(Flight { result: Mutex::new(None), cv: Condvar::new() });
308 sched.inflight = Some(flight.clone());
309 None
310 }
311 };
312 if let Some(current) = existing {
313 let mut slot = current.result.lock().expect("flight");
314 while slot.is_none() {
315 slot = current.cv.wait(slot).expect("flight");
316 }
317 return slot.clone().unwrap();
318 }
319 let result = self.poll_now();
320 let flight = self.inner.sched.lock().expect("sched").inflight.clone();
321 if let Some(flight) = flight {
322 let mut slot = flight.result.lock().expect("flight");
323 *slot = Some(result.clone());
324 flight.cv.notify_all();
325 }
326 self.inner.sched.lock().expect("sched").inflight = None;
327 result
328 }
329
330 fn poll_now(&self) -> Result<bool, SamlError> {
331 let (url, ack, set_errs) = {
332 let mut state = self.inner.state.lock().expect("state");
333 let url = state.stream.get("delivery").and_then(|d| d.get("endpoint_url")).and_then(|v| v.as_str()).unwrap_or("").to_string();
334 let ack = std::mem::take(&mut state.ack);
335 let set_errs = std::mem::take(&mut state.errs);
336 (url, ack, set_errs)
337 };
338 let mut body = Map::new();
339 body.insert("maxEvents".to_string(), json!(self.inner.max_events));
340 body.insert("returnImmediately".to_string(), Value::Bool(true));
341 if !ack.is_empty() {
342 body.insert("ack".to_string(), Value::Array(ack.iter().cloned().map(Value::String).collect()));
343 }
344 if !set_errs.is_empty() {
345 body.insert("setErrs".to_string(), Value::Object(set_errs.clone()));
346 }
347 let sent = self.call("POST", &url, Some(&Value::Object(body)));
348 let (status, parsed) = match sent {
349 Ok(value) => value,
350 Err(error) => {
351 self.restore(ack, set_errs);
352 return Err(error);
353 }
354 };
355 if status != 200 {
356 self.restore(ack, set_errs);
357 let mut text = parsed.to_string();
358 if text.len() > 300 { text.truncate(300); }
359 return Err(err("ssf", format!("the poll answered {status}: {text}")));
360 }
361 let sets = parsed.get("sets").and_then(|v| v.as_object()).cloned().unwrap_or_default();
362 for (jti, token) in sets {
363 let token = string_of(&token);
364 if let Err(error) = self.handle(&jti, &token) {
365 let description = error.to_string();
366 self.inner.log.warn(&format!("ssf: SET {jti} refused: {description}"));
367 let kind = if error.code == "signature" { "invalid_key" } else { "invalid_request" };
368 self.inner.state.lock().expect("state").errs.insert(jti, json!({"err": kind, "description": description}));
369 continue;
370 }
371 self.inner.state.lock().expect("state").ack.push(jti);
372 }
373 Ok(parsed.get("moreAvailable").and_then(|v| v.as_bool()).unwrap_or(false))
374 }
375
376 fn restore(&self, ack: Vec<String>, set_errs: Map<String, Value>) {
377 let mut state = self.inner.state.lock().expect("state");
378 let mut merged = ack;
379 merged.append(&mut state.ack);
380 state.ack = merged;
381 let mut errs = set_errs;
382 let current = std::mem::take(&mut state.errs);
383 for (k, v) in current {
384 errs.insert(k, v);
385 }
386 state.errs = errs;
387 }
388
389 fn handle(&self, jti: &str, token: &str) -> Result<(), SamlError> {
390 let keys = self.jwks(false)?;
391 let verified = match verify_compact_jws(token, &keys) {
392 Ok(value) => Ok(value),
393 Err(error) => {
394 if error.code == "signature" && (error.message.contains("publishes no") || error.message.contains("does not verify")) {
395 let keys = self.jwks(true).map_err(|_| error.clone())?;
396 verify_compact_jws(token, &keys)
397 } else {
398 Err(error)
399 }
400 }
401 };
402 let (header, payload) = verified?;
403 if header.get("typ").is_some() && string_of(header.get("typ").unwrap()).to_ascii_lowercase() != "secevent+jwt" {
404 return Err(err("validation", format!("the SET's typ is {}", string_of(header.get("typ").unwrap()))));
405 }
406 let (issuer, want) = {
407 let state = self.inner.state.lock().expect("state");
408 (string_of(state.config.get("issuer").unwrap_or(&Value::Null)), state.stream.get("aud").cloned())
409 };
410 if string_of(payload.get("iss").unwrap_or(&Value::Null)) != issuer {
411 return Err(err("validation", format!("the SET was issued by {}, not {issuer}", string_of(payload.get("iss").unwrap_or(&Value::Null)))));
412 }
413 let wanted = audience_list(want.as_ref());
414 let audience = audience_list(payload.get("aud"));
415 if !wanted.is_empty() && !audience.iter().any(|item| wanted.iter().any(|allowed| item == allowed)) {
416 return Err(err("validation", format!("the SET is for {}, not this stream", audience.join(", "))));
417 }
418 if payload.get("jti").is_some() && string_of(payload.get("jti").unwrap()) != jti {
419 return Err(err("validation", "the SET's jti is not the one it was delivered under"));
420 }
421 let events = payload.get("events").and_then(|v| v.as_object()).cloned().unwrap_or_default();
422 if events.is_empty() {
423 return Err(err("validation", "the SET carries no events"));
424 }
425 for (event_type, raw_body) in events {
426 let body = raw_body.as_object().cloned().unwrap_or_default();
427 let subject_source = if payload.get("sub_id").is_some() {
428 payload.get("sub_id").cloned().unwrap_or(Value::Null)
429 } else {
430 body.get("subject").cloned().unwrap_or(Value::Null)
431 };
432 let subject = subject_of(&subject_source, &issuer);
433 let sessions = self.sessions_for(&event_type, &subject);
434 let mut ends = self.inner.end_on.get(&event_type).copied().unwrap_or(false) && !sessions.is_empty();
435 let iat = payload.get("iat").and_then(|v| v.as_f64());
436 let txn = payload.get("txn").and_then(|v| v.as_str()).map(str::to_string);
437 let mut signal = SignalEvent {
438 event_type: event_type.clone(),
439 payload: body,
440 subject,
441 jti: jti.to_string(),
442 sessions: sessions.clone(),
443 ended: ends,
444 iat,
445 txn,
446 };
447 if ends {
448 if let Err(error) = (self.inner.on_end)(&sessions, &signal) {
449 self.inner.log.error(&format!("ssf: onEndSessions threw for {event_type} (SET {jti} is still acknowledged): {error}"));
450 ends = false;
451 signal.ended = false;
452 }
453 if ends {
454 for local_id in &sessions {
455 self.inner.index.remove(local_id);
456 }
457 }
458 }
459 let handlers = {
460 let state = self.inner.state.lock().expect("state");
461 let mut handlers = state.handlers.get(&event_type).cloned().unwrap_or_default();
462 if let Some(star) = state.handlers.get("*") {
463 handlers.extend(star.iter().cloned());
464 }
465 handlers
466 };
467 for handler in handlers {
468 if let Err(error) = handler(&signal) {
469 self.inner.log.error(&format!("ssf: a handler for {event_type} threw (SET {jti} is still acknowledged): {error}"));
470 }
471 }
472 }
473 Ok(())
474 }
475
476 fn sessions_for(&self, event_type: &str, subject: &HashMap<String, String>) -> Vec<String> {
477 if event_type == event("verification") || event_type == event("stream_updated") {
478 return Vec::new();
479 }
480 if let Some(idp_session) = subject.get("idp_session").filter(|s| !s.is_empty()) {
481 let found = self.inner.index.by_idp_session(idp_session);
482 if !found.is_empty() || event_type == event("session_revoked") {
483 return found;
484 }
485 }
486 if let Some(person) = subject.get("person").filter(|s| !s.is_empty()) {
487 return self.inner.index.by_person(person);
488 }
489 if let Some(email) = subject.get("email").filter(|s| !s.is_empty()) {
490 return self.inner.index.by_email(email);
491 }
492 Vec::new()
493 }
494
495 pub fn verify(&self, state_value: &str) -> Result<(), SamlError> {
497 let (endpoint, stream_id) = {
498 let state = self.inner.state.lock().expect("state");
499 (
500 string_of(state.config.get("verification_endpoint").unwrap_or(&Value::Null)),
501 string_of(state.stream.get("stream_id").unwrap_or(&Value::Null)),
502 )
503 };
504 if endpoint.is_empty() {
505 return Err(err("ssf", "the transmitter publishes no verification_endpoint"));
506 }
507 let mut body = Map::new();
508 body.insert("stream_id".to_string(), Value::String(stream_id));
509 if !state_value.is_empty() {
510 body.insert("state".to_string(), Value::String(state_value.to_string()));
511 }
512 let (status, _) = self.call("POST", &endpoint, Some(&Value::Object(body)))?;
513 if status != 200 && status != 204 {
514 return Err(err("ssf", format!("verification answered {status}")));
515 }
516 Ok(())
517 }
518
519 fn call(&self, method: &str, raw_url: &str, body: Option<&Value>) -> Result<(u16, Value), SamlError> {
520 let mut headers = vec![("accept".to_string(), "application/json".to_string())];
521 if let Some(extra) = &self.inner.headers {
522 for (key, value) in extra() {
523 headers.push((key, value));
524 }
525 }
526 let payload = if let Some(body) = body {
527 headers.push(("content-type".to_string(), "application/json".to_string()));
528 body.to_string()
529 } else {
530 String::new()
531 };
532 let header_refs: Vec<(&str, &str)> = headers.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
533 let answer = send(raw_url, method, &header_refs, &payload, self.inner.tls.as_ref(), "ssf")?;
534 let parsed = if answer.body.is_empty() {
535 Value::Null
536 } else {
537 serde_json::from_str(&answer.body).unwrap_or(Value::String(answer.body))
538 };
539 Ok((answer.status, parsed))
540 }
541
542 fn discover(&self) -> Result<Map<String, Value>, SamlError> {
543 let url = format!("{}/.well-known/ssf-configuration", self.inner.transmitter);
544 let (status, parsed) = self.call("GET", &url, None)?;
545 let config = parsed.as_object().cloned().unwrap_or_default();
546 if status != 200 || string_of(config.get("configuration_endpoint").unwrap_or(&Value::Null)).is_empty() || string_of(config.get("jwks_uri").unwrap_or(&Value::Null)).is_empty() {
547 return Err(err("ssf", format!("{url} answered {status} without a usable transmitter configuration")));
548 }
549 if let Some(supported) = config.get("delivery_methods_supported").and_then(|v| v.as_array()) {
550 if !supported.is_empty() && !supported.iter().any(|item| string_of(item) == POLL_METHOD) {
551 return Err(err("ssf", "the transmitter does not offer poll delivery (RFC 8936)"));
552 }
553 }
554 Ok(config)
555 }
556
557 fn jwks(&self, force: bool) -> Result<Vec<Map<String, Value>>, SamlError> {
558 let cached = {
559 let state = self.inner.state.lock().expect("state");
560 if !force && !state.keys.is_empty() && state.keys_at.is_some_and(|at| at.elapsed() < Duration::from_secs(3600)) {
561 Some(state.keys.clone())
562 } else {
563 None
564 }
565 };
566 if let Some(keys) = cached {
567 return Ok(keys);
568 }
569 let uri = string_of(self.inner.state.lock().expect("state").config.get("jwks_uri").unwrap_or(&Value::Null));
570 let (status, parsed) = self.call("GET", &uri, None)?;
571 let raw = parsed.get("keys").and_then(|v| v.as_array()).cloned();
572 let Some(raw) = raw else {
573 return Err(err("ssf", format!("the transmitter's JWKS answered {status}")));
574 };
575 if status != 200 {
576 return Err(err("ssf", format!("the transmitter's JWKS answered {status}")));
577 }
578 let keys: Vec<Map<String, Value>> = raw.into_iter().filter_map(|item| item.as_object().cloned()).collect();
579 let mut state = self.inner.state.lock().expect("state");
580 state.keys = keys.clone();
581 state.keys_at = Some(Instant::now());
582 Ok(keys)
583 }
584
585 fn ensure_stream(&self) -> Result<Map<String, Value>, SamlError> {
586 let endpoint = string_of(self.inner.state.lock().expect("state").config.get("configuration_endpoint").unwrap_or(&Value::Null));
587 let (status, parsed) = self.call("GET", &endpoint, None)?;
588 if status == 200 {
589 let all: Vec<Value> = match &parsed {
590 Value::Array(items) => items.clone(),
591 Value::Object(_) => vec![parsed.clone()],
592 _ => Vec::new(),
593 };
594 for item in all {
595 let Some(stream) = item.as_object() else { continue };
596 if string_of(stream.get("stream_id").unwrap_or(&Value::Null)).is_empty() {
597 continue;
598 }
599 let method = stream.get("delivery").and_then(|d| d.get("method")).map(string_of).unwrap_or_default();
600 if method == POLL_METHOD {
601 return Ok(stream.clone());
602 }
603 }
604 } else if status != 404 {
605 let mut text = parsed.to_string();
606 if text.len() > 300 { text.truncate(300); }
607 return Err(err("ssf", format!("listing the streams at {endpoint} answered {status}: {text}")));
608 }
609 let mut body = Map::new();
610 body.insert("delivery".to_string(), json!({"method": POLL_METHOD}));
611 body.insert("events_requested".to_string(), Value::Array(self.inner.events_requested.iter().cloned().map(Value::String).collect()));
612 if !self.inner.description.is_empty() {
613 body.insert("description".to_string(), Value::String(self.inner.description.clone()));
614 }
615 let (created_status, created) = self.call("POST", &endpoint, Some(&Value::Object(body)))?;
616 let stream = created.as_object().cloned().unwrap_or_default();
617 if (created_status != 200 && created_status != 201) || string_of(stream.get("stream_id").unwrap_or(&Value::Null)).is_empty() {
618 let mut text = created.to_string();
619 if text.len() > 300 { text.truncate(300); }
620 return Err(err("ssf", format!("creating a stream at {endpoint} answered {created_status}: {text}")));
621 }
622 Ok(stream)
623 }
624}
625
626fn audience_list(value: Option<&Value>) -> Vec<String> {
627 match value {
628 Some(Value::Array(items)) => items.iter().map(string_of).filter(|s| !s.is_empty()).collect(),
629 Some(Value::String(text)) if !text.is_empty() => vec![text.clone()],
630 Some(Value::Null) | None => Vec::new(),
631 Some(other) => vec![other.to_string()],
632 }
633}