use std::{error::Error as StdError, fmt, sync::Arc};
use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize, de};
use thiserror::Error;
use crate::{
AttemptId, AuthorizationReceiptId, BoxFuture, CapabilityIdentity, Digest, EventId,
InvocationId, RunId, SkillActingWindowId, TenantId, ThreadId, Timestamp, ToolDescriptor,
ToolInput,
};
const RECEIPT_DIGEST_DOMAIN: &[u8] = b"stateknot.tool-authorization-receipt.v1\0";
const WINDOW_RECEIPT_DIGEST_DOMAIN: &[u8] = b"stateknot.tool-authorization-receipt.v2\0";
const DESCRIPTOR_DIGEST_DOMAIN: &[u8] = b"stateknot.tool-authorization-descriptor.v1\0";
const INPUT_DIGEST_DOMAIN: &[u8] = b"stateknot.tool-authorization-input.v1\0";
#[derive(Clone, Copy, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ToolAuthorizationOperation {
Execute,
Reconcile,
}
#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
#[allow(
clippy::struct_field_names,
reason = "explicit ID suffixes keep every durable provenance boundary unambiguous"
)]
pub struct ToolAuthorizationProvenance {
tenant_id: TenantId,
run_id: RunId,
thread_id: ThreadId,
invocation_id: InvocationId,
attempt_id: AttemptId,
origin_event_id: EventId,
}
impl ToolAuthorizationProvenance {
#[must_use]
pub const fn new(
tenant_id: TenantId,
run_id: RunId,
thread_id: ThreadId,
invocation_id: InvocationId,
attempt_id: AttemptId,
origin_event_id: EventId,
) -> Self {
Self {
tenant_id,
run_id,
thread_id,
invocation_id,
attempt_id,
origin_event_id,
}
}
#[must_use]
pub const fn tenant_id(&self) -> &TenantId {
&self.tenant_id
}
#[must_use]
pub const fn run_id(&self) -> RunId {
self.run_id
}
#[must_use]
pub const fn thread_id(&self) -> ThreadId {
self.thread_id
}
#[must_use]
pub const fn invocation_id(&self) -> InvocationId {
self.invocation_id
}
#[must_use]
pub const fn attempt_id(&self) -> AttemptId {
self.attempt_id
}
#[must_use]
pub const fn origin_event_id(&self) -> EventId {
self.origin_event_id
}
}
#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ToolAuthorizationReceipt {
receipt_id: AuthorizationReceiptId,
provenance: ToolAuthorizationProvenance,
operation: ToolAuthorizationOperation,
tool: CapabilityIdentity,
descriptor_digest: Digest,
input_digest: Digest,
subject_digest: Digest,
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
#[serde(skip_serializing_if = "Option::is_none")]
authorization_window_id: Option<SkillActingWindowId>,
authorized_at: Timestamp,
has_recovery_handle: bool,
receipt_digest: Digest,
}
impl ToolAuthorizationReceipt {
pub fn digest_descriptor(
descriptor: &ToolDescriptor,
) -> Result<Digest, ToolAuthorizationReceiptError> {
digest_canonical(DESCRIPTOR_DIGEST_DOMAIN, descriptor)
}
pub fn digest_input(input: &ToolInput) -> Result<Digest, ToolAuthorizationReceiptError> {
digest_canonical(INPUT_DIGEST_DOMAIN, input)
}
#[allow(clippy::too_many_arguments)]
pub fn new(
receipt_id: AuthorizationReceiptId,
provenance: ToolAuthorizationProvenance,
operation: ToolAuthorizationOperation,
tool: CapabilityIdentity,
descriptor_digest: Digest,
input_digest: Digest,
subject_digest: Digest,
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
authorized_at: Timestamp,
has_recovery_handle: bool,
) -> Result<Self, ToolAuthorizationReceiptError> {
let mut receipt = Self {
receipt_id,
provenance,
operation,
tool,
descriptor_digest,
input_digest,
subject_digest,
policy,
policy_digest,
decision_digest,
authorization_window_id: None,
authorized_at,
has_recovery_handle,
receipt_digest: Digest::sha256(b""),
};
receipt.receipt_digest = receipt.compute_digest()?;
Ok(receipt)
}
#[must_use]
pub const fn receipt_id(&self) -> AuthorizationReceiptId {
self.receipt_id
}
#[must_use]
pub const fn provenance(&self) -> &ToolAuthorizationProvenance {
&self.provenance
}
#[must_use]
pub const fn operation(&self) -> ToolAuthorizationOperation {
self.operation
}
#[must_use]
pub const fn tool(&self) -> &CapabilityIdentity {
&self.tool
}
#[must_use]
pub const fn descriptor_digest(&self) -> Digest {
self.descriptor_digest
}
#[must_use]
pub const fn input_digest(&self) -> Digest {
self.input_digest
}
#[must_use]
pub const fn subject_digest(&self) -> Digest {
self.subject_digest
}
#[must_use]
pub const fn policy(&self) -> &CapabilityIdentity {
&self.policy
}
#[must_use]
pub const fn policy_digest(&self) -> Digest {
self.policy_digest
}
#[must_use]
pub const fn decision_digest(&self) -> Digest {
self.decision_digest
}
pub fn with_authorization_window(
mut self,
window_id: SkillActingWindowId,
) -> Result<Self, ToolAuthorizationReceiptError> {
self.authorization_window_id = Some(window_id);
self.receipt_digest = self.compute_digest()?;
Ok(self)
}
#[must_use]
pub const fn authorization_window_id(&self) -> Option<SkillActingWindowId> {
self.authorization_window_id
}
#[must_use]
pub const fn authorized_at(&self) -> Timestamp {
self.authorized_at
}
#[must_use]
pub const fn has_recovery_handle(&self) -> bool {
self.has_recovery_handle
}
#[must_use]
pub const fn receipt_digest(&self) -> Digest {
self.receipt_digest
}
fn compute_digest(&self) -> Result<Digest, ToolAuthorizationReceiptError> {
#[derive(Serialize)]
struct LegacyPreimage<'a> {
receipt_id: AuthorizationReceiptId,
provenance: &'a ToolAuthorizationProvenance,
operation: ToolAuthorizationOperation,
tool: &'a CapabilityIdentity,
descriptor_digest: Digest,
input_digest: Digest,
subject_digest: Digest,
policy: &'a CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
authorized_at: Timestamp,
has_recovery_handle: bool,
}
#[derive(Serialize)]
struct WindowPreimage<'a> {
#[serde(flatten)]
legacy: LegacyPreimage<'a>,
authorization_window_id: SkillActingWindowId,
}
let legacy = LegacyPreimage {
receipt_id: self.receipt_id,
provenance: &self.provenance,
operation: self.operation,
tool: &self.tool,
descriptor_digest: self.descriptor_digest,
input_digest: self.input_digest,
subject_digest: self.subject_digest,
policy: &self.policy,
policy_digest: self.policy_digest,
decision_digest: self.decision_digest,
authorized_at: self.authorized_at,
has_recovery_handle: self.has_recovery_handle,
};
let Some(authorization_window_id) = self.authorization_window_id else {
return digest_canonical(RECEIPT_DIGEST_DOMAIN, &legacy);
};
digest_canonical(
WINDOW_RECEIPT_DIGEST_DOMAIN,
&WindowPreimage {
legacy,
authorization_window_id,
},
)
}
}
fn digest_canonical<T: Serialize>(
domain: &[u8],
value: &T,
) -> Result<Digest, ToolAuthorizationReceiptError> {
let canonical = serde_json_canonicalizer::to_vec(value)
.map_err(|_| ToolAuthorizationReceiptError::Encoding)?;
let mut bytes = Vec::with_capacity(domain.len() + 8 + canonical.len());
bytes.extend_from_slice(domain);
bytes.extend_from_slice(
&u64::try_from(canonical.len())
.expect("canonical authorization binding length fits u64")
.to_be_bytes(),
);
bytes.extend_from_slice(&canonical);
Ok(Digest::sha256(bytes))
}
impl fmt::Debug for ToolAuthorizationReceipt {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ToolAuthorizationReceipt")
.field("receipt_id", &self.receipt_id)
.field("provenance", &self.provenance)
.field("operation", &self.operation)
.field("tool", &self.tool)
.field("descriptor_digest", &self.descriptor_digest)
.field("input_digest", &self.input_digest)
.field("subject_digest", &self.subject_digest)
.field("policy", &self.policy)
.field("policy_digest", &self.policy_digest)
.field("decision_digest", &self.decision_digest)
.field("authorization_window_id", &self.authorization_window_id)
.field("authorized_at", &self.authorized_at)
.field("has_recovery_handle", &self.has_recovery_handle)
.field("receipt_digest", &self.receipt_digest)
.finish_non_exhaustive()
}
}
impl<'de> Deserialize<'de> for ToolAuthorizationReceipt {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
receipt_id: AuthorizationReceiptId,
provenance: ToolAuthorizationProvenance,
operation: ToolAuthorizationOperation,
tool: CapabilityIdentity,
descriptor_digest: Digest,
input_digest: Digest,
subject_digest: Digest,
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
#[serde(default)]
authorization_window_id: Option<SkillActingWindowId>,
authorized_at: Timestamp,
has_recovery_handle: bool,
receipt_digest: Digest,
}
let wire = Wire::deserialize(deserializer)?;
let mut receipt = Self::new(
wire.receipt_id,
wire.provenance,
wire.operation,
wire.tool,
wire.descriptor_digest,
wire.input_digest,
wire.subject_digest,
wire.policy,
wire.policy_digest,
wire.decision_digest,
wire.authorized_at,
wire.has_recovery_handle,
)
.map_err(de::Error::custom)?;
if let Some(window_id) = wire.authorization_window_id {
receipt = receipt
.with_authorization_window(window_id)
.map_err(de::Error::custom)?;
}
if receipt.receipt_digest != wire.receipt_digest {
return Err(de::Error::custom(
ToolAuthorizationReceiptError::DigestMismatch,
));
}
Ok(receipt)
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ToolAuthorizationReceiptError {
#[error("tool authorization receipt canonical encoding failed")]
Encoding,
#[error("tool authorization receipt digest does not match its fields")]
DigestMismatch,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ToolAuthorizationReceiptSinkFailure {
Unavailable,
Rejected,
}
#[derive(Debug)]
struct PrivateReceiptSinkSource(Arc<dyn StdError + Send + Sync + 'static>);
impl fmt::Display for PrivateReceiptSinkSource {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("private Tool authorization receipt sink failure")
}
}
impl StdError for PrivateReceiptSinkSource {
fn source(&self) -> Option<&(dyn StdError + 'static)> {
Some(self.0.as_ref())
}
}
pub struct ToolAuthorizationReceiptSinkError {
failure: ToolAuthorizationReceiptSinkFailure,
private_source: PrivateReceiptSinkSource,
}
impl ToolAuthorizationReceiptSinkError {
#[must_use]
pub fn new<E>(failure: ToolAuthorizationReceiptSinkFailure, source: E) -> Self
where
E: StdError + Send + Sync + 'static,
{
Self {
failure,
private_source: PrivateReceiptSinkSource(Arc::new(source)),
}
}
#[must_use]
pub const fn failure(&self) -> ToolAuthorizationReceiptSinkFailure {
self.failure
}
#[must_use]
pub fn private_source(&self) -> &(dyn StdError + Send + Sync + 'static) {
self.private_source.0.as_ref()
}
}
impl fmt::Debug for ToolAuthorizationReceiptSinkError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ToolAuthorizationReceiptSinkError")
.field("failure", &self.failure)
.field("has_private_source", &true)
.finish_non_exhaustive()
}
}
impl fmt::Display for ToolAuthorizationReceiptSinkError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("Tool authorization receipt sink failed")
}
}
impl StdError for ToolAuthorizationReceiptSinkError {
fn source(&self) -> Option<&(dyn StdError + 'static)> {
Some(&self.private_source)
}
}
pub trait ToolAuthorizationReceiptSink: Send + Sync + 'static {
fn record(
&self,
receipt: ToolAuthorizationReceipt,
) -> BoxFuture<'_, Result<(), ToolAuthorizationReceiptSinkError>>;
}
#[cfg(test)]
mod tests {
use std::{error::Error as StdError, fmt};
use serde_json::{Value, from_value, to_value};
use super::*;
use crate::{
CapabilityName, CapabilityReference, IssuerId, PrincipalIdentity, SubjectId, Version,
};
fn principal(subject: &str) -> PrincipalIdentity {
PrincipalIdentity::new(
"https://issuer.example.com/tenant"
.parse::<IssuerId>()
.unwrap(),
subject.parse::<SubjectId>().unwrap(),
)
}
fn capability(owner: &str, name: &str, version: Version) -> CapabilityIdentity {
CapabilityIdentity::new(
principal(owner),
CapabilityReference::new(name.parse::<CapabilityName>().unwrap(), version),
)
}
fn receipt() -> ToolAuthorizationReceipt {
ToolAuthorizationReceipt::new(
"018f1f65-45d3-7a2e-8a19-4de38b78345f".parse().unwrap(),
ToolAuthorizationProvenance::new(
"tenant-a".parse().unwrap(),
"018f1f65-45d3-7a2e-8a19-4de38b783460".parse().unwrap(),
"018f1f65-45d3-7a2e-8a19-4de38b783461".parse().unwrap(),
"018f1f65-45d3-7a2e-8a19-4de38b783462".parse().unwrap(),
"018f1f65-45d3-7a2e-8a19-4de38b783463".parse().unwrap(),
"018f1f65-45d3-7a2e-8a19-4de38b783464".parse().unwrap(),
),
ToolAuthorizationOperation::Execute,
capability("tool-registry", "filesystem.read", Version::new(2, 1, 0)),
Digest::sha256(b"complete descriptor"),
Digest::sha256(b"private tool input"),
Digest::sha256(b"mcp skill subject"),
capability(
"policy-registry",
"skill-tool-policy",
Version::new(3, 0, 4),
),
Digest::sha256(b"policy artifact"),
Digest::sha256(b"decision evidence"),
"2026-09-20T12:34:56.123456Z".parse().unwrap(),
true,
)
.unwrap()
}
#[test]
fn receipt_round_trips_and_rejects_field_or_digest_tampering() {
let receipt = receipt();
let value = to_value(&receipt).unwrap();
assert!(value.get("authorization_window_id").is_none());
assert_eq!(
receipt.receipt_digest(),
"sha256:6ce59977d983802b7724acfdd213e4315c79e895bbb59869a485007920f9d780"
.parse()
.unwrap()
);
assert_eq!(
from_value::<ToolAuthorizationReceipt>(value.clone()).unwrap(),
receipt
);
let windowed = receipt
.clone()
.with_authorization_window("018f1f65-45d3-7a2e-8a19-4de38b783465".parse().unwrap())
.unwrap();
assert_ne!(windowed.receipt_digest(), receipt.receipt_digest());
assert!(
to_value(&windowed).unwrap()["authorization_window_id"]
.as_str()
.is_some()
);
let mut changed_input = value.clone();
changed_input["input_digest"] = to_value(Digest::sha256(b"different input")).unwrap();
assert!(
from_value::<ToolAuthorizationReceipt>(changed_input)
.unwrap_err()
.to_string()
.contains("digest does not match")
);
let mut changed_digest = value;
changed_digest["receipt_digest"] = to_value(Digest::sha256(b"forged")).unwrap();
assert!(
from_value::<ToolAuthorizationReceipt>(changed_digest)
.unwrap_err()
.to_string()
.contains("digest does not match")
);
}
#[test]
fn receipt_digest_changes_for_every_security_relevant_operation_bit() {
let execute = receipt();
let reconcile = ToolAuthorizationReceipt::new(
execute.receipt_id(),
execute.provenance().clone(),
ToolAuthorizationOperation::Reconcile,
execute.tool().clone(),
execute.descriptor_digest(),
execute.input_digest(),
execute.subject_digest(),
execute.policy().clone(),
execute.policy_digest(),
execute.decision_digest(),
execute.authorized_at(),
execute.has_recovery_handle(),
)
.unwrap();
assert_ne!(execute.receipt_digest(), reconcile.receipt_digest());
}
#[test]
fn wire_form_contains_only_identity_and_digest_evidence() {
let serialized = serde_json::to_string(&receipt()).unwrap();
assert!(!serialized.contains("private tool input"));
assert!(!serialized.contains("decision evidence"));
assert!(!serialized.contains("policy artifact"));
let value = serde_json::from_str::<Value>(&serialized).unwrap();
assert!(value.get("input").is_none());
assert!(value.get("policy_payload").is_none());
assert!(value.get("decision_payload").is_none());
}
#[derive(Debug)]
struct SecretSource;
impl fmt::Display for SecretSource {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("private-database-diagnostic")
}
}
impl StdError for SecretSource {}
#[test]
fn sink_error_public_views_redact_private_source() {
let error = ToolAuthorizationReceiptSinkError::new(
ToolAuthorizationReceiptSinkFailure::Unavailable,
SecretSource,
);
assert_eq!(
error.failure(),
ToolAuthorizationReceiptSinkFailure::Unavailable
);
assert!(!error.to_string().contains("private-database-diagnostic"));
assert!(!format!("{error:?}").contains("private-database-diagnostic"));
assert_eq!(
error.private_source().to_string(),
"private-database-diagnostic"
);
}
}