# FileVault

[![pipeline status](https://git.unturf.com/engineering/unturf/filevault/badges/main/pipeline.svg)](https://git.unturf.com/engineering/unturf/filevault/-/commits/main)
[![license](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://en.wikipedia.org/wiki/Public_domain)

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
```bash
pip install git+https://git.unturf.com/engineering/unturf/filevault.git
```

### From Source
```bash
git clone https://git.unturf.com/engineering/unturf/filevault.git
cd filevault
pip install .
```

## How to Use

### Creating a Vault

```python
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
```python
# 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
```python
# Random filename
random_file = v.create_random_filename(".png")
# Example: "6/1/6169d6ee0ac0bc63ab667fb94d9cc747df0c03596ac43e24a51b3517d74bdc42.png"
```

## Full Example

```python
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](https://en.wikipedia.org/wiki/Public_domain).

## Original Author

Russell Ballestrini ([russell@ballestrini.net](mailto:russell@ballestrini.net))