profclaw 0.0.1-beta.1

package/dist/utils/security.js

@@ -0,0 +1,347 @@
+/**
+ * Security utilities for input validation and XSS prevention
+ */
+/**
+ * Maximum allowed file sizes by type (in bytes)
+ */
+export const FILE_SIZE_LIMITS = {
+    image: 10 * 1024 * 1024, // 10MB for images
+    document: 25 * 1024 * 1024, // 25MB for documents
+    attachment: 50 * 1024 * 1024, // 50MB for general attachments
+    avatar: 2 * 1024 * 1024, // 2MB for avatars
+};
+/**
+ * Allowed MIME types for file uploads
+ */
+export const ALLOWED_MIME_TYPES = {
+    image: ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'],
+    document: [
+        'application/pdf',
+        'application/msword',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'application/vnd.ms-excel',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        'text/plain',
+        'text/markdown',
+        'text/csv',
+    ],
+    code: [
+        'text/javascript',
+        'application/javascript',
+        'text/typescript',
+        'application/json',
+        'text/html',
+        'text/css',
+        'text/x-python',
+        'text/x-java-source',
+    ],
+};
+/**
+ * HTML entities for XSS prevention
+ */
+const HTML_ENTITIES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+    '/': '&#x2F;',
+    '`': '&#x60;',
+    '=': '&#x3D;',
+};
+/**
+ * Escape HTML special characters to prevent XSS attacks
+ * Use this for any user-generated content that will be rendered as HTML
+ */
+export function escapeHtml(input) {
+    return input.replace(/[&<>"'`=/]/g, (char) => HTML_ENTITIES[char] || char);
+}
+/**
+ * Sanitize a string by removing potentially dangerous characters
+ * Use for things like filenames, labels, etc.
+ */
+export function sanitizeString(input, options) {
+    let result = input;
+    // Remove null bytes
+    result = result.replace(/\0/g, '');
+    // Remove control characters (except newlines if allowed)
+    if (options?.allowNewlines) {
+        result = result.replace(/[\x00-\x09\x0B\x0C\x0E-\x1F\x7F]/g, '');
+    }
+    else {
+        result = result.replace(/[\x00-\x1F\x7F]/g, '');
+    }
+    // Escape HTML unless explicitly allowed
+    if (!options?.allowHtml) {
+        result = escapeHtml(result);
+    }
+    // Truncate to max length
+    if (options?.maxLength && result.length > options.maxLength) {
+        result = result.slice(0, options.maxLength);
+    }
+    return result.trim();
+}
+/**
+ * Dangerous shell metacharacters and injection patterns
+ */
+const SHELL_INJECTION_PATTERNS = [
+    /[;&|`$(){}[\]<>\\]/, // Shell metacharacters
+    /\$\(/, // Command substitution
+    /`/, // Backtick substitution
+    /\|\|/, // OR operator
+    /&&/, // AND operator
+    /[><]/, // Redirects
+    /\n|\r/, // Newlines (command separators)
+    /\0/, // Null byte
+];
+/**
+ * Allowlist of safe commands for scheduled jobs
+ * Extend this list based on your application needs
+ */
+export const ALLOWED_SCRIPT_COMMANDS = new Set([
+    // Node/npm commands
+    'node',
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    // System utilities
+    'curl',
+    'wget',
+    'echo',
+    'date',
+    // Database utilities
+    'sqlite3',
+    // Git
+    'git',
+]);
+/**
+ * Validate a command to prevent command injection
+ * Returns validation result with detailed error messages
+ */
+export function validateCommand(command, args) {
+    // Check the command itself
+    if (!command || typeof command !== 'string') {
+        return { valid: false, error: 'Command is required' };
+    }
+    // Extract base command (remove path)
+    const baseCommand = command.includes('/')
+        ? command.split('/').pop() || command
+        : command;
+    // Check if command is in allowlist
+    if (!ALLOWED_SCRIPT_COMMANDS.has(baseCommand)) {
+        return {
+            valid: false,
+            error: `Command '${baseCommand}' is not in the allowlist. Allowed commands: ${[...ALLOWED_SCRIPT_COMMANDS].join(', ')}`
+        };
+    }
+    // Check command for injection patterns
+    for (const pattern of SHELL_INJECTION_PATTERNS) {
+        if (pattern.test(command)) {
+            return { valid: false, error: 'Command contains potentially dangerous characters' };
+        }
+    }
+    // Validate and sanitize arguments
+    const sanitizedArgs = [];
+    if (args) {
+        for (const arg of args) {
+            if (typeof arg !== 'string') {
+                return { valid: false, error: 'Arguments must be strings' };
+            }
+            // Check each argument for injection
+            for (const pattern of SHELL_INJECTION_PATTERNS) {
+                if (pattern.test(arg)) {
+                    return {
+                        valid: false,
+                        error: `Argument '${arg.slice(0, 20)}...' contains potentially dangerous characters`
+                    };
+                }
+            }
+            // Sanitize: escape single quotes and wrap in quotes if has spaces
+            let sanitized = arg;
+            if (arg.includes(' ') || arg.includes("'") || arg.includes('"')) {
+                // Use single quotes and escape internal single quotes
+                sanitized = "'" + arg.replace(/'/g, "'\\''") + "'";
+            }
+            sanitizedArgs.push(sanitized);
+        }
+    }
+    return {
+        valid: true,
+        sanitizedCommand: command,
+        sanitizedArgs,
+    };
+}
+/**
+ * Sanitize a filename to prevent path traversal and other attacks
+ */
+export function sanitizeFilename(filename) {
+    // Remove path separators
+    let result = filename.replace(/[/\\]/g, '');
+    // Remove leading dots (hidden files / directory traversal)
+    result = result.replace(/^\.+/, '');
+    // Remove control characters
+    result = result.replace(/[\x00-\x1F\x7F]/g, '');
+    // Remove potentially dangerous characters
+    result = result.replace(/[<>:"|?*]/g, '');
+    // Limit length
+    if (result.length > 255) {
+        const ext = result.slice(result.lastIndexOf('.'));
+        const name = result.slice(0, result.lastIndexOf('.'));
+        result = name.slice(0, 255 - ext.length) + ext;
+    }
+    // If nothing left, use default
+    return result || 'unnamed_file';
+}
+/**
+ * Validate file upload metadata
+ */
+export function validateFileUpload(file, options) {
+    const errors = [];
+    // Check file size
+    const maxSize = options?.maxSize ??
+        (options?.category ? FILE_SIZE_LIMITS[options.category] : FILE_SIZE_LIMITS.attachment);
+    if (file.fileSize && file.fileSize > maxSize) {
+        const maxMB = (maxSize / (1024 * 1024)).toFixed(1);
+        const actualMB = (file.fileSize / (1024 * 1024)).toFixed(1);
+        errors.push(`File size ${actualMB}MB exceeds maximum allowed ${maxMB}MB`);
+    }
+    // Check file type if restrictions specified
+    if (options?.allowedTypes && file.fileType) {
+        if (!options.allowedTypes.includes(file.fileType)) {
+            errors.push(`File type '${file.fileType}' is not allowed`);
+        }
+    }
+    // Validate filename
+    const sanitizedName = sanitizeFilename(file.fileName);
+    if (sanitizedName !== file.fileName) {
+        // Name was modified, could indicate attack attempt
+        errors.push('Filename contains invalid characters');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Validate URL to prevent SSRF and unsafe redirects
+ */
+export function validateUrl(url, options) {
+    try {
+        const parsed = new URL(url);
+        // Check protocol
+        const allowedProtocols = options?.allowedProtocols ?? ['https:', 'http:'];
+        if (!allowedProtocols.includes(parsed.protocol)) {
+            return { valid: false, error: `Protocol ${parsed.protocol} not allowed` };
+        }
+        // Block localhost/internal IPs if specified
+        if (options?.blockLocalhost !== false) {
+            const host = parsed.hostname.toLowerCase();
+            const localPatterns = [
+                'localhost',
+                '127.0.0.1',
+                '0.0.0.0',
+                '::1',
+                /^10\./,
+                /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+                /^192\.168\./,
+                /^169\.254\./,
+            ];
+            for (const pattern of localPatterns) {
+                if (typeof pattern === 'string') {
+                    if (host === pattern || host.endsWith('.' + pattern)) {
+                        return { valid: false, error: 'Internal URLs not allowed' };
+                    }
+                }
+                else if (pattern.test(host)) {
+                    return { valid: false, error: 'Internal URLs not allowed' };
+                }
+            }
+        }
+        // Check allowed hosts if specified
+        if (options?.allowedHosts && options.allowedHosts.length > 0) {
+            if (!options.allowedHosts.includes(parsed.hostname)) {
+                return { valid: false, error: `Host ${parsed.hostname} not in allowed list` };
+            }
+        }
+        return { valid: true };
+    }
+    catch {
+        return { valid: false, error: 'Invalid URL format' };
+    }
+}
+/**
+ * Check if a redirect URL is safe (same-origin or relative path)
+ * Use this to prevent open redirect vulnerabilities
+ */
+export function isSafeRedirectUrl(redirectUrl, requestUrl) {
+    try {
+        // Relative paths starting with / are safe (but not //)
+        if (redirectUrl.startsWith('/') && !redirectUrl.startsWith('//')) {
+            return true;
+        }
+        // Parse URLs and compare origins
+        const request = new URL(requestUrl);
+        const target = new URL(redirectUrl, request.origin);
+        return target.origin === request.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Redact sensitive values from objects before logging
+ * Returns a deep copy with sensitive fields replaced
+ */
+export function redactSensitive(obj, additionalKeys) {
+    // All keys here should be lowercase since we compare against key.toLowerCase()
+    const sensitiveKeys = new Set([
+        'password',
+        'token',
+        'secret',
+        'apikey',
+        'api_key',
+        'accesstoken',
+        'access_token',
+        'refreshtoken',
+        'refresh_token',
+        'sessiontoken',
+        'session_token',
+        'authorization',
+        'cookie',
+        'credentials',
+        'privatekey',
+        'private_key',
+        ...(additionalKeys?.map(k => k.toLowerCase()) ?? []),
+    ]);
+    function redact(value, key) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        // Check if this key should be redacted
+        if (key && sensitiveKeys.has(key.toLowerCase())) {
+            return '[REDACTED]';
+        }
+        if (typeof value === 'string') {
+            // Redact values that look like secrets
+            if (value.length > 20 && /^[a-zA-Z0-9+/=_-]+$/.test(value)) {
+                // Looks like a base64 or JWT token
+                return value.slice(0, 8) + '...[REDACTED]';
+            }
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => redact(item));
+        }
+        if (typeof value === 'object') {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = redact(v, k);
+            }
+            return result;
+        }
+        return value;
+    }
+    return redact(obj);
+}
+//# sourceMappingURL=security.js.map

package/dist/voice/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Voice I/O Service Coordinator
+ *
+ * Provides a unified interface for:
+ * - STT (speech-to-text) via OpenAI Whisper or Deepgram
+ * - TTS (text-to-speech) via OpenAI TTS, ElevenLabs, or system fallback
+ *
+ * Provider selection is based on available environment variables.
+ */
+export interface TranscribeOptions {
+    /** ISO 639-1 language code (e.g. 'en', 'fr'). Auto-detected if omitted. */
+    language?: string;
+    /** Model identifier: 'whisper-1', 'deepgram-nova-2', etc. */
+    model?: string;
+    /** Explicit provider override. */
+    provider?: 'whisper' | 'deepgram';
+    /** Audio format hint: 'wav', 'mp3', 'webm', 'ogg', etc. */
+    format?: string;
+}
+export interface TranscribeResult {
+    text: string;
+    language?: string;
+    duration_ms?: number;
+    confidence?: number;
+    segments?: {
+        start: number;
+        end: number;
+        text: string;
+    }[];
+}
+export interface SynthesizeOptions {
+    /** Voice name or ID. */
+    voice?: string;
+    /** Model identifier: 'tts-1', 'tts-1-hd', 'eleven_multilingual_v2'. */
+    model?: string;
+    /** Explicit provider override. */
+    provider?: 'openai' | 'elevenlabs' | 'system';
+    /** Playback speed multiplier (0.25 to 4.0). */
+    speed?: number;
+    /** Output audio format. */
+    format?: 'mp3' | 'opus' | 'aac' | 'wav';
+}
+export interface SynthesizeResult {
+    audio: Buffer;
+    format: string;
+    duration_ms?: number;
+    characters_used?: number;
+}
+export interface VoiceInfo {
+    id: string;
+    name: string;
+    provider: string;
+    language?: string;
+    gender?: string;
+    preview_url?: string;
+}
+export interface VoiceService {
+    transcribe(audio: Buffer, options?: TranscribeOptions): Promise<TranscribeResult>;
+    synthesize(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult>;
+    getAvailableVoices(): Promise<VoiceInfo[]>;
+    /** Alias for getAvailableVoices - lists all voices across configured providers. */
+    listVoices(): Promise<VoiceInfo[]>;
+    isSTTAvailable(): boolean;
+    isTTSAvailable(): boolean;
+    /** Returns the active TTS provider name, or null if none configured. */
+    getTTSProvider(): string | null;
+    /** Returns the active STT provider name, or null if none configured. */
+    getSTTProvider(): string | null;
+}
+/**
+ * Returns the shared VoiceService singleton.
+ * Initializes it on first call and probes system TTS availability.
+ */
+export declare function getVoiceService(): Promise<VoiceService>;
+/**
+ * Reset the singleton (useful in tests).
+ */
+export declare function resetVoiceService(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/voice/index.js

@@ -0,0 +1,144 @@
+/**
+ * Voice I/O Service Coordinator
+ *
+ * Provides a unified interface for:
+ * - STT (speech-to-text) via OpenAI Whisper or Deepgram
+ * - TTS (text-to-speech) via OpenAI TTS, ElevenLabs, or system fallback
+ *
+ * Provider selection is based on available environment variables.
+ */
+import { logger } from '../utils/logger.js';
+import { transcribeWithWhisper } from './stt/whisper.js';
+import { synthesizeWithOpenAI, getOpenAIVoices, } from './tts/openai-tts.js';
+import { synthesizeWithElevenLabs, getElevenLabsVoices, } from './tts/elevenlabs.js';
+import { synthesizeWithSystem, isSystemTTSAvailable, probeSystemTTSAvailability, } from './tts/system.js';
+// Provider detection helpers
+function detectSTTProvider() {
+    if (process.env.OPENAI_API_KEY)
+        return 'whisper';
+    if (process.env.DEEPGRAM_API_KEY)
+        return 'deepgram';
+    return null;
+}
+function detectTTSProvider() {
+    if (process.env.ELEVENLABS_API_KEY)
+        return 'elevenlabs';
+    if (process.env.OPENAI_API_KEY)
+        return 'openai';
+    if (isSystemTTSAvailable())
+        return 'system';
+    return null;
+}
+// VoiceServiceImpl
+class VoiceServiceImpl {
+    sttProvider;
+    ttsProvider;
+    constructor() {
+        this.sttProvider = detectSTTProvider();
+        this.ttsProvider = detectTTSProvider();
+        logger.info('[Voice] Service initialized', {
+            stt: this.sttProvider ?? 'unavailable',
+            tts: this.ttsProvider ?? 'unavailable',
+        });
+    }
+    isSTTAvailable() {
+        return this.sttProvider !== null;
+    }
+    isTTSAvailable() {
+        return this.ttsProvider !== null;
+    }
+    getTTSProvider() {
+        return this.ttsProvider;
+    }
+    getSTTProvider() {
+        return this.sttProvider;
+    }
+    async listVoices() {
+        return this.getAvailableVoices();
+    }
+    async transcribe(audio, options) {
+        // Allow explicit override via options.provider
+        const provider = options?.provider ?? this.sttProvider;
+        if (!provider) {
+            throw new Error('No STT provider available. Set OPENAI_API_KEY or DEEPGRAM_API_KEY.');
+        }
+        logger.info('[Voice] Transcribing', { provider, bufferSize: audio.length });
+        switch (provider) {
+            case 'whisper':
+                return transcribeWithWhisper(audio, options);
+            case 'deepgram':
+                // Deepgram adapter is not yet implemented - delegate gracefully.
+                throw new Error('Deepgram STT provider is not yet implemented. Use provider: "whisper" instead.');
+            default: {
+                // TypeScript exhaustive check via never
+                const unreachable = provider;
+                throw new Error(`Unknown STT provider: ${String(unreachable)}`);
+            }
+        }
+    }
+    async synthesize(text, options) {
+        if (!text.trim()) {
+            throw new Error('Text must not be empty');
+        }
+        // Allow explicit override via options.provider
+        const provider = options?.provider ?? this.ttsProvider;
+        if (!provider) {
+            throw new Error('No TTS provider available. Set ELEVENLABS_API_KEY, OPENAI_API_KEY, or ensure say/espeak is installed.');
+        }
+        logger.info('[Voice] Synthesizing', { provider, chars: text.length });
+        switch (provider) {
+            case 'elevenlabs':
+                return synthesizeWithElevenLabs(text, options);
+            case 'openai':
+                return synthesizeWithOpenAI(text, options);
+            case 'system':
+                return synthesizeWithSystem(text, options);
+            default: {
+                const unreachable = provider;
+                throw new Error(`Unknown TTS provider: ${String(unreachable)}`);
+            }
+        }
+    }
+    async getAvailableVoices() {
+        const results = [];
+        // Collect from all configured providers in parallel where possible
+        const tasks = [];
+        if (process.env.OPENAI_API_KEY) {
+            tasks.push(Promise.resolve(getOpenAIVoices()));
+        }
+        if (process.env.ELEVENLABS_API_KEY) {
+            tasks.push(getElevenLabsVoices().catch((error) => {
+                logger.warn('[Voice] Failed to fetch ElevenLabs voices', {
+                    error: error instanceof Error ? error.message : 'Unknown',
+                });
+                return [];
+            }));
+        }
+        const settled = await Promise.all(tasks);
+        for (const list of settled) {
+            results.push(...list);
+        }
+        return results;
+    }
+}
+// Singleton accessor
+let instance = null;
+/**
+ * Returns the shared VoiceService singleton.
+ * Initializes it on first call and probes system TTS availability.
+ */
+export async function getVoiceService() {
+    if (instance)
+        return instance;
+    // Warm the system TTS availability cache before constructing
+    await probeSystemTTSAvailability().catch(() => undefined);
+    instance = new VoiceServiceImpl();
+    return instance;
+}
+/**
+ * Reset the singleton (useful in tests).
+ */
+export function resetVoiceService() {
+    instance = null;
+}
+//# sourceMappingURL=index.js.map

package/dist/voice/stt/whisper.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenAI Whisper STT Provider
+ *
+ * Transcribes audio using OpenAI's Whisper API.
+ * Supports language detection, segmentation, and confidence scoring.
+ */
+import type { TranscribeOptions, TranscribeResult } from '../index.js';
+/**
+ * Transcribe audio using OpenAI Whisper.
+ * Requires OPENAI_API_KEY environment variable.
+ */
+export declare function transcribeWithWhisper(audio: Buffer, options?: TranscribeOptions): Promise<TranscribeResult>;
+//# sourceMappingURL=whisper.d.ts.map

package/dist/voice/stt/whisper.js

@@ -0,0 +1,116 @@
+/**
+ * OpenAI Whisper STT Provider
+ *
+ * Transcribes audio using OpenAI's Whisper API.
+ * Supports language detection, segmentation, and confidence scoring.
+ */
+import { z } from 'zod';
+import { logger } from '../../utils/logger.js';
+const WHISPER_API_URL = 'https://api.openai.com/v1/audio/transcriptions';
+const DEFAULT_MODEL = 'whisper-1';
+// Zod schema for the verbose_json response from Whisper
+const WhisperSegmentSchema = z.object({
+    id: z.number(),
+    start: z.number(),
+    end: z.number(),
+    text: z.string(),
+    avg_logprob: z.number().optional(),
+});
+const WhisperResponseSchema = z.object({
+    text: z.string(),
+    language: z.string().optional(),
+    duration: z.number().optional(),
+    segments: z.array(WhisperSegmentSchema).optional(),
+});
+function computeConfidence(segments) {
+    if (!segments || segments.length === 0)
+        return undefined;
+    const validSegments = segments.filter((s) => typeof s.avg_logprob === 'number');
+    if (validSegments.length === 0)
+        return undefined;
+    const avgLogProb = validSegments.reduce((sum, s) => sum + (s.avg_logprob ?? 0), 0) /
+        validSegments.length;
+    // Convert log probability to a 0-1 confidence score
+    return Math.min(1, Math.max(0, Math.exp(avgLogProb)));
+}
+/**
+ * Transcribe audio using OpenAI Whisper.
+ * Requires OPENAI_API_KEY environment variable.
+ */
+export async function transcribeWithWhisper(audio, options) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error('OPENAI_API_KEY is not set');
+    }
+    const model = options?.model ?? DEFAULT_MODEL;
+    const startMs = Date.now();
+    logger.info('[Whisper] Transcribing audio', {
+        model,
+        language: options?.language,
+        bufferSize: audio.length,
+    });
+    const form = new FormData();
+    form.append('file', new Blob([audio]), 'audio.webm');
+    form.append('model', model);
+    form.append('response_format', 'verbose_json');
+    if (options?.language) {
+        form.append('language', options.language);
+    }
+    let rawResponse;
+    try {
+        rawResponse = await fetch(WHISPER_API_URL, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: form,
+        });
+    }
+    catch (error) {
+        logger.error('[Whisper] Network error during transcription', {
+            error: error instanceof Error ? error.message : 'Unknown',
+        });
+        throw new Error(`Whisper network error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    if (!rawResponse.ok) {
+        const errorBody = await rawResponse.text();
+        logger.error('[Whisper] API error', {
+            status: rawResponse.status,
+            body: errorBody,
+        });
+        throw new Error(`Whisper API error ${rawResponse.status}: ${errorBody}`);
+    }
+    let json;
+    try {
+        json = await rawResponse.json();
+    }
+    catch (error) {
+        throw new Error(`Whisper response parse error: ${error instanceof Error ? error.message : 'Unknown'}`);
+    }
+    const parsed = WhisperResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        logger.error('[Whisper] Unexpected response shape', {
+            issues: parsed.error.issues,
+        });
+        throw new Error(`Unexpected Whisper response: ${parsed.error.message}`);
+    }
+    const data = parsed.data;
+    const durationMs = Date.now() - startMs;
+    logger.info('[Whisper] Transcription complete', {
+        language: data.language,
+        audioDuration: data.duration,
+        elapsed: durationMs,
+    });
+    return {
+        text: data.text.trim(),
+        language: data.language,
+        duration_ms: data.duration != null ? Math.round(data.duration * 1000) : undefined,
+        confidence: computeConfidence(data.segments),
+        segments: data.segments?.map((s) => ({
+            start: s.start,
+            end: s.end,
+            text: s.text,
+        })),
+    };
+}
+//# sourceMappingURL=whisper.js.map