f970f3fb58
- 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?;
245 lines
11 KiB
Markdown
245 lines
11 KiB
Markdown
# 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
|