@metamask/snaps-execution-environments 3.4.2 → 3.5.0

package/dist/types/{offscreen/OffscreenSnapExecutor.d.ts → proxy/ProxySnapExecutor.d.ts}

@@ -6,20 +6,19 @@ declare type ExecutorJob = {
     stream: WindowPostMessageStream;
 };
 /**
- * A snap executor using the Offscreen Documents API.
+ * A "proxy" snap executor that uses a level of indirection to execute snaps.
+ *
+ * Useful for multiple execution environments.
  *
  * 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/
+ * This executor is persisted between snap executions. The executor essentially
+ * acts as a proxy between the client and the iframe execution environment.
  */
-export declare class OffscreenSnapExecutor {
+export declare class ProxySnapExecutor {
     #private;
     readonly jobs: Record<string, ExecutorJob>;
     /**
@@ -27,9 +26,10 @@ export declare class OffscreenSnapExecutor {
      * constructor.
      *
      * @param stream - The stream to use for communication.
+     * @param frameUrl - An optional URL for the iframe to use.
      * @returns The initialized executor.
      */
-    static initialize(stream: BasePostMessageStream): OffscreenSnapExecutor;
-    constructor(stream: BasePostMessageStream);
+    static initialize(stream: BasePostMessageStream, frameUrl?: string): ProxySnapExecutor;
+    constructor(stream: BasePostMessageStream, frameUrl: string);
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask/snaps-execution-environments",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Snap sandbox environments for executing SES javascript",
   "repository": {
     "type": "git",
@@ -44,14 +44,14 @@
     "lint:dependencies": "depcheck"
   },
   "dependencies": {
-    "@metamask/json-rpc-engine": "^7.3.0",
+    "@metamask/json-rpc-engine": "^7.3.1",
     "@metamask/object-multiplex": "^2.0.0",
     "@metamask/post-message-stream": "^7.0.0",
     "@metamask/providers": "^14.0.2",
     "@metamask/rpc-errors": "^6.1.0",
-    "@metamask/snaps-sdk": "^1.3.0",
-    "@metamask/snaps-utils": "^5.0.1",
-    "@metamask/utils": "^8.2.1",
+    "@metamask/snaps-sdk": "^1.4.0",
+    "@metamask/snaps-utils": "^5.2.0",
+    "@metamask/utils": "^8.3.0",
     "nanoid": "^3.1.31",
     "readable-stream": "^3.6.2",
     "superstruct": "^1.0.3"
@@ -62,10 +62,10 @@
     "@babel/preset-typescript": "^7.23.2",
     "@esbuild-plugins/node-globals-polyfill": "^0.2.3",
     "@esbuild-plugins/node-modules-polyfill": "^0.2.2",
-    "@lavamoat/allow-scripts": "^2.5.1",
-    "@lavamoat/lavapack": "^5.4.1",
-    "@lavamoat/lavatube": "^0.2.3",
-    "@metamask/auto-changelog": "^3.4.3",
+    "@lavamoat/allow-scripts": "^3.0.0",
+    "@lavamoat/lavapack": "^6.0.2",
+    "@lavamoat/lavatube": "^1.0.0",
+    "@metamask/auto-changelog": "^3.4.4",
     "@metamask/eslint-config": "^12.1.0",
     "@metamask/eslint-config-jest": "^12.1.0",
     "@metamask/eslint-config-nodejs": "^12.1.0",
@@ -105,13 +105,13 @@
     "jest": "^29.0.2",
     "jest-environment-node": "^29.5.0",
     "jest-fetch-mock": "^3.0.3",
-    "lavamoat": "^7.3.1",
-    "lavamoat-browserify": "^15.9.1",
+    "lavamoat": "^8.0.2",
+    "lavamoat-browserify": "^17.0.2",
     "prettier": "^2.7.1",
     "prettier-plugin-packagejson": "^2.2.11",
     "rimraf": "^4.1.2",
     "serve-handler": "^6.1.5",
-    "ses": "^0.18.8",
+    "ses": "^1.1.0",
     "terser": "^5.17.7",
     "ts-node": "^10.9.1",
     "typescript": "~4.8.4",

package/dist/cjs/offscreen/OffscreenSnapExecutor.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/offscreen/OffscreenSnapExecutor.ts"],"sourcesContent":["import type { BasePostMessageStream } from '@metamask/post-message-stream';\nimport { WindowPostMessageStream } from '@metamask/post-message-stream';\nimport { createWindow, logError } from '@metamask/snaps-utils';\nimport type { JsonRpcRequest } from '@metamask/utils';\nimport { 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.extra - Extra data.\n   * @param data.extra.frameUrl - The URL to load in the iframe.\n   */\n  #onData(data: {\n    data: JsonRpcRequest;\n    jobId: string;\n    extra: { frameUrl: string };\n  }) {\n    const {\n      jobId,\n      extra: { frameUrl },\n      data: request,\n    } = 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          logError('[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"],"names":["OffscreenSnapExecutor","initialize","stream","constructor","jobs","on","onData","bind","data","jobId","extra","frameUrl","request","initializeJob","then","catch","error","logError","method","terminateJob","write","window","createWindow","jobStream","WindowPostMessageStream","name","target","targetWindow","targetOrigin","id","assert","iframe","document","getElementById","remove","destroy"],"mappings":";;;;+BA0BaA;;;eAAAA;;;mCAzB2B;4BACD;uBAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuBZ,uCAoBT;;;;;;;;;;GAUC,GACD,uCA0CM,8CAkBN;;;;;GAKC,GACD;AAlGK,MAAMA;IAKX;;;;;;GAMC,GACD,OAAOC,WAAWC,MAA6B,EAAE;QAC/C,OAAO,IAAIF,sBAAsBE;IACnC;IAEAC,YAAYD,MAA6B,CAAE;QAgB3C,iCAAA;QAoCA;;;;;GAKC,GACD,iCAAM;QAwBN,iCAAA;QAjGA,gCAAS;;mBAAT,KAAA;;QAEA,uBAASE,QAAoC,CAAC;uCActCF,SAASA;QACf,yBAAA,IAAI,EAAEA,SAAOG,EAAE,CAAC,QAAQ,0BAAA,IAAI,EAAEC,SAAAA,QAAOC,IAAI,CAAC,IAAI;IAChD;AAyFF;AA5EE,SAAA,OAAQC,IAIP;IACC,MAAM,EACJC,KAAK,EACLC,OAAO,EAAEC,QAAQ,EAAE,EACnBH,MAAMI,OAAO,EACd,GAAGJ;IAEJ,IAAI,CAAC,IAAI,CAACJ,IAAI,CAACK,MAAM,EAAE;QACrB,qEAAqE;QACrE,mEAAmE;QACnE,kDAAkD;QAClD,0BAAA,IAAI,EAAEI,gBAAAA,oBAAN,IAAI,EAAgBJ,OAAOE,UACxBG,IAAI,CAAC;YACJ,0BAAA,IAAI,EAAER,SAAAA,aAAN,IAAI,EAASE;QACf,GACCO,KAAK,CAAC,CAACC;YACNC,IAAAA,oBAAQ,EAAC,oCAAoCD;QAC/C;QAEF;IACF;IAEA,2EAA2E;IAC3E,uDAAuD;IACvD,IAAIJ,QAAQM,MAAM,KAAK,gBAAgB;QACrC,0BAAA,IAAI,EAAEC,eAAAA,mBAAN,IAAI,EAAeV;QACnB;IACF;IAEA,IAAI,CAACL,IAAI,CAACK,MAAM,CAACP,MAAM,CAACkB,KAAK,CAACR;AAChC;AAQA,eAAA,cAAqBH,KAAa,EAAEE,QAAgB;IAClD,MAAMU,SAAS,MAAMC,IAAAA,wBAAY,EAACX,UAAUF;IAC5C,MAAMc,YAAY,IAAIC,0CAAuB,CAAC;QAC5CC,MAAM;QACNC,QAAQ;QACRC,cAAcN;QACdO,cAAc;IAChB;IAEA,yEAAyE;IACzEL,UAAUlB,EAAE,CAAC,QAAQ,CAACG;QACpB,yBAAA,IAAI,EAAEN,SAAOkB,KAAK,CAAC;YAAEZ;YAAMC;QAAM;IACnC;IAEA,IAAI,CAACL,IAAI,CAACK,MAAM,GAAG;QAAEoB,IAAIpB;QAAOY;QAAQnB,QAAQqB;IAAU;IAC1D,OAAO,IAAI,CAACnB,IAAI,CAACK,MAAM;AACzB;AAQA,SAAA,aAAcA,KAAa;IACzBqB,IAAAA,aAAM,EAAC,IAAI,CAAC1B,IAAI,CAACK,MAAM,EAAE,CAAC,KAAK,EAAEA,MAAM,YAAY,CAAC;IAEpD,MAAMsB,SAASC,SAASC,cAAc,CAACxB;IACvCqB,IAAAA,aAAM,EAACC,QAAQ,CAAC,gBAAgB,EAAEtB,MAAM,YAAY,CAAC;IAErDsB,OAAOG,MAAM;IACb,IAAI,CAAC9B,IAAI,CAACK,MAAM,CAACP,MAAM,CAACiC,OAAO;IAC/B,OAAO,IAAI,CAAC/B,IAAI,CAACK,MAAM;AACzB"}

package/dist/esm/offscreen/OffscreenSnapExecutor.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/offscreen/OffscreenSnapExecutor.ts"],"sourcesContent":["import type { BasePostMessageStream } from '@metamask/post-message-stream';\nimport { WindowPostMessageStream } from '@metamask/post-message-stream';\nimport { createWindow, logError } from '@metamask/snaps-utils';\nimport type { JsonRpcRequest } from '@metamask/utils';\nimport { 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.extra - Extra data.\n   * @param data.extra.frameUrl - The URL to load in the iframe.\n   */\n  #onData(data: {\n    data: JsonRpcRequest;\n    jobId: string;\n    extra: { frameUrl: string };\n  }) {\n    const {\n      jobId,\n      extra: { frameUrl },\n      data: request,\n    } = 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          logError('[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"],"names":["WindowPostMessageStream","createWindow","logError","assert","OffscreenSnapExecutor","initialize","stream","constructor","jobs","on","onData","bind","data","jobId","extra","frameUrl","request","initializeJob","then","catch","error","method","terminateJob","write","window","jobStream","name","target","targetWindow","targetOrigin","id","iframe","document","getElementById","remove","destroy"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,SAASA,uBAAuB,QAAQ,gCAAgC;AACxE,SAASC,YAAY,EAAEC,QAAQ,QAAQ,wBAAwB;AAE/D,SAASC,MAAM,QAAQ,kBAAkB;IAuB9B,uCAoBT;;;;;;;;;;GAUC,GACD,uCA0CM,8CAkBN;;;;;GAKC,GACD;AAhHF;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMC;IAKX;;;;;;GAMC,GACD,OAAOC,WAAWC,MAA6B,EAAE;QAC/C,OAAO,IAAIF,sBAAsBE;IACnC;IAEAC,YAAYD,MAA6B,CAAE;QAgB3C,iCAAA;QAoCA;;;;;GAKC,GACD,iCAAM;QAwBN,iCAAA;QAjGA,gCAAS;;mBAAT,KAAA;;QAEA,uBAASE,QAAoC,CAAC;uCActCF,SAASA;QACf,yBAAA,IAAI,EAAEA,SAAOG,EAAE,CAAC,QAAQ,0BAAA,IAAI,EAAEC,SAAAA,QAAOC,IAAI,CAAC,IAAI;IAChD;AAyFF;AA5EE,SAAA,OAAQC,IAIP;IACC,MAAM,EACJC,KAAK,EACLC,OAAO,EAAEC,QAAQ,EAAE,EACnBH,MAAMI,OAAO,EACd,GAAGJ;IAEJ,IAAI,CAAC,IAAI,CAACJ,IAAI,CAACK,MAAM,EAAE;QACrB,qEAAqE;QACrE,mEAAmE;QACnE,kDAAkD;QAClD,0BAAA,IAAI,EAAEI,gBAAAA,oBAAN,IAAI,EAAgBJ,OAAOE,UACxBG,IAAI,CAAC;YACJ,0BAAA,IAAI,EAAER,SAAAA,aAAN,IAAI,EAASE;QACf,GACCO,KAAK,CAAC,CAACC;YACNlB,SAAS,oCAAoCkB;QAC/C;QAEF;IACF;IAEA,2EAA2E;IAC3E,uDAAuD;IACvD,IAAIJ,QAAQK,MAAM,KAAK,gBAAgB;QACrC,0BAAA,IAAI,EAAEC,eAAAA,mBAAN,IAAI,EAAeT;QACnB;IACF;IAEA,IAAI,CAACL,IAAI,CAACK,MAAM,CAACP,MAAM,CAACiB,KAAK,CAACP;AAChC;AAQA,eAAA,cAAqBH,KAAa,EAAEE,QAAgB;IAClD,MAAMS,SAAS,MAAMvB,aAAac,UAAUF;IAC5C,MAAMY,YAAY,IAAIzB,wBAAwB;QAC5C0B,MAAM;QACNC,QAAQ;QACRC,cAAcJ;QACdK,cAAc;IAChB;IAEA,yEAAyE;IACzEJ,UAAUhB,EAAE,CAAC,QAAQ,CAACG;QACpB,yBAAA,IAAI,EAAEN,SAAOiB,KAAK,CAAC;YAAEX;YAAMC;QAAM;IACnC;IAEA,IAAI,CAACL,IAAI,CAACK,MAAM,GAAG;QAAEiB,IAAIjB;QAAOW;QAAQlB,QAAQmB;IAAU;IAC1D,OAAO,IAAI,CAACjB,IAAI,CAACK,MAAM;AACzB;AAQA,SAAA,aAAcA,KAAa;IACzBV,OAAO,IAAI,CAACK,IAAI,CAACK,MAAM,EAAE,CAAC,KAAK,EAAEA,MAAM,YAAY,CAAC;IAEpD,MAAMkB,SAASC,SAASC,cAAc,CAACpB;IACvCV,OAAO4B,QAAQ,CAAC,gBAAgB,EAAElB,MAAM,YAAY,CAAC;IAErDkB,OAAOG,MAAM;IACb,IAAI,CAAC1B,IAAI,CAACK,MAAM,CAACP,MAAM,CAAC6B,OAAO;IAC/B,OAAO,IAAI,CAAC3B,IAAI,CAACK,MAAM;AACzB"}