kiwavi 0.1.1

# Kiwavi 

A secure TOTP-based key derivation system that generates deterministic values from user salts without storing sensitive data in plaintext.

## Features

- **🔒 Secure**: Never stores derived values or secrets in plaintext memory
- **🔄 Deterministic**: Same salt + app config = same derived value
- **📱 Standard TOTP**: Compatible with Google Authenticator, Authy, etc.
- **🎯 Unique per User**: Different salts produce completely different values
- **⚡ Zero Dependencies on Storage**: All values derived on-demand
- **🛡️ Wrong Value Protection**: Returns believable but wrong values for incorrect TOTP codes

## Use Cases

Kiwavi is perfect for:
- **Backup key derivation** for WebAuthn/passkey systems
- **Deterministic secret generation** from user inputs
- **Recovery mechanisms** for encrypted data
- **Multi-factor authentication** where you need consistent derived values

## Salt Input Guidelines

Kiwavi accepts various salt formats for maximum flexibility:

### 🚀 **Most Efficient (Recommended)**
```rust
// 32-byte arrays from crypto.getRandomValues() - zero-copy
let prf_salt: [u8; 32] = get_from_webauthn_prf(); // Your WebAuthn PRF salt
let kiwavi = Kiwavi::from_prf_salt(prf_salt, app_config)?;

// Or any byte slice/vector
let salt_bytes: &[u8] = &your_binary_salt;
let kiwavi = Kiwavi::new(salt_bytes, app_config)?;
```

### ⚡ **Good Performance**
```rust
// Hex strings (common format) - minimal parsing overhead
let kiwavi = Kiwavi::from_hex("a1b2c3d4...", app_config)?;

// Direct Vec<u8>
let kiwavi = Kiwavi::new(your_salt_vec, app_config)?;
```

### 🐌 **Functional but Slower**
```rust  
// String salts - require UTF-8 processing
let kiwavi = Kiwavi::new("user_salt_string", app_config)?;
```

## Quick Start

Add Kiwavi to your `Cargo.toml`:

```toml
[dependencies]
kiwavi = "0.1.0"
```

### Basic Usage

```rust
use kiwavi::{Kiwavi, AppConfig};

// Create app configuration
let app_config = AppConfig::new("YourApp", "some-user@example.com");

// Initialize Kiwavi with user's unique salt
let kiwavi = Kiwavi::new("user_unique_salt_123", app_config)?;

// Generate QR code for user to scan with authenticator app
println!("Setup URL: {}", kiwavi.get_setup_qr());

// Validate TOTP and get derived value
let result = kiwavi.validate_and_derive("123456");

match result {
    ValidationResult::Success(value) => {
        println!("Correct! Derived value: {}", result.hex());
        // Use the 32-byte value for encryption keys, etc.
    }
    ValidationResult::Invalid(wrong_value) => {
        println!("Wrong TOTP code. Got: {}", result.hex());
        // This is a different, deterministic wrong value
    }
}
```

### WebAuthn Backup Example

```rust
use kiwavi::{Kiwavi, AppConfig};

// User's WebAuthn PRF salt (from your existing system)
let webauthn_prf_salt = "user_webauthn_salt_from_db";

// Create Kiwavi backup for this user
let app_config = AppConfig::new("MyWallet", "some-user@example.com");
let backup_kiwavi = Kiwavi::new(webauthn_prf_salt, app_config)?;

// User sets up TOTP during onboarding
println!("Backup recovery setup: {}", backup_kiwavi.get_setup_qr());

// Later, when user needs recovery access:
let totp_code = "734521"; // From their authenticator app
let result = backup_kiwavi.validate_and_derive(totp_code);

if result.is_valid() {
    // This derived value can be used as the WebAuthn PRF salt
    let recovered_salt = result.value();
    // Now decrypt private keys using this salt...
}
```

## API Reference

### `Kiwavi`

The main struct for TOTP-based key derivation.

#### Methods

- `new(user_salt: &str, app_config: AppConfig) -> Result<Self, KiwaviError>`
    - Creates new Kiwavi instance from user salt
- `validate_and_derive(&self, totp_code: &str) -> ValidationResult`
    - Validates TOTP and returns derived value
- `get_setup_qr(&self) -> String`
    - Returns otpauth:// URL for authenticator apps
- `preview_derived_value(&self) -> String`
    - Shows what the correct derived value would be (for testing)

### `AppConfig`

Configuration for your application.

```rust
let config = AppConfig::new("YourApp", "some-user@example.com");
// or with custom issuer
let config = AppConfig::with_issuer("YourApp", "some-user@example.com", "MyCompany");
```

### `ValidationResult`

Result of TOTP validation:

- `Success([u8; 32])` - TOTP was correct
- `Invalid([u8; 32])` - TOTP was wrong (contains different deterministic value)

#### Methods

- `value(&self) -> [u8; 32]` - Get the 32-byte value
- `hex(&self) -> String` - Get value as uppercase hex string
- `is_valid(&self) -> bool` - Check if TOTP was correct

## Security Properties

### ✅ What Kiwavi Protects Against

- **Memory dumps**: Derived values are never stored, only computed on-demand
- **Storage attacks**: No sensitive data in databases or files
- **Brute force**: Wrong TOTP codes get believable but useless values
- **Rainbow tables**: Each user salt produces unique value space

### ⚠️ What You Must Protect

- **User salts**: Keep these secure and consistent per user
- **TOTP secrets**: Users must secure their authenticator apps
- **App configuration**: Keep your app name/issuer consistent

## Why Kiwavi?

Traditional TOTP just validates codes. Kiwavi goes further by:

1. **Deriving cryptographic values** from user salts
2. **Never storing** the actual derived values
3. **Producing consistent results** for the same user
4. **Generating different values** for each user automatically
5. **Providing wrong but believable values** for security

This makes it perfect for backup systems, key derivation, and recovery mechanisms where you need more than just "yes/no" validation.

## License

Licensed under either of:

- Apache License, Version 2.0
- MIT License

at your option.