signalwire-agents 0.1.0

package/src/AgentServer.ts

@@ -0,0 +1,149 @@
+/**
+ * AgentServer - Hosts multiple AgentBase instances under a single HTTP server.
+ *
+ * Each agent is mounted at its own route prefix. The root `/` lists all
+ * registered agents, and `/health` + `/ready` are global health checks.
+ */
+
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { AgentBase } from './AgentBase.js';
+import { getLogger } from './Logger.js';
+
+/** Multi-agent HTTP server that hosts multiple AgentBase instances on distinct route prefixes. */
+export class AgentServer {
+  /** Hostname the server binds to. */
+  host: string;
+  /** Port the server listens on. */
+  port: number;
+  private agents: Map<string, AgentBase> = new Map();
+  private _app: Hono;
+  private log = getLogger('AgentServer');
+
+  /**
+   * Create an AgentServer.
+   * @param opts - Optional host and port overrides; defaults to 0.0.0.0:3000.
+   */
+  constructor(opts?: { host?: string; port?: number }) {
+    this.host = opts?.host ?? '0.0.0.0';
+    this.port = opts?.port ?? parseInt(process.env['PORT'] ?? '3000', 10);
+    this._app = new Hono();
+
+    // Security headers
+    this._app.use('*', async (c, next) => {
+      await next();
+      c.res.headers.set('X-Content-Type-Options', 'nosniff');
+      c.res.headers.set('X-Frame-Options', 'DENY');
+      c.res.headers.set('X-XSS-Protection', '1; mode=block');
+      c.res.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+    });
+
+    // CORS
+    this._app.use('*', cors({ origin: '*', credentials: true }));
+
+    // Global health endpoints
+    this._app.get('/health', (c) => c.json({ status: 'ok' }));
+    this._app.get('/ready', (c) => c.json({ status: 'ready' }));
+  }
+
+  /**
+   * Register an agent at the given route prefix.
+   * @param agent - The AgentBase instance to mount.
+   * @param route - Route prefix; defaults to the agent's own route or '/'.
+   * @throws If the route is already occupied by another agent.
+   */
+  register(agent: AgentBase, route?: string): void {
+    let r = route ?? (agent as any).route ?? '/';
+    if (!r.startsWith('/')) r = `/${r}`;
+    r = r.replace(/\/+$/, '') || '/';
+
+    if (this.agents.has(r)) {
+      throw new Error(`Route '${r}' is already in use`);
+    }
+
+    this.agents.set(r, agent);
+
+    // Mount the agent's Hono app at the route prefix
+    const agentApp = agent.getApp();
+    if (r === '/') {
+      this._app.route('/', agentApp);
+    } else {
+      this._app.route(r, agentApp);
+    }
+
+    this.log.info(`Registered '${agent.name}' at ${r}`);
+  }
+
+  /**
+   * Remove an agent registration by route.
+   * @param route - The route prefix to unregister.
+   */
+  unregister(route: string): void {
+    this.agents.delete(route);
+    // Note: Hono doesn't support dynamic route removal,
+    // but the agent won't be listed anymore
+  }
+
+  /**
+   * Get all registered agents keyed by their route prefix.
+   * @returns A map of route prefixes to AgentBase instances.
+   */
+  getAgents(): Map<string, AgentBase> {
+    return this.agents;
+  }
+
+  /**
+   * Look up a registered agent by its route prefix.
+   * @param route - The route prefix to look up.
+   * @returns The agent at that route, or undefined if none is registered.
+   */
+  getAgent(route: string): AgentBase | undefined {
+    return this.agents.get(route);
+  }
+
+  /**
+   * Build and return the Hono application with all registered agents and a root listing endpoint.
+   * @returns The fully configured Hono app.
+   */
+  getApp(): Hono {
+    // Add root listing (registered after agents so it doesn't shadow them)
+    const listing = [...this.agents.entries()].map(([route, agent]) => ({
+      name: agent.name,
+      route,
+    }));
+
+    // We create a response for the root that lists agents
+    // Only if no agent is mounted at /
+    if (!this.agents.has('/')) {
+      this._app.get('/', (c) =>
+        c.json({
+          service: 'SignalWire AI Agents',
+          agents: listing,
+        }),
+      );
+    }
+
+    return this._app;
+  }
+
+  /**
+   * Start the HTTP server and begin listening for requests.
+   * @param host - Override the configured hostname.
+   * @param port - Override the configured port.
+   */
+  async run(host?: string, port?: number): Promise<void> {
+    const { serve } = await import('@hono/node-server');
+    const h = host ?? this.host;
+    const p = port ?? this.port;
+
+    const app = this.getApp();
+
+    this.log.info(`Starting on http://${h}:${p}`);
+    for (const [route, agent] of this.agents) {
+      const [user] = agent.getBasicAuthCredentials();
+      this.log.info(`  ${route} -> ${agent.name} (auth: ${user}:****)`);
+    }
+
+    serve({ fetch: app.fetch, port: p, hostname: h });
+  }
+}

package/src/AuthHandler.ts

@@ -0,0 +1,141 @@
+/**
+ * AuthHandler - Multi-method authentication handler.
+ *
+ * Supports Bearer token, API key, and Basic auth with constant-time comparison.
+ * Can be used as Hono middleware or standalone validator.
+ */
+
+import { timingSafeEqual, randomBytes } from 'node:crypto';
+
+/** Configuration for one or more authentication methods checked by {@link AuthHandler}. */
+export interface AuthConfig {
+  /** Bearer token matched against the Authorization header. */
+  bearerToken?: string;
+  /** API key matched against the X-Api-Key header. */
+  apiKey?: string;
+  /** Basic auth credentials as a [username, password] tuple. */
+  basicAuth?: [string, string];
+  /** Custom validator function; return true to allow the request. */
+  customValidator?: (request: { headers: Record<string, string>; method: string; url: string }) => boolean | Promise<boolean>;
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+function safeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Compare against a dummy to prevent length-based timing leaks
+    const dummy = randomBytes(a.length).toString('hex');
+    timingSafeEqual(Buffer.from(dummy), Buffer.from(dummy));
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+/** Multi-method authentication handler with timing-safe credential comparison. */
+export class AuthHandler {
+  private config: AuthConfig;
+
+  /**
+   * Create a new AuthHandler.
+   * @param config - Authentication configuration specifying one or more auth methods.
+   */
+  constructor(config: AuthConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Validate request headers against configured auth methods (Bearer, API Key, Basic, Custom) in order.
+   * @param headers - The request headers as a string-keyed record.
+   * @returns True if any configured method accepts the request, or if no methods are configured.
+   */
+  async validate(headers: Record<string, string>): Promise<boolean> {
+    // 1. Bearer token
+    if (this.config.bearerToken) {
+      const authHeader = headers['authorization'] || headers['Authorization'] || '';
+      if (authHeader.startsWith('Bearer ')) {
+        const token = authHeader.slice(7);
+        if (safeCompare(token, this.config.bearerToken)) return true;
+      }
+    }
+
+    // 2. API Key
+    if (this.config.apiKey) {
+      const key = headers['x-api-key'] || headers['X-Api-Key'] || '';
+      if (key && safeCompare(key, this.config.apiKey)) return true;
+    }
+
+    // 3. Basic auth
+    if (this.config.basicAuth) {
+      const authHeader = headers['authorization'] || headers['Authorization'] || '';
+      if (authHeader.startsWith('Basic ')) {
+        const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+        const colonIdx = decoded.indexOf(':');
+        if (colonIdx > 0) {
+          const user = decoded.slice(0, colonIdx);
+          const pass = decoded.slice(colonIdx + 1);
+          const [expectedUser, expectedPass] = this.config.basicAuth;
+          if (safeCompare(user, expectedUser) && safeCompare(pass, expectedPass)) return true;
+        }
+      }
+    }
+
+    // 4. Custom validator
+    if (this.config.customValidator) {
+      const result = await this.config.customValidator({
+        headers,
+        method: '',
+        url: '',
+      });
+      if (result) return true;
+    }
+
+    // If no methods configured, allow (backwards compat)
+    if (!this.config.bearerToken && !this.config.apiKey && !this.config.basicAuth && !this.config.customValidator) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Create a Hono-compatible middleware that rejects unauthorized requests with a 401 response.
+   * @returns A middleware function suitable for use with Hono's `app.use()`.
+   */
+  middleware(): (c: any, next: () => Promise<void>) => Promise<Response | void> {
+    return async (c: any, next: () => Promise<void>) => {
+      const headers: Record<string, string> = {};
+      c.req.raw.headers.forEach((v: string, k: string) => { headers[k] = v; });
+
+      const valid = await this.validate(headers);
+      if (!valid) {
+        return c.json({ error: 'Unauthorized' }, 401);
+      }
+      await next();
+    };
+  }
+
+  /**
+   * Check whether Bearer token authentication is configured.
+   * @returns True if a bearer token has been set.
+   */
+  hasBearerAuth(): boolean {
+    return !!this.config.bearerToken;
+  }
+
+  /**
+   * Check whether API key authentication is configured.
+   * @returns True if an API key has been set.
+   */
+  hasApiKeyAuth(): boolean {
+    return !!this.config.apiKey;
+  }
+
+  /**
+   * Check whether Basic authentication is configured.
+   * @returns True if basic auth credentials have been set.
+   */
+  hasBasicAuth(): boolean {
+    return !!this.config.basicAuth;
+  }
+}

package/src/ConfigLoader.ts

@@ -0,0 +1,165 @@
+/**
+ * ConfigLoader - JSON config file loader with env var interpolation.
+ *
+ * Supports ${VAR|default} syntax for env var substitution and
+ * dot-notation access for nested values.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const ENV_VAR_PATTERN = /\$\{([^}|]+)(?:\|([^}]*))?\}/g;
+
+/** JSON configuration file loader with environment variable interpolation and dot-notation access. */
+export class ConfigLoader {
+  private data: Record<string, unknown> = {};
+  private filePath: string | null = null;
+
+  /**
+   * Create a new ConfigLoader, optionally loading a JSON file immediately.
+   * @param filePath - Path to a JSON config file to load on construction.
+   */
+  constructor(filePath?: string) {
+    if (filePath) {
+      this.load(filePath);
+    }
+  }
+
+  /**
+   * Load configuration from a JSON file, performing `${VAR|default}` env var interpolation on the raw text.
+   * @param filePath - Path to the JSON config file.
+   * @returns This instance for chaining.
+   */
+  load(filePath: string): this {
+    const absPath = resolve(filePath);
+    if (!existsSync(absPath)) {
+      throw new Error(`Config file not found: ${absPath}`);
+    }
+    const raw = readFileSync(absPath, 'utf-8');
+    const interpolated = this.interpolateEnvVars(raw);
+    this.data = JSON.parse(interpolated);
+    this.filePath = absPath;
+    return this;
+  }
+
+  /**
+   * Search for a config file in standard locations (CWD, `./config`, `$HOME/.signalwire`).
+   * @param filename - The config file name to search for.
+   * @returns A loaded ConfigLoader if found, or null if the file does not exist in any search path.
+   */
+  static search(filename: string): ConfigLoader | null {
+    const searchPaths = [
+      process.cwd(),
+      join(process.cwd(), 'config'),
+      join(process.env['HOME'] ?? '', '.signalwire'),
+    ];
+
+    for (const dir of searchPaths) {
+      const filePath = join(dir, filename);
+      if (existsSync(filePath)) {
+        return new ConfigLoader(filePath);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Retrieve a configuration value using a dot-notation path (e.g. `'server.port'`).
+   * @param path - Dot-separated key path into the config object.
+   * @param defaultValue - Value returned when the path does not exist.
+   * @returns The resolved value, or defaultValue if not found.
+   */
+  get<T = unknown>(path: string, defaultValue?: T): T {
+    const parts = path.split('.');
+    let current: unknown = this.data;
+
+    for (const part of parts) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return defaultValue as T;
+      }
+      current = (current as Record<string, unknown>)[part];
+    }
+
+    return (current !== undefined ? current : defaultValue) as T;
+  }
+
+  /**
+   * Set a configuration value at the given dot-notation path, creating intermediate objects as needed.
+   * @param path - Dot-separated key path into the config object.
+   * @param value - The value to store.
+   * @returns This instance for chaining.
+   */
+  set(path: string, value: unknown): this {
+    const parts = path.split('.');
+    let current: Record<string, unknown> = this.data;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+        current[part] = {};
+      }
+      current = current[part] as Record<string, unknown>;
+    }
+
+    current[parts[parts.length - 1]] = value;
+    return this;
+  }
+
+  /**
+   * Check whether a dot-notation path exists in the loaded configuration.
+   * @param path - Dot-separated key path to check.
+   * @returns True if the path resolves to a defined value.
+   */
+  has(path: string): boolean {
+    const parts = path.split('.');
+    let current: unknown = this.data;
+
+    for (const part of parts) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return false;
+      }
+      if (!(part in (current as Record<string, unknown>))) return false;
+      current = (current as Record<string, unknown>)[part];
+    }
+    return true;
+  }
+
+  /**
+   * Return a shallow copy of the entire configuration object.
+   * @returns A copy of the top-level config data.
+   */
+  getAll(): Record<string, unknown> {
+    return { ...this.data };
+  }
+
+  /**
+   * Return the absolute path of the loaded config file, if any.
+   * @returns The file path, or null if config was loaded from an object.
+   */
+  getFilePath(): string | null {
+    return this.filePath;
+  }
+
+  /**
+   * Load configuration from a plain object instead of a file, useful for testing or programmatic setup.
+   * @param obj - The configuration object to use.
+   * @returns This instance for chaining.
+   */
+  loadFromObject(obj: Record<string, unknown>): this {
+    this.data = { ...obj };
+    this.filePath = null;
+    return this;
+  }
+
+  /**
+   * Interpolate ${VAR|default} patterns in a string.
+   */
+  private interpolateEnvVars(input: string): string {
+    return input.replace(ENV_VAR_PATTERN, (_match, varName: string, defaultValue?: string) => {
+      const envVal = process.env[varName.trim()];
+      if (envVal !== undefined) return envVal;
+      if (defaultValue !== undefined) return defaultValue;
+      return '';
+    });
+  }
+}