Skip to main content
Version: v0.21.0

Process Flows

This document describes the key protocol flows implemented by the TSG Wallet, showing how W3C and other standards are applied in practice for credential and identity operations.

Note: These flows represent the Wallet's implementation of standard protocols. For system-wide data space flows, see the Architecture Documentation.

Core Wallet Flows​

The Wallet implements several key protocol flows that form the foundation of data space identity operations:

Authentication flow​

The authentication flows are either between the wallet and the UI or the wallet and an external system within the same security domain of the wallet.

Frontend​

External system​

Verifiable Presentation verification flow​

Issuance flow​

This flow describes the process of exchanging a new credential between two Wallet instances

Presentation protocols​

Different protocols for exchanging Verifiable Presentations between the holder of credentials and the verifier can be used in different scenarios.

The Wallet implements these presentation exchange protocols:

  • Eclipse Decentralized Claims Protocol: a protocol providing a machine-to-machine interface for exchanging Verifiable Presentations
  • OpenID for Verifiable Presentations: interactive presentation exchange

Eclipse Decentralized Claims Protocol (DCP)​

The Eclipse Decentralized Claims Protocol (DCP) defines protocols for credential issuance and presentation. The TSG Wallet implements the Eclipse DCP Presentation Protocol for exchanging Verifiable Presentations. The foundational standards used in this protocol are:

The sequence diagram below shows the interactions between the wallets and external systems of the verifier and holder. Routes are relative to each Wallet's deployed API base (for example /api in an embedded Docker deployment). Local management calls select a tenant with X-Tenant-Slug or X-Tenant-Id and use managed credentials bound to the canonical organization and Wallet audience. Peer DCP calls discover the holder's CredentialService from its DID document.

The exchange works as follows:

  1. The holder's local application calls GET /management/dcp/holder/token with the verifier DID as audience and an optional space-separated scope. The Wallet signs a self-issued ID token and creates the presentation access token embedded in it. A supplied scope restricts the credentials available to a later presentation query.
  2. The application sends the ID token as a bearer token with its request to the external verifier, such as a Control Plane DSP request.
  3. The verifier calls its Wallet's POST /management/dcp/verifier/verify with holderIdToken and exactly one of presentationDefinition or scope. Scope aliases normally resolve to a presentation definition in the verifier's Wallet. Explicit queryMode: scope instead forwards the scopes to the holder.
  4. The verifier Wallet validates the holder token, resolves its DID document and finds the CredentialService. It signs a verifier token addressed to the holder, containing the holder-issued access token.
  5. It posts a PresentationQueryMessage to the service's /presentations/query endpoint. The message contains exactly one of a presentation definition or scopes; its bearer token is the verifier's self-issued token.
  6. The holder validates the verifier token and access token. Token scopes, when present, restrict which credentials a definition can match. A scope query is limited to scopes authorized by the access token; a query with no authorized scopes returns 403. Matching complete credentials are signed into presentations.
  7. The holder returns a PresentationResponseMessage. The verifier validates its presentations, holder binding and requested query constraints, then returns the verified presentations to its local caller. The external system decides whether to authorize the original request.

The selected Wallet tenant's lifecycle and authorization also apply to protected operations. Public tenant paths identify the recipient; they do not replace the protocol's token and proof checks.

Credential status protocols​

BitstringStatusList​

The TSG Wallet has support for the Bitstring Status List v1.0 that allows for providing dynamic statuses for credentials from the perspective of the issuer.

The current implementation supports the revocation status purpose for credentials of which the TSG Wallet is the issuer. For credentials issued by external wallet implementations, the TSG Wallet has support to additionally evaluate refresh, suspension, and message purposes.