Add a Module API for accessing storage helper functions. (#34284)

* Add a Module API for accessing the Platform.

* Drop overkill module test

* drop unused sample file

* fix import

* Update module API

* fix typo

* fix typo again

* and again

* update api

apps/web/src/modules/Api.ts

@@ -34,6 +34,7 @@ import { WidgetLifecycleApi } from "./WidgetLifecycleApi.ts";
 import { WidgetApi } from "./WidgetApi.ts";
 import { CustomisationsApi } from "./customisationsApi.ts";
 import { ComposerApi } from "./ComposerApi.ts";
+import { StorageHelperApi } from "./StorageHelperApi.ts";
 import { SettingsApi } from "./SettingsApi.ts";
 import defaultDispatcher from "../dispatcher/dispatcher.ts";
 
@@ -97,6 +98,7 @@ export class ModuleApi implements Api {
     public readonly client = new ClientApi();
     public readonly stores = new StoresApi();
     public readonly composer = new ComposerApi(defaultDispatcher);
+    public readonly storageHelper = new StorageHelperApi();
     public readonly settings = new SettingsApi();
 
     public createRoot(element: Element): Root {

apps/web/src/modules/StorageHelperApi.test.ts

@@ -0,0 +1,32 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+// @vitest-environment happy-dom
+
+import { describe, it, expect, vi } from "vitest";
+import { mockPlatformPeg } from "test-utils";
+
+import { StorageHelperApi } from "./StorageHelperApi";
+
+describe("StorageHelperApi", () => {
+    it("should return the pickle key from the platform", async () => {
+        const mockPlatform = mockPlatformPeg();
+        vi.spyOn(mockPlatform, "getPickleKey").mockResolvedValue("test-pickle-key");
+
+        const api = new StorageHelperApi();
+        await expect(api.getPickleKey("@alice:example.org", "DEVICE123")).resolves.toBe("test-pickle-key");
+        expect(mockPlatform.getPickleKey).toHaveBeenCalledWith("@alice:example.org", "DEVICE123");
+    });
+
+    it("should return null if the platform has no pickle key stored", async () => {
+        const mockPlatform = mockPlatformPeg();
+        vi.spyOn(mockPlatform, "getPickleKey").mockResolvedValue(null);
+
+        const api = new StorageHelperApi();
+        await expect(api.getPickleKey("@alice:example.org", "DEVICE123")).resolves.toBeNull();
+    });
+});

apps/web/src/modules/StorageHelperApi.ts

@@ -0,0 +1,15 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { StorageHelperApi as IStorageHelperApi } from "@element-hq/element-web-module-api";
+import PlatformPeg from "../PlatformPeg";
+
+export class StorageHelperApi implements IStorageHelperApi {
+    public async getPickleKey(userId: string, deviceId: string): Promise<string | null> {
+        return PlatformPeg.get()!.getPickleKey(userId, deviceId);
+    }
+}

packages/module-api/element-web-module-api.api.md

@@ -63,6 +63,8 @@ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiEx
     readonly rootNode: HTMLElement;
     // @alpha
     readonly settings: SettingsApi;
+    // @alpha
+    readonly storageHelper: StorageHelperApi;
     readonly stores: StoresApi;
     // @alpha
     readonly widget: WidgetApi;
@@ -495,6 +497,11 @@ export interface SpacePanelItemProps {
     tooltip?: string;
 }
 
+// @alpha
+export interface StorageHelperApi {
+    getPickleKey(userId: string, deviceId: string): Promise<string | null>;
+}
+
 // @public
 export interface StoresApi {
     roomListStore: RoomListStoreApi;

packages/module-api/src/api/index.ts

@@ -24,6 +24,7 @@ import { type WidgetLifecycleApi } from "./widget-lifecycle.ts";
 import { type WidgetApi } from "./widget.ts";
 import { type CustomisationsApi } from "./customisations.ts";
 import { type ComposerApi } from "./composer.ts";
+import { type StorageHelperApi } from "./storage-helper.ts";
 import { type SettingsApi } from "./settings.ts";
 
 /**
@@ -167,6 +168,11 @@ export interface Api
      */
     readonly composer: ComposerApi;
 
+    /**
+     * Allows modules to access storage helper functions.
+     * @alpha Subject to change.
+     */
+    readonly storageHelper: StorageHelperApi;
     /**
      * Allows modules to read application settings.
      * @alpha Subject to change.

packages/module-api/src/api/storage-helper.ts

@@ -0,0 +1,20 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * API for accessing functions that help with storing things.
+ * @alpha Subject to change.
+ */
+export interface StorageHelperApi {
+    /**
+     * Gets a previously stored pickle key, used for encrypting crypto data.
+     * @param userId - the user ID for the user that the pickle key is for.
+     * @param deviceId - the device ID that the pickle key is for.
+     * @returns the previously stored pickle key, or null if no pickle key has been stored.
+     */
+    getPickleKey(userId: string, deviceId: string): Promise<string | null>;
+}

packages/module-api/src/index.ts

@@ -35,6 +35,7 @@ export type * from "./api/widget-lifecycle";
 export type * from "./api/widget";
 export type * from "./api/customisations";
 export { UIComponent } from "./api/customisations";
+export type * from "./api/storage-helper";
 export type * from "./api/settings";
 export * from "./api/watchable";
 export type * from "./utils";