chore: sync II spec to dfinity/internet-identity release-2026-08-21 - #350
Merged
Conversation
marc0olo
approved these changes
Aug 24, 2026
aterga
pushed a commit
that referenced
this pull request
Aug 24, 2026
main now mirrors the App metadata section (#350 synced .sources/internetidentity to release-2026-08-21), so the guide can point at #app-metadata instead of the specification page root. This commit originally carried the submodule bump and the regenerated spec files. The rebase dropped them: #350 landed the identical sync first, so only the anchor change remains.
marc0olo
pushed a commit
that referenced
this pull request
Aug 24, 2026
## Summary - Adds an **App metadata** section to `docs/guides/authentication/internet-identity.mdx`, between *Alternative origins* and *Common mistakes*, covering the `/.well-known/ii-app-metadata` document that lets an app supply its own name, description, and logo for the Internet Identity sign-in screens. Nothing in the guide covered it: until now the only way to get branded screens was to be in the curated list shipped inside II, which this mechanism replaces. - Placement is deliberate. The section reuses the derivation origin the reader has just configured in *Alternative origins* (the document is fetched from the origin identities are derived for, so an app publishes it once and all of its alternative origins present the same way), and it extends the same `.ic-assets.json5` with CORS entries for the document and the logo. - Content covers what an integrator has to get right: the field limits (40 / 120 code points), the raster-only logo rules (same origin, no SVG, 1 MiB, 4096 px per side, re-encoded by II at up to 512 px), the 8 KiB document cap, `200` with no redirect, and the 10 second budget. It also states that a single invalid field drops the whole document and that II names the offending field in the browser console, since that is the first thing someone debugging missing metadata needs to know. - Ends with a note that the metadata is exactly as trustworthy as the origin serving it and verifies nothing about the app, which is why II keeps the origin on screen next to it. - Links the specification by anchor (`#app-metadata`) rather than at the page root. ## Scope This PR is now a documentation change only: `docs/guides/authentication/internet-identity.mdx`, +56 / -1. Earlier revisions of this branch also carried a bump of `.sources/internetidentity` to `release-2026-08-21` and the regenerated spec files, because the mirrored specification did not yet have the section this guide links to. #350 has since landed the identical sync on main, so rebasing dropped those changes as already applied. The anchor works against main as it stands. `docs/references/internet-identity-spec.md` on main now carries the App metadata section and its JSON Schema, and states the alternative origins limit as 100 (upstream dfinity/internet-identity#4221 and #4261, both in `release-2026-08-21`). ## Relationship to #349 #349 (merged) raised the same limit in the guide prose, on line 572. This branch inserts a section further down, so the two do not overlap. With #350 also merged, the guide and the specification now agree on 100. ## Structural decisions - **Heading level.** Added as an `##` section so it sits as a sibling of *Alternative origins* and *Common mistakes* rather than nesting under either. The mechanism is independent of alternative origins: apps that never set a `derivationOrigin` use it too. ## Verification - Rebased onto main (`b21a283`); the branch is two commits and merges cleanly. - `npm run build` passes from a clean `dist/` (exit 0, 210 pages), and the built `dist/references/internet-identity-spec/index.html` contains `id="app-metadata"`, so the guide's anchor resolves against main's mirrored spec. - `node scripts/validate.js --all`: no errors in the changed file. The 4 reported errors are pre-existing, in `docs/guides/digital-assets/chain-key-tokens.mdx` and `docs/guides/backends/data-persistence.mdx`, both untouched here. - Limits and behaviour in the guide text were taken from the merged implementation (`src/frontend/src/lib/utils/appMetadata.ts` in dfinity/internet-identity), not from memory, and match the mirrored spec section now on main. - The `:::note` in the new section renders as a plain `div` rather than a styled callout. So does the page's pre-existing note under *Alternative origins*: the built page contains no `starlight-aside` elements at all, so this is existing site behaviour and not something this change introduces. Left as is to match the page; happy to open a separate issue if the directive handling should be fixed. --------- Co-authored-by: Claude <noreply@anthropic.com>
2 tasks
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
1 participant
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
Automated sync of the Internet Identity specification from
dfinity/internet-identity.Release:
release-2026-08-21(pinned from21ab317→4c934d1f)Changed upstream files:
docs/ii-spec.mdxRan
npm run sync:ii-spec— regenerateddocs/references/internet-identity-spec.mdanddocs/references/verifiable-credentials-spec.mdBuild passed ✓
Checklist
docs/references/internet-identity-spec.mdfor content changesdocs/references/verifiable-credentials-spec.mdfor content changesinternetcomputer.orglink patterns (script exits non-zero if any were missed)Sync recommendation
sync from dfinity/internet-identity — docs/ii-spec.mdx, docs/vc-spec.md, src/internet_identity/internet_identity.did