# 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
```bash
npm start          # Production mode
npm run nodemon    # Development mode with auto-reload
```

### Installation
The application is typically installed via:
```bash
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