@metamask/snaps-rpc-methods 3.1.0

package/dist/types/restricted/invokeSnap.d.ts

@@ -0,0 +1,62 @@
+import type { PermissionSpecificationBuilder, RestrictedMethodOptions, PermissionValidatorConstraint, PermissionSideEffect } from '@metamask/permission-controller';
+import { PermissionType } from '@metamask/permission-controller';
+import type { Snap, SnapId, SnapRpcHookArgs, RequestedSnapPermissions, InstallSnapsResult } from '@metamask/snaps-utils';
+import type { Json, NonEmptyArray } from '@metamask/utils';
+import type { MethodHooksObject } from '../utils';
+export declare const WALLET_SNAP_PERMISSION_KEY = "wallet_snap";
+export declare type InstallSnaps = {
+    type: `SnapController:install`;
+    handler: (origin: string, requestedSnaps: RequestedSnapPermissions) => Promise<InstallSnapsResult>;
+};
+export declare type GetPermittedSnaps = {
+    type: `SnapController:getPermitted`;
+    handler: (origin: string) => InstallSnapsResult;
+};
+declare type AllowedActions = InstallSnaps | GetPermittedSnaps;
+export declare type InvokeSnapMethodHooks = {
+    getSnap: (snapId: SnapId) => Snap | undefined;
+    handleSnapRpcRequest: ({ snapId, origin, handler, request, }: SnapRpcHookArgs & {
+        snapId: SnapId;
+    }) => Promise<unknown>;
+};
+declare type InvokeSnapSpecificationBuilderOptions = {
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    methodHooks: InvokeSnapMethodHooks;
+};
+export declare type InvokeSnapParams = {
+    snapId: string;
+    request: Record<string, unknown>;
+};
+/**
+ * The side-effect method to handle the snap install.
+ *
+ * @param params - The side-effect params.
+ * @param params.requestData - The request data associated to the requested permission.
+ * @param params.messagingSystem - The messenger to call an action.
+ */
+export declare const handleSnapInstall: PermissionSideEffect<AllowedActions, never>['onPermitted'];
+export declare const invokeSnapBuilder: Readonly<{
+    readonly targetName: "wallet_snap";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, InvokeSnapSpecificationBuilderOptions, {
+        permissionType: PermissionType.RestrictedMethod;
+        targetName: typeof WALLET_SNAP_PERMISSION_KEY;
+        methodImplementation: ReturnType<typeof getInvokeSnapImplementation>;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+        validator: PermissionValidatorConstraint;
+        sideEffect: {
+            onPermitted: PermissionSideEffect<AllowedActions, never>['onPermitted'];
+        };
+    }>;
+    readonly methodHooks: MethodHooksObject<InvokeSnapMethodHooks>;
+}>;
+/**
+ * Builds the method implementation for `wallet_snap_*`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.getSnap - A function that retrieves all information stored about a snap.
+ * @param hooks.handleSnapRpcRequest - A function that sends an RPC request to a snap's RPC handler or throws if that fails.
+ * @returns The method implementation which returns the result of `handleSnapRpcRequest`.
+ * @throws If the params are invalid.
+ */
+export declare function getInvokeSnapImplementation({ getSnap, handleSnapRpcRequest, }: InvokeSnapMethodHooks): (options: RestrictedMethodOptions<Record<string, Json>>) => Promise<Json>;
+export {};

package/dist/types/restricted/manageAccounts.d.ts

@@ -0,0 +1,63 @@
+import type { RestrictedMethodOptions, ValidPermissionSpecification, PermissionSpecificationBuilder } from '@metamask/permission-controller';
+import { PermissionType } from '@metamask/permission-controller';
+import type { Json, NonEmptyArray } from '@metamask/utils';
+import type { Infer } from 'superstruct';
+declare const SnapMessageStruct: import("superstruct").Struct<{
+    method: string;
+} | {
+    params: Record<string, Json> | Json[];
+    method: string;
+}, null>;
+declare type Message = Infer<typeof SnapMessageStruct>;
+export declare const methodName = "snap_manageAccounts";
+export declare type ManageAccountsMethodHooks = {
+    /**
+     * Gets the snap keyring implementation.
+     */
+    getSnapKeyring: (snapOrigin: string) => Promise<{
+        handleKeyringSnapMessage: (snapId: string, message: Message) => Promise<Json>;
+    }>;
+};
+declare type ManageAccountsSpecificationBuilderOptions = {
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    methodHooks: ManageAccountsMethodHooks;
+};
+declare type ManageAccountsSpecification = ValidPermissionSpecification<{
+    permissionType: PermissionType.RestrictedMethod;
+    targetName: typeof methodName;
+    methodImplementation: ReturnType<typeof manageAccountsImplementation>;
+    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+}>;
+/**
+ * The specification builder for the `snap_manageAccounts` permission.
+ * `snap_manageAccounts` lets the Snap manage a set of accounts via a custom keyring.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_manageAccounts` permission.
+ */
+export declare const specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageAccountsSpecificationBuilderOptions, ManageAccountsSpecification>;
+/**
+ * Builds the method implementation for `snap_manageAccounts`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.getSnapKeyring - A function to get the snap keyring.
+ * @returns The method implementation which either returns `null` for a
+ * successful state update/deletion or returns the decrypted state.
+ * @throws If the params are invalid.
+ */
+export declare function manageAccountsImplementation({ getSnapKeyring, }: ManageAccountsMethodHooks): (options: RestrictedMethodOptions<Message>) => Promise<Json>;
+export declare const manageAccountsBuilder: Readonly<{
+    readonly targetName: "snap_manageAccounts";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageAccountsSpecificationBuilderOptions, {
+        permissionType: PermissionType.RestrictedMethod;
+        targetName: typeof methodName;
+        methodImplementation: ReturnType<typeof manageAccountsImplementation>;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+    readonly methodHooks: {
+        readonly getSnapKeyring: true;
+    };
+}>;
+export {};

package/dist/types/restricted/manageState.d.ts

@@ -0,0 +1,127 @@
+import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from '@metamask/permission-controller';
+import { PermissionType } from '@metamask/permission-controller';
+import type { EnumToUnion } from '@metamask/snaps-utils';
+import type { Json, NonEmptyArray, Hex } from '@metamask/utils';
+import type { MethodHooksObject } from '../utils';
+export declare const STATE_ENCRYPTION_SALT = "snap_manageState encryption";
+declare const methodName = "snap_manageState";
+export declare type ManageStateMethodHooks = {
+    /**
+     * @returns The mnemonic of the user's primary keyring.
+     */
+    getMnemonic: () => Promise<Uint8Array>;
+    /**
+     * Waits for the extension to be unlocked.
+     *
+     * @returns A promise that resolves once the extension is unlocked.
+     */
+    getUnlockPromise: (shouldShowUnlockRequest: boolean) => Promise<void>;
+    /**
+     * A function that clears the state of the requesting Snap.
+     */
+    clearSnapState: (snapId: string) => Promise<void>;
+    /**
+     * A function that gets the encrypted state of the requesting Snap.
+     *
+     * @returns The current state of the Snap.
+     */
+    getSnapState: (snapId: string) => Promise<string>;
+    /**
+     * A function that updates the state of the requesting Snap.
+     *
+     * @param newState - The new state of the Snap.
+     */
+    updateSnapState: (snapId: string, newState: string) => Promise<void>;
+    /**
+     * Encrypts data with a key. This is assumed to perform symmetric encryption.
+     *
+     * @param key - The key to use for encryption, in hexadecimal format.
+     * @param data - The JSON data to encrypt.
+     * @returns The ciphertext as a string. The format for this string is
+     * dependent on the implementation, but MUST be a string.
+     */
+    encrypt: (key: string, data: Json) => Promise<string>;
+    /**
+     * Decrypts data with a key. This is assumed to perform symmetric decryption.
+     *
+     * @param key - The key to use for decryption, in hexadecimal format.
+     * @param cipherText - The ciphertext to decrypt. The format for this string
+     * is dependent on the implementation, but MUST be a string.
+     * @returns The decrypted data as a JSON object.
+     */
+    decrypt: (key: Hex, cipherText: string) => Promise<unknown>;
+};
+declare type ManageStateSpecificationBuilderOptions = {
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    methodHooks: ManageStateMethodHooks;
+};
+declare type ManageStateSpecification = ValidPermissionSpecification<{
+    permissionType: PermissionType.RestrictedMethod;
+    targetName: typeof methodName;
+    methodImplementation: ReturnType<typeof getManageStateImplementation>;
+    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+}>;
+/**
+ * The specification builder for the `snap_manageState` permission.
+ * `snap_manageState` lets the Snap store and manage some of its state on
+ * your device.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_manageState` permission.
+ */
+export declare const specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageStateSpecificationBuilderOptions, ManageStateSpecification>;
+export declare const manageStateBuilder: Readonly<{
+    readonly targetName: "snap_manageState";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageStateSpecificationBuilderOptions, {
+        permissionType: PermissionType.RestrictedMethod;
+        targetName: typeof methodName;
+        methodImplementation: ReturnType<typeof getManageStateImplementation>;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+    readonly methodHooks: MethodHooksObject<ManageStateMethodHooks>;
+}>;
+export declare enum ManageStateOperation {
+    ClearState = "clear",
+    GetState = "get",
+    UpdateState = "update"
+}
+export declare type ManageStateArgs = {
+    operation: EnumToUnion<ManageStateOperation>;
+    newState?: Record<string, Json>;
+};
+export declare const STORAGE_SIZE_LIMIT = 104857600;
+/**
+ * Builds the method implementation for `snap_manageState`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.clearSnapState - A function that clears the state stored for a
+ * snap.
+ * @param hooks.getSnapState - A function that fetches the persisted decrypted
+ * state for a snap.
+ * @param hooks.updateSnapState - A function that updates the state stored for a
+ * snap.
+ * @param hooks.getMnemonic - A function to retrieve the Secret Recovery Phrase
+ * of the user.
+ * @param hooks.getUnlockPromise - A function that resolves once the MetaMask
+ * extension is unlocked and prompts the user to unlock their MetaMask if it is
+ * locked.
+ * @param hooks.encrypt - A function that encrypts the given state.
+ * @param hooks.decrypt - A function that decrypts the given state.
+ * @returns The method implementation which either returns `null` for a
+ * successful state update/deletion or returns the decrypted state.
+ * @throws If the params are invalid.
+ */
+export declare function getManageStateImplementation({ getMnemonic, getUnlockPromise, clearSnapState, getSnapState, updateSnapState, encrypt, decrypt, }: ManageStateMethodHooks): (options: RestrictedMethodOptions<ManageStateArgs>) => Promise<null | Record<string, Json>>;
+/**
+ * Validates the manageState method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @param method - RPC method name used for debugging errors.
+ * @param storageSizeLimit - Maximum allowed size (in bytes) of a new state object.
+ * @returns The validated method parameter object.
+ */
+export declare function getValidatedParams(params: unknown, method: string, storageSizeLimit?: number): ManageStateArgs;
+export {};

package/dist/types/restricted/notify.d.ts

@@ -0,0 +1,81 @@
+import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from '@metamask/permission-controller';
+import { PermissionType } from '@metamask/permission-controller';
+import type { EnumToUnion } from '@metamask/snaps-utils';
+import type { NonEmptyArray } from '@metamask/utils';
+import type { MethodHooksObject } from '../utils';
+declare const methodName = "snap_notify";
+export declare enum NotificationType {
+    InApp = "inApp",
+    Native = "native"
+}
+export declare type NotificationArgs = {
+    /**
+     * Enum type to determine notification type.
+     */
+    type: EnumToUnion<NotificationType>;
+    /**
+     * A message to show on the notification.
+     */
+    message: string;
+};
+export declare type NotifyMethodHooks = {
+    /**
+     * @param snapId - The ID of the Snap that created the notification.
+     * @param args - The notification arguments.
+     */
+    showNativeNotification: (snapId: string, args: NotificationArgs) => Promise<null>;
+    /**
+     * @param snapId - The ID of the Snap that created the notification.
+     * @param args - The notification arguments.
+     */
+    showInAppNotification: (snapId: string, args: NotificationArgs) => Promise<null>;
+};
+declare type SpecificationBuilderOptions = {
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    methodHooks: NotifyMethodHooks;
+};
+declare type Specification = ValidPermissionSpecification<{
+    permissionType: PermissionType.RestrictedMethod;
+    targetName: typeof methodName;
+    methodImplementation: ReturnType<typeof getImplementation>;
+    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+}>;
+/**
+ * The specification builder for the `snap_notify` permission.
+ * `snap_notify` allows snaps to send multiple types of notifications to its users.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_notify` permission.
+ */
+export declare const specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, SpecificationBuilderOptions, Specification>;
+export declare const notifyBuilder: Readonly<{
+    readonly targetName: "snap_notify";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, SpecificationBuilderOptions, {
+        permissionType: PermissionType.RestrictedMethod;
+        targetName: typeof methodName;
+        methodImplementation: ReturnType<typeof getImplementation>;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+    readonly methodHooks: MethodHooksObject<NotifyMethodHooks>;
+}>;
+/**
+ * Builds the method implementation for `snap_notify`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.showNativeNotification - A function that shows a native browser notification.
+ * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.
+ * @returns The method implementation which returns `null` on success.
+ * @throws If the params are invalid.
+ */
+export declare function getImplementation({ showNativeNotification, showInAppNotification, }: NotifyMethodHooks): (args: RestrictedMethodOptions<NotificationArgs>) => Promise<null>;
+/**
+ * Validates the notify method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @returns The validated method parameter object.
+ */
+export declare function getValidatedParams(params: unknown): NotificationArgs;
+export {};

package/dist/types/utils.d.ts

@@ -0,0 +1,94 @@
+import { SLIP10Node } from '@metamask/key-tree';
+import type { MagicValue } from '@metamask/snaps-utils';
+import type { Hex } from '@metamask/utils';
+/**
+ * Maps an interface with method hooks to an object, using the keys of the
+ * interface, and `true` as value. This ensures that the `methodHooks` object
+ * has the same values as the interface.
+ */
+export declare type MethodHooksObject<HooksType extends Record<string, unknown>> = {
+    [Key in keyof HooksType]: true;
+};
+/**
+ * Returns the subset of the specified `hooks` that are included in the
+ * `hookNames` object. This is a Principle of Least Authority (POLA) measure
+ * to ensure that each RPC method implementation only has access to the
+ * API "hooks" it needs to do its job.
+ *
+ * @param hooks - The hooks to select from.
+ * @param hookNames - The names of the hooks to select.
+ * @returns The selected hooks.
+ * @template Hooks - The hooks to select from.
+ * @template HookName - The names of the hooks to select.
+ */
+export declare function selectHooks<Hooks extends Record<string, unknown>, HookName extends keyof Hooks>(hooks: Hooks, hookNames?: Record<HookName, boolean>): Pick<Hooks, HookName> | undefined;
+declare type DeriveEntropyOptions = {
+    /**
+     * The input value to derive entropy from.
+     */
+    input: string;
+    /**
+     * An optional salt to use when deriving entropy.
+     */
+    salt?: string;
+    /**
+     * The mnemonic phrase to use for entropy derivation.
+     */
+    mnemonicPhrase: Uint8Array;
+    /**
+     * A hardened BIP-32 index, which is used to derive the root key from the
+     * mnemonic phrase.
+     */
+    magic: MagicValue;
+};
+/**
+ * Derive entropy from the given mnemonic phrase and salt.
+ *
+ * This is based on the reference implementation of
+ * [SIP-6](https://metamask.github.io/SIPs/SIPS/sip-6).
+ *
+ * @param options - The options for entropy derivation.
+ * @param options.input - The input value to derive entropy from.
+ * @param options.salt - An optional salt to use when deriving entropy.
+ * @param options.mnemonicPhrase - The mnemonic phrase to use for entropy
+ * derivation.
+ * @param options.magic - A hardened BIP-32 index, which is used to derive the
+ * root key from the mnemonic phrase.
+ * @returns The derived entropy.
+ */
+export declare function deriveEntropy({ input, salt, mnemonicPhrase, magic, }: DeriveEntropyOptions): Promise<Hex>;
+/**
+ * Get the path prefix to use for key derivation in `key-tree`. This assumes the
+ * following:
+ *
+ * - The Secp256k1 curve always use the BIP-32 specification.
+ * - The Ed25519 curve always use the SLIP-10 specification.
+ *
+ * While this does not matter in most situations (no known case at the time of
+ * writing), `key-tree` requires a specific specification to be used.
+ *
+ * @param curve - The curve to get the path prefix for. The curve is NOT
+ * validated by this function.
+ * @returns The path prefix, i.e., `secp256k1` or `ed25519`.
+ */
+export declare function getPathPrefix(curve: 'secp256k1' | 'ed25519'): 'bip32' | 'slip10';
+declare type GetNodeArgs = {
+    curve: 'secp256k1' | 'ed25519';
+    secretRecoveryPhrase: Uint8Array;
+    path: string[];
+};
+/**
+ * Get a `key-tree`-compatible node.
+ *
+ * Note: This function assumes that all the parameters have been validated
+ * beforehand.
+ *
+ * @param options - The derivation options.
+ * @param options.curve - The curve to use for derivation.
+ * @param options.secretRecoveryPhrase - The secret recovery phrase to use for
+ * derivation.
+ * @param options.path - The derivation path to use as array, starting with an
+ * "m" as the first item.
+ */
+export declare function getNode({ curve, secretRecoveryPhrase, path, }: GetNodeArgs): Promise<SLIP10Node>;
+export {};

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@metamask/snaps-rpc-methods",
+  "version": "3.1.0",
+  "description": "MetaMask Snaps JSON-RPC method implementations.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/snaps.git"
+  },
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist/cjs/**",
+    "dist/esm/**",
+    "dist/types/**"
+  ],
+  "scripts": {
+    "test": "jest && yarn posttest",
+    "posttest": "jest-it-up --margin 0.25",
+    "test:ci": "yarn test",
+    "lint:eslint": "eslint . --cache --ext js,ts,jsx,tsx",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern --loglevel warn \"**/*.json\" \"**/*.md\" \"**/*.html\" \"!CHANGELOG.md\" --ignore-path ../../.gitignore",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn lint:changelog && yarn lint:dependencies",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
+    "lint:changelog": "../../scripts/validate-changelog.sh @metamask/snaps-rpc-methods",
+    "build": "yarn build:source && yarn build:types",
+    "build:source": "yarn build:esm && yarn build:cjs",
+    "build:types": "tsc --project tsconfig.build.json",
+    "build:esm": "swc src --out-dir dist/esm --config-file ../../.swcrc.build.json --config module.type=es6",
+    "build:cjs": "swc src --out-dir dist/cjs --config-file ../../.swcrc.build.json --config module.type=commonjs",
+    "build:clean": "yarn clean && yarn build",
+    "clean": "rimraf '*.tsbuildinfo' 'dist'",
+    "publish:preview": "yarn npm publish --tag preview",
+    "lint:ci": "yarn lint",
+    "lint:dependencies": "depcheck"
+  },
+  "dependencies": {
+    "@metamask/key-tree": "^9.0.0",
+    "@metamask/permission-controller": "^5.0.0",
+    "@metamask/rpc-errors": "^6.1.0",
+    "@metamask/snaps-ui": "^3.0.1",
+    "@metamask/snaps-utils": "^3.1.0",
+    "@metamask/utils": "^8.1.0",
+    "@noble/hashes": "^1.3.1",
+    "superstruct": "^1.0.3"
+  },
+  "devDependencies": {
+    "@lavamoat/allow-scripts": "^2.5.1",
+    "@metamask/auto-changelog": "^3.3.0",
+    "@metamask/browser-passworder": "^4.1.0",
+    "@metamask/eslint-config": "^12.1.0",
+    "@metamask/eslint-config-jest": "^12.1.0",
+    "@metamask/eslint-config-nodejs": "^12.1.0",
+    "@metamask/eslint-config-typescript": "^12.1.0",
+    "@metamask/json-rpc-engine": "^7.1.1",
+    "@swc/cli": "^0.1.62",
+    "@swc/core": "1.3.78",
+    "@swc/jest": "^0.2.26",
+    "@types/node": "18.14.2",
+    "@typescript-eslint/eslint-plugin": "^5.42.1",
+    "@typescript-eslint/parser": "^5.42.1",
+    "deepmerge": "^4.2.2",
+    "depcheck": "^1.4.7",
+    "eslint": "^8.27.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jest": "^27.1.5",
+    "eslint-plugin-jsdoc": "^39.6.2",
+    "eslint-plugin-n": "^15.7.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-promise": "^6.1.1",
+    "expect-type": "^0.15.0",
+    "jest": "^29.0.2",
+    "jest-it-up": "^2.0.0",
+    "prettier": "^2.7.1",
+    "prettier-plugin-packagejson": "^2.2.11",
+    "rimraf": "^4.1.2",
+    "typescript": "~4.8.4"
+  },
+  "engines": {
+    "node": "^18.16 || >=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}