From fad03b50c946b186799877a6c588b0e09f2a86ca Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 02:59:18 +0000 Subject: [PATCH 01/11] fix(store,doctor): hold a Store's folder to the daemon's 0700 rule (#570 port) Ported from #570 (8a85fa4b9 and the store part of 6be2f6c31), which was closed as ported into #647 but never reached layerfs_v2_0_0. The daemon's own startup already refuses an Overlay or Store parent this user does not own privately (`mode & 0o077 != 0`), and `store.create` makes `store/` 0700. The SDK's Store openers had no such rule: the kernel guard checked only the filesystem type, `project.init` guarded the parent of the Store's folder, and `install_local` and backup restore guarded the volume above the folder they then created. Doctor accepted a `0701` Store folder and suggested `chmod g-rwx,o-rw`, a mode no daemon opens. - `kernel_guard`: check the Store's own directory as a real `0700` directory of the current user, refusing a missing path, a symlink, another owner's directory and any group/other bit, and name the path, its mode, the expected `0700` and `chmod 700 `. The check stays side-effect-free: it never creates a directory or changes permissions. Linux and macOS, before the filesystem check. - `store.create`: create `store/` privately, let `make_empty` create `store/` as 0700, then guard the Store file path; a refusal removes the folder only when this call made it, never a user's existing one. - `project.init` and the SQLite diagnostic guard the Store file, so the folder checked is the Store's own. - `install_local` and backup `fetch` create the folder (`0700`) first, then guard the Store file, and remove the folder they made when the guard refuses. - daemon `config::private_directory`: name the path and the failing rule (type, owner uid, or mode with a `chmod 700` hint). - doctor: a Store folder is held to `0o077` with `chmod 700` as its fix, because the daemon refuses any group/other bit there; the home's other folders keep the `0701` pass-through allowance. Tests: `kernel_guard` (a missing directory is refused without being created, `open_direct` leaves no empty directory, `0700` passes for a `.sqlite` and a non-`.sqlite` name, `0755` is refused with path, mode, `0700` and `chmod 700`, and left untouched); `doctor` (a `0701` Store folder is one error naming `chmod 700`, and `0700` is ok while `store/` itself stays `0701`); `store_family` (`store.create` refuses a pre-existing `0755` folder without deleting it or changing its mode, and a new Store's folder is `0700`); `project_family` (`project.init` on a `0755` Store folder refuses naming the path and fix). Fixtures that put a Store in a shared temp directory now make its folder private: `diagnostic_structure`, `store_doctor`, `project_export` and `project_init_worker`. Docs: store-calls service (what the guard checks), store/create (the open order and the `Unsupported` row), project/init (`Unsupported`), daemon startup (the message), doctor (the Store folder row) and the versioned 2.0.0 pages for the `native` machine and doctor. Production LOC: 158272 -> 158376 (delta +104) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py --detail` on the exact parent e9b903eac (exported tree) and this tree. engine 73950 -> 74027 (+77: layerfs-store-service 14373 -> 14425, layerfs-daemon 8069 -> 8094); control 38975 -> 39002 (+27: layerfs-store 8567 -> 8573, layerfs-bucket 3788 -> 3797, layerfs-control 5443 -> 5455); core 39787 and api 5560 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: none. --- .../layerfs-api/tests/project_export.rs | 2 +- .../layerfs-api/tests/project_family.rs | 30 ++++++++ .../layerfs-api/tests/project_init_worker.rs | 2 +- api/crates/layerfs-api/tests/store_family.rs | 38 ++++++++++ .../layerfs-bucket/src/backup/restore.rs | 25 +++++-- .../crates/layerfs-control/src/doctor/scan.rs | 24 +++++- .../crates/layerfs-control/tests/doctor.rs | 29 ++++++++ .../layerfs-control/tests/store_doctor.rs | 2 +- control/crates/layerfs-store/src/identity.rs | 2 + .../crates/layerfs-store/src/project/add.rs | 3 +- .../crates/layerfs-store/src/sqlite/create.rs | 9 ++- .../tests/diagnostic_structure.rs | 23 +++++- docs/architecture/api/sdk/project/init.md | 4 +- docs/architecture/api/sdk/store/create.md | 9 ++- .../architecture/control/management/doctor.md | 1 + docs/architecture/engine/daemon/startup.md | 2 +- .../engine/store-calls/service.md | 9 ++- docs/versioned/2.0.0/calls.md | 3 +- docs/versioned/2.0.0/machines-and-stores.md | 2 +- .../layerfs-daemon/src/application/config.rs | 35 +++++++-- .../crates/layerfs-store-service/Cargo.toml | 2 +- .../layerfs-store-service/src/install.rs | 34 ++++++--- .../layerfs-store-service/src/kernel_guard.rs | 59 +++++++++++++-- .../tests/kernel_guard.rs | 74 ++++++++++++++++++- 24 files changed, 364 insertions(+), 59 deletions(-) diff --git a/api/crates/layerfs-api/tests/project_export.rs b/api/crates/layerfs-api/tests/project_export.rs index 7105001e88..51c869aaf8 100644 --- a/api/crates/layerfs-api/tests/project_export.rs +++ b/api/crates/layerfs-api/tests/project_export.rs @@ -874,7 +874,7 @@ fn branch_selection_and_pinned_snapshot_under_concurrent_writes() { fn move_store_file(from: &Path, to: &Path, store: &str) { let source = paths::store_dir(from, store); let target = paths::store_dir(to, store); - std::fs::create_dir_all(&target).unwrap(); + home::private_dir(&target).unwrap(); for entry in std::fs::read_dir(&source).unwrap() { let entry = entry.unwrap(); let name = entry.file_name().to_string_lossy().into_owned(); diff --git a/api/crates/layerfs-api/tests/project_family.rs b/api/crates/layerfs-api/tests/project_family.rs index 6785b14abc..fc4ba41bc0 100644 --- a/api/crates/layerfs-api/tests/project_family.rs +++ b/api/crates/layerfs-api/tests/project_family.rs @@ -86,6 +86,36 @@ fn init_files_branches_move_and_remove() { ); assert_eq!(refused.unwrap_err().0, "NotFound"); ok(&home, "store.create", &[("name", t("shop"))]); + // project.init on an existing Store refuses up front if its directory was + // made non-private (e.g. chmod 0755), reporting path, 0755, 0700 and chmod 700 + { + use std::os::unix::fs::PermissionsExt; + let shop_dir = paths::store_dir(&home, "shop"); + std::fs::set_permissions(&shop_dir, std::fs::Permissions::from_mode(0o755)).unwrap(); + let (code, message) = call( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ) + .unwrap_err(); + assert_eq!(code, "Unsupported", "{message}"); + assert!( + message.contains(&shop_dir.display().to_string()), + "{message}" + ); + assert!( + message.contains("0755") && message.contains("0700"), + "{message}" + ); + assert!( + message.contains(&format!("chmod 700 {}", shop_dir.display())), + "{message}" + ); + std::fs::set_permissions(&shop_dir, std::fs::Permissions::from_mode(0o700)).unwrap(); + } let mut events = Vec::new(); let args = SdkValue::map([ ("project", t("shop/api")), diff --git a/api/crates/layerfs-api/tests/project_init_worker.rs b/api/crates/layerfs-api/tests/project_init_worker.rs index 553f602218..d0f3900c4b 100644 --- a/api/crates/layerfs-api/tests/project_init_worker.rs +++ b/api/crates/layerfs-api/tests/project_init_worker.rs @@ -42,7 +42,7 @@ fn init_args(project: &str, folder: &Path) -> SdkValue { fn move_store_file(from: &Path, to: &Path, store: &str) { let source = paths::store_dir(from, store); let target = paths::store_dir(to, store); - std::fs::create_dir_all(&target).unwrap(); + home::private_dir(&target).unwrap(); for entry in std::fs::read_dir(&source).unwrap() { let entry = entry.unwrap(); let name = entry.file_name().to_string_lossy().into_owned(); diff --git a/api/crates/layerfs-api/tests/store_family.rs b/api/crates/layerfs-api/tests/store_family.rs index 8fa06e6312..36e5100aae 100644 --- a/api/crates/layerfs-api/tests/store_family.rs +++ b/api/crates/layerfs-api/tests/store_family.rs @@ -63,8 +63,46 @@ fn home_with_box() -> (PathBuf, PathBuf) { #[test] fn create_list_get_and_status() { + use std::os::unix::fs::PermissionsExt; let (home, root) = home_with_box(); + // a pre-existing store directory with group/other access is refused up + // front without changing the user's directory mode + let bad_dir = paths::store_dir(&home, "open-dir"); + home::private_dir(bad_dir.parent().unwrap()).unwrap(); + std::fs::create_dir_all(&bad_dir).unwrap(); + std::fs::set_permissions(&bad_dir, std::fs::Permissions::from_mode(0o755)).unwrap(); + let (code, message) = call(&home, "store.create", &[("name", t("open-dir"))]).unwrap_err(); + assert_eq!(code, "Unsupported", "{message}"); + assert!( + message.contains(&bad_dir.display().to_string()), + "{message}" + ); + assert!( + message.contains("0755") && message.contains("0700"), + "{message}" + ); + assert!( + message.contains(&format!("chmod 700 {}", bad_dir.display())), + "{message}" + ); + assert!(bad_dir.exists(), "user's existing directory is not deleted"); + assert_eq!( + std::fs::metadata(&bad_dir).unwrap().permissions().mode() & 0o7777, + 0o755, + "user's existing directory permissions are not modified" + ); + std::fs::remove_dir_all(&bad_dir).unwrap(); + let made = call(&home, "store.create", &[("name", t("shop"))]).unwrap(); + assert_eq!( + std::fs::metadata(paths::store_dir(&home, "shop")) + .unwrap() + .permissions() + .mode() + & 0o7777, + 0o700, + "a Store's own folder is 0700" + ); assert_eq!(made.get_text("machine"), Some("native")); assert!( made.get("cursor").is_none(), diff --git a/control/crates/layerfs-bucket/src/backup/restore.rs b/control/crates/layerfs-bucket/src/backup/restore.rs index a4aa64e622..8dec25bbb6 100644 --- a/control/crates/layerfs-bucket/src/backup/restore.rs +++ b/control/crates/layerfs-bucket/src/backup/restore.rs @@ -180,14 +180,23 @@ fn fetch( .parent() .ok_or("the Store destination has no directory")?; // as install_local: the volume holding the Store's directory - kernel_guard::check(directory).map_err(|reason| reason.0)?; - installer_user()?; - if !directory.exists() { - use std::os::unix::fs::DirBuilderExt; - fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .map_err(text)?; + let existed = directory.exists(); + let outcome = (|| { + installer_user()?; + if !existed { + use std::os::unix::fs::DirBuilderExt; + fs::DirBuilder::new() + .mode(0o700) + .create(directory) + .map_err(text)?; + } + kernel_guard::check(destination).map_err(|reason| reason.0) + })(); + if let Err(error) = outcome { + if !existed { + let _ = fs::remove_dir_all(directory); + } + return Err(error); } let (target, _) = paths(destination).map_err(text)?; let cloning = binding.is_none(); diff --git a/control/crates/layerfs-control/src/doctor/scan.rs b/control/crates/layerfs-control/src/doctor/scan.rs index cc8cd0567f..f3fb00cd4a 100644 --- a/control/crates/layerfs-control/src/doctor/scan.rs +++ b/control/crates/layerfs-control/src/doctor/scan.rs @@ -1,8 +1,8 @@ //! Every record of a layout 3 home, read once: whether it parses, whether //! an entity record has `"v": 1`, and the modes of the home's folders -//! (0700, or 0701 where a namespaces Sandbox passes through) and record -//! files (0600). A Store folder with projects and no Store record is -//! reported here too. +//! (0700, or 0701 where a namespaces Sandbox passes through; a Store's own +//! folder is 0700 like the daemon's rule) and record files (0600). A Store +//! folder with projects and no Store record is reported here too. use super::report::Findings; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::home::{paths, read_record, RECORD_VERSION}; @@ -78,7 +78,7 @@ pub(super) fn scan(home: &Path, findings: &mut Findings) -> Result { /// One Store's folder: its record and its projects'. fn store(home: &Path, name: &str, scanned: &mut Scanned, findings: &mut Findings) -> Result<()> { let entity = ("store", name); - folder(&paths::store_dir(home, name), entity, findings); + store_folder(&paths::store_dir(home, name), entity, findings); let path = paths::store_record(home, name); let has_record = path.exists(); if has_record { @@ -275,6 +275,22 @@ fn folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { } } +/// A Store's own folder is held to the daemon's rule (kernel_guard): no +/// group or other bits at all, not even pass-through, so a folder doctor +/// calls fine is one the daemon opens. +fn store_folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { + if let Some(mode) = mode(path).filter(|mode| mode & 0o077 != 0) { + findings.error( + entity, + format!( + "{} has mode {mode:04o}; a Store's folder is 0700", + path.display() + ), + format!("`chmod 700 {}`", path.display()), + ); + } +} + /// A record file others or its group may read is an error. fn file_mode(path: &Path, entity: (&str, &str), findings: &mut Findings) { if let Some(mode) = mode(path).filter(|mode| mode & 0o077 != 0) { diff --git a/control/crates/layerfs-control/tests/doctor.rs b/control/crates/layerfs-control/tests/doctor.rs index 7b3eeb9990..73a854b08e 100644 --- a/control/crates/layerfs-control/tests/doctor.rs +++ b/control/crates/layerfs-control/tests/doctor.rs @@ -146,6 +146,35 @@ fn a_clean_home_is_ok_with_no_findings() { std::fs::remove_dir_all(home).unwrap(); } +#[test] +fn a_store_folder_others_may_pass_through_is_an_error_naming_chmod_700() { + // #534: the daemon refuses a Store folder with any group/other bit, so + // doctor must not call 0701 fine there; other home folders keep 0701. + let home = new_home("store-0701"); + layerfs_control::migrate::open(&home).unwrap(); + store(&home, "shop", sqlite("shop", "native")); + let native = SdkValue::map([("name", t("native")), ("platform", t("native"))]); + write_entity(&paths::machine_record(&home, "native"), &native).unwrap(); + let dir = paths::store_dir(&home, "shop"); + std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o701)).unwrap(); + std::fs::set_permissions(home.join("store"), std::fs::Permissions::from_mode(0o701)).unwrap(); + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(false)), "{report:?}"); + let found = findings(&report); + assert_eq!(found.len(), 1, "{found:?}"); + let (severity, kind, name, message, fix) = &found[0]; + assert_eq!( + (severity.as_str(), kind.as_str(), name.as_str()), + ("error", "store", "shop") + ); + assert!(message.contains("0701"), "{message}"); + assert!(fix.contains("chmod 700"), "{fix}"); + std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap(); + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(true)), "{report:?}"); + std::fs::remove_dir_all(home).unwrap(); +} + #[test] fn a_home_that_does_not_exist_is_ok_and_stays_absent() { let home = new_home("absent"); diff --git a/control/crates/layerfs-control/tests/store_doctor.rs b/control/crates/layerfs-control/tests/store_doctor.rs index c603653d33..fc4a68ee02 100644 --- a/control/crates/layerfs-control/tests/store_doctor.rs +++ b/control/crates/layerfs-control/tests/store_doctor.rs @@ -105,7 +105,7 @@ fn worker_child() { fn actual_worker_audit_streams_and_cancelled_peer_does_not_poison_next_call() { let f = Fixture::new(); let path = paths::store_file(&f.root, "one"); - std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + layerfs_home::home::private_dir(path.parent().unwrap()).unwrap(); let authority = HistoryCatalogConfig { binding_key: b"doctor-worker".to_vec(), cursor_key: [9; 32], diff --git a/control/crates/layerfs-store/src/identity.rs b/control/crates/layerfs-store/src/identity.rs index fc972569a9..fa9bdf55a4 100644 --- a/control/crates/layerfs-store/src/identity.rs +++ b/control/crates/layerfs-store/src/identity.rs @@ -215,6 +215,8 @@ pub fn make_empty( .create(global) .map_err(failed)?; } + layerfs_store_service::kernel_guard::check(destination) + .map_err(|reason| refused("Unsupported", reason.0))?; let (target, _) = layerfs_store_service::install::paths(destination).map_err(failed)?; layerfs_store_service::install::absent(&target) .map_err(|error| refused("Exists", format!("{}: {error}", target.display())))?; diff --git a/control/crates/layerfs-store/src/project/add.rs b/control/crates/layerfs-store/src/project/add.rs index 4bf3122d22..af7e24516f 100644 --- a/control/crates/layerfs-store/src/project/add.rs +++ b/control/crates/layerfs-store/src/project/add.rs @@ -131,8 +131,7 @@ pub fn add_project(request: &ProjectAdd) -> Outcome { let deadline = crate::project::init::deadline(request.timeout_ms)?; let open = request.open(); let store_file = request.store_file(); - let global = store_file.parent().unwrap_or(&store_file); - layerfs_store_service::kernel_guard::check(global) + layerfs_store_service::kernel_guard::check(&store_file) .map_err(|reason| refused("Unsupported", reason.0))?; let identity = identity(&open)?; sqlite_only(&identity, "adding a project")?; diff --git a/control/crates/layerfs-store/src/sqlite/create.rs b/control/crates/layerfs-store/src/sqlite/create.rs index 4928f17e40..ed4474b58f 100644 --- a/control/crates/layerfs-store/src/sqlite/create.rs +++ b/control/crates/layerfs-store/src/sqlite/create.rs @@ -14,7 +14,10 @@ pub fn create(home: &Path, name: &StoreName) -> Outcome { return Err(refused("Exists", format!("a Store named {name} exists"))); } let directory = paths::store_dir(home, name); - home::private_dir(&directory)?; + let existed = directory.exists(); + if let Some(parent) = directory.parent() { + home::private_dir(parent)?; + } let identity = crate::identity::Identity { kind: crate::identity::Kind::Sqlite, binding: layerfs_home::helpers::random()?.to_vec(), @@ -26,7 +29,9 @@ pub fn create(home: &Path, name: &StoreName) -> Outcome { Ok(sealed) => sealed, Err(refusal) => { // nothing was published: this call's own directory goes - let _ = std::fs::remove_dir_all(&directory); + if !existed { + let _ = std::fs::remove_dir_all(&directory); + } return Err(refusal); } }; diff --git a/control/crates/layerfs-store/tests/diagnostic_structure.rs b/control/crates/layerfs-store/tests/diagnostic_structure.rs index 3d2caa060d..385882fb9d 100644 --- a/control/crates/layerfs-store/tests/diagnostic_structure.rs +++ b/control/crates/layerfs-store/tests/diagnostic_structure.rs @@ -3,9 +3,24 @@ use layerfs_store::{ diagnostic::{self, Options, Outcome}, identity::{Identity, Kind}, }; + +/// A private (`0700`) scratch directory for one Store file: the kernel guard +/// admits a Store's own directory only, as in a home. +fn scratch(label: &str) -> std::path::PathBuf { + use std::os::unix::fs::DirBuilderExt; + let directory = + std::env::temp_dir().join(format!("layerfs-doctor-{label}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&directory); + std::fs::DirBuilder::new() + .mode(0o700) + .create(&directory) + .unwrap(); + directory +} + #[test] fn selected_malformed_store_has_structural_failure_and_incomplete_access() { - let path = std::env::temp_dir().join(format!("layerfs-doctor-header-{}", std::process::id())); + let path = scratch("header").join("store.sqlite"); std::fs::write(&path, vec![0xA5; 8192]).unwrap(); let before = std::fs::read(&path).unwrap(); let mut observations = Vec::new(); @@ -27,14 +42,14 @@ fn selected_malformed_store_has_structural_failure_and_incomplete_access() { "{observations:?}" ); assert_eq!(std::fs::read(&path).unwrap(), before); - std::fs::remove_file(path).unwrap(); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); } #[test] fn binding_mismatch_keeps_logical_access_unavailable_without_corruption() { use layerfs_persistence::{PersistenceConfig, SqliteHandles, SqlitePersistenceProfile}; use layerfs_storage::StoragePolicy; - let path = std::env::temp_dir().join(format!("layerfs-doctor-binding-{}", std::process::id())); + let path = scratch("binding").join("store.sqlite"); let handles = SqliteHandles::create( PersistenceConfig::sqlite(&path).with_sqlite_profile(SqlitePersistenceProfile::Disposable), StoragePolicy::frozen_default(), @@ -72,5 +87,5 @@ fn binding_mismatch_keeps_logical_access_unavailable_without_corruption() { "{observations:?}" ); assert_eq!(std::fs::read(&path).unwrap(), before); - std::fs::remove_file(path).unwrap(); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); } diff --git a/docs/architecture/api/sdk/project/init.md b/docs/architecture/api/sdk/project/init.md index ca6c511fde..9aab9447ca 100644 --- a/docs/architecture/api/sdk/project/init.md +++ b/docs/architecture/api/sdk/project/init.md @@ -104,7 +104,7 @@ The summary is built in [`project/record.rs`](../../../../../control/crates/laye | Store kind | Platform of the Store's machine | Runs in | | --- | --- | --- | | PostgreSQL | any | caller's process (needs a build with the `postgresql` feature) | -| sqlite | executes locally (`native` on Linux or macOS) | caller's process; the kernel guard admits the Store's directory only on Linux ext4, xfs or btrfs, or macOS apfs or hfs | +| sqlite | executes locally (`native` on Linux or macOS) | caller's process; the kernel guard admits the Store's directory only when it is owned by this user and private (`0700`) on Linux ext4, xfs or btrfs, or macOS apfs or hfs | | sqlite | any other machine, and `native` on Windows | that machine's worker, on a copy of the folder | Init is a live add, not a seal: `ProjectApi::add_project` opens the @@ -127,7 +127,7 @@ Store calls hide that Branch: they treat `main` as the line of Layers (see | `Exists` | the project's record, entry or LayerStack name exists | no | `project/family.rs`, `store/identity.rs` | | `Capacity` | worker route: the machine's free disk is below the copy plus headroom | no | `project/send.rs` `room` | | `Unavailable` | worker route: no worker recorded, or not reached; nothing sent | no | [`place.rs`](../../../../../control/crates/layerfs-store/src/place.rs) | -| `Unsupported` | the kernel guard refuses the Store's filesystem; the Store has no acquisition tables; PostgreSQL in a build without `postgresql` | no | `store/identity.rs`, [`kernel_guard.rs`](../../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| `Unsupported` | the kernel guard refuses the Store's directory (non-private mode/owner/type or unsupported filesystem); the Store has no acquisition tables; PostgreSQL in a build without `postgresql` | no | `store/identity.rs`, [`kernel_guard.rs`](../../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | `NoStore` | no Store file at the Store's path | no | `store/identity.rs` | | `Failed` | deadline passed, read error, or any engine failure, **including an Init whose outcome is unknown** | **may be** | `store/identity.rs` `add_failure` | | `Unknown` | **worker route: a stage or the `project.init` answer was lost** | **yes** | [`worker/client.rs`](../../../../../control/crates/layerfs-machine/src/worker/client.rs) | diff --git a/docs/architecture/api/sdk/store/create.md b/docs/architecture/api/sdk/store/create.md index 6ce3d9fed5..7cfdc791c8 100644 --- a/docs/architecture/api/sdk/store/create.md +++ b/docs/architecture/api/sdk/store/create.md @@ -78,12 +78,14 @@ shown. The answer is the same shape as [store.get](get.md). StoreName::parse(name) home lock ----------------------------------- waits up to 120 s store//record.json exists? --> Exists - mkdir store// (0700) + mkdir store/ (0700) identity: kind sqlite, random binding, random cursor key - make_empty: ProjectApi::create_store -> store.sqlite.creating + make_empty: kernel_guard::check(store//store.sqlite) + (a real 0700 directory of this user; mkdir 0700 when absent) + ProjectApi::create_store -> store.sqlite.creating (Disposable profile, frozen default policy) chmod 0600; rename -> store//store.sqlite - failure: remove store// (nothing was published) + failure: remove store// (its own directory only; nothing was published) save_record + created_on_native; write record.json ``` @@ -103,6 +105,7 @@ create it and then [push](push.md) it. See the | `InvalidInput` | a bad Store name; a folder-scoped client | no | [`names.rs`](../../../../../control/crates/layerfs-home/src/names.rs), [`calls/scope.rs`](../../../../../api/crates/layerfs-api/src/calls/scope.rs) | | `Exists` | a Store record of that name exists, or a file is already at the target | no | [`sqlite/create.rs`](../../../../../control/crates/layerfs-store/src/sqlite/create.rs), [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs) `make_empty` | | `Unavailable` | another process held the home lock or the Store's lock for 120 s | no | [`home/lock.rs`](../../../../../control/crates/layerfs-home/src/home/lock.rs) | +| `Unsupported` | the kernel guard refuses `store//` (not on a local lock-carrying filesystem, or an existing directory is not owned by this user or has group/other access instead of mode `0700`) | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs), [`kernel_guard.rs`](../../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | `Failed` | the empty Store could not be made or written (`Store create: …`), or the record write failed | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs) | A failure before the record is written removes the call's own diff --git a/docs/architecture/control/management/doctor.md b/docs/architecture/control/management/doctor.md index 62244224a5..73c9b5de75 100644 --- a/docs/architecture/control/management/doctor.md +++ b/docs/architecture/control/management/doctor.md @@ -68,6 +68,7 @@ A live owner's `op` is not a finding: the operation is still running. | each machine, Store, project, Sandbox record | it does not parse, or an entity record's `v` is not 1 | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `record` | | record file mode | not 0600 (group or others may read) | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `file_mode` | | folder mode | others may list or change it, or its group may use it; 0701 is allowed | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `folder` | +| Store folder mode | any group or other bit at all: a Store's own folder is `0700`, as the daemon's rule (kernel guard) requires; 0701 is not allowed there | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `store_folder` | | Store folder | it has projects and no Store record | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `store` | | Sandbox folder | its record, `control.json` and Workspace records | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `sandbox` | | Workspace folder | each `workspace//` folder's mode, and each command record under its `exec/`; the doctor ends no command and removes no record | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `execs` | diff --git a/docs/architecture/engine/daemon/startup.md b/docs/architecture/engine/daemon/startup.md index 7dc4231d16..f38146e59b 100644 --- a/docs/architecture/engine/daemon/startup.md +++ b/docs/architecture/engine/daemon/startup.md @@ -39,7 +39,7 @@ carry no key and no command. | `command_uid` differs from the daemon uid, except on the NFS route | `command and daemon identities must differ` | [`config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | | `serial_low_water` below `layerfs_workspace::SERIAL_REFILL` | `serial low-water must be below the refill window` | [`config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | | Store, overlay and config paths outside the mount home; Store is not the overlay file | `separate protected backing and mount paths` | [`config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | -| Overlay and Store parents are private `0700` directories (created once if absent); an installed Store file is protected | `private directory ownership/mode/type` | [`config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | +| Overlay and Store parents are private `0700` directories (created once if absent); an installed Store file is protected | `private directory ownership/mode/type at : …` | [`config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | The `DaemonSetup` fields are listed on [Bridge: Daemon setup](bridge.md#daemon-setup). diff --git a/docs/architecture/engine/store-calls/service.md b/docs/architecture/engine/store-calls/service.md index 3e67765561..e85d2e3c41 100644 --- a/docs/architecture/engine/store-calls/service.md +++ b/docs/architecture/engine/store-calls/service.md @@ -77,9 +77,12 @@ Backend details are in [Store: Lifecycle](../store/lifecycle.md) and [Store: Backends](../store/backends.md). The kernel guard ([`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs)) -allows ext4, xfs and btrfs on Linux and apfs or hfs on macOS (for the native -Sandbox, where the SDK and daemon share one macOS kernel). Every other platform -is `Unsupported`. +checks, without opening or creating anything, that the Store's own directory +exists as a real `0700` directory owned by the current effective user (refusing +a missing path, a symlink, wrong owner or `mode & 0o077 != 0` without modifying +directory permissions), and allows ext4, xfs and btrfs on Linux and apfs or hfs +on macOS (for the native Sandbox, where the SDK and daemon share one macOS +kernel). Every other platform is `Unsupported`. ```text StoreService::bind(workspace, branch) Store::bind_private diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index b005f6f475..6c009e0bc8 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -485,7 +485,8 @@ layerfs doctor --text # a count line, then each finding and its fix out of date and refuses nothing. Each finding's `fix` names the call (or the by-hand step, where no call can) that fixes it. - It checks: records that do not parse, or whose `"v"` is not 1; folder - modes other than 0700 (0701 where a namespaces Sandbox passes through) and + modes other than 0700 (0701 where a namespaces Sandbox passes through, but + never a Store's own folder, which stays 0700) and record modes other than 0600; broken references (a Sandbox whose Store, project or machine is gone, a Store on a machine with no record, a project in a Store folder with no record, a built-in machine whose recorded daemon is not there, an error diff --git a/docs/versioned/2.0.0/machines-and-stores.md b/docs/versioned/2.0.0/machines-and-stores.md index 6413ac26b5..0d604293bc 100644 --- a/docs/versioned/2.0.0/machines-and-stores.md +++ b/docs/versioned/2.0.0/machines-and-stores.md @@ -20,7 +20,7 @@ the [contract](../../architecture/control/support-matrix/disabled-platforms.md). | Kind | How many | Made by | Sandboxes run as | Tool | | --- | --- | --- | --- | --- | -| `native` | one, built in | — | macOS: host processes with a loopback NFS mount. Linux: namespaces (needs root). Windows: none; `native` holds only records (O5) | — | +| `native` | one, built in | — | macOS: host processes with a loopback NFS mount (each sqlite Store's directory must be owned by this user and private, mode `0700`). Linux: namespaces (needs root). Windows: none; `native` holds only records (O5) | — | | `docker` | one, built in | — | namespaces inside its worker container (D-8), rooted in the bundle's Sandbox image. The image `machine update docker --image` records, else the bundle's Sandbox image loaded into Docker once (#535 P5), is the worker container's; see Routes | `docker` | | `apple-container` | many | `machine create` | namespaces inside the VM | `container` | | `lima` | many | `machine create` | namespaces inside the VM | `limactl` | diff --git a/engine/crates/layerfs-daemon/src/application/config.rs b/engine/crates/layerfs-daemon/src/application/config.rs index 1e556f81b4..95caad8bf8 100644 --- a/engine/crates/layerfs-daemon/src/application/config.rs +++ b/engine/crates/layerfs-daemon/src/application/config.rs @@ -106,11 +106,36 @@ fn private_directory(path: &Path, create: bool) -> io::Result<()> { .custom_flags((OFlag::O_NOFOLLOW | OFlag::O_DIRECTORY | OFlag::O_CLOEXEC).bits()) .open(path)?; let metadata = directory.metadata()?; - if !metadata.is_dir() - || metadata.uid() != Uid::effective().as_raw() - || metadata.mode() & 0o077 != 0 - { - return Err(invalid("private directory ownership/mode/type")); + let uid = Uid::effective().as_raw(); + let mode = metadata.mode() & 0o7777; + if !metadata.is_dir() { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + format!( + "private directory ownership/mode/type at {}: not a directory (mode {mode:04o})", + path.display() + ), + )); + } + if metadata.uid() != uid { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + format!( + "private directory ownership/mode/type at {}: owned by uid {}, expected uid {uid}", + path.display(), + metadata.uid() + ), + )); + } + if mode & 0o077 != 0 { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + format!( + "private directory ownership/mode/type at {}: mode is {mode:04o}, expected 0700 (fix with: chmod 700 {})", + path.display(), + path.display() + ), + )); } Ok(()) } diff --git a/engine/crates/layerfs-store-service/Cargo.toml b/engine/crates/layerfs-store-service/Cargo.toml index c35603f928..0647dc6f0b 100644 --- a/engine/crates/layerfs-store-service/Cargo.toml +++ b/engine/crates/layerfs-store-service/Cargo.toml @@ -20,7 +20,7 @@ layerfs-history = { path = "../../../core/crates/layerfs-history" } layerfs-telemetry = { path = "../../../core/crates/layerfs-telemetry" } # Concrete Store opening (bootstrap) and the kernel guard's open. layerfs-persistence = { path = "../layerfs-persistence" } -nix = { version = "=0.31.3", default-features = false, features = ["fs"] } +nix = { version = "=0.31.3", default-features = false, features = ["fs", "user"] } # Only the `postgresql` feature's tests use it directly (schema cleanup). postgres = { version = "=0.19.14", optional = true } diff --git a/engine/crates/layerfs-store-service/src/install.rs b/engine/crates/layerfs-store-service/src/install.rs index 2b7692f459..2da08660ca 100644 --- a/engine/crates/layerfs-store-service/src/install.rs +++ b/engine/crates/layerfs-store-service/src/install.rs @@ -138,10 +138,11 @@ impl std::fmt::Display for LocalInstallFailure { /// Installs the sealed Store `source` (described by `manifest`) at /// `destination` in this process: the project volume's -/// `global/store.sqlite`, its `global/` directory made owner-only. The -/// destination's filesystem must pass the kernel guard, as every Store opener -/// must, and this process must run as the daemons' user. Returns the -/// installed manifest, which records this process's SQLite version. +/// `global/store.sqlite`, its `global/` directory made owner-only (`0700`, +/// created as such when missing). The destination's directory and filesystem +/// must pass the kernel guard, as every Store opener must, and this process +/// must run as the daemons' user. Returns the installed manifest, which +/// records this process's SQLite version. pub fn install_local( source: &Path, manifest: &StoreManifest, @@ -159,15 +160,24 @@ pub fn install_local( let directory = destination .parent() .ok_or("the Store destination has no directory")?; - crate::kernel_guard::check(directory).map_err(|reason| reason.0)?; - installer_user()?; let text = |error: io::Error| error.to_string(); - if !directory.exists() { - use std::os::unix::fs::DirBuilderExt; - fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .map_err(text)?; + let existed = directory.exists(); + let outcome = (|| { + installer_user()?; + if !existed { + use std::os::unix::fs::DirBuilderExt; + fs::DirBuilder::new() + .mode(0o700) + .create(directory) + .map_err(text)?; + } + crate::kernel_guard::check(destination).map_err(|reason| reason.0) + })(); + if let Err(error) = outcome { + if !existed { + let _ = fs::remove_dir_all(directory); + } + return Err(error); } let (target, temporary) = paths(destination).map_err(text)?; let mut file = claim(&target, &temporary).map_err(text)?; diff --git a/engine/crates/layerfs-store-service/src/kernel_guard.rs b/engine/crates/layerfs-store-service/src/kernel_guard.rs index e0e3945972..1be6339d48 100644 --- a/engine/crates/layerfs-store-service/src/kernel_guard.rs +++ b/engine/crates/layerfs-store-service/src/kernel_guard.rs @@ -4,9 +4,10 @@ //! filesystem that holds it: SQLite's WAL locks and the writers' admission //! lane (a `flock` on the Store's directory) coordinate only within one //! kernel. The guard checks what this process can verify before it opens any -//! file: the platform, and the type of the filesystem holding the Store's -//! directory, from an allowlist of local filesystems. Anything else is -//! `Unsupported` with its reason; there is no other route to fall back to. +//! file: the platform, the Store's own directory (a real `0700` directory +//! owned by this user) and the type of the filesystem holding it, from an +//! allowlist of local filesystems. Anything else is `Unsupported` with its +//! reason; there is no other route to fall back to. use std::path::Path; /// Filesystems that carry the Store's locks: ext4, xfs and btrfs. @@ -27,8 +28,54 @@ impl std::fmt::Display for Unsupported { } } -/// Checks the platform and the filesystem holding `store`'s directory, -/// before anything is opened. Returns the filesystem's name. +/// Checks that `directory` satisfies the daemon's private-directory +/// requirements: an existing real directory (not a symlink) owned by the +/// current effective user with no group/other access (`mode & 0o077 == 0`). +/// Side-effect-free: never creates a directory or modifies permissions. +#[cfg(any(target_os = "linux", target_os = "macos"))] +fn check_private_directory(directory: &Path) -> Result<(), Unsupported> { + use std::fs; + use std::os::unix::fs::MetadataExt; + let euid = nix::unistd::geteuid().as_raw(); + let meta = fs::symlink_metadata(directory).map_err(|error| { + Unsupported(format!( + "the Store's directory {} cannot be examined: {error}", + directory.display() + )) + })?; + let path = directory.display(); + if meta.file_type().is_symlink() { + return Err(Unsupported(format!( + "the Store's directory {path} is a symlink; a real private directory (mode 0700) is required" + ))); + } + if !meta.is_dir() { + return Err(Unsupported(format!( + "the Store's directory {path} is not a directory (mode {:04o}); a private directory (mode 0700) is required", + meta.mode() & 0o7777 + ))); + } + if meta.uid() != euid { + return Err(Unsupported(format!( + "the Store's directory {path} is owned by uid {}, not the current user (uid {euid}); \ + the daemon requires a private directory owned by uid {euid} (mode 0700)", + meta.uid() + ))); + } + let mode = meta.mode() & 0o7777; + if mode & 0o077 != 0 { + return Err(Unsupported(format!( + "the Store's directory {path} has mode {mode:04o} (group/other bits {:04o} are set); \ + the daemon requires a private directory (mode 0700, no group/other access); \ + fix with: chmod 700 {path}", + mode & 0o077 + ))); + } + Ok(()) +} + +/// Checks the platform, `store`'s own private directory and the filesystem +/// holding it, before anything is opened. Returns the filesystem's name. pub fn check(store: &Path) -> Result<&'static str, Unsupported> { #[cfg(target_os = "linux")] { @@ -36,6 +83,7 @@ pub fn check(store: &Path) -> Result<&'static str, Unsupported> { .parent() .filter(|parent| !parent.as_os_str().is_empty()) .unwrap_or_else(|| Path::new(".")); + check_private_directory(directory)?; let stat = nix::sys::statfs::statfs(directory).map_err(|error| { Unsupported(format!( "the Store's directory {} cannot be examined: {error}", @@ -65,6 +113,7 @@ pub fn check(store: &Path) -> Result<&'static str, Unsupported> { .parent() .filter(|parent| !parent.as_os_str().is_empty()) .unwrap_or_else(|| Path::new(".")); + check_private_directory(directory)?; let stat = nix::sys::statfs::statfs(directory).map_err(|error| { Unsupported(format!( "the Store's directory {} cannot be examined: {error}", diff --git a/engine/crates/layerfs-store-service/tests/kernel_guard.rs b/engine/crates/layerfs-store-service/tests/kernel_guard.rs index e99d46ea85..ab17acbba4 100644 --- a/engine/crates/layerfs-store-service/tests/kernel_guard.rs +++ b/engine/crates/layerfs-store-service/tests/kernel_guard.rs @@ -3,7 +3,6 @@ //! a filesystem outside the allowlist (here tmpfs). The refusal comes before //! any file is opened: the Store file's bytes are unchanged and no overlay //! template is created. On macOS a local apfs or hfs directory is allowed. -#[cfg(not(target_os = "macos"))] use layerfs_store_service::{OpenRefusal, StoreService}; use std::path::{Path, PathBuf}; @@ -27,11 +26,82 @@ fn refused(directory: &Path) -> (String, Vec, Vec) { } fn scratch(parent: &Path, label: &str) -> PathBuf { + use std::os::unix::fs::DirBuilderExt; let directory = parent.join(format!("layerfs-guard-{label}-{}", std::process::id())); - std::fs::create_dir_all(&directory).unwrap(); + let _ = std::fs::remove_dir_all(&directory); + std::fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(&directory) + .unwrap(); directory } +#[cfg(any(target_os = "linux", target_os = "macos"))] +#[test] +fn missing_store_directory_is_refused_without_creating_it_and_non_private_directory_is_refused() { + use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; + let parent = scratch(&std::env::temp_dir(), "private-mode"); + let missing = parent.join("global"); + assert!(!missing.exists()); + let refused_missing = layerfs_store_service::kernel_guard::check(&missing.join("store.sqlite")) + .expect_err("missing directory must be refused without creating it"); + assert!( + refused_missing.0.contains(&missing.display().to_string()), + "{refused_missing}" + ); + assert!( + !missing.exists(), + "kernel_guard::check must not create a missing directory" + ); + let template = parent.join("overlay.sqlite"); + let open_missing = StoreService::open_direct( + &missing.join("store.sqlite"), + b"binding", + [7; 32], + &template, + ); + match open_missing { + Err(OpenRefusal::Unsupported(_)) => {} + Err(other) => panic!("expected OpenRefusal::Unsupported, got {other:?}"), + Ok(_) => panic!("expected OpenRefusal::Unsupported, Store opened"), + } + assert!( + !missing.exists(), + "open_direct on a missing Store directory must not leave an empty directory" + ); + + // An existing 0700 directory passes, even for a non-.sqlite filename. + std::fs::DirBuilder::new() + .mode(0o700) + .create(&missing) + .unwrap(); + let checked = layerfs_store_service::kernel_guard::check(&missing.join("db")); + assert!(checked.is_ok(), "{checked:?}"); + + // An existing directory with group/other access (e.g. 0755 from default + // umask) is refused up front with its path, current mode, expected 0700 + // and chmod command, without modifying the user's directory permissions. + std::fs::set_permissions(&missing, std::fs::Permissions::from_mode(0o755)).unwrap(); + let refused = layerfs_store_service::kernel_guard::check(&missing.join("store.sqlite")) + .expect_err("0755 directory must be refused"); + assert!( + refused.0.contains(&missing.display().to_string()), + "{refused}" + ); + assert!(refused.0.contains("0755"), "{refused}"); + assert!(refused.0.contains("0700"), "{refused}"); + assert!( + refused + .0 + .contains(&format!("chmod 700 {}", missing.display())), + "{refused}" + ); + let unchanged = std::fs::metadata(&missing).unwrap().permissions().mode() & 0o7777; + assert_eq!(unchanged, 0o755); + std::fs::remove_dir_all(parent).unwrap(); +} + #[cfg(target_os = "macos")] #[test] fn direct_access_is_allowed_on_a_local_macos_filesystem() { From a80592cae7abb0c1404171e21897a7e3ad3b3acc Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 03:14:32 +0000 Subject: [PATCH 02/11] fix(sandbox): pass the caller's Rust and Git locations to native macOS commands (#570 port) Ported from #570 (cc1edadad with the macOS gate of 6be2f6c31), which was closed as ported into #647 but never reached layerfs_v2_0_0. A native macOS Sandbox runs its commands with `HOME` set to the Sandbox's own scratch folder, so a command there saw no toolchain and no Git identity. On macOS, a `HostProcess` command now receives `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` from the caller's environment, or from the caller's real `HOME` (`~/.rustup`, `~/.cargo`, `~/.gitconfig`, else `$XDG_CONFIG_HOME/git/config` or `~/.config/git/config`) when that path exists. They are applied before `request.environment`, so an explicit request value or a command's own override wins, and `HOME` itself stays the Sandbox's scratch folder. Off macOS `user_environment()` answers empty, so the Linux and namespaces backends' command environments are unchanged; the header comment and the `Environment` row in the connect guide say so. Test: `local_search_path::a_native_command_receives_existing_user_toolchain_and_git_locations` covers absent paths, the XDG default, `XDG_CONFIG_HOME/git/config`, `~/.rustup` plus `~/.cargo` plus `~/.gitconfig` (chosen ahead of XDG), caller environment overrides and request environment overrides, with `HOME` remaining the Sandbox's scratch folder. `fixture()` names each run's directory so the two tests in that binary no longer collide, and both take one environment lock. Production LOC: 158376 -> 158412 (delta +36) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py --detail` on the exact parent fad03b50c and this tree. control 39002 -> 39038 (+36, `layerfs-sandbox-backend` 5789 -> 5825); engine 74027, core 39787 and api 5560 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: none. --- .../src/backend/host_process/exec.rs | 53 ++++- .../tests/local_search_path.rs | 183 +++++++++++++++++- docs/architecture/api/sdk/workspace/exec.md | 2 +- .../control/sandboxes/commands-and-streams.md | 2 +- 4 files changed, 227 insertions(+), 13 deletions(-) diff --git a/control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs b/control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs index 32c7cc807f..2dc0c87fe0 100644 --- a/control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs +++ b/control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs @@ -1,9 +1,10 @@ //! One ordinary command to its end in a local Sandbox: the command identity, -//! the Workspace directory and a search path (on macOS this process's own); -//! nothing else of this process's environment, no shell of its own and no -//! implicit timeout. Each command leads a process group of its own, named in -//! the Sandbox until it is empty, so what it leaves running ends with the -//! Sandbox. +//! the Workspace directory, a search path (on macOS this process's own), and +//! (on macOS) the caller's Rust and Git locations (`RUSTUP_HOME`, +//! `CARGO_HOME`, `GIT_CONFIG_GLOBAL`) when present; nothing else of this +//! process's environment, no shell of its own and no implicit timeout. Each +//! command leads a process group of its own, named in the Sandbox until it is +//! empty, so what it leaves running ends with the Sandbox. use super::sandbox::Sandbox; use crate::local::streams; use crate::local::{groups, search::search_path}; @@ -12,6 +13,7 @@ use crate::{ExecExit, ExecRequest, RuntimeError, WireFailure}; use layerfs_bridge::process::{self, LocalProcess}; use nix::sys::signal::{killpg, Signal}; use std::{ + ffi::OsString, io::{self, Write}, os::unix::process::{CommandExt, ExitStatusExt}, path::Path, @@ -54,6 +56,7 @@ impl Sandbox { .args(&request.arguments[1..]) .env_clear() .env("PATH", search_path()) + .envs(user_environment()) .current_dir(Path::new(&request.directory)) // std drops supplementary groups (setgroups 0) when it sets a uid as root .uid(request.identity.uid) @@ -155,3 +158,43 @@ fn check(request: &ExecRequest) -> Result<(), RuntimeError> { } Ok(()) } + +/// The caller's Rust and Git locations on macOS, when present, so a command +/// whose `HOME` is the Sandbox's scratch directory still sees them unless the +/// caller's environment or the request sets its own. +#[cfg(target_os = "macos")] +fn user_environment() -> Vec<(&'static str, OsString)> { + use std::path::PathBuf; + let home = non_empty_env("HOME").map(PathBuf::from); + let existing = |path: PathBuf| path.exists().then(|| path.into_os_string()); + let mut vars = Vec::new(); + for (name, subdir) in [("RUSTUP_HOME", ".rustup"), ("CARGO_HOME", ".cargo")] { + let value = + non_empty_env(name).or_else(|| home.as_ref().and_then(|h| existing(h.join(subdir)))); + if let Some(value) = value { + vars.push((name, value)); + } + } + let git_config = non_empty_env("GIT_CONFIG_GLOBAL") + .or_else(|| home.as_ref().and_then(|h| existing(h.join(".gitconfig")))) + .or_else(|| { + let xdg = non_empty_env("XDG_CONFIG_HOME") + .map(PathBuf::from) + .or_else(|| home.as_ref().map(|h| h.join(".config")))?; + existing(xdg.join("git").join("config")) + }); + if let Some(value) = git_config { + vars.push(("GIT_CONFIG_GLOBAL", value)); + } + vars +} + +#[cfg(not(target_os = "macos"))] +fn user_environment() -> Vec<(&'static str, OsString)> { + Vec::new() +} + +#[cfg(target_os = "macos")] +fn non_empty_env(name: &str) -> Option { + std::env::var_os(name).filter(|value| !value.is_empty()) +} diff --git a/control/crates/layerfs-sandbox-backend/tests/local_search_path.rs b/control/crates/layerfs-sandbox-backend/tests/local_search_path.rs index 2296effb2c..a287f973cf 100644 --- a/control/crates/layerfs-sandbox-backend/tests/local_search_path.rs +++ b/control/crates/layerfs-sandbox-backend/tests/local_search_path.rs @@ -2,17 +2,26 @@ //! process's own PATH, so this user's tools (`node` in `~/.local/bin`, //! Homebrew's `/opt/homebrew/bin`) are found as in the caller's shell; with //! no PATH, or an empty one, a container's search path and Homebrew's. -//! A small shell script stands in for the daemon. One test: it changes this -//! process's PATH, which no other test in this binary reads. +//! Commands also receive `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` +//! from the caller's environment or real `HOME` when present, while `HOME` +//! stays the Sandbox's scratch directory. A small shell script stands in for +//! the daemon. #![cfg(target_os = "macos")] use layerfs_sandbox_backend::{host_process::Sandbox, local::Local, CommandIdentity, ExecRequest}; use std::{ + ffi::OsString, fs, os::unix::fs::PermissionsExt, path::{Path, PathBuf}, + sync::{ + atomic::{AtomicUsize, Ordering}, + Mutex, + }, time::Duration, }; +static ENV_LOCK: Mutex<()> = Mutex::new(()); +static NEXT: AtomicUsize = AtomicUsize::new(0); const WAIT: Duration = Duration::from_secs(10); const FALLBACK: &str = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/homebrew/bin"; @@ -20,10 +29,11 @@ const FALLBACK: &str = /// A fresh 0755 runtime root and a stand-in daemon that prints its /// environment, then its listener line, then waits. fn fixture() -> (PathBuf, PathBuf) { - let base = std::env::temp_dir() - .canonicalize() - .unwrap() - .join(format!("layerfs-search-path-{}", std::process::id())); + let base = std::env::temp_dir().canonicalize().unwrap().join(format!( + "layerfs-search-path-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); let _ = fs::remove_dir_all(&base); fs::create_dir_all(base.join("root")).unwrap(); fs::set_permissions(&base, fs::Permissions::from_mode(0o755)).unwrap(); @@ -76,6 +86,7 @@ fn command_path(sandbox: &Sandbox, environment: &[&str]) -> String { #[test] fn a_native_daemon_and_its_commands_start_with_this_processs_path() { + let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner()); let (root, daemon) = fixture(); let own = "/Users/someone/.local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"; let saved = std::env::var_os("PATH"); @@ -105,3 +116,163 @@ fn a_native_daemon_and_its_commands_start_with_this_processs_path() { } let _ = fs::remove_dir_all(root.parent().unwrap()); } + +/// A command's output for `script`, `printf` by its absolute path, so a +/// lookup is not needed. +fn command_script(sandbox: &Sandbox, script: &str, environment: &[&str]) -> String { + let request = ExecRequest { + identity: CommandIdentity { + uid: nix::unistd::Uid::effective().as_raw(), + gid: nix::unistd::Gid::effective().as_raw(), + }, + arguments: vec!["/bin/sh".into(), "-c".into(), script.into()], + environment: environment.iter().map(|e| e.to_string()).collect(), + directory: sandbox.directory().display().to_string(), + stdin: false, + }; + let (mut out, mut err) = (Vec::new(), Vec::new()); + let exit = sandbox.run(&request, &mut out, &mut err).unwrap(); + assert_eq!(exit.code, 0, "{}", String::from_utf8_lossy(&err)); + String::from_utf8(out).unwrap() +} + +struct SavedEnv(Vec<(&'static str, Option)>); + +impl SavedEnv { + fn capture(names: &[&'static str]) -> Self { + Self( + names + .iter() + .map(|&name| (name, std::env::var_os(name))) + .collect(), + ) + } +} + +impl Drop for SavedEnv { + fn drop(&mut self) { + for (name, value) in &self.0 { + match value { + Some(v) => std::env::set_var(name, v), + None => std::env::remove_var(name), + } + } + } +} + +#[test] +fn a_native_command_receives_existing_user_toolchain_and_git_locations() { + let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner()); + let _saved = SavedEnv::capture(&[ + "HOME", + "RUSTUP_HOME", + "CARGO_HOME", + "GIT_CONFIG_GLOBAL", + "XDG_CONFIG_HOME", + ]); + let (root, daemon) = fixture(); + let base = root.parent().unwrap(); + let user_home = base.join("user-home"); + fs::create_dir_all(&user_home).unwrap(); + for name in [ + "RUSTUP_HOME", + "CARGO_HOME", + "GIT_CONFIG_GLOBAL", + "XDG_CONFIG_HOME", + ] { + std::env::remove_var(name); + } + std::env::set_var("HOME", &user_home); + + let mut sandbox = started(&root, &daemon, "layerfs-user-env-1"); + let scratch_home = format!("HOME={}", sandbox.tmp().display()); + let probe = + "printf '%s|%s|%s|%s' \"$HOME\" \"${RUSTUP_HOME:-unset}\" \"${CARGO_HOME:-unset}\" \"${GIT_CONFIG_GLOBAL:-unset}\""; + + // absent under HOME: none of the three is set, and HOME stays the Sandbox's tmp + assert_eq!( + command_script(&sandbox, probe, &[&scratch_home]), + format!("{}|unset|unset|unset", sandbox.tmp().display()) + ); + + // XDG git config under ~/.config/git/config when ~/.gitconfig is absent + let xdg_default = user_home.join(".config/git/config"); + fs::create_dir_all(xdg_default.parent().unwrap()).unwrap(); + fs::write(&xdg_default, "[user]\n\tname = XdgUser\n").unwrap(); + assert_eq!( + command_script(&sandbox, probe, &[&scratch_home]), + format!( + "{}|unset|unset|{}", + sandbox.tmp().display(), + xdg_default.display() + ) + ); + + // XDG_CONFIG_HOME/git/config when XDG_CONFIG_HOME is set + let custom_xdg = base.join("xdg-config"); + let custom_xdg_git = custom_xdg.join("git/config"); + fs::create_dir_all(custom_xdg_git.parent().unwrap()).unwrap(); + fs::write(&custom_xdg_git, "[user]\n\tname = CustomXdg\n").unwrap(); + std::env::set_var("XDG_CONFIG_HOME", &custom_xdg); + assert_eq!( + command_script(&sandbox, probe, &[&scratch_home]), + format!( + "{}|unset|unset|{}", + sandbox.tmp().display(), + custom_xdg_git.display() + ) + ); + + // ~/.rustup, ~/.cargo and ~/.gitconfig present: all three passed through, + // with ~/.gitconfig chosen ahead of XDG, while HOME remains the Sandbox's tmp + let rustup = user_home.join(".rustup"); + let cargo = user_home.join(".cargo"); + let gitconfig = user_home.join(".gitconfig"); + fs::create_dir(&rustup).unwrap(); + fs::create_dir(&cargo).unwrap(); + fs::write(&gitconfig, "[user]\n\tname = HomeUser\n").unwrap(); + assert_eq!( + command_script(&sandbox, probe, &[&scratch_home]), + format!( + "{}|{}|{}|{}", + sandbox.tmp().display(), + rustup.display(), + cargo.display(), + gitconfig.display() + ) + ); + + // caller environment variables take precedence over HOME defaults + std::env::set_var("RUSTUP_HOME", "/custom/env/rustup"); + std::env::set_var("CARGO_HOME", "/custom/env/cargo"); + std::env::set_var("GIT_CONFIG_GLOBAL", "/custom/env/gitconfig"); + assert_eq!( + command_script(&sandbox, probe, &[&scratch_home]), + format!( + "{}|/custom/env/rustup|/custom/env/cargo|/custom/env/gitconfig", + sandbox.tmp().display() + ) + ); + + // explicit request environment entries take precedence over both + assert_eq!( + command_script( + &sandbox, + probe, + &[ + &scratch_home, + "RUSTUP_HOME=/req/rustup", + "CARGO_HOME=/req/cargo", + "GIT_CONFIG_GLOBAL=/req/gitconfig", + ] + ), + format!( + "{}|/req/rustup|/req/cargo|/req/gitconfig", + sandbox.tmp().display() + ) + ); + + sandbox.stop(1).unwrap(); + sandbox.delete().unwrap(); + let _ = fs::remove_dir_all(base); +} diff --git a/docs/architecture/api/sdk/workspace/exec.md b/docs/architecture/api/sdk/workspace/exec.md index cd9b974856..534730e86e 100644 --- a/docs/architecture/api/sdk/workspace/exec.md +++ b/docs/architecture/api/sdk/workspace/exec.md @@ -40,7 +40,7 @@ layerfs workspace exec [--stream] [--message TEXT] [--exec-id ID] | Name | Kind | Rule | Source | | --- | --- | --- | --- | | `ws` | Text | `:` or `:` from [workspace.mount](mount.md) | [`names.rs`](../../../../../control/crates/layerfs-home/src/names.rs) `WorkspaceRef` | -| `command` | Text | run as `bash -c ` as the Sandbox's command identity, `HOME` its scratch folder, in the Workspace directory | [`exec/run.rs`](../../../../../control/crates/layerfs-sandbox/src/exec/run.rs) | +| `command` | Text | run as `bash -c ` as the Sandbox's command identity, `HOME` its scratch folder (on macOS `native`, `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` default to the caller's when present; override in the caller's environment or the command), in the Workspace directory | [`exec/run.rs`](../../../../../control/crates/layerfs-sandbox/src/exec/run.rs) | ## Options diff --git a/docs/architecture/control/sandboxes/commands-and-streams.md b/docs/architecture/control/sandboxes/commands-and-streams.md index 07a15f7945..8a5b981ccd 100644 --- a/docs/architecture/control/sandboxes/commands-and-streams.md +++ b/docs/architecture/control/sandboxes/commands-and-streams.md @@ -38,7 +38,7 @@ the Workspace through ordinary file calls on the mount. | --- | --- | --- | | Identity | uid and gid non-zero, else `Protocol("nonroot command uid/gid")`. | [`types/execution.rs`](../../../../control/crates/layerfs-sandbox-backend/src/types/execution.rs) | | Arguments | At least one, first non-empty, no NUL. No shell is added by the runtime; `bash -c` comes from the API. | [`types/request.rs`](../../../../control/crates/layerfs-sandbox-backend/src/types/request.rs) | -| Environment | `NAME=value`, not starting with `=`, no NUL. Nothing else of the runtime's environment reaches the command but `PATH`. | same; [`host_process/exec.rs`](../../../../control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs) | +| Environment | `NAME=value`, not starting with `=`, no NUL. Nothing else of the runtime's environment reaches the command but `PATH`, and on `HostProcess` on macOS `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` from the caller's environment or `HOME` (`~/.rustup`, `~/.cargo`, `~/.gitconfig` or XDG `git/config`) when present and not overridden by `request.environment`. | same; [`host_process/exec.rs`](../../../../control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs) | | Directory | Absolute, no NUL. | same | | Stdin | Both backends refuse it (`Unsupported`). | [`host_process/exec.rs`](../../../../control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs) | | Timeout | None. A command runs until it ends. | each `exec.rs` | From 64149ba6f1fd2302ebbf948a452ee51e3ceb24d5 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 03:41:20 +0000 Subject: [PATCH 03/11] docs(backup,sdk): follow the Store folder's 0700 rule in restore and remove (#570 port) `fad03b50c` changed the order backup restore uses and made the kernel guard check the Store's own directory, but two guides still described the old behaviour. - Backup and restore, step 1: `fetch` takes the remote object, then requires the daemons' user (`installer_user`), then creates the destination's directory `0700` when it is absent, then runs the kernel guard on the Store file; a refusal removes only a directory this call made. The flow line and row 1 of the check table now say that, instead of "kernel_guard on the directory; installer_user". - `project.remove`'s `Unsupported` row: the guard refuses the Store's own directory, not only its filesystem, so a missing, symlinked, another owner's or group/other-accessible directory (mode `0700` required) refuses the call too, in the words of `store/create.md` and `project/init.md`. `remove_project` opens the Store through `service::with_service` -> `StoreService::open_direct`, where the guard runs. Checked against the source at `fad03b50c`: `bucket/src/backup/restore.rs` `fetch`, `store-service/src/install.rs` `install_local` (the same order), `store-service/src/kernel_guard.rs` `check`, `store-store/src/project/remove.rs`, `service.rs` `open` and `store_service.rs` `open_direct`. Documentation only: no build, test or measurement was run. Production LOC: 158412 -> 158412 (delta 0) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py --detail` on this tree; its only changes are two Markdown files, so the total is the parent a80592cae's. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: none. --- docs/architecture/api/sdk/project/remove.md | 2 +- docs/architecture/control/backups/backup-and-restore.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/architecture/api/sdk/project/remove.md b/docs/architecture/api/sdk/project/remove.md index 54d7538959..0e89af1cb8 100644 --- a/docs/architecture/api/sdk/project/remove.md +++ b/docs/architecture/api/sdk/project/remove.md @@ -96,7 +96,7 @@ other daemons and SDK processes keep reading meanwhile. See the | `NoSuchStore`, `NoSuchProject` | a record is missing; `NoSuchProject` also when the Store holds no LayerStack of that name | no | [`resolve.rs`](../../../../../control/crates/layerfs-store/src/resolve.rs), `store/identity.rs` | | `InUse` | a Sandbox of the project is recorded; `detail.related` lists each `{ kind: "sandbox", name }` | no | [`inventory.rs`](../../../../../control/crates/layerfs-control/src/inventory.rs) | | `Busy`, `Unresolved` | the Store's record holds another operation's intent | no | [`op.rs`](../../../../../control/crates/layerfs-home/src/op.rs) | -| `Unsupported` | a PostgreSQL Store; or the kernel guard refuses the Store's filesystem when the Store is opened | no | `project/family.rs`, [`service.rs`](../../../../../control/crates/layerfs-store/src/service.rs) | +| `Unsupported` | a PostgreSQL Store; or the kernel guard refuses the Store's directory when the Store is opened (non-private mode/owner/type — another user's directory or one with group/other access instead of `0700` — or unsupported filesystem) | no | `project/family.rs`, [`service.rs`](../../../../../control/crates/layerfs-store/src/service.rs) | | `Unavailable` | worker route: no worker recorded, or not reached | no | [`place.rs`](../../../../../control/crates/layerfs-store/src/place.rs) | | `Failed` | **the Store write failed, its outcome included**: `remove_layerstack` errors are all `Failed` | **may be** | `store/identity.rs` `remove_project` | | `Unknown` | **worker route: the answer was lost** | **yes** | [`worker/client.rs`](../../../../../control/crates/layerfs-machine/src/worker/client.rs) | diff --git a/docs/architecture/control/backups/backup-and-restore.md b/docs/architecture/control/backups/backup-and-restore.md index 2097c45c45..15505c6a9b 100644 --- a/docs/architecture/control/backups/backup-and-restore.md +++ b/docs/architecture/control/backups/backup-and-restore.md @@ -109,7 +109,9 @@ push never overwrites a file this home did not move. backup.restore(store, bucket, file?) api/…/backup/restore.rs existing Store? refuse PostgreSQL; replaceable? (lock; checked) backup::load(driver, file, store/.restore-/store.sqlite, cursor) - | 1 store_object(file); kernel_guard on the directory; installer_user + | 1 store_object(file); installer_user; make the directory 0700 when + | absent; kernel_guard on the Store file (a refusal removes the + | directory this call made) | 2 destination absent (load); no -wal/-shm beside it | 3 stat: present; binding from layerfs-binding (else refused) | 4 download to .pulling (0600, create_new): pieces::download @@ -126,7 +128,7 @@ push never overwrites a file this home did not move. | # | Check | Refusal | Source | | --- | --- | --- | --- | -| 1 | The destination's filesystem passes the Store kernel guard; the installer is the daemons' user. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | +| 1 | The installer is the daemons' user; the destination's directory is made `0700` when absent; the Store's file passes the kernel guard (a real `0700` directory of this user on a local filesystem), which refuses a missing, symlinked, another owner's or non-private directory. A refusal removes only a directory this call made. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | | 2 | Load: no Store at the target. Pull: no `-wal` or `-shm` beside it (no opener holds it). | "a Store exists"; "the local Store … is open" | same | | 3 | The remote file exists and records `layerfs-binding`; a pull's expected binding matches. | "records no layerfs-binding; push it again"; "has another binding" | same | | 4 | Manifest, every piece and the whole file match their sha256. | `Integrity` | [`bucket/pieces.rs`](../../../../control/crates/layerfs-bucket/src/bucket/pieces.rs) | From eb7a34f85179ca28d5f30ee3d820be4e1c164cfb Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 04:36:01 +0000 Subject: [PATCH 04/11] fix(store): claim a Store directory only when this call's mkdir made it (#570 P1) LP570-REVIEW P1-1: `install_local` and backup restore observed the directory absent before `mkdir` and used that observation as ownership, so a call that lost the creation race recursively removed the directory (and the Store) another call had made while it was away. `store.create` did the same from the observation it made before `make_empty`. - `install::prepare` (new; used by `install_local` and `backup::fetch`): the installer check, the `0700` directory when absent, then the kernel guard. The directory belongs to the call only once its own `mkdir` returned success. An installer-user or `mkdir` failure (including `AlreadyExists`, another caller's directory) deletes nothing, and the guard refusal -- which happens before any Store file exists -- reclaims only that own directory with a non-recursive `remove_dir`, so nothing another caller put there can be taken. `AlreadyExists` stays this call's failure: no continue, no retry. Failures after the guard keep their existing custody. - `backup::fetch` drops its copy of that block and calls the same `prepare`. - `identity::make_empty` hands back `MadeDirectory` (`ThisCall`/`AlreadyThere`) beside its result, and `sqlite::create` reclaims `store/` only for `ThisCall`, instead of the `existed` it saw before `make_empty`. Its own temporary file is still cleaned up; the home lock still serializes `store.create`, so its recursive cleanup of its own directory is unchanged. Tests: new `layerfs-store-service` target `install_directory`. (a) This call observes the directory absent, another caller creates it `0700` with its Store, this call's `mkdir` then fails, and nothing of the other caller's is removed; before the fix this test fails (the directory and its Store were removed). (b) A guard refusal after this call's own `mkdir` reclaims the empty directory it made and leaves both the volume and a directory it did not make, with its content. New `layerfs-store` target `create_directory`: a refused `store.create` reclaims only the empty `store/` its own `mkdir` made and leaves a pre-existing directory with its marker. The race is driven through `install::prepare_between`'s step, never a sleep. Docs: backup-and-restore step 1 and store/create -- the "only a directory this call made" rule now names the guard's non-recursive removal of the still-empty own directory and the mkdir-failure case that removes nothing. Production LOC: 158412 -> 158417 (delta +5) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py --detail` on the parent 64149ba6f (exported tree) and this tree: engine 74027 -> 74036 (+9, layerfs-store-service 14425 -> 14434), control 39038 -> 39034 (-4, layerfs-bucket 3797 -> 3776 (-21), layerfs-store 8573 -> 8590 (+17)); core 39787 and api 5560 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: none. --- .../layerfs-bucket/src/backup/restore.rs | 29 ++----- control/crates/layerfs-store/src/identity.rs | 32 ++++++- .../crates/layerfs-store/src/sqlite/create.rs | 9 +- .../layerfs-store/tests/create_directory.rs | 59 +++++++++++++ docs/architecture/api/sdk/store/create.md | 8 +- .../control/backups/backup-and-restore.md | 4 +- .../layerfs-store-service/src/install.rs | 71 ++++++++++----- .../tests/install_directory.rs | 86 +++++++++++++++++++ 8 files changed, 242 insertions(+), 56 deletions(-) create mode 100644 control/crates/layerfs-store/tests/create_directory.rs create mode 100644 engine/crates/layerfs-store-service/tests/install_directory.rs diff --git a/control/crates/layerfs-bucket/src/backup/restore.rs b/control/crates/layerfs-bucket/src/backup/restore.rs index 8dec25bbb6..b3943aff39 100644 --- a/control/crates/layerfs-bucket/src/backup/restore.rs +++ b/control/crates/layerfs-bucket/src/backup/restore.rs @@ -25,8 +25,7 @@ use crate::bucket::{progress, Driver}; use layerfs_persistence::{PersistenceConfig, SqlitePersistenceProfile}; use layerfs_storage::ReservationBlocks; use layerfs_store_service::bootstrap::open_store_observed; -use layerfs_store_service::install::{installer_user, paths}; -use layerfs_store_service::kernel_guard; +use layerfs_store_service::install::{paths, prepare}; use std::fs::{self, OpenOptions}; use std::io::{self, Write}; use std::path::{Path, PathBuf}; @@ -176,28 +175,10 @@ fn fetch( let result = (|| { let text = |error: io::Error| error.to_string(); let object = store_object(name)?; - let directory = destination - .parent() - .ok_or("the Store destination has no directory")?; - // as install_local: the volume holding the Store's directory - let existed = directory.exists(); - let outcome = (|| { - installer_user()?; - if !existed { - use std::os::unix::fs::DirBuilderExt; - fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .map_err(text)?; - } - kernel_guard::check(destination).map_err(|reason| reason.0) - })(); - if let Err(error) = outcome { - if !existed { - let _ = fs::remove_dir_all(directory); - } - return Err(error); - } + // as install_local: the Store's own directory (`0700` when absent), + // the Store file guarded; a refusal reclaims only an empty directory + // this call made + prepare(destination)?; let (target, _) = paths(destination).map_err(text)?; let cloning = binding.is_none(); if cloning && exists(&target).map_err(text)? { diff --git a/control/crates/layerfs-store/src/identity.rs b/control/crates/layerfs-store/src/identity.rs index fa9bdf55a4..3d4bb84e78 100644 --- a/control/crates/layerfs-store/src/identity.rs +++ b/control/crates/layerfs-store/src/identity.rs @@ -200,13 +200,41 @@ pub fn sqlite_only(identity: &Identity, what: &str) -> Result<()> { } } +/// Whether `make_empty`'s own `mkdir` made the Store's directory: the only +/// ownership that lets its caller reclaim the directory when nothing was +/// published. A directory another caller (or the user) made is never this +/// call's to remove. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum MadeDirectory { + /// This call's `mkdir` created it. + ThisCall, + /// It was already there. + AlreadyThere, +} + /// Creates and seals the empty Store at `.creating`, then -/// renames it into place; a failure removes this call's own file. +/// renames it into place; a failure removes this call's own temporary file. +/// Also says whether this call's own `mkdir` made `global`, which is the only +/// ownership that may reclaim the directory. pub fn make_empty( global: &Path, destination: &Path, identity: &Identity, policy: layerfs_storage::StoragePolicy, +) -> (Result, MadeDirectory) { + let mut made = MadeDirectory::AlreadyThere; + let result = create_empty(global, destination, identity, policy, &mut made); + (result, made) +} + +/// [`make_empty`]'s steps; `made` records whether this call's own `mkdir` +/// created `global`. +fn create_empty( + global: &Path, + destination: &Path, + identity: &Identity, + policy: layerfs_storage::StoragePolicy, + made: &mut MadeDirectory, ) -> Result { use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; if !global.exists() { @@ -214,6 +242,8 @@ pub fn make_empty( .mode(0o700) .create(global) .map_err(failed)?; + // the directory is this call's own only now that its mkdir succeeded + *made = MadeDirectory::ThisCall; } layerfs_store_service::kernel_guard::check(destination) .map_err(|reason| refused("Unsupported", reason.0))?; diff --git a/control/crates/layerfs-store/src/sqlite/create.rs b/control/crates/layerfs-store/src/sqlite/create.rs index ed4474b58f..1f83304f7a 100644 --- a/control/crates/layerfs-store/src/sqlite/create.rs +++ b/control/crates/layerfs-store/src/sqlite/create.rs @@ -14,7 +14,6 @@ pub fn create(home: &Path, name: &StoreName) -> Outcome { return Err(refused("Exists", format!("a Store named {name} exists"))); } let directory = paths::store_dir(home, name); - let existed = directory.exists(); if let Some(parent) = directory.parent() { home::private_dir(parent)?; } @@ -25,11 +24,13 @@ pub fn create(home: &Path, name: &StoreName) -> Outcome { }; let file = paths::store_file(home, name); let policy = layerfs_storage::StoragePolicy::frozen_default(); - let sealed = match crate::identity::make_empty(&directory, &file, &identity, policy) { + let (created, made) = crate::identity::make_empty(&directory, &file, &identity, policy); + let sealed = match created { Ok(sealed) => sealed, Err(refusal) => { - // nothing was published: this call's own directory goes - if !existed { + // nothing was published: the directory goes only when this call's + // own mkdir made it, never one another caller made meanwhile + if made == crate::identity::MadeDirectory::ThisCall { let _ = std::fs::remove_dir_all(&directory); } return Err(refusal); diff --git a/control/crates/layerfs-store/tests/create_directory.rs b/control/crates/layerfs-store/tests/create_directory.rs new file mode 100644 index 0000000000..17476f48a0 --- /dev/null +++ b/control/crates/layerfs-store/tests/create_directory.rs @@ -0,0 +1,59 @@ +//! `store.create`'s directory (#570 P1): `make_empty` hands back whether this +//! call's own `mkdir` made `store/`, and only that ownership may reclaim +//! the directory when nothing was published. The guard refuses tmpfs by +//! filesystem, after the `mkdir` succeeded, so it shows both sides. +use layerfs_home::home::paths; +use layerfs_home::names::StoreName; +use std::path::{Path, PathBuf}; + +fn scratch(parent: &Path, label: &str) -> PathBuf { + use std::os::unix::fs::DirBuilderExt; + let directory = parent.join(format!("layerfs-create-{label}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&directory); + std::fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(&directory) + .unwrap(); + directory +} + +#[cfg(target_os = "linux")] +#[test] +fn a_refused_create_removes_only_the_directory_this_call_made() { + use std::os::unix::fs::DirBuilderExt; + // a home on tmpfs: `make_empty`'s own `0700` mkdir succeeds and the kernel + // guard then refuses the filesystem + let home = scratch(Path::new("/dev/shm"), "tmpfs-home"); + layerfs_home::home::layout::create(&home).unwrap(); + let name = StoreName::parse("tmp").unwrap(); + let refusal = layerfs_store::sqlite::create::create(&home, &name).unwrap_err(); + assert_eq!(refusal.code, "Unsupported", "{}", refusal.message); + assert!( + refusal.message.contains("ext4, xfs or btrfs"), + "{}", + refusal.message + ); + let directory = paths::store_dir(&home, &name); + assert!( + !directory.exists(), + "the empty directory this call made is reclaimed" + ); + assert!( + paths::store_dir(&home, &name).parent().unwrap().is_dir(), + "store/ itself stays" + ); + + // a directory this call did not make, and what it holds, stay + std::fs::DirBuilder::new() + .mode(0o700) + .create(&directory) + .unwrap(); + let marker = directory.join("another callers file"); + std::fs::write(&marker, b"another caller's file").unwrap(); + let refusal = layerfs_store::sqlite::create::create(&home, &name).unwrap_err(); + assert_eq!(refusal.code, "Unsupported", "{}", refusal.message); + assert!(directory.is_dir(), "the other caller's directory stays"); + assert_eq!(std::fs::read(&marker).unwrap(), b"another caller's file"); + std::fs::remove_dir_all(home).unwrap(); +} diff --git a/docs/architecture/api/sdk/store/create.md b/docs/architecture/api/sdk/store/create.md index 7cfdc791c8..fe575f0870 100644 --- a/docs/architecture/api/sdk/store/create.md +++ b/docs/architecture/api/sdk/store/create.md @@ -85,7 +85,8 @@ shown. The answer is the same shape as [store.get](get.md). ProjectApi::create_store -> store.sqlite.creating (Disposable profile, frozen default policy) chmod 0600; rename -> store//store.sqlite - failure: remove store// (its own directory only; nothing was published) + failure: remove store// (its own directory only: one this + call's mkdir made, with nothing published) save_record + created_on_native; write record.json ``` @@ -108,8 +109,9 @@ create it and then [push](push.md) it. See the | `Unsupported` | the kernel guard refuses `store//` (not on a local lock-carrying filesystem, or an existing directory is not owned by this user or has group/other access instead of mode `0700`) | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs), [`kernel_guard.rs`](../../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | `Failed` | the empty Store could not be made or written (`Store create: …`), or the record write failed | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs) | -A failure before the record is written removes the call's own -`store//` folder. +A failure before the record is written removes the `store//` folder +only when this call's own `mkdir` made it; a folder that was already there +(or that another caller made meanwhile) is never removed. ## Examples diff --git a/docs/architecture/control/backups/backup-and-restore.md b/docs/architecture/control/backups/backup-and-restore.md index 15505c6a9b..b645149ec4 100644 --- a/docs/architecture/control/backups/backup-and-restore.md +++ b/docs/architecture/control/backups/backup-and-restore.md @@ -111,7 +111,7 @@ push never overwrites a file this home did not move. backup::load(driver, file, store/.restore-/store.sqlite, cursor) | 1 store_object(file); installer_user; make the directory 0700 when | absent; kernel_guard on the Store file (a refusal removes the - | directory this call made) + | still-empty directory this call's own mkdir made) | 2 destination absent (load); no -wal/-shm beside it | 3 stat: present; binding from layerfs-binding (else refused) | 4 download to .pulling (0600, create_new): pieces::download @@ -128,7 +128,7 @@ push never overwrites a file this home did not move. | # | Check | Refusal | Source | | --- | --- | --- | --- | -| 1 | The installer is the daemons' user; the destination's directory is made `0700` when absent; the Store's file passes the kernel guard (a real `0700` directory of this user on a local filesystem), which refuses a missing, symlinked, another owner's or non-private directory. A refusal removes only a directory this call made. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | +| 1 | The installer is the daemons' user; the destination's directory is made `0700` when absent; the Store's file passes the kernel guard (a real `0700` directory of this user on a local filesystem), which refuses a missing, symlinked, another owner's or non-private directory. A refusal removes only a directory this call made: the guard's refusal, which happens before any Store file exists, removes this call's own directory with a non-recursive `remove_dir` and only while it is still empty; an installer-user or `mkdir` failure (including `AlreadyExists`, another caller's directory) removes nothing. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | | 2 | Load: no Store at the target. Pull: no `-wal` or `-shm` beside it (no opener holds it). | "a Store exists"; "the local Store … is open" | same | | 3 | The remote file exists and records `layerfs-binding`; a pull's expected binding matches. | "records no layerfs-binding; push it again"; "has another binding" | same | | 4 | Manifest, every piece and the whole file match their sha256. | `Integrity` | [`bucket/pieces.rs`](../../../../control/crates/layerfs-bucket/src/bucket/pieces.rs) | diff --git a/engine/crates/layerfs-store-service/src/install.rs b/engine/crates/layerfs-store-service/src/install.rs index 2da08660ca..2c29b401de 100644 --- a/engine/crates/layerfs-store-service/src/install.rs +++ b/engine/crates/layerfs-store-service/src/install.rs @@ -5,7 +5,9 @@ //! initial Branch. The daemon does this for a Store streamed to it; Import //! does it in the SDK's process ([`install_local`]), so no Sandbox is started //! to install a Store. One attempt: a failure keeps whatever it left, named -//! in its report, and nothing is deleted or tried again. +//! in its report, and nothing is deleted or tried again, except that a guard +//! refusal before any Store file exists reclaims only the empty directory +//! that call's own `mkdir` made. use crate::bootstrap::{open_store_observed, OpenedStore}; use crate::store::{checked_base, PortError}; use layerfs_bridge::provision::{StoreManifest, StoreProfile}; @@ -136,6 +138,51 @@ impl std::fmt::Display for LocalInstallFailure { } } +/// Makes the Store's directory owner-only (`0700`, created as such when it is +/// absent), then checks the kernel guard for the Store file. A directory is +/// this call's own only when this call's `mkdir` returned success: an +/// installer-user or `mkdir` failure (`AlreadyExists`, when another caller +/// made the directory first, included) removes nothing, and a guard refusal — +/// which happens before any Store file exists — removes only that own +/// directory, non-recursively, so it cannot take another caller's Store. +pub fn prepare(destination: &Path) -> Result<(), String> { + installer_user()?; + prepare_between(destination, &|| {}) +} + +/// [`prepare`]'s directory and guard steps, without the installer check, with +/// `between` run after the directory's absence is observed and before this +/// call's `mkdir`. A regression test uses it to let another caller create the +/// same directory first (#570 P1); production passes no step of its own. +#[doc(hidden)] +pub fn prepare_between(destination: &Path, between: &dyn Fn()) -> Result<(), String> { + let directory = destination + .parent() + .ok_or("the Store destination has no directory")?; + let mut made = false; + if !directory.exists() { + between(); + use std::os::unix::fs::DirBuilderExt; + fs::DirBuilder::new() + .mode(0o700) + .create(directory) + .map_err(|error| error.to_string())?; + // the directory is this call's own only now that its mkdir succeeded + made = true; + } + match crate::kernel_guard::check(destination) { + Ok(_) => Ok(()), + Err(reason) => { + if made { + // no Store file exists yet: this call's own directory, and + // only while it still holds nothing + let _ = fs::remove_dir(directory); + } + Err(reason.0) + } + } +} + /// Installs the sealed Store `source` (described by `manifest`) at /// `destination` in this process: the project volume's /// `global/store.sqlite`, its `global/` directory made owner-only (`0700`, @@ -157,28 +204,8 @@ pub fn install_local( if manifest.profile != StoreProfile::Disposable || manifest.daemon_sqlite.is_some() { return Err("a sealed, not yet installed, Disposable Store is required".to_owned()); } - let directory = destination - .parent() - .ok_or("the Store destination has no directory")?; let text = |error: io::Error| error.to_string(); - let existed = directory.exists(); - let outcome = (|| { - installer_user()?; - if !existed { - use std::os::unix::fs::DirBuilderExt; - fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .map_err(text)?; - } - crate::kernel_guard::check(destination).map_err(|reason| reason.0) - })(); - if let Err(error) = outcome { - if !existed { - let _ = fs::remove_dir_all(directory); - } - return Err(error); - } + prepare(destination)?; let (target, temporary) = paths(destination).map_err(text)?; let mut file = claim(&target, &temporary).map_err(text)?; left.temporary = Some(temporary.clone()); diff --git a/engine/crates/layerfs-store-service/tests/install_directory.rs b/engine/crates/layerfs-store-service/tests/install_directory.rs new file mode 100644 index 0000000000..7fd3af1909 --- /dev/null +++ b/engine/crates/layerfs-store-service/tests/install_directory.rs @@ -0,0 +1,86 @@ +//! The Store directory an install (`install_local`) or a backup restore +//! (`backup::fetch`) prepares before it writes anything (#570 P1). Both call +//! [`layerfs_store_service::install::prepare`]: the directory belongs to the +//! call only when that call's own `mkdir` returned success. A `mkdir` failure +//! claims nothing, and a guard refusal reclaims only that own, still-empty +//! directory, non-recursively. +use layerfs_store_service::install; +use std::path::{Path, PathBuf}; + +fn scratch(parent: &Path, label: &str) -> PathBuf { + use std::os::unix::fs::DirBuilderExt; + let directory = parent.join(format!("layerfs-install-{label}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&directory); + std::fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(&directory) + .unwrap(); + directory +} + +/// The race of #570 P1, without a sleep: this call observes the directory +/// absent, another caller creates it and installs its Store there, and this +/// call's `mkdir` then fails. Nothing of the other caller's may be removed. +#[test] +fn a_lost_creation_race_never_removes_the_other_callers_directory() { + use std::os::unix::fs::DirBuilderExt; + let parent = scratch(&std::env::temp_dir(), "lost-race"); + let directory = parent.join("global"); + let destination = directory.join("store.sqlite"); + // this call sees no directory yet ... + assert!(!directory.exists()); + // ... another caller makes the same directory `0700` and installs a Store + let other = |directory: &Path| { + std::fs::DirBuilder::new() + .mode(0o700) + .create(directory) + .unwrap(); + std::fs::write(directory.join("store.sqlite"), b"another caller's Store").unwrap(); + }; + // ... and this call's mkdir fails: it made nothing, so it removes nothing + let refused = install::prepare_between(&destination, &|| other(&directory)).unwrap_err(); + assert!(refused.contains("File exists"), "{refused}"); + assert!(directory.is_dir(), "the other caller's directory stays"); + assert_eq!( + std::fs::read(&destination).unwrap(), + b"another caller's Store", + "the other caller's Store stays" + ); + std::fs::remove_dir_all(parent).unwrap(); +} + +/// A guard refusal happens before any Store file exists: it reclaims the +/// empty directory this call's own `mkdir` made, and never one it did not +/// make. tmpfs refuses the guard by filesystem, after the `mkdir` succeeded. +#[cfg(target_os = "linux")] +#[test] +fn a_refused_guard_removes_only_the_empty_directory_this_call_made() { + use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; + let volume = scratch(Path::new("/dev/shm"), "tmpfs-volume"); + let directory = volume.join("global"); + let destination = directory.join("store.sqlite"); + let refused = install::prepare_between(&destination, &|| {}).unwrap_err(); + assert!(refused.contains("ext4, xfs or btrfs"), "{refused}"); + assert!( + !directory.exists(), + "the empty directory this call made is reclaimed" + ); + assert!(volume.is_dir(), "the volume itself is untouched"); + + // a directory this call did not make, and what it holds, stay + std::fs::DirBuilder::new() + .mode(0o700) + .create(&directory) + .unwrap(); + std::fs::write(&destination, b"another caller's Store").unwrap(); + std::fs::set_permissions(&destination, std::fs::Permissions::from_mode(0o600)).unwrap(); + let refused = install::prepare_between(&destination, &|| {}).unwrap_err(); + assert!(refused.contains("ext4, xfs or btrfs"), "{refused}"); + assert!(directory.is_dir(), "the other caller's directory stays"); + assert_eq!( + std::fs::read(&destination).unwrap(), + b"another caller's Store" + ); + std::fs::remove_dir_all(volume).unwrap(); +} From 16a0ba3cb2c7c5f02166415a21fff6406c9c8a19 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 05:03:14 +0000 Subject: [PATCH 05/11] fix(store): drop the install test seam from the shipped API (#570 P1 review) LP570-P1FIX-REVIEW P2-1: `install::prepare_between(destination, &dyn Fn())` was a `pub fn` whose callback only a regression test passed. `#[doc(hidden)]` hides it from rustdoc, not from callers: the integration test in another crate compiled and called it, so a test-only entry point and its injection point shipped in the product library, which `engine/AGENTS.md` forbids. - `install::prepare` keeps the directory and guard steps inline: the installer-user check, the `0700` directory when absent, then the kernel guard. The directory is this call's own only once its own `mkdir` returned success: an installer-user or `mkdir` failure (including `AlreadyExists`) removes nothing, and a guard refusal reclaims only that own, still-empty directory with a non-recursive `remove_dir`. No callback, hidden name, test feature, `cfg(test)` or included private source. - `installer_user` becomes private: `prepare` is its only caller. - `tests/install_directory.rs` drives the public `prepare` only. The lost-mkdir race cannot be built deterministically without the injection point, so that case is deleted; the fix is supported by source review and by the old-logic run recorded in LP570-P1FIX-REVIEW (exit 101, the other caller's directory removed). The two guard cases stay; `prepare` starts with the installer-user check, so away from the daemons' user (uid 0) they assert that this call refuses before touching the directory or the guard and so creates and removes nothing, and the guard branches themselves run as that user. The same guard and ownership rule run unprivileged in `layerfs-store`'s `create_directory` through `store.create`, which has no installer-user check. - `docs/architecture/api/sdk/store/create.md` (P3-1): the folder is reclaimed for a `make_empty` failure only; a `save_record` failure after `make_empty` succeeded keeps the Store file and the folder, as `sqlite/create.rs` does. Production LOC: 158417 -> 158412 (delta -5) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py --detail` on the parent eb7a34f85 (exported tree) and this tree: engine 74036 -> 74031 (-5, layerfs-store-service 14434 -> 14429); control 39034, core 39787 and api 5560 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: engine/crates/layerfs-store-service/tests/install_directory.rs `a_lost_creation_race_never_removes_the_other_callers_directory` (built only through the removed `prepare_between` seam; see above). --- docs/architecture/api/sdk/store/create.md | 7 +- .../layerfs-store-service/src/install.rs | 14 +-- .../tests/install_directory.rs | 88 ++++++++++--------- 3 files changed, 54 insertions(+), 55 deletions(-) diff --git a/docs/architecture/api/sdk/store/create.md b/docs/architecture/api/sdk/store/create.md index fe575f0870..89291c5c8c 100644 --- a/docs/architecture/api/sdk/store/create.md +++ b/docs/architecture/api/sdk/store/create.md @@ -109,9 +109,10 @@ create it and then [push](push.md) it. See the | `Unsupported` | the kernel guard refuses `store//` (not on a local lock-carrying filesystem, or an existing directory is not owned by this user or has group/other access instead of mode `0700`) | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs), [`kernel_guard.rs`](../../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | `Failed` | the empty Store could not be made or written (`Store create: …`), or the record write failed | no | [`identity.rs`](../../../../../control/crates/layerfs-store/src/identity.rs) | -A failure before the record is written removes the `store//` folder -only when this call's own `mkdir` made it; a folder that was already there -(or that another caller made meanwhile) is never removed. +A failure of `make_empty` removes the `store//` folder only when this +call's own `mkdir` made it; a folder that was already there (or that another +caller made meanwhile) is never removed. Once `make_empty` succeeded, a +failure of `save_record` keeps the Store file and the folder. ## Examples diff --git a/engine/crates/layerfs-store-service/src/install.rs b/engine/crates/layerfs-store-service/src/install.rs index 2c29b401de..0341a04fcd 100644 --- a/engine/crates/layerfs-store-service/src/install.rs +++ b/engine/crates/layerfs-store-service/src/install.rs @@ -147,21 +147,11 @@ impl std::fmt::Display for LocalInstallFailure { /// directory, non-recursively, so it cannot take another caller's Store. pub fn prepare(destination: &Path) -> Result<(), String> { installer_user()?; - prepare_between(destination, &|| {}) -} - -/// [`prepare`]'s directory and guard steps, without the installer check, with -/// `between` run after the directory's absence is observed and before this -/// call's `mkdir`. A regression test uses it to let another caller create the -/// same directory first (#570 P1); production passes no step of its own. -#[doc(hidden)] -pub fn prepare_between(destination: &Path, between: &dyn Fn()) -> Result<(), String> { let directory = destination .parent() .ok_or("the Store destination has no directory")?; let mut made = false; if !directory.exists() { - between(); use std::os::unix::fs::DirBuilderExt; fs::DirBuilder::new() .mode(0o700) @@ -244,12 +234,12 @@ pub fn install_local( /// installs its Store (there is no root daemon to match); the daemon's own /// check that it owns the Store file still holds. #[cfg(target_os = "macos")] -pub fn installer_user() -> Result<(), String> { +fn installer_user() -> Result<(), String> { Ok(()) } /// Refuses an installer that is not the daemons' user. #[cfg(not(target_os = "macos"))] -pub fn installer_user() -> Result<(), String> { +fn installer_user() -> Result<(), String> { use std::os::unix::fs::MetadataExt; // the owner of /proc/self is this process's effective user let uid = fs::metadata("/proc/self") diff --git a/engine/crates/layerfs-store-service/tests/install_directory.rs b/engine/crates/layerfs-store-service/tests/install_directory.rs index 7fd3af1909..7f81a63bb2 100644 --- a/engine/crates/layerfs-store-service/tests/install_directory.rs +++ b/engine/crates/layerfs-store-service/tests/install_directory.rs @@ -4,9 +4,25 @@ //! call only when that call's own `mkdir` returned success. A `mkdir` failure //! claims nothing, and a guard refusal reclaims only that own, still-empty //! directory, non-recursively. +//! +//! `prepare` starts with the installer-user check, so its own two guard +//! branches need the daemons' user (uid 0), as an install runs in production. +//! Run elsewhere, each case asserts what the same call does at this privilege +//! level: the check refuses before the directory or the guard is touched, so +//! the call creates nothing and removes nothing. `layerfs-store`'s +//! `create_directory` test drives the guard and the same ownership rule +//! through `store.create`, which has no installer-user check, so those run +//! unprivileged. +#![cfg(target_os = "linux")] use layerfs_store_service::install; use std::path::{Path, PathBuf}; +/// Whether this process is the daemons' user, which installs a Store. +fn daemons_user() -> bool { + use std::os::unix::fs::MetadataExt; + std::fs::metadata("/proc/self").is_ok_and(|meta| meta.uid() == 0) +} + fn scratch(parent: &Path, label: &str) -> PathBuf { use std::os::unix::fs::DirBuilderExt; let directory = parent.join(format!("layerfs-install-{label}-{}", std::process::id())); @@ -19,68 +35,60 @@ fn scratch(parent: &Path, label: &str) -> PathBuf { directory } -/// The race of #570 P1, without a sleep: this call observes the directory -/// absent, another caller creates it and installs its Store there, and this -/// call's `mkdir` then fails. Nothing of the other caller's may be removed. -#[test] -fn a_lost_creation_race_never_removes_the_other_callers_directory() { - use std::os::unix::fs::DirBuilderExt; - let parent = scratch(&std::env::temp_dir(), "lost-race"); - let directory = parent.join("global"); - let destination = directory.join("store.sqlite"); - // this call sees no directory yet ... - assert!(!directory.exists()); - // ... another caller makes the same directory `0700` and installs a Store - let other = |directory: &Path| { - std::fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .unwrap(); - std::fs::write(directory.join("store.sqlite"), b"another caller's Store").unwrap(); - }; - // ... and this call's mkdir fails: it made nothing, so it removes nothing - let refused = install::prepare_between(&destination, &|| other(&directory)).unwrap_err(); - assert!(refused.contains("File exists"), "{refused}"); - assert!(directory.is_dir(), "the other caller's directory stays"); - assert_eq!( - std::fs::read(&destination).unwrap(), - b"another caller's Store", - "the other caller's Store stays" - ); - std::fs::remove_dir_all(parent).unwrap(); -} - /// A guard refusal happens before any Store file exists: it reclaims the -/// empty directory this call's own `mkdir` made, and never one it did not -/// make. tmpfs refuses the guard by filesystem, after the `mkdir` succeeded. -#[cfg(target_os = "linux")] +/// empty directory this call's own `mkdir` made, and leaves the volume. +/// tmpfs refuses the guard by filesystem, after the `mkdir` succeeded. #[test] fn a_refused_guard_removes_only_the_empty_directory_this_call_made() { - use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; let volume = scratch(Path::new("/dev/shm"), "tmpfs-volume"); let directory = volume.join("global"); let destination = directory.join("store.sqlite"); - let refused = install::prepare_between(&destination, &|| {}).unwrap_err(); + let refused = install::prepare(&destination).unwrap_err(); + if !daemons_user() { + // the installer-user check comes first: this call made no directory, + // so it has none of its own to reclaim + assert!(refused.contains("must run as user 0"), "{refused}"); + assert!(!directory.exists(), "a refused call made no directory"); + std::fs::remove_dir_all(&volume).unwrap(); + return; + } assert!(refused.contains("ext4, xfs or btrfs"), "{refused}"); assert!( !directory.exists(), "the empty directory this call made is reclaimed" ); assert!(volume.is_dir(), "the volume itself is untouched"); + std::fs::remove_dir_all(&volume).unwrap(); +} - // a directory this call did not make, and what it holds, stay +/// A guard refusal never removes a directory this call did not make, nor the +/// Store another caller put in it. +#[test] +fn a_refused_guard_keeps_a_directory_this_call_did_not_make() { + use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; + let volume = scratch(Path::new("/dev/shm"), "tmpfs-foreign"); + let directory = volume.join("global"); std::fs::DirBuilder::new() .mode(0o700) .create(&directory) .unwrap(); + let destination = directory.join("store.sqlite"); std::fs::write(&destination, b"another caller's Store").unwrap(); std::fs::set_permissions(&destination, std::fs::Permissions::from_mode(0o600)).unwrap(); - let refused = install::prepare_between(&destination, &|| {}).unwrap_err(); - assert!(refused.contains("ext4, xfs or btrfs"), "{refused}"); + let refused = install::prepare(&destination).unwrap_err(); + let guard = daemons_user(); + assert!( + refused.contains(if guard { + "ext4, xfs or btrfs" + } else { + "must run as user 0" + }), + "{refused}" + ); assert!(directory.is_dir(), "the other caller's directory stays"); assert_eq!( std::fs::read(&destination).unwrap(), b"another caller's Store" ); - std::fs::remove_dir_all(volume).unwrap(); + std::fs::remove_dir_all(&volume).unwrap(); } From e45898ae062c73b045813ead656ffebf04373475 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 06:45:49 +0000 Subject: [PATCH 06/11] test(store): cover the mkdir failure that claims no Store directory (#570 P1) LP570-P2FIX-REVIEW P3-2: after the creation-race case went away with the removed test seam, nothing drove `install::prepare` or `identity::make_empty` to their own `mkdir` failing with `AlreadyExists`, so the "a `mkdir` failure claims nothing" rule had no deterministic regression. Both cases give the directory name to a dangling symbolic link inside the test's own scratch directory: `Path::exists` looks through the link and reports nothing, so the call reaches its own `mkdir`, which fails on the taken name. The call must then remove neither that name nor anything behind it, and must not create the link's target. - `layerfs-store-service`'s `install_directory`: `a_mkdir_failure_claims_nothing` calls the public `install::prepare`. `prepare` starts with the installer-user check, so as the daemons' user it asserts the `mkdir` failure itself; at any other privilege level it asserts the refusal the other cases in this file assert, and that the call still changes nothing. No root, no callback, no other test seam. - `layerfs-store`'s `create_directory`: `a_mkdir_failure_removes_nothing` calls `sqlite::create::create`, which has no installer-user check, so it drives `make_empty`'s `mkdir` failure unprivileged. Evidence: in a throwaway worktree at 16a0ba3cb with the reclaim rule put back to "a directory that was absent when observed goes as well" (`install::prepare` and `sqlite::create::create` as before eb7a34f85), `a_mkdir_failure_removes_nothing` fails with exit 101 (the link is removed) while the older tmpfs case still passes; the same reversion with the installer-user check simulated as the daemons' user makes `a_mkdir_failure_claims_nothing` fail with exit 101, and that case passes with the current rule. Production LOC: 158412 -> 158412 (delta 0) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api (tests, fixtures, tools, docs, manifests and generated artifacts excluded), counted with `tools/production_loc.py` on the parent 16a0ba3cb (fresh throwaway worktree) and this tree; only the two test files changed. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Deleted tests: none. --- .../layerfs-store/tests/create_directory.rs | 35 ++++++++++++++++++- .../tests/install_directory.rs | 30 ++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/control/crates/layerfs-store/tests/create_directory.rs b/control/crates/layerfs-store/tests/create_directory.rs index 17476f48a0..06db7ed906 100644 --- a/control/crates/layerfs-store/tests/create_directory.rs +++ b/control/crates/layerfs-store/tests/create_directory.rs @@ -1,7 +1,8 @@ //! `store.create`'s directory (#570 P1): `make_empty` hands back whether this //! call's own `mkdir` made `store/`, and only that ownership may reclaim //! the directory when nothing was published. The guard refuses tmpfs by -//! filesystem, after the `mkdir` succeeded, so it shows both sides. +//! filesystem, after the `mkdir` succeeded, so it shows both sides; a `mkdir` +//! that fails on a taken name claims nothing and removes nothing. use layerfs_home::home::paths; use layerfs_home::names::StoreName; use std::path::{Path, PathBuf}; @@ -18,6 +19,38 @@ fn scratch(parent: &Path, label: &str) -> PathBuf { directory } +/// A `mkdir` that fails removes nothing: the Store's directory name is taken +/// already, by a dangling symbolic link here — `Path::exists` looks through +/// the link and sees nothing, so `make_empty` reaches its own `mkdir`, which +/// returns `AlreadyExists` and so claims no directory. The link, its target +/// and its surroundings stay as they were, and no Store is created. +#[cfg(unix)] +#[test] +fn a_mkdir_failure_removes_nothing() { + let home = scratch(&std::env::temp_dir(), "taken-name"); + layerfs_home::home::layout::create(&home).unwrap(); + let name = StoreName::parse("taken").unwrap(); + let directory = paths::store_dir(&home, &name); + let absent_target = home.join("link-target"); + std::fs::create_dir(home.join("store")).unwrap(); + std::os::unix::fs::symlink(&absent_target, &directory).unwrap(); + let refusal = layerfs_store::sqlite::create::create(&home, &name).unwrap_err(); + assert_eq!(refusal.code, "Failed", "{}", refusal.message); + assert!( + refusal.message.contains("File exists"), + "{}", + refusal.message + ); + let link = std::fs::symlink_metadata(&directory).unwrap(); + assert!(link.file_type().is_symlink(), "the taken name stays"); + assert_eq!(std::fs::read_link(&directory).unwrap(), absent_target); + assert!( + std::fs::symlink_metadata(&absent_target).is_err(), + "the call creates no directory of its own" + ); + std::fs::remove_dir_all(&home).unwrap(); +} + #[cfg(target_os = "linux")] #[test] fn a_refused_create_removes_only_the_directory_this_call_made() { diff --git a/engine/crates/layerfs-store-service/tests/install_directory.rs b/engine/crates/layerfs-store-service/tests/install_directory.rs index 7f81a63bb2..8b51539e50 100644 --- a/engine/crates/layerfs-store-service/tests/install_directory.rs +++ b/engine/crates/layerfs-store-service/tests/install_directory.rs @@ -61,6 +61,36 @@ fn a_refused_guard_removes_only_the_empty_directory_this_call_made() { std::fs::remove_dir_all(&volume).unwrap(); } +/// A `mkdir` that fails claims nothing: the destination's directory name is +/// already taken, by a dangling symbolic link here — `Path::exists` looks +/// through the link and sees nothing, so the call reaches `mkdir`, which +/// returns `AlreadyExists`. The call removes neither that name nor anything +/// behind it, and creates no target of its own. +#[test] +fn a_mkdir_failure_claims_nothing() { + let volume = scratch(Path::new("/dev/shm"), "taken-name"); + let directory = volume.join("global"); + let absent_target = volume.join("link-target"); + std::os::unix::fs::symlink(&absent_target, &directory).unwrap(); + let destination = directory.join("store.sqlite"); + let refused = install::prepare(&destination).unwrap_err(); + if !daemons_user() { + // the installer-user check comes first: this call never reached its + // `mkdir`, and changes nothing + assert!(refused.contains("must run as user 0"), "{refused}"); + } else { + assert!(refused.contains("File exists"), "{refused}"); + } + let link = std::fs::symlink_metadata(&directory).unwrap(); + assert!(link.file_type().is_symlink(), "the taken name stays"); + assert_eq!(std::fs::read_link(&directory).unwrap(), absent_target); + assert!( + std::fs::symlink_metadata(&absent_target).is_err(), + "the call creates no directory of its own" + ); + std::fs::remove_dir_all(&volume).unwrap(); +} + /// A guard refusal never removes a directory this call did not make, nor the /// Store another caller put in it. #[test] From 7c54540dcb2e4849cbc68eea802d18032ec8936c Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:05:34 +0000 Subject: [PATCH 07/11] fix(store): refuse a restore into a Store folder that is not private (#570 P1) `backup.restore` installed through `home::private_dir`, which keeps an existing folder's mode: a `store/` left at 0755 by an earlier restore was accepted and stayed 0755, so the daemon, `branch.fork` and `sandbox.create` refused the Store the restore had just written. The restore now runs `store.create`'s own kernel guard on an existing `store/` before it stages or writes anything, and refuses with the same `Unsupported` code and `chmod 700` remedy; an absent folder is still made 0700 by the install. Tests: the refusal with nothing staged, the same folder at 0700 and an absent one (backup_refusals); a restore into a pre-made 0700 folder against MinIO (backup_family). No test deleted. Production LOC: 159347 -> 159351 (delta +4) Scope: first-party product implementation under core/engine/control/api crates' src plus shipped runtime SQL; tests, docs, tools and manifests are excluded. Counted with `tools/production_loc.py --root `, once on the parent tree 2647fc84e and once on this commit's tree; control 39452 -> 39456, api 5613 -> 5613. Migration subtotals: reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- api/crates/layerfs-api/tests/backup_family.rs | 32 ++++++++++ .../layerfs-api/tests/backup_refusals.rs | 63 +++++++++++++++++++ .../layerfs-store/src/backup/restore.rs | 9 +++ docs/architecture/api/sdk/backup/restore.md | 4 +- .../control/backups/backup-and-restore.md | 3 + 5 files changed, 110 insertions(+), 1 deletion(-) diff --git a/api/crates/layerfs-api/tests/backup_family.rs b/api/crates/layerfs-api/tests/backup_family.rs index 906cd846cd..53ce6cec35 100644 --- a/api/crates/layerfs-api/tests/backup_family.rs +++ b/api/crates/layerfs-api/tests/backup_family.rs @@ -261,6 +261,38 @@ fn backups_against_minio() { ); assert_eq!(states(&home).len(), 2, "objects stayed"); + // a Store folder already there at the daemon's own mode is restored into + // as before (#570 P1): its mode stays, and the Store it takes opens + let private = paths::store_dir(&home, "kept"); + std::fs::create_dir_all(&private).unwrap(); + std::fs::set_permissions(&private, std::fs::Permissions::from_mode(0o700)).unwrap(); + let kept = ok( + &home, + "backup.restore", + &[ + ("store", t("kept")), + ("bucket", t("b1")), + ("file", t("shop")), + ], + ); + assert_eq!(kept.get("projects"), Some(&SdkValue::List(vec![t("api")]))); + assert!(paths::store_file(&home, "kept").is_file()); + assert_eq!( + std::fs::metadata(&private).unwrap().permissions().mode() & 0o7777, + 0o700, + "a Store's own folder stays 0700" + ); + let read = ok( + &home, + "file.read", + &[ + ("project", t("kept/api")), + ("branch", t("dev")), + ("path", t("/NEW")), + ], + ); + assert_eq!(read.get_text("text"), Some("x")); + for dir in [home, folder, root] { let _ = std::fs::remove_dir_all(dir); } diff --git a/api/crates/layerfs-api/tests/backup_refusals.rs b/api/crates/layerfs-api/tests/backup_refusals.rs index ebf7cc008e..f78b5d9534 100644 --- a/api/crates/layerfs-api/tests/backup_refusals.rs +++ b/api/crates/layerfs-api/tests/backup_refusals.rs @@ -128,6 +128,69 @@ fn restore_over_a_store_with_a_running_sandbox_is_in_use() { } } +/// `store/` already there but not the daemon's private directory: the +/// restore refuses it with `store.create`'s own code and remedy before it +/// stages anything, writes nothing and leaves the user's directory as it was +/// (#570 P1). The same folder held `0700`, and an absent one, pass the check +/// and go on to the download. +#[test] +fn restore_refuses_a_store_folder_that_is_not_private() { + let home = tempdir("folder-mode"); + home::open(&home).unwrap(); + dead_bucket(&home); + let directory = paths::store_dir(&home, "open-dir"); + let store = home.join("store"); + let restore = || { + call( + &home, + "backup.restore", + &[("store", t("open-dir")), ("bucket", t("dead"))], + ) + .unwrap_err() + }; + let mode = |dir: &Path| std::fs::metadata(dir).unwrap().permissions().mode() & 0o7777; + + std::fs::create_dir_all(&directory).unwrap(); + std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o755)).unwrap(); + let (code, message) = restore(); + assert_eq!(code, "Unsupported", "{message}"); + assert!( + message.contains(&directory.display().to_string()), + "{message}" + ); + assert!( + message.contains("0755") && message.contains("0700"), + "{message}" + ); + assert!( + message.contains(&format!("chmod 700 {}", directory.display())), + "{message}" + ); + // nothing was written: no staging folder, no Store file or record, and + // the user's own directory keeps its mode + let names: Vec<_> = std::fs::read_dir(&store) + .unwrap() + .filter_map(|entry| entry.ok()) + .map(|entry| entry.file_name().to_string_lossy().into_owned()) + .collect(); + assert_eq!(names, vec!["open-dir"], "a refused restore stages nothing"); + assert_eq!(mode(&directory), 0o755, "the folder's mode is not changed"); + assert!(!paths::store_file(&home, "open-dir").exists()); + assert!(!paths::store_record(&home, "open-dir").exists()); + + // the daemon's own private directory passes: the restore goes on to the + // download, which the dead bucket fails as usual + std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o700)).unwrap(); + let (code, message) = restore(); + assert_ne!(code, "Unsupported", "{message}"); + + // and an absent folder is made `0700` by the install, as before + std::fs::remove_dir_all(&directory).unwrap(); + let (code, message) = restore(); + assert_ne!(code, "Unsupported", "{message}"); + let _ = std::fs::remove_dir_all(home); +} + /// A restore killed mid-download leaves its folder; the next restore removes /// it, and keeps a folder whose restore still holds its lock and one with /// no lock file at all. diff --git a/control/crates/layerfs-store/src/backup/restore.rs b/control/crates/layerfs-store/src/backup/restore.rs index 733351e05a..db19033d90 100644 --- a/control/crates/layerfs-store/src/backup/restore.rs +++ b/control/crates/layerfs-store/src/backup/restore.rs @@ -38,6 +38,15 @@ pub fn restore( let home = home.to_path_buf(); let store = request.store.as_str(); layerfs_home::names::StoreName::parse(store)?; + // the Store's own directory, before this call writes anything (its + // staging folder included): a restore installs into the folder a daemon + // opens, so an existing one must be the same private directory + // `store.create` and every opener require, refused with its own code and + // remedy (#570 P1). Absent: the install makes it `0700`, as before. + if paths::store_dir(&home, store).exists() { + layerfs_store_service::kernel_guard::check(&paths::store_file(&home, store)) + .map_err(|reason| refused("Unsupported", reason.0))?; + } let bucket = request.bucket.as_str(); let driver = BucketRecord::of(&home, bucket)?.driver()?; let existing = StoreRecord::read(&home, store)?; diff --git a/docs/architecture/api/sdk/backup/restore.md b/docs/architecture/api/sdk/backup/restore.md index ae65861063..e38650946e 100644 --- a/docs/architecture/api/sdk/backup/restore.md +++ b/docs/architecture/api/sdk/backup/restore.md @@ -66,6 +66,8 @@ layerfs backup restore [] [--progress] ```text caller process (native) bucket ----------------------- + store/ already there? not the daemon's private 0700 + directory --> Unsupported (store.create's refusal, chmod 700) existing Store? PostgreSQL --> InvalidInput locks: replaceable? (on native, no op, idle, heads == link's heads, no -wal/-shm) --> else refuse @@ -102,7 +104,7 @@ See the [routing table](../../../control/routing/routing-table.md). | --- | --- | --- | --- | | `InvalidInput` | bad names; a PostgreSQL Store; a folder-scoped client | no | [`backup/restore.rs`](../../../../../control/crates/layerfs-store/src/backup/restore.rs) | | `NotFound` | no such bucket; the Store was removed during the download | no | same | -| `Unsupported` | the Store to replace is not on `native` | no | same, `replaceable` | +| `Unsupported` | the Store's folder already exists and is not the daemon's private directory (not a real `0700` directory of this user on a local filesystem; `store.create`'s own refusal, with its `chmod 700` remedy), checked before anything is written; or the Store to replace is not on `native` | no | same | | `Busy` / `Unresolved` | an operation runs on the Store / an earlier one is unresolved | no | [`record.rs`](../../../../../control/crates/layerfs-store/src/record.rs) `unblocked` | | `InUse` | a process holds the Store, a Sandbox of it is recorded, or its `-wal`/`-shm` exists | no | [`inventory.rs`](../../../../../control/crates/layerfs-control/src/inventory.rs) `store_idle`, `replaceable` | | `Conflict` | the Store changed since its last backup or restore through this bucket, has no link, or was replaced during the download | no | same | diff --git a/docs/architecture/control/backups/backup-and-restore.md b/docs/architecture/control/backups/backup-and-restore.md index b645149ec4..707ed9d98a 100644 --- a/docs/architecture/control/backups/backup-and-restore.md +++ b/docs/architecture/control/backups/backup-and-restore.md @@ -107,6 +107,8 @@ push never overwrites a file this home did not move. ```text backup.restore(store, bucket, file?) api/…/backup/restore.rs + store/ already there? refuse it unless it is the daemon's own + private 0700 directory (store.create's guard; before any write) existing Store? refuse PostgreSQL; replaceable? (lock; checked) backup::load(driver, file, store/.restore-/store.sqlite, cursor) | 1 store_object(file); installer_user; make the directory 0700 when @@ -128,6 +130,7 @@ push never overwrites a file this home did not move. | # | Check | Refusal | Source | | --- | --- | --- | --- | +| 0 | The Store's own folder, when it exists, is the daemon's private directory: a real `0700` directory of this user on a local filesystem, checked with `store.create`'s own guard and refused with its `Unsupported` code and `chmod 700` remedy. It runs before the staging folder, so a refused restore writes nothing and leaves the folder's mode alone; an absent folder is made `0700` by the install (row 1). | `Unsupported` | [`backup/restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs) | | 1 | The installer is the daemons' user; the destination's directory is made `0700` when absent; the Store's file passes the kernel guard (a real `0700` directory of this user on a local filesystem), which refuses a missing, symlinked, another owner's or non-private directory. A refusal removes only a directory this call made: the guard's refusal, which happens before any Store file exists, removes this call's own directory with a non-recursive `remove_dir` and only while it is still empty; an installer-user or `mkdir` failure (including `AlreadyExists`, another caller's directory) removes nothing. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | | 2 | Load: no Store at the target. Pull: no `-wal` or `-shm` beside it (no opener holds it). | "a Store exists"; "the local Store … is open" | same | | 3 | The remote file exists and records `layerfs-binding`; a pull's expected binding matches. | "records no layerfs-binding; push it again"; "has another binding" | same | From 82eb09f6479f2c4bb48a2b4f0f4912cc90658033 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 01:57:06 +0000 Subject: [PATCH 08/11] fix(store): check a restore's target folder again before the install (#570 P1) `backup.restore`'s folder check runs when the call starts, but the download between it and the install is a long window: a `store/` that appeared meanwhile, or was changed to 0755, was still installed into and stayed 0755, so the daemon, `branch.fork` and `sandbox.create` refused the Store the restore had just written (#663 review P2-1). The restore's install step is now `backup::restore::install`, which runs the same kernel guard on the target folder again under the home lock, before it links the Store into it or renames it over the old file, and refuses with the same `Unsupported` code and `chmod 700` remedy. What was staged is dropped with the staging folder as before. The first check stays: a folder that is already not private is refused before anything is staged. Tests: `layerfs-store/tests/restore_install.rs` covers the install boundary itself, without a bucket or install permission: a folder made 0755 during the download is refused with nothing installed and its mode kept; a replaced Store's folder is refused before the replacement's own checks; an absent folder is made 0700 and the Store and record are written. The two positive cases in `backup_refusals` now assert a `Failed` from inside the download (the installer-user check as a Linux non-root user, the dead endpoint's own request with install permission) and the staging folder made and removed, instead of "not Unsupported" (review P3-1). No test deleted. Production LOC: 159351 -> 159375 (delta +24) Scope: first-party product implementation under core/engine/control/api crates' src plus shipped runtime SQL; tests, docs, tools and manifests are excluded. Counted with `tools/production_loc.py --root `, once on the parent tree 7c54540dc and once on this commit's staged tree; control 39456 -> 39480, api 5613 -> 5613. Migration subtotals: reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-api/tests/backup_refusals.rs | 68 +++++- .../layerfs-store/src/backup/restore.rs | 94 ++++++--- .../layerfs-store/tests/restore_install.rs | 194 ++++++++++++++++++ docs/architecture/api/sdk/backup/restore.md | 4 +- .../control/backups/backup-and-restore.md | 6 +- 5 files changed, 325 insertions(+), 41 deletions(-) create mode 100644 control/crates/layerfs-store/tests/restore_install.rs diff --git a/api/crates/layerfs-api/tests/backup_refusals.rs b/api/crates/layerfs-api/tests/backup_refusals.rs index f78b5d9534..25dc198a3d 100644 --- a/api/crates/layerfs-api/tests/backup_refusals.rs +++ b/api/crates/layerfs-api/tests/backup_refusals.rs @@ -132,7 +132,7 @@ fn restore_over_a_store_with_a_running_sandbox_is_in_use() { /// restore refuses it with `store.create`'s own code and remedy before it /// stages anything, writes nothing and leaves the user's directory as it was /// (#570 P1). The same folder held `0700`, and an absent one, pass the check -/// and go on to the download. +/// and go on into the download. #[test] fn restore_refuses_a_store_folder_that_is_not_private() { let home = tempdir("folder-mode"); @@ -178,19 +178,71 @@ fn restore_refuses_a_store_folder_that_is_not_private() { assert!(!paths::store_file(&home, "open-dir").exists()); assert!(!paths::store_record(&home, "open-dir").exists()); - // the daemon's own private directory passes: the restore goes on to the - // download, which the dead bucket fails as usual + // the daemon's own private directory passes: the restore goes on into + // the download (`remote::load`), which fails there as it would without + // this check std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o700)).unwrap(); - let (code, message) = restore(); - assert_ne!(code, "Unsupported", "{message}"); + let failed = restore(); + failed_in_the_download(&failed.0, &failed.1); + assert!(!paths::store_file(&home, "open-dir").exists()); + assert!(!paths::store_record(&home, "open-dir").exists()); - // and an absent folder is made `0700` by the install, as before + // and an absent folder passes the check the same way; the install that + // would make it `0700` never runs without install permission, and is + // covered by `layerfs-store`'s `restore_install` std::fs::remove_dir_all(&directory).unwrap(); - let (code, message) = restore(); - assert_ne!(code, "Unsupported", "{message}"); + let failed = restore(); + failed_in_the_download(&failed.0, &failed.1); + assert!(!directory.exists(), "no install ran for this call"); + // both calls reached the download: each made its staging folder under + // the home lock and removed it when it failed + let staged: Vec<_> = std::fs::read_dir(&store) + .unwrap() + .filter_map(|entry| entry.ok()) + .map(|entry| entry.file_name().to_string_lossy().into_owned()) + .filter(|name| name.starts_with(".restore-")) + .collect(); + assert!( + staged.is_empty(), + "a failed download left its staging folder: {staged:?}" + ); let _ = std::fs::remove_dir_all(home); } +/// A restore that passed the directory check failed inside the download: +/// `remote::load`'s own first checks run there, and which one stops it says +/// how far it went — the installer user in a Linux process that cannot +/// install (before any request is sent), else the dead endpoint's own +/// request. Neither is this directory guard. +fn failed_in_the_download(code: &str, message: &str) { + assert_eq!(code, "Failed", "{message}"); + if installs_as_the_daemons_user() { + assert!( + !message.contains("chmod 700"), + "the download failed, not the directory guard: {message}" + ); + } else { + assert!( + message.contains("must run as user 0"), + "the download's own installer-user check: {message}" + ); + } +} + +/// Whether this process is the user a Store install requires: on Linux only +/// uid 0 is (`layerfs-store-service` `install`), so every other run stops at +/// that check instead of reaching the bucket. +fn installs_as_the_daemons_user() -> bool { + #[cfg(target_os = "linux")] + { + nix::unistd::geteuid().is_root() + } + #[cfg(not(target_os = "linux"))] + { + true + } +} + /// A restore killed mid-download leaves its folder; the next restore removes /// it, and keeps a folder whose restore still holds its lock and one with /// no lock file at all. diff --git a/control/crates/layerfs-store/src/backup/restore.rs b/control/crates/layerfs-store/src/backup/restore.rs index db19033d90..50607ee43b 100644 --- a/control/crates/layerfs-store/src/backup/restore.rs +++ b/control/crates/layerfs-store/src/backup/restore.rs @@ -112,20 +112,75 @@ pub fn restore( let found = projects_in(&home, store, &record, &staged)?; shown.phase(events, "install"); let _lock = home::lock::take(&home)?; + install( + &home, + store, + bucket, + existing.as_ref(), + &record, + &staged, + related, + )?; + write_link( + &home, + store, + bucket, + StoreLink::new( + &file, + "restore", + loaded.bytes, + &loaded.sha256, + loaded.heads.as_ref(), + ), + )?; + let projects = write_projects(&home, store, &found)?; + Ok(SdkValue::map([ + ("store", SdkValue::text(store)), + ("bucket", SdkValue::text(bucket)), + ("file", SdkValue::text(&file)), + ("bytes", SdkValue::Int(loaded.bytes as i64)), + ("sha256", hex(&loaded.sha256)), + ("heads", loaded.heads.as_ref().map(hex).unwrap_or_default()), + ("projects", projects), + ])) +} + +/// Installs the downloaded Store `staged` as `store` (under the home lock): +/// a new Store where `existing` is `None`, else it replaces the Store that +/// record names. +/// +/// The target's folder is checked again first: the download is a long +/// window, in which `store/` can appear or lose its privacy after the +/// restore's own first check, and `home::private_dir` keeps an existing +/// folder's mode. This is `store.create`'s guard, its code and its remedy +/// (#570 P1). +pub fn install( + home: &Path, + store: &str, + bucket: &str, + existing: Option<&StoreRecord>, + record: &StoreRecord, + staged: &Path, + related: Related, +) -> Result<()> { + if paths::store_dir(home, store).exists() { + layerfs_store_service::kernel_guard::check(&paths::store_file(home, store)) + .map_err(|reason| refused("Unsupported", reason.0))?; + } // a Store replaced here is checked and replaced under its lock, which // the link below takes again let store_lock = match &existing { - Some(_) => Some(crate::record::lock(&home, store)?), + Some(_) => Some(crate::record::lock(home, store)?), None => None, }; - let destination = paths::store_file(&home, store); - let now = StoreRecord::read(&home, store)?; + let destination = paths::store_file(home, store); + let now = StoreRecord::read(home, store)?; match (&existing, now) { (None, None) if !destination.exists() => { - home::private_dir(&paths::store_dir(&home, store))?; + home::private_dir(&paths::store_dir(home, store))?; // a link never replaces a Store that appeared meanwhile - std::fs::hard_link(&staged, &destination).map_err(failed)?; - record.write(&home)?; + std::fs::hard_link(staged, &destination).map_err(failed)?; + record.write(home)?; } (None, _) => { return Err(refused( @@ -146,33 +201,12 @@ pub fn restore( format!("Store {store} was replaced while this restore downloaded"), )); } - replaceable(&home, store, bucket, &now, related)?; - std::fs::rename(&staged, &destination).map_err(failed)?; + replaceable(home, store, bucket, &now, related)?; + std::fs::rename(staged, &destination).map_err(failed)?; } } drop(store_lock); - write_link( - &home, - store, - bucket, - StoreLink::new( - &file, - "restore", - loaded.bytes, - &loaded.sha256, - loaded.heads.as_ref(), - ), - )?; - let projects = write_projects(&home, store, &found)?; - Ok(SdkValue::map([ - ("store", SdkValue::text(store)), - ("bucket", SdkValue::text(bucket)), - ("file", SdkValue::text(&file)), - ("bytes", SdkValue::Int(loaded.bytes as i64)), - ("sha256", hex(&loaded.sha256)), - ("heads", loaded.heads.as_ref().map(hex).unwrap_or_default()), - ("projects", projects), - ])) + Ok(()) } /// A restore's own download folder, `store/.restore-/` (hidden from diff --git a/control/crates/layerfs-store/tests/restore_install.rs b/control/crates/layerfs-store/tests/restore_install.rs new file mode 100644 index 0000000000..2364f2e8c3 --- /dev/null +++ b/control/crates/layerfs-store/tests/restore_install.rs @@ -0,0 +1,194 @@ +//! The install step of `backup.restore` (#570 P1, review P2-1). The restore +//! checks `store/` when it starts, but the download between that check +//! and the install is a long window: the folder can appear, or lose its +//! privacy, while it runs, and `home::private_dir` keeps an existing folder's +//! mode. The install therefore checks the target's folder again, under the +//! home lock, before it links the Store into it: a folder that is not the +//! daemon's private one is refused with `store.create`'s code and remedy and +//! nothing is installed; a private one, and an absent one (made `0700`), are +//! installed. These tests run in an ordinary user's process: no bucket, no +//! install permission, no timing. +use layerfs_bridge::control::SdkRefusal; +use layerfs_home::home::{self, paths}; +use layerfs_store::backup::restore::install; +use layerfs_store::record::StoreRecord; +use layerfs_store::Related; +use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; +use std::path::{Path, PathBuf}; + +/// A home whose own folder is private, as `backup.restore` requires. +fn scratch(label: &str) -> PathBuf { + let home = std::env::temp_dir().join(format!( + "layerfs-restore-install-{label}-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&home); + std::fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(&home) + .unwrap(); + home::layout::create(&home).unwrap(); + home::private_dir(&home.join("store")).unwrap(); + home +} + +/// The `InUse` checks a new Store's install never asks. +fn unused(home: &Path, name: &str) -> Result<(), SdkRefusal> { + panic!( + "a new Store's install asks no user: {} in {}", + name, + home.display() + ); +} + +fn related() -> Related { + Related { + store_idle: unused, + can_remove_project: unused, + } +} + +/// The downloaded Store, staged as `backup.restore` leaves it before the +/// install. +fn staged(home: &Path) -> PathBuf { + let folder = home.join("store/.restore-fixture"); + home::private_dir(&folder).unwrap(); + let file = folder.join("store.sqlite"); + std::fs::write(&file, b"the downloaded Store\n").unwrap(); + file +} + +fn mode(path: &Path) -> u32 { + std::fs::metadata(path).unwrap().permissions().mode() & 0o7777 +} + +fn set_mode(path: &Path, mode: u32) { + std::fs::set_permissions(path, std::fs::Permissions::from_mode(mode)).unwrap(); +} + +/// `store/` made `0755` while the restore downloads: the install +/// refuses it, with `store.create`'s `Unsupported` and `chmod 700` remedy, +/// before it links the Store or writes the record. The user's folder keeps +/// its mode, nothing of the restore is installed and the staged file stays +/// for the restore to remove with its staging folder; once the folder is +/// private again the same install goes through. +#[test] +fn a_folder_made_unprivate_during_the_download_is_refused_before_the_install() { + let home = scratch("window"); + let store = "shop"; + let directory = paths::store_dir(&home, store); + let staged = staged(&home); + let record = StoreRecord::restored(store, b"binding", &[7; 32]); + let _lock = home::lock::take(&home).unwrap(); + + // the restore's own first check saw no folder; the download ran + assert!(!directory.exists()); + std::fs::create_dir(&directory).unwrap(); + set_mode(&directory, 0o755); + + let refusal = install(&home, store, "bucket", None, &record, &staged, related()) + .expect_err("a 0755 folder is not the daemon's private directory"); + assert_eq!(refusal.code, "Unsupported", "{}", refusal.message); + assert!( + refusal.message.contains(&directory.display().to_string()), + "{}", + refusal.message + ); + assert!( + refusal.message.contains("0755") && refusal.message.contains("0700"), + "{}", + refusal.message + ); + assert!( + refusal + .message + .contains(&format!("chmod 700 {}", directory.display())), + "{}", + refusal.message + ); + assert_eq!(mode(&directory), 0o755, "the folder's mode is not changed"); + assert!(!paths::store_file(&home, store).exists()); + assert!(!paths::store_record(&home, store).exists()); + assert_eq!( + std::fs::read(&staged).unwrap(), + b"the downloaded Store\n", + "nothing was linked out of the staging folder" + ); + + // the folder made private again: this install is the one that goes in + set_mode(&directory, 0o700); + install(&home, store, "bucket", None, &record, &staged, related()).unwrap(); + assert_eq!(mode(&directory), 0o700); + assert_eq!( + std::fs::read(paths::store_file(&home, store)).unwrap(), + b"the downloaded Store\n" + ); + let written = StoreRecord::read(&home, store).unwrap().unwrap(); + assert_eq!(written.binding(), Some(&b"binding"[..])); + let _ = std::fs::remove_dir_all(&home); +} + +/// A Store this restore replaces lost its privacy during the download: its +/// own folder is refused before the replacement's checks run, so the download +/// is not installed over the Store either. +#[test] +fn a_replaced_stores_folder_is_checked_again_before_the_install() { + let home = scratch("replacing"); + let store = "shop"; + let directory = paths::store_dir(&home, store); + let staged = staged(&home); + let existing = StoreRecord::restored(store, b"binding", &[9; 32]); + existing.write(&home).unwrap(); + set_mode(&directory, 0o755); + let _lock = home::lock::take(&home).unwrap(); + + let refusal = install( + &home, + store, + "bucket", + Some(&existing), + &existing, + &staged, + related(), + ) + .expect_err("a 0755 folder is not the daemon's private directory"); + assert_eq!(refusal.code, "Unsupported", "{}", refusal.message); + assert!(refusal.message.contains("chmod 700"), "{}", refusal.message); + // the guard's refusal, not the replacement's own: the Store was not + // reached, so it still holds what it had and its folder its mode + assert!( + !refusal.message.contains("changed since"), + "{}", + refusal.message + ); + assert!(!paths::store_file(&home, store).exists()); + assert_eq!(mode(&directory), 0o755); + assert_eq!( + StoreRecord::read(&home, store).unwrap().unwrap().binding(), + Some(&b"binding"[..]) + ); + let _ = std::fs::remove_dir_all(&home); +} + +/// A folder the download left absent is made `0700` by the install, which is +/// the restore's own new-Store path: the Store file and its record are +/// written, and the folder is one every opener accepts. +#[test] +fn an_absent_folder_is_made_private_by_the_install() { + let home = scratch("absent"); + let store = "shop"; + let staged = staged(&home); + let record = StoreRecord::restored(store, b"binding", &[3; 32]); + let _lock = home::lock::take(&home).unwrap(); + assert!(!paths::store_dir(&home, store).exists()); + + install(&home, store, "bucket", None, &record, &staged, related()).unwrap(); + assert_eq!(mode(&paths::store_dir(&home, store)), 0o700); + assert_eq!( + std::fs::read(paths::store_file(&home, store)).unwrap(), + b"the downloaded Store\n" + ); + assert!(paths::store_record(&home, store).is_file()); + let _ = std::fs::remove_dir_all(&home); +} diff --git a/docs/architecture/api/sdk/backup/restore.md b/docs/architecture/api/sdk/backup/restore.md index e38650946e..bf3e19160e 100644 --- a/docs/architecture/api/sdk/backup/restore.md +++ b/docs/architecture/api/sdk/backup/restore.md @@ -78,6 +78,8 @@ layerfs backup restore [] [--progress] checked; binding must match an existing Store's read the file's projects (own connection, closed) home lock (+ Store lock when replacing): + store/ checked again: it may have appeared or lost its + privacy during the download --> Unsupported, nothing installed new: hard-link into store//store.sqlite, write record replace: re-check binding and replaceable, rename over the file write the link; rebuild project records @@ -104,7 +106,7 @@ See the [routing table](../../../control/routing/routing-table.md). | --- | --- | --- | --- | | `InvalidInput` | bad names; a PostgreSQL Store; a folder-scoped client | no | [`backup/restore.rs`](../../../../../control/crates/layerfs-store/src/backup/restore.rs) | | `NotFound` | no such bucket; the Store was removed during the download | no | same | -| `Unsupported` | the Store's folder already exists and is not the daemon's private directory (not a real `0700` directory of this user on a local filesystem; `store.create`'s own refusal, with its `chmod 700` remedy), checked before anything is written; or the Store to replace is not on `native` | no | same | +| `Unsupported` | the Store's folder already exists and is not the daemon's private directory (not a real `0700` directory of this user on a local filesystem; `store.create`'s own refusal, with its `chmod 700` remedy), checked before anything is written and again under the home lock before the install, so a folder that appeared or lost its privacy during the download is refused too; or the Store to replace is not on `native` | no | same | | `Busy` / `Unresolved` | an operation runs on the Store / an earlier one is unresolved | no | [`record.rs`](../../../../../control/crates/layerfs-store/src/record.rs) `unblocked` | | `InUse` | a process holds the Store, a Sandbox of it is recorded, or its `-wal`/`-shm` exists | no | [`inventory.rs`](../../../../../control/crates/layerfs-control/src/inventory.rs) `store_idle`, `replaceable` | | `Conflict` | the Store changed since its last backup or restore through this bucket, has no link, or was replaced during the download | no | same | diff --git a/docs/architecture/control/backups/backup-and-restore.md b/docs/architecture/control/backups/backup-and-restore.md index 707ed9d98a..76e588b046 100644 --- a/docs/architecture/control/backups/backup-and-restore.md +++ b/docs/architecture/control/backups/backup-and-restore.md @@ -124,13 +124,15 @@ push never overwrites a file this home did not move. v binding == existing Store's? (else Failed) read its projects - home lock: re-check replaceable; hard link (new) or rename (replace) + home lock: the target's folder checked again (it may have appeared or + lost its privacy during the download); re-check replaceable; hard + link (new) or rename (replace) write the link and project records ``` | # | Check | Refusal | Source | | --- | --- | --- | --- | -| 0 | The Store's own folder, when it exists, is the daemon's private directory: a real `0700` directory of this user on a local filesystem, checked with `store.create`'s own guard and refused with its `Unsupported` code and `chmod 700` remedy. It runs before the staging folder, so a refused restore writes nothing and leaves the folder's mode alone; an absent folder is made `0700` by the install (row 1). | `Unsupported` | [`backup/restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs) | +| 0 | The Store's own folder, when it exists, is the daemon's private directory: a real `0700` directory of this user on a local filesystem, checked with `store.create`'s own guard and refused with its `Unsupported` code and `chmod 700` remedy. It runs before the staging folder, so a refused restore writes nothing and leaves the folder's mode alone; an absent folder is made `0700` by the install (row 1). **It runs again under the home lock, after the download and before the install** (the restore's `install` step): the download is a long window in which `store/` can appear or be changed to a non-private mode, and `home::private_dir` keeps an existing folder's mode, so the first check alone would admit a folder the daemon, `branch.fork` and `sandbox.create` then refuse. The staged Store is dropped with the staging folder either way. | `Unsupported` | [`backup/restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs) | | 1 | The installer is the daemons' user; the destination's directory is made `0700` when absent; the Store's file passes the kernel guard (a real `0700` directory of this user on a local filesystem), which refuses a missing, symlinked, another owner's or non-private directory. A refusal removes only a directory this call made: the guard's refusal, which happens before any Store file exists, removes this call's own directory with a non-recursive `remove_dir` and only while it is still empty; an installer-user or `mkdir` failure (including `AlreadyExists`, another caller's directory) removes nothing. | `PullFailure` cause | [`backup/restore.rs`](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | | 2 | Load: no Store at the target. Pull: no `-wal` or `-shm` beside it (no opener holds it). | "a Store exists"; "the local Store … is open" | same | | 3 | The remote file exists and records `layerfs-binding`; a pull's expected binding matches. | "records no layerfs-binding; push it again"; "has another binding" | same | From affb55b6cb96c5f0e78512b0b0ffb52303ad2bd0 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:37:25 +0000 Subject: [PATCH 09/11] fix(store): share the directory claim and report a linked Store folder (#570 P1 review) Review r663.md, points 1-3 and the smaller ones: - Point 1, the merge with #647: its `installed::Fixture` made the Store's folder with plain `std::fs::create_dir` (0755), so its new `open_direct` tests reached this branch's guard's `Unsupported` before Busy, corrupt or concurrent (`tests/support/installed_store.rs:48,119`). Both constructors now make that folder `0700` through one `private_directory`. Verified by merging `origin/fix/578-sync-volume` into a throwaway worktree: before, `kernel_guard`'s two new tests failed with `Unsupported(... has mode 0775 ...)`; after, all 5 passed. Whichever PR lands second needs this folder to be `0700`. - Point 2: the restore's install-entry check from 82eb09f64 is unchanged. `install` checks the target's folder before `private_dir`, `hard_link` and `rename`, under the caller's home lock (`control/crates/layerfs-store/src/backup/restore.rs:166`). - Smaller: the claim step (a `0700` `mkdir`, ownership only when this call's own `mkdir` succeeded) is now one product function, `install::make_private_directory`, used by `prepare` and by `store.create`'s `make_empty`. This removes the second copy of the ownership rule and lets an unprivileged test drive both branches and the failed `mkdir`; the `install_directory` guard cases still need the daemons' user. - Smaller: doctor now reports a folder that is a symlink as a link, and its remedy no longer `chmod`s through the link into the target (the 0777 it reported was the link's own mode). A `store/` link is scanned too, so a Store folder the daemon refuses is reported rather than skipped. - Smaller: docs say the macOS `HostProcess` Rust and Git homes are the caller's own writable ones, so a native command can change the host's toolchain. - Not split: the env passthrough (a80592cae) stays in this PR; the review calls the split optional. - Point 3 (the breaking change in the PR description) is in the handoff report, which no call or code change can carry. Production LOC: 160145 -> 160194 (delta +49) Scope and method: first-party production Rust/SQL/JavaScript in core, engine, control and api; tests, fixtures, tools, docs, manifests/lockfiles and generated artifacts excluded. Counted with tools/production_loc.py --detail on the exported parent tree (this commit's parent 3f039a74a) and this tree: engine 74500 -> 74506 (+6), control 39882 -> 39925 (+43); core 39787 and api 5976 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../crates/layerfs-control/src/doctor/scan.rs | 57 ++++++++++++++++- .../crates/layerfs-control/tests/doctor.rs | 55 ++++++++++++++++ control/crates/layerfs-store/src/identity.rs | 15 ++--- .../control/sandboxes/commands-and-streams.md | 5 ++ .../layerfs-store-service/src/install.rs | 38 ++++++++--- .../tests/install_directory.rs | 64 +++++++++++++++++-- .../tests/support/installed_store.rs | 12 +++- 7 files changed, 220 insertions(+), 26 deletions(-) diff --git a/control/crates/layerfs-control/src/doctor/scan.rs b/control/crates/layerfs-control/src/doctor/scan.rs index f3fb00cd4a..0d6a238526 100644 --- a/control/crates/layerfs-control/src/doctor/scan.rs +++ b/control/crates/layerfs-control/src/doctor/scan.rs @@ -37,6 +37,30 @@ fn names(dir: &Path) -> Result> { paths::names(dir).map_err(failed) } +/// The Store names under `home/store`: a real folder, and a link to one, which +/// the scan reports (the Store guard refuses a link where it wants the Store's +/// own directory) rather than skipping it as [`paths::names`] does. +fn store_names(dir: &Path) -> Result> { + let mut names = Vec::new(); + let entries = match std::fs::read_dir(dir) { + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(names), + other => other.map_err(failed)?, + }; + for entry in entries { + let entry = entry.map_err(failed)?; + let kind = entry.file_type().map_err(failed)?; + if !kind.is_dir() && !kind.is_symlink() { + continue; + } + if let Some(name) = entry.file_name().to_str() { + if !name.starts_with('.') { + names.push(name.to_owned()); + } + } + } + Ok(names) +} + /// Reads the home's records and modes. pub(super) fn scan(home: &Path, findings: &mut Findings) -> Result { let mut scanned = Scanned::default(); @@ -60,7 +84,7 @@ pub(super) fn scan(home: &Path, findings: &mut Findings) -> Result { } record(&paths::worker_record(home, &name), entity, false, findings); } - for name in names(&home.join("store"))? { + for name in store_names(&home.join("store"))? { store(home, &name, &mut scanned, findings)?; } for name in names(&home.join("sandbox"))? { @@ -260,9 +284,37 @@ fn mode(path: &Path) -> Option { Some(metadata.permissions().mode() & 0o7777) } +/// Reports `path` when it is a symbolic link and says whether it did: a +/// link's own mode (0777) is not the folder's, and a `chmod` through the link +/// changes what it points at, so neither describes the folder. The Store +/// guard likewise refuses a link where it wants the Store's own directory. +fn link(path: &Path, entity: (&str, &str), findings: &mut Findings) -> bool { + let Ok(metadata) = std::fs::symlink_metadata(path) else { + return false; + }; + if !metadata.file_type().is_symlink() { + return false; + } + findings.error( + entity, + format!( + "{} is a symlink, not a folder; a `chmod` through it would change what it points at", + path.display() + ), + format!( + "make it a real folder: remove the link and create {} as 0700", + path.display() + ), + ); + true +} + /// A folder others may list or change, or its group may use, is an error; /// others may pass through (0701). fn folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { + if link(path, entity, findings) { + return; + } if let Some(mode) = mode(path).filter(|mode| mode & 0o076 != 0) { findings.error( entity, @@ -279,6 +331,9 @@ fn folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { /// group or other bits at all, not even pass-through, so a folder doctor /// calls fine is one the daemon opens. fn store_folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { + if link(path, entity, findings) { + return; + } if let Some(mode) = mode(path).filter(|mode| mode & 0o077 != 0) { findings.error( entity, diff --git a/control/crates/layerfs-control/tests/doctor.rs b/control/crates/layerfs-control/tests/doctor.rs index abbfba22f9..485d282112 100644 --- a/control/crates/layerfs-control/tests/doctor.rs +++ b/control/crates/layerfs-control/tests/doctor.rs @@ -175,6 +175,61 @@ fn a_store_folder_others_may_pass_through_is_an_error_naming_chmod_700() { std::fs::remove_dir_all(home).unwrap(); } +#[test] +fn a_symlinked_store_folder_is_an_error_that_does_not_change_the_target() { + // the home's `store/` as a link: its own mode is 0777, not the folder's, + // and the remedy must not chmod through the link into its target + let home = new_home("store-link"); + layerfs_control::migrate::open(&home).unwrap(); + let elsewhere = + std::env::temp_dir().join(format!("layerfs-doctor-link-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&elsewhere); + std::fs::create_dir(&elsewhere).unwrap(); + std::fs::set_permissions(&elsewhere, std::fs::Permissions::from_mode(0o700)).unwrap(); + let store = home.join("store"); + let _ = std::fs::remove_dir_all(&store); + std::os::unix::fs::symlink(&elsewhere, &store).unwrap(); + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(false)), "{report:?}"); + let found = findings(&report); + assert_eq!(found.len(), 1, "{found:?}"); + let (severity, kind, _name, message, fix) = &found[0]; + assert_eq!((severity.as_str(), kind.as_str()), ("error", "home")); + assert!(message.contains("symlink"), "{message}"); + assert!(!fix.contains("chmod"), "{fix}"); + std::fs::remove_file(&store).unwrap(); + std::fs::remove_dir_all(&elsewhere).unwrap(); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn a_symlinked_store_entry_is_an_error_that_does_not_change_the_target() { + // `store/` as a link: the daemon refuses it, so doctor reports it; + // the remedy is not a chmod, which would change the link's target + let home = new_home("store-entry-link"); + layerfs_control::migrate::open(&home).unwrap(); + store(&home, "shop", sqlite("shop", "native")); + let elsewhere = + std::env::temp_dir().join(format!("layerfs-doctor-entry-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&elsewhere); + std::fs::rename(paths::store_dir(&home, "shop"), &elsewhere).unwrap(); + std::os::unix::fs::symlink(&elsewhere, paths::store_dir(&home, "shop")).unwrap(); + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(false)), "{report:?}"); + let found = findings(&report); + assert_eq!(found.len(), 1, "{found:?}"); + let (severity, kind, name, message, fix) = &found[0]; + assert_eq!( + (severity.as_str(), kind.as_str(), name.as_str()), + ("error", "store", "shop") + ); + assert!(message.contains("symlink"), "{message}"); + assert!(!fix.contains("chmod"), "{fix}"); + std::fs::remove_file(paths::store_dir(&home, "shop")).unwrap(); + std::fs::remove_dir_all(&elsewhere).unwrap(); + std::fs::remove_dir_all(home).unwrap(); +} + #[test] fn a_home_that_does_not_exist_is_ok_and_stays_absent() { let home = new_home("absent"); diff --git a/control/crates/layerfs-store/src/identity.rs b/control/crates/layerfs-store/src/identity.rs index 3d4bb84e78..a6d233fa3a 100644 --- a/control/crates/layerfs-store/src/identity.rs +++ b/control/crates/layerfs-store/src/identity.rs @@ -236,15 +236,12 @@ fn create_empty( policy: layerfs_storage::StoragePolicy, made: &mut MadeDirectory, ) -> Result { - use std::os::unix::fs::{DirBuilderExt, PermissionsExt}; - if !global.exists() { - std::fs::DirBuilder::new() - .mode(0o700) - .create(global) - .map_err(failed)?; - // the directory is this call's own only now that its mkdir succeeded - *made = MadeDirectory::ThisCall; - } + use std::os::unix::fs::PermissionsExt; + // the one ownership rule an install uses too: this call's own `mkdir` + *made = match layerfs_store_service::install::make_private_directory(global).map_err(failed)? { + layerfs_store_service::install::Made::ThisCall => MadeDirectory::ThisCall, + layerfs_store_service::install::Made::AlreadyThere => MadeDirectory::AlreadyThere, + }; layerfs_store_service::kernel_guard::check(destination) .map_err(|reason| refused("Unsupported", reason.0))?; let (target, _) = layerfs_store_service::install::paths(destination).map_err(failed)?; diff --git a/docs/architecture/control/sandboxes/commands-and-streams.md b/docs/architecture/control/sandboxes/commands-and-streams.md index 8a5b981ccd..f914791a95 100644 --- a/docs/architecture/control/sandboxes/commands-and-streams.md +++ b/docs/architecture/control/sandboxes/commands-and-streams.md @@ -43,6 +43,11 @@ the Workspace through ordinary file calls on the mount. | Stdin | Both backends refuse it (`Unsupported`). | [`host_process/exec.rs`](../../../../control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs) | | Timeout | None. A command runs until it ends. | each `exec.rs` | +The macOS `HostProcess` homes are the caller's own, writable ones, not copies: +a command there (`cargo install`, `rustup update`, a git write) changes the +host's toolchain, installed binaries and global Git configuration, as the +same command run by the user would. + ## Streams ```text diff --git a/engine/crates/layerfs-store-service/src/install.rs b/engine/crates/layerfs-store-service/src/install.rs index 0341a04fcd..5c27660c7e 100644 --- a/engine/crates/layerfs-store-service/src/install.rs +++ b/engine/crates/layerfs-store-service/src/install.rs @@ -138,6 +138,32 @@ impl std::fmt::Display for LocalInstallFailure { } } +/// Whether this call's own `mkdir` made the Store's directory: the only +/// ownership that lets a caller reclaim that directory when nothing was +/// published. A directory another caller, or the user, made is never this +/// call's to remove. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum Made { + /// This call's `mkdir` created it. + ThisCall, + /// It was already there; it is not this call's to remove. + AlreadyThere, +} + +/// Makes the Store's directory owner-only (`0700`) when it is absent and says +/// whether this call's own `mkdir` made it. One ownership rule for the Store's +/// directory, shared by an install and `store.create` (`make_empty`): a +/// `mkdir` that fails — `AlreadyExists`, when another caller made the +/// directory first, included — claims nothing. +pub fn make_private_directory(directory: &Path) -> io::Result { + use std::os::unix::fs::DirBuilderExt; + if directory.exists() { + return Ok(Made::AlreadyThere); + } + fs::DirBuilder::new().mode(0o700).create(directory)?; + Ok(Made::ThisCall) +} + /// Makes the Store's directory owner-only (`0700`, created as such when it is /// absent), then checks the kernel guard for the Store file. A directory is /// this call's own only when this call's `mkdir` returned success: an @@ -150,16 +176,8 @@ pub fn prepare(destination: &Path) -> Result<(), String> { let directory = destination .parent() .ok_or("the Store destination has no directory")?; - let mut made = false; - if !directory.exists() { - use std::os::unix::fs::DirBuilderExt; - fs::DirBuilder::new() - .mode(0o700) - .create(directory) - .map_err(|error| error.to_string())?; - // the directory is this call's own only now that its mkdir succeeded - made = true; - } + let made = + make_private_directory(directory).map_err(|error| error.to_string())? == Made::ThisCall; match crate::kernel_guard::check(destination) { Ok(_) => Ok(()), Err(reason) => { diff --git a/engine/crates/layerfs-store-service/tests/install_directory.rs b/engine/crates/layerfs-store-service/tests/install_directory.rs index 8b51539e50..14f8024f1b 100644 --- a/engine/crates/layerfs-store-service/tests/install_directory.rs +++ b/engine/crates/layerfs-store-service/tests/install_directory.rs @@ -9,10 +9,12 @@ //! branches need the daemons' user (uid 0), as an install runs in production. //! Run elsewhere, each case asserts what the same call does at this privilege //! level: the check refuses before the directory or the guard is touched, so -//! the call creates nothing and removes nothing. `layerfs-store`'s -//! `create_directory` test drives the guard and the same ownership rule -//! through `store.create`, which has no installer-user check, so those run -//! unprivileged. +//! the call creates nothing and removes nothing. The claim step itself is +//! [`install::make_private_directory`], one function shared with +//! `store.create`'s `make_empty`; it has no installer-user check, so the test +//! below drives both of its branches and its failed `mkdir` unprivileged, +//! and `layerfs-store`'s `create_directory` test drives the same step and the +//! guard through `store.create`. #![cfg(target_os = "linux")] use layerfs_store_service::install; use std::path::{Path, PathBuf}; @@ -35,6 +37,60 @@ fn scratch(parent: &Path, label: &str) -> PathBuf { directory } +/// The claim step on its own, as any user: an absent directory is made +/// `0700` and belongs to this call, one that is already there keeps its mode +/// and belongs to no one, and a `mkdir` that fails on a taken name claims +/// nothing. `prepare` acts on exactly this answer, and `store.create`'s +/// `make_empty` uses the same step. +#[test] +fn the_directory_claim_creates_0700_and_marks_only_its_own_mkdir() { + use std::os::unix::fs::PermissionsExt; + let volume = scratch(&std::env::temp_dir(), "claim"); + let made = volume.join("made"); + assert_eq!( + install::make_private_directory(&made).unwrap(), + install::Made::ThisCall + ); + let mode = std::fs::symlink_metadata(&made) + .unwrap() + .permissions() + .mode() + & 0o7777; + assert_eq!(mode, 0o700, "this call's own directory is private"); + std::fs::set_permissions(&made, std::fs::Permissions::from_mode(0o755)).unwrap(); + assert_eq!( + install::make_private_directory(&made).unwrap(), + install::Made::AlreadyThere + ); + let mode = std::fs::symlink_metadata(&made) + .unwrap() + .permissions() + .mode() + & 0o7777; + assert_eq!( + mode, 0o755, + "a directory this call did not make keeps its mode" + ); + // a taken name: `Path::exists` looks through the dangling link and sees + // nothing, so the step reaches `mkdir`, which claims no directory + let taken = volume.join("taken"); + std::os::unix::fs::symlink(volume.join("absent-target"), &taken).unwrap(); + let refused = install::make_private_directory(&taken).unwrap_err(); + assert_eq!( + refused.kind(), + std::io::ErrorKind::AlreadyExists, + "{refused}" + ); + assert!( + std::fs::symlink_metadata(&taken) + .unwrap() + .file_type() + .is_symlink(), + "the taken name stays" + ); + std::fs::remove_dir_all(&volume).unwrap(); +} + /// A guard refusal happens before any Store file exists: it reclaims the /// empty directory this call's own `mkdir` made, and leaves the volume. /// tmpfs refuses the guard by filesystem, after the `mkdir` succeeded. diff --git a/engine/crates/layerfs-store-service/tests/support/installed_store.rs b/engine/crates/layerfs-store-service/tests/support/installed_store.rs index e609c8258e..8187f5c8a6 100644 --- a/engine/crates/layerfs-store-service/tests/support/installed_store.rs +++ b/engine/crates/layerfs-store-service/tests/support/installed_store.rs @@ -45,7 +45,7 @@ impl Fixture { ) -> Self { let directory = std::env::temp_dir().join(format!("layerfs-installed-{}-{label}", std::process::id())); - std::fs::create_dir(&directory).unwrap(); + private_directory(&directory); let source = directory.join("source"); std::fs::create_dir(&source).unwrap(); let count = build(&source); @@ -116,7 +116,7 @@ impl Fixture { pub fn cloned(label: &str, store: &std::path::Path, count: usize) -> Self { let directory = std::env::temp_dir().join(format!("layerfs-installed-{}-{label}", std::process::id())); - std::fs::create_dir(&directory).unwrap(); + private_directory(&directory); let installed = directory.join("store.sqlite"); std::fs::copy(store, &installed).unwrap(); Self { @@ -132,6 +132,14 @@ impl Fixture { std::fs::remove_dir_all(self.directory).unwrap(); } } +/// The fixture's own Store folder: private as every folder a daemon opens, +/// because `kernel_guard` refuses group or other access and an open through +/// `StoreService::open_direct` reaches the Store itself. +fn private_directory(path: &std::path::Path) { + use std::os::unix::fs::DirBuilderExt; + std::fs::DirBuilder::new().mode(0o700).create(path).unwrap(); +} + pub fn bytes(n: usize) -> Vec { format!("complete installed file {n:06}\n").into_bytes() } From 7bbe6811ce8888c35b797219ad859982a9b1d65e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:23:06 +0000 Subject: [PATCH 10/11] fix(doctor): stop descending into a symlinked Store entry (#570 P1 review R2) When `store_names` began enumerating symlinks under `home/store`, `store()` reported the symlink finding in `store_folder()` but still descended into `record.json` and `project/`. A symlink pointing to a regular file caused `paths::names(&projects)` to fail with ENOTDIR, aborting `scan()` and discarding the entire doctor report. `store_folder()` now returns whether the path is a symlink so `store()` stops descending after reporting it and continues scanning remaining Stores; `store_names()` also sorts entries for deterministic output. Added regression tests for a regular-file symlink and a dangling symlink under `home/store` alongside another Store finding. True first-parent Production LOC disclosure for merge commit 3f039a74a (history preserved without rewriting; 3f039a74a's own message erroneously compared against second parent af2ad92bc, 159977 -> 160145, delta +168): 82eb09f64 -> 3f039a74a: 159375 -> 160145 (delta +770); core 39787 -> 39787 (0), engine 74495 -> 74500 (+5), control 39480 -> 39882 (+402), api 5613 -> 5976 (+363); reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). Production LOC: 160194 -> 160198 (delta +4) Scope and method: first-parent comparison (parent affb55b6c, this commit's tree). First-party production Rust/SQL/JavaScript/Python in core, engine, control and api; tests, fixtures, tools, docs, manifests/lockfiles and generated artifacts excluded. Counted with tools/production_loc.py --detail on exported parent tree affb55b6c and committed tree: control 39925 -> 39929 (+4); core 39787, engine 74506 and api 5976 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../crates/layerfs-control/src/doctor/scan.rs | 13 ++- .../crates/layerfs-control/tests/doctor.rs | 108 ++++++++++++++++++ 2 files changed, 117 insertions(+), 4 deletions(-) diff --git a/control/crates/layerfs-control/src/doctor/scan.rs b/control/crates/layerfs-control/src/doctor/scan.rs index 0d6a238526..bb933ed7f6 100644 --- a/control/crates/layerfs-control/src/doctor/scan.rs +++ b/control/crates/layerfs-control/src/doctor/scan.rs @@ -58,6 +58,7 @@ fn store_names(dir: &Path) -> Result> { } } } + names.sort(); Ok(names) } @@ -102,7 +103,9 @@ pub(super) fn scan(home: &Path, findings: &mut Findings) -> Result { /// One Store's folder: its record and its projects'. fn store(home: &Path, name: &str, scanned: &mut Scanned, findings: &mut Findings) -> Result<()> { let entity = ("store", name); - store_folder(&paths::store_dir(home, name), entity, findings); + if store_folder(&paths::store_dir(home, name), entity, findings) { + return Ok(()); + } let path = paths::store_record(home, name); let has_record = path.exists(); if has_record { @@ -329,10 +332,11 @@ fn folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { /// A Store's own folder is held to the daemon's rule (kernel_guard): no /// group or other bits at all, not even pass-through, so a folder doctor -/// calls fine is one the daemon opens. -fn store_folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { +/// calls fine is one the daemon opens. Returns whether `path` is a symlink +/// (already reported, so the caller stops descending into this entry). +fn store_folder(path: &Path, entity: (&str, &str), findings: &mut Findings) -> bool { if link(path, entity, findings) { - return; + return true; } if let Some(mode) = mode(path).filter(|mode| mode & 0o077 != 0) { findings.error( @@ -344,6 +348,7 @@ fn store_folder(path: &Path, entity: (&str, &str), findings: &mut Findings) { format!("`chmod 700 {}`", path.display()), ); } + false } /// A record file others or its group may read is an error. diff --git a/control/crates/layerfs-control/tests/doctor.rs b/control/crates/layerfs-control/tests/doctor.rs index 485d282112..f7de118a84 100644 --- a/control/crates/layerfs-control/tests/doctor.rs +++ b/control/crates/layerfs-control/tests/doctor.rs @@ -230,6 +230,114 @@ fn a_symlinked_store_entry_is_an_error_that_does_not_change_the_target() { std::fs::remove_dir_all(home).unwrap(); } +#[test] +fn a_symlink_to_a_file_under_store_does_not_abort_other_findings() { + // `store/` linked to a regular file: must not fail `read_dir(.../project)` + // with ENOTDIR and discard findings for the rest of the home + let home = new_home("store-entry-file-link"); + layerfs_control::migrate::open(&home).unwrap(); + let native = SdkValue::map([("name", t("native")), ("platform", t("native"))]); + write_entity(&paths::machine_record(&home, "native"), &native).unwrap(); + store(&home, "other", sqlite("other", "native")); + std::fs::set_permissions( + paths::store_dir(&home, "other"), + std::fs::Permissions::from_mode(0o701), + ) + .unwrap(); + let target = std::env::temp_dir().join(format!("layerfs-doctor-file-{}", std::process::id())); + let _ = std::fs::remove_file(&target); + std::fs::write(&target, b"keep").unwrap(); + std::fs::set_permissions(&target, std::fs::Permissions::from_mode(0o644)).unwrap(); + let link = paths::store_dir(&home, "shop"); + std::os::unix::fs::symlink(&target, &link).unwrap(); + + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(false)), "{report:?}"); + let found = findings(&report); + assert_eq!(found.len(), 2, "{found:#?}"); + assert_eq!( + ( + found[0].0.as_str(), + found[0].1.as_str(), + found[0].2.as_str() + ), + ("error", "store", "other") + ); + assert!(found[0].3.contains("0701"), "{found:#?}"); + assert_eq!( + ( + found[1].0.as_str(), + found[1].1.as_str(), + found[1].2.as_str() + ), + ("error", "store", "shop") + ); + assert!(found[1].3.contains("symlink"), "{found:#?}"); + assert!(!found[1].4.contains("chmod"), "{found:#?}"); + + assert!(std::fs::symlink_metadata(&link) + .unwrap() + .file_type() + .is_symlink()); + assert_eq!(std::fs::read_link(&link).unwrap(), target); + let target_meta = std::fs::symlink_metadata(&target).unwrap(); + assert!(target_meta.file_type().is_file()); + assert_eq!(target_meta.permissions().mode() & 0o7777, 0o644); + assert_eq!(std::fs::read(&target).unwrap(), b"keep"); + + std::fs::remove_file(&link).unwrap(); + std::fs::remove_file(&target).unwrap(); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn a_dangling_symlink_under_store_is_an_error_that_keeps_scanning() { + let home = new_home("store-entry-dangling-link"); + layerfs_control::migrate::open(&home).unwrap(); + let native = SdkValue::map([("name", t("native")), ("platform", t("native"))]); + write_entity(&paths::machine_record(&home, "native"), &native).unwrap(); + store(&home, "other", sqlite("other", "native")); + std::fs::set_permissions( + paths::store_dir(&home, "other"), + std::fs::Permissions::from_mode(0o701), + ) + .unwrap(); + let missing = + std::env::temp_dir().join(format!("layerfs-doctor-missing-{}", std::process::id())); + let _ = std::fs::remove_file(&missing); + let link = paths::store_dir(&home, "dangling"); + std::os::unix::fs::symlink(&missing, &link).unwrap(); + + let report = doctor(&home).unwrap(); + assert_eq!(report.get("ok"), Some(&SdkValue::Bool(false)), "{report:?}"); + let found = findings(&report); + assert_eq!(found.len(), 2, "{found:#?}"); + assert_eq!( + ( + found[0].0.as_str(), + found[0].1.as_str(), + found[0].2.as_str() + ), + ("error", "store", "dangling") + ); + assert!(found[0].3.contains("symlink"), "{found:#?}"); + assert!(!found[0].4.contains("chmod"), "{found:#?}"); + assert_eq!( + ( + found[1].0.as_str(), + found[1].1.as_str(), + found[1].2.as_str() + ), + ("error", "store", "other") + ); + assert!(found[1].3.contains("0701"), "{found:#?}"); + assert_eq!(std::fs::read_link(&link).unwrap(), missing); + assert!(!missing.exists()); + + std::fs::remove_file(&link).unwrap(); + std::fs::remove_dir_all(home).unwrap(); +} + #[test] fn a_home_that_does_not_exist_is_ok_and_stays_absent() { let home = new_home("absent"); From aef328188c868b7b20f99174eb07eb660b812d39 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 08:46:31 +0000 Subject: [PATCH 11/11] docs(store,doctor): port Store 0700, doctor symlink and macOS exec env notes to rebuilt docs Ported the substantive documentation updates from the 10 architecture pages deleted by upstream #671 into their rebuilt replacements: - api/sdk/backup.md & control/backups/README.md: backup.restore runs the kernel guard before staging and again under the home lock before install, and install::make_private_directory reclaims only this call's own mkdir - api/sdk/project.md & api/sdk/store.md: kernel guard 0700 directory rule and make_empty own-mkdir reclamation semantics - api/sdk/workspace.md & control/sandboxes/daemon-channel-and-exec.md: macOS HostProcess RUSTUP_HOME/CARGO_HOME/GIT_CONFIG_GLOBAL passthrough and host toolchain mutability note - control/doctor/checks.md: Store folder 0700 rule (0701 refused) and symlink reporting without descending or suggesting chmod - control/stores-and-projects/README.md, engine/daemon/README.md & engine/store-calls/README.md: kernel guard 0700 directory checks and daemon private_directory error format Production LOC: 160198 -> 160198 (delta 0) Scope and method: first-parent comparison (parent f1cdbb4ed, this commit's tree). First-party production Rust/SQL/JavaScript/Python in core, engine, control and api; tests, fixtures, tools, docs, manifests/lockfiles and generated artifacts excluded. Counted with tools/production_loc.py --detail: core 39787, engine 74506, control 39929 and api 5976 unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/api/sdk/backup.md | 7 ++++++- docs/architecture/api/sdk/project.md | 6 +++--- docs/architecture/api/sdk/store.md | 17 ++++++++++++----- docs/architecture/api/sdk/workspace.md | 2 +- docs/architecture/control/backups/README.md | 8 ++++---- docs/architecture/control/doctor/checks.md | 3 ++- .../sandboxes/daemon-channel-and-exec.md | 1 + .../control/stores-and-projects/README.md | 4 ++-- docs/architecture/engine/daemon/README.md | 2 +- docs/architecture/engine/store-calls/README.md | 4 ++-- 10 files changed, 34 insertions(+), 20 deletions(-) diff --git a/docs/architecture/api/sdk/backup.md b/docs/architecture/api/sdk/backup.md index 776846a91b..b29cda6831 100644 --- a/docs/architecture/api/sdk/backup.md +++ b/docs/architecture/api/sdk/backup.md @@ -150,6 +150,11 @@ CLI layerfs backup restore [] [--progress] ``` `file` defaults to the file the Store's link names, else the Store's name. +If `store/` already exists, it runs `store.create`'s kernel guard +before staging anything and again under the home lock before the install +(`backup::restore::install`), refusing `Unsupported` (with `chmod 700`) if +the folder is not a real `0700` directory of this user on a local +filesystem. Phases: `check`, `download` (bytes, pieces), `verify` (the bytes open as the Store), `install`. `projects` lists the projects the restored file holds; their records are rebuilt and records of projects it lacks are removed. It @@ -162,7 +167,7 @@ is `Conflict`: read `store.get` first | Error | When | | --- | --- | -| `Unsupported` | the Store to replace is not on `native` | +| `Unsupported` | `store/` already exists and is not the daemon's private `0700` directory (checked before staging and again under the home lock before the install); or the Store to replace is not on `native` | | `InUse` | a process holds the Store, a Sandbox of it is recorded, or its `-wal`/`-shm` exists | | `Conflict` | the Store changed since its last transfer through this bucket, has no link, or was replaced during the download | | `Exists` | a Store of that name was made during the download | diff --git a/docs/architecture/api/sdk/project.md b/docs/architecture/api/sdk/project.md index 71519f1b80..e300021835 100644 --- a/docs/architecture/api/sdk/project.md +++ b/docs/architecture/api/sdk/project.md @@ -74,7 +74,7 @@ Branch's base) and `root` (that Branch's effective root) | Store | Runs in | | --- | --- | | PostgreSQL | caller's process (a build with the `postgresql` feature) | -| sqlite on a locally executing machine (`native` on Linux or macOS) | caller's process; the kernel guard admits only Linux ext4, xfs or btrfs, or macOS apfs or hfs | +| sqlite on a locally executing machine (`native` on Linux or macOS) | caller's process; the kernel guard admits the Store's directory only when it is owned by this user and private (`0700`) on Linux ext4, xfs or btrfs, or macOS apfs or hfs | | sqlite on any other machine, and `native` on Windows | that machine's worker, on a staged copy of the folder sent from the caller | | Error | When | Source | @@ -84,7 +84,7 @@ Branch's base) and `root` (that Branch's effective root) | `Exists` | the project's record, entry or LayerStack name exists | `project/family.rs`, [`identity.rs`](../../../../control/crates/layerfs-store/src/identity.rs) | | `Busy` | also when another add's working rows remain in the Store | `identity.rs` `add_failure` | | `Capacity` | worker route: the machine's free disk is below the copy plus headroom | `project/send.rs` `room` | -| `Unsupported` | the kernel guard refuses the Store's filesystem; PostgreSQL in a build without `postgresql` | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| `Unsupported` | the kernel guard refuses the Store's directory (non-private mode/owner/type or unsupported filesystem); PostgreSQL in a build without `postgresql` | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | `NoStore` | no Store file at the Store's path | `identity.rs` | | `Failed` | deadline passed, read error or any other engine failure, **including an Init whose outcome is unknown**; the entry this call made is kept | `identity.rs` `add_failure` | | `Unknown` | worker route: a stage or the `project.init` answer was lost; the home gains no record, and the worker removes its staged copy when its Init ends | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | @@ -254,7 +254,7 @@ under the Store's lease, locally or as the worker operation `project.remove`. | --- | --- | --- | | `NoSuchProject` | also when the Store holds no LayerStack of that name | [`identity.rs`](../../../../control/crates/layerfs-store/src/identity.rs) | | `InUse` | a Sandbox of the project is recorded; `detail.related` lists `{ kind: "sandbox", name }` | [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | -| `Unsupported` | a PostgreSQL Store ("removing a project from a PostgreSQL Store is not built"); the kernel guard refuses the Store's filesystem | [`project/family.rs`](../../../../control/crates/layerfs-store/src/project/family.rs) | +| `Unsupported` | a PostgreSQL Store ("removing a project from a PostgreSQL Store is not built"); the kernel guard refuses the Store's directory when opened (non-private mode/owner/type — another user's directory or group/other access instead of `0700` — or unsupported filesystem) | [`project/family.rs`](../../../../control/crates/layerfs-store/src/project/family.rs) | | `Failed` | the Store write failed, its outcome included | `identity.rs` `remove_project` | | `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | diff --git a/docs/architecture/api/sdk/store.md b/docs/architecture/api/sdk/store.md index efca03c22a..9ecdbe155b 100644 --- a/docs/architecture/api/sdk/store.md +++ b/docs/architecture/api/sdk/store.md @@ -172,14 +172,21 @@ CLI layerfs store create Returns `{ name, kind: "sqlite", machine: "native", profile: "disposable", created, sqlite, projects: [] }`. Under the home lock (waits up to 120 s) -the call makes `store//` (0700), builds the empty file as -`store.sqlite.creating` (0600) and renames it to `store.sqlite`; a failure -before the record is written removes the call's folder +the call makes `store/` (`0700`), creates `store//` (`0700`) when +absent and checks `store//store.sqlite` with `kernel_guard::check` +before building the empty file as `store.sqlite.creating` (`0600`) and +renaming it to `store.sqlite`. A failure of `make_empty` removes +`store//` only when this call's own `mkdir` made it (a pre-existing +folder or one made by another caller is never removed); once `make_empty` +succeeds, a `save_record` failure keeps the Store file and folder ([`sqlite/create.rs`](../../../../control/crates/layerfs-store/src/sqlite/create.rs), [`identity.rs`](../../../../control/crates/layerfs-store/src/identity.rs)). To place it elsewhere, create it and then push it. Errors: `Exists` (a -record of that name, of either kind, or a file at the target); `Unavailable` -(a lock held 120 s); `Failed`. +record of that name, of either kind, or a file at the target); +`Unsupported` (the kernel guard refuses `store//`: not on a local +lock-carrying filesystem, or an existing directory is not owned by this +user, is a symlink, or has group/other access instead of `0700`); +`Unavailable` (a lock held 120 s); `Failed`. ### store.connect diff --git a/docs/architecture/api/sdk/workspace.md b/docs/architecture/api/sdk/workspace.md index 4fac960411..d7352dead2 100644 --- a/docs/architecture/api/sdk/workspace.md +++ b/docs/architecture/api/sdk/workspace.md @@ -90,7 +90,7 @@ CLI layerfs workspace exec [--message ] [--stream] [ | Argument | Kind | Rule | | --- | --- | --- | -| `command` | Text | `bash -c ` as the Sandbox's command identity, `HOME` its scratch folder ([`exec/run.rs`](../../../../control/crates/layerfs-sandbox/src/exec/run.rs)) | +| `command` | Text | `bash -c ` as the Sandbox's command identity, `HOME` its scratch folder (on macOS `native`, `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` default to the caller's when present; override in the caller's environment or the command) ([`exec/run.rs`](../../../../control/crates/layerfs-sandbox/src/exec/run.rs)) | | `message` option | Text | echoed in the answer; no Commit is made | | `stream` option | Bool | pass output to this process's stdout and stderr when no functions are given (CLI `--stream`) | | `stdout`, `stderr` options | Function | receive each output event's text, or bytes when not UTF-8; never reach the library | diff --git a/docs/architecture/control/backups/README.md b/docs/architecture/control/backups/README.md index 094b3122c1..0f77d28f7d 100644 --- a/docs/architecture/control/backups/README.md +++ b/docs/architecture/control/backups/README.md @@ -76,12 +76,12 @@ A PostgreSQL Store is not backed up here. | # | Step | Source | | --- | --- | --- | -| 1 | Existing Store: refuse PostgreSQL; under the home lock and the Store's lock check `replaceable`: on `native`, no unfinished operation, this process's open copy closed, no other lease holder or running Sandbox (`store_idle`), heads equal to the link's, no `-wal` or `-shm`. Then hold its lease. A new Store gets a fresh cursor key. | [`restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs), [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | +| 1 | Existing `store/` folder (if present): `store.create`'s kernel guard requires a real `0700` directory of this user (`Unsupported`, `chmod 700` before any staging). Existing Store: refuse PostgreSQL; under the home lock and the Store's lock check `replaceable`: on `native`, no unfinished operation, this process's open copy closed, no other lease holder or running Sandbox (`store_idle`), heads equal to the link's, no `-wal` or `-shm`. Then hold its lease. A new Store gets a fresh cursor key. | [`restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs), [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | | 2 | Make `store/.restore-/` with a held `lock` file; first remove older restore folders whose lock can be taken (killed restores). | same, `Staging`, `sweep` | -| 3 | `load` into it: kernel guard on the folder, installer is the daemons' user, no Store at the target, no sidecars; stat the object and take `layerfs-binding`; download to `.pulling` (0600, create-new) through `pieces::download`. | [`restore.rs` (bucket)](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | +| 3 | `load` into it: `installer_user` (daemons' user), make the destination directory `0700` when absent (`install::make_private_directory`), `kernel_guard` on the Store file (a guard refusal removes only the still-empty directory this call's `mkdir` made; installer-user or `mkdir` failure removes nothing), no Store at the target, no sidecars; stat the object and take `layerfs-binding`; download to `.pulling` (0600, create-new) through `pieces::download`. | [`restore.rs` (bucket)](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | | 4 | `verify`: open the bytes as a Disposable Store with that binding and cursor key, close, read heads, require no `-wal`/`-shm` left; `install`: hard link into place. | same | | 5 | The binding must be the existing Store's. Read the Store's projects on a connection of the call's own. | [`restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs), `projects_in` | -| 6 | Home lock: a new Store is hard-linked (never over one that appeared); an existing one is re-checked and renamed over. Write the link and project records; remove records of projects the Store no longer holds. The staging folder goes when the call ends. | same, `write_projects` | +| 6 | Home lock: re-check the target's folder with the kernel guard (`backup::restore::install`) so a folder that appeared or lost its privacy during the download is refused `Unsupported` with nothing installed; a new Store is hard-linked (never over one that appeared), an existing one is re-checked and renamed over. Write the link and project records; remove records of projects the Store no longer holds. The staging folder goes when the call ends. | same, `write_projects` | The download and its checks run before the home lock; the lock covers only the re-checks, the install and the record writes. A restore opens the bytes @@ -121,7 +121,7 @@ Bucket errors map to call refusals: `Uncertain` is `Unknown`, `Invalid` is | Create: snapshot fails | `Failed` "snapshot: …" | [`steps.rs`](../../../../control/crates/layerfs-store/src/sqlite/transfer/steps.rs) | | Create: fetched worker copy differs | `Failed` "the staged copy is not the snapshot the worker made" | [`create.rs`](../../../../control/crates/layerfs-store/src/backup/create.rs) | | Create: a request's answer is lost | `Unknown`; the object may or may not be replaced; not resent | [`record.rs`](../../../../control/crates/layerfs-store/src/backup/record.rs) | -| Restore over a Store not on `native` | `Unsupported`; move it there first | `replaceable` in [`restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs) | +| Restore over a Store not on `native`, or into a non-private `store/` folder | `Unsupported`; move to `native` or `chmod 700` the Store's folder (checked before staging and again under the home lock before install) | `replaceable`, `install` in [`restore.rs`](../../../../control/crates/layerfs-store/src/backup/restore.rs) | | Restore over a changed Store | `Conflict`; back it up first or restore under a new name | same | | Restore over an open Store (lease holder, Sandbox, `-wal`/`-shm`) | `InUse` | same; [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | | Restore: any load check (missing object, no binding, sha256, open) | `Failed` naming the check, e.g. "no Store `` on the remote: remote file missing"; the staging folder is removed | [`restore.rs` (bucket)](../../../../control/crates/layerfs-bucket/src/backup/restore.rs) | diff --git a/docs/architecture/control/doctor/checks.md b/docs/architecture/control/doctor/checks.md index 725594ff9d..b5b6ac634c 100644 --- a/docs/architecture/control/doctor/checks.md +++ b/docs/architecture/control/doctor/checks.md @@ -58,7 +58,8 @@ without options. | --- | --- | --- | | each record | `error` when it does not parse ("repair or remove it by hand"), or when an entity record's `v` is not 1 ("use the LayerFS build that wrote it") | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `record` | | record file mode | `error` when group or others may read it; fix `chmod 600 ` | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `file_mode` | -| folder mode | `error` when others may list or change it or its group may use it (0701 is allowed, for a namespaces Sandbox); fix `chmod g-rwx,o-rw ` | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `folder` | +| folder mode | `error` when others may list or change it or its group may use it (0701 is allowed, for a namespaces Sandbox, except on a Store's own folder; a symlink is reported as a link with `make it a real folder`, never `chmod`, which would change the target); fix `chmod g-rwx,o-rw ` | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `folder`, `link` | +| Store folder mode | `error` when a Store's own folder has any group or other bit (`0701` is not allowed; fix `chmod 700 `) or is a symlink (scanned under `store/`, reported without descending into `record.json` or `project/`, and without suggesting `chmod`) | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `store_folder`, `store_names` | | Store folder | `error` on each project in a Store folder with no Store record; fix: restore the record or delete the folder by hand | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `store` | | Workspace folder | `warning` for `workspace//` with no `.json` beside it; fix: its Workspace was unmounted, remove the folder by hand | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `execs` | | command record | `warning` when its owner process is gone; fix `layerfs workspace exec-cancel : `, or the Workspace's unmount or the Sandbox's close; `error` when a file under `exec/` does not read as one | [`scan.rs`](../../../../control/crates/layerfs-control/src/doctor/scan.rs) `execs` | diff --git a/docs/architecture/control/sandboxes/daemon-channel-and-exec.md b/docs/architecture/control/sandboxes/daemon-channel-and-exec.md index cf0308755a..0fe217ae48 100644 --- a/docs/architecture/control/sandboxes/daemon-channel-and-exec.md +++ b/docs/architecture/control/sandboxes/daemon-channel-and-exec.md @@ -95,6 +95,7 @@ No step is retried, rebound or re-attached on the caller's behalf. | Item | Rule | Source | | --- | --- | --- | | Exec record | `/workspace//exec/.json`: `{ v, id, workspace, path, name, owner, route, stop, started, cancel? }`. `owner` is pid, start time and boot; `route` is `local` or `machine:`; `stop` is null until spawn. Kept on the side that keeps the Workspace's record. | [`exec/record.rs`](../../../../control/crates/layerfs-sandbox/src/exec/record.rs) | +| Environment | Caller variables are cleared except `PATH`; on macOS `HostProcess` (`native`), `RUSTUP_HOME`, `CARGO_HOME` and `GIT_CONFIG_GLOBAL` are passed from the caller's environment or `HOME` (`~/.rustup`, `~/.cargo`, `~/.gitconfig` or XDG `git/config`) when present and not overridden by `request.environment`. Those are the caller's own writable directories, not copies, so `cargo install`, `rustup update` or git writes change the host toolchain. | [`host_process/exec.rs`](../../../../control/crates/layerfs-sandbox-backend/src/backend/host_process/exec.rs) | | Duplicate id | A live record of the id is `Exists`, found by path, with no scan. | `Running::start` | | Stop handle | `{ cgroup: { path } }` (namespaces: `/ws-/exec-`) or `{ group: { pgid, pid, pid_start, pid_boot } }` (native); written only once the command runs in it. | `stop_value` in `exec/record.rs`, [Backends](backends.md#stoprs-stop-handles) | | Output | Each stream kept in memory up to 1 MiB (`INLINE`), then spilled to an unlinked file; read back in pages of at most 1 MiB until released. The backend reads the pipe only as fast as the spool takes it (8 KiB windows). `truncated` is always false. | [`output.rs`](../../../../control/crates/layerfs-sandbox/src/output.rs), [`exec/run.rs`](../../../../control/crates/layerfs-sandbox/src/exec/run.rs) | diff --git a/docs/architecture/control/stores-and-projects/README.md b/docs/architecture/control/stores-and-projects/README.md index f2f102c052..b14bdba469 100644 --- a/docs/architecture/control/stores-and-projects/README.md +++ b/docs/architecture/control/stores-and-projects/README.md @@ -100,7 +100,7 @@ refusal names the clearing call: a new `store push ` or `store pull | The Store lock is taken after the home lock, never before, and never held across a worker call or byte transfer | [`record.rs`](../../../../control/crates/layerfs-store/src/record.rs) `lock` | | No call starts a machine: a worker not recorded or not answering is `Unavailable`, naming `layerfs machine start` | [`place.rs`](../../../../control/crates/layerfs-store/src/place.rs) | | A guest never reads the home: the caller sends the Store's record with each call; the worker finds the file under its own root by name | [`call.rs`](../../../../control/crates/layerfs-store/src/call.rs), [`worker_server.rs`](../../../../control/crates/layerfs-control/src/worker_server.rs) | -| Direct Store access only where every opener shares one kernel and a local filesystem: Linux ext4, xfs, btrfs; macOS apfs, hfs; else every Store call is `Unsupported` with its reason, no fallback | [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs), [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| Direct Store access only where the Store's own directory is a real `0700` directory owned by this user and every opener shares one kernel and a local filesystem: Linux ext4, xfs, btrfs; macOS apfs, hfs; else every Store call is `Unsupported` with its reason, no fallback | [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs), [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | One attempt per call; nothing is resent | [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs), [`place.rs`](../../../../control/crates/layerfs-store/src/place.rs) | | Store records are created with `profile: disposable` (Disposable/WAL/synchronous=OFF, the only permitted profile); Durable execution is `NOT_RUN — disabled by owner until explicit reauthorization` | [`record.rs`](../../../../control/crates/layerfs-store/src/record.rs) `created_on_native`, `restored` | @@ -113,7 +113,7 @@ refusal names the clearing call: a new `store push ` or `store pull | Store lock held | `Unavailable` after 120 s | [Home](../home/README.md#locks-and-leases) | | Leased or used by a Sandbox (push, pull, remove, disconnect, restore) | `InUse`, `detail.related` lists `{kind: "lease", name: }` and `{kind: "sandbox", name}` | [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) `store_idle` | | Open-Store idle close | 60 s (`IDLE`); a Store with a call running is never closed (`close` refuses `InUse`) | [`open.rs`](../../../../control/crates/layerfs-store/src/open.rs) | -| Store kernel guard | `Unsupported`, naming the filesystem | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| Store kernel guard | `Unsupported`, naming the directory requirement (`0700` owned by this user, not missing/symlink) or filesystem | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | Store file missing | `NoStore` | [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs) | ## Demonstration diff --git a/docs/architecture/engine/daemon/README.md b/docs/architecture/engine/daemon/README.md index 5b133f5b72..4697766de6 100644 --- a/docs/architecture/engine/daemon/README.md +++ b/docs/architecture/engine/daemon/README.md @@ -56,7 +56,7 @@ layerfs-daemon --config | --- | --- | --- | | Takes one argument | `--config `; argv and env carry no key and no command ("no launcher or shell command mode") | [`application/cli.rs`](../../../../engine/crates/layerfs-daemon/src/application/cli.rs) | | Checks the config | Opened `O_NOFOLLOW`; regular file owned by the daemon user, no group/other bits, private directory; at most 8 192 bytes; one `DaemonSetup` record | [`application/config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | -| Separates identities and paths | `command_uid` differs from the daemon uid (except on NFS); Store, overlay and config sit outside the mount home in private `0700` directories; the Store is not the overlay file; `serial_low_water` below `SERIAL_REFILL` | [`application/config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | +| Separates identities and paths | `command_uid` differs from the daemon uid (except on NFS); Store, overlay and config sit outside the mount home in private `0700` directories (failing with `private directory ownership/mode/type at : …` and a `chmod 700` hint on mode errors); the Store is not the overlay file; `serial_low_water` below `SERIAL_REFILL` | [`application/config.rs`](../../../../engine/crates/layerfs-daemon/src/application/config.rs) | | Chooses the route | `fuse` or `nfs`; macOS accepts only `nfs` | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) | | Starts the overlay owner | Creates and closes the overlay template (`pager_kib`, `namespaces`); every later start failure is `AfterOverlay`, keeping the owner | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs), [Overlay](../overlay/README.md) | | Takes a fresh incarnation | `generate_keypair()`; the public half is `DaemonStatus.instance` | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs) | diff --git a/docs/architecture/engine/store-calls/README.md b/docs/architecture/engine/store-calls/README.md index 0a80d2974b..71bfec018f 100644 --- a/docs/architecture/engine/store-calls/README.md +++ b/docs/architecture/engine/store-calls/README.md @@ -50,7 +50,7 @@ Commits use; those are described under [Commit](../commit/README.md) and | --- | --- | --- | | One route, in the caller's process | `fs.*`, `branch.*`, `project.*` and `store.stats` run on this engine in the process that opened the Store. There is no daemon route for them and no fallback. | [`lib.rs`](../../../../engine/crates/layerfs-store-service/src/lib.rs), [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs) | | Daemon serves only Workspace calls | Mount, exec, Workspace Commit, status and unmount go to a Sandbox daemon; the daemon reuses this crate's `store` and `overlay` modules, not `StoreService`. | [`store_service.rs`](../../../../engine/crates/layerfs-store-service/src/store_service.rs), [Daemon](../daemon/README.md) | -| Kernel guard first | Before any file opens, `kernel_guard::check` reads the platform and the filesystem type of the Store's directory. Linux: ext4, xfs, btrfs. macOS: apfs or hfs (native Sandbox, one shared macOS kernel). Anything else: `OpenRefusal::Unsupported` with its reason. | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| Kernel guard first | Before any file opens or is created, `kernel_guard::check` verifies without modifying permissions that the Store's own directory (`store.parent()`, or `.` when empty) exists as a real `0700` directory owned by the current effective user (refusing a missing path, a symlink, wrong owner or `mode & 0o077 != 0` with a `chmod 700` hint) and checks the filesystem type. Linux: ext4, xfs, btrfs. macOS: apfs or hfs (native Sandbox, one shared macOS kernel). Anything else: `OpenRefusal::Unsupported` with its reason. | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | macOS and Windows hosts | A process that cannot open the Store under the guard sends its Store calls to a loopback worker: a Linux process (a container on macOS, a WSL2 distribution on Windows) that runs this same engine and opens the Store directly. The engine knows no worker. | [Control: Workers and reach](../../control/machines/workers-and-reach.md) | | PostgreSQL | `open_postgres` (feature `postgresql`) runs no kernel guard: the Store is a server reached over a connection. Without the feature a PostgreSQL selection fails `BackendUnavailable`. | [`store_service.rs`](../../../../engine/crates/layerfs-store-service/src/store_service.rs), [`bootstrap.rs`](../../../../engine/crates/layerfs-store-service/src/bootstrap.rs) | @@ -195,7 +195,7 @@ not in `methods::call`, and in this repository only tests call it. | Limit or failure | Value or error | Source | | --- | --- | --- | -| Unsupported platform or filesystem | `OpenRefusal::Unsupported`, nothing opened | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| Unsupported directory, platform or filesystem | `OpenRefusal::Unsupported`, nothing opened or created | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | | Store file absent | `OpenRefusal::Missing` | [`store_service.rs`](../../../../engine/crates/layerfs-store-service/src/store_service.rs) | | Private Workspaces per process | 64; then `Capacity` | same | | Overlay maintenance stopped | `bind` refuses | same |