docs: raise alternative origins limit to 100 - #349
Merged
Conversation
Internet Identity raised the cap on entries in `/.well-known/ii-alternative-origins` from 10 to 100 (dfinity/internet-identity#4261). Update the statement of the limit in the Internet Identity guide. The same limit appears three times in docs/references/internet-identity-spec.md, but that page is generated by scripts/sync-ii-spec.mjs from the pinned .sources/internetidentity submodule, so it is left alone here: it picks the new value up when that submodule is bumped and the sync is rerun.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Internet Identity guide to reflect the new 100-origin limit.
Changes:
- Raises the documented limit from 10 to 100.
- Leaves the linked generated specification inconsistent at 10.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ``` | ||
|
|
||
| A maximum of 10 alternative origins can be listed. No trailing slashes or paths. | ||
| A maximum of 100 alternative origins can be listed. No trailing slashes or paths. |
Contributor
Author
There was a problem hiding this comment.
Agreed on the inconsistency, and it is called out in the PR description. Not doing the bump here, for two reasons from this repo's own docs:
.agents/submodule-bumping.mdopens with "Only the project maintainer bumps submodule refs."- It is already automated for this submodule.
.github/workflows/sync-ii-spec.ymlruns weekly on Tuesdays at 09:00 UTC, resolves the latestrelease-YYYY-MM-DDtag, reruns the sync, updates.sources/VERSIONS, and opens its owninfra/sync-ii-spec-<tag>PR.
Concrete timing: the pin is at release-2026-08-07 (c78d1b99), and I confirmed release-2026-08-21 already carries the new value (MAX_ALTERNATIVE_ORIGINS = 100 in src/frontend/src/lib/utils/validateDerivationOrigin.ts). So the next scheduled run, tomorrow 2026-08-25, should open the bump PR and regenerate all three occurrences in docs/references/internet-identity-spec.md on its own.
If you want both landing together, the options are to hold this PR until that sync PR opens and merge them as a pair, or for a maintainer to trigger the workflow early via workflow_dispatch. Happy to do either, but the bump itself is not mine to make.
Generated by Claude Code
marc0olo
approved these changes
Aug 24, 2026
Contributor
Author
|
Please review before merging. Generated by Claude Code |
aterga
pushed a commit
that referenced
this pull request
Aug 24, 2026
main had already synced the II spec to release-2026-08-14 (#345), so .sources/VERSIONS conflicted on the internetidentity line. Resolved to release-2026-08-21 (4c934d1f), the newer pin, and reran npm run sync:ii-spec so the generated files come from that pin rather than from a text merge of two generated versions. main also merged #349, which raised the alternative origins limit in the guide; that line auto-merged and is unaffected by this branch.
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>
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
/.well-known/ii-alternative-originsfrom 10 to 100 (Increase maximum number of alternative origins to 100 internet-identity#4261, merged). This updates the docs to match.docs/guides/authentication/internet-identity.mdx: the alternative origins step said "A maximum of 10 alternative origins can be listed"; now 100.Scope
The limit also appears three times in
docs/references/internet-identity-spec.md(requirements list, the JSON schemamaxItems, and the "prevent misuse" note). That file is generated byscripts/sync-ii-spec.mjsfrom the pinned.sources/internetidentitysubmodule and carries a "do not edit directly" marker, so it is deliberately untouched here. The upstreamdocs/ii-spec.mdxalready has the new value, so the page picks it up when that submodule is bumped and the sync is rerun. Happy to do that in a separate PR if you would like it in the same release.No other page needed changing: the remaining "at most 10" hits in
docs/references/execution-errors.mdanddocs/references/ic-interface-spec/management-canister.mdare about canister controllers.Verification
npm run buildpasses (210 pages).docs/for the limit in every phrasing; only the generated spec page still says 10, for the reason above.