Senzor Core

The robust, secure, and high-performance API core for the Senzor VPS Monitoring platform. Built with Node.js, Express, and TypeScript, it handles user authentication, agent telemetry ingestion, real-time WebSockets, background workers, and data persistence with MongoDB.

🚀 Key Features

• Secure Authentication:
  • Users: Firebase Admin SDK (JWT verification).
  • Agents: Custom API Key & VPS ID headers.
• High-Performance Ingestion: "Fire-and-forget" telemetry endpoint optimized for high throughput.
• Global Uptime: Integrated background workers for distributed heartbeat checks (HTTP/TCP).
• Web Terminal: Secure SSH-over-WebSocket relay for browser-based server management.
• Secure Auth: Firebase Admin SDK integration (JWT) with Role-Based Access Control (RBAC).
• Plan-Based Retention: Per-document MongoDB TTL (expiresAt) automatically expires telemetry at the end of each tenant's plan retention window — Starter 3 days, Pro 15 days, Business 30 days, Enterprise 90 days — applied uniformly across all telemetry collections, with a hard-cap backstop index to bound storage.
• Validation: Strict runtime payload validation using Zod.
• Security Hardening: Implements helmet, cors, and aggressive rate-limiting to prevent abuse.

🛠 Tech Stack

• Runtime: Node.js (v18+)
• Language: TypeScript
• Framework: Express.js
• Real-time: Socket.io
• Database: MongoDB (Mongoose ODM)
• Auth: Firebase Admin SDK
• Validation: Zod
• Logging: Winston

⚙️ Prerequisites

Before starting, ensure you have:

1. Node.js (v18 or higher) & npm installed.
2. MongoDB Database (Local or Atlas) connection string.
3. Firebase Project with a Service Account JSON key.

📦 Installation

1. Clone the repository:

 git clone https://github.com/Senzops/core
cd core

2. Install dependencies:

 npm install

3. Configure Environment:
   Create a .env file in the src/config directory:

   cp src/config/.env.example src/config/.env
   

🔐 Environment Variables

You must configure the following variables in your /src/config/.env file:

# Server ConfigPORT=5000NODE_ENV=development# Database Connection# IMPORTANT: Append ?authSource=admin if using root authMONGO_URI=mongodb://root:password@localhost:27017/senzor?authSource=admin# Demo User (firebaseUid)# OPTIONAL: Add when demo access requiredDEMO_USER_ID=senzor-demo-account# Firebase Service Account (JSON String)# Copy the entire content of your service-account.json into this single lineFIREBASE_SERVICE_ACCOUNT='{"type":"service_account","project_id":"...","private_key":"..."}'

🏃‍♂️ Running the Server

Development Mode

Runs with ts-node-dev for hot-reloading and direct TypeScript execution.

npm run dev

Production Mode

Compiles TypeScript to JavaScript (dist/) and runs the optimized build.

npm run build
npm start

📚 API Endpoints

1. Server Management

Headers: Authorization: Bearer <firebase_id_token>

Method	Endpoint	Description
POST	/api/vps/register	Register a new VPS. Returns SERVER_ID & API_KEY.
GET	/api/vps/list	List all servers with status summaries.
GET	/api/vps/:id/stats	Get historical telemetry, docker stats, and integrations.
DELETE	/api/vps/:id	Irreversibly delete a server and its data.

2. Web Analytics

Headers: Authorization: Bearer <firebase_id_token>

Method	Endpoint	Description
POST	/api/web/register	Register a website for tracking. Returns WEB_ID.
GET	/api/web/list	List tracked websites.
GET	/api/web/:id/stats	Get views, visitors, heatmaps, and geo-data.

3. Uptime Monitor

Headers: Authorization: Bearer <firebase_id_token>

Method	Endpoint	Description
POST	/api/uptime/register	Create a new HTTP/TCP monitor.
GET	/api/uptime/list	List all monitors.
GET	/api/uptime/:id/stats	Get latency graphs and check history.

4. Ingestion API (Public/Agent)

Rate Limited: 60-200 req/min

Method	Endpoint	Auth Header	Description
POST	/api/ingest/stats	x-api-key	Ingest Server Telemetry.
POST	/api/ingest/web	Body webId	Ingest Web Analytics (Pageviews/Pings).
WS	/api/socket	x-api-key	Secure WebSocket for Web Terminal.

🛡 Security Notes

1. API Keys: Generated using crypto-secure random bytes. In strict compliance environments, these should be hashed in the DB (like passwords). Currently stored as plain text to allow user viewing (optional).
2. Rate Limiting:
   • Management: 100 req / 15 min.
   • Ingestion: 60 req / 1 min per IP (Allows 1 update/sec).
3. Terminal: Access is protected by Firebase Auth on the client side and API Key validation on the agent side.

🧪 Testing Database Connection

If you encounter AuthenticationFailed errors, use the provided test script:

# Edit the URI inside test-db.js first
node ./test/db.js

Coolify / Dokploy Fixes

If deploying to PaaS platforms like Coolify that use PostgreSQL for their internal env storage, you might hit character limits for the Firebase JSON key.

1. Fix Env Var Limit:
   Access your Coolify database container and run:
   docker exec -it coolify-db psql -U coolify -d coolify
   ALTER TABLE environment_variables ALTER COLUMN value TYPE text;

2. Use Base64:
   Always prefer FIREBASE_SERVICE_ACCOUNT_BASE64 for Docker deployments to avoid JSON parsing issues with newlines.