credential-status-manager-db

A Typescript library for managing the status of Verifiable Credentials in a database using Bitstring Status List

Background

Credentials are dynamic artifacts with a lifecycle that goes well beyond issuance. This lifecycle is liable to span revocation, suspension, and expiry, among other common states. Many proposals have been put forth to capture these statuses in Verifiable Credentials. One of the most mature specifications for this is Bitstring Status List. This library provides an implementation of this specification that leverages database services like MongoDB and MySQL for storage and authentication.

Install

Node.js 20+ is recommended.

NPM

To install via NPM:

npm install @digitalcredentials/credential-status-manager-db

Development

To install locally (for development):

git clone https://github.com/digitalcredentials/credential-status-manager-db.git
cd credential-status-manager-db
npm install

Usage

Create credential status manager

The createStatusManager function is the only exported pure function of this library. It is an asynchronous function that accepts configuration options and returns a credential status manager that aligns with these options. Here are all the possible configuration options:

Key	Description	Type	Required
`databaseService`	name of the database service used to manage credential status data	`mongodb`	yes
`statusCredentialSiteOrigin`	base URL of status credentials managed by a given deployment	string	yes
`databaseUrl`	URL of the database instance used to manage credential status data	string	yes (if `databaseHost`, `databasePort`, `databaseUsername`, and `databasePassword` are not set)
`databaseHost`	host of the database instance used to manage credential status data	string	yes (if `databaseUrl` is not set)
`databasePort`	port of the database instance used to manage credential status data	number	yes (if `databaseUrl` is not set)
`databaseUsername`	username of user with read/write privileges on the database instance used to manage credential status data	string	yes (if `databaseUrl` is not set)
`databasePassword`	password associated with `databaseUsername`	string	yes (if `databaseUrl` is not set)
`databaseName`	name of the database instance used to manage credential status data	string	no (default: `credentialStatus`)
`statusCredentialTableName`	name of the database table used to manage status credentials (schema)	string	no (default: `StatusCredential`)
`userCredentialTableName`	name of the database table used to manage user credentials (schema)	string	no (default: `UserCredential`)
`configTableName`	name of the database table used to manage application configuration (schema)	string	no (default: `Config`)
`eventTableName`	name of the database table used to manage credential status events (schema)	string	no (default: `Event`)
`credentialEventTableName`	name of the database table used to manage the latest status event for a given credential (schema)	string	no (default: `CredentialEvent`)
`autoDeployDatabase`	whether or not to automatically create the database (`databaseName`) and the initial tables (`statusCredentialTableName` and `configTableName`)	string	no (default: `true`)
`didMethod`	name of the DID method used for signing	`key` \| `web`	yes
`didSeed`	seed used to deterministically generate DID	string	yes
`didWebUrl`	URL for `did:web`	string	yes (if `didMethod` = `web`)
`signStatusCredential`	whether or not to sign status credentials	boolean	no (default: `true`)
`signUserCredential`	whether or not to sign user credentials	boolean	no (default: `false`)

Here is a sample call to createStatusManager:

import { createStatusManager } from '@digitalcredentials/credential-status-manager-db';

const statusManager = await createStatusManager({
  databaseService: 'mongodb',
  statusCredentialSiteOrigin: 'https://credentials.example.edu/status',
  databaseUrl: 'mongodb+srv://testuser:testpass@domain.mongodb.net?retryWrites=false',
  databaseUsername: 'testuser',
  databasePassword: 'testpass',
  didMethod: 'key',
  didSeed: 'DsnrHBHFQP0ab59dQELh3uEwy7i5ArcOTwxkwRO2hM87CBRGWBEChPO7AjmwkAZ2' // Please create your own DID seed (see Dependencies section for detailed instructions)
});

Allocate status for credential

allocateStatus is an instance method that is called on a credential status manager initialized by createStatusManager. It is an asynchronous method that accepts a credential and an array of status purposes as input (options: revocation | suspension), records its status in a previously configured database instance, and returns the credential with status metadata attached.

Here is a sample call to allocateStatus:

const credential = {
  '@context': [
    'https://www.w3.org/ns/credentials/v2',
    'https://w3id.org/security/suites/ed25519-2020/v1'
  ],
  id: 'https://credentials.example.edu/3732',
  type: [
    'VerifiableCredential'
  ],
  issuer: 'did:key:z6MkhVTX9BF3NGYX6cc7jWpbNnR7cAjH8LUffabZP8Qu4ysC',
  validFrom: '2020-03-10T04:24:12.164Z',
  credentialSubject: {
    id: 'did:example:abcdef'
  }
};
const credentialWithStatus = await statusManager.allocateStatus({
  credential,
  statusPurposes: ['revocation', 'suspension']
});
console.log(credentialWithStatus);
/*
{
  '@context': [
    'https://www.w3.org/ns/credentials/v2'
  ],
  id: 'https://credentials.example.edu/3732',
  type: [ 'VerifiableCredential' ],
  issuer: 'did:key:z6MkhVTX9BF3NGYX6cc7jWpbNnR7cAjH8LUffabZP8Qu4ysC',
  validFrom: '2020-03-10T04:24:12.164Z',
  credentialSubject: { id: 'did:example:abcdef' },
  credentialStatus: [
    {
      id: 'https://credentials.example.edu/status/Uz42qSDSXTcoLH7kZ6ST#6',
      type: 'BitstringStatusListEntry',
      statusPurpose: 'revocation',
      statusListIndex: '6',
      statusListCredential: 'https://credentials.example.edu/status/Uz42qSDSXTcoLH7kZ6ST'
    },
    {
      id: 'https://credentials.example.edu/status/9kGimd8POqM88l32F9aT#3',
      type: 'BitstringStatusListEntry',
      statusPurpose: 'suspension',
      statusListIndex: '3',
      statusListCredential: 'https://credentials.example.edu/status/9kGimd8POqM88l32F9aT'
    }
  ]
}
*/

Note: You can also call allocateRevocationStatus(credential) to achieve the same effect as allocateStatus({ credential, statusPurposes: ['revocation'] }), allocateSuspensionStatus(credential) to achieve the same effect as allocateStatus({ credential, statusPurposes: ['suspension'] }), and allocateSupportedStatuses(credential) to achieve the same effect as allocateStatus({ credential, statusPurposes: ['revocation', 'suspension'] }).

Additionally, if the caller invokes allocateStatus multiple times with the same credential ID against the same instance of a credential status manager, the library will not allocate a new entry. It will just return a credential with the same status info as it did in the previous invocation.

Update status of credential

updateStatus is an instance method that is called on a credential status manager initialized by createStatusManager. It is an asynchronous method that accepts as input a credential ID, a status purpose (options: revocation | suspension), and whether to invalidate the status; records its new status in a previously configured database instance; and returns the status credential.

Here is a sample call to updateStatus:

const statusCredential = await statusManager.updateStatus({
  credentialId: credentialWithStatus.id,
  statusPurpose: 'revocation',
  invalidate: true
});
console.log(statusCredential);
/*
{
  '@context': [
    'https://www.w3.org/ns/credentials/v2'
  ],
  id: 'https://credentials.example.edu/status/Uz42qSDSXTcoLH7kZ6ST',
  type: [ 'VerifiableCredential', 'BitstringStatusListCredential' ],
  credentialSubject: {
    id: 'https://credentials.example.edu/status/Uz42qSDSXTcoLH7kZ6ST#list',
    type: 'BitstringStatusList',
    encodedList: 'H4sIAAAAAAAAA-3BMQ0AAAACIGf_0LbwAhoAAAAAAAAAAAAAAIC_AfqBUGnUMAAA',
    statusPurpose: 'revocation'
  },
  issuer: 'did:key:z6MkhVTX9BF3NGYX6cc7jWpbNnR7cAjH8LUffabZP8Qu4ysC',
  validFrom: '2024-03-10T00:00:00.000Z'
}
*/

Note: You can also call revokeCredential(credentialId) to achieve the same effect as updateStatus({ credentialId, statusPurpose: 'revocation', invalidate: true }) and suspendCredential(credentialId) to achieve the same effect as updateStatus({ credentialId, statusPurpose: 'suspension', invalidate: true }). Also note that unsuspendCredential(credentialId) will lift a suspension from a credential, while there is no equivalent reversal logic for revocation, since it is not allowed.

Check status of credential

getStatus is an instance method that is called on a credential status manager initialized by createStatusManager. It is an asynchronous method that accepts a credential ID as input and returns status information for the credential.

Here is a sample call to getStatus:

const credentialStatus = await statusManager.getStatus(credentialWithStatus.id);
console.log(credentialStatus);
/*
{
  revocation: {
    statusCredentialId: 'Uz42qSDSXTcoLH7kZ6ST',
    statusListIndex: 6,
    valid: true
  },
  suspension: {
    statusCredentialId: '9kGimd8POqM88l32F9aT',
    statusListIndex: 3,
    valid: false
  }
}
*/

Schemas

There is a lot of data that is managed by this service. In this section, we will outline the schemas for each database table maintained by a given deployment.

`StatusCredential`

Key	Description	Type
`id`	ID of the status credential database record	string
`credential`	Bitstring Status List Verifiable Credential	object (BitstringStatusListCredential)

`UserCredential`

Key	Description	Type
`id`	ID of the user credential database record	string
`issuer`	ID of the issuer of the credential	string
`subject`	ID of the subject of the credential	string
`statusInfo`	mapping from status purpose to status info	object
`statusInfo[PURPOSE].statusCredentialId`	ID of the status credential associated with the credential for a given purpose	string
`statusInfo[PURPOSE].statusListIndex`	position allocated on the status credential for the credential for a given purpose	number
`statusInfo[PURPOSE].valid`	validity of the credential according to the status credential tracking its status for a given purpose	boolean

`Config`

Key	Description	Type
`id`	ID of the config database record	string
`statusCredentialSiteOrigin`	base URL of status credentials managed by a given deployment	string
`statusCredentialInfo`	mapping from status purpose to status credential info	object
`statusCredentialInfo[PURPOSE].latestStatusCredentialId`	ID of the latest status credential to be created for a given purpose in a given deployment	string
`statusCredentialInfo[PURPOSE].latestCredentialsIssuedCounter`	number of credentials issued against the latest status credential for a given purpose in a given deployment	number
`statusCredentialInfo[PURPOSE].statusCredentialsCounter`	total number of status credentials for a given purpose in a given deployment	number
`credentialsIssuedCounter`	total number of credentials issued in a given deployment	number

`Event`

Key	Description	Type
`id`	ID of the event database record	string
`timestamp`	ISO timestamp of the moment that the event was recorded	string
`credentialId`	ID of the credential associated with the event	string
`statusPurpose`	name of the purpose of the credential status whose modification is being tracked by the event	`revocation` \| `suspension` (see `statusPurpose` here)
`valid`	validity of the credential that is being applied by the event	boolean

`CredentialEvent`

Key	Description	Type
`credentialId`	ID of a previously issued credential database record	string
`eventId`	ID of the latest status event database record for credential with ID `credentialId`	string

Dependencies

Generate DID seeds

In order to generate a DID seed, you will need to use software that is capable of creating it in a format that corresponds to a valid DID document. Here is sample code that does this:

import { generateSecretKeySeed } from '@digitalcredentials/bnid';

// Set `didSeed` key to this value
const secretKeySeed = await generateSecretKeySeed();

If didMethod = web, you must also generate a DID document and host it at didWebUrl/.well-known/did.json. Here is sample code that does this:

import { decodeSecretKeySeed } from '@digitalcredentials/bnid';
import { Ed25519VerificationKey2020 } from '@digitalcredentials/ed25519-verification-key-2020';
import { X25519KeyAgreementKey2020 } from '@digitalcredentials/x25519-key-agreement-key-2020';
import * as DidWeb from '@interop/did-web-resolver';
import { CryptoLD } from '@digitalcredentials/crypto-ld';

const cryptoLd = new CryptoLD();
cryptoLd.use(Ed25519VerificationKey2020);
cryptoLd.use(X25519KeyAgreementKey2020);
const didWebDriver = DidWeb.driver({ cryptoLd });

const decodedSeed = decodeSecretKeySeed({secretKeySeed});

// Host this document at `didWebUrl`/.well-known/did.json
const didWebUrl = 'https://example.edu';
const didDocument = didWebDriver.generate({ url: didWebUrl, seed: decodedSeed });

Contribute

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

credential-status-manager-db

Table of Contents

Background

Install

NPM

Development

Usage

Create credential status manager

Allocate status for credential

Update status of credential

Check status of credential

Schemas

`StatusCredential`

`UserCredential`

`Config`

`Event`

`CredentialEvent`

Dependencies

Generate DID seeds

Contribute

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

credential-status-manager-db

Table of Contents

Background

Install

NPM

Development

Usage

Create credential status manager

Allocate status for credential

Update status of credential

Check status of credential

Schemas

StatusCredential

UserCredential

Config

Event

CredentialEvent

Dependencies

Generate DID seeds

Contribute

License

`StatusCredential`

`UserCredential`

`Config`

`Event`

`CredentialEvent`