@originals/sdk 1.4.3 → 1.5.0

package/dist/migration/checkpoint/CheckpointManager.js

@@ -0,0 +1,96 @@
+/**
+ * CheckpointManager - Creates and manages migration checkpoints for rollback
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { CheckpointStorage } from './CheckpointStorage';
+export class CheckpointManager {
+    constructor(config, didManager, credentialManager) {
+        this.config = config;
+        this.didManager = didManager;
+        this.credentialManager = credentialManager;
+        this.storage = new CheckpointStorage(config);
+    }
+    /**
+     * Create a checkpoint before migration
+     */
+    async createCheckpoint(migrationId, options) {
+        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 = {
+                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) {
+        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) {
+        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() {
+        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);
+        }
+    }
+    extractLayer(did) {
+        if (did.startsWith('did:peer:'))
+            return 'peer';
+        if (did.startsWith('did:webvh:'))
+            return 'webvh';
+        if (did.startsWith('did:btco:'))
+            return 'btco';
+        return null;
+    }
+}

package/dist/migration/checkpoint/CheckpointStorage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CheckpointStorage - Persists checkpoints to storage
+ */
+import { MigrationCheckpoint } from '../types';
+import { OriginalsConfig } from '../../types';
+export declare class CheckpointStorage {
+    private config;
+    private checkpoints;
+    constructor(config: OriginalsConfig);
+    /**
+     * Save a checkpoint
+     */
+    save(checkpoint: MigrationCheckpoint): Promise<void>;
+    /**
+     * Retrieve a checkpoint
+     */
+    get(checkpointId: string): Promise<MigrationCheckpoint | null>;
+    /**
+     * Delete a checkpoint
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Delete checkpoints older than specified timestamp
+     */
+    deleteOlderThan(cutoffTime: number): Promise<void>;
+}

package/dist/migration/checkpoint/CheckpointStorage.js

@@ -0,0 +1,89 @@
+/**
+ * CheckpointStorage - Persists checkpoints to storage
+ */
+export class CheckpointStorage {
+    constructor(config) {
+        this.config = config;
+        this.checkpoints = new Map();
+    }
+    /**
+     * Save a checkpoint
+     */
+    async save(checkpoint) {
+        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.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) {
+        // Try in-memory first
+        const memoryCheckpoint = this.checkpoints.get(checkpointId);
+        if (memoryCheckpoint) {
+            return memoryCheckpoint;
+        }
+        // Try loading from storage adapter
+        const storageAdapter = this.config.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) {
+        this.checkpoints.delete(checkpointId);
+        // Also delete from storage adapter
+        const storageAdapter = this.config.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) {
+        const toDelete = [];
+        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/dist/migration/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Migration module exports
+ * Provides DID layer migration capabilities with validation, checkpoints, and rollbacks
+ */
+export { MigrationManager } from './MigrationManager';
+export * from './types';
+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';
+export { CheckpointManager } from './checkpoint/CheckpointManager';
+export { CheckpointStorage } from './checkpoint/CheckpointStorage';
+export { RollbackManager } from './rollback/RollbackManager';
+export { StateTracker } from './state/StateTracker';
+export { StateMachine } from './state/StateMachine';
+export { AuditLogger } from './audit/AuditLogger';
+export { BaseMigration } from './operations/BaseMigration';
+export { PeerToWebvhMigration } from './operations/PeerToWebvhMigration';
+export { WebvhToBtcoMigration } from './operations/WebvhToBtcoMigration';
+export { PeerToBtcoMigration } from './operations/PeerToBtcoMigration';

package/dist/migration/index.js

@@ -0,0 +1,27 @@
+/**
+ * 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/dist/migration/operations/BaseMigration.d.ts

@@ -0,0 +1,48 @@
+/**
+ * BaseMigration - Base class for all migration operations
+ */
+import { MigrationOptions, MigrationError, MigrationErrorType, 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 declare abstract class BaseMigration {
+    protected config: OriginalsConfig;
+    protected didManager: DIDManager;
+    protected credentialManager: CredentialManager;
+    protected stateTracker: StateTracker;
+    protected eventEmitter: EventEmitter;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager, stateTracker: StateTracker);
+    /**
+     * 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 emitEvent(type: string, data: any): Promise<void>;
+    /**
+     * Create migration error
+     */
+    protected createError(type: MigrationErrorType, code: string, message: string, migrationId?: string, details?: any): MigrationError;
+    /**
+     * Update migration state with error handling
+     */
+    protected updateStateWithRetry(migrationId: string, updates: any, maxRetries?: number): Promise<void>;
+    /**
+     * Resolve source DID document
+     */
+    protected resolveSourceDid(sourceDid: string): Promise<DIDDocument>;
+    /**
+     * Extract layer from DID
+     */
+    protected extractLayer(did: string): 'peer' | 'webvh' | 'btco';
+}

package/dist/migration/operations/BaseMigration.js

@@ -0,0 +1,83 @@
+/**
+ * BaseMigration - Base class for all migration operations
+ */
+import { EventEmitter } from '../../events/EventEmitter';
+export class BaseMigration {
+    constructor(config, didManager, credentialManager, stateTracker) {
+        this.config = config;
+        this.didManager = didManager;
+        this.credentialManager = credentialManager;
+        this.stateTracker = stateTracker;
+        this.eventEmitter = new EventEmitter();
+    }
+    /**
+     * Emit migration 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);
+        }
+    }
+    /**
+     * Create migration error
+     */
+    createError(type, code, message, migrationId, details) {
+        return {
+            type,
+            code,
+            message,
+            technicalDetails: details ? JSON.stringify(details) : undefined,
+            migrationId,
+            timestamp: Date.now()
+        };
+    }
+    /**
+     * Update migration state with error handling
+     */
+    async updateStateWithRetry(migrationId, updates, maxRetries = 3) {
+        let lastError = 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
+     */
+    async resolveSourceDid(sourceDid) {
+        const didDocument = await this.didManager.resolveDID(sourceDid);
+        if (!didDocument) {
+            throw new Error(`Could not resolve source DID: ${sourceDid}`);
+        }
+        return didDocument;
+    }
+    /**
+     * 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}`);
+    }
+}

package/dist/migration/operations/PeerToBtcoMigration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PeerToBtcoMigration - Handles direct migration from did:peer to did:btco
+ */
+import { MigrationOptions, CostEstimate } 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 declare class PeerToBtcoMigration extends BaseMigration {
+    private bitcoinManager;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager, stateTracker: StateTracker, bitcoinManager: BitcoinManager);
+    /**
+     * Execute peer → btco migration (direct, skipping webvh layer)
+     */
+    executeMigration(options: MigrationOptions, migrationId: string): Promise<{
+        targetDid: string;
+        didDocument: DIDDocument;
+    }>;
+    /**
+     * Estimate cost for peer → btco migration
+     */
+    estimateCost(options: MigrationOptions): Promise<CostEstimate>;
+}

package/dist/migration/operations/PeerToBtcoMigration.js

@@ -0,0 +1,67 @@
+/**
+ * PeerToBtcoMigration - Handles direct migration from did:peer to did:btco
+ */
+import { MigrationStateEnum } from '../types';
+import { BaseMigration } from './BaseMigration';
+export class PeerToBtcoMigration extends BaseMigration {
+    constructor(config, didManager, credentialManager, stateTracker, bitcoinManager) {
+        super(config, didManager, credentialManager, stateTracker);
+        this.bitcoinManager = bitcoinManager;
+    }
+    /**
+     * Execute peer → btco migration (direct, skipping webvh layer)
+     */
+    async executeMigration(options, migrationId) {
+        // 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) {
+        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/dist/migration/operations/PeerToWebvhMigration.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PeerToWebvhMigration - Handles migration from did:peer to did:webvh
+ */
+import { MigrationOptions, CostEstimate } from '../types';
+import { DIDDocument } from '../../types';
+import { BaseMigration } from './BaseMigration';
+export declare class PeerToWebvhMigration extends BaseMigration {
+    /**
+     * Execute peer → webvh migration
+     */
+    executeMigration(options: MigrationOptions, migrationId: string): Promise<{
+        targetDid: string;
+        didDocument: DIDDocument;
+    }>;
+    /**
+     * Estimate cost for peer → webvh migration
+     */
+    estimateCost(options: MigrationOptions): Promise<CostEstimate>;
+}

package/dist/migration/operations/PeerToWebvhMigration.js

@@ -0,0 +1,46 @@
+/**
+ * PeerToWebvhMigration - Handles migration from did:peer to did:webvh
+ */
+import { MigrationStateEnum } from '../types';
+import { BaseMigration } from './BaseMigration';
+export class PeerToWebvhMigration extends BaseMigration {
+    /**
+     * Execute peer → webvh migration
+     */
+    async executeMigration(options, migrationId) {
+        // 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) {
+        // Web hosting is typically negligible cost
+        return {
+            storageCost: 0,
+            networkFees: 0,
+            totalCost: 0,
+            currency: 'sats'
+        };
+    }
+}

package/dist/migration/operations/WebvhToBtcoMigration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * WebvhToBtcoMigration - Handles migration from did:webvh to did:btco
+ */
+import { MigrationOptions, CostEstimate } 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 declare class WebvhToBtcoMigration extends BaseMigration {
+    private bitcoinManager;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager, stateTracker: StateTracker, bitcoinManager: BitcoinManager);
+    /**
+     * Execute webvh → btco migration
+     */
+    executeMigration(options: MigrationOptions, migrationId: string): Promise<{
+        targetDid: string;
+        didDocument: DIDDocument;
+    }>;
+    /**
+     * Estimate cost for webvh → btco migration
+     */
+    estimateCost(options: MigrationOptions): Promise<CostEstimate>;
+}

package/dist/migration/operations/WebvhToBtcoMigration.js

@@ -0,0 +1,67 @@
+/**
+ * WebvhToBtcoMigration - Handles migration from did:webvh to did:btco
+ */
+import { MigrationStateEnum } from '../types';
+import { BaseMigration } from './BaseMigration';
+export class WebvhToBtcoMigration extends BaseMigration {
+    constructor(config, didManager, credentialManager, stateTracker, bitcoinManager) {
+        super(config, didManager, credentialManager, stateTracker);
+        this.bitcoinManager = bitcoinManager;
+    }
+    /**
+     * Execute webvh → btco migration
+     */
+    async executeMigration(options, migrationId) {
+        // 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) {
+        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'
+        };
+    }
+}