microsandbox-rb 0.16.0 → 0.17.1

data/ext/microsandbox/src/sandbox.rs

@@ -7,6 +7,7 @@
 //! as a plain Ruby `Hash`/`Array`/`String` and shaped into value objects by the
 //! Ruby layer.
 
+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -39,6 +40,7 @@ use tokio::task::JoinHandle;
 use crate::conv;
 use crate::error;
 use crate::exec::ExecHandle;
+use crate::host_path::{self, HostPaths};
 use crate::runtime::{block_on, ruby};
 use crate::stream::{LogStream, MetricsStream};
 
@@ -75,6 +77,9 @@ impl Sandbox {
     /// Shared by `create` (blocking) and `create_with_progress` (streaming pull).
     fn build_builder(name: String, opts: RHash) -> Result<SandboxBuilder, Error> {
         let mut b = microsandbox::Sandbox::builder(name);
+        // Relative host paths are anchored to the current directory here, once,
+        // before the core persists them (see host_path.rs).
+        let host_paths = HostPaths::for_default_backend();
 
         if let Some(v) = conv::opt_string(opts, "image")? {
             if let Some(fstype) = conv::opt_string(opts, "fstype")? {
@@ -83,13 +88,17 @@ impl Sandbox {
                 // image_with(disk().fstype()). (A bare `image` string otherwise
                 // auto-detects OCI vs disk by extension.) Errors in disk()/fstype()
                 // are captured on the builder and surface at create().
-                b = b.image_with(move |i| i.disk(v).fstype(fstype));
+                let path = host_paths.pin(v, "root disk image path")?;
+                b = b.image_with(move |i| i.disk(path).fstype(fstype));
             } else {
-                b = b.image(v);
+                b = match host_paths.pin_image(v)? {
+                    host_path::Image::Text(text) => b.image(text),
+                    host_path::Image::Path(path) => b.image(path),
+                };
             }
         }
         if let Some(v) = conv::opt_string(opts, "from_snapshot")? {
-            b = b.from_snapshot(v);
+            b = b.from_snapshot(host_paths.pin_snapshot(v)?);
         }
         if let Some(v) = conv::opt_u8(opts, "cpus")? {
             b = b.cpus(v);
@@ -208,27 +217,35 @@ impl Sandbox {
             // the per-mount opt-out. Valid for bind/named-directory mounts —
             // the core rejects it elsewhere at build().
             let follow_root_symlinks = conv::opt::<bool>(m, "follow_root_symlinks")?;
-            // bind/named/disk require a source; tmpfs must not have one.
-            match kind.as_str() {
-                "bind" | "named" | "disk" if source.is_some() => {}
-                "bind" | "named" | "disk" => {
+            // bind/named/disk require a source; tmpfs must not have one. A
+            // bind or disk source is a host path; a named source is a volume
+            // name and is never resolved.
+            let backing = match (kind.as_str(), source) {
+                ("bind", Some(host)) => {
+                    MountBacking::Bind(host_paths.pin(host, "bind mount host path")?)
+                }
+                ("disk", Some(host)) => {
+                    MountBacking::Disk(host_paths.pin(host, "disk mount host path")?)
+                }
+                ("named", Some(name)) => MountBacking::Named(name),
+                ("bind" | "named" | "disk", None) => {
                     return Err(error::base_error(format!(
                         "volume mount kind {kind:?} requires a source"
                     )))
                 }
-                "tmpfs" => {}
-                other => {
+                ("tmpfs", _) => MountBacking::Tmpfs,
+                (other, _) => {
                     return Err(error::base_error(format!(
                         "unknown volume mount kind {other:?} (expected bind/named/tmpfs/disk)"
                     )))
                 }
-            }
+            };
             b = b.volume(guest, move |mut mb| {
-                mb = match kind.as_str() {
-                    "named" => mb.named(source.unwrap()),
-                    "tmpfs" => mb.tmpfs(),
-                    "disk" => mb.disk(source.unwrap()),
-                    _ => mb.bind(source.unwrap()), // "bind"
+                mb = match backing {
+                    MountBacking::Named(name) => mb.named(name),
+                    MountBacking::Tmpfs => mb.tmpfs(),
+                    MountBacking::Disk(host) => mb.disk(host),
+                    MountBacking::Bind(host) => mb.bind(host),
                 };
                 if let Some(n) = size_mib {
                     mb = mb.size(n);
@@ -272,7 +289,7 @@ impl Sandbox {
         // patches: rootfs modifications applied before boot. The Ruby layer
         // normalizes each `Microsandbox::Patch.*` into a string-keyed Hash with
         // a `kind` discriminator; mirrors the Python binding's `apply_patch`.
-        for patch in parse_patches(opts)? {
+        for patch in parse_patches(opts, host_paths)? {
             b = b.add_patch(patch);
         }
         if let Some(net) = conv::opt_string(opts, "network")? {
@@ -326,7 +343,7 @@ impl Sandbox {
         // layer maps the deprecated `oci_upper_size:` kwarg to the managed kind
         // before it reaches the wire.
         if let Some(v) = conv::opt::<Value>(opts, "root_disk")? {
-            let spec = parse_root_disk(v)?;
+            let spec = parse_root_disk(v, host_paths)?;
             b = b.root_disk_with(move |d| spec.apply(d));
         }
         // Registry connection settings, for private / non-default registries:
@@ -374,7 +391,7 @@ impl Sandbox {
             .map(parse_dns)
             .transpose()?;
         let tls = conv::opt::<RHash>(opts, "tls")?
-            .map(parse_tls)
+            .map(|t| parse_tls(t, host_paths))
             .transpose()?;
         let ipv4_pool = conv::opt_string(opts, "ipv4_pool")?
             .map(|s| {
@@ -390,12 +407,22 @@ impl Sandbox {
             .transpose()?;
         let max_connections = conv::opt::<usize>(opts, "max_connections")?;
         let trust_host_cas = conv::opt::<bool>(opts, "trust_host_cas")?;
+        // strict: fail-closed hostname-policy enforcement (v0.6.18). A
+        // hostname-rule allow must be backed by an inspectable request
+        // authority (plain-HTTP Host, or SNI/authority under TLS interception);
+        // otherwise the flow is denied before the upstream dial. Mirrors the
+        // Python SDK's `Network(strict=...)`. Create-only here to match the
+        // Python SDK's `modify` surface, which does not expose `strict`; the
+        // core's generated network config patch (ConfigPatch derive) does
+        // carry a `strict` field, so this is SDK parity, not a core limit.
+        let strict = conv::opt::<bool>(opts, "strict")?;
         if dns.is_some()
             || tls.is_some()
             || ipv4_pool.is_some()
             || ipv6_pool.is_some()
             || max_connections.is_some()
             || trust_host_cas.is_some()
+            || strict.is_some()
         {
             b = b.network(move |mut n| {
                 if let Some(dns) = dns {
@@ -450,6 +477,9 @@ impl Sandbox {
                 if let Some(t) = trust_host_cas {
                     n = n.trust_host_cas(t);
                 }
+                if let Some(s) = strict {
+                    n = n.strict(s);
+                }
                 n
             });
         }
@@ -475,6 +505,18 @@ impl Sandbox {
                 })
             });
         }
+        // proxy: outbound SOCKS4/SOCKS5 proxy for egress traffic (v0.6.17,
+        // upstream #1234/#1507). The Ruby layer (`OutboundProxy.coerce`) has
+        // already validated the shape and normalized it to the Python SDK's
+        // `_to_dict()` wire form: {protocol:, address:, user_id?:,
+        // credentials?: {username:, password: {kind: "env", var:}}}. Only the
+        // password's env var NAME travels; the core resolves it host-side.
+        // Applied exactly as sdk/python/src/helpers.rs does; the address is
+        // parsed by the core's proxy builder (an invalid one surfaces as
+        // NetworkBuilder(InvalidOutboundProxy) → InvalidConfigError, see error.rs).
+        if let Some(proxy) = conv::opt::<RHash>(opts, "proxy")? {
+            b = apply_outbound_proxy(b, proxy)?;
+        }
         // init: hand guest PID 1 to an init system. The Ruby layer normalizes
         // `init:` to a Hash { cmd:, args?:, env?: }. `init_with` with empty
         // args/env builds the same HandoffInit as the plain `init(cmd)`, so route
@@ -1192,7 +1234,7 @@ fn patch_bytes(h: RHash, key: &str) -> Result<Vec<u8>, Error> {
 /// Parse the `patches` option into core `Patch` operations. The Ruby layer
 /// normalizes each `Microsandbox::Patch.*` into a string-keyed Hash carrying a
 /// `kind` discriminator plus the variant-specific fields.
-fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
+fn parse_patches(opts: RHash, host_paths: HostPaths) -> Result<Vec<Patch>, Error> {
     let mut out = Vec::new();
     for h in conv::opt_hash_vec(opts, "patches")? {
         let kind = patch_str(h, "kind")?;
@@ -1216,13 +1258,13 @@ fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
                 content: patch_str(h, "content")?,
             },
             "copy_file" => Patch::CopyFile {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 mode,
                 replace,
             },
             "copy_dir" => Patch::CopyDir {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 replace,
             },
@@ -1420,6 +1462,63 @@ fn parse_dns(d: RHash) -> Result<DnsSpec, Error> {
     })
 }
 
+/// Apply the normalized `proxy` create option (v0.6.17) to the builder.
+/// Mirrors `sdk/python/src/helpers.rs`: `socks4` takes an optional `user_id`,
+/// `socks5` optional `credentials` whose password is an env-backed
+/// [`SecretSource`] (the only kind). Unknown protocols and non-env password
+/// sources are rejected here (the Ruby layer already does, so these are
+/// belt-and-braces for callers of the native API).
+fn apply_outbound_proxy(b: SandboxBuilder, proxy: RHash) -> Result<SandboxBuilder, Error> {
+    let protocol = conv::opt_string(proxy, "protocol")?
+        .ok_or_else(|| error::base_error("proxy requires protocol:"))?;
+    let address = conv::opt_string(proxy, "address")?
+        .ok_or_else(|| error::base_error("proxy requires address:"))?;
+    match protocol.as_str() {
+        "socks4" => {
+            let user_id = conv::opt_string(proxy, "user_id")?;
+            Ok(b.proxy(move |p| {
+                let p = p.socks4(address);
+                match user_id {
+                    Some(user_id) => p.user_id(user_id),
+                    None => p,
+                }
+            }))
+        }
+        "socks5" => {
+            let credentials = match conv::opt::<RHash>(proxy, "credentials")? {
+                None => None,
+                Some(c) => {
+                    let username = conv::opt_string(c, "username")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require username:"))?;
+                    let password = conv::opt::<RHash>(c, "password")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require password:"))?;
+                    let kind = conv::opt_string(password, "kind")?.ok_or_else(|| {
+                        error::base_error("SOCKS5 password source requires kind:")
+                    })?;
+                    if kind != "env" {
+                        return Err(error::base_error(format!(
+                            "unsupported SOCKS5 password source {kind:?}; only env is supported"
+                        )));
+                    }
+                    let var = conv::opt_string(password, "var")?
+                        .ok_or_else(|| error::base_error("SOCKS5 password source requires var:"))?;
+                    Some((username, SecretSource::env(var)))
+                }
+            };
+            Ok(b.proxy(move |p| {
+                let p = p.socks5(address);
+                match credentials {
+                    Some((username, password)) => p.credentials(username, password),
+                    None => p,
+                }
+            }))
+        }
+        other => Err(error::base_error(format!(
+            "unsupported outbound proxy protocol {other:?}; expected socks4 or socks5"
+        ))),
+    }
+}
+
 /// One token bucket of the `rate_limiter` create option (v0.6.9):
 /// `(size, refill_time_ms, one_time_burst)`. Size is bytes for bandwidth
 /// buckets, frames for ops buckets.
@@ -1502,20 +1601,25 @@ struct TlsSpec {
     verify_upstream: Option<bool>,
     intercepted_ports: Option<Vec<u16>>,
     block_quic: Option<bool>,
-    upstream_ca_cert: Option<String>,
-    intercept_ca_cert: Option<String>,
-    intercept_ca_key: Option<String>,
+    upstream_ca_cert: Option<PathBuf>,
+    intercept_ca_cert: Option<PathBuf>,
+    intercept_ca_key: Option<PathBuf>,
 }
 
-fn parse_tls(t: RHash) -> Result<TlsSpec, Error> {
+fn parse_tls(t: RHash, host_paths: HostPaths) -> Result<TlsSpec, Error> {
+    let pin = |key: &str, label: &str| {
+        conv::opt_string(t, key)?
+            .map(|path| host_paths.pin(path, label))
+            .transpose()
+    };
     Ok(TlsSpec {
         bypass: conv::opt_string_vec(t, "bypass")?,
         verify_upstream: conv::opt::<bool>(t, "verify_upstream")?,
         intercepted_ports: conv::opt::<Vec<u16>>(t, "intercepted_ports")?,
         block_quic: conv::opt::<bool>(t, "block_quic")?,
-        upstream_ca_cert: conv::opt_string(t, "upstream_ca_cert")?,
-        intercept_ca_cert: conv::opt_string(t, "intercept_ca_cert")?,
-        intercept_ca_key: conv::opt_string(t, "intercept_ca_key")?,
+        upstream_ca_cert: pin("upstream_ca_cert", "upstream CA certificate path")?,
+        intercept_ca_cert: pin("intercept_ca_cert", "interception CA certificate path")?,
+        intercept_ca_key: pin("intercept_ca_key", "interception CA key path")?,
     })
 }
 
@@ -1629,6 +1733,14 @@ fn network_profile_from_str(s: &str) -> Result<NetworkProfile, Error> {
     }
 }
 
+/// What backs a volume mount, with any host path already pinned.
+enum MountBacking {
+    Bind(PathBuf),
+    Disk(PathBuf),
+    Named(String),
+    Tmpfs,
+}
+
 /// Parsed `root_disk` create option. Integer shorthand = managed upper of N
 /// MiB (mirrors Python's `root_disk=8192` and the CLI bare-size form); Hash =
 /// explicit kind. Kind/field cross-validation (size on a disk image, etc.)
@@ -1644,7 +1756,7 @@ struct RootDiskSpec {
 enum RootDiskKindSpec {
     Managed,
     Tmpfs,
-    Disk(String),
+    Disk(PathBuf),
     Flat,
 }
 
@@ -1672,7 +1784,7 @@ impl RootDiskSpec {
     }
 }
 
-fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
+fn parse_root_disk(v: Value, host_paths: HostPaths) -> Result<RootDiskSpec, Error> {
     if let Ok(mib) = u32::try_convert(v) {
         return Ok(RootDiskSpec {
             kind: RootDiskKindSpec::Managed,
@@ -1695,7 +1807,7 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             let Some(path) = conv::opt_string(h, "path")? else {
                 return Err(error::base_error("root_disk disk kind requires path:"));
             };
-            RootDiskKindSpec::Disk(path)
+            RootDiskKindSpec::Disk(host_paths.pin(path, "root disk image path")?)
         }
         Some("flat") => RootDiskKindSpec::Flat,
         Some(other) => {

data/ext/microsandbox/src/volume.rs

@@ -3,11 +3,12 @@
 //! Mirrors `sdk/python/src/volume.rs`. Static async CRUD over the volume store;
 //! results are returned as plain Ruby Hashes/Arrays.
 
+use std::path::{Component, Path};
 use std::sync::Arc;
 
 use magnus::{function, method, prelude::*, Error, RArray, RHash, RModule, RString, Ruby};
 use microsandbox::volume::VolumeHandle;
-use microsandbox::Backend;
+use microsandbox::{Backend, MicrosandboxError};
 
 use crate::conv;
 use crate::error;
@@ -104,6 +105,23 @@ fn remove(name: String) -> Result<(), Error> {
     block_on(microsandbox::Volume::remove(&name)).map_err(error::to_ruby)
 }
 
+/// Volume paths are relative to the volume root and never need a `..` segment,
+/// so one is refused before the path reaches the core's resolver (which keeps
+/// its own containment check). Enforced here rather than only in the Ruby
+/// wrapper because `Microsandbox::Native::VolumeFs` is callable directly.
+fn contained(path: &str) -> Result<&str, Error> {
+    if Path::new(path)
+        .components()
+        .any(|part| matches!(part, Component::ParentDir))
+    {
+        return Err(error::to_ruby(MicrosandboxError::SandboxFsOps(
+            "path traversal outside volume root (`..` segments are not allowed in volume paths)"
+                .into(),
+        )));
+    }
+    Ok(path)
+}
+
 /// A host-side filesystem view over a named volume — read/write its contents
 /// without a running sandbox. Mirrors the Python `VolumeFs` / Node `VolumeFs`.
 /// The core `VolumeFs<'a>` borrows the volume name, so (like the Python binding)
@@ -131,26 +149,30 @@ impl VolumeFs {
     }
 
     fn read(&self, path: String) -> Result<RString, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let bytes = block_on(fs.read(&path)).map_err(error::to_ruby)?;
+        let bytes = block_on(fs.read(path)).map_err(error::to_ruby)?;
         Ok(ruby().str_from_slice(bytes.as_ref()))
     }
 
     fn read_text(&self, path: String) -> Result<String, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.read_to_string(&path)).map_err(error::to_ruby)
+        block_on(fs.read_to_string(path)).map_err(error::to_ruby)
     }
 
     fn write(&self, path: String, data: RString) -> Result<(), Error> {
         // Copy the bytes out while the GVL is held (GC.compact could move them).
         let bytes = unsafe { data.as_slice() }.to_vec();
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.write(&path, &bytes)).map_err(error::to_ruby)
+        block_on(fs.write(path, &bytes)).map_err(error::to_ruby)
     }
 
     fn list(&self, path: String) -> Result<RArray, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let entries = block_on(fs.list(&path)).map_err(error::to_ruby)?;
+        let entries = block_on(fs.list(path)).map_err(error::to_ruby)?;
         let arr = ruby().ary_new();
         for entry in &entries {
             arr.push(fs_entry_to_hash(entry))?;
@@ -159,38 +181,47 @@ impl VolumeFs {
     }
 
     fn mkdir(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.mkdir(&path)).map_err(error::to_ruby)
+        block_on(fs.mkdir(path)).map_err(error::to_ruby)
     }
 
     fn remove_file(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.remove(&path)).map_err(error::to_ruby)
+        block_on(fs.remove(path)).map_err(error::to_ruby)
     }
 
     fn remove_dir(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.remove_dir(&path)).map_err(error::to_ruby)
+        block_on(fs.remove_dir(path)).map_err(error::to_ruby)
     }
 
     fn exists(&self, path: String) -> Result<bool, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.exists(&path)).map_err(error::to_ruby)
+        block_on(fs.exists(path)).map_err(error::to_ruby)
     }
 
     fn copy(&self, from: String, to: String) -> Result<(), Error> {
+        let from = contained(&from)?;
+        let to = contained(&to)?;
         let fs = self.fs();
-        block_on(fs.copy(&from, &to)).map_err(error::to_ruby)
+        block_on(fs.copy(from, to)).map_err(error::to_ruby)
     }
 
     fn rename(&self, from: String, to: String) -> Result<(), Error> {
+        let from = contained(&from)?;
+        let to = contained(&to)?;
         let fs = self.fs();
-        block_on(fs.rename(&from, &to)).map_err(error::to_ruby)
+        block_on(fs.rename(from, to)).map_err(error::to_ruby)
     }
 
     fn stat(&self, path: String) -> Result<RHash, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let meta = block_on(fs.stat(&path)).map_err(error::to_ruby)?;
+        let meta = block_on(fs.stat(path)).map_err(error::to_ruby)?;
         Ok(fs_metadata_to_hash(&meta))
     }
 }

data/lib/microsandbox/fs.rb

@@ -27,7 +27,7 @@ module Microsandbox
 
     # @return [Time, nil] last-modified time, if known
     def modified
-      @modified_ms && Time.at(@modified_ms / 1000.0)
+      Microsandbox.time_from_ms(@modified_ms)
     end
 
     def file? = @type == :file
@@ -64,12 +64,12 @@ module Microsandbox
 
     # @return [Time, nil] last-modified time, if known
     def modified
-      @modified_ms && Time.at(@modified_ms / 1000.0)
+      Microsandbox.time_from_ms(@modified_ms)
     end
 
     # @return [Time, nil] creation time, if known
     def created
-      @created_ms && Time.at(@created_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_ms)
     end
 
     def inspect
@@ -188,11 +188,7 @@ module Microsandbox
       sink = FsWriteSink.new(@native.fs_write_stream(path.to_s))
       return sink unless block_given?
 
-      begin
-        yield sink
-      ensure
-        sink.close
-      end
+      Microsandbox.close_after(sink) { yield sink }
     end
   end
 

data/lib/microsandbox/image.rb

@@ -18,12 +18,12 @@ module Microsandbox
 
     # @return [Time, nil]
     def created_at
-      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_at_ms)
     end
 
     # @return [Time, nil]
     def last_used_at
-      @last_used_at_ms && Time.at(@last_used_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@last_used_at_ms)
     end
 
     def inspect

data/lib/microsandbox/log_entry.rb

@@ -22,7 +22,7 @@ module Microsandbox
 
     # @return [Time] wall-clock capture time
     def timestamp
-      Time.at(@timestamp_ms / 1000.0)
+      Microsandbox.time_from_ms(@timestamp_ms)
     end
 
     # @return [String] the captured bytes decoded as UTF-8 (lossy — invalid byte

data/lib/microsandbox/metrics.rb

@@ -53,7 +53,7 @@ module Microsandbox
 
     # @return [Time] when this snapshot was captured
     def timestamp
-      Time.at(@timestamp_ms / 1000.0)
+      Microsandbox.time_from_ms(@timestamp_ms)
     end
 
     def inspect