circles/examples/wss_demo/README.md

# WSS (WebSocket Secure) Demo

This directory contains a complete demonstration of WSS (WebSocket Secure) functionality with TLS encryption and authentication.

## Contents

- `cert.pem` - Self-signed TLS certificate for testing
- `key.pem` - Private key for the TLS certificate
- `wss_server.rs` - WSS server example with authentication
- `wss_client.rs` - WSS client example for testing

## Quick Start

### 1. Start the WSS Server

```bash
# From the project root - specify the correct package and feature
cargo run --manifest-path src/server/Cargo.toml --example wss_server --features circle_ws_lib/auth

# OR run from the wss_demo directory
cd examples/wss_demo
cargo run --bin wss_server
```

The server will start on:
- **WSS (Secure)**: `wss://127.0.0.1:8443/ws`
- **WS (Regular)**: `ws://127.0.0.1:8080/ws`

### 2. Test with the WSS Client

Run the WSS client that uses the circle_client_ws library:

```bash
# Navigate to the wss_demo directory
cd examples/wss_demo

# Run with logging (recommended)
RUST_LOG=info cargo run --bin wss_client

# Or without logging
cargo run --bin wss_client
```

This will run the `wss_client.rs` file which demonstrates:
- Automatic credential generation using secp256k1
- WSS connection with TLS encryption
- Full authentication flow
- Script execution over secure WebSocket

**Note**: The WSS client must be run from the `examples/wss_demo` directory as it's a standalone project with its own dependencies.

## Features Demonstrated

### 🔒 **TLS/WSS Encryption**
- Self-signed certificate for development/testing
- Secure WebSocket connections over TLS
- Certificate validation and error handling

### 🛡️ **Authentication**
- secp256k1 signature-based authentication
- Nonce generation and verification
- Authenticated vs unauthenticated request handling

### 📝 **JSON-RPC Protocol**
- Standard JSON-RPC 2.0 over WebSocket
- Method calls: `fetch_nonce`, `authenticate`, `play`
- Error handling and response validation

## Certificate Information

The included certificate is a **self-signed certificate** for development and testing purposes only.

**Certificate Details:**
- **Subject**: `/C=US/ST=Demo/L=Demo/O=WSS Demo/CN=localhost`
- **Validity**: 365 days from generation
- **Key Size**: RSA 4096-bit
- **Usage**: Development/Testing only

⚠️ **Security Notice**: Do not use this certificate in production. Generate proper certificates from a trusted Certificate Authority for production use.

## Testing with Browser

You can test the WSS connection using browser developer tools:

```javascript
// Open browser console and run:
const ws = new WebSocket('wss://127.0.0.1:8443/ws');

ws.onopen = () => {
    console.log('WSS Connected!');
    // Send a test message
    ws.send(JSON.stringify({
        jsonrpc: "2.0",
        method: "fetch_nonce",
        params: { pubkey: "test_key" },
        id: 1
    }));
};

ws.onmessage = (event) => {
    console.log('Response:', JSON.parse(event.data));
};
```

**Note**: Your browser may show a security warning due to the self-signed certificate. This is expected for development.

## Testing with websocat

You can also test with websocat (WebSocket command-line client):

```bash
# Install websocat if not already installed
cargo install websocat

# Connect to WSS server (ignoring certificate validation for self-signed cert)
websocat --insecure wss://127.0.0.1:8443/ws

# Or with more explicit options
websocat -k wss://127.0.0.1:8443/ws

# Send a test message (after connecting)
{"jsonrpc":"2.0","method":"fetch_nonce","params":{"pubkey":"test_key"},"id":1}
```

**Note**: The `--insecure` or `-k` flag is needed because we're using a self-signed certificate.

## Authentication Flow

### 1. Fetch Nonce
```json
{
    "jsonrpc": "2.0",
    "method": "fetch_nonce",
    "params": { "pubkey": "your_public_key_hex" },
    "id": 1
}
```

### 2. Authenticate
```json
{
    "jsonrpc": "2.0",
    "method": "authenticate",
    "params": {
        "pubkey": "your_public_key_hex",
        "signature": "signed_nonce_hex"
    },
    "id": 2
}
```

### 3. Execute Commands
```json
{
    "jsonrpc": "2.0",
    "method": "play",
    "params": { "script": "40 + 2" },
    "id": 3
}
```

## Troubleshooting

### Certificate Issues
If you encounter certificate-related errors:

1. **Regenerate certificates**:
   ```bash
   cd examples/wss_demo
   rm cert.pem key.pem
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/C=US/ST=Demo/L=Demo/O=WSS Demo/CN=localhost"
   ```

2. **Check file permissions**:
   ```bash
   ls -la cert.pem key.pem
   ```

### Connection Issues
- Ensure no other services are using ports 8080 or 8443
- Check firewall settings
- Verify the server started successfully (look for "✅ WSS Server started successfully!" message)

### Authentication Issues
- Ensure you're using valid secp256k1 signatures
- Check that the nonce hasn't expired (default: 5 minutes)
- Verify the public key format is correct hex encoding

## Production Deployment

For production use:

1. **Use proper certificates** from a trusted CA
2. **Configure proper hostnames** (not localhost)
3. **Set up proper firewall rules**
4. **Use environment variables** for sensitive configuration
5. **Enable proper logging and monitoring**
6. **Consider load balancing** for high availability

## Related Documentation

- [WSS Implementation Plan](../../WSS_IMPLEMENTATION_PLAN.md)
- [Server WS README](../../src/server/README.md)
- [Client WS README](../../src/client_ws/README.md)