@nightowne/tas-cli 2.1.0 → 2.4.0

package/src/cli.js

@@ -15,13 +15,31 @@ import { Compressor } from './utils/compression.js';
 import { FileIndex } from './db/index.js';
 import { processFile, retrieveFile } from './index.js';
 import { printBanner, LOGO, TAGLINE, VERSION } from './utils/branding.js';
-import { getPassword, verifyPassword, loadConfig, requireConfig, getAndVerifyPassword } from './utils/cli-helpers.js';
+import { getPassword, verifyPassword, loadConfig, requireConfig, getAndVerifyPassword, decryptBotToken, resolveConfig } from './utils/cli-helpers.js';
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import os from 'os';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DATA_DIR = path.join(__dirname, '..', 'data');
+const DATA_DIR = process.env.TAS_DATA_DIR || path.join(os.homedir(), '.tas');
+
+// Global error handlers — prevent silent crashes
+process.on('unhandledRejection', (reason) => {
+    console.error(chalk.red('\n✗ Unhandled error:'), reason?.message || reason);
+    process.exit(1);
+});
+
+process.on('uncaughtException', (err) => {
+    console.error(chalk.red('\n✗ Fatal error:'), err.message);
+    process.exit(1);
+});
+
+// Graceful shutdown on signals
+const cleanupAndExit = (signal) => {
+    console.log(chalk.dim(`\n${signal} received, shutting down...`));
+    process.exit(0);
+};
+process.on('SIGINT', () => cleanupAndExit('SIGINT'));
+process.on('SIGTERM', () => cleanupAndExit('SIGTERM'));
 
 const program = new Command();
 
@@ -104,15 +122,19 @@ program
             const userInfo = await client.waitForChatId(120000);
             spinner.succeed(`Linked to ${userInfo.firstName} (@${userInfo.username})`);
 
-            // Save config
+            // Save config (bot token encrypted with user's password)
             const configPath = path.join(DATA_DIR, 'config.json');
+            const encryptedToken = encryptor.encrypt(Buffer.from(token, 'utf-8')).toString('base64');
             fs.writeFileSync(configPath, JSON.stringify({
-                botToken: token,
+                encryptedBotToken: encryptedToken,
                 chatId: userInfo.chatId,
                 passwordHash: encryptor.getPasswordHash(),
                 username: userInfo.username,
-                createdAt: new Date().toISOString()
+                createdAt: new Date().toISOString(),
+                configVersion: 2
             }, null, 2));
+            // Restrict config file permissions — contains encrypted token and password hash
+            try { fs.chmodSync(configPath, 0o600); } catch { /* ignore on Windows */ }
 
             // Initialize database
             spinner.start('Initializing local index...');
@@ -152,11 +174,12 @@ program
                 process.exit(1);
             }
 
-            const config = requireConfig(DATA_DIR);
+            const rawConfig = requireConfig(DATA_DIR);
             spinner.stop();
 
             // Get and verify password
             const password = await getAndVerifyPassword(options.password, DATA_DIR);
+            const config = resolveConfig(rawConfig, password);
 
             spinner.start('Processing file...');
 
@@ -207,7 +230,7 @@ program
         const spinner = ora('Looking up file...').start();
 
         try {
-            const config = requireConfig(DATA_DIR);
+            const rawConfig = requireConfig(DATA_DIR);
 
             // Find file in index
             const db = new FileIndex(path.join(DATA_DIR, 'index.db'));
@@ -223,6 +246,7 @@ program
 
             // Get and verify password
             const password = await getAndVerifyPassword(options.password, DATA_DIR);
+            const config = resolveConfig(rawConfig, password);
 
             spinner.start('Downloading...');
 
@@ -266,6 +290,7 @@ program
     .alias('ls')
     .description('List all stored files')
     .option('-l, --long', 'Show detailed information')
+    .option('--json', 'Output as JSON (for scripting)')
     .action(async (options) => {
         try {
             const db = new FileIndex(path.join(DATA_DIR, 'index.db'));
@@ -273,8 +298,15 @@ program
 
             const files = db.listAll();
 
+            if (options.json) {
+                console.log(JSON.stringify(files, null, 2));
+                db.close();
+                return;
+            }
+
             if (files.length === 0) {
                 console.log(chalk.yellow('\n📭 No files stored yet. Use `tas push <file>` to upload.\n'));
+                db.close();
                 return;
             }
 
@@ -298,6 +330,7 @@ program
             }
 
             console.log();
+            db.close();
 
         } catch (err) {
             console.error(chalk.red('Error listing files:'), err.message);
@@ -311,6 +344,7 @@ program
     .alias('rm')
     .description('Remove a file from the index (optionally from Telegram too)')
     .option('--hard', 'Also delete from Telegram')
+    .option('-p, --password <password>', 'Encryption password (required for --hard)')
     .action(async (identifier, options) => {
         try {
             const db = new FileIndex(path.join(DATA_DIR, 'index.db'));
@@ -334,8 +368,9 @@ program
             if (confirm) {
                 // If hard delete, also remove from Telegram
                 if (options.hard) {
-                    const configPath = path.join(DATA_DIR, 'config.json');
-                    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                    const rawConfig = requireConfig(DATA_DIR);
+                    const password = await getAndVerifyPassword(options.password, DATA_DIR);
+                    const config = resolveConfig(rawConfig, password);
 
                     const client = new TelegramClient(DATA_DIR);
                     await client.initialize(config.botToken);
@@ -361,11 +396,16 @@ program
 program
     .command('status')
     .description('Show TAS status and statistics')
-    .action(async () => {
+    .option('--json', 'Output as JSON (for scripting)')
+    .action(async (options) => {
         const configPath = path.join(DATA_DIR, 'config.json');
 
         if (!fs.existsSync(configPath)) {
-            console.log(chalk.yellow('\n⚠️  TAS not initialized. Run `tas init` first.\n'));
+            if (options.json) {
+                console.log(JSON.stringify({ initialized: false }));
+            } else {
+                console.log(chalk.yellow('\n⚠️  TAS not initialized. Run `tas init` first.\n'));
+            }
             return;
         }
 
@@ -378,13 +418,30 @@ program
         const storedSize = files.reduce((acc, f) => acc + f.stored_size, 0);
         const savings = totalSize > 0 ? Math.round((1 - storedSize / totalSize) * 100) : 0;
 
+        if (options.json) {
+            console.log(JSON.stringify({
+                initialized: true,
+                createdAt: config.createdAt,
+                username: config.username || 'unknown',
+                fileCount: files.length,
+                totalSize,
+                storedSize,
+                savingsPercent: savings,
+                dataDir: DATA_DIR
+            }, null, 2));
+            db.close();
+            return;
+        }
+
         console.log(chalk.cyan('\n📊 TAS Status\n'));
         console.log(`  Initialized: ${chalk.white(new Date(config.createdAt).toLocaleDateString())}`);
         console.log(`  Telegram user: ${chalk.white('@' + (config.username || 'unknown'))}`);
+        console.log(`  Data dir: ${chalk.white(DATA_DIR)}`);
         console.log(`  Files stored: ${chalk.white(files.length)}`);
         console.log(`  Total size: ${chalk.white(formatBytes(totalSize))}`);
         console.log(`  Compressed: ${chalk.white(formatBytes(storedSize))} ${chalk.dim(`(${savings}% saved)`)}`);
         console.log();
+        db.close();
     });
 
 // ============== MOUNT COMMAND ==============
@@ -395,8 +452,9 @@ program
     .action(async (mountpoint, options) => {
         console.log(chalk.cyan('\n🗂️  Mounting Telegram as filesystem...\n'));
 
-        const config = requireConfig(DATA_DIR);
+        const rawConfig = requireConfig(DATA_DIR);
         const password = await getAndVerifyPassword(options.password, DATA_DIR);
+        const config = resolveConfig(rawConfig, password);
 
         const spinner = ora('Initializing filesystem...').start();
 
@@ -678,8 +736,9 @@ syncCmd
     .action(async (options) => {
         console.log(chalk.cyan('\n🔄 Starting folder sync...\n'));
 
-        const config = requireConfig(DATA_DIR);
+        const rawConfig = requireConfig(DATA_DIR);
         const password = await getAndVerifyPassword(options.password, DATA_DIR);
+        const config = resolveConfig(rawConfig, password);
 
         let limitRate = null;
         if (options.limit) {
@@ -768,8 +827,9 @@ syncCmd
     .action(async (options) => {
         console.log(chalk.cyan('\n📥 Pulling files from Telegram...\n'));
 
-        const config = requireConfig(DATA_DIR);
+        const rawConfig = requireConfig(DATA_DIR);
         const password = await getAndVerifyPassword(options.password, DATA_DIR);
+        const config = resolveConfig(rawConfig, password);
 
         const spinner = ora('Loading...').start();
 
@@ -854,10 +914,13 @@ syncCmd
 program
     .command('verify')
     .description('Verify file integrity and check for missing Telegram messages')
-    .action(async () => {
+    .option('-p, --password <password>', 'Encryption password')
+    .action(async (options) => {
         console.log(chalk.cyan('\n🔍 Verifying file integrity...\n'));
 
-        const config = requireConfig(DATA_DIR);
+        const rawConfig = requireConfig(DATA_DIR);
+        const password = await getAndVerifyPassword(options.password, DATA_DIR);
+        const config = resolveConfig(rawConfig, password);
 
         const spinner = ora('Checking files...').start();
 
@@ -944,10 +1007,11 @@ program
 
 // Helper function
 function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0) return '0 B';
     if (bytes === 0) return '0 B';
     const k = 1024;
-    const sizes = ['B', 'KB', 'MB', 'GB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1);
     return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
 }
 
@@ -1052,8 +1116,8 @@ program
             }
 
             // Resume uploads
-            const config = loadConfig(DATA_DIR);
-            if (!config) {
+            const rawConfig = loadConfig(DATA_DIR);
+            if (!rawConfig) {
                 console.log(chalk.red('✗ TAS not initialized.'));
                 db.close();
                 return;
@@ -1061,6 +1125,7 @@ program
 
             // Get and verify password
             const password = await getAndVerifyPassword(options.password, DATA_DIR);
+            const config = resolveConfig(rawConfig, password);
 
             // Connect to Telegram
             const { TelegramClient } = await import('./telegram/client.js');
@@ -1147,8 +1212,9 @@ shareCmd
     .action(async (file, options) => {
         console.log(chalk.cyan('\n🔗 Creating share link...\n'));
 
-        const config = requireConfig(DATA_DIR);
+        const rawConfig = requireConfig(DATA_DIR);
         const password = await getAndVerifyPassword(options.password, DATA_DIR);
+        const config = resolveConfig(rawConfig, password);
 
         const spinner = ora('Setting up...').start();
 
@@ -1299,6 +1365,98 @@ shareCmd
         }
     });
 
+// ============== DOCTOR COMMAND ==============
+program
+    .command('doctor')
+    .description('🩺 Run self-diagnostics and check system health')
+    .action(async () => {
+        console.log(chalk.cyan('\n🩺 TAS Doctor — System Health Check\n'));
+
+        const checks = [];
+        const ok = (label) => { checks.push({ label, status: 'ok' }); console.log(chalk.green(`  ✓ ${label}`)); };
+        const warn = (label, detail) => { checks.push({ label, status: 'warn', detail }); console.log(chalk.yellow(`  ⚠ ${label}`) + chalk.dim(` — ${detail}`)); };
+        const fail = (label, detail) => { checks.push({ label, status: 'fail', detail }); console.log(chalk.red(`  ✗ ${label}`) + chalk.dim(` — ${detail}`)); };
+
+        // 1. Check Node.js version
+        const nodeVer = process.versions.node;
+        const major = parseInt(nodeVer.split('.')[0]);
+        if (major >= 18) ok(`Node.js ${nodeVer}`);
+        else warn(`Node.js ${nodeVer}`, 'Requires >= 18.0.0');
+
+        // 2. Check data directory
+        if (fs.existsSync(DATA_DIR)) ok(`Data directory: ${DATA_DIR}`);
+        else warn('Data directory missing', `Run \`tas init\` to create ${DATA_DIR}`);
+
+        // 3. Check config
+        const configPath = path.join(DATA_DIR, 'config.json');
+        if (fs.existsSync(configPath)) {
+            try {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                if (config.configVersion === 2) ok('Config v2 (encrypted token)');
+                else if (config.botToken) warn('Config v1 (plaintext token)', 'Re-run `tas init` to encrypt token');
+                else fail('Config invalid', 'Missing bot token');
+
+                if (config.chatId) ok(`Chat ID: ${config.chatId}`);
+                else fail('Chat ID missing', 'Run `tas init`');
+            } catch (e) {
+                fail('Config corrupted', e.message);
+            }
+        } else {
+            warn('Config not found', 'Run `tas init`');
+        }
+
+        // 4. Check database
+        const dbPath = path.join(DATA_DIR, 'index.db');
+        if (fs.existsSync(dbPath)) {
+            try {
+                const db = new FileIndex(dbPath);
+                db.init();
+                const stats = db.getStats();
+                ok(`Database: ${stats.file_count} files, ${formatBytes(stats.total_original)} total`);
+                db.close();
+            } catch (e) {
+                fail('Database error', e.message);
+            }
+        } else {
+            warn('Database not found', 'Will be created on first upload');
+        }
+
+        // 5. Check FUSE availability
+        try {
+            await import('fuse-native');
+            ok('FUSE support available');
+        } catch (e) {
+            warn('FUSE not available', 'Install libfuse for mount support');
+        }
+
+        // 6. Check disk space
+        try {
+            const { execSync } = await import('child_process');
+            const df = execSync(`df -h "${DATA_DIR}" 2>/dev/null || echo "unknown"`).toString().trim();
+            const lines = df.split('\n');
+            if (lines.length > 1) {
+                const parts = lines[1].split(/\s+/);
+                const avail = parts[3] || 'unknown';
+                const usage = parts[4] || 'unknown';
+                if (parseInt(usage) > 90) warn(`Disk space: ${avail} free (${usage} used)`, 'Running low!');
+                else ok(`Disk space: ${avail} free (${usage} used)`);
+            }
+        } catch (e) { /* ignore */ }
+
+        // 7. Security check
+        const iterations = 600000;
+        ok(`Encryption: AES-256-GCM, PBKDF2-SHA512 ${iterations.toLocaleString()} iterations`);
+
+        // Summary
+        const fails = checks.filter(c => c.status === 'fail').length;
+        const warns = checks.filter(c => c.status === 'warn').length;
+        console.log();
+        if (fails > 0) console.log(chalk.red(`  ${fails} issue(s) found. Please fix them above.`));
+        else if (warns > 0) console.log(chalk.yellow(`  ${warns} warning(s). System is functional.`));
+        else console.log(chalk.green('  ✨ All systems go! TAS is healthy.'));
+        console.log();
+    });
+
 program.parse();
 
 

package/src/crypto/encryption.js

@@ -10,7 +10,7 @@ const KEY_LENGTH = 32; // 256 bits
 const IV_LENGTH = 12;  // 96 bits for GCM
 const TAG_LENGTH = 16; // 128 bits auth tag
 const SALT_LENGTH = 32;
-const PBKDF2_ITERATIONS = 100000;
+const PBKDF2_ITERATIONS = 600000; // OWASP 2025 recommendation for SHA-512
 
 export class Encryptor {
     constructor(password) {
@@ -19,11 +19,42 @@ export class Encryptor {
 
     /**
      * Get a hash of the password for verification (not the actual key!)
+     * Uses PBKDF2 with a fixed salt derived from the password domain to make brute-force expensive.
      */
     getPasswordHash() {
-        return crypto.createHash('sha256')
-            .update(this.password + 'was-verify')
+        const verifySalt = Buffer.from('tas-password-verify-v2', 'utf-8');
+        return crypto.pbkdf2Sync(this.password, verifySalt, PBKDF2_ITERATIONS, 32, 'sha512').toString('hex');
+    }
+
+    /**
+     * Check password against a stored hash (supports both legacy SHA-256 and new PBKDF2 formats)
+     * Uses timing-safe comparison to prevent side-channel attacks.
+     */
+    static verifyPasswordHash(password, storedHash) {
+        const encryptor = new Encryptor(password);
+
+        const computedHash = encryptor.getPasswordHash();
+        const computedBuf = Buffer.from(computedHash, 'utf-8');
+        const storedBuf = Buffer.from(storedHash, 'utf-8');
+
+        // Try new PBKDF2-based verification first
+        if (computedBuf.length === storedBuf.length &&
+            crypto.timingSafeEqual(computedBuf, storedBuf)) {
+            return true;
+        }
+
+        // Fallback: legacy SHA-256 verification for backward compatibility
+        const legacyHash = crypto.createHash('sha256')
+            .update(password + 'was-verify')
             .digest('hex');
+        const legacyBuf = Buffer.from(legacyHash, 'utf-8');
+
+        if (legacyBuf.length === storedBuf.length &&
+            crypto.timingSafeEqual(legacyBuf, storedBuf)) {
+            return true;
+        }
+
+        return false;
     }
 
     /**
@@ -92,6 +123,10 @@ export class Encryptor {
                 callback();
             },
             flush(callback) {
+                if (!headerWritten) {
+                    this.push(Buffer.concat([salt, iv]));
+                    headerWritten = true;
+                }
                 const final = cipher.final();
                 if (final.length > 0) {
                     this.push(final);

package/src/db/index.js

@@ -171,25 +171,32 @@ export class FileIndex {
   }
 
   /**
-   * Find file by hash
+   * Escape SQL LIKE wildcard characters
+   */
+  _escapeLike(str) {
+    return str.replace(/[%_\\]/g, '\\$&');
+  }
+
+  /**
+   * Find file by hash (exact match or prefix match)
    */
   findByHash(hash) {
     const stmt = this.db.prepare(`
-      SELECT * FROM files WHERE hash = ? OR hash LIKE ?
+      SELECT * FROM files WHERE hash = ? OR hash LIKE ? ESCAPE '\\'
     `);
 
-    return stmt.get(hash, hash + '%');
+    return stmt.get(hash, this._escapeLike(hash) + '%');
   }
 
   /**
-   * Find file by filename
+   * Find file by filename (exact match or substring match)
    */
   findByName(filename) {
     const stmt = this.db.prepare(`
-      SELECT * FROM files WHERE filename = ? OR filename LIKE ?
+      SELECT * FROM files WHERE filename = ? OR filename LIKE ? ESCAPE '\\'
     `);
 
-    return stmt.get(filename, '%' + filename + '%');
+    return stmt.get(filename, '%' + this._escapeLike(filename) + '%');
   }
 
   /**
@@ -399,11 +406,11 @@ export class FileIndex {
       SELECT f.*, GROUP_CONCAT(t.tag) as tags
       FROM files f
       LEFT JOIN tags t ON f.id = t.file_id
-      WHERE f.filename LIKE ?
+      WHERE f.filename LIKE ? ESCAPE '\\'
       GROUP BY f.id
       ORDER BY f.created_at DESC
     `);
-    return stmt.all(`%${query}%`);
+    return stmt.all(`%${this._escapeLike(query)}%`);
   }
 
   /**
@@ -414,11 +421,11 @@ export class FileIndex {
       SELECT f.*, GROUP_CONCAT(t.tag) as tags
       FROM files f
       INNER JOIN tags t ON f.id = t.file_id
-      WHERE t.tag LIKE ?
+      WHERE t.tag LIKE ? ESCAPE '\\'
       GROUP BY f.id
       ORDER BY f.created_at DESC
     `);
-    return stmt.all(`%${query}%`);
+    return stmt.all(`%${this._escapeLike(query)}%`);
   }
 
   // ============== RESUME UPLOAD METHODS ==============
@@ -572,10 +579,9 @@ export class FileIndex {
    */
   cleanExpiredShares() {
     const stmt = this.db.prepare(`
-      DELETE FROM shares WHERE
-        REPLACE(REPLACE(expires_at, 'T', ' '), 'Z', '') < strftime('%Y-%m-%d %H:%M:%f', 'now')
+      DELETE FROM shares WHERE expires_at < ?
     `);
-    return stmt.run().changes;
+    return stmt.run(new Date().toISOString()).changes;
   }
 
   /**

package/src/fuse/mount.js

@@ -5,21 +5,40 @@
  * This is the killer feature - use Telegram like a regular folder!
  */
 
-import Fuse from 'fuse-native';
 import path from 'path';
 import fs from 'fs';
+import { pipeline } from 'stream/promises';
+
+let Fuse;
+try {
+    Fuse = (await import('fuse-native')).default;
+} catch {
+    // fuse-native is optional — unavailable on ARM64 or systems without libfuse
+}
 import { TelegramClient } from '../telegram/client.js';
 import { Encryptor } from '../crypto/encryption.js';
 import { Compressor } from '../utils/compression.js';
 import { FileIndex } from '../db/index.js';
-import { createHeader, parseHeader, HEADER_SIZE } from '../utils/chunker.js';
+import { createHeader } from '../utils/chunker.js';
+import { createDownloadPipeline } from '../utils/download-stream.js';
 
 // File cache for performance (avoid re-downloading)
 const fileCache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+const CACHE_MAX_ENTRIES = 100; // Prevent unbounded memory growth
 
 export class TelegramFS {
     constructor(options) {
+        if (!Fuse) {
+            throw new Error(
+                'fuse-native is not available on this system.\n' +
+                '  On Linux x86_64: npm install fuse-native && sudo apt install fuse libfuse-dev\n' +
+                '  On macOS: brew install macfuse && npm install fuse-native\n' +
+                '  On ARM64: see https://github.com/ixchio/tas/issues/1 for a workaround\n' +
+                '  All other TAS commands (push, pull, sync, share) work without FUSE.'
+            );
+        }
+
         this.dataDir = options.dataDir;
         this.password = options.password;
         this.config = options.config;
@@ -364,56 +383,18 @@ export class TelegramFS {
         }
 
         const chunks = this.db.getChunks(file.id);
-        if (chunks.length === 0) throw new Error('No chunks found');
-
-        // Pre-sort chunks
-        chunks.sort((a, b) => a.chunk_index - b.chunk_index);
-
-        const firstChunkData = await this.client.downloadFile(chunks[0].file_telegram_id);
-        const header = parseHeader(firstChunkData);
-        let wasCompressed = header.compressed;
-
-        const decryptStream = this.encryptor.getDecryptStream();
-        const decompressStream = this.compressor.getDecompressStream(wasCompressed);
-
-        const { Readable } = await import('stream');
-        const { pipeline } = await import('stream/promises');
-
-        const self = this;
-        let currentChunkIndex = 0;
-        let preloadedFirstChunk = firstChunkData;
-
-        const downloadStream = new Readable({
-            async read() {
-                try {
-                    if (currentChunkIndex >= chunks.length) {
-                        this.push(null);
-                        return;
-                    }
-
-                    const chunk = chunks[currentChunkIndex];
-                    let data;
-                    if (currentChunkIndex === 0 && preloadedFirstChunk) {
-                        data = preloadedFirstChunk;
-                        preloadedFirstChunk = null;
-                    } else {
-                        data = await self.client.downloadFile(chunk.file_telegram_id);
-                    }
-
-                    const payload = data.subarray(HEADER_SIZE);
-                    this.push(payload);
-                    currentChunkIndex++;
-                } catch (err) {
-                    this.destroy(err);
-                }
-            }
+
+        const { readable } = await createDownloadPipeline({
+            client: this.client,
+            chunks,
+            encryptor: this.encryptor,
+            compressor: this.compressor
         });
 
         const tmpOutputPath = outputPath + '.tmp';
         const writeStream = fs.createWriteStream(tmpOutputPath);
 
-        // Pipeline: Telegram -> Decrypt -> Decompress -> Disk Cache
-        await pipeline(downloadStream, decryptStream, decompressStream, writeStream);
+        await pipeline(readable, writeStream);
 
         // Rename to final atomic path
         fs.renameSync(tmpOutputPath, outputPath);
@@ -504,6 +485,23 @@ export class TelegramFS {
     }
 
     setCache(filename, cachePath) {
+        // Evict oldest entry if cache is full
+        if (fileCache.size >= CACHE_MAX_ENTRIES) {
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [key, entry] of fileCache) {
+                if (entry.timestamp < oldestTime) {
+                    oldestTime = entry.timestamp;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey) {
+                const evicted = fileCache.get(oldestKey);
+                try { if (fs.existsSync(evicted.path)) fs.unlinkSync(evicted.path); } catch (e) { }
+                fileCache.delete(oldestKey);
+            }
+        }
+
         fileCache.set(filename, {
             path: cachePath,
             timestamp: Date.now()