@h-ai/iam 0.1.0-alpha.72 → 0.1.0-alpha.74

package/dist/browser.d.ts

@@ -2,6 +2,7 @@ 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 { Challenge } from 'altcha/lib';
 import { DmlWithTxOperations } from '@h-ai/reldb';
 
 /**
@@ -61,7 +62,10 @@ declare const PasswordConfigSchema: z.ZodObject<{
     requireLowercase: z.ZodDefault<z.ZodBoolean>;
     requireNumber: z.ZodDefault<z.ZodBoolean>;
     requireSpecialChar: z.ZodDefault<z.ZodBoolean>;
+    minCharacterClasses: z.ZodDefault<z.ZodNumber>;
     expirationDays: z.ZodDefault<z.ZodNumber>;
+    preventSamePassword: z.ZodDefault<z.ZodBoolean>;
+    requireInitialChange: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * 密码配置类型
@@ -255,9 +259,25 @@ type RegisterConfig = z.infer<typeof RegisterConfigSchema>;
  * ```
  */
 declare const SecurityConfigSchema: z.ZodObject<{
+    lockoutEnabled: z.ZodDefault<z.ZodBoolean>;
+    failureWindow: z.ZodDefault<z.ZodNumber>;
     maxLoginAttempts: z.ZodDefault<z.ZodNumber>;
     lockoutDuration: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * 自托管 ALTCHA 计算挑战；默认关闭，强度与有效期由应用设置。
+ * @example
+ * ```ts
+ * import { CaptchaConfigSchema } from '@h-ai/iam'
+ * const config = CaptchaConfigSchema.parse({ enabled: true, ttlSeconds: 120 })
+ * ```
+ */
+declare const CaptchaConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    ttlSeconds: z.ZodDefault<z.ZodNumber>;
+    cost: z.ZodDefault<z.ZodNumber>;
+    maxCounter: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * 服务端账户失败计数与锁定策略。
  * @example
@@ -267,6 +287,25 @@ declare const SecurityConfigSchema: z.ZodObject<{
  * ```
  */
 type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
+/**
+ * 登录时段与地址策略；空地址/时段列表不限制对应维度。周一为1，周日为7。
+ * @example
+ * ```ts
+ * import { LoginAccessConfigSchema } from '@h-ai/iam'
+ * const policy = LoginAccessConfigSchema.parse({ enabled: true, allowIps: ['192.0.2.0/24'], timezone: 'Asia/Shanghai' })
+ * ```
+ */
+declare const LoginAccessConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+    denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+    timezone: z.ZodDefault<z.ZodString>;
+    windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        days: z.ZodArray<z.ZodNumber>;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 /**
  * 协议展示配置
  * @example
@@ -340,8 +379,26 @@ type AuthUiConfig = z.infer<typeof AuthUiConfigSchema>;
  */
 declare const SessionConfigSchema: z.ZodObject<{
     maxAge: z.ZodDefault<z.ZodNumber>;
+    endOnPageHide: z.ZodDefault<z.ZodBoolean>;
     sliding: z.ZodDefault<z.ZodBoolean>;
     singleDevice: z.ZodDefault<z.ZodBoolean>;
+    singleDeviceMode: z.ZodDefault<z.ZodEnum<{
+        replace: "replace";
+        reject: "reject";
+    }>>;
+    maxSessions: z.ZodDefault<z.ZodNumber>;
+    terminalLimits: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        web: "web";
+        app: "app";
+        desktop: "desktop";
+        api: "api";
+    }> & z.core.$partial, z.ZodNumber>>;
+    terminalLimitMode: z.ZodDefault<z.ZodEnum<{
+        replace: "replace";
+        reject: "reject";
+    }>>;
+    idleTimeout: z.ZodDefault<z.ZodNumber>;
+    absoluteTimeout: z.ZodDefault<z.ZodNumber>;
     refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /**
@@ -378,6 +435,18 @@ declare const RbacConfigSchema: z.ZodObject<{
  * ```
  */
 type RbacConfig = z.infer<typeof RbacConfigSchema>;
+/**
+ * 可选账号闲置扫描；0天关闭自动休眠，不影响明确设置的账号状态与到期时间。
+ * @example
+ * ```ts
+ * import { AccountConfigSchema } from '@h-ai/iam'
+ * const config = AccountConfigSchema.parse({ dormantAfterDays: 90, scanIntervalSeconds: 3600 })
+ * ```
+ */
+declare const AccountConfigSchema: z.ZodObject<{
+    dormantAfterDays: z.ZodDefault<z.ZodNumber>;
+    scanIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * IAM 统一配置 Schema
  * @example
@@ -390,6 +459,29 @@ type RbacConfig = z.infer<typeof RbacConfigSchema>;
  * ```
  */
 declare const IamConfigSchema: z.ZodObject<{
+    initialCredentials: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    reauthentication: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        ttlSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    loginAccess: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        timezone: z.ZodDefault<z.ZodString>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            days: z.ZodArray<z.ZodNumber>;
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    accounts: z.ZodOptional<z.ZodObject<{
+        dormantAfterDays: z.ZodDefault<z.ZodNumber>;
+        scanIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     ui: z.ZodOptional<z.ZodObject<{
         variant: z.ZodDefault<z.ZodEnum<{
             card: "card";
@@ -409,7 +501,10 @@ declare const IamConfigSchema: z.ZodObject<{
         requireLowercase: z.ZodDefault<z.ZodBoolean>;
         requireNumber: z.ZodDefault<z.ZodBoolean>;
         requireSpecialChar: z.ZodDefault<z.ZodBoolean>;
+        minCharacterClasses: z.ZodDefault<z.ZodNumber>;
         expirationDays: z.ZodDefault<z.ZodNumber>;
+        preventSamePassword: z.ZodDefault<z.ZodBoolean>;
+        requireInitialChange: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     otp: z.ZodOptional<z.ZodObject<{
         email: z.ZodDefault<z.ZodBoolean>;
@@ -464,14 +559,40 @@ declare const IamConfigSchema: z.ZodObject<{
         showOnRegister: z.ZodDefault<z.ZodBoolean>;
         showOnLogin: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    captcha: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        ttlSeconds: z.ZodDefault<z.ZodNumber>;
+        cost: z.ZodDefault<z.ZodNumber>;
+        maxCounter: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     security: z.ZodDefault<z.ZodObject<{
+        lockoutEnabled: z.ZodDefault<z.ZodBoolean>;
+        failureWindow: z.ZodDefault<z.ZodNumber>;
         maxLoginAttempts: z.ZodDefault<z.ZodNumber>;
         lockoutDuration: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     session: z.ZodOptional<z.ZodObject<{
         maxAge: z.ZodDefault<z.ZodNumber>;
+        endOnPageHide: z.ZodDefault<z.ZodBoolean>;
         sliding: z.ZodDefault<z.ZodBoolean>;
         singleDevice: z.ZodDefault<z.ZodBoolean>;
+        singleDeviceMode: z.ZodDefault<z.ZodEnum<{
+            replace: "replace";
+            reject: "reject";
+        }>>;
+        maxSessions: z.ZodDefault<z.ZodNumber>;
+        terminalLimits: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            web: "web";
+            app: "app";
+            desktop: "desktop";
+            api: "api";
+        }> & z.core.$partial, z.ZodNumber>>;
+        terminalLimitMode: z.ZodDefault<z.ZodEnum<{
+            replace: "replace";
+            reject: "reject";
+        }>>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        absoluteTimeout: z.ZodDefault<z.ZodNumber>;
         refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     rbac: z.ZodDefault<z.ZodObject<{
@@ -717,6 +838,8 @@ interface PermissionQueryOptions extends PaginationOptionsInput {
  * ```
  */
 interface Permission {
+    /** 此资源权限要求二次认证的操作ID；与文件清单取并集，空或null表示不追加。 */
+    sensitiveOperations?: string[] | null;
     /** 权限 ID */
     id: string;
     /** 权限代码（如 users:read, posts:write） */
@@ -777,6 +900,10 @@ interface Role {
  * ```
  */
 interface AuthzOperations {
+    /** 实时读取RBAC中配置的敏感操作；RBAC关闭时为空，读取失败须拒绝受保护操作。 */
+    getSensitiveOperations: () => Promise<HaiResult<string[]>>;
+    /** 设置资源权限的敏感操作清单；空数组清除数据库追加规则，不清除文件中的规则。 */
+    setPermissionSensitiveOperations: (permissionId: string, operations: string[]) => Promise<HaiResult<void>>;
     /** 查询当前角色与权限代码，一次读取角色并批量聚合权限，不依赖会话缓存。 */
     getUserAuthorization: (userId: string) => Promise<HaiResult<Pick<Session, 'roles' | 'permissions'>>>;
     /**
@@ -1050,6 +1177,16 @@ interface User {
     avatarUrl?: string;
     /** 是否启用 */
     enabled: boolean;
+    /** 账号类型；未设置时为长期账号。 */
+    accountType?: 'permanent' | 'temporary';
+    /** 账号生命周期；与管理员 enabled 开关共同决定可用性。 */
+    accountStatus?: 'active' | 'dormant' | 'closed';
+    /** 临时账号到期时间；长期账号可为 null，临时账号必须设置。 */
+    accountExpiresAt?: Date | null;
+    /** 最近成功登录时间，失败尝试不更新。 */
+    lastLoginAt?: Date | null;
+    /** 初始凭据尚未更换；此时不能签发或使用普通业务会话。 */
+    mustChangePassword?: boolean;
     /** 是否邮箱验证 */
     emailVerified?: boolean;
     /** 是否手机验证 */
@@ -1113,6 +1250,8 @@ interface StoredUser extends User {
     passwordUpdatedAt?: Date;
     /** 登录失败次数 */
     loginFailedCount?: number;
+    /** 当前固定失败计数窗口的起点。 */
+    firstLoginFailedAt?: Date;
     /** 最后登录失败时间 */
     lastLoginFailedAt?: Date;
     /** 锁定截止时间 */
@@ -1127,6 +1266,14 @@ interface StoredUser extends User {
  * ```
  */
 interface RegisterOptions {
+    /** 可选交互挑战证明；管理端 createUser/inviteUser 不使用。 */
+    captcha?: string;
+    /** 服务端管理入口可指定临时账号；公开注册接口不应允许修改生命周期字段。 */
+    accountType?: 'permanent' | 'temporary';
+    /** 管理入口指定初始状态；公开注册 Schema 不接受此字段。 */
+    accountStatus?: 'active' | 'dormant' | 'closed';
+    /** 临时账号的到期时间。 */
+    accountExpiresAt?: Date;
     /** 用户名 */
     username: string;
     /** 邮箱 */
@@ -1199,6 +1346,14 @@ interface UpdateCurrentUserInput {
  * ```
  */
 interface UserOperations {
+    /**
+     * 创建独立随机初始凭据并发送短期单次邀请；不返回或通知原始初始密码。
+     * initialCredentials.enabled、passwordReset 与通知通道必须就绪；接收人使用现有重置页面设密。
+     * 投递未知时保留已创建账号并返回失败；核对后可通过重置通知流程恢复。
+     * @param options - 可信管理端输入，必须包含通知通道对应的邮箱/手机号。
+     * @returns 创建结果或失败；不能把通知结果未知当作未创建账号。
+     */
+    inviteUser: (options: Omit<RegisterOptions, 'password'>) => Promise<HaiResult<RegisterResult>>;
     /** 批量查询最多 1000 个用户 ID，去重并保持输入顺序，忽略不存在的 ID；可批量包含角色。 */
     getUsers: (userIds: readonly string[], options?: {
         include?: ('roles')[];
@@ -1253,6 +1408,17 @@ interface UserOperations {
      * @returns 成功返回分页用户列表
      */
     listUsers: (options?: ListUsersOptions) => Promise<HaiResult<PaginatedResult<User>>>;
+    /**
+     * 依据 accounts.dormantAfterDays 原子休眠长期未登录的账号，返回数量；0天时不执行。
+     * IAM 开启自动扫描时定时调用；外露管理接口须自行验证管理员权限。
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * const scanned = await iam.user.scanInactiveAccounts()
+     * if (!scanned.success) throw new Error(scanned.error.message)
+     * ```
+     */
+    scanInactiveAccounts: () => Promise<HaiResult<number>>;
     /**
      * 更新用户信息
      *
@@ -1282,6 +1448,22 @@ interface UserOperations {
      * @returns 成功返回 ok；用户不存在返回 USER_NOT_FOUND，密码不合规返回 PASSWORD_POLICY_VIOLATION
      */
     adminResetPassword: (userId: string, newPassword: string) => Promise<HaiResult<void>>;
+    /**
+     * 使用原凭据完成首次或过期改密，不需要先获得普通会话。
+     * 仍执行账号状态、旧密码校验、失败锁定及新密码策略；成功后需重新登录。
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * const changed = await iam.user.renewPassword({ identifier: 'alice', password: 'Temporary123!', newPassword: 'ChosenPassword456!' })
+     * if (!changed.success) throw new Error(changed.error.message)
+     * ```
+     */
+    renewPassword: (input: {
+        identifier: string;
+        password: string;
+        newPassword: string;
+        captcha?: string;
+    }) => Promise<HaiResult<void>>;
     /**
      * 修改密码
      *
@@ -1320,7 +1502,9 @@ interface UserOperations {
      *   requested.error.code // 投递未知不能当作成功或由调用端擅自重发通知。
      * ```
      */
-    requestPasswordReset: (identifier: string) => Promise<HaiResult<void>>;
+    requestPasswordReset: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<void>>;
     /**
      * 确认密码重置
      *
@@ -1423,6 +1607,8 @@ interface AuthResult {
  * ```
  */
 interface Session {
+    /** 登录时固定的终端分组；旧记录未设置时归为 web，刷新不能切换分组。 */
+    terminalType?: 'web' | 'app' | 'desktop' | 'api';
     /** 会话内容版本；显式更新产生新版本，内部滑动续期保留版本。 */
     version: string;
     /** 认证快照绑定的持久凭据代；改密后的旧会话即使缓存清理失败也拒绝。 */
@@ -1449,7 +1635,9 @@ interface Session {
     accessToken: string;
     /** 创建时间 */
     createdAt: Date;
-    /** 最后活动时间 */
+    /** 首次签发时间；刷新保留，用于绝对期限。旧记录未设置时以 createdAt 为准。 */
+    startedAt?: Date;
+    /** 最后活动时间；启用闲置策略时，自动 refresh 不延长此值。 */
     lastActiveAt: Date;
     /** 过期时间 */
     expiresAt: Date;
@@ -1481,6 +1669,8 @@ type SessionData = Record<string, unknown> & {
  * ```
  */
 interface CreateSessionOptions {
+    /** 可信宿主提供的终端分组；会话签发后不可通过 update/refresh 改变。 */
+    terminalType?: 'web' | 'app' | 'desktop' | 'api';
     /** 策略已验证的凭据代；创建前须与当前数据库核对，省略时仅供可信服务端按当前用户签发。 */
     expectedCredentialVersion?: string;
     /** 服务端已验证的 API Key 绑定；不得来自未验证客户端输入。 */
@@ -1638,6 +1828,145 @@ interface SessionFieldUpdates {
     permissions?: string[];
 }
 
+/**
+ * @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>>;
+}
+
 /**
  * @h-ai/iam — 认证类型定义
  *
@@ -1645,6 +1974,44 @@ interface SessionFieldUpdates {
  * @module iam-authn-types
  */
 
+/**
+ * 交互鉴别用途；同一挑战不能用于另一入口，API Key 机器鉴别不使用它。
+ * @example
+ * ```ts
+ * import type { CaptchaOperation } from '@h-ai/iam'
+ * const operation: CaptchaOperation = 'login'
+ * ```
+ */
+type CaptchaOperation = 'login' | 'register' | 'sendOtp' | 'passwordReset' | 'renewPassword';
+/**
+ * 可公开的 ALTCHA 挑战；签名秘密仅存共享缓存，不包含在返回值中。
+ * @example
+ * ```ts
+ * import { iam, type IamCaptchaChallenge } from '@h-ai/iam'
+ * const result = await iam.auth.createCaptcha({ operation: 'login' })
+ * if (result.success) { const challenge: IamCaptchaChallenge = result.data; void challenge.id }
+ * ```
+ */
+interface IamCaptchaChallenge {
+    id: string;
+    challenge: Challenge;
+}
+/**
+ * 由可信 HTTP 宿主提供的登录元数据，独立于客户端凭据输入。
+ * @example
+ * ```ts
+ * import type { AuthRequestContext } from '@h-ai/iam'
+ * const context: AuthRequestContext = { ip: '192.0.2.10', requestId: 'request-1' }
+ * ```
+ */
+interface AuthRequestContext {
+    /** 宿主识别的接入终端分组；不是物理设备证明，省略时普通登录归为 web。 */
+    terminalType?: 'web' | 'app' | 'desktop' | 'api';
+    /** socket/平台或受信代理解析后的地址；不能直接复制 X-Forwarded-For。 */
+    ip?: string;
+    userAgent?: string;
+    requestId?: string;
+}
 /**
  * 用户凭证（用于密码登录）
  * @example
@@ -1654,6 +2021,9 @@ interface SessionFieldUpdates {
  * ```
  */
 interface PasswordCredentials {
+    /** 原地恢复会话时限定原主体；鉴别成功但不是此用户时也不签发新会话。 */
+    expectedUserId?: string;
+    captcha?: string;
     /** 用户名/邮箱/手机号 */
     identifier: string;
     /** 密码 */
@@ -1668,6 +2038,9 @@ interface PasswordCredentials {
  * ```
  */
 interface OtpCredentials {
+    /** 会话恢复限定原主体，不能以其他账号的有效验证码恢复原业务动作。 */
+    expectedUserId?: string;
+    captcha?: string;
     /** 邮箱/手机号 */
     identifier: string;
     /** 验证码 */
@@ -1682,6 +2055,9 @@ interface OtpCredentials {
  * ```
  */
 interface LdapCredentials {
+    /** 会话恢复限定原主体；其他账号鉴别成功也不签发恢复会话。 */
+    expectedUserId?: string;
+    captcha?: string;
     /** 用户名 */
     username: string;
     /** 密码 */
@@ -1781,29 +2157,54 @@ interface AuthStrategy {
  * ```
  */
 interface AuthnOperations {
+    /** 生成短期单用、自托管挑战；启用后各交互入口在服务端校验解答。 */
+    createCaptcha: (input: {
+        operation: CaptchaOperation;
+    }) => Promise<HaiResult<IamCaptchaChallenge>>;
+    /**
+     * 验证当前会话和原密码，为已配置的敏感操作签发短期单次证明。
+     * 不创建新会话，不替代操作本身的权限/资源检查。
+     * @param accessToken - 当前会话令牌。
+     * @param password - 原密码；失败计数与登录共用。
+     * @param operation - 配置中选定的操作 ID。
+     * @returns 绑定用户、会话与操作的单次票据，或鉴别失败。
+     */
+    reauthenticate: (accessToken: string, password: string, operation: string) => Promise<HaiResult<IssuedTicket>>;
+    /**
+     * 操作入口完成权限检查后调用；关闭策略/未选操作仅验证当前会话。
+     * 选定操作原子消费证明；不能跨会话、跨操作或重复使用。
+     * @param accessToken - 当前会话令牌。
+     * @param operation - 服务端确定的操作 ID，不能由客户端选择要执行的守卫。
+     * @param ticket - reauthenticate 签发的短期证明。
+     * @returns 允许继续时成功；拒绝或基础设施失败时返回错误。
+     */
+    checkSensitiveOperation: (accessToken: string, operation: string, ticket?: string) => Promise<HaiResult<void>>;
     /**
      * 登录（使用密码）
      *
      * 检查登录方式启用 → 密码策略认证 → 创建会话 → 返回令牌。
      *
      * @param credentials - 密码凭证（identifier + password）
+     * @param context - 宿主提供的可信登录元数据，不从凭据输入复制 IP。
      * @returns 成功返回 AuthResult（用户信息、令牌、协议展示）；失败返回错误
      */
-    login: (credentials: PasswordCredentials) => Promise<HaiResult<AuthResult>>;
+    login: (credentials: PasswordCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
     /**
      * 使用验证码登录
      *
      * @param credentials - OTP 凭证（identifier + code）
+     * @param context - 宿主提供的可信登录元数据，不从凭据输入复制 IP。
      * @returns 成功返回 AuthResult；验证码无效/过期返回 OTP_INVALID
      */
-    loginWithOtp: (credentials: OtpCredentials) => Promise<HaiResult<AuthResult>>;
+    loginWithOtp: (credentials: OtpCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
     /**
      * 使用 LDAP 登录
      *
      * @param credentials - LDAP 凭证（username + password）
+     * @param context - 宿主提供的可信登录元数据，不从凭据输入复制 IP。
      * @returns 成功返回 AuthResult（自动同步本地用户）；失败返回错误
      */
-    loginWithLdap: (credentials: LdapCredentials) => Promise<HaiResult<AuthResult>>;
+    loginWithLdap: (credentials: LdapCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
     /**
      * 使用 API Key 登录
      *
@@ -1811,9 +2212,10 @@ interface AuthnOperations {
      * 空 scopes 无操作权限；显式 * 也不超出主体权限。受限 key 通过 permission 授权，不保留角色入口。
      *
      * @param credentials - API Key 凭证
+     * @param context - 宿主提供的可信登录元数据，不从凭据输入复制 IP。
      * @returns 成功返回 AuthResult；API Key 无效/过期/禁用返回对应错误
      */
-    loginWithApiKey: (credentials: ApiKeyCredentials) => Promise<HaiResult<AuthResult>>;
+    loginWithApiKey: (credentials: ApiKeyCredentials, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
     /**
      * 登出
      *
@@ -1840,7 +2242,9 @@ interface AuthnOperations {
      * @param identifier - 用户标识（邮箱/手机号）
      * @returns 成功返回验证码过期时间；频率限制返回 OTP_RESEND_TOO_FAST
      */
-    sendOtp: (identifier: string) => Promise<HaiResult<{
+    sendOtp: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<{
         expiresAt: Date;
     }>>;
     /**
@@ -1852,7 +2256,7 @@ interface AuthnOperations {
      * @param options - 注册选项（用户名、密码、邮箱等）
      * @returns 成功返回 AuthResult（用户信息、令牌、协议展示）；失败返回对应错误码
      */
-    registerAndLogin: (options: RegisterOptions) => Promise<HaiResult<AuthResult>>;
+    registerAndLogin: (options: RegisterOptions, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
 }
 
 /**
@@ -1938,6 +2342,10 @@ type LdapClientFactory = (config: LdapConfig) => Promise<HaiResult<LdapClient>>;
  * ```
  */
 interface IamPublicConfig {
+    /** 只公开是否需要交互挑战，不公开秘密或缓存状态。 */
+    captcha: {
+        enabled: boolean;
+    };
     /** 页面显示密码策略，不包含密码哈希或账户信息。 */
     password: ReturnType<typeof PasswordConfigSchema.parse>;
     /** 自助注册开关；管理端创建账户仍需要独立授权。 */
@@ -1969,146 +2377,17 @@ interface IamPublicConfig {
     /** 默认 access 有效时长，单位秒；真实认证期限由服务端会话状态决定。 */
     session: {
         maxAge: number;
+        endOnPageHide: boolean;
+    };
+    /** 仅公开操作清单，便于界面在选定操作前请求再鉴别。 */
+    reauthentication: {
+        enabled: boolean;
+        operations: string[];
+    };
+    /** 邀请入口同时要求开关、密码重置与通知通道就绪。 */
+    initialCredentials: {
+        enabled: boolean;
     };
-}
-
-/**
- * @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>>;
 }
 
 /**
@@ -2147,6 +2426,15 @@ declare const HaiIamError: {
     readonly OTP_EXPIRED: _h_ai_core.HaiErrorDef;
     readonly SECURITY_BUSY: _h_ai_core.HaiErrorDef;
     readonly PASSWORD_RESET_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly PASSWORD_CHANGE_REQUIRED: _h_ai_core.HaiErrorDef;
+    readonly LOGIN_ACCESS_DENIED: _h_ai_core.HaiErrorDef;
+    readonly REAUTHENTICATION_REQUIRED: _h_ai_core.HaiErrorDef;
+    readonly INVITATION_DELIVERY_UNKNOWN: _h_ai_core.HaiErrorDef;
+    readonly INVITATION_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly CAPTCHA_REQUIRED: _h_ai_core.HaiErrorDef;
+    readonly CAPTCHA_INVALID: _h_ai_core.HaiErrorDef;
+    readonly CAPTCHA_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly CAPTCHA_UNAVAILABLE: _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;
@@ -2154,6 +2442,7 @@ declare const HaiIamError: {
     readonly TOKEN_EXPIRED: _h_ai_core.HaiErrorDef;
     readonly TOKEN_INVALID: _h_ai_core.HaiErrorDef;
     readonly TOKEN_REFRESH_FAILED: _h_ai_core.HaiErrorDef;
+    readonly SESSION_LIMIT_EXCEEDED: _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;
@@ -2297,8 +2586,19 @@ interface IamFunctions {
     close: () => Promise<void>;
     /** 当前脱敏后的配置快照（未初始化时为 null） */
     readonly config: IamConfig | null;
-    /** 安全且反映实际可用能力的认证页面配置。 */
+    /** 安全的文件配置快照；含数据库敏感规则的有效配置使用 getPublicConfig()。 */
     readonly publicConfig: IamPublicConfig | null;
+    /**
+     * 读取包含文件与当前RBAC数据库敏感操作并集的公开配置；数据库读取失败返回失败。
+     * @returns 独立公开快照；未初始化或启用策略时数据库故障返回 HaiResult 失败。
+     * @example
+     * ```ts
+     * import { iam } from '@h-ai/iam'
+     * const config = await iam.getPublicConfig()
+     * if (config.success) config.data.reauthentication.operations
+     * ```
+     */
+    getPublicConfig: () => Promise<HaiResult<IamPublicConfig>>;
     /** 是否已初始化 */
     readonly isInitialized: boolean;
     /** 注册功能是否启用（未初始化或未配置时默认启用） */
@@ -2317,4 +2617,4 @@ interface IamFunctions {
     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 };
+export { AccountConfigSchema, type AgreementConfig, AgreementConfigSchema, type AgreementDisplay, type ApiKey, type ApiKeyConfig, ApiKeyConfigSchema, type ApiKeyCredentials, type ApiKeyOperations, type ApiKeySortDirection, type ApiKeySortField, type AuthRequestContext, type AuthResult, type AuthStrategy, type AuthStrategyType, AuthStrategyTypeSchema, type AuthUiConfig, AuthUiConfigSchema, type AuthnOperations, type AuthzOperations, CaptchaConfigSchema, type CaptchaOperation, type ConsumeTicketOptions, type ConsumedTicket, type CreateApiKeyOptions, type CreateApiKeyResult, type CreateSessionOptions, type Credentials, HaiIamError, type IamCaptchaChallenge, 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, LoginAccessConfigSchema, 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 };