Add SelfFreezoneClient wrapper for Self components

- Created SelfFreezoneClient in Self components - Wraps SDK FreezoneScriptClient for Self-specific operations - Implements send_verification_email method - Uses Rhai script template for email verification - Includes template variable substitution - Added serde-wasm-bindgen dependency Usage: let client = SelfFreezoneClient::builder() .supervisor_url("http://localhost:8080") .secret("my-secret") .build()?; client.send_verification_email( "user@example.com", "123456", "https://verify.com/abc" ).await?;
2025-11-03 16:16:18 +01:00
parent be061409af
commit f970f3fb58
33 changed files with 8947 additions and 449 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,244 @@
+# System Architecture
+
+## Overview
+
+Self is a decentralized digital identity system built on self-sovereign identity principles. The architecture consists of client-side components for identity management and a lightweight server for email verification and OAuth-compatible authentication.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Client (Browser)                         │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │   Registration  │  │     Login       │  │    Identity     │  │
+│  │   Component     │  │   Component     │  │   Component     │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                │                                │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │ Vault Manager   │  │     Crypto      │  │      Sign       │  │
+│  │   Component     │  │    Utilities    │  │   Component     │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                │                                │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │              Local Storage (Encrypted)                     │  │
+│  │  • Encrypted Private Keys  • User Preferences              │  │
+│  │  • Vault Data              • Session Data                  │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                          HTTPS/WSS
+                                │
+┌─────────────────────────────────────────────────────────────────┐
+│                      Identity Server                            │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │ Email Verification│ │ OAuth Endpoints │  │ User Management │  │
+│  │    • SSE Stream  │  │  • /oauth/token │  │  • Registration│  │
+│  │    • Verify Link │  │  • /oauth/userinfo│ │  • User Store  │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                │                                │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │                In-Memory Storage                            │  │
+│  │  • Verification Status     • User Records                  │  │
+│  │  • JWT Secrets            • Session Management             │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Principles
+
+### 1. Self-Sovereign Identity
+- Users generate and control their own cryptographic key pairs
+- No central authority controls user identities
+- Private keys never leave the user's device unencrypted
+- Users can prove their identity without revealing sensitive information
+
+### 2. Client-Side Security
+- All cryptographic operations performed in the browser
+- Private keys encrypted with user-chosen passwords before storage
+- Zero-knowledge architecture - server never sees private keys
+- Local storage used only for encrypted data
+
+### 3. Minimal Server Dependency
+- Server only handles email verification and OAuth compatibility
+- No user data stored on server beyond public keys and basic profile
+- Stateless authentication using JWT tokens
+- Can be self-hosted or run as a service
+
+## Component Architecture
+
+### Client Components (Rust + WASM)
+
+#### Registration Component
+- **Purpose**: New user onboarding and key generation
+- **Features**:
+  - Email verification flow
+  - Secure key pair generation
+  - Password-based encryption
+  - Key backup confirmation
+- **Dependencies**: Crypto utilities, Server API
+
+#### Login Component  
+- **Purpose**: Existing user authentication
+- **Features**:
+  - Challenge-response authentication
+  - Private key decryption
+  - JWT token management
+  - Session establishment
+- **Dependencies**: Crypto utilities, Vault system
+
+#### Identity Component
+- **Purpose**: Identity management and key access
+- **Features**:
+  - Identity information display
+  - Private key access with password
+  - Public key sharing
+  - Account management
+- **Dependencies**: Vault system, Server API
+
+#### Vault Manager Component
+- **Purpose**: Multi-key storage and management
+- **Features**:
+  - Multiple encrypted key storage
+  - Password-based access control
+  - Key import/export functionality
+  - Secure key deletion
+- **Dependencies**: Crypto utilities
+
+#### Crypto Utilities
+- **Purpose**: Core cryptographic operations
+- **Features**:
+  - Key pair generation (secp256k1)
+  - AES-256-GCM encryption/decryption
+  - PBKDF2 key derivation
+  - Digital signatures
+- **Dependencies**: Web Crypto API, Rust crypto crates
+
+#### Sign Component
+- **Purpose**: Message and document signing
+- **Features**:
+  - Digital signature creation
+  - Signature verification
+  - Message authentication
+  - Document integrity
+- **Dependencies**: Crypto utilities, Vault system
+
+### Server Component (Rust + Axum)
+
+#### Email Verification Service
+- **Purpose**: Verify user email addresses
+- **Features**:
+  - Verification token generation
+  - Server-sent events for real-time status
+  - Email verification callbacks
+  - Development console output
+- **Storage**: In-memory verification status
+
+#### OAuth Endpoints
+- **Purpose**: OAuth 2.0 compatible authentication
+- **Features**:
+  - JWT token issuance
+  - User info endpoint
+  - Bearer token validation
+  - Standard OAuth flows
+- **Compliance**: OAuth 2.0, OpenID Connect compatible
+
+#### User Management
+- **Purpose**: Basic user record management
+- **Features**:
+  - User registration
+  - Public key storage
+  - Profile information
+  - Account lookup
+- **Storage**: In-memory user store (production: database)
+
+## Data Flow
+
+### Registration Flow
+1. User enters email and personal information
+2. Server generates verification token and sends email
+3. User clicks verification link
+4. Client generates key pair locally
+5. User sets encryption password
+6. Private key encrypted and stored locally
+7. Public key and profile sent to server
+8. Registration completed
+
+### Authentication Flow
+1. User initiates login with public key
+2. Server generates authentication challenge
+3. Client decrypts private key with password
+4. Client signs challenge with private key
+5. Server verifies signature
+6. Server issues JWT token
+7. Client stores token for session
+
+### Identity Access Flow
+1. User requests identity information
+2. Client sends JWT token to server
+3. Server validates token and returns user info
+4. Client displays identity information
+5. User can decrypt private key for operations
+
+## Security Architecture
+
+### Encryption Layers
+1. **Transport Layer**: HTTPS for all communications
+2. **Application Layer**: JWT tokens for session management
+3. **Storage Layer**: AES-256-GCM for private key encryption
+4. **Key Derivation**: PBKDF2 with 10,000 iterations
+
+### Trust Model
+- **User Trust**: Users trust their own devices and passwords
+- **Server Trust**: Minimal trust required - only for email verification
+- **Network Trust**: HTTPS provides transport security
+- **Storage Trust**: Local storage with client-side encryption
+
+### Threat Mitigation
+- **Key Theft**: Private keys encrypted, passwords required
+- **Server Compromise**: No private keys stored on server
+- **Network Attacks**: HTTPS and signature verification
+- **Browser Attacks**: Encrypted storage, secure key handling
+
+## Scalability Considerations
+
+### Horizontal Scaling
+- Stateless server design enables load balancing
+- In-memory storage can be replaced with distributed cache
+- Multiple server instances can share user database
+- Client components scale with user devices
+
+### Performance Optimization
+- WASM compilation for crypto operations
+- Lazy loading of components
+- Efficient key derivation caching
+- Minimal server round trips
+
+### Storage Scaling
+- Client storage limited by browser quotas
+- Server storage minimal (public keys only)
+- Database can be sharded by user ID
+- CDN can serve static client assets
+
+## Technology Stack
+
+### Client Side
+- **Language**: Rust compiled to WebAssembly
+- **Framework**: Yew for UI components
+- **Crypto**: aes-gcm, sha2, getrandom crates
+- **Storage**: Browser localStorage API
+- **Build**: Trunk for WASM bundling
+
+### Server Side
+- **Language**: Rust
+- **Framework**: Axum for HTTP server
+- **Auth**: jsonwebtoken for JWT handling
+- **Async**: Tokio runtime
+- **CORS**: tower-http for cross-origin requests
+
+### Deployment
+- **Client**: Static files served via CDN or web server
+- **Server**: Container deployment (Docker/Kubernetes)
+- **Database**: PostgreSQL/MySQL for production
+- **Monitoring**: Structured logging with tracing crate