@openverifiable/open-verifiable-id-sdk

v0.0.5

Published

16 days ago

Open Verifiable ID SDK - Reference implementation for decentralized identity and verifiable credentials

0High
0Medium
0Low

lukenispel

verifiable-credentials did decentralized-identity w3c vc-2.0 open-verifiable identity credentials

🚀 Open Verifiable ID SDK

Reference implementation for decentralized identity and verifiable credentials based on W3C VC 2.0 and DIF standards

📋 Overview

The Open Verifiable ID SDK is a comprehensive TypeScript implementation of decentralized identity standards, designed to provide a secure, cross-platform foundation for verifiable credential operations. This SDK serves as the reference implementation for the Open Verifiable ecosystem.

✨ Key Features

🌐 Cross-Platform: Native support for Node.js, Browser, and React Native
🔐 W3C VC 2.0 Compliant: Full support for W3C Verifiable Credentials 2.0 with Data Integrity Proofs
🏗️ Modular Architecture: Extensible agent system with plugin support
🔒 Secure by Default: Hardware-backed key storage
📱 Offline First: Full offline capability with intelligent sync
🤝 Trust Registry: Local-first trust validation with community import
🧪 Comprehensive Testing: 90%+ test coverage with cross-platform validation
📦 End-to-End Workflows: Complete DID, QR code, and storage workflows

🏗️ Architecture

Based on 14 comprehensive ADRs, the SDK implements a 4-layer architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Developer Tools Layer                    │
│  SDK Tools │ Type Generation │ Testing Framework │ LLM Docs │
├─────────────────────────────────────────────────────────────┤
│                    Integration Layer                        │
│ Trust Registry │ Schema Registry │ Storage Adapters │
├─────────────────────────────────────────────────────────────┤
│                       Agent Layer                          │
│   User Agent  │ Package Agent │ Parent Agent │ Service Agent│
├─────────────────────────────────────────────────────────────┤
│                    Core SDK Layer                          │
│ W3C VC 2.0 │ DID Management │ Secure Storage │ Crypto Ops  │
└─────────────────────────────────────────────────────────────┘

🚧 Implementation Status

✅ Phase 1: Foundation (COMPLETED)

[x] Project Structure: Cross-platform monorepo with TypeScript
[x] Platform Detection: ADR-0013 compliant platform capabilities
[x] Type System: Comprehensive TypeScript definitions for all components
[x] Agent Architecture: ADR-0007 extensible agent system with plugin support
[x] Configuration System: Platform-aware SDK initialization
[x] W3C VC 2.0 Migration: Data Integrity Proofs implementation
[x] Secure Storage: Cross-platform encrypted storage (ADR-0006)
[x] DID Management: Enhanced multi-method DID operations
[x] Core Agent Implementation: UserAgent, PackageAgent, ParentAgent, ServiceAgent
[x] Comprehensive Testing: Unit tests, integration tests, and e2e workflows

🔄 Phase 2: Core Features (IN PROGRESS)

[ ] Trust Registry Client: Local-first trust validation (ADR-0002)
[ ] Revocation Checking: Credential revocation system (ADR-0003)
[ ] Schema Registry Integration: Type generation from schemas (ADR-0008)
[ ] CLI Tooling: Comprehensive command-line interface (ADR-0010)
[ ] Advanced Testing Framework: 90%+ coverage testing system (ADR-0009)

📋 Phase 3: Advanced Features (PLANNED)

[ ] Offline Caching: Intelligent credential caching and sync (ADR-0005)
[ ] Performance Optimization: Sub-2ms validation targets (ADR-0014)
[ ] Error Handling: Comprehensive error recovery (ADR-0012)

🛠️ Phase 4: Developer Experience (PLANNED)

[ ] LLM Integration: AI-friendly documentation and code generation (ADR-0011)
[ ] Cross-Platform Testing: Node.js, Browser, React Native validation (ADR-0013)
[ ] Documentation: Complete API documentation and examples
[ ] Community Testing: Open source validation and feedback

🚀 Quick Start

Installation

npm install @open-verifiable/id-sdk

Basic Usage

import { 
  PackageAgent,
  UserAgent,
  ParentAgent,
  ServiceAgent
} from '@open-verifiable/id-sdk';

// Create a package agent for software package identity
const packageAgent = new PackageAgent({
  packageName: '@my-org/my-package',
  packageVersion: '1.0.0'
});

await packageAgent.initialize();

// Create a DID
const { did } = await packageAgent.createDID('key', {
  alias: 'my-package-did'
});

// Issue a verifiable credential
const credential = await packageAgent.issueCredential({
  '@context': ['https://www.w3.org/ns/credentials/v2'],
  type: ['VerifiableCredential', 'PackageIdentityCredential'],
  issuer: did,
  credentialSubject: {
    id: 'pkg:npm/@my-org/my-package',
    name: '@my-org/my-package',
    version: '1.0.0',
    description: 'My awesome package'
  },
  validFrom: new Date().toISOString()
});

// Verify the credential
const verificationResult = await packageAgent.verifyCredential(credential);
console.log('Credential valid:', verificationResult.isValid);

End-to-End Workflows

The SDK includes comprehensive e2e workflow tests demonstrating real-world usage:

// DID Import and Credential Workflow
import { runDIDWorkflow } from '@open-verifiable/id-sdk/examples';

// Complete workflow: key validation → DID creation → credential issuance → verification → storage
await runDIDWorkflow();

// QR Code Credential Exchange
import { runQRWorkflow } from '@open-verifiable/id-sdk/examples';

// QR workflow: credential creation → QR generation → data encoding → decoding → verification
await runQRWorkflow();


// Storage and Backup
import { runStorageWorkflow } from '@open-verifiable/id-sdk/examples';

// Storage workflow: credential creation → storage → retrieval → backup → restore
await runStorageWorkflow();

Migration from Legacy SDKs

The SDK provides backward compatibility during the transition:

// Legacy SDK functions will be supported
import { 
  createDID,    // ✅ Backward compatible
  signVC,       // ✅ Backward compatible  
  verifyVC      // ✅ Backward compatible
} from '@openverifiable/open-verifiable-id-sdk';

// New SDK features
import { 
  TrustRegistryClient
} from '@openverifiable/open-verifiable-id-sdk';

🧪 Testing

The SDK includes a comprehensive test suite with 90%+ coverage:

Test Structure

tests/
├── unit/                    # Unit tests for individual components
│   ├── agents/             # Agent type tests
│   ├── did/                # DID management tests
│   ├── storage/            # Storage and encryption tests
│   └── credentialing/      # Credential operations tests
├── integration/            # Integration tests for component interactions
├── e2e/                   # End-to-end workflow tests
│   ├── did-workflow.test.ts      # Complete DID workflows
│   ├── qr-workflow.test.ts       # QR code exchange workflows
│   └── storage-workflow.test.ts  # Storage and backup workflows
├── security/              # Security and cryptographic tests
└── performance/           # Performance and benchmark tests

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:security
npm run test:performance

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📚 Documentation

Architecture Decision Records (ADRs)

The SDK implementation is based on 14 comprehensive ADRs:

ADR-0001: W3C VC 2.0 Migration Strategy
ADR-0002: Trust Registry Client Integration
ADR-0003: Credential Revocation Checking
ADR-0005: Offline Credential Caching and Sync
ADR-0006: Secure Local Storage
ADR-0007: Agent Architecture and Extensibility
ADR-0009: Testing & Validation Strategy
ADR-0010: Developer Experience & CLI Tooling
ADR-0011: LLM Development Integration
ADR-0012: Error Handling & Recovery Strategy
ADR-0013: Cross-Platform Compatibility
ADR-0014: SDK Performance Optimization

Examples and Demos

DID Import Workflow: Complete DID creation and credential workflow
QR Code Demo: QR code generation and credential exchange

🛠️ Development

Prerequisites

Node.js 18+
TypeScript 5.0+
Git

Setup

# Clone the repository
git clone https://github.com/open-verifiable/open-verifiable-id-sdk.git
cd open-verifiable-id-sdk

# Install dependencies
npm install

# Run type checking
npm run type-check

# Build for all platforms
npm run build

# Run tests
npm test

# Run e2e tests
npm run test:e2e

Platform-Specific Development

# Node.js development
npm run dev:node

# Browser development
npm run dev:browser

# Test on specific platforms
npm run test:node
npm run test:browser
npm run test:react-native

Scripts and Utilities

# Generate types from schemas
npm run generate:types

# Validate schemas
npm run validate:schemas

# Run ADR inventory
npm run inventory:adrs

🤝 Contributing

We welcome contributions from the community! Please see our Contributing Guidelines for details.

Development Status

This SDK has completed its core implementation and is ready for Phase 2 features. Current focus areas:

Trust Registry: Local-first trust validation system
Revocation Checking: Credential revocation and status checking
Schema Registry: Integration with Open Verifiable Schema Registry
CLI Tooling: Developer experience improvements
Performance Optimization: Sub-2ms validation targets

Getting Involved

📧 Email: [email protected]
💬 Discussions: GitHub Discussions
🐛 Issues: GitHub Issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Open Verifiable Community: For governance and standards development
W3C Credentials Community Group: For W3C VC 2.0 specifications
DIF (Decentralized Identity Foundation): For interoperability standards
OriginVault Team: For the original implementation inspiration

🔗 Related Projects

Open Verifiable Schema Registry: Schema definitions and type generation
Open Verifiable Architecture Decision Records: Governance and technical decisions
Legacy SDK: Original implementation reference

Built with ❤️ by the Open Verifiable Community