CDN-APP-INSIDER/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CDN-APP-INSIDER is a self-hosted Content Delivery Network (CDN) application for secure file transfer and management. The application supports multiple authentication methods (Discord, LDAP/ActiveDirectory), file collaboration, and real-time WebSocket updates.

Version: 1.2.0-beta Author: Dinawo - Group Myaxrin Labs Main Contributor: WaYy

Development Commands

Running the Application

npm start          # Production mode
npm run nodemon    # Development mode with auto-reload

Installation

The application is typically installed via:

curl -s https://apollon.dinawo.fr/getcdn/install/latest | bash

After installation, access the dashboard at: https://your-ip:3000/dpanel/dashboard

Prerequisites: A CDN-Access group must exist in your LDAP directory.

Architecture Overview

Core Components

server.js - Application entry point that:

• Initializes Express app with session management and Passport authentication
• Configures authentication strategies based on data/setup.json (Discord, LDAP)
• Sets up WebSocket server for real-time updates
• Starts cron jobs for file cleanup and system reporting
• Protects sensitive JSON files in /data/ directory
• Listens on port 3000 (configurable via PORT env variable)

routes/routes.js - Central routing hub that imports and mounts all route modules with middleware chains

Authentication System

The application uses Passport.js with multiple strategies:

• Discord OAuth (models/Passport-Discord.js)
• LDAP/ActiveDirectory (models/Passport-ActiveDirectory.js)
• Google OAuth (models/Passport-Google.js)

Authentication strategies are conditionally loaded based on data/setup.json configuration.

authMiddleware.js - Core authentication middleware that:

• Validates session authentication via req.isAuthenticated()
• Loads user data from data/user.json
• Attaches user object to req.session.user, res.locals.user, and req.userData
• Redirects unauthenticated users to /auth/login

Logging System (config/logs.js)

Winston-based logging with:

• Daily rotating file logs (14-day retention, 20MB max size)
• Multiple specialized loggers: server, client, error, auth, suspicious, API, filesystem, database
• Configurable via data/setup.json with:
  • logs.enabled: 'on' or 'off'
  • logs.level: 'info', 'warn', 'error', etc.
  • logs.includeOnly: Array of paths to exclusively log
  • logs.excludePaths: Array of paths to exclude from logging
  • logs.levels: Array of enabled log levels

Logs are stored in /logs/ directory with format: log-YYYY-MM-DD.log

Security & Ban System (models/banModel.js)

Progressive ban system that:

• Tracks suspicious requests per IP in data/banUser.json
• Implements escalating ban levels: 10min, 30min, 60min, permanent
• Triggers after 5 suspicious requests within 60 seconds
• Excludes localhost and specific endpoints (ActiveDirectory, favicon)
• All suspicious activity is logged via suspiciousLogger

discordWebhookSuspisiousAlertMiddleware.js - Sends Discord webhook alerts for suspicious API requests

WebSocket System (models/websocketManager.js)

Real-time communication for:

• File collaboration status (who's viewing/editing)
• Broadcasting file updates to all connected clients
• Connection management keyed by userId and fileId
• Sends fileStatus messages with active users array

Access via: req.app.get('wsManager') in routes

File Management

File Storage: All uploaded files are stored in /cdn-files/ directory

File Metadata: Tracked in data/file_info.json with:

• File path, name, size, upload date
• Expiry date for automatic cleanup
• Owner information and permissions

File Cleanup Service (services/fileCleanupService.js):

• Extends BaseService class
• Runs on cron schedule (default: hourly at 0 * * * *)
• Removes expired files based on expiryDate
• Removes orphaned entries for missing files
• Updates data/file_info.json after cleanup

Report Service (services/reportService.js):

• Generates system reports in /report/ directory
• Runs on configurable cron schedule

Data Files

Located in /data/ directory (protected from direct HTTP access):

• user.json - User accounts and roles
• setup.json - Application configuration (auth providers, logging, etc.)
• file_info.json - File metadata registry
• banUser.json - IP ban tracking
• collaboration.json - File collaboration settings

Route Structure

Public Routes

• / - Landing page
• /auth/login - Login page
• /auth/logout - Logout handler
• /auth/activedirectory - AD/LDAP authentication callback
• /auth/discord - Discord OAuth callback
• /attachments - File serving endpoint
• /build-metadata - Build information

Dashboard Routes (/dpanel/dashboard)

• /dpanel/dashboard - Main dashboard (requires auth)
• /dpanel/dashboard/folder - Folder view
• /dpanel/dashboard/profil - User profile
• /dpanel/upload - File upload interface

Admin Routes (/dpanel/dashboard/admin)

Require admin role:

• /dpanel/dashboard/admin - Admin panel
• /dpanel/dashboard/admin/users - User management
• /dpanel/dashboard/admin/settingsetup - System settings
• /dpanel/dashboard/admin/stats-logs - Statistics and logs
• /dpanel/dashboard/admin/Privacy-Security - Security settings

API Routes (/api/dpanel)

All API routes use:

1. discordWebhookSuspisiousAlertMiddleware - Alerts on suspicious activity
2. logApiRequest - Logs API calls with timing

Key endpoints:

• POST /api/dpanel/upload - File upload
• POST /api/dpanel/dashboard/newfolder - Create folder
• PUT /api/dpanel/dashboard/rename - Rename file
• PUT /api/dpanel/folders/rename - Rename folder
• DELETE /api/dpanel/dashboard/delete - Delete file
• DELETE /api/dpanel/dashboard/deletefolder - Delete folder
• POST /api/dpanel/dashboard/movefile - Move file
• POST /api/dpanel/collaboration - Manage file collaboration
• GET /api/dpanel/users/search - Search users
• GET/POST /api/dpanel/sharedfolders - Shared folder operations
• POST /api/dpanel/generate-token - Generate API token
• POST /api/dpanel/revoke-token - Revoke API token

API Documentation

Swagger UI available at: /api/docs

Middleware Chain

Standard middleware chain for protected routes:

authMiddleware → discordWebhookSuspisiousAlertMiddleware → logApiRequest → route handler

Frontend

• View Engine: EJS templates in /views/
• Static Assets: /public/ directory
• CSS: Custom dashboard styles in /public/css/dashboard.styles.css
• JavaScript: Client-side logic in /public/js/dashboard.js
• Styling: TailwindCSS + DaisyUI components

Key Dependencies

• express - Web framework
• passport - Authentication
• socket.io & ws - WebSocket support
• winston - Logging
• node-cron - Scheduled tasks
• multer & express-fileupload - File uploads
• pg & mysql2 - Database support
• bcrypt - Password hashing
• jsonwebtoken - JWT tokens

Important Notes

Security Considerations

• All /data/*.json files are protected from direct HTTP access
• Session secrets are generated using crypto.randomBytes(64)
• Cookies are secure in production (NODE_ENV=production)
• Rate limiting via express-rate-limit
• Progressive ban system for suspicious activity

File Paths

• Always use path.join(__dirname, ...) for file paths
• Normalize paths with path.normalize() and replace backslashes
• File paths in metadata use forward slashes

Session Management

• User data is stored in both session and attached to req.userData
• Session maxAge: 24 hours
• Sessions persist across server restarts via session storage

Error Handling

• Global error handlers catch uncaught exceptions and unhandled rejections
• Errors are logged via ErrorLogger from config/logs
• API errors return JSON with { error, message } structure
• HTML requests receive rendered error pages

WebSocket Events

• join - User joins file view (params: userId, fileId)
• leave - User leaves file view (params: fileId)
• fileStatus - Broadcast of active users on a file

Testing & Debugging

• Winston logs are colorized in console for easier debugging
• Request logging includes IP, User-Agent, method, URL, and timing
• API requests log response status and duration
• Suspicious activity is highlighted with orange prefix
• Error logs include full stack traces