Files

Timur Gordon f970f3fb58 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

11 KiB

Raw Permalink Blame History

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

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

User enters email and personal information
Server generates verification token and sends email
User clicks verification link
Client generates key pair locally
User sets encryption password
Private key encrypted and stored locally
Public key and profile sent to server
Registration completed

Authentication Flow

User initiates login with public key
Server generates authentication challenge
Client decrypts private key with password
Client signs challenge with private key
Server verifies signature
Server issues JWT token
Client stores token for session

Identity Access Flow

User requests identity information
Client sends JWT token to server
Server validates token and returns user info
Client displays identity information
User can decrypt private key for operations

Security Architecture

Encryption Layers

Transport Layer: HTTPS for all communications
Application Layer: JWT tokens for session management
Storage Layer: AES-256-GCM for private key encryption
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

11 KiB Raw Permalink Blame History