Repository navigation
docs(authentication): notifying a user through Internet Identity - #438
Merged
Merged
Conversation
… caution correctly
…e funnel in the campaign
…onger one is allowed
lwshang
approved these changes
Nov 6, 2026
sea-snake
added a commit
to dfinity/icskills
that referenced
this pull request
Nov 6, 2026
## Summary The Internet Identity skill was 424 lines plus six files in `references/`, covering five jobs that are loaded at different times by different people. It becomes five skills, each a single `SKILL.md`: | Skill | What it is for | |---|---| | `internet-identity` | Sign-in, the client lifecycle, local development, and the primary origin an app's principals are permanently tied to | | `internet-identity-shared-sessions` | One sign-in across sibling subdomains | | `internet-identity-attributes` | A verified email or display name in the backend, Motoko and Rust | | `internet-identity-notifications` | Web push from a canister while the app is closed | | `internet-identity-sso` | The organization's own single sign-on, an IT admin's job | `references/` is gone. Every reference file is absorbed into the body of the skill that owns it, so each skill reads end to end in one file and the Rust/Motoko asymmetry in attributes (Motoko inline, Rust one hop away) disappears. ## Routing No new frontmatter field: routing is the `description` plus backticked skill names in prose, which is what the repo already does. Each leaf skill opens with a one-line prerequisite pointing at `internet-identity`; `internet-identity` closes with the four follow-ups. Nothing outside the suite links to attributes, notifications or SSO, so those three cut cleanly. Origins do have inbound links, which is why they stay in core. ## Content changes beyond moving text - **Mistake 9 was wrong and is replaced.** It claimed that setting `derivationOrigin` to the gateway domain breaks authentication. It does not: `validateDerivationOrigin.ts:31-37` compares the two origins in canonical form and returns valid before any fetch, so it is a no-op. The real mistake, letting the first origin with users be one you can lose, takes its place. - **Derivation origins are reframed around the canister id** and moved after sign-in works rather than before it. The default, setting nothing, is already correct, so the section teaches a decision instead of a configuration. - **`ii-derivation-origin` is documented here for the first time.** It appeared only in `service-discoverability`. Both directions of the relation are now described together with who reads each. - **`shared-sessions.md` built its client with `derivationOrigin: \"https://auth.example.com\"`**, a custom domain, which is the one thing the origins section advises against. Corrected to the canister address. - **`app-metadata.md`'s opening was a heading and a sentence spliced together** by a bad edit. Repaired. - **Notifications gains** the parallel sign-in and consent pattern, a notifications toggle, the composed notification title (II shows the app's name then the title the canister sent, falling back to the origin's hostname), and the per-browser fan-out, informed by dfinity/developer-docs#438. - **Implementation details of our own libraries are out.** A skill documents the public API, the documented errors and observable behaviour; where an internal fact has a consequence, the consequence is written instead of the mechanism. ## Verified - `node scripts/check-project.js` passes for 39 skills. The two warnings are pre-existing (`autosync-ic-skills`, `sns-launch` have no eval files); all five skills here do. - Every code fence carries the language the original source used, checked block by block against the files being replaced. - No em dashes and no banned vocabulary in any of the five. - The two claims in the rewrite come from reading `dfinity/internet-identity` at `origin/main`, not from the existing docs: the derivation-origin no-op from `validateDerivationOrigin.ts`, and what the sign-in header shows from `AuthorizeHeader.svelte`. The notification title composition and the per-browser queue come from the service worker's wake-up path and the canister's notifications module. ## Evaluations Existing cases follow the skill that now owns them: 6 attribute cases, 4 shared-session cases and 3 notification cases move out of `evaluations/internet-identity.json`, which keeps 22. `internet-identity-sso` had no cases, since the three SSO cases in the old suite all test the app-side `ssoDomain` check that stays in core, so it gets three new adversarial ones for the discovery file: whole-file rejection on one bad value, exact-origin `app_clients` keys, and `stable_identifier_claim` on Entra ID. Trigger evals are rewritten per skill, with each sibling's queries as negatives. Eval runs are in progress and will be posted as a comment on this PR. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
guides/authentication/notifications.mdx: asking a user for permission to notify them through Internet Identity, naming the sending canister at/.well-known/ii-notification-senders, and sending from a Motoko or Rust canister.app-metadata.mdboth ways. The notification's title is the app'snamefollowed by the title the canister sent, falling back to the origin's hostname, and thelogois the icon, so that document brands notifications and not just the sign-in screen.Structural decisions
sidebar.order: 8, appended rather than slotted mid-list, so no existing page is renumbered. The section reads as "set up sign-in, then get more from it", and reaching a user after they have left belongs at the end of that..mdxrather than.mdfor the Motoko and Rust tabs, in that order.sendcall and links to the crate and the Mops package forendpoints!,init, and the fullNotificationtype, rather than reproducing the library's README.Verified
npm run buildpasses..mdextension; both targets checked withls.dfinity/identity-notificationsatmainand the Internet Identity source, not from memory: the title composition and hostname fallback are from the service worker's wake-up path, and the sender list limits and cache windows from the senders cache.