npm package: @scriptdb/server
Description: server module resolver for script database
Latest version: 1.1.3

# 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
```

## CLI Tool

ScriptDB provides a CLI tool for easy server management:

```bash
# Install CLI globally
npm install -g @scriptdb/cli

# Start server in foreground
scriptdb start

# Start server in background (daemon mode with PM2)
scriptdb start -d

# Check server status
scriptdb status

# View real-time logs
scriptdb logs

# Monitor performance
scriptdb monit

# Stop server
scriptdb stop

# Restart server
scriptdb restart -d

# Start interactive shell
scriptdb shell

# Install packages to ScriptDB
scriptdb add lodash

# Install packages locally
scriptdb add --local lodash
```

### CLI Configuration

The CLI reads configuration from `~/.scriptdb/config.json`:

```json
{
  "host": "localhost",
  "port": 1234,
  "users": [
    {
      "username": "admin",
      "password": "your-password",
      "hash": false
    }
  ],
  "folder": "databases",
  "secure": false
}
```

### Process Management

The CLI uses PM2 for daemon mode, providing:

- Automatic restart on failure
- Log management
- Performance monitoring
- Cluster mode support

PM2 files are stored in `~/.scriptdb/`:
- `ecosystem.config.js` - PM2 configuration
- `pm2-*.log` - Log files

## Changelog

### 1.1.2 (2025-01-16)

**Added**
- Native `scriptdb logs` command to view real-time logs
- Native `scriptdb monit` command to monitor performance
- Native `scriptdb restart` command to restart the server
- Native `scriptdb stop` command to stop the server
- ESLint configuration for TypeScript linting

**Fixed**
- Fixed TypeScript type mismatch in users config normalization
- Fixed TypeScript "used before assigned" error for storage variable
- Fixed TypeScript module resolution errors
- Improved error handling and Windows compatibility

## License

MIT