Encryption

Encrypt and decrypt HCL configuration files for secure storage and deployment using Laravel’s Encrypter with AES-256-CBC.

Use cases: Encrypting sensitive configs at rest, storing encrypted configs in version control, and decrypting during deployment.

Basic Encryption

use Cline\Huckle\Facades\Huckle;

// Encrypt a configuration file (generates a new key)
$result = Huckle::encrypt('/path/to/credentials.hcl');

// $result contains:
// [
//     'path' => '/path/to/credentials.hcl.encrypted',  // The encrypted file
//     'key'  => 'base64:ABC123...',                    // Store this securely!
// ]

Caution

Save the key securely (environment variable, secret manager, etc.). You’ll need it to decrypt the file later.

Decryption

// Decrypt using the key from encryption
$decryptedPath = Huckle::decrypt(
    '/path/to/credentials.hcl.encrypted',
    'base64:ABC123...',  // The key from encrypt()
);

// Returns: '/path/to/credentials.hcl' (original filename without .encrypted)

Using a Custom Key

// Generate your own key (must be valid for AES-256-CBC = 32 bytes)
$myKey = 'base64:' . base64_encode(random_bytes(32));

// Encrypt with your key
$result = Huckle::encrypt('/path/to/config.hcl', $myKey);

// Decrypt with the same key
Huckle::decrypt('/path/to/config.hcl.encrypted', $myKey);

Force Overwrite

// By default, decrypt() throws if the target file already exists
// Use force: true to overwrite
$decryptedPath = Huckle::decrypt(
    '/path/to/credentials.hcl.encrypted',
    $key,
    force: true,
);

Custom Cipher

// Use a different cipher (default is AES-256-CBC)
$result = Huckle::encrypt(
    '/path/to/config.hcl',
    cipher: 'AES-128-CBC',  // 16-byte key
);

// Decrypt with matching cipher
Huckle::decrypt(
    '/path/to/config.hcl.encrypted',
    $result['key'],
    cipher: 'AES-128-CBC',
);

CLI Commands

# Encrypt a file (generates and displays key)
php artisan huckle:encrypt config/credentials.hcl

# Encrypt with a specific key
php artisan huckle:encrypt config/credentials.hcl --key="base64:ABC123..."

# Encrypt using APP_KEY
php artisan huckle:encrypt config/credentials.hcl --app-key

# Encrypt and delete original
php artisan huckle:encrypt config/credentials.hcl --prune

# Decrypt a file
php artisan huckle:decrypt config/credentials.hcl.encrypted --key="base64:ABC123..."

# Decrypt using APP_KEY
php artisan huckle:decrypt config/credentials.hcl.encrypted --app-key

# Decrypt with force overwrite
php artisan huckle:decrypt config/credentials.hcl.encrypted --key="..." --force

# Decrypt to custom path
php artisan huckle:decrypt config/credentials.hcl.encrypted --key="..." --path=/var/www/config

# Decrypt with custom filename
php artisan huckle:decrypt config/credentials.hcl.encrypted --key="..." --filename=decrypted.hcl

# Use custom cipher
php artisan huckle:encrypt config/credentials.hcl --cipher=AES-128-CBC
php artisan huckle:decrypt config/credentials.hcl.encrypted --key="..." --cipher=AES-128-CBC

# Environment-specific encryption (suffix style)
php artisan huckle:encrypt config/credentials.hcl --env=production
php artisan huckle:decrypt config/credentials.hcl --key="..." --env=production

# Environment-specific encryption (directory style)
php artisan huckle:encrypt config/credentials.hcl --env=production --env-style=directory
php artisan huckle:decrypt config/credentials.hcl --key="..." --env=production --env-style=directory

Environment-Specific Files

Suffix Style (Default)

Suffix style transforms config.hcl → config.production.hcl. This matches Laravel’s .env pattern.

$result = Huckle::encrypt(
    '/path/to/config.hcl',
    env: 'production',  // Encrypts /path/to/config.production.hcl
);

// Decrypts /path/to/config.production.hcl.encrypted
Huckle::decrypt(
    '/path/to/config.hcl',
    $result['key'],
    env: 'production',
);

Directory Style

Directory style transforms config/credentials/db.hcl → config/credentials/production/db.hcl. Perfect for organizing configs in environment subdirectories.

$result = Huckle::encrypt(
    '/path/to/config/credentials/db.hcl',
    env: 'production',
    envStyle: 'directory',
);

Huckle::decrypt(
    '/path/to/config/credentials/db.hcl',
    $result['key'],
    env: 'production',
    envStyle: 'directory',
);

Prune Option

Delete the source file after the operation completes.

// Delete the original file after encryption
$result = Huckle::encrypt('/path/to/credentials.hcl', prune: true);
// /path/to/credentials.hcl is deleted, only .encrypted remains

// Delete the encrypted file after decryption
Huckle::decrypt('/path/to/credentials.hcl.encrypted', $key, prune: true);
// .encrypted file is deleted, only decrypted file remains

Custom Output Location

// Output to a different directory
$decryptedPath = Huckle::decrypt(
    '/path/to/credentials.hcl.encrypted',
    $key,
    path: '/var/www/app/config',
);
// Returns: /var/www/app/config/credentials.hcl

// Use a custom filename
$decryptedPath = Huckle::decrypt(
    '/path/to/credentials.hcl.encrypted',
    $key,
    filename: 'decrypted-credentials.hcl',
);
// Returns: /path/to/decrypted-credentials.hcl

// Combine path and filename
$decryptedPath = Huckle::decrypt(
    '/path/to/credentials.hcl.encrypted',
    $key,
    path: '/var/www/app/config',
    filename: 'app-credentials.hcl',
);
// Returns: /var/www/app/config/app-credentials.hcl

Directory Encryption

Encrypt all files in a directory with a single key. Perfect for encrypting entire config directories like .huckle/.

use Cline\Huckle\Facades\Huckle;

// Encrypt all files in a directory
$result = Huckle::encryptDirectory('/path/to/.huckle');

// $result contains:
// [
//     'files' => [
//         ['path' => '/path/to/.huckle/config.hcl.encrypted', 'key' => '...'],
//         ['path' => '/path/to/.huckle/secrets.hcl.encrypted', 'key' => '...'],
//     ],
//     'key' => 'base64:ABC123...',  // Same key for all files
// ]

Recursive Directory Encryption

// Encrypt files in subdirectories too
$result = Huckle::encryptDirectory(
    '/path/to/.huckle',
    recursive: true,
);

Filter Files with Glob Pattern

// Only encrypt HCL files
$result = Huckle::encryptDirectory(
    '/path/to/.huckle',
    glob: '*.hcl',
);

// Encrypt HCL files recursively
$result = Huckle::encryptDirectory(
    '/path/to/.huckle',
    recursive: true,
    glob: '*.hcl',
);

Directory Decryption

// Decrypt all .encrypted files in directory
$decryptedPaths = Huckle::decryptDirectory(
    '/path/to/.huckle',
    'base64:ABC123...',  // Key from encryptDirectory()
);

// Returns array of decrypted file paths:
// ['/path/to/.huckle/config.hcl', '/path/to/.huckle/secrets.hcl']

// Recursive decryption
$decryptedPaths = Huckle::decryptDirectory(
    '/path/to/.huckle',
    $key,
    recursive: true,
);

Prune and Force Options

// Delete originals after encryption
$result = Huckle::encryptDirectory(
    '/path/to/.huckle',
    prune: true,
);

// Overwrite existing encrypted files
$result = Huckle::encryptDirectory(
    '/path/to/.huckle',
    force: true,
);

// Delete encrypted files after decryption, overwrite existing
$decryptedPaths = Huckle::decryptDirectory(
    '/path/to/.huckle',
    $key,
    prune: true,
    force: true,
);

CLI Commands for Directories

# Encrypt directory
php artisan huckle:encrypt .huckle

# Encrypt recursively with glob filter
php artisan huckle:encrypt .huckle --recursive --glob='*.hcl'

# Delete originals after encryption
php artisan huckle:encrypt .huckle --recursive --prune

# Decrypt directory
php artisan huckle:decrypt .huckle --key="base64:ABC123..."

# Decrypt recursively with force
php artisan huckle:decrypt .huckle --key="..." --recursive --force