@originals/sdk 1.4.2 → 1.4.5

package/dist/migration/MigrationManager.js

@@ -0,0 +1,412 @@
+/**
+ * MigrationManager - Main orchestrator for DID layer migrations
+ * Coordinates validation, checkpoints, rollbacks, state tracking, and audit logging
+ */
+import { MigrationStateEnum, MigrationErrorType } from './types';
+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 {
+    constructor(config, didManager, credentialManager, bitcoinManager) {
+        this.config = config;
+        this.didManager = didManager;
+        this.credentialManager = credentialManager;
+        this.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;
+            this.peerToBtco = null;
+        }
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance(config, didManager, credentialManager, bitcoinManager) {
+        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() {
+        MigrationManager.instance = null;
+    }
+    /**
+     * Main migration method
+     */
+    async migrate(options) {
+        const startTime = Date.now();
+        let migrationState;
+        let checkpoint;
+        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, targetLayer, feeRate) {
+        const options = {
+            sourceDid,
+            targetLayer: targetLayer,
+            feeRate,
+            estimateCostOnly: true
+        };
+        const validationResult = await this.validationPipeline.validate(options);
+        return validationResult.estimatedCost;
+    }
+    /**
+     * Get migration status
+     */
+    async getMigrationStatus(migrationId) {
+        return await this.stateTracker.getState(migrationId);
+    }
+    /**
+     * Rollback a migration
+     */
+    async rollback(migrationId) {
+        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) {
+        return this.inMemoryAuditRecords.get(did) || [];
+    }
+    /**
+     * Batch migration
+     */
+    async migrateBatch(dids, targetLayer, options) {
+        const batchId = `batch_${Date.now()}`;
+        const results = new Map();
+        const errors = [];
+        let completed = 0;
+        let failed = 0;
+        const total = dids.length;
+        for (const did of dids) {
+            try {
+                const migrationOptions = {
+                    sourceDid: did,
+                    targetLayer: targetLayer,
+                    ...options
+                };
+                const result = await this.migrate(migrationOptions);
+                results.set(did, result);
+                if (result.success) {
+                    completed++;
+                }
+                else {
+                    failed++;
+                }
+            }
+            catch (error) {
+                failed++;
+                const 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
+     */
+    async handleMigrationFailure(error, options, migrationState, checkpoint, startTime) {
+        const migrationId = migrationState?.migrationId || `mig_failed_${Date.now()}`;
+        const 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
+     */
+    getMigrationOperation(options) {
+        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
+     */
+    storeAuditRecordInMemory(record) {
+        // 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
+     */
+    extractLayer(did) {
+        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
+     */
+    createMigrationError(type, code, message, migrationId, details) {
+        const error = new Error(message);
+        error.type = type;
+        error.code = code;
+        error.migrationId = migrationId;
+        error.details = details;
+        return error;
+    }
+    /**
+     * Emit event
+     */
+    async emitEvent(type, data) {
+        try {
+            await this.eventEmitter.emit({
+                type,
+                timestamp: new Date().toISOString(),
+                ...data
+            });
+        }
+        catch (error) {
+            console.error(`Error emitting event ${type}:`, error);
+        }
+    }
+}
+MigrationManager.instance = null;

package/dist/migration/audit/AuditLogger.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AuditLogger - Creates and manages migration audit records
+ */
+import { MigrationAuditRecord, IAuditLogger } from '../types';
+import { OriginalsConfig } from '../../types';
+export declare class AuditLogger implements IAuditLogger {
+    private config;
+    private auditRecords;
+    constructor(config: OriginalsConfig);
+    /**
+     * Log a migration audit record
+     */
+    logMigration(record: MigrationAuditRecord): Promise<void>;
+    /**
+     * Get migration history for a DID
+     */
+    getMigrationHistory(did: string): Promise<MigrationAuditRecord[]>;
+    /**
+     * Get system-wide migration logs with filters
+     * Fixed dedupe logic: use signature to avoid timeline collapse
+     */
+    getSystemMigrationLogs(filters: Partial<MigrationAuditRecord>): Promise<MigrationAuditRecord[]>;
+    /**
+     * 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 signAuditRecord;
+    /**
+     * Verify an audit record signature
+     */
+    verifyAuditRecord(record: MigrationAuditRecord): Promise<boolean>;
+    /**
+     * Persist audit record to storage (append-only, never overwrite)
+     * Updated key design: audit/migrations/{migrationId}/{timestamp}-{finalState}.json
+     */
+    private persistAuditRecord;
+    /**
+     * Load audit records from storage
+     */
+    loadAuditRecords(did: string): Promise<void>;
+}

package/dist/migration/audit/AuditLogger.js

@@ -0,0 +1,156 @@
+/**
+ * AuditLogger - Creates and manages migration audit records
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { encodeBase64UrlMultibase } from '../../utils/encoding';
+export class AuditLogger {
+    constructor(config) {
+        this.config = config;
+        this.auditRecords = new Map();
+    }
+    /**
+     * Log a migration audit record
+     */
+    async logMigration(record) {
+        // 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) {
+        return this.auditRecords.get(did) || [];
+    }
+    /**
+     * Get system-wide migration logs with filters
+     * Fixed dedupe logic: use signature to avoid timeline collapse
+     */
+    async getSystemMigrationLogs(filters) {
+        const allRecords = [];
+        // Collect all unique records (dedupe by signature to preserve timeline)
+        const seen = new Set();
+        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] !== 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);
+     */
+    async signAuditRecord(record) {
+        // Create a canonical representation of the record (without signature)
+        const { signature, ...recordWithoutSig } = record;
+        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) {
+        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
+     */
+    async persistAuditRecord(record) {
+        const storageAdapter = this.config.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) {
+        const storageAdapter = this.config.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 = 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/dist/migration/checkpoint/CheckpointManager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CheckpointManager - Creates and manages migration checkpoints for rollback
+ */
+import { MigrationOptions, MigrationCheckpoint, ICheckpointManager } from '../types';
+import { OriginalsConfig } from '../../types';
+import { DIDManager } from '../../did/DIDManager';
+import { CredentialManager } from '../../vc/CredentialManager';
+export declare class CheckpointManager implements ICheckpointManager {
+    private config;
+    private didManager;
+    private credentialManager;
+    private storage;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager);
+    /**
+     * Create a checkpoint before migration
+     */
+    createCheckpoint(migrationId: string, options: MigrationOptions): Promise<MigrationCheckpoint>;
+    /**
+     * Retrieve a checkpoint by ID
+     */
+    getCheckpoint(checkpointId: string): Promise<MigrationCheckpoint | null>;
+    /**
+     * Delete a checkpoint (after successful migration or cleanup)
+     */
+    deleteCheckpoint(checkpointId: string): Promise<void>;
+    /**
+     * Clean up old checkpoints (older than 24 hours for successful migrations)
+     */
+    cleanupOldCheckpoints(): Promise<void>;
+    private extractLayer;
+}