Skip to main content

folderbase_core/
template_expansion.rs

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
476/// Re-plan and apply one exact data-only template package under Folderbase's
477/// shared transaction lease.
478///
479/// The caller supplies only the reviewed digest, never a deserialized plan.
480/// Core derives the live plan again after the lease is held and fails before
481/// any template write when it no longer matches the approval.
482pub 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}