lzm-iam 0.2.0

系统用户与权限鉴权库 - 账号管理、组织管理、DAC 权限模型

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

项目定位

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

安装

# 默认（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
• TODO：docs/todo.md

快速开始

SQLite（默认）

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（生产环境）

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 实例

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]。

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	现代高性能非对称方案

配置示例

# 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/               # 文档

相关文档

• 开发进度时间线
• 常见错误归档
• 编码规范
• TODO 管理
• 架构设计