//! Warrant type - the core primitive of Tenuo. //! //! A warrant is a cryptographically-signed token of authority. There are two types: //! //! ## Warrant Types //! //! - **ISSUER**: Can issue EXECUTION warrants. Used by planners/orchestrators that //! decide what capabilities to grant without executing tools themselves. //! - **EXECUTION**: Can invoke specific tools with specific constraints. Used by //! workers that execute actions. //! //! ## Clearance Levels //! //! Warrants have hierarchical clearance levels (Untrusted=0 → System=50): //! - **Untrusted** (0): Anonymous/unauthenticated entities //! - **External** (10): Authenticated external users //! - **Partner** (20): Third-party integrations //! - **Internal** (30): Internal services //! - **Privileged** (40): Admin operations //! - **System** (50): Control plane //! //! Clearance levels can only decrease during delegation, preventing privilege escalation. //! //! ## Core Components //! //! - **Type**: ISSUER or EXECUTION (determines capabilities) //! - **Tools/Constraints**: What actions are authorized and how //! - **parent_hash**: Cryptographic linkage to parent warrant //! - **Signatures**: Cryptographic proof of authority //! - **TTL**: Time-to-live (ephemeral by design) //! //! ## Key Properties //! //! - **Monotonic Attenuation**: Capabilities only shrink when delegated, never expand //! - **Mandatory PoP**: Proof-of-Possession prevents stolen warrant usage //! - **WarrantStack Verification**: Full chain verified via parent_hash linkage //! - **Type-Safe**: Rust's type system prevents misuse use crate::approval::{AuditEvent, AuditEventType}; use crate::audit::log_event; use crate::constraints::{Constraint, ConstraintDiagnostics, ConstraintSet, ConstraintValue}; use crate::crypto::{PublicKey, Signature, SigningKey}; use crate::diff::ClearanceDiff; use crate::error::{Error, Result}; use crate::wire::{ KEY_DISPLAY_TRUNCATION, MAX_CONSTRAINTS_PER_TOOL, MAX_EXTENSION_KEYS, MAX_EXTENSION_KEY_SIZE, MAX_EXTENSION_VALUE_SIZE, MAX_TOOLS_PER_WARRANT, }; use crate::MAX_DELEGATION_DEPTH; use chrono::{DateTime, Duration as ChronoDuration, Utc}; use serde::{Deserialize, Deserializer, Serialize}; use std::collections::{BTreeMap, HashMap}; use std::time::Duration; use uuid::Uuid; /// The required prefix for all warrant IDs. pub const WARRANT_ID_PREFIX: &str = "tnu_wrt_"; /// Warrant schema version. /// /// Incremented when breaking changes are made to the warrant structure. pub const WARRANT_VERSION: u32 = 1; /// Clock skew tolerance for temporal validation (30 seconds). /// /// Warrants issued more than this amount of time in the future are rejected. /// This prevents "time travel" attacks while allowing for reasonable clock drift. pub const CLOCK_SKEW_TOLERANCE_SECS: u64 = 30; /// Type of warrant: ISSUER or EXECUTION. /// /// - **ISSUER**: Can issue execution warrants. Used by P-LLM/planner components /// that decide capabilities without executing tools. /// - **EXECUTION**: Can invoke specific tools with specific constraints. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u8)] pub enum WarrantType { /// Execution warrant - can invoke tools. /// Wire value: 0 Execution = 0, /// Issuer warrant - can issue execution warrants. /// Wire value: 1 Issuer = 1, } impl Serialize for WarrantType { fn serialize(&self, serializer: S) -> std::result::Result where S: serde::Serializer, { serializer.serialize_u8(*self as u8) } } impl<'de> Deserialize<'de> for WarrantType { fn deserialize(deserializer: D) -> std::result::Result where D: Deserializer<'de>, { struct WarrantTypeVisitor; impl<'de> serde::de::Visitor<'de> for WarrantTypeVisitor { type Value = WarrantType; fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result { formatter.write_str("integer 0 (Execution) or 1 (Issuer)") } fn visit_u8(self, value: u8) -> std::result::Result where E: serde::de::Error, { match value { 0 => Ok(WarrantType::Execution), 1 => Ok(WarrantType::Issuer), v => Err(E::custom(format!("invalid warrant type: {}", v))), } } fn visit_u64(self, value: u64) -> std::result::Result where E: serde::de::Error, { self.visit_u8(value as u8) } } deserializer.deserialize_u8(WarrantTypeVisitor) } } /// Clearance level for warrants. /// /// Used to enforce boundaries in multi-tenant or multi-component systems. /// Issuers can only issue warrants with clearance levels at or below their own `clearance` (monotonicity). /// /// Clearance levels are ordered numerically, with higher values indicating greater authority. /// This allows for simple comparisons: `clearance >= Clearance::INTERNAL`. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] #[repr(transparent)] #[serde(transparent)] pub struct Clearance(pub u8); /// Clearance may only stay the same, decrease, or be dropped along a chain. /// /// A warrant without a clearance is untrusted, so a child cannot introduce a /// clearance its parent never had. pub(crate) fn validate_clearance_attenuation( parent: Option, child: Option, ) -> Result<()> { match (parent, child) { (_, None) => Ok(()), (Some(parent), Some(child)) if child <= parent => Ok(()), (Some(parent), Some(child)) => Err(Error::MonotonicityViolation(format!( "clearance cannot increase: parent {:?}, child {:?}", parent, child ))), (None, Some(child)) => Err(Error::MonotonicityViolation(format!( "cannot introduce clearance {:?} in child when parent has none", child ))), } } impl Clearance { /// Untrusted - anonymous or unauthenticated entities (0). pub const UNTRUSTED: Self = Self(0); /// External - authenticated external users (10). pub const EXTERNAL: Self = Self(10); /// Partner - third-party integrations (20). pub const PARTNER: Self = Self(20); /// Internal - internal services (30). pub const INTERNAL: Self = Self(30); /// Privileged - admin-level access (40). pub const PRIVILEGED: Self = Self(40); /// System - control plane and highest authority (50). pub const SYSTEM: Self = Self(50); /// Create a new custom clearance level. /// /// Values 0-50 overlap with standard tiers; 51-255 are fully custom. /// /// # Example /// ``` /// use tenuo::Clearance; /// /// // Organization-specific levels /// const CONTRACTOR: Clearance = Clearance::custom(15); // Between External and Partner /// const SENIOR_ENGINEER: Clearance = Clearance::custom(35); // Between Internal and Privileged /// /// assert!(CONTRACTOR.meets(Clearance::EXTERNAL)); // 15 >= 10 /// assert!(!CONTRACTOR.meets(Clearance::PARTNER)); // 15 < 20 /// ``` pub const fn custom(level: u8) -> Self { Self(level) } /// Alias for `custom()` - create a clearance level from a raw value. pub const fn new(level: u8) -> Self { Self(level) } /// Get the raw numeric value. pub const fn level(&self) -> u8 { self.0 } /// Check if this clearance meets or exceeds the requirement. pub fn meets(&self, required: Clearance) -> bool { self.0 >= required.0 } } impl std::str::FromStr for Clearance { type Err = String; fn from_str(s: &str) -> std::result::Result { match s.to_lowercase().as_str() { "untrusted" => Ok(Clearance::UNTRUSTED), "external" => Ok(Clearance::EXTERNAL), "partner" => Ok(Clearance::PARTNER), "internal" => Ok(Clearance::INTERNAL), "privileged" => Ok(Clearance::PRIVILEGED), "system" => Ok(Clearance::SYSTEM), // Allow parsing integers (e.g. "25") s => s.parse::().map(Clearance).map_err(|_| { format!( "Invalid clearance: {}. Must be a named level or integer (0-255).", s ) }), } } } impl std::fmt::Display for Clearance { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self.0 { 0 => write!(f, "Untrusted"), 10 => write!(f, "External"), 20 => write!(f, "Partner"), 30 => write!(f, "Internal"), 40 => write!(f, "Privileged"), 50 => write!(f, "System"), n => write!(f, "Level({})", n), } } } /// Size of the timestamp window for PoP signatures in seconds. /// /// The verifier uses **bidirectional** window checking, accepting signatures from /// windows centered on the current time. With default settings (30s windows, 5 total), /// tolerance is ±60 seconds to handle clock skew in both directions. /// /// **Security trade-off**: Larger windows tolerate more clock skew but increase /// the replay window. Smaller windows reduce replay risk but may cause false /// rejections in distributed systems. pub const POP_TIMESTAMP_WINDOW_SECS: i64 = 30; /// Default number of PoP windows to check (bidirectional). /// /// With 5 windows and 30s window size, the check pattern is: /// `[0, -1, +1, -2, +2]` → current time ±60s tolerance. pub const POP_MAX_WINDOWS: u32 = 5; use crate::domain::POP_CONTEXT; /// A unique identifier for a warrant. /// /// Stored as raw 16-byte UUID on the wire (CBOR bytes). /// Uses UUIDv7 (time-ordered) which provides: /// - 48 bits of millisecond timestamp /// - 74 bits of random data /// - Monotonically increasing within the same millisecond /// - Collision probability: 1 in 2^74 per millisecond (effectively zero) #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct WarrantId([u8; 16]); impl Serialize for WarrantId { fn serialize(&self, serializer: S) -> std::result::Result where S: serde::Serializer, { serializer.serialize_bytes(&self.0) } } impl<'de> Deserialize<'de> for WarrantId { fn deserialize(deserializer: D) -> std::result::Result where D: Deserializer<'de>, { struct BytesVisitor; impl<'de> serde::de::Visitor<'de> for BytesVisitor { type Value = WarrantId; fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result { formatter.write_str("16 bytes for warrant ID") } fn visit_bytes(self, v: &[u8]) -> std::result::Result where E: serde::de::Error, { if v.len() != 16 { return Err(E::custom(format!( "warrant ID must be 16 bytes, got {}", v.len() ))); } let mut arr = [0u8; 16]; arr.copy_from_slice(v); Ok(WarrantId(arr)) } fn visit_byte_buf(self, v: Vec) -> std::result::Result where E: serde::de::Error, { self.visit_bytes(&v) } } deserializer.deserialize_bytes(BytesVisitor) } } impl WarrantId { /// Generate a new time-ordered warrant ID (UUIDv7). /// /// UUIDv7 provides both uniqueness and chronological ordering, /// making it ideal for debugging and audit trails. pub fn new() -> Self { Self(*Uuid::now_v7().as_bytes()) } /// Generate a random warrant ID (UUIDv4). /// /// Use this when you don't want IDs to reveal timing information. pub fn new_random() -> Self { Self(*Uuid::new_v4().as_bytes()) } /// Create a warrant ID from raw bytes. pub fn from_bytes(bytes: [u8; 16]) -> Self { Self(bytes) } /// Create a warrant ID from a hex string or prefixed string. /// /// Accepts: /// - Raw hex: "0123456789abcdef0123456789abcdef" (32 chars) /// - Prefixed: "tnu_wrt_0123456789abcdef0123456789abcdef" /// - Standard UUID: "01234567-89ab-cdef-0123-456789abcdef" pub fn from_string(s: impl AsRef) -> Result { let s = s.as_ref(); // Try parsing with prefix let hex_str = if let Some(stripped) = s.strip_prefix(WARRANT_ID_PREFIX) { stripped } else if s.contains('-') { // Standard UUID format return Uuid::parse_str(s) .map(|u| Self(*u.as_bytes())) .map_err(|e| Error::InvalidWarrantId(format!("invalid UUID: {}", e))); } else { s }; // Parse hex if hex_str.len() != 32 { return Err(Error::InvalidWarrantId(format!( "expected 32 hex chars, got {}", hex_str.len() ))); } let mut bytes = [0u8; 16]; for (i, chunk) in hex_str.as_bytes().chunks(2).enumerate() { let hex = std::str::from_utf8(chunk) .map_err(|_| Error::InvalidWarrantId("invalid UTF-8".to_string()))?; bytes[i] = u8::from_str_radix(hex, 16) .map_err(|_| Error::InvalidWarrantId(format!("invalid hex: {}", hex)))?; } Ok(Self(bytes)) } /// Get the ID as raw bytes. pub fn as_bytes(&self) -> &[u8; 16] { &self.0 } /// Get the ID as a hex string (for display/logging). pub fn to_hex(&self) -> String { hex::encode(self.0) } /// Get the ID as a prefixed string (for display/logging). pub fn to_prefixed_string(&self) -> String { format!("{}{}", WARRANT_ID_PREFIX, hex::encode(self.0)) } } impl Default for WarrantId { fn default() -> Self { Self::new() } } impl std::fmt::Display for WarrantId { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { // Display as prefixed string for human readability write!(f, "{}{}", WARRANT_ID_PREFIX, hex::encode(self.0)) } } pub use crate::payload::WarrantPayload; /// A signed warrant - the complete token of authority. /// This corresponds to the "Envelope" in the spec. /// A signed warrant - the complete token of authority. /// /// This serves as the primary domain object. On the wire, it is serialized /// as a `SignedWarrant` envelope (ver, payload_bytes, sig). #[derive(Debug, Clone)] pub struct Warrant { /// The deserialized payload (for business logic). pub payload: WarrantPayload, /// The internal signature. pub signature: Signature, /// The canonical bytes of the payload (for signature verification). pub payload_bytes: Vec, /// Envelope format version (default 1). pub envelope_version: u8, } // Domain separation is handled by crypto::SigningKey using strictly defined context. // PREIMAGE = envelope_version || payload_bytes // Actual signed message = SIGNATURE_CONTEXT || PREIMAGE impl Serialize for Warrant { fn serialize(&self, serializer: S) -> std::result::Result where S: serde::Serializer, { // Serialize as SignedWarrant envelope // Using a tuple/array format as per spec? // Spec says: CBOR Array [0: ver, 1: payload, 2: sig] // Our SignedWarrantEnvelope struct with integer keys implies a Map. // Spec text: "The outer envelope (SignedWarrant) is a CBOR Map." // Spec block: // CBOR Array [ ... ] // Wait, spec is contradictory or I misread "Structure" as Array? // "We use integer keys for compactness in the envelope." usually implies Map with integer keys. // But the block shows `[...]` which is Array. // And "Index 0:", "Index 1:". // Let's re-read spec carefully. // Line 521: "Envelope (SignedWarrant): CBOR Array [...]" // But Line 511 mentions integer keys? // Wait, line 511 was about constraints? // Let's check spec content again via view_file. // Line 638: | Envelope pattern | `SignedWarrant { payload, signature }` | // If it's an Array: // Use `serializer.serialize_tuple(3)` // If it's a Map: // Use struct with `rename="0"`, etc. // My previous view showed: // 524: CBOR Array [ // 525: 0: envelope_version (u8), // 526: 1: payload (bytes), // 527: 2: signature (Signature), // 528: ] // This notation usually means Array indices. // So tuple (u8, Vec, Signature). use serde::ser::SerializeTuple; let mut tup = serializer.serialize_tuple(3)?; tup.serialize_element(&self.envelope_version)?; tup.serialize_element(&serde_bytes::Bytes::new(&self.payload_bytes))?; tup.serialize_element(&self.signature)?; tup.end() } } impl<'de> Deserialize<'de> for Warrant { fn deserialize(deserializer: D) -> std::result::Result where D: serde::Deserializer<'de>, { struct WarrantVisitor; impl<'de> serde::de::Visitor<'de> for WarrantVisitor { type Value = Warrant; fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result { formatter.write_str("a signed warrant array [ver, payload_bytes, sig]") } fn visit_seq(self, mut seq: A) -> std::result::Result where A: serde::de::SeqAccess<'de>, { let envelope_version: u8 = seq .next_element()? .ok_or_else(|| serde::de::Error::invalid_length(0, &self))?; if envelope_version != 1 { return Err(serde::de::Error::custom(format!( "unsupported envelope_version: {}", envelope_version ))); } let payload_bytes: Vec = seq .next_element()? .ok_or_else(|| serde::de::Error::invalid_length(1, &self))?; let signature: Signature = seq .next_element()? .ok_or_else(|| serde::de::Error::invalid_length(2, &self))?; if seq.next_element::()?.is_some() { return Err(serde::de::Error::invalid_length(4, &self)); } // Deserialize payload let payload: WarrantPayload = ciborium::de::from_reader(&payload_bytes[..]) .map_err(|e| { serde::de::Error::custom(format!("invalid payload CBOR: {}", e)) })?; // Verify signature against domain-separated signed message: // SIGNATURE_CONTEXT || envelope_version || payload_bytes. // Built in a single allocation to avoid the intermediate // preimage vec the earlier code materialized. let ctx = crate::SIGNATURE_CONTEXT; let mut signed = Vec::with_capacity(ctx.len() + 1 + payload_bytes.len()); signed.extend_from_slice(ctx); signed.push(envelope_version); signed.extend_from_slice(&payload_bytes); if payload.issuer.verify_raw(&signed, &signature).is_err() { return Err(serde::de::Error::custom("invalid warrant signature")); } // The signature is valid, so the payload integrity is guaranteed. // Structural validation (e.g. depth limits) is handled by the // deserializer recursion limits and subsequent usage checks. Ok(Warrant { envelope_version, payload, signature, payload_bytes, }) } } deserializer.deserialize_tuple(3, WarrantVisitor) } } impl Warrant { /// Create a new warrant builder. pub fn builder() -> WarrantBuilder { WarrantBuilder::new() } /// Get the warrant ID. pub fn id(&self) -> &WarrantId { &self.payload.id } /// Get the warrant type. pub fn r#type(&self) -> WarrantType { self.payload.warrant_type } /// Get the warrant version. pub fn version(&self) -> u8 { self.payload.version } /// Get capabilities (compat alias for tools). pub fn capabilities(&self) -> Option<&BTreeMap> { if self.payload.tools.is_empty() { None } else { Some(&self.payload.tools) } } /// Inspect optional arguments in the signed policy applicable to a tool. /// /// Execution entries use exact-tool precedence over wildcard fallback. /// Issuer bounds apply only to tools authorized by `issuable_tools`. pub fn optional_fields(&self, tool: &str) -> impl Iterator { let constraints = match self.r#type() { WarrantType::Execution => self .payload .tools .get(tool) .or_else(|| self.payload.tools.get("*")), WarrantType::Issuer => self .issuable_tools() .filter(|tools| { tools .iter() .any(|candidate| candidate == tool || candidate == "*") }) .and(self.constraint_bounds()), }; constraints .into_iter() .flat_map(ConstraintSet::optional_fields) } /// Retain only specific tools (attenuation). pub fn retain_capabilities(&mut self, tools: &[String]) { let tools_set: std::collections::HashSet<_> = tools.iter().map(|s| s.as_str()).collect(); self.payload .tools .retain(|k, _| tools_set.contains(k.as_str())); } /// Get the tools authorized by this warrant. pub fn tools(&self) -> Vec { let mut tools: Vec = self.payload.tools.keys().cloned().collect(); tools.sort(); // Deterministic order tools } /// Get issuable tools (None for execution warrants). pub fn issuable_tools(&self) -> Option<&[String]> { self.payload.issuable_tools.as_deref() } /// Get max issue depth (None for execution warrants). pub fn max_issue_depth(&self) -> Option { self.payload.max_issue_depth } /// Get constraint bounds (None for execution warrants). pub fn constraint_bounds(&self) -> Option<&ConstraintSet> { self.payload.constraint_bounds.as_ref() } /// Get clearance (optional, for sensitivity enforcement). pub fn clearance(&self) -> Option { self.payload.clearance } /// Get when this warrant was issued. pub fn issued_at(&self) -> DateTime { DateTime::from_timestamp(self.payload.issued_at as i64, 0).unwrap_or_default() } /// Get the expiration time. pub fn expires_at(&self) -> DateTime { DateTime::from_timestamp(self.payload.expires_at as i64, 0).unwrap_or_default() } /// Validate that constraint nesting depths are within limits. pub fn validate_constraint_depth(&self) -> Result<()> { // Validate tools count if self.payload.tools.len() > MAX_TOOLS_PER_WARRANT { return Err(Error::Validation(format!( "tools count {} exceeds limit {}", self.payload.tools.len(), MAX_TOOLS_PER_WARRANT ))); } for constraints in self.payload.tools.values() { // Validate constraints per tool if constraints.len() > MAX_CONSTRAINTS_PER_TOOL { return Err(Error::Validation(format!( "constraints count {} exceeds limit {}", constraints.len(), MAX_CONSTRAINTS_PER_TOOL ))); } constraints.validate_depth()?; } if let Some(constraint_bounds) = &self.payload.constraint_bounds { constraint_bounds.validate_depth()?; } Ok(()) } /// Comprehensive validation of warrant structure and invariants. pub fn validate(&self) -> Result<()> { // Validate version // NOTE: Warrant version is u8 now. Assuming const WARRANT_VERSION is updated to u8 or cast here. if self.payload.version != WARRANT_VERSION as u8 { return Err(Error::Validation(format!( "unsupported warrant version: {} (expected {})", self.payload.version, WARRANT_VERSION ))); } // Validate temporal constraints let now = Utc::now().timestamp() as u64; // Check 1: Issued in future (Clock Skew) // Strict fail-closed check to prevent "time travel" attacks. if self.payload.issued_at > now.saturating_add(CLOCK_SKEW_TOLERANCE_SECS) { return Err(Error::IssuedInFuture); } // Check 2: Expiration > Issued if self.payload.expires_at <= self.payload.issued_at { return Err(Error::Validation( "warrant expires_at must be strictly greater than issued_at".to_string(), )); } // Validate expiry (informational check in some contexts, but good to validate structure) if self.is_expired() { // We usually don't fail validation for expiry alone (as historical validation is valid), // but for *new* issuance flows it might be relevant. // Following spec: validation checks invariants. Expiration is a state, not an invariant violation. } // Validate warrant type consistency match self.payload.warrant_type { WarrantType::Execution => { // Execution warrants MUST have tools (even if empty map, though usually not) // Spec implies "tools" is always present. if self.payload.issuable_tools.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have issuable_tools".to_string(), }); } if self.payload.max_issue_depth.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have max_issue_depth".to_string(), }); } } WarrantType::Issuer => { if !self.payload.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "issuer warrant cannot have tools".to_string(), }); } if self .payload .issuable_tools .as_ref() .is_none_or(|t| t.is_empty()) { return Err(Error::InvalidWarrantType { message: "issuer warrant requires at least one issuable_tool".to_string(), }); } } } // Validate max_issue_depth doesn't exceed max_depth if let Some(max_issue) = self.payload.max_issue_depth { let effective_max = self.effective_max_depth(); if max_issue > effective_max { return Err(Error::IssueDepthExceeded { depth: max_issue, max: effective_max, }); } } // Validate constraint depth self.validate_constraint_depth()?; // Validate extensions if self.payload.extensions.len() > MAX_EXTENSION_KEYS { return Err(Error::Validation(format!( "extensions count {} exceeds limit {}", self.payload.extensions.len(), MAX_EXTENSION_KEYS ))); } for (key, val) in &self.payload.extensions { if val.len() > MAX_EXTENSION_VALUE_SIZE { return Err(Error::Validation(format!( "extension '{}' value size {} exceeds limit {}", key, val.len(), MAX_EXTENSION_VALUE_SIZE ))); } } // Validate expiration is in the future if self.is_expired() { // Informational } // Validate multi-sig configuration consistency. // min_approvals must not exceed the number of eligible approvers. // A warrant claiming "3-of-1" would silently degrade to "1-of-1" during // verification via the approval_threshold() cap, which violates the issuer's // stated intent. Reject at validation time to surface the misconfiguration. if let (Some(approvers), Some(min)) = (&self.payload.required_approvers, self.payload.min_approvals) { // Distinct keys: a repeated approver cannot count twice toward the quorum. let len = distinct_approver_count(approvers); if min > len { return Err(Error::Validation(format!( "min_approvals ({}) exceeds number of distinct required_approvers ({})", min, len ))); } if min == 0 { return Err(Error::Validation( "min_approvals must be at least 1 when required_approvers is set".to_string(), )); } } Ok(()) } /// Validate structural invariants that are safe to check without a wall-clock. /// /// This is a subset of [`Warrant::validate`] covering version, type consistency, /// depth bounds, extension sizes, and multi-sig configuration. Temporal checks /// (clock-skew, expiry) are intentionally excluded so that this method can be /// called inside chain verifiers without rejecting warrants whose timestamps /// were set to a fixed future value in tests or offline contexts. pub fn validate_structural(&self) -> Result<()> { if self.payload.version != WARRANT_VERSION as u8 { return Err(Error::Validation(format!( "unsupported warrant version: {} (expected {})", self.payload.version, WARRANT_VERSION ))); } if self.payload.expires_at <= self.payload.issued_at { return Err(Error::Validation( "warrant expires_at must be strictly greater than issued_at".to_string(), )); } match self.payload.warrant_type { WarrantType::Execution => { if self.payload.issuable_tools.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have issuable_tools".to_string(), }); } if self.payload.max_issue_depth.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have max_issue_depth".to_string(), }); } } WarrantType::Issuer => { if !self.payload.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "issuer warrant cannot have tools".to_string(), }); } if self .payload .issuable_tools .as_ref() .is_none_or(|t| t.is_empty()) { return Err(Error::InvalidWarrantType { message: "issuer warrant requires at least one issuable_tool".to_string(), }); } } } if let Some(max_issue) = self.payload.max_issue_depth { let effective_max = self.effective_max_depth(); if max_issue > effective_max { return Err(Error::IssueDepthExceeded { depth: max_issue, max: effective_max, }); } } self.validate_constraint_depth()?; if self.payload.extensions.len() > MAX_EXTENSION_KEYS { return Err(Error::Validation(format!( "extensions count {} exceeds limit {}", self.payload.extensions.len(), MAX_EXTENSION_KEYS ))); } for (key, val) in &self.payload.extensions { if val.len() > MAX_EXTENSION_VALUE_SIZE { return Err(Error::Validation(format!( "extension '{}' value size {} exceeds limit {}", key, val.len(), MAX_EXTENSION_VALUE_SIZE ))); } } if let (Some(approvers), Some(min)) = (&self.payload.required_approvers, self.payload.min_approvals) { // Distinct keys: a repeated approver cannot count twice toward the quorum. let len = distinct_approver_count(approvers); if min > len { return Err(Error::Validation(format!( "min_approvals ({}) exceeds number of distinct required_approvers ({})", min, len ))); } if min == 0 { return Err(Error::Validation( "min_approvals must be at least 1 when required_approvers is set".to_string(), )); } } Ok(()) } /// Get the delegation depth (0 for root, increments on each attenuation). pub fn depth(&self) -> u32 { self.payload.depth } /// Get the maximum delegation depth allowed for this warrant chain. pub fn max_depth(&self) -> Option { // Spec has max_depth as u8. Code uses u32. Cast safely. Some(self.payload.max_depth as u32) } /// Get the effective maximum depth. pub fn effective_max_depth(&self) -> u32 { self.payload.max_depth as u32 } /// Get the parent warrant ID. /// Get the parent warrant hash, if this is a delegated warrant. pub fn parent_hash(&self) -> Option<&[u8; 32]> { self.payload.parent_hash.as_ref() } /// Check if this warrant is a root warrant (no parent). pub fn is_root(&self) -> bool { self.payload.parent_hash.is_none() } /// Get the session ID. pub fn session_id(&self) -> Option<&str> { self.payload.session_id.as_deref() } /// Get the agent ID. pub fn agent_id(&self) -> Option<&str> { self.payload.agent_id.as_deref() } /// Get the issuer's public key. pub fn issuer(&self) -> &PublicKey { &self.payload.issuer } /// Get the authorized holder's public key. pub fn authorized_holder(&self) -> &PublicKey { &self.payload.holder } /// Get the extensions map. pub fn extensions(&self) -> &BTreeMap> { &self.payload.extensions } /// Get a specific extension value. pub fn extension(&self, key: &str) -> Option<&Vec> { self.payload.extensions.get(key) } /// Check if this warrant requires Proof-of-Possession. pub fn requires_pop(&self) -> bool { true } /// Get the required approvers for multi-sig workflows. pub fn required_approvers(&self) -> Option<&Vec> { self.payload.required_approvers.as_ref() } /// Get the minimum number of approvals required. pub fn min_approvals(&self) -> Option { self.payload.min_approvals } /// Check if this warrant requires multi-sig approval. pub fn requires_multisig(&self) -> bool { self.payload.required_approvers.is_some() } /// Get the effective approval threshold. pub fn approval_threshold(&self) -> u32 { approval_threshold( self.payload.required_approvers.as_ref(), self.payload.min_approvals, ) } /// Tools an approval gate is scoped against: the execution tools, or for an /// issuer warrant, the tools it may issue. pub(crate) fn approval_gate_scope(&self) -> BTreeMap { approval_gate_scope( self.payload.warrant_type, &self.payload.tools, self.payload.issuable_tools.as_ref(), ) } /// Parse the signed `tenuo.approval_gates` extension. /// /// Returns `Ok(None)` when the extension is absent or empty. /// Returns `Err` when the bytes are present but malformed (fail-closed). pub fn approval_gate_map(&self) -> Result> { crate::approval_gate::parse_approval_gate_map( self.extension(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY), ) } /// Inspect how this warrant gates `tool`, without evaluating arguments. /// /// Distinguishes no gate, an unconditional whole-tool gate, and a /// per-argument conditional gate. Does not decide authorization. pub fn inspect_approval_gate( &self, tool: &str, ) -> Result { let map = self.approval_gate_map()?; Ok(crate::approval_gate::inspect_approval_gate( map.as_ref(), tool, )) } /// Evaluate whether a concrete tool call requires approval. /// /// Checks capability constraints first (same [`crate::constraints::Constraint::matches`] /// path as the authorizer). A denied call is [`ApprovalRequirement::Denied`] /// so adapters do not collect a signature the authorizer will reject. /// /// Does **not** check PoP, expiry, or collected approvals — those remain /// authorizer-only. Malformed or unknown gate encodings return `Err` /// (fail-closed). Do not treat an error as "not gated". pub fn approval_requirement( &self, tool: &str, args: &HashMap, ) -> Result { if let Err(err) = self.check_constraints(tool, args) { let (code, reason) = match &err { Error::ToolNotAuthorized { tool } => ( crate::ErrorCode::ToolNotAuthorized.name().to_string(), format!("warrant does not authorize tool '{tool}'"), ), Error::ConstraintNotSatisfied { field, reason } => ( crate::ErrorCode::ConstraintViolation.name().to_string(), format!("{field}: {reason}"), ), other => ("denied".to_string(), other.to_string()), }; return Ok(crate::approval_gate::ApprovalRequirement::Denied { code, reason }); } let map = self.approval_gate_map()?; crate::approval_gate::approval_requirement(map.as_ref(), tool, args) } /// Get the payload bytes (for batch signature verification). pub fn payload_bytes(&self) -> &[u8] { &self.payload_bytes } /// Build the domain-separated signature preimage. pub fn signature_preimage(&self) -> Vec { let mut preimage = Vec::with_capacity(1 + self.payload_bytes.len()); preimage.push(self.envelope_version); preimage.extend_from_slice(&self.payload_bytes); preimage } /// Build the fully domain-separated signed message: /// `SIGNATURE_CONTEXT || envelope_version || payload_bytes`. /// /// Prefer this over `signature_preimage` in batch-verification hot paths /// so a single allocation covers both the Tenuo domain prefix and the /// envelope version byte. pub fn signed_message(&self) -> Vec { let ctx = crate::SIGNATURE_CONTEXT; let mut out = Vec::with_capacity(ctx.len() + 1 + self.payload_bytes.len()); out.extend_from_slice(ctx); out.push(self.envelope_version); out.extend_from_slice(&self.payload_bytes); out } /// Get the signature. pub fn signature(&self) -> &Signature { &self.signature } /// Verify that a holder signature proves possession. pub fn verify_holder(&self, challenge: &[u8], signature: &Signature) -> Result<()> { self.payload .holder .verify(challenge, signature) .map_err(|_| Error::SignatureInvalid("holder proof-of-possession failed".to_string())) } /// Check if the warrant has expired. pub fn is_expired(&self) -> bool { self.is_expired_as_of(Utc::now().timestamp()) } /// Check expiry against a committed evaluation instant. pub fn is_expired_as_of(&self, as_of: i64) -> bool { let now = as_of.max(0) as u64; now >= self.payload.expires_at } /// True when `issued_at` is after `as_of` beyond `tolerance`. pub fn is_issued_in_future_as_of(&self, as_of: i64, tolerance: chrono::Duration) -> bool { let now = as_of.max(0) as u64; let tol_secs = tolerance.num_seconds().max(0) as u64; self.payload.issued_at > now.saturating_add(tol_secs) } /// Lifetime of this warrant in seconds (`expires_at - issued_at`). pub fn lifetime_secs(&self) -> u64 { self.payload .expires_at .saturating_sub(self.payload.issued_at) } /// Check if this warrant is terminal (cannot delegate further). pub fn is_terminal(&self) -> bool { self.depth() >= self.effective_max_depth() } /// Check if the warrant has expired, with clock skew tolerance. pub fn is_expired_with_tolerance(&self, tolerance: chrono::Duration) -> bool { self.is_expired_with_tolerance_as_of(tolerance, Utc::now().timestamp()) } /// Clock-skew expiry check against a committed evaluation instant. pub fn is_expired_with_tolerance_as_of(&self, tolerance: chrono::Duration, as_of: i64) -> bool { let now = as_of.max(0) as u64; let tol_secs = tolerance.num_seconds(); if tol_secs < 0 { now > self.payload.expires_at.saturating_sub((-tol_secs) as u64) } else { now > self.payload.expires_at.saturating_add(tol_secs as u64) } } /// Verify the warrant signature. pub fn verify(&self, expected_issuer: &PublicKey) -> Result<()> { if &self.payload.issuer != expected_issuer { return Err(Error::SignatureInvalid( "issuer public key does not match".to_string(), )); } self.verify_signature() } /// Verify the warrant signature without checking the issuer. pub fn verify_signature(&self) -> Result<()> { // Build the full signed message (SIGNATURE_CONTEXT || envelope_version || // payload_bytes) in a single allocation. The previous implementation // composed `signature_preimage()` and `PublicKey::verify()`, each of // which allocated and memcpy'd the payload, paying twice for what is // ultimately a handful of extra bytes of framing. let ctx = crate::SIGNATURE_CONTEXT; let mut signed = Vec::with_capacity(ctx.len() + 1 + self.payload_bytes.len()); signed.extend_from_slice(ctx); signed.push(self.envelope_version); signed.extend_from_slice(&self.payload_bytes); self.payload.issuer.verify_raw(&signed, &self.signature) } /// Authorize an action against this warrant. pub fn authorize( &self, tool: &str, args: &HashMap, signature: Option<&Signature>, ) -> Result<()> { self.authorize_with_pop_args(tool, args, args, signature) } /// Authorize an action using separate PoP bytes and constraint-matching args. /// /// Split-view authorize for transports (like MCP) that canonicalize /// proof-of-possession over the raw wire args, but match warrant constraints /// against an extracted/renamed view of those args. /// /// - `pop_args`: the dict the PoP signature was computed over (typically the /// raw wire args the caller sent). /// - `constraint_args`: the dict whose fields are checked against the /// warrant's per-tool constraints (typically the result of an /// `McpConfig` extraction, with renamed/coerced fields). /// /// For non-transport callers, pass the same dict for both — that matches /// [`Warrant::authorize`]. pub fn authorize_with_pop_args( &self, tool: &str, pop_args: &HashMap, constraint_args: &HashMap, signature: Option<&Signature>, ) -> Result<()> { self.authorize_with_pop_args_and_config_as_of( tool, pop_args, constraint_args, signature, POP_TIMESTAMP_WINDOW_SECS, POP_MAX_WINDOWS, Utc::now().timestamp(), ) } /// Authorize an action with custom PoP window configuration. pub fn authorize_with_pop_config( &self, tool: &str, args: &HashMap, signature: Option<&Signature>, pop_window_secs: i64, pop_max_windows: u32, ) -> Result<()> { self.authorize_with_pop_args_and_config( tool, args, args, signature, pop_window_secs, pop_max_windows, ) } /// Split-view authorize with custom PoP window configuration. /// /// Same split-view semantics as [`Warrant::authorize_with_pop_args`] but /// accepts explicit PoP window parameters. Used by /// [`crate::planes::Authorizer::check_chain_with_pop_args`]. pub fn authorize_with_pop_args_and_config( &self, tool: &str, pop_args: &HashMap, constraint_args: &HashMap, signature: Option<&Signature>, pop_window_secs: i64, pop_max_windows: u32, ) -> Result<()> { self.authorize_with_pop_args_and_config_as_of( tool, pop_args, constraint_args, signature, pop_window_secs, pop_max_windows, Utc::now().timestamp(), ) } /// Authorize against a committed evaluation instant (test / replay seam). /// /// Decoding is clock-neutral, so this standalone path rejects a warrant /// issued after `as_of` by more than [`CLOCK_SKEW_TOLERANCE_SECS`]. /// Verifiers with their own tolerance (`Authorizer`, `DataPlane`) check /// issuance themselves and call the shared core instead. #[allow(clippy::too_many_arguments)] pub fn authorize_with_pop_args_and_config_as_of( &self, tool: &str, pop_args: &HashMap, constraint_args: &HashMap, signature: Option<&Signature>, pop_window_secs: i64, pop_max_windows: u32, as_of: i64, ) -> Result<()> { if self.is_issued_in_future_as_of( as_of, chrono::Duration::seconds(CLOCK_SKEW_TOLERANCE_SECS as i64), ) { return Err(Error::IssuedInFuture); } self.authorize_issuance_checked_as_of( tool, pop_args, constraint_args, signature, pop_window_secs, pop_max_windows, as_of, ) } /// Authorization after the caller has applied its own future-issuance /// policy: expiry, warrant type, tool, proof of possession, constraints. #[allow(clippy::too_many_arguments)] pub(crate) fn authorize_issuance_checked_as_of( &self, tool: &str, pop_args: &HashMap, constraint_args: &HashMap, signature: Option<&Signature>, pop_window_secs: i64, pop_max_windows: u32, as_of: i64, ) -> Result<()> { if self.is_expired_as_of(as_of) { return Err(Error::WarrantExpired { warrant_id: self.id().to_string(), expired_at: self.expires_at(), }); } if self.payload.warrant_type != WarrantType::Execution { return Err(Error::InvalidWarrantType { message: "only execution warrants can authorize actions".to_string(), }); } let constraints = if let Some(c) = self.payload.tools.get(tool) { c } else if let Some(c) = self.payload.tools.get("*") { c } else { return Err(Error::ToolNotAuthorized { tool: tool.to_string(), }); }; self.verify_pop_as_of( tool, pop_args, signature, pop_window_secs, pop_max_windows, as_of, )?; constraints.matches(constraint_args) } /// Check if constraints match without performing other authorization checks (like PoP or expiration). /// useful for diagnostics. pub fn check_constraints( &self, tool: &str, args: &HashMap, ) -> Result<()> { // Check if tool is allowed let constraints = if let Some(c) = self.payload.tools.get(tool) { c } else if let Some(c) = self.payload.tools.get("*") { c } else { return Err(Error::ToolNotAuthorized { tool: tool.to_string(), }); }; constraints.matches(args) } /// Diagnose all capability-constraint failures without authorizing the call. /// /// This resolves exact and wildcard tool capabilities exactly as /// [`Self::check_constraints`] does, but returns deterministic structured /// diagnostics for adapters and developer tooling. It does not verify any /// cryptographic or temporal security property. pub fn diagnose_constraints( &self, tool: &str, args: &HashMap, ) -> Result { let constraints = if let Some(c) = self.payload.tools.get(tool) { c } else if let Some(c) = self.payload.tools.get("*") { c } else { return Ok(ConstraintDiagnostics::tool_not_authorized(tool)); }; constraints.diagnose(args) } /// Canonical PoP preimage: `POP_CONTEXT || CBOR((warrant_id_hex, tool, sorted_args, window_ts))`. /// /// `timestamp` is a unix-seconds instant, not a pre-windowed value. This /// function floors it the same way verification does: /// `window_ts = (timestamp / window_secs) * window_secs`. /// There is no clock read inside this function. /// /// The returned bytes are the preimage, not the final Ed25519 message. /// The final message is `SIGNATURE_CONTEXT || preimage`. pub fn pop_preimage( &self, tool: &str, args: &HashMap, timestamp: i64, window_secs: i64, ) -> Result> { if window_secs <= 0 { return Err(Error::Validation( "PoP window_secs must be greater than zero".to_string(), )); } let mut sorted_args: Vec<(&String, &ConstraintValue)> = args.iter().collect(); // determinism: canonical iteration order required — see docs/determinism-audit.md#finding-pop-sign-sort. sorted_args.sort_by_key(|(k, _)| *k); let window_ts = (timestamp / window_secs) * window_secs; let challenge_data = (self.payload.id.to_hex(), tool, sorted_args, window_ts); let mut challenge_bytes = Vec::new(); ciborium::ser::into_writer(&challenge_data, &mut challenge_bytes) .map_err(|e| Error::SerializationError(e.to_string()))?; let mut preimage = POP_CONTEXT.to_vec(); preimage.extend_from_slice(&challenge_bytes); Ok(preimage) } /// Verify PoP signature with configurable window. /// /// Uses **bidirectional** window checking to handle clock skew in both directions: /// - If holder's clock is behind verifier's → signature is in a "past" window /// - If holder's clock is ahead of verifier's → signature is in a "future" window /// /// The `max_windows` parameter controls total windows checked (centered on current time). /// With `max_windows = 5` and `window_secs = 30`, we check: -60s, -30s, 0s, +30s, +60s. pub fn verify_pop( &self, tool: &str, args: &HashMap, signature: Option<&Signature>, window_secs: i64, max_windows: u32, ) -> Result<()> { self.verify_pop_as_of( tool, args, signature, window_secs, max_windows, Utc::now().timestamp(), ) } /// Verify PoP against windows derived from `as_of`. Does not read a clock. pub fn verify_pop_at( &self, tool: &str, args: &HashMap, signature: Option<&Signature>, window_secs: i64, max_windows: u32, as_of: DateTime, ) -> Result<()> { self.verify_pop_as_of( tool, args, signature, window_secs, max_windows, as_of.timestamp(), ) } /// Verify PoP against a committed unix-seconds instant. pub fn verify_pop_as_of( &self, tool: &str, args: &HashMap, signature: Option<&Signature>, window_secs: i64, max_windows: u32, as_of: i64, ) -> Result<()> { let signature = signature .ok_or_else(|| Error::MissingSignature("Proof-of-Possession required".to_string()))?; if window_secs <= 0 { return Err(Error::Validation( "PoP window_secs must be greater than zero".to_string(), )); } let now = as_of; let mut verified = false; // Bidirectional window checking: check current window first, then alternate // between past and future windows. This handles clock skew in both directions. // // With max_windows=5: offsets are [0, -1, +1, -2, +2] → checks ±60s with 30s windows // With max_windows=4: offsets are [0, -1, +1, -2] → checks -60s to +30s let half = (max_windows / 2) as i64; for i in 0..max_windows { // Generate offset: 0, -1, +1, -2, +2, -3, +3, ... let offset = if i == 0 { 0 } else { let abs_offset = i.div_ceil(2) as i64; if i % 2 == 1 { -abs_offset // Odd indices: past windows } else { abs_offset // Even indices: future windows } }; // Skip if offset exceeds our intended range (for asymmetric max_windows) if offset.abs() > half { continue; } let window_ts = (now / window_secs + offset) * window_secs; let preimage = match self.pop_preimage(tool, args, window_ts, window_secs) { Ok(bytes) => bytes, Err(_) => continue, }; if self.payload.holder.verify(&preimage, signature).is_ok() { verified = true; break; } } if !verified { return Err(Error::SignatureInvalid( "Proof-of-Possession verification failed".to_string(), )); } Ok(()) } /// Sign an action for this warrant (creates Proof-of-Possession). pub fn sign( &self, keypair: &SigningKey, tool: &str, args: &HashMap, ) -> Result { self.sign_with_timestamp(keypair, tool, args, None) } /// Sign with an explicit timestamp for deterministic replay. /// /// This is the internal implementation that accepts an optional timestamp. /// Used by Temporal workflows to ensure replay safety. pub fn sign_with_timestamp( &self, keypair: &SigningKey, tool: &str, args: &HashMap, timestamp: Option, ) -> Result { let now = timestamp.unwrap_or_else(|| Utc::now().timestamp()); let preimage = self.pop_preimage(tool, args, now, POP_TIMESTAMP_WINDOW_SECS)?; Ok(keypair.sign(&preimage)) } /// Generate a deduplication key. pub fn dedup_key(&self, tool: &str, args: &HashMap) -> String { use sha2::{Digest, Sha256}; let mut sorted_args: Vec<(&String, &ConstraintValue)> = args.iter().collect(); // determinism: canonical iteration order required — see docs/determinism-audit.md#finding-dedup-sort. sorted_args.sort_by_key(|(k, _)| *k); let payload = (self.payload.id.to_hex(), tool, &sorted_args); let mut payload_bytes = Vec::new(); ciborium::ser::into_writer(&payload, &mut payload_bytes) .expect("dedup payload serialization should never fail"); let mut hasher = Sha256::new(); hasher.update(&payload_bytes); let hash = hasher.finalize(); hex::encode(hash) } pub const fn dedup_ttl_secs() -> i64 { POP_TIMESTAMP_WINDOW_SECS * 4 } pub fn attenuate(&self) -> AttenuationBuilder<'_> { AttenuationBuilder::new(self) } pub fn issue_execution_warrant(&self) -> Result> { if self.payload.warrant_type != WarrantType::Issuer { return Err(Error::InvalidWarrantType { message: "can only issue execution warrants from issuer warrants".to_string(), }); } Ok(IssuanceBuilder::new(self)) } } /// Count distinct approvers in `approvers`. /// /// Hash-set based: lists arrive from untrusted wire payloads before the /// issuer is checked, so the count must stay linear in the list length. fn distinct_approver_count(approvers: &[PublicKey]) -> u32 { use std::convert::TryInto; approvers .iter() .collect::>() .len() .try_into() .unwrap_or(u32::MAX) } /// Count distinct approvers in `child` that are not present in `parent`. pub(crate) fn added_approver_count(parent: &[PublicKey], child: &[PublicKey]) -> u32 { use std::collections::HashSet; use std::convert::TryInto; let parent: HashSet<_> = parent.iter().collect(); child .iter() .collect::>() .difference(&parent) .count() .try_into() .unwrap_or(u32::MAX) } /// Effective approval threshold: `min_approvals` capped at the distinct /// approver count, or every distinct approver when unset. fn approval_threshold(approvers: Option<&Vec>, min: Option) -> u32 { match (approvers, min) { (Some(approvers), Some(min)) => min.min(distinct_approver_count(approvers)), (Some(approvers), None) => distinct_approver_count(approvers), (None, _) => 0, } } /// A parent gate with no approvers can never be approved. A child that keeps /// such a gate must not name approvers: they apply warrant-wide, so the /// delegator could approve calls the parent could never make. pub(crate) fn check_approvers_under_unapprovable_gate( parent: &Warrant, child_scope: &BTreeMap, child_approvers: Option<&Vec>, ) -> Result<()> { if parent .payload .required_approvers .as_ref() .is_some_and(|a| !a.is_empty()) || child_approvers.is_none_or(|a| a.is_empty()) { return Ok(()); } let parent_gates = crate::approval_gate::parse_approval_gate_map( parent.extension(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY), )?; if parent_gates .is_some_and(|g| crate::approval_gate::propagate_approval_gates(&g, child_scope).is_some()) { return Err(Error::MonotonicityViolation( "cannot add approvers under a parent approval gate that has none".to_string(), )); } Ok(()) } /// Approvers sorted and deduplicated, as the builders store them, so an /// inherited list compares equal to the parent's however the parent wrote it. fn canonical_approvers(approvers: Option<&Vec>) -> Option> { approvers.map(|approvers| { let mut approvers = approvers.clone(); approvers.sort_by_key(|a| a.to_bytes()); approvers.dedup(); approvers }) } /// Approvers in `child` that `parent` does not already list. fn delegated_added_approvers(parent: &Warrant, child: Option<&Vec>) -> u32 { match (parent.payload.required_approvers.as_deref(), child) { (Some(p), Some(c)) => added_approver_count(p, c), _ => 0, } } /// A delegated child's minimum. Left at the parent's value, it rises by one per /// added approver, as issuance does, so adding a key never needs a separate /// `raise_min_approvals` call. fn delegated_min_approvals( parent: &Warrant, approvers: Option<&Vec>, min: Option, ) -> Option { let parent_min = parent.payload.min_approvals; match (min.or(parent_min), parent_min) { (Some(min), Some(parent_min)) if min == parent_min => { Some(parent_min.saturating_add(delegated_added_approvers(parent, approvers))) } (min, _) => min, } } /// Error text for a child threshold below `base` plus one per added approver. pub(crate) fn threshold_violation(base: u32, added: u32, threshold: u32) -> String { if added == 0 { format!( "cannot lower approval threshold from {} to {}", base, threshold ) } else { format!( "adding {} approver(s) requires an approval threshold of at least {}, got {}", added, base.saturating_add(added), threshold ) } } /// See [`Warrant::approval_gate_scope`]. fn approval_gate_scope( warrant_type: WarrantType, tools: &BTreeMap, issuable_tools: Option<&Vec>, ) -> BTreeMap { match warrant_type { WarrantType::Execution => tools.clone(), WarrantType::Issuer => issuable_tools .into_iter() .flatten() .map(|name| (name.clone(), ConstraintSet::new())) .collect(), } } /// Builder for creating root warrants. #[derive(Debug, Clone)] pub struct WarrantBuilder { warrant_type: Option, // tools (Execution) tools: BTreeMap, // Issuer fields issuable_tools: Option>, max_issue_depth: Option, constraint_bounds: ConstraintSet, // Common clearance: Option, ttl: Option, max_depth: Option, session_id: Option, agent_id: Option, holder: Option, required_approvers: Option>, min_approvals: Option, id: Option, // Root warrants have no parent hash // parent_id removed as it is not part of root warrant payload // extensions // Extensions extensions: BTreeMap>, // Deferred error (from builder methods that can't return Result) error: Option, } impl WarrantBuilder { pub fn new() -> Self { Self { warrant_type: None, tools: BTreeMap::new(), issuable_tools: None, max_issue_depth: None, constraint_bounds: ConstraintSet::new(), clearance: None, ttl: None, max_depth: None, session_id: None, agent_id: None, holder: None, required_approvers: None, min_approvals: None, id: None, // parent_id: None, extensions: BTreeMap::new(), error: None, } } pub fn r#type(mut self, warrant_type: WarrantType) -> Self { self.warrant_type = Some(warrant_type); self } pub fn clearance(mut self, level: Clearance) -> Self { self.clearance = Some(level); self } pub fn issuable_tools(mut self, tools: Vec) -> Self { self.issuable_tools = Some(tools); self } pub fn max_issue_depth(mut self, depth: u32) -> Self { self.max_issue_depth = Some(depth); self } pub fn constraint_bound( mut self, field: impl Into, constraint: impl Into, ) -> Self { self.constraint_bounds.insert(field, constraint); self } // depth() removed in 0.1.0 - root warrants always have depth 0 // Use warrant.depth() accessor instead after building. // Root warrants cannot have a parent ID/hash set manually via this builder. // Use AttenuationBuilder for delegated warrants. // Add extension support pub fn extension(mut self, key: impl Into, value: Vec) -> Self { self.extensions.insert(key.into(), value); self } // Support /// Add a capability (tool + constraints). /// Add a tool (tool + constraints). pub fn tool(mut self, tool: impl Into, constraints: ConstraintSet) -> Self { let tool_name: String = tool.into(); // Validate reserved tool namespace if tool_name.starts_with("tenuo:") { self.error = Some(Error::Validation( "Reserved tool namespace: tools starting with 'tenuo:' are reserved for framework use" .to_string(), )); return self; } self.tools.insert(tool_name, constraints); self } /// Compat alias pub fn capability(self, tool: impl Into, constraints: ConstraintSet) -> Self { self.tool(tool, constraints) } // Support authorized_holder renamed to holder pub fn holder(mut self, holder: PublicKey) -> Self { self.holder = Some(holder); self } pub fn ttl(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self } pub fn session_id(mut self, id: impl Into) -> Self { self.session_id = Some(id.into()); self } pub fn agent_id(mut self, id: impl Into) -> Self { self.agent_id = Some(id.into()); self } pub fn required_approvers(mut self, approvers: Vec) -> Self { self.required_approvers = Some(approvers); self } pub fn min_approvals(mut self, min: u32) -> Self { self.min_approvals = Some(min); self } pub fn max_depth(mut self, depth: u32) -> Self { self.max_depth = Some(depth); self } /// Set a custom warrant ID. pub fn id(mut self, id: WarrantId) -> Self { self.id = Some(id); self } /// Build and sign the warrant. pub fn build(mut self, signing_key: &SigningKey) -> Result { // Return deferred error if any if let Some(err) = self.error { return Err(err); } if self.warrant_type.is_none() { if !self.tools.is_empty() { self.warrant_type = Some(WarrantType::Execution); } else if self.issuable_tools.is_some() || self.max_issue_depth.is_some() { self.warrant_type = Some(WarrantType::Issuer); } } // Canonicalize lists for deterministic serialization if let Some(tools) = &mut self.issuable_tools { tools.sort(); tools.dedup(); } if let Some(approvers) = &mut self.required_approvers { // PublicKey doesn't implement Ord, so sort by bytes approvers.sort_by_key(|a| a.to_bytes()); approvers.dedup(); } let warrant_type = self .warrant_type .ok_or_else(|| Error::Validation("warrant type required".to_string()))?; // Validate required fields based on warrant type match warrant_type { WarrantType::Execution => { if self.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "execution warrant must have tools".to_string(), }); } if self.issuable_tools.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have issuable_tools".to_string(), }); } if self.max_issue_depth.is_some() { return Err(Error::InvalidWarrantType { message: "execution warrant cannot have max_issue_depth".to_string(), }); } } WarrantType::Issuer => { if !self.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "issuer warrant cannot have tools".to_string(), }); } if self.issuable_tools.as_ref().is_none_or(|t| t.is_empty()) { return Err(Error::InvalidWarrantType { message: "issuer warrant requires at least one issuable_tool".to_string(), }); } } } // Default TTL: 5 minutes - ephemeral by design, expand only as needed let ttl = self .ttl .unwrap_or_else(|| Duration::from_secs(crate::DEFAULT_WARRANT_TTL_SECS)); // Validate TTL doesn't exceed protocol maximum (90 days) if ttl.as_secs() > crate::MAX_WARRANT_TTL_SECS { return Err(Error::InvalidTtl(format!( "TTL {} seconds exceeds protocol maximum of {} seconds ({} days)", ttl.as_secs(), crate::MAX_WARRANT_TTL_SECS, crate::MAX_WARRANT_TTL_SECS / 86400 ))); } // Holder defaults to issuer if not set (Self-issued) which is valid. let holder = self.holder.unwrap_or_else(|| signing_key.public_key()); let max_depth_val = self.max_depth.unwrap_or(crate::MAX_DELEGATION_DEPTH); let max_depth_u8 = max_depth_val as u8; // Safe cast assuming MAX_DELEGATION_DEPTH small // Validate max_depth doesn't exceed protocol cap if max_depth_val > crate::MAX_DELEGATION_DEPTH { return Err(Error::DepthExceeded( max_depth_val, crate::MAX_DELEGATION_DEPTH, )); } // Validate max_issue_depth for issuer warrants if let Some(max_issue) = self.max_issue_depth { if max_issue > max_depth_val { return Err(Error::IssueDepthExceeded { depth: max_issue, max: max_depth_val, }); } } // Validate min_approvals if set if let (Some(approvers), Some(min)) = (&self.required_approvers, self.min_approvals) { if min as usize > approvers.len() { return Err(Error::MonotonicityViolation(format!( "min_approvals ({}) cannot exceed required_approvers count ({})", min, approvers.len() ))); } } // required_approvers must be paired with an approval gate map: the gate map // specifies which tools require approval. Without one, required_approvers // has no effect at authorization time. if self .required_approvers .as_ref() .map(|a| !a.is_empty()) .unwrap_or(false) && !self .extensions .contains_key(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { return Err(Error::Validation( "required_approvers requires an approval gate map: add a tenuo.approval_gates extension \ specifying which tools need approval" .to_string(), )); } // Validate tools count if self.tools.len() > MAX_TOOLS_PER_WARRANT { return Err(Error::Validation(format!( "tools count {} exceeds limit {}", self.tools.len(), MAX_TOOLS_PER_WARRANT ))); } // Validate constraint depth in tools for constraints in self.tools.values() { // Validate constraints per tool if constraints.len() > MAX_CONSTRAINTS_PER_TOOL { return Err(Error::Validation(format!( "constraints count {} exceeds limit {}", constraints.len(), MAX_CONSTRAINTS_PER_TOOL ))); } constraints.validate_depth()?; } // Validate extensions if self.extensions.len() > MAX_EXTENSION_KEYS { return Err(Error::Validation(format!( "extensions count {} exceeds limit {}", self.extensions.len(), MAX_EXTENSION_KEYS ))); } for (key, val) in &self.extensions { if key.len() > MAX_EXTENSION_KEY_SIZE { return Err(Error::Validation(format!( "extension key '{}...' length {} exceeds limit {}", key.chars().take(KEY_DISPLAY_TRUNCATION).collect::(), key.len(), MAX_EXTENSION_KEY_SIZE ))); } if val.len() > MAX_EXTENSION_VALUE_SIZE { return Err(Error::Validation(format!( "extension '{}' value size {} exceeds limit {}", key, val.len(), MAX_EXTENSION_VALUE_SIZE ))); } } if !self.constraint_bounds.is_empty() { self.constraint_bounds.validate_depth()?; } let id = self.id.unwrap_or_default(); let issued_at = Utc::now().timestamp() as u64; let expires_at = issued_at + ttl.as_secs(); let payload = WarrantPayload { version: WARRANT_VERSION as u8, warrant_type, id, tools: self.tools, holder, issuer: signing_key.public_key(), issued_at, expires_at, max_depth: max_depth_u8, depth: 0, // Root warrant has depth 0 parent_hash: None, // Root warrant has no parent hash extensions: self.extensions, issuable_tools: self.issuable_tools, max_issue_depth: self.max_issue_depth, constraint_bounds: if self.constraint_bounds.is_empty() { None } else { Some(self.constraint_bounds) }, clearance: self.clearance, session_id: self.session_id, agent_id: self.agent_id, required_approvers: self.required_approvers, min_approvals: self.min_approvals, }; let mut payload_bytes = Vec::new(); ciborium::ser::into_writer(&payload, &mut payload_bytes) .map_err(|e| Error::SerializationError(e.to_string()))?; // Preimage: envelope_version || payload_bytes let mut preimage = Vec::with_capacity(1 + payload_bytes.len()); preimage.push(1); // envelope_version preimage.extend_from_slice(&payload_bytes); let signature = signing_key.sign(&preimage); let warrant = Warrant { payload, signature, payload_bytes, envelope_version: 1, }; // Audit: Log warrant creation log_event(AuditEvent { id: Uuid::new_v4().to_string(), event_type: AuditEventType::WarrantIssued, timestamp: Utc::now(), provider: "tenuo".to_string(), external_id: None, public_key_hex: Some(hex::encode(signing_key.public_key().to_bytes())), actor: format!( "issuer:{}", hex::encode(&signing_key.public_key().to_bytes()[..8]) ), details: Some(format!( "root warrant created: type={:?}, tools={:?}, depth=0", warrant.payload.warrant_type, warrant.tools() )), related_ids: Some(vec![warrant.id().to_string()]), }); Ok(warrant) } } impl Default for WarrantBuilder { fn default() -> Self { Self::new() } } /// Expiry for a delegated warrant that requested `ttl_secs`. /// /// A child may not outlive its parent. A request that would is rejected /// rather than silently shortened, so the caller learns that it asked for /// more than it was given. Omitting the TTL inherits the parent's expiry. fn child_expiry_within_parent(now_sec: u64, ttl_secs: u64, parent_expires_at: u64) -> Result { let proposed = now_sec.saturating_add(ttl_secs); if proposed > parent_expires_at { return Err(Error::MonotonicityViolation(format!( "ttl {}s would outlive the parent warrant, which expires in {}s", ttl_secs, parent_expires_at.saturating_sub(now_sec) ))); } Ok(proposed) } /// Expiry for a high-level delegation API that promises to cap a requested /// lifetime at the parent's expiry. This calculation is deliberately done in /// the core, using the same clock read as warrant construction, so language /// bindings cannot race a wall-clock second boundary. fn child_expiry_capped_to_parent(now_sec: u64, ttl_secs: u64, parent_expires_at: u64) -> u64 { now_sec.saturating_add(ttl_secs).min(parent_expires_at) } /// Builder for attenuating existing warrants. #[derive(Debug)] pub struct AttenuationBuilder<'a> { parent: &'a Warrant, // Execution warrant fields tools: BTreeMap, // Issuer warrant fields issuable_tools: Option>, max_issue_depth: Option, constraint_bounds: ConstraintSet, // Common fields clearance: Option, ttl: Option, cap_ttl_to_parent: bool, max_depth: Option, session_id: Option, agent_id: Option, holder: Option, required_approvers: Option>, min_approvals: Option, // Extensions extensions: BTreeMap>, } impl<'a> AttenuationBuilder<'a> { /// Create a new attenuation builder. /// /// Follows the **Principle of Least Authority (POLA)**: the child warrant /// starts with NO capabilities. You must explicitly specify each capability /// you want using `.tool()`. This prevents accidentally granting /// more authority than intended. fn new(parent: &'a Warrant) -> Self { // POLA: Start with empty capabilities - must explicitly add each one let (tools, issuable_tools, max_issue_depth, constraint_bounds) = match parent.payload.warrant_type { WarrantType::Execution => ( // POLA: Start empty, not with parent's tools BTreeMap::new(), None, None, ConstraintSet::new(), ), WarrantType::Issuer => ( BTreeMap::new(), // POLA: Start empty for issuable_tools too None, parent.payload.max_issue_depth, parent.payload.constraint_bounds.clone().unwrap_or_default(), ), }; // Inherit tenuo.approval_gates from parent — approval gates propagate automatically // during delegation and are scoped to the child's tool set at build() time. let mut extensions = BTreeMap::new(); if let Some(gate_bytes) = parent .payload .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), gate_bytes.clone(), ); } Self { parent, tools, issuable_tools, max_issue_depth, constraint_bounds, clearance: parent.payload.clearance, ttl: None, cap_ttl_to_parent: false, max_depth: None, // Will inherit from parent if not set session_id: parent.payload.session_id.clone(), agent_id: parent.payload.agent_id.clone(), holder: Some(parent.payload.holder.clone()), // Multi-sig: inherit from parent (can only add MORE approvers or raise threshold) required_approvers: parent.payload.required_approvers.clone(), min_approvals: parent.payload.min_approvals, extensions, } } /// Inherit all capabilities from the parent warrant. /// /// This is an **explicit opt-in** to full inheritance. Use this when you /// want to start with all parent capabilities and then narrow specific ones. /// /// Without this, the builder follows POLA and starts empty. pub fn inherit_all(mut self) -> Self { match self.parent.payload.warrant_type { WarrantType::Execution => { self.tools = self.parent.payload.tools.clone(); } WarrantType::Issuer => { self.issuable_tools = self.parent.payload.issuable_tools.clone(); } } self } /// Add a capability (tool + constraints) to the attenuated warrant. /// /// **POLA**: You must explicitly add each capability you want. Only tools /// specified via this method will be in the child warrant. /// /// The tool must exist in the parent warrant, and constraints must be /// equal to or narrower than the parent's constraints for that tool. /// **POLA**: You must explicitly add each tool you want. Only tools /// specified via this method will be in the child warrant. /// /// The tool must exist in the parent warrant, and constraints must be /// equal to or narrower than the parent's constraints for that tool. pub fn tool(mut self, tool: impl Into, constraints: impl Into) -> Self { self.tools.insert(tool.into(), constraints.into()); self } /// Compat alias pub fn capability( self, tool: impl Into, constraints: impl Into, ) -> Self { self.tool(tool, constraints) } /// Set a single tool for issuable_tools (for issuer warrants). pub fn issuable_tool(mut self, tool: impl Into) -> Self { self.issuable_tools = Some(vec![tool.into()]); self } /// Set multiple tools for issuable_tools (for issuer warrants). pub fn issuable_tools(mut self, tools: Vec) -> Self { self.issuable_tools = Some(tools); self } /// Set a shorter TTL. pub fn ttl(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self.cap_ttl_to_parent = false; self } /// Set a TTL, shortening it atomically to the parent's expiry if needed. /// /// This is intended for high-level SDKs whose documented behavior is to /// clamp a requested lifetime. Low-level callers should use [`Self::ttl`] /// when an overlong request must be reported as an error. pub fn ttl_capped_to_parent(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self.cap_ttl_to_parent = true; self } /// Set a lower maximum delegation depth. pub fn max_depth(mut self, max_depth: u32) -> Self { self.max_depth = Some(max_depth); self } // NOTE: session_id is inherited from parent and immutable during attenuation. /// Set or change the agent ID. pub fn agent_id(mut self, agent_id: impl Into) -> Self { self.agent_id = Some(agent_id.into()); self } /// Set or change the authorized holder (Proof-of-Possession). pub fn holder(mut self, public_key: PublicKey) -> Self { self.holder = Some(public_key); self } /// Add required approvers (can only add more, not remove). pub fn add_approvers(mut self, approvers: Vec) -> Self { let mut current = self.required_approvers.unwrap_or_default(); for approver in approvers { if !current.contains(&approver) { current.push(approver); } } self.required_approvers = Some(current); self } /// Increase the minimum approvals required (can only increase). pub fn raise_min_approvals(mut self, min: u32) -> Self { let current = self.min_approvals.unwrap_or(0); self.min_approvals = Some(min.max(current)); self } /// Set the clearance (can only decrease from parent). /// /// Clearance monotonicity is enforced at build time. pub fn clearance(mut self, clearance: Clearance) -> Self { self.clearance = Some(clearance); self } /// Add an extension. /// /// The `tenuo.approval_gates` key is system-managed (inherited from parent and /// propagated automatically) and cannot be overwritten here. pub fn extension(mut self, key: impl Into, value: Vec) -> Self { let key = key.into(); if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return self; } self.extensions.insert(key, value); self } /// Validate multi-sig monotonicity (cannot remove approvers or lower threshold). fn validate_multisig_monotonicity(&self) -> Result<()> { check_approvers_under_unapprovable_gate( self.parent, &approval_gate_scope( self.parent.payload.warrant_type, &self.tools, self.issuable_tools.as_ref(), ), self.required_approvers.as_ref(), )?; if let Some(parent_approvers) = &self.parent.payload.required_approvers { if let Some(child_approvers) = &self.required_approvers { for parent_key in parent_approvers { if !child_approvers.contains(parent_key) { return Err(Error::MonotonicityViolation(format!( "cannot remove approver {} from multi-sig set", hex::encode(parent_key.to_bytes()) ))); } } } else { return Err(Error::MonotonicityViolation( "cannot remove multi-sig requirement from parent".to_string(), )); } } if let Some(parent_min) = self.parent.payload.min_approvals { if let Some(child_min) = self.min_approvals { if child_min < parent_min { return Err(Error::MonotonicityViolation(format!( "cannot lower min_approvals from {} to {}", parent_min, child_min ))); } } } if let (Some(approvers), Some(min)) = (&self.required_approvers, self.min_approvals) { if min as usize > approvers.len() { return Err(Error::MonotonicityViolation(format!( "min_approvals ({}) cannot exceed required_approvers count ({})", min, approvers.len() ))); } } // An unset parent minimum still means every parent approver; each added // approver must also raise the effective threshold so a new key cannot // satisfy the quorum in place of a parent approver. let added = delegated_added_approvers(self.parent, self.required_approvers.as_ref()); let base = self.parent.approval_threshold(); let threshold = approval_threshold( self.required_approvers.as_ref(), delegated_min_approvals( self.parent, self.required_approvers.as_ref(), self.min_approvals, ), ); if threshold < base.saturating_add(added) { return Err(Error::MonotonicityViolation(threshold_violation( base, added, threshold, ))); } Ok(()) } /// Build and sign the attenuated warrant. /// /// The signing key must belong to the holder of the parent warrant. /// This enforces the delegation authority rule: you can only delegate /// what you hold. /// /// # Arguments /// * `signing_key` - The keypair of the parent warrant's holder (the delegator) /// /// # Errors /// Returns `DelegationAuthorityError` if the signing key doesn't match /// the parent warrant's holder. /// Compatibility sugar: prepare, raw-sign, finalize. pub fn build(self, signing_key: &SigningKey) -> Result { if signing_key.public_key() != *self.parent.authorized_holder() { return Err(Error::DelegationAuthorityError { expected: self.parent.authorized_holder().fingerprint(), actual: signing_key.public_key().fingerprint(), }); } let prepared = self.prepare()?; let signature = signing_key.sign_raw(prepared.final_signing_bytes()); prepared.finalize(signature) } /// Freeze the child payload for an external or local parent signer. pub fn prepare(mut self) -> Result { if let Some(tools) = &mut self.issuable_tools { tools.sort(); tools.dedup(); } if let Some(approvers) = &mut self.required_approvers { approvers.sort_by_key(|a| a.to_bytes()); approvers.dedup(); } let new_depth = self.parent.depth() + 1; if new_depth > MAX_DELEGATION_DEPTH { return Err(Error::DepthExceeded(new_depth, MAX_DELEGATION_DEPTH)); } // Calculate effective max_depth (monotonic: can only shrink) let parent_max_depth = self.parent.max_depth(); let effective_max = match (parent_max_depth, self.max_depth) { (Some(parent_max), Some(child_max)) => { if child_max > parent_max { return Err(Error::MonotonicityViolation(format!( "max_depth {} exceeds parent's max_depth {}", child_max, parent_max ))); } Some(child_max) } (Some(parent_max), None) => Some(parent_max), (None, Some(child_max)) => { if child_max > MAX_DELEGATION_DEPTH { return Err(Error::DepthExceeded(child_max, MAX_DELEGATION_DEPTH)); } Some(child_max) } (None, None) => None, }; let depth_limit = effective_max.unwrap_or(MAX_DELEGATION_DEPTH); if new_depth > depth_limit { return Err(Error::DepthExceeded(new_depth, depth_limit)); } if self.parent.is_expired() { return Err(Error::WarrantExpired { warrant_id: self.parent.id().to_string(), expired_at: self.parent.expires_at(), }); } // Validate attenuation monotonicity based on warrant type match self.parent.payload.warrant_type { WarrantType::Execution => { let parent_tools = &self.parent.payload.tools; crate::constraints::validate_tool_map_attenuation( parent_tools, &self.tools, "tools", )?; if self.tools.is_empty() { return Err(Error::Validation( "execution warrant must have at least one tool".to_string(), )); } // Clearance monotonicity: child cannot exceed parent, and cannot // introduce a clearance claim that the parent never established. if let Some(child_clearance) = self.clearance { match self.parent.payload.clearance { Some(parent_clearance) => { if child_clearance > parent_clearance { return Err(Error::MonotonicityViolation(format!( "clearance cannot increase: parent {:?}, child {:?}", parent_clearance, child_clearance ))); } } None => { return Err(Error::MonotonicityViolation(format!( "cannot introduce clearance {:?} in child when parent has none", child_clearance ))); } } } } WarrantType::Issuer => { validate_clearance_attenuation(self.parent.payload.clearance, self.clearance)?; if let Some(parent_issuable) = &self.parent.payload.issuable_tools { if let Some(ref child_issuable) = self.issuable_tools { for tool in child_issuable { if !parent_issuable.iter().any(|t| t == tool || t == "*") { return Err(Error::MonotonicityViolation(format!( "issuable_tool '{}' not in parent's issuable_tools", tool ))); } } } } if let Some(parent_bounds) = &self.parent.payload.constraint_bounds { parent_bounds.validate_attenuation(&self.constraint_bounds)?; } } } // Propagate approval gates: scope inherited gate map to the child's tool set. // Gates for tools the child doesn't have are dropped. if let Some(gate_bytes) = self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) .cloned() { let parent_gates = crate::approval_gate::parse_approval_gate_map(Some(&gate_bytes))?; if let Some(parent_gates) = parent_gates { match crate::approval_gate::propagate_approval_gates( &parent_gates, &approval_gate_scope( self.parent.payload.warrant_type, &self.tools, self.issuable_tools.as_ref(), ), ) { Some(scoped) => { let encoded = crate::approval_gate::encode_approval_gate_map(&scoped)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); } None => { // No gate survives: inherited approvers have nothing to // approve. Approvers set on this builder would be lost. if canonical_approvers(self.required_approvers.as_ref()) != canonical_approvers(self.parent.payload.required_approvers.as_ref()) || self.min_approvals != self.parent.payload.min_approvals { return Err(Error::Validation( "required_approvers requires an approval gate map".to_string(), )); } self.extensions .remove(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY); self.required_approvers = None; self.min_approvals = None; } } } } if self .extensions .contains_key(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) || self.required_approvers.is_some() { self.validate_multisig_monotonicity()?; } // Validate extensions if self.extensions.len() > MAX_EXTENSION_KEYS { return Err(Error::Validation(format!( "extensions count {} exceeds limit {}", self.extensions.len(), MAX_EXTENSION_KEYS ))); } for (key, val) in &self.extensions { if key.len() > MAX_EXTENSION_KEY_SIZE { return Err(Error::Validation(format!( "extension key '{}...' length {} exceeds limit {}", key.chars().take(KEY_DISPLAY_TRUNCATION).collect::(), key.len(), MAX_EXTENSION_KEY_SIZE ))); } if val.len() > MAX_EXTENSION_VALUE_SIZE { return Err(Error::Validation(format!( "extension '{}' value size {} exceeds limit {}", key, val.len(), MAX_EXTENSION_VALUE_SIZE ))); } } let holder = self .holder .ok_or_else(|| Error::Validation("holder is required".to_string()))?; let now_sec = Utc::now().timestamp() as u64; let expires_at = if let Some(ttl) = self.ttl { if self.cap_ttl_to_parent { child_expiry_capped_to_parent( now_sec, ttl.as_secs(), self.parent.payload.expires_at, ) } else { child_expiry_within_parent(now_sec, ttl.as_secs(), self.parent.payload.expires_at)? } } else { self.parent.payload.expires_at }; let effective_min = if self.required_approvers.is_some() { delegated_min_approvals( self.parent, self.required_approvers.as_ref(), self.min_approvals, ) } else { None }; use sha2::{Digest, Sha256}; let mut hasher = Sha256::new(); hasher.update(&self.parent.payload_bytes); let parent_hash: [u8; 32] = hasher.finalize().into(); let payload = WarrantPayload { version: WARRANT_VERSION as u8, warrant_type: self.parent.payload.warrant_type, id: WarrantId::new(), holder, tools: self.tools, issuable_tools: match self.parent.payload.warrant_type { WarrantType::Issuer => self.issuable_tools.clone(), WarrantType::Execution => None, }, max_issue_depth: match self.parent.payload.warrant_type { WarrantType::Issuer => self.max_issue_depth, WarrantType::Execution => None, }, constraint_bounds: match self.parent.payload.warrant_type { WarrantType::Issuer => { if self.constraint_bounds.is_empty() { None } else { Some(self.constraint_bounds) } } WarrantType::Execution => None, }, clearance: self.clearance, issued_at: now_sec, expires_at, max_depth: effective_max .map(|d| d as u8) .unwrap_or(MAX_DELEGATION_DEPTH as u8), depth: self.parent.depth() + 1, // Increment depth from parent session_id: self.session_id, agent_id: self.agent_id, issuer: self.parent.authorized_holder().clone(), parent_hash: Some(parent_hash), required_approvers: self.required_approvers, min_approvals: effective_min, extensions: self.extensions, }; if payload.warrant_type == WarrantType::Issuer && !payload.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "issuer warrant cannot have tools".to_string(), }); } let mut payload_bytes = Vec::new(); ciborium::ser::into_writer(&payload, &mut payload_bytes) .map_err(|e| Error::SerializationError(e.to_string()))?; let envelope_version = 1u8; let mut final_bytes = Vec::with_capacity(crate::SIGNATURE_CONTEXT.len() + 1 + payload_bytes.len()); final_bytes.extend_from_slice(crate::SIGNATURE_CONTEXT); final_bytes.push(envelope_version); final_bytes.extend_from_slice(&payload_bytes); Ok(PreparedDelegation { payload, payload_bytes, envelope_version, final_bytes, parent_holder: self.parent.authorized_holder().clone(), parent_id: self.parent.id().clone(), }) } } /// Unsigned child warrant. Payload is frozen after [`AttenuationBuilder::prepare`]. pub struct PreparedDelegation { payload: WarrantPayload, payload_bytes: Vec, envelope_version: u8, final_bytes: Vec, parent_holder: crate::crypto::PublicKey, parent_id: WarrantId, } impl PreparedDelegation { /// `SIGNATURE_CONTEXT || envelope_version || payload_bytes`. pub fn final_signing_bytes(&self) -> &[u8] { &self.final_bytes } /// Verify the parent-holder signature, bind it, and return the child warrant. pub fn finalize(self, signature: Signature) -> Result { self.parent_holder .verify_raw(&self.final_bytes, &signature) .map_err(|_| { Error::SignatureInvalid("delegation signature does not match parent holder".into()) })?; let warrant = Warrant { payload: self.payload, signature, payload_bytes: self.payload_bytes, envelope_version: self.envelope_version, }; log_event(AuditEvent { id: Uuid::new_v4().to_string(), event_type: AuditEventType::WarrantIssued, timestamp: Utc::now(), provider: "tenuo".to_string(), external_id: None, public_key_hex: Some(hex::encode(self.parent_holder.to_bytes())), actor: format!( "delegator:{}", hex::encode(&self.parent_holder.to_bytes()[..8]) ), details: Some(format!( "warrant attenuated: type={:?}, depth={}, parent={}", warrant.payload.warrant_type, warrant.depth(), self.parent_id )), related_ids: Some(vec![warrant.id().to_string(), self.parent_id.to_string()]), }); Ok(warrant) } } /// Builder for attenuating warrants that owns its data (no lifetime). /// /// This is identical to `AttenuationBuilder` but owns the parent warrant, /// making it suitable for FFI boundaries (e.g., Python bindings) where /// lifetime management is difficult. /// /// # Example /// /// ```ignore /// let builder = OwnedAttenuationBuilder::new(parent.clone()); /// let child = builder /// .constraint("path", Pattern::new("/data/specific/*")) /// .ttl(Duration::from_secs(60)) /// .build(&delegator_keypair)?; // delegator holds the parent warrant /// ``` #[derive(Debug, Clone)] pub struct OwnedAttenuationBuilder { parent: Warrant, // Execution warrant fields tools: BTreeMap, /// Set by `inherit_all()` and cleared by `retain_*`. While set, the /// additive `inherit_capability*` calls are refused: on a full selection /// they cannot narrow anything, and callers written against the old /// `with_tool` (which narrowed) would silently keep every parent tool. inherited_all: bool, // Issuer warrant fields issuable_tools: Option>, max_issue_depth: Option, constraint_bounds: ConstraintSet, // Common fields clearance: Option, ttl: Option, cap_ttl_to_parent: bool, max_depth: Option, session_id: Option, agent_id: Option, holder: Option, required_approvers: Option>, min_approvals: Option, /// Intent/purpose for this delegation (for audit trails). intent: Option, // Extensions extensions: BTreeMap>, } impl OwnedAttenuationBuilder { /// Create a new owned attenuation builder. /// /// Follows the **Principle of Least Authority (POLA)**: the child warrant /// starts with NO capabilities. You must explicitly specify each capability /// you want using `.set_tool()`. This prevents accidentally granting /// more authority than intended. /// /// Use `.inherit_all()` if you explicitly want all parent capabilities. pub fn new(parent: Warrant) -> Self { // POLA: Start with empty capabilities - must explicitly add each one let (tools, issuable_tools, max_issue_depth, constraint_bounds) = match parent.payload.warrant_type { WarrantType::Execution => ( // POLA: Start empty, not with parent's tools BTreeMap::new(), None, None, ConstraintSet::new(), ), WarrantType::Issuer => ( BTreeMap::new(), // POLA: Start empty for issuable_tools too None, parent.payload.max_issue_depth, parent.payload.constraint_bounds.clone().unwrap_or_default(), ), }; // Inherit tenuo.approval_gates from parent let mut extensions = BTreeMap::new(); if let Some(gate_bytes) = parent .payload .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), gate_bytes.clone(), ); } Self { clearance: parent.payload.clearance, session_id: parent.payload.session_id.clone(), agent_id: parent.payload.agent_id.clone(), holder: Some(parent.payload.holder.clone()), required_approvers: parent.payload.required_approvers.clone(), min_approvals: parent.payload.min_approvals, parent, tools, inherited_all: false, issuable_tools, max_issue_depth, constraint_bounds, ttl: None, cap_ttl_to_parent: false, max_depth: None, intent: None, extensions, } } /// Inherit all capabilities from the parent warrant. /// /// This is an **explicit opt-in** to full inheritance. Use this when you /// want to start with all parent capabilities and then narrow specific ones. /// /// Without this, the builder follows POLA and starts empty. pub fn inherit_all(&mut self) { match self.parent.payload.warrant_type { WarrantType::Execution => { self.tools = self.parent.payload.tools.clone(); self.inherited_all = true; } WarrantType::Issuer => { self.issuable_tools = self.parent.payload.issuable_tools.clone(); } } } /// Get the configured tools. pub fn tools(&self) -> &BTreeMap { &self.tools } /// Get a reference to the parent warrant. pub fn parent(&self) -> &Warrant { &self.parent } /// Keep only the specified tool (remove others). pub fn retain_tool(&mut self, tool: &str) { self.tools.retain(|k, _| k == tool); self.inherited_all = false; } /// Compat alias pub fn retain_capability(&mut self, tool: &str) { self.retain_tool(tool) } /// Keep only the specified tools (remove others). pub fn retain_tools(&mut self, tools: &[String]) { self.tools.retain(|k, _| tools.contains(k)); self.inherited_all = false; } /// Compat alias pub fn retain_capabilities(&mut self, tools: &[String]) { self.retain_tools(tools) } /// Refuse the additive selection calls while `inherit_all()` is in effect. fn guard_additive_selection(&self) -> Result<()> { if self.inherited_all { return Err(Error::Validation( "tool()/tools() after inherit_all() would not narrow the selection: \ every parent tool is already selected. Use retain_tools([...]) to keep \ a subset, or drop inherit_all() and name the tools to add." .to_string(), )); } Ok(()) } /// The parent's constraint set for `tool`, honoring a parent `*` tool the /// same way authorization and attenuation validation do. fn parent_constraints_for(&self, tool: &str) -> Result { if self.parent.payload.warrant_type == WarrantType::Issuer { return Err(Error::Validation(format!( "tool '{}' cannot be selected on an issuer warrant: issuer warrants carry \ issuable_tools, not tools. Use with_issuable_tool()/issuable_tool().", tool ))); } self.parent .payload .tools .get(tool) .or_else(|| self.parent.payload.tools.get("*")) .cloned() .ok_or_else(|| { Error::MonotonicityViolation(format!("tool '{}' not in parent's tools", tool)) }) } /// Add a capability by inheriting its constraints from the parent warrant. /// /// This is the constraint-free selection path used by language bindings: /// naming a tool grants exactly the authority the parent has for that tool. /// A capability already selected, for example narrowed with /// `set_capability`, is kept as is; this call never widens an existing /// selection. After `inherit_all()` it is refused; use `retain_tools`. pub fn inherit_capability(&mut self, tool: &str) -> Result<()> { self.guard_additive_selection()?; let constraints = self.parent_constraints_for(tool)?; self.tools.entry(tool.to_string()).or_insert(constraints); Ok(()) } /// Add capabilities by inheriting each tool's constraints from the parent. /// /// Validation is atomic: if any requested tool is absent from the parent, /// no capabilities are added. Already-selected capabilities are kept as is. pub fn inherit_capabilities(&mut self, tools: &[String]) -> Result<()> { self.guard_additive_selection()?; let inherited = tools .iter() .map(|tool| { self.parent_constraints_for(tool) .map(|constraints| (tool.clone(), constraints)) }) .collect::>>()?; for (tool, constraints) in inherited { self.tools.entry(tool).or_insert(constraints); } Ok(()) } /// Get the configured TTL (if any). pub fn ttl_seconds(&self) -> Option { self.ttl.map(|d| d.as_secs()) } /// Get the configured holder (if any). pub fn get_holder(&self) -> Option<&PublicKey> { self.holder.as_ref() } /// Get the configured trust level. pub fn clearance(&self) -> Option { self.clearance } /// Get the configured intent. pub fn intent(&self) -> Option<&str> { self.intent.as_deref() } /// Add a tool description (tool + constraints) to the warrant. pub fn tool(mut self, tool: impl Into, constraints: impl Into) -> Self { self.tools.insert(tool.into(), constraints.into()); self } /// Compat alias pub fn capability( self, tool: impl Into, constraints: impl Into, ) -> Self { self.tool(tool, constraints) } /// Add a tool (mutable version for FFI). pub fn set_tool(&mut self, tool: impl Into, constraints: impl Into) { self.tools.insert(tool.into(), constraints.into()); } /// Compat alias pub fn set_capability( &mut self, tool: impl Into, constraints: impl Into, ) { self.set_tool(tool, constraints) } /// Set a shorter TTL. pub fn ttl(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self.cap_ttl_to_parent = false; self } /// Set TTL (mutable version for FFI). pub fn set_ttl(&mut self, ttl: Duration) { self.ttl = Some(ttl); self.cap_ttl_to_parent = false; } /// Set a TTL, shortening it atomically to the parent's expiry if needed. pub fn ttl_capped_to_parent(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self.cap_ttl_to_parent = true; self } /// Mutable variant of [`Self::ttl_capped_to_parent`] for FFI bindings. pub fn set_ttl_capped_to_parent(&mut self, ttl: Duration) { self.ttl = Some(ttl); self.cap_ttl_to_parent = true; } /// Set a lower maximum delegation depth. pub fn max_depth(mut self, max_depth: u32) -> Self { self.max_depth = Some(max_depth); self } /// Set max depth (mutable version for FFI). pub fn set_max_depth(&mut self, max_depth: u32) { self.max_depth = Some(max_depth); } /// Make this warrant terminal (cannot be delegated further). pub fn terminal(mut self) -> Self { self.max_depth = Some(self.parent.depth() + 1); self } /// Make this warrant terminal (mutable version for FFI). pub fn set_terminal(&mut self) { self.max_depth = Some(self.parent.depth() + 1); } /// Set or change the agent ID. pub fn agent_id(mut self, agent_id: impl Into) -> Self { self.agent_id = Some(agent_id.into()); self } /// Set or change the authorized holder. pub fn holder(mut self, public_key: PublicKey) -> Self { self.holder = Some(public_key); self } /// Set holder (mutable version for FFI). pub fn set_holder(&mut self, public_key: PublicKey) { self.holder = Some(public_key); } /// Set the clearance for the child warrant. pub fn set_clearance(&mut self, level: Clearance) { self.clearance = Some(level); } /// Set the intent/purpose for this delegation. pub fn set_intent(&mut self, intent: impl Into) { self.intent = Some(intent.into()); } /// Set a single tool for issuable_tools (for issuer warrants). pub fn issuable_tool(mut self, tool: impl Into) -> Self { self.issuable_tools = Some(vec![tool.into()]); self } /// Set a single tool (mutable version for FFI). pub fn set_issuable_tool(&mut self, tool: impl Into) { self.issuable_tools = Some(vec![tool.into()]); } /// Set multiple tools for issuable_tools (for issuer warrants). pub fn issuable_tools(mut self, tools: Vec) -> Self { self.issuable_tools = Some(tools); self } /// Set multiple tools (mutable version for FFI). pub fn set_issuable_tools(&mut self, tools: Vec) { self.issuable_tools = Some(tools); } /// Drop tools from issuable_tools (for issuer warrants). pub fn drop_issuable_tools(&mut self, tools_to_drop: Vec) { if let Some(current) = &mut self.issuable_tools { current.retain(|t| !tools_to_drop.contains(t)); } else if let Some(parent_tools) = &self.parent.payload.issuable_tools { // If not set, start with parent's tools and remove let mut current = parent_tools.clone(); current.retain(|t| !tools_to_drop.contains(t)); self.issuable_tools = Some(current); } } /// Add an extension. /// /// The `tenuo.approval_gates` key is system-managed and cannot be overwritten. pub fn extension(mut self, key: impl Into, value: Vec) -> Self { let key = key.into(); if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return self; } self.extensions.insert(key, value); self } /// Add extension (FFI). /// /// The `tenuo.approval_gates` key is system-managed and cannot be overwritten. pub fn add_extension(&mut self, key: String, value: Vec) { if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return; } self.extensions.insert(key, value); } /// Add or merge approval gate bytes into the `tenuo.approval_gates` extension. /// /// Merges with any inherited parent gates using union semantics /// (more-restrictive wins for conflicts). Scoping to child tools /// still happens during `build()` via `propagate_approval_gates`. pub fn set_approval_gates_extension(&mut self, bytes: Vec) -> Result<()> { let explicit = match crate::approval_gate::parse_approval_gate_map(Some(&bytes))? { Some(g) => g, None => return Ok(()), }; let merged = match self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { Some(existing) => { match crate::approval_gate::parse_approval_gate_map(Some(existing))? { Some(inherited) => { crate::approval_gate::merge_approval_gate_maps(&inherited, &explicit) } None => explicit, } } None => explicit, }; let encoded = crate::approval_gate::encode_approval_gate_map(&merged)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); Ok(()) } /// Add required approvers. pub fn add_approvers(mut self, approvers: Vec) -> Self { let mut current = self.required_approvers.unwrap_or_default(); for approver in approvers { if !current.contains(&approver) { current.push(approver); } } self.required_approvers = Some(current); self } /// Increase the minimum approvals required. pub fn raise_min_approvals(mut self, min: u32) -> Self { let current = self.min_approvals.unwrap_or(0); self.min_approvals = Some(min.max(current)); self } /// Compute the diff between parent and proposed child warrant. /// /// This can be used to preview what will change before calling `build()`. pub fn diff(&self) -> crate::diff::DelegationDiff { use crate::diff::{ConstraintDiff, DelegationDiff, DepthDiff, ToolsDiff, TtlDiff}; use chrono::Utc; use std::collections::HashMap; // Tools - for attenuation, tools stay the same or subset let parent_tools = self.parent.payload.tools.keys().cloned().collect(); // Child tools: keys of self.tools let mut child_tools: Vec = self.tools.keys().cloned().collect(); child_tools.sort(); let tools = ToolsDiff::new(parent_tools, child_tools.clone()); // Capabilities diff logic let mut capabilities: HashMap> = HashMap::new(); // iterate distinct tools from both let mut all_tools = child_tools.clone(); for tool in self.parent.payload.tools.keys() { if !all_tools.contains(tool) { all_tools.push(tool.clone()); } } all_tools.sort(); for tool in all_tools { let parent_constraints = self .parent .payload .tools .get(&tool) .cloned() .unwrap_or_default(); let child_constraints = self.tools.get(&tool).cloned().unwrap_or_default(); let mut tool_diffs = HashMap::new(); let mut all_fields: Vec = Vec::new(); for (field, _) in parent_constraints.iter() { all_fields.push(field.clone()); } for (field, _) in child_constraints.iter() { if !all_fields.contains(field) { all_fields.push(field.clone()); } } for field in all_fields { let pc = parent_constraints.get(&field).cloned(); let cc = child_constraints.get(&field).cloned(); tool_diffs.insert(field.clone(), ConstraintDiff::new(field, pc, cc)); } if !tool_diffs.is_empty() { capabilities.insert(tool, tool_diffs); } } // TTL let now = Utc::now(); let parent_remaining = (self.parent.expires_at() - now).num_seconds().max(0); let child_ttl = self.ttl.map(|d| d.as_secs() as i64); let ttl = TtlDiff::new(Some(parent_remaining), child_ttl); // Clearance let clearance = ClearanceDiff::new(self.parent.clearance(), self.clearance()); // Depth let depth = DepthDiff::new( self.parent.depth(), self.parent.depth() + 1, self.parent.max_depth(), ); DelegationDiff { parent_warrant_id: self.parent.id().to_string(), child_warrant_id: None, // Not yet built timestamp: Utc::now(), tools, capabilities, ttl, clearance, depth, intent: self.intent.clone(), } } /// Validate multi-sig monotonicity. fn validate_multisig_monotonicity(&self) -> Result<()> { check_approvers_under_unapprovable_gate( &self.parent, &approval_gate_scope( self.parent.payload.warrant_type, &self.tools, self.issuable_tools.as_ref(), ), self.required_approvers.as_ref(), )?; if let Some(parent_approvers) = &self.parent.payload.required_approvers { if let Some(child_approvers) = &self.required_approvers { for parent_key in parent_approvers { if !child_approvers.contains(parent_key) { return Err(Error::MonotonicityViolation(format!( "cannot remove approver {} from multi-sig set", hex::encode(parent_key.to_bytes()) ))); } } } else { return Err(Error::MonotonicityViolation( "cannot remove multi-sig requirement from parent".to_string(), )); } } if let Some(parent_min) = self.parent.payload.min_approvals { if let Some(child_min) = self.min_approvals { if child_min < parent_min { return Err(Error::MonotonicityViolation(format!( "cannot lower min_approvals from {} to {}", parent_min, child_min ))); } } } if let (Some(approvers), Some(min)) = (&self.required_approvers, self.min_approvals) { if min as usize > approvers.len() { return Err(Error::MonotonicityViolation(format!( "min_approvals ({}) cannot exceed required_approvers count ({})", min, approvers.len() ))); } } // An unset parent minimum still means every parent approver; each added // approver must also raise the effective threshold so a new key cannot // satisfy the quorum in place of a parent approver. let added = delegated_added_approvers(&self.parent, self.required_approvers.as_ref()); let base = self.parent.approval_threshold(); let threshold = approval_threshold( self.required_approvers.as_ref(), delegated_min_approvals( &self.parent, self.required_approvers.as_ref(), self.min_approvals, ), ); if threshold < base.saturating_add(added) { return Err(Error::MonotonicityViolation(threshold_violation( base, added, threshold, ))); } Ok(()) } /// Build and sign the attenuated warrant. /// /// Build and sign the attenuated warrant. /// /// The signing key must belong to the holder of the parent warrant. pub fn build(mut self, signing_key: &SigningKey) -> Result { // Canonicalize lists for deterministic serialization if let Some(tools) = &mut self.issuable_tools { tools.sort(); tools.dedup(); } if let Some(approvers) = &mut self.required_approvers { approvers.sort_by_key(|a| a.to_bytes()); approvers.dedup(); } // Delegation authority check: signer must be the parent's holder if signing_key.public_key() != *self.parent.authorized_holder() { return Err(Error::DelegationAuthorityError { expected: self.parent.authorized_holder().fingerprint(), actual: signing_key.public_key().fingerprint(), }); } let new_depth = self.parent.depth() + 1; let parent_max = self.parent.payload.max_depth as u32; let effective_max = match self.max_depth { Some(child_max) => { if child_max > parent_max { return Err(Error::MonotonicityViolation(format!( "max_depth {} exceeds parent's max_depth {}", child_max, parent_max ))); } Some(child_max) } None => Some(parent_max), }; let depth_limit = effective_max.unwrap_or(MAX_DELEGATION_DEPTH); if new_depth > depth_limit { return Err(Error::DepthExceeded(new_depth, depth_limit)); } if new_depth > MAX_DELEGATION_DEPTH { return Err(Error::DepthExceeded(new_depth, MAX_DELEGATION_DEPTH)); } if self.parent.is_expired() { use chrono::TimeZone; let expiry = Utc .timestamp_opt(self.parent.payload.expires_at as i64, 0) .single() .unwrap_or_else(Utc::now); return Err(Error::WarrantExpired { warrant_id: self.parent.id().to_string(), expired_at: expiry, }); } // Validate attenuation monotonicity match self.parent.payload.warrant_type { WarrantType::Execution => { // For execution warrants, validate tool attenuation let parent_tools = &self.parent.payload.tools; crate::constraints::validate_tool_map_attenuation( parent_tools, &self.tools, "tools", )?; if self.tools.is_empty() { return Err(Error::Validation( "execution warrant must have at least one tool".to_string(), )); } // Clearance monotonicity: child cannot exceed parent, and cannot // introduce a clearance claim that the parent never established. if let Some(child_clearance) = self.clearance { match self.parent.payload.clearance { Some(parent_clearance) => { if child_clearance > parent_clearance { return Err(Error::MonotonicityViolation(format!( "clearance cannot increase: parent {:?}, child {:?}", parent_clearance, child_clearance ))); } } None => { return Err(Error::MonotonicityViolation(format!( "cannot introduce clearance {:?} in child when parent has none", child_clearance ))); } } } } WarrantType::Issuer => { validate_clearance_attenuation(self.parent.payload.clearance, self.clearance)?; if let Some(parent_issuable) = &self.parent.payload.issuable_tools { if let Some(ref child_issuable) = self.issuable_tools { for tool in child_issuable { if !parent_issuable.iter().any(|t| t == tool || t == "*") { return Err(Error::MonotonicityViolation(format!( "issuable_tool '{}' not in parent's issuable_tools", tool ))); } } } } if let Some(parent_bounds) = &self.parent.payload.constraint_bounds { parent_bounds.validate_attenuation(&self.constraint_bounds)?; } } } // Propagate approval gates: scope inherited gate map to the child's tool set. if let Some(gate_bytes) = self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) .cloned() { let parent_gates = crate::approval_gate::parse_approval_gate_map(Some(&gate_bytes))?; if let Some(parent_gates) = parent_gates { match crate::approval_gate::propagate_approval_gates( &parent_gates, &approval_gate_scope( self.parent.payload.warrant_type, &self.tools, self.issuable_tools.as_ref(), ), ) { Some(scoped) => { let encoded = crate::approval_gate::encode_approval_gate_map(&scoped)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); } None => { // No gate survives: inherited approvers have nothing to // approve. Approvers set on this builder would be lost. if canonical_approvers(self.required_approvers.as_ref()) != canonical_approvers(self.parent.payload.required_approvers.as_ref()) || self.min_approvals != self.parent.payload.min_approvals { return Err(Error::Validation( "required_approvers requires an approval gate map".to_string(), )); } self.extensions .remove(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY); self.required_approvers = None; self.min_approvals = None; } } } } if self .extensions .contains_key(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) || self.required_approvers.is_some() { self.validate_multisig_monotonicity()?; } // Defense-in-depth: verify the final child gate map is monotonically // at least as strict as the parent's gates. This catches any code path // that bypassed `set_approval_gates_extension` (e.g. raw `add_extension` calls) // and accidentally weakened a gate. { let parent_gate_bytes = self .parent .extension(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY); let parent_gates = crate::approval_gate::parse_approval_gate_map(parent_gate_bytes)?; let child_gate_bytes = self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY); let child_gates = crate::approval_gate::parse_approval_gate_map(child_gate_bytes)?; crate::approval_gate::verify_approval_gate_monotonicity( parent_gates.as_ref(), child_gates.as_ref(), &approval_gate_scope( self.parent.payload.warrant_type, &self.tools, self.issuable_tools.as_ref(), ), ) .map_err(|e| Error::Validation(format!("approval gate monotonicity violation: {e}")))?; } let holder = self .holder .ok_or_else(|| Error::Validation("holder is required".to_string()))?; // NOTE: Holder cycling (A → B → A) is NOT blocked let now_sec = Utc::now().timestamp() as u64; let expires_at = if let Some(ttl) = self.ttl { let chrono_ttl = ChronoDuration::from_std(ttl) .map_err(|_| Error::InvalidTtl("TTL too large".to_string()))?; if self.cap_ttl_to_parent { child_expiry_capped_to_parent( now_sec, chrono_ttl.num_seconds() as u64, self.parent.payload.expires_at, ) } else { child_expiry_within_parent( now_sec, chrono_ttl.num_seconds() as u64, self.parent.payload.expires_at, )? } } else { self.parent.payload.expires_at }; let effective_min = if self.required_approvers.is_some() { delegated_min_approvals( &self.parent, self.required_approvers.as_ref(), self.min_approvals, ) } else { None }; let payload = WarrantPayload { version: WARRANT_VERSION as u8, warrant_type: self.parent.payload.warrant_type, id: WarrantId::new(), holder, tools: self.tools, issuable_tools: match self.parent.payload.warrant_type { WarrantType::Issuer => self.issuable_tools.clone(), WarrantType::Execution => None, }, max_issue_depth: match self.parent.payload.warrant_type { WarrantType::Issuer => self.max_issue_depth, WarrantType::Execution => None, }, constraint_bounds: match self.parent.payload.warrant_type { WarrantType::Issuer => { if self.constraint_bounds.is_empty() { None } else { Some(self.constraint_bounds) } } WarrantType::Execution => None, }, clearance: self.clearance, issued_at: now_sec, expires_at, max_depth: effective_max.unwrap_or(MAX_DELEGATION_DEPTH) as u8, depth: self.parent.depth() + 1, // Increment depth from parent session_id: self.session_id, agent_id: self.agent_id, issuer: signing_key.public_key(), parent_hash: { use sha2::{Digest, Sha256}; let mut hasher = Sha256::new(); hasher.update(&self.parent.payload_bytes); Some(hasher.finalize().into()) }, required_approvers: self.required_approvers, min_approvals: effective_min, extensions: self.extensions, }; if payload.warrant_type == WarrantType::Issuer && !payload.tools.is_empty() { return Err(Error::InvalidWarrantType { message: "issuer warrant cannot have tools".to_string(), }); } let mut payload_bytes = Vec::new(); ciborium::ser::into_writer(&payload, &mut payload_bytes) .map_err(|e| Error::SerializationError(e.to_string()))?; // Preimage: envelope_version || payload_bytes let mut preimage = Vec::with_capacity(1 + payload_bytes.len()); preimage.push(1); // envelope_version preimage.extend_from_slice(&payload_bytes); let signature = signing_key.sign(&preimage); Ok(Warrant { payload, signature, payload_bytes, envelope_version: 1, }) } /// Build and sign the attenuated warrant, returning both warrant and receipt. /// /// The signing key must belong to the holder of the parent warrant. pub fn build_with_receipt( self, signing_key: &SigningKey, ) -> Result<(Warrant, crate::diff::DelegationReceipt)> { // Capture diff before build consumes self let mut diff = self.diff(); // Get fingerprints before build let delegator_fingerprint = signing_key.public_key().fingerprint(); let delegatee_fingerprint = self .get_holder() .map(|h| h.fingerprint()) .unwrap_or_else(|| signing_key.public_key().fingerprint()); // Build the warrant let child = self.build(signing_key)?; // Update diff with child warrant ID diff.child_warrant_id = Some(child.id().to_string()); // Create receipt from diff let receipt = crate::diff::DelegationReceipt::from_diff( diff, child.id().to_string(), delegator_fingerprint, delegatee_fingerprint, ); Ok((child, receipt)) } } /// Builder for issuing execution warrants from issuer warrants. /// /// This builder validates that the issued execution warrant complies with /// the issuer warrant's constraints: /// - Tool must be in `issuable_tools` /// - Clearance must be <= issuer's clearance (monotonicity) /// - Constraints must be within `constraint_bounds` /// - Depth must not exceed `max_issue_depth` #[derive(Debug)] pub struct IssuanceBuilder<'a> { issuer: &'a Warrant, tools: BTreeMap, clearance: Option, ttl: Option, max_depth: Option, session_id: Option, agent_id: Option, holder: Option, required_approvers: Option>, min_approvals: Option, extensions: BTreeMap>, } impl<'a> IssuanceBuilder<'a> { /// Create a new issuance builder. /// /// Inherits `tenuo.approval_gates` from the issuer warrant as a template — /// approval gates propagate to issued execution warrants. fn new(issuer: &'a Warrant) -> Self { let mut extensions = BTreeMap::new(); if let Some(gate_bytes) = issuer .payload .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), gate_bytes.clone(), ); } Self { issuer, tools: BTreeMap::new(), clearance: None, ttl: None, max_depth: None, session_id: issuer.payload.session_id.clone(), agent_id: issuer.payload.agent_id.clone(), holder: None, required_approvers: None, min_approvals: None, extensions, } } /// Add a tool to the execution warrant. /// /// The tool must be in the issuer's `issuable_tools` list. /// The constraint must be within the issuer's `constraint_bounds`. pub fn tool(mut self, tool: impl Into, constraints: impl Into) -> Self { self.tools.insert(tool.into(), constraints.into()); self } /// Compat alias pub fn capability( self, tool: impl Into, constraints: impl Into, ) -> Self { self.tool(tool, constraints) } /// Set the clearance (optional). pub fn clearance(mut self, clearance: Clearance) -> Self { self.clearance = Some(clearance); self } /// Set the time-to-live for the execution warrant. pub fn ttl(mut self, ttl: Duration) -> Self { self.ttl = Some(ttl); self } /// Set the maximum delegation depth for the execution warrant. /// /// This must not exceed the issuer's `max_issue_depth`. pub fn max_depth(mut self, max_depth: u32) -> Self { self.max_depth = Some(max_depth); self } /// Set the session ID. pub fn session_id(mut self, session_id: impl Into) -> Self { self.session_id = Some(session_id.into()); self } /// Set the agent ID. pub fn agent_id(mut self, agent_id: impl Into) -> Self { self.agent_id = Some(agent_id.into()); self } /// Set the holder (Proof-of-Possession). /// /// This is required - the execution warrant must have a holder. pub fn holder(mut self, public_key: PublicKey) -> Self { self.holder = Some(public_key); self } /// Set required approvers for multi-sig workflows. pub fn required_approvers(mut self, approvers: Vec) -> Self { self.required_approvers = Some(approvers); self } /// Set the minimum number of approvals required. pub fn min_approvals(mut self, min: u32) -> Self { self.min_approvals = Some(min); self } /// Add an extension. /// /// The `tenuo.approval_gates` key is system-managed and cannot be overwritten. pub fn extension(mut self, key: impl Into, value: Vec) -> Self { let key = key.into(); if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return self; } self.extensions.insert(key, value); self } /// Add or merge approval gates for the execution warrant being issued. /// /// Inherited issuer gates are retained; explicit gates can only add a /// whole-tool gate or additional per-argument triggers. pub fn set_approval_gates_extension(&mut self, bytes: Vec) -> Result<()> { let explicit = match crate::approval_gate::parse_approval_gate_map(Some(&bytes))? { Some(gates) => gates, None => return Ok(()), }; let merged = match self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { Some(existing) => { match crate::approval_gate::parse_approval_gate_map(Some(existing))? { Some(inherited) => { crate::approval_gate::merge_approval_gate_maps(&inherited, &explicit) } None => explicit, } } None => explicit, }; let encoded = crate::approval_gate::encode_approval_gate_map(&merged)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); Ok(()) } /// Build and sign the execution warrant. /// /// This validates: /// - Tool is in issuer's `issuable_tools` /// - Clearance <= issuer's clearance (monotonicity) /// - Constraints are within issuer's `constraint_bounds` /// - Depth doesn't exceed issuer's `max_issue_depth` /// - Signing key matches issuer warrant's holder (delegation authority) /// /// # Arguments /// /// * `signing_key` - The keypair of the issuer warrant holder (the delegator) pub fn build(mut self, signing_key: &SigningKey) -> Result { // Canonicalize lists for deterministic serialization // Note: IssuanceBuilder only creates execution warrants, so no issuable_tools if let Some(approvers) = &mut self.required_approvers { approvers.sort_by_key(|a| a.to_bytes()); approvers.dedup(); } // Delegation authority check: signer must be the issuer warrant's holder if signing_key.public_key() != *self.issuer.authorized_holder() { return Err(Error::DelegationAuthorityError { expected: self.issuer.authorized_holder().fingerprint(), actual: signing_key.public_key().fingerprint(), }); } // Validate issuer is not expired if self.issuer.is_expired() { use chrono::TimeZone; let expiry = Utc .timestamp_opt(self.issuer.payload.expires_at as i64, 0) .single() .unwrap_or_else(Utc::now); return Err(Error::WarrantExpired { warrant_id: self.issuer.id().to_string(), expired_at: expiry, }); } // Validate required fields if self.tools.is_empty() { return Err(Error::Validation( "execution warrant requires at least one tool".to_string(), )); } // Validate each tool against issuer constraints if let Some(issuable_tools) = &self.issuer.payload.issuable_tools { for (tool, constraints) in &self.tools { // 1. Tool must be issuable if !issuable_tools.iter().any(|t| t == tool || t == "*") { return Err(Error::Validation(format!( "tool '{}' is not in issuer's issuable_tools", tool ))); } // 2. Constraints must be within bounds if let Some(bounds) = &self.issuer.payload.constraint_bounds { bounds.validate_attenuation(constraints)?; } } } else { return Err(Error::InvalidWarrantType { message: "issuer warrant requires at least one issuable_tool".to_string(), }); } let holder = self.holder.ok_or(Error::Validation( "execution warrant requires holder".to_string(), ))?; let ttl = self.ttl.ok_or(Error::MissingField("ttl".to_string()))?; // SECURITY: Issuer cannot grant execution warrants to themselves // This prevents privilege escalation where an issuer could convert their // issuer warrant into execution capabilities for themselves. if holder == self.issuer.payload.holder { return Err(Error::SelfIssuanceProhibited { reason: "issuer cannot grant execution warrants to themselves".to_string(), }); } // SECURITY: Execution warrant holder cannot be the issuer warrant's issuer // This prevents a more subtle privilege escalation where the issuer warrant's // issuer could indirectly grant execution capabilities to themselves through // the issuer warrant mechanism. if holder == self.issuer.payload.issuer { return Err(Error::SelfIssuanceProhibited { reason: "execution warrant holder cannot be the issuer warrant's issuer (issuer-holder separation required)".to_string(), }); } // Validate all tools are in issuable_tools if let Some(issuable_tools) = &self.issuer.payload.issuable_tools { for tool in self.tools.keys() { if !issuable_tools.iter().any(|t| t == tool || t == "*") { return Err(Error::UnauthorizedToolIssuance { tool: tool.clone(), allowed: issuable_tools.clone(), }); } } } else { return Err(Error::InvalidWarrantType { message: "issuer warrant requires at least one issuable_tool".to_string(), }); } // Clearance monotonicity: issued warrant cannot exceed issuer's clearance, and // cannot introduce a clearance claim the issuer warrant never established. if let Some(clearance) = self.clearance { match self.issuer.payload.clearance { Some(issuer_clearance) => { if clearance > issuer_clearance { return Err(Error::ClearanceLevelExceeded { requested: format!("{:?}", clearance), limit: format!("{:?}", issuer_clearance), }); } } None => { return Err(Error::MonotonicityViolation(format!( "cannot introduce clearance {:?} when issuer has none", clearance ))); } } } // Validate tool constraints are within constraint_bounds if let Some(constraint_bounds) = &self.issuer.payload.constraint_bounds { if !constraint_bounds.is_empty() { for (tool, constraints) in self.tools.iter() { for (field, constraint) in constraints.iter() { if let Some(bound) = constraint_bounds.get(field) { // Validate that the constraint is within the bound using attenuation validation bound.validate_attenuation(constraint).map_err(|e| { Error::Validation(format!( "constraint for tool '{}' field '{}' exceeds issuer's constraint_bounds: {}", tool, field, e )) })?; } } } } } // Validate depth doesn't exceed max_issue_depth let new_depth = self.issuer.depth() + 1; if let Some(max_issue_depth) = self.issuer.payload.max_issue_depth { if new_depth > max_issue_depth { return Err(Error::IssueDepthExceeded { depth: new_depth, max: max_issue_depth, }); } } // Validate max_depth doesn't exceed issuer's max_issue_depth if let Some(max_depth) = self.max_depth { if let Some(max_issue_depth) = self.issuer.payload.max_issue_depth { if max_depth > max_issue_depth { return Err(Error::IssueDepthExceeded { depth: max_depth, max: max_issue_depth, }); } } } // Validate tool validation depth for constraints in self.tools.values() { constraints.validate_depth()?; } // Propagate approval gates from issuer template, scoped to issued tools. if let Some(gate_bytes) = self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) .cloned() { let parent_gates = crate::approval_gate::parse_approval_gate_map(Some(&gate_bytes))?; if let Some(parent_gates) = parent_gates { match crate::approval_gate::propagate_approval_gates(&parent_gates, &self.tools) { Some(scoped) => { let encoded = crate::approval_gate::encode_approval_gate_map(&scoped)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); } None => { self.extensions .remove(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY); } } } } // The issuer's approvers and threshold are part of its approval template: // wherever a gate survives scoping, the issued warrant keeps them. Issuance // may add approvers or raise the threshold, never remove or lower them. if self .extensions .contains_key(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { if let Some(issuer_approvers) = &self.issuer.payload.required_approvers { match &self.required_approvers { None => self.required_approvers = Some(issuer_approvers.clone()), Some(approvers) => { for key in issuer_approvers { if !approvers.contains(key) { return Err(Error::MonotonicityViolation(format!( "cannot remove issuer approver {}", hex::encode(key.to_bytes()) ))); } } } } } let added = match ( self.issuer.payload.required_approvers.as_deref(), self.required_approvers.as_deref(), ) { (Some(p), Some(c)) => added_approver_count(p, c), _ => 0, }; if let Some(issuer_min) = self.issuer.payload.min_approvals { match self.min_approvals { None => self.min_approvals = Some(issuer_min.saturating_add(added)), Some(min) if min < issuer_min => { return Err(Error::MonotonicityViolation(format!( "cannot lower min_approvals from {} to {}", issuer_min, min ))); } Some(_) => {} } } // An unset issuer minimum still means every issuer approver; each added // approver must also raise the effective threshold so a new key cannot // satisfy the quorum in place of an issuer approver. let required_threshold = self.issuer.approval_threshold().saturating_add(added); let threshold = approval_threshold(self.required_approvers.as_ref(), self.min_approvals); if threshold < required_threshold { return Err(Error::MonotonicityViolation(threshold_violation( self.issuer.approval_threshold(), added, threshold, ))); } } check_approvers_under_unapprovable_gate( self.issuer, &self.tools, self.required_approvers.as_ref(), )?; // Validate min_approvals if set if let (Some(approvers), Some(min)) = (&self.required_approvers, self.min_approvals) { if min as usize > approvers.len() { return Err(Error::Validation(format!( "min_approvals ({}) cannot exceed required_approvers count ({})", min, approvers.len() ))); } } // Approver metadata without an approval gate is permissive at // authorization time. Reject that shape so an issuance API can never // appear gated while silently allowing every call. if self .required_approvers .as_ref() .is_some_and(|approvers| !approvers.is_empty()) && !self .extensions .contains_key(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { return Err(Error::Validation( "required_approvers requires an approval gate map".to_string(), )); } // Validate extensions if self.extensions.len() > MAX_EXTENSION_KEYS { return Err(Error::Validation(format!( "extensions count {} exceeds limit {}", self.extensions.len(), MAX_EXTENSION_KEYS ))); } for (key, val) in &self.extensions { if key.len() > MAX_EXTENSION_KEY_SIZE { return Err(Error::Validation(format!( "extension key '{}...' length {} exceeds limit {}", key.chars().take(KEY_DISPLAY_TRUNCATION).collect::(), key.len(), MAX_EXTENSION_KEY_SIZE ))); } if val.len() > MAX_EXTENSION_VALUE_SIZE { return Err(Error::Validation(format!( "extension '{}' value size {} exceeds limit {}", key, val.len(), MAX_EXTENSION_VALUE_SIZE ))); } } let chrono_ttl = ChronoDuration::from_std(ttl) .map_err(|_| Error::InvalidTtl("TTL too large".to_string()))?; let now_sec = Utc::now().timestamp() as u64; let expires_at = child_expiry_within_parent( now_sec, chrono_ttl.num_seconds() as u64, self.issuer.payload.expires_at, )?; // Effective max depth: logic needs to align with requirement for concrete u8 // If max_depth not set, inherit or default? // Spec implies max_depth is mandatory on wire. // For issuance, we're creating a NEW warrant. // Logic: use configured max_depth, or if None, use parent's (if restricted), or default MAX. // But invalid types: self.issuer.payload.max_depth is u8. self.max_depth is Option. let effective_max_u8 = if let Some(configured) = self.max_depth { if configured > 255 { return Err(Error::Validation("max_depth exceeds u8 range".to_string())); } configured as u8 } else { // Inherit from parent? Or default? // Since this is issuance (creation of EXECUTION warrant), typically we set strict limits. // If parent has a max_depth (u8), we should probably use that or less. // self.issuer.payload.max_depth is the limit of the ISSUER warrant itself. // That limit applies to the DELEGATION chain length. self.issuer.payload.max_depth }; let payload = WarrantPayload { version: WARRANT_VERSION as u8, warrant_type: WarrantType::Execution, id: WarrantId::new(), holder, tools: self.tools, issuable_tools: None, max_issue_depth: None, constraint_bounds: None, clearance: self.clearance, issued_at: now_sec, expires_at, max_depth: effective_max_u8, depth: self.issuer.depth() + 1, // Increment depth from issuer session_id: self.session_id, agent_id: self.agent_id, issuer: signing_key.public_key(), parent_hash: { use sha2::{Digest, Sha256}; let mut hasher = Sha256::new(); hasher.update(&self.issuer.payload_bytes); Some(hasher.finalize().into()) }, required_approvers: self.required_approvers, min_approvals: self.min_approvals, extensions: self.extensions, }; // Serialize payload to sign it let mut payload_bytes = Vec::new(); ciborium::ser::into_writer(&payload, &mut payload_bytes) .map_err(|e| Error::SerializationError(e.to_string()))?; // Preimage: envelope_version || payload_bytes let mut preimage = Vec::with_capacity(1 + payload_bytes.len()); preimage.push(1); // envelope_version preimage.extend_from_slice(&payload_bytes); let signature = signing_key.sign(&preimage); let warrant = Warrant { payload, signature, payload_bytes, envelope_version: 1, }; // Audit: Log warrant issuance from issuer warrant let tools_list: Vec = warrant.payload.tools.keys().cloned().collect(); log_event(AuditEvent { id: Uuid::new_v4().to_string(), event_type: AuditEventType::WarrantIssued, timestamp: Utc::now(), provider: "tenuo".to_string(), external_id: None, public_key_hex: Some(hex::encode(signing_key.public_key().to_bytes())), actor: format!("issuer_warrant:{}", &self.issuer.id().to_string()[..8]), details: Some(format!( "execution warrant issued from issuer: tools={:?}, depth={}, issuer_id={}", tools_list, warrant.depth(), self.issuer.id() )), related_ids: Some(vec![warrant.id().to_string(), self.issuer.id().to_string()]), }); Ok(warrant) } } /// Owned version of IssuanceBuilder for use in FFI contexts (e.g., Python bindings). /// /// This builder owns the issuer warrant, avoiding lifetime issues in FFI. #[derive(Debug, Clone)] pub struct OwnedIssuanceBuilder { issuer: Warrant, tools: BTreeMap, clearance: Option, ttl: Option, max_depth: Option, session_id: Option, agent_id: Option, holder: Option, required_approvers: Option>, min_approvals: Option, intent: Option, extensions: BTreeMap>, } impl OwnedIssuanceBuilder { /// Create a new owned issuance builder. /// /// Inherits `tenuo.approval_gates` from the issuer warrant as a template. pub fn new(issuer: Warrant) -> Self { let mut extensions = BTreeMap::new(); if let Some(gate_bytes) = issuer .payload .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), gate_bytes.clone(), ); } Self { session_id: issuer.payload.session_id.clone(), agent_id: issuer.payload.agent_id.clone(), issuer, tools: BTreeMap::new(), clearance: None, ttl: None, max_depth: None, holder: None, required_approvers: None, min_approvals: None, intent: None, extensions, } } /// Get a reference to the issuer warrant. pub fn issuer(&self) -> &Warrant { &self.issuer } /// Get the configured tools. pub fn tools(&self) -> &BTreeMap { &self.tools } /// Get the configured holder. pub fn holder(&self) -> Option<&PublicKey> { self.holder.as_ref() } /// Get the configured trust level. pub fn clearance(&self) -> Option { self.clearance } /// Get the configured TTL. pub fn ttl_seconds(&self) -> Option { self.ttl.map(|d| d.as_secs()) } /// Get the configured max depth. pub fn max_depth(&self) -> Option { self.max_depth } /// Get the configured session ID. pub fn session_id(&self) -> Option<&str> { self.session_id.as_deref() } /// Get the configured agent ID. pub fn agent_id(&self) -> Option<&str> { self.agent_id.as_deref() } /// Get the configured minimum approvals. pub fn min_approvals(&self) -> Option { self.min_approvals } /// Get the configured required approvers. pub fn required_approvers(&self) -> Option<&[PublicKey]> { self.required_approvers.as_deref() } /// Get the configured intent. pub fn intent(&self) -> Option<&str> { self.intent.as_deref() } /// Add a tool description (tool + constraints) to the warrant (mutable version for FFI). pub fn set_tool(&mut self, tool: impl Into, constraints: impl Into) { self.tools.insert(tool.into(), constraints.into()); } /// Compat alias pub fn set_capability( &mut self, tool: impl Into, constraints: impl Into, ) { self.set_tool(tool, constraints) } /// Add a tool (builder pattern). pub fn tool(mut self, tool: impl Into, constraints: impl Into) -> Self { self.tools.insert(tool.into(), constraints.into()); self } /// Compat alias pub fn capability( self, tool: impl Into, constraints: impl Into, ) -> Self { self.tool(tool, constraints) } /// Set the clearance (mutable version for FFI). pub fn set_clearance(&mut self, level: Clearance) { self.clearance = Some(level); } /// Set TTL (mutable version for FFI). pub fn set_ttl(&mut self, ttl: Duration) { self.ttl = Some(ttl); } /// Set the maximum delegation depth (mutable version for FFI). pub fn set_max_depth(&mut self, max_depth: u32) { self.max_depth = Some(max_depth); } /// Make this warrant terminal (cannot be delegated further). pub fn terminal(mut self) -> Self { self.max_depth = Some(self.issuer.depth() + 1); self } /// Make this warrant terminal (mutable version for FFI). pub fn set_terminal(&mut self) { self.max_depth = Some(self.issuer.depth() + 1); } /// Set the session ID (mutable version for FFI). pub fn set_session_id(&mut self, session_id: impl Into) { self.session_id = Some(session_id.into()); } /// Set the agent ID (mutable version for FFI). pub fn set_agent_id(&mut self, agent_id: impl Into) { self.agent_id = Some(agent_id.into()); } /// Set the holder (mutable version for FFI). pub fn set_holder(&mut self, public_key: PublicKey) { self.holder = Some(public_key); } /// Get the holder. pub fn get_holder(&self) -> Option<&PublicKey> { self.holder.as_ref() } /// Set required approvers (mutable version for FFI). pub fn set_required_approvers(&mut self, approvers: Vec) { self.required_approvers = Some(approvers); } /// Set minimum approvals (mutable version for FFI). pub fn set_min_approvals(&mut self, min: u32) { self.min_approvals = Some(min); } /// Set the intent/purpose for this issuance (mutable version for FFI). pub fn set_intent(&mut self, intent: impl Into) { self.intent = Some(intent.into()); } /// Add extension (FFI). /// /// The `tenuo.approval_gates` key is system-managed and cannot be overwritten. pub fn add_extension(&mut self, key: String, value: Vec) { if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return; } self.extensions.insert(key, value); } /// Add or merge approval gate bytes into the `tenuo.approval_gates` extension. /// /// Merges with any inherited parent gates using union semantics /// (more-restrictive wins for conflicts). Scoping to child tools /// still happens during `build()` via `propagate_approval_gates`. pub fn set_approval_gates_extension(&mut self, bytes: Vec) -> Result<()> { let explicit = match crate::approval_gate::parse_approval_gate_map(Some(&bytes))? { Some(g) => g, None => return Ok(()), }; let merged = match self .extensions .get(crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY) { Some(existing) => { match crate::approval_gate::parse_approval_gate_map(Some(existing))? { Some(inherited) => { crate::approval_gate::merge_approval_gate_maps(&inherited, &explicit) } None => explicit, } } None => explicit, }; let encoded = crate::approval_gate::encode_approval_gate_map(&merged)?; self.extensions.insert( crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY.to_string(), encoded, ); Ok(()) } /// Add an extension. /// /// The `tenuo.approval_gates` key is system-managed and cannot be overwritten. pub fn extension(mut self, key: impl Into, value: Vec) -> Self { let key = key.into(); if key == crate::approval_gate::APPROVAL_GATE_EXTENSION_KEY { return self; } self.extensions.insert(key, value); self } /// Build and sign the execution warrant. /// /// The signing key must belong to the holder of the issuer warrant. pub fn build(self, signing_key: &SigningKey) -> Result { // Delegate to IssuanceBuilder IssuanceBuilder { issuer: &self.issuer, tools: self.tools, clearance: self.clearance, ttl: self.ttl, max_depth: self.max_depth, session_id: self.session_id, agent_id: self.agent_id, holder: self.holder, required_approvers: self.required_approvers, min_approvals: self.min_approvals, extensions: self.extensions, } .build(signing_key) } } #[cfg(test)] mod tests { use super::*; use crate::constraints::{Exact, Pattern, Range}; fn create_test_keypair() -> SigningKey { SigningKey::generate() } #[test] fn test_warrant_creation() { let keypair = create_test_keypair(); let mut constraints = ConstraintSet::new(); constraints.insert("cluster", Pattern::new("staging-*").unwrap()); let warrant = Warrant::builder() .tool("upgrade_cluster", constraints) .ttl(Duration::from_secs(600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let caps = warrant.capabilities().unwrap(); assert!(caps.contains_key("upgrade_cluster")); assert_eq!(warrant.depth(), 0); assert!(warrant.is_root()); assert!(!warrant.is_expired()); } #[test] fn test_decoded_future_warrant_cannot_authorize_standalone() { // Decoding is clock-neutral, so the standalone authorize path must // reject a correctly signed warrant dated beyond the default skew. let keypair = create_test_keypair(); let args = HashMap::new(); for (offset, accepted) in [(3600, false), (10, true)] { let mut warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let now = Utc::now().timestamp() as u64; warrant.payload.issued_at = now + offset; warrant.payload.expires_at = now + offset + 300; warrant.payload_bytes = crate::wire::to_vec(&warrant.payload).unwrap(); warrant.signature = keypair.sign_raw(&warrant.signed_message()); let decoded = crate::wire::decode(&crate::wire::encode(&warrant).unwrap()).unwrap(); decoded.verify(&keypair.public_key()).unwrap(); let pop = decoded.sign(&keypair, "test", &args).unwrap(); let result = decoded.authorize("test", &args, Some(&pop)); if accepted { assert!(result.is_ok(), "issued {offset}s ahead: {result:?}"); } else { assert!(matches!(result, Err(Error::IssuedInFuture)), "{result:?}"); } } } #[test] fn test_issued_in_future_rejection() { let keypair = create_test_keypair(); let mut warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); // Manipulate timestamps to simulate future issuance // Use a time far in the future > 30s skew let future = Utc::now().timestamp() as u64 + 3600; warrant.payload.issued_at = future; warrant.payload.expires_at = future + 300; // Validation must fail match warrant.validate() { Err(Error::IssuedInFuture) => (), res => panic!("Expected IssuedInFuture error, got {:?}", res), } // Also verify strict expiration (expires_at > issued_at) let now = Utc::now().timestamp() as u64; warrant.payload.issued_at = now; warrant.payload.expires_at = now; // Equal, should fail match warrant.validate() { Err(Error::Validation(msg)) if msg.contains("strictly greater") => (), res => panic!("Expected strict expiry error, got {:?}", res), } } #[test] fn test_warrant_verification() { let keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); assert!(warrant.verify(&keypair.public_key()).is_ok()); let other_keypair = create_test_keypair(); assert!(warrant.verify(&other_keypair.public_key()).is_err()); } #[test] fn test_warrant_authorization() { let keypair = create_test_keypair(); let mut constraints = ConstraintSet::new(); constraints.insert("cluster", Pattern::new("staging-*").unwrap()); constraints.insert("version", Pattern::new("1.28.*").unwrap()); let warrant = Warrant::builder() .tool("upgrade_cluster", constraints) .ttl(Duration::from_secs(600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let mut args = HashMap::new(); args.insert( "cluster".to_string(), ConstraintValue::String("staging-web".to_string()), ); args.insert( "version".to_string(), ConstraintValue::String("1.28.5".to_string()), ); // Create PoP signature (mandatory now) let pop_sig = warrant.sign(&keypair, "upgrade_cluster", &args).unwrap(); assert!(warrant .authorize("upgrade_cluster", &args, Some(&pop_sig)) .is_ok()); // Wrong tool assert!(warrant .authorize("delete_cluster", &args, Some(&pop_sig)) .is_err()); // Wrong cluster let mut bad_args = args.clone(); bad_args.insert( "cluster".to_string(), ConstraintValue::String("production-web".to_string()), ); assert!(warrant .authorize("upgrade_cluster", &bad_args, Some(&pop_sig)) .is_err()); } #[test] fn test_attenuation_basic() { let parent_keypair = create_test_keypair(); let _child_keypair = create_test_keypair(); // Unused with new delegation API let mut parent_constraints = ConstraintSet::new(); parent_constraints.insert("cluster", Pattern::new("staging-*").unwrap()); let parent = Warrant::builder() .tool("upgrade_cluster", parent_constraints) .ttl(Duration::from_secs(600)) .holder(parent_keypair.public_key()) .build(&parent_keypair) .unwrap(); let mut child_constraints = ConstraintSet::new(); child_constraints.insert("cluster", Exact::new("staging-web")); let child = parent .attenuate() .tool("upgrade_cluster", child_constraints) .build(&parent_keypair) // parent_keypair is parent's holder .unwrap(); assert_eq!(child.depth(), 1); use sha2::{Digest, Sha256}; let mut hasher = Sha256::new(); hasher.update(parent.payload_bytes()); let parent_hash: [u8; 32] = hasher.finalize().into(); assert_eq!(child.parent_hash(), Some(&parent_hash)); assert!(child.expires_at() <= parent.expires_at()); } #[test] fn test_attenuation_monotonicity_enforced() { let parent_keypair = create_test_keypair(); let _child_keypair = create_test_keypair(); // Unused with new delegation API let mut parent_constraints = ConstraintSet::new(); parent_constraints.insert("cluster", Pattern::new("staging-*").unwrap()); let parent = Warrant::builder() .tool("upgrade_cluster", parent_constraints) .ttl(Duration::from_secs(600)) .holder(parent_keypair.public_key()) .build(&parent_keypair) .unwrap(); // Attempt to widen scope - should fail let mut child_constraints = ConstraintSet::new(); child_constraints.insert("cluster", Pattern::new("*").unwrap()); let result = parent .attenuate() .tool("upgrade_cluster", child_constraints) .build(&parent_keypair); // parent_keypair is parent's holder assert!(result.is_err()); match result.unwrap_err() { Error::PatternExpanded { parent: p, child: c, } => { assert_eq!(p, "staging-*"); assert_eq!(c, "*"); } e => panic!("Expected PatternExpanded, got {:?}", e), } } #[test] fn test_attenuation_ttl_cannot_exceed_parent() { let parent_keypair = create_test_keypair(); let _child_keypair = create_test_keypair(); // Unused with new delegation API let parent = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .holder(parent_keypair.public_key()) .build(&parent_keypair) .unwrap(); // Requesting a longer TTL than the parent has left is a widening attempt. let result = parent .attenuate() .inherit_all() // POLA: explicitly inherit all capabilities .ttl(Duration::from_secs(3600)) .build(&parent_keypair); // parent_keypair is parent's holder assert!( matches!(result, Err(Error::MonotonicityViolation(ref m)) if m.contains("outlive")), "expected rejection, got {:?}", result.map(|w| w.expires_at()) ); // Omitting the TTL inherits the parent's expiry. let child = parent .attenuate() .inherit_all() .build(&parent_keypair) .unwrap(); assert_eq!(child.expires_at(), parent.expires_at()); // A TTL within the parent's remaining lifetime is accepted as requested. let child = parent .attenuate() .inherit_all() .ttl(Duration::from_secs(30)) .build(&parent_keypair) .unwrap(); assert!(child.expires_at() <= parent.expires_at()); // High-level SDKs can explicitly request atomic clamping without a // separate, racy wall-clock calculation in the language binding. let child = parent .attenuate() .inherit_all() .ttl_capped_to_parent(Duration::from_secs(3600)) .build(&parent_keypair) .unwrap(); assert_eq!(child.expires_at(), parent.expires_at()); } #[test] fn test_attenuation_max_depth_limit() { let keypair = create_test_keypair(); // Create warrant with explicit max_depth let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .max_depth(5) .holder(keypair.public_key()) .build(&keypair) .unwrap(); // max_depth is the policy limit (inherited), depth is the counter assert_eq!(warrant.depth(), 0); assert_eq!(warrant.max_depth(), Some(5)); // Delegate - depth increases, max_depth is inherited // POLA: must inherit_all() to get parent capabilities let child = warrant.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(child.depth(), 1); assert_eq!(child.max_depth(), Some(5)); // Inherited // When depth reaches max_depth, warrant is terminal let mut current = child; for _ in 2..5 { current = current.attenuate().inherit_all().build(&keypair).unwrap(); } assert_eq!(current.depth(), 4); // depth=5 would equal max_depth=5, so next attenuation should still work let level5 = current.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(level5.depth(), 5); assert!( level5.is_terminal(), "warrant at depth=max_depth should be terminal" ); // Further attenuation should fail let result = level5.attenuate().inherit_all().build(&keypair); assert!(result.is_err(), "cannot attenuate terminal warrant"); } #[test] fn test_attenuation_depth_limit_with_max_depth() { let keypair = create_test_keypair(); // Create warrant with explicit max_depth of 3 (smaller than chain length limit) let mut warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .max_depth(3) .holder(keypair.public_key()) .build(&keypair) .unwrap(); // Delegate up to max depth (POLA: inherit_all) for _ in 0..3 { warrant = warrant.attenuate().inherit_all().build(&keypair).unwrap(); } // Next delegation should fail due to depth limit let result = warrant.attenuate().inherit_all().build(&keypair); assert!(result.is_err()); match result.unwrap_err() { Error::DepthExceeded(_, _) => {} e => panic!("Expected DepthExceeded, got {:?}", e), } } #[test] fn test_range_constraint_attenuation() { let parent_keypair = create_test_keypair(); let _child_keypair = create_test_keypair(); // Unused with new delegation API let mut parent_constraints = ConstraintSet::new(); parent_constraints.insert("amount", Range::max(10000.0).unwrap()); let parent = Warrant::builder() .tool("transfer_funds", parent_constraints) .ttl(Duration::from_secs(600)) .holder(parent_keypair.public_key()) .build(&parent_keypair) .unwrap(); // Valid: narrower range let mut child_constraints = ConstraintSet::new(); child_constraints.insert("amount", Range::max(5000.0).unwrap()); let child = parent .attenuate() .tool("transfer_funds", child_constraints) .build(&parent_keypair); // parent_keypair is parent's holder assert!(child.is_ok()); // Invalid: wider range let mut invalid_constraints = ConstraintSet::new(); invalid_constraints.insert("amount", Range::max(20000.0).unwrap()); let invalid = parent .attenuate() .tool("transfer_funds", invalid_constraints) .build(&parent_keypair); // parent_keypair is parent's holder assert!(invalid.is_err()); } #[test] fn test_session_binding() { let keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .session_id("session_123") .holder(keypair.public_key()) .build(&keypair) .unwrap(); assert_eq!(warrant.session_id(), Some("session_123")); // Session ID is preserved through attenuation (POLA: inherit_all) let child = warrant.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(child.session_id(), Some("session_123")); } // ========================================================================= // PROOF-OF-POSSESSION (PoP) FAILURE CASES // ========================================================================= #[test] fn test_pop_signature_wrong_keypair() { let correct_keypair = create_test_keypair(); let wrong_keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(600)) .holder(correct_keypair.public_key()) .build(&correct_keypair) .unwrap(); let mut args = HashMap::new(); args.insert( "param".to_string(), ConstraintValue::String("value".to_string()), ); // Create PoP signature with WRONG keypair let wrong_pop_sig = warrant.sign(&wrong_keypair, "test", &args).unwrap(); // Authorization should fail - wrong keypair assert!(warrant .authorize("test", &args, Some(&wrong_pop_sig)) .is_err()); } #[test] fn test_pop_signature_wrong_tool() { let keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("test_tool", ConstraintSet::new()) .ttl(Duration::from_secs(600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let mut args = HashMap::new(); args.insert( "param".to_string(), ConstraintValue::String("value".to_string()), ); // Create PoP signature for WRONG tool let pop_sig = warrant.sign(&keypair, "wrong_tool", &args).unwrap(); // Authorization should fail - tool mismatch assert!(warrant .authorize("test_tool", &args, Some(&pop_sig)) .is_err()); } #[test] fn test_pop_signature_wrong_args() { let keypair = create_test_keypair(); let mut constraints = ConstraintSet::new(); constraints.insert("cluster", Pattern::new("staging-*").unwrap()); let warrant = Warrant::builder() .tool("test", constraints) .ttl(Duration::from_secs(600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let mut correct_args = HashMap::new(); correct_args.insert( "cluster".to_string(), ConstraintValue::String("staging-web".to_string()), ); let mut wrong_args = HashMap::new(); wrong_args.insert( "cluster".to_string(), ConstraintValue::String("prod-web".to_string()), ); // Create PoP signature with WRONG args let pop_sig = warrant.sign(&keypair, "test", &wrong_args).unwrap(); // Authorization with correct args but wrong PoP signature should fail // (PoP signature is bound to specific args) assert!(warrant .authorize("test", &correct_args, Some(&pop_sig)) .is_err()); } #[test] fn test_pop_signature_expired_warrant() { let keypair = create_test_keypair(); // Create warrant with very short TTL let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(1)) // 1 second TTL .holder(keypair.public_key()) .build(&keypair) .unwrap(); let args = HashMap::new(); let pop_sig = warrant.sign(&keypair, "test", &args).unwrap(); // Wait for expiration std::thread::sleep(Duration::from_secs(2)); // Authorization should fail - warrant expired assert!(warrant.authorize("test", &args, Some(&pop_sig)).is_err()); } #[test] fn test_pop_signature_no_signature() { let keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); let args = HashMap::new(); // Authorization without PoP signature should fail assert!(warrant.authorize("test", &args, None).is_err()); } #[test] fn test_warrant_id_format() { let id = WarrantId::new(); // Display shows prefixed string assert!(id.to_string().starts_with("tnu_wrt_")); // Hex is 32 chars (16 bytes) assert_eq!(id.to_hex().len(), 32); // Parse from prefixed string let parsed = WarrantId::from_string(id.to_string()).unwrap(); assert_eq!(parsed, id); // Parse from hex let parsed_hex = WarrantId::from_string(id.to_hex()).unwrap(); assert_eq!(parsed_hex, id); // Invalid hex length let invalid = WarrantId::from_string("invalid_id"); assert!(invalid.is_err()); } #[test] fn test_max_depth_policy_limit() { let keypair = create_test_keypair(); // Create warrant with policy limit of 3 let root = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .max_depth(3) .holder(keypair.public_key()) .build(&keypair) .unwrap(); assert_eq!(root.max_depth(), Some(3)); assert_eq!(root.effective_max_depth(), 3); // Can delegate up to depth 3 (POLA: inherit_all for all) let level1 = root.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(level1.depth(), 1); assert_eq!(level1.max_depth(), Some(3)); // Inherited let level2 = level1.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(level2.depth(), 2); let level3 = level2.attenuate().inherit_all().build(&keypair).unwrap(); assert_eq!(level3.depth(), 3); // Depth 4 should fail (exceeds policy limit) let result = level3.attenuate().inherit_all().build(&keypair); assert!(result.is_err()); match result.unwrap_err() { Error::DepthExceeded(4, 3) => {} e => panic!("Expected DepthExceeded(4, 3), got {:?}", e), } } #[test] fn test_max_depth_monotonicity() { let keypair = create_test_keypair(); let root = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .max_depth(5) .holder(keypair.public_key()) .build(&keypair) .unwrap(); // Can shrink max_depth (POLA: inherit_all) let child = root .attenuate() .inherit_all() .max_depth(3) .build(&keypair) .unwrap(); assert_eq!(child.max_depth(), Some(3)); // Cannot expand max_depth let result = child .attenuate() .inherit_all() .max_depth(10) .build(&keypair); assert!(result.is_err()); match result.unwrap_err() { Error::MonotonicityViolation(_) => {} e => panic!("Expected MonotonicityViolation, got {:?}", e), } } #[test] fn test_max_depth_protocol_cap() { let keypair = create_test_keypair(); // Cannot set max_depth above protocol cap let result = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .max_depth(100) // Above MAX_DELEGATION_DEPTH .holder(keypair.public_key()) .build(&keypair); assert!(result.is_err()); match result.unwrap_err() { Error::DepthExceeded(100, max) if max == crate::MAX_DELEGATION_DEPTH => {} e => panic!( "Expected DepthExceeded(100, {}), got {:?}", crate::MAX_DELEGATION_DEPTH, e ), } } #[test] fn test_no_max_depth_uses_protocol_default() { let keypair = create_test_keypair(); let root = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); // max_depth is now None when not explicitly set (protocol default applies) // max_depth is now mandatory u8, defaulting to MAX_DELEGATION_DEPTH if unset assert_eq!(root.max_depth(), Some(MAX_DELEGATION_DEPTH)); assert_eq!(root.effective_max_depth(), MAX_DELEGATION_DEPTH); } // ========================================================================= // MULTI-SIG TESTS // ========================================================================= #[test] fn test_multisig_root_warrant() { use crate::approval_gate::{encode_approval_gate_map, ApprovalGateMap, ToolApprovalGate}; let issuer = create_test_keypair(); let approver1 = create_test_keypair(); let approver2 = create_test_keypair(); let mut gates = ApprovalGateMap::new(); gates.insert("sensitive_action".into(), ToolApprovalGate::whole_tool()); let warrant = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key(), approver2.public_key()]) .min_approvals(2) .holder(issuer.public_key()) .extension( "tenuo.approval_gates", encode_approval_gate_map(&gates).unwrap(), ) .build(&issuer) .unwrap(); assert!(warrant.requires_multisig()); assert_eq!(warrant.approval_threshold(), 2); assert_eq!(warrant.required_approvers().unwrap().len(), 2); } #[test] fn test_multisig_default_all_must_sign() { use crate::approval_gate::{encode_approval_gate_map, ApprovalGateMap, ToolApprovalGate}; let issuer = create_test_keypair(); let approver1 = create_test_keypair(); let approver2 = create_test_keypair(); let mut gates = ApprovalGateMap::new(); gates.insert("sensitive_action".into(), ToolApprovalGate::whole_tool()); // Set approvers but NOT min_approvals - should require all let warrant = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key(), approver2.public_key()]) .holder(issuer.public_key()) .extension( "tenuo.approval_gates", encode_approval_gate_map(&gates).unwrap(), ) // min_approvals NOT set .build(&issuer) .unwrap(); assert!(warrant.requires_multisig()); assert_eq!(warrant.approval_threshold(), 2); // All must sign } #[test] fn test_multisig_min_approvals_exceeds_approvers() { let issuer = create_test_keypair(); let approver1 = create_test_keypair(); // Try to require 3 approvals with only 1 approver let result = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key()]) .min_approvals(3) .holder(issuer.public_key()) .build(&issuer); assert!(result.is_err()); } #[test] fn test_multisig_attenuation_add_approvers() { use crate::approval_gate::{encode_approval_gate_map, ApprovalGateMap, ToolApprovalGate}; let issuer = create_test_keypair(); let delegator = create_test_keypair(); let approver1 = create_test_keypair(); let approver2 = create_test_keypair(); let mut gates = ApprovalGateMap::new(); gates.insert("sensitive_action".into(), ToolApprovalGate::whole_tool()); // Root with 1 approver let root = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key()]) .min_approvals(1) .holder(issuer.public_key()) .extension( "tenuo.approval_gates", encode_approval_gate_map(&gates).unwrap(), ) .build(&issuer) .unwrap(); // Attenuate and ADD another approver (valid: more restrictive) // POLA: inherit_all to get parent capabilities let child = root .attenuate() .inherit_all() .add_approvers(vec![approver2.public_key()]) .raise_min_approvals(2) .holder(delegator.public_key()) .build(&issuer) // issuer signs (they hold root) .unwrap(); assert_eq!(child.required_approvers().unwrap().len(), 2); assert_eq!(child.approval_threshold(), 2); } #[test] fn test_multisig_attenuation_cannot_remove_approvers() { use crate::approval_gate::{encode_approval_gate_map, ApprovalGateMap, ToolApprovalGate}; let issuer = create_test_keypair(); let delegatee = create_test_keypair(); let approver1 = create_test_keypair(); let approver2 = create_test_keypair(); let mut gates = ApprovalGateMap::new(); gates.insert("sensitive_action".into(), ToolApprovalGate::whole_tool()); // Root with 2 approvers let root = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key(), approver2.public_key()]) .min_approvals(1) .holder(issuer.public_key()) .extension( "tenuo.approval_gates", encode_approval_gate_map(&gates).unwrap(), ) .build(&issuer) .unwrap(); // POLA: inherit_all to get parent capabilities let child = root .attenuate() .inherit_all() .holder(delegatee.public_key()) .build(&issuer) // issuer signs (they hold root) .unwrap(); // All parent approvers should be preserved assert_eq!(child.required_approvers().unwrap().len(), 2); } #[test] fn test_multisig_attenuation_cannot_lower_threshold() { use crate::approval_gate::{encode_approval_gate_map, ApprovalGateMap, ToolApprovalGate}; let issuer = create_test_keypair(); let delegatee = create_test_keypair(); let approver1 = create_test_keypair(); let approver2 = create_test_keypair(); let mut gates = ApprovalGateMap::new(); gates.insert("sensitive_action".into(), ToolApprovalGate::whole_tool()); // Root with threshold of 2 let root = Warrant::builder() .tool("sensitive_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .required_approvers(vec![approver1.public_key(), approver2.public_key()]) .min_approvals(2) .holder(issuer.public_key()) .extension( "tenuo.approval_gates", encode_approval_gate_map(&gates).unwrap(), ) .build(&issuer) .unwrap(); // POLA: inherit_all to get parent capabilities let child = root .attenuate() .inherit_all() .raise_min_approvals(1) // Tries to set 1, but max(current, 1) = 2 .holder(delegatee.public_key()) .build(&issuer) // issuer signs (they hold root) .unwrap(); // Threshold should still be 2 (inherited, max applied) assert_eq!(child.approval_threshold(), 2); } #[test] fn test_no_multisig_by_default() { let keypair = create_test_keypair(); let warrant = Warrant::builder() .tool("regular_action", ConstraintSet::new()) .ttl(Duration::from_secs(300)) .holder(keypair.public_key()) .build(&keypair) .unwrap(); assert!(!warrant.requires_multisig()); assert_eq!(warrant.approval_threshold(), 0); assert!(warrant.required_approvers().is_none()); } #[test] fn test_issuer_warrant_issues_execution_warrant() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); // Create an issuer warrant let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string(), "send_email".to_string()]) .clearance(Clearance::INTERNAL) .max_issue_depth(2) .constraint_bound("path", Pattern::new("/data/*").unwrap()) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Issue an execution warrant // Note: issuer_kp is both the issuer warrant holder and the issuer warrant issuer let mut constraints = ConstraintSet::new(); constraints.insert("path", Pattern::new("/data/q3.pdf").unwrap()); let execution_warrant = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", constraints) .clearance(Clearance::EXTERNAL) .ttl(Duration::from_secs(60)) .holder(holder_kp.public_key()) .build(&issuer_kp) // issuer_kp is both holder and issuer .unwrap(); assert_eq!(execution_warrant.r#type(), WarrantType::Execution); let caps = execution_warrant.capabilities().unwrap(); assert!(caps.contains_key("read_file")); assert_eq!( execution_warrant.authorized_holder(), &holder_kp.public_key() ); assert_eq!(execution_warrant.depth(), 1); use sha2::{Digest, Sha256}; let mut hasher = Sha256::new(); hasher.update(issuer_warrant.payload_bytes()); let parent_hash: [u8; 32] = hasher.finalize().into(); assert_eq!(execution_warrant.parent_hash(), Some(&parent_hash)); } #[test] fn test_issuance_ttl_cannot_exceed_issuer() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .ttl(Duration::from_secs(60)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .holder(holder_kp.public_key()) .build(&issuer_kp); assert!( matches!(result, Err(Error::MonotonicityViolation(ref message)) if message.contains("outlive")), "expected overlong issuance TTL to be rejected" ); } #[test] fn test_issuer_cannot_issue_to_self() { let issuer_kp = create_test_keypair(); // Create an issuer warrant held by issuer_kp let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::INTERNAL) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue an execution warrant to SELF (the issuer warrant holder) // This should be rejected as it would allow privilege escalation let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .holder(issuer_kp.public_key()) // Same as issuer warrant holder! .build(&issuer_kp); assert!(result.is_err()); let err = result.unwrap_err(); assert!( err.to_string().contains("self-issuance prohibited"), "Expected self-issuance error, got: {}", err ); } #[test] fn test_issuer_holder_separation() { // Test that execution warrant holder cannot be the issuer warrant's issuer // (the key that signed the issuer warrant) let issuer_kp = create_test_keypair(); // Signs issuer warrant AND will be execution holder let holder_kp = create_test_keypair(); // Holds the issuer warrant // Create an issuer warrant signed by issuer_kp, held by holder_kp let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::INTERNAL) .ttl(Duration::from_secs(3600)) .holder(holder_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue an execution warrant where the holder is the issuer warrant's issuer // This should be rejected as it would allow indirect privilege escalation let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .holder(issuer_kp.public_key()) // Same as issuer warrant's issuer! .build(&holder_kp); // holder_kp signs (they hold issuer_warrant) assert!(result.is_err()); let err = result.unwrap_err(); assert!( err.to_string() .contains("issuer-holder separation required"), "Expected issuer-holder separation error, got: {}", err ); } #[test] fn test_holder_cycling_allowed_with_monotonicity() { // Test that A → B → A delegation is allowed because monotonic attenuation // already guarantees privileges can only shrink. B delegating back to A // gives A a strictly weaker warrant than their original. let keypair_a = create_test_keypair(); let keypair_b = create_test_keypair(); // A creates a root warrant for themselves let mut root_constraints = ConstraintSet::new(); root_constraints.insert("env", Pattern::new("*").unwrap()); let root = Warrant::builder() .tool("test", root_constraints) .ttl(Duration::from_secs(3600)) .holder(keypair_a.public_key()) .build(&keypair_a) .unwrap(); // A delegates to B with narrower constraints let mut child_b_constraints = ConstraintSet::new(); child_b_constraints.insert("env", Pattern::new("staging-*").unwrap()); let child_b = root .attenuate() .tool("test", child_b_constraints) .holder(keypair_b.public_key()) .build(&keypair_a) // keypair_a is parent's holder .unwrap(); assert_eq!(child_b.depth(), 1); // B delegates back to A - this IS allowed because A gets a weaker warrant // POLA: inherit_all since B is just passing on the same capabilities let result = child_b .attenuate() .inherit_all() .holder(keypair_a.public_key()) .build(&keypair_b); // keypair_b is parent's holder // Should succeed - A now has a warrant limited to staging-*, not the original * assert!(result.is_ok()); let child_a = result.unwrap(); assert_eq!(child_a.depth(), 2); // A's new warrant is strictly weaker than their original due to monotonicity } #[test] fn test_issuance_validates_tool_in_issuable_tools() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::INTERNAL) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue with invalid tool let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("send_email", ConstraintSet::new()) // Not in issuable_tools .ttl(Duration::from_secs(60)) .holder(holder_kp.public_key()) .build(&issuer_kp); let err = result.expect_err("expected unauthorized tool issuance error"); let msg = err.to_string(); assert!( msg.contains("unauthorized tool issuance") || msg.contains("not in issuer's issuable_tools"), "unexpected error: {msg}" ); } #[test] fn test_issuance_validates_clearance() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::EXTERNAL) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue with trust level exceeding ceiling let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", ConstraintSet::new()) .clearance(Clearance::INTERNAL) // Exceeds External ceiling .ttl(Duration::from_secs(60)) .holder(holder_kp.public_key()) .build(&issuer_kp); assert!(result.is_err()); assert!(result .unwrap_err() .to_string() .contains("clearance level exceeded")); } #[test] fn test_issuance_validates_constraint_bounds() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::INTERNAL) .constraint_bound("path", Pattern::new("/data/*").unwrap()) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue with constraint outside bounds let mut constraints = ConstraintSet::new(); constraints.insert("path", Pattern::new("/etc/*").unwrap()); // Outside /data/* let result = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", constraints) .ttl(Duration::from_secs(60)) .holder(holder_kp.public_key()) .build(&issuer_kp); match result { Err(Error::PatternExpanded { parent, child }) => { assert_eq!(parent, "/data/*"); assert_eq!(child, "/etc/*"); } Err(other) => panic!("unexpected error: {:?}", other), Ok(_) => panic!("expected constraint bounds violation"), } } #[test] fn test_issuance_validates_max_issue_depth() { let issuer_kp = create_test_keypair(); let holder_kp = create_test_keypair(); let issuer_warrant = Warrant::builder() .r#type(WarrantType::Issuer) .issuable_tools(vec!["read_file".to_string()]) .clearance(Clearance::INTERNAL) .max_issue_depth(1) // Only allow depth 1 .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Issue first execution warrant (depth 1) - should work let exec1 = issuer_warrant .issue_execution_warrant() .unwrap() .tool("read_file", ConstraintSet::new()) .ttl(Duration::from_secs(60)) .holder(holder_kp.public_key()) .build(&issuer_kp) .unwrap(); assert_eq!(exec1.depth(), 1); // Try to issue from execution warrant (would be depth 2) - should fail // But wait, execution warrants can't issue, so this test doesn't apply // The max_issue_depth is about the depth of issued warrants, not delegation } #[test] fn test_execution_warrant_cannot_issue() { let issuer_kp = create_test_keypair(); let execution_warrant = Warrant::builder() .r#type(WarrantType::Execution) .tool("read_file", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) .holder(issuer_kp.public_key()) .build(&issuer_kp) .unwrap(); // Try to issue from execution warrant - should fail let result = execution_warrant.issue_execution_warrant(); assert!(result.is_err()); assert!(result .unwrap_err() .to_string() .contains("can only issue execution warrants from issuer warrants")); } #[test] fn test_clearance_ordering() { assert!(Clearance::SYSTEM > Clearance::PRIVILEGED); assert!(Clearance::PRIVILEGED > Clearance::INTERNAL); assert!(Clearance::INTERNAL > Clearance::PARTNER); assert!(Clearance::PARTNER > Clearance::EXTERNAL); assert!(Clearance::EXTERNAL > Clearance::UNTRUSTED); // Explicit check of values to prevent reordering assert_eq!(Clearance::UNTRUSTED.0, 0); assert_eq!(Clearance::EXTERNAL.0, 10); assert_eq!(Clearance::PARTNER.0, 20); assert_eq!(Clearance::INTERNAL.0, 30); assert_eq!(Clearance::PRIVILEGED.0, 40); assert_eq!(Clearance::SYSTEM.0, 50); } #[test] fn test_effective_max_depth_latching() { // 1. Root warrant (None/Unlimited) let root_kp = create_test_keypair(); let root = Warrant::builder() .tool("test", ConstraintSet::new()) .ttl(Duration::from_secs(3600)) // max_depth: None (defaults to MAX_DELEGATION_DEPTH=64) .holder(root_kp.public_key()) .build(&root_kp) .unwrap(); assert_eq!(root.effective_max_depth(), MAX_DELEGATION_DEPTH); // 2. Child warrant sets limit (Some(5)) - POLA: inherit_all let child = root .attenuate() .inherit_all() .max_depth(5) .build(&root_kp) .unwrap(); assert_eq!(child.effective_max_depth(), 5); // 3. Grandchild tries to increase limit (Some(10)) - Should fail/latch let result = child .attenuate() .inherit_all() .max_depth(10) .build(&root_kp); // Expect error because 10 > 5 assert!(result.is_err()); let err = result.unwrap_err(); match err { // We expect MonotonicityViolation or Validation error depending on implementation Error::MonotonicityViolation(_) | Error::Validation(_) => {} _ => panic!( "Expected monitoring violation or validation error, got {:?}", err ), } // 4. Grandchild with lower limit (Some(3)) - Should succeed let grandchild = child .attenuate() .inherit_all() .max_depth(3) .build(&root_kp) .unwrap(); assert_eq!(grandchild.effective_max_depth(), 3); } }