@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/config-validation.js

@@ -1 +1,513 @@
-import{ok,err}from"./_deps/shared/index.js";import{XBindError}from"./errors.js";export class ConfigValidationError extends 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}}export const AGENT_OPTIONS_DEFAULTS={identity:"persistent",identityTTL:36e5,postQuantumSig:!1};export const AGENT_CREATE_OPTIONS_DEFAULTS={timestampWindowMs:3e4,postQuantumSig:!1,xchange:!1,scopes:[]};export function validateAgentOptions(t){if(!t||"object"!=typeof t)return 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?err(r[0]):ok(e)}export function validateAgentCreateOptions(t){if(!t||"object"!=typeof t)return 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?err(r[0]):ok(e)}export 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}}export function assertValidConfig(t){const e=validateAgentOptions(t);if(!e.ok)throw e.error}export function assertValidCreateConfig(t){const e=validateAgentCreateOptions(t);if(!e.ok)throw e.error}
+/**
+ * @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
+ * });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { XBindError } from './errors.js';
+/**
+ * Configuration validation error with detailed context.
+ */
+export class ConfigValidationError extends 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;
+    }
+}
+/**
+ * Default values for AgentOptions.
+ */
+export const AGENT_OPTIONS_DEFAULTS = {
+    identity: 'persistent',
+    identityTTL: 3600000, // 1 hour
+    postQuantumSig: false,
+};
+/**
+ * Default values for AgentCreateOptions.
+ */
+export const 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);
+ * }
+ * ```
+ */
+export function validateAgentOptions(options) {
+    if (!options || typeof options !== 'object') {
+        return 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 err(errors[0]);
+    }
+    return 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);
+ * }
+ * ```
+ */
+export function validateAgentCreateOptions(options) {
+    if (!options || typeof options !== 'object') {
+        return 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 err(errors[0]);
+    }
+    return 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}`);
+ * });
+ * ```
+ */
+export 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}`);
+ *   }
+ * }
+ * ```
+ */
+export 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
+ */
+export function assertValidCreateConfig(options) {
+    const result = validateAgentCreateOptions(options);
+    if (!result.ok) {
+        throw result.error;
+    }
+}