KAScope - Kasserver Account Analyzer

A modern, full-stack application for analyzing Kasserver subaccounts, categorizing them into hosting/email plans, and providing export, cleanup, and debug functionality.

🚀 Features

Secure Authentication: Login with Kasserver main account credentials (not stored permanently)
Account Analysis: Automatically fetch and analyze up to 200 subaccounts
Plan Categorization: Smart categorization into Hosting S/M/L and E-Mails S/M/L plans
Real-time Progress: Live progress tracking during analysis
Multiple Export Formats: Export results as Excel (.xlsx) or PDF
Database Cleanup: Securely delete all sensitive data after analysis
Debug System: Built-in debug panel showing API requests/responses
Modern UI: Clean, responsive React interface

📋 Prerequisites

Node.js 18+ and npm
Kasserver API access credentials
Windows/Mac/Linux operating system

🛠️ Tech Stack

Backend

Node.js + Express
SQLite (better-sqlite3)
Axios (Kasserver API client)
Winston (logging)
XLSX (Excel export)
PDFKit (PDF export)

Frontend

React 18
Vite
React Router DOM
Zustand (state management)
Axios (API calls)

📦 Installation

1. Clone the Repository

git clone https://github.com/ExpoXR/KAScope.git
cd KAScope

2. Backend Setup

cd backend
npm install

Create a .env file from the example:

cp .env.example .env

Edit .env and configure your settings. The backend refuses to start unless the required secrets below are set to real values (the shipped placeholders are rejected). Generate secrets with e.g. openssl rand -base64 36:

# REQUIRED — admin login (seeds the first admin user on first boot)
ADMIN_USERNAME=your_admin_username
ADMIN_PASSWORD=your_strong_admin_password   # >= 8 chars

# REQUIRED — JWT signing secret (>= 32 chars) and AES key (>= 16 chars)
JWT_SECRET=your_long_random_jwt_secret
JWT_EXPIRY=24h
ENCRYPTION_KEY=your_long_random_encryption_key

# Server Configuration
PORT=3000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173   # CORS origin

# Database Configuration
DB_PATH=../database/kascope.db

Kasserver API credentials are not set here — configure them in the Settings screen after logging in. They are stored AES-256-encrypted at rest.

3. Frontend Setup

cd ../frontend
npm install

Create a .env file (optional):

cp .env.example .env

The default backend URL is http://localhost:3000. Change if needed:

VITE_API_URL=http://localhost:3000

🚀 Running the Application

Start the Backend Server

cd backend
npm start

Or for development with auto-reload:

npm run dev

The backend will start on http://localhost:3000

Start the Frontend

In a new terminal:

cd frontend
npm run dev

The frontend will start on http://localhost:5173

📖 Usage Guide

1. Login Page

Enter your Kasserver main account login and password
Click "Login & Fetch Accounts"
The system will fetch all subaccounts and store them temporarily

2. Subaccount Overview

View all subaccounts with their resource limits
Review domains, subdomains, SSL, databases, webspace, mail accounts, and mail forwards
Click "Start Analyse All Accounts" to begin analysis

3. Analysis Progress

Real-time progress indicator showing current account being analyzed
Progress bar with percentage completion
Automatic redirect to results when complete

4. Results Page

View Analysis Results:

Current vs. Recommended hosting plans
Current vs. Recommended email plans
Status indicators for accounts needing plan changes

Export Options:

Export all results as Excel
Export all results as PDF
Export individual account as Excel

Database Cleanup:

Click "Cleanup Database" to securely delete all data
Confirms before deletion
Redirects to login after cleanup

5. Debug Panel

Click "Debug Info" button (bottom-right corner)
View recent API requests and responses
Timestamps and detailed logs
Expandable JSON data view

🗂️ Project Structure

KAScope/
├── backend/
│   ├── routes/
│   │   ├── api.js           # Main API routes (login, accounts, analyse, results)
│   │   ├── export.js        # Export routes (Excel, PDF)
│   │   └── cleanup.js       # Database cleanup route
│   ├── database.js          # SQLite database setup and queries
│   ├── kasserver-client-v2.js # Kasserver API client
│   ├── logger.js            # Winston logger and debug system
│   ├── plan-categorizer.js  # Plan categorization logic
│   ├── server.js            # Express server setup
│   ├── package.json
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── DebugPanel.jsx       # Floating debug panel
│   │   │   ├── FetchDebugModal.jsx  # Account-fetch debug modal
│   │   │   └── ProgressBar.jsx      # Multi-step progress indicator
│   │   ├── pages/
│   │   │   ├── Login.jsx         # Login page
│   │   │   ├── Overview.jsx      # Accounts overview
│   │   │   ├── AnalyseProgress.jsx  # Analysis progress
│   │   │   ├── Results.jsx       # Results with export
│   │   │   └── Settings.jsx      # API testing, cache & debug
│   │   ├── services/
│   │   │   └── api.js           # API client
│   │   ├── store/
│   │   │   └── useStore.js      # Zustand state management
│   │   ├── utils/
│   │   │   └── planUtils.js     # Plan helpers (uses /api/plans)
│   │   ├── constants.js        # Shared thresholds, colors, steps
│   │   ├── App.jsx              # Main app with routing
│   │   ├── main.jsx             # Entry point
│   │   └── index.css            # Global styles
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   └── .env.example
├── database/                # SQLite database (auto-created)
├── logs/                    # Log files (auto-created)
└── README.md

🔒 Security

JWT authentication: admin login issues a signed JWT (jsonwebtoken); every /api/* route except /api/auth/* and /health requires a valid Authorization: Bearer token. Admin passwords are hashed with bcrypt.
Fail-fast secrets: the server refuses to boot without JWT_SECRET, ENCRYPTION_KEY, ADMIN_USERNAME, and ADMIN_PASSWORD — and rejects the shipped placeholder values. There is no hardcoded fallback secret.
Encryption at rest: Kasserver credentials and cached subaccount passwords are stored AES-256-encrypted (ENCRYPTION_KEY). Cached passwords also expire after 24 h. No other value is encrypted; the rest is operational data.
Brute-force protection: POST /api/auth/login is rate-limited per IP.
Hardening: helmet security headers; CORS locked to FRONTEND_URL; all DB access via parameterized prepared statements; passwords redacted from request logs; export filenames sanitized against header injection.
Data wipe: all analysed/cached data can be deleted at any time — DELETE /api/cleanup, DELETE /api/cache?type=all, or POST /api/cleanup-and-refresh. Admin users and the (encrypted) Kasserver credentials are intentionally preserved so the operator is not locked out; rotate them from the Settings screen.
Secrets never committed: .env and *.db are gitignored; only .env.example (placeholders) is tracked.

Fonts load from Google Fonts by default. For fully offline / privacy-first deployments, self-host Manrope + JetBrains Mono and drop the <link> tags in frontend/index.html.

📊 Plan Categorization Logic

These values are the single source of truth in backend/plan-categorizer.js and are served to the frontend via GET /api/plans.

Hosting Plans

Plan	Domains	Subdomains	SSL	Databases	Webspace (GB)
Hosting S	3	6	2	3	3
Hosting M	6	12	3	6	5
Hosting L	12	24	6	12	10

Email Plans

Plan	Mail Accounts	Mail Forwards	Webspace (GB)
E-Mails S	12	15	2
E-Mails M	24	30	4
E-Mails L	40	50	6

Recommendation Logic:

"What is": Determined by current account limits
"What should be": Smallest plan that fits actual usage
If usage exceeds all plans, recommends "Plan++"

🐛 Troubleshooting

Backend won't start

Check if port 3000 is already in use
Verify Node.js version (18+)
Ensure all dependencies are installed: npm install
Check .env file exists and is properly configured

Frontend can't connect to backend

Verify backend is running on http://localhost:3000
Check browser console for CORS errors
Ensure VITE_API_URL in frontend .env matches backend URL

Analysis fails or times out

Check Kasserver API credentials in backend .env
Verify Kasserver API is accessible
Check logs in logs/debug.log for detailed errors
Kasserver API has rate limits - analysis may need time

Database errors

Ensure database/ directory exists and is writable
Delete database/kascope.db and restart to recreate
Check file permissions

📝 API Endpoints

Backend API Routes

Method	Endpoint	Description
POST	`/api/login`	Login and fetch accounts
GET	`/api/accounts`	Get all accounts
POST	`/api/check-subaccounts`	Refresh the subaccount list
POST	`/api/cleanup-and-refresh`	Wipe data and re-fetch accounts
POST	`/api/fetch-account-info`	Fetch detailed info for one account
POST	`/api/analyse`	Start analysis (SSE stream)
GET	`/api/results`	Get analysis results
GET	`/api/plans`	Get hosting/email plan definitions
POST	`/api/refresh-cache`	Refresh cached data (all/one account)
GET	`/api/cache-status`	Inspect cache freshness
DELETE	`/api/cache`	Clear cache (all / cache-only / one account)
GET	`/api/export/all/excel`	Export all as Excel
GET	`/api/export/all/pdf`	Export all as PDF
GET	`/api/export/account/:id/excel`	Export single account
DELETE	`/api/cleanup`	Cleanup database
GET	`/api/debug/logs`	Get debug logs
GET	`/health`	Health check

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Open a Pull Request

📄 License

👤 Author

Created as part of the KAScope project for Kasserver account management.

🙏 Acknowledgments

Kasserver for their API
React team for the amazing framework
All open-source contributors

Need Help? Check the logs in logs/debug.log or use the Debug Panel in the UI for detailed information about API calls and errors.

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation