Add compat flag to mark jsg::Object prototypes as immutable (#5522)

Author: jasnell

src/workerd/api/BUILD.bazel

@@ -1170,3 +1170,9 @@ wd_test(
         "tests/instrumentation-tail-worker.js",
     ],
 )
+
+wd_test(
+    src = "tests/headers-immutable-prototype-test.wd-test",
+    args = ["--experimental"],
+    data = ["tests/headers-immutable-prototype-test.js"],
+)

src/workerd/api/tests/headers-immutable-prototype-test.js

@@ -0,0 +1,10 @@
+import { strictEqual } from 'node:assert';
+
+export const test = {
+  test() {
+    strictEqual(
+      Reflect.getOwnPropertyDescriptor(Headers, 'prototype').writable,
+      false
+    );
+  },
+};

src/workerd/api/tests/headers-immutable-prototype-test.wd-test

@@ -0,0 +1,15 @@
+using Workerd = import "/workerd/workerd.capnp";
+
+const unitTests :Workerd.Config = (
+  services = [
+    ( name = "headers-immutable-prototype-test",
+      worker = (
+        modules = [
+          (name = "worker", esModule = embed "headers-immutable-prototype-test.js")
+        ],
+        compatibilityDate = "2025-11-01",
+        compatibilityFlags = ["nodejs_compat", "immutable_api_prototypes"],
+      )
+    ),
+  ],
+);

src/workerd/io/compatibility-date.capnp

@@ -1221,4 +1221,10 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
     $compatDisableFlag("disable_python_check_rng_state")
     $experimental;
 
+  shouldSetImmutablePrototype @145 :Bool
+    $compatEnableFlag("immutable_api_prototypes")
+    $compatDisableFlag("mutable_api_prototypes");
+  # When set, tells JSG to make the prototype of all jsg::Objects immutable.
+  # TODO(soon): Add the default on date once the flag is verified to be
+  # generally safe.
 }

src/workerd/io/worker.c++

@@ -1052,9 +1052,14 @@ Worker::Isolate::Isolate(kj::Own<Api> apiParam,
     lock->v8Isolate->SetData(jsg::SET_DATA_ISOLATE, this);
 
     lock->setCaptureThrowsAsRejections(features.getCaptureThrowsAsRejections());
+    // TODO(cleanup): Now that this list has grown significantly, we should probably
+    // refactor to pass all of the options in a single call instead of one by one.
     if (features.getSetToStringTag()) {
       lock->setToStringTag();
     }
+    if (features.getShouldSetImmutablePrototype() || features.getPythonWorkers()) {
+      lock->setImmutablePrototype();
+    }
     if (features.getNodeJsCompatV2()) {
       lock->setNodeJsCompatEnabled();
     }

src/workerd/jsg/jsg-test.h

@@ -217,7 +217,6 @@ struct NumberBox: public Object {
   }
 
   JSG_RESOURCE_TYPE(NumberBox) {
-
     JSG_METHOD(increment);
     JSG_METHOD(incrementBy);
     JSG_METHOD(incrementByBox);

src/workerd/jsg/jsg.c++

@@ -231,6 +231,10 @@ void Lock::setToStringTag() {
   IsolateBase::from(v8Isolate).enableSetToStringTag();
 }
 
+void Lock::setImmutablePrototype() {
+  IsolateBase::from(v8Isolate).enableSetImmutablePrototype();
+}
+
 void Lock::setLoggerCallback(kj::Function<Logger>&& logger) {
   IsolateBase::from(v8Isolate).setLoggerCallback({}, kj::mv(logger));
 }

src/workerd/jsg/jsg.h

@@ -2660,6 +2660,7 @@ class Lock {
   void setThrowOnUnrecognizedImportAssertion();
   bool getThrowOnUnrecognizedImportAssertion() const;
   void setToStringTag();
+  void setImmutablePrototype();
   void disableTopLevelAwait();
 
   using Logger = void(Lock&, kj::StringPtr);

src/workerd/jsg/resource.h

@@ -1896,6 +1896,10 @@ class ResourceWrapper {
           static_cast<v8::PropertyAttribute>(v8::PropertyAttribute::DontEnum |
               v8::PropertyAttribute::DontDelete | v8::PropertyAttribute::ReadOnly));
 
+      if (getShouldSetImmutablePrototype(isolate)) {
+        constructor->ReadOnlyPrototype();
+      }
+
       constructor->SetClassName(classname);
 
       static_assert(kj::isSameType<typename T::jsgThis, T>(),

src/workerd/jsg/setup.h

@@ -178,6 +178,14 @@ class IsolateBase {
     setToStringTag = true;
   }
 
+  inline bool shouldSetImmutablePrototype() const {
+    return shouldSetImmutablePrototypeFlag;
+  }
+
+  void enableSetImmutablePrototype() {
+    shouldSetImmutablePrototypeFlag = true;
+  }
+
   inline void disableTopLevelAwait() {
     allowTopLevelAwait = false;
   }
@@ -324,6 +332,7 @@ class IsolateBase {
   bool nodeJsCompatEnabled = false;
   bool nodeJsProcessV2Enabled = false;
   bool setToStringTag = false;
+  bool shouldSetImmutablePrototypeFlag = false;
   bool allowTopLevelAwait = true;
   bool usingNewModuleRegistry = false;
   bool usingEnhancedErrorSerialization = false;