@zucker-framework/auth 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2363 @@
+import { Term, DatabaseAdapter } from '@zucker-framework/core';
+export { Term } from '@zucker-framework/core';
+import * as _nestjs_common from '@nestjs/common';
+import { ExecutionContext, Logger, CanActivate, OnModuleInit, DynamicModule, Type, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import * as _nestjs_passport from '@nestjs/passport';
+import { Reflector, DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { JwtService } from '@nestjs/jwt';
+import { ICache } from '@zucker-framework/cache';
+import * as passport_jwt from 'passport-jwt';
+import { StrategyOptionsWithoutRequest, Strategy } from 'passport-jwt';
+export { DATABASE_ADAPTER } from '@zucker-framework/crud';
+
+/**
+ * Data access control configuration types.
+ */
+/** Data access control type identifier */
+interface DataAccessType {
+    id: string;
+    name: string;
+}
+/** Built-in data access types */
+declare const DefaultDataAccessType: {
+    readonly OWN_CREATED: DataAccessType;
+    readonly DENY_FIELDS: DataAccessType;
+    readonly SCOPE: DataAccessType;
+    readonly DIMENSION_SCOPE: DataAccessType;
+};
+/**
+ * Base data access configuration.
+ * Each config binds to a specific action (query/update/delete/etc.)
+ * and a specific type of access control.
+ */
+interface DataAccessConfig {
+    /** The action this config applies to (e.g. 'query', 'update', 'delete') */
+    action: string;
+    /** Access control type */
+    type: DataAccessType;
+}
+/**
+ * Only allow access to records created by the current user.
+ * The creator field name is configurable (defaults to 'creatorId').
+ */
+interface OwnCreatedDataAccessConfig extends DataAccessConfig {
+    type: typeof DefaultDataAccessType.OWN_CREATED;
+    /** The field that stores the creator user ID (default: 'creatorId') */
+    creatorField?: string;
+}
+/**
+ * Field-level access control: deny access to specific fields.
+ */
+interface FieldFilterDataAccessConfig extends DataAccessConfig {
+    type: typeof DefaultDataAccessType.DENY_FIELDS;
+    /** Fields that should be denied/filtered */
+    fields: string[];
+}
+/**
+ * Scope-based row-level access control.
+ * Injects WHERE conditions based on scope type and values.
+ */
+interface ScopeDataAccessConfig extends DataAccessConfig {
+    type: typeof DefaultDataAccessType.SCOPE;
+    /** Scope type identifier (e.g. 'org', 'department') */
+    scopeType: string;
+    /** Scope values to filter by */
+    scope: unknown[];
+}
+/**
+ * Dimension-based row-level access control.
+ * Uses the dimension system to filter rows based on user's dimension membership.
+ */
+interface DimensionDataAccessConfig extends DataAccessConfig {
+    type: typeof DefaultDataAccessType.DIMENSION_SCOPE;
+    /** Dimension type / scopeType  */
+    dimensionType: string;
+    /** The field on the resource that holds the dimension value */
+    dimensionField?: string;
+    /** Whether to include child dimensions in scope  */
+    children?: boolean;
+}
+/** Helper to create OwnCreated config */
+declare function ownCreatedConfig(action: string, creatorField?: string): OwnCreatedDataAccessConfig;
+/** Helper to create FieldFilter config */
+declare function fieldFilterConfig(action: string, fields: string[]): FieldFilterDataAccessConfig;
+/** Helper to create Scope config */
+declare function scopeConfig(action: string, scopeType: string, scope: unknown[]): ScopeDataAccessConfig;
+/** Helper to create Dimension config */
+declare function dimensionConfig(action: string, dimensionType: string, dimensionField?: string): DimensionDataAccessConfig;
+
+/**
+ * Standard permission action constants.
+ */
+declare const PermissionActions: {
+    readonly QUERY: "query";
+    readonly GET: "get";
+    readonly ADD: "add";
+    readonly SAVE: "save";
+    readonly UPDATE: "update";
+    readonly DELETE: "delete";
+    readonly IMPORT: "import";
+    readonly EXPORT: "export";
+    readonly DISABLE: "disable";
+    readonly ENABLE: "enable";
+};
+interface Permission {
+    id: string;
+    name: string;
+    actions: string[];
+    describe?: string;
+    /** Data-level access control configurations */
+    dataAccesses: DataAccessConfig[];
+    /** Extension options map  */
+    options?: Record<string, unknown>;
+    /** Find fields that should be denied for the given action */
+    findDenyFields(action: string): string[];
+    /** Find a specific DataAccessConfig by action and type */
+    findDataAccess<T extends DataAccessConfig>(action: string, type: string): T | undefined;
+    /** Get all DataAccessConfigs for a given action */
+    getDataAccesses(action: string): DataAccessConfig[];
+    /** Find a FieldFilterDataAccessConfig for the given action */
+    findFieldFilter(action: string): FieldFilterDataAccessConfig | undefined;
+    /** Find scope values for the given action, type and scopeType */
+    findScope(action: string, type: string, scopeType: string): unknown[];
+    /** Deep copy this permission */
+    copy(actionFilter?: (action: string) => boolean, dataAccessFilter?: (config: DataAccessConfig) => boolean): Permission;
+}
+/**
+ * Simple Permission implementation with data access helpers.
+ */
+declare class SimplePermission implements Permission {
+    id: string;
+    name: string;
+    actions: string[];
+    describe?: string;
+    dataAccesses: DataAccessConfig[];
+    options?: Record<string, unknown>;
+    constructor(data: {
+        id: string;
+        name: string;
+        actions: string[];
+        describe?: string;
+        dataAccesses?: DataAccessConfig[];
+        options?: Record<string, unknown>;
+    });
+    /** Check if a config's action matches the requested action (supports '*' wildcard) */
+    private actionMatches;
+    findDenyFields(action: string): string[];
+    findDataAccess<T extends DataAccessConfig>(action: string, type: string): T | undefined;
+    getDataAccesses(action: string): DataAccessConfig[];
+    findFieldFilter(action: string): FieldFilterDataAccessConfig | undefined;
+    findScope(action: string, type: string, scopeType: string): unknown[];
+    copy(actionFilter?: (action: string) => boolean, dataAccessFilter?: (config: DataAccessConfig) => boolean): SimplePermission;
+}
+interface Role {
+    id: string;
+    name: string;
+    permissions: Permission[];
+    parentId?: string;
+}
+interface RoleTreeNode extends Role {
+    children: RoleTreeNode[];
+}
+interface DimensionType {
+    id: string;
+    name: string;
+    isSameType(type: DimensionType | string): boolean;
+}
+interface Dimension {
+    id: string;
+    name: string;
+    type: DimensionType;
+    options?: Record<string, unknown>;
+}
+interface DimensionProvider {
+    /** 维度类型标识 */
+    readonly dimensionType: string;
+    getAllTypes(): Promise<DimensionType[]>;
+    getDimensionsByUserId(userId: string): Promise<Dimension[]>;
+    getDimensionById(type: DimensionType, id: string): Promise<Dimension | null>;
+    getUserIdsByDimensionId(dimensionId: string): Promise<string[]>;
+    /** 获取用户在该维度下的值列表 */
+    getDimensionValues(userId: string): Promise<string[]>;
+    /** 级联展开维度树（返回 value 及其所有子节点值） */
+    expandDimensionTree(value: string): Promise<string[]>;
+}
+declare const DIMENSION_PROVIDERS: unique symbol;
+declare enum TokenState {
+    NORMAL = "normal",
+    EXPIRED = "expired",
+    LOCK = "lock",
+    DENY = "deny",
+    REVOKED = "revoked",
+    OFFLINE = "offline"
+}
+interface TokenInfo {
+    token: string;
+    userId: string;
+    state: TokenState;
+    /** Token type (e.g. 'default', 'api', 'mobile'). */
+    type: string;
+    signInTime: Date;
+    lastRequestTime: Date;
+    /** Number of requests made with this token. */
+    requestTimes: number;
+    maxInactiveInterval?: number;
+}
+/**
+ * Allopatric (concurrent) login mode.
+ */
+declare enum AllopatricLoginMode {
+    /** Deny login if user already logged in elsewhere */
+    DENY = "deny",
+    /** Allow concurrent login (default) */
+    ALLOW = "allow",
+    /** Kick existing sessions offline when new login occurs */
+    OFFLINE_OTHER = "offlineOther"
+}
+interface AuthUser {
+    id: string;
+    username: string;
+    [key: string]: unknown;
+}
+interface Authentication {
+    getUser(): AuthUser;
+    getPermissions(): Permission[];
+    getDimensions(type?: string): Dimension[];
+    /** Get a specific permission by id  */
+    getPermission(id: string): Permission | undefined;
+    /** Get a specific dimension by type and id */
+    getDimension(type: string, id: string): Dimension | undefined;
+    hasPermission(permissionId: string, ...actions: string[]): boolean;
+    hasDimension(type: string, ...ids: string[]): boolean;
+    getAttributes(): Record<string, unknown>;
+    getAttribute<T>(key: string): T | undefined;
+    setAttribute(key: string, value: unknown): void;
+    /** Merge another Authentication into this one */
+    merge(other: Authentication): Authentication;
+    /**
+     * Copy with filters.
+     * @param permissionFilter - (permission, action) => whether to keep the action
+     * @param dimensionFilter - (dimension) => whether to keep the dimension
+     */
+    copy(permissionFilter?: (permission: Permission, action: string) => boolean, dimensionFilter?: (dimension: Dimension) => boolean): Authentication;
+}
+interface ZuckerAuthModuleOptions {
+    jwtSecret?: string;
+    /**
+     * Register the framework's generic authorization, menu, and third-party
+     * account controllers. Defaults to true for backwards compatibility.
+     *
+     * Products that provide their own authentication surface should disable
+     * these controllers to avoid exposing unused routes.
+     */
+    registerControllers?: boolean;
+    dimensionProviders?: Array<new (...args: unknown[]) => DimensionProvider>;
+    /** 缓存 provider token（用于 Token 黑名单），指向 ICache 的注入 token */
+    cacheProvider?: string | symbol;
+    /** 最大并发会话数，0 表示不限制 */
+    maxActiveSessions?: number;
+}
+/**
+ * A simple DimensionType implementation that can be used as a constructor.
+ */
+declare class SimpleDimensionType implements DimensionType {
+    readonly id: string;
+    readonly name: string;
+    constructor(id: string, name: string);
+    isSameType(type: DimensionType | string): boolean;
+}
+/**
+ * Built-in dimension types.
+ */
+declare const DefaultDimensionType: {
+    readonly user: SimpleDimensionType;
+    readonly role: SimpleDimensionType;
+};
+/**
+ * Simple Dimension implementation.
+ */
+declare class SimpleDimension implements Dimension {
+    id: string;
+    name: string;
+    type: DimensionType;
+    options?: Record<string, unknown>;
+    constructor(id: string, name: string, type: DimensionType, options?: Record<string, unknown>);
+    static of(id: string, name: string, type: DimensionType, options?: Record<string, unknown>): SimpleDimension;
+}
+/**
+ * Predicate function for testing Authentication.
+ */
+type AuthenticationPredicate = (auth: Authentication) => boolean;
+/**
+ * Factory methods for creating AuthenticationPredicates.
+ */
+declare const AuthenticationPredicates: {
+    /** Check if authentication has the given permission string (e.g. "user:query") */
+    readonly has: (permissionString: string) => AuthenticationPredicate;
+    /** Check dimension membership */
+    readonly dimension: (dimensionType: string, ...ids: string[]) => AuthenticationPredicate;
+    /** Check specific permission with actions */
+    readonly permission: (permissionId: string, ...actions: string[]) => AuthenticationPredicate;
+    /** Combine two predicates with AND */
+    readonly and: (a: AuthenticationPredicate, b: AuthenticationPredicate) => AuthenticationPredicate;
+    /** Combine two predicates with OR */
+    readonly or: (a: AuthenticationPredicate, b: AuthenticationPredicate) => AuthenticationPredicate;
+};
+/**
+ * Parse a permission string like "user:query" or "role:admin" into a predicate.
+ */
+declare function createAuthenticationPredicate(permissionString: string): AuthenticationPredicate;
+/**
+ * User setting read/write permission levels.
+ */
+declare enum UserSettingPermission {
+    NONE = "NONE",
+    R = "R",
+    W = "W",
+    RW = "RW"
+}
+/**
+ * Holds a user setting value with typed accessors.
+ */
+interface SettingValueHolder {
+    asString(): string | undefined;
+    asNumber(): number | undefined;
+    asBoolean(): boolean | undefined;
+    asList<T>(): T[] | undefined;
+    getValue(): unknown;
+    getPermission(): UserSettingPermission;
+}
+/**
+ * Null object for SettingValueHolder.
+ * All accessors return undefined, permission is NONE.
+ */
+declare const NullSettingValueHolder: SettingValueHolder;
+/**
+ * Create a SettingValueHolder from a raw value and permission.
+ */
+declare function createSettingValueHolder(value: unknown, permission?: UserSettingPermission): SettingValueHolder;
+
+/**
+ * Utility helpers for TokenInfo
+ * (isNormal, isExpired, isOffline, isDeny, isLock, checkExpired, validate).
+ */
+declare const TokenInfoUtils: {
+    readonly isNormal: (token: TokenInfo) => boolean;
+    readonly isExpired: (token: TokenInfo) => boolean;
+    readonly isOffline: (token: TokenInfo) => boolean;
+    readonly isDeny: (token: TokenInfo) => boolean;
+    readonly isLock: (token: TokenInfo) => boolean;
+    /** Check if the token has exceeded its maxInactiveInterval. */
+    readonly checkExpired: (token: TokenInfo) => boolean;
+    /** Validate token is in normal state, throw if not. */
+    readonly validate: (token: TokenInfo) => boolean;
+};
+
+interface DataAccessResult {
+    /** Whether access is allowed */
+    allowed: boolean;
+    /** WHERE conditions to inject into queries (AND logic) */
+    filterConditions?: Term[];
+    /** Fields that should be denied/stripped from the result */
+    denyFields?: string[];
+}
+/** Create an allowed result with no extra conditions */
+declare function allowResult(): DataAccessResult;
+/** Create a denied result */
+declare function denyResult(): DataAccessResult;
+/** Create an allowed result with filter conditions */
+declare function filterResult(filterConditions: Term[], denyFields?: string[]): DataAccessResult;
+/**
+ * Merge multiple DataAccessResults with AND logic.
+ * - If any result is denied, the merged result is denied.
+ * - All filterConditions are concatenated.
+ * - All denyFields are merged (union).
+ */
+declare function mergeResults(results: DataAccessResult[]): DataAccessResult;
+
+/**
+ * Context passed to DataAccessHandler for evaluation.
+ */
+interface AuthorizingContext {
+    /** Current authenticated user */
+    authentication: Authentication;
+    /** The permission being checked */
+    permissionId: string;
+    /** The action being performed (query/update/delete/etc.) */
+    action: string;
+    /** Data type / resource being accessed */
+    dataType: string;
+    /** HTTP request object (for accessing params, body, query) */
+    request: {
+        method: string;
+        params: Record<string, string>;
+        query: Record<string, unknown>;
+        body: unknown;
+        path: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Data access handler SPI.
+ * Implementations handle specific DataAccessConfig types.
+ * Registered via NestJS DI and iterated by DataPermissionGuard.
+ */
+interface DataAccessHandler {
+    /**
+     * Whether this handler supports the given config.
+     */
+    isSupport(config: DataAccessConfig): boolean;
+    /**
+     * Evaluate data access for the given config and context.
+     * Returns a result indicating allowed/denied + optional filter conditions.
+     */
+    handle(config: DataAccessConfig, context: AuthorizingContext): Promise<DataAccessResult>;
+}
+declare const DATA_ACCESS_HANDLERS: unique symbol;
+
+/**
+ * Handles OwnCreated data access control.
+ * Restricts access to records created by the current user.
+ * The creator field name is configurable (defaults to 'creatorId').
+ */
+declare class OwnCreatedDataAccessHandler implements DataAccessHandler {
+    private readonly db;
+    private readonly logger;
+    constructor(db: DatabaseAdapter);
+    isSupport(config: DataAccessConfig): boolean;
+    handle(config: DataAccessConfig, context: AuthorizingContext): Promise<DataAccessResult>;
+}
+
+/**
+ * Handles field-level access control.
+ * Returns denyFields list so that the guard or downstream service
+ * can strip these fields from query results or reject mutations on them.
+ */
+declare class FieldFilterDataAccessHandler implements DataAccessHandler {
+    isSupport(config: DataAccessConfig): boolean;
+    handle(config: DataAccessConfig, _context: AuthorizingContext): Promise<DataAccessResult>;
+}
+
+/**
+ * Handles scope-based row-level access control.
+ * Injects WHERE conditions based on scope type and values.
+ * E.g., only allow access to records within certain organizations.
+ */
+declare class ScopeDataAccessHandler implements DataAccessHandler {
+    isSupport(config: DataAccessConfig): boolean;
+    handle(config: DataAccessConfig, _context: AuthorizingContext): Promise<DataAccessResult>;
+}
+
+/**
+ * 维度服务注册中心
+ * 管理多个 DimensionProvider，按 dimensionType 索引
+ */
+declare class DimensionService {
+    private readonly providers;
+    private readonly logger;
+    private readonly providerMap;
+    constructor(providers: DimensionProvider[] | null);
+    /** 注册新的维度 Provider */
+    registerProvider(provider: DimensionProvider): void;
+    /** 获取指定类型的 Provider */
+    getProvider(dimensionType: string): DimensionProvider | undefined;
+    /** 获取所有已注册的 Provider */
+    getAllProviders(): DimensionProvider[];
+    getUserDimensions(userId: string): Promise<Dimension[]>;
+    /** 获取用户在指定维度类型下的值 */
+    getUserDimensionValues(userId: string, dimensionType: string): Promise<string[]>;
+    /** 级联展开维度树 */
+    expandDimensionTree(dimensionType: string, value: string): Promise<string[]>;
+    /** 获取用户在所有维度的完整展开值集合 */
+    getExpandedUserDimensions(userId: string): Promise<Map<string, string[]>>;
+    hasDimension(userId: string, dimensionType: string, dimensionId: string): Promise<boolean>;
+    getAllDimensionTypes(): Promise<DimensionType[]>;
+    getDimensionById(type: DimensionType, id: string): Promise<Dimension | null>;
+    getUserIdsByDimensionId(dimensionId: string): Promise<string[]>;
+    private getActiveProviders;
+}
+
+/**
+ * Handles dimension-based row-level access control.
+ * Uses DimensionService to resolve user dimensions and inject
+ * WHERE conditions or check resource membership.
+ *
+ * Refactored from the original hard-coded logic in DataPermissionGuard.
+ */
+declare class DimensionDataAccessHandler implements DataAccessHandler {
+    private readonly db;
+    private readonly dimensionService?;
+    private readonly logger;
+    constructor(db: DatabaseAdapter, dimensionService?: DimensionService | undefined);
+    isSupport(config: DataAccessConfig): boolean;
+    handle(config: DataAccessConfig, context: AuthorizingContext): Promise<DataAccessResult>;
+}
+
+/**
+ * Authentication supplier interface.
+ * Multiple suppliers can be registered to build a complete Authentication
+ * from different sources (JWT, database, LDAP, etc.).
+ */
+interface AuthenticationSupplier {
+    /** Supplier priority — lower values are applied first */
+    readonly order?: number;
+    /**
+     * Get authentication for the current request context.
+     * Returns null if this supplier cannot provide authentication.
+     */
+    get(context: SupplierContext): Promise<Authentication | null>;
+    /**
+     * Get authentication for a specific user ID.
+     * Used for admin impersonation or background jobs.
+     */
+    getByUserId?(userId: string): Promise<Authentication | null>;
+}
+interface SupplierContext {
+    /** The HTTP request object */
+    request: {
+        headers: Record<string, string | string[] | undefined>;
+        user?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+}
+declare const AUTHENTICATION_SUPPLIERS: unique symbol;
+
+/**
+ * Default implementation of Authentication.
+ * Supports merge() for combining permissions and dimensions from multiple suppliers.
+ */
+declare class DefaultAuthentication implements Authentication {
+    private user;
+    private permissions;
+    private dimensions;
+    private attributes;
+    constructor(data?: {
+        user?: AuthUser;
+        permissions?: Permission[];
+        dimensions?: Dimension[];
+        attributes?: Record<string, unknown>;
+    });
+    getUser(): AuthUser;
+    getPermissions(): Permission[];
+    getDimensions(type?: string | DimensionType): Dimension[];
+    /**
+     * 权限检查
+     *
+     * 权限 id 为 '*' 时允许所有操作；否则需要匹配权限 id，
+     * 并满足全部请求动作或拥有动作通配符 '*'。
+     * 在方法入口捕获权限列表引用，整个检查过程使用同一列表。
+     */
+    hasPermission(permissionId: string, ...actions: string[]): boolean;
+    /**
+     * 维度检查
+     * 先捕获 this.dimensions 到局部变量再操作。
+     */
+    hasDimension(type: string | DimensionType, ...ids: string[]): boolean;
+    getPermission(id: string): Permission | undefined;
+    /**
+     * Get dimension by type and id.
+     * When type is a string, uses case-insensitive comparison.
+     * When type is a DimensionType, uses isSameType.
+     */
+    getDimension(type: string | DimensionType, id: string): Dimension | undefined;
+    getAttributes(): Record<string, unknown>;
+    getAttribute<T>(key: string): T | undefined;
+    setAttribute(key: string, value: unknown): void;
+    setAttributes(attributes: Record<string, unknown>): void;
+    /**
+     * Set the user. Also adds the user as a dimension of type 'user'
+     *
+     * A user with an id is appended without deduplicating existing dimensions.
+     */
+    setUser(user: AuthUser): void;
+    /**
+     * Set user without adding to dimensions list.
+     */
+    setUser0(user: AuthUser): void;
+    setPermissions(permissions: Permission[]): void;
+    /**
+     * Append dimensions to the existing list.
+     */
+    setDimensions(dimensions: Dimension[]): void;
+    /**
+     * Replace all dimensions (for cases where full replacement is needed).
+     */
+    replaceDimensions(dimensions: Dimension[]): void;
+    /**
+     * Factory method for subclasses to override.
+     */
+    protected newInstance(): DefaultAuthentication;
+    /**
+     * Static factory.
+     */
+    static of(): DefaultAuthentication;
+    /**
+     * Copy with filters.
+     */
+    copy(permissionFilter?: (permission: Permission, action: string) => boolean, dimensionFilter?: (dimension: Dimension) => boolean): DefaultAuthentication;
+    /**
+     * Add a single dimension.
+     */
+    addDimension(dimension: Dimension): void;
+    /**
+     * Merge another Authentication into this one.
+     * Merge behavior:
+     * - User: later suppliers override the current user when present
+     * - Permissions: merge by ID, combining actions and dataAccesses; when
+     *   other permission is new, use permission.copy()
+     * - Dimensions: merge by type+id dedup
+     * - Attributes: shallow merge (other wins on conflict)
+     */
+    merge(other: Authentication): DefaultAuthentication;
+}
+/**
+ * Create a DefaultAuthentication from a plain JWT user object (backward compat).
+ */
+declare function fromJwtUser(user: Record<string, unknown>): DefaultAuthentication;
+
+/**
+ * AuthenticationHolder — resolves and caches Authentication per request.
+ *
+ * Aggregates multiple AuthenticationSuppliers (JWT, database, LDAP, etc.)
+ * and merges their results into a single Authentication instance.
+ *
+ * Uses AsyncLocalStorage for request-scoped caching so that
+ * the same request only resolves suppliers once.
+ */
+declare class AuthenticationHolder {
+    private readonly logger;
+    private readonly als;
+    private readonly suppliers;
+    constructor(suppliers: AuthenticationSupplier[] | null);
+    /**
+     * Run a function within an AsyncLocalStorage context.
+     * Call this in middleware or interceptor to enable request-level caching.
+     */
+    runInContext<T>(fn: () => T): T;
+    /**
+     * Resolve the current Authentication from all registered suppliers.
+     * Results are cached per-request via AsyncLocalStorage.
+     */
+    resolve(context: SupplierContext): Promise<Authentication | null>;
+    /**
+     * Resolve Authentication by user ID (for background jobs, impersonation).
+     */
+    resolveByUserId(userId: string): Promise<Authentication | null>;
+    /**
+     * Get the current Authentication from ALS cache without re-resolving.
+     */
+    getCurrent(): Authentication | null;
+}
+
+declare const IS_PUBLIC_KEY = "zucker:auth:isPublic";
+declare const PERMISSIONS_KEY = "zucker:auth:permissions";
+declare const RESOURCE_KEY = "zucker:auth:resource";
+declare const ACTION_KEY = "zucker:auth:action";
+declare const AUTHORIZE_KEY = "zucker:auth:authorize";
+declare const DATA_PERMISSION_KEY = "zucker:auth:dataPermission";
+declare const TWO_FACTOR_KEY = "zucker:auth:twoFactor";
+declare const DIMENSION_KEY = "zucker:auth:dimension";
+
+declare const Public: () => _nestjs_common.CustomDecorator<string>;
+declare const Permissions: (...permissions: string[]) => _nestjs_common.CustomDecorator<string>;
+declare const RequirePermissions: (...permissions: string[]) => _nestjs_common.CustomDecorator<string>;
+interface ResourceOptions {
+    id: string;
+    name: string;
+    description?: string;
+    optionalFields?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+interface ActionOptions {
+    action: string;
+    name: string;
+    description?: string;
+}
+type AuthorizeLogical = 'AND' | 'OR' | 'DEFAULT';
+type AuthorizePhased = 'before' | 'after';
+interface AuthorizeResourceOptions extends ResourceOptions {
+    actions?: ActionOptions[];
+    merge?: boolean;
+    logical?: AuthorizeLogical;
+    phased?: AuthorizePhased;
+    group?: string[];
+}
+declare const Resource: (options: ResourceOptions) => _nestjs_common.CustomDecorator<string>;
+declare const Action: (options: ActionOptions) => _nestjs_common.CustomDecorator<string>;
+declare const QueryAction: (name?: string, description?: string) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Create action.
+ */
+declare const CreateAction: (name?: string, description?: string) => _nestjs_common.CustomDecorator<string>;
+declare const SaveAction: (name?: string, description?: string) => _nestjs_common.CustomDecorator<string>;
+declare const DeleteAction: (name?: string, description?: string) => _nestjs_common.CustomDecorator<string>;
+declare const UpdateAction: (name?: string, description?: string) => _nestjs_common.CustomDecorator<string>;
+declare const ResourceAction: (options: ActionOptions) => _nestjs_common.CustomDecorator<string>;
+declare const CurrentUser: (...dataOrPipes: (string | _nestjs_common.ParameterDecoratorOptions | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+interface DataPermissionOptions {
+    dataType?: string;
+    skipDataPermission?: boolean;
+}
+declare const DataPermission: (options?: DataPermissionOptions | string) => _nestjs_common.CustomDecorator<string>;
+declare const SkipDataPermission: () => _nestjs_common.CustomDecorator<string>;
+interface TwoFactorOptions {
+    /** 操作标识 — 用于区分不同操作的验证规则 */
+    operation: string;
+    /** 验证有效期（毫秒），默认 10 分钟 */
+    timeout?: number;
+    /** 验证器供应商（totp/sms/email），默认 'default' */
+    provider?: string;
+    /** 验证码的 HTTP 参数名，默认 'verifyCode' */
+    parameter?: string;
+    /** 是否忽略/关闭验证，默认 false */
+    ignore?: boolean;
+    /** 验证失败提示消息 */
+    message?: string;
+}
+interface ResolvedAuthorizeOptions {
+    resources: AuthorizeResourceOptions[];
+    dimensions: DimensionOptions[];
+    permissions?: string[];
+    dataPermission?: DataPermissionOptions;
+    ignore: boolean;
+    message: string;
+    merge: boolean;
+    logical: AuthorizeLogical;
+    phased: AuthorizePhased;
+    description: string[];
+}
+declare const TwoFactor: (options: string | TwoFactorOptions) => ClassDecorator & MethodDecorator;
+interface AuthorizeOptions {
+    /** 资源定义 — 用于资源-动作模型 */
+    resource?: ResourceOptions;
+    /** 动作定义 — 用于资源-动作模型 */
+    action?: ActionOptions;
+    /** 多资源定义 */
+    resources?: AuthorizeResourceOptions[];
+    /** 维度定义 */
+    dimension?: DimensionOptions[];
+    /** 字符串权限列表 — 简单模式 */
+    permissions?: string[];
+    /** 数据权限选项 */
+    dataPermission?: DataPermissionOptions;
+    /** 是否忽略（等同 @Public） */
+    ignore?: boolean;
+    /** 验证失败消息 */
+    message?: string;
+    /** 是否合并类上的注解 */
+    merge?: boolean;
+    /** 多个资源/维度时的判断逻辑 */
+    logical?: AuthorizeLogical;
+    /** 验证时机 */
+    phased?: AuthorizePhased;
+    /** 说明文本 */
+    description?: string[];
+}
+/**
+ * @Authorize 组合装饰器
+ *
+ * 将 @Resource, @Action, @Permissions, @DataPermission, @Public
+ * 组合为单个装饰器，简化常用权限声明。
+ *
+ * 支持类级别和方法级别。
+ *
+ * @example
+ * ```ts
+ * @Authorize({ resource: { id: 'user', name: '用户' }, action: { action: 'query', name: '查询' } })
+ * async list() { ... }
+ *
+ * @Authorize({ ignore: true })
+ * async publicEndpoint() { ... }
+ *
+ * @Authorize({ permissions: ['admin:manage'] })
+ * async adminOnly() { ... }
+ * ```
+ */
+declare function Authorize(options: AuthorizeOptions): ClassDecorator & MethodDecorator;
+interface DimensionOptions {
+    type: string;
+    ids: string[];
+    logical?: AuthorizeLogical;
+}
+/**
+ * @DimensionCheck 装饰器
+ *
+ * 通用维度权限检查，支持角色、部门等维度类型。
+ */
+declare const DimensionCheck: (options: DimensionOptions) => ClassDecorator & MethodDecorator;
+/**
+ * @RequiresRoles 装饰器
+ *
+ * 要求用户拥有指定角色之一（OR 逻辑）。
+ */
+interface RequiresRolesOptions {
+    logical?: AuthorizeLogical;
+}
+declare function RequiresRoles(...roles: string[]): ClassDecorator & MethodDecorator;
+declare function RequiresRoles(options: RequiresRolesOptions, ...roles: string[]): ClassDecorator & MethodDecorator;
+
+/** Minimal TopicEventBus interface to avoid hard dependency on @zucker-framework/event */
+interface TopicEventBusLike$5 {
+    publish(topic: string, payload: unknown): Promise<void>;
+}
+declare const TOKEN_CACHE: unique symbol;
+interface TokenServiceOptions {
+    /** 最大并发会话数，0 表示不限制 */
+    maxActiveSessions?: number;
+    /** Token 黑名单 TTL（毫秒），默认 7 天 */
+    blacklistTtlMs?: number;
+    /** 异地登录模式  */
+    allopatricLoginMode?: AllopatricLoginMode;
+}
+declare class TokenService {
+    private readonly cache?;
+    private readonly jwtService?;
+    private readonly topicEventBus?;
+    private readonly logger;
+    /** 内存中的 token 会话映射（兜底存储） */
+    private readonly tokens;
+    private readonly userTokens;
+    private maxActiveSessions;
+    private blacklistTtlMs;
+    private allopatricLoginMode;
+    constructor(cache?: ICache | undefined, jwtService?: JwtService | undefined, topicEventBus?: TopicEventBusLike$5 | undefined);
+    /** 配置选项（在模块初始化时调用） */
+    configure(options: TokenServiceOptions): void;
+    signIn(userId: string, token: string, type?: string, maxInactiveInterval?: number): Promise<TokenInfo>;
+    signOut(token: string): Promise<void>;
+    /** 撤销单个 token，加入黑名单 */
+    revokeToken(token: string): Promise<void>;
+    /** 撤销用户所有 token（强制登出） */
+    revokeUserTokens(userId: string): Promise<void>;
+    /** Token 轮换：旧 token 失效，签发新 token */
+    rotateToken(oldToken: string, payload: Record<string, unknown>): Promise<{
+        token: string;
+        tokenInfo: TokenInfo;
+    } | null>;
+    /** 检查 token 是否在黑名单中 */
+    isBlacklisted(token: string): Promise<boolean>;
+    /**
+     * Get token info, checking for timeout expiration first.
+     *
+     * A normal token expires when its positive maxInactiveInterval is exceeded.
+     * Missing tokens return null; other token states are preserved.
+     */
+    getByToken(token: string): Promise<TokenInfo | null>;
+    getByUserId(userId: string): Promise<TokenInfo[]>;
+    changeState(token: string, state: TokenState): Promise<void>;
+    touch(token: string): Promise<void>;
+    /** Check if a user has any active (normal) sessions. */
+    userIsLoggedIn(userId: string): Promise<boolean>;
+    /** Check if a specific token is logged in (normal state). */
+    tokenIsLoggedIn(token: string): Promise<boolean>;
+    /** Total number of unique logged-in users. */
+    totalUsers(): Promise<number>;
+    /** Get all active tokens. */
+    allLoggedTokens(): Promise<TokenInfo[]>;
+    /** Change state for all tokens of a user. */
+    changeUserState(userId: string, state: TokenState): Promise<void>;
+    /**
+     * Check all tokens for expiration, expire timed-out ones and remove them.
+     *
+     *   Flux.fromIterable(tokenStorage.values())
+     *     .doOnNext(this::checkTimeout)     // marks as expired via changeTokenState
+     *     .filter(UserToken::isExpired)
+     *     .map(UserToken::getToken)
+     *     .flatMap(this::signOutByToken)    // removes and publishes UserTokenRemovedEvent
+     *     .then()
+     */
+    checkExpired(): Promise<void>;
+    signOutByUserId(userId: string): Promise<void>;
+    totalTokens(): Promise<number>;
+    private publishEvent;
+}
+
+declare const JwtAuthGuard_base: _nestjs_passport.Type<_nestjs_passport.IAuthGuard>;
+declare class JwtAuthGuard extends JwtAuthGuard_base {
+    private reflector;
+    private tokenService;
+    private authenticationHolder?;
+    constructor(reflector: Reflector, tokenService: TokenService, authenticationHolder?: AuthenticationHolder | undefined);
+    canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean>;
+    private postValidate;
+}
+
+declare class RoleHierarchyService {
+    private readonly db;
+    private readonly logger;
+    /**
+     * Cached parent-ID lookup table: roleId -> parentId | undefined.
+     * Populated lazily on first hierarchy traversal, cleared on invalidate().
+     * Avoids N+1 DB queries when walking the role tree.
+     */
+    private parentIdMap;
+    constructor(db: DatabaseAdapter);
+    /**
+     * Invalidate the cached role hierarchy.
+     * Call after role CRUD operations that change parentId relationships.
+     */
+    invalidateCache(): void;
+    /**
+     * Load all role parentId mappings in a single query (lazy, cached).
+     */
+    private ensureParentIdMap;
+    /**
+     * 获取角色的所有父角色（递归向上）
+     * Uses cached parent-ID map to avoid N+1 DB queries.
+     */
+    getParentRoles(roleId: string): Promise<string[]>;
+    /**
+     * 获取角色的所有子角色（递归向下）
+     * Uses cached parent-ID map to build child lookup in-memory.
+     */
+    getChildRoles(roleId: string): Promise<string[]>;
+    /**
+     * 获取角色的完整权限集（包括继承自父角色的权限）
+     * 递归展开角色层级，合并所有权限
+     */
+    getRolePermissions(roleId: string): Promise<Permission[]>;
+    /**
+     * 获取角色的所有权限（包括继承自父角色的）
+     * 同 getRolePermissions，保持向后兼容
+     */
+    getExpandedPermissions(roleId: string): Promise<Permission[]>;
+    /**
+     * 获取角色树
+     */
+    getRoleTree(): Promise<RoleTreeNode[]>;
+    /**
+     * 构建角色树
+     */
+    buildRoleTree(): Promise<RoleTreeNode[]>;
+    /**
+     * 获取用户通过角色层级展开后的所有权限 ID
+     */
+    getUserExpandedPermissionIds(userId: string): Promise<string[]>;
+    private loadPermissionsByRoleIds;
+    private loadRolePermissions;
+}
+
+declare class PermissionService {
+    private readonly db;
+    protected readonly logger: Logger;
+    private roleHierarchyService?;
+    private readonly permissionCache;
+    constructor(db: DatabaseAdapter);
+    /** 注入角色层级服务（在模块初始化后调用） */
+    setRoleHierarchyService(service: RoleHierarchyService): void;
+    /**
+     * Invalidate the permission cache for a specific user, or all users.
+     * Call after role/permission changes to ensure fresh data.
+     */
+    invalidatePermissionCache(userId?: string): void;
+    /**
+     * 获取用户的所有权限（包括角色权限和直接权限）
+     * Results are cached for a short TTL to avoid redundant DB queries
+     * when multiple guards check permissions in the same request.
+     */
+    findUserPermissions(userId: string): Promise<string[]>;
+    /**
+     * Internal: load user permissions from database.
+     */
+    private _loadUserPermissions;
+    /**
+     * 检查用户是否拥有所需权限
+     */
+    hasPermission(userId: string, requiredPermissions: string[]): Promise<boolean>;
+    /**
+     * 检查用户对特定数据的权限
+     */
+    hasDataPermission(userId: string, dataType: string, dataId: string, action: string): Promise<boolean>;
+    /**
+     * 检查用户是否拥有指定维度（角色/部门等）
+     *
+     * 支持维度条件和角色条件校验。
+     *
+     * @param userId 用户 ID
+     * @param dimensionType 维度类型，如 'role' 或 'department'
+     * @param dimensionIds 需要的维度 ID 列表
+     * @param logical AND = 全部满足, OR = 满足任一
+     */
+    hasDimension(userId: string, dimensionType: string, dimensionIds: string[], logical?: 'AND' | 'OR' | 'DEFAULT'): Promise<boolean>;
+    /**
+     * 检查用户是否拥有某资源的全部指定动作。
+     */
+    hasResourceActions(userId: string, resourceId: string, actions: string[]): Promise<boolean>;
+    /**
+     * 批量导入权限
+     */
+    importPermissions(permissions: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        status?: boolean;
+        actions?: unknown[];
+        optionalFields?: unknown[];
+        parents?: string[];
+    }>): Promise<{
+        total: number;
+        success: number;
+        fail: number;
+        results: {
+            id: string;
+            success: boolean;
+            message: string;
+        }[];
+    }>;
+    private addPermissionToSet;
+}
+
+declare class PermissionsGuard implements CanActivate {
+    private reflector;
+    private permissionService;
+    private readonly logger;
+    constructor(reflector: Reflector, permissionService: PermissionService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private hasAuthorizeResourcePermission;
+    private hasAuthorizeDimensions;
+    private resolveAuthorizeOptions;
+    private mergeResources;
+    private mergeDimensions;
+    private cloneAuthorizeOptions;
+    private createEmptyAuthorizeOptions;
+    private cloneResource;
+    private normalizeLogical;
+}
+
+/** Key to store data access result on the request for downstream use */
+declare const DATA_ACCESS_RESULT_KEY = "__dataAccessResult";
+declare class DataPermissionGuard implements CanActivate {
+    private reflector;
+    private readonly handlers;
+    private readonly logger;
+    constructor(reflector: Reflector, handlers: DataAccessHandler[] | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private isAuthentication;
+    private getActionFromMethod;
+    private getDataTypeFromRequest;
+}
+
+/**
+ * Two-factor authentication interfaces.
+ */
+interface TwoFactorValidator {
+    /**
+     * Returns the provider identifier.
+     */
+    getProvider(): string;
+    /**
+     * Verify a code and keep the validation valid until timeout elapses.
+     */
+    verify(code: string, timeout: number): Promise<boolean> | boolean;
+    /**
+     * Whether the current validation has expired.
+     */
+    expired(): Promise<boolean> | boolean;
+}
+interface TwoFactorValidatorProvider {
+    /**
+     * Returns the provider identifier (e.g., 'totp', 'sms').
+     */
+    getProvider(): string;
+    /**
+     * Create a validator instance for a specific user and operation.
+     */
+    createTwoFactorValidator(userId: string, operation: string): TwoFactorValidator;
+}
+
+declare const TWO_FACTOR_PROVIDERS: unique symbol;
+declare class TwoFactorService {
+    private readonly logger;
+    private readonly providerMap;
+    constructor(providers?: TwoFactorValidatorProvider[] | null);
+    registerProvider(provider: TwoFactorValidatorProvider): void;
+    getProvider(name: string): TwoFactorValidatorProvider | undefined;
+    getAvailableProviders(): string[];
+    /**
+     * Validate a two-factor code.
+     * @param userId - the user ID
+     * @param provider - the provider name (e.g. 'totp', 'sms')
+     * @param code - the verification code
+     * @param operation - the operation requiring 2FA
+     */
+    validate(userId: string, provider: string, code: string, operation: string, timeout: number): Promise<boolean>;
+    /**
+     * Get a validator for a user/operation.
+     */
+    getValidator(userId: string, operation: string, provider: string): TwoFactorValidator | undefined;
+}
+
+/**
+ * TwoFactorGuard — 双因素认证守卫
+ *
+ * 消费 @TwoFactor 装饰器的元数据，在请求进入 handler 前
+ * 验证双因素认证码。
+ *
+ * 支持类级别和方法级别组合（方法级别优先）。
+ */
+declare class TwoFactorGuard implements CanActivate {
+    private readonly reflector;
+    private readonly twoFactorService;
+    private readonly logger;
+    constructor(reflector: Reflector, twoFactorService: TwoFactorService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+interface ScannedPermission {
+    id: string;
+    name: string;
+    description: string;
+    status: boolean;
+    actions: Array<{
+        action: string;
+        name: string;
+        description: string;
+        properties?: Record<string, unknown>;
+    }>;
+    optionalFields?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+declare class PermissionScannerService {
+    private readonly discoveryService;
+    private readonly metadataScanner;
+    private readonly reflector;
+    constructor(discoveryService: DiscoveryService, metadataScanner: MetadataScanner, reflector: Reflector);
+    scanPermissions(): ScannedPermission[];
+    private ensurePermission;
+    private addAction;
+}
+
+interface MenuNode {
+    id: string;
+    name: string;
+    path?: string;
+    icon?: string;
+    parentId?: string;
+    sortOrder: number;
+    status: boolean;
+    permissions: string[];
+    properties?: Record<string, unknown>;
+    children?: MenuNode[];
+}
+declare class MenuService {
+    private readonly db;
+    private readonly logger;
+    constructor(db: DatabaseAdapter);
+    /** 获取完整菜单树 */
+    getMenuTree(): Promise<MenuNode[]>;
+    /** 根据用户权限过滤菜单树 */
+    getMenuTreeByUserId(userId: string, userPermissions: string[]): Promise<MenuNode[]>;
+    /** 根据角色获取菜单 ID 列表 */
+    getMenuIdsByRoleId(roleId: string): Promise<string[]>;
+    /** 为角色分配菜单 */
+    assignMenusToRole(roleId: string, menuIds: string[]): Promise<void>;
+    /**
+     * 批量更新菜单（排序、状态等）
+     */
+    batchUpdate(menus: Array<{
+        id: string;
+        sortOrder?: number;
+        status?: boolean;
+        name?: string;
+        path?: string;
+        icon?: string;
+    }>): Promise<number>;
+    private buildTree;
+}
+
+interface ThirdPartyProfile {
+    providerAccountId: string;
+    email?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: Date;
+    profileData?: Record<string, unknown>;
+}
+declare class ThirdPartyAccountService {
+    private readonly db;
+    private readonly logger;
+    constructor(db: DatabaseAdapter);
+    /** 绑定第三方账号到用户 */
+    bindAccount(userId: string, provider: string, profile: ThirdPartyProfile): Promise<void>;
+    /** 解绑第三方账号（禁止解绑最后一个登录方式） */
+    unbindAccount(userId: string, provider: string): Promise<void>;
+    /**
+     * OAuth 登录时查找或创建用户
+     * 如果第三方账号已绑定，返回绑定的用户
+     * 如果未绑定，创建新用户并绑定
+     */
+    findOrCreateUser(provider: string, profile: ThirdPartyProfile): Promise<{
+        userId: string;
+        isNew: boolean;
+    }>;
+    /** 获取用户的所有第三方绑定 */
+    getUserBinds(userId: string): Promise<Array<{
+        provider: string;
+        displayName?: string;
+        email?: string;
+    }>>;
+}
+
+/**
+ * 内置的部门维度 Provider 示例
+ * 基于 dimensions / dimensionUsers 表实现组织架构维度
+ */
+declare class DepartmentDimensionProvider implements DimensionProvider {
+    private readonly db;
+    readonly dimensionType = "department";
+    private readonly logger;
+    constructor(db: DatabaseAdapter);
+    getAllTypes(): Promise<DimensionType[]>;
+    getDimensionsByUserId(userId: string): Promise<Dimension[]>;
+    getDimensionById(type: DimensionType, id: string): Promise<Dimension | null>;
+    getUserIdsByDimensionId(dimensionId: string): Promise<string[]>;
+    /** 获取用户绑定的维度值列表 */
+    getDimensionValues(userId: string): Promise<string[]>;
+    /** 级联展开：返回该维度节点及其所有子节点的 ID */
+    expandDimensionTree(value: string): Promise<string[]>;
+}
+
+/**
+ * Password encoder interface.
+ */
+interface PasswordEncoder {
+    /**
+     * Encode a raw password into a secure hash.
+     */
+    encode(raw: string): Promise<string>;
+    /**
+     * Check if a raw password matches the encoded hash.
+     */
+    matches(raw: string, encoded: string): Promise<boolean>;
+}
+
+/**
+ * Password strength validation.
+ */
+interface PasswordPolicy {
+    minLength: number;
+    maxLength: number;
+    requireUppercase: boolean;
+    requireLowercase: boolean;
+    requireDigit: boolean;
+    requireSpecialChar: boolean;
+    specialChars?: string;
+}
+declare const DEFAULT_PASSWORD_POLICY: PasswordPolicy;
+/**
+ * Shared validation result — same shape as UsernameValidationResult.
+ * Unified to avoid duplicating the {valid, errors} interface.
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+declare class PasswordValidator {
+    private readonly policy;
+    constructor(policy?: Partial<PasswordPolicy>);
+    validate(password: string): ValidationResult;
+}
+
+/**
+ * Username validation
+ *
+ * Provides configurable username policy enforcement including:
+ * - Length constraints
+ * - Character restrictions (alphanumeric, email format, etc.)
+ * - Reserved name blocking
+ */
+interface UsernamePolicy {
+    minLength: number;
+    maxLength: number;
+    /** Allowed character pattern (regex). Default: alphanumeric + underscore + dot + @ */
+    pattern: RegExp;
+    /** Human-readable description of the pattern for error messages */
+    patternDescription: string;
+    /** Reserved usernames that cannot be used */
+    reservedNames: string[];
+}
+declare const DEFAULT_USERNAME_POLICY: UsernamePolicy;
+interface UsernameValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * UsernameValidator — configurable username policy enforcement.
+ */
+declare class UsernameValidator {
+    private readonly policy;
+    constructor(policy?: Partial<UsernamePolicy>);
+    validate(username: string): UsernameValidationResult;
+}
+
+/** Minimal TopicEventBus interface to avoid hard dependency on @zucker-framework/event */
+interface TopicEventBusLike$4 {
+    publish(topic: string, payload: unknown): Promise<void>;
+}
+/** User entity shape — 对齐 Prisma schema `model users` */
+interface UserEntity {
+    id: string;
+    username: string;
+    password?: string;
+    name: string;
+    typeId: string;
+    status: boolean;
+    creatorId?: string;
+    createTime?: Date | number;
+    email?: string;
+    emailVerified?: boolean;
+    locale?: string;
+    [key: string]: unknown;
+}
+declare const PASSWORD_ENCODER: unique symbol;
+
+/**
+ * UserService
+ *
+ * Provides complete user lifecycle management:
+ * - CRUD operations with duplicate-username protection
+ * - Password encoding with per-user salt
+ * - Username and password validation
+ * - Status management (enable/disable)
+ * - Event publishing for all user mutations
+ * - Authorization cache invalidation on user changes
+ */
+declare class UserService {
+    private readonly db;
+    private readonly topicEventBus?;
+    private readonly logger;
+    private passwordEncoder;
+    private passwordValidator;
+    private usernameValidator;
+    constructor(db: DatabaseAdapter, passwordEncoder?: PasswordEncoder, topicEventBus?: TopicEventBusLike$4 | undefined);
+    /** Override the password encoder (e.g. for testing or custom schemes) */
+    setPasswordEncoder(encoder: PasswordEncoder): void;
+    /** Override the password validator policy */
+    setPasswordValidator(validator: PasswordValidator): void;
+    /** Override the username validator policy */
+    setUsernameValidator(validator: UsernameValidator): void;
+    /**
+     * Find a user by ID.
+     */
+    findById(id: string): Promise<UserEntity | null>;
+    /**
+     * Find a user by username.
+     */
+    findByUsername(username: string): Promise<UserEntity | null>;
+    /**
+     * Find a user by username and verify the plain-text password matches.
+     * Returns null if user not found or password does not match.
+     */
+    findByUsernameAndPassword(username: string, plainPassword: string): Promise<UserEntity | null>;
+    /**
+     * Save a user (insert if no ID or not found, update if exists).
+     */
+    saveUser(userEntity: Partial<UserEntity> & {
+        username: string;
+    }): Promise<UserEntity>;
+    /**
+     * Add a new user.
+     *
+     * - Validates username and password
+     * - Checks for duplicate username
+     * - Generates salt and encodes password
+     * - Publishes UserCreatedEvent
+     */
+    addUser(data: Partial<UserEntity> & {
+        username: string;
+        password?: string;
+    }): Promise<UserEntity>;
+    /**
+     * Update an existing user.
+     *
+     * - Re-encodes password if changed
+     * - Publishes UserModifiedEvent with passwordChanged flag
+     * - Clears authorization cache for the user
+     */
+    private doUpdate;
+    /**
+     * Change user status (enable/disable).
+     *
+     * - Batch update status for multiple user IDs
+     * - Publishes UserStateChangedEvent
+     */
+    changeState(userIds: string[], state: number | boolean): Promise<number>;
+    /**
+     * Change user password.
+     *
+     * - Verifies old password before allowing change
+     * - Validates new password
+     * - Publishes UserModifiedEvent with passwordChanged flag
+     */
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<boolean>;
+    /**
+     * Delete a user.
+     *
+     * - Publishes UserDeletedEvent
+     */
+    deleteUser(userId: string): Promise<boolean>;
+    /**
+     * Lock a user account.
+     */
+    lockUser(userId: string): Promise<void>;
+    /**
+     * Unlock a user account.
+     */
+    unlockUser(userId: string): Promise<void>;
+    /**
+     * Query users with dynamic filters.
+     */
+    findUsers(where?: Record<string, unknown>): Promise<UserEntity[]>;
+    /**
+     * Count users matching a filter.
+     */
+    countUsers(where?: Record<string, unknown>): Promise<number>;
+    private publishEvent;
+}
+
+/** Minimal TopicEventBus interface to avoid hard dependency on @zucker-framework/event */
+interface TopicEventBusLike$3 {
+    publish(topic: string, payload: unknown): Promise<void>;
+}
+/** Role entity shape — 对齐 Prisma schema `model roles` */
+interface RoleEntity {
+    id: string;
+    name: string;
+    description?: string;
+    status?: boolean;
+    parentId?: string;
+    groupId?: string;
+    creatorId?: string;
+    createTime?: Date | number;
+    [key: string]: unknown;
+}
+/** Role event topics */
+declare const ROLE_EVENT_TOPICS: {
+    readonly ROLE_CREATED: "/role/created";
+    readonly ROLE_MODIFIED: "/role/modified";
+    readonly ROLE_DELETED: "/role/deleted";
+};
+declare function createRoleCreatedEvent(roleId: string, roleName: string, creatorId?: string): {
+    roleId: string;
+    roleName: string;
+    creatorId: string | undefined;
+    timestamp: number;
+};
+declare function createRoleModifiedEvent(roleId: string, changes: Array<{
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+}>): {
+    roleId: string;
+    changes: {
+        field: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }[];
+    timestamp: number;
+};
+declare function createRoleDeletedEvent(roleId: string): {
+    roleId: string;
+    timestamp: number;
+};
+/**
+ * RoleService
+ *
+ * Provides complete role lifecycle management:
+ * - CRUD operations with name-based lookup
+ * - Permission assignment with transactional guarantee
+ * - Cascade deletion of related rolePermissions/userRoles/roleMenus
+ * - Event publishing for all role mutations
+ */
+declare class RoleService {
+    private readonly db;
+    private readonly topicEventBus?;
+    private readonly permissionService?;
+    private readonly logger;
+    private roleHierarchyService?;
+    constructor(db: DatabaseAdapter, topicEventBus?: TopicEventBusLike$3 | undefined, permissionService?: PermissionService | undefined);
+    /** 注入角色层级服务（在模块初始化后调用） */
+    setRoleHierarchyService(service: RoleHierarchyService): void;
+    /**
+     * Find a role by ID.
+     */
+    findById(id: string): Promise<RoleEntity | null>;
+    /**
+     * Find a role by name.
+     */
+    findByName(name: string): Promise<RoleEntity | null>;
+    /**
+     * Query roles with dynamic filters.
+     */
+    findRoles(where?: Record<string, unknown>): Promise<RoleEntity[]>;
+    /**
+     * Count roles matching a filter.
+     */
+    countRoles(where?: Record<string, unknown>): Promise<number>;
+    /**
+     * Add a new role.
+     *
+     * - Sets default status and createTime
+     * - Publishes RoleCreatedEvent
+     */
+    addRole(data: Partial<RoleEntity> & {
+        name: string;
+    }): Promise<RoleEntity>;
+    /**
+     * Update an existing role.
+     *
+     * - Tracks field changes
+     * - Publishes RoleModifiedEvent
+     */
+    updateRole(id: string, data: Partial<RoleEntity>): Promise<RoleEntity>;
+    /**
+     * Delete a role with cascade cleanup.
+     *
+     * - Cascade deletes rolePermissions, userRoles, roleMenus
+     * - Publishes RoleDeletedEvent
+     */
+    deleteRole(id: string): Promise<boolean>;
+    /**
+     * Get permission IDs assigned to a role.
+     */
+    getRolePermissions(roleId: string): Promise<string[]>;
+    /**
+     * Set permissions for a role (replace all).
+     * Uses transaction to ensure atomicity.
+     */
+    setRolePermissions(roleId: string, permissionIds: string[]): Promise<void>;
+    private publishEvent;
+}
+
+/** Minimal TopicEventBus interface to avoid hard dependency on @zucker-framework/event */
+interface TopicEventBusLike$2 {
+    publish(topic: string, payload: unknown): Promise<void>;
+    subscribe?(topic: string, handler: (payload: unknown) => void | Promise<void>): void;
+}
+/**
+ * Authorization setting entity shape.
+ * Each row maps a permission to a dimension (role/department/etc.)
+ * with specific action access.
+ */
+interface AuthorizationSettingEntity {
+    id: string;
+    permission: string;
+    dimensionType: string;
+    dimensionTarget: string;
+    /** JSON: the granted actions for this permission+dimension combination */
+    actions?: unknown;
+    /** JSON: data access configurations */
+    dataAccesses?: unknown;
+    /** Merge flag: true = merge with other dimension settings */
+    merge?: boolean;
+    /** Priority: higher = higher precedence when merging */
+    priority?: number;
+    status?: number;
+}
+/**
+ * AuthorizationSettingService
+ *
+ * Manages the mapping between permissions and dimensions (roles, departments, etc.).
+ * - Generates deterministic IDs from permission + dimensionType + dimensionTarget
+ * - Clears user authorization cache when settings are modified
+ * - Cascade-deletes settings when a dimension is deleted
+ */
+declare class AuthorizationSettingService {
+    private readonly db;
+    private readonly dimensionService?;
+    private readonly topicEventBus?;
+    private readonly logger;
+    constructor(db: DatabaseAdapter, dimensionService?: DimensionService | undefined, topicEventBus?: TopicEventBusLike$2 | undefined);
+    /**
+     * Generate a deterministic ID for an authorization setting.
+     *
+     * -- uses DigestUtils.md5Hex(permission + dimensionType + dimensionTarget)
+     */
+    generateId(entity: Pick<AuthorizationSettingEntity, 'permission' | 'dimensionType' | 'dimensionTarget'>): string;
+    /**
+     * Save (upsert) one or more authorization settings.
+     * Auto-generates IDs if not set.
+     */
+    save(settings: AuthorizationSettingEntity | AuthorizationSettingEntity[]): Promise<number>;
+    /**
+     * Delete authorization settings by IDs.
+     */
+    deleteByIds(ids: string[]): Promise<number>;
+    /**
+     * Find settings by dimension type and target.
+     */
+    findByDimension(dimensionType: string, dimensionTarget: string): Promise<AuthorizationSettingEntity[]>;
+    /**
+     * Find settings by permission ID.
+     */
+    findByPermission(permissionId: string): Promise<AuthorizationSettingEntity[]>;
+    /**
+     * Clear user authorization cache for users affected by setting changes.
+     *
+     * -- resolves dimension providers to find all affected user IDs,
+     *    then publishes ClearUserAuthorizationCacheEvent
+     */
+    private clearUserAuthCache;
+    /**
+     * Handle dimension deletion -- cascade delete associated authorization settings.
+     */
+    private handleDimensionDeleted;
+}
+
+/** Minimal TopicEventBus interface to avoid hard dependency on @zucker-framework/event */
+interface TopicEventBusLike$1 {
+    publish(topic: string, payload: unknown): Promise<void>;
+    subscribe?(topic: string, handler: (payload: unknown) => void | Promise<void>): void;
+}
+/**
+ * Dimension-user binding entity.
+ */
+interface DimensionUserEntity {
+    id: string;
+    userId: string;
+    dimensionTypeId: string;
+    dimensionId: string;
+    dimensionName?: string;
+}
+/**
+ * DimensionUserService
+ *
+ * Manages the binding between users and dimensions (roles, departments, etc.).
+ * Publishes bind/unbind events and handles cascade deletions.
+ *
+ * Key behaviors:
+ * - User deleted -> delete all dimension bindings for that user
+ * - Dimension entity deleted -> delete all bindings for that dimension
+ * - Binding saved/created -> publish DimensionBindEvent + clear auth cache
+ * - Binding deleted -> publish DimensionUnbindEvent + clear auth cache
+ * - Binding modified -> clear auth cache
+ */
+declare class DimensionUserService {
+    private readonly db;
+    private readonly topicEventBus?;
+    private readonly logger;
+    constructor(db: DatabaseAdapter, topicEventBus?: TopicEventBusLike$1 | undefined);
+    /**
+     * Bind a user to a dimension.
+     */
+    bind(data: {
+        userId: string;
+        dimensionTypeId: string;
+        dimensionId: string;
+        dimensionName?: string;
+    }): Promise<DimensionUserEntity>;
+    /**
+     * Batch bind users to dimensions.
+     */
+    bindBatch(bindings: Array<{
+        userId: string;
+        dimensionTypeId: string;
+        dimensionId: string;
+        dimensionName?: string;
+    }>): Promise<DimensionUserEntity[]>;
+    /**
+     * Unbind a user from a dimension.
+     */
+    unbind(id: string): Promise<boolean>;
+    /**
+     * Find all bindings for a user.
+     */
+    findByUserId(userId: string): Promise<DimensionUserEntity[]>;
+    /**
+     * Find all bindings for a dimension.
+     */
+    findByDimensionId(dimensionId: string): Promise<DimensionUserEntity[]>;
+    /**
+     * Get user IDs bound to a specific dimension.
+     */
+    getUserIdsByDimensionId(dimensionId: string): Promise<string[]>;
+    /**
+     * Get dimension bind info for multiple users.
+     */
+    getDimensionBindInfo(userIds: string[]): Promise<Array<{
+        userId: string;
+        dimensionTypeId: string;
+        dimensionId: string;
+    }>>;
+    /**
+     * Handle user deletion -- cascade delete all dimension bindings.
+     */
+    private handleUserDeleted;
+    /**
+     * Handle dimension entity deletion -- cascade delete all user bindings.
+     */
+    private handleDimensionDeleted;
+    /**
+     * Clear authorization cache for affected users.
+     */
+    private clearUserCache;
+    private publishEvent;
+}
+
+/**
+ * PermissionSyncService
+ *
+ * Scans controller decorators (@Resource/@Action) at startup and synchronizes
+ * discovered permission definitions to the database. Existing permissions are
+ * updated (actions merged), new permissions are created.
+ *
+ * Key behaviors:
+ * - Scan @Resource/@Action definitions with PermissionScannerService
+ * - Merge with existing DB records (preserve custom actions, merge new ones)
+ * - Convert ResourceDefinition to PermissionEntity with actions and optionalFields
+ * - Upsert (save) all merged permissions to the database
+ */
+declare class PermissionSyncService implements OnModuleInit {
+    private readonly db;
+    private readonly scannerService?;
+    private readonly logger;
+    private enabled;
+    constructor(db: DatabaseAdapter, scannerService?: PermissionScannerService | undefined);
+    /** Disable automatic sync on startup (useful for tests) */
+    setEnabled(enabled: boolean): void;
+    /**
+     * NestJS lifecycle hook -- runs permission synchronization on startup.
+     */
+    onModuleInit(): Promise<void>;
+    /**
+     * Perform permission synchronization.
+     *
+     * 1. Scan all controller @Resource/@Action decorators
+     * 2. Load existing permissions from database
+     * 3. Merge scanned definitions with existing records
+     * 4. Upsert merged permissions back to database
+     */
+    synchronize(): Promise<{
+        total: number;
+        created: number;
+        updated: number;
+    }>;
+    /**
+     * Merge a scanned permission definition with an existing database record.
+     *
+     * - Preserves existing name/description if already set
+     * - Merges actions (new actions added, existing preserved)
+     * - Preserves existing optionalFields
+     * - Adds supportDataAccessTypes from scanned definition
+     */
+    private mergePermission;
+    private parseActions;
+}
+
+declare class MenuController {
+    private readonly menuService;
+    private readonly permissionService;
+    private readonly db;
+    constructor(menuService: MenuService, permissionService: PermissionService, db: DatabaseAdapter);
+    /** GET /api/menu/tree — 获取当前用户可见的菜单树 */
+    getMenuTree(req: {
+        user: {
+            id: string;
+        };
+    }): Promise<MenuNode[]>;
+    /** GET /api/menu/all — 获取全部菜单列表（管理端用） */
+    getAllMenus(): Promise<unknown[]>;
+    /** GET /api/menu/:id — 查询单个菜单 */
+    findOne(id: string): Promise<unknown>;
+    /** POST /api/menu — 创建菜单 */
+    create(body: Record<string, unknown>): Promise<unknown>;
+    /** PUT /api/menu/:id — 更新菜单 */
+    update(id: string, body: Record<string, unknown>): Promise<unknown>;
+    /** DELETE /api/menu/:id — 递归删除菜单及所有子菜单 */
+    remove(id: string): Promise<void>;
+    /** 递归收集所有后代菜单 ID */
+    private collectDescendantIds;
+    /** PUT /api/menu/:id/sort — 更新菜单排序 */
+    updateSort(id: string, body: {
+        sortOrder: number;
+    }): Promise<unknown>;
+}
+
+declare class ThirdPartyAccountController {
+    private readonly thirdPartyAccountService;
+    constructor(thirdPartyAccountService: ThirdPartyAccountService);
+    /** 获取当前用户的所有第三方绑定 */
+    getBinds(req: {
+        user: {
+            id: string;
+        };
+    }): Promise<{
+        provider: string;
+        displayName?: string;
+        email?: string;
+    }[]>;
+    /** 绑定第三方账号 */
+    bind(req: {
+        user: {
+            id: string;
+        };
+    }, provider: string, profile: ThirdPartyProfile): Promise<{
+        success: boolean;
+    }>;
+    /** 解绑第三方账号 */
+    unbind(req: {
+        user: {
+            id: string;
+        };
+    }, provider: string): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface TopicEventBusLike {
+    publish(topic: string, payload: unknown): Promise<void>;
+}
+interface LoginRequest {
+    username: string;
+    password: string;
+    [key: string]: unknown;
+}
+interface LoginResult {
+    userId: string;
+    token: string;
+    expires: number;
+    [key: string]: unknown;
+}
+interface AuthenticationManagerLike {
+    authenticate(username: string, password: string): Promise<AuthUser | null>;
+    getByUserId?(userId: string): Promise<Authentication | null>;
+}
+declare const AUTHENTICATION_MANAGER = "AUTHENTICATION_MANAGER";
+declare class AuthorizationController {
+    private readonly tokenService;
+    private readonly authManager;
+    private readonly authHolder?;
+    private readonly eventBus?;
+    private readonly logger;
+    constructor(tokenService: TokenService, authManager: AuthenticationManagerLike, authHolder?: AuthenticationHolder | undefined, eventBus?: TopicEventBusLike | undefined);
+    /**
+     * GET /authorize/me — current user's authentication info.
+     */
+    me(req: {
+        user?: AuthUser;
+        auth?: Authentication;
+    }): Promise<Authentication>;
+    /**
+     * POST /authorize/login — username/password login.
+     * 1. DecodeEvent (可修改密码/用户名)
+     * 2. BeforeEvent (可阻止登录/注入已认证用户)
+     * 3. authenticate
+     * 4. SuccessEvent / FailedEvent
+     */
+    login(body: LoginRequest): Promise<LoginResult>;
+}
+
+declare class UserTokenController {
+    private readonly tokenService;
+    constructor(tokenService: TokenService);
+    /**
+     * GET /user-token/reset — reset current user's token (sign out self).
+     */
+    resetToken(): Promise<boolean>;
+    /**
+     * PUT /user-token/check — check and remove all expired tokens.
+     */
+    checkExpiredToken(): Promise<boolean>;
+    /**
+     * GET /user-token/token/:token — get token info by token string.
+     */
+    getByToken(token: string): Promise<TokenInfo | null>;
+    /**
+     * GET /user-token/user/:userId — get all tokens for a user.
+     */
+    getByUserId(userId: string): Promise<TokenInfo[]>;
+    /**
+     * GET /user-token/user/:userId/logged — check if user is logged in.
+     */
+    userIsLoggedIn(userId: string): Promise<boolean>;
+    /**
+     * GET /user-token/token/:token/logged — check if token is active.
+     */
+    tokenIsLoggedIn(token: string): Promise<boolean>;
+    /**
+     * GET /user-token/user/total — total logged-in users.
+     */
+    totalUser(): Promise<number>;
+    /**
+     * GET /user-token/token/total — total active tokens.
+     */
+    totalToken(): Promise<number>;
+    /**
+     * GET /user-token — list all active tokens.
+     */
+    allLoggedUser(): Promise<TokenInfo[]>;
+    /**
+     * DELETE /user-token/user/:userId — kick user offline by userId.
+     */
+    signOutByUserId(userId: string): Promise<void>;
+    /**
+     * DELETE /user-token/token/:token — invalidate a specific token.
+     */
+    signOutByToken(token: string): Promise<void>;
+    /**
+     * PUT /user-token/user/:userId/:state — change all tokens for a user to a state.
+     */
+    changeUserState(userId: string, state: string): Promise<void>;
+    /**
+     * GET /user-token/:token/touch — refresh token TTL.
+     */
+    touch(token: string): Promise<void>;
+}
+
+interface JwtPayload {
+    sub: string;
+    username: string;
+    [key: string]: unknown;
+}
+declare const JwtStrategy_base: new (...args: [opt: passport_jwt.StrategyOptionsWithRequest] | [opt: StrategyOptionsWithoutRequest]) => Strategy & {
+    validate(...args: any[]): unknown;
+};
+declare class JwtStrategy extends JwtStrategy_base {
+    constructor(secret: string);
+    validate(payload: JwtPayload): Record<string, unknown> & {
+        id: string;
+        username: string;
+    };
+}
+
+/**
+ * Authorization lifecycle events.
+ */
+declare const AUTH_EVENT_TOPICS: {
+    readonly USER_CREATED: "auth/user/created";
+    readonly USER_MODIFIED: "auth/user/modified";
+    readonly USER_DELETED: "auth/user/deleted";
+    readonly USER_STATE_CHANGED: "auth/user/state-changed";
+    readonly DIMENSION_BIND: "auth/dimension/bind";
+    readonly DIMENSION_UNBIND: "auth/dimension/unbind";
+    readonly DIMENSION_DELETED: "auth/dimension/deleted";
+    readonly LOGIN_BEFORE: "auth/login/before";
+    readonly LOGIN_DECODE: "auth/login/decode";
+    readonly LOGIN_SUCCESS: "auth/login/success";
+    readonly LOGIN_FAILED: "auth/login/failed";
+    readonly LOGIN_EXIT: "auth/login/exit";
+    readonly AUTH_INITIALIZE: "auth/initialize";
+    readonly AUTH_HANDLE_BEFORE: "auth/handle/before";
+    readonly TOKEN_CREATED: "auth/token/created";
+    readonly TOKEN_CHANGED: "auth/token/changed";
+    readonly TOKEN_REMOVED: "auth/token/removed";
+    readonly CLEAR_AUTH_CACHE: "auth/cache/clear";
+};
+interface FieldChange {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+interface UserCreatedEvent {
+    userId: string;
+    username: string;
+    creator?: string;
+    timestamp: Date;
+}
+interface UserModifiedEvent {
+    userId: string;
+    changes: FieldChange[];
+    /** 密码是否变更 */
+    passwordChanged?: boolean;
+    modifier?: string;
+    timestamp: Date;
+}
+interface UserDeletedEvent {
+    userId: string;
+    operator?: string;
+    timestamp: Date;
+}
+type UserState = 'enabled' | 'disabled' | 'locked';
+interface UserStateChangedEvent {
+    userId: string;
+    oldState: UserState;
+    newState: UserState;
+    operator?: string;
+    timestamp: Date;
+}
+interface DimensionBindEvent {
+    userId: string;
+    dimensionType: string;
+    dimensionId: string;
+    operator?: string;
+    timestamp: Date;
+}
+interface DimensionUnbindEvent {
+    userId: string;
+    dimensionType: string;
+    dimensionId: string;
+    operator?: string;
+    timestamp: Date;
+}
+/**
+ * 维度删除事件
+ *
+ * 当维度实体（如角色、部门）被删除时触发，
+ * 用于级联清理该维度关联的授权配置。
+ */
+interface DimensionDeletedEvent {
+    dimensionType: string;
+    dimensionId: string;
+    timestamp: Date;
+}
+/**
+ * 维度用户绑定信息
+ *
+ * 表示用户与维度的绑定关系，
+ * 用于 DimensionUserBindProvider.getDimensionBindInfo() 返回值。
+ */
+interface DimensionUserBind {
+    userId: string;
+    dimensionTypeId: string;
+    dimensionId: string;
+}
+/**
+ * Clear user authorization cache event.
+ * If userId is undefined, all caches should be cleared.
+ */
+interface ClearUserAuthorizationCacheEvent {
+    userId?: string;
+    reason?: string;
+    timestamp: Date;
+}
+/** Fired before login attempt. */
+interface LoginBeforeEvent {
+    username: string;
+    /** Additional parameters from the login request */
+    parameters?: Record<string, unknown>;
+    /**
+     * Set by event handlers to short-circuit authentication with a known userId.
+     */
+    authorizedUserId?: string;
+    /**
+     * Set to true when pre-authorization has been established
+     */
+    isAuthorized?: boolean;
+    timestamp: Date;
+}
+/** Fired to decode/transform credentials. */
+interface LoginDecodeEvent {
+    username: string;
+    /** Password to decode  */
+    password?: string;
+    /** Decoded/transformed username (set by handlers) */
+    decodedUsername?: string;
+    /** Decoded/transformed password (set by handlers) */
+    decodedPassword?: string;
+    /** Additional parameters from the login request */
+    parameters?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Fired after successful login. */
+interface LoginSuccessEvent {
+    userId: string;
+    username: string;
+    /** Additional result data that handlers can attach  */
+    result?: Record<string, unknown>;
+    /** Additional parameters from the login request  */
+    parameters?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Fired after failed login attempt. */
+interface LoginFailedEvent {
+    username: string;
+    error: string;
+    /** The actual exception/error object  */
+    exception?: Error;
+    /** Additional parameters from the login request */
+    parameters?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Fired when user logs out. */
+interface LoginExitEvent {
+    userId: string;
+    username?: string;
+    timestamp: Date;
+}
+/** Fired when authentication is initialized/loaded. */
+interface AuthInitializeEvent {
+    userId: string;
+    timestamp: Date;
+}
+/** Fired before authorization check. */
+interface AuthHandleBeforeEvent {
+    userId: string;
+    permissionId: string;
+    action: string;
+    /** Set to true by handlers to explicitly allow */
+    allow?: boolean;
+    /** Set to true to skip default authorization logic */
+    skip?: boolean;
+    timestamp: Date;
+}
+/** Fired when a new token is created. */
+interface TokenCreatedEvent {
+    token: string;
+    userId: string;
+    type: string;
+    timestamp: Date;
+}
+/** Fired when a token state changes. */
+interface TokenChangedEvent {
+    token: string;
+    userId: string;
+    oldState: string;
+    newState: string;
+    timestamp: Date;
+}
+/** Fired when a token is removed. */
+interface TokenRemovedEvent {
+    token: string;
+    userId: string;
+    timestamp: Date;
+}
+declare function createUserCreatedEvent(userId: string, username: string, creator?: string): UserCreatedEvent;
+declare function createUserModifiedEvent(userId: string, changes: FieldChange[], modifier?: string, passwordChanged?: boolean): UserModifiedEvent;
+declare function createUserDeletedEvent(userId: string, operator?: string): UserDeletedEvent;
+declare function createUserStateChangedEvent(userId: string, oldState: UserState, newState: UserState, operator?: string): UserStateChangedEvent;
+declare function createDimensionBindEvent(userId: string, dimensionType: string, dimensionId: string, operator?: string): DimensionBindEvent;
+declare function createDimensionUnbindEvent(userId: string, dimensionType: string, dimensionId: string, operator?: string): DimensionUnbindEvent;
+declare function createDimensionDeletedEvent(dimensionType: string, dimensionId: string): DimensionDeletedEvent;
+declare function createDimensionUserBind(userId: string, dimensionTypeId: string, dimensionId: string): DimensionUserBind;
+declare function createClearAuthCacheEvent(userId?: string, reason?: string): ClearUserAuthorizationCacheEvent;
+declare function createLoginBeforeEvent(username: string, parameters?: Record<string, unknown>): LoginBeforeEvent;
+declare function createLoginDecodeEvent(username: string, password?: string, parameters?: Record<string, unknown>): LoginDecodeEvent;
+declare function createLoginSuccessEvent(userId: string, username: string, result?: Record<string, unknown>, parameters?: Record<string, unknown>): LoginSuccessEvent;
+declare function createLoginFailedEvent(username: string, error: string, exception?: Error, parameters?: Record<string, unknown>): LoginFailedEvent;
+declare function createLoginExitEvent(userId: string, username?: string): LoginExitEvent;
+declare function createAuthInitializeEvent(userId: string): AuthInitializeEvent;
+declare function createAuthHandleBeforeEvent(userId: string, permissionId: string, action: string): AuthHandleBeforeEvent;
+declare function createTokenCreatedEvent(token: string, userId: string, type: string): TokenCreatedEvent;
+declare function createTokenChangedEvent(token: string, userId: string, oldState: string, newState: string): TokenChangedEvent;
+declare function createTokenRemovedEvent(token: string, userId: string): TokenRemovedEvent;
+
+/**
+ * TOTP (Time-based One-Time Password) validator.
+ * Compatible with Google Authenticator (RFC 6238).
+ *
+ * Implements HMAC-based OTP without external dependencies.
+ */
+declare class TotpValidator implements TwoFactorValidatorProvider {
+    private readonly period;
+    private readonly digits;
+    private readonly window;
+    private readonly validatedUntil;
+    private secretResolver;
+    constructor(options?: {
+        period?: number;
+        digits?: number;
+        window?: number;
+        secretResolver?: (userId: string) => Promise<string | null>;
+    });
+    getProvider(): string;
+    createTwoFactorValidator(userId: string, operation: string): TwoFactorValidator;
+    setSecretResolver(resolver: (userId: string) => Promise<string | null>): void;
+    /**
+     * Generate a random base32-encoded secret.
+     */
+    generateSecret(): string;
+    /**
+     * Generate a QR code URL (otpauth:// URI) for authenticator apps.
+     */
+    generateQRCodeUrl(secret: string, issuer: string, account: string): string;
+    /**
+     * Verify a TOTP token against a secret.
+     * Accepts tokens within the configured time window.
+     */
+    private verifyToken;
+    private generateToken;
+    private buildCacheKey;
+}
+
+/**
+ * Bcrypt-compatible password encoder using Node.js built-in crypto.
+ *
+ * Uses PBKDF2 with SHA-512 as a secure alternative that requires no
+ * external dependencies (bcryptjs). The output format includes the salt
+ * and iteration count for self-contained verification.
+ */
+declare class BcryptEncoder implements PasswordEncoder {
+    private readonly iterations;
+    private readonly keyLength;
+    private readonly saltLength;
+    constructor(options?: {
+        iterations?: number;
+        keyLength?: number;
+        saltLength?: number;
+    });
+    encode(raw: string): Promise<string>;
+    matches(raw: string, encoded: string): Promise<boolean>;
+    private pbkdf2;
+}
+
+/**
+ * User personalization settings service.
+ *
+ * Stores per-user settings keyed by userId + scope + key.
+ */
+declare class UserSettingsService {
+    private readonly db;
+    private readonly logger;
+    constructor(db: DatabaseAdapter);
+    get<T = unknown>(userId: string, scope: string, key: string): Promise<T | undefined>;
+    /**
+     * Get a setting as a SettingValueHolder.
+     * Returns NullSettingValueHolder if not found.
+     */
+    getSetting(userId: string, key: string, scope?: string): Promise<SettingValueHolder>;
+    set(userId: string, scope: string, key: string, value: unknown, permission?: UserSettingPermission): Promise<void>;
+    /**
+     * Save a setting with permission.
+     */
+    saveSetting(userId: string, key: string, value: string, permission?: UserSettingPermission, scope?: string): Promise<void>;
+    getAll(userId: string, scope: string): Promise<Record<string, unknown>>;
+    delete(userId: string, scope: string, key: string): Promise<void>;
+    deleteAll(userId: string, scope?: string): Promise<void>;
+}
+
+/**
+ * Authorization definition types
+ *
+ * ResourceDefinition / ResourceActionDefinition / AuthorizeDefinition
+ * describe the permission model that gets scanned from decorators at startup
+ * and stored for runtime RBAC checks.
+ */
+/** Logical operator for combining permission checks */
+type Logical = 'AND' | 'OR' | 'DEFAULT';
+/** Phase of authorization check */
+type Phased = 'before' | 'after';
+/** Handle type for authorization events */
+type HandleType = 'RBAC' | 'DATA';
+interface DataAccessTypeDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    controller?: string;
+    configuration?: Record<string, unknown>;
+}
+interface DataAccessDefinition {
+    dataAccessTypes: Set<DataAccessTypeDefinition>;
+}
+declare function createDataAccessDefinition(): DataAccessDefinition;
+/**
+ * Defines a single action within a resource (e.g. query, save, delete).
+ */
+interface ResourceActionDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    dataAccess: DataAccessDefinition;
+}
+declare function createResourceActionDefinition(id: string, name: string, description?: string): ResourceActionDefinition;
+/**
+ * Defines a permission resource (e.g. "user", "device", "role").
+ */
+interface ResourceDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    actions: Map<string, ResourceActionDefinition>;
+    group?: string[];
+    logical: Logical;
+    phased: Phased;
+}
+declare function createResourceDefinition(id: string, name: string, options?: {
+    description?: string;
+    logical?: Logical;
+    phased?: Phased;
+    group?: string[];
+}): ResourceDefinition;
+/** Add an action to a resource, merging data access types if action already exists */
+declare function addActionToResource(resource: ResourceDefinition, action: ResourceActionDefinition): void;
+/** Get all action IDs for a resource */
+declare function getActionIds(resource: ResourceDefinition): Set<string>;
+/** Check if a resource has specific actions (respects logical AND/OR) */
+declare function hasAction(resource: ResourceDefinition, actions: string[]): boolean;
+/** Get actions that have data access definitions */
+declare function getDataAccessActions(resource: ResourceDefinition): ResourceActionDefinition[];
+interface DimensionDefinition {
+    typeId: string;
+    dimensionIds: Set<string>;
+    logical: Logical;
+}
+/**
+ * Complete authorization definition for a controller method.
+ */
+interface AuthorizeDefinition {
+    resources: ResourceDefinition[];
+    dimensions: DimensionDefinition[];
+    message: string;
+    phased: Phased;
+    isEmpty: boolean;
+}
+declare function createEmptyAuthorizeDefinition(): AuthorizeDefinition;
+/** Get human-readable description of the definition (e.g. "user:query,save") */
+declare function getDefinitionDescription(def: AuthorizeDefinition): string;
+/**
+ * Check if an authentication has permission matching the resource definitions.
+ */
+declare function hasPermissionForResources(resources: ResourceDefinition[], hasPermissionFn: (resourceId: string, actions: string[]) => boolean): boolean;
+
+interface AllowPermissionConfig {
+    /** Map of dimensionType -> dimensionId -> pattern */
+    allows: Record<string, Record<string, string>>;
+}
+declare class UserAllowPermissionHandler {
+    private readonly logger;
+    private config;
+    /**
+     * Set the allows configuration.
+     */
+    setConfig(config: AllowPermissionConfig): void;
+    /**
+     * Check if the authentication is allowed to bypass permission checks
+     * for the given controller path (className.methodName).
+     *
+     * @param authentication Current user authentication
+     * @param controllerPath Full path like "UserController.query"
+     * @returns true if allowed (skip permission check), false otherwise
+     */
+    isAllowed(authentication: Authentication, controllerPath: string): boolean;
+}
+
+interface ZuckerAuthModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    /**
+     * Register the framework's generic HTTP controllers.
+     * Defaults to true for backwards compatibility.
+     */
+    registerControllers?: boolean;
+    useFactory?: (...args: unknown[]) => ZuckerAuthModuleOptions | Promise<ZuckerAuthModuleOptions>;
+    useClass?: Type<ZuckerAuthModuleOptionsFactory>;
+    useExisting?: Type<ZuckerAuthModuleOptionsFactory>;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+interface ZuckerAuthModuleOptionsFactory {
+    createAuthOptions(): ZuckerAuthModuleOptions | Promise<ZuckerAuthModuleOptions>;
+}
+declare class ZuckerAuthModule {
+    /**
+     * Build the common provider list shared by both forRoot and forRootAsync.
+     *
+     * @param optionsToken - injection token that resolves to ZuckerAuthModuleOptions
+     *                       (AUTH_MODULE_OPTIONS for async, or a literal-value provider for sync)
+     */
+    private static buildProviders;
+    /**
+     * Build option-specific providers (cache, dimensions) that differ
+     * between forRoot (has direct options) and forRootAsync (reads from token).
+     */
+    private static buildOptionSpecificProviders;
+    static forRoot(options?: ZuckerAuthModuleOptions): DynamicModule;
+    static forRootAsync(asyncOptions: ZuckerAuthModuleAsyncOptions): DynamicModule;
+    private static createAsyncProviders;
+}
+
+export { ACTION_KEY, AUTHENTICATION_MANAGER, AUTHENTICATION_SUPPLIERS, AUTHORIZE_KEY, AUTH_EVENT_TOPICS, Action, type ActionOptions, AllopatricLoginMode, type AllowPermissionConfig, type AuthHandleBeforeEvent, type AuthInitializeEvent, type AuthUser, type Authentication, AuthenticationHolder, type AuthenticationManagerLike, type AuthenticationPredicate, AuthenticationPredicates, type AuthenticationSupplier, AuthorizationController, type AuthorizationSettingEntity, AuthorizationSettingService, Authorize, type AuthorizeDefinition, type AuthorizeLogical, type AuthorizeOptions, type AuthorizePhased, type AuthorizeResourceOptions, type AuthorizingContext, BcryptEncoder, type ClearUserAuthorizationCacheEvent, CreateAction, CurrentUser, DATA_ACCESS_HANDLERS, DATA_ACCESS_RESULT_KEY, DATA_PERMISSION_KEY, DEFAULT_PASSWORD_POLICY, DEFAULT_USERNAME_POLICY, DIMENSION_KEY, DIMENSION_PROVIDERS, type DataAccessConfig, DefaultDataAccessType as DataAccessConfigDefaultType, type DataAccessDefinition, type DataAccessHandler, type DataAccessResult, type DataAccessType, type DataAccessTypeDefinition, DataPermission, DataPermissionGuard, type DataPermissionOptions, DefaultAuthentication, DefaultDataAccessType, DefaultDimensionType, DeleteAction, DepartmentDimensionProvider, type Dimension, type DimensionBindEvent, DimensionCheck, type DimensionDataAccessConfig, DimensionDataAccessHandler, type DimensionDefinition, type DimensionDeletedEvent, type DimensionOptions, type DimensionProvider, DimensionService, type DimensionType, type DimensionUnbindEvent, type DimensionUserBind, type DimensionUserEntity, DimensionUserService, type FieldChange, type FieldFilterDataAccessConfig, FieldFilterDataAccessHandler, type HandleType, IS_PUBLIC_KEY, JwtAuthGuard, type JwtPayload, JwtStrategy, type Logical, type LoginBeforeEvent, type LoginDecodeEvent, type LoginExitEvent, type LoginFailedEvent, type LoginRequest, type LoginResult, type LoginSuccessEvent, MenuController, type MenuNode, MenuService, NullSettingValueHolder, type OwnCreatedDataAccessConfig, OwnCreatedDataAccessHandler, PASSWORD_ENCODER, PERMISSIONS_KEY, type PasswordEncoder, type PasswordPolicy, PasswordValidator, type Permission, PermissionActions, PermissionScannerService, PermissionService, PermissionSyncService, Permissions, PermissionsGuard, type Phased, Public, QueryAction, RESOURCE_KEY, ROLE_EVENT_TOPICS, RequirePermissions, RequiresRoles, type RequiresRolesOptions, type ResolvedAuthorizeOptions, Resource, ResourceAction, type ResourceActionDefinition, type ResourceDefinition, type ResourceOptions, type Role, type RoleEntity, RoleHierarchyService, RoleService, type RoleTreeNode, SaveAction, type ScannedPermission, type ScopeDataAccessConfig, ScopeDataAccessHandler, type SettingValueHolder, SimpleDimension, SimpleDimensionType, SimplePermission, SkipDataPermission, type SupplierContext, TOKEN_CACHE, TWO_FACTOR_KEY, TWO_FACTOR_PROVIDERS, ThirdPartyAccountController, ThirdPartyAccountService, type ThirdPartyProfile, type TokenChangedEvent, type TokenCreatedEvent, type TokenInfo, TokenInfoUtils, type TokenRemovedEvent, TokenService, type TokenServiceOptions, TokenState, TotpValidator, TwoFactor, TwoFactorGuard, type TwoFactorOptions, TwoFactorService, type TwoFactorValidator, type TwoFactorValidatorProvider, UpdateAction, UserAllowPermissionHandler, type UserCreatedEvent, type UserDeletedEvent, type UserEntity, type UserModifiedEvent, UserService, UserSettingPermission, UserSettingsService, type UserState, type UserStateChangedEvent, UserTokenController, type UsernamePolicy, type UsernameValidationResult, UsernameValidator, ZuckerAuthModule, type ZuckerAuthModuleAsyncOptions, type ZuckerAuthModuleOptions, type ZuckerAuthModuleOptionsFactory, addActionToResource, allowResult, createAuthHandleBeforeEvent, createAuthInitializeEvent, createAuthenticationPredicate, createClearAuthCacheEvent, createDataAccessDefinition, createDimensionBindEvent, createDimensionDeletedEvent, createDimensionUnbindEvent, createDimensionUserBind, createEmptyAuthorizeDefinition, createLoginBeforeEvent, createLoginDecodeEvent, createLoginExitEvent, createLoginFailedEvent, createLoginSuccessEvent, createResourceActionDefinition, createResourceDefinition, createRoleCreatedEvent, createRoleDeletedEvent, createRoleModifiedEvent, createSettingValueHolder, createTokenChangedEvent, createTokenCreatedEvent, createTokenRemovedEvent, createUserCreatedEvent, createUserDeletedEvent, createUserModifiedEvent, createUserStateChangedEvent, denyResult, dimensionConfig, fieldFilterConfig, filterResult, fromJwtUser, getActionIds, getDataAccessActions, getDefinitionDescription, hasAction, hasPermissionForResources, mergeResults, ownCreatedConfig, scopeConfig };