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}