1use std::{
4 ffi::OsStr,
5 fs,
6 io::{self, Read},
7 path::{Component, Path, PathBuf},
8};
9
10use cap_std::{ambient_authority, fs::Dir};
11use serde::{Deserialize, Serialize};
12use sha2::{Digest, Sha256};
13use walkdir::WalkDir;
14
15use crate::{
16 ContentDigest, FolderbaseError, LocalVersionStore, ObjectId, Result, VersionId,
17 root_attestation::metadata_is_link_or_reparse,
18 traversal_policy::{
19 NestedFolderbaseBoundaryKind, classify_nested_folderbase_boundary,
20 is_reconstructable_directory, is_reserved_workspace_component as is_reserved_component,
21 },
22};
23
24pub const MAX_WORKSPACE_TEXT_BYTES: u64 = 2 * 1024 * 1024;
25const MAX_WORKSPACE_ENTRIES: usize = 50_000;
26const MAX_WORKSPACE_DEPTH: usize = 64;
27const ROOT_IGNORE_POLICY_PATH: &str = ".folderbaseignore";
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(rename_all = "lowercase")]
31pub enum WorkspaceEntryKind {
32 Folderbase,
33 Directory,
34 File,
35 Symlink,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
39pub struct WorkspaceEntry {
40 pub path: String,
41 pub name: String,
42 pub kind: WorkspaceEntryKind,
43 pub bytes: u64,
44 pub editable: bool,
45 pub reconstructable: bool,
46}
47
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49pub struct WorkspaceListing {
50 pub root: PathBuf,
51 pub entries: Vec<WorkspaceEntry>,
52}
53
54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55pub struct WorkspaceTextDocument {
56 pub path: String,
57 pub content: String,
58 pub sha256: String,
59 pub bytes: u64,
60}
61
62#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
63pub struct WorkspaceSaveResult {
64 pub path: String,
65 pub previous_sha256: String,
66 pub document: WorkspaceDocumentState,
67 pub object_id: ObjectId,
68 pub version_id: VersionId,
69}
70
71#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
72pub struct WorkspaceDocumentState {
73 pub path: String,
74 pub sha256: String,
75 pub bytes: u64,
76}
77
78pub fn list_workspace(root: impl AsRef<Path>) -> Result<WorkspaceListing> {
84 let root = canonical_folderbase_root(root.as_ref())?;
85 let mut entries = Vec::new();
86 let mut walker = WalkDir::new(&root)
87 .follow_links(false)
88 .sort_by_file_name()
89 .into_iter();
90
91 while let Some(next) = walker.next() {
92 let entry = next.map_err(|error| {
93 let path = error
94 .path()
95 .map(Path::to_path_buf)
96 .unwrap_or_else(|| root.clone());
97 FolderbaseError::io(
98 path,
99 error
100 .into_io_error()
101 .unwrap_or_else(|| io::Error::other("workspace traversal failed")),
102 )
103 })?;
104 if entry.depth() == 0 {
105 continue;
106 }
107 if entry.depth() > MAX_WORKSPACE_DEPTH {
108 return Err(invalid_workspace_record(
109 &root,
110 format!("workspace traversal exceeds the {MAX_WORKSPACE_DEPTH} level depth limit"),
111 ));
112 }
113
114 let file_type = entry.file_type();
115 let name = entry.file_name();
116 if is_reserved_workspace_component(name) {
117 if file_type.is_dir() {
118 walker.skip_current_dir();
119 }
120 continue;
121 }
122 let is_collapsed_reconstructable = file_type.is_dir() && is_reconstructable_directory(name);
123 let is_nested_folderbase_boundary =
124 file_type.is_dir() && has_nested_folderbase_marker(entry.path())?;
125
126 if entries.len() == MAX_WORKSPACE_ENTRIES {
127 return Err(invalid_workspace_record(
128 &root,
129 format!("workspace traversal exceeds {MAX_WORKSPACE_ENTRIES} entries"),
130 ));
131 }
132
133 let relative = entry
134 .path()
135 .strip_prefix(&root)
136 .map_err(|_| FolderbaseError::UnsafePath(entry.path().to_path_buf()))?;
137 let path = displayable_path(relative)?;
138 let name = name
139 .to_str()
140 .map(ToOwned::to_owned)
141 .ok_or_else(|| FolderbaseError::UnsafePath(relative.to_path_buf()))?;
142 let metadata = fs::symlink_metadata(entry.path())
143 .map_err(|source| FolderbaseError::io(entry.path(), source))?;
144
145 let (kind, bytes, editable) = if is_nested_folderbase_boundary {
146 (WorkspaceEntryKind::Folderbase, 0, false)
147 } else if file_type.is_symlink() {
148 (WorkspaceEntryKind::Symlink, 0, false)
149 } else if file_type.is_dir() {
150 (WorkspaceEntryKind::Directory, 0, false)
151 } else if file_type.is_file() {
152 let bytes = metadata.len();
153 (
154 WorkspaceEntryKind::File,
155 bytes,
156 refuse_generic_workspace_mutation_path(relative).is_ok()
157 && file_is_editable(entry.path(), bytes)?,
158 )
159 } else {
160 continue;
161 };
162
163 entries.push(WorkspaceEntry {
164 path,
165 name,
166 kind,
167 bytes,
168 editable,
169 reconstructable: is_collapsed_reconstructable && !is_nested_folderbase_boundary,
170 });
171 if is_collapsed_reconstructable || is_nested_folderbase_boundary {
172 walker.skip_current_dir();
173 }
174 }
175
176 entries.sort_by(|left, right| left.path.cmp(&right.path));
177 Ok(WorkspaceListing { root, entries })
178}
179
180pub fn read_workspace_text(
182 root: impl AsRef<Path>,
183 relative_path: impl AsRef<Path>,
184) -> Result<WorkspaceTextDocument> {
185 let root = canonical_folderbase_root(root.as_ref())?;
186 let relative_path = safe_workspace_path(relative_path.as_ref())?;
187 let (file_path, relative_path) = resolve_existing_workspace_file(&root, &relative_path)?;
188 let metadata =
189 fs::metadata(&file_path).map_err(|source| FolderbaseError::io(&file_path, source))?;
190 if metadata.len() > MAX_WORKSPACE_TEXT_BYTES {
191 return Err(workspace_text_too_large(&relative_path));
192 }
193
194 let bytes = read_limited(&file_path)?;
195 if bytes.contains(&0) {
196 return Err(invalid_workspace_record(
197 &relative_path,
198 "workspace text contains a NUL byte",
199 ));
200 }
201 let content = String::from_utf8(bytes.clone())
202 .map_err(|_| invalid_workspace_record(&relative_path, "workspace file is not UTF-8"))?;
203
204 Ok(WorkspaceTextDocument {
205 path: displayable_path(&relative_path)?,
206 content,
207 sha256: format!("{:x}", Sha256::digest(&bytes)),
208 bytes: bytes.len() as u64,
209 })
210}
211
212pub fn save_workspace_text(
215 root: impl AsRef<Path>,
216 relative_path: impl AsRef<Path>,
217 expected_sha256: &str,
218 content: &str,
219) -> Result<WorkspaceSaveResult> {
220 let root = canonical_folderbase_root(root.as_ref())?;
221 let relative_path = safe_workspace_path(relative_path.as_ref())?;
222 refuse_generic_workspace_mutation_path(&relative_path)?;
223 validate_sha256(expected_sha256, &relative_path)?;
224 if content.len() as u64 > MAX_WORKSPACE_TEXT_BYTES {
225 return Err(workspace_text_too_large(&relative_path));
226 }
227 if content.contains('\0') {
228 return Err(invalid_workspace_record(
229 &relative_path,
230 "workspace text contains a NUL byte",
231 ));
232 }
233
234 let (_, relative_path) = resolve_existing_workspace_file(&root, &relative_path)?;
238 refuse_generic_workspace_mutation_path(&relative_path)?;
239 let current = read_workspace_text(&root, &relative_path)?;
240 if current.sha256 != expected_sha256 {
241 return Err(FolderbaseError::WorkspaceContentChanged(relative_path));
242 }
243
244 let expected = ContentDigest {
245 algorithm: "sha256".to_owned(),
246 digest: expected_sha256.to_owned(),
247 bytes: current.bytes,
248 };
249 let versioned = LocalVersionStore::open(&root)?.replace_file_versioned(
250 &relative_path,
251 &expected,
252 content.as_bytes(),
253 )?;
254 let path = displayable_path(&relative_path)?;
255 let document = WorkspaceDocumentState {
256 path: path.clone(),
257 sha256: versioned.content.digest.clone(),
258 bytes: versioned.content.bytes,
259 };
260 Ok(WorkspaceSaveResult {
261 path,
262 previous_sha256: versioned.previous_content.digest,
263 document,
264 object_id: versioned.object_id,
265 version_id: versioned.version_id,
266 })
267}
268
269pub(crate) fn canonical_folderbase_root(root: &Path) -> Result<PathBuf> {
270 let metadata = fs::symlink_metadata(root).map_err(|source| match source.kind() {
271 io::ErrorKind::NotFound => FolderbaseError::InvalidRoot(root.to_path_buf()),
272 _ => FolderbaseError::io(root, source),
273 })?;
274 if metadata_is_link_or_reparse(&metadata) || !metadata.is_dir() {
275 return Err(FolderbaseError::InvalidRoot(root.to_path_buf()));
276 }
277 root.canonicalize()
278 .map_err(|source| FolderbaseError::io(root, source))
279}
280
281pub(crate) fn safe_workspace_path(path: &Path) -> Result<PathBuf> {
282 if path.as_os_str().is_empty() || path.is_absolute() || path.to_str().is_none() {
283 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
284 }
285 let mut normalized = PathBuf::new();
286 for component in path.components() {
287 let Component::Normal(name) = component else {
288 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
289 };
290 if is_reserved_workspace_component(name) {
291 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
292 }
293 normalized.push(name);
294 }
295 if normalized.as_os_str().is_empty() {
296 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
297 }
298 Ok(normalized)
299}
300
301pub(crate) fn resolve_existing_workspace_file(
302 root: &Path,
303 relative: &Path,
304) -> Result<(PathBuf, PathBuf)> {
305 let relative = safe_workspace_path(relative)?;
306 let mut resolved = root.to_path_buf();
307 for component in relative.components() {
308 let Component::Normal(name) = component else {
309 return Err(FolderbaseError::UnsafePath(relative));
310 };
311 resolved.push(name);
312 let metadata = fs::symlink_metadata(&resolved)
313 .map_err(|source| FolderbaseError::io(&resolved, source))?;
314 if metadata.file_type().is_symlink() {
315 return Err(FolderbaseError::UnsafePath(resolved));
316 }
317 if metadata.is_dir() && has_nested_folderbase_marker(&resolved)? {
318 return Err(FolderbaseError::UnsafePath(relative.to_path_buf()));
319 }
320 }
321 let metadata =
322 fs::symlink_metadata(&resolved).map_err(|source| FolderbaseError::io(&resolved, source))?;
323 if !metadata.is_file() || metadata.file_type().is_symlink() {
324 return Err(invalid_workspace_record(
325 resolved,
326 "workspace path is not a regular file",
327 ));
328 }
329 let resolved = resolved
330 .canonicalize()
331 .map_err(|source| FolderbaseError::io(&resolved, source))?;
332 let canonical_relative = resolved
333 .strip_prefix(root)
334 .map_err(|_| FolderbaseError::UnsafePath(resolved.clone()))?
335 .to_path_buf();
336 Ok((resolved, canonical_relative))
337}
338
339pub(crate) fn is_reserved_workspace_component(name: &OsStr) -> bool {
340 is_reserved_component(name)
341}
342
343pub(crate) fn refuse_generic_workspace_mutation_path(path: &Path) -> Result<()> {
344 let mut components = path.components();
345 let is_root_ignore_policy = matches!(
346 components.next(),
347 Some(Component::Normal(name))
348 if name
349 .to_str()
350 .is_some_and(|name| name.eq_ignore_ascii_case(ROOT_IGNORE_POLICY_PATH))
351 ) && components.next().is_none();
352 if is_root_ignore_policy {
353 return Err(FolderbaseError::UnsafePath(path.to_path_buf()));
354 }
355 Ok(())
356}
357
358pub(crate) fn has_nested_folderbase_marker(path: &Path) -> Result<bool> {
359 let directory = Dir::open_ambient_dir(path, ambient_authority())
360 .map_err(|source| FolderbaseError::io(path, source))?;
361 match classify_nested_folderbase_boundary(&directory, path)? {
362 NestedFolderbaseBoundaryKind::ExactBoundary => Ok(true),
363 NestedFolderbaseBoundaryKind::None => Ok(false),
364 NestedFolderbaseBoundaryKind::UnsafeAliasShape => {
365 Err(FolderbaseError::UnsafePath(path.to_path_buf()))
366 }
367 }
368}
369
370fn displayable_path(path: &Path) -> Result<String> {
371 path.to_str()
372 .map(|value| value.replace(std::path::MAIN_SEPARATOR, "/"))
373 .ok_or_else(|| FolderbaseError::UnsafePath(path.to_path_buf()))
374}
375
376fn file_is_editable(path: &Path, bytes: u64) -> Result<bool> {
377 if bytes > MAX_WORKSPACE_TEXT_BYTES {
378 return Ok(false);
379 }
380 match read_limited(path) {
381 Ok(contents) => Ok(!contents.contains(&0) && std::str::from_utf8(&contents).is_ok()),
382 Err(FolderbaseError::InvalidRecord { message, .. })
383 if message.contains("workspace text exceeds") =>
384 {
385 Ok(false)
386 }
387 Err(error) => Err(error),
388 }
389}
390
391fn read_limited(path: &Path) -> Result<Vec<u8>> {
392 let file = fs::File::open(path).map_err(|source| FolderbaseError::io(path, source))?;
393 let mut contents = Vec::new();
394 file.take(MAX_WORKSPACE_TEXT_BYTES + 1)
395 .read_to_end(&mut contents)
396 .map_err(|source| FolderbaseError::io(path, source))?;
397 if contents.len() as u64 > MAX_WORKSPACE_TEXT_BYTES {
398 return Err(workspace_text_too_large(path));
399 }
400 Ok(contents)
401}
402
403fn workspace_text_too_large(path: &Path) -> FolderbaseError {
404 invalid_workspace_record(
405 path,
406 format!(
407 "workspace text exceeds the {} byte limit",
408 MAX_WORKSPACE_TEXT_BYTES
409 ),
410 )
411}
412
413fn validate_sha256(value: &str, path: &Path) -> Result<()> {
414 if value.len() != 64
415 || !value
416 .bytes()
417 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
418 {
419 return Err(invalid_workspace_record(
420 path,
421 "expected SHA-256 must be 64 lowercase hexadecimal characters",
422 ));
423 }
424 Ok(())
425}
426
427fn invalid_workspace_record(
428 path: impl Into<PathBuf>,
429 message: impl Into<String>,
430) -> FolderbaseError {
431 FolderbaseError::InvalidRecord {
432 path: path.into(),
433 message: message.into(),
434 }
435}
436
437#[cfg(test)]
438mod tests {
439 use super::*;
440
441 #[test]
442 fn generic_mutation_classifier_reserves_ascii_case_variants_only_at_the_root() {
443 for root_policy in [
444 ".folderbaseignore",
445 ".FOLDERBASEIGNORE",
446 ".FolderBaseIgnore",
447 ] {
448 assert!(matches!(
449 refuse_generic_workspace_mutation_path(Path::new(root_policy)),
450 Err(FolderbaseError::UnsafePath(path)) if path == Path::new(root_policy)
451 ));
452 }
453
454 for ordinary_path in [
455 "docs/.folderbaseignore",
456 "docs/.FOLDERBASEIGNORE",
457 ".folderbaseignore.txt",
458 ] {
459 assert!(
460 refuse_generic_workspace_mutation_path(Path::new(ordinary_path)).is_ok(),
461 "{ordinary_path} is not the root capture policy"
462 );
463 }
464 }
465}