@useconductor/conductor 1.0.0

package/src/plugins/manager.ts

@@ -0,0 +1,213 @@
+import { Conductor } from '../core/conductor.js';
+export type { ToolContext } from '../core/interfaces.js';
+
+export interface Plugin {
+  name: string;
+  description: string;
+  version: string;
+  initialize(conductor: Conductor): Promise<void>;
+  isConfigured(): boolean;
+  getTools(): PluginTool[];
+  configSchema?: PluginConfigSchema;
+  /** Optional: return a short context string for the proactive reasoning cycle. */
+  getContext?(): Promise<string | null>;
+}
+
+export interface PluginConfigSchema {
+  fields: {
+    key: string;
+    label: string;
+    type: 'string' | 'password' | 'number' | 'boolean';
+    description?: string;
+    required: boolean;
+    secret?: boolean; // If true, stored in Keychain instead of config.json
+    service?: string; // For secret fields, the Keychain service name
+  }[];
+  setupInstructions?: string;
+}
+
+/** The canonical input type for all tool handlers at runtime. */
+export type ToolInput = Record<string, unknown>;
+/** Tool handlers should return a string or a plain-object result. */
+export type ToolOutput = string | Record<string, unknown>;
+
+export interface PluginTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handler: (input: any) => Promise<any>;
+  requiresApproval?: boolean;
+}
+
+export interface PluginStatus {
+  name: string;
+  status: 'ready' | 'not_configured' | 'init_failed' | 'disabled';
+  toolCount: number;
+  error?: string;
+  setupCommand?: string;
+}
+
+export class PluginManager {
+  private conductor: Conductor;
+  private plugins: Map<string, Plugin> = new Map();
+  private initializedPlugins: Set<string> = new Set();
+  private initErrors: Map<string, string> = new Map();
+
+  constructor(conductor: Conductor) {
+    this.conductor = conductor;
+  }
+
+  /** Register a plugin without initializing it. */
+  registerPlugin(plugin: Plugin): void {
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  /** Load all builtin plugins (register only, no init). */
+  async loadBuiltins(): Promise<void> {
+    const builtins = await import('./builtin/index.js');
+    for (const plugin of builtins.getAllBuiltinPlugins()) {
+      this.registerPlugin(plugin);
+    }
+  }
+
+  /** Get a plugin by name. Lazily initializes on first use. */
+  async getPlugin(name: string): Promise<Plugin | undefined> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return undefined;
+
+    if (!this.initializedPlugins.has(name)) {
+      try {
+        await plugin.initialize(this.conductor);
+        this.initializedPlugins.add(name);
+        this.initErrors.delete(name);
+      } catch (error: any) {
+        const msg: string = error.message ?? String(error);
+        this.initErrors.set(name, msg);
+        process.stderr.write(`[conductor] ✗ ${name}: init failed — ${msg}\n`);
+        process.stderr.write(`[conductor]   → Run: conductor doctor ${name}\n`);
+        return undefined;
+      }
+    }
+
+    return plugin;
+  }
+
+  /** Get the recorded init error for a plugin, if any. */
+  getInitError(name: string): string | undefined {
+    return this.initErrors.get(name);
+  }
+
+  /**
+   * Probe all enabled plugins and return a status summary.
+   * Used by the MCP startup summary and conductor doctor.
+   */
+  async getStatusSummary(): Promise<PluginStatus[]> {
+    const enabledNames = this.conductor.getConfig().get<string[]>('plugins.enabled') ?? [];
+    const statuses: PluginStatus[] = [];
+
+    for (const name of enabledNames) {
+      const plugin = this.plugins.get(name);
+      if (!plugin) {
+        statuses.push({ name, status: 'disabled', toolCount: 0 });
+        continue;
+      }
+
+      if (!plugin.isConfigured()) {
+        statuses.push({
+          name,
+          status: 'not_configured',
+          toolCount: 0,
+          setupCommand: `conductor plugins setup ${name}`,
+        });
+        continue;
+      }
+
+      // Attempt init if not done yet
+      if (!this.initializedPlugins.has(name)) {
+        await this.getPlugin(name);
+      }
+
+      const err = this.initErrors.get(name);
+      if (err) {
+        statuses.push({ name, status: 'init_failed', toolCount: 0, error: err });
+      } else {
+        const toolCount = plugin.getTools().length;
+        statuses.push({ name, status: 'ready', toolCount });
+      }
+    }
+
+    return statuses;
+  }
+
+  /** List all registered plugins. Does NOT initialize them. */
+  listPlugins(): Array<{
+    name: string;
+    description: string;
+    version: string;
+    enabled: boolean;
+    configSchema?: PluginConfigSchema;
+  }> {
+    const enabledPlugins = this.conductor.getConfig().get<string[]>('plugins.enabled') || [];
+
+    return Array.from(this.plugins.values()).map((plugin) => ({
+      name: plugin.name,
+      description: plugin.description,
+      version: plugin.version,
+      enabled: enabledPlugins.includes(plugin.name),
+      configSchema: plugin.configSchema,
+    }));
+  }
+
+  isPluginEnabled(name: string): boolean {
+    const enabled = this.conductor.getConfig().get<string[]>('plugins.enabled') || [];
+    return enabled.includes(name);
+  }
+
+  async enablePlugin(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) throw new Error(`Plugin not found: ${name}`);
+
+    // Initialize to verify it works
+    if (!this.initializedPlugins.has(name)) {
+      try {
+        await plugin.initialize(this.conductor);
+        this.initializedPlugins.add(name);
+      } catch (error: any) {
+        throw new Error(`Failed to enable plugin "${name}": initialization failed: ${error.message}`);
+      }
+    }
+
+    const enabled = this.conductor.getConfig().get<string[]>('plugins.enabled') || [];
+    if (!enabled.includes(name)) {
+      enabled.push(name);
+      await this.conductor.getConfig().set('plugins.enabled', enabled);
+    }
+  }
+
+  async disablePlugin(name: string): Promise<void> {
+    const enabled = this.conductor.getConfig().get<string[]>('plugins.enabled') || [];
+    const filtered = enabled.filter((p) => p !== name);
+    await this.conductor.getConfig().set('plugins.enabled', filtered);
+    this.initializedPlugins.delete(name);
+  }
+
+  /** Get MCP tools from enabled plugins only. */
+  async getEnabledTools(): Promise<PluginTool[]> {
+    const tools: PluginTool[] = [];
+    const enabledNames = this.conductor.getConfig().get<string[]>('plugins.enabled') || [];
+
+    for (const name of enabledNames) {
+      try {
+        const plugin = await this.getPlugin(name);
+        if (plugin) {
+          tools.push(...plugin.getTools());
+        }
+      } catch (error: any) {
+        process.stderr.write(`Warning: plugin "${name}" failed to load: ${error.message}\n`);
+      }
+    }
+
+    return tools;
+  }
+}

package/src/plugins/validation.ts

@@ -0,0 +1,94 @@
+/**
+ * Zod validation wrapper for plugin tool handlers.
+ *
+ * Every tool handler input is validated against its inputSchema before execution.
+ * Invalid inputs are rejected with clear error messages — no silent failures,
+ * no `any` types slipping through.
+ */
+
+import { z } from 'zod';
+import type { PluginTool } from './manager.js';
+
+/**
+ * Convert an MCP-style JSON Schema inputSchema to a Zod schema.
+ * This validates tool inputs at runtime before they reach the handler.
+ */
+function schemaFromInputSchema(schema: Record<string, unknown>): z.ZodType {
+  if (schema.type !== 'object') {
+    return z.unknown();
+  }
+
+  const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  const required = new Set<string>((schema.required as string[]) ?? []);
+  const shape: Record<string, z.ZodType> = {};
+
+  for (const [key, propSchema] of Object.entries(properties)) {
+    let fieldSchema: z.ZodType;
+
+    switch (propSchema.type) {
+      case 'string':
+        fieldSchema = z.string();
+        if (propSchema.enum) {
+          fieldSchema = z.enum(propSchema.enum as [string, ...string[]]);
+        }
+        break;
+      case 'number':
+      case 'integer':
+        fieldSchema = z.number();
+        break;
+      case 'boolean':
+        fieldSchema = z.boolean();
+        break;
+      case 'array':
+        fieldSchema = z.array(
+          (propSchema.items as { type?: string })?.type === 'string'
+            ? z.string()
+            : (propSchema.items as { type?: string })?.type === 'number'
+              ? z.number()
+              : z.unknown(),
+        );
+        break;
+      case 'object':
+        fieldSchema = z.record(z.string(), z.unknown());
+        break;
+      default:
+        fieldSchema = z.unknown();
+    }
+
+    if (propSchema.description) {
+      fieldSchema = fieldSchema.describe(propSchema.description as string);
+    }
+
+    shape[key] = required.has(key) ? fieldSchema : fieldSchema.optional();
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Wrap a plugin tool with Zod validation.
+ * Returns a new tool whose handler validates input before execution.
+ */
+export function withValidation(tool: PluginTool): PluginTool {
+  const validator = schemaFromInputSchema(tool.inputSchema);
+
+  return {
+    ...tool,
+    handler: async (input: unknown) => {
+      const result = validator.safeParse(input);
+      if (!result.success) {
+        const errors = result.error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
+        throw new Error(`Invalid input for tool "${tool.name}": ${errors}`);
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return tool.handler(result.data as any);
+    },
+  };
+}
+
+/**
+ * Wrap an array of plugin tools with Zod validation.
+ */
+export function validateTools(tools: PluginTool[]): PluginTool[] {
+  return tools.map(withValidation);
+}

package/src/security/README.md

@@ -0,0 +1,12 @@
+# src/security
+
+Security layer for Conductor — authentication, keychain management, and credential encryption.
+
+## Contents
+
+- `keychain.ts` - OS keychain integration for secret storage
+- `auth.ts` - Authentication and authorization utilities
+
+## Architecture
+
+Secret credentials are AES-256-GCM encrypted with a machine-bound key. The keychain stores secrets in the OS keychain rather than `config.json`. All HTTP endpoints are protected by `express-rate-limit`. The shell plugin uses a whitelist allowlist — no `eval()` or `exec()`.

package/src/security/auth.ts

@@ -0,0 +1,72 @@
+import crypto from 'crypto';
+
+export interface VerificationCode {
+  code: string;
+  userId?: number;
+  expiresAt: Date;
+  used: boolean;
+}
+
+export class AuthManager {
+  private codes: Map<string, VerificationCode> = new Map();
+
+  /**
+   * Generate a verification code like: CX-8F2K-9L4P
+   */
+  generateVerificationCode(): string {
+    const part1 = this.randomString(2);
+    const part2 = this.randomString(4);
+    const part3 = this.randomString(4);
+
+    const code = `${part1}-${part2}-${part3}`.toUpperCase();
+
+    // Store with 5-minute expiry
+    this.codes.set(code, {
+      code,
+      expiresAt: new Date(Date.now() + 5 * 60 * 1000),
+      used: false,
+    });
+
+    return code;
+  }
+
+  /**
+   * Verify a code and mark it as used.
+   */
+  verifyCode(code: string, userId: number): boolean {
+    const storedCode = this.codes.get(code.toUpperCase());
+
+    if (!storedCode) return false;
+    if (storedCode.used) return false;
+    if (storedCode.expiresAt < new Date()) return false;
+
+    storedCode.used = true;
+    storedCode.userId = userId;
+
+    return true;
+  }
+
+  /**
+   * Clean up expired codes.
+   */
+  cleanupExpiredCodes(): void {
+    const now = new Date();
+    for (const [code, data] of this.codes.entries()) {
+      if (data.expiresAt < now) {
+        this.codes.delete(code);
+      }
+    }
+  }
+
+  private randomString(length: number): string {
+    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Exclude ambiguous chars
+    let result = '';
+    const bytes = crypto.randomBytes(length);
+
+    for (let i = 0; i < length; i++) {
+      result += chars[bytes[i] % chars.length];
+    }
+
+    return result;
+  }
+}

package/src/security/keychain.ts

@@ -0,0 +1,226 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import { readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { execSync } from 'child_process';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Keychain — encrypted credential storage.
+ *
+ * Supports two formats:
+ *   v2  — AES-256-GCM with machine-specific key derivation (written by install.sh)
+ *   v1  — AES-256-CBC legacy format (written by older versions)
+ *
+ * New writes always use the v2 format.
+ */
+export class Keychain {
+  private keychainDir: string;
+  private masterKey: Buffer;
+
+  constructor(configDir: string) {
+    this.keychainDir = path.join(configDir, 'keychain');
+    this.masterKey = this.deriveMasterKey();
+  }
+
+  /**
+   * Derive a machine-specific master key.
+   * Matches the install.sh derivation so credentials saved by either
+   * the installer or the app are interchangeable.
+   */
+  private deriveMasterKey(): Buffer {
+    const machineSecret = this.getMachineSecret();
+    const salt = crypto.createHash('sha256').update('conductor:keychain:v1').digest();
+    return crypto.scryptSync(machineSecret, salt, 32, { N: 16384, r: 8, p: 1 });
+  }
+
+  /**
+   * Get a machine-specific secret for key derivation.
+   * Mirrors the logic in install.sh's save_cred function.
+   */
+  private getMachineSecret(): string {
+    // Linux: /etc/machine-id or /var/lib/dbus/machine-id
+    const linuxSources = ['/etc/machine-id', '/var/lib/dbus/machine-id', '/proc/sys/kernel/random/boot_id'];
+
+    for (const src of linuxSources) {
+      try {
+        const data = readFileSync(src, 'utf8').trim();
+        if (data) return data;
+      } catch {
+        // Not available on this platform
+      }
+    }
+
+    // macOS: IOPlatformUUID
+    if (process.platform === 'darwin') {
+      try {
+        const out = execSync("ioreg -rd1 -c IOPlatformExpertDevice | awk '/IOPlatformUUID/{print $NF}'", {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+          .trim()
+          .replace(/"/g, '');
+        if (out) return out;
+      } catch {
+        // ioreg not available
+      }
+    }
+
+    // Windows: MachineGuid from registry
+    if (process.platform === 'win32') {
+      try {
+        const out = execSync('reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const match = out.match(/MachineGuid\s+REG_SZ\s+(.+)/);
+        if (match?.[1]?.trim()) return match[1].trim();
+      } catch {
+        // Registry not accessible
+      }
+    }
+
+    // Persistent fallback: Save a random UUID to a file if hardware IDs fail.
+    // This is safer than hostname which can change.
+    const fallbackPath = path.join(this.keychainDir, 'machine_secret');
+    try {
+      if (readFileSync(fallbackPath, 'utf8').trim()) {
+        return readFileSync(fallbackPath, 'utf8').trim();
+      }
+    } catch {
+      try {
+        const secret = crypto.randomUUID();
+        // Use synchronous write since this is inside deriveMasterKey constructor path
+        mkdirSync(this.keychainDir, { recursive: true, mode: 0o700 });
+        writeFileSync(fallbackPath, secret, { mode: 0o600 });
+        return secret;
+      } catch {
+        // Absolute last resort
+        return os.hostname();
+      }
+    }
+
+    return os.hostname();
+  }
+
+  /**
+   * Store an encrypted credential (v2 format: AES-256-GCM).
+   */
+  async set(service: string, key: string, value: string): Promise<void> {
+    await fs.mkdir(this.keychainDir, { recursive: true, mode: 0o700 });
+    // Enforce 0700 permissions in case dir already existed with wrong perms
+    await fs.chmod(this.keychainDir, 0o700).catch(() => {});
+
+    const iv = crypto.randomBytes(12); // 96-bit IV for GCM
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.masterKey, iv);
+
+    let encrypted = cipher.update(value, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const tag = cipher.getAuthTag().toString('hex');
+
+    // Format: v2:iv:tag:ciphertext
+    const result = ['v2', iv.toString('hex'), tag, encrypted].join(':');
+
+    const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+    await fs.writeFile(filepath, result, { mode: 0o600 });
+  }
+
+  /**
+   * Retrieve and decrypt a credential.
+   * Handles both v2 (GCM) and legacy v1 (CBC) formats.
+   */
+  async get(service: string, key: string): Promise<string | null> {
+    try {
+      const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+      const data = await fs.readFile(filepath, 'utf-8');
+      return this.decrypt(data.trim());
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Delete a credential.
+   */
+  async delete(service: string, key: string): Promise<void> {
+    const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+    try {
+      await fs.unlink(filepath);
+    } catch {
+      // File doesn't exist — that's fine
+    }
+  }
+
+  /**
+   * Check if a credential exists.
+   */
+  async has(service: string, key: string): Promise<boolean> {
+    try {
+      const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+      await fs.access(filepath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List all credential keys for a service.
+   */
+  async list(service: string): Promise<string[]> {
+    try {
+      const files = await fs.readdir(this.keychainDir);
+      return files
+        .filter((f) => f.startsWith(`${service}.`) && f.endsWith('.enc'))
+        .map((f) => f.replace(`${service}.`, '').replace('.enc', ''));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Decrypt a stored value, auto-detecting format version.
+   */
+  private decrypt(stored: string): string {
+    const parts = stored.split(':');
+
+    if (parts[0] === 'v2' && parts.length === 4) {
+      // v2: AES-256-GCM — iv:tag:ciphertext
+      return this.decryptGCM(parts[1], parts[2], parts[3]);
+    }
+
+    if (parts.length === 2) {
+      // Legacy v1: AES-256-CBC — iv:ciphertext (no version prefix)
+      return this.decryptCBC(parts[0], parts[1]);
+    }
+
+    throw new Error('Unrecognized credential format');
+  }
+
+  /**
+   * AES-256-GCM decryption (v2 format, matches install.sh).
+   */
+  private decryptGCM(ivHex: string, tagHex: string, cipherHex: string): string {
+    const iv = Buffer.from(ivHex, 'hex');
+    const tag = Buffer.from(tagHex, 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', this.masterKey, iv);
+    decipher.setAuthTag(tag);
+
+    let decrypted = decipher.update(cipherHex, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  }
+
+  /**
+   * AES-256-CBC decryption (legacy v1 format).
+   * Kept for backward-compat with credentials written before the v2 migration.
+   */
+  private decryptCBC(ivHex: string, cipherHex: string): string {
+    const iv = Buffer.from(ivHex, 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-cbc', this.masterKey, iv);
+
+    let decrypted = decipher.update(cipherHex, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  }
+}

package/src/utils/README.md

@@ -0,0 +1,12 @@
+# src/utils
+
+Shared utility functions used across the Conductor codebase.
+
+## Contents
+
+- `google-auth.ts` - Google OAuth authentication helpers
+- `retry.ts` - Generic retry logic utilities
+
+## Architecture
+
+These are cross-cutting utilities consumed by multiple modules. `google-auth.ts` is used by Google Workspace plugins (GCal, GDrive, Gmail). `retry.ts` provides reusable retry logic complementary to the core retry module.