⚡ zappzarapp/security

全面的 PHP 安全库，提供 CSP、安全响应头、CSRF 防护、安全 Cookie、密码验证、输入净化、速率限制、SRI、密钥加载、加密、会话安全、TOTP 双因素认证、签名 URL 和安全事件日志记录。

亮点

• 一体化 — 单个可组合包中包含 17 个安全模块
• 默认安全 — 严格的 CSP，无 unsafe-*，HTTPS 优先
• 框架无关 — 适用于任何 PHP 8.4+ 应用程序
• 不可变且类型安全 — readonly 类、枚举、with*() API
• 质量保障 — PHPStan Level 8、Psalm Level 1、100% Mutation Score、Deptrac 架构强制检查
• PSR 兼容 — PSR-3（日志）、PSR-15（中间件）、PSR-18（HTTP 客户端）

模块

模块	描述	关键类
CSP	内容安全策略响应头构建与违规报告	CspDirectives、HeaderBuilder、NonceGenerator、CspReportParser
Headers	安全响应头（HSTS、Permissions-Policy 等）	SecurityHeaders、SecurityHeadersBuilder
CSRF	跨站请求伪造防护	CsrfProtection、CsrfConfig
Cookie	安全 Cookie 处理	SecureCookie、CookieBuilder、CookieOptions
Encryption	XChaCha20-Poly1305 认证加密	SymmetricEncryptor、EnvelopeEncryptor、EncryptionKey、KeyRingEncryptor
Password	密码验证与哈希	PasswordPolicy、PwnedPasswordChecker、PepperedPasswordHasher
Sanitization	输入净化（HTML、SQL、URI、路径）及文件上传验证	HtmlSanitizer、UriSanitizer、PathValidator、UploadValidator
RateLimiting	支持多种算法的速率限制	DefaultRateLimiter、RateLimitConfig
SRI	子资源完整性哈希生成	SriHashGenerator、IntegrityAttribute
Secrets	基于 Docker/文件的密钥加载	SecretLoader、SecretValue、FileSecretSource
Session	会话加固与会话固定攻击防护	SessionGuard、SessionConfig、SessionConfigurator
SignedUrl	带强制过期时间的 HMAC 签名 URL	UrlSigner、SigningKey
TOTP	基于时间的一次性密码（RFC 6238）	TotpAuthenticator、TotpSecret、ProvisioningUri、RecoveryCodeGenerator
Analyzer	安全响应头分析与审计	SecurityHeaderAnalyzer、AnalysisResult
Scanner	CLI 安全响应头扫描器	ScanCommand、StreamHeaderFetcher
Middleware	用于无缝框架集成的 PSR-15 中间件	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}");
}

带 Nonce 的 CSP

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');
}

有关所有模块的详细示例，请参阅文档。

文档

每个模块都有详细的 API 文档，包含类引用、配置选项和代码示例：