Credentials Module

The credentials module provides W3C Verifiable Credentials backed by BSV MasterCertificate cryptography. It includes schema definition, credential issuance/verification/revocation, and wallet-side acquisition.

Source: src/modules/credentials.ts

CredentialSchema

Defines the fields, validation, and computed values for a credential type.

Constructor

new CredentialSchema(config: CredentialSchemaConfig)

Parameter	Type	Description
config.id	string	Unique schema identifier
config.name	string	Human-readable name
config.description	string?	Optional description
config.certificateTypeBase64	string?	Custom certificate type (default: base64 of id)
config.fields	CredentialFieldSchema[]	Field definitions
config.fieldGroups	{ key, label }[]?	Optional field grouping
config.validate	(values) => string | null	Custom validation function
config.computedFields	(values) => Record<string, string>	Add/transform fields at issuance

schema.validate()

validate(values: Record<string, string>): string | null

Validate field values. Returns null if valid, or an error message string.

Checks:

1. Required fields are present and non-empty

2. Custom validate function (if provided)

schema.computeFields()

computeFields(values: Record<string, string>): Record<string, string>

Merge computed fields into values. Returns a new object with original values plus computed additions.

schema.getInfo()

getInfo(): {
  id: string
  name: string
  description?: string
  certificateTypeBase64: string
  fieldCount: number
}

schema.getConfig()

getConfig(): CredentialSchemaConfig

Returns the full configuration object. Used when creating a CredentialIssuer.

CredentialIssuer

Issues, verifies, and revokes Verifiable Credentials.

CredentialIssuer.create()

static async create(config: CredentialIssuerConfig): Promise<CredentialIssuer>

Parameter	Type	Required	Description
config.privateKey	string	Yes	Hex-encoded private key
config.schemas	CredentialSchemaConfig[]	No	Schema definitions
config.revocation.enabled	boolean	No	Enable on-chain revocation
config.revocation.wallet	WalletInterface	If enabled	Wallet for creating revocation UTXOs
config.revocation.store	RevocationStore	No	Storage backend (default: MemoryRevocationStore)

Throws: CredentialError if revocation is enabled but no wallet is provided.

issuer.issue()

async issue(
  subjectIdentityKey: string,
  schemaId: string,
  fields: Record<string, string>
): Promise<VerifiableCredential>

Issue a Verifiable Credential.

Parameter	Type	Description
subjectIdentityKey	string	Subject's compressed public key
schemaId	string	ID of a registered schema
fields	Record<string, string>	Field values

What happens:

1. Validates fields against the schema

2. Merges computed fields

3. If revocation enabled: creates a hash-lock UTXO (OP_SHA256 <hash> OP_EQUAL, 1 satoshi), saves secret to store

4. Issues a MasterCertificate

5. Wraps in W3C Verifiable Credential format

Throws: CredentialError if schema not found or validation fails.

issuer.verify()

async verify(vc: VerifiableCredential): Promise<VerificationResult>

Verify a Verifiable Credential.

Returns:

{
  valid: boolean      // true if all checks pass
  revoked: boolean    // true if credential has been revoked
  errors: string[]    // list of validation errors
  issuer?: string     // issuer DID
  subject?: string    // subject DID
  type?: string       // credential types joined
}

Checks:

1. W3C @context is present

2. VerifiableCredential type is present

3. Proof and signature are present

4. BSV certificate data is present

5. Revocation status (checks if secret still exists in store)

issuer.revoke()

async revoke(serialNumber: string): Promise<{ txid: string }>

Revoke a credential by spending its hash-lock UTXO.

Parameter	Type	Description
serialNumber	string	Certificate serial number

What happens:

1. Loads the revocation record (secret + outpoint) from the store

2. Creates an unlocking script with the secret

3. Spends the hash-lock UTXO

4. Deletes the record from the store

Throws: CredentialError if revocation is not enabled, or the certificate is not found/already revoked.

issuer.isRevoked()

async isRevoked(serialNumber: string): Promise<boolean>

Check if a credential has been revoked. Returns true if the revocation record no longer exists in the store.

issuer.getInfo()

getInfo(): {
  publicKey: string
  did: string
  schemas: { id: string; name: string }[]
}

Revocation Stores

MemoryRevocationStore

In-memory storage for browser and tests.

import { MemoryRevocationStore } from '@bsv/simple/browser'
const store = new MemoryRevocationStore()

FileRevocationStore

File-based storage for Node.js servers.

const { FileRevocationStore } = await import('@bsv/simple/server')
const store = new FileRevocationStore()                        // default: .revocation-secrets.json
const store = new FileRevocationStore('/path/to/secrets.json') // custom path

Add the secrets file to .gitignore.

RevocationStore Interface

Both stores implement:

interface RevocationStore {
  save(serialNumber: string, record: RevocationRecord): Promise<void>
  load(serialNumber: string): Promise<RevocationRecord | undefined>
  delete(serialNumber: string): Promise<void>
  has(serialNumber: string): Promise<boolean>
  findByOutpoint(outpoint: string): Promise<boolean>
}

Standalone Utilities

toVerifiableCredential()

function toVerifiableCredential(
  cert: CertificateData,
  issuerKey: string,
  options?: { credentialType?: string }
): VerifiableCredential

Wrap a BSV CertificateData into a W3C Verifiable Credential envelope.

toVerifiablePresentation()

function toVerifiablePresentation(
  credentials: VerifiableCredential[],
  holderKey: string
): VerifiablePresentation

Wrap an array of VCs into a W3C Verifiable Presentation.

Wallet Methods

acquireCredential()

async acquireCredential(config: {
  serverUrl: string
  schemaId?: string
  fields?: Record<string, string>
  replaceExisting?: boolean
}): Promise<VerifiableCredential>

Acquire a Verifiable Credential from a remote issuer server.

Parameter	Type	Default	Description
config.serverUrl	string	required	Issuer server base URL
config.schemaId	string	—	Schema to request
config.fields	Record<string, string>	—	Field values to submit
config.replaceExisting	boolean	true	Revoke existing certs first

listCredentials()

async listCredentials(config: {
  certifiers: string[]
  types: string[]
  limit?: number
}): Promise<VerifiableCredential[]>

List wallet certificates wrapped as Verifiable Credentials.

createPresentation()

createPresentation(credentials: VerifiableCredential[]): VerifiablePresentation

Wrap Verifiable Credentials into a Verifiable Presentation. Synchronous.