Skip to main content

qualia_core_db/services/solid_ldp/
consent.rs

1//! Explicit sanctuary leave choice — never silent.
2//!
3//! Migrating to Solid requires the principal to choose:
4//! 1. **Omit** sanctuary / restricted / bilateral data from the export, or
5//! 2. **Reclassify** (change permission structures) so that data may leave
6//!    for Solid under owner control.
7//!
8//! Classified context **never** leaves, regardless of choice.
9
10use crate::{NQuin, PermissiveRoutingLane};
11
12use super::filter::EgressStats;
13
14/// Principal’s decision when sanctuary-bearing quins are present.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
16pub enum SanctuaryExportChoice {
17    /// No choice recorded — export must fail closed if sanctuary is present.
18    #[default]
19    Unset,
20    /// Leave sanctuary data behind; export only what Solid can hold under
21    /// current public/restricted-off policy.
22    OmitSanctuary,
23    /// Owner accepts that permission structures change so sanctuary/restricted
24    /// data may be projected into Solid (still never classified).
25    ReclassifyForSolid,
26}
27
28impl SanctuaryExportChoice {
29    /// Static string.
30    pub fn as_str(self) -> &'static str {
31        match self {
32            Self::Unset => "unset",
33            Self::OmitSanctuary => "omit-sanctuary",
34            Self::ReclassifyForSolid => "reclassify-for-solid",
35        }
36    }
37
38    /// Builds `SanctuaryExportChoice` from `str`.
39    pub fn from_str(s: &str) -> Option<Self> {
40        match s.trim().to_ascii_lowercase().as_str() {
41            "unset" | "" => Some(Self::Unset),
42            "omit" | "omit-sanctuary" | "leave-behind" => Some(Self::OmitSanctuary),
43            "reclassify" | "reclassify-for-solid" | "include-restricted" => {
44                Some(Self::ReclassifyForSolid)
45            }
46            _ => None,
47        }
48    }
49
50    /// Whether this choice opts sanctuary/restricted into the Solid export.
51    pub fn includes_restricted(self) -> bool {
52        matches!(self, Self::ReclassifyForSolid)
53    }
54}
55
56/// Count how many quins would be sanctuary-gated (excluding classified).
57pub fn count_sanctuary_quins(quins: &[NQuin]) -> usize {
58    quins
59        .iter()
60        .filter_map(|q| {
61            let mut qq = *q;
62            if qq.parity == 0 {
63                qq.recalculate_parity();
64            }
65            qq.verify_ecc_parity().then_some(qq)
66        })
67        .filter(|q| q.get_sensitivity_byte() != NQuin::SENSITIVITY_CLASSIFIED)
68        .filter(|q| is_sanctuary_bearing(q))
69        .count()
70}
71
72/// Counts quins by classification.
73pub fn count_classified_quins(quins: &[NQuin]) -> usize {
74    quins
75        .iter()
76        .filter_map(|q| {
77            let mut qq = *q;
78            if qq.parity == 0 {
79                qq.recalculate_parity();
80            }
81            qq.verify_ecc_parity().then_some(qq)
82        })
83        .filter(|q| q.get_sensitivity_byte() == NQuin::SENSITIVITY_CLASSIFIED)
84        .count()
85}
86
87fn is_sanctuary_bearing(quin: &NQuin) -> bool {
88    match quin.get_sensitivity_byte() {
89        NQuin::SENSITIVITY_RESTRICTED => return true,
90        NQuin::SENSITIVITY_CLASSIFIED => return true,
91        _ => {}
92    }
93    match quin.get_sensitivity_tier() {
94        NQuin::SENSITIVITY_TIER_LEGAL
95        | NQuin::SENSITIVITY_TIER_MEDICAL
96        | NQuin::SENSITIVITY_TIER_FIDUCIARY => return true,
97        _ => {}
98    }
99    quin.identify_routing_lane() == PermissiveRoutingLane::EnforceBilateralMicroCommons
100}
101
102/// Pre-flight notice for desktop / Databox UI before building a leave bundle.
103#[derive(Debug, Clone, PartialEq, Eq)]
104pub struct SanctuaryMigrationNotice {
105    pub sanctuary_quin_count: usize,
106    pub classified_quin_count: usize,
107    pub requires_choice: bool,
108    pub title: String,
109    pub body: String,
110    pub choice_omit_label: String,
111    pub choice_reclassify_label: String,
112    pub classified_note: String,
113}
114
115/// Build the user-facing notice. Call before export when planning a leave.
116pub fn plan_sanctuary_migration_notice(quins: &[NQuin]) -> SanctuaryMigrationNotice {
117    let sanctuary = count_sanctuary_quins(quins);
118    let classified = count_classified_quins(quins);
119    let requires_choice = sanctuary > 0;
120    SanctuaryMigrationNotice {
121        sanctuary_quin_count: sanctuary,
122        classified_quin_count: classified,
123        requires_choice,
124        title: if requires_choice {
125            "Sanctuary data needs a choice before Solid export".into()
126        } else {
127            "Ready to export to Solid".into()
128        },
129        body: if requires_choice {
130            format!(
131                "This graph contains {sanctuary} sanctuary / restricted / bilateral record(s). \
132                 Solid Pods store open RDF triples and quads — not Qualia sanctuary structures. \
133                 You must choose: (1) omit that information from the export, or (2) change \
134                 permission structures so it can be reclassified and exported under your control. \
135                 Classified records ({classified}) never leave this device."
136            )
137        } else if classified > 0 {
138            format!(
139                "No sanctuary-tier records to decide on. {classified} classified record(s) \
140                 will stay on this device and will not appear in the Solid export."
141            )
142        } else {
143            "No sanctuary or classified records detected. You can export the public graph to Solid."
144                .into()
145        },
146        choice_omit_label: "Omit sanctuary data — export only what Solid can hold without reclassification"
147            .into(),
148        choice_reclassify_label:
149            "Reclassify for Solid — I change permissions so sanctuary data may leave as RDF under my control"
150                .into(),
151        classified_note: "Classified context never exports to Solid, regardless of choice.".into(),
152    }
153}
154
155/// Fail closed when sanctuary is present and the principal has not chosen.
156pub fn require_sanctuary_choice(
157    quins: &[NQuin],
158    choice: SanctuaryExportChoice,
159) -> Result<(), String> {
160    let sanctuary = count_sanctuary_quins(quins);
161    if sanctuary == 0 {
162        return Ok(());
163    }
164    match choice {
165        SanctuaryExportChoice::Unset => Err(format!(
166            "SANCTUARY_CHOICE_REQUIRED: {sanctuary} sanctuary/restricted record(s) present. \
167             Choose omit-sanctuary (leave them behind) or reclassify-for-solid (change \
168             permissions so they may export). Classified records never leave. See \
169             plan_sanctuary_migration_notice()."
170        )),
171        SanctuaryExportChoice::OmitSanctuary | SanctuaryExportChoice::ReclassifyForSolid => Ok(()),
172    }
173}
174
175/// Summarise what an export did, for post-export UI.
176pub fn export_outcome_summary(choice: SanctuaryExportChoice, stats: &EgressStats) -> String {
177    match choice {
178        SanctuaryExportChoice::Unset => "No sanctuary choice was recorded.".into(),
179        SanctuaryExportChoice::OmitSanctuary => format!(
180            "Exported {} record(s); omitted {} sanctuary/restricted; classified redacted {}.",
181            stats.exported, stats.redacted_restricted, stats.redacted_classified
182        ),
183        SanctuaryExportChoice::ReclassifyForSolid => format!(
184            "Exported {} record(s) after reclassification consent; classified still redacted {}.",
185            stats.exported, stats.redacted_classified
186        ),
187    }
188}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193    use crate::q_hash;
194
195    fn public_quin() -> NQuin {
196        let mut q = NQuin {
197            subject: q_hash("Alice"),
198            predicate: q_hash("knows"),
199            object: q_hash("Bob"),
200            context: 0,
201            metadata: 0,
202            parity: 0,
203        };
204        q.recalculate_parity();
205        q
206    }
207
208    #[test]
209    fn unset_fails_when_sanctuary_present() {
210        let mut q = public_quin();
211        q.set_sensitivity_byte(NQuin::SENSITIVITY_RESTRICTED);
212        q.recalculate_parity();
213        assert!(require_sanctuary_choice(&[q], SanctuaryExportChoice::Unset).is_err());
214        assert!(require_sanctuary_choice(&[q], SanctuaryExportChoice::OmitSanctuary).is_ok());
215    }
216
217    #[test]
218    fn notice_requires_choice_when_restricted() {
219        let mut q = public_quin();
220        q.set_sensitivity_byte(NQuin::SENSITIVITY_RESTRICTED);
221        q.recalculate_parity();
222        let n = plan_sanctuary_migration_notice(&[q]);
223        assert!(n.requires_choice);
224        assert!(n.body.contains("omit"));
225        assert!(n.body.contains("reclassif"));
226    }
227}