From 5bb1d3d461e1fec44b7ebf9beeaf2019da79899e Mon Sep 17 00:00:00 2001
From: David Langley <langley.dave@gmail.com>
Date: Wed, 18 Feb 2026 13:17:53 +0000
Subject: [PATCH] Add widget permissions module api

---
 .../element-web-module-api/src/api/index.ts   |  7 ++
 .../src/api/widget-lifecycle.ts               | 82 +++++++++++++++++++
 packages/element-web-module-api/src/index.ts  |  1 +
 3 files changed, 90 insertions(+)
 create mode 100644 packages/element-web-module-api/src/api/widget-lifecycle.ts

diff --git a/packages/element-web-module-api/src/api/index.ts b/packages/element-web-module-api/src/api/index.ts
index 1401e6fc6d..9c5e59ed57 100644
--- a/packages/element-web-module-api/src/api/index.ts
+++ b/packages/element-web-module-api/src/api/index.ts
@@ -19,6 +19,7 @@ import { type ExtrasApi } from "./extras.ts";
 import { type BuiltinsApi } from "./builtins.ts";
 import { type StoresApi } from "./stores.ts";
 import { type ClientApi } from "./client.ts";
+import { type WidgetLifecycleApi } from "./widget-lifecycle.ts";
 
 /**
  * Module interface for modules to implement.
@@ -136,6 +137,12 @@ export interface Api
      */
     readonly client: ClientApi;
 
+    /**
+     * API for modules to auto-approve widget preloading, identity token requests, and capability requests.
+     * @alpha Subject to change.
+     */
+    readonly widgetLifecycle: WidgetLifecycleApi;
+
     /**
      * Create a ReactDOM root for rendering React components.
      * Exposed to allow modules to avoid needing to bundle their own ReactDOM.
diff --git a/packages/element-web-module-api/src/api/widget-lifecycle.ts b/packages/element-web-module-api/src/api/widget-lifecycle.ts
new file mode 100644
index 0000000000..dd8125e397
--- /dev/null
+++ b/packages/element-web-module-api/src/api/widget-lifecycle.ts
@@ -0,0 +1,82 @@
+/*
+Copyright 2026 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * The scope of a widget: room-scoped, user-scoped (account), or an ephemeral modal overlay.
+ * @alpha Subject to change.
+ */
+export type WidgetKind = "room" | "account" | "modal";
+
+/**
+ * A description of a widget passed to approver callbacks.
+ * Contains the information needed to make approval decisions.
+ * @alpha Subject to change.
+ */
+export type WidgetDescriptor = {
+    /** The unique identifier of the widget. */
+    id: string;
+    /** The template URL of the widget, which may contain `$matrix_*` placeholder variables. */
+    templateUrl: string;
+    /** The Matrix user ID of the user who created the widget. */
+    creatorUserId: string;
+    /** The widget type, e.g. `m.custom`, `m.jitsi`, `m.stickerpicker`. */
+    type: string;
+    /** The origin of the widget URL. */
+    origin: string;
+    /** The room ID the widget belongs to, if it is a room widget. */
+    roomId?: string;
+    /** The scope of the widget. */
+    kind: WidgetKind;
+};
+
+/**
+ * Callback that decides whether a widget should be auto-approved for preloading
+ * (i.e. loaded without the user clicking "Continue").
+ * Return `true` to auto-approve, or any other value to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type PreloadApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+/**
+ * Callback that decides whether a widget should be auto-approved to receive
+ * the user's OpenID identity token.
+ * Return `true` to auto-approve, or any other value to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type IdentityApprover = (widget: WidgetDescriptor) => boolean | Promise<boolean> | undefined;
+/**
+ * Callback that decides which of a widget's requested capabilities should be auto-approved.
+ * Return a `Set` of approved capability strings, or `undefined` to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type CapabilitiesApprover = (
+    widget: WidgetDescriptor,
+    requestedCapabilities: Set<string>,
+) => Set<string> | Promise<Set<string> | undefined> | undefined;
+
+/**
+ * API for modules to auto-approve widget preloading, identity token requests, and capability requests.
+ * @alpha Subject to change.
+ */
+export interface WidgetLifecycleApi {
+    /**
+     * Register a handler that can auto-approve widget preloading.
+     * Returning true auto-approves; any other value results in no auto-approval.
+     */
+    registerPreloadApprover(approver: PreloadApprover): void;
+
+    /**
+     * Register a handler that can auto-approve identity token requests.
+     * Returning true auto-approves; any other value results in no auto-approval.
+     */
+    registerIdentityApprover(approver: IdentityApprover): void;
+
+    /**
+     * Register a handler that can auto-approve widget capabilities.
+     * Return a set containing the capabilities to approve.
+     */
+    registerCapabilitiesApprover(approver: CapabilitiesApprover): void;
+}
diff --git a/packages/element-web-module-api/src/index.ts b/packages/element-web-module-api/src/index.ts
index 52a0593bc5..da9c3669d9 100644
--- a/packages/element-web-module-api/src/index.ts
+++ b/packages/element-web-module-api/src/index.ts
@@ -22,4 +22,5 @@ export type * from "./api/navigation";
 export type * from "./api/builtins";
 export type * from "./api/stores";
 export type * from "./api/client";
+export type * from "./api/widget-lifecycle";
 export * from "./api/watchable";