# Cardea Machine Readable Governance

Heavily inspired by [Aries RFC 430](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0430-machine-readable-governance-frameworks/README.md) (including the 3 quotes below).

## What Is Machine Readable Governance?
> A governance framework (also called a trust framework in some contexts) is a set of rules that establish trust about processes (and indirectly, about outcomes) in a given context.

Machine readable governance, therefore is
> Governance frameworks... embodied in formal data structures, so it's possible to react to them with software, not just with human intelligence.

### What Are the Benefits of Machine Readable Governance?
>Trust frameworks are like guy wires: they balance opposing forces to produce careful alignment and optimal behavior

* Increase trust between parties
* Organize the ecosystem by codifying rules, conventions, and standards
* Provide flexibility to accommodate change and avoid having to frequently re-release or update agents

## Sample Email Implementation
The first trust framework we're releasing in a production environment deals with email credential issuance and verification.

### Goals of the Email Implementation of Machine Readable Governance
* Share contact information for the governing body
* List schemas in use
* List roles of participating parties
* List issuers (approved issuers that provide the correct verifiable credentials)
* List validated verifiers (can be trusted to verify credentials according to the governance framework)

### Validated Email Workflow
1. Holder looks up the governance file from a trusted party.
2. Holder finds at least one issuer that offers a validated email credential and has been verified by the governing organization.
3. Holder uses the information in the machine readable governance framework to connect to the issuer and follow the procedure for receiving a credential.
4. The issuer uses provided information to validate the email and issue the credential according to the governance framework.
5. After receiving the email credential, the holder looks up a list of verifiers that:
a) have been vetted as trustworthy verifiers of the email credential (i.e., you can trust them not to misuse any data you share with them).
b) can help them verify that their credential is in working order.

### Email Governance File

{
  "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
  "name": "Email Validation",
  "version": "0.1",
  "description": "Issuance and verification of validated email credentials. Provides a source of truth for current schemas, issuers, and verifiers",
  "last_updated": "2021-06-07",
  "docs_uri": "create_or_leave_blank",
  "data_uri": "create_or_leave_blank",
  "schemas": ["email_schema_here"],
  "roles": ["issuer", "verifier"],
  "define": [
    {
      "name": "Email_Issuer",
      "id": "update_with_did_please",
      "describe": {
        "label": "Email Issuer",
        "sublabel": "Issuing Org",
        "website": "issuingorgsite.com",
        "email": "[e-mail]"
        "endpoints": [
          {
            "type": "invitation_request",
            "url": "https://domain_or_ip:port/api/invitations"
          },
          {
            "type": "email_request",
            "url": "https://domain_or_ip:port/api/credentials"
          },
        ]
      }
    },
    {
      "name": "Email_Verifier",
      "id": "update_with_did_please",
      "describe": {
        "label": "Email Verifier",
        "sublabel": "Verifying Org",
        "website": "verifyingorgsite.com",
        "email": "[e-mail]"
      }
    }
  ], 
  "rules": [
    {"when": {"name": "Email_Issuer"}, "thus": "issuer"},
    {"when": {"name": "Email_Verifier"}, "thus": "verifier"}
  ]
}

## Cardea Governance
### For Immediate Implementation
Here are some things we're working on right now. These items establish the necessary foundations of machine readable governance for the current features of Cardea so that other governance features can be added later.
1. Create a governance file including schemas, roles, invitations, network details, and mediator info
2. Host the governance file with the government agent since it represents the governing body
3. Adjust all of the agents to use the governance file
4. Include the machine readable governance code in the appropriate repos
5. Create a public demo of Cardea (which includes governance)

### Sample File

{
  "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
  "name": "Health Governance",
  "version": "0.1",
  "description": "Issuance and verification of health credentials. Provides a source of truth for current schemas, issuers, and verifiers",
  "last_updated": "2021-06-10",
  "docs_uri": "need_to_create",
  "data_uri": "need_to_create",
  "schemas": ["test_id", "test_result", "trusted_traveler"],
  "roles": ["issuer", "verifier"],
  "define": [
    {
      "name": "Government_Organization",
      "id": "update_with_did",
      "describe": {
        "label": "Government",
        "sublabel": "Full Government Organization Name",
        "website": "issuinggovernmentsite.org",
        "email": "[e-mail]"
      }
    },
    {
      "name": "Lab_Issuer",
      "id": "update_with_did",
      "describe": {
        "label": "Lab Issuer",
        "sublabel": "Full Organization Name",
        "website": "issuinglabsite.com",
        "email": "[e-mail]"
      }
    },
    {
      "name": "Health_Verifier",
      "id": "update_with_did_please",
      "describe": {
        "label": "Health Verifier",
        "sublabel": "Verifying Org",
        "website": "verifyingorgsite.com",
        "email": "[e-mail]"
      }
    }
  ], 
  "rules": [
    {"when": {"name": "Government_Organization"}, "thus": "issuer"},
    {"when": {"name": "Lab_Issuer"}, "thus": "issuer"},
    {"when": {"name": "Government_Organization"}, "thus": "verifier"}
    {"when": {"name": "Health_Verifier"}, "thus": "verifier"}
  ]
}

### Ideas for Future Implementation
* Verify trusted issuers
* Verify trusted verifiers
* Describe presentations between agents

## Future Governance Possibilities
* Dynamic ecosystem
* Change the issuers, verifiers, rules, etc. over time
* Provide for stable versions where all participating parties know what to expect
* Approved schemas
* Can address multi-ledger security concerns
* Define data formats and conversion standards (e.g. to and from FHIR)
* Rules for issuers
* Allowed attribute values
* Prerequisites
* Rules for holders
* Caching
* Pre-requisites
* Rules for verifiers
* Verifiers can identify approved issuers
* Allowed presentations
* Business logic based on presentations
* Workflow instructions
* Steps, requirements, and logic for multiple participants
* Describe presentations between agents
* Can apply to issuance, presentation, data storage, and business logic dependent on verifiable credentials