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