1use std::{
5 collections::{BTreeMap, BTreeSet},
6 ffi::{OsStr, OsString},
7 io::{Read, Write},
8 path::{Component, Path, PathBuf},
9};
10
11#[cfg(not(windows))]
12use cap_fs_ext::DirExt;
13use cap_fs_ext::{FollowSymlinks, OpenOptionsFollowExt};
14use cap_std::fs::{Dir, OpenOptions as CapOpenOptions};
15use serde::{
16 Deserialize, Serialize,
17 de::{IgnoredAny, SeqAccess, Visitor},
18};
19use sha2::{Digest, Sha256};
20use uuid::Uuid;
21
22use crate::{
23 FolderbaseCaptureError, FolderbaseError,
24 folderbase_seal::{
25 ReconstructedHistoryClosure, ReconstructedTombstoneAssociation,
26 install_reconstructed_history, prepare_reconstructed_history,
27 },
28 folderbase_state::FolderbaseState,
29 folderbase_version::{
30 DeletedKind, FolderbaseVersion, FolderbaseVersionError, MAX_PATH_BYTES,
31 MAX_PATH_COMPONENT_BYTES, PathBindingKind,
32 },
33 local_versions::{
34 LocalObjectRecord, LocalVersionRecord, LocalVersionStore, ObjectId, ObjectLifecycle,
35 ObjectProvenance, VersionId,
36 },
37 migration_filesystem::{
38 publish_retained_directory_noreplace, require_retained_directory_publication,
39 sync_retained_directory,
40 },
41 physical_identity::PhysicalIdentity,
42 root_attestation::{
43 FolderbaseRootAttestation, ManifestProtocolProfile, RootAttestationError,
44 attest_retained_folderbase_root_with_profile, metadata_is_link_or_reparse,
45 open_root_nofollow,
46 },
47 transfer_manifest::{ChunkManifest, ManifestError, ObjectVerificationError},
48 traversal_policy::is_reserved_workspace_component,
49};
50
51pub const PACKAGE_FORMAT_V1: &str = "folderbase-root-reconstruction-package-v1";
52pub const MAX_PACKAGE_INDEX_BYTES: u64 = 8_388_608;
53pub const MAX_PACKAGE_VERSION_BYTES: u64 = 67_108_864;
54pub const MAX_PACKAGE_MANIFEST_BYTES: u64 = 67_108_864;
55pub const MAX_PACKAGE_REFERENCES: usize = 16_385;
56pub const MAX_DISTINCT_MANIFESTS: usize = 16_385;
57pub const MAX_DISTINCT_CHUNKS: usize = 1_048_576;
58pub const MAX_CHUNKS_PER_MANIFEST: usize = 262_144;
59pub const MAX_PACKAGE_OBJECT_BYTES: u64 = 1_099_511_627_776;
60pub const MAX_TOTAL_OBJECT_BYTES: u64 = 9_007_199_254_740_991;
61pub const MAX_VISIBLE_ENTRIES: usize = 16_384;
62const ACTIVE_RECONSTRUCTION_PATH: &str = ".folderbase/local/root-reconstruction/active.json";
63const COMPLETED_RECONSTRUCTION_PATH: &str = ".folderbase/local/root-reconstruction/completed.json";
64const RECONSTRUCTION_OBJECTS_DIRECTORY: &str = ".folderbase/local/root-reconstruction/objects";
65const MAX_RECONSTRUCTION_RECORD_BYTES: u64 = 64 * 1024;
66const FORCE_UNSUPPORTED_FILESYSTEM_ENV: &str =
67 "FOLDERBASE_ROOT_RECONSTRUCTION_CONFORMANCE_FORCE_UNSUPPORTED_FILESYSTEM";
68const STAGE_OWNERSHIP_FORMAT_V1: &str = "folderbase-root-reconstruction-stage-ownership-v1";
69
70pub struct ManifestInput<R> {
72 chunk_manifest_sha256: String,
73 encoded: R,
74}
75
76impl<R> ManifestInput<R> {
77 pub fn new(chunk_manifest_sha256: impl Into<String>, encoded: R) -> Self {
78 Self {
79 chunk_manifest_sha256: chunk_manifest_sha256.into(),
80 encoded,
81 }
82 }
83
84 pub fn digest(&self) -> &str {
85 &self.chunk_manifest_sha256
86 }
87}
88
89#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
90pub enum ReconstructionReferenceRole {
91 RootManifest,
92 LiveRegularFile,
93 RetainedTombstone,
94}
95
96#[derive(Debug, Clone, PartialEq, Eq)]
97pub struct PlannedObjectReference {
98 object_version_id: String,
99 object_id: Option<String>,
100 roles: Vec<ReconstructionReferenceRole>,
101 chunk_manifest_sha256: String,
102}
103
104impl PlannedObjectReference {
105 pub fn object_version_id(&self) -> &str {
106 &self.object_version_id
107 }
108
109 pub fn object_id(&self) -> Option<&str> {
110 self.object_id.as_deref()
111 }
112
113 pub fn roles(&self) -> &[ReconstructionReferenceRole] {
114 &self.roles
115 }
116
117 pub fn chunk_manifest_sha256(&self) -> &str {
118 &self.chunk_manifest_sha256
119 }
120}
121
122#[derive(Debug, Clone, PartialEq, Eq)]
123pub struct PlannedManifest {
124 chunk_manifest_sha256: String,
125 object_sha256: String,
126 object_bytes: u64,
127 chunk_count: usize,
128}
129
130impl PlannedManifest {
131 pub fn chunk_manifest_sha256(&self) -> &str {
132 &self.chunk_manifest_sha256
133 }
134
135 pub fn object_sha256(&self) -> &str {
136 &self.object_sha256
137 }
138
139 pub fn object_bytes(&self) -> u64 {
140 self.object_bytes
141 }
142
143 pub fn chunk_count(&self) -> usize {
144 self.chunk_count
145 }
146}
147
148#[derive(Debug, Clone, PartialEq, Eq)]
149pub struct DerivedSymlink {
150 path: String,
151 object_id: String,
152 object_version_id: String,
153 target: String,
154 content_sha256: String,
155 bytes: u64,
156}
157
158#[derive(Debug, Clone, PartialEq, Eq)]
159pub struct PlannedTombstoneFidelity {
160 path: String,
161 object_id: String,
162 object_version_id: String,
163 executable: bool,
164}
165
166impl PlannedTombstoneFidelity {
167 pub fn path(&self) -> &str {
168 &self.path
169 }
170
171 pub fn object_id(&self) -> &str {
172 &self.object_id
173 }
174
175 pub fn object_version_id(&self) -> &str {
176 &self.object_version_id
177 }
178
179 pub fn executable(&self) -> bool {
180 self.executable
181 }
182}
183
184impl DerivedSymlink {
185 pub fn path(&self) -> &str {
186 &self.path
187 }
188
189 pub fn object_id(&self) -> &str {
190 &self.object_id
191 }
192
193 pub fn object_version_id(&self) -> &str {
194 &self.object_version_id
195 }
196
197 pub fn target(&self) -> &str {
198 &self.target
199 }
200
201 pub fn content_sha256(&self) -> &str {
202 &self.content_sha256
203 }
204
205 pub fn bytes(&self) -> u64 {
206 self.bytes
207 }
208}
209
210#[derive(Debug)]
211pub struct RootReconstructionPlan {
212 package_index_sha256: String,
213 encoded_version_sha256: String,
214 canonical_version_sha256: String,
215 version: FolderbaseVersion,
216 references: Vec<PlannedObjectReference>,
217 manifests: Vec<PlannedManifest>,
218 derived_symlinks: Vec<DerivedSymlink>,
219 tombstone_fidelity: Vec<PlannedTombstoneFidelity>,
220 distinct_chunk_count: usize,
221 total_object_bytes: u64,
222}
223
224pub struct RootReconstructionOperation<'a> {
226 plan: &'a RootReconstructionPlan,
227 operation_id: String,
228 request_sha256: String,
229}
230
231impl<'a> RootReconstructionOperation<'a> {
232 pub fn new(
233 plan: &'a RootReconstructionPlan,
234 operation_id: impl Into<String>,
235 package_index_sha256: impl Into<String>,
236 ) -> Result<Self, RootReconstructionError> {
237 let operation_id = operation_id.into();
238 let package_index_sha256 = package_index_sha256.into();
239 let Some(uuid) = operation_id.strip_prefix("reconstruction_") else {
240 return Err(RootReconstructionError::InvalidOperation);
241 };
242 let parsed =
243 Uuid::parse_str(uuid).map_err(|_| RootReconstructionError::InvalidOperation)?;
244 if parsed.hyphenated().to_string() != uuid || !(1..=8).contains(&parsed.get_version_num()) {
245 return Err(RootReconstructionError::InvalidOperation);
246 }
247 if package_index_sha256 != plan.package_index_sha256() {
248 return Err(RootReconstructionError::PackageIndexPinMismatch);
249 }
250 let request_sha256 =
251 root_reconstruction_request_sha256(&operation_id, &package_index_sha256)?;
252 Ok(Self {
253 plan,
254 operation_id,
255 request_sha256,
256 })
257 }
258
259 pub fn request_sha256(&self) -> &str {
260 &self.request_sha256
261 }
262}
263
264#[derive(Debug, Clone, Copy, PartialEq, Eq)]
265pub enum RootReconstructionPhase {
266 StageEntryDurable,
267 PreparedJournal,
268 VerifiedStaging,
269 Publication,
270 CompletionDurable,
271}
272
273pub struct RetainedReconstructionPackage {
275 root: Dir,
276 display_root: PathBuf,
277}
278
279struct ValidatedPackage {
280 manifests: BTreeMap<String, ChunkManifest>,
281 _manifests_directory: Dir,
282 chunks_directory: Dir,
283 index_identity: PhysicalIdentity,
284 version_identity: PhysicalIdentity,
285 manifests_directory_identity: PhysicalIdentity,
286 chunks_directory_identity: PhysicalIdentity,
287 manifest_identities: BTreeMap<String, PhysicalIdentity>,
288 chunk_identities: BTreeMap<String, PackageRegularIdentity>,
289}
290
291#[derive(Clone, Copy, PartialEq, Eq)]
292struct PackageRegularIdentity {
293 physical: PhysicalIdentity,
294 bytes: u64,
295}
296
297impl RetainedReconstructionPackage {
298 pub fn open(root: impl AsRef<Path>) -> Result<Self, RootReconstructionError> {
299 let display_root = root.as_ref().to_path_buf();
300 let file =
301 open_root_nofollow(&display_root).map_err(|source| RootReconstructionError::Io {
302 path: display_root.clone(),
303 source,
304 })?;
305 let metadata = file
306 .metadata()
307 .map_err(|source| RootReconstructionError::Io {
308 path: display_root.clone(),
309 source,
310 })?;
311 if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
312 return Err(RootReconstructionError::UnsafePackage(display_root));
313 }
314 #[cfg(unix)]
315 {
316 use std::os::unix::fs::PermissionsExt;
317 if metadata.permissions().mode() & 0o022 != 0 {
318 return Err(RootReconstructionError::UnsafePackage(display_root));
319 }
320 }
321 let root = Dir::from_std_file(file);
322 Ok(Self { root, display_root })
323 }
324}
325
326pub struct RetainedReconstructionDestination {
330 parent: Dir,
331 display_parent: PathBuf,
332 name: OsString,
333}
334
335impl RetainedReconstructionDestination {
336 pub fn open(
337 parent: impl AsRef<Path>,
338 name: impl AsRef<OsStr>,
339 ) -> Result<Self, RootReconstructionError> {
340 Self::open_with_preflight(
341 parent.as_ref(),
342 name.as_ref(),
343 std::env::var_os(FORCE_UNSUPPORTED_FILESYSTEM_ENV).is_some(),
344 )
345 }
346
347 fn open_with_preflight(
348 parent: &Path,
349 name: &OsStr,
350 force_unsupported: bool,
351 ) -> Result<Self, RootReconstructionError> {
352 let display_parent = parent.to_path_buf();
353 if force_unsupported {
354 return Err(
355 RootReconstructionError::UnsupportedReconstructionFilesystem {
356 path: display_parent,
357 reason: "conformance seam forced unsupported reconstruction filesystem"
358 .to_owned(),
359 },
360 );
361 }
362 let name = name.to_os_string();
363 if name.is_empty()
364 || Path::new(&name).components().count() != 1
365 || !matches!(
366 Path::new(&name).components().next(),
367 Some(Component::Normal(_))
368 )
369 {
370 return Err(RootReconstructionError::InvalidDestination);
371 }
372 let file =
373 open_root_nofollow(&display_parent).map_err(|source| RootReconstructionError::Io {
374 path: display_parent.clone(),
375 source,
376 })?;
377 let metadata = file
378 .metadata()
379 .map_err(|source| RootReconstructionError::Io {
380 path: display_parent.clone(),
381 source,
382 })?;
383 if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
384 return Err(RootReconstructionError::InvalidDestination);
385 }
386 let parent = Dir::from_std_file(file);
387 match parent.symlink_metadata(&name) {
388 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
389 require_retained_directory_publication(&parent, &display_parent)
390 .map_err(|error| unsupported_publication_error(error, &display_parent))?;
391 }
392 Ok(_) => {}
393 Err(source) => {
394 return Err(RootReconstructionError::Io {
395 path: display_parent.join(&name),
396 source,
397 });
398 }
399 }
400 Ok(Self {
401 parent,
402 display_parent,
403 name,
404 })
405 }
406}
407
408#[derive(Debug, Clone)]
409pub struct RootReconstructionResult {
410 replayed: bool,
411 attestation: FolderbaseRootAttestation,
412}
413
414impl RootReconstructionResult {
415 pub fn replayed(&self) -> bool {
416 self.replayed
417 }
418
419 pub fn attestation(&self) -> &FolderbaseRootAttestation {
420 &self.attestation
421 }
422}
423
424#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
425#[serde(deny_unknown_fields)]
426struct ReconstructionRecord {
427 format: String,
428 operation_id: String,
429 request_sha256: String,
430 package_index_sha256: String,
431 folderbase_id: String,
432 folderbase_version_id: String,
433 canonical_version_sha256: String,
434 visible_entries: usize,
435 external_objects: usize,
436}
437
438#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
439#[serde(deny_unknown_fields)]
440struct ReconstructionCompletion {
441 #[serde(flatten)]
442 operation: ReconstructionRecord,
443 root_instance_sha256: String,
444 manifest_sha256: String,
445}
446
447#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
448#[serde(deny_unknown_fields)]
449struct StageOwnershipRecord {
450 format: String,
451 operation: ReconstructionRecord,
452 staged_name: String,
453 phase: StageOwnershipPhase,
454 physical_identity_sha256: Option<String>,
455}
456
457#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
458#[serde(rename_all = "snake_case")]
459enum StageOwnershipPhase {
460 IntentDurable,
461 StageOwned,
462}
463
464impl RootReconstructionPlan {
465 pub fn package_index_sha256(&self) -> &str {
466 &self.package_index_sha256
467 }
468
469 pub fn encoded_version_sha256(&self) -> &str {
470 &self.encoded_version_sha256
471 }
472
473 pub fn canonical_version_sha256(&self) -> &str {
474 &self.canonical_version_sha256
475 }
476
477 pub fn version(&self) -> &FolderbaseVersion {
478 &self.version
479 }
480
481 pub fn references(&self) -> &[PlannedObjectReference] {
482 &self.references
483 }
484
485 pub fn manifests(&self) -> &[PlannedManifest] {
486 &self.manifests
487 }
488
489 pub fn derived_symlinks(&self) -> &[DerivedSymlink] {
490 &self.derived_symlinks
491 }
492
493 pub fn tombstone_fidelity(&self) -> &[PlannedTombstoneFidelity] {
494 &self.tombstone_fidelity
495 }
496
497 pub fn externally_materialized_object_count(&self) -> usize {
498 self.references.len()
499 }
500
501 pub fn visible_entry_count(&self) -> usize {
502 self.version.binding_count()
503 }
504
505 pub fn distinct_chunk_count(&self) -> usize {
506 self.distinct_chunk_count
507 }
508
509 pub fn total_object_bytes(&self) -> u64 {
510 self.total_object_bytes
511 }
512}
513
514#[derive(Debug, thiserror::Error)]
515pub enum RootReconstructionError {
516 #[error("root reconstruction operation identity is invalid")]
517 InvalidOperation,
518 #[error("root reconstruction package-index pin differs from the validated plan")]
519 PackageIndexPinMismatch,
520 #[error("root reconstruction destination leaf is invalid")]
521 InvalidDestination,
522 #[error("root reconstruction destination is occupied: {0}")]
523 DestinationOccupied(PathBuf),
524 #[error("root reconstruction operation conflicts with retained state")]
525 OperationConflict,
526 #[error("root reconstruction package changed at {0}")]
527 PackageChanged(PathBuf),
528 #[error("root reconstruction package is unsafe at {0}")]
529 UnsafePackage(PathBuf),
530 #[error("root reconstruction filesystem is unsupported at {path}: {reason}")]
531 UnsupportedReconstructionFilesystem { path: PathBuf, reason: String },
532 #[error("root reconstruction filesystem operation failed: {0}")]
533 Filesystem(#[from] FolderbaseError),
534 #[error("root reconstruction history installation failed: {0}")]
535 History(#[from] FolderbaseCaptureError),
536 #[error("reconstructed root attestation failed: {0}")]
537 Attestation(#[from] RootAttestationError),
538 #[error("root reconstruction object verification failed: {0}")]
539 ObjectVerification(#[from] ObjectVerificationError),
540 #[error("root reconstruction I/O failed at {path}: {source}")]
541 Io {
542 path: PathBuf,
543 #[source]
544 source: std::io::Error,
545 },
546 #[error("package index input failed: {0}")]
547 IndexReader(#[source] std::io::Error),
548 #[error("encoded package index exceeds {maximum_bytes} bytes")]
549 IndexTooLarge { maximum_bytes: u64 },
550 #[error("package index is not valid closed JSON: {0}")]
551 InvalidIndexJson(#[source] serde_json::Error),
552 #[error("package index limit declaration is not the fixed v1 declaration")]
553 LimitsMismatch,
554 #[error("package index format is unsupported")]
555 UnknownFormat,
556 #[error("package index contains more than {maximum} references")]
557 TooManyReferences { maximum: usize },
558 #[error("Folderbase Version input failed: {0}")]
559 VersionReader(#[source] std::io::Error),
560 #[error("encoded Folderbase Version exceeds {maximum_bytes} bytes")]
561 VersionTooLarge { maximum_bytes: u64 },
562 #[error("Folderbase Version is invalid: {0}")]
563 InvalidVersion(#[source] FolderbaseVersionError),
564 #[error("package index Folderbase identity differs from the Version")]
565 FolderbaseIdMismatch,
566 #[error("package index Folderbase Version identity differs from the Version")]
567 VersionIdMismatch,
568 #[error("encoded Folderbase Version digest differs from the package index")]
569 EncodedVersionDigestMismatch,
570 #[error("canonical Folderbase Version digest differs from the package index")]
571 CanonicalVersionDigestMismatch,
572 #[error("package references are not strictly ordered by Object Version ID")]
573 ReferencesOutOfOrder,
574 #[error("package contains duplicate Object Version reference {object_version_id}")]
575 DuplicateReference { object_version_id: String },
576 #[error("package reference {object_version_id} has a noncanonical role set")]
577 InvalidReferenceRoles { object_version_id: String },
578 #[error("package reference {object_version_id} is not in the Version closure")]
579 UnexpectedReference { object_version_id: String },
580 #[error("Version closure reference {object_version_id} is missing")]
581 MissingReference { object_version_id: String },
582 #[error("package reference {object_version_id} differs from the Version closure")]
583 ReferenceMismatch { object_version_id: String },
584 #[error("package reference {object_version_id} has an invalid manifest digest")]
585 InvalidManifestDigest { object_version_id: String },
586 #[error("package contains more than {maximum} manifest documents")]
587 TooManyManifests { maximum: usize },
588 #[error("manifest {chunk_manifest_sha256} is not referenced by the Version closure")]
589 UnreferencedManifest { chunk_manifest_sha256: String },
590 #[error("manifest {chunk_manifest_sha256} is supplied more than once")]
591 DuplicateManifest { chunk_manifest_sha256: String },
592 #[error("referenced manifest {chunk_manifest_sha256} is missing")]
593 MissingManifest { chunk_manifest_sha256: String },
594 #[error("manifest {chunk_manifest_sha256} is invalid: {source}")]
595 InvalidManifest {
596 chunk_manifest_sha256: String,
597 #[source]
598 source: ManifestError,
599 },
600 #[error("manifest document does not match its canonical digest {chunk_manifest_sha256}")]
601 ManifestDigestMismatch { chunk_manifest_sha256: String },
602 #[error("package manifests reference more than {maximum} distinct chunks")]
603 TooManyDistinctChunks { maximum: usize },
604 #[error("manifest for {object_version_id} differs from the Version-bound object")]
605 ManifestObjectMismatch { object_version_id: String },
606 #[error("package object bytes exceed the aggregate v1 maximum of {maximum}")]
607 TotalObjectBytesTooLarge { maximum: u64 },
608 #[error("package Tombstone fidelity closure differs from the Folderbase Version")]
609 TombstoneFidelityMismatch,
610}
611
612pub fn execute_root_reconstruction(
619 operation: RootReconstructionOperation<'_>,
620 package: &RetainedReconstructionPackage,
621 destination: &RetainedReconstructionDestination,
622) -> Result<RootReconstructionResult, RootReconstructionError> {
623 execute_root_reconstruction_with_phase_callback(operation, package, destination, |_| {})
624}
625
626#[doc(hidden)]
627pub fn execute_root_reconstruction_with_phase_callback<F>(
628 operation: RootReconstructionOperation<'_>,
629 package: &RetainedReconstructionPackage,
630 destination: &RetainedReconstructionDestination,
631 mut phase: F,
632) -> Result<RootReconstructionResult, RootReconstructionError>
633where
634 F: FnMut(RootReconstructionPhase),
635{
636 let record = reconstruction_record(&operation);
637
638 if let Some(root) = open_directory_if_present(
639 &destination.parent,
640 &destination.name,
641 &destination.display_parent.join(&destination.name),
642 )? {
643 return replay_published_root(&root, destination, &record);
644 }
645 require_package_destination_separation(package, destination)?;
646 let validated_package = revalidate_package(package, operation.plan)?;
647
648 let staged_name = staged_root_name(&operation.operation_id);
649 let staged_display = destination.display_parent.join(&staged_name);
650 let owner_name = stage_owner_name(&operation.operation_id);
651 let (staged, ownership) = acquire_owned_stage(
652 destination,
653 &staged_name,
654 &owner_name,
655 &staged_display,
656 &record,
657 &mut phase,
658 )?;
659
660 ensure_directory(&staged, Path::new(".folderbase"), &staged_display)?;
661 let state = FolderbaseState::from_retained_root(&staged, &staged_display)?;
662 state.ensure_private_dir(Path::new(".folderbase/local/root-reconstruction"))?;
663 state.ensure_private_dir(Path::new(RECONSTRUCTION_OBJECTS_DIRECTORY))?;
664 install_exact_record(&state, Path::new(ACTIVE_RECONSTRUCTION_PATH), &record)?;
665 phase(RootReconstructionPhase::PreparedJournal);
666 require_same_package_identity(
667 package,
668 &validated_package,
669 &revalidate_package(package, operation.plan)?,
670 )?;
671 prepare_reconstructed_history(&state)?;
672
673 let local = LocalVersionStore::for_retained_root(&staged_display);
674 let history = materialize_reconstruction(
675 &staged,
676 &staged_display,
677 &state,
678 &local,
679 package,
680 operation.plan,
681 &validated_package,
682 )?;
683 let (attestation, _, profile) =
684 attest_retained_folderbase_root_with_profile(&staged, &staged_display)?;
685 if attestation.folderbase_id != operation.plan.version().folderbase_id() {
686 return Err(RootReconstructionError::OperationConflict);
687 }
688 require_matching_protocol_profile(operation.plan.version(), &profile)?;
689 install_reconstructed_history(
690 &local,
691 &state,
692 &attestation,
693 operation.plan.version(),
694 operation.plan.canonical_version_sha256(),
695 &history,
696 )?;
697 require_same_package_identity(
698 package,
699 &validated_package,
700 &revalidate_package(package, operation.plan)?,
701 )?;
702 verify_visible_tree(&staged, &staged_display, operation.plan.version())?;
703 phase(RootReconstructionPhase::VerifiedStaging);
704 let verified = attest_retained_folderbase_root_with_profile(&staged, &staged_display)?.0;
705 let completion = ReconstructionCompletion {
706 operation: record.clone(),
707 root_instance_sha256: verified.root_instance_sha256.clone(),
708 manifest_sha256: verified.manifest_sha256.clone(),
709 };
710 install_exact_record(
711 &state,
712 Path::new(COMPLETED_RECONSTRUCTION_PATH),
713 &completion,
714 )?;
715
716 publish_retained_directory_noreplace(
717 &destination.parent,
718 &staged_name,
719 &destination.name,
720 &destination.display_parent,
721 )
722 .map_err(|error| match error {
723 FolderbaseError::WouldOverwrite(path) => RootReconstructionError::DestinationOccupied(path),
724 error => RootReconstructionError::Filesystem(error),
725 })?;
726 let final_display = destination.display_parent.join(&destination.name);
727 let published_root =
728 open_directory_if_present(&destination.parent, &destination.name, &final_display)?
729 .ok_or(RootReconstructionError::OperationConflict)?;
730 if Some(directory_identity_sha256(&published_root, &final_display)?)
731 != ownership.physical_identity_sha256
732 {
733 return Err(RootReconstructionError::OperationConflict);
734 }
735 verify_visible_tree(&published_root, &final_display, operation.plan.version())?;
736 let final_attestation =
737 attest_retained_folderbase_root_with_profile(&published_root, &final_display)?.0;
738 if final_attestation.root_instance_sha256 != completion.root_instance_sha256
739 || final_attestation.manifest_sha256 != completion.manifest_sha256
740 {
741 return Err(RootReconstructionError::OperationConflict);
742 }
743 phase(RootReconstructionPhase::Publication);
744 retire_stage_owner(destination, &owner_name, &ownership, &published_root)?;
745 phase(RootReconstructionPhase::CompletionDurable);
746 Ok(RootReconstructionResult {
747 replayed: false,
748 attestation: final_attestation,
749 })
750}
751
752fn require_package_destination_separation(
753 package: &RetainedReconstructionPackage,
754 destination: &RetainedReconstructionDestination,
755) -> Result<(), RootReconstructionError> {
756 let package_identity = cap_directory_identity(&package.root, &package.display_root)?;
757 let destination_identity =
758 cap_directory_identity(&destination.parent, &destination.display_parent)?;
759 let package_canonical = canonical_retained_directory(
760 &package.root,
761 &package.display_root,
762 RootReconstructionError::PackageChanged(package.display_root.clone()),
763 )?;
764 let destination_canonical = canonical_retained_directory(
765 &destination.parent,
766 &destination.display_parent,
767 RootReconstructionError::InvalidDestination,
768 )?;
769 if package_identity == destination_identity
770 || physical_ancestor_chain_contains(&package_canonical, destination_identity)?
771 || physical_ancestor_chain_contains(&destination_canonical, package_identity)?
772 {
773 return Err(RootReconstructionError::InvalidDestination);
774 }
775 Ok(())
776}
777
778fn canonical_retained_directory(
779 directory: &Dir,
780 display: &Path,
781 mismatch: RootReconstructionError,
782) -> Result<PathBuf, RootReconstructionError> {
783 let canonical =
784 std::fs::canonicalize(display).map_err(|source| RootReconstructionError::Io {
785 path: display.to_path_buf(),
786 source,
787 })?;
788 let canonical_identity =
789 PhysicalIdentity::from_path(&canonical).map_err(|source| RootReconstructionError::Io {
790 path: canonical.clone(),
791 source,
792 })?;
793 if canonical_identity != cap_directory_identity(directory, display)? {
794 return Err(mismatch);
795 }
796 Ok(canonical)
797}
798
799fn physical_ancestor_chain_contains(
800 descendant: &Path,
801 ancestor_identity: PhysicalIdentity,
802) -> Result<bool, RootReconstructionError> {
803 for candidate in descendant.ancestors() {
804 let identity = PhysicalIdentity::from_path(candidate).map_err(|source| {
805 RootReconstructionError::Io {
806 path: candidate.to_path_buf(),
807 source,
808 }
809 })?;
810 if identity == ancestor_identity {
811 return Ok(true);
812 }
813 }
814 Ok(false)
815}
816
817fn reconstruction_record(operation: &RootReconstructionOperation<'_>) -> ReconstructionRecord {
818 ReconstructionRecord {
819 format: "folderbase-root-reconstruction-operation-v1".to_owned(),
820 operation_id: operation.operation_id.clone(),
821 request_sha256: operation.request_sha256.clone(),
822 package_index_sha256: operation.plan.package_index_sha256().to_owned(),
823 folderbase_id: operation.plan.version().folderbase_id().to_owned(),
824 folderbase_version_id: operation.plan.version().version_id().to_owned(),
825 canonical_version_sha256: operation.plan.canonical_version_sha256().to_owned(),
826 visible_entries: operation.plan.visible_entry_count(),
827 external_objects: operation.plan.externally_materialized_object_count(),
828 }
829}
830
831fn require_matching_protocol_profile(
832 version: &FolderbaseVersion,
833 profile: &ManifestProtocolProfile,
834) -> Result<(), RootReconstructionError> {
835 let matches = matches!(
836 (version.protocol_version(), profile),
837 ("0.4", ManifestProtocolProfile::LegacyV01V02)
838 | ("0.5", ManifestProtocolProfile::OrdinaryV05 { .. })
839 );
840 if matches {
841 Ok(())
842 } else {
843 Err(RootReconstructionError::OperationConflict)
844 }
845}
846
847fn unsupported_publication_error(
848 error: FolderbaseError,
849 display: &Path,
850) -> RootReconstructionError {
851 match error {
852 FolderbaseError::UnsupportedMigrationFilesystem { reason, .. } => {
853 RootReconstructionError::UnsupportedReconstructionFilesystem {
854 path: display.to_path_buf(),
855 reason,
856 }
857 }
858 error => RootReconstructionError::Filesystem(error),
859 }
860}
861
862fn staged_root_name(operation_id: &str) -> OsString {
863 OsString::from(format!(
864 ".folderbase-reconstruction-{}.stage",
865 operation_id
866 .strip_prefix("reconstruction_")
867 .expect("validated operation ID")
868 ))
869}
870
871fn stage_owner_name(operation_id: &str) -> OsString {
872 OsString::from(format!(
873 ".folderbase-reconstruction-{}.owner.json",
874 operation_id
875 .strip_prefix("reconstruction_")
876 .expect("validated operation ID")
877 ))
878}
879
880fn stage_proof_name(operation_id: &str) -> OsString {
881 OsString::from(format!(
882 ".folderbase-reconstruction-{}.stage-owned.json",
883 operation_id
884 .strip_prefix("reconstruction_")
885 .expect("validated operation ID")
886 ))
887}
888
889fn acquire_owned_stage<F>(
890 destination: &RetainedReconstructionDestination,
891 staged_name: &OsStr,
892 owner_name: &OsStr,
893 staged_display: &Path,
894 operation: &ReconstructionRecord,
895 phase: &mut F,
896) -> Result<(Dir, StageOwnershipRecord), RootReconstructionError>
897where
898 F: FnMut(RootReconstructionPhase),
899{
900 let owner_display = destination.display_parent.join(owner_name);
901 let proof_name = stage_proof_name(&operation.operation_id);
902 let proof_display = destination.display_parent.join(&proof_name);
903 let expected_intent = StageOwnershipRecord {
904 format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
905 operation: operation.clone(),
906 staged_name: staged_name.to_string_lossy().into_owned(),
907 phase: StageOwnershipPhase::IntentDurable,
908 physical_identity_sha256: None,
909 };
910 let intent = read_parent_regular(
911 &destination.parent,
912 owner_name,
913 &owner_display,
914 MAX_RECONSTRUCTION_RECORD_BYTES,
915 )?;
916 if let Some(encoded) = intent.as_deref() {
917 require_exact_stage_ownership(encoded, &expected_intent)?;
918 } else {
919 if read_parent_regular(
920 &destination.parent,
921 &proof_name,
922 &proof_display,
923 MAX_RECONSTRUCTION_RECORD_BYTES,
924 )?
925 .is_some()
926 || open_owned_stage_if_present(destination, staged_name, staged_display)?.is_some()
927 {
928 return Err(RootReconstructionError::OperationConflict);
929 }
930 write_parent_new(
931 &destination.parent,
932 owner_name,
933 &owner_display,
934 &destination.display_parent,
935 &serde_json::to_vec(&expected_intent)
936 .map_err(|_| RootReconstructionError::OperationConflict)?,
937 )?;
938 }
939
940 let stage = open_owned_stage_if_present(destination, staged_name, staged_display)?;
941 let proof = read_parent_regular(
942 &destination.parent,
943 &proof_name,
944 &proof_display,
945 MAX_RECONSTRUCTION_RECORD_BYTES,
946 )?;
947 match (stage, proof) {
948 (None, None) => {
949 destination
950 .parent
951 .create_dir(staged_name)
952 .map_err(|source| RootReconstructionError::Io {
953 path: staged_display.to_path_buf(),
954 source,
955 })?;
956 sync_retained_directory(&destination.parent, &destination.display_parent)?;
957 let staged = open_owned_stage_if_present(destination, staged_name, staged_display)?
958 .ok_or(RootReconstructionError::OperationConflict)?;
959 phase(RootReconstructionPhase::StageEntryDurable);
960 let ownership = persist_stage_ownership(
961 destination,
962 &staged,
963 staged_name,
964 staged_display,
965 &proof_name,
966 &proof_display,
967 operation,
968 )?;
969 Ok((staged, ownership))
970 }
971 (Some(staged), None) => {
972 let ownership = persist_stage_ownership(
973 destination,
974 &staged,
975 staged_name,
976 staged_display,
977 &proof_name,
978 &proof_display,
979 operation,
980 )?;
981 Ok((staged, ownership))
982 }
983 (Some(staged), Some(encoded)) => {
984 let ownership = decode_stage_ownership(&encoded)?;
985 let actual_identity = directory_identity_sha256(&staged, staged_display)?;
986 if ownership.format != STAGE_OWNERSHIP_FORMAT_V1
987 || ownership.operation != *operation
988 || ownership.staged_name != staged_name.to_string_lossy()
989 || ownership.phase != StageOwnershipPhase::StageOwned
990 || ownership.physical_identity_sha256.as_deref() != Some(actual_identity.as_str())
991 {
992 return Err(RootReconstructionError::OperationConflict);
993 }
994 Ok((staged, ownership))
995 }
996 _ => Err(RootReconstructionError::OperationConflict),
997 }
998}
999
1000fn persist_stage_ownership(
1001 destination: &RetainedReconstructionDestination,
1002 staged: &Dir,
1003 staged_name: &OsStr,
1004 staged_display: &Path,
1005 proof_name: &OsStr,
1006 proof_display: &Path,
1007 operation: &ReconstructionRecord,
1008) -> Result<StageOwnershipRecord, RootReconstructionError> {
1009 let ownership = StageOwnershipRecord {
1010 format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1011 operation: operation.clone(),
1012 staged_name: staged_name.to_string_lossy().into_owned(),
1013 phase: StageOwnershipPhase::StageOwned,
1014 physical_identity_sha256: Some(directory_identity_sha256(staged, staged_display)?),
1015 };
1016 write_parent_new(
1017 &destination.parent,
1018 proof_name,
1019 proof_display,
1020 &destination.display_parent,
1021 &serde_json::to_vec(&ownership).map_err(|_| RootReconstructionError::OperationConflict)?,
1022 )?;
1023 Ok(ownership)
1024}
1025
1026fn open_owned_stage_if_present(
1027 destination: &RetainedReconstructionDestination,
1028 staged_name: &OsStr,
1029 staged_display: &Path,
1030) -> Result<Option<Dir>, RootReconstructionError> {
1031 match open_directory_if_present(&destination.parent, staged_name, staged_display) {
1032 Err(RootReconstructionError::DestinationOccupied(_)) => {
1033 Err(RootReconstructionError::OperationConflict)
1034 }
1035 result => result,
1036 }
1037}
1038
1039fn decode_stage_ownership(encoded: &[u8]) -> Result<StageOwnershipRecord, RootReconstructionError> {
1040 let record: StageOwnershipRecord =
1041 serde_json::from_slice(encoded).map_err(|_| RootReconstructionError::OperationConflict)?;
1042 if serde_json::to_vec(&record).ok().as_deref() != Some(encoded) {
1043 return Err(RootReconstructionError::OperationConflict);
1044 }
1045 Ok(record)
1046}
1047
1048fn require_exact_stage_ownership(
1049 encoded: &[u8],
1050 expected: &StageOwnershipRecord,
1051) -> Result<(), RootReconstructionError> {
1052 if decode_stage_ownership(encoded)? == *expected {
1053 Ok(())
1054 } else {
1055 Err(RootReconstructionError::OperationConflict)
1056 }
1057}
1058
1059fn directory_identity_sha256(
1060 directory: &Dir,
1061 display: &Path,
1062) -> Result<String, RootReconstructionError> {
1063 cap_directory_identity(directory, display).map(PhysicalIdentity::stable_sha256)
1064}
1065
1066fn cap_directory_identity(
1067 directory: &Dir,
1068 display: &Path,
1069) -> Result<PhysicalIdentity, RootReconstructionError> {
1070 let file = directory
1071 .try_clone()
1072 .map_err(|source| RootReconstructionError::Io {
1073 path: display.to_path_buf(),
1074 source,
1075 })?
1076 .into_std_file();
1077 PhysicalIdentity::from_file(&file).map_err(|source| RootReconstructionError::Io {
1078 path: display.to_path_buf(),
1079 source,
1080 })
1081}
1082
1083fn read_parent_regular(
1084 parent: &Dir,
1085 name: &OsStr,
1086 display: &Path,
1087 maximum: u64,
1088) -> Result<Option<Vec<u8>>, RootReconstructionError> {
1089 let mut options = CapOpenOptions::new();
1090 options.read(true).follow(FollowSymlinks::No);
1091 let mut file = match parent.open_with(name, &options) {
1092 Ok(file) => file,
1093 Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1094 Err(source) => {
1095 return Err(RootReconstructionError::Io {
1096 path: display.to_path_buf(),
1097 source,
1098 });
1099 }
1100 };
1101 let metadata = file
1102 .metadata()
1103 .map_err(|source| RootReconstructionError::Io {
1104 path: display.to_path_buf(),
1105 source,
1106 })?;
1107 if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() > maximum {
1108 return Err(RootReconstructionError::OperationConflict);
1109 }
1110 let mut encoded = Vec::new();
1111 Read::by_ref(&mut file)
1112 .take(maximum.saturating_add(1))
1113 .read_to_end(&mut encoded)
1114 .map_err(|source| RootReconstructionError::Io {
1115 path: display.to_path_buf(),
1116 source,
1117 })?;
1118 if encoded.len() as u64 > maximum {
1119 return Err(RootReconstructionError::OperationConflict);
1120 }
1121 Ok(Some(encoded))
1122}
1123
1124fn write_parent_new(
1125 parent: &Dir,
1126 name: &OsStr,
1127 display: &Path,
1128 parent_display: &Path,
1129 encoded: &[u8],
1130) -> Result<(), RootReconstructionError> {
1131 let mut options = CapOpenOptions::new();
1132 options
1133 .write(true)
1134 .create_new(true)
1135 .follow(FollowSymlinks::No);
1136 let mut file =
1137 parent
1138 .open_with(name, &options)
1139 .map_err(|source| RootReconstructionError::Io {
1140 path: display.to_path_buf(),
1141 source,
1142 })?;
1143 file.write_all(encoded)
1144 .and_then(|()| file.sync_all())
1145 .map_err(|source| RootReconstructionError::Io {
1146 path: display.to_path_buf(),
1147 source,
1148 })?;
1149 sync_retained_directory(parent, parent_display)?;
1150 Ok(())
1151}
1152
1153fn retire_stage_owner(
1154 destination: &RetainedReconstructionDestination,
1155 owner_name: &OsStr,
1156 expected: &StageOwnershipRecord,
1157 published_root: &Dir,
1158) -> Result<(), RootReconstructionError> {
1159 let owner_display = destination.display_parent.join(owner_name);
1160 let staged_name = staged_root_name(&expected.operation.operation_id);
1161 let intent = StageOwnershipRecord {
1162 format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1163 operation: expected.operation.clone(),
1164 staged_name: staged_name.to_string_lossy().into_owned(),
1165 phase: StageOwnershipPhase::IntentDurable,
1166 physical_identity_sha256: None,
1167 };
1168 let intent_encoded = read_parent_regular(
1169 &destination.parent,
1170 owner_name,
1171 &owner_display,
1172 MAX_RECONSTRUCTION_RECORD_BYTES,
1173 )?
1174 .ok_or(RootReconstructionError::OperationConflict)?;
1175 require_exact_stage_ownership(&intent_encoded, &intent)?;
1176 let proof_name = stage_proof_name(&expected.operation.operation_id);
1177 let proof_display = destination.display_parent.join(&proof_name);
1178 let proof_encoded = read_parent_regular(
1179 &destination.parent,
1180 &proof_name,
1181 &proof_display,
1182 MAX_RECONSTRUCTION_RECORD_BYTES,
1183 )?
1184 .ok_or(RootReconstructionError::OperationConflict)?;
1185 require_exact_stage_ownership(&proof_encoded, expected)?;
1186 if expected.format != STAGE_OWNERSHIP_FORMAT_V1
1187 || expected.staged_name != staged_name.to_string_lossy()
1188 || expected.phase != StageOwnershipPhase::StageOwned
1189 || directory_identity_sha256(
1190 published_root,
1191 &destination.display_parent.join(&destination.name),
1192 )? != expected
1193 .physical_identity_sha256
1194 .as_deref()
1195 .ok_or(RootReconstructionError::OperationConflict)?
1196 {
1197 return Err(RootReconstructionError::OperationConflict);
1198 }
1199 destination
1200 .parent
1201 .remove_file(&proof_name)
1202 .map_err(|source| RootReconstructionError::Io {
1203 path: proof_display,
1204 source,
1205 })?;
1206 sync_retained_directory(&destination.parent, &destination.display_parent)?;
1207 destination
1208 .parent
1209 .remove_file(owner_name)
1210 .map_err(|source| RootReconstructionError::Io {
1211 path: owner_display,
1212 source,
1213 })?;
1214 sync_retained_directory(&destination.parent, &destination.display_parent)?;
1215 Ok(())
1216}
1217
1218fn retire_stage_owner_after_replay(
1219 destination: &RetainedReconstructionDestination,
1220 expected_operation: &ReconstructionRecord,
1221 published_root: &Dir,
1222) -> Result<(), RootReconstructionError> {
1223 let owner_name = stage_owner_name(&expected_operation.operation_id);
1224 let owner_display = destination.display_parent.join(&owner_name);
1225 let owner = read_parent_regular(
1226 &destination.parent,
1227 &owner_name,
1228 &owner_display,
1229 MAX_RECONSTRUCTION_RECORD_BYTES,
1230 )?;
1231 let proof_name = stage_proof_name(&expected_operation.operation_id);
1232 let proof_display = destination.display_parent.join(&proof_name);
1233 let proof = read_parent_regular(
1234 &destination.parent,
1235 &proof_name,
1236 &proof_display,
1237 MAX_RECONSTRUCTION_RECORD_BYTES,
1238 )?;
1239 let Some(owner) = owner else {
1240 return if proof.is_none() {
1241 Ok(())
1242 } else {
1243 Err(RootReconstructionError::OperationConflict)
1244 };
1245 };
1246 let staged_name = staged_root_name(&expected_operation.operation_id);
1247 let intent = StageOwnershipRecord {
1248 format: STAGE_OWNERSHIP_FORMAT_V1.to_owned(),
1249 operation: expected_operation.clone(),
1250 staged_name: staged_name.to_string_lossy().into_owned(),
1251 phase: StageOwnershipPhase::IntentDurable,
1252 physical_identity_sha256: None,
1253 };
1254 require_exact_stage_ownership(&owner, &intent)?;
1255 if let Some(proof) = proof {
1256 let ownership = decode_stage_ownership(&proof)?;
1257 let actual_identity = directory_identity_sha256(
1258 published_root,
1259 &destination.display_parent.join(&destination.name),
1260 )?;
1261 if ownership.format != STAGE_OWNERSHIP_FORMAT_V1
1262 || ownership.operation != *expected_operation
1263 || ownership.staged_name != staged_name.to_string_lossy()
1264 || ownership.phase != StageOwnershipPhase::StageOwned
1265 || ownership.physical_identity_sha256.as_deref() != Some(actual_identity.as_str())
1266 {
1267 return Err(RootReconstructionError::OperationConflict);
1268 }
1269 destination
1270 .parent
1271 .remove_file(&proof_name)
1272 .map_err(|source| RootReconstructionError::Io {
1273 path: proof_display,
1274 source,
1275 })?;
1276 sync_retained_directory(&destination.parent, &destination.display_parent)?;
1277 }
1278 if intent.operation != *expected_operation {
1279 return Err(RootReconstructionError::OperationConflict);
1280 }
1281 destination
1282 .parent
1283 .remove_file(&owner_name)
1284 .map_err(|source| RootReconstructionError::Io {
1285 path: owner_display,
1286 source,
1287 })?;
1288 sync_retained_directory(&destination.parent, &destination.display_parent)?;
1289 Ok(())
1290}
1291
1292fn open_directory_if_present(
1293 parent: &Dir,
1294 name: &OsStr,
1295 display: &Path,
1296) -> Result<Option<Dir>, RootReconstructionError> {
1297 let metadata = match parent.symlink_metadata(name) {
1298 Ok(metadata) => metadata,
1299 Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
1300 Err(source) => {
1301 return Err(RootReconstructionError::Io {
1302 path: display.to_path_buf(),
1303 source,
1304 });
1305 }
1306 };
1307 if metadata.file_type().is_symlink() || !metadata.is_dir() {
1308 return Err(RootReconstructionError::DestinationOccupied(
1309 display.to_path_buf(),
1310 ));
1311 }
1312 parent
1313 .open_dir_nofollow(name)
1314 .map(Some)
1315 .map_err(|source| RootReconstructionError::Io {
1316 path: display.to_path_buf(),
1317 source,
1318 })
1319}
1320
1321fn replay_published_root(
1322 root: &Dir,
1323 destination: &RetainedReconstructionDestination,
1324 expected: &ReconstructionRecord,
1325) -> Result<RootReconstructionResult, RootReconstructionError> {
1326 let display = destination.display_parent.join(&destination.name);
1327 match replay_published_root_exact(root, destination, expected) {
1328 Ok(result) => Ok(result),
1329 Err(PublishedReplayError::NotExact) => {
1330 Err(RootReconstructionError::DestinationOccupied(display))
1331 }
1332 Err(PublishedReplayError::Operational(error)) => Err(error),
1333 }
1334}
1335
1336enum PublishedReplayError {
1337 NotExact,
1338 Operational(RootReconstructionError),
1339}
1340
1341impl From<RootReconstructionError> for PublishedReplayError {
1342 fn from(error: RootReconstructionError) -> Self {
1343 Self::Operational(error)
1344 }
1345}
1346
1347fn replay_published_root_exact(
1348 root: &Dir,
1349 destination: &RetainedReconstructionDestination,
1350 expected: &ReconstructionRecord,
1351) -> Result<RootReconstructionResult, PublishedReplayError> {
1352 let display = destination.display_parent.join(&destination.name);
1353 let state = match FolderbaseState::from_retained_root(root, &display) {
1354 Ok(state) => state,
1355 Err(FolderbaseError::Io { source, .. })
1356 if source.kind() == std::io::ErrorKind::NotFound =>
1357 {
1358 return Err(PublishedReplayError::NotExact);
1359 }
1360 Err(error) => {
1361 return Err(PublishedReplayError::Operational(
1362 RootReconstructionError::Filesystem(error),
1363 ));
1364 }
1365 };
1366 let Some(bytes) = state
1367 .read_bounded(
1368 Path::new(COMPLETED_RECONSTRUCTION_PATH),
1369 MAX_RECONSTRUCTION_RECORD_BYTES,
1370 )
1371 .map_err(|error| {
1372 PublishedReplayError::Operational(RootReconstructionError::Filesystem(error))
1373 })?
1374 else {
1375 return Err(PublishedReplayError::NotExact);
1376 };
1377 let completion: ReconstructionCompletion =
1378 serde_json::from_slice(&bytes).map_err(|_| PublishedReplayError::NotExact)?;
1379 if serde_json::to_vec(&completion).ok().as_deref() != Some(bytes.as_slice())
1380 || &completion.operation != expected
1381 {
1382 return Err(PublishedReplayError::NotExact);
1383 }
1384 let (attestation, _, profile) = attest_retained_folderbase_root_with_profile(root, &display)
1385 .map_err(|error| match &error {
1386 RootAttestationError::Io { source, .. }
1387 if source.kind() == std::io::ErrorKind::NotFound =>
1388 {
1389 PublishedReplayError::NotExact
1390 }
1391 RootAttestationError::Io { .. }
1392 | RootAttestationError::RootChangedDuringAttestation
1393 | RootAttestationError::PhysicalIdentityUnavailable => {
1394 PublishedReplayError::Operational(RootReconstructionError::Attestation(error))
1395 }
1396 _ => PublishedReplayError::NotExact,
1397 })?;
1398 if attestation.folderbase_id != expected.folderbase_id
1399 || attestation.root_instance_sha256 != completion.root_instance_sha256
1400 || attestation.manifest_sha256 != completion.manifest_sha256
1401 {
1402 return Err(PublishedReplayError::NotExact);
1403 }
1404 let version_bytes = state
1405 .read_bounded(
1406 &Path::new(".folderbase/versions/folderbase")
1407 .join(format!("{}.json", expected.folderbase_version_id)),
1408 MAX_PACKAGE_VERSION_BYTES,
1409 )
1410 .map_err(|error| {
1411 PublishedReplayError::Operational(RootReconstructionError::Filesystem(error))
1412 })?
1413 .ok_or(PublishedReplayError::NotExact)?;
1414 let version = FolderbaseVersion::decode_bounded(version_bytes.as_slice())
1415 .map_err(|_| PublishedReplayError::NotExact)?;
1416 if version
1417 .canonical_digest()
1418 .map_err(|_| PublishedReplayError::NotExact)?
1419 != expected.canonical_version_sha256
1420 {
1421 return Err(PublishedReplayError::NotExact);
1422 }
1423 require_matching_protocol_profile(&version, &profile)
1424 .map_err(|_| PublishedReplayError::NotExact)?;
1425 verify_visible_tree(root, &display, &version).map_err(|error| match error {
1426 RootReconstructionError::OperationConflict => PublishedReplayError::NotExact,
1427 error => PublishedReplayError::Operational(error),
1428 })?;
1429 retire_stage_owner_after_replay(destination, expected, root)
1430 .map_err(PublishedReplayError::Operational)?;
1431 Ok(RootReconstructionResult {
1432 replayed: true,
1433 attestation,
1434 })
1435}
1436
1437fn install_exact_record<T: Serialize>(
1438 state: &FolderbaseState,
1439 path: &Path,
1440 record: &T,
1441) -> Result<(), RootReconstructionError> {
1442 let encoded =
1443 serde_json::to_vec(record).map_err(|_| RootReconstructionError::OperationConflict)?;
1444 match state.publish_new(path, &encoded) {
1445 Ok(()) => Ok(()),
1446 Err(FolderbaseError::WouldOverwrite(_)) => {
1447 if state
1448 .read_bounded(path, MAX_RECONSTRUCTION_RECORD_BYTES)?
1449 .as_deref()
1450 == Some(encoded.as_slice())
1451 {
1452 Ok(())
1453 } else {
1454 Err(RootReconstructionError::OperationConflict)
1455 }
1456 }
1457 Err(error) => Err(error.into()),
1458 }
1459}
1460
1461fn revalidate_package(
1462 package: &RetainedReconstructionPackage,
1463 plan: &RootReconstructionPlan,
1464) -> Result<ValidatedPackage, RootReconstructionError> {
1465 let (index, index_identity) = read_package_regular_with_identity(
1466 package,
1467 Path::new("index.json"),
1468 MAX_PACKAGE_INDEX_BYTES,
1469 )?;
1470 if sha256(&index) != plan.package_index_sha256() {
1471 return Err(RootReconstructionError::PackageChanged(
1472 package.display_root.join("index.json"),
1473 ));
1474 }
1475 let (version, version_identity) = read_package_regular_with_identity(
1476 package,
1477 Path::new("version.json"),
1478 MAX_PACKAGE_VERSION_BYTES,
1479 )?;
1480 if sha256(&version) != plan.encoded_version_sha256() {
1481 return Err(RootReconstructionError::PackageChanged(
1482 package.display_root.join("version.json"),
1483 ));
1484 }
1485 let decoded = FolderbaseVersion::decode_bounded(version.as_slice())
1486 .map_err(RootReconstructionError::InvalidVersion)?;
1487 if decoded
1488 .canonical_digest()
1489 .map_err(RootReconstructionError::InvalidVersion)?
1490 != plan.canonical_version_sha256()
1491 {
1492 return Err(RootReconstructionError::PackageChanged(
1493 package.display_root.join("version.json"),
1494 ));
1495 }
1496
1497 require_exact_entries(
1498 &package.root,
1499 &package.display_root,
1500 &["chunks", "index.json", "manifests", "version.json"]
1501 .into_iter()
1502 .map(str::to_owned)
1503 .collect(),
1504 )?;
1505 let manifests_dir = open_package_directory(package, "manifests")?;
1506 let chunks_dir = open_package_directory(package, "chunks")?;
1507 let manifests_directory_identity =
1508 cap_directory_identity(&manifests_dir, &package.display_root.join("manifests"))?;
1509 let chunks_directory_identity =
1510 cap_directory_identity(&chunks_dir, &package.display_root.join("chunks"))?;
1511 let mut manifests = BTreeMap::new();
1512 let mut manifest_identities = BTreeMap::new();
1513 let mut manifest_names = BTreeSet::new();
1514 let mut chunk_names = BTreeSet::new();
1515 for planned in plan.manifests() {
1516 let name = format!("{}.json", planned.chunk_manifest_sha256());
1517 manifest_names.insert(name.clone());
1518 let (encoded, identity) = read_regular_from_with_identity(
1519 &manifests_dir,
1520 &package.display_root.join("manifests").join(&name),
1521 Path::new(&name),
1522 MAX_PACKAGE_MANIFEST_BYTES,
1523 )?;
1524 manifest_identities.insert(name.clone(), identity);
1525 let manifest = ChunkManifest::decode_slice_bounded(&encoded).map_err(|source| {
1526 RootReconstructionError::InvalidManifest {
1527 chunk_manifest_sha256: planned.chunk_manifest_sha256().to_owned(),
1528 source,
1529 }
1530 })?;
1531 if manifest.canonical_digest().ok().as_deref() != Some(planned.chunk_manifest_sha256())
1532 || manifest.object_sha256 != planned.object_sha256()
1533 || manifest.object_bytes != planned.object_bytes()
1534 || manifest.chunks.len() != planned.chunk_count()
1535 {
1536 return Err(RootReconstructionError::PackageChanged(
1537 package.display_root.join("manifests").join(name),
1538 ));
1539 }
1540 chunk_names.extend(manifest.chunks.iter().map(|chunk| chunk.sha256.clone()));
1541 manifests.insert(planned.chunk_manifest_sha256().to_owned(), manifest);
1542 }
1543 require_exact_entries(
1544 &manifests_dir,
1545 &package.display_root.join("manifests"),
1546 &manifest_names,
1547 )?;
1548 require_exact_entries(
1549 &chunks_dir,
1550 &package.display_root.join("chunks"),
1551 &chunk_names,
1552 )?;
1553 let mut chunk_identities = BTreeMap::new();
1554 for name in &chunk_names {
1555 let display = package.display_root.join("chunks").join(name);
1556 let file = open_regular_from(&chunks_dir, &display, Path::new(name))?;
1557 let metadata = file
1558 .metadata()
1559 .map_err(|source| RootReconstructionError::Io {
1560 path: display.clone(),
1561 source,
1562 })?;
1563 validate_package_regular_metadata(&metadata, &display)?;
1564 chunk_identities.insert(
1565 name.clone(),
1566 PackageRegularIdentity {
1567 physical: cap_file_identity(&file, &display)?,
1568 bytes: metadata.len(),
1569 },
1570 );
1571 }
1572 Ok(ValidatedPackage {
1573 manifests,
1574 _manifests_directory: manifests_dir,
1575 chunks_directory: chunks_dir,
1576 index_identity,
1577 version_identity,
1578 manifests_directory_identity,
1579 chunks_directory_identity,
1580 manifest_identities,
1581 chunk_identities,
1582 })
1583}
1584
1585fn require_same_package_identity(
1586 package: &RetainedReconstructionPackage,
1587 expected: &ValidatedPackage,
1588 actual: &ValidatedPackage,
1589) -> Result<(), RootReconstructionError> {
1590 if expected.index_identity != actual.index_identity
1591 || expected.version_identity != actual.version_identity
1592 || expected.manifests_directory_identity != actual.manifests_directory_identity
1593 || expected.chunks_directory_identity != actual.chunks_directory_identity
1594 || expected.manifest_identities != actual.manifest_identities
1595 || expected.chunk_identities != actual.chunk_identities
1596 {
1597 return Err(RootReconstructionError::PackageChanged(
1598 package.display_root.clone(),
1599 ));
1600 }
1601 Ok(())
1602}
1603
1604fn open_package_directory(
1605 package: &RetainedReconstructionPackage,
1606 name: &str,
1607) -> Result<Dir, RootReconstructionError> {
1608 let directory =
1609 package
1610 .root
1611 .open_dir_nofollow(name)
1612 .map_err(|source| RootReconstructionError::Io {
1613 path: package.display_root.join(name),
1614 source,
1615 })?;
1616 let metadata = directory
1617 .dir_metadata()
1618 .map_err(|source| RootReconstructionError::Io {
1619 path: package.display_root.join(name),
1620 source,
1621 })?;
1622 #[cfg(unix)]
1623 {
1624 use cap_std::fs::PermissionsExt;
1625 if metadata.permissions().mode() & 0o022 != 0 {
1626 return Err(RootReconstructionError::UnsafePackage(
1627 package.display_root.join(name),
1628 ));
1629 }
1630 }
1631 Ok(directory)
1632}
1633
1634fn require_exact_entries(
1635 directory: &Dir,
1636 display: &Path,
1637 expected: &BTreeSet<String>,
1638) -> Result<(), RootReconstructionError> {
1639 let mut actual = BTreeSet::new();
1640 let maximum_observations = expected.len().saturating_add(1);
1641 for entry in directory
1642 .entries()
1643 .map_err(|source| RootReconstructionError::Io {
1644 path: display.to_path_buf(),
1645 source,
1646 })?
1647 {
1648 if actual.len() >= maximum_observations {
1649 return Err(RootReconstructionError::UnsafePackage(
1650 display.to_path_buf(),
1651 ));
1652 }
1653 let entry = entry.map_err(|source| RootReconstructionError::Io {
1654 path: display.to_path_buf(),
1655 source,
1656 })?;
1657 let name = entry.file_name();
1658 if name.as_encoded_bytes().len() > MAX_PATH_COMPONENT_BYTES {
1659 return Err(RootReconstructionError::UnsafePackage(
1660 display.to_path_buf(),
1661 ));
1662 }
1663 let name = name
1664 .into_string()
1665 .map_err(|_| RootReconstructionError::UnsafePackage(display.to_path_buf()))?;
1666 actual.insert(name);
1667 }
1668 if &actual == expected {
1669 Ok(())
1670 } else {
1671 Err(RootReconstructionError::UnsafePackage(
1672 display.to_path_buf(),
1673 ))
1674 }
1675}
1676
1677fn read_package_regular_with_identity(
1678 package: &RetainedReconstructionPackage,
1679 relative: &Path,
1680 maximum: u64,
1681) -> Result<(Vec<u8>, PhysicalIdentity), RootReconstructionError> {
1682 read_regular_from_with_identity(
1683 &package.root,
1684 &package.display_root.join(relative),
1685 relative,
1686 maximum,
1687 )
1688}
1689
1690fn read_regular_from_with_identity(
1691 directory: &Dir,
1692 display: &Path,
1693 relative: &Path,
1694 maximum: u64,
1695) -> Result<(Vec<u8>, PhysicalIdentity), RootReconstructionError> {
1696 let mut file = open_regular_from(directory, display, relative)?;
1697 let identity = cap_file_identity(&file, display)?;
1698 let metadata = file
1699 .metadata()
1700 .map_err(|source| RootReconstructionError::Io {
1701 path: display.to_path_buf(),
1702 source,
1703 })?;
1704 validate_package_regular_metadata(&metadata, display)?;
1705 if metadata.len() > maximum {
1706 return Err(RootReconstructionError::PackageChanged(
1707 display.to_path_buf(),
1708 ));
1709 }
1710 let mut bytes = Vec::new();
1711 Read::by_ref(&mut file)
1712 .take(maximum.saturating_add(1))
1713 .read_to_end(&mut bytes)
1714 .map_err(|source| RootReconstructionError::Io {
1715 path: display.to_path_buf(),
1716 source,
1717 })?;
1718 if bytes.len() as u64 > maximum {
1719 return Err(RootReconstructionError::PackageChanged(
1720 display.to_path_buf(),
1721 ));
1722 }
1723 let reopened = open_regular_from(directory, display, relative)?;
1724 let reopened_identity = cap_file_identity(&reopened, display)?;
1725 let after = reopened
1726 .metadata()
1727 .map_err(|source| RootReconstructionError::Io {
1728 path: display.to_path_buf(),
1729 source,
1730 })?;
1731 validate_package_regular_metadata(&after, display)?;
1732 if after.len() != metadata.len() || reopened_identity != identity {
1733 return Err(RootReconstructionError::PackageChanged(
1734 display.to_path_buf(),
1735 ));
1736 }
1737 Ok((bytes, identity))
1738}
1739
1740fn validate_package_regular_metadata(
1741 metadata: &cap_std::fs::Metadata,
1742 display: &Path,
1743) -> Result<(), RootReconstructionError> {
1744 if metadata.file_type().is_symlink() || !metadata.is_file() {
1745 return Err(RootReconstructionError::UnsafePackage(
1746 display.to_path_buf(),
1747 ));
1748 }
1749 #[cfg(unix)]
1750 {
1751 use cap_fs_ext::OsMetadataExt;
1752 use cap_std::fs::PermissionsExt;
1753 if metadata.permissions().mode() & 0o022 != 0 || metadata.nlink() != 1 {
1754 return Err(RootReconstructionError::UnsafePackage(
1755 display.to_path_buf(),
1756 ));
1757 }
1758 }
1759 Ok(())
1760}
1761
1762fn cap_file_identity(
1763 file: &cap_std::fs::File,
1764 display: &Path,
1765) -> Result<PhysicalIdentity, RootReconstructionError> {
1766 let file = file
1767 .try_clone()
1768 .map_err(|source| RootReconstructionError::Io {
1769 path: display.to_path_buf(),
1770 source,
1771 })?
1772 .into_std();
1773 PhysicalIdentity::from_file(&file).map_err(|source| RootReconstructionError::Io {
1774 path: display.to_path_buf(),
1775 source,
1776 })
1777}
1778
1779fn open_regular_from(
1780 directory: &Dir,
1781 display: &Path,
1782 relative: &Path,
1783) -> Result<cap_std::fs::File, RootReconstructionError> {
1784 let leaf = retain_leaf_parent(directory, relative, display)?;
1785 let mut options = CapOpenOptions::new();
1786 options.read(true).follow(FollowSymlinks::No);
1787 let file = leaf
1788 .parent
1789 .open_with(&leaf.name, &options)
1790 .map_err(|source| RootReconstructionError::Io {
1791 path: display.to_path_buf(),
1792 source,
1793 })?;
1794 let metadata = file
1795 .metadata()
1796 .map_err(|source| RootReconstructionError::Io {
1797 path: display.to_path_buf(),
1798 source,
1799 })?;
1800 if metadata.file_type().is_symlink() || !metadata.is_file() {
1801 return Err(RootReconstructionError::UnsafePackage(
1802 display.to_path_buf(),
1803 ));
1804 }
1805 Ok(file)
1806}
1807
1808#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1809enum ObservedVisibleKind {
1810 Directory,
1811 RegularFile,
1812 Symlink,
1813}
1814
1815fn verify_visible_tree(
1816 root: &Dir,
1817 display_root: &Path,
1818 version: &FolderbaseVersion,
1819) -> Result<(), RootReconstructionError> {
1820 let expected = version
1821 .bindings()
1822 .iter()
1823 .map(|binding| (binding.path().to_owned(), binding.kind()))
1824 .collect::<BTreeMap<_, _>>();
1825 let mut observed = BTreeMap::new();
1826 inventory_visible_directory(
1827 root,
1828 display_root,
1829 Path::new(""),
1830 expected.len(),
1831 &mut observed,
1832 )?;
1833 if observed.len() != expected.len()
1834 || expected.iter().any(|(path, kind)| {
1835 observed.get(path).copied()
1836 != Some(match kind {
1837 PathBindingKind::Directory => ObservedVisibleKind::Directory,
1838 PathBindingKind::RegularFile => ObservedVisibleKind::RegularFile,
1839 PathBindingKind::Symlink => ObservedVisibleKind::Symlink,
1840 })
1841 })
1842 {
1843 return Err(RootReconstructionError::OperationConflict);
1844 }
1845
1846 for binding in version.bindings() {
1847 let relative = Path::new(binding.path());
1848 let display = display_root.join(relative);
1849 let leaf = retain_leaf_parent(root, relative, &display)?;
1850 match binding.kind() {
1851 PathBindingKind::Directory => {
1852 let metadata = leaf.parent.symlink_metadata(&leaf.name).map_err(|source| {
1853 RootReconstructionError::Io {
1854 path: display,
1855 source,
1856 }
1857 })?;
1858 if metadata.file_type().is_symlink() || !metadata.is_dir() {
1859 return Err(RootReconstructionError::OperationConflict);
1860 }
1861 }
1862 PathBindingKind::RegularFile => {
1863 verify_exact_regular_binding(root, display_root, binding)?;
1864 }
1865 PathBindingKind::Symlink => {
1866 let target = leaf.parent.read_link(&leaf.name).map_err(|source| {
1867 RootReconstructionError::Io {
1868 path: display,
1869 source,
1870 }
1871 })?;
1872 if target != Path::new(binding.symlink_target().expect("symlink target")) {
1873 return Err(RootReconstructionError::OperationConflict);
1874 }
1875 }
1876 }
1877 }
1878 Ok(())
1879}
1880
1881fn inventory_visible_directory(
1882 directory: &Dir,
1883 display_root: &Path,
1884 relative_directory: &Path,
1885 maximum: usize,
1886 observed: &mut BTreeMap<String, ObservedVisibleKind>,
1887) -> Result<(), RootReconstructionError> {
1888 let display_directory = display_root.join(relative_directory);
1889 for entry in directory
1890 .entries()
1891 .map_err(|source| RootReconstructionError::Io {
1892 path: display_directory.clone(),
1893 source,
1894 })?
1895 {
1896 if observed.len() >= maximum.saturating_add(1) {
1897 return Err(RootReconstructionError::OperationConflict);
1898 }
1899 let entry = entry.map_err(|source| RootReconstructionError::Io {
1900 path: display_directory.clone(),
1901 source,
1902 })?;
1903 let name = entry.file_name();
1904 if name.as_encoded_bytes().is_empty()
1905 || name.as_encoded_bytes().len() > MAX_PATH_COMPONENT_BYTES
1906 {
1907 return Err(RootReconstructionError::OperationConflict);
1908 }
1909 if relative_directory.as_os_str().is_empty()
1910 && name.to_str().is_some_and(|name| name == ".folderbase")
1911 {
1912 continue;
1913 }
1914 let relative = relative_directory.join(&name);
1915 let path = relative
1916 .to_str()
1917 .filter(|path| path.len() <= MAX_PATH_BYTES)
1918 .ok_or(RootReconstructionError::OperationConflict)?
1919 .to_owned();
1920 let metadata =
1921 directory
1922 .symlink_metadata(&name)
1923 .map_err(|source| RootReconstructionError::Io {
1924 path: display_root.join(&relative),
1925 source,
1926 })?;
1927 let kind = if metadata.file_type().is_symlink() {
1928 ObservedVisibleKind::Symlink
1929 } else if metadata.is_dir() {
1930 ObservedVisibleKind::Directory
1931 } else if metadata.is_file() {
1932 ObservedVisibleKind::RegularFile
1933 } else {
1934 return Err(RootReconstructionError::OperationConflict);
1935 };
1936 if observed.insert(path, kind).is_some() {
1937 return Err(RootReconstructionError::OperationConflict);
1938 }
1939 if kind == ObservedVisibleKind::Directory {
1940 let child = directory.open_dir_nofollow(&name).map_err(|source| {
1941 RootReconstructionError::Io {
1942 path: display_root.join(&relative),
1943 source,
1944 }
1945 })?;
1946 inventory_visible_directory(&child, display_root, &relative, maximum, observed)?;
1947 }
1948 }
1949 Ok(())
1950}
1951
1952fn verify_exact_regular_binding(
1953 root: &Dir,
1954 display_root: &Path,
1955 binding: &crate::folderbase_version::PathBinding,
1956) -> Result<(), RootReconstructionError> {
1957 let relative = Path::new(binding.path());
1958 let display = display_root.join(relative);
1959 let mut file = open_regular_from(root, &display, relative)?;
1960 let expected_bytes = binding.bytes().expect("regular bytes");
1961 let metadata = file
1962 .metadata()
1963 .map_err(|source| RootReconstructionError::Io {
1964 path: display.clone(),
1965 source,
1966 })?;
1967 let identity = cap_file_identity(&file, &display)?;
1968 if metadata.len() != expected_bytes
1969 || regular_is_executable(&metadata) != binding.executable().expect("regular executable")
1970 {
1971 return Err(RootReconstructionError::OperationConflict);
1972 }
1973 let mut digest = Sha256::new();
1974 let mut bytes = 0_u64;
1975 let mut buffer = [0_u8; 64 * 1024];
1976 let mut bounded = Read::by_ref(&mut file).take(expected_bytes.saturating_add(1));
1977 loop {
1978 let read = bounded
1979 .read(&mut buffer)
1980 .map_err(|source| RootReconstructionError::Io {
1981 path: display.clone(),
1982 source,
1983 })?;
1984 if read == 0 {
1985 break;
1986 }
1987 bytes = bytes.saturating_add(read as u64);
1988 digest.update(&buffer[..read]);
1989 }
1990 if bytes != expected_bytes
1991 || format!("{:x}", digest.finalize()) != binding.content_sha256().expect("regular digest")
1992 {
1993 return Err(RootReconstructionError::OperationConflict);
1994 }
1995 let reopened = open_regular_from(root, &display, relative)?;
1996 let reopened_metadata = reopened
1997 .metadata()
1998 .map_err(|source| RootReconstructionError::Io {
1999 path: display.clone(),
2000 source,
2001 })?;
2002 if cap_file_identity(&reopened, &display)? != identity
2003 || reopened_metadata.len() != expected_bytes
2004 || regular_is_executable(&reopened_metadata)
2005 != binding.executable().expect("regular executable")
2006 {
2007 return Err(RootReconstructionError::OperationConflict);
2008 }
2009 Ok(())
2010}
2011
2012fn regular_is_executable(metadata: &cap_std::fs::Metadata) -> bool {
2013 #[cfg(unix)]
2014 {
2015 use cap_std::fs::PermissionsExt;
2016 metadata.permissions().mode() & 0o111 != 0
2017 }
2018 #[cfg(not(unix))]
2019 {
2020 let _ = metadata;
2021 false
2022 }
2023}
2024
2025struct RetainedLeafParent {
2026 parent: Dir,
2027 name: OsString,
2028 parent_display: PathBuf,
2029 display: PathBuf,
2030}
2031
2032fn retain_leaf_parent(
2033 root: &Dir,
2034 relative: &Path,
2035 display: &Path,
2036) -> Result<RetainedLeafParent, RootReconstructionError> {
2037 let name = relative
2038 .file_name()
2039 .ok_or(RootReconstructionError::InvalidDestination)?
2040 .to_os_string();
2041 let mut parent = root
2042 .try_clone()
2043 .map_err(|source| RootReconstructionError::Io {
2044 path: display.to_path_buf(),
2045 source,
2046 })?;
2047 if let Some(ancestors) = relative.parent() {
2048 for component in ancestors.components() {
2049 let Component::Normal(component) = component else {
2050 return Err(RootReconstructionError::InvalidDestination);
2051 };
2052 parent = parent.open_dir_nofollow(component).map_err(|source| {
2053 RootReconstructionError::Io {
2054 path: display.to_path_buf(),
2055 source,
2056 }
2057 })?;
2058 }
2059 }
2060 Ok(RetainedLeafParent {
2061 parent,
2062 name,
2063 parent_display: display.parent().unwrap_or(display).to_path_buf(),
2064 display: display.to_path_buf(),
2065 })
2066}
2067
2068fn materialize_reconstruction(
2069 root: &Dir,
2070 display_root: &Path,
2071 state: &FolderbaseState,
2072 local: &LocalVersionStore,
2073 _package: &RetainedReconstructionPackage,
2074 plan: &RootReconstructionPlan,
2075 validated_package: &ValidatedPackage,
2076) -> Result<ReconstructedHistoryClosure, RootReconstructionError> {
2077 let mut executable_fidelity = BTreeMap::new();
2078 for binding in plan.version().bindings() {
2079 if binding.kind() == PathBindingKind::RegularFile {
2080 insert_executable_fidelity(
2081 &mut executable_fidelity,
2082 binding
2083 .object_version_id()
2084 .ok_or(RootReconstructionError::OperationConflict)?,
2085 binding.executable().unwrap_or(false),
2086 )?;
2087 }
2088 }
2089 for fidelity in plan.tombstone_fidelity() {
2090 insert_executable_fidelity(
2091 &mut executable_fidelity,
2092 fidelity.object_version_id(),
2093 fidelity.executable(),
2094 )?;
2095 }
2096
2097 for binding in plan.version().bindings() {
2098 if binding.kind() == PathBindingKind::Directory {
2099 ensure_directory(root, Path::new(binding.path()), display_root)?;
2100 } else if let Some(parent) = Path::new(binding.path()).parent()
2101 && !parent.as_os_str().is_empty()
2102 {
2103 ensure_directory(root, parent, display_root)?;
2104 }
2105 }
2106
2107 let mut object_paths = BTreeMap::new();
2108 let mut object_versions = Vec::new();
2109 for reference in plan.references() {
2110 let manifest = validated_package
2111 .manifests
2112 .get(reference.chunk_manifest_sha256())
2113 .ok_or(RootReconstructionError::OperationConflict)?;
2114 let relative = Path::new(RECONSTRUCTION_OBJECTS_DIRECTORY)
2115 .join(format!("{}.object", reference.object_version_id()));
2116 write_verified_package_object(root, display_root, &relative, validated_package, manifest)?;
2117 let mut staged_object = open_regular_from(root, &display_root.join(&relative), &relative)?;
2118 let installed = local.install_content_reader_in(
2119 state,
2120 &mut staged_object,
2121 &display_root.join(&relative),
2122 manifest.object_bytes,
2123 )?;
2124 if installed.digest != manifest.object_sha256 || installed.bytes != manifest.object_bytes {
2125 return Err(RootReconstructionError::OperationConflict);
2126 }
2127 let object_id = match reference.object_id() {
2128 Some(value) => ObjectId::parse(value.to_owned())?,
2129 None => derived_root_object_id(plan)?,
2130 };
2131 let mut extensions = BTreeMap::new();
2132 if let Some(executable) = executable_fidelity.get(reference.object_version_id()) {
2133 extensions.insert(
2134 "executable".to_owned(),
2135 serde_json::Value::Bool(*executable),
2136 );
2137 }
2138 object_versions.push(LocalVersionRecord {
2139 id: VersionId::parse(reference.object_version_id().to_owned())?,
2140 object_id,
2141 content: installed,
2142 captured_at: plan.version().created_at().to_owned(),
2143 extensions,
2144 });
2145 object_paths.insert(reference.object_version_id().to_owned(), relative);
2146 }
2147
2148 let root_reference = plan
2149 .references()
2150 .iter()
2151 .find(|reference| {
2152 reference
2153 .roles()
2154 .contains(&ReconstructionReferenceRole::RootManifest)
2155 })
2156 .ok_or(RootReconstructionError::OperationConflict)?;
2157 let root_manifest = validated_package
2158 .manifests
2159 .get(root_reference.chunk_manifest_sha256())
2160 .ok_or(RootReconstructionError::OperationConflict)?;
2161 copy_verified_stage_object(
2162 root,
2163 display_root,
2164 object_paths
2165 .get(root_reference.object_version_id())
2166 .ok_or(RootReconstructionError::OperationConflict)?,
2167 Path::new(".folderbase/manifest.json"),
2168 root_manifest,
2169 false,
2170 )?;
2171
2172 for binding in plan.version().bindings() {
2173 if binding.kind() != PathBindingKind::RegularFile {
2174 continue;
2175 }
2176 let version_id = binding
2177 .object_version_id()
2178 .ok_or(RootReconstructionError::OperationConflict)?;
2179 let reference = plan
2180 .references()
2181 .iter()
2182 .find(|reference| reference.object_version_id() == version_id)
2183 .ok_or(RootReconstructionError::OperationConflict)?;
2184 let manifest = validated_package
2185 .manifests
2186 .get(reference.chunk_manifest_sha256())
2187 .ok_or(RootReconstructionError::OperationConflict)?;
2188 copy_verified_stage_object(
2189 root,
2190 display_root,
2191 object_paths
2192 .get(version_id)
2193 .ok_or(RootReconstructionError::OperationConflict)?,
2194 Path::new(binding.path()),
2195 manifest,
2196 binding.executable().unwrap_or(false),
2197 )?;
2198 }
2199
2200 for symlink in plan.derived_symlinks() {
2201 create_exact_symlink(root, display_root, symlink)?;
2202 let content = local.install_content_bytes_in(state, symlink.target().as_bytes())?;
2203 if content.digest != symlink.content_sha256() || content.bytes != symlink.bytes() {
2204 return Err(RootReconstructionError::OperationConflict);
2205 }
2206 object_versions.push(LocalVersionRecord {
2207 id: VersionId::parse(symlink.object_version_id().to_owned())?,
2208 object_id: ObjectId::parse(symlink.object_id().to_owned())?,
2209 content,
2210 captured_at: plan.version().created_at().to_owned(),
2211 extensions: BTreeMap::new(),
2212 });
2213 }
2214
2215 let mut projections = BTreeMap::new();
2216 for binding in plan.version().bindings() {
2217 if binding.kind() != PathBindingKind::RegularFile
2218 || !can_project_reconstructed_object(binding.path())
2219 {
2220 continue;
2221 }
2222 let object_id = ObjectId::parse(binding.object_id().to_owned())?;
2223 let version_id = VersionId::parse(
2224 binding
2225 .object_version_id()
2226 .ok_or(RootReconstructionError::OperationConflict)?
2227 .to_owned(),
2228 )?;
2229 merge_reconstructed_projection(
2230 &mut projections,
2231 reconstructed_projection(
2232 object_id,
2233 version_id,
2234 binding.path(),
2235 plan.version().created_at(),
2236 "canonical",
2237 ),
2238 );
2239 }
2240 for tombstone in plan.version().tombstones() {
2241 if tombstone.deleted_kind() != DeletedKind::RegularFile
2242 || !can_project_reconstructed_object(tombstone.path())
2243 {
2244 continue;
2245 }
2246 let Some(version_id) = tombstone.last_object_version_id() else {
2247 continue;
2248 };
2249 merge_reconstructed_projection(
2250 &mut projections,
2251 reconstructed_projection(
2252 ObjectId::parse(tombstone.object_id().to_owned())?,
2253 VersionId::parse(version_id.to_owned())?,
2254 tombstone.path(),
2255 plan.version().created_at(),
2256 "deleted",
2257 ),
2258 );
2259 }
2260 object_versions.sort_by(|left, right| left.id.as_str().cmp(right.id.as_str()));
2261 let tombstone_associations = plan
2262 .tombstone_fidelity()
2263 .iter()
2264 .map(|fidelity| {
2265 let record = object_versions
2266 .iter()
2267 .find(|record| {
2268 record.id.as_str() == fidelity.object_version_id()
2269 && record.object_id.as_str() == fidelity.object_id()
2270 })
2271 .ok_or(RootReconstructionError::OperationConflict)?;
2272 Ok(ReconstructedTombstoneAssociation::for_tombstone(
2273 fidelity.path(),
2274 fidelity.object_id(),
2275 fidelity.object_version_id(),
2276 &record.content.digest,
2277 record.content.bytes,
2278 fidelity.executable(),
2279 ))
2280 })
2281 .collect::<Result<Vec<_>, RootReconstructionError>>()?;
2282 Ok(ReconstructedHistoryClosure {
2283 object_versions,
2284 object_projections: projections.into_values().collect(),
2285 tombstone_associations,
2286 })
2287}
2288
2289fn can_project_reconstructed_object(path: &str) -> bool {
2290 !Path::new(path).components().any(|component| {
2291 matches!(component, Component::Normal(name) if is_reserved_workspace_component(name))
2292 })
2293}
2294
2295fn insert_executable_fidelity(
2296 executable_fidelity: &mut BTreeMap<String, bool>,
2297 object_version_id: &str,
2298 executable: bool,
2299) -> Result<(), RootReconstructionError> {
2300 if executable_fidelity
2301 .insert(object_version_id.to_owned(), executable)
2302 .is_some_and(|previous| previous != executable)
2303 {
2304 return Err(RootReconstructionError::TombstoneFidelityMismatch);
2305 }
2306 Ok(())
2307}
2308
2309fn reconstructed_projection(
2310 object_id: ObjectId,
2311 version_id: VersionId,
2312 path: &str,
2313 created_at: &str,
2314 lifecycle_status: &str,
2315) -> LocalObjectRecord {
2316 LocalObjectRecord {
2317 schema: "https://folderbase.ai/protocol/0.1/object.schema.json".to_owned(),
2318 id: object_id,
2319 object_type: "file".to_owned(),
2320 path: path.to_owned(),
2321 lifecycle: ObjectLifecycle {
2322 status: lifecycle_status.to_owned(),
2323 extensions: BTreeMap::new(),
2324 },
2325 provenance: ObjectProvenance {
2326 created_at: created_at.to_owned(),
2327 source: "folderbase-root-reconstruction".to_owned(),
2328 extensions: BTreeMap::new(),
2329 },
2330 current_version: version_id.clone(),
2331 versions: vec![version_id],
2332 extensions: BTreeMap::new(),
2333 }
2334}
2335
2336fn merge_reconstructed_projection(
2337 projections: &mut BTreeMap<String, LocalObjectRecord>,
2338 candidate: LocalObjectRecord,
2339) {
2340 match projections.entry(candidate.id.as_str().to_owned()) {
2341 std::collections::btree_map::Entry::Vacant(entry) => {
2342 entry.insert(candidate);
2343 }
2344 std::collections::btree_map::Entry::Occupied(mut entry) => {
2345 let existing = entry.get_mut();
2346 for version in candidate.versions {
2347 if !existing.versions.contains(&version) {
2348 existing.versions.push(version);
2349 }
2350 }
2351 existing
2352 .versions
2353 .sort_by(|left, right| left.as_str().cmp(right.as_str()));
2354 }
2355 }
2356}
2357
2358fn derived_root_object_id(
2359 plan: &RootReconstructionPlan,
2360) -> Result<ObjectId, RootReconstructionError> {
2361 let digest = Sha256::digest(
2362 format!(
2363 "folderbase-root-reconstruction-root-object-v1\0{}\0{}",
2364 plan.version().folderbase_id(),
2365 plan.version().root_manifest().object_version_id()
2366 )
2367 .as_bytes(),
2368 );
2369 let mut bytes = [0_u8; 16];
2370 bytes.copy_from_slice(&digest[..16]);
2371 bytes[6] = (bytes[6] & 0x0f) | 0x70;
2372 bytes[8] = (bytes[8] & 0x3f) | 0x80;
2373 ObjectId::parse(format!("obj_{}", Uuid::from_bytes(bytes).hyphenated())).map_err(Into::into)
2374}
2375
2376fn write_verified_package_object(
2377 root: &Dir,
2378 display_root: &Path,
2379 relative: &Path,
2380 validated_package: &ValidatedPackage,
2381 manifest: &ChunkManifest,
2382) -> Result<(), RootReconstructionError> {
2383 let leaf = retain_leaf_parent(root, relative, &display_root.join(relative))?;
2384 match leaf.parent.symlink_metadata(&leaf.name) {
2385 Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
2386 let existing = open_regular_from(root, &leaf.display, relative)?;
2387 if manifest.verify_object(existing).is_ok() {
2388 manifest.verify_object(PackageObjectReader::new(validated_package, manifest)?)?;
2389 return Ok(());
2390 }
2391 leaf.parent
2392 .remove_file(&leaf.name)
2393 .map_err(|source| RootReconstructionError::Io {
2394 path: leaf.display.clone(),
2395 source,
2396 })?;
2397 sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2398 }
2399 Ok(_) => return Err(RootReconstructionError::OperationConflict),
2400 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2401 Err(source) => {
2402 return Err(RootReconstructionError::Io {
2403 path: leaf.display.clone(),
2404 source,
2405 });
2406 }
2407 }
2408 let mut options = CapOpenOptions::new();
2409 options
2410 .write(true)
2411 .create_new(true)
2412 .follow(FollowSymlinks::No);
2413 let mut file = leaf
2414 .parent
2415 .open_with(&leaf.name, &options)
2416 .map_err(|source| RootReconstructionError::Io {
2417 path: leaf.display.clone(),
2418 source,
2419 })?;
2420 manifest.verify_object_and_copy(
2421 PackageObjectReader::new(validated_package, manifest)?,
2422 &mut file,
2423 )?;
2424 file.sync_all()
2425 .map_err(|source| RootReconstructionError::Io {
2426 path: leaf.display.clone(),
2427 source,
2428 })?;
2429 sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2430 manifest.verify_object(open_regular_from(
2431 root,
2432 &display_root.join(relative),
2433 relative,
2434 )?)?;
2435 Ok(())
2436}
2437
2438fn copy_verified_stage_object(
2439 root: &Dir,
2440 display_root: &Path,
2441 source: &Path,
2442 destination: &Path,
2443 manifest: &ChunkManifest,
2444 executable: bool,
2445) -> Result<(), RootReconstructionError> {
2446 let leaf = retain_leaf_parent(root, destination, &display_root.join(destination))?;
2447 match leaf.parent.symlink_metadata(&leaf.name) {
2448 Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => {
2449 let existing = open_regular_from(root, &leaf.display, destination)?;
2450 if manifest.verify_object(existing).is_ok()
2451 && regular_is_executable(&metadata) == executable
2452 {
2453 return Ok(());
2454 }
2455 leaf.parent
2456 .remove_file(&leaf.name)
2457 .map_err(|source| RootReconstructionError::Io {
2458 path: leaf.display.clone(),
2459 source,
2460 })?;
2461 sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2462 }
2463 Ok(_) => return Err(RootReconstructionError::OperationConflict),
2464 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2465 Err(source) => {
2466 return Err(RootReconstructionError::Io {
2467 path: leaf.display.clone(),
2468 source,
2469 });
2470 }
2471 }
2472 let mut options = CapOpenOptions::new();
2473 options
2474 .write(true)
2475 .create_new(true)
2476 .follow(FollowSymlinks::No);
2477 let mut destination_file = leaf
2478 .parent
2479 .open_with(&leaf.name, &options)
2480 .map_err(|source| RootReconstructionError::Io {
2481 path: leaf.display.clone(),
2482 source,
2483 })?;
2484 let source_file = open_regular_from(root, &display_root.join(source), source)?;
2485 manifest.verify_object_and_copy(source_file, &mut destination_file)?;
2486 set_regular_executable(
2487 &destination_file,
2488 executable,
2489 &display_root.join(destination),
2490 )?;
2491 destination_file
2492 .sync_all()
2493 .map_err(|source| RootReconstructionError::Io {
2494 path: leaf.display.clone(),
2495 source,
2496 })?;
2497 sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2498 Ok(())
2499}
2500
2501fn set_regular_executable(
2502 file: &cap_std::fs::File,
2503 executable: bool,
2504 display: &Path,
2505) -> Result<(), RootReconstructionError> {
2506 #[cfg(unix)]
2507 {
2508 use cap_std::fs::PermissionsExt;
2509 let mode = if executable { 0o755 } else { 0o644 };
2510 file.set_permissions(cap_std::fs::Permissions::from_mode(mode))
2511 .map_err(|source| RootReconstructionError::Io {
2512 path: display.to_path_buf(),
2513 source,
2514 })?;
2515 }
2516 #[cfg(not(unix))]
2517 let _ = (file, executable, display);
2518 Ok(())
2519}
2520
2521fn create_exact_symlink(
2522 root: &Dir,
2523 display_root: &Path,
2524 symlink: &DerivedSymlink,
2525) -> Result<(), RootReconstructionError> {
2526 let relative = Path::new(symlink.path());
2527 let leaf = retain_leaf_parent(root, relative, &display_root.join(relative))?;
2528 match leaf.parent.read_link(&leaf.name) {
2529 Ok(target) if target == Path::new(symlink.target()) => return Ok(()),
2530 Ok(_) => return Err(RootReconstructionError::OperationConflict),
2531 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {}
2532 Err(source) => {
2533 return Err(RootReconstructionError::Io {
2534 path: display_root.join(relative),
2535 source,
2536 });
2537 }
2538 }
2539 leaf.parent
2540 .symlink_contents(symlink.target(), &leaf.name)
2541 .map_err(|source| RootReconstructionError::Io {
2542 path: leaf.display.clone(),
2543 source,
2544 })?;
2545 sync_retained_directory(&leaf.parent, &leaf.parent_display)?;
2546 Ok(())
2547}
2548
2549fn ensure_directory(
2550 root: &Dir,
2551 relative: &Path,
2552 display_root: &Path,
2553) -> Result<(), RootReconstructionError> {
2554 let mut current = root
2555 .try_clone()
2556 .map_err(|source| RootReconstructionError::Io {
2557 path: display_root.to_path_buf(),
2558 source,
2559 })?;
2560 let mut display = display_root.to_path_buf();
2561 for component in relative.components() {
2562 let Component::Normal(name) = component else {
2563 return Err(RootReconstructionError::InvalidDestination);
2564 };
2565 display.push(name);
2566 match current.symlink_metadata(name) {
2567 Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => {}
2568 Ok(_) => return Err(RootReconstructionError::OperationConflict),
2569 Err(source) if source.kind() == std::io::ErrorKind::NotFound => {
2570 current
2571 .create_dir(name)
2572 .map_err(|source| RootReconstructionError::Io {
2573 path: display.clone(),
2574 source,
2575 })?;
2576 sync_retained_directory(¤t, &display)?;
2577 }
2578 Err(source) => {
2579 return Err(RootReconstructionError::Io {
2580 path: display.clone(),
2581 source,
2582 });
2583 }
2584 }
2585 current =
2586 current
2587 .open_dir_nofollow(name)
2588 .map_err(|source| RootReconstructionError::Io {
2589 path: display.clone(),
2590 source,
2591 })?;
2592 }
2593 Ok(())
2594}
2595
2596struct PackageObjectReader<'a> {
2597 chunks: Dir,
2598 display: PathBuf,
2599 expected_identities: &'a BTreeMap<String, PackageRegularIdentity>,
2600 descriptors: Vec<(String, u64)>,
2601 next: usize,
2602 current: Option<OpenPackageChunk>,
2603}
2604
2605struct OpenPackageChunk {
2606 file: cap_std::fs::File,
2607 name: String,
2608 bytes: u64,
2609 identity: PhysicalIdentity,
2610}
2611
2612impl<'a> PackageObjectReader<'a> {
2613 fn new(
2614 package: &'a ValidatedPackage,
2615 manifest: &ChunkManifest,
2616 ) -> Result<Self, RootReconstructionError> {
2617 Ok(Self {
2618 chunks: package.chunks_directory.try_clone().map_err(|source| {
2619 RootReconstructionError::Io {
2620 path: PathBuf::from("chunks"),
2621 source,
2622 }
2623 })?,
2624 display: PathBuf::from("chunks"),
2625 expected_identities: &package.chunk_identities,
2626 descriptors: manifest
2627 .chunks
2628 .iter()
2629 .map(|chunk| (chunk.sha256.clone(), chunk.bytes))
2630 .collect(),
2631 next: 0,
2632 current: None,
2633 })
2634 }
2635
2636 fn open_next(&mut self) -> std::io::Result<bool> {
2637 let Some((name, bytes)) = self.descriptors.get(self.next) else {
2638 return Ok(false);
2639 };
2640 let mut options = CapOpenOptions::new();
2641 options.read(true).follow(FollowSymlinks::No);
2642 let file = self.chunks.open_with(name, &options)?;
2643 let metadata = file.metadata()?;
2644 validate_package_regular_metadata(&metadata, &self.display.join(name))
2645 .map_err(|error| std::io::Error::other(error.to_string()))?;
2646 let expected = self
2647 .expected_identities
2648 .get(name)
2649 .ok_or_else(|| std::io::Error::other("package chunk identity is unbound"))?;
2650 let identity = cap_file_identity(&file, &self.display.join(name)).map_err(|error| {
2651 std::io::Error::other(format!("package chunk identity failed: {error}"))
2652 })?;
2653 if metadata.len() != *bytes
2654 || metadata.len() != expected.bytes
2655 || identity != expected.physical
2656 {
2657 return Err(std::io::Error::other(format!(
2658 "package chunk changed: {}",
2659 self.display.join(name).display()
2660 )));
2661 }
2662 self.current = Some(OpenPackageChunk {
2663 file,
2664 name: name.clone(),
2665 bytes: *bytes,
2666 identity,
2667 });
2668 self.next += 1;
2669 Ok(true)
2670 }
2671}
2672
2673impl Read for PackageObjectReader<'_> {
2674 fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
2675 loop {
2676 if self.current.is_none() && !self.open_next()? {
2677 return Ok(0);
2678 }
2679 let read = self
2680 .current
2681 .as_mut()
2682 .expect("opened package chunk")
2683 .file
2684 .read(buffer)?;
2685 if read != 0 {
2686 return Ok(read);
2687 }
2688 let completed = self.current.take().expect("completed package chunk");
2689 let mut options = CapOpenOptions::new();
2690 options.read(true).follow(FollowSymlinks::No);
2691 let reopened = self.chunks.open_with(&completed.name, &options)?;
2692 let metadata = reopened.metadata()?;
2693 validate_package_regular_metadata(&metadata, &self.display.join(&completed.name))
2694 .map_err(|error| std::io::Error::other(error.to_string()))?;
2695 let identity = cap_file_identity(&reopened, &self.display.join(&completed.name))
2696 .map_err(|error| std::io::Error::other(error.to_string()))?;
2697 if metadata.len() != completed.bytes || identity != completed.identity {
2698 return Err(std::io::Error::other("package chunk changed during read"));
2699 }
2700 }
2701 }
2702}
2703
2704pub fn plan_retained_package(
2711 package: &RetainedReconstructionPackage,
2712) -> Result<RootReconstructionPlan, RootReconstructionError> {
2713 let (index_encoded, _) = read_package_regular_with_identity(
2714 package,
2715 Path::new("index.json"),
2716 MAX_PACKAGE_INDEX_BYTES,
2717 )?;
2718 let count: ReferenceCountProbe = serde_json::from_slice(&index_encoded)
2719 .map_err(RootReconstructionError::InvalidIndexJson)?;
2720 if count.references.exceeds_maximum {
2721 return Err(RootReconstructionError::TooManyReferences {
2722 maximum: MAX_PACKAGE_REFERENCES,
2723 });
2724 }
2725 let index: PackageIndexWire = serde_json::from_slice(&index_encoded)
2726 .map_err(RootReconstructionError::InvalidIndexJson)?;
2727 let mut manifest_digests = BTreeSet::new();
2728 for reference in &index.references {
2729 if !is_sha256(&reference.chunk_manifest_sha256) {
2730 return Err(RootReconstructionError::InvalidManifestDigest {
2731 object_version_id: reference.object_version_id.clone(),
2732 });
2733 }
2734 manifest_digests.insert(reference.chunk_manifest_sha256.clone());
2735 }
2736 if manifest_digests.len() > MAX_DISTINCT_MANIFESTS {
2737 return Err(RootReconstructionError::TooManyManifests {
2738 maximum: MAX_DISTINCT_MANIFESTS,
2739 });
2740 }
2741 let (version_encoded, _) = read_package_regular_with_identity(
2742 package,
2743 Path::new("version.json"),
2744 MAX_PACKAGE_VERSION_BYTES,
2745 )?;
2746 let manifests_directory = open_package_directory(package, "manifests")?;
2747 let mut manifest_inputs = Vec::with_capacity(manifest_digests.len());
2748 for digest in manifest_digests {
2749 let name = format!("{digest}.json");
2750 let (encoded, _) = read_regular_from_with_identity(
2751 &manifests_directory,
2752 &package.display_root.join("manifests").join(&name),
2753 Path::new(&name),
2754 MAX_PACKAGE_MANIFEST_BYTES,
2755 )?;
2756 manifest_inputs.push(ManifestInput::new(digest, std::io::Cursor::new(encoded)));
2757 }
2758 let plan = decode_and_plan(
2759 std::io::Cursor::new(index_encoded),
2760 std::io::Cursor::new(version_encoded),
2761 manifest_inputs,
2762 )?;
2763 revalidate_package(package, &plan)?;
2764 Ok(plan)
2765}
2766
2767pub fn decode_and_plan<IR, VR, MR, MI>(
2770 index_reader: IR,
2771 version_reader: VR,
2772 manifest_inputs: MI,
2773) -> Result<RootReconstructionPlan, RootReconstructionError>
2774where
2775 IR: Read,
2776 VR: Read,
2777 MR: Read,
2778 MI: IntoIterator<Item = ManifestInput<MR>>,
2779{
2780 let index_encoded = read_bounded_index(index_reader)?;
2781 let count: ReferenceCountProbe = serde_json::from_slice(&index_encoded)
2782 .map_err(RootReconstructionError::InvalidIndexJson)?;
2783 if count.references.exceeds_maximum {
2784 return Err(RootReconstructionError::TooManyReferences {
2785 maximum: MAX_PACKAGE_REFERENCES,
2786 });
2787 }
2788 let index: PackageIndexWire = serde_json::from_slice(&index_encoded)
2789 .map_err(RootReconstructionError::InvalidIndexJson)?;
2790 if index.format != PACKAGE_FORMAT_V1 {
2791 return Err(RootReconstructionError::UnknownFormat);
2792 }
2793 if index.limits != PackageLimitsWire::v1() {
2794 return Err(RootReconstructionError::LimitsMismatch);
2795 }
2796
2797 let version_encoded = read_bounded_version(version_reader)?;
2798 let encoded_version_sha256 = sha256(&version_encoded);
2799 if index.encoded_version_sha256 != encoded_version_sha256 {
2800 return Err(RootReconstructionError::EncodedVersionDigestMismatch);
2801 }
2802 let version = FolderbaseVersion::decode_bounded(version_encoded.as_slice())
2803 .map_err(RootReconstructionError::InvalidVersion)?;
2804 if index.folderbase_id != version.folderbase_id() {
2805 return Err(RootReconstructionError::FolderbaseIdMismatch);
2806 }
2807 if index.folderbase_version_id != version.version_id() {
2808 return Err(RootReconstructionError::VersionIdMismatch);
2809 }
2810 let canonical_version_sha256 = version
2811 .canonical_digest()
2812 .map_err(RootReconstructionError::InvalidVersion)?;
2813 if index.canonical_version_sha256 != canonical_version_sha256 {
2814 return Err(RootReconstructionError::CanonicalVersionDigestMismatch);
2815 }
2816 if version.binding_count() > MAX_VISIBLE_ENTRIES {
2817 return Err(RootReconstructionError::LimitsMismatch);
2818 }
2819
2820 let tombstone_fidelity = validate_tombstone_fidelity(&version, index.tombstone_fidelity)?;
2821 let (expected, derived_symlinks) = expected_closure(&version);
2822 let references = validate_references(index.references, &expected)?;
2823 let expected_manifest_digests = references
2824 .iter()
2825 .map(|reference| reference.chunk_manifest_sha256.clone())
2826 .collect::<BTreeSet<_>>();
2827 if expected_manifest_digests.len() > MAX_DISTINCT_MANIFESTS {
2828 return Err(RootReconstructionError::TooManyManifests {
2829 maximum: MAX_DISTINCT_MANIFESTS,
2830 });
2831 }
2832
2833 let mut manifests = BTreeMap::new();
2834 let mut distinct_chunks = BTreeSet::new();
2835 for (position, input) in manifest_inputs.into_iter().enumerate() {
2836 if position >= MAX_DISTINCT_MANIFESTS {
2837 return Err(RootReconstructionError::TooManyManifests {
2838 maximum: MAX_DISTINCT_MANIFESTS,
2839 });
2840 }
2841 let digest = input.chunk_manifest_sha256;
2842 if !expected_manifest_digests.contains(&digest) {
2843 return Err(RootReconstructionError::UnreferencedManifest {
2844 chunk_manifest_sha256: digest,
2845 });
2846 }
2847 if manifests.contains_key(&digest) {
2848 return Err(RootReconstructionError::DuplicateManifest {
2849 chunk_manifest_sha256: digest,
2850 });
2851 }
2852 let manifest = ChunkManifest::decode_bounded(input.encoded).map_err(|source| {
2853 RootReconstructionError::InvalidManifest {
2854 chunk_manifest_sha256: digest.clone(),
2855 source,
2856 }
2857 })?;
2858 let canonical = manifest.canonical_digest().map_err(|source| {
2859 RootReconstructionError::InvalidManifest {
2860 chunk_manifest_sha256: digest.clone(),
2861 source: ManifestError::InvalidManifest(source),
2862 }
2863 })?;
2864 if canonical != digest {
2865 return Err(RootReconstructionError::ManifestDigestMismatch {
2866 chunk_manifest_sha256: digest,
2867 });
2868 }
2869 for chunk in &manifest.chunks {
2870 distinct_chunks.insert(chunk.sha256.clone());
2871 if distinct_chunks.len() > MAX_DISTINCT_CHUNKS {
2872 return Err(RootReconstructionError::TooManyDistinctChunks {
2873 maximum: MAX_DISTINCT_CHUNKS,
2874 });
2875 }
2876 }
2877 manifests.insert(
2878 canonical.clone(),
2879 PlannedManifest {
2880 chunk_manifest_sha256: canonical,
2881 object_sha256: manifest.object_sha256,
2882 object_bytes: manifest.object_bytes,
2883 chunk_count: manifest.chunks.len(),
2884 },
2885 );
2886 }
2887 for expected_digest in &expected_manifest_digests {
2888 if !manifests.contains_key(expected_digest) {
2889 return Err(RootReconstructionError::MissingManifest {
2890 chunk_manifest_sha256: expected_digest.clone(),
2891 });
2892 }
2893 }
2894
2895 let mut total_object_bytes = 0_u64;
2896 for reference in &references {
2897 let manifest = &manifests[&reference.chunk_manifest_sha256];
2898 let expected_object = &expected[&reference.object_version_id];
2899 if let Some(identity) = &expected_object.authenticated
2900 && (manifest.object_sha256 != identity.sha256
2901 || manifest.object_bytes != identity.bytes)
2902 {
2903 return Err(RootReconstructionError::ManifestObjectMismatch {
2904 object_version_id: reference.object_version_id.clone(),
2905 });
2906 }
2907 total_object_bytes = total_object_bytes
2908 .checked_add(manifest.object_bytes)
2909 .ok_or(RootReconstructionError::TotalObjectBytesTooLarge {
2910 maximum: MAX_TOTAL_OBJECT_BYTES,
2911 })?;
2912 if total_object_bytes > MAX_TOTAL_OBJECT_BYTES {
2913 return Err(RootReconstructionError::TotalObjectBytesTooLarge {
2914 maximum: MAX_TOTAL_OBJECT_BYTES,
2915 });
2916 }
2917 }
2918
2919 Ok(RootReconstructionPlan {
2920 package_index_sha256: sha256(&index_encoded),
2921 encoded_version_sha256,
2922 canonical_version_sha256,
2923 version,
2924 references,
2925 manifests: manifests.into_values().collect(),
2926 derived_symlinks,
2927 tombstone_fidelity,
2928 distinct_chunk_count: distinct_chunks.len(),
2929 total_object_bytes,
2930 })
2931}
2932
2933#[derive(Deserialize)]
2934#[serde(deny_unknown_fields)]
2935struct PackageIndexWire {
2936 format: String,
2937 folderbase_id: String,
2938 folderbase_version_id: String,
2939 canonical_version_sha256: String,
2940 encoded_version_sha256: String,
2941 limits: PackageLimitsWire,
2942 references: Vec<ReferenceWire>,
2943 tombstone_fidelity: Vec<TombstoneFidelityWire>,
2944}
2945
2946#[derive(Debug, Deserialize, PartialEq, Eq)]
2947#[serde(deny_unknown_fields)]
2948struct TombstoneFidelityWire {
2949 path: String,
2950 object_id: String,
2951 object_version_id: String,
2952 executable: bool,
2953}
2954
2955#[derive(Debug, Deserialize, PartialEq, Eq)]
2956#[serde(deny_unknown_fields)]
2957struct PackageLimitsWire {
2958 max_index_bytes: u64,
2959 max_version_bytes: u64,
2960 max_manifest_bytes: u64,
2961 max_references: usize,
2962 max_distinct_manifests: usize,
2963 max_distinct_chunks: usize,
2964 max_chunks_per_manifest: usize,
2965 max_object_bytes: u64,
2966 max_total_object_bytes: u64,
2967 max_visible_entries: usize,
2968}
2969
2970impl PackageLimitsWire {
2971 fn v1() -> Self {
2972 Self {
2973 max_index_bytes: MAX_PACKAGE_INDEX_BYTES,
2974 max_version_bytes: MAX_PACKAGE_VERSION_BYTES,
2975 max_manifest_bytes: MAX_PACKAGE_MANIFEST_BYTES,
2976 max_references: MAX_PACKAGE_REFERENCES,
2977 max_distinct_manifests: MAX_DISTINCT_MANIFESTS,
2978 max_distinct_chunks: MAX_DISTINCT_CHUNKS,
2979 max_chunks_per_manifest: MAX_CHUNKS_PER_MANIFEST,
2980 max_object_bytes: MAX_PACKAGE_OBJECT_BYTES,
2981 max_total_object_bytes: MAX_TOTAL_OBJECT_BYTES,
2982 max_visible_entries: MAX_VISIBLE_ENTRIES,
2983 }
2984 }
2985}
2986
2987#[derive(Deserialize)]
2988#[serde(deny_unknown_fields)]
2989struct ReferenceWire {
2990 object_version_id: String,
2991 #[serde(default, deserialize_with = "deserialize_optional_object_id")]
2992 object_id: OptionalObjectId,
2993 #[serde(deserialize_with = "deserialize_bounded_roles")]
2994 roles: Vec<ReferenceRoleWire>,
2995 chunk_manifest_sha256: String,
2996}
2997
2998#[derive(Clone, Copy, Deserialize, PartialEq, Eq)]
2999#[serde(rename_all = "snake_case")]
3000enum ReferenceRoleWire {
3001 RootManifest,
3002 LiveRegularFile,
3003 RetainedTombstone,
3004}
3005
3006#[derive(Default)]
3007struct OptionalObjectId {
3008 present: bool,
3009 value: Option<String>,
3010}
3011
3012fn deserialize_optional_object_id<'de, D>(deserializer: D) -> Result<OptionalObjectId, D::Error>
3013where
3014 D: serde::Deserializer<'de>,
3015{
3016 Ok(OptionalObjectId {
3017 present: true,
3018 value: Option::<String>::deserialize(deserializer)?,
3019 })
3020}
3021
3022fn deserialize_bounded_roles<'de, D>(deserializer: D) -> Result<Vec<ReferenceRoleWire>, D::Error>
3023where
3024 D: serde::Deserializer<'de>,
3025{
3026 struct RolesVisitor;
3027 impl<'de> Visitor<'de> for RolesVisitor {
3028 type Value = Vec<ReferenceRoleWire>;
3029
3030 fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3031 formatter.write_str("a canonical root-reconstruction role array")
3032 }
3033
3034 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
3035 where
3036 A: SeqAccess<'de>,
3037 {
3038 let mut roles = Vec::with_capacity(2);
3039 while let Some(role) = sequence.next_element()? {
3040 if roles.len() == 2 {
3041 return Err(serde::de::Error::custom("reference has too many roles"));
3042 }
3043 roles.push(role);
3044 }
3045 Ok(roles)
3046 }
3047 }
3048 deserializer.deserialize_seq(RolesVisitor)
3049}
3050
3051#[derive(Deserialize)]
3052struct ReferenceCountProbe {
3053 references: ReferenceCount,
3054}
3055
3056struct ReferenceCount {
3057 exceeds_maximum: bool,
3058}
3059
3060impl<'de> Deserialize<'de> for ReferenceCount {
3061 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
3062 where
3063 D: serde::Deserializer<'de>,
3064 {
3065 struct CountVisitor;
3066 impl<'de> Visitor<'de> for CountVisitor {
3067 type Value = ReferenceCount;
3068
3069 fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3070 formatter.write_str("a package reference array")
3071 }
3072
3073 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
3074 where
3075 A: SeqAccess<'de>,
3076 {
3077 let mut count = 0_usize;
3078 while sequence.next_element::<IgnoredAny>()?.is_some() {
3079 count = count.saturating_add(1);
3080 }
3081 Ok(ReferenceCount {
3082 exceeds_maximum: count > MAX_PACKAGE_REFERENCES,
3083 })
3084 }
3085 }
3086 deserializer.deserialize_seq(CountVisitor)
3087 }
3088}
3089
3090#[derive(Clone)]
3091struct ObjectIdentity {
3092 sha256: String,
3093 bytes: u64,
3094}
3095
3096struct ExpectedObject {
3097 object_id: Option<String>,
3098 roles: BTreeSet<ReconstructionReferenceRole>,
3099 authenticated: Option<ObjectIdentity>,
3100}
3101
3102fn expected_closure(
3103 version: &FolderbaseVersion,
3104) -> (BTreeMap<String, ExpectedObject>, Vec<DerivedSymlink>) {
3105 let root = version.root_manifest();
3106 let mut expected = BTreeMap::from([(
3107 root.object_version_id().to_owned(),
3108 ExpectedObject {
3109 object_id: None,
3110 roles: BTreeSet::from([ReconstructionReferenceRole::RootManifest]),
3111 authenticated: Some(ObjectIdentity {
3112 sha256: root.content_sha256().to_owned(),
3113 bytes: root.bytes(),
3114 }),
3115 },
3116 )]);
3117 let mut symlinks = Vec::new();
3118 for binding in version.bindings() {
3119 let Some(object_version_id) = binding.object_version_id() else {
3120 continue;
3121 };
3122 match binding.kind() {
3123 PathBindingKind::Directory => {}
3124 PathBindingKind::RegularFile => {
3125 expected.insert(
3126 object_version_id.to_owned(),
3127 ExpectedObject {
3128 object_id: Some(binding.object_id().to_owned()),
3129 roles: BTreeSet::from([ReconstructionReferenceRole::LiveRegularFile]),
3130 authenticated: Some(ObjectIdentity {
3131 sha256: binding.content_sha256().expect("regular digest").to_owned(),
3132 bytes: binding.bytes().expect("regular length"),
3133 }),
3134 },
3135 );
3136 }
3137 PathBindingKind::Symlink => {
3138 let target = binding.symlink_target().expect("symlink target");
3139 let identity = ObjectIdentity {
3140 sha256: sha256(target.as_bytes()),
3141 bytes: target.len() as u64,
3142 };
3143 expected.insert(
3144 object_version_id.to_owned(),
3145 ExpectedObject {
3146 object_id: Some(binding.object_id().to_owned()),
3147 roles: BTreeSet::new(),
3148 authenticated: Some(identity.clone()),
3149 },
3150 );
3151 symlinks.push(DerivedSymlink {
3152 path: binding.path().to_owned(),
3153 object_id: binding.object_id().to_owned(),
3154 object_version_id: object_version_id.to_owned(),
3155 target: target.to_owned(),
3156 content_sha256: identity.sha256,
3157 bytes: identity.bytes,
3158 });
3159 }
3160 }
3161 }
3162 for tombstone in version.tombstones() {
3163 let Some(object_version_id) = tombstone.last_object_version_id() else {
3164 continue;
3165 };
3166 expected
3167 .entry(object_version_id.to_owned())
3168 .and_modify(|object| {
3169 object
3170 .roles
3171 .insert(ReconstructionReferenceRole::RetainedTombstone);
3172 })
3173 .or_insert_with(|| ExpectedObject {
3174 object_id: Some(tombstone.object_id().to_owned()),
3175 roles: BTreeSet::from([ReconstructionReferenceRole::RetainedTombstone]),
3176 authenticated: None,
3177 });
3178 }
3179 (expected, symlinks)
3180}
3181
3182fn validate_tombstone_fidelity(
3183 version: &FolderbaseVersion,
3184 supplied: Vec<TombstoneFidelityWire>,
3185) -> Result<Vec<PlannedTombstoneFidelity>, RootReconstructionError> {
3186 let expected = version
3187 .tombstones()
3188 .iter()
3189 .filter(|tombstone| tombstone.deleted_kind() == DeletedKind::RegularFile)
3190 .filter_map(|tombstone| {
3191 tombstone.last_object_version_id().map(|object_version_id| {
3192 (tombstone.path(), tombstone.object_id(), object_version_id)
3193 })
3194 })
3195 .collect::<Vec<_>>();
3196 if supplied.len() != expected.len() {
3197 return Err(RootReconstructionError::TombstoneFidelityMismatch);
3198 }
3199 let mut planned = Vec::with_capacity(supplied.len());
3200 let mut previous_path: Option<&str> = None;
3201 for (record, (path, object_id, object_version_id)) in supplied.iter().zip(expected) {
3202 if previous_path.is_some_and(|previous| previous.as_bytes() >= record.path.as_bytes())
3203 || record.path != path
3204 || record.object_id != object_id
3205 || record.object_version_id != object_version_id
3206 {
3207 return Err(RootReconstructionError::TombstoneFidelityMismatch);
3208 }
3209 previous_path = Some(&record.path);
3210 planned.push(PlannedTombstoneFidelity {
3211 path: record.path.clone(),
3212 object_id: record.object_id.clone(),
3213 object_version_id: record.object_version_id.clone(),
3214 executable: record.executable,
3215 });
3216 }
3217 Ok(planned)
3218}
3219
3220fn validate_references(
3221 references: Vec<ReferenceWire>,
3222 expected: &BTreeMap<String, ExpectedObject>,
3223) -> Result<Vec<PlannedObjectReference>, RootReconstructionError> {
3224 let mut planned = Vec::with_capacity(references.len());
3225 let mut previous: Option<String> = None;
3226 let mut observed = BTreeSet::new();
3227 for reference in references {
3228 if let Some(previous) = &previous {
3229 match previous
3230 .as_bytes()
3231 .cmp(reference.object_version_id.as_bytes())
3232 {
3233 std::cmp::Ordering::Equal => {
3234 return Err(RootReconstructionError::DuplicateReference {
3235 object_version_id: reference.object_version_id,
3236 });
3237 }
3238 std::cmp::Ordering::Greater => {
3239 return Err(RootReconstructionError::ReferencesOutOfOrder);
3240 }
3241 std::cmp::Ordering::Less => {}
3242 }
3243 }
3244 previous = Some(reference.object_version_id.clone());
3245 let roles = canonical_roles(&reference)?;
3246 let Some(expected_object) = expected.get(&reference.object_version_id) else {
3247 return Err(RootReconstructionError::UnexpectedReference {
3248 object_version_id: reference.object_version_id,
3249 });
3250 };
3251 let expected_roles = expected_object.roles.iter().copied().collect::<Vec<_>>();
3252 if roles != expected_roles || reference.object_id.value != expected_object.object_id {
3253 return Err(RootReconstructionError::ReferenceMismatch {
3254 object_version_id: reference.object_version_id,
3255 });
3256 }
3257 if !is_sha256(&reference.chunk_manifest_sha256) {
3258 return Err(RootReconstructionError::InvalidManifestDigest {
3259 object_version_id: reference.object_version_id,
3260 });
3261 }
3262 observed.insert(reference.object_version_id.clone());
3263 planned.push(PlannedObjectReference {
3264 object_version_id: reference.object_version_id,
3265 object_id: reference.object_id.value,
3266 roles,
3267 chunk_manifest_sha256: reference.chunk_manifest_sha256,
3268 });
3269 }
3270 for (object_version_id, expected_object) in expected {
3271 if !expected_object.roles.is_empty() && !observed.contains(object_version_id) {
3272 return Err(RootReconstructionError::MissingReference {
3273 object_version_id: object_version_id.clone(),
3274 });
3275 }
3276 }
3277 Ok(planned)
3278}
3279
3280fn canonical_roles(
3281 reference: &ReferenceWire,
3282) -> Result<Vec<ReconstructionReferenceRole>, RootReconstructionError> {
3283 let roles = match reference.roles.as_slice() {
3284 [ReferenceRoleWire::RootManifest] if !reference.object_id.present => {
3285 vec![ReconstructionReferenceRole::RootManifest]
3286 }
3287 [ReferenceRoleWire::LiveRegularFile] if reference.object_id.value.is_some() => {
3288 vec![ReconstructionReferenceRole::LiveRegularFile]
3289 }
3290 [ReferenceRoleWire::RetainedTombstone] if reference.object_id.value.is_some() => {
3291 vec![ReconstructionReferenceRole::RetainedTombstone]
3292 }
3293 [
3294 ReferenceRoleWire::LiveRegularFile,
3295 ReferenceRoleWire::RetainedTombstone,
3296 ] if reference.object_id.value.is_some() => {
3297 vec![
3298 ReconstructionReferenceRole::LiveRegularFile,
3299 ReconstructionReferenceRole::RetainedTombstone,
3300 ]
3301 }
3302 _ => {
3303 return Err(RootReconstructionError::InvalidReferenceRoles {
3304 object_version_id: reference.object_version_id.clone(),
3305 });
3306 }
3307 };
3308 Ok(roles)
3309}
3310
3311fn read_bounded_index(mut reader: impl Read) -> Result<Vec<u8>, RootReconstructionError> {
3312 let mut encoded = Vec::new();
3313 reader
3314 .by_ref()
3315 .take(MAX_PACKAGE_INDEX_BYTES + 1)
3316 .read_to_end(&mut encoded)
3317 .map_err(RootReconstructionError::IndexReader)?;
3318 if encoded.len() as u64 > MAX_PACKAGE_INDEX_BYTES {
3319 return Err(RootReconstructionError::IndexTooLarge {
3320 maximum_bytes: MAX_PACKAGE_INDEX_BYTES,
3321 });
3322 }
3323 Ok(encoded)
3324}
3325
3326fn read_bounded_version(mut reader: impl Read) -> Result<Vec<u8>, RootReconstructionError> {
3327 let mut encoded = Vec::new();
3328 reader
3329 .by_ref()
3330 .take(MAX_PACKAGE_VERSION_BYTES + 1)
3331 .read_to_end(&mut encoded)
3332 .map_err(RootReconstructionError::VersionReader)?;
3333 if encoded.len() as u64 > MAX_PACKAGE_VERSION_BYTES {
3334 return Err(RootReconstructionError::VersionTooLarge {
3335 maximum_bytes: MAX_PACKAGE_VERSION_BYTES,
3336 });
3337 }
3338 Ok(encoded)
3339}
3340
3341fn sha256(bytes: &[u8]) -> String {
3342 format!("{:x}", Sha256::digest(bytes))
3343}
3344
3345fn root_reconstruction_request_sha256(
3346 operation_id: &str,
3347 package_index_sha256: &str,
3348) -> Result<String, RootReconstructionError> {
3349 if !is_sha256(package_index_sha256) {
3350 return Err(RootReconstructionError::InvalidOperation);
3351 }
3352 let operation = operation_id.as_bytes();
3353 let operation_bytes =
3354 u32::try_from(operation.len()).map_err(|_| RootReconstructionError::InvalidOperation)?;
3355 let mut digest = Sha256::new();
3356 digest.update(b"folderbase-root-reconstruction-request-v1\0");
3357 digest.update(operation_bytes.to_be_bytes());
3358 digest.update(operation);
3359 let mut pin = [0_u8; 32];
3360 for (index, pair) in package_index_sha256.as_bytes().chunks_exact(2).enumerate() {
3361 let encoded = std::str::from_utf8(pair)
3362 .ok()
3363 .and_then(|value| u8::from_str_radix(value, 16).ok())
3364 .ok_or(RootReconstructionError::InvalidOperation)?;
3365 pin[index] = encoded;
3366 }
3367 digest.update(pin);
3368 Ok(format!("{:x}", digest.finalize()))
3369}
3370
3371fn is_sha256(value: &str) -> bool {
3372 value.len() == 64
3373 && value
3374 .bytes()
3375 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
3376}
3377
3378#[cfg(test)]
3379mod tests {
3380 use std::{
3381 collections::BTreeMap,
3382 io::{Cursor, Read as _},
3383 panic::{AssertUnwindSafe, catch_unwind},
3384 path::Path,
3385 };
3386
3387 use serde_json::{Value, json};
3388 use sha2::{Digest, Sha256};
3389
3390 use super::{
3391 COMPLETED_RECONSTRUCTION_PATH, MAX_PACKAGE_INDEX_BYTES, MAX_PACKAGE_MANIFEST_BYTES,
3392 MAX_PACKAGE_REFERENCES, RetainedReconstructionDestination, RetainedReconstructionPackage,
3393 RootReconstructionError, RootReconstructionOperation, RootReconstructionPhase,
3394 can_project_reconstructed_object, execute_root_reconstruction,
3395 execute_root_reconstruction_with_phase_callback, plan_retained_package,
3396 root_reconstruction_request_sha256, stage_owner_name, stage_proof_name, staged_root_name,
3397 };
3398 use super::{ManifestInput, ReconstructionReferenceRole, decode_and_plan};
3399 use crate::{
3400 folderbase_version::FolderbaseVersion,
3401 transfer_manifest::{
3402 CHUNKING_ALGORITHM_V1, ChunkDescriptor, ChunkManifest, MANIFEST_FORMAT_V1,
3403 ManifestError, STANDARD_PROFILE_V1,
3404 },
3405 };
3406
3407 const FOLDERBASE_ID: &str = "folderbase_01900000-0000-7000-8000-000000000001";
3408 const FOLDERBASE_VERSION_ID: &str = "fbversion_01900000-0000-7000-8000-000000000002";
3409 const ROOT_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000003";
3410 const LIVE_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000004";
3411 const SYMLINK_VERSION_ID: &str = "version_01900000-0000-7000-8000-000000000005";
3412 const LIVE_OBJECT_ID: &str = "obj_01900000-0000-7000-8000-000000000006";
3413
3414 struct Fixture {
3415 index: Vec<u8>,
3416 version: Vec<u8>,
3417 manifests: Vec<ManifestInput<Cursor<Vec<u8>>>>,
3418 }
3419
3420 #[test]
3421 fn complete_package_plans_exact_reference_closure_and_derived_symlink() {
3422 let fixture = complete_fixture();
3423
3424 let plan = decode_and_plan(
3425 fixture.index.as_slice(),
3426 fixture.version.as_slice(),
3427 fixture.manifests,
3428 )
3429 .expect("complete package should plan");
3430
3431 assert_eq!(plan.version().folderbase_id(), FOLDERBASE_ID);
3432 assert_eq!(plan.version().version_id(), FOLDERBASE_VERSION_ID);
3433 assert_eq!(plan.references().len(), 2);
3434 assert_eq!(
3435 plan.references()[1].roles(),
3436 &[
3437 ReconstructionReferenceRole::LiveRegularFile,
3438 ReconstructionReferenceRole::RetainedTombstone,
3439 ]
3440 );
3441 assert_eq!(plan.manifests().len(), 2);
3442 assert_eq!(plan.derived_symlinks().len(), 1);
3443 assert_eq!(plan.derived_symlinks()[0].path(), "shortcut");
3444 assert_eq!(plan.derived_symlinks()[0].target(), "current.txt");
3445 assert_eq!(
3446 plan.derived_symlinks()[0].content_sha256(),
3447 sha256(b"current.txt")
3448 );
3449 assert_eq!(plan.derived_symlinks()[0].bytes(), 11);
3450 assert_eq!(plan.externally_materialized_object_count(), 2);
3451 assert_eq!(plan.visible_entry_count(), 2);
3452 assert_eq!(
3453 plan.total_object_bytes(),
3454 root_manifest_bytes().len() as u64 + 7
3455 );
3456 }
3457
3458 #[test]
3459 fn retained_package_planning_uses_the_exact_nofollow_package_shape() {
3460 let temporary = tempfile::tempdir().expect("temporary root");
3461 let source = temporary.path().join("package");
3462 std::fs::create_dir(&source).expect("package root");
3463 let fixture = complete_fixture();
3464 write_package(&source, &fixture);
3465 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3466
3467 let plan = plan_retained_package(&package).expect("retained package plan");
3468
3469 assert_eq!(plan.version().version_id(), FOLDERBASE_VERSION_ID);
3470 assert_eq!(plan.package_index_sha256(), sha256(&fixture.index));
3471 assert_eq!(plan.externally_materialized_object_count(), 2);
3472 assert!(can_project_reconstructed_object("current.txt"));
3473 assert!(!can_project_reconstructed_object("repo/.git/HEAD"));
3474 assert!(!can_project_reconstructed_object(
3475 ".folderbase/private.json"
3476 ));
3477
3478 #[cfg(unix)]
3479 {
3480 std::os::unix::fs::symlink("version.json", source.join("version-alias.json"))
3481 .expect("unsafe package alias");
3482 assert!(matches!(
3483 plan_retained_package(&package),
3484 Err(RootReconstructionError::UnsafePackage(path)) if path == source
3485 ));
3486 }
3487 }
3488
3489 #[test]
3490 fn destination_inside_source_is_rejected_before_the_package_changes() {
3491 let temporary = tempfile::tempdir().expect("temporary root");
3492 let source = temporary.path().join("package");
3493 std::fs::create_dir(&source).expect("package root");
3494 let fixture = complete_fixture();
3495 write_package(&source, &fixture);
3496 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3497 let plan = plan_retained_package(&package).expect("retained package plan");
3498 let destination = RetainedReconstructionDestination::open(&source, "restored")
3499 .expect("retained destination inside source");
3500 let before = package_tree_snapshot(&source);
3501
3502 let result = execute_root_reconstruction(
3503 RootReconstructionOperation::new(
3504 &plan,
3505 "reconstruction_01900000-0000-7000-8000-000000000201",
3506 plan.package_index_sha256(),
3507 )
3508 .expect("valid operation"),
3509 &package,
3510 &destination,
3511 );
3512
3513 assert!(matches!(
3514 result,
3515 Err(RootReconstructionError::InvalidDestination)
3516 ));
3517 assert_eq!(package_tree_snapshot(&source), before);
3518 }
3519
3520 #[test]
3521 fn source_inside_destination_parent_is_rejected_before_the_package_changes() {
3522 let temporary = tempfile::tempdir().expect("temporary root");
3523 let destination_parent = temporary.path().join("destination-parent");
3524 let source = destination_parent.join("package");
3525 std::fs::create_dir(&destination_parent).expect("destination parent");
3526 std::fs::create_dir(&source).expect("package root");
3527 let fixture = complete_fixture();
3528 write_package(&source, &fixture);
3529 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3530 let plan = plan_retained_package(&package).expect("retained package plan");
3531 let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
3532 .expect("retained destination around source");
3533 let before = package_tree_snapshot(&source);
3534
3535 let result = execute_root_reconstruction(
3536 RootReconstructionOperation::new(
3537 &plan,
3538 "reconstruction_01900000-0000-7000-8000-000000000202",
3539 plan.package_index_sha256(),
3540 )
3541 .expect("valid operation"),
3542 &package,
3543 &destination,
3544 );
3545
3546 assert!(matches!(
3547 result,
3548 Err(RootReconstructionError::InvalidDestination)
3549 ));
3550 assert_eq!(package_tree_snapshot(&source), before);
3551 assert_eq!(
3552 std::fs::read_dir(&destination_parent)
3553 .expect("destination parent remains readable")
3554 .map(|entry| entry.expect("destination parent entry").file_name())
3555 .collect::<Vec<_>>(),
3556 vec![std::ffi::OsString::from("package")]
3557 );
3558 }
3559
3560 #[test]
3561 fn destination_parent_beneath_source_is_rejected_before_the_package_changes() {
3562 let temporary = tempfile::tempdir().expect("temporary root");
3563 let source = temporary.path().join("package");
3564 std::fs::create_dir(&source).expect("package root");
3565 let fixture = complete_fixture();
3566 write_package(&source, &fixture);
3567 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3568 let plan = plan_retained_package(&package).expect("retained package plan");
3569 let destination =
3570 RetainedReconstructionDestination::open(source.join("chunks"), "restored")
3571 .expect("retained destination beneath source");
3572 let before = package_tree_snapshot(&source);
3573
3574 let result = execute_root_reconstruction(
3575 RootReconstructionOperation::new(
3576 &plan,
3577 "reconstruction_01900000-0000-7000-8000-000000000203",
3578 plan.package_index_sha256(),
3579 )
3580 .expect("valid operation"),
3581 &package,
3582 &destination,
3583 );
3584
3585 assert!(matches!(
3586 result,
3587 Err(RootReconstructionError::InvalidDestination)
3588 ));
3589 assert_eq!(package_tree_snapshot(&source), before);
3590 }
3591
3592 #[cfg(unix)]
3593 #[test]
3594 fn aliased_source_ancestor_cannot_hide_containment_from_destination_parent() {
3595 let temporary = tempfile::tempdir().expect("temporary root");
3596 let destination_parent = temporary.path().join("physical-parent");
3597 let source = destination_parent.join("package");
3598 let aliased_parent = temporary.path().join("aliased-parent");
3599 std::fs::create_dir(&destination_parent).expect("physical destination parent");
3600 std::fs::create_dir(&source).expect("package root");
3601 std::os::unix::fs::symlink(&destination_parent, &aliased_parent)
3602 .expect("destination-parent alias");
3603 let fixture = complete_fixture();
3604 write_package(&source, &fixture);
3605 let package = RetainedReconstructionPackage::open(aliased_parent.join("package"))
3606 .expect("retained package through aliased ancestor");
3607 let plan = plan_retained_package(&package).expect("retained package plan");
3608 let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
3609 .expect("retained physical destination parent");
3610 let before = package_tree_snapshot(&source);
3611
3612 let result = execute_root_reconstruction(
3613 RootReconstructionOperation::new(
3614 &plan,
3615 "reconstruction_01900000-0000-7000-8000-000000000204",
3616 plan.package_index_sha256(),
3617 )
3618 .expect("valid operation"),
3619 &package,
3620 &destination,
3621 );
3622
3623 assert!(matches!(
3624 result,
3625 Err(RootReconstructionError::InvalidDestination)
3626 ));
3627 assert_eq!(package_tree_snapshot(&source), before);
3628 assert_eq!(
3629 std::fs::read_dir(&destination_parent)
3630 .expect("destination parent remains readable")
3631 .map(|entry| entry.expect("destination parent entry").file_name())
3632 .collect::<Vec<_>>(),
3633 vec![std::ffi::OsString::from("package")]
3634 );
3635 }
3636
3637 #[cfg(unix)]
3638 #[test]
3639 fn aliased_destination_ancestor_cannot_hide_containment_inside_source() {
3640 let temporary = tempfile::tempdir().expect("temporary root");
3641 let source = temporary.path().join("package");
3642 let aliased_source = temporary.path().join("aliased-package");
3643 std::fs::create_dir(&source).expect("package root");
3644 let fixture = complete_fixture();
3645 write_package(&source, &fixture);
3646 std::os::unix::fs::symlink(&source, &aliased_source).expect("package alias");
3647 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3648 let plan = plan_retained_package(&package).expect("retained package plan");
3649 let destination =
3650 RetainedReconstructionDestination::open(aliased_source.join("chunks"), "restored")
3651 .expect("retained destination through aliased ancestor");
3652 let before = package_tree_snapshot(&source);
3653
3654 let result = execute_root_reconstruction(
3655 RootReconstructionOperation::new(
3656 &plan,
3657 "reconstruction_01900000-0000-7000-8000-000000000205",
3658 plan.package_index_sha256(),
3659 )
3660 .expect("valid operation"),
3661 &package,
3662 &destination,
3663 );
3664
3665 assert!(matches!(
3666 result,
3667 Err(RootReconstructionError::InvalidDestination)
3668 ));
3669 assert_eq!(package_tree_snapshot(&source), before);
3670 }
3671
3672 #[test]
3673 fn execution_publishes_one_complete_verified_root() {
3674 let temporary = tempfile::tempdir().expect("temporary root");
3675 let source = temporary.path().join("package");
3676 let destination_parent = temporary.path().join("destinations");
3677 std::fs::create_dir(&source).expect("package root");
3678 std::fs::create_dir(&destination_parent).expect("destination parent");
3679 let fixture = complete_fixture();
3680 write_package(&source, &fixture);
3681 let plan = plan_from_fixture(&fixture);
3682 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3683 let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
3684 .expect("retained absent destination");
3685 let operation = RootReconstructionOperation::new(
3686 &plan,
3687 "reconstruction_01900000-0000-7000-8000-000000000100",
3688 plan.package_index_sha256(),
3689 )
3690 .expect("valid operation");
3691
3692 let result = execute_root_reconstruction(operation, &package, &destination)
3693 .expect("root reconstruction");
3694
3695 let restored = destination_parent.join("restored");
3696 assert!(!result.replayed());
3697 assert_eq!(result.attestation().root, restored);
3698 assert_eq!(
3699 std::fs::read(restored.join("current.txt")).unwrap(),
3700 b"payload"
3701 );
3702 assert_eq!(
3703 std::fs::read_link(restored.join("shortcut")).unwrap(),
3704 std::path::Path::new("current.txt")
3705 );
3706 assert_eq!(
3707 crate::attest_folderbase_root(&restored)
3708 .expect("published root attests")
3709 .folderbase_id,
3710 FOLDERBASE_ID
3711 );
3712 let store =
3713 crate::FolderbaseVersionStore::open(&restored).expect("open reconstructed root");
3714 assert_eq!(
3715 store
3716 .read_version(FOLDERBASE_VERSION_ID)
3717 .expect("installed Version")
3718 .canonical_digest()
3719 .expect("Version digest"),
3720 plan.canonical_version_sha256()
3721 );
3722 let capture = store.plan_capture().expect("follow-up capture plan");
3723 store
3724 .seal_capture(capture)
3725 .expect("follow-up capture remains operational");
3726
3727 let owner = stage_owner_name("reconstruction_01900000-0000-7000-8000-000000000100");
3728 let proof = stage_proof_name("reconstruction_01900000-0000-7000-8000-000000000100");
3729 assert!(!destination_parent.join(owner).exists());
3730 assert!(!destination_parent.join(proof).exists());
3731 std::fs::remove_dir_all(&source).expect("transport may disappear after completion");
3732 let replay = execute_root_reconstruction(
3733 RootReconstructionOperation::new(
3734 &plan,
3735 "reconstruction_01900000-0000-7000-8000-000000000100",
3736 plan.package_index_sha256(),
3737 )
3738 .unwrap(),
3739 &package,
3740 &destination,
3741 )
3742 .expect("exact replay does not require transport");
3743 assert!(replay.replayed());
3744 assert_eq!(replay.attestation().root, restored);
3745
3746 let occupied = execute_root_reconstruction(
3747 RootReconstructionOperation::new(
3748 &plan,
3749 "reconstruction_01900000-0000-7000-8000-000000000101",
3750 plan.package_index_sha256(),
3751 )
3752 .unwrap(),
3753 &package,
3754 &destination,
3755 );
3756 assert!(matches!(
3757 occupied,
3758 Err(RootReconstructionError::DestinationOccupied(path)) if path == restored
3759 ));
3760 assert_eq!(
3761 std::fs::read(restored.join("current.txt")).unwrap(),
3762 b"payload"
3763 );
3764 }
3765
3766 #[test]
3767 fn reconstructed_tombstone_only_history_restores_exact_fidelity() {
3768 let temporary = tempfile::tempdir().expect("temporary root");
3769 let source = temporary.path().join("package");
3770 let destination_parent = temporary.path().join("destinations");
3771 std::fs::create_dir(&source).expect("package root");
3772 std::fs::create_dir(&destination_parent).expect("destination parent");
3773 let fixture = tombstone_only_fixture();
3774 write_package(&source, &fixture);
3775 let plan = plan_from_fixture(&fixture);
3776 let package = RetainedReconstructionPackage::open(&source).expect("retained package");
3777 let destination = RetainedReconstructionDestination::open(&destination_parent, "restored")
3778 .expect("retained absent destination");
3779
3780 execute_root_reconstruction(
3781 RootReconstructionOperation::new(
3782 &plan,
3783 "reconstruction_01900000-0000-7000-8000-000000000102",
3784 plan.package_index_sha256(),
3785 )
3786 .expect("valid operation"),
3787 &package,
3788 &destination,
3789 )
3790 .expect("root reconstruction");
3791
3792 let restored = destination_parent.join("restored");
3793 let local = crate::LocalVersionStore::open(&restored).expect("reopen local versions");
3794 local
3795 .restore_version(
3796 &crate::VersionId::parse(LIVE_VERSION_ID.to_owned())
3797 .expect("valid Object Version ID"),
3798 "Restored/previous.txt",
3799 )
3800 .expect("ordinary Object Version restore preserves retained fidelity");
3801 assert_eq!(
3802 std::fs::read(restored.join("Restored/previous.txt")).unwrap(),
3803 b"payload"
3804 );
3805 #[cfg(unix)]
3806 {
3807 use std::os::unix::fs::PermissionsExt;
3808 assert_ne!(
3809 std::fs::metadata(restored.join("Restored/previous.txt"))
3810 .unwrap()
3811 .permissions()
3812 .mode()
3813 & 0o111,
3814 0
3815 );
3816 }
3817
3818 let store = crate::FolderbaseVersionStore::open(&restored).expect("reopen root");
3819 store
3820 .restore_tombstone("previous.txt")
3821 .expect("retained Tombstone remains restorable without ancestor Versions");
3822 assert_eq!(
3823 std::fs::read(restored.join("previous.txt")).unwrap(),
3824 b"payload"
3825 );
3826 #[cfg(unix)]
3827 {
3828 use std::os::unix::fs::PermissionsExt;
3829 assert_ne!(
3830 std::fs::metadata(restored.join("previous.txt"))
3831 .unwrap()
3832 .permissions()
3833 .mode()
3834 & 0o111,
3835 0,
3836 "Tombstone restore must retain executable fidelity"
3837 );
3838 }
3839 }
3840
3841 #[test]
3842 fn operation_derives_the_normative_request_digest_and_rejects_invalid_identity_or_pin() {
3843 assert_eq!(
3844 root_reconstruction_request_sha256(
3845 "reconstruction_019f0000-0000-7000-8000-000000000001",
3846 "c646776fc7a7c2f8b3d6320fcb647f19fa2df32f7061ed70944efc5bf13aac28",
3847 )
3848 .unwrap(),
3849 "3c306292ba513818e68b83a09f65a127dca5ae44a892ce7db4485e4f29b45115"
3850 );
3851 let fixture = complete_fixture();
3852 let plan = plan_from_fixture(&fixture);
3853 let operation = RootReconstructionOperation::new(
3854 &plan,
3855 "reconstruction_01900000-0000-7000-8000-000000000100",
3856 plan.package_index_sha256(),
3857 )
3858 .expect("canonical UUID and exact pin");
3859 assert!(super::is_sha256(operation.request_sha256()));
3860 assert!(matches!(
3861 RootReconstructionOperation::new(
3862 &plan,
3863 "reconstruction_01900000-0000-7000-8000-000000000100",
3864 "ab".repeat(32),
3865 ),
3866 Err(RootReconstructionError::PackageIndexPinMismatch)
3867 ));
3868 assert!(matches!(
3869 RootReconstructionOperation::new(
3870 &plan,
3871 "reconstruction_01900000-0000-9000-8000-000000000100",
3872 plan.package_index_sha256(),
3873 ),
3874 Err(RootReconstructionError::InvalidOperation)
3875 ));
3876 }
3877
3878 #[test]
3879 fn occupied_destination_and_foreign_private_state_are_preserved() {
3880 let temporary = tempfile::tempdir().unwrap();
3881 let source = temporary.path().join("package");
3882 let parent = temporary.path().join("destinations");
3883 std::fs::create_dir(&source).unwrap();
3884 std::fs::create_dir(&parent).unwrap();
3885 let fixture = complete_fixture();
3886 write_package(&source, &fixture);
3887 let plan = plan_from_fixture(&fixture);
3888 let package = RetainedReconstructionPackage::open(&source).unwrap();
3889
3890 std::fs::create_dir(parent.join("occupied")).unwrap();
3891 std::fs::write(parent.join("occupied/keep.txt"), b"keep").unwrap();
3892 let occupied_destination =
3893 RetainedReconstructionDestination::open(&parent, "occupied").unwrap();
3894 let result = execute_root_reconstruction(
3895 RootReconstructionOperation::new(
3896 &plan,
3897 "reconstruction_01900000-0000-7000-8000-000000000110",
3898 plan.package_index_sha256(),
3899 )
3900 .unwrap(),
3901 &package,
3902 &occupied_destination,
3903 );
3904 assert!(matches!(
3905 result,
3906 Err(RootReconstructionError::DestinationOccupied(_))
3907 ));
3908 assert_eq!(
3909 std::fs::read(parent.join("occupied/keep.txt")).unwrap(),
3910 b"keep"
3911 );
3912
3913 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000111";
3914 let foreign_stage = parent.join(staged_root_name(operation_id));
3915 std::fs::create_dir(&foreign_stage).unwrap();
3916 std::fs::write(foreign_stage.join("keep.txt"), b"foreign").unwrap();
3917 let destination =
3918 RetainedReconstructionDestination::open(&parent, "foreign-target").unwrap();
3919 let result = execute_root_reconstruction(
3920 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
3921 .unwrap(),
3922 &package,
3923 &destination,
3924 );
3925 assert!(matches!(
3926 result,
3927 Err(RootReconstructionError::OperationConflict)
3928 ));
3929 assert_eq!(
3930 std::fs::read(foreign_stage.join("keep.txt")).unwrap(),
3931 b"foreign"
3932 );
3933
3934 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000112";
3935 let foreign_owner = parent.join(stage_owner_name(operation_id));
3936 std::fs::write(&foreign_owner, b"foreign-owner").unwrap();
3937 let destination =
3938 RetainedReconstructionDestination::open(&parent, "foreign-owner-target").unwrap();
3939 let result = execute_root_reconstruction(
3940 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
3941 .unwrap(),
3942 &package,
3943 &destination,
3944 );
3945 assert!(matches!(
3946 result,
3947 Err(RootReconstructionError::OperationConflict)
3948 ));
3949 assert_eq!(std::fs::read(foreign_owner).unwrap(), b"foreign-owner");
3950 }
3951
3952 #[test]
3953 fn unsupported_preflight_creates_no_private_stage() {
3954 let temporary = tempfile::tempdir().unwrap();
3955 let parent = temporary.path().join("destinations");
3956 std::fs::create_dir(&parent).unwrap();
3957 let result = RetainedReconstructionDestination::open_with_preflight(
3958 &parent,
3959 std::ffi::OsStr::new("restored"),
3960 true,
3961 );
3962 assert!(matches!(
3963 result,
3964 Err(RootReconstructionError::UnsupportedReconstructionFilesystem { .. })
3965 ));
3966 assert_eq!(std::fs::read_dir(&parent).unwrap().count(), 0);
3967 }
3968
3969 #[test]
3970 fn exact_owned_stage_rejects_extra_entries_and_repairs_executable_fidelity() {
3971 let temporary = tempfile::tempdir().unwrap();
3972 let source = temporary.path().join("package");
3973 let parent = temporary.path().join("destinations");
3974 std::fs::create_dir(&source).unwrap();
3975 std::fs::create_dir(&parent).unwrap();
3976 let fixture = complete_fixture();
3977 write_package(&source, &fixture);
3978 let plan = plan_from_fixture(&fixture);
3979 let package = RetainedReconstructionPackage::open(&source).unwrap();
3980 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000120";
3981 let destination = RetainedReconstructionDestination::open(&parent, "extra-target").unwrap();
3982 let crash = catch_unwind(AssertUnwindSafe(|| {
3983 let _ = execute_root_reconstruction_with_phase_callback(
3984 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
3985 .unwrap(),
3986 &package,
3987 &destination,
3988 |phase| {
3989 if phase == RootReconstructionPhase::PreparedJournal {
3990 let stage = parent.join(staged_root_name(operation_id));
3991 std::fs::write(stage.join("extra.txt"), b"extra").unwrap();
3992 panic!("simulated loss");
3993 }
3994 },
3995 );
3996 }));
3997 assert!(crash.is_err());
3998 let result = execute_root_reconstruction(
3999 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4000 .unwrap(),
4001 &package,
4002 &destination,
4003 );
4004 assert!(matches!(
4005 result,
4006 Err(RootReconstructionError::OperationConflict)
4007 ));
4008 assert_eq!(
4009 std::fs::read(
4010 parent
4011 .join(staged_root_name(operation_id))
4012 .join("extra.txt")
4013 )
4014 .unwrap(),
4015 b"extra"
4016 );
4017
4018 #[cfg(unix)]
4019 {
4020 use std::os::unix::fs::PermissionsExt;
4021 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000121";
4022 let destination =
4023 RetainedReconstructionDestination::open(&parent, "mode-target").unwrap();
4024 let crash = catch_unwind(AssertUnwindSafe(|| {
4025 let _ = execute_root_reconstruction_with_phase_callback(
4026 RootReconstructionOperation::new(
4027 &plan,
4028 operation_id,
4029 plan.package_index_sha256(),
4030 )
4031 .unwrap(),
4032 &package,
4033 &destination,
4034 |phase| {
4035 if phase == RootReconstructionPhase::VerifiedStaging {
4036 let file = parent
4037 .join(staged_root_name(operation_id))
4038 .join("current.txt");
4039 std::fs::set_permissions(&file, std::fs::Permissions::from_mode(0o755))
4040 .unwrap();
4041 panic!("simulated loss");
4042 }
4043 },
4044 );
4045 }));
4046 assert!(crash.is_err());
4047 let result = execute_root_reconstruction(
4048 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4049 .unwrap(),
4050 &package,
4051 &destination,
4052 )
4053 .expect("retry repairs exact executable fidelity");
4054 assert!(!result.replayed());
4055 assert_eq!(
4056 std::fs::metadata(parent.join("mode-target/current.txt"))
4057 .unwrap()
4058 .permissions()
4059 .mode()
4060 & 0o111,
4061 0
4062 );
4063 }
4064 }
4065
4066 #[test]
4067 fn post_publication_phase_losses_replay_and_retire_only_owned_records() {
4068 for (suffix, crash_phase) in [
4069 ("130", RootReconstructionPhase::Publication),
4070 ("131", RootReconstructionPhase::CompletionDurable),
4071 ] {
4072 let temporary = tempfile::tempdir().unwrap();
4073 let source = temporary.path().join("package");
4074 let parent = temporary.path().join("destinations");
4075 std::fs::create_dir(&source).unwrap();
4076 std::fs::create_dir(&parent).unwrap();
4077 let fixture = complete_fixture();
4078 write_package(&source, &fixture);
4079 let plan = plan_from_fixture(&fixture);
4080 let package = RetainedReconstructionPackage::open(&source).unwrap();
4081 let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4082 let operation_id = format!("reconstruction_01900000-0000-7000-8000-000000000{suffix}");
4083
4084 let crashed = catch_unwind(AssertUnwindSafe(|| {
4085 let _ = execute_root_reconstruction_with_phase_callback(
4086 RootReconstructionOperation::new(
4087 &plan,
4088 &operation_id,
4089 plan.package_index_sha256(),
4090 )
4091 .unwrap(),
4092 &package,
4093 &destination,
4094 |phase| {
4095 if phase == crash_phase {
4096 panic!("simulated post-publication loss");
4097 }
4098 },
4099 );
4100 }));
4101 assert!(crashed.is_err());
4102 assert!(parent.join("restored").is_dir());
4103
4104 let replay = execute_root_reconstruction(
4105 RootReconstructionOperation::new(&plan, &operation_id, plan.package_index_sha256())
4106 .unwrap(),
4107 &package,
4108 &destination,
4109 )
4110 .expect("published completion replays");
4111 assert!(replay.replayed());
4112 assert!(!parent.join(stage_owner_name(&operation_id)).exists());
4113 assert!(!parent.join(stage_proof_name(&operation_id)).exists());
4114 }
4115 }
4116
4117 #[test]
4118 fn durable_owned_stage_entry_without_proof_converges_on_retry() {
4119 let temporary = tempfile::tempdir().unwrap();
4120 let source = temporary.path().join("package");
4121 let parent = temporary.path().join("destinations");
4122 std::fs::create_dir(&source).unwrap();
4123 std::fs::create_dir(&parent).unwrap();
4124 let fixture = complete_fixture();
4125 write_package(&source, &fixture);
4126 let plan = plan_from_fixture(&fixture);
4127 let package = RetainedReconstructionPackage::open(&source).unwrap();
4128 let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4129 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000132";
4130
4131 let crashed = catch_unwind(AssertUnwindSafe(|| {
4132 let _ = execute_root_reconstruction_with_phase_callback(
4133 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4134 .unwrap(),
4135 &package,
4136 &destination,
4137 |phase| {
4138 if phase == RootReconstructionPhase::StageEntryDurable {
4139 panic!("simulated loss after durable stage entry");
4140 }
4141 },
4142 );
4143 }));
4144 assert!(crashed.is_err());
4145 assert!(!parent.join("restored").exists());
4146
4147 let recovered = execute_root_reconstruction(
4148 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4149 .unwrap(),
4150 &package,
4151 &destination,
4152 )
4153 .expect("exact owned stage resumes after loss before proof");
4154 assert!(!recovered.replayed());
4155 assert!(parent.join("restored").is_dir());
4156 }
4157
4158 #[test]
4159 fn same_byte_package_child_substitution_fails_closed() {
4160 let temporary = tempfile::tempdir().unwrap();
4161 let source = temporary.path().join("package");
4162 let parent = temporary.path().join("destinations");
4163 std::fs::create_dir(&source).unwrap();
4164 std::fs::create_dir(&parent).unwrap();
4165 let fixture = complete_fixture();
4166 write_package(&source, &fixture);
4167 let plan = plan_from_fixture(&fixture);
4168 let package = RetainedReconstructionPackage::open(&source).unwrap();
4169 let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4170 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000133";
4171 let chunk_name = std::fs::read_dir(source.join("chunks"))
4172 .unwrap()
4173 .next()
4174 .unwrap()
4175 .unwrap()
4176 .file_name();
4177 let chunk_path = source.join("chunks").join(chunk_name);
4178 let original = std::fs::read(&chunk_path).unwrap();
4179 let mut substituted = false;
4180
4181 let result = execute_root_reconstruction_with_phase_callback(
4182 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4183 .unwrap(),
4184 &package,
4185 &destination,
4186 |phase| {
4187 if phase == RootReconstructionPhase::PreparedJournal && !substituted {
4188 std::fs::remove_file(&chunk_path).unwrap();
4189 std::fs::write(&chunk_path, &original).unwrap();
4190 substituted = true;
4191 }
4192 },
4193 );
4194 assert!(matches!(
4195 result,
4196 Err(RootReconstructionError::PackageChanged(_))
4197 ));
4198 assert!(!parent.join("restored").exists());
4199 }
4200
4201 #[cfg(unix)]
4202 #[test]
4203 fn replay_operational_read_failure_is_not_destination_attention() {
4204 use std::os::unix::fs::PermissionsExt;
4205
4206 let temporary = tempfile::tempdir().unwrap();
4207 let source = temporary.path().join("package");
4208 let parent = temporary.path().join("destinations");
4209 std::fs::create_dir(&source).unwrap();
4210 std::fs::create_dir(&parent).unwrap();
4211 let fixture = complete_fixture();
4212 write_package(&source, &fixture);
4213 let plan = plan_from_fixture(&fixture);
4214 let package = RetainedReconstructionPackage::open(&source).unwrap();
4215 let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4216 let operation_id = "reconstruction_01900000-0000-7000-8000-000000000134";
4217 execute_root_reconstruction(
4218 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4219 .unwrap(),
4220 &package,
4221 &destination,
4222 )
4223 .unwrap();
4224
4225 let completion = parent.join("restored").join(COMPLETED_RECONSTRUCTION_PATH);
4226 std::fs::set_permissions(&completion, std::fs::Permissions::from_mode(0o000)).unwrap();
4227 let replay = execute_root_reconstruction(
4228 RootReconstructionOperation::new(&plan, operation_id, plan.package_index_sha256())
4229 .unwrap(),
4230 &package,
4231 &destination,
4232 );
4233 std::fs::set_permissions(&completion, std::fs::Permissions::from_mode(0o600)).unwrap();
4234
4235 assert!(replay.is_err());
4236 assert!(!matches!(
4237 replay,
4238 Err(RootReconstructionError::DestinationOccupied(_))
4239 ));
4240 }
4241
4242 #[cfg(unix)]
4243 #[test]
4244 fn unsafe_package_permissions_and_hardlink_aliases_fail_before_staging() {
4245 use std::os::unix::fs::PermissionsExt;
4246
4247 for (suffix, make_unsafe) in [("140", 0_u8), ("141", 1_u8)] {
4248 let temporary = tempfile::tempdir().unwrap();
4249 let source = temporary.path().join("package");
4250 let parent = temporary.path().join("destinations");
4251 std::fs::create_dir(&source).unwrap();
4252 std::fs::create_dir(&parent).unwrap();
4253 let fixture = complete_fixture();
4254 write_package(&source, &fixture);
4255 let plan = plan_from_fixture(&fixture);
4256 if make_unsafe == 0 {
4257 std::fs::set_permissions(
4258 source.join("index.json"),
4259 std::fs::Permissions::from_mode(0o666),
4260 )
4261 .unwrap();
4262 } else {
4263 let chunk = source.join("chunks").join(sha256(b"payload"));
4264 std::fs::hard_link(&chunk, temporary.path().join("chunk-alias")).unwrap();
4265 }
4266 let package = RetainedReconstructionPackage::open(&source).unwrap();
4267 let destination = RetainedReconstructionDestination::open(&parent, "restored").unwrap();
4268 let operation_id = format!("reconstruction_01900000-0000-7000-8000-000000000{suffix}");
4269 let result = execute_root_reconstruction(
4270 RootReconstructionOperation::new(&plan, &operation_id, plan.package_index_sha256())
4271 .unwrap(),
4272 &package,
4273 &destination,
4274 );
4275 assert!(matches!(
4276 result,
4277 Err(RootReconstructionError::UnsafePackage(_))
4278 ));
4279 assert!(!parent.join("restored").exists());
4280 assert!(!parent.join(staged_root_name(&operation_id)).exists());
4281 }
4282 }
4283
4284 #[test]
4285 fn closure_rejects_missing_root_live_and_retained_tombstone_roles() {
4286 let mut missing_fidelity = complete_fixture();
4287 mutate_index(&mut missing_fidelity, |index| {
4288 index["tombstone_fidelity"] = json!([]);
4289 });
4290 assert!(matches!(
4291 plan(missing_fidelity),
4292 Err(RootReconstructionError::TombstoneFidelityMismatch)
4293 ));
4294
4295 let mut missing_root = complete_fixture();
4296 mutate_index(&mut missing_root, |index| {
4297 index["references"]
4298 .as_array_mut()
4299 .expect("references")
4300 .remove(0);
4301 });
4302 assert!(matches!(
4303 plan(missing_root),
4304 Err(RootReconstructionError::MissingReference { object_version_id })
4305 if object_version_id == ROOT_VERSION_ID
4306 ));
4307
4308 let mut missing_live = complete_fixture();
4309 mutate_index(&mut missing_live, |index| {
4310 index["references"]
4311 .as_array_mut()
4312 .expect("references")
4313 .remove(1);
4314 });
4315 assert!(matches!(
4316 plan(missing_live),
4317 Err(RootReconstructionError::MissingReference { object_version_id })
4318 if object_version_id == LIVE_VERSION_ID
4319 ));
4320
4321 let mut missing_tombstone_role = complete_fixture();
4322 mutate_index(&mut missing_tombstone_role, |index| {
4323 index["references"][1]["roles"] = json!(["live_regular_file"]);
4324 });
4325 assert!(matches!(
4326 plan(missing_tombstone_role),
4327 Err(RootReconstructionError::ReferenceMismatch { object_version_id })
4328 if object_version_id == LIVE_VERSION_ID
4329 ));
4330 }
4331
4332 #[test]
4333 fn closure_rejects_duplicate_extra_and_out_of_order_references() {
4334 let mut duplicate = complete_fixture();
4335 mutate_index(&mut duplicate, |index| {
4336 let repeated = index["references"][1].clone();
4337 index["references"]
4338 .as_array_mut()
4339 .expect("references")
4340 .push(repeated);
4341 });
4342 assert!(matches!(
4343 plan(duplicate),
4344 Err(RootReconstructionError::DuplicateReference { .. })
4345 ));
4346
4347 let mut extra = complete_fixture();
4348 mutate_index(&mut extra, |index| {
4349 index["references"]
4350 .as_array_mut()
4351 .expect("references")
4352 .push(json!({
4353 "object_version_id": "version_01900000-0000-7000-8000-000000000099",
4354 "object_id": "obj_01900000-0000-7000-8000-000000000099",
4355 "roles": ["retained_tombstone"],
4356 "chunk_manifest_sha256": "99".repeat(32)
4357 }));
4358 });
4359 assert!(matches!(
4360 plan(extra),
4361 Err(RootReconstructionError::UnexpectedReference { .. })
4362 ));
4363
4364 let mut reordered = complete_fixture();
4365 mutate_index(&mut reordered, |index| {
4366 index["references"]
4367 .as_array_mut()
4368 .expect("references")
4369 .swap(0, 1);
4370 });
4371 assert!(matches!(
4372 plan(reordered),
4373 Err(RootReconstructionError::ReferencesOutOfOrder)
4374 ));
4375 }
4376
4377 #[test]
4378 fn manifests_must_match_canonical_digest_and_version_digest_and_length() {
4379 let mut changed_plan = complete_fixture();
4380 let changed_manifest = manifest(b"changed", 0x33);
4381 changed_plan.manifests[0].encoded =
4382 Cursor::new(serde_json::to_vec(&changed_manifest).expect("encode changed manifest"));
4383 assert!(matches!(
4384 plan(changed_plan),
4385 Err(RootReconstructionError::ManifestDigestMismatch { .. })
4386 ));
4387
4388 let mut digest_mismatch = complete_fixture();
4389 let mut changed_digest = manifest(b"payload", 0x22);
4390 changed_digest.object_sha256 = "aa".repeat(32);
4391 replace_live_manifest(&mut digest_mismatch, changed_digest);
4392 assert!(matches!(
4393 plan(digest_mismatch),
4394 Err(RootReconstructionError::ManifestObjectMismatch { object_version_id })
4395 if object_version_id == LIVE_VERSION_ID
4396 ));
4397
4398 let mut length_mismatch = complete_fixture();
4399 let mut changed_length = manifest(b"payload", 0x22);
4400 changed_length.object_bytes += 1;
4401 changed_length.chunks[0].bytes += 1;
4402 replace_live_manifest(&mut length_mismatch, changed_length);
4403 assert!(matches!(
4404 plan(length_mismatch),
4405 Err(RootReconstructionError::ManifestObjectMismatch { object_version_id })
4406 if object_version_id == LIVE_VERSION_ID
4407 ));
4408 }
4409
4410 #[test]
4411 fn manifest_set_is_exact_without_missing_duplicate_or_unreferenced_documents() {
4412 let mut missing = complete_fixture();
4413 missing.manifests.pop();
4414 assert!(matches!(
4415 plan(missing),
4416 Err(RootReconstructionError::MissingManifest { .. })
4417 ));
4418
4419 let mut duplicate = complete_fixture();
4420 let digest = duplicate.manifests[0].digest().to_owned();
4421 let encoded = duplicate.manifests[0].encoded.get_ref().clone();
4422 duplicate
4423 .manifests
4424 .push(ManifestInput::new(digest, Cursor::new(encoded)));
4425 assert!(matches!(
4426 plan(duplicate),
4427 Err(RootReconstructionError::DuplicateManifest { .. })
4428 ));
4429
4430 let mut extra = complete_fixture();
4431 let extra_manifest = manifest(b"extra", 0x44);
4432 let extra_digest = extra_manifest.canonical_digest().expect("valid manifest");
4433 extra
4434 .manifests
4435 .push(manifest_input(extra_digest, extra_manifest));
4436 assert!(matches!(
4437 plan(extra),
4438 Err(RootReconstructionError::UnreferencedManifest { .. })
4439 ));
4440 }
4441
4442 #[test]
4443 fn fixed_limits_and_encoded_input_bounds_fail_closed() {
4444 let mut changed_limits = complete_fixture();
4445 mutate_index(&mut changed_limits, |index| {
4446 index["limits"]["max_visible_entries"] = json!(16_383);
4447 });
4448 assert!(matches!(
4449 plan(changed_limits),
4450 Err(RootReconstructionError::LimitsMismatch)
4451 ));
4452
4453 let too_many_references = serde_json::to_vec(&json!({
4454 "references": vec![Value::Null; MAX_PACKAGE_REFERENCES + 1]
4455 }))
4456 .expect("encode count probe");
4457 let empty_manifests: Vec<ManifestInput<Cursor<Vec<u8>>>> = Vec::new();
4458 assert!(matches!(
4459 decode_and_plan(
4460 too_many_references.as_slice(),
4461 std::io::empty(),
4462 empty_manifests
4463 ),
4464 Err(RootReconstructionError::TooManyReferences { .. })
4465 ));
4466
4467 let empty_manifests: Vec<ManifestInput<Cursor<Vec<u8>>>> = Vec::new();
4468 assert!(matches!(
4469 decode_and_plan(
4470 std::io::repeat(b' ').take(MAX_PACKAGE_INDEX_BYTES + 1),
4471 std::io::empty(),
4472 empty_manifests
4473 ),
4474 Err(RootReconstructionError::IndexTooLarge { .. })
4475 ));
4476
4477 let fixture = complete_fixture();
4478 let oversized_digest = fixture.manifests[0].digest().to_owned();
4479 let mut boxed_inputs: Vec<ManifestInput<Box<dyn std::io::Read>>> = Vec::new();
4480 for input in fixture.manifests {
4481 let reader: Box<dyn std::io::Read> = if input.digest() == oversized_digest {
4482 Box::new(std::io::repeat(b' ').take(MAX_PACKAGE_MANIFEST_BYTES + 1))
4483 } else {
4484 Box::new(input.encoded)
4485 };
4486 boxed_inputs.push(ManifestInput::new(input.chunk_manifest_sha256, reader));
4487 }
4488 assert!(matches!(
4489 decode_and_plan(
4490 fixture.index.as_slice(),
4491 fixture.version.as_slice(),
4492 boxed_inputs
4493 ),
4494 Err(RootReconstructionError::InvalidManifest {
4495 source: ManifestError::EncodedManifestTooLarge { .. },
4496 ..
4497 })
4498 ));
4499 }
4500
4501 fn complete_fixture() -> Fixture {
4502 let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4503 let live_manifest = manifest(b"payload", 0x22);
4504 let root_manifest_digest = root_manifest.canonical_digest().expect("valid manifest");
4505 let live_manifest_digest = live_manifest.canonical_digest().expect("valid manifest");
4506 let version_value = version_json(&root_manifest, &live_manifest);
4507 let version = serde_json::to_vec(&version_value).expect("encode version");
4508 let decoded = FolderbaseVersion::decode_bounded(version.as_slice()).expect("valid version");
4509 let mut references = vec![
4510 json!({
4511 "object_version_id": ROOT_VERSION_ID,
4512 "roles": ["root_manifest"],
4513 "chunk_manifest_sha256": root_manifest_digest,
4514 }),
4515 json!({
4516 "object_version_id": LIVE_VERSION_ID,
4517 "object_id": LIVE_OBJECT_ID,
4518 "roles": ["live_regular_file", "retained_tombstone"],
4519 "chunk_manifest_sha256": live_manifest_digest,
4520 }),
4521 ];
4522 references.sort_by(|left, right| {
4523 left["object_version_id"]
4524 .as_str()
4525 .expect("object version")
4526 .as_bytes()
4527 .cmp(
4528 right["object_version_id"]
4529 .as_str()
4530 .expect("object version")
4531 .as_bytes(),
4532 )
4533 });
4534 let index = serde_json::to_vec(&json!({
4535 "format": "folderbase-root-reconstruction-package-v1",
4536 "folderbase_id": FOLDERBASE_ID,
4537 "folderbase_version_id": FOLDERBASE_VERSION_ID,
4538 "canonical_version_sha256": decoded.canonical_digest().expect("version digest"),
4539 "encoded_version_sha256": sha256(&version),
4540 "limits": package_limits(),
4541 "references": references,
4542 "tombstone_fidelity": [{
4543 "path": "previous.txt",
4544 "object_id": LIVE_OBJECT_ID,
4545 "object_version_id": LIVE_VERSION_ID,
4546 "executable": false
4547 }],
4548 }))
4549 .expect("encode index");
4550 let mut manifests = vec![
4551 manifest_input(root_manifest_digest, root_manifest),
4552 manifest_input(live_manifest_digest, live_manifest),
4553 ];
4554 manifests.sort_by(|left, right| left.digest().as_bytes().cmp(right.digest().as_bytes()));
4555 Fixture {
4556 index,
4557 version,
4558 manifests,
4559 }
4560 }
4561
4562 fn tombstone_only_fixture() -> Fixture {
4563 let root_manifest = manifest(&root_manifest_bytes(), 0x11);
4564 let retained_manifest = manifest(b"payload", 0x22);
4565 let root_manifest_digest = root_manifest.canonical_digest().expect("valid manifest");
4566 let retained_manifest_digest = retained_manifest
4567 .canonical_digest()
4568 .expect("valid manifest");
4569 let mut version_value = version_json(&root_manifest, &retained_manifest);
4570 version_value["bindings"] = json!([]);
4571 let version = serde_json::to_vec(&version_value).expect("encode version");
4572 let decoded = FolderbaseVersion::decode_bounded(version.as_slice()).expect("valid version");
4573 let mut references = vec![
4574 json!({
4575 "object_version_id": ROOT_VERSION_ID,
4576 "roles": ["root_manifest"],
4577 "chunk_manifest_sha256": root_manifest_digest,
4578 }),
4579 json!({
4580 "object_version_id": LIVE_VERSION_ID,
4581 "object_id": LIVE_OBJECT_ID,
4582 "roles": ["retained_tombstone"],
4583 "chunk_manifest_sha256": retained_manifest_digest,
4584 }),
4585 ];
4586 references.sort_by(|left, right| {
4587 left["object_version_id"]
4588 .as_str()
4589 .expect("object version")
4590 .as_bytes()
4591 .cmp(
4592 right["object_version_id"]
4593 .as_str()
4594 .expect("object version")
4595 .as_bytes(),
4596 )
4597 });
4598 let index = serde_json::to_vec(&json!({
4599 "format": "folderbase-root-reconstruction-package-v1",
4600 "folderbase_id": FOLDERBASE_ID,
4601 "folderbase_version_id": FOLDERBASE_VERSION_ID,
4602 "canonical_version_sha256": decoded.canonical_digest().expect("version digest"),
4603 "encoded_version_sha256": sha256(&version),
4604 "limits": package_limits(),
4605 "references": references,
4606 "tombstone_fidelity": [{
4607 "path": "previous.txt",
4608 "object_id": LIVE_OBJECT_ID,
4609 "object_version_id": LIVE_VERSION_ID,
4610 "executable": true
4611 }],
4612 }))
4613 .expect("encode index");
4614 let mut manifests = vec![
4615 manifest_input(root_manifest_digest, root_manifest),
4616 manifest_input(retained_manifest_digest, retained_manifest),
4617 ];
4618 manifests.sort_by(|left, right| left.digest().as_bytes().cmp(right.digest().as_bytes()));
4619 Fixture {
4620 index,
4621 version,
4622 manifests,
4623 }
4624 }
4625
4626 fn plan(fixture: Fixture) -> Result<super::RootReconstructionPlan, RootReconstructionError> {
4627 decode_and_plan(
4628 fixture.index.as_slice(),
4629 fixture.version.as_slice(),
4630 fixture.manifests,
4631 )
4632 }
4633
4634 fn plan_from_fixture(fixture: &Fixture) -> super::RootReconstructionPlan {
4635 let manifests = fixture
4636 .manifests
4637 .iter()
4638 .map(|input| {
4639 ManifestInput::new(input.digest(), Cursor::new(input.encoded.get_ref().clone()))
4640 })
4641 .collect::<Vec<_>>();
4642 decode_and_plan(
4643 fixture.index.as_slice(),
4644 fixture.version.as_slice(),
4645 manifests,
4646 )
4647 .expect("complete plan")
4648 }
4649
4650 fn write_package(root: &std::path::Path, fixture: &Fixture) {
4651 std::fs::create_dir(root.join("manifests")).expect("manifest directory");
4652 std::fs::create_dir(root.join("chunks")).expect("chunk directory");
4653 std::fs::write(root.join("index.json"), &fixture.index).expect("package index");
4654 std::fs::write(root.join("version.json"), &fixture.version).expect("package Version");
4655 for input in &fixture.manifests {
4656 std::fs::write(
4657 root.join("manifests")
4658 .join(format!("{}.json", input.digest())),
4659 input.encoded.get_ref(),
4660 )
4661 .expect("package manifest");
4662 }
4663 for bytes in [root_manifest_bytes(), b"payload".to_vec()] {
4664 std::fs::write(root.join("chunks").join(sha256(&bytes)), bytes).expect("package chunk");
4665 }
4666 }
4667
4668 fn package_tree_snapshot(root: &Path) -> BTreeMap<String, Vec<u8>> {
4669 fn visit(root: &Path, relative: &Path, snapshot: &mut BTreeMap<String, Vec<u8>>) {
4670 let directory = root.join(relative);
4671 let mut entries = std::fs::read_dir(&directory)
4672 .expect("read package directory")
4673 .map(|entry| entry.expect("read package entry"))
4674 .collect::<Vec<_>>();
4675 entries.sort_by_key(|entry| entry.file_name());
4676 for entry in entries {
4677 let child_relative = relative.join(entry.file_name());
4678 let wire = child_relative
4679 .components()
4680 .map(|component| component.as_os_str().to_string_lossy())
4681 .collect::<Vec<_>>()
4682 .join("/");
4683 let metadata = entry.metadata().expect("package entry metadata");
4684 if metadata.is_dir() {
4685 snapshot.insert(wire, b"directory".to_vec());
4686 visit(root, &child_relative, snapshot);
4687 } else {
4688 assert!(metadata.is_file(), "package contains only regular files");
4689 snapshot.insert(wire, std::fs::read(entry.path()).expect("package bytes"));
4690 }
4691 }
4692 }
4693
4694 let mut snapshot = BTreeMap::new();
4695 visit(root, Path::new(""), &mut snapshot);
4696 snapshot
4697 }
4698
4699 fn root_manifest_bytes() -> Vec<u8> {
4700 serde_json::to_vec_pretty(&json!({
4701 "$schema": "https://folderbase.ai/protocol/0.5/folderbase.schema.json",
4702 "protocol_version": "0.5.0",
4703 "folderbase": {
4704 "id": FOLDERBASE_ID,
4705 "name": "Root reconstruction test",
4706 "kind": "project",
4707 "status": "active",
4708 "created_at": "2026-08-06T00:00:00Z"
4709 },
4710 "adapters": [],
4711 "policies": {
4712 "availability": "keep_local",
4713 "structural_changes": "approve",
4714 "archive": "manual",
4715 "cloud_sync": "disabled",
4716 "capture_ignore": {
4717 "format": "folderbase-capture-ignore-v1",
4718 "rules": []
4719 }
4720 }
4721 }))
4722 .expect("root manifest")
4723 }
4724
4725 fn mutate_index(fixture: &mut Fixture, mutate: impl FnOnce(&mut Value)) {
4726 let mut index: Value = serde_json::from_slice(&fixture.index).expect("decode index");
4727 mutate(&mut index);
4728 fixture.index = serde_json::to_vec(&index).expect("encode index");
4729 }
4730
4731 fn replace_live_manifest(fixture: &mut Fixture, replacement: ChunkManifest) {
4732 let replacement_digest = replacement.canonical_digest().expect("valid replacement");
4733 let mut previous_digest = None;
4734 mutate_index(fixture, |index| {
4735 let reference = &mut index["references"][1];
4736 previous_digest = Some(
4737 reference["chunk_manifest_sha256"]
4738 .as_str()
4739 .expect("manifest digest")
4740 .to_owned(),
4741 );
4742 reference["chunk_manifest_sha256"] = json!(replacement_digest);
4743 });
4744 let previous_digest = previous_digest.expect("previous manifest digest");
4745 fixture
4746 .manifests
4747 .retain(|input| input.digest() != previous_digest);
4748 fixture
4749 .manifests
4750 .push(manifest_input(replacement_digest, replacement));
4751 }
4752
4753 fn version_json(root_manifest: &ChunkManifest, live_manifest: &ChunkManifest) -> Value {
4754 json!({
4755 "format": "folderbase-version-v1",
4756 "protocol_version": "0.5",
4757 "folderbase_id": FOLDERBASE_ID,
4758 "version_id": FOLDERBASE_VERSION_ID,
4759 "parents": [],
4760 "created_at": "2026-08-06T00:00:00Z",
4761 "path_policy": {
4762 "format": "folderbase-portable-path-v1",
4763 "normalization": "NFC",
4764 "normalization_unicode_version": "17.0.0",
4765 "case_folding": "full-default",
4766 "case_folding_unicode_version": "9.0.0"
4767 },
4768 "root_manifest": {
4769 "path": ".folderbase/manifest.json",
4770 "object_version_id": ROOT_VERSION_ID,
4771 "content_sha256": root_manifest.object_sha256,
4772 "bytes": root_manifest.object_bytes
4773 },
4774 "bindings": [
4775 {
4776 "path": "current.txt",
4777 "object_id": LIVE_OBJECT_ID,
4778 "lifecycle": "live",
4779 "kind": "regular_file",
4780 "object_version_id": LIVE_VERSION_ID,
4781 "content_sha256": live_manifest.object_sha256,
4782 "bytes": live_manifest.object_bytes,
4783 "executable": false
4784 },
4785 {
4786 "path": "shortcut",
4787 "object_id": "obj_01900000-0000-7000-8000-000000000007",
4788 "lifecycle": "live",
4789 "kind": "symlink",
4790 "object_version_id": SYMLINK_VERSION_ID,
4791 "target": "current.txt",
4792 "target_safety": "relative-within-folderbase"
4793 }
4794 ],
4795 "tombstones": [{
4796 "path": "previous.txt",
4797 "object_id": LIVE_OBJECT_ID,
4798 "lifecycle": "deleted",
4799 "deleted_kind": "regular_file",
4800 "last_object_version_id": LIVE_VERSION_ID
4801 }],
4802 "exclusions": []
4803 })
4804 }
4805
4806 fn package_limits() -> Value {
4807 json!({
4808 "max_index_bytes": 8_388_608,
4809 "max_version_bytes": 67_108_864,
4810 "max_manifest_bytes": 67_108_864,
4811 "max_references": 16_385,
4812 "max_distinct_manifests": 16_385,
4813 "max_distinct_chunks": 1_048_576,
4814 "max_chunks_per_manifest": 262_144,
4815 "max_object_bytes": 1_099_511_627_776_u64,
4816 "max_total_object_bytes": 9_007_199_254_740_991_u64,
4817 "max_visible_entries": 16_384
4818 })
4819 }
4820
4821 fn manifest(bytes: &[u8], _chunk_byte: u8) -> ChunkManifest {
4822 ChunkManifest {
4823 format: MANIFEST_FORMAT_V1.to_owned(),
4824 algorithm: CHUNKING_ALGORITHM_V1.to_owned(),
4825 profile: STANDARD_PROFILE_V1.to_owned(),
4826 minimum_chunk_bytes: 256 * 1024,
4827 average_chunk_bytes: 1024 * 1024,
4828 maximum_chunk_bytes: 4 * 1024 * 1024,
4829 object_sha256: sha256(bytes),
4830 object_bytes: bytes.len() as u64,
4831 chunks: vec![ChunkDescriptor {
4832 index: 0,
4833 offset: 0,
4834 bytes: bytes.len() as u64,
4835 sha256: sha256(bytes),
4836 }],
4837 }
4838 }
4839
4840 fn manifest_input(digest: String, manifest: ChunkManifest) -> ManifestInput<Cursor<Vec<u8>>> {
4841 ManifestInput::new(
4842 digest,
4843 Cursor::new(serde_json::to_vec(&manifest).expect("encode manifest")),
4844 )
4845 }
4846
4847 fn sha256(bytes: &[u8]) -> String {
4848 format!("{:x}", Sha256::digest(bytes))
4849 }
4850}