docs: verifiable credentials guide

[marc0olo]

Summary

• Explains the four actors (user, issuer, relying party, identity provider) and the unlinkability property
• 7-step protocol flow plus window message protocol details
• Implementing an issuer: all four API endpoints (vc_consent_message, derivation_origin, prepare_credential, get_credential) with credential format conventions
• Implementing a relying party: JS SDK approach with @dfinity/verifiable-credentials, manual window message integration, and full VP verification (structure, cryptographic, semantic checks)
• Testing: live demo canister IDs and local development setup with ii: true in icp.yaml
• Privacy properties: unlinkability, user consent, opaque errors
• Sourced from dfinity/portal verifiable-credentials section (all 4 pages)

Sync recommendation

informed by dfinity/portal — verifiable-credentials/overview.mdx, how-it-works.mdx, issuer.mdx, relying-party.mdx

[marc0olo]

Review: Verifiable Credentials

Must fix

• Internet Identity URL is stale: The page uses https://identity.internetcomputer.org in two developer-facing code examples — the JS SDK identityProvider parameter (line 169) and the manual window.open call (line 191). The internet-identity skill explicitly states the correct mainnet II URL is https://id.ai. The page should use https://id.ai for both. The local development URL http://id.ai.localhost:8000 is already used correctly in the icp.yaml section.

  Related: the semantic verification section (line 341) instructs developers to check that the iss field is https://identity.internetcomputer.org/. If II now issues credentials with https://id.ai/ as the issuer, this verification check is incorrect and will cause relying party implementations to incorrectly reject valid credentials. This needs verification against the live vc-spec or a fresh VC flow. The portal source also uses identity.internetcomputer.org/ for the iss value, but the portal itself has not been updated to reflect id.ai. Flag this for human verification if the canonical iss value cannot be confirmed from .sources/.

• Broken internal link in "Next steps": The link [Internet Identity integration](internet-identity.md) (line 395) resolves to docs/guides/authentication/internet-identity.md, which does not exist. The actual file is docs/guides/authentication/internet-identity.mdx. Per project rules, .md extension links to .mdx files are valid and Astro resolves them — so the link extension is correct. However, confirm Astro actually resolves the link at build time; if not, the page is a stub that exists so linking to it is fine.

  Status: internet-identity.mdx exists at docs/guides/authentication/internet-identity.mdx. The link internet-identity.md should resolve correctly. This is not broken — mark as verified.

• Rust issuer code snippets are stubs: The vc_consent_message endpoint section (lines 61–67) shows only a comment block, not actual code. This is protected by a <!-- Needs human verification --> flag, which is correct. However, the other three endpoints (derivation_origin, prepare_credential, get_credential) also lack actual code examples — only prose descriptions are provided. The portal source links to actual Rust code in the vc-playground repo. For a guide on implementing an issuer, the absence of code for all four required API endpoints leaves developers without usable implementation guidance. Either add code examples verified from .sources/ or link to the vc-playground reference implementation more prominently.

Suggestions

• Demo issuer URL: The testing section links the demo issuer to https://qdiif-2iaaa-aaaap-ahjaq-cai.icp0.io/ (line 369). The portal source links this same canister to https://dashboard.internetcomputer.org/canister/qdiif-2iaaa-aaaap-ahjaq-cai (the NNS dashboard). If the demo issuer has a frontend at the .icp0.io URL, the page's link is more useful. If it does not serve a frontend (it's only an API canister), the link will return an error or empty page. Consider linking to the GitHub demo or dashboard page instead, since the vc-playground is the primary reference.

• @dfinity/verifiable-credentials package placement: The page introduces the JS SDK option (@dfinity/verifiable-credentials) before the manual integration, which is the right order of preference. However, it does not mention that this package is separate from the @icp-sdk/* family. Developers familiar with @icp-sdk/auth might wonder why they need a different npm package. A one-sentence clarification that this is a dedicated VC SDK (not part of @icp-sdk) would reduce confusion.

• Verification section cross-credential check: The cross-credential check (line 351) says to verify that the sub of the issued credential (did-id-alias) matches vc.credentialSubject.InternetIdentityIdAlias.hasIdAlias. This is accurate per the portal source. Consider adding a note that this sub uses the did: URI scheme (i.e., it is a DID string, not a bare principal text), since the decoded JSON shows "sub": "<did-id-alias>" which is easy to misread as a plain string.

• Opening paragraph funnel: The page opens well — it defines VC, names the actors, and describes the flow. The "How the protocol works" section follows naturally. The content brief coverage is solid. However, the guide does not tell developers upfront which role they are implementing (issuer vs. relying party) before diving into concepts — an early "Choose your integration path" paragraph or callout would help developers skip directly to the section relevant to them.

Verified

• All internal links checked: ../../reference/internet-identity-spec.md → docs/reference/internet-identity-spec.md (exists), ../../reference/ic-interface-spec.md → docs/reference/ic-interface-spec.md (exists), internet-identity.md → docs/guides/authentication/internet-identity.mdx (exists, .md extension resolves per Astro convention).
• Frontmatter is complete and consistent: title and description both present, description matches page scope.
• No dfx references present.
• No mo:base imports present (page has no Motoko code).
• No internetcomputer.org/docs/ links present.
• No .mdx file (uses .md as required for this content type).
• <!-- Upstream: --> comment present at end of page.
• The four-actor model (user, issuer, relying party, identity provider) matches the portal source.
• JSON-RPC message format (vc-flow-ready, request_credential, success/error responses) matches the portal's relying-party.mdx.
• VP structure (two JWTs: id-alias credential + issued credential) matches the portal source.
• Semantic verification steps match the portal's relying-party.mdx.
• icp.yaml ii: true configuration matches the internet-identity skill.
• Testing environment URLs (demo RP at l7rua-raaaa-aaaap-ahh6a-cai.icp0.io, staging II at fgte5-ciaaa-aaaad-aaatq-cai.ic0.app) match the portal's how-it-works.mdx.
• @dfinity/verifiable-credentials package is the correct npm package per portal source (not in @icp-sdk namespace — this is a separate VC-specific SDK).
• Code snippet lengths: all inline examples are under 30 lines.
• Link to vc_util library (line 333) and vc-playground (lines 131, 355) are external GitHub links to the correct repos.

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed for PR #80 (Verifiable Credentials guide):

Changes applied

Must fix — Internet Identity URL is stale

• Updated identityProvider: new URL("https://identity.internetcomputer.org") to new URL("https://id.ai") in the JS SDK example
• Updated window.open("https://identity.internetcomputer.org/vc-flow") to window.open("https://id.ai/vc-flow") in the manual integration section
• Source: internet-identity skill (SKILL.md) explicitly states https://id.ai is the correct mainnet II URL

Must fix — iss field in semantic verification (flagged for human verification)

• The iss check in semantic verification still reads https://identity.internetcomputer.org/ — this matches the portal source (relying-party.mdx line 237). The reviewer correctly notes this needs verification against the live vc-spec. Added a <\!-- Needs human verification --> flag on that line so reviewers know to confirm whether II now uses https://id.ai/ as the issuer for credentials.
• Not changed to id.ai/ — the portal source explicitly shows "iss": "https://identity.internetcomputer.org/" and the vc-spec was not available in .sources/ to confirm the live behavior. The developer-facing connection URLs (identityProvider, window.open) are confirmed updated; the iss verification value requires a human to run a live VC flow to confirm.

Must fix — Issuer code stubs

• Added a more prominent pointer to the vc-playground reference implementation with explanation of why it is the right place for all four endpoints (canister signatures, certified data, Candid interfaces)
• Added a <\!-- Needs human verification --> flag for the issuer endpoint signatures, making it explicit that vc-playground is not in .sources/ and inline code cannot be verified
• Actual Rust code not added — vc-playground is not in .sources/ so no code can be verified; the existing approach of linking the reference implementation is the correct one

Suggestion — Integration path callout

• Added a "Choose your path" paragraph after the introduction, linking directly to the issuer and relying party sections

Suggestion — @dfinity/verifiable-credentials package clarification

• Added one sentence clarifying the package is separate from the @icp-sdk/* family

Suggestion — DID URI scheme note in cross-credential check

• Updated the cross-credential check to clarify that the sub value uses the did: URI scheme and is not a bare principal text

Suggestion — Demo issuer URL

• Updated the demo issuer link to point to the NNS dashboard plus the vc-playground repo, matching the portal source (how-it-works.mdx line 84). The .icp0.io URL could not be verified as serving a real frontend.

Items skipped

Broken internal link check

• The reviewer verified this is not broken: internet-identity.md resolves to docs/guides/authentication/internet-identity.mdx per Astro convention. No fix needed.

iss value change to https://id.ai/

• Skipped changing the iss verification value. Reason: the portal source (relying-party.mdx) uses https://identity.internetcomputer.org/ and no source in .sources/ confirms this has changed. The feedback itself says to flag for human verification if the canonical iss value cannot be confirmed from .sources/. A verification flag was added instead.