w3c · rdcronin · Aug 22, 2024 · oliverdunk · Sep 12, 2024 · rdcronin
diff --git a/proposals/dom_create_port.md b/proposals/dom_create_port.md
@@ -0,0 +1,206 @@
+# Proposal: Inter (JS) World Communication
+
+**Summary**
+
+This introduces a special message port that can be passed and shared between different JS "worlds" (contexts) in the same document.
+
+**Document Metadata**
+
+**Author:** rdcronin
+
+**Sponsoring Browser:** Chrome
+
+**Contributors:** Rob--W, ...
+
+**Created:** 2024-06-24
+
+**Related Issues:** <TODO>
+
+## Motivation
+
+### Objective
+
+This allows the ability to establish a communication channel between different
+active JS worlds they may have.  This enables coordination between e.g. a main
+content script and any scripts that may inject in the main world, or between a
+content script and other user scripts.
+
+#### Use Cases
+
+The primary use case is coordinating work between different JS worlds in a way
+that is more difficult for any other script in the main world to intercept.
+This helps extensions avoid interacting with the existing page script, when
+doing so is undesirable.  This also allows executing code based on data within
+a content script without leaking the details of that content script to the main
+world.  (Though we don't consider the isolated world boundary a security
+boundary, it is useful isolation and can serve as a "first line of defense").
+
+### Known Consumers
+
+User script managers have expressed an interest in this API.  More broadly,
+this would help any extension that needs to communicate between the main world
+of a web page with a more trusted script.
+
+## Specification
+
+### Schema
+
+```
+declare namespace dom {
+  interface PortProperties {
+    world: ExecutionWorld;
+    worldId?: string;
+  };
+
+  interface MessagePort {
+    sendMessage(args?: any): void
+    onMessage(args?: any): void
-    sendMessage(args?: any): void
-    onMessage(args?: any): void
+    sendMessage(message?: any): void
+    onMessage(message?: any): void
-    sendMessage(args?: any): void
-    onMessage(args?: any): void
+    sendMessage(message?: any): void
+    onMessage(message?: any): void
+  };
+
+  export function createPort(
+      properties: PortProperties
+  ): MessagePort;
+}
+```
+
+### Behavior
+
+#### Creating a Port
+
+An extension can create a new message port using `dom.createPort()`.  This will
+create and return a new message port according to the specifies `properties`
+(see below).
+
+#### Port Properties and World ID
+
+A message port can only be used to communicate with a single other world.  This:
+* Avoids the "many-to-one" opener-listener behavior that existing message ports
+  (created by `runtime.connect()`) in extensions have.  This behavior has caused
+  increased complexity and developer confusion.  A given port will have only one
+  channel.
+* Protects against accidentally sharing the port with another world.
+
+The caller indicates which world it would like the port to be associated with
+by specifying the `world` property to the appropriate type of execution world
+and, if appropriate, the `worldId` (e.g. for specific user script worlds).
+
+#### Passing a Message Port
+
+A message port can be passed to another world (in order to establish a
+connection) by leveraging the new `dom.execute()` API.  `dom.execute()` will be
+expanded to have special serialization logic for the MessagePort type.
-expanded to have special serialization logic for the MessagePort type.
+expanded to have special serialization logic for the MessagePort type.
+
+Once a message port has been passed to a `dom.execute` call, it cannot be passed
+again - an error will be thrown because it is not structurally cloneable.
+
-expanded to have special serialization logic for the MessagePort type.
+expanded to have special serialization logic for the MessagePort type.
+
+Once a message port has been passed to a `dom.execute` call, it cannot be passed
+again - an error will be thrown because it is not structurally cloneable.
+
+
-
+
+### Message dispatch
+
+Upon calling `sendMessage`, `onMessage` is synchronously called before
+`sendMessage` returns. `sendMessage` returns successfully if `onMessage` has
+been called, even if the function itself threw an error.
+
+`sendMessage` may throw if the input message cannot be serialized.
+
+`sendMessage` may throw if the return value cannot be serialized.
+
+`sendMessage` may throw when the recipient is unavailable. For example, if the
+recipient did not assign an `onMessage` listener. Or if the port was never
+delivered to the other world.
+
-
+
+### Message dispatch
+
+Upon calling `sendMessage`, `onMessage` is synchronously called before
+`sendMessage` returns. `sendMessage` returns successfully if `onMessage` has
+been called, even if the function itself threw an error.
+
+`sendMessage` may throw if the input message cannot be serialized.
+
+`sendMessage` may throw if the return value cannot be serialized.
+
+`sendMessage` may throw when the recipient is unavailable. For example, if the
+recipient did not assign an `onMessage` listener. Or if the port was never
+delivered to the other world.
+
+#### Example Usage
+
+Script that executes in the main world:
+```js
+function getFoo() { ... }
+function getBar() { ... }
+// Other code dispatches 'foochanged' and 'barchanged' events.
+```
+
+Content script:
+```js
+// This function will execute in the main world.
+function setUpMainWorld(port) {
+  // This responds to a message received from the content script.
+  port.onMessage = (message) => {
+    if (message == 'getFoo') {
+      const foo = getFoo();
+      port.sendMessage({foo});
+    } else if (message == 'getBar') {
+      const bar = getBar();
+      port.sendMessage({bar});
-      const foo = getFoo();
-      port.sendMessage({foo});
-    } else if (message == 'getBar') {
-      const bar = getBar();
-      port.sendMessage({bar});
+      port.sendMessage({foo:  getFoo()});
+    } else if (message == 'getBar') {
+      port.sendMessage({bar: getBar()});
-      const foo = getFoo();
-      port.sendMessage({foo});
-    } else if (message == 'getBar') {
-      const bar = getBar();
-      port.sendMessage({bar});
+      port.sendMessage({foo:  getFoo()});
+    } else if (message == 'getBar') {
+      port.sendMessage({bar: getBar()});
+    }
+  };
+
+  // These notify the content script of changes.
-  // These notify the content script of changes.
+  // These notify the content script of changes.
+  // NOTE: addEventListener used in this example is not part of the API.
-  // These notify the content script of changes.
+  // These notify the content script of changes.
+  // NOTE: addEventListener used in this example is not part of the API.
+  addEventListener('foochanged', () => {
+    port.sendMessage({foo: getFoo()});
+  });
+  addEventListener('barchanged', () => {
+    port.sendMessage({bar: getBar()});
+  });
+}
+
+// The rest of this code executes in the content script world.
+const mainWorldPort = browser.dom.createPort({world: 'MAIN'});
+
+mainWorldPort.onMessage = (message) => {
+  if (message.foo) {
+    updateFoo(message.foo);
+  } else if (message.bar) {
+    updateBar(message.bar);
+  }
+};
+
+browser.dom.execute(
+    {
+      func: setUpMainWorld,
+      args: mainWorldPort,
-      args: mainWorldPort,
+      args: [mainWorldPort],
-      args: mainWorldPort,
+      args: [mainWorldPort],
+    });
+
+function fetchFoo() {
+  mainWorldPort.sendMessage('getFoo');
+}
+
+function fetchBar() {
+  mainWorldPort.sendMessage('getBar');
+}
+```
+
+##### Message serialization
+
+Message arguments are serialized and deserialized using the Structured Cloning
+algorithm.  This allows for more flexibility than simply JSON conversion.
+Message ports cannot pass other message ports in arguments.
+
+### New Permissions
+
+There are no new permissions for this capability.  This does not allow any new
+data access, since it is only accessible once the extension has already
+injected a script into the document.  Extensions can also already interact with
+the main world of the document through either appending script tags or directly
+injecting with registered content or user scripts, or the
+scripting.executeScript() method.
+
+### Manifest File Changes
+
+There are no necessary manifest changes.
+
+## Security and Privacy
+
+### Exposed Sensitive Data
+
+This does not result in any new data being exposed.
+
+### Abuse Mitigations
+
+This doesn't enable any new data access.  To reduce risk of cross-world
+contamination, extensions must specify the world with which they want to
+communicate, and all arguments are copied rather than directly shared.
+
+### Additional Security Considerations
+
+N/A.
+
-
+
+#### Secrecy of data
+
+This API is designed to offer a secure communication channel between one world
+and an untrusted world. It is the responsibility of the extension to maintain
+further secrecy beyond that. In general, this requires avoiding the use of
+prototype members.
+
+For example, imagine a func that reads `message.foo` in the main world. This
+is safe if `message` is always an object with the `foo` member. If this is not
+the case, then it is a language feature of JavaScript to look up the `foo`
+member in the prototype chain. Most objects ultimately inherit from
+`Object.prototype`, which can be manipulated by other (untrusted) scripts to
+intercept the message.
+
+Example:
+
+```javascript
+// Attack:
+Object.defineProperty(Object.prototype, "foo", {
+  get() { console.log("Intercepted via foo:", this); return "intercepted" }
+});
+
+// Safe use: foo always defined, web page cannot intercept access.
+message = { secret: 1, foo: true };
+console.log("message.foo=", message.foo);
+// Logs "message.foo= true"
+
+// Unsafe use: foo not set; web page can intercept access attempt.
+message = { secret: 1 };
+console.log("message.foo=", message.foo);
+// Logs "Intercepted via foo: { secret: 1 }
+// Logs "message.foo= intercepted"
+```
+
-
+
+#### Secrecy of data
+
+This API is designed to offer a secure communication channel between one world
+and an untrusted world. It is the responsibility of the extension to maintain
+further secrecy beyond that. In general, this requires avoiding the use of
+prototype members.
+
+For example, imagine a func that reads `message.foo` in the main world. This
+is safe if `message` is always an object with the `foo` member. If this is not
+the case, then it is a language feature of JavaScript to look up the `foo`
+member in the prototype chain. Most objects ultimately inherit from
+`Object.prototype`, which can be manipulated by other (untrusted) scripts to
+intercept the message.
+
+Example:
+
+```javascript
+// Attack:
+Object.defineProperty(Object.prototype, "foo", {
+  get() { console.log("Intercepted via foo:", this); return "intercepted" }
+});
+
+// Safe use: foo always defined, web page cannot intercept access.
+message = { secret: 1, foo: true };
+console.log("message.foo=", message.foo);
+// Logs "message.foo= true"
+
+// Unsafe use: foo not set; web page can intercept access attempt.
+message = { secret: 1 };
+console.log("message.foo=", message.foo);
+// Logs "Intercepted via foo: { secret: 1 }
+// Logs "message.foo= intercepted"
+```
+
+## Alternatives
+
+### Existing Workarounds
+
+Today, to communicate between JS worlds, extensions can use custom events as
+described in the [content script
+documentation](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#host-page-communication).
+This is fragile and hacky, and can lean to leaking more data to the embedding
+page.
+
+### Open Web API
+
+The open web is unaware of the concept of multiple Javascript worlds, so this
+wouldn't belong as an open web API.
+
+## Implementation Notes
+
+N/A.
-N/A.
+### Prototype
+To avoid interception by web pages, the prototype chain of the `MessagePort`
+instance should terminate at `null` instead of `Object.prototype`.
+
+Concretely, this means that an instance of `MessagePort` could either inherit
+from a (hidden) MessagePort class \* (which itself has a `null` Prototype), or
+be a plain object with a null Prototype and all specified members as own
+property descriptors.
+
+\* hidden means: not exposed as a global class. If anyone (e.g. the web page)
+ever gets access to a `MessagePort` instance, it may see the hidden prototype
+via `port.__proto__` or `port.constructor.prototype` and through that intercept
+& interfere with all future port communications.
-N/A.
+### Prototype
+To avoid interception by web pages, the prototype chain of the `MessagePort`
+instance should terminate at `null` instead of `Object.prototype`.
+
+Concretely, this means that an instance of `MessagePort` could either inherit
+from a (hidden) MessagePort class \* (which itself has a `null` Prototype), or
+be a plain object with a null Prototype and all specified members as own
+property descriptors.
+
+\* hidden means: not exposed as a global class. If anyone (e.g. the web page)
+ever gets access to a `MessagePort` instance, it may see the hidden prototype
+via `port.__proto__` or `port.constructor.prototype` and through that intercept
+& interfere with all future port communications.
+
+## Future Work