@originals/sdk 1.8.0 → 1.8.2

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);
+    }
+  }
+}

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'
+    };
+  }
+}