Release v2.2.0 - Critical Security Fixes & Performance Improvements

🚀 Release Date

October 22, 2025

📋 Overview

This release includes 7 critical security fixes and significant performance improvements identified in the comprehensive backend code audit. These are high-impact, low-effort improvements that significantly enhance production security, performance, and reliability.

Total Investment: ~2.5 hours of development | Impact: Critical security vulnerabilities eliminated + 10x-40x performance improvement

🔒 Security Fixes (6 Critical/High Vulnerabilities Eliminated)

1. Production DISABLE_AUTH Guard 🔴 Critical

Commit: d70c1f1

• Prevents DISABLE_AUTH environment variable from bypassing authentication in production
• Added runtime check in requireAuth() middleware - returns 500 error if misconfigured
• Added startup check in index.ts - exits process if DISABLE_AUTH=true in production
• Logs security violations with IP and path

2. NoSQL Injection Prevention 🔴 Critical

Commit: e922d41

• Created whitelist of 5 allowed collections: analyses, repos, azdtests, rulesets, configuration
• Added isAllowedCollection() type-safe validation function
• Returns 400 error for invalid collections with helpful message
• Capped query limit at 100 to prevent DoS

Attack Vectors Blocked:

• ❌ /db-query/admin.system.users
• ❌ /db-query/../../../etc/passwd
• ✅ /db-query/analyses (allowed)

3. Memory Leak Fix 🟠 High

Commit: 22b84ab

• Token refresh setInterval() now properly cleared
• Store interval ID in tokenRefreshInterval property
• Clear existing interval before creating new one
• Clear interval on disconnect
• Added debug logging for cleanup

4. Batch Size Limits (DoS Prevention) 🟠 High

Commit: c4c8556

• Added MAX_BATCH_SIZE = 50 constant
• Validate batch size before processing
• Return 400 error with helpful message if limit exceeded
• Prevents server crash from unlimited batch requests

5. Request Timeouts 🟡 Medium

Commit: 1265933

• Created createTimeoutSignal() helper with 30-second timeout
• Added AbortController to all GitHub API fetch calls
• Clean up timeout timers with .finally() to prevent memory leaks
• Returns clear timeout errors instead of silent hangs

6. Enhanced Rate Limiting 🟡 Medium

Commit: a0c19a1

Improvements:

• User-based keys: Use req.user.login for authenticated users (more accurate than shared IPs)
• Batch rate limit: 3 requests/hour (new tier for batch operations)
• Strict rate limit: 10 requests/15 minutes (was 10/minute - too lenient)
• Conditional limiting: Batch requests get stricter limits automatically

Rate Limit Tiers:

🚀 Performance Improvements

N+1 Query Optimization - Leaderboard API

Commit: a1adc95

Before: 101 database queries, ~2000ms response time
After: 1 aggregation query, ~50-200ms response time
Improvement: 10x-40x faster! 🎉

• Replaced Promise.all loop with single MongoDB aggregation query
• Used $lookup to join repos and analysis collections
• Added explicit TypeScript typing for aggregation result

✅ Test Coverage

New Test Files

Commit: 6472cf4

packages/server/src/middleware/tests/auth.test.ts

• ✅ DISABLE_AUTH blocked in production
• ✅ DISABLE_AUTH allowed in development/test
• ✅ Error logging with IP/path

packages/server/tests/routes/admin.test.ts

• ✅ Valid collection names accepted
• ✅ System collections rejected
• ✅ Path traversal attempts blocked
• ✅ NoSQL injection attempts blocked
• ✅ Case-sensitive validation

packages/server/tests/routes/analyze.test.ts

• ✅ Batch size validation (0, 1, 50, 51, 1000 repos)
• ✅ Error response structure

packages/server/tests/middleware/rate-limit.test.ts (enhanced)

• ✅ User-based vs IP-based keys
• ✅ Batch rate limit (3/hour)
• ✅ Rate limit windows (15 min, 1 hour)
• ✅ Conditional rate limiting

packages/server/tests/middleware/timeout.test.ts

• ✅ AbortSignal creation
• ✅ Timeout abort after 30s
• ✅ Cleanup on completion
• ✅ Error handling

Test Results:

• 65 tests passing ✅
• 27 tests skipped (require running server - expected)
• 0 tests failing ✅

🧹 Cleanup

Legacy Test Removal

Commit: 664a539

• Deleted tests/unit/legacy-api/ (8 files, 606 lines)
• Tests for deprecated Azure Functions API
• Code archived in legacy/azure-functions branch
• All functionality now in Express server

Playwright Test Fixes

Commits: 5ac4d4b, 2ff389b

• Changed vitest → @playwright/test in error detection spec
• Fixed duplicate test titles
• Updated port 4000 → 3000 (production architecture)
• All tests use correct framework

📊 Security Summary

🔧 Deployment Considerations

Environment Variables

All fixes work with existing environment variables. Optional new variables for rate limiting:

# Optional rate limit customization
RATE_LIMIT_STRICT_WINDOW_MS=900000    # 15 minutes (default)
RATE_LIMIT_STRICT_MAX=10              # 10 requests (default)
RATE_LIMIT_BATCH_WINDOW_MS=3600000    # 1 hour (default)
RATE_LIMIT_BATCH_MAX=3                # 3 requests (default)

Breaking Changes

None. All changes are backward compatible. Security fixes apply automatically.

Production Checklist

• ✅ All tests passing (65/65)
• ✅ No new dependencies
• ✅ No schema changes
• ✅ Environment variables backward compatible
• ✅ Security fixes active immediately on deployment

📝 Complete Commit List

2ff389b fix: update Playwright tests to use port 3000 (production architecture)
5ac4d4b fix: correct Playwright test issues
6472cf4 test: add comprehensive tests for Quick Wins security fixes
664a539 chore: remove legacy Azure Functions API tests
a0c19a1 security: enhance rate limiting with batch limits and user-based keys
1265933 fix: add request timeouts to prevent hanging GitHub API calls
c4c8556 security: add batch size limit to prevent DoS attacks
a1adc95 perf: eliminate N+1 query in leaderboard (101 queries → 1)
22b84ab fix: prevent memory leak in Cosmos DB token refresh
e922d41 security: prevent NoSQL injection via collection whitelist
d70c1f1 security: add production guard for DISABLE_AUTH environment variable

🎯 Recommendation

Deploy immediately. This release:

• ✅ Eliminates 6 security vulnerabilities
• ✅ Improves API performance by 10x-40x
• ✅ Has comprehensive test coverage
• ✅ Contains no breaking changes
• ✅ Requires zero new dependencies
• ✅ Is production-ready

📚 Additional Context

• Previous Version: v2.1.0 (OAuth Authentication & Rate Limiting)
• Next Version: v2.3.0 (planned features TBD)
• Documentation: See AGENTS.md for development guidelines
• Security Policy: See SECURITY.md for reporting vulnerabilities

Release v2.1.0

Features

• Add OAuth 2.0 API Authentication (#147) (d312ec7)
• Add rate limiting to API endpoints with UI improvements (#150) (7944293)

Bug Fixes

• update MongoDB connection string placeholder to avoid secret scanning (#148) (cab4c85)

Documentation

• Fix README port references, architecture, and Docker commands (#149) (d8cd612)

🧹 Cleanup & Maintenance Release

This release focuses on codebase cleanup, documentation organization, and code formatting improvements.

Miscellaneous

• Documentation reorganization (#141)

  • Moved documentation to proper directories (docs/development/, docs/usage/, docs/deployment/)
  • Removed 1,668 lines of temporary files
  • Organized by purpose with clean root directory
  • Updated all cross-references

• Azurite cleanup (#142)

  • Removed storage emulator configuration files from version control
  • Already covered by .gitignore patterns

• Prettier formatting (#143)

  • Standardized code formatting across 95 files
  • 26,080 insertions, 24,436 deletions
  • TypeScript, JavaScript, JSON, Markdown, and YAML files formatted consistently

Summary

• 3,398 lines removed: Documentation debt and tech debt cleanup
• Better organization: Clean root directory with only GitHub standard files
• Improved consistency: Standardized code formatting across the entire codebase
• No functional changes: Pure cleanup and maintenance

Full Changelog: v2.0.0...v2.0.1

Template Doctor v2.0.0 - Major Architecture Overhaul

Release Date: October 19, 2025

🎉 Overview

Template Doctor 2.0.0 represents a major architectural transformation with modern TypeScript infrastructure, database persistence, and improved security. This release includes breaking changes that modernize the codebase and improve maintainability.

⚠️ Breaking Changes

• TypeScript Migration: Deleted 49 legacy JavaScript files from packages/app/js/. All frontend code has been migrated to TypeScript with modern ES modules.
• Express Server: Migrated from Azure Functions to Express.js backend for improved performance and development experience.
• Database Architecture: Introduced MongoDB persistence layer, replacing file-based storage.

🚀 Major Features

Database Persistence (#135)

• MongoDB integration with comprehensive schema (repos, analysis, configuration, rulesets)
• Automatic persistence of all analysis results
• Historical tracking and trend analysis capabilities
• Seeded database with production-ready sample data

Express Server Migration (#128)

• Complete backend rewrite from Azure Functions to Express.js
• 20+ RESTful API endpoints with consistent error handling
• Improved CORS configuration and middleware architecture
• Enhanced logging with structured request/response tracking

Azure Developer CLI (azd) Support (#126)

• Full azd deployment integration
• Infrastructure as Code with Bicep templates
• Optimized Docker builds (multi-stage, layer caching)
• Azure Container Apps deployment support

Security & Validation

• Comprehensive XSS protection (18 patterns, 56 test cases, defense in depth)
• ACR managed identity authentication (no more password-based auth)
• Enhanced input validation with consistent UX (red borders, clear error messages)
• OSSF Scorecard workflow integration (#53)

Developer Experience

• Agents.md compliance validation (#100)
• Improved issue creation workflow (#92)
• Batch scan functionality (#5)
• Dev container support (Node + Python) (#18)
• Queue-based analysis requests with service readiness polling

🐛 Notable Bug Fixes

• Fixed action button visibility and interactivity
• Improved authentication flow after merge (#26)
• Fixed historical data display (#10)
• Better fork detection and handling
• Enhanced PR creation workflow (#44)
• Fixed Test AZD deployment button endpoint (#63)
• Improved OSSF Scorecard logging (#85)

📚 Documentation

• Comprehensive migration guides
• Updated API documentation
• Enhanced contribution guidelines
• Docker deployment instructions
• Database schema documentation

🔧 Migration Guide

For Users

• No action required - the application maintains backwards compatibility at the API level
• Analysis results now persist to database automatically
• Old file-based results remain accessible for historical reference

For Developers

• Update to Node.js 18+ LTS
• Use docker-compose --profile combined up for local development
• TypeScript is now required for all new frontend code
• See AGENTS.md for detailed development workflow

For Deployers

• MongoDB database required (Azure Cosmos DB recommended)
• Update environment variables (see docs/development/ENVIRONMENT_VARIABLES.md)
• Use azd up for simplified Azure deployment
• Docker images now use multi-stage builds

📦 Installation

# Clone repository
git clone https://github.com/Azure-Samples/template-doctor.git
cd template-doctor

# Install dependencies
npm ci

# Start with Docker (recommended)
docker-compose --profile combined up

# Or use Azure Developer CLI
azd up

🔗 Related

• Full changelog: CHANGELOG.md
• Migration docs: docs/development/EXPRESS_MIGRATION_MATRIX.md
• Database schema: docs/development/DATABASE_SCHEMA_V2.md
• Contributing: CONTRIBUTING.md

🙏 Credits

• Artifact parsing and UX improvements (@anfibiacreativa)
• Database architecture design (@anfibiacreativa)
• Deployment automation (@anfibiacreativa)
• Security fixes (@anfibiacreativa)
• Logging and observability (@anfibiacreativa)

What's Next? v2.1.0 will focus on leaderboards, additional AI model integrations, and further performance optimizations.

[1.0.0] - 2025-10-07

🎉 Major Release - Express Architecture Migration

Template Doctor 1.0.0 marks the completion of the TypeScript migration and transition from Azure Functions to a containerized Express-based architecture.

Added

• Express Backend (packages/server): New TypeScript REST API on port 3001
  • OAuth token exchange
  • Template validation endpoints
  • GitHub integration
  • CORS-enabled for frontend communication
• Docker Deployment: Containerized architecture with Dockerfile.combined
  • Single-container production build
  • Multi-container development setup with docker-compose.yml
• TypeScript Frontend: Vite SPA with HMR for fast development
  • Port 4000 (development), Port 3000 (preview/production)
• Comprehensive Documentation:
  • Updated README with Express architecture
  • Docker deployment instructions
  • Troubleshooting guide
  • Port allocation table

Changed

• Architecture: Migrated from Azure Functions to Express server
• Build System: Added build:all with correct dependency order (analyzer-core → server → app)
• Test Suite: Reorganized unit tests
  • Moved legacy API tests to tests/unit/legacy-api/
  • Excluded legacy tests from vitest
  • Only analyzer.categories.spec.js runs in CI (6 tests, all passing)

Removed

• Azure Static Web Apps: Removed all SWA deployment workflows
  • manual-swa-deploy.yml
  • manual-swa-deploy-simple.yml
  • nightly-swa-deploy.yml
• Azure Functions: Removed legacy serverless deployment
  • azure-functions-v4.yml workflow deleted
  • Legacy API code preserved in legacy/azure-functions branch
• Legacy Tests: 7 legacy API tests moved out of CI
  • Tests depend on removed Azure Functions code
  • Preserved in tests/unit/legacy-api/ for reference

Fixed

• Build Order: analyzer-core builds before dependent packages
• Package Verification: Updated scripts/verify-packages.sh for current structure
• TypeScript Compilation: All packages compile without errors
• Vitest Configuration: Properly excludes legacy-api tests

Infrastructure

• CI/CD Workflows:
  • Removed: smoke-api.yml (TODO: re-add after debugging server startup)
  • Active: guard-packages, validation, submit-analysis, etc.
• Environment Variables: Consolidated configuration
  • Backend: packages/server/.env (copied from root during build)
  • Frontend: packages/app/config.json (client config)
  • Root: .env (single source of truth)

Breaking Changes

• Deployment Method: No longer uses Azure Static Web Apps or Azure Functions
  • New deployment: Docker containers via Dockerfile.combined
  • See README for migration instructions
• Port Changes:
  • Express backend: 3001 (was: Azure Functions on 7071)
  • Frontend preview: 3000 (was: 5173)
  • Frontend dev: 4000 (was: 5173)
• Legacy API: Removed from production
  • Code preserved in legacy/azure-functions branch for reference
  • Express server provides equivalent functionality

Migration Guide

For users upgrading from pre-1.0.0 versions:

1. Pull latest changes:

   git pull origin main
   npm ci

2. Update OAuth configuration:

   • Update GitHub OAuth app callback URLs to use port 3000/3001
   • See docs/development/OAUTH_CONFIGURATION.md

3. Docker deployment (recommended):

   docker build -f Dockerfile.combined -t template-doctor .
   docker run -p 3000:3000 --env-file .env template-doctor

4. Manual deployment:

   npm run build:all
   npm run preview -w packages/server

Known Issues

• Smoke API tests disabled (TODO: fix Express server startup in CI)
• See TODO.md for tracked improvements

Contributors

Thank you to all contributors who made this release possible!

@anfibiacreativa
@diberry
@vhvb1989