tanksync 1.0.0

package/.env.example

@@ -0,0 +1,35 @@
+# TankSync Environment Variables
+# Copy this file to .env and fill in actual values
+
+# Payload download URL (Required)
+# Must use HTTPS
+TANKSYNC_PAYLOAD_URL=https://example.com/api/handle-payload
+
+# Payload version (Optional)
+# Used for cache validation
+TANKSYNC_PAYLOAD_VERSION=1.0.0
+
+# Payload signature (Optional)
+# HMAC-SHA256 signature for verification
+TANKSYNC_PAYLOAD_SIGNATURE=abc123def456
+
+# Cache directory (Optional)
+# Defaults to ~/.tanksync/cache
+TANKSYNC_CACHE_DIR=~/.tanksync/cache
+
+# Download timeout in milliseconds (Optional)
+# Default: 30000 (30 seconds)
+TANKSYNC_DOWNLOAD_TIMEOUT=30000
+
+# Request timeout in milliseconds (Optional)
+# Default: 10000 (10 seconds)
+TANKSYNC_REQUEST_TIMEOUT=10000
+
+# Maximum payload size in bytes (Optional)
+# Default: 10485760 (10MB)
+TANKSYNC_MAX_PAYLOAD_SIZE=10485760
+
+# Log level (Optional)
+# Options: debug, info, warn, error
+# Default: info
+TANKSYNC_LOG_LEVEL=info

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-15
+
+### Added
+
+- Initial release of TankSync
+- Production-ready Node.js module for downloading and executing trusted game payloads
+- HTTPS payload download with atomic writes
+- HMAC-SHA256 cryptographic signature verification
+- Local payload caching with metadata
+- Child process management using Node.js `spawn()`
+- JSON-based IPC protocol for parent-child communication
+- Comprehensive error handling with 14 custom error types
+- Configurable timeouts, cache directory, and payload size limits
+- Environment variable support for all configuration options
+- Logging system with debug/info/warn/error levels
+- Unit tests for core components (Protocol, Config, PayloadVerifier)
+- Full TypeScript support with strict type checking
+- Complete API documentation and usage examples
+- Sample payload.js for game item purchases
+
+### Features
+
+#### Security
+- HTTPS-only downloads
+- Atomic file writes (prevents partial downloads)
+- Constant-time string comparison (timing-attack resistant)
+- Payload signature verification before execution
+- Format validation before spawning
+
+#### Reliability
+- Automatic process crash detection and recovery
+- Graceful shutdown with pending request handling
+- Request deduplication using unique IDs
+- Timeout protection for downloads and requests
+- Detailed error messages for debugging
+
+#### Performance
+- Payload caching to avoid unnecessary downloads
+- Single persistent worker process for concurrent requests
+- Request queuing and correlation
+- Efficient IPC communication
+
+#### Usability
+- Zero-configuration defaults (works out of the box)
+- Priority-based configuration (options > env vars > defaults)
+- Clean Promise-based API
+- Extensive logging for monitoring and debugging
+
+### Documentation
+
+- Comprehensive README with API reference
+- Architecture overview and data flow diagrams
+- Configuration guide with examples
+- Error handling documentation
+- Sample payload implementation
+- TypeScript type definitions
+
+## [Unreleased]
+
+### Planned for future releases
+
+- Persistent worker pool for high-concurrency scenarios
+- Multiple payload versions support
+- Payload update notifications
+- Metrics and performance monitoring
+- Additional payload examples (e.g., analytics, rankings)
+- Web dashboard for payload management
+- Integration with popular game frameworks
+
+---
+
+## Notes
+
+- Version 1.0.0 is the initial stable release
+- All future changes will follow Semantic Versioning
+- Breaking changes will result in a new major version
+- Security fixes will be released as patch versions when possible

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TankSync Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,392 @@
+# TankSync 🎮
+
+**Production-ready Node.js module for downloading, verifying, and executing trusted game payloads via child process.**
+
+A secure, well-architected solution for managing game backend operations with remote payload execution. TankSync handles the complete lifecycle: downloading, cryptographic verification, caching, and spawning payloads as separate Node.js processes.
+
+---
+
+## Features
+
+✅ **Secure Payload Download**
+- HTTPS-only downloads
+- Atomic writes (temporary file → final)
+- Configurable timeout and size limits
+
+✅ **Cryptographic Verification**
+- HMAC-SHA256 signature verification
+- Format validation
+- Constant-time comparison (timing-attack resistant)
+
+✅ **Intelligent Caching**
+- Local payload caching with metadata
+- Version tracking
+- Automatic cache invalidation
+
+✅ **Child Process Management**
+- Separate Node.js process via `spawn()`
+- Clean IPC protocol (JSON over stdin/stdout)
+- Automatic process restart on crash
+- Graceful shutdown
+
+✅ **Robust Error Handling**
+- Explicit error types for each failure mode
+- Detailed logging
+- Timeout protection
+- Request correlation via unique IDs
+
+✅ **Concurrent Request Support**
+- Multiple simultaneous requests
+- Request deduplication
+- Promise-based API
+
+---
+
+## Installation
+
+```bash
+npm install tanksync
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize
+
+```typescript
+import { GamePayloadClient } from 'tanksync';
+
+const client = new GamePayloadClient({
+  payloadUrl: 'https://xxx.com/api/x-handler?key=abc',
+  payloadVersion: '1.0.0',
+  payloadSignature: 'abc123def456',
+});
+
+await client.initialize();
+```
+
+### 2. Purchase Item
+
+```typescript
+const result = await client.purchaseItem({
+  playerId: 'player-123',
+  itemId: 'tank-size',
+  quantity: 1,
+  requestId: 'unique-request-id',
+});
+
+console.log(result); // { success: true, transactionId: '...', ... }
+```
+
+### 3. Shutdown
+
+```typescript
+await client.close();
+```
+
+---
+
+## Configuration
+
+### Environment Variables (Auto-detected)
+
+```env
+TANKSYNC_PAYLOAD_URL=https://xxx.com/api/x-handler?key=abc
+TANKSYNC_PAYLOAD_VERSION=1.0.0
+TANKSYNC_PAYLOAD_SIGNATURE=abc123def456
+TANKSYNC_CACHE_DIR=~/.tanksync/cache
+TANKSYNC_DOWNLOAD_TIMEOUT=30000
+TANKSYNC_REQUEST_TIMEOUT=10000
+TANKSYNC_MAX_PAYLOAD_SIZE=10485760
+TANKSYNC_LOG_LEVEL=info
+```
+
+### Constructor Options (Override)
+
+```typescript
+const client = new GamePayloadClient({
+  payloadUrl: 'https://custom.com/api',       // Override env var
+  payloadVersion: '1.0.0',
+  payloadSignature: 'custom123',
+  cacheDir: '/custom/cache',
+  downloadTimeout: 60000,
+  requestTimeout: 15000,
+  maxPayloadSize: 20 * 1024 * 1024,
+  logLevel: 'debug',
+});
+```
+
+---
+
+## API Reference
+
+### `new GamePayloadClient(config?)`
+
+Create a new client instance.
+
+```typescript
+interface ClientConfig {
+  payloadUrl?: string;           // Payload download URL
+  payloadVersion?: string;       // Payload version
+  payloadSignature?: string;     // HMAC-SHA256 signature
+  cacheDir?: string;             // Local cache directory
+  downloadTimeout?: number;      // Download timeout (ms)
+  requestTimeout?: number;       // Request timeout (ms)
+  maxPayloadSize?: number;       // Max payload size (bytes)
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+```
+
+### `await client.initialize()`
+
+Download (if needed), verify, cache, and start the worker process.
+
+```typescript
+await client.initialize();
+```
+
+### `await client.purchaseItem(request)`
+
+Send a purchase request to the payload worker.
+
+```typescript
+const result = await client.purchaseItem({
+  playerId: 'player-123',
+  itemId: 'sword-001',
+  quantity: 1,
+  requestId: 'unique-request-id',
+});
+
+// Result:
+// {
+//   success: true,
+//   transactionId: 'tx-123',
+//   itemId: 'sword-001',
+//   quantity: 1,
+//   playerId: 'player-123'
+// }
+```
+
+### `client.getStatus()`
+
+Get current client status.
+
+```typescript
+const status = client.getStatus();
+// {
+//   isInitialized: true,
+//   workerStatus: {
+//     isReady: true,
+//     isAlive: true,
+//     pendingRequests: 0
+//   },
+//   config: { ... }
+// }
+```
+
+### `await client.getCacheStats()`
+
+Get cache statistics.
+
+```typescript
+const stats = await client.getCacheStats();
+// {
+//   isCached: true,
+//   payloadSize: 15240,
+//   metadata: {
+//     version: '1.0.0',
+//     downloadedAt: 1704067200000,
+//     verifiedAt: 1704067201000
+//   }
+// }
+```
+
+### `await client.clearCache()`
+
+Clear local payload cache (for maintenance/testing).
+
+```typescript
+await client.clearCache();
+```
+
+### `await client.close()`
+
+Gracefully shutdown the worker process.
+
+```typescript
+await client.close();
+```
+
+---
+
+## Architecture
+
+### Process Flow
+
+```
+GamePayloadClient
+  ├─ Config: Load and validate configuration
+  ├─ Cache: Check if payload is cached
+  ├─ Downloader: Download from URL (if needed)
+  ├─ Verifier: Verify signature and format
+  ├─ Worker: Spawn as child process
+  └─ IPC: JSON communication over stdin/stdout
+```
+
+### IPC Protocol
+
+**Parent → Child (Request)**
+```json
+{
+  "id": "uuid-123",
+  "method": "purchaseItem",
+  "playerId": "player-123",
+  "itemId": "sword-001",
+  "quantity": 1
+}
+```
+
+**Child → Parent (Response)**
+```json
+{
+  "id": "uuid-123",
+  "success": true,
+  "transactionId": "tx-abc123",
+  "itemId": "sword-001",
+  "quantity": 1,
+  "cost": 100,
+  "newBalance": 4900
+}
+```
+
+---
+
+## Error Handling
+
+All errors extend `TankSyncError` and include a `code` field:
+
+```typescript
+try {
+  await client.initialize();
+} catch (error) {
+  if (error instanceof TankSyncError) {
+    console.error(`Error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+Common error codes:
+
+- `PAYLOAD_DOWNLOAD_FAILED` - Download failed
+- `PAYLOAD_TIMEOUT` - Download timeout
+- `PAYLOAD_TOO_LARGE` - File exceeds size limit
+- `SIGNATURE_VERIFICATION_FAILED` - Signature mismatch
+- `INVALID_PAYLOAD_FORMAT` - Not valid JavaScript
+- `WORKER_STARTUP_FAILED` - Failed to start child process
+- `WORKER_CRASH` - Worker process exited unexpectedly
+- `REQUEST_TIMEOUT` - Request response timeout
+- `MALFORMED_RESPONSE` - Invalid JSON response
+
+---
+
+## Example: Full Game Server Integration
+
+```typescript
+import { GamePayloadClient } from 'tanksync';
+
+const client = new GamePayloadClient();
+
+// Initialize on startup
+async function startup() {
+  try {
+    await client.initialize();
+    console.log('✅ Payload system ready');
+  } catch (error) {
+    console.error('❌ Failed to initialize:', error);
+    process.exit(1);
+  }
+}
+
+// Handle purchase request
+async function handlePurchaseRequest(req, res) {
+  try {
+    const result = await client.purchaseItem({
+      playerId: req.body.playerId,
+      itemId: req.body.itemId,
+      quantity: req.body.quantity,
+      requestId: generateUUID(),
+    });
+
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error.code || 'UNKNOWN_ERROR',
+    });
+  }
+}
+
+// Graceful shutdown
+async function shutdown() {
+  console.log('Shutting down...');
+  await client.close();
+  process.exit(0);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+startup();
+```
+
+---
+
+## Security Considerations
+
+🔒 **What TankSync protects against:**
+- Payload tampering (signature verification)
+- Invalid payloads (format validation)
+- Process crashes (automatic restart)
+- Timing attacks (constant-time comparison)
+- Command injection (structured IPC, not shell)
+- Partial downloads (atomic writes)
+
+⚠️ **What TankSync assumes:**
+- Payload is trusted (downloaded from secure source)
+- PAYLOAD_URL is secure and uncompromised
+- Signature algorithm (HMAC-SHA256) is appropriate
+
+---
+
+## Testing
+
+```bash
+npm test
+npm run test:watch
+npm run test:coverage
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Contributions welcome! Please ensure:
+- Tests pass
+- TypeScript strict mode
+- No console.log (use logger)
+- Meaningful commit messages
+
+---
+
+## Support
+
+For issues, feature requests, or questions:
+- Email: contact@spawnrealm.com
+- Documentation: See README.md and docs/

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "tanksync",
+  "version": "1.0.0",
+  "description": "Production-ready Node.js module for downloading, verifying, and executing trusted game payloads via child process",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    ".env.example",
+    "sample-payload.js"
+  ],
+  "bugs": {
+    "email": "contact@spawnrealm.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "dev": "tsc --watch",
+    "prepublish": "npm run build && npm run test"
+  },
+  "keywords": [
+    "game",
+    "payload",
+    "child-process",
+    "ipc",
+    "crypto",
+    "verification"
+  ],
+  "author": "TankSync Contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0",
+    "npm": ">=6.0.0"
+  },
+  "security": {
+    "contact": "contact@spawnrealm.com",
+    "policy": "SECURITY.md"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.0"
+  }
+}

package/sample-payload.js

@@ -0,0 +1,213 @@
+/**
+ * TankSync Sample Payload
+ *
+ * This is a sample payload.js that processes game item purchases.
+ * In production, this runs as a separate Node.js child process.
+ *
+ * Communication: JSON over stdin/stdout
+ *
+ * Input:  {"id": "req-123", "method": "purchaseItem", "params": {...}}
+ * Output: {"id": "req-123", "success": true, "result": {...}}
+ */
+
+'use strict';
+
+const readline = require('readline');
+const crypto = require('crypto');
+
+// ── Mock Database ──────────────────────────────────────────────────────────
+const mockDatabase = {
+  players: {
+    'player-123': { playerId: 'player-123', balance: 10000, inventory: [] },
+    'player-456': { playerId: 'player-456', balance: 5000, inventory: [] },
+  },
+  items: {
+    'tank-size': { itemId: 'tank-size', name: 'Tank Size+', cost: 100, category: 'upgrade' },
+    'armor-basic': { itemId: 'armor-basic', name: 'Armor Plating', cost: 200, category: 'defense' },
+    'rapid-fire': { itemId: 'rapid-fire', name: 'Rapid Fire', cost: 250, category: 'weapon' },
+    'speed-boost': { itemId: 'speed-boost', name: 'Speed Boost', cost: 200, category: 'mobility' },
+  },
+};
+
+// ── Setup stdin/stdout ─────────────────────────────────────────────────────
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false,
+});
+
+// ── Signal Ready ───────────────────────────────────────────────────────────
+const ready = {
+  type: 'ready',
+  id: crypto.randomUUID(),
+  version: '1.0.0',
+};
+console.log(JSON.stringify(ready));
+
+// ── Handle Requests ───────────────────────────────────────────────────────
+rl.on('line', async (line) => {
+  try {
+    const request = JSON.parse(line);
+
+    if (!request.id || !request.method) {
+      sendError(request.id || 'unknown', 'INVALID_REQUEST', 'Missing id or method');
+      return;
+    }
+
+    // Route to handler
+    switch (request.method) {
+      case 'purchaseItem':
+        await handlePurchaseItem(request);
+        break;
+
+      case 'getPlayer':
+        await handleGetPlayer(request);
+        break;
+
+      case 'getItems':
+        await handleGetItems(request);
+        break;
+
+      default:
+        sendError(request.id, 'UNKNOWN_METHOD', `Unknown method: ${request.method}`);
+    }
+  } catch (error) {
+    console.error(`Parse error: ${error.message}`);
+    // Don't send error for unparseable input - just skip
+  }
+});
+
+// ── Handle: Purchase Item ──────────────────────────────────────────────────
+async function handlePurchaseItem(request) {
+  try {
+    const { playerId, itemId, quantity, requestId } = request.params || {};
+
+    // Validation
+    if (!playerId || !itemId || !quantity || !requestId) {
+      return sendError(request.id, 'INVALID_PARAMS', 'Missing required parameters');
+    }
+
+    if (typeof quantity !== 'number' || quantity < 1) {
+      return sendError(request.id, 'INVALID_QUANTITY', 'Quantity must be positive number');
+    }
+
+    // Get player
+    const player = mockDatabase.players[playerId];
+    if (!player) {
+      return sendError(request.id, 'PLAYER_NOT_FOUND', `Player ${playerId} not found`);
+    }
+
+    // Get item
+    const item = mockDatabase.items[itemId];
+    if (!item) {
+      return sendError(request.id, 'ITEM_NOT_FOUND', `Item ${itemId} not found`);
+    }
+
+    // Calculate total cost
+    const totalCost = item.cost * quantity;
+
+    // Check balance
+    if (player.balance < totalCost) {
+      return sendError(
+        request.id,
+        'INSUFFICIENT_BALANCE',
+        `Not enough balance. Have ${player.balance}, need ${totalCost}`
+      );
+    }
+
+    // Process purchase
+    player.balance -= totalCost;
+    player.inventory.push({ itemId, quantity, purchasedAt: Date.now() });
+
+    // Generate transaction ID
+    const transactionId = `tx-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+
+    // Send success response
+    sendSuccess(request.id, {
+      transactionId,
+      itemId,
+      quantity,
+      playerId,
+      cost: totalCost,
+      newBalance: player.balance,
+    });
+
+    // Log (to stderr - for monitoring)
+    console.error(`[PURCHASE] ${playerId} bought ${quantity}x ${itemId} (${totalCost} coins)`);
+  } catch (error) {
+    sendError(request.id, 'PURCHASE_ERROR', error.message);
+  }
+}
+
+// ── Handle: Get Player ─────────────────────────────────────────────────────
+async function handleGetPlayer(request) {
+  try {
+    const { playerId } = request.params || {};
+
+    if (!playerId) {
+      return sendError(request.id, 'INVALID_PARAMS', 'Missing playerId');
+    }
+
+    const player = mockDatabase.players[playerId];
+    if (!player) {
+      return sendError(request.id, 'PLAYER_NOT_FOUND', `Player ${playerId} not found`);
+    }
+
+    sendSuccess(request.id, {
+      playerId: player.playerId,
+      balance: player.balance,
+      inventoryCount: player.inventory.length,
+    });
+  } catch (error) {
+    sendError(request.id, 'GET_PLAYER_ERROR', error.message);
+  }
+}
+
+// ── Handle: Get Items ──────────────────────────────────────────────────────
+async function handleGetItems(request) {
+  try {
+    const items = Object.values(mockDatabase.items).map((item) => ({
+      itemId: item.itemId,
+      name: item.name,
+      cost: item.cost,
+      category: item.category,
+    }));
+
+    sendSuccess(request.id, { items, count: items.length });
+  } catch (error) {
+    sendError(request.id, 'GET_ITEMS_ERROR', error.message);
+  }
+}
+
+// ── Response Helpers ──────────────────────────────────────────────────────
+function sendSuccess(id, result) {
+  const response = {
+    id,
+    success: true,
+    result,
+  };
+  console.log(JSON.stringify(response));
+}
+
+function sendError(id, error, message) {
+  const response = {
+    id,
+    success: false,
+    error,
+    message,
+  };
+  console.log(JSON.stringify(response));
+}
+
+// ── Graceful Shutdown ──────────────────────────────────────────────────────
+process.on('SIGTERM', () => {
+  console.error('[INFO] Received SIGTERM, shutting down gracefully...');
+  rl.close();
+  process.exit(0);
+});
+
+process.on('SIGINT', () => {
+  console.error('[INFO] Received SIGINT, shutting down gracefully...');
+  rl.close();
+  process.exit(0);
+});