sharenet_passport_creator/README.md

# Sharenet Passport Creator

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

**Binary Name**: `sharenet-passport`

## 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

## Installation

```bash
# Clone the repository
git clone <repository-url>
cd sharenet_passport_creator

# Build the project
cargo build --release

# Run the CLI
./target/release/sharenet-passport --help
```

## Usage Guide

### Creating a New Passport

Create a new Sharenet Passport with a secure recovery phrase:

```bash
./target/release/sharenet-passport create my-passport.spf
```

You'll be prompted to:
1. Enter an access password (used to encrypt the .spf file)
2. Confirm the access password

The tool will then:
- Generate a 24-word BIP-39 recovery phrase
- Create an Ed25519 key pair
- Generate a DID (Decentralized Identifier)
- Save an encrypted .spf file

**Important**: Store your recovery phrase securely offline! It's the only way to recover your identity if you lose access.

### Importing from Recovery Phrase

If you have a 24-word recovery phrase, you can import it to create a new .spf file:

```bash
./target/release/sharenet-passport import-recovery recovered-passport.spf
```

You'll be prompted to:
1. Enter your 24-word recovery phrase (one word per line)
2. Set a new access password for the .spf file

### Importing from Existing .spf File

Import an existing .spf file (useful for re-encryption or verification):

```bash
# Import without re-encryption
./target/release/sharenet-passport import-file existing.spf

# Import and re-encrypt to new file
./target/release/sharenet-passport import-file existing.spf new-passport.spf
```

You'll be prompted for the access password of the existing file.

### Exporting with New Password

Export a passport with a new access password:

```bash
./target/release/sharenet-passport export old-passport.spf new-passport.spf
```

You'll be prompted to:
1. Enter the current access password
2. Set a new access password

### Viewing Passport Information

Display information about a .spf file:

```bash
./target/release/sharenet-passport info my-passport.spf
```

Shows:
- DID (Decentralized Identifier)
- Public Key
- File location

### Signing Messages

Sign a message using your passport's private key:

```bash
./target/release/sharenet-passport sign my-passport.spf "Hello, Sharenet!"
```

Output includes:
- The original message
- 64-byte Ed25519 signature (hex encoded)
- Public key (for verification)

## 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

### 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

## Recovery Phrase Security

Your 24-word recovery phrase is the master key to your identity:

- **Never store digitally** - Write it down on paper
- **Keep offline** - Store in a secure physical location
- **Don't share** - Anyone with your recovery phrase can control your identity
- **Verify accuracy** - Double-check all 24 words when writing them down

## Development

### Running Tests

```bash
cargo test
```

### Project Structure

```
src/
├── domain/           # Core entities and traits
├── application/      # Use cases and business logic
├── infrastructure/   # Crypto and storage implementations
└── cli/             # Command-line interface
```

### Architecture

Built with Clean Architecture principles:
- **Domain Layer**: Core entities (Passport, RecoveryPhrase, etc.) and traits
- **Application Layer**: Use cases (CreatePassport, SignCard, etc.)
- **Infrastructure Layer**: Crypto implementations, file storage
- **CLI Layer**: User interface and command handling

## Security Considerations

- Passwords are never stored - only used for encryption/decryption
- Recovery phrases are only displayed during creation
- Private keys are zeroized from memory when no longer needed
- All cryptographic operations use industry-standard algorithms

## 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/

## Contributing

[Add contribution guidelines]