Ecosystem architecture¶

Level: Intermediate architecture

What you will learn¶

• How the 21 packages relate to each other across five layers
• Which packages to choose for your use case
• How issuer, verifier, wallet, and agent trust components are composed
• What deployment patterns the ecosystem supports

Audience & purpose¶

SD-JWT .NET is a standards-first .NET library ecosystem. This document explains how the ecosystem's packages fit together. Unless explicitly marked Stable, packages are not certification claims or finished external standards.

Context¶

The SD-JWT .NET Ecosystem provides standards-first .NET libraries, protocol components, reference infrastructure, and preview trust extensions for selective disclosure, verifiable credentials, wallet interoperability, and delegated agent trust.

It is not a standalone wallet, identity provider, authorization server, or compliance certification product. It provides reusable implementation building blocks that issuers, verifiers, wallet frameworks, enterprise APIs, and agent systems can build on.

How to read this ecosystem¶

Start from the bottom:

• SdJwt.Net is the cryptographic foundation. It implements SD-JWT per RFC 9901.
• Credential packages define what kind of credential is being carried (SD-JWT VC, mdoc, W3C VCDM).
• Protocol packages define how credentials move between issuer, wallet, and verifier (OID4VCI, OID4VP, Presentation Exchange, Federation).
• Reference packages show how wallet and EUDIW-style infrastructure can be composed.
• Agent Trust packages are preview extensions for agent/tool authorization.

You do not need every package. Choose the smallest set that matches your use case.

Choose by use case¶

Package Role In The Ecosystem¶

System architecture¶

Hub-and-spoke model¶

The ecosystem has one standards core and two major adoption tracks: digital credential / wallet interoperability and preview delegated agent trust.

Layer model¶

The ecosystem is organized into five layers. Each layer depends only on layers below it. This enforces separation of concerns and allows teams to adopt only the layers they need.

Layer descriptions¶

Package dependency graph¶

graph LR
    Core["SdJwt.Net"]

    Vc["SdJwt.Net.Vc"] --> Core
    VcDm["SdJwt.Net.VcDm"] --> Core
    StatusList["SdJwt.Net.StatusList"] --> Core
    Mdoc["SdJwt.Net.Mdoc"] --> Core

    OID4VCI["SdJwt.Net.Oid4Vci"] --> Vc
    OID4VCI --> StatusList
    OID4VP["SdJwt.Net.Oid4Vp"] --> Vc
    OID4VP --> StatusList
    SIOPv2["SdJwt.Net.SiopV2"] --> Core
    PEX["SdJwt.Net.PresentationExchange"] --> Vc
    Fed["SdJwt.Net.OidFederation"] --> Core

    HAIP["SdJwt.Net.HAIP"] --> Core
    Eudiw["SdJwt.Net.Eudiw"] --> Vc
    Eudiw --> Mdoc
    Eudiw --> HAIP
    Wallet["SdJwt.Net.Wallet"] --> Vc
    Wallet --> Mdoc
    Wallet --> StatusList
    Wallet --> OID4VCI
    Wallet --> OID4VP

    ATCore["AgentTrust.Core"] --> Core
    ATPolicy["AgentTrust.Policy"] --> ATCore
    ATAsp["AgentTrust.AspNetCore"] --> ATCore
    ATAsp --> ATPolicy
    ATMaf["AgentTrust.Maf"] --> ATCore
    ATMaf --> ATPolicy
    ATOtel["AgentTrust.OpenTelemetry"] --> ATCore
    ATOpa["AgentTrust.Policy.Opa"] --> ATPolicy
    ATMcp["AgentTrust.Mcp"] --> ATCore
    ATMcp --> ATPolicy
    ATA2A["AgentTrust.A2A"] --> ATCore
    ATA2A --> ATPolicy

    style Core fill:#1b4332,color:#fff
    style HAIP fill:#d62828,color:#fff
    style Eudiw fill:#d62828,color:#fff
    style ATCore fill:#7b2d8e,color:#fff

Component architecture¶

Issuer¶

The issuer creates credentials and manages their lifecycle.

flowchart LR
    subgraph IssuerService["Issuer Service"]
        direction TB
        CredBuilder["Credential Builder"]
        StatusMgr["Status Manager"]
        KeyMgr["Key Manager"]
        Endpoint["OID4VCI Endpoint"]
    end

    CredBuilder --> SdJwtVc["SdJwt.Net.Vc"]
    CredBuilder --> MdocLib["SdJwt.Net.Mdoc"]
    StatusMgr --> StatusList["SdJwt.Net.StatusList"]
    KeyMgr --> HAIP["SdJwt.Net.HAIP"]
    Endpoint --> OID4VCI["SdJwt.Net.Oid4Vci"]

Verifier¶

The verifier validates presented credentials.

flowchart LR
    subgraph VerifierService["Verifier Service"]
        direction TB
        AuthzReq["Authorization Request"]
        VPValidator["VP Token Validator"]
        StatusCheck["Status Checker"]
        TrustCheck["Trust Resolver"]
    end

    AuthzReq --> OID4VP["SdJwt.Net.Oid4Vp"]
    VPValidator --> PEX["SdJwt.Net.PresentationExchange"]
    StatusCheck --> StatusList["SdJwt.Net.StatusList"]
    TrustCheck --> Fed["SdJwt.Net.OidFederation"]
    TrustCheck --> HAIP["SdJwt.Net.HAIP"]

Wallet¶

The wallet stores credentials and creates presentations.

flowchart LR
    subgraph WalletInfra["Wallet Infrastructure"]
        direction TB
        CredStore["Credential Store"]
        FormatPlugin["Format Plugins"]
        ProtocolPlugin["Protocol Plugins"]
        KeyStore["Key Manager"]
    end

    CredStore --> Wallet["SdJwt.Net.Wallet"]
    FormatPlugin --> SdJwtVc["SdJwt.Net.Vc"]
    FormatPlugin --> MdocLib["SdJwt.Net.Mdoc"]
    ProtocolPlugin --> OID4VCI["SdJwt.Net.Oid4Vci"]
    ProtocolPlugin --> OID4VP["SdJwt.Net.Oid4Vp"]
    Wallet --> Eudiw["SdJwt.Net.Eudiw"]

Deployment patterns¶

Pattern 1: single ecosystem¶

Simplest deployment - one organization issues, verifies, and hosts status lists.

flowchart LR
    Issuer["Issuer<br/>(SdJwt.Net.Vc + OID4VCI)"]
    Holder["Holder Wallet<br/>(SdJwt.Net.Wallet)"]
    Verifier["Verifier<br/>(SdJwt.Net.Oid4Vp + PEX)"]
    StatusCDN["Status List CDN"]

    Issuer -->|"1. Issue credential"| Holder
    Holder -->|"2. Present"| Verifier
    Verifier -->|"3. Check status"| StatusCDN
    Issuer -->|"Publish status"| StatusCDN

Packages needed: SdJwt.Net, SdJwt.Net.Vc, SdJwt.Net.StatusList, SdJwt.Net.Oid4Vci, SdJwt.Net.Oid4Vp

Use when: Enterprise issuing employee badges, membership cards, or internal attestations.

Pattern 2: multi-issuer federation¶

Multiple issuers, verified via trust chains.

flowchart TB
    TA["Trust Anchor<br/>(Federation Metadata)"]
    IssuerA["Issuer A<br/>(University)"]
    IssuerB["Issuer B<br/>(Government)"]
    Holder["Holder Wallet"]
    Verifier["Verifier<br/>(Employer)"]

    TA -->|"Trust Chain"| IssuerA
    TA -->|"Trust Chain"| IssuerB
    IssuerA -->|"Diploma"| Holder
    IssuerB -->|"ID card"| Holder
    Holder -->|"Present both"| Verifier
    Verifier -->|"Resolve trust"| TA

Additional packages: SdJwt.Net.OidFederation, SdJwt.Net.PresentationExchange

Use when: Cross-organization verification where issuers and verifiers don't have direct trust.

Pattern 3: high assurance (HAIP regulated)¶

Financial, healthcare, or government systems with strict cryptographic requirements.

Additional packages: SdJwt.Net.HAIP

Configuration: Select the applicable HAIP Final flows (Oid4VciIssuance, Oid4VpRedirectPresentation, or Oid4VpDigitalCredentialsApiPresentation) and credential profiles (SdJwtVc, MsoMdoc). Validate the declared capabilities with HaipProfileValidator, reject weak algorithms, and enforce holder binding where required by the selected profile.

Pattern 4: EUDIW / ARF reference infrastructure¶

Reference infrastructure for EU Architecture Reference Framework concepts.

Additional packages: SdJwt.Net.Eudiw, SdJwt.Net.Mdoc, SdJwt.Net.HAIP

Features: ARF-oriented credential type validation, PID/mDL/QEAA handling, EU trust-list models, RP registration validation, and HAIP Final flow/profile validation.

Pattern 5: AI agent trust¶

M2M capability-based authorization for AI agent ecosystems.

Additional packages: SdJwt.Net.AgentTrust.Core, SdJwt.Net.AgentTrust.Policy, SdJwt.Net.AgentTrust.AspNetCore, SdJwt.Net.AgentTrust.Maf

Features: Per-action scoped tokens, policy engine, delegation chains, audit receipts, replay prevention.

Security architecture¶

Cryptographic controls¶

Key management recommendations¶

Threat model summary¶

Non-goals¶

The ecosystem intentionally does not provide:

• A user-facing wallet app (it provides the library infrastructure)
• An authorization server (use your existing OIDC provider)
• Certificate authority / PKI management (integrate with existing CA)
• Database or storage backends (pluggable interfaces provided)
• HTTP transport / web framework (integrates with ASP.NET Core)

Constraints & assumptions¶

Alternatives considered¶

Related concepts¶

• What SD-JWT .NET Is - and Is Not - Ecosystem boundaries and terminology
• Standards and Maturity Status - Specification and package maturity status
• Capability Matrix - Feature coverage
• Concepts Index - Reading order for deep dives
• Enterprise Roadmap - Strategic phases
• Getting Started - 15-minute quickstart