use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
use serde::{Deserialize, Serialize};
use crate::agent_id::{self, AgentId};
use crate::api_error::ApiError;
pub const DOMAIN: &str = "integration-proxy-capability-v2";
pub const MAX_LIFETIME_SECS: u64 = 15 * 60;
#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Claims {
pub v: u8,
pub connection_id: String,
pub platform: String,
pub aud: String,
pub app: String,
pub cnf: String,
pub exp: u64,
}
#[derive(Debug)]
pub struct Parsed {
pub claims: Claims,
pub app: AgentId,
pub cnf: AgentId,
json: Vec<u8>,
signature: String,
}
pub fn message(json: &[u8]) -> Vec<u8> {
let mut message = Vec::with_capacity(DOMAIN.len() + 1 + json.len());
message.extend_from_slice(DOMAIN.as_bytes());
message.push(b'\n');
message.extend_from_slice(json);
message
}
pub fn parse(token: &str) -> Result<Parsed, ApiError> {
if token.len() > 4096 {
return Err(ApiError::InvalidCapability);
}
let (payload, signature) = token.split_once('.').ok_or(ApiError::InvalidCapability)?;
let json = URL_SAFE_NO_PAD
.decode(payload)
.map_err(|_| ApiError::InvalidCapability)?;
let claims: Claims = serde_json::from_slice(&json).map_err(|_| ApiError::InvalidCapability)?;
if claims.v != 2 {
return Err(ApiError::InvalidCapability);
}
let app = agent_id::parse(&claims.app).ok_or(ApiError::InvalidCapability)?;
let cnf = agent_id::parse(&claims.cnf).ok_or(ApiError::InvalidCapability)?;
Ok(Parsed {
claims,
app,
cnf,
json,
signature: signature.to_owned(),
})
}
impl Parsed {
pub fn verify(&self, owner: &AgentId, audience: &str, now_secs: u64) -> Result<(), ApiError> {
if !owner.verify(&message(&self.json), &self.signature) {
return Err(ApiError::InvalidCapability);
}
if self.claims.aud != audience {
return Err(ApiError::WrongAudience);
}
if self.claims.exp <= now_secs {
return Err(ApiError::CapabilityExpired);
}
if self.claims.exp - now_secs > MAX_LIFETIME_SECS {
return Err(ApiError::CapabilityTooLong);
}
Ok(())
}
}
#[cfg(test)]
pub fn mint(owner: &crate::agent_id::test_signer::Agent, claims: &Claims) -> String {
let json = serde_json::to_vec(claims).unwrap();
format!(
"{}.{}",
URL_SAFE_NO_PAD.encode(&json),
owner.sign(&message(&json))
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::agent_id::test_signer::Agent;
const NOW: u64 = 1_790_000_000;
const AUD: &str = "https://proxy.example";
fn claims(frame: &Agent, app: &Agent) -> Claims {
Claims {
v: 2,
connection_id: "conn".into(),
platform: "github-issues".into(),
aud: AUD.into(),
app: app.id(),
cnf: frame.id(),
exp: NOW + 600,
}
}
#[test]
fn a_capability_verifies_against_its_owner_and_names_app_and_frame() {
let (owner, app, frame) = (Agent::new(1), Agent::new(2), Agent::new(3));
let token = mint(&owner, &claims(&frame, &app));
let parsed = parse(&token).unwrap();
assert_eq!(parsed.app.as_str(), app.id());
assert_eq!(parsed.cnf.as_str(), frame.id());
let owner_id = agent_id::parse(&owner.id()).unwrap();
assert_eq!(parsed.verify(&owner_id, AUD, NOW), Ok(()));
let other = agent_id::parse(&Agent::new(9).id()).unwrap();
assert_eq!(
parsed.verify(&other, AUD, NOW),
Err(ApiError::InvalidCapability)
);
}
#[test]
fn legacy_ids_in_claims_are_canonicalized() {
let (owner, app, frame) = (Agent::new(1), Agent::new(2), Agent::new(3));
let mut c = claims(&frame, &app);
c.app = app.legacy_id();
c.cnf = frame.legacy_id();
let parsed = parse(&mint(&owner, &c)).unwrap();
assert_eq!(parsed.app.as_str(), app.id());
assert_eq!(parsed.cnf.as_str(), frame.id());
}
#[test]
fn audience_and_lifetime_are_enforced() {
let (owner, app, frame) = (Agent::new(1), Agent::new(2), Agent::new(3));
let owner_id = agent_id::parse(&owner.id()).unwrap();
let parsed = parse(&mint(&owner, &claims(&frame, &app))).unwrap();
for audience in [
"https://other-proxy.example",
"http://proxy.example",
"https://proxy.example/",
] {
assert_eq!(
parsed.verify(&owner_id, audience, NOW),
Err(ApiError::WrongAudience)
);
}
assert_eq!(
parsed.verify(&owner_id, AUD, NOW + 600),
Err(ApiError::CapabilityExpired)
);
assert_eq!(parsed.verify(&owner_id, AUD, NOW + 599), Ok(()));
let mut long = claims(&frame, &app);
long.exp = NOW + MAX_LIFETIME_SECS + 1;
let parsed = parse(&mint(&owner, &long)).unwrap();
assert_eq!(
parsed.verify(&owner_id, AUD, NOW),
Err(ApiError::CapabilityTooLong)
);
long.exp = NOW + MAX_LIFETIME_SECS;
let parsed = parse(&mint(&owner, &long)).unwrap();
assert_eq!(parsed.verify(&owner_id, AUD, NOW), Ok(()));
}
#[test]
fn tampering_with_any_claim_breaks_the_signature() {
let (owner, app, frame) = (Agent::new(1), Agent::new(2), Agent::new(3));
let owner_id = agent_id::parse(&owner.id()).unwrap();
let token = mint(&owner, &claims(&frame, &app));
let signature = token.split_once('.').unwrap().1;
let mut forged = claims(&Agent::new(4), &app);
forged.exp = NOW + 700;
let json = serde_json::to_vec(&forged).unwrap();
let tampered = format!("{}.{signature}", URL_SAFE_NO_PAD.encode(json));
assert_eq!(
parse(&tampered).unwrap().verify(&owner_id, AUD, NOW),
Err(ApiError::InvalidCapability)
);
}
#[test]
fn a_capability_signature_is_not_a_request_signature() {
let (owner, app, frame) = (Agent::new(1), Agent::new(2), Agent::new(3));
let c = claims(&frame, &app);
let json = serde_json::to_vec(&c).unwrap();
let token = format!("{}.{}", URL_SAFE_NO_PAD.encode(&json), owner.sign(&json));
let owner_id = agent_id::parse(&owner.id()).unwrap();
assert_eq!(
parse(&token).unwrap().verify(&owner_id, AUD, NOW),
Err(ApiError::InvalidCapability)
);
}
#[test]
fn malformed_and_other_version_capabilities_are_rejected_before_any_lookup() {
let (app, frame) = (Agent::new(2), Agent::new(3));
let encode =
|value: serde_json::Value| format!("{}.sig", URL_SAFE_NO_PAD.encode(value.to_string()));
let good = serde_json::to_value(claims(&frame, &app)).unwrap();
let mut v1 = good.clone();
v1["v"] = 1.into();
let mut extra = good.clone();
extra["scope"] = "all".into();
let mut missing_cnf = good.clone();
missing_cnf.as_object_mut().unwrap().remove("cnf");
let mut bad_cnf = good.clone();
bad_cnf["cnf"] = "did:ad:agent:test".into();
let mut bad_app = good.clone();
bad_app["app"] = "https://example.com/app".into();
let mut string_exp = good;
string_exp["exp"] = "1790000600".into();
for token in [
String::new(),
"no-dot".into(),
"!!!.sig".into(),
format!(
"{}.sig",
URL_SAFE_NO_PAD.encode(br#"{"v":1,"connection_id":"c","platform":"p","exp":1}"#)
),
encode(v1),
encode(extra),
encode(missing_cnf),
encode(bad_cnf),
encode(bad_app),
encode(string_exp),
"a".repeat(5000),
] {
assert_eq!(
parse(&token).err(),
Some(ApiError::InvalidCapability),
"{token}"
);
}
}
}