Skip to content

docs: add comments explaining DID verification relationships and key purposes - #604

Open
A-Chronicle wants to merge 1 commit into
hyperledger-identus:mainfrom
A-Chronicle:docs/did-verification-relationships
Open

docs: add comments explaining DID verification relationships and key purposes#604
A-Chronicle wants to merge 1 commit into
hyperledger-identus:mainfrom
A-Chronicle:docs/did-verification-relationships

Conversation

@A-Chronicle

@A-Chronicle A-Chronicle commented May 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Resolves #598 by adding comprehensive inline documentation explaining DID verification relationships and key purposes to help new contributors understand Self-Sovereign Identity (SSI) concepts.

Changes

FindDIDSigningKeys.ts

  • Added 37-line module-level documentation explaining:

    • DID verification relationships concept
    • ISSUING_KEY → "assertionMethod" mapping (credential issuance)
    • AUTHENTICATION_KEY → "authentication" mapping (DID ownership proofs)
    • Why multiple keys exist (key rotation, security, scalability)
    • Example DID document structure with references to W3C DID Core Specification

  • Enhanced class JSDoc with workflow details and example usage

  • Added comment in run() method explaining verification method mapping

  • Added documentation for matchKeys() method explaining key matching algorithm and encoding formats

CreateJwt.ts

  • Added comprehensive documentation explaining:

    • JWT use cases in SSI systems
    • Why ISSUING_KEY is default (credential issuance)
    • When to use AUTHENTICATION_KEY (challenge-response authentication)
    • How verification works on recipient side
    • Complete JSDoc parameter descriptions

  • Added comment in run() method clarifying default key selection

CreateSDJWT.ts

  • Added 23-line documentation explaining:

    • Selective Disclosure JWT (SD-JWT) concept and RFC 9052
    • Privacy-preserving credential sharing use cases
    • Why ISSUING_KEY is default
    • How verifiers can verify disclosed claims

  • Added comment in run() method explaining verification process

Key Concepts Documented

  • Verification Relationships - DID mechanism for specifying key purposes
  • ISSUING_KEY vs AUTHENTICATION_KEY - When and why each is used
  • Key Rotation - Security benefits of separate keys
  • JWT/SD-JWT - How signed credentials work in SSI flows

References Added

Testing

  • All changes are documentation-only (comments)
  • No functional code changes
  • CI checks (lint, build, test, coverage) will pass unchanged
  • Comments are beginner-friendly for those new to DIDs and SSI

Signed-off-by: Anshika Chaubey aajmarketa@gmail.com

@A-Chronicle
A-Chronicle requested a review from a team as a code owner May 5, 2026 12:46
elribonazo
elribonazo requested changes May 5, 2026
View reviewed changes

@elribonazo elribonazo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please follow the contribution guidelines, and always provide DCO and valid signatures on all your commits.

Please respect the pull request default template, and explicitly select the items that apply to your PR

Can you also take a look at the other signing keys of DID's and make sure we add them into the FindDIDSigningKeys Args? I'd try adding each signing key possible and what is the purpose of that key the link to ref docs w3c if perfect

@A-Chronicle
A-Chronicle force-pushed the docs/did-verification-relationships branch from 1805b98 to af7ef79 Compare May 5, 2026 12:54
elribonazo
elribonazo requested changes May 5, 2026
View reviewed changes

@elribonazo elribonazo left a comment •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can u please also tkae a look at the following

Comment thread packages/lib/sdk/src/edge-agent/didFunctions/FindDIDSigningKeys.ts
* @returns {SigningKeyData[]} Array of matched signing keys with their public key info and key IDs
*
* Example usage:
* - CreateJWT defaults to ISSUING_KEY for credential issuance

@elribonazo elribonazo May 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SDJWT should too right? can you confirm that

Comment thread packages/lib/sdk/src/edge-agent/didFunctions/FindDIDSigningKeys.ts Outdated
@A-Chronicle
A-Chronicle force-pushed the docs/did-verification-relationships branch from af7ef79 to 7b27a7b Compare May 5, 2026 12:59
A-Chronicle pushed a commit to A-Chronicle/sdk-ts that referenced this pull request May 5, 2026
Anshika Chaubey
docs: expand DID verification relationships documentation with other …
cdddbf1 
…key types

- Add documentation for future verification relationships (keyAgreement, capabilityInvocation, capabilityDelegation)
- Explain where each key type appears in DID document
- Confirm that SD-JWT also defaults to ISSUING_KEY like CreateJWT
- Provide complete DID document structure example with all verification relationships
- Clarify that SDK currently supports ISSUING_KEY and AUTHENTICATION_KEY

Addresses reviewer feedback on PR hyperledger-identus#604
@A-Chronicle
A-Chronicle force-pushed the docs/did-verification-relationships branch from cdddbf1 to c057c89 Compare May 5, 2026 13:05
@A-Chronicle

A-Chronicle commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the feedback! I've updated the PR to address both comments:

  1. Confirmed SD-JWT uses ISSUING_KEY: Yes, SD-JWT also defaults to ISSUING_KEY just like CreateJWT, since both are used for credential issuance flows. Added explicit documentation in CreateSDJWT noting this parallel behavior.

  2. Added other signing keys documentation: Expanded the module-level documentation in FindDIDSigningKeys to include:

    • keyAgreement → for encryption/decryption operations
    • capabilityInvocation → for invoking delegated capabilities
    • capabilityDelegation → for delegating capabilities to others

    Also provided a complete DID document structure example showing where each verification relationship appears, and clarified that the SDK currently supports ISSUING_KEY and AUTHENTICATION_KEY with other types noted as future extensions.

The updated commit includes all these improvements and is ready for review!

@A-Chronicle

A-Chronicle commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed feedback! I understand now - you want me to actually add support for the other signing keys (keyAgreement, capabilityInvocation, capabilityDelegation) into the FindDIDSigningKeys Args interface, not just document them as future possibilities.

I'll work on:

  1. Extending the Args interface to support all DID verification relationships
  2. Implementing the logic to handle each key type
  3. Adding proper W3C documentation references for each

Will have the updated implementation ready shortly!

@elribonazo

elribonazo commented May 5, 2026

Copy link
Copy Markdown
Contributor

Correct.

Looks a lot better, this is related to #596.
Do you want to try and tackle this in your PR? maybe a separate one

@coveralls

coveralls commented May 5, 2026

Copy link
Copy Markdown

Coverage Status

coverage: 75.19%. remained the same — A-Chronicle:docs/did-verification-relationships into hyperledger-identus:main

@A-Chronicle

A-Chronicle commented May 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Correct.

Looks a lot better, this is related to #596. Do you want to try and tackle this in your PR? maybe a separate one

Thanks for the suggestion @elribonazo ! Almost done with the implementation work! The Args interface extension for all DID verification relationships (keyAgreement, capabilityInvocation, capabilityDelegation) and the logic to handle each key type with proper W3C documentation references is nearly complete.

I've already raised a PR for #596 , should I address these changes in that PR ?

@A-Chronicle A-Chronicle mentioned this pull request May 9, 2026
Merged
8 tasks
@elribonazo
elribonazo self-requested a review May 11, 2026 11:48
elribonazo
elribonazo requested changes May 11, 2026
View reviewed changes

@elribonazo elribonazo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fix the signature please

@A-Chronicle
A-Chronicle force-pushed the docs/did-verification-relationships branch 3 times, most recently from 7221466 to b7b4244 Compare May 21, 2026 07:14
@A-Chronicle
docs: add comments explaining DID verification relationships and key …
09ac600 
…purposes

- Add module-level documentation to FindDIDSigningKeys explaining:
  * DID verification relationships concept
  * ISSUING_KEY ↔ assertionMethod mapping (for credential issuance)
  * AUTHENTICATION_KEY ↔ authentication mapping (for DID ownership proofs)
  * Why multiple keys exist (key rotation, security, scalability)
  * Reference to W3C DID Core Specification
  * Other verification relationships: keyAgreement, capabilityInvocation, capabilityDelegation

- Enhance CreateJwt documentation:
  * Explain SSI JWT use cases
  * Clarify why ISSUING_KEY is default for credential issuance
  * Document when to use AUTHENTICATION_KEY for authentication flows
  * Add complete JSDoc parameter descriptions

- Add CreateSDJWT documentation:
  * Explain Selective Disclosure JWT (SD-JWT) concept
  * Document privacy-preserving credential sharing use case
  * Reference RFC 9052 specification
  * Explain verification process
  * Confirm SD-JWT also defaults to ISSUING_KEY

- Add matchKeys() documentation:
  * Explain key matching algorithm
  * Clarify multibase and JWK encoding support
  * Ensure keys are authorized for requested purpose

- Provide complete DID document structure example with all verification relationships
- Clarify that SDK currently supports ISSUING_KEY and AUTHENTICATION_KEY

Addresses issue hyperledger-identus#598: Makes it easier for new contributors to understand
DID verification relationships, key purposes, and SSI concepts.

Signed-off-by: A-Chronicle <chaubeyanshika319@gmail.com>
@A-Chronicle
A-Chronicle force-pushed the docs/did-verification-relationships branch from b7b4244 to 09ac600 Compare May 21, 2026 07:23
@sonarqubecloud

sonarqubecloud Bot commented May 21, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@elribonazo elribonazo elribonazo requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: add comments explaining DID verification relationships and key purposes

3 participants

@A-Chronicle @elribonazo @coveralls