refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
2026-01-18 21:48:25 +03:00
parent 3da69c03e1
commit d214eecebe
378 changed files with 10514 additions and 496 deletions

View File

@@ -0,0 +1,74 @@
<?php
/*
// MODULE_CONTRACT: Implements `SignerInterface` using OpenSSL for PKCS#7 (CMS) data signing.
// RESPONSIBILITY: To provide a concrete implementation of digital signing that takes a raw data string (e.g., canonicalized JSON), signs it using the configured mTLS certificate and private key, and returns a Base64 encoded PKCS#7 detached signature, adhering to Alfa Bank's security requirements.
// INPUTS: Data string to be signed. Certificate path and private key path are provided during instantiation.
// OUTPUTS: Base64 encoded PKCS#7 detached signature string.
// LINKS: Contracts/SecurityContracts.php, Utils/CmsSigner.php, README.md#security
*/
namespace Apoloz\AlfaBank\Services;
// <SECTION name="module_imports" intent="Import necessary classes for the signer contract.">
// <BELIEF_STATE "The `SignerInterface` is imported to ensure that `OpenSslCmsSigner` adheres to a predefined contract for digital signing, promoting interoperability and testability within the SDK.">
use Apoloz\AlfaBank\Contracts\SignerInterface;
// </SECTION>
// <SECTION name="class_definition" intent="Define the OpenSSL-based CMS signer service.">
// <BELIEF_STATE "The `OpenSslCmsSigner` class provides a robust and compliant solution for PKCS#7 CMS signing. By implementing `SignerInterface` and utilizing OpenSSL functions, it ensures that data integrity and authenticity can be cryptographically verified, which is critical for secure communication with financial institutions like Alfa Bank. The class takes certificate and private key paths during construction, allowing for flexible configuration.">
class OpenSslCmsSigner implements SignerInterface
{
// <SECTION name="constructor_definition" intent="Initialize the signer with certificate and private key paths.">
// <BELIEF_STATE "The constructor receives the file paths to the mTLS certificate and private key. These paths are stored as protected properties, ensuring that the signer instance is configured with the necessary credentials to perform digital signing operations, aligning with the principle of dependency injection for external resources.">
public function __construct(
protected string $certificatePath,
protected string $privateKeyPath
) {}
// </SECTION>
// <SECTION name="sign_method" intent="Sign a given data string using PKCS#7 CMS.">
// <BELIEF_STATE "The `sign` method performs the digital signature process as required by Alfa Bank. It reads the certificate and private key from the configured paths, then uses `openssl_pkcs7_sign` with `PKCS7_BINARY | PKCS7_DETACHED` flags to create a detached CMS signature. Error handling is included for robust operation, and the final signature is Base64 encoded after stripping unnecessary headers, ensuring compatibility with API expectations.">
public function sign(string $data): string
{
$privateKey = openssl_pkey_get_private(file_get_contents($this->privateKeyPath)); // assuming no passphrase for simplicity here
if (!$privateKey) {
throw new \Exception("Could not read private key for signing from {$this->privateKeyPath}.");
}
$cert = openssl_x509_read(file_get_contents($this->certificatePath));
if (!$cert) {
throw new \Exception("Could not read certificate for signing from {$this->certificatePath}.");
}
$inFile = tempnam(sys_get_temp_dir(), 'alfa_in');
$outFile = tempnam(sys_get_temp_dir(), 'alfa_out');
file_put_contents($inFile, $data);
$status = openssl_pkcs7_sign(
$inFile,
$outFile,
$cert,
$privateKey,
[],
PKCS7_BINARY | PKCS7_DETACHED
);
if (!$status) {
unlink($inFile);
unlink($outFile);
throw new \Exception("Signing failed: " . openssl_error_string());
}
$signedData = file_get_contents($outFile);
unlink($inFile);
unlink($outFile);
$parts = explode("\n\n", $signedData);
$signature = end($parts);
return str_replace(["\n", "\r"], '', $signature);
}
// </SECTION>
}
// </SECTION>

View File

@@ -0,0 +1,45 @@
<?php
/*
// MODULE_CONTRACT: Implements `EncryptorInterface` using phpseclib3 to encrypt card PANs with RSA OAEP for Alfa Bank.
// RESPONSIBILITY: To provide a concrete implementation of card data encryption, specifically adhering to the cryptographic algorithms and parameters (RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING) required by Alfa Bank for secure payment processing.
// INPUTS: Card PAN (string) for encryption, public key PEM provided during instantiation.
// OUTPUTS: Base64 encoded encrypted PAN (string).
// LINKS: Contracts/SecurityContracts.php, Utils/CardEncryptor.php, README.md#security
*/
namespace Apoloz\AlfaBank\Services;
// <SECTION name="module_imports" intent="Import necessary classes for the encryption contract and cryptographic operations.">
// <BELIEF_STATE "These imports establish the foundational elements for the `PhpseclibCardEncryptor`. `EncryptorInterface` ensures adherence to a defined contract, while `PublicKeyLoader` and `RSA` from phpseclib3 provide the robust cryptographic capabilities required for secure RSA encryption, including key loading and algorithm configuration.">
use Apoloz\AlfaBank\Contracts\EncryptorInterface;
use phpseclib3\Crypt\PublicKeyLoader;
use phpseclib3\Crypt\RSA;
// </SECTION>
// <SECTION name="class_definition" intent="Define the phpseclib3-based card encryptor service.">
// <BELIEF_STATE "The `PhpseclibCardEncryptor` class implements `EncryptorInterface`, providing a concrete and testable service for card data encryption. It uses phpseclib3 to handle complex cryptographic operations, abstracting the details of RSA OAEP encryption from the rest of the application and promoting a clean architecture.">
class PhpseclibCardEncryptor implements EncryptorInterface
{
// <SECTION name="constructor_definition" intent="Initialize the encryptor with a public key.">
// <BELIEF_STATE "The constructor receives the public key in PEM format, which is essential for encrypting data. This key is stored as a protected property, making it available for the `encrypt` method and ensuring that the encryptor is properly configured upon instantiation.">
public function __construct(
protected string $publicKeyPem
) {}
// </SECTION>
// <SECTION name="encrypt_method" intent="Encrypt a given string (e.g., card PAN) using RSA OAEP.">
// <BELIEF_STATE "This method, implementing the `encrypt` contract, takes the raw data (e.g., a card PAN) and encrypts it using the pre-configured public key. It specifies RSA OAEP padding with SHA-256 for the hash and MGF1 with SHA-1, as required by Alfa Bank. The resulting encrypted data is then Base64 encoded for safe transport, ensuring both security and compatibility.">
public function encrypt(string $data): string
{
/** @var RSA $key */
$key = PublicKeyLoader::load($this->publicKeyPem);
$key = $key->withHash('sha256')
->withMGFHash('sha1') // MGF1 with SHA1 is standard for banking
->withPadding(RSA::ENCRYPTION_OAEP);
return base64_encode($key->encrypt($data));
}
// </SECTION>
}
// </SECTION>