microsandbox-rb 0.5.8 → 0.5.10

data/ext/microsandbox/src/sandbox.rs

@@ -15,12 +15,15 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    FsEntry, FsEntryKind, FsMetadata, PullPolicy, RlimitResource, SandboxFilter, SandboxHandle,
-    SandboxMetrics, SandboxStatus, SandboxStopResult, SecurityProfile,
+    AttachOptionsBuilder, FsEntry, FsEntryKind, FsMetadata, Patch, PullPolicy, RlimitResource,
+    SandboxFilter, SandboxHandle, SandboxMetrics, SandboxStatus, SandboxStopResult,
+    SecurityProfile,
 };
 use microsandbox::LogLevel;
 use microsandbox::RegistryAuth;
-use microsandbox_network::policy::NetworkPolicy;
+use microsandbox_network::policy::{
+    Action, Destination, DestinationGroup, Direction, NetworkPolicy, PortRange, Protocol, Rule,
+};
 
 use crate::conv;
 use crate::error;
@@ -108,6 +111,12 @@ 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)? {
+            b = b.add_patch(patch);
+        }
         if let Some(net) = conv::opt_string(opts, "network")? {
             match net.as_str() {
                 "none" | "disabled" | "disable" | "airgapped" => b = b.disable_network(),
@@ -123,6 +132,13 @@ impl Sandbox {
                 }
             }
         }
+        // Custom network policy: an ordered allow/deny rule list with per-direction
+        // defaults and bulk domain denials. The Ruby layer routes bare presets to
+        // the `network` key above and full policies here; mirrors the Python
+        // binding's `apply_network`.
+        if let Some(policy) = parse_network_policy(opts)? {
+            b = b.network(move |n| n.policy(policy));
+        }
         if let Some(level) = conv::opt_string(opts, "log_level")? {
             b = b.log_level(log_level_from_str(&level)?);
         }
@@ -193,27 +209,36 @@ impl Sandbox {
         Ok(Sandbox::from_inner(inner))
     }
 
-    /// Lightweight metadata for a sandbox by name (running or not).
-    fn get(name: String) -> Result<RHash, Error> {
+    /// A controllable handle for a sandbox by name (running or not). Carries
+    /// metadata accessors and the full lifecycle surface (see `SbHandle`).
+    fn get(name: String) -> Result<SbHandle, Error> {
         let handle = block_on(microsandbox::Sandbox::get(&name)).map_err(error::to_ruby)?;
-        Ok(handle_to_hash(&handle))
+        Ok(SbHandle::from_inner(handle))
     }
 
-    /// All sandboxes as metadata hashes.
+    /// All sandboxes as controllable handles.
     fn list() -> Result<RArray, Error> {
         let handles = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
-        rhash_array(handles.iter().map(handle_to_hash))
+        let arr = ruby().ary_new();
+        for h in handles {
+            arr.push(SbHandle::from_inner(h))?;
+        }
+        Ok(arr)
     }
 
-    /// Sandboxes filtered by required `key=value` labels (AND-matched). `opts`
-    /// carries a string→string `labels` map.
+    /// Sandboxes filtered by required `key=value` labels (AND-matched), as
+    /// controllable handles. `opts` carries a string→string `labels` map.
     fn list_with(opts: RHash) -> Result<RArray, Error> {
         let mut filter = SandboxFilter::new();
         for (k, v) in conv::opt_string_map(opts, "labels")? {
             filter = filter.label(k, v);
         }
         let handles = block_on(microsandbox::Sandbox::list_with(filter)).map_err(error::to_ruby)?;
-        rhash_array(handles.iter().map(handle_to_hash))
+        let arr = ruby().ary_new();
+        for h in handles {
+            arr.push(SbHandle::from_inner(h))?;
+        }
+        Ok(arr)
     }
 
     /// Remove a (stopped) sandbox by name.
@@ -270,44 +295,46 @@ impl Sandbox {
         Ok(ExecHandle::from_core(handle))
     }
 
-    /// Graceful stop (+ wait). `timeout` is optional seconds.
-    fn stop(&self, timeout: Option<f64>) -> Result<(), Error> {
-        match timeout {
-            Some(secs) => block_on(self.inner.stop_with_timeout(Duration::from_secs_f64(secs))),
-            None => block_on(self.inner.stop()),
-        }
+    /// Graceful stop. Mirrors the official SDKs: the live handle routes through
+    /// a freshly fetched `SandboxHandle::stop` (SIGTERM→SIGKILL escalation with
+    /// a 10s default). Fine-grained control — a custom timeout or fire-and-
+    /// return `request_*` — lives on `SandboxHandle`, obtained via `Sandbox.get`.
+    fn stop(&self) -> Result<(), Error> {
+        let name = self.inner.name().to_string();
+        block_on(async move {
+            let handle = microsandbox::sandbox::Sandbox::get(&name).await?;
+            handle.stop().await
+        })
         .map_err(error::to_ruby)
     }
 
-    /// Force kill (SIGKILL). `timeout` is optional seconds.
-    fn kill(&self, timeout: Option<f64>) -> Result<(), Error> {
-        match timeout {
-            Some(secs) => block_on(self.inner.kill_with_timeout(Duration::from_secs_f64(secs))),
-            None => block_on(self.inner.kill()),
-        }
-        .map_err(error::to_ruby)
+    /// Graceful stop, then wait for the process to exit. Returns an exit-status
+    /// Hash (`exit_code`, `success`). Local backend only.
+    fn stop_and_wait(&self) -> Result<RHash, Error> {
+        let status = block_on(self.inner.stop_and_wait()).map_err(error::to_ruby)?;
+        Ok(exit_status_to_hash(status))
     }
 
-    /// Send the graceful-shutdown request and return without waiting.
-    fn request_stop(&self) -> Result<(), Error> {
-        block_on(self.inner.request_stop()).map_err(error::to_ruby)
+    /// Force kill (SIGKILL).
+    fn kill(&self) -> Result<(), Error> {
+        block_on(self.inner.kill()).map_err(error::to_ruby)
     }
 
-    /// Send the force-kill request and return without waiting.
-    fn request_kill(&self) -> Result<(), Error> {
-        block_on(self.inner.request_kill()).map_err(error::to_ruby)
+    /// Trigger a graceful drain (SIGUSR1 on local).
+    fn drain(&self) -> Result<(), Error> {
+        block_on(self.inner.drain()).map_err(error::to_ruby)
     }
 
-    /// Send the drain request and return without waiting.
-    fn request_drain(&self) -> Result<(), Error> {
-        block_on(self.inner.request_drain()).map_err(error::to_ruby)
+    /// Wait for the process to exit. Returns an exit-status Hash. Local only.
+    fn wait(&self) -> Result<RHash, Error> {
+        let status = block_on(self.inner.wait()).map_err(error::to_ruby)?;
+        Ok(exit_status_to_hash(status))
     }
 
-    /// Block until the sandbox is observed in a terminal state; returns a
-    /// stop-result Hash (name, status, exit_code, signal, observed_at_ms, source).
-    fn wait_until_stopped(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.wait_until_stopped()).map_err(error::to_ruby)?;
-        Ok(stop_result_to_hash(&result))
+    /// Live status fetched from the backend (a round-trip per call).
+    fn status(&self) -> Result<String, Error> {
+        let status = block_on(self.inner.status()).map_err(error::to_ruby)?;
+        Ok(sandbox_status_str(status).to_string())
     }
 
     /// Whether this handle owns the sandbox process lifecycle (a synchronous,
@@ -434,6 +461,120 @@ impl Sandbox {
         let fs = self.inner.fs();
         block_on(fs.copy_to_host(&guest_path, &host_path)).map_err(error::to_ruby)
     }
+
+    //----------------------------------------------------------------------
+    // SSH (mirror SandboxSshOps)
+    //----------------------------------------------------------------------
+
+    /// Open a native in-process SSH client to this sandbox. `opts`: user, term,
+    /// sftp (bool, default true).
+    fn ssh_open_client(&self, opts: RHash) -> Result<crate::ssh::SshClient, Error> {
+        let user = conv::opt_string(opts, "user")?;
+        let term = conv::opt_string(opts, "term")?;
+        let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let ssh = self.inner.ssh();
+        let client = block_on(ssh.open_client_with(move |mut b| {
+            if let Some(u) = user {
+                b = b.user(u);
+            }
+            if let Some(t) = term {
+                b = b.term(t);
+            }
+            b.sftp(sftp)
+        }))
+        .map_err(error::to_ruby)?;
+        Ok(crate::ssh::SshClient::from_core(client))
+    }
+
+    /// Prepare a reusable SSH server endpoint. `opts`: host_key_path,
+    /// authorized_keys_path, user, sftp (bool, default true).
+    fn ssh_prepare_server(&self, opts: RHash) -> Result<crate::ssh::SshServer, Error> {
+        let host_key_path = conv::opt_string(opts, "host_key_path")?;
+        let authorized_keys_path = conv::opt_string(opts, "authorized_keys_path")?;
+        let user = conv::opt_string(opts, "user")?;
+        let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let ssh = self.inner.ssh();
+        let server = block_on(ssh.prepare_server_with(move |mut b| {
+            if let Some(p) = host_key_path {
+                b = b.host_key_path(p);
+            }
+            if let Some(p) = authorized_keys_path {
+                b = b.authorized_keys_path(p);
+            }
+            if let Some(u) = user {
+                b = b.user(u);
+            }
+            b.sftp(sftp)
+        }))
+        .map_err(error::to_ruby)?;
+        Ok(crate::ssh::SshServer::from_core(server))
+    }
+
+    //----------------------------------------------------------------------
+    // Interactive attach (host-TTY coupled)
+    //----------------------------------------------------------------------
+
+    /// Attach an interactive terminal to a command in the sandbox; returns its
+    /// exit code. Puts the host terminal in raw mode (requires a real tty) and
+    /// blocks until the command exits or the detach sequence is typed. `opts`:
+    /// cwd, user, env, detach_keys, rlimits.
+    fn attach(&self, cmd: String, args: Vec<String>, opts: RHash) -> Result<i32, Error> {
+        let parsed = AttachOpts::parse(args, opts)?;
+        block_on(self.inner.attach_with(cmd, move |b| parsed.apply(b))).map_err(error::to_ruby)
+    }
+
+    /// Attach an interactive terminal running the sandbox's default shell.
+    fn attach_shell(&self) -> Result<i32, Error> {
+        block_on(self.inner.attach_shell()).map_err(error::to_ruby)
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// Attach option parsing
+//--------------------------------------------------------------------------------------------------
+
+struct AttachOpts {
+    args: Vec<String>,
+    cwd: Option<String>,
+    user: Option<String>,
+    env: Vec<(String, String)>,
+    detach_keys: Option<String>,
+    rlimits: Vec<(RlimitResource, u64, u64)>,
+}
+
+impl AttachOpts {
+    fn parse(args: Vec<String>, opts: RHash) -> Result<Self, Error> {
+        Ok(Self {
+            args,
+            cwd: conv::opt_string(opts, "cwd")?,
+            user: conv::opt_string(opts, "user")?,
+            env: conv::opt_string_map(opts, "env")?,
+            detach_keys: conv::opt_string(opts, "detach_keys")?,
+            rlimits: parse_rlimits(opts)?,
+        })
+    }
+
+    fn apply(self, mut b: AttachOptionsBuilder) -> AttachOptionsBuilder {
+        if !self.args.is_empty() {
+            b = b.args(self.args);
+        }
+        if let Some(cwd) = self.cwd {
+            b = b.cwd(cwd);
+        }
+        if let Some(user) = self.user {
+            b = b.user(user);
+        }
+        for (k, v) in self.env {
+            b = b.env(k, v);
+        }
+        if let Some(keys) = self.detach_keys {
+            b = b.detach_keys(keys);
+        }
+        for (resource, soft, hard) in self.rlimits {
+            b = b.rlimit_range(resource, soft, hard);
+        }
+        b
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -511,6 +652,358 @@ fn parse_rlimits(opts: RHash) -> Result<Vec<(RlimitResource, u64, u64)>, Error>
     Ok(out)
 }
 
+//--------------------------------------------------------------------------------------------------
+// Patch parsing (mirrors the Python binding's `apply_patch`)
+//--------------------------------------------------------------------------------------------------
+
+/// Read a required string field from a per-patch Hash.
+fn patch_str(h: RHash, key: &str) -> Result<String, Error> {
+    conv::opt_string(h, key)?
+        .ok_or_else(|| error::base_error(format!("patch is missing required key :{key}")))
+}
+
+/// Read a required field as raw bytes (for the binary `file` patch content).
+fn patch_bytes(h: RHash, key: &str) -> Result<Vec<u8>, Error> {
+    let s = conv::opt::<RString>(h, key)?
+        .ok_or_else(|| error::base_error(format!("patch is missing required key :{key}")))?;
+    // Copy out while the GVL is held; the buffer is consumed synchronously here.
+    Ok(unsafe { s.as_slice() }.to_vec())
+}
+
+/// 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> {
+    let mut out = Vec::new();
+    for h in conv::opt_hash_vec(opts, "patches")? {
+        let kind = patch_str(h, "kind")?;
+        let mode = conv::opt_u32(h, "mode")?;
+        let replace = conv::opt_bool(h, "replace")?;
+        let patch = match kind.as_str() {
+            "text" => Patch::Text {
+                path: patch_str(h, "path")?,
+                content: patch_str(h, "content")?,
+                mode,
+                replace,
+            },
+            "file" => Patch::File {
+                path: patch_str(h, "path")?,
+                content: patch_bytes(h, "content")?,
+                mode,
+                replace,
+            },
+            "append" => Patch::Append {
+                path: patch_str(h, "path")?,
+                content: patch_str(h, "content")?,
+            },
+            "copy_file" => Patch::CopyFile {
+                src: patch_str(h, "src")?.into(),
+                dst: patch_str(h, "dst")?,
+                mode,
+                replace,
+            },
+            "copy_dir" => Patch::CopyDir {
+                src: patch_str(h, "src")?.into(),
+                dst: patch_str(h, "dst")?,
+                replace,
+            },
+            "symlink" => Patch::Symlink {
+                target: patch_str(h, "target")?,
+                link: patch_str(h, "link")?,
+                replace,
+            },
+            "mkdir" => Patch::Mkdir {
+                path: patch_str(h, "path")?,
+                mode,
+            },
+            "remove" => Patch::Remove {
+                path: patch_str(h, "path")?,
+            },
+            other => {
+                return Err(error::base_error(format!(
+                    "unknown patch kind {other:?} (expected one of \
+                     text/file/append/copy_file/copy_dir/symlink/mkdir/remove)"
+                )))
+            }
+        };
+        out.push(patch);
+    }
+    Ok(out)
+}
+
+//--------------------------------------------------------------------------------------------------
+// Network policy parsing (mirrors the Python binding's `apply_network`)
+//--------------------------------------------------------------------------------------------------
+
+/// Parse the `network_policy` option (a Hash normalized by the Ruby layer) into
+/// a core `NetworkPolicy`. Returns `None` when the option is absent (bare
+/// presets travel via the separate `network` key handled in `create`).
+///
+/// Composition (mirrors the Go SDK's `NetworkConfig`): bulk domain-deny rules
+/// come first (so they outrank later allow rules), then a preset's rules (if a
+/// preset base is given), then the caller's explicit `rules`. Per-direction
+/// defaults come from the explicit `default_egress`/`default_ingress` when set,
+/// else the preset's defaults, else the asymmetric default (deny egress / allow
+/// ingress).
+fn parse_network_policy(opts: RHash) -> Result<Option<NetworkPolicy>, Error> {
+    let Some(np) = conv::opt::<RHash>(opts, "network_policy")? else {
+        return Ok(None);
+    };
+
+    // Bulk domain denials → prepended deny-egress rules.
+    let mut rules: Vec<Rule> = Vec::new();
+    for d in conv::opt_string_vec(np, "deny_domains")? {
+        let domain = d
+            .parse()
+            .map_err(|e| error::base_error(format!("deny_domains {d:?}: {e}")))?;
+        rules.push(Rule::deny_egress(Destination::Domain(domain)));
+    }
+    for s in conv::opt_string_vec(np, "deny_domain_suffixes")? {
+        let suffix = s
+            .parse()
+            .map_err(|e| error::base_error(format!("deny_domain_suffixes {s:?}: {e}")))?;
+        rules.push(Rule::deny_egress(Destination::DomainSuffix(suffix)));
+    }
+
+    // Optional preset base (its rules and defaults seed the policy).
+    let (preset_egress, preset_ingress) = match conv::opt_string(np, "preset")? {
+        Some(p) => {
+            let mut base = network_preset(&p)?;
+            rules.append(&mut base.rules);
+            (Some(base.default_egress), Some(base.default_ingress))
+        }
+        None => (None, None),
+    };
+
+    // Caller's explicit rules come after preset rules.
+    for rd in conv::opt_hash_vec(np, "rules")? {
+        rules.push(parse_rule(rd)?);
+    }
+
+    let default_egress = match conv::opt_string(np, "default_egress")? {
+        Some(s) => action_from_str(&s)?,
+        None => preset_egress.unwrap_or(Action::Deny),
+    };
+    let default_ingress = match conv::opt_string(np, "default_ingress")? {
+        Some(s) => action_from_str(&s)?,
+        None => preset_ingress.unwrap_or(Action::Allow),
+    };
+
+    Ok(Some(NetworkPolicy {
+        default_egress,
+        default_ingress,
+        rules,
+    }))
+}
+
+fn network_preset(p: &str) -> Result<NetworkPolicy, Error> {
+    Ok(match p {
+        "none" | "disabled" | "disable" | "airgapped" => NetworkPolicy::none(),
+        "public" | "public_only" | "public-only" | "default" => NetworkPolicy::public_only(),
+        "all" | "allow_all" | "allow-all" => NetworkPolicy::allow_all(),
+        "non_local" | "non-local" | "nonlocal" => NetworkPolicy::non_local(),
+        other => {
+            return Err(error::base_error(format!(
+                "unknown network preset {other:?} (expected one of \
+                 public_only/none/allow_all/non_local)"
+            )))
+        }
+    })
+}
+
+fn action_from_str(s: &str) -> Result<Action, Error> {
+    match s {
+        "allow" => Ok(Action::Allow),
+        "deny" => Ok(Action::Deny),
+        other => Err(error::base_error(format!(
+            "unknown network action {other:?} (expected allow/deny)"
+        ))),
+    }
+}
+
+fn direction_from_str(s: &str) -> Result<Direction, Error> {
+    match s {
+        "egress" => Ok(Direction::Egress),
+        "ingress" => Ok(Direction::Ingress),
+        "any" => Ok(Direction::Any),
+        other => Err(error::base_error(format!(
+            "unknown rule direction {other:?} (expected egress/ingress/any)"
+        ))),
+    }
+}
+
+fn protocol_from_str(s: &str) -> Result<Protocol, Error> {
+    match s {
+        "tcp" => Ok(Protocol::Tcp),
+        "udp" => Ok(Protocol::Udp),
+        "icmpv4" => Ok(Protocol::Icmpv4),
+        "icmpv6" => Ok(Protocol::Icmpv6),
+        other => Err(error::base_error(format!(
+            "unknown protocol {other:?} (expected tcp/udp/icmpv4/icmpv6)"
+        ))),
+    }
+}
+
+/// Parse a single rule Hash into a core `Rule`.
+fn parse_rule(rd: RHash) -> Result<Rule, Error> {
+    let action = action_from_str(&patch_str(rd, "action")?)?;
+    let direction = match conv::opt_string(rd, "direction")? {
+        Some(s) => direction_from_str(&s)?,
+        None => Direction::Egress,
+    };
+    let kind = conv::opt_string(rd, "destination_kind")?;
+    let raw = conv::opt_string(rd, "destination")?;
+    let destination = parse_destination(kind.as_deref(), raw.as_deref())?;
+
+    let mut protocols = Vec::new();
+    for p in conv::opt_string_vec(rd, "protocols")? {
+        let proto = protocol_from_str(&p)?;
+        if !protocols.contains(&proto) {
+            protocols.push(proto);
+        }
+    }
+
+    let mut ports = Vec::new();
+    for p in conv::opt_string_vec(rd, "ports")? {
+        let range = parse_port_range(&p)?;
+        if !ports.contains(&range) {
+            ports.push(range);
+        }
+    }
+
+    Ok(Rule {
+        direction,
+        destination,
+        protocols,
+        ports,
+        action,
+    })
+}
+
+/// Parse a port string into a `PortRange`. Accepts a single port (`"443"`) or
+/// an inclusive range (`"8000-9000"`).
+fn parse_port_range(raw: &str) -> Result<PortRange, Error> {
+    let invalid = || error::base_error(format!("invalid port {raw:?} (expected N or N-M)"));
+    if let Some((lo, hi)) = raw.split_once('-') {
+        let lo: u16 = lo.trim().parse().map_err(|_| invalid())?;
+        let hi: u16 = hi.trim().parse().map_err(|_| invalid())?;
+        if lo > hi {
+            return Err(error::base_error(format!(
+                "invalid port range {raw:?}: low {lo} exceeds high {hi}"
+            )));
+        }
+        Ok(PortRange::range(lo, hi))
+    } else {
+        let p: u16 = raw.trim().parse().map_err(|_| invalid())?;
+        Ok(PortRange::single(p))
+    }
+}
+
+/// Resolve a destination from an explicit `kind` + raw value, or — when `kind`
+/// is absent — classify the raw shorthand string. Mirrors the Python binding's
+/// `parse_network_destination` / `parse_shorthand_destination`.
+fn parse_destination(kind: Option<&str>, raw: Option<&str>) -> Result<Destination, Error> {
+    let required = |raw: Option<&str>, kind: &str| -> Result<String, Error> {
+        raw.map(str::to_string).ok_or_else(|| {
+            error::base_error(format!(
+                "destination is required for destination kind {kind:?}"
+            ))
+        })
+    };
+    match kind {
+        Some("any") => Ok(Destination::Any),
+        Some("ip") => parse_ip_destination(&required(raw, "ip")?),
+        Some("cidr") => parse_cidr_destination(&required(raw, "cidr")?),
+        Some("domain") => parse_domain_destination(&required(raw, "domain")?),
+        Some("domain_suffix") | Some("domain-suffix") => {
+            parse_domain_suffix_destination(&required(raw, "domain_suffix")?)
+        }
+        Some("group") => parse_group_destination(&required(raw, "group")?),
+        Some(other) => Err(error::base_error(format!(
+            "unknown destination kind {other:?}"
+        ))),
+        None => parse_shorthand_destination(raw),
+    }
+}
+
+fn parse_shorthand_destination(raw: Option<&str>) -> Result<Destination, Error> {
+    let Some(raw) = raw else {
+        return Ok(Destination::Any);
+    };
+    if raw == "*" {
+        return Ok(Destination::Any);
+    }
+    if let Some(rest) = raw.strip_prefix("domain=") {
+        return parse_domain_destination(rest);
+    }
+    if let Some(rest) = raw.strip_prefix("suffix=") {
+        return parse_domain_suffix_destination(rest);
+    }
+    if let Some(dest) = maybe_group_destination(raw) {
+        return Ok(dest);
+    }
+    if raw.starts_with('.') {
+        return parse_domain_suffix_destination(raw);
+    }
+    if raw.contains('/') {
+        return parse_cidr_destination(raw);
+    }
+    if raw.parse::<std::net::IpAddr>().is_ok() {
+        return parse_ip_destination(raw);
+    }
+    parse_domain_destination(raw)
+}
+
+fn parse_ip_destination(raw: &str) -> Result<Destination, Error> {
+    let ip: std::net::IpAddr = raw
+        .parse()
+        .map_err(|e| error::base_error(format!("invalid IP address {raw:?}: {e}")))?;
+    let prefix = if ip.is_ipv4() { 32 } else { 128 };
+    let cidr = ipnetwork::IpNetwork::new(ip, prefix)
+        .map_err(|e| error::base_error(format!("invalid IP address {raw:?}: {e}")))?;
+    Ok(Destination::Cidr(cidr))
+}
+
+fn parse_cidr_destination(raw: &str) -> Result<Destination, Error> {
+    let cidr: ipnetwork::IpNetwork = raw
+        .parse()
+        .map_err(|e| error::base_error(format!("invalid CIDR {raw:?}: {e}")))?;
+    Ok(Destination::Cidr(cidr))
+}
+
+fn parse_domain_destination(raw: &str) -> Result<Destination, Error> {
+    let name = raw
+        .parse()
+        .map_err(|e| error::base_error(format!("invalid domain {raw:?}: {e}")))?;
+    Ok(Destination::Domain(name))
+}
+
+fn parse_domain_suffix_destination(raw: &str) -> Result<Destination, Error> {
+    let name = raw
+        .parse()
+        .map_err(|e| error::base_error(format!("invalid domain suffix {raw:?}: {e}")))?;
+    Ok(Destination::DomainSuffix(name))
+}
+
+fn parse_group_destination(raw: &str) -> Result<Destination, Error> {
+    maybe_group_destination(raw)
+        .ok_or_else(|| error::base_error(format!("unknown destination group {raw:?}")))
+}
+
+fn maybe_group_destination(raw: &str) -> Option<Destination> {
+    let group = match raw {
+        "public" => DestinationGroup::Public,
+        "loopback" => DestinationGroup::Loopback,
+        "private" => DestinationGroup::Private,
+        "link-local" | "link_local" => DestinationGroup::LinkLocal,
+        "metadata" => DestinationGroup::Metadata,
+        "multicast" => DestinationGroup::Multicast,
+        "host" => DestinationGroup::Host,
+        _ => return None,
+    };
+    Some(Destination::Group(group))
+}
+
 //--------------------------------------------------------------------------------------------------
 // Registry option parsing
 //--------------------------------------------------------------------------------------------------
@@ -582,6 +1075,7 @@ struct ExecOpts {
     timeout: Option<Duration>,
     tty: bool,
     stdin: Option<Vec<u8>>,
+    stdin_pipe: bool,
     rlimits: Vec<(RlimitResource, u64, u64)>,
 }
 
@@ -596,6 +1090,7 @@ impl ExecOpts {
             timeout: conv::opt_f64(opts, "timeout")?.map(Duration::from_secs_f64),
             tty: conv::opt_bool(opts, "tty")?,
             stdin,
+            stdin_pipe: conv::opt_bool(opts, "stdin_pipe")?,
             rlimits: parse_rlimits(opts)?,
         })
     }
@@ -622,7 +1117,13 @@ impl ExecOpts {
         if self.tty {
             b = b.tty(true);
         }
-        if let Some(stdin) = self.stdin {
+        // Pipe mode opens a writable stdin sink (lifted out by ExecHandle via
+        // `take_stdin`); bytes mode feeds a fixed buffer and closes. The core's
+        // `StdinMode` is a single enum, so the two are mutually exclusive — pipe
+        // wins if a caller somehow sets both.
+        if self.stdin_pipe {
+            b = b.stdin_pipe();
+        } else if let Some(stdin) = self.stdin {
             b = b.stdin_bytes(stdin);
         }
         for (resource, soft, hard) in self.rlimits {
@@ -713,7 +1214,13 @@ pub(crate) fn metrics_to_hash(m: &SandboxMetrics) -> RHash {
 }
 
 fn sandbox_status_str(status: SandboxStatus) -> &'static str {
+    // Lowercased `Debug` names, matching the official SDKs' `format!("{:?}")`.
+    // `Created`/`Starting` are new in v0.5.8 (cloud-only today). The match is
+    // intentionally exhaustive — no wildcard — so a future upstream variant
+    // surfaces as a compile error rather than a silent fallback.
     match status {
+        SandboxStatus::Created => "created",
+        SandboxStatus::Starting => "starting",
         SandboxStatus::Running => "running",
         SandboxStatus::Draining => "draining",
         SandboxStatus::Paused => "paused",
@@ -722,6 +1229,15 @@ fn sandbox_status_str(status: SandboxStatus) -> &'static str {
     }
 }
 
+/// A `std::process::ExitStatus` as a Ruby Hash: `exit_code` (Integer or nil) and
+/// `success` (Boolean). Returned by the live `Sandbox#wait` / `#stop_and_wait`.
+fn exit_status_to_hash(status: std::process::ExitStatus) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("exit_code", status.code());
+    let _ = hash.aset("success", status.success());
+    hash
+}
+
 fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     let hash = ruby().hash_new();
     let _ = hash.aset("name", result.name.clone());
@@ -733,19 +1249,85 @@ fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     hash
 }
 
-fn handle_to_hash(handle: &SandboxHandle) -> RHash {
-    let hash = ruby().hash_new();
-    let _ = hash.aset("name", handle.name().to_string());
-    let _ = hash.aset("status", sandbox_status_str(handle.status()));
-    let _ = hash.aset(
-        "created_at_ms",
-        handle.created_at().map(|dt| dt.timestamp_millis()),
-    );
-    let _ = hash.aset(
-        "updated_at_ms",
-        handle.updated_at().map(|dt| dt.timestamp_millis()),
-    );
-    hash
+//--------------------------------------------------------------------------------------------------
+// SandboxHandle — the controllable lightweight handle
+//--------------------------------------------------------------------------------------------------
+
+/// Wraps a core `microsandbox::sandbox::SandboxHandle` (returned by
+/// `Sandbox.get`/`list`/`list_with`). Carries metadata accessors plus the rich
+/// lifecycle surface that moved off the live `Sandbox` in v0.5.8 — mirroring the
+/// official Python (`PySandboxHandle`) and Node (`SandboxHandle`) SDKs. Status is
+/// a synchronous snapshot read off the handle (no round-trip).
+#[magnus::wrap(class = "Microsandbox::Native::SandboxHandle", free_immediately, size)]
+pub struct SbHandle {
+    inner: SandboxHandle,
+}
+
+impl SbHandle {
+    fn from_inner(inner: SandboxHandle) -> Self {
+        Self { inner }
+    }
+
+    fn name(&self) -> String {
+        self.inner.name().to_string()
+    }
+
+    /// Status snapshot captured when the handle was fetched (synchronous).
+    fn status(&self) -> String {
+        sandbox_status_str(self.inner.status_snapshot()).to_string()
+    }
+
+    fn created_at_ms(&self) -> Option<i64> {
+        self.inner.created_at().map(|dt| dt.timestamp_millis())
+    }
+
+    fn updated_at_ms(&self) -> Option<i64> {
+        self.inner.updated_at().map(|dt| dt.timestamp_millis())
+    }
+
+    /// Graceful stop (SIGTERM→SIGKILL escalation, 10s default) and wait.
+    fn stop(&self) -> Result<(), Error> {
+        block_on(self.inner.stop()).map_err(error::to_ruby)
+    }
+
+    /// Graceful stop with a custom escalation timeout (seconds).
+    fn stop_with_timeout(&self, secs: f64) -> Result<(), Error> {
+        block_on(self.inner.stop_with_timeout(Duration::from_secs_f64(secs)))
+            .map_err(error::to_ruby)
+    }
+
+    /// Force kill (SIGKILL) and wait.
+    fn kill(&self) -> Result<(), Error> {
+        block_on(self.inner.kill()).map_err(error::to_ruby)
+    }
+
+    /// Force kill, waiting up to `secs` for the process to disappear.
+    fn kill_with_timeout(&self, secs: f64) -> Result<(), Error> {
+        block_on(self.inner.kill_with_timeout(Duration::from_secs_f64(secs)))
+            .map_err(error::to_ruby)
+    }
+
+    /// Send the graceful-shutdown request and return without waiting.
+    fn request_stop(&self) -> Result<(), Error> {
+        block_on(self.inner.request_stop()).map_err(error::to_ruby)
+    }
+
+    /// Send the force-kill request and return without waiting.
+    fn request_kill(&self) -> Result<(), Error> {
+        block_on(self.inner.request_kill()).map_err(error::to_ruby)
+    }
+
+    /// Send the drain request (SIGUSR1) and return without waiting.
+    fn request_drain(&self) -> Result<(), Error> {
+        block_on(self.inner.request_drain()).map_err(error::to_ruby)
+    }
+
+    /// Block until the sandbox reaches a terminal state; returns a stop-result
+    /// Hash (name, status, exit_code, signal, observed_at_ms, source).
+    fn wait_until_stopped(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.wait_until_stopped()).map_err(error::to_ruby)?;
+        Ok(stop_result_to_hash(&result))
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -846,15 +1428,12 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("shell", method!(Sandbox::shell, 2))?;
     class.define_method("exec_stream", method!(Sandbox::exec_stream, 3))?;
     class.define_method("shell_stream", method!(Sandbox::shell_stream, 2))?;
-    class.define_method("stop", method!(Sandbox::stop, 1))?;
-    class.define_method("kill", method!(Sandbox::kill, 1))?;
-    class.define_method("request_stop", method!(Sandbox::request_stop, 0))?;
-    class.define_method("request_kill", method!(Sandbox::request_kill, 0))?;
-    class.define_method("request_drain", method!(Sandbox::request_drain, 0))?;
-    class.define_method(
-        "wait_until_stopped",
-        method!(Sandbox::wait_until_stopped, 0),
-    )?;
+    class.define_method("stop", method!(Sandbox::stop, 0))?;
+    class.define_method("stop_and_wait", method!(Sandbox::stop_and_wait, 0))?;
+    class.define_method("kill", method!(Sandbox::kill, 0))?;
+    class.define_method("drain", method!(Sandbox::drain, 0))?;
+    class.define_method("wait", method!(Sandbox::wait, 0))?;
+    class.define_method("status", method!(Sandbox::status, 0))?;
     class.define_method("owns_lifecycle", method!(Sandbox::owns_lifecycle, 0))?;
     class.define_method("detach", method!(Sandbox::detach, 0))?;
     class.define_method("metrics", method!(Sandbox::metrics, 0))?;
@@ -876,5 +1455,31 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("fs_copy_from_host", method!(Sandbox::fs_copy_from_host, 2))?;
     class.define_method("fs_copy_to_host", method!(Sandbox::fs_copy_to_host, 2))?;
 
+    class.define_method("ssh_open_client", method!(Sandbox::ssh_open_client, 1))?;
+    class.define_method(
+        "ssh_prepare_server",
+        method!(Sandbox::ssh_prepare_server, 1),
+    )?;
+
+    class.define_method("attach", method!(Sandbox::attach, 3))?;
+    class.define_method("attach_shell", method!(Sandbox::attach_shell, 0))?;
+
+    let handle = native.define_class("SandboxHandle", ruby.class_object())?;
+    handle.define_method("name", method!(SbHandle::name, 0))?;
+    handle.define_method("status", method!(SbHandle::status, 0))?;
+    handle.define_method("created_at_ms", method!(SbHandle::created_at_ms, 0))?;
+    handle.define_method("updated_at_ms", method!(SbHandle::updated_at_ms, 0))?;
+    handle.define_method("stop", method!(SbHandle::stop, 0))?;
+    handle.define_method("stop_with_timeout", method!(SbHandle::stop_with_timeout, 1))?;
+    handle.define_method("kill", method!(SbHandle::kill, 0))?;
+    handle.define_method("kill_with_timeout", method!(SbHandle::kill_with_timeout, 1))?;
+    handle.define_method("request_stop", method!(SbHandle::request_stop, 0))?;
+    handle.define_method("request_kill", method!(SbHandle::request_kill, 0))?;
+    handle.define_method("request_drain", method!(SbHandle::request_drain, 0))?;
+    handle.define_method(
+        "wait_until_stopped",
+        method!(SbHandle::wait_until_stopped, 0),
+    )?;
+
     Ok(())
 }