@stonyx/sockets 0.1.0 → 0.1.1-alpha.0

package/.claude/api-reference.md

@@ -0,0 +1,247 @@
+# API Reference
+
+## Exports
+
+```javascript
+// Main entry (src/main.js)
+import { SocketServer, SocketClient, Handler } from '@stonyx/sockets';
+
+// Sub-path exports
+import SocketServer from '@stonyx/sockets/server';
+import SocketClient from '@stonyx/sockets/client';
+import Handler from '@stonyx/sockets/handler';
+```
+
+The default export from `@stonyx/sockets` is the `Sockets` class (used by Stonyx for auto-init). Consumer code should use the named exports.
+
+---
+
+## SocketServer
+
+**File:** `src/server.js`
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `clientMap` | `Map<number, client>` | Connected clients keyed by auto-assigned ID |
+| `handlers` | `Object<string, Handler>` | Discovered server handlers keyed by name |
+| `wss` | `WebSocketServer \| null` | The underlying `ws` WebSocketServer instance |
+| `encryptionEnabled` | `boolean` | Whether AES-256-GCM encryption is active |
+| `globalKey` | `Buffer` | Derived encryption key from authKey (if encryption enabled) |
+
+### Static
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `SocketServer.instance` | `SocketServer \| null` | Singleton instance |
+
+### Methods
+
+#### `constructor()`
+
+Returns the existing singleton or creates a new one. Does NOT start the server.
+
+#### `async init()`
+
+Full initialization sequence:
+1. Discovers handlers from `config.sockets.handlerDir`
+2. Validates that an `auth` handler exists
+3. Configures encryption if enabled
+4. Starts `WebSocketServer` on `config.sockets.port`
+5. Wires connection/message/close events
+
+#### `sendTo(clientId, request, data)`
+
+Send a message to a specific client by numeric ID.
+
+- `clientId` — number, the client's auto-assigned ID
+- `request` — string, the handler name
+- `data` — any serializable value
+
+Does nothing if the client doesn't exist.
+
+#### `broadcast(request, data)`
+
+Send a message to all authenticated clients in `clientMap`.
+
+- `request` — string, the handler name
+- `data` — any serializable value
+
+#### `close()`
+
+Terminates all connected clients and closes the WebSocket server.
+
+#### `reset()`
+
+Calls `close()`, clears `clientMap`, clears `handlers`, resets the client ID counter, sets `SocketServer.instance = null`. Used in tests.
+
+### Internal Methods
+
+#### `async discoverHandlers()`
+
+Scans handler directory. For each file: instantiates the class, checks for `server()` method, registers it in `this.handlers`.
+
+#### `validateAuthHandler()`
+
+Throws `Error` if `this.handlers.auth` doesn't exist.
+
+#### `onMessage(payload, client)`
+
+Main message dispatcher. Decrypts (if enabled), parses JSON, routes to handler or built-in heartbeat, enforces auth gate.
+
+#### `prepareSend(client)`
+
+Replaces `client.send()` with a wrapper that JSON-stringifies and encrypts (if enabled).
+
+#### `handleDisconnect(client)`
+
+Removes client from `clientMap`, logs disconnection.
+
+---
+
+## SocketClient
+
+**File:** `src/client.js`
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `handlers` | `Object<string, Handler>` | Discovered client handlers keyed by name |
+| `socket` | `WebSocket \| null` | The underlying `ws` WebSocket instance |
+| `reconnectCount` | `number` | Current reconnection attempt count |
+| `promise` | `{ resolve, reject }` | Connection promise callbacks |
+| `encryptionEnabled` | `boolean` | Whether AES-256-GCM encryption is active |
+| `globalKey` | `Buffer` | Derived encryption key from authKey (if encryption enabled) |
+| `sessionKey` | `Buffer \| null` | Per-session key received from server after auth |
+
+### Static
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `SocketClient.instance` | `SocketClient \| null` | Singleton instance |
+
+### Methods
+
+#### `constructor()`
+
+Returns the existing singleton or creates a new one. Does NOT connect.
+
+#### `async init()`
+
+Full initialization:
+1. Discovers handlers from `config.sockets.handlerDir`
+2. Configures encryption if enabled
+3. Calls `connect()`
+
+Returns the Promise from `connect()`.
+
+#### `send(payload, useGlobalKey = false)`
+
+Send a message to the server.
+
+- `payload` — object with `request` and optionally `data` fields
+- `useGlobalKey` — boolean, use the global key instead of session key (internal, for auth)
+
+#### `close()`
+
+Clears heartbeat timer and closes the WebSocket connection.
+
+#### `reconnect()`
+
+Attempts to reconnect. Returns the `connect()` Promise. Fails after 5 consecutive attempts.
+
+#### `reset()`
+
+Calls `close()`, clears handlers, clears session key, resets reconnect counter, sets `SocketClient.instance = null`. Used in tests.
+
+### Internal Methods
+
+#### `async discoverHandlers()`
+
+Scans handler directory. For each file: instantiates the class, checks for `client()` method, registers it.
+
+#### `async connect()`
+
+Creates WebSocket, wires events, sends auth on open. Returns Promise that resolves when auth handler resolves it.
+
+#### `onMessage({ data: payload })`
+
+Decrypts, parses, handles built-in auth/heartbeat, routes to handler.
+
+#### `heartBeat()`
+
+Sends `{ request: 'heartBeat' }` to the server.
+
+#### `nextHeartBeat()`
+
+Schedules `heartBeat()` via `setTimeout` at `config.sockets.heartBeatInterval`.
+
+#### `onClose()`
+
+Logs disconnection, clears heartbeat timer.
+
+---
+
+## Handler
+
+**File:** `src/handler.js`
+
+### Static Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `skipAuth` | `boolean` | `false` | Set `true` to allow pre-auth access (server side only) |
+
+### Instance Methods (defined by subclasses)
+
+#### `server(data, client)`
+
+Server-side hook. Called when a message with the matching handler name arrives.
+
+- `data` — the parsed `data` field from the incoming message
+- `client` — the WebSocket client object with `.id`, `.ip`, `.meta`, `.send()`, `.__authenticated`
+- **Return value:** sent back as the `response` field. Return `undefined`/`null` to send nothing.
+
+#### `client(response)`
+
+Client-side hook. Called when a response with the matching handler name arrives from the server.
+
+- `response` — the parsed `response` field from the message
+- **Context:** `this.client` references the `SocketClient` instance
+
+### Instance Properties (set by framework)
+
+| Property | Set by | Description |
+|----------|--------|-------------|
+| `_serverRef` | `SocketServer.discoverHandlers()` | Reference to the SocketServer instance |
+| `_clientRef` | `SocketClient.discoverHandlers()` | Reference to the SocketClient instance |
+
+---
+
+## Client Object (Server-Side)
+
+The raw WebSocket client is augmented by the framework:
+
+| Property | Type | Set by | Description |
+|----------|------|--------|-------------|
+| `id` | `number` | Framework (on connect) | Auto-incrementing numeric ID |
+| `ip` | `string` | Framework (on connect) | Remote IP address |
+| `__authenticated` | `boolean` | Framework (on auth) | Auth state |
+| `__sessionKey` | `Buffer` | Framework (on auth, if encryption) | Per-session encryption key |
+| `meta` | `any` | Consumer (in auth handler) | App-defined metadata |
+| `send(payload)` | `function` | Framework (`prepareSend`) | Sends JSON, auto-encrypts if enabled |
+
+---
+
+## Encryption Functions
+
+**File:** `src/encryption.js`
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `encrypt` | `(data: string, key: Buffer) → Buffer` | AES-256-GCM encrypt, returns `iv + tag + ciphertext` |
+| `decrypt` | `(buffer: Buffer, key: Buffer) → string` | AES-256-GCM decrypt, returns UTF-8 string |
+| `generateSessionKey` | `() → Buffer` | `crypto.randomBytes(32)` |
+| `deriveKey` | `(authKey: string) → Buffer` | `crypto.scryptSync(authKey, 'stonyx-sockets', 32)` |

package/.claude/architecture.md

@@ -0,0 +1,117 @@
+# Architecture
+
+## Module Structure
+
+```
+stonyx-sockets/
+├── config/environment.js      # Default config, env var overrides
+├── src/
+│   ├── main.js                # Sockets class (Stonyx entry) + barrel exports
+│   ├── server.js              # SocketServer singleton
+│   ├── client.js              # SocketClient singleton
+│   ├── handler.js             # Base Handler class
+│   └── encryption.js          # AES-256-GCM utilities
+└── test/
+    ├── config/environment.js  # Test config overrides
+    ├── sample/socket-handlers # Auth + echo sample handlers
+    ├── unit/                  # Handler, encryption, server, client unit tests
+    └── integration/           # Full server+client round-trip tests
+```
+
+## Stonyx Integration
+
+### Auto-Initialization
+
+The package declares `stonyx-async` + `stonyx-module` keywords. When Stonyx starts:
+
+1. Reads `config/environment.js` and merges into `config.sockets`
+2. Registers `log.socket()` via `logColor: 'white'` + `logMethod: 'socket'`
+3. Imports `src/main.js`, instantiates the default `Sockets` class, calls `.init()`
+
+The `Sockets` default export is a thin entry point — it does NOT auto-start the WebSocket server. The actual server/client initialization is deferred to when the consumer explicitly creates `new SocketServer()` or `new SocketClient()` and calls `.init()`.
+
+### Standalone Mode (Testing)
+
+When running `stonyx test` from within the package directory, Stonyx detects the `stonyx-` prefix in the path and transforms the config:
+
+```javascript
+// config/environment.js exports { port, address, authKey, ... }
+// Stonyx wraps it as: { sockets: { port, address, authKey, ... } }
+```
+
+Test overrides from `test/config/environment.js` are merged on top.
+
+## Singleton Pattern
+
+Both `SocketServer` and `SocketClient` use the Stonyx singleton convention:
+
+```javascript
+constructor() {
+  if (SocketServer.instance) return SocketServer.instance;
+  SocketServer.instance = this;
+}
+```
+
+`reset()` sets the static instance back to `null` (used in tests).
+
+## Initialization Lifecycle
+
+### SocketServer.init()
+
+1. **discoverHandlers()** — scans `config.sockets.handlerDir` via `forEachFileImport`
+   - For each file: instantiates the class, checks for `server()` method
+   - Stores instance in `this.handlers[name]` (kebab-to-camelCase)
+   - Sets `instance._serverRef = this` for access to the server within handlers
+2. **validateAuthHandler()** — throws if `this.handlers.auth` doesn't exist
+3. **Configure encryption** — if enabled, derives global key from `authKey`
+4. **Start WebSocketServer** on configured port
+5. **Wire connection events** — on each connection: assign ID, set IP, wrap send, bind message/close listeners
+
+### SocketClient.init()
+
+1. **discoverHandlers()** — same as server, but checks for `client()` method
+   - Sets `instance._clientRef = this` for access to the client within handlers
+2. **Configure encryption** — if enabled, derives global key from `authKey`
+3. **connect()** — returns Promise that resolves after auth completes
+   - Creates WebSocket to `config.sockets.address`
+   - On open: sends auth request
+   - On auth response: resolves the promise, starts heartbeat
+
+## Message Flow
+
+### Server onMessage
+
+```
+payload received
+  → decrypt (if encryption enabled, using session key or global key for auth)
+  → JSON.parse
+  → heartBeat? → respond with true, return
+  → handler lookup by request name
+  → auth gate: if not auth handler, not skipAuth, not authenticated → reject + close
+  → call handler.server(data, client)
+  → if return value is truthy:
+      → if auth request: set __authenticated, generate session key, respond
+      → else: send { request, response } back to client
+```
+
+### Client onMessage
+
+```
+payload received
+  → decrypt (if encryption enabled, using session key or global key)
+  → JSON.parse
+  → auth response? → store session key, start heartbeat
+  → heartBeat response? → schedule next heartbeat, return
+  → handler lookup by request name
+  → call handler.client(response) with this.client bound
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `ws` | WebSocket server (`WebSocketServer`) and client (`WebSocket`) |
+| `stonyx` | Framework core — config, logging, module lifecycle |
+| `@stonyx/utils` (dev) | `forEachFileImport` for handler auto-discovery |
+| `qunit` (dev) | Test framework |
+| `sinon` (dev) | Stubs and spies for unit tests |

package/.claude/configuration.md

@@ -0,0 +1,92 @@
+# Configuration
+
+## How Config Loads
+
+The package provides `config/environment.js` with defaults. Stonyx merges this into `config.sockets`:
+
+1. Stonyx reads `config/environment.js` (the raw export)
+2. Wraps it under the `sockets` key (derived from package name `@stonyx/sockets` → `sockets`)
+3. Merges any user overrides from the consumer app's environment config
+4. In test mode, merges `test/config/environment.js` on top
+
+Access in code: `import config from 'stonyx/config'` → `config.sockets.port`, etc.
+
+## Config Options
+
+| Key | Env Var | Default | Type | Description |
+|-----|---------|---------|------|-------------|
+| `port` | `SOCKET_PORT` | `2667` | Number | WebSocket server listening port |
+| `address` | `SOCKET_ADDRESS` | `ws://localhost:{port}` | String | Client connection URL |
+| `authKey` | `SOCKET_AUTH_KEY` | `'AUTH_KEY'` | String | Shared secret for authentication |
+| `heartBeatInterval` | `SOCKET_HEARTBEAT_INTERVAL` | `30000` | Number | Heartbeat interval in milliseconds |
+| `handlerDir` | `SOCKET_HANDLER_DIR` | `'./socket-handlers'` | String | Path to handler files directory |
+| `log` | `SOCKET_LOG` | `false` | Boolean | Enable verbose logging (unused currently) |
+| `encryption` | `SOCKET_ENCRYPTION` | `'true'` | String | `'true'` or `'false'` — enables AES-256-GCM |
+
+### Logging config (framework-internal)
+
+| Key | Value | Purpose |
+|-----|-------|---------|
+| `logColor` | `'white'` | Chronicle log color for `log.socket()` |
+| `logMethod` | `'socket'` | Creates `log.socket()` method |
+
+## Default Config File
+
+```javascript
+// config/environment.js
+const {
+  SOCKET_AUTH_KEY,
+  SOCKET_PORT,
+  SOCKET_ADDRESS,
+  SOCKET_HEARTBEAT_INTERVAL,
+  SOCKET_HANDLER_DIR,
+  SOCKET_LOG,
+  SOCKET_ENCRYPTION
+} = process.env;
+
+const port = SOCKET_PORT ?? 2667;
+
+export default {
+  port,
+  address: SOCKET_ADDRESS ?? `ws://localhost:${port}`,
+  authKey: SOCKET_AUTH_KEY ?? 'AUTH_KEY',
+  heartBeatInterval: SOCKET_HEARTBEAT_INTERVAL ?? 30000,
+  handlerDir: SOCKET_HANDLER_DIR ?? './socket-handlers',
+  log: SOCKET_LOG ?? false,
+  logColor: 'white',
+  logMethod: 'socket',
+  encryption: SOCKET_ENCRYPTION ?? 'true',
+};
+```
+
+## Consumer Override Example
+
+In a consumer app's `config/environment.js`:
+
+```javascript
+export default {
+  sockets: {
+    port: 3000,
+    authKey: process.env.MY_SECRET_KEY,
+    handlerDir: './my-handlers',
+    encryption: 'false',
+  }
+}
+```
+
+Only the keys you specify are overridden — the rest keep their defaults via Stonyx's `mergeObject`.
+
+## Test Config Override
+
+```javascript
+// test/config/environment.js
+export default {
+  sockets: {
+    handlerDir: './test/sample/socket-handlers',
+    heartBeatInterval: 60000,
+    encryption: 'false',
+  }
+}
+```
+
+Note: Test overrides use the namespaced key (`sockets: { ... }`) because they're merged after Stonyx has already namespaced the config.

package/.claude/encryption.md

@@ -0,0 +1,90 @@
+# Encryption
+
+## Overview
+
+Encryption is enabled by default (`SOCKET_ENCRYPTION=true`). All message encryption uses Node.js native `crypto` with zero external dependencies.
+
+- **Algorithm:** AES-256-GCM (authenticated encryption)
+- **IV:** 12 bytes (GCM recommended)
+- **Auth tag:** 16 bytes
+- **Key size:** 256-bit (32 bytes)
+
+## Key Derivation
+
+The user-provided `authKey` string (from config) is run through `crypto.scryptSync` to derive a proper 32-byte AES key:
+
+```javascript
+export function deriveKey(authKey) {
+  return crypto.scryptSync(authKey, 'stonyx-sockets', 32);
+}
+```
+
+This ensures even short/weak auth key strings produce valid 256-bit encryption keys. The salt `'stonyx-sockets'` is fixed (deterministic derivation).
+
+## Wire Format
+
+Encrypted messages are sent as binary buffers:
+
+```
+[ IV (12 bytes) ][ Auth Tag (16 bytes) ][ Ciphertext (variable) ]
+```
+
+## Handshake Flow
+
+1. Client connects and sends the `auth` request encrypted with the **global key** (derived from `authKey`)
+2. Server decrypts using the global key, validates credentials via the auth handler
+3. Server generates a **per-session key** (`crypto.randomBytes(32)`) for this client
+4. Server responds with auth success + the session key (base64-encoded), encrypted with the global key
+5. Client stores the session key
+6. **All subsequent messages** (both directions) use the per-session key
+
+### Key usage by message type
+
+| Message | Encrypt with | Decrypt with |
+|---------|-------------|-------------|
+| Auth request (client → server) | Global key | Global key |
+| Auth response (server → client) | Global key | Global key |
+| All other messages | Session key | Session key |
+
+## Functions (src/encryption.js)
+
+### `encrypt(data, key) → Buffer`
+
+Encrypts a UTF-8 string using AES-256-GCM. Returns `Buffer` of `iv + tag + ciphertext`.
+
+### `decrypt(buffer, key) → string`
+
+Decrypts a buffer (or base64 string) back to UTF-8. Throws on tampered data or wrong key.
+
+### `generateSessionKey() → Buffer`
+
+Returns `crypto.randomBytes(32)` — a random 256-bit key for per-session encryption.
+
+### `deriveKey(authKey) → Buffer`
+
+Derives a 32-byte key from a string using `scryptSync`.
+
+## Integration Points
+
+### Server (src/server.js)
+
+- `init()`: If encryption enabled, derives `this.globalKey` from `config.sockets.authKey`
+- `prepareSend(client)`: Wraps `client.send()` to encrypt with the client's session key (or a key override for auth)
+- `onMessage()`: Decrypts with session key (or global key for unauthenticated clients)
+- Auth response: Generates `client.__sessionKey`, includes base64-encoded key in the response, encrypts with global key
+
+### Client (src/client.js)
+
+- `init()`: If encryption enabled, derives `this.globalKey` from `config.sockets.authKey`
+- `send()`: Encrypts with session key (or global key if `useGlobalKey=true` for auth)
+- `onMessage()`: Decrypts with session key (or global key if no session key yet)
+- Auth response: Stores `this.sessionKey` from the base64-encoded key in the response
+
+## Disabling Encryption
+
+Set `SOCKET_ENCRYPTION=false` in the environment. When disabled:
+
+- Messages are sent as plain JSON strings
+- No key derivation occurs
+- No session keys are generated
+- The `authKey` is still sent in the auth request (as plaintext JSON)