@stone-js/starters 0.8.3

package/full-service-imperative/app/services/SecurityService.ts

@@ -0,0 +1,224 @@
+import bcrypt from 'bcryptjs'
+import jwt from 'jsonwebtoken'
+import { ISessionService } from './contracts/ISessionService'
+import { ISecurityService } from './contracts/ISecurityService'
+import { BadCredentialsError } from '../errors/CredentialsError'
+import { IUserRepository } from '../repositories/contracts/IUserRepository'
+import { defineService, IBlueprint, isEmpty, isNotEmpty } from '@stone-js/core'
+import { BadRequestError, IncomingHttpEvent, UnauthorizedError } from '@stone-js/http-core'
+import { UserLogin, UserToken, UserRegister, UserChangePassword, UserModel, UserTokenPayload } from '../models/User'
+
+/**
+ * Security Service Options
+*/
+export interface SecurityServiceOptions {
+  blueprint: IBlueprint
+  userRepository: IUserRepository
+  sessionService: ISessionService
+}
+
+/**
+ * Factory Security Service
+*/
+export function factorySecurityService ({ blueprint, userRepository, sessionService }: SecurityServiceOptions): ISecurityService {
+  return {
+    /**
+     * Login a user
+     *
+     * @param credentials - The user to login
+     * @returns The user token
+    */
+    async login (event: IncomingHttpEvent, credentials: UserLogin): Promise<UserToken> {
+      const user = await userRepository.findBy(credentials)
+
+      if (isEmpty(user)) {
+        throw new BadCredentialsError(`The user with email ${credentials.email} does not exist`)
+      }
+
+      if (!(await this.comparePassword(credentials.password, user.password))) {
+        throw new BadCredentialsError('Invalid user password')
+      }
+
+      return {
+        tokenType: 'bearer',
+        expiresIn: blueprint.get<number>('security.jwt.expiresIn', 3600),
+        accessToken: await this.generateToken(user, event.ip, event.userAgent)
+      }
+    },
+
+    /**
+     * Refresh a token
+     *
+     * @param token - The token to refresh
+    */
+    async refresh (token: string): Promise<UserToken> {
+      const payload = this.verifyToken(token)
+      const user = await userRepository.findById(payload.user.id)
+
+      if (isEmpty(user)) {
+        throw new UnauthorizedError('User not found')
+      }
+
+      return {
+        tokenType: 'bearer',
+        expiresIn: blueprint.get<number>('security.jwt.expiresIn', 3600),
+        accessToken: await this.generateToken(user, payload.session.ip, payload.session.userAgent ?? undefined)
+      }
+    },
+
+    /**
+     * Logout a user
+     *
+     * @param token - The token to logout
+    */
+    async logout (token: string): Promise<void> {
+      const payload = this.verifyToken(token)
+      await sessionService.close(payload.session)
+    },
+
+    /**
+     * Authenticate a user
+     *
+     * @param token - The token to authenticate
+     * @returns The authenticated user
+    */
+    async authenticate (token: string, ip: string, userAgent?: string): Promise<UserModel> {
+      const payload = this.verifyToken(token)
+      const user = await userRepository.findById(payload.user.id)
+
+      if (payload.session.ip !== ip) {
+        throw new UnauthorizedError('Invalid IP address')
+      } else if (payload.session.userAgent !== userAgent) {
+        throw new UnauthorizedError('Invalid user agent')
+      } else if (isEmpty(user)) {
+        throw new UnauthorizedError('User not found')
+      }
+
+      await sessionService.updateLastActivity(payload.session)
+
+      return user
+    },
+
+    /**
+     * Hashes a password before storing it in the database.
+     *
+     * @param password - The plaintext password.
+     * @returns The hashed password.
+     */
+    async hashPassword (password: string): Promise<string> {
+      return await bcrypt.hash(password, blueprint.get<number>('security.bcrypt.saltRounds', 10))
+    },
+
+    /**
+     * Compares a plaintext password with a hashed password.
+     *
+     * @param password - The plaintext password.
+     * @param hashedPassword - The stored hashed password.
+     * @returns `true` if the password matches, otherwise `false`.
+     */
+    async comparePassword (password: string, hashedPassword?: string | null): Promise<boolean> {
+      return await bcrypt.compare(password, hashedPassword ?? '')
+    },
+
+    /**
+     * Generates a JWT token for a user.
+     *
+     * @param user - The user information to include in the token.
+     * @returns The generated JWT token.
+     */
+    async generateToken (user: UserModel, ip: string, userAgent?: string): Promise<string> {
+      let session = await sessionService.getLatest(user)
+
+      if (
+        isEmpty(session) ||
+        session?.ip !== ip ||
+        isNotEmpty(session.closedAt) ||
+        session?.userAgent !== userAgent
+      ) {
+        session = await sessionService.createForUser(user, ip, userAgent)
+      } else {
+        session = await sessionService.extend(
+          session,
+          blueprint.get<number>('security.jwt.expiresIn', 3600)
+        )
+      }
+
+      return jwt.sign(
+        {
+          user: {
+            ...user,
+            password: undefined
+          },
+          session
+        },
+        blueprint.get<string>('security.secret', 'secret'),
+        blueprint.get<jwt.SignOptions>('security.jwt')
+      )
+    },
+
+    /**
+     * Verifies a JWT token and returns the decoded payload.
+     *
+     * @param token - The JWT token to verify.
+     * @returns The decoded user payload or null if invalid.
+     */
+    verifyToken (token: string): UserTokenPayload {
+      try {
+        return jwt.verify(
+          token,
+          blueprint.get<string>('security.secret', 'secret')
+        ) as UserTokenPayload
+      } catch (error: any) {
+        throw new UnauthorizedError('Invalid token', { cause: error })
+      }
+    },
+
+    /**
+     * Register a user
+     *
+     * @param user - The user to register
+    */
+    async register (payload: UserRegister): Promise<void> {
+      const user = await userRepository.findBy({ email: payload.email })
+
+      if (isNotEmpty(user)) {
+        throw new BadRequestError(`The user with email ${payload.email} already exists`)
+      }
+
+      const password = await this.hashPassword(payload.password)
+
+      await userRepository.create({
+        ...payload,
+        password,
+        updatedAt: Date.now(),
+        createdAt: Date.now()
+      })
+    },
+
+    /**
+     * Change the user password
+     *
+     * @param user - The user to change the password
+     * @param password - The password to change
+    */
+    async changePassword (user?: UserModel, password?: UserChangePassword): Promise<void> {
+      if (isEmpty(user)) {
+        throw new UnauthorizedError('User not found')
+      }
+
+      if (isEmpty(password) || !(await this.comparePassword(password.password, user.password))) {
+        throw new UnauthorizedError('Invalid user password')
+      }
+
+      await userRepository.update(user.id, { password: password.newPassword })
+    }
+  }
+}
+
+/**
+ * Security Service
+ *
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+ */
+export const SecurityService = defineService(factorySecurityService, { isFactory: true, singleton: true, alias: 'securityService' })

package/full-service-imperative/app/services/SessionService.ts

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto'
+import { UserModel } from '../models/User'
+import { Session } from '../models/Session'
+import { defineService } from '@stone-js/core'
+import { ISessionService } from './contracts/ISessionService'
+import { ISessionRepository } from '../repositories/contracts/ISessionRepository'
+
+/**
+ * Session Service Options
+ */
+export interface SessionServiceOptions {
+  sessionRepository: ISessionRepository
+}
+
+/**
+ * Factory Session Service
+*/
+export function factorySessionService ({ sessionRepository }: SessionServiceOptions): ISessionService {
+  return {
+    /**
+     * Finds all sessions.
+     *
+     * @param limit - The limit of sessions to list
+     * @returns The list of sessions
+     */
+    async list (limit: number): Promise<Session[]> {
+      return await sessionRepository.list(limit)
+    },
+
+    /**
+     * Finds a sessions by user.
+     *
+     * @param user - The user to look up
+     * @param limit - The limit of sessions to list
+     * @returns The list of sessions
+     */
+    async getByUser (user: UserModel, limit: number): Promise<Session[]> {
+      return await sessionRepository.listByUser(user, limit)
+    },
+
+    /**
+     * Finds a session by ID.
+     *
+     * @param sessionId - The session ID to look up
+     * @returns The session data or `undefined` if not found
+     */
+    async getById (id: number): Promise<Session | undefined> {
+      return await sessionRepository.findById(id)
+    },
+
+    /**
+     * Finds the latest session of a user.
+     *
+     * @param user - The user to look up
+     * @returns The latest session or `undefined` if not found
+     */
+    async getLatest (user: UserModel): Promise<Session | undefined> {
+      return await sessionRepository.getLatest(user)
+    },
+
+    /**
+     * Creates a new session for a user.
+     *
+     * @param user - The user to create the session for
+     * @param ip - The IP address of the user
+     * @param userAgent - The user agent of the user
+     * @returns The created session
+    */
+    async createForUser (user: UserModel, ip: string, userAgent?: string): Promise<Session> {
+      const session = {
+        ip,
+        userAgent,
+        userId: user.id,
+        createdAt: Date.now(),
+        uuid: randomUUID(),
+        lastActivityAt: Date.now(),
+        expiresAt: Date.now() + 3600
+      }
+
+      return await sessionRepository.create(session)
+    },
+
+    /**
+     * Updates the last activity timestamp of a session.
+     *
+     * @param sessionId - The session ID to update
+     * @returns `true` if the session was updated, otherwise `false`
+     */
+    async updateLastActivity (session: Session): Promise<void> {
+      await sessionRepository.update(session.id, { lastActivityAt: Date.now() })
+    },
+
+    /**
+     * Extends a session expiration time.
+     *
+     * @param sessionId - The session ID to extend
+     * @param additionalTime - Additional time in milliseconds
+     * @returns `true` if the session was extended, otherwise `false`
+     */
+    async extend (session: Session, additionalTime: number): Promise<Session> {
+      session.expiresAt = Date.now() + additionalTime
+      await sessionRepository.update(session.id, session)
+      return session
+    },
+
+    /**
+     * Closes a session.
+     *
+     * @param sessionId - The session ID to close
+     */
+    async close (session: Session): Promise<void> {
+      session.closedAt = Date.now()
+      await sessionRepository.update(session.id, session)
+    }
+  }
+}
+
+/**
+ * Session Service
+ *
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+ */
+export const SessionService = defineService(factorySessionService, { isFactory: true, singleton: true, alias: 'sessionService' })

package/full-service-imperative/app/services/UserService.ts

@@ -0,0 +1,105 @@
+import { UserModel } from '../models/User'
+import { UserEvent } from '../events/UserEvent'
+import { NotFoundError } from '@stone-js/http-core'
+import { DependencyResolver } from '@stone-js/router'
+import { IUserService } from './contracts/IUserService'
+import { defineService, EventEmitter, isNotEmpty } from '@stone-js/core'
+import { IUserRepository } from '../repositories/contracts/IUserRepository'
+
+/**
+ * User Service Options
+*/
+export interface UserServiceOptions {
+  eventEmitter: EventEmitter
+  userRepository: IUserRepository
+}
+
+/**
+ * Factory User Service
+*/
+export function factoryUserService ({ userRepository, eventEmitter }: UserServiceOptions): IUserService {
+  return {
+    /**
+     * List users
+     *
+     * @param limit - The limit of users to list
+     */
+    async list (limit: number = 10): Promise<UserModel[]> {
+      return await userRepository.list(limit)
+    },
+
+    /**
+     * Find a user
+     *
+     * @param conditions - The conditions to find the user
+     * @returns The found user
+     */
+    async findBy (conditions: Record<string, any>): Promise<UserModel> {
+      const user = await userRepository.findById(conditions.id)
+      if (isNotEmpty<UserModel>(user)) return user
+      throw new NotFoundError(`User with ID ${String(conditions.id)} not found`)
+    },
+
+    /**
+     * Find a user
+     *
+     * @param conditions - The conditions to find the user
+     * @returns The found user
+     */
+    async findByEmail (conditions: Record<string, any>): Promise<UserModel | undefined> {
+      return await userRepository.findBy(conditions)
+    },
+
+    /**
+     * Create a user
+     *
+     * @param payload - The user data to create
+     */
+    async create (payload: Omit<UserModel, 'id'>): Promise<bigint | undefined> {
+      await eventEmitter.emit(new UserEvent(payload))
+      return await userRepository.create({ ...payload, createdAt: Date.now(), updatedAt: Date.now() })
+    },
+
+    /**
+     * Update a user
+     *
+     * @param id - The id of the user to update
+     * @param payload - The user data to update
+     * @returns The updated user
+     */
+    async update (id: number, payload: UserModel): Promise<UserModel> {
+      const user = await userRepository.update(id, payload)
+      if (isNotEmpty<UserModel>(user)) return user
+      throw new NotFoundError(`User with ID ${id} not found`)
+    },
+
+    /**
+     * Delete a user
+     *
+     * @param id - The id of the user to delete
+     */
+    async delete (id: number): Promise<boolean> {
+      return await userRepository.delete(id)
+    }
+  }
+}
+
+/**
+ * Resolve route binding
+ *
+ * @param key - The key of the binding
+ * @param value - The value of the binding
+ * @param container - The container
+ */
+export async function userResolveRouteBinding (key: string, value: any, container?: DependencyResolver): Promise<UserModel | undefined> {
+  const userService = container?.resolve<IUserService>('userService')
+  return await userService?.findBy({ [key]: value })
+}
+
+/**
+ * User Service
+ *
+ * The alias is required to get benefits of desctructuring Dependency Injection.
+ * And because the front-end class will be minified, we need to use alias to keep the class name.
+ */
+export const UserService = defineService(factoryUserService, { isFactory: true, singleton: true, alias: 'userService' })

package/full-service-imperative/app/services/contracts/ICommentService.ts

@@ -0,0 +1,62 @@
+import { Comment, CommentModel } from '../../models/Comment'
+
+/**
+ * Comment Service contract
+ */
+export interface ICommentService {
+  /**
+   * List comments.
+   *
+   * @param limit - The limit of comments to list.
+   */
+  list: (limit?: number) => Promise<Comment[]>
+
+  /**
+   * Retrieve comments for a specific post.
+   *
+   * @param postId - The post ID.
+   * @param limit - The number of comments to retrieve.
+   */
+  listByPost: (postId: number, limit?: number) => Promise<Comment[]>
+
+  /**
+   * Retrieve comments by a specific user.
+   *
+   * @param authorId - The author ID.
+   * @param limit - The number of comments to retrieve.
+   */
+  listByAuthor: (authorId: number, limit?: number) => Promise<Comment[]>
+
+  /**
+   * Find a comment by ID.
+   *
+   * @param id - The ID of the comment.
+   * @returns The found comment.
+   * @throws NotFoundError if comment is not found.
+   */
+  findById: (id: number) => Promise<Comment>
+
+  /**
+   * Create a new comment.
+   *
+   * @param payload - The comment data to create.
+   */
+  create: (payload: Omit<CommentModel, 'id'>) => Promise<bigint | undefined>
+
+  /**
+   * Update an existing comment.
+   *
+   * @param id - The ID of the comment.
+   * @param payload - The comment data to update.
+   * @returns The updated comment.
+   * @throws NotFoundError if comment is not found.
+   */
+  update: (id: number, payload: Partial<CommentModel>) => Promise<Comment>
+
+  /**
+   * Delete a comment.
+   *
+   * @param id - The ID of the comment.
+   */
+  delete: (id: number) => Promise<boolean>
+}

package/full-service-imperative/app/services/contracts/IPostService.ts

@@ -0,0 +1,53 @@
+import { Post, PostCreateModel, PostModel } from '../../models/Post'
+
+/**
+ * Post Service contract
+ */
+export interface IPostService {
+  /**
+   * List posts.
+   *
+   * @param limit - The limit of posts to list.
+   */
+  list: (limit?: number) => Promise<Post[]>
+
+  /**
+   * Retrieve posts by a specific user.
+   *
+   * @param authorId - The author ID.
+   * @param limit - The number of posts to retrieve.
+   */
+  listByAuthor: (authorId: number, limit?: number) => Promise<Post[]>
+
+  /**
+   * Find a post by ID.
+   *
+   * @param id - The ID of the post.
+   * @returns The found post.
+   * @throws NotFoundError if post is not found.
+   */
+  findById: (id: number) => Promise<Post>
+
+  /**
+   * Create a new post.
+   *
+   * @param payload - The post data to create.
+   */
+  create: (payload: Omit<PostCreateModel, 'id'>) => Promise<bigint | undefined>
+
+  /**
+   * Update an existing post.
+   *
+   * @param id - The ID of the post.
+   * @param payload - The post data to update.
+   * @returns `true` if the update was successful.
+   */
+  update: (id: number, payload: Partial<PostModel>) => Promise<boolean>
+
+  /**
+   * Delete a post.
+   *
+   * @param id - The ID of the post.
+   */
+  delete: (id: number) => Promise<boolean>
+}

package/full-service-imperative/app/services/contracts/ISecurityService.ts

@@ -0,0 +1,97 @@
+import { IncomingHttpEvent } from '@stone-js/http-core'
+import { UserLogin, UserToken, UserModel, UserTokenPayload, UserRegister, UserChangePassword } from '../../models/User'
+
+/**
+ * Security Service contract
+ */
+export interface ISecurityService {
+  /**
+   * Logs in a user and returns a JWT token.
+   *
+   * @param event - The incoming HTTP event containing IP and user agent.
+   * @param credentials - The user's email and password.
+   * @returns The user token.
+   * @throws BadCredentialsError if credentials are invalid.
+   */
+  login: (event: IncomingHttpEvent, credentials: UserLogin) => Promise<UserToken>
+
+  /**
+   * Refreshes an access token using a valid existing token.
+   *
+   * @param token - The current JWT token.
+   * @returns The refreshed user token.
+   * @throws UnauthorizedError if the token is invalid or user not found.
+   */
+  refresh: (token: string) => Promise<UserToken>
+
+  /**
+   * Logs out a user by closing the associated session.
+   *
+   * @param token - The JWT token of the user session.
+   */
+  logout: (token: string) => Promise<void>
+
+  /**
+   * Authenticates a user based on a token, IP, and user agent.
+   *
+   * @param token - The JWT token to verify.
+   * @param ip - The IP address of the request.
+   * @param userAgent - Optional user agent string.
+   * @returns The authenticated user.
+   * @throws UnauthorizedError if token or session info is invalid.
+   */
+  authenticate: (token: string, ip: string, userAgent?: string) => Promise<UserModel>
+
+  /**
+   * Hashes a plaintext password using bcrypt.
+   *
+   * @param password - The plaintext password.
+   * @returns The hashed password.
+   */
+  hashPassword: (password: string) => Promise<string>
+
+  /**
+   * Compares a plaintext password with a hashed one.
+   *
+   * @param password - The plaintext password.
+   * @param hashedPassword - The hashed password.
+   * @returns `true` if the password matches, `false` otherwise.
+   */
+  comparePassword: (password: string, hashedPassword?: string | null) => Promise<boolean>
+
+  /**
+   * Generates a signed JWT token for a user and session.
+   *
+   * @param user - The user to generate a token for.
+   * @param ip - The IP address of the request.
+   * @param userAgent - Optional user agent.
+   * @returns The generated JWT token string.
+   */
+  generateToken: (user: UserModel, ip: string, userAgent?: string) => Promise<string>
+
+  /**
+   * Verifies a JWT token and returns the payload.
+   *
+   * @param token - The JWT token to verify.
+   * @returns The decoded payload.
+   * @throws UnauthorizedError if the token is invalid.
+   */
+  verifyToken: (token: string) => UserTokenPayload
+
+  /**
+   * Registers a new user.
+   *
+   * @param payload - The user registration data.
+   * @throws BadRequestError if the email is already in use.
+   */
+  register: (payload: UserRegister) => Promise<void>
+
+  /**
+   * Changes the password of a user.
+   *
+   * @param user - The user whose password is being changed.
+   * @param password - The old and new passwords.
+   * @throws UnauthorizedError if validation fails.
+   */
+  changePassword: (user?: UserModel, password?: UserChangePassword) => Promise<void>
+}