@h-ai/iam 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,1394 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult, PaginationOptionsInput, PaginatedResult } from '@h-ai/core';
+import { DmlWithTxOperations } from '@h-ai/reldb';
+
+/**
+ * @h-ai/iam — 配置 Schema
+ *
+ * 本文件定义 IAM 模块的配置结构，使用 Zod 进行运行时校验。
+ * @module iam-config
+ */
+
+/**
+ * 认证策略类型
+ *
+ * 支持的认证方式：
+ * - `password` - 用户名/邮箱 + 密码
+ * - `otp` - 邮箱/短信 + 验证码
+ * - `ldap` - LDAP 目录认证
+ */
+declare const AuthStrategyTypeSchema: z.ZodEnum<{
+    password: "password";
+    otp: "otp";
+    ldap: "ldap";
+    apikey: "apikey";
+}>;
+/** 认证策略类型 */
+type AuthStrategyType = z.infer<typeof AuthStrategyTypeSchema>;
+/**
+ * 密码配置 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>;
+/** 密码配置类型 */
+type PasswordConfig = z.infer<typeof PasswordConfigSchema>;
+/**
+ * OTP 配置 Schema
+ */
+declare const OtpConfigSchema: z.ZodObject<{
+    length: z.ZodDefault<z.ZodNumber>;
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+    resendInterval: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** OTP 配置类型 */
+type OtpConfig = z.infer<typeof OtpConfigSchema>;
+/**
+ * 密码重置配置 Schema
+ */
+declare const PasswordResetConfigSchema: z.ZodObject<{
+    tokenExpiresIn: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** 密码重置配置类型 */
+type PasswordResetConfig = z.infer<typeof PasswordResetConfigSchema>;
+/**
+ * LDAP 配置 Schema
+ */
+declare const LdapConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    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 配置类型 */
+type LdapConfig = z.infer<typeof LdapConfigSchema>;
+/**
+ * API Key 配置 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 配置类型 */
+type ApiKeyConfig = z.infer<typeof ApiKeyConfigSchema>;
+/** 登录类型启用配置 */
+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>;
+type LoginConfig = z.infer<typeof LoginConfigSchema>;
+/** 注册配置 */
+declare const RegisterConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    defaultEnabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type RegisterConfig = z.infer<typeof RegisterConfigSchema>;
+/** 安全策略配置 */
+declare const SecurityConfigSchema: z.ZodObject<{
+    maxLoginAttempts: z.ZodDefault<z.ZodNumber>;
+    lockoutDuration: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
+/** 协议展示配置 */
+declare const AgreementConfigSchema: z.ZodObject<{
+    userAgreementUrl: z.ZodOptional<z.ZodURL>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodURL>;
+    showOnRegister: z.ZodDefault<z.ZodBoolean>;
+    showOnLogin: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type AgreementConfig = z.infer<typeof AgreementConfigSchema>;
+/**
+ * 会话配置 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>;
+/** 会话配置类型 */
+type SessionConfig = z.infer<typeof SessionConfigSchema>;
+/**
+ * RBAC 配置 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 配置类型 */
+type RbacConfig = z.infer<typeof RbacConfigSchema>;
+/**
+ * IAM 统一配置 Schema
+ *
+ * @example
+ * ```ts
+ * const config: IamConfig = {
+ *     password: { minLength: 8 },
+ *     session: {
+ *         maxAge: 86400,
+ *         sliding: true
+ *     },
+ *     login: { password: true, otp: true },
+ *     register: { enabled: true, defaultEnabled: true },
+ *     rbac: { enabled: true }
+ * }
+ * ```
+ */
+declare const IamConfigSchema: z.ZodObject<{
+    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<{
+        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.ZodString;
+        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<{
+        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<{
+        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.ZodOptional<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 配置类型 */
+type IamConfig = z.infer<typeof IamConfigSchema>;
+/**
+ * IAM 配置设置输入类型（仅设置字段，不含运行时依赖）
+ *
+ * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
+ */
+type IamConfigSettingsInput = z.input<typeof IamConfigSchema>;
+
+/**
+ * @h-ai/iam — API Key 类型定义
+ *
+ * 包含 API Key 实体、创建选项、查询选项等类型。
+ * @module iam-authn-apikey-types
+ */
+
+/**
+ * API Key 实体（对外展示）
+ *
+ * 不含密钥哈希等敏感信息。
+ */
+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 的返回结果
+ *
+ * 仅在创建时返回明文密钥，之后无法再获取。
+ */
+interface CreateApiKeyResult {
+    /** API Key 元数据 */
+    apiKey: ApiKey;
+    /** 明文密钥（仅此一次展示） */
+    rawKey: string;
+}
+/**
+ * 创建 API Key 选项
+ */
+interface CreateApiKeyOptions {
+    /** API Key 名称 */
+    name: string;
+    /** 有效期天数（0 或不传表示永不过期） */
+    expirationDays?: number;
+    /** 权限范围 */
+    scopes?: string[];
+}
+/**
+ * API Key 管理操作接口
+ */
+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
+     * @returns API Key 列表（不含密钥哈希）
+     */
+    listApiKeys: (userId: string) => Promise<HaiResult<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）
+ *
+ * @h-ai/iam — 授权子功能类型定义（RBAC）
+ * @module iam-authz-types
+ */
+
+/**
+ * 权限类型
+ *
+ * - menu：菜单/导航可见性控制
+ * - api：接口级访问控制
+ * - button：操作按钮显隐控制
+ */
+type PermissionType = 'menu' | 'api' | 'button';
+/**
+ * 权限查询参数
+ *
+ * 扩展分页参数，支持按类型和关键字筛选。
+ */
+interface PermissionQueryOptions extends PaginationOptionsInput {
+    /** 按权限类型筛选 */
+    type?: PermissionType;
+    /** 按关键字搜索（匹配 code 或 name） */
+    search?: string;
+}
+/**
+ * 权限
+ */
+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;
+}
+/**
+ * 角色
+ */
+interface Role {
+    /** 角色 ID */
+    id: string;
+    /** 角色代码 */
+    code: string;
+    /** 角色名称 */
+    name: string;
+    /** 角色描述 */
+    description?: string;
+    /** 是否系统角色（不可删除） */
+    isSystem?: boolean;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+}
+/**
+ * 授权子功能接口
+ */
+interface AuthzOperations {
+    /**
+     * 检查权限
+     *
+     * 超级管理员角色自动拥有所有权限。
+     * 支持通配符匹配（如 `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'>, 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>>>;
+    /**
+     * 更新角色
+     *
+     * @param roleId - 角色 ID
+     * @param data - 要更新的字段（name、description 等）
+     * @returns 成功返回更新后的角色；角色不存在返回 ROLE_NOT_FOUND
+     */
+    updateRole: (roleId: string, data: Partial<Omit<Role, 'id' | 'createdAt' | 'updatedAt'>>, 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
+ */
+
+/**
+ * 用户列表查询选项
+ */
+interface ListUsersOptions extends PaginationOptionsInput {
+    /** 搜索关键字（模糊匹配用户名、邮箱、手机号、显示名称） */
+    search?: string;
+    /** 按启用状态过滤，不传则返回全部 */
+    enabled?: boolean;
+    /** 包含关联数据（如 'roles' 表示同时返回用户角色列表） */
+    include?: ('roles')[];
+}
+/**
+ * 用户基础信息
+ */
+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[];
+}
+/**
+ * 用户协议/隐私协议展示配置
+ */
+interface AgreementDisplay {
+    /** 用户协议 URL */
+    userAgreementUrl?: string;
+    /** 隐私协议 URL */
+    privacyPolicyUrl?: string;
+    /** 注册时展示协议 */
+    showOnRegister: boolean;
+    /** 登录时展示协议 */
+    showOnLogin: boolean;
+}
+/**
+ * 内部存储用户（包含密码哈希等敏感信息）
+ */
+interface StoredUser extends User {
+    /** 密码哈希 */
+    passwordHash?: string;
+    /** 密码更新时间 */
+    passwordUpdatedAt?: Date;
+    /** 登录失败次数 */
+    loginFailedCount?: number;
+    /** 最后登录失败时间 */
+    lastLoginFailedAt?: Date;
+    /** 锁定截止时间 */
+    lockedUntil?: Date;
+}
+/**
+ * 用户注册选项
+ */
+interface RegisterOptions {
+    /** 用户名 */
+    username: string;
+    /** 邮箱 */
+    email?: string;
+    /** 手机号 */
+    phone?: string;
+    /** 密码 */
+    password: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 扩展属性 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 注册结果
+ */
+interface RegisterResult {
+    /** 用户信息 */
+    user: User;
+    /** 协议展示信息（可选） */
+    agreements?: AgreementDisplay;
+}
+/**
+ * 当前登录用户可自行修改的字段白名单
+ *
+ * 仅允许修改个人资料相关字段，禁止修改安全字段（enabled、emailVerified、roles 等）。
+ */
+interface UpdateCurrentUserInput {
+    /** 用户名 */
+    username?: string;
+    /** 邮箱 */
+    email?: string;
+    /** 显示名称 */
+    displayName?: string;
+    /** 头像 URL */
+    avatarUrl?: string;
+    /** 手机号 */
+    phone?: string;
+    /** 扩展属性 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 用户子功能接口
+ */
+interface UserOperations {
+    /**
+     * 注册用户
+     *
+     * 校验注册开关、密码强度、用户名/邮箱唯一性后，
+     * 在事务中创建用户并分配默认角色。
+     *
+     * @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'] 同时返回角色列表）
+     * @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>>;
+    /**
+     * 请求密码重置
+     *
+     * 查找用户 → 生成重置令牌（缓存存储、SHA-256 哈希）→ 调用 onPasswordResetRequest 回调通知业务层。
+     * 即使用户不存在也返回 ok（防止用户枚举攻击）。
+     *
+     * @param identifier - 用户标识（邮箱）
+     * @returns 始终返回 ok（防枚举）；内部异常返回 INTERNAL_ERROR
+     */
+    requestPasswordReset: (identifier: string) => Promise<HaiResult<void>>;
+    /**
+     * 确认密码重置
+     *
+     * 验证新密码强度 → 验证令牌有效性与尝试次数 → 哈希并更新密码 → 删除令牌 → 清除该用户所有会话。
+     *
+     * @param token - 重置令牌（明文，由 requestPasswordReset 生成并由业务层发送给用户）
+     * @param newPassword - 新密码
+     * @returns 成功返回 ok；令牌无效/过期返回 RESET_TOKEN_INVALID，尝试超限返回 RESET_TOKEN_MAX_ATTEMPTS
+     */
+    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 认证流程。
+ */
+interface TokenPair {
+    /** 访问令牌（短期，用于 API 认证） */
+    accessToken: string;
+    /** 刷新令牌（长期，用于换取新 accessToken） */
+    refreshToken: string;
+    /** accessToken 过期时间（秒） */
+    expiresIn: number;
+    /** 令牌类型，固定为 'Bearer' */
+    tokenType: 'Bearer';
+}
+/**
+ * 认证结果
+ *
+ * 登录/注册成功后返回，包含用户信息、令牌、角色权限等。
+ * `roles` / `permissions` 来源于会话创建时写入的 RBAC 数据，
+ * 调用方无需再通过 `verifyToken` 获取。
+ */
+interface AuthResult {
+    /** 用户信息 */
+    user: User;
+    /** 令牌对（替代原来的单个 accessToken） */
+    tokens: TokenPair;
+    /** 角色 code 列表（登录时从 RBAC 写入） */
+    roles: string[];
+    /** 权限 code 列表（登录时从 RBAC 写入） */
+    permissions: string[];
+    /** 协议展示信息（可选） */
+    agreements?: AgreementDisplay;
+}
+/**
+ * 会话数据
+ */
+interface Session {
+    /** 用户 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;
+    /** 扩展数据（内部保留 _tokenPair 供 logout 时吊销 refreshToken） */
+    data?: SessionData;
+}
+/**
+ * 会话扩展数据
+ *
+ * 支持开放的 Record 扩展，同时约束内部保留字段 _tokenPair。
+ */
+type SessionData = Record<string, unknown> & {
+    /** 令牌对（内部保留字段，由 session.create 写入，logout 时读取） */
+    _tokenPair?: TokenPair;
+};
+/**
+ * 创建会话选项
+ */
+interface CreateSessionOptions {
+    /** 用户 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;
+}
+/**
+ * 会话子功能接口
+ */
+interface SessionOperations {
+    /**
+     * 创建会话
+     *
+     * 单设备模式下会先清除用户已有的所有会话。
+     *
+     * @param options - 会话创建选项（用户 ID、角色、来源等）
+     * @returns 成功返回完整的 Session 对象（含生成的访问令牌和过期时间）
+     */
+    create: (options: CreateSessionOptions) => Promise<HaiResult<Session>>;
+    /**
+     * 获取会话
+     *
+     * 查询缓存中的会话数据。滑动窗口模式下自动续期。
+     * 已过期的会话会自动删除并返回 null。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回会话对象或 null（会话不存在/已过期）
+     */
+    get: (accessToken: string) => Promise<HaiResult<Session | null>>;
+    /**
+     * 验证访问令牌
+     *
+     * 等同于 get 但在会话不存在时返回错误而非 null。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 成功返回会话；会话无效返回 SESSION_INVALID
+     */
+    verifyToken: (accessToken: string) => Promise<HaiResult<Session>>;
+    /**
+     * 更新会话
+     *
+     * 合并 patch 到现有会话（data 字段浅合并）并更新 lastActiveAt。
+     *
+     * @param accessToken - 访问令牌
+     * @param data - 要更新的字段（roles、username、source、data 等）
+     * @returns 成功返回 ok；会话不存在返回 SESSION_NOT_FOUND
+     */
+    update: (accessToken: string, data: Partial<Session>) => Promise<HaiResult<void>>;
+    /**
+     * 删除会话
+     *
+     * 同时清除用户令牌映射关系。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 始终返回 ok（令牌不存在时静默成功）
+     */
+    delete: (accessToken: string) => Promise<HaiResult<void>>;
+    /**
+     * 删除用户所有会话
+     *
+     * 遍历用户的所有令牌并逐一删除。
+     *
+     * @param userId - 用户 ID
+     * @returns 成功返回实际删除的会话数量
+     */
+    deleteByUserId: (userId: string) => Promise<HaiResult<number>>;
+    /**
+     * 通过 refreshToken 换取新的 TokenPair
+     *
+     * 验证 refreshToken 有效性，签发新的 accessToken + refreshToken，
+     * 旧 refreshToken 自动失效（Rotation 策略）。
+     *
+     * @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）
+ *
+ * 用于角色/权限变更后的会话同步。
+ */
+interface SessionFieldUpdates {
+    /** 角色 code 列表 */
+    roles?: string[];
+    /** 权限 code 列表 */
+    permissions?: string[];
+}
+
+/**
+ * @h-ai/iam — 认证类型定义
+ *
+ * 包含： - 凭证类型（Credentials） - 认证策略接口（AuthStrategy） - 认证操作接口（AuthnOperations）
+ * @module iam-authn-types
+ */
+
+/**
+ * 用户凭证（用于密码登录）
+ */
+interface PasswordCredentials {
+    /** 用户名/邮箱/手机号 */
+    identifier: string;
+    /** 密码 */
+    password: string;
+    /** 记住我 */
+    rememberMe?: boolean;
+}
+/**
+ * OTP 凭证（用于验证码登录）
+ */
+interface OtpCredentials {
+    /** 邮箱/手机号 */
+    identifier: string;
+    /** 验证码 */
+    code: string;
+}
+/**
+ * LDAP 凭证
+ */
+interface LdapCredentials {
+    /** 用户名 */
+    username: string;
+    /** 密码 */
+    password: string;
+}
+/**
+ * API Key 凭证（用于 API Key 认证）
+ */
+interface ApiKeyCredentials {
+    /** 明文 API Key */
+    key: string;
+}
+/**
+ * 统一凭证类型
+ */
+type Credentials = {
+    type: 'password';
+} & PasswordCredentials | {
+    type: 'otp';
+} & OtpCredentials | {
+    type: 'ldap';
+} & LdapCredentials | {
+    type: 'apikey';
+} & ApiKeyCredentials;
+/**
+ * 认证策略接口
+ *
+ * 所有认证方式（密码/OTP/LDAP）都实现此接口
+ */
+interface AuthStrategy {
+    /** 策略类型 */
+    readonly type: AuthStrategyType;
+    /** 策略名称 */
+    readonly name: string;
+    /**
+     * 执行认证
+     *
+     * @param credentials - 统一凭证（包含 type 字段标识认证方式）
+     * @returns 认证成功返回用户信息；失败返回对应错误码（INVALID_CREDENTIALS / USER_LOCKED 等）
+     */
+    authenticate: (credentials: Credentials) => Promise<HaiResult<User>>;
+}
+/**
+ * 认证子功能接口
+ */
+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 有效性 → 查找关联用户 → 创建会话 → 返回令牌。
+     *
+     * @param credentials - API Key 凭证
+     * @returns 成功返回 AuthResult；API Key 无效/过期/禁用返回对应错误
+     */
+    loginWithApiKey: (credentials: ApiKeyCredentials) => Promise<HaiResult<AuthResult>>;
+    /**
+     * 登出
+     *
+     * 删除会话数据和用户令牌映射。令牌无效时静默成功。
+     *
+     * @param accessToken - 访问令牌
+     * @returns 始终返回 ok
+     */
+    logout: (accessToken: string) => Promise<HaiResult<void>>;
+    /**
+     * 验证令牌
+     *
+     * 查询会话并校验有效性，滑动窗口模式下自动续期。
+     *
+     * @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 客户端接口
+ */
+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 搜索结果条目
+ */
+interface LdapSearchEntry {
+    /** DN */
+    dn: string;
+    /** 属性 */
+    attributes: Record<string, string | string[]>;
+}
+/**
+ * LDAP 客户端工厂
+ */
+type LdapClientFactory = (config: LdapConfig) => Promise<HaiResult<LdapClient>>;
+
+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 OTP_EXPIRED: _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 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 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 NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly INTERNAL_ERROR: _h_ai_core.HaiErrorDef;
+};
+/**
+ * IAM 初始化配置
+ *
+ * 包含 Zod 校验的设置字段和运行时依赖。
+ * 传入 `iam.init()` 的唯一参数。
+ */
+interface IamConfigInput extends IamConfigSettingsInput {
+    /** LDAP 客户端工厂（启用 LDAP 登录时必填） */
+    ldapClientFactory?: LdapClientFactory;
+    /** LDAP 用户同步开关（默认 true） */
+    ldapSyncUser?: boolean;
+    /**
+     * 密码重置令牌回调（可选）
+     *
+     * 当用户请求密码重置时，框架生成令牌后通过此回调通知业务层，
+     * 业务层负责将令牌通过邮件/短信等渠道发送给用户。
+     * 若未提供此回调，requestPasswordReset 将仅记录日志不发送通知。
+     *
+     * @param user - 请求重置的用户信息
+     * @param token - 重置令牌（明文，需发送给用户）
+     * @param expiresAt - 令牌过期时间
+     */
+    onPasswordResetRequest?: (user: User, token: string, expiresAt: Date) => Promise<void>;
+    /**
+     * OTP 邮件验证码发送回调（可选）
+     *
+     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
+     * 业务层负责将验证码通过邮件发送给用户。
+     * 若未提供此回调，sendOtp 将返回"发送方式未配置"错误。
+     *
+     * @param email - 目标邮箱
+     * @param code - 验证码
+     */
+    onOtpSendEmail?: (email: string, code: string) => Promise<void>;
+    /**
+     * OTP 短信验证码发送回调（可选）
+     *
+     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
+     * 业务层负责将验证码通过短信发送给用户。
+     * 若未提供此回调，sendOtp 将返回"发送方式未配置"错误。
+     *
+     * @param phone - 目标手机号
+     * @param code - 验证码
+     */
+    onOtpSendSms?: (phone: string, code: string) => Promise<void>;
+}
+/**
+ * IAM 函数接口
+ *
+ * 统一聚合所有 IAM 功能。
+ */
+interface IamFunctions {
+    /**
+     * 初始化 IAM 服务
+     *
+     * 幂等操作：已初始化时直接返回成功。
+     * 内部按依赖顺序创建 session → authz → authn → user 子功能，
+     * 并可选执行种子数据初始化。
+     *
+     * @param config - IAM 初始化配置（可选 session/password/LDAP 等策略配置）
+     * @returns 成功返回 `ok(undefined)`；失败返回含错误码的 `err`
+     *
+     * @example
+     * ```ts
+     * const result = await iam.init({ session: { maxAge: 86400 } })
+     * if (!result.success) {
+     *   console.error(result.error.message)
+     * }
+     * ```
+     */
+    init: (config: IamConfigInput) => Promise<HaiResult<void>>;
+    /**
+     * 关闭 IAM 服务
+     *
+     * 释放所有内部子功能引用，将模块恢复到未初始化状态。
+     * 关闭后访问 `iam.auth` 等属性将返回未初始化错误。
+     */
+    close: () => Promise<void>;
+    /** 当前配置（未初始化时为 null） */
+    readonly config: IamConfig | 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;
+}
+
+/**
+ * @h-ai/iam — IAM 服务主入口
+ *
+ * 管理运行时状态、实现生命周期（init / close）、通过 get 访问器暴露子功能。
+ * @module iam-main
+ */
+
+declare const iam: IamFunctions;
+
+export { type AgreementConfig, AgreementConfigSchema, type AgreementDisplay, type ApiKey, type ApiKeyConfig, ApiKeyConfigSchema, type ApiKeyCredentials, type ApiKeyOperations, type AuthResult, type AuthStrategy, type AuthStrategyType, AuthStrategyTypeSchema, type AuthnOperations, type AuthzOperations, type CreateApiKeyOptions, type CreateApiKeyResult, type CreateSessionOptions, type Credentials, HaiIamError, type IamConfig, type IamConfigInput, IamConfigSchema, type IamConfigSettingsInput, type IamFunctions, type LdapClientFactory, type LdapConfig, LdapConfigSchema, type LdapCredentials, 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 TokenPair, type UpdateCurrentUserInput, type User, type UserOperations, iam };