Skip to content

feat: seed Internet Identity identities on managed networks - #790

Draft
marc0olo wants to merge 6 commits into
mainfrom
feat/seed-ii-identities
Draft

marc0olo wants to merge 6 commits into
mainfrom
feat/seed-ii-identities

Conversation

@marc0olo

@marc0olo marc0olo commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Local Internet Identity loses all identities whenever the network state is lost, so developers have to create them again after every launcher or PocketIC upgrade.

With II enabled, icp network start now registers alice, bob and charlie with II and logs one line, Seeding Internet Identity with 3 identities. The per-identity details are logged at debug level.

  • New optional network setting ii-identities: a list replaces the defaults, [] turns it off.
  • Local II runs with dummy auth, where the frontend derives an Ed25519 key from the seed index. Each identity is registered with exactly that key, so "use existing passkey" plus the name's position in the list signs in. This works in a fresh browser too.
  • Every icp network start begins with a fresh network, so the identities are registered on each start. Registration is sequential, so the same names get the same identity numbers every time.
  • Keys live only in memory. Nothing is added to the user's identities.
  • Launcher-managed networks only: for image networks, icp-cli can't tell whether II is running.
  • Fix: nns networks now also get the id.ai friendly domain. nns installs II, but previously only ii added the route.

No launcher or PocketIC change is needed. A follow-up proposal to the II team would make the frontend list these identities by name, without the index prompt.

When Internet Identity is enabled, `icp network start` registers the
identities named by the new `ii-identities` network setting (default:
alice, bob, charlie) with the keys local II's dummy auth derives for
their seed index, and prints the index to sign in with for each.
Copilot AI balanced review requested due to automatic review settings September 24, 2026 11:45

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Seeding is skipped when Internet Identity is enabled implicitly through Bitcoin or Dogecoin integration.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 Medium severity · 1 Low severity

Open (2)
What changed in this PR

Adds deterministic Internet Identity seeding for launcher-managed local networks.

Changes:

  • Adds configurable ii-identities defaults and documentation.
  • Registers deterministic identities and reports their seed indexes.
  • Adds Candid interfaces and registration tests.
File Description
docs/​schemas/​network-yaml-schema.json Adds network schema field.
docs/​schemas/​icp-yaml-schema.json Adds project schema field.
docs/​reference/​configuration.md Documents configuration and login flow.
docs/​guides/​containerized-networks.md Clarifies image-network limitations.
docs/​concepts/​environments.md Lists the new setting.
crates/​icp-project/​src/​project.rs Updates generated configuration.
crates/​icp-project/​src/​network/​mod.rs Adds effective config and defaults.
crates/​icp-project/​src/​manifest/​project.rs Updates manifest tests.
crates/​icp-project/​src/​manifest/​network.rs Parses and tests the setting.
crates/​icp-project/​src/​lib.rs Updates mock configurations.
crates/​icp-cli/​tests/​network_tests.rs Tests fresh identity registration.
crates/​icp-canister-interfaces/​src/​internet_identity.rs Adds II Candid types.
crates/​icp-app/​src/​network/​managed/​run.rs Invokes identity seeding.
crates/​icp-app/​src/​network/​managed/​mod.rs Exposes the seeding module.
crates/​icp-app/​src/​network/​managed/​launcher.rs Excludes CLI-only configuration from launcher flags.
crates/​icp-app/​src/​network/​managed/​ii_identities.rs Implements deterministic registration and reporting.
crates/​icp-app/​src/​context/​tests.rs Updates test configurations.
CHANGELOG.md Announces the feature.
.claude/​architecture.md Documents network initialization responsibilities.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

bitcoind-addr and dogecoind-addr no longer imply Internet Identity in the
network launcher.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

NNS-only networks omit the friendly Internet Identity route despite seeding and reporting identities.

Review effort: Balanced
Findings: None

Resolved since last review (2)
Previously missed (1)

In code that hasn't changed since last review

Low severity Limit identity seeding release note to launcher-managed networks

CHANGELOG.md:11

This release note overstates the scope: Docker image networks are also managed networks, but the implementation deliberately skips identity seeding for ManagedMode::Image. Qualify the statement as launcher-managed so users of image networks are not promised unavailable behavior.

nns implies Internet Identity, but only ii put the id.ai entry in
custom-domains.txt, so the address printed for seeded identities did not
route on NNS-only networks.
@marc0olo

Copy link
Copy Markdown
Contributor Author

Addressed Copilot's second review in a28c7d7:

  • NNS networks: nns installs II, but only ii added the id.ai friendly domain, so the sign-in address printed on NNS-only networks didn't route (reproduced: HTTP 400). Seeding and the domain entry now share ManagedLauncherConfig::installs_ii(), and id.ai.localhost routes on NNS networks.
  • Changelog: the entry now says seeding applies to launcher-managed networks, not Docker image networks.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The fallback Internet Identity URL ignores configured gateway domains and can advertise an unroutable login endpoint.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Medium severity Preserve configured gateway domain when friendly aliases are unsupported

crates/​icp-app/​src/​network/​managed/​ii_identities.rs:159

When friendly-domain files are unsupported, this fallback ignores the configured gateway domain. For example, a network launched with gateway.domains: [my-app.localhost] only passes that domain to the launcher, but this reports and registers uqzsh-….localhost; that host is not one of the gateway's routing domains, while the usable standard URL is uqzsh-….my-app.localhost. Preserve gateway_domain(gateway_url) for principal-based routing when friendly aliases are unavailable.

The per-identity table grew with every name. Log a single line like the
balance seeding does, with the details at debug level. The registered
origin now keeps the gateway domain when friendly domains are unavailable.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The implementation, configuration behavior, documentation, and restart-safe registration path are consistently covered.

Review effort: Balanced
Findings: None

`icp network start` wipes the network state before every launch, so II is
always fresh when seeding runs and no identity can already be registered.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants