Merge pull request #2300 from dfinity/add-fetchrootkey-info

Add caution regarding using `fetchRootKey` in agent-js on the mainnet

docs/developer-docs/agents/javascript-intro.md

@@ -163,6 +163,12 @@ In the `index.js` file, each of the previously explained pieces are pulled toget
 }
 ```
 
+:::caution
+This example uses `fetchRootKey`. It is not recommended that dapps deployed on the mainnet call this function from agent-js, since using `fetchRootKey` on the mainnet poses severe security concerns for the dapp that's making the call. It is recommended to put it behind a condition so that it only runs locally. 
+
+This API call will fetch a root key for verification of update calls from a single replica, so it’s possible for that replica to respond with a malicious key. A verified mainnet root key is already embedded into agent-js, so this only needs to be called on your local replica, which will have a different key from mainnet that agent-js does not know ahead of time.
+:::
+
 This constructor first creates a `HTTPAgent`, which is wraps the JS `fetch` API and uses it to encode calls through the public API. This code also optionally fetches the root key of the replica, for non-mainnet deployments. Finally, it creates an actor using the automatically generated interface for the canister will call, passing it the `canisterId` and the `HTTPAgent` that have been initialized.
 
 This `actor` instance is now set up to call all of the service methods as methods. Once this is all set up, you can simply run `dfx generate` whenever you make changes to your canister API, and the full interface will automatically stay in sync in your frontend code.

docs/developer-docs/frontend/index.md

@@ -89,6 +89,12 @@ export const createActor = (canisterId, options = {}) => {
 export const hello_frontend = createActor(canisterId);
 ```
 
+:::caution
+This example uses `fetchRootKey`. It is not recommended that dapps deployed on the mainnet call this function from agent-js, since using `fetchRootKey` on the mainnet poses severe security concerns for the dapp that's making the call. It is recommended to put it behind a condition so that it only runs locally. 
+
+This API call will fetch a root key for verification of update calls from a single replica, so it’s possible for that replica to respond with a malicious key. A verified mainnet root key is already embedded into agent-js, so this only needs to be called on your local replica, which will have a different key from mainnet that agent-js does not know ahead of time.
+:::
+
 Then, if you look at the `src/hello_frontend/src/index.js` file, you can see that it takes the generated actor, and uses it to make a call to the hello canister’s greet method:
 
 ```

docs/tutorials/developer-journey/level-2/2.5-unit-testing.md

@@ -250,6 +250,12 @@ This agent file does the following:
 
 - Creates a default actor. 
 
+:::caution
+This example uses `fetchRootKey`. It is not recommended that dapps deployed on the mainnet call this function from agent-js, since using `fetchRootKey` on the mainnet poses severe security concerns for the dapp that's making the call. It is recommended to put it behind a condition so that it only runs locally. 
+
+This API call will fetch a root key for verification of update calls from a single replica, so it’s possible for that replica to respond with a malicious key. A verified mainnet root key is already embedded into agent-js, so this only needs to be called on your local replica, which will have a different key from mainnet that agent-js does not know ahead of time.
+:::
+
 ### Creating a test file
 
 Now it's time to create our test file. Create a new file in `src/tests/` called `e2e_tests_backend.test.ts`, then insert the following content:

docs/tutorials/developer-journey/level-3/3.4-intro-to-agents.md

@@ -200,6 +200,12 @@ export const random_maze = createActor(canisterId);
 
 In this code, the constructor first creates an `HTTPAgent` which wraps the JavaScript API, then uses it to encode calls through the public API. If the deployment is on the mainnet, the root key of the replica is fetched. Then, an actor is created using the automatically generated Candid interface for the canister and is passed the canister ID and the `HTTPAgent`.
 
+:::caution
+This example uses `fetchRootKey`. It is not recommended that dapps deployed on the mainnet call this function from agent-js, since using `fetchRootKey` on the mainnet poses severe security concerns for the dapp that's making the call. It is recommended to put it behind a condition so that it only runs locally. 
+
+This API call will fetch a root key for verification of update calls from a single replica, so it’s possible for that replica to respond with a malicious key. A verified mainnet root key is already embedded into agent-js, so this only needs to be called on your local replica, which will have a different key from mainnet that agent-js does not know ahead of time.
+:::
+
 Now our actor is set up to call all of the defined service methods; in this instance, there is just the `generate` method. 
 
 Let's deploy our canisters with the command: