ComusThumbz Original Updated for PHP 8

Welcome to the Comus Manual

If you are a prior ComusThumbs user this is a must read...  You may remember before ComusThumbs lost all support and no longer recieved updates it was hacked (around Nov 2008).  You can view the issues here: 
Latest Update (2.53-024 [Jan 12 09]) [SECURITY ALERT]

  After reviewing the ComusThumbs code I found a LOT of security issues that may (or may not) have been the source of his hack. I have done my best to close all security issues with the script to harden all possible entry points and  
  make it difficult for a would be hacker to cause issues.

  Beyond security, the entire codebase has been modernized to work with current PHP standards (8.1+), and several tools have been significantly improved to work better with today's internet.

  ---
  Security Fixes

  Some (but not all) of the security fixes are as follows:

  Authentication & Session Management
  - Replaced the legacy cookie-based authentication system with server-side session validation
  - Implemented secure session cookies with HttpOnly, Secure, and SameSite attributes
  - Added session fingerprinting to detect and prevent session hijacking
  - Added activity-based session timeouts (idle and absolute) to limit exposure window
  - Replaced weak session ID generation with cryptographically secure random bytes
  - Converted session storage engine to prevent database lock contention
  - Added brute-force login throttling (per-IP rate limiting)
  - Hardened all legacy cookie operations across the application

  Database Security
  - Migrated all database queries to use parameterized prepared statements
  - Replaced blacklist-based input filtering with proper query parameterization
  - Removed legacy string concatenation in query construction
  - Secured the admin search and filter system against injection via user input
  - Secured the bulk record operations (update, delete, replace) against injection
  - Removed error messages that exposed database structure or query details to end users

  Cross-Site Scripting (XSS) Prevention
  - Applied output encoding to all user-supplied data rendered in HTML contexts
  - Secured JavaScript variable assignments against injection via form data
  - Escaped all error and debug messages that previously echoed raw user input
  - Secured dynamically generated form actions and link attributes
  - Removed legacy debug output that exposed internal system information

  Cross-Site Request Forgery (CSRF)
  - Implemented token-based CSRF protection on all destructive admin operations
  - Added CSRF verification to form submissions across the admin panel and public-facing forms

  Input Validation & Sanitization
  - Replaced the legacy keyword-blacklist sanitizer with context-appropriate validation
  - Added proper email format validation using modern PHP filter functions
  - Added URL scheme validation to prevent malicious protocol injection
  - Implemented input length and bounds checking on image processing parameters
  - Stripped newline characters from all inputs used in email headers to prevent header injection
  - Replaced unsafe type coercion with explicit integer casting on all numeric inputs

  File System & Path Security
  - Added path traversal protection on all user-supplied file paths used in image operations
  - Restricted image source paths to designated temporary directories only
  - Applied filename filtering on overlay and template file references to prevent directory escape
  - Added null byte detection in file path handling

  Command Injection Prevention
  - Sanitized all external tool parameters passed to shell commands (ImageMagick, FFmpeg)
  - Added execution timeouts on all subprocess calls to prevent resource exhaustion
  - Implemented process termination for hung external commands

  Network Security
  - Added Server-Side Request Forgery (SSRF) validation on all outbound HTTP requests
  - Replaced the legacy socket-based HTTP client with a modern, hardened implementation
  - Added proper SSL/TLS verification on outbound connections
  - Secured URL resolution against open redirect and path traversal attacks
  - Added request timeouts and retry limits on all external HTTP operations

  Access Control
  - Added authentication gates to previously unprotected administrative endpoints
  - Secured background worker processes against unauthorized execution
  - Restricted debug mode activation to authenticated administrators only
  - Blocked direct web access to log files and debug artifacts

  Cryptographic Improvements
  - Replaced MD5 hashing with SHA-256 for all non-password hash operations
  - Replaced predictable random number generation with cryptographically secure alternatives

  ---
  Code Modernization

  The entire codebase has been brought up to current PHP 8.1+ standards:

  Session System Rewrite
  - The old custom database-based session system has been replaced with PHP's native session handling
  - Sessions are now faster, more reliable, and compatible with modern hosting environments
  - Legacy session data is automatically migrated on first login — no manual steps needed
  - All existing features (pagination state, search filters, preferences) continue to work as before

  Database Query Modernization
  - All database operations now use prepared statements — the modern standard for safe, fast queries
  - The old pattern of building queries by stitching together text strings has been completely replaced
  - A new FormDataBag helper class provides clean, type-safe access to form data, replacing the legacy variable-variable pattern that was difficult to maintain and debug

  HTTP Client Upgrade
  - The legacy socket-based HTTP client (fsockopen) has been replaced with a modern curl-based implementation
  - All outbound connections now properly handle HTTPS, redirects, compression, and timeouts
  - Gallery scanning is more reliable across a wider variety of websites and hosting configurations

  Class and Code Structure
  - All PHP classes updated to modern syntax (proper constructors, visibility declarations, type hints)
  - Dead code removed — over 500 lines of unused legacy code cleaned up
  - Added documentation comments throughout key functions for future maintainability

  ---
  Gallery Scanner Improvements

  The gallery scanning tools (Scan URL, Thumb Scanner, Turbo Cropper) have been significantly improved:

  Universal Scanner
  - The scanner now works with a much wider variety of gallery page formats and hosting setups
  - Pages that redirect (302) are now followed correctly — images are found on the final destination page, not the redirect URL
  - Galleries that host their images on separate CDN or content servers (very common today) are now detected properly
  - URLs containing common words (like "join", "select", "password") are no longer broken by the old text filter

  Video Support
  - When the scanner finds a video on a gallery page, it now automatically extracts still frames from the video using FFmpeg
  - Up to 20 frames are pulled from evenly spaced points throughout the video, giving you plenty of choices for your thumbnail
  - If multiple videos are found, the frames are split evenly (2 videos = 10 frames each, 4 videos = 5 each)
  - Frame images are created at double the video resolution for the best quality crop
  - This works on video-only galleries where previously no images would be found

  Modern HTML Detection
  - The scanner now finds media embedded in JavaScript video players (JWPlayer, MediaElement, etc.)
  - HTML5 <video> and <source> tags are detected, even when dynamically loaded
  - Open Graph meta tags (og:video, og:image) are checked for additional media
  - This means galleries using modern web players are now fully supported

  Thumbnail Cropping Enhancements
  - Crosshair Overlay — A yellow camera-style viewfinder crosshair appears on the crop box so you always know the exact center of your selection
  - Live Preview — A real-time preview window shows exactly what your cropped thumbnail will look like before you commit, now available in both the Thumb Scanner and Scan URL pages (previously only in the Turbo Cropper)
  - Crop Button — A green "CROP" button appears below your selection, eliminating the guesswork of clicking inside the box
  - Keyboard Shortcuts — Press Enter or Space to crop instantly without touching the mouse
  - Double-Click to Crop — Double-clicking inside the crop box immediately saves your selection
  - Crop Accuracy Fix — Fixed a long-standing issue where the cropped thumbnail could drift or shift from what was shown in the red box, caused by coordinate scaling when images were displayed smaller than their actual size

  Thumbnail Grid Layout
  - Scanned images are now displayed in a responsive grid that automatically fills the available width
  - No more single-column layouts — you'll see as many thumbnails per row as your screen allows
  - Each thumbnail shows a "Keep" option for quick selection without cropping

  ---
  Auto Scan & Batch Operations

  Improved Reliability
  - All batch operations (Auto Scan, Auto Thumb, Turbo Thumb, 404 Check, etc.) now run more reliably without causing server timeouts
  - The scanner properly handles slow or unresponsive gallery sites without hanging
  - Background operations report progress in real time so you can monitor what's happening

  Video Frame Extraction in Batch Mode
  - Turbo Thumb and Auto Thumb now include video frame extraction — if a gallery has videos but no images, frames are automatically pulled for thumbnail creation
  - This applies to all scanning methods: individual scan, batch scan, and auto scan

  ---
  Modular Admin Panel

  The main admin control panel has been restructured from a single 7,000+ line file into focused modules:

  Query Builder
  - The search, filter, and pagination logic has been extracted into its own module
  - Searches can now be bookmarked — a permalink appears in the pagination bar that captures your current search, filters, page number, and sort order in the URL
  - Shared or bookmarked search links restore the exact view when opened

  Command Handler
  - All batch commands (Auto Scan, Turbo Thumb, Delete, Replace, Export, 302 Check, 404 Check, etc.) are organized in a dedicated module
  - Each command's logic is self-contained and easier to maintain or extend

  Record Editor
  - The gallery record save system has been extracted with modern form handling
  - Uses parameterized database queries for all record updates
  - Cleaner, auditable code for every field save operation

  Batch Processor
  - Background job processing has been moved to its own module
  - Includes the new job queue system for submitting batch operations
  - Real-time progress monitoring with cancel support

  Scanner Configuration
  - All scanner settings (timeouts, image quality, proxy, FFmpeg paths, etc.) are consolidated in a single configuration class
  - Settings load from the database once and are available everywhere — no more scattered global variables
  - Connection reuse for faster scanning — the same HTTP connection is kept open when downloading multiple images from the same website