# Seif Handshake Examples

This directory contains examples demonstrating the Seif Protocol handshake implementation in Prosperon.

## Files

- `seif_simple.js` - A standalone demonstration of the Seif handshake cryptographic operations
- `seif_server.js` - A server that accepts Seif handshake connections
- `seif_client.js` - A client that initiates Seif handshake with a server

## Running the Examples

### Simple Demo
To see the cryptographic operations in action:
```bash
./prosperon examples/seif_simple.js
```

### Client-Server Demo

1. First, start the server:
```bash
./prosperon examples/seif_server.js
```

2. Note the server's public key that is printed

3. Create a file `bob_public.key` with the server's public key:
```bash
echo "SERVER_PUBLIC_KEY_HERE" > bob_public.key
```

4. In another terminal, run the client:
```bash
./prosperon examples/seif_client.js
```

## The Seif Protocol

The Seif handshake establishes a secure session in one round trip:

1. **Alice's Message**: 
   - Generates random `handshake_key`
   - Sends: `{seif: 1, handshake: encrypt_pk(bob_public, handshake_key), payload: encrypt(handshake_key, alice_public)}`

2. **Bob's Response**:
   - Decrypts `handshake_key` using his private key
   - Decrypts Alice's public key from payload
   - Generates `session_key`
   - Sends: `encrypt(handshake_key, {session: encrypt_pk(alice_public, session_key)})`

3. **Result**: Both parties share `session_key` for symmetric encryption

## Actor System Integration

In Prosperon's actor system:
- Actor objects can serve as public key identifiers (they contain unique IDs)
- The `$_.portal()` function creates a listening endpoint
- The `$_.contact()` function initiates connections
- Messages are automatically routed through the actor system

## Security Properties

- **Authentication**: Both parties prove possession of their private keys
- **Forward Secrecy**: Session keys are ephemeral
- **Man-in-the-Middle Protection**: Requires knowledge of both private keys
- **One Round Trip**: Efficient session establishment

## Notes on Implementation

The current implementation uses the actor object's ID as part of the identity system. In a production system, you might want to:

1. Store the public key as part of the actor's data
2. Use a proper key derivation function for session keys
3. Add additional metadata in the handshake (timestamps, nonces, etc.)
4. Implement key rotation and session management

The crypto module provides:
- `crypto.keypair()` - Generate X25519 key pairs
- `crypto.encrypt_pk(public_key, data)` - Public key encryption
- `crypto.decrypt_pk(private_key, data)` - Public key decryption
- `crypto.encrypt(key, data)` - Symmetric encryption
- `crypto.decrypt(key, data)` - Symmetric decryption