@toolkit-p2p/identity

Cryptographic identity and trust system for toolkit-p2p.

Overview

@toolkit-p2p/identity provides self-sovereign decentralized identifiers (DIDs) using Ed25519 cryptography, mutual trust tickets for peer linking, and session key derivation for secure P2P communication.

Features

• Self-Sovereign DIDs: Each device generates its own did:zeta:<base58(publicKey)>
• Persistent Identity: Stored securely in IndexedDB with localStorage fallback
• Trust Tickets: Mutual, signed permission objects for auto-connect/sync
• Session Keys: PBKDF2-derived symmetric keys for per-room HMAC signing
• Blocklist: Local DID blocking for security and privacy
• QR Code Generation: Generate QR codes for peer connections in multiple formats (PNG, SVG, terminal)
• BIP39 Mnemonic Backup: Human-readable 12 or 24-word phrases for identity backup and recovery
• Zero Server: All operations are local; no central authority

Installation

pnpm add @toolkit-p2p/identity

Quick Start

import { loadOrCreateIdentity, createTrustTicket, verifyTrustTicket } from '@toolkit-p2p/identity';

// Generate or load your identity
const myIdentity = await loadOrCreateIdentity();
console.log(myIdentity.did);  // "did:zeta:Abc123..."

// Create a trust ticket for another peer
const ticket = createTrustTicket(
  myIdentity,
  'did:zeta:Def456...',  // Their DID
  {
    autoMesh: true,
    autoSyncState: true,
    allowRelay: true,
    allowLanUpgrade: true
  },
  7 * 86400  // 7 days
);

// Verify a trust ticket from them
const isValid = verifyTrustTicket(ticket);

QR Code Generation

Generate QR codes for easy peer-to-peer connection setup:

import { loadOrCreateIdentity } from '@toolkit-p2p/identity';
import { generateQRDataURL, generateQRSVG, generateQRTerminal } from '@toolkit-p2p/identity';

const identity = await loadOrCreateIdentity();

// Create QR data for sharing
const qrData = {
  version: 1,
  did: identity.did,
  sceneId: 'conference-room-A',           // Optional: scene/room identifier
  wsUrl: 'wss://signal.example.com:8080'  // Optional: signaling server URL
};

// Generate as PNG data URL for web
const dataUrl = await generateQRDataURL(qrData);
// Use in HTML: <img src={dataUrl} alt="Peer Connection" />

// Generate as SVG for scalability
const svg = await generateQRSVG(qrData, { width: 500 });
// Embed directly: document.getElementById('qr').innerHTML = svg;

// Generate for terminal/CLI display
const terminal = await generateQRTerminal(qrData);
console.log(terminal);

Mnemonic Backup and Recovery

Backup your identity using human-readable BIP39 mnemonic phrases:

import { generateMnemonic, recoverFromMnemonic, validateMnemonic } from '@toolkit-p2p/identity';

// Generate new identity with mnemonic backup
const { mnemonic, identity, wordCount } = await generateMnemonic();
console.log('BACKUP THIS PHRASE:', mnemonic);
// Example: "witch collapse practice feed shame open despair creek road again ice least"
console.log(`Word count: ${wordCount}`);  // 12

// Generate with 24 words and passphrase for extra security
const secure = await generateMnemonic({
  strength: 256,              // 24 words
  passphrase: 'my-secret'     // Optional additional security
});

// Validate a mnemonic before using it
if (validateMnemonic(mnemonic)) {
  // Recover identity from mnemonic
  const recovered = await recoverFromMnemonic(mnemonic);
  console.log('Recovered DID:', recovered.did);

  // With passphrase (must match the one used during generation)
  const recoveredSecure = await recoverFromMnemonic(mnemonic, 'my-secret');
}

API

See API documentation for complete reference.

Security

• Private keys are stored in IndexedDB (browser-level encryption)
• Ed25519 signatures prevent tampering
• Session keys use PBKDF2 with 10,000 iterations
• Blocklist prevents connections from malicious peers
• BIP39 mnemonics use cryptographically secure entropy with optional passphrase protection
• Deterministic key derivation ensures same mnemonic always produces same identity
• QR codes contain only public information (DID, scene ID, signaling server URL)

License

MIT © 2025 Aaron Rosenthal