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

package/dist/index.d.ts

@@ -1,1636 +1,32 @@
-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';
+import { IamFunctions } from './browser.js';
+export { AgreementConfig, AgreementConfigSchema, AgreementDisplay, ApiKey, ApiKeyConfig, ApiKeyConfigSchema, ApiKeyCredentials, ApiKeyOperations, ApiKeySortDirection, ApiKeySortField, AuthResult, AuthStrategy, AuthStrategyType, AuthStrategyTypeSchema, AuthUiConfig, AuthUiConfigSchema, AuthnOperations, AuthzOperations, ConsumeTicketOptions, ConsumedTicket, CreateApiKeyOptions, CreateApiKeyResult, CreateSessionOptions, Credentials, HaiIamError, IamConfig, IamConfigInput, IamConfigSchema, IamConfigSettingsInput, IamNotificationContext, IamPublicConfig, IssueTicketOptions, IssuedTicket, LdapClientFactory, LdapConfig, LdapConfigSchema, LdapCredentials, ListApiKeysOptions, ListUsersOptions, LoginConfig, LoginConfigSchema, OtpConfig, OtpConfigSchema, OtpCredentials, PasswordConfig, PasswordConfigSchema, PasswordCredentials, PasswordResetConfig, PasswordResetConfigSchema, Permission, PermissionQueryOptions, PermissionType, RbacConfig, RbacConfigSchema, RegisterConfig, RegisterConfigSchema, RegisterOptions, RegisterResult, Role, SecurityConfig, SecurityConfigSchema, Session, SessionConfig, SessionConfigSchema, SessionData, SessionFieldUpdates, SessionOperations, StoredUser, TicketGrant, TicketOperations, TokenPair, UpdateCurrentUserInput, User, UserOperations, UserSortDirection, UserSortField } from './browser.js';
+import 'zod';
+import '@h-ai/core';
+import '@h-ai/reach';
+import '@h-ai/reldb';
 
 /**
- * @h-ai/iam — 配置 Schema
+ * @h-ai/iam — IAM 服务主入口
  *
- * 本文件定义 IAM 模块的配置结构，使用 Zod 进行运行时校验。
- * @module iam-config
+ * 管理运行时状态、实现生命周期（init / close）、通过 get 访问器暴露子功能。
+ * @module iam-main
  */
 
 /**
- * 认证策略类型
- *
- * 支持的认证方式：
- * - `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<{
-    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 配置类型 */
-type OtpConfig = z.infer<typeof OtpConfigSchema>;
-/**
- * 密码重置配置 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>;
-/** 密码重置配置类型 */
-type PasswordResetConfig = z.infer<typeof PasswordResetConfigSchema>;
-/**
- * LDAP 配置 Schema
- */
-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 配置类型 */
-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<{
-    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>;
-type AgreementConfig = z.infer<typeof AgreementConfigSchema>;
-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>;
-type AuthUiConfig = z.infer<typeof AuthUiConfigSchema>;
-/**
- * 会话配置 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
- *
+ * IAM 服务单例；应用先初始化共享 RelDB/Cache，再 init → use → close，子功能返回 HaiResult。
  * @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 }
+ * import { iam } from '@h-ai/iam'
+ * // Cache、RelDB、Crypto 已由应用按顺序初始化。
+ * const initialized = await iam.init({ seedDefaultData: false })
+ * if (initialized.success) {
+ *   const result = await iam.user.getUser('user-1')
+ *   if (result.success && result.data)
+ *     result.data.username
+ *   await iam.close()
  * }
  * ```
  */
-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 配置类型 */
-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;
-    /** 权限代码范围；默认空数组。受限 key 不保留角色授权入口，使用 permission 守卫。 */
-    scopes?: string[];
-}
-/** API Key 列表允许的服务端排序字段。 */
-type ApiKeySortField = 'name' | 'createdAt' | 'lastUsedAt' | 'expiresAt';
-/** API Key 列表排序方向。 */
-type ApiKeySortDirection = 'asc' | 'desc';
-/**
- * API Key 列表查询选项
- */
-interface ListApiKeysOptions extends PaginationOptionsInput {
-    /** 搜索关键字（模糊匹配名称与密钥前缀） */
-    search?: string;
-    /** 按启用状态过滤，不传则返回全部 */
-    enabled?: boolean;
-    /** 服务端排序字段；未指定时保持按创建时间倒序的历史行为。 */
-    sortBy?: ApiKeySortField;
-    /** 服务端排序方向；仅在指定 sortBy 时生效，默认 desc。 */
-    sortDirection?: ApiKeySortDirection;
-}
-/**
- * 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
-     * @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：操作按钮显隐控制
- */
-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 {
-    /** 查询当前角色与权限代码，一次读取角色并批量聚合权限，不依赖会话缓存。 */
-    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
- */
-
-/** 用户列表允许的服务端排序字段。 */
-type UserSortField = 'username' | 'email' | 'displayName' | 'enabled' | 'createdAt';
-/** 用户列表排序方向。 */
-type UserSortDirection = 'asc' | 'desc';
-/**
- * 用户列表查询选项
- */
-interface ListUsersOptions extends PaginationOptionsInput {
-    /** 角色 code 精确筛选，在数据库分页前执行。 */
-    roleCode?: string;
-    /** 搜索关键字（模糊匹配用户名、邮箱、手机号、显示名称） */
-    search?: string;
-    /** 按启用状态过滤，不传则返回全部 */
-    enabled?: boolean;
-    /** 服务端排序字段；未指定时保持按创建时间倒序的历史行为。 */
-    sortBy?: UserSortField;
-    /** 服务端排序方向；仅在指定 sortBy 时生效，默认 desc。 */
-    sortDirection?: UserSortDirection;
-    /** 包含关联数据（如 '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 {
-    /** 用户协议 Markdown 正文，显示优先于 URL。 */
-    userAgreementMarkdown?: string;
-    /** 隐私协议 Markdown 正文，显示优先于 URL。 */
-    privacyPolicyMarkdown?: string;
-    /** 用户协议 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 {
-    /** 批量查询最多 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>>;
-    /**
-     * 请求密码重置
-     *
-     * 查找用户 → 生成重置令牌（缓存存储、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 {
-    /** 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;
-    /** 扩展数据（内部保留 _tokenPair 供 logout 时吊销 refreshToken） */
-    data?: SessionData;
-}
-/**
- * 会话扩展数据
- *
- * 支持开放的 Record 扩展，同时约束内部保留字段 _tokenPair。
- */
-type SessionData = Record<string, unknown> & {
-    /** 令牌对（内部保留字段，由 session.create 写入，logout 时读取） */
-    _tokenPair?: TokenPair;
-};
-/**
- * 创建会话选项
- */
-interface CreateSessionOptions {
-    /** 服务端已验证的 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;
-}
-/**
- * 会话子功能接口
- */
-interface SessionOperations {
-    /**
-     * 创建会话
-     *
-     * 单设备模式下会先清除用户已有的所有会话。
-     *
-     * @param options - 会话创建选项（用户 ID、角色、来源等）
-     * @returns 成功返回完整的 Session 对象（含生成的访问令牌和过期时间）
-     */
-    create: (options: CreateSessionOptions) => Promise<HaiResult<Session>>;
-    /**
-     * 获取会话
-     *
-     * 查询缓存中的会话数据。API Key 会话先重新校验持久化 key 与 scopes；滑动窗口模式下自动续期。
-     * 已过期的会话会自动删除并返回 null。
-     *
-     * @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>>;
-    /**
-     * 更新会话
-     *
-     * 合并 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 有效性 → 查找关联用户 → 按 scopes 收敛授权 → 创建绑定 key 的会话。
-     * 空 scopes 无操作权限；显式 * 也不超出主体权限。受限 key 通过 permission 授权，不保留角色入口。
-     *
-     * @param credentials - API Key 凭证
-     * @returns 成功返回 AuthResult；API Key 无效/过期/禁用返回对应错误
-     */
-    loginWithApiKey: (credentials: ApiKeyCredentials) => Promise<HaiResult<AuthResult>>;
-    /**
-     * 登出
-     *
-     * 删除会话数据和用户令牌映射。令牌无效时静默成功。
-     *
-     * @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 客户端接口
- */
-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>>;
-
-/** 提供给认证页面的白名单配置；不含连接信息、密钥及安全状态。 */
-
-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'];
-    ui: ReturnType<typeof AuthUiConfigSchema.parse>;
-    session: {
-        maxAge: number;
-    };
-}
-
-/**
- * @h-ai/iam — 一次性票据类型
- *
- * 定义通用的短期、一次性能力票据（capability ticket）：由已认证的上下文签发，
- * 绑定主体、用途与授权信息，在无法携带 Bearer Token 的通道（如 WebSocket URL）中
- * 用作一次性入场凭证。典型用途：AI 语音 WebSocket 接入。
- * @module ticket/iam-ticket-types
- */
-
-/**
- * 票据授权绑定信息
- *
- * 消费时原样返回，供服务端确认本次操作、模型、会话等参数与签发时一致。
- * 除固定字段外允许应用自定义键值。
- */
-interface TicketGrant {
-    /** 操作类型（如 `'transcribe'` | `'synthesize'` 或应用自定义） */
-    operation?: string;
-    /** 模型 ID */
-    model?: string;
-    /** 会话 ID */
-    sessionId?: string;
-    /** 应用自定义绑定字段 */
-    [key: string]: unknown;
-}
-/**
- * 签发一次性票据的选项
- */
-interface IssueTicketOptions {
-    /** 主体 ID（票据绑定的用户 / 主体，消费时原样返回） */
-    subjectId: string;
-    /** 票据用途（如 `'ai-audio'`），消费时校验一致 */
-    purpose: string;
-    /** 授权绑定信息（操作 / 模型 / 会话等，消费时原样返回） */
-    grant?: TicketGrant;
-    /** 有效期（毫秒，默认 30000） */
-    ttlMs?: number;
-}
-/**
- * 签发结果
- */
-interface IssuedTicket {
-    /** 一次性票据值（密码学安全随机，base64url） */
-    ticket: string;
-    /** 过期时间（Unix 毫秒） */
-    expiresAt: number;
-}
-/**
- * 消费票据的选项
- */
-interface ConsumeTicketOptions {
-    /** 期望用途；与签发用途不一致时返回 `TICKET_INVALID`（防止跨用途重放） */
-    purpose?: string;
-}
-/**
- * 消费结果（校验通过并原子消费后返回）
- */
-interface ConsumedTicket {
-    /** 票据绑定的主体 ID */
-    subjectId: string;
-    /** 票据用途 */
-    purpose: string;
-    /** 授权绑定信息 */
-    grant: TicketGrant;
-}
-/**
- * 一次性票据操作接口（通过 `iam.ticket` 访问）
- *
- * 提供密码学安全、带 TTL、原子单次消费的能力票据签发与消费。
- */
-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>>;
-}
-
-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 初始化配置
- *
- * 包含 Zod 校验的设置字段和运行时依赖。
- * 传入 `iam.init()` 的唯一参数。
- */
-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 expiresAt - 令牌过期时间
-     */
-    onPasswordResetRequest?: (user: User, token: string, expiresAt: Date) => Promise<void>;
-    /**
-     * OTP 邮件验证码发送回调（可选）
-     *
-     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
-     * 业务层负责将验证码通过邮件发送给用户。
-     * 显式回调覆盖 Reach 的 otp_email 模板；两者均不可用时该登录入口关闭。
-     * 投递失败须拒绝 Promise，异常由 IAM 转为业务结果，不要在回调中吞掉失败。
-     *
-     * @param email - 目标邮箱
-     * @param code - 验证码
-     */
-    onOtpSendEmail?: (email: string, code: string) => Promise<void>;
-    /**
-     * OTP 短信验证码发送回调（可选）
-     *
-     * 当用户请求 OTP 验证码时，框架生成验证码后通过此回调通知业务层，
-     * 业务层负责将验证码通过短信发送给用户。
-     * 显式回调覆盖 Reach 的 otp_sms 模板；两者均不可用时该登录入口关闭。
-     * 投递失败须拒绝 Promise，异常由 IAM 转为业务结果，不要在回调中吞掉失败。
-     *
-     * @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 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;
-}
-
-/**
- * @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 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 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, iam };
+export { IamFunctions, iam };