lean-claudient-daemon 0.1.0

package/dist/middleware/validation.js

@@ -0,0 +1,181 @@
+/**
+ * Input Validation Middleware
+ * Express middleware for validating request bodies and parameters
+ */
+import { z } from 'zod';
+/**
+ * Create validation middleware for a given schema
+ */
+export function createValidationMiddleware(schema) {
+    return (req, res, next) => {
+        try {
+            const validated = schema.parse(req.body);
+            req.validatedBody = validated;
+            next();
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const errors = error.errors.map((e) => ({
+                    field: e.path.join('.'),
+                    message: e.message,
+                }));
+                return res.status(400).json({
+                    error: 'Validation failed',
+                    code: 'VALIDATION_ERROR',
+                    details: errors,
+                });
+            }
+            return res.status(400).json({
+                error: 'Invalid request',
+                code: 'INVALID_REQUEST',
+            });
+        }
+    };
+}
+/**
+ * Validate request body
+ */
+export function validateRequestBody(data, schema) {
+    try {
+        const parsed = schema.parse(data);
+        return { valid: true, data: parsed };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const errors = error.errors.map((e) => ({
+                field: e.path.join('.'),
+                message: e.message,
+            }));
+            return { valid: false, errors };
+        }
+        return {
+            valid: false,
+            errors: [{ field: 'unknown', message: 'Validation failed' }],
+        };
+    }
+}
+/**
+ * Validate UUID in path parameter
+ */
+export function validatePathUUID(req, res, next, id, paramName = 'id') {
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (!uuidPattern.test(id)) {
+        return res.status(400).json({
+            error: 'Invalid UUID format',
+            code: 'INVALID_UUID',
+            details: {
+                field: paramName,
+                message: 'Must be a valid UUID (36 characters with hyphens)',
+            },
+        });
+    }
+    next();
+}
+/**
+ * Middleware to validate UUID parameter 'id'
+ */
+export function validateIdParam(req, res, next) {
+    const { id } = req.params;
+    if (!id) {
+        return res.status(400).json({
+            error: 'Missing id parameter',
+            code: 'MISSING_PARAM',
+        });
+    }
+    validatePathUUID(req, res, next, id, 'id');
+}
+/**
+ * Middleware to validate UUID parameter 'sessionId'
+ */
+export function validateSessionIdParam(req, res, next) {
+    const { sessionId } = req.params;
+    if (!sessionId) {
+        return res.status(400).json({
+            error: 'Missing sessionId parameter',
+            code: 'MISSING_PARAM',
+        });
+    }
+    validatePathUUID(req, res, next, sessionId, 'sessionId');
+}
+/**
+ * Middleware to ensure Content-Type is application/json
+ */
+export function validateContentType(req, res, next) {
+    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+        const contentType = req.get('Content-Type');
+        if (!contentType || !contentType.includes('application/json')) {
+            return res.status(415).json({
+                error: 'Unsupported Media Type',
+                code: 'UNSUPPORTED_MEDIA_TYPE',
+                details: {
+                    message: 'Content-Type must be application/json',
+                },
+            });
+        }
+    }
+    next();
+}
+/**
+ * Middleware to limit request body size
+ */
+export function validateRequestSize(maxSize = '1mb') {
+    return (req, res, next) => {
+        if (!req.get('Content-Length')) {
+            return next();
+        }
+        const sizeBytes = parseSize(maxSize);
+        const contentLength = parseInt(req.get('Content-Length') || '0', 10);
+        if (contentLength > sizeBytes) {
+            return res.status(413).json({
+                error: 'Payload Too Large',
+                code: 'PAYLOAD_TOO_LARGE',
+                details: {
+                    maxSize,
+                    received: `${(contentLength / 1024).toFixed(2)}kb`,
+                },
+            });
+        }
+        next();
+    };
+}
+/**
+ * Parse size string to bytes
+ */
+function parseSize(size) {
+    const units = {
+        b: 1,
+        kb: 1024,
+        mb: 1024 * 1024,
+        gb: 1024 * 1024 * 1024,
+    };
+    const match = size.toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(kb|mb|gb|b)?$/);
+    if (!match)
+        return 1024 * 1024; // default 1mb
+    const [, number, unit = 'b'] = match;
+    return Math.floor(parseFloat(number) * (units[unit] || 1));
+}
+/**
+ * Validate query parameters
+ */
+export function validateQueryParams(data, allowedKeys) {
+    if (typeof data !== 'object' || data === null) {
+        return { valid: false, errors: [{ field: 'query', message: 'Invalid query parameters' }] };
+    }
+    const errors = [];
+    const validated = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (!allowedKeys.includes(key)) {
+            errors.push({
+                field: key,
+                message: `Unknown parameter: ${key}`,
+            });
+        }
+        else {
+            validated[key] = value;
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return { valid: true, data: validated };
+}

package/dist/security/envValidation.js

@@ -0,0 +1,266 @@
+/**
+ * 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) {
+    // Placeholder for secrets detection
+    return [];
+}
+/**
+ * Check if process environment contains suspicious secrets
+ */
+export function checkEnvironmentSecrets() {
+    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) {
+    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) {
+    // 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) {
+    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) {
+    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() {
+    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() {
+    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() {
+    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) {
+    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) {
+    const lines = [];
+    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, exitCode = 1) {
+    if (!result.passed) {
+        console.error(formatValidationResult(result));
+        process.exit(exitCode);
+    }
+}

package/dist/service.js

@@ -0,0 +1,47 @@
+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 {
+    constructor(port = 9831, logPath) {
+        this.app = express();
+        this.port = port;
+        this.logPath = logPath || path.join(process.env.HOME, '.lean-claudient', 'daemon.log');
+        this.metricsStore = new MetricsStore();
+        this.setupExpress();
+    }
+    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(() => { });
+    }
+    async shutdown() {
+        this.log('Shutting down daemon...');
+        await this.metricsStore.close();
+        this.log('Daemon stopped cleanly');
+        process.exit(0);
+    }
+    log(msg) {
+        const timestamp = new Date().toISOString();
+        const line = `[${timestamp}] ${msg}\n`;
+        console.log(line);
+        fs.appendFileSync(this.logPath, line);
+    }
+}

package/dist/validation/schemas.js

@@ -0,0 +1,157 @@
+/**
+ * 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'),
+});
+/**
+ * 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']),
+});
+/**
+ * Metrics payload schema for POST /api/metrics
+ */
+export const metricsPayloadSchema = z.object({
+    sessionId: sessionIdSchema,
+    metrics: metricsRecordSchema.omit({ sessionId: true }),
+});
+/**
+ * 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();
+/**
+ * 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();
+/**
+ * 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();
+/**
+ * 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(),
+});
+/**
+ * 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(),
+});
+/**
+ * Validate UUID in path parameter
+ */
+export function validateUUID(id) {
+    try {
+        return uuidSchema.parse(id);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Safe parse helper - returns [data, error]
+ */
+export function safeParse(schema, data) {
+    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)];
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "lean-claudient-daemon",
+  "version": "0.1.0",
+  "description": "Universal status daemon for Lean Claudient: token budget enforcement across CLIs",
+  "type": "module",
+  "main": "dist/service.js",
+  "bin": {
+    "lean-claudient-daemon": "dist/bin/daemon.js"
+  },
+  "author": "Lean Claudient Contributors",
+  "license": "MIT",
+  "homepage": "https://github.com/Claudient/LeanClaudient#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Claudient/LeanClaudient.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Claudient/LeanClaudient/issues"
+  },
+  "keywords": [
+    "claude",
+    "daemon",
+    "token-budget",
+    "llm",
+    "anthropic"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "echo 'tests pending'",
+    "test:watch": "echo 'tests pending'",
+    "test:coverage": "echo 'tests pending'",
+    "lint": "echo 'linter pending'",
+    "format": "echo 'formatter pending'",
+    "type-check": "tsc --noEmit",
+    "start": "node dist/bin/daemon.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "sqlite3": "^5.1.6",
+    "commander": "^11.1.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.2"
+  }
+}