internet-identity skill: add Node.js/script guidance for root key handling
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:
- Apply the "never use
fetchRootKey()" rule blindly to Node.js scripts, breaking local test setups, or - Fall back to
shouldFetchRootKey: true— the pattern the skill explicitly bans — because there's no documented alternative.
Current state (Pitfall 4)
Using
shouldFetchRootKeyorfetchRootKey()instead of theic_envcookie. […] Never callfetchRootKey()— 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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