npm package: @lemur-bookstores/secure-stack-mesh
Description: Secure Service Mesh for SecureStack - Hybrid encryption, JWT auth, and service discovery
Author: @elkincp5
Latest version: 0.2.0

# Service Mesh Package

Secure service mesh implementation for SecureStack with hybrid encryption and mutual authentication.

## Features

### 🔐 Hybrid Encryption

- **RSA-4096** for key exchange and session establishment
- **AES-256-GCM** for efficient message encryption
- **HMAC-SHA256** for message integrity verification
- Key persistence and rotation support

### 🎫 JWT Authentication

- Mutual authentication between services
- Token-based authorization
- Configurable expiration times
- Secret rotation capabilities

### 🔄 Session Management

- Automatic session creation and tracking
- Timeout handling (default 1 hour)
- Message count tracking
- Session cleanup

### 📡 Service Discovery

- Static service registry
- Dynamic service lookup
- Health check support
- Service metadata management

## Installation

```bash
npm install @lemur-bookstores/secure-stack-mesh
```

## Quick Start

```typescript
import { SecureMesh } from '@lemur-bookstores/secure-stack-mesh';

// Create a mesh instance
const mesh = new SecureMesh({
  serviceId: 'my-service',
  port: 50051,
  security: {
    rsaKeySize: 4096,
    aesKeySize: 256,
  },
  discovery: {
    services: [{ id: 'other-service', host: 'localhost', port: 50052 }],
  },
});

// Initialize
await mesh.initialize();

// Connect to another service
const client = mesh.connect('other-service');

// Make a secure call
const response = await client.call('methodName', {
  data: 'payload',
});

console.log(response);

// Get statistics
const stats = mesh.getStats();
console.log('Active sessions:', stats.activeSessions);

// Cleanup
await mesh.cleanup();
```

## Architecture

### Components

#### CryptoManager

Handles all cryptographic operations:

- RSA key pair generation and management
- AES session key generation
- Hybrid encryption/decryption
- HMAC signature generation and verification

```typescript
const crypto = new CryptoManager({
  rsaKeySize: 4096,
  aesKeySize: 256,
});

await crypto.initialize();

const encrypted = crypto.encrypt(data, recipientPublicKey);
const decrypted = crypto.decrypt(encrypted, senderPublicKey);
```

#### JWTManager

Manages authentication tokens:

- Token generation with claims
- Token verification
- Secret rotation

```typescript
const jwt = new JWTManager({ secret: 'my-secret' });

const token = jwt.generateToken(serviceId, sessionId, '1h');
const payload = jwt.verifyToken(token);
```

#### SessionManager

Tracks active sessions:

- Session creation and lookup
- Timeout management
- Message tracking

```typescript
const sessions = new SessionManager({ timeout: 3600000 });

const session = sessions.createSession('service1', 'service2');
sessions.trackMessage(session.id);
```

#### StaticDiscovery

Service registry implementation:

- Service registration
- Service lookup
- Health checks

```typescript
const discovery = new StaticDiscovery();

discovery.register({
  id: 'my-service',
  host: 'localhost',
  port: 50051,
  publicKey: '<RSA-PUBLIC-KEY>',
});

const service = discovery.lookup('my-service');
```

## Security Features

### End-to-End Encryption

All messages are encrypted using a hybrid approach:

1. **Session Key Generation**: AES-256 key generated for each session
2. **Key Exchange**: Session key encrypted with recipient's RSA-4096 public key
3. **Message Encryption**: Data encrypted with AES-256-GCM
4. **Integrity Check**: HMAC-SHA256 signature for tamper detection

### Mutual Authentication

Both parties verify each other's identity:

1. **JWT Tokens**: Each request includes a JWT signed by sender
2. **Claims Verification**: Service ID and session ID validated
3. **Expiration Checks**: Tokens expire after configurable time
4. **Secret Rotation**: Periodic secret changes for enhanced security

## Configuration

```typescript
interface MeshConfig {
  serviceId: string; // Unique service identifier
  port: number; // gRPC server port

  security?: {
    rsaKeySize?: 2048 | 4096; // RSA key size (default: 4096)
    aesKeySize?: 128 | 192 | 256; // AES key size (default: 256)
    jwtSecret?: string; // JWT secret (auto-generated if not provided)
    jwtExpiration?: string; // Token expiration (default: '1h')
    sessionTimeout?: number; // Session timeout in ms (default: 3600000)
  };

  discovery?: {
    services: Array<{
      id: string;
      host: string;
      port: number;
      publicKey?: string;
    }>;
  };
}
```

## API Reference

### SecureMesh

#### `initialize(): Promise<void>`

Initialize cryptographic components and start the mesh.

#### `connect(serviceId: string): SecureMeshClient`

Create a client connection to another service.

#### `getStats(): MeshStats`

Get current mesh statistics (sessions, messages, services).

#### `healthCheck(): Promise<HealthStatus>`

Check mesh health status.

#### `cleanup(): Promise<void>`

Cleanup resources and close connections.

### SecureMeshClient

#### `call<TInput, TResult>(method: string, input: TInput): Promise<TResult>`

Make an encrypted, authenticated call to the remote service.

## Examples

See [examples/basic/src/mesh-example.ts](../../examples/basic/src/mesh-example.ts) for a complete working example.

## Performance

- **Encryption Overhead**: ~2-5ms per message (depends on payload size)
- **Session Establishment**: ~50-100ms (includes key exchange)
- **JWT Verification**: <1ms per token
- **Max Throughput**: ~10,000 messages/second per connection

## Security Considerations

1. **Key Storage**: Private keys are stored in memory and can be persisted to disk (ensure proper file permissions)
2. **Secret Management**: Use environment variables for JWT secrets in production
3. **Session Timeouts**: Configure appropriate timeouts based on your use case
4. **Key Rotation**: Implement periodic key rotation for long-running services
5. **Network Security**: Use TLS for transport layer security in production

## Roadmap

- [ ] gRPC protocol implementation
- [ ] Certificate-based authentication
- [ ] Rate limiting per service
- [ ] Circuit breaker pattern
- [ ] Distributed tracing integration
- [ ] Key rotation automation
- [ ] Service mesh observability dashboard

## License

MIT