use crate::time::Duration;
use std::collections::{BTreeMap, HashMap};
use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use base64::Engine as _;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use jsonwebtoken::{Algorithm, DecodingKey, Validation, decode};
use serde::Serialize;
use serde_json::{Map, Value};
use crate::client::{AxiamClient, OmitBrowserCredentials};
use crate::error::{AxiamError, SetFailureReason};
use crate::sensitive::Sensitive;
use crate::token::jwks::JwksVerifier;
pub const MIN_REPLAY_WINDOW: Duration = Duration::from_secs(7 * 24 * 60 * 60);
pub mod event_types {
pub const SESSION_REVOKED: &str =
"https://schemas.openid.net/secevent/caep/event-type/session-revoked";
pub const CREDENTIAL_CHANGE: &str =
"https://schemas.openid.net/secevent/caep/event-type/credential-change";
pub const ASSURANCE_LEVEL_CHANGE: &str =
"https://schemas.openid.net/secevent/caep/event-type/assurance-level-change";
pub const ACCOUNT_DISABLED: &str =
"https://schemas.openid.net/secevent/risc/event-type/account-disabled";
pub const ACCOUNT_ENABLED: &str =
"https://schemas.openid.net/secevent/risc/event-type/account-enabled";
pub const ACCOUNT_PURGED: &str =
"https://schemas.openid.net/secevent/risc/event-type/account-purged";
pub const VERIFICATION: &str =
"https://schemas.openid.net/secevent/ssf/event-type/verification";
pub const STREAM_UPDATED: &str =
"https://schemas.openid.net/secevent/ssf/event-type/stream-updated";
}
#[derive(Debug, Clone)]
pub enum SsfKeySource {
JwksUri(String),
DiscoveryUrl(String),
}
pub type AccessTokenFuture =
Pin<Box<dyn Future<Output = Result<Sensitive<String>, AxiamError>> + Send>>;
pub type AccessTokenProvider = Arc<dyn Fn() -> AccessTokenFuture + Send + Sync>;
pub type ReplayStoreError = Box<dyn std::error::Error + Send + Sync>;
pub trait ReplayStore: Send + Sync {
fn check_and_record(&self, jti: &str, window: Duration) -> Result<bool, ReplayStoreError>;
}
#[derive(Debug, Default)]
pub struct MemoryReplayStore {
seen: Mutex<HashMap<String, crate::time::Instant>>,
}
impl ReplayStore for MemoryReplayStore {
fn check_and_record(&self, jti: &str, window: Duration) -> Result<bool, ReplayStoreError> {
let now = crate::time::Instant::now();
let mut seen = self.seen.lock().unwrap_or_else(|p| p.into_inner());
seen.retain(|_, expires| *expires > now);
if seen.contains_key(jti) {
return Ok(false);
}
seen.insert(jti.to_string(), now + window);
Ok(true)
}
}
#[derive(Clone)]
pub struct SsfReceiverConfig {
pub issuer: String,
pub audience: String,
pub keys: SsfKeySource,
pub access_token_provider: Option<AccessTokenProvider>,
pub replay_window: Duration,
pub replay_store: Option<Arc<dyn ReplayStore>>,
}
impl std::fmt::Debug for SsfReceiverConfig {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("SsfReceiverConfig")
.field("issuer", &self.issuer)
.field("audience", &self.audience)
.field("keys", &self.keys)
.field(
"access_token_provider",
&self.access_token_provider.as_ref().map(|_| "<provider>"),
)
.field("replay_window", &self.replay_window)
.finish_non_exhaustive()
}
}
impl SsfReceiverConfig {
pub fn new(issuer: impl Into<String>, audience: impl Into<String>, keys: SsfKeySource) -> Self {
Self {
issuer: issuer.into(),
audience: audience.into(),
keys,
access_token_provider: None,
replay_window: MIN_REPLAY_WINDOW,
replay_store: None,
}
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct SecurityEvent {
pub jti: String,
pub iat: i64,
pub iss: String,
pub aud: Value,
pub txn: Option<String>,
pub event_type: String,
pub event: Value,
pub sub_id: Value,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RefusedSet {
pub jti: String,
pub reason: SetFailureReason,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SetErr {
pub err: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
impl SetErr {
pub fn from_reason(reason: SetFailureReason) -> Self {
Self {
err: reason.push_error_code().to_string(),
description: None,
}
}
}
#[derive(Debug, Clone, Default)]
pub struct SsfPollOptions {
pub max_events: Option<u32>,
pub return_immediately: Option<bool>,
pub ack: Option<Vec<String>>,
pub set_errs: Option<BTreeMap<String, SetErr>>,
}
#[derive(Serialize)]
struct PollBody<'a> {
#[serde(rename = "maxEvents", skip_serializing_if = "Option::is_none")]
max_events: Option<u32>,
#[serde(rename = "returnImmediately", skip_serializing_if = "Option::is_none")]
return_immediately: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
ack: Option<&'a Vec<String>>,
#[serde(rename = "setErrs", skip_serializing_if = "Option::is_none")]
set_errs: Option<&'a BTreeMap<String, SetErr>>,
}
#[derive(Debug, Clone)]
pub struct SsfPollResult {
pub events: Vec<SecurityEvent>,
pub more_available: bool,
pub refused: Vec<RefusedSet>,
pub unjudged: Vec<String>,
}
pub struct SsfReceiver {
client: AxiamClient,
issuer: String,
audience: String,
keys: SsfKeySource,
verifier: tokio::sync::OnceCell<JwksVerifier>,
token_provider: Option<AccessTokenProvider>,
replay_window: Duration,
replay_store: Arc<dyn ReplayStore>,
discovery_failed_at: Mutex<Option<crate::time::Instant>>,
}
impl std::fmt::Debug for SsfReceiver {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("SsfReceiver")
.field("issuer", &self.issuer)
.field("audience", &self.audience)
.field("keys", &self.keys)
.field("replay_window", &self.replay_window)
.finish_non_exhaustive()
}
}
fn refuse(reason: SetFailureReason, detail: &str) -> AxiamError {
AxiamError::set_refused(reason, detail)
}
fn store_failure(cause: ReplayStoreError) -> AxiamError {
const UNJUDGED: &str =
"the replay store could not answer: the SET is unjudged and was not recorded";
match cause.downcast::<AxiamError>() {
Ok(own) if own.set_failure_reason().is_none() => *own,
Ok(refusal) => AxiamError::network_with_source(UNJUDGED, refusal),
Err(other) => AxiamError::network_with_source(UNJUDGED, other),
}
}
fn b64_json(part: &str) -> Option<Map<String, Value>> {
let bytes = URL_SAFE_NO_PAD.decode(part).ok()?;
match serde_json::from_slice(&bytes).ok()? {
Value::Object(map) => Some(map),
_ => None,
}
}
impl SsfReceiver {
pub fn new(client: &AxiamClient, config: SsfReceiverConfig) -> Result<Self, AxiamError> {
use crate::management::error::local_refusal;
if config.replay_window < MIN_REPLAY_WINDOW {
return Err(local_refusal(
"ssf.receiver",
"replay_window",
"must be at least seven days, the transmitter's buffer retention (CONTRACT.md §32.7)",
));
}
if config.issuer.is_empty() || config.audience.is_empty() {
return Err(local_refusal(
"ssf.receiver",
"issuer",
"issuer and audience are required (CONTRACT.md §32.7)",
));
}
Ok(Self {
client: client.clone(),
issuer: config.issuer,
audience: config.audience,
keys: config.keys,
verifier: tokio::sync::OnceCell::new(),
token_provider: config.access_token_provider,
replay_window: config.replay_window,
replay_store: config
.replay_store
.unwrap_or_else(|| Arc::new(MemoryReplayStore::default())),
discovery_failed_at: Mutex::new(None),
})
}
async fn verifier(&self) -> Result<&JwksVerifier, AxiamError> {
self.verifier
.get_or_try_init(|| async {
let jwks_uri = match &self.keys {
SsfKeySource::JwksUri(u) => u.clone(),
SsfKeySource::DiscoveryUrl(d) => self.discover_jwks_uri_limited(d).await?,
};
let url = parse_secure("jwks_uri", &jwks_uri)?;
Ok::<_, AxiamError>(
JwksVerifier::for_jwks_url(self.client.http_bare().clone(), url)
.limiting_failed_fetches(),
)
})
.await
}
async fn discover_jwks_uri_limited(&self, discovery_url: &str) -> Result<String, AxiamError> {
let recent = self
.discovery_failed_at
.lock()
.unwrap_or_else(|p| p.into_inner())
.is_some_and(|at| at.elapsed() < crate::token::jwks::FAILED_FETCH_MIN_INTERVAL);
if recent {
return Err(AxiamError::network(
"the SSF configuration fetch failed less than a minute ago; no fetch was made \
(CONTRACT.md §34.2 P6)",
));
}
let outcome = self.discover_jwks_uri(discovery_url).await;
*self
.discovery_failed_at
.lock()
.unwrap_or_else(|p| p.into_inner()) = outcome.is_err().then(crate::time::Instant::now);
outcome
}
async fn discover_jwks_uri(&self, discovery_url: &str) -> Result<String, AxiamError> {
let url = parse_secure("discovery_url", discovery_url)?;
let response = self
.client
.http_bare()
.get(url)
.omit_browser_credentials()
.send()
.await
.map_err(|e| AxiamError::network(format!("SSF configuration fetch failed: {e}")))?;
if !response.status().is_success() {
return Err(AxiamError::from_http_status(
response.status().as_u16(),
"SSF configuration endpoint returned a non-success status",
));
}
let doc: Value = response
.json()
.await
.map_err(|e| AxiamError::network(format!("SSF configuration parse failed: {e}")))?;
if doc.get("issuer").and_then(Value::as_str) != Some(self.issuer.as_str()) {
return Err(AxiamError::network(
"the SSF configuration's issuer is not the configured issuer",
));
}
doc.get("jwks_uri")
.and_then(Value::as_str)
.map(str::to_owned)
.ok_or_else(|| AxiamError::network("the SSF configuration carries no jwks_uri"))
}
pub async fn verify_set(&self, set: &str) -> Result<SecurityEvent, AxiamError> {
let event = self.judge(set, None).await?;
self.record(event)
}
fn record(&self, event: SecurityEvent) -> Result<SecurityEvent, AxiamError> {
match self
.replay_store
.check_and_record(&event.jti, self.replay_window)
{
Ok(true) => Ok(event),
Ok(false) => Err(refuse(SetFailureReason::Replayed, "jti already seen")),
Err(cause) => Err(store_failure(cause)),
}
}
async fn judge(
&self,
set: &str,
expected_jti: Option<&str>,
) -> Result<SecurityEvent, AxiamError> {
use SetFailureReason::*;
let parts: Vec<&str> = set.split('.').collect();
if parts.len() != 3 || URL_SAFE_NO_PAD.decode(parts[2]).is_err() {
return Err(refuse(Malformed, "not three base64url parts"));
}
let (Some(header), Some(claims)) = (b64_json(parts[0]), b64_json(parts[1])) else {
return Err(refuse(Malformed, "header or payload is not a JSON object"));
};
let typ = header.get("typ").and_then(Value::as_str).unwrap_or("");
if !typ.eq_ignore_ascii_case("secevent+jwt")
&& !typ.eq_ignore_ascii_case("application/secevent+jwt")
{
return Err(refuse(InvalidType, "typ is not secevent+jwt"));
}
if header.get("alg").and_then(Value::as_str) != Some("EdDSA") {
return Err(refuse(InvalidKey, "alg is not EdDSA"));
}
let Some(kid) = header.get("kid").and_then(Value::as_str) else {
return Err(refuse(InvalidKey, "no kid"));
};
let verifier = self.verifier().await?;
let Some(jwk) = verifier.key_for_kid(kid).await? else {
return Err(refuse(InvalidKey, "no key for kid in the JWKS"));
};
let key = DecodingKey::from_jwk(&jwk)
.map_err(|_| refuse(InvalidKey, "the JWKS key is not usable"))?;
let mut validation = Validation::new(Algorithm::EdDSA);
validation.required_spec_claims.clear();
validation.validate_exp = false;
validation.validate_nbf = false;
validation.validate_aud = false;
validation.leeway = 0;
decode::<Value>(set, &key, &validation)
.map_err(|_| refuse(InvalidKey, "signature does not verify"))?;
let iss = claims.get("iss").and_then(Value::as_str).unwrap_or("");
if iss != self.issuer {
return Err(refuse(InvalidIssuer, "iss is not the configured issuer"));
}
let aud = claims.get("aud").cloned().unwrap_or(Value::Null);
let aud_ok = match &aud {
Value::String(a) => *a == self.audience,
Value::Array(items) => items.iter().any(|a| a.as_str() == Some(&self.audience)),
_ => false,
};
if !aud_ok {
return Err(refuse(InvalidAudience, "aud does not name this receiver"));
}
if claims.contains_key("exp") || claims.contains_key("sub") {
return Err(refuse(InvalidRequest, "a SET carries no exp and no sub"));
}
let jti = claims
.get("jti")
.and_then(Value::as_str)
.filter(|j| !j.is_empty())
.ok_or_else(|| refuse(InvalidRequest, "no jti"))?;
let iat = claims
.get("iat")
.and_then(Value::as_i64)
.ok_or_else(|| refuse(InvalidRequest, "no numeric iat"))?;
let sub_id = claims
.get("sub_id")
.filter(|v| v.is_object())
.cloned()
.ok_or_else(|| refuse(InvalidRequest, "no sub_id"))?;
let events = claims
.get("events")
.and_then(Value::as_object)
.filter(|e| e.len() == 1)
.ok_or_else(|| refuse(InvalidRequest, "events must have exactly one member"))?;
if expected_jti.is_some_and(|k| k != jti) {
return Err(refuse(InvalidRequest, "the poll key is not the SET's jti"));
}
let (event_type, event) = events.iter().next().expect("one member");
Ok(SecurityEvent {
jti: jti.to_string(),
iat,
iss: iss.to_string(),
aud,
txn: claims.get("txn").and_then(Value::as_str).map(str::to_owned),
event_type: event_type.clone(),
event: event.clone(),
sub_id,
})
}
pub async fn poll(
&self,
stream_id: &str,
options: SsfPollOptions,
) -> Result<SsfPollResult, AxiamError> {
use crate::retry::{
Attempt, RetryRunner, ThreadRngJitter, TokioSleeper, parse_retry_after,
};
self.client.ensure_open()?;
let provider = self.token_provider.as_ref().ok_or_else(|| {
AxiamError::auth(
"ssf.poll needs an access_token_provider (a client-credentials token with ssf.manage)",
)
})?;
let mut url = self.client.base_url().clone();
url.path_segments_mut()
.map_err(|_| AxiamError::network("the base URL cannot carry a path"))?
.pop_if_empty()
.extend(["ssf", "v1", "poll", stream_id]);
let body = PollBody {
max_events: options.max_events,
return_immediately: options.return_immediately,
ack: options.ack.as_ref(),
set_errs: options.set_errs.as_ref(),
};
let token = provider().await?;
let runner = RetryRunner {
enabled: self.client.retry_enabled(),
operation: "ssf.poll",
telemetry: self.client.telemetry(),
jitter: &ThreadRngJitter,
sleeper: &TokioSleeper,
};
let (url, body, token) = (&url, &body, &token);
let reply: Value = runner
.run(|_| async move {
let response = self
.client
.http_bare()
.post(url.clone())
.bearer_auth(token.expose())
.json(body)
.omit_browser_credentials()
.send()
.await
.map_err(|e| {
Attempt::bare(AxiamError::network(format!("ssf.poll request failed: {e}")))
})?;
let status = response.status();
if !status.is_success() {
let retry_after = response
.headers()
.get(reqwest::header::RETRY_AFTER)
.and_then(|v| v.to_str().ok())
.and_then(parse_retry_after);
let text = response.text().await.unwrap_or_default();
let err = crate::management::error::from_management_status(
"ssf.poll",
status.as_u16(),
text,
);
if !crate::retry::status_is_retryable(status.as_u16()) {
return Ok(Err(err));
}
return Err(Attempt { err, retry_after });
}
Ok(response.json::<Value>().await.map_err(|e| {
AxiamError::network(format!("ssf.poll: failed to parse the response: {e}"))
}))
})
.await??;
let more_available = reply
.get("moreAvailable")
.and_then(Value::as_bool)
.unwrap_or(false);
let mut judged = Vec::new();
if let Some(sets) = reply.get("sets").and_then(Value::as_object) {
for (jti, set) in sets {
let verdict = match set.as_str() {
Some(set) => self.judge(set, Some(jti)).await,
None => Err(refuse(SetFailureReason::Malformed, "not a string")),
};
if let Err(e) = &verdict
&& e.set_failure_reason().is_none()
{
return Err(verdict.unwrap_err());
}
judged.push((jti, verdict));
}
}
let mut events = Vec::new();
let mut refused = Vec::new();
let mut unjudged = Vec::new();
for (jti, verdict) in judged {
if !unjudged.is_empty() && verdict.is_ok() {
unjudged.push(jti.clone());
continue;
}
match verdict.and_then(|event| self.record(event)) {
Ok(event) => events.push(event),
Err(e) => match e.set_failure_reason() {
Some(reason) => refused.push(RefusedSet {
jti: jti.clone(),
reason,
}),
None => unjudged.push(jti.clone()),
},
}
}
if !unjudged.is_empty() {
self.client
.telemetry()
.emit(crate::telemetry::TelemetryEvent::SsfUnjudged {
operation: "ssf.poll",
count: unjudged.len(),
category: "replay_store",
});
}
Ok(SsfPollResult {
events,
more_available,
refused,
unjudged,
})
}
}
fn parse_secure(label: &str, raw: &str) -> Result<url::Url, AxiamError> {
let url = url::Url::parse(raw)
.map_err(|e| AxiamError::network(format!("{label} is not an absolute URL: {e}")))?;
crate::url_guard::ensure_secure_scheme(label, url.scheme(), url.host_str(), "https")
.map_err(AxiamError::network)?;
Ok(url)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_memory_store_refuses_a_second_sighting_and_forgets_after_the_window() {
let store = MemoryReplayStore::default();
assert!(
store
.check_and_record("a", Duration::from_secs(60))
.unwrap()
);
assert!(
!store
.check_and_record("a", Duration::from_secs(60))
.unwrap()
);
assert!(store.check_and_record("b", Duration::ZERO).unwrap());
assert!(
store.check_and_record("b", Duration::ZERO).unwrap(),
"expired, so new again"
);
}
#[test]
fn push_codes_are_rfc_8935_codes() {
for (reason, code) in [
(SetFailureReason::Malformed, "invalid_request"),
(SetFailureReason::InvalidType, "invalid_request"),
(SetFailureReason::Replayed, "invalid_request"),
(SetFailureReason::InvalidKey, "invalid_key"),
(SetFailureReason::InvalidIssuer, "invalid_issuer"),
(SetFailureReason::InvalidAudience, "invalid_audience"),
(SetFailureReason::InvalidRequest, "invalid_request"),
] {
assert_eq!(reason.push_error_code(), code);
assert_eq!(SetErr::from_reason(reason).err, code);
}
assert_eq!(SetFailureReason::Replayed.to_string(), "replayed");
}
}