Metadata-Version: 2.4
Name: lzm-iam
Version: 0.2.0
Summary: 系统用户与权限鉴权库 - 账号管理、组织管理、DAC 权限模型
Author: Lzm
License-Expression: MIT
Project-URL: Homepage, https://github.com/lzm/lzm-iam
Project-URL: Issues, https://github.com/lzm/lzm-iam/issues
Keywords: iam,auth,permission,dac,user-management,lzm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: bcrypt>=4.0
Requires-Dist: pyjwt>=2.0
Requires-Dist: aiosqlite>=0.20
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2; extra == "mysql"
Provides-Extra: space
Requires-Dist: lzm-space>=0.2.0; extra == "space"
Provides-Extra: all
Requires-Dist: lzm-iam[mysql,space]; extra == "all"

# lzm-iam 系统用户与权限鉴权库

![PyPI version](https://img.shields.io/pypi/v/lzm-iam)
![Python >=3.11](https://img.shields.io/pypi/pyversions/lzm-iam)
![License MIT](https://img.shields.io/pypi/l/lzm-iam)

## 项目定位

独立于 lzm-space 的系统用户与权限鉴权库，提供账号管理、组织管理、DAC 权限模型三大能力。与 lzm-space 使用同一套 DAC 权限体系，但**零依赖、可独立运作**。

## 安装

```bash
# 默认（SQLite 存储）
pip install lzm-iam

# 生产环境（MySQL 存储）
pip install lzm-iam[mysql]

# AgentOS 架构（lzm-space Cabinet 存储）
pip install lzm-iam[space]

# 全部可选依赖
pip install lzm-iam[all]
```

## 技术栈

| 层 | 技术 | 版本 |
|----|------|------|
| 语言 | Python | >= 3.11 |
| 存储 | SQLite（aiosqlite）/ MySQL（aiomysql）/ lzm-space | >= 0.20 / >= 0.2 |
| 密码 | bcrypt | >= 4.0 |
| Token | PyJWT | >= 2.0 |

## 项目状态

- **当前阶段**：v0.2.0 — SpaceStore 适配器完成
- **进度**：[docs/timeline.md](docs/timeline.md)
- **TODO**：[docs/todo.md](docs/todo.md)

## 快速开始

### SQLite（默认）

```python
from lzm.iam import IAMManager

iam = IAMManager(db_path="/data/iam.db")
await iam.initialize(root_password="Admin@2026")

# 认证
user, token = await iam.authenticate("root", "Admin@2026")
```

### MySQL（生产环境）

```python
from lzm.iam import IAMManager

iam = IAMManager(config={
    "driver": "mysql",
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "mysql_password",
    "database": "iam",
})
await iam.initialize(root_password="Admin@2026")
```

### 手动传入 Store 实例

```python
from lzm.iam import IAMManager, SQLiteStore, MySQLStore

# 使用 SQLite（自定义连接参数）
store = SQLiteStore("/custom/path/iam.db")
iam = IAMManager(store=store)

# 使用 MySQL
store = MySQLStore(host="localhost", user="root", password="xxx", database="iam")
iam = IAMManager(store=store)
```

### SpaceStore（基于 lzm-space Cabinet — AgentOS 架构）

依赖 lzm-space v0.2.0，需要安装 `pip install lzm-iam[space]`。

```python
from lzm.iam import IAMManager, SpaceStore
from lzm.space import CabinetBackend, CABINET_USERS, CABINET_ORGS
from lzm.space.backends.sql_backend import SQLBackend

# Step 1: 创建 SQL 后端
backend = SQLBackend("sys", config={
    "dsn": "postgresql://user:pass@localhost:5432/agentos",
})

# Step 2: 创建信息柜
users_cabinet = CabinetBackend("sys", CABINET_USERS, backend)
orgs_cabinet = CabinetBackend("sys", CABINET_ORGS, backend)

# Step 3: 创建 SpaceStore 并传入 IAMManager
store = SpaceStore(users_cabinet, orgs_cabinet)
iam = IAMManager(store=store)
await iam.initialize(root_password="Admin@2026")

# 认证（与 SQLite/MySQL 使用方式完全一致）
user, token = await iam.authenticate("root", "Admin@2026")
```

**注意**：SpaceStore 不管理后端的生命周期（start/stop），由调用方统一管理。

## 安全架构

### 认证流程

```
客户端 (浏览器/App)         你的后端 API                lzm-iam
      │                         │                         │
      │ ① HTTPS 加密传输          │                         │
      │    明文密码               │                         │
      │ ──────────────────→      │                         │
      │                         │ ② authenticate("alice", │
      │                         │    "pass123")           │
      │                         │ ───────────────────→    │
      │                         │                         │
      │                         │   ③ bcrypt 哈希比对      │
      │                         │   ④ 签发 JWT Token       │
      │                         │                         │
      │ ⑤ 收到 JWT Token        │ ←─── (User, token) ─── │
      │ ←──────────────────     │                         │
      │                         │                         │
      │ ⑥ 后续请求携带 Token     │                         │
      │     Authorization:      │                         │
      │     Bearer <token>      │ ⑦ verify_token(token)   │
      │ ──────────────────→     │ ───────────────────→    │
      │                         │   ⑧ 校验签名+检测变更    │
      │                         │   ⑨ 返回 (User, token)  │
```

`authenticate()` 接收 **明文密码**，这是业界标准设计：

| 层级 | 安全措施 | 说明 |
|------|---------|------|
| **传输层** | HTTPS / TLS | 客户端到服务器的通道加密，密码在传输中是密文 |
| **认证层** | bcrypt | 存储的是 bcrypt 哈希，即使数据库泄露也无法还原密码 |
| **鉴权层** | 可配置 JWT 算法（HS256/HS384/HS512/RS256/ES256 等） | Token 内嵌用户信息快照，由密钥签名防篡改 |

> 所有主流框架（Django、Flask-Login、FastAPI）的 `authenticate()` 函数均接收明文密码。明文在这里的含义是"未经过二次哈希的原始密码字符串"，它的传输安全由 TLS 保障，存储安全由 bcrypt 保障。

## JWT 配置

### 加密算法选择

| 算法 | 类型 | 密钥要求 | 适用场景 |
|------|------|---------|---------|
| **HS256** (默认) | 对称 | 任意字符串，推荐 ≥32 字符 | 单服务、开发环境 |
| **HS384** | 对称 | 推荐 ≥48 字符 | 需要更高安全性的对称方案 |
| **HS512** | 对称 | 推荐 ≥64 字符 | 最高安全性对称方案 |
| **RS256** | 非对称 | RSA 私钥 PEM / 公钥 PEM | 微服务间鉴权（私钥签发，公钥验证） |
| **ES256** | 非对称 | ECDSA 私钥 PEM | 性能敏感场景的微服务鉴权 |
| **EdDSA** | 非对称 | Ed25519 私钥 PEM | 现代高性能非对称方案 |

### 配置示例

```python
# HS512 — 强对称密钥
iam = IAMManager(
    db_path="/data/iam.db",
    jwt_secret="your-64-char-min-secret-key-for-hs512-here!",
    jwt_algorithm="HS512",
)

# RS256 — 非对称密钥（微服务场景）
iam = IAMManager(
    db_path="/data/iam.db",
    jwt_secret="""-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----""",
    jwt_algorithm="RS256",
)
```

### 关于密钥长度警告

PyJWT 对对称算法（HS*）有最低密钥长度要求：

| 算法 | 最低字节 | 建议字节 |
|------|---------|---------|
| HS256 | 32 | 32+ |
| HS384 | 48 | 48+ |
| HS512 | 64 | 64+ |

密钥低于最低长度会触发 `InsecureKeyLengthWarning`，不影响使用，但强烈建议配置足够长度的密钥。

## 目录结构

```
lzm-iam/
├── src/lzm/iam/
│   ├── core/           # 数据模型 + 纯逻辑（零外部依赖）
│   ├── store/          # SQLite / MySQL / Space 持久化
│   └── manager/        # 编排逻辑
├── tests/              # pytest 测试（112 项）
└── docs/               # 文档
```

## 相关文档

- [开发进度时间线](docs/timeline.md)
- [常见错误归档](docs/common-errors.md)
- [编码规范](docs/coding-standards.md)
- [TODO 管理](docs/todo.md)
- [架构设计](docs/logic-records/20260716-lzm-iam-architecture-design.md)
