fix(translate): reject symlinks to prevent directory traversal (Issue #6)

TDD Cycle: RED-GREEN-REFACTOR for symlink path validation

RED Phase:
- Added 5 failing tests for symlink validation
- Tests verify symlink rejection for files and directories
- Tests verify regular files/directories still work correctly
- Tests verify clear error messages

GREEN Phase:
- Added lstatSync check at translate() entry point before processing
- lstatSync doesn't follow symlinks, allowing detection before statSync
- Throws error with clear message: "Symlinks are not supported for security reasons: <path>"
- Re-throws symlink errors while catching other filesystem errors
- All 1454 tests passing

Security Impact:
- Prevents directory traversal attacks via symlinks
- Blocks access to sensitive files like /etc/passwd
- Prevents reading files outside intended directory scope
- Example attack: ln -s /etc/passwd ~/myfile.txt && deepl translate ~/myfile.txt

Implementation:
- Uses fs.lstatSync() to detect symlinks (doesn't follow them)
- Applies to both file and directory translation paths
- Clear, actionable error messages for users

Updated 2 existing tests to mock lstatSync for new validation.
CHANGELOG.md updated with security enhancement details.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: sjsyrek

CHANGELOG.md

@@ -52,6 +52,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Performance Benefit**: Avoids expensive database aggregation on every cache write
   - Location: `src/storage/cache.ts` (currentSize field, initialize, set, clear, cleanupExpired, evictIfNeeded)
 
+### Security
+- **Symlink Path Validation** - Prevents directory traversal attacks (Issue #6)
+  - Rejects symlinks at translate() entry point before processing files
+  - Uses `fs.lstatSync()` to detect symlinks (doesn't follow symlinks)
+  - Prevents attackers from using symlinks to access sensitive files outside intended scope
+  - Clear error message: "Symlinks are not supported for security reasons: <path>"
+  - Applies to both file and directory paths
+  - Added 5 comprehensive tests covering symlink rejection and regular path acceptance
+  - **Impact**: Closes security vulnerability allowing directory traversal via symlinks
+  - **Example Attack Prevented**: User creating symlink to `/etc/passwd` and attempting to translate it
+  - Location: `src/cli/commands/translate.ts:118-149` (translate method with lstatSync check)
+
 ### Fixed
 - **Critical: Duplicate text handling in batch translation** - Fixed data loss bug for duplicate inputs
   - When input array contained duplicate texts (e.g., `["Hello", "Hello", "World"]`), only the last occurrence received translation

src/cli/commands/translate.ts

@@ -113,17 +113,30 @@ export class TranslateCommand {
   /**
    * Translate text, file, or directory
    * Fix for Issue #8: Cache stats to avoid redundant filesystem calls
+   * Fix for Issue #6: Reject symlinks for security (prevent directory traversal attacks)
    */
   async translate(textOrPath: string, options: TranslateOptions): Promise<string> {
     // Check if input is a file/directory with a single stat() call
     // Cache the stats result to avoid duplicate syscalls later
     let stats: fs.Stats | null = null;
     try {
+      // First check if the path is a symlink using lstatSync (doesn't follow symlinks)
+      // This prevents directory traversal attacks and accessing sensitive files
+      const lstat = fs.lstatSync(textOrPath);
+      if (lstat.isSymbolicLink()) {
+        throw new Error(`Symlinks are not supported for security reasons: ${textOrPath}`);
+      }
+
+      // Now safe to use statSync (follows symlinks if any, but we already checked)
       stats = fs.statSync(textOrPath);
       if (stats.isDirectory()) {
         return this.translateDirectory(textOrPath, options);
       }
-    } catch {
+    } catch (error) {
+      // Re-throw symlink errors
+      if (error instanceof Error && error.message.includes('Symlinks are not supported')) {
+        throw error;
+      }
       // Not a file/directory, treat as text
     }
 

tests/unit/translate-command.test.ts

@@ -704,8 +704,9 @@ describe('TranslateCommand', () => {
 
   describe('translate() - file/directory detection', () => {
     it('should detect and route to translateDirectory() for directory paths', async () => {
-      // Mock fs to indicate directory
+      // Mock fs to indicate directory (Issue #6: must check lstatSync for symlinks)
       const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({ isSymbolicLink: () => false, isDirectory: () => true } as any);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       jest.spyOn(fs, 'statSync').mockReturnValue({ isDirectory: () => true } as any);
 
@@ -725,9 +726,10 @@ describe('TranslateCommand', () => {
     });
 
     it('should detect and route to translateFile() for file paths', async () => {
-      // Mock fs to indicate file (not directory)
+      // Mock fs to indicate file (not directory) (Issue #6: must check lstatSync for symlinks)
       const fs = jest.requireActual('fs');
       const mockStats = { isDirectory: () => false, isFile: () => true };
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({ isSymbolicLink: () => false, isFile: () => true } as any);
       jest.spyOn(fs, 'existsSync').mockReturnValue(true);
       jest.spyOn(fs, 'statSync').mockReturnValue(mockStats as any);
 
@@ -1587,4 +1589,115 @@ describe('TranslateCommand', () => {
       ).rejects.toThrow('Invalid target language code: "invalid"');
     });
   });
+
+  describe('symlink path validation (Issue #6)', () => {
+    it('should reject symlink file paths', async () => {
+      const fs = jest.requireActual('fs');
+      // Mock lstatSync to indicate it's a symlink
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => true,
+        isDirectory: () => false,
+        isFile: () => false,
+      } as any);
+
+      await expect(
+        translateCommand.translate('/path/to/symlink.txt', {
+          to: 'es',
+          output: '/out.txt',
+        })
+      ).rejects.toThrow('Symlinks are not supported for security reasons');
+    });
+
+    it('should reject symlink directory paths', async () => {
+      const fs = jest.requireActual('fs');
+      // Mock lstatSync to indicate it's a symlink directory
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => true,
+        isDirectory: () => true,
+        isFile: () => false,
+      } as any);
+
+      await expect(
+        translateCommand.translate('/path/to/symlink-dir', {
+          to: 'es',
+          output: '/out',
+        })
+      ).rejects.toThrow('Symlinks are not supported for security reasons');
+    });
+
+    it('should accept regular file paths', async () => {
+      const fs = jest.requireActual('fs');
+      // Mock lstatSync to indicate it's a regular file (not a symlink)
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => false,
+        isDirectory: () => false,
+        isFile: () => true,
+        size: 1024,
+      } as any);
+      jest.spyOn(fs, 'statSync').mockReturnValue({
+        isDirectory: () => false,
+        isFile: () => true,
+        size: 1024,
+      } as any);
+      jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
+      jest.spyOn(fs, 'writeFileSync').mockImplementation(() => undefined);
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+
+      (mockDocumentTranslationService.isDocumentSupported as jest.Mock).mockReturnValue(true);
+      (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
+        text: 'Hola mundo',
+      });
+
+      const result = await translateCommand.translate('/path/to/regular-file.txt', {
+        to: 'es',
+        output: '/out.txt',
+      });
+
+      expect(result).toContain('Translated');
+      expect(result).toContain('/out.txt');
+    });
+
+    it('should accept regular directory paths', async () => {
+      const fs = jest.requireActual('fs');
+      // Mock lstatSync to indicate it's a regular directory (not a symlink)
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => false,
+        isDirectory: () => true,
+        isFile: () => false,
+      } as any);
+      jest.spyOn(fs, 'statSync').mockReturnValue({
+        isDirectory: () => true,
+        isFile: () => false,
+      } as any);
+
+      // Mock translateDirectory to return success
+      const spy = jest.spyOn(translateCommand as any, 'translateDirectory')
+        .mockResolvedValue('Directory translation complete');
+
+      const result = await translateCommand.translate('/path/to/regular-dir', {
+        to: 'es',
+        output: '/out',
+      });
+
+      expect(result).toBe('Directory translation complete');
+      expect(spy).toHaveBeenCalled();
+      spy.mockRestore();
+    });
+
+    it('should provide clear error message for symlinks', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'lstatSync').mockReturnValue({
+        isSymbolicLink: () => true,
+        isDirectory: () => false,
+        isFile: () => false,
+      } as any);
+
+      await expect(
+        translateCommand.translate('/path/to/symlink.txt', {
+          to: 'es',
+          output: '/out.txt',
+        })
+      ).rejects.toThrow('Symlinks are not supported for security reasons: /path/to/symlink.txt');
+    });
+  });
 });