@jeswr/vc-cli NPM

Verifiable Credentials CLI and API

This package provides both a CLI and programmatic API for working with Verifiable Credentials, including CID generation, credential signing, verification, and proof derivation.

Installation

npm install -g @jeswr/vc-cli

⚠️ Warning

This library is currently in development and is not intended for production use. It is provided for testing and educational purposes only. Use at your own risk.

API Reference

`generateCIDDocument(controller, options)`

Generates a new CID (Cryptographic Identifier) document.

import { generateCIDDocument } from '@your-package-name';

const { cid, privateKeys } = await generateCIDDocument('did:example:alice', {
  includeEd25519: true,  // optional, defaults to true
  includeBBS: true       // optional, defaults to true
});

Parameters:

controller (string): The DID to use as the controller
options (object, optional):
- includeEd25519 (boolean): Whether to include Ed25519 signature type
- includeBBS (boolean): Whether to include BBS+ signature type

Returns:

{ cid: Object, privateKeys: Object }: The generated CID document and private keys

`signCredential(options)`

Signs a verifiable credential using a CID document and private keys.

import { signCredential } from '@your-package-name';

const signedCredential = await signCredential({
  cid: cidDocument,
  privateKeys: privateKeysObject,
  document: credentialDocument,
  keyId: 'verification-method-id',
  credentialId: 'optional-credential-id',
  subjectId: 'optional-subject-id'
});

Parameters:

options (object):
- cid (Object): CID document
- privateKeys (Object): Private keys object
- document (Object): Document to sign
- keyId (string): ID of the key to use for signing
- credentialId (string, optional): ID for the credential
- subjectId (string, optional): ID for the credential subject

Returns:

Object: The signed credential

`verifyCredential(options)`

Verifies a verifiable credential using a CID document.

import { verifyCredential } from '@your-package-name';

const isValid = await verifyCredential({
  cid: cidDocument,
  document: signedCredential
});

Parameters:

options (object):
- cid (Object): CID document
- document (Object): Verifiable credential to verify

Returns:

boolean: Whether the verification was successful

`deriveProof(options)`

Creates a derived BBS proof from a signed input BBS document.

import { deriveProof } from '@your-package-name';

const derivedDocument = await deriveProof({
  document: signedBBSDocument,
  revealPointers: ['/credentialSubject/name', '/credentialSubject/age']
});

Parameters:

options (object):
- document (Object): Signed BBS document
- revealPointers (string[]): Array of JSON pointers to reveal

Returns:

Object: The derived document

`preprocessBBSVerification(options)`

Preprocesses BBS verification data from derived credentials.

import { preprocessBBSVerification } from '@your-package-name';

const preprocessedData = await preprocessBBSVerification({
  document: derivedBBSDocument,
  cid: cidDocument
});

Parameters:

options (object):
- document (Object): Derived BBS document
- cid (Object): CID document

Returns:

Object: The preprocessed data containing verification information

`preprocessEd25519Verification(options)`

Preprocesses Ed25519 verification data from signed credentials.

import { preprocessEd25519Verification } from '@your-package-name';

const preprocessedData = await preprocessEd25519Verification({
  document: signedEd25519Document,
  cid: cidDocument
});

Parameters:

options (object):
- document (Object): Signed Ed25519 document
- cid (Object): CID document

Returns:

Object: The preprocessed data containing verification information

`collectDocuments(options)`

Collects JSON-LD documents into a single Turtle file, excluding proofs.

import { collectDocuments } from '@your-package-name';

await collectDocuments({
  documents: ['path/to/doc1.jsonld', 'path/to/doc2.jsonld'],
  outputPath: 'output.ttl'
});

Parameters:

options (object):
- documents (string[]): Array of JSON-LD document paths
- outputPath (string): Output path for Turtle file (must end with .ttl)

Returns:

Promise<void>

CLI Commands

Generate CID

Generate a new CID document with cryptographic keys.

vc-cli generate-cid -c <controller-did> [options]

Options:

-c, --controller <controller>: Controller DID (required)
-o, --output <path>: Output path for CID document (file or directory)
-k, --keys <path>: Path to save private keys JSON file
--no-ed25519: Exclude Ed25519 signature type
--no-bbs: Exclude BBS+ signature type
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Examples:

# Generate CID with default options
vc-cli generate-cid -c did:example:123

# Generate CID and save to specific files
vc-cli generate-cid -c did:example:123 -o cid.json -k keys.json

# Generate CID with custom document loader content
vc-cli generate-cid -c did:example:123 --document-loader-content loader-content.json

Sign Credential

Sign a verifiable credential using a CID document and private keys.

vc-cli sign-credential -c <cid-path> -k <keys-path> -d <document-path> -i <key-id> -o <output-path>

Options:

-c, --cid <path>: Path to CID document (required)
-k, --keys <path>: Path to private keys JSON file (required)
-d, --document <path>: Path to JSON-LD document to sign (required)
-i, --key-id <id>: ID of the key to use for signing (required)
-o, --output <path>: Output path for signed credential (required)
--credential-id <id>: ID for the credential (optional)
--subject-id <id>: ID for the credential subject (optional)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Sign a credential with default options
vc-cli sign-credential -c cid.json -k keys.json -d credential.json -i key-1 -o signed-credential.json

# Sign a credential with custom IDs and document loader content
vc-cli sign-credential -c cid.json -k keys.json -d credential.json -i key-1 -o signed-credential.json --credential-id "urn:uuid:123" --subject-id "did:example:subject" --document-loader-content loader-content.json

Verify Credential

Verify a verifiable credential using a CID document.

vc-cli verify-credential -c <cid-path> -d <document-path>

Options:

-c, --cid <path>: Path to CID document (required)
-d, --document <path>: Path to verifiable credential to verify (required)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Verify a credential with default options
vc-cli verify-credential -c cid.json -d signed-credential.json

# Verify a credential with custom document loader content
vc-cli verify-credential -c cid.json -d signed-credential.json --document-loader-content loader-content.json

Derive Credential

Create a derived BBS proof from a signed credential, revealing only specific fields while maintaining the cryptographic integrity of the original credential.

vc-cli derive-proof -d <document-path> -r <pointers> -o <output-path>

Options:

-d, --document <path>: Path to signed BBS document (required)
-r, --reveal <pointers>: Comma-separated list of JSON pointers to reveal (required)
-o, --output <path>: Output path for derived document (required)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Derive a credential revealing only specific fields
vc-cli derive-proof -d signed-credential.json -r '/credentialSubject/givenName,/credentialSubject/familyName' -o derived-credential.json

# Derive a credential with custom document loader content
vc-cli derive-proof -d signed-credential.json -r '/credentialSubject/givenName,/credentialSubject/familyName' -o derived-credential.json --document-loader-content loader-content.json

BBS Verify Preprocess

Preprocess BBS verification data from derived credentials for efficient verification.

vc-cli bbs-verify-preprocess -d <document-path> -c <cid-path> -o <output-path>

Options:

-d, --document <path>: Path to derived BBS document or directory containing derived BBS documents (required)
-c, --cid <path>: Path to CID document (required)
-o, --output <path>: Output path for preprocessed data (file or directory) (required)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Preprocess a single derived BBS document
vc-cli bbs-verify-preprocess -d derived-credential.json -c cid.json -o preprocessed.json

# Preprocess with custom document loader content
vc-cli bbs-verify-preprocess -d derived-credential.json -c cid.json -o preprocessed.json --document-loader-content loader-content.json

Ed25519 Verify Preprocess

Preprocess Ed25519 verification data from signed credentials for efficient verification.

vc-cli ed25519-verify-preprocess -d <document-path> -c <cid-path> -o <output-path>

Options:

-d, --document <path>: Path to signed Ed25519 document or directory containing signed Ed25519 documents (required)
-c, --cid <path>: Path to CID document (required)
-o, --output <path>: Output path for preprocessed data (file or directory) (required)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Preprocess a single Ed25519 document
vc-cli ed25519-verify-preprocess -d signed-credential.json -c cid.json -o preprocessed.json

# Preprocess with custom document loader content
vc-cli ed25519-verify-preprocess -d signed-credential.json -c cid.json -o preprocessed.json --document-loader-content loader-content.json

Generate

Generate CIDs, sign credentials, and create derived proofs in a batch process.

vc-cli generate [options]

Options:

-c, --cids <ids>: Comma-separated list of CID controller DIDs default: "did:example:alice,did:example:bob,did:example:charlie,did:example:dave"
-d, --documents <paths>: Comma-separated list of credential document paths to sign default: all mock credentials
-s, --signatures <types>: Comma-separated list of signature types to use (bbs,ed25519) default: "bbs,ed25519"
--no-derive: Skip creating derived proofs for BBS signatures
--no-preprocess: Skip preprocessing derived proofs (enabled by default)
-o, --output-dir <path>: Output directory for generated files default: "./generated"
--distribute: Distribute documents across CIDs instead of having each CID sign all documents
--collect: Collect all generated files into a single Turtle file named collected.ttl in the output directory
--subject-id <id>: ID for the credential subject (optional, defaults to a random DID)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Generate with default options
vc-cli generate

# Generate with custom document loader content
vc-cli generate --document-loader-content loader-content.json

# Generate with custom CIDs, documents, and document loader content
vc-cli generate -c "did:example:alice,did:example:bob" -d "./mocks/residence.jsonld,./mocks/education.jsonld" --document-loader-content loader-content.json

Collect

Collect multiple JSON-LD documents into a single Turtle file, excluding proofs.

vc-cli collect -d <directory-path> -o <output-path>

Options:

-d, --directory <path>: Directory containing JSON-LD documents (required)
-o, --output <path>: Output path for Turtle file (must end with .ttl) (required)
--document-loader-content <path>: Path to JSON file containing predefined document loader responses

Example:

# Collect all JSON-LD documents from a directory into a single Turtle file
vc-cli collect -d ./generated -o output.ttl

# Collect with custom document loader content
vc-cli collect -d ./generated -o output.ttl --document-loader-content loader-content.json

Document Loader Content

The --document-loader-content option allows you to provide predefined responses for specific URLs used in JSON-LD document processing. This is useful for:

Testing with mock data
Working offline
Ensuring consistent responses
Avoiding network requests for known contexts and schemas

The document loader content file should be a JSON file with the following structure:

{
  "https://example.org/context.json": {
    "@context": {
      // context content
    }
  },
  "https://example.org/schema.json": {
    // schema content
  }
}

When a URL is requested during document processing, the document loader will: 1. First check if the URL exists in the provided content 2. If found, return that content immediately 3. If not found, fall back to the existing caching behavior 4. Finally, if not in cache, use the default document loader or fetch from the network

This allows for more control over the document loading process and can help improve performance and reliability in various scenarios.