self/README.md

# Self - Sovereign Entity Local Framework

A peer-to-peer identity solution providing self-sovereign identity management tools and widgets. Built with Yew WASM for client-side functionality and Rust backend for email verification.

## Architecture

- **Components**: Reusable Yew components for identity management (registration, login, etc.)
- **App**: Reference implementation using the components
- **Server**: Backend for email verification and registration endpoints

## Features

### Registration Component

- **Identity Collection**: Name and email input with validation
- **Email Verification**: Server-sent events for real-time verification status
- **Private Key Generation**: Secure secp256k1 key pair generation
- **Client-side Encryption**: AES-256-GCM encryption of private keys with user password
- **Key Confirmation**: Requires user to copy and paste private key to confirm backup
- **Single-page Flow**: Progressive multi-step form without page navigation

### Security Features

- Private keys generated and encrypted entirely client-side
- Password-based key derivation with salt and key stretching
- Secure key confirmation process prevents accidental loss
- No private keys transmitted to server

## Quick Start

### Prerequisites

- Rust (latest stable)
- `trunk` for WASM building: `cargo install trunk`
- `wasm32-unknown-unknown` target: `rustup target add wasm32-unknown-unknown`

### Running the Application

1. **Start the backend server:**
   ```bash
   cd server
   # Default port (8080)
   cargo run
   
   # Custom port
   cargo run -- --port 9001
   ```

2. **Start the frontend app:**
   ```bash
   cd app
   # Default configuration (server: localhost:8080, port: 8000)
   ./serve.sh
   
   # Custom server URL
   ./serve.sh --server-url http://localhost:9001
   
   # Custom frontend port
   ./serve.sh --port 8001
   
   # Both custom server and port
   ./serve.sh --server-url http://localhost:9001 --port 8001
   
   # Using environment variables
   SELF_SERVER_URL=http://localhost:9001 ./serve.sh
   ```

3. **Open your browser** to the displayed frontend URL

### Email Verification Flow

1. Enter name and email, proceed to verification step
2. Click "Send Verification" - check server console for verification link
3. Click the verification link in a new tab
4. The registration form will automatically update when verified
5. Continue with key generation

### Key Generation Flow

1. Click "Generate Keys" to create a new key pair
2. Enter and confirm an encryption password (minimum 8 characters)
3. Copy the private key using the "Copy" button
4. Proceed to confirmation step
5. Paste the private key to confirm you saved it
6. Complete registration

## Development

### Project Structure

```
self/
├── components/          # Reusable Yew components
│   ├── src/
│   │   ├── registration.rs  # Main registration component
│   │   ├── crypto.rs       # Cryptographic utilities
│   │   └── lib.rs         # Component exports
│   └── Cargo.toml
├── app/                # Reference application
│   ├── src/lib.rs      # App implementation
│   ├── index.html      # HTML template with Bootstrap
│   ├── Trunk.toml      # Trunk configuration
│   └── Cargo.toml
├── server/             # Backend server
│   ├── src/main.rs     # Axum server with SSE support
│   └── Cargo.toml
└── Cargo.toml          # Workspace configuration
```

### Using the Registration Component

```rust
use self_components::{Registration, RegistrationConfig};

let config = RegistrationConfig {
    server_url: "http://localhost:8080".to_string(),
    app_name: "My App".to_string(),
};

let on_complete = Callback::from(|(email, public_key): (String, String)| {
    // Handle successful registration
    console::log!("User registered: {} with key: {}", email, public_key);
});

html! {
    <Registration 
        config={config}
        on_complete={on_complete}
    />
}
```

### API Endpoints

- `POST /api/send-verification` - Send email verification
- `GET /api/verification-status/{email}` - SSE stream for verification status
- `GET /api/verify/{token}` - Email verification callback
- `POST /api/register` - Complete user registration
- `GET /health` - Health check

### Configuration Options

**Backend Server:**
- Command line: `cargo run -- --port 9001`
- Default port: 8080

**Frontend App:**
- Command line: `./serve.sh --server-url http://localhost:9001 --port 8001`
- Environment variables: `SELF_SERVER_URL`, `SELF_PORT`
- Defaults: server `http://localhost:8080`, port `8000`

**Registration Component:**
The registration component accepts a `RegistrationConfig` with:
- `server_url`: Backend server URL (configured via build-time environment variable)
- `app_name`: Application name for branding

The component emits completion events with `(email, public_key)` tuple for integration with your application.

## Security Considerations

- Private keys are generated using cryptographically secure random number generation
- Keys are encrypted client-side before any storage
- Password-based key derivation uses PBKDF2-like key stretching
- No sensitive data is transmitted to the server except public keys
- Email verification prevents unauthorized registrations

## Production Deployment

For production use:

1. **Replace mock email sending** in server with actual SMTP integration
2. **Add database storage** for user data and verification states
3. **Implement proper secp256k1** key generation (current implementation is simplified)
4. **Add rate limiting** for verification requests
5. **Use HTTPS** for all communications
6. **Configure CORS** appropriately for your domain

## License

This project is part of the Hero Code ecosystem for decentralized identity management.