PHPackages kode/jwt - 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. [Authentication & Authorization](/categories/authentication) 4. / 5. kode/jwt ActiveLibrary[Authentication & Authorization](/categories/authentication) kode/jwt ======== 为现代 PHP 应用提供安全、灵活、高性能的 JWT 身份验证解决方案，支持单点登录（SSO）、多点登录、黑名单管理、自动续期、多平台适配，兼容 FPM、Swoole、RoadRunner 等运行环境。 1.11.0(1w ago)11441Apache-2.0PHPPHP ^8.3 Since Sep 20Pushed 5d agoCompare [ Source](https://github.com/kodephp/jwt)[ Packagist](https://packagist.org/packages/kode/jwt)[ RSS](/packages/kode-jwt/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (18)Versions (21)Used By (0) Kode JWT：一个健壮、全面、现代化的 PHP 8.3+ JWT 包 ==================================== [](#kode-jwt一个健壮全面现代化的-php-83-jwt-包) > **项目名称**：`kode/jwt` > **当前版本**：`v1.12.0` > **目标**：为现代 PHP 应用提供安全、灵活、高性能的 JWT 身份验证解决方案，支持单点登录（SSO）、多点登录、黑名单管理、自动续期、多平台适配、防重放攻击（Anti-Replay）、JWK 密钥管理、Token 客户端指纹绑定、JWKS 端点发布、Token Introspection、OIDC Discovery，兼容 FPM、Swoole、RoadRunner 等运行环境。 --- 📌 项目愿景 ------ [](#-项目愿景) 构建一个**生产级、零侵入、高可扩展**的 JWT 包，专为 PHP 8.3+ 设计，充分利用现代 PHP 特性（`readonly class`、类型化类常量、`json_validate()`、`#[\Override]` 属性、`enum`、联合类型、反射优化），并支持主流框架（Laravel、Symfony、ThinkPHP、Hyperf、EasySwoole 等）无缝接入。 可使用 kode 相关包或其他通用适合的包快速集成。 --- 🚀 核心特性 ------ [](#-核心特性) 特性说明✅ **PHP 8.3+ 原生支持**使用 `readonly class`、类型化类常量（`private const array FOO = [...]`）、`json_validate()`、`#[\Override]` 属性等 PHP 8.3+ 特性✅ **多平台支持**H5、PC、App、小程序（微信/支付宝/抖音）等，通过 `platform` 声明区分，是否启用平台，平台配置一致或单独配置✅ **单点登录（SSO）**同一用户在同一平台仅允许一个有效 Token，支持 Redis Lua 原子化踢出✅ **多点登录（MLO）**支持同一用户在多个设备同时登录✅ **Token 黑名单**支持主动注销、强制下线，基于 Redis 或内存存储（协程安全）✅ **自动续期（Refresh）**支持滑动过期、固定刷新周期，防止频繁登录✅ **多环境配置**支持 `config/jwt.php` 配置，兼容 Laravel、Hyperf 等框架✅ **运行时兼容**支持 FPM、Swoole 多进程/协程、RoadRunner 多线程✅ **类型安全 & 反射优化**使用 `ReflectionClass` + 缓存实现高性能依赖注入与配置解析✅ **逆变/协变设计**接口设计遵循 LSP，支持泛型风格扩展（通过 PHPDoc + 命名规范）✅ **零框架依赖**可独立使用，也可通过适配器接入任意框架✅ **事件驱动**提供 `TokenIssued`、`TokenExpired`、`TokenRevoked` 等事件钩子✅ **审计日志**可选记录 Token 生成、使用、注销行为，使用通用日志包✅ **加密算法可插拔**默认 `HS256` / `RS256`，支持自定义签名器✅ **防重放攻击（Anti-Replay）**基于 Redis Nonce + 滑动窗口，杜绝 Token 被截获后重复使用✅ **高熵 JTI**32 字节（256 bit）密码学安全随机数，远高于 UUID v4✅ **标准声明（iss/aud/sub）**业务级强制校验，防止跨服务/跨租户混用✅ **时钟漂移容忍**跨节点 NTP 偏差场景下，配置 `clock_skew` 即可容错✅ **Redis 原子化撤销**Lua 脚本保证"黑名单 + SSO 映射 + 用户 Token 列表"三步原子性🆕 v1.9 **JWK 密钥管理（RFC 7517）**`Jwk` / `JwkSet` / `KeyConverter` / `JwkFactory`，支持 RSA / EC / oct 三种密钥类型，PEM ↔ JWK 互转，CSPRNG 安全密钥生成🆕 v1.9 **Token 客户端指纹绑定**`Fingerprint` 组件将 Token 与客户端 UA + IP 前缀绑定，防止跨设备重放，内置可信内网 IP 白名单🆕 v1.9 **算法白名单强制校验**三层防御：永久禁用 `none` 算法 → 显式白名单 → 单算法严格匹配，杜绝算法混淆攻击🆕 v1.9 **PHP 8.3 readonly class**`Jwk`、`JwkSet` 等核心值对象使用 `final readonly class`，运行期不可变，防止密钥被篡改🆕 v1.9 **类型化类常量**使用 `private const array SUPPORTED_KTY = [...]` 等 PHP 8.3 类型化常量，强化类型安全🆕 v1.10 **JWKS 端点发布（RFC 7517 §5）**`JwksPublisher` 将 JWK Set 以标准 JSON 格式发布到 `jwks_uri`，自动剥离私钥，支持 ETag / If-None-Match 协商缓存🆕 v1.10 **Token Introspection（RFC 7662）**`Introspector` + `IntrospectionResponse` 提供标准 introspection 端点，资源服务器可查询 Token 当前状态🆕 v1.10 **OIDC Discovery（RFC 8414）**`DiscoveryConfiguration` + `DiscoveryPublisher` 发布授权服务器元数据，支持 `/.well-known/openid-configuration`🆕 v1.10 **Scope 值对象与声明检查器**`Scope` 不可变集合（has/hasAny/hasAll/intersect/diff），`ClaimInspector` 链式校验 issuer/audience/scope/time window🆕 v1.10 **TokenPolicy 策略对象**不可变策略值对象，链式配置（issuer/audience/platform/scope/custom），一次性 `enforce()` 完成 Token 校验🆕 v1.11 **完整 JWS 算法族（RFC 7518/8017/8037）**`Signer` 统一门面：HMAC + RSA-PSS（真 EMSA-PSS）+ ECDSA（R‖S 标准 raw）+ EdDSA（Ed25519）🆕 v1.11 **cnf 确认声明（RFC 7800）**`Confirmation` 值对象，支持 jkt/jwk/jku/kid，绑定密钥指纹🆕 v1.11 **DPoP 持有证明（RFC 9449）**`DPoPProofBuilder` / `DPoPValidator`：内联公钥 JWK 证明，防 Token 重放/转发🆕 v1.11 **Token 撤销端点（RFC 7009）**`RevocationHandler` 将 jti 加入黑名单，被撤销 Token 立即失效🆕 v1.11 **JWK 指纹（RFC 7638）**`Jwk::thumbprint()` 跨语言一致指纹，支持 RSA/EC/OKP/oct；EC/OKP PEM↔JWK 互转--- 📁 项目结构（PSR-4） ------------- [](#-项目结构psr-4) ``` src/ ├── Contract/ # 所有接口定义 │ ├── TokenManagerInterface.php │ ├── StorageInterface.php │ ├── GuardInterface.php │ ├── SsoStorageInterface.php # SSO 高级能力（atomicRevoke/trackUserToken/...） │ ├── ReplayProtectionInterface.php │ ├── EventInterface.php │ ├── EventListener.php │ ├── Arrayable.php │ ├── Jsonable.php │ └── LoggerInterface.php ├── Token/ # Token 核心类 │ ├── Builder.php # 签发构造器（含公私钥 mtime 缓存） │ ├── Parser.php # 解析校验器（含算法白名单三层防御） │ ├── Claim.php │ ├── Payload.php # readonly 值对象 │ └── TokenManager.php ├── Guard/ # 守卫机制 │ ├── BaseGuard.php # 支持 ttl_unit / refresh_ttl_unit 配置 │ ├── SsoGuard.php │ └── MloGuard.php ├── Storage/ # 存储驱动 │ ├── RedisStorage.php # + SsoStorageInterface (Lua 原子撤销) │ ├── CoroutineRedisStorage.php # Swoole 协程 Redis │ ├── MemoryStorage.php │ ├── FileStorage.php # sha256 短哈希防 key 碰撞 │ ├── ApcuStorage.php │ ├── DatabaseStorage.php # MySQL/SQLite 方言自动适配 │ ├── MemcachedStorage.php │ ├── NullStorage.php │ ├── RedisReplayProtection.php │ └── StorageFactory.php ├── Key/ # 🆕 v1.9 JWK 密钥管理（RFC 7517） │ ├── Jwk.php # final readonly class 值对象 │ ├── JwkSet.php # JWK 集合（密钥轮换） │ ├── KeyConverter.php # PEM ↔ JWK 互转（ASN.1 DER 编码） │ └── JwkFactory.php # CSPRNG 安全密钥生成 ├── KeyRotation/ # 密钥轮换 │ ├── KeyRotationManager.php # getMultiple 批量优化 │ └── KeyVersion.php ├── Security/ # 安全组件 │ ├── AntiReplay.php # Nonce 一次性消费 + 滑动窗口 │ └── Fingerprint.php # 🆕 v1.9 客户端指纹绑定（UA + IP 前缀） ├── Signature/ # 多签机制 │ ├── MultiSignature.php │ └── SignatureResult.php ├── Event/ # 事件系统 │ ├── BaseEvent.php │ ├── EventDispatcher.php │ ├── EventServiceProvider.php │ ├── TokenIssued.php │ ├── TokenExpired.php │ ├── TokenRefreshed.php │ ├── TokenRevoked.php │ ├── TokenBlacklisted.php │ └── TokenValidated.php ├── Exception/ # 自定义异常 │ ├── JwtException.php │ ├── TokenInvalidException.php │ ├── TokenExpiredException.php │ ├── TokenBlacklistedException.php │ └── TokenReplayException.php ├── Config/ # 配置管理 │ └── ConfigLoader.php ├── Enum/ # 枚举 │ ├── Algorithm.php │ ├── GuardMode.php │ └── StorageType.php ├── Log/ # 日志适配 │ ├── FileLogger.php │ ├── NullLogger.php │ ├── MonologAdapter.php │ └── LoggerFactory.php ├── Metrics/ # 监控指标 │ └── PrometheusMetrics.php ├── OAuth2/ # OAuth2 模块 │ ├── HybridProvider.php │ ├── HybridTokenResponse.php │ ├── JwksPublisher.php # 🆕 v1.10 JWKS 端点发布器 │ ├── JwksResponse.php # 🆕 v1.10 JWKS 响应值对象 │ ├── IntrospectionResponse.php # 🆕 v1.10 RFC 7662 内省响应 │ └── Introspector.php # 🆕 v1.10 RFC 7662 内省服务 ├── OpenId/ # OpenID Connect │ ├── IdTokenBuilder.php │ ├── UserInfo.php │ ├── DiscoveryConfiguration.php # 🆕 v1.10 RFC 8414 Discovery 元数据 │ └── DiscoveryPublisher.php # 🆕 v1.10 Discovery 端点发布器 ├── Claim/ # 🆕 v1.10 声明模块 │ ├── Scope.php # OAuth2/OIDC Scope 值对象 │ └── ClaimInspector.php # 链式声明校验器 ├── Policy/ # 🆕 v1.10 策略模块 │ └── TokenPolicy.php # Token 校验策略值对象 ├── Support/ # 辅助工具 │ ├── ImmutableDto.php │ └── PhpFeature.php ├── Console/ # CLI 命令 │ ├── InstallCommand.php │ ├── KeyGenerateCommand.php │ └── TokenCommand.php └── KodeJwt.php # 主门面/工厂类 ``` --- 🛠️ 安装方式 ------- [](#️-安装方式) ``` composer require kode/jwt ``` ### CLI 工具初始化 [](#cli-工具初始化) 安装完成后，在你的项目根目录运行以下命令来生成配置文件和密钥： ``` # 进入你的项目目录 cd /path/to/your/project # 安装配置文件和生成密钥（RSA 密钥对 + HMAC 密钥） php vendor/bin/jwt install # 或者仅生成配置文件 php vendor/bin/jwt install --config-only # 或者仅生成密钥 php vendor/bin/jwt install --key-only # 强制覆盖已存在的文件 php vendor/bin/jwt install --force ``` ### CLI 命令详解 [](#cli-命令详解) 命令说明示例`jwt install` 或 `jwt i`安装配置文件并生成密钥`php jwt install``jwt key` 或 `jwt k`生成密钥对`php jwt key rsa``jwt help` 或 `jwt h`显示帮助信息`php jwt help`#### install 命令选项 [](#install-命令选项) 选项说明`--config-only`仅发布配置文件，不生成密钥`--key-only`仅生成密钥，不发布配置文件`--force`强制覆盖已存在的文件`--platform=`指定默认平台（默认: web）#### key 命令选项 [](#key-命令选项) 参数说明`rsa`生成 RSA 密钥对（默认）`hmac`生成 HMAC 密钥`stdout`输出到标准输出（而非文件）`file`保存到文件（默认）`--force`强制覆盖已存在的密钥文件**示例**： ``` # 生成 RSA 密钥对（默认） php jwt key rsa # 生成 HMAC 密钥 php jwt key hmac # 生成并输出到控制台 php jwt key rsa stdout # 强制覆盖现有密钥 php jwt key rsa --force ``` ### 生成的文件结构 [](#生成的文件结构) 运行 `php jwt install` 后，会在你的项目目录中生成以下文件： ``` your-project/ ├── config/ │ └── jwt.php # JWT 配置文件 └── storage/ └── keys/ ├── secret # HMAC 密钥（用于 HS256） ├── private.pem # RSA 私钥（用于 RS256 签名） └── public.pem # RSA 公钥（用于 RS256 验证） ``` > **重要**：请确保 `storage/keys/` 目录不在版本控制中（添加到 `.gitignore`），以保护密钥安全。 --- 🧩 配置文件（`config/jwt.php`） ------------------------ [](#-配置文件configjwtphp) 运行 `php jwt install` 后，会自动生成配置文件。以下是完整配置说明： ```