vauban_claim/

composition.rs

//! Five composition operators (CDDL §6) and the `composition-record` envelope.

use alloc::collections::{BTreeMap, BTreeSet};
use alloc::string::String;
use alloc::vec;
use alloc::vec::Vec;
use serde::{Deserialize, Serialize};

use crate::claim::{Claim, ClaimRef};
use crate::error::CompositionError;
use crate::primitives::{
    evidence::{Evidence, EvidenceEnvelope, EvidenceScheme, StarkProofEnvelope},
    revelation_mask::RevelationMask,
};

/// Operator discriminator (CDDL `operator-tag`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum OperatorTag {
    /// `∧` — logical AND.
    Conjunction,
    /// `→` — authority chain.
    Delegation,
    /// `⊕` — multi-issuer aggregation in one STARK.
    Aggregation,
    /// `▷` — narrowing of revelation mask.
    Restriction,
    /// `¬` — sticky revocation.
    Revocation,
}

/// Operator-specific record body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum OperatorBody {
    /// §6.1 conjunction body.
    Conjunction(ConjunctionBody),
    /// §6.2 delegation body.
    Delegation(DelegationBody),
    /// §6.3 aggregation body.
    Aggregation(AggregationBody),
    /// §6.4 restriction body.
    Restriction(RestrictionBody),
    /// §6.5 revocation body.
    Revocation(RevocationBody),
}

/// CDDL §6.1 conjunction body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ConjunctionBody {
    /// Left operand.
    pub left: ClaimRef,
    /// Right operand.
    pub right: ClaimRef,
    /// Linkage proof — required iff subjects differ (C-1).
    #[serde(rename = "linkage-proof", default, skip_serializing_if = "Option::is_none")]
    pub linkage_proof: Option<alloc::vec::Vec<u8>>,
}

/// CDDL §6.2 delegation body — one chain link per composition node.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DelegationBody {
    /// Reference to the previous link in the chain.
    pub parent: ClaimRef,
    /// Authority making this delegation step.
    pub authority: Authority,
    /// Constrained scope the delegate may issue.
    pub scope: DelegationScope,
}

/// Authority record (CDDL `authority`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Authority {
    /// Discriminator.
    #[serde(rename = "type")]
    pub authority_type: AuthorityType,
    /// Identifier — bytes (e.g. CSCA name) or text (DID).
    pub identifier: AuthorityId,
    /// Optional public-key reference.
    #[serde(rename = "key-ref", default, skip_serializing_if = "Option::is_none", with = "opt_bytes")]
    pub key_ref: Option<Vec<u8>>,
    /// Optional anchor pinning the authority to a trust root.
    #[serde(rename = "trust-root", default, skip_serializing_if = "Option::is_none")]
    pub trust_root: Option<crate::primitives::anchor::AnchorEntry>,
}

/// Authority discriminator.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AuthorityType {
    /// PKI X.509 certificate authority.
    #[serde(rename = "x509-ca")]
    X509Ca,
    /// W3C DID-method authority.
    #[serde(rename = "did-method")]
    DidMethod,
    /// Cairo on-chain registry contract.
    #[serde(rename = "starknet-registry")]
    StarknetRegistry,
    /// IETF Trust Anchor (RFC 5914).
    #[serde(rename = "ietf-ta")]
    IetfTa,
}

/// Authority identifier — bytes or text.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(untagged)]
pub enum AuthorityId {
    /// Byte-encoded identifier.
    Bytes(#[serde(with = "serde_bytes")] Vec<u8>),
    /// Textual identifier.
    Text(String),
}

/// Delegation scope (CDDL `delegation-scope`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
pub struct DelegationScope {
    /// Allowed predicate types — `None` ⇒ inherit parent.
    #[serde(rename = "predicate-types", default, skip_serializing_if = "Option::is_none")]
    pub predicate_types: Option<Vec<crate::primitives::predicate::PredicateType>>,
    /// Allowed `predicate.domain` prefixes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub domains: Option<Vec<String>>,
    /// Path-length constraint (RFC 5280 §4.2.1.9).
    #[serde(rename = "max-depth", default, skip_serializing_if = "Option::is_none")]
    pub max_depth: Option<u64>,
}

/// CDDL §6.3 aggregation body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AggregationBody {
    /// Number of operands (must equal `composition_record.operands.len()`).
    pub count: u64,
    /// Single STARK proof verifying every operand jointly.
    #[serde(rename = "aggregated-evidence")]
    pub aggregated_evidence: StarkProofEnvelope,
    /// Per-operand issuer key bindings (machine-checkable G-1).
    #[serde(rename = "issuer-bindings")]
    pub issuer_bindings: Vec<IssuerBinding>,
}

/// Issuer binding for aggregation diversity check (CDDL `issuer-binding`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IssuerBinding {
    /// Operand reference.
    pub operand: ClaimRef,
    /// Canonical pubkey of the operand's issuer (e.g. JWK thumbprint).
    #[serde(rename = "issuer-key", with = "serde_bytes")]
    pub issuer_key: Vec<u8>,
    /// Optional anchor pinning the issuer.
    #[serde(rename = "issuer-anchor", default, skip_serializing_if = "Option::is_none")]
    pub issuer_anchor: Option<crate::primitives::anchor::AnchorEntry>,
}

/// CDDL §6.4 restriction body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RestrictionBody {
    /// Source Claim being restricted.
    pub source: ClaimRef,
    /// New (narrower) mask.
    pub mask: RevelationMask,
    /// Optional proof of monotonicity.
    #[serde(rename = "monotonicity-proof", default, skip_serializing_if = "Option::is_none")]
    pub monotonicity_proof: Option<alloc::vec::Vec<u8>>,
}

/// CDDL §6.5 revocation body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RevocationBody {
    /// Source Claim being revoked.
    pub source: ClaimRef,
    /// POSIX-epoch revocation time.
    #[serde(rename = "revoked-at")]
    pub revoked_at: u64,
    /// Authority issuing the revocation.
    pub revoker: Authority,
    /// Mode-specific revocation evidence.
    pub proof: RevocationProof,
    /// Optional RFC 5280 §5.3.1 reason code.
    #[serde(rename = "reason-code", default, skip_serializing_if = "Option::is_none")]
    pub reason_code: Option<RevocationReasonCode>,
}

/// Revocation evidence variants (CDDL `revocation-proof`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "mode", rename_all = "kebab-case")]
pub enum RevocationProof {
    /// On-chain Poseidon nullifier inclusion.
    Nullifier {
        /// 32-byte Poseidon-felt252 nullifier.
        #[serde(with = "serde_bytes")]
        nullifier: Vec<u8>,
        /// On-chain inclusion anchor entry.
        #[serde(rename = "anchor-entry")]
        anchor_entry: crate::primitives::anchor::AnchorEntry,
    },
    /// Signed revocation status list.
    StatusList {
        /// URI of the published status list.
        #[serde(rename = "list-uri")]
        list_uri: String,
        /// Index of this Claim in the list.
        #[serde(rename = "list-index")]
        list_index: u64,
        /// Revoker signature over the list.
        #[serde(default, skip_serializing_if = "Option::is_none", with = "opt_bytes")]
        signature: Option<Vec<u8>>,
        /// Optional batched on-chain commitment.
        #[serde(rename = "batch-anchor", default, skip_serializing_if = "Option::is_none")]
        batch_anchor: Option<crate::primitives::anchor::AnchorEntry>,
    },
}

/// RFC 5280 §5.3.1 reason codes (subset relevant to Vauban Claims).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RevocationReasonCode {
    /// No specific reason given.
    Unspecified,
    /// Subject's private key has been compromised.
    KeyCompromise,
    /// CA's private key has been compromised.
    CaCompromise,
    /// Subject affiliation changed.
    AffiliationChanged,
    /// Replaced by another credential.
    Superseded,
    /// Issuing CA / authority no longer operates.
    CessationOfOperation,
    /// Temporary hold.
    CertificateHold,
    /// Subject no longer privileged to hold the credential.
    PrivilegeWithdrawn,
}

mod opt_bytes {
    use alloc::vec::Vec;
    use serde::{Deserialize, Deserializer, Serialize, Serializer};
    pub fn serialize<S: Serializer>(v: &Option<Vec<u8>>, s: S) -> Result<S::Ok, S::Error> {
        match v {
            Some(b) => serde_bytes::Bytes::new(b).serialize(s),
            None => s.serialize_none(),
        }
    }
    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec<u8>>, D::Error> {
        let opt: Option<serde_bytes::ByteBuf> = Option::deserialize(d)?;
        Ok(opt.map(serde_bytes::ByteBuf::into_vec))
    }
}

/// Composition record (CDDL `composition-record`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CompositionRecord {
    /// Operator discriminator.
    pub operator: OperatorTag,
    /// Operand references.
    pub operands: Vec<ClaimRef>,
    /// Longest path from this node to any atomic leaf.
    pub depth: u64,
    /// Opaque metadata bag.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<BTreeMap<String, serde_json::Value>>,
    /// Discriminated body.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<OperatorBody>,
}

/// Trait exposing the five operators on Claims.
pub trait ClaimComposition {
    /// `∧` — Conjunction (§6.1).
    fn conjunct(&self, other: &Claim) -> Result<Claim, CompositionError>;

    /// `→` — Delegation (§6.2). The `authority` issues this delegation step.
    fn delegate(&self, authority: &Authority, scope: DelegationScope)
        -> Result<Claim, CompositionError>;

    /// `⊕` — Aggregation (§6.3). Single STARK across `claims`. Issuer keys
    /// must be pairwise distinct (G-1).
    fn aggregate(
        claims: &[Claim],
        bindings: Vec<IssuerBinding>,
        aggregated_evidence: StarkProofEnvelope,
    ) -> Result<Claim, CompositionError>;

    /// `▷` — Restriction (§6.4). New mask must refine the source mask (R-1).
    fn restrict(&self, mask: &RevelationMask) -> Result<Claim, CompositionError>;

    /// `¬` — Revocation (§6.5). Returns a derived `Claim_revoked`.
    fn revoke(
        &self,
        revoker: Authority,
        revoked_at: u64,
        proof: RevocationProof,
        reason: Option<RevocationReasonCode>,
    ) -> Result<Claim, CompositionError>;
}

impl ClaimComposition for Claim {
    fn conjunct(&self, other: &Claim) -> Result<Claim, CompositionError> {
        // C-1 — subjects must match (or linkage proof would be required).
        if self.subject != other.subject {
            return Err(CompositionError::SubjectMismatch);
        }
        // C-3 — temporal-intersect.
        let temporal = self
            .temporal_frame
            .intersect(&other.temporal_frame)
            .ok_or(CompositionError::TemporalDisjoint)?;
        // C-2 — anchor union.
        let anchor = self.anchor.union(&other.anchor);
        // C-4 — disclosed bound (use intersection of disclosed paths).
        let mask = merge_masks(&self.revelation_mask, &other.revelation_mask)?;
        let left = self.claim_ref().expect("claim_ref encoding");
        let right = other.claim_ref().expect("claim_ref encoding");
        let body = OperatorBody::Conjunction(ConjunctionBody {
            left: left.clone(),
            right: right.clone(),
            linkage_proof: None,
        });
        let depth = 1 + self.depth().max(other.depth());
        let record = CompositionRecord {
            operator: OperatorTag::Conjunction,
            operands: vec![left, right],
            depth,
            metadata: None,
            body: Some(body),
        };
        let claim = Claim {
            subject: self.subject.clone(),
            predicate: self.predicate.clone(),
            evidence: self.evidence.clone(),
            temporal_frame: temporal,
            revelation_mask: mask,
            anchor,
            composition: Some(record),
            extensions: None,
            #[cfg(feature = "transcript-v2")]
            transcript_version: crate::transcript_v2::TranscriptVersion::default(),
        };
        claim.validate()?;
        Ok(claim)
    }

    fn delegate(
        &self,
        authority: &Authority,
        scope: DelegationScope,
    ) -> Result<Claim, CompositionError> {
        // D-3: each link must be valid at evaluation time — surfaced via temporal_frame.
        // D-2: scope ⊆ parent scope. We compare against the immediate parent.
        if let Some(parent_record) = &self.composition {
            if matches!(parent_record.operator, OperatorTag::Delegation) {
                if let Some(OperatorBody::Delegation(parent)) = &parent_record.body {
                    enforce_scope_subset(&parent.scope, &scope)?;
                    if let Some(max_depth) = parent.scope.max_depth {
                        if parent_record.depth >= max_depth {
                            return Err(CompositionError::ScopeOverflow);
                        }
                    }
                }
            }
        }
        // Cycle detection by walking the parent chain via in-memory `composition`.
        let mut chain = BTreeSet::new();
        let mut cursor = Some(self);
        while let Some(c) = cursor {
            let r = c.claim_ref().expect("claim_ref encoding");
            if !chain.insert(r.digest.clone()) {
                return Err(CompositionError::DelegationCycle);
            }
            cursor = None; // in-memory chain stops; deeper detection would walk a Claim store.
            // Local DAG: a self-loop happens only if the parent_ref of `self` references its own digest.
            if let Some(rec) = &c.composition {
                if let Some(OperatorBody::Delegation(d)) = &rec.body {
                    if d.parent.digest == r.digest {
                        return Err(CompositionError::DelegationCycle);
                    }
                }
            }
        }
        let parent_ref = self.claim_ref().expect("claim_ref encoding");
        let body = OperatorBody::Delegation(DelegationBody {
            parent: parent_ref.clone(),
            authority: authority.clone(),
            scope,
        });
        let depth = 1 + self.depth();
        let record = CompositionRecord {
            operator: OperatorTag::Delegation,
            operands: vec![parent_ref],
            depth,
            metadata: None,
            body: Some(body),
        };
        Ok(Claim {
            subject: self.subject.clone(),
            predicate: self.predicate.clone(),
            evidence: self.evidence.clone(),
            temporal_frame: self.temporal_frame,
            revelation_mask: self.revelation_mask.clone(),
            anchor: self.anchor.clone(),
            composition: Some(record),
            extensions: None,
            #[cfg(feature = "transcript-v2")]
            transcript_version: crate::transcript_v2::TranscriptVersion::default(),
        })
    }

    fn aggregate(
        claims: &[Claim],
        bindings: Vec<IssuerBinding>,
        aggregated_evidence: StarkProofEnvelope,
    ) -> Result<Claim, CompositionError> {
        if claims.len() < 2 {
            return Err(CompositionError::AggregationTooFew);
        }
        if bindings.len() != claims.len() {
            return Err(CompositionError::Invariant(
                "issuer_bindings.len must equal operands.len",
            ));
        }
        // G-1 — issuer-key diversity.
        let mut seen = BTreeSet::new();
        for b in &bindings {
            if !seen.insert(b.issuer_key.clone()) {
                return Err(CompositionError::IssuerDuplicate);
            }
        }
        // Anchor union, temporal intersection (G-3).
        let mut temporal = claims[0].temporal_frame;
        let mut anchor = claims[0].anchor.clone();
        for c in &claims[1..] {
            temporal = temporal
                .intersect(&c.temporal_frame)
                .ok_or(CompositionError::TemporalDisjoint)?;
            anchor = anchor.union(&c.anchor);
        }
        let operands: Vec<ClaimRef> = claims
            .iter()
            .map(|c| c.claim_ref().expect("claim_ref encoding"))
            .collect();
        let depth = 1 + claims.iter().map(Claim::depth).max().unwrap_or(0);
        let body = OperatorBody::Aggregation(AggregationBody {
            count: claims.len() as u64,
            aggregated_evidence: aggregated_evidence.clone(),
            issuer_bindings: bindings,
        });
        let evidence = Evidence::new(
            EvidenceScheme::Stark,
            aggregated_evidence.proof.clone(),
            Some(EvidenceEnvelope::Stark(aggregated_evidence)),
        )?;
        Ok(Claim {
            subject: claims[0].subject.clone(),
            predicate: claims[0].predicate.clone(),
            evidence,
            temporal_frame: temporal,
            revelation_mask: claims[0].revelation_mask.clone(),
            anchor,
            composition: Some(CompositionRecord {
                operator: OperatorTag::Aggregation,
                operands,
                depth,
                metadata: None,
                body: Some(body),
            }),
            extensions: None,
            #[cfg(feature = "transcript-v2")]
            transcript_version: crate::transcript_v2::TranscriptVersion::default(),
        })
    }

    fn restrict(&self, mask: &RevelationMask) -> Result<Claim, CompositionError> {
        // R-1 — monotonicity.
        if !mask.refines(&self.revelation_mask) {
            return Err(CompositionError::MaskNonMonotonic);
        }
        mask.validate_shape()?;
        let source = self.claim_ref().expect("claim_ref encoding");
        let body = OperatorBody::Restriction(RestrictionBody {
            source: source.clone(),
            mask: mask.clone(),
            monotonicity_proof: None,
        });
        let depth = 1 + self.depth();
        Ok(Claim {
            subject: self.subject.clone(),
            predicate: self.predicate.clone(),
            evidence: self.evidence.clone(),
            temporal_frame: self.temporal_frame,
            revelation_mask: mask.clone(),
            anchor: self.anchor.clone(),
            composition: Some(CompositionRecord {
                operator: OperatorTag::Restriction,
                operands: vec![source],
                depth,
                metadata: None,
                body: Some(body),
            }),
            extensions: None,
            #[cfg(feature = "transcript-v2")]
            transcript_version: crate::transcript_v2::TranscriptVersion::default(),
        })
    }

    fn revoke(
        &self,
        revoker: Authority,
        revoked_at: u64,
        proof: RevocationProof,
        reason: Option<RevocationReasonCode>,
    ) -> Result<Claim, CompositionError> {
        // V-2 — proof shape sanity.
        match &proof {
            RevocationProof::Nullifier { nullifier, .. } => {
                if nullifier.len() != 32 {
                    return Err(CompositionError::Invariant(
                        "V-2: nullifier must be 32 bytes (Poseidon-felt252)",
                    ));
                }
            }
            RevocationProof::StatusList { list_uri, .. } => {
                if list_uri.is_empty() {
                    return Err(CompositionError::Invariant(
                        "V-2: status-list revocation requires a non-empty list_uri",
                    ));
                }
            }
        }
        // Sticky check (sub-rule, not a CDDL "MUST"): an already-revoked Claim
        // should not be wrapped twice — surface to the caller for explicit handling.
        if self.temporal_frame.is_revoked_at(revoked_at) {
            return Err(CompositionError::AlreadyRevoked);
        }
        let source = self.claim_ref().expect("claim_ref encoding");
        let body = OperatorBody::Revocation(RevocationBody {
            source: source.clone(),
            revoked_at,
            revoker,
            proof,
            reason_code: reason,
        });
        let mut frame = self.temporal_frame;
        frame.revoked_at = Some(revoked_at);
        let depth = 1 + self.depth();
        Ok(Claim {
            subject: self.subject.clone(),
            predicate: self.predicate.clone(),
            evidence: self.evidence.clone(),
            temporal_frame: frame,
            revelation_mask: self.revelation_mask.clone(),
            anchor: self.anchor.clone(),
            composition: Some(CompositionRecord {
                operator: OperatorTag::Revocation,
                operands: vec![source],
                depth,
                metadata: None,
                body: Some(body),
            }),
            extensions: None,
            #[cfg(feature = "transcript-v2")]
            transcript_version: crate::transcript_v2::TranscriptVersion::default(),
        })
    }
}

fn merge_masks(
    a: &RevelationMask,
    b: &RevelationMask,
) -> Result<RevelationMask, CompositionError> {
    let mut disclosed = a.disclosed.clone();
    for d in &b.disclosed {
        if !disclosed.contains(d) {
            disclosed.push(d.clone());
        }
    }
    let mut committed = a.committed.clone();
    for c in &b.committed {
        if !committed.iter().any(|x| x.path == c.path) {
            committed.push(c.clone());
        }
    }
    RevelationMask::new(disclosed, committed, a.hash_alg.or(b.hash_alg))
}

fn enforce_scope_subset(
    parent: &DelegationScope,
    child: &DelegationScope,
) -> Result<(), CompositionError> {
    if let (Some(parent_pt), Some(child_pt)) = (&parent.predicate_types, &child.predicate_types) {
        let p: BTreeSet<_> = parent_pt.iter().collect();
        for x in child_pt {
            if !p.contains(x) {
                return Err(CompositionError::ScopeOverflow);
            }
        }
    }
    if let (Some(parent_dom), Some(child_dom)) = (&parent.domains, &child.domains) {
        for x in child_dom {
            if !parent_dom.iter().any(|p| x.starts_with(p)) {
                return Err(CompositionError::ScopeOverflow);
            }
        }
    }
    if let (Some(parent_md), Some(child_md)) = (parent.max_depth, child.max_depth) {
        if child_md > parent_md {
            return Err(CompositionError::ScopeOverflow);
        }
    }
    Ok(())
}