docs: Internet Identity spec reference

[marc0olo]

Summary

• Identity design: anchor model, principal-per-app isolation with derivation formula, multi-device setup
• Passkey management: WebAuthn registration/assertion, ECDSA P-256/Ed25519, OpenID login
• Client authentication protocol: step-by-step flow, delegation structure, session key lifecycle
• Delegation chain format: wire-level fields, IC verification algorithm
• Canister signatures: certified variables, public key OID and encoding
• Alternative frontend origins: .well-known/ii-alternative-origins protocol
• Protocol guarantees and non-guarantees

Sync recommendation

informed by dfinity/portal — docs/building-apps/authentication/internet-identity/; dfinity/icskills — skills/internet-identity/SKILL.md

[marc0olo]

Review: Internet Identity Specification

Must fix

• Inaccurate canister signature description (step 1): The page says "The II canister computes SHA-256(delegation_payload) and stores it in its certified variable tree at a path encoding the seed." This is incorrect. Per the IC interface specification (line 421), the canister stores an empty blob at path ["sig", SHA-256(seed), SHA-256(payload)]. The payload hash is part of the path, not the value stored — the verification checks lookup_path(["sig", <s>, <m>], tree) = Found "". Suggested fix: "The II canister stores an empty blob at path ["sig", SHA-256(seed), SHA-256(payload)] in its certified variable tree. This causes the certified data root hash to commit to both the seed and the payload."

• "Hostname" used where "origin" is correct: The page says "II uses the origin hostname as the seed input when computing the delegation." The II protocol uses the full frontend origin (scheme + host + port) as the derivation input, not just the hostname. Using "hostname" is imprecise and could mislead developers — https://app.example.com and http://app.example.com are different origins and produce different principals. The portal source uses "frontend origin" consistently throughout. Suggested fix: replace "the origin hostname" with "the frontend origin" in both occurrences in the Client authentication protocol section.

Suggestions

• Canister signature step 3 wording: The verification step says "The witness tree demonstrates the expected path value exists." This is vague and does not match the spec's actual check (see reconstruct(tree) and the lookup_path check). Consider: "The witness tree has a hash that matches the certified data value in the certificate, and contains the path ["sig", SHA-256(seed), SHA-256(payload)]."

• OpenID vs OpenID Connect consistency: The page says "II supports OpenID Connect providers (Google, Apple, Microsoft)" in the body but uses "OpenID login" as the section heading. Consider using "OpenID Connect (OIDC)" consistently throughout for precision.

• Key type table: Ed25519 claim: The table notes "Hardware security keys may use either depending on their firmware." Most FIDO2 hardware keys do not support Ed25519 (COSE algorithm -8) — ECDSA P-256 is the near-universal default. Consider softening to: "Some hardware security keys support Ed25519; ECDSA P-256 is more universally supported."

• Alternative origins code example — context gap: The code snippet in "Alternative frontend origins" shows bare authClient.login({...}) without import or initialization context. Adding a comment like // assumes authClient is initialized — see the Internet Identity guide would prevent confusion for readers who land on this section directly.

Verified

• Canister IDs: Both rdmx6-jaaaa-aaaaa-aaadq-cai (backend) and uqzsh-gqaaa-aaaaq-qaada-cai (frontend, https://id.ai) verified against .sources/icskills/skills/internet-identity/SKILL.md. Correct.
• Delegation expiry values: 8-hour default and 30-day maximum (2,592,000,000,000,000 ns) verified against icskills source and math-checked. Correct.
• Maximum delegation chain length: "20 delegations" verified against .sources/portal/docs/references/ic-interface-spec.md line 1123. Correct.
• Delegation wire format fields (sender_pubkey, sender_delegation, sender_sig): Verified against IC interface spec lines 1091–1121. Correct field names and descriptions.
• Canister signature OID: 1.3.6.1.4.1.56387.1.2 verified against IC interface spec line 395. Correct.
• Canister signature BIT STRING encoding: |signing_canister_id| · signing_canister_id · seed format verified against IC interface spec line 397. Correct.
• Principal derivation formula: SHA-224(DER-encoded_canister_signature_public_key) · 0x02 — SHA-224 confirmed as the hash function for self-authenticating principals in the IC spec (lines 158, 174). Correct.
• Alternative origins protocol: Max 10 entries, certified assets requirement, derivationOrigin usage all verified against .sources/portal/docs/building-apps/authentication/alternative-origins.mdx. Correct.
• Asset canister configuration: .ic-assets.json pattern with .well-known and ii-alternative-origins entries verified against portal source. Correct.
• icp0.io vs ic0.app handling: Page correctly notes II handles this automatically and no alternative origins are needed for that case. Consistent with icskill mistake docs: getting-started what-next page #7.
• Internal links: All three internal link targets verified — ../guides/authentication/internet-identity.md resolves to .mdx (acceptable per CLAUDE.md), system-canisters.md exists, ic-interface-spec.md exists.
• Content rules compliance: No dfx references, no mo:base imports, no banned internetcomputer.org/docs/ URLs, .md file extension used correctly throughout.
• Upstream comment: Present at end of file, lists relevant portal pages and icskills. Correct format.
• Content brief coverage: All five brief items covered — delegation chain structure, passkey management, canister signatures, alternative origins, session management. Full spec link present.

[marc0olo]

<!-- feedback-addressed -->

Feedback addressed: PR #91 — Internet Identity Specification

Changes applied

Must fix (both addressed):

1. Canister signature description corrected — The page previously said "The II canister computes SHA-256(delegation_payload) and stores it in its certified variable tree at a path encoding the seed." This is incorrect per IC interface spec line 418: lookup_path(["sig", <s>, <m>], tree) = Found "". Fixed to: "The II canister stores an empty blob at path ["sig", SHA-256(seed), SHA-256(payload)] in its certified variable tree. This causes the certified data root hash to commit to both the seed and the payload."

2. "Hostname" replaced with "frontend origin" — Line 79 used "the origin hostname" twice. The II protocol uses the full frontend origin (scheme + host + port) as the derivation input, not just the hostname. Replaced with "the frontend origin (scheme + host + port)" — important for correctness since https://app.example.com and http://app.example.com are different origins that produce different principals.

Suggestions (all applied):

3. Canister signature verification step clarified — Step 3's "The witness tree demonstrates the expected path value exists" was vague. Updated to: "The witness tree has a hash that matches the certified data value in the certificate, and contains the path ["sig", SHA-256(seed), SHA-256(payload)]." This aligns with the spec's actual reconstruct(tree) and lookup_path checks.

4. OpenID Connect (OIDC) terminology made consistent — Section heading was "OpenID login" while body used "OpenID Connect providers". Changed heading to "OpenID Connect (OIDC) login" and updated body text to use "OpenID Connect (OIDC)" consistently. Also updated the intro paragraph.

5. Ed25519 hardware key claim softened — "Hardware security keys may use either depending on their firmware" overstated Ed25519 support. Most FIDO2 hardware keys use ECDSA P-256 exclusively. Changed to: "Some hardware security keys support Ed25519; ECDSA P-256 is more universally supported."

6. Initialization context added to alternative origins code snippet — Added comment // assumes authClient is initialized — see the Internet Identity guide to the authClient.login({...}) snippet in the alternative origins section, preventing confusion for readers who land on that section directly.

Items skipped

None — all feedback items were factually correct and improve the page.

Build status

The npm run build fails on a pre-existing issue in docs/guides/backends/https-outcalls.mdx (missing .sources/examples submodule files — the examples and candid submodules did not initialize in this worktree due to SSH key restrictions). This error exists identically on the branch before and after my changes. The internet-identity-spec.md page itself has no build errors.