# Issuer Registry MVP

## Overview

In the initial implementation, Verite issuer registry will be stored off-chain as a JSON file in Verite gihub repo (similar to Verite credential schemas and processes).

The structure, usage, semantics, and lightweight governance is described here. All to be interpreted as MVP/G

## Usage/Intent of the Issuer Registry

The Verite Issuer Registry identifies entities authorized to issue Verite credentials (segmented by different credential types), along with associated metadata.

On receipt of a Verite credential, a verifier confirms:
1. the issuer, identified by stable identifier (typically a `did:web:`-prefixed reference to the URL of the issuance dapp) is in the issuer registry
2. the issuer is certified to issue the desired credential type

The Issuer Registry, along with the Issuer Rules associated with credential types and processes, helps achieve determinism in Verite credential issuance, in the sense that identical identity claim inputs should lead, among different Verite issuers, to the same decision to issue, or not to issue, a credential.

## Limitations, Assumptions, Scope (of this document and in general)

- Off-chain verification: as Verite credential verification is an off-chain process, the issuer registry does not need to be on-chain
- Out of scope is Verite membership aspects of governance.

### Notes for internal use only (not to share publicly)

TO DISCUSS: Centre and Circle Verite team

Centre is unable to do anything without board approval and heavy scrutiny around potential IP concerns. The following (in isolation or in combination) would introduce strong friction:
- Deploying a smart contract and the related requirement for key custody
- Verite membership program as part of more general governance structure

## Design

### Roles

The following roles are referred to below
- Verite owners/administrators:
- Initially Verite github repo (centrehq) administrators. (INTERNAL NOTE: this is Kim and Juan)
- Sole technical/logistic ability to approval and merge PRs
- Later to be replaced with real governance/membership scheme
- Verite participants:
- Signing Verite CLA is prerequisite to be listed in the registry as an issuer
- Consensus among other issuers of a given credential is mandatory to be listed in the registry as an issuer
- note: until there is a "rulebook" per credential, manually approving new issuers will be a slow process contingent on direct communications between each new issuer and every current issuer of a given credential.

### Implementation

- Verite issuer registry to be deployed as JSON file in Verite github repo:
- Specifically, in a directory under here (note: this is where we put processes and definitions) https://github.com/centrehq/verite/tree/main/packages/docs/static
- As with Verite processes and definitions (and @Context file), this file can be referenced with a canonical (verite.id URL)

### File Structure
JSON file contains list of Issuers. Issuer object structure:

{
    name: "<entity name>",
    id: "<DID>",
    authorizations: ["list", "of", "credentialTypes"]
        // e.g. `IndivAccInvAttestation`, `KYCAMLAttestation`, or `KYCAMLAttestation+IndivAccInvAttestation`
        // Should link to exact versioned definitions at https://verite.id/...

}

Questions:

- Need signature? Or do github signed commits suffice?
- Juan: I think PKI is law, github commits should suffice IMHO
- Where are versions needed? Issuer level, authorizations, both?
-

See more questions below

## Governance and Prerequisites

- Prerequisites:
- Organization must sign Verite CLA
- Organization must receive approval from WG members (question: is this off-limits for Centre membership wise?)
- Juan's quick hack: I just rephrased this as per-cred issuer governance, i.e. all issuers of a given cred approve new issuers of that cred. more nuanced membership including issuers out-of-scope til we have signatory authority and/or a new, safer home!
- Process for updates to issuer registry:
- Any individual representing an organization covered by Verite CLA may open PR against Centre Verite github org
- schemas after v1 are permanent and any changes need a new version/separate registry entry and permanent URL
- Verite owners/administrators must review, approve, and merge
- Juan: Adding a new schema needs approval of relevant WG
- Juan: Adding a new version of an existing schema needs approval of all current issuers of that credential
- Juan: approval by all issuers COULD be done on github instead of email, in theory, although that sounds impractical

Governance
- above plus wg approval? (Is this too membership-y)
- Juan: nah, fair game cuz WG is defined by CLA and desire to issue a credential, no membership needed (technically)

## Questions / To Decide

- Versioning and verification
- How deep do we want versioning to go in MVG?
- Different versions resolvable through URLs? I.e. each "version" can be considered immutable -- Juan: YES (see edits above). Alternative to chaotic/human-error-prone
- Or file updates with "date added/removed" -- Juan: NO
- Do we want to use any of the above in the verification process to ensure any VCs issued by the issuer _before_ they were added to the registry would be rejected?
- Juan: IMHO that makes the registry more complex than it needs to be and can be solved out-of-bound, i.e., don't issue any v1+ creds in prod until you're approved cuz you're violating the terms of being an issuer if those circulate and get erroneously accepted...
- At what level do we need timestamps?
- When added to the issuer registry
- When individual credential type authorizations added
- Juan: Feels like overkill to me. I prefer to let versioning do this work. Authorizations are per-version, don't issue anything >v0.9.9 unless you're ready to revoke those test-creds before getting certified
- Should link to registry be in vc itself?
- I think this would be valuable
- this would be a change to credential schema
- Juan: Idunno, I like keeping open the option of moving to an [additional or subset] on-chain registry later for some use-cases. This locks in registry decision in advance and forever :D
- Do we want to include instrucions for removal from registry?
- Juan: I think we just say:
- To remove an issuer's authorization for a given credential, consensus among other issuers of said credential is required.
- To remove an issuer from the registry entirely, 51% of ALL issuers and a consultation with Centre Legal is required