microsandbox-rb 0.16.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 011c5bcfdd4eff6b2f86ec6ded70720520b5c77d93ceb575dc4ac9b0ce0a5078
-  data.tar.gz: 2e84a073bd4852e2cdbc124f4ce6b400beb5b20012c6b9ff81833169f13d58e1
+  metadata.gz: 8fbc8d09d8029bef1ec00d128bf554b037c937e51ebe8b9b8a6014043fce178e
+  data.tar.gz: 626313c0471102e108793f3880bcd1f1e30ba9f48470274bf53495a86cfadff7
 SHA512:
-  metadata.gz: 6a12d8b308f479630dc8b266c3129bb7e337939da1963faf975fda7ebb890fe95d50ccbf77b37e9f33d3ccb0506dd94633e0374ac6c52cac599c6c80348ee931
-  data.tar.gz: 730a26aef15b87d348e95a23ede127520aee10d410856526f956d3366118959dc51f60d418e7c876781191be0c72009daafaa442a353afc6b6010643adf1a46f
+  metadata.gz: 49461a4a9ca44f5af82d62fe30086bd4b153d3885267274fce7de8328b071cb418055f202b3b2feea3f149d76572a2a78874596c707ac094d62f7cc5171269aa
+  data.tar.gz: 929b0a19b88eb839d371899191e6a0229eded4eb616100dbd8d316352eac3bf68dcfefa91fb04c4ce41ad540deaa41233c1533d2471222bbf4772d8708451be6

data/CHANGELOG.md

@@ -6,6 +6,235 @@ All notable changes to this gem are documented here. The format is based on
 microsandbox runtime it embeds; each release notes the upstream runtime tag it
 wraps, and the README's Versioning section keeps the full gem→runtime map.
 
+## [Unreleased]
+
+## [0.17.1] - 2026-10-12
+
+Gem-only security and hardening release; the embedded runtime stays at
+**`v0.6.18`**. Upgrading is recommended for everyone on `0.17.0` or earlier.
+Two fixes tighten input handling and can reject input that used to be
+accepted: `Volume.fs` paths containing a `..` segment, and
+`Microsandbox.runtime_path = nil`.
+
+### Security
+
+- **Relative host paths are pinned when a sandbox is created**
+  ([GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm),
+  high; fixed upstream in runtime `v0.7.6`, which this gem does not embed yet).
+  The embedded runtime stored a relative host path exactly as written and
+  resolved it against the working directory of whichever process later
+  started the sandbox, so restarting a sandbox from another directory mounted
+  a different host directory than the one originally intended. The native
+  layer now anchors every relative host path to the creating process's
+  directory before the configuration is persisted: bind and disk mount
+  sources in `volumes:`, a directory or disk-image `image:`, a `root_disk:`
+  image path, `Patch.copy_file` / `Patch.copy_dir` sources, the `tls:`
+  certificate paths, and a path-form `from_snapshot:`. This covers sandboxes
+  created through the gem; the `msb` CLI the gem installs is unchanged, so use
+  absolute paths with it. Paths are anchored
+  without following symlinks and without requiring the target to exist, so a
+  symlinked bind-mount root is still refused unless
+  `follow_root_symlinks: true`. Absolute paths, named volumes, and OCI
+  references are unchanged, and on a cloud backend paths are forwarded as
+  written (they belong to the remote host).
+
+  **Existing sandboxes are not rewritten.** A sandbox created by an earlier
+  gem version with a relative path keeps that saved path and its old
+  behaviour: recreate it, or only ever start it from its original directory.
+  Affects every earlier `microsandbox-rb` release; the upstream advisory does
+  not list this gem.
+- **Errors no longer repeat values that can be credentials.** A URL-style
+  proxy address (`socks5://user:pass@host:port`) is refused by shape without
+  being echoed; an `env:` / `labels:` / `scripts:` value that is not a Hash
+  (or convertible to one, like `ENV`), a malformed patch, and a non-Hash
+  secret spec are reported by class name only.
+- **Dependencies with published advisories updated in `Cargo.lock`**:
+  `russh` 0.63.1 → 0.63.3 (GHSA-35g8-35p8-c8fw, SSH server side),
+  `rustls` 0.23.41 → 0.23.45 (RUSTSEC-2026-0285), `h2` 0.4.15 → 0.4.16
+  (RUSTSEC-2026-0258), plus `anyhow` 1.0.104 and `event-listener` 5.4.2
+  (unsoundness fixes). Those pulled in `aws-lc-rs` 1.18.1, `aws-lc-sys`
+  0.45.0, `rustls-webpki` 0.103.15, and `num-bigint` 0.5.1 in place of
+  `internal-russh-num-bigint`. `rkyv` and `rsa` have no compatible fixed
+  release at the pinned runtime and are unchanged.
+
+### Added
+
+- `SECURITY.md`: how to report a vulnerability privately, and a table mapping
+  upstream microsandbox advisories to the `microsandbox-rb` versions they
+  affect (upstream advisories do not list this gem). Shipped in the gem.
+- `require "microsandbox-rb"` as an entry point named after the gem. Outside
+  Bundler, `require "microsandbox"` can resolve to the unrelated `microsandbox`
+  gem on RubyGems.
+
+### Fixed
+
+- **Documentation examples that did not run.** The README quick start failed
+  on its second run (`SandboxAlreadyExistsError`; it now uses
+  `ephemeral: true`), and the README / configuration-guide `secrets:` example
+  used the `#modify` shape and raised `TypeError`. The observability and
+  errors guides named the wrong error class for the metrics startup window
+  (it is the base `Microsandbox::Error`, matched by message), and
+  `log_stream(follow: true)` was documented as ending when the sandbox stops
+  (it does not). The guides now also state that an inline secret `value:` is
+  stored in cleartext in the local catalog until the sandbox is removed, that
+  the block form stops but does not remove, that a runtime home belongs to one
+  runtime line (`MSB_HOME`), and list known issues at the pinned runtime
+  (including guest `fallocate` truncating bind-mounted files on macOS hosts).
+- **A rejected option no longer triggers a runtime download.** The first-use
+  runtime check ran before most argument validation, so `Sandbox.create` with
+  a bad option downloaded and installed `msb` before raising. It now runs
+  after the options are validated, in `create`, `connect_or_create` and
+  `create_with_progress`.
+- **First-use provisioning is serialized within a process.** Several threads
+  making their first `Sandbox.create` at once each ran the installer, which
+  replaces files in place. `Microsandbox.install`, `Microsandbox.setup` and
+  the first-use check now share one lock, and the check runs once.
+- **`Microsandbox.runtime_path = nil` / `libkrunfw_path = nil`** (or `""`)
+  raise `ArgumentError` instead of writing an empty path into the set-once
+  slot for the rest of the process.
+- **Companion gem detection no longer depends on the host project's name.**
+  When the host project is itself a gem with its bundle installed inside the
+  project directory, `microsandbox-rb-binaries` could be attributed to the
+  host project and ignored, depending on gem load order. The owner is now
+  the gem with the innermost matching root.
+- **`patches:` with `from_snapshot:`** raises `ArgumentError` up front. The
+  runtime rejects the pair only after claiming the sandbox name on disk,
+  which left an empty directory holding the name.
+- **Block forms keep the caller's exception.** `fs.write_stream { }`,
+  `ssh.open_client { }` and `client.sftp { }` closed in a bare `ensure`, so a
+  failing close replaced whatever the block had raised. The block's exception
+  now wins; a close failure is still raised when the block itself succeeded.
+- **`PullSession#sandbox`** re-raises the original create failure when called
+  again, instead of an unrelated "already taken" error.
+- **Timestamps are exact to the millisecond.** `Time.at(ms / 1000.0)` went
+  through a Float and reported one millisecond low for about half of all
+  values (`FsEntry#modified`, `FsMetadata#modified` / `#created`,
+  `LogEntry#timestamp`, `Metrics#timestamp`, and every `created_at` /
+  `updated_at` / `last_used_at` / `observed_at` reader).
+- **`secrets:` given as a `{ "NAME" => { ... } }` Hash** (the `#modify`
+  shape) raises a descriptive `ArgumentError` instead of `TypeError`; a single
+  bare spec Hash is accepted as a list of one, as is a single patch Hash for
+  `patches:`.
+
+### Changed
+
+- **`Volume.fs` paths may not contain a `..` segment.** Every `VolumeFs` operation
+  (`read`, `read_text`, `write`, `list`, `mkdir`, `remove_file`, `remove_dir`,
+  `exists?`, `copy`, `rename`, `stat`) now refuses a path that contains a `..`
+  segment with `FilesystemError`, in the native layer as well as the Ruby
+  wrapper. Volume paths are relative to the volume root and never need one.
+  A path such as `"a/../b"` that used to be accepted must now be written as
+  `"b"`. Names that merely contain dots (`"..hidden"`, `"a..b"`) are fine.
+- **README restructured** along the lines of a conventional Ruby SDK README:
+  badges, a Highlights list, a short install + quick start, a Documentation
+  table, and a sourced comparison with the official `microsandbox` gem. The
+  detailed guides moved into `docs/` (`lifecycle`, `configuration`,
+  `execution`, `filesystem`, `observability`, `images`, `runtime`, `errors`,
+  `surface`, `releasing`), which the gem now ships (`spec.files`), so the
+  links resolve on rubygems.org and rubydoc.info. `docs/surface.md` replaces
+  the duplicated implemented-surface prose in README and `DESIGN.md` as the
+  single scope statement. `docs/errors.md` lists every error class and marks
+  the four the native layer does not currently raise (`PathNotFoundError`,
+  `ImagePullFailedError`, `SecretViolationError`, `TlsError`) as reserved.
+
+## [0.17.0] - 2026-09-13
+
+Adopts upstream runtime **`v0.6.16` → `v0.6.18`**, stepping through the
+intermediate tag (`v0.6.17` verified and committed on its own).
+
+### Added
+
+- **Strict hostname policy** — `strict:` (Boolean, default `false`) on
+  `Sandbox.create` / `connect_or_create` / `create_with_progress` (upstream
+  `v0.6.18`, from the security fork-merge below). In strict mode a flow that the
+  egress policy allows *only* through a hostname rule must be backed by an
+  inspectable request authority — the plain-HTTP `Host` header, or SNI /
+  `:authority` under TLS interception. Without that visibility (bypassed or
+  non-intercepted HTTPS) the runtime fails closed *before* dialing upstream
+  instead of trusting opaque hostname evidence. Mirrors the Python SDK's
+  `Network(strict=...)`. An explicit `false` is sent as-is (not dropped), like
+  `trust_host_cas:`. Create-only in Ruby, matching the Python SDK's `modify`
+  surface (which does not expose `strict`); the core itself does carry a
+  generated `strict` field on its network config patch (`ConfigPatch` derive),
+  so this is an SDK-parity choice, not a core limitation. Accepted by the cloud
+  create contract (`CloudNetworkSpec.strict`), so there is no `UnsupportedError`
+  path.
+
+- **Outbound SOCKS proxies** — `proxy:` on `Sandbox.create` /
+  `connect_or_create` / `create_with_progress` (upstream #1234 SOCKS4/SOCKS5
+  and #1507 SOCKS5 UDP + credentials, `v0.6.17`). The runtime's host-side
+  network stack dials the proxy for the sandbox's egress — SOCKS4 for TCP,
+  SOCKS5 for TCP and non-DNS UDP — uniformly for TLS-intercepted and
+  bypassed/plain TCP, while the egress policy (`network:`) still decides which
+  destinations may be reached. The address is resolved from the **host**
+  (`127.0.0.1` is the host's loopback). Spelled like the Python SDK's
+  `proxy=`, as a top-level create option rather than inside `network:`:
+  - `Microsandbox::OutboundProxy.socks4(address, user_id: nil)` and
+    `Microsandbox::OutboundProxy.socks5(address)`, the latter chaining
+    `#credentials(username, password)` which returns a **new** proxy (the
+    objects are immutable, like Python's frozen dataclass).
+  - `Microsandbox::SecretSource.env("VAR")` — the only password source: the
+    host environment variable's *name* is what reaches the runtime, which reads
+    the value host-side. No password value ever travels through the binding or
+    appears in `inspect`/error output.
+  - The equivalent plain Hash is accepted too: `{ protocol: :socks5,
+    address: "IP:port", credentials: { username:, password: { env: "VAR" } } }`
+    or `{ protocol: :socks4, address:, user_id: }`.
+  - Validation mirrors the Python SDK's `OutboundProxy.__post_init__`
+    (`ArgumentError`): `user_id` only for SOCKS4, credentials only for SOCKS5,
+    username and password together or neither, a non-empty String address.
+    `IP:port` parsing is left to the core, which reports an unparseable address
+    (or an invalid SOCKS4 user ID) at create time, before any boot; the binding
+    surfaces that as `InvalidConfigError` — a malformed proxy is a configuration
+    mistake, not a policy one — while every other network-builder error keeps
+    its `NetworkPolicyError` class. The cloud backend rejects the option with
+    `UnsupportedError` (`sandbox.create`, hint naming `network.outbound_proxy`).
+
+### Changed
+
+- **Plain-HTTP requests are now checked against the egress policy by their
+  `Host` / `:authority`, whenever the policy has any domain rule — in
+  non-strict mode too** (upstream `v0.6.18` hardening, `crates/network/lib/
+  tcp/proxy.rs`: `enforce_http_authority = network_policy.has_domain_rules()`).
+  Previously a plain-HTTP connection admitted by an IP/CIDR/group rule could
+  name any host in its `Host` header; now, if the policy carries `Domain` /
+  `DomainSuffix` rules (including `deny_domains:` / `deny_domain_suffixes:`,
+  which are domain rules), the request's authority is evaluated against the
+  **ordered** egress policy (rules first, then `default_egress`) together with
+  the real destination IP/port, and — for a request carrying valid authority
+  metadata — the request is denied only when that evaluation denies it.
+  Separately, a plain-HTTP request with a *missing*, *duplicate* or
+  *unparsable* `Host` / `:authority` is now rejected outright whenever domain
+  rules are present (the upstream validator requires exactly one well-formed
+  authority before any policy evaluation), so an HTTP/1.0 request without a
+  `Host` header no longer passes on such a policy. Existing IP/CIDR/group allows and a permissive
+  `default_egress` still count: a plain-HTTP request to an allowed IP that
+  sends an unrelated `Host` is still allowed unless a rule (or the default)
+  denies that hostname. Policies with no domain rules are unaffected, and so is
+  HTTPS without interception. What changes in practice: an IP-based request
+  whose `Host` names a host the ordered policy *denies* (a `deny_domains:`
+  entry, or a domain not matched by any allow under `default_egress: :deny`)
+  now fails even in non-strict mode — allow the hostname it actually sends.
+  `strict:` is not a substitute for a restrictive policy; it only tightens
+  hostname-rule allows that lack an inspectable authority.
+
+### Security
+
+- Runtime `v0.6.18` carries the upstream security fork-merge (`439a88a5`, no
+  public advisory identifier at the time of writing): aligns HTTP `Host` policy
+  checks with the rest of the egress enforcement (the Changed note above) and
+  adds the fail-closed pre-connect strict hostname mode (`strict:` above). No
+  gem-side change was needed beyond exposing `strict:`.
+
+### Fixed
+
+- Runtime `v0.6.17` restores the released database-migration order (upstream
+  #1517, fixing #1502): a local `~/.microsandbox` database last opened by an
+  upstream **`v0.6.15`** binary — typically the `msb` CLI, since this gem never
+  shipped `v0.6.15` on its own — failed to open under `v0.6.16` with "database
+  schema is newer than this msb binary". Any such database now migrates
+  forward cleanly on the next `require "microsandbox"` + first operation.
+
 ## [0.16.0] - 2026-09-01
 
 Adopts upstream runtime **`v0.6.14` → `v0.6.16`**, stepping through the
@@ -1162,7 +1391,11 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.1...HEAD
+[0.17.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.0...v0.17.1
+[0.17.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.16.0...v0.17.0
+[0.16.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.13.0...v0.14.0
 [0.9.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.1...v0.8.2