# For God so loved the world that he gave his only begotten Son, that whoever believes in him should not perish but have eternal life. — John 3:16
# FiLeLuYa
[](https://github.com/loveJesus/fileluya/releases/latest/download/FiLeLuYa-v0.1.0.dmg)
[](https://crates.io/crates/fileluya-proto)
[](https://github.com/loveJesus/fileluya)
[](LICENSE)
[](https://fileluya.com)
> **FiLeLuYa** is a secure, encrypted filesystem where files act like reactive spreadsheet cells. Only authorized people can read or contribute to protected content. Every change is signed with hybrid post-quantum cryptography and forms a tamper-proof audit trail. Related files can automatically respond when linked content changes. Everyone begins with the same amount of **Time** ("Honor"), and Time can be bestowed within a system that measures genuine reuse across the network.
---
## Quick Start
```bash
# First-time setup (creates keys, config, default vault)
fileluya setup
# Mount your encrypted vault (runs as background daemon)
fileluya mount
# Use it like any folder
echo "hello world" > ~/FiLeLuYa/doc.txt
mkdir ~/FiLeLuYa/projects
cp report.pdf ~/FiLeLuYa/projects/
# Check active mounts
fileluya status
# Unmount
fileluya unmount ~/FiLeLuYa
# Remount later — your files are still there
fileluya mount
cat ~/FiLeLuYa/doc.txt
# -> "hello world"
# Open the desktop GUI
fileluya gui
```
---
## Install
### From crates.io (recommended)
```bash
# Prerequisites: Rust 1.85+, MacFUSE (macOS) or libfuse3-dev (Linux)
cargo install fileluya
```
### From git
```bash
# Installs the published-facing `fileluya` package from this repository
cargo install --git https://github.com/loveJesus/fileluya fileluya
```
### From a local clone
```bash
git clone https://github.com/loveJesus/fileluya
cd fileluya
cargo install --path crates-chirho/fileluya-fuse-chirho
```
### Build locally
```bash
git clone https://github.com/loveJesus/fileluya
cd fileluya
cargo build --release
# Binary at: target/release/fileluya
```
### macOS DMG
Download the [signed + notarized DMG](https://github.com/loveJesus/fileluya/releases/latest/download/FiLeLuYa-v0.1.0.dmg). Requires [MacFUSE](https://osxfuse.github.io/).
### Linux
```bash
# Install FUSE
sudo apt install libfuse3-dev fuse3 # Debian/Ubuntu
sudo dnf install fuse3-devel fuse3 # Fedora
cargo install fileluya
```
### Library crates (crates.io)
```bash
cargo add fileluya-proto # Wire protocol types
cargo add fileluya-lattices # CRDT lattice types
cargo add fileluya-crypto # Hybrid PQ crypto
cargo add fileluya-ledger # Token system
```
---
## Commands
```
fileluya setup First-time setup wizard
fileluya mount [path] [--cache-dir] Mount encrypted vault (daemonizes)
fileluya mount --foreground Mount in foreground (Ctrl+C to unmount)
fileluya unmount <path> Cleanly unmount
fileluya status Show active mounts and PIDs
fileluya config show Print current configuration
fileluya config set <key> <value> Update a config value
fileluya gui Open desktop app (Tauri)
```
### Configuration
After `fileluya setup`, config lives at `~/.fileluya/config.toml`:
```toml
[server_chirho]
url = "https://api-chirho.fileluya.com"
[identity_chirho]
user_id = "u-..."
public_key_signing = "ed25519:..."
public_key_exchange = "x25519:..."
[vault_chirho]
default_mount = "~/FiLeLuYa"
cache_dir = "~/.fileluya/cache"
[crypto_chirho]
argon2_profile = "standard" # standard (64MB) | light (32MB) | minimal (16MB)
```
---
## How It Works
```
You write a file
-> Encrypted with XChaCha20-Poly1305 (192-bit nonce)
-> Signed by your hybrid keypair (Ed25519 + ML-DSA-65)
-> Persisted to encrypted disk cache
-> Synced to Cloudflare R2 (server sees only opaque blobs)
You read a file
-> Loaded from local cache (or fetched from R2)
-> Decrypted client-side with your keys
-> Server never sees plaintext
You share a file
-> File key wrapped with recipient's X25519+ML-KEM public key
-> They can decrypt; nobody else can
-> Key rotation on member removal
```
### Zero-Knowledge Architecture
- Argon2id key derivation runs **client-side only**
- Server stores only encrypted blobs and public keys
- File sizes hidden via power-of-2 bucket padding
- All signatures are hybrid (classical + post-quantum) for non-repudiation
---
## Cryptography
| Key exchange | **X25519 + ML-KEM-768** | Hybrid: attacker must break both |
| Signatures | **Ed25519 + ML-DSA-65** | Hybrid post-quantum non-repudiation |
| Symmetric | **XChaCha20-Poly1305** | 192-bit nonce, safe for distributed random generation |
| Key derivation | **Argon2id -> HKDF-SHA256** | Memory-hard (64MB default), configurable for light devices |
| Content hash | **SHA-256** | Merkle chain for sigchain integrity |
Every mutation produces a `ProvenanceChirho` record with dual signatures forming a per-user sigchain (Merkle chain). An adversary must break **both** Ed25519 **and** ML-DSA to forge authorship.
---
## Reactive Files (Forge)
Files aren't static — they can be linked into reactive networks. When one changes, dependent files recompute automatically.
```
data.csv --(watches)--> Waterwheel --(outputs)--> summary.json
config.toml --(validates)--> Gear (must be valid TOML)
```
Connections are defined in `.forge` files using [Forge-Chirho](https://github.com/lovejesus/forge-aleluya):
- **Gears** — blocking constraints. All gears must agree or nothing changes.
- **Waterwheels** — derived computations. Input changes, output recomputes.
- **The `.forge` file is itself a cell** — edit it and the network reconfigures live.
Built on [propagators-chirho](https://crates.io/crates/propagators-chirho), a join-semilattice propagator network runtime with truth maintenance.
---
## Honor System (Time)
Everyone starts with **1.0 honor**. You bestow yours on people whose work you value. Total honor = total users (conserved). Anti-sybil by construction — creating accounts dilutes nothing.
**Three separate graphs prevent circular capture:**
1. **Identity Trust** — who vouches for whom (gates access, weights reputation)
2. **Content Reputation** — what gets reused, cited, forked (measures genuine value)
3. **Economic Rewards** — Time tokens, vested over 90 days (rewards sustained contribution)
Influence flows one-way: Trust -> Reputation -> Rewards (damped). Rewards **never** influence trust. Capital cannot buy truth.
### 9 Normative Invariants
1. Provenance != quality (authorship is fact, not endorsement)
2. Stake = collateral, not epistemic weight
3. Reuse > consumption (creating reusable content earns more)
4. Honor is conserved (total = N users)
5. Trust graphs are separate from reward graphs
6. No circular capture between graphs
7. Vesting prevents hit-and-run extraction
8. Key rotation invalidates old signatures
9. Every mutation is signed and chained
---
## Architecture
```
fileluya (single binary)
|-- setup First-time key generation + config
|-- mount / unmount / status FUSE filesystem driver (daemon mode)
|-- config View/edit ~/.fileluya/config.toml
|-- gui Desktop app (Tauri 2)
|
+-- Internal crates:
|-- fileluya-proto-chirho Wire protocol types, IDs, messages
|-- fileluya-lattices-chirho 7 lattice types (locks, CRDTs, versions, permissions)
|-- fileluya-crypto-chirho Hybrid PQ crypto, key wrapping, Argon2id
|-- fileluya-ledger-chirho Time tokens, honor, sigchain, escrow, vesting
|-- fileluya-fuse-chirho FUSE driver, caches, Forge executor, persistence
|-- fileluya-worker-chirho Cloudflare Worker backend (Rust/WASM)
+-- fileluya-gui-chirho Tauri 2 desktop application
```
### Backend
- **Cloudflare Workers** (Rust compiled to WASM) — request handling, auth, schema
- **R2** — encrypted chunk storage (server sees only opaque blobs)
- **D1** — metadata, user public keys, sigchain, auth sessions
- **Durable Objects** — lock coordination, propagator network state
Backend-agnostic by design — can also self-host.
**Live endpoints:**
- Worker: https://api-chirho.fileluya.com
- Website: https://fileluya.com
### Lattice Types
| `FileLockLatticeChirho` | Read/write lock coordination with timeout |
| `DirEntrySetChirho` | OR-Set CRDT for directory listings |
| `FileVersionLatticeChirho` | Version vectors for conflict detection |
| `PermissionLatticeChirho` | Monotonic permission grants |
| `CacheValidityChirho` | Cache coherence (Valid/Stale/Evicted) |
| `PropagatorStateLatticeChirho` | Forge computation state tracking |
| `TreeMoveLatticeChirho` | Safe concurrent directory renames |
---
## Formal Verification (LEAN4)
22 theorems proven across 5 files in `lean4-chirho/FiLeLuYa/`:
- **Lock safety**: write+write with different owners always conflicts (proven)
- **Lock liveness**: timeout guarantees eventual release (proven)
- **Version vectors**: partial order, merge is LUB, commutative, associative, idempotent (8 proofs)
- **OR-Set convergence**: membership preserved across merge orders (5 proofs)
- **Hybrid crypto**: combined scheme secure if either component is secure (5 proofs)
---
## What Makes It Different
| **Encryption** | E2E | Server-side | Varies | **Hybrid post-quantum E2E** |
| **Files** | Static blobs | Static blobs | N/A | **Reactive cells (propagator networks)** |
| **Conflicts** | Last-writer-wins | Conflict copies | N/A | **TMS-based: knows WHY, resolves intelligently** |
| **Trust** | Social proofs | None | Stake = power | **Conserved honor (anti-sybil by construction)** |
| **Sharing** | Folder-level | Folder-level | N/A | **Per-file, per-key wrapping** |
| **Rewards** | None | None | Mining/staking | **Reuse-based, vested 90 days** |
| **Post-quantum** | No | No | Mostly no | **Yes (ML-KEM-768 + ML-DSA-65)** |
| **Formal proofs** | No | No | Some | **22 LEAN4 theorems** |
---
## Project Status
| Encrypted mount | **Working** — tested on macOS with MacFUSE |
| Persistence | **Working** — survives unmount/remount (14/14 e2e tests) |
| Daemon mode | **Working** — survives shell exit, PID management |
| Setup wizard | **Working** — passphrase, keygen, config, vault creation |
| Crypto | **Working** — XChaCha20 + Ed25519 + X25519 + Argon2id |
| Locking | **Working** — propagator lattice with EAGAIN |
| Sharing | **Built** — team keys, per-file wrapping, key rotation |
| Conflict resolution | **Built** — TMS + Dropbox-style conflict files |
| Forge integration | **Built** — .forge watcher, gear/waterwheel execution |
| Token system | **Built** — honor, balances, transfers, escrow, vesting |
| Worker backend | **Deployed** — CF Workers + R2 + D1 (7 tables) |
| Website | **Live** — [fileluya.com](https://fileluya.com) (SvelteKit on CF Workers) |
| LEAN4 proofs | **22 theorems** proven |
| crates.io | **4 crates published** |
| GUI | **Scaffolded** — Tauri 2 with setup wizard, sharing, settings |
| Windows | **Scaffolded** — needs WinFsp testing |
**574+ tests, 0 failures.**
---
## Documentation
- [Vision](spec-chirho/vision-chirho.md) — strategic overview and three visibility levels
- [PRD](spec-chirho/PRD-chirho.md) — full product requirements with task tracking
- [Invariants](spec-chirho/invariants-chirho.md) — 10 normative rules
- [Trust & Value](spec-chirho/trust-and-value-chirho.md) — honor system design (three graphs)
- [UX Plan](spec-chirho/ux-plan-chirho.md) — setup wizard, sharing, config, Forge UX
- [Whitepaper](spec-chirho/fileluya-whitepaper-chirho.pdf) — 7-page LaTeX document
- [Monetary Policy](spec-chirho/ledger-chirho.forge) — Forge spec for Time token
---
## Related Projects
- [propagators-chirho](https://crates.io/crates/propagators-chirho) — Propagator networks runtime (join-semilattices, TMS)
- [Forge-Chirho](https://github.com/lovejesus/forge-aleluya) — Declarative language for reactive file networks
---
## License
MIT — Love Jesus (b. cowan)
**Soli Deo Gloria**