use std::fmt;
use std::panic::{catch_unwind, AssertUnwindSafe};
use super::checkpoint_ack::V2CheckpointAcknowledgement;
use super::claim_store::{V2AuthoritativeClock, V2ChallengeClaim, V2StoreError};
use super::context::V2Context;
use super::crypto::{key_id_v2, lower_hex, sha384, verify_v2_statement, V2ObjectType};
use super::errors::{err, V2Error, V2ErrorClass, V2Result};
use super::limits::{valid_v2_timestamp, V2_MAX_TIMESTAMP_SECONDS};
use super::receipt::{
decode_verification_receipt_v2, verification_receipt_v2_body, verification_receipt_v2_digest,
verification_receipt_v2_signable_bytes, VerificationReceiptV2,
};
use crate::types::HybridPublicKey;
pub struct CommittedV2Outcome {
claim_id: String,
verifier_id: String,
receipt_body: Vec<u8>,
challenge_expires_at: i64,
allow_horizon: i64,
}
impl fmt::Debug for CommittedV2Outcome {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("CommittedV2Outcome")
.field("claim_id", &self.claim_id)
.field("receipt_body_digest", &self.receipt_body_digest())
.finish_non_exhaustive()
}
}
impl CommittedV2Outcome {
pub(crate) fn new(claim: &V2ChallengeClaim, body: &[u8], allow_horizon: i64) -> Self {
CommittedV2Outcome {
claim_id: claim.claim_id.clone(),
verifier_id: claim.verifier_id.clone(),
receipt_body: body.to_vec(),
challenge_expires_at: claim.expires_at,
allow_horizon,
}
}
pub fn claim_id(&self) -> String {
self.claim_id.clone()
}
pub fn receipt_body(&self) -> Vec<u8> {
self.receipt_body.clone()
}
pub fn receipt_body_digest(&self) -> String {
receipt_outbox_digest_v2(&self.receipt_body)
}
pub fn challenge_expires_at(&self) -> i64 {
self.challenge_expires_at
}
pub fn allow_horizon(&self) -> Option<i64> {
(self.allow_horizon > 0).then_some(self.allow_horizon)
}
}
pub fn receipt_outbox_digest_v2(body: &[u8]) -> String {
format!(
"sha384:{}",
hex::encode(sha384(&[b"ratify-protocol-receipt-outbox-v2", &[0], body]))
)
}
pub trait V2ReceiptPublisher: Send + Sync {
fn publish_v2_receipt(&self, ctx: &V2Context, claim_id: &str, receipt_body: &[u8]) -> Result<Vec<u8>, V2StoreError>;
}
pub trait V2ReceiptCheckpoint: Send + Sync {
fn acknowledge_v2_receipt(
&self,
ctx: &V2Context,
log_id: &str,
sequence: i64,
previous_entry_hash: &[u8],
entry_hash: &[u8],
) -> Result<V2CheckpointAcknowledgement, V2StoreError>;
fn get_v2_acknowledgement(
&self,
ctx: &V2Context,
log_id: &str,
sequence: i64,
) -> Result<V2CheckpointAcknowledgement, V2StoreError>;
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct V2ReleaseRecord {
pub claim_id: String,
pub entry_hash: Vec<u8>,
pub ack_timestamp: i64,
pub outcome: V2ReleaseStatus,
pub reason: String,
}
pub fn valid_v2_release_record_outcome(outcome: V2ReleaseStatus, reason: &str) -> bool {
match outcome {
V2ReleaseStatus::Released => reason.is_empty(),
V2ReleaseStatus::Withheld => {
matches!(reason, "clock_regressed" | "challenge_expired" | "allow_horizon_passed")
}
_ => false,
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct V2TerminalClaimRecord {
pub terminal: bool,
pub receipt_outbox_digest: String,
pub challenge_expires_at: i64,
pub allow_horizon: i64,
pub finalized_at: i64,
pub receipt_abandoned: bool,
pub release: Option<V2ReleaseRecord>,
}
pub trait V2ReleaseClaimStore: V2AuthoritativeClock {
fn load_v2_terminal_claim(&self, ctx: &V2Context, claim_id: &str) -> Result<V2TerminalClaimRecord, V2StoreError>;
fn record_v2_release(&self, ctx: &V2Context, record: V2ReleaseRecord) -> Result<(), V2StoreError>;
}
#[derive(Clone, Copy)]
pub struct V2ReleaseConfig<'a> {
pub verifier_public_key: &'a HybridPublicKey,
pub log_id: &'a str,
pub claim_store: &'a dyn V2ReleaseClaimStore,
pub checkpoint: &'a dyn V2ReceiptCheckpoint,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum V2ReleaseStatus {
Released,
Pending,
Withheld,
Rejected,
}
impl V2ReleaseStatus {
pub fn as_str(self) -> &'static str {
match self {
V2ReleaseStatus::Released => "released",
V2ReleaseStatus::Pending => "pending",
V2ReleaseStatus::Withheld => "withheld",
V2ReleaseStatus::Rejected => "rejected",
}
}
}
pub struct V2ReleasedDecision {
claim_id: String,
decision: String,
reason: String,
identity_status: String,
granted_scope: Vec<String>,
receipt_wire: Vec<u8>,
release_time: i64,
challenge_expires_at: i64,
allow_horizon: i64,
}
impl fmt::Debug for V2ReleasedDecision {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("V2ReleasedDecision")
.field("claim_id", &self.claim_id)
.field("decision", &self.decision)
.field("reason", &self.reason)
.finish_non_exhaustive()
}
}
impl V2ReleasedDecision {
pub fn claim_id(&self) -> String {
self.claim_id.clone()
}
pub fn decision(&self) -> String {
self.decision.clone()
}
pub fn reason(&self) -> String {
self.reason.clone()
}
pub fn identity_status(&self) -> String {
self.identity_status.clone()
}
pub fn granted_scope(&self) -> Vec<String> {
self.granted_scope.clone()
}
pub fn receipt_wire(&self) -> Vec<u8> {
self.receipt_wire.clone()
}
pub fn receipt(&self) -> V2Result<VerificationReceiptV2> {
if self.receipt_wire.is_empty() {
return err(V2ErrorClass::Malformed, "v2 released decision carries no receipt");
}
decode_verification_receipt_v2(&self.receipt_wire)
}
pub fn release_time(&self) -> i64 {
self.release_time
}
pub fn challenge_expires_at(&self) -> i64 {
self.challenge_expires_at
}
pub fn allow_horizon(&self) -> Option<i64> {
(self.allow_horizon > 0).then_some(self.allow_horizon)
}
pub fn allowed(&self, ctx: &V2Context, clock: &dyn V2AuthoritativeClock) -> bool {
if self.decision != "allow" || self.receipt_wire.is_empty() || self.allow_horizon <= 0 {
return false;
}
match read_v2_authoritative_time(ctx, clock) {
Ok(now) => now < self.challenge_expires_at && now < self.allow_horizon,
Err(_) => false,
}
}
}
#[derive(Debug)]
pub struct V2ReleaseResult {
pub status: V2ReleaseStatus,
pub reason: String,
decision: Option<V2ReleasedDecision>,
}
impl V2ReleaseResult {
pub fn decision(&self) -> Option<&V2ReleasedDecision> {
self.decision.as_ref()
}
pub fn into_decision(self) -> Option<V2ReleasedDecision> {
self.decision
}
}
fn release_result_v2(status: V2ReleaseStatus, reason: &str) -> V2ReleaseResult {
V2ReleaseResult {
status,
reason: reason.into(),
decision: None,
}
}
pub fn release_v2_decision(
ctx: &V2Context,
committed: &CommittedV2Outcome,
signed_receipt: Option<&[u8]>,
config: V2ReleaseConfig<'_>,
) -> V2ReleaseResult {
use V2ReleaseStatus::*;
if committed.claim_id.is_empty() || committed.receipt_body.is_empty() {
return release_result_v2(Rejected, "release_state_mismatch");
}
if config.log_id.len() != 32 || !lower_hex(config.log_id) {
return release_result_v2(Rejected, "release_state_mismatch");
}
let record = match catch_unwind(AssertUnwindSafe(|| {
config.claim_store.load_v2_terminal_claim(ctx, &committed.claim_id)
})) {
Ok(Ok(r)) => r,
Ok(Err(e)) if e.class() == Some(V2ErrorClass::ClaimNotFound) => {
return release_result_v2(Rejected, "release_state_mismatch")
}
_ => return release_result_v2(Pending, "claim_store_unavailable"),
};
if record.receipt_abandoned {
return release_result_v2(Withheld, "receipt_abandoned");
}
let verifier_id = key_id_v2(config.verifier_public_key);
if !record.terminal
|| record.receipt_outbox_digest != committed.receipt_body_digest()
|| record.challenge_expires_at != committed.challenge_expires_at
|| record.allow_horizon != committed.allow_horizon
|| verifier_id.as_deref().ok() != Some(committed.verifier_id.as_str())
{
return release_result_v2(Rejected, "release_state_mismatch");
}
if let Some(release) = &record.release {
if release.claim_id != committed.claim_id || !valid_v2_release_record_outcome(release.outcome, &release.reason) {
return release_result_v2(Rejected, "release_state_mismatch");
}
if release.outcome == Withheld {
return release_result_v2(Withheld, &release.reason);
}
}
let Some(signed_receipt) = signed_receipt.filter(|r| !r.is_empty()) else {
return release_result_v2(Pending, "receipt_not_appended");
};
let receipt = match verify_published_v2_receipt(signed_receipt, config) {
Ok(r) if r.verifier_id == committed.verifier_id => r,
_ => return release_result_v2(Rejected, "receipt_invalid"),
};
match verification_receipt_v2_body(&receipt) {
Ok(body) if body == committed.receipt_body => {}
_ => return release_result_v2(Rejected, "receipt_body_mismatch"),
}
let Ok(entry_hash) = verification_receipt_v2_digest(&receipt) else {
return release_result_v2(Rejected, "receipt_invalid");
};
if record.release.as_ref().is_some_and(|r| r.entry_hash != entry_hash) {
return release_result_v2(Rejected, "release_state_mismatch");
}
if receipt.sequence > 1 {
let previous = match get_v2_acknowledgement_safely(ctx, config.checkpoint, &receipt.log_id, receipt.sequence - 1) {
Ok(a) => a,
Err(_) => return release_result_v2(Pending, "acknowledgement_unavailable"),
};
if previous.log_id != receipt.log_id
|| previous.sequence != receipt.sequence - 1
|| previous.entry_hash != receipt.previous_receipt_hash
{
return release_result_v2(Rejected, "log_predecessor_mismatch");
}
}
let ack = match get_v2_acknowledgement_safely(ctx, config.checkpoint, &receipt.log_id, receipt.sequence) {
Ok(a) => a,
Err(_) => return release_result_v2(Pending, "acknowledgement_unavailable"),
};
if ack.log_id != receipt.log_id || ack.sequence != receipt.sequence || ack.entry_hash != entry_hash {
return release_result_v2(Rejected, "acknowledgement_mismatch");
}
if record.release.as_ref().is_some_and(|r| r.ack_timestamp != ack.timestamp) {
return release_result_v2(Rejected, "release_state_mismatch");
}
let withhold = |reason: &str| -> V2ReleaseResult {
if record.release.is_none() {
let withheld = V2ReleaseRecord {
claim_id: committed.claim_id.clone(),
entry_hash: entry_hash.clone(),
ack_timestamp: ack.timestamp,
outcome: Withheld,
reason: reason.into(),
};
if let Err(V2StoreError::ReleaseStateMismatch) = record_v2_release_safely(ctx, config.claim_store, withheld) {
return release_result_v2(Rejected, "release_state_mismatch");
}
}
release_result_v2(Withheld, reason)
};
let now = match read_v2_authoritative_time(ctx, config.claim_store) {
Ok(now) => now,
Err(e) if e.class == V2ErrorClass::ClockRegressed && e.is_classified() => return withhold("clock_regressed"),
Err(_) => return release_result_v2(Pending, "clock_unavailable"),
};
if !valid_v2_timestamp(record.finalized_at)
|| !valid_v2_timestamp(ack.timestamp)
|| record.finalized_at > ack.timestamp
|| ack.timestamp > now
{
return withhold("clock_regressed");
}
if ack.timestamp >= committed.challenge_expires_at || now >= committed.challenge_expires_at {
return withhold("challenge_expired");
}
if receipt.decision == "allow"
&& (committed.allow_horizon <= 0 || ack.timestamp >= committed.allow_horizon || now >= committed.allow_horizon)
{
return withhold("allow_horizon_passed");
}
if record.release.is_none() {
let new_record = V2ReleaseRecord {
claim_id: committed.claim_id.clone(),
entry_hash: entry_hash.clone(),
ack_timestamp: ack.timestamp,
outcome: Released,
reason: String::new(),
};
match record_v2_release_safely(ctx, config.claim_store, new_record) {
Ok(()) => {}
Err(V2StoreError::ReleaseStateMismatch) => return release_result_v2(Rejected, "release_state_mismatch"),
Err(_) => return release_result_v2(Pending, "claim_store_unavailable"),
}
}
let allow = receipt.decision == "allow";
V2ReleaseResult {
status: Released,
reason: String::new(),
decision: Some(V2ReleasedDecision {
claim_id: committed.claim_id.clone(),
decision: receipt.decision.clone(),
reason: receipt.decision_reason.clone(),
identity_status: receipt.identity_status.clone(),
granted_scope: receipt.granted_scope.clone(),
receipt_wire: signed_receipt.to_vec(),
release_time: ack.timestamp,
challenge_expires_at: committed.challenge_expires_at,
allow_horizon: if allow { committed.allow_horizon } else { 0 },
}),
}
}
fn verify_published_v2_receipt(wire: &[u8], config: V2ReleaseConfig<'_>) -> V2Result<VerificationReceiptV2> {
let receipt = decode_verification_receipt_v2(wire)?;
if receipt.log_id != config.log_id {
return err(V2ErrorClass::LogStateMismatch, "v2 published receipt belongs to an unconfigured log");
}
let body = verification_receipt_v2_signable_bytes(&receipt)?;
verify_v2_statement(
V2ObjectType::VerificationReceipt,
&body,
&receipt.signature,
config.verifier_public_key,
)?;
Ok(receipt)
}
fn record_v2_release_safely(
ctx: &V2Context,
store: &dyn V2ReleaseClaimStore,
record: V2ReleaseRecord,
) -> Result<(), V2StoreError> {
catch_unwind(AssertUnwindSafe(|| store.record_v2_release(ctx, record)))
.unwrap_or_else(|_| Err(V2StoreError::Unavailable("claim store panicked".into())))
}
fn get_v2_acknowledgement_safely(
ctx: &V2Context,
checkpoint: &dyn V2ReceiptCheckpoint,
log_id: &str,
sequence: i64,
) -> Result<V2CheckpointAcknowledgement, V2StoreError> {
catch_unwind(AssertUnwindSafe(|| checkpoint.get_v2_acknowledgement(ctx, log_id, sequence)))
.unwrap_or_else(|_| Err(V2StoreError::Unavailable("checkpoint panicked".into())))
}
pub(crate) fn read_v2_authoritative_time(ctx: &V2Context, clock: &dyn V2AuthoritativeClock) -> V2Result<i64> {
let now = match catch_unwind(AssertUnwindSafe(|| clock.authoritative_time_v2(ctx))) {
Ok(Ok(now)) => now,
Ok(Err(e)) => return Err(e.into_v2()),
Err(_) => return Err(V2Error::plain("v2 authoritative clock panicked")),
};
if !valid_v2_timestamp(now) {
return Err(V2Error::plain(format!(
"v2 authoritative clock returned {now} outside 0..{V2_MAX_TIMESTAMP_SECONDS}"
)));
}
Ok(now)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::crypto::generate_hybrid_keypair;
use crate::v2::reference::Store;
#[test]
fn forged_zero_value_outcome_is_rejected() {
let (public, private) = generate_hybrid_keypair();
let log_id = "dddddddddddddddddddddddddddddd01";
let store = Store::new(1_800_000_000, 30, log_id, &private).unwrap();
let forged = CommittedV2Outcome {
claim_id: String::new(),
verifier_id: String::new(),
receipt_body: Vec::new(),
challenge_expires_at: 0,
allow_horizon: 0,
};
let result = release_v2_decision(
&V2Context::background(),
&forged,
None,
V2ReleaseConfig {
verifier_public_key: &public,
log_id,
claim_store: &store,
checkpoint: &store,
},
);
assert_eq!(
(result.status, result.reason.as_str()),
(V2ReleaseStatus::Rejected, "release_state_mismatch")
);
assert!(result.decision().is_none());
}
}