Decentralized Credential Exchange (DCX)

Package Versions

Name	Latest Version
@formfree/dcx

Decentralized Credential Exchange (DCX) is a new DWeb Node (DWN) procotol proposal (implemented as a npm package) with the purpose of facilitating the decentralized exchange of credentials between applicants, issuers and data providers. is both a protocol and a software package. The DCX protocol defines a process for verifiable credential exchange between user agents and issuers via DWN protocols. The DCX package is a FOSS npm package that implements the protocol in addition to a "credentials in, credentials out" asynchronous web server that manages protocol interactions between user agents and DWN servers. The goal of this project is to implement a well documented, abstractly designed npm package and merge it into the Web5 monorepo under the name @web5/dcx, so developers can npm install @web5/dcx into any javascript/typescript project and run a DCX server to participate in the DCX protocol.

Package

The DCX package is a FOSS npm package used to bootstrap running a DCX issuer server. The package handles the connection between the DCX server and its corresponding DWN server and provides the following functionality:

1. DCX to DWN server connection - asynchronous communication between issuers and applicants
2. DCX to DHT gateway connection - asynchronous communication between issuers and DHT gateways
3. DID DHT key management - import/export/create DID DHT keys
4. DCX protocol & handlers - integrated with api handlers to facilitate required interactions with DWNs and 3rd parties

Protocol

The DCX protocol is open and permissionless leveraging the benefits of DWNs, Verifiable Credentials (VCs) and many other powerful Web5 primitives. As mentioned above, the protocol is designed to facilitate the decentralized exchange of credentials between applicants, issuers and data providers; more specifically, DCX interacts with applicant and issuer DWNs performing CRUD operations on DWN Records. Different types of DWN record schemas are defined to represent different messages being sent to/from different actors. These records contain informatino about the VCs required as inputs to the DCX server to received as outputs different VCs.

Credential Manifests are a big part of what makes DCX work. These documents outline key pieces of information:

1. The input credentials required by the issuer
2. The output credential(s) the applicant can expect
3. Data formatting preferences

Credential Manifests are a resource format that defines preconditional requirements, Issuer style preferences, and other facets. User Agents utilize to help articulate and select the inputs necessary for processing and issuance of a specified credential.

A Credential Manifest is a document, hosted by an Issuer and consumed by User Agents, codifying the credentials that it issues in terms of pre-requisites and inputs. These can be static or dynamic, but their form and usage are detailed in this specification.

Applicants pull these manifest records from the issuer's DWN, so they can understand what VCs are required on their side of the exchange. For more details on protocol interactions between issuers and applicants, see the diagrams in the Architecture and Sequence sections below.

The DCX protocol and its varying schemas can be found below:

Protocol

• src/protocol/credential-issuer.ts defines credential issuer protocol
• src/protocol/credential-applicant.ts defines credential applicant protocol

Protocol Schemas

• src/protocol/schemas/invoice.ts defines the schema for invoice records
• src/protocol/schemas/manifest.ts defines schema for manifest records
• src/protocol/schemas/application.ts defines schema for application records
• src/protocol/schemas/response.ts defines schema for response records

Protocol Manifests

• src/protocol/manifests/EXAMPLE-MANIFEST.json defines an example manifest
• NOTE: Manifests do not ship with the DCX package. Developers are required to provide their own manifests when building their DCX issuer server

Architecture

Actors

• DCX: Protocol boundary within which actors communicate
• DCX Issuer: Web server running @web5/dcx and web5-js
• Issuer DWN: DCX Issuer's DWN server running dwn-sdk-js
• DCX Applicant: User client application running @web5/dcx and web5-js
• Applicant DWN: DCX Applicant's DWN server running dwn-sdk-js

Packages

• web5-js
• @web5/dcx
• dwn-sdk-js

Sequence

Full Sequence

1. DCX Issuer configures Issuer DWN with dcx protocol: credential-issuer and credential-applicant
2. DCX Issuer creates credential manifest record in Issuer DWN
3. DCX Issuer creates subscription to Issuer DWN
4. DCX Applicant creates subscription to Applicant DWN
5. DCX Applicant reads credential manifest record from Issuer DWN
6. DCX Applicant acquires required credentials from issuers listed in manifest
7. DCX Applicant creates application record in Issuer DWN
8. DCX Issuer reads application record via Issuer DWN subscription
9. DCX Issuer uses @web5/dcx to verify application record credentials against credential manifest
10. DCX Issuer creates response record in Applicant DWN
11. DCX Applicant reads response record via Applicant DWN subscription
12. DCX Issuer creates invoice record in Applicant DWN
13. DCX Applicant reads invoice record via Applicant DWN subscription

Notes:

1. Credential-issuer and credential-applicant protocols defines DWN record CRUD actions between Issuer and Applicant
2. under the credential-issuer manifest route
3. Subscription to receive incoming application records
4. Subscription to receive incoming response records
5. Defines required "credentials in" to receive desired "credentials out"
6. Credentials are acquired separately, outside of DCX protocol, from listed trusted issuers
7. Application record includes credentials that satisfy credential manifest mentioned in step 5
8. DCX Issuer validates credentials against credential manifest using DCX software handlers

Issuer Sequence

1. DCX Issuer configures Issuer DWN with dcx protocol (issuer & applicant)
2. DCX Issuer creates credential manifest record in Issuer DWN
3. DCX Issuer creates subscription to Issuer DWN
4. DCX Issuer reads application record via Issuer DWN subscription
5. DCX Issuer uses DCX software handlers to verify credentials against credential manifest
6. DCX Issuer configures DWN with DCX Issuer protocol
7. DCX Issuer creates DWN manifest record in own DWN to define required credentials to obtain other credentials
8. DCX Issuer subscribes to own DWN to listen for application records
9. DCX Issuer reads an incoming application record and validates against respective credential manifest
10. DCX Issuer creates application response or denial record and sends to applicant DWN
11. DCX Issuer creates invoice response record and sends to applicant DWN

Applicant Sequence

1. DCX Applicant configures Applicant DWN with dcx protocol (issuer & applicant)
2. DCX Applicant creates subscription to Applicant DWN
3. DCX Applicant reads credential manifest record from Issuer DWN
4. DCX Applicant acquires required credentials from issuers listed in manifest
5. DCX Applicant creates application record in Issuer DWN
6. DCX Applicant reads response record via Applicant DWN subscription
7. DCX Applicant reads invoice record via Applicant DWN subscription (optional)

Use

// issuer side
import {
  credentialIssuerProtocol,
  manifestSchema,
} from "@web5/credential-issuance-protocol";

// example use in protocol query
const { protocols } = await web5.dwn.protocols.query({
  from: did,
  message: {
    filter: {
      protocol: credentialIssuerProtocol.protocol,
    },
  },
});

// applicant side
import {
  credentialApplicantProtocol,
  manifestSchema,
  presentationSchema,
  responseSchema,
} from "@web5/credential-issuance-protocol";

// example use in write
const { record: applicationRecord, status: createStatus } =
  await web5?.web5.dwn.records.create({
    store: true,
    data: presentationResult.presentation,
    message: {
      recipient: issuerDid,
      schema: presentationSchema.$id,
      dataFormat: "application/json",
      protocol: credentialApplicantProtocol.protocol,
      protocolPath: "application",
    },
  });

To Do

• Create repo with documentation and diagrams
• Credential issuer protocol handlers: #5
  • Use env var to allow importing custom manifests: #5
  • Create, read, update credential manifest records in DWN: #5
  • Create and update responses to applications: #5
  • Read applications, parse credentials and validate against manifest (presentation exchange): #5
  • Request new credentials from trusted 3rd party issuers: #5
  • Create new credentials from 3rd party data requests: #5
• DCX DWN Manager #15
• DID DHT Manager #10
• DCX Server #13

Other PRs

• Debugging and cleanup

Project Resources

Resource	Description
CODEOWNERS	Outlines the project lead(s)
CODE_OF_CONDUCT.md	Expected behavior for project contributors, promoting a welcoming environment
CONTRIBUTING.md	Developer guide to build, test, run, access CI, chat, discuss, file issues
GOVERNANCE.md	Project governance
LICENSE	Apache License, Version 2.0