@onurege3467/workspaces

🚀 Secure, feature-rich WebSocket client-server package for Node.js

📖 Table of Contents

Features
Installation
Quick Start
Configuration
API Documentation
Examples
Security
Troubleshooting
Contributing
License

✨ Features

🔒 End-to-End Encryption - Diffie-Hellman key exchange + AES-256-GCM with secure key derivation
🏠 Room/Channel System - Organize clients into rooms for targeted messaging
💓 Heartbeat/Ping-Pong - Keep connections alive and detect dead connections
🔄 Exponential Backoff Reconnection - Smart reconnection strategy that adapts
🗜️ Message Compression - Reduce bandwidth usage with gzip compression
🛡️ Security - Token authentication, IP whitelist, CORS support, Rate limiting
⚡ Remote Code Execution - Secure sandboxed code execution with VM2
🎯 TypeScript - Fully typed with excellent IntelliSense support
✅ 98.1% Test Coverage - Comprehensive test suite with integration tests
🚀 High Performance - 100 clients connect in ~224ms, broadcast in ~112ms

📦 Installation

npm install @onurege3467/workspaces ws

Note: ws is a peer dependency and must be installed separately.

🚀 Quick Start

Server

import { Server } from '@onurege3467/workspaces'

const server = new Server({
  port: 8080,
  token: 'your-secret-token',
  enableEncryption: true,
  enableRooms: true,
  enableHeartbeat: true,
  enableCompression: true,
  allowedOrigins: ['https://example.com'],
  enableRateLimit: true
})

server.listen(() => {
  console.log('Server running on port 8080')
})

// Broadcast to all clients
server.broadcast({ type: 'announcement', message: 'Welcome!' })

// Broadcast to a specific room
server.to('general').broadcast({ type: 'message', content: 'Hello general!' })

Client

import { Client } from '@onurege3467/workspaces'

const client = new Client({
  address: 'localhost:8080',
  token: 'your-secret-token',
  name: 'MyClient',
  enableEncryption: true,
  enableCompression: true,
  reconnectInterval: 5000,
  reconnectMaxInterval: 60000,
  reconnectBackoffFactor: 2,
  enableHeartbeat: true
})

client.on('open', () => {
  console.log('Connected!')
  client.send('Hello server!')
  client.join('general')
})

client.on('message', (message) => {
  console.log('Received:', message)
})

client.on('error', (error) => {
  console.error('Error:', error.message)
})

client.connect()

⚙️ Configuration

Server Options

Option	Type	Default	Description
`port`	`number`	required	Server port
`token`	`string`	required	Authentication token
`enableEncryption`	`boolean`	`false`	Enable end-to-end encryption
`enableRooms`	`boolean`	`false`	Enable room/channel system
`enableHeartbeat`	`boolean`	`false`	Enable heartbeat monitoring
`heartbeatInterval`	`number`	`30000`	Heartbeat interval (ms)
`heartbeatTimeout`	`number`	`5000`	Heartbeat timeout (ms)
`enableCompression`	`boolean`	`false`	Enable message compression
`compressionThreshold`	`number`	`1024`	Compression threshold (bytes)
`ipWhitelist`	`string[]`	`[]`	Allowed IP addresses
`allowedOrigins`	`string[]`	`[]`	CORS allowed origins
`allowCredentials`	`boolean`	`false`	Allow CORS credentials
`maxConnections`	`number`	`1000`	Maximum connections
`enableRateLimit`	`boolean`	`true`	Enable rate limiting
`rateLimitMaxRequests`	`number`	`100`	Max requests per window
`rateLimitWindowMs`	`number`	`60000`	Rate limit window (ms)
`enableCodeExecution`	`boolean`	`false`	DANGER: Enable remote code execution
`codeExecutionTimeout`	`number`	`5000`	Code execution timeout (ms)
`codeExecutionMemoryLimit`	`number`	`134217728`	Code execution memory limit (bytes)

Client Options

Option	Type	Default	Description
`address`	`string`	required	Server address (host:port)
`token`	`string`	required	Authentication token
`enableEncryption`	`boolean`	`false`	Enable end-to-end encryption
`enableCompression`	`boolean`	`false`	Enable message compression
`reconnectInterval`	`number`	`5000`	Initial reconnection interval (ms)
`reconnectMaxInterval`	`number`	`60000`	Max reconnection interval (ms)
`reconnectBackoffFactor`	`number`	`2`	Exponential backoff factor
`enableHeartbeat`	`boolean`	`false`	Enable heartbeat monitoring
`heartbeatInterval`	`number`	`30000`	Heartbeat interval (ms)
`heartbeatTimeout`	`number`	`5000`	Heartbeat timeout (ms)
`secure`	`boolean`	`false`	Use WSS instead of WS
`name`	`string`	`undefined`	Client identifier

📚 API Documentation

📖 Full API documentation is available at: ./docs/index.html

Open docs/index.html in your browser for comprehensive API reference with TypeScript types, examples, and detailed descriptions.

Server API

Constructor

new Server(config: ServerConfig)

Methods

listen(callback?: () => void): void Start the WebSocket server and begin listening for connections.

server.listen(() => {
  console.log('Server started on port 8080');
});

broadcast(message: any, sender?: WebSocket): void Broadcast a message to all connected clients except the sender.

server.broadcast('Hello everyone!');
server.broadcast({ type: 'announcement', content: 'Server restart' });

to(roomName: string): RoomManager Get room manager for targeted broadcasting to a specific room.

server.to('general').broadcast('Message for general room only');

close(callback?: () => void): void Gracefully close the server and all connections.

server.close(() => {
  console.log('Server closed');
});

getConnectionCount(): number Get the current number of connected clients.

const count = server.getConnectionCount();
console.log(`Connected clients: ${count}`);

getAllRooms(): string[] Get list of all active room names.

const rooms = server.getAllRooms();
console.log('Active rooms:', rooms);

getRoomClients(roomName: string): Set<WebSocket> | undefined Get all clients in a specific room.

const clients = server.getRoomClients('general');
console.log(`Clients in general room: ${clients?.size}`);

Client API

Constructor

new Client(config: ClientConfig)

Methods

connect(): void Establish connection to the WebSocket server.

send(message: any): void Send a message to the server.

client.send('Hello world!');
client.send({ type: 'chat', content: 'Hi!' });
client.send({ sender: 'user1', data: 'Custom message' });

join(roomName: string): void Join a chat room for targeted messaging.

client.join('general');
client.join('support');

leave(roomName: string): void Leave a chat room.

client.leave('general');

close(): void Close the WebSocket connection gracefully.

isConnected(): boolean Check if the client is currently connected.

getReconnectAttempts(): number Get the current reconnection attempt count.

Events

open Connection established.

message Message received from server.

close Connection closed.

error Error occurred.

reconnecting Attempting to reconnect.

heartbeat Heartbeat received.

💡 Examples

Basic Connection

// server.ts
import { Server } from '@onurege3467/workspaces'

const server = new Server({
  port: 8080,
  token: 'secret'
})

server.listen()

// client.ts
import { Client } from '@onurege3467/workspaces'

const client = new Client({
  address: 'localhost:8080',
  token: 'secret'
})

client.connect()

Encrypted Chat

// server.ts
const server = new Server({
  port: 8080,
  token: 'secret',
  enableEncryption: true
})

// client.ts
const client = new Client({
  address: 'localhost:8080',
  token: 'secret',
  enableEncryption: true
})

client.on('message', (msg) => console.log('Secure:', msg))
client.connect()

Room-Based Messaging

// server.ts
const server = new Server({
  port: 8080,
  token: 'secret',
  enableRooms: true
})

// Broadcast to specific room
server.to('general').broadcast({ type: 'msg', content: 'Hello general!' })
server.to('support').broadcast({ type: 'msg', content: 'Hello support!' })

// client.ts
client.on('open', () => {
  client.join('general')
})

client.send({ type: 'msg', content: 'My message' })

Heartbeat & Reconnection

// client.ts
const client = new Client({
  address: 'localhost:8080',
  token: 'secret',
  enableHeartbeat: true,
  reconnectInterval: 5000,
  reconnectMaxInterval: 60000,
  reconnectBackoffFactor: 2
})

client.on('reconnecting', () => {
  console.log('Attempting to reconnect...');
})

client.on('heartbeat', () => {
  console.log('Connection is alive');
})

Rate Limiting

// server.ts
const server = new Server({
  port: 8080,
  token: 'secret',
  enableRateLimit: true,
  rateLimitMaxRequests: 50,  // 50 requests
  rateLimitWindowMs: 60000   // per minute
})

// Check remaining requests for an IP
const remaining = server.getRateLimitRemaining('192.168.1.1');
console.log(`Remaining requests: ${remaining}`);

🔒 Security Features

End-to-End Encryption

The package uses Diffie-Hellman key exchange for secure key generation and AES-256-GCM for message encryption with PBKDF2 key derivation:

Client generates public/private key pair using Diffie-Hellman
Server generates its own key pair
Both parties exchange public keys
Shared secret is computed using Diffie-Hellman
AES-256-GCM key is securely derived from shared secret using PBKDF2 with 100,000 iterations
All messages are encrypted with this key and include integrity protection

Rate Limiting

Built-in rate limiting protects against abuse:

Configurable request limits per IP address
Sliding window time periods
Automatic cleanup of old requests
Returns HTTP 429 when limits exceeded

Authentication & Authorization

Token Authentication: Required for all connections
IP Whitelisting: Restrict access to specific IP addresses
CORS Support: Configurable cross-origin policies

Input Validation

All cryptographic operations include comprehensive input validation
JSON parsing with proper error handling
Buffer length validation for encryption keys

🔧 Development

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Generate API documentation
npm run docs

📖 Troubleshooting

Common Issues

Connection Refused

Check if server is running on the correct port
Verify token matches between client and server
Check IP whitelist if enabled

Encryption Errors

Ensure both client and server have encryption enabled
Check network connectivity for key exchange
Verify compatible Node.js version

Rate Limiting

Check rate limit configuration
Monitor server logs for rate limit violations
Adjust limits based on your use case

Room Messages Not Received

Ensure rooms are enabled on server
Verify client has joined the correct room
Check room name spelling

Debug Mode

Enable debug logging:

// Server
const server = new Server({
  // ... config
  enableDebug: true
})

// Client
const client = new Client({
  // ... config
  enableDebug: true
})

Performance Tuning

For high-traffic applications:

const server = new Server({
  port: 8080,
  token: 'secret',
  maxConnections: 10000,
  enableCompression: true,
  compressionThreshold: 512, // Lower threshold
  enableRateLimit: true,
  rateLimitMaxRequests: 1000,
  rateLimitWindowMs: 60000
})

⚠️ DANGER: Remote Code Execution ⚠️

🚨 SECURITY WARNING: Remote code execution is EXTREMELY DANGEROUS and should NEVER be enabled in production environments unless you are in a completely trusted environment with proper security measures in place.

Why It's Dangerous:

Arbitrary Code Execution: Attackers can run any code on your server
System Compromise: File system access, network access, privilege escalation
Data Breach: Sensitive data theft, database manipulation
Denial of Service: Infinite loops, memory exhaustion, resource abuse
Backdoors: Malicious code can create persistent access

Configuration (Default: DISABLED)

const server = new Server({
  port: 8080,
  token: 'secret',
  enableCodeExecution: false, // ⚠️ KEEP THIS FALSE!
  codeExecutionTimeout: 5000, // 5 second timeout
  codeExecutionMemoryLimit: 128 * 1024 * 1024 // 128MB limit
});

Security Measures (If You Must Use It):

Only enable in isolated, air-gapped environments
Use VM2 sandboxing with strict timeouts
Implement comprehensive input validation
Block dangerous functions (require, fs, process, etc.)
Use rate limiting and IP whitelisting
Monitor execution logs continuously
Regular security audits

Example Usage (FOR EDUCATIONAL PURPOSES ONLY)

import { VM } from 'vm2';

// ⚠️ DANGER: Only for trusted environments!
const server = new Server({
  port: 8080,
  token: 'secret',
  enableCodeExecution: true, // ⚠️ NEVER DO THIS IN PRODUCTION!
  enableEncryption: true,
  enableRateLimit: true
});

// Handle code execution (with security checks)
server.on('connection', (client) => {
  client.on('message', async (message) => {
    if (message.type === 'execute_code') {
      try {
        // Security validation
        if (message.code.length > 10000) {
          throw new Error('Code too large');
        }

        // Dangerous patterns check
        const dangerous = /require|fs\.|process\.|eval\(/;
        if (dangerous.test(message.code)) {
          throw new Error('Dangerous code pattern detected');
        }

        // Execute in sandbox
        const vm = new VM({
          timeout: 5000,
          sandbox: {
            console: { log: (...args) => console.log('[VM]', ...args) },
            Math, Date, JSON, Array, Object
          }
        });

        const result = vm.run(message.code);

        client.send({
          type: 'execution_result',
          success: true,
          result: result
        });

      } catch (error: any) {
        client.send({
          type: 'execution_error',
          success: false,
          error: error.message
        });
      }
    }
  });
});

// Client (also dangerous if not trusted)
const client = new Client({
  address: 'localhost:8080',
  token: 'secret',
  enableEncryption: true
});

client.send({
  type: 'execute_code',
  code: `
    // Safe example: mathematical computation
    const fibonacci = (n) => n <= 1 ? n : fibonacci(n-1) + fibonacci(n-2);
    const result = {
      fibonacci_10: fibonacci(10),
      timestamp: Date.now(),
      calculation: Math.pow(2, 8) + Math.PI
    };
    result;
  `
});

🚫 NEVER Use This In Production

Web applications open to internet
Multi-user systems
Financial applications
Healthcare systems
Government systems
Any system handling sensitive data

Use only in: Isolated development environments, educational demos, trusted internal networks with proper security controls.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

ISC

Made with ❤️ by @onurege3467

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.vscode		.vscode
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
TEST_REPORT.md		TEST_REPORT.md
benchmark.js		benchmark.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json

License

onure9e/workspaces

Folders and files

Latest commit

History

Repository files navigation

@onurege3467/workspaces

📖 Table of Contents

✨ Features

📦 Installation

🚀 Quick Start

Server

Client

⚙️ Configuration

Server Options

Client Options

📚 API Documentation

Server API

Constructor

Methods

Client API

Constructor

Methods

Events

💡 Examples

Basic Connection

Encrypted Chat

Room-Based Messaging

Heartbeat & Reconnection

Rate Limiting

🔒 Security Features

End-to-End Encryption

Rate Limiting

Authentication & Authorization

Input Validation

🔧 Development

📖 Troubleshooting

Common Issues

Debug Mode

Performance Tuning

⚠️ DANGER: Remote Code Execution ⚠️

Why It's Dangerous:

Configuration (Default: DISABLED)

Security Measures (If You Must Use It):

Example Usage (FOR EDUCATIONAL PURPOSES ONLY)

🚫 NEVER Use This In Production

🤝 Contributing

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages