Difference between revisions of "Machine Readable Governance"

Latest revision as of 10:13, 1 September 2024

Full Title or Meme

Analysis of a Machine Readable Governance as applied to COVID Creentisls by the government of Aruba for access to that country.

Context

• For more information on the general topic see the wiki page on Digital Governance.
• This output was provided by the Cardea project early in their development process and is no where near the final format.

Current Draft

1. 2022-03-22 - It is believed that this output is designed to be a json-LD document - but that has not been verified.
2. the operating assumption is that this is designed as the policy of the government to be applied by customs and immigration officers at debarkation (or better yet at embarkation).

{
  "@context": [
    "https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0430-machine-readable-governance-frameworks/context.jsonld"
  ],
  "name": "COVID Governance",
  "version": "0.1",
  "format": "1.0",
  "id": "<uuid>",
  "description": "This document describes COVID health and travel governance for the nation of in a machine readable way.",
  "last_updated": "2022-02-24",
  "docs_uri": "need_to_create",
  "data_uri": "need_to_create",
  "topics": [
    "medical, travel"
  ],
  "jurisdictions": [
    "US>NY>New York City",
    "US>PA"
  ],
  "geos": [
    "USA",
  ],
  "schemas": [
    {
      "id": "4CLG5pU5v294VdkMWxSByu:2:Medical_Release:1.0",
      "name": "Medical Release",
    },
    {
      "id": "RuuJwd3JMffNwZ43DcJKN1:2:Lab_Order:1.4",
      "name": "Lab Order"
    },
    {
      "id": "RuuJwd3JMffNwZ43DcJKN1:2:Lab_Result:1.4",
      "name": "Lab Result"
    },
    {
      "id": "RuuJwd3JMffNwZ43DcJKN1:2:Vaccination:1.4",
      "name": "Vaccine"
    },
    {
      "id": "RuuJwd3JMffNwZ43DcJKN1:2:Vaccine_Exemption:1.4",
      "name": "Vaccine Exemption"
    },
    {
      "id": "RuuJwd3JMffNwZ43DcJKN1:2:Trusted_Traveler:1.4",
      "name": "Trusted Traveler"
    }
  ],
  "participants": [
    {
      "name": "Country Government",
      "id": "RqeuBcho2Br1wszHpnseMf",
      "describe": {
        "label": "Country Government",
        "sublabel": "Government",
        "website": "issuinggovernmentsite.org",
        "email": "credential_manager@issuinggovernmentsite.org"
      }
    },
    {
      "name": "Local Health Lab",
      "id": "APk7kmMyzM4VTUkFUACrky",
      "describe": {
        "label": "Health Lab",
        "sublabel": "Local Health Lab",
        "website": "issuinglabsite.com",
        "email": "credential_manager@issuinglabsite.com"
      }
    },
    {
      "name": "Large Event Venue",
      "id": "7CyC6bkX93tcMvLQCbpTqM",
      "describe": {
        "label": "Event Venue",
        "sublabel": "Large Event Venue",
        "website": "verifyingorgsite.com",
        "email": "verifying_manager@verifyingorgsite.com"
      }
    }
  ],
  "roles": [
    "holder",
    "health_issuer",
    "travel_issuer",
    "health_verifier",
    "travel_verifier",
    "hospitality_verifier"
  ],
  "permissions": [
    {
      "grant": ["health_issuer"],
      "when": {
        "any": [
          {"id": "APk7kmMyzM4VTUkFUACrky"},
        ]
      }
    },
    {
      "grant": ["travel_issuer"],
      "when": {
        "any": [
          {"id": "RqeuBcho2Br1wszHpnseMf"}
        ]
      }
    },
    {
      "grant": ["health_verifier"],
      "when": {
        "any": [
          {"id": "RqeuBcho2Br1wszHpnseMf"}
        ]
      }
    },
    {
      "grant": ["travel_verifier"],
      "when": {
        "any": [
          {"id": "RqeuBcho2Br1wszHpnseMf"}
        ]
      }
    },
    {
      "grant": ["hospitality_verifier"],
      "when": {
        "any": [
          {"id": "7CyC6bkX93tcMvLQCbpTqM"}
        ]
      }
    }
  ],
  "actions": [
    {
      "name": "connect-holder-health-issuer",
      "role": [
        "health_issuer"
      ],
      "initial": true,
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/connections/1.0/",
        "startmessage": "invitation"
      },
      "next": {
        "success": "ask-demographics",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "ask-demographics",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/questionAnswer/1.0/",
        "startmessage": "question",
        "question_answer": [
          {
            "question": "Have you received a Medical Release credential from Health Lab before?"
          },
          {
            "question_detail": "Please select an option below:"
          },
          {
            "valid_responses": [
              {
                "text": "I need a new credential"
              },
              {
                "text": "I already have a credential"
              }
            ]
          }
        ]
      },
      "next": {
        "success": "decision-medical-release-option",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "decision-medical-release-option",
      "role": [
        "health_issuer"
      ],
      "type": "decision",
      "data": {
        "input_name": "medical_release_option",
        "options": [
          {
            "values": [
              "I need a new credential"
            ],
            "next": "request-identity-presentation"
          },
          {
            "values": [
              "I already have a credential"
            ],
            "next": "request-presentation"
          }
        ]
      },
      "next": {
        "success": "default",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "request-identity-presentation",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/present-proof/1.0/",
        "startmessage": ["request-presentation"]
      },
      "next": {
        "success": "decision-country-of-origin",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "request-presentation",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/present-proof/1.0/",
        "startmessage": ["request-presentation"]
      },
      "next": {
        "success": "decision-country-of-origin",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "decision-country-of-origin",
      "role": [
        "health_issuer"
      ],
      "type": "decision",
      "data": {
        "input_name": "country_of_origin",
        "options": [
          {
            "values": [
            ],
            "next": "reject-country"
          },
          {
            "values": [
            ],
            "next": "select-health-credentials"
          }
        ]
      },
      "next": {
        "success": "select-health-credentials",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "select-health-credentials",
      "role": [
        "health_issuer"
      ],
      "type": "decision",
      "data": {
        "input_name": "requested_health_credential",
        "options": [
          {
            "values": [
              "lab_result"
            ],
            "next": "validate-lab-result"
          },
          {
            "values": [
              "exemption"
            ],
            "next": "validate-exemption"
          },
          {
            "values": [
              "vaccination"
            ],
            "next": "validate-vaccination"
          }
        ]
      },
      "next": {
        "success": "lab_result",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "issue-lab-result",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "schema": "RuuJwd3JMffNwZ43DcJKN1:2:Lab_Result:1.4",
        "protocol": "https://didcomm.org/issue-credential/1.0/",
        "startmessage": "offer-credential"
      },
      "next": {
        "success": "request-health-proof",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "issue-exemption",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "schema": "RuuJwd3JMffNwZ43DcJKN1:2:Exemption:1.4",
        "protocol": "https://didcomm.org/issue-credential/1.0/",
        "startmessage": "offer-credential"
      },
      "next": {
        "success": "request-health-proof",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "issue-vaccination",
      "role": [
        "health_issuer"
      ],
      "type": "protocol",
      "data": {
        "schema": "RuuJwd3JMffNwZ43DcJKN1:2:Vaccination:1.4",
        "protocol": "https://didcomm.org/issue-credential/1.0/",
        "startmessage": "offer-credential"
      },
      "next": {
        "success": "request-health-proof",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "request-health-proof",
      "role": [
        "travel_issuer"
      ],
      "initial": true,
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/issue-credential/1.0/",
        "startmessage": "request-presentation",
        "presentation_definition": "http://localhost:3100/api/presentation-exchange"
      },
      "next": {
        "success": "verify-health-credential",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "verify-health-credential",
      "role": [
        "travel_issuer"
      ],
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/present-proof/1.0/",
        "startmessage": "request-presentation",
        "presentation_definition": "http://localhost:3100/api/presentation-exchange"
      },
      "next": {
        "success": "validate-health-credential",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "validate-health-credential",
      "role": [
        "travel_issuer"
      ],
      "type": "protocol",
      "data": {
        "presentation_definition": "http://localhost:3100/api/presentation-exchange"
      },
      "next": {
        "success": "issue-trusted-traveler",
        "error": "some-kind-of-error-handler..."
      }
    },
    {
      "name": "issue-trusted-traveler",
      "role": [
        "travel_issuer"
      ],
      "initial": true,
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/issue-credential/1.0/",
        "startmessage": "offer-credential",
        "schema": "RuuJwd3JMffNwZ43DcJKN1:2:Trusted_Traveler:1.4"
      }
    },
    {
      "name": "reject-country",
      "role": [
        "travel-issuer"
      ],
      "type": "protocol",
      "data": {
        "protocol": "https://didcomm.org/basic-message/1.0/",
        "startmessage": "send-message",
        "content": "We're sorry, your country is not approved for entry by Government"
      }
    },
    {
      "name": "submit-payment",
      "role": [
        "point-of-sale"
      ],
      "type": "api",
      "data": {
        "api": "https://paymentmagic.com",
        "method": "POST",
        "attributes": [
          "customer_name",
          "customer_date_of_birth",
          "customer_billing_address",
          "customer_shipping_address",
          "credit_card_number",
          "credit_card_expiration",
          "credit_card_security_code"
        ]
      }
    }
  ]
}

Bottom notes:
The document only changes as often as government-level health guidance, and that is not daily. Aruba has only changed policy 4 or 5 times in the last year. Aruba's method of implementing changes is to introduce them between the last flight of one day and the first flight of the next day so that no one will be caught mid-flight with a changing guideline.
The "Schemas" referred to were decided on by the multi-organization Cardea community, released as open source, and adopted by Aruba for a POC. They have proven quite stable and have not changed in over six months. This machine readable governance file establishes a trust framework for airlines, travelers, organizations, companies, and others that interact with Aruba in the health and travel ecosystems.
"Participants" is the list of issuing and/or verifying agents that Aruba has vetted and represents to the public as official and safe. This taxonomy to describe them could definitely be worked on by the identity community so that it is as useful as possible and agreed upon so it can be widely adopted.
"Permissions" are mapped to "Participants" using "Roles" and this is explicitly to prevent any old agent from issuing their own "ticket" that gets accepted. While not fully separated into separate document sections, the issuing parties are decided upon by the governing body and the issuing and relying parties are included in separate roles.
The "Actions" section directs programs how to behave (removing much of the decision making overhead from humans involved). It also includes references to presentation definitions which are used in a rules engine that dictates how values from different countries are 1) standardized to prevent uneven results and 2) to evaluate the credentials that are presented. Governance files are designed to be easily shareable but not dictated from a central super-national authority, allowing countries to customize their polices without requiring them to write them completely from scratch. The framework is mostly geared toward allowance/denial of access, but allows for other paths (e.g., in the case of COVID, on-island testing and quarantine that allow for later access to the nation).

Commentary

1. While it is clear that this document will be changed often during an infection, even daily, it is not clear how to tell what is valid at any pariticular time. F or example could the traveller be assure that the policy in force at the time of departure would be applied at the time of debarkation? See the user journey of a Credential Policy Coordination for details.
2. "schemas" These appear to be the document formats for credentials. Not clear that a country of the size of this document could ever keep up the the potential formats. It seems that a "trust framework" is required to establish the scope of schemas to be accepted by immigration officials.
3. "participants" It seems like there are the relying parties, or the sites that actually grant (or deny) access. A common taxonomy of venues would be good, but perhaps might (in the US) even be state specific.
4. "permissions" It seems like this is a collection of issuers and verifiers. At first glance that is troubling, but I can see some relying parties issuing their own "tickets" for entry. I personally believe we need to break the relying party / verifier into separate sections as show in other use case; namely: the policy definition point that sets the policy for each site and the policy execution point that accepts the tickets and acts on them.
5. "actions" This is the largest section and appears to written an a UX program that tells the immegration officials what questions to ask and what answers to expect. In some cases the request is to the user wallet and the evaluation of the values returned. These values are actually dependent on the country where the certificates were issued so the result is likely to be uneven. Here is the place where some sort of rules engine would be most useful. It is unlike that most countries would be in a position to create such a rules engine, so the source would like be established on a continental bases. It is presumed that the only action available is is to grant or deny access to the country.
6. "others"

Reference

• See wiki page Policy-Based Access Control.
• See the wiki page on Governance Framework.