@h-ai/iam 0.1.0-alpha.55 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,556 @@
+# @h-ai/iam
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/audit](../audit/README.en.md) · [@h-ai/cache](../cache/README.en.md) · [@h-ai/core](../core/README.en.md) · [@h-ai/crypto](../crypto/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
+
+Identity and access management through a unified `iam` object for authentication, sessions, authorization, and user management.
+
+## Features
+
+| Feature              | Description                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Authentication**   | Password, OTP (email/SMS codes), LDAP, and API Key strategies                                                          |
+| **Sessions**         | Stateful sessions (random access tokens + cache, optional sliding renewal)                                             |
+| **Authorization**    | RBAC roles and permissions (DB + cache, wildcard matching)                                                             |
+| **User management**  | Registration, queries, updates, password reset, and admin password reset                                               |
+| **API Key**          | Create, revoke, and verify API keys with scopes and expiration                                                         |
+| **One-time tickets** | Short-lived capability tickets (issue / atomic consume) for channels such as WebSocket that cannot carry Bearer tokens |
+| **Frontend client**  | HTTP API contracts for independent frontends                                                                           |
+
+## Installation
+
+```bash
+pnpm add @h-ai/iam
+```
+
+## Dependencies
+
+- `@h-ai/reldb`: persistence for users/roles/permissions; **initialize before iam.init()**.
+- `@h-ai/cache`: sessions/OTP/reset tokens/permission cache; **initialize before iam.init()**.
+- `@h-ai/crypto`: password hashing, used internally and initialized automatically.
+- `@h-ai/audit`: audit records for key RBAC operations.
+
+## Quick start
+
+```ts
+import { cache } from '@h-ai/cache'
+import { iam } from '@h-ai/iam'
+import { reldb } from '@h-ai/reldb'
+
+// 1. 初始化依赖
+await reldb.init({ type: 'sqlite', database: './data.db' })
+await cache.init({ type: 'memory' })
+
+// 2. 初始化 IAM（自动使用已初始化的 reldb 和 cache 单例）
+await iam.init({
+  session: { maxAge: 86400, sliding: true },
+  // OTP 回调（启用 OTP 登录时注入发送逻辑）
+  onOtpSendEmail: async (email, code) => {
+    await sendEmail(email, `验证码: ${code}`)
+  },
+  // 密码重置回调（启用密码重置时注入通知逻辑）
+  onPasswordResetRequest: async (user, token, expiresAt) => {
+    await sendEmail(user.email!, `重置链接: https://example.com/reset?token=${token}`)
+  },
+})
+
+// 2. 注册
+const userResult = await iam.user.register({
+  username: 'admin',
+  email: 'admin@example.com',
+  password: 'Password123',
+})
+
+// 3. 登录
+const loginResult = await iam.auth.login({
+  identifier: 'admin',
+  password: 'Password123',
+})
+if (loginResult.success) {
+  const { user, tokens } = loginResult.data
+}
+
+// 4. 验证令牌
+const session = await iam.auth.verifyToken(loginResult.data.tokens.accessToken)
+
+// 5. OTP 验证码登录
+await iam.auth.sendOtp('user@example.com')
+const otpResult = await iam.auth.loginWithOtp({
+  identifier: 'user@example.com',
+  code: '123456',
+})
+
+// 6. 检查权限
+const hasPermission = await iam.authz.checkPermission(
+  loginResult.data.user.id,
+  'user:read',
+)
+
+// 7. 关闭
+await iam.close()
+```
+
+`iam.config` returns a **redacted configuration snapshot**. Sensitive LDAP `url` / `bindPassword` and similar fields are hidden automatically. Use it to inspect state, not as the original configuration source.
+
+## Design
+
+### Architecture
+
+IAM is a **lifecycle singleton** managed through `iam.init()` / `iam.close()`. Five internal subsystems initialize in dependency order:
+
+```
+iam.init()
+  ├─ session  (cached sessions; no DB dependency)
+  ├─ authz    (RBAC roles/permissions; DB + cache)
+  ├─ authn    (authentication; depends on session + authz)
+  ├─ user     (users; depends on session + authz + passwordStrategy)
+  └─ seed     (seed data; depends on authz)
+```
+
+All subsystems use **factories + closures** (for example `createSessionOperations(deps)`), not classes. Getters expose them as `iam.auth` / `iam.user` / `iam.authz` / `iam.session` / `iam.apiKey`.
+
+Before initialization, every subsystem method returns `NOT_INITIALIZED` through a `NotInitializedKit` proxy.
+
+### Data storage
+
+| Data                                                | Storage       | Description                                                                                                                   |
+| --------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Users, roles, permissions, associations, API keys   | DB (6 tables) | `hai_iam_users`、`hai_iam_roles`、`hai_iam_permissions`、`hai_iam_role_permissions`、`hai_iam_user_roles`、`hai_iam_api_keys` |
+| Sessions (accessToken → Session)                    | Cache         | TTL, optional sliding renewal                                                                                                 |
+| Token mapping (refreshToken → userId + accessToken) | Cache         | Separate keys; old tokens expire immediately after refresh                                                                    |
+| OTP codes                                           | Cache         | TTL + attempt limit                                                                                                           |
+| Password reset tokens                               | Cache         | TTL + maximum verification attempts                                                                                           |
+| API Key                                             | DB            | `hai_iam_api_keys`; store hashes only, never plaintext; prefix narrows candidates                                             |
+
+---
+
+### Authentication (authn) — `iam.auth`
+
+#### Key types
+
+- **`AuthnOperations`**: `login` / `loginWithOtp` / `loginWithLdap` / `loginWithApiKey` / `logout` / `verifyToken` / `sendOtp` / `registerAndLogin`.
+- **`AuthStrategy`**: strategy interface (`type` + `authenticate` + `challenge?`), implemented for password, OTP, LDAP, and API Key.
+- **`AuthResult`**: login result with user details, `TokenPair` (accessToken + refreshToken), and roles/permissions.
+- **`Credentials`**: a credential union combining `{ type: 'password' | 'otp' | 'ldap' | 'apikey' }` with strategy-specific credentials.
+
+#### Key workflows
+
+**Password login:**
+
+```
+login(credentials)
+  → Check password login is enabled
+  → Find user by identifier (username / email / phone)
+  → Dummy hash for missing users (fixed timing to mitigate timing attacks)
+  → Check account lock (loginFailedCount >= maxLoginAttempts within lockoutDuration)
+  → Verify password hash (@h-ai/crypto)
+  → Failure: record attempt; lock at the limit
+  → Success: reset failure count
+  → Check password expiration (passwordUpdatedAt when expirationDays > 0)
+  → Query user roles + permissions
+  → Create session (session.create → TokenPair)
+  → Return AuthResult { user, tokens, roles, permissions, agreements? }
+```
+
+**Token verification:**
+
+```
+verifyToken(accessToken)
+  → session.get(accessToken) → cache lookup
+  → Extend TTL automatically when sliding renewal is enabled
+  → Return Session (userId, roles, permissions)
+```
+
+#### Usage
+
+`authz.createRole({ ..., permissionIds })` and `authz.updateRole(id, { ..., permissionIds })` save role data and the complete permission set in one transaction; any failure rolls back. `permissionIds: []` clears permissions, omission preserves them, duplicate IDs are deduplicated, and unknown permissions fail. Concurrent updates use the last committed complete set without merging. Self-managed commits synchronize user sessions; with an external transaction, the caller must synchronize after commit. Admin Console uses this API directly, without split updates or compensating role deletion.
+
+```ts
+// 密码登录
+const result = await iam.auth.login({ identifier: 'admin', password: 'Password123' })
+
+// OTP 登录
+await iam.auth.sendOtp('user@example.com')
+const result = await iam.auth.loginWithOtp({ identifier: 'user@example.com', code: '123456' })
+
+// LDAP 登录（需在 init 时提供 ldapClientFactory）
+const result = await iam.auth.loginWithLdap({ username: 'jdoe', password: 'pass' })
+
+// API Key 登录（需启用 login.apikey: true）
+const result = await iam.auth.loginWithApiKey({ key: 'hai_xxxx...' })
+
+// 验证令牌
+const session = await iam.auth.verifyToken(accessToken)
+
+// 注册并登录（一站式）
+const result = await iam.auth.registerAndLogin({ username: 'new', password: 'Pass123' })
+```
+
+#### Considerations
+
+- **Timing attack mitigation**: perform a dummy password hash for nonexistent users to keep response timing consistent.
+- **Account lockout**: lock for `lockoutDuration` seconds after `maxLoginAttempts` consecutive failures.
+- **Independent strategy toggles**: `login.password` / `login.otp` / `login.ldap` / `login.apikey`.
+- **OTP security**: rejection sampling avoids modulo bias, constant-time comparison mitigates timing attacks, and `resendInterval` limits frequency.
+
+---
+
+### Sessions (session) — `iam.session`
+
+#### Key types
+
+- **`SessionOperations`**: `create` / `get` / `verifyToken` / `update` / `delete` / `deleteByUserId` / `refresh` / `revokeRefresh` / `patchUserSessions`.
+- **`Session`**: userId, roles, permissions, accessToken, expiration, and other session data.
+- **`TokenPair`**: `{ accessToken, refreshToken, expiresIn, tokenType: 'Bearer' }`.
+
+#### Key workflows
+
+**Token refresh (rotation):**
+
+```
+refresh(refreshToken)
+  → Read refreshToken → { userId, accessToken } from cache
+  → Get old session via accessToken
+  → Delete old refreshToken (expire key immediately to prevent replay)
+  → Delete old accessToken session
+  → Create a new session with the old user context
+  → Return new TokenPair
+```
+
+**Single-device login:**
+
+```
+create(options) [singleDevice=true]
+  → Clear all existing user tokens via user→tokens mapping
+  → Generate new accessToken + refreshToken
+  → Store session in cache
+```
+
+#### Usage
+
+```ts
+// 创建会话（通常由 login 内部调用）
+const session = await iam.session.create({
+  userId: 'user-id',
+  username: 'admin',
+  roles: ['admin'],
+  permissions: ['user:read', 'user:write'],
+})
+
+// 验证令牌
+const session = await iam.session.verifyToken(accessToken)
+
+// 刷新令牌
+const newTokens = await iam.session.refresh(refreshToken)
+
+// 强制下线
+await iam.session.deleteByUserId(userId)
+```
+
+#### Considerations
+
+- **Cache-only storage**: no database persistence; all sessions expire after restart, following the security design.
+- **Sliding renewal**: with `sliding: true`, each `get()` extends TTL automatically.
+- **Refresh rotation**: old refreshToken expires after one use; replay detection indicates token leakage.
+- **Token strength**: 256-bit cryptographic randomness (`crypto.getRandomValues(new Uint8Array(32))`), base64url encoded.
+
+---
+
+### Authorization (authz) — `iam.authz`
+
+#### Key types
+
+- **`AuthzOperations`**: role/permission CRUD, role-permission/user-role assignments, and permission checks.
+- **`Role`**: `{ id, code, name, description, isSystem }`.
+- **`Permission`**: `{ id, code, name, type, resource, action }`; type is `menu` / `api` / `button`.
+- **`PermissionType`**: permission type enum.
+
+#### Key workflows
+
+**Permission checks (`checkPermission`):**
+
+```
+checkPermission(userId, permission)
+  → Return true if RBAC is disabled
+  → Query user roles (DB)
+  → Check super-admin role (cached superAdminRoleId); return true if present
+  → Get each role's permission codes (cache first; DB on miss, then cache)
+  → Match each permission exactly or by wildcard (`admin:*` matches `admin:read`)
+  → Return true / false
+```
+
+**Session synchronization after role/permission changes:**
+
+```
+assignPermissionToRole(roleId, permId)
+  → Write association to DB
+  → Clear role permission cache
+  → Find role users → resolve permissions per user → update active sessions
+  (best-effort: failures only log.error; permission assignment still succeeds)
+```
+
+#### Usage
+
+```ts
+// 角色管理
+const role = await iam.authz.createRole({ code: 'editor', name: '编辑' })
+const roles = await iam.authz.getAllRoles({ page: 1, pageSize: 20 })
+
+// 权限管理
+const perm = await iam.authz.createPermission({
+  code: 'article:publish',
+  name: '发布文章',
+  type: 'api',
+  resource: 'article',
+  action: 'publish',
+})
+
+// 分配与检查
+await iam.authz.assignRole(userId, role.data.id)
+await iam.authz.assignPermissionToRole(role.data.id, perm.data.id)
+const allowed = await iam.authz.checkPermission(userId, 'article:publish')
+
+// 批量同步角色
+await iam.authz.syncRoles(userId, [roleId1, roleId2])
+```
+
+#### Considerations
+
+- **Wildcard matching**: `admin:*` matches `admin:read`, `admin:write:detail`, etc.; one `*` matches everything after the colon.
+- **Super-admin role**: `rbac.superAdminRole` (default `super_admin`) automatically grants all permissions.
+- **Transactions**: `deleteRole` / `deletePermission` clear associations before deleting entities in a DB transaction.
+- **Session synchronization latency**: permission changes update active session permissions on a best-effort basis; many users may cause delay.
+- **Seed data**: `seedDefaultData: true` idempotently creates admin/user/guest roles and basic permissions.
+
+---
+
+### Users (user) — `iam.user`
+
+#### Key types
+
+- **`UserOperations`**: registration, queries, updates, deletion, password changes/resets, and password strength validation.
+- **`User`** (public fields): `{ id, username, email, phone, displayName, avatarUrl, enabled, roles? }`.
+- **`StoredUser`**: internal stored user, including sensitive `passwordHash`, `loginFailedCount`, `lockedUntil`, etc.
+- **`RegisterOptions`** / **`RegisterResult`**: registration input/output.
+- **`UpdateCurrentUserInput`**: fields the current user may change (`displayName` / `avatarUrl` / `phone` / `metadata`).
+
+#### Key workflows
+
+**User registration:**
+
+```
+register(options)
+  → Check registration is enabled
+  → Validate password strength (Zod schema + custom rules)
+  → Hash password (@h-ai/crypto)
+  → DB transaction: create user + query result
+  → Assign default role (rbac.defaultRole, outside transaction; failures only log)
+  → Return RegisterResult { user, agreements? }
+```
+
+**Password reset:**
+
+```
+requestPasswordReset(email)
+  → Find user by email (missing users return ok silently to prevent enumeration)
+  → Generate a random 256-bit token
+  → Cache SHA-256(token) → userId (TTL + maxAttempts)
+  → Call onPasswordResetRequest (application sends email/SMS)
+
+confirmPasswordReset(token, newPassword)
+  → Look up SHA-256(token) and verify expiration/attempts
+  → Validate password strength → hash → update DB
+  → Clear all active user sessions to force login
+  → Delete consumed reset token
+```
+
+#### Usage
+
+```ts
+// 注册
+const result = await iam.user.register({
+  username: 'alice',
+  email: 'alice@example.com',
+  password: 'Password123',
+})
+
+// 当前用户操作
+const me = await iam.user.getCurrentUser(accessToken)
+await iam.user.updateCurrentUser(accessToken, { displayName: '新名称' })
+await iam.user.changeCurrentUserPassword(accessToken, 'oldPass', 'newPass')
+
+// 管理操作
+const users = await iam.user.listUsers({
+  page: 1,
+  pageSize: 20,
+  search: 'alice',
+  sortBy: 'createdAt',
+  sortDirection: 'desc',
+  include: ['roles'],
+})
+await iam.user.updateUser(userId, { enabled: false }) // 禁用用户 → 自动清除会话
+await iam.user.deleteUser(userId) // 删除用户 → 事务清除角色关联
+
+// 密码重置
+await iam.user.requestPasswordReset('alice@example.com')
+await iam.user.confirmPasswordReset(token, 'NewPassword456')
+await iam.user.adminResetPassword(userId, 'TempPassword123')
+
+// 密码强度验证（同步方法）
+const valid = iam.user.validatePassword('weak')
+```
+
+#### Considerations
+
+- **`toUser()` redaction**: public users omit sensitive fields such as `passwordHash` and `loginFailedCount`.
+- **Session invalidation**: `deleteUser` / `updateUser({ enabled: false })` / `changePassword` / `confirmPasswordReset` clear all active sessions for affected users.
+- **Enumeration protection**: `requestPasswordReset` returns `ok(undefined)` for nonexistent emails instead of an error.
+- **Synchronous validatePassword**: the only synchronous method in `UserOperations`; all others are asynchronous.
+- **Fuzzy search**: `listUsers` searches username, email, phone, and display name with escaped LIKE wildcards.
+- **Server sorting**: `listUsers` allows only `username`, `email`, `displayName`, `enabled`, and `createdAt`, mapped through an allowlist; defaults to newest creation first.
+
+---
+
+### API keys — `iam.apiKey`
+
+#### Key types
+
+- **`ApiKeyOperations`**: `createApiKey` / `listApiKeys` / `getApiKey` / `revokeApiKey` / `verifyApiKey`.
+- **`ApiKey`** (public fields): `{ id, userId, name, keyPrefix, enabled, expiresAt, scopes }`.
+- **`CreateApiKeyResult`**: `{ apiKey, rawKey }`; the plaintext key is returned only once.
+
+#### Key workflows
+
+**API key verification:**
+
+```
+verifyApiKey(rawKey)
+  → Extract prefix from rawKey (prefix + first 8 characters)
+  → Query candidate keys by prefix from DB
+  → Verify each hash synchronously
+  → If valid, check expiration/disabled state
+  → Update lastUsedAt asynchronously without blocking return
+  → Return ApiKey
+```
+
+#### Usage
+
+```ts
+// 创建 API Key
+const result = await iam.apiKey.createApiKey(userId, {
+  name: 'CI/CD',
+  expirationDays: 90,
+  scopes: ['api:read'],
+})
+// result.data.rawKey → 明文密钥（仅此一次展示）
+
+// 列出用户的 API Key（服务端分页）
+const keys = await iam.apiKey.listApiKeys(userId, { page: 1, pageSize: 20, search: 'ci' })
+// keys.data → { items, total, page, pageSize }
+
+// 吊销
+await iam.apiKey.revokeApiKey(keyId)
+```
+
+#### Considerations
+
+- **No plaintext persistence**: only hashes are stored; `rawKey` at creation is the sole opportunity to retrieve it.
+- **Prefix lookup**: `keyPrefix` narrows candidates without a full table scan.
+- **Count limit**: at most `maxKeysPerUser` (default 10) keys per user.
+- **Explicit enablement**: API keys initialize only with `login.apikey: true`.
+
+---
+
+## More usage
+
+See the skill template (Chinese) for detailed API parameters, codes, and integration patterns: `packages/cli/templates/skills/hai-iam/SKILL.md`.
+
+## Frontend API calls
+
+Public HTTP APIs are defined by `@h-ai/api-contract` and called through the `@h-ai/api-client` typed client:
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({ baseUrl: '/api/v1' })
+
+// 登录
+const result = await apiClient.iam.auth.login({
+  identifier: 'admin',
+  password: 'Password123',
+})
+
+// 获取当前用户
+const user = await apiClient.iam.auth.currentUser()
+
+// 修改密码
+await apiClient.iam.auth.changePassword({
+  oldPassword: 'Password123',
+  newPassword: 'NewPassword456',
+})
+```
+
+## Password reset
+
+```ts
+// 请求重置（即使用户不存在也返回 ok，防止枚举）
+await iam.user.requestPasswordReset('admin@example.com')
+
+// 确认重置（校验令牌有效期和尝试次数 → 更新密码 → 清除所有会话）
+const result = await iam.user.confirmPasswordReset(token, 'NewPassword456')
+
+// 管理员重置（无需旧密码）
+await iam.user.adminResetPassword(userId, 'TempPassword123')
+```
+
+## One-time tickets — `iam.ticket`
+
+Short-lived capability tickets for channels that cannot carry Bearer tokens, such as WebSocket URLs. An authenticated HTTP request issues a ticket bound to a subject, purpose, and operation. The server **atomically consumes** it on first validation, making it valid only once.
+
+```ts
+// 签发（已登录 HTTP 请求内）：绑定主体、用途与本次操作，30 秒过期
+const issued = await iam.ticket.issue({
+  subjectId: session.userId,
+  purpose: 'ai-audio',
+  grant: { operation: 'transcribe', model: 'whisper-1' },
+  ttlMs: 30_000,
+})
+// issued.data.ticket 交给客户端，用于建立 WebSocket 连接
+
+// 消费（服务端建连时）：原子单次，返回主体 + 用途 + grant
+const consumed = await iam.ticket.consume(ticket, { purpose: 'ai-audio' })
+if (consumed.success) {
+  const { subjectId, grant } = consumed.data
+  // 用 grant.operation / grant.model 交叉校验客户端请求
+}
+```
+
+Features: cryptographically secure randomness, TTL, atomic single use (only one concurrent consumer succeeds), and purpose binding to prevent cross-purpose replay.
+
+## Error handling
+
+All operations return `HaiResult<T>`; branch on `HaiIamError`:
+
+```ts
+import { HaiIamError, iam } from '@h-ai/iam'
+
+const result = await iam.auth.login({ identifier: 'admin', password: 'wrong' })
+if (!result.success) {
+  if (result.error.code === HaiIamError.INVALID_CREDENTIALS.code) {
+    // 用户名或密码错误
+  }
+}
+```
+
+## Tests
+
+```bash
+pnpm test
+```
+
+## License
+
+Apache-2.0
+
+Role lists aggregate actual member counts for the current page with one `iam.authz.getRoleUserCounts(roleIds)` call, returning `HaiResult<Map<string, number>>`. Unassigned roles get 0; failed queries show loading errors rather than fabricated zero counts.

package/README.ja.md

@@ -0,0 +1,556 @@
+# @h-ai/iam
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/audit](../audit/README.ja.md) · [@h-ai/cache](../cache/README.ja.md) · [@h-ai/core](../core/README.ja.md) · [@h-ai/crypto](../crypto/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
+
+共通の `iam` オブジェクトで認証、セッション、認可、ユーザー管理を提供する Identity and Access Management モジュールです。
+
+## 機能
+
+| 機能                           | 説明                                                                                      |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| **認証**                       | パスワード、OTP（メール・SMS コード）、LDAP、API Key の認証方式                           |
+| **セッション**                 | 状態を持つセッション（ランダム access token + キャッシュ、任意の自動延長）                |
+| **認可**                       | RBAC のロール・権限管理（DB + キャッシュ、ワイルドカード照合）                            |
+| **ユーザー管理**               | 登録、検索、更新、パスワードリセット、管理者によるリセット                                |
+| **API Key**                    | scope・期限付き API Key の作成、失効、検証                                                |
+| **一度限りのチケット**         | Bearer Token を付けられない WebSocket などのための短期チケット（発行 / アトミックな消費） |
+| **フロントエンドクライアント** | 独立フロントエンド向けの HTTP API 契約                                                    |
+
+## インストール
+
+```bash
+pnpm add @h-ai/iam
+```
+
+## 依存関係
+
+- `@h-ai/reldb`：ユーザー・ロール・権限の永続化。**iam.init() より先に初期化**。
+- `@h-ai/cache`：セッション・OTP・リセット Token・権限のキャッシュ。**iam.init() より先に初期化**。
+- `@h-ai/crypto`：内部で使用するパスワードハッシュ。自動初期化。
+- `@h-ai/audit`：主要な RBAC 操作の監査記録。
+
+## クイックスタート
+
+```ts
+import { cache } from '@h-ai/cache'
+import { iam } from '@h-ai/iam'
+import { reldb } from '@h-ai/reldb'
+
+// 1. 初始化依赖
+await reldb.init({ type: 'sqlite', database: './data.db' })
+await cache.init({ type: 'memory' })
+
+// 2. 初始化 IAM（自动使用已初始化的 reldb 和 cache 单例）
+await iam.init({
+  session: { maxAge: 86400, sliding: true },
+  // OTP 回调（启用 OTP 登录时注入发送逻辑）
+  onOtpSendEmail: async (email, code) => {
+    await sendEmail(email, `验证码: ${code}`)
+  },
+  // 密码重置回调（启用密码重置时注入通知逻辑）
+  onPasswordResetRequest: async (user, token, expiresAt) => {
+    await sendEmail(user.email!, `重置链接: https://example.com/reset?token=${token}`)
+  },
+})
+
+// 2. 注册
+const userResult = await iam.user.register({
+  username: 'admin',
+  email: 'admin@example.com',
+  password: 'Password123',
+})
+
+// 3. 登录
+const loginResult = await iam.auth.login({
+  identifier: 'admin',
+  password: 'Password123',
+})
+if (loginResult.success) {
+  const { user, tokens } = loginResult.data
+}
+
+// 4. 验证令牌
+const session = await iam.auth.verifyToken(loginResult.data.tokens.accessToken)
+
+// 5. OTP 验证码登录
+await iam.auth.sendOtp('user@example.com')
+const otpResult = await iam.auth.loginWithOtp({
+  identifier: 'user@example.com',
+  code: '123456',
+})
+
+// 6. 检查权限
+const hasPermission = await iam.authz.checkPermission(
+  loginResult.data.user.id,
+  'user:read',
+)
+
+// 7. 关闭
+await iam.close()
+```
+
+`iam.config` は**機密情報をマスクした設定スナップショット**を返します。LDAP の `url` / `bindPassword` などは自動的に非表示になります。状態確認用で、元の設定の代わりにはなりません。
+
+## 設計
+
+### アーキテクチャ
+
+IAM は `iam.init()` / `iam.close()` で状態を管理する**ライフサイクル付きシングルトン**です。内部の 5 つのサブモジュールを依存順に初期化します：
+
+```
+iam.init()
+  ├─ session  （キャッシュによるセッション、DB 依存なし）
+  ├─ authz    （RBAC ロール・権限、DB + キャッシュ）
+  ├─ authn    （認証、session + authz に依存）
+  ├─ user     （ユーザー管理、session + authz + passwordStrategy に依存）
+  └─ seed     （初期データ、authz に依存）
+```
+
+各サブモジュールは class ではなく**ファクトリー + クロージャー**（`createSessionOperations(deps)` など）で作成し、getter で `iam.auth` / `iam.user` / `iam.authz` / `iam.session` / `iam.apiKey` として公開します。
+
+初期化前のサブモジュール呼び出しは `NotInitializedKit` Proxy により `NOT_INITIALIZED` を返します。
+
+### データの保存先
+
+| データ種別                                        | 保存先           | 説明                                                                                                                          |
+| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| ユーザー、ロール、権限、関連付け、API Key         | DB（6 テーブル） | `hai_iam_users`、`hai_iam_roles`、`hai_iam_permissions`、`hai_iam_role_permissions`、`hai_iam_user_roles`、`hai_iam_api_keys` |
+| セッション（accessToken → Session）               | キャッシュ       | TTL 付き、任意の自動延長                                                                                                      |
+| Token 対応（refreshToken → userId + accessToken） | キャッシュ       | 独立 key、更新後に旧 Token を即時無効化                                                                                       |
+| OTP コード                                        | キャッシュ       | TTL + 試行回数制限                                                                                                            |
+| パスワードリセット Token                          | キャッシュ       | TTL + 最大検証回数                                                                                                            |
+| API Key                                           | DB               | `hai_iam_api_keys`。平文は保存せず hash のみ。接頭辞で候補検索                                                                |
+
+---
+
+### 認証（authn）— `iam.auth`
+
+#### 主要な型
+
+- **`AuthnOperations`**：認証操作。`login` / `loginWithOtp` / `loginWithLdap` / `loginWithApiKey` / `logout` / `verifyToken` / `sendOtp` / `registerAndLogin`。
+- **`AuthStrategy`**：認証方式のインターフェース（`type` + `authenticate` + `challenge?`）。パスワード・OTP・LDAP・API Key の 4 実装。
+- **`AuthResult`**：ユーザー情報、`TokenPair`（accessToken + refreshToken）、ロール・権限を含むログイン結果。
+- **`Credentials`**：`{ type: 'password' | 'otp' | 'ldap' | 'apikey' }` と各方式の認証情報を組み合わせた共通の共用体型。
+
+#### 主要な処理
+
+**パスワードによるログイン：**
+
+```
+login(credentials)
+  → パスワードログインの有効化を確認
+  → identifier でユーザー検索（username / email / phone）
+  → 未存在なら dummy hash（固定時間でタイミング攻撃を防止）
+  → アカウントロックを確認（lockoutDuration 内で loginFailedCount >= maxLoginAttempts）
+  → パスワードハッシュ検証（@h-ai/crypto）
+  → 失敗：回数を記録し、上限でロック
+  → 成功：失敗回数をリセット
+  → 期限を確認（expirationDays > 0 なら passwordUpdatedAt）
+  → ロール + 権限を検索
+  → セッション作成（session.create → TokenPair）
+  → AuthResult { user, tokens, roles, permissions, agreements? } を返す
+```
+
+**Token の検証：**
+
+```
+verifyToken(accessToken)
+  → session.get(accessToken) → キャッシュ検索
+  → 自動延長モードなら TTL を延長
+  → Session を返す（userId、roles、permissions）
+```
+
+#### 使用方法
+
+`authz.createRole({ ..., permissionIds })` と `authz.updateRole(id, { ..., permissionIds })` は、同じトランザクションでロールと権限集合全体を保存し、途中の失敗はすべてロールバックします。`permissionIds: []` は消去、省略は維持、重複 ID は除去、不明な権限は失敗です。並行更新は最後にコミットした完全な集合を採用し、集合を合成しません。自動管理のコミット後はユーザーセッションを同期し、外部トランザクションでは呼び出し元がコミット後に同期します。Admin Console も直接この API を使い、分割更新や補償削除は行いません。
+
+```ts
+// 密码登录
+const result = await iam.auth.login({ identifier: 'admin', password: 'Password123' })
+
+// OTP 登录
+await iam.auth.sendOtp('user@example.com')
+const result = await iam.auth.loginWithOtp({ identifier: 'user@example.com', code: '123456' })
+
+// LDAP 登录（需在 init 时提供 ldapClientFactory）
+const result = await iam.auth.loginWithLdap({ username: 'jdoe', password: 'pass' })
+
+// API Key 登录（需启用 login.apikey: true）
+const result = await iam.auth.loginWithApiKey({ key: 'hai_xxxx...' })
+
+// 验证令牌
+const session = await iam.auth.verifyToken(accessToken)
+
+// 注册并登录（一站式）
+const result = await iam.auth.registerAndLogin({ username: 'new', password: 'Pass123' })
+```
+
+#### 注意点
+
+- **タイミング攻撃対策**：未存在ユーザーにも dummy password hash を実行し、応答時間をそろえます。
+- **アカウントロック**：連続 `maxLoginAttempts` 回の失敗で `lockoutDuration` 秒ロック。
+- **方式ごとの有効化**：`login.password` / `login.otp` / `login.ldap` / `login.apikey` で制御。
+- **OTP の安全性**：rejection sampling で剰余偏りを除去、定時間比較でタイミング攻撃を防ぎ、`resendInterval` で頻度制限。
+
+---
+
+### セッション（session）— `iam.session`
+
+#### 主要な型
+
+- **`SessionOperations`**：`create` / `get` / `verifyToken` / `update` / `delete` / `deleteByUserId` / `refresh` / `revokeRefresh` / `patchUserSessions`。
+- **`Session`**：userId、roles、permissions、accessToken、期限などを含むセッション。
+- **`TokenPair`**：Token のペア。`{ accessToken, refreshToken, expiresIn, tokenType: 'Bearer' }`。
+
+#### 主要な処理
+
+**Token 更新（Rotation）：**
+
+```
+refresh(refreshToken)
+  → キャッシュから refreshToken → { userId, accessToken } を取得
+  → accessToken で旧 session を取得
+  → 旧 refreshToken を削除（即時無効化で再使用防止）
+  → 旧 accessToken の session を削除
+  → 旧ユーザー context で新 session を作成
+  → 新 TokenPair を返す
+```
+
+**単一端末のログイン：**
+
+```
+create(options) [singleDevice=true]
+  → user→tokens の対応から既存の全 Token を削除
+  → 新 accessToken + refreshToken を生成
+  → session をキャッシュへ保存
+```
+
+#### 使用方法
+
+```ts
+// 创建会话（通常由 login 内部调用）
+const session = await iam.session.create({
+  userId: 'user-id',
+  username: 'admin',
+  roles: ['admin'],
+  permissions: ['user:read', 'user:write'],
+})
+
+// 验证令牌
+const session = await iam.session.verifyToken(accessToken)
+
+// 刷新令牌
+const newTokens = await iam.session.refresh(refreshToken)
+
+// 强制下线
+await iam.session.deleteByUserId(userId)
+```
+
+#### 注意点
+
+- **キャッシュのみの保存**：DB に保存せず、再起動後はすべてのセッションが無効になります（安全性の設計方針）。
+- **自動延長**：`sliding: true` なら各 `get()` で TTL を延長。
+- **Refresh Rotation**：旧 refreshToken は一度の使用で無効化。再使用は漏洩の兆候。
+- **Token 強度**：256-bit の暗号学的乱数（`crypto.getRandomValues(new Uint8Array(32))`）、base64url 形式。
+
+---
+
+### 認可（authz）— `iam.authz`
+
+#### 主要な型
+
+- **`AuthzOperations`**：ロール・権限 CRUD、ロールと権限・ユーザーとロールの割り当て、権限確認。
+- **`Role`**：ロール。`{ id, code, name, description, isSystem }`。
+- **`Permission`**：権限。`{ id, code, name, type, resource, action }`、type は `menu` / `api` / `button`。
+- **`PermissionType`**：権限種別の enum。
+
+#### 主要な処理
+
+**権限確認（`checkPermission`）：**
+
+```
+checkPermission(userId, permission)
+  → RBAC 無効なら true
+  → ユーザーのロール一覧を DB から取得
+  → 最高管理者を確認（キャッシュの superAdminRoleId）、あれば true
+  → 各ロールの権限を取得（キャッシュ優先、miss は DB から取得して保存）
+  → 厳密・ワイルドカード照合（`admin:*` は `admin:read` に一致）
+  → true / false を返す
+```
+
+**ロール・権限変更後のセッション同期：**
+
+```
+assignPermissionToRole(roleId, permId)
+  → 関連を DB に保存
+  → ロール権限のキャッシュを消去
+  → 所属ユーザー検索 → 各権限を再解決 → 活動中 session を更新
+  （best-effort：失敗は log.error のみで割り当て結果に影響しない）
+```
+
+#### 使用方法
+
+```ts
+// 角色管理
+const role = await iam.authz.createRole({ code: 'editor', name: '编辑' })
+const roles = await iam.authz.getAllRoles({ page: 1, pageSize: 20 })
+
+// 权限管理
+const perm = await iam.authz.createPermission({
+  code: 'article:publish',
+  name: '发布文章',
+  type: 'api',
+  resource: 'article',
+  action: 'publish',
+})
+
+// 分配与检查
+await iam.authz.assignRole(userId, role.data.id)
+await iam.authz.assignPermissionToRole(role.data.id, perm.data.id)
+const allowed = await iam.authz.checkPermission(userId, 'article:publish')
+
+// 批量同步角色
+await iam.authz.syncRoles(userId, [roleId1, roleId2])
+```
+
+#### 注意点
+
+- **ワイルドカード**：`admin:*` は `admin:read`、`admin:write:detail` などに一致。1 つの `*` がコロン以降全体に一致します。
+- **最高管理者**：`rbac.superAdminRole`（既定 `super_admin`）はすべての権限を持ちます。
+- **トランザクション**：`deleteRole` / `deletePermission` は DB トランザクションで関連を削除してから本体を削除。
+- **同期の遅延**：権限変更は稼働中のセッションへ best-effort で反映し、多数のユーザーでは遅延する場合があります。
+- **初期データ**：`seedDefaultData: true` で admin/user/guest と基本権限を冪等に作成。
+
+---
+
+### ユーザー管理（user）— `iam.user`
+
+#### 主要な型
+
+- **`UserOperations`**：登録、検索、更新、削除、パスワード変更・リセット、強度検証。
+- **`User`**（公開フィールド）：`{ id, username, email, phone, displayName, avatarUrl, enabled, roles? }`。
+- **`StoredUser`**：内部保存用ユーザー。`passwordHash`、`loginFailedCount`、`lockedUntil` などの機密フィールドを含みます。
+- **`RegisterOptions`** / **`RegisterResult`**：登録の入力・出力。
+- **`UpdateCurrentUserInput`**：現在のユーザーが変更できるフィールド（`displayName` / `avatarUrl` / `phone` / `metadata`）。
+
+#### 主要な処理
+
+**ユーザー登録：**
+
+```
+register(options)
+  → 登録の有効化を確認
+  → 強度検証（Zod schema + 独自ルール）
+  → パスワードハッシュ（@h-ai/crypto）
+  → DB トランザクション：作成 + 結果取得
+  → 既定ロール付与（rbac.defaultRole、トランザクション外、失敗は log のみ）
+  → RegisterResult { user, agreements? } を返す
+```
+
+**パスワードリセット：**
+
+```
+requestPasswordReset(email)
+  → メールで検索（未存在は静かに ok、列挙攻撃を防止）
+  → 256-bit ランダム Token を生成
+  → SHA-256(token) → userId をキャッシュ（TTL + maxAttempts）
+  → onPasswordResetRequest を呼ぶ（アプリがメール・SMS 送信）
+
+confirmPasswordReset(token, newPassword)
+  → SHA-256(token) を取得して期限・試行回数を検証
+  → 強度検証 → ハッシュ → DB 更新
+  → 全活動セッションを削除して再ログインを要求
+  → 使用済みリセット Token を削除
+```
+
+#### 使用方法
+
+```ts
+// 注册
+const result = await iam.user.register({
+  username: 'alice',
+  email: 'alice@example.com',
+  password: 'Password123',
+})
+
+// 当前用户操作
+const me = await iam.user.getCurrentUser(accessToken)
+await iam.user.updateCurrentUser(accessToken, { displayName: '新名称' })
+await iam.user.changeCurrentUserPassword(accessToken, 'oldPass', 'newPass')
+
+// 管理操作
+const users = await iam.user.listUsers({
+  page: 1,
+  pageSize: 20,
+  search: 'alice',
+  sortBy: 'createdAt',
+  sortDirection: 'desc',
+  include: ['roles'],
+})
+await iam.user.updateUser(userId, { enabled: false }) // 禁用用户 → 自动清除会话
+await iam.user.deleteUser(userId) // 删除用户 → 事务清除角色关联
+
+// 密码重置
+await iam.user.requestPasswordReset('alice@example.com')
+await iam.user.confirmPasswordReset(token, 'NewPassword456')
+await iam.user.adminResetPassword(userId, 'TempPassword123')
+
+// 密码强度验证（同步方法）
+const valid = iam.user.validatePassword('weak')
+```
+
+#### 注意点
+
+- **`toUser()` の機密除去**：公開ユーザー情報から `passwordHash`、`loginFailedCount` などを除外。
+- **セッション連動**：`deleteUser` / `updateUser({ enabled: false })` / `changePassword` / `confirmPasswordReset` は対象ユーザーの全セッションを削除。
+- **列挙攻撃対策**：未登録メールへの `requestPasswordReset` はエラーでなく `ok(undefined)`。
+- **validatePassword は同期**：`UserOperations` の唯一の同期メソッドで、ほかは非同期。
+- **部分一致検索**：`listUsers` はユーザー名・メール・電話・表示名を検索し、LIKE のワイルドカードはエスケープ済み。
+- **サーバー側の並び順**：`listUsers` は `username`、`email`、`displayName`、`enabled`、`createdAt` のみを許可リストで対応付け、既定は作成日時の降順。
+
+---
+
+### API Key — `iam.apiKey`
+
+#### 主要な型
+
+- **`ApiKeyOperations`**：`createApiKey` / `listApiKeys` / `getApiKey` / `revokeApiKey` / `verifyApiKey`。
+- **`ApiKey`**（公開フィールド）：`{ id, userId, name, keyPrefix, enabled, expiresAt, scopes }`。
+- **`CreateApiKeyResult`**：`{ apiKey, rawKey }`。平文の鍵を返すのは一度のみ。
+
+#### 主要な処理
+
+**API Key の検証：**
+
+```
+verifyApiKey(rawKey)
+  → rawKey から接頭辞取得（prefix + 最初の 8 文字）
+  → DB で接頭辞による候補検索
+  → 各 hash を同期検証
+  → 成功後に期限・無効化を確認
+  → lastUsedAt を非同期更新（応答をブロックしない）
+  → ApiKey を返す
+```
+
+#### 使用方法
+
+```ts
+// 创建 API Key
+const result = await iam.apiKey.createApiKey(userId, {
+  name: 'CI/CD',
+  expirationDays: 90,
+  scopes: ['api:read'],
+})
+// result.data.rawKey → 明文密钥（仅此一次展示）
+
+// 列出用户的 API Key（服务端分页）
+const keys = await iam.apiKey.listApiKeys(userId, { page: 1, pageSize: 20, search: 'ci' })
+// keys.data → { items, total, page, pageSize }
+
+// 吊销
+await iam.apiKey.revokeApiKey(keyId)
+```
+
+#### 注意点
+
+- **平文は保存しない**：DB は hash のみを保存し、作成時の `rawKey` が唯一の取得機会。
+- **接頭辞検索**：`keyPrefix` で候補を絞り、全テーブル走査を避けます。
+- **件数制限**：ユーザーあたり最大 `maxKeysPerUser`（既定 10）件。
+- **明示的有効化**：`login.apikey: true` の場合のみ初期化。
+
+---
+
+## その他の使い方
+
+API 引数・エラーコード・統合パターンの詳細は中国語の Skill テンプレート（`packages/cli/templates/skills/hai-iam/SKILL.md`）を参照してください。
+
+## フロントエンドの API 呼び出し
+
+公開 HTTP API は `@h-ai/api-contract` で定義し、`@h-ai/api-client` の型付きクライアントで呼び出します：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({ baseUrl: '/api/v1' })
+
+// 登录
+const result = await apiClient.iam.auth.login({
+  identifier: 'admin',
+  password: 'Password123',
+})
+
+// 获取当前用户
+const user = await apiClient.iam.auth.currentUser()
+
+// 修改密码
+await apiClient.iam.auth.changePassword({
+  oldPassword: 'Password123',
+  newPassword: 'NewPassword456',
+})
+```
+
+## パスワードリセット
+
+```ts
+// 请求重置（即使用户不存在也返回 ok，防止枚举）
+await iam.user.requestPasswordReset('admin@example.com')
+
+// 确认重置（校验令牌有效期和尝试次数 → 更新密码 → 清除所有会话）
+const result = await iam.user.confirmPasswordReset(token, 'NewPassword456')
+
+// 管理员重置（无需旧密码）
+await iam.user.adminResetPassword(userId, 'TempPassword123')
+```
+
+## 一度限りのチケット — `iam.ticket`
+
+WebSocket URL など Bearer Token を付けられない経路向けの短期チケットです。認証済み HTTP リクエストで、主体・用途・操作に結び付けて発行します。サーバーは初回検証時に**アトミックに消費**し、一度のみ有効です。
+
+```ts
+// 签发（已登录 HTTP 请求内）：绑定主体、用途与本次操作，30 秒过期
+const issued = await iam.ticket.issue({
+  subjectId: session.userId,
+  purpose: 'ai-audio',
+  grant: { operation: 'transcribe', model: 'whisper-1' },
+  ttlMs: 30_000,
+})
+// issued.data.ticket 交给客户端，用于建立 WebSocket 连接
+
+// 消费（服务端建连时）：原子单次，返回主体 + 用途 + grant
+const consumed = await iam.ticket.consume(ticket, { purpose: 'ai-audio' })
+if (consumed.success) {
+  const { subjectId, grant } = consumed.data
+  // 用 grant.operation / grant.model 交叉校验客户端请求
+}
+```
+
+特徴：暗号学的に安全な乱数、TTL、アトミックな単回消費（並行消費では 1 件のみ成功）、用途の固定による別用途の再使用防止。
+
+## エラー処理
+
+すべての操作は `HaiResult<T>` を返し、`HaiIamError` で分岐します：
+
+```ts
+import { HaiIamError, iam } from '@h-ai/iam'
+
+const result = await iam.auth.login({ identifier: 'admin', password: 'wrong' })
+if (!result.success) {
+  if (result.error.code === HaiIamError.INVALID_CREDENTIALS.code) {
+    // 用户名或密码错误
+  }
+}
+```
+
+## テスト
+
+```bash
+pnpm test
+```
+
+## ライセンス
+
+Apache-2.0
+
+ロール一覧は `iam.authz.getRoleUserCounts(roleIds)` の 1 回の集計で現在のページの実際の所属人数を取得し、`HaiResult<Map<string, number>>` を返します。関連がなければ 0、検索失敗は読み込みエラーを表示し、0 件の統計を作りません。

package/README.md

@@ -1,5 +1,9 @@
 # @h-ai/iam
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/audit](../audit/README.md) · [@h-ai/cache](../cache/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/crypto](../crypto/README.md) · [@h-ai/reldb](../reldb/README.md)
+
 身份与访问管理模块，提供统一的 `iam` 对象实现认证、会话、授权与用户管理。
 
 ## 功能特性

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/iam",
   "type": "module",
-  "version": "0.1.0-alpha.55",
+  "version": "0.1.0-alpha.57",
   "description": "Hai Framework identity and access management module.",
   "license": "Apache-2.0",
   "exports": {
@@ -26,11 +26,11 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@h-ai/audit": "0.1.0-alpha.55",
-    "@h-ai/cache": "0.1.0-alpha.55",
-    "@h-ai/core": "0.1.0-alpha.55",
-    "@h-ai/reldb": "0.1.0-alpha.55",
-    "@h-ai/crypto": "0.1.0-alpha.55"
+    "@h-ai/audit": "0.1.0-alpha.57",
+    "@h-ai/cache": "0.1.0-alpha.57",
+    "@h-ai/core": "0.1.0-alpha.57",
+    "@h-ai/reldb": "0.1.0-alpha.57",
+    "@h-ai/crypto": "0.1.0-alpha.57"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",