@originals/sdk 1.4.2 → 1.4.5

package/dist/migration/types.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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 declare 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"
+}
+/**
+ * Migration error types
+ */
+export declare 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"
+}
+/**
+ * Migration options for initiating a migration
+ */
+export interface MigrationOptions {
+    sourceDid: string;
+    targetLayer: DIDLayer;
+    credentialIssuance?: boolean;
+    batchMode?: boolean;
+    partialMode?: {
+        chunkSize: number;
+        resumable: boolean;
+    };
+    estimateCostOnly?: boolean;
+    metadata?: Record<string, any>;
+    domain?: string;
+    satoshi?: string;
+    feeRate?: number;
+}
+/**
+ * Batch migration options
+ */
+export interface BatchMigrationOptions extends MigrationOptions {
+    maxConcurrent?: number;
+    continueOnError?: boolean;
+}
+/**
+ * Cost estimate for a migration
+ */
+export interface CostEstimate {
+    storageCost: number;
+    networkFees: number;
+    totalCost: number;
+    currency: string;
+}
+/**
+ * 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[];
+    warnings: ValidationWarning[];
+    estimatedCost: CostEstimate;
+    estimatedDuration: number;
+}
+/**
+ * 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;
+    errors?: MigrationError[];
+}
+/**
+ * Migration state tracking
+ */
+export interface MigrationState {
+    migrationId: string;
+    state: MigrationStateEnum;
+    sourceDid: string;
+    sourceLayer: DIDLayer;
+    targetDid?: string;
+    targetLayer: DIDLayer;
+    progress: number;
+    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;
+    sourceDid: string;
+    sourceLayer: DIDLayer;
+    targetDid: string | null;
+    targetLayer: DIDLayer;
+    finalState: MigrationStateEnum;
+    validationResults: MigrationValidationResult;
+    costActual: CostEstimate;
+    duration: number;
+    checkpointId?: string;
+    errors: MigrationError[];
+    metadata: Record<string, any>;
+    signature?: string;
+}
+/**
+ * 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;
+    error?: MigrationError;
+}
+/**
+ * Batch migration result
+ */
+export interface BatchMigrationResult {
+    batchId: string;
+    total: number;
+    completed: number;
+    failed: number;
+    inProgress: number;
+    results: Map<string, MigrationResult>;
+    overallProgress: number;
+    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;
+}
+/**
+ * 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/dist/migration/types.js

@@ -0,0 +1,33 @@
+/**
+ * Migration system types and interfaces
+ * Defines all types used across the migration infrastructure
+ */
+/**
+ * Migration state enum
+ */
+export var MigrationStateEnum;
+(function (MigrationStateEnum) {
+    MigrationStateEnum["PENDING"] = "pending";
+    MigrationStateEnum["VALIDATING"] = "validating";
+    MigrationStateEnum["CHECKPOINTED"] = "checkpointed";
+    MigrationStateEnum["IN_PROGRESS"] = "in_progress";
+    MigrationStateEnum["ANCHORING"] = "anchoring";
+    MigrationStateEnum["COMPLETED"] = "completed";
+    MigrationStateEnum["FAILED"] = "failed";
+    MigrationStateEnum["ROLLED_BACK"] = "rolled_back";
+    MigrationStateEnum["QUARANTINED"] = "quarantined"; // Rollback failed, needs manual intervention
+})(MigrationStateEnum || (MigrationStateEnum = {}));
+/**
+ * Migration error types
+ */
+export var MigrationErrorType;
+(function (MigrationErrorType) {
+    MigrationErrorType["VALIDATION_ERROR"] = "validation_error";
+    MigrationErrorType["STORAGE_ERROR"] = "storage_error";
+    MigrationErrorType["BITCOIN_ERROR"] = "bitcoin_error";
+    MigrationErrorType["CREDENTIAL_ERROR"] = "credential_error";
+    MigrationErrorType["NETWORK_ERROR"] = "network_error";
+    MigrationErrorType["ROLLBACK_ERROR"] = "rollback_error";
+    MigrationErrorType["TIMEOUT_ERROR"] = "timeout_error";
+    MigrationErrorType["UNKNOWN_ERROR"] = "unknown_error"; // Unexpected error
+})(MigrationErrorType || (MigrationErrorType = {}));

package/dist/migration/validation/BitcoinValidator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BitcoinValidator - Validates Bitcoin network requirements for btco migrations
+ */
+import { MigrationOptions, MigrationValidationResult, IValidator } from '../types';
+import { OriginalsConfig } from '../../types';
+import { BitcoinManager } from '../../bitcoin/BitcoinManager';
+export declare class BitcoinValidator implements IValidator {
+    private config;
+    private bitcoinManager;
+    constructor(config: OriginalsConfig, bitcoinManager: BitcoinManager);
+    validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+    private createResult;
+}

package/dist/migration/validation/BitcoinValidator.js

@@ -0,0 +1,83 @@
+/**
+ * BitcoinValidator - Validates Bitcoin network requirements for btco migrations
+ */
+export class BitcoinValidator {
+    constructor(config, bitcoinManager) {
+        this.config = config;
+        this.bitcoinManager = bitcoinManager;
+    }
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        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);
+        }
+    }
+    createResult(valid, errors, warnings, networkFees, duration) {
+        return {
+            valid,
+            errors,
+            warnings,
+            estimatedCost: {
+                storageCost: 0,
+                networkFees,
+                totalCost: networkFees,
+                currency: 'sats'
+            },
+            estimatedDuration: duration
+        };
+    }
+}

package/dist/migration/validation/CredentialValidator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CredentialValidator - Validates credential compatibility for migration
+ */
+import { MigrationOptions, MigrationValidationResult, IValidator } from '../types';
+import { OriginalsConfig } from '../../types';
+import { CredentialManager } from '../../vc/CredentialManager';
+export declare class CredentialValidator implements IValidator {
+    private config;
+    private credentialManager;
+    constructor(config: OriginalsConfig, credentialManager: CredentialManager);
+    validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+    private createResult;
+}

package/dist/migration/validation/CredentialValidator.js

@@ -0,0 +1,46 @@
+/**
+ * CredentialValidator - Validates credential compatibility for migration
+ */
+export class CredentialValidator {
+    constructor(config, credentialManager) {
+        this.config = config;
+        this.credentialManager = credentialManager;
+    }
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        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);
+        }
+    }
+    createResult(valid, errors, warnings) {
+        return {
+            valid,
+            errors,
+            warnings,
+            estimatedCost: {
+                storageCost: 0,
+                networkFees: 0,
+                totalCost: 0,
+                currency: 'sats'
+            },
+            estimatedDuration: 50 // Credential validation typically takes ~50ms
+        };
+    }
+}

package/dist/migration/validation/DIDCompatibilityValidator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DIDCompatibilityValidator - Validates DID document compatibility between layers
+ */
+import { MigrationOptions, MigrationValidationResult, IValidator } from '../types';
+import { OriginalsConfig } from '../../types';
+import { DIDManager } from '../../did/DIDManager';
+export declare class DIDCompatibilityValidator implements IValidator {
+    private config;
+    private didManager;
+    constructor(config: OriginalsConfig, didManager: DIDManager);
+    validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+    private extractLayer;
+    private validateMigrationPath;
+    private isVerificationMethodCompatible;
+    private createResult;
+}

package/dist/migration/validation/DIDCompatibilityValidator.js

@@ -0,0 +1,127 @@
+/**
+ * DIDCompatibilityValidator - Validates DID document compatibility between layers
+ */
+export class DIDCompatibilityValidator {
+    constructor(config, didManager) {
+        this.config = config;
+        this.didManager = didManager;
+    }
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        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);
+        }
+    }
+    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;
+    }
+    validateMigrationPath(sourceLayer, targetLayer) {
+        const errors = [];
+        // Check for invalid reverse migrations
+        const layerOrder = { peer: 0, webvh: 1, btco: 2 };
+        const sourceOrder = layerOrder[sourceLayer];
+        const targetOrder = layerOrder[targetLayer];
+        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;
+    }
+    isVerificationMethodCompatible(vm, targetLayer) {
+        // 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);
+    }
+    createResult(valid, errors, warnings) {
+        return {
+            valid,
+            errors,
+            warnings,
+            estimatedCost: {
+                storageCost: 0,
+                networkFees: 0,
+                totalCost: 0,
+                currency: 'sats'
+            },
+            estimatedDuration: 100 // DID validation typically takes ~100ms
+        };
+    }
+}

package/dist/migration/validation/LifecycleValidator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * LifecycleValidator - Validates lifecycle state transitions
+ */
+import { MigrationOptions, MigrationValidationResult, IValidator } from '../types';
+import { OriginalsConfig } from '../../types';
+export declare class LifecycleValidator implements IValidator {
+    private config;
+    constructor(config: OriginalsConfig);
+    validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+}