Post-quantum encrypted filesystem with Telegram cloud storage

TGCryptFS is an encrypted filesystem that uses Telegram as its cloud storage backend. Files written to a TGCryptFS volume are encrypted locally with post-quantum cryptography (XChaCha20-Poly1305 authenticated encryption combined with ML-KEM-768 key encapsulation), split into content-defined chunks with deduplication, and uploaded as opaque blocks to your Telegram account. To you, it looks like a normal mounted directory. To everyone else -- including Telegram -- it is meaningless ciphertext.

The metadata layer uses an opaque SQLite schema where every table name, column name, and index name is derived through BLAKE3 keyed hashing, making the database itself resistant to schema analysis even if captured. Key material is protected by Argon2id password hashing, hierarchical key derivation, and optional forward secrecy through epoch-based key rotation.

TGCryptFS includes a dead man's switch that can automatically destroy volumes if you fail to check in, multi-user key sharing through ML-KEM post-quantum key exchange, and a REST API for programmatic integration. A 22-word sentence reference system provides human-readable key backup that can reconstruct access to any volume.

• Post-quantum cryptography -- XChaCha20-Poly1305 for authenticated encryption, ML-KEM-768 for key encapsulation, BLAKE3 for hashing, Argon2id for password derivation
• Telegram cloud storage backend -- unlimited, free, end-to-end encrypted block storage using your own Telegram account
• FUSE mounting -- mount encrypted volumes as normal directories; transparent read/write access from any application
• REST API -- 21 endpoints covering volumes, sharing, authentication, dead man's switch, and system status
• Dead man's switch -- configurable auto-destruction triggers with armed/disarmed states
• Multi-user key sharing -- share volumes with other users via ML-KEM key exchange or invite links
• 22-word sentence references -- human-readable, memorizable key backup for volume recovery
• Opaque SQLite schema -- all database identifiers derived via BLAKE3 keyed hashing; resistant to schema analysis
• Content-defined chunking -- deduplication across and within volumes using rolling hash boundaries
• Forward secrecy -- key epoch rotation so compromise of current keys does not expose past data

Install script (Linux and macOS):

curl -fsSL https://raw.githubusercontent.com/hedonistic-io/tgcryptfs/main/scripts/install.sh | bash

From crates.io:

cargo install tgcryptfs-cli

Build from source:

git clone https://github.com/hedonistic-io/tgcryptfs.git
cd tgcryptfs
cargo build --release
# Binary at target/release/tgcryptfs

See Building from Source for details and platform-specific notes.

1. Set up Telegram API credentials

TGCryptFS needs a Telegram API ID and hash to access your account. See docs/TELEGRAM_SETUP.md for a step-by-step walkthrough, or run the setup script:

./scripts/setup-telegram.sh

2. Authenticate

tgcryptfs auth login

3. Create an encrypted volume

tgcryptfs volume create --name mydata

4. Mount it

tgcryptfs volume mount mydata ~/secure

5. Use it like a normal directory

cp documents/*.pdf ~/secure/
ls ~/secure/
cat ~/secure/report.pdf

6. Unmount when done

tgcryptfs volume unmount ~/secure

7. Start the REST API server (optional)

tgcryptfs serve --bind 127.0.0.1:8080

For the complete walkthrough, see docs/GETTING_STARTED.md.

TGCryptFS is organized as a 9-crate Rust workspace:

                          +----------------+
                          | tgcryptfs-cli  |    CLI binary
                          +-------+--------+
                                  |
                    +-------------+-------------+
                    |                           |
             +------+------+           +-------+-------+
             | tgcryptfs-  |           | tgcryptfs-api |   REST API
             |    fuse     |           +-------+-------+
             +------+------+                   |
                    |                          |
        +-----------+-----------+--------------+----------+
        |           |           |              |          |
  +-----+-----+ +--+-------+ +-+----------+ +-+------+ +-+--------+
  | tgcryptfs- | | tgcryptfs| | tgcryptfs- | |tgcrypt| |tgcryptfs-|
  |   cache    | | -sharing | |  deadman   | |fs-tele| |  store   |
  +-----+------+ +--+-------+ +--+---------+ |gram   | +----+-----+
        |            |            |           +---+----+      |
        +------------+------------+---------------+-----------+
                                  |
                          +-------+--------+
                          | tgcryptfs-core |   Crypto, blocks,
                          +----------------+   metadata, policy

Prerequisites:

• Rust 1.75 or later
• FUSE development headers (Linux: libfuse3-dev; macOS: macFUSE; Windows: WinFsp)
• SQLite (bundled via rusqlite, no system dependency required)

git clone https://github.com/hedonistic-io/tgcryptfs.git
cd tgcryptfs
cargo build --release

The binary is written to target/release/tgcryptfs. To install it to your Cargo bin directory:

cargo install --path crates/tgcryptfs-cli

Run the full test suite:

cargo test --workspace    # 471 tests

See scripts/build.sh for platform-specific build automation.

Systemd and launchd service files are provided in the system/ directory:

# Linux (systemd) -- API server as user service
mkdir -p ~/.config/systemd/user
cp system/tgcryptfs-api.service ~/.config/systemd/user/
systemctl --user enable --now tgcryptfs-api

# Linux (systemd) -- dead man's switch timer
cp system/tgcryptfs-deadman.service system/tgcryptfs-deadman.timer ~/.config/systemd/user/
systemctl --user enable --now tgcryptfs-deadman.timer

# macOS (launchd) -- API server as user agent
cp system/io.hedonistic.tgcryptfs-api.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/io.hedonistic.tgcryptfs-api.plist

TGCryptFS is designed for strong confidentiality:

• Encryption: XChaCha20-Poly1305 authenticated encryption with 192-bit nonces. Every block, metadata record, and key blob is individually encrypted with unique associated data.
• Post-quantum key exchange: ML-KEM-768 (NIST FIPS 203) for key encapsulation during sharing operations. Resistant to quantum computing attacks on key exchange.
• Key derivation: Argon2id for password-to-key derivation. HKDF-SHA256 for hierarchical key derivation with domain separation.
• Schema obfuscation: All SQLite table names, column names, and index names are BLAKE3 keyed hashes. The database schema reveals nothing about data structure.
• Forward secrecy: Key epoch rotation ensures that compromise of current keys does not retroactively expose data encrypted under previous epochs.
• Memory safety: All key material implements ZeroizeOnDrop for automatic secure erasure.
• Dead man's switch: Configurable triggers for automatic volume destruction.

For the full threat model and cryptographic design, see docs/SECURITY.md.

Reporting vulnerabilities: If you discover a security issue, please report it privately to security@hedonistic.io. Do not open a public issue.

Contributions are welcome. See CONTRIBUTING.md for development setup, coding standards, and pull request guidelines.

# Run tests
cargo test --workspace

# Run clippy
cargo clippy --workspace -- -D warnings

# Format check
cargo fmt --check

TGCryptFS is licensed under the MIT License.

Copyright 2026 Hedonistic IO LLC.