lean-claudient-daemon 0.1.0

package/src/security/envValidation.ts

@@ -0,0 +1,321 @@
+/**
+ * Environment Validation
+ * Validates daemon security configuration at startup
+ */
+
+import { existsSync, accessSync, constants } from 'fs';
+import { dirname } from 'path';
+
+// Mock detectSecrets function since core/security is not accessible from daemon
+function detectSecrets(text: string): Array<{ severity: string }> {
+  // Placeholder for secrets detection
+  return [];
+}
+
+export interface ValidationResult {
+  passed: boolean;
+  checks: {
+    name: string;
+    status: 'PASS' | 'WARN' | 'FAIL';
+    message: string;
+  }[];
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Check if process environment contains suspicious secrets
+ */
+export function checkEnvironmentSecrets(): { status: 'PASS' | 'WARN'; message: string } {
+  const envString = JSON.stringify(process.env);
+  const findings = detectSecrets(envString);
+
+  if (findings.length === 0) {
+    return { status: 'PASS', message: 'No hardcoded secrets in environment' };
+  }
+
+  const critical = findings.filter((f) => f.severity === 'CRITICAL');
+  const high = findings.filter((f) => f.severity === 'HIGH');
+
+  if (critical.length > 0) {
+    return {
+      status: 'WARN',
+      message: `Found ${critical.length} CRITICAL and ${high.length} HIGH severity secrets in environment`,
+    };
+  }
+
+  return {
+    status: 'PASS',
+    message: `Found ${high.length} potential high-entropy strings (may be expected secrets)`,
+  };
+}
+
+/**
+ * Validate daemon port is not privileged
+ */
+export function checkDaemonPort(port: number): { status: 'PASS' | 'FAIL'; message: string } {
+  if (port < 1024) {
+    return {
+      status: 'FAIL',
+      message: `Port ${port} is privileged (<1024). Use unprivileged port or run as root (not recommended).`,
+    };
+  }
+
+  if (port > 65535) {
+    return {
+      status: 'FAIL',
+      message: `Port ${port} is invalid (>65535)`,
+    };
+  }
+
+  return {
+    status: 'PASS',
+    message: `Daemon port ${port} is valid`,
+  };
+}
+
+/**
+ * Check if log directory is writable
+ */
+export function checkLogDirectory(logDir: string): { status: 'PASS' | 'WARN'; message: string } {
+  // Create directory if it doesn't exist
+  if (!existsSync(logDir)) {
+    try {
+      const parentDir = dirname(logDir);
+      if (!existsSync(parentDir)) {
+        return {
+          status: 'WARN',
+          message: `Log directory parent doesn't exist: ${parentDir}`,
+        };
+      }
+
+      accessSync(parentDir, constants.W_OK);
+      return {
+        status: 'PASS',
+        message: `Log directory can be created: ${logDir}`,
+      };
+    } catch {
+      return {
+        status: 'WARN',
+        message: `Cannot write to log directory parent: ${dirname(logDir)}`,
+      };
+    }
+  }
+
+  try {
+    accessSync(logDir, constants.W_OK);
+    return {
+      status: 'PASS',
+      message: `Log directory is writable: ${logDir}`,
+    };
+  } catch {
+    return {
+      status: 'WARN',
+      message: `Log directory is not writable: ${logDir}`,
+    };
+  }
+}
+
+/**
+ * Check if database path is writable
+ */
+export function checkDatabasePath(dbPath: string): { status: 'PASS' | 'WARN'; message: string } {
+  const dbDir = dirname(dbPath);
+
+  if (!existsSync(dbDir)) {
+    const parentDir = dirname(dbDir);
+    try {
+      accessSync(parentDir, constants.W_OK);
+      return {
+        status: 'PASS',
+        message: `Database directory can be created: ${dbDir}`,
+      };
+    } catch {
+      return {
+        status: 'WARN',
+        message: `Cannot write to database directory parent: ${parentDir}`,
+      };
+    }
+  }
+
+  try {
+    accessSync(dbDir, constants.W_OK);
+    return {
+      status: 'PASS',
+      message: `Database directory is writable: ${dbDir}`,
+    };
+  } catch {
+    return {
+      status: 'WARN',
+      message: `Database directory is not writable: ${dbDir}`,
+    };
+  }
+}
+
+/**
+ * Check required environment variables
+ */
+export function checkRequiredEnvVars(required: string[]): { status: 'PASS' | 'FAIL'; message: string } {
+  const missing = required.filter((key) => !process.env[key]);
+
+  if (missing.length === 0) {
+    return {
+      status: 'PASS',
+      message: `All required environment variables are set`,
+    };
+  }
+
+  return {
+    status: 'FAIL',
+    message: `Missing environment variables: ${missing.join(', ')}`,
+  };
+}
+
+/**
+ * Check for deprecated or insecure environment variables
+ */
+export function checkDeprecatedEnvVars(): { status: 'PASS' | 'WARN'; message: string } {
+  const deprecated = [
+    'DEBUG',
+    'VERBOSE',
+    'LOG_LEVEL', // prefer structured logging
+  ];
+
+  const found = deprecated.filter((key) => process.env[key]);
+
+  if (found.length === 0) {
+    return {
+      status: 'PASS',
+      message: 'No deprecated environment variables detected',
+    };
+  }
+
+  return {
+    status: 'WARN',
+    message: `Found deprecated environment variables: ${found.join(', ')}`,
+  };
+}
+
+/**
+ * Validate NODE_ENV is set appropriately
+ */
+export function checkNodeEnv(): { status: 'PASS' | 'WARN'; message: string } {
+  const nodeEnv = process.env.NODE_ENV || 'development';
+
+  if (nodeEnv === 'production' || nodeEnv === 'staging' || nodeEnv === 'development') {
+    return {
+      status: 'PASS',
+      message: `NODE_ENV is set to: ${nodeEnv}`,
+    };
+  }
+
+  return {
+    status: 'WARN',
+    message: `NODE_ENV has unexpected value: ${nodeEnv}. Should be production, staging, or development.`,
+  };
+}
+
+/**
+ * Check memory and resource limits
+ */
+export function checkResourceLimits(): { status: 'PASS' | 'WARN'; message: string } {
+  const memUsage = process.memoryUsage();
+  const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
+  const heapTotalMB = Math.round(memUsage.heapTotal / 1024 / 1024);
+
+  if (heapTotalMB > 4096) {
+    return {
+      status: 'WARN',
+      message: `Daemon has high heap allocation: ${heapTotalMB}MB (${heapUsedMB}MB used)`,
+    };
+  }
+
+  return {
+    status: 'PASS',
+    message: `Memory usage: ${heapUsedMB}MB / ${heapTotalMB}MB`,
+  };
+}
+
+/**
+ * Full validation suite
+ */
+export function validateEnvironment(config: {
+  port: number;
+  logDir: string;
+  dbPath: string;
+  requiredEnvVars?: string[];
+  critical?: boolean;
+}): ValidationResult {
+  const checks = [
+    { name: 'Environment Secrets', ...checkEnvironmentSecrets() },
+    { name: 'Daemon Port', ...checkDaemonPort(config.port) },
+    { name: 'Log Directory', ...checkLogDirectory(config.logDir) },
+    { name: 'Database Path', ...checkDatabasePath(config.dbPath) },
+    { name: 'NODE_ENV', ...checkNodeEnv() },
+    { name: 'Deprecated Variables', ...checkDeprecatedEnvVars() },
+    { name: 'Resource Limits', ...checkResourceLimits() },
+  ];
+
+  if (config.requiredEnvVars && config.requiredEnvVars.length > 0) {
+    checks.push({
+      name: 'Required Variables',
+      ...checkRequiredEnvVars(config.requiredEnvVars),
+    });
+  }
+
+  const failures = checks.filter((c) => c.status === 'FAIL');
+  const warnings = checks.filter((c) => c.status === 'WARN');
+  const errors = failures.map((c) => c.message);
+
+  // If critical mode and failures exist, fail entire validation
+  const passed = config.critical ? failures.length === 0 : true;
+
+  return {
+    passed,
+    checks,
+    errors,
+    warnings: warnings.map((c) => c.message),
+  };
+}
+
+/**
+ * Format validation result for console output
+ */
+export function formatValidationResult(result: ValidationResult): string {
+  const lines: string[] = [];
+
+  lines.push('\n=== Security Environment Validation ===\n');
+
+  for (const check of result.checks) {
+    const symbol = check.status === 'PASS' ? '✓' : check.status === 'WARN' ? '⚠' : '✗';
+    lines.push(`${symbol} ${check.name}: ${check.message}`);
+  }
+
+  if (result.errors.length > 0) {
+    lines.push('\nErrors:');
+    for (const error of result.errors) {
+      lines.push(`  ✗ ${error}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push('\nWarnings:');
+    for (const warning of result.warnings) {
+      lines.push(`  ⚠ ${warning}`);
+    }
+  }
+
+  lines.push(`\nValidation Status: ${result.passed ? 'PASSED' : 'FAILED'}\n`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Exit with validation error
+ */
+export function exitOnValidationFailure(result: ValidationResult, exitCode = 1): void {
+  if (!result.passed) {
+    console.error(formatValidationResult(result));
+    process.exit(exitCode);
+  }
+}

package/src/service.ts

@@ -0,0 +1,62 @@
+import express from 'express';
+import { MetricsStore } from './metricsStore.js';
+import { createApiRouter } from './api.js';
+import fs from 'fs';
+import path from 'path';
+
+export class LeanClaudientDaemon {
+  private app = express();
+  private metricsStore: MetricsStore;
+  private port: number;
+  private logPath: string;
+
+  constructor(port: number = 9831, logPath?: string) {
+    this.port = port;
+    this.logPath = logPath || path.join(process.env.HOME!, '.lean-claudient', 'daemon.log');
+    this.metricsStore = new MetricsStore();
+    this.setupExpress();
+  }
+
+  private setupExpress() {
+    this.app.use(express.json());
+    this.app.use('/api', createApiRouter(this.metricsStore));
+
+    this.app.get('/health', (req, res) => {
+      res.json({ status: 'ok', uptime: process.uptime(), pid: process.pid });
+    });
+  }
+
+  async start() {
+    const logDir = path.dirname(this.logPath);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    this.log('Lean Claudient Daemon starting...');
+
+    await this.metricsStore.initialize();
+
+    this.app.listen(this.port, () => {
+      this.log(`Daemon listening on port ${this.port}`);
+    });
+
+    process.on('SIGTERM', () => this.shutdown());
+    process.on('SIGINT', () => this.shutdown());
+
+    await new Promise(() => {});
+  }
+
+  private async shutdown() {
+    this.log('Shutting down daemon...');
+    await this.metricsStore.close();
+    this.log('Daemon stopped cleanly');
+    process.exit(0);
+  }
+
+  private log(msg: string) {
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] ${msg}\n`;
+    console.log(line);
+    fs.appendFileSync(this.logPath, line);
+  }
+}

package/src/validation/schemas.ts

@@ -0,0 +1,190 @@
+/**
+ * Input Validation Schemas
+ * Zod schemas for all API inputs and daemon operations
+ */
+
+import { z } from 'zod';
+
+/**
+ * UUID validation - 36 characters with hyphens
+ */
+export const uuidSchema = z.string().uuid().describe('Valid UUID format');
+
+/**
+ * Session ID schema
+ */
+export const sessionIdSchema = z
+  .string()
+  .uuid()
+  .describe('Session ID must be a valid UUID');
+
+/**
+ * Metrics record schema
+ */
+export const metricsRecordSchema = z.object({
+  sessionId: sessionIdSchema,
+  timestamp: z.number().int().positive().describe('Unix timestamp'),
+  inputTokens: z.number().int().nonnegative().describe('Input tokens used'),
+  outputTokens: z.number().int().nonnegative().describe('Output tokens generated'),
+  totalTokens: z.number().int().nonnegative().describe('Total tokens (input + output)'),
+  cost: z.number().nonnegative().describe('Cost in USD'),
+  savedTokens: z
+    .number()
+    .int()
+    .nonnegative()
+    .describe('Tokens saved through compression'),
+  compressionRatio: z.number().nonnegative().describe('Compression ratio percentage'),
+  subagentCount: z.number().int().nonnegative().describe('Number of subagents used'),
+});
+
+export type MetricsRecord = z.infer<typeof metricsRecordSchema>;
+
+/**
+ * Budget status schema
+ */
+export const budgetStatusSchema = z.object({
+  sessionId: sessionIdSchema,
+  remainingTokens: z.number().int().nonnegative(),
+  totalBudget: z.number().int().positive(),
+  usedTokens: z.number().int().nonnegative(),
+  percentUsed: z.number().min(0).max(100),
+  status: z.enum(['ACTIVE', 'WARNING', 'CRITICAL', 'EXCEEDED']),
+});
+
+export type BudgetStatus = z.infer<typeof budgetStatusSchema>;
+
+/**
+ * Metrics payload schema for POST /api/metrics
+ */
+export const metricsPayloadSchema = z.object({
+  sessionId: sessionIdSchema,
+  metrics: metricsRecordSchema.omit({ sessionId: true }),
+});
+
+export type MetricsPayload = z.infer<typeof metricsPayloadSchema>;
+
+/**
+ * Checkpoint schema - valid git commit hash or checkpoint identifier
+ */
+export const checkpointSchema = z
+  .object({
+    checkpoint: z.string().min(1).max(1000).describe('Checkpoint identifier or hash'),
+  })
+  .strict();
+
+export type CheckpointPayload = z.infer<typeof checkpointSchema>;
+
+/**
+ * Budget schema for budget updates
+ */
+export const budgetSchema = z
+  .object({
+    sessionId: sessionIdSchema,
+    totalBudget: z.number().int().positive().describe('Total token budget'),
+    softLimit: z.number().int().positive().optional().describe('Warning threshold'),
+    hardLimit: z.number().int().positive().optional().describe('Absolute maximum'),
+  })
+  .strict();
+
+export type BudgetPayload = z.infer<typeof budgetSchema>;
+
+/**
+ * Session creation schema
+ */
+export const sessionCreationSchema = z
+  .object({
+    sessionId: sessionIdSchema,
+    budget: z.number().int().positive().describe('Initial token budget'),
+    metadata: z.record(z.any()).optional().describe('Custom metadata'),
+  })
+  .strict();
+
+export type SessionCreation = z.infer<typeof sessionCreationSchema>;
+
+/**
+ * Query validation schema
+ */
+export const queryParamSchema = z.object({
+  sessionId: sessionIdSchema.optional(),
+  startTime: z.number().int().nonnegative().optional(),
+  endTime: z.number().int().nonnegative().optional(),
+  limit: z.number().int().min(1).max(1000).optional(),
+});
+
+export type QueryParams = z.infer<typeof queryParamSchema>;
+
+/**
+ * Error response schema
+ */
+export const errorResponseSchema = z.object({
+  error: z.string(),
+  code: z.string().optional(),
+  details: z.any().optional(),
+});
+
+/**
+ * Success response schema
+ */
+export const successResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.any().optional(),
+  message: z.string().optional(),
+});
+
+/**
+ * Health check response schema
+ */
+export const healthCheckSchema = z.object({
+  running: z.boolean(),
+  uptime: z.number().int().nonnegative(),
+  memory: z.number().nonnegative(),
+  pid: z.number().int().positive(),
+  timestamp: z.string().datetime().optional(),
+  version: z.string().optional(),
+});
+
+/**
+ * Aggregate metrics schema
+ */
+export const aggregateMetricsSchema = z.object({
+  totalInputTokens: z.number().int().nonnegative(),
+  totalOutputTokens: z.number().int().nonnegative(),
+  totalTokens: z.number().int().nonnegative(),
+  totalCost: z.string(),
+  totalSavedTokens: z.number().int().nonnegative(),
+  averageCompressionRatio: z.number().nonnegative(),
+  sessionCount: z.number().int().nonnegative(),
+  averageSubagentCount: z.number().int().nonnegative(),
+});
+
+export type AggregateMetrics = z.infer<typeof aggregateMetricsSchema>;
+
+/**
+ * Validate UUID in path parameter
+ */
+export function validateUUID(id: string): string | null {
+  try {
+    return uuidSchema.parse(id);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safe parse helper - returns [data, error]
+ */
+export function safeParse<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown
+): [T | null, string | null] {
+  try {
+    const result = schema.parse(data);
+    return [result, null];
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const messages = error.errors.map((e) => `${e.path.join('.')}: ${e.message}`);
+      return [null, messages.join('; ')];
+    }
+    return [null, String(error)];
+  }
+}