Yukkai Vault Tool — Folder Encryption

What is it?

The Yukkai Vault Tool encrypts entire folders on your Mac using AES-256-GCM authenticated encryption — the same standard trusted by banks and governments. Your files are locked into a single .yukkaivault archive that cannot be opened without the correct credentials.

You choose how to authenticate: a passphrase, a BIP-39 mnemonic phrase, your fingerprint via TouchID, or any combination of these. An optional Shamir's Secret Sharing scheme splits the key across multiple recovery fragments so that no single fragment alone can unlock the vault — ideal for team or family scenarios.

How it works

1. Encryption — The tool reads every file inside the source folder, encrypts them with AES-256-GCM, and writes a single .yukkaivault archive. The original files are not modified or deleted.
2. Decryption — Given the correct credentials, the tool reads the .yukkaivault archive and restores all files to an output folder.
3. Inspection — You can read a vault's metadata (name, auth methods, fragment settings) at any time without decrypting or needing credentials.
4. Shamir Fragmentation — When enabled, the master key is split into N fragments using a threshold scheme (e.g., 2-of-3, 3-of-5, 4-of-7). Any K fragments must be collected to reconstruct the key and decrypt.

How to use it

Encrypt a folder

Parameter	Required	Description
action	✅	encrypt
source_path	✅	Path to the folder to encrypt
name	✅	A label for the vault (shown in metadata)
auth_methods	✅	One or more of: passphrase, bip39, touchid (combine with +, e.g. touchid+bip39)
passphrase	If using passphrase	At least 12 characters
bip39_word_count	Optional	15, 18, 21, or 24 words (default 15)
fragment_preset	Optional	none (default), 2of3, 3of5, 4of7

⚠️ TouchID requires a biometric prompt on your Mac. You must be present to confirm via fingerprint.

Decrypt a vault

Parameter	Required	Description
action	✅	decrypt
vault_path	✅	Path to the .yukkaivault or .yukkaifrag file
output_path	✅	Where to restore the decrypted files
passphrase	If passphrase was used	The passphrase you set during encryption
mnemonic	If BIP-39 was used	The recovery phrase
fragment_paths	If using Shamir	JSON array of fragment file paths

Inspect a vault

Parameter	Required	Description
action	✅	inspect
vault_path	✅	Path to the .yukkaivault file

Returns metadata without decrypting — no credentials needed.

Generate a password

Parameter	Required	Description
action	✅	generate_password
length	Optional	Password length (default 24)
include_special	Optional	Include special characters (default true)

Generate a BIP-39 mnemonic

Parameter	Required	Description
action	✅	generate_mnemonic
word_count	Optional	15, 18, 21, or 24 (default 15)

Examples

Example 1 — Simple passphrase encryption

Encrypt the folder ~/Documents/Financials
Name it: financial-vault
Auth method: passphrase
Passphrase: MyStr0ng!Passphrase

This creates financial-vault.yukkaivault containing all encrypted files.

Example 2 — TouchID + BIP-39 with Shamir 2-of-3

Encrypt the folder ~/Projects/seeds
Name it: seeds-vault
Auth method: touchid+bip39
BIP-39 word count: 24
Fragment preset: 2of3

The tool generates a 24-word mnemonic, encrypts the folder, and produces 3 fragment files. You need any 2 of them plus the mnemonic (or TouchID) to decrypt.

Example 3 — Decrypt with a passphrase

Decrypt the vault ~/Desktop/financial-vault.yukkaivault
Output to: ~/Documents/restored
Passphrase: MyStr0ng!Passphrase

Example 4 — Decrypt with Shamir fragments

Decrypt using fragments:
  ~/frag1.yukkaifrag
  ~/frag2.yukkaifrag
Output to: ~/Documents/restored

Provide at least 2 fragment paths for a 2-of-3 scheme.

Example 5 — Inspect without decrypting

Inspect ~/Desktop/financial-vault.yukkaivault

Returns the vault name, auth methods, and fragment configuration.

Tips & best practices

• Always back up your credentials. If you lose your passphrase or BIP-39 mnemonic, there is no way to recover the vault. Store them in a separate, secure location (e.g., a password manager).
• Use multi-factor auth. Combine touchid+bip39 so that you can unlock with your fingerprint but still recover via mnemonic if your Mac is lost or replaced.
• Shamir fragments add resilience. Distribute fragments across different physical locations or trusted people. With 2-of-3, one fragment can be lost without losing access.
• 24-word mnemonics are stronger. If maximum security matters, choose bip39_word_count: 24. The default 15 is still strong but shorter.
• Inspect before decrypting. Use inspect to confirm a vault's auth methods and fragment settings before attempting decryption — it saves time and avoids failed attempts.
• Generate strong passwords. Use the built-in generate_password tool rather than inventing your own. The default length of 24 with special characters provides excellent entropy.
• Encryption does not delete originals. After encrypting, you may want to securely delete the source folder. The tool leaves your original files untouched.
• Keep .yukkaivault and .yukkaifrag files safe. These are your encrypted data. Without them, even the correct passphrase cannot restore your files.
• Test decryption immediately. After creating a vault, try decrypting it to a temporary folder to verify everything works before relying on it for critical backups.