docs(ADR): add verifiable credential ADR 006 (#179)

fix(simulation): propagate error for add verification Co-authored-by: PaddyMc <[email protected]> Co-authored-by: Barrie Byron <[email protected]>
elesto-dao · Aug 3, 2022 · 3d4fcb1 · 3d4fcb1
1 parent b87ade2
commit 3d4fcb1
Show file tree

Hide file tree

Showing 7 changed files with 484 additions and 29 deletions.
diff --git a/docs/Explanation/ADR/adr-006-public-verifiable-credential.md b/docs/Explanation/ADR/adr-006-public-verifiable-credential.md
@@ -0,0 +1,126 @@
+# ADR 006: Verifiable Credentials
+
+## Changelog
+
+- 2022-07-04: Initial draft
+
+## Status
+
+DRAFT
+
+## Abstract
+
+Credentials are part of our daily interactions; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and concert tickets are used to assert that we can attend an event.
+
+Many credential types are used to store [personal identifiable information](https://en.wikipedia.org/wiki/Personal_data) (PII) and therefore must be kept private. However, there are many cases where it is more practical to publish credentials. For example, business licenses are used to assert that a business is legitimate and has the authorization to operate.
+
+In this context, a credential is defined as a set of one or more claims made by an issuer and a [verifiable credential](https://www.w3.org/TR/2022/REC-vc-data-model-20220303/) (VC) as a tamper-evident credential that has authorship that can be cryptographically verified.
+
+This document specifies support for VCs for private credentials and public credentials and support for credential definitions.
+
+## Context
+
+The self-sovereign identity (SSI) approach to tackling the identity and privacy challenge has gained momentum in recent years. Coupled with distributed ledger technology (DLT) technology, the SSI approach has captured the attention of the private and public sectors.
+
+The SSI approach relies on two building blocks: decentralized identifiers (DID) and VCs. This architecture decision record (ADR) describes the implementation for supporting VCs in a Cosmos SDK-based blockchain.
+
+This ADR aims to define a foundation for the components required to realize the Elesto objectives while ensuring the VC implementation is fully compliant with the W3C recommendations. **Successive iterations will address API ergonomics and standard compatibility issues.**
+
+## Decision
+
+A new credential module for the Elesto implementation for VCs will follow the [Verifiable Credentials Data Model W3C Recommendations](https://www.w3.org/TR/2022/REC-vc-data-model-20220303/) to maximize compatibility with third-party tools and projects.
+
+This ADR introduces two data structures for the Elesto chain:
+
+- Credential Definition (CD)
+- Public Verifiable Credential (PVC)
+
+### Credential Definition (CD)
+
+CDs are used to describe the model of a credential, that is, its structure, fields, properties, and behavior. CDs consist of the following fields:
+
+- `id` - the credential definition did
+- `publisherId` - the DID of the publisher of the credential
+- `name` - the human-readable name of the credential 
+- `description` - the description of the credential usage
+- `isPublic` - the credential can be issued on-chain
+- `isActive` - a hint that indicates the credentials based on this schema should not be issued
+- `supersededBy` - id of a new credential definition that supersedes this definition 
+- `schema` - the credential [data schema](#credential-schema) 
+- `vocab` - the credential [JSON-LD vocabulary](#credential-json-ld-vocabulary)
+
+A CD cannot be deleted from the state. 
+
+#### Credential Data Schema
+
+A credential [data schema](https://www.w3.org/TR/vc-data-model/#data-schemas) is a machine-readable definition of fields and data types of a credential. 
+
+The credential module supports the `JsonSchemaValidator2018` JSON-LD type schema format as described in the W3C [Verifiable Credentials JSON Schema Specification](https://w3c-ccg.github.io/vc-json-schemas/v1/index.html). The schema is stored as an uncompressed byte slice.
+
+#### Credential JSON-LD vocabulary
+
+A credential [JSON-LD context](https://www.w3.org/TR/json-ld11/#the-context) is a semantic vocabulary for the credential field descriptions. The vocabulary, in JSON format, is stored as an uncompressed byte slice.
+
+### Public Verifiable Credential (PVC)
+
+With PVCs, a VC is stored on-chain.
+
+To publish a VC on-chain, the sender must provide the credential definition that describes the credential. A credential is published only if:
+
+- The credential definition has been published on-chain
+- The credential definition allows publication of the credential (the field `isPublic` is true)
+- The credential definition status is active (the field `isActive` is true)
+- The credential conforms to the schema
+- The proof of the credential can be positively verified
+
+The `supersededBy` is used only for communication purposes and does not influence the publication of a credential.
+
+PVCs are intended for advertising information that is public domain and leverages the tamper-resistant capability of the blockchain. A PVC can be deleted from the state.
+
+## Privacy Considerations
+
+There is a risk that a credential definition allows publication of PII since the failsafe mechanism provided by the `isPublic` field can be misused by the credential publisher.   
+
+## Security Considerations
+
+The credential schema and the vocabulary must be stored uncompressed. Compression will make the node vulnerable to a [zip bomb](https://en.wikipedia.org/wiki/Zip_bomb) attack. 
+
+## Consequences
+
+The Elesto chain will provide support for credential schemas and vocabularies. At the same time, support for PVCs provides a strong foundation for a network of trust.
+
+### Backward Compatibility
+
+The credential module is a new module so backward compatibility is not a concern.
+
+### Positive
+
+- The ADR implementation improves compatibility with the SSI identity model.
+- Closely following the W3C standard gives the best chance of successful interoperability with third-party components.
+
+### Negative
+
+N/A
+
+### Neutral
+
+N/A
+
+## Further Discussions
+
+While an ADR is in the DRAFT or PROPOSED stage, this section summarizes issues to be solved in future iterations. The issues summarized here can reference comments from a pull request discussion.
+
+Later, this section can optionally list ideas or improvements the author or reviewers found during the analysis of this ADR.
+
+## Test Cases [optional]
+
+N/A
+
+## References
+
+- [W3C Recommendation Verificable Credentials Data Model v1.1](https://www.w3.org/TR/2022/REC-vc-data-model-20220303/)
+- [W3C Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/#data-schemas)
+- [W3C Recommendation JSON-LD v1.1](https://www.w3.org/TR/2020/REC-json-ld11-20200716/)
+- [W3C Verifiable Credentials JSON Schema Specification](https://w3c-ccg.github.io/vc-json-schemas/v1/index.html)
+- [Personally Identifiable Information (PII)](https://en.wikipedia.org/wiki/Personal_data)
+- [General Data Protection Regulation (GDPR)](https://eur-lex.europa.eu/eli/reg/2016/679/oj)
diff --git a/docs/Explanation/ADR/adr-007-revocation-lists.md b/docs/Explanation/ADR/adr-007-revocation-lists.md
@@ -0,0 +1,212 @@
+# ADR 007: Revocation Lists
+
+## Changelog
+
+- 2022-07-04: Initial draft
+
+## Status
+
+DRAFT
+
+## Abstract
+
+Credentials are part of our daily interactions; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and concert tickets are used to assert that we can attend an event.
+
+It is helpful for a credential issuer of a [verifiable credential](https://www.w3.org/TR/2022/REC-vc-data-model-20220303/) (VC) to provide a location where a verifier can check to see if a credential has been revoked.
+
+This document specifies support for a native implementation of revocation lists that are based on the W3C Credentials Community Group [Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/) report. This report details a strong privacy-preserving, space-efficient, and high-performance mechanism for publishing the revocation status of VCs.
+
+## Context
+
+The self-sovereign identity (SSI) approach to tackling the identity and privacy challenge has gained momentum in recent years. Coupled with distributed ledger technology (DLT) technology, the SSI approach has captured the attention of the private and public sectors.
+
+The SSI approach relies on two building blocks: decentralized identifiers (DID) and VCs. This architecture decision record (ADR) describes a method to leverage public VCs in Cosmos SDK-based blockchains to provide support for revocation lists. 
+
+## Decision
+
+By leveraging public verifiable credentials (PVCs) and a credential definition schema, the Elesto node will offer native support for revocation lists. Privacy and performance must be considered when designing, publishing, and processing revocation lists.
+
+This ADR introduces a [credential definition](adr-006-public-verifiable-credential.md#credential-definition-cd) for use by a credential issuer to publish one or more revocation lists. Each revocation list is encoded in a [public verifiable credential (PVC)](adr-006-public-verifiable-credential.md#public-verifiable-credential-pvc).
+
+The revocation list model is an implementation of the W3C Credentials Community Group [Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/) privacy-preserving, space-efficient, and high-performance mechanism for publishing the revocation status of VCs.
+
+In this model, the credential issuer assigns an arbitrary positive number to each credential that it issues: the number is the index in the revocation list encoded in the [public verifiable credential](adr-006-public-verifiable-credential.md#public-verifiable-credential-pvc).
+
+The credential schema, included in the revocation list credential definition, is defined by this JSON-formatted schema:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://elesto.id/revocation-list2020/1.0/json-schema.json",
+  "$metadata": {
+    "slug": "revocation-list2020",
+    "version": "1.0"
+  },
+  "title": "RevocationList2020",
+  "description": "RevocationList2020 - A privacy-preserving mechanism for revoking Verifiable Credentials",
+  "type": "object",
+  "required": [
+    "@context",
+    "type",
+    "issuer",
+    "issuanceDate",
+    "credentialSubject"
+  ],
+  "properties": {
+    "@context": {
+      "type": [
+        "string",
+        "array",
+        "object"
+      ]
+    },
+    "id": {
+      "type": "string",
+      "format": "uri"
+    },
+    "type": {
+      "type": [
+        "string",
+        "array"
+      ],
+      "items": {
+        "type": "string"
+      }
+    },
+    "issuer": {
+      "type": [
+        "string",
+        "object"
+      ],
+      "format": "uri",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "issuanceDate": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "expirationDate": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "credentialSubject": {
+      "type": "object",
+      "required": [
+        "id",
+        "type",
+        "encodedList"
+      ],
+      "properties": {
+        "id": {
+          "title": "ID",
+          "description": "The revocation list ID",
+          "type": "string",
+          "format": "uri"
+        },
+        "type": {
+          "title": "Type",
+          "description": "value must be: RevocationList2020 ",
+          "type": "string"
+        },
+        "encodedList": {
+          "title": "encodedList",
+          "description": "base64 endcoded string of the zlib compressed bitstring",
+          "type": "string"
+        }
+      }
+    },
+    "credentialSchema": {
+      "type": "object",
+      "required": [
+        "id",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri"
+        },
+        "type": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}
+```
+
+### Example
+
+For example, a revocation list based on the credential definition schema looks like:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/vc-revocation-list-2020/v1"
+  ],
+  "id": "https://regulator/credentials/status/001",
+  "type": ["VerifiableCredential", "RevocationList2020Credential"],
+  "issuer": "did:cosmos:elesto:example-credential-issuer",
+  "issuanceDate": "2020-04-05T14:27:40Z",
+  "credentialSubject": {
+    "id": "https://regulator/credentials/status/001#list",
+    "type": "RevocationList2020",
+    "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQsvoAAAAAAAAAAAAAAAAP4GcwM92tQwAAA"
+  }
+}
+```
+
+As shown in the following diagram:
+
+![](../../assets/diagrams/out/revocationList2020.example.svg)
+
+## Privacy Considerations
+
+Refer to the privacy considerations of the W3C [Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/#privacy-considerations) report.
+
+## Security Considerations
+
+Refer to the security considerations of the W3C [Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/#security-considerations) report.
+
+## Consequences
+
+By leveraging the public verifiable credentials, the Elesto node offers native support for revocation lists. Revocation lists are stored as credentials in the node state, within the credential module keeper. 
+
+### Backward Compatibility
+
+There are no concerns related to backward compatibility.
+
+### Positive
+
+- The revocation list support and implementation improves the compatibility of the Elesto node with the SSI identity model.
+
+### Negative
+
+N/A
+
+### Neutral
+
+The credential issuer will be responsible for creating, maintaining, and tracking an index of the credentials that it issues; it is the credential issuer's responsibility to know what the next unassigned credential index associated with a revocation list is.
+## Further Discussions
+
+While an ADR is in the DRAFT or PROPOSED stage, this section summarizes issues to be solved in future iterations. The issues summarized here can reference comments from a pull request discussion.
+
+Later, this section can optionally list ideas or improvements the author or reviewers found during the analysis of this ADR.
+
+## Test Cases [optional]
+
+N/A
+
+## References
+
+- [W3C Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/) report
+- [W3C Recommendation Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/2022/REC-vc-data-model-20220303/)
diff --git a/docs/assets/diagrams/src/revocationList2020.example.puml b/docs/assets/diagrams/src/revocationList2020.example.puml
@@ -0,0 +1,17 @@
+@startjson
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/vc-revocation-list-2020/v1"
+  ],
+  "id": "https://regulator/credentials/status/001",
+  "type": ["VerifiableCredential", "RevocationList2020Credential"],
+  "issuer": "did:cosmos:elesto:example-credential-issuer",
+  "issuanceDate": "2020-04-05T14:27:40Z",
+  "credentialSubject": {
+    "id": "https://regulator/credentials/status/001#list",
+    "type": "RevocationList2020",
+    "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQsvoAAAAAAAAAAAAAAAAP4GcwM92tQwAAA"
+  }
+}
+@endjson