use crate::answer::{self, DERIVATION_HISTORY_CARD, DERIVATION_HISTORY_CARD_2};
use crate::ask::Book;
use crate::canonical::jcs;
use crate::derivation::decode_strict;
use crate::respond::{respond, RespondOptions, Responder, ResponderPolicy, SharePolicy};
use crate::store::CheckpointedLog;
use cll::checkpoint::DecodedCheckpointCose;
use evidence_request::envelope::{parse_reply, Binding, Reply, PROFILE};
use evidence_request::request::{self, Coverage, Derivation, Subject};
use rand_core::{OsRng, RngCore};
use serde_json::json;
use serde_json::Value;
use sha2::{Digest, Sha256};
pub const DERIVATION_STANDARD_HISTORY: &str = "standard_history/1";
pub const DERIVATION_STANDARD_HISTORY_3: &str = "standard_history/3";
const CARD_MEMBERS: [&str; 14] = [
"anchor",
"bands",
"class_missing",
"controller_class",
"derivation",
"disputes",
"happened",
"holder_kind",
"in_window",
"outcomes",
"policy",
"roles",
"since",
"window",
];
const CARD_MEMBERS_3: [&str; 20] = [
"anchor",
"bands",
"class_missing",
"controller_class",
"coverage_start",
"derivation",
"disputes",
"happened",
"holder_kind",
"in_window",
"local_times",
"not_counted",
"not_honoured",
"outcomes",
"policy",
"remedied",
"roles",
"since",
"unpriced",
"window",
];
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StapleCheck {
pub derivation: String,
pub anchor: String,
pub nonce: String,
pub issued_at: String,
pub artifact: Vec<u8>,
pub card_form_checked: bool,
}
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
#[error("staple: {0}")]
pub struct StapleError(String);
fn refuse<T>(why: impl Into<String>) -> Result<T, StapleError> {
Err(StapleError(why.into()))
}
pub fn check_staple(
request: &[u8],
reply: &[u8],
holder: &str,
) -> Result<StapleCheck, StapleError> {
let req = match request::parse_json(request) {
Ok(req) => req,
Err(e) => return refuse(format!("the request is malformed: {e}")),
};
let derivation = match &req.derivation {
Some(Derivation::Token(t)) => t.as_str(),
_ => "",
};
let capped = matches!(
(derivation, &req.subject),
(DERIVATION_HISTORY_CARD, Subject::Checkpoints)
| (DERIVATION_HISTORY_CARD_2, Subject::Checkpoints)
| (DERIVATION_STANDARD_HISTORY, Subject::FullHistory)
| (DERIVATION_STANDARD_HISTORY_3, Subject::FullHistory)
);
if !capped {
return refuse(format!(
"a staple carries {DERIVATION_HISTORY_CARD} or {DERIVATION_HISTORY_CARD_2} over checkpoints or {DERIVATION_STANDARD_HISTORY} or {DERIVATION_STANDARD_HISTORY_3} over full_history, not {derivation:?}"
));
}
let (Coverage::ExpectedPin(pin), Some(nonce)) = (&req.coverage, &req.nonce) else {
return refuse("the request pins its anchor and carries a nonce");
};
if nonce.is_empty() {
return refuse("the request pins its anchor and carries a nonce");
}
let e = match parse_reply(reply, Binding::Json) {
Ok(Reply::Envelope(e)) => e,
Ok(Reply::Refusal(_)) => return refuse("the reply is a refusal"),
Err(e) => return refuse(format!("the reply: {e}")),
};
if let Err(err) = e.verify() {
return refuse(format!("the envelope: {err}"));
}
if e.responder != holder {
return refuse("the staple is not presented by its holder");
}
if e.request_digest != hex::encode(Sha256::digest(request)) {
return refuse("the envelope answers another request");
}
if e.derivation != req.derivation || e.subject != req.subject {
return refuse("the envelope signs another derivation or subject");
}
if &e.anchor.digest != pin {
return refuse("the envelope is as of another anchor");
}
let asked = decode_strict(request)
.ok()
.and_then(|v| v.get("profile").and_then(Value::as_str).map(str::to_owned))
.unwrap_or_else(|| PROFILE.to_owned());
if e.profile != asked {
return refuse("the envelope names another profile");
}
if derivation == DERIVATION_HISTORY_CARD {
history_card_form(&e.artifact, pin)?;
history_card_chain(&e.artifact)?;
}
if derivation == DERIVATION_HISTORY_CARD_2 {
check_history_card_2(&e.artifact, pin)?;
}
if derivation == DERIVATION_STANDARD_HISTORY || derivation == DERIVATION_STANDARD_HISTORY_3 {
let members_of: &[&str] = if derivation == DERIVATION_STANDARD_HISTORY_3 {
&CARD_MEMBERS_3
} else {
&CARD_MEMBERS
};
let card = match decode_strict(&e.artifact) {
Ok(card) => card,
Err(_) => return refuse("the stapled card is not JSON"),
};
let Some(members) = card.as_object() else {
return refuse("the stapled card is not an object");
};
let mut names: Vec<&str> = members.keys().map(String::as_str).collect();
names.sort_unstable();
if names != members_of || members["derivation"] != derivation {
return refuse("the stapled card is not the standard card's members");
}
}
Ok(StapleCheck {
derivation: derivation.to_owned(),
anchor: pin.clone(),
nonce: nonce.clone(),
issued_at: e.issued_at.clone(),
artifact: e.artifact.clone(),
card_form_checked: derivation != DERIVATION_STANDARD_HISTORY
&& derivation != DERIVATION_STANDARD_HISTORY_3,
})
}
fn history_card_form(artifact: &[u8], anchor: &str) -> Result<(), StapleError> {
let bad = |why: &str| StapleError(format!("the stapled history_card/1 {why}"));
let hex_text = |v: &Value| {
v.as_str().is_some_and(|s| {
!s.is_empty()
&& s.len() % 2 == 0
&& s.bytes().all(|c| matches!(c, b'0'..=b'9' | b'a'..=b'f'))
})
};
let card = decode_strict(artifact).map_err(|_| bad("is not a JSON object"))?;
let Some(members) = card.as_object() else {
return Err(bad("is not a JSON object"));
};
let mut names: Vec<&str> = members.keys().map(String::as_str).collect();
names.sort_unstable();
if names
!= [
"anchor",
"derivation",
"evidence_stream",
"history",
"subject",
]
{
return Err(bad("has members other than the card's"));
}
let stream_ok = members["evidence_stream"]
.as_str()
.is_some_and(|s| !s.is_empty());
if members["derivation"] != DERIVATION_HISTORY_CARD
|| members["anchor"] != anchor
|| !stream_ok
|| members["subject"] != serde_json::json!({"checkpoints": null})
{
return Err(bad(
"does not name its derivation, anchor, stream and subject",
));
}
let history = match members["history"].as_array() {
Some(h) if !h.is_empty() => h,
_ => return Err(bad("has no history")),
};
for (i, entry) in history.iter().enumerate() {
let Some(entry) = entry.as_object() else {
return Err(bad(&format!(
"entry {i} has members other than a checkpoint and its consistency proof"
)));
};
let mut names: Vec<&str> = entry.keys().map(String::as_str).collect();
names.sort_unstable();
if names != ["checkpoint", "consistency_from_previous"] {
return Err(bad(&format!(
"entry {i} has members other than a checkpoint and its consistency proof"
)));
}
let proof = &entry["consistency_from_previous"];
if !hex_text(&entry["checkpoint"])
|| proof.is_null() != (i == 0)
|| (i > 0 && !hex_text(proof))
{
return Err(bad(&format!(
"entry {i} is not a hex checkpoint with its consistency proof"
)));
}
}
let last = history[history.len() - 1]["checkpoint"]
.as_str()
.unwrap_or_default();
let raw = hex::decode(last).map_err(|_| bad("does not end at its anchor"))?;
if hex::encode(Sha256::digest(raw)) != anchor {
return Err(bad("does not end at its anchor"));
}
Ok(())
}
fn history_card_chain(artifact: &[u8]) -> Result<(), StapleError> {
let bad = |i: usize, why: &str| {
StapleError(format!(
"the stapled history_card/1's checkpoints are not one chain: entry {i} {why}"
))
};
let card = decode_strict(artifact).map_err(|_| bad(0, "is unreadable"))?;
let history = card["history"].as_array().map_or(&[][..], Vec::as_slice);
let mut previous: Option<DecodedCheckpointCose> = None;
let mut key = String::new();
for (i, entry) in history.iter().enumerate() {
let statement = hex::decode(entry["checkpoint"].as_str().unwrap_or_default())
.map_err(|_| bad(i, "is not hex"))?;
if !crate::ed25519::statement_verifies(&statement) {
return Err(bad(i, "has a checkpoint that does not verify"));
}
let verified = cll::checkpoint::verify_checkpoint_cose_offline(&statement);
let cp = match verified.decoded {
Some(cp) if verified.ok => cp,
_ => return Err(bad(i, "has a checkpoint that does not verify")),
};
if i == 0 {
key = cp.key_id.clone();
} else if cp.key_id != key {
return Err(bad(i, "is signed by another key than the first checkpoint"));
}
if let Some(prev) = &previous {
if cp.log_id != prev.log_id || cp.mmr_size <= prev.mmr_size {
return Err(bad(i, "does not extend the log"));
}
if cp.prev_size != prev.mmr_size || cp.prev_root != prev.root {
return Err(bad(
i,
"has a signed prev_size and prev_root that are not the previous checkpoint's",
));
}
let proof = hex::decode(
entry["consistency_from_previous"]
.as_str()
.unwrap_or_default(),
)
.map_err(|_| bad(i, "has a consistency proof that is not hex"))?;
if !consistency_holds(prev, &cp, &proof) {
return Err(bad(i, "has a consistency proof that does not verify"));
}
}
previous = Some(cp);
}
Ok(())
}
pub fn check_history_card_2(artifact: &[u8], anchor: &str) -> Result<(), StapleError> {
let bad = |why: &str| StapleError(format!("the history_card/2 {why}"));
let card = decode_strict(artifact).map_err(|_| bad("is not a JSON object"))?;
let Some(members) = card.as_object() else {
return Err(bad("is not a JSON object"));
};
let mut names: Vec<&str> = members.keys().map(String::as_str).collect();
names.sort_unstable();
if names
!= [
"anchor",
"derivation",
"evidence_stream",
"history",
"subject",
"window",
]
{
return Err(bad("has members other than the card's"));
}
let stream_ok = members["evidence_stream"]
.as_str()
.is_some_and(|s| !s.is_empty());
let subject_ok = members["subject"] == serde_json::json!({"checkpoints": null})
|| members["subject"] == serde_json::json!({"full_history": null});
if members["derivation"] != DERIVATION_HISTORY_CARD_2
|| members["anchor"] != anchor
|| !stream_ok
|| !subject_ok
{
return Err(bad(
"does not name its derivation, anchor, stream and subject",
));
}
for (i, entry) in members["history"]
.as_array()
.map_or(&[][..], Vec::as_slice)
.iter()
.enumerate()
{
let mut names: Vec<&str> = entry
.as_object()
.map_or(Vec::new(), |m| m.keys().map(String::as_str).collect());
names.sort_unstable();
if names
!= [
"checkpoint",
"consistency_from_previous",
"position",
"receipts",
]
{
return Err(bad(&format!(
"entry {i} has members other than a position, checkpoint, receipts and consistency proof"
)));
}
}
let first_key = members["history"][0]["checkpoint"]
.as_str()
.and_then(|h| hex::decode(h).ok())
.and_then(|raw| {
let verified = cll::checkpoint::verify_checkpoint_cose_offline(&raw);
verified.decoded.map(|cp| cp.key_id)
})
.unwrap_or_default();
match evidence_request::cll_material::check_history_card_2(&card, anchor, &[first_key]) {
None => Ok(()),
Some(finding) => Err(bad(&format!("fails {finding}"))),
}
}
fn consistency_holds(
prev: &DecodedCheckpointCose,
next: &DecodedCheckpointCose,
proof: &[u8],
) -> bool {
use ciborium::value::Value as Cbor;
let mut rest = proof;
let Ok(Cbor::Array(parts)) = ciborium::from_reader::<Cbor, _>(&mut rest) else {
return false;
};
if !rest.is_empty() {
return false;
}
let hashes = |v: &Cbor| -> Option<Vec<Vec<u8>>> {
match v {
Cbor::Array(items) => items
.iter()
.map(|i| match i {
Cbor::Bytes(b) => Some(b.clone()),
_ => None,
})
.collect(),
_ => None,
}
};
let size = |v: &Cbor| match v {
Cbor::Integer(n) => u64::try_from(*n).ok(),
_ => None,
};
let [size1, size2, paths, right] = parts.as_slice() else {
return false;
};
let (Some(size1), Some(size2), Some(right), Cbor::Array(paths)) =
(size(size1), size(size2), hashes(right), paths)
else {
return false;
};
if size1 != prev.mmr_size || size2 != next.mmr_size {
return false;
}
let new_peaks = &next.new_peak_hashes;
if right.len() > new_peaks.len()
|| !new_peaks[new_peaks.len() - right.len()..]
.iter()
.zip(&right)
.all(|(a, b)| a.as_slice() == b.as_slice())
{
return false;
}
let Some(witness) = paths
.iter()
.map(|p| hashes(p).map(|h| h.iter().map(hex::encode).collect::<Vec<_>>()))
.collect::<Option<Vec<_>>>()
else {
return false;
};
let (Ok(old_root), Ok(new_root)) = (hex_hash(&prev.root), hex_hash(&next.root)) else {
return false;
};
let proof = cll::mmr::ConsistencyProof {
v: 1,
kind: "consistency".to_owned(),
size_a: size1,
size_b: size2,
old_peaks: prev.new_peak_hashes.iter().map(hex::encode).collect(),
witness,
new_peaks: new_peaks.iter().map(hex::encode).collect(),
};
cll::mmr::verify_consistency(&old_root, size1, &new_root, size2, &proof)
}
fn hex_hash(s: &str) -> Result<cll::mmr::Hash, ()> {
hex::decode(s).map_err(|_| ())?.try_into().map_err(|_| ())
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Staple {
pub request: Vec<u8>,
pub reply: Vec<u8>,
}
pub fn staple_history_card<B: Book + CheckpointedLog>(
book: &mut B,
responder: &Responder<'_>,
) -> Result<Staple, StapleError> {
staple_of(book, responder, DERIVATION_HISTORY_CARD)
}
pub fn staple_history_card_2<B: Book + CheckpointedLog>(
book: &mut B,
responder: &Responder<'_>,
) -> Result<Staple, StapleError> {
staple_of(book, responder, DERIVATION_HISTORY_CARD_2)
}
pub fn staple_standard_history<B: Book + CheckpointedLog>(
book: &mut B,
responder: &Responder<'_>,
) -> Result<Staple, StapleError> {
staple_of(book, responder, DERIVATION_STANDARD_HISTORY)
}
fn staple_of<B: Book + CheckpointedLog>(
book: &mut B,
responder: &Responder<'_>,
derivation: &str,
) -> Result<Staple, StapleError> {
let fail = |e: &dyn std::fmt::Display| StapleError(e.to_string());
let covered = answer::anchors(book)
.map_err(|e| fail(&e))?
.last()
.map(|a| a.size);
let leaves = book.leaf_count().map_err(|e| fail(&e))?;
if covered != Some(leaves) {
book.checkpoint().map_err(|e| fail(&e))?;
}
let Some(newest) = book.stated_checkpoints().map_err(|e| fail(&e))?.pop() else {
return refuse("the book has no checkpoint to staple");
};
let mut nonce = [0u8; 16];
OsRng.fill_bytes(&mut nonce);
let subject = if derivation == DERIVATION_STANDARD_HISTORY {
json!({"full_history": null})
} else {
json!({"checkpoints": null})
};
let request = jcs(&json!({
"coverage": {"expected_pin": answer::anchor_digest(&newest)},
"derivation": derivation,
"nonce": hex::encode(nonce),
"profile": PROFILE,
"subject": subject,
}))
.map_err(|e| fail(&e))?;
let holder = hex::encode(responder.signer.verifying_key().to_bytes());
let opts = RespondOptions {
authenticated_requester: (derivation == DERIVATION_STANDARD_HISTORY).then_some(&holder),
policy: SharePolicy::default(),
};
let own = ResponderPolicy {
refusal_policy: responder.policy.refusal_policy,
limiter: None,
max_request_bytes: responder.policy.max_request_bytes,
max_answer_items: responder.policy.max_answer_items,
history_window: responder.policy.history_window,
};
let responder = Responder {
signer: responder.signer,
derivations: responder.derivations,
policy: &own,
standard_history: responder.standard_history,
};
let (reply, _) =
respond(book, &responder, &request, Binding::Json, &opts).map_err(|e| fail(&e))?;
if !matches!(parse_reply(&reply, Binding::Json), Ok(Reply::Envelope(_))) {
return refuse(format!("the book refused its own {derivation} request"));
}
Ok(Staple { request, reply })
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(serde::Deserialize)]
struct Vector {
name: String,
holder: String,
request: String,
reply: String,
pass: bool,
#[serde(default)]
members_only: bool,
#[serde(default)]
nonce: String,
#[serde(default)]
anchor: String,
}
#[test]
fn agrees_with_the_go_vectors() {
let path = concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../testdata/staple/staples.json"
);
let vectors: Vec<Vector> =
serde_json::from_slice(&std::fs::read(path).expect("vectors")).expect("parse");
assert!(vectors.len() >= 2);
for v in vectors {
let got = check_staple(v.request.as_bytes(), v.reply.as_bytes(), &v.holder);
assert_eq!(got.is_ok(), v.pass, "{}: {got:?}", v.name);
if let Ok(c) = got {
let standard = c.derivation == DERIVATION_STANDARD_HISTORY;
assert_eq!(c.card_form_checked, !standard, "{}", v.name);
assert_eq!((c.nonce, c.anchor), (v.nonce, v.anchor), "{}", v.name);
}
}
}
#[test]
fn agrees_with_the_go_history_card_2_vectors() {
let dir = concat!(env!("CARGO_MANIFEST_DIR"), "/../../testdata/history-card-2");
let vectors: Vec<Vector> =
serde_json::from_slice(&std::fs::read(format!("{dir}/staples.json")).unwrap()).unwrap();
assert!(vectors.len() >= 10);
for v in vectors {
let got = check_staple(v.request.as_bytes(), v.reply.as_bytes(), &v.holder);
assert_eq!(got.is_ok(), v.pass, "{}: {got:?}", v.name);
if let Ok(c) = got {
assert_eq!((c.nonce, c.anchor), (v.nonce, v.anchor), "{}", v.name);
}
}
}
#[test]
fn agrees_with_the_go_standard_history_3_vectors() {
let path = concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../testdata/staple-3/staples.json"
);
let vectors: Vec<Vector> =
serde_json::from_slice(&std::fs::read(path).expect("vectors")).expect("parse");
assert!(vectors.len() >= 6);
for v in vectors {
let got = check_staple(v.request.as_bytes(), v.reply.as_bytes(), &v.holder);
assert_eq!(got.is_ok(), v.pass || v.members_only, "{}: {got:?}", v.name);
if let Ok(c) = got {
assert_eq!(
(c.derivation.as_str(), c.nonce, c.anchor),
(DERIVATION_STANDARD_HISTORY_3, v.nonce, v.anchor),
"{}",
v.name
);
assert!(!c.card_form_checked, "{}", v.name);
}
}
}
#[test]
fn card_members_are_sorted() {
let mut sorted = CARD_MEMBERS;
sorted.sort_unstable();
assert_eq!(sorted, CARD_MEMBERS);
let mut sorted = CARD_MEMBERS_3;
sorted.sort_unstable();
assert_eq!(sorted, CARD_MEMBERS_3);
}
}