@metamask/snaps-execution-environments 0.27.0 → 0.28.0

package/dist/common/validation.d.ts

@@ -10,15 +10,15 @@ import { Infer } from 'superstruct';
  */
 export declare function validateExport(type: HandlerType, snapExport: unknown): boolean;
 export declare const JsonRpcRequestWithoutIdStruct: import("superstruct").Struct<{
-    jsonrpc: "2.0";
     method: string;
+    jsonrpc: "2.0";
+    params?: Record<string, Json> | Json[] | undefined;
     id?: string | number | null | undefined;
-    params?: Json[] | Record<string, Json> | undefined;
 }, {
     id: import("superstruct").Struct<string | number | null | undefined, null>;
-    jsonrpc: import("superstruct").Struct<"2.0", "2.0">;
+    params: import("superstruct").Struct<Record<string, Json> | Json[] | undefined, null>;
     method: import("superstruct").Struct<string, null>;
-    params: import("superstruct").Struct<Json[] | Record<string, Json> | undefined, null>;
+    jsonrpc: import("superstruct").Struct<"2.0", "2.0">;
 }>;
 export declare type JsonRpcRequestWithoutId = Infer<typeof JsonRpcRequestWithoutIdStruct>;
 export declare const EndowmentStruct: import("superstruct").Struct<string, null>;
@@ -41,10 +41,10 @@ export declare const PingRequestArgumentsStruct: import("superstruct").Struct<un
 export declare const TerminateRequestArgumentsStruct: import("superstruct").Struct<unknown[] | undefined, null>;
 export declare const ExecuteSnapRequestArgumentsStruct: import("superstruct").Struct<[string, string, string[] | undefined], null>;
 export declare const SnapRpcRequestArgumentsStruct: import("superstruct").Struct<[string, HandlerType, string, {
-    jsonrpc: "2.0";
     method: string;
-    id?: string | number | null | undefined;
+    jsonrpc: "2.0";
     params?: Record<string, Json> | undefined;
+    id?: string | number | null | undefined;
 }], null>;
 export declare type PingRequestArguments = Infer<typeof PingRequestArgumentsStruct>;
 export declare type TerminateRequestArguments = Infer<typeof TerminateRequestArgumentsStruct>;
@@ -71,13 +71,13 @@ export declare type OnTransactionRequestArguments = Infer<typeof OnTransactionRe
  */
 export declare function assertIsOnTransactionRequestArguments(value: unknown): asserts value is OnTransactionRequestArguments;
 declare const OkResponseStruct: import("superstruct").Struct<{
-    jsonrpc: "2.0";
     id: string | number | null;
+    jsonrpc: "2.0";
     result: "OK";
 }, {
     result: import("superstruct").Struct<"OK", "OK">;
-    jsonrpc: import("superstruct").Struct<"2.0", "2.0">;
     id: import("superstruct").Struct<string | number | null, null>;
+    jsonrpc: import("superstruct").Struct<"2.0", "2.0">;
 }>;
 declare const SnapRpcResponse: import("superstruct").Struct<{
     id: string | number | null;

package/dist/offscreen/OffscreenSnapExecutor.d.ts

@@ -0,0 +1,34 @@
+import { BasePostMessageStream, WindowPostMessageStream } from '@metamask/post-message-stream';
+declare type ExecutorJob = {
+    id: string;
+    window: Window;
+    stream: WindowPostMessageStream;
+};
+/**
+ * A snap executor using the Offscreen Documents API.
+ *
+ * This is not a traditional snap executor, as it does not execute snaps itself.
+ * Instead, it creates an iframe window for each snap execution, and sends the
+ * snap execution request to the iframe window. The iframe window is responsible
+ * for executing the snap.
+ *
+ * Extensions can only have a single offscreen document, so this executor is
+ * persisted between snap executions. The offscreen snap executor essentially
+ * acts as a proxy between the extension and the iframe execution environment.
+ *
+ * @see https://developer.chrome.com/docs/extensions/reference/offscreen/
+ */
+export declare class OffscreenSnapExecutor {
+    #private;
+    readonly jobs: Record<string, ExecutorJob>;
+    /**
+     * Initialize the executor with the given stream. This is a wrapper around the
+     * constructor.
+     *
+     * @param stream - The stream to use for communication.
+     * @returns The initialized executor.
+     */
+    static initialize(stream: BasePostMessageStream): OffscreenSnapExecutor;
+    constructor(stream: BasePostMessageStream);
+}
+export {};

package/dist/offscreen/OffscreenSnapExecutor.js

@@ -0,0 +1,104 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _OffscreenSnapExecutor_instances, _OffscreenSnapExecutor_stream, _OffscreenSnapExecutor_onData, _OffscreenSnapExecutor_initializeJob, _OffscreenSnapExecutor_terminateJob;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OffscreenSnapExecutor = void 0;
+const post_message_stream_1 = require("@metamask/post-message-stream");
+const snaps_utils_1 = require("@metamask/snaps-utils");
+const utils_1 = require("@metamask/utils");
+/**
+ * A snap executor using the Offscreen Documents API.
+ *
+ * This is not a traditional snap executor, as it does not execute snaps itself.
+ * Instead, it creates an iframe window for each snap execution, and sends the
+ * snap execution request to the iframe window. The iframe window is responsible
+ * for executing the snap.
+ *
+ * Extensions can only have a single offscreen document, so this executor is
+ * persisted between snap executions. The offscreen snap executor essentially
+ * acts as a proxy between the extension and the iframe execution environment.
+ *
+ * @see https://developer.chrome.com/docs/extensions/reference/offscreen/
+ */
+class OffscreenSnapExecutor {
+    constructor(stream) {
+        _OffscreenSnapExecutor_instances.add(this);
+        _OffscreenSnapExecutor_stream.set(this, void 0);
+        this.jobs = {};
+        __classPrivateFieldSet(this, _OffscreenSnapExecutor_stream, stream, "f");
+        __classPrivateFieldGet(this, _OffscreenSnapExecutor_stream, "f").on('data', __classPrivateFieldGet(this, _OffscreenSnapExecutor_instances, "m", _OffscreenSnapExecutor_onData).bind(this));
+    }
+    /**
+     * Initialize the executor with the given stream. This is a wrapper around the
+     * constructor.
+     *
+     * @param stream - The stream to use for communication.
+     * @returns The initialized executor.
+     */
+    static initialize(stream) {
+        return new OffscreenSnapExecutor(stream);
+    }
+}
+exports.OffscreenSnapExecutor = OffscreenSnapExecutor;
+_OffscreenSnapExecutor_stream = new WeakMap(), _OffscreenSnapExecutor_instances = new WeakSet(), _OffscreenSnapExecutor_onData = function _OffscreenSnapExecutor_onData(data) {
+    const { jobId, frameUrl, data: request } = data;
+    if (!this.jobs[jobId]) {
+        // This ensures that a job is initialized before it is used. To avoid
+        // code duplication, we call the `#onData` method again, which will
+        // run the rest of the logic after initialization.
+        __classPrivateFieldGet(this, _OffscreenSnapExecutor_instances, "m", _OffscreenSnapExecutor_initializeJob).call(this, jobId, frameUrl)
+            .then(() => {
+            __classPrivateFieldGet(this, _OffscreenSnapExecutor_instances, "m", _OffscreenSnapExecutor_onData).call(this, data);
+        })
+            .catch((error) => {
+            console.error('[Worker] Error initializing job:', error);
+        });
+        return;
+    }
+    // This is a method specific to the `OffscreenSnapExecutor`, as the service
+    // itself does not have access to the iframes directly.
+    if (request.method === 'terminateJob') {
+        __classPrivateFieldGet(this, _OffscreenSnapExecutor_instances, "m", _OffscreenSnapExecutor_terminateJob).call(this, jobId);
+        return;
+    }
+    this.jobs[jobId].stream.write(request);
+}, _OffscreenSnapExecutor_initializeJob = 
+/**
+ * Create a new iframe and set up a stream to communicate with it.
+ *
+ * @param jobId - The job ID.
+ * @param frameUrl - The URL to load in the iframe.
+ */
+async function _OffscreenSnapExecutor_initializeJob(jobId, frameUrl) {
+    const window = await (0, snaps_utils_1.createWindow)(frameUrl, jobId);
+    const jobStream = new post_message_stream_1.WindowPostMessageStream({
+        name: 'parent',
+        target: 'child',
+        targetWindow: window,
+        targetOrigin: '*',
+    });
+    // Write messages from the iframe to the parent, wrapped with the job ID.
+    jobStream.on('data', (data) => {
+        __classPrivateFieldGet(this, _OffscreenSnapExecutor_stream, "f").write({ data, jobId });
+    });
+    this.jobs[jobId] = { id: jobId, window, stream: jobStream };
+    return this.jobs[jobId];
+}, _OffscreenSnapExecutor_terminateJob = function _OffscreenSnapExecutor_terminateJob(jobId) {
+    (0, utils_1.assert)(this.jobs[jobId], `Job "${jobId}" not found.`);
+    const iframe = document.getElementById(jobId);
+    (0, utils_1.assert)(iframe, `Iframe with ID "${jobId}" not found.`);
+    iframe.remove();
+    this.jobs[jobId].stream.destroy();
+    delete this.jobs[jobId];
+};
+//# sourceMappingURL=OffscreenSnapExecutor.js.map

package/dist/offscreen/OffscreenSnapExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OffscreenSnapExecutor.js","sourceRoot":"","sources":["../../src/offscreen/OffscreenSnapExecutor.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BasePostMessageStream,\n  WindowPostMessageStream,\n} from '@metamask/post-message-stream';\nimport { createWindow } from '@metamask/snaps-utils';\nimport { JsonRpcRequest, assert } from '@metamask/utils';\n\ntype ExecutorJob = {\n  id: string;\n  window: Window;\n  stream: WindowPostMessageStream;\n};\n\n/**\n * A snap executor using the Offscreen Documents API.\n *\n * This is not a traditional snap executor, as it does not execute snaps itself.\n * Instead, it creates an iframe window for each snap execution, and sends the\n * snap execution request to the iframe window. The iframe window is responsible\n * for executing the snap.\n *\n * Extensions can only have a single offscreen document, so this executor is\n * persisted between snap executions. The offscreen snap executor essentially\n * acts as a proxy between the extension and the iframe execution environment.\n *\n * @see https://developer.chrome.com/docs/extensions/reference/offscreen/\n */\nexport class OffscreenSnapExecutor {\n  readonly #stream: BasePostMessageStream;\n\n  readonly jobs: Record<string, ExecutorJob> = {};\n\n  /**\n   * Initialize the executor with the given stream. This is a wrapper around the\n   * constructor.\n   *\n   * @param stream - The stream to use for communication.\n   * @returns The initialized executor.\n   */\n  static initialize(stream: BasePostMessageStream) {\n    return new OffscreenSnapExecutor(stream);\n  }\n\n  constructor(stream: BasePostMessageStream) {\n    this.#stream = stream;\n    this.#stream.on('data', this.#onData.bind(this));\n  }\n\n  /**\n   * Handle an incoming message from the `OffscreenExecutionService`. This\n   * assumes that the message contains a `jobId` property, and a JSON-RPC\n   * request in the `data` property.\n   *\n   * @param data - The message data.\n   * @param data.data - The JSON-RPC request.\n   * @param data.jobId - The job ID.\n   * @param data.frameUrl - The URL to load in the iframe.\n   */\n  #onData(data: { data: JsonRpcRequest; jobId: string; frameUrl: string }) {\n    const { jobId, frameUrl, data: request } = data;\n\n    if (!this.jobs[jobId]) {\n      // This ensures that a job is initialized before it is used. To avoid\n      // code duplication, we call the `#onData` method again, which will\n      // run the rest of the logic after initialization.\n      this.#initializeJob(jobId, frameUrl)\n        .then(() => {\n          this.#onData(data);\n        })\n        .catch((error) => {\n          console.error('[Worker] Error initializing job:', error);\n        });\n\n      return;\n    }\n\n    // This is a method specific to the `OffscreenSnapExecutor`, as the service\n    // itself does not have access to the iframes directly.\n    if (request.method === 'terminateJob') {\n      this.#terminateJob(jobId);\n      return;\n    }\n\n    this.jobs[jobId].stream.write(request);\n  }\n\n  /**\n   * Create a new iframe and set up a stream to communicate with it.\n   *\n   * @param jobId - The job ID.\n   * @param frameUrl - The URL to load in the iframe.\n   */\n  async #initializeJob(jobId: string, frameUrl: string): Promise<ExecutorJob> {\n    const window = await createWindow(frameUrl, jobId);\n    const jobStream = new WindowPostMessageStream({\n      name: 'parent',\n      target: 'child',\n      targetWindow: window,\n      targetOrigin: '*',\n    });\n\n    // Write messages from the iframe to the parent, wrapped with the job ID.\n    jobStream.on('data', (data) => {\n      this.#stream.write({ data, jobId });\n    });\n\n    this.jobs[jobId] = { id: jobId, window, stream: jobStream };\n    return this.jobs[jobId];\n  }\n\n  /**\n   * Terminate the job with the given ID. This will close the iframe and delete\n   * the job from the internal job map.\n   *\n   * @param jobId - The job ID.\n   */\n  #terminateJob(jobId: string) {\n    assert(this.jobs[jobId], `Job \"${jobId}\" not found.`);\n\n    const iframe = document.getElementById(jobId);\n    assert(iframe, `Iframe with ID \"${jobId}\" not found.`);\n\n    iframe.remove();\n    this.jobs[jobId].stream.destroy();\n    delete this.jobs[jobId];\n  }\n}\n"]}

package/dist/offscreen/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/offscreen/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const post_message_stream_1 = require("@metamask/post-message-stream");
+const lockdown_1 = require("../common/lockdown/lockdown");
+const lockdown_more_1 = require("../common/lockdown/lockdown-more");
+const OffscreenSnapExecutor_1 = require("./OffscreenSnapExecutor");
+(0, lockdown_1.executeLockdown)();
+(0, lockdown_more_1.executeLockdownMore)();
+// The stream from the offscreen document to the execution service.
+const parentStream = new post_message_stream_1.BrowserRuntimePostMessageStream({
+    name: 'child',
+    target: 'parent',
+});
+OffscreenSnapExecutor_1.OffscreenSnapExecutor.initialize(parentStream);
+//# sourceMappingURL=index.js.map

package/dist/offscreen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/offscreen/index.ts"],"names":[],"mappings":";;AAAA,uEAAgF;AAEhF,0DAA8D;AAC9D,oEAAuE;AACvE,mEAAgE;AAEhE,IAAA,0BAAe,GAAE,CAAC;AAClB,IAAA,mCAAmB,GAAE,CAAC;AAEtB,mEAAmE;AACnE,MAAM,YAAY,GAAG,IAAI,qDAA+B,CAAC;IACvD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,QAAQ;CACjB,CAAC,CAAC;AAEH,6CAAqB,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC","sourcesContent":["import { BrowserRuntimePostMessageStream } from '@metamask/post-message-stream';\n\nimport { executeLockdown } from '../common/lockdown/lockdown';\nimport { executeLockdownMore } from '../common/lockdown/lockdown-more';\nimport { OffscreenSnapExecutor } from './OffscreenSnapExecutor';\n\nexecuteLockdown();\nexecuteLockdownMore();\n\n// The stream from the offscreen document to the execution service.\nconst parentStream = new BrowserRuntimePostMessageStream({\n  name: 'child',\n  target: 'parent',\n});\n\nOffscreenSnapExecutor.initialize(parentStream);\n"]}