@originals/sdk 1.4.2 → 1.4.5

package/src/migration/types.ts

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

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

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

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