@originals/sdk 1.1.0

package/src/migration/types.ts

@@ -0,0 +1,344 @@
+/**
+ * Migration system types and interfaces
+ * Defines all types used across the migration infrastructure
+ */
+
+import { DIDDocument, VerifiableCredential } from '../types';
+
+/**
+ * DID layer types
+ */
+export type DIDLayer = 'peer' | 'webvh' | 'btco';
+
+/**
+ * Migration state enum
+ */
+export enum MigrationStateEnum {
+  PENDING = 'pending',           // Migration queued
+  VALIDATING = 'validating',     // Running validation pipeline
+  CHECKPOINTED = 'checkpointed', // Checkpoint created
+  IN_PROGRESS = 'in_progress',   // Active migration
+  ANCHORING = 'anchoring',       // Bitcoin anchoring (btco only)
+  COMPLETED = 'completed',       // Successfully completed
+  FAILED = 'failed',             // Failed, rollback initiated
+  ROLLED_BACK = 'rolled_back',   // Rolled back successfully
+  QUARANTINED = 'quarantined'    // Rollback failed, needs manual intervention
+}
+
+/**
+ * Migration error types
+ */
+export enum MigrationErrorType {
+  VALIDATION_ERROR = 'validation_error',     // Pre-migration validation failed
+  STORAGE_ERROR = 'storage_error',           // Storage adapter failure
+  BITCOIN_ERROR = 'bitcoin_error',           // Bitcoin anchoring failed
+  CREDENTIAL_ERROR = 'credential_error',     // Credential re-issuance failed
+  NETWORK_ERROR = 'network_error',           // Network/connectivity failure
+  ROLLBACK_ERROR = 'rollback_error',         // Rollback failed (critical)
+  TIMEOUT_ERROR = 'timeout_error',           // Operation timeout
+  UNKNOWN_ERROR = 'unknown_error'            // Unexpected error
+}
+
+/**
+ * Migration options for initiating a migration
+ */
+export interface MigrationOptions {
+  sourceDid: string;                    // Source DID to migrate from
+  targetLayer: DIDLayer;                // Target layer
+  credentialIssuance?: boolean;         // Require VC issuance (default: true)
+  batchMode?: boolean;                  // Batch operation flag
+  partialMode?: {                       // For large files
+    chunkSize: number;                  // Bytes per chunk
+    resumable: boolean;                 // Support resume
+  };
+  estimateCostOnly?: boolean;           // Return cost estimate without migrating
+  metadata?: Record<string, any>;       // Additional migration metadata
+  domain?: string;                      // For webvh migrations
+  satoshi?: string;                     // For btco migrations
+  feeRate?: number;                     // For btco migrations
+}
+
+/**
+ * Batch migration options
+ */
+export interface BatchMigrationOptions extends MigrationOptions {
+  maxConcurrent?: number;               // Max concurrent migrations
+  continueOnError?: boolean;            // Continue batch if individual migration fails
+}
+
+/**
+ * Cost estimate for a migration
+ */
+export interface CostEstimate {
+  storageCost: number;                  // Storage cost in currency units
+  networkFees: number;                  // Bitcoin network fees (btco only)
+  totalCost: number;                    // Total cost
+  currency: string;                     // Currency unit (e.g., 'sats', 'USD')
+}
+
+/**
+ * Validation error
+ */
+export interface ValidationError {
+  code: string;
+  message: string;
+  field?: string;
+  details?: any;
+}
+
+/**
+ * Validation warning
+ */
+export interface ValidationWarning {
+  code: string;
+  message: string;
+  field?: string;
+}
+
+/**
+ * Migration validation result
+ */
+export interface MigrationValidationResult {
+  valid: boolean;
+  errors: ValidationError[];            // Blocking errors
+  warnings: ValidationWarning[];        // Non-blocking issues
+  estimatedCost: CostEstimate;
+  estimatedDuration: number;            // milliseconds
+}
+
+/**
+ * Migration checkpoint data
+ */
+export interface MigrationCheckpoint {
+  checkpointId?: string;
+  migrationId: string;
+  timestamp: number;
+  sourceDid: string;
+  sourceLayer: DIDLayer;
+  didDocument: DIDDocument;
+  credentials: VerifiableCredential[];
+  storageReferences: Record<string, any>;
+  lifecycleState: any;
+  ownershipProofs: any[];
+  metadata: Record<string, any>;
+}
+
+/**
+ * Rollback result
+ */
+export interface RollbackResult {
+  success: boolean;
+  migrationId: string;
+  checkpointId?: string;
+  restoredState: MigrationStateEnum;
+  duration: number;                     // milliseconds
+  errors?: MigrationError[];
+}
+
+/**
+ * Migration state tracking
+ */
+export interface MigrationState {
+  migrationId: string;
+  state: MigrationStateEnum;
+  sourceDid: string;
+  sourceLayer: DIDLayer;
+  targetDid?: string;
+  targetLayer: DIDLayer;
+  progress: number;                     // 0-100
+  currentOperation: string;
+  startTime: number;
+  endTime?: number;
+  error?: MigrationError;
+  checkpointId?: string;
+}
+
+/**
+ * Migration error details
+ */
+export interface MigrationError {
+  type: MigrationErrorType;
+  code: string;
+  message: string;
+  technicalDetails?: string;
+  suggestedRecovery?: string;
+  migrationId?: string;
+  sourceDid?: string;
+  targetDid?: string;
+  timestamp: number;
+  stack?: string;
+}
+
+/**
+ * Migration audit record
+ */
+export interface MigrationAuditRecord {
+  migrationId: string;
+  timestamp: number;
+  initiator: string;                    // User/system identifier
+  sourceDid: string;
+  sourceLayer: DIDLayer;
+  targetDid: string | null;             // null if failed before creation
+  targetLayer: DIDLayer;
+  finalState: MigrationStateEnum;
+  validationResults: MigrationValidationResult;
+  costActual: CostEstimate;             // Actual costs incurred
+  duration: number;                     // milliseconds
+  checkpointId?: string;                 // For rollback reference
+  errors: MigrationError[];             // Any errors encountered
+  metadata: Record<string, any>;        // Custom metadata
+  signature?: string;                   // Cryptographic signature
+}
+
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+  migrationId: string;
+  success: boolean;
+  sourceDid: string;
+  targetDid?: string;
+  sourceLayer: DIDLayer;
+  targetLayer: DIDLayer;
+  state: MigrationStateEnum;
+  duration: number;
+  cost: CostEstimate;
+  auditRecord?: MigrationAuditRecord;  // Optional - undefined when AuditLogger disabled (v1.0)
+  error?: MigrationError;
+}
+
+/**
+ * Batch migration result
+ */
+export interface BatchMigrationResult {
+  batchId: string;
+  total: number;
+  completed: number;
+  failed: number;
+  inProgress: number;
+  results: Map<string, MigrationResult>;  // sourceDid → result
+  overallProgress: number;                // 0-100
+  startTime: number;
+  endTime?: number;
+  errors: MigrationError[];
+}
+
+/**
+ * Partial migration progress
+ */
+export interface PartialMigrationProgress {
+  totalChunks: number;
+  completedChunks: number;
+  currentChunk: number;
+  bytesTransferred: number;
+  totalBytes: number;
+  percentComplete: number;
+  estimatedTimeRemaining: number;       // milliseconds
+}
+
+/**
+ * Migration event types
+ */
+export type MigrationEventType =
+  | 'migration:started'
+  | 'migration:validated'
+  | 'migration:checkpointed'
+  | 'migration:in_progress'
+  | 'migration:anchoring'
+  | 'migration:completed'
+  | 'migration:failed'
+  | 'migration:rolledback'
+  | 'migration:quarantine'
+  | 'batch:progress';
+
+/**
+ * Migration event payload
+ */
+export interface MigrationEvent {
+  type: MigrationEventType;
+  migrationId: string;
+  timestamp: number;
+  state: MigrationStateEnum;
+  data?: any;
+}
+
+/**
+ * Storage migration context
+ */
+export interface StorageMigrationContext {
+  sourceDid: string;
+  targetDid: string;
+  sourceLayer: DIDLayer;
+  targetLayer: DIDLayer;
+  resources: Array<{
+    id: string;
+    hash: string;
+    contentType: string;
+    size: number;
+    url?: string;
+  }>;
+}
+
+/**
+ * Bitcoin anchoring context
+ */
+export interface BitcoinAnchoringContext {
+  didDocument: DIDDocument;
+  migrationMetadata: Record<string, any>;
+  network: 'mainnet' | 'testnet' | 'signet';
+  feeRate?: number;
+  satoshi?: string;
+}
+
+/**
+ * Lifecycle migration context
+ */
+export interface LifecycleMigrationContext {
+  sourceDid: string;
+  targetDid: string;
+  currentState: any;
+  eventHistory: any[];
+  migrationId: string;
+}
+
+/**
+ * Validator interface
+ */
+export interface IValidator {
+  validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+}
+
+/**
+ * Checkpoint manager interface
+ */
+export interface ICheckpointManager {
+  createCheckpoint(migrationId: string, options: MigrationOptions): Promise<MigrationCheckpoint>;
+  getCheckpoint(checkpointId: string): Promise<MigrationCheckpoint | null>;
+  deleteCheckpoint(checkpointId: string): Promise<void>;
+}
+
+/**
+ * Rollback manager interface
+ */
+export interface IRollbackManager {
+  rollback(migrationId: string, checkpointId: string): Promise<RollbackResult>;
+}
+
+/**
+ * State tracker interface
+ */
+export interface IStateTracker {
+  createMigration(options: MigrationOptions): Promise<MigrationState>;
+  updateState(migrationId: string, updates: Partial<MigrationState>): Promise<void>;
+  getState(migrationId: string): Promise<MigrationState | null>;
+  queryStates(filters: Partial<MigrationState>): Promise<MigrationState[]>;
+}
+
+/**
+ * Audit logger interface
+ */
+export interface IAuditLogger {
+  logMigration(record: MigrationAuditRecord): Promise<void>;
+  getMigrationHistory(did: string): Promise<MigrationAuditRecord[]>;
+  getSystemMigrationLogs(filters: any): Promise<MigrationAuditRecord[]>;
+}

package/src/migration/validation/BitcoinValidator.ts

@@ -0,0 +1,107 @@
+/**
+ * BitcoinValidator - Validates Bitcoin network requirements for btco migrations
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  IValidator
+} from '../types';
+import { OriginalsConfig } from '../../types';
+import { BitcoinManager } from '../../bitcoin/BitcoinManager';
+
+export class BitcoinValidator implements IValidator {
+  constructor(
+    private config: OriginalsConfig,
+    private bitcoinManager: BitcoinManager
+  ) {}
+
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    try {
+      // Only validate for btco migrations
+      if (options.targetLayer !== 'btco') {
+        return this.createResult(true, errors, warnings, 0, 0);
+      }
+
+      // Check if Bitcoin provider is configured
+      const ordinalsProvider = this.config.ordinalsProvider;
+      if (!ordinalsProvider) {
+        errors.push({
+          code: 'BITCOIN_PROVIDER_REQUIRED',
+          message: 'Ordinals provider is required for btco migrations',
+          details: { targetLayer: options.targetLayer }
+        });
+        return this.createResult(false, errors, warnings, 0, 0);
+      }
+
+      // Estimate Bitcoin network fees
+      let networkFees = 0;
+      let estimatedDuration = 600000; // 10 minutes default
+
+      try {
+        // Estimate fee for a typical inscription (assume 1KB data)
+        const estimatedSize = 1024; // bytes
+        const feeRate = options.feeRate || 10; // sats/vB
+        networkFees = estimatedSize * feeRate;
+
+        // Check if fee is within reasonable limits
+        if (feeRate > 1000) {
+          warnings.push({
+            code: 'HIGH_FEE_RATE',
+            message: `Fee rate of ${feeRate} sat/vB is unusually high`,
+            field: 'feeRate'
+          });
+        }
+      } catch (error) {
+        warnings.push({
+          code: 'FEE_ESTIMATION_FAILED',
+          message: `Could not estimate Bitcoin network fees: ${error instanceof Error ? error.message : String(error)}`
+        });
+        networkFees = 10240; // Default fallback: ~1KB at 10 sat/vB
+      }
+
+      // Validate network (should be signet for testnet)
+      if (this.config.network !== 'mainnet' && this.config.network !== 'signet') {
+        warnings.push({
+          code: 'NETWORK_MISMATCH',
+          message: `Network '${this.config.network}' will use signet for Bitcoin anchoring`
+        });
+      }
+
+      return this.createResult(true, errors, warnings, networkFees, estimatedDuration);
+    } catch (error) {
+      errors.push({
+        code: 'BITCOIN_VALIDATION_ERROR',
+        message: 'Error validating Bitcoin requirements',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+      return this.createResult(false, errors, warnings, 0, 0);
+    }
+  }
+
+  private createResult(
+    valid: boolean,
+    errors: ValidationError[],
+    warnings: ValidationWarning[],
+    networkFees: number,
+    duration: number
+  ): MigrationValidationResult {
+    return {
+      valid,
+      errors,
+      warnings,
+      estimatedCost: {
+        storageCost: 0,
+        networkFees,
+        totalCost: networkFees,
+        currency: 'sats'
+      },
+      estimatedDuration: duration
+    };
+  }
+}

package/src/migration/validation/CredentialValidator.ts

@@ -0,0 +1,62 @@
+/**
+ * CredentialValidator - Validates credential compatibility for migration
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  IValidator
+} from '../types';
+import { OriginalsConfig } from '../../types';
+import { CredentialManager } from '../../vc/CredentialManager';
+
+export class CredentialValidator implements IValidator {
+  constructor(
+    private config: OriginalsConfig,
+    private credentialManager: CredentialManager
+  ) {}
+
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    try {
+      // Credential validation is optional if credentialIssuance is false
+      if (options.credentialIssuance === false) {
+        return this.createResult(true, errors, warnings);
+      }
+
+      // All credential types are compatible with all layers
+      // This validator primarily checks that credential issuance is possible
+
+      // For now, credentials are always compatible
+      // Future enhancements could include schema validation
+
+      return this.createResult(true, errors, warnings);
+    } catch (error) {
+      errors.push({
+        code: 'CREDENTIAL_VALIDATION_ERROR',
+        message: 'Error validating credential compatibility',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+      return this.createResult(false, errors, warnings);
+    }
+  }
+
+  private createResult(valid: boolean, errors: ValidationError[], warnings: ValidationWarning[]): MigrationValidationResult {
+    return {
+      valid,
+      errors,
+      warnings,
+      estimatedCost: {
+        storageCost: 0,
+        networkFees: 0,
+        totalCost: 0,
+        currency: 'sats'
+      },
+      estimatedDuration: 50 // Credential validation typically takes ~50ms
+    };
+  }
+}

package/src/migration/validation/DIDCompatibilityValidator.ts

@@ -0,0 +1,151 @@
+/**
+ * DIDCompatibilityValidator - Validates DID document compatibility between layers
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  IValidator
+} from '../types';
+import { OriginalsConfig } from '../../types';
+import { DIDManager } from '../../did/DIDManager';
+
+export class DIDCompatibilityValidator implements IValidator {
+  constructor(
+    private config: OriginalsConfig,
+    private didManager: DIDManager
+  ) {}
+
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    try {
+      // Resolve source DID
+      const sourceDid = await this.didManager.resolveDID(options.sourceDid);
+      if (!sourceDid) {
+        errors.push({
+          code: 'SOURCE_DID_NOT_FOUND',
+          message: `Could not resolve source DID: ${options.sourceDid}`,
+          field: 'sourceDid'
+        });
+        return this.createResult(false, errors, warnings);
+      }
+
+      // Extract source layer from DID
+      const sourceLayer = this.extractLayer(options.sourceDid);
+      if (!sourceLayer) {
+        errors.push({
+          code: 'INVALID_SOURCE_DID_FORMAT',
+          message: 'Source DID has unsupported format',
+          field: 'sourceDid',
+          details: { did: options.sourceDid }
+        });
+        return this.createResult(false, errors, warnings);
+      }
+
+      // Validate migration path
+      const pathErrors = this.validateMigrationPath(sourceLayer, options.targetLayer);
+      errors.push(...pathErrors);
+
+      if (errors.length > 0) {
+        return this.createResult(false, errors, warnings);
+      }
+
+      // Validate verification methods compatibility
+      if (sourceDid.verificationMethod && Array.isArray(sourceDid.verificationMethod)) {
+        for (const vm of sourceDid.verificationMethod) {
+          if (!this.isVerificationMethodCompatible(vm, options.targetLayer)) {
+            warnings.push({
+              code: 'VERIFICATION_METHOD_INCOMPATIBLE',
+              message: `Verification method ${vm.id} may not be compatible with ${options.targetLayer}`,
+              field: 'verificationMethod'
+            });
+          }
+        }
+      }
+
+      // Validate service endpoints
+      if (sourceDid.service && Array.isArray(sourceDid.service)) {
+        if (options.targetLayer === 'peer' && sourceDid.service.length > 0) {
+          warnings.push({
+            code: 'SERVICE_ENDPOINTS_ON_PEER',
+            message: 'Service endpoints on peer DIDs may have limited discoverability'
+          });
+        }
+      }
+
+      return this.createResult(true, errors, warnings);
+    } catch (error) {
+      errors.push({
+        code: 'DID_VALIDATION_ERROR',
+        message: 'Error validating DID compatibility',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+      return this.createResult(false, errors, warnings);
+    }
+  }
+
+  private extractLayer(did: string): string | null {
+    if (did.startsWith('did:peer:')) return 'peer';
+    if (did.startsWith('did:webvh:')) return 'webvh';
+    if (did.startsWith('did:btco:')) return 'btco';
+    return null;
+  }
+
+  private validateMigrationPath(sourceLayer: string, targetLayer: string): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    // Check for invalid reverse migrations
+    const layerOrder = { peer: 0, webvh: 1, btco: 2 };
+    const sourceOrder = layerOrder[sourceLayer as keyof typeof layerOrder];
+    const targetOrder = layerOrder[targetLayer as keyof typeof layerOrder];
+
+    if (sourceOrder === undefined || targetOrder === undefined) {
+      errors.push({
+        code: 'INVALID_LAYER',
+        message: 'Invalid source or target layer',
+        details: { sourceLayer, targetLayer }
+      });
+      return errors;
+    }
+
+    if (sourceOrder >= targetOrder) {
+      errors.push({
+        code: 'INVALID_MIGRATION_PATH',
+        message: `Cannot migrate from ${sourceLayer} to ${targetLayer}. Migrations must move forward through layers (peer → webvh → btco)`,
+        details: { sourceLayer, targetLayer }
+      });
+    }
+
+    return errors;
+  }
+
+  private isVerificationMethodCompatible(vm: any, targetLayer: string): boolean {
+    // All verification method types are compatible with all layers
+    // This is a placeholder for more sophisticated compatibility checks
+    if (!vm.type) return false;
+
+    // Common types that are widely supported
+    const supportedTypes = ['Multikey', 'Ed25519VerificationKey2020', 'EcdsaSecp256k1VerificationKey2019'];
+
+    return supportedTypes.includes(vm.type);
+  }
+
+  private createResult(valid: boolean, errors: ValidationError[], warnings: ValidationWarning[]): MigrationValidationResult {
+    return {
+      valid,
+      errors,
+      warnings,
+      estimatedCost: {
+        storageCost: 0,
+        networkFees: 0,
+        totalCost: 0,
+        currency: 'sats'
+      },
+      estimatedDuration: 100 // DID validation typically takes ~100ms
+    };
+  }
+}