@tjamescouch/agentchat 0.11.0 → 0.13.0

package/lib/escrow-hooks.js

@@ -0,0 +1,237 @@
+/**
+ * EscrowHooks - Event system for external escrow integration
+ *
+ * Allows external systems (blockchain, multi-sig, compliance) to hook into
+ * escrow lifecycle events without modifying core AgentChat code.
+ *
+ * Events:
+ *   escrow:created    - Escrow created when proposal accepted with stakes
+ *   escrow:released   - Escrow released (expired, cancelled)
+ *   settlement:completion - Proposal completed, stakes returned
+ *   settlement:dispute    - Proposal disputed, stakes transferred/burned
+ */
+
+export const EscrowEvent = {
+  CREATED: 'escrow:created',
+  RELEASED: 'escrow:released',
+  COMPLETION_SETTLED: 'settlement:completion',
+  DISPUTE_SETTLED: 'settlement:dispute'
+};
+
+export class EscrowHooks {
+  constructor(options = {}) {
+    this.handlers = new Map(); // event -> Set of handlers
+    this.logger = options.logger || console;
+    this.continueOnError = options.continueOnError !== false; // default true
+
+    // Initialize event handler sets
+    for (const event of Object.values(EscrowEvent)) {
+      this.handlers.set(event, new Set());
+    }
+  }
+
+  /**
+   * Register a handler for an escrow event
+   * @param {string} event - Event name from EscrowEvent
+   * @param {Function} handler - Async function(payload) to call
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      throw new Error(`Unknown escrow event: ${event}`);
+    }
+
+    if (typeof handler !== 'function') {
+      throw new Error('Handler must be a function');
+    }
+
+    this.handlers.get(event).add(handler);
+
+    // Return unsubscribe function
+    return () => this.off(event, handler);
+  }
+
+  /**
+   * Remove a handler for an escrow event
+   * @param {string} event - Event name
+   * @param {Function} handler - Handler to remove
+   */
+  off(event, handler) {
+    if (this.handlers.has(event)) {
+      this.handlers.get(event).delete(handler);
+    }
+  }
+
+  /**
+   * Remove all handlers for an event (or all events)
+   * @param {string} [event] - Optional event name
+   */
+  clear(event) {
+    if (event) {
+      if (this.handlers.has(event)) {
+        this.handlers.get(event).clear();
+      }
+    } else {
+      for (const handlers of this.handlers.values()) {
+        handlers.clear();
+      }
+    }
+  }
+
+  /**
+   * Emit an escrow event to all registered handlers
+   * @param {string} event - Event name
+   * @param {Object} payload - Event payload
+   * @returns {Promise<Object>} Results from all handlers
+   */
+  async emit(event, payload) {
+    if (!this.handlers.has(event)) {
+      throw new Error(`Unknown escrow event: ${event}`);
+    }
+
+    const handlers = this.handlers.get(event);
+    if (handlers.size === 0) {
+      return { event, handled: false, results: [] };
+    }
+
+    const results = [];
+    const errors = [];
+
+    for (const handler of handlers) {
+      try {
+        const result = await handler(payload);
+        results.push({ success: true, result });
+      } catch (err) {
+        const errorInfo = {
+          success: false,
+          error: err.message,
+          stack: err.stack
+        };
+        errors.push(errorInfo);
+        results.push(errorInfo);
+
+        this.logger.error?.(`[EscrowHooks] Error in ${event} handler:`, err.message);
+
+        if (!this.continueOnError) {
+          break;
+        }
+      }
+    }
+
+    return {
+      event,
+      handled: true,
+      results,
+      errors: errors.length > 0 ? errors : undefined
+    };
+  }
+
+  /**
+   * Check if any handlers are registered for an event
+   * @param {string} event - Event name
+   * @returns {boolean}
+   */
+  hasHandlers(event) {
+    return this.handlers.has(event) && this.handlers.get(event).size > 0;
+  }
+
+  /**
+   * Get count of handlers for an event
+   * @param {string} event - Event name
+   * @returns {number}
+   */
+  handlerCount(event) {
+    return this.handlers.has(event) ? this.handlers.get(event).size : 0;
+  }
+}
+
+/**
+ * Create payload for escrow:created event
+ */
+export function createEscrowCreatedPayload(proposal, escrowResult) {
+  return {
+    event: EscrowEvent.CREATED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    proposer_stake: proposal.proposer_stake || 0,
+    acceptor_stake: proposal.acceptor_stake || 0,
+    total_stake: (proposal.proposer_stake || 0) + (proposal.acceptor_stake || 0),
+    task: proposal.task,
+    amount: proposal.amount,
+    currency: proposal.currency,
+    expires: proposal.expires,
+    escrow_id: escrowResult.escrow?.proposal_id || proposal.id
+  };
+}
+
+/**
+ * Create payload for settlement:completion event
+ */
+export function createCompletionPayload(proposal, ratingChanges) {
+  const escrowInfo = ratingChanges?._escrow || {};
+  return {
+    event: EscrowEvent.COMPLETION_SETTLED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    completed_by: proposal.completed_by,
+    completion_proof: proposal.completion_proof,
+    settlement: 'returned',
+    stakes_returned: {
+      proposer: escrowInfo.proposer_stake || 0,
+      acceptor: escrowInfo.acceptor_stake || 0
+    },
+    rating_changes: {
+      [proposal.from]: ratingChanges?.[proposal.from],
+      [proposal.to]: ratingChanges?.[proposal.to]
+    }
+  };
+}
+
+/**
+ * Create payload for settlement:dispute event
+ */
+export function createDisputePayload(proposal, ratingChanges) {
+  const escrowInfo = ratingChanges?._escrow || {};
+  return {
+    event: EscrowEvent.DISPUTE_SETTLED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    disputed_by: proposal.disputed_by,
+    dispute_reason: proposal.dispute_reason,
+    settlement: escrowInfo.settlement || 'settled',
+    settlement_reason: escrowInfo.settlement_reason,
+    fault_determination: escrowInfo.fault_party,
+    stakes_transferred: escrowInfo.transferred,
+    stakes_burned: escrowInfo.burned,
+    rating_changes: {
+      [proposal.from]: ratingChanges?.[proposal.from],
+      [proposal.to]: ratingChanges?.[proposal.to]
+    }
+  };
+}
+
+/**
+ * Create payload for escrow:released event
+ */
+export function createEscrowReleasedPayload(proposalId, escrow, reason) {
+  return {
+    event: EscrowEvent.RELEASED,
+    timestamp: Date.now(),
+    proposal_id: proposalId,
+    from_agent: escrow.from?.agent_id,
+    to_agent: escrow.to?.agent_id,
+    stakes_released: {
+      proposer: escrow.from?.stake || 0,
+      acceptor: escrow.to?.stake || 0
+    },
+    reason: reason || 'expired'
+  };
+}
+
+export default EscrowHooks;

package/lib/identity.js

@@ -44,6 +44,7 @@ export class Identity {
     this.pubkey = data.pubkey;      // PEM format
     this.privkey = data.privkey;    // PEM format (null if loaded from export)
     this.created = data.created;
+    this.rotations = data.rotations || [];  // Array of rotation records
 
     // Lazy-load crypto key objects
     this._publicKey = null;
@@ -85,7 +86,8 @@ export class Identity {
       name: this.name,
       pubkey: this.pubkey,
       privkey: this.privkey,
-      created: this.created
+      created: this.created,
+      rotations: this.rotations
     };
 
     await fs.writeFile(filePath, JSON.stringify(data, null, 2), {
@@ -160,7 +162,137 @@ export class Identity {
     return {
       name: this.name,
       pubkey: this.pubkey,
-      created: this.created
+      created: this.created,
+      rotations: this.rotations
     };
   }
+
+  /**
+   * Rotate to a new keypair
+   * Signs the new public key with the old private key for chain of custody
+   * @returns {object} Rotation record with old_pubkey, new_pubkey, signature, timestamp
+   */
+  rotate() {
+    if (!this.privkey) {
+      throw new Error('Private key not available - cannot rotate');
+    }
+
+    // Generate new keypair
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const newPubkey = publicKey.export({ type: 'spki', format: 'pem' });
+    const newPrivkey = privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+    // Use same timestamp for both signing and record
+    const timestamp = new Date().toISOString();
+
+    // Create rotation record content to sign
+    const rotationContent = JSON.stringify({
+      old_pubkey: this.pubkey,
+      new_pubkey: newPubkey,
+      timestamp
+    });
+
+    // Sign with old private key
+    const signature = this.sign(rotationContent);
+
+    // Create rotation record
+    const rotationRecord = {
+      old_pubkey: this.pubkey,
+      old_agent_id: this.getAgentId(),
+      new_pubkey: newPubkey,
+      new_agent_id: pubkeyToAgentId(newPubkey),
+      signature,
+      timestamp
+    };
+
+    // Update identity with new keys
+    this.rotations.push(rotationRecord);
+    this.pubkey = newPubkey;
+    this.privkey = newPrivkey;
+    this._publicKey = null;
+    this._privateKey = null;
+
+    return rotationRecord;
+  }
+
+  /**
+   * Verify a rotation record
+   * Checks that the signature is valid using the old public key
+   * @param {object} record - Rotation record to verify
+   * @returns {boolean} True if signature is valid
+   */
+  static verifyRotation(record) {
+    try {
+      const rotationContent = JSON.stringify({
+        old_pubkey: record.old_pubkey,
+        new_pubkey: record.new_pubkey,
+        timestamp: record.timestamp
+      });
+
+      return Identity.verify(rotationContent, record.signature, record.old_pubkey);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Verify the entire rotation chain
+   * @returns {object} { valid: boolean, errors: string[] }
+   */
+  verifyRotationChain() {
+    const errors = [];
+
+    if (this.rotations.length === 0) {
+      return { valid: true, errors: [] };
+    }
+
+    // Verify each rotation in sequence
+    for (let i = 0; i < this.rotations.length; i++) {
+      const record = this.rotations[i];
+
+      // Verify signature
+      if (!Identity.verifyRotation(record)) {
+        errors.push(`Rotation ${i + 1}: Invalid signature`);
+        continue;
+      }
+
+      // Verify chain continuity (each new_pubkey should match next old_pubkey)
+      if (i < this.rotations.length - 1) {
+        const nextRecord = this.rotations[i + 1];
+        if (record.new_pubkey !== nextRecord.old_pubkey) {
+          errors.push(`Rotation ${i + 1}: Chain break - new_pubkey doesn't match next old_pubkey`);
+        }
+      }
+    }
+
+    // Verify final pubkey matches current identity
+    const lastRotation = this.rotations[this.rotations.length - 1];
+    if (lastRotation.new_pubkey !== this.pubkey) {
+      errors.push('Final rotation new_pubkey does not match current identity pubkey');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Get the original (genesis) public key before any rotations
+   * @returns {string} Original public key in PEM format
+   */
+  getOriginalPubkey() {
+    if (this.rotations.length === 0) {
+      return this.pubkey;
+    }
+    return this.rotations[0].old_pubkey;
+  }
+
+  /**
+   * Get the original (genesis) agent ID
+   * @returns {string} Original agent ID
+   */
+  getOriginalAgentId() {
+    return pubkeyToAgentId(this.getOriginalPubkey());
+  }
 }

package/lib/protocol.js

@@ -24,7 +24,12 @@ export const ClientMessageType = {
   DISPUTE: 'DISPUTE',
   // Skill discovery message types
   REGISTER_SKILLS: 'REGISTER_SKILLS',
-  SEARCH_SKILLS: 'SEARCH_SKILLS'
+  SEARCH_SKILLS: 'SEARCH_SKILLS',
+  // Presence message types
+  SET_PRESENCE: 'SET_PRESENCE',
+  // Identity verification message types
+  VERIFY_REQUEST: 'VERIFY_REQUEST',
+  VERIFY_RESPONSE: 'VERIFY_RESPONSE'
 };
 
 // Server -> Client message types
@@ -47,7 +52,14 @@ export const ServerMessageType = {
   DISPUTE: 'DISPUTE',
   // Skill discovery message types
   SKILLS_REGISTERED: 'SKILLS_REGISTERED',
-  SEARCH_RESULTS: 'SEARCH_RESULTS'
+  SEARCH_RESULTS: 'SEARCH_RESULTS',
+  // Presence message types
+  PRESENCE_CHANGED: 'PRESENCE_CHANGED',
+  // Identity verification message types
+  VERIFY_REQUEST: 'VERIFY_REQUEST',
+  VERIFY_RESPONSE: 'VERIFY_RESPONSE',
+  VERIFY_SUCCESS: 'VERIFY_SUCCESS',
+  VERIFY_FAILED: 'VERIFY_FAILED'
 };
 
 // Error codes
@@ -68,7 +80,19 @@ export const ErrorCode = {
   NOT_PROPOSAL_PARTY: 'NOT_PROPOSAL_PARTY',
   // Staking errors
   INSUFFICIENT_REPUTATION: 'INSUFFICIENT_REPUTATION',
-  INVALID_STAKE: 'INVALID_STAKE'
+  INVALID_STAKE: 'INVALID_STAKE',
+  // Verification errors
+  VERIFICATION_FAILED: 'VERIFICATION_FAILED',
+  VERIFICATION_EXPIRED: 'VERIFICATION_EXPIRED',
+  NO_PUBKEY: 'NO_PUBKEY'
+};
+
+// Presence status
+export const PresenceStatus = {
+  ONLINE: 'online',
+  AWAY: 'away',
+  BUSY: 'busy',
+  OFFLINE: 'offline'
 };
 
 // Proposal status
@@ -340,6 +364,50 @@ export function validateClientMessage(raw) {
       // query_id is optional but useful for tracking responses
       break;
 
+    case ClientMessageType.SET_PRESENCE:
+      // Set presence requires: status (online, away, busy, offline)
+      const validStatuses = ['online', 'away', 'busy', 'offline'];
+      if (!msg.status || !validStatuses.includes(msg.status)) {
+        return { valid: false, error: `Invalid presence status. Must be one of: ${validStatuses.join(', ')}` };
+      }
+      // Optional: status_text for custom message
+      if (msg.status_text !== undefined && typeof msg.status_text !== 'string') {
+        return { valid: false, error: 'status_text must be a string' };
+      }
+      if (msg.status_text && msg.status_text.length > 100) {
+        return { valid: false, error: 'status_text too long (max 100 chars)' };
+      }
+      break;
+
+    case ClientMessageType.VERIFY_REQUEST:
+      // Verify request requires: target agent and nonce
+      if (!msg.target) {
+        return { valid: false, error: 'Missing target agent' };
+      }
+      if (!isAgent(msg.target)) {
+        return { valid: false, error: 'Target must be an agent (@id)' };
+      }
+      if (!msg.nonce || typeof msg.nonce !== 'string') {
+        return { valid: false, error: 'Missing or invalid nonce' };
+      }
+      if (msg.nonce.length < 16 || msg.nonce.length > 128) {
+        return { valid: false, error: 'Nonce must be 16-128 characters' };
+      }
+      break;
+
+    case ClientMessageType.VERIFY_RESPONSE:
+      // Verify response requires: request_id, nonce, and signature
+      if (!msg.request_id) {
+        return { valid: false, error: 'Missing request_id' };
+      }
+      if (!msg.nonce || typeof msg.nonce !== 'string') {
+        return { valid: false, error: 'Missing or invalid nonce' };
+      }
+      if (!msg.sig || typeof msg.sig !== 'string') {
+        return { valid: false, error: 'Missing or invalid signature' };
+      }
+      break;
+
     default:
       return { valid: false, error: `Unknown message type: ${msg.type}` };
   }
@@ -395,3 +463,21 @@ export function isProposalMessage(type) {
     ClientMessageType.DISPUTE
   ].includes(type);
 }
+
+/**
+ * Generate a unique verification request ID
+ * Format: verify_<timestamp>_<random>
+ */
+export function generateVerifyId() {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomBytes(4).toString('hex');
+  return `verify_${timestamp}_${random}`;
+}
+
+/**
+ * Generate a random nonce for identity verification
+ * Returns a 32-character hex string
+ */
+export function generateNonce() {
+  return crypto.randomBytes(16).toString('hex');
+}

package/lib/server-directory.js

@@ -0,0 +1,181 @@
+/**
+ * Server Directory
+ * Registry of known AgentChat servers for discovery
+ */
+
+import http from 'http';
+import https from 'https';
+import fs from 'fs/promises';
+import path from 'path';
+
+// Default public servers (can be extended)
+export const DEFAULT_SERVERS = [
+  {
+    name: 'AgentChat Public',
+    url: 'wss://agentchat-server.fly.dev',
+    description: 'Official public AgentChat server',
+    region: 'global'
+  }
+];
+
+// Default directory file path
+export const DEFAULT_DIRECTORY_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE || '.',
+  '.agentchat',
+  'servers.json'
+);
+
+/**
+ * Server Directory for discovering AgentChat servers
+ */
+export class ServerDirectory {
+  constructor(options = {}) {
+    this.directoryPath = options.directoryPath || DEFAULT_DIRECTORY_PATH;
+    this.servers = [...DEFAULT_SERVERS];
+    this.timeout = options.timeout || 5000;
+  }
+
+  /**
+   * Load servers from directory file
+   */
+  async load() {
+    try {
+      const data = await fs.readFile(this.directoryPath, 'utf8');
+      const loaded = JSON.parse(data);
+      if (Array.isArray(loaded.servers)) {
+        // Merge with defaults, avoiding duplicates by URL
+        const urls = new Set(this.servers.map(s => s.url));
+        for (const server of loaded.servers) {
+          if (!urls.has(server.url)) {
+            this.servers.push(server);
+            urls.add(server.url);
+          }
+        }
+      }
+    } catch (err) {
+      // File doesn't exist or is invalid, use defaults
+    }
+    return this;
+  }
+
+  /**
+   * Save servers to directory file
+   */
+  async save() {
+    const dir = path.dirname(this.directoryPath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(this.directoryPath, JSON.stringify({
+      version: 1,
+      updated_at: new Date().toISOString(),
+      servers: this.servers
+    }, null, 2));
+  }
+
+  /**
+   * Add a server to the directory
+   */
+  async addServer(server) {
+    const existing = this.servers.find(s => s.url === server.url);
+    if (existing) {
+      Object.assign(existing, server);
+    } else {
+      this.servers.push(server);
+    }
+    await this.save();
+  }
+
+  /**
+   * Remove a server from the directory
+   */
+  async removeServer(url) {
+    this.servers = this.servers.filter(s => s.url !== url);
+    await this.save();
+  }
+
+  /**
+   * Check health of a single server
+   * @param {Object} server - Server object with url
+   * @returns {Object} Server with health status
+   */
+  async checkHealth(server) {
+    const wsUrl = server.url;
+    // Convert ws:// or wss:// to http:// or https://
+    const httpUrl = wsUrl
+      .replace('wss://', 'https://')
+      .replace('ws://', 'http://');
+
+    try {
+      const health = await this._fetchHealth(httpUrl + '/health');
+      return {
+        ...server,
+        status: 'online',
+        health,
+        checked_at: new Date().toISOString()
+      };
+    } catch (err) {
+      return {
+        ...server,
+        status: 'offline',
+        error: err.message || err.code || 'Unknown error',
+        checked_at: new Date().toISOString()
+      };
+    }
+  }
+
+  /**
+   * Fetch health endpoint
+   */
+  _fetchHealth(url) {
+    return new Promise((resolve, reject) => {
+      const protocol = url.startsWith('https') ? https : http;
+      const req = protocol.get(url, { timeout: this.timeout }, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          if (res.statusCode === 200) {
+            try {
+              resolve(JSON.parse(data));
+            } catch {
+              reject(new Error('Invalid health response'));
+            }
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Timeout'));
+      });
+    });
+  }
+
+  /**
+   * Discover available servers (check health of all known servers)
+   * @param {Object} options
+   * @param {boolean} options.onlineOnly - Only return online servers
+   * @returns {Array} List of servers with status
+   */
+  async discover(options = {}) {
+    const results = await Promise.all(
+      this.servers.map(server => this.checkHealth(server))
+    );
+
+    if (options.onlineOnly) {
+      return results.filter(s => s.status === 'online');
+    }
+
+    return results;
+  }
+
+  /**
+   * Get list of known servers without health check
+   */
+  list() {
+    return [...this.servers];
+  }
+}
+
+export default ServerDirectory;