@h-ai/iam 0.1.0-alpha.66 → 0.1.0-alpha.68

package/README.en.md

@@ -4,9 +4,11 @@
 
 [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) · [@h-ai/reach](../reach/README.en.md)
 
+## Introduction
+
 Identity and access management through a unified `iam` object for authentication, sessions, authorization, and user management.
 
-## Features
+## Core features
 
 | Feature              | Description                                                                                                            |
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -18,27 +20,29 @@ Identity and access management through a unified `iam` object for authentication
 | **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
+## Getting started
+
+### Installation
 
 ```bash
 pnpm add @h-ai/iam
 ```
 
-## Dependencies
+### Dependencies
 
 - `@h-ai/reldb`: persistence for users/roles/permissions; **initialize before iam.init()**.
-- `@h-ai/cache`: sessions/OTP/reset tokens/one-time tickets/shared locks; **initialize before iam.init()**.
+- `@h-ai/cache`: sessions/OTP/one-time tickets; **initialize before iam.init()**.
 - `@h-ai/crypto`: password hashing, used internally and initialized automatically.
 - `@h-ai/audit`: audit records for key RBAC operations.
 
 - `@h-ai/reach`: **optional**, installed, initialized and injected by the application for standard notifications; custom callbacks do not require Reach.
 - `ldapts`: **optional**, loaded only when LDAP is explicitly enabled without an injected `ldapClientFactory`.
 
-## Optional LDAP and notifications
+### Optional LDAP and notifications
 
 Password authentication, users and RBAC work without LDAP or Reach. Both are optional peer dependencies: install only the integrations you use. The snippets below run inside application startup/authentication functions after reldb/cache initialization; `username/password` are validated input.
 
-### LDAP / Active Directory
+#### LDAP / Active Directory
 
 For the default client run `pnpm add ldapts`, then explicitly set `login.ldap: true` and connection settings. Connection settings alone do not enable LDAP. Enabling the default client without the SDK returns an initialization configuration error.
 
@@ -58,7 +62,7 @@ ldap:
   connectTimeout: 5000
 ```
 
-`ldaps://` uses TLS; `ldap://` with `useTls: true` uses StartTLS. For Active Directory use `searchFilter: "(sAMAccountName={{username}})"` and `usernameAttribute: sAMAccountName`; the username placeholder is escaped before searching. First login synchronizes a local user and assigns the default role; disabled accounts and lockouts still apply. Set `ldapSyncUser: false` or inject a `ldapClientFactory` returning `bind/search/unbind` methods with HaiResult results. An injected factory does not require ldapts.
+`ldaps://` uses TLS; `ldap://` with `useTls: true` uses StartTLS. For Active Directory use `searchFilter: "(sAMAccountName={{username}})"` and `usernameAttribute: sAMAccountName`; the username placeholder is escaped before searching. First login synchronizes a local user and assigns the default role; disabled accounts and lockouts still apply. `ldapSyncUser: false` requires an existing enabled local user with a database credential generation; no virtual DN user is created. You may inject a `ldapClientFactory` returning `bind/search/unbind` methods with HaiResult results. An injected factory does not require ldapts.
 
 ```ts
 import type { IamConfigSettingsInput } from '@h-ai/iam'
@@ -75,7 +79,7 @@ if (!result.success)
 return result
 ```
 
-### Automatic delivery with optional Reach
+#### Automatic delivery with optional Reach
 
 Run `pnpm add @h-ai/reach`. The application configures, initializes and closes Reach; IAM uses only the injected instance. These SMTP/HTTP providers are examples; the SMS gateway accepts the [Reach notification interface](../reach/README.en.md). Console logs metadata and does not deliver messages.
 
@@ -133,7 +137,7 @@ if (!initialized.success)
 return iam.auth.sendOtp('user@example.com')
 ```
 
-### Custom email and SMS delivery
+#### Custom email and SMS delivery
 
 Inject `onOtpSendEmail`, `onOtpSendSms` and `onPasswordResetRequest` to use existing application services. Implement only needed callbacks or mix them with Reach; explicit callbacks take priority. These services are application implementations whose promises resolve only after successful delivery. If a service returns HaiResult, check `success` and throw inside the callback on failure. IAM catches callback exceptions and returns a business error without exposing codes, tokens or internal delivery details.
 
@@ -145,26 +149,26 @@ import { mailService, smsService } from './notifications.js'
 // 调用方须检查服务投递结果，失败时拒绝 Promise，不能吞掉错误。
 const initialized = await iam.init({
   otp: { email: true, sms: true },
-  onOtpSendEmail: async (email, code) => {
-    await mailService.send({ to: email, subject: 'Verification code', text: code })
+  onOtpSendEmail: async (email, code, context) => {
+    await mailService.send({ to: email, subject: 'Verification code', text: code, idempotencyKey: context.idempotencyKey })
   },
-  onOtpSendSms: async (phone, code) => {
-    await smsService.send({ to: phone, code })
+  onOtpSendSms: async (phone, code, context) => {
+    await smsService.send({ to: phone, code, idempotencyKey: context.idempotencyKey })
   },
   passwordReset: { mode: 'email' },
-  onPasswordResetRequest: async (user, token, expiresAt) => {
+  onPasswordResetRequest: async (user, token, context) => {
     if (!user.email)
       throw new Error('Reset recipient unavailable')
     const url = new URL('https://app.example.com/auth/reset-password')
     url.searchParams.set('token', token)
-    await mailService.send({ to: user.email, subject: 'Password reset', text: url.toString(), expiresAt })
+    await mailService.send({ to: user.email, subject: 'Password reset', text: url.toString(), expiresAt: context.expiresAt, idempotencyKey: context.idempotencyKey })
   },
 })
 if (!initialized.success)
   return initialized
 ```
 
-## Quick start
+### Quick start
 
 ```ts
 import { cache } from '@h-ai/cache'
@@ -209,9 +213,9 @@ LDAP is disabled by default. Public OTP methods require `otp` settings and send
 
 `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
+### Design
 
-### Architecture
+#### Architecture
 
 IAM is a **lifecycle singleton** managed through `iam.init()` / `iam.close()`. Five internal subsystems initialize in dependency order:
 
@@ -228,29 +232,29 @@ All subsystems use **factories + closures** (for example `createSessionOperation
 
 Before initialization, every subsystem method returns `NOT_INITIALIZED` through a `NotInitializedKit` proxy.
 
-### Data storage
+#### Data storage
 
-| Data                                                | Storage                                      | Description                                                                                                                   |
-| --------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Users, roles, permissions, associations, API keys   | DB (5 base tables, 1 optional API Key table) | `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                                             |
+| Data                                              | Storage                                      | Description                                                                                                                   |
+| ------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Users, roles, permissions, associations, API keys | DB (5 base tables, 1 optional API Key table) | `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                                                                                                 |
+| Refresh state                                     | Redis user partition                         | Atomic with session/index                                                                                                     |
+| OTP codes                                         | Cache                                        | TTL + attempt limit                                                                                                           |
+| Password reset tokens                             | User database row                            | SM3 hash, DB expiry, attempts and conditional password commit                                                                 |
+| API Key                                           | DB                                           | `hai_iam_api_keys`; store hashes only, never plaintext; prefix narrows candidates                                             |
 
 ---
 
-### Authentication (authn) — `iam.auth`
+#### Authentication (authn) — `iam.auth`
 
-#### Key types
+##### 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
+##### Key workflows
 
 **Password login:**
 
@@ -274,13 +278,14 @@ login(credentials)
 ```
 verifyToken(accessToken)
   → session.get(accessToken) → cache lookup
+  → Read the persistent user and validate enabled status and the session-bound credentialVersion
   → Extend TTL automatically when sliding renewal is enabled
-  → Read current user status, role JOIN and one batched permission query (skip permissions for no roles)
-  → Reject disabled users or database failures; intersect API Key scopes again
+  → Read the current user again, recheck enabled status and credentialVersion, then read the role JOIN and batched permissions (skip permissions for no roles)
+  → Reject any persistent read failure, missing/disabled user or credential-version mismatch; intersect API Key scopes again
   → Return current Session (userId, roles, permissions)
 ```
 
-#### Usage
+##### Usage
 
 These examples run on the server after successful reldb/cache/IAM initialization, with validated request input. Password login is available by default. OTP requires `login.otp: true`, an `otp` channel and delivery callbacks/Reach templates; LDAP requires `login.ldap: true` (see configuration above); API Key requires `login.apikey: true` (see the complete flow below). Login returns `AuthResult`; registration with login returns the same authentication structure. Registration and password login have separate switches.
 
@@ -312,47 +317,47 @@ async function registerWithSession(username: string, password: string) {
 }
 ```
 
-#### Considerations
+##### 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.
 
+`iam.auth.logout(accessToken)` uses the complete opaque token to revoke its access and refresh credentials in one user-partition CAS, including when access has expired. Invalid or absent tokens are idempotent successes. Cache read/commit failures return failure and can be retried with the same token after recovery. The HTTP endpoint revokes only a possessed token, accepts no userId target and does not require a still-authenticated access token. Callers must inspect `success`; clearing local cookies or secure storage is not confirmation of server revocation and failures must be shown.
+
 ---
 
-### Sessions (session) — `iam.session`
+#### Sessions (session) — `iam.session`
 
-#### Key types
+##### 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
+##### 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
+  → Read the user partition and session version; validate authorization
+  → Build candidate tokens without publishing them
+  → Single-key CAS rechecks version/refresh and atomically replaces the old session
+  → Return the unique successor only after commit
 ```
 
 **Single-device login:**
 
 ```
 create(options) [singleDevice=true]
-  → Clear all existing user tokens via user→tokens mapping
-  → Generate new accessToken + refreshToken
-  → Store session in cache
+  → Build candidate accessToken + refreshToken
+  → Single-key CAS replaces all old sessions and their index together
+  → Failed commits preserve the previous session
 ```
 
-#### Usage
+##### Usage
 
 Use `tokens.accessToken` to authenticate requests and `tokens.refreshToken` to obtain a new pair; `expiresIn` is measured in seconds. Independent APIs use `Authorization: Bearer <accessToken>`. For SvelteKit Cookie endpoints, use kit's standard authentication integration described below.
 
@@ -387,27 +392,35 @@ async function forceSignOut(userId: string) {
 }
 ```
 
-#### Considerations
+##### Considerations
 
 - **Cache-only storage**: Memory sessions are lost on restart; shared Redis sessions survive IAM service restarts until TTL or revocation.
 - **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.
 
+`create({ maxAge })` overrides the configured default with a positive safe integer in seconds, persisted as `Session.maxAge`. Issuance and refresh return that duration in `expiresIn`. Sliding renewal uses this duration and returns committed `lastActiveAt/expiresAt`; delayed requests cannot shorten a newer renewal. Explicit `update` applies valid date patches and creates a new content version. Clients schedule refresh from the returned `expiresIn` rather than a hardcoded default.
+
+Access and refresh expire independently. The user partition remains until the latest live access/refresh deadline, while access authentication checks only its own `expiresAt`. An expired access token can still be rotated with a live refresh token. Each rotation starts a new `refreshTokenMaxAge` period and invalidates both old credentials. Access deletion, logoutAll and single-device replacement also revoke refresh-only records; revokeRefresh preserves a still-live access token. Refresh routes validate refresh credentials without requiring a live access token first.
+
+Session cache read/commit failures return failed HaiResult values, never absence/expiry or cleanup compensation. Sessions and their index share one document, so batch updates no longer use per-token get/ttl calls or a separate index; cleanup uses confirmed absolute deadlines only. After recovery, re-read and retry updates/logout; logoutAll still covers every original record. Malformed state fails closed and is preserved for operator repair instead of being overwritten with an empty document.
+
+Session.credentialVersion binds the database credential generation at creation. Only trusted authenticated strategies supply CreateSessionOptions.expectedCredentialVersion, and stale generations fail. Low-level create without that option still reads a real enabled local user and binds its current generation; it cannot create an authenticated identity without a database record.
+
 ---
 
-### Authorization (authz) — `iam.authz`
+#### Authorization (authz) — `iam.authz`
 
 Role lists use `iam.authz.getRoleUserCounts(roleIds)` to aggregate actual membership for the current page in one query, returning `HaiResult<Map<string, number>>`. Missing relations mean zero; query failures display an error instead of invented zero counts.
 
-#### Key types
+##### 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
+##### Key workflows
 
 **Permission checks (`checkPermission`):**
 
@@ -430,7 +443,7 @@ assignPermissionToRole(roleId, permId)
   (best-effort: failures only log.error; permission assignment still succeeds)
 ```
 
-#### Usage
+##### Usage
 
 Create permissions, save permission **IDs** through the role's `permissionIds`, and assign a role by its **ID**. Session roles/permissions and guards use stable **codes**; display names can change independently. These examples assume RBAC is enabled. Applications must authorize administrative operations and check resource access before calling them.
 
@@ -478,19 +491,19 @@ async function currentAuthorization(userId: string) {
 }
 ```
 
-#### Considerations
+##### 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**: cache updates are best-effort. Protected requests use `iam.auth.verifyToken` to read current user status and authorization and reject read failures. `iam.session.verifyToken` validates a session snapshot only. `iam.authz.getUserAuthorization(userId)` shares the role JOIN and batched permission query.
+- **Session synchronization**: cache updates are best-effort. Protected requests use `iam.auth.verifyToken` to validate the session-bound persistent credential version, then recheck current user status and credential version and read fresh authorization. Failure at either read rejects authentication. `iam.session.get/verifyToken` also checks persistent user enabled status and `credentialVersion`, but its role/permission fields remain a session snapshot and do not replace current authorization. `iam.authz.getUserAuthorization(userId)` shares the role JOIN and batched permission query.
 - **Seed data**: `seedDefaultData: true` idempotently creates admin/user/guest roles and basic permissions.
 
 ---
 
-### Users (user) — `iam.user`
+#### Users (user) — `iam.user`
 
-#### Key types
+##### 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? }`.
@@ -498,7 +511,7 @@ async function currentAuthorization(userId: string) {
 - **`RegisterOptions`** / **`RegisterResult`**: registration input/output.
 - **`UpdateCurrentUserInput`**: fields the current user may change (`username` / `email` / `displayName` / `avatarUrl` / `phone` / `metadata`).
 
-#### Key workflows
+##### Key workflows
 
 **User registration:**
 
@@ -528,7 +541,7 @@ confirmPasswordReset(token, newPassword)
   → Delete consumed reset token
 ```
 
-#### Usage
+##### Usage
 
 `register` returns a user without a session; use `auth.registerAndLogin` when both are needed. `createUser` is an administrative operation independent of self-registration settings. Use `getCurrentUser/updateCurrentUser` for profile fields: username/email/displayName/avatarUrl/phone/metadata. Security fields and roles require authorized administrative operations.
 
@@ -586,7 +599,7 @@ async function disableUser(userId: string) {
 }
 ```
 
-#### Considerations
+##### 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.
@@ -597,17 +610,17 @@ async function disableUser(userId: string) {
 
 ---
 
-### API keys — `iam.apiKey`
+#### API keys — `iam.apiKey`
 
 `scopes` intersect the subject's permissions and support `*` and namespace `:*`. The default empty array grants identity only, without operation permissions. Restricted keys have empty session `roles` and use permission guards; explicit `*` never exceeds subject authorization. API Key login binds the key ID: get/verifyToken/refresh recheck its persistent state and reject revoked, disabled, expired keys or DB failures. Standalone verifyApiKey returns verified key metadata and still requires subject/operation authorization.
 
-#### Key types
+##### 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
+##### Key workflows
 
 **API key verification:**
 
@@ -621,7 +634,7 @@ verifyApiKey(rawKey)
   → Return ApiKey
 ```
 
-#### Usage
+##### Usage
 
 Enable API Key during initialization. A Key is a restricted user credential: **effective permissions = current subject permissions ∩ scopes**. Scopes use permission codes, not role/display names or resource IDs. They neither create permissions nor replace tenant/record ownership checks.
 
@@ -707,7 +720,7 @@ Key-derived sessions remain bound to the Key when refreshed through `iam.session
 
 `expirationDays: 0` means no expiration; omission uses `apikey.defaultExpirationDays`. Set an explicit duration for time-limited access. Never put raw Keys or Tokens in URLs, logs, public configuration or ordinary localStorage.
 
-#### Considerations
+##### 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.
@@ -716,11 +729,11 @@ Key-derived sessions remain bound to the Key when refreshed through `iam.session
 
 ---
 
-## More usage
+### 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
+### Frontend API calls
 
 Public HTTP APIs are defined by `@h-ai/api-contract` and called through the `@h-ai/api-client` typed client:
 
@@ -745,7 +758,9 @@ await apiClient.iam.auth.changePassword({
 })
 ```
 
-## Password reset
+The browser entry exports configuration schemas, types and HaiIamError, without the server `iam` instance. Authenticate through the HTTP/typed client.
+
+### Password reset
 
 Password reset requires `passwordReset.enabled` and a working delivery callback/Reach template. Success does not prove that the account exists or the recipient received a message. Handle delivery/internal failures through HaiResult. Reset tokens expire, limit attempts, and permit one successful consumption; success revokes old sessions. Administrator resets do not require the old password, but applications must authorize the administrator.
 
@@ -768,7 +783,9 @@ async function resetByAdministrator(userId: string, newPassword: string) {
 }
 ```
 
-## One-time tickets — `iam.ticket`
+Cache cleanup may return a failure after the new password and credential generation have committed; they are not rolled back. Sign in again instead of automatically retrying with old credentials.
+
+### 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.
 
@@ -801,7 +818,9 @@ async function consumeAudioTicket(ticket: string) {
 
 Features: cryptographically secure randomness, TTL, atomic single use (only one concurrent consumer succeeds), and purpose binding to prevent cross-purpose replay.
 
-## Configuration driven authentication
+### Configuration driven authentication
+
+Password login submits only `identifier` and `password`; `AuthPanel` maps the `LoginForm` field `username` to `identifier`. Server settings `session.maxAge` / `session.refreshTokenMaxAge` control session lifetimes. The login form has no per-login persistent-session option.
 
 `iam.publicConfig` and the client's `client.iam.auth.publicConfig()` HTTP contract expose a safe configuration whitelist and only advertise configured, available methods. `login.password/otp/ldap`, `otp.email/sms`, `register.enabled/defaultEnabled`, `passwordReset.enabled/mode/resetUrl` and agreement display flags are independent. `ui` configures card/split layout, title, subtitle, brand text, Logo and illustration URLs. Browser links only accept HTTP(S). LDAP is optional and disabled by default; install ldapts only for the default client, or inject a custom factory.
 
@@ -811,13 +830,13 @@ SvelteKit routes export handlers from `kit.auth.createApi(iam)`; use `kit.auth.p
 
 Agreements open in a Modal without losing form input. URL pages must allow iframe embedding; scripts are disabled and a new-window fallback is available. LoginForm/RegisterForm expose `header/extraFields/footer` snippets. AuthPanel forwards `loginHeader/loginFields/loginFooter` and `registerHeader/registerFields/registerFooter`; application state and actions handle additional fields. See [UI usage](../ui/README.en.md#configuration-driven-authentication).
 
-All nodes must share a database and Redis. Memory is limited to one process. Login counters and lock expiry use atomic database updates. OTP attempt limits, resend intervals and consumption use shared state; consuming/exhausting a code does not reset the resend interval. Reset TTL and attempt limits use shared cache and per-user locks: policy failures count, only the newest token is valid, and concurrent use succeeds once. Reset revokes old sessions and clears login locks. Disabled users cannot authenticate. Server password policy is authoritative.
+All nodes share the same database and Redis; Memory is for single-process tests. OTP code, attempts and cooldown share one identity key with CAS publication and consumption. Conflicts reject stale generations and consumption preserves cooldown. Password reset hash, expiry, attempts and resetVersion live in the user database row. Policy failures count, and one conditional SQL statement changes the password, consumes the token and advances credentialVersion. New tokens, later attempts, disablement or expiry reject delayed commits. Requesting a reset only advances resetVersion; successful password changes advance credentialVersion. Authentication captures the verified credential generation; session creation, authentication and refresh check the current database generation, so failed cache cleanup cannot authorize old sessions. Notification callbacks run after publication and receive { expiresAt, idempotencyKey } as their third argument. Applications and Reach providers must durably deduplicate that key. Exceptions/timeouts mean delivery may have succeeded: the result is unknown, with no automatic resend or rollback. Exactly-once external effects require receiver-side idempotency.
 
 Standard endpoints: `GET /auth/config`, `POST /auth/login/ldap`, `POST /auth/password-reset/request`, `POST /auth/password-reset/confirm`. Security errors: `SECURITY_BUSY (hai:iam:023)` and `PASSWORD_RESET_DISABLED (hai:iam:024)`. Declare optional fields such as `ldap` in YAML before overriding them, or replace the module configuration with a JSON value in `HAI_IAM`. Existing fields support overrides such as `HAI_IAM_LOGIN_OTP`.
 
 `passwordReset.mode` selects `email` (default, `password_reset`) or `phone` (`password_reset_sms`); the public config tells the recovery form which identifier to request.
 
-### Markdown agreements
+#### Markdown agreements
 
 Configure `agreements.userAgreementMarkdown` and `privacyPolicyMarkdown` to load agreement content directly from configuration. YAML `|` preserves paragraphs and newlines. The modal reuses the safe MarkdownRenderer with raw HTML, scripts and code tools disabled. Markdown takes priority over a URL for the same agreement; a URL remains an optional external-view link. URL-only agreements use a sandboxed iframe.
 
@@ -840,7 +859,7 @@ agreements:
   # privacyPolicyUrl: https://example.com/privacy
 ```
 
-## Error handling
+### Error handling
 
 All operations return `HaiResult<T>`; branch on `HaiIamError`:
 
@@ -855,14 +874,26 @@ if (!result.success) {
 }
 ```
 
-## Tests
+### Optional integrations
+
+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.
+
+Sessions and refresh consumption share one versioned `hai:iam:sessions:{SHA256(userId)}` document, replacing separate mappings/indexes. Bearer tokens contain an untrusted routing hint plus 256 random bits; clients must treat them as opaque strings. Rotation checks `Session.version` at commit. Memory is for single-process tests; production nodes share Redis, including Cluster. Conflicts retry from the latest state and return CONFLICT when exhausted; one refresh cannot publish two successors. An ambiguous lost response requires failing closed and signing in again, without assuming the old token remains valid. All records remain covered by the same user index.
+
+`iam.session.update(token, patch, expectedVersion)` requires the Session.version from the read. Stale versions return CONFLICT; revoked tokens return SESSION_NOT_FOUND. Timestamp-only sliding updates keep the content version, allowing normal parallel requests. Batch permission updates bind the initial token/version set and never apply delayed snapshots to later sign-ins; newer content versions require re-reading authorization before retry.
+
+## Development and testing
+
+Public examples import from `@h-ai/iam` and distinguish defaultable `IamConfigInput` from parsed `IamConfig`. Initialize server dependencies, check `HaiResult.success`, update sessions with their observed `version`, and reuse persistent notification idempotency keys. Strategy/repository examples marked as internal context do not define application deep imports. The checker verifies types only; Redis/database, LDAP and delivery behavior still require their integration tests. See the [JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
 
 ```bash
-pnpm test
+pnpm --filter @h-ai/iam typecheck
+pnpm --filter @h-ai/iam lint
+pnpm --filter @h-ai/iam build
+pnpm --filter @h-ai/iam test
+node scripts/check-module-jsdoc.mjs --package iam
 ```
 
 ## 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.