Skip to content

feat: DIDComm v2 support#2698

Closed
tarunvaddeSoul wants to merge 33 commits intoopenwallet-foundation:mainfrom
tarunvaddeSoul:feat/didcomm-v2-upgrade
Closed

feat: DIDComm v2 support#2698
tarunvaddeSoul wants to merge 33 commits intoopenwallet-foundation:mainfrom
tarunvaddeSoul:feat/didcomm-v2-upgrade

Conversation

@tarunvaddeSoul
Copy link
Copy Markdown
Contributor

@tarunvaddeSoul tarunvaddeSoul commented Mar 12, 2026 •
edited
Loading

Changes

  • v2 envelope: ECDH-1PU+A256KW (authcrypt), A256GCM, JWE application/didcomm-encrypted+json
  • v2 key resolution, plaintext building, v2→v1 normalization for existing handlers
  • Config: didcommVersions: ['v1', 'v2'] and connection.didcommVersion for version selection
  • OOB v2 (spec): no-handshake connection setup
  • KMS: ECDH-1PU support (Askar, Node)
  • Connection request/response remain v1
  • BasicMessage 2.0 (spec): works over v1 and v2 envelopes; basicMessages.protocols: ['1.0', '2.0'] for protocol selection; toV2Plaintext() for v2 packing

Known gaps

  • Message Pickup and Mediation stay v1-only (assertDidCommV1Connection)

Demo

  • Updated for DIDComm v2 and BasicMessage 2.0

tarunvaddeSoul and others added 25 commits February 17, 2026 16:41
@tarunvaddeSoul
feat(didcomm): add DIDComm v2 support
c6f2233 
- DIDComm v2 envelope service with ECDH-1PU+A256KW and ECDH-ES
- OOB 2.0 and DidCommOutOfBandInvitationV2
- DidCommV2Service in DID document resolution
- Peer DID num algo 2 recipient key fingerprint support for v2
- acceptDidCommV2, sendDidCommV2, autoCreateConnectionOnFirstMessage config
- Demo scripts alice:v2 and faber:v2

Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
fix(didcomm): improve DIDComm v2 connectionless and key resolution
089ecc9 
- Use did:key for skid/kid so recipients can resolve via tryParseKidAsPublicJwk
- Fix Ed25519/X25519 fingerprint matching in DID exchange and OOB receiver lookup
- Support NewDidCommV2Service (DIDCommMessaging) in document resolution
- Default acceptDidCommV2 and sendDidCommV2 to true
- Guard Ed25519->X25519 conversion against invalid key bytes

Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
feat(didcomm): support did:peer:4 in message sender recipient key res…
ff950c2 
…olution

- Extend peer DID fallback to did:peer:4 long form (in addition to did:peer:2)
- Apply fallback for both requester and responder when recipient keys are empty
- Export didToNumAlgo4DidDocument from core for peer DID parsing
- Use NewDidCommV2Service type for v2 service handling

Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
fix(didcomm): type assertion and refactor key validation
a34bceb 
- Add recipientKeys type assertion in DidCommMessageSender peer DID fallback
- Extract toX25519 helper in DidCommDidExchangeResponseHandler for cleaner Ed25519/X25519 validation

Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
Merge branch 'openwallet-foundation:main' into feat/didcomm-v2-upgrade
f17d44e
@tarunvaddeSoul
chore: readd the removed comments in KmsEncryptOptions
c04516c 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
refactor: switch to DidCommHandshakeProtocol.DidExchange in tests
10669d6 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
chore: version change
432d0d7 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
refactor: remove anoncrypt senderKey validation in DidCommConnectionR…
952794f 
…e*Handlers

Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
refactor: move frequent type assertions to toX25519
4b04033 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
fix: stop registering non-resolvable didcomm/v2 in discover-features
1716a73 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
revert: restore .gitignore to previous state
53b3c9c 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
chore: keep DIDComm V2 as false by default
7da07d3 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
chore: Removed legacy base64url conversion code as it's no longer needed
c7f9cbd 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
chore: reset setup.ts
d03792b 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
chore: reset @stablelib/ed25519 version in indy-vdr package.json
f3e2192 
Signed-off-by: Tarun Vadde <tarun@soulverse.us>
@tarunvaddeSoul
Merge branch 'openwallet-foundation:main' into feat/didcomm-v2-upgrade
9d521cc
@tarunvaddeSoul
chore: update DIDCommV2* interface with additional fields
0ab8cd7 
Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
Merge branch 'openwallet-foundation:main' into feat/didcomm-v2-upgrade
54aa940
@tarunvaddeSoul
refactor(didcommv2): update normalize.ts to also consider attachments…
53d6209 
… and timing

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
refactor(didcommv2): update plaintextBuilder.ts to consider attachmen…
de6541c 
…ts and time while building V2 plain text

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
test: update normalize.test
e2938a3 
Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
test: add tests for plaintextBuilder for DIDComm V2
f74dbcc 
Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
Merge branch 'openwallet-foundation:main' into feat/didcomm-v2-upgrade
90f5336
@tarunvaddeSoul
refactor(didcomm)!: refactor DIDComm v2 support
043b167 
Protocol and message version restrictions:
- Add supportedDidCommVersions to message types; restrict Message Pickup
  and Mediation to v1 connections
- Enforce version compatibility in DidCommMessageSender

Module and API configuration:
- Replace acceptDidCommV2/sendDidCommV2 with didcommVersions array
  (default ["v1"])
- Add peerDidNumAlgoForV2OOB; default to did:peer:4, support did:peer:2
  for legacy deployments
- Add optional didcommVersion to DidCommConnectionRecord (default v1);
  outbound envelope version derived from connection

V2 envelope and conversion:
- Add v2 OOB invitations with optional ourDid for stable connection lookup
- Support decorators (e.g. threading) in v1/v2 conversion (normalize,
  plaintextBuilder)

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul tarunvaddeSoul requested a review from a team as a code owner March 12, 2026 12:43
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Mar 12, 2026 •
edited
Loading

⚠️ No Changeset found

Latest commit: 67089fd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

TimoGlastra
TimoGlastra reviewed Mar 12, 2026
View reviewed changes
TimoGlastra
TimoGlastra reviewed Mar 12, 2026
View reviewed changes
@tarunvaddeSoul
chore(demo): remove unused env var and logger
647fe4b 
Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
tarunvaddeSoul and others added 4 commits March 16, 2026 10:01
@tarunvaddeSoul
Merge branch 'main' into feat/didcomm-v2-upgrade
22e4d32 
Signed-off-by: Tarun Vadde <142969534+tarunvaddeSoul@users.noreply.github.com>
@tarunvaddeSoul
fix: typo in PeerDidRegistrar.ts
83ce0d5 
Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
feat(didcomm): add BasicMessage 2.0 protocol support
a445cc7 
Add support for BasicMessage 2.0 (https://didcomm.org/basicmessage/2.0/)
over both DIDComm v1 and v2 envelopes, per spec.

- Add DidCommBasicMessageV2 message class with toV2Plaintext() for v2 packing
- Add BasicMessageV2Handler and DidCommBasicMessageService.createMessageV2/saveV2
- Extend DidCommBasicMessagesModuleConfig with protocols: ['1.0' | '2.0']
- When protocols includes 2.0, DidCommBasicMessagesApi uses BM 2.0
- BM 2.0 fields: content, created_time (Unix epoch), optional lang
- BM 2.0 works over v1 envelope (v1-style plaintext) and v2 envelope (body, type, id)
- Add DidCommBasicMessageV2StateChanged event for received BM 2.0 messages
- plaintxtBuilder uses toV2Plaintext() for messages that implement it

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
Merge branch 'main' into feat/didcomm-v2-upgrade
13e1737
tarunvaddeSoul and others added 3 commits March 18, 2026 00:50
@tarunvaddeSoul
feat(didcomm): add Message Pickup 3.0 protocol (DIDComm v2)
655ab0f 
Implement Message Pickup protocol 3.0 per https://didcomm.org/messagepickup/3.0/
for DIDComm v2 connections (mediation 2.0, pickup v3).

Protocol:
- Add DidCommMessagePickupV3Protocol with PIURI https://didcomm.org/messagepickup/3.0
- Message types: status-request, status, delivery-request, delivery,
  messages-received, live-delivery-change (all with return_route: all)
- Handlers: StatusRequestV3, StatusV3, DeliveryRequestV3, MessageDeliveryV3,
  MessagesReceivedV3, LiveDeliveryChangeV3
- Optional recipient_did in status-request/delivery-request; required limit
  in delivery-request; base64 attachments in delivery; message_id_list in
  messages-received

API and module:
- DidCommMessagePickupApi: pickupMessages, setLiveDeliveryMode, deliverMessages,
  deliverMessagesFromQueue with protocolVersion 'v3' and recipientDid for v3
- DidCommMessagePickupModule registers DidCommMessagePickupV3Protocol
- Pickup v3 restricted to DIDComm v2 (assertDidCommV2Connection)

Live mode:
- processLiveDeliveryChange saves/removes live session by sessionId; responds
  with status including live_delivery and message_count
- When live_delivery is true on non-persistent transport (no sessionId), send
  problem report with code e.m.live-mode-not-supported per spec

Tests:
- protocol/v3/__tests__/pickup-v3-protocol.test.ts for v3 protocol and
  live-delivery-change (including problem report when sessionId missing)
- Existing pickup/MessagePickupApi/MessagePickupModule tests unchanged

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
feat(didcomm): implement Coordinate Mediation 2.0 routing coordination
c4236a8 
Add full Coordinate Mediation 2.0 support in Credo-ts, including mediator/recipient coordination,
key registration, and routing behavior aligned with DIF messaging expectations.

- Introduce Coordinate Mediation 2.0 message types and models:
  mediate-request, mediate-grant, mediate-deny, keylist-update, keylist-update-response,
  keylist-query, and keylist
- Implement mediator-side services and handlers for:
  processing Forward (routing 2.0/forward) and coordinating delivery strategies,
  handling keylist updates/queries, and emitting state/keylist events
- Implement recipient-side services and handlers for:
  provisioning mediation v2, awaiting grants, and issuing keylist updates (v2)
- Update routing/mediation integration paths used by DIDComm v2 sender/receiver flow
  (including v2 routing DID and Forward message handling)
- Add/extend tests covering mediation v2 messaging + message pickup v3 interoperability
- Update Drizzle storage adapters and mediation record typing to support mediation v2 fields

Signed-off-by: Tarun Vadde <vaddeofficial@gmail.com>
@tarunvaddeSoul
Merge branch 'main' into feat/didcomm-v2-upgrade
67089fd
@genaris genaris mentioned this pull request Mar 18, 2026
Open
@genaris
Copy link
Copy Markdown
Contributor

genaris commented Mar 18, 2026

@tarunvaddeSoul this PR has been closed in favour of #2704 which uses a local branch and allows to create PR-releases to test before merging. You can create new PRs targetting feat/didcomm-v2 branch until we are able to merge to main this initial work.

@genaris genaris closed this Mar 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@TimoGlastra TimoGlastra TimoGlastra left review comments

Assignees

No one assigned

Labels

alpha-release

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@tarunvaddeSoul @genaris @TimoGlastra