first commit

2025-09-24 05:11:15 +02:00
commit be061409af
19 changed files with 6052 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,180 @@
+# 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.