Add onInvalidated event proposal

Author: Carlos Jeurissen

proposals/runtime_on_invalidated.md

@@ -0,0 +1,156 @@
+# 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 contentScripts to be notified when
+background scripts 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 contentScripts to be notified when
+background scripts get invalidated.
+
+#### Use Cases
+
+Cleanup of effects in contentScripts. After-invalidated handling of frames.
+For example, know when to use browser.tabs vs window.open.
+
+### 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 background scripts 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": "disabled", "description": "Specifies the event reason as an uninstallation."}
+  ],
+  "description": "The reason that this event is being dispatched."
+}
+```
+
+### Behavior
+
+Describe the behavior of the new API if there is anything that is not
+immediately obvious from the schema above. Include descriptions of:
+
+*   Behavior on the newly-introduced types and methods.
+The event would be fired when the extension background scripts 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 background
+scripts are 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