feat: add narrow shared memory accessor to UninitializedSandbox

src/hyperlight_host/src/sandbox/uninitialized.rs

@@ -30,8 +30,9 @@ use crate::func::{ParameterTuple, SupportedReturnType};
 #[cfg(feature = "build-metadata")]
 use crate::log_build_details;
 use crate::mem::memory_region::{DEFAULT_GUEST_BLOB_MEM_FLAGS, MemoryRegionFlags};
+use crate::mem::layout::SandboxMemoryLayout;
 use crate::mem::mgr::SandboxMemoryManager;
-use crate::mem::shared_mem::ExclusiveSharedMemory;
+use crate::mem::shared_mem::{ExclusiveSharedMemory, SharedMemory};
 use crate::sandbox::SandboxConfiguration;
 use crate::{MultiUseSandbox, Result, new_error};
 
@@ -161,6 +162,43 @@ impl<'a> From<GuestBinary<'a>> for GuestEnvironment<'a, '_> {
 }
 
 impl UninitializedSandbox {
+    /// Returns a host-side pointer to a specific guest physical address (GPA)
+    /// within the sandbox's shared memory region.
+    ///
+    /// This is the safe way to obtain host-side access to guest memory.
+    /// The method validates that the GPA falls within the sandbox's
+    /// allocated memory region before returning the corresponding host pointer.
+    ///
+    /// # Safety
+    ///
+    /// The returned pointer is valid as long as the sandbox (and its underlying
+    /// shared memory mapping) remains alive. Dereferencing the pointer requires
+    /// `unsafe` code and the caller must ensure proper synchronization.
+    pub fn guest_memory_ptr(&mut self, gpa: usize) -> Result<*mut u8> {
+        let base = SandboxMemoryLayout::BASE_ADDRESS;
+        let mem_size = self.mgr.shared_mem.mem_size();
+
+        if gpa < base {
+            return Err(new_error!(
+                "GPA {:#x} is below the sandbox base address {:#x}",
+                gpa,
+                base
+            ));
+        }
+
+        let offset = gpa - base;
+        if offset >= mem_size {
+            return Err(new_error!(
+                "GPA {:#x} (offset {:#x}) is beyond sandbox memory size {:#x}",
+                gpa,
+                offset,
+                mem_size
+            ));
+        }
+
+        Ok(unsafe { self.mgr.shared_mem.base_ptr().add(offset) })
+    }
+
     // Creates a new uninitialized sandbox from a pre-built snapshot.
     // Note that since memory configuration is part of the snapshot the only configuration
     // that can be changed (from the original snapshot) is the configuration defines the behaviour of