@useconductor/conductor 1.0.0

package/src/core/rbac.ts

@@ -0,0 +1,321 @@
+/**
+ * RBAC — Role-Based Access Control foundation for multi-user Conductor.
+ *
+ * Provides role definitions, permission checks, user management, and
+ * persistence. Designed to be plugged into the MCP server's tool routing
+ * so every tool call is authorized before execution.
+ *
+ * Default roles:
+ *   admin            — full access to all resources and actions
+ *   editor           — create / read / update / execute (no delete)
+ *   viewer           — read-only
+ *   service_account  — execute only (for automated tool calls)
+ */
+
+// ── Role ──────────────────────────────────────────────────────────────────────
+
+export enum Role {
+  ADMIN = 'admin',
+  EDITOR = 'editor',
+  VIEWER = 'viewer',
+  SERVICE_ACCOUNT = 'service_account',
+}
+
+// ── Action ────────────────────────────────────────────────────────────────────
+
+export enum Action {
+  CREATE = 'create',
+  READ = 'read',
+  UPDATE = 'update',
+  DELETE = 'delete',
+  EXECUTE = 'execute',
+}
+
+// ── Permission ────────────────────────────────────────────────────────────────
+
+export interface Permission {
+  resource: string;
+  action: Action;
+}
+
+// ── RolePermissions ───────────────────────────────────────────────────────────
+
+/**
+ * Maps each role to the set of (resource, action) pairs it is allowed to perform.
+ *
+ * The special resource '*' is a wildcard meaning "all resources".
+ */
+export type RolePermissions = Map<Role, Permission[]>;
+
+/**
+ * Default permission assignments for built-in roles.
+ */
+export function defaultRolePermissions(): RolePermissions {
+  const perms = new Map<Role, Permission[]>();
+
+  perms.set(Role.ADMIN, [
+    { resource: '*', action: Action.CREATE },
+    { resource: '*', action: Action.READ },
+    { resource: '*', action: Action.UPDATE },
+    { resource: '*', action: Action.DELETE },
+    { resource: '*', action: Action.EXECUTE },
+  ]);
+
+  perms.set(Role.EDITOR, [
+    { resource: '*', action: Action.CREATE },
+    { resource: '*', action: Action.READ },
+    { resource: '*', action: Action.UPDATE },
+    { resource: '*', action: Action.EXECUTE },
+  ]);
+
+  perms.set(Role.VIEWER, [{ resource: '*', action: Action.READ }]);
+
+  perms.set(Role.SERVICE_ACCOUNT, [
+    { resource: '*', action: Action.EXECUTE },
+    { resource: '*', action: Action.READ },
+  ]);
+
+  return perms;
+}
+
+// ── User ──────────────────────────────────────────────────────────────────────
+
+export interface User {
+  id: string;
+  email: string;
+  role: Role;
+  createdAt: Date;
+  lastLoginAt: Date | null;
+}
+
+// ── Audit log entry ───────────────────────────────────────────────────────────
+
+export interface RBACAuditEntry {
+  timestamp: Date;
+  userId: string;
+  resource: string;
+  action: string;
+  granted: boolean;
+}
+
+// ── Serialised shape ──────────────────────────────────────────────────────────
+
+interface SerialisedUser {
+  id: string;
+  email: string;
+  role: Role;
+  createdAt: string;
+  lastLoginAt: string | null;
+}
+
+interface SerialisedState {
+  users: SerialisedUser[];
+  permissions: Record<string, { resource: string; action: Action }[]>;
+}
+
+// ── RBACManager ───────────────────────────────────────────────────────────────
+
+export class RBACManager {
+  private users: Map<string, User> = new Map();
+  private permissions: RolePermissions;
+  private auditLog: RBACAuditEntry[] = [];
+
+  constructor(permissions?: RolePermissions) {
+    this.permissions = permissions ?? defaultRolePermissions();
+  }
+
+  // ── User CRUD ────────────────────────────────────────────────────────────
+
+  /**
+   * Add a user. Throws if the user id already exists.
+   */
+  addUser(user: User): void {
+    if (this.users.has(user.id)) {
+      throw new Error(`User already exists: ${user.id}`);
+    }
+    this.users.set(user.id, { ...user });
+  }
+
+  /**
+   * Remove a user by id. Returns true if the user existed and was removed.
+   */
+  removeUser(userId: string): boolean {
+    return this.users.delete(userId);
+  }
+
+  /**
+   * Retrieve a user by id, or undefined if not found.
+   */
+  getUser(userId: string): User | undefined {
+    return this.users.get(userId);
+  }
+
+  /**
+   * Return a snapshot of all users.
+   */
+  listUsers(): User[] {
+    return Array.from(this.users.values());
+  }
+
+  // ── Role management ──────────────────────────────────────────────────────
+
+  /**
+   * Assign a new role to an existing user. Returns false if the user doesn't exist.
+   */
+  assignRole(userId: string, role: Role): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+    user.role = role;
+    return true;
+  }
+
+  /**
+   * Record a login timestamp for a user. Returns false if the user doesn't exist.
+   */
+  recordLogin(userId: string): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+    user.lastLoginAt = new Date();
+    return true;
+  }
+
+  // ── Permission checks ────────────────────────────────────────────────────
+
+  /**
+   * Check whether a user has permission to perform `action` on `resource`.
+   *
+   * The check consults the user's role against the RolePermissions map.
+   * Wildcard resource '*' in the permission set grants access to all resources.
+   *
+   * Every check (granted or denied) is appended to the in-memory audit log.
+   */
+  checkPermission(userId: string, resource: string, action: string): boolean {
+    const user = this.users.get(userId);
+    if (!user) {
+      this.audit({ userId, resource, action, granted: false });
+      return false;
+    }
+
+    const rolePerms = this.permissions.get(user.role);
+    if (!rolePerms || rolePerms.length === 0) {
+      this.audit({ userId, resource, action, granted: false });
+      return false;
+    }
+
+    const granted = rolePerms.some((p) => (p.resource === '*' || p.resource === resource) && p.action === action);
+
+    this.audit({ userId, resource, action, granted });
+    return granted;
+  }
+
+  /**
+   * Check multiple permissions at once. Returns true only if ALL are granted.
+   */
+  checkPermissions(userId: string, checks: { resource: string; action: string }[]): boolean {
+    return checks.every((c) => this.checkPermission(userId, c.resource, c.action));
+  }
+
+  // ── Custom permissions ───────────────────────────────────────────────────
+
+  /**
+   * Add a custom permission entry for a specific role.
+   */
+  addPermission(role: Role, permission: Permission): void {
+    const existing = this.permissions.get(role) ?? [];
+    // Avoid duplicates
+    if (!existing.some((p) => p.resource === permission.resource && p.action === permission.action)) {
+      existing.push(permission);
+      this.permissions.set(role, existing);
+    }
+  }
+
+  /**
+   * Remove a permission entry from a role.
+   */
+  removePermission(role: Role, resource: string, action: Action): void {
+    const existing = this.permissions.get(role);
+    if (!existing) return;
+    const filtered = existing.filter((p) => !(p.resource === resource && p.action === action));
+    this.permissions.set(role, filtered);
+  }
+
+  /**
+   * Get all permissions for a role.
+   */
+  getRolePermissions(role: Role): Permission[] {
+    return [...(this.permissions.get(role) ?? [])];
+  }
+
+  // ── Audit log ────────────────────────────────────────────────────────────
+
+  /**
+   * Return the in-memory audit log.
+   */
+  getAuditLog(): RBACAuditEntry[] {
+    return [...this.auditLog];
+  }
+
+  /**
+   * Clear the audit log (useful for tests or after flushing to persistent storage).
+   */
+  clearAuditLog(): void {
+    this.auditLog = [];
+  }
+
+  private audit(entry: Omit<RBACAuditEntry, 'timestamp'>): void {
+    this.auditLog.push({ ...entry, timestamp: new Date() });
+  }
+
+  // ── Persistence ──────────────────────────────────────────────────────────
+
+  /**
+   * Serialise the entire RBAC state (users + custom permissions) to a JSON string.
+   * The audit log is intentionally excluded — it should be flushed separately.
+   */
+  serialize(): string {
+    const state: SerialisedState = {
+      users: Array.from(this.users.values()).map((u) => ({
+        id: u.id,
+        email: u.email,
+        role: u.role,
+        createdAt: u.createdAt.toISOString(),
+        lastLoginAt: u.lastLoginAt?.toISOString() ?? null,
+      })),
+      permissions: Object.fromEntries(
+        Array.from(this.permissions.entries()).map(([role, perms]) => [
+          role,
+          perms.map((p) => ({ resource: p.resource, action: p.action })),
+        ]),
+      ),
+    };
+    return JSON.stringify(state);
+  }
+
+  /**
+   * Restore RBAC state from a previously serialised JSON string.
+   * Replaces all existing users and permissions.
+   */
+  deserialize(data: string): void {
+    const state: SerialisedState = JSON.parse(data);
+
+    this.users = new Map(
+      state.users.map((u) => [
+        u.id,
+        {
+          id: u.id,
+          email: u.email,
+          role: u.role,
+          createdAt: new Date(u.createdAt),
+          lastLoginAt: u.lastLoginAt ? new Date(u.lastLoginAt) : null,
+        },
+      ]),
+    );
+
+    this.permissions = new Map(
+      Object.entries(state.permissions).map(([roleStr, perms]) => [
+        roleStr as Role,
+        perms.map((p) => ({ resource: p.resource, action: p.action })),
+      ]),
+    );
+  }
+}

package/src/core/retry.ts

@@ -0,0 +1,61 @@
+/**
+ * Retry with exponential backoff and jitter.
+ *
+ * Every tool call is automatically retried on transient failures.
+ * Backoff: baseDelay * 2^attempt + random jitter
+ *
+ * Designed for API rate limits, network blips, and temporary outages.
+ */
+
+export interface RetryOptions {
+  /** Maximum number of attempts (including the first) */
+  maxAttempts: number;
+  /** Base delay in ms */
+  baseDelay: number;
+  /** Maximum delay in ms */
+  maxDelay: number;
+  /** Retry only on these error codes/messages */
+  retryableErrors?: string[];
+  /** Callback for each retry attempt */
+  onRetry?: (attempt: number, error: Error, delay: number) => void;
+}
+
+const DEFAULTS: RetryOptions = {
+  maxAttempts: 3,
+  baseDelay: 1000,
+  maxDelay: 30000,
+};
+
+export async function withRetry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T> {
+  const opts = { ...DEFAULTS, ...options };
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      // Don't retry if error is not retryable
+      if (opts.retryableErrors && opts.retryableErrors.length > 0) {
+        if (!opts.retryableErrors.some((pattern) => lastError!.message.includes(pattern))) {
+          throw lastError;
+        }
+      }
+
+      // Don't retry on last attempt
+      if (attempt === opts.maxAttempts) {
+        throw lastError;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const delay = Math.min(opts.baseDelay * Math.pow(2, attempt - 1) + Math.random() * 1000, opts.maxDelay);
+
+      opts.onRetry?.(attempt, lastError, delay);
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError!;
+}

package/src/core/webhooks.ts

@@ -0,0 +1,234 @@
+/**
+ * Webhook System — event-driven plugin communication.
+ *
+ * Plugins can emit events. External systems can subscribe via webhooks.
+ * Events are queued, retried on failure, and logged for audit.
+ *
+ * Event types: tool_called, tool_failed, plugin_enabled, plugin_disabled,
+ *              config_changed, auth_success, auth_failure, health_degraded
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+export interface WebhookSubscription {
+  id: string;
+  url: string;
+  /** Events to receive. ['*'] for all events. */
+  events: string[];
+  /** Secret for HMAC signature verification */
+  secret: string;
+  /** Whether this subscription is active */
+  active: boolean;
+  /** Created timestamp */
+  createdAt: string;
+  /** Last successful delivery timestamp */
+  lastSuccessAt?: string;
+  /** Number of consecutive failures */
+  consecutiveFailures: number;
+}
+
+export interface WebhookEvent {
+  id: string;
+  type: string;
+  timestamp: string;
+  /** The resource that triggered the event */
+  resource: string;
+  /** Event payload */
+  data: Record<string, unknown>;
+}
+
+export interface WebhookDelivery {
+  eventId: string;
+  subscriptionId: string;
+  url: string;
+  status: 'pending' | 'delivered' | 'failed';
+  attempts: number;
+  lastAttemptAt?: string;
+  responseCode?: number;
+  responseError?: string;
+}
+
+const MAX_CONSECUTIVE_FAILURES = 10;
+const DELIVERY_TIMEOUT = 10000;
+
+export class WebhookManager {
+  private subscriptionsFile: string;
+  private subscriptions: Map<string, WebhookSubscription>;
+  private deliveryQueue: Array<{ event: WebhookEvent; subscription: WebhookSubscription }>;
+  private processing = false;
+
+  constructor(configDir: string) {
+    this.subscriptionsFile = path.join(configDir, 'webhooks.json');
+    this.subscriptions = new Map();
+    this.deliveryQueue = [];
+  }
+
+  /**
+   * Load subscriptions from disk.
+   */
+  async load(): Promise<void> {
+    try {
+      const content = await fs.readFile(this.subscriptionsFile, 'utf-8');
+      const data = JSON.parse(content) as WebhookSubscription[];
+      for (const sub of data) {
+        this.subscriptions.set(sub.id, sub);
+      }
+    } catch {
+      // No subscriptions file yet
+    }
+  }
+
+  /**
+   * Save subscriptions to disk.
+   */
+  async save(): Promise<void> {
+    const data = Array.from(this.subscriptions.values());
+    await fs.writeFile(this.subscriptionsFile, JSON.stringify(data, null, 2), { mode: 0o600 });
+  }
+
+  /**
+   * Create a new webhook subscription.
+   */
+  async create(url: string, events: string[]): Promise<WebhookSubscription> {
+    const subscription: WebhookSubscription = {
+      id: crypto.randomUUID(),
+      url,
+      events,
+      secret: crypto.randomBytes(32).toString('hex'),
+      active: true,
+      createdAt: new Date().toISOString(),
+      consecutiveFailures: 0,
+    };
+
+    this.subscriptions.set(subscription.id, subscription);
+    await this.save();
+    return subscription;
+  }
+
+  /**
+   * Delete a webhook subscription.
+   */
+  async delete(id: string): Promise<boolean> {
+    const deleted = this.subscriptions.delete(id);
+    if (deleted) await this.save();
+    return deleted;
+  }
+
+  /**
+   * List all subscriptions.
+   */
+  list(): WebhookSubscription[] {
+    return Array.from(this.subscriptions.values());
+  }
+
+  /**
+   * Emit an event. Queues it for delivery to matching subscriptions.
+   */
+  async emit(event: Omit<WebhookEvent, 'id' | 'timestamp'>): Promise<void> {
+    const fullEvent: WebhookEvent = {
+      ...event,
+      id: crypto.randomUUID(),
+      timestamp: new Date().toISOString(),
+    };
+
+    for (const sub of this.subscriptions.values()) {
+      if (!sub.active) continue;
+      if (!sub.events.includes('*') && !sub.events.includes(event.type)) continue;
+
+      this.deliveryQueue.push({ event: fullEvent, subscription: sub });
+    }
+
+    // Process queue asynchronously
+    if (!this.processing) {
+      this.processQueue().catch(() => {});
+    }
+  }
+
+  /**
+   * Process the delivery queue.
+   */
+  private async processQueue(): Promise<void> {
+    this.processing = true;
+
+    while (this.deliveryQueue.length > 0) {
+      const item = this.deliveryQueue.shift()!;
+      await this.deliver(item.event, item.subscription);
+    }
+
+    this.processing = false;
+  }
+
+  /**
+   * Deliver an event to a subscription.
+   */
+  private async deliver(event: WebhookEvent, subscription: WebhookSubscription): Promise<void> {
+    const payload = JSON.stringify({
+      id: event.id,
+      type: event.type,
+      timestamp: event.timestamp,
+      resource: event.resource,
+      data: event.data,
+    });
+
+    const signature = crypto.createHmac('sha256', subscription.secret).update(payload).digest('hex');
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), DELIVERY_TIMEOUT);
+
+      const response = await fetch(subscription.url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Conductor-Signature': `sha256=${signature}`,
+          'X-Conductor-Event': event.type,
+          'X-Conductor-Delivery': event.id,
+          'User-Agent': 'Conductor-Webhook/1.0',
+        },
+        body: payload,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+
+      if (response.ok) {
+        subscription.consecutiveFailures = 0;
+        subscription.lastSuccessAt = new Date().toISOString();
+        await this.save();
+      } else {
+        await this.recordFailure(subscription, response.status, `HTTP ${response.status}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await this.recordFailure(subscription, 0, message);
+    }
+  }
+
+  /**
+   * Record a delivery failure. Deactivate after MAX_CONSECUTIVE_FAILURES.
+   */
+  private async recordFailure(subscription: WebhookSubscription, _status: number, _error: string): Promise<void> {
+    subscription.consecutiveFailures++;
+
+    if (subscription.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+      subscription.active = false;
+    }
+
+    await this.save();
+  }
+
+  /**
+   * Generate example webhook payload for testing.
+   */
+  static exampleEvent(type: string, resource: string): WebhookEvent {
+    return {
+      id: 'evt_example_123',
+      type,
+      timestamp: new Date().toISOString(),
+      resource,
+      data: { example: true, message: 'This is a test event' },
+    };
+  }
+}

package/src/core/zero-config.ts

@@ -0,0 +1,72 @@
+/**
+ * Zero-Config Mode Bootstrap
+ *
+ * Automatically enables 20+ tools that work without any API keys.
+ * These plugins have isConfigured() returning true without setup,
+ * or have safe defaults that work for public/unauthenticated use.
+ */
+
+import { Conductor } from '../core/conductor.js';
+
+/**
+ * List of plugins that work without any credentials
+ * (isConfigured() returns true or they have safe defaults)
+ */
+export const ZERO_CONFIG_PLUGINS = [
+  // Core utilities - all work without credentials
+  'calculator', // Math expressions, unit conversions
+  'colors', // Color format conversion
+  'crypto', // Cryptocurrency prices/search
+  'hash', // Hashing, encoding
+  'text-tools', // JSON formatting, word count
+  'timezone', // Timezone conversion
+  'network', // DNS lookup, IP info
+  'url-tools', // URL parsing, expansion
+  'fun', // Jokes, facts
+  'system', // System info, clipboard
+
+  // Productivity - local only or safe defaults
+  'notes', // Local markdown notes
+  'memory', // Local semantic memory
+  'cron', // Cron expression parsing
+
+  // Infrastructure - local tools
+  'shell', // Safe shell commands (whitelist)
+  'docker', // Local Docker (if installed)
+
+  // GitHub - public data works without auth
+  'github', // Public repos, user info
+
+  // Weather - uses free Open-Meteo API
+  'weather', // Weather/current forecasts
+
+  // File system tools are built into Shell plugin
+];
+
+/**
+ * Enable zero-config plugins on first run
+ */
+export async function enableZeroConfigMode(conductor: Conductor): Promise<void> {
+  const config = conductor.getConfig();
+
+  // Get currently enabled plugins
+  let enabledPlugins = config.get<string[]>('plugins.enabled') ?? [];
+
+  // Enable any zero-config plugins not already enabled
+  const toEnable = ZERO_CONFIG_PLUGINS.filter((plugin) => !enabledPlugins.includes(plugin));
+
+  if (toEnable.length > 0) {
+    enabledPlugins = [...enabledPlugins, ...toEnable];
+    await config.set('plugins.enabled', enabledPlugins);
+
+    process.stderr.write(`[ZERO-CONFIG] Enabled ${toEnable.length} plugins: ${toEnable.join(', ')}\n`);
+  }
+}
+
+/**
+ * Check if zero-config mode is active
+ */
+export function isZeroConfigMode(conductor: Conductor): boolean {
+  const enabledPlugins = conductor.getConfig().get<string[]>('plugins.enabled') ?? [];
+  return ZERO_CONFIG_PLUGINS.every((plugin) => enabledPlugins.includes(plugin));
+}

package/src/dashboard/README.md

@@ -0,0 +1,15 @@
+# src/dashboard
+
+Web dashboard for Conductor — an Express server serving a single-page application.
+
+## Contents
+
+- `server.ts` - Express server with metrics, audit, health, and webhook endpoints
+- `index.html` - Single-page application UI
+- `cli.ts` - Dashboard-specific CLI commands
+
+## Architecture
+
+The dashboard provides a web UI for monitoring Conductor. It consumes metrics, audit logs, health status, and webhook data from the MCP server's shared state. The Express server uses `express-rate-limit` for protection. The `postbuild` script copies `index.html` to `dist/dashboard/index.html`.
+
+Transport: HTTP/SSE for real-time updates from the MCP server.