From 2b732ff7a054ec5e98a301596cdf17001e8d141c Mon Sep 17 00:00:00 2001
From: Shota Jolbordi <shota.jolbordi@iohk.io>
Date: Sun, 24 Mar 2024 00:06:09 +0400
Subject: [PATCH] Add revocation docs

Signed-off-by: Shota Jolbordi <shota.jolbordi@iohk.io>
---
 docs/docusaurus/credentials/revocation.md | 89 +++++++++++++++++++++++
 docs/docusaurus/sidebars.js               |  3 +-
 2 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 docs/docusaurus/credentials/revocation.md

diff --git a/docs/docusaurus/credentials/revocation.md b/docs/docusaurus/credentials/revocation.md
new file mode 100644
index 0000000000..0b0dbb142e
--- /dev/null
+++ b/docs/docusaurus/credentials/revocation.md
@@ -0,0 +1,89 @@
+# JWT credential revocation
+
+Identus implements revocation mechanism of JWT credentials according to [Bitstring Status List v1.0](https://www.w3.org/TR/2023/WD-vc-status-list-20230427/). It is an open standart that enables Identus to verify revocation status of any credential which implements revocation mechanism using the same specification.
+
+## Overview
+
+Every credential will contain the property `credentialStatus`, which will look like this
+
+```json
+"credentialStatus": {
+    "id": "http://localhost:8080/prism-agent/credentials/status/3#94567"
+    "type": "StatusList2021Entry",
+    "statusPurpose": "revocation",
+    "statusListIndex": "94567",
+    "statusListCredential": "http://localhost:8080/prism-agent/credentials/status/3"
+  },
+```
+
+* `type` will always be `StatusList2021Entry`
+* `statusListCredential` is a publically accessable URL that resolves a status list credential, it will look like this:
+```json
+{
+  "proof" : {
+    "type" : "DataIntegrityProof",
+    "proofPurpose" : "assertionMethod",
+    "verificationMethod" : "data:application/json;base64,eyJAY29udGV4dCI6WyJodHRwczovL3czaWQub3JnL3NlY3VyaXR5L211bHRpa2V5L3YxIl0sInR5cGUiOiJNdWx0aWtleSIsInB1YmxpY0tleU11bHRpYmFzZSI6InVNRll3RUFZSEtvWkl6ajBDQVFZRks0RUVBQW9EUWdBRUNYSUZsMlIxOGFtZUxELXlrU09HS1FvQ0JWYkZNNW91bGtjMnZJckp0UzRQWkJnMkxyNEQzUFdYR2xHTXB1aHdwSk84MEFpdzFXeVVHT1hONkJqSlFBPT0ifQ==",
+    "created" : "2024-03-23T16:45:50.924279Z",
+    "proofValue" : "ziKx1CJPKLy4U9kMmVzYct5xztq4oHRLPgMpAjh95zQxzBZorhLFmhZ85UPixJoQbaqkVaygLBnLARyxgGJGFNKFggaPSXHgJuG",
+    "cryptoSuite" : "eddsa-jcs-2022"
+  },
+  "@context" : [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://w3id.org/vc/status-list/2021/v1"
+  ],
+  "type" : [
+    "VerifiableCredential",
+    "StatusList2021Credential"
+  ],
+  "id" : "http://localhost:8080/prism-agent/credential-status/27526236-3836-4061-9867-f69314e258b4",
+  "issuer" : "did:prism:462c4811bf61d7de25b3baf86c5d2f0609b4debe53792d297bf612269bf8593a",
+  "issuanceDate" : 1711212350,
+  "credentialSubject" : {
+    "id" : "",
+    "type" : "StatusList2021",
+    "statusPurpose" : "Revocation",
+    "encodedList" : "H4sIAAAAAAAAAO3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
+  }
+}
+
+```
+* `statusListIndex` is an index in a bit-string at which revocation status of the credential can be verified.
+
+
+Status list credential contains `encodedList` which is a base64 encoded bit-string that contains revocation status of the credentail.
+
+## Verification
+
+In order to verify the revocation status of the credential, one must follow these steps:
+
+1. resolve Status list credential using the URL found at path - `credentialStatus.statusListCredential`
+2. Verify embeded proof of the credential
+3. decode bit-string which can be found in the JSON document of Status list credential, found at path - `credentialSubject.encodedList`
+4. Use the status list index from `credentialStatus.statusListIndex` to check if the bit at this index in the decoded bit-string from step 3 is on or off. If the bit is on, credential is revoked, otherwise it has not been revoked
+
+## Proof verification
+
+Status list credential integrity can be verified using the embeded proof of type `DataIntegrityProof` via crypto suite `eddsa-jcs-2022`. The exact steps are described in the [Data Integrity EdDSA Cryptosuites v1.0](https://www.w3.org/TR/vc-di-eddsa/#eddsa-jcs-2022)
+
+
+## Revocation
+
+Credential can only be revoked by the issuer of that credential.
+
+*Get the list of credentials*
+```bash
+curl -X 'GET' \
+  'http://localhost:8080/prism-agent/issue-credentials/records' \
+  -H 'accept: application/json'
+```
+this endpoint will return the credentials issued, every credential includes ID
+
+*Revoke the credential*
+```bash
+curl -X 'PATCH' \
+  'http://localhost:8080/prism-agent/revoke-credential/<credential_id>' \
+  -H 'accept: */*'
+```
+
+**Note:** [Present proof](./issue.md) will fail the verification if one of the credentials presented by the holder is revoked.
diff --git a/docs/docusaurus/sidebars.js b/docs/docusaurus/sidebars.js
index c0673aaebc..7e1712fa68 100644
--- a/docs/docusaurus/sidebars.js
+++ b/docs/docusaurus/sidebars.js
@@ -20,7 +20,8 @@ const sidebars = {
       },
       items: [
         'credentials/issue',
-        'credentials/present-proof'
+        'credentials/present-proof',
+        'credentials/revocation',
       ]
     },
     {