use crate::answer::{self, anchor_digest, citing_half, Options, Record, Selection};
use crate::ask::{profile_time, Book, Entry, Sealed};
use crate::derivation::{Derivations, Registered};
use crate::record::{record_types, EpistemicType};
use crate::request::SubjectKind;
use crate::standard_history::{HeldRecord, StandardHistorySource};
use crate::store::{CheckpointedLog, RecordSource};
use crate::substrate::StatedCheckpoint;
use ed25519_dalek::SigningKey;
use evidence_request::envelope::{Binding, Envelope};
use evidence_request::registry::Reason;
use evidence_request::request::{self, Coverage, Derivation, Freshness, Request, Subject};
use evidence_request::resolve::{self, ResolvedAnchor};
use evidence_request::time::{parse_utc, UtcTime};
use serde::Serialize;
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use std::collections::BTreeMap;
use std::sync::Mutex;
pub const DEFAULT_MAX_REQUEST_BYTES: usize = 64 << 10;
pub const DEFAULT_MAX_ANSWER_ITEMS: usize = 10_000;
pub const PROFILE_ID: &str = crate::ask::PROFILE_ID;
pub const PROFILE_V1: &str = evidence_request::envelope::PROFILE_V1;
pub(crate) const ANSWERED_PROFILES: [&str; 2] = [
evidence_request::envelope::PROFILE,
evidence_request::envelope::PROFILE_V1,
];
pub trait RequestLimiter: Send + Sync {
fn allow(&self, requester: Option<&str>, now: UtcTime) -> bool;
}
pub struct WindowLimiter {
n: usize,
window: i64,
seen: Mutex<BTreeMap<Option<String>, Vec<UtcTime>>>,
}
impl WindowLimiter {
pub fn new(n: usize, window_seconds: i64) -> Self {
WindowLimiter {
n,
window: window_seconds,
seen: Mutex::new(BTreeMap::new()),
}
}
}
impl RequestLimiter for WindowLimiter {
fn allow(&self, requester: Option<&str>, now: UtcTime) -> bool {
let mut seen = self.seen.lock().expect("limiter lock");
let bucket = seen.entry(requester.map(str::to_string)).or_default();
let cutoff = UtcTime {
seconds: now.seconds - self.window,
nanos: now.nanos,
};
bucket.retain(|t| *t > cutoff);
if bucket.len() >= self.n {
return false;
}
bucket.push(now);
true
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum RefusalPolicy {
Specific,
#[default]
Uniform,
}
#[derive(Default)]
pub struct ResponderPolicy {
pub refusal_policy: RefusalPolicy,
pub limiter: Option<Box<dyn RequestLimiter>>,
pub max_request_bytes: usize,
pub max_answer_items: usize,
pub history_window: usize,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
pub struct SharePolicy {
pub record_at_completion: String,
pub history_segments: String,
pub adjudications: String,
#[serde(skip_serializing_if = "String::is_empty")]
pub witness: String,
}
impl Default for SharePolicy {
fn default() -> Self {
SharePolicy {
record_at_completion: "counterparty".into(),
history_segments: "counterparties".into(),
adjudications: "deliver_to_subjects".into(),
witness: String::new(),
}
}
}
impl SharePolicy {
pub fn validate(&self) -> Result<(), RespondError> {
let checks: [(&str, &str, &[&str]); 3] = [
(
"record_at_completion",
&self.record_at_completion,
&["counterparty", "off"],
),
(
"history_segments",
&self.history_segments,
&["counterparties", "prospective", "peers", "off"],
),
(
"adjudications",
&self.adjudications,
&["deliver_to_subjects", "off"],
),
];
for (name, value, allowed) in checks {
if !allowed.contains(&value) {
return Err(RespondError::Invalid(format!(
"share.{name}={value:?} is not one of {allowed:?}"
)));
}
}
Ok(())
}
fn may_have(
&self,
requester: Option<&str>,
relationship: Relationship,
named: &[Option<String>],
) -> bool {
let Some(requester) = requester else {
return false;
};
match self.history_segments.as_str() {
"peers" => true,
"counterparties" | "prospective" => {
relationship == Relationship::Counterparty
&& named.iter().all(|c| c.as_deref() == Some(requester))
}
_ => false,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Relationship {
Stranger,
Identified,
Counterparty,
}
impl Relationship {
pub fn as_str(self) -> &'static str {
match self {
Relationship::Stranger => "stranger",
Relationship::Identified => "identified",
Relationship::Counterparty => "counterparty",
}
}
}
#[derive(Clone, Debug, Default)]
pub struct RespondOptions<'a> {
pub authenticated_requester: Option<&'a str>,
pub policy: SharePolicy,
}
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
pub struct AnsweredStatement {
pub request_digest: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub subject_kind: Option<SubjectKind>,
pub outcome: String,
#[serde(skip_serializing_if = "String::is_empty")]
pub reason: String,
pub relationship: String,
#[serde(skip_serializing_if = "String::is_empty")]
pub anchor: String,
#[serde(skip_serializing_if = "String::is_empty")]
pub artifact_digest: String,
}
pub const OUTCOME_ARTIFACT: &str = "artifact";
pub const OUTCOME_REFUSAL: &str = "refusal";
#[derive(Debug, thiserror::Error)]
pub enum RespondError {
#[error("invalid: {0}")]
Invalid(String),
#[error(transparent)]
Seal(#[from] crate::ask::SealError),
#[error(transparent)]
Substrate(#[from] crate::substrate::SubstrateError),
#[error("answer: {0}")]
Answer(#[from] answer::AnswerError),
#[error("sign: {0}")]
Sign(String),
}
pub struct Responder<'a> {
pub signer: &'a SigningKey,
pub derivations: &'a Derivations,
pub policy: &'a ResponderPolicy,
pub standard_history: Option<&'a StandardHistorySource>,
}
fn sha256_hex(bytes: &[u8]) -> String {
hex::encode(Sha256::digest(bytes))
}
pub fn respond<B: Book + CheckpointedLog>(
book: &mut B,
responder: &Responder<'_>,
octets: &[u8],
binding: Binding,
opts: &RespondOptions<'_>,
) -> Result<(Vec<u8>, Option<Sealed>), RespondError> {
opts.policy.validate()?;
if let Some(source) = responder.standard_history {
source
.validate()
.map_err(|e| RespondError::Invalid(e.to_string()))?;
}
let now_text = book.now();
if parse_utc(&now_text).is_none() {
return Err(RespondError::Invalid(format!(
"the book's clock read {now_text:?}, not an RFC 3339 UTC time"
)));
}
let mut run = Run {
responder,
octets,
binding,
opts,
now_text,
digest: sha256_hex(octets),
statement: AnsweredStatement::default(),
seal: false,
};
let reply = run.run(book)?;
if !run.seal {
return Ok((reply, None));
}
let statement =
serde_json::to_value(&run.statement).map_err(|e| RespondError::Invalid(e.to_string()))?;
let sealed = book.seal(&Entry {
record_type: record_types::REQUEST_ANSWERED.into(),
epistemic_type: EpistemicType::ObservedEvent,
links: Vec::new(),
statement,
})?;
Ok((reply, Some(sealed)))
}
struct Run<'a, 'b> {
responder: &'a Responder<'a>,
octets: &'a [u8],
binding: Binding,
opts: &'a RespondOptions<'b>,
now_text: String,
digest: String,
statement: AnsweredStatement,
seal: bool,
}
impl Run<'_, '_> {
fn now(&self) -> UtcTime {
parse_utc(&self.now_text).expect("a book's clock reads RFC 3339 UTC")
}
fn refuse(&mut self, reason: Reason, detail: Option<&str>) -> Result<Vec<u8>, RespondError> {
let refusal = evidence_request::refusal::sign(
&self.digest,
reason,
&profile_time(&self.now_text),
self.responder.signer,
)
.map_err(|e| RespondError::Sign(e.to_string()))?;
self.statement.outcome = OUTCOME_REFUSAL.into();
self.statement.reason = reason.token().into();
Ok(encode_refusal(&refusal, detail, self.binding))
}
fn run<B: Book + CheckpointedLog>(&mut self, book: &mut B) -> Result<Vec<u8>, RespondError> {
let policy = self.responder.policy;
let limit = match policy.max_request_bytes {
0 => DEFAULT_MAX_REQUEST_BYTES,
n => n,
};
let requester = self.opts.authenticated_requester;
if self.octets.len() > limit {
return self.refuse(limit_reason(self.octets, self.binding), None);
}
if let Some(limiter) = &policy.limiter {
if !limiter.allow(requester, self.now()) {
return self.refuse(limit_reason(self.octets, self.binding), None);
}
}
let req = match read_request(self.octets, self.binding) {
Ok(req) => req,
Err((reason, detail)) => return self.refuse(reason, detail),
};
let relationship = relationship(book, requester);
self.statement = AnsweredStatement {
request_digest: self.digest.clone(),
subject_kind: Some(subject_kind(&req.subject)),
relationship: relationship.as_str().into(),
..Default::default()
};
self.seal = relationship != Relationship::Stranger;
let gate = Gate {
requester,
relationship,
share: &self.opts.policy,
derivations: self.responder.derivations,
standard_history: self.responder.standard_history.is_some(),
uniform: policy.refusal_policy == RefusalPolicy::Uniform,
};
let mut view = View::of(book)?;
let mut decision = decide(
&view,
&req,
&gate,
&|r, reg| authorized(&view, r, &gate, reg),
self.now(),
self.seal,
);
if matches!(decision, Decision::NeedAnchor) {
book.checkpoint()?;
view = View::of(book)?;
decision = decide(
&view,
&req,
&gate,
&|r, reg| authorized(&view, r, &gate, reg),
self.now(),
false,
);
if matches!(decision, Decision::NeedAnchor) {
decision = Decision::Refuse(gate.disclose(Reason::CoverageUnsatisfiable));
}
}
let (anchor_at, half_pin, leaves) = match decision {
Decision::Refuse(reason) => return self.refuse(reason, None),
Decision::NeedAnchor => unreachable!("a second NeedAnchor is refused above"),
Decision::Serve {
anchor,
half_pin,
leaves,
} => (anchor, half_pin, leaves),
};
let max_items = match policy.max_answer_items {
0 => DEFAULT_MAX_ANSWER_ITEMS,
n => n,
};
let anchor = &view.checkpoints[anchor_at];
let chain = anchor_at + 1;
let over = !is_standard_history(&req)
&& !is_history_card_2(&req)
&& (leaves.len() > max_items
|| (matches!(req.subject, Subject::Checkpoints) || is_history_card(&req))
&& chain > max_items
|| matches!(req.subject, Subject::CheckpointRange(a, b)
if b - a + 1 > max_items as u64));
if over {
return self.refuse(limit_reason(self.octets, self.binding), None);
}
let resolved = if half_pin {
ResolvedAnchor::ExchangeHalf(match &req.coverage {
Coverage::ExpectedPin(pin) => pin.clone(),
Coverage::MinFreshness(_) => unreachable!("a half pin is an expected_pin"),
})
} else {
ResolvedAnchor::Anchor(resolve::Anchor {
digest: anchor_digest(anchor),
size: anchor.checkpoint.leaf_count()?,
issued_at: anchor.checkpoint.timestamp.clone(),
})
};
let standard_card = match self.responder.standard_history {
Some(source) if is_standard_history(&req) => {
Some(standard_card(source, &view, anchor_at, &leaves)?)
}
_ => None,
};
let book: &B = book;
let envelope = match answer::build(
book,
book,
&req,
self.octets,
&resolved,
&Selection {
at: anchor_at,
records: leaves,
},
Options {
derivations: Some(self.responder.derivations),
requester,
standard_card: standard_card.as_deref(),
history_window: self.responder.policy.history_window,
..Options::default()
},
self.responder.signer,
&profile_time(&self.now_text),
) {
Ok(envelope) => envelope,
Err(answer::AnswerError::OverLimit) => {
return self.refuse(limit_reason(self.octets, self.binding), None)
}
Err(answer::AnswerError::NotAuthorized) => {
return self.refuse(gate.disclose(Reason::NotAuthorized), None)
}
Err(e) => return Err(e.into()),
};
if let Some(deadline) = req.deadline {
if parse_utc(&book.now()).is_some_and(|now| now > deadline) {
return self.refuse(Reason::DeadlineUnmet, None);
}
}
self.statement.outcome = OUTCOME_ARTIFACT.into();
self.statement.anchor = envelope.anchor.digest.clone();
self.statement.artifact_digest = envelope.artifact_digest.clone();
Ok(encode_envelope(&envelope, self.binding))
}
}
fn is_standard_history(req: &Request) -> bool {
matches!(&req.derivation, Some(Derivation::Token(t)) if t == answer::DERIVATION_STANDARD_HISTORY)
}
fn standard_card(
source: &StandardHistorySource,
view: &View<'_>,
anchor_at: usize,
leaves: &[u64],
) -> Result<Vec<u8>, RespondError> {
let held = leaves
.iter()
.map(|&leaf| {
let record = view.src.record_at(leaf)?;
let header = view.src.header_of(&record)?;
Some(HeldRecord { record, header })
})
.collect::<Option<Vec<_>>>()
.ok_or_else(|| RespondError::Invalid("a record the anchor covers cannot be read".into()))?;
source
.card(
&view.checkpoints[anchor_at],
&view.checkpoints[0].checkpoint.timestamp,
&held,
)
.map_err(|e| RespondError::Invalid(e.to_string()))
}
fn is_history_card(req: &Request) -> bool {
matches!(&req.derivation, Some(Derivation::Token(t)) if t == answer::DERIVATION_HISTORY_CARD)
}
fn is_history_card_2(req: &Request) -> bool {
matches!(&req.derivation, Some(Derivation::Token(t)) if t == answer::DERIVATION_HISTORY_CARD_2)
}
fn encode_envelope(envelope: &Envelope, binding: Binding) -> Vec<u8> {
envelope.encode(binding)
}
fn encode_refusal(
refusal: &evidence_request::refusal::Refusal,
detail: Option<&str>,
binding: Binding,
) -> Vec<u8> {
match (binding, detail) {
(Binding::Json, None) => evidence_request::jcs::to_string(&refusal.to_json())
.expect("text members canonicalize")
.into_bytes(),
(Binding::Json, Some(detail)) => {
let mut object = refusal.to_json();
object["detail"] = json!(detail);
evidence_request::jcs::to_string(&object)
.expect("text members canonicalize")
.into_bytes()
}
(Binding::Cbor, None) => refusal.to_cbor(),
(Binding::Cbor, Some(detail)) => {
use ciborium::Value as C;
let text = |s: &str| C::Text(s.to_string());
let encoded = |v: &C| {
let mut out = Vec::new();
ciborium::into_writer(v, &mut out).expect("writing to a Vec never fails");
out
};
let mut entries = vec![
(text("issued_at"), text(&refusal.issued_at)),
(text("reason"), text(refusal.reason.token())),
(text("request_digest"), text(&refusal.request_digest)),
(text("key_id"), text(&refusal.key_id)),
(text("sig"), text(&refusal.sig)),
(text("detail"), text(detail)),
];
entries.sort_by_cached_key(|(k, _)| encoded(k));
encoded(&C::Map(entries))
}
}
}
fn subject_kind(subject: &Subject) -> SubjectKind {
match subject {
Subject::FullHistory => SubjectKind::FullHistory,
Subject::Checkpoints | Subject::CheckpointRange(..) => SubjectKind::Checkpoints,
Subject::Record(_) => SubjectKind::Record,
Subject::Range(..) => SubjectKind::Range,
Subject::Correlation(_) => SubjectKind::Correlation,
_ => SubjectKind::CitingRecords,
}
}
fn limit_reason(octets: &[u8], binding: Binding) -> Reason {
if read_request(octets, binding).is_err() {
return Reason::PolicyDeclined;
}
match named_profile(octets, binding) {
NamedProfile::Text(profile) if profile == PROFILE_V1 => Reason::CapacityExceeded,
_ => Reason::PolicyDeclined,
}
}
enum NamedProfile {
Absent,
Text(String),
NotText,
}
pub(crate) fn requested_profile(octets: &[u8]) -> Option<String> {
let binding = if serde_json::from_slice::<Value>(octets).is_ok() {
Binding::Json
} else {
Binding::Cbor
};
match named_profile(octets, binding) {
NamedProfile::Absent => Some(evidence_request::envelope::PROFILE.to_string()),
NamedProfile::Text(profile) if profile.is_empty() => {
Some(evidence_request::envelope::PROFILE.to_string())
}
NamedProfile::Text(profile) => Some(profile),
NamedProfile::NotText => None,
}
}
fn named_profile(octets: &[u8], binding: Binding) -> NamedProfile {
match binding {
Binding::Json => match serde_json::from_slice::<Value>(octets)
.ok()
.and_then(|v| v.get("profile").cloned())
{
None => NamedProfile::Absent,
Some(Value::String(s)) => NamedProfile::Text(s),
Some(_) => NamedProfile::NotText,
},
Binding::Cbor => {
let Ok(ciborium::Value::Map(entries)) = ciborium::from_reader(octets) else {
return NamedProfile::Absent;
};
for (k, v) in entries {
if matches!(&k, ciborium::Value::Text(k) if k == "profile") {
return match v {
ciborium::Value::Text(v) => NamedProfile::Text(v),
_ => NamedProfile::NotText,
};
}
}
NamedProfile::Absent
}
}
}
struct NoDuplicates;
impl<'de> serde::Deserialize<'de> for NoDuplicates {
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
struct Visitor;
impl<'de> serde::de::Visitor<'de> for Visitor {
type Value = NoDuplicates;
fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("JSON with no repeated member name")
}
fn visit_map<A: serde::de::MapAccess<'de>>(
self,
mut map: A,
) -> Result<NoDuplicates, A::Error> {
let mut seen = std::collections::BTreeSet::new();
while let Some(key) = map.next_key::<String>()? {
if !seen.insert(key.clone()) {
return Err(serde::de::Error::custom(format!("repeated member {key:?}")));
}
map.next_value::<NoDuplicates>()?;
}
Ok(NoDuplicates)
}
fn visit_seq<A: serde::de::SeqAccess<'de>>(
self,
mut seq: A,
) -> Result<NoDuplicates, A::Error> {
while seq.next_element::<NoDuplicates>()?.is_some() {}
Ok(NoDuplicates)
}
fn visit_bool<E>(self, _: bool) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
fn visit_i64<E>(self, _: i64) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
fn visit_u64<E>(self, _: u64) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
fn visit_f64<E>(self, _: f64) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
fn visit_str<E>(self, _: &str) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
fn visit_unit<E>(self) -> Result<NoDuplicates, E> {
Ok(NoDuplicates)
}
}
d.deserialize_any(Visitor)
}
}
fn members_well_formed(octets: &[u8], binding: Binding) -> bool {
if matches!(named_profile(octets, binding), NamedProfile::NotText) {
return false;
}
let derivation = match binding {
Binding::Json => serde_json::from_slice::<Value>(octets)
.ok()
.and_then(|v| v.get("derivation").cloned())
.map(|d| match d {
Value::String(s) => Some(s),
_ => None,
}),
Binding::Cbor => match ciborium::from_reader(octets) {
Ok(ciborium::Value::Map(entries)) => entries
.into_iter()
.find(|(k, _)| matches!(k, ciborium::Value::Text(k) if k == "derivation"))
.map(|(_, v)| match v {
ciborium::Value::Text(s) => Some(s),
_ => None,
}),
_ => None,
},
};
match derivation {
None => true,
Some(None) => false,
Some(Some(text)) => crate::ask::derivation_text_is_well_formed(&text),
}
}
type Refused = (Reason, Option<&'static str>);
fn read_request(octets: &[u8], binding: Binding) -> Result<Request, Refused> {
let parsed = match binding {
Binding::Json => {
if serde_json::from_slice::<NoDuplicates>(octets).is_err() {
return Err((Reason::RequestMalformed, None));
}
request::parse_json(octets)
}
Binding::Cbor => request::parse_cbor(octets),
};
let req = match parsed {
Ok(req) => req,
Err(request::RequestError::CoverageUnsatisfiable)
if !members_well_formed(octets, binding) =>
{
return Err((Reason::RequestMalformed, None))
}
Err(e) => return Err((e.reason(), None)),
};
if !crate::ask::derivation_is_well_formed(&req) {
return Err((Reason::RequestMalformed, None));
}
match named_profile(octets, binding) {
NamedProfile::Absent => {}
NamedProfile::NotText => return Err((Reason::RequestMalformed, None)),
NamedProfile::Text(profile) => {
if !profile.is_empty() && !ANSWERED_PROFILES.contains(&profile.as_str()) {
return Err((Reason::RequestMalformed, Some(const_concat_profiles())));
}
}
}
Ok(req)
}
pub(crate) fn read_sent_request(octets: &[u8]) -> Result<Request, Reason> {
read_request(octets, Binding::Json).map_err(|(reason, _)| reason)
}
fn const_concat_profiles() -> &'static str {
"profiles supported: evidence-interop/0, evidence-interop/1"
}
fn relationship<B: Book>(book: &B, authenticated: Option<&str>) -> Relationship {
let Some(authenticated) = authenticated else {
return Relationship::Stranger;
};
for leaf in 0..book.len() {
let counterparty = book
.record_at(leaf)
.and_then(|r| book.header_of(&r))
.and_then(|h| {
h.get("counterparty_ref")
.and_then(Value::as_str)
.map(str::to_string)
});
if counterparty.as_deref() == Some(authenticated) {
return Relationship::Counterparty;
}
}
Relationship::Identified
}
struct Gate<'a> {
requester: Option<&'a str>,
relationship: Relationship,
share: &'a SharePolicy,
derivations: &'a Derivations,
standard_history: bool,
uniform: bool,
}
impl Gate<'_> {
fn disclose(&self, reason: Reason) -> Reason {
if self.uniform
&& matches!(
reason,
Reason::NotAuthorized | Reason::NoSuchSubject | Reason::CoverageUnsatisfiable
)
{
Reason::PolicyDeclined
} else {
reason
}
}
}
struct AnchorFacts {
digest: String,
entries: u64,
issued: UtcTime,
}
trait Evidence {
fn anchors(&self) -> &[AnchorFacts];
fn entries(&self) -> u64;
fn leaf_of(&self, digest: &str) -> Option<u64>;
fn servable(&self, leaf: u64) -> bool;
fn correlated(&self, id: &str) -> Vec<u64>;
fn citing(&self, half: &str) -> Vec<u64>;
fn counterparty(&self, leaf: u64) -> Option<String>;
fn lapsed(&self, subject: &Subject, now: UtcTime) -> bool;
fn named(&self, subject: &Subject) -> Vec<Option<String>> {
let leaves: Vec<u64> = match (subject, citing_half(subject)) {
(Subject::Record(d), _) => self.leaf_of(d).into_iter().collect(),
(Subject::Correlation(id), _) => self.correlated(id),
(_, Some(half)) => self.citing(half),
_ => Vec::new(),
};
leaves.into_iter().map(|l| self.counterparty(l)).collect()
}
}
struct View<'a> {
checkpoints: Vec<StatedCheckpoint>,
anchors: Vec<AnchorFacts>,
entries: u64,
leaves: Vec<LeafFacts>,
commitments: Vec<(Subject, UtcTime)>,
by_entry: BTreeMap<String, u64>,
src: &'a dyn RecordSource,
}
struct LeafFacts {
servable: bool,
counterparty: Option<String>,
}
impl<'a> View<'a> {
fn of<B: Book + CheckpointedLog>(book: &'a B) -> Result<View<'a>, RespondError> {
let checkpoints = book.stated_checkpoints()?;
let mut anchors = Vec::with_capacity(checkpoints.len());
for cp in &checkpoints {
let issued = parse_utc(&cp.checkpoint.timestamp).ok_or_else(|| {
RespondError::Invalid(format!("checkpoint time {:?}", cp.checkpoint.timestamp))
})?;
anchors.push(AnchorFacts {
digest: anchor_digest(cp),
entries: cp.checkpoint.leaf_count()?,
issued,
});
}
let entries = book.len();
let mut leaves = Vec::with_capacity(entries as usize);
let mut commitments = Vec::new();
let mut by_entry = BTreeMap::new();
for leaf in 0..entries {
let record: Option<Record> = book.record_at(leaf);
let header = record.as_ref().and_then(|r| book.header_of(r));
let kind = match header
.as_ref()
.and_then(|h| h.get("record_type").and_then(Value::as_str))
{
Some(kind) => kind,
None => {
return Err(RespondError::Invalid(format!(
"the book holds no record_type for the record at leaf {leaf}; a responder needs RecordSource::header_of"
)))
}
};
let servable = !matches!(
kind,
record_types::REQUEST_ANSWERED | record_types::DISCLOSURE
);
let counterparty = header
.as_ref()
.and_then(|h| h.get("counterparty_ref").and_then(Value::as_str))
.map(str::to_string);
if let Some(record) = &record {
by_entry.entry(record.digest.clone()).or_insert(leaf);
}
if kind == "retention_commitment" {
if let Some(c) = header
.as_ref()
.and_then(|h| h.get("statement"))
.and_then(read_commitment)
{
commitments.push(c);
}
}
leaves.push(LeafFacts {
servable,
counterparty,
});
}
Ok(View {
checkpoints,
anchors,
entries,
leaves,
commitments,
by_entry,
src: book,
})
}
}
impl Evidence for View<'_> {
fn servable(&self, leaf: u64) -> bool {
self.leaves.get(leaf as usize).is_some_and(|l| l.servable)
}
fn leaf_of(&self, digest: &str) -> Option<u64> {
self.by_entry
.get(digest)
.copied()
.filter(|&l| self.servable(l))
}
fn correlated(&self, id: &str) -> Vec<u64> {
let mut leaves = self.src.correlation(id);
leaves.retain(|&l| self.servable(l));
leaves
}
fn citing(&self, half: &str) -> Vec<u64> {
let mut leaves = self.src.citing(half);
leaves.retain(|&l| self.servable(l));
leaves
}
fn lapsed(&self, subject: &Subject, now: UtcTime) -> bool {
self.commitments
.iter()
.any(|(s, until)| s == subject && now > *until)
}
fn counterparty(&self, leaf: u64) -> Option<String> {
self.leaves.get(leaf as usize)?.counterparty.clone()
}
fn anchors(&self) -> &[AnchorFacts] {
&self.anchors
}
fn entries(&self) -> u64 {
self.entries
}
}
fn read_commitment(statement: &Value) -> Option<(Subject, UtcTime)> {
let subject = request::subject_from_value(statement.get("subject")?).ok()?;
let until = evidence_request::envelope::is_profile_time(statement.get("until")?.as_str()?)
.then(|| parse_utc(statement["until"].as_str()?))
.flatten()?;
Some((subject, until))
}
enum Decision {
Refuse(Reason),
NeedAnchor,
Serve {
anchor: usize,
half_pin: bool,
leaves: Vec<u64>,
},
}
fn decide(
view: &dyn Evidence,
req: &Request,
gate: &Gate<'_>,
authorize: &dyn Fn(&Request, Option<&Registered>) -> bool,
now: UtcTime,
may_issue: bool,
) -> Decision {
decide_inner(view, req, gate, authorize, now, may_issue)
}
fn decide_inner(
view: &dyn Evidence,
req: &Request,
gate: &Gate<'_>,
authorize: &dyn Fn(&Request, Option<&Registered>) -> bool,
now: UtcTime,
may_issue: bool,
) -> Decision {
use Decision::Refuse;
if let Some(deadline) = req.deadline {
if now >= deadline {
return Refuse(Reason::DeadlineUnmet);
}
}
let form = req.subject.form();
let mut registered: Option<&Registered> = None;
match &req.derivation {
Some(Derivation::Token(t))
if t == answer::DERIVATION_HISTORY_CARD || t == answer::DERIVATION_HISTORY_CARD_2 =>
{
if !matches!(req.subject, Subject::FullHistory | Subject::Checkpoints) {
return Refuse(Reason::NoSuchSubject);
}
}
Some(Derivation::Token(t)) if t == answer::DERIVATION_STANDARD_HISTORY => {
if !gate.standard_history {
return Refuse(Reason::DerivationUnsupported);
}
}
Some(Derivation::Token(_)) => return Refuse(Reason::DerivationUnsupported),
Some(Derivation::Digest(id)) => match gate.derivations.get(id) {
Some(r) => registered = Some(r),
None => return Refuse(Reason::DerivationUnsupported),
},
None => {}
}
if !authorize(req, registered) {
return Refuse(gate.disclose(Reason::NotAuthorized));
}
if let Some(r) = registered {
if !r.declares(form) {
return Refuse(gate.disclose(Reason::NoSuchSubject));
}
}
if is_standard_history(req) && !matches!(req.subject, Subject::FullHistory) {
return Refuse(gate.disclose(Reason::NoSuchSubject));
}
let (anchor, half_pin) = match resolve_coverage(view, req, now, may_issue) {
Ok(chosen) => chosen,
Err(Refuse(reason)) => return Refuse(gate.disclose(reason)),
Err(decision) => return decision,
};
match resolve_subject(view, req, anchor, half_pin, now) {
Refuse(reason) => Refuse(gate.disclose(reason)),
other => other,
}
}
fn authorized(
view: &dyn Evidence,
req: &Request,
gate: &Gate<'_>,
registered: Option<&Registered>,
) -> bool {
let public = (matches!(
req.subject,
Subject::Checkpoints | Subject::CheckpointRange(..)
) && req.derivation.is_none())
|| is_history_card(req)
|| is_history_card_2(req);
if public {
return true; }
if is_standard_history(req) {
return gate.requester.is_some();
}
if let Some(recipient) = registered.and_then(Registered::recipient) {
return gate.requester == Some(recipient);
}
match &req.subject {
Subject::Record(_) | Subject::Correlation(_) => {}
subject if citing_half(subject).is_some() => {}
_ => return false,
}
gate.share
.may_have(gate.requester, gate.relationship, &view.named(&req.subject))
}
fn resolve_coverage(
view: &dyn Evidence,
req: &Request,
now: UtcTime,
may_issue: bool,
) -> Result<(usize, bool), Decision> {
let unsatisfiable = || Decision::Refuse(Reason::CoverageUnsatisfiable);
match &req.coverage {
Coverage::ExpectedPin(pin) => {
if let Some(i) = view.anchors().iter().position(|a| a.digest == *pin) {
return Ok((i, false));
}
if citing_half(&req.subject) == Some(pin.as_str()) {
return Ok((usize::MAX, true));
}
Err(unsatisfiable())
}
Coverage::MinFreshness(floor) => {
for i in (0..view.anchors().len()).rev() {
let AnchorFacts {
entries, issued, ..
} = view.anchors()[i];
let meets = match floor {
Freshness::Size(n) => entries >= *n,
Freshness::Time(t) => {
UtcTime {
seconds: issued.seconds,
nanos: 0,
} >= *t
}
};
if meets {
return Ok((i, false));
}
}
let beyond = match floor {
Freshness::Size(n) => *n > view.entries(),
Freshness::Time(t) => *t > now,
};
if beyond || !may_issue || view.entries() == 0 {
return Err(unsatisfiable());
}
Err(Decision::NeedAnchor)
}
}
}
fn resolve_subject(
view: &dyn Evidence,
req: &Request,
anchor: usize,
half_pin: bool,
now: UtcTime,
) -> Decision {
use Decision::Refuse;
let no_such = || {
Refuse(if view.lapsed(&req.subject, now) {
Reason::RetentionExpired
} else {
Reason::NoSuchSubject
})
};
let mut anchor = anchor;
if half_pin {
let half = citing_half(&req.subject).expect("a half pin is a citing-records subject");
let cited = view.citing(half);
if cited.is_empty() {
return no_such();
}
let latest = view.anchors().last().map_or(0, |a| a.entries);
let Some(last) = cited.iter().copied().filter(|&l| l < latest).max() else {
return Refuse(Reason::CoverageUnsatisfiable);
};
match view.anchors().iter().position(|a| a.entries > last) {
Some(i) => anchor = i,
None => return Refuse(Reason::CoverageUnsatisfiable),
}
}
if anchor >= view.anchors().len() {
return Refuse(Reason::CoverageUnsatisfiable);
}
let covered = view.anchors()[anchor].entries;
let serve = |leaves: Vec<u64>| Decision::Serve {
anchor,
half_pin,
leaves,
};
match &req.subject {
Subject::Checkpoints => serve(Vec::new()),
Subject::CheckpointRange(_, end) => {
if *end > anchor as u64 {
return Refuse(Reason::CoverageUnsatisfiable);
}
serve(Vec::new())
}
Subject::FullHistory => {
let leaves: Vec<u64> = (0..covered).filter(|&l| view.servable(l)).collect();
if leaves.is_empty() && req.derivation.is_none() {
return Refuse(Reason::NoSuchSubject);
}
serve(leaves)
}
Subject::Record(d) => match view.leaf_of(d) {
None => no_such(),
Some(leaf) if leaf >= covered => Refuse(Reason::CoverageUnsatisfiable),
Some(leaf) => serve(vec![leaf]),
},
Subject::Range(a, b) => {
if *b >= covered {
if *b < view.entries() {
return Refuse(Reason::CoverageUnsatisfiable);
}
return no_such();
}
let leaves: Vec<u64> = (*a..=*b).filter(|&l| view.servable(l)).collect();
if leaves.is_empty() {
return no_such();
}
serve(leaves)
}
subject => {
let all = match (subject, citing_half(subject)) {
(Subject::Correlation(id), _) => view.correlated(id),
(_, Some(half)) => view.citing(half),
_ => unreachable!("every other form is matched above"),
};
let mut leaves: Vec<u64> = all.iter().copied().filter(|&l| l < covered).collect();
leaves.sort_unstable();
leaves.dedup();
if !leaves.is_empty() {
return serve(leaves);
}
if !all.is_empty() {
return Refuse(Reason::CoverageUnsatisfiable);
}
no_such()
}
}
}
#[cfg(test)]
mod vectors {
use super::*;
use std::collections::BTreeMap;
use std::path::PathBuf;
fn corpus(name: &str) -> Value {
let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("../../testdata/evidence-request")
.join(name);
serde_json::from_slice(&std::fs::read(&path).unwrap_or_else(|e| panic!("{path:?}: {e}")))
.unwrap()
}
fn cases(corpus: &Value) -> &Vec<Value> {
corpus["cases"].as_array().unwrap()
}
#[test]
fn the_request_vectors_in_both_bindings() {
let corpus = corpus("request.json");
assert_eq!(cases(&corpus).len(), 33);
let mut cbor = 0;
for case in cases(&corpus) {
let id = case["id"].as_str().unwrap();
let expect = &case["expect"];
let mut bindings = vec![(
Binding::Json,
case["request_json"].as_str().unwrap().as_bytes().to_vec(),
case["request_json_digest"].as_str(),
)];
if let Some(h) = case["request_cbor_hex"].as_str().filter(|h| !h.is_empty()) {
bindings.push((
Binding::Cbor,
hex::decode(h).unwrap(),
case["request_cbor_digest"].as_str(),
));
cbor += 1;
}
for (binding, octets, digest) in bindings {
if let Some(d) = digest.filter(|d| !d.is_empty()) {
assert_eq!(
sha256_hex(&octets),
d,
"{id}: the digest is over the octets"
);
}
let got = read_request(&octets, binding);
if expect["well_formed"] == json!(true) {
assert!(got.is_ok(), "{id} {binding:?}: refused {:?}", got.err());
} else {
let (reason, _) = got
.err()
.unwrap_or_else(|| panic!("{id} {binding:?}: read"));
assert_eq!(reason.token(), expect["reason"], "{id} {binding:?}");
}
}
}
assert!(cbor > 0);
}
struct Vector {
log_size: u64,
anchors: Vec<AnchorFacts>,
records: Vec<String>,
correlation: BTreeMap<String, Vec<String>>,
citations: BTreeMap<String, Vec<String>>,
}
impl Vector {
fn positions(&self, digests: Option<&Vec<String>>) -> Vec<u64> {
digests
.into_iter()
.flatten()
.filter_map(|d| self.leaf_of(d))
.collect()
}
}
impl Evidence for Vector {
fn anchors(&self) -> &[AnchorFacts] {
&self.anchors
}
fn entries(&self) -> u64 {
self.log_size
}
fn leaf_of(&self, digest: &str) -> Option<u64> {
self.records
.iter()
.position(|r| r == digest)
.map(|i| i as u64)
}
fn servable(&self, leaf: u64) -> bool {
leaf < self.records.len() as u64
}
fn correlated(&self, id: &str) -> Vec<u64> {
self.positions(self.correlation.get(id))
}
fn citing(&self, half: &str) -> Vec<u64> {
self.positions(self.citations.get(half))
}
fn counterparty(&self, _: u64) -> Option<String> {
None
}
fn lapsed(&self, _: &Subject, _: UtcTime) -> bool {
false
}
}
fn strings(v: &Value) -> Vec<String> {
v.as_array()
.unwrap()
.iter()
.map(|s| s.as_str().unwrap().to_string())
.collect()
}
fn map_of(v: &Value) -> BTreeMap<String, Vec<String>> {
v.as_object()
.unwrap()
.iter()
.map(|(k, v)| (k.clone(), strings(v)))
.collect()
}
fn decide_for_vector(
view: &Vector,
request: &str,
now: UtcTime,
may_issue: bool,
uniform: bool,
) -> String {
let req = match read_request(request.as_bytes(), Binding::Json) {
Ok(req) => req,
Err((reason, _)) => return reason.token().to_string(),
};
let derivations = Derivations::new();
let share = SharePolicy::default();
let gate = Gate {
requester: Some("peer"),
relationship: Relationship::Identified,
share: &share,
derivations: &derivations,
standard_history: false,
uniform,
};
match decide(view, &req, &gate, &|_, _| true, now, may_issue) {
Decision::Refuse(reason) => reason.token().to_string(),
Decision::NeedAnchor => gate.disclose(Reason::CoverageUnsatisfiable).token().into(),
Decision::Serve { .. } => String::new(),
}
}
#[test]
fn the_resolution_vectors() {
let corpus = corpus("resolution.json");
let state = &corpus["responder"];
assert_eq!(
state["supported_derivations"],
json!({"history_card/1": ["full_history", "checkpoints"]}),
"the corpus's derivations differ from this responder's"
);
let view = Vector {
log_size: state["log_size"].as_u64().unwrap(),
anchors: state["anchors"]
.as_array()
.unwrap()
.iter()
.map(|a| AnchorFacts {
digest: a["digest"].as_str().unwrap().into(),
entries: a["size"].as_u64().unwrap(),
issued: parse_utc(a["issued_at"].as_str().unwrap()).unwrap(),
})
.collect(),
records: strings(&state["records"]),
correlation: map_of(&state["correlations"]),
citations: map_of(
state
.as_object()
.unwrap()
.iter()
.find(|(name, _)| name.ends_with("_citations"))
.map(|(_, v)| v)
.expect("the corpus declares the citing records"),
),
};
let now = parse_utc("2026-09-28T12:00:00Z").unwrap();
let may_issue = state["issues_new_commitments"] == json!(true);
let (mut ran, mut skipped) = (0, 0);
for case in cases(&corpus) {
let id = case["id"].as_str().unwrap();
let overrides = &case["responder_overrides"];
if overrides["positional_ordering"] == json!(false) {
skipped += 1;
continue;
}
let uniform = overrides["uniform_policy_declined"]
.as_bool()
.unwrap_or(state["uniform_policy_declined"] == json!(true));
let got = decide_for_vector(
&view,
case["request_json"].as_str().unwrap(),
now,
may_issue,
uniform,
);
let expect = &case["expect"];
let want = if expect["answer"] == "artifact" {
""
} else {
expect["reason"].as_str().unwrap()
};
assert_eq!(got, want, "{id}");
ran += 1;
}
assert_eq!((ran, skipped), (18, 1), "ran {ran} of 19 resolution cases");
}
#[test]
fn the_refusal_vectors() {
let corpus = corpus("refusal.json");
assert_eq!(cases(&corpus).len(), 21);
for case in cases(&corpus) {
let id = case["id"].as_str().unwrap();
let object: Value = match case["file"].as_str() {
Some(file) => serde_json::from_slice(
&std::fs::read(
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("../../testdata/evidence-request")
.join(file),
)
.unwrap(),
)
.unwrap(),
None => case["refusal"].clone(),
};
let check = evidence_request::refusal::check(&object);
let expect = &case["expect"];
assert_eq!(
check.signature_valid,
expect["signature"] == "valid",
"{id}: signature"
);
assert_eq!(
check.conformant,
expect["conformant"] == json!(true),
"{id}: conformant"
);
if let Some(registered) = expect["reason_registered"].as_bool() {
assert_eq!(check.reason_registered, registered, "{id}: reason");
}
}
}
}