Skip to content

Concepts & Architecture

Audience & Purpose
Audience Developers, architects, and security engineers working with the SD-JWT .NET ecosystem
Purpose Understand the architecture, design decisions, and technical details of each component
Scope All implemented packages and their interactions
Success Reader understands how components fit together and can make informed design decisions

Reading Order

Start with the ecosystem architecture, then dive into the specific area you need.

1. Ecosystem Overview

Document Topic Read Time
What This Project Is Ecosystem boundary and terminology 10 min
Ecosystem Architecture Master architecture, package map, deployment patterns 20 min
Selective Disclosure Mechanics How salts, hashes, and key binding work 10 min

2. Core Credential Formats

Document Topic Read Time
SD-JWT RFC 9901 token format, issuance, presentation, verification 25 min
Verifiable Credential SD-JWT VC profile, claims, lifecycle 15 min
W3C VCDM W3C Verifiable Credentials Data Model 2.0 15 min
mdoc ISO 18013-5 CBOR/COSE structures, mDL 20 min

3. Protocols

Document Topic Read Time
OpenID4VCI Credential issuance protocol 20 min
OpenID4VP Presentation protocol 20 min
Presentation Exchange DIF PEX query language 15 min
DC API W3C Digital Credentials API 15 min

4. Trust, Status & Assurance Profiles

Document Topic Read Time
Status List Revocation, suspension, status checking 15 min
HAIP High Assurance Interoperability Profile 15 min
HAIP Profile Validation Guide Integration guide and policy engine 15 min

5. Reference Infrastructure

Document Topic Read Time
Wallet Generic wallet architecture and plugin model 20 min
EUDIW EUDIW / ARF reference infrastructure 20 min

6. Preview Trust Extensions (Agent Trust)

Document Topic Read Time
Agent Trust Profile Capability tokens, threat model, concepts 15 min
Agent Trust Kits Package map and architecture overview 15 min
MCP Trust Interceptor MCP client/server trust guard 10 min
ASP.NET Core Middleware Inbound HTTP verification 5 min
Agent-to-Agent Delegation Delegation chains and bounded authority 10 min
Agent Trust Operations Deployment, telemetry, nonce, key custody 10 min
Agent Trust Governance OWASP, EU AI Act, NIST AI RMF mapping 5 min

Architecture at a Glance

graph TB
    subgraph Application["Application Layer"]
        Issuer["Issuer Service"]
        Verifier["Verifier Service"]
        WalletApp["Wallet App"]
        AgentRuntime["Agent Runtime"]
    end

    subgraph Protocol["L3: Protocol & Interoperability"]
        OID4VCI["SdJwt.Net.Oid4Vci"]
        OID4VP["SdJwt.Net.Oid4Vp"]
        SIOPv2["SdJwt.Net.SiopV2"]
        PEX["SdJwt.Net.PresentationExchange"]
        Fed["SdJwt.Net.OidFederation"]
    end

    subgraph Credential["L2: Credential Formats, Status & Assurance Profiles"]
        Vc["SdJwt.Net.Vc"]
        Status["SdJwt.Net.StatusList"]
        Mdoc["SdJwt.Net.Mdoc"]
        VcDm["SdJwt.Net.VcDm"]
        HAIP["SdJwt.Net.HAIP"]
    end

    subgraph Core["L1: Core"]
        SdJwt["SdJwt.Net (RFC 9901)"]
    end

    subgraph RefPreview["L4: Reference Infrastructure & Trust Extensions"]
        Wallet["SdJwt.Net.Wallet"]
        Eudiw["SdJwt.Net.Eudiw"]
        ATCore["AgentTrust.Core"]
        ATPolicy["AgentTrust.Policy"]
        ATAsp["AgentTrust.AspNetCore"]
        ATMaf["AgentTrust.Maf"]
        ATOTel["AgentTrust.OpenTelemetry"]
        ATOpa["AgentTrust.Policy.Opa"]
        ATMcp["AgentTrust.Mcp"]
        ATA2A["AgentTrust.A2A"]
    end

    Issuer --> OID4VCI
    Verifier --> OID4VP
    Verifier --> PEX
    WalletApp --> Wallet
    AgentRuntime --> ATMaf

    OID4VCI --> Vc
    OID4VCI --> Status
    OID4VP --> Vc
    OID4VP --> Status
    SIOPv2 --> SdJwt
    Fed --> SdJwt

    Vc --> SdJwt
    Status --> SdJwt
    Mdoc --> SdJwt
    VcDm --> SdJwt
    HAIP --> SdJwt

    Wallet --> Vc
    Wallet --> Mdoc
    Wallet --> OID4VCI
    Wallet --> OID4VP
    Eudiw --> Vc
    Eudiw --> Mdoc
    Eudiw --> HAIP

    ATCore --> SdJwt
    ATPolicy --> ATCore
    ATAsp --> ATCore
    ATMaf --> ATCore
    ATOTel --> ATCore
    ATOpa --> ATPolicy
    ATMcp --> ATCore
    ATA2A --> ATCore

    style SdJwt fill:#1b4332,color:#fff
    style HAIP fill:#2a6478,color:#fff
    style Mdoc fill:#2a6478,color:#fff
    style ATCore fill:#7b2d8e,color:#fff