@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/index.ts

@@ -30,7 +30,7 @@ export { createServer } from './server.js';
 export type { ServerConfig, ServerInstance } from './server.js';
 
 // Deploy
-export { deployToCloud, generateDockerCompose, generateFlyToml } from './deploy/managed.js';
+export { deployToCloud, generateDockerCompose, generateEnvFile, generateFlyToml } from './deploy/managed.js';
 
 // Routes (for custom server setups)
 export { createAdminRoutes } from './admin/routes.js';
@@ -49,6 +49,10 @@ export {
   ValidationError,
 } from './middleware/index.js';
 
+// Setup Wizard
+export { runSetupWizard, provision } from './setup/index.js';
+export type { CompanyInfo, DatabaseSelection, DeployTarget, DomainSelection, ProvisionConfig, ProvisionResult } from './setup/index.js';
+
 // Engine (managed agent deployment platform)
 export * from './engine/index.js';
 
@@ -62,3 +66,7 @@ export {
   CircuitOpenError,
 } from './lib/resilience.js';
 export type { RetryOptions, CircuitBreakerOptions, RateLimiterOptions, HealthCheckOptions } from './lib/resilience.js';
+
+// Agent Runtime (standalone agent execution)
+export { AgentRuntime, createAgentRuntime } from './runtime/index.js';
+export type { AgentConfig, SessionState, StreamEvent, RuntimeConfig, ModelConfig, SpawnOptions } from './runtime/types.js';

package/src/lib/cidr.ts

@@ -0,0 +1,122 @@
+/**
+ * AgenticMail Enterprise — IPv4 CIDR Matching Utilities
+ *
+ * Pure functions for parsing and matching IPs against CIDR ranges.
+ * Used by the firewall middleware for IP access control and trusted proxy validation.
+ */
+
+/** Parsed CIDR with pre-computed numeric values for fast matching. */
+export interface ParsedCidr {
+  network: number;
+  mask: number;
+  original: string;
+}
+
+/**
+ * Convert an IPv4 address string to a 32-bit unsigned integer.
+ * Handles IPv4-mapped IPv6 (::ffff:x.x.x.x).
+ * Returns null for invalid or non-IPv4 addresses.
+ */
+export function ipToNumber(ip: string): number | null {
+  if (!ip) return null;
+  // Strip IPv4-mapped IPv6 prefix
+  let cleaned = ip.trim();
+  if (cleaned.startsWith('::ffff:')) cleaned = cleaned.slice(7);
+  // Must be IPv4 dotted-quad
+  const parts = cleaned.split('.');
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (let i = 0; i < 4; i++) {
+    const octet = parseInt(parts[i], 10);
+    if (isNaN(octet) || octet < 0 || octet > 255) return null;
+    num = (num << 8) | octet;
+  }
+  return num >>> 0; // Ensure unsigned
+}
+
+/**
+ * Parse a CIDR string (e.g., "10.0.0.0/8") into a pre-computed matcher.
+ * Plain IPs (e.g., "192.168.1.1") are treated as /32.
+ * Returns null for invalid input.
+ */
+export function parseCidr(cidr: string): ParsedCidr | null {
+  if (!cidr) return null;
+  const trimmed = cidr.trim();
+  const slashIdx = trimmed.indexOf('/');
+  let ip: string;
+  let prefix: number;
+
+  if (slashIdx === -1) {
+    ip = trimmed;
+    prefix = 32;
+  } else {
+    ip = trimmed.slice(0, slashIdx);
+    prefix = parseInt(trimmed.slice(slashIdx + 1), 10);
+    if (isNaN(prefix) || prefix < 0 || prefix > 32) return null;
+  }
+
+  const num = ipToNumber(ip);
+  if (num === null) return null;
+
+  // Build the mask: prefix=8 → 0xFF000000, prefix=32 → 0xFFFFFFFF, prefix=0 → 0x00000000
+  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+  const network = (num & mask) >>> 0;
+
+  return { network, mask, original: trimmed };
+}
+
+/**
+ * Test whether an IP address matches a parsed CIDR range.
+ */
+export function ipMatchesCidr(ip: string, cidr: ParsedCidr): boolean {
+  const num = ipToNumber(ip);
+  if (num === null) return false;
+  return ((num & cidr.mask) >>> 0) === cidr.network;
+}
+
+/**
+ * Compile a list of IP/CIDR strings into a fast matcher function.
+ * Pre-parses all entries so per-request matching is O(n) comparisons with no parsing.
+ * Invalid entries are silently skipped.
+ */
+export function compileIpMatcher(entries: string[]): (ip: string) => boolean {
+  const parsed: ParsedCidr[] = [];
+  for (const entry of entries) {
+    const p = parseCidr(entry);
+    if (p) parsed.push(p);
+  }
+  if (parsed.length === 0) return () => false;
+
+  return function matchIp(ip: string): boolean {
+    const num = ipToNumber(ip);
+    if (num === null) return false;
+    for (let i = 0; i < parsed.length; i++) {
+      if (((num & parsed[i].mask) >>> 0) === parsed[i].network) return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Validate that a string is a valid IPv4 address or CIDR notation.
+ */
+export function isValidIpOrCidr(str: string): boolean {
+  return parseCidr(str) !== null;
+}
+
+/**
+ * Match a hostname against a pattern that may include wildcards.
+ * Supports: "*.example.com" matching "api.example.com", "sub.api.example.com"
+ * Exact match: "example.com" only matches "example.com"
+ */
+export function hostMatchesPattern(host: string, pattern: string): boolean {
+  if (!host || !pattern) return false;
+  const h = host.toLowerCase().trim();
+  const p = pattern.toLowerCase().trim();
+  if (p === h) return true;
+  if (p.startsWith('*.')) {
+    const suffix = p.slice(1); // ".example.com"
+    return h.endsWith(suffix) || h === p.slice(2);
+  }
+  return false;
+}

package/src/lib/config-store.ts

@@ -0,0 +1,86 @@
+/**
+ * Encrypted Config Storage
+ *
+ * Stores database credentials in an encrypted file (.agenticmail.enc)
+ * using AES-256-GCM with scrypt key derivation from a master secret.
+ *
+ * Format: JSON { iv, tag, salt, data } (all base64)
+ */
+
+import { scryptSync, randomBytes, createCipheriv, createDecipheriv } from 'crypto';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const CONFIG_FILE = '.agenticmail.enc';
+const ALGORITHM = 'aes-256-gcm';
+const SCRYPT_KEYLEN = 32;
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+
+function deriveKey(secret: string, salt: Buffer): Buffer {
+  return scryptSync(secret, salt, SCRYPT_KEYLEN, SCRYPT_PARAMS);
+}
+
+function getConfigPath(): string {
+  return join(process.cwd(), CONFIG_FILE);
+}
+
+export interface DatabaseConfigEntry {
+  type: string;
+  host?: string;
+  port?: number;
+  database?: string;
+  username?: string;
+  password?: string;
+  connectionString?: string;
+  ssl?: boolean;
+  authToken?: string;
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+}
+
+export async function saveDbConfig(config: DatabaseConfigEntry, secret: string): Promise<void> {
+  const salt = randomBytes(16);
+  const key = deriveKey(secret, salt);
+  const iv = randomBytes(12);
+
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const plaintext = JSON.stringify(config);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  const payload = {
+    iv: iv.toString('base64'),
+    tag: tag.toString('base64'),
+    salt: salt.toString('base64'),
+    data: encrypted.toString('base64'),
+  };
+
+  writeFileSync(getConfigPath(), JSON.stringify(payload, null, 2), 'utf-8');
+}
+
+export async function loadDbConfig(secret: string): Promise<DatabaseConfigEntry | null> {
+  const path = getConfigPath();
+  if (!existsSync(path)) return null;
+
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    const salt = Buffer.from(raw.salt, 'base64');
+    const iv = Buffer.from(raw.iv, 'base64');
+    const tag = Buffer.from(raw.tag, 'base64');
+    const data = Buffer.from(raw.data, 'base64');
+
+    const key = deriveKey(secret, salt);
+    const decipher = createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+
+    const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
+    return JSON.parse(decrypted.toString('utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function configFileExists(): boolean {
+  return existsSync(getConfigPath());
+}

package/src/mcp/adapters/activecampaign.adapter.ts

@@ -0,0 +1,391 @@
+/**
+ * MCP Skill Adapter — ActiveCampaign
+ *
+ * Maps ActiveCampaign API v3 endpoints to MCP tool handlers.
+ * Covers contacts, deals, and automations management.
+ *
+ * ActiveCampaign API docs: https://developers.activecampaign.com/reference
+ *
+ * Base URL is dynamic based on the customer's account name:
+ * https://{account}.api-us1.com/api/3
+ *
+ * The account name is read from ctx.skillConfig.account.
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Resolve the ActiveCampaign base URL from skill config */
+function acUrl(ctx: ToolExecutionContext): string {
+  const account = ctx.skillConfig.account;
+  if (!account) {
+    throw new Error('ActiveCampaign account name is required in skillConfig (e.g. { account: "mycompany" })');
+  }
+  return `https://${account}.api-us1.com/api/3`;
+}
+
+function activecampaignError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const message = data.message || data.error || err.message;
+      const errors = data.errors ? ` -- ${JSON.stringify(data.errors)}` : '';
+      return { content: `ActiveCampaign API error: ${message}${errors}`, isError: true };
+    }
+    return { content: `ActiveCampaign API error: ${err.message}`, isError: true };
+  }
+  return { content: `ActiveCampaign API error: ${String(err)}`, isError: true };
+}
+
+/** Format an ActiveCampaign contact for display */
+function formatContact(contact: any): string {
+  const name = [contact.firstName, contact.lastName].filter(Boolean).join(' ') || '(no name)';
+  const email = contact.email || '(no email)';
+  const phone = contact.phone ? ` | ${contact.phone}` : '';
+  return `${name} <${email}>${phone} (ID: ${contact.id})`;
+}
+
+/** Format an ActiveCampaign deal for display */
+function formatDeal(deal: any): string {
+  const title = deal.title || 'Untitled';
+  const value = deal.value ? `$${Number(deal.value / 100).toLocaleString()}` : 'N/A';
+  const stage = deal.stage || 'unknown';
+  const status = deal.status === '0' ? 'Open' : deal.status === '1' ? 'Won' : deal.status === '2' ? 'Lost' : deal.status;
+  return `${title} -- ${status} -- ${value} -- stage: ${stage} (ID: ${deal.id})`;
+}
+
+// ─── Tool: ac_list_contacts ─────────────────────────────
+
+const listContacts: ToolHandler = {
+  description:
+    'List contacts from ActiveCampaign. Optionally filter by email or search query. Returns contact names, emails, and IDs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      search: {
+        type: 'string',
+        description: 'Search contacts by email or name',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of contacts to return (default 20, max 100)',
+      },
+      offset: {
+        type: 'number',
+        description: 'Offset for pagination (default 0)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = acUrl(ctx);
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 20),
+        offset: String(params.offset ?? 0),
+      };
+      if (params.search) query.search = params.search;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/contacts`,
+        query,
+      });
+
+      const contacts: any[] = result.contacts || [];
+      if (contacts.length === 0) {
+        return { content: 'No contacts found.', metadata: { count: 0 } };
+      }
+
+      const lines = contacts.map((c: any) => formatContact(c));
+      const total = result.meta?.total ?? contacts.length;
+
+      return {
+        content: `Found ${total} contacts (showing ${contacts.length}):\n${lines.join('\n')}`,
+        metadata: { count: contacts.length, total },
+      };
+    } catch (err) {
+      return activecampaignError(err);
+    }
+  },
+};
+
+// ─── Tool: ac_create_contact ────────────────────────────
+
+const createContact: ToolHandler = {
+  description:
+    'Create a new contact in ActiveCampaign. Provide at least an email address, plus optional name and phone fields.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      email: {
+        type: 'string',
+        description: 'Contact email address',
+      },
+      firstName: {
+        type: 'string',
+        description: 'Contact first name',
+      },
+      lastName: {
+        type: 'string',
+        description: 'Contact last name',
+      },
+      phone: {
+        type: 'string',
+        description: 'Contact phone number',
+      },
+    },
+    required: ['email'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = acUrl(ctx);
+
+      const contact: Record<string, any> = { email: params.email };
+      if (params.firstName) contact.firstName = params.firstName;
+      if (params.lastName) contact.lastName = params.lastName;
+      if (params.phone) contact.phone = params.phone;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: `${baseUrl}/contacts`,
+        body: { contact },
+      });
+
+      const c = result.contact;
+      return {
+        content: `Contact created: ${formatContact(c)}`,
+        metadata: { contactId: c.id, email: params.email },
+      };
+    } catch (err) {
+      return activecampaignError(err);
+    }
+  },
+};
+
+// ─── Tool: ac_list_deals ────────────────────────────────
+
+const listDeals: ToolHandler = {
+  description:
+    'List deals from ActiveCampaign CRM. Optionally filter by stage or search query.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      search: {
+        type: 'string',
+        description: 'Search deals by title',
+      },
+      stage: {
+        type: 'number',
+        description: 'Filter by stage ID',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of deals to return (default 20, max 100)',
+      },
+      offset: {
+        type: 'number',
+        description: 'Offset for pagination (default 0)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = acUrl(ctx);
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 20),
+        offset: String(params.offset ?? 0),
+      };
+      if (params.search) query['filters[search]'] = params.search;
+      if (params.stage) query['filters[stage]'] = String(params.stage);
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/deals`,
+        query,
+      });
+
+      const deals: any[] = result.deals || [];
+      if (deals.length === 0) {
+        return { content: 'No deals found.', metadata: { count: 0 } };
+      }
+
+      const lines = deals.map((d: any) => formatDeal(d));
+      const total = result.meta?.total ?? deals.length;
+
+      return {
+        content: `Found ${total} deals (showing ${deals.length}):\n${lines.join('\n')}`,
+        metadata: { count: deals.length, total },
+      };
+    } catch (err) {
+      return activecampaignError(err);
+    }
+  },
+};
+
+// ─── Tool: ac_list_automations ──────────────────────────
+
+const listAutomations: ToolHandler = {
+  description:
+    'List automations from ActiveCampaign. Returns automation names, statuses, and trigger info.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of automations to return (default 20, max 100)',
+      },
+      offset: {
+        type: 'number',
+        description: 'Offset for pagination (default 0)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = acUrl(ctx);
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 20),
+        offset: String(params.offset ?? 0),
+      };
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/automations`,
+        query,
+      });
+
+      const automations: any[] = result.automations || [];
+      if (automations.length === 0) {
+        return { content: 'No automations found.', metadata: { count: 0 } };
+      }
+
+      const lines = automations.map((a: any) => {
+        const name = a.name || '(unnamed)';
+        const status = a.status === '1' ? 'Active' : 'Inactive';
+        const entered = a.entered ?? 0;
+        return `${name} -- ${status} -- ${entered} contacts entered (ID: ${a.id})`;
+      });
+
+      const total = result.meta?.total ?? automations.length;
+
+      return {
+        content: `Found ${total} automations (showing ${automations.length}):\n${lines.join('\n')}`,
+        metadata: { count: automations.length, total },
+      };
+    } catch (err) {
+      return activecampaignError(err);
+    }
+  },
+};
+
+// ─── Tool: ac_create_deal ───────────────────────────────
+
+const createDeal: ToolHandler = {
+  description:
+    'Create a new deal in ActiveCampaign CRM. Provide a title, value, and pipeline/stage info.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: {
+        type: 'string',
+        description: 'Deal title',
+      },
+      value: {
+        type: 'number',
+        description: 'Deal value in cents (e.g. 50000 = $500.00)',
+      },
+      currency: {
+        type: 'string',
+        description: 'Currency code (e.g. "usd")',
+      },
+      group: {
+        type: 'string',
+        description: 'Pipeline ID',
+      },
+      stage: {
+        type: 'string',
+        description: 'Stage ID within the pipeline',
+      },
+      owner: {
+        type: 'string',
+        description: 'Owner user ID',
+      },
+      contact: {
+        type: 'string',
+        description: 'Primary contact ID to associate with the deal',
+      },
+    },
+    required: ['title', 'value'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = acUrl(ctx);
+
+      const deal: Record<string, any> = {
+        title: params.title,
+        value: params.value,
+        currency: params.currency || 'usd',
+      };
+      if (params.group) deal.group = params.group;
+      if (params.stage) deal.stage = params.stage;
+      if (params.owner) deal.owner = params.owner;
+      if (params.contact) deal.contact = params.contact;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: `${baseUrl}/deals`,
+        body: { deal },
+      });
+
+      const d = result.deal;
+      return {
+        content: `Deal created: ${formatDeal(d)}`,
+        metadata: { dealId: d.id, title: params.title },
+      };
+    } catch (err) {
+      return activecampaignError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const activecampaignAdapter: SkillAdapter = {
+  skillId: 'activecampaign',
+  name: 'ActiveCampaign',
+  // Base URL is dynamic based on account name; tools use ctx.apiExecutor.request() with full URLs
+  baseUrl: 'https://ACCOUNT.api-us1.com/api/3',
+  auth: {
+    type: 'api_key',
+    headerName: 'Api-Token',
+  },
+  tools: {
+    ac_list_contacts: listContacts,
+    ac_create_contact: createContact,
+    ac_list_deals: listDeals,
+    ac_list_automations: listAutomations,
+    ac_create_deal: createDeal,
+  },
+  configSchema: {
+    account: {
+      type: 'string' as const,
+      label: 'Account Name',
+      description: 'Your ActiveCampaign account name (e.g. "mycompany" for mycompany.api-us1.com)',
+      required: true,
+      placeholder: 'mycompany',
+    },
+  },
+  rateLimits: {
+    requestsPerSecond: 5,
+    burstLimit: 10,
+  },
+};