# Revocations

## Overview

A credential with a revocation‐purpose status entry indicates that its valid/invalid state is determined by a Bitstring Status List maintained on‐chain. The verifier must:

1. Detect the presence of a revocation‐purpose `credentialStatus` entry.
2. Resolve and fetch the on‐chain revocation list.
3. Decode the bitstring and inspect the bit at the credential’s `statusListIndex`.
4. Reject the VC if that bit is set (1), otherwise allow validation to continue.

***

## Integration Point

> **Location in code**: `VcValidators.validateVc()`

This is where existing validation checks occur (proof, issuer DID, subject matching). After those checks, insert the revocation validation logic described below.

***

## Revocation Validation Steps

1. **Extract `credentialStatus` from the VC**
   * Read the VC’s `credentialStatus` array.
   * Look for an entry where:
     * `type` equals `"BitstringStatusListEntry"`, and
     * `statusPurpose` equals `"revocation"`.
   * If no such entry exists, skip revocation validation and treat the VC as valid.
2. **Parse the `statusListCredential` URI**
   * The `credentialStatus` entry contains a `statusListCredential` field in this format:

     ```
     ssi://{issuerDid}/{resourceId}
     ```
   * Extract:
     * `{issuerDid}` – the DID of the issuer, and
     * `{resourceId}` – the identifier of the on‐chain resource.
3. **Fetch the Revocation List from the Blockchain**
   * Call:

     ```
     getLinkedResource(blockchainRpcUrl, issuerDid, resourceId)
     ```
   * If the call returns a “resource not found” error, assume no revocation list has been published for this credential. In that case, allow the VC to pass validation (revocation cannot be determined).
4. **Decode the Retrieved Data**
   * The returned data is a byte array containing a compressed (gzipped) bitstring in Base64 form.
   * First decode the byte array from Base64 to obtain the raw gzip bytes.
   * Then decompress (gunzip) to recover the full bitstring as a sequence of bytes.
5. **Inspect the Bit at `statusListIndex`**
   * From the `credentialStatus` entry, read the numeric `statusListIndex`.
   * Within the decompressed bitstring, locate the bit at that index.
     * A bit value of `1` means the credential is revoked.
     * A bit value of `0` means the credential is not revoked.
   * If the bit is `1`, immediately fail validation (the VC is revoked).
   * If the bit is `0`, continue with any remaining validation steps (proof verification, expiration check, etc.).

***

## Example `credentialStatus` Entry

```json
"credentialStatus": [{
  "id": "ssi://did:example:12345/statusList3#94567",
  "type": "BitstringStatusListEntry",
  "statusPurpose": "revocation",
  "statusListIndex": "94567",
  "statusListCredential": "ssi://did:example:12345/statusList3"
}]
```

* **`statusListCredential`**: `ssi://did:example:12345/statusList3` → split into `issuerDid = did:example:12345` and `resourceId = statusList3`.
* **`statusListIndex`**: `94567` → the index of the bit to check in the decompressed bitstring.

***

## Failure Modes

* **Resource Not Found**
  * If `getLinkedResource(...)` indicates the on‐chain revocation list does not exist, treat the VC as not revoked (do not fail).
* **Network or Decode Errors**
  * If fetching or decoding the bitstring fails unexpectedly, the verifier may optionally treat the status as indeterminate and reject the VC, or fall back to a local policy. The exact behavior should align with your security requirements.

***

## Summary

When a VC includes a revocation‐purpose status entry:

1. Check for `type: BitstringStatusListEntry` and `statusPurpose: revocation`.
2. Fetch the on‐chain revocation list via `getLinkedResource(blockchainRpcUrl, issuerDid, resourceId)`.
3. If not found, allow the VC. If found, decode from Base64 → gzip → raw bytes.
4. Read the bit at `statusListIndex`:
   * `1` → credential revoked → fail validation.
   * `0` → credential not revoked → continue validation.

Add this section under your Verifier documentation to ensure all VCs with a revocation entry are properly checked before being accepted.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.empe.io/develop/verifier/revocations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.