chongming-utils-jwt/README.md

# chongming-jwt

基于 **Rust + PyO3** 实现的 JWT 库，性能远超纯 Python 实现，支持多种签名算法。所有编解码操作在 Rust 层执行，不阻塞 Python 事件循环。

---

## 安装

```bash
uv pip install -e utils/jwt
```

需要 Rust 工具链，`uv` 自动通过 `maturin` 编译。

---

## 支持的算法

| 算法      | 类型        | 说明             |
| --------- | ----------- | ---------------- |
| **HS256** | HMAC-SHA256 | 对称签名（推荐） |
| **HS384** | HMAC-SHA384 | 对称签名         |
| **HS512** | HMAC-SHA512 | 对称签名         |
| **RS256** | RSA-SHA256  | 非对称签名       |
| **RS384** | RSA-SHA384  | 非对称签名       |
| **RS512** | RSA-SHA512  | 非对称签名       |

---

## API

### `JWT` 类

```python
from chongming_jwt import JWT

jwt = JWT(
    secret="your-secret-key-change-in-production",
    algorithm="HS256"
)
```

| 参数        | 类型  | 默认值    | 说明                             |
| ----------- | ----- | --------- | -------------------------------- |
| `secret`    | `str` | —         | 签名密钥（HS256 建议 ≥ 32 字节） |
| `algorithm` | `str` | `"HS256"` | 签名算法                         |

### 方法

```python
# 编码
token: str = jwt.encode(
    payload='{"sub": "user_id", "username": "john"}',
    expires_in_seconds=3600
)

# 解码（自动验证签名和过期时间）
claims: str = jwt.decode(token)

# 仅验证，不返回载荷
is_valid: bool = jwt.validate(token)
```

| 方法       | 签名                                             | 说明                             |
| ---------- | ------------------------------------------------ | -------------------------------- |
| `encode`   | `(payload: str, expires_in_seconds: int) -> str` | 编码 JSON 载荷为 JWT Token       |
| `decode`   | `(token: str) -> str`                            | 解码并验证 Token，无效时抛出异常 |
| `validate` | `(token: str) -> bool`                           | 验证有效性，返回布尔值           |

---

## 注意事项

- payload 必须包含 `sub` 字段（JWT 规范）
- HS256 密钥建议 ≥ 32 字节
- RS256/384/512 需要 PEM 格式 RSA 密钥
- 超时后 `decode` 抛出异常

---

## 手动编译

```bash
uv run maturin develop --release -m utils/jwt/Cargo.toml
```

---

## 依赖 (Rust)

- `jsonwebtoken` — JWT 编解码
- `pyo3` — Python 绑定
- `serde` / `serde_json` — JSON 序列化