@auxiora/agent-protocol 1.0.0

package/dist/signing.js

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import { getLogger } from '@auxiora/logger';
+const logger = getLogger('agent-protocol:signing');
+/**
+ * Ed25519-based message signing and verification for agent-to-agent communication.
+ */
+export class MessageSigner {
+    publicKey;
+    privateKey;
+    constructor(keyPair) {
+        if (keyPair) {
+            this.importKeys(keyPair);
+        }
+    }
+    /** Generate a new Ed25519 key pair. */
+    static generateKeyPair() {
+        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+        return {
+            publicKey: publicKey
+                .export({ type: 'spki', format: 'pem' })
+                .toString(),
+            privateKey: privateKey
+                .export({ type: 'pkcs8', format: 'pem' })
+                .toString(),
+        };
+    }
+    /** Import keys from PEM strings. */
+    importKeys(keyPair) {
+        this.publicKey = crypto.createPublicKey(keyPair.publicKey);
+        this.privateKey = crypto.createPrivateKey(keyPair.privateKey);
+    }
+    /** Import only a public key (for verification). */
+    importPublicKey(pem) {
+        this.publicKey = crypto.createPublicKey(pem);
+    }
+    /** Sign a message payload. Returns base64-encoded signature. */
+    sign(payload) {
+        if (!this.privateKey) {
+            throw new Error('Private key not available for signing');
+        }
+        const signature = crypto.sign(null, Buffer.from(payload, 'utf-8'), this.privateKey);
+        return signature.toString('base64');
+    }
+    /** Verify a signature against a payload. */
+    verify(payload, signature, publicKeyPem) {
+        const key = publicKeyPem ? crypto.createPublicKey(publicKeyPem) : this.publicKey;
+        if (!key) {
+            throw new Error('Public key not available for verification');
+        }
+        try {
+            return crypto.verify(null, Buffer.from(payload, 'utf-8'), key, Buffer.from(signature, 'base64'));
+        }
+        catch (error) {
+            logger.debug('Signature verification failed', { error: error });
+            return false;
+        }
+    }
+    /** Get the public key PEM string. */
+    getPublicKeyPem() {
+        return this.publicKey
+            ?.export({ type: 'spki', format: 'pem' })
+            .toString();
+    }
+}
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,MAAM,GAAG,SAAS,CAAC,wBAAwB,CAAC,CAAC;AAOnD;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,SAAS,CAA+B;IACxC,UAAU,CAA+B;IAEjD,YAAY,OAAiB;QAC3B,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,uCAAuC;IACvC,MAAM,CAAC,eAAe;QACpB,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;QAExE,OAAO;YACL,SAAS,EAAE,SAAS;iBACjB,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;iBACvC,QAAQ,EAAE;YACb,UAAU,EAAE,UAAU;iBACnB,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;iBACxC,QAAQ,EAAE;SACd,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAChE,CAAC;IAED,mDAAmD;IACnD,eAAe,CAAC,GAAW;QACzB,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED,gEAAgE;IAChE,IAAI,CAAC,OAAe;QAClB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpF,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,OAAe,EAAE,SAAiB,EAAE,YAAqB;QAC9D,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;QACjF,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,CAAC,MAAM,CAClB,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAC7B,GAAG,EACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CACjC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,KAAK,EAAE,KAAc,EAAE,CAAC,CAAC;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,eAAe;QACb,OAAO,IAAI,CAAC,SAAS;YACnB,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;aACxC,QAAQ,EAAE,CAAC;IAChB,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/** Agent identifier in the form auxiora://user@host */
+export interface AgentIdentifier {
+    user: string;
+    host: string;
+}
+export type AgentMessageType = 'text' | 'request' | 'response' | 'capability_query' | 'capability_response' | 'ping' | 'pong';
+/** A message exchanged between agents. */
+export interface AgentMessage {
+    id: string;
+    from: AgentIdentifier;
+    to: AgentIdentifier;
+    type: AgentMessageType;
+    payload: string;
+    timestamp: number;
+    signature?: string;
+    replyTo?: string;
+}
+/** A capability offered by an agent. */
+export interface AgentCapability {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+/** An entry in the agent directory. */
+export interface AgentDirectoryEntry {
+    identifier: AgentIdentifier;
+    displayName: string;
+    capabilities: AgentCapability[];
+    publicKey: string;
+    endpoint: string;
+    lastSeen: number;
+    registeredAt: number;
+}
+/** Format an AgentIdentifier to its URI form. */
+export declare function formatAgentId(id: AgentIdentifier): string;
+/** Parse an agent URI string to an AgentIdentifier. */
+export declare function parseAgentId(uri: string): AgentIdentifier | undefined;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,SAAS,GACT,UAAU,GACV,kBAAkB,GAClB,qBAAqB,GACrB,MAAM,GACN,MAAM,CAAC;AAEX,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,eAAe,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,eAAe,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAIrE"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** Format an AgentIdentifier to its URI form. */
+export function formatAgentId(id) {
+    return `auxiora://${id.user}@${id.host}`;
+}
+/** Parse an agent URI string to an AgentIdentifier. */
+export function parseAgentId(uri) {
+    const match = uri.match(/^auxiora:\/\/([^@]+)@(.+)$/);
+    if (!match)
+        return undefined;
+    return { user: match[1], host: match[2] };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8CA,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,EAAmB;IAC/C,OAAO,aAAa,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5C,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@auxiora/agent-protocol",
+  "version": "1.0.0",
+  "description": "Agent-to-agent communication protocol with Ed25519 signing and discovery",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auxiora/core": "1.0.0",
+    "@auxiora/audit": "1.0.0",
+    "@auxiora/logger": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/directory.ts

@@ -0,0 +1,112 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getLogger } from '@auxiora/logger';
+import { getAuxioraDir } from '@auxiora/core';
+import type { AgentIdentifier, AgentDirectoryEntry, AgentCapability } from './types.js';
+import { formatAgentId } from './types.js';
+
+const logger = getLogger('agent-protocol:directory');
+
+/**
+ * Directory of known agents for discovery and lookup.
+ */
+export class AgentDirectory {
+  private filePath: string;
+
+  constructor(options?: { dir?: string }) {
+    const dir = options?.dir ?? path.join(getAuxioraDir(), 'agent-protocol');
+    this.filePath = path.join(dir, 'directory.json');
+  }
+
+  async register(
+    identifier: AgentIdentifier,
+    displayName: string,
+    publicKey: string,
+    endpoint: string,
+    capabilities?: AgentCapability[],
+  ): Promise<AgentDirectoryEntry> {
+    const entries = await this.readFile();
+    const uri = formatAgentId(identifier);
+
+    // Update if already registered
+    const existing = entries.find(e => formatAgentId(e.identifier) === uri);
+    if (existing) {
+      existing.displayName = displayName;
+      existing.publicKey = publicKey;
+      existing.endpoint = endpoint;
+      existing.capabilities = capabilities ?? existing.capabilities;
+      existing.lastSeen = Date.now();
+      await this.writeFile(entries);
+      logger.debug('Updated agent registration', { uri });
+      return existing;
+    }
+
+    const entry: AgentDirectoryEntry = {
+      identifier,
+      displayName,
+      capabilities: capabilities ?? [],
+      publicKey,
+      endpoint,
+      lastSeen: Date.now(),
+      registeredAt: Date.now(),
+    };
+
+    entries.push(entry);
+    await this.writeFile(entries);
+    logger.debug('Registered agent', { uri });
+    return entry;
+  }
+
+  async lookup(identifier: AgentIdentifier): Promise<AgentDirectoryEntry | undefined> {
+    const entries = await this.readFile();
+    const uri = formatAgentId(identifier);
+    return entries.find(e => formatAgentId(e.identifier) === uri);
+  }
+
+  async search(query: string): Promise<AgentDirectoryEntry[]> {
+    const entries = await this.readFile();
+    const lowerQuery = query.toLowerCase();
+
+    return entries.filter(e =>
+      e.displayName.toLowerCase().includes(lowerQuery) ||
+      formatAgentId(e.identifier).toLowerCase().includes(lowerQuery) ||
+      e.capabilities.some(c =>
+        c.name.toLowerCase().includes(lowerQuery) ||
+        c.description.toLowerCase().includes(lowerQuery),
+      ),
+    );
+  }
+
+  async remove(identifier: AgentIdentifier): Promise<boolean> {
+    const entries = await this.readFile();
+    const uri = formatAgentId(identifier);
+    const filtered = entries.filter(e => formatAgentId(e.identifier) !== uri);
+    if (filtered.length === entries.length) return false;
+
+    await this.writeFile(filtered);
+    logger.debug('Removed agent', { uri });
+    return true;
+  }
+
+  async listAll(): Promise<AgentDirectoryEntry[]> {
+    return this.readFile();
+  }
+
+  private async readFile(): Promise<AgentDirectoryEntry[]> {
+    try {
+      const content = await fs.readFile(this.filePath, 'utf-8');
+      return JSON.parse(content) as AgentDirectoryEntry[];
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  private async writeFile(entries: AgentDirectoryEntry[]): Promise<void> {
+    const dir = path.dirname(this.filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(this.filePath, JSON.stringify(entries, null, 2), 'utf-8');
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export type {
+  AgentIdentifier,
+  AgentMessage,
+  AgentMessageType,
+  AgentCapability,
+  AgentDirectoryEntry,
+} from './types.js';
+export { formatAgentId, parseAgentId } from './types.js';
+export { AgentProtocol } from './protocol.js';
+export type { MessageHandler } from './protocol.js';
+export { MessageSigner } from './signing.js';
+export type { KeyPair } from './signing.js';
+export { AgentDirectory } from './directory.js';
+export { ProtocolServer } from './server.js';

package/src/protocol.ts

@@ -0,0 +1,145 @@
+import * as crypto from 'node:crypto';
+import { getLogger } from '@auxiora/logger';
+import { audit } from '@auxiora/audit';
+import type { AgentIdentifier, AgentMessage, AgentMessageType } from './types.js';
+import { formatAgentId } from './types.js';
+import type { MessageSigner } from './signing.js';
+import type { AgentDirectory } from './directory.js';
+
+const logger = getLogger('agent-protocol:protocol');
+
+export interface MessageHandler {
+  (message: AgentMessage): Promise<AgentMessage | void>;
+}
+
+/**
+ * Core agent-to-agent protocol. JSON-over-HTTPS messaging
+ * with Ed25519 signature verification.
+ */
+export class AgentProtocol {
+  private identity: AgentIdentifier;
+  private signer: MessageSigner;
+  private directory: AgentDirectory;
+  private handlers = new Map<AgentMessageType, MessageHandler>();
+  private inbox: AgentMessage[] = [];
+  private maxInboxSize = 1000;
+
+  constructor(
+    identity: AgentIdentifier,
+    signer: MessageSigner,
+    directory: AgentDirectory,
+  ) {
+    this.identity = identity;
+    this.signer = signer;
+    this.directory = directory;
+  }
+
+  /** Send a message to another agent. */
+  async send(
+    to: AgentIdentifier,
+    type: AgentMessageType,
+    payload: string,
+    replyTo?: string,
+  ): Promise<AgentMessage> {
+    const message: AgentMessage = {
+      id: `msg-${crypto.randomUUID().slice(0, 8)}`,
+      from: this.identity,
+      to,
+      type,
+      payload,
+      timestamp: Date.now(),
+      replyTo,
+    };
+
+    // Sign the message
+    const signaturePayload = `${message.id}:${message.timestamp}:${message.payload}`;
+    message.signature = this.signer.sign(signaturePayload);
+
+    // Look up the target agent's endpoint
+    const entry = await this.directory.lookup(to);
+    if (!entry) {
+      throw new Error(`Agent not found: ${formatAgentId(to)}`);
+    }
+
+    // Send via HTTPS (in production would use fetch)
+    // For now, store in local outbox for testing
+    logger.debug('Message sent', {
+      to: formatAgentId(to),
+      type,
+      id: message.id,
+    });
+    void audit('agent_protocol.message_sent', {
+      to: formatAgentId(to),
+      type,
+      id: message.id,
+    });
+
+    return message;
+  }
+
+  /** Receive and process an incoming message. */
+  async receive(message: AgentMessage): Promise<AgentMessage | void> {
+    // Verify signature if present
+    if (message.signature) {
+      const senderEntry = await this.directory.lookup(message.from);
+      if (senderEntry) {
+        const signaturePayload = `${message.id}:${message.timestamp}:${message.payload}`;
+        const valid = this.signer.verify(signaturePayload, message.signature, senderEntry.publicKey);
+        if (!valid) {
+          logger.debug('Invalid message signature', { from: formatAgentId(message.from) });
+          throw new Error('Invalid message signature');
+        }
+      }
+    }
+
+    // Store in inbox
+    this.inbox.push(message);
+    if (this.inbox.length > this.maxInboxSize) {
+      this.inbox = this.inbox.slice(-this.maxInboxSize);
+    }
+
+    logger.debug('Message received', {
+      from: formatAgentId(message.from),
+      type: message.type,
+      id: message.id,
+    });
+    void audit('agent_protocol.message_received', {
+      from: formatAgentId(message.from),
+      type: message.type,
+      id: message.id,
+    });
+
+    // Dispatch to handler
+    const handler = this.handlers.get(message.type);
+    if (handler) {
+      return handler(message);
+    }
+  }
+
+  /** Register a handler for a message type. */
+  onMessage(type: AgentMessageType, handler: MessageHandler): void {
+    this.handlers.set(type, handler);
+  }
+
+  /** Discover agents with specific capabilities. */
+  async discover(query: string): Promise<AgentIdentifier[]> {
+    const entries = await this.directory.search(query);
+    return entries.map(e => e.identifier);
+  }
+
+  /** Query another agent's capabilities. */
+  async negotiate(target: AgentIdentifier): Promise<AgentMessage> {
+    return this.send(target, 'capability_query', '');
+  }
+
+  /** Get messages from the inbox. */
+  getInbox(limit?: number): AgentMessage[] {
+    const max = limit ?? 50;
+    return this.inbox.slice(-max);
+  }
+
+  /** Get this agent's identity. */
+  getIdentity(): AgentIdentifier {
+    return this.identity;
+  }
+}

package/src/server.ts

@@ -0,0 +1,66 @@
+import { getLogger } from '@auxiora/logger';
+import type { AgentMessage } from './types.js';
+import type { AgentProtocol } from './protocol.js';
+
+const logger = getLogger('agent-protocol:server');
+
+/**
+ * HTTP endpoint handler for receiving agent messages.
+ * Designed to be mounted on an Express router.
+ */
+export class ProtocolServer {
+  private protocol: AgentProtocol;
+
+  constructor(protocol: AgentProtocol) {
+    this.protocol = protocol;
+  }
+
+  /**
+   * Handle an incoming HTTP request with an agent message.
+   * Returns the response message (if any) or an error.
+   */
+  async handleRequest(body: unknown): Promise<{
+    status: number;
+    body: { success: boolean; response?: AgentMessage; error?: string };
+  }> {
+    if (!body || typeof body !== 'object') {
+      return {
+        status: 400,
+        body: { success: false, error: 'Invalid request body' },
+      };
+    }
+
+    const message = body as AgentMessage;
+
+    if (!message.id || !message.from || !message.to || !message.type || message.payload === undefined) {
+      return {
+        status: 400,
+        body: { success: false, error: 'Missing required message fields' },
+      };
+    }
+
+    try {
+      const response = await this.protocol.receive(message);
+
+      return {
+        status: 200,
+        body: {
+          success: true,
+          ...(response ? { response } : {}),
+        },
+      };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      logger.debug('Failed to handle agent message', { error: error as Error });
+      return {
+        status: 400,
+        body: { success: false, error: msg },
+      };
+    }
+  }
+
+  /** Get the protocol instance. */
+  getProtocol(): AgentProtocol {
+    return this.protocol;
+  }
+}

package/src/signing.ts

@@ -0,0 +1,85 @@
+import * as crypto from 'node:crypto';
+import { getLogger } from '@auxiora/logger';
+
+const logger = getLogger('agent-protocol:signing');
+
+export interface KeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+
+/**
+ * Ed25519-based message signing and verification for agent-to-agent communication.
+ */
+export class MessageSigner {
+  private publicKey: crypto.KeyObject | undefined;
+  private privateKey: crypto.KeyObject | undefined;
+
+  constructor(keyPair?: KeyPair) {
+    if (keyPair) {
+      this.importKeys(keyPair);
+    }
+  }
+
+  /** Generate a new Ed25519 key pair. */
+  static generateKeyPair(): KeyPair {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+
+    return {
+      publicKey: publicKey
+        .export({ type: 'spki', format: 'pem' })
+        .toString(),
+      privateKey: privateKey
+        .export({ type: 'pkcs8', format: 'pem' })
+        .toString(),
+    };
+  }
+
+  /** Import keys from PEM strings. */
+  importKeys(keyPair: KeyPair): void {
+    this.publicKey = crypto.createPublicKey(keyPair.publicKey);
+    this.privateKey = crypto.createPrivateKey(keyPair.privateKey);
+  }
+
+  /** Import only a public key (for verification). */
+  importPublicKey(pem: string): void {
+    this.publicKey = crypto.createPublicKey(pem);
+  }
+
+  /** Sign a message payload. Returns base64-encoded signature. */
+  sign(payload: string): string {
+    if (!this.privateKey) {
+      throw new Error('Private key not available for signing');
+    }
+
+    const signature = crypto.sign(null, Buffer.from(payload, 'utf-8'), this.privateKey);
+    return signature.toString('base64');
+  }
+
+  /** Verify a signature against a payload. */
+  verify(payload: string, signature: string, publicKeyPem?: string): boolean {
+    const key = publicKeyPem ? crypto.createPublicKey(publicKeyPem) : this.publicKey;
+    if (!key) {
+      throw new Error('Public key not available for verification');
+    }
+
+    try {
+      return crypto.verify(
+        null,
+        Buffer.from(payload, 'utf-8'),
+        key,
+        Buffer.from(signature, 'base64'),
+      );
+    } catch (error) {
+      logger.debug('Signature verification failed', { error: error as Error });
+      return false;
+    }
+  }
+
+  /** Get the public key PEM string. */
+  getPublicKeyPem(): string | undefined {
+    return this.publicKey
+      ?.export({ type: 'spki', format: 'pem' })
+      .toString();
+  }
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+/** Agent identifier in the form auxiora://user@host */
+export interface AgentIdentifier {
+  user: string;
+  host: string;
+}
+
+export type AgentMessageType =
+  | 'text'
+  | 'request'
+  | 'response'
+  | 'capability_query'
+  | 'capability_response'
+  | 'ping'
+  | 'pong';
+
+/** A message exchanged between agents. */
+export interface AgentMessage {
+  id: string;
+  from: AgentIdentifier;
+  to: AgentIdentifier;
+  type: AgentMessageType;
+  payload: string;
+  timestamp: number;
+  signature?: string;
+  replyTo?: string;
+}
+
+/** A capability offered by an agent. */
+export interface AgentCapability {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+/** An entry in the agent directory. */
+export interface AgentDirectoryEntry {
+  identifier: AgentIdentifier;
+  displayName: string;
+  capabilities: AgentCapability[];
+  publicKey: string;
+  endpoint: string;
+  lastSeen: number;
+  registeredAt: number;
+}
+
+/** Format an AgentIdentifier to its URI form. */
+export function formatAgentId(id: AgentIdentifier): string {
+  return `auxiora://${id.user}@${id.host}`;
+}
+
+/** Parse an agent URI string to an AgentIdentifier. */
+export function parseAgentId(uri: string): AgentIdentifier | undefined {
+  const match = uri.match(/^auxiora:\/\/([^@]+)@(.+)$/);
+  if (!match) return undefined;
+  return { user: match[1], host: match[2] };
+}