1use std::collections::{BTreeMap, BTreeSet};
2use std::fs;
3use std::io::ErrorKind;
4use std::path::{Component, Path, PathBuf};
5
6use cap_std::fs::Dir;
7use chrono::{DateTime, Utc};
8use semver::Version;
9use serde_json::{Value, json};
10use sha2::{Digest, Sha256};
11use unicode_casefold::UnicodeCaseFold;
12use unicode_normalization::UnicodeNormalization;
13use uuid::Uuid;
14
15use crate::initialization::{
16 canonical_directory, create_directory_no_clobber, ensure_safe_relative,
17 install_text_no_clobber, refuse_symlink_root, sha256_reader, validate_template_path_collisions,
18};
19use crate::model::{AppliedTemplate, TemplateApplicationComparison, TemplateExpansionPrecondition};
20use crate::physical_identity::{PhysicalIdentity, RetainedPhysicalIdentity};
21use crate::template::{
22 render_template_for_capability_destination, template_package_sha256, validate_runtime_package,
23};
24use crate::{
25 FolderbaseError, PlannedTemplateAddition, Result, TemplateAnswerValue,
26 TemplateApplicationCreatedPath, TemplateApplicationRecord, TemplateApplicationResult,
27 TemplateApplicationState, TemplateArtifactKind, TemplateComparisonSource,
28 TemplateExpansionPlan, TemplatePackage, TemplatePlanDigest, TemplateStructuralChange,
29 TemplateStructuralChangeKind, attest_folderbase_root,
30};
31use crate::{
32 folderbase_state::{FolderbaseState, WorkspaceTarget},
33 local_versions::LocalVersionStore,
34};
35
36const MANIFEST: &str = ".folderbase/manifest.json";
37const APPLICATIONS: &str = ".folderbase/template-applications";
38const APPLICATION_SCHEMA: &str =
39 "https://folderbase.ai/protocol/0.2/template-application.schema.json";
40const MAX_TEMPLATE_HISTORY_RECORDS: usize = 4096;
41const MAX_TEMPLATE_APPLICATION_BYTES: u64 = 4 * 1024 * 1024;
42const MAX_TEMPLATE_PATH_ENTRY_WORK: usize = 100_000;
43const MAX_TEMPLATE_PRESERVED_HASH_BYTES: u64 = 1024 * 1024;
44
45pub fn plan_template_expansion(
46 root: impl AsRef<Path>,
47 target: &TemplatePackage,
48 answers: &BTreeMap<String, TemplateAnswerValue>,
49) -> Result<TemplateExpansionPlan> {
50 refuse_symlink_root(root.as_ref())?;
51 let root = canonical_directory(root.as_ref())?;
52 validate_folderbase_root(&root)?;
53 let state = FolderbaseState::open_existing_read_only(&root)?;
54 plan_template_expansion_in_state(&state, target, answers)
55}
56
57fn plan_template_expansion_in_state(
58 state: &FolderbaseState,
59 target: &TemplatePackage,
60 answers: &BTreeMap<String, TemplateAnswerValue>,
61) -> Result<TemplateExpansionPlan> {
62 state.classify_attached_root_boundary().map(drop)?;
63 let root = state.display_root().to_path_buf();
64 validate_runtime_package(&root, target)?;
65
66 let root_identity =
67 RetainedPhysicalIdentity::from_file(state.clone_root_capability()?.into_std_file())
68 .map_err(|source| FolderbaseError::io(&root, source))?;
69 let root_identity_sha256 = root_identity.identity().stable_sha256();
70 let manifest_path = root.join(MANIFEST);
71 let manifest_bytes = state
72 .read_bounded(Path::new(MANIFEST), 2 * 1024 * 1024)?
73 .ok_or_else(|| FolderbaseError::InvalidRecord {
74 path: manifest_path.clone(),
75 message: "Folderbase manifest is missing".to_owned(),
76 })?;
77 let manifest_sha256 = sha256_bytes(&manifest_bytes);
78 let manifest: Value = serde_json::from_slice(&manifest_bytes)
79 .map_err(|source| FolderbaseError::json(&manifest_path, source))?;
80 let folderbase_id =
81 required_string(&manifest, &["folderbase", "id"], &manifest_path)?.to_owned();
82
83 let (history, history_sha256) =
84 read_history_with_snapshot_in_state(state, Some(&folderbase_id))?;
85 validate_application_history_chain(&manifest, &history, &manifest_path)?;
86 let package_digest = TemplatePlanDigest {
87 algorithm: "sha256".to_owned(),
88 digest: template_package_sha256(target)?,
89 };
90 let comparison = derive_comparison(&manifest, &history, target.id(), &manifest_path)?;
91
92 if comparison.template_id != target.id() {
93 return build_plan(
94 root,
95 root_identity,
96 root_identity_sha256,
97 folderbase_id,
98 target,
99 package_digest,
100 comparison,
101 Vec::new(),
102 Vec::new(),
103 Vec::new(),
104 vec![TemplateStructuralChange {
105 kind: TemplateStructuralChangeKind::Lineage,
106 path: None,
107 reason: format!(
108 "template lineage changes from {} to {}",
109 manifest
110 .pointer("/folderbase/template_provenance/id")
111 .and_then(Value::as_str)
112 .unwrap_or("unknown"),
113 target.id()
114 ),
115 }],
116 manifest_sha256,
117 history_sha256,
118 );
119 }
120
121 if comparison.version == target.version() {
122 if comparison.package_digest.digest != package_digest.digest {
123 return Err(FolderbaseError::InvalidRecord {
124 path: root,
125 message: format!(
126 "same template version {} has a different package digest",
127 target.version()
128 ),
129 });
130 }
131 return build_plan(
132 root,
133 root_identity,
134 root_identity_sha256,
135 folderbase_id,
136 target,
137 package_digest,
138 comparison,
139 Vec::new(),
140 Vec::new(),
141 Vec::new(),
142 Vec::new(),
143 manifest_sha256,
144 history_sha256,
145 );
146 }
147
148 let comparison_version =
149 Version::parse(&comparison.version).map_err(|_| FolderbaseError::InvalidRecord {
150 path: manifest_path.clone(),
151 message: format!(
152 "invalid comparison template version: {}",
153 comparison.version
154 ),
155 })?;
156 let target_version =
157 Version::parse(target.version()).map_err(|_| FolderbaseError::InvalidRecord {
158 path: root.clone(),
159 message: format!("invalid target template version: {}", target.version()),
160 })?;
161
162 let mut structural_changes = Vec::new();
163 if target_version < comparison_version {
164 structural_changes.push(TemplateStructuralChange {
165 kind: TemplateStructuralChangeKind::Downgrade,
166 path: None,
167 reason: format!(
168 "template downgrade {} -> {}",
169 comparison.version,
170 target.version()
171 ),
172 });
173 } else if comparison.source != TemplateComparisonSource::Unmanaged
174 && !target
175 .upgrade_edges
176 .iter()
177 .any(|edge| edge.from == comparison.version && edge.to == target.version())
178 {
179 structural_changes.push(TemplateStructuralChange {
180 kind: TemplateStructuralChangeKind::UnsupportedTransition,
181 path: None,
182 reason: format!(
183 "template does not declare an additive edge {} -> {}",
184 comparison.version,
185 target.version()
186 ),
187 });
188 }
189
190 if !structural_changes.is_empty() {
191 return build_plan(
192 root,
193 root_identity,
194 root_identity_sha256,
195 folderbase_id,
196 target,
197 package_digest,
198 comparison,
199 Vec::new(),
200 Vec::new(),
201 Vec::new(),
202 structural_changes,
203 manifest_sha256,
204 history_sha256,
205 );
206 }
207
208 validate_template_paths_against_existing_in_state(
209 state,
210 target
211 .artifacts
212 .iter()
213 .map(|artifact| artifact.target.as_path()),
214 true,
215 )?;
216 let rendered = render_template_for_capability_destination(target, &root, answers)?;
217 let mut rendered = rendered
218 .additions
219 .into_iter()
220 .map(|addition| (addition.path.clone(), addition))
221 .collect::<BTreeMap<_, _>>();
222 let mut additions = Vec::new();
223 let mut preserved_paths = Vec::new();
224 let mut preserved_preconditions = Vec::new();
225 let mut blocked_paths = Vec::new();
226 for artifact in &target.artifacts {
227 match open_template_target(state, &artifact.target)? {
228 WorkspaceTarget::Absent => additions.push(
229 rendered
230 .remove(&artifact.target)
231 .expect("capability renderer returned every validated artifact"),
232 ),
233 WorkspaceTarget::Directory(directory) => {
234 if artifact.kind != TemplateArtifactKind::Directory {
235 blocked_paths.push(artifact.target.clone());
236 continue;
237 }
238 let identity = RetainedPhysicalIdentity::from_file(directory.into_std_file())
239 .map_err(|source| FolderbaseError::io(root.join(&artifact.target), source))?;
240 preserved_paths.push(artifact.target.clone());
241 preserved_preconditions.push(TemplateExpansionPrecondition {
242 path: artifact.target.clone(),
243 kind: artifact.kind,
244 sha256: None,
245 identity,
246 });
247 }
248 WorkspaceTarget::RegularFile(file) => {
249 if artifact.kind != TemplateArtifactKind::Text {
250 blocked_paths.push(artifact.target.clone());
251 continue;
252 }
253 let mut file = file.into_std();
254 let metadata = file
255 .metadata()
256 .map_err(|source| FolderbaseError::io(root.join(&artifact.target), source))?;
257 if metadata.len() > MAX_TEMPLATE_PRESERVED_HASH_BYTES {
258 blocked_paths.push(artifact.target.clone());
259 continue;
260 }
261 let sha256 = sha256_reader(&mut file)
262 .map_err(|source| FolderbaseError::io(root.join(&artifact.target), source))?;
263 let identity = RetainedPhysicalIdentity::from_file(file)
264 .map_err(|source| FolderbaseError::io(root.join(&artifact.target), source))?;
265 preserved_paths.push(artifact.target.clone());
266 preserved_preconditions.push(TemplateExpansionPrecondition {
267 path: artifact.target.clone(),
268 kind: artifact.kind,
269 sha256: Some(sha256),
270 identity,
271 });
272 }
273 }
274 }
275 add_missing_parent_directories_in_state(state, &mut additions)?;
276 validate_template_path_collisions(
277 &root,
278 additions.iter().map(|addition| {
279 (
280 addition.path.as_path(),
281 addition.kind == TemplateArtifactKind::Directory,
282 )
283 }),
284 )?;
285 additions.sort_by(|left, right| left.path.cmp(&right.path));
286 additions.dedup_by(|left, right| left.path == right.path);
287
288 preserved_paths.sort();
289 preserved_preconditions.sort_by(|left, right| left.path.cmp(&right.path));
290 blocked_paths.sort();
291 state.classify_attached_root_boundary().map(drop)?;
292
293 build_plan(
294 root,
295 root_identity,
296 root_identity_sha256,
297 folderbase_id,
298 target,
299 package_digest,
300 comparison,
301 additions,
302 preserved_paths,
303 blocked_paths,
304 structural_changes,
305 manifest_sha256,
306 history_sha256,
307 )
308 .map(|mut plan| {
309 plan.preserved_preconditions = preserved_preconditions;
310 plan.plan_digest = digest_plan(&plan);
311 plan
312 })
313}
314
315pub fn apply_template_expansion(plan: &TemplateExpansionPlan) -> Result<TemplateApplicationResult> {
316 let state = FolderbaseState::open_existing(&plan.root)?;
317 let _lease = LocalVersionStore::acquire_transaction_lock_for_state(&plan.root, &state)?;
318 apply_template_expansion_in_state(&state, plan)
319}
320
321fn apply_template_expansion_in_state(
322 state: &FolderbaseState,
323 plan: &TemplateExpansionPlan,
324) -> Result<TemplateApplicationResult> {
325 if !plan.structural_changes.is_empty() {
326 return Err(FolderbaseError::StructuralTemplateChangeRequiresApproval);
327 }
328 if !plan.blocked_paths.is_empty() {
329 return Err(FolderbaseError::TemplateExpansionBlocked);
330 }
331
332 let root = state.display_root().to_path_buf();
333 state
334 .verify_root_identity(&plan.root_identity.identity())
335 .map_err(|_| FolderbaseError::PlanRootIdentityChanged(root.clone()))?;
336
337 let manifest_bytes = state
338 .read_bounded(Path::new(MANIFEST), 2 * 1024 * 1024)?
339 .ok_or_else(|| FolderbaseError::PlanPreconditionChanged(PathBuf::from(MANIFEST)))?;
340 if sha256_bytes(&manifest_bytes) != plan.manifest_sha256 {
341 return Err(FolderbaseError::PlanPreconditionChanged(PathBuf::from(
342 MANIFEST,
343 )));
344 }
345 let (_, history_sha256) =
346 read_history_with_snapshot_in_state(state, Some(&plan.folderbase_id))?;
347 if history_sha256 != plan.history_sha256 {
348 return Err(FolderbaseError::PlanPreconditionChanged(PathBuf::from(
349 APPLICATIONS,
350 )));
351 }
352 validate_template_paths_against_existing_in_state(
353 state,
354 plan.additions
355 .iter()
356 .map(|addition| addition.path.as_path())
357 .chain(plan.preserved_paths.iter().map(PathBuf::as_path)),
358 true,
359 )?;
360 verify_preserved_preconditions_in_state(state, plan)?;
361 verify_additions_absent_in_state(state, plan)?;
362
363 if plan.is_noop() {
364 return Ok(TemplateApplicationResult {
365 created_paths: Vec::new(),
366 preserved_paths: Vec::new(),
367 application_record: None,
368 });
369 }
370
371 let root_dir = state.clone_root_capability()?;
372 let mut ordered = plan.additions.iter().collect::<Vec<_>>();
373 ordered.sort_by(|left, right| {
374 let left_directory = left.kind == TemplateArtifactKind::Directory;
375 let right_directory = right.kind == TemplateArtifactKind::Directory;
376 right_directory
377 .cmp(&left_directory)
378 .then_with(|| {
379 left.path
380 .components()
381 .count()
382 .cmp(&right.path.components().count())
383 })
384 .then_with(|| left.path.cmp(&right.path))
385 });
386
387 for addition in &ordered {
388 match addition.kind {
389 TemplateArtifactKind::Directory => {
390 create_directory_no_clobber(&root_dir, &root, &addition.path)?;
391 }
392 TemplateArtifactKind::Text => {
393 install_text_no_clobber(
394 &root_dir,
395 &root,
396 &addition.path,
397 addition.content.as_deref().unwrap_or_default().as_bytes(),
398 "template-expansion",
399 )?;
400 }
401 }
402 }
403
404 let created_paths = verify_created_additions_in_state(state, &plan.additions)?;
405 verify_preserved_preconditions_in_state(state, plan)?;
406 let preserved_targets = materialize_preserved_targets_in_state(state, plan)?;
407
408 let application_id = format!("template_application_{}", Uuid::now_v7());
409 let mut record = TemplateApplicationRecord {
410 schema: APPLICATION_SCHEMA.to_owned(),
411 protocol_version: "0.2.0".to_owned(),
412 id: application_id.clone(),
413 folderbase_id: plan.folderbase_id.clone(),
414 state: TemplateApplicationState::Verified,
415 template: AppliedTemplate {
416 id: plan.template_id.clone(),
417 version: plan.template_version.clone(),
418 package_digest: plan.template_package_digest.clone(),
419 },
420 comparison: TemplateApplicationComparison {
421 source: plan.comparison_source,
422 version: plan.comparison_version.clone(),
423 application_id: plan.comparison_application_id.clone(),
424 },
425 applied_at: Utc::now().to_rfc3339(),
426 created_paths,
427 preserved_targets,
428 plan_digest: plan.plan_digest.clone(),
429 record_digest: TemplatePlanDigest {
430 algorithm: "sha256".to_owned(),
431 digest: String::new(),
432 },
433 };
434 record.record_digest = digest_application_record(&record);
435 validate_application_record(&record, Some(&plan.folderbase_id), &root)?;
436
437 ensure_history_directory_in_state(state, &root_dir)?;
438 let record_path = PathBuf::from(APPLICATIONS).join(format!("{application_id}.json"));
439 let mut bytes = serde_json::to_vec_pretty(&record)
440 .map_err(|source| FolderbaseError::json(root.join(&record_path), source))?;
441 bytes.push(b'\n');
442 install_text_no_clobber(
443 &root_dir,
444 &root,
445 &record_path,
446 &bytes,
447 "template-application",
448 )?;
449 let installed_bytes = state
450 .read_bounded(&record_path, MAX_TEMPLATE_APPLICATION_BYTES)?
451 .ok_or_else(|| FolderbaseError::InvalidRecord {
452 path: root.join(&record_path),
453 message: "installed template application record is missing".to_owned(),
454 })?;
455 let installed: TemplateApplicationRecord = serde_json::from_slice(&installed_bytes)
456 .map_err(|source| FolderbaseError::json(root.join(&record_path), source))?;
457 validate_application_record(&installed, Some(&plan.folderbase_id), &root)?;
458 if installed != record {
459 return Err(FolderbaseError::InvalidRecord {
460 path: root.join(&record_path),
461 message: "installed template application record failed verification".to_owned(),
462 });
463 }
464
465 Ok(TemplateApplicationResult {
466 created_paths: plan
467 .additions
468 .iter()
469 .map(|addition| addition.path.clone())
470 .collect(),
471 preserved_paths: plan.preserved_paths.clone(),
472 application_record: Some(record_path),
473 })
474}
475
476pub fn apply_template_expansion_with_expected_plan_digest(
483 root: impl AsRef<Path>,
484 target: &TemplatePackage,
485 answers: &BTreeMap<String, TemplateAnswerValue>,
486 expected_plan_digest: &str,
487) -> Result<(TemplateExpansionPlan, TemplateApplicationResult)> {
488 apply_template_expansion_with_expected_plan_digest_and_hook(
489 root,
490 target,
491 answers,
492 expected_plan_digest,
493 || {},
494 )
495}
496
497fn apply_template_expansion_with_expected_plan_digest_and_hook(
498 root: impl AsRef<Path>,
499 target: &TemplatePackage,
500 answers: &BTreeMap<String, TemplateAnswerValue>,
501 expected_plan_digest: &str,
502 after_lease: impl FnOnce(),
503) -> Result<(TemplateExpansionPlan, TemplateApplicationResult)> {
504 if expected_plan_digest.len() != 64
505 || !expected_plan_digest
506 .bytes()
507 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
508 {
509 return Err(FolderbaseError::InvalidTemplateExpansionPlanDigest);
510 }
511
512 let state = FolderbaseState::open_existing(root.as_ref())?;
513 let _lease = LocalVersionStore::acquire_transaction_lock_for_state(root.as_ref(), &state)?;
514 after_lease();
515 state.classify_attached_root_boundary().map(drop)?;
516 let plan = plan_template_expansion_in_state(&state, target, answers)?;
517 state.classify_attached_root_boundary().map(drop)?;
518 if plan.plan_digest.digest != expected_plan_digest {
519 return Err(FolderbaseError::TemplateExpansionPlanChanged {
520 expected: expected_plan_digest.to_owned(),
521 actual: plan.plan_digest.digest.clone(),
522 });
523 }
524 let result = apply_template_expansion_in_state(&state, &plan)?;
525 Ok((plan, result))
526}
527
528pub fn template_application_history(
529 root: impl AsRef<Path>,
530) -> Result<Vec<TemplateApplicationRecord>> {
531 refuse_symlink_root(root.as_ref())?;
532 let root = canonical_directory(root.as_ref())?;
533 validate_folderbase_root(&root)?;
534 let manifest_path = root.join(MANIFEST);
535 let manifest: Value = serde_json::from_slice(
536 &fs::read(&manifest_path).map_err(|source| FolderbaseError::io(&manifest_path, source))?,
537 )
538 .map_err(|source| FolderbaseError::json(&manifest_path, source))?;
539 let folderbase_id = required_string(&manifest, &["folderbase", "id"], &manifest_path)?;
540 let (history, _) = read_history_with_snapshot(&root, Some(folderbase_id))?;
541 validate_application_history_chain(&manifest, &history, &manifest_path)?;
542 Ok(history)
543}
544
545struct Comparison {
546 template_id: String,
547 version: String,
548 package_digest: TemplatePlanDigest,
549 source: TemplateComparisonSource,
550 application_id: Option<String>,
551}
552
553fn derive_comparison(
554 manifest: &Value,
555 history: &[TemplateApplicationRecord],
556 template_id: &str,
557 manifest_path: &Path,
558) -> Result<Comparison> {
559 let predecessor_ids = history
560 .iter()
561 .filter_map(|record| record.comparison.application_id.as_deref())
562 .collect::<BTreeSet<_>>();
563 let terminals = history
564 .iter()
565 .filter(|record| {
566 record.template.id == template_id && !predecessor_ids.contains(record.id.as_str())
567 })
568 .collect::<Vec<_>>();
569 match terminals.as_slice() {
570 [record] => {
571 return Ok(Comparison {
572 template_id: record.template.id.clone(),
573 version: record.template.version.clone(),
574 package_digest: record.template.package_digest.clone(),
575 source: TemplateComparisonSource::Application,
576 application_id: Some(record.id.clone()),
577 });
578 }
579 [] if history
580 .iter()
581 .all(|record| record.template.id != template_id) => {}
582 _ => {
583 return Err(FolderbaseError::InvalidRecord {
584 path: manifest_path.to_path_buf(),
585 message: format!(
586 "template application history does not have one terminal for {template_id}"
587 ),
588 });
589 }
590 }
591
592 let Some(provenance) = manifest
593 .pointer("/folderbase/template_provenance")
594 .and_then(Value::as_object)
595 else {
596 if history.is_empty() {
597 require_native_unmanaged_lineage(manifest, manifest_path)?;
598 return Ok(Comparison {
599 template_id: template_id.to_owned(),
600 version: "0.0.0".to_owned(),
601 package_digest: TemplatePlanDigest {
602 algorithm: "sha256".to_owned(),
603 digest: format!(
604 "{:x}",
605 Sha256::digest(b"folderbase-unmanaged-template-origin-v1\0")
606 ),
607 },
608 source: TemplateComparisonSource::Unmanaged,
609 application_id: None,
610 });
611 }
612 let predecessor_ids = history
613 .iter()
614 .filter_map(|record| record.comparison.application_id.as_deref())
615 .collect::<BTreeSet<_>>();
616 let terminals = history
617 .iter()
618 .filter(|record| !predecessor_ids.contains(record.id.as_str()))
619 .collect::<Vec<_>>();
620 if let [record] = terminals.as_slice() {
621 return Ok(Comparison {
622 template_id: record.template.id.clone(),
623 version: record.template.version.clone(),
624 package_digest: record.template.package_digest.clone(),
625 source: TemplateComparisonSource::Application,
626 application_id: Some(record.id.clone()),
627 });
628 }
629 return Err(FolderbaseError::InvalidRecord {
630 path: manifest_path.to_path_buf(),
631 message: "template history has no immutable origin".to_owned(),
632 });
633 };
634 let origin_id = provenance
635 .get("id")
636 .and_then(Value::as_str)
637 .ok_or_else(|| FolderbaseError::InvalidRecord {
638 path: manifest_path.to_path_buf(),
639 message: "template origin is missing id".to_owned(),
640 })?;
641 let version = provenance
642 .get("version")
643 .and_then(Value::as_str)
644 .ok_or_else(|| FolderbaseError::InvalidRecord {
645 path: manifest_path.to_path_buf(),
646 message: "template origin is missing version".to_owned(),
647 })?;
648 let package_digest =
649 provenance
650 .get("package_digest")
651 .ok_or_else(|| FolderbaseError::InvalidRecord {
652 path: manifest_path.to_path_buf(),
653 message: "template origin is missing package digest".to_owned(),
654 })?;
655 let package_digest: TemplatePlanDigest = serde_json::from_value(package_digest.clone())
656 .map_err(|source| FolderbaseError::json(manifest_path, source))?;
657 validate_digest(&package_digest, manifest_path)?;
658 Ok(Comparison {
659 template_id: origin_id.to_owned(),
660 version: version.to_owned(),
661 package_digest,
662 source: TemplateComparisonSource::Origin,
663 application_id: None,
664 })
665}
666
667fn validate_application_history_chain(
668 manifest: &Value,
669 history: &[TemplateApplicationRecord],
670 manifest_path: &Path,
671) -> Result<()> {
672 if history.is_empty() {
673 return Ok(());
674 }
675
676 let provenance = manifest
677 .pointer("/folderbase/template_provenance")
678 .and_then(Value::as_object);
679 let origin = provenance
680 .map(|_| {
681 Ok::<_, FolderbaseError>((
682 required_string(
683 manifest,
684 &["folderbase", "template_provenance", "id"],
685 manifest_path,
686 )?,
687 required_string(
688 manifest,
689 &["folderbase", "template_provenance", "version"],
690 manifest_path,
691 )?,
692 ))
693 })
694 .transpose()?;
695 let records_by_id = history
696 .iter()
697 .map(|record| (record.id.as_str(), record))
698 .collect::<BTreeMap<_, _>>();
699 let mut origin_roots = BTreeSet::new();
700 let mut predecessor_ids = BTreeSet::new();
701
702 for record in history {
703 let target_version =
704 Version::parse(&record.template.version).expect("validated application version");
705 let comparison_version =
706 Version::parse(&record.comparison.version).expect("validated comparison version");
707 if target_version <= comparison_version {
708 return Err(FolderbaseError::InvalidRecord {
709 path: manifest_path.to_path_buf(),
710 message: format!(
711 "template application {} does not advance its comparison version",
712 record.id
713 ),
714 });
715 }
716
717 match record.comparison.source {
718 TemplateComparisonSource::Unmanaged => {
719 if !manifest_is_native_v05(manifest)
720 || provenance.is_some()
721 || record.comparison.version != "0.0.0"
722 || !origin_roots.insert(record.template.id.as_str())
723 {
724 return Err(FolderbaseError::InvalidRecord {
725 path: manifest_path.to_path_buf(),
726 message: if !manifest_is_native_v05(manifest) {
727 "unmanaged template lineage requires native protocol 0.5.0".to_owned()
728 } else {
729 format!(
730 "template application {} has invalid unmanaged origin",
731 record.id
732 )
733 },
734 });
735 }
736 }
737 TemplateComparisonSource::Origin => {
738 if let Some((origin_id, origin_version)) = origin {
739 if record.template.id != origin_id
740 || record.comparison.version != origin_version
741 {
742 return Err(FolderbaseError::InvalidRecord {
743 path: manifest_path.to_path_buf(),
744 message: format!(
745 "template application {} does not extend the active template origin",
746 record.id
747 ),
748 });
749 }
750 } else {
751 return Err(FolderbaseError::InvalidRecord {
752 path: manifest_path.to_path_buf(),
753 message: format!(
754 "template application {} claims a missing manifest origin",
755 record.id
756 ),
757 });
758 }
759 if !origin_roots.insert(record.template.id.as_str()) {
760 return Err(FolderbaseError::InvalidRecord {
761 path: manifest_path.to_path_buf(),
762 message: format!(
763 "template application history has multiple origin roots for {}",
764 record.template.id
765 ),
766 });
767 }
768 }
769 TemplateComparisonSource::Application => {
770 let predecessor_id = record
771 .comparison
772 .application_id
773 .as_deref()
774 .expect("validated application comparison id");
775 let predecessor = records_by_id.get(predecessor_id).ok_or_else(|| {
776 FolderbaseError::InvalidRecord {
777 path: manifest_path.to_path_buf(),
778 message: format!("comparison application does not exist: {predecessor_id}"),
779 }
780 })?;
781 if predecessor.folderbase_id != record.folderbase_id
782 || predecessor.template.id != record.template.id
783 || predecessor.template.version != record.comparison.version
784 {
785 return Err(FolderbaseError::InvalidRecord {
786 path: manifest_path.to_path_buf(),
787 message: format!(
788 "comparison application does not match {} template lineage and version",
789 record.id
790 ),
791 });
792 }
793 if parsed_application_time(predecessor) > parsed_application_time(record) {
794 return Err(FolderbaseError::InvalidRecord {
795 path: manifest_path.to_path_buf(),
796 message: format!("comparison application does not precede {}", record.id),
797 });
798 }
799 if !predecessor_ids.insert(predecessor_id) {
800 return Err(FolderbaseError::InvalidRecord {
801 path: manifest_path.to_path_buf(),
802 message: format!("template application history forks at {predecessor_id}"),
803 });
804 }
805 }
806 }
807 }
808
809 Ok(())
810}
811
812fn require_native_unmanaged_lineage(manifest: &Value, manifest_path: &Path) -> Result<()> {
813 if manifest_is_native_v05(manifest) {
814 return Ok(());
815 }
816 Err(FolderbaseError::InvalidRecord {
817 path: manifest_path.to_path_buf(),
818 message: "unmanaged template lineage requires native protocol 0.5.0".to_owned(),
819 })
820}
821
822fn manifest_is_native_v05(manifest: &Value) -> bool {
823 manifest.get("protocol_version").and_then(Value::as_str) == Some("0.5.0")
824}
825
826#[allow(clippy::too_many_arguments)]
827fn build_plan(
828 root: PathBuf,
829 root_identity: RetainedPhysicalIdentity,
830 root_identity_sha256: String,
831 folderbase_id: String,
832 target: &TemplatePackage,
833 template_package_digest: TemplatePlanDigest,
834 comparison: Comparison,
835 additions: Vec<PlannedTemplateAddition>,
836 preserved_paths: Vec<PathBuf>,
837 blocked_paths: Vec<PathBuf>,
838 mut structural_changes: Vec<TemplateStructuralChange>,
839 manifest_sha256: String,
840 history_sha256: String,
841) -> Result<TemplateExpansionPlan> {
842 structural_changes.sort_by(|left, right| {
843 left.kind
844 .cmp(&right.kind)
845 .then_with(|| left.path.cmp(&right.path))
846 });
847 let mut plan = TemplateExpansionPlan {
848 root,
849 folderbase_id,
850 template_id: target.id().to_owned(),
851 comparison_version: comparison.version,
852 comparison_source: comparison.source,
853 comparison_application_id: comparison.application_id,
854 comparison_package_digest: comparison.package_digest,
855 template_version: target.version().to_owned(),
856 template_package_digest,
857 additions,
858 preserved_paths,
859 blocked_paths,
860 structural_changes,
861 plan_digest: TemplatePlanDigest {
862 algorithm: "sha256".to_owned(),
863 digest: String::new(),
864 },
865 manifest_sha256,
866 history_sha256,
867 preserved_preconditions: Vec::new(),
868 root_identity_sha256,
869 root_identity,
870 };
871 plan.plan_digest = digest_plan(&plan);
872 Ok(plan)
873}
874
875fn digest_plan(plan: &TemplateExpansionPlan) -> TemplatePlanDigest {
876 let additions = plan
877 .additions
878 .iter()
879 .map(|addition| {
880 let bytes = addition.content.as_deref().map(str::as_bytes);
881 json!({
882 "path": path_text(&addition.path),
883 "kind": addition.kind,
884 "bytes": bytes.map(|bytes| bytes.len() as u64),
885 "sha256": bytes.map(sha256_bytes),
886 })
887 })
888 .collect::<Vec<_>>();
889 let preserved = plan
890 .preserved_preconditions
891 .iter()
892 .map(|precondition| {
893 json!({
894 "path": path_text(&precondition.path),
895 "kind": precondition.kind,
896 "sha256": precondition.sha256,
897 })
898 })
899 .collect::<Vec<_>>();
900 let structural = plan
901 .structural_changes
902 .iter()
903 .map(|change| {
904 json!({
905 "kind": change.kind,
906 "path": change.path.as_ref().map(|path| path_text(path)),
907 "reason": change.reason,
908 })
909 })
910 .collect::<Vec<_>>();
911 let dto = json!({
912 "folderbase_id": plan.folderbase_id,
913 "root_identity_sha256": plan.root_identity_sha256,
914 "manifest_sha256": plan.manifest_sha256,
915 "history_sha256": plan.history_sha256,
916 "comparison": {
917 "source": plan.comparison_source,
918 "version": plan.comparison_version,
919 "application_id": plan.comparison_application_id,
920 "package_digest": plan.comparison_package_digest,
921 },
922 "target": {
923 "id": plan.template_id,
924 "version": plan.template_version,
925 "package_digest": plan.template_package_digest,
926 },
927 "additions": additions,
928 "preserved": preserved,
929 "blocked": plan.blocked_paths.iter().map(|path| path_text(path)).collect::<Vec<_>>(),
930 "structural": structural,
931 });
932 TemplatePlanDigest {
933 algorithm: "sha256".to_owned(),
934 digest: sha256_bytes(
935 &serde_json::to_vec(&dto).expect("canonical expansion plan DTO serializes"),
936 ),
937 }
938}
939
940fn open_template_target(state: &FolderbaseState, path: &Path) -> Result<WorkspaceTarget> {
941 if path
942 .components()
943 .next()
944 .is_some_and(|component| component.as_os_str() == ".folderbase")
945 {
946 state.open_private_target_nofollow(path)
947 } else {
948 state.open_workspace_target_nofollow(path)
949 }
950}
951
952fn template_directory_names(
953 state: &FolderbaseState,
954 path: &Path,
955 maximum_entries: usize,
956) -> Result<Vec<std::ffi::OsString>> {
957 if path
958 .components()
959 .next()
960 .is_some_and(|component| component.as_os_str() == ".folderbase")
961 {
962 state.private_directory_names(path, maximum_entries)
963 } else {
964 state.workspace_directory_names(path, maximum_entries)
965 }
966}
967
968fn template_path_key(value: &str) -> String {
969 value
970 .nfc()
971 .collect::<String>()
972 .case_fold()
973 .collect::<String>()
974 .nfc()
975 .collect()
976}
977
978fn validate_template_paths_against_existing_in_state<'a>(
979 state: &FolderbaseState,
980 planned_paths: impl IntoIterator<Item = &'a Path>,
981 allow_exact_target: bool,
982) -> Result<()> {
983 let mut remaining_work = MAX_TEMPLATE_PATH_ENTRY_WORK;
984 for planned in planned_paths {
985 let mut parent = PathBuf::new();
986 let component_count = planned.components().count();
987 for (index, component) in planned.components().enumerate() {
988 let Component::Normal(component) = component else {
989 return Err(FolderbaseError::UnsafePath(planned.to_path_buf()));
990 };
991 let component_text = component
992 .to_str()
993 .ok_or_else(|| FolderbaseError::UnsafePath(planned.to_path_buf()))?;
994 let folded = template_path_key(component_text);
995 let names = template_directory_names(state, &parent, remaining_work.saturating_add(1))?;
996 if names.len() > remaining_work {
997 return Err(FolderbaseError::InvalidRecord {
998 path: state.display_root().to_path_buf(),
999 message: format!(
1000 "template path inspection exceeds {MAX_TEMPLATE_PATH_ENTRY_WORK} directory entries"
1001 ),
1002 });
1003 }
1004 remaining_work -= names.len();
1005 let mut exact = false;
1006 for name in names {
1007 let Some(name_text) = name.to_str() else {
1008 continue;
1009 };
1010 if template_path_key(name_text) != folded {
1011 continue;
1012 }
1013 if name == component {
1014 exact = true;
1015 } else {
1016 return Err(FolderbaseError::InvalidRecord {
1017 path: state.display_root().to_path_buf(),
1018 message: format!(
1019 "planned path collision: {} aliases existing {}",
1020 planned.display(),
1021 state.display_root().join(&parent).join(name).display()
1022 ),
1023 });
1024 }
1025 }
1026 if !exact {
1027 break;
1028 }
1029 parent.push(component);
1030 if index + 1 == component_count {
1031 if allow_exact_target {
1032 break;
1033 }
1034 return Err(FolderbaseError::WouldOverwrite(
1035 state.display_root().join(planned),
1036 ));
1037 }
1038 if parent != Path::new(".folderbase")
1039 && !matches!(
1040 open_template_target(state, &parent)?,
1041 WorkspaceTarget::Directory(_)
1042 )
1043 {
1044 return Err(FolderbaseError::InvalidRecord {
1045 path: state.display_root().join(&parent),
1046 message: format!(
1047 "planned path collision: ancestor {} is not a safe directory",
1048 parent.display()
1049 ),
1050 });
1051 }
1052 }
1053 }
1054 Ok(())
1055}
1056
1057fn add_missing_parent_directories_in_state(
1058 state: &FolderbaseState,
1059 additions: &mut Vec<PlannedTemplateAddition>,
1060) -> Result<()> {
1061 let planned = additions
1062 .iter()
1063 .map(|addition| addition.path.clone())
1064 .collect::<Vec<_>>();
1065 let mut extra = BTreeSet::new();
1066 for path in planned {
1067 let Some(parent) = path.parent() else {
1068 continue;
1069 };
1070 let mut relative = PathBuf::new();
1071 for component in parent.components() {
1072 let Component::Normal(component) = component else {
1073 return Err(FolderbaseError::UnsafePath(path));
1074 };
1075 relative.push(component);
1076 if relative == Path::new(".folderbase") {
1077 continue;
1078 }
1079 match open_template_target(state, &relative)? {
1080 WorkspaceTarget::Absent => {
1081 extra.insert(relative.clone());
1082 }
1083 WorkspaceTarget::Directory(_) => {}
1084 WorkspaceTarget::RegularFile(_) => {
1085 return Err(FolderbaseError::UnsafePath(
1086 state.display_root().join(&relative),
1087 ));
1088 }
1089 }
1090 }
1091 }
1092 for path in extra {
1093 if additions.iter().all(|addition| addition.path != path) {
1094 additions.push(PlannedTemplateAddition {
1095 path,
1096 kind: TemplateArtifactKind::Directory,
1097 content: None,
1098 });
1099 }
1100 }
1101 Ok(())
1102}
1103
1104fn validate_folderbase_root(root: &Path) -> Result<()> {
1105 attest_folderbase_root(root)
1106 .map(drop)
1107 .map_err(|source| FolderbaseError::InvalidRecord {
1108 path: root.join(MANIFEST),
1109 message: source.to_string(),
1110 })
1111}
1112
1113fn verify_preserved_preconditions_in_state(
1114 state: &FolderbaseState,
1115 plan: &TemplateExpansionPlan,
1116) -> Result<()> {
1117 for precondition in &plan.preserved_preconditions {
1118 match open_template_target(state, &precondition.path) {
1119 Ok(WorkspaceTarget::Directory(directory))
1120 if precondition.kind == TemplateArtifactKind::Directory =>
1121 {
1122 let file = directory.into_std_file();
1123 let identity = PhysicalIdentity::from_file(&file).map_err(|_| {
1124 FolderbaseError::PlanPreconditionChanged(precondition.path.clone())
1125 })?;
1126 if identity != precondition.identity.identity() {
1127 return Err(FolderbaseError::PlanPreconditionChanged(
1128 precondition.path.clone(),
1129 ));
1130 }
1131 }
1132 Ok(WorkspaceTarget::RegularFile(file))
1133 if precondition.kind == TemplateArtifactKind::Text =>
1134 {
1135 let mut file = file.into_std();
1136 let identity = PhysicalIdentity::from_file(&file).map_err(|_| {
1137 FolderbaseError::PlanPreconditionChanged(precondition.path.clone())
1138 })?;
1139 if identity != precondition.identity.identity() {
1140 return Err(FolderbaseError::PlanPreconditionChanged(
1141 precondition.path.clone(),
1142 ));
1143 }
1144 if let Some(expected) = &precondition.sha256
1145 && sha256_reader(&mut file).map_err(|_| {
1146 FolderbaseError::PlanPreconditionChanged(precondition.path.clone())
1147 })? != *expected
1148 {
1149 return Err(FolderbaseError::PlanPreconditionChanged(
1150 precondition.path.clone(),
1151 ));
1152 }
1153 }
1154 _ => {
1155 return Err(FolderbaseError::PlanPreconditionChanged(
1156 precondition.path.clone(),
1157 ));
1158 }
1159 }
1160 }
1161 Ok(())
1162}
1163
1164fn verify_additions_absent_in_state(
1165 state: &FolderbaseState,
1166 plan: &TemplateExpansionPlan,
1167) -> Result<()> {
1168 for addition in &plan.additions {
1169 ensure_safe_relative(&addition.path)?;
1170 if !matches!(
1171 open_template_target(state, &addition.path)?,
1172 WorkspaceTarget::Absent
1173 ) {
1174 return Err(FolderbaseError::WouldOverwrite(
1175 state.display_root().join(&addition.path),
1176 ));
1177 }
1178 }
1179 Ok(())
1180}
1181
1182fn verify_created_additions_in_state(
1183 state: &FolderbaseState,
1184 additions: &[PlannedTemplateAddition],
1185) -> Result<Vec<TemplateApplicationCreatedPath>> {
1186 let mut created = Vec::new();
1187 for addition in additions {
1188 let (bytes, sha256) = match (addition.kind, open_template_target(state, &addition.path)?) {
1189 (TemplateArtifactKind::Directory, WorkspaceTarget::Directory(_)) => (None, None),
1190 (TemplateArtifactKind::Text, WorkspaceTarget::RegularFile(file)) => {
1191 let mut file = file.into_std();
1192 let metadata = file.metadata().map_err(|source| {
1193 FolderbaseError::io(state.display_root().join(&addition.path), source)
1194 })?;
1195 let digest = sha256_reader(&mut file).map_err(|source| {
1196 FolderbaseError::io(state.display_root().join(&addition.path), source)
1197 })?;
1198 let expected =
1199 sha256_bytes(addition.content.as_deref().unwrap_or_default().as_bytes());
1200 if digest != expected {
1201 return Err(FolderbaseError::InvalidRecord {
1202 path: state.display_root().join(&addition.path),
1203 message: "template addition content digest mismatch".to_owned(),
1204 });
1205 }
1206 (Some(metadata.len()), Some(digest))
1207 }
1208 _ => {
1209 return Err(FolderbaseError::InvalidRecord {
1210 path: state.display_root().join(&addition.path),
1211 message: "template addition failed post-write verification".to_owned(),
1212 });
1213 }
1214 };
1215 created.push(TemplateApplicationCreatedPath {
1216 path: addition.path.clone(),
1217 kind: addition.kind,
1218 bytes,
1219 sha256,
1220 });
1221 }
1222 created.sort_by(|left, right| left.path.cmp(&right.path));
1223 Ok(created)
1224}
1225
1226fn materialize_preserved_targets_in_state(
1227 state: &FolderbaseState,
1228 plan: &TemplateExpansionPlan,
1229) -> Result<Vec<crate::TemplateApplicationPreservedTarget>> {
1230 let mut preserved = Vec::new();
1231 for precondition in &plan.preserved_preconditions {
1232 let (bytes, sha256) = match open_template_target(state, &precondition.path)? {
1233 WorkspaceTarget::Directory(_)
1234 if precondition.kind == TemplateArtifactKind::Directory =>
1235 {
1236 (None, None)
1237 }
1238 WorkspaceTarget::RegularFile(file)
1239 if precondition.kind == TemplateArtifactKind::Text =>
1240 {
1241 let mut file = file.into_std();
1242 let metadata = file.metadata().map_err(|source| {
1243 FolderbaseError::io(state.display_root().join(&precondition.path), source)
1244 })?;
1245 let digest = sha256_reader(&mut file).map_err(|source| {
1246 FolderbaseError::io(state.display_root().join(&precondition.path), source)
1247 })?;
1248 if precondition.sha256.as_ref() != Some(&digest) {
1249 return Err(FolderbaseError::PlanPreconditionChanged(
1250 precondition.path.clone(),
1251 ));
1252 }
1253 (Some(metadata.len()), Some(digest))
1254 }
1255 _ => {
1256 return Err(FolderbaseError::PlanPreconditionChanged(
1257 precondition.path.clone(),
1258 ));
1259 }
1260 };
1261 preserved.push(crate::TemplateApplicationPreservedTarget {
1262 path: precondition.path.clone(),
1263 kind: precondition.kind,
1264 bytes,
1265 sha256,
1266 });
1267 }
1268 preserved.sort_by(|left, right| left.path.cmp(&right.path));
1269 Ok(preserved)
1270}
1271
1272fn ensure_history_directory_in_state(state: &FolderbaseState, root_dir: &Dir) -> Result<()> {
1273 match state.open_private_target_nofollow(Path::new(APPLICATIONS))? {
1274 WorkspaceTarget::Directory(_) => Ok(()),
1275 WorkspaceTarget::Absent => {
1276 create_directory_no_clobber(root_dir, state.display_root(), Path::new(APPLICATIONS))
1277 }
1278 WorkspaceTarget::RegularFile(_) => Err(FolderbaseError::UnsafePath(
1279 state.display_root().join(APPLICATIONS),
1280 )),
1281 }
1282}
1283
1284fn validate_history_path(root: &Path) -> Result<()> {
1285 let protocol_dir = root.join(".folderbase");
1286 let metadata = fs::symlink_metadata(&protocol_dir)
1287 .map_err(|source| FolderbaseError::io(&protocol_dir, source))?;
1288 if metadata.file_type().is_symlink() || !metadata.is_dir() {
1289 return Err(FolderbaseError::UnsafePath(protocol_dir));
1290 }
1291 let expected = "template-applications".case_fold().collect::<String>();
1292 for entry in
1293 fs::read_dir(&protocol_dir).map_err(|source| FolderbaseError::io(&protocol_dir, source))?
1294 {
1295 let entry = entry.map_err(|source| FolderbaseError::io(&protocol_dir, source))?;
1296 let Some(name) = entry.file_name().to_str().map(str::to_owned) else {
1297 continue;
1298 };
1299 if name.case_fold().collect::<String>() == expected && name != "template-applications" {
1300 return Err(FolderbaseError::UnsafePath(entry.path()));
1301 }
1302 }
1303 let history = root.join(APPLICATIONS);
1304 match fs::symlink_metadata(&history) {
1305 Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => Ok(()),
1306 Ok(_) => Err(FolderbaseError::UnsafePath(history)),
1307 Err(source) if source.kind() == ErrorKind::NotFound => Ok(()),
1308 Err(source) => Err(FolderbaseError::io(history, source)),
1309 }
1310}
1311
1312fn read_history_with_snapshot_in_state(
1313 state: &FolderbaseState,
1314 expected_folderbase_id: Option<&str>,
1315) -> Result<(Vec<TemplateApplicationRecord>, String)> {
1316 let expected_name = template_path_key("template-applications");
1317 for name in state.private_directory_names(Path::new(".folderbase"), 4097)? {
1318 let Some(text) = name.to_str() else {
1319 continue;
1320 };
1321 if template_path_key(text) == expected_name && text != "template-applications" {
1322 return Err(FolderbaseError::UnsafePath(
1323 state.display_root().join(".folderbase").join(name),
1324 ));
1325 }
1326 }
1327
1328 let names = match state.open_private_target_nofollow(Path::new(APPLICATIONS))? {
1329 WorkspaceTarget::Absent => return Ok((Vec::new(), sha256_bytes(b"absent"))),
1330 WorkspaceTarget::Directory(_) => state
1331 .private_directory_names(Path::new(APPLICATIONS), MAX_TEMPLATE_HISTORY_RECORDS + 1)?,
1332 WorkspaceTarget::RegularFile(_) => {
1333 return Err(FolderbaseError::UnsafePath(
1334 state.display_root().join(APPLICATIONS),
1335 ));
1336 }
1337 };
1338 if names.len() > MAX_TEMPLATE_HISTORY_RECORDS {
1339 return Err(FolderbaseError::InvalidRecord {
1340 path: state.display_root().join(APPLICATIONS),
1341 message: format!(
1342 "template application history exceeds {MAX_TEMPLATE_HISTORY_RECORDS} records"
1343 ),
1344 });
1345 }
1346 let mut names = names;
1347 names.sort_by(|left, right| left.as_encoded_bytes().cmp(right.as_encoded_bytes()));
1348 let mut snapshot = Sha256::new();
1349 let mut history = Vec::new();
1350 let mut ids = BTreeSet::new();
1351 for name in names {
1352 let Some(name_text) = name.to_str() else {
1353 return Err(FolderbaseError::InvalidRecord {
1354 path: state.display_root().join(APPLICATIONS),
1355 message: "template application history filename is not UTF-8".to_owned(),
1356 });
1357 };
1358 if Path::new(name_text)
1359 .extension()
1360 .and_then(|extension| extension.to_str())
1361 != Some("json")
1362 {
1363 return Err(FolderbaseError::InvalidRecord {
1364 path: state.display_root().join(APPLICATIONS).join(&name),
1365 message: "template application history contains a non-JSON entry".to_owned(),
1366 });
1367 }
1368 let relative = Path::new(APPLICATIONS).join(&name);
1369 let bytes = state
1370 .read_bounded(&relative, MAX_TEMPLATE_APPLICATION_BYTES)?
1371 .ok_or_else(|| FolderbaseError::InvalidRecord {
1372 path: state.display_root().join(&relative),
1373 message: "template application disappeared during planning".to_owned(),
1374 })?;
1375 snapshot.update(name.as_encoded_bytes());
1376 snapshot.update([0]);
1377 snapshot.update(&bytes);
1378 snapshot.update([0]);
1379 let path = state.display_root().join(&relative);
1380 let record: TemplateApplicationRecord = serde_json::from_slice(&bytes)
1381 .map_err(|source| FolderbaseError::json(&path, source))?;
1382 validate_application_record(&record, expected_folderbase_id, &path)?;
1383 if Path::new(name_text)
1384 .file_stem()
1385 .and_then(|stem| stem.to_str())
1386 != Some(record.id.as_str())
1387 {
1388 return Err(FolderbaseError::InvalidRecord {
1389 path,
1390 message: "template application filename does not match record id".to_owned(),
1391 });
1392 }
1393 if !ids.insert(record.id.clone()) {
1394 return Err(FolderbaseError::InvalidRecord {
1395 path,
1396 message: "duplicate template application id".to_owned(),
1397 });
1398 }
1399 history.push(record);
1400 }
1401 history.sort_by(|left, right| {
1402 parsed_application_time(left)
1403 .cmp(&parsed_application_time(right))
1404 .then_with(|| left.id.cmp(&right.id))
1405 });
1406 Ok((history, format!("{:x}", snapshot.finalize())))
1407}
1408
1409fn read_history_with_snapshot(
1410 root: &Path,
1411 expected_folderbase_id: Option<&str>,
1412) -> Result<(Vec<TemplateApplicationRecord>, String)> {
1413 validate_history_path(root)?;
1414 let history_dir = root.join(APPLICATIONS);
1415 if !history_dir.exists() {
1416 return Ok((Vec::new(), sha256_bytes(b"absent")));
1417 }
1418
1419 let mut paths = fs::read_dir(&history_dir)
1420 .map_err(|source| FolderbaseError::io(&history_dir, source))?
1421 .map(|entry| {
1422 entry
1423 .map(|entry| entry.path())
1424 .map_err(|source| FolderbaseError::io(&history_dir, source))
1425 })
1426 .collect::<Result<Vec<_>>>()?;
1427 paths.sort();
1428 let mut snapshot = Sha256::new();
1429 let mut history = Vec::new();
1430 let mut ids = BTreeSet::new();
1431 for path in paths {
1432 let metadata =
1433 fs::symlink_metadata(&path).map_err(|source| FolderbaseError::io(&path, source))?;
1434 if metadata.file_type().is_symlink() || !metadata.is_file() {
1435 return Err(FolderbaseError::UnsafePath(path));
1436 }
1437 if path.extension().and_then(|extension| extension.to_str()) != Some("json") {
1438 return Err(FolderbaseError::InvalidRecord {
1439 path,
1440 message: "template application history contains a non-JSON entry".to_owned(),
1441 });
1442 }
1443 let bytes = fs::read(&path).map_err(|source| FolderbaseError::io(&path, source))?;
1444 snapshot.update(
1445 path.file_name()
1446 .expect("history entry name")
1447 .as_encoded_bytes(),
1448 );
1449 snapshot.update([0]);
1450 snapshot.update(&bytes);
1451 snapshot.update([0]);
1452 let record: TemplateApplicationRecord = serde_json::from_slice(&bytes)
1453 .map_err(|source| FolderbaseError::json(&path, source))?;
1454 validate_application_record(&record, expected_folderbase_id, &path)?;
1455 if path.file_stem().and_then(|stem| stem.to_str()) != Some(record.id.as_str()) {
1456 return Err(FolderbaseError::InvalidRecord {
1457 path,
1458 message: "template application filename does not match record id".to_owned(),
1459 });
1460 }
1461 if !ids.insert(record.id.clone()) {
1462 return Err(FolderbaseError::InvalidRecord {
1463 path,
1464 message: "duplicate template application id".to_owned(),
1465 });
1466 }
1467 history.push(record);
1468 }
1469 history.sort_by(|left, right| {
1470 parsed_application_time(left)
1471 .cmp(&parsed_application_time(right))
1472 .then_with(|| left.id.cmp(&right.id))
1473 });
1474 Ok((history, format!("{:x}", snapshot.finalize())))
1475}
1476
1477fn parsed_application_time(record: &TemplateApplicationRecord) -> DateTime<Utc> {
1478 DateTime::parse_from_rfc3339(&record.applied_at)
1479 .expect("application time was validated")
1480 .with_timezone(&Utc)
1481}
1482
1483fn validate_application_record(
1484 record: &TemplateApplicationRecord,
1485 expected_folderbase_id: Option<&str>,
1486 path: &Path,
1487) -> Result<()> {
1488 if record.schema != APPLICATION_SCHEMA
1489 || record.protocol_version != "0.2.0"
1490 || record.state != TemplateApplicationState::Verified
1491 || !record.id.starts_with("template_application_")
1492 || Uuid::parse_str(record.id.trim_start_matches("template_application_"))
1493 .ok()
1494 .is_none_or(|id| id.get_version_num() != 7)
1495 {
1496 return Err(FolderbaseError::InvalidRecord {
1497 path: path.to_path_buf(),
1498 message: "invalid template application identity or state".to_owned(),
1499 });
1500 }
1501 if expected_folderbase_id.is_some_and(|expected| expected != record.folderbase_id) {
1502 return Err(FolderbaseError::InvalidRecord {
1503 path: path.to_path_buf(),
1504 message: "template application folderbase_id does not match active manifest".to_owned(),
1505 });
1506 }
1507 Version::parse(&record.template.version).map_err(|_| FolderbaseError::InvalidRecord {
1508 path: path.to_path_buf(),
1509 message: "invalid applied template version".to_owned(),
1510 })?;
1511 Version::parse(&record.comparison.version).map_err(|_| FolderbaseError::InvalidRecord {
1512 path: path.to_path_buf(),
1513 message: "invalid comparison template version".to_owned(),
1514 })?;
1515 DateTime::parse_from_rfc3339(&record.applied_at).map_err(|_| {
1516 FolderbaseError::InvalidRecord {
1517 path: path.to_path_buf(),
1518 message: "invalid template application time".to_owned(),
1519 }
1520 })?;
1521 validate_digest(&record.template.package_digest, path)?;
1522 validate_digest(&record.plan_digest, path)?;
1523 validate_digest(&record.record_digest, path)?;
1524 if digest_application_record(record) != record.record_digest {
1525 return Err(FolderbaseError::InvalidRecord {
1526 path: path.to_path_buf(),
1527 message: "template application record digest mismatch".to_owned(),
1528 });
1529 }
1530 if (record.comparison.source == TemplateComparisonSource::Application)
1531 != record.comparison.application_id.is_some()
1532 {
1533 return Err(FolderbaseError::InvalidRecord {
1534 path: path.to_path_buf(),
1535 message: "comparison source and application id disagree".to_owned(),
1536 });
1537 }
1538 let mut seen = BTreeSet::new();
1539 for created in &record.created_paths {
1540 validate_record_path(&created.path, &mut seen, path)?;
1541 match created.kind {
1542 TemplateArtifactKind::Directory
1543 if created.bytes.is_none() && created.sha256.is_none() => {}
1544 TemplateArtifactKind::Text
1545 if created.bytes.is_some()
1546 && created.sha256.as_deref().is_some_and(valid_sha256) => {}
1547 _ => {
1548 return Err(FolderbaseError::InvalidRecord {
1549 path: path.to_path_buf(),
1550 message: "created path metadata does not match its type".to_owned(),
1551 });
1552 }
1553 }
1554 }
1555 for preserved in &record.preserved_targets {
1556 validate_record_path(&preserved.path, &mut seen, path)?;
1557 match preserved.kind {
1558 TemplateArtifactKind::Directory
1559 if preserved.bytes.is_none() && preserved.sha256.is_none() => {}
1560 TemplateArtifactKind::Text
1561 if preserved.bytes.is_some()
1562 && preserved.sha256.as_deref().is_some_and(valid_sha256) => {}
1563 _ => {
1564 return Err(FolderbaseError::InvalidRecord {
1565 path: path.to_path_buf(),
1566 message: "preserved target metadata does not match its type".to_owned(),
1567 });
1568 }
1569 }
1570 }
1571 Ok(())
1572}
1573
1574fn validate_record_path(
1575 relative: &Path,
1576 seen: &mut BTreeSet<String>,
1577 record_path: &Path,
1578) -> Result<()> {
1579 ensure_safe_relative(relative).map_err(|_| FolderbaseError::InvalidRecord {
1580 path: record_path.to_path_buf(),
1581 message: format!("unsafe application path: {}", relative.display()),
1582 })?;
1583 let text = path_text(relative);
1584 if !seen.insert(text.case_fold().collect::<String>()) {
1585 return Err(FolderbaseError::InvalidRecord {
1586 path: record_path.to_path_buf(),
1587 message: format!("duplicate application path: {text}"),
1588 });
1589 }
1590 Ok(())
1591}
1592
1593fn validate_digest(digest: &TemplatePlanDigest, path: &Path) -> Result<()> {
1594 if digest.algorithm != "sha256" || !valid_sha256(&digest.digest) {
1595 return Err(FolderbaseError::InvalidRecord {
1596 path: path.to_path_buf(),
1597 message: "invalid sha256 digest".to_owned(),
1598 });
1599 }
1600 Ok(())
1601}
1602
1603fn valid_sha256(digest: &str) -> bool {
1604 digest.len() == 64
1605 && digest
1606 .bytes()
1607 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
1608}
1609
1610fn required_string<'a>(value: &'a Value, path: &[&str], source: &Path) -> Result<&'a str> {
1611 let mut current = value;
1612 for component in path {
1613 current = current
1614 .get(*component)
1615 .ok_or_else(|| FolderbaseError::InvalidRecord {
1616 path: source.to_path_buf(),
1617 message: format!("missing manifest field {}", path.join(".")),
1618 })?;
1619 }
1620 current
1621 .as_str()
1622 .ok_or_else(|| FolderbaseError::InvalidRecord {
1623 path: source.to_path_buf(),
1624 message: format!("manifest field {} is not a string", path.join(".")),
1625 })
1626}
1627
1628fn sha256_bytes(bytes: &[u8]) -> String {
1629 format!("{:x}", Sha256::digest(bytes))
1630}
1631
1632fn digest_application_record(record: &TemplateApplicationRecord) -> TemplatePlanDigest {
1633 let dto = json!({
1634 "$schema": record.schema,
1635 "protocol_version": record.protocol_version,
1636 "id": record.id,
1637 "folderbase_id": record.folderbase_id,
1638 "state": record.state,
1639 "template": record.template,
1640 "comparison": record.comparison,
1641 "applied_at": record.applied_at,
1642 "created_paths": record.created_paths,
1643 "preserved_targets": record.preserved_targets,
1644 "plan_digest": record.plan_digest,
1645 });
1646 TemplatePlanDigest {
1647 algorithm: "sha256".to_owned(),
1648 digest: sha256_bytes(
1649 &serde_json::to_vec(&dto).expect("canonical application record DTO serializes"),
1650 ),
1651 }
1652}
1653
1654fn path_text(path: &Path) -> String {
1655 path.to_str()
1656 .expect("validated template paths are UTF-8")
1657 .to_owned()
1658}
1659
1660#[cfg(test)]
1661mod capability_security_tests {
1662 use super::*;
1663 use crate::{InitializationOptions, initialize, plan_initialization};
1664
1665 fn package() -> TemplatePackage {
1666 serde_json::from_value(json!({
1667 "protocol_version": "0.2.0",
1668 "id": "example.project",
1669 "version": "1.0.0",
1670 "name": "Capability security fixture",
1671 "suggested_folderbase_kind": "project",
1672 "questions": [],
1673 "artifacts": [{
1674 "target": "Notes/README.md",
1675 "kind": "text",
1676 "content": "# Notes\n",
1677 "install": "create_if_missing"
1678 }],
1679 "upgrade_edges": []
1680 }))
1681 .expect("template package")
1682 }
1683
1684 #[cfg(unix)]
1685 #[test]
1686 fn apply_never_reenters_a_replaced_ambient_root_after_acquiring_its_lease() {
1687 let owner = tempfile::tempdir().expect("fixture owner");
1688 let root = owner.path().join("root");
1689 fs::create_dir(&root).expect("root directory");
1690 initialize(
1691 &plan_initialization(&root, InitializationOptions::default())
1692 .expect("initialization plan"),
1693 )
1694 .expect("initialize root");
1695 let package = package();
1696 let answers = BTreeMap::new();
1697 let reviewed =
1698 plan_template_expansion(&root, &package, &answers).expect("reviewed expansion");
1699 let approved = reviewed.plan_digest().digest().to_owned();
1700 let moved = owner.path().join("moved-root");
1701
1702 let result = apply_template_expansion_with_expected_plan_digest_and_hook(
1703 &root,
1704 &package,
1705 &answers,
1706 &approved,
1707 || {
1708 fs::rename(&root, &moved).expect("detach retained root");
1709 fs::create_dir_all(root.join(".folderbase")).expect("replacement state");
1710 fs::copy(moved.join(MANIFEST), root.join(MANIFEST))
1711 .expect("same manifest in replacement root");
1712 },
1713 );
1714
1715 assert!(result.is_err(), "detached display root must fail closed");
1716 assert!(
1717 !root.join("Notes/README.md").exists(),
1718 "replacement root must never receive template writes"
1719 );
1720 assert!(
1721 !moved.join("Notes/README.md").exists(),
1722 "a detached retained root is not published through an obsolete display path"
1723 );
1724 }
1725}