# Trust Registry Intro
In many real-world credential exchange scenarios, a credential holder or verifier has the question "How do I know the issuer of this credential is trustworthy?"

Credential holders may also be uneasy about sharing information with a verifier if trust in the verifier has not been established.

These problems can be solved by having a trusted third party vouch for the trustworthiness of a credential exchange participant.

A trust registry is a list of authorized issuers and verifiers in the ecosystem and the types of credentials and passes they are authorized to issue and verify.

## Terminology
- **Trust Registry**: A list of all authorized organizations in the ecosystem and the types of data they are authorized to exchange.
- **Governance Framework**: A set of business and legal rules that describe how entities in an ecosystem must act to be trustworthy in a given context.
- **Provider**: The organization that productizes the trust model for an ecosystem to make it easy for participants to adopt. The provider's primary role is to productize and make adoption easy. It configures governance-as-code to comply with relevant Governance Framework(s) and regulations, including a trust registry and schemas.

Other terms you might hear thrown around:

- **Trust Framework**: Another name for a Governance Framework
- **Rules Engine**: An encoded implementation of the rules of a trust framework that can make decisions automatically. **Out of scope for this implementation, but should be considered**
- Governance Authority: Someone who defines the rules of the governance framework

## Trust Registry Requirements

The high level user stories for the trust registry are as follows:
- **As an user of the Trinsic CLI, I can create and delete registries**
- **As the creator of a trust registry, I can add/remove wallets from my trust registry**
- **As a credential holder or verifier, I can check that a credential's issuer is part of a trust registry.**
- As a wallet holder, I can enable/disable governance frameworks for my wallet.
- As a wallet holder, I can check that a verifier is part of a trust registry before responding to a presentation request.

## Trust Registry Example

# 1. Provider creates a registry using the CLI. 
trinsic registry create medcreds
----------------------------------------------
|.           name          |          ID                               |
----------------------------------------------
|     "medcreds"      |     did:web:asdfasdfasd    |
----------------------------------------------

# Provider creates three wallets: vaccination clinic, airline, alice
...

# 2. Provider adds clinic to registry with ability to issue a Vaccination Credential
trinsic registry add clinic 
--registry-id= did:web:asdfasdfasd \ 
--issuer-id=did:key:asdfasdfasdf \
-- type=https://cdc.gov/VaccinationCredential
> issuer did:key:asdfasdfasdf as been added to registry
----------------------------------------------------------------------
|.           ID                             |           type                                                       |
-----------------------------------------------------------------------
|    did:key:asdfasdfasdf      |     https://cdc.gov/VaccinationCredential    |
-----------------------------------------------------------------------
|    did:key:qwerqwerqwe      |     https://cdc.gov/VaccinationCredential,  |
|                                               |     https://cdc.gov/CovidTest
-----------------------------------------------------------------------

# Clinic issues credential to Alice
...

# 3. Alice checks if issuer is trusted based on information received from the credential
trinsic registry check \
--registry-id=did:web:asdfasdfasdf \
--issuer-id=did:key:asdfasdfasdf \
--type=https://cdc.gov/VaccinationCredential
> { 
       status: current, 
       authorization-start-date: 2021-01-02, 
       authorization-end-date: null
    }

# Alice presents credential 
... ...

#  4. Verifier verifies pass and checks credential
trinsic registry check \ 
--registry-id=did:web:asdfasdfasdf \
--issuer-id=did:key:asdfasdfasdf \
--type=https://cdc.gov/VaccinationCredential

# 5. Provider removes clinic from registry
trinsic registry remove \
--registry-id= did:web:asdfasdfasd \ 
--issuer-id=did:key:asdfasdfasdf

## Reference
### Trust Registry
A trust registry can either be completely public or private for only invited wallets.

Given the initial use cases are small scale and low risk, we may choose to start by implementing only public trust registries.

However, some customers have privacy of their trust registry as a requirement and authenticated fetching of trust registires should be considered.

message Registry {
    alias: string,
    id: did:web
    ...
}

#### Create a registry
No limits on the mount of registires to create for now.
Any CLI user can create a registry. This registry must be highly available - there will be many read transactions on it.

message CreateRegistryRequest {
    alias
    uri (optional)
    ...
}

Message CreateRegistryResponse {
    alias
    uri
}

CreateRegistry(CreateRegistryRequest) : CreateRegistryResponse

#### Remove a registry

message RemoveRegistryRequest {
    either id or alias
}

message RemoveRegistryResponse {
    statusCode
}
RemoveTrustRegistry(...)

#### Check the registry
This endpoint must be available via HTTP get (with authentication in the future) to comply with the GHP standards. CLI users may be better suited to call directly via grpc.

message CheckRegistryRequest {
    Trust registry DID
    issuer DID
    Verifiable credential type URI // example: https://cdc.gov/contexts/VaccinationCredential
}

Message CheckRegistryResponse { 
       status: current | expired | revoked | not found | terminated, 
       authorization-start-date: 2021-01-02, 
       authorization-end-date: null
}

CheckRegistry(...)

#### Add issuer to the registry
Add issuers by their ID that will be included in the credentials they issue. This is the ID that will be discovered by the verifier and checked with the ledger. They must have one or more types associated with them to be added. //note: perhaps we add a wildcard for an issuer that's trusted with all cred types?

message AddIssuerRequest {
    registryDid
    issuerDid
    credentialTypes: []
}

#### Remove/revoke entity from the registry
Removing is different from revoking. Both are provider initiated.

message RemoveIssuerRequest {
    registryDid
    issuerDid
    (optional) credentialTypes: []
}

#### Remove issuer from registry (as issuer)
If ownership over the ID can be proven, it can be removed.

## GHP Trust Registry Requirements
Please refer to 7.2.4.3.2 Trust Registries in [1]

### A GHP-compliant trust registry:
1. MUST be identified by a trust registry DID generated using a GHP-compliant DID method.
2. MUST support all mandated requirements of the GHP Trust Registry Protocol Specification .
3. SHOULD incorporate throttling, DDOS protection, etc.
4. MAY limit the DID methods permitted to be used for the registered DIDs to a subset of the
GHP-compliant DID methods.

### 7.2.4.3.3 Trust Registry Protocol
The GHP trust registry protocol:
1. MUST be an open standard royalty-free specification.
2. MUST be specified in either:
2.1. A GHP Trust Registry Protocol Specification.
2.2. A more general purpose trust registry protocol specification if it meets all the
requirements in these recommendations.
3. MUST support trust registry service endpoint resolution using GHP-compliant DID methods.
3.1. SHOULD support the GHP X.509 Subject Alternative Name URI Specification
4. MUST provide a registration method.
5. SHOULD provide a revocation method.
6. SHOULD provide a verifier access request method.
7. MUST support queries consisting of the following parameters to enable issuer authorization:
7.1. Trust registry DID
7.2. Issuer DID
7.3. Verifiable credential type URI
8. MUST support queries of the following parameters for cross-registration of peer trust registries
8.1. Trust registry DID
8.2. Verifiable credential type URI
8.3. Verifiable credential issuance date
9. MUST return exactly one of the following status values:
9.1. Not found
9.2. Current
9.3. Expired (not renewed after the previous valid registration period)
9.4. Terminated (voluntarily terminated by the issuer)
9.5. Revoked (involuntarily terminated by the governing authority)
10. MUST return exactly two date values (formatted to comply with RFC3339, as UTC/Z - with no
offset):
10.1. AuthorizationStartDate - which indicates the data that the Issuer’s authorization started.
10.2. AuthorizationEndDate - which may be null for Issuers that are currently, at time of the
query, an Authorized Issuer. If an Issuer is not currently an Authorized Issuer, the date
that they lost that status will be returned.

### 7.2.4.3.4 Issuers
GHP-compliant issuers:
1. MUST be identified by an issuer DID generated using a GHP-compliant DID method.
2. MUST register the issuer DID in the trust registry of any specific EGF under which the issuer
wishes to issue GHP-compliant credentials.
3. MUST issue GHP-compliant verifiable credentials that meet the following requirements:
3.1. The verifiable credential includes a claim specified in the GHP Verifiable Credentials
Specification whose value is the trust registry DID for the specific EGF under which the
credential or pass was issued.
3.2. The value of the verifiable credential issuer ID is the issuer DID registered in the trust
registry identified by the trust registry DID.
3.3. The value of the verifiable credential type is a GHP credential type URI specified in the
GHP EGF.
### 7.2.4.4 Recommended Timelines
#### 7.2.4.4.1 Phase One (30 Day Horizon)
GHP-compliant specific governing authorities:
1. SHOULD manually maintain a list of authorized issuers in a DID document using a did:web: URL
as specified GHP Trust Registry Protocol Specification.
2. SHOULD participate in development of the GHP Trust Registry Protocol Specification.
3. SHOULD publish their trust registry development plans.
#### 7.2.4.4.2 Phase Two (90 Day Horizon)
GHP-compliant specific governing authorities:
1. SHOULD publish their trust registry policies and specifications in their specific EGF.
2. SHOULD have their trust registry implemented.
3. SHOULD pass a GHP-compliant trust registry protocol test suite.
4. SHOULD maintain a list of the trust registry DIDs of other GHP-compliant peer governing
authorities.
#### 7.2.4.4.3 Phase Three (180 Day Horizon)
GHP-compliant specific governing authorities:
1. MUST have implemented a GHP-compliant trust registry.
2. MUST meet all requirements in their specific EGF.

---
sources:
1. [GHPC Interoperability Blueprint_v0.1.0_May 25 2021.pdf](https://github.com/trinsic-id/server/files/6609552/GHPC.Interoperability.Blueprint_v0.1.0_May.25.2021.pdf)

## Clarifications

### How are dependant parties notified of changes to the trust registry?
Any notifications around updates to the registry are out of scope for our first release. Queries to the trust registry will resolve to the current status. If an entity is removed from the registry, their new status will be fetched the next time around.

However, for future releases a trust registry changes state - eg an entity or type is added or removed - dependent parties like holders or verifiers will want to know. The trust registry should have a versioning system such that each new state change increments the version.

###

@startuml

Issuer -> Alice: "Issues Cred"
Alice -> Ver A: "Presents Cred"
Alice -> Issuer
@enduml

---

## Potential Implementations

### Example Vaccination Registry

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://www.w3.org/2018/credentials/v1",
    "https://trinsic.id/governance/v1"
  ],
  "id": "http://trinsic.id/registries/rhode-island-health-vaccination",
  "type": ["TrustedRegistryCredential", "VerifiableCredential"],
  "description": "Official State Registry of Covid Vaccination Issuers",
  "trustedIssuers": [
    {
      "id": "did:key:12345",
      
    {
      "id": "did:key:67890",
      "type": "TrustedEntity",
      "alsoKnownAs": ["mailto:[e-mail]"]
    }
  ]
}

### Example Registry Context

{
  "@context": {
    "@protected": true,
    "@version": 1.1,
    "id": "@id",
    "type": "@type",
    "description": "http://schema.org/description",
    "trustedIssuers": {
      "@id": "https://trinsic.id/governance#trustedIssuers",
      "@type": "@id",
      "@container": "@set"
    },
    "TrustedRegistryCredential": {
      "@id": "https://trinsic.id/governance#TrustedRegistryCredential",
      "@context": {
        "@version": 1.1,
        "@protected": true,
        "id": "@id",
        "type": "@type",
        "description": "http://schema.org/description"
      }
    },
    "TrustedEntity": {
      "@id": "https://trinsic.id/governance#TrustedEntity",
      "@context": {
        "@version": 1.1,
        "@protected": true,
        "id": "@id",
        "type": "@type",
        "alsoKnownAs": {
          "@id": "https://www.w3.org/ns/activitystreams#alsoKnownAs",
          "@type": "@id"
        }
      }
    }
  }
}

---
Action items
- Create spec with web idl
- SDKs
- Sample Implementation
- Scope: Spec it but not implement it. POC it.
- Clarify all the business requirements.
- Look into create a sample w3c spec up tool write out largest sections we have. Get headings of spec. modify content. show it to trust over IP.
- If we can give them a draft spec, we can start implementing it then. Get feedback and verify it.