OrbitDB WebAuthn DID Identity Provider

🚀 Try the Live Demo - Interactive WebAuthn demo with biometric authentication

A hardware-secured identity provider for OrbitDB using WebAuthn authentication. This provider enables hardware -secured database access (Ledger, Yubikey etc.) where private keys never leave the secure hardware element and biometric authentication via Passkey.

Features

• 🔐 Hardware-secured authentication - Uses WebAuthn with platform authenticators (Face ID, Touch ID, Windows Hello)
• 🚫 Private keys never leave hardware - Keys are generated and stored in secure elements
• 🌐 Cross-platform compatibility - Works across modern browsers and platforms
• 📱 Biometric authentication - Seamless user experience with fingerprint, face recognition, or PIN
• 🔒 Quantum-resistant - P-256 elliptic curve cryptography with hardware backing
• 🆔 DID-based identity - Generates deterministic did:key DIDs based on WebAuthn credentials

Installation

npm install orbitdb-identity-provider-webauthn-did

Basic Usage

import { createOrbitDB, Identities, IPFSAccessController } from '@orbitdb/core'
import { createHelia } from 'helia'
import { 
  WebAuthnDIDProvider,
  OrbitDBWebAuthnIdentityProviderFunction,
  registerWebAuthnProvider,
  checkWebAuthnSupport,
  storeWebAuthnCredential,
  loadWebAuthnCredential
} from 'orbitdb-identity-provider-webauthn-did'

// Check WebAuthn support
const support = await checkWebAuthnSupport()
if (!support.supported) {
  console.error('WebAuthn not supported:', support.message)
  return
}

// Create or load WebAuthn credential
let credential = loadWebAuthnCredential()

if (!credential) {
  // Create new WebAuthn credential (triggers biometric prompt)
  credential = await WebAuthnDIDProvider.createCredential({
    userId: '[email protected]',
    displayName: 'Alice Smith'
  })
  
  // Store credential for future use
  storeWebAuthnCredential(credential)
}

// Register the WebAuthn provider
registerWebAuthnProvider()

// Create identities instance
const identities = await Identities()

// Create WebAuthn identity
const identity = await identities.createIdentity({
  provider: OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: credential })
})

// Create IPFS instance - see OrbitDB Liftoff example for full libp2p configuration:
// https://github.com/orbitdb/orbitdb/tree/main/examples/liftoff
const ipfs = await createHelia()

// Create OrbitDB instance with WebAuthn identity
const orbitdb = await createOrbitDB({
  ipfs,
  identities,
  identity
})

// Create a database - will require biometric authentication for each write
const db = await orbitdb.open('my-secure-database', {
  type: 'keyvalue',
  accessController: IPFSAccessController({
    write: [identity.id] // Only this WebAuthn identity can write
  })
})

// Adding data will trigger biometric prompt
await db.put('greeting', 'Hello, secure world!')

Advanced Configuration

LibP2P and IPFS Setup

For an example libp2p configuration. See the OrbitDB Liftoff example for example libp2p setup including:

Credential Creation Options

const credential = await WebAuthnDIDProvider.createCredential({
  userId: 'unique-user-identifier',
  displayName: 'User Display Name',
  domain: 'your-app-domain.com', // Defaults to current hostname
  timeout: 60000 // Authentication timeout in milliseconds
})

Identity Provider Configuration

// Manual identity provider setup
import { OrbitDBWebAuthnIdentityProviderFunction } from 'orbitdb-identity-provider-webauthn-did'

const identityProvider = OrbitDBWebAuthnIdentityProviderFunction({
  webauthnCredential: credential
})

const orbitdb = await createOrbitDB({
  identity: {
    provider: identityProvider
  }
})

WebAuthn Support Detection

The library provides utilities to check WebAuthn compatibility:

import { checkWebAuthnSupport, WebAuthnDIDProvider } from 'orbitdb-identity-provider-webauthn-did'

// Comprehensive support check
const support = await checkWebAuthnSupport()
console.log({
  supported: support.supported,
  platformAuthenticator: support.platformAuthenticator,
  message: support.message
})

// Quick checks
const isSupported = WebAuthnDIDProvider.isSupported()
const hasBiometric = await WebAuthnDIDProvider.isPlatformAuthenticatorAvailable()

Browser Compatibility

| Browser | Version | Face ID | Touch ID | Windows Hello | |---------|---------|---------|----------|---------------| | Chrome | 67+ | ✅ | ✅ | ✅ | | Firefox | 60+ | ✅ | ✅ | ✅ | | Safari | 14+ | ✅ | ✅ | ✅ | | Edge | 18+ | ✅ | ✅ | ✅ |

Platform Support

• macOS: Face ID, Touch ID
• iOS: Face ID, Touch ID
• Windows: Windows Hello (face, fingerprint, PIN)
• Android: Fingerprint, face unlock, screen lock
• Linux: FIDO2 security keys, fingerprint readers

Credential Storage Utilities

The library provides utility functions for properly storing and loading WebAuthn credentials:

Using the Built-in Utilities:

import { 
  storeWebAuthnCredential, 
  loadWebAuthnCredential, 
  clearWebAuthnCredential 
} from 'orbitdb-identity-provider-webauthn-did'

// Store credential (handles Uint8Array serialization automatically)
storeWebAuthnCredential(credential)

// Load credential (handles Uint8Array deserialization automatically)  
const credential = loadWebAuthnCredential()

// Clear stored credential
clearWebAuthnCredential()

// Use custom storage keys
storeWebAuthnCredential(credential, 'my-custom-key')
const credential = loadWebAuthnCredential('my-custom-key')

Why we provide these utilities: WebAuthn credentials contain Uint8Array objects that don't serialize properly with JSON.stringify(). Without proper serialization, the public key coordinates become empty arrays after loading from localStorage, causing DID generation to fail. Our utility functions handle this complexity automatically and ensure proper did:key format generation.

Verification Utilities

The library provides comprehensive verification utilities to validate database operations and identity storage without relying on external network calls:

import { 
  verifyDatabaseUpdate,
  verifyIdentityStorage,
  verifyDataEntries,
  isValidWebAuthnDID
} from 'orbitdb-identity-provider-webauthn-did'

// Verify database update events
const updateResult = await verifyDatabaseUpdate(database, identityHash, expectedWebAuthnDID)
if (updateResult.success) {
  console.log('✅ Database update verified')
} else {
  console.log('❌ Verification failed:', updateResult.error)
}

// Verify identity is properly stored
const storageResult = await verifyIdentityStorage(identities, identity)
console.log('Identity stored correctly:', storageResult.success)

// Verify generic data entries with custom matching
const dataResults = await verifyDataEntries(database, dataItems, expectedWebAuthnDID, {
  matchFn: (dbItem, expectedItem) => dbItem.id === expectedItem.id,
  checkLog: true
})

// DID format validation
if (isValidWebAuthnDID(identity.id)) {
  console.log('Valid WebAuthn DID format')
}

Verification Features

• Database-centric verification: Uses local database state instead of unreliable IPFS gateway calls
• Access control validation: Verifies write permissions and database ownership
• Identity storage checking: Confirms identities are properly stored in OrbitDB's identity store
• Generic data verification: Flexible verification system that works with any data structure
• DID format validation: Utility functions for WebAuthn DID validation and parsing
• Pragmatic fallback: Provides fallback verification when network resources are unavailable

Security Considerations

Private Key Security

• Private keys are generated within the secure hardware element
• Keys cannot be extracted, cloned, or compromised through software attacks
• Each authentication requires user presence and verification

DID Generation

• DIDs are deterministically generated from the WebAuthn public key
• Same credential always produces the same DID
• Format: did:key:{base58btc-encoded-multikey} (compliant with DID key specification)

Authentication Flow

1. User attempts database operation
2. WebAuthn prompt appears
3. User provides authentication
4. Hardware element signs the operation
5. OrbitDB verifies the signature

Error Handling

The library provides detailed error handling for common WebAuthn scenarios:

try {
  const credential = await WebAuthnDIDProvider.createCredential()
} catch (error) {
  switch (error.message) {
    case 'Biometric authentication was cancelled or failed':
      // User cancelled or biometric failed
      break
    case 'WebAuthn is not supported on this device':
      // Device/browser doesn't support WebAuthn
      break
    case 'A credential with this ID already exists':
      // Credential already registered for this user
      break
    default:
      console.error('WebAuthn error:', error.message)
  }
}

Development

Building

npm run build

Testing

npm test

The test suite includes both unit tests and browser integration tests that verify WebAuthn functionality across different platforms.

Dependencies

• @orbitdb/core - OrbitDB core functionality
• cbor-web - CBOR decoding for WebAuthn attestation objects

API Reference

WebAuthnDIDProvider

Core class for WebAuthn DID operations.

Static Methods

• isSupported() - Check if WebAuthn is supported
• isPlatformAuthenticatorAvailable() - Check for biometric authenticators
• createCredential(options) - Create new WebAuthn credential
• createDID(credentialInfo) - Generate DID from credential
• extractPublicKey(credential) - Extract public key from WebAuthn credential

Instance Methods

• sign(data) - Sign data using WebAuthn (triggers biometric prompt)
• verify(signature, data, publicKey) - Verify WebAuthn signature

OrbitDBWebAuthnIdentityProvider

OrbitDB-compatible identity provider.

Methods

• getId() - Get the DID identifier
• signIdentity(data, options) - Sign identity data
• verifyIdentity(signature, data, publicKey) - Verify identity signature

Utility Functions

• registerWebAuthnProvider() - Register provider with OrbitDB
• checkWebAuthnSupport() - Comprehensive support detection
• OrbitDBWebAuthnIdentityProviderFunction(options) - Provider factory function
• storeWebAuthnCredential(credential, key?) - Store credential to localStorage with proper serialization
• loadWebAuthnCredential(key?) - Load credential from localStorage with proper deserialization
• clearWebAuthnCredential(key?) - Clear stored credential from localStorage

Examples

See the test/ directory for comprehensive usage examples including:

• Basic credential creation and authentication
• Multi-platform compatibility testing
• Error handling scenarios
• Integration with OrbitDB databases

Reference Documentation

Core Technologies

OrbitDB

• OrbitDB Documentation - Peer-to-peer database for the decentralized web
• OrbitDB GitHub - Source code and examples
• OrbitDB Liftoff Example - Complete setup guide

IPFS & Helia

• Helia Documentation - Lean, modular, and modern implementation of IPFS for JavaScript
• Helia GitHub - Source code and examples
• IPFS Documentation - InterPlanetary File System docs

libp2p

• libp2p Documentation - Modular network stack for peer-to-peer applications
• libp2p JavaScript - JavaScript implementation
• libp2p Browser Examples - Browser-specific configurations

WebAuthn & Authentication

WebAuthn Standard

• WebAuthn W3C Specification - Official WebAuthn standard
• WebAuthn Guide - Comprehensive WebAuthn tutorial
• MDN WebAuthn API - Browser API documentation

Passkeys

• Passkeys.dev - Complete guide to implementing passkeys
• Apple Passkeys - iOS/macOS passkey implementation
• Google Passkeys - Android/Chrome passkey support
• Microsoft Passkeys - Windows Hello integration

Hardware Security Keys

Ledger WebAuthn

• Ledger WebAuthn Support - FIDO U2F and WebAuthn on Ledger devices
• Ledger Developer Portal - Building apps for Ledger hardware wallets
• Ledger WebAuthn Example - Implementation examples

YubiKey WebAuthn

• YubiKey WebAuthn Guide - Complete WebAuthn implementation guide
• YubiKey Developer Program - SDKs, libraries, and documentation
• YubiKey WebAuthn Examples - Server-side WebAuthn implementation
• YubiKey JavaScript Library - Web integration tools

Browser Compatibility

• Can I Use WebAuthn - Browser support matrix
• WebAuthn Awesome List - Curated WebAuthn resources
• FIDO Alliance - Industry standards and certification

Cryptography & DIDs

Decentralized Identifiers (DIDs)

• DID W3C Specification - Official DID standard
• DID Method Registry - Registered DID methods
• DID Primer - Introduction to DIDs

P-256 Elliptic Curve Cryptography

• RFC 6090 - ECC Algorithms - Fundamental ECC operations
• NIST P-256 Curve - Technical specifications
• WebCrypto API - Browser cryptography APIs

Changelog

v0.1.0 - DID Key Format Migration (2025-01-10)

⚠️ BREAKING CHANGES

• DID Format Change: Migrated from custom did:webauthn: format to standard-compliant did:key: format
• Ucanto Compatibility: Now compatible with ucanto's P-256 key support for UCAN delegation
• Standard Compliance: Uses proper multikey encoding with P-256 multicodec prefix (0x1200)
• Base58btc Encoding: Implements correct base58btc encoding for multikey representation

Technical Changes:

• Fixed varint encoding issues in multiformats integration
• Updated all tests to validate did:key: format instead of did:webauthn:
• Improved error handling and fallback mechanisms for DID generation
• Enhanced public key compression and encoding

Migration Guide: Existing credentials will generate new DID identifiers. Users will need to recreate their OrbitDB databases or migrate data manually.

v0.0.2 - Initial WebAuthn Implementation (2024-12-20)

• Initial release with WebAuthn DID provider
• Custom did:webauthn: format (deprecated in v0.1.0)
• Basic OrbitDB integration
• Platform authenticator support

Contributing

Contributions are welcome! Please ensure all tests pass and follow the existing code style.

License

MIT License - see LICENSE file for details.

Security Disclosures

For security vulnerabilities, please email [email protected] instead of using the issue tracker.