Skip to main content

qualia_core_db/domain_licence/
model.rs

1//! Data model for domain licence instruments.
2
3use serde::{Deserialize, Serialize};
4
5/// Maximum subject domains per licence.
6pub const MAX_DOMAINS: usize = 64;
7/// Maximum delegated members in a steward licence.
8pub const MAX_MEMBERS: usize = 256;
9/// Maximum capability scopes per licence.
10pub const MAX_SCOPES: usize = 16;
11/// Maximum chain anchors per licence.
12pub const MAX_ANCHORS: usize = 8;
13/// Maximum roster amendments chained to one licence.
14pub const MAX_AMENDMENT_DELTA: usize = 256;
15
16/// Recognised licence classes (WIP §2). Unknown fails closed.
17#[repr(u8)]
18#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
19pub enum LicenceClass {
20    #[default]
21    Unknown = 0,
22    /// Non-profit / community / humanitarian — gratis.
23    Community = 1,
24    /// Local custodian administering delegated members (the "inn" model).
25    CommunitySteward = 2,
26    /// Natural person, self-hosted.
27    Personal = 3,
28    /// Time-boxed trial for any org.
29    Evaluation = 4,
30    /// Commercial organisation — payment evidence expected.
31    Commercial = 5,
32    /// Issuer's own deployments.
33    Internal = 6,
34}
35
36impl LicenceClass {
37    /// Decode a class tag (1–6); out-of-range values become `Unknown`
38    /// (fail-closed).
39    pub fn from_u8(value: u8) -> Self {
40        match value {
41            1 => Self::Community,
42            2 => Self::CommunitySteward,
43            3 => Self::Personal,
44            4 => Self::Evaluation,
45            5 => Self::Commercial,
46            6 => Self::Internal,
47            _ => Self::Unknown,
48        }
49    }
50
51    /// Parse a class token. Unrecognised strings become `Unknown` (fail-closed).
52    pub fn parse(tag: &str) -> Self {
53        match tag.trim().to_ascii_lowercase().as_str() {
54            "community" => Self::Community,
55            "community-steward" | "community_steward" | "steward" => Self::CommunitySteward,
56            "personal" => Self::Personal,
57            "evaluation" | "eval" | "trial" => Self::Evaluation,
58            "commercial" => Self::Commercial,
59            "internal" => Self::Internal,
60            _ => Self::Unknown,
61        }
62    }
63
64    /// Canonical lowercase token for the class (inverse of `parse`).
65    pub fn token(self) -> &'static str {
66        match self {
67            Self::Unknown => "unknown",
68            Self::Community => "community",
69            Self::CommunitySteward => "community-steward",
70            Self::Personal => "personal",
71            Self::Evaluation => "evaluation",
72            Self::Commercial => "commercial",
73            Self::Internal => "internal",
74        }
75    }
76
77    /// Does this class permit delegated administration of member subdomains?
78    pub fn permits_delegation(self) -> bool {
79        matches!(self, Self::CommunitySteward | Self::Internal)
80    }
81
82    /// Does this class normally require payment evidence at issuance?
83    pub fn expects_payment(self) -> bool {
84        matches!(self, Self::Commercial)
85    }
86
87    /// True when the class is gratis community/personal/humanitarian.
88    pub fn is_gratis_non_commercial(self) -> bool {
89        matches!(
90            self,
91            Self::Community | Self::CommunitySteward | Self::Personal
92        )
93    }
94}
95
96/// Licensee agent kind — mirrors the QDP `AgentType` token set in
97/// `client-core/domains.rs`. Unknown fails closed.
98#[repr(u8)]
99#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
100pub enum AgentKind {
101    Unknown = 0,
102    NaturalPerson = 1,
103    Organization = 2,
104    AiAgent = 3,
105    HumanitarianService = 4,
106    ContentProvider = 5,
107    Group = 6,
108}
109
110impl AgentKind {
111    /// Parse an agent-kind token (accepts common synonyms); unrecognised
112    /// strings become `Unknown` (fail-closed).
113    pub fn parse(tag: &str) -> Self {
114        match tag.trim().to_ascii_lowercase().as_str() {
115            "person" | "natural-person" => Self::NaturalPerson,
116            "org" | "organization" | "organisation" => Self::Organization,
117            "ai" | "agent" => Self::AiAgent,
118            "service" | "humanitarian" => Self::HumanitarianService,
119            "content" => Self::ContentProvider,
120            "group" => Self::Group,
121            _ => Self::Unknown,
122        }
123    }
124
125    /// Canonical token for the agent kind (inverse of `parse`).
126    pub fn token(self) -> &'static str {
127        match self {
128            Self::Unknown => "unknown",
129            Self::NaturalPerson => "person",
130            Self::Organization => "org",
131            Self::AiAgent => "ai",
132            Self::HumanitarianService => "service",
133            Self::ContentProvider => "content",
134            Self::Group => "group",
135        }
136    }
137}
138
139/// Represented-principal / beneficiary usage classification (`QUALIADB-IMPLEMENTATION-ROADMAP.md` §13).
140///
141/// Prevents commercial entities from acting through natural-person or AI agents to claim
142/// gratis community/personal licensing tiers.
143#[repr(u8)]
144#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
145#[serde(rename_all = "snake_case")]
146pub enum PrincipalCategory {
147    #[default]
148    NaturalPersonDirect = 1,
149    FiduciaryAgentForHumanBeneficiary = 2,
150    NonProfitOrHumanitarianCommunity = 3,
151    CommercialEntityOrPrincipal = 4,
152}
153
154/// Context binding the invoking agent to the represented principal and beneficiary.
155#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
156pub struct RepresentedPrincipalContext {
157    pub invoking_agent_kind: AgentKind,
158    pub represented_principal: PrincipalCategory,
159    pub beneficiary_is_commercial: bool,
160}
161
162impl RepresentedPrincipalContext {
163    /// Returns `true` when the represented principal or beneficiary is commercial,
164    /// regardless of whether the immediate invoking agent is a natural person or AI agent.
165    #[inline]
166    pub const fn requires_commercial_licence(&self) -> bool {
167        matches!(
168            self.represented_principal,
169            PrincipalCategory::CommercialEntityOrPrincipal
170        ) || self.beneficiary_is_commercial
171    }
172}
173
174/// Delegated-administration scope for steward licences (WIP §2-A).
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176pub struct Delegation {
177    #[serde(default)]
178    pub covers_subdomains: bool,
179    #[serde(default)]
180    pub members: Vec<String>,
181    #[serde(default)]
182    pub steward_agreement: String,
183}
184
185/// Payment evidence recorded at issuance (WIP §3).
186#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
187pub struct PaymentEvidence {
188    pub rail: String,
189    pub txid: String,
190    #[serde(default)]
191    pub amount_sats: u64,
192}
193
194/// On-chain anchor carrying the canonical licence digest (WIP §4-B).
195#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
196pub struct ChainAnchor {
197    pub chain: String,
198    pub txid: String,
199    #[serde(default)]
200    pub op_return_hex: String,
201    pub digest: String,
202}
203
204/// A signed domain licence instrument (WIP §3).
205#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
206pub struct DomainLicence {
207    pub format: String,
208    pub licence_id: String,
209    pub issuer_did: String,
210    pub issuer_pubkey_hex: String,
211    pub subject_domains: Vec<String>,
212    #[serde(default)]
213    pub domain_did: String,
214    #[serde(default)]
215    pub delegation: Option<Delegation>,
216    #[serde(default)]
217    pub licensee_did: String,
218    #[serde(default)]
219    pub licensee_agent_type: String,
220    #[serde(default)]
221    pub licensee_label: String,
222    pub licence_class: String,
223    #[serde(default)]
224    pub capability_scope: Vec<String>,
225    #[serde(default)]
226    pub not_before_unix: u64,
227    #[serde(default)]
228    pub expires_unix: u64,
229    #[serde(default)]
230    pub payment_evidence: Option<PaymentEvidence>,
231    #[serde(default)]
232    pub chain_anchors: Vec<ChainAnchor>,
233    #[serde(default)]
234    pub revocation_uri: String,
235    #[serde(default)]
236    pub terms_uri: String,
237    #[serde(default)]
238    pub signature_hex: String,
239}
240
241/// A signed roster amendment chained to a licence by `licence_id` (WIP §7-13).
242#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
243pub struct LicenceAmendment {
244    pub licence_id: String,
245    pub seq: u32,
246    #[serde(default)]
247    pub add_members: Vec<String>,
248    #[serde(default)]
249    pub remove_members: Vec<String>,
250    pub issued_unix: u64,
251    pub signature_hex: String,
252}