diff --git a/capsules/browser/browser/browser-status.js b/capsules/browser/browser/browser-status.js index 599393c62..7e705b545 100644 --- a/capsules/browser/browser/browser-status.js +++ b/capsules/browser/browser/browser-status.js @@ -71,6 +71,9 @@ export function friendlyOpenError(error) { : "This browser cannot show the Browser session. Use a supported browser or enable WebRTC."; } if (outcome?.state === "terminal_pre_effect_failure" && error?.payload?.stage === "engine_readiness") { + if (error?.payload?.code === "browser_host_setup_required") { + return sanitizedErrorText({ message: error.payload.message || text }); + } switch (error?.payload?.reason) { case "artifact_invalid": return "Browser Engine files need repair. Prepare this Engine or choose another approved Engine."; diff --git a/capsules/browser/browser/browser-status.test.mjs b/capsules/browser/browser/browser-status.test.mjs index 75f12c1ae..6bb8d1eda 100644 --- a/capsules/browser/browser/browser-status.test.mjs +++ b/capsules/browser/browser/browser-status.test.mjs @@ -260,6 +260,20 @@ test("readiness failures explain the repair while cleanup retains priority", () } }); +test("Linux host setup guidance names the opt-in command", () => { + const error = openError("terminal_pre_effect_failure"); + Object.assign(error.payload, { + stage: "engine_readiness", + code: "browser_host_setup_required", + message: "Browser is available on this computer. To turn it on, run: elastos setup --browser. Then close Home and start it again with elastos home --browser.", + }); + assert.equal(friendlyOpenError(error), error.payload.message); + error.payload.message = "Browser needs KVM on this computer. After KVM is available, run: elastos setup --browser. Then close Home and start it again with elastos home --browser."; + assert.equal(friendlyOpenError(error), error.payload.message); + error.payload.outcome.state = "cleanup_pending"; + assert.doesNotMatch(friendlyOpenError(error), /elastos setup --browser/); +}); + test("one-page capacity refusal says only one Browser window can be open", () => { for (const state of ["terminal_pre_effect_failure", "terminal_post_effect_cleanup"]) { const error = openError(state); diff --git a/docs/BROWSER_VM_TARGET.md b/docs/BROWSER_VM_TARGET.md index d35c7fe45..965840303 100644 --- a/docs/BROWSER_VM_TARGET.md +++ b/docs/BROWSER_VM_TARGET.md @@ -483,22 +483,32 @@ guest and viewer allocations meet; loopback, private ranges and every other peer are denied, and TCP relays are off. coturn checks peer IPs only, so the relay output rule above confines relayed UDP to the TURN ports; host services on the slot IP stay unreachable. `check` refuses a receipt without that rule. -`elastos setup` writes the Home's TURN credential to the +`elastos setup --browser` writes the Linux Home's TURN credential to the owner-only `$DATA_DIR/runtime-turn/turn-credentials.env` and keeps an existing one. -For removal, use the same root shell and helper: +The Linux installer leaves Browser host access and its image to the Home owner. +On a supported Linux ARM64 host with KVM, run `elastos setup --browser` from a +terminal. This command admits the signed helpers, runs the one-time administrator +setup above, checks host access, then downloads and verifies the image with +progress. The administrator helper shows its changes and asks for confirmation. +Ordinary `elastos setup` leaves the Linux Browser image untouched. Close Home +and start it again after enabling Browser. Browser open explains this command +on an unprepared host; after setup it prepares a missing image on demand. +Apple Silicon setup keeps its existing Browser preparation behavior. + +For removal, close Browser and run this as the Home user before uninstalling: ```sh -python3 /usr/local/lib/elastos/browser-vm-linux-network.py remove --user +sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)" ``` After confirmation, removal deletes this account's TAPs, filter hooks/chains, boot service, udev rule, locks and receipts. It restores the prior named KVM ACL, or removes the grant created by setup. The shared root helper is removed when the last account's setup is removed. Other host firewall rules stay with -their owner. `install.sh` integration is a separate change; the installer can -call the exact setup command above as its approved root step. +their owner. Runtime and the installer leave these administrator operations +to the explicit Browser setup and removal commands. ### Linux operator proof @@ -562,8 +572,9 @@ generator/stager for: - verified links to an existing rootfs, kernel, initrd and matching build manifest Linux uses the native supervisor and a disposable qcow2 overlay for each -launch. The installer removes the retired `browser-vm/rootfs-pool` image copies -as their ordinary owner and reports the removed path. +launch. Linux Browser preparation belongs to `elastos setup --browser`. +That command removes retired `browser-vm/rootfs-pool` image copies as their +ordinary owner before preparing Browser. For already-provisioned targets, `scripts/browser-vm-target-refresh.sh` is the host-helper maintenance path. Guest drift requires a rebuilt image set. Runtime diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 5a7a7632f..48d370b3e 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -87,7 +87,9 @@ stop after bootstrap. The current default Home exposes Assistant, Chat (Community), System, People, Wallet, Documents, Library, Marketplace, and Inbox. On Apple Silicon -Macs it also exposes Browser; Linux Homes do not show Browser in 2.0.0. People is installed as a +Macs it also exposes Browser. On supported Linux ARM64 computers with KVM, +Browser is optional; see [Jetson](#jetson) for `elastos setup --browser`. +People is installed as a separate app capsule; Home presents it but does not own its state or authority. Native Windows is not an accepted install target today. The current product @@ -173,20 +175,27 @@ The installer detects Linux `aarch64`: curl -fsSL https://elastos.elacitylabs.com/install.sh | bash ``` -Home and chat use the ordinary user account. Browser runs on Apple Silicon Macs -and uses the local Engine's virtual machine. When the signed release supplies -Browser support, setup obtains its matching helpers and verified image before -Home starts. The image streams to disk with progress; a transfer stops after 30 -seconds without data. Runtime keeps the committed Browser profile separate from -the image during reopen and updates. - -On other computers, including Linux ARM64 (Jetson) and Linux x86-64, Browser is -hidden until the next release; setup prints "Browser is not available on this -computer yet." Setup also clears the Browser Engine selection and removes the -Browser host helpers and image an earlier release installed (Browser profiles -stay). The installer runs its Linux host step only after setup and only if the -helper is still present, so it asks for no administrator step. If an earlier -release set up Browser host access on Linux, it can be removed with: +Home and chat use the ordinary user account. Browser uses the local Engine's +virtual machine on Apple Silicon Macs and supported Linux ARM64 hosts with KVM. +On Linux, Marketplace lists Browser with its setup command. To turn it on, run +`elastos setup --browser` in a terminal as the user who installed Home. The +command installs the signed Browser helpers, shows the host access changes and +asks for administrator approval. It then downloads and verifies the image with +progress. Close Home and start it again with `elastos home --browser`. + +The Linux installer and ordinary `elastos setup` leave Browser preparation to +your choice until you enable it. Home lists Browser on supported Linux ARM64 +computers; opening it before setup explains the command and restart. After you +enable Browser, ordinary setup refreshes its signed helpers and image during +updates. A later open repairs missing or changed helpers and prepares a missing +image on demand. Apple Silicon setup continues to prepare its helpers and image +before Home starts. The image +streams to disk with progress; a transfer stops after 30 seconds without data. +Runtime keeps the committed Browser profile separate from the image during +reopen and updates. Linux x86-64 keeps Browser hidden and retires helpers and +images from unsupported releases while preserving Browser profiles. + +To remove Browser host access, close Browser and run this before uninstalling: ```sh sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)" @@ -502,8 +511,8 @@ directory stays, including Browser profiles, so installing again continues with the same identity. Pass the same `--install-dir` you installed with. An install or update that is running or was interrupted stops the removal; finish it first. -On Linux, the uninstall leaves any Browser host access an earlier release set -up in place. Remove it with: +On Linux, the administrator helper owns Browser host access. If you enabled it, +close Browser and remove that access before uninstalling: ```sh sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)" diff --git a/elastos/CHANGELOG.md b/elastos/CHANGELOG.md index 0face0b63..789809466 100644 --- a/elastos/CHANGELOG.md +++ b/elastos/CHANGELOG.md @@ -13,6 +13,7 @@ release's Added, Changed, Fixed, Removed and Security bullets before you update; ### Fixed - On a Jetson, Browser uses more of the processor, so scrolling is about twice as smooth. +- On Linux, Browser is turned on when you choose it, not during install. - Open apps, including Chat, stay connected while Home runs, and reconnect by themselves after a network drop or a restart. - The installer uses numeric process age to verify and stop a running Home with any time locale (#517). - The installer repairs group-writable files in an older Home that you own and gives one ownership repair command for root-owned installation files (#516). diff --git a/elastos/crates/elastos-server/src/api/browser_capsules.rs b/elastos/crates/elastos-server/src/api/browser_capsules.rs index ccb3e730a..84b26159a 100644 --- a/elastos/crates/elastos-server/src/api/browser_capsules.rs +++ b/elastos/crates/elastos-server/src/api/browser_capsules.rs @@ -430,7 +430,7 @@ fn list_launchable_browser_capsules_for( if !capsule_is_offered(data_dir, &manifest.name) { continue; } - if manifest.name == "browser" && !crate::setup::home_browser_available(data_dir, platform) { + if manifest.name == "browser" && !crate::setup::browser_available(platform) { continue; } let Ok(capsule) = resolve_browser_capsule(data_dir, &manifest.name) else { @@ -1494,12 +1494,12 @@ mod tests { } #[test] - fn browser_is_launchable_only_on_hosts_with_a_local_engine() { + fn browser_is_launchable_on_supported_hosts_before_setup() { let data_dir = tempfile::tempdir().unwrap(); write_test_browser_capsule(data_dir.path(), "browser", "Browser", "app"); for (platform, listed) in [ ("linux-amd64", false), - ("linux-arm64", false), + ("linux-arm64", true), ("darwin-arm64", true), ] { let names: Vec<_> = list_launchable_browser_capsules_for(data_dir.path(), platform) diff --git a/elastos/crates/elastos-server/src/api/gateway_browser.rs b/elastos/crates/elastos-server/src/api/gateway_browser.rs index 67f5a1e5a..eb684bd1b 100644 --- a/elastos/crates/elastos-server/src/api/gateway_browser.rs +++ b/elastos/crates/elastos-server/src/api/gateway_browser.rs @@ -87,7 +87,7 @@ pub(super) struct BrowserProviderResourceCall { } #[derive(Debug)] -struct BrowserOpenFailure { +pub(in crate::api::gateway) struct BrowserOpenFailure { status: StatusCode, body: BrowserOpenFailureBody, outcome: serde_json::Value, @@ -194,7 +194,7 @@ impl BrowserOpenFailure { (status, Json(self.status_value())).into_response() } - fn status_value(&self) -> serde_json::Value { + pub(in crate::api::gateway) fn status_value(&self) -> serde_json::Value { let mut value = match &self.body { BrowserOpenFailureBody::Text(message) => serde_json::json!({ "schema": "elastos.browser.open-error/v1", @@ -459,6 +459,7 @@ pub(super) async fn browser_app_open( input, home_token, request_origin, + &crate::setup::detect_platform(), ) .await { @@ -485,6 +486,7 @@ pub(super) async fn browser_app_open( input, home_token, request_origin, + &crate::setup::detect_platform(), ) .await { @@ -561,13 +563,34 @@ fn browser_open_status_value(open_id: &str, snapshot: BrowserOpenJobSnapshot) -> } } -async fn execute_browser_open( +fn browser_host_setup_failure( + data: &std::path::Path, + platform: &str, + adapter_id: Option<&str>, +) -> Option { + if adapter_id.is_some_and(|id| id != "browser-vm-product") { + return None; + } + crate::setup::linux_host_setup_message(data, platform).map(|message| { + BrowserOpenFailure::json( + StatusCode::CONFLICT, + serde_json::json!({ + "code": "browser_host_setup_required", + "stage": "engine_readiness", + "message": message, + }), + ) + }) +} + +pub(in crate::api::gateway) async fn execute_browser_open( state: &GatewayState, context: HomeLaunchTokenContext, authority: RuntimeWalletAuthority, input: BrowserOpenRequest, home_token: Option, request_origin: Option, + platform: &str, ) -> Result { let BrowserOpenRequest { url: requested_url, @@ -595,6 +618,23 @@ async fn execute_browser_open( err.to_string(), )); } + let requested_adapter_id = match browser_engine_adapter_id(adapter_id) { + Ok(value) => value, + Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)), + }; + if requested_adapter_id + .as_deref() + .is_none_or(|id| id == "browser-vm-product") + { + crate::setup::repair_browser_host_components_for_open(&state.data_dir, platform) + .await + .map_err(|error| BrowserOpenFailure::provider("browser-engine", error))?; + } + if let Some(failure) = + browser_host_setup_failure(&state.data_dir, platform, requested_adapter_id.as_deref()) + { + return Err(failure); + } let registry = match state.provider_registry.as_ref().cloned() { Some(registry) => registry, None => { @@ -614,10 +654,6 @@ async fn execute_browser_open( Ok(value) => value, Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)), }; - let requested_adapter_id = match browser_engine_adapter_id(adapter_id) { - Ok(value) => value, - Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)), - }; let browser_instance = match browser_instance_id(browser_instance) { Ok(value) => value, Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)), @@ -4627,6 +4663,27 @@ fn browser_display_error_response(error: BrowserDisplayError) -> Response { mod browser_open_outcome_tests { use super::*; + #[test] + fn unprepared_linux_browser_open_explains_setup_and_restart_before_acquiring_effects() { + let data = tempfile::tempdir().unwrap(); + for adapter in [None, Some("browser-vm-product")] { + let failure = browser_host_setup_failure(data.path(), "linux-arm64", adapter).unwrap(); + assert_eq!(failure.status, StatusCode::CONFLICT); + let body = failure.status_value(); + assert_eq!(body["code"], "browser_host_setup_required"); + assert_eq!(body["stage"], "engine_readiness"); + let message = body["message"].as_str().unwrap(); + assert!(message.contains("elastos setup --browser")); + assert!(message.contains("close Home and start it again with elastos home --browser")); + assert_eq!(body["outcome"]["effects"]["vm_acquired"], false); + } + assert!( + browser_host_setup_failure(data.path(), "linux-arm64", Some("remote-engine")).is_none() + ); + assert!(browser_host_setup_failure(data.path(), "darwin-arm64", None).is_none()); + assert!(std::fs::read_dir(data.path()).unwrap().next().is_none()); + } + #[test] fn failed_open_serializes_cleanup_pending_separately_from_pre_effect_failure() { let pending = BrowserOpenFailure::text( diff --git a/elastos/crates/elastos-server/src/api/gateway_browser_route_tests.rs b/elastos/crates/elastos-server/src/api/gateway_browser_route_tests.rs index e40e8719b..f37412e02 100644 --- a/elastos/crates/elastos-server/src/api/gateway_browser_route_tests.rs +++ b/elastos/crates/elastos-server/src/api/gateway_browser_route_tests.rs @@ -9748,3 +9748,134 @@ async fn test_browser_operator_inspection_fill_bootstrap_and_detach_scope() { ); } } + +#[tokio::test] +async fn browser_open_repairs_missing_helpers_after_viewer_load() { + browser_open_repairs_helpers_after_viewer_load(false, true, None).await; +} + +#[tokio::test] +async fn browser_open_repairs_stale_helpers_after_viewer_load() { + browser_open_repairs_helpers_after_viewer_load(true, true, Some("browser-vm-product")).await; +} + +#[tokio::test] +async fn browser_open_fresh_linux_home_refuses_before_helper_acquisition() { + browser_open_repairs_helpers_after_viewer_load(false, false, None).await; +} + +#[tokio::test] +async fn browser_open_fresh_linux_home_refuses_before_helper_acquisition_with_padded_adapter() { + browser_open_repairs_helpers_after_viewer_load(false, false, Some(" browser-vm-product ")) + .await; +} + +async fn browser_open_repairs_helpers_after_viewer_load( + stale: bool, + enabled: bool, + adapter_id: Option<&str>, +) { + use sha2::Digest as _; + use std::os::unix::fs::PermissionsExt; + let temp = tempfile::tempdir().unwrap(); + let data = temp.path().canonicalize().unwrap(); + std::fs::create_dir_all(data.join("config")).unwrap(); + std::fs::write( + data.join("config/browser-engine-adapter.json"), + serde_json::to_vec( + &json!({"adapters":[{"kind":"chromium_microvm","supervisor":{ + "program":data.join("bin/browser-vz-engine-supervisor") + }}]}), + ) + .unwrap(), + ) + .unwrap(); + let helpers = [ + ("browser-vz-engine-supervisor", "bin/browser-vz-engine-supervisor", + b"#!/bin/sh\nprintf '%s' '{\"schema\":\"elastos.browser.vm-host-capabilities/v1\",\"available\":false}'\n".as_slice()), + ("browser-vm-linux-network", "scripts/browser-vm-linux-network.py", b"# admitted network helper\n".as_slice()), + ]; + let mut manifest = json!({"schema":"elastos.components/v1", "capsules":{}, + "profiles":{"browser-host":{"components":["browser-vz-engine-supervisor","browser-vm-linux-network"]}}, + "external":{}}); + let mut artifacts = HashMap::new(); + for (name, relative, bytes) in helpers { + let digest = Sha256::digest(bytes); + let cid = cid::Cid::new_v1( + 0x55, + cid::multihash::Multihash::<64>::wrap(0x12, &digest).unwrap(), + ) + .to_string(); + manifest["external"][name] = json!({"install_path":relative,"platforms":{"*":{ + "release_path":name,"checksum":format!("sha256:{digest:x}"),"size":bytes.len(),"cid":cid + }}}); + artifacts.insert(cid, bytes.to_vec()); + let path = data.join(relative); + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + std::fs::write(&path, bytes).unwrap(); + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap(); + } + std::fs::write( + data.join("components.json"), + serde_json::to_vec(&manifest).unwrap(), + ) + .unwrap(); + let source = serde_json::from_value(json!({"name":"fixture", + "publisher_dids":[elastos_identity::derive_did(&[217;32]).1], + "connect_ticket":"", "publisher_node_id":""})) + .unwrap(); + let (_, server, serving) = + crate::setup::tests::carrier_cid_source(&data, &source, artifacts).await; + let owner = passkey_authority_with_name(&data, Some("helper-repair")); + // The viewer already holds its launch token. Open must repair independently + // of the capsule's earlier Home launch preparation. + let token = app_token_for_authority(&data, BROWSER_CAPSULE_ID, &owner); + let authority = runtime_wallet_authority_for_app_token(&data, BROWSER_CAPSULE_ID, &token); + let state = browser_engine_attached_test_state(&data).await; + for (_, relative, bytes) in helpers { + if stale { + std::fs::write(data.join(relative), vec![b'x'; bytes.len()]).unwrap(); + } else { + std::fs::remove_file(data.join(relative)).unwrap(); + } + } + if !enabled { + std::fs::remove_file(data.join("config/browser-engine-adapter.json")).unwrap(); + } + let input = serde_json::from_value( + json!({"url":"https://example.com/", "adapter_id":adapter_id, + "display_mode":"webrtc_remote_display", "guarantee_level":"operator_rbi"}), + ) + .unwrap(); + let result = super::super::gateway_browser::execute_browser_open( + &state, + authority.home_launch_context(), + authority, + input, + Some(token), + Some("null".into()), + "linux-arm64", + ) + .await; + // This fixture deliberately has no host capability. Repair must finish + // before that refusal, while image acquisition and VM effects stay gated. + let failure = result.unwrap_err(); + assert_eq!( + failure.status_value()["code"], + "browser_host_setup_required" + ); + for (_, relative, bytes) in helpers { + if enabled { + assert_eq!( + std::fs::read(data.join(relative)).ok().as_deref(), + Some(bytes), + "Open must repair {relative}" + ); + } else { + assert!(!data.join(relative).exists()); + } + } + assert!(!data.join("browser-vm").exists()); + server.close().await; + assert_eq!(serving.await.unwrap().len(), if enabled { 2 } else { 0 }); +} diff --git a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs index 39dc97328..6fdccf1aa 100644 --- a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs +++ b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs @@ -1428,13 +1428,16 @@ mod tests { "expected the first-party development capsule set to be visible" ); - for platform in ["linux-arm64", "linux-amd64"] { - // Where Browser is unavailable it is absent, not merely unlaunchable. - assert!( - !read_model::capsule_catalog_summary_for(data_dir.path(), platform) + for (platform, browser_listed) in [("linux-arm64", true), ("linux-amd64", false)] { + // Linux ARM64 lists Browser so opening it shows the setup command. + // Linux AMD64 has no supported Browser Engine and keeps it absent. + assert_eq!( + read_model::capsule_catalog_summary_for(data_dir.path(), platform) .capsules .iter() - .any(|capsule| capsule.name == "browser") + .any(|capsule| capsule.name == "browser"), + browser_listed, + "Browser catalog visibility on {platform}" ); } let catalog = read_model::capsule_catalog_summary_for(data_dir.path(), "darwin-arm64"); diff --git a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog/read_model.rs b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog/read_model.rs index 523879834..0d672f1b3 100644 --- a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog/read_model.rs +++ b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog/read_model.rs @@ -40,20 +40,24 @@ pub(in crate::api::gateway) fn capsule_catalog_summary_for( protected_content || manifest.name != crate::protected_content_runtime::ELACITY_PLAYER_CAPSULE_ID }) - // Browser is absent, not merely unlaunchable, where it is unavailable. - .filter(|manifest| { - manifest.name != "browser" || crate::setup::home_browser_available(data_dir, platform) - }) + // Supported Linux owners can find Browser before granting host access. + .filter(|manifest| manifest.name != "browser" || crate::setup::browser_available(platform)) // Hidden Services and an unconfigured WalletConnect are absent here as // in the launcher and Wallet. .filter(|manifest| capsule_is_offered(data_dir, &manifest.name)) .map(|manifest| { - catalog_capsule_summary( + let mut summary = catalog_capsule_summary( manifest, &launch_targets, &components, &accepted_content_by_viewer, - ) + ); + if summary.name == "browser" { + if let Some(message) = crate::setup::linux_host_setup_message(data_dir, platform) { + summary.description = message.to_string(); + } + } + summary }) .collect::>(); // The browser terminal only starts in developer mode, so the Terminal @@ -739,6 +743,30 @@ fn load_capsule_components(data_dir: &std::path::Path) -> BTreeMap