@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/cjs/config-validation.js

@@ -1,522 +1 @@
-"use strict";
-/**
- * @module config-validation
- * Configuration validation for xBind agent initialization.
- *
- * Provides schema validation, type checking, and clear error messages
- * for AgentOptions and AgentCreateOptions to enhance configuration safety
- * and improve developer experience.
- *
- * @example
- * ```typescript
- * import { validateAgentOptions, validateAgentCreateOptions } from '@private.me/xbind';
- *
- * // Validate simplified options
- * const simpleResult = validateAgentOptions({
- *   identity: 'persistent',
- *   registry: 'https://private.me/registry'
- * });
- *
- * if (!simpleResult.ok) {
- *   console.error(simpleResult.error); // Clear, actionable error message
- * }
- *
- * // Validate full options
- * const fullResult = validateAgentCreateOptions({
- *   name: 'my-agent',
- *   registry: myRegistryInstance,
- *   transport: myTransportAdapter
- * });
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_CREATE_OPTIONS_DEFAULTS = exports.AGENT_OPTIONS_DEFAULTS = exports.ConfigValidationError = void 0;
-exports.validateAgentOptions = validateAgentOptions;
-exports.validateAgentCreateOptions = validateAgentCreateOptions;
-exports.getValidationDetails = getValidationDetails;
-exports.assertValidConfig = assertValidConfig;
-exports.assertValidCreateConfig = assertValidCreateConfig;
-const shared_1 = require("../_deps/shared/index.js");
-const errors_js_1 = require("./errors.js");
-/**
- * Configuration validation error with detailed context.
- */
-class ConfigValidationError extends errors_js_1.XBindError {
-    /** Field that failed validation */
-    field;
-    /** Expected value/type */
-    expected;
-    /** Actual value received */
-    actual;
-    /** Suggested fix */
-    fix;
-    constructor(field, expected, actual, fix) {
-        const message = `Configuration validation failed for '${field}': Expected ${expected}, got ${typeof actual === 'object' && actual !== null ? JSON.stringify(actual) : String(actual)}. ${fix}`;
-        super('CONFIG_INVALID', message, 'https://private.me/docs/xbind/api/configuration');
-        this.name = 'ConfigValidationError';
-        this.field = field;
-        this.expected = expected;
-        this.actual = actual;
-        this.fix = fix;
-    }
-}
-exports.ConfigValidationError = ConfigValidationError;
-/**
- * Default values for AgentOptions.
- */
-exports.AGENT_OPTIONS_DEFAULTS = {
-    identity: 'persistent',
-    identityTTL: 3600000, // 1 hour
-    postQuantumSig: false,
-};
-/**
- * Default values for AgentCreateOptions.
- */
-exports.AGENT_CREATE_OPTIONS_DEFAULTS = {
-    timestampWindowMs: 30000, // 30 seconds
-    postQuantumSig: false,
-    xchange: false,
-    scopes: [],
-};
-/**
- * Validate AgentOptions configuration.
- *
- * Checks all fields for correct types, valid values, and logical consistency.
- * Provides clear, actionable error messages for any validation failures.
- *
- * @param options - AgentOptions to validate
- * @returns Result with validation errors or success
- *
- * @example
- * ```typescript
- * const result = validateAgentOptions({
- *   identity: 'persistent',
- *   registry: 'https://private.me/registry',
- *   identityTTL: 7200000 // 2 hours
- * });
- *
- * if (result.ok) {
- *   console.log('Configuration valid!');
- * } else {
- *   console.error(result.error);
- * }
- * ```
- */
-function validateAgentOptions(options) {
-    if (!options || typeof options !== 'object') {
-        return (0, shared_1.err)(new ConfigValidationError('options', 'object', options, 'Provide a configuration object with at least one option.'));
-    }
-    const opts = options;
-    const errors = [];
-    const warnings = [];
-    // Validate identity mode
-    if (opts.identity !== undefined) {
-        if (typeof opts.identity !== 'string') {
-            errors.push(new ConfigValidationError('identity', "'persistent' | 'ephemeral'", opts.identity, "Use 'persistent' for long-lived DIDs or 'ephemeral' for short-lived DIDs."));
-        }
-        else if (opts.identity !== 'persistent' && opts.identity !== 'ephemeral') {
-            errors.push(new ConfigValidationError('identity', "'persistent' | 'ephemeral'", opts.identity, `Invalid identity mode. Use 'persistent' or 'ephemeral'.`));
-        }
-    }
-    // Validate identityTTL
-    if (opts.identityTTL !== undefined) {
-        if (typeof opts.identityTTL !== 'number') {
-            errors.push(new ConfigValidationError('identityTTL', 'number (milliseconds)', opts.identityTTL, 'Provide TTL as a number in milliseconds (e.g., 3600000 for 1 hour).'));
-        }
-        else if (opts.identityTTL <= 0) {
-            errors.push(new ConfigValidationError('identityTTL', 'positive number', opts.identityTTL, 'TTL must be greater than 0. Use at least 60000 (1 minute).'));
-        }
-        else if (opts.identityTTL < 60000) {
-            warnings.push(`identityTTL is very short (${opts.identityTTL}ms). Consider using at least 60000ms (1 minute) to avoid frequent re-registrations.`);
-        }
-        else if (opts.identityTTL > 86400000) {
-            warnings.push(`identityTTL is very long (${opts.identityTTL}ms). Consider using 'persistent' identity mode instead for long-lived agents.`);
-        }
-        // Warn if TTL specified but identity is not ephemeral
-        if (opts.identity === 'persistent') {
-            warnings.push("identityTTL is ignored for 'persistent' identity mode. Remove this option or switch to 'ephemeral' mode.");
-        }
-    }
-    // Validate registry
-    if (opts.registry !== undefined) {
-        const isString = typeof opts.registry === 'string';
-        const isObject = typeof opts.registry === 'object' && opts.registry !== null;
-        if (!isString && !isObject) {
-            errors.push(new ConfigValidationError('registry', 'TrustRegistry instance or URL string', opts.registry, 'Provide either a registry URL (e.g., "https://private.me/registry") or a TrustRegistry instance.'));
-        }
-        else if (isString) {
-            const url = opts.registry;
-            try {
-                const parsed = new URL(url);
-                if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-                    errors.push(new ConfigValidationError('registry', 'HTTP(S) URL', url, 'Registry URL must use HTTP or HTTPS protocol.'));
-                }
-            }
-            catch {
-                errors.push(new ConfigValidationError('registry', 'valid URL', url, 'Provide a valid URL (e.g., "https://private.me/registry").'));
-            }
-        }
-        else if (isObject) {
-            // Validate TrustRegistry interface
-            const registry = opts.registry;
-            const requiredMethods = ['register', 'resolve'];
-            const missingMethods = requiredMethods.filter((method) => !(method in registry) || typeof registry[method] !== 'function');
-            if (missingMethods.length > 0) {
-                errors.push(new ConfigValidationError('registry', 'TrustRegistry instance', 'object missing required methods', `TrustRegistry must implement ${missingMethods.join(', ')} method(s). Use HttpTrustRegistry or MemoryTrustRegistry.`));
-            }
-        }
-    }
-    // Validate transport
-    if (opts.transport !== undefined) {
-        const isArray = Array.isArray(opts.transport);
-        const isSingleTransport = typeof opts.transport === 'object' && opts.transport !== null && !isArray;
-        if (!isSingleTransport && !isArray) {
-            errors.push(new ConfigValidationError('transport', 'XailTransportAdapter or XailTransportAdapter[]', opts.transport, 'Provide a single transport adapter or an array of adapters for split-channel security.'));
-        }
-        else if (isArray) {
-            const transports = opts.transport;
-            if (transports.length === 0) {
-                errors.push(new ConfigValidationError('transport', 'non-empty array', transports, 'Provide at least one transport adapter.'));
-            }
-            // Validate each transport in array
-            transports.forEach((transport, index) => {
-                if (typeof transport !== 'object' || transport === null) {
-                    errors.push(new ConfigValidationError(`transport[${index}]`, 'XailTransportAdapter', transport, 'Each transport must be a XailTransportAdapter instance.'));
-                }
-                else {
-                    const t = transport;
-                    if (!('send' in t) || typeof t.send !== 'function') {
-                        errors.push(new ConfigValidationError(`transport[${index}]`, 'XailTransportAdapter with send() method', 'object missing send() method', 'Transport must implement send() method. Use HttpsTransportAdapter or custom adapter.'));
-                    }
-                }
-            });
-        }
-        else {
-            // Validate single transport
-            const transport = opts.transport;
-            if (!('send' in transport) || typeof transport.send !== 'function') {
-                errors.push(new ConfigValidationError('transport', 'XailTransportAdapter with send() method', 'object missing send() method', 'Transport must implement send() method. Use HttpsTransportAdapter or custom adapter.'));
-            }
-        }
-    }
-    // Validate securityPolicy
-    if (opts.securityPolicy !== undefined) {
-        if (typeof opts.securityPolicy !== 'object' || opts.securityPolicy === null) {
-            errors.push(new ConfigValidationError('securityPolicy', 'SecurityPolicy instance', opts.securityPolicy, 'Provide a SecurityPolicy instance (e.g., DefaultSecurityPolicy or custom policy).'));
-        }
-        else {
-            const policy = opts.securityPolicy;
-            if (!('classify' in policy) || typeof policy.classify !== 'function') {
-                errors.push(new ConfigValidationError('securityPolicy', 'SecurityPolicy with classify() method', 'object missing classify() method', 'SecurityPolicy must implement classify() method. Use DefaultSecurityPolicy.'));
-            }
-        }
-    }
-    // Validate postQuantumSig
-    if (opts.postQuantumSig !== undefined) {
-        if (typeof opts.postQuantumSig !== 'boolean') {
-            errors.push(new ConfigValidationError('postQuantumSig', 'boolean', opts.postQuantumSig, 'Use true to enable ML-DSA-65 post-quantum signatures, or false to disable.'));
-        }
-    }
-    // Validate backupConfig
-    if (opts.backupConfig !== undefined) {
-        if (typeof opts.backupConfig !== 'object' || opts.backupConfig === null) {
-            errors.push(new ConfigValidationError('backupConfig', 'BackupConfig object', opts.backupConfig, 'Provide a BackupConfig object with threshold (k) and totalShares (n) properties.'));
-        }
-        else {
-            const config = opts.backupConfig;
-            if (typeof config.threshold !== 'number') {
-                errors.push(new ConfigValidationError('backupConfig.threshold', 'number', config.threshold, 'Threshold (k) must be a number representing shares needed for reconstruction.'));
-            }
-            else if (config.threshold < 2) {
-                errors.push(new ConfigValidationError('backupConfig.threshold', 'number >= 2', config.threshold, 'Threshold must be at least 2 for meaningful splitting.'));
-            }
-            if (typeof config.totalShares !== 'number') {
-                errors.push(new ConfigValidationError('backupConfig.totalShares', 'number', config.totalShares, 'totalShares (n) must be a number representing total shares to create.'));
-            }
-            else if (config.totalShares < 2) {
-                errors.push(new ConfigValidationError('backupConfig.totalShares', 'number >= 2', config.totalShares, 'totalShares must be at least 2 for splitting.'));
-            }
-            // Validate threshold <= totalShares
-            if (typeof config.threshold === 'number' &&
-                typeof config.totalShares === 'number' &&
-                config.threshold > config.totalShares) {
-                errors.push(new ConfigValidationError('backupConfig', 'threshold <= totalShares', `threshold=${config.threshold}, totalShares=${config.totalShares}`, `Threshold (${config.threshold}) cannot exceed totalShares (${config.totalShares}). Use threshold <= totalShares.`));
-            }
-        }
-    }
-    // Return first error or success
-    if (errors.length > 0) {
-        return (0, shared_1.err)(errors[0]);
-    }
-    return (0, shared_1.ok)(opts);
-}
-/**
- * Validate AgentCreateOptions configuration.
- *
- * Checks all fields for correct types, valid values, and logical consistency.
- * Provides clear, actionable error messages for any validation failures.
- *
- * @param options - AgentCreateOptions to validate
- * @returns Result with validation errors or success
- *
- * @example
- * ```typescript
- * const result = validateAgentCreateOptions({
- *   name: 'my-agent',
- *   registry: new MemoryTrustRegistry(),
- *   transport: new HttpsTransportAdapter(),
- *   timestampWindowMs: 60000 // 1 minute
- * });
- *
- * if (result.ok) {
- *   console.log('Configuration valid!');
- * } else {
- *   console.error(result.error);
- * }
- * ```
- */
-function validateAgentCreateOptions(options) {
-    if (!options || typeof options !== 'object') {
-        return (0, shared_1.err)(new ConfigValidationError('options', 'object', options, 'Provide a configuration object with required fields: name, registry, transport.'));
-    }
-    const opts = options;
-    const errors = [];
-    // Validate required fields
-    if (opts.name === undefined) {
-        errors.push(new ConfigValidationError('name', 'string (required)', undefined, 'Provide a display name for the agent (e.g., "my-agent").'));
-    }
-    else if (typeof opts.name !== 'string') {
-        errors.push(new ConfigValidationError('name', 'string', opts.name, 'Agent name must be a string.'));
-    }
-    else if (opts.name.trim().length === 0) {
-        errors.push(new ConfigValidationError('name', 'non-empty string', opts.name, 'Agent name cannot be empty or whitespace only.'));
-    }
-    else if (opts.name.length > 255) {
-        errors.push(new ConfigValidationError('name', 'string with length <= 255', opts.name, `Agent name is too long (${opts.name.length} characters). Use 255 characters or less.`));
-    }
-    // Validate required registry
-    if (opts.registry === undefined) {
-        errors.push(new ConfigValidationError('registry', 'TrustRegistry (required)', undefined, 'Provide a TrustRegistry instance (e.g., new MemoryTrustRegistry() or new HttpTrustRegistry()).'));
-    }
-    else if (typeof opts.registry !== 'object' || opts.registry === null) {
-        errors.push(new ConfigValidationError('registry', 'TrustRegistry instance', opts.registry, 'Registry must be a TrustRegistry instance, not a string or primitive value.'));
-    }
-    else {
-        // Validate TrustRegistry interface
-        const registry = opts.registry;
-        const requiredMethods = ['register', 'resolve'];
-        const missingMethods = requiredMethods.filter((method) => !(method in registry) || typeof registry[method] !== 'function');
-        if (missingMethods.length > 0) {
-            errors.push(new ConfigValidationError('registry', 'TrustRegistry instance', 'object missing required methods', `TrustRegistry must implement: ${missingMethods.join(', ')}. Use HttpTrustRegistry or MemoryTrustRegistry.`));
-        }
-    }
-    // Validate required transport
-    if (opts.transport === undefined) {
-        errors.push(new ConfigValidationError('transport', 'XailTransportAdapter or XailTransportAdapter[] (required)', undefined, 'Provide a transport adapter (e.g., new HttpsTransportAdapter()) or array of adapters for split-channel.'));
-    }
-    else {
-        const isArray = Array.isArray(opts.transport);
-        const isSingleTransport = typeof opts.transport === 'object' && opts.transport !== null && !isArray;
-        if (!isSingleTransport && !isArray) {
-            errors.push(new ConfigValidationError('transport', 'XailTransportAdapter or XailTransportAdapter[]', opts.transport, 'Provide a single transport adapter or an array of adapters.'));
-        }
-        else if (isArray) {
-            const transports = opts.transport;
-            if (transports.length === 0) {
-                errors.push(new ConfigValidationError('transport', 'non-empty array', transports, 'Provide at least one transport adapter.'));
-            }
-            // Validate each transport in array
-            transports.forEach((transport, index) => {
-                if (typeof transport !== 'object' || transport === null) {
-                    errors.push(new ConfigValidationError(`transport[${index}]`, 'XailTransportAdapter', transport, 'Each transport must be a XailTransportAdapter instance.'));
-                }
-                else {
-                    const t = transport;
-                    if (!('send' in t) || typeof t.send !== 'function') {
-                        errors.push(new ConfigValidationError(`transport[${index}]`, 'XailTransportAdapter with send() method', 'object missing send() method', 'Transport must implement send() method. Use HttpsTransportAdapter or custom adapter.'));
-                    }
-                }
-            });
-        }
-        else {
-            // Validate single transport
-            const transport = opts.transport;
-            if (!('send' in transport) || typeof transport.send !== 'function') {
-                errors.push(new ConfigValidationError('transport', 'XailTransportAdapter with send() method', 'object missing send() method', 'Transport must implement send() method. Use HttpsTransportAdapter or custom adapter.'));
-            }
-        }
-    }
-    // Validate optional nonceStore
-    if (opts.nonceStore !== undefined) {
-        if (typeof opts.nonceStore !== 'object' || opts.nonceStore === null) {
-            errors.push(new ConfigValidationError('nonceStore', 'NonceStore instance', opts.nonceStore, 'Provide a NonceStore instance (e.g., new MemoryNonceStore()).'));
-        }
-        else {
-            const store = opts.nonceStore;
-            const requiredMethods = ['check', 'cleanup'];
-            const missingMethods = requiredMethods.filter((method) => !(method in store) || typeof store[method] !== 'function');
-            if (missingMethods.length > 0) {
-                errors.push(new ConfigValidationError('nonceStore', 'NonceStore instance', 'object missing required methods', `NonceStore must implement: ${missingMethods.join(', ')}. Use MemoryNonceStore.`));
-            }
-        }
-    }
-    // Validate scopes
-    if (opts.scopes !== undefined) {
-        if (!Array.isArray(opts.scopes)) {
-            errors.push(new ConfigValidationError('scopes', 'string[]', opts.scopes, 'Provide an array of scope strings (e.g., ["read", "write"]).'));
-        }
-        else {
-            const scopes = opts.scopes;
-            scopes.forEach((scope, index) => {
-                if (typeof scope !== 'string') {
-                    errors.push(new ConfigValidationError(`scopes[${index}]`, 'string', scope, 'Each scope must be a string.'));
-                }
-                else if (scope.trim().length === 0) {
-                    errors.push(new ConfigValidationError(`scopes[${index}]`, 'non-empty string', scope, 'Scope cannot be empty or whitespace only.'));
-                }
-            });
-        }
-    }
-    // Validate timestampWindowMs
-    if (opts.timestampWindowMs !== undefined) {
-        if (typeof opts.timestampWindowMs !== 'number') {
-            errors.push(new ConfigValidationError('timestampWindowMs', 'number (milliseconds)', opts.timestampWindowMs, 'Provide timestamp window as a number in milliseconds (e.g., 30000 for 30 seconds).'));
-        }
-        else if (opts.timestampWindowMs <= 0) {
-            errors.push(new ConfigValidationError('timestampWindowMs', 'positive number', opts.timestampWindowMs, 'Timestamp window must be greater than 0. Use at least 1000 (1 second).'));
-        }
-        else if (opts.timestampWindowMs < 5000) {
-            errors.push(new ConfigValidationError('timestampWindowMs', 'number >= 5000', opts.timestampWindowMs, 'Timestamp window is very short. Use at least 5000ms (5 seconds) to account for clock skew.'));
-        }
-        else if (opts.timestampWindowMs > 300000) {
-            errors.push(new ConfigValidationError('timestampWindowMs', 'number <= 300000', opts.timestampWindowMs, 'Timestamp window is very long. Consider using 300000ms (5 minutes) or less for security.'));
-        }
-    }
-    // Validate postQuantumSig
-    if (opts.postQuantumSig !== undefined) {
-        if (typeof opts.postQuantumSig !== 'boolean') {
-            errors.push(new ConfigValidationError('postQuantumSig', 'boolean', opts.postQuantumSig, 'Use true to enable ML-DSA-65 post-quantum signatures, or false to disable.'));
-        }
-    }
-    // Validate xchange
-    if (opts.xchange !== undefined) {
-        if (typeof opts.xchange !== 'boolean') {
-            errors.push(new ConfigValidationError('xchange', 'boolean', opts.xchange, 'Use true to advertise Xchange mode support, or false to disable.'));
-        }
-    }
-    // Validate securityPolicy
-    if (opts.securityPolicy !== undefined) {
-        if (typeof opts.securityPolicy !== 'object' || opts.securityPolicy === null) {
-            errors.push(new ConfigValidationError('securityPolicy', 'SecurityPolicy instance', opts.securityPolicy, 'Provide a SecurityPolicy instance (e.g., DefaultSecurityPolicy or custom policy).'));
-        }
-        else {
-            const policy = opts.securityPolicy;
-            if (!('classify' in policy) || typeof policy.classify !== 'function') {
-                errors.push(new ConfigValidationError('securityPolicy', 'SecurityPolicy with classify() method', 'object missing classify() method', 'SecurityPolicy must implement classify() method. Use DefaultSecurityPolicy.'));
-            }
-        }
-    }
-    // Return first error or success
-    if (errors.length > 0) {
-        return (0, shared_1.err)(errors[0]);
-    }
-    return (0, shared_1.ok)(opts);
-}
-/**
- * Get detailed validation result with all errors and warnings.
- *
- * Unlike the Result-based validators, this function returns all validation
- * issues at once for comprehensive feedback.
- *
- * @param options - AgentOptions to validate
- * @returns ValidationResult with all errors and warnings
- *
- * @example
- * ```typescript
- * const result = getValidationDetails({
- *   identity: 'invalid',
- *   identityTTL: -100,
- *   postQuantumSig: 'yes' // type error
- * });
- *
- * console.log(`Valid: ${result.valid}`);
- * console.log(`Errors: ${result.errors.length}`);
- * console.log(`Warnings: ${result.warnings.length}`);
- *
- * result.errors.forEach(err => {
- *   console.error(`- ${err.field}: ${err.message}`);
- * });
- * ```
- */
-function getValidationDetails(options) {
-    const errors = [];
-    const warnings = [];
-    // Run validation and collect all errors
-    const result = validateAgentOptions(options);
-    if (!result.ok) {
-        errors.push(result.error);
-    }
-    // Check for warning conditions (even if validation passed)
-    if (options && typeof options === 'object') {
-        const opts = options;
-        // Check for warning conditions
-        if (typeof opts.identityTTL === 'number') {
-            if (opts.identityTTL < 60000 && opts.identityTTL > 0) {
-                warnings.push(`identityTTL is very short (${opts.identityTTL}ms). Consider using at least 60000ms (1 minute).`);
-            }
-            else if (opts.identityTTL > 86400000) {
-                warnings.push(`identityTTL is very long (${opts.identityTTL}ms). Consider using 'persistent' identity mode instead.`);
-            }
-            if (opts.identity === 'persistent') {
-                warnings.push("identityTTL is ignored for 'persistent' identity mode.");
-            }
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        errors,
-        warnings,
-    };
-}
-/**
- * Validate configuration and throw on error.
- *
- * Convenience function that validates configuration and throws
- * ConfigValidationError if validation fails.
- *
- * @param options - AgentOptions or AgentCreateOptions to validate
- * @throws ConfigValidationError if validation fails
- *
- * @example
- * ```typescript
- * try {
- *   assertValidConfig({
- *     identity: 'persistent',
- *     registry: 'https://private.me/registry'
- *   });
- *   // Configuration is valid, continue
- * } catch (err) {
- *   if (err instanceof ConfigValidationError) {
- *     console.error(`Invalid ${err.field}: ${err.fix}`);
- *   }
- * }
- * ```
- */
-function assertValidConfig(options) {
-    const result = validateAgentOptions(options);
-    if (!result.ok) {
-        throw result.error;
-    }
-}
-/**
- * Validate configuration and throw on error (full options).
- *
- * @param options - AgentCreateOptions to validate
- * @throws ConfigValidationError if validation fails
- */
-function assertValidCreateConfig(options) {
-    const result = validateAgentCreateOptions(options);
-    if (!result.ok) {
-        throw result.error;
-    }
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.AGENT_CREATE_OPTIONS_DEFAULTS=exports.AGENT_OPTIONS_DEFAULTS=exports.ConfigValidationError=void 0,exports.validateAgentOptions=validateAgentOptions,exports.validateAgentCreateOptions=validateAgentCreateOptions,exports.getValidationDetails=getValidationDetails,exports.assertValidConfig=assertValidConfig,exports.assertValidCreateConfig=assertValidCreateConfig;const shared_1=require("../_deps/shared/index.js"),errors_js_1=require("./errors.js");class ConfigValidationError extends errors_js_1.XBindError{field;expected;actual;fix;constructor(t,e,r,i){super("CONFIG_INVALID",`Configuration validation failed for '${t}': Expected ${e}, got ${"object"==typeof r&&null!==r?JSON.stringify(r):String(r)}. ${i}`,"https://private.me/docs/xbind/api/configuration"),this.name="ConfigValidationError",this.field=t,this.expected=e,this.actual=r,this.fix=i}}function validateAgentOptions(t){if(!t||"object"!=typeof t)return(0,shared_1.err)(new ConfigValidationError("options","object",t,"Provide a configuration object with at least one option."));const e=t,r=[],i=[];if(void 0!==e.identity&&("string"!=typeof e.identity?r.push(new ConfigValidationError("identity","'persistent' | 'ephemeral'",e.identity,"Use 'persistent' for long-lived DIDs or 'ephemeral' for short-lived DIDs.")):"persistent"!==e.identity&&"ephemeral"!==e.identity&&r.push(new ConfigValidationError("identity","'persistent' | 'ephemeral'",e.identity,"Invalid identity mode. Use 'persistent' or 'ephemeral'."))),void 0!==e.identityTTL&&("number"!=typeof e.identityTTL?r.push(new ConfigValidationError("identityTTL","number (milliseconds)",e.identityTTL,"Provide TTL as a number in milliseconds (e.g., 3600000 for 1 hour).")):e.identityTTL<=0?r.push(new ConfigValidationError("identityTTL","positive number",e.identityTTL,"TTL must be greater than 0. Use at least 60000 (1 minute).")):e.identityTTL<6e4?i.push(`identityTTL is very short (${e.identityTTL}ms). Consider using at least 60000ms (1 minute) to avoid frequent re-registrations.`):e.identityTTL>864e5&&i.push(`identityTTL is very long (${e.identityTTL}ms). Consider using 'persistent' identity mode instead for long-lived agents.`),"persistent"===e.identity&&i.push("identityTTL is ignored for 'persistent' identity mode. Remove this option or switch to 'ephemeral' mode.")),void 0!==e.registry){const t="string"==typeof e.registry,i="object"==typeof e.registry&&null!==e.registry;if(t||i){if(t){const t=e.registry;try{const e=new URL(t);"http:"!==e.protocol&&"https:"!==e.protocol&&r.push(new ConfigValidationError("registry","HTTP(S) URL",t,"Registry URL must use HTTP or HTTPS protocol."))}catch{r.push(new ConfigValidationError("registry","valid URL",t,'Provide a valid URL (e.g., "https://private.me/registry").'))}}else if(i){const t=e.registry,i=["register","resolve"].filter(e=>!(e in t)||"function"!=typeof t[e]);i.length>0&&r.push(new ConfigValidationError("registry","TrustRegistry instance","object missing required methods",`TrustRegistry must implement ${i.join(", ")} method(s). Use HttpTrustRegistry or MemoryTrustRegistry.`))}}else r.push(new ConfigValidationError("registry","TrustRegistry instance or URL string",e.registry,'Provide either a registry URL (e.g., "https://private.me/registry") or a TrustRegistry instance.'))}if(void 0!==e.transport){const t=Array.isArray(e.transport);if("object"==typeof e.transport&&null!==e.transport&&!t||t)if(t){const t=e.transport;0===t.length&&r.push(new ConfigValidationError("transport","non-empty array",t,"Provide at least one transport adapter.")),t.forEach((t,e)=>{if("object"!=typeof t||null===t)r.push(new ConfigValidationError(`transport[${e}]`,"XailTransportAdapter",t,"Each transport must be a XailTransportAdapter instance."));else{"send"in t&&"function"==typeof t.send||r.push(new ConfigValidationError(`transport[${e}]`,"XailTransportAdapter with send() method","object missing send() method","Transport must implement send() method. Use HttpsTransportAdapter or custom adapter."))}})}else{const t=e.transport;"send"in t&&"function"==typeof t.send||r.push(new ConfigValidationError("transport","XailTransportAdapter with send() method","object missing send() method","Transport must implement send() method. Use HttpsTransportAdapter or custom adapter."))}else r.push(new ConfigValidationError("transport","XailTransportAdapter or XailTransportAdapter[]",e.transport,"Provide a single transport adapter or an array of adapters for split-channel security."))}if(void 0!==e.securityPolicy)if("object"!=typeof e.securityPolicy||null===e.securityPolicy)r.push(new ConfigValidationError("securityPolicy","SecurityPolicy instance",e.securityPolicy,"Provide a SecurityPolicy instance (e.g., DefaultSecurityPolicy or custom policy)."));else{const t=e.securityPolicy;"classify"in t&&"function"==typeof t.classify||r.push(new ConfigValidationError("securityPolicy","SecurityPolicy with classify() method","object missing classify() method","SecurityPolicy must implement classify() method. Use DefaultSecurityPolicy."))}if(void 0!==e.postQuantumSig&&"boolean"!=typeof e.postQuantumSig&&r.push(new ConfigValidationError("postQuantumSig","boolean",e.postQuantumSig,"Use true to enable ML-DSA-65 post-quantum signatures, or false to disable.")),void 0!==e.backupConfig)if("object"!=typeof e.backupConfig||null===e.backupConfig)r.push(new ConfigValidationError("backupConfig","BackupConfig object",e.backupConfig,"Provide a BackupConfig object with threshold (k) and totalShares (n) properties."));else{const t=e.backupConfig;"number"!=typeof t.threshold?r.push(new ConfigValidationError("backupConfig.threshold","number",t.threshold,"Threshold (k) must be a number representing shares needed for reconstruction.")):t.threshold<2&&r.push(new ConfigValidationError("backupConfig.threshold","number >= 2",t.threshold,"Threshold must be at least 2 for meaningful splitting.")),"number"!=typeof t.totalShares?r.push(new ConfigValidationError("backupConfig.totalShares","number",t.totalShares,"totalShares (n) must be a number representing total shares to create.")):t.totalShares<2&&r.push(new ConfigValidationError("backupConfig.totalShares","number >= 2",t.totalShares,"totalShares must be at least 2 for splitting.")),"number"==typeof t.threshold&&"number"==typeof t.totalShares&&t.threshold>t.totalShares&&r.push(new ConfigValidationError("backupConfig","threshold <= totalShares",`threshold=${t.threshold}, totalShares=${t.totalShares}`,`Threshold (${t.threshold}) cannot exceed totalShares (${t.totalShares}). Use threshold <= totalShares.`))}return r.length>0?(0,shared_1.err)(r[0]):(0,shared_1.ok)(e)}function validateAgentCreateOptions(t){if(!t||"object"!=typeof t)return(0,shared_1.err)(new ConfigValidationError("options","object",t,"Provide a configuration object with required fields: name, registry, transport."));const e=t,r=[];if(void 0===e.name?r.push(new ConfigValidationError("name","string (required)",void 0,'Provide a display name for the agent (e.g., "my-agent").')):"string"!=typeof e.name?r.push(new ConfigValidationError("name","string",e.name,"Agent name must be a string.")):0===e.name.trim().length?r.push(new ConfigValidationError("name","non-empty string",e.name,"Agent name cannot be empty or whitespace only.")):e.name.length>255&&r.push(new ConfigValidationError("name","string with length <= 255",e.name,`Agent name is too long (${e.name.length} characters). Use 255 characters or less.`)),void 0===e.registry)r.push(new ConfigValidationError("registry","TrustRegistry (required)",void 0,"Provide a TrustRegistry instance (e.g., new MemoryTrustRegistry() or new HttpTrustRegistry())."));else if("object"!=typeof e.registry||null===e.registry)r.push(new ConfigValidationError("registry","TrustRegistry instance",e.registry,"Registry must be a TrustRegistry instance, not a string or primitive value."));else{const t=e.registry,i=["register","resolve"].filter(e=>!(e in t)||"function"!=typeof t[e]);i.length>0&&r.push(new ConfigValidationError("registry","TrustRegistry instance","object missing required methods",`TrustRegistry must implement: ${i.join(", ")}. Use HttpTrustRegistry or MemoryTrustRegistry.`))}if(void 0===e.transport)r.push(new ConfigValidationError("transport","XailTransportAdapter or XailTransportAdapter[] (required)",void 0,"Provide a transport adapter (e.g., new HttpsTransportAdapter()) or array of adapters for split-channel."));else{const t=Array.isArray(e.transport);if("object"==typeof e.transport&&null!==e.transport&&!t||t)if(t){const t=e.transport;0===t.length&&r.push(new ConfigValidationError("transport","non-empty array",t,"Provide at least one transport adapter.")),t.forEach((t,e)=>{if("object"!=typeof t||null===t)r.push(new ConfigValidationError(`transport[${e}]`,"XailTransportAdapter",t,"Each transport must be a XailTransportAdapter instance."));else{"send"in t&&"function"==typeof t.send||r.push(new ConfigValidationError(`transport[${e}]`,"XailTransportAdapter with send() method","object missing send() method","Transport must implement send() method. Use HttpsTransportAdapter or custom adapter."))}})}else{const t=e.transport;"send"in t&&"function"==typeof t.send||r.push(new ConfigValidationError("transport","XailTransportAdapter with send() method","object missing send() method","Transport must implement send() method. Use HttpsTransportAdapter or custom adapter."))}else r.push(new ConfigValidationError("transport","XailTransportAdapter or XailTransportAdapter[]",e.transport,"Provide a single transport adapter or an array of adapters."))}if(void 0!==e.nonceStore)if("object"!=typeof e.nonceStore||null===e.nonceStore)r.push(new ConfigValidationError("nonceStore","NonceStore instance",e.nonceStore,"Provide a NonceStore instance (e.g., new MemoryNonceStore())."));else{const t=e.nonceStore,i=["check","cleanup"].filter(e=>!(e in t)||"function"!=typeof t[e]);i.length>0&&r.push(new ConfigValidationError("nonceStore","NonceStore instance","object missing required methods",`NonceStore must implement: ${i.join(", ")}. Use MemoryNonceStore.`))}if(void 0!==e.scopes)if(Array.isArray(e.scopes)){e.scopes.forEach((t,e)=>{"string"!=typeof t?r.push(new ConfigValidationError(`scopes[${e}]`,"string",t,"Each scope must be a string.")):0===t.trim().length&&r.push(new ConfigValidationError(`scopes[${e}]`,"non-empty string",t,"Scope cannot be empty or whitespace only."))})}else r.push(new ConfigValidationError("scopes","string[]",e.scopes,'Provide an array of scope strings (e.g., ["read", "write"]).'));if(void 0!==e.timestampWindowMs&&("number"!=typeof e.timestampWindowMs?r.push(new ConfigValidationError("timestampWindowMs","number (milliseconds)",e.timestampWindowMs,"Provide timestamp window as a number in milliseconds (e.g., 30000 for 30 seconds).")):e.timestampWindowMs<=0?r.push(new ConfigValidationError("timestampWindowMs","positive number",e.timestampWindowMs,"Timestamp window must be greater than 0. Use at least 1000 (1 second).")):e.timestampWindowMs<5e3?r.push(new ConfigValidationError("timestampWindowMs","number >= 5000",e.timestampWindowMs,"Timestamp window is very short. Use at least 5000ms (5 seconds) to account for clock skew.")):e.timestampWindowMs>3e5&&r.push(new ConfigValidationError("timestampWindowMs","number <= 300000",e.timestampWindowMs,"Timestamp window is very long. Consider using 300000ms (5 minutes) or less for security."))),void 0!==e.postQuantumSig&&"boolean"!=typeof e.postQuantumSig&&r.push(new ConfigValidationError("postQuantumSig","boolean",e.postQuantumSig,"Use true to enable ML-DSA-65 post-quantum signatures, or false to disable.")),void 0!==e.xchange&&"boolean"!=typeof e.xchange&&r.push(new ConfigValidationError("xchange","boolean",e.xchange,"Use true to advertise Xchange mode support, or false to disable.")),void 0!==e.securityPolicy)if("object"!=typeof e.securityPolicy||null===e.securityPolicy)r.push(new ConfigValidationError("securityPolicy","SecurityPolicy instance",e.securityPolicy,"Provide a SecurityPolicy instance (e.g., DefaultSecurityPolicy or custom policy)."));else{const t=e.securityPolicy;"classify"in t&&"function"==typeof t.classify||r.push(new ConfigValidationError("securityPolicy","SecurityPolicy with classify() method","object missing classify() method","SecurityPolicy must implement classify() method. Use DefaultSecurityPolicy."))}return r.length>0?(0,shared_1.err)(r[0]):(0,shared_1.ok)(e)}function getValidationDetails(t){const e=[],r=[],i=validateAgentOptions(t);if(i.ok||e.push(i.error),t&&"object"==typeof t){const e=t;"number"==typeof e.identityTTL&&(e.identityTTL<6e4&&e.identityTTL>0?r.push(`identityTTL is very short (${e.identityTTL}ms). Consider using at least 60000ms (1 minute).`):e.identityTTL>864e5&&r.push(`identityTTL is very long (${e.identityTTL}ms). Consider using 'persistent' identity mode instead.`),"persistent"===e.identity&&r.push("identityTTL is ignored for 'persistent' identity mode."))}return{valid:0===e.length,errors:e,warnings:r}}function assertValidConfig(t){const e=validateAgentOptions(t);if(!e.ok)throw e.error}function assertValidCreateConfig(t){const e=validateAgentCreateOptions(t);if(!e.ok)throw e.error}exports.ConfigValidationError=ConfigValidationError,exports.AGENT_OPTIONS_DEFAULTS={identity:"persistent",identityTTL:36e5,postQuantumSig:!1},exports.AGENT_CREATE_OPTIONS_DEFAULTS={timestampWindowMs:3e4,postQuantumSig:!1,xchange:!1,scopes:[]};