@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/cli/xbind.js

@@ -1,149 +1,2 @@
 #!/usr/bin/env node
-/* eslint-disable no-console */
-/**
- * @module cli/xbind
- * Main xBind CLI router - dispatches to subcommands.
- *
- * Supports 12 commands (v2.0.0 spec):
- * 1. setup     - Create deployment identity
- * 2. connect   - Connect to a service (TODO)
- * 3. invite    - Generate invite link (TODO)
- * 4. list      - List connections (TODO)
- * 5. status    - Display connection status (TODO)
- * 6. migrate   - Scan for API keys (TODO)
- * 7. trial     - Activate free trial (TODO)
- * 8. deploy    - Deploy algorithms (TODO)
- * 9. server    - Start relay server (TODO)
- * 10. revoke   - Revoke connection (TODO)
- * 11. backup   - Export/import identity (TODO)
- * 12. debug    - Diagnostics (TODO)
- */
-import { parseArgs } from 'node:util';
-import { ExitCode, Colors } from './types.js';
-/**
- * Show help message.
- */
-function showHelp() {
-    console.log(`
-xBind CLI - Identity-Based M2M Authentication
-
-Usage:
-  xbind <command> [options]
-
-Commands:
-  setup        Create deployment identity (DID + DeploymentID)
-  connect      Connect to a service (TODO)
-  invite       Generate viral invite link (TODO)
-  list         List all active connections (TODO)
-  status       Display connection status (TODO)
-  migrate      Scan codebase for API keys (TODO)
-  trial        Activate 3-month free trial (TODO)
-  deploy       Deploy proprietary algorithms (TODO)
-  server       Start agent relay server (TODO)
-  revoke       Revoke connection (TODO)
-  backup       Export/import identity (TODO)
-  debug        Diagnostic information (TODO)
-
-Global Options:
-  --json       Output JSON only (no human-readable text)
-  --no-color   Disable colored output
-  --debug      Show detailed error information
-  -h, --help   Show this help message
-
-Examples:
-  xbind setup --name my-service
-  xbind setup --email user@example.com --force
-  xbind connect payments-service
-  xbind status
-
-Documentation:
-  https://private.me/docs/xbind
-  `.trim());
-}
-/**
- * Show version.
- */
-function showVersion() {
-    // Read from package.json
-    console.log('xBind CLI v1.3.0');
-}
-/**
- * Main CLI entry point.
- */
-async function main() {
-    const args = process.argv.slice(2);
-    // No arguments - show help
-    if (args.length === 0) {
-        showHelp();
-        return;
-    }
-    // Parse global flags
-    const { values, positionals } = parseArgs({
-        args,
-        options: {
-            help: { type: 'boolean', short: 'h' },
-            version: { type: 'boolean', short: 'v' },
-            json: { type: 'boolean' },
-            'no-color': { type: 'boolean' },
-            debug: { type: 'boolean' },
-        },
-        allowPositionals: true,
-        strict: false, // Allow command-specific flags
-    });
-    // Global flags
-    if (values.help) {
-        showHelp();
-        return;
-    }
-    if (values.version) {
-        showVersion();
-        return;
-    }
-    // Get command
-    const command = positionals[0];
-    if (!command) {
-        showHelp();
-        return;
-    }
-    // Route to command handler
-    switch (command) {
-        case 'setup': {
-            const { main: setupMain } = await import('./setup.js');
-            await setupMain(args.slice(1)); // Pass remaining args to setup command
-            break;
-        }
-        case 'connect':
-        case 'invite':
-        case 'list':
-        case 'status':
-        case 'migrate':
-        case 'trial':
-        case 'deploy':
-        case 'server':
-        case 'revoke':
-        case 'backup':
-        case 'debug': {
-            const useColors = !values['no-color'] && process.stderr.isTTY;
-            const yellow = useColors ? Colors.YELLOW : '';
-            const reset = useColors ? Colors.RESET : '';
-            console.error(`${yellow}⚠️  Command "${command}" not yet implemented${reset}`);
-            console.error(`\nAvailable commands:`);
-            console.error(`  • setup - Create deployment identity (IMPLEMENTED)`);
-            console.error(`\nComing soon: connect, invite, list, status, migrate, trial, deploy, server, revoke, backup, debug`);
-            process.exit(ExitCode.USER_ERROR);
-        }
-        default: {
-            const useColors = !values['no-color'] && process.stderr.isTTY;
-            const red = useColors ? Colors.RED : '';
-            const reset = useColors ? Colors.RESET : '';
-            console.error(`${red}❌ Error: Unknown command "${command}"${reset}`);
-            console.error(`\nRun "xbind --help" to see available commands.`);
-            process.exit(ExitCode.USER_ERROR);
-        }
-    }
-}
-// Run main
-main().catch((error) => {
-    console.error('Fatal error:', error instanceof Error ? error.message : String(error));
-    process.exit(ExitCode.SYSTEM_ERROR);
-});
+import{parseArgs}from"node:util";import{ExitCode,Colors}from"./types.js";function showHelp(){console.log("\nxBind CLI - Identity-Based M2M Authentication\n\nUsage:\n  xbind <command> [options]\n\nCommands:\n  setup        Create deployment identity (DID + DeploymentID)\n  connect      Connect to a service (TODO)\n  invite       Generate viral invite link (TODO)\n  list         List all active connections (TODO)\n  status       Display connection status (TODO)\n  migrate      Scan codebase for API keys (TODO)\n  trial        Activate 3-month free trial (TODO)\n  deploy       Deploy proprietary algorithms (TODO)\n  server       Start agent relay server (TODO)\n  revoke       Revoke connection (TODO)\n  backup       Export/import identity (TODO)\n  debug        Diagnostic information (TODO)\n\nGlobal Options:\n  --json       Output JSON only (no human-readable text)\n  --no-color   Disable colored output\n  --debug      Show detailed error information\n  -h, --help   Show this help message\n\nExamples:\n  xbind setup --name my-service\n  xbind setup --email user@example.com --force\n  xbind connect payments-service\n  xbind status\n\nDocumentation:\n  https://private.me/docs/xbind\n  ".trim())}function showVersion(){console.log("xBind CLI v1.3.0")}async function main(){const e=process.argv.slice(2);if(0===e.length)return void showHelp();const{values:o,positionals:n}=parseArgs({args:e,options:{help:{type:"boolean",short:"h"},version:{type:"boolean",short:"v"},json:{type:"boolean"},"no-color":{type:"boolean"},debug:{type:"boolean"}},allowPositionals:!0,strict:!1});if(o.help)return void showHelp();if(o.version)return void showVersion();const t=n[0];if(t)switch(t){case"setup":{const{main:o}=await import("./setup.js");await o(e.slice(1));break}case"connect":case"invite":case"list":case"status":case"migrate":case"trial":case"deploy":case"server":case"revoke":case"backup":case"debug":{const e=!o["no-color"]&&process.stderr.isTTY,n=e?Colors.YELLOW:"",s=e?Colors.RESET:"";console.error(`${n}⚠️  Command "${t}" not yet implemented${s}`),console.error("\nAvailable commands:"),console.error("  • setup - Create deployment identity (IMPLEMENTED)"),console.error("\nComing soon: connect, invite, list, status, migrate, trial, deploy, server, revoke, backup, debug"),process.exit(ExitCode.USER_ERROR)}default:{const e=!o["no-color"]&&process.stderr.isTTY,n=e?Colors.RED:"",s=e?Colors.RESET:"";console.error(`${n}❌ Error: Unknown command "${t}"${s}`),console.error('\nRun "xbind --help" to see available commands.'),process.exit(ExitCode.USER_ERROR)}}else showHelp()}main().catch(e=>{console.error("Fatal error:",e instanceof Error?e.message:String(e)),process.exit(ExitCode.SYSTEM_ERROR)});

package/dist-standalone/config-validation.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @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 type { Result } from '@private.me/shared';
+import type { AgentOptions, AgentCreateOptions } from './agent.js';
+import { XBindError } from './errors.js';
+/**
+ * Configuration validation error with detailed context.
+ */
+export declare class ConfigValidationError extends XBindError {
+    /** Field that failed validation */
+    readonly field: string;
+    /** Expected value/type */
+    readonly expected: string;
+    /** Actual value received */
+    readonly actual: unknown;
+    /** Suggested fix */
+    readonly fix: string;
+    constructor(field: string, expected: string, actual: unknown, fix: string);
+}
+/**
+ * Validation result with detailed error information.
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: ConfigValidationError[];
+    /** Warnings (non-blocking issues) */
+    warnings: string[];
+}
+/**
+ * Default values for AgentOptions.
+ */
+export declare const AGENT_OPTIONS_DEFAULTS: {
+    readonly identity: "persistent";
+    readonly identityTTL: 3600000;
+    readonly postQuantumSig: false;
+};
+/**
+ * Default values for AgentCreateOptions.
+ */
+export declare const AGENT_CREATE_OPTIONS_DEFAULTS: {
+    readonly timestampWindowMs: 30000;
+    readonly postQuantumSig: false;
+    readonly xchange: false;
+    readonly scopes: string[];
+};
+/**
+ * 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 declare function validateAgentOptions(options: unknown): Result<AgentOptions, ConfigValidationError>;
+/**
+ * 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 declare function validateAgentCreateOptions(options: unknown): Result<AgentCreateOptions, ConfigValidationError>;
+/**
+ * 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 declare function getValidationDetails(options: unknown): ValidationResult;
+/**
+ * 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 declare function assertValidConfig(options: unknown): asserts options is AgentOptions;
+/**
+ * Validate configuration and throw on error (full options).
+ *
+ * @param options - AgentCreateOptions to validate
+ * @throws ConfigValidationError if validation fails
+ */
+export declare function assertValidCreateConfig(options: unknown): asserts options is AgentCreateOptions;

package/dist-standalone/config-validation.js

@@ -0,0 +1 @@
+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}

package/dist-standalone/connect.js

@@ -1,274 +1 @@
-/**
- * @module connect
- * High-level connect() API for zero-config XBind connections.
- *
- * Enables: `const service = await connect('payments-service')`
- *
- * Combines:
- * - Service discovery
- * - Trust verification
- * - Agent creation
- * - Connection establishment
- *
- * @example
- * ```ts
- * import { connect } from '@private.me/xbind';
- *
- * // Connect by name (uses registry):
- * const payments = await connect('payments-service');
- *
- * // Connect by domain (uses .well-known):
- * const payments = await connect('payments.example.com');
- *
- * // Connect by URL (direct):
- * const payments = await connect('https://api.payments.com/xbind');
- *
- * // Use the connection:
- * await payments.send({
- *   to: payments.did,
- *   payload: { action: 'createCharge', amount: 100 },
- *   scope: 'payments',
- * });
- * ```
- */
-import { ok, err } from"./_deps/shared/index.js";
-import { fromBase64, toBase64 } from"./_deps/crypto/index.js";
-import { Agent } from './agent.js';
-import { ServiceDiscovery } from './discovery.js';
-import { HttpsTransportAdapter } from './transport.js';
-import { MemoryTrustRegistry } from './trust-registry.js';
-import { importPublicKey } from './identity.js';
-/**
- * Connect error codes.
- */
-export var ConnectErrorCode;
-(function (ConnectErrorCode) {
-    ConnectErrorCode["DISCOVERY_FAILED"] = "CONNECT_DISCOVERY_FAILED";
-    ConnectErrorCode["AGENT_CREATION_FAILED"] = "CONNECT_AGENT_CREATION_FAILED";
-    ConnectErrorCode["TRUST_VERIFICATION_FAILED"] = "CONNECT_TRUST_VERIFICATION_FAILED";
-    ConnectErrorCode["INVALID_SERVICE_INFO"] = "CONNECT_INVALID_SERVICE_INFO";
-})(ConnectErrorCode || (ConnectErrorCode = {}));
-/**
- * Connect to a service with zero configuration.
- *
- * @param nameOrUrl - Service name, domain, or URL
- * @param options - Connection options
- * @returns Connection or error
- *
- * @example
- * ```ts
- * // Minimal:
- * const connection = await connect('payments-service');
- * if (connection.ok) {
- *   await connection.value.agent.send({
- *     to: connection.value.did,
- *     payload: { action: 'test' },
- *     scope: 'test',
- *   });
- * }
- *
- * // With options:
- * const connection = await connect('payments-service', {
- *   name: 'billing-service',
- *   xchange: true, // Use faster Xchange mode
- *   splitChannel: true, // Use split-channel by default
- * });
- * ```
- */
-export async function connect(nameOrUrl, options = {}) {
-    // Step 1: Discover service
-    const discovery = options.discovery || new ServiceDiscovery();
-    const serviceResult = await discovery.discover(nameOrUrl);
-    if (!serviceResult.ok) {
-        return err({
-            code: ConnectErrorCode.DISCOVERY_FAILED,
-            message: `Failed to discover service: ${serviceResult.error.message}`,
-            hint: serviceResult.error.hint,
-            cause: serviceResult.error,
-        });
-    }
-    const service = serviceResult.value;
-    // Step 2: Validate service info
-    if (!service.did || !service.endpoint || !service.publicKey) {
-        return err({
-            code: ConnectErrorCode.INVALID_SERVICE_INFO,
-            message: 'Service info missing required fields (did, endpoint, publicKey)',
-            hint: 'Service must provide complete metadata',
-        });
-    }
-    // Step 3: Create trust registry and add service
-    const registry = options.registry || new MemoryTrustRegistry();
-    try {
-        // Import public key (convert from base64 string)
-        const publicKeyBytes = fromBase64(service.publicKey);
-        const publicKeyResult = await importPublicKey(publicKeyBytes);
-        if (!publicKeyResult.ok) {
-            return err({
-                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
-                message: 'Invalid service public key',
-                cause: publicKeyResult.error,
-            });
-        }
-        // Add to trust registry
-        await registry.add({
-            did: service.did,
-            publicKey: publicKeyResult.value,
-            x25519PublicKey: service.x25519PublicKey
-                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
-                : undefined,
-            mlKemPublicKey: service.mlKemPublicKey
-                ? fromBase64(service.mlKemPublicKey)
-                : undefined,
-        });
-    }
-    catch (error) {
-        return err({
-            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
-            message: 'Failed to verify service public key',
-            cause: error,
-        });
-    }
-    // Step 4: Create transport
-    const transport = options.transport || new HttpsTransportAdapter({
-        baseUrl: service.endpoint,
-    });
-    // Step 5: Create agent
-    const agentName = options.name || `client-${Date.now()}`;
-    const agentOptions = {
-        name: agentName,
-        registry,
-        transport,
-        xchange: options.xchange,
-        postQuantumSig: options.postQuantumSig,
-    };
-    const agentResult = await Agent.create(agentOptions);
-    if (!agentResult.ok) {
-        return err({
-            code: ConnectErrorCode.AGENT_CREATION_FAILED,
-            message: 'Failed to create agent',
-            cause: agentResult.error,
-        });
-    }
-    // Step 6: Return connection
-    return ok({
-        agent: agentResult.value,
-        service,
-        did: service.did,
-        endpoint: service.endpoint,
-    });
-}
-/**
- * Accept an invite and establish connection.
- *
- * @param inviteUrl - Invite URL
- * @param options - Connection options
- * @returns Connection or error
- *
- * @example
- * ```ts
- * const connection = await acceptInvite('https://xbind.to/invite/abc123', {
- *   name: 'my-service',
- * });
- *
- * if (connection.ok) {
- *   console.log('Connected to:', connection.value.service.name);
- * }
- * ```
- */
-export async function acceptInvite(inviteUrl, options = {}) {
-    const { InviteService } = await import('./invite.js');
-    const inviteService = new InviteService();
-    // Get invite details
-    const inviteResult = await inviteService.get(inviteUrl);
-    if (!inviteResult.ok) {
-        return err({
-            code: ConnectErrorCode.DISCOVERY_FAILED,
-            message: `Failed to get invite: ${inviteResult.error.message}`,
-            cause: inviteResult.error,
-        });
-    }
-    const invite = inviteResult.value;
-    // Convert invite.from to ServiceInfo
-    const service = {
-        name: invite.from.name,
-        did: invite.from.did,
-        endpoint: invite.from.endpoint,
-        publicKey: invite.from.publicKey,
-        x25519PublicKey: invite.from.x25519PublicKey,
-        mlKemPublicKey: invite.from.mlKemPublicKey,
-    };
-    // Connect to service (same as connect())
-    // Create trust registry and add service
-    const registry = options.registry || new MemoryTrustRegistry();
-    try {
-        // Import public key (convert from base64 string)
-        const publicKeyBytes = fromBase64(service.publicKey);
-        const publicKeyResult = await importPublicKey(publicKeyBytes);
-        if (!publicKeyResult.ok) {
-            return err({
-                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
-                message: 'Invalid service public key',
-                cause: publicKeyResult.error,
-            });
-        }
-        await registry.add({
-            did: service.did,
-            publicKey: publicKeyResult.value,
-            x25519PublicKey: service.x25519PublicKey
-                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
-                : undefined,
-            mlKemPublicKey: service.mlKemPublicKey
-                ? fromBase64(service.mlKemPublicKey)
-                : undefined,
-        });
-    }
-    catch (error) {
-        return err({
-            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
-            message: 'Failed to verify service public key',
-            cause: error,
-        });
-    }
-    const transport = options.transport || new HttpsTransportAdapter({
-        baseUrl: service.endpoint,
-    });
-    const agentName = options.name || `client-${Date.now()}`;
-    const agentOptions = {
-        name: agentName,
-        registry,
-        transport,
-        xchange: options.xchange,
-        postQuantumSig: options.postQuantumSig,
-    };
-    const agentResult = await Agent.create(agentOptions);
-    if (!agentResult.ok) {
-        return err({
-            code: ConnectErrorCode.AGENT_CREATION_FAILED,
-            message: 'Failed to create agent',
-            cause: agentResult.error,
-        });
-    }
-    // Accept the invite
-    const acceptResult = await inviteService.accept({
-        inviteUrl,
-        acceptor: {
-            name: agentOptions.name,
-            did: agentResult.value.did,
-            endpoint: options.endpoint || '', // Agent's endpoint (where it can be reached), empty for client-only agents
-            publicKey: toBase64(agentResult.value.identity.rawPublicKey),
-            x25519PublicKey: agentResult.value.identity.rawX25519PublicKey
-                ? toBase64(agentResult.value.identity.rawX25519PublicKey)
-                : undefined,
-        },
-    });
-    if (!acceptResult.ok) {
-        // Connection created but invite acceptance failed - still return connection
-        // (invite acceptance is for tracking/notification, not required for connectivity)
-    }
-    return ok({
-        agent: agentResult.value,
-        service,
-        did: service.did,
-        endpoint: service.endpoint,
-    });
-}
+import{ok,err}from"./_deps/shared/index.js";import{fromBase64,toBase64}from"./crypto-utils.js";import{Agent}from"./agent.js";import{ServiceDiscovery}from"./discovery.js";import{HttpsTransportAdapter}from"./transport.js";import{MemoryTrustRegistry}from"./trust-registry.js";import{importPublicKey}from"./identity.js";export var ConnectErrorCode;!function(e){e.DISCOVERY_FAILED="CONNECT_DISCOVERY_FAILED",e.AGENT_CREATION_FAILED="CONNECT_AGENT_CREATION_FAILED",e.TRUST_VERIFICATION_FAILED="CONNECT_TRUST_VERIFICATION_FAILED",e.INVALID_SERVICE_INFO="CONNECT_INVALID_SERVICE_INFO"}(ConnectErrorCode||(ConnectErrorCode={}));export async function connect(e,r={}){const t=r.discovery||new ServiceDiscovery,i=await t.discover(e);if(!i.ok)return err({code:ConnectErrorCode.DISCOVERY_FAILED,message:`Failed to discover service: ${i.error.message}`,hint:i.error.hint,cause:i.error});const o=i.value;if(!o.did||!o.endpoint||!o.publicKey)return err({code:ConnectErrorCode.INVALID_SERVICE_INFO,message:"Service info missing required fields (did, endpoint, publicKey)",hint:"Service must provide complete metadata"});const n=r.registry||new MemoryTrustRegistry;try{const e=fromBase64(o.publicKey),r=await importPublicKey(e);if(!r.ok)return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Invalid service public key",cause:r.error});await n.add({did:o.did,publicKey:r.value,x25519PublicKey:o.x25519PublicKey?await importPublicKey(fromBase64(o.x25519PublicKey)).then(e=>e.ok?e.value:void 0):void 0,mlKemPublicKey:o.mlKemPublicKey?fromBase64(o.mlKemPublicKey):void 0})}catch(e){return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Failed to verify service public key",cause:e})}const a=r.transport||new HttpsTransportAdapter({baseUrl:o.endpoint}),c={name:r.name||`client-${Date.now()}`,registry:n,transport:a,xchange:r.xchange,postQuantumSig:r.postQuantumSig},s=await Agent.create(c);return s.ok?ok({agent:s.value,service:o,did:o.did,endpoint:o.endpoint}):err({code:ConnectErrorCode.AGENT_CREATION_FAILED,message:"Failed to create agent",cause:s.error})}export async function acceptInvite(e,r={}){const{InviteService:t}=await import("./invite.js"),i=new t,o=await i.get(e);if(!o.ok)return err({code:ConnectErrorCode.DISCOVERY_FAILED,message:`Failed to get invite: ${o.error.message}`,cause:o.error});const n=o.value,a={name:n.from.name,did:n.from.did,endpoint:n.from.endpoint,publicKey:n.from.publicKey,x25519PublicKey:n.from.x25519PublicKey,mlKemPublicKey:n.from.mlKemPublicKey},c=r.registry||new MemoryTrustRegistry;try{const e=fromBase64(a.publicKey),r=await importPublicKey(e);if(!r.ok)return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Invalid service public key",cause:r.error});await c.add({did:a.did,publicKey:r.value,x25519PublicKey:a.x25519PublicKey?await importPublicKey(fromBase64(a.x25519PublicKey)).then(e=>e.ok?e.value:void 0):void 0,mlKemPublicKey:a.mlKemPublicKey?fromBase64(a.mlKemPublicKey):void 0})}catch(e){return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Failed to verify service public key",cause:e})}const s=r.transport||new HttpsTransportAdapter({baseUrl:a.endpoint}),d={name:r.name||`client-${Date.now()}`,registry:c,transport:s,xchange:r.xchange,postQuantumSig:r.postQuantumSig},u=await Agent.create(d);if(!u.ok)return err({code:ConnectErrorCode.AGENT_CREATION_FAILED,message:"Failed to create agent",cause:u.error});return(await i.accept({inviteUrl:e,acceptor:{name:d.name,did:u.value.did,endpoint:r.endpoint||"",publicKey:toBase64(u.value.identity.rawPublicKey),x25519PublicKey:u.value.identity.rawX25519PublicKey?toBase64(u.value.identity.rawX25519PublicKey):void 0}})).ok,ok({agent:u.value,service:a,did:a.did,endpoint:a.endpoint})}