@h-ai/iam 0.1.0-alpha.71 → 0.1.0-alpha.73

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,16 @@ 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>;
+    idleTimeout: z.ZodDefault<z.ZodNumber>;
+    absoluteTimeout: z.ZodDefault<z.ZodNumber>;
     refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /**
@@ -378,6 +425,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 +449,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 +491,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 +549,30 @@ 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>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        absoluteTimeout: z.ZodDefault<z.ZodNumber>;
         refreshTokenMaxAge: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     rbac: z.ZodDefault<z.ZodObject<{
@@ -1050,6 +1151,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 +1224,8 @@ interface StoredUser extends User {
     passwordUpdatedAt?: Date;
     /** 登录失败次数 */
     loginFailedCount?: number;
+    /** 当前固定失败计数窗口的起点。 */
+    firstLoginFailedAt?: Date;
     /** 最后登录失败时间 */
     lastLoginFailedAt?: Date;
     /** 锁定截止时间 */
@@ -1127,6 +1240,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 +1320,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 +1382,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 +1422,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 +1476,9 @@ interface UserOperations {
      *   requested.error.code // 投递未知不能当作成功或由调用端擅自重发通知。
      * ```
      */
-    requestPasswordReset: (identifier: string) => Promise<HaiResult<void>>;
+    requestPasswordReset: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<void>>;
     /**
      * 确认密码重置
      *
@@ -1449,7 +1607,9 @@ interface Session {
     accessToken: string;
     /** 创建时间 */
     createdAt: Date;
-    /** 最后活动时间 */
+    /** 首次签发时间；刷新保留，用于绝对期限。旧记录未设置时以 createdAt 为准。 */
+    startedAt?: Date;
+    /** 最后活动时间；启用闲置策略时，自动 refresh 不延长此值。 */
     lastActiveAt: Date;
     /** 过期时间 */
     expiresAt: Date;
@@ -1638,6 +1798,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 +1944,42 @@ 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 {
+    /** socket/平台或受信代理解析后的地址；不能直接复制 X-Forwarded-For。 */
+    ip?: string;
+    userAgent?: string;
+    requestId?: string;
+}
 /**
  * 用户凭证（用于密码登录）
  * @example
@@ -1654,6 +1989,7 @@ interface SessionFieldUpdates {
  * ```
  */
 interface PasswordCredentials {
+    captcha?: string;
     /** 用户名/邮箱/手机号 */
     identifier: string;
     /** 密码 */
@@ -1668,6 +2004,7 @@ interface PasswordCredentials {
  * ```
  */
 interface OtpCredentials {
+    captcha?: string;
     /** 邮箱/手机号 */
     identifier: string;
     /** 验证码 */
@@ -1682,6 +2019,7 @@ interface OtpCredentials {
  * ```
  */
 interface LdapCredentials {
+    captcha?: string;
     /** 用户名 */
     username: string;
     /** 密码 */
@@ -1781,29 +2119,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 +2174,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 +2204,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 +2218,7 @@ interface AuthnOperations {
      * @param options - 注册选项（用户名、密码、邮箱等）
      * @returns 成功返回 AuthResult（用户信息、令牌、协议展示）；失败返回对应错误码
      */
-    registerAndLogin: (options: RegisterOptions) => Promise<HaiResult<AuthResult>>;
+    registerAndLogin: (options: RegisterOptions, context?: AuthRequestContext) => Promise<HaiResult<AuthResult>>;
 }
 
 /**
@@ -1938,6 +2304,10 @@ type LdapClientFactory = (config: LdapConfig) => Promise<HaiResult<LdapClient>>;
  * ```
  */
 interface IamPublicConfig {
+    /** 只公开是否需要交互挑战，不公开秘密或缓存状态。 */
+    captcha: {
+        enabled: boolean;
+    };
     /** 页面显示密码策略，不包含密码哈希或账户信息。 */
     password: ReturnType<typeof PasswordConfigSchema.parse>;
     /** 自助注册开关；管理端创建账户仍需要独立授权。 */
@@ -1969,146 +2339,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 +2388,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 +2404,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;
@@ -2317,4 +2568,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 };