Add onInvalidated event proposal

Author: carlosjeurissen

proposals/runtime_on_invalidated.md

@@ -0,0 +1,159 @@
+# Proposal: browser.runtime.onInvalidated event>
+
+** How to Use This Template **
+
+See [Proposal Process](proposal_process.md) for the detailed process on how to
+propose new APIs and use this template.  Each section includes instructions on
+what to include.  Delete the instructions for a given section once it's filled
+out.  Remove this section once the template is filled out.
+
+**Summary**
+
+`browser.runtime.onInvalidated`
+
+This event allows extension frames and content scripts to be notified when
+context get invalidated.
+
+**Document Metadata**
+
+**Author:** carlosjeurissen
+
+**Sponsoring Browser:** Chrome
+
+**Contributors:** TBD
+
+**Created:** 2025-03-26
+
+**Related Issues:** https://github.com/w3c/webextensions/issues/138
+
+## Motivation
+
+### Objective
+
+This event allows extension frames and content scripts to be notified when
+context get invalidated.
+
+#### Use Cases
+
+When the extension context gets invalidated, this means the content script
+or frame can no longer use the chrome APIs or communicate with the extension.
+
+As content script or frame, knowing when this happens is crucial for moving
+forward. Alternatives can be used in this situation, like `window.open` instead
+of `browser.tabs.create`. If moving forward is no option, this event can be
+used for initiating the cleanup of any side effects caused in the frames
+extensions have been operating in.
+
+### Known Consumers
+
+Any extension with a content script which applies certain side effects to the
+web page.
+
+## Specification
+
+### Schema
+
+New onInvalidated event:
+```json
+{
+  "name": "onInvalidated",
+  "type": "function",
+  "description": "Fired when the extension context get invalidated.",
+  "parameters": [
+    {
+      "type": "object",
+      "name": "details",
+      "properties": {
+        "reason": {
+          "optional": true,
+          "$ref": "OnInvalidatedReason",
+          "description": "The reason that this event is being dispatched."
+        }
+      }
+    }
+  ]
+}
+```
+
+Optionally gives a reason of type OnInvalidatedReason
+
+OnInvalidatedReason:
+
+```json
+{
+  "id": "OnInvalidatedReason",
+  "type": "string",
+  "enum": [
+    {"name": "uninstalled", "description": "Specifies the event reason as an uninstallation."},
+    {"name": "update", "description": "Specifies the event reason as an extension update."},
+    {"name": "reload", "description": "Specifies the event reason as an extension reloading."},
+    {"name": "disabled", "description": "Specifies the event reason as an extension disabling."}
+  ],
+  "description": "The reason that this event is being dispatched."
+}
+```
+
+### Behavior
+
+The event would be fired when the extension context get invalidated.
+Browsers can optionally pass a reason which allows an extension to determine
+the proper type of event.
+
+### New Permissions
+
+No new permissions introduced.
+
+### Manifest File Changes
+
+No new manifest fields.
+
+## Security and Privacy
+
+### Exposed Sensitive Data
+
+Document any sensitive data or personally-identifiable information the API
+exposes to the extension.
+
+### Abuse Mitigations
+
+Currently extensions could try checking if an API gets thrown with an
+invalidated error. This would allow an extension to figure out if the extension
+is invalidated. No new abuse surface is introduced.
+
+As for the returned reason. The uninstalled reason can not be abused more than
+currently `browser.runtime.setUninstalledURL`.
+
+As for the `update` reason, this can be figured out by attempting to negotiate
+between the old content script and the new content script.
+
+The `disabled` reason could provide additional information. However this seems
+to not be a big abuse surface.
+
+### Additional Security Considerations
+
+Extensions could potentially leak the onInvalidatedReason if they try hard.
+This does not seem to introduce any attack surfaces.
+
+## Alternatives
+
+### Existing Workarounds
+
+An extension could attempt to run an API which throws when an extension is
+invalidated. This is very expensive as it would require to run this API in a
+loop. In addition, the lack of an onInvalidated event leads to many
+extension developers to not deal with the situation in which the context is
+invalidated. Introducing the onInvalidated encourages developers to handle
+these situations.
+
+### Open Web API
+
+There is no viable path to turn this into an Open Web API.
+
+## Implementation Notes
+
+The event should be fired in the situation in which extension APIs would throw
+with an context invalidated error.
+
+## Future Work
+
+Not at this moment