jeslxdev/password-scrambler

Password scrambler: reversible time-bound Base64 shuffle + AEAD (XChaCha20-Poly1305) and Argon2id hasher.

dev-master 2025-09-03 23:50 UTC

Requires

• php: >=8.4
• ext-json: *
• ext-sodium: *

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0

MIT

• jeslxdev

README

Concise, production-focused PHP library for reversible, time-boxed password tokenization and secure password storage.

What this library provides

• Deterministic reversible "scrambling" of password strings: Base64 encode -> deterministic shuffle -> AEAD (XChaCha20-Poly1305).
• Time-boxed keys with TTL and grace window for key rotation.
• Compact, versioned token format (base64url JSON payload).
• Argon2id password hashing for long-term storage (recommended).
• A small PDO-backed repository to persist scrambled tokens without requiring callers to write SQL.

Requirements

• PHP >= 8.4
• ext-sodium
• ext-json
• PDO + appropriate driver for your DB (SQLite or MySQL supported by repository code)

Quick usage

1. Create key descriptor and key store

use JeslxDev\PasswordScrambler\KeyStore\KeyDescriptor;
use JeslxDev\PasswordScrambler\KeyStore\InMemoryKeyStore;

$master = random_bytes(32);
$kid = substr(bin2hex(sodium_crypto_generichash($master, '', 16)), 0, 8);
$desc = new KeyDescriptor($kid, base64_encode($master), time(), 86400);
$store = new InMemoryKeyStore([$desc]);

1. Encrypt / decrypt

use JeslxDev\PasswordScrambler\Cipher\PasswordCipher;
use JeslxDev\PasswordScrambler\Cipher\CipherConfig;

$cipher = new PasswordCipher($store, new CipherConfig());
$token = $cipher->encrypt('my-plain-password');
$plain = $cipher->decrypt($token);

1. Store tokens with PasswordManager (optional)

use JeslxDev\PasswordScrambler\Storage\DBConfig;
use JeslxDev\PasswordScrambler\Storage\Database;
use JeslxDev\PasswordScrambler\Service\PasswordManagerFactory;

$db = new Database(new DBConfig('sqlite:/path/to/file.db'));
$manager = PasswordManagerFactory::createFromDbAndKeyStore($db, $store);
$manager->store('user-id', 'my-plain-password');

Migration

• A minimal migration helper is available at bin/migrate.php. It creates a user_passwords table for SQLite or MySQL.
• For production use, prefer a dedicated migration tool (Phinx, Doctrine Migrations, Flyway, etc.).

Security notes

• Never commit master key material. Keep keys in an HSM or a secrets manager when possible.
• The reversible token is intended for workflows that need restoration for a limited time; prefer one-way hashing (Argon2id) when possible.

Testing

• Unit tests: PHPUnit. An integration test uses SQLite in-memory and will be skipped if the PDO sqlite driver is not present.

License

• MIT