From a94c15498df9bfd25264926d1b8866da67d201fd Mon Sep 17 00:00:00 2001 From: Ziad Saab Date: Tue, 6 Feb 2024 10:28:18 -0500 Subject: [PATCH 1/3] Document unencrypted state Fixes MetaMask/metamask-planning#1629 --- snaps/index.mdx | 6 ++++++ snaps/reference/entry-points.md | 6 ++++++ snaps/reference/snaps-api.md | 4 ++++ 3 files changed, 16 insertions(+) diff --git a/snaps/index.mdx b/snaps/index.mdx index 4157a197bec..d915b5d6c73 100644 --- a/snaps/index.mdx +++ b/snaps/index.mdx @@ -42,6 +42,12 @@ The following Snaps features are available in the stable version of MetaMask: title: "Encrypted storage", description: "Securely store and manage data on the user's device." }, + { + icon: require("./assets/features/state.png").default, + href: "reference/snaps-api#snap_managestate", + title: "Unencrypted storage", + description: "Store non-sensitive data and access it while MetaMask is locked." + }, { icon: require("./assets/features/manage-keys.png").default, href: "how-to/manage-keys", diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md index 688fc9cb64c..acdf8724b1a 100644 --- a/snaps/reference/entry-points.md +++ b/snaps/reference/entry-points.md @@ -268,6 +268,12 @@ module.exports.onCronjob = async ({ request }) => { +#### Access data from cronjobs + +When accessing encrypted data from cronjobs using [`snap_manageState`](../reference/snaps-api.md#snap_managestate), MetaMask will require the user to enter their password if the wallet is locked. This interaction can be jarring, as the data access happens in the background without the user being aware. + +If your Snap's cronjob needs to access non-sensitive, public data, you should store that data in [unencrypted state](../reference/snaps-api.md#unencrypted-state) instead. This is done by passing `encrypted: false` to the `snap_manageState` methods, as shown in the reference. + ## onInstall To run an action on installation, a Snap must expose the `onInstall` entry point. diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md index f28088b8887..62fad81af3e 100644 --- a/snaps/reference/snaps-api.md +++ b/snaps/reference/snaps-api.md @@ -687,6 +687,10 @@ An object containing: - `operation` - The state operation to perform (`'clear'`, `'get'`, or `'update'`). - `newState` - The value to update state with if the operation is `update`, and nothing otherwise. +#### Unencrypted state + +- `encrypted` - Optional, defaults to `true`. If set to `false`, Snaps will use a separate storage section, and will not encrypt the data. This is useful to access that data from background operations without requiring the user to enter their password in the case that MetaMask is locked. + ### Returns The value stored in state if the operation is `get`, and `null` otherwise. From 2307603f60a0c34d96af46f1e699db0b62182323 Mon Sep 17 00:00:00 2001 From: Ziad Saab Date: Tue, 6 Feb 2024 11:16:41 -0500 Subject: [PATCH 2/3] improve wording on unencrypted state --- snaps/reference/entry-points.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md index acdf8724b1a..6ae1ff5ff2f 100644 --- a/snaps/reference/entry-points.md +++ b/snaps/reference/entry-points.md @@ -272,7 +272,7 @@ module.exports.onCronjob = async ({ request }) => { When accessing encrypted data from cronjobs using [`snap_manageState`](../reference/snaps-api.md#snap_managestate), MetaMask will require the user to enter their password if the wallet is locked. This interaction can be jarring, as the data access happens in the background without the user being aware. -If your Snap's cronjob needs to access non-sensitive, public data, you should store that data in [unencrypted state](../reference/snaps-api.md#unencrypted-state) instead. This is done by passing `encrypted: false` to the `snap_manageState` methods, as shown in the reference. +If your Snap's cronjob does not need to access sensitive data, you should store that data in [unencrypted state](../reference/snaps-api.md#unencrypted-state) instead. This is done by passing `encrypted: false` to the `snap_manageState` methods, as shown in the reference. ## onInstall From 02b3709cc307cc09c7d310c3fb89276f47027018 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Tue, 6 Feb 2024 12:37:46 -0800 Subject: [PATCH 3/3] edits --- snaps/reference/entry-points.md | 16 ++++++++++------ snaps/reference/snaps-api.md | 13 ++++++++----- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/snaps/reference/entry-points.md b/snaps/reference/entry-points.md index 6ae1ff5ff2f..94c934dd12e 100644 --- a/snaps/reference/entry-points.md +++ b/snaps/reference/entry-points.md @@ -216,6 +216,16 @@ For MetaMask to call the Snap's `onCronjob` method, you must request the [`endowment:cronjob`](permissions.md#endowmentcronjob) permission. ::: +:::info Access data from cron jobs +When accessing encrypted data from cron jobs using [`snap_manageState`](../reference/snaps-api.md#snap_managestate), +MetaMask requires the user to enter their password if the wallet is locked. +This interaction can be confusing to the user, since the Snap accesses the data in the background +without the user being aware. + +If your Snap's cron job does not need to access sensitive data, store that data in unencrypted state +by setting `encrypted` to `false` when using [`snap_manageState`](../reference/snaps-api.md#snap_managestate). +::: + #### Parameters An object containing an RPC request specified in the `endowment:cronjob` permission. @@ -268,12 +278,6 @@ module.exports.onCronjob = async ({ request }) => { -#### Access data from cronjobs - -When accessing encrypted data from cronjobs using [`snap_manageState`](../reference/snaps-api.md#snap_managestate), MetaMask will require the user to enter their password if the wallet is locked. This interaction can be jarring, as the data access happens in the background without the user being aware. - -If your Snap's cronjob does not need to access sensitive data, you should store that data in [unencrypted state](../reference/snaps-api.md#unencrypted-state) instead. This is done by passing `encrypted: false` to the `snap_manageState` methods, as shown in the reference. - ## onInstall To run an action on installation, a Snap must expose the `onInstall` entry point. diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md index 62fad81af3e..6dd9fc652b4 100644 --- a/snaps/reference/snaps-api.md +++ b/snaps/reference/snaps-api.md @@ -678,7 +678,9 @@ class MyKeyring implements Keyring { ## snap_manageState Allows the Snap to persist up to 100 MB of data to disk and retrieve it at will. -The data is automatically encrypted using a Snap-specific key and automatically decrypted when retrieved. +By default, the data is automatically encrypted using a Snap-specific key and automatically +decrypted when retrieved. +You can set `encrypted` to `false` to use unencrypted storage. ### Parameters @@ -686,10 +688,11 @@ An object containing: - `operation` - The state operation to perform (`'clear'`, `'get'`, or `'update'`). - `newState` - The value to update state with if the operation is `update`, and nothing otherwise. - -#### Unencrypted state - -- `encrypted` - Optional, defaults to `true`. If set to `false`, Snaps will use a separate storage section, and will not encrypt the data. This is useful to access that data from background operations without requiring the user to enter their password in the case that MetaMask is locked. +- `encrypted` (optional) - Indicates whether the Snap will encrypt the data. + The default is `true`. + If set to `false`, the Snap will use a separate storage section, and will not encrypt the data. + This is useful to access the data from background operations without requiring the user to enter + their password in the case that MetaMask is locked. ### Returns