Skip to main content

aep_core/
documents.rs

1use std::collections::HashSet;
2
3use serde::{Deserialize, Serialize};
4use url::Url;
5
6use crate::{
7    ParseError, ValidationError, ValidationIssue,
8    validation::{
9        deserialize_optional_non_null, issue, parse_and_validate, require_unique, result,
10    },
11};
12
13pub const SERVICE_DOCUMENTS_EXTENSION: &str =
14    "urn:aep:ext:aep-foundation:service-documents#v=1.0.0";
15pub const MAX_SERVICE_DOCUMENT_BYTES: usize = 1 << 20;
16pub const SERVICE_DOCUMENT_TYPES: &[&str] = &[
17    "acceptable_use_policy",
18    "age_or_parental_consent",
19    "ai_data_use_policy",
20    "community_guidelines",
21    "cookie_policy",
22    "data_processing_agreement",
23    "data_retention_notice",
24    "electronic_signature_consent",
25    "privacy_policy",
26    "security_policy",
27    "subscription_terms",
28    "supplemental_terms",
29    "terms_of_service",
30];
31
32#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
33#[serde(rename_all = "snake_case")]
34pub enum DocumentEnrollment {
35    Required,
36    #[serde(rename = "not-required")]
37    NotRequired,
38}
39
40#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
41pub struct DocumentRepresentation {
42    pub media_type: String,
43    pub url: String,
44}
45
46#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
47pub struct ServiceDocument {
48    pub id: String,
49    #[serde(rename = "type")]
50    pub document_type: String,
51    pub title: String,
52    pub enrollment: DocumentEnrollment,
53    pub representations: Vec<DocumentRepresentation>,
54}
55
56#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
57#[serde(tag = "type", rename_all = "snake_case")]
58pub enum PortableDocumentBlock {
59    Paragraph {
60        text: String,
61    },
62    Section {
63        title: String,
64        blocks: Vec<PortableDocumentBlock>,
65    },
66    BulletedList {
67        items: Vec<String>,
68    },
69    NumberedList {
70        items: Vec<String>,
71    },
72}
73
74#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
75pub struct PortableServiceDocument {
76    pub format: String,
77    pub version: String,
78    pub id: String,
79    #[serde(
80        default,
81        deserialize_with = "deserialize_optional_non_null",
82        skip_serializing_if = "Option::is_none"
83    )]
84    pub summary: Option<Vec<PortableDocumentBlock>>,
85    pub content: Vec<PortableDocumentBlock>,
86}
87
88pub(crate) fn validate_document_ids(ids: &[String], path: &str, issues: &mut Vec<ValidationIssue>) {
89    if ids.len() > 7 || ids.iter().any(|id| !valid_id(id)) {
90        issues.push(issue(
91            path,
92            "Expected at most seven IDs of 1 to 32 ASCII identifier characters.",
93        ));
94    }
95    require_unique(ids, path, issues);
96}
97
98fn valid_id(id: &str) -> bool {
99    (1..=32).contains(&id.len())
100        && id.as_bytes()[0].is_ascii_alphanumeric()
101        && id
102            .bytes()
103            .all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b))
104}
105
106pub fn validate_service_document(document: &ServiceDocument) -> Result<(), ValidationError> {
107    let mut issues = Vec::new();
108    if !valid_id(&document.id) {
109        issues.push(issue(
110            "$.id",
111            "Expected a document ID of 1 to 32 ASCII identifier characters.",
112        ));
113    }
114    if !(1..=64).contains(&document.document_type.len())
115        || !document
116            .document_type
117            .as_bytes()
118            .first()
119            .is_some_and(u8::is_ascii_lowercase)
120        || !document
121            .document_type
122            .bytes()
123            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
124    {
125        issues.push(issue("$.type", "Expected a lowercase document type."));
126    }
127    bounded_text(&document.title, 256, "$.title", &mut issues);
128    let mut media = HashSet::new();
129    if !(1..=8).contains(&document.representations.len()) {
130        issues.push(issue(
131            "$.representations",
132            "Expected 1 to 8 representations.",
133        ));
134    }
135    for representation in &document.representations {
136        if !media.insert(representation.media_type.as_str())
137            || !valid_media_type(&representation.media_type)
138        {
139            issues.push(issue(
140                "$.representations",
141                "Expected distinct lowercase media types without parameters.",
142            ));
143        }
144        if !valid_document_url(&representation.url) {
145            issues.push(issue("$.representations", "Expected an absolute HTTPS URL or literal-loopback HTTP URL, without user information, at most 2048 ASCII characters."));
146        }
147    }
148    if !media.contains("text/html") {
149        issues.push(issue(
150            "$.representations",
151            "Expected an HTML representation.",
152        ));
153    }
154    result("Service Document", issues)
155}
156
157fn valid_media_type(value: &str) -> bool {
158    let Some((kind, subtype)) = value.split_once('/') else {
159        return false;
160    };
161    [kind, subtype].into_iter().all(|part| {
162        part.as_bytes()
163            .first()
164            .is_some_and(|b| b.is_ascii_lowercase() || b.is_ascii_digit())
165            && part
166                .bytes()
167                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"!#$&^_.+-".contains(&b))
168    })
169}
170
171fn valid_document_url(value: &str) -> bool {
172    if value.len() > 2048
173        || !value.is_ascii()
174        || value.bytes().any(|b| b <= 32 || b == 127 || b == b'\\')
175    {
176        return false;
177    }
178    let Some((_, rest)) = value.split_once("://") else {
179        return false;
180    };
181    let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
182    if authority.is_empty() || authority.contains('@') {
183        return false;
184    }
185    let Ok(url) = Url::parse(value) else {
186        return false;
187    };
188    if url.host_str().is_none() {
189        return false;
190    }
191    let literal_host = if authority.starts_with('[') {
192        authority
193            .split_once(']')
194            .map(|(host, _)| format!("{host}]"))
195            .unwrap_or_default()
196    } else {
197        authority
198            .split(':')
199            .next()
200            .unwrap_or_default()
201            .to_ascii_lowercase()
202    };
203    url.scheme() == "https"
204        || (url.scheme() == "http"
205            && matches!(literal_host.as_str(), "localhost" | "127.0.0.1" | "[::1]"))
206}
207
208pub fn parse_portable_service_document(
209    data: &[u8],
210    expected_id: &str,
211) -> Result<PortableServiceDocument, ParseError> {
212    if data.len() > MAX_SERVICE_DOCUMENT_BYTES {
213        return Err(ValidationError {
214            document_type: "portable Service Document".into(),
215            issues: vec![issue("$", "Document exceeds one mebibyte.")],
216        }
217        .into());
218    }
219    parse_and_validate(
220        data,
221        "portable Service Document",
222        |document: &PortableServiceDocument| {
223            validate_portable_service_document(document)?;
224            result(
225                "portable Service Document",
226                if document.id == expected_id {
227                    vec![]
228                } else {
229                    vec![issue(
230                        "$.id",
231                        "Document ID does not match the selected descriptor.",
232                    )]
233                },
234            )
235        },
236    )
237}
238
239pub fn validate_portable_service_document(
240    document: &PortableServiceDocument,
241) -> Result<(), ValidationError> {
242    let mut issues = Vec::new();
243    if document.format != "aep-service-document"
244        || document.version != "1.0"
245        || !valid_id(&document.id)
246    {
247        issues.push(issue("$", "Unsupported document format, version, or ID."));
248    }
249    if document.content.is_empty() || document.summary.as_ref().is_some_and(Vec::is_empty) {
250        issues.push(issue(
251            "$",
252            "Content and supplied summary must contain blocks.",
253        ));
254    }
255    let mut pending: Vec<_> = document
256        .content
257        .iter()
258        .chain(document.summary.iter().flatten())
259        .map(|block| (block, 0))
260        .collect();
261    let mut count = 0;
262    while let Some((block, depth)) = pending.pop() {
263        count += 1;
264        if count > 1024 {
265            issues.push(issue("$", "Expected at most 1024 total blocks."));
266            break;
267        }
268        match block {
269            PortableDocumentBlock::Paragraph { text } => {
270                bounded_text(text, 16384, "$.text", &mut issues)
271            }
272            PortableDocumentBlock::Section { title, blocks } => {
273                bounded_text(title, 256, "$.title", &mut issues);
274                if depth >= 8 || blocks.is_empty() {
275                    issues.push(issue(
276                        "$.blocks",
277                        "Expected nonempty sections at most eight levels deep.",
278                    ));
279                }
280                pending.extend(blocks.iter().map(|block| (block, depth + 1)));
281            }
282            PortableDocumentBlock::BulletedList { items }
283            | PortableDocumentBlock::NumberedList { items } => {
284                if !(1..=128).contains(&items.len()) {
285                    issues.push(issue("$.items", "Expected 1 to 128 list items."));
286                }
287                for text in items {
288                    bounded_text(text, 16384, "$.items", &mut issues);
289                }
290            }
291        }
292    }
293    result("portable Service Document", issues)
294}
295
296fn bounded_text(value: &str, maximum: usize, path: &str, issues: &mut Vec<ValidationIssue>) {
297    if value.is_empty() || value.chars().count() > maximum {
298        issues.push(issue(
299            path,
300            format!("Expected 1 to {maximum} Unicode scalar values."),
301        ));
302    }
303}