sharenet/passport/README.md

# Sharenet Passport Library

A secure Rust library for creating and managing Sharenet Passport files (.spf) for decentralized identity management.

## Features

- **Secure Passport Creation**: Generate encrypted .spf files with BIP-39 mnemonic recovery phrases
- **Ed25519 Key Generation**: Cryptographically secure key derivation and signing
- **Recovery Support**: Import passports from recovery phrases or existing .spf files
- **Export & Re-encrypt**: Export passports with new passwords
- **Message Signing**: Sign messages using your passport's private key
- **Security First**: Zeroize memory management and secure file encryption
- **WASM Support**: Compatible with web applications via WebAssembly

## Installation

### From Private Registry

```toml
[dependencies]
sharenet-passport = { version = "0.2.0", registry = "sharenet-sh-forgejo" }
```

Platform selection is automatic based on your compilation target:
- **Native targets** (x86_64, aarch64, etc.): Use native implementations
- **WASM targets** (wasm32-unknown-unknown): Use WASM implementations

## Usage

### Creating a New Passport

```rust
use sharenet_passport::{
    application::use_cases::CreatePassportUseCase,
    infrastructure::{Bip39MnemonicGenerator, Ed25519KeyDeriver, XChaCha20FileEncryptor, FileSystemStorage},
};

let use_case = CreatePassportUseCase::new(
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    XChaCha20FileEncryptor,
    FileSystemStorage,
);

let (passport, recovery_phrase) = use_case.execute("your-password", "passport.spf")?;

println!("Public Key: {:?}", passport.public_key());
println!("DID: {}", passport.did().as_str());
println!("Recovery Phrase: {}", recovery_phrase.to_string());
```

### Importing from Recovery Phrase

```rust
use sharenet_passport::{
    application::use_cases::ImportFromRecoveryUseCase,
    infrastructure::{Bip39MnemonicGenerator, Ed25519KeyDeriver, XChaCha20FileEncryptor, FileSystemStorage},
};

let use_case = ImportFromRecoveryUseCase::new(
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    XChaCha20FileEncryptor,
    FileSystemStorage,
);

let recovery_words = vec!["word1".to_string(), "word2".to_string(), /* ... 24 words */];
let passport = use_case.execute(&recovery_words, "new-password", "recovered-passport.spf")?;
```

### Signing Messages

```rust
use sharenet_passport::{
    application::use_cases::{ImportFromFileUseCase, SignCardUseCase},
    infrastructure::{XChaCha20FileEncryptor, FileSystemStorage},
};

// Import passport from file
let import_use_case = ImportFromFileUseCase::new(
    XChaCha20FileEncryptor,
    FileSystemStorage,
);

let passport = import_use_case.execute("passport.spf", "password", None)?;

// Sign message
let sign_use_case = SignCardUseCase::new();
let signature = sign_use_case.execute(&passport, "Hello, Sharenet!")?;
```

## Architecture

Built with Clean Architecture principles:

- **Domain Layer**: Core entities (Passport, RecoveryPhrase, PublicKey, etc.) and traits
- **Application Layer**: Use cases (CreatePassport, ImportFromRecovery, SignCard, etc.)
- **Infrastructure Layer**: Crypto implementations, file storage

## Targets

The library automatically selects the appropriate implementation based on your compilation target:

### Native Targets
- **Platforms**: Linux, macOS, Windows, etc.
- **Storage**: File system
- **RNG**: System entropy (OsRng)
- **Time**: System time

### WASM Targets
- **Platforms**: Web browsers, Node.js
- **Storage**: Browser LocalStorage
- **RNG**: Web Crypto API via getrandom
- **Time**: JavaScript Date API

### Optional Override Features

For testing and special cases:
- `force-wasm`: Use WASM implementation even on native targets
- `force-native`: Use native implementation even on WASM targets

These features are mutually exclusive and will trigger a compile error if both are enabled.

## Security Features

- **XChaCha20-Poly1305**: Authenticated encryption for file security
- **HKDF-SHA256**: Key derivation from passwords
- **Zeroize**: Secure memory wiping for sensitive data
- **BIP-39**: Standard mnemonic generation and validation
- **Ed25519**: Cryptographically secure signing

## File Format (.spf)

Sharenet Passport Files (.spf) are encrypted containers that store:

- **Encrypted Seed**: The master seed encrypted with XChaCha20-Poly1305
- **Public Key**: Your Ed25519 public key
- **DID**: Your Decentralized Identifier
- **Metadata**: Creation timestamp, version, and encryption parameters

## Development

### Running Tests

```bash
# Test native implementation
cargo test

# Test WASM implementation
cargo test --target wasm32-unknown-unknown

# Test with override features
cargo test --features force-wasm
cargo test --features force-native
```

### Building for Different Targets

```bash
# Build for native
cargo build

# Build for WASM
cargo build --target wasm32-unknown-unknown
```

## License

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You are free to:
- **Share** — copy and redistribute the material in any medium or format
- **Adapt** — remix, transform, and build upon the material

Under the following terms:
- **Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
- **NonCommercial** — You may not use the material for commercial purposes.
- **ShareAlike** — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/4.0/