@originals/sdk 1.1.0

package/src/migration/checkpoint/CheckpointManager.ts

@@ -0,0 +1,112 @@
+/**
+ * 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

@@ -0,0 +1,101 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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

@@ -0,0 +1,126 @@
+/**
+ * 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

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

package/src/migration/operations/PeerToWebvhMigration.ts

@@ -0,0 +1,62 @@
+/**
+ * PeerToWebvhMigration - Handles migration from did:peer to did:webvh
+ */
+
+import {
+  MigrationOptions,
+  CostEstimate,
+  MigrationStateEnum
+} from '../types';
+import { DIDDocument } from '../../types';
+import { BaseMigration } from './BaseMigration';
+
+export class PeerToWebvhMigration extends BaseMigration {
+  /**
+   * Execute peer → webvh migration
+   */
+  async executeMigration(
+    options: MigrationOptions,
+    migrationId: string
+  ): Promise<{ targetDid: string; didDocument: DIDDocument }> {
+    // Resolve source DID
+    const sourceDid = await this.resolveSourceDid(options.sourceDid);
+
+    // Validate domain is provided
+    if (!options.domain) {
+      throw new Error('Domain is required for webvh migrations');
+    }
+
+    await this.updateStateWithRetry(migrationId, {
+      state: MigrationStateEnum.IN_PROGRESS,
+      currentOperation: 'Creating webvh DID document',
+      progress: 30
+    });
+
+    // Migrate DID document to webvh
+    const migratedDoc = await this.didManager.migrateToDIDWebVH(sourceDid, options.domain);
+
+    await this.updateStateWithRetry(migrationId, {
+      currentOperation: 'Migration completed',
+      progress: 100,
+      targetDid: migratedDoc.id
+    });
+
+    return {
+      targetDid: migratedDoc.id,
+      didDocument: migratedDoc
+    };
+  }
+
+  /**
+   * Estimate cost for peer → webvh migration
+   */
+  async estimateCost(options: MigrationOptions): Promise<CostEstimate> {
+    // Web hosting is typically negligible cost
+    return {
+      storageCost: 0,
+      networkFees: 0,
+      totalCost: 0,
+      currency: 'sats'
+    };
+  }
+}

package/src/migration/operations/WebvhToBtcoMigration.ts

@@ -0,0 +1,105 @@
+/**
+ * WebvhToBtcoMigration - Handles migration from did:webvh 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 WebvhToBtcoMigration 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 webvh → btco migration
+   */
+  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 webvh → 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'
+    };
+  }
+}