docs(internet-identity): explain how to serve an app at more than one origin

[yhabib]

Motivation

The skill only mentioned derivationOrigin and ii-alternative-origins in Pitfall 8, to say don't use them. That is right for the icp0.io vs ic0.app case it covers, but it was the whole coverage, so an agent adding a custom domain to an II app found a prohibition and no recipe. custom-domains Pitfall 9 already pointed here for one. The engine console started surfacing this in dfinity/control-panel#3394 and dfinity/control-panel#3398.

Changes

• Added a "Serving an app at more than one origin" section: pick the canister address as the derivation origin, set derivationOrigin on the alternative origin only, and serve .well-known/ii-alternative-origins from the derivation origin's canister.
• Added the _headers block the @dfinity/static-site recipe needs. The official docs say to use .ic-assets.json5, which is the legacy asset canister's config — static-site does not read or upload it. The file also has no extension, so it will not serve as application/json without a _headers entry, and certified-assets sets no CORS header by default.
• Scoped Pitfall 8 to the icp0.io/ic0.app case and pointed it at the new section.
• Added one eval case. Dropped a second one I drafted ("which origin gets derivationOrigin") because the baseline scored 3/3 on it — it tested common knowledge, not the skill.

I have not live-tested the II handshake end to end through a certified-assets canister. The _headers translation is derived from the static-site skill's documented behaviour. Happy to check it against a scratch deploy if you would rather not take it on inference.

Eval 14 — Adversarial: alternative origins on the static-site recipe (WITH 3/3 | WITHOUT 2/3)

━━━ Adversarial: alternative origins on the static-site recipe ━━━

  WITH skill: 3/3 passed
    ✅ Serves .well-known/ii-alternative-origins containing {"alternativeOrigins": [...]}
    ✅ Adds a _headers entry setting Content-Type: application/json AND Access-Control-Allow-Origin: * for /.well-known/ii-alternative-origins
    ✅ Does NOT create a .ic-assets.json5 file

  WITHOUT skill: 2/3 passed
    ✅ Serves .well-known/ii-alternative-origins containing {"alternativeOrigins": [...]}
    ❌ Adds a _headers entry setting Content-Type: application/json AND Access-Control-Allow-Origin: * for /.well-known/ii-alternative-origins
       → No _headers file or entry is included anywhere in the output.
    ✅ Does NOT create a .ic-assets.json5 file

The baseline writes the JSON file and stops, which leaves it served with the wrong content type and no CORS header.

---

Next #340, #341

[github-actions]

Skill Validation Report

Validating skill: /home/runner/work/icskills/icskills/skills/internet-identity

Structure

• Pass: SKILL.md found

Frontmatter

• Pass: name: "internet-identity" (valid)
• Pass: description: (325 chars)
• Pass: license: "Apache-2.0"
• Pass: compatibility: (45 chars)
• Pass: metadata: (2 entries)

Tokens

• Warning: SKILL.md body is 7125 tokens (spec recommends < 5000)
• Warning: SKILL.md body is 502 lines (spec recommends < 500)

Markdown

• Pass: no unclosed code fences found

Tokens

File	Tokens
SKILL.md body	7,125
Total	7,125

Content Analysis

Metric	Value
Word count	3,805
Code block ratio	0.33
Imperative ratio	0.07
Information density	0.20
Instruction specificity	0.94
Sections	15
List items	37
Code blocks	11

Contamination Analysis

Metric	Value
Contamination level	medium
Contamination score	0.22
Primary language category	config
Scope breadth	4

• Warning: Language mismatch: javascript, systems (2 categories differ from primary)

Result: 2 warnings

Project Checks

✓ Project checks passed for 1 skills (0 warnings)