rose-squared-sdk 0.1.0

# Rose-Squared SDK

[![Crates.io](https://img.shields.io/crates/v/rose-squared-sdk.svg)](https://crates.io/crates/rose-squared-sdk)
[![Documentation](https://docs.rs/rose-squared-sdk/badge.svg)](https://docs.rs/rose-squared-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Privacy-preserving encrypted search SDK implementing the SWiSSSE protocol with forward/backward security and volume-hiding, compilable to WebAssembly.**

---

## Overview

Rose-Squared SDK enables developers to build applications with **searchable encrypted data vaults**. Store sensitive data on untrusted servers while maintaining the ability to search by keyword — without ever revealing what you're searching for, which documents match, or even how many results exist.

Built on state-of-the-art academic cryptographic protocols, this SDK handles all the complexity of encryption, key management, and private search protocols, allowing you to focus on your application's core functionality.

## Key Features

### 🔒 Strong Security Guarantees

- **Forward Security** — Search tokens generated at time T cannot discover documents added after T
- **Backward Security Type-II** — Deleted documents are permanently unreachable via epoch rotation
- **Volume Hiding** — Every operation has exactly N_max entries (default 256); servers cannot distinguish result counts
- **Tamper Detection** — AES-256-GCM authentication tags detect server-side corruption or forgery
- **Memory Safety** — All secret keys derive `ZeroizeOnDrop`, automatically wiped from RAM on scope exit
- **Zero Unsafe Code** — `#![forbid(unsafe_code)]` enforced across the entire codebase

### ⚡ High Performance

- **O(1) Server Complexity** — Direct hash-map lookups, not scans or linked-list traversals
- **Efficient Cryptographic Primitives** — Argon2id + HKDF key derivation, AES-256-GCM encryption
- **WASM-Optimized** — Compiled to WebAssembly with LTO and size optimizations for browser use

### 🌐 WebAssembly Support

- **Browser-Ready** — Compile to WASM with `wasm-pack build --target web --features wasm`
- **IndexedDB Integration** — Persistent client-side state storage in the browser
- **Async JavaScript API** — Clean `WasmVault` class with Promise-based methods

### 🗄️ Pluggable Storage

- **EncryptedStore Trait** — Implement your own backend (IndexedDB, SQLite, Redis, S3, etc.)
- **MockStore Included** — HashMap-backed store for testing and development
- **State Persistence** — Encrypted index can be persisted locally or on remote servers

## Architecture

```
rose-squared-sdk/
├── crypto/           # Primitives: KDF (Argon2id+HKDF), AEAD (AES-256-GCM)
├── client/           # KeywordState, TrapdoorEngine, UpdateEngine
├── server/           # EncryptedStore trait + MockStore
├── protocol/         # SearchProtocol, SWiSSSE volume padding
├── wasm/             # WASM bindings and IndexedDB store
├── vault.rs          # PrivacyVault: the public API
└── error.rs          # VaultError types
```

### Cryptographic Protocols

This SDK implements the **SWiSSSE** (System-Wide Security for Searchable Symmetric Encryption) protocol, published in PoPETS 2024, with enhancements from the RO(SE)² framework for O(1) search complexity and forward/backward security.

## Quick Start

### Add to Your Project

```toml
[dependencies]
rose-squared-sdk = "0.1.0"
```

### Basic Usage (Native Rust)

```rust
use rose_squared_sdk::{PrivacyVault, VolumeConfig};

// Initialize a new vault with a password
let password = "secure_password_here";
let config = VolumeConfig::default(); // N_max = 256
let vault = PrivacyVault::new(password, config)?;

// Add a document with keywords
vault.add_document(
    "doc_uuid_1",
    "My Secret Document",
    &["rust", "privacy", "encryption"]
)?;

// Search for documents
let results = vault.search("privacy")?;
println!("Found {} documents", results.len());

// Delete a document
vault.delete_document("doc_uuid_1", &["rust", "privacy", "encryption"])?;
```

### WebAssembly Usage (Browser)

```bash
# Build for WASM
wasm-pack build --target web --features wasm
```

```javascript
import { WasmVault } from 'rose-squared-sdk';

const vault = new WasmVault();
await vault.initialize('my_secure_password');

await vault.addDocument('doc_1', 'Secret Notes', ['rust', 'privacy']);
const results = await vault.search('privacy');
console.log(`Found ${results.length} documents`);
```

## Cryptographic Flow

1. **Initialization** — Password + salt → Argon2id (64 MiB, 3 iterations) → 256-bit root key → HKDF-SHA256 fans out into 4 sub-keys (K_tag, K_val, K_state, K_srch)

2. **Add Document** — For each keyword: increment `total_writes`, derive HMAC-based tag, encrypt payload with AES-256-GCM, pad to N_max with decoy entries, write to server

3. **Search** — Look up live indices, generate (tag, key) pairs, pad with dummy entries, Fisher-Yates shuffle, send to server, decrypt matching results

4. **Delete Document** — Collect old-epoch tags, evict from live indices, bump epoch, re-encrypt survivors under new epoch, atomic update on server

## Use Cases

- **📔 Secure Journaling** — Store journal entries encrypted, search by keyword without the provider reading them
- **📝 Private Note-Taking** — Ideas and sensitive information in a searchable private vault
- **🔑 Password Managers** — Store and search passwords by website/service name securely
- **🏥 Healthcare Records** — HIPAA-compliant patient record search
- **⚖️ Legal Documents** — GDPR-compliant document management with cryptographic "Right to be Forgotten"
- **💬 Secure Messaging** — Private message history search in chat applications

## Configuration

### VolumeConfig

Control the volume-hiding behavior:

```rust
use rose_squared_sdk::VolumeConfig;

let config = VolumeConfig {
    n_max: 256,  // Pad all operations to 256 entries
};
```

- Larger `N_max` = better privacy, more bandwidth/storage overhead
- Smaller `N_max` = faster operations, weaker volume hiding
- Default: 256 (recommended for most use cases)

## Building from Source

### Prerequisites

- Rust 1.70+ (Edition 2021)
- For WASM: `wasm-pack` (`cargo install wasm-pack`)

### Native Build

```bash
# Clone the repository
git clone https://github.com/adithya-adee/rose-squared-sdk.git
cd rose-squared-sdk

# Run tests
cargo test

# Build
cargo build --release
```

### WASM Build

```bash
# Install wasm-pack if not already installed
cargo install wasm-pack

# Build for web
wasm-pack build --target web --features wasm

# Output in pkg/ directory, ready for npm or direct browser use
```

### Run Examples

```bash
# SQLite example (requires rusqlite)
cargo run --example sqlite_store
```

## Testing

```bash
# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run specific test module
cargo test crypto::
```

## Security Considerations

### What the Server **Cannot** Learn

- 🔍 **Search queries** — Keywords being searched are hidden via trapdoor tokens
- 📄 **Document contents** — All data encrypted with AES-256-GCM
- 🔗 **Access patterns** — Forward/backward security prevents linking operations
- 📊 **Result counts** — Volume hiding pads all operations to constant size

### What You **Must** Protect

- 🔑 **Client-side password** — Compromise reveals all data
- 💾 **ClientStateTable** — If lost without backup, data becomes unrecoverable
- ⚠️ **Search token reuse** — Using same token enables server-side query linking

### Limitations

- Not designed for multi-writer scenarios (single user per vault)
- Client state must be maintained for forward/backward security
- Volume padding introduces bandwidth overhead (N_max entries per operation)

## API Documentation

- [API Reference (docs.rs)](https://docs.rs/rose-squared-sdk)
- [Academic Paper (PDF)](docs/IAS_RoseSquared_v3.pdf)

## Roadmap

### ✅ Completed (v0.1.0)

- [x] RO(SE)² protocol implementation
- [x] SWiSSSE volume hiding
- [x] Forward and backward security
- [x] WASM bindings
- [x] IndexedDB integration
- [x] Crash recovery mechanism

### 🚧 Planned

- [ ] SQLite backend for native apps
- [ ] Redis backend for distributed systems
- [ ] S3-compatible object storage backend
- [ ] Adaptive N_max based on dataset analysis
- [ ] Multi-keyword boolean queries (AND/OR)
- [ ] Fuzzy search support

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

## Author

**Adithya** — [GitHub](https://github.com/adithya-adee)

## Acknowledgments

This SDK is based on the following academic papers:

- **RO(SE)²**: "A Robust, Secure, and Efficient Searchable Encryption Scheme" — IEEE Transactions on Computers, January 2025
- **SWiSSSE**: "System-Wide Security for Searchable Symmetric Encryption" — PoPETS 2024

---

<p align="center">
  <sub>Built with 🔒 for privacy, ❤️ for developers</sub>
</p>