Metadata-Version: 2.4
Name: pyfino
Version: 0.1.0
Summary: Proof-of-Concept: Secure File Sharing via IPFS + Nostr DMs
Author: arnispen
License-Expression: MIT
Project-URL: Homepage, https://github.com/arnispen/fino
Project-URL: Repository, https://github.com/arnispen/fino
Project-URL: Issues, https://github.com/arnispen/fino/issues
Keywords: nostr,ipfs,encryption,file-sharing,proof-of-concept,innovation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pynostr[websocket-client]>=0.0.20
Requires-Dist: typer>=0.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: websockets>=11.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# FiNo 🔐📁

> **Proof-of-Concept: Secure File Sharing via IPFS + Nostr DMs**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Status: Proof of Concept](https://img.shields.io/badge/Status-Proof%20of%20Concept-orange.svg)](https://github.com/arnispen/fino)

**FiNo** (File + Nostr) is an innovative proof-of-concept CLI tool that demonstrates secure, decentralized file sharing using the Nostr protocol and IPFS. This project explores the intersection of decentralized messaging and distributed file storage for private, censorship-resistant file transfers.

## 🚀 **Innovation Highlights**

- **🔐 End-to-End Encryption**: Custom ECDH-based encryption for cross-key communication
- **🌐 Decentralized Infrastructure**: Leverages Nostr relays and IPFS for distributed operation
- **📱 CLI-First Design**: Simple, powerful command-line interface
- **🔒 Privacy-Focused**: No central servers, no tracking, no metadata retention
- **⚡ Real-Time**: Instant file sharing via Nostr DMs with IPFS storage

## 🏗️ **Architecture Overview**

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Sender    │    │   Nostr     │    │   Receiver  │
│             │    │   Relay     │    │             │
│ 1. Encrypt  │───▶│ 2. DM with  │───▶│ 3. Decrypt  │
│    File     │    │   Metadata  │    │   & Save    │
│ 2. Upload   │    │             │    │             │
│    to IPFS  │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌─────────────┐
                    │    IPFS     │
                    │   Storage   │
                    │             │
                    │ Encrypted   │
                    │   Files     │
                    └─────────────┘
```

## 🛠️ **Installation**

### Prerequisites

- Python 3.8 or higher
- Nostr key pair (nsec/npub)
- Pinata API key (for IPFS storage - **only needed for sending**)

### Quick Start

#### Option 1: Install from PyPI (Recommended)

```bash
# Install the package (includes all dependencies)
pip install pyfino

# Generate keys
fino gen-key

# Send a file
fino send --file document.pdf --to npub1... --from nsec1...

# Receive files
fino receive --from nsec1...
```

#### Option 2: Install from Source

```bash
# Clone the repository
git clone https://github.com/arnispen/fino.git
cd fino

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies and CLI tool (installing requirements.txt might not be absolutely necessary, but it's good to do just in case)
pip install -r requirements.txt
pip install -e .
```

## 🔑 **Setup**

### 1. Generate Nostr Keys

```bash
# Generate a new key pair
fino gen-key

# This will output:
# nsec: nsec1...
# npub: npub1...
```

### 2. Configure Pinata (IPFS Storage) - **Only for Sending**

Configure your Pinata JWT token globally:

```bash
# Interactive setup (recommended)
fino config set pinata-jwt

# Or set directly
fino config set pinata-jwt --value your_jwt_token_here
```

This will guide you through getting your JWT token from Pinata and store it securely in `~/.fino/config.json`.

> **Note**: Pinata JWT is only required for sending files (uploading to IPFS). Receiving files doesn't require any API keys.

## 📖 **Usage**

### Sending Files

```bash
# Send a file to a recipient
fino send \
  --file ./secret_document.pdf \
  --to npub1recipient_public_key_here \
  --from nsec1your_private_key_here
```

### Receiving Files

```bash
# Listen for incoming files (saves to current directory by default)
# Only shows NEW files sent to you after starting the command
fino receive \
  --from nsec1your_private_key_here

# Save to specific directory
fino receive \
  --from nsec1your_private_key_here \
  --output-dir ./downloads
```

> Note: FiNo uses a built-in default relay configuration for simplicity and reliability.

### Key Management

```bash
# Generate new key pair
fino gen-key
```

## 🔐 **Security Features**

### Encryption Layers

1. **File Encryption**: AES-256-CBC with random key and nonce
2. **Metadata Encryption**: Custom ECDH-based encryption for cross-key communication
3. **Nostr DMs**: Standard Nostr kind 4 encrypted direct messages

### Privacy Guarantees

- ✅ **No Central Servers**: Fully decentralized via Nostr relays
- ✅ **No Metadata Tracking**: IPFS CIDs are encrypted in DMs
- ✅ **End-to-End Encryption**: Only sender and recipient can decrypt
- ✅ **Censorship Resistant**: Distributed across multiple relays and IPFS nodes
- ✅ **Filename Preservation**: Original filenames are preserved when files are received

## 🧪 **Proof-of-Concept Status**

⚠️ **Important**: This is a **proof-of-concept** project designed for:

- **Innovation Research**: Exploring decentralized file sharing concepts
- **Educational Purposes**: Understanding Nostr + IPFS integration
- **Developer Experimentation**: Testing new cryptographic approaches

**Not intended for production use** without significant security audits and hardening.

## 🏗️ **Technical Implementation**

### Core Components

- **`src/fino/encryption.py`**: AES file encryption/decryption
- **`src/fino/ipfs.py`**: IPFS upload/download via Pinata
- **`src/fino/nostr.py`**: Nostr DM handling with custom ECDH encryption
- **`src/fino/commands/`**: CLI command implementations

### Key Innovations

1. **Custom ECDH Encryption**: Bypasses pynostr's broken cross-key encryption
2. **Hybrid Architecture**: Combines Nostr's real-time messaging with IPFS's persistent storage
3. **CLI-First Design**: Developer-friendly interface for rapid prototyping

## 🧪 **Manual Testing**

```bash
# Test file sharing between two users
# Terminal 1: Start receiver
fino receive --from nsec1receiver_key

# Terminal 2: Send file
fino send --file test.txt --to npub1receiver_key --from nsec1sender_key
```



## 🤝 **Contributing**

This is a proof-of-concept project. Contributions are welcome for:

- Bug fixes and improvements
- Documentation enhancements
- Security audits and recommendations
- Feature suggestions

Please read [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and guidelines.

## 📄 **License**

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

## ⚠️ **Disclaimer**

This software is provided as-is for educational and research purposes. The authors make no guarantees about security, reliability, or suitability for any purpose. Use at your own risk.

---

**FiNo** - Exploring the future of decentralized file sharing, one proof-of-concept at a time. 🔐📁
