Skip to content

Commit ecfef03

Browse files
marc0olomarc0olo
authored
infra: add sync:ii-spec script, port II spec commits, and sync vc-spec (#249)
## Summary - Adds `scripts/sync-ii-spec.mjs` — a deterministic sync script that transforms upstream specs from `dfinity/internet-identity` into reference pages; same pattern as `sync-motoko.sh` - Syncs two specs in one pass: - `docs/ii-spec.mdx` → `docs/references/internet-identity-spec.md`: strip MDX imports, remove H1, rewrite 8 absolute `internetcomputer.org` link patterns to relative paths, inline the Candid `.did` file in place of `<CodeBlock>`, inject frontmatter, append link-adaptation log - `docs/vc-spec.md` → `docs/references/verifiable-credentials-spec.md`: remove H1, rewrite 5 stale portal links to relative internal paths, inject frontmatter, append link-adaptation log; upstream fix tracked in `dfinity/internet-identity#3889` - Pins `.sources/internetidentity` to `release-2026-05-08` (`f6cf858`) — switches from main-tracking to release-tracking; spec changes are only live once the canister is deployed - Adds `internetidentity` to `.sources/VERSIONS` alongside other release-pinned submodules - Adds `"sync:ii-spec": "./scripts/sync-ii-spec.mjs"` to `package.json` - Adds `.github/workflows/sync-ii-spec.yml` — runs weekly on Tuesday and on `workflow_dispatch`; finds the latest `release-YYYY-MM-DD` tag, filters for changes to `ii-spec.mdx`, `vc-spec.md`, or `internet_identity.did`, and opens a PR (with VERSIONS update) only if relevant files changed - Adds `verifiable-credentials-spec` to the sidebar and reference index - Updates the VC guide's "Next steps" to link to the new reference page instead of the raw GitHub file - Updates `AGENTS.md`: documents both output files, `vcLinkMap`, release-based pinning strategy, and the "only bump if synced docs changed" policy - Fixes `scripts/validate.js`: `checkForbiddenPatterns` now skips code blocks (same as `checkEmdash`), preventing false positives on URLs inside Candid code comments ## Sync recommendation `sync from dfinity/internet-identity — docs/ii-spec.mdx, docs/vc-spec.md, src/internet_identity/internet_identity.did`
1 parent 9345d50 commit ecfef03

13 files changed

Lines changed: 2417 additions & 1012 deletions

File tree

‎.github/workflows/sync-ii-spec.yml‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
name: Sync II spec
2+
3+
on:
4+
schedule:
5+
- cron: '0 9 * * 2' # Weekly on Tuesday (II releases are typically Monday/Tuesday)
6+
workflow_dispatch:
7+
8+
jobs:
9+
sync:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
13+
with:
14+
fetch-depth: 0
15+
16+
- name: Create GitHub App Token
17+
uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
18+
id: app-token
19+
with:
20+
client-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_CLIENT_ID }}
21+
private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}
22+
23+
- name: Initialize internetidentity submodule at current pin
24+
run: |
25+
git config --global url."https://github.com/".insteadOf "git@github.com:"
26+
git submodule update --init --depth 1 .sources/internetidentity
27+
28+
- name: Get current pinned hash
29+
id: current
30+
run: |
31+
HASH=$(git -C .sources/internetidentity rev-parse HEAD)
32+
echo "hash=$HASH" >> $GITHUB_OUTPUT
33+
echo "short=$(git -C .sources/internetidentity rev-parse --short HEAD)" >> $GITHUB_OUTPUT
34+
35+
- name: Fetch latest release tag and resolve hash
36+
id: latest
37+
run: |
38+
git -C .sources/internetidentity fetch --tags --depth 100 origin
39+
TAG=$(git -C .sources/internetidentity tag --sort=-version:refname \
40+
| grep '^release-[0-9][0-9][0-9][0-9]-' | head -1)
41+
echo "Latest release tag: $TAG"
42+
HASH=$(git -C .sources/internetidentity rev-parse "$TAG")
43+
SHORT=$(git -C .sources/internetidentity rev-parse --short "$TAG")
44+
echo "tag=$TAG" >> $GITHUB_OUTPUT
45+
echo "hash=$HASH" >> $GITHUB_OUTPUT
46+
echo "short=$SHORT" >> $GITHUB_OUTPUT
47+
48+
- name: Check if relevant files changed
49+
id: check
50+
run: |
51+
CURRENT="${{ steps.current.outputs.hash }}"
52+
LATEST="${{ steps.latest.outputs.hash }}"
53+
BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.tag }}"
54+
55+
if [ "$CURRENT" = "$LATEST" ]; then
56+
echo "Already at latest release ${{ steps.latest.outputs.tag }}. No update needed."
57+
echo "needed=false" >> $GITHUB_OUTPUT
58+
exit 0
59+
fi
60+
61+
if git ls-remote --exit-code origin "refs/heads/${BRANCH}" > /dev/null 2>&1; then
62+
echo "Branch $BRANCH already exists — PR likely open, skipping."
63+
echo "needed=false" >> $GITHUB_OUTPUT
64+
exit 0
65+
fi
66+
67+
# Only proceed if the spec files themselves changed
68+
CHANGED=$(git -C .sources/internetidentity diff --name-only "${CURRENT}..${LATEST}" -- \
69+
docs/ii-spec.mdx \
70+
docs/vc-spec.md \
71+
src/internet_identity/internet_identity.did)
72+
73+
if [ -z "$CHANGED" ]; then
74+
echo "No changes to ii-spec.mdx, vc-spec.md, or internet_identity.did. Skipping."
75+
echo "needed=false" >> $GITHUB_OUTPUT
76+
else
77+
echo "Spec files changed:"
78+
echo "$CHANGED"
79+
echo "needed=true" >> $GITHUB_OUTPUT
80+
echo "changed_files<<EOF" >> $GITHUB_OUTPUT
81+
echo "$CHANGED" >> $GITHUB_OUTPUT
82+
echo "EOF" >> $GITHUB_OUTPUT
83+
fi
84+
85+
- name: Bump submodule to latest main
86+
if: steps.check.outputs.needed == 'true'
87+
run: git -C .sources/internetidentity checkout ${{ steps.latest.outputs.hash }}
88+
89+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
90+
if: steps.check.outputs.needed == 'true'
91+
with:
92+
node-version: 22
93+
cache: npm
94+
95+
- name: Install dependencies
96+
if: steps.check.outputs.needed == 'true'
97+
run: npm ci
98+
99+
- name: Initialize examples submodule (required for build)
100+
if: steps.check.outputs.needed == 'true'
101+
run: git submodule update --init --depth 1 .sources/examples
102+
103+
- name: Run II spec sync
104+
if: steps.check.outputs.needed == 'true'
105+
run: npm run sync:ii-spec
106+
107+
- name: Build check
108+
if: steps.check.outputs.needed == 'true'
109+
run: npm run build
110+
111+
- name: Update VERSIONS
112+
if: steps.check.outputs.needed == 'true'
113+
run: |
114+
sed -i "s|^internetidentity.*|internetidentity ${{ steps.latest.outputs.tag }} ${{ steps.latest.outputs.short }}|" .sources/VERSIONS
115+
116+
- name: Create PR
117+
if: steps.check.outputs.needed == 'true'
118+
run: |
119+
git config user.name "pr-automation-bot-public[bot]"
120+
git config user.email "pr-automation-bot-public[bot]@users.noreply.github.com"
121+
122+
BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.tag }}"
123+
git checkout -b "$BRANCH"
124+
git add .sources/internetidentity docs/references/internet-identity-spec.md docs/references/verifiable-credentials-spec.md public/references/internet-identity.did .sources/VERSIONS
125+
git commit -m "chore: sync II spec to dfinity/internet-identity ${{ steps.latest.outputs.tag }}"
126+
git push -u origin "$BRANCH"
127+
128+
CHANGED="${{ steps.check.outputs.changed_files }}"
129+
{
130+
echo "## Summary"
131+
echo ""
132+
echo "Automated sync of the Internet Identity specification from \`dfinity/internet-identity\`."
133+
echo ""
134+
echo "**Release:** \`${{ steps.latest.outputs.tag }}\` (pinned from \`${{ steps.current.outputs.short }}\` → \`${{ steps.latest.outputs.short }}\`)"
135+
echo ""
136+
echo "**Changed upstream files:**"
137+
while IFS= read -r f; do
138+
[ -n "$f" ] && echo "- \`$f\`"
139+
done <<< "$CHANGED"
140+
echo ""
141+
echo "- Ran \`npm run sync:ii-spec\` — regenerated \`docs/references/internet-identity-spec.md\` and \`docs/references/verifiable-credentials-spec.md\`"
142+
echo "- Build passed ✓"
143+
echo ""
144+
echo "## Checklist"
145+
echo ""
146+
echo "- [ ] Review the diff to \`docs/references/internet-identity-spec.md\` for content changes"
147+
echo "- [ ] Review the diff to \`docs/references/verifiable-credentials-spec.md\` for content changes"
148+
echo "- [ ] Check for new absolute \`internetcomputer.org\` link patterns (script exits non-zero if any were missed)"
149+
echo "- [ ] Verify any renamed or restructured sections are reflected correctly"
150+
echo ""
151+
echo "## Sync recommendation"
152+
echo ""
153+
echo "\`sync from dfinity/internet-identity — docs/ii-spec.mdx, docs/vc-spec.md, src/internet_identity/internet_identity.did\`"
154+
} > /tmp/pr-body.md
155+
156+
gh pr create \
157+
--title "chore: sync II spec to dfinity/internet-identity ${{ steps.latest.outputs.tag }}" \
158+
--body-file /tmp/pr-body.md
159+
env:
160+
GH_TOKEN: ${{ steps.app-token.outputs.token }}

‎.sources/VERSIONS‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
# version. Those repos are: examples, icskills, dotskills,
55
# icp-cli-recipes, icp-cli-templates, icp-js-sdk-docs.
66
#
7+
# internetidentity — uses date-based release tags (release-YYYY-MM-DD).
8+
# Only ii-spec.mdx, vc-spec.md, and internet_identity.did are synced.
9+
# Pin to the latest release tag, not the tip of main — spec changes are
10+
# only live once the canister is deployed at that release.
11+
# The automated workflow (.github/workflows/sync-ii-spec.yml) finds the
12+
# latest release-YYYY-MM-DD tag and only opens a PR if those files changed.
13+
#
714
# FORMAT: <submodule> <version label> <7-char hash>
815
#
916
# The hash is the authoritative ref — it is what .gitmodules pins and what
@@ -55,3 +62,4 @@ motoko-core v2.4.0
5562
cdk-rs ic-cdk v0.20.1 / ic-cdk-timers v1.0.0 / ic-cdk-executor v2.0.0 317f55c
5663
candid 2025-12-18 # candid v0.10.20, didc v0.5.4 2e4a2cf
5764
response-verification v3.1.0 18c5a37
65+
internetidentity release-2026-05-08 f6cf858

‎.sources/internetidentity‎

Submodule internetidentity updated 1181 files

‎AGENTS.md‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ docs/ # All documentation (.md only) — src/content/docs/
192192
All upstream source repos are pinned as **git submodules** under `.sources/`. This ensures every agent reads the exact same content, regardless of when they run.
193193

194194
**Two pinning strategies:**
195-
- **Track latest release** — repos that publish versioned releases users install. Pin to the latest release tag.
195+
- **Track latest release** — repos where the release represents the live/deployed state. Pin to the latest release tag. Spec changes are only accurate once released.
196196
- **Track main/master** — content repos where the default branch *is* the canonical source.
197197

198198
For current release hashes, see `.sources/VERSIONS`.
@@ -216,7 +216,7 @@ For current release hashes, see `.sources/VERSIONS`.
216216
| `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) |
217217
| `.agents/skills/icp-brand-voice` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand voice: positioning, vocabulary, banned terms, voice attributes |
218218
| `.agents/skills/icp-brand-design` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand design: color tokens, typography, layout, components, accessibility |
219-
| `.sources/internetidentity` | `dfinity/internet-identity` | `main` | Internet Identity spec (`docs/ii-spec.mdx`), Candid interface (`src/internet_identity/internet_identity.did`) |
219+
| `.sources/internetidentity` | `dfinity/internet-identity` | latest release | Internet Identity spec (`docs/ii-spec.mdx`), VC spec (`docs/vc-spec.md`), Candid interface (`src/internet_identity/internet_identity.did`) |
220220

221221
### Submodule initialization
222222

@@ -288,7 +288,7 @@ EOF
288288
| `candid` | Check for spec changes affecting the Candid reference or type-mapping examples |
289289
| `response-verification` | Check for API changes affecting certified variables patterns |
290290
| `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria |
291-
| `internetidentity` | Check for spec changes in `docs/ii-spec.mdx`; re-sync `internet-identity-spec.md` (see link adaptation note below). Re-copy Candid interface from `src/internet_identity/internet_identity.did` if changed |
291+
| `internetidentity` | Run `npm run sync:ii-spec` — the script syncs both `ii-spec.mdx` → `docs/references/internet-identity-spec.md` and `vc-spec.md` → `docs/references/verifiable-credentials-spec.md`, handling all link rewrites, Candid inlining, and frontmatter in one pass. If the script exits with a warning about unhandled links, add the new pattern to `linkMap` (ii-spec) or `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. Pin to the latest `release-YYYY-MM-DD` tag — spec changes are only live once the canister is deployed at that release. The **Sync II spec** workflow (`.github/workflows/sync-ii-spec.yml`) checks the latest release tag and only opens a PR when `docs/ii-spec.mdx`, `docs/vc-spec.md`, or `internet_identity.did` actually changed. Trigger manually for early sync. |
292292
| `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns |
293293
| `papi` | Check for changed payment interface or cycle cost model |
294294
| `ic-pub-key` | Check for changed CLI flags or commands |
@@ -313,14 +313,7 @@ EOF
313313
```
314314
4. Run `npm run build` to confirm no broken links.
315315

316-
**Link adaptation for `internet-identity-spec.md`:** The upstream source (`docs/ii-spec.mdx`) uses absolute `internetcomputer.org` URLs pointing to the IC interface spec. Our file uses relative paths into the split `ic-interface-spec/` directory. After every re-sync, run:
317-
```bash
318-
grep -n "ic-interface-spec" docs/references/internet-identity-spec.md
319-
```
320-
Any link of the form `internetcomputer.org/.../ic-interface-spec#<anchor>` or `./ic-interface-spec.md#<anchor>` must be converted. Use the anchor-to-file mapping at the bottom of `docs/references/internet-identity-spec.md` as the authoritative guide. If a new anchor appears that is not in the comment, find its file with:
321-
```bash
322-
grep -r "{#<anchor>}" docs/references/ic-interface-spec/
323-
```
316+
**Link adaptation for `internet-identity-spec.md` and `verifiable-credentials-spec.md`:** Both are handled automatically by `npm run sync:ii-spec`. The script rewrites stale `internetcomputer.org` links to internal relative paths using `linkMap` (ii-spec) and `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. If a new unhandled link pattern appears, the script exits with a warning — add it to the appropriate map with the correct relative path (use `grep -r "{#<anchor>}" docs/references/ic-interface-spec/` to find which file owns a given anchor), then re-run. Stale links in `vc-spec.md` are tracked upstream in `dfinity/internet-identity#3889`; once fixed, the rewrites become harmless no-ops (old URL simply no longer appears in the source).
324317

325318
### Directly maintained spec files
326319

‎docs/guides/authentication/verifiable-credentials.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -395,7 +395,7 @@ The VC protocol provides the following privacy guarantees:
395395

396396
## Next steps
397397

398-
- Read the [VC specification](https://github.com/dfinity/internet-identity/blob/main/docs/vc-spec.md) for the full protocol details.
398+
- Read the [VC specification](../../references/verifiable-credentials-spec.md) for the full protocol details.
399399
- Explore the [verifiable credentials playground](https://github.com/dfinity/vc-playground) for issuer and relying party reference implementations.
400400
- Review [Internet Identity integration](internet-identity.md) for authentication setup.
401401
- See the [Internet Identity specification](../../references/internet-identity-spec.md) for alternative derivation origins and canister signature details.

‎docs/references/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Technical reference material for ICP development. These pages cover exact specif
3636
- **[HTTP Gateway Specification](http-gateway-protocol-spec.md)**: How boundary nodes serve canister HTTP responses with certification verification.
3737
- **[Candid Specification](candid-spec.md)**: The Candid interface description language: type system, encoding, and subtyping rules.
3838
- **[Internet Identity Specification](internet-identity-spec.md)**: Delegation chains, passkey management, and canister signatures.
39+
- **[Verifiable Credentials Specification](verifiable-credentials-spec.md)**: Normative protocol for issuing and verifying credentials on ICP.
3940

4041
## Governance
4142

0 commit comments

Comments
 (0)