FileVault

FileVault is a class for managing a hash directory tree of files on a filesystem.

A Vault will:

• Create a hash directory tree of custom depth
• Spread out files to keep CLI snappy when traversing the tree
• Scale to hundreds of thousands of files
• Obfuscate directory paths and filenames

How to Install

From GitLab

pip install git+https://git.unturf.com/engineering/unturf/filevault.git

From Source

git clone https://git.unturf.com/engineering/unturf/filevault.git
cd filevault
pip install .

How to Use

Creating a Vault

from filevault import Vault

# Default vault (creates a 'vault' directory in current working directory)
v = Vault()

# Custom vault
v = Vault(
    vaultpath="/tmp/for-test",  # Directory to store files
    depth=2,                    # Depth of directory structure
    salt="your-secret-salt"     # Change this for production!
)

Vault Parameters

• vaultpath: Where should the tree be created? (default: 'vault' in current directory)
• depth: How deep should the tree span? (default: 3 directories deep)
• salt: Custom salt for unique and secure hashing (default: 'changeme')

Examples

Create a hashed filename

# Create a consistent filename
filename = v.create_filename("my-document", ".pdf")
# Example: "3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.pdf"

# Get absolute path
abs_path = v.create_filename("my-document", ".pdf", absolute=True)
# Example: "/tmp/for-test/3/9/39938...e32.pdf"

Create a random filename

# Random filename
random_file = v.create_random_filename(".png")
# Example: "6/1/6169d6ee0ac0bc63ab667fb94d9cc747df0c03596ac43e24a51b3517d74bdc42.png"

Full Example

from filevault import Vault

# Create vault instance
v = Vault(vaultpath="/tmp/for-test", depth=2, salt="sugar")

# Create and print a filename
print(v.create_filename("my-first-file", ".png"))
# Output: 3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png

# Same input produces same output
print(v.create_filename("my-first-file", ".png"))
# Output: 3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png

# Get absolute path
print(v.create_filename("my-first-file", ".png", absolute=True))
# Output: /tmp/for-test/3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png

# Generate a random filename
print(v.create_random_filename())
# Output: 6/1/6169d6ee0ac0bc63ab667fb94d9cc747df0c03596ac43e24a51b3517d74bdc42

About the Salt

The salt parameter is used to add uniqueness and security to the generated file paths:

• Prevents easy guessing of file paths
• Makes directory traversal attacks more difficult
• Ensures different applications generate different paths for the same filenames

Important: Always change the default salt value in production environments.

License

This project is released into the Public Domain.

Original Author

Russell Ballestrini (russell@ballestrini.net)