dfinity / dfinity/icskills

internet-identity skill: add Node.js/script guidance for root key handling

Open Beginner friendly
#164 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
35
Forks
13
Avg merge
19h 10m
Merged PRs (30d)
22

Description

Summary

The internet-identity skill's guidance on root key handling is incomplete. It correctly says to use safeGetCanisterEnv() and the ic_env cookie in browser contexts, but it doesn't address Node.js environments (test scripts, server-side code, CLI tools) where the cookie is unavailable. This causes agents to either:

  1. Apply the "never use fetchRootKey()" rule blindly to Node.js scripts, breaking local test setups, or
  2. Fall back to shouldFetchRootKey: true — the pattern the skill explicitly bans — because there's no documented alternative.

Current state (Pitfall 4)

Using shouldFetchRootKey or fetchRootKey() instead of the ic_env cookie. […] Never call fetchRootKey() — it fetches the root key from the replica at runtime, which lets a man-in-the-middle substitute a fake key on mainnet.

This is correct for browser code but the blanket "never" is misleading for Node.js.

Suggested changes

1. Clarify Pitfall #4 to scope the rule to browser/mainnet
4. **Using `shouldFetchRootKey` or `fetchRootKey()` in browser code or against mainnet.** In browser
   contexts (asset canister or Vite dev server), the `ic_env` cookie is available — pass
   `rootKey: canisterEnv?.IC_ROOT_KEY` from `safeGetCanisterEnv()` instead. This works in both
   local and production without environment branching. Never call `fetchRootKey()` against a mainnet
   endpoint — it fetches the root key at runtime, which lets a man-in-the-middle substitute a
   fake key.
2. Add a Node.js section

Add a short section (or note within the existing implementation section) covering the non-browser case:

### Node.js environments (scripts, tests, server-side code)

`safeGetCanisterEnv()` reads the `ic_env` cookie — it only works in browser contexts. In Node.js,
the cookie is unavailable. For scripts connecting to a **local** replica, call `fetchRootKey()`
explicitly after creating the agent:

\`\`\`javascript
import { HttpAgent } from "@icp-sdk/core/agent";

const agent = await HttpAgent.create({
  identity,
  host: "http://localhost:8000",
});

// Only for local replicas. Never call this against mainnet.
if (process.env.NODE_ENV !== "production") {
  await agent.fetchRootKey();
}
\`\`\`

On mainnet from Node.js, no root key fetching is needed — omit the call entirely. The root key
is pre-trusted and the agent verifies certificates against it automatically.

Why this matters

We discovered this gap while reviewing a docs page that had shouldFetchRootKey: true in its agent setup and cited the skill's "never use fetchRootKey" rule as justification — while simultaneously needing to support local test scripts. The distinction between browser and Node.js contexts makes both the rule and the workaround correct; the skill just needs to document both paths.

Related

The icp-cli skill's references/binding-generation.md may also reference the ic_env pattern — worth checking for consistency if this is updated.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the internet-identity skill and inspect Pitfall #4 plus the implementation guidance; then check references/binding-generation.md in the icp-cli skill for related ic_env wording. Update the documentation to distinguish browser, local Node.js, and mainnet behavior, and confirm the examples consistently explain when root-key fetching is permitted.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
documentation, security
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.