use crate::request::SubjectKind;
use evidence_request::registry::{Reason, SubjectForm};
use evidence_request::request::{Derivation, Request};
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::collections::BTreeMap;
pub const HEADER_FIELDS: [&str; 15] = [
"book_id",
"committed_at",
"correlation",
"counterparty_ref",
"epistemic_type",
"event_time_claim",
"links",
"payload_commitments",
"principal_ref",
"record_type",
"retention_state",
"seq",
"statement",
"subject_ref",
"v",
];
const MAX_NESTING: usize = 32;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct DerivationDefinition {
pub document: Vec<u8>,
pub recipient: Option<String>,
pub forms: Vec<SubjectKind>,
pub fields: Vec<String>,
}
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum DerivationError {
#[error("derivation definition: {0}")]
NotJson(String),
#[error("a derivation definition is a JSON object")]
NotAnObject,
#[error("derivation definition: {0}")]
Canonical(String),
#[error("a derivation declares its subject forms and its field set")]
Undeclared,
#[error("a derivation over records cannot be defined over checkpoints")]
OverCheckpoints,
#[error("{0:?} is not a record header member")]
NotAHeaderMember(String),
#[error("derivation {0} is registered with a different recipient, forms or fields")]
Redeclared(String),
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Registered {
id: String,
recipient: Option<String>,
forms: Vec<SubjectKind>,
fields: Vec<String>,
}
impl Registered {
pub fn id(&self) -> &str {
&self.id
}
pub fn recipient(&self) -> Option<&str> {
self.recipient.as_deref()
}
pub fn forms(&self) -> &[SubjectKind] {
&self.forms
}
pub fn fields(&self) -> &[String] {
&self.fields
}
pub fn declares(&self, form: SubjectForm) -> bool {
self.forms.iter().any(|&kind| subject_form(kind) == form)
}
pub fn authorizes(&self, requester: Option<&str>) -> Option<bool> {
self.recipient
.as_deref()
.map(|recipient| requester == Some(recipient))
}
}
#[derive(Clone, Debug, Default)]
pub struct Derivations {
by_id: BTreeMap<String, Registered>,
}
impl Derivations {
pub fn new() -> Self {
Self::default()
}
pub fn register(
&mut self,
definition: DerivationDefinition,
) -> Result<String, DerivationError> {
let document = decode_strict(&definition.document)?;
if !document.is_object() {
return Err(DerivationError::NotAnObject);
}
let canonical = crate::canonical::jcs(&document)
.map_err(|e| DerivationError::Canonical(e.to_string()))?;
if definition.forms.is_empty() || definition.fields.is_empty() {
return Err(DerivationError::Undeclared);
}
if definition.forms.contains(&SubjectKind::Checkpoints) {
return Err(DerivationError::OverCheckpoints);
}
if let Some(field) = definition
.fields
.iter()
.find(|f| !HEADER_FIELDS.contains(&f.as_str()))
{
return Err(DerivationError::NotAHeaderMember(field.clone()));
}
let id = hex::encode(Sha256::digest(&canonical));
let recipient = definition.recipient.filter(|r| !r.is_empty());
if let Some(prev) = self.by_id.get(&id) {
return if prev.recipient == recipient
&& same_set(&prev.forms, &definition.forms)
&& same_set(&prev.fields, &definition.fields)
{
Ok(id)
} else {
Err(DerivationError::Redeclared(id))
};
}
let registered = Registered {
id: id.clone(),
recipient,
forms: definition.forms,
fields: definition.fields,
};
self.by_id.insert(id.clone(), registered);
Ok(id)
}
pub fn get(&self, id: &str) -> Option<&Registered> {
self.by_id.get(id)
}
pub fn forms_of(&self, derivation: &Derivation) -> Option<Vec<SubjectForm>> {
match derivation {
Derivation::Digest(id) => self
.get(id)
.map(|r| r.forms.iter().map(|&kind| subject_form(kind)).collect()),
Derivation::Token(_) => None,
}
}
pub fn check(
&self,
request: &Request,
requester: Option<&str>,
share_policy_allows: bool,
) -> Result<Option<&Registered>, Reason> {
let Some(Derivation::Digest(id)) = &request.derivation else {
return Ok(None);
};
let registered = self.get(id).ok_or(Reason::DerivationUnsupported)?;
if !registered
.authorizes(requester)
.unwrap_or(share_policy_allows)
{
return Err(Reason::NotAuthorized);
}
if !registered.declares(request.subject.form()) {
return Err(Reason::NoSuchSubject);
}
Ok(Some(registered))
}
}
fn same_set<T: PartialEq>(a: &[T], b: &[T]) -> bool {
a.iter().all(|x| b.contains(x)) && b.iter().all(|x| a.contains(x))
}
pub(crate) fn subject_form(kind: SubjectKind) -> SubjectForm {
serde_json::to_value(kind)
.ok()
.as_ref()
.and_then(Value::as_str)
.and_then(SubjectForm::from_token)
.expect("every subject kind is a registry form")
}
pub(crate) fn decode_strict(document: &[u8]) -> Result<Value, DerivationError> {
let text = std::str::from_utf8(document)
.map_err(|_| DerivationError::NotJson("JSON text is not valid UTF-8".into()))?;
let mut reader = Reader {
text: text.as_bytes(),
at: 0,
canonical: None,
keep_numbers: false,
};
reader.space();
let value = reader.value(0)?;
reader.space();
if reader.at != reader.text.len() {
return Err(reader.malformed("trailing data after the JSON value"));
}
match reader.canonical {
Some(reason) => Err(DerivationError::Canonical(reason)),
None => Ok(value),
}
}
pub(crate) fn decode_syntax(document: &[u8]) -> Result<Value, DerivationError> {
let text = std::str::from_utf8(document)
.map_err(|_| DerivationError::NotJson("JSON text is not valid UTF-8".into()))?;
let mut reader = Reader {
text: text.as_bytes(),
at: 0,
canonical: None,
keep_numbers: true,
};
reader.space();
let value = reader.value(0)?;
reader.space();
if reader.at != reader.text.len() {
return Err(reader.malformed("trailing data after the JSON value"));
}
Ok(value)
}
struct Reader<'a> {
text: &'a [u8],
at: usize,
canonical: Option<String>,
keep_numbers: bool,
}
impl Reader<'_> {
fn malformed(&self, what: &str) -> DerivationError {
DerivationError::NotJson(format!("{what} at byte {}", self.at))
}
fn peek(&self) -> Option<u8> {
self.text.get(self.at).copied()
}
fn space(&mut self) {
while matches!(self.peek(), Some(b' ' | b'\t' | b'\n' | b'\r')) {
self.at += 1;
}
}
fn expect(&mut self, byte: u8) -> Result<(), DerivationError> {
if self.peek() != Some(byte) {
return Err(self.malformed(&format!("expected {:?}", byte as char)));
}
self.at += 1;
Ok(())
}
fn value(&mut self, depth: usize) -> Result<Value, DerivationError> {
if depth > MAX_NESTING {
return Err(self.malformed("nested too deeply"));
}
match self.peek() {
Some(b'{') => self.object(depth),
Some(b'[') => self.array(depth),
Some(b'"') => self.string().map(Value::String),
Some(b't') => self.literal("true", Value::Bool(true)),
Some(b'f') => self.literal("false", Value::Bool(false)),
Some(b'n') => self.literal("null", Value::Null),
Some(b'-' | b'0'..=b'9') => self.number(),
_ => Err(self.malformed("expected a JSON value")),
}
}
fn literal(&mut self, word: &str, value: Value) -> Result<Value, DerivationError> {
if !self.text[self.at..].starts_with(word.as_bytes()) {
return Err(self.malformed("expected a JSON value"));
}
self.at += word.len();
Ok(value)
}
fn object(&mut self, depth: usize) -> Result<Value, DerivationError> {
self.expect(b'{')?;
let mut members = serde_json::Map::new();
self.space();
if self.peek() == Some(b'}') {
self.at += 1;
return Ok(Value::Object(members));
}
loop {
self.space();
let name = self.string()?;
if members.contains_key(&name) {
return Err(self.malformed(&format!("duplicate member {name:?}")));
}
self.space();
self.expect(b':')?;
self.space();
let value = self.value(depth + 1)?;
members.insert(name, value);
self.space();
match self.peek() {
Some(b',') => self.at += 1,
Some(b'}') => {
self.at += 1;
return Ok(Value::Object(members));
}
_ => return Err(self.malformed("expected ',' or '}'")),
}
}
}
fn array(&mut self, depth: usize) -> Result<Value, DerivationError> {
self.expect(b'[')?;
let mut items = Vec::new();
self.space();
if self.peek() == Some(b']') {
self.at += 1;
return Ok(Value::Array(items));
}
loop {
self.space();
items.push(self.value(depth + 1)?);
self.space();
match self.peek() {
Some(b',') => self.at += 1,
Some(b']') => {
self.at += 1;
return Ok(Value::Array(items));
}
_ => return Err(self.malformed("expected ',' or ']'")),
}
}
}
fn string(&mut self) -> Result<String, DerivationError> {
self.expect(b'"')?;
let mut out = String::new();
loop {
let start = self.at;
while matches!(self.peek(), Some(c) if c != b'"' && c != b'\\' && c >= 0x20) {
self.at += 1;
}
out.push_str(std::str::from_utf8(&self.text[start..self.at]).expect("valid UTF-8"));
match self.peek() {
Some(b'"') => {
self.at += 1;
return Ok(out);
}
Some(b'\\') => {
self.at += 1;
out.push(self.escape()?);
}
Some(_) => return Err(self.malformed("control character in a string")),
None => return Err(self.malformed("unterminated string")),
}
}
}
fn escape(&mut self) -> Result<char, DerivationError> {
let c = self
.peek()
.ok_or_else(|| self.malformed("unterminated string"))?;
self.at += 1;
Ok(match c {
b'"' => '"',
b'\\' => '\\',
b'/' => '/',
b'b' => '\u{8}',
b'f' => '\u{c}',
b'n' => '\n',
b'r' => '\r',
b't' => '\t',
b'u' => {
let unit = self.hex4()?;
match unit {
0xd800..=0xdbff => {
if !self.text[self.at..].starts_with(b"\\u") {
return Err(self.malformed("unpaired high surrogate escape"));
}
self.at += 2;
let low = self.hex4()?;
if !(0xdc00..=0xdfff).contains(&low) {
return Err(self.malformed("unpaired high surrogate escape"));
}
let scalar = 0x10000 + ((unit - 0xd800) << 10) + (low - 0xdc00);
char::from_u32(scalar).expect("a surrogate pair is a scalar value")
}
0xdc00..=0xdfff => return Err(self.malformed("unpaired low surrogate escape")),
_ => char::from_u32(unit).expect("a non-surrogate unit is a scalar value"),
}
}
_ => return Err(self.malformed("invalid escape")),
})
}
fn hex4(&mut self) -> Result<u32, DerivationError> {
let digits = self
.text
.get(self.at..self.at + 4)
.and_then(|d| std::str::from_utf8(d).ok())
.filter(|d| d.bytes().all(|b| b.is_ascii_hexdigit()))
.ok_or_else(|| self.malformed("invalid \\u escape"))?;
self.at += 4;
Ok(u32::from_str_radix(digits, 16).expect("four hex digits"))
}
fn number(&mut self) -> Result<Value, DerivationError> {
let start = self.at;
let digits = |r: &mut Self| {
let from = r.at;
while matches!(r.peek(), Some(b'0'..=b'9')) {
r.at += 1;
}
r.at - from
};
if self.peek() == Some(b'-') {
self.at += 1;
}
match self.peek() {
Some(b'0') => self.at += 1,
Some(b'1'..=b'9') => {
digits(self);
}
_ => return Err(self.malformed("invalid number")),
}
let mut integer = true;
if self.peek() == Some(b'.') {
self.at += 1;
integer = false;
if digits(self) == 0 {
return Err(self.malformed("invalid number"));
}
}
if matches!(self.peek(), Some(b'e' | b'E')) {
self.at += 1;
integer = false;
if matches!(self.peek(), Some(b'+' | b'-')) {
self.at += 1;
}
if digits(self) == 0 {
return Err(self.malformed("invalid number"));
}
}
let token = std::str::from_utf8(&self.text[start..self.at]).expect("ASCII");
let reason = if !integer {
Some(format!(
"{token} is not an integer and has no canonical form"
))
} else if unsafe_integer(token) {
Some(format!("integer {token} is outside +/-(2^53 - 1)"))
} else {
None
};
if let Some(reason) = reason {
if self.keep_numbers {
let kept = token
.parse::<i64>()
.ok()
.filter(|_| token.trim_start_matches('-').len() <= 18)
.map(Value::from)
.or_else(|| {
token
.parse::<f64>()
.ok()
.and_then(serde_json::Number::from_f64)
.map(Value::Number)
});
return Ok(kept.unwrap_or(Value::Null));
}
self.canonical.get_or_insert(reason);
return Ok(Value::Null);
}
Ok(Value::from(token.parse::<i64>().expect("a safe integer")))
}
}
fn unsafe_integer(token: &str) -> bool {
let digits = token.strip_prefix('-').unwrap_or(token);
match digits.len().cmp(&16) {
std::cmp::Ordering::Greater => true,
std::cmp::Ordering::Less => false,
std::cmp::Ordering::Equal => digits > "9007199254740991",
}
}
#[cfg(test)]
mod tests {
use super::*;
fn define(document: &str) -> DerivationDefinition {
DerivationDefinition {
document: document.as_bytes().to_vec(),
recipient: None,
forms: vec![SubjectKind::Record],
fields: vec!["seq".into()],
}
}
#[test]
fn the_identifier_is_the_digest_of_the_jcs() {
let mut d = Derivations::new();
let a = d.register(define(r#"{ "b": [1, "x"], "a": -0 }"#)).unwrap();
let b = d.register(define(r#"{"a":0,"b":[1,"x"]}"#)).unwrap();
assert_eq!(a, b);
assert_eq!(a, hex::encode(Sha256::digest(br#"{"a":0,"b":[1,"x"]}"#)));
}
#[test]
fn the_reader_refuses_what_the_go_reader_refuses() {
let mut d = Derivations::new();
for bad in [
r#"{"a":1,"a":2}"#,
r#"{"a":1.0}"#,
r#"{"a":1e2}"#,
r#"{"a":-0.0}"#,
r#"{"a":9007199254740992}"#,
r#"{"a":123456789012345678901234567890}"#,
r#"{"a":"\ud800"}"#,
r#"{"a":-9007199254740992}"#,
r#"{"a":18446744073709551616}"#,
r#"{"a":1,"a":2.5}"#,
r#"{} {}"#,
"[1]",
"\"text\"",
] {
assert!(d.register(define(bad)).is_err(), "{bad}");
}
let private = "$serde_json::private::Number";
assert!(d
.register(define(&format!(r#"{{"{private}":1,"b":2}}"#)))
.is_ok());
assert!(d
.register(define(&format!(r#"{{"x":{{"{private}":"1.5"}}}}"#)))
.is_ok());
assert_eq!(
d.register(define(&format!(r#"{{"x":{{"{private}":"1.5"}}}}"#)))
.unwrap(),
hex::encode(Sha256::digest(format!(r#"{{"x":{{"{private}":"1.5"}}}}"#)))
);
for bad in [
format!(r#"{{"{private}":{{"a":1,"a":2}}}}"#),
format!(r#"{{"{private}":{}0{}}}"#, "[".repeat(40), "]".repeat(40)),
] {
assert!(
matches!(d.register(define(&bad)), Err(DerivationError::NotJson(_))),
"{bad}"
);
}
for bad in [
r#"{"a":01}"#,
r#"{"a":1.}"#,
r#"{"a":-}"#,
r#"{"a":tru}"#,
r#"{"a":1,}"#,
"{\"a\":\"\t\"}",
r#"{"a":"\x"}"#,
"{'a':1}",
"",
] {
assert!(
matches!(d.register(define(bad)), Err(DerivationError::NotJson(_))),
"{bad}"
);
}
for malformed in [r#"{"a":1,"a":2.5}"#, r#"{"a":1.5"#] {
assert!(matches!(
d.register(define(malformed)),
Err(DerivationError::NotJson(_))
));
}
assert!(d.register(define(r#"{"a":"1.5e3","b\"":"-0.1"}"#)).is_ok());
let nested = |n: usize| format!("{}{}", "[".repeat(n), "]".repeat(n));
assert!(d
.register(define(&format!(r#"{{"a":{}}}"#, nested(32))))
.is_ok());
assert!(d
.register(define(&format!(r#"{{"a":{}}}"#, nested(33))))
.is_err());
assert!(d
.register(define(&format!(
r#"{{"a":{}0{}}}"#,
"[".repeat(32),
"]".repeat(32)
)))
.is_err());
}
#[test]
fn a_definition_declares_record_forms_and_header_fields() {
let mut d = Derivations::new();
let mut def = define("{}");
def.forms.clear();
assert_eq!(d.register(def), Err(DerivationError::Undeclared));
let mut def = define("{}");
def.fields.clear();
assert_eq!(d.register(def), Err(DerivationError::Undeclared));
let mut def = define("{}");
def.forms.push(SubjectKind::Checkpoints);
assert_eq!(d.register(def), Err(DerivationError::OverCheckpoints));
let mut def = define("{}");
def.fields.push("payload".into());
assert_eq!(
d.register(def),
Err(DerivationError::NotAHeaderMember("payload".into()))
);
}
#[test]
fn a_recipient_is_the_only_requester_answered() {
let mut d = Derivations::new();
let mut def = define(r#"{"recipient":"alice"}"#);
def.recipient = Some("alice".into());
let id = d.register(def).unwrap();
let r = d.get(&id).unwrap();
assert_eq!(r.authorizes(Some("alice")), Some(true));
assert_eq!(r.authorizes(Some("bob")), Some(false));
assert_eq!(r.authorizes(None), Some(false));
let mut def = define("{}");
def.recipient = Some(String::new());
let open = d.register(def).unwrap();
assert_eq!(d.get(&open).unwrap().authorizes(None), None);
}
#[test]
fn check_authorizes_before_it_reads_the_form() {
let mut d = Derivations::new();
let mut def = define(r#"{"recipient":"alice"}"#);
def.recipient = Some("alice".into());
let named = d.register(def).unwrap();
let open = d.register(define(r#"{"open":true}"#)).unwrap();
let ask = |id: &str, subject: &str| {
let wire = format!(
r#"{{"subject":{subject},"coverage":{{"min_freshness":1}},"derivation":"{id}"}}"#
);
evidence_request::request::parse_json(wire.as_bytes()).unwrap()
};
let record = format!(r#"{{"record":"{}"}}"#, "ab".repeat(32));
let range = r#"{"range":[0,1]}"#;
let refused = |r: Result<Option<&Registered>, Reason>| r.err();
assert_eq!(
refused(d.check(&ask(&named, range), Some("bob"), true)),
Some(Reason::NotAuthorized)
);
assert_eq!(
refused(d.check(&ask(&named, range), Some("alice"), false)),
Some(Reason::NoSuchSubject)
);
assert!(d
.check(&ask(&named, &record), Some("alice"), false)
.unwrap()
.is_some());
assert_eq!(
refused(d.check(&ask(&open, range), None, false)),
Some(Reason::NotAuthorized)
);
assert_eq!(
refused(d.check(&ask(&open, range), None, true)),
Some(Reason::NoSuchSubject)
);
assert!(d.check(&ask(&open, &record), None, true).unwrap().is_some());
let unknown = "cd".repeat(32);
assert_eq!(
refused(d.check(&ask(&unknown, &record), None, true)),
Some(Reason::DerivationUnsupported)
);
let plain = evidence_request::request::parse_json(
br#"{"subject":{"checkpoints":null},"coverage":{"min_freshness":1}}"#,
)
.unwrap();
assert!(d.check(&plain, None, false).unwrap().is_none());
}
}