Feature/w3c credential endpoints #451
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull request overview
This PR adds W3C credential and Presentation Exchange (PEX v2) support to the Credo TS-based REST API, enabling issuance and verification of W3C Verifiable Credentials alongside the existing AnonCreds functionality. This hybrid architecture allows the agent to support both privacy-preserving AnonCreds and interoperable W3C credentials.
Changes:
- Added JsonLdCredentialFormatService and DifPresentationExchangeProofFormatService to agent modules for W3C credential/proof handling
- Extended API type definitions with W3C-specific types (W3cCredential, PresentationDefinitionV2, JsonLdCredentialFormat) to satisfy TSOA OpenAPI generation
- Created comprehensive E2E test suite and documentation for W3C credential issuance and PEX-based proof verification flows
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 16 comments.
Show a summary per file
| File | Description |
|---|---|
| src/agent.ts | Registers JsonLdCredentialFormatService and DifPresentationExchangeProofFormatService in credential/proof protocols, adds W3cCredentialsModule |
| src/controllers/v1/credentials/CredentialController.ts | Updates credential operations to support both AnonCreds and JSON-LD formats via type assertions to internal Credo types |
| src/controllers/v1/proofs/ProofController.ts | Extends proof request/response handlers to support both AnonCreds and PEX formats with conditional spreading |
| src/controllers/types.ts | Adds extensive W3C and PEX type definitions (ApiJsonObject, W3cCredential, PresentationDefinitionV2, etc.) for TSOA compatibility |
| src/controllers/examples.ts | Updates OpenAPI examples with JSON-LD credential format examples and corrects field naming (mime-type to mimeType) |
| tests/unit/agent.test.ts | Adds test verifying W3cCredentialsModule is registered on agent instance |
| tests/unit/credential.test.ts | Adds unit tests for JSON-LD credential proposal and offer operations |
| tests/unit/proof.test.ts | Adds unit test verifying PEX presentationDefinition passes through correctly |
| tests/integration/e2e.w3c.test.ts | New comprehensive E2E test covering W3C credential issuance from Alice to Bob and PEX-based proof verification by Charlie |
| docs/credentials-and-proofs.md | New comprehensive guide documenting AnonCreds vs W3C credentials, DID methods, and API usage patterns |
| docs/explicit-credential-selection.md | Adds reference to new credentials-and-proofs guide |
| README.md | Adds link to new credentials and proofs documentation |
| package.json | Version bump to 0.17.4, fixes lint:fix script syntax |
Comments suppressed due to low confidence (1)
src/controllers/v1/credentials/CredentialController.ts:258
- The error message assumes the credential format is always AnonCreds, but the endpoint now supports W3C credentials via JSON-LD format as well. When a W3C credential issuance fails, accessing
options.credentialFormats.anoncreds?.credentialDefinitionIdcould be undefined, resulting in a confusing error message like 'credential definition "undefined" not found'. The error message should be updated to handle both credential formats appropriately.
if (error instanceof RecordNotFoundError) {
throw new NotFoundError(
`credential definition "${options.credentialFormats.anoncreds?.credentialDefinitionId}" not found`
)
rmlearney-digicatapult
changed the base branch from
main
to
chore/types-reorg
rmlearney-digicatapult
added
the
v:minor
rmlearney-digicatapult
force-pushed
the
feature/w3c-credential-endpoints
branch
2 times, most recently
from
e9ec57a to
0ce208f
Compare
src/controllers/types/common.ts
Outdated
Comment on lines
32
to
54
|
|
||
| /** | ||
| * Recursive JSON types for TSOA compatibility. | ||
| * Defined locally to avoid TSOA errors with imported specific types. | ||
| * | ||
| * NOTE: The extensive type and interface definitions in this file (specifically explicitly | ||
| * recursive types like ApiJsonObject) are required to satisfy TSOA's schema generation. | ||
| * TSOA struggles with generic 'Record<string, any>' or complex union types imported | ||
| * from @credo-ts/core, often throwing 'Index Type' or 'Reference' errors during spec generation. | ||
| * By defining strict, self-contained recursive structures here, we ensure Swagger/OpenAPI | ||
| * specs are generated correctly. | ||
| * | ||
| * TODO: TSOA v7.0.0-alpha.0 added OpenAPI 3.1 support (PR #1768), effectively supporting | ||
| * variadic tuples and usage of 'prefixItems' for array validation. | ||
| * Once upgraded, we should revisit these recursive types to see if the workaround is still needed. | ||
| */ | ||
| export type ApiJsonValue = string | number | boolean | null | ApiJsonObject | ApiJsonArray | undefined | ||
| export type ApiJsonArray = Array<ApiJsonValue> | ||
| export interface ApiJsonObject { | ||
| [key: string]: ApiJsonValue | ||
| } | ||
|
|
||
| export type GenericRecord = ApiJsonObject |
Contributor
There was a problem hiding this comment.
This is pretty nasty. Essentially we're typing a bunch of objects as "any valid value for JSON". We should have a look at how bad a representation that is compared to the credo types.
Contributor
Author
There was a problem hiding this comment.
Am reworking some of the types but sadly I think there are some non-ideal things we will have to do to make TSOA happy because of type collisions with sphereon-pex within credo-ts
rmlearney-digicatapult
force-pushed
the
feature/w3c-credential-endpoints
branch
from
4a1a24d to
85ac247
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request
Checklist
PR Type
Please delete options that are irrelevant.
Linked tickets
High level description
Enabling W3C credential handling and proof exchange
Detailed description
1. API Endpoint Updates
Typed Controllers:
CredentialControllerandProofControllerupdated to accept W3C types. API now processes requests containing standard credential subjects and proof options, validating them against the new standard before passing them to the agent. Implemented Proof Exchange Version 2 (PEX Version 2)2. TSOA Typing
types.tsexpanded to extract all nested types required for TSOA happiness3. VDRPC Module
Now supports both AnonCreds and PEX
4. E2E Testing
New Test Suite:
e2e.didWeb_w3c.test.tsadded to validate a complete lifecycle: issuing a W3C credential from Alice to Bob over an implicit connection (did document resolution against a did:web), and Charlie successfully requesting and validating a proof using PEXRenamed Test Suite:
e2e.didKey_w3c.test.tssame as above with explicit invitation (OOB) and W3C credential issuanceDescribe alternatives you've considered
Operational impact
Additional context
Needs other PRs merged first to fix test flakiness, rename methods and reorganise
types.tsto simplify review