@originals/sdk 1.1.0

package/src/migration/MigrationManager.ts

@@ -0,0 +1,527 @@
+/**
+ * MigrationManager - Main orchestrator for DID layer migrations
+ * Coordinates validation, checkpoints, rollbacks, state tracking, and audit logging
+ */
+
+import {
+  MigrationOptions,
+  MigrationResult,
+  MigrationStateEnum,
+  MigrationError,
+  MigrationErrorType,
+  BatchMigrationOptions,
+  BatchMigrationResult,
+  CostEstimate
+} from './types';
+import { OriginalsConfig } from '../types';
+import { DIDManager } from '../did/DIDManager';
+import { CredentialManager } from '../vc/CredentialManager';
+import { BitcoinManager } from '../bitcoin/BitcoinManager';
+import { ValidationPipeline } from './validation/ValidationPipeline';
+import { CheckpointManager } from './checkpoint/CheckpointManager';
+import { RollbackManager } from './rollback/RollbackManager';
+import { StateTracker } from './state/StateTracker';
+// TODO: AuditLogger temporarily disabled for v1.0 release
+// Will be re-enabled in v1.1 with proper Ed25519 digital signatures
+// import { AuditLogger } from './audit/AuditLogger';
+import { PeerToWebvhMigration } from './operations/PeerToWebvhMigration';
+import { WebvhToBtcoMigration } from './operations/WebvhToBtcoMigration';
+import { PeerToBtcoMigration } from './operations/PeerToBtcoMigration';
+import { EventEmitter } from '../events/EventEmitter';
+
+export class MigrationManager {
+  private static instance: MigrationManager | null = null;
+
+  private validationPipeline: ValidationPipeline;
+  private checkpointManager: CheckpointManager;
+  private rollbackManager: RollbackManager;
+  private stateTracker: StateTracker;
+  // TODO: AuditLogger temporarily disabled for v1.0 release
+  // private auditLogger: AuditLogger;
+  private eventEmitter: EventEmitter;
+
+  // Temporary in-memory audit storage for v1.0 (unsigned records)
+  // Will be replaced by proper AuditLogger with signatures in v1.1
+  private inMemoryAuditRecords: Map<string, any[]>;
+
+  // Migration operation handlers
+  private peerToWebvh: PeerToWebvhMigration;
+  private webvhToBtco: WebvhToBtcoMigration;
+  private peerToBtco: PeerToBtcoMigration;
+
+  private constructor(
+    private config: OriginalsConfig,
+    private didManager: DIDManager,
+    private credentialManager: CredentialManager,
+    private bitcoinManager?: BitcoinManager
+  ) {
+    // Initialize components
+    this.validationPipeline = new ValidationPipeline(
+      config,
+      didManager,
+      credentialManager,
+      bitcoinManager
+    );
+    this.checkpointManager = new CheckpointManager(config, didManager, credentialManager);
+    this.stateTracker = new StateTracker(config);
+    this.rollbackManager = new RollbackManager(config, this.checkpointManager, didManager);
+    // TODO: AuditLogger temporarily disabled for v1.0 release
+    // this.auditLogger = new AuditLogger(config);
+    this.eventEmitter = new EventEmitter();
+
+    // Initialize in-memory audit storage for v1.0
+    this.inMemoryAuditRecords = new Map();
+
+    // Initialize migration operations
+    this.peerToWebvh = new PeerToWebvhMigration(config, didManager, credentialManager, this.stateTracker);
+
+    if (bitcoinManager) {
+      this.webvhToBtco = new WebvhToBtcoMigration(config, didManager, credentialManager, this.stateTracker, bitcoinManager);
+      this.peerToBtco = new PeerToBtcoMigration(config, didManager, credentialManager, this.stateTracker, bitcoinManager);
+    } else {
+      // Create stub implementations that throw errors
+      this.webvhToBtco = null as any;
+      this.peerToBtco = null as any;
+    }
+  }
+
+  /**
+   * Get singleton instance
+   */
+  static getInstance(
+    config?: OriginalsConfig,
+    didManager?: DIDManager,
+    credentialManager?: CredentialManager,
+    bitcoinManager?: BitcoinManager
+  ): MigrationManager {
+    if (!MigrationManager.instance) {
+      if (!config || !didManager || !credentialManager) {
+        throw new Error('Configuration and managers required for first initialization');
+      }
+      MigrationManager.instance = new MigrationManager(config, didManager, credentialManager, bitcoinManager);
+    }
+    return MigrationManager.instance;
+  }
+
+  /**
+   * Reset singleton instance (primarily for testing)
+   */
+  static resetInstance(): void {
+    MigrationManager.instance = null;
+  }
+
+  /**
+   * Main migration method
+   */
+  async migrate(options: MigrationOptions): Promise<MigrationResult> {
+    const startTime = Date.now();
+    let migrationState: any;
+    let checkpoint: any;
+
+    try {
+      // Step 1: Create migration state
+      migrationState = await this.stateTracker.createMigration(options);
+      const migrationId = migrationState.migrationId;
+
+      await this.emitEvent('migration:started', { migrationId, options });
+
+      // Step 2: Validate migration
+      await this.stateTracker.updateState(migrationId, {
+        state: MigrationStateEnum.VALIDATING,
+        currentOperation: 'Validating migration',
+        progress: 10
+      });
+
+      const validationResult = await this.validationPipeline.validate(options);
+
+      if (!validationResult.valid) {
+        throw this.createMigrationError(
+          MigrationErrorType.VALIDATION_ERROR,
+          'VALIDATION_FAILED',
+          `Migration validation failed: ${validationResult.errors.map(e => e.message).join(', ')}`,
+          migrationId,
+          { errors: validationResult.errors }
+        );
+      }
+
+      await this.emitEvent('migration:validated', { migrationId, validationResult });
+
+      // Step 3: Create checkpoint
+      await this.stateTracker.updateState(migrationId, {
+        state: MigrationStateEnum.CHECKPOINTED,
+        currentOperation: 'Creating checkpoint',
+        progress: 20
+      });
+
+      checkpoint = await this.checkpointManager.createCheckpoint(migrationId, options);
+
+      // Persist checkpointId immediately so rollback can locate it
+      await this.stateTracker.updateState(migrationId, {
+        checkpointId: checkpoint.checkpointId
+      });
+
+      await this.emitEvent('migration:checkpointed', { migrationId, checkpointId: checkpoint.checkpointId });
+
+      // Step 4: Execute migration
+      const migration = this.getMigrationOperation(options);
+      const result = await migration.executeMigration(options, migrationId);
+
+      // Step 5: Complete migration
+      await this.stateTracker.updateState(migrationId, {
+        state: MigrationStateEnum.COMPLETED,
+        currentOperation: 'Completed',
+        progress: 100,
+        targetDid: result.targetDid
+      });
+
+      await this.emitEvent('migration:completed', { migrationId, targetDid: result.targetDid });
+
+      // Step 6: Create audit record
+      const duration = Date.now() - startTime;
+      const auditRecord = {
+        migrationId,
+        timestamp: startTime,
+        initiator: 'system',
+        sourceDid: options.sourceDid,
+        sourceLayer: this.extractLayer(options.sourceDid),
+        targetDid: result.targetDid,
+        targetLayer: options.targetLayer,
+        finalState: MigrationStateEnum.COMPLETED,
+        validationResults: validationResult,
+        costActual: validationResult.estimatedCost,
+        duration,
+        checkpointId: checkpoint.checkpointId,
+        errors: [],
+        metadata: options.metadata || {}
+      };
+
+      // TODO: AuditLogger temporarily disabled for v1.0 release
+      // Store in-memory for v1.0 (unsigned, will be replaced with signed records in v1.1)
+      this.storeAuditRecordInMemory(auditRecord);
+
+      // Clean up checkpoint after successful migration
+      setTimeout(() => {
+        this.checkpointManager.deleteCheckpoint(checkpoint.checkpointId);
+      }, 24 * 60 * 60 * 1000); // Delete after 24 hours
+
+      return {
+        migrationId,
+        success: true,
+        sourceDid: options.sourceDid,
+        targetDid: result.targetDid,
+        sourceLayer: this.extractLayer(options.sourceDid),
+        targetLayer: options.targetLayer,
+        state: MigrationStateEnum.COMPLETED,
+        duration,
+        cost: validationResult.estimatedCost,
+        auditRecord
+      };
+    } catch (error) {
+      // Handle migration failure
+      return await this.handleMigrationFailure(
+        error,
+        options,
+        migrationState,
+        checkpoint,
+        startTime
+      );
+    }
+  }
+
+  /**
+   * Estimate migration cost without executing
+   */
+  async estimateMigrationCost(sourceDid: string, targetLayer: string, feeRate?: number): Promise<CostEstimate> {
+    const options: MigrationOptions = {
+      sourceDid,
+      targetLayer: targetLayer as any,
+      feeRate,
+      estimateCostOnly: true
+    };
+
+    const validationResult = await this.validationPipeline.validate(options);
+    return validationResult.estimatedCost;
+  }
+
+  /**
+   * Get migration status
+   */
+  async getMigrationStatus(migrationId: string): Promise<any> {
+    return await this.stateTracker.getState(migrationId);
+  }
+
+  /**
+   * Rollback a migration
+   */
+  async rollback(migrationId: string): Promise<any> {
+    const state = await this.stateTracker.getState(migrationId);
+    if (!state || !state.checkpointId) {
+      throw new Error(`Migration ${migrationId} not found or has no checkpoint`);
+    }
+
+    const rollbackResult = await this.rollbackManager.rollback(migrationId, state.checkpointId);
+
+    await this.emitEvent('migration:rolledback', { migrationId, rollbackResult });
+
+    return rollbackResult;
+  }
+
+  /**
+   * Get migration history for a DID
+   * TODO: AuditLogger temporarily disabled for v1.0 release
+   * Returns in-memory audit records (unsigned) - will use proper AuditLogger in v1.1
+   */
+  async getMigrationHistory(did: string): Promise<any[]> {
+    return this.inMemoryAuditRecords.get(did) || [];
+  }
+
+  /**
+   * Batch migration
+   */
+  async migrateBatch(dids: string[], targetLayer: string, options?: BatchMigrationOptions): Promise<BatchMigrationResult> {
+    const batchId = `batch_${Date.now()}`;
+    const results = new Map<string, MigrationResult>();
+    const errors: MigrationError[] = [];
+
+    let completed = 0;
+    let failed = 0;
+    const total = dids.length;
+
+    for (const did of dids) {
+      try {
+        const migrationOptions: MigrationOptions = {
+          sourceDid: did,
+          targetLayer: targetLayer as any,
+          ...options
+        };
+
+        const result = await this.migrate(migrationOptions);
+        results.set(did, result);
+
+        if (result.success) {
+          completed++;
+        } else {
+          failed++;
+        }
+      } catch (error) {
+        failed++;
+        const migrationError: MigrationError = {
+          type: MigrationErrorType.UNKNOWN_ERROR,
+          code: 'BATCH_MIGRATION_ERROR',
+          message: error instanceof Error ? error.message : String(error),
+          sourceDid: did,
+          timestamp: Date.now()
+        };
+        errors.push(migrationError);
+
+        if (!options?.continueOnError) {
+          break;
+        }
+      }
+    }
+
+    return {
+      batchId,
+      total,
+      completed,
+      failed,
+      inProgress: 0,
+      results,
+      overallProgress: (completed + failed) / total * 100,
+      startTime: Date.now(),
+      errors
+    };
+  }
+
+  /**
+   * Handle migration failure with automatic rollback
+   */
+  private async handleMigrationFailure(
+    error: any,
+    options: MigrationOptions,
+    migrationState: any,
+    checkpoint: any,
+    startTime: number
+  ): Promise<MigrationResult> {
+    const migrationId = migrationState?.migrationId || `mig_failed_${Date.now()}`;
+
+    const migrationError: MigrationError = {
+      type: error.type || MigrationErrorType.UNKNOWN_ERROR,
+      code: error.code || 'MIGRATION_FAILED',
+      message: error.message || String(error),
+      technicalDetails: error.stack,
+      migrationId,
+      sourceDid: options.sourceDid,
+      timestamp: Date.now()
+    };
+
+    // Update state to failed
+    if (migrationState) {
+      try {
+        await this.stateTracker.updateState(migrationId, {
+          state: MigrationStateEnum.FAILED,
+          error: migrationError
+        });
+      } catch (updateError) {
+        console.error('Failed to update migration state:', updateError);
+      }
+    }
+
+    await this.emitEvent('migration:failed', { migrationId, error: migrationError });
+
+    // Attempt rollback if checkpoint exists
+    let rollbackSuccess = false;
+    if (checkpoint) {
+      try {
+        const rollbackResult = await this.rollbackManager.rollback(migrationId, checkpoint.checkpointId);
+        rollbackSuccess = rollbackResult.success;
+
+        if (!rollbackSuccess) {
+          await this.emitEvent('migration:quarantine', {
+            migrationId,
+            checkpointId: checkpoint.checkpointId,
+            reason: 'Rollback failed'
+          });
+        }
+      } catch (rollbackError) {
+        console.error('Rollback failed:', rollbackError);
+        await this.emitEvent('migration:quarantine', {
+          migrationId,
+          checkpointId: checkpoint.checkpointId,
+          reason: rollbackError instanceof Error ? rollbackError.message : String(rollbackError)
+        });
+      }
+    }
+
+    // Create audit record
+    const duration = Date.now() - startTime;
+    const auditRecord = {
+      migrationId,
+      timestamp: startTime,
+      initiator: 'system',
+      sourceDid: options.sourceDid,
+      sourceLayer: this.extractLayer(options.sourceDid),
+      targetDid: null,
+      targetLayer: options.targetLayer,
+      finalState: rollbackSuccess ? MigrationStateEnum.ROLLED_BACK : MigrationStateEnum.FAILED,
+      validationResults: {
+        valid: false,
+        errors: [],
+        warnings: [],
+        estimatedCost: { storageCost: 0, networkFees: 0, totalCost: 0, estimatedDuration: 0, currency: 'sats' },
+        estimatedDuration: 0
+      },
+      costActual: { storageCost: 0, networkFees: 0, totalCost: 0, estimatedDuration: duration, currency: 'sats' },
+      duration,
+      checkpointId: checkpoint?.checkpointId || '',
+      errors: [migrationError],
+      metadata: options.metadata || {}
+    };
+
+    // TODO: AuditLogger temporarily disabled for v1.0 release
+    // Store in-memory for v1.0 (unsigned, will be replaced with signed records in v1.1)
+    this.storeAuditRecordInMemory(auditRecord);
+
+    return {
+      migrationId,
+      success: false,
+      sourceDid: options.sourceDid,
+      sourceLayer: this.extractLayer(options.sourceDid),
+      targetLayer: options.targetLayer,
+      state: rollbackSuccess ? MigrationStateEnum.ROLLED_BACK : MigrationStateEnum.FAILED,
+      duration,
+      cost: { storageCost: 0, networkFees: 0, totalCost: 0, currency: 'sats' },
+      auditRecord,
+      error: migrationError
+    };
+  }
+
+  /**
+   * Get appropriate migration operation handler
+   */
+  private getMigrationOperation(options: MigrationOptions): any {
+    const sourceLayer = this.extractLayer(options.sourceDid);
+
+    if (sourceLayer === 'peer' && options.targetLayer === 'webvh') {
+      return this.peerToWebvh;
+    }
+
+    if (sourceLayer === 'webvh' && options.targetLayer === 'btco') {
+      if (!this.webvhToBtco) {
+        throw new Error('Bitcoin manager required for btco migrations');
+      }
+      return this.webvhToBtco;
+    }
+
+    if (sourceLayer === 'peer' && options.targetLayer === 'btco') {
+      if (!this.peerToBtco) {
+        throw new Error('Bitcoin manager required for btco migrations');
+      }
+      return this.peerToBtco;
+    }
+
+    throw new Error(`Unsupported migration path: ${sourceLayer} → ${options.targetLayer}`);
+  }
+
+  /**
+   * Store audit record in memory for v1.0
+   * Stores by both source and target DID for easy lookup
+   * TODO: Remove in v1.1 when AuditLogger is re-enabled with signatures
+   */
+  private storeAuditRecordInMemory(record: any): void {
+    // Store by source DID
+    const sourceRecords = this.inMemoryAuditRecords.get(record.sourceDid) || [];
+    sourceRecords.push(record);
+    this.inMemoryAuditRecords.set(record.sourceDid, sourceRecords);
+
+    // Also store by target DID if available
+    if (record.targetDid) {
+      const targetRecords = this.inMemoryAuditRecords.get(record.targetDid) || [];
+      targetRecords.push(record);
+      this.inMemoryAuditRecords.set(record.targetDid, targetRecords);
+    }
+  }
+
+  /**
+   * Extract layer from DID
+   */
+  private 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}`);
+  }
+
+  /**
+   * Create migration error
+   */
+  private createMigrationError(
+    type: MigrationErrorType,
+    code: string,
+    message: string,
+    migrationId?: string,
+    details?: any
+  ): Error & { type: MigrationErrorType; code: string } {
+    const error = new Error(message) as any;
+    error.type = type;
+    error.code = code;
+    error.migrationId = migrationId;
+    error.details = details;
+    return error;
+  }
+
+  /**
+   * Emit event
+   */
+  private 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);
+    }
+  }
+}

package/src/migration/audit/AuditLogger.ts

@@ -0,0 +1,176 @@
+/**
+ * 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);
+    }
+  }
+}