README

Effectra\Security is a modern PHP library that provides secure hashing, password management, CSRF token handling, JWT generation, and two-way authenticated encryption using PHP 8.1+ features.

Features

Hashing: Securely hash data using various algorithms with enums.
Password Management: Generate and verify hashed passwords using secure defaults like Argon2id.
CSRF Protection: Generate and validate CSRF tokens, designed for Dependency Injection containers.
Token Generation: Create and decode JSON Web Tokens (JWT) using typed configurations.
Encryption: Two-way authenticated encryption/decryption using Sodium (XChaCha20-Poly1305).

Requirements

PHP 8.1 or higher
ext-sodium extension

Installation

Install the library via Composer:

composer require effectra/security

Usage

Encryption (New!)

The Encryption class provides secure two-way authenticated encryption using Sodium.

use Effectra\Security\Encryption;

// Generate a secure key (save this key securely!)
$key = Encryption::generateKey();

$data = 'sensitive information';

// Encrypt data
$encrypted = Encryption::encrypt($data, $key);

// Decrypt data
$decrypted = Encryption::decrypt($encrypted, $key);

Hashing

The Hash class provides methods for hashing data using HMAC algorithms.

use Effectra\Security\Hash;
use Effectra\Security\Enums\HashAlgo;

$data = 'Hello, World!';
$key = 'secret-key';

Hash::setAlgo(HashAlgo::SHA256);
$hash = Hash::set($data, $key);

if (Hash::verify($hash, $hash)) {
    echo "Hash is valid.";
}

Password Management

The Hash class securely manages passwords using Argon2id by default.

use Effectra\Security\Hash;

$password = 'password123';

$hashedPassword = Hash::setPassword($password);

if (Hash::verifyPassword($password, $hashedPassword)) {
    echo "Password is valid.";
}

CSRF Protection

The Csrf class generates and validates CSRF tokens.

use Effectra\Security\Csrf;
use Effectra\Session\Session; // Replace with your own session implementation

$session = new Session();
$csrf = new Csrf($session);

// Insert hidden token in HTML forms
$html = '<form method="POST">';
$html .= $csrf->insertHiddenToken();
$html .= '<button type="submit">Submit</button>';
$html .= '</form>';

echo $html;

// Validate on submission
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // Pass $_POST explicitly for DI container compatibility, or leave null to read directly
    $csrf = new Csrf($session, [], $_POST);
    
    if ($csrf->validate()) {
        echo "CSRF valid.";
    }
}

Token Generation (JWT)

The Token class uses strongly-typed TokenConfig for JSON Web Tokens.

use Effectra\Security\Token;
use Effectra\Security\Config\TokenConfig;

$data = ['user_id' => 123];

$config = new TokenConfig(
    key: 'your-secret-key',
    issuedAt: time(),
    expirationTime: time() + 3600,
    issuer: 'example.com'
);

$token = new Token();
$token->config($config);

// Create token
$jwt = $token->set($data);
echo $jwt;

// Read and decode token
$decoded = $token->get($jwt);

// Validate time
if ($token->validateTime($decoded)) {
    echo "Token is within valid time.";
}

Contributing

Contributions are welcome! Feel free to submit bug reports, feature requests, or pull requests on the GitHub repository.

License

Effectra\Security is licensed under the MIT License.

effectra / security

Maintainers

Package info

Statistics

Security