najm-auth 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,1466 @@
+import * as najm_core from 'najm-core';
+import { ValidationPluginConfig } from 'najm-validation';
+import { RateLimitPluginConfig } from 'najm-rate';
+import { I18nService } from 'najm-i18n';
+import { EmailService } from 'najm-email';
+import { TDb, SeedEntry } from 'najm-database';
+import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, RolePermission } from './schema/pg.js';
+export { NewRolePermission, NewToken, Token, authSchema, baseFields, permissionsTable, rolePermissionsTable, rolesTable, tokensTable, usersTable } from './schema/pg.js';
+import { CacheService } from 'najm-cache';
+import { z } from 'zod';
+import { GuardResult } from 'najm-guard';
+import 'drizzle-orm';
+import 'drizzle-orm/pg-core';
+
+/**
+ * JWT configuration for token generation and verification
+ */
+interface JwtConfig {
+    /** Secret key for access token signing */
+    accessSecret: string;
+    /** Access token expiration time (e.g., '15m', '1h') */
+    accessExpiresIn: string;
+    /** Secret key for refresh token signing */
+    refreshSecret: string;
+    /** Refresh token expiration time (e.g., '7d', '30d') */
+    refreshExpiresIn: string;
+}
+/**
+ * Complete auth plugin configuration (internal)
+ */
+interface AuthConfig {
+    /** JWT configuration */
+    jwt: JwtConfig;
+    /** Refresh token cookie name (default: 'refreshToken') */
+    refreshCookieName: string;
+    /** Database name to use (default: 'default') */
+    database: string;
+    /** Cache key prefix for blacklist (default: 'auth:blacklist:') */
+    blacklistPrefix: string;
+    /** Default role name for new user registration (default: null - no role assigned) */
+    defaultRole: string | null;
+}
+/**
+ * Auth plugin configuration options
+ * Cache is provided by najm-cache plugin (auto-dependency)
+ */
+/**
+ * Auth schema shape (dialect-agnostic)
+ * Import from 'najm-auth/pg', 'najm-auth/sqlite', or 'najm-auth/mysql'
+ */
+interface AuthSchema {
+    users: any;
+    tokens: any;
+    roles: any;
+    permissions: any;
+    rolePermissions: any;
+}
+type AuthPluginConfig = {
+    /** Database dialect (default: 'pg'). Auto-selects the correct schema. */
+    dialect?: 'pg' | 'sqlite' | 'mysql';
+    /** Database schema tables (optional, overrides dialect). Use authSchema from 'najm-auth/sqlite' or 'najm-auth/mysql' */
+    schema?: AuthSchema;
+    /** JWT configuration (secrets can be set via env vars) */
+    jwt?: Partial<JwtConfig>;
+    /** Refresh token cookie name (default: 'refreshToken') */
+    refreshCookieName?: string;
+    /** Database name to use (default: 'default') */
+    database?: string;
+    /** Cache key prefix for blacklist (default: 'auth:blacklist:') */
+    blacklistPrefix?: string;
+    /** Default role name for new user registration (default: null - no role assigned). Set to 'user' for auto-assignment. */
+    defaultRole?: string | null;
+    /** Optional config forwarded to validation() dependency */
+    validation?: ValidationPluginConfig;
+    /** Optional config forwarded to rateLimit() dependency */
+    rateLimit?: RateLimitPluginConfig;
+};
+/**
+ * JWT payload structure
+ */
+interface JwtPayload {
+    userId: string;
+    /** Unique token ID for blacklist-based revocation */
+    jti: string;
+    exp?: number;
+    iat?: number;
+}
+/**
+ * Token pair returned after authentication
+ */
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiresAt?: number;
+    refreshTokenExpiresAt?: number;
+}
+/**
+ * User data structure for authentication
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    role?: string;
+    permissions?: string[];
+}
+
+declare const auth$1: (config?: AuthPluginConfig) => najm_core.NajmPlugin;
+
+declare const AUTH_CONFIG: unique symbol;
+declare const AUTH_SCHEMA: unique symbol;
+declare const AUTH_USER: unique symbol;
+declare const AUTH_ROLE: unique symbol;
+declare const AUTH_PERMISSIONS: unique symbol;
+
+var auth = {
+	errors: {
+		invalidCredentials: "Invalid email or password",
+		emailExists: "Email already registered",
+		accessDenied: "Access denied",
+		tokenExpired: "Token has expired",
+		tokenInvalid: "Invalid token",
+		tokenMissing: "Authorization token is missing",
+		tokenVerificationFailed: "Token verification failed",
+		tokenRevoked: "Token has been revoked",
+		refreshTokenMissing: "Refresh token is missing",
+		refreshTokenInvalid: "Invalid refresh token",
+		invalidResetToken: "Invalid password reset token",
+		resetTokenExpired: "Password reset token has expired",
+		unauthorized: "Unauthorized access",
+		sessionExpired: "Session has expired"
+	},
+	success: {
+		login: "Login successful",
+		logout: "Logout successful",
+		passwordChanged: "Password changed successfully",
+		tokenRefreshed: "Token refreshed successfully"
+	}
+};
+var users = {
+	errors: {
+		notFound: "User not found",
+		idExists: "User ID already exists",
+		emailRequired: "Email is required",
+		passwordRequired: "Password is required",
+		invalidEmail: "Invalid email format",
+		weakPassword: "Password is too weak",
+		adminRoleNotFound: "Admin role not found in system"
+	},
+	success: {
+		created: "User created successfully",
+		updated: "User updated successfully",
+		deleted: "User deleted successfully",
+		retrieved: "User retrieved successfully"
+	}
+};
+var roles = {
+	errors: {
+		notFound: "Role not found",
+		exists: "Role already exists",
+		nameRequired: "Role name is required",
+		cannotDeleteSystem: "Cannot delete system role"
+	},
+	success: {
+		created: "Role created successfully",
+		updated: "Role updated successfully",
+		deleted: "Role deleted successfully",
+		assigned: "Role assigned successfully",
+		retrieved: "Role retrieved successfully"
+	}
+};
+var permissions = {
+	errors: {
+		notFound: "Permission not found",
+		nameExists: "Permission name already exists",
+		roleAlreadyHasPermission: "Role already has this permission",
+		cannotRemoveRequired: "Cannot remove required permission"
+	},
+	success: {
+		created: "Permission created successfully",
+		updated: "Permission updated successfully",
+		deleted: "Permission deleted successfully",
+		granted: "Permission granted successfully",
+		revoked: "Permission revoked successfully",
+		retrieved: "Permissions retrieved successfully",
+		assigned: "Permission assigned to role successfully",
+		removed: "Permission removed from role successfully",
+		allDeleted: "All permissions deleted successfully"
+	}
+};
+var en = {
+	auth: auth,
+	users: users,
+	roles: roles,
+	permissions: permissions
+};
+
+/**
+ * Default auth translations organized by language
+ * Can be imported and merged with user translations
+ */
+declare const AUTH_LOCALES: {
+    readonly en: {
+        auth: {
+            errors: {
+                invalidCredentials: string;
+                emailExists: string;
+                accessDenied: string;
+                tokenExpired: string;
+                tokenInvalid: string;
+                tokenMissing: string;
+                tokenVerificationFailed: string;
+                tokenRevoked: string;
+                refreshTokenMissing: string;
+                refreshTokenInvalid: string;
+                invalidResetToken: string;
+                resetTokenExpired: string;
+                unauthorized: string;
+                sessionExpired: string;
+            };
+            success: {
+                login: string;
+                logout: string;
+                passwordChanged: string;
+                tokenRefreshed: string;
+            };
+        };
+        users: {
+            errors: {
+                notFound: string;
+                idExists: string;
+                emailRequired: string;
+                passwordRequired: string;
+                invalidEmail: string;
+                weakPassword: string;
+                adminRoleNotFound: string;
+            };
+            success: {
+                created: string;
+                updated: string;
+                deleted: string;
+                retrieved: string;
+            };
+        };
+        roles: {
+            errors: {
+                notFound: string;
+                exists: string;
+                nameRequired: string;
+                cannotDeleteSystem: string;
+            };
+            success: {
+                created: string;
+                updated: string;
+                deleted: string;
+                assigned: string;
+                retrieved: string;
+            };
+        };
+        permissions: {
+            errors: {
+                notFound: string;
+                nameExists: string;
+                roleAlreadyHasPermission: string;
+                cannotRemoveRequired: string;
+            };
+            success: {
+                created: string;
+                updated: string;
+                deleted: string;
+                granted: string;
+                revoked: string;
+                retrieved: string;
+                assigned: string;
+                removed: string;
+                allDeleted: string;
+            };
+        };
+    };
+};
+/**
+ * Get translations for a specific language
+ * Falls back to English if language not found
+ */
+declare function getAuthLocale(lang: string): Record<string, any>;
+/**
+ * All supported languages in auth package
+ */
+declare const AUTH_SUPPORTED_LANGUAGES: string[];
+
+/**
+ * EncryptionService - Pure hashing utility
+ * Validation is handled by UserValidator (single source of truth)
+ */
+declare class EncryptionService {
+    constructor();
+    hashPassword(password: string): Promise<string>;
+    comparePassword(password: string, hashedPassword: string): Promise<boolean>;
+}
+
+declare class CookieManager {
+    private config;
+    private cookieService;
+    private get cookieName();
+    setRefreshToken(refreshToken: string): void;
+    clearRefreshToken(): void;
+    getRefreshToken(): string | undefined;
+    hasRefreshToken(): boolean;
+    getCookieName(): string;
+}
+
+interface UserWithPermissions extends Omit<User, 'password'> {
+    role?: string | null;
+    permissions: string[];
+}
+declare class UserRepository {
+    db: TDb;
+    private schema;
+    private get users();
+    private get roles();
+    /** Shared query helper */
+    private get q();
+    getAll(): Promise<UserWithPermissions[]>;
+    getById(id: string): Promise<UserWithPermissions | undefined>;
+    getByEmail(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
+    create(data: NewUser): Promise<User>;
+    update(id: string, data: Partial<NewUser>): Promise<User>;
+    delete(id: string): Promise<User>;
+    deleteAll(): Promise<User[]>;
+    getRoleNameById(userId: string): Promise<string | null>;
+    getUserPassword(email: string): Promise<string | undefined>;
+    getUserPermissions(userId: string): Promise<string[]>;
+}
+
+/**
+ * UserValidator - Business validation for user operations
+ * Handles database checks (unique, exists, permissions)
+ * Schema validation is handled by DTOs in user.dto.ts
+ */
+declare class UserValidator {
+    private userRepository;
+    private encryptionService;
+    private t;
+    constructor(userRepository: UserRepository, encryptionService: EncryptionService);
+    /**
+     * Check if email already exists in database
+     */
+    checkEmailUnique(email: string, excludeId?: string): Promise<void>;
+    /**
+     * Check if user exists by ID
+     */
+    checkUserExists(id: string): Promise<UserWithPermissions>;
+    /**
+     * Check if user exists by email
+     */
+    checkUserExistsByEmail(email: string): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        email: string;
+        emailVerified: boolean;
+        password: string;
+        image: string;
+        status: "active" | "inactive" | "pending";
+        roleId: string;
+        lastLogin: string;
+    } & {
+        role?: string | null;
+    }>;
+    /**
+     * Check if email exists in database
+     */
+    checkEmailExists(email: string): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        email: string;
+        emailVerified: boolean;
+        password: string;
+        image: string;
+        status: "active" | "inactive" | "pending";
+        roleId: string;
+        lastLogin: string;
+    } & {
+        role?: string | null;
+    }>;
+    /**
+     * Verify password against hashed password (throws on invalid)
+     */
+    checkPasswordValid(password: string, hashedPassword: string): Promise<void>;
+    /**
+     * Compare password against hash - returns boolean (no throw)
+     * Used for timing-safe authentication
+     */
+    comparePassword(password: string, hashedPassword: string): Promise<boolean>;
+    /**
+     * Check if user ID is unique (for custom IDs)
+     */
+    checkUserIdIsUnique(id: string): Promise<void>;
+    /**
+     * Check if user has required role
+     */
+    hasRole(userId: string, roles: string[]): Promise<boolean>;
+    /**
+     * Validate password strength and complexity
+     * Enforces:
+     * - Minimum 8 characters
+     * - At least one uppercase letter
+     * - At least one lowercase letter
+     * - At least one number
+     */
+    validatePasswordStrength(password: string): void;
+}
+
+declare class RoleRepository {
+    db: TDb;
+    private schema;
+    private get roles();
+    getAll(): Promise<RoleEntity[]>;
+    getById(id: string): Promise<RoleEntity | undefined>;
+    getByName(name: string): Promise<RoleEntity | undefined>;
+    create(data: NewRoleEntity): Promise<RoleEntity>;
+    update(id: string, data: Partial<NewRoleEntity>): Promise<RoleEntity>;
+    delete(id: string): Promise<RoleEntity>;
+}
+
+/**
+ * RoleValidator - Business validation for role operations
+ * Handles database checks (unique, exists)
+ * Schema validation is handled by DTOs in role.dto.ts
+ */
+declare class RoleValidator {
+    private roleRepository;
+    private t;
+    constructor(roleRepository: RoleRepository);
+    /**
+     * Check if role name is unique
+     */
+    checkNameUnique(roleName: string, excludeId?: string): Promise<void>;
+    /**
+     * Check if role exists by ID
+     */
+    checkRoleExists(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if role exists by name
+     */
+    checkRoleExistsByName(roleName: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if admin role exists (required for system setup)
+     */
+    checkAdminRoleExists(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if role name exists (returns boolean, doesn't throw)
+     */
+    isRoleNameExists(roleName: string): Promise<boolean>;
+}
+
+declare class RoleService {
+    private roleRepository;
+    private roleValidator;
+    constructor(roleRepository: RoleRepository, roleValidator: RoleValidator);
+    getAll(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    getById(id: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    getByName(name: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    create(data: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    update(id: any, data: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    delete(id: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    seedDefaultRoles(defaultRoles: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    getRoleIdByName(name: any): Promise<string>;
+}
+
+type SanitizedUser = Omit<User, 'password'> & {
+    role?: string | null;
+    permissions?: string[];
+};
+declare class UserService {
+    private roleValidator;
+    private roleService;
+    private userRepository;
+    private userValidator;
+    private encryptionService;
+    private i18nService;
+    private authConfig;
+    constructor(roleValidator: RoleValidator, roleService: RoleService, userRepository: UserRepository, userValidator: UserValidator, encryptionService: EncryptionService, i18nService: I18nService, authConfig: AuthConfig);
+    private sanitizeUser;
+    private sanitizeUsers;
+    private resolveUserRole;
+    getAll(): Promise<SanitizedUser[]>;
+    getById(id: string): Promise<SanitizedUser>;
+    getByEmail(email: string): Promise<SanitizedUser>;
+    /**
+     * Find user by email without throwing - returns null if not found
+     * Used for timing-safe authentication
+     */
+    findByEmail(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
+    create(data: Record<string, any>): Promise<SanitizedUser>;
+    update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
+    delete(id: string): Promise<SanitizedUser>;
+    deleteAll(): Promise<SanitizedUser[]>;
+    getRoleName(id: string): Promise<string | null>;
+    getPassword(email: string): Promise<string | undefined>;
+    assignRole(id: string, roleId?: string, roleName?: string): Promise<SanitizedUser>;
+    removeRole(id: string): Promise<SanitizedUser>;
+    seedAdminUser(config?: {
+        email?: string;
+        password?: string;
+        name?: string;
+    }): Promise<SanitizedUser>;
+    updateLang(language: string): Promise<string>;
+    getLang(): Promise<string>;
+}
+
+declare class TokenRepository {
+    db: TDb;
+    private schema;
+    private get tokens();
+    private get users();
+    private get roles();
+    /** Shared query helper */
+    private get q();
+    storeRefreshToken(tokenData: {
+        userId: string;
+        token: string;
+        expiresAt: string;
+    }): Promise<any>;
+    getRefreshToken(userId: string): Promise<any>;
+    revokeToken(userId: string): Promise<any>;
+    isUserExists(userId: string): Promise<boolean>;
+    getRoleNameById(userId: string): Promise<string>;
+    getUserPermissions(userId: string): Promise<string[]>;
+    getUser(userId: string): Promise<any>;
+}
+
+declare class TokenService {
+    private tokenRepository;
+    private cookieManager;
+    private cache;
+    private config;
+    private t;
+    constructor(tokenRepository: TokenRepository, cookieManager: CookieManager, cache: CacheService);
+    /**
+     * Get blacklist key prefix
+     */
+    private get blacklistPrefix();
+    extractAccessToken(authorization: string): string;
+    /**
+     * Verify access token and check blacklist
+     * Throws error if token is invalid, expired, or blacklisted
+     */
+    verifyAccessToken(token: string): Promise<JwtPayload>;
+    verifyRefreshToken(token: string): string;
+    getUser(auth: string): Promise<any>;
+    getTokenExpire(token: string): number | undefined;
+    /**
+     * Generate access token with unique jti for blacklist support
+     */
+    generateAccessToken(data: {
+        userId: string;
+    }): string;
+    /**
+     * Generate refresh token with unique jti
+     */
+    generateRefreshToken(data: {
+        userId: string;
+    }): string;
+    generateTokens(userId: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+        accessTokenExpiresAt: number;
+        refreshTokenExpiresAt: number;
+    }>;
+    /**
+     * Blacklist an access token by its jti
+     * Token will be rejected until it naturally expires
+     */
+    blacklistToken(jti: string, expiresInSeconds: number): Promise<void>;
+    /**
+     * Check if a token is blacklisted
+     */
+    isTokenBlacklisted(jti: string): Promise<boolean>;
+    /**
+     * Blacklist the current access token (for logout)
+     * Extracts jti and remaining TTL from the token
+     */
+    blacklistCurrentToken(token: string): Promise<void>;
+    /**
+     * Store hashed refresh token in database for security
+     * This prevents token theft in case of database breach
+     */
+    storeRefreshToken(userId: string, refreshToken: string): Promise<void>;
+    /**
+     * Refresh tokens with secure token comparison
+     * Compares provided token with hashed version in database
+     */
+    refreshTokens(): Promise<{
+        accessToken: string;
+        refreshToken: string;
+        accessTokenExpiresAt: number;
+        refreshTokenExpiresAt: number;
+    }>;
+    revokeToken(userId: string): Promise<any>;
+    /**
+     * Logout user - blacklist access token and revoke refresh token
+     */
+    logout(userId: string, authorization?: string): Promise<void>;
+    /**
+     * Generate secure password reset token
+     * Returns both the plain token (to send via email) and userId for identification
+     */
+    generateResetToken(userId: string): {
+        token: string;
+        userId: string;
+    };
+    /**
+     * Verify password reset token
+     * Returns userId if valid, throws error if expired/invalid
+     */
+    verifyResetToken(token: string): string;
+}
+
+declare const createUserDto: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    roleId: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<File, File>]>>;
+    emailVerified: z.ZodDefault<z.ZodBoolean>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        pending: "pending";
+    }>>;
+}, z.core.$strip>;
+declare const updateUserDto: z.ZodObject<{
+    email: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    roleId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    image: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<File, File>]>>>;
+    emailVerified: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    status: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        inactive: "inactive";
+        pending: "pending";
+    }>>>;
+}, z.core.$strip>;
+declare const userIdParam: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const loginDto: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+declare const changePasswordDto: z.ZodObject<{
+    currentPassword: z.ZodString;
+    newPassword: z.ZodString;
+}, z.core.$strip>;
+declare const resetPasswordDto: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+declare const confirmResetPasswordDto: z.ZodObject<{
+    token: z.ZodString;
+    newPassword: z.ZodString;
+}, z.core.$strip>;
+declare const languageParam: z.ZodObject<{
+    language: z.ZodString;
+}, z.core.$strip>;
+declare const emailParam: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+declare const userIdInParam: z.ZodObject<{
+    userId: z.ZodString;
+}, z.core.$strip>;
+declare const assignRoleParams: z.ZodObject<{
+    userId: z.ZodString;
+    roleId: z.ZodString;
+}, z.core.$strip>;
+type CreateUserDto = z.infer<typeof createUserDto>;
+type UpdateUserDto = z.infer<typeof updateUserDto>;
+type UserIdParam = z.infer<typeof userIdParam>;
+type LoginDto = z.infer<typeof loginDto>;
+type ChangePasswordDto = z.infer<typeof changePasswordDto>;
+type ResetPasswordDto = z.infer<typeof resetPasswordDto>;
+type ConfirmResetPasswordDto = z.infer<typeof confirmResetPasswordDto>;
+type LanguageParam = z.infer<typeof languageParam>;
+type EmailParam = z.infer<typeof emailParam>;
+type UserIdInParam = z.infer<typeof userIdInParam>;
+type AssignRoleParams = z.infer<typeof assignRoleParams>;
+
+declare class AuthService {
+    private tokenService;
+    private userService;
+    private userValidator;
+    private cookieManager;
+    private i18nService;
+    private emailService;
+    private t;
+    private logger;
+    private static readonly DUMMY_HASH;
+    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
+    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    loginUser(body: LoginDto): Promise<TokenPair>;
+    refreshTokens(): Promise<TokenPair>;
+    logoutUser(userId: string, authorization?: string): Promise<{
+        data: any;
+        message: string;
+    }>;
+    getUserProfile(userData: AuthUser): Promise<AuthUser & {
+        language: string;
+    }>;
+    forgotPassword(email: string): Promise<{
+        message: string;
+    }>;
+    resetPassword(token: string, newPassword: string): Promise<{
+        message: string;
+    }>;
+}
+
+declare class AuthController {
+    private authService;
+    constructor(authService: AuthService);
+    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    loginUser(body: LoginDto): Promise<TokenPair>;
+    refreshTokens(): Promise<TokenPair>;
+    logoutUser(userId: string, authorization?: string): Promise<{
+        data: any;
+        message: string;
+    }>;
+    userProfile(user: any): Promise<AuthUser & {
+        language: string;
+    }>;
+    forgotPassword(body: ResetPasswordDto): Promise<{
+        message: string;
+    }>;
+    resetPassword(body: ConfirmResetPasswordDto): Promise<{
+        message: string;
+    }>;
+}
+
+declare class AuthGuard {
+    private tokenService;
+    canActivate(auth: string): Promise<GuardResult | false>;
+}
+declare const isAuth: () => ClassDecorator & MethodDecorator;
+
+declare const AUTH_MODULE: readonly [typeof AuthService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController];
+
+declare class PermissionRepository {
+    db: TDb;
+    private schema;
+    private get permissions();
+    private get rolePermissions();
+    private get roles();
+    getAll(): Promise<Permission[]>;
+    getById(id: string): Promise<Permission | undefined>;
+    getByName(name: string): Promise<Permission | undefined>;
+    getByResource(resource: string): Promise<Permission[]>;
+    create(data: NewPermission): Promise<Permission>;
+    update(id: string, data: Partial<NewPermission>): Promise<Permission>;
+    delete(id: string): Promise<Permission>;
+    getPermissionsByRole(roleId: string): Promise<Array<Pick<Permission, 'id' | 'name' | 'description' | 'resource' | 'action'>>>;
+    getRolesByPermission(permissionId: string): Promise<Array<Pick<RoleEntity, 'id' | 'name' | 'description'>>>;
+    assignPermissionToRole(roleId: string, permissionId: string): Promise<RolePermission>;
+    removePermissionFromRole(roleId: string, permissionId: string): Promise<RolePermission>;
+    checkRoleHasPermission(roleId: string, permissionId: string): Promise<boolean>;
+    deleteAll(): Promise<Permission[]>;
+}
+
+declare class PermissionGuard {
+    canActivate(requiredPermission: string, permissions: string[]): GuardResult | false;
+    private checkPermission;
+}
+declare const Can: (permission: string) => ClassDecorator & MethodDecorator;
+declare const canCreate: (resource: string) => ClassDecorator & MethodDecorator;
+declare const canRead: (resource: string) => ClassDecorator & MethodDecorator;
+declare const canUpdate: (resource: string) => ClassDecorator & MethodDecorator;
+declare const canDelete: (resource: string) => ClassDecorator & MethodDecorator;
+declare const canManage: (resource: string) => ClassDecorator & MethodDecorator;
+
+declare const ROLES: {
+    readonly ADMIN: "admin";
+};
+declare const ROLE_GROUPS: {
+    ADMINISTRATORS: "admin"[];
+};
+type RoleType = typeof ROLES[keyof typeof ROLES];
+type RoleInput = string | string[];
+
+declare class RoleGuard {
+    canActivate(allowedRoles: RoleInput, userRole: string): false | {
+        role: string;
+    };
+}
+declare const Role: (roles: RoleInput) => any;
+declare const isAdmin: () => ClassDecorator & MethodDecorator;
+declare const isAdministrator: () => ClassDecorator & MethodDecorator;
+
+declare const createRoleDto: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const updateRoleDto: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+declare const roleIdParam: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const assignRoleDto: z.ZodObject<{
+    userId: z.ZodString;
+    roleId: z.ZodString;
+}, z.core.$strip>;
+type CreateRoleDto = z.infer<typeof createRoleDto>;
+type UpdateRoleDto = z.infer<typeof updateRoleDto>;
+type RoleIdParam = z.infer<typeof roleIdParam>;
+type AssignRoleDto = z.infer<typeof assignRoleDto>;
+
+declare class RoleController {
+    private roleService;
+    constructor(roleService: RoleService);
+    getRoles(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    getRole(params: RoleIdParam): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    createRole(body: CreateRoleDto): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    updateRole(params: RoleIdParam, body: UpdateRoleDto): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    deleteRole(params: RoleIdParam): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+}
+
+/**
+ * PermissionValidator - Business validation for permission operations
+ * Handles database checks (unique, exists, role permissions)
+ * Schema validation is handled by DTOs in permission.dto.ts
+ */
+declare class PermissionValidator {
+    private permissionRepository;
+    private roleValidator;
+    private t;
+    constructor(permissionRepository: PermissionRepository, roleValidator: RoleValidator);
+    /**
+     * Check if permission exists by ID
+     */
+    checkPermissionExists(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    /**
+     * Check if permission exists by name
+     */
+    checkPermissionExistsByName(name: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    /**
+     * Check if permission name is unique
+     */
+    checkPermissionNameUnique(name: string, excludeId?: string): Promise<void>;
+    /**
+     * Check if role exists (delegates to RoleValidator)
+     */
+    checkRoleExists(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if role exists by name (delegates to RoleValidator)
+     */
+    checkRoleExistsByName(name: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if role already has permission
+     */
+    checkRoleHasPermission(roleId: string, permissionId: string): Promise<void>;
+}
+
+declare class PermissionService {
+    private permissionRepository;
+    private permissionValidator;
+    private roleService;
+    constructor(permissionRepository: PermissionRepository, permissionValidator: PermissionValidator, roleService: RoleService);
+    getAll(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }[]>;
+    getById(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    getByName(name: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    getByResource(resource: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }[]>;
+    create(data: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    update(id: string, data: any): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    delete(id: string): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    getPermissionsByRole(roleId: string): Promise<Pick<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }, "id" | "name" | "description" | "resource" | "action">[]>;
+    getRolesByPermission(permissionId: string): Promise<Pick<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }, "id" | "name" | "description">[]>;
+    assignPermissionToRole(roleId: string, permissionId: string): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        roleId: string;
+        permissionId: string;
+    }>;
+    removePermissionFromRole(roleId: string, permissionId: string): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        roleId: string;
+        permissionId: string;
+    }>;
+    seedDefaultPermissions(defaultPermissions: any): Promise<{
+        created: any[];
+        skipped: any[];
+    }>;
+    seedDefaultRolePermissions(defaultRolePermissions: any): Promise<{
+        assigned: any[];
+        skipped: any[];
+    }>;
+    deleteAll(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }[]>;
+}
+
+declare const createPermissionDto: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    resource: z.ZodString;
+    action: z.ZodString;
+}, z.core.$strip>;
+declare const updatePermissionDto: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    resource: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const permissionIdParam: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const assignPermissionDto: z.ZodObject<{
+    roleId: z.ZodString;
+    permissionId: z.ZodString;
+}, z.core.$strip>;
+declare const checkPermissionDto: z.ZodObject<{
+    userId: z.ZodString;
+    resource: z.ZodString;
+    action: z.ZodString;
+}, z.core.$strip>;
+type CreatePermissionDto = z.infer<typeof createPermissionDto>;
+type UpdatePermissionDto = z.infer<typeof updatePermissionDto>;
+type PermissionIdParam = z.infer<typeof permissionIdParam>;
+type AssignPermissionDto = z.infer<typeof assignPermissionDto>;
+type CheckPermissionDto = z.infer<typeof checkPermissionDto>;
+
+declare class PermissionController {
+    private permissionService;
+    constructor(permissionService: PermissionService);
+    getPermissions(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }[]>;
+    getPermission(params: PermissionIdParam): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    create(body: CreatePermissionDto): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    update(params: PermissionIdParam, body: UpdatePermissionDto): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    delete(params: PermissionIdParam): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }>;
+    getByRole(params: RoleIdParam): Promise<Pick<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }, "id" | "name" | "description" | "resource" | "action">[]>;
+    getRolesByPermission(params: PermissionIdParam): Promise<Pick<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+    }, "id" | "name" | "description">[]>;
+    assignToRole(params: AssignPermissionDto): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        roleId: string;
+        permissionId: string;
+    }>;
+    removeFromRole(params: AssignPermissionDto): Promise<{
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        roleId: string;
+        permissionId: string;
+    }>;
+    deleteAll(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        createdAt: string;
+        updatedAt: string;
+        resource: string;
+        action: string;
+    }[]>;
+}
+
+/**
+ * Shared query builders used across auth repositories.
+ * Eliminates duplication between UserRepository and TokenRepository.
+ */
+declare class AuthQueries {
+    private db;
+    private schema;
+    constructor(db: any, schema: AuthSchema);
+    /**
+     * Standard user selection fields with role join
+     */
+    userSelection(): {
+        id: any;
+        email: any;
+        emailVerified: any;
+        image: any;
+        status: any;
+        roleId: any;
+        role: any;
+        createdAt: any;
+        updatedAt: any;
+    };
+    /**
+     * Get permissions for a user by their userId
+     */
+    getUserPermissions(userId: string): Promise<string[]>;
+    /**
+     * Get role name for a user
+     */
+    getRoleName(userId: string): Promise<string | null>;
+    /**
+     * Batch load permissions for multiple users (fixes N+1 query problem)
+     * Returns a Map of roleId -> permissions[]
+     */
+    batchLoadPermissionsByRole(): Promise<Map<string, string[]>>;
+}
+
+declare const avatarsPath: string;
+declare const parseSchema: (schema: any, data: any) => Promise<any>;
+declare const clean: (obj: any) => any;
+declare const getAvatarFile: (fileName: any) => Promise<File>;
+declare const formatDate: (dateValue: any) => string;
+declare function calculateAge(dateOfBirth: any): number;
+declare function calculateYearsOfExperience(hireDate: any): number;
+declare function pickProps<T>(source: T, keys: any): Partial<T>;
+declare const isEmpty: any;
+declare const isPath: (img: any) => boolean;
+declare const isFile: (img: any) => boolean;
+
+declare const createTokenDto: z.ZodObject<{
+    userId: z.ZodString;
+    token: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        access: "access";
+        refresh: "refresh";
+    }>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+        expired: "expired";
+    }>>;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+declare const updateTokenDto: z.ZodObject<{
+    status: z.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+        expired: "expired";
+    }>;
+}, z.core.$strip>;
+declare const tokenIdParam: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const verifyTokenDto: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strip>;
+declare const refreshTokenDto: z.ZodObject<{
+    refreshToken: z.ZodString;
+}, z.core.$strip>;
+declare const revokeTokenDto: z.ZodObject<{
+    userId: z.ZodString;
+}, z.core.$strip>;
+type CreateTokenDto = z.infer<typeof createTokenDto>;
+type UpdateTokenDto = z.infer<typeof updateTokenDto>;
+type TokenIdParam = z.infer<typeof tokenIdParam>;
+type VerifyTokenDto = z.infer<typeof verifyTokenDto>;
+type RefreshTokenDto = z.infer<typeof refreshTokenDto>;
+type RevokeTokenDto = z.infer<typeof revokeTokenDto>;
+
+declare class UserController {
+    private userService;
+    constructor(userService: UserService);
+    getUsers(): Promise<SanitizedUser[]>;
+    getLang(): Promise<{
+        language: string;
+    }>;
+    updateLang(params: LanguageParam): Promise<string>;
+    getUser(params: UserIdParam): Promise<SanitizedUser>;
+    getByEmail(params: EmailParam): Promise<SanitizedUser>;
+    getRole(params: UserIdInParam): Promise<string>;
+    create(body: CreateUserDto): Promise<SanitizedUser>;
+    update(params: UserIdParam, body: UpdateUserDto): Promise<SanitizedUser>;
+    delete(params: UserIdParam): Promise<SanitizedUser>;
+    deleteAll(): Promise<SanitizedUser[]>;
+    assignRole(params: AssignRoleParams): Promise<SanitizedUser>;
+    removeRole(params: UserIdInParam): Promise<SanitizedUser>;
+}
+
+declare const USER_STATUS: readonly ["active", "inactive", "pending"];
+declare const TOKEN_STATUS: readonly ["active", "revoked", "expired"];
+declare const TOKEN_TYPE: readonly ["access", "refresh"];
+
+/**
+ * Shared user configuration for seeding
+ */
+interface SeedUserConfig {
+    email: string;
+    password: string;
+    roleName: string;
+    emailVerified?: boolean;
+    status?: 'active' | 'inactive' | 'pending';
+    image?: string;
+    username?: string;
+}
+/**
+ * Low-level factory config (for use with SeedService)
+ */
+interface AuthSeedConfig {
+    adminEmail: string;
+    adminPass: string;
+    roles?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    permissions?: Array<{
+        action: string;
+        resource: string;
+        name: string;
+        description?: string;
+    }>;
+    additionalUsers?: SeedUserConfig[];
+}
+/**
+ * High-level standalone function config
+ */
+interface SeedAuthDataConfig {
+    /** Drizzle database instance (required) */
+    db: any;
+    /** Admin email (required) */
+    adminEmail: string;
+    /** Admin password (required) */
+    adminPassword: string;
+    /** Additional users to seed (optional) */
+    users?: SeedUserConfig[];
+    /** Custom roles (optional - uses defaults if omitted) */
+    roles?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Custom permissions (optional - uses defaults if omitted) */
+    permissions?: Array<{
+        action: string;
+        resource: string;
+        name: string;
+        description?: string;
+    }>;
+    /** Show verbose logging (optional) */
+    verbose?: boolean;
+    /** Conflict handling strategy (optional) */
+    onConflict?: 'skip' | 'replace' | 'fail';
+}
+/**
+ * Result of seedAuthData operation
+ */
+interface SeedAuthDataResult {
+    inserted: number;
+    skipped: number;
+    failed: number;
+    users: Array<{
+        id: string;
+        email: string;
+        roleId: string;
+    }>;
+    roles: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+
+/**
+ * Composable seed definition factory for najm-auth plugin.
+ *
+ * Provides default roles, permissions, and admin user with proper validation and password hashing.
+ *
+ * @example
+ * ```typescript
+ * const seeder = server.container.get(SeedService);
+ *
+ * await seeder.run({
+ *   ...authSeed({ adminEmail: 'admin@test.com', adminPass: 'Admin123!' }),
+ *   // ... your app-specific seeds
+ * });
+ * ```
+ */
+declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
+
+/**
+ * Standalone function to seed authentication data.
+ * Handles Server setup, seeding, and cleanup automatically.
+ *
+ * @example
+ * ```typescript
+ * // In a seed script
+ * import { seedAuthData } from 'najm-auth';
+ * import { db } from './database';
+ *
+ * await seedAuthData({
+ *   db,
+ *   adminEmail: 'admin@app.com',
+ *   adminPassword: 'Secret123!',
+ *   users: [
+ *     { email: 'user@app.com', password: 'User123!', roleName: 'user' }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a service method
+ * @Service()
+ * class SetupService {
+ *   async seedDefaultData() {
+ *     await seedAuthData({
+ *       db: this.db,
+ *       adminEmail: process.env.ADMIN_EMAIL!,
+ *       adminPassword: process.env.ADMIN_PASSWORD!,
+ *       verbose: true
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
+
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, type ChangePasswordDto, type CheckPermissionDto, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type SanitizedUser, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, canCreate, canDelete, canManage, canRead, canUpdate, changePasswordDto, checkPermissionDto, clean, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, languageParam, loginDto, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto };