@ackplus/nest-auth 0.1.51 → 1.1.1

package/src/lib/admin-console/dto/login.dto.ts

@@ -0,0 +1,10 @@
+import { IsEmail, IsNotEmpty, IsString } from 'class-validator';
+
+export class AdminLoginDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @IsNotEmpty()
+  password: string;
+}

package/src/lib/admin-console/dto/reset-password.dto.ts

@@ -0,0 +1,21 @@
+import { IsEmail, IsNotEmpty, IsString, Matches, MinLength } from 'class-validator';
+
+export class AdminResetPasswordDto {
+    @IsString()
+    @IsEmail()
+    @IsNotEmpty()
+    email: string;
+
+    @IsString()
+    @IsNotEmpty()
+    secretKey: string;
+
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    @Matches(
+        /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
+        { message: 'Password must contain uppercase, lowercase, number, and special character' }
+    )
+    newPassword: string;
+}

package/src/lib/admin-console/dto/setup-admin.dto.ts

@@ -0,0 +1,23 @@
+import { IsEmail, IsNotEmpty, IsOptional, IsString, Matches, MinLength } from 'class-validator';
+
+export class AdminSetupDto {
+  @IsString()
+  @IsNotEmpty()
+  setupKey: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(8)
+  @Matches(
+    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
+    { message: 'Password must contain uppercase, lowercase, number, and special character' }
+  )
+  password: string;
+
+  @IsOptional()
+  @IsString()
+  name?: string;
+}

package/src/lib/admin-console/dto/signup.dto.ts

@@ -0,0 +1,51 @@
+import { IsEmail, IsNotEmpty, IsOptional, IsString, Matches, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AdminSignupDto {
+    @ApiProperty({
+        description: 'Admin email address',
+        example: 'admin@example.com'
+    })
+    @IsEmail()
+    @IsNotEmpty()
+    email: string;
+
+    @ApiProperty({
+        description: 'Admin password (minimum 8 characters, must contain uppercase, lowercase, number, and special character)',
+        example: 'SecurePassword123!',
+        minLength: 8
+    })
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    @Matches(
+        /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
+        { message: 'Password must contain uppercase, lowercase, number, and special character' }
+    )
+    password: string;
+
+    @ApiProperty({
+        description: 'Secret key for authorization (provided in module configuration)',
+        example: 'your-secret-key'
+    })
+    @IsString()
+    @IsNotEmpty()
+    secretKey: string;
+
+    @ApiProperty({
+        description: 'Admin name (optional)',
+        required: false,
+        example: 'Admin User'
+    })
+    @IsOptional()
+    @IsString()
+    name?: string;
+
+    @ApiProperty({
+        description: 'Additional metadata for the admin user (optional)',
+        required: false,
+        example: { department: 'IT', role: 'super-admin' }
+    })
+    @IsOptional()
+    metadata?: Record<string, any>;
+}

package/src/lib/admin-console/entities/admin-user.entity.ts

@@ -0,0 +1,74 @@
+import {
+  BaseEntity,
+  BeforeInsert,
+  BeforeUpdate,
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import * as argon2 from 'argon2';
+
+@Entity('nest_auth_admin_users')
+export class AdminUser extends BaseEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ unique: true })
+  @Index()
+  email: string;
+
+  @Column({ nullable: true })
+  name?: string;
+
+  @Column()
+  passwordHash: string;
+
+  @Column({ type: 'simple-json', nullable: true, default: '{}' })
+  metadata?: Record<string, any>;
+
+  @Column({ type: 'datetime', nullable: true })
+  lastLoginAt?: Date;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @BeforeInsert()
+  normalizeEmail() {
+    if (this.email) {
+      this.email = this.email.toLowerCase();
+    }
+  }
+
+  @BeforeUpdate()
+  normalizeEmailOnUpdate() {
+    if (this.email) {
+      this.email = this.email.toLowerCase();
+    }
+  }
+
+  async setPassword(password: string): Promise<void> {
+    this.passwordHash = await argon2.hash(password, {
+      type: argon2.argon2id,
+      memoryCost: 65536,
+      timeCost: 3,
+      parallelism: 4,
+    });
+  }
+
+  async validatePassword(password: string): Promise<boolean> {
+    if (!this.passwordHash) {
+      return false;
+    }
+    try {
+      return await argon2.verify(this.passwordHash, password);
+    } catch {
+      return false;
+    }
+  }
+}

package/src/lib/admin-console/guards/admin-session.guard.ts

@@ -0,0 +1,47 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { AdminSessionService } from '../services/admin-session.service';
+import { AdminUserService } from '../services/admin-user.service';
+import { AdminConsoleConfigService } from '../services/admin-console-config.service';
+import { AdminUser } from '../entities/admin-user.entity';
+
+export interface AdminRequest extends Request {
+  adminUser?: AdminUser;
+}
+
+@Injectable()
+export class AdminSessionGuard implements CanActivate {
+  constructor(
+    private readonly sessions: AdminSessionService,
+    private readonly adminUsers: AdminUserService,
+    private readonly config: AdminConsoleConfigService,
+  ) { }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const req = context.switchToHttp().getRequest<AdminRequest>();
+    this.config.ensureEnabled();
+
+    const token = this.sessions.extractToken(req);
+    if (!token) {
+      throw new UnauthorizedException('Admin authentication required');
+    }
+
+    const payload = this.sessions.verifySession(token);
+    if (!payload) {
+      throw new UnauthorizedException('Invalid admin session');
+    }
+
+    const admin = await this.adminUsers.findById(payload.sub);
+    if (!admin) {
+      throw new UnauthorizedException('Admin account not found');
+    }
+
+    req.adminUser = admin;
+    return true;
+  }
+}

package/src/lib/admin-console/services/admin-auth.service.ts

@@ -0,0 +1,82 @@
+import { Injectable, UnauthorizedException, BadRequestException } from '@nestjs/common';
+import { AdminUserService } from './admin-user.service';
+import { AdminSessionService } from './admin-session.service';
+import { AdminConsoleConfigService } from './admin-console-config.service';
+import { AdminUser } from '../entities/admin-user.entity';
+import { DebugLoggerService } from '../../core/services/debug-logger.service';
+import { compareKeys } from '../../utils/security.util';
+
+@Injectable()
+export class AdminAuthService {
+  constructor(
+    private readonly adminUsers: AdminUserService,
+    private readonly sessions: AdminSessionService,
+    private readonly config: AdminConsoleConfigService,
+    private readonly debugLogger: DebugLoggerService,
+  ) { }
+
+  async validateCredentials(email: string, password: string): Promise<AdminUser> {
+    const admin = await this.adminUsers.findByEmail(email);
+    if (!admin) {
+      throw new UnauthorizedException('Invalid credentials');
+    }
+    const valid = await admin.validatePassword(password);
+    if (!valid) {
+      throw new UnauthorizedException('Invalid credentials');
+    }
+    admin.lastLoginAt = new Date();
+    await admin.save();
+    return admin;
+  }
+
+  async createInitialAdmin(payload: {
+    setupKey: string;
+    email: string;
+    password: string;
+    name?: string;
+    metadata?: Record<string, any>;
+  }): Promise<AdminUser> {
+    this.config.ensureEnabled();
+    const configuredKey = this.config.getSecretKey();
+
+    if (!configuredKey) {
+      throw new BadRequestException({
+        message: 'Admin console setup key is not configured.',
+        code: 'ADMIN_CONSOLE_SETUP_DISABLED',
+      });
+    }
+
+    // Use constant-time comparison to prevent timing attacks
+    if (!compareKeys(payload.setupKey, configuredKey)) {
+      throw new UnauthorizedException({
+        message: 'Invalid admin console setup key.',
+        code: 'INVALID_ADMIN_CONSOLE_SETUP_KEY',
+      });
+    }
+
+    const existingAdmins = await this.adminUsers.listAdmins();
+    if (existingAdmins.length > 0) {
+      throw new BadRequestException({
+        message: 'Admin users already exist. Use the dashboard to manage administrators.',
+        code: 'ADMIN_USERS_ALREADY_INITIALIZED',
+      });
+    }
+
+    // Mask email to avoid logging PII
+    const maskedEmail = payload.email.replace(/(.{2})(.*)(@.*)/, '$1****$3');
+    this.debugLogger.info('Creating initial admin console user', 'AdminAuthService', {
+      email: maskedEmail,
+    });
+
+    return this.adminUsers.createAdmin({
+      email: payload.email,
+      password: payload.password,
+      name: payload.name,
+      metadata: payload.metadata,
+    });
+  }
+
+  createSession(admin: AdminUser): string {
+    return this.sessions.createSession(admin);
+  }
+}

package/src/lib/admin-console/services/admin-console-config.service.ts

@@ -0,0 +1,62 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { AuthConfigService } from '../../core/services/auth-config.service';
+import { AdminConsoleOptions } from '../../core/interfaces/auth-module-options.interface';
+import { CookieOptions } from 'express';
+
+@Injectable()
+export class AdminConsoleConfigService {
+  constructor(private readonly authConfig: AuthConfigService) { }
+
+  get options(): AdminConsoleOptions {
+    return this.authConfig.getConfig().adminConsole ?? ({} as AdminConsoleOptions);
+  }
+
+  ensureEnabled(): void {
+    if (this.options?.enabled === false) {
+      throw new NotFoundException('Admin console is disabled');
+    }
+  }
+
+  getCookieName(): string {
+    return this.options?.sessionCookieName ?? 'nest_auth_admin';
+  }
+
+  getBasePath(): string {
+    return this.options?.basePath;
+  }
+
+  getSessionSecret(): string {
+    // Use secretKey for session signing - unified key for all admin console security operations
+    return this.options?.secretKey ?? 'change-me-admin-secret';
+  }
+
+  getSessionDuration(): string | number {
+    return this.options?.sessionDuration ?? '2h';
+  }
+
+  getCookieOptions(): CookieOptions {
+    // Determine secure flag based on environment
+    const secureDefault = process.env.NODE_ENV === 'production';
+
+    const base: CookieOptions = {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: secureDefault,
+      path: this.getBasePath(),
+    };
+
+    return {
+      ...base,
+      ...(this.options?.cookie ?? {}),
+      path: this.options?.cookie?.path ?? base.path,
+    };
+  }
+
+  allowAdminManagement(): boolean {
+    return this.options?.allowAdminManagement !== false;
+  }
+
+  getSecretKey(): string | undefined {
+    return this.options?.secretKey;
+  }
+}

package/src/lib/admin-console/services/admin-session.service.ts

@@ -0,0 +1,106 @@
+import { Injectable } from '@nestjs/common';
+import { Request } from 'express';
+import * as jwt from 'jsonwebtoken';
+import ms from 'ms';
+import { AdminConsoleConfigService } from './admin-console-config.service';
+import { AdminUser } from '../entities/admin-user.entity';
+
+interface AdminSessionPayload {
+  sub: string;
+  email: string;
+  iat: number;
+  exp: number;
+}
+
+@Injectable()
+export class AdminSessionService {
+  constructor(private readonly config: AdminConsoleConfigService) { }
+
+  createSession(admin: AdminUser): string {
+    const secret = this.config.getSessionSecret();
+    const duration = this.config.getSessionDuration();
+    const expiresIn = typeof duration === 'number' ? duration : duration || '2h';
+    return jwt.sign(
+      {
+        sub: admin.id,
+        email: admin.email,
+      },
+      secret,
+      {
+        expiresIn,
+      },
+    );
+  }
+
+  verifySession(token: string): AdminSessionPayload | null {
+    if (!token) {
+      return null;
+    }
+    try {
+      return jwt.verify(token, this.config.getSessionSecret()) as AdminSessionPayload;
+    } catch (error) {
+      // Log JWT verification failures for security monitoring
+      console.warn('JWT verification failed:', error.message);
+      return null;
+    }
+  }
+
+  getCookieName(): string {
+    return this.config.getCookieName();
+  }
+
+  getMaxAge(): number | undefined {
+    const duration = this.config.getSessionDuration();
+    if (typeof duration === 'number') {
+      return duration * 1000;
+    }
+    if (typeof duration === 'string') {
+      return ms(duration);
+    }
+    return ms('2h');
+  }
+
+  extractToken(request: Request): string | undefined {
+    const cookieName = this.getCookieName();
+    const cookieHeader = request.headers?.cookie;
+
+    if (request.cookies && request.cookies[cookieName]) {
+      return request.cookies[cookieName];
+    }
+
+    if (!cookieHeader) {
+      return undefined;
+    }
+
+    const cookies = this.parseCookieHeader(cookieHeader);
+    return cookies[cookieName];
+  }
+
+  /**
+   * Invalidate all sessions for a given admin user.
+   * Since we're using stateless JWT tokens, this is a no-op for now,
+   * but provides a hook for future stateful session implementations.
+   */
+  async invalidateSessionForAdmin(adminId: string): Promise<void> {
+    // With JWT-based stateless sessions, we can't revoke tokens server-side
+    // This method exists for future implementations that use database-backed sessions
+    // For now, clearing the client cookie in the logout handler is sufficient
+    return Promise.resolve();
+  }
+
+  private parseCookieHeader(header: string): Record<string, string> {
+    return header.split(';').reduce<Record<string, string>>((acc, part) => {
+      const [key, ...rest] = part.split('=');
+      if (!key) {
+        return acc;
+      }
+      try {
+        acc[key.trim()] = decodeURIComponent(rest.join('=').trim());
+      } catch (error) {
+        // If decoding fails, use the raw value
+        acc[key.trim()] = rest.join('=').trim();
+      }
+      return acc;
+    }, {});
+  }
+}

package/src/lib/admin-console/services/admin-user.service.ts

@@ -0,0 +1,96 @@
+import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { AdminUser } from '../entities/admin-user.entity';
+import { DebugLoggerService } from '../../core/services/debug-logger.service';
+
+@Injectable()
+export class AdminUserService {
+  constructor(
+    @InjectRepository(AdminUser)
+    private readonly adminRepo: Repository<AdminUser>,
+    private readonly debugLogger: DebugLoggerService,
+  ) {}
+
+  async createAdmin(data: {
+    email: string;
+    password: string;
+    name?: string;
+    metadata?: Record<string, any>;
+  }): Promise<AdminUser> {
+    const email = data.email.toLowerCase();
+    const existing = await this.adminRepo.findOne({ where: { email } });
+    if (existing) {
+      throw new ConflictException({
+        message: `Admin user with email ${email} already exists.`,
+        code: 'ADMIN_USER_EXISTS',
+      });
+    }
+
+    const admin = this.adminRepo.create({
+      email,
+      name: data.name,
+      metadata: data.metadata ?? {},
+    });
+    await admin.setPassword(data.password);
+    this.debugLogger.debug('Creating admin user', 'AdminUserService', { email });
+    await this.adminRepo.save(admin);
+    this.debugLogger.info('Admin user created', 'AdminUserService', { id: admin.id, email });
+    return admin;
+  }
+
+  async findByEmail(email: string): Promise<AdminUser | null> {
+    if (!email) {
+      return null;
+    }
+    return this.adminRepo.findOne({ where: { email: email.toLowerCase() } });
+  }
+
+  async findById(id: string): Promise<AdminUser | null> {
+    if (!id) {
+      return null;
+    }
+    return this.adminRepo.findOne({ where: { id } });
+  }
+
+  async listAdmins(): Promise<AdminUser[]> {
+    return this.adminRepo.find({ order: { createdAt: 'DESC' } });
+  }
+
+  async updateAdmin(
+    id: string,
+    data: { name?: string; password?: string; metadata?: Record<string, any> },
+  ): Promise<AdminUser> {
+    const admin = await this.findById(id);
+    if (!admin) {
+      throw new NotFoundException({
+        message: `Admin user with ID ${id} not found`,
+        code: 'ADMIN_USER_NOT_FOUND',
+      });
+    }
+
+    if (data.name !== undefined) {
+      admin.name = data.name;
+    }
+    if (data.metadata !== undefined) {
+      admin.metadata = data.metadata;
+    }
+    if (data.password) {
+      await admin.setPassword(data.password);
+    }
+
+    await this.adminRepo.save(admin);
+    return admin;
+  }
+
+  async deleteAdmin(id: string): Promise<void> {
+    const admin = await this.findById(id);
+    if (!admin) {
+      throw new NotFoundException({
+        message: `Admin user with ID ${id} not found`,
+        code: 'ADMIN_USER_NOT_FOUND',
+      });
+    }
+    await this.adminRepo.delete(id);
+  }
+}