@originals/sdk 1.4.2 → 1.4.5

package/dist/migration/validation/LifecycleValidator.js

@@ -0,0 +1,52 @@
+/**
+ * LifecycleValidator - Validates lifecycle state transitions
+ */
+export class LifecycleValidator {
+    constructor(config) {
+        this.config = config;
+    }
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        try {
+            // All lifecycle states are compatible with all layers
+            // This validator checks for pending operations that might interfere
+            // For now, lifecycle is always compatible
+            // Future enhancements could check for:
+            // - Pending operations on source DID
+            // - State machine compatibility
+            // - Event history preservation capability
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+                estimatedCost: {
+                    storageCost: 0,
+                    networkFees: 0,
+                    totalCost: 0,
+                    currency: 'sats'
+                },
+                estimatedDuration: 30
+            };
+        }
+        catch (error) {
+            errors.push({
+                code: 'LIFECYCLE_VALIDATION_ERROR',
+                message: 'Error validating lifecycle compatibility',
+                details: { error: error instanceof Error ? error.message : String(error) }
+            });
+            return {
+                valid: false,
+                errors,
+                warnings,
+                estimatedCost: {
+                    storageCost: 0,
+                    networkFees: 0,
+                    totalCost: 0,
+                    currency: 'sats'
+                },
+                estimatedDuration: 0
+            };
+        }
+    }
+}

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

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

package/dist/migration/validation/StorageValidator.js

@@ -0,0 +1,65 @@
+/**
+ * StorageValidator - Validates storage adapter compatibility
+ */
+export class StorageValidator {
+    constructor(config) {
+        this.config = config;
+    }
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        try {
+            const storageAdapter = this.config.storageAdapter;
+            // Check if storage adapter is available
+            if (!storageAdapter) {
+                warnings.push({
+                    code: 'NO_STORAGE_ADAPTER',
+                    message: 'No storage adapter configured; using memory storage (not persistent)'
+                });
+            }
+            // Check large file support for partial migrations
+            if (options.partialMode) {
+                // Verify storage adapter supports chunked uploads
+                if (storageAdapter && typeof storageAdapter.putChunk !== 'function') {
+                    warnings.push({
+                        code: 'NO_CHUNKED_UPLOAD_SUPPORT',
+                        message: 'Storage adapter does not support chunked uploads; partial mode may be inefficient'
+                    });
+                }
+            }
+            // Estimate storage costs (minimal for webvh, zero for peer/btco)
+            const storageCost = options.targetLayer === 'webvh' ? 0.001 : 0;
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+                estimatedCost: {
+                    storageCost,
+                    networkFees: 0,
+                    totalCost: storageCost,
+                    currency: 'sats'
+                },
+                estimatedDuration: 50
+            };
+        }
+        catch (error) {
+            errors.push({
+                code: 'STORAGE_VALIDATION_ERROR',
+                message: 'Error validating storage compatibility',
+                details: { error: error instanceof Error ? error.message : String(error) }
+            });
+            return {
+                valid: false,
+                errors,
+                warnings,
+                estimatedCost: {
+                    storageCost: 0,
+                    networkFees: 0,
+                    totalCost: 0,
+                    currency: 'sats'
+                },
+                estimatedDuration: 0
+            };
+        }
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * ValidationPipeline - Orchestrates all validation checks before migration
+ */
+import { MigrationOptions, MigrationValidationResult, ValidationError } from '../types';
+import { OriginalsConfig } from '../../types';
+import { DIDManager } from '../../did/DIDManager';
+import { CredentialManager } from '../../vc/CredentialManager';
+import { BitcoinManager } from '../../bitcoin/BitcoinManager';
+export declare class ValidationPipeline {
+    private config;
+    private didManager;
+    private credentialManager;
+    private bitcoinManager?;
+    private validators;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager, bitcoinManager?: BitcoinManager | undefined);
+    private initializeValidators;
+    /**
+     * Run all validation checks for a migration
+     */
+    validate(options: MigrationOptions): Promise<MigrationValidationResult>;
+    /**
+     * Validate basic input parameters
+     */
+    private validateInput;
+    /**
+     * Quick validation check (basic only, no async operations)
+     */
+    validateQuick(options: MigrationOptions): ValidationError[];
+}

package/dist/migration/validation/ValidationPipeline.js

@@ -0,0 +1,180 @@
+/**
+ * ValidationPipeline - Orchestrates all validation checks before migration
+ */
+import { DIDCompatibilityValidator } from './DIDCompatibilityValidator';
+import { CredentialValidator } from './CredentialValidator';
+import { StorageValidator } from './StorageValidator';
+import { LifecycleValidator } from './LifecycleValidator';
+import { BitcoinValidator } from './BitcoinValidator';
+export class ValidationPipeline {
+    constructor(config, didManager, credentialManager, bitcoinManager) {
+        this.config = config;
+        this.didManager = didManager;
+        this.credentialManager = credentialManager;
+        this.bitcoinManager = bitcoinManager;
+        this.validators = new Map();
+        this.initializeValidators();
+    }
+    initializeValidators() {
+        this.validators.set('did', new DIDCompatibilityValidator(this.config, this.didManager));
+        this.validators.set('credential', new CredentialValidator(this.config, this.credentialManager));
+        this.validators.set('storage', new StorageValidator(this.config));
+        this.validators.set('lifecycle', new LifecycleValidator(this.config));
+        if (this.bitcoinManager) {
+            this.validators.set('bitcoin', new BitcoinValidator(this.config, this.bitcoinManager));
+        }
+    }
+    /**
+     * Run all validation checks for a migration
+     */
+    async validate(options) {
+        const errors = [];
+        const warnings = [];
+        let estimatedCost = {
+            storageCost: 0,
+            networkFees: 0,
+            totalCost: 0,
+            currency: 'sats'
+        };
+        let estimatedDuration = 0;
+        try {
+            // Basic input validation
+            const inputErrors = this.validateInput(options);
+            if (inputErrors.length > 0) {
+                return {
+                    valid: false,
+                    errors: inputErrors,
+                    warnings: [],
+                    estimatedCost,
+                    estimatedDuration: 0
+                };
+            }
+            // Run DID compatibility validation
+            const didResult = await this.validators.get('did').validate(options);
+            errors.push(...didResult.errors);
+            warnings.push(...didResult.warnings);
+            estimatedDuration = Math.max(estimatedDuration, didResult.estimatedDuration);
+            // Run credential validation if enabled
+            if (options.credentialIssuance !== false) {
+                const credResult = await this.validators.get('credential').validate(options);
+                errors.push(...credResult.errors);
+                warnings.push(...credResult.warnings);
+            }
+            // Run storage validation
+            const storageResult = await this.validators.get('storage').validate(options);
+            errors.push(...storageResult.errors);
+            warnings.push(...storageResult.warnings);
+            estimatedCost.storageCost = storageResult.estimatedCost.storageCost;
+            // Run lifecycle validation
+            const lifecycleResult = await this.validators.get('lifecycle').validate(options);
+            errors.push(...lifecycleResult.errors);
+            warnings.push(...lifecycleResult.warnings);
+            // Run Bitcoin validation for btco migrations
+            if (options.targetLayer === 'btco') {
+                const bitcoinValidator = this.validators.get('bitcoin');
+                if (!bitcoinValidator) {
+                    errors.push({
+                        code: 'BITCOIN_VALIDATOR_MISSING',
+                        message: 'Bitcoin validator required for btco migrations but not configured',
+                        details: { targetLayer: options.targetLayer }
+                    });
+                }
+                else {
+                    const bitcoinResult = await bitcoinValidator.validate(options);
+                    errors.push(...bitcoinResult.errors);
+                    warnings.push(...bitcoinResult.warnings);
+                    estimatedCost.networkFees = bitcoinResult.estimatedCost.networkFees;
+                    estimatedDuration = Math.max(estimatedDuration, bitcoinResult.estimatedDuration);
+                }
+            }
+            // Calculate total cost
+            estimatedCost.totalCost = estimatedCost.storageCost + estimatedCost.networkFees;
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+                estimatedCost,
+                estimatedDuration
+            };
+        }
+        catch (error) {
+            errors.push({
+                code: 'VALIDATION_PIPELINE_ERROR',
+                message: 'Unexpected error during validation',
+                details: { error: error instanceof Error ? error.message : String(error) }
+            });
+            return {
+                valid: false,
+                errors,
+                warnings,
+                estimatedCost,
+                estimatedDuration
+            };
+        }
+    }
+    /**
+     * Validate basic input parameters
+     */
+    validateInput(options) {
+        const errors = [];
+        // Validate source DID
+        if (!options.sourceDid || typeof options.sourceDid !== 'string') {
+            errors.push({
+                code: 'INVALID_SOURCE_DID',
+                message: 'Source DID is required and must be a string',
+                field: 'sourceDid'
+            });
+        }
+        // Validate target layer
+        if (!options.targetLayer) {
+            errors.push({
+                code: 'INVALID_TARGET_LAYER',
+                message: 'Target layer is required',
+                field: 'targetLayer'
+            });
+        }
+        else if (!['peer', 'webvh', 'btco'].includes(options.targetLayer)) {
+            errors.push({
+                code: 'INVALID_TARGET_LAYER',
+                message: 'Target layer must be one of: peer, webvh, btco',
+                field: 'targetLayer',
+                details: { received: options.targetLayer }
+            });
+        }
+        // Validate partial mode options
+        if (options.partialMode) {
+            if (typeof options.partialMode.chunkSize !== 'number' || options.partialMode.chunkSize <= 0) {
+                errors.push({
+                    code: 'INVALID_CHUNK_SIZE',
+                    message: 'Chunk size must be a positive number',
+                    field: 'partialMode.chunkSize'
+                });
+            }
+        }
+        // Validate webvh-specific options
+        if (options.targetLayer === 'webvh' && !options.domain) {
+            errors.push({
+                code: 'DOMAIN_REQUIRED',
+                message: 'Domain is required for webvh migrations',
+                field: 'domain'
+            });
+        }
+        // Validate btco-specific options
+        if (options.targetLayer === 'btco') {
+            if (options.feeRate !== undefined && (typeof options.feeRate !== 'number' || options.feeRate <= 0)) {
+                errors.push({
+                    code: 'INVALID_FEE_RATE',
+                    message: 'Fee rate must be a positive number',
+                    field: 'feeRate'
+                });
+            }
+        }
+        return errors;
+    }
+    /**
+     * Quick validation check (basic only, no async operations)
+     */
+    validateQuick(options) {
+        return this.validateInput(options);
+    }
+}

package/dist/resources/ResourceManager.d.ts

@@ -0,0 +1,231 @@
+/**
+ * ResourceManager - CRUD operations for immutable, versioned resources.
+ *
+ * Resources in the Originals SDK are content-addressed and immutable. Each "update"
+ * creates a new version with a new content hash, linked to the previous version
+ * via previousVersionHash. This creates a verifiable provenance chain.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ResourceManager();
+ *
+ * // Create a new resource
+ * const resource = manager.createResource('Hello, World!', {
+ *   type: 'text',
+ *   contentType: 'text/plain'
+ * });
+ *
+ * // Update creates a new version
+ * const updatedResource = manager.updateResource(resource, 'Hello, Updated World!', {
+ *   changes: 'Updated greeting'
+ * });
+ *
+ * // Get version history
+ * const history = manager.getResourceHistory(resource.id);
+ * ```
+ */
+import type { Resource, ResourceOptions, ResourceUpdateOptions, ResourceVersionHistory, ResourceManagerConfig, ResourceValidationResult, ResourceType } from './types.js';
+/**
+ * ResourceManager provides CRUD operations for immutable, content-addressed resources
+ * with versioning support and validation.
+ */
+export declare class ResourceManager {
+    private resources;
+    private config;
+    /**
+     * Create a new ResourceManager instance.
+     *
+     * @param config - Optional configuration for the manager
+     */
+    constructor(config?: ResourceManagerConfig);
+    /**
+     * Create a new resource from content.
+     *
+     * @param content - The resource content (string for text, Buffer for binary)
+     * @param options - Creation options including type and contentType
+     * @returns The created Resource
+     * @throws Error if content or options are invalid
+     *
+     * @example
+     * ```typescript
+     * // Create a text resource
+     * const textResource = manager.createResource('# README\nHello', {
+     *   type: 'text',
+     *   contentType: 'text/markdown'
+     * });
+     *
+     * // Create a binary resource (image)
+     * const imageBuffer = fs.readFileSync('image.png');
+     * const imageResource = manager.createResource(imageBuffer, {
+     *   type: 'image',
+     *   contentType: 'image/png'
+     * });
+     * ```
+     */
+    createResource(content: Buffer | string, options: ResourceOptions): Resource;
+    /**
+     * Update a resource by creating a new version.
+     * The original resource remains unchanged (immutable versioning).
+     *
+     * @param resource - The resource to update (or its ID)
+     * @param newContent - The new content
+     * @param options - Optional update options including change description
+     * @returns The new version of the resource
+     * @throws Error if resource not found or content unchanged
+     *
+     * @example
+     * ```typescript
+     * const v2 = manager.updateResource(originalResource, 'Updated content', {
+     *   changes: 'Fixed typo in documentation'
+     * });
+     *
+     * console.log(v2.version); // 2
+     * console.log(v2.previousVersionHash); // hash of v1
+     * ```
+     */
+    updateResource(resource: Resource | string, newContent: Buffer | string, options?: ResourceUpdateOptions): Resource;
+    /**
+     * Get the complete version history for a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns Array of all versions (oldest to newest), or empty array if not found
+     *
+     * @example
+     * ```typescript
+     * const history = manager.getResourceHistory('my-resource-id');
+     * console.log(`Found ${history.length} versions`);
+     * history.forEach((v, i) => console.log(`v${i + 1}: ${v.hash}`));
+     * ```
+     */
+    getResourceHistory(resourceId: string): Resource[];
+    /**
+     * Get detailed version history with metadata.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns ResourceVersionHistory object or null if not found
+     */
+    getResourceVersionHistory(resourceId: string): ResourceVersionHistory | null;
+    /**
+     * Get a specific version of a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @param version - Version number (1-indexed)
+     * @returns The resource at that version, or null if not found
+     */
+    getResourceVersion(resourceId: string, version: number): Resource | null;
+    /**
+     * Get the current (latest) version of a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns The current version, or null if not found
+     */
+    getCurrentVersion(resourceId: string): Resource | null;
+    /**
+     * Get a resource by its content hash.
+     *
+     * @param hash - The content hash to search for
+     * @returns The resource with that hash, or null if not found
+     */
+    getResourceByHash(hash: string): Resource | null;
+    /**
+     * Validate a resource object.
+     *
+     * @param resource - The resource to validate
+     * @returns ValidationResult with valid flag and any errors/warnings
+     *
+     * @example
+     * ```typescript
+     * const result = manager.validateResource(resource);
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * if (result.warnings.length > 0) {
+     *   console.warn('Warnings:', result.warnings);
+     * }
+     * ```
+     */
+    validateResource(resource: Resource): ResourceValidationResult;
+    /**
+     * Verify the integrity of a resource's version chain.
+     * Ensures that previousVersionHash references form a valid chain.
+     *
+     * @param resourceId - The logical resource ID to verify
+     * @returns ResourceValidationResult indicating chain integrity
+     */
+    verifyVersionChain(resourceId: string): ResourceValidationResult;
+    /**
+     * Hash content using SHA-256.
+     *
+     * @param content - Content to hash (string or Buffer)
+     * @returns Hex-encoded SHA-256 hash
+     *
+     * @example
+     * ```typescript
+     * const hash = manager.hashContent('Hello, World!');
+     * console.log(hash); // 64-character hex string
+     * ```
+     */
+    hashContent(content: Buffer | string): string;
+    /**
+     * Delete a resource and all its versions.
+     *
+     * @param resourceId - The resource ID to delete
+     * @returns true if deleted, false if not found
+     */
+    deleteResource(resourceId: string): boolean;
+    /**
+     * List all resource IDs managed by this instance.
+     *
+     * @returns Array of resource IDs
+     */
+    listResourceIds(): string[];
+    /**
+     * Get the total number of resources (unique IDs) managed.
+     *
+     * @returns Number of resources
+     */
+    getResourceCount(): number;
+    /**
+     * Get the total number of versions across all resources.
+     *
+     * @returns Total version count
+     */
+    getTotalVersionCount(): number;
+    /**
+     * Import a resource from an existing AssetResource.
+     * Useful for loading resources from storage or external sources.
+     *
+     * @param assetResource - The AssetResource to import
+     * @returns The imported Resource
+     */
+    importResource(assetResource: Resource): Resource;
+    /**
+     * Export all resources as an array (for serialization).
+     *
+     * @returns Array of all resources (all versions)
+     */
+    exportResources(): Resource[];
+    /**
+     * Clear all resources from this manager.
+     */
+    clear(): void;
+    /**
+     * Infer resource type from MIME type.
+     *
+     * @param contentType - The MIME content type
+     * @returns Inferred ResourceType
+     */
+    static inferResourceType(contentType: string): ResourceType;
+    /**
+     * Check if a string is a valid MIME type format.
+     */
+    private isValidMimeType;
+    /**
+     * Convert content to Buffer.
+     */
+    private toBuffer;
+    /**
+     * Check if content is binary (Buffer) rather than text.
+     */
+    private isBinaryContent;
+}