use std::time::{Duration, SystemTime, UNIX_EPOCH};
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use base64::Engine as _;
use serde::Deserialize;
use serde_json::{Map, Value};
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VerifyError {
Malformed(String),
Algorithm(String),
UnknownKey(String),
Signature,
Expired,
Issuer(String),
Audience,
Keys(String),
Replayed,
}
impl std::fmt::Display for VerifyError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
VerifyError::Malformed(m) => write!(f, "malformed token: {m}"),
VerifyError::Algorithm(a) => write!(f, "algorithm {a} is not accepted"),
VerifyError::UnknownKey(k) => write!(f, "no key {k} in the issuer's key set"),
VerifyError::Signature => f.write_str("the signature does not verify"),
VerifyError::Expired => f.write_str("the token is expired or not yet valid"),
VerifyError::Issuer(i) => write!(f, "unexpected issuer {i}"),
VerifyError::Audience => f.write_str("the token is not for this audience"),
VerifyError::Keys(m) => write!(f, "key set: {m}"),
VerifyError::Replayed => f.write_str("the receipt was already used"),
}
}
}
impl std::error::Error for VerifyError {}
#[derive(Debug, Clone)]
pub struct Expect {
pub issuer: String,
pub audiences: Vec<String>,
pub leeway: Duration,
pub typ: Option<String>,
}
impl Expect {
pub fn issuer(issuer: impl Into<String>) -> Expect {
Expect {
issuer: issuer.into().trim_end_matches('/').to_string(),
audiences: vec![],
leeway: Duration::from_secs(60),
typ: None,
}
}
pub fn typ(mut self, typ: impl Into<String>) -> Expect {
self.typ = Some(typ.into());
self
}
pub fn audience(mut self, audience: impl Into<String>) -> Expect {
self.audiences.push(audience.into());
self
}
pub fn leeway(mut self, leeway: Duration) -> Expect {
self.leeway = leeway;
self
}
pub fn callback(callback_url: impl Into<String>) -> Expect {
Expect::issuer(CALLBACK_RECEIPT_ISSUER)
.audience(callback_url)
.leeway(Duration::from_secs(CALLBACK_LEEWAY_SECONDS))
.typ(CALLBACK_RECEIPT_TYP)
}
}
#[derive(Debug, Default)]
pub struct ReplayGuard {
seen: std::sync::Mutex<std::collections::HashMap<String, i64>>,
}
impl ReplayGuard {
pub fn new() -> ReplayGuard {
ReplayGuard::default()
}
pub fn admit(&self, claims: &Claims, now: i64) -> Result<(), VerifyError> {
let (Some(jti), Some(exp)) = (claims.jti(), claims.expires_at()) else {
return Err(VerifyError::Replayed);
};
let mut seen = self.seen.lock().unwrap_or_else(|e| e.into_inner());
seen.retain(|_, until| *until > now);
if seen.contains_key(jti) {
return Err(VerifyError::Replayed);
}
seen.insert(jti.to_string(), exp + CALLBACK_LEEWAY_SECONDS as i64);
Ok(())
}
}
pub fn verify_callback_with_keys(
token: &str,
keys: &Jwks,
callback_url: &str,
guard: &ReplayGuard,
now: i64,
) -> Result<Claims, VerifyError> {
let claims = verify_with_keys(token, keys, &Expect::callback(callback_url), now)?;
guard.admit(&claims, now)?;
Ok(claims)
}
#[derive(Debug, Clone, PartialEq)]
pub struct Claims(pub Map<String, Value>);
impl Claims {
pub fn subject(&self) -> Option<&str> {
self.0.get("sub").and_then(Value::as_str)
}
pub fn get(&self, claim: &str) -> Option<&Value> {
self.0.get(claim)
}
pub fn expires_at(&self) -> Option<i64> {
self.0.get("exp").and_then(Value::as_i64)
}
pub fn jti(&self) -> Option<&str> {
self.0.get("jti").and_then(Value::as_str)
}
}
pub const CALLBACK_RECEIPT_TYP: &str = "compute-tick-receipt+jwt";
pub const CALLBACK_LEEWAY_SECONDS: u64 = 30;
pub const CALLBACK_RECEIPT_ISSUER: &str = "https://api.compute.sylphx.com";
pub const CALLBACK_RECEIPT_JWKS_URL: &str =
"https://api.compute.sylphx.com/.well-known/compute-tick-receipt-jwks.json";
#[derive(Debug, Clone, Default, Deserialize)]
pub struct Jwks {
#[serde(default)]
pub keys: Vec<Jwk>,
}
#[derive(Debug, Clone, Deserialize)]
pub struct Jwk {
#[serde(default)]
pub kid: String,
pub kty: String,
#[serde(default)]
pub crv: String,
#[serde(default)]
pub x: String,
#[serde(default)]
pub y: String,
#[serde(default)]
pub alg: Option<String>,
#[serde(rename = "use", default)]
pub use_: Option<String>,
}
#[derive(Deserialize)]
struct Header {
alg: String,
#[serde(default)]
kid: String,
#[serde(default)]
typ: Option<String>,
}
fn part(s: &str, what: &str) -> Result<Vec<u8>, VerifyError> {
URL_SAFE_NO_PAD
.decode(s)
.map_err(|_| VerifyError::Malformed(format!("{what} is not base64url")))
}
fn verify_signature(jwk: &Jwk, alg: &str, signed: &[u8], sig: &[u8]) -> Result<(), VerifyError> {
if jwk.use_.as_deref().is_some_and(|u| u != "sig")
|| jwk.alg.as_deref().is_some_and(|a| a != alg)
{
return Err(VerifyError::Signature);
}
match (alg, jwk.kty.as_str(), jwk.crv.as_str()) {
("ES256", "EC", "P-256") => {
use p256::ecdsa::signature::Verifier as _;
let mut point = vec![0x04];
point.extend(part(&jwk.x, "key x")?);
point.extend(part(&jwk.y, "key y")?);
let key = p256::ecdsa::VerifyingKey::from_sec1_bytes(&point)
.map_err(|_| VerifyError::Keys("bad P-256 key".into()))?;
let sig =
p256::ecdsa::Signature::from_slice(sig).map_err(|_| VerifyError::Signature)?;
key.verify(signed, &sig).map_err(|_| VerifyError::Signature)
}
("EdDSA", "OKP", "Ed25519") => {
use ed25519_dalek::Verifier as _;
let raw: [u8; 32] = part(&jwk.x, "key x")?
.try_into()
.map_err(|_| VerifyError::Keys("bad Ed25519 key".into()))?;
let key = ed25519_dalek::VerifyingKey::from_bytes(&raw)
.map_err(|_| VerifyError::Keys("bad Ed25519 key".into()))?;
let sig: [u8; 64] = sig.try_into().map_err(|_| VerifyError::Signature)?;
key.verify(signed, &ed25519_dalek::Signature::from_bytes(&sig))
.map_err(|_| VerifyError::Signature)
}
_ => Err(VerifyError::Signature),
}
}
pub fn key_id(token: &str) -> Result<String, VerifyError> {
let head = token.split('.').next().unwrap_or_default();
let h: Header = serde_json::from_slice(&part(head, "header")?)
.map_err(|_| VerifyError::Malformed("header is not JSON".into()))?;
Ok(h.kid)
}
pub fn verify_with_keys(
token: &str,
keys: &Jwks,
expect: &Expect,
now: i64,
) -> Result<Claims, VerifyError> {
let mut it = token.split('.');
let (Some(h), Some(p), Some(s), None) = (it.next(), it.next(), it.next(), it.next()) else {
return Err(VerifyError::Malformed("not three parts".into()));
};
let header: Header = serde_json::from_slice(&part(h, "header")?)
.map_err(|_| VerifyError::Malformed("header is not JSON".into()))?;
if !matches!(header.alg.as_str(), "ES256" | "EdDSA") {
return Err(VerifyError::Algorithm(header.alg));
}
if expect
.typ
.as_deref()
.is_some_and(|want| header.typ.as_deref() != Some(want))
{
return Err(VerifyError::Malformed("unexpected token type".into()));
}
let candidates: Vec<&Jwk> = keys
.keys
.iter()
.filter(|k| header.kid.is_empty() || k.kid == header.kid)
.collect();
if candidates.is_empty() {
return Err(VerifyError::UnknownKey(header.kid));
}
let sig = part(s, "signature")?;
let signed = format!("{h}.{p}");
if !candidates
.iter()
.any(|k| verify_signature(k, &header.alg, signed.as_bytes(), &sig).is_ok())
{
return Err(VerifyError::Signature);
}
let claims: Map<String, Value> = serde_json::from_slice(&part(p, "payload")?)
.map_err(|_| VerifyError::Malformed("payload is not a JSON object".into()))?;
let leeway = expect.leeway.as_secs() as i64;
let num = |k: &str| claims.get(k).and_then(Value::as_i64);
match num("exp") {
Some(exp) if exp + leeway > now => {}
_ => return Err(VerifyError::Expired),
}
if num("nbf").is_some_and(|nbf| nbf - leeway > now)
|| num("iat").is_some_and(|iat| iat - leeway > now)
{
return Err(VerifyError::Expired);
}
let iss = claims
.get("iss")
.and_then(Value::as_str)
.unwrap_or_default();
if iss.trim_end_matches('/') != expect.issuer {
return Err(VerifyError::Issuer(iss.to_string()));
}
let auds: Vec<&str> = match claims.get("aud") {
Some(Value::String(a)) => vec![a.as_str()],
Some(Value::Array(a)) => a.iter().filter_map(Value::as_str).collect(),
_ => vec![],
};
if expect.audiences.is_empty() || !auds.iter().any(|a| expect.audiences.iter().any(|e| e == a))
{
return Err(VerifyError::Audience);
}
Ok(Claims(claims))
}
fn now_unix() -> i64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.unwrap_or(0)
}
#[cfg(feature = "http")]
pub struct Verifier {
expect: Expect,
jwks_url: String,
http: reqwest::Client,
cache: tokio::sync::RwLock<Option<(Jwks, std::time::Instant)>>,
last_forced: std::sync::Mutex<Option<std::time::Instant>>,
}
#[cfg(feature = "http")]
impl Verifier {
pub const TTL: Duration = Duration::from_secs(600);
pub const MIN_REFETCH: Duration = Duration::from_secs(30);
pub fn new(expect: Expect) -> Verifier {
let url = format!("{}/v1/oauth/jwks.json", expect.issuer);
Verifier::with_jwks_url(expect, url)
}
pub fn callback(callback_url: impl Into<String>) -> Verifier {
Verifier::with_jwks_url(Expect::callback(callback_url), CALLBACK_RECEIPT_JWKS_URL)
}
pub fn with_jwks_url(expect: Expect, jwks_url: impl Into<String>) -> Verifier {
Verifier {
expect,
jwks_url: jwks_url.into(),
http: reqwest::Client::builder()
.timeout(Duration::from_secs(10))
.build()
.expect("a reqwest client"),
cache: tokio::sync::RwLock::new(None),
last_forced: std::sync::Mutex::new(None),
}
}
async fn keys(&self, force: bool) -> Result<Jwks, VerifyError> {
if let Some((k, at)) = self.cache.read().await.as_ref() {
let fresh = at.elapsed() < Verifier::TTL;
let throttled = force && {
let mut last = self.last_forced.lock().unwrap_or_else(|e| e.into_inner());
let recent = last.is_some_and(|t| t.elapsed() < Verifier::MIN_REFETCH);
if !recent {
*last = Some(std::time::Instant::now());
}
recent
};
if fresh && (!force || throttled) {
return Ok(k.clone());
}
}
let fetched: Jwks = self
.http
.get(&self.jwks_url)
.send()
.await
.and_then(|r| r.error_for_status())
.map_err(|e| VerifyError::Keys(e.to_string()))?
.json()
.await
.map_err(|e| VerifyError::Keys(e.to_string()))?;
*self.cache.write().await = Some((fetched.clone(), std::time::Instant::now()));
Ok(fetched)
}
pub async fn verify(&self, token: &str) -> Result<Claims, VerifyError> {
let keys = self.keys(false).await?;
match verify_with_keys(token, &keys, &self.expect, now_unix()) {
Err(VerifyError::UnknownKey(_)) => {
let keys = self.keys(true).await?;
verify_with_keys(token, &keys, &self.expect, now_unix())
}
other => other,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use p256::ecdsa::signature::Signer as _;
use serde_json::json;
fn b64(v: &[u8]) -> String {
URL_SAFE_NO_PAD.encode(v)
}
fn es256() -> (p256::ecdsa::SigningKey, Jwk) {
let sk = p256::ecdsa::SigningKey::from_slice(&[7u8; 32]).unwrap();
let pt = sk.verifying_key().to_encoded_point(false);
let jwk = Jwk {
kid: "k1".into(),
kty: "EC".into(),
crv: "P-256".into(),
x: b64(pt.x().unwrap()),
y: b64(pt.y().unwrap()),
alg: Some("ES256".into()),
use_: Some("sig".into()),
};
(sk, jwk)
}
fn sign_es(sk: &p256::ecdsa::SigningKey, header: Value, claims: Value) -> String {
let signed = format!(
"{}.{}",
b64(header.to_string().as_bytes()),
b64(claims.to_string().as_bytes())
);
let sig: p256::ecdsa::Signature = sk.sign(signed.as_bytes());
format!("{signed}.{}", b64(&sig.to_bytes()))
}
const NOW: i64 = 1_800_000_000;
fn good() -> Value {
json!({"iss": "https://api.sylphx.com", "aud": ["app"], "sub": "u1", "exp": NOW + 300, "iat": NOW - 10})
}
fn expect() -> Expect {
Expect::issuer("https://api.sylphx.com").audience("app")
}
#[test]
fn a_valid_es256_token_verifies() {
let (sk, jwk) = es256();
let keys = Jwks { keys: vec![jwk] };
let t = sign_es(&sk, json!({"alg": "ES256", "kid": "k1"}), good());
let c = verify_with_keys(&t, &keys, &expect(), NOW).unwrap();
assert_eq!(c.subject(), Some("u1"));
assert_eq!(key_id(&t).unwrap(), "k1");
}
#[test]
fn a_valid_eddsa_token_verifies() {
use ed25519_dalek::Signer as _;
let sk = ed25519_dalek::SigningKey::from_bytes(&[9u8; 32]);
let keys = Jwks {
keys: vec![Jwk {
kid: "e1".into(),
kty: "OKP".into(),
crv: "Ed25519".into(),
x: b64(sk.verifying_key().as_bytes()),
y: String::new(),
alg: None,
use_: None,
}],
};
let signed = format!(
"{}.{}",
b64(json!({"alg": "EdDSA", "kid": "e1"}).to_string().as_bytes()),
b64(good().to_string().as_bytes())
);
let t = format!("{signed}.{}", b64(&sk.sign(signed.as_bytes()).to_bytes()));
assert!(verify_with_keys(&t, &keys, &expect(), NOW).is_ok());
}
#[test]
fn an_empty_audience_list_refuses_every_token() {
let (sk, jwk) = es256();
let keys = Jwks { keys: vec![jwk] };
let t = sign_es(&sk, json!({"alg": "ES256", "kid": "k1"}), good());
let none = Expect::issuer("https://api.sylphx.com");
assert_eq!(
verify_with_keys(&t, &keys, &none, NOW).unwrap_err(),
VerifyError::Audience
);
}
#[test]
fn hostile_tokens_are_refused() {
let (sk, jwk) = es256();
let keys = Jwks { keys: vec![jwk] };
let h = json!({"alg": "ES256", "kid": "k1"});
let with = |f: &dyn Fn(&mut Map<String, Value>)| {
let mut c = good().as_object().unwrap().clone();
f(&mut c);
sign_es(&sk, h.clone(), Value::Object(c))
};
let cases: Vec<(&str, String, fn(&VerifyError) -> bool)> = vec![
(
"expired",
with(&|c| {
c.insert("exp".into(), json!(NOW - 120));
}),
|e| *e == VerifyError::Expired,
),
(
"no exp",
with(&|c| {
c.remove("exp");
}),
|e| *e == VerifyError::Expired,
),
(
"not yet valid",
with(&|c| {
c.insert("nbf".into(), json!(NOW + 600));
}),
|e| *e == VerifyError::Expired,
),
(
"other issuer",
with(&|c| {
c.insert("iss".into(), json!("https://evil.example"));
}),
|e| matches!(e, VerifyError::Issuer(_)),
),
(
"other audience",
with(&|c| {
c.insert("aud".into(), json!("other"));
}),
|e| *e == VerifyError::Audience,
),
(
"alg none",
format!(
"{}.{}.",
b64(br#"{"alg":"none"}"#),
b64(good().to_string().as_bytes())
),
|e| matches!(e, VerifyError::Algorithm(_)),
),
(
"alg HS256",
format!(
"{}.{}.x",
b64(br#"{"alg":"HS256","kid":"k1"}"#),
b64(good().to_string().as_bytes())
),
|e| matches!(e, VerifyError::Algorithm(_)),
),
(
"unknown kid",
sign_es(&sk, json!({"alg": "ES256", "kid": "zz"}), good()),
|e| matches!(e, VerifyError::UnknownKey(_)),
),
("two parts", "a.b".into(), |e| {
matches!(e, VerifyError::Malformed(_))
}),
("garbage", "!!.!!.!!".into(), |e| {
matches!(e, VerifyError::Malformed(_))
}),
];
for (name, token, ok) in cases {
let e = verify_with_keys(&token, &keys, &expect(), NOW).expect_err(name);
assert!(ok(&e), "{name}: {e:?}");
}
let t = sign_es(&sk, h.clone(), good());
let mut parts: Vec<&str> = t.split('.').collect();
let forged = b64(json!({"iss": "https://api.sylphx.com", "aud": "app", "sub": "admin", "exp": NOW + 300}).to_string().as_bytes());
parts[1] = &forged;
assert_eq!(
verify_with_keys(&parts.join("."), &keys, &expect(), NOW),
Err(VerifyError::Signature)
);
let other = p256::ecdsa::SigningKey::from_slice(&[8u8; 32]).unwrap();
let t = sign_es(&other, h.clone(), good());
assert_eq!(
verify_with_keys(&t, &keys, &expect(), NOW),
Err(VerifyError::Signature)
);
let t = with(&|c| {
c.insert("exp".into(), json!(NOW - 30));
});
assert!(verify_with_keys(&t, &keys, &expect(), NOW).is_ok());
}
fn receipt(
sk: &ed25519_dalek::SigningKey,
kid: &str,
aud: &str,
jti: &str,
exp: i64,
) -> String {
use ed25519_dalek::Signer as _;
let signed = format!(
"{}.{}",
b64(json!({"alg": "EdDSA", "typ": "compute-tick-receipt+jwt", "kid": kid}).to_string().as_bytes()),
b64(json!({"iss": CALLBACK_RECEIPT_ISSUER, "aud": aud, "jti": jti, "iat": NOW, "nbf": NOW, "exp": exp}).to_string().as_bytes())
);
format!("{signed}.{}", b64(&sk.sign(signed.as_bytes()).to_bytes()))
}
#[test]
fn a_callback_receipt_verifies_for_its_url_once() {
let sk = ed25519_dalek::SigningKey::from_bytes(&[5u8; 32]);
let keys: Jwks = serde_json::from_value(json!({"keys": [{
"issuer": CALLBACK_RECEIPT_ISSUER, "typ": "compute-tick-receipt+jwt",
"kty": "OKP", "crv": "Ed25519", "alg": "EdDSA", "use": "sig", "kid": "cb-1",
"x": b64(sk.verifying_key().as_bytes()),
"not_before_unix_seconds": 0, "not_after_unix_seconds": 4_102_444_800i64
}]}))
.unwrap();
let url = "https://hooks.example.com/task";
let guard = ReplayGuard::new();
let t = receipt(&sk, "cb-1", url, "s:2026:t1", NOW + 300);
let c = verify_callback_with_keys(&t, &keys, url, &guard, NOW).unwrap();
assert_eq!(c.jti(), Some("s:2026:t1"));
assert_eq!(
verify_callback_with_keys(&t, &keys, url, &guard, NOW + 5),
Err(VerifyError::Replayed)
);
let other = receipt(
&sk,
"cb-1",
"https://evil.example.com/x",
"s:2026:t2",
NOW + 300,
);
assert_eq!(
verify_callback_with_keys(&other, &keys, url, &guard, NOW),
Err(VerifyError::Audience)
);
let old = receipt(&sk, "cb-1", url, "s:2026:t3", NOW - 120);
assert_eq!(
verify_callback_with_keys(&old, &keys, url, &guard, NOW),
Err(VerifyError::Expired)
);
let sk2 = ed25519_dalek::SigningKey::from_bytes(&[6u8; 32]);
let mut both = keys.clone();
both.keys.push(Jwk {
kid: "cb-2".into(),
kty: "OKP".into(),
crv: "Ed25519".into(),
x: b64(sk2.verifying_key().as_bytes()),
y: String::new(),
alg: Some("EdDSA".into()),
use_: Some("sig".into()),
});
let t2 = receipt(&sk2, "cb-2", url, "s:2026:t4", NOW + 300);
assert!(verify_callback_with_keys(&t2, &both, url, &guard, NOW).is_ok());
let t5 = receipt(&sk, "cb-1", url, "s:2026:t5", NOW + 10);
assert!(verify_callback_with_keys(&t5, &keys, url, &guard, NOW).is_ok());
assert_eq!(
verify_callback_with_keys(&t5, &keys, url, &guard, NOW + 35),
Err(VerifyError::Replayed)
);
let signed = format!(
"{}.{}",
b64(json!({"alg": "EdDSA", "kid": "cb-1"})
.to_string()
.as_bytes()),
b64(
json!({"iss": CALLBACK_RECEIPT_ISSUER, "aud": url, "jti": "x", "exp": NOW + 300})
.to_string()
.as_bytes()
)
);
use ed25519_dalek::Signer as _;
let untyped = format!("{signed}.{}", b64(&sk.sign(signed.as_bytes()).to_bytes()));
assert!(matches!(
verify_callback_with_keys(&untyped, &keys, url, &guard, NOW),
Err(VerifyError::Malformed(_))
));
}
}