@saulo.martins/backend-auth 1.0.2

package/src/auth.service.ts

@@ -0,0 +1,272 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import * as crypto from 'crypto';
+import {
+  AuthEmailServiceContract,
+  AuthUserProfile,
+  AuthUsersServiceContract
+} from './contracts';
+import { AUTH_EMAIL_SERVICE, AUTH_USERS_SERVICE } from './tokens';
+import { SignupDto } from './dto/signup.dto';
+import { LoginDto } from './dto/login.dto';
+import { ChangePasswordDto } from './dto/change-password.dto';
+import { ResetPasswordDto } from './dto/reset-password.dto';
+
+export type ProfileResponse = {
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  phoneCountryCode: string | null;
+  phoneNumber: string | null;
+  preferredLanguage: string | null;
+  isAdmin: boolean;
+  isCustomer: boolean;
+  isCompany: boolean;
+};
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code?: string
+  ) {
+    super(message);
+  }
+}
+
+function badRequest(message: string, code?: string): ApiError {
+  return new ApiError(400, message, code);
+}
+
+function unauthorized(message: string, code?: string): ApiError {
+  return new ApiError(401, message, code);
+}
+
+function toBaseProfile(
+  user: AuthUserProfile
+): Omit<ProfileResponse, 'isAdmin' | 'isCustomer' | 'isCompany'> {
+  return {
+    id: user.id,
+    email: user.email,
+    firstName: user.firstName ?? null,
+    lastName: user.lastName ?? null,
+    phoneCountryCode: user.phoneCountryCode ?? null,
+    phoneNumber: user.phoneNumber ?? null,
+    preferredLanguage: user.preferredLanguage ?? null
+  };
+}
+
+function isAdminFromEnv(email: string): boolean {
+  const adminEmails = (process.env.ADMIN_EMAILS ?? '')
+    .split(',')
+    .map((e) => e.trim().toLowerCase())
+    .filter(Boolean);
+  return adminEmails.length > 0 && adminEmails.includes(email.toLowerCase());
+}
+
+@Injectable()
+export class AuthService {
+  constructor(
+    @Inject(AUTH_USERS_SERVICE)
+    private readonly usersService: AuthUsersServiceContract,
+    @Inject(AUTH_EMAIL_SERVICE)
+    private readonly emailService: AuthEmailServiceContract,
+    private readonly jwtService: JwtService
+  ) {}
+
+  async signup(dto: SignupDto) {
+    const raw = dto.clientHash ?? dto.password;
+    if (!raw) {
+      throw badRequest(
+        'Send clientHash (SHA-256 of password) or password',
+        'SEND_CLIENT_HASH_OR_PASSWORD'
+      );
+    }
+    const existing = await this.usersService.findByEmail(dto.email);
+    if (existing) {
+      throw unauthorized('Email is already in use', 'EMAIL_ALREADY_IN_USE');
+    }
+    const passwordScheme = dto.clientHash ? 'sha256' : 'plain';
+    const user = await this.usersService.create({
+      email: dto.email,
+      password: raw,
+      passwordScheme,
+      firstName: dto.firstName,
+      lastName: dto.lastName,
+      phoneCountryCode: dto.phoneCountryCode,
+      phoneNumber: dto.phoneNumber
+    });
+    if (this.usersService.onSignupComplete) {
+      await this.usersService.onSignupComplete(user.id, {
+        userType: dto.userType,
+        firstName: dto.firstName,
+        lastName: dto.lastName
+      });
+    }
+    return this.buildToken(user.id, user.email);
+  }
+
+  async login(dto: LoginDto) {
+    if (!dto.clientHash && !dto.password) {
+      throw badRequest(
+        'Send clientHash or password',
+        'SEND_CLIENT_HASH_OR_PASSWORD'
+      );
+    }
+    const user = await this.usersService.findByEmail(dto.email);
+    if (!user) {
+      throw unauthorized(
+        'Invalid email or password',
+        'INVALID_EMAIL_OR_PASSWORD'
+      );
+    }
+    const scheme = user.passwordScheme ?? 'plain';
+    const valueToCompare =
+      scheme === 'sha256' ? dto.clientHash : dto.password;
+    if (!valueToCompare) {
+      throw unauthorized(
+        scheme === 'sha256'
+          ? 'Login requires clientHash (password hashed on client).'
+          : 'Resend your password for this device.',
+        'LOGIN_REQUIRES_CLIENT_HASH_OR_PASSWORD'
+      );
+    }
+    await this.usersService.verifyCredentials(dto.email, valueToCompare);
+    if (scheme === 'plain' && dto.clientHash && dto.password) {
+      await this.usersService.upgradeToClientHash(user.id, dto.clientHash);
+    }
+    return this.buildToken(user.id, user.email);
+  }
+
+  async tokenForUser(userId: string, email: string) {
+    return this.buildToken(userId, email);
+  }
+
+  async getMe(userId: string): Promise<ProfileResponse> {
+    const user = await this.usersService.findById(userId);
+    if (!user) {
+      throw unauthorized('User not found', 'USER_NOT_FOUND');
+    }
+    return this.profileWithRoles(user);
+  }
+
+  private async profileWithRoles(user: AuthUserProfile): Promise<ProfileResponse> {
+    const base = toBaseProfile(user);
+    let isCustomer = false;
+    let isCompany = false;
+    if (this.usersService.getProfileRoles) {
+      const roles = await this.usersService.getProfileRoles(user.id);
+      isCustomer = roles.isCustomer;
+      isCompany = roles.isCompany;
+    }
+    return {
+      ...base,
+      isAdmin: isAdminFromEnv(user.email),
+      isCustomer,
+      isCompany
+    };
+  }
+
+  async updatePreferredLanguage(
+    userId: string,
+    preferredLanguage: string
+  ): Promise<void> {
+    await this.usersService.updatePreferredLanguage(userId, preferredLanguage);
+  }
+
+  async changePassword(
+    userId: string,
+    dto: ChangePasswordDto
+  ): Promise<{ accessToken: string }> {
+    const user = await this.usersService.findById(userId);
+    if (!user) {
+      throw unauthorized('User not found', 'USER_NOT_FOUND');
+    }
+    const scheme = user.passwordScheme ?? 'plain';
+    const currentRaw =
+      scheme === 'sha256' ? dto.currentClientHash : dto.currentPassword;
+    const newRaw = dto.newClientHash ?? dto.newPassword;
+    if (!currentRaw || !newRaw) {
+      throw badRequest(
+        scheme === 'sha256'
+          ? 'Send currentClientHash and newClientHash'
+          : 'Send currentPassword and newPassword (or use clientHash)',
+        'SEND_CURRENT_AND_NEW_PASSWORD'
+      );
+    }
+    await this.usersService.verifyCredentials(user.email, currentRaw);
+    if (scheme === 'sha256') {
+      await this.usersService.upgradeToClientHash(userId, newRaw);
+    } else {
+      await this.usersService.setPasswordPlain(userId, newRaw);
+    }
+    return this.buildToken(userId, user.email);
+  }
+
+  async forgotPassword(email: string, frontendBaseUrl: string): Promise<{ message: string }> {
+    const user = await this.usersService.findByEmail(email);
+    if (!user) {
+      return {
+        message:
+          'If this email exists in our system, you will receive instructions to reset your password.'
+      };
+    }
+    const token = crypto.randomBytes(32).toString('hex');
+    const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
+    await this.usersService.createPasswordReset(user.id, token, expiresAt);
+
+    const baseUrl = frontendBaseUrl.replace(/\/+$/, '');
+    const resetLink = `${baseUrl}/reset-password?token=${encodeURIComponent(
+      token
+    )}`;
+    await this.emailService.sendPasswordResetEmail(user.email, resetLink);
+
+    return {
+      message:
+        'If this email exists in our system, you will receive instructions to reset your password.'
+    };
+  }
+
+  async resetPassword(dto: ResetPasswordDto): Promise<{ accessToken: string }> {
+    const record = await this.usersService.findValidPasswordReset(dto.token);
+    if (!record) {
+      throw badRequest(
+        'Invalid or expired reset token.',
+        'INVALID_OR_EXPIRED_RESET_TOKEN'
+      );
+    }
+    const user = await this.usersService.findById(record.userId);
+    if (!user) {
+      throw badRequest(
+        'User not found for this token.',
+        'USER_NOT_FOUND_FOR_TOKEN'
+      );
+    }
+
+    const raw = dto.clientHash ?? dto.password;
+    if (!raw) {
+      throw badRequest(
+        'Send clientHash (SHA-256 of password) or password.',
+        'SEND_CLIENT_HASH_OR_PASSWORD'
+      );
+    }
+
+    const passwordScheme = dto.clientHash ? 'sha256' : 'plain';
+    if (passwordScheme === 'sha256') {
+      await this.usersService.upgradeToClientHash(user.id, raw);
+    } else {
+      await this.usersService.setPasswordPlain(user.id, raw);
+    }
+    await this.usersService.markPasswordResetUsed(record.id);
+
+    return this.buildToken(user.id, user.email);
+  }
+
+  private async buildToken(userId: string, email: string) {
+    const payload = { sub: userId, email };
+    const accessToken = await this.jwtService.signAsync(payload);
+    return { accessToken };
+  }
+}
+

package/src/contracts.ts

@@ -0,0 +1,63 @@
+export type AuthUserProfile = {
+  id: string;
+  email: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  phoneCountryCode?: string | null;
+  phoneNumber?: string | null;
+  preferredLanguage?: string | null;
+  passwordScheme?: 'sha256' | 'plain' | null;
+};
+
+export type PasswordResetRecord = {
+  id: string;
+  userId: string;
+  token: string;
+  expiresAt: Date;
+  usedAt: Date | null;
+};
+
+/** Payload passed to {@link AuthUsersServiceContract.onSignupComplete} after the user row exists. */
+export type SignupFollowUpPayload = {
+  userType?: 'customer' | 'company';
+  firstName?: string;
+  lastName?: string;
+};
+
+export interface AuthUsersServiceContract {
+  findByEmail(email: string): Promise<AuthUserProfile | null>;
+  findById(id: string): Promise<AuthUserProfile | null>;
+  create(input: {
+    email: string;
+    password: string;
+    passwordScheme: 'sha256' | 'plain';
+    firstName?: string | null;
+    lastName?: string | null;
+    phoneCountryCode?: string | null;
+    phoneNumber?: string | null;
+  }): Promise<AuthUserProfile>;
+  verifyCredentials(email: string, rawPasswordOrHash: string): Promise<void>;
+  upgradeToClientHash(userId: string, clientHash: string): Promise<void>;
+  setPasswordPlain(userId: string, plainPassword: string): Promise<void>;
+  updatePreferredLanguage(userId: string, preferredLanguage: string): Promise<void>;
+  createPasswordReset(userId: string, token: string, expiresAt: Date): Promise<PasswordResetRecord>;
+  findValidPasswordReset(token: string): Promise<PasswordResetRecord | null>;
+  markPasswordResetUsed(resetId: string): Promise<void>;
+
+  /**
+   * Optional: create domain rows after signup (e.g. CustomerUser / CompanyUser).
+   * Implement in the host app when using `userType` on signup.
+   */
+  onSignupComplete?(userId: string, payload: SignupFollowUpPayload): Promise<void>;
+
+  /**
+   * Optional: resolve customer vs company flags for `/auth/me`.
+   * If omitted, both default to `false` (admin still uses `ADMIN_EMAILS`).
+   */
+  getProfileRoles?(userId: string): Promise<{ isCustomer: boolean; isCompany: boolean }>;
+}
+
+export interface AuthEmailServiceContract {
+  sendPasswordResetEmail(email: string, resetLink: string): Promise<void>;
+}
+

package/src/dto/change-password.dto.ts

@@ -0,0 +1,22 @@
+import { IsOptional, IsString, MinLength } from 'class-validator';
+
+export class ChangePasswordDto {
+  @IsOptional()
+  @IsString()
+  @MinLength(6)
+  currentPassword?: string;
+
+  @IsOptional()
+  @IsString()
+  currentClientHash?: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(6)
+  newPassword?: string;
+
+  @IsOptional()
+  @IsString()
+  newClientHash?: string;
+}
+

package/src/dto/forgot-password.dto.ts

@@ -0,0 +1,7 @@
+import { IsEmail } from 'class-validator';
+
+export class ForgotPasswordDto {
+  @IsEmail()
+  email!: string;
+}
+

package/src/dto/login.dto.ts

@@ -0,0 +1,16 @@
+import { IsEmail, IsOptional, IsString, MinLength } from 'class-validator';
+
+export class LoginDto {
+  @IsEmail()
+  email!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(6)
+  password?: string;
+
+  @IsOptional()
+  @IsString()
+  clientHash?: string;
+}
+

package/src/dto/reset-password.dto.ts

@@ -0,0 +1,16 @@
+import { IsOptional, IsString, MinLength } from 'class-validator';
+
+export class ResetPasswordDto {
+  @IsString()
+  token!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(6)
+  password?: string;
+
+  @IsOptional()
+  @IsString()
+  clientHash?: string;
+}
+

package/src/dto/signup.dto.ts

@@ -0,0 +1,37 @@
+import { IsEmail, IsIn, IsOptional, IsString, MinLength } from 'class-validator';
+
+export class SignupDto {
+  @IsEmail()
+  email!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(6)
+  password?: string;
+
+  @IsOptional()
+  @IsString()
+  clientHash?: string;
+
+  @IsOptional()
+  @IsString()
+  firstName?: string;
+
+  @IsOptional()
+  @IsString()
+  lastName?: string;
+
+  @IsOptional()
+  @IsString()
+  phoneCountryCode?: string;
+
+  @IsOptional()
+  @IsString()
+  phoneNumber?: string;
+
+  /** When set, the host app should link customer/company profile rows via `AuthUsersServiceContract.onSignupComplete`. */
+  @IsOptional()
+  @IsIn(['customer', 'company'])
+  userType?: 'customer' | 'company';
+}
+

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './auth.module';
+export * from './auth.service';
+export * from './auth.controller';
+export * from './jwt.strategy';
+export * from './jwt-optional.guard';
+export * from './contracts';
+export * from './tokens';
+export * from './dto/signup.dto';
+export * from './dto/login.dto';
+export * from './dto/forgot-password.dto';
+export * from './dto/reset-password.dto';
+export * from './dto/change-password.dto';
+

package/src/jwt-optional.guard.ts

@@ -0,0 +1,28 @@
+import { ExecutionContext, Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class JwtOptionalGuard extends AuthGuard('jwt') {
+  handleRequest<TUser = unknown>(
+    err: unknown,
+    user: unknown,
+    _info: unknown,
+    _context: ExecutionContext,
+    _status?: unknown
+  ): TUser {
+    if (err) {
+      return null as TUser;
+    }
+    return (user ?? null) as TUser;
+  }
+
+  canActivate(context: ExecutionContext) {
+    const request = context.switchToHttp().getRequest();
+    const authHeader: string | undefined = request.headers['authorization'];
+    if (!authHeader) {
+      return true;
+    }
+    return super.canActivate(context);
+  }
+}
+

package/src/jwt.strategy.ts

@@ -0,0 +1,19 @@
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor() {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: process.env.JWT_SECRET || 'dev-secret'
+    });
+  }
+
+  async validate(payload: { sub: string; email: string }) {
+    return { userId: payload.sub, email: payload.email };
+  }
+}
+

package/src/tokens.ts

@@ -0,0 +1,3 @@
+export const AUTH_USERS_SERVICE = Symbol('AUTH_USERS_SERVICE');
+export const AUTH_EMAIL_SERVICE = Symbol('AUTH_EMAIL_SERVICE');
+

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "module": "commonjs",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src"]
+}
+