@metamask/snaps-utils 2.0.1 → 3.1.0

package/dist/esm/virtual-file/VirtualFile.js

@@ -19,13 +19,19 @@ function _define_property(obj, key, value) {
     }
     return obj;
 }
-import { assert } from '@metamask/utils';
+import { assert, bytesToHex } from '@metamask/utils';
+import { base64 } from '@scure/base';
 import { deepClone } from '../deep-clone';
 export class VirtualFile {
     toString(encoding) {
         if (typeof this.value === 'string') {
             assert(encoding === undefined, 'Tried to encode string.');
             return this.value;
+        } else if (this.value instanceof Uint8Array && encoding === 'hex') {
+            return bytesToHex(this.value);
+        } else if (this.value instanceof Uint8Array && encoding === 'base64') {
+            // TODO: Use @metamask/utils for this
+            return base64.encode(this.value);
         }
         const decoder = new TextDecoder(encoding);
         return decoder.decode(this.value);

package/dist/esm/virtual-file/VirtualFile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/virtual-file/VirtualFile.ts"],"sourcesContent":["// TODO(ritave): Move into separate package @metamask/vfile / @metamask/utils + @metamask/to-vfile when passes code review\n// TODO(ritave): Streaming vfile contents similar to vinyl maybe?\n// TODO(ritave): Move fixing manifest in cli and bundler plugins to write messages to vfile\n//               similar to unified instead of throwing \"ProgrammaticallyFixableErrors\".\n//\n// Using https://github.com/vfile/vfile would be helpful, but they only support ESM and we need to support CommonJS.\n// https://github.com/gulpjs/vinyl is also good, but they normalize paths, which we can't do, because\n// we're calculating checksums based on original path.\nimport { assert } from '@metamask/utils';\n\nimport { deepClone } from '../deep-clone';\n\n/**\n * This map registers the type of the {@link VirtualFile.data} key of a {@link VirtualFile}.\n *\n * This type can be augmented to register custom `data` types.\n *\n * @example\n * declare module '@metamask/snaps-utils' {\n *   interface DataMap {\n *     // `file.data.name` is typed as `string`\n *     name: string\n *   }\n * }\n */\n// eslint-disable-next-line @typescript-eslint/consistent-type-definitions, @typescript-eslint/no-empty-interface\nexport interface DataMap {}\n\nexport type Value = string | Uint8Array;\nexport type Compatible<Result = unknown> =\n  | string\n  | Uint8Array\n  | Options<Result>;\nexport type Data = Record<string, unknown> & Partial<DataMap>;\nexport type Options<Result = unknown> = {\n  value: Value;\n  path?: string;\n  data?: Data;\n  result?: Result;\n};\n\nexport class VirtualFile<Result = unknown> {\n  constructor(value?: Compatible<Result>) {\n    let options: Options | undefined;\n    if (typeof value === 'string' || value instanceof Uint8Array) {\n      options = { value };\n    } else {\n      options = value;\n    }\n\n    this.value = options?.value ?? '';\n    // This situations happens when there's no .result used,\n    // we expect the file to have default generic in that situation:\n    // VirtualFile<unknown> which will handle undefined properly\n    //\n    // While not 100% type safe, it'll be way less frustrating to work with.\n    // The alternative would be to have VirtualFile.result be Result | undefined\n    // and that would result in needing to branch out and check in all situations.\n    //\n    // In short, optimizing for most common use case.\n    this.result = options?.result ?? (undefined as any);\n    this.data = options?.data ?? {};\n    this.path = options?.path ?? '/';\n  }\n\n  value: Value;\n\n  result: Result;\n\n  data: Data;\n\n  path: string;\n\n  toString(encoding?: string) {\n    if (typeof this.value === 'string') {\n      assert(encoding === undefined, 'Tried to encode string.');\n      return this.value;\n    }\n    const decoder = new TextDecoder(encoding);\n    return decoder.decode(this.value);\n  }\n\n  clone() {\n    const vfile = new VirtualFile<Result>();\n    if (typeof this.value === 'string') {\n      vfile.value = this.value;\n    } else {\n      // deep-clone doesn't clone Buffer properly, even if it's a sub-class of Uint8Array\n      vfile.value = this.value.slice(0);\n    }\n    vfile.result = deepClone(this.result);\n    vfile.data = deepClone(this.data);\n    vfile.path = this.path;\n    return vfile;\n  }\n}\n"],"names":["assert","deepClone","VirtualFile","toString","encoding","value","undefined","decoder","TextDecoder","decode","clone","vfile","slice","result","data","path","constructor","options","Uint8Array"],"mappings":"AAAA,0HAA0H;AAC1H,iEAAiE;AACjE,2FAA2F;AAC3F,wFAAwF;AACxF,EAAE;AACF,oHAAoH;AACpH,qGAAqG;AACrG,sDAAsD;;;;;;;;;;;;;;AACtD,SAASA,MAAM,QAAQ,kBAAkB;AAEzC,SAASC,SAAS,QAAQ,gBAAgB;AA+B1C,OAAO,MAAMC;IAgCXC,SAASC,QAAiB,EAAE;QAC1B,IAAI,OAAO,IAAI,CAACC,KAAK,KAAK,UAAU;YAClCL,OAAOI,aAAaE,WAAW;YAC/B,OAAO,IAAI,CAACD,KAAK;QACnB;QACA,MAAME,UAAU,IAAIC,YAAYJ;QAChC,OAAOG,QAAQE,MAAM,CAAC,IAAI,CAACJ,KAAK;IAClC;IAEAK,QAAQ;QACN,MAAMC,QAAQ,IAAIT;QAClB,IAAI,OAAO,IAAI,CAACG,KAAK,KAAK,UAAU;YAClCM,MAAMN,KAAK,GAAG,IAAI,CAACA,KAAK;QAC1B,OAAO;YACL,mFAAmF;YACnFM,MAAMN,KAAK,GAAG,IAAI,CAACA,KAAK,CAACO,KAAK,CAAC;QACjC;QACAD,MAAME,MAAM,GAAGZ,UAAU,IAAI,CAACY,MAAM;QACpCF,MAAMG,IAAI,GAAGb,UAAU,IAAI,CAACa,IAAI;QAChCH,MAAMI,IAAI,GAAG,IAAI,CAACA,IAAI;QACtB,OAAOJ;IACT;IApDAK,YAAYX,KAA0B,CAAE;QAuBxCA,uBAAAA,SAAAA,KAAAA;QAEAQ,uBAAAA,UAAAA,KAAAA;QAEAC,uBAAAA,QAAAA,KAAAA;QAEAC,uBAAAA,QAAAA,KAAAA;QA5BE,IAAIE;QACJ,IAAI,OAAOZ,UAAU,YAAYA,iBAAiBa,YAAY;YAC5DD,UAAU;gBAAEZ;YAAM;QACpB,OAAO;YACLY,UAAUZ;QACZ;QAEA,IAAI,CAACA,KAAK,GAAGY,SAASZ,SAAS;QAC/B,wDAAwD;QACxD,gEAAgE;QAChE,4DAA4D;QAC5D,EAAE;QACF,wEAAwE;QACxE,4EAA4E;QAC5E,8EAA8E;QAC9E,EAAE;QACF,iDAAiD;QACjD,IAAI,CAACQ,MAAM,GAAGI,SAASJ,UAAWP;QAClC,IAAI,CAACQ,IAAI,GAAGG,SAASH,QAAQ,CAAC;QAC9B,IAAI,CAACC,IAAI,GAAGE,SAASF,QAAQ;IAC/B;AAgCF"}
+{"version":3,"sources":["../../../src/virtual-file/VirtualFile.ts"],"sourcesContent":["// TODO(ritave): Move into separate package @metamask/vfile / @metamask/utils + @metamask/to-vfile when passes code review\n// TODO(ritave): Streaming vfile contents similar to vinyl maybe?\n// TODO(ritave): Move fixing manifest in cli and bundler plugins to write messages to vfile\n//               similar to unified instead of throwing \"ProgrammaticallyFixableErrors\".\n//\n// Using https://github.com/vfile/vfile would be helpful, but they only support ESM and we need to support CommonJS.\n// https://github.com/gulpjs/vinyl is also good, but they normalize paths, which we can't do, because\n// we're calculating checksums based on original path.\nimport { assert, bytesToHex } from '@metamask/utils';\nimport { base64 } from '@scure/base';\n\nimport { deepClone } from '../deep-clone';\n\n/**\n * This map registers the type of the {@link VirtualFile.data} key of a {@link VirtualFile}.\n *\n * This type can be augmented to register custom `data` types.\n *\n * @example\n * declare module '@metamask/snaps-utils' {\n *   interface DataMap {\n *     // `file.data.name` is typed as `string`\n *     name: string\n *   }\n * }\n */\n// eslint-disable-next-line @typescript-eslint/consistent-type-definitions, @typescript-eslint/no-empty-interface\nexport interface DataMap {}\n\nexport type Value = string | Uint8Array;\nexport type Compatible<Result = unknown> =\n  | string\n  | Uint8Array\n  | Options<Result>;\nexport type Data = Record<string, unknown> & Partial<DataMap>;\nexport type Options<Result = unknown> = {\n  value: Value;\n  path?: string;\n  data?: Data;\n  result?: Result;\n};\n\nexport class VirtualFile<Result = unknown> {\n  constructor(value?: Compatible<Result>) {\n    let options: Options | undefined;\n    if (typeof value === 'string' || value instanceof Uint8Array) {\n      options = { value };\n    } else {\n      options = value;\n    }\n\n    this.value = options?.value ?? '';\n    // This situations happens when there's no .result used,\n    // we expect the file to have default generic in that situation:\n    // VirtualFile<unknown> which will handle undefined properly\n    //\n    // While not 100% type safe, it'll be way less frustrating to work with.\n    // The alternative would be to have VirtualFile.result be Result | undefined\n    // and that would result in needing to branch out and check in all situations.\n    //\n    // In short, optimizing for most common use case.\n    this.result = options?.result ?? (undefined as any);\n    this.data = options?.data ?? {};\n    this.path = options?.path ?? '/';\n  }\n\n  value: Value;\n\n  result: Result;\n\n  data: Data;\n\n  path: string;\n\n  toString(encoding?: string) {\n    if (typeof this.value === 'string') {\n      assert(encoding === undefined, 'Tried to encode string.');\n      return this.value;\n    } else if (this.value instanceof Uint8Array && encoding === 'hex') {\n      return bytesToHex(this.value);\n    } else if (this.value instanceof Uint8Array && encoding === 'base64') {\n      // TODO: Use @metamask/utils for this\n      return base64.encode(this.value);\n    }\n    const decoder = new TextDecoder(encoding);\n    return decoder.decode(this.value);\n  }\n\n  clone() {\n    const vfile = new VirtualFile<Result>();\n    if (typeof this.value === 'string') {\n      vfile.value = this.value;\n    } else {\n      // deep-clone doesn't clone Buffer properly, even if it's a sub-class of Uint8Array\n      vfile.value = this.value.slice(0);\n    }\n    vfile.result = deepClone(this.result);\n    vfile.data = deepClone(this.data);\n    vfile.path = this.path;\n    return vfile;\n  }\n}\n"],"names":["assert","bytesToHex","base64","deepClone","VirtualFile","toString","encoding","value","undefined","Uint8Array","encode","decoder","TextDecoder","decode","clone","vfile","slice","result","data","path","constructor","options"],"mappings":"AAAA,0HAA0H;AAC1H,iEAAiE;AACjE,2FAA2F;AAC3F,wFAAwF;AACxF,EAAE;AACF,oHAAoH;AACpH,qGAAqG;AACrG,sDAAsD;;;;;;;;;;;;;;AACtD,SAASA,MAAM,EAAEC,UAAU,QAAQ,kBAAkB;AACrD,SAASC,MAAM,QAAQ,cAAc;AAErC,SAASC,SAAS,QAAQ,gBAAgB;AA+B1C,OAAO,MAAMC;IAgCXC,SAASC,QAAiB,EAAE;QAC1B,IAAI,OAAO,IAAI,CAACC,KAAK,KAAK,UAAU;YAClCP,OAAOM,aAAaE,WAAW;YAC/B,OAAO,IAAI,CAACD,KAAK;QACnB,OAAO,IAAI,IAAI,CAACA,KAAK,YAAYE,cAAcH,aAAa,OAAO;YACjE,OAAOL,WAAW,IAAI,CAACM,KAAK;QAC9B,OAAO,IAAI,IAAI,CAACA,KAAK,YAAYE,cAAcH,aAAa,UAAU;YACpE,qCAAqC;YACrC,OAAOJ,OAAOQ,MAAM,CAAC,IAAI,CAACH,KAAK;QACjC;QACA,MAAMI,UAAU,IAAIC,YAAYN;QAChC,OAAOK,QAAQE,MAAM,CAAC,IAAI,CAACN,KAAK;IAClC;IAEAO,QAAQ;QACN,MAAMC,QAAQ,IAAIX;QAClB,IAAI,OAAO,IAAI,CAACG,KAAK,KAAK,UAAU;YAClCQ,MAAMR,KAAK,GAAG,IAAI,CAACA,KAAK;QAC1B,OAAO;YACL,mFAAmF;YACnFQ,MAAMR,KAAK,GAAG,IAAI,CAACA,KAAK,CAACS,KAAK,CAAC;QACjC;QACAD,MAAME,MAAM,GAAGd,UAAU,IAAI,CAACc,MAAM;QACpCF,MAAMG,IAAI,GAAGf,UAAU,IAAI,CAACe,IAAI;QAChCH,MAAMI,IAAI,GAAG,IAAI,CAACA,IAAI;QACtB,OAAOJ;IACT;IAzDAK,YAAYb,KAA0B,CAAE;QAuBxCA,uBAAAA,SAAAA,KAAAA;QAEAU,uBAAAA,UAAAA,KAAAA;QAEAC,uBAAAA,QAAAA,KAAAA;QAEAC,uBAAAA,QAAAA,KAAAA;QA5BE,IAAIE;QACJ,IAAI,OAAOd,UAAU,YAAYA,iBAAiBE,YAAY;YAC5DY,UAAU;gBAAEd;YAAM;QACpB,OAAO;YACLc,UAAUd;QACZ;QAEA,IAAI,CAACA,KAAK,GAAGc,SAASd,SAAS;QAC/B,wDAAwD;QACxD,gEAAgE;QAChE,4DAA4D;QAC5D,EAAE;QACF,wEAAwE;QACxE,4EAA4E;QAC5E,8EAA8E;QAC9E,EAAE;QACF,iDAAiD;QACjD,IAAI,CAACU,MAAM,GAAGI,SAASJ,UAAWT;QAClC,IAAI,CAACU,IAAI,GAAGG,SAASH,QAAQ,CAAC;QAC9B,IAAI,CAACC,IAAI,GAAGE,SAASF,QAAQ;IAC/B;AAqCF"}

package/dist/esm/virtual-file/toVirtualFile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/virtual-file/toVirtualFile.ts"],"sourcesContent":["import { promises as fsPromises } from 'fs';\n\nimport { VirtualFile } from './VirtualFile';\n\n/**\n * Reads a file from filesystem and creates a vfile.\n *\n * @param path - Filesystem path to load the contents from.\n * @param encoding - Optional encoding to pass down to fs.readFile.\n * @returns Promise returning VFile with loaded file contents.\n */\nexport async function readVirtualFile(\n  path: string,\n  encoding: BufferEncoding | null = null,\n) {\n  return new VirtualFile({\n    path,\n    value: await fsPromises.readFile(path, { encoding }),\n  });\n}\n\ntype WriteVFileOptions = Exclude<\n  Parameters<typeof fsPromises['writeFile']>[2],\n  undefined\n>;\n\n/**\n * Writes vfile to filesystem.\n *\n * @param vfile - The vfile to write.\n * @param options - Options to pass down to fs.writeFile.\n */\nexport async function writeVirtualFile(\n  vfile: VirtualFile,\n  options?: WriteVFileOptions,\n) {\n  return fsPromises.writeFile(vfile.path, vfile.value, options);\n}\n"],"names":["promises","fsPromises","VirtualFile","readVirtualFile","path","encoding","value","readFile","writeVirtualFile","vfile","options","writeFile"],"mappings":"AAAA,SAASA,YAAYC,UAAU,QAAQ,KAAK;AAE5C,SAASC,WAAW,QAAQ,gBAAgB;AAE5C;;;;;;CAMC,GACD,OAAO,eAAeC,gBACpBC,IAAY,EACZC,WAAkC,IAAI;IAEtC,OAAO,IAAIH,YAAY;QACrBE;QACAE,OAAO,MAAML,WAAWM,QAAQ,CAACH,MAAM;YAAEC;QAAS;IACpD;AACF;AAOA;;;;;CAKC,GACD,OAAO,eAAeG,iBACpBC,KAAkB,EAClBC,OAA2B;IAE3B,OAAOT,WAAWU,SAAS,CAACF,MAAML,IAAI,EAAEK,MAAMH,KAAK,EAAEI;AACvD"}
+{"version":3,"sources":["../../../src/virtual-file/toVirtualFile.ts"],"sourcesContent":["import { promises as fsPromises } from 'fs';\n\nimport { VirtualFile } from './VirtualFile';\n\n/**\n * Reads a file from filesystem and creates a vfile.\n *\n * @param path - Filesystem path to load the contents from.\n * @param encoding - Optional encoding to pass down to fs.readFile.\n * @returns Promise returning VFile with loaded file contents.\n */\nexport async function readVirtualFile(\n  path: string,\n  encoding: BufferEncoding | null = null,\n) {\n  return new VirtualFile({\n    path,\n    value: await fsPromises.readFile(path, { encoding }),\n  });\n}\n\ntype WriteVFileOptions = Exclude<\n  Parameters<(typeof fsPromises)['writeFile']>[2],\n  undefined\n>;\n\n/**\n * Writes vfile to filesystem.\n *\n * @param vfile - The vfile to write.\n * @param options - Options to pass down to fs.writeFile.\n */\nexport async function writeVirtualFile(\n  vfile: VirtualFile,\n  options?: WriteVFileOptions,\n) {\n  return fsPromises.writeFile(vfile.path, vfile.value, options);\n}\n"],"names":["promises","fsPromises","VirtualFile","readVirtualFile","path","encoding","value","readFile","writeVirtualFile","vfile","options","writeFile"],"mappings":"AAAA,SAASA,YAAYC,UAAU,QAAQ,KAAK;AAE5C,SAASC,WAAW,QAAQ,gBAAgB;AAE5C;;;;;;CAMC,GACD,OAAO,eAAeC,gBACpBC,IAAY,EACZC,WAAkC,IAAI;IAEtC,OAAO,IAAIH,YAAY;QACrBE;QACAE,OAAO,MAAML,WAAWM,QAAQ,CAACH,MAAM;YAAEC;QAAS;IACpD;AACF;AAOA;;;;;CAKC,GACD,OAAO,eAAeG,iBACpBC,KAAkB,EAClBC,OAA2B;IAE3B,OAAOT,WAAWU,SAAS,CAACF,MAAML,IAAI,EAAEK,MAAMH,KAAK,EAAEI;AACvD"}

package/dist/types/auxiliary-files.d.ts

@@ -0,0 +1,13 @@
+export declare enum AuxiliaryFileEncoding {
+    Base64 = "base64",
+    Hex = "hex",
+    Utf8 = "utf8"
+}
+/**
+ * Re-encodes an auxiliary file if needed depending on the requested file encoding.
+ *
+ * @param value - The base64 value stored for the auxiliary file.
+ * @param encoding - The chosen encoding.
+ * @returns The file encoded in the requested encoding.
+ */
+export declare function encodeAuxiliaryFile(value: string, encoding: AuxiliaryFileEncoding): string;

package/dist/types/caveats.d.ts

@@ -19,6 +19,10 @@ export declare enum SnapCaveatType {
      * The origins that a Snap can receive JSON-RPC messages from.
      */
     RpcOrigin = "rpcOrigin",
+    /**
+     * The origins that a Snap can receive keyring messages from.
+     */
+    KeyringOrigin = "keyringOrigin",
     /**
      * Caveat specifying the snap IDs that can be interacted with.
      */

package/dist/types/errors.d.ts

@@ -1,3 +1,6 @@
+import { JsonRpcError as RpcError } from '@metamask/rpc-errors';
+import type { DataWithOptionalCause } from '@metamask/rpc-errors';
+import type { Json, JsonRpcError } from '@metamask/utils';
 /**
  * Get the error message from an unknown error type.
  *
@@ -8,3 +11,182 @@
  * @returns The error message.
  */
 export declare function getErrorMessage(error: unknown): string;
+/**
+ * Get the error stack from an unknown error type.
+ *
+ * @param error - The error to get the stack from.
+ * @returns The error stack, or undefined if the error does not have a valid
+ * stack.
+ */
+export declare function getErrorStack(error: unknown): string | undefined;
+/**
+ * Get the error code from an unknown error type.
+ *
+ * @param error - The error to get the code from.
+ * @returns The error code, or `-32603` if the error does not have a valid code.
+ */
+export declare function getErrorCode(error: unknown): number;
+/**
+ * Get the error data from an unknown error type.
+ *
+ * @param error - The error to get the data from.
+ * @returns The error data, or an empty object if the error does not have valid
+ * data.
+ */
+export declare function getErrorData(error: unknown): {
+    [prop: string]: Json;
+};
+export declare const SNAP_ERROR_WRAPPER_CODE = -31001;
+export declare const SNAP_ERROR_WRAPPER_MESSAGE = "Wrapped Snap Error";
+export declare const SNAP_ERROR_CODE = -31002;
+export declare const SNAP_ERROR_MESSAGE = "Snap Error";
+export declare type SerializedSnapErrorWrapper = {
+    code: typeof SNAP_ERROR_WRAPPER_CODE;
+    message: typeof SNAP_ERROR_WRAPPER_MESSAGE;
+    data: {
+        cause: Json;
+    };
+};
+export declare type SerializedSnapError = {
+    code: typeof SNAP_ERROR_CODE;
+    message: typeof SNAP_ERROR_MESSAGE;
+    data: {
+        cause: JsonRpcError & {
+            data: Record<string, Json>;
+        };
+    };
+};
+export declare class WrappedSnapError extends Error {
+    #private;
+    /**
+     * Create a new `WrappedSnapError`.
+     *
+     * @param error - The error to create the `WrappedSnapError` from.
+     */
+    constructor(error: unknown);
+    /**
+     * The error name.
+     *
+     * @returns The error name.
+     */
+    get name(): string;
+    /**
+     * The error message.
+     *
+     * @returns The error message.
+     */
+    get message(): string;
+    /**
+     * The error stack.
+     *
+     * @returns The error stack.
+     */
+    get stack(): string | undefined;
+    /**
+     * Convert the error to a JSON object.
+     *
+     * @returns The JSON object.
+     */
+    toJSON(): SerializedSnapErrorWrapper;
+    /**
+     * Serialize the error to a JSON object. This is called by
+     * `@metamask/rpc-errors` when serializing the error.
+     *
+     * @returns The JSON object.
+     */
+    serialize(): SerializedSnapErrorWrapper;
+}
+/**
+ * A generic error which can be thrown by a Snap, without it causing the Snap to
+ * crash.
+ */
+export declare class SnapError extends Error {
+    #private;
+    /**
+     * Create a new `SnapError`.
+     *
+     * @param error - The error to create the `SnapError` from. If this is a
+     * `string`, it will be used as the error message. If this is an `Error`, its
+     * `message` property will be used as the error message. If this is a
+     * `JsonRpcError`, its `message` property will be used as the error message
+     * and its `code` property will be used as the error code. Otherwise, the
+     * error will be converted to a string and used as the error message.
+     * @param data - Additional data to include in the error. This will be merged
+     * with the error data, if any.
+     */
+    constructor(error: string | Error | JsonRpcError, data?: Record<string, Json>);
+    /**
+     * The error name.
+     *
+     * @returns The error name.
+     */
+    get name(): string;
+    /**
+     * The error code.
+     *
+     * @returns The error code.
+     */
+    get code(): number;
+    /**
+     * The error message.
+     *
+     * @returns The error message.
+     */
+    get message(): string;
+    /**
+     * Additional data for the error.
+     *
+     * @returns Additional data for the error.
+     */
+    get data(): Record<string, Json>;
+    /**
+     * The error stack.
+     *
+     * @returns The error stack.
+     */
+    get stack(): string | undefined;
+    /**
+     * Convert the error to a JSON object.
+     *
+     * @returns The JSON object.
+     */
+    toJSON(): SerializedSnapError;
+    /**
+     * Serialize the error to a JSON object. This is called by
+     * `@metamask/rpc-errors` when serializing the error.
+     *
+     * @returns The JSON object.
+     */
+    serialize(): SerializedSnapError;
+}
+/**
+ * Check if an object is a `SnapError`.
+ *
+ * @param error - The object to check.
+ * @returns Whether the object is a `SnapError`.
+ */
+export declare function isSnapError(error: unknown): error is SnapError;
+/**
+ * Check if a JSON-RPC error is a `SnapError`.
+ *
+ * @param error - The object to check.
+ * @returns Whether the object is a `SnapError`.
+ */
+export declare function isSerializedSnapError(error: JsonRpcError): error is SerializedSnapError;
+/**
+ * Check if a JSON-RPC error is a `WrappedSnapError`.
+ *
+ * @param error - The object to check.
+ * @returns Whether the object is a `WrappedSnapError`.
+ */
+export declare function isWrappedSnapError(error: unknown): error is SerializedSnapErrorWrapper;
+/**
+ * Attempt to unwrap an unknown error to a `JsonRpcError`. This function will
+ * try to get the error code, message, and data from the error, and return a
+ * `JsonRpcError` with those properties.
+ *
+ * @param error - The error to unwrap.
+ * @returns A tuple containing the unwrapped error and a boolean indicating
+ * whether the error was handled.
+ */
+export declare function unwrapError(error: unknown): [error: RpcError<DataWithOptionalCause>, isHandled: boolean];

package/dist/types/handlers.d.ts

@@ -8,7 +8,8 @@ export declare enum HandlerType {
     OnCronjob = "onCronjob",
     OnInstall = "onInstall",
     OnUpdate = "onUpdate",
-    OnNameLookup = "onNameLookup"
+    OnNameLookup = "onNameLookup",
+    OnKeyringRequest = "onKeyringRequest"
 }
 declare type SnapHandler = {
     /**
@@ -62,6 +63,11 @@ export declare const SNAP_EXPORTS: {
         readonly required: false;
         readonly validator: (snapExport: unknown) => snapExport is LifecycleEventHandler;
     };
+    readonly onKeyringRequest: {
+        readonly type: HandlerType.OnKeyringRequest;
+        readonly required: true;
+        readonly validator: (snapExport: unknown) => snapExport is OnKeyringRequestHandler<JsonRpcParams>;
+    };
 };
 /**
  * The `onRpcRequest` handler. This is called whenever a JSON-RPC request is
@@ -142,6 +148,19 @@ export declare type OnInstallHandler = LifecycleEventHandler;
  * This type is an alias for {@link LifecycleEventHandler}.
  */
 export declare type OnUpdateHandler = LifecycleEventHandler;
+/**
+ * The `onKeyringRequest` handler. This is called by the MetaMask client for
+ * privileged keyring actions.
+ *
+ * @param args - The request arguments.
+ * @param args.origin - The origin of the request. This can be the ID of
+ * another snap, or the URL of a dapp.
+ * @param args.request - The JSON-RPC request sent to the snap.
+ */
+export declare type OnKeyringRequestHandler<Params extends JsonRpcParams = JsonRpcParams> = (args: {
+    origin: string;
+    request: JsonRpcRequest<Params>;
+}) => Promise<unknown>;
 /**
  * Utility type for getting the handler function type from a handler type.
  */
@@ -187,7 +206,7 @@ export declare type OnNameLookupHandler = (args: OnNameLookupArgs) => Promise<On
  * All the function-based handlers that a snap can implement.
  */
 export declare type SnapFunctionExports = {
-    [Key in keyof typeof SNAP_EXPORTS]?: HandlerFunction<typeof SNAP_EXPORTS[Key]>;
+    [Key in keyof typeof SNAP_EXPORTS]?: HandlerFunction<(typeof SNAP_EXPORTS)[Key]>;
 };
 /**
  * All handlers that a snap can implement.

package/dist/types/index.browser.d.ts

@@ -1,4 +1,5 @@
 export * from './array';
+export * from './auxiliary-files';
 export * from './caveats';
 export * from './checksum';
 export * from './cronjob';

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './array';
+export * from './auxiliary-files';
 export * from './caveats';
 export * from './cronjob';
 export * from './checksum';

package/dist/types/index.executionenv.d.ts

@@ -1,3 +1,4 @@
+export * from './errors';
 export * from './handlers';
 export * from './logging';
 export * from './namespace';

package/dist/types/json-rpc.d.ts

@@ -1,11 +1,14 @@
-import type { Json, JsonRpcSuccess, AssertionErrorConstructor } from '@metamask/utils';
+import { SubjectType } from '@metamask/permission-controller';
+import type { AssertionErrorConstructor, Json, JsonRpcSuccess } from '@metamask/utils';
 import type { Infer } from 'superstruct';
 export declare const RpcOriginsStruct: import("superstruct").Struct<{
     dapps?: boolean | undefined;
     snaps?: boolean | undefined;
+    allowedOrigins?: string[] | undefined;
 }, {
     dapps: import("superstruct").Struct<boolean | undefined, null>;
     snaps: import("superstruct").Struct<boolean | undefined, null>;
+    allowedOrigins: import("superstruct").Struct<string[] | undefined, import("superstruct").Struct<string, null>>;
 }>;
 export declare type RpcOrigins = Infer<typeof RpcOriginsStruct>;
 /**
@@ -17,6 +20,30 @@ export declare type RpcOrigins = Infer<typeof RpcOriginsStruct>;
  * @throws If the value is not a valid {@link RpcOrigins} object.
  */
 export declare function assertIsRpcOrigins(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is RpcOrigins;
+export declare const KeyringOriginsStruct: import("superstruct").Struct<{
+    allowedOrigins?: string[] | undefined;
+}, {
+    allowedOrigins: import("superstruct").Struct<string[] | undefined, import("superstruct").Struct<string, null>>;
+}>;
+export declare type KeyringOrigins = Infer<typeof KeyringOriginsStruct>;
+/**
+ * Assert that the given value is a valid {@link KeyringOrigins} object.
+ *
+ * @param value - The value to assert.
+ * @param ErrorWrapper - An optional error wrapper to use. Defaults to
+ * {@link AssertionError}.
+ * @throws If the value is not a valid {@link KeyringOrigins} object.
+ */
+export declare function assertIsKeyringOrigins(value: unknown, ErrorWrapper?: AssertionErrorConstructor): asserts value is KeyringOrigins;
+/**
+ * Check if the given origin is allowed by the given JSON-RPC origins object.
+ *
+ * @param origins - The JSON-RPC origins object.
+ * @param subjectType - The type of the origin.
+ * @param origin - The origin to check.
+ * @returns Whether the origin is allowed.
+ */
+export declare function isOriginAllowed(origins: RpcOrigins, subjectType: SubjectType, origin: string): boolean;
 /**
  * Assert that the given value is a successful JSON-RPC response. If the value
  * is not a success response, an error is thrown. If the value is an JSON-RPC

package/dist/types/manifest/manifest.d.ts

@@ -66,6 +66,15 @@ export declare function getSnapSourceCode(basePath: string, manifest: Json, sour
  * @returns The contents of the icon, if any.
  */
 export declare function getSnapIcon(basePath: string, manifest: Json): Promise<VirtualFile | undefined>;
+/**
+ * Given an unvalidated Snap manifest, attempts to extract the auxiliary files
+ * and read them.
+ *
+ * @param basePath - The path to the folder with the manifest files.
+ * @param manifest - The unvalidated Snap manifest file contents.
+ * @returns A list of auxiliary files and their contents, if any.
+ */
+export declare function getSnapAuxiliaryFiles(basePath: string, manifest: Json): Promise<VirtualFile[] | undefined>;
 /**
  * Sorts the given manifest in our preferred sort order and removes the
  * `repository` field if it is falsy (it may be `null`).
@@ -83,5 +92,6 @@ export declare function getWritableManifest(manifest: SnapManifest): SnapManifes
  * @param snapFiles.packageJson - The npm Snap's `package.json`.
  * @param snapFiles.sourceCode - The Snap's source code.
  * @param snapFiles.svgIcon - The Snap's optional icon.
+ * @param snapFiles.auxiliaryFiles - Any auxiliary files required by the snap at runtime.
  */
-export declare function validateNpmSnapManifest({ manifest, packageJson, sourceCode, svgIcon, }: SnapFiles): void;
+export declare function validateNpmSnapManifest({ manifest, packageJson, sourceCode, svgIcon, auxiliaryFiles, }: SnapFiles): void;

package/dist/types/manifest/validation.d.ts

@@ -55,8 +55,12 @@ export declare const PermissionsStruct: Struct<{
     'endowment:rpc'?: {
         dapps?: boolean | undefined;
         snaps?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
     } | undefined;
     'endowment:name-lookup'?: string[] | undefined;
+    'endowment:keyring'?: {
+        allowedOrigins?: string[] | undefined;
+    } | undefined;
     snap_dialog?: {} | undefined;
     snap_confirm?: {} | undefined;
     snap_manageState?: {} | undefined;
@@ -130,11 +134,18 @@ export declare const PermissionsStruct: Struct<{
     'endowment:rpc': Struct<{
         dapps?: boolean | undefined;
         snaps?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
     } | undefined, {
         dapps: Struct<boolean | undefined, null>;
         snaps: Struct<boolean | undefined, null>;
+        allowedOrigins: Struct<string[] | undefined, Struct<string, null>>;
     }>;
     'endowment:name-lookup': Struct<string[] | undefined, Struct<string, null>>;
+    'endowment:keyring': Struct<{
+        allowedOrigins?: string[] | undefined;
+    } | undefined, {
+        allowedOrigins: Struct<string[] | undefined, Struct<string, null>>;
+    }>;
     snap_dialog: Struct<{} | undefined, {}>;
     snap_confirm: Struct<{} | undefined, {}>;
     snap_manageState: Struct<{} | undefined, {}>;
@@ -179,6 +190,7 @@ export declare const PermissionsStruct: Struct<{
     }> | undefined, null>;
 }>;
 export declare type SnapPermissions = Infer<typeof PermissionsStruct>;
+export declare const SnapAuxilaryFilesStruct: Struct<string[], Struct<string, null>>;
 export declare const SnapManifestStruct: Struct<{
     description: string;
     version: import("@metamask/utils").SemVerVersion;
@@ -193,6 +205,7 @@ export declare const SnapManifestStruct: Struct<{
             };
         };
         shasum: string;
+        files?: string[] | undefined;
     };
     initialPermissions: {
         'endowment:network-access'?: {} | undefined;
@@ -214,8 +227,12 @@ export declare const SnapManifestStruct: Struct<{
         'endowment:rpc'?: {
             dapps?: boolean | undefined;
             snaps?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
         } | undefined;
         'endowment:name-lookup'?: string[] | undefined;
+        'endowment:keyring'?: {
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
         snap_dialog?: {} | undefined;
         snap_confirm?: {} | undefined;
         snap_manageState?: {} | undefined;
@@ -264,6 +281,7 @@ export declare const SnapManifestStruct: Struct<{
             };
         };
         shasum: string;
+        files?: string[] | undefined;
     }, {
         shasum: Struct<string, null>;
         location: Struct<{
@@ -286,6 +304,7 @@ export declare const SnapManifestStruct: Struct<{
                 registry: Struct<"https://registry.npmjs.org" | "https://registry.npmjs.org/", null>;
             }>;
         }>;
+        files: Struct<string[] | undefined, Struct<string, null>>;
     }>;
     initialPermissions: Struct<{
         'endowment:network-access'?: {} | undefined;
@@ -307,8 +326,12 @@ export declare const SnapManifestStruct: Struct<{
         'endowment:rpc'?: {
             dapps?: boolean | undefined;
             snaps?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
         } | undefined;
         'endowment:name-lookup'?: string[] | undefined;
+        'endowment:keyring'?: {
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
         snap_dialog?: {} | undefined;
         snap_confirm?: {} | undefined;
         snap_manageState?: {} | undefined;
@@ -382,11 +405,18 @@ export declare const SnapManifestStruct: Struct<{
         'endowment:rpc': Struct<{
             dapps?: boolean | undefined;
             snaps?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
         } | undefined, {
             dapps: Struct<boolean | undefined, null>;
             snaps: Struct<boolean | undefined, null>;
+            allowedOrigins: Struct<string[] | undefined, Struct<string, null>>;
         }>;
         'endowment:name-lookup': Struct<string[] | undefined, Struct<string, null>>;
+        'endowment:keyring': Struct<{
+            allowedOrigins?: string[] | undefined;
+        } | undefined, {
+            allowedOrigins: Struct<string[] | undefined, Struct<string, null>>;
+        }>;
         snap_dialog: Struct<{} | undefined, {}>;
         snap_confirm: Struct<{} | undefined, {}>;
         snap_manageState: Struct<{} | undefined, {}>;

package/dist/types/snaps.d.ts

@@ -1,10 +1,9 @@
 import type { SubjectPermissions, PermissionConstraint } from '@metamask/permission-controller';
 import type { BlockReason } from '@metamask/snaps-registry';
-import type { Json, SemVerVersion, Opaque } from '@metamask/utils';
-import type { SerializedEthereumRpcError } from 'eth-rpc-errors/dist/classes';
+import type { Json, JsonRpcError, Opaque, SemVerVersion } from '@metamask/utils';
 import type { Struct } from 'superstruct';
 import type { SnapManifest, SnapPermissions } from './manifest/validation';
-import type { SnapFiles, SnapId, SnapsPermissionRequest } from './types';
+import type { FetchedSnapFiles, SnapId, SnapsPermissionRequest } from './types';
 import { SnapIdPrefixes, SnapValidationFailureReason } from './types';
 export declare const PROPOSED_NAME_REGEX: RegExp;
 /**
@@ -44,6 +43,10 @@ export declare type VersionHistory = {
     version: string;
     date: number;
 };
+export declare type SnapAuxilaryFile = {
+    path: string;
+    value: string;
+};
 export declare type PersistedSnap = Snap;
 /**
  * A Snap as it exists in {@link SnapController} state.
@@ -91,6 +94,10 @@ export declare type Snap = {
      * Can be used to derive when the Snap was installed, when it was updated to a certain version and who requested the change.
      */
     versionHistory: VersionHistory[];
+    /**
+     * Static auxiliary files that can be loaded at runtime.
+     */
+    auxiliaryFiles?: SnapAuxilaryFile[];
 };
 export declare type TruncatedSnapFields = 'id' | 'initialPermissions' | 'version' | 'enabled' | 'blocked';
 /**
@@ -99,7 +106,7 @@ export declare type TruncatedSnapFields = 'id' | 'initialPermissions' | 'version
  */
 export declare type TruncatedSnap = Pick<Snap, TruncatedSnapFields>;
 export declare type ProcessSnapResult = TruncatedSnap | {
-    error: SerializedEthereumRpcError;
+    error: JsonRpcError;
 };
 export declare type InstallSnapsResult = Record<SnapId, ProcessSnapResult>;
 /**
@@ -116,7 +123,7 @@ export declare class ProgrammaticallyFixableSnapError extends Error {
  * @param files - All required Snap files to be included in the checksum.
  * @returns The Base64-encoded SHA-256 digest of the source code.
  */
-export declare function getSnapChecksum(files: Pick<SnapFiles, 'manifest' | 'sourceCode' | 'svgIcon'>): string;
+export declare function getSnapChecksum(files: FetchedSnapFiles): string;
 /**
  * Checks whether the `source.shasum` property of a Snap manifest matches the
  * shasum of the snap.
@@ -124,7 +131,7 @@ export declare function getSnapChecksum(files: Pick<SnapFiles, 'manifest' | 'sou
  * @param files - All required Snap files to be included in the checksum.
  * @param errorMessage - The error message to throw if validation fails.
  */
-export declare function validateSnapShasum(files: Pick<SnapFiles, 'manifest' | 'sourceCode' | 'svgIcon'>, errorMessage?: string): void;
+export declare function validateSnapShasum(files: FetchedSnapFiles, errorMessage?: string): void;
 export declare const LOCALHOST_HOSTNAMES: readonly ["localhost", "127.0.0.1", "[::1]"];
 export declare const BaseSnapIdStruct: Struct<string, null>;
 export declare const LocalSnapIdStruct: Struct<string, null>;

package/dist/types/types.d.ts

@@ -53,6 +53,7 @@ export declare type UnvalidatedSnapFiles = {
     packageJson?: VirtualFile<Json>;
     sourceCode?: VirtualFile;
     svgIcon?: VirtualFile;
+    auxiliaryFiles: VirtualFile[];
 };
 /**
  * An object for storing the contents of Snap files that have passed JSON
@@ -63,7 +64,12 @@ export declare type SnapFiles = {
     packageJson: VirtualFile<NpmSnapPackageJson>;
     sourceCode: VirtualFile;
     svgIcon?: VirtualFile;
+    auxiliaryFiles: VirtualFile[];
 };
+/**
+ * A subset of snap files extracted from a fetched snap.
+ */
+export declare type FetchedSnapFiles = Pick<SnapFiles, 'manifest' | 'sourceCode' | 'svgIcon' | 'auxiliaryFiles'>;
 /**
  * The possible prefixes for snap ids.
  */

package/dist/types/validation.d.ts

@@ -1,8 +1,8 @@
-import type { SnapFiles } from './types';
+import type { FetchedSnapFiles } from './types';
 /**
  * Validates the files contained in a fetched snap.
  *
  * @param files - All potentially included files in a fetched snap.
  * @throws If any of the files are considered invalid.
  */
-export declare function validateFetchedSnap(files: Pick<SnapFiles, 'manifest' | 'sourceCode' | 'svgIcon'>): void;
+export declare function validateFetchedSnap(files: FetchedSnapFiles): void;

package/dist/types/virtual-file/toVirtualFile.d.ts

@@ -10,7 +10,7 @@ import { VirtualFile } from './VirtualFile';
  * @returns Promise returning VFile with loaded file contents.
  */
 export declare function readVirtualFile(path: string, encoding?: BufferEncoding | null): Promise<VirtualFile<unknown>>;
-declare type WriteVFileOptions = Exclude<Parameters<typeof fsPromises['writeFile']>[2], undefined>;
+declare type WriteVFileOptions = Exclude<Parameters<(typeof fsPromises)['writeFile']>[2], undefined>;
 /**
  * Writes vfile to filesystem.
  *