PHPackages azaharizaman/nexus-crypto - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. azaharizaman/nexus-crypto ActiveLibrary[Security](/categories/security) azaharizaman/nexus-crypto ========================= Framework-agnostic cryptographic abstraction layer with post-quantum readiness for ERP system v0.1.0-alpha1(1mo ago)027MITPHPPHP ^8.3 Since May 5Pushed 1mo agoCompare [ Source](https://github.com/azaharizaman/nexus-crypto)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-crypto)[ RSS](/packages/azaharizaman-nexus-crypto/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (3)Versions (2)Used By (7) Nexus\\Crypto ============= [](#nexuscrypto) Framework-agnostic cryptographic abstraction layer providing **algorithm agility** and **post-quantum readiness** for the Nexus ERP ecosystem. Overview -------- [](#overview) The **Nexus\\Crypto** package provides a complete cryptographic primitive library designed for long-term security and future-proofing against quantum computing threats. By abstracting all cryptographic operations behind interfaces, the package enables seamless migration from classical algorithms (RSA, ECDSA, AES) to post-quantum alternatives (Dilithium, Kyber) simply by changing bindings in the application layer. ### Core Principles [](#core-principles) 1. **Algorithm Agility**: All crypto operations via interfaces, enabling algorithm swapping without code changes 2. **Post-Quantum Readiness**: Hybrid mode support planned for dual classical + PQC signing/encryption 3. **Stateless Design**: All persistence via `KeyStorageInterface` - no framework dependencies 4. **Immutable Value Objects**: All cryptographic results as readonly data structures 5. **Audit Trail**: All operations compatible with `Nexus\AuditLogger` for compliance Features -------- [](#features) ### Phase 1 (Current - Classical Algorithms) [](#phase-1-current---classical-algorithms) - **Hashing**: SHA-256/384/512, BLAKE2b via Sodium - **Symmetric Encryption**: AES-256-GCM (authenticated), ChaCha20-Poly1305 - **Asymmetric Signing**: Ed25519, RSA-2048/4096, ECDSA P-256, HMAC-SHA256 - **Key Management**: Envelope encryption, automated rotation via Scheduler - **Feature Flags**: Gradual rollout support with `CRYPTO_LEGACY_MODE` ### Phase 2 (Planned - Hybrid PQC) [](#phase-2-planned---hybrid-pqc) - **Hybrid Signing**: Dual ECDSA + Dilithium signatures - **Hybrid KEM**: Dual X25519 + Kyber key encapsulation - **Transparent Migration**: Existing code works unchanged ### Phase 3 (Future - Pure PQC) [](#phase-3-future---pure-pqc) - **Pure PQC Algorithms**: ML-DSA, ML-KEM (NIST standards) - **Classical Deprecation**: Full quantum-resistant operation Installation ------------ [](#installation) ``` composer require azaharizaman/nexus-crypto ``` ### Required PHP Extensions [](#required-php-extensions) ``` php -m | grep -E "(sodium|openssl)" ``` - **ext-sodium**: Required for modern algorithms (ChaCha20, Ed25519, BLAKE2b) - **ext-openssl**: Required for legacy algorithms (RSA, AES-CBC) ### Integration Requirements [](#integration-requirements) Consuming applications must implement: 1. **`KeyStorageInterface`** - For persistent key storage 2. **Service Container Bindings** - Bind all crypto interfaces 3. **Master Key Management** - Secure master key for envelope encryption 4. **(Optional)** **Scheduler Integration** - For automated key rotation Architecture ------------ [](#architecture) ``` ┌─────────────────────────────────────────────────────────────────┐ │ CONSUMING PACKAGE │ │ (e.g., Nexus\Export, Nexus\Connector, Nexus\Finance) │ │ │ │ Calls: $crypto->encrypt(data) │ │ Calls: $crypto->sign(data) │ │ Consumes: HashResult, EncryptedData, SignedData │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ NEXUS\CRYPTO (THIS PACKAGE) │ │ │ │ CryptoManager ──► HasherInterface │ │ │ SymmetricEncryptorInterface │ │ │ AsymmetricSignerInterface │ │ │ KeyGeneratorInterface │ │ └──► KeyStorageInterface │ │ │ │ Enums: HashAlgorithm, SymmetricAlgorithm, AsymmetricAlgorithm │ │ Value Objects: HashResult, EncryptedData, SignedData, KeyPair │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ APPLICATION LAYER (Consuming App) │ │ │ │ KeyStorage Implementation ─► Database/Redis/Filesystem │ │ Service Bindings ─► IoC Container (Laravel/Symfony) │ │ Master Key Management ─► Secure configuration │ │ KeyRotationHandler ─► Scheduler integration (optional) │ └─────────────────────────────────────────────────────────────────┘ ``` Usage ----- [](#usage) ### 1. Hash Data (Integrity Checking) [](#1-hash-data-integrity-checking) ``` use Nexus\Crypto\Services\CryptoManager; use Nexus\Crypto\Enums\HashAlgorithm; $crypto = app(CryptoManager::class); // Hash with default SHA-256 $result = $crypto->hash('sensitive data'); // HashResult(hash: '5d41...', algorithm: SHA256, salt: null) // Hash with specific algorithm $result = $crypto->hash('sensitive data', HashAlgorithm::BLAKE2B); // Verify hash if ($crypto->verifyHash('sensitive data', $result)) { // Data integrity confirmed } ``` ### 2. Encrypt Data (Symmetric Encryption) [](#2-encrypt-data-symmetric-encryption) ``` use Nexus\Crypto\Enums\SymmetricAlgorithm; // Encrypt with default AES-256-GCM $encrypted = $crypto->encrypt('confidential information'); // EncryptedData( // ciphertext: '8f3a...', // iv: '4b2c...', // tag: '9d1e...', // algorithm: AES256GCM, // metadata: [] // ) // Decrypt $plaintext = $crypto->decrypt($encrypted); // Encrypt with specific key $keyId = 'tenant-123-finance'; $encrypted = $crypto->encryptWithKey('payroll data', $keyId); $plaintext = $crypto->decryptWithKey($encrypted, $keyId); ``` ### 3. Sign Data (Digital Signatures) [](#3-sign-data-digital-signatures) ``` use Nexus\Crypto\Enums\AsymmetricAlgorithm; // Generate key pair $keyPair = $crypto->generateKeyPair(AsymmetricAlgorithm::ED25519); // Sign data $signed = $crypto->sign('financial report', $keyPair->privateKey); // SignedData( // data: 'financial report', // signature: 'a8f3...', // algorithm: ED25519, // publicKey: '7b2c...' // ) // Verify signature if ($crypto->verifySignature($signed)) { // Signature valid - data authentic and unmodified } ``` ### 4. HMAC Signing (Webhook Verification) [](#4-hmac-signing-webhook-verification) ``` // Generate HMAC signature $signature = $crypto->hmac($payload, $secret); // Verify HMAC if ($crypto->verifyHmac($payload, $signature, $secret)) { // Webhook authentic } ``` ### 5. Key Rotation (Automated via Scheduler) [](#5-key-rotation-automated-via-scheduler) ``` // Manual rotation $newKey = $crypto->rotateKey('tenant-123-finance'); // Automated rotation (configured in CryptoServiceProvider) // KeyRotationHandler checks all keys daily and rotates expired ones // Based on expiresAt field in EncryptionKey value object ``` Value Objects ------------- [](#value-objects) ### HashResult [](#hashresult) ``` final readonly class HashResult { public function __construct( public string $hash, // Hex-encoded hash public HashAlgorithm $algorithm, // Algorithm used public ?string $salt = null // Optional salt (for KDF) ) {} public function toArray(): array; public static function fromArray(array $data): self; } ``` ### EncryptedData [](#encrypteddata) ``` final readonly class EncryptedData { public function __construct( public string $ciphertext, // Base64-encoded encrypted data public string $iv, // Initialization vector public string $tag, // Authentication tag (GCM/Poly1305) public SymmetricAlgorithm $algorithm, // Algorithm used public array $metadata = [] // Additional context ) {} public function toArray(): array; public static function fromArray(array $data): self; } ``` ### SignedData [](#signeddata) ``` final readonly class SignedData { public function __construct( public string $data, // Original data public string $signature, // Signature bytes public AsymmetricAlgorithm $algorithm, // Algorithm used public ?string $publicKey = null // Public key (optional) ) {} public function isQuantumResistant(): bool; // Check if PQC algorithm public function toArray(): array; public static function fromArray(array $data): self; } ``` ### KeyPair [](#keypair) ``` final readonly class KeyPair { public function __construct( public string $publicKey, // Base64-encoded public key public string $privateKey, // Base64-encoded private key public AsymmetricAlgorithm $algorithm // Algorithm used ) {} } ``` ### EncryptionKey [](#encryptionkey) ``` final readonly class EncryptionKey { public function __construct( public string $key, // Base64-encoded key material public SymmetricAlgorithm $algorithm, // Algorithm public DateTimeImmutable $createdAt, public ?DateTimeImmutable $expiresAt = null ) {} public function isExpired(ClockInterface $clock): bool; } ``` Enums ----- [](#enums) ### HashAlgorithm [](#hashalgorithm) ``` enum HashAlgorithm: string { case SHA256 = 'sha256'; case SHA384 = 'sha384'; case SHA512 = 'sha512'; case BLAKE2B = 'blake2b'; public function isQuantumResistant(): bool; public function getSecurityLevel(): int; // Bits (e.g., 256) } ``` ### SymmetricAlgorithm [](#symmetricalgorithm) ``` enum SymmetricAlgorithm: string { case AES256GCM = 'aes-256-gcm'; case AES256CBC = 'aes-256-cbc'; case CHACHA20POLY1305 = 'chacha20-poly1305'; public function isAuthenticated(): bool; // GCM/Poly1305 = true public function requiresIV(): bool; public function getKeyLength(): int; // Bytes } ``` ### AsymmetricAlgorithm [](#asymmetricalgorithm) ``` enum AsymmetricAlgorithm: string { case HMACSHA256 = 'hmac-sha256'; case ED25519 = 'ed25519'; case RSA2048 = 'rsa-2048'; case RSA4096 = 'rsa-4096'; case ECDSAP256 = 'ecdsa-p256'; // Phase 2 (stubs for now) case DILITHIUM3 = 'dilithium3'; case KYBER768 = 'kyber768'; public function isQuantumResistant(): bool; public function getSecurityLevel(): int; } ``` Security Considerations ----------------------- [](#security-considerations) ### Envelope Encryption [](#envelope-encryption) All data encryption keys (DEKs) are encrypted with the master key (`APP_KEY`) before storage: ``` Plaintext → Encrypt with DEK → Ciphertext DEK → Encrypt with Master Key → Encrypted DEK (stored in database) ``` ### Key Rotation [](#key-rotation) - **Automated**: `KeyRotationHandler` runs daily via `Nexus\Scheduler` - **Frequency**: 90-day default (configurable) - **Audit Trail**: All rotations logged to `key_rotation_history` - **Zero Downtime**: Old keys retained for decryption of existing data ### Algorithm Selection [](#algorithm-selection) ``` // Recommended defaults (Phase 1) HashAlgorithm::SHA256 // General hashing SymmetricAlgorithm::AES256GCM // Data encryption (authenticated) AsymmetricAlgorithm::ED25519 // Digital signatures (fast) // Legacy support SymmetricAlgorithm::AES256CBC // Backward compatibility AsymmetricAlgorithm::RSA2048 // Standards compliance ``` Error Handling -------------- [](#error-handling) ``` use Nexus\Crypto\Exceptions\{ EncryptionException, DecryptionException, SignatureException, InvalidKeyException, UnsupportedAlgorithmException, FeatureNotImplementedException }; try { $encrypted = $crypto->encrypt($data); } catch (EncryptionException $e) { // Handle encryption failure $logger->error('Encryption failed', ['error' => $e->getMessage()]); } try { $signed = $hybridSigner->sign($data); // Phase 2 feature } catch (FeatureNotImplementedException $e) { // Fall back to classical signing $signed = $crypto->sign($data); } ``` Performance ----------- [](#performance) ### Benchmarks (Phase 1 - Classical Algorithms) [](#benchmarks-phase-1---classical-algorithms) OperationAlgorithmInput SizeTargetActualHashSHA-2561 KB< 1ms~0.3msHashBLAKE2b1 KB< 1ms~0.2msEncryptAES-256-GCM1 KB< 2ms~0.8msDecryptAES-256-GCM1 KB< 2ms~0.9msSignEd255191 KB< 5ms~1.2msVerifyEd255191 KB< 5ms~1.5ms*Benchmarks on PHP 8.3, ext-sodium 2.0.23* Roadmap ------- [](#roadmap) ### ✅ Phase 1: Classical Algorithms (Q4 2025) [](#-phase-1-classical-algorithms-q4-2025) - Core interfaces and value objects - Sodium-based implementations - Key rotation handler - Feature flag support - Legacy code refactoring ### 🔄 Phase 2: Hybrid PQC Mode (Q3 2026) [](#-phase-2-hybrid-pqc-mode-q3-2026) - Monitor liboqs-php maturity - Implement `HybridSignerInterface` - Implement `HybridKEMInterface` - Dual signature verification - Migration tooling ### 🔮 Phase 3: Pure PQC (Post-2027) [](#-phase-3-pure-pqc-post-2027) - NIST ML-DSA/ML-KEM standards finalized - Pure PQC implementations - Classical algorithm deprecation - Performance optimization Contributing ------------ [](#contributing) This package follows the Nexus architecture principles: - **Framework-agnostic**: No Laravel dependencies in `src/` - **Contract-driven**: All persistence via interfaces - **Immutable**: Readonly value objects only - **Testable**: All dependencies injected Documentation ------------- [](#documentation) ### User Documentation [](#user-documentation) - **[Getting Started](docs/getting-started.md)** - Quick start guide with prerequisites, core concepts, and first integration - **[API Reference](docs/api-reference.md)** - Complete documentation of all interfaces, services, value objects, enums, and exceptions - **[Integration Guide](docs/integration-guide.md)** - Laravel and Symfony integration with complete examples - **[Basic Usage Examples](docs/examples/basic-usage.php)** - Common cryptographic operations - **[Advanced Usage Examples](docs/examples/advanced-usage.php)** - Key rotation, envelope encryption, multi-tenant patterns ### Project Documentation [](#project-documentation) - **[IMPLEMENTATION\_SUMMARY.md](IMPLEMENTATION_SUMMARY.md)** - Development progress, metrics, and design decisions - **[REQUIREMENTS.md](REQUIREMENTS.md)** - Complete requirements tracking (42 requirements, 88.1% complete) - **[TEST\_SUITE\_SUMMARY.md](TEST_SUITE_SUMMARY.md)** - Testing strategy and recommendations (85 tests at application layer) - **[VALUATION\_MATRIX.md](VALUATION_MATRIX.md)** - Package valuation metrics ($225K estimated value, 1,719% ROI) License ------- [](#license) MIT License - see LICENSE file for details. Security Disclosure ------------------- [](#security-disclosure) For security vulnerabilities, please email: (DO NOT file public issues) ### Health Score 37 — LowBetter than 81% of packages Maintenance93 Actively maintained with recent releases Popularity3 Limited adoption so far Community16 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 76.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 36d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman) --- Top Contributors [![azaharizaman](https://avatars.githubusercontent.com/u/117408?v=4)](https://github.com/azaharizaman "azaharizaman (467 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/azaharizaman-nexus-crypto/health.svg) ``` [![Health](https://phpackages.com/badges/azaharizaman-nexus-crypto/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-crypto) ``` ### Alternatives [matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.6k38.2k](/packages/matomo-matomo)[symfony/http-kernel Provides a structured process for converting a Request into a Response 8.1k853.6M8.2k](/packages/symfony-http-kernel)[symfony/cache Provides extended PSR-6, PSR-16 (and tags) implementations 4.2k365.0M3.1k](/packages/symfony-cache)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[ecotone/ecotone Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes. 562565.8k41](/packages/ecotone-ecotone)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1237.8M117](/packages/web-auth-webauthn-lib) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)