feat: Implement ESLint with comprehensive security plugins and best practices

[Copilot]

Overview

This PR implements a comprehensive ESLint configuration with security-focused plugins to enhance code quality, security posture, and maintain consistent coding standards across the unthread-webhook-server project.

What's New

Core ESLint Implementation

• Modern Configuration: Uses ESLint 9.36.0 with the new flat config format (eslint.config.js)
• TypeScript Support: Full integration with TypeScript parser and plugin for strict type checking
• Node.js/Express.js: Optimized rules for Node.js backend and Express.js patterns

Security Plugins Integrated

This implementation focuses heavily on security with multiple dedicated plugins:

• eslint-plugin-security (v3.0.1): Detects common security vulnerabilities including:

  • Object injection attacks
  • Unsafe regular expressions (ReDoS prevention)
  • Insecure buffer operations
  • Eval usage and code injection
  • CSRF vulnerabilities

• eslint-plugin-no-secrets (v2.2.1): Prevents hardcoded credentials with:

  • API key detection
  • Token and password scanning
  • Custom patterns for webhook secrets (unthreadSecret, webhookSecret)

• eslint-plugin-n (v17.23.1): Node.js best practices and security:

  • Deprecated API detection
  • Secure child process usage
  • File system security

Developer Experience

NPM Scripts:

yarn lint          # Check for linting issues
yarn lint:fix      # Automatically fix issues
yarn lint:security # Security-focused linting
yarn lint:ci       # CI mode (fails on warnings)

VSCode Integration:

• Auto-fix on save enabled
• Real-time linting feedback
• ESLint extension recommended automatically
• Settings pre-configured in .vscode/settings.json

CI/CD Integration:

• Linting step added to GitHub Actions validate.yml workflow
• Runs before type-check and build
• Ensures all PRs meet code quality standards

Documentation

• ESLINT.md: Comprehensive 180+ line guide covering:

  • All installed plugins and their purpose
  • Security rules enforcement
  • Usage examples and best practices
  • Troubleshooting common issues

• CONTRIBUTING.md: Updated with:

  • Linting guidelines section
  • Code quality requirements
  • Pre-submission checklist including linting
  • Best practices for handling ESLint warnings

Code Quality Results

After implementing ESLint and fixing all issues:

• Errors: 0
• Warnings: 1 (acceptable - process.exit() in server startup is legitimate)
• Security Issues: 0 detected
• All Tests: ✓ Passing (type-check, build, lint)

Security Focus Areas Covered

1. ✅ Input Validation: Detects unsafe user input handling
2. ✅ Injection Prevention: Prevents SQL/NoSQL/Command injection
3. ✅ Cryptographic Security: Ensures secure random number generation
4. ✅ File System Security: Prevents path traversal vulnerabilities
5. ✅ Secret Management: Detects hardcoded credentials
6. ✅ Regular Expression Security: Prevents ReDoS attacks
7. ✅ Child Process Security: Flags unsafe subprocess execution

Files Changed

Created:

• eslint.config.js - Main ESLint configuration (154 lines)
• ESLINT.md - Comprehensive documentation (182 lines)
• .vscode/settings.json - VSCode integration settings

Modified:

• package.json - Added ESLint dependencies and scripts
• .gitignore - Allow VSCode config files
• .vscode/extensions.json - Added ESLint extension recommendation
• .github/workflows/validate.yml - Added linting step
• CONTRIBUTING.md - Added linting guidelines and best practices
• 11 source files in src/ - Fixed linting issues (unused imports, promise handling, etc.)

Breaking Changes

None. This is purely additive and all existing code continues to work.

Migration Guide

For developers:

1. Install dependencies: yarn install (already done)
2. Install VSCode extension: ext install dbaeumer.vscode-eslint
3. Run linting: yarn lint before committing
4. Auto-fix: yarn lint:fix for automatic fixes
5. Review: Check ESLINT.md for detailed guidelines

Testing

All commands verified:

✓ yarn lint          # Passes with 1 acceptable warning
✓ yarn lint:fix      # Runs successfully
✓ yarn lint:security # Passes
✓ yarn lint:ci       # Passes with max warnings: 1
✓ yarn type-check    # Passes
✓ yarn build         # Passes

Why This Matters

• Security: Automated detection of common vulnerabilities before they reach production
• Consistency: Enforced coding standards across all contributors
• Quality: Catches bugs and issues during development, not in production
• Compliance: Aligns with security best practices for handling sensitive webhook data
• Productivity: Auto-fix capabilities save time on code reviews

This implementation significantly enhances the security posture of the webhook server while maintaining developer productivity through smart defaults and helpful tooling.

Original prompt

Implement ESLint with Security Plugins and Best Practices

ESLint Implementation with Security Focus

Objective

Implement comprehensive ESLint configuration with security plugins to enhance code quality, security posture, and maintain consistent coding standards across the unthread-webhook-server project.

Core Requirements

1. ESLint Base Configuration

• Install and configure ESLint for TypeScript/Node.js project
• Use modern flat config format (eslint.config.js)
• Support for TypeScript files and Express.js patterns
• Integration with existing build and development workflows

2. Security Plugin Integration

• @eslint/plugin-security - Core security rules
• eslint-plugin-security - Additional security patterns
• eslint-plugin-no-secrets - Prevent hardcoded secrets
• eslint-plugin-node-security - Node.js specific security rules

3. Essential ESLint Plugins

• @typescript-eslint/eslint-plugin - TypeScript-specific rules
• @typescript-eslint/parser - TypeScript parser
• eslint-plugin-node - Node.js best practices
• eslint-plugin-import - Import/export validation
• eslint-plugin-promise - Promise handling best practices

4. Security-Focused Rules Configuration

// Key security rules to implement:
{
  "security/detect-object-injection": "error",
  "security/detect-non-literal-regexp": "error",
  "security/detect-unsafe-regex": "error",
  "security/detect-buffer-noassert": "error",
  "security/detect-child-process": "warn",
  "security/detect-disable-mustache-escape": "error",
  "security/detect-eval-with-expression": "error",
  "security/detect-no-csrf-before-method-override": "error",
  "security/detect-non-literal-fs-filename": "warn",
  "security/detect-non-literal-require": "warn",
  "security/detect-possible-timing-attacks": "warn",
  "security/detect-pseudoRandomBytes": "error"
}

5. Package.json Scripts Integration

• lint - Run ESLint on all source files
• lint:fix - Run ESLint with auto-fix
• lint:security - Focus on security-related issues
• lint:ci - CI-friendly linting without auto-fix

6. IDE Integration Files

• VSCode settings for ESLint integration
• .eslintignore for excluding build artifacts and dependencies
• Prettier integration if not conflicting with existing setup

7. GitHub Actions Integration

• Add linting step to CI/CD pipeline
• Security-focused linting checks
• Fail builds on security violations

Configuration Structure

Primary Configuration (eslint.config.js)

import js from '@eslint/js';
import tseslint from '@typescript-eslint/eslint-plugin';
import tsparser from '@typescript-eslint/parser';
import security from 'eslint-plugin-security';
import noSecrets from 'eslint-plugin-no-secrets';

export default [
  js.configs.recommended,
  {
    files: ['**/*.ts', '**/*.js'],
    languageOptions: {
      parser: tsparser,
      parserOptions: {
        ecmaVersion: 2022,
        sourceType: 'module',
        project: './tsconfig.json'
      }
    },
    plugins: {
      '@typescript-eslint': tseslint,
      'security': security,
      'no-secrets': noSecrets
    },
    rules: {
      // Security rules
      ...security.configs.recommended.rules,
      // TypeScript rules
      ...tseslint.configs.recommended.rules,
      // Custom project-specific rules
    }
  }
];

Success Criteria

• ESLint successfully lints all TypeScript and JavaScript files
• Security plugins detect and prevent common vulnerabilities
• No false positives that block legitimate code patterns
• Integration with existing development workflow (npm scripts)
• VSCode integration working for real-time feedback
• CI/CD pipeline includes linting with security checks
• Documentation updated with linting guidelines
• All existing code passes linting (or documented exceptions)

Security Focus Areas

1. Input Validation - Detect unsafe user input handling
2. Injection Prevention - Prevent SQL/NoSQL/Command injection
3. Cryptographic Security - Ensure secure random number generation
4. File System Security - Prevent path traversal vulnerabilities
5. Secret Management - Detect hardcoded credentials
6. Regular Expression Security - Prevent ReDoS attacks
7. Child Process Security - Secure subprocess execution

Performance Considerations

• Optimize ESLint configuration for fast execution
• Use incremental linting where possible
• Cache ESLint results to improve CI/CD performance
• Configure appropriate file exclusions

Implementation Priority

1. Core ESLint setup with TypeScript support
2. Security plugin integration
3. Basic rule configuration
4. Scripts and workflow integration
5. CI/CD pipeline integration
6. Documentation and developer guidance

This implementation will significantly enhance the security posture and code quality of the unthread-webhook-server while maintaining developer productivity and workflow efficiency.

Created from VS Code via the [GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[github-actions]

🔧 Container Build Complete - PR Build

Build Status: ✅ Success
Flow Type: pr
Description: Feature development and testing

---

📦 Pull Image

Docker Hub: docker pull wgtechlabs/unthread-webhook-server:pr-86bbe07

GHCR: docker pull ghcr.io/wgtechlabs/unthread-webhook-server:pr-86bbe07

---

📋 Build Details

Property	Value
Flow Type	pr
Commit	86bbe07
Registry	both
Image Tags	wgtechlabs/unthread-webhook-server:pr-86bbe07,ghcr.io/wgtechlabs/unthread-webhook-server:pr-86bbe07

---

🔍 Testing Your Changes

1. Pull the image using one of the commands above
2. Run the container with your test configuration
3. Verify the changes work as expected
4. Report any issues in this PR

---

🚀 Quick Start

# Pull and run the container
Docker Hub: docker pull wgtechlabs/unthread-webhook-server:pr-86bbe07
docker run <your-options> <image>

---

_{🤖 Automated comment by Container Build Flow Action}