Add widget permissions module api

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.

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;
+}

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";