diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7fc6c1d3c83..a5042d13508 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,3 @@ -* @MetaMask/dev-ex @MetaMask/tech-writers +* @MetaMask/tech-writers /snaps/ @MetaMask/tech-writers @MetaMask/snaps -/wallet/ @MetaMask/tech-writers +/wallet/ @MetaMask/tech-writers @MetaMask/dev-ex diff --git a/docusaurus.config.js b/docusaurus.config.js index 3cba7cc6a1e..1c442b1ce4d 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -311,12 +311,12 @@ const config = { to: "/snaps/features/custom-evm-accounts/create-account-snap", }, { - from: "/snaps/concepts/design-guidelines", - to: "/snaps/how-to/design-a-snap", + from: ["/snaps/concepts/design-guidelines", "/snaps/how-to/design-a-snap"], + to: "/snaps/learn/best-practices/design-guidelines", }, { - from: "/snaps/concepts/security-guidelines", - to: "/snaps/how-to/secure-a-snap", + from: ["/snaps/concepts/security-guidelines", "/snaps/how-to/secure-a-snap"], + to: "/snaps/learn/best-practices/security-guidelines", }, { from: "/guide/snaps-permissions", diff --git a/snaps/how-to/communicate-errors.md b/snaps/how-to/communicate-errors.md index 653d9168bbe..1d861718344 100644 --- a/snaps/how-to/communicate-errors.md +++ b/snaps/how-to/communicate-errors.md @@ -1,5 +1,5 @@ --- -description: Communicate errors from your Snap without crashing it +description: Communicate errors from your Snap without crashing it. sidebar_position: 2 --- diff --git a/snaps/how-to/connect-to-a-snap.md b/snaps/how-to/connect-to-a-snap.md index 9f4164e39a4..d6ca78bca6c 100644 --- a/snaps/how-to/connect-to-a-snap.md +++ b/snaps/how-to/connect-to-a-snap.md @@ -1,6 +1,6 @@ --- description: Connect your dapp to existing, third-party Snaps. -sidebar_position: 9 +sidebar_position: 7 --- # Connect to a Snap diff --git a/snaps/how-to/debug-a-snap/index.md b/snaps/how-to/debug-a-snap/index.md index f26082aacc3..d14b120b31c 100644 --- a/snaps/how-to/debug-a-snap/index.md +++ b/snaps/how-to/debug-a-snap/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 5 --- # Debug a Snap diff --git a/snaps/how-to/publish-a-snap.md b/snaps/how-to/publish-a-snap.md index c5e50504718..beaecd6bd67 100644 --- a/snaps/how-to/publish-a-snap.md +++ b/snaps/how-to/publish-a-snap.md @@ -1,6 +1,6 @@ --- description: Develop, test, and publish a Snap. -sidebar_position: 8 +sidebar_position: 6 --- # Publish a Snap diff --git a/snaps/how-to/test-a-snap.md b/snaps/how-to/test-a-snap.md index fd798e29fe4..0d1740e6511 100644 --- a/snaps/how-to/test-a-snap.md +++ b/snaps/how-to/test-a-snap.md @@ -1,6 +1,6 @@ --- description: Use Jest for end-to-end Snap testing. -sidebar_position: 6 +sidebar_position: 4 --- # Test a Snap diff --git a/snaps/learn/best-practices/_category_.json b/snaps/learn/best-practices/_category_.json new file mode 100644 index 00000000000..81c88ab22c0 --- /dev/null +++ b/snaps/learn/best-practices/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Best practices", + "position": 3, + "link": { + "type": "generated-index", + "slug": "learn/best-practices" + } +} diff --git a/snaps/how-to/design-a-snap.md b/snaps/learn/best-practices/design-guidelines.md similarity index 96% rename from snaps/how-to/design-a-snap.md rename to snaps/learn/best-practices/design-guidelines.md index ef72d9329b3..0900272a35e 100644 --- a/snaps/how-to/design-a-snap.md +++ b/snaps/learn/best-practices/design-guidelines.md @@ -1,10 +1,10 @@ --- -description: Create accessible Snap installation flows. -sidebar_position: 4 +description: Learn about best practices for designing accessible Snap installation flows. +sidebar_position: 1 toc_max_heading_level: 2 --- -# Design a Snap installation flow +# Snaps design guidelines This page outlines guiding principles for designers, developers, builders, and writers to create Snap installation flows that are accessible to all users. @@ -67,7 +67,7 @@ Consider introducing your Snap in your companion dapp using a modal, tooltip, or This introduction should be impactful, clear, and direct, and can happen before or alongside the installation prompt. -![Introducing your Snap's features via a modal](../assets/install-modal.png) +![Introducing your Snap's features via a modal](../../assets/install-modal.png) Important details to include when introducing your Snap: @@ -95,7 +95,7 @@ Instead, **wait to prompt installation until a point when the Snap is required** In the following example, a key management Snap is suggested when the user is prompted to pick networks: -![Installation and connection to your Snap embedded in existing flows](../assets/picker.png) +![Installation and connection to your Snap embedded in existing flows](../../assets/picker.png) ## Optimize your metadata @@ -142,9 +142,9 @@ For example: The following images demonstrate how your Snap's avatar and name are displayed during installation, transaction insights, and custom dialogs: -![How your Snap's avatar and name are displayed during installation](../assets/install.png) -![How your Snap's name is displayed during transaction insights](../assets/insights.png) -![How your Snap's avatar and name are displayed during a custom dialog screen](../assets/dialog.png) +![How your Snap's avatar and name are displayed during installation](../../assets/install.png) +![How your Snap's name is displayed during transaction insights](../../assets/insights.png) +![How your Snap's avatar and name are displayed during a custom dialog screen](../../assets/dialog.png) ## Enhance your copy diff --git a/snaps/how-to/secure-a-snap.md b/snaps/learn/best-practices/security-guidelines.md similarity index 92% rename from snaps/how-to/secure-a-snap.md rename to snaps/learn/best-practices/security-guidelines.md index 56fc1ad3f55..74e79b5d5ec 100644 --- a/snaps/how-to/secure-a-snap.md +++ b/snaps/learn/best-practices/security-guidelines.md @@ -1,16 +1,16 @@ --- description: Learn about best practices for creating secure and reliable Snaps. -sidebar_position: 5 +sidebar_position: 2 --- -# Secure a Snap +# Snaps security guidelines This page outlines essential principles for builders to develop secure and reliable Snaps. Use these guidelines when creating your Snap to ensure it is safe for users. ## Manage permissions -The following are guidelines for [managing permissions](request-permissions.md) in the Snap manifest file. +The following are guidelines for [managing permissions](../../how-to/request-permissions.md) in the Snap manifest file. - **Minimum permissions** - Follow the principle of least authority by only adding the minimum permissions needed by your Snap in the manifest file. @@ -18,12 +18,12 @@ The following are guidelines for [managing permissions](request-permissions.md) You can validate your permissions using the [Snaps Simulator Manifest Validator](https://metamask.github.io/snaps/snaps-simulator/staging/#/manifest). -- **Minimum RPC access** - When adding the [`endowment:rpc`](../reference/permissions.md/#endowmentrpc) +- **Minimum RPC access** - When adding the [`endowment:rpc`](../../reference/permissions.md#endowmentrpc) permission for Snaps or dapps, ask yourself if both are necessary. For example, if permission is granted to communicate with Snaps, it means other Snaps can call your Snap's sensitive RPC methods. -- **Minimum network access** - Only add the [`endowment:network-access`](../reference/permissions.md/#endowmentnetwork-access) +- **Minimum network access** - Only add the [`endowment:network-access`](../../reference/permissions.md#endowmentnetwork-access) permission if it's absolutely necessary, such as when needing to communicate with a remote API that is part of your Snap's functionality. This to mitigate users' concern about sharing wallet usage to remote servers. @@ -66,7 +66,7 @@ The following are guidelines for user notifications and authorizations: use a companion dapp as an "admin interface" to interact with your Snap's sensitive methods. There are two ways to do this: - 1. Restrict the [`endowment:rpc`](../reference/permissions.md#endowmentrpc) permission to specific + 1. Restrict the [`endowment:rpc`](../../reference/permissions.md#endowmentrpc) permission to specific URLs using the `allowedOrigins` caveat. 2. Filter specific methods to specific URLs using the built-in [URL @@ -109,7 +109,7 @@ user IPs, emails, passwords, and private keys: - **Private keys** - Avoid retrieving the user's private key from the Snap unless absolutely necessary, such as to sign a transaction. - If you only need the user's public key, use [`snap_getBip32PublicKey`](../reference/snaps-api.md#snap_getbip32publickey) + If you only need the user's public key, use [`snap_getBip32PublicKey`](../../reference/snaps-api.md#snap_getbip32publickey) instead of deriving it from the private key. Never return the private key in an RPC method to a dapp or another Snap. To give users a way to view their private key, display it in a dialog. @@ -142,19 +142,19 @@ The following are guidelines for validating RPC parameters and handling values: confirmation flow. - **Use `copyable` for safe disclosures** - When displaying arbitrary content in a Snap dialog, such - as for signing a message, use the [`copyable`](../features/custom-ui.md/#copyable) user + as for signing a message, use the [`copyable`](../../features/custom-ui.md#copyable) user interface component instead of `text`. When using dialogs, the input may contain special characters that render as Markdown and can mislead the user. For example: - ![Example not using copyable with Markdown rendering](../assets/copyable-example-1.png) + ![Example not using copyable with Markdown rendering](../../assets/copyable-example-1.png) The special characters `*` and `_` render Markdown formatting, so what the user sees does not match the content. To avoid this, use `copyable` instead: - ![Example using copyable with clean rendering](../assets/copyable-example-2.png) + ![Example using copyable with clean rendering](../../assets/copyable-example-2.png) `copyable` does not render Markdown and has the added benefit that the user can select to copy the content. Also, the formatting provides a visual delineator to separate arbitrary input or fields from user @@ -177,7 +177,7 @@ Avoid using the following deprecated methods: - `wallet_enable`, which is deprecated in favor of [`wallet_requestSnaps`](/wallet/reference/wallet_requestsnaps). -- `snap_confirm`, which is deprecated in favor of [`snap_dialog`](../reference/snaps-api.md#snap_dialog). +- `snap_confirm`, which is deprecated in favor of [`snap_dialog`](../../reference/snaps-api.md#snap_dialog). - `endowment:long-running`, which is deprecated for MetaMask stable but still allowed in MetaMask Flask. @@ -187,7 +187,7 @@ The following are coding security tips and warnings: - **SES compatibility** - Use packages or libraries compatible with SES (hardened JavaScript). If you don't, you might encounter errors that require [patching a specific - dependency](debug-a-snap/common-issues.md/#patch-dependencies) to fix. + dependency](../../how-to/debug-a-snap/common-issues.md#patch-dependencies) to fix. - **Timers and side-channel attacks** - Certain JavaScript features such as timers (for example, `Date.now`) can expose critical system information, making a user vulnerable to @@ -200,7 +200,7 @@ The following are coding security tips and warnings: Do not use insufficient hashing algorithms such as `md5` or `sha2`. Do not roll your own cryptography or use custom or unproven cryptography methods or libraries. - We recommend using [`snap_getEntropy`](../reference/snaps-api.md/#snap_getentropy) for entropy, the + We recommend using [`snap_getEntropy`](../../reference/snaps-api.md#snap_getentropy) for entropy, the built-in [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) or [Noble cryptography libraries](https://paulmillr.com/noble/), and safe hashing algorithms such as `sha256`. Choose audited, widely used libraries over obscure, untested implementations. diff --git a/src/components/SnapsSection.tsx b/src/components/SnapsSection.tsx index 6cff9906830..003accc89dd 100644 --- a/src/components/SnapsSection.tsx +++ b/src/components/SnapsSection.tsx @@ -12,7 +12,7 @@ const CardList: CardItem[] = [ }, { title: "⚙️ Snaps tutorials", - link: "/snaps/tutorials", + link: "/snaps/learn/tutorials", description: (<> Follow the step-by-step tutorials to create Snaps that estimate gas fees, provide transaction insights with custom UI, and more.