@originals/sdk 1.8.2 → 1.8.3

package/src/migration/audit/AuditLogger.ts

@@ -1,176 +0,0 @@
-/**
- * AuditLogger - Creates and manages migration audit records
- */
-
-import { MigrationAuditRecord, IAuditLogger } from '../types';
-import { OriginalsConfig } from '../../types';
-import { sha256 } from '@noble/hashes/sha2.js';
-import { encodeBase64UrlMultibase } from '../../utils/encoding';
-
-export class AuditLogger implements IAuditLogger {
-  private auditRecords: Map<string, MigrationAuditRecord[]>;
-
-  constructor(private config: OriginalsConfig) {
-    this.auditRecords = new Map();
-  }
-
-  /**
-   * Log a migration audit record
-   */
-  async logMigration(record: MigrationAuditRecord): Promise<void> {
-    // Sign the audit record
-    const signature = await this.signAuditRecord(record);
-    const signedRecord = { ...record, signature };
-
-    // Store by source DID
-    const existingRecords = this.auditRecords.get(record.sourceDid) || [];
-    existingRecords.push(signedRecord);
-    this.auditRecords.set(record.sourceDid, existingRecords);
-
-    // Also store by target DID if available
-    if (record.targetDid) {
-      const targetRecords = this.auditRecords.get(record.targetDid) || [];
-      targetRecords.push(signedRecord);
-      this.auditRecords.set(record.targetDid, targetRecords);
-    }
-
-    // Persist to storage if available (append-only, never overwrite)
-    await this.persistAuditRecord(signedRecord);
-  }
-
-  /**
-   * Get migration history for a DID
-   */
-  async getMigrationHistory(did: string): Promise<MigrationAuditRecord[]> {
-    return this.auditRecords.get(did) || [];
-  }
-
-  /**
-   * Get system-wide migration logs with filters
-   * Fixed dedupe logic: use signature to avoid timeline collapse
-   */
-  async getSystemMigrationLogs(filters: Partial<MigrationAuditRecord>): Promise<MigrationAuditRecord[]> {
-    const allRecords: MigrationAuditRecord[] = [];
-
-    // Collect all unique records (dedupe by signature to preserve timeline)
-    const seen = new Set<string>();
-    for (const records of this.auditRecords.values()) {
-      for (const record of records) {
-        const dedupKey = record.signature || `${record.migrationId}-${record.timestamp}-${record.finalState}`;
-        if (!seen.has(dedupKey)) {
-          seen.add(dedupKey);
-          allRecords.push(record);
-        }
-      }
-    }
-
-    // Apply filters
-    return allRecords.filter(record => {
-      for (const [key, value] of Object.entries(filters)) {
-        if (record[key as keyof MigrationAuditRecord] !== value) {
-          return false;
-        }
-      }
-      return true;
-    });
-  }
-
-  /**
-   * Sign an audit record for integrity
-   *
-   * TODO: Replace with real digital signatures (Ed25519/ECDSA)
-   * Current implementation uses SHA256 hash for integrity verification.
-   * In production, use config.signer.sign(bytes)/verify(bytes, signature) with:
-   * - Ed25519 for performance
-   * - ECDSA (secp256k1/secp256r1) for compatibility
-   *
-   * Example:
-   * const signer = config.signer; // Ed25519Signer or ES256KSigner
-   * const signature = await signer.sign(Buffer.from(canonical), privateKey);
-   * return encodeBase64UrlMultibase(signature);
-   */
-  private async signAuditRecord(record: MigrationAuditRecord): Promise<string> {
-    // Create a canonical representation of the record (without signature)
-    const { signature, ...recordWithoutSig } = record as any;
-    const canonical = JSON.stringify(recordWithoutSig);
-
-    // Hash the canonical representation (placeholder for real signature)
-    const hash = sha256(Buffer.from(canonical, 'utf8'));
-
-    // Encode as multibase for storage
-    return encodeBase64UrlMultibase(Buffer.from(hash));
-  }
-
-  /**
-   * Verify an audit record signature
-   */
-  async verifyAuditRecord(record: MigrationAuditRecord): Promise<boolean> {
-    if (!record.signature) {
-      return false;
-    }
-
-    const expectedSignature = await this.signAuditRecord(record);
-    return expectedSignature === record.signature;
-  }
-
-  /**
-   * Persist audit record to storage (append-only, never overwrite)
-   * Updated key design: audit/migrations/{migrationId}/{timestamp}-{finalState}.json
-   */
-  private async persistAuditRecord(record: MigrationAuditRecord): Promise<void> {
-    const storageAdapter = (this.config as any).storageAdapter;
-    if (storageAdapter && typeof storageAdapter.put === 'function') {
-      try {
-        const data = JSON.stringify(record);
-        // Use unique key to prevent overwriting: migrationId/timestamp-state
-        const key = `audit/migrations/${record.migrationId}/${record.timestamp}-${record.finalState}.json`;
-        await storageAdapter.put(key, Buffer.from(data), { contentType: 'application/json' });
-      } catch (error) {
-        console.error('Failed to persist audit record:', error);
-        // Continue - in-memory record is still available
-      }
-    }
-  }
-
-  /**
-   * Load audit records from storage
-   */
-  async loadAuditRecords(did: string): Promise<void> {
-    const storageAdapter = (this.config as any).storageAdapter;
-    if (!storageAdapter || typeof storageAdapter.list !== 'function') {
-      return;
-    }
-
-    try {
-      // List all audit records
-      const files = await storageAdapter.list('audit/migrations/');
-
-      for (const file of files) {
-        try {
-          const data = await storageAdapter.get(file);
-          if (data) {
-            const record: MigrationAuditRecord = JSON.parse(data.toString());
-
-            // Add to in-memory store if it matches the DID
-            if (record.sourceDid === did || record.targetDid === did) {
-              const existingRecords = this.auditRecords.get(did) || [];
-              // Use signature for dedupe to prevent timeline collapse
-              const dedupKey = record.signature || `${record.migrationId}-${record.timestamp}`;
-              if (!existingRecords.find(r => {
-                const rKey = r.signature || `${r.migrationId}-${r.timestamp}`;
-                return rKey === dedupKey;
-              })) {
-                existingRecords.push(record);
-                this.auditRecords.set(did, existingRecords);
-              }
-            }
-          }
-        } catch (error) {
-          // Skip invalid audit records
-        }
-      }
-    } catch (error) {
-      console.error('Failed to load audit records:', error);
-    }
-  }
-}

package/src/migration/checkpoint/CheckpointManager.ts

@@ -1,112 +0,0 @@
-/**
- * CheckpointManager - Creates and manages migration checkpoints for rollback
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import {
-  MigrationOptions,
-  MigrationCheckpoint,
-  ICheckpointManager
-} from '../types';
-import { OriginalsConfig } from '../../types';
-import { DIDManager } from '../../did/DIDManager';
-import { CredentialManager } from '../../vc/CredentialManager';
-import { CheckpointStorage } from './CheckpointStorage';
-
-export class CheckpointManager implements ICheckpointManager {
-  private storage: CheckpointStorage;
-
-  constructor(
-    private config: OriginalsConfig,
-    private didManager: DIDManager,
-    private credentialManager: CredentialManager
-  ) {
-    this.storage = new CheckpointStorage(config);
-  }
-
-  /**
-   * Create a checkpoint before migration
-   */
-  async createCheckpoint(migrationId: string, options: MigrationOptions): Promise<MigrationCheckpoint> {
-    try {
-      const checkpointId = `chk_${uuidv4()}`;
-
-      // Resolve source DID document
-      const didDocument = await this.didManager.resolveDID(options.sourceDid);
-      if (!didDocument) {
-        throw new Error(`Could not resolve source DID: ${options.sourceDid}`);
-      }
-
-      // Extract source layer
-      const sourceLayer = this.extractLayer(options.sourceDid);
-      if (!sourceLayer) {
-        throw new Error(`Invalid source DID format: ${options.sourceDid}`);
-      }
-
-      // Create checkpoint
-      const checkpoint: MigrationCheckpoint = {
-        checkpointId,
-        migrationId,
-        timestamp: Date.now(),
-        sourceDid: options.sourceDid,
-        sourceLayer,
-        didDocument,
-        credentials: [], // Would be populated by querying credential store
-        storageReferences: {}, // Would be populated by querying storage adapter
-        lifecycleState: {}, // Would be populated by querying lifecycle manager
-        ownershipProofs: [], // Would be populated if available
-        metadata: options.metadata || {}
-      };
-
-      // Store checkpoint
-      await this.storage.save(checkpoint);
-
-      return checkpoint;
-    } catch (error) {
-      throw new Error(`Failed to create checkpoint: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /**
-   * Retrieve a checkpoint by ID
-   */
-  async getCheckpoint(checkpointId: string): Promise<MigrationCheckpoint | null> {
-    try {
-      return await this.storage.get(checkpointId);
-    } catch (error) {
-      console.error(`Error retrieving checkpoint ${checkpointId}:`, error);
-      return null;
-    }
-  }
-
-  /**
-   * Delete a checkpoint (after successful migration or cleanup)
-   */
-  async deleteCheckpoint(checkpointId: string): Promise<void> {
-    try {
-      await this.storage.delete(checkpointId);
-    } catch (error) {
-      console.error(`Error deleting checkpoint ${checkpointId}:`, error);
-      // Don't throw - deletion failures shouldn't break migrations
-    }
-  }
-
-  /**
-   * Clean up old checkpoints (older than 24 hours for successful migrations)
-   */
-  async cleanupOldCheckpoints(): Promise<void> {
-    try {
-      const cutoffTime = Date.now() - (24 * 60 * 60 * 1000); // 24 hours
-      await this.storage.deleteOlderThan(cutoffTime);
-    } catch (error) {
-      console.error('Error cleaning up old checkpoints:', error);
-    }
-  }
-
-  private extractLayer(did: string): 'peer' | 'webvh' | 'btco' | null {
-    if (did.startsWith('did:peer:')) return 'peer';
-    if (did.startsWith('did:webvh:')) return 'webvh';
-    if (did.startsWith('did:btco:')) return 'btco';
-    return null;
-  }
-}

package/src/migration/checkpoint/CheckpointStorage.ts

@@ -1,101 +0,0 @@
-/**
- * CheckpointStorage - Persists checkpoints to storage
- */
-
-import { MigrationCheckpoint } from '../types';
-import { OriginalsConfig } from '../../types';
-
-export class CheckpointStorage {
-  private checkpoints: Map<string, MigrationCheckpoint>;
-
-  constructor(private config: OriginalsConfig) {
-    this.checkpoints = new Map();
-  }
-
-  /**
-   * Save a checkpoint
-   */
-  async save(checkpoint: MigrationCheckpoint): Promise<void> {
-    if (!checkpoint.checkpointId) {
-      throw new Error('Checkpoint must have an ID');
-    }
-    this.checkpoints.set(checkpoint.checkpointId, checkpoint);
-
-    // Optionally persist to configured storage adapter
-    const storageAdapter = (this.config as any).storageAdapter;
-    if (storageAdapter && typeof storageAdapter.put === 'function') {
-      try {
-        const data = JSON.stringify(checkpoint);
-        const key = `checkpoints/${checkpoint.checkpointId}.json`;
-        await storageAdapter.put(key, Buffer.from(data), { contentType: 'application/json' });
-      } catch (error) {
-        console.error('Failed to persist checkpoint to storage:', error);
-        // Continue - in-memory checkpoint is still available
-      }
-    }
-  }
-
-  /**
-   * Retrieve a checkpoint
-   */
-  async get(checkpointId: string): Promise<MigrationCheckpoint | null> {
-    // Try in-memory first
-    const memoryCheckpoint = this.checkpoints.get(checkpointId);
-    if (memoryCheckpoint) {
-      return memoryCheckpoint;
-    }
-
-    // Try loading from storage adapter
-    const storageAdapter = (this.config as any).storageAdapter;
-    if (storageAdapter && typeof storageAdapter.get === 'function') {
-      try {
-        const key = `checkpoints/${checkpointId}.json`;
-        const data = await storageAdapter.get(key);
-        if (data) {
-          const checkpoint = JSON.parse(data.toString());
-          this.checkpoints.set(checkpointId, checkpoint);
-          return checkpoint;
-        }
-      } catch (error) {
-        // Checkpoint not found in storage
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Delete a checkpoint
-   */
-  async delete(checkpointId: string): Promise<void> {
-    this.checkpoints.delete(checkpointId);
-
-    // Also delete from storage adapter
-    const storageAdapter = (this.config as any).storageAdapter;
-    if (storageAdapter && typeof storageAdapter.delete === 'function') {
-      try {
-        const key = `checkpoints/${checkpointId}.json`;
-        await storageAdapter.delete(key);
-      } catch (error) {
-        // Ignore deletion errors
-      }
-    }
-  }
-
-  /**
-   * Delete checkpoints older than specified timestamp
-   */
-  async deleteOlderThan(cutoffTime: number): Promise<void> {
-    const toDelete: string[] = [];
-
-    for (const [id, checkpoint] of this.checkpoints.entries()) {
-      if (checkpoint.timestamp < cutoffTime) {
-        toDelete.push(id);
-      }
-    }
-
-    for (const id of toDelete) {
-      await this.delete(id);
-    }
-  }
-}

package/src/migration/index.ts

@@ -1,33 +0,0 @@
-/**
- * Migration module exports
- * Provides DID layer migration capabilities with validation, checkpoints, and rollbacks
- */
-
-export { MigrationManager } from './MigrationManager';
-export * from './types';
-
-// Validators
-export { ValidationPipeline } from './validation/ValidationPipeline';
-export { DIDCompatibilityValidator } from './validation/DIDCompatibilityValidator';
-export { CredentialValidator } from './validation/CredentialValidator';
-export { StorageValidator } from './validation/StorageValidator';
-export { LifecycleValidator } from './validation/LifecycleValidator';
-export { BitcoinValidator } from './validation/BitcoinValidator';
-
-// Checkpoint and Rollback
-export { CheckpointManager } from './checkpoint/CheckpointManager';
-export { CheckpointStorage } from './checkpoint/CheckpointStorage';
-export { RollbackManager } from './rollback/RollbackManager';
-
-// State Management
-export { StateTracker } from './state/StateTracker';
-export { StateMachine } from './state/StateMachine';
-
-// Audit
-export { AuditLogger } from './audit/AuditLogger';
-
-// Operations
-export { BaseMigration } from './operations/BaseMigration';
-export { PeerToWebvhMigration } from './operations/PeerToWebvhMigration';
-export { WebvhToBtcoMigration } from './operations/WebvhToBtcoMigration';
-export { PeerToBtcoMigration } from './operations/PeerToBtcoMigration';

package/src/migration/operations/BaseMigration.ts

@@ -1,126 +0,0 @@
-/**
- * BaseMigration - Base class for all migration operations
- */
-
-import {
-  MigrationOptions,
-  MigrationResult,
-  MigrationError,
-  MigrationErrorType,
-  MigrationStateEnum,
-  CostEstimate
-} from '../types';
-import { OriginalsConfig, DIDDocument } from '../../types';
-import { DIDManager } from '../../did/DIDManager';
-import { CredentialManager } from '../../vc/CredentialManager';
-import { StateTracker } from '../state/StateTracker';
-import { EventEmitter } from '../../events/EventEmitter';
-
-export abstract class BaseMigration {
-  protected eventEmitter: EventEmitter;
-
-  constructor(
-    protected config: OriginalsConfig,
-    protected didManager: DIDManager,
-    protected credentialManager: CredentialManager,
-    protected stateTracker: StateTracker
-  ) {
-    this.eventEmitter = new EventEmitter();
-  }
-
-  /**
-   * Execute the migration (to be implemented by subclasses)
-   */
-  abstract executeMigration(
-    options: MigrationOptions,
-    migrationId: string
-  ): Promise<{ targetDid: string; didDocument: DIDDocument }>;
-
-  /**
-   * Get estimated cost (to be implemented by subclasses)
-   */
-  abstract estimateCost(options: MigrationOptions): Promise<CostEstimate>;
-
-  /**
-   * Emit migration event
-   */
-  protected async emitEvent(type: string, data: any): Promise<void> {
-    try {
-      await this.eventEmitter.emit({
-        type,
-        timestamp: new Date().toISOString(),
-        ...data
-      });
-    } catch (error) {
-      console.error(`Error emitting event ${type}:`, error);
-    }
-  }
-
-  /**
-   * Create migration error
-   */
-  protected createError(
-    type: MigrationErrorType,
-    code: string,
-    message: string,
-    migrationId?: string,
-    details?: any
-  ): MigrationError {
-    return {
-      type,
-      code,
-      message,
-      technicalDetails: details ? JSON.stringify(details) : undefined,
-      migrationId,
-      timestamp: Date.now()
-    };
-  }
-
-  /**
-   * Update migration state with error handling
-   */
-  protected async updateStateWithRetry(
-    migrationId: string,
-    updates: any,
-    maxRetries: number = 3
-  ): Promise<void> {
-    let lastError: Error | null = null;
-
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
-      try {
-        await this.stateTracker.updateState(migrationId, updates);
-        return;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (attempt < maxRetries - 1) {
-          // Exponential backoff: 100ms, 200ms, 400ms
-          await new Promise(resolve => setTimeout(resolve, 100 * Math.pow(2, attempt)));
-        }
-      }
-    }
-
-    throw lastError || new Error('Failed to update state after retries');
-  }
-
-  /**
-   * Resolve source DID document
-   */
-  protected async resolveSourceDid(sourceDid: string): Promise<DIDDocument> {
-    const didDocument = await this.didManager.resolveDID(sourceDid);
-    if (!didDocument) {
-      throw new Error(`Could not resolve source DID: ${sourceDid}`);
-    }
-    return didDocument;
-  }
-
-  /**
-   * Extract layer from DID
-   */
-  protected extractLayer(did: string): 'peer' | 'webvh' | 'btco' {
-    if (did.startsWith('did:peer:')) return 'peer';
-    if (did.startsWith('did:webvh:')) return 'webvh';
-    if (did.startsWith('did:btco:')) return 'btco';
-    throw new Error(`Unsupported DID method: ${did}`);
-  }
-}

package/src/migration/operations/PeerToBtcoMigration.ts

@@ -1,105 +0,0 @@
-/**
- * PeerToBtcoMigration - Handles direct migration from did:peer to did:btco
- */
-
-import {
-  MigrationOptions,
-  CostEstimate,
-  MigrationStateEnum
-} from '../types';
-import { DIDDocument, OriginalsConfig } from '../../types';
-import { BaseMigration } from './BaseMigration';
-import { BitcoinManager } from '../../bitcoin/BitcoinManager';
-import { DIDManager } from '../../did/DIDManager';
-import { CredentialManager } from '../../vc/CredentialManager';
-import { StateTracker } from '../state/StateTracker';
-
-export class PeerToBtcoMigration extends BaseMigration {
-  private bitcoinManager: BitcoinManager;
-
-  constructor(
-    config: OriginalsConfig,
-    didManager: DIDManager,
-    credentialManager: CredentialManager,
-    stateTracker: StateTracker,
-    bitcoinManager: BitcoinManager
-  ) {
-    super(config, didManager, credentialManager, stateTracker);
-    this.bitcoinManager = bitcoinManager;
-  }
-
-  /**
-   * Execute peer → btco migration (direct, skipping webvh layer)
-   */
-  async executeMigration(
-    options: MigrationOptions,
-    migrationId: string
-  ): Promise<{ targetDid: string; didDocument: DIDDocument }> {
-    // Resolve source DID
-    const sourceDid = await this.resolveSourceDid(options.sourceDid);
-
-    await this.updateStateWithRetry(migrationId, {
-      state: MigrationStateEnum.IN_PROGRESS,
-      currentOperation: 'Creating Bitcoin inscription',
-      progress: 30
-    });
-
-    // Create Bitcoin inscription with DID document
-    const manifest = {
-      didDocument: sourceDid,
-      migrationId,
-      timestamp: new Date().toISOString()
-    };
-    const payload = Buffer.from(JSON.stringify(manifest));
-
-    await this.updateStateWithRetry(migrationId, {
-      state: MigrationStateEnum.ANCHORING,
-      currentOperation: 'Anchoring to Bitcoin',
-      progress: 50
-    });
-
-    const inscription = await this.bitcoinManager.inscribeData(
-      payload,
-      'application/json',
-      options.feeRate
-    );
-
-    // Use satoshi identifier or inscription ID
-    const satoshiId = inscription.satoshi || inscription.inscriptionId.split('i')[0];
-
-    await this.updateStateWithRetry(migrationId, {
-      currentOperation: 'Creating btco DID document',
-      progress: 80
-    });
-
-    // Migrate DID document to btco
-    const migratedDoc = await this.didManager.migrateToDIDBTCO(sourceDid, satoshiId);
-
-    await this.updateStateWithRetry(migrationId, {
-      currentOperation: 'Migration completed',
-      progress: 100,
-      targetDid: migratedDoc.id
-    });
-
-    return {
-      targetDid: migratedDoc.id,
-      didDocument: migratedDoc
-    };
-  }
-
-  /**
-   * Estimate cost for peer → btco migration
-   */
-  async estimateCost(options: MigrationOptions): Promise<CostEstimate> {
-    const feeRate = options.feeRate || 10; // default 10 sat/vB
-    const estimatedSize = 1024; // ~1KB for typical DID document
-    const networkFees = estimatedSize * feeRate;
-
-    return {
-      storageCost: 0,
-      networkFees,
-      totalCost: networkFees,
-      currency: 'sats'
-    };
-  }
-}