Skip to Content
API ReferenceRevocation

Revocation & Status Lists

Functions for managing credential revocation using bitstring-based status lists, compatible with W3C Status List 2021 . Status lists are compact bitstrings where each index represents a credential --- flip a bit to revoke it.

createStatusList

Creates a new status list bitstring for tracking credential revocation.

function createStatusList(options: CreateStatusListOptions): StatusListData

Parameters

CreateStatusListOptions

ParameterTypeRequiredDefaultDescription
idstringYes---Unique identifier for this status list
issuerstringYes---DID of the issuer who owns this list
urlstringYes---Public URL where the status list credential will be hosted
sizenumberNo131072Number of entries in the list (minimum 131072 per W3C spec)

Returns

StatusListData

FieldTypeDescription
bitstringUint8ArrayThe raw bitstring (all bits initially 0 = not revoked)
issuerstringIssuer DID
idstringStatus list identifier
sizenumberTotal number of entries

Example

import { createStatusList } from "@credat/sdk";
 
const statusList = createStatusList({
  id: "status-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
// statusList.bitstring → Uint8Array (all zeros)
// statusList.size → 131072

setRevocationStatus

Sets or clears the revocation status for a specific index in the status list.

function setRevocationStatus(
  list: StatusListData,
  index: number,
  revoked: boolean,
): void

Parameters

ParameterTypeRequiredDescription
listStatusListDataYesThe status list to modify
indexnumberYesIndex of the credential to revoke or un-revoke
revokedbooleanYestrue to revoke, false to reinstate

Returns

void --- mutates the list.bitstring in place.

Errors

Throws CredentialError with code STATUS_LIST_INVALID if index is out of range (negative or >= list.size).

Example

import { createStatusList, setRevocationStatus } from "@credat/sdk";
 
const statusList = createStatusList({
  id: "status-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
// Revoke credential at index 42
setRevocationStatus(statusList, 42, true);
 
// Reinstate it
setRevocationStatus(statusList, 42, false);

isRevoked

Checks whether a specific index in the status list is marked as revoked.

function isRevoked(list: StatusListData, index: number): boolean

Parameters

ParameterTypeRequiredDescription
listStatusListDataYesThe status list to query
indexnumberYesIndex to check

Returns

boolean --- true if the credential at the given index is revoked.

Errors

Throws CredentialError with code STATUS_LIST_INVALID if index is out of range.

Example

import { createStatusList, setRevocationStatus, isRevoked } from "@credat/sdk";
 
const statusList = createStatusList({
  id: "status-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
setRevocationStatus(statusList, 42, true);
 
isRevoked(statusList, 42);  // true
isRevoked(statusList, 43);  // false

encodeStatusList

Compresses and encodes a status list bitstring for transport. The output is a gzip-compressed, base64url-encoded string as required by the W3C Status List specification.

function encodeStatusList(bitstring: Uint8Array): string

Parameters

ParameterTypeRequiredDescription
bitstringUint8ArrayYesRaw bitstring from StatusListData.bitstring

Returns

string --- base64url-encoded gzip-compressed bitstring.

Example

import { createStatusList, encodeStatusList } from "@credat/sdk";
 
const statusList = createStatusList({
  id: "status-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
const encoded = encodeStatusList(statusList.bitstring);
// "H4sIAAAAAAAAA-3BMQ0AAA..." (base64url string)

decodeStatusList

Decodes a compressed status list bitstring back to its raw Uint8Array form. The inverse of encodeStatusList.

function decodeStatusList(encoded: string): Uint8Array

Parameters

ParameterTypeRequiredDescription
encodedstringYesBase64url gzip-compressed bitstring

Returns

Uint8Array --- the decompressed bitstring.

Example

import { encodeStatusList, decodeStatusList } from "@credat/sdk";
 
const encoded = encodeStatusList(bitstring);
const decoded = decodeStatusList(encoded);
// decoded is identical to the original bitstring

createStatusListCredential

Creates a signed JWT credential wrapping the status list for publication. The JWT uses the statuslist+jwt media type as defined by the specification.

function createStatusListCredential(
  options: CreateStatusListCredentialOptions,
): string

Parameters

CreateStatusListCredentialOptions

ParameterTypeRequiredDefaultDescription
listStatusListDataYes---The status list to publish
issuerPrivateKeyUint8ArrayYes---Private key of the issuer
urlstringYes---Public URL where this credential will be hosted
algorithmAlgorithmNo"ES256"Signing algorithm ("ES256" or "EdDSA")

Returns

string --- a signed JWT with typ: "statuslist+jwt" containing the gzip-compressed bitstring.

Example

import { createStatusList, setRevocationStatus, createStatusListCredential, generateKeyPair } from "@credat/sdk";
 
const ownerKeyPair = generateKeyPair("ES256");
 
const statusList = createStatusList({
  id: "status-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
// Revoke a credential
setRevocationStatus(statusList, 42, true);
 
// Publish the status list as a signed JWT
const jwt = createStatusListCredential({
  list: statusList,
  issuerPrivateKey: ownerKeyPair.privateKey,
  url: "https://acme.com/.well-known/status/1",
});
 
// Host this JWT at the url so verifiers can fetch it

verifyStatusListCredential

Verifies a status list credential JWT and extracts the bitstring.

function verifyStatusListCredential(
  jwt: string,
  publicKey: Uint8Array,
): VerifyStatusListCredentialResult

Parameters

ParameterTypeRequiredDescription
jwtstringYesThe statuslist+jwt token to verify
publicKeyUint8ArrayYesIssuer’s public key

Returns

VerifyStatusListCredentialResult

FieldTypeDescription
validbooleanWhether the JWT signature is valid
bitstringUint8Array | undefinedThe decoded bitstring (present when valid is true)
issuerstring | undefinedIssuer DID from the JWT (present when valid is true)
errorsstring[] | undefinedError messages (present when valid is false)

Example

import { verifyStatusListCredential, isRevoked, generateKeyPair } from "@credat/sdk";
 
const ownerKeyPair = generateKeyPair("ES256");
 
// jwt was created with createStatusListCredential
const result = verifyStatusListCredential(jwt, ownerKeyPair.publicKey);
 
if (result.valid) {
  // Check if a specific credential is revoked
  const revoked = isRevoked(
    { bitstring: result.bitstring!, issuer: result.issuer!, id: "", size: result.bitstring!.length * 8 },
    42,
  );
  console.log("Credential 42 revoked:", revoked);
} else {
  console.error("Invalid status list:", result.errors);
}

Status list storage

Helper functions for persisting status lists via a StorageAdapter. Useful for production deployments where you need to persist status lists across restarts.

saveStatusList

function saveStatusList(storage: StorageAdapter, list: StatusListData): Promise<void>

Saves a status list to the storage adapter. Uses list.id as the storage key.

loadStatusList

function loadStatusList(storage: StorageAdapter, id: string): Promise<StatusListData | null>

Loads a status list by ID. Returns null if not found.

deleteStatusList

function deleteStatusList(storage: StorageAdapter, id: string): Promise<boolean>

Deletes a status list from storage.

listStatusLists

function listStatusLists(storage: StorageAdapter): Promise<StatusListData[]>

Returns all stored status lists.

Example

import {
  createStatusList,
  setRevocationStatus,
  saveStatusList,
  loadStatusList,
  listStatusLists,
  MemoryStorage,
} from "@credat/sdk";
 
const storage = new MemoryStorage();
 
// Create and persist
const statusList = createStatusList({
  id: "prod-list-1",
  issuer: "did:web:acme.com",
  url: "https://acme.com/.well-known/status/1",
});
 
await saveStatusList(storage, statusList);
 
// Later: load, revoke, save
const loaded = await loadStatusList(storage, "prod-list-1");
if (loaded) {
  setRevocationStatus(loaded, 42, true);
  await saveStatusList(storage, loaded);
}
 
// List all status lists
const all = await listStatusLists(storage);
console.log(`${all.length} status list(s) in storage`);
Last updated on
ScopesCrypto