feat: allow builtin module overrides, extensible globals, and freeze

- Allow overriding built-in modules (io, crypto, console) via
  native_modules! — custom modules take priority over built-ins.
  The require module is protected and cannot be overridden.
- Make console and print globals writable during init so
  custom_globals! can extend them (e.g. add console.warn/error).
- Freeze console (Object.freeze) and print (non-writable) after
  custom_globals! runs — handler code cannot tamper with them.
- 3-step init in JsRuntime::new: setup → custom_globals → freeze.
- New globals/freeze.rs module for post-init lockdown.
- Tests: require override rejection, console extension via
  custom_globals, freeze verification, console.log after freeze.
- Updated docs/extending-runtime.md with override rules.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

docs/extending-runtime.md

@@ -189,9 +189,13 @@ modules into the global native module registry. Called automatically by the
 `NativeModuleLoader` on first use — you never need to call it yourself.
 Built-in modules are inherited automatically.
 
-**Restrictions:**
-- Custom module names **cannot** shadow built-in modules (`io`, `crypto`,
-  `console`, `require`). Attempting to register a built-in name panics.
+Custom modules with the same name as a built-in (`io`, `crypto`, `console`)
+take priority, allowing extender crates to replace built-in implementations
+when needed.
+
+**Restriction:** The `require` module cannot be overridden — it is part of
+the runtime's core module loading infrastructure. Attempting to register
+a module named `"require"` will panic.
 
 ### `register_native_module`
 

src/hyperlight-js-runtime/src/globals/console.rs

@@ -13,15 +13,18 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-use rquickjs::object::Property;
-use rquickjs::{Ctx, Module, Object};
+use rquickjs::{Ctx, Function, Module, Object};
 
 pub fn setup(ctx: &Ctx<'_>) -> rquickjs::Result<()> {
     let globals = ctx.globals();
 
-    // Setup `console`.
-    let console: Object = Module::import(ctx, "console")?.finish()?;
-    globals.prop("console", Property::from(console))?;
+    // Create console as a plain extensible Object (not the frozen module namespace).
+    // This allows custom_globals! consumers to add methods (warn, error, info, debug)
+    // before globals::freeze() locks it down.
+    let console_mod: Object = Module::import(ctx, "console")?.finish()?;
+    let console = Object::new(ctx.clone())?;
+    console.set("log", console_mod.get::<_, Function>("log")?)?;
+    globals.set("console", console)?;
 
     Ok(())
 }

src/hyperlight-js-runtime/src/globals/freeze.rs

@@ -0,0 +1,41 @@
+/*
+Copyright 2026  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+use rquickjs::Ctx;
+
+/// Freeze built-in globals so handler code cannot tamper with them.
+///
+/// Called AFTER custom_globals! so extender crates can modify/extend
+/// globals first (e.g. adding console.warn/error/info/debug).
+///
+/// Frozen: console (Object.freeze), print (non-writable).
+/// Already frozen: require (non-configurable from setup),
+///                 String.bytesFrom (on frozen String constructor).
+pub fn setup(ctx: &Ctx<'_>) -> rquickjs::Result<()> {
+    ctx.eval::<(), _>(
+        r#"
+        if (typeof globalThis.console === 'object') {
+            Object.freeze(globalThis.console);
+        }
+        if (typeof globalThis.print === 'function') {
+            Object.defineProperty(globalThis, 'print', {
+                writable: false,
+                configurable: false
+            });
+        }
+        "#,
+    )?;
+    Ok(())
+}

src/hyperlight-js-runtime/src/globals/mod.rs

@@ -16,14 +16,22 @@ limitations under the License.
 use rquickjs::Ctx;
 
 mod console;
+mod freeze;
 mod print;
 mod require;
 mod string;
 
+/// Setup built-in globals (writable — before custom_globals!).
 pub fn setup(ctx: &Ctx<'_>) -> rquickjs::Result<()> {
     string::setup(ctx)?;
     print::setup(ctx)?;
     console::setup(ctx)?;
     require::setup(ctx)?;
     Ok(())
 }
+
+/// Freeze built-in globals (after custom_globals! has run).
+pub fn freeze(ctx: &Ctx<'_>) -> rquickjs::Result<()> {
+    freeze::setup(ctx)?;
+    Ok(())
+}

src/hyperlight-js-runtime/src/globals/print.rs

@@ -13,15 +13,16 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-use rquickjs::object::Property;
 use rquickjs::{Ctx, Function, Module, Object};
 
 pub fn setup(ctx: &Ctx<'_>) -> rquickjs::Result<()> {
     let globals = ctx.globals();
 
-    // Setup `print` function.
+    // Setup `print` as a writable global.
+    // Allows custom_globals! to override (e.g. for output capture).
+    // Frozen by globals::freeze() after custom_globals! runs.
     let io: Object = Module::import(ctx, "io")?.finish()?;
-    globals.prop("print", Property::from(io.get::<_, Function>("print")?))?;
+    globals.set("print", io.get::<_, Function>("print")?)?;
 
     Ok(())
 }

src/hyperlight-js-runtime/src/lib.rs

@@ -102,12 +102,16 @@ impl JsRuntime {
             // store some global state needed for module instantiation.
             host_loader.install(&ctx)?;
 
-            // Setup the global objects in the context, so they are available to the handler scripts.
+            // Step 1: Setup the global objects in the context, so they are available to the handler scripts.
             globals::setup(&ctx).catch(&ctx)?;
 
-            // Setup custom globals registered by extender crates via custom_globals! macro.
+            // Step 2: Setup custom globals registered by extender crates via custom_globals! macro.
             // Runs after built-in globals so custom setup can reference console, require, etc.
-            modules::setup_custom_globals(&ctx).catch(&ctx)
+            // also allows custom_globals! to override some (io,console) built-in globals if needed (e.g. for testing).
+            modules::setup_custom_globals(&ctx).catch(&ctx)?;
+
+            // Step 3: Freeze built-in globals (handler code can't tamper)
+            globals::freeze(&ctx).catch(&ctx)
         })?;
 
         Ok(Self {

src/hyperlight-js-runtime/src/modules/mod.rs

@@ -67,19 +67,22 @@ static CUSTOM_MODULES: Lazy<Mutex<HashMap<&'static str, ModuleDeclarationFn>>> =
 /// Register a custom native module by name.
 ///
 /// The module will be available to JavaScript via `import { ... } from "name"`.
-/// Custom modules cannot shadow built-in modules (io, crypto, console, require).
+/// Custom modules take priority over built-in modules with the same name,
+/// allowing extender crates to replace built-ins (e.g. `io`, `crypto`,
+/// `console`) with custom implementations.
+///
+/// The `require` module cannot be overridden — it is part of the runtime's
+/// core module loading infrastructure.
 ///
 /// This is typically called via the [`native_modules!`] macro rather than
 /// directly.
 ///
 /// # Panics
 ///
-/// Panics if `name` collides with a built-in module name.
+/// Panics if `name` is `"require"`.
 pub fn register_native_module(name: &'static str, decl: ModuleDeclarationFn) {
-    if BUILTIN_MODULES.contains_key(name) {
-        panic!(
-            "Cannot register custom native module '{name}': name conflicts with a built-in module"
-        );
+    if name == "require" {
+        panic!("Cannot override the 'require' module — it is part of the runtime's core infrastructure");
     }
     CUSTOM_MODULES.lock().insert(name, decl);
 }
@@ -152,8 +155,8 @@ impl Loader for NativeModuleLoader {
 /// }
 /// ```
 ///
-/// Custom module names **cannot** shadow built-in modules (`io`, `crypto`,
-/// `console`, `require`). Attempting to do so will panic at startup.
+/// Custom modules take priority over built-in modules with the same name,
+/// allowing extender crates to replace built-ins with custom implementations.
 #[macro_export]
 macro_rules! native_modules {
     ($($name:expr => $module:ty),* $(,)?) => {

src/hyperlight-js-runtime/tests/native_modules.rs

@@ -153,23 +153,29 @@ fn builtins_still_work_after_custom_registration() {
     });
 }
 
-// ── Override prevention ────────────────────────────────────────────────────
+// ── Built-in override ──────────────────────────────────────────────────────
 
 #[test]
-#[should_panic(expected = "conflicts with a built-in module")]
-fn registering_builtin_name_panics() {
+#[should_panic(expected = "Cannot override the 'require' module")]
+fn overriding_require_panics() {
     #[rquickjs::module(rename_vars = "camelCase")]
-    mod fake_io {
+    mod fake_require {
         #[rquickjs::function]
-        pub fn print(_txt: String) {}
+        pub fn require(_name: String) -> String {
+            String::from("fake")
+        }
     }
 
     hyperlight_js_runtime::modules::register_native_module(
-        "io",
-        hyperlight_js_runtime::modules::declaration::<js_fake_io>(),
+        "require",
+        hyperlight_js_runtime::modules::declaration::<js_fake_require>(),
     );
 }
 
+// Note: overriding io/crypto/console is allowed but tested via the
+// full-pipeline extended_runtime fixture to avoid poisoning the shared
+// static module registry used by other tests in this process.
+
 // ── native_modules! macro ──────────────────────────────────────────────────
 
 #[rquickjs::module(rename_vars = "camelCase")]
@@ -192,9 +198,20 @@ fn setup_test_constant(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
     Ok(())
 }
 
+fn setup_console_extensions(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    ctx.eval::<(), _>(
+        r#"
+        console.warn = console.log;
+        console.error = console.log;
+    "#,
+    )?;
+    Ok(())
+}
+
 // The macro generates init_custom_globals() which calls each setup function
 hyperlight_js_runtime::custom_globals! {
     setup_test_constant,
+    setup_console_extensions,
 }
 
 #[test]
@@ -460,6 +477,26 @@ fn full_pipeline_console_log_with_custom_modules() {
 
 // ── custom_globals! tests ──────────────────────────────────────────────────
 
+#[test]
+fn e2e_console_warn_works_via_custom_globals() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler = r#"
+        export function handler() {
+            console.warn("warn test");
+            console.error("error test");
+            return "ok";
+        }
+    "#;
+
+    runtime.register_handler("warn_test", handler, ".").unwrap();
+    let result = runtime
+        .run_handler("warn_test".into(), "{}".into(), false)
+        .unwrap();
+    assert_eq!(result, "\"ok\"");
+}
+
 #[test]
 fn e2e_custom_globals_are_available_in_handlers() {
     let mut runtime =
@@ -574,3 +611,102 @@ fn full_pipeline_custom_globals_with_modules() {
         "Expected 42 + 8 = 50, got: {stdout}"
     );
 }
+// ── globals freeze tests ───────────────────────────────────────────────────
+
+#[test]
+fn e2e_console_is_extensible_during_custom_globals() {
+    // setup_test_constant already runs via custom_globals! in this file.
+    // Verify custom globals constant works (proves custom_globals! ran).
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler = r#"
+        export function handler() {
+            return TEST_CUSTOM_GLOBAL;
+        }
+    "#;
+
+    runtime
+        .register_handler("extensible_test", handler, ".")
+        .unwrap();
+
+    let result = runtime
+        .run_handler("extensible_test".into(), "{}".into(), false)
+        .unwrap();
+    assert_eq!(result, "99");
+}
+
+#[test]
+fn e2e_console_frozen_after_init() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler = r#"
+        export function handler() {
+            try {
+                console.custom = function() {};
+                return "not_frozen";
+            } catch(e) {
+                return "frozen";
+            }
+        }
+    "#;
+
+    runtime
+        .register_handler("freeze_test", handler, ".")
+        .unwrap();
+    let result = runtime
+        .run_handler("freeze_test".into(), "{}".into(), false)
+        .unwrap();
+    assert!(
+        result.contains("frozen"),
+        "console should be frozen, got: {result}"
+    );
+}
+
+#[test]
+fn e2e_print_frozen_after_init() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler = r#"
+        export function handler() {
+            try {
+                globalThis.print = function() {};
+                return "not_frozen";
+            } catch(e) {
+                return "frozen";
+            }
+        }
+    "#;
+
+    runtime
+        .register_handler("print_freeze", handler, ".")
+        .unwrap();
+    let result = runtime
+        .run_handler("print_freeze".into(), "{}".into(), false)
+        .unwrap();
+    assert!(
+        result.contains("frozen"),
+        "print should be frozen, got: {result}"
+    );
+}
+
+#[test]
+fn e2e_console_log_still_works_after_freeze() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler = r#"
+        export function handler() {
+            console.log("still works");
+            return "ok";
+        }
+    "#;
+
+    runtime.register_handler("log_test", handler, ".").unwrap();
+    let result = runtime
+        .run_handler("log_test".into(), "{}".into(), false)
+        .unwrap();
+    assert_eq!(result, "\"ok\"");
+}