From 6484fe8d25fcbf7ddb85a015c6443a8046b65394 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 16 Oct 2026 04:13:45 +0000 Subject: [PATCH 1/8] docs: record how the Linux runtime behaves inside WSL2 Describe the installer, data directory, health probe, stop signal, and the Browser paths that stay closed without KVM or systemd. Co-authored-by: Sash --- docs/WINDOWS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index 18a7dc8a9..f90f81477 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -38,6 +38,50 @@ identity, and capability contracts. Do not leak WSL paths, host ports, or shell commands into capsule, provider, or object contracts. +## Linux build inside WSL2 + +This note is from the Linux installer and Runtime on `develop`. It was read +from code. It was not executed on a Windows machine or inside a WSL2 distro. + +Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` therefore selects +the Linux release for that architecture (`x86_64-linux` or `aarch64-linux`) +and writes the Linux data directory: `$XDG_DATA_HOME/elastos` or +`~/.local/share/elastos`. The published Linux binary is the musl target +(`x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`), so the distro +glibc is not the loader. The same `elastos gateway --addr 127.0.0.1:8090` +command and `GET /healthz` body `OK` apply. `healthz` in +`elastos/crates/elastos-server/src/api/gateway_site.rs` returns that body. + +The launcher keeps `HOME` and the data directory on the distro filesystem. +The host lock is an exclusive `flock` on `{data}/host-process.lock`. That lock +belongs on the Linux filesystem. A data directory on `/mnt/c` is a different +filesystem and is outside this install path. + +`elastos gateway` leaves the browser closed. On Linux, `elastos home --browser` +tries `wslview` and then `xdg-open`. The Windows launcher opens +`http://127.0.0.1:8090/home/` itself and keeps that exact origin for the +passkey. `localhost` and `127.0.0.1` are different WebAuthn origins. + +The Windows supervisor signals the Linux gateway process. `SIGTERM` to the +`wsl` parent, with the gateway left running inside the distro, skips the +Runtime's process-group shutdown. The launcher sends `SIGTERM` to the gateway +pid inside the distro, then waits until `/healthz` fails. + +Home's HTTP gateway does not need `/dev/kvm` or systemd. Two later paths do: + +- Local Browser and crosvm open `/dev/kvm` and fail closed when the device is + absent. Nested virtualization is a separate Windows setting. Without it, the + honest report is that the local Browser engine is unavailable and a remote + engine is the viewer path. +- `scripts/install.sh` runs `scripts/browser-vm-linux-network.py` only when + that helper is installed and `/dev/kvm` exists. The helper's setup writes + systemd and udev units. A distro without systemd keeps the HTTP Home and + leaves that Browser host setup incomplete. + +Native `elastos.exe` is still absent. `install.sh` stops when `uname` is not +Linux or Darwin. A Windows launcher that wants this Runtime starts the distro +and runs the Linux binary there. + ## Later native Windows direction Native Windows remains later host-adapter work behind the same Runtime and From 8d99372873b8892480e955f372d4ec327253dd12 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 16 Oct 2026 11:59:51 +0000 Subject: [PATCH 2/8] docs: state the WSL2 launcher as a target contract The Windows note now uses the Home origin http://localhost:8090/home/ and describes launcher stop, storage, and Browser as future behavior. It keeps the installer facts that exist: Linux platform selection, signature verification, and the musl binary. Branch status leaves this document. Co-authored-by: Sash --- docs/WINDOWS.md | 83 ++++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 45 deletions(-) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index f90f81477..5d5a08b6d 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -23,8 +23,8 @@ The first honest Windows product should run the Linux Runtime locally inside WSL2. - Package the Runtime as a signed or importable ElastOS WSL distribution. -- Provide a small Windows launcher that starts, stops, updates, health-checks, - and opens `http://localhost:61180/apps/home/`. +- A Windows launcher must start, stop, update, and health-check the Linux + Runtime, and open `http://localhost:8090/home/`. - Keep Runtime state in the Linux filesystem, not in mixed host paths. - Enforce explicit storage budgets and cleanup. - Keep localhost and passkey origin stable. @@ -35,52 +35,45 @@ WSL2 is a host substrate, not a new capsule API and not a substitute for capsule isolation. Capsules keep the same Runtime, Carrier, provider, identity, and capability contracts. -Do not leak WSL paths, host ports, or shell commands into capsule, provider, or -object contracts. +Capsule, provider, and object contracts stay on the Runtime surface. WSL paths, +host ports, and shell commands stay in the host launcher. ## Linux build inside WSL2 -This note is from the Linux installer and Runtime on `develop`. It was read -from code. It was not executed on a Windows machine or inside a WSL2 distro. - -Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` therefore selects -the Linux release for that architecture (`x86_64-linux` or `aarch64-linux`) -and writes the Linux data directory: `$XDG_DATA_HOME/elastos` or -`~/.local/share/elastos`. The published Linux binary is the musl target -(`x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`), so the distro -glibc is not the loader. The same `elastos gateway --addr 127.0.0.1:8090` -command and `GET /healthz` body `OK` apply. `healthz` in -`elastos/crates/elastos-server/src/api/gateway_site.rs` returns that body. - -The launcher keeps `HOME` and the data directory on the distro filesystem. -The host lock is an exclusive `flock` on `{data}/host-process.lock`. That lock -belongs on the Linux filesystem. A data directory on `/mnt/c` is a different -filesystem and is outside this install path. - -`elastos gateway` leaves the browser closed. On Linux, `elastos home --browser` -tries `wslview` and then `xdg-open`. The Windows launcher opens -`http://127.0.0.1:8090/home/` itself and keeps that exact origin for the -passkey. `localhost` and `127.0.0.1` are different WebAuthn origins. - -The Windows supervisor signals the Linux gateway process. `SIGTERM` to the -`wsl` parent, with the gateway left running inside the distro, skips the -Runtime's process-group shutdown. The launcher sends `SIGTERM` to the gateway -pid inside the distro, then waits until `/healthz` fails. - -Home's HTTP gateway does not need `/dev/kvm` or systemd. Two later paths do: - -- Local Browser and crosvm open `/dev/kvm` and fail closed when the device is - absent. Nested virtualization is a separate Windows setting. Without it, the - honest report is that the local Browser engine is unavailable and a remote - engine is the viewer path. -- `scripts/install.sh` runs `scripts/browser-vm-linux-network.py` only when - that helper is installed and `/dev/kvm` exists. The helper's setup writes - systemd and udev units. A distro without systemd keeps the HTTP Home and - leaves that Browser host setup incomplete. - -Native `elastos.exe` is still absent. `install.sh` stops when `uname` is not -Linux or Darwin. A Windows launcher that wants this Runtime starts the distro -and runs the Linux binary there. +A Windows launcher must run the Linux Runtime inside a WSL2 distro. This +section states the installer behavior that exists today and the launcher +behavior a future Windows program must provide. An executed Windows proof is +an owning issue. + +Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` selects the Linux +release for that architecture (`x86_64-linux` or `aarch64-linux`). It verifies +the release signature and hash before it installs the binary. It writes the +Linux data directory: `$XDG_DATA_HOME/elastos` or `~/.local/share/elastos`. +The published Linux binary is the musl target +(`x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`). + +A Windows launcher must keep `HOME` and the data directory on the distro +filesystem. It must start Home with `elastos gateway --addr localhost:8090` +and open one origin, `http://localhost:8090/home/`. The passkey relying party +id for that origin is `localhost`. + +`elastos gateway` leaves the browser closed. That is the one browser-open +path for this host: the Windows launcher opens the Home origin above. +`elastos home --browser` on Linux tries `wslview` and then `xdg-open`. A +Windows launcher must not open a second origin through that command. + +A Windows launcher must stop the gateway by a method the owning issue +specifies, and it must confirm the process has exited. This note does not +define a signal path. + +The HTTP gateway is the Home path inside the distro. A local Browser engine +is a separate host decision. This note claims no Windows Browser engine. +`scripts/install.sh` runs `scripts/browser-vm-linux-network.py` when that +helper is installed and `/dev/kvm` exists. That helper writes systemd and +udev units. + +`install.sh` stops when `uname` is not Linux or Darwin. A Windows launcher +must start the distro and run the Linux binary there. ## Later native Windows direction From 4644e08a7644779b0f109a154254e3e33780c161 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 17 Oct 2026 05:43:23 +0000 Subject: [PATCH 3/8] docs: cite the WSL Home origin and name the open gaps The Windows note points at the gateway port, the /home/ route, and the installer signature and hash checks. It states the WSL decision to skip the Browser VM helper, and it records the home --browser, /mnt, and rollback gaps. Co-authored-by: Sash --- docs/WINDOWS.md | 121 ++++++++++++++++++++++++++++++------------------ 1 file changed, 76 insertions(+), 45 deletions(-) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index 5d5a08b6d..783ef827e 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -19,61 +19,92 @@ Browser contracts. Capsules must not branch on Windows or learn host topology. ## First Windows product: WSL2 -The first honest Windows product should run the Linux Runtime locally inside -WSL2. +The first honest Windows product runs the Linux Runtime locally inside WSL2. +The executed proof for that product is +[issue #265](https://github.com/Elacity/elastos-runtime/issues/265). - Package the Runtime as a signed or importable ElastOS WSL distribution. -- A Windows launcher must start, stop, update, and health-check the Linux - Runtime, and open `http://localhost:8090/home/`. -- Keep Runtime state in the Linux filesystem, not in mixed host paths. -- Enforce explicit storage budgets and cleanup. -- Keep localhost and passkey origin stable. -- Report Browser availability honestly. Edge is a shell surface for Home, not - proof of a local isolated Browser capsule. - -WSL2 is a host substrate, not a new capsule API and not a substitute for -capsule isolation. Capsules keep the same Runtime, Carrier, provider, -identity, and capability contracts. +- A Windows launcher starts, stops, updates, and health-checks the Linux + Runtime, and opens one Home origin: `http://localhost:8090/home/`. +- The launcher keeps Runtime state on the distro filesystem. +- The launcher enforces explicit storage budgets and cleanup. +- The launcher keeps the localhost passkey origin stable. +- The launcher reports Browser availability honestly. Edge is a shell surface + for Home. It is not proof of a local isolated Browser capsule. + +WSL2 is a host substrate. It is not a new capsule API and it is not a +substitute for capsule isolation. Capsules keep the same Runtime, Carrier, +provider, identity, and capability contracts. Capsule, provider, and object contracts stay on the Runtime surface. WSL paths, host ports, and shell commands stay in the host launcher. ## Linux build inside WSL2 -A Windows launcher must run the Linux Runtime inside a WSL2 distro. This -section states the installer behavior that exists today and the launcher -behavior a future Windows program must provide. An executed Windows proof is -an owning issue. - -Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` selects the Linux -release for that architecture (`x86_64-linux` or `aarch64-linux`). It verifies -the release signature and hash before it installs the binary. It writes the -Linux data directory: `$XDG_DATA_HOME/elastos` or `~/.local/share/elastos`. -The published Linux binary is the musl target -(`x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`). - -A Windows launcher must keep `HOME` and the data directory on the distro -filesystem. It must start Home with `elastos gateway --addr localhost:8090` -and open one origin, `http://localhost:8090/home/`. The passkey relying party -id for that origin is `localhost`. - -`elastos gateway` leaves the browser closed. That is the one browser-open -path for this host: the Windows launcher opens the Home origin above. -`elastos home --browser` on Linux tries `wslview` and then `xdg-open`. A -Windows launcher must not open a second origin through that command. - -A Windows launcher must stop the gateway by a method the owning issue -specifies, and it must confirm the process has exited. This note does not -define a signal path. - -The HTTP gateway is the Home path inside the distro. A local Browser engine -is a separate host decision. This note claims no Windows Browser engine. -`scripts/install.sh` runs `scripts/browser-vm-linux-network.py` when that -helper is installed and `/dev/kvm` exists. That helper writes systemd and -udev units. +A Windows launcher runs the Linux Runtime inside a WSL2 distro. This section +cites the installer and gateway behavior that exists today, and it names the +gaps a launcher still owns. + +Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` `detect_platform` +selects `x86_64-linux` or `aarch64-linux`. `scripts/prepare-release-platform.sh` +builds those releases as `x86_64-unknown-linux-musl` or +`aarch64-unknown-linux-musl`. + +`scripts/install.sh` `verify_signature` checks the Ed25519 signature on +`release-head.json` and `release.json` against `MAINTAINER_DID` before it +installs. `sha256_check` then checks the binary against the signed SHA-256. +`scripts/install-bootstrap-test.py` covers a tampered release +(`test_signature_and_binding_failures_reject_before_artifacts_in_populated_installation`), +a foreign trust anchor in that same test, and a binary whose bytes differ +(`test_corrupt_artifacts_fail_before_changes_then_clean_rerun_installs`, +which expects `SHA-256 mismatch`). This note does not claim the installer +refuses an older release that still carries a valid signature. That rollback +check is a gap. + +The installer writes `$XDG_DATA_HOME/elastos` or `~/.local/share/elastos`. +The launcher keeps `HOME` and that data directory on the distro filesystem. +`install.sh` does not reject a data root under `/mnt`. That guard is a gap. + +The one Home origin is `http://localhost:8090/home/`. + +- `BROWSER_HOME_PORT` in `elastos/crates/elastos-server/src/update_controller.rs` + is `8090`. +- `HOME_ROUTE` in `elastos/crates/elastos-server/src/api/gateway.rs` is + `/home/`. +- `elastos home --browser` binds `localhost:8090` and opens the gateway Home + URL (`gateway_entry.rs` `run_browser_home`). The gateway builds that URL as + `{api}/home/` (`gateway_server.rs`). +- `/home`, `/apps/home`, and `/apps/home/` redirect to `/home/` + (`redirect_home_root` in `api/browser_capsules.rs`). +- `elastos gateway` without `--addr` binds `127.0.0.1:8090` (`main.rs`, the + `Gateway` command). A launcher that wants the localhost origin passes + `--addr localhost:8090`. + +The passkey relying party id for `http://localhost:8090/home/` is `localhost`. +WebAuthn scopes that id by host, so any port on `localhost` can request an +assertion for it. The Windows launcher opens only `http://localhost:8090/home/`. + +`elastos gateway` leaves the browser closed. The Windows launcher owns the +browser-open path and opens the Home origin above. `elastos home --browser` +still calls `open_browser` in `main.rs`, which tries `wslview` and then +`xdg-open` with the URL it was given. This note does not make that command +refuse under WSL. A second open from that command is a gap. + +The runtime update command is `elastos update` (`Commands::Update` in +`main.rs`). `scripts/install.sh` `show_ready` prints that command. A Windows +launcher calls `elastos update`. It does not ship a second updater. This note +does not define the stop signal. Issue #265 owns that path. `wsl --shutdown` +stops the distro without a Runtime stop. + +The decision for WSL is that the installer skips +`scripts/browser-vm-linux-network.py` and prints that skip. This note claims +no Windows Browser engine. This note does not change `install.sh`. Today +`prepare_browser_linux_host` still runs that helper when the file is installed +and `/dev/kvm` exists, and the helper can write systemd and udev units. The +visible skip is open work on issue #265. `install.sh` stops when `uname` is not Linux or Darwin. A Windows launcher -must start the distro and run the Linux binary there. +starts the distro and runs the Linux binary there. ## Later native Windows direction From 474db0abc681f6a84b7daa0df7689b8bd27aef62 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 06:01:39 +0000 Subject: [PATCH 4/8] docs: cite WSL2 Home, release checks, update path and Browser by line Give each WSL2 statement a file:line citation in the code. Keep the Home URL in one place and point the other mentions at it. Correct two statements against the code. An existing installation already refuses an older signed release (install_release in update.rs), so only a new installation lacks a version floor. Browser fails closed on every Linux host: setup removes the network helper before the installer host step, so WSL2 asks for no sudo (browser_available and retire_host in setup/browser_config.rs). Name the update path: the signed head sets the channel, elastos update follows it, a canary subscription also follows stable, and elastos source switch-channel changes it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- docs/WINDOWS.md | 235 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 171 insertions(+), 64 deletions(-) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index 783ef827e..b8ce4a3eb 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -25,7 +25,8 @@ The executed proof for that product is - Package the Runtime as a signed or importable ElastOS WSL distribution. - A Windows launcher starts, stops, updates, and health-checks the Linux - Runtime, and opens one Home origin: `http://localhost:8090/home/`. + Runtime, and opens one Home origin. [Home origin](#home-origin) gives that + URL and its code. - The launcher keeps Runtime state on the distro filesystem. - The launcher enforces explicit storage budgets and cleanup. - The launcher keeps the localhost passkey origin stable. @@ -42,69 +43,175 @@ host ports, and shell commands stay in the host launcher. ## Linux build inside WSL2 A Windows launcher runs the Linux Runtime inside a WSL2 distro. This section -cites the installer and gateway behavior that exists today, and it names the -gaps a launcher still owns. - -Inside a distro, `uname -s` is `Linux`. `scripts/install.sh` `detect_platform` -selects `x86_64-linux` or `aarch64-linux`. `scripts/prepare-release-platform.sh` -builds those releases as `x86_64-unknown-linux-musl` or -`aarch64-unknown-linux-musl`. - -`scripts/install.sh` `verify_signature` checks the Ed25519 signature on -`release-head.json` and `release.json` against `MAINTAINER_DID` before it -installs. `sha256_check` then checks the binary against the signed SHA-256. -`scripts/install-bootstrap-test.py` covers a tampered release -(`test_signature_and_binding_failures_reject_before_artifacts_in_populated_installation`), -a foreign trust anchor in that same test, and a binary whose bytes differ -(`test_corrupt_artifacts_fail_before_changes_then_clean_rerun_installs`, -which expects `SHA-256 mismatch`). This note does not claim the installer -refuses an older release that still carries a valid signature. That rollback -check is a gap. - -The installer writes `$XDG_DATA_HOME/elastos` or `~/.local/share/elastos`. -The launcher keeps `HOME` and that data directory on the distro filesystem. -`install.sh` does not reject a data root under `/mnt`. That guard is a gap. - -The one Home origin is `http://localhost:8090/home/`. - -- `BROWSER_HOME_PORT` in `elastos/crates/elastos-server/src/update_controller.rs` - is `8090`. -- `HOME_ROUTE` in `elastos/crates/elastos-server/src/api/gateway.rs` is - `/home/`. -- `elastos home --browser` binds `localhost:8090` and opens the gateway Home - URL (`gateway_entry.rs` `run_browser_home`). The gateway builds that URL as - `{api}/home/` (`gateway_server.rs`). -- `/home`, `/apps/home`, and `/apps/home/` redirect to `/home/` - (`redirect_home_root` in `api/browser_capsules.rs`). -- `elastos gateway` without `--addr` binds `127.0.0.1:8090` (`main.rs`, the - `Gateway` command). A launcher that wants the localhost origin passes - `--addr localhost:8090`. - -The passkey relying party id for `http://localhost:8090/home/` is `localhost`. -WebAuthn scopes that id by host, so any port on `localhost` can request an -assertion for it. The Windows launcher opens only `http://localhost:8090/home/`. - -`elastos gateway` leaves the browser closed. The Windows launcher owns the -browser-open path and opens the Home origin above. `elastos home --browser` -still calls `open_browser` in `main.rs`, which tries `wslview` and then -`xdg-open` with the URL it was given. This note does not make that command -refuse under WSL. A second open from that command is a gap. - -The runtime update command is `elastos update` (`Commands::Update` in -`main.rs`). `scripts/install.sh` `show_ready` prints that command. A Windows -launcher calls `elastos update`. It does not ship a second updater. This note -does not define the stop signal. Issue #265 owns that path. `wsl --shutdown` -stops the distro without a Runtime stop. - -The decision for WSL is that the installer skips -`scripts/browser-vm-linux-network.py` and prints that skip. This note claims -no Windows Browser engine. This note does not change `install.sh`. Today -`prepare_browser_linux_host` still runs that helper when the file is installed -and `/dev/kvm` exists, and the helper can write systemd and udev units. The -visible skip is open work on issue #265. - -`install.sh` stops when `uname` is not Linux or Darwin. A Windows launcher -starts the distro and runs the Linux binary there. +records what the installer and Runtime do there today. Each statement cites +the code. If a line number moves, use the named function. Rust paths are +relative to `elastos/crates/elastos-server/src/`. + +### Platform + +Inside a distro, `uname -s` is `Linux`. `detect_platform` +(`scripts/install.sh:317-336`) selects `x86_64-linux` or `aarch64-linux`. +`scripts/prepare-release-platform.sh:107-108` builds those releases for +`x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl`. +`installer_data_dir` (`scripts/install.sh:300-315`) stops on a system name +that is not `Linux` or `Darwin`. A Windows launcher starts the distro and runs +the Linux installer and binary there. + +### Home origin + +The Home origin is `http://localhost:8090/home/`. A Windows launcher opens +only this URL. Other text in this note refers to it as "the Home origin". + +- `elastos home --browser` binds `localhost:` plus `BROWSER_HOME_PORT` + (`gateway_entry.rs:17-31`). `BROWSER_HOME_PORT` is `8090` + (`update_controller.rs:2288-2289`). +- The gateway keeps the host name `localhost` in its URL + (`api/gateway_server.rs:96-101`) and adds `/home/` + (`api/gateway_server.rs:117`). `HOME_ROUTE` is `/home/` + (`api/gateway.rs:440`). +- `/home`, `/apps/home`, and `/apps/home/` redirect permanently to `/home/` + (`api/gateway.rs:1222-1235`, `redirect_home_root` in + `api/browser_capsules.rs:58-64`). +- After an update restart, Runtime prints the same URL + (`update_controller.rs:1049`). The update controller accepts a ready Home + only at port `8090` and path `/home/` (`approved_home_url`, + `update_controller.rs:2291-2299`). +- `elastos gateway` is a hidden operator command. Without `--addr` it binds + `127.0.0.1:8090` (`main.rs:438-441`). A launcher does not use it to open + Home. `127.0.0.1` is a different origin from `localhost`, and a passkey made + on one origin does not sign in on the other. + +The passkey relying party id for the Home origin is `localhost`. WebAuthn +scopes that id by host, so any port on `localhost` can request an assertion +for it. + +`docs/INSTALL.md` gives the same Home origin. The source-build guides +`docs/MAC.md` and `docs/HOME_LOCAL_SETUP.md` use a developer gateway at +`http://localhost:61180/apps/home/`. That is a developer lane, not the +installed product. + +`elastos home --browser` opens a browser itself. `browser_home_ready` +(`gateway_entry.rs:33-40`) prints the URL and calls `open_browser` +(`main.rs:2268-2283`). On Linux, `open_browser` tries `wslview` and then +`xdg-open`. It skips the open after an update restart +(`ELASTOS_UPDATE_RESTART=1`). There is no flag that stops this open, so a +launcher that also opens Home makes a second tab. That is a gap. + +### Release verification + +The installer trusts one maintainer key. The publish step writes that +`did:key` into `install.sh` as `MAINTAINER_DID` +(`scripts/install.sh:45-48`). `ELASTOS_MAINTAINER_DID` or `--maintainer-did` +replaces it (`scripts/install.sh:45`, `scripts/install.sh:1128`). The +installer stops when the value is empty or is not a `did:key` +(`scripts/install.sh:1167-1172`). The signature check is only as strong as the +`install.sh` copy that carries this key. A Windows launcher must check the +SHA-256 of `install.sh` against its own signed record before it runs it, and +must not set `ELASTOS_MAINTAINER_DID`. + +Before the installer changes any file, it does these checks: + +1. `verify_signature` (`scripts/install.sh:678-825`) checks the Ed25519 + signature over the domain and the canonical payload. It also checks that + the signer is the pinned `MAINTAINER_DID`. The installer runs it on + `release-head.json` (`scripts/install.sh:1286`) and on `release.json` + (`scripts/install.sh:1313`). +2. `validate_release_identity` (`scripts/install.sh:827-863`) checks that the + signed head names the SHA-256 of the exact `release.json` bytes. +3. `sha256_check` (`scripts/install.sh:356-364`) checks the downloaded binary + against the SHA-256 in the signed `release.json` + (`scripts/install.sh:1354`). + +These tests in `scripts/install-bootstrap-test.py` feed a bad input and check +that the installer stops and changes nothing: + +- `test_signature_and_binding_failures_reject_before_artifacts_in_populated_installation` + (line 1235): a release with one changed field, a head bound to another + release, and a foreign trust anchor. The first and last expect + `Signature verification FAILED`. +- `test_corrupt_artifacts_fail_before_changes_then_clean_rerun_installs` + (line 991): a truncated binary and a binary with different bytes. Both + expect `SHA-256 mismatch`. +- `test_altered_message_signature_and_key` (line 215) and + `test_binding_precedes_artifacts` (line 731) cover the Ed25519 check and + the head-to-release binding. + +On an existing installation, the release writer refuses a release that is +older than the installed release, and a release from another channel +(`install_release`, `update.rs:505-513`). The Rust test +`older_installer_after_update_is_refused_without_changes` (`update.rs:5067`) +covers the older release. A new installation has no installed release to +compare. It accepts any release that the pinned key signed. A launcher that +needs a version floor on a new installation must supply it. That is a gap. + +### Data location + +The installer writes `$XDG_DATA_HOME/elastos` or `~/.local/share/elastos` +(`installer_data_dir`, `scripts/install.sh:300-315`). The launcher keeps +`HOME` and that data directory on the distro filesystem. `install.sh` does not +reject a data directory under `/mnt`. That guard is a gap. + +### Update path + +The signed release head names its channel. The installer reads it, accepts +`stable`, `canary`, or `jetson-test` (`scripts/install.sh:84`, +`scripts/install.sh:1290-1293`), and records it as the channel of the trusted +source in `sources.json` (`scripts/install.sh:1406-1425`). The publisher +gateway that the installer reads sets which channel a new installation gets. + +- `elastos update` (`Commands::Update`, `main.rs:550-570`) is the update + command. `show_ready` prints it after installation + (`scripts/install.sh:885-904`). +- `elastos update` refuses a signed release that is older than the installed + release (`update.rs:1233-1237`). The release writer keeps the installed + version as a floor (`update.rs:505-512`; test + `force_keeps_signed_installed_version_as_downgrade_floor`, + `update.rs:4081`). This note does not describe a rollback path. +- `verify_source_channel` (`update.rs:170-183`) accepts only the subscribed + channel. A `canary` subscription also accepts `stable` releases from the + same publisher. +- `elastos source switch-channel ` changes the subscription + (`sources.rs:465-475`, `sources.rs:713-719`). +- A second run of `install.sh` also updates. It uses the same release writer + and the same refusals as above. + +A Windows launcher calls `elastos update`. It does not ship a second updater. +This note does not define the stop signal. Issue #265 owns that path. +`wsl --shutdown` stops the distro without a Runtime stop. + +### Browser on WSL2 + +Runtime offers Browser only on `darwin-arm64` (`browser_available`, +`setup/browser_config.rs:166-168`). On every Linux host, WSL2 included, +Browser fails closed: + +- `elastos setup` removes the Browser host files that a release installs + (`retire_host`, `setup/browser_config.rs:300-355`). The removed files + include `scripts/browser-vm-linux-network.py`. When a Browser capsule + folder exists, setup also writes an empty Engine selection and prints + `Browser is not available on this computer yet.` + (`setup/browser_config.rs:301-306`, `setup/browser_config.rs:352-354`). + Without that folder, setup prints no Browser line. +- The Home catalog leaves Browser out + (`api/gateway_capsule_catalog/read_model.rs:44`, + `api/browser_capsules.rs:431-433`). +- The installer runs `elastos setup` before its Linux host step + (`scripts/install.sh:950-952`). `prepare_browser_linux_host` + (`scripts/install.sh:908-937`) returns when the helper file is absent + (`scripts/install.sh:914`). Thus the installer asks for no `sudo`, and no + systemd unit, udev rule, TAP device, or KVM access rule is written. +- The Rust test `linux_setup_installs_no_browser_host_helpers_or_image` + (`setup/browser_config.rs:808`) checks this for `linux-amd64` and + `linux-arm64`. + +This result does not depend on `/dev/kvm`. This note claims no Windows Browser +Engine. + +If an earlier release ran the root helper on a host, `retire_host` removes +only the files in the data directory. The root-owned copy in +`/usr/local/lib/elastos`, the systemd unit, the udev rule, and the KVM access +rule stay until an administrator runs the helper `remove` action. That is a +gap. ## Later native Windows direction From 15f65e9bdd099fea39948cb27897a719f82da36f Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 06:21:25 +0000 Subject: [PATCH 5/8] docs: point the WSL2 Home origin at the launcher contract The launcher contract owns the Home URL and the passkey origin, so this note links to it and does not repeat the value. Keep the Runtime facts with their citations: what elastos home --browser binds, the redirects, the update controller readiness hosts, and the hidden gateway default. State the open gap: the desktop launcher and the launcher contract do not use the same host name today, and localhost and 127.0.0.1 are different passkey origins. The note does not choose one. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- docs/WINDOWS.md | 49 +++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index b8ce4a3eb..b5007ecc0 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -25,11 +25,12 @@ The executed proof for that product is - Package the Runtime as a signed or importable ElastOS WSL distribution. - A Windows launcher starts, stops, updates, and health-checks the Linux - Runtime, and opens one Home origin. [Home origin](#home-origin) gives that - URL and its code. + Runtime, and opens one Home origin. The + [launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url) owns that + URL. - The launcher keeps Runtime state on the distro filesystem. - The launcher enforces explicit storage budgets and cleanup. -- The launcher keeps the localhost passkey origin stable. +- The launcher keeps the passkey origin stable. - The launcher reports Browser availability honestly. Edge is a shell surface for Home. It is not proof of a local isolated Browser capsule. @@ -59,36 +60,36 @@ the Linux installer and binary there. ### Home origin -The Home origin is `http://localhost:8090/home/`. A Windows launcher opens -only this URL. Other text in this note refers to it as "the Home origin". +The [launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url) is the +one source for the Home URL that a launcher opens and for the passkey origin. +This note does not repeat that value. It records what the Runtime code serves: -- `elastos home --browser` binds `localhost:` plus `BROWSER_HOME_PORT` - (`gateway_entry.rs:17-31`). `BROWSER_HOME_PORT` is `8090` - (`update_controller.rs:2288-2289`). -- The gateway keeps the host name `localhost` in its URL +- `elastos home --browser` binds the host name `localhost` at + `BROWSER_HOME_PORT` (`gateway_entry.rs:17-31`, + `update_controller.rs:2288-2289`). +- The gateway keeps the host name that it was given in its URL (`api/gateway_server.rs:96-101`) and adds `/home/` (`api/gateway_server.rs:117`). `HOME_ROUTE` is `/home/` (`api/gateway.rs:440`). - `/home`, `/apps/home`, and `/apps/home/` redirect permanently to `/home/` (`api/gateway.rs:1222-1235`, `redirect_home_root` in `api/browser_capsules.rs:58-64`). -- After an update restart, Runtime prints the same URL - (`update_controller.rs:1049`). The update controller accepts a ready Home - only at port `8090` and path `/home/` (`approved_home_url`, - `update_controller.rs:2291-2299`). +- After an update restart, Runtime prints the Home URL with the host name + `localhost` (`update_controller.rs:1049`). The update controller accepts a + ready Home at `BROWSER_HOME_PORT` and `/home/` on `localhost`, `127.0.0.1`, + or `[::1]` (`approved_home_url`, `update_controller.rs:2291-2299`). - `elastos gateway` is a hidden operator command. Without `--addr` it binds - `127.0.0.1:8090` (`main.rs:438-441`). A launcher does not use it to open - Home. `127.0.0.1` is a different origin from `localhost`, and a passkey made - on one origin does not sign in on the other. + `127.0.0.1` at the same port (`main.rs:438-441`). -The passkey relying party id for the Home origin is `localhost`. WebAuthn -scopes that id by host, so any port on `localhost` can request an assertion -for it. +`localhost` and `127.0.0.1` are different browser origins. A passkey that is +registered on one origin does not sign in on the other. The desktop launcher +and the launcher contract do not use the same host name for the Home origin +today. That is an open gap. The team decides the canonical origin, and this +note does not choose one. -`docs/INSTALL.md` gives the same Home origin. The source-build guides -`docs/MAC.md` and `docs/HOME_LOCAL_SETUP.md` use a developer gateway at -`http://localhost:61180/apps/home/`. That is a developer lane, not the -installed product. +`docs/INSTALL.md` describes `elastos home --browser`. The source-build guides +`docs/MAC.md` and `docs/HOME_LOCAL_SETUP.md` use a developer gateway on a +different port. That is a developer lane, not the installed product. `elastos home --browser` opens a browser itself. `browser_home_ready` (`gateway_entry.rs:33-40`) prints the URL and calls `open_browser` @@ -239,6 +240,6 @@ Before Windows support is called product-ready, prove: - same-device and cross-device Carrier behavior where applicable - bounded disk usage and explicit cleanup - no orphan processes after stop -- stable localhost and passkey origin +- stable Home and passkey origin - honest Browser availability - installed artifact receipt and source receipt From 756dad1c55210bb6f5732276b83d865b167f0818 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 07:22:39 +0000 Subject: [PATCH 6/8] deps: move zip to 9.x for RUSTSEC-2026-0367/0368/0369 cargo-audit fails on every PR: zip 2.4.2 in elastos/Cargo.lock and in capsules/object-provider/Cargo.lock (through its elastos-server path dependency) has three advisories against ZipArchive::extract and the stream extract API. The runtime calls neither; it reads each entry itself. zip 9.0.4 is the patched release. - elastos-server uses zip 9.0.4, still without default features. 9.x has no separate flate2 feature; deflate-flate2 now enables the dependency. - Both lockfiles change only for zip: nix 0.31.3 and typed-path come in, derive_arbitrary goes. `cargo update -p zip` also moved unrelated range dependencies (windows-sys, getrandom); those lines stay as they were, and `cargo metadata --locked` accepts both files. - ZipFile::name now returns a Result. The ZIP readers report an error as "invalid ZIP archive entry". - Whole-archive extract keeps its rule for entry names. zip 9 enclosed_name turns "/a.txt" into "a.txt" and folds "x/../a.txt" into "a.txt", so an entry that extract refuses today would be written. The runtime now checks the name with the rule zip 2.x applied: no NUL byte, no root or drive prefix, no climb above the archive root. test_library_provider_extract_zip_refuses_absolute_dotdot_and_symlink_entries covers absolute, "..", inner "..", backslash and symlink entries. It passes on zip 2.4.2 and with this change, and fails on the Absolute.zip case when extract uses zip 9 enclosed_name. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- capsules/object-provider/Cargo.lock | 50 ++--- elastos/Cargo.lock | 50 ++--- elastos/crates/elastos-server/Cargo.toml | 2 +- .../src/api/gateway_tests/library.rs | 199 +++++++++++++++++- elastos/crates/elastos-server/src/library.rs | 44 +++- 5 files changed, 290 insertions(+), 55 deletions(-) diff --git a/capsules/object-provider/Cargo.lock b/capsules/object-provider/Cargo.lock index d5114091d..914d1dc39 100644 --- a/capsules/object-provider/Cargo.lock +++ b/capsules/object-provider/Cargo.lock @@ -167,9 +167,6 @@ name = "arbitrary" version = "1.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1" -dependencies = [ - "derive_arbitrary", -] [[package]] name = "arc-swap" @@ -1190,7 +1187,7 @@ dependencies = [ "elastos-protected-content-provider-contracts", "elastos-protected-content-rights", "getrandom 0.2.17", - "nix", + "nix 0.29.0", "serde", "serde_json", "sha2 0.10.9", @@ -1274,17 +1271,6 @@ version = "0.5.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c" -[[package]] -name = "derive_arbitrary" -version = "1.4.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a" -dependencies = [ - "proc-macro2", - "quote", - "syn 2.0.119", -] - [[package]] name = "derive_more" version = "2.1.1" @@ -1589,7 +1575,7 @@ dependencies = [ "elastos-common", "elastos-compute", "libc", - "nix", + "nix 0.29.0", "serde", "serde_json", "thiserror 1.0.69", @@ -1689,7 +1675,7 @@ dependencies = [ "ghash", "hkdf", "hpke", - "nix", + "nix 0.29.0", "rand 0.10.2", "rand 0.9.5", "rand_chacha 0.3.1", @@ -1734,7 +1720,7 @@ dependencies = [ "elastos-protected-content-provider-contracts", "elastos-wallet-contract", "hex", - "nix", + "nix 0.29.0", "serde", "serde_json", "sha2 0.10.9", @@ -3855,6 +3841,18 @@ dependencies = [ "libc", ] +[[package]] +name = "nix" +version = "0.31.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d" +dependencies = [ + "bitflags", + "cfg-if", + "cfg_aliases", + "libc", +] + [[package]] name = "nom" version = "7.1.3" @@ -6053,6 +6051,12 @@ dependencies = [ "utf-8", ] +[[package]] +name = "typed-path" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e" + [[package]] name = "typenum" version = "1.20.1" @@ -7446,18 +7450,16 @@ dependencies = [ [[package]] name = "zip" -version = "2.4.2" +version = "9.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50" +checksum = "a954114b47a54df49f83d2722814e86b23d4bb1b54a1b90fb7d92b41619ddc22" dependencies = [ - "arbitrary", "crc32fast", - "crossbeam-utils", - "displaydoc", "flate2", "indexmap", "memchr", - "thiserror 2.0.20", + "nix 0.31.3", + "typed-path", ] [[package]] diff --git a/elastos/Cargo.lock b/elastos/Cargo.lock index ac82b721d..dc06da84e 100644 --- a/elastos/Cargo.lock +++ b/elastos/Cargo.lock @@ -167,9 +167,6 @@ name = "arbitrary" version = "1.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1" -dependencies = [ - "derive_arbitrary", -] [[package]] name = "arc-swap" @@ -1197,7 +1194,7 @@ dependencies = [ "elastos-protected-content-provider-contracts", "elastos-protected-content-rights", "getrandom 0.2.17", - "nix", + "nix 0.29.0", "serde", "serde_json", "sha2 0.10.9", @@ -1281,17 +1278,6 @@ version = "0.5.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c" -[[package]] -name = "derive_arbitrary" -version = "1.4.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a" -dependencies = [ - "proc-macro2", - "quote", - "syn 2.0.119", -] - [[package]] name = "derive_more" version = "2.1.1" @@ -1598,7 +1584,7 @@ dependencies = [ "elastos-common", "elastos-compute", "libc", - "nix", + "nix 0.29.0", "serde", "serde_json", "tempfile", @@ -1706,7 +1692,7 @@ dependencies = [ "hkdf", "hpke", "k256", - "nix", + "nix 0.29.0", "rand 0.10.2", "rand 0.9.5", "rand_chacha 0.3.1", @@ -1765,7 +1751,7 @@ dependencies = [ "elastos-wallet-contract", "hex", "k256", - "nix", + "nix 0.29.0", "serde", "serde_json", "sha2 0.10.9", @@ -3925,6 +3911,18 @@ dependencies = [ "libc", ] +[[package]] +name = "nix" +version = "0.31.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d" +dependencies = [ + "bitflags", + "cfg-if", + "cfg_aliases", + "libc", +] + [[package]] name = "nom" version = "7.1.3" @@ -6164,6 +6162,12 @@ dependencies = [ "utf-8", ] +[[package]] +name = "typed-path" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e" + [[package]] name = "typenum" version = "1.20.1" @@ -7703,18 +7707,16 @@ dependencies = [ [[package]] name = "zip" -version = "2.4.2" +version = "9.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50" +checksum = "a954114b47a54df49f83d2722814e86b23d4bb1b54a1b90fb7d92b41619ddc22" dependencies = [ - "arbitrary", "crc32fast", - "crossbeam-utils", - "displaydoc", "flate2", "indexmap", "memchr", - "thiserror 2.0.20", + "nix 0.31.3", + "typed-path", ] [[package]] diff --git a/elastos/crates/elastos-server/Cargo.toml b/elastos/crates/elastos-server/Cargo.toml index 84788f1d5..e54e95885 100644 --- a/elastos/crates/elastos-server/Cargo.toml +++ b/elastos/crates/elastos-server/Cargo.toml @@ -104,7 +104,7 @@ tempfile = "3.10" # Archive extraction (for capsule artifacts) flate2 = "1.0" tar = "0.4" -zip = { version = "2.4.2", default-features = false, features = ["deflate-flate2", "flate2"] } +zip = { version = "9.0.4", default-features = false, features = ["deflate-flate2"] } libc = "0.2" # Built-in Carrier transport (P2P for updates, gossip messaging, DHT discovery). diff --git a/elastos/crates/elastos-server/src/api/gateway_tests/library.rs b/elastos/crates/elastos-server/src/api/gateway_tests/library.rs index d8477c0db..0253c229f 100644 --- a/elastos/crates/elastos-server/src/api/gateway_tests/library.rs +++ b/elastos/crates/elastos-server/src/api/gateway_tests/library.rs @@ -892,7 +892,7 @@ fn zip_text_files(bytes: &[u8]) -> std::collections::BTreeMap { if entry.is_dir() { continue; } - let name = entry.name().to_string(); + let name = entry.name().unwrap().into_owned(); let mut body = String::new(); entry.read_to_string(&mut body).unwrap(); files.insert(name, body); @@ -3870,6 +3870,203 @@ async fn test_library_provider_rejects_unsafe_zip_entries() { .contains("relative and safe")); } +/// Every path under `root` (files, folders and symlinks, not followed). +fn walk_paths(root: &std::path::Path) -> Vec { + let mut out = Vec::new(); + let mut stack = vec![root.to_path_buf()]; + while let Some(dir) = stack.pop() { + for entry in std::fs::read_dir(&dir).unwrap() { + let entry = entry.unwrap(); + let path = entry.path(); + if entry.file_type().unwrap().is_dir() { + stack.push(path.clone()); + } + out.push(path); + } + } + out +} + +#[tokio::test] +async fn test_library_provider_extract_zip_refuses_absolute_dotdot_and_symlink_entries() { + use std::io::Write as _; + + let dir = tempfile::tempdir().unwrap(); + let app = gateway_router(library_test_state(dir.path()).await); + let authority = passkey_authority_with_name(dir.path(), Some("admin")); + let token = app_token_for_authority(dir.path(), LIBRARY_CAPSULE_ID, &authority); + let root = crate::auth::principal_localhost_root(&authority.principal_id); + let documents_uri = format!("{root}/Documents"); + let imports_uri = format!("{documents_uri}/Imports"); + + let (status, _) = post_library( + app.clone(), + &token, + "mkdir", + json!({ "parent_uri": root, "name": "Documents" }), + ) + .await; + assert_eq!(status, StatusCode::OK); + let (status, _) = post_library( + app.clone(), + &token, + "mkdir", + json!({ "parent_uri": documents_uri, "name": "Imports" }), + ) + .await; + assert_eq!(status, StatusCode::OK); + + let options = + zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored); + // Each archive holds one hostile entry. The whole-archive extract must + // refuse it and write nothing for it, inside or outside the Library. + // (archive name, entry kind, entry name, symlink target, expected message) + let cases: [(&str, &str, &str, &str, &str); 5] = [ + ( + "Absolute.zip", + "file", + "/absolute-escape.txt", + "", + "relative and safe", + ), + ( + "DotDot.zip", + "file", + "../dotdot-escape.txt", + "", + "relative and safe", + ), + ( + "Inner.zip", + "file", + "Nested/../inner-escape.txt", + "", + "relative and safe", + ), + ( + "Backslash.zip", + "file", + "..\\backslash-escape.txt", + "", + "invalid library object name", + ), + ( + "Symlink.zip", + "symlink", + "symlink-escape.txt", + "/etc/passwd", + "non-file", + ), + ]; + for (archive_name, kind, entry_name, link_target, expected) in cases { + let archive_bytes = { + let mut writer = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); + if kind == "symlink" { + writer + .add_symlink(entry_name, link_target, options) + .unwrap(); + } else { + writer.start_file(entry_name, options).unwrap(); + writer.write_all(b"escape").unwrap(); + } + writer.finish().unwrap().into_inner() + }; + let zip_uri = format!("{documents_uri}/{archive_name}"); + let (write_status, write) = post_library( + app.clone(), + &token, + "write", + json!({ + "uri": zip_uri, + "mime": "application/zip", + "data": base64::engine::general_purpose::STANDARD.encode(archive_bytes), + }), + ) + .await; + assert_eq!(write_status, StatusCode::OK, "{archive_name}"); + assert_eq!(write["status"], "ok", "{archive_name}: {write}"); + + let (extract_status, extracted) = post_library( + app.clone(), + &token, + "extract_archive", + json!({ "uri": zip_uri }), + ) + .await; + assert_eq!(extract_status, StatusCode::OK, "{archive_name}"); + assert_eq!( + extracted["status"], "error", + "{archive_name}: hostile entry {entry_name:?} was not refused: {extracted}" + ); + assert!( + extracted["message"].as_str().unwrap().contains(expected), + "{archive_name}: {extracted}" + ); + + if kind == "symlink" { + // The listing marks it blocked and a selected extract refuses it. + let (list_status, listed) = post_library( + app.clone(), + &token, + "archive_entries", + json!({ "uri": zip_uri }), + ) + .await; + assert_eq!(list_status, StatusCode::OK); + let rows = listed["data"]["entries"].as_array().unwrap(); + assert!( + rows.iter().any(|entry| entry["path"] == entry_name + && entry["kind"] == "blocked" + && entry["safety"]["reason"] + .as_str() + .unwrap() + .contains("non-file")), + "{listed}" + ); + let (select_status, selected) = post_library( + app.clone(), + &token, + "archive_extract_entries", + json!({ + "uri": zip_uri, + "destination_uri": imports_uri, + "entries": [entry_name], + }), + ) + .await; + assert_eq!(select_status, StatusCode::OK); + assert_eq!(selected["status"], "ok", "{selected}"); + assert_eq!( + selected["data"]["receipt"]["progress"]["blocked_entries"], + 1 + ); + assert!(selected["data"]["blocked"][0]["reason"] + .as_str() + .unwrap() + .contains("non-file")); + } + } + + // Nothing from any hostile entry exists anywhere under the data dir, and + // no symlink was created. + for path in walk_paths(dir.path()) { + let name = path.file_name().unwrap().to_string_lossy().to_string(); + assert!( + !name.contains("escape"), + "hostile entry was written: {}", + path.display() + ); + assert!( + !std::fs::symlink_metadata(&path) + .unwrap() + .file_type() + .is_symlink(), + "symlink was created: {}", + path.display() + ); + } +} + #[tokio::test] async fn test_library_gateway_reads_webspace_files_through_runtime_provider() { let dir = tempfile::tempdir().unwrap(); diff --git a/elastos/crates/elastos-server/src/library.rs b/elastos/crates/elastos-server/src/library.rs index 9e537d229..84c791d0a 100644 --- a/elastos/crates/elastos-server/src/library.rs +++ b/elastos/crates/elastos-server/src/library.rs @@ -4239,7 +4239,10 @@ fn preview_zip_archive_entry( let mut file = archive .by_index(index) .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))?; - let raw_name = file.name().to_string(); + let raw_name = file + .name() + .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))? + .into_owned(); let Ok(normalized) = normalized_archive_entry_path(Path::new(&raw_name)) else { continue; }; @@ -4457,7 +4460,10 @@ fn list_zip_archive_entries(bytes: Vec) -> anyhow::Result<(Vec, bool) let file = archive .by_index(index) .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))?; - let raw_name = file.name().to_string(); + let raw_name = file + .name() + .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))? + .into_owned(); let path = Path::new(&raw_name); let normalized = match normalized_archive_entry_path(path) { Ok(path) => path, @@ -4939,7 +4945,10 @@ fn collect_selected_zip_writes( let mut file = archive .by_index(index) .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))?; - let raw_name = file.name().to_string(); + let raw_name = file + .name() + .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))? + .into_owned(); let normalized = match normalized_archive_entry_path(Path::new(&raw_name)) { Ok(path) => path, Err(err) => { @@ -5429,8 +5438,10 @@ fn extract_zip_archive( let mut file = archive .by_index(index) .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))?; - let entry_path = file - .enclosed_name() + let raw_name = file + .name() + .map_err(|err| anyhow!("invalid ZIP archive entry: {err}"))?; + let entry_path = zip_entry_enclosed_path(&raw_name) .ok_or_else(|| anyhow!("library archive entry path must be relative and safe"))?; let entry_uri = archive_entry_uri(&destination.uri, &entry_path)?; if entry_uri == destination.uri { @@ -5461,6 +5472,29 @@ fn extract_zip_archive( Ok(()) } +/// The path a whole-archive ZIP extract writes for an entry name, or `None` +/// when the name holds a NUL byte, is absolute (a root or a drive prefix), or +/// climbs above the archive root. `archive_entry_uri` then refuses any `..` +/// that is left. This keeps the rule in the runtime: zip 9 `enclosed_name` +/// strips a leading `/` or drive prefix and folds `..` instead, which would +/// write entries that this extract refuses. +fn zip_entry_enclosed_path(name: &str) -> Option { + if name.contains('\0') { + return None; + } + let path = PathBuf::from(name); + let mut depth = 0usize; + for component in path.components() { + match component { + Component::Prefix(_) | Component::RootDir => return None, + Component::ParentDir => depth = depth.checked_sub(1)?, + Component::Normal(_) => depth += 1, + Component::CurDir => {} + } + } + Some(path) +} + fn archive_entry_uri(destination_uri: &str, path: &Path) -> anyhow::Result { let mut uri = destination_uri.trim_end_matches('/').to_string(); for component in path.components() { From 38e2d777cf38c3e2a1beb81050570219b8e6afa4 Mon Sep 17 00:00:00 2001 From: Anders Alm Date: Sat, 17 Oct 2026 09:52:37 +0000 Subject: [PATCH 7/8] model-provider: held-lock journal test takes its lock with the bounded retry (#381) Port of develop commit 50515055 (Anders Alm). The test flaked in CI with "WouldBlock" at journal.rs:4223 on PR heads that predate the fix. (cherry picked from commit 505150556cf3ed34357c55fecdb3c3533d8d47c3) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- capsules/model-provider/src/journal.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/capsules/model-provider/src/journal.rs b/capsules/model-provider/src/journal.rs index b711b092d..d3c6878f2 100644 --- a/capsules/model-provider/src/journal.rs +++ b/capsules/model-provider/src/journal.rs @@ -4220,7 +4220,10 @@ mod tests { } let temp_before = file_bytes(&temp); let writer = open_journal_directory(&directory).unwrap(); - writer.try_lock().unwrap(); + // A child forked on another test thread can briefly hold a copy of an + // earlier lock fd on this directory (#381); take the lock with the + // provider's own bounded retry instead of one try. + lock_journal_directory(&writer).unwrap(); assert_eq!( RunJournal::open(root.clone()).err().unwrap().code(), "selection_unavailable" From 8bdc380342f2d714bd0f5be9e8dbc4d70383c417 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 12:33:17 +0000 Subject: [PATCH 8/8] docs: WSL2 notes state the localhost origin, python3 and the open proof Issue #265 owns the WSL2 proof and is not yet proven, so the note no longer calls it an executed proof. The Home origin is localhost everywhere, as the launcher contract states, because browsers refuse passkeys on an IP-address origin. The note adds the tools the installer needs in the distro, with python3 for the release checks, and says a second Home tab is possible but not certain. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- docs/WINDOWS.md | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index b5007ecc0..6c0cde347 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -20,8 +20,9 @@ Browser contracts. Capsules must not branch on Windows or learn host topology. ## First Windows product: WSL2 The first honest Windows product runs the Linux Runtime locally inside WSL2. -The executed proof for that product is -[issue #265](https://github.com/Elacity/elastos-runtime/issues/265). +[Issue #265](https://github.com/Elacity/elastos-runtime/issues/265) owns the +proof for that product. Until its acceptance items are proven, this section is +a target, not a result. - Package the Runtime as a signed or importable ElastOS WSL distribution. - A Windows launcher starts, stops, updates, and health-checks the Linux @@ -58,11 +59,22 @@ Inside a distro, `uname -s` is `Linux`. `detect_platform` that is not `Linux` or `Darwin`. A Windows launcher starts the distro and runs the Linux installer and binary there. +### Tools in the distro + +The installer needs `curl`, `python3`, and `sha256sum` or `shasum` inside the +distro (`scripts/install.sh:35`). It stops before it downloads anything when +`curl` or `python3` is missing or `python3` does not run, and when neither +SHA-256 tool is present (`scripts/install.sh:1177-1191`). `python3` runs the +release checks: `verify_signature` (`scripts/install.sh:683`) and +`validate_release_identity` (`scripts/install.sh:830`). A WSL2 distro without +`python3` cannot install the Runtime. A launcher checks for these tools, or +installs them, before it runs `install.sh`. + ### Home origin The [launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url) is the one source for the Home URL that a launcher opens and for the passkey origin. -This note does not repeat that value. It records what the Runtime code serves: +This note does not repeat the URL. It records what the Runtime code serves: - `elastos home --browser` binds the host name `localhost` at `BROWSER_HOME_PORT` (`gateway_entry.rs:17-31`, @@ -82,21 +94,26 @@ This note does not repeat that value. It records what the Runtime code serves: `127.0.0.1` at the same port (`main.rs:438-441`). `localhost` and `127.0.0.1` are different browser origins. A passkey that is -registered on one origin does not sign in on the other. The desktop launcher -and the launcher contract do not use the same host name for the Home origin -today. That is an open gap. The team decides the canonical origin, and this -note does not choose one. +registered on one origin does not sign in on the other. Browsers refuse +passkeys (WebAuthn) on an IP-address origin such as `http://127.0.0.1:8090`, +so passkeys work only on `localhost`. The Home origin is decided: `localhost` +everywhere. The launcher contract states it, and a WSL2 launcher opens and +probes Home on `localhost`, as on every other computer. `docs/INSTALL.md` describes `elastos home --browser`. The source-build guides `docs/MAC.md` and `docs/HOME_LOCAL_SETUP.md` use a developer gateway on a different port. That is a developer lane, not the installed product. -`elastos home --browser` opens a browser itself. `browser_home_ready` +`elastos home --browser` can open a browser itself. `browser_home_ready` (`gateway_entry.rs:33-40`) prints the URL and calls `open_browser` -(`main.rs:2268-2283`). On Linux, `open_browser` tries `wslview` and then -`xdg-open`. It skips the open after an update restart -(`ELASTOS_UPDATE_RESTART=1`). There is no flag that stops this open, so a -launcher that also opens Home makes a second tab. That is a gap. +(`main.rs:2268-2283`). On Linux, `open_browser` starts `wslview` and, if that +cannot start, `xdg-open`. It does not check that a page opened. It skips the +open after an update restart (`ELASTOS_UPDATE_RESTART=1`). There is no flag +that stops this open. A launcher that runs `elastos home --browser` and also +opens Home can thus get a second tab. This is possible, not certain: it +depends on whether `wslview` or `xdg-open` is in the distro and can reach a +Windows browser. That is a gap. `elastos gateway` (`gateway_entry.rs:1-15`) +opens no browser. ### Release verification