feat(fe): permissionless app metadata for the authorize flow

[aterga]

Motivation

The app name, description and logo shown on the authorize-flow screens ("Continue to App", the sign-in header, the redirect animation, the CLI header) are currently sourced from a curated dapps.json list shipped inside II itself. Apps not on that list fall back to a bare hostname, and getting on the list requires a change to this repository. This PR replaces that with a permissionless mechanism: any app can provide its own display metadata, with no client-library changes and no involvement from the II team.

Changes

• New well-known resource: apps serve /.well-known/ii-app-metadata (JSON with optional name, description, logo) on their own origin, mirroring the existing /.well-known/ii-alternative-origins pattern. Works for any web origin, not just ICP canisters, since the file has no principal-derivation security semantics.
• Fetched from the origin the identity is derived for — the validated derivationOrigin when the authorization request carries one, the requesting origin otherwise. An app publishes once, on the origin its principals and its II accounts are bound to, and every alternative frontend origin it has certified as its own presents identically, with nothing to keep in sync. The screens keep displaying the origin the user signed in from as the trust anchor: where the two differ, the metadata's origin has listed the displayed one in its certified alternative-origins document, so no origin can present itself using metadata of an origin that hasn't vouched for it.
• $lib/utils/appMetadata.ts fetches and validates the document. Hardened like the alternative-origins fetch (no credentials, no redirects, 10 s budget spanning connection and body) plus:
  • All-or-nothing validation. A field that is present but doesn't meet the requirements rejects the whole document rather than being dropped on its own, and the reason is logged naming the field — a half-applied file looks like a working integration while quietly missing a name or logo on a screen the app can't inspect.
  • name ≤ 40 and description ≤ 120 Unicode code points, measured on the value as served, so the published JSON Schema is exactly what II enforces. Characters that can reorder text are refused (control characters, the bidi embeddings and overrides U+202A–U+202E, U+FEFF); the bidi marks U+200E/U+200F/U+061C, the isolates U+2066–U+2069 and the zero-width characters U+200B–U+200D are accepted, since mixed-direction and non-Latin names need them (RTL text ending in punctuation, Thai/Khmer line-break opportunities, Persian shaping, emoji sequences). Isolates must be balanced, so an app's string can never run past itself into II's own text, and a field must contain at least one visible character. Whitespace normalization is presentation only, applied after validation.
  • logo must resolve to the same origin as the document (which also rules out data:/javascript: schemes and keeps the sign-in private from third parties), be a raster image of an allowed content type, at most 1 MiB and 4096 px per axis.
  • The logo is never rendered as served. The response streams through a counting transform into a Blob (so the payload stays in the browser's blob store, never a JS buffer), is decoded with createImageBitmap — so Content-Type is a claim that gets checked, not trusted — then drawn once into a canvas, re-encoded at ≤ 512 px on its longest side and handed to the <img> as a blob: URL. What renders is a still image II produced itself; img-src gains blob: accordingly. image/svg+xml is not accepted, because a vector image can't go through that step across the browsers this repo supports.
  • Every failure mode (missing file, CORS, timeout, invalid JSON, undecodable logo, …) yields undefined instead of an error, so metadata can never break sign-in. Failures of the logo asset cost only the logo, since a second network request can fail transiently.
  • The document itself is capped at 8 KiB.
• $lib/stores/app-metadata.store.ts: per-origin cached store. Resolves synchronously to the curated-list entry (so known dapps never flash an unbranded screen) and updates in place once the fetched document validates; a valid document replaces the curated entry wholesale (the app owns its presentation). The curated fallback is matched against the displayed origin as well as the derivation origin, since a curated entry names the origins an app signs in from and needn't include the one it derives from. It is a fallback only, never a metadata source, and can be removed once major dapps have migrated.
• UI wiring: AuthorizeHeader (which now also renders the app-provided description, with dir="auto" so its direction comes from its own content and stays isolated from the screen), AuthWizardView, ContinueView, RedirectAnimationView, the upgrade panel in authorize/+page.svelte, and CliHeader all read the store instead of getDapps(). The origin badge stays visible everywhere the metadata is shown, and keeps any scheme or port that distinguishes one origin from another (originLabel).
• Spec: new "App metadata" section in docs/ii-spec.mdx with the requirements, a JSON Schema that mirrors them (noting the one rule it can't express, isolate balance), CORS requirements and security considerations.

Not changed: the certified-attributes opt-in gate in channelHandlers/attributes.ts (a security decision, not display metadata), the legacy VC flow, and the dapps-explorer/manage screens, which still use the curated list.

Also note: no lingui message IDs were added or changed, so the translation catalogs are untouched.

Tests

• New unit tests: appMetadata.test.ts (37 cases — hardened fetch options, byte caps enforced up front and while streaming, per-field validation and whole-document rejection, the bidi rules in both directions, same-origin logo enforcement including protocol-relative and scheme-downgrade attempts, content-type allowlist, decode failure, dimension cap, downscaling, timeout via fake timers) and app-metadata.store.test.ts (9 cases — fallback behaviour, wholesale replacement, per-origin caching, derivation-vs-displayed origin, subscriber updates), plus originLabel cases in urlUtils.test.ts. 60 tests across the three files.
• The published JSON Schema was validated against the documented behaviour (accepted and rejected samples, including RTL, Thai and emoji names).
• npm run check (tsc + svelte-check): 0 errors, warnings unchanged from main. npm run lint:eslint, npm run format-check and cargo fmt --check: clean.
• npm test: the new tests pass; the only failures in the full suite (iiConnection.test.ts, findWebAuthnFlows.test.ts, chrome-extension spec) are pre-existing in this environment and reproduce identically on main without this change.
• Existing playwright e2e assertions (e.g. "My Test Dapp account") remain valid via the curated-list fallback: the metadata fetch 404s against the test app and falls back exactly as before.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ApQTUxtZxjzpFsoJqKCXxo

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds permissionless application metadata to authorization flows while retaining curated metadata as fallback.

Changes:

• Fetches, validates, and caches app-provided names, descriptions, and logos.
• Integrates metadata across authorization and CLI interfaces.
• Documents the metadata specification and adds unit tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
CliHeader.svelte	Uses cached app metadata in CLI authorization.
RedirectAnimationView.svelte	Displays app-provided logos during redirect.
ContinueView.svelte	Uses app-provided names.
AuthWizardView.svelte	Uses metadata in sign-in messaging.
authorize/+page.svelte	Uses metadata in the upgrade panel.
appMetadata.ts	Fetches and validates metadata and logos.
appMetadata.test.ts	Tests metadata validation and fetching.
app-metadata.store.ts	Adds per-origin metadata caching and fallback.
app-metadata.store.test.ts	Tests store caching and updates.
AuthorizeHeader.svelte	Displays metadata and descriptions.
ii-spec.mdx	Documents the metadata resource and schema.

---

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

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/frontend/src/lib/utils/appMetadata.ts:158

• Both early-return branches clear the abort timer without cancelling the response body. A hostile origin can therefore send an unbounded non-200 response, or claim an oversized Content-Length, and keep downloading after this function returns, bypassing the documented hard cap. Cancel the stream before returning.

    if (response.status !== 200) {
      return undefined;
    }
    const declaredLength = response.headers.get("content-length");
    if (declaredLength !== null && Number(declaredLength) > maxBytes) {

src/frontend/src/lib/stores/app-metadata.store.ts:38

• This parameter documentation excludes derivation origins, but AttributeConsentView intentionally calls this store through AuthorizeHeader with its displayed, validated effectiveOrigin. That also contradicts the new spec’s displayed-origin rule. Describe the displayed origin rather than requiring the channel origin.

 * @param origin Origin as shown to the user (e.g. the postMessage channel
 *   origin), not the derivation origin (which may be remapped).

docs/ii-spec.mdx:352

• The spec says the exact origin is displayed, but the wired components render new URL(origin).hostname (for example, AuthorizeHeader.svelte:14), which omits the scheme and port even though those distinguish origins. Either display the full origin or describe the actual hostname badge so the security guarantee is accurate.

Internet Identity fetches this document when the authorization flow starts, always from the same origin it displays to the user alongside the metadata — for the authorization screens this is the origin of the client application (`event.origin` of the authorization request); screens that display a validated `derivationOrigin` instead fetch the document from that displayed origin. When the document is missing or invalid, Internet Identity falls back to the curated metadata it ships for a small list of known applications (a transitional mechanism that this document supersedes), and otherwise to displaying the origin's hostname only.

Since the file is under the sole control of the application origin, the metadata is exactly as trustworthy as that origin itself: it does not certify or verify the application's identity in any way. Internet Identity therefore always displays the application's origin alongside this metadata, as the value users can actually verify.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/frontend/src/lib/utils/appMetadata.ts:281

• TextDecoder uses replacement mode by default, so malformed UTF-8 is silently converted to U+FFFD and may be accepted as valid JSON metadata. JSON exchanged between systems must be UTF-8; use fatal decoding so invalid byte sequences follow the documented malformed-file fallback.

    const parsed: unknown = JSON.parse(new TextDecoder().decode(result.body));

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/frontend/src/routes/(new-styling)/authorize/views/ContinueView.svelte:190

• This asynchronously fetched value also makes the account-edit baseline mutable. If metadata resolves while an unnamed account's dialog is open, EditAccount keeps its initial local name but its reactive account prop changes, so the untouched form becomes “changed”; submitting or toggling the default then persists the stale fallback as an explicit account name. Snapshot the fallback used when opening the dialog, or compare against that original value rather than the live metadata-derived value.

  const application = $derived($metadataStore.name);

src/frontend/src/routes/(new-styling)/authorize/views/ContinueView.svelte:190

• A valid permissionless name can make account editing invalid: metadata allows 40 code points, but this value is expanded into My ${application} account, passed to EditAccount for unnamed accounts, and that form rejects names over 32 UTF-16 units (src/frontend/src/lib/components/views/EditAccount.svelte:81-104). Users then cannot save a default-sign-in-only change without first renaming the account. Keep the account fallback within its 32-character limit or keep remote display metadata out of account labels.

This issue also appears on line 190 of the same file.

  const application = $derived($metadataStore.name);

src/frontend/src/lib/utils/appMetadata.ts:190

• The sanitizer misses U+061C ARABIC LETTER MARK, which is part of Unicode's Bidi_Control set and can alter the visual ordering of app-provided text. This leaves the stated bidi-spoofing hardening incomplete; strip it alongside the other bidi controls.

      /[\u0000-\u0008\u000e-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g,

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/frontend/src/routes/(new-styling)/authorize/+page.svelte:514

• The permissionless name can be shown here without its matching trust anchor. upgradePanel() is also rendered around SsoNormalLoginRequired and UpgradeSuccessView, neither of which displays an origin; during attribute consent, the adjacent header may instead display effectiveOrigin. Thus a channel origin can supply this name while no matching hostname—or a different hostname—is visible, contrary to the new metadata invariant. Add the channel-origin badge inside this panel whenever the name is used, or keep this copy generic in wrappers that do not display that same origin.

        {#if dapp.name !== undefined}
          {@const application = dapp.name}
          {$t`${application} has moved to the new Internet Identity`}

src/frontend/src/lib/utils/appMetadata.test.ts:133

• The 10-second abort path is a core hardening behavior, but this suite never advances timers or verifies that the request's signal is aborted; the network-error test only covers an immediate rejection. Add a hanging-fetch test so removal or mis-scoping of the timeout cannot silently leave metadata requests pending indefinitely.

test("should return undefined when the fetch fails (e.g. missing CORS headers)", async () => {
  setupFetchMock(new TypeError("Failed to fetch"));

  expect(await fetchAppMetadata(ORIGIN)).toBeUndefined();
});

[aterga]

Note on the red Canister tests check: the failures are e2e-playwright (mobile, 6_6) / (mobile, 3_6) — the legacy-domain popup test (legacy.spec.ts:52) and the gated-SSO 1-click test (sso.spec.ts:1129) timing out on mobile emulation. These are pre-existing flakes, not caused by this PR: the main-branch run for 21ab317 — this PR's exact base commit, without any of these changes — failed with the same two jobs, and both tests pass on desktop and passed on this branch's earlier waves (fd6faf9, c3108bf) with identical relevant code. Everything else (Rust, frontend checks, all canister integration tests, the other 11 e2e shards) is green on every commit of this PR. I'm re-running the affected jobs until the flake clears.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/frontend/src/lib/utils/appMetadata.ts:193

• This range also removes U+200C ZERO WIDTH NON-JOINER and U+200D ZERO WIDTH JOINER. Those are required for correct shaping in languages such as Persian and for common emoji sequences, so valid names like Acme 👩‍💻 are silently changed to Acme 👩💻; neither character is a control or bidi-override character covered by the documented sanitization. Preserve these two joiners while continuing to remove zero-width space and bidi marks, and add a regression case for them.

      /[\u0000-\u0008\u000e-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g,

[aterga]

@copilot thanks — the last two rounds landed three findings that were all worth acting on, including one real bug. Responses below, all pushed.

Round 6 — ZWNJ/ZWJ stripped by the sanitizer (4ee96e9). You were right, and this was a genuine bug rather than a nit. - swallowed U+200C and U+200D, neither of which is a control or bidi character: ZWNJ drives correct shaping in scripts such as Persian, and ZWJ holds emoji sequences together, so Acme 👩‍💻 silently decayed into Acme 👩💻. The range is now `` — zero-width space plus LRM/RLM — and there's a regression case for both joiners. I checked it actually guards: it fails against the old range and passes against the new one.

Round 5, item 1 — app name shown without its trust anchor (dcf8827). Confirmed by reading the wrappers: UpgradeSuccessView renders no origin at all and SsoNormalLoginRequired shows only the SSO org name, so on those screens a permissionless name had nothing vouching for it, and during attribute consent the header shows the effective/derivation origin instead. I took your second suggested option: upgradePanel now takes showsAppOrigin and only names the app in the wrappers whose header shows that same channel origin (the sign-in wizard and the continue screen); upgrade-success, the SSO fail-safe and attribute consent keep the generic "This app has moved…" copy.

Round 5, item 2 — untested abort path (dcf8827). Added two fake-timer cases: a hanging origin has its signal aborted and falls back once the budget elapses, and the signal is still live one millisecond before it — so the timeout can't be removed or mis-scoped without a failure. The budget is now exported as APP_METADATA_FETCH_TIMEOUT_MILLIS so the tests assert against the real value.

Still standing by the one thing I declined earlier (here): fetch-time logo decode probing and intrinsic-dimension caps. A pathological logo only degrades the sign-in popup of the origin that served it, and probing would penalise SVG, the most common legitimate logo format. The render-time onerror fallback plus the content-type allowlist and 256 KiB cap cover the user-visible failure.

On the red Canister tests check: the failure is sso.spec.ts:1129 (gated non-sub SSO), which fails identically on main at this PR's base commit 21ab317 — see that run's shard 3. Pre-existing flake, re-running.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/frontend/src/lib/components/ui/AuthorizeHeader.svelte:17

• The badge does not identify the origin that supplied this permissionless metadata: hostname drops both the scheme and any non-default port. For example, metadata fetched from https://example.com:8443 is displayed next to example.com, even though that is a different origin (and principal) from https://example.com. Display the serialized origin, or at minimum all security-relevant origin components, as the trust anchor and cover a non-default-port case in tests.

  const metadataStore = $derived(getAppMetadataStore(origin));

docs/ii-spec.mdx:352

• Calling only the hostname “the application's origin” hides security-relevant scheme and port differences. Since the feature supports arbitrary web origins and fetches metadata from the exact origin, the specification should require displaying the serialized origin (for example, https://example.com:8443) and the UI should follow that requirement.

Since the file is under the sole control of the application origin, the metadata is exactly as trustworthy as that origin itself: it does not certify or verify the application's identity in any way. Internet Identity therefore always displays the application's origin (as its hostname) alongside this metadata, as the value users can actually verify.

src/frontend/src/routes/(new-styling)/authorize/views/RedirectAnimationView.svelte:24

• This redirect view has the same origin-confusion issue as the authorization header: the logo comes from the exact channel origin, but the badge omits its scheme and port. Distinct origins such as https://example.com and https://example.com:8443 therefore get the same visible trust anchor. Render the serialized origin (consistently with the other metadata consumers) instead of only .hostname.

  const hostname = $derived(new URL($establishedChannelStore.origin).hostname);

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to c6812c1.

Security Overview

• 🔎 Scanned files: 14 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/6d3e3b61-710b-4b2b-9c0b-43458b6314b6?scanId=734dc533-9b1c-491d-8dda-a4839d41430f&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► src/frontend/src/lib/components/ui/AuthorizeHeader.svelte     Modify to use app-metadata store and display app metadata (logo, name, description) with improved rendering and fallback behavior ► src/frontend/src/lib/stores/app-metadata.store.ts     Add per-origin app metadata store with fallback to curated dapps and fetch logic ► src/frontend/src/lib/utils/appMetadata.ts     Add app metadata utilities (fetch metadata, constants, types)
Enhancement	► src/frontend/src/lib/stores/app-metadata.store.test.ts     Add tests for app metadata store behavior (fallback, fetch, caching, reset)
Enhancement	► src/frontend/src/lib/utils/appMetadata.test.ts     Add extensive tests for app metadata utilities (fetching, decoding logos, size/type checks, normalization, error handling)