⚡ zappzarapp/security

مكتبة أمان PHP شاملة توفر CSP، ترويسات الأمان، حماية CSRF، الكوكيز الآمنة، التحقق من كلمات المرور، تعقيم المدخلات، تحديد معدل الطلبات، SRI، تحميل الأسرار، التشفير، أمان الجلسات، المصادقة الثنائية TOTP، الروابط الموقّعة، وتسجيل أحداث الأمان.

أبرز المزايا

• كل شيء في واحد — 17 وحدة أمان في حزمة واحدة قابلة للتركيب
• آمن افتراضيًا — CSP صارم، بدون unsafe-*، HTTPS أولًا
• مستقل عن الأطر — يعمل مع أي تطبيق PHP 8.4+
• غير قابل للتغيير وآمن الأنواع — فئات readonly، تعدادات، واجهة برمجة with*()
• مدعوم بالجودة — PHPStan Level 8، Psalm Level 1، 100% Mutation Score، فرض بنية Deptrac
• متوافق مع PSR — PSR-3 (تسجيل)، PSR-15 (Middleware)، PSR-18 (عميل HTTP)

الوحدات

الوحدة	الوصف	الفئات الرئيسية
CSP	بناء ترويسة سياسة أمان المحتوى والإبلاغ عن الانتهاكات	CspDirectives, HeaderBuilder, NonceGenerator, CspReportParser
Headers	ترويسات الأمان (HSTS، Permissions-Policy، إلخ.)	SecurityHeaders, SecurityHeadersBuilder
CSRF	الحماية من تزوير الطلبات عبر المواقع	CsrfProtection, CsrfConfig
Cookie	التعامل الآمن مع الكوكيز	SecureCookie, CookieBuilder, CookieOptions
Encryption	تشفير مصادق عليه XChaCha20-Poly1305	SymmetricEncryptor, EnvelopeEncryptor, EncryptionKey, KeyRingEncryptor
Password	التحقق من كلمات المرور وتجزئتها	PasswordPolicy, PwnedPasswordChecker, PepperedPasswordHasher
Sanitization	تعقيم المدخلات (HTML، SQL، URI، Path) والتحقق من رفع الملفات	HtmlSanitizer, UriSanitizer, PathValidator, UploadValidator
RateLimiting	تحديد معدل الطلبات مع خوارزميات متعددة	DefaultRateLimiter, RateLimitConfig
SRI	توليد تجزئات تكامل الموارد الفرعية	SriHashGenerator, IntegrityAttribute
Secrets	تحميل الأسرار من Docker/الملفات	SecretLoader, SecretValue, FileSecretSource
Session	تقوية الجلسات والحماية من تثبيت الجلسة	SessionGuard, SessionConfig, SessionConfigurator
SignedUrl	روابط موقّعة بـ HMAC مع انتهاء صلاحية إلزامي	UrlSigner, SigningKey
TOTP	كلمات مرور لمرة واحدة مبنية على الوقت (RFC 6238)	TotpAuthenticator, TotpSecret, ProvisioningUri, RecoveryCodeGenerator
Analyzer	تحليل وتدقيق ترويسات الأمان	SecurityHeaderAnalyzer, AnalysisResult
Scanner	ماسح ترويسات أمان CLI	ScanCommand, StreamHeaderFetcher
Middleware	PSR-15 middleware لتكامل سلس مع الأطر	SecurityHeadersMiddleware, CspMiddleware, CspReportHandler, CsrfMiddleware, DoubleSubmitCsrfMiddleware, RateLimitMiddleware, CorsMiddleware
Logging	تسجيل أحداث الأمان	SecurityAuditLogger, SecurityEvent

المتطلبات

• PHP ^8.4
• ext-dom
• ext-libxml
• ext-sodium

التثبيت

composer require zappzarapp/security

بدء سريع

ترويسات الأمان

use Zappzarapp\Security\Headers\Builder\SecurityHeadersBuilder;

$headers = SecurityHeadersBuilder::recommended()->build();
foreach ($headers as $name => $value) {
    header("{$name}: {$value}");
}

CSP مع Nonces

use Zappzarapp\Security\Csp\HeaderBuilder;
use Zappzarapp\Security\Csp\Directive\CspDirectives;
use Zappzarapp\Security\Csp\Nonce\NonceGenerator;

$generator = new NonceGenerator();
$csp = HeaderBuilder::build(CspDirectives::strict(), $generator);
header("Content-Security-Policy: {$csp}");

$nonce = $generator->get();
echo "<script nonce=\"{$nonce}\">console.log('Safe!');</script>";

حماية CSRF

use Zappzarapp\Security\Csrf\CsrfProtection;
use Zappzarapp\Security\Csrf\Storage\SessionCsrfStorage;

$csrf = new CsrfProtection(new SessionCsrfStorage());

// توليد رمز للنموذج
$token = $csrf->generateToken();
echo '<input type="hidden" name="_token" value="' . $token->value() . '">';

// التحقق عند الإرسال
if (!$csrf->validateToken($_POST['_token'])) {
    throw new Exception('CSRF validation failed');
}

تعقيم المدخلات

use Zappzarapp\Security\Sanitization\Html\HtmlSanitizer;
use Zappzarapp\Security\Sanitization\Path\PathValidationConfig;
use Zappzarapp\Security\Sanitization\Path\PathValidator;

// تعقيم HTML (يزيل الوسوم/الخصائص الخطرة)
$sanitizer = new HtmlSanitizer();
$safe = $sanitizer->sanitize($userInput);

// التحقق من مسارات الملفات (منع اجتياز الدلائل)
$validator = new PathValidator(new PathValidationConfig(basePath: '/var/www/uploads'));
if (!$validator->isSafe($userPath)) {
    throw new Exception('Invalid path');
}

راجع التوثيق للحصول على أمثلة مفصلة لجميع الوحدات.