Bitstring Status List

This guide explains how to manage the lifecycle of Verifiable Credentials (VCs) using the @trustvc/trustvc library. It covers the creation, hosting, and management of a credential status list that supports revocation or suspension using the Bitstring Status List method.

Overview

The Bitstring Status List efficiently tracks the revocation/suspension state of VCs using a sequence of bits:

• Each bit corresponds to a credential in the list.
• 0 indicates the credential is valid (active).
• 1 indicates the credential is revoked or suspended.

This approach enables verifiers to determine the status of a credential without altering the original VC.

Installation

To install the package, use:

npm install @trustvc/trustvc

Creating a Credential Status List

1. Import Required Modules

import {
  createCredentialStatusPayload,
  CredentialStatusPurpose,
  StatusList,
  VCBitstringCredentialSubject
} from "@trustvc/trustvc/w3c/credential-status";
import { signCredential } from "@trustvc/trustvc/w3c/vc";

2. Set Up Hosting URL and Status List

Pick a hosting URL for the status list:

const hostingUrl = "https://example.com/credentials/status/3";

Initialize a new StatusList:

const credentialStatus = new StatusList({ length: 131072 }); // Default: 131,072 bits

3. Select the Status List Purpose

Choose between revocation or suspension:

const purpose: CredentialStatusPurpose = "revocation";

4. Update the Status of an Index

Note: Consider using a randomized index to enhance security and prevent predictability.

Retrieve and modify the status of a specific index:

const index = 94567; // Example index
credentialStatus.setStatus(index, true); // true = revoked/suspended

5. Encode the Updated Status List

Compress and encode the bitstring:

const encodedList = await credentialStatus.encode();

6. Create and Sign the Credential Status VC

Create a Credential Status Payload:

const credentialSubject: VCBitstringCredentialSubject = {
  id: `${hostingUrl}#list`,
  type: "BitstringStatusList",
  statusPurpose: purpose,
  encodedList,
}
const options = {
  id: hostingUrl,
  credentialSubject: credentialSubject,
};

const keyPair = {
  "@context": "https://w3id.org/security/multikey/v1",
  id: "did:web:example.com#keys-1",
  type: "Multikey",
  controller: "did:web:example.com",
  secretKeyMultibase: "<secretKeyMultibase>",
  publicKeyMultibase: "<publicKeyMultibase>",
};

const credentialStatusVC = await createCredentialStatusPayload(options, keyPair, 'BitstringStatusListCredential', 'ecdsa-sd-2023');
console.log("Credential Status VC:", credentialStatusVC);

Sign the Credential Status VC:

const { signed, error } = await signCredential(credentialStatusVC, keyPair);
if (error) throw new Error(error);
console.log("Signed Credential Status VC:", signed);

Updating the Credential Status List

1. Import Required Modules

import {
  createCredentialStatusPayload,
  fetchCredentialStatusVC,
  StatusList,
} from "@trustvc/trustvc/w3c/credential-status";
import { signCredential } from "@trustvc/trustvc/w3c/vc";

2. Fetch the Existing Credential Status VC

Retrieve the Credential Status VC from the hosting URL:

const hostingUrl = "https://example.com/credentials/status/3";

let credentialStatusVC;
try {
  credentialStatusVC = await fetchCredentialStatusVC(hostingUrl);
} catch (err) {
  console.error("Invalid URL:", err);
  throw err;
}

3. Update the Status List

Decode the existing bitstring and update the status:

const statusList = await StatusList.decode({
  encodedList: credentialStatusVC.credentialSubject.encodedList,
});

const indexToUpdate = 94567; // Example index
statusList.setStatus(indexToUpdate, true); // true = revoked/suspended

4. Encode and Sign the Updated Status List

Re-encode the updated status list:

const encodedList = await statusList.encode();

Create and sign the updated Credential Status VC:

const credentialSubject: VCBitstringCredentialSubject = {
  id: `${hostingUrl}#list`,
  type: "BitstringStatusList",
  statusPurpose: "revocation",
  encodedList,
}

const credentialStatusPayload = await createCredentialStatusPayload(
  {
    id: hostingUrl,
    credentialSubject
  },
  keyPair,
  'BitstringStatusListCredential',
  'ecdsa-sd-2023',
);

const { signed, error } = await signCredential(credentialStatusPayload, keyPair);
if (error) throw new Error(error);
console.log("Updated Credential Status VC:", signed);

Hosting the Credential Status List

When managing credential status using a bitstring-based Status List, the list must be hosted at a publicly accessible URL. This allows verifiers to fetch the list and verify the credential's status.

For the examples above, the Credential Status List is hosted at: https://example.com/credentials/status/3

CORS Configuration Required for Interoperability

Your hosted Status List must have CORS enabled. This requires configuring the status list endpoint to return the Access-Control-Allow-Origin: * header. Without this configuration, external verifiers (like ref.tradetrust.io) will be blocked by the browser's CORS policy and cannot check if credentials are revoked or suspended.

Why this matters:

• This only affects web-based verifiers running in browsers (like ref.tradetrust.io)
• Server-side or native app verifiers are not affected by CORS
• Testing locally or within your own domain won't reveal this issue
• The error only appears when external web verifiers try to fetch your status list
• This is a browser security feature, not a bug in TradeTrust
• Verification will fail or show warnings if the status cannot be checked

For detailed instructions on configuring CORS for your status list endpoint, see the CORS Errors guide.

How the Credential Status Looks in a Verifiable Credential

Here is an example of how the hosted Credential Status List is referenced in a Verifiable Credential (VC):

"credentialStatus": {
  "id": "https://example.com/credentials/status/3#94567",
  "type": "BitstringStatusListEntry",
  "statusPurpose": "revocation",
  "statusListIndex": "94567",
  "statusListCredential": "https://example.com/credentials/status/3"
}

Using the Hosted Credential Status List

To use the hosted Credential Status List in your Verifiable Credential:

• Replace the example values in the credentialStatus object with those relevant to your setup:

  • Update the id, statusListIndex, and statusListCredential fields with the appropriate values based on your hosted Credential Status List and the credential's specific entry.

• Include the credentialStatus object in your Verifiable Credential payload before signing.

By referencing a hosted Credential Status List, verifiers can efficiently check the validity of credentials while ensuring that no sensitive data is exposed directly in the VC itself.