From 679d08cfe1ff5e6b031cdedbe47fb8cf1ab0a036 Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Thu, 5 Oct 2023 17:26:41 +0300 Subject: [PATCH 1/7] intercept-connctions-to-wallet Added Draft implementation of sip-13: Intercept connections to Wallet --- SIPS/sip-13 .md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 SIPS/sip-13 .md diff --git a/SIPS/sip-13 .md b/SIPS/sip-13 .md new file mode 100644 index 0000000..b33d084 --- /dev/null +++ b/SIPS/sip-13 .md @@ -0,0 +1,61 @@ +--- +sip: 13 +title: Intercept connections to Wallet +status: Draft +discussions-to: https://github.com/MetaMask/SIPs/discussions/109 +author: John Dickerson (@javaspeak) +created: 2023-10-05 +--- + +## Abstract + +This SIP proposes: a new way of intercepting a connection to the wallet so that the snap can make a call to an external API to check on the security of the domain the wallet is connecting to. The snap can then decide whether it wishes to warn or reassure the end user as to the trustworthiness of the connection they are are about to make. The end user can then decide whether they wish to continue with the connection or not. + +## Motivation + +In the crypto space a web domain may be malicious and drain the coins from the wallet of an unexpecting user. Adding a snap that is able to intercept a wallet connect; perform a check; and, inform the user if there are any security issues on the address, reduces the risk of wallet transactions on the web. UTU Trust (utu.io) builds trust in the crypto space and can provide this enhanced functionality to metamask in the form of this SIP and a snap which hits its API. + +## Specification + +> Formal specifications are written in Typescript. Usage of `CAIP-N` specifications, where `N` is a number, are references to [Chain Agnostic Improvement Proposals](https://github.com/ChainAgnostic/CAIPs). + +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and +"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Snap Manifest + +No new permissions. Will require the existing connection permission to make the ajax call to an external API. + +### Snap Implementation + +The following is an example implementation / usage of the API: + +```typescript +import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; + +export const onConnect: OnConnectHandler = async ({ + domain, address +} ) => { + let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(); + + if ( dangerType === 'danger' | dangerType === 'warn' ) { + + // The end user will be shown the message and dangerType (danger | warming | none) and also be + // asked the question: 'Do you wish to proceed and connect your wallet to the {domain}?' + let connect: boolean = showConnectWarning(message, dangerType ); + + // If the user clicked the 'No' button connect will be false, else true. + return connect; + } + + // connects without prompting user + return true; +}; +``` + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). From 55b64ea4f53226e39c1f3d9c44dbeb72e583e321 Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Thu, 5 Oct 2023 17:32:42 +0300 Subject: [PATCH 2/7] Renamed SIP --- SIPS/sip-13.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 SIPS/sip-13.md diff --git a/SIPS/sip-13.md b/SIPS/sip-13.md new file mode 100644 index 0000000..b33d084 --- /dev/null +++ b/SIPS/sip-13.md @@ -0,0 +1,61 @@ +--- +sip: 13 +title: Intercept connections to Wallet +status: Draft +discussions-to: https://github.com/MetaMask/SIPs/discussions/109 +author: John Dickerson (@javaspeak) +created: 2023-10-05 +--- + +## Abstract + +This SIP proposes: a new way of intercepting a connection to the wallet so that the snap can make a call to an external API to check on the security of the domain the wallet is connecting to. The snap can then decide whether it wishes to warn or reassure the end user as to the trustworthiness of the connection they are are about to make. The end user can then decide whether they wish to continue with the connection or not. + +## Motivation + +In the crypto space a web domain may be malicious and drain the coins from the wallet of an unexpecting user. Adding a snap that is able to intercept a wallet connect; perform a check; and, inform the user if there are any security issues on the address, reduces the risk of wallet transactions on the web. UTU Trust (utu.io) builds trust in the crypto space and can provide this enhanced functionality to metamask in the form of this SIP and a snap which hits its API. + +## Specification + +> Formal specifications are written in Typescript. Usage of `CAIP-N` specifications, where `N` is a number, are references to [Chain Agnostic Improvement Proposals](https://github.com/ChainAgnostic/CAIPs). + +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and +"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Snap Manifest + +No new permissions. Will require the existing connection permission to make the ajax call to an external API. + +### Snap Implementation + +The following is an example implementation / usage of the API: + +```typescript +import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; + +export const onConnect: OnConnectHandler = async ({ + domain, address +} ) => { + let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(); + + if ( dangerType === 'danger' | dangerType === 'warn' ) { + + // The end user will be shown the message and dangerType (danger | warming | none) and also be + // asked the question: 'Do you wish to proceed and connect your wallet to the {domain}?' + let connect: boolean = showConnectWarning(message, dangerType ); + + // If the user clicked the 'No' button connect will be false, else true. + return connect; + } + + // connects without prompting user + return true; +}; +``` + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). From e841c63b5fe1fdb197418e392d70c32060236e86 Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Fri, 6 Oct 2023 15:02:13 +0300 Subject: [PATCH 3/7] removed --- SIPS/sip-13 .md | 61 ------------------------------------------------- 1 file changed, 61 deletions(-) delete mode 100644 SIPS/sip-13 .md diff --git a/SIPS/sip-13 .md b/SIPS/sip-13 .md deleted file mode 100644 index b33d084..0000000 --- a/SIPS/sip-13 .md +++ /dev/null @@ -1,61 +0,0 @@ ---- -sip: 13 -title: Intercept connections to Wallet -status: Draft -discussions-to: https://github.com/MetaMask/SIPs/discussions/109 -author: John Dickerson (@javaspeak) -created: 2023-10-05 ---- - -## Abstract - -This SIP proposes: a new way of intercepting a connection to the wallet so that the snap can make a call to an external API to check on the security of the domain the wallet is connecting to. The snap can then decide whether it wishes to warn or reassure the end user as to the trustworthiness of the connection they are are about to make. The end user can then decide whether they wish to continue with the connection or not. - -## Motivation - -In the crypto space a web domain may be malicious and drain the coins from the wallet of an unexpecting user. Adding a snap that is able to intercept a wallet connect; perform a check; and, inform the user if there are any security issues on the address, reduces the risk of wallet transactions on the web. UTU Trust (utu.io) builds trust in the crypto space and can provide this enhanced functionality to metamask in the form of this SIP and a snap which hits its API. - -## Specification - -> Formal specifications are written in Typescript. Usage of `CAIP-N` specifications, where `N` is a number, are references to [Chain Agnostic Improvement Proposals](https://github.com/ChainAgnostic/CAIPs). - -### Language - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and -"OPTIONAL" written in uppercase in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) - -### Snap Manifest - -No new permissions. Will require the existing connection permission to make the ajax call to an external API. - -### Snap Implementation - -The following is an example implementation / usage of the API: - -```typescript -import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; - -export const onConnect: OnConnectHandler = async ({ - domain, address -} ) => { - let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(); - - if ( dangerType === 'danger' | dangerType === 'warn' ) { - - // The end user will be shown the message and dangerType (danger | warming | none) and also be - // asked the question: 'Do you wish to proceed and connect your wallet to the {domain}?' - let connect: boolean = showConnectWarning(message, dangerType ); - - // If the user clicked the 'No' button connect will be false, else true. - return connect; - } - - // connects without prompting user - return true; -}; -``` - -## Copyright - -Copyright and related rights waived via [CC0](../LICENSE). From a60a5b96604c90b63057c08c505e9f260224f420 Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Fri, 6 Oct 2023 15:22:43 +0300 Subject: [PATCH 4/7] intercept-connections-to-wallet Beefed up SIPP-13.md with some more explanations. --- SIPS/sip-13.md | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/SIPS/sip-13.md b/SIPS/sip-13.md index b33d084..6523c3e 100644 --- a/SIPS/sip-13.md +++ b/SIPS/sip-13.md @@ -39,13 +39,13 @@ import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; export const onConnect: OnConnectHandler = async ({ domain, address } ) => { - let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(); + let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(domain); if ( dangerType === 'danger' | dangerType === 'warn' ) { // The end user will be shown the message and dangerType (danger | warming | none) and also be // asked the question: 'Do you wish to proceed and connect your wallet to the {domain}?' - let connect: boolean = showConnectWarning(message, dangerType ); + let connect: boolean = showConnectMessage(message, dangerType ); // If the user clicked the 'No' button connect will be false, else true. return connect; @@ -56,6 +56,44 @@ export const onConnect: OnConnectHandler = async ({ }; ``` +Note that OnConnectHandler is a new Handler which is part of the same event mechanism used by +existing SNAP handlers like OnTransactionHandler, OnCronjobHandler, OnRpcRequestHandler. + +See: [Snaps exports](https://docs.metamask.io/snaps/reference/exports/) + +OnConnectHandler fires when the end user is attempting to connect the dApp to their wallet. + +In the above usage example, The hook can return true or false. It returns true if the connection +should be allowed to go ahead and false if the wallet should not connect to the dApp. + +There is a new function which needs to be added to the SNAP API called: + + showConnectMessage(message: string, dangerType: string): boolean + +This function takes in a message and dangerType. The message could be something like: + +"Domain gooooogle.com is a phishing website. Be Careful" + +dangerType can have the following values: danger | warning | none + +"danger" means the domain is a dangerous one and one should be very vigilant. +"warning" means the domain has had some issues so one should be careful. +"none" means the domain has no reported issues. + +Note that the implementation of showConnectMessage(..) MUST show the message and dangerType and also have a dialog with the additional text: + +"Do you wish to proceed and connect your wallet to the {domain}?'" + +This dialog has 2 buttons to respond with: + +Yes - means the user wishes to connect to their wallet +No - means the user does not wish to connect to their wallet + +The showConnectMessage() returns true to connect and false to not connect. + +Note that the ajaxCallToRemoteAPI(domain) function above is not part of the API and is an example +of integrating this functionality with the UTU Trust network. + ## Copyright Copyright and related rights waived via [CC0](../LICENSE). From 837c879c3ab3cac208234f4a44227120c82a31af Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Mon, 9 Oct 2023 11:30:10 +0300 Subject: [PATCH 5/7] intercept-connections-to-wallet Improved typing in the API --- SIPS/sip-13.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/SIPS/sip-13.md b/SIPS/sip-13.md index 6523c3e..ae39b5e 100644 --- a/SIPS/sip-13.md +++ b/SIPS/sip-13.md @@ -39,13 +39,13 @@ import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; export const onConnect: OnConnectHandler = async ({ domain, address } ) => { - let checkConnectionDetails: { message, dangerType } = ajaxCallToRemoteAPI(domain); + let checkConnectionDetails: { message: string, dangerType: string } = ajaxCallToRemoteAPI(domain); - if ( dangerType === 'danger' | dangerType === 'warn' ) { + if ( checkConnectionDetails.dangerType === 'danger' | checkConnectionDetails.dangerType === 'warn' ) { // The end user will be shown the message and dangerType (danger | warming | none) and also be // asked the question: 'Do you wish to proceed and connect your wallet to the {domain}?' - let connect: boolean = showConnectMessage(message, dangerType ); + let connect: boolean = showConnectMessage(checkConnectionDetails.message, checkConnectionDetails.dangerType ); // If the user clicked the 'No' button connect will be false, else true. return connect; From 28082eae4ce564326fac38261edd4e1b7dbe9d6c Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Mon, 9 Oct 2023 12:01:09 +0300 Subject: [PATCH 6/7] intercept-connections-to-wallet Added types to method signature --- SIPS/sip-13.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SIPS/sip-13.md b/SIPS/sip-13.md index ae39b5e..b87417b 100644 --- a/SIPS/sip-13.md +++ b/SIPS/sip-13.md @@ -37,7 +37,7 @@ The following is an example implementation / usage of the API: import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; export const onConnect: OnConnectHandler = async ({ - domain, address + domain: string, address: string } ) => { let checkConnectionDetails: { message: string, dangerType: string } = ajaxCallToRemoteAPI(domain); From ee5d6d0e4610a6627b4692ac696ed5dff983ac61 Mon Sep 17 00:00:00 2001 From: John Dickerson Date: Mon, 9 Oct 2023 12:22:10 +0300 Subject: [PATCH 7/7] intercept-connections-to-wallet Improved typing of method signature --- SIPS/sip-13.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SIPS/sip-13.md b/SIPS/sip-13.md index b87417b..bce723b 100644 --- a/SIPS/sip-13.md +++ b/SIPS/sip-13.md @@ -37,8 +37,8 @@ The following is an example implementation / usage of the API: import { OnConnectHandler, showConnectWarning } from "@metamask/snap-types"; export const onConnect: OnConnectHandler = async ({ - domain: string, address: string -} ) => { + domain, address +} ) : {domain: string, address: string} => { let checkConnectionDetails: { message: string, dangerType: string } = ajaxCallToRemoteAPI(domain); if ( checkConnectionDetails.dangerType === 'danger' | checkConnectionDetails.dangerType === 'warn' ) { @@ -72,7 +72,7 @@ There is a new function which needs to be added to the SNAP API called: This function takes in a message and dangerType. The message could be something like: -"Domain gooooogle.com is a phishing website. Be Careful" + "Domain gooooogle.com is a phishing website. Be Careful" dangerType can have the following values: danger | warning | none @@ -82,7 +82,7 @@ dangerType can have the following values: danger | warning | none Note that the implementation of showConnectMessage(..) MUST show the message and dangerType and also have a dialog with the additional text: -"Do you wish to proceed and connect your wallet to the {domain}?'" + "Do you wish to proceed and connect your wallet to the {domain}?'" This dialog has 2 buttons to respond with: