DidComm.Transports.Http 0.1.0-preview.1

didcomm-dotnet

A spec-complete .NET 10 implementation of DIDComm Messaging v2.1 — the DIF protocol for confidential, integrity-protected, optionally non-repudiable messaging between parties identified by Decentralized Identifiers (DIDs).

DIDComm gives two parties a way to exchange messages whose trust derives from control of DIDs rather than from CAs, IdPs, or transport-level TLS. It is message-based, asynchronous, simplex, and transport-agnostic.

DID resolution is delegated to the sibling library NetDid — didcomm-dotnet implements only the messaging layer (message model, JOSE envelopes, routing, threading, OOB, and the protocols defined directly in the spec).

Project status

Phases 0 – 6 complete. The library has a public Pack / Unpack / Send surface (DidCommClient), DID resolution via NetDid 1.3.0, a consumer-supplied ISecretsResolver contract, the three protective envelope shapes (signed / anoncrypt / authcrypt) and their legal compositions, addressing consistency including the FR-CONSIST-06 resolver-backed authorization check, DID rotation via from_prior, Routing Protocol 2.0 (sender forward wrapping

• mediator relay + rewrapping), and the HTTPS / WebSocket transports plus the ASP.NET Core receive endpoint. Phase 6 adds threading / ACKs / i18n / profiles and all the spec's built-in protocols — Trust Ping, Discover Features, Empty, Report Problem, Trace (off by default), and Out-of-Band 2.0. The DIDComm v2.1 Appendix C inbound interop gate passes for every vendored vector.

Shipped highlights:

• Public facade — services.AddDidComm(b => …) → Pack{Plaintext,Signed,Encrypted}Async + UnpackAsync + SendAsync. Auto-detects envelope shape on unpack, enforces FR-API-05 (expires_time) and FR-API-06 (MaxReceiveBytes), surfaces FR-API-04 metadata on every unpack.
• DID resolution via the NetDidKeyService adapter over net-did (did:key, did:peer); JWK + Multikey verification methods both supported; did:web deliberately refused at every entry point with UnsupportedDidMethodException (DD-08).
• DID rotation — Message.FromPrior carries a JWT validated against the prior DID's authentication relationship; FR-ROT-03 enforced (rotation messages MUST be encrypted).
• Routing & mediation — PackEncryptedAsync(... Forward: true) resolves the recipient's DIDCommMessaging service (object / array-of-objects / opt-in DD-10 bare-string), implicitly prepends mediator keyAgreement keys (FR-ROUTE-04), reverse-order anoncrypt-wraps a forward per routing key, and surfaces the transport URI on PackEncryptedResult.ServiceEndpoint. ForwardProcessor handles the mediator side with optional rewrapping (FR-ROUTE-05/06).
• Transports — DidCommClient.SendAsync(...) packs and dispatches via an ITransportRouter. DidComm.Transports.Http ships a Polly-backed HTTPS sender (FR-TRN-04..08); DidComm.Transports.WebSocket ships a one-message- per-envelope WS sender with connection pool + exponential reconnect (FR-TRN-09..11). DidComm.AspNetCore provides MapDidCommEndpoint / MapDidCommWebSocket minimal-API extensions — Content-Type validation ⇒ 415, MaxReceiveBytes ⇒ 413 / 1009 (FR-TRN-07 + FR-API-06).
• Built-in protocols — every protocol the spec defines directly: Trust Ping 2.0, Discover Features 2.0, Empty 1.0, Report Problem 2.0 (taxonomy + interpolation + escalation + cascade guard), Trace 2.0 (off by default), and Out-of-Band 2.0 (OutOfBand.CreateInvitation / ToUrl / FromUrl, short-form ?_oobid= retrieval, web_redirect).
• Cookbook — runnable, narrated samples for the PRD §14.2 API tasks: K (unpack metadata), M (threading & ACKs), N (rotation), O (routing via a mediator), P (send over a transport), Q (receive over HTTP), R (receive over WebSocket), S (Trust Ping), T (Discover Features), U (Report Problem), V (Out-of-Band invitation), W (Empty message), X (custom handler), AA (net-did + did:web rejection), BB (profiles & i18n). Build the project and dotnet run --project samples/02-Cookbook to see end-to-end output.

576 unit + 96 interop tests pass under warnaserror. See CHANGELOG.md for the per-phase log, the PRD for normative requirements (the six-phase plan is §12), and the roadmap below for status at a glance.

Install

didcomm-dotnet ships as focused NuGet packages (hybrid packaging, DD-03) — the core plus one package per transport and integration:

# The first release is a prerelease (0.1.0-preview.1), so pass --prerelease until a stable tag:
dotnet add package DidComm.Core --prerelease
dotnet add package DidComm.Extensions.DependencyInjection --prerelease

The release pipeline (.github/workflows/release.yml) packs all packages (with symbols + SourceLink) and pushes them to NuGet.org on a vMAJOR.MINOR.PATCH tag. The first version (0.1.0-preview.1) has not been tagged/published yet — until then, build from source. Maintainers: see RELEASING.md for the publish runbook.

What "spec-complete" means

didcomm-dotnet v1.0 will implement, in full, the messaging layer of DIDComm Messaging v2.1:

did:web is explicitly NOT supported. This is a deliberate security policy (DD-08), not a messaging-conformance gap. See PRD §1.1 and §15.

The conformance gate is the spec's own Appendix C test vectors plus a live cross-implementation harness round-tripping against the SICPA reference implementations in Python, JVM, and Rust.

Package map

Built today

Planned (later phases)

Naming convention

The repository is didcomm-dotnet (kebab-case, matching net-did and zcap-dotnet). .NET assemblies, NuGet packages, and namespaces use the PascalCase root DidComm (e.g. DidComm.Core, DidComm.Transports.Http). The acronym "DIDComm" from the spec is rendered DidComm in code per .NET capitalization guidelines for 3+ letter acronyms (matching NetDid). Prose references to the protocol keep the spec spelling "DIDComm".

Public API at a glance

The signatures below are what ships today in DidComm.Core + DidComm.Extensions.DependencyInjection.

// The facade — DidComm.Facade.DidCommClient
public sealed class DidCommClient
{
    public Task<string>              PackPlaintextAsync(Message m,                              CancellationToken ct = default);
    public Task<string>              PackSignedAsync(Message m, string signFrom,                CancellationToken ct = default);
    public Task<PackEncryptedResult> PackEncryptedAsync(Message m, PackEncryptedOptions opts,   CancellationToken ct = default);
    public Task<SendResult>          SendAsync(Message m, SendOptions opts,                     CancellationToken ct = default);
    public Task<UnpackResult>        UnpackAsync(string packed,                                 CancellationToken ct = default);
}

// DID resolution adapter — DidComm.Resolution
public interface IDidKeyService
{
    Task<IReadOnlyList<Jwk>> GetVerificationMethodsAsync(string did, VerificationRelationship rel, CancellationToken ct = default);
    Task<bool>               IsKeyAuthorizedAsync(string did, string kid, VerificationRelationship rel, CancellationToken ct = default);
    void                     RejectUnsupportedMethod(string did);  // throws UnsupportedDidMethodException for did:web
}

// Consumer-supplied secrets (KMS / HSM / Vault) — DidComm.Secrets
public interface ISecretsResolver
{
    Task<Jwk?>                  FindAsync(string kid,                       CancellationToken ct = default);
    Task<IReadOnlyList<string>> FindPresentAsync(IEnumerable<string> kids,  CancellationToken ct = default);
}

// Transport binding (Phase 5) — DidComm.Transports
public interface IDidCommTransport
{
    string                Scheme { get; }
    bool                  CanHandle(Uri endpoint);
    Task<TransportResult> SendAsync(TransportRequest request, CancellationToken ct);
}

// DI wiring — DidComm.Extensions.DependencyInjection
services.AddDidComm(b =>
{
    b.UseNetDidResolver();                     // did:key + did:peer via net-did
    b.UseSecretsResolver<MyVaultResolver>();   // FR-SEC-02 fail-fast if absent
    b.UseHttpTransport();                      // FR-TRN-04..08 (Polly resilience)
    b.UseWebSocketTransport();                 // FR-TRN-09..11
    b.Configure(o => o.MaxReceiveBytes = 1 * 1024 * 1024);
});
var client = sp.GetRequiredService<DidCommClient>();

// Server side — DidComm.AspNetCore
app.MapDidCommEndpoint("/didcomm",      async (unpacked, ct) => { /* host dispatch */ });
app.MapDidCommWebSocket("/ws/didcomm",  async (unpacked, ct) => { /* host dispatch */ });

The runnable samples/02-Cookbook project demonstrates each shipped API task — the README at that path documents the §14.2 letter mapping (K, M, N, O, P, Q, R, S, T, U, V, W, X, AA, BB through the Phase 6 increment).

Specifications

Roadmap

didcomm-dotnet is delivered in six phases (see PRD §12 for the full plan, exit criteria, and per-phase agent kickoff prompts):

The conformance bar is binary: MUST requirements implemented, full Appendix C vector suite passes, cross-implementation interop matrix passes (both inbound static vectors and live round-trip against SICPA Python/JVM/Rust), every public API member demonstrated by a runnable sample, and the README quickstart works unmodified.

Repository layout

didcomm-dotnet/
├── src/
│   ├── DidComm.Core/                              # message model, envelopes, facade, resolution, secrets, rotation, routing, transport abstractions
│   ├── DidComm.Extensions.DependencyInjection/    # services.AddDidComm(b => …)
│   ├── DidComm.Adapters.NetDid/                   # optional NetDid.IKeyStore → ISecretsResolver bridge
│   ├── DidComm.Transports.Http/                   # Polly-backed HTTPS sender (FR-TRN-04..08)
│   ├── DidComm.Transports.WebSocket/              # WebSocket sender with pool + reconnect (FR-TRN-09..11)
│   ├── DidComm.AspNetCore/                        # MapDidCommEndpoint / MapDidCommWebSocket (FR-TRN-07/09/10)
│   └── DidComm.Protocols.*/                       # (Phase 6)
├── tests/
│   ├── DidComm.Core.Tests/                        # 576 unit tests
│   ├── DidComm.InteropTests/                      # 63 cases: Appendix C vectors + Appendix B resolution + facade round-trip + rotation + routing + transports + Cookbook smoke
│   └── DidComm.TestSupport/                       # InMemorySecretsResolver helper (non-test library)
├── samples/
│   ├── _shared/                                   # Narrator + PeerIdentityFactory (did:peer:2 via NetDid)
│   └── 02-Cookbook/                               # PRD §14.2 sections K, N, O, P, Q, R, AA today; grows with each phase
├── docs/
│   └── didcomm-dotnet_PRD.md                      # normative product requirements
├── tasks/                                         # phased todo files + lessons.md
├── Directory.Build.props
├── Directory.Packages.props
└── DidComm.sln

The Phase 2 fixtures submodule migration (planned at PRD §13.3) is still pending — Appendix A / B / C vectors currently live inline under tests/DidComm.InteropTests/fixtures/. They'll move to a dedicated didcomm-dotnet-fixtures repo before Phase 6 closes.

Contributing

didcomm-dotnet welcomes contributions. The PRD is the source of truth for what to build; contributors should read it before opening non-trivial PRs. See CONTRIBUTING.md for setup, code conventions, and the phased delivery model.

If you're filing an issue or PR for a specific requirement, please reference its ID (e.g. FR-ENC-13) — the PRD is structured so that traceability stays tight.

Security

didcomm-dotnet handles cryptographic key material and implements security-critical primitives (JWE, JWS, ECDH-1PU, AES-CBC-HMAC). If you discover a vulnerability, do not open a public issue. See SECURITY.md for the responsible-disclosure process.

Code of Conduct

This project follows the Contributor Covenant. By participating, you agree to uphold its terms.

Related projects

• NetDid — W3C DID Core 1.0 implementation; provides DID resolution to didcomm-dotnet
• zcap-dotnet — Authorization Capabilities (ZCAP-LD) for .NET

License

Licensed under the Apache License 2.0. See also NOTICE.