docs: list the exact certified_data_set contexts and scope the cookie root key

certified_data_set is allowed in init, upgrade hooks, updates, reply and reject
callbacks and system tasks, not in cleanup callbacks or any query. The ic_env
root key is only trustworthy on a verifying hostname.

Author: marc0olo

docs/guides/backends/certified-variables.md

@@ -40,7 +40,7 @@ CLIENT:
 ## Key constraints
 
 - `certified_data_set` accepts **at most 32 bytes**. You cannot certify arbitrary data directly. Build a Merkle tree over your data and certify only the 32-byte root hash. The tree provides proofs for individual values.
-- `certified_data_set` works in every replicated context (`init`, `post_upgrade`, update calls, reply and reject callbacks, timers, heartbeat) and **traps in a query call**.
+- `certified_data_set` can be called from `canister_init`, `canister_post_upgrade`, `canister_pre_upgrade`, update methods, reply and reject callbacks, and system tasks (`canister_heartbeat`, `canister_global_timer`, `canister_on_low_wasm_memory`). It **traps anywhere else**, including query methods (whether called as a query or as an update), composite queries and cleanup callbacks.
 - `data_certificate()` returns `None` in update calls, including a query method invoked as an update call. `icp canister call` sends an update call unless you pass `--query`, so always test certified getters with `icp canister call --query`.
 - Certified data survives upgrades (install and reinstall start it empty). A Merkle tree kept on the heap does not: in Rust, rebuild the tree in `#[post_upgrade]` and call `certified_data_set` again. A Motoko `CertTree.Store` persists with the actor, so nothing needs re-setting.
 

docs/guides/frontends/certification.md

@@ -273,7 +273,7 @@ export async function getVerifiedValue(
 
 Pass the root key of the network the canister runs on:
 
-- **Browser:** `safeGetCanisterEnv()?.IC_ROOT_KEY` from the `ic_env` cookie (`@icp-sdk/core/agent/canister-env`), which the frontend canister sets on local networks and mainnet alike. It is the key of the network serving the page.
+- **Browser:** `safeGetCanisterEnv()?.IC_ROOT_KEY` from the `ic_env` cookie (`@icp-sdk/core/agent/canister-env`), which the frontend canister sets on local networks and mainnet alike. It is the key of the network serving the page, and only as trustworthy as the page: on a verifying hostname the gateway verifies the cookie along with the page, but a page loaded from a `raw` hostname can carry a forged key. A client that verifies responses fetched from a `raw` hostname needs a root key obtained independently, such as the mainnet key built into `@icp-sdk/core`.
 - **Node scripts and tests:** the `root_key` field of `icp network status --json`, hex-decoded to bytes.
 - **Mainnet:** the agent's built-in default, `agent.rootKey` on an agent created without a `rootKey` option.