@auxiora/config 1.0.0

package/src/index.ts

@@ -0,0 +1,403 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { getConfigPath, isWindows } from '@auxiora/core';
+
+const GatewayConfigSchema = z.object({
+  host: z.string().default('0.0.0.0'),
+  port: z.number().int().min(1).max(65535).default(18800),
+  corsOrigins: z.array(z.string()).default(['http://localhost:18800']),
+});
+
+const AuthConfigSchema = z.object({
+  mode: z.enum(['none', 'password', 'jwt']).default('none'),
+  /** Argon2id hash of the gateway password */
+  passwordHash: z.string().optional(),
+  /** Secret for signing JWT tokens (min 32 chars recommended) */
+  jwtSecret: z.string().optional(),
+  jwtExpiresIn: z.string().default('7d'),
+  refreshExpiresIn: z.string().default('30d'),
+});
+
+const RateLimitConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  windowMs: z.number().int().positive().default(60000), // 1 minute
+  maxRequests: z.number().int().positive().default(300),
+});
+
+const PairingConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  codeLength: z.number().int().min(4).max(12).default(6),
+  expiryMinutes: z.number().int().positive().default(15),
+  autoApproveChannels: z.array(z.string()).default(['webchat']),
+  persistPath: z.string().optional(),
+});
+
+const ModelRoutingSchema = z.object({
+  enabled: z.boolean().default(true),
+  defaultModel: z.string().optional(),
+  rules: z.array(z.object({
+    task: z.enum(['reasoning', 'code', 'creative', 'vision', 'long-context', 'fast', 'private', 'image-gen']),
+    provider: z.string(),
+    model: z.string(),
+    priority: z.number().default(0),
+  })).default([]),
+  costLimits: z.object({
+    dailyBudget: z.number().positive().optional(),
+    monthlyBudget: z.number().positive().optional(),
+    perMessageMax: z.number().positive().optional(),
+    warnAt: z.number().min(0).max(1).default(0.8),
+  }).default({}),
+  preferences: z.object({
+    preferLocal: z.boolean().default(false),
+    preferCheap: z.boolean().default(false),
+    sensitiveToLocal: z.boolean().default(false),
+  }).default({}),
+});
+
+const ProviderConfigSchema = z.object({
+  primary: z.string().default('anthropic'),
+  fallback: z.string().optional(),
+  anthropic: z.object({
+    model: z.string().default('claude-sonnet-4-20250514'),
+    maxTokens: z.number().int().positive().default(4096),
+  }).default({}),
+  openai: z.object({
+    model: z.string().default('gpt-5.2'),
+    maxTokens: z.number().int().positive().default(4096),
+  }).default({}),
+  google: z.object({
+    model: z.string().default('gemini-2.5-flash'),
+    maxTokens: z.number().int().positive().default(4096),
+  }).default({}),
+  ollama: z.object({
+    model: z.string().default('llama3'),
+    maxTokens: z.number().int().positive().default(4096),
+    baseUrl: z.string().default('http://localhost:11434'),
+  }).default({}),
+  openaiCompatible: z.object({
+    model: z.string().default(''),
+    maxTokens: z.number().int().positive().default(4096),
+    baseUrl: z.string().default(''),
+    name: z.string().default('custom'),
+  }).default({}),
+});
+
+const SessionConfigSchema = z.object({
+  maxContextTokens: z.number().int().positive().default(100000),
+  ttlMinutes: z.number().int().positive().default(1440), // 24 hours
+  autoSave: z.boolean().default(true),
+  compactionEnabled: z.boolean().default(true),
+});
+
+const LoggingConfigSchema = z.object({
+  level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  auditEnabled: z.boolean().default(true),
+  maxFileSizeMb: z.number().positive().default(10),
+  maxFiles: z.number().int().positive().default(5),
+});
+
+const ChannelConfigSchema = z.object({
+  discord: z.object({
+    enabled: z.boolean().default(false),
+    mentionOnly: z.boolean().default(true),
+  }).default({}),
+  telegram: z.object({
+    enabled: z.boolean().default(false),
+    webhookMode: z.boolean().default(false),
+  }).default({}),
+  slack: z.object({
+    enabled: z.boolean().default(false),
+    socketMode: z.boolean().default(true),
+  }).default({}),
+  twilio: z.object({
+    enabled: z.boolean().default(false),
+    smsEnabled: z.boolean().default(true),
+    whatsappEnabled: z.boolean().default(false),
+  }).default({}),
+  webchat: z.object({
+    enabled: z.boolean().default(true),
+  }).default({}),
+  matrix: z.object({
+    enabled: z.boolean().default(false),
+    autoJoinRooms: z.boolean().default(true),
+  }).default({}),
+  signal: z.object({
+    enabled: z.boolean().default(false),
+  }).default({}),
+  email: z.object({
+    enabled: z.boolean().default(false),
+    pollInterval: z.number().int().positive().default(30000),
+  }).default({}),
+  teams: z.object({
+    enabled: z.boolean().default(false),
+  }).default({}),
+  whatsapp: z.object({
+    enabled: z.boolean().default(false),
+  }).default({}),
+});
+
+const VoiceConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  sttProvider: z.enum(['openai-whisper']).default('openai-whisper'),
+  ttsProvider: z.enum(['openai-tts']).default('openai-tts'),
+  defaultVoice: z.string().default('alloy'),
+  language: z.string().default('en'),
+  maxAudioDuration: z.number().int().positive().default(30),
+  sampleRate: z.number().int().positive().default(16000),
+});
+
+const WebhookConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  basePath: z.string().default('/api/v1/webhooks'),
+  signatureHeader: z.string().default('x-webhook-signature'),
+  maxPayloadSize: z.number().int().positive().default(65536),
+});
+
+const DashboardConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  sessionTtlMs: z.number().int().positive().default(86_400_000),
+});
+
+// [P6] Desktop config
+export const DesktopConfigSchema = z.object({
+  autoStart: z.boolean().default(false),
+  minimizeToTray: z.boolean().default(true),
+  hotkey: z.string().default('CommandOrControl+Shift+A'),
+  notificationsEnabled: z.boolean().default(true),
+  updateChannel: z.enum(['stable', 'beta', 'nightly']).default('stable'),
+  ollamaEnabled: z.boolean().default(false),
+  ollamaPort: z.number().int().min(1).max(65535).default(11434),
+  windowWidth: z.number().int().positive().default(1024),
+  windowHeight: z.number().int().positive().default(768),
+});
+export type DesktopConfig = z.infer<typeof DesktopConfigSchema>;
+
+// [P7] Cloud config
+export const CloudConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  baseDataDir: z.string().default('/data/tenants'),
+  jwtSecret: z.string().default(''),
+  stripeSecretKey: z.string().optional(),
+  stripeWebhookSecret: z.string().optional(),
+  domain: z.string().default('localhost'),
+});
+export type CloudConfig = z.infer<typeof CloudConfigSchema>;
+
+// [P12] Trust / Autonomy
+const TrustConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  defaultLevel: z.number().int().min(0).max(4).default(0),
+  autoPromote: z.boolean().default(true),
+  promotionThreshold: z.number().int().positive().default(10),
+  demotionThreshold: z.number().int().positive().default(3),
+  autoPromoteCeiling: z.number().int().min(0).max(4).default(3),
+});
+
+const ResearchConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  braveApiKey: z.string().optional(),
+  defaultDepth: z.enum(['quick', 'standard', 'deep']).default('standard'),
+  maxConcurrentSources: z.number().int().positive().default(5),
+  searchTimeout: z.number().int().positive().default(10000),
+  fetchTimeout: z.number().int().positive().default(15000),
+});
+
+const IntentConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  confidenceThreshold: z.number().min(0).max(1).default(0.3),
+});
+
+const PluginsConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  dir: z.string().optional(),
+  marketplace: z.object({
+    registryUrl: z.string().default('https://registry.auxiora.dev'),
+    autoUpdate: z.boolean().default(false),
+  }).default({}),
+  pluginConfigs: z.record(z.string(), z.unknown()).default({}),
+  approvedPermissions: z.record(z.string(), z.array(z.enum([
+    'NETWORK', 'FILESYSTEM', 'SHELL', 'PROVIDER_ACCESS', 'CHANNEL_ACCESS', 'MEMORY_ACCESS',
+  ]))).default({}),
+});
+
+const MemoryConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  autoExtract: z.boolean().default(true),
+  maxEntries: z.number().int().positive().default(1000),
+  encryptAtRest: z.boolean().default(false),
+  cleanupIntervalMinutes: z.number().int().positive().default(60),
+  adaptivePersonality: z.boolean().default(true),
+  patternDetection: z.boolean().default(true),
+  relationshipTracking: z.boolean().default(true),
+  importanceDecay: z.number().min(0).max(1).default(0.01),
+});
+
+const OrchestrationConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  maxConcurrentAgents: z.number().int().min(1).max(10).default(5),
+  defaultTimeout: z.number().int().positive().default(60000),
+  totalTimeout: z.number().int().positive().default(300000),
+  allowedPatterns: z.array(z.enum([
+    'parallel', 'sequential', 'debate', 'map-reduce', 'supervisor',
+  ])).default(['parallel', 'sequential', 'debate', 'map-reduce', 'supervisor']),
+  costMultiplierWarning: z.number().positive().default(3),
+});
+
+const UserPreferencesSchema = z.object({
+  verbosity: z.number().min(0).max(1).default(0.5),
+  formality: z.number().min(0).max(1).default(0.5),
+  proactiveness: z.number().min(0).max(1).default(0.5),
+  riskTolerance: z.number().min(0).max(1).default(0.5),
+  humor: z.number().min(0).max(1).default(0.3),
+  feedbackStyle: z.enum(['direct', 'sandwich', 'gentle']).default('direct'),
+  expertiseAssumption: z.enum(['beginner', 'intermediate', 'expert']).default('intermediate'),
+});
+
+const ModeIdSchema = z.enum([
+  'operator', 'analyst', 'advisor', 'writer',
+  'socratic', 'legal', 'roast', 'companion',
+]);
+
+const ModesConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  defaultMode: z.union([ModeIdSchema, z.literal('auto'), z.literal('off')]).default('auto'),
+  autoDetection: z.boolean().default(true),
+  confirmationThreshold: z.number().min(0).max(1).default(0.4),
+  preferences: UserPreferencesSchema.default({}),
+});
+
+const AgentIdentitySchema = z.object({
+  name: z.string().default('Auxiora'),
+  pronouns: z.string().default('they/them'),
+  avatar: z.string().optional(),
+  vibe: z.string().max(200).optional(),
+  customInstructions: z.string().max(4000).optional(),
+  personality: z.string().default('professional'),
+  tone: z.object({
+    warmth: z.number().min(0).max(1).default(0.6),
+    directness: z.number().min(0).max(1).default(0.5),
+    humor: z.number().min(0).max(1).default(0.3),
+    formality: z.number().min(0).max(1).default(0.5),
+  }).default({}),
+  expertise: z.array(z.string()).default([]),
+  errorStyle: z.enum(['apologetic', 'matter_of_fact', 'self_deprecating', 'professional', 'gentle', 'detailed', 'encouraging', 'terse', 'educational']).default('professional'),
+  catchphrases: z.object({
+    greeting: z.string().optional(),
+    farewell: z.string().optional(),
+    thinking: z.string().optional(),
+    success: z.string().optional(),
+    error: z.string().optional(),
+  }).default({}),
+  boundaries: z.object({
+    neverJokeAbout: z.array(z.string()).default([]),
+    neverAdviseOn: z.array(z.string()).default([]),
+  }).default({}),
+});
+
+export type AgentIdentity = z.infer<typeof AgentIdentitySchema>;
+
+export const ConfigSchema = z.object({
+  gateway: GatewayConfigSchema.default({}),
+  auth: AuthConfigSchema.default({}),
+  rateLimit: RateLimitConfigSchema.default({}),
+  pairing: PairingConfigSchema.default({}),
+  provider: ProviderConfigSchema.default({}),
+  routing: ModelRoutingSchema.default({}),
+  session: SessionConfigSchema.default({}),
+  logging: LoggingConfigSchema.default({}),
+  channels: ChannelConfigSchema.default({}),
+  voice: VoiceConfigSchema.default({}),
+  webhooks: WebhookConfigSchema.default({}),
+  dashboard: DashboardConfigSchema.default({}),
+  plugins: PluginsConfigSchema.default({}),
+  memory: MemoryConfigSchema.default({}),
+  orchestration: OrchestrationConfigSchema.default({}),
+  agent: AgentIdentitySchema.default({}),
+  modes: ModesConfigSchema.default({}),
+  research: ResearchConfigSchema.default({}),
+  // [P12] Trust / Autonomy
+  trust: TrustConfigSchema.default({}),
+  intent: IntentConfigSchema.default({}),
+  // [P6] Desktop
+  desktop: DesktopConfigSchema.default({}),
+  // [P7] Cloud
+  cloud: CloudConfigSchema.default({}),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+export type ModelRouting = z.infer<typeof ModelRoutingSchema>;
+export type OrchestrationConfig = z.infer<typeof OrchestrationConfigSchema>;
+export type ResearchConfig = z.infer<typeof ResearchConfigSchema>;
+export type TrustConfig = z.infer<typeof TrustConfigSchema>;
+export type IntentConfig = z.infer<typeof IntentConfigSchema>;
+export type ModesConfig = z.infer<typeof ModesConfigSchema>;
+
+const ENV_PREFIX = 'AUXIORA_';
+
+function camelToSnake(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter}`).toUpperCase();
+}
+
+function getEnvValue(path: string[]): string | undefined {
+  const envKey = ENV_PREFIX + path.map(camelToSnake).join('_');
+  return process.env[envKey];
+}
+
+function applyEnvOverrides(config: Record<string, unknown>, path: string[] = []): void {
+  for (const [key, value] of Object.entries(config)) {
+    const currentPath = [...path, key];
+
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      applyEnvOverrides(value as Record<string, unknown>, currentPath);
+    } else {
+      const envValue = getEnvValue(currentPath);
+      if (envValue !== undefined) {
+        if (typeof value === 'boolean') {
+          config[key] = envValue.toLowerCase() === 'true';
+        } else if (typeof value === 'number') {
+          config[key] = Number(envValue);
+        } else {
+          config[key] = envValue;
+        }
+      }
+    }
+  }
+}
+
+export async function loadConfig(): Promise<Config> {
+  const configPath = getConfigPath();
+  let rawConfig: Record<string, unknown> = {};
+
+  try {
+    const content = await fs.readFile(configPath, 'utf-8');
+    rawConfig = JSON.parse(content);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+    // File doesn't exist, use defaults
+  }
+
+  // Apply environment variable overrides
+  applyEnvOverrides(rawConfig);
+
+  // Validate and return
+  return ConfigSchema.parse(rawConfig);
+}
+
+export async function saveConfig(config: Config): Promise<void> {
+  const configPath = getConfigPath();
+  const configDir = path.dirname(configPath);
+
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+  if (!isWindows()) {
+    await fs.chmod(configPath, 0o600);
+  }
+}
+
+export async function getDefaultConfig(): Promise<Config> {
+  return ConfigSchema.parse({});
+}

package/src/validator.ts

@@ -0,0 +1,226 @@
+/**
+ * Configuration validation with detailed error messages
+ */
+
+import { type Config } from './index.js';
+import type { ZodError } from 'zod';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}
+
+export interface ValidationError {
+  path: string;
+  message: string;
+  value?: any;
+  suggestion?: string;
+}
+
+export interface ValidationWarning {
+  path: string;
+  message: string;
+  suggestion: string;
+}
+
+/**
+ * Validate configuration and provide helpful error messages
+ */
+export function validateConfig(config: Config): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  // Validate gateway configuration
+  if (config.gateway.host === '0.0.0.0' && config.auth.mode === 'none') {
+    warnings.push({
+      path: 'gateway.host',
+      message: 'Gateway bound to 0.0.0.0 with no authentication',
+      suggestion: 'Consider binding to 127.0.0.1 or enabling JWT authentication for security',
+    });
+  }
+
+  if (config.gateway.port < 1024) {
+    warnings.push({
+      path: 'gateway.port',
+      message: `Port ${config.gateway.port} requires elevated privileges`,
+      suggestion: 'Use a port >= 1024 to avoid needing root/admin access',
+    });
+  }
+
+  // Validate authentication configuration
+  if (config.auth.mode === 'jwt') {
+    if (!config.auth.jwtSecret) {
+      errors.push({
+        path: 'auth.jwtSecret',
+        message: 'JWT secret required when auth mode is "jwt"',
+        suggestion: 'Generate a secret: openssl rand -hex 32',
+      });
+    } else if (config.auth.jwtSecret.length < 32) {
+      warnings.push({
+        path: 'auth.jwtSecret',
+        message: 'JWT secret should be at least 32 characters',
+        suggestion: 'Use a longer secret for better security: openssl rand -hex 32',
+      });
+    }
+  }
+
+  if (config.auth.mode === 'password' && !config.auth.passwordHash) {
+    errors.push({
+      path: 'auth.passwordHash',
+      message: 'Password hash required when auth mode is "password"',
+      suggestion: 'Set a password using the CLI: auxiora auth set-password',
+    });
+  }
+
+  // Validate rate limiting
+  if (!config.rateLimit.enabled) {
+    warnings.push({
+      path: 'rateLimit.enabled',
+      message: 'Rate limiting is disabled',
+      suggestion: 'Enable rate limiting to prevent abuse',
+    });
+  }
+
+  if (config.rateLimit.maxRequests > 1000) {
+    warnings.push({
+      path: 'rateLimit.maxRequests',
+      message: `High rate limit (${config.rateLimit.maxRequests} requests)`,
+      suggestion: 'Consider a lower limit to prevent API quota exhaustion',
+    });
+  }
+
+  // Validate provider configuration
+  if (config.provider.primary === config.provider.fallback) {
+    warnings.push({
+      path: 'provider.fallback',
+      message: 'Fallback provider same as primary',
+      suggestion: 'Use a different provider for fallback or remove fallback',
+    });
+  }
+
+  // Validate session configuration
+  if (config.session.maxContextTokens > 200000) {
+    warnings.push({
+      path: 'session.maxContextTokens',
+      message: 'Very large context window may cause performance issues',
+      suggestion: 'Consider reducing to 100000 tokens for better performance',
+    });
+  }
+
+  if (config.session.ttlMinutes < 60) {
+    warnings.push({
+      path: 'session.ttlMinutes',
+      message: 'Short session TTL may cause frequent session loss',
+      suggestion: 'Consider at least 60 minutes for better user experience',
+    });
+  }
+
+  // Validate channel configuration
+  const enabledChannels = Object.entries(config.channels)
+    .filter(([_, channelConfig]) => channelConfig.enabled)
+    .map(([name]) => name);
+
+  if (enabledChannels.length === 0) {
+    warnings.push({
+      path: 'channels',
+      message: 'No channels enabled',
+      suggestion: 'Enable at least webchat for testing',
+    });
+  }
+
+  // Validate logging configuration
+  if (config.logging.maxFileSizeMb > 100) {
+    warnings.push({
+      path: 'logging.maxFileSizeMb',
+      message: 'Large log file size may consume significant disk space',
+      suggestion: 'Consider a smaller size with log rotation',
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Format validation errors for display
+ */
+export function formatValidationErrors(result: ValidationResult): string {
+  const lines: string[] = [];
+
+  if (result.errors.length > 0) {
+    lines.push('❌ Configuration Errors:\n');
+    for (const error of result.errors) {
+      lines.push(`  ${error.path}: ${error.message}`);
+      if (error.suggestion) {
+        lines.push(`    💡 ${error.suggestion}`);
+      }
+      lines.push('');
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push('⚠️  Configuration Warnings:\n');
+    for (const warning of result.warnings) {
+      lines.push(`  ${warning.path}: ${warning.message}`);
+      lines.push(`    💡 ${warning.suggestion}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format Zod validation errors
+ */
+export function formatZodError(error: ZodError): string {
+  const lines: string[] = ['❌ Configuration Validation Failed:\n'];
+
+  for (const issue of error.issues) {
+    const path = issue.path.join('.');
+    lines.push(`  ${path || 'config'}: ${issue.message}`);
+
+    // Add helpful suggestions based on error type
+    if (issue.code === 'invalid_type') {
+      lines.push(`    💡 Expected ${issue.expected}, got ${issue.received}`);
+    } else if (issue.code === 'invalid_enum_value') {
+      lines.push(`    💡 Valid options: ${issue.options.join(', ')}`);
+    } else if (issue.code === 'too_small') {
+      lines.push(`    💡 Minimum value: ${issue.minimum}`);
+    } else if (issue.code === 'too_big') {
+      lines.push(`    💡 Maximum value: ${issue.maximum}`);
+    }
+
+    lines.push('');
+  }
+
+  lines.push('See .env.example for configuration reference');
+
+  return lines.join('\n');
+}
+
+/**
+ * Validate and report configuration issues
+ */
+export function validateAndReport(config: Config): boolean {
+  const result = validateConfig(config);
+
+  if (!result.valid || result.warnings.length > 0) {
+    console.error(formatValidationErrors(result));
+  }
+
+  if (!result.valid) {
+    console.error('\n⛔ Cannot start with invalid configuration\n');
+    return false;
+  }
+
+  if (result.warnings.length > 0) {
+    console.warn('⚠️  Starting with warnings (see above)\n');
+  }
+
+  return true;
+}