self/README.md

# Self - Sovereign Digital Identity

A comprehensive self-sovereign identity system that puts users in complete control of their digital identity. Built with Rust and WebAssembly, Self provides cryptographic authentication without passwords, secure key management, and OAuth-compatible identity services.

## 🎯 Vision

Self enables true digital sovereignty by eliminating dependence on centralized identity providers. Users generate and control their own cryptographic keys, authenticate using digital signatures, and maintain complete ownership of their identity data.

## ✨ Key Features

### 🔐 Self-Sovereign Identity
- **User-Controlled Keys**: Generate and manage your own cryptographic key pairs
- **No Central Authority**: No single point of failure or control
- **Cryptographic Authentication**: Authenticate using digital signatures, not passwords
- **Zero-Knowledge Architecture**: Private keys never leave your device unencrypted

### 🛡️ Advanced Security
- **AES-256-GCM Encryption**: Military-grade encryption for private key storage
- **PBKDF2 Key Derivation**: 10,000+ iterations prevent brute force attacks
- **Client-Side Cryptography**: All sensitive operations performed locally
- **Secure Vault System**: Manage multiple encrypted identities

### 🌐 Standards Compliance
- **OAuth 2.0 Compatible**: Standard token-based authentication
- **OpenID Connect Ready**: Compatible with existing identity infrastructure
- **JWT Tokens**: Industry-standard session management
- **RESTful API**: Clean, documented endpoints

### 🔧 Developer-Friendly
- **Reusable Components**: Drop-in Yew components for any application
- **Comprehensive API**: Well-documented server endpoints
- **Multiple Deployment Options**: Docker, cloud-native, or bare metal
- **Extensive Documentation**: Complete guides for integration and deployment

## 🚀 Quick Start

### Prerequisites

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add WASM target and install Trunk
rustup target add wasm32-unknown-unknown
cargo install trunk
```

### Running the Application

1. **Clone and setup:**
   ```bash
   git clone <repository-url>
   cd self
   ```

2. **Start the backend server:**
   ```bash
   cd server
   cargo run
   # Server runs on http://localhost:8080
   ```

3. **Start the frontend (in another terminal):**
   ```bash
   cd app
   ./serve.sh
   # Frontend runs on http://localhost:8000
   ```

4. **Try the demo:**
   - Open http://localhost:8000 in your browser
   - Register a new identity with email verification
   - Generate and securely store your cryptographic keys
   - Experience passwordless authentication

### Core Workflows

#### 🆔 Identity Registration
1. **Email Verification**: Enter email → receive verification link → confirm
2. **Key Generation**: Generate secp256k1 key pair locally
3. **Secure Storage**: Encrypt private key with password → store in browser
4. **Backup Confirmation**: Copy private key for safe keeping
5. **Complete Registration**: Submit public key and profile to server

#### 🔑 Authentication
1. **Identity Selection**: Choose from stored identities in vault
2. **Key Decryption**: Enter password to decrypt private key
3. **Challenge Response**: Sign server challenge with private key
4. **Session Establishment**: Receive JWT token for authenticated session
5. **Identity Access**: Access identity information and services

## 🏗️ Architecture

### System Components

```
┌─────────────────────────────────────────────────────────────────┐
│                        Client (Browser)                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Registration  │  │     Login       │  │    Identity     │  │
│  │   Component     │  │   Component     │  │   Component     │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│                                │                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ Vault Manager   │  │     Crypto      │  │      Sign       │  │
│  │   Component     │  │    Utilities    │  │   Component     │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│                                │                                │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │              Local Storage (Encrypted)                     │  │
│  └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │
                          HTTPS/WSS
                                │
┌─────────────────────────────────────────────────────────────────┐
│                      Identity Server                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ Email Verification│ │ OAuth Endpoints │  │ User Management │  │
│  │    • SSE Stream  │  │  • /oauth/token │  │  • Registration│  │
│  │    • Verify Link │  │  • /oauth/userinfo│ │  • User Store  │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

### Project Structure

```
self/
├── components/                 # 🧩 Reusable Yew Components
│   ├── src/
│   │   ├── registration.rs    # User registration flow
│   │   ├── login.rs           # Authentication component
│   │   ├── identity.rs        # Identity management
│   │   ├── vault_manager.rs   # Multi-key vault system
│   │   ├── vault.rs           # Secure key storage
│   │   ├── crypto.rs          # Cryptographic utilities
│   │   ├── sign.rs            # Digital signing
│   │   └── lib.rs             # Component exports
│   └── Cargo.toml
├── app/                       # 🖥️ Reference Application
│   ├── src/lib.rs             # Demo app implementation
│   ├── index.html             # HTML template
│   ├── serve.sh               # Development server
│   └── Cargo.toml
├── server/                    # 🌐 Identity Server
│   ├── src/main.rs            # Axum server with OAuth endpoints
│   └── Cargo.toml
├── docs/                      # 📚 Comprehensive Documentation
│   ├── architecture.md        # System design and components
│   ├── authentication-flows.md # Auth workflows and security
│   ├── server-api.md          # API documentation
│   ├── cryptography.md        # Crypto implementation details
│   ├── vault-system.md        # Key management system
│   ├── openid-compliance.md   # OAuth/OIDC compatibility
│   ├── security-model.md      # Security analysis and threats
│   ├── deployment.md          # Production deployment guide
│   └── development.md         # Development setup and workflow
└── Cargo.toml                 # Workspace configuration
```

## 📚 Documentation

### Complete Documentation Suite

- **[Architecture Guide](docs/architecture.md)** - System design, components, and data flow
- **[Authentication Flows](docs/authentication-flows.md)** - Registration, login, and session management
- **[Server API](docs/server-api.md)** - Complete API reference with examples
- **[Cryptography](docs/cryptography.md)** - Detailed crypto implementation and security
- **[Vault System](docs/vault-system.md)** - Multi-key storage and management
- **[OpenID Compliance](docs/openid-compliance.md)** - OAuth 2.0 and OIDC compatibility
- **[Security Model](docs/security-model.md)** - Threat analysis and security controls
- **[Deployment Guide](docs/deployment.md)** - Production deployment and operations
- **[Development Guide](docs/development.md)** - Setup, workflow, and contribution guidelines

### Quick Integration

```rust
// Add Self components to your Yew application
use self_components::{Registration, Login, Identity, VaultManager};

// Registration flow
html! {
    <Registration 
        config={RegistrationConfig {
            server_url: "https://your-identity-server.com".to_string(),
            app_name: "Your App".to_string(),
        }}
        on_complete={|identity| {
            // Handle successful registration
        }}
    />
}

// Authentication flow
html! {
    <Login 
        config={LoginConfig {
            server_url: "https://your-identity-server.com".to_string(),
        }}
        on_login={|session| {
            // Handle successful login
        }}
    />
}
```

## 🔐 Security Features

### Cryptographic Foundation
- **Secp256k1 Keys**: Bitcoin/Ethereum-compatible elliptic curve cryptography
- **AES-256-GCM**: Authenticated encryption for private key storage
- **PBKDF2**: 10,000+ iterations for password-based key derivation
- **Secure Random**: Cryptographically secure random number generation

### Zero-Knowledge Architecture
- **Client-Side Operations**: All crypto operations in browser
- **No Server Secrets**: Server never sees private keys or passwords
- **Encrypted Storage**: Only encrypted data stored in localStorage
- **Minimal Data**: Server stores only public keys and basic profile

### Standards Compliance
- **OAuth 2.0**: Standard token-based authentication
- **OpenID Connect**: Compatible user info endpoint
- **JWT Tokens**: Industry-standard session management
- **HTTPS Only**: All communications encrypted in transit

## 🚀 Production Ready

### Deployment Options
- **Docker**: Complete containerized deployment
- **Kubernetes**: Cloud-native scaling and orchestration
- **Bare Metal**: Direct server deployment
- **Cloud Platforms**: AWS, GCP, Azure compatible

### Monitoring & Operations
- **Health Checks**: Built-in health monitoring endpoints
- **Structured Logging**: JSON-formatted logs with tracing
- **Metrics**: Prometheus-compatible metrics collection
- **Security Monitoring**: Comprehensive audit logging

### Scalability
- **Stateless Design**: Horizontal scaling support
- **Database Agnostic**: PostgreSQL, MySQL, or in-memory storage
- **Load Balancer Ready**: Multiple instance support
- **CDN Compatible**: Static asset optimization

## 🤝 Contributing

Self is open source and welcomes contributions! See our [Development Guide](docs/development.md) for:

- Development environment setup
- Code style guidelines
- Testing strategies
- Pull request process
- Release procedures

## 📄 License

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

---

**Ready to take control of your digital identity?** Start with our [Quick Start](#-quick-start) guide or dive deep into the [Architecture Documentation](docs/architecture.md).