@scriptdb/server 1.0.0

package/README.md

@@ -0,0 +1,407 @@
+# ScriptDB Server
+
+Server module for hosting and running ScriptDB instances with authentication, sandboxing, and command execution.
+
+## Installation
+
+```bash
+npm install @scriptdb/server
+# or
+yarn add @scriptdb/server
+# or
+bun add @scriptdb/server
+```
+
+## Quick Start
+
+```typescript
+import { server } from '@scriptdb/server';
+
+// Start the server with default configuration
+server();
+```
+
+## Configuration
+
+The server can be configured through:
+
+1. **Configuration file** (`scriptdb.config.json`)
+2. **Programmatic configuration**
+
+### Configuration File
+
+Create a `scriptdb.config.json` file in your project root:
+
+```json
+{
+  "host": "localhost",
+  "port": 1234,
+  "users": [
+    {
+      "username": "admin",
+      "password": "password123"
+    },
+    {
+      "username": "guest",
+      "password": "guest123"
+    }
+  ],
+  "folder": "databases"
+}
+```
+
+### Configuration Options
+
+- `host` (string): Server host (default: "localhost")
+- `port` (number): Server port (default: 1234)
+- `users` (array): Array of user objects
+- `folder` (string): Database storage folder (default: "databases")
+
+### User Configuration
+
+Each user object can contain:
+
+```json
+{
+  "username": "string",
+  "password": "string",
+  "passwordHash": "string",  // Pre-hashed password (bcrypt)
+  "signingSecret": "string"  // Secret for message signing
+}
+```
+
+## Programmatic Usage
+
+### Basic Server
+
+```typescript
+import { server } from '@scriptdb/server';
+
+// Start server with default settings
+server();
+```
+
+### Advanced Configuration
+
+```typescript
+import { server } from '@scriptdb/server';
+
+// The server reads from scriptdb.config.json if it exists
+// You can also modify the configuration programmatically before starting
+
+// Create a custom config file before starting
+import { writeFileSync } from 'fs';
+
+const config = {
+  host: "0.0.0.0",
+  port: 8080,
+  users: [
+    {
+      username: "admin",
+      passwordHash: "$2b$10$..."  // bcrypt hash
+    }
+  ],
+  folder: "./data"
+};
+
+writeFileSync('./scriptdb.config.json', JSON.stringify(config, null, 2));
+
+// Start the server
+server();
+```
+
+## Security Features
+
+### Authentication
+
+The server supports username/password authentication with bcrypt password hashing:
+
+```typescript
+// Using plain text passwords (server will hash them)
+{
+  "username": "user",
+  "password": "plain-text-password"
+}
+
+// Using pre-hashed passwords (bcrypt)
+{
+  "username": "user",
+  "passwordHash": "$2b$10$N9qo8uLOickgx2ZMRZoMye.IcnmVoKSj.9iECkZXod4HPnywpQqWu"
+}
+```
+
+### TLS/SSL Support
+
+The server supports secure connections using TLS:
+
+```json
+{
+  "host": "localhost",
+  "port": 1234,
+  "secure": true,
+  "tlsOptions": {
+    "key": "./server-key.pem",
+    "cert": "./server-cert.pem",
+    "ca": "./ca-cert.pem",
+    "rejectUnauthorized": true
+  },
+  "users": [
+    {
+      "username": "admin",
+      "password": "password"
+    }
+  ]
+}
+```
+
+### Message Signing
+
+Configure message signing for additional security:
+
+```json
+{
+  "users": [
+    {
+      "username": "admin",
+      "password": "password",
+      "signingSecret": "my-secret-key"
+    }
+  ]
+}
+```
+
+## API
+
+### server()
+
+Starts the ScriptDB server using the configuration file.
+
+```typescript
+import { server } from '@scriptdb/server';
+
+server(): void
+```
+
+The function:
+1. Reads `scriptdb.config.json` from the base path
+2. Validates configuration
+3. Creates the database folder if it doesn't exist
+4. Initializes the VM and protocol handler
+5. Starts the server
+
+## Database Management
+
+### Database Structure
+
+```
+databases/
+├── mydb1/
+│   ├── users.json
+│   ├── products.json
+│   └── ...
+├── mydb2/
+│   └── ...
+```
+
+### Command Execution
+
+The server executes JavaScript commands in a sandboxed environment:
+
+```javascript
+// Client can send commands like:
+const users = db.users.find({ status: 'active' });
+return users;
+
+// Or more complex operations:
+const result = db.collection('products').aggregate([
+  { $match: { category: 'electronics' } },
+  { $group: { _id: '$brand', count: { $sum: 1 } } }
+]);
+return result;
+```
+
+## Worker Threads
+
+The server uses worker threads for:
+
+- **bcrypt operations**: Password hashing and verification
+- **VM execution**: Running user code in isolation
+- **Payload validation**: Validating incoming requests
+
+This ensures the main thread remains responsive and operations don't block each other.
+
+## Rate Limiting
+
+The server implements IP-based and username-based rate limiting:
+
+```json
+{
+  "rateLimiting": {
+    "ipFailWindowMs": 900000,     // 15 minutes
+    "maxLoginAttempts": 5,
+    "lockDurationMs": 1800000     // 30 minutes
+  }
+}
+```
+
+## Examples
+
+### Production Server Setup
+
+```typescript
+import { server } from '@scriptdb/server';
+import { writeFileSync } from 'fs';
+
+// Production configuration
+const productionConfig = {
+  host: "0.0.0.0",
+  port: 443,
+  secure: true,
+  tlsOptions: {
+    key: "/path/to/private.key",
+    cert: "/path/to/certificate.crt",
+    ca: "/path/to/ca_bundle.crt"
+  },
+  users: [
+    {
+      username: "api_user",
+      passwordHash: "$2b$10$...",  // Pre-hashed password
+      signingSecret: "production-secret"
+    }
+  ],
+  folder: "/var/lib/scriptdb",
+  rateLimiting: {
+    ipFailWindowMs: 900000,
+    maxLoginAttempts: 5,
+    lockDurationMs: 1800000
+  }
+};
+
+// Write configuration
+writeFileSync('./scriptdb.config.json', JSON.stringify(productionConfig, null, 2));
+
+// Start server
+console.log("Starting ScriptDB server...");
+server();
+```
+
+### Development Setup
+
+```typescript
+import { server } from '@scriptdb/server';
+import { writeFileSync } from 'fs';
+
+// Development configuration
+const devConfig = {
+  host: "localhost",
+  port: 1234,
+  secure: false,  // Disable TLS for development
+  users: [
+    {
+      username: "dev",
+      password: "dev123"
+    },
+    {
+      username: "test",
+      password: "test123"
+    }
+  ],
+  folder: "./dev_databases"
+};
+
+writeFileSync('./scriptdb.config.json', JSON.stringify(devConfig, null, 2));
+
+// Start server
+console.log("Starting ScriptDB development server...");
+server();
+```
+
+### Multi-User Setup
+
+```typescript
+// Create multiple users with different permissions
+const multiUserConfig = {
+  host: "localhost",
+  port: 1234,
+  users: [
+    {
+      username: "admin",
+      password: "admin123",
+      signingSecret: "admin-signing-key"
+    },
+    {
+      username: "read_only",
+      password: "readonly123",
+      signingSecret: "readonly-signing-key"
+    },
+    {
+      username: "writer",
+      password: "writer123",
+      signingSecret: "writer-signing-key"
+    }
+  ],
+  folder: "./shared_databases"
+};
+```
+
+## Error Handling
+
+The server handles various error conditions:
+
+1. **Invalid Configuration**: Validates and sanitizes configuration values
+2. **Authentication Failures**: Tracks failed attempts and implements lockouts
+3. **File System Errors**: Creates directories and handles permission issues
+4. **Network Errors**: Handles connection failures and timeouts
+5. **VM Errors**: Isolates and reports script execution errors
+
+## Logging
+
+The server logs important events:
+
+- Server startup and configuration
+- Client connections and disconnections
+- Authentication attempts and failures
+- Command execution results
+- Error conditions
+
+Configure logging through environment variables or modify the server implementation.
+
+## Environment Variables
+
+- `NODE_ENV`: Set to 'production' for production mode
+- `SCRIPTDB_CONFIG_PATH`: Custom path to configuration file
+- `SCRIPTDB_LOG_LEVEL`: Logging level (debug, info, warn, error)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+
+# Lint code
+npm run lint
+```
+
+## Security Considerations
+
+1. **Use TLS in production**: Always enable secure connections
+2. **Strong passwords**: Use bcrypt hashes for stored passwords
+3. **Network security**: Configure firewalls and limit access
+4. **Regular updates**: Keep dependencies updated
+5. **Monitor logs**: Regularly check for suspicious activity
+
+## License
+
+MIT