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

package/dist/browser.d.ts

@@ -0,0 +1,2320 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult, PaginationOptionsInput, PaginatedResult } from '@h-ai/core';
+import { ReachFunctions } from '@h-ai/reach';
+import { DmlWithTxOperations } from '@h-ai/reldb';
+
+/**
+ * @h-ai/iam — 配置 Schema
+ *
+ * 本文件定义 IAM 模块的配置结构，使用 Zod 进行运行时校验。
+ * @module iam-config
+ */
+
+/**
+ * 认证策略类型
+ *
+ * 支持的认证方式：
+ * - `password` - 用户名/邮箱 + 密码
+ * - `otp` - 邮箱/短信 + 验证码
+ * - `ldap` - LDAP 目录认证
+ * - `apikey` - API Key 认证并按 scopes 收敛权限
+ * @example
+ * ```ts
+ * import { AuthStrategyTypeSchema } from '@h-ai/iam'
+ * const result = AuthStrategyTypeSchema.safeParse('password')
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const AuthStrategyTypeSchema: z.ZodEnum<{
+    password: "password";
+    otp: "otp";
+    ldap: "ldap";
+    apikey: "apikey";
+}>;
+/**
+ * 认证策略类型
+ * @example
+ * ```ts
+ * import { AuthStrategyTypeSchema, type AuthStrategyType } from '@h-ai/iam'
+ * const value: AuthStrategyType = AuthStrategyTypeSchema.parse('password')
+ * ```
+ */
+type AuthStrategyType = z.infer<typeof AuthStrategyTypeSchema>;
+/**
+ * 密码配置 Schema
+ * @example
+ * ```ts
+ * import { PasswordConfigSchema } from '@h-ai/iam'
+ * const result = PasswordConfigSchema.safeParse({ minLength: 12, requireSpecialChar: true })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const PasswordConfigSchema: z.ZodObject<{
+    minLength: z.ZodDefault<z.ZodNumber>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    requireUppercase: z.ZodDefault<z.ZodBoolean>;
+    requireLowercase: z.ZodDefault<z.ZodBoolean>;
+    requireNumber: z.ZodDefault<z.ZodBoolean>;
+    requireSpecialChar: z.ZodDefault<z.ZodBoolean>;
+    expirationDays: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 密码配置类型
+ * @example
+ * ```ts
+ * import { PasswordConfigSchema, type PasswordConfig } from '@h-ai/iam'
+ * const value: PasswordConfig = PasswordConfigSchema.parse({ minLength: 12, requireSpecialChar: true })
+ * ```
+ */
+type PasswordConfig = z.infer<typeof PasswordConfigSchema>;
+/**
+ * OTP 配置 Schema
+ * @example
+ * ```ts
+ * import { OtpConfigSchema } from '@h-ai/iam'
+ * const result = OtpConfigSchema.safeParse({ email: true, sms: false, length: 6 })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const OtpConfigSchema: z.ZodObject<{
+    email: z.ZodDefault<z.ZodBoolean>;
+    sms: z.ZodDefault<z.ZodBoolean>;
+    length: z.ZodDefault<z.ZodNumber>;
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+    resendInterval: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * OTP 配置类型
+ * @example
+ * ```ts
+ * import { OtpConfigSchema, type OtpConfig } from '@h-ai/iam'
+ * const value: OtpConfig = OtpConfigSchema.parse({ email: true, sms: false, length: 6 })
+ * ```
+ */
+type OtpConfig = z.infer<typeof OtpConfigSchema>;
+/**
+ * 密码重置配置 Schema
+ * @example
+ * ```ts
+ * import { PasswordResetConfigSchema } from '@h-ai/iam'
+ * const result = PasswordResetConfigSchema.safeParse({ enabled: true, mode: 'email', resetUrl: 'https://app.example.com/reset-password' })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const PasswordResetConfigSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        email: "email";
+        phone: "phone";
+    }>>;
+    resetUrl: z.ZodOptional<z.ZodURL>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    tokenExpiresIn: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 密码重置配置类型
+ * @example
+ * ```ts
+ * import { PasswordResetConfigSchema, type PasswordResetConfig } from '@h-ai/iam'
+ * const value: PasswordResetConfig = PasswordResetConfigSchema.parse({ enabled: true, mode: 'email', resetUrl: 'https://app.example.com/reset-password' })
+ * ```
+ */
+type PasswordResetConfig = z.infer<typeof PasswordResetConfigSchema>;
+/**
+ * LDAP 配置 Schema
+ * @example
+ * ```ts
+ * import { LdapConfigSchema } from '@h-ai/iam'
+ * const bindPassword = process.env.LDAP_BIND_PASSWORD
+ * if (bindPassword) {
+ *   const result = LdapConfigSchema.safeParse({ url: 'ldaps://directory.example.com', bindDn: 'cn=service,dc=example,dc=com', bindPassword: bindPassword, searchBase: 'ou=users,dc=example,dc=com' })
+ *   if (result.success)
+ *     result.data.searchBase
+ * }
+ * ```
+ */
+declare const LdapConfigSchema: z.ZodObject<{
+    url: z.ZodURL;
+    bindDn: z.ZodString;
+    bindPassword: z.ZodString;
+    searchBase: z.ZodString;
+    searchFilter: z.ZodDefault<z.ZodString>;
+    usernameAttribute: z.ZodDefault<z.ZodString>;
+    emailAttribute: z.ZodDefault<z.ZodString>;
+    displayNameAttribute: z.ZodDefault<z.ZodString>;
+    useTls: z.ZodDefault<z.ZodBoolean>;
+    connectTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * LDAP 配置类型
+ * @example
+ * ```ts
+ * import { LdapConfigSchema, type LdapConfig } from '@h-ai/iam'
+ * const bindPassword = process.env.LDAP_BIND_PASSWORD
+ * if (bindPassword) {
+ *   const value: LdapConfig = LdapConfigSchema.parse({ url: 'ldaps://directory.example.com', bindDn: 'cn=service,dc=example,dc=com', bindPassword: bindPassword, searchBase: 'ou=users,dc=example,dc=com' })
+ *   value.url
+ * }
+ * ```
+ */
+type LdapConfig = z.infer<typeof LdapConfigSchema>;
+/**
+ * API Key 配置 Schema
+ * @example
+ * ```ts
+ * import { ApiKeyConfigSchema } from '@h-ai/iam'
+ * const result = ApiKeyConfigSchema.safeParse({ maxKeysPerUser: 5, defaultExpirationDays: 30 })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const ApiKeyConfigSchema: z.ZodObject<{
+    maxKeysPerUser: z.ZodDefault<z.ZodNumber>;
+    defaultExpirationDays: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * API Key 配置类型
+ * @example
+ * ```ts
+ * import { ApiKeyConfigSchema, type ApiKeyConfig } from '@h-ai/iam'
+ * const value: ApiKeyConfig = ApiKeyConfigSchema.parse({ maxKeysPerUser: 5, defaultExpirationDays: 30 })
+ * ```
+ */
+type ApiKeyConfig = z.infer<typeof ApiKeyConfigSchema>;
+/**
+ * 登录类型启用配置
+ * @example
+ * ```ts
+ * import { LoginConfigSchema } from '@h-ai/iam'
+ * const result = LoginConfigSchema.safeParse({ password: true, otp: false })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const LoginConfigSchema: z.ZodObject<{
+    password: z.ZodDefault<z.ZodBoolean>;
+    otp: z.ZodDefault<z.ZodBoolean>;
+    ldap: z.ZodDefault<z.ZodBoolean>;
+    apikey: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * 登录方式开关配置。
+ * @example
+ * ```ts
+ * import { LoginConfigSchema, type LoginConfig } from '@h-ai/iam'
+ * const value: LoginConfig = LoginConfigSchema.parse({ password: true, otp: false })
+ * ```
+ */
+type LoginConfig = z.infer<typeof LoginConfigSchema>;
+/**
+ * 注册配置
+ * @example
+ * ```ts
+ * import { RegisterConfigSchema } from '@h-ai/iam'
+ * const result = RegisterConfigSchema.safeParse({ enabled: false })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const RegisterConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    defaultEnabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * 注册开关及新用户默认状态。
+ * @example
+ * ```ts
+ * import { RegisterConfigSchema, type RegisterConfig } from '@h-ai/iam'
+ * const value: RegisterConfig = RegisterConfigSchema.parse({ enabled: false })
+ * ```
+ */
+type RegisterConfig = z.infer<typeof RegisterConfigSchema>;
+/**
+ * 安全策略配置
+ * @example
+ * ```ts
+ * import { SecurityConfigSchema } from '@h-ai/iam'
+ * const result = SecurityConfigSchema.safeParse({ maxLoginAttempts: 5, lockoutDuration: 900 })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const SecurityConfigSchema: z.ZodObject<{
+    maxLoginAttempts: z.ZodDefault<z.ZodNumber>;
+    lockoutDuration: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 服务端账户失败计数与锁定策略。
+ * @example
+ * ```ts
+ * import { SecurityConfigSchema, type SecurityConfig } from '@h-ai/iam'
+ * const value: SecurityConfig = SecurityConfigSchema.parse({ maxLoginAttempts: 5, lockoutDuration: 900 })
+ * ```
+ */
+type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
+/**
+ * 协议展示配置
+ * @example
+ * ```ts
+ * import { AgreementConfigSchema } from '@h-ai/iam'
+ * const result = AgreementConfigSchema.safeParse({ userAgreementUrl: 'https://app.example.com/terms', showOnRegister: true })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const AgreementConfigSchema: z.ZodObject<{
+    userAgreementMarkdown: z.ZodOptional<z.ZodString>;
+    privacyPolicyMarkdown: z.ZodOptional<z.ZodString>;
+    userAgreementUrl: z.ZodOptional<z.ZodURL>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodURL>;
+    showOnRegister: z.ZodDefault<z.ZodBoolean>;
+    showOnLogin: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * 登录和注册的协议展示设置。
+ * @example
+ * ```ts
+ * import { AgreementConfigSchema, type AgreementConfig } from '@h-ai/iam'
+ * const value: AgreementConfig = AgreementConfigSchema.parse({ userAgreementUrl: 'https://app.example.com/terms', showOnRegister: true })
+ * ```
+ */
+type AgreementConfig = z.infer<typeof AgreementConfigSchema>;
+/**
+ * 认证页面外观 Schema；图片仅接受 HTTP(S) 或站内路径，输出包含默认展示模式。
+ * @example
+ * ```ts
+ * import { AuthUiConfigSchema } from '@h-ai/iam'
+ * const result = AuthUiConfigSchema.safeParse({ variant: 'split', logoUrl: '/logo.svg' })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const AuthUiConfigSchema: z.ZodObject<{
+    variant: z.ZodDefault<z.ZodEnum<{
+        card: "card";
+        split: "split";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    brandTitle: z.ZodOptional<z.ZodString>;
+    brandText: z.ZodOptional<z.ZodString>;
+    logoUrl: z.ZodOptional<z.ZodString>;
+    illustrationUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 认证页外观设置；不包含服务端秘密。
+ * @example
+ * ```ts
+ * import { AuthUiConfigSchema, type AuthUiConfig } from '@h-ai/iam'
+ * const value: AuthUiConfig = AuthUiConfigSchema.parse({ variant: 'split', logoUrl: '/logo.svg' })
+ * ```
+ */
+type AuthUiConfig = z.infer<typeof AuthUiConfigSchema>;
+/**
+ * 会话配置 Schema
+ * @example
+ * ```ts
+ * import { SessionConfigSchema } from '@h-ai/iam'
+ * const result = SessionConfigSchema.safeParse({ maxAge: 3600, refreshTokenMaxAge: 604800 })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const SessionConfigSchema: z.ZodObject<{
+    maxAge: z.ZodDefault<z.ZodNumber>;
+    sliding: z.ZodDefault<z.ZodBoolean>;
+    singleDevice: z.ZodDefault<z.ZodBoolean>;
+    refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 会话配置类型
+ * @example
+ * ```ts
+ * import { SessionConfigSchema, type SessionConfig } from '@h-ai/iam'
+ * const value: SessionConfig = SessionConfigSchema.parse({ maxAge: 3600, refreshTokenMaxAge: 604800 })
+ * ```
+ */
+type SessionConfig = z.infer<typeof SessionConfigSchema>;
+/**
+ * RBAC 配置 Schema
+ * @example
+ * ```ts
+ * import { RbacConfigSchema } from '@h-ai/iam'
+ * const result = RbacConfigSchema.safeParse({ enabled: true, defaultRole: 'user' })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const RbacConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    superAdminRole: z.ZodDefault<z.ZodString>;
+    defaultRole: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * RBAC 配置类型
+ * @example
+ * ```ts
+ * import { RbacConfigSchema, type RbacConfig } from '@h-ai/iam'
+ * const value: RbacConfig = RbacConfigSchema.parse({ enabled: true, defaultRole: 'user' })
+ * ```
+ */
+type RbacConfig = z.infer<typeof RbacConfigSchema>;
+/**
+ * IAM 统一配置 Schema
+ * @example
+ * ```ts
+ * import { IamConfigSchema } from '@h-ai/iam'
+ * const result = IamConfigSchema.safeParse({ seedDefaultData: false, session: { maxAge: 3600 } })
+ * if (result.success) {
+ *   result.data // 输出已应用 Schema 默认值。
+ * }
+ * ```
+ */
+declare const IamConfigSchema: z.ZodObject<{
+    ui: z.ZodOptional<z.ZodObject<{
+        variant: z.ZodDefault<z.ZodEnum<{
+            card: "card";
+            split: "split";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        subtitle: z.ZodOptional<z.ZodString>;
+        brandTitle: z.ZodOptional<z.ZodString>;
+        brandText: z.ZodOptional<z.ZodString>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        illustrationUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    password: z.ZodOptional<z.ZodObject<{
+        minLength: z.ZodDefault<z.ZodNumber>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        requireUppercase: z.ZodDefault<z.ZodBoolean>;
+        requireLowercase: z.ZodDefault<z.ZodBoolean>;
+        requireNumber: z.ZodDefault<z.ZodBoolean>;
+        requireSpecialChar: z.ZodDefault<z.ZodBoolean>;
+        expirationDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    otp: z.ZodOptional<z.ZodObject<{
+        email: z.ZodDefault<z.ZodBoolean>;
+        sms: z.ZodDefault<z.ZodBoolean>;
+        length: z.ZodDefault<z.ZodNumber>;
+        expiresIn: z.ZodDefault<z.ZodNumber>;
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+        resendInterval: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    ldap: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        bindDn: z.ZodString;
+        bindPassword: z.ZodString;
+        searchBase: z.ZodString;
+        searchFilter: z.ZodDefault<z.ZodString>;
+        usernameAttribute: z.ZodDefault<z.ZodString>;
+        emailAttribute: z.ZodDefault<z.ZodString>;
+        displayNameAttribute: z.ZodDefault<z.ZodString>;
+        useTls: z.ZodDefault<z.ZodBoolean>;
+        connectTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    apikey: z.ZodOptional<z.ZodObject<{
+        maxKeysPerUser: z.ZodDefault<z.ZodNumber>;
+        defaultExpirationDays: z.ZodDefault<z.ZodNumber>;
+        prefix: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    passwordReset: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+        }>>;
+        resetUrl: z.ZodOptional<z.ZodURL>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        tokenExpiresIn: z.ZodDefault<z.ZodNumber>;
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    login: z.ZodDefault<z.ZodObject<{
+        password: z.ZodDefault<z.ZodBoolean>;
+        otp: z.ZodDefault<z.ZodBoolean>;
+        ldap: z.ZodDefault<z.ZodBoolean>;
+        apikey: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    register: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        defaultEnabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    agreements: z.ZodDefault<z.ZodObject<{
+        userAgreementMarkdown: z.ZodOptional<z.ZodString>;
+        privacyPolicyMarkdown: z.ZodOptional<z.ZodString>;
+        userAgreementUrl: z.ZodOptional<z.ZodURL>;
+        privacyPolicyUrl: z.ZodOptional<z.ZodURL>;
+        showOnRegister: z.ZodDefault<z.ZodBoolean>;
+        showOnLogin: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    security: z.ZodDefault<z.ZodObject<{
+        maxLoginAttempts: z.ZodDefault<z.ZodNumber>;
+        lockoutDuration: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    session: z.ZodOptional<z.ZodObject<{
+        maxAge: z.ZodDefault<z.ZodNumber>;
+        sliding: z.ZodDefault<z.ZodBoolean>;
+        singleDevice: z.ZodDefault<z.ZodBoolean>;
+        refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    rbac: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        superAdminRole: z.ZodDefault<z.ZodString>;
+        defaultRole: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    seedDefaultData: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * IAM 配置类型
+ * @example
+ * ```ts
+ * import { IamConfigSchema, type IamConfig } from '@h-ai/iam'
+ * const value: IamConfig = IamConfigSchema.parse({ seedDefaultData: false, session: { maxAge: 3600 } })
+ * ```
+ */
+type IamConfig = z.infer<typeof IamConfigSchema>;
+/**
+ * IAM 配置设置输入类型（仅设置字段，不含运行时依赖）
+ *
+ * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
+ * @example
+ * ```ts
+ * import type { IamConfigSettingsInput } from '@h-ai/iam'
+ * const value: IamConfigSettingsInput = { session: { maxAge: 3600 }, seedDefaultData: false }
+ * ```
+ */
+type IamConfigSettingsInput = z.input<typeof IamConfigSchema>;
+
+/**
+ * @h-ai/iam — API Key 类型定义
+ *
+ * 包含 API Key 实体、创建选项、查询选项等类型。
+ * @module iam-authn-apikey-types
+ */
+
+/**
+ * API Key 实体（对外展示）
+ *
+ * 不含密钥哈希等敏感信息。
+ * @example
+ * ```ts
+ * import { iam, type ApiKey } from '@h-ai/iam'
+ * // 已初始化依赖和 IAM，并启用 login.apikey。
+ * const result = await iam.apiKey.getApiKey('key-1')
+ * if (result.success && result.data) {
+ *   const key: ApiKey = result.data
+ *   key.keyPrefix // 展示前缀，不包含 rawKey 或哈希。
+ * }
+ * ```
+ */
+interface ApiKey {
+    /** API Key ID */
+    id: string;
+    /** 所属用户 ID */
+    userId: string;
+    /** API Key 名称（用户自定义标识） */
+    name: string;
+    /** 密钥前缀（用于展示，如 'hai_abc1****'） */
+    keyPrefix: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 过期时间（null 表示永不过期） */
+    expiresAt: Date | null;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 最后使用时间 */
+    lastUsedAt: Date | null;
+    /** 权限代码范围，支持 * / 命名空间 :*；空数组无操作权限，* 不超出主体权限。 */
+    scopes: string[];
+}
+/**
+ * 创建 API Key 的返回结果
+ *
+ * 仅在创建时返回明文密钥，之后无法再获取。
+ * @example
+ * ```ts
+ * import { iam, type CreateApiKeyResult } from '@h-ai/iam'
+ * // 已初始化依赖和 IAM、启用 login.apikey；user-1 为已存在的用户。
+ * const created = await iam.apiKey.createApiKey('user-1', { name: 'report-reader', scopes: ['report:read'] })
+ * if (created.success) {
+ *   const value: CreateApiKeyResult = created.data
+ *   const oneTimeSecret = value.rawKey // 仅本次交给调用者安全保存，不能写日志。
+ * }
+ * ```
+ */
+interface CreateApiKeyResult {
+    /** API Key 元数据 */
+    apiKey: ApiKey;
+    /** 明文密钥（仅此一次展示） */
+    rawKey: string;
+}
+/**
+ * 创建 API Key 选项
+ * @example
+ * ```ts
+ * import type { CreateApiKeyOptions } from '@h-ai/iam'
+ * const value: CreateApiKeyOptions = { name: 'report-reader', expirationDays: 30, scopes: ['report:read'] }
+ * ```
+ */
+interface CreateApiKeyOptions {
+    /** API Key 名称 */
+    name: string;
+    /** 有效期天数（0 或不传表示永不过期） */
+    expirationDays?: number;
+    /** 权限代码范围；默认空数组。受限 key 不保留角色授权入口，使用 permission 守卫。 */
+    scopes?: string[];
+}
+/**
+ * API Key 列表允许的服务端排序字段。
+ * @example
+ * ```ts
+ * import type { ApiKeySortField } from '@h-ai/iam'
+ * const value: ApiKeySortField = 'createdAt'
+ * ```
+ */
+type ApiKeySortField = 'name' | 'createdAt' | 'lastUsedAt' | 'expiresAt';
+/**
+ * API Key 列表排序方向。
+ * @example
+ * ```ts
+ * import type { ApiKeySortDirection } from '@h-ai/iam'
+ * const value: ApiKeySortDirection = 'desc'
+ * ```
+ */
+type ApiKeySortDirection = 'asc' | 'desc';
+/**
+ * API Key 列表查询选项
+ * @example
+ * ```ts
+ * import type { ListApiKeysOptions } from '@h-ai/iam'
+ * const value: ListApiKeysOptions = { page: 1, pageSize: 20, enabled: true, sortBy: 'createdAt', sortDirection: 'desc' }
+ * ```
+ */
+interface ListApiKeysOptions extends PaginationOptionsInput {
+    /** 搜索关键字（模糊匹配名称与密钥前缀） */
+    search?: string;
+    /** 按启用状态过滤，不传则返回全部 */
+    enabled?: boolean;
+    /** 服务端排序字段；未指定时保持按创建时间倒序的历史行为。 */
+    sortBy?: ApiKeySortField;
+    /** 服务端排序方向；仅在指定 sortBy 时生效，默认 desc。 */
+    sortDirection?: ApiKeySortDirection;
+}
+/**
+ * API Key 管理操作接口
+ * @example
+ * ```ts
+ * import { iam, type ApiKeyOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化，并启用 login.apikey。
+ * const operations: ApiKeyOperations = iam.apiKey
+ * const result = await operations.listApiKeys('user-1', { page: 1, pageSize: 20 })
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface ApiKeyOperations {
+    /**
+     * 创建 API Key
+     *
+     * @param userId - 用户 ID
+     * @param options - 创建选项
+     * @returns 成功返回 API Key 元数据和明文密钥
+     */
+    createApiKey: (userId: string, options: CreateApiKeyOptions) => Promise<HaiResult<CreateApiKeyResult>>;
+    /**
+     * 分页列出用户的 API Key
+     *
+     * @param userId - 用户 ID
+     * @param options - 分页、搜索、过滤与排序选项
+     * @returns 分页 API Key 列表（不含密钥哈希）
+     */
+    listApiKeys: (userId: string, options?: ListApiKeysOptions) => Promise<HaiResult<PaginatedResult<ApiKey>>>;
+    /**
+     * 获取 API Key 详情
+     *
+     * @param keyId - API Key ID
+     * @returns API Key 详情
+     */
+    getApiKey: (keyId: string) => Promise<HaiResult<ApiKey | null>>;
+    /**
+     * 吊销/删除 API Key
+     *
+     * @param keyId - API Key ID
+     * @returns 操作结果
+     */
+    revokeApiKey: (keyId: string) => Promise<HaiResult<void>>;
+    /**
+     * 验证 API Key 并返回关联用户 ID
+     *
+     * @param rawKey - 明文 API Key
+     * @returns 成功返回 API Key 实体（含用户 ID），失败返回错误码
+     */
+    verifyApiKey: (rawKey: string) => Promise<HaiResult<ApiKey>>;
+}
+
+/**
+ * @h-ai/iam — 授权子功能类型定义（RBAC）
+ *
+ * @module iam-authz-types
+ */
+
+/**
+ * 权限类型
+ *
+ * - menu：菜单/导航可见性控制
+ * - api：接口级访问控制
+ * - button：操作按钮显隐控制
+ * @example
+ * ```ts
+ * import type { PermissionType } from '@h-ai/iam'
+ * const value: PermissionType = 'api'
+ * ```
+ */
+type PermissionType = 'menu' | 'api' | 'button';
+/**
+ * 权限查询参数
+ *
+ * 扩展分页参数，支持按类型和关键字筛选。
+ * @example
+ * ```ts
+ * import type { PermissionQueryOptions } from '@h-ai/iam'
+ * const value: PermissionQueryOptions = { page: 1, pageSize: 20, type: 'api', search: 'report' }
+ * ```
+ */
+interface PermissionQueryOptions extends PaginationOptionsInput {
+    /** 按权限类型筛选 */
+    type?: PermissionType;
+    /** 按关键字搜索（匹配 code 或 name） */
+    search?: string;
+}
+/**
+ * 权限
+ * @example
+ * ```ts
+ * import type { Permission } from '@h-ai/iam'
+ * const value: Permission = { id: 'permission-1', code: 'report:read', name: '查看报表', type: 'api', createdAt: new Date(), updatedAt: new Date() }
+ * ```
+ */
+interface Permission {
+    /** 权限 ID */
+    id: string;
+    /** 权限代码（如 users:read, posts:write） */
+    code: string;
+    /** 权限名称 */
+    name: string;
+    /** 权限描述 */
+    description?: string;
+    /** 权限类型（menu / api / button） */
+    type?: PermissionType;
+    /** 资源类型 */
+    resource?: string;
+    /** 操作类型（create/read/update/delete） */
+    action?: string;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+}
+/**
+ * 角色
+ * @example
+ * ```ts
+ * import type { Role } from '@h-ai/iam'
+ * const value: Role = { id: 'role-1', code: 'report_reader', name: '报表读者', createdAt: new Date(), updatedAt: new Date() }
+ * ```
+ */
+interface Role {
+    /** 角色 ID */
+    id: string;
+    /** 角色代码 */
+    code: string;
+    /** 角色名称 */
+    name: string;
+    /** 角色描述 */
+    description?: string;
+    /** 是否系统角色（不可删除） */
+    isSystem?: boolean;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+}
+/**
+ * 授权子功能接口
+ * @example
+ * ```ts
+ * import { iam, type AuthzOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化。
+ * const operations: AuthzOperations = iam.authz
+ * const result = await operations.checkPermission('user-1', 'report:read')
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface AuthzOperations {
+    /** 查询当前角色与权限代码，一次读取角色并批量聚合权限，不依赖会话缓存。 */
+    getUserAuthorization: (userId: string) => Promise<HaiResult<Pick<Session, 'roles' | 'permissions'>>>;
+    /**
+     * 检查权限
+     *
+     * 超级管理员角色自动拥有所有权限。
+     * 支持通配符匹配（如 `user:*` 匹配 `user:read`）。
+     *
+     * **数据来源**：角色列表和权限代码均从数据库实时查询。
+     *
+     * @param userId - 用户 ID
+     * @param permission - 权限代码（如 `user:read`）
+     * @returns 成功返回 true/false
+     */
+    checkPermission: (userId: string, permission: string) => Promise<HaiResult<boolean>>;
+    /**
+     * 获取用户权限列表
+     *
+     * 通过用户角色聚合所有权限（自动去重）。
+     *
+     * **数据来源**：直接查询数据库，返回最新数据。
+     *
+     * @param userId - 用户 ID
+     * @returns 成功返回去重后的权限列表
+     */
+    getUserPermissions: (userId: string) => Promise<HaiResult<Permission[]>>;
+    /**
+     * 获取用户角色列表
+     *
+     * **数据来源**：直接查询数据库，返回最新数据。
+     *
+     * @param userId - 用户 ID
+     * @returns 成功返回角色列表
+     */
+    getUserRoles: (userId: string) => Promise<HaiResult<Role[]>>;
+    /**
+     * 分配角色给用户
+     *
+     * @param userId - 用户 ID
+     * @param roleId - 角色 ID
+     * @returns 成功返回 ok；角色不存在返回 ROLE_NOT_FOUND
+     */
+    assignRole: (userId: string, roleId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 移除用户角色
+     *
+     * @param userId - 用户 ID
+     * @param roleId - 角色 ID
+     * @returns 成功返回 ok
+     */
+    removeRole: (userId: string, roleId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 同步用户角色（替换为目标角色列表）
+     *
+     * 自动计算当前角色与目标角色的差集，批量移除多余角色、添加缺失角色，
+     * 最终同步一次会话权限。若目标与当前一致则跳过操作。
+     *
+     * @param userId - 用户 ID
+     * @param roleIds - 目标角色 ID 列表
+     * @returns 成功返回 ok
+     */
+    syncRoles: (userId: string, roleIds: string[], tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 创建角色
+     *
+     * @param role - 角色数据（code、name、description、isSystem）
+     * @returns 成功返回创建的角色（含 id 和时间戳）
+     */
+    createRole: (role: Omit<Role, 'id' | 'createdAt' | 'updatedAt'> & {
+        permissionIds?: string[];
+    }, tx?: DmlWithTxOperations) => Promise<HaiResult<Role>>;
+    /**
+     * 获取角色
+     *
+     * @param roleId - 角色 ID
+     * @returns 成功返回角色或 null（不存在时）
+     */
+    getRole: (roleId: string) => Promise<HaiResult<Role | null>>;
+    /**
+     * 根据角色代码获取角色
+     *
+     * @param code - 角色代码（如 'admin'、'user'）
+     * @returns 成功返回角色或 null（不存在时）
+     */
+    getRoleByCode: (code: string) => Promise<HaiResult<Role | null>>;
+    /**
+     * 获取所有角色（分页）
+     *
+     * @param options - 分页参数，可选
+     * @returns 成功返回分页角色列表
+     */
+    getAllRoles: (options?: PaginationOptionsInput) => Promise<HaiResult<PaginatedResult<Role>>>;
+    /** 批量统计角色成员数；成功时无关联返回 0，查询失败返回错误 */
+    getRoleUserCounts: (roleIds: string[]) => Promise<HaiResult<Map<string, number>>>;
+    /**
+     * 更新角色
+     *
+     * @param roleId - 角色 ID
+     * @param data - 要更新的字段；permissionIds 在同一事务内全量替换，未传则保持权限不变
+     * @returns 成功返回更新后的角色；角色不存在返回 ROLE_NOT_FOUND
+     */
+    updateRole: (roleId: string, data: Partial<Omit<Role, 'id' | 'createdAt' | 'updatedAt'>> & {
+        permissionIds?: string[];
+    }, tx?: DmlWithTxOperations) => Promise<HaiResult<Role>>;
+    /**
+     * 删除角色
+     *
+     * 级联删除用户-角色、角色-权限关联，并同步受影响用户的会话。
+     *
+     * @param roleId - 角色 ID
+     * @returns 成功返回 ok；角色不存在返回 ROLE_NOT_FOUND
+     */
+    deleteRole: (roleId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 创建权限
+     *
+     * @param permission - 权限数据（code、name、resource、action）
+     * @returns 成功返回创建的权限（含 id 和时间戳）
+     */
+    createPermission: (permission: Omit<Permission, 'id' | 'createdAt' | 'updatedAt'>, tx?: DmlWithTxOperations) => Promise<HaiResult<Permission>>;
+    /**
+     * 获取权限
+     *
+     * @param permissionId - 权限 ID
+     * @returns 成功返回权限或 null（不存在时）
+     */
+    getPermission: (permissionId: string) => Promise<HaiResult<Permission | null>>;
+    /**
+     * 根据权限代码获取权限
+     *
+     * @param code - 权限代码（如 `user:read`）
+     * @returns 成功返回权限或 null（不存在时）
+     */
+    getPermissionByCode: (code: string) => Promise<HaiResult<Permission | null>>;
+    /**
+     * 获取所有权限（分页）
+     *
+     * 支持按权限类型（menu/api/button）和关键字（code/name）筛选。
+     *
+     * @param options - 分页及筛选参数，可选
+     * @returns 成功返回分页权限列表
+     */
+    getAllPermissions: (options?: PermissionQueryOptions) => Promise<HaiResult<PaginatedResult<Permission>>>;
+    /**
+     * 删除权限
+     *
+     * 级联删除角色-权限关联，并同步受影响用户的会话。
+     *
+     * @param permissionId - 权限 ID
+     * @returns 成功返回 ok；权限不存在返回 PERMISSION_NOT_FOUND
+     */
+    deletePermission: (permissionId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 为角色分配权限
+     *
+     * @param roleId - 角色 ID
+     * @param permissionId - 权限 ID
+     * @returns 成功返回 ok；角色/权限不存在返回对应错误码
+     */
+    assignPermissionToRole: (roleId: string, permissionId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 移除角色权限
+     *
+     * @param roleId - 角色 ID
+     * @param permissionId - 权限 ID
+     * @returns 成功返回 ok；权限不存在返回 PERMISSION_NOT_FOUND
+     */
+    removePermissionFromRole: (roleId: string, permissionId: string, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    /**
+     * 获取角色的权限列表
+     *
+     * **数据来源**：直接查询数据库，返回最新数据。
+     *
+     * @param roleId - 角色 ID
+     * @returns 成功返回角色关联的权限列表
+     */
+    getRolePermissions: (roleId: string) => Promise<HaiResult<Permission[]>>;
+    /**
+     * 批量获取多个用户的角色列表
+     *
+     * 单次查询替代 N 次 getUserRoles 调用，避免 N+1 问题。
+     * 返回 Map：key 为 userId，value 为该用户的角色列表；无角色的用户返回空数组。
+     *
+     * **数据来源**：直接查询数据库，返回最新数据。
+     *
+     * @param userIds - 用户 ID 列表
+     * @returns Map<userId, Role[]>
+     */
+    getUserRolesForMany: (userIds: string[]) => Promise<HaiResult<Map<string, Role[]>>>;
+    /**
+     * 批量获取多个角色的权限列表
+     *
+     * 单次查询替代 N 次 getRolePermissions 调用，避免 N+1 问题。
+     * 返回 Map：key 为 roleId，value 为该角色的权限列表；无权限的角色返回空数组。
+     *
+     * **数据来源**：直接查询数据库，返回最新数据。
+     *
+     * @param roleIds - 角色 ID 列表
+     * @returns Map<roleId, Permission[]>
+     */
+    getRolePermissionsForMany: (roleIds: string[]) => Promise<HaiResult<Map<string, Permission[]>>>;
+}
+
+/**
+ * @h-ai/iam — 用户相关类型定义
+ *
+ * 包含： - 用户基础类型（User、StoredUser） - 注册选项（RegisterOptions） - 协议展示类型（AgreementDisplay） - 用户操作接口（UserOperations）
+ * @module iam-user-types
+ */
+
+/**
+ * 用户列表允许的服务端排序字段。
+ * @example
+ * ```ts
+ * import type { UserSortField } from '@h-ai/iam'
+ * const value: UserSortField = 'username'
+ * ```
+ */
+type UserSortField = 'username' | 'email' | 'displayName' | 'enabled' | 'createdAt';
+/**
+ * 用户列表排序方向。
+ * @example
+ * ```ts
+ * import type { UserSortDirection } from '@h-ai/iam'
+ * const value: UserSortDirection = 'asc'
+ * ```
+ */
+type UserSortDirection = 'asc' | 'desc';
+/**
+ * 用户列表查询选项
+ * @example
+ * ```ts
+ * import type { ListUsersOptions } from '@h-ai/iam'
+ * const value: ListUsersOptions = { page: 1, pageSize: 20, enabled: true, roleCode: 'user', include: ['roles'] }
+ * ```
+ */
+interface ListUsersOptions extends PaginationOptionsInput {
+    /** 角色 code 精确筛选，在数据库分页前执行。 */
+    roleCode?: string;
+    /** 搜索关键字（模糊匹配用户名、邮箱、手机号、显示名称） */
+    search?: string;
+    /** 按启用状态过滤，不传则返回全部 */
+    enabled?: boolean;
+    /** 服务端排序字段；未指定时保持按创建时间倒序的历史行为。 */
+    sortBy?: UserSortField;
+    /** 服务端排序方向；仅在指定 sortBy 时生效，默认 desc。 */
+    sortDirection?: UserSortDirection;
+    /** 包含关联数据（如 'roles' 表示同时返回用户角色列表） */
+    include?: ('roles')[];
+}
+/**
+ * 用户基础信息
+ * @example
+ * ```ts
+ * import type { User } from '@h-ai/iam'
+ * const value: User = { id: 'user-1', username: 'alice', enabled: true, createdAt: new Date(), updatedAt: new Date() }
+ * ```
+ */
+interface User {
+    /** 用户 ID */
+    id: string;
+    /** 用户名 */
+    username: string;
+    /** 邮箱 */
+    email?: string;
+    /** 手机号 */
+    phone?: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 头像 URL */
+    avatarUrl?: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否邮箱验证 */
+    emailVerified?: boolean;
+    /** 是否手机验证 */
+    phoneVerified?: boolean;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+    /** 扩展属性 */
+    metadata?: Record<string, unknown>;
+    /** 用户角色列表（仅在 include: ['roles'] 时返回） */
+    roles?: Role[];
+}
+/**
+ * 用户协议/隐私协议展示配置
+ * @example
+ * ```ts
+ * import type { AgreementDisplay } from '@h-ai/iam'
+ * const value: AgreementDisplay = { userAgreementUrl: 'https://app.example.com/terms', showOnRegister: true, showOnLogin: false }
+ * ```
+ */
+interface AgreementDisplay {
+    /** 用户协议 Markdown 正文，显示优先于 URL。 */
+    userAgreementMarkdown?: string;
+    /** 隐私协议 Markdown 正文，显示优先于 URL。 */
+    privacyPolicyMarkdown?: string;
+    /** 用户协议 URL */
+    userAgreementUrl?: string;
+    /** 隐私协议 URL */
+    privacyPolicyUrl?: string;
+    /** 注册时展示协议 */
+    showOnRegister: boolean;
+    /** 登录时展示协议 */
+    showOnLogin: boolean;
+}
+/**
+ * 内部存储用户（包含密码哈希等敏感信息）
+ * @example
+ * ```ts
+ * import type { StoredUser } from '@h-ai/iam'
+ * // 服务端存储类型；不得直接序列化给浏览器。
+ * function credentialVersion(row: StoredUser): string {
+ *   return row.credentialVersion ?? ''
+ * }
+ * ```
+ */
+interface StoredUser extends User {
+    /** 密码凭据代际；密码提交时原子推进，旧会话及迟到认证不得复用。 */
+    credentialVersion?: string;
+    /** 密码重置操作的独立代际；发布/尝试推进，不影响现有登录。 */
+    resetVersion?: string;
+    /** 当前重置令牌的 SM3 摘要，仅内部存储。 */
+    resetHash?: string;
+    /** 重置令牌的 Unix 毫秒过期时间，由数据库时钟核验。 */
+    resetExpiresAt?: number;
+    /** 当前重置令牌已使用的尝试次数。 */
+    resetAttempts?: number;
+    /** 密码哈希 */
+    passwordHash?: string;
+    /** 密码更新时间 */
+    passwordUpdatedAt?: Date;
+    /** 登录失败次数 */
+    loginFailedCount?: number;
+    /** 最后登录失败时间 */
+    lastLoginFailedAt?: Date;
+    /** 锁定截止时间 */
+    lockedUntil?: Date;
+}
+/**
+ * 用户注册选项
+ * @example
+ * ```ts
+ * import type { RegisterOptions } from '@h-ai/iam'
+ * const value: RegisterOptions = { username: 'alice', email: 'alice@example.com', password: 'ExampleOnly123!' }
+ * ```
+ */
+interface RegisterOptions {
+    /** 用户名 */
+    username: string;
+    /** 邮箱 */
+    email?: string;
+    /** 手机号 */
+    phone?: string;
+    /** 密码 */
+    password: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 扩展属性 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 注册结果
+ * @example
+ * ```ts
+ * import { iam, type RegisterResult } from '@h-ai/iam'
+ * const result = await iam.user.register({ username: 'alice', password: 'ExampleOnly123!' })
+ * if (result.success) {
+ *   const registered: RegisterResult = result.data
+ *   registered.user.id
+ * }
+ * ```
+ */
+interface RegisterResult {
+    /** 用户信息 */
+    user: User;
+    /** 协议展示信息（可选） */
+    agreements?: AgreementDisplay;
+}
+/**
+ * 当前登录用户可自行修改的字段白名单
+ *
+ * 仅允许修改个人资料相关字段，禁止修改安全字段（enabled、emailVerified、roles 等）。
+ * @example
+ * ```ts
+ * import type { UpdateCurrentUserInput } from '@h-ai/iam'
+ * const value: UpdateCurrentUserInput = { displayName: 'Alice', avatarUrl: 'https://app.example.com/avatar/alice.png' }
+ * ```
+ */
+interface UpdateCurrentUserInput {
+    /** 用户名 */
+    username?: string;
+    /** 邮箱 */
+    email?: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 头像 URL */
+    avatarUrl?: string;
+    /** 手机号 */
+    phone?: string;
+    /** 扩展属性 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 用户子功能接口
+ * @example
+ * ```ts
+ * import { iam, type UserOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化。
+ * const operations: UserOperations = iam.user
+ * const result = await operations.listUsers({ page: 1, pageSize: 20, include: ['roles'] })
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface UserOperations {
+    /** 批量查询最多 1000 个用户 ID，去重并保持输入顺序，忽略不存在的 ID；可批量包含角色。 */
+    getUsers: (userIds: readonly string[], options?: {
+        include?: ('roles')[];
+    }) => Promise<HaiResult<User[]>>;
+    /** 管理端创建账户，不受自助注册开关限制；调用端必须执行管理员授权。 */
+    createUser: (options: RegisterOptions) => Promise<HaiResult<RegisterResult>>;
+    /**
+     * 注册用户
+     *
+     * 校验注册开关、密码强度、用户名/邮箱唯一性后，
+     * 在事务中创建用户并分配默认角色。
+     *
+     * @param options - 注册选项（用户名、密码、邮箱等）
+     * @returns 成功返回用户信息及可选的协议展示；失败返回对应错误码
+     */
+    register: (options: RegisterOptions) => Promise<HaiResult<RegisterResult>>;
+    /**
+     * 获取当前用户
+     *
+     * 通过访问令牌验证会话后查询用户信息。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回用户信息；令牌无效/过期返回错误
+     */
+    getCurrentUser: (accessToken: string) => Promise<HaiResult<User>>;
+    /**
+     * 更新当前登录用户信息（通过 accessToken 识别用户）
+     *
+     * 仅允许修改白名单字段（username、email、displayName、avatarUrl、phone、metadata），
+     * 禁止修改安全字段（enabled、emailVerified 等）。修改 username/email 时自动校验唯一性。
+     *
+     * @param accessToken - 访问令牌
+     * @param data - 要更新的字段（仅白名单字段）
+     * @returns 成功返回更新后的用户信息
+     */
+    updateCurrentUser: (accessToken: string, data: UpdateCurrentUserInput) => Promise<HaiResult<User>>;
+    /**
+     * 获取用户信息
+     *
+     * @param userId - 用户 ID
+     * @param options - 查询选项（可选 include: ['roles'] 同时返回角色列表）
+     * @param options.include - 指定需要额外展开的关联字段；传入 ['roles'] 时同时返回角色列表
+     * @returns 成功返回用户信息或 null（用户不存在时）
+     */
+    getUser: (userId: string, options?: {
+        include?: ('roles')[];
+    }) => Promise<HaiResult<User | null>>;
+    /**
+     * 获取用户列表（分页 + 搜索 + 过滤）
+     *
+     * @param options - 查询选项（页码、每页数量、搜索关键字、启用状态过滤）
+     * @returns 成功返回分页用户列表
+     */
+    listUsers: (options?: ListUsersOptions) => Promise<HaiResult<PaginatedResult<User>>>;
+    /**
+     * 更新用户信息
+     *
+     * 空更新（无有效字段）时直接返回当前用户信息。
+     *
+     * @param userId - 用户 ID
+     * @param data - 要更新的字段（displayName、email 等）
+     * @returns 成功返回更新后的用户信息；用户不存在返回 USER_NOT_FOUND
+     */
+    updateUser: (userId: string, data: Partial<User>) => Promise<HaiResult<User>>;
+    /**
+     * 删除用户
+     *
+     * 同时清理用户的角色关联数据。
+     *
+     * @param userId - 用户 ID
+     * @returns 成功返回 ok；用户不存在返回 USER_NOT_FOUND
+     */
+    deleteUser: (userId: string) => Promise<HaiResult<void>>;
+    /**
+     * 管理员重置用户密码
+     *
+     * 无需旧密码，直接设置新密码（仅限管理员操作）。
+     *
+     * @param userId - 用户 ID
+     * @param newPassword - 新密码
+     * @returns 成功返回 ok；用户不存在返回 USER_NOT_FOUND，密码不合规返回 PASSWORD_POLICY_VIOLATION
+     */
+    adminResetPassword: (userId: string, newPassword: string) => Promise<HaiResult<void>>;
+    /**
+     * 修改密码
+     *
+     * 验证旧密码 → 校验新密码强度 → 哈希并更新。
+     *
+     * @param userId - 用户 ID
+     * @param oldPassword - 旧密码
+     * @param newPassword - 新密码
+     * @returns 成功返回 ok；旧密码错误返回 INVALID_CREDENTIALS，新密码不合规返回 PASSWORD_POLICY_VIOLATION
+     */
+    changePassword: (userId: string, oldPassword: string, newPassword: string) => Promise<HaiResult<void>>;
+    /**
+     * 当前登录用户修改密码
+     *
+     * 通过访问令牌识别用户 → 验证旧密码 → 校验新密码强度 → 哈希并更新 → 清除该用户所有会话。
+     *
+     * @param accessToken - 当前用户的访问令牌
+     * @param oldPassword - 旧密码
+     * @param newPassword - 新密码
+     * @returns 成功返回 ok；旧密码错误返回 INVALID_CREDENTIALS，新密码不合规返回 PASSWORD_POLICY_VIOLATION
+     */
+    changeCurrentUserPassword: (accessToken: string, oldPassword: string, newPassword: string) => Promise<HaiResult<void>>;
+    /**
+     * 请求密码重置
+     *
+     * 查找用户 → 条件发布重置令牌（用户数据库行、SM3 摘要及 resetVersion）→ 通知业务层。
+     * 即使用户不存在也返回 ok（防止用户枚举攻击）。
+     *
+     * @param identifier - 用户标识（邮箱）
+     * @returns 用户不存在返回 ok；发布冲突、存储故障或投递未知返回失败，通知不自动重发。
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * const requested = await iam.user.requestPasswordReset('alice@example.com')
+     * if (!requested.success)
+     *   requested.error.code // 投递未知不能当作成功或由调用端擅自重发通知。
+     * ```
+     */
+    requestPasswordReset: (identifier: string) => Promise<HaiResult<void>>;
+    /**
+     * 确认密码重置
+     *
+     * 条件计次并取得代际 → 验证密码策略 → 最终 SQL 同时校验代际/有效期/状态并改密、消费令牌。
+     * 凭据代际已在数据库推进，后续缓存清理失败也不能重新授权旧会话。
+     *
+     * @param token - 重置令牌（明文，由 requestPasswordReset 生成并由业务层发送给用户）
+     * @param newPassword - 新密码
+     * @returns 成功返回 ok；令牌无效/过期返回 RESET_TOKEN_INVALID，尝试超限返回 RESET_TOKEN_MAX_ATTEMPTS
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * const result = await iam.user.confirmPasswordReset('token-from-recovery-link', 'ExampleOnly123!')
+     * if (!result.success)
+     *   result.error.code
+     * ```
+     */
+    confirmPasswordReset: (token: string, newPassword: string) => Promise<HaiResult<void>>;
+    /**
+     * 验证密码强度（同步方法）
+     *
+     * 根据密码策略校验长度、大小写、数字、特殊字符等要求。
+     *
+     * @param password - 待校验的密码
+     * @returns 通过返回 ok；不合规返回 PASSWORD_POLICY_VIOLATION
+     */
+    validatePassword: (password: string) => HaiResult<void>;
+}
+
+/**
+ * @h-ai/iam — 会话相关类型定义
+ *
+ * 包含： - 认证结果（AuthResult） - 会话类型（Session） - 会话子功能接口（SessionOperations）
+ * @module iam-session-types
+ */
+
+/**
+ * 认证令牌对（登录成功返回）
+ *
+ * 所有端（Web SSR / H5 SPA / Capacitor App / 未来小程序）
+ * 使用完全相同的 Bearer Token 认证流程。
+ * @example
+ * ```ts
+ * import { iam, type TokenPair } from '@h-ai/iam'
+ * const login = await iam.auth.login({ identifier: 'alice', password: 'ExampleOnly123!' })
+ * if (login.success) {
+ *   const tokens: TokenPair = login.data.tokens
+ *   const authorization = `${tokens.tokenType} ${tokens.accessToken}` // 仅用于受保护请求。
+ * }
+ * ```
+ */
+interface TokenPair {
+    /** 访问令牌（短期，用于 API 认证） */
+    accessToken: string;
+    /** 刷新令牌（长期，用于换取新 accessToken） */
+    refreshToken: string;
+    /** accessToken 过期时间（秒） */
+    expiresIn: number;
+    /** 令牌类型，固定为 'Bearer' */
+    tokenType: 'Bearer';
+}
+/**
+ * 认证结果
+ *
+ * 登录/注册成功后返回，包含用户信息、令牌、角色权限等。
+ * `roles` / `permissions` 来源于会话创建时写入的 RBAC 数据，
+ * 调用方无需再通过 `verifyToken` 获取。
+ * @example
+ * ```ts
+ * import { iam, type AuthResult } from '@h-ai/iam'
+ * const login = await iam.auth.login({ identifier: 'alice', password: 'ExampleOnly123!' })
+ * if (login.success) {
+ *   const authenticated: AuthResult = login.data
+ *   authenticated.user.displayName
+ * }
+ * ```
+ */
+interface AuthResult {
+    /** 用户信息 */
+    user: User;
+    /** 令牌对（替代原来的单个 accessToken） */
+    tokens: TokenPair;
+    /** 角色 code 列表（登录时从 RBAC 写入） */
+    roles: string[];
+    /** 权限 code 列表（登录时从 RBAC 写入） */
+    permissions: string[];
+    /** 协议展示信息（可选） */
+    agreements?: AgreementDisplay;
+}
+/**
+ * 会话数据
+ * @example
+ * ```ts
+ * import { iam, type Session } from '@h-ai/iam'
+ * const verified = await iam.auth.verifyToken('token-from-authorization-header')
+ * if (verified.success) {
+ *   const session: Session = verified.data
+ *   session.permissions.includes('report:read')
+ * }
+ * ```
+ */
+interface Session {
+    /** 会话内容版本；显式更新产生新版本，内部滑动续期保留版本。 */
+    version: string;
+    /** 认证快照绑定的持久凭据代；改密后的旧会话即使缓存清理失败也拒绝。 */
+    credentialVersion: string;
+    /** API Key 派生会话绑定的 key ID；普通用户登录时省略。 */
+    apiKeyId?: string;
+    /** 当前 key scopes；get/verify/refresh 每次重新验证持久化 key 并收敛权限。 */
+    apiKeyScopes?: string[];
+    /** 用户 ID */
+    userId: string;
+    /** 用户名 */
+    username?: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 头像 URL */
+    avatarUrl?: string;
+    /** 角色 code 列表（登录时写入，用于会话解析） */
+    roles: string[];
+    /** 权限 code 列表（登录时写入，用于会话解析） */
+    permissions: string[];
+    /** 来源（如 pc/android/ios） */
+    source?: string;
+    /** 访问令牌 */
+    accessToken: string;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 最后活动时间 */
+    lastActiveAt: Date;
+    /** 过期时间 */
+    expiresAt: Date;
+    /** 本会话 access 的签发/滑动有效期，单位秒；创建时固化，刷新沿用该值。 */
+    maxAge: number;
+    /** 扩展数据（内部保留 _tokenPair 供 logout 时吊销 refreshToken） */
+    data?: SessionData;
+}
+/**
+ * 会话扩展数据
+ *
+ * 支持开放的 Record 扩展，同时约束内部保留字段 _tokenPair。
+ * @example
+ * ```ts
+ * import type { SessionData } from '@h-ai/iam'
+ * const value: SessionData = { theme: 'dark', locale: 'zh-CN' }
+ * ```
+ */
+type SessionData = Record<string, unknown> & {
+    /** 令牌对（内部保留字段，由 session.create 写入，logout 时读取） */
+    _tokenPair?: TokenPair;
+};
+/**
+ * 创建会话选项
+ * @example
+ * ```ts
+ * import type { CreateSessionOptions } from '@h-ai/iam'
+ * const value: CreateSessionOptions = { userId: 'user-1', source: 'server', maxAge: 3600 }
+ * ```
+ */
+interface CreateSessionOptions {
+    /** 策略已验证的凭据代；创建前须与当前数据库核对，省略时仅供可信服务端按当前用户签发。 */
+    expectedCredentialVersion?: string;
+    /** 服务端已验证的 API Key 绑定；不得来自未验证客户端输入。 */
+    apiKeyId?: string;
+    apiKeyScopes?: string[];
+    /** 用户 ID */
+    userId: string;
+    /** 用户名 */
+    username?: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 头像 URL */
+    avatarUrl?: string;
+    /** 角色 code 列表 */
+    roles?: string[];
+    /** 权限 code 列表 */
+    permissions?: string[];
+    /** 来源（如 pc/android/ios） */
+    source?: string;
+    /** 过期时间（秒） */
+    maxAge?: number;
+    /** 扩展数据 */
+    data?: SessionData;
+}
+/**
+ * 会话子功能接口
+ * @example
+ * ```ts
+ * import { iam, type SessionOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化。
+ * const operations: SessionOperations = iam.session
+ * const result = await operations.get('token-from-authorization-header')
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface SessionOperations {
+    /**
+     * 创建会话
+     *
+     * 单设备模式在同一次原子提交内替换用户已有会话；提交失败保留旧会话。
+     *
+     * @param options - 会话创建选项（用户 ID、角色、来源等）
+     * @returns 成功返回完整的 Session 对象（含生成的访问令牌和过期时间）
+     */
+    create: (options: CreateSessionOptions) => Promise<HaiResult<Session>>;
+    /**
+     * 获取会话
+     *
+     * 查询缓存中的会话数据。API Key 会话先重新校验持久化 key 与 scopes；滑动窗口模式下自动续期。
+     * access 到期返回 null；记录保留到 refresh 到期或撤销，允许独立刷新。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回会话对象或 null（会话不存在/已过期）
+     */
+    get: (accessToken: string) => Promise<HaiResult<Session | null>>;
+    /**
+     * 验证访问令牌
+     *
+     * 等同于 get 但在会话不存在时返回错误而非 null；API Key 撤销/禁用/过期立即拒绝。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回会话；会话无效返回 SESSION_INVALID
+     */
+    verifyToken: (accessToken: string) => Promise<HaiResult<Session>>;
+    /**
+     * 更新会话
+     *
+     * 合并允许的资料/授权/时间字段（data 浅合并）；未传 lastActiveAt 时使用提交时刻。
+     * expiresAt/lastActiveAt 必须是有效日期；不允许修改主体、令牌、固有 maxAge 和版本。
+     *
+     * @param accessToken - 访问令牌
+     * @param data - 要更新的字段（roles、username、source、data 等）
+     * @param expectedVersion - 读取到的 Session.version；过期版本失败，不能覆盖较新的修改
+     * @returns 成功返回 ok；不存在返回 SESSION_NOT_FOUND，版本变化返回 CONFLICT
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * // 已完成身份与更新权限校验的服务端上下文。
+     * const token = 'token-from-authorization-header'
+     * const found = await iam.session.get(token)
+     * if (found.success && found.data) {
+     *   const updated = await iam.session.update(token, { data: { theme: 'dark' } }, found.data.version)
+     *   if (!updated.success)
+     *     updated.error.code // 版本冲突后重新读取，不能无条件覆盖。
+     * }
+     * ```
+     */
+    update: (accessToken: string, data: Partial<Session>, expectedVersion: string) => Promise<HaiResult<void>>;
+    /**
+     * 删除会话
+     *
+     * 同时清除用户令牌映射关系。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 已撤销或令牌不存在时返回 ok；共享存储读取或提交失败时返回错误
+     */
+    delete: (accessToken: string) => Promise<HaiResult<void>>;
+    /**
+     * 删除用户所有会话
+     *
+     * 原子删除用户分区内所有会话与 refresh 凭据。
+     *
+     * @param userId - 用户 ID
+     * @returns 成功返回实际删除的会话数量
+     */
+    deleteByUserId: (userId: string) => Promise<HaiResult<number>>;
+    /**
+     * 通过 refreshToken 换取新的 TokenPair
+     *
+     * 验证 refreshToken 有效性，签发新的 accessToken + refreshToken，
+     * 旧 refreshToken 自动失效（Rotation 策略）；access 过期不阻止仍有效的 refresh。
+     *
+     * @param refreshToken - 刷新令牌
+     * @returns 成功返回新的 TokenPair；失败返回 TOKEN_REFRESH_FAILED / TOKEN_EXPIRED
+     */
+    refresh: (refreshToken: string) => Promise<HaiResult<TokenPair>>;
+    /**
+     * 吊销 refreshToken（登出时调用）
+     *
+     * @param refreshToken - 刷新令牌
+     * @returns 成功返回 ok；令牌不存在时静默成功
+     */
+    revokeRefresh: (refreshToken: string) => Promise<HaiResult<void>>;
+    /**
+     * 批量更新用户所有活跃会话的 roles / permissions 字段
+     *
+     * 遍历用户缓存中的所有 session token，合并更新指定字段，
+     * 同时清理已失效的会话令牌。用于角色/权限变更后的会话同步。
+     *
+     * @param userId - 用户 ID
+     * @param updates - 要更新的字段（roles / permissions）
+     * @returns 成功返回 ok
+     */
+    patchUserSessions: (userId: string, updates: SessionFieldUpdates) => Promise<HaiResult<void>>;
+}
+/**
+ * 会话字段更新（仅限 roles / permissions）
+ *
+ * 用于角色/权限变更后的会话同步。
+ * @example
+ * ```ts
+ * import type { SessionFieldUpdates } from '@h-ai/iam'
+ * const value: SessionFieldUpdates = { roles: ['user'], permissions: ['report:read'] }
+ * ```
+ */
+interface SessionFieldUpdates {
+    /** 角色 code 列表 */
+    roles?: string[];
+    /** 权限 code 列表 */
+    permissions?: string[];
+}
+
+/**
+ * @h-ai/iam — 认证类型定义
+ *
+ * 包含： - 凭证类型（Credentials） - 认证策略接口（AuthStrategy） - 认证操作接口（AuthnOperations）
+ * @module iam-authn-types
+ */
+
+/**
+ * 用户凭证（用于密码登录）
+ * @example
+ * ```ts
+ * import type { PasswordCredentials } from '@h-ai/iam'
+ * const value: PasswordCredentials = { identifier: 'alice', password: 'ExampleOnly123!' }
+ * ```
+ */
+interface PasswordCredentials {
+    /** 用户名/邮箱/手机号 */
+    identifier: string;
+    /** 密码 */
+    password: string;
+}
+/**
+ * OTP 凭证（用于验证码登录）
+ * @example
+ * ```ts
+ * import type { OtpCredentials } from '@h-ai/iam'
+ * const value: OtpCredentials = { identifier: 'alice@example.com', code: '123456' }
+ * ```
+ */
+interface OtpCredentials {
+    /** 邮箱/手机号 */
+    identifier: string;
+    /** 验证码 */
+    code: string;
+}
+/**
+ * LDAP 凭证
+ * @example
+ * ```ts
+ * import type { LdapCredentials } from '@h-ai/iam'
+ * const value: LdapCredentials = { username: 'alice', password: 'ExampleOnly123!' }
+ * ```
+ */
+interface LdapCredentials {
+    /** 用户名 */
+    username: string;
+    /** 密码 */
+    password: string;
+}
+/**
+ * API Key 凭证（用于 API Key 认证）
+ * @example
+ * ```ts
+ * import { iam, type ApiKeyCredentials } from '@h-ai/iam'
+ * const created = await iam.apiKey.createApiKey('user-1', { name: 'report-reader', scopes: ['report:read'] })
+ * if (created.success) {
+ *   const credentials: ApiKeyCredentials = { key: created.data.rawKey }
+ *   const authenticated = await iam.auth.loginWithApiKey(credentials)
+ *   if (!authenticated.success)
+ *     authenticated.error.code
+ * }
+ * ```
+ */
+interface ApiKeyCredentials {
+    /** 明文 API Key */
+    key: string;
+}
+/**
+ * 统一凭证类型
+ * @example
+ * ```ts
+ * import type { Credentials } from '@h-ai/iam'
+ * const value: Credentials = { type: 'otp', identifier: 'alice@example.com', code: '123456' }
+ * ```
+ */
+type Credentials = {
+    type: 'password';
+} & PasswordCredentials | {
+    type: 'otp';
+} & OtpCredentials | {
+    type: 'ldap';
+} & LdapCredentials | {
+    type: 'apikey';
+} & ApiKeyCredentials;
+/**
+ * 策略内部可信认证快照；凭据代来自实际验证的用户行，不能用会话创建时的新快照替换。
+ * @internal
+ * @example 模块内部上下文
+ * ```ts
+ * function credentialSnapshot(user: AuthenticatedUser) {
+ *   return { userId: user.id, expectedCredentialVersion: user.credentialVersion }
+ * }
+ * ```
+ */
+interface AuthenticatedUser extends User {
+    /** 密码最终提交时更换；仅在服务端策略和会话构造间传递。 */
+    credentialVersion: string;
+}
+/**
+ * 认证策略接口
+ *
+ * 所有认证方式（密码/OTP/LDAP）都实现此接口
+ * @example
+ * ```ts
+ * import type { AuthStrategy, Credentials } from '@h-ai/iam'
+ * async function authenticate(strategy: AuthStrategy, credentials: Credentials) {
+ *   const result = await strategy.authenticate(credentials)
+ *   if (!result.success)
+ *     return result
+ *   return { userId: result.data.id, credentialVersion: result.data.credentialVersion }
+ * }
+ * ```
+ */
+interface AuthStrategy {
+    /** 策略类型 */
+    readonly type: AuthStrategyType;
+    /** 策略名称 */
+    readonly name: string;
+    /**
+     * 执行认证
+     *
+     * @param credentials - 统一凭证（包含 type 字段标识认证方式）
+     * @returns 认证成功返回用户信息；失败返回对应错误码（INVALID_CREDENTIALS / USER_LOCKED 等）
+     */
+    authenticate: (credentials: Credentials) => Promise<HaiResult<AuthenticatedUser>>;
+}
+/**
+ * 认证子功能接口
+ * @example
+ * ```ts
+ * import { iam, type AuthnOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化。
+ * const operations: AuthnOperations = iam.auth
+ * const result = await operations.verifyToken('token-from-authorization-header')
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface AuthnOperations {
+    /**
+     * 登录（使用密码）
+     *
+     * 检查登录方式启用 → 密码策略认证 → 创建会话 → 返回令牌。
+     *
+     * @param credentials - 密码凭证（identifier + password）
+     * @returns 成功返回 AuthResult（用户信息、令牌、协议展示）；失败返回错误
+     */
+    login: (credentials: PasswordCredentials) => Promise<HaiResult<AuthResult>>;
+    /**
+     * 使用验证码登录
+     *
+     * @param credentials - OTP 凭证（identifier + code）
+     * @returns 成功返回 AuthResult；验证码无效/过期返回 OTP_INVALID
+     */
+    loginWithOtp: (credentials: OtpCredentials) => Promise<HaiResult<AuthResult>>;
+    /**
+     * 使用 LDAP 登录
+     *
+     * @param credentials - LDAP 凭证（username + password）
+     * @returns 成功返回 AuthResult（自动同步本地用户）；失败返回错误
+     */
+    loginWithLdap: (credentials: LdapCredentials) => Promise<HaiResult<AuthResult>>;
+    /**
+     * 使用 API Key 登录
+     *
+     * 验证 API Key 有效性 → 查找关联用户 → 按 scopes 收敛授权 → 创建绑定 key 的会话。
+     * 空 scopes 无操作权限；显式 * 也不超出主体权限。受限 key 通过 permission 授权，不保留角色入口。
+     *
+     * @param credentials - API Key 凭证
+     * @returns 成功返回 AuthResult；API Key 无效/过期/禁用返回对应错误
+     */
+    loginWithApiKey: (credentials: ApiKeyCredentials) => Promise<HaiResult<AuthResult>>;
+    /**
+     * 登出
+     *
+     * 按完整访问令牌原子删除会话及关联 refresh，access 已到期也撤销待刷新记录。
+     * 无效或不存在的令牌幂等成功；缓存读取/提交失败必须返回错误，不能宣称服务端已退出。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 撤销完成或令牌不存在返回 ok；共享存储失败返回错误，恢复后可用同一令牌重试
+     */
+    logout: (accessToken: string) => Promise<HaiResult<void>>;
+    /**
+     * 验证令牌
+     *
+     * 验证会话并读取当前用户状态、角色与权限；重新应用 API Key scopes，依赖失败即拒绝。
+     * 会话同步仅是缓存快照，受保护请求使用此入口而非低层 session.verifyToken。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回会话信息；令牌无效/过期返回 SESSION_INVALID
+     */
+    verifyToken: (accessToken: string) => Promise<HaiResult<Session>>;
+    /**
+     * 发送验证码
+     *
+     * @param identifier - 用户标识（邮箱/手机号）
+     * @returns 成功返回验证码过期时间；频率限制返回 OTP_RESEND_TOO_FAST
+     */
+    sendOtp: (identifier: string) => Promise<HaiResult<{
+        expiresAt: Date;
+    }>>;
+    /**
+     * 注册并登录（一站式）
+     *
+     * 先注册用户（含默认角色分配），成功后立即登录并返回令牌。
+     * 注册失败则直接返回注册错误；注册成功但登录失败则返回登录错误。
+     *
+     * @param options - 注册选项（用户名、密码、邮箱等）
+     * @returns 成功返回 AuthResult（用户信息、令牌、协议展示）；失败返回对应错误码
+     */
+    registerAndLogin: (options: RegisterOptions) => Promise<HaiResult<AuthResult>>;
+}
+
+/**
+ * @h-ai/iam — LDAP 认证策略
+ *
+ * LDAP 目录认证方式
+ * @module iam-authn-ldap-strategy
+ */
+
+/**
+ * LDAP 客户端接口
+ * @internal
+ * @example 模块内部上下文
+ * ```ts
+ * async function lookup(client: LdapClient) {
+ *   const found = await client.search('ou=users,dc=example,dc=com', '(uid=alice)', ['uid', 'mail'])
+ *   if (!found.success)
+ *     return found
+ *   return found.data.map(entry => entry.dn)
+ * }
+ * ```
+ */
+interface LdapClient {
+    /**
+     * 绑定（认证）
+     */
+    bind: (dn: string, password: string) => Promise<HaiResult<void>>;
+    /**
+     * 搜索用户
+     */
+    search: (base: string, filter: string, attributes: string[]) => Promise<HaiResult<LdapSearchEntry[]>>;
+    /**
+     * 解除绑定
+     */
+    unbind: () => Promise<HaiResult<void>>;
+}
+/**
+ * LDAP 搜索结果条目
+ * @internal
+ * @example 模块内部上下文
+ * ```ts
+ * const entry: LdapSearchEntry = { dn: 'uid=alice,ou=users,dc=example,dc=com', attributes: { uid: 'alice', mail: ['alice@example.com'] } }
+ * const username = entry.attributes.uid
+ * ```
+ */
+interface LdapSearchEntry {
+    /** DN */
+    dn: string;
+    /** 属性 */
+    attributes: Record<string, string | string[]>;
+}
+/**
+ * LDAP 客户端工厂
+ * @example
+ * ```ts
+ * import type { LdapClientFactory, LdapConfig } from '@h-ai/iam'
+ * async function check(factory: LdapClientFactory, config: LdapConfig) {
+ *   const opened = await factory(config)
+ *   if (!opened.success)
+ *     return opened
+ *   const result = await opened.data.bind(config.bindDn, config.bindPassword)
+ *   const closed = await opened.data.unbind()
+ *   if (!closed.success)
+ *     return closed
+ *   return result
+ * }
+ * ```
+ */
+type LdapClientFactory = (config: LdapConfig) => Promise<HaiResult<LdapClient>>;
+
+/** 提供给认证页面的白名单配置；不含连接信息、密钥及安全状态。 */
+
+/**
+ * 认证页面可读取的白名单配置；能力开关同时考虑实际运行时依赖，不能用于服务端授权。
+ * @example
+ * ```ts
+ * import { iam, type IamPublicConfig } from '@h-ai/iam'
+ * const config: IamPublicConfig | null = iam.publicConfig
+ * if (config) {
+ *   const canOfferEmailOtp = config.login.email
+ *   const passwordMinLength = config.password.minLength
+ * }
+ * ```
+ */
+interface IamPublicConfig {
+    /** 页面显示密码策略，不包含密码哈希或账户信息。 */
+    password: ReturnType<typeof PasswordConfigSchema.parse>;
+    /** 自助注册开关；管理端创建账户仍需要独立授权。 */
+    register: {
+        enabled: boolean;
+    };
+    /** 方式开关同时考虑配置和发送回调就绪状态，避免展示无法使用的入口。 */
+    login: {
+        password: boolean;
+        otp: boolean;
+        ldap: boolean;
+        email: boolean;
+        sms: boolean;
+    };
+    /** 重置能力同时要求配置启用和通知发送回调就绪。 */
+    passwordReset: {
+        enabled: boolean;
+        mode: 'email' | 'phone';
+    };
+    /** 单位：验证码位数、重发间隔秒；安全计数与期限只由服务端执行。 */
+    otp: {
+        length: number;
+        resendInterval: number;
+    };
+    /** 用户协议及隐私政策展示配置。 */
+    agreements: IamConfig['agreements'];
+    /** 已经由外观 Schema 校验的标题、图像 URL 和布局。 */
+    ui: ReturnType<typeof AuthUiConfigSchema.parse>;
+    /** 默认 access 有效时长，单位秒；真实认证期限由服务端会话状态决定。 */
+    session: {
+        maxAge: number;
+    };
+}
+
+/**
+ * @h-ai/iam — 一次性票据类型
+ *
+ * 定义通用的短期、一次性能力票据（capability ticket）：由已认证的上下文签发，
+ * 绑定主体、用途与授权信息，在无法携带 Bearer Token 的通道（如 WebSocket URL）中
+ * 用作一次性入场凭证。典型用途：AI 语音 WebSocket 接入。
+ * @module ticket/iam-ticket-types
+ */
+
+/**
+ * 票据授权绑定信息
+ *
+ * 消费时原样返回，供服务端确认本次操作、模型、会话等参数与签发时一致。
+ * 除固定字段外允许应用自定义键值。
+ * @example
+ * ```ts
+ * import type { TicketGrant } from '@h-ai/iam'
+ * const value: TicketGrant = { operation: 'transcribe', model: 'speech-model', sessionId: 'conversation-1' }
+ * ```
+ */
+interface TicketGrant {
+    /** 操作类型（如 `'transcribe'` | `'synthesize'` 或应用自定义） */
+    operation?: string;
+    /** 模型 ID */
+    model?: string;
+    /** 会话 ID */
+    sessionId?: string;
+    /** 应用自定义绑定字段 */
+    [key: string]: unknown;
+}
+/**
+ * 签发一次性票据的选项
+ * @example
+ * ```ts
+ * import type { IssueTicketOptions } from '@h-ai/iam'
+ * const value: IssueTicketOptions = { subjectId: 'user-1', purpose: 'ai-audio', ttlMs: 30000, grant: { operation: 'transcribe' } }
+ * ```
+ */
+interface IssueTicketOptions {
+    /** 主体 ID（票据绑定的用户 / 主体，消费时原样返回） */
+    subjectId: string;
+    /** 票据用途（如 `'ai-audio'`），消费时校验一致 */
+    purpose: string;
+    /** 授权绑定信息（操作 / 模型 / 会话等，消费时原样返回） */
+    grant?: TicketGrant;
+    /** 有效期（毫秒，默认 30000） */
+    ttlMs?: number;
+}
+/**
+ * 签发结果
+ * @example
+ * ```ts
+ * import { iam, type IssuedTicket } from '@h-ai/iam'
+ * const issued = await iam.ticket.issue({ subjectId: 'user-1', purpose: 'ai-audio' })
+ * if (issued.success) {
+ *   const value: IssuedTicket = issued.data
+ *   value.expiresAt // 不能延长服务端签发期限；票据只能消费一次。
+ * }
+ * ```
+ */
+interface IssuedTicket {
+    /** 一次性票据值（密码学安全随机，base64url） */
+    ticket: string;
+    /** 过期时间（Unix 毫秒） */
+    expiresAt: number;
+}
+/**
+ * 消费票据的选项
+ * @example
+ * ```ts
+ * import type { ConsumeTicketOptions } from '@h-ai/iam'
+ * const value: ConsumeTicketOptions = { purpose: 'ai-audio' }
+ * ```
+ */
+interface ConsumeTicketOptions {
+    /** 期望用途；与签发用途不一致时返回 `TICKET_INVALID`（防止跨用途重放） */
+    purpose?: string;
+}
+/**
+ * 消费结果（校验通过并原子消费后返回）
+ * @example
+ * ```ts
+ * import { iam, type ConsumedTicket } from '@h-ai/iam'
+ * const consumed = await iam.ticket.consume('ticket-from-upgrade-request', { purpose: 'ai-audio' })
+ * if (consumed.success) {
+ *   const authorization: ConsumedTicket = consumed.data
+ *   authorization.grant.operation // 校验与本次请求操作相同。
+ * }
+ * ```
+ */
+interface ConsumedTicket {
+    /** 票据绑定的主体 ID */
+    subjectId: string;
+    /** 票据用途 */
+    purpose: string;
+    /** 授权绑定信息 */
+    grant: TicketGrant;
+}
+/**
+ * 一次性票据操作接口（通过 `iam.ticket` 访问）
+ *
+ * 提供密码学安全、带 TTL、原子单次消费的能力票据签发与消费。
+ * @example
+ * ```ts
+ * import { iam, type TicketOperations } from '@h-ai/iam'
+ * // 应用已完成 RelDB、Cache、Crypto 和 IAM 初始化。
+ * const operations: TicketOperations = iam.ticket
+ * const result = await operations.issue({ subjectId: 'user-1', purpose: 'ai-audio', ttlMs: 30000 })
+ * if (!result.success) {
+ *   result.error.code // 调用方将失败交给统一错误边界。
+ * }
+ * else {
+ *   result.data
+ * }
+ * ```
+ */
+interface TicketOperations {
+    /**
+     * 签发一次性票据
+     *
+     * 生成密码学安全随机值，绑定主体 / 用途 / 授权信息并按 TTL 存入 cache。
+     *
+     * @param options - 签发选项
+     * @returns 票据值与过期时间
+     */
+    issue: (options: IssueTicketOptions) => Promise<HaiResult<IssuedTicket>>;
+    /**
+     * 原子消费一次性票据
+     *
+     * 单次有效：并发消费同一票据时只有一个成功，其余返回 `TICKET_INVALID`。
+     * 票据不存在 / 已过期 / 已消费 / 用途不匹配时返回错误。
+     *
+     * @param ticket - 票据值
+     * @param options - 消费选项（可校验用途）
+     * @returns 主体 + 用途 + 授权信息
+     */
+    consume: (ticket: string, options?: ConsumeTicketOptions) => Promise<HaiResult<ConsumedTicket>>;
+}
+
+/**
+ * IAM 错误码及 HTTP 状态定义；调用方按 code 分支，底层原因只用于脱敏诊断。
+ * @example
+ * ```ts
+ * import { HaiIamError, iam } from '@h-ai/iam'
+ * const result = await iam.auth.verifyToken('token-from-authorization-header')
+ * if (!result.success && result.error.code === HaiIamError.SESSION_INVALID.code) {
+ *   // 由应用的认证边界转为重新登录响应，不泄露底层 cause。
+ * }
+ * ```
+ */
+declare const HaiIamError: {
+    readonly AUTH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly INVALID_CREDENTIALS: _h_ai_core.HaiErrorDef;
+    readonly USER_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly USER_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly USER_LOCKED: _h_ai_core.HaiErrorDef;
+    readonly USER_ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly PASSWORD_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly PASSWORD_POLICY_VIOLATION: _h_ai_core.HaiErrorDef;
+    readonly OTP_INVALID: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly OTP_RESEND_TOO_FAST: _h_ai_core.HaiErrorDef;
+    readonly LOGIN_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly REGISTER_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly STRATEGY_NOT_SUPPORTED: _h_ai_core.HaiErrorDef;
+    readonly APIKEY_INVALID: _h_ai_core.HaiErrorDef;
+    readonly APIKEY_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly APIKEY_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly APIKEY_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly RESET_TOKEN_INVALID: _h_ai_core.HaiErrorDef;
+    readonly RESET_TOKEN_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly RESET_TOKEN_MAX_ATTEMPTS: _h_ai_core.HaiErrorDef;
+    readonly OTP_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly SECURITY_BUSY: _h_ai_core.HaiErrorDef;
+    readonly PASSWORD_RESET_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly SESSION_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly SESSION_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly SESSION_INVALID: _h_ai_core.HaiErrorDef;
+    readonly SESSION_CREATE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TOKEN_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly TOKEN_INVALID: _h_ai_core.HaiErrorDef;
+    readonly TOKEN_REFRESH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly PERMISSION_DENIED: _h_ai_core.HaiErrorDef;
+    readonly ROLE_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly PERMISSION_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly ROLE_ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly PERMISSION_ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly LDAP_CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly LDAP_BIND_FAILED: _h_ai_core.HaiErrorDef;
+    readonly LDAP_SEARCH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TICKET_INVALID: _h_ai_core.HaiErrorDef;
+    readonly TICKET_EXPIRED: _h_ai_core.HaiErrorDef;
+    readonly TICKET_ISSUE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly REPOSITORY_ERROR: _h_ai_core.HaiErrorDef;
+    readonly NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly CONFLICT: _h_ai_core.HaiErrorDef;
+    readonly FORBIDDEN: _h_ai_core.HaiErrorDef;
+    readonly INVALID_ARGUMENT: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly INTERNAL_ERROR: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 已成功发布的认证通知上下文；发送服务必须按幂等键持久化去重。
+ * 回调抛错代表送达结果未知；IAM 不自动重发，也不回滚已经发布的凭据。
+ * @example
+ * ```ts
+ * import type { IamNotificationContext } from '@h-ai/iam'
+ * async function deliver(context: IamNotificationContext, enqueue: (key: string, expiresAt: Date) => Promise<void>) {
+ *   // 接收端持久去重；回调失败代表送达未知，不能擅自生成新的幂等键重发。
+ *   await enqueue(context.idempotencyKey, context.expiresAt)
+ * }
+ * ```
+ */
+interface IamNotificationContext {
+    /** 同一次凭据发布的稳定 ID，不包含验证码或明文令牌。 */
+    readonly idempotencyKey: string;
+    /** 凭据过期时间；迟到通知不得延长其有效期。 */
+    readonly expiresAt: Date;
+}
+/**
+ * IAM 初始化配置
+ *
+ * 包含 Zod 校验的设置字段和运行时依赖。
+ * 传入 `iam.init()` 的唯一参数。
+ * @example
+ * ```ts
+ * import type { IamConfigInput } from '@h-ai/iam'
+ * const value: IamConfigInput = { login: { password: true, otp: false }, register: { enabled: false }, seedDefaultData: false }
+ * ```
+ */
+interface IamConfigInput extends IamConfigSettingsInput {
+    /**
+     * 可选、已初始化的触达模块；由应用安装并注入，IAM 不导入或关闭该模块。
+     * 自动使用 otp_email、otp_sms、password_reset、password_reset_sms 模板；显式发送回调优先。
+     */
+    reach?: ReachFunctions;
+    /** LDAP 客户端工厂（可选）；启用 LDAP 且未注入时才加载应用安装的 ldapts。 */
+    ldapClientFactory?: LdapClientFactory;
+    /** LDAP 用户同步开关（默认 true） */
+    ldapSyncUser?: boolean;
+    /**
+     * 密码重置令牌回调（可选）
+     *
+     * 当用户请求密码重置时，框架生成令牌后通过此回调通知业务层，
+     * 业务层负责将令牌通过邮件/短信等渠道发送给用户。
+     * 也可传入已初始化的 reach 自动发送；两者均未配置时重置功能不可用。
+     *
+     * @param user - 请求重置的用户信息
+     * @param token - 重置令牌（明文，需发送给用户）
+     * @param context - 令牌有效期及接收端必须复用的幂等键；发送失败/超时视为结果未知。
+     */
+    onPasswordResetRequest?: (user: User, token: string, context: IamNotificationContext) => Promise<void>;
+    /**
+     * OTP 邮件验证码发送回调（可选）
+     *
+     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
+     * 业务层负责将验证码通过邮件发送给用户。
+     * 显式回调覆盖 Reach 的 otp_email 模板；两者均不可用时该登录入口关闭。
+     * 投递失败须拒绝 Promise，异常由 IAM 转为业务结果，不要在回调中吞掉失败。
+     *
+     * @param email - 目标邮箱
+     * @param code - 验证码
+     */
+    onOtpSendEmail?: (email: string, code: string, context: IamNotificationContext) => Promise<void>;
+    /**
+     * OTP 短信验证码发送回调（可选）
+     *
+     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
+     * 业务层负责将验证码通过短信发送给用户。
+     * 显式回调覆盖 Reach 的 otp_sms 模板；两者均不可用时该登录入口关闭。
+     * 投递失败须拒绝 Promise，异常由 IAM 转为业务结果，不要在回调中吞掉失败。
+     *
+     * @param phone - 目标手机号
+     * @param code - 验证码
+     */
+    onOtpSendSms?: (phone: string, code: string, context: IamNotificationContext) => Promise<void>;
+}
+/**
+ * IAM 函数接口
+ *
+ * 统一聚合所有 IAM 功能。
+ * @example
+ * ```ts
+ * import { iam, type IamFunctions } from '@h-ai/iam'
+ * const service: IamFunctions = iam
+ * // 应用先初始化 Cache、RelDB、Crypto；关闭时先停止接收请求。
+ * const initialized = await service.init({ seedDefaultData: false })
+ * if (initialized.success) {
+ *   const users = await service.user.listUsers({ page: 1, pageSize: 20 })
+ *   if (!users.success)
+ *     users.error.code
+ *   await service.close() // IAM 不关闭应用注入的依赖。
+ * }
+ * ```
+ */
+interface IamFunctions {
+    /**
+     * 初始化 IAM 服务
+     *
+     * 已初始化时先关闭旧内部状态再重新初始化；并发初始化返回配置错误。
+     * 内部按依赖顺序创建 session → authz → authn → user 子功能，
+     * 并可选执行种子数据初始化。
+     *
+     * @param config - IAM 初始化配置（可选 session/password/LDAP 等策略配置）
+     * @returns 成功返回 `ok(undefined)`；失败返回含错误码的 `err`
+     *
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * // 共享 RelDB、Cache 已由应用初始化；IAM 会确保 Crypto 可用。
+     * const result = await iam.init({ session: { maxAge: 86400 } })
+     * if (!result.success)
+     *   result.error.code // 交给应用统一错误边界，不能继续接收认证请求。
+     * ```
+     */
+    init: (config: IamConfigInput) => Promise<HaiResult<void>>;
+    /**
+     * 关闭 IAM 服务
+     *
+     * 释放所有内部子功能引用，将模块恢复到未初始化状态。
+     * 关闭后访问 `iam.auth` 等属性将返回未初始化错误。
+     */
+    close: () => Promise<void>;
+    /** 当前脱敏后的配置快照（未初始化时为 null） */
+    readonly config: IamConfig | null;
+    /** 安全且反映实际可用能力的认证页面配置。 */
+    readonly publicConfig: IamPublicConfig | null;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 注册功能是否启用（未初始化或未配置时默认启用） */
+    readonly isRegisterEnabled: boolean;
+    /** 认证操作（登录、登出、令牌验证等） */
+    readonly auth: AuthnOperations;
+    /** 用户管理（注册、查询、更新、密码管理等） */
+    readonly user: UserOperations;
+    /** 授权管理（角色/权限 CRUD、用户角色分配、权限检查） */
+    readonly authz: AuthzOperations;
+    /** 会话管理（创建、查询、验证、删除会话） */
+    readonly session: SessionOperations;
+    /** API Key 管理（创建、列表、吊销、验证），未启用 apikey 登录时返回未初始化代理 */
+    readonly apiKey: ApiKeyOperations;
+    /** 一次性能力票据（签发 / 原子消费短期票据，用于 WebSocket 等无法携带 Bearer Token 的通道） */
+    readonly ticket: TicketOperations;
+}
+
+export { type AgreementConfig, AgreementConfigSchema, type AgreementDisplay, type ApiKey, type ApiKeyConfig, ApiKeyConfigSchema, type ApiKeyCredentials, type ApiKeyOperations, type ApiKeySortDirection, type ApiKeySortField, type AuthResult, type AuthStrategy, type AuthStrategyType, AuthStrategyTypeSchema, type AuthUiConfig, AuthUiConfigSchema, type AuthnOperations, type AuthzOperations, type ConsumeTicketOptions, type ConsumedTicket, type CreateApiKeyOptions, type CreateApiKeyResult, type CreateSessionOptions, type Credentials, HaiIamError, type IamConfig, type IamConfigInput, IamConfigSchema, type IamConfigSettingsInput, type IamFunctions, type IamNotificationContext, type IamPublicConfig, type IssueTicketOptions, type IssuedTicket, type LdapClientFactory, type LdapConfig, LdapConfigSchema, type LdapCredentials, type ListApiKeysOptions, type ListUsersOptions, type LoginConfig, LoginConfigSchema, type OtpConfig, OtpConfigSchema, type OtpCredentials, type PasswordConfig, PasswordConfigSchema, type PasswordCredentials, type PasswordResetConfig, PasswordResetConfigSchema, type Permission, type PermissionQueryOptions, type PermissionType, type RbacConfig, RbacConfigSchema, type RegisterConfig, RegisterConfigSchema, type RegisterOptions, type RegisterResult, type Role, type SecurityConfig, SecurityConfigSchema, type Session, type SessionConfig, SessionConfigSchema, type SessionData, type SessionFieldUpdates, type SessionOperations, type StoredUser, type TicketGrant, type TicketOperations, type TokenPair, type UpdateCurrentUserInput, type User, type UserOperations, type UserSortDirection, type UserSortField };