Document unencrypted state (#1124)

* Document unencrypted state Fixes MetaMask/MetaMask-planning#1629 * improve wording on unencrypted state * edits --------- Co-authored-by: Alexandra Tran <[email protected]>
MetaMask · Feb 14, 2024 · d0b1302 · d0b1302
1 parent f53ea78
commit d0b1302
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 1 deletion.
diff --git 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
@@ -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).
+:::
+
 If the cron job's logic requires access to encrypted state, you can use
 [`snap_getClientStatus`](../reference/snaps-api.md#snap_getclientstatus) to ensure that MetaMask is
 unlocked before accessing state.

diff --git a/snaps/reference/snaps-api.md b/snaps/reference/snaps-api.md
@@ -719,7 +719,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.
 
 :::note
 Accessing encrypted state requires MetaMask to be unlocked.
@@ -734,6 +736,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.
+- `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