# Spec ## Goal The goal is to build a service that allows governing authority to create and maintain machine readable rules of its ecosystem governance framework. The rules must define (according to [ToIP v1 protocol specification](https://github.com/trustoverip/tswg-trust-registry-tf/blob/main/v1/docs/ToIP%20Trust%20Registry%20V1%20Specification.md)): 1. Which **issuers** are **authorized** to issue what types of **verifiable credentials**. 2. Which **verifiers** are **authorized** to request what types of **verifiable presentations**. The content of the trust registry must be **machine-readable and publicly** accessible. Changes must be **managed by governing authority**. The governing authority is responsible for the content of the trust registry, but the trust registry should provide as much as possible **automation and validation** to prevent human errors. - machine readable rules of governance framework - the content of the registry must be publicly accessible but changed only by authorized persons (governing authority) - support governance framework rules, mainly on entity onboarding, but also mechanisms for invalidation of such rules, no data deletion should be necessary - must be highly-available service with long running endpoints - the governing authority is responsible for the content of the trust registry, but the service should provide as much as possible **automation and validation** to prevent human errors ## User Stories Trust registry serves governance authority and all other participants in the ecosystem acting in various roles as issuers, verifiers and holders. The following user stories describes how participants in a given role interacts with the trust registry service. - As an issuer, I want to submit DIDs with metadata and credential types I'm issuing, so that I'll be recognized by verifiers and holders as an authorized issuer. - As a verifier, I want to submit DIDs with metadata, so that I'll be recognized by holders as an authorized verifier. - As a governing authority, I want to explicitly approve submission from issuers and verifiers, so that I can fulfill my obligation to keep the validity and authenticity of the registry. - As a governing authority, I want to manage list of credential types that are possible to issue and verify in ecosystem, so that the service can allow only requests to issue or verify such credential types. - As a verifier, I want to know who's authorized issuer of a particular credential type, so that I can request presentation with restrictions for particular issuer and credential type. - As a holder, I want to know who's authorized verifier, so that I can answer a presentation request only from them and don’t share my data with a fraudulent entity. - We intentionally don’t want to specify authorized verifiers for specific credential type. We assume that all authorized verifiers inside the registry are known and have been vetted by governing authority. - As a holder, I want to know what credentials are issued by authorized issuers, so that I can request the credential from them. - As a holder, I want to know who's authorized issuer of a particular credential, so that I’m not misled that I have a correct credential but later verification would fail because the credential was issued by an illegitimate issuer. - As an issuer or verifier, I want to be able to update DIDs and metadata about my entity, so that I can change the information and keep them updated in the registry (without asking Governing Authority). ## High-Level Roadmap - changes via static file applied by re-deployment - word of mouth onboarding - did resolver - old-school access management (username & password) - invitation link - UI - submission management, updates of entries - signature verification - modern access management with DIDs and VCs - full entity onboarding according to legal framework ## Implementation Phases There are still a lot of unknowns about how exactly trust registry will and should work in the future. One week we're talking about features it should have and the other one we discuss if we really need those things. Those discussions are great. We probably don't need a lot of features in the beginning but it's reasonable to consider all the possible ways how the future can look like. There is no reason to rush with implementation until we have more data from the usage of trust registry. Eventually, we can get to a state, when everything is fully automated based on integration with other systems (government level registry of companies, vLEI) or relying on existing DIDs and verifiable credentials. There is not only long way to get there, but those existing DIDs and verifiable credentials must be first issued by entities from trust registry (we can call them genesis entries). Or, we can find out that no trust registry is needed in a way we imagined. It can be a smart contract running on blockchain/distributed ledger. Therefore, we have to implement the service in some iterative way, when it's always production-ready system. Each phase should address the following questions: - What's the onboarding process? - What's the access management? - What are validation rules? - Who's GA? - What's the scale? - What's the acceptance criteria? - What are benefits we're delivering and feedback we expected to get? ### Phase 0 (August 2023) - Onboarding: word of mouth, data are send via e-mail to Sean and then added to the static JSON file in the project's repository - Access management: changes are loaded from static files into the database during the deploy of the service, everything is restricted by this process, submission endpoint is not available - Validation rules: required fields, DID is fully qualified and resolvable, issuing credentials belongs to existing schema - Governing authority: Absa/DIDx - Scale: units of entities - Acceptance criteria: the service is deployed on `dev` and `prod`, publicly accessible and utilized by at least one app, perhaps Absa Identity Wallet - Benefits: - feedback on deployment process and usability of registry data structure, - deliver value making registry available to read for all participants ### Phase 1 (November 2023) - Onboarding: word-of-mouth combined with an invitation link sent to entity representative e-mail, data filled in via UI or send to a given endpoint, approved or declined by admin via UI - Access management: invitation link to create/update registry entry for a given entity, user account based on e-mail and password with Admin role to approve/decline/invalidate entry, the content of the trust registry is publicly available via endpoint and web UI - Validation rules: the same as in previous, we can add validation that there is an e-mail part of submission that is the same as the e-mail receiving the invitation - Governing authority: Absa/DIDx - Scale: tens of entities - Acceptance criteria: - the onboarding process is automated with invitation link, user access management is in place, there is a web UI, the content of trust registry is changed in runtime - both Absa VCXS and DIDx cloud agent are able to register their DIDs to trust registry - Benefits: - feedback on access management and maintenance of running system - simpler onboarding allowing validation at a time of sending the data not at startup - feedback on UI - allow the entities to submit updates of their entries directly ### Next Phases - Scale: hundreds of entities, tens of schemas - Governing authority: BankservAfrica ## Ideas for Current and Future Enhancements - Access management: submission is signed with DID(s), admin auth based on DIDs and VCs - Validation rules: submission is signed with DID(s) - Content: verification policies - multiple ecosystems -> governance frameworks - entity logo is uploaded to trust registry - public directory Yellow pages - invitation to connect with Absa - validate if the schema ID is resolvable - GA can also directly create - As a GA Admin, I would like to see which schemas are already being used (and by who), and which are not used, so that...? ## Current Phase (Phase 1) ### User Stories - As an entity representative, I want to receive an invitation link, so that only I can create submission with data about my entity and DIDs via web form or send it programmatically to an API endpoint. - As a GA admin, I want to generate invitation link, so that only I can decide who can send a submission to the registry. - As a GA admin, I want to explicitly approve or reject submission, so that only I can decide what entity can be part of the trust registry. - As an entity representative, I want to be send other submissions without asking for permission of GA, so that I update data about my entity and I don't have to contact the GA for each update. - The submission is not direct update of registry, but just a request for that. - As a GA admin, I want to manage list of schemas, so that entities can registry only schemas that are allowed in the ecosystem. Open issues: - Shouldn't we allow to update data without GA's explicit approval? ### Data Structures We defined what's the purpose and basic functionality of trust registry, let's define what data structures it should store. Entity ```json { "id": "8fa665b6-7fc5-4b0b-baee-6221b1844ec8", "name": "Absa", "dids": [ "did:indy:sovrin:2NPnMDv5Lh57gVZ3p3SYu3", "did:indy:sovrin:staging:C279iyCR8wtKiPC8o9iPmb" ], "logo_url": "https://s3.eu-central-1.amazonaws.com/builds.eth.company/absa.svg", "domain": "www.absa.africa", "role": ["issuer"], "credentials": [ "did:indy:sovrin:staging:C279iyCR8wtKiPC8o9iPmb/anoncreds/v0/SCHEMA/e-KYC/1.0.0" ], "created_at": "2023-08-11T09:39:40.941Z", "updated_at": "2023-08-22T12:27:10.920Z" } ``` Schema ```json { "schema_id": "did:indy:sovrin:staging:C279iyCR8wtKiPC8o9iPmb/anoncreds/v0/SCHEMA/e-KYC/1.0.0", "name": "Digital Identity", "created_at": "2023-08-11T09:39:40.921Z", "updated_at": "2023-08-23T09:57:54.551Z" } ``` Open issues: - `credentials` vs. `issuing_credentials` - `dids` property or more entries with one `did` per entity - credential schema or credential definition in `credentials` - eventually enhance `entity` with e-mail where we send an invitation link, that must match, but do we want to show it publicly? - What should be allowed format(s) for logo? - Should we align with ToIP API? - https://github.com/trustoverip/tswg-trust-registry-tf/blob/main/v1/api/toip.trustregistry.api.yaml ### API `GET /api/registry` Returns the whole registry with publicly available data `GET /api/submissions` List of all submissions `GET /api/submissions/<generated_invitation_string>` Show submission `POST /api/submissions/<generated_invitation_string>` Create submission `POST /api/entities` Create an entry in registry based on submission ### Deployment - The service will be deployed as a Docker container on DIDx infrastructure. There must be separate stable `prod` and `dev` environment. Open issues: - We should perhaps loose the entity lifecycle rules on dev environment to allow exploration and testing.