filanti 1.1.0

A modular, security-focused file framework for encryption, hashing, and integrity verification

FILANTI

A modular, security-focused file framework for Python

Installation • Quick Start • Features • CLI • SDK • Security

---

Overview

Filanti is a Python framework providing secure-by-default primitives for:

• File Encryption - AES-256-GCM, ChaCha20-Poly1305 with password-based encryption
• Asymmetric Encryption - Hybrid encryption with X25519, RSA-OAEP for multi-recipient file exchange
• Cryptographic Hashing - SHA-256/384/512, SHA3, BLAKE2b
• Integrity Verification - HMAC, digital signatures, checksums
• Streaming Support - Memory-efficient processing of large files
• Plugin Architecture - Extensible algorithm support
• ENV-Based Secrets - Secure secret injection for automation workflows

Filanti acts as a secure abstraction layer over cryptographic operations, avoiding unsafe custom implementations while remaining extensible and auditable.

Installation

From PyPI

pip install filanti

From Source

git clone https://github.com/decliqe/filanti.git
cd filanti
pip install -e .

Development Installation

pip install -e ".[dev]"

This includes testing and linting tools: pytest, pytest-cov, ruff, mypy.

Requirements

• Python: 3.11 or higher
• Dependencies:
  • cryptography>=42.0.0 - Core cryptographic operations
  • typer>=0.9.0 - CLI framework
  • argon2-cffi>=23.1.0 - Password hashing and KDF

---

Quick Start

Python SDK

from filanti.api import Filanti

# Hash a file
result = Filanti.hash_file("document.pdf")
print(f"SHA-256: {result.hash}")

# Encrypt with password
Filanti.encrypt("secret.txt", password="my-secure-password")

# Decrypt
Filanti.decrypt("secret.txt.enc", password="my-secure-password")

# Asymmetric encryption (for secure file sharing)
keypair = Filanti.generate_asymmetric_keypair()
Filanti.save_asymmetric_keypair(keypair, "mykey.pem")
Filanti.hybrid_encrypt("secret.txt", ["recipient.pub"])
Filanti.hybrid_decrypt("secret.txt.henc", "mykey.pem")

# Generate signing keys
keypair = Filanti.generate_keypair()

# Sign a file
signature = Filanti.sign_file("document.pdf", keypair.private_key, create_file=True)

# Verify signature
Filanti.verify_signature_file("document.pdf")

Command Line

# Hash a file
filanti hash document.pdf

# Encrypt a file
filanti encrypt secret.txt --password "my-password"

# Decrypt a file
filanti decrypt secret.txt.enc --password "my-password"

# Asymmetric encryption (for secure file sharing)
filanti keygen-asymmetric mykey
filanti encrypt-pubkey secret.txt --pubkey recipient.pub
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem

# Generate signing keys
filanti keygen my_key --protect

# Sign a file
filanti sign document.pdf --key my_key

# Verify signature
filanti verify-sig document.pdf

---

Features

Encryption

Modern authenticated encryption with automatic integrity verification.

Algorithm	Description	Key Size	Use Case
aes-256-gcm	AES-256 in GCM mode (default)	256-bit	General purpose, hardware-accelerated
chacha20-poly1305	ChaCha20 with Poly1305 MAC	256-bit	Excellent software performance

Password-Based Encryption:

• Uses Argon2id (OWASP recommended) for key derivation
• Automatic salt generation (32 bytes)
• Secure memory handling for passwords

from filanti.api import Filanti

# Password-based encryption
Filanti.encrypt("file.txt", password="secure-password")
Filanti.decrypt("file.txt.enc", password="secure-password")

# Raw key encryption
key = Filanti.generate_key(32)  # 256-bit key
Filanti.encrypt("file.txt", key=key)

Hashing

Cryptographic hash functions for file fingerprinting and integrity.

Algorithm	Digest Size	Description
sha256	256-bit	SHA-2 family (default)
sha384	384-bit	SHA-2 family
sha512	512-bit	SHA-2 family
sha3-256	256-bit	SHA-3 family
sha3-384	384-bit	SHA-3 family
sha3-512	512-bit	SHA-3 family
blake2b	512-bit	Modern, fast hash

from filanti.api import Filanti

# Hash bytes
result = Filanti.hash(b"Hello, Filanti!")
print(result.hash)

# Hash file with specific algorithm
result = Filanti.hash_file("document.pdf", algorithm="blake2b")

# Verify hash
is_valid = Filanti.verify_file_hash("document.pdf", expected_hash)

Integrity Verification

HMAC (Message Authentication Code)

Keyed integrity verification for detecting tampering.

Algorithm	Description
hmac-sha256	HMAC with SHA-256 (default)
hmac-sha384	HMAC with SHA-384
hmac-sha512	HMAC with SHA-512
hmac-sha3-256	HMAC with SHA3-256
hmac-blake2b	HMAC with BLAKE2b

from filanti.api import Filanti

# Compute MAC
key = Filanti.generate_key(32)
result = Filanti.mac_file("file.txt", key, create_file=True)

# Verify MAC (uses .mac metadata file)
is_valid = Filanti.verify_mac_file("file.txt", key)

Digital Signatures

Asymmetric signature operations for authenticity verification.

Algorithm	Description
ed25519	EdDSA with Curve25519 (default)
ecdsa-p256	ECDSA with P-256 curve
ecdsa-p384	ECDSA with P-384 curve
ecdsa-p521	ECDSA with P-521 curve

from filanti.api import Filanti

# Generate key pair
keypair = Filanti.generate_keypair(algorithm="ed25519", password="key-password")

# Sign file (creates .sig file)
Filanti.sign_file("document.pdf", keypair.private_key, create_file=True)

# Verify signature
is_valid = Filanti.verify_signature_file("document.pdf")

Checksums

Non-cryptographic checksums for detecting accidental corruption.

Algorithm	Description
crc32	CRC-32 (default)
adler32	Adler-32
xxhash64	XXHash 64-bit (fast)

⚠️ Note: Checksums are NOT cryptographically secure. Use for detecting accidental corruption only.

from filanti.api import Filanti

# Compute checksum
result = Filanti.checksum_file("file.txt", algorithm="crc32", create_file=True)

# Verify checksum
is_valid = Filanti.verify_checksum_file("file.txt")

Streaming Encryption

Memory-efficient processing of large files with progress callbacks.

from filanti.crypto.streaming import encrypt_stream_file, decrypt_stream_file

# Encrypt large file with progress
def progress(bytes_done, total):
    print(f"Progress: {bytes_done} bytes")

encrypt_stream_file(
    "large_file.bin",
    "large_file.bin.enc",
    key,
    chunk_size=64 * 1024,  # 64 KB chunks
    progress_callback=progress,
)

# Decrypt with streaming
decrypt_stream_file("large_file.bin.enc", "large_file.bin", key)

Plugin Architecture

Extend Filanti with custom algorithms without modifying core code.

from filanti.core.plugins import PluginRegistry, HashPlugin

class MyCustomHash(HashPlugin):
    name = "my-hash"
    digest_size = 32
    
    def hash(self, data: bytes) -> bytes:
        # Your implementation
        return custom_hash(data)

# Register plugin
PluginRegistry.register_hash(MyCustomHash())

# Use it
from filanti.api import Filanti
result = Filanti.hash(data, algorithm="my-hash")

Plugin Types:

• HashPlugin - Custom hash algorithms
• EncryptionPlugin - Custom encryption algorithms
• MACPlugin - Custom MAC algorithms
• SignaturePlugin - Custom signature algorithms
• ChecksumPlugin - Custom checksum algorithms
• KDFPlugin - Custom key derivation functions

Secure Memory Handling

Defense-in-depth memory protection for sensitive data.

from filanti.core.secure_memory import SecureBytes, SecureString

# Secure bytes handling
with SecureBytes(sensitive_data) as secure:
    process(secure.data)
# Data is automatically cleared

# Secure string handling
with SecureString("my-password") as pwd:
    use_password(pwd.value)
# Password is automatically cleared

ENV-Based Secrets

Secure secret injection for automation and CI/CD workflows. Avoid hardcoding passwords in scripts or command lines.

Supported Patterns:

Pattern	Description	Example
ENV:VAR	Unix-style (original)	ENV:MY_PASSWORD
$env:VAR	PowerShell-style	$env:MY_PASSWORD
${VAR}	Shell variable expansion	${MY_PASSWORD}
env.VAR	Dot notation (cross-platform)	env.MY_PASSWORD

import os
from filanti.api import Filanti

# Set secret in environment (done by CI/CD, Docker, etc.)
os.environ["ENCRYPT_PASSWORD"] = "my-secure-password"

# All patterns are supported
Filanti.encrypt("secret.txt", password="ENV:ENCRYPT_PASSWORD")      # Unix-style
Filanti.encrypt("secret.txt", password="$env:ENCRYPT_PASSWORD")     # PowerShell
Filanti.encrypt("secret.txt", password="${ENCRYPT_PASSWORD}")       # Shell-style
Filanti.encrypt("secret.txt", password="env.ENCRYPT_PASSWORD")      # Dot notation

# Load secrets from .env file
Filanti.load_dotenv(".env")
Filanti.encrypt("secret.txt", password="ENV:SECRET_FROM_DOTENV")

# Or load during encryption
Filanti.encrypt("secret.txt", password="ENV:MY_KEY", dotenv_path=".env")

# Check if value is an ENV reference
Filanti.is_env_reference("ENV:MY_SECRET")     # True
Filanti.is_env_reference("$env:MY_SECRET")    # True
Filanti.is_env_reference("${MY_SECRET}")      # True

# Resolve secret manually
password = Filanti.resolve_secret("ENV:ENCRYPT_PASSWORD")

# Redact secrets from output (for logging)
safe_text = Filanti.redact_secret("Password is secret123", "secret123")
# Returns: "Password is [REDACTED]"

# Create JSON-safe output with redacted secrets
data = {"password": "secret123", "user": "admin"}
safe = Filanti.safe_json_output(data, secret_keys=["password"])
# Returns: {"password": "[REDACTED]", "user": "admin"}

CLI Support:

# Set environment variable
export ENCRYPT_PASSWORD="my-secure-password"

# All pattern formats work in --password
filanti encrypt secret.txt --password ENV:ENCRYPT_PASSWORD
filanti encrypt secret.txt --password '$env:ENCRYPT_PASSWORD'  # PowerShell
filanti encrypt secret.txt --password '${ENCRYPT_PASSWORD}'    # Shell-style
filanti encrypt secret.txt --password env.ENCRYPT_PASSWORD     # Dot notation

# PowerShell-friendly --env option (no special characters)
filanti encrypt secret.txt --env ENCRYPT_PASSWORD
filanti decrypt secret.txt.enc --env ENCRYPT_PASSWORD

# Load from .env file
filanti encrypt secret.txt --dotenv .env --env-key MY_PASSWORD
filanti mac file.txt --dotenv secrets.env --env-key HMAC_KEY

# All secret-accepting commands support these options:
#   --password   Literal or ENV pattern
#   --env        Variable name (PowerShell-friendly)
#   --dotenv     Path to .env file
#   --env-key    Variable name from .env file

Benefits:

• Secrets don't appear in command line or process listings
• Works with CI/CD (GitHub Actions, GitLab CI, Jenkins)
• Compatible with Docker/Kubernetes secrets
• 12-factor app compliance
• PowerShell-native syntax support
• Cross-platform .env file loading

Secure File Deletion

Delete original files securely after encryption/decryption operations.

from filanti.api import Filanti

# Encrypt and securely delete original
Filanti.encrypt("secret.txt", password="my-pass", remove_source=True)
# Original file is securely overwritten before deletion

# Decrypt and remove encrypted file
Filanti.decrypt("secret.txt.enc", password="my-pass", remove_source=True)
# Encrypted file is securely deleted after decryption

# Use faster (non-secure) deletion
Filanti.encrypt("secret.txt", password="my-pass", 
                remove_source=True, secure_delete=False)

CLI Support:

# Encrypt and securely delete original
filanti encrypt secret.txt --password mypass --remove-source

# Decrypt and remove encrypted file
filanti decrypt secret.txt.enc --password mypass --remove-source

# Use faster (non-secure) deletion
filanti encrypt secret.txt --password mypass --remove-source --no-secure-delete

⚠️ Note: Secure deletion provides defense-in-depth but has limitations on SSDs with wear-leveling, journaling filesystems, and cloud-synced folders. For maximum security, use full-disk encryption.

Asymmetric / Hybrid Encryption

Public-key based encryption for secure file exchange between parties who don't share a secret key.

How it works:

1. Sender encrypts file with recipient's public key
2. A random session key is generated and encrypted for each recipient
3. Data is encrypted with fast symmetric AEAD (AES-256-GCM)
4. Recipient decrypts with their private key

Algorithm	Description	Key Type
x25519	Modern elliptic curve Diffie-Hellman (default)	256-bit
rsa-oaep	RSA with OAEP padding	2048/3072/4096-bit

Key Generation:

from filanti.api import Filanti

# Generate X25519 key pair (recommended)
keypair = Filanti.generate_asymmetric_keypair()
Filanti.save_asymmetric_keypair(keypair, "alice.pem")
# Creates: alice.pem (private) and alice.pub (public)

# Generate RSA key pair
keypair = Filanti.generate_asymmetric_keypair(
    algorithm="rsa-oaep",
    rsa_key_size=4096
)

# Generate with password protection
keypair = Filanti.generate_asymmetric_keypair(password="my-password")

Encryption & Decryption:

from filanti.api import Filanti

# Encrypt file for a recipient
Filanti.hybrid_encrypt("secret.txt", ["recipient.pub"])
# Creates: secret.txt.henc

# Encrypt for multiple recipients
Filanti.hybrid_encrypt(
    "secret.txt",
    ["alice.pub", "bob.pub", "charlie.pub"],
    recipient_ids=["alice", "bob", "charlie"]
)

# Decrypt with private key
Filanti.hybrid_decrypt("secret.txt.henc", "my-key.pem")

# Decrypt with password-protected key
Filanti.hybrid_decrypt(
    "secret.txt.henc",
    "my-key.pem",
    password="key-password"
)

# Get file metadata
info = Filanti.get_hybrid_file_info("secret.txt.henc")
print(f"Recipients: {info.recipient_count}")
print(f"Algorithm: {info.asymmetric_algorithm}")

Bytes Encryption:

from filanti.api import Filanti

# Encrypt bytes for recipients
encrypted = Filanti.hybrid_encrypt_bytes(
    b"secret data",
    ["recipient.pub"]
)

# Decrypt bytes
decrypted = Filanti.hybrid_decrypt_bytes(encrypted, "my-key.pem")

CLI Usage:

# Generate X25519 key pair
filanti keygen-asymmetric mykey

# Generate RSA key pair
filanti keygen-asymmetric mykey --algorithm rsa-oaep --rsa-size 4096

# Generate with password protection
filanti keygen-asymmetric mykey --protect

# Encrypt file for recipient
filanti encrypt-pubkey secret.txt --pubkey recipient.pub

# Encrypt for multiple recipients
filanti encrypt-pubkey secret.txt --pubkey alice.pub --pubkey bob.pub

# Decrypt with private key
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem

# Decrypt with password-protected key
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem --password "key-pass"

# Show hybrid file info
filanti info-hybrid secret.txt.henc

Use Cases:

• Secure file sharing - Send encrypted files without exchanging passwords
• Team collaboration - Encrypt for multiple team members at once
• End-to-end encryption - Each recipient uses their own private key
• Key escrow - Include backup recipient for recovery

---

CLI Reference

All CLI commands output JSON for automation and scripting.

General Commands

# Show version
filanti version

# List all supported algorithms
filanti list-algorithms

# Show supported hash algorithms
filanti algorithms

Hashing

# Hash a file (SHA-256 default)
filanti hash document.pdf

# Hash with specific algorithm
filanti hash document.pdf --algorithm sha512
filanti hash document.pdf -a blake2b

# Verify file hash
filanti verify document.pdf abc123...
filanti verify document.pdf abc123... --algorithm sha512

Encryption

# Encrypt with password (will prompt)
filanti encrypt secret.txt

# Encrypt with password argument
filanti encrypt secret.txt --password "my-password"

# Encrypt with ENV-based secret (recommended for automation)
export ENCRYPT_PASSWORD="my-secure-password"
filanti encrypt secret.txt --password ENV:ENCRYPT_PASSWORD

# Encrypt with specific algorithm
filanti encrypt secret.txt -p "password" --algorithm chacha20-poly1305

# Specify output path
filanti encrypt secret.txt -o encrypted_file.bin -p "password"

# Decrypt
filanti decrypt secret.txt.enc --password "my-password"

# Decrypt with ENV-based secret
filanti decrypt secret.txt.enc --password ENV:ENCRYPT_PASSWORD

filanti decrypt secret.txt.enc -o original.txt -p "password"

MAC (Integrity)

# Generate MAC with key
filanti mac file.txt --key "my-secret-key"

# Generate MAC with ENV-based secret (recommended)
export HMAC_KEY="my-hmac-secret-key"
filanti mac file.txt --key ENV:HMAC_KEY

# Generate MAC with hex key
filanti mac file.txt --key abc123def456...

# Create detached .mac file
filanti mac file.txt --key ENV:HMAC_KEY --create-file

# Verify MAC
filanti verify-mac file.txt --key ENV:HMAC_KEY
filanti verify-mac file.txt --key ENV:HMAC_KEY --mac-file file.txt.mac

Digital Signatures

# Generate key pair
filanti keygen my_signing_key

# Generate protected key pair (encrypted private key)
filanti keygen my_signing_key --protect
# (prompts for password)

# Generate with ENV-based password
filanti keygen my_signing_key --password ENV:KEY_PASSWORD

# Generate with specific algorithm
filanti keygen my_key --algorithm ecdsa-p384

# Sign a file
filanti sign document.pdf --key my_signing_key

# Sign with password-protected key
filanti sign document.pdf --key my_signing_key --password "key-password"

# Sign with ENV-based password (recommended for automation)
filanti sign document.pdf --key my_signing_key --password ENV:KEY_PASSWORD

# Sign without embedding public key
filanti sign document.pdf --key my_signing_key --no-embed-key

# Verify signature (uses embedded public key)
filanti verify-sig document.pdf

# Verify with external public key
filanti verify-sig document.pdf --key my_signing_key.pub

Checksums

# Compute checksum (CRC-32 default)
filanti checksum file.txt

# Compute with specific algorithm
filanti checksum file.txt --algorithm xxhash64

# Create detached .checksum file
filanti checksum file.txt --create-file

# Verify checksum
filanti verify-checksum file.txt --expected "0x1a2b3c4d"
filanti verify-checksum file.txt --checksum-file file.txt.checksum

Asymmetric / Hybrid Encryption

# Generate X25519 key pair (default)
filanti keygen-asymmetric mykey

# Generate with password protection
filanti keygen-asymmetric mykey --protect

# Generate RSA key pair
filanti keygen-asymmetric mykey --algorithm rsa-oaep --rsa-size 4096

# Generate with ENV-based password
filanti keygen-asymmetric mykey --password ENV:KEY_PASSWORD

# Encrypt file for recipient
filanti encrypt-pubkey secret.txt --pubkey recipient.pub

# Encrypt with specific algorithm
filanti encrypt-pubkey secret.txt --pubkey recipient.pub --algorithm rsa-oaep

# Encrypt for multiple recipients
filanti encrypt-pubkey secret.txt --pubkey alice.pub --pubkey bob.pub

# Encrypt with recipient IDs
filanti encrypt-pubkey secret.txt --pubkey alice.pub -r alice --pubkey bob.pub -r bob

# Specify output path
filanti encrypt-pubkey secret.txt --pubkey recipient.pub -o encrypted_file.henc

# Decrypt with private key
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem

# Decrypt with password-protected key
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem --password "key-pass"

# Decrypt with ENV-based password
filanti decrypt-privkey secret.txt.henc --privkey mykey.pem --password ENV:KEY_PASSWORD

# Show hybrid encrypted file metadata
filanti info-hybrid secret.txt.henc

---

Python SDK

Filanti Class

The Filanti class provides a unified high-level API for all operations.

from filanti.api import Filanti

Hashing Methods

Method	Description
Filanti.hash(data, algorithm)	Hash bytes data
Filanti.hash_file(path, algorithm)	Hash a file
Filanti.verify_hash(data, expected, algorithm)	Verify hash of bytes
Filanti.verify_file_hash(path, expected, algorithm)	Verify hash of file

Encryption Methods

Method	Description
Filanti.encrypt(path, password/key, output, algorithm)	Encrypt a file
Filanti.decrypt(path, password/key, output)	Decrypt a file
Filanti.encrypt_bytes(data, password/key, algorithm)	Encrypt bytes
Filanti.decrypt_bytes(data, password/key)	Decrypt bytes

Asymmetric / Hybrid Encryption Methods

Method	Description
Filanti.generate_asymmetric_keypair(algorithm, password, rsa_key_size)	Generate asymmetric key pair
Filanti.save_asymmetric_keypair(keypair, private_path, public_path)	Save key pair to files
Filanti.hybrid_encrypt(path, public_keys, output, algorithm)	Encrypt file for recipients
Filanti.hybrid_decrypt(path, private_key, output, password)	Decrypt hybrid encrypted file
Filanti.hybrid_encrypt_bytes(data, public_keys, algorithm)	Encrypt bytes for recipients
Filanti.hybrid_decrypt_bytes(data, private_key, password)	Decrypt hybrid encrypted bytes
Filanti.get_hybrid_file_info(path)	Get hybrid file metadata

Integrity Methods

Method	Description
Filanti.mac(data, key, algorithm)	Compute MAC of bytes
Filanti.mac_file(path, key, algorithm, create_file)	Compute MAC of file
Filanti.verify_mac(data, mac_value, key, algorithm)	Verify MAC of bytes
Filanti.verify_mac_file(path, key, mac_value/mac_file)	Verify MAC of file

Signature Methods

Method	Description
Filanti.generate_keypair(algorithm, password)	Generate key pair
Filanti.sign(data, private_key, algorithm, password)	Sign bytes
Filanti.sign_file(path, private_key, algorithm, password, create_file)	Sign file
Filanti.verify_signature(data, signature, public_key, algorithm)	Verify signature of bytes
Filanti.verify_signature_file(path, signature_file, public_key)	Verify signature of file

Checksum Methods

Method	Description
Filanti.checksum(data, algorithm)	Compute checksum of bytes
Filanti.checksum_file(path, algorithm, create_file)	Compute checksum of file
Filanti.verify_checksum(data, expected, algorithm)	Verify checksum of bytes
Filanti.verify_checksum_file(path, expected/checksum_file, algorithm)	Verify checksum of file

Utility Methods

Method	Description
Filanti.generate_key(size)	Generate random key
Filanti.derive_key(password, salt, algorithm)	Derive key from password
Filanti.algorithms()	Get all supported algorithms

Secrets Methods

Method	Description
Filanti.resolve_secret(value, allow_empty)	Resolve ENV:VAR_NAME to value
Filanti.is_env_reference(value)	Check if value is ENV reference
Filanti.redact_secret(text, secret)	Redact secret from text
Filanti.redact_secrets(text, secrets)	Redact multiple secrets
Filanti.safe_json_output(data, secrets, secret_keys)	Create JSON with redacted secrets

Direct Module Access

For more control, use the underlying modules directly:

# Hashing
from filanti.hashing import crypto_hash
digest = crypto_hash.hash_file("file.txt", "sha256")

# Encryption
from filanti.crypto import encrypt_file, decrypt_file
encrypt_file(input_path, output_path, key)

# Asymmetric/Hybrid Encryption
from filanti.crypto.asymmetric import (
    generate_asymmetric_keypair,
    hybrid_encrypt_file,
    hybrid_decrypt_file,
)
keypair = generate_asymmetric_keypair("x25519")
hybrid_encrypt_file(input_path, output_path, [keypair.public_key])

# Integrity
from filanti.integrity import compute_file_mac, verify_file_mac
mac = compute_file_mac("file.txt", key)

# Signatures
from filanti.integrity import generate_keypair, sign_file
keypair = generate_keypair("ed25519")
sign_file("file.txt", keypair.private_key)

# Streaming
from filanti.crypto.streaming import encrypt_stream_file
encrypt_stream_file(input_path, output_path, key)

# Secure Memory
from filanti.core.secure_memory import SecureBytes, secure_random_bytes
random = secure_random_bytes(32)

# Secrets
from filanti.core.secrets import resolve_secret, redact_secret
password = resolve_secret("ENV:MY_PASSWORD")
safe_output = redact_secret("Password is secret123", "secret123")

---

Module Dependencies

api/sdk.py
    ├── hashing/crypto_hash.py
    ├── crypto/encryption.py
    ├── crypto/decryption.py
    ├── crypto/asymmetric.py
    ├── crypto/kdf.py
    ├── crypto/key_management.py
    ├── integrity/mac.py
    ├── integrity/signature.py
    ├── integrity/checksum.py
    └── core/errors.py

cli/main.py
    └── (same dependencies as sdk.py)

---

Security Model

Threat Assumptions

Filanti is designed assuming:

• Host compromise is possible - Keys should be protected
• Files may be intercepted - All encryption is authenticated
• Password reuse may occur - Strong KDF with unique salts
• Timing attacks are a concern - Constant-time comparisons

Security Mitigations

Threat	Mitigation
Eavesdropping	Authenticated encryption (AES-GCM, ChaCha20-Poly1305)
Tampering	Authentication tags, HMAC, digital signatures
Replay attacks	Unique nonces per encryption
Password cracking	Argon2id with high memory cost
Timing attacks	Constant-time comparison (secrets.compare_digest)
Memory leaks	Secure memory zeroing
Algorithm confusion	Explicit algorithm selection

Best Practices

1. Use password-based encryption for user-facing features

   • Argon2id provides excellent protection against GPU/ASIC attacks

2. Use raw keys for server-to-server encryption

   • Generate keys with Filanti.generate_key(32)
   • Store keys securely (HSM, vault, secure key management)

3. Use hybrid encryption for secure file sharing

   • X25519 recommended for performance and security
   • Protect private keys with passwords
   • Multi-recipient encryption for team collaboration

4. Always verify signatures with trusted public keys

   • Don't rely solely on embedded public keys

5. Use HMAC for integrity when confidentiality isn't needed

   • Faster than signatures
   • Requires shared secret key

6. Use checksums only for accidental corruption

   • Not secure against malicious modification

---

Metadata Formats

Encrypted File Format

FLNT           # Magic bytes (4 bytes)
VERSION        # Format version (1 byte)
METADATA_LEN   # Metadata length (4 bytes)
METADATA_JSON  # Algorithm, nonce, salt, KDF params
CIPHERTEXT     # Encrypted data with auth tag

Hybrid Encrypted File Format (.henc)

FLAS           # Magic bytes (4 bytes) - "Filanti Asymmetric"
METADATA_LEN   # Metadata length (4 bytes)
METADATA_JSON  # Includes:
               #   - symmetric_algorithm
               #   - nonce
               #   - created_at
               #   - session_keys[] (one per recipient)
               #     - encrypted_key
               #     - ephemeral_public_key (X25519)
               #     - algorithm
               #     - recipient_id (optional)
CIPHERTEXT     # Encrypted data with auth tag

Detached Metadata Files

.mac File

{
  "version": "1.0",
  "algorithm": "hmac-sha256",
  "mac": "a1b2c3...",
  "filename": "document.pdf",
  "filesize": 12345,
  "created_at": "2026-01-16T12:00:00Z"
}

.sig File

{
  "version": "1.0",
  "algorithm": "ed25519",
  "signature": "d4e5f6...",
  "public_key": "-----BEGIN PUBLIC KEY-----...",
  "filename": "document.pdf",
  "filesize": 12345,
  "created_at": "2026-01-16T12:00:00Z"
}

.checksum File

{
  "version": "1.0",
  "algorithm": "crc32",
  "checksum": "0x1a2b3c4d",
  "filename": "document.pdf",
  "filesize": 12345,
  "created_at": "2026-01-16T12:00:00Z"
}

---

Error Handling

All Filanti exceptions inherit from FilantiError:

from filanti import (
    FilantiError,       
    FileOperationError, 
    HashingError,        
    ValidationError,     
    EncryptionError,     
    DecryptionError,     
    IntegrityError,      
    SignatureError,      
    SecretError,         
)

try:
    Filanti.decrypt("file.enc", password="wrong")
except DecryptionError as e:
    print(f"Decryption failed: {e}")
    print(f"Context: {e.context}")

# Handle missing ENV secrets
try:
    Filanti.encrypt("file.txt", password="ENV:MISSING_VAR")
except SecretError as e:
    print(f"Secret error: {e}")
    print(f"Missing variable: {e.env_var}")

---

Configuration

KDF Parameters

Adjust Argon2id parameters for security/performance trade-off:

from filanti.crypto.kdf import KDFParams, derive_key

# High-security settings (slower)
params = KDFParams(
    argon2_memory_cost=131072,  # 128 MiB
    argon2_time_cost=4,
    argon2_parallelism=4,
)

# Derive key with custom params
result = derive_key(password, salt, params)

Streaming Chunk Size

Optimize for memory vs. performance:

from filanti.crypto.streaming import encrypt_stream_file

# Larger chunks = faster, more memory
encrypt_stream_file(input_path, output_path, key, chunk_size=1024*1024)  # 1 MB

# Smaller chunks = slower, less memory
encrypt_stream_file(input_path, output_path, key, chunk_size=16*1024)   # 16 KB

---

Contributors || Acknowledgements

@stephenlb Thanks for the inspiration and guidance on encryption and security best practices.

Development Setup

git clone https://github.com/decliqe/FILANTI.git
cd filanti
pip install -e ".[dev]"

Changelog

v1.0.0 (2026-01-16)

License

MIT License

---

Made by Decliqe