create-nexwire 4.3.0 → 4.4.0

package/fastify/src/modules/auth/__tests__/resetpass.test.ts

@@ -0,0 +1,206 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/framework/facade.js", () => ({
+  db: {
+    query: { users: { findFirst: vi.fn() } },
+    transaction: vi.fn()
+  },
+  password: { hashPassword: vi.fn() }
+}));
+
+vi.mock("@/modules/auth/helpers/auth.js", () => ({
+  hashResetToken: vi.fn((t: string) => `hashed:${t}`)
+}));
+
+vi.mock("@/modules/auth/database/models/user.js", () => ({
+  users: { __table: "users", id: "users.id", email: "users.email" },
+  passwordResetTokens: {
+    __table: "passwordResetTokens",
+    email: "passwordResetTokens.email",
+    token: "passwordResetTokens.token",
+    expiresAt: "passwordResetTokens.expiresAt"
+  },
+  refreshTokens: { __table: "refreshTokens", userId: "refreshTokens.userId" }
+}));
+
+import { db, password } from "@/framework/facade.js";
+import { hashResetToken } from "@/modules/auth/helpers/auth.js";
+import { resetPasswordService } from "@/modules/auth/services/resetpassword.js";
+
+const fakeUser = { id: 1, email: "user@example.com", name: "Jane" };
+const body = {
+  email: "user@example.com",
+  token: "plain-token",
+  password: "new-secret"
+};
+
+function buildTx({ consumeRow = { id: 1 } as unknown, failOnUpdate }: { consumeRow?: unknown; failOnUpdate?: 1 | 2 } = {}) {
+  const updateCalls: { table: unknown; values: unknown; where: unknown }[] = [];
+
+  const txDeleteReturning = vi.fn((_args?: unknown) => Promise.resolve(consumeRow ? [consumeRow] : []));
+  const txDeleteWhere = vi.fn((_where: unknown) => ({
+    returning: txDeleteReturning
+  }));
+  const txDelete = vi.fn((_table: unknown) => ({ where: txDeleteWhere }));
+
+  const txUpdate = vi.fn((table: unknown) => {
+    const callIndex = updateCalls.length + 1;
+    let currentValues: unknown;
+
+    const txUpdateWhere = vi.fn((where: unknown) => {
+      updateCalls.push({ table, values: currentValues, where });
+      if (failOnUpdate === callIndex) {
+        return Promise.reject(new Error("constraint violation"));
+      }
+      return Promise.resolve(undefined);
+    });
+
+    const txUpdateSet = vi.fn((values: unknown) => {
+      currentValues = values;
+      return { where: txUpdateWhere };
+    });
+
+    return { set: txUpdateSet };
+  });
+
+  return {
+    tx: { delete: txDelete, update: txUpdate },
+    txDelete,
+    txDeleteWhere,
+    txDeleteReturning,
+    txUpdate,
+    updateCalls
+  };
+}
+
+describe("resetPasswordService.resetPassword", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(db.query.users.findFirst).mockResolvedValue(fakeUser as any);
+    vi.mocked(password.hashPassword).mockResolvedValue("hashed-new-pw" as any);
+  });
+
+  it("returns invalid_token without touching the DB when user does not exist", async () => {
+    vi.mocked(db.query.users.findFirst).mockResolvedValueOnce(undefined);
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "invalid_token",
+      message: "Invalid or expired reset token"
+    });
+    expect(db.transaction).not.toHaveBeenCalled();
+    expect(password.hashPassword).not.toHaveBeenCalled();
+  });
+
+  it("returns invalid_token when no reset token row was consumed", async () => {
+    const { tx } = buildTx({ consumeRow: null });
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "invalid_token",
+      message: "Invalid or expired reset token"
+    });
+  });
+
+  it("hashes the password BEFORE opening the transaction", async () => {
+    const callOrder: string[] = [];
+
+    vi.mocked(password.hashPassword).mockImplementationOnce(async () => {
+      callOrder.push("hashPassword");
+      return "hashed-new-pw" as any;
+    });
+
+    const { tx } = buildTx();
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => {
+      callOrder.push("transaction");
+      return fn(tx);
+    });
+
+    await resetPasswordService.resetPassword(body);
+
+    expect(callOrder).toEqual(["hashPassword", "transaction"]);
+  });
+
+  it("consumes the token by its HASHED value inside the transaction", async () => {
+    const { tx, txDelete, txDeleteWhere } = buildTx();
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    await resetPasswordService.resetPassword(body);
+
+    expect(hashResetToken).toHaveBeenCalledWith("plain-token");
+    expect(txDelete).toHaveBeenCalledTimes(1);
+
+    const whereArg = txDeleteWhere.mock.calls[0][0];
+    const serialized = JSON.stringify(whereArg);
+    expect(serialized).toContain("hashed:plain-token");
+    expect(serialized).not.toContain('"plain-token"');
+  });
+
+  it("updates password + revokes sessions inside the same transaction", async () => {
+    const { tx, updateCalls } = buildTx();
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "reset",
+      message: "Password reset successfully"
+    });
+
+    expect(updateCalls).toHaveLength(2);
+
+    expect((updateCalls[0].table as any).__table).toBe("users");
+    expect(updateCalls[0].values).toEqual({
+      password: "hashed-new-pw",
+      updatedAt: expect.any(Date)
+    });
+
+    expect((updateCalls[1].table as any).__table).toBe("refreshTokens");
+    expect(updateCalls[1].values).toEqual({ revoked: 1 });
+  });
+
+  it("returns invalid_token when the transaction fails before consuming", async () => {
+    vi.mocked(db.transaction).mockRejectedValueOnce(new Error("db down"));
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "invalid_token",
+      message: "Invalid or expired reset token"
+    });
+  });
+
+  it("stops at the failing update — second update is never attempted", async () => {
+    const { tx, updateCalls } = buildTx({ failOnUpdate: 1 });
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "invalid_token",
+      message: "Invalid or expired reset token"
+    });
+
+    expect(updateCalls).toHaveLength(1);
+    expect((updateCalls[0].table as any).__table).toBe("users");
+    expect(updateCalls.some((c) => (c.table as any).__table === "refreshTokens")).toBe(false);
+  });
+
+  it("propagates failure if the 2nd update rejects (session revocation fails)", async () => {
+    const { tx, updateCalls } = buildTx({ failOnUpdate: 2 });
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await resetPasswordService.resetPassword(body);
+
+    expect(result).toEqual({
+      kind: "invalid_token",
+      message: "Invalid or expired reset token"
+    });
+
+    expect(updateCalls).toHaveLength(2);
+    expect((updateCalls[1].table as any).__table).toBe("refreshTokens");
+  });
+});

package/fastify/src/modules/auth/__tests__/verifyemail.test.ts

@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/config/index.js", () => ({
+  authConfig: { requireEmailVerification: true }
+}));
+
+vi.mock("@/framework/facade.js", () => ({
+  db: {
+    query: { users: { findFirst: vi.fn() } },
+    transaction: vi.fn()
+  }
+}));
+
+vi.mock("@/modules/auth/helpers/auth.js", () => ({
+  hashEmailVerificationToken: vi.fn((t: string) => `hashed:${t}`)
+}));
+
+vi.mock("@/modules/auth/database/models/user.js", () => ({
+  users: { __table: "users", id: "users.id", email: "users.email" },
+  emailVerificationTokens: {
+    __table: "emailVerificationTokens",
+    email: "emailVerificationTokens.email",
+    token: "emailVerificationTokens.token",
+    expiresAt: "emailVerificationTokens.expiresAt"
+  }
+}));
+
+import { authConfig } from "@/config/index.js";
+import { db } from "@/framework/facade.js";
+import { hashEmailVerificationToken } from "@/modules/auth/helpers/auth.js";
+import { verifyEmailService } from "@/modules/auth/services/verifyemail.js";
+
+const fakeUser = { id: 1, email: "user@example.com", name: "Jane" };
+const body = { email: "user@example.com", token: "plain-verify-token" };
+
+/** The exact result the service returns for every invalid-token path. */
+const INVALID_TOKEN = {
+  kind: "invalid_token",
+  message: "Invalid or expired verification token"
+} as const;
+
+/**
+ * Build a fake tx.
+ *   - consumeRow: row returned by delete().returning(), or null for "no match"
+ *   - failOnUpdate: 1-indexed update that rejects (only one update here)
+ */
+function buildTx({ consumeRow = { id: 1 } as unknown, failOnUpdate }: { consumeRow?: unknown; failOnUpdate?: 1 } = {}) {
+  const updateCalls: { table: unknown; values: unknown; where: unknown }[] = [];
+
+  const txDeleteReturning = vi.fn((_args?: unknown) => Promise.resolve(consumeRow ? [consumeRow] : []));
+  const txDeleteWhere = vi.fn((_where: unknown) => ({
+    returning: txDeleteReturning
+  }));
+  const txDelete = vi.fn((_table: unknown) => ({ where: txDeleteWhere }));
+
+  const txUpdate = vi.fn((table: unknown) => {
+    const callIndex = updateCalls.length + 1;
+    let currentValues: unknown;
+
+    const txUpdateWhere = vi.fn((where: unknown) => {
+      updateCalls.push({ table, values: currentValues, where });
+      if (failOnUpdate === callIndex) {
+        return Promise.reject(new Error("constraint violation"));
+      }
+      return Promise.resolve(undefined);
+    });
+
+    const txUpdateSet = vi.fn((values: unknown) => {
+      currentValues = values;
+      return { where: txUpdateWhere };
+    });
+
+    return { set: txUpdateSet };
+  });
+
+  return {
+    tx: { delete: txDelete, update: txUpdate },
+    txDelete,
+    txDeleteWhere,
+    txDeleteReturning,
+    txUpdate,
+    updateCalls
+  };
+}
+
+describe("verifyEmailService.verifyEmail", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(authConfig).requireEmailVerification = true;
+    vi.mocked(db.query.users.findFirst).mockResolvedValue(fakeUser as any);
+  });
+
+  it("returns not_required without touching the DB when verification is disabled", async () => {
+    vi.mocked(authConfig).requireEmailVerification = false;
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual({
+      kind: "not_required",
+      message: "Email verification is not required"
+    });
+    expect(db.query.users.findFirst).not.toHaveBeenCalled();
+    expect(db.transaction).not.toHaveBeenCalled();
+  });
+
+  it("returns invalid_token when the user does not exist", async () => {
+    vi.mocked(db.query.users.findFirst).mockResolvedValueOnce(undefined);
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual(INVALID_TOKEN);
+    expect(db.transaction).not.toHaveBeenCalled();
+  });
+
+  it("returns invalid_token when no token row was consumed", async () => {
+    const { tx } = buildTx({ consumeRow: null });
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual(INVALID_TOKEN);
+  });
+
+  it("consumes the token by its HASHED value inside the transaction", async () => {
+    const { tx, txDelete, txDeleteWhere } = buildTx();
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    await verifyEmailService.verifyEmail(body);
+
+    expect(hashEmailVerificationToken).toHaveBeenCalledWith("plain-verify-token");
+    expect(txDelete).toHaveBeenCalledTimes(1);
+
+    const whereArg = txDeleteWhere.mock.calls[0][0];
+    const serialized = JSON.stringify(whereArg);
+    expect(serialized).toContain("hashed:plain-verify-token");
+    expect(serialized).not.toContain('"plain-verify-token"');
+  });
+
+  it("marks the user verified by id (not email) inside the transaction", async () => {
+    const { tx, updateCalls } = buildTx();
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual({
+      kind: "verified",
+      message: "Email verified successfully"
+    });
+
+    expect(updateCalls).toHaveLength(1);
+    expect((updateCalls[0].table as any).__table).toBe("users");
+
+    const values = updateCalls[0].values as {
+      emailVerifiedAt: Date;
+      updatedAt: Date;
+    };
+    expect(values.emailVerifiedAt).toBeInstanceOf(Date);
+    expect(values.updatedAt).toBeInstanceOf(Date);
+
+    // Same Date instance for both fields — proves `now` is shared
+    expect(values.emailVerifiedAt).toBe(values.updatedAt);
+  });
+
+  it("returns invalid_token when the transaction rejects", async () => {
+    vi.mocked(db.transaction).mockRejectedValueOnce(new Error("db down"));
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual(INVALID_TOKEN);
+  });
+
+  it("returns invalid_token when the update rejects inside the transaction", async () => {
+    const { tx, updateCalls } = buildTx({ failOnUpdate: 1 });
+    vi.mocked(db.transaction).mockImplementationOnce(async (fn: any) => fn(tx));
+
+    const result = await verifyEmailService.verifyEmail(body);
+
+    expect(result).toEqual(INVALID_TOKEN);
+
+    expect(updateCalls).toHaveLength(1);
+    expect((updateCalls[0].table as any).__table).toBe("users");
+  });
+});

package/fastify/src/modules/auth/controllers/auth.ts

@@ -0,0 +1,252 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { cookie, HttpStatusCodes } from "@/framework/facade.js";
+import { registerService } from "@/modules/auth/services/register.js";
+import type {
+  ForgotPasswordInput,
+  LoginInput,
+  RefreshTokenInput,
+  RegisterInput,
+  ResetPasswordInput,
+  VerifyEmailInput
+} from "@/modules/auth/types/auth.js";
+import { forgotPasswordService } from "../services/forgetpassword.js";
+import { loginService } from "../services/login.js";
+import { logoutService } from "../services/logout.js";
+import { logoutAllDevicesService } from "../services/logoutalldevices.js";
+import { meService } from "../services/me.js";
+import { refreshTokenService } from "../services/refreshtoken.js";
+import { resetPasswordService } from "../services/resetpassword.js";
+import { verifyEmailService } from "../services/verifyemail.js";
+
+type Body<T> = FastifyRequest<{ Body: T }>;
+
+/**
+ * Why: Creates a new user, issues tokens, and triggers signup side effects.
+ * When: Used on first-time account creation.
+ * Where: POST auth register route.
+ */
+export const register = async (request: Body<RegisterInput>, reply: FastifyReply) => {
+  try {
+    const result = await registerService.register(request, reply, request.body);
+
+    switch (result.kind) {
+      case "email_exists":
+        return reply.code(HttpStatusCodes.UNPROCESSABLE_ENTITY).send({ message: result.message });
+
+      case "verification_required":
+        return reply.code(HttpStatusCodes.CREATED).send({ message: result.message });
+
+      case "registered":
+        return reply.code(HttpStatusCodes.CREATED).send({
+          message: result.message,
+          data: result.data
+        });
+    }
+  } catch (error) {
+    console.error("Register error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to register user" });
+  }
+};
+
+/**
+ * Why: Authenticates user credentials and rotates active login cookies/tokens.
+ * When: Used whenever a user signs in.
+ * Where: POST auth login route.
+ */
+export const login = async (request: Body<LoginInput>, reply: FastifyReply) => {
+  try {
+    const result = await loginService.login(request, reply, request.body);
+
+    switch (result.kind) {
+      case "invalid_credentials":
+        return reply.code(HttpStatusCodes.UNAUTHORIZED).send({ message: result.message });
+
+      case "email_not_verified":
+        return reply.code(HttpStatusCodes.FORBIDDEN).send({ message: result.message });
+
+      case "logged_in":
+        return reply.code(HttpStatusCodes.OK).send({
+          message: result.message,
+          data: result.data
+        });
+    }
+  } catch (error) {
+    console.error("Login error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to login" });
+  }
+};
+
+/**
+ * Why: Returns the currently authenticated user profile.
+ * When: Used by clients to bootstrap session/user state.
+ * Where: GET auth me route.
+ */
+export const me = async (request: FastifyRequest, reply: FastifyReply) => {
+  try {
+    const auth = request.auth as { id: number };
+    const result = await meService.me(auth.id);
+
+    switch (result.kind) {
+      case "not_found":
+        return reply.code(HttpStatusCodes.NOT_FOUND).send({ message: result.message });
+
+      case "found":
+        return reply.code(HttpStatusCodes.OK).send({
+          message: result.message,
+          data: result.data
+        });
+    }
+  } catch (error) {
+    console.error("Me error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to fetch user" });
+  }
+};
+
+/**
+ * Why: Revokes current refresh token and clears auth cookies.
+ * When: Used when the active device logs out.
+ * Where: POST auth logout route.
+ */
+export const logout = async (request: FastifyRequest, reply: FastifyReply) => {
+  try {
+    const result = await logoutService.logout(request, reply);
+
+    // cookie cleanup is an HTTP concern — stays in the controller
+    cookie.deleteAuth(reply);
+    cookie.deleteRefresh(reply);
+
+    return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+  } catch (error) {
+    console.error("Logout error:", error);
+
+    cookie.deleteAuth(reply);
+    cookie.deleteRefresh(reply);
+
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to logout" });
+  }
+};
+
+/**
+ * Why: Starts password reset flow and queues email delivery event.
+ * When: Used when user requests a forgot-password link.
+ * Where: POST auth forgot-password route.
+ */
+export const forgotPassword = async (request: Body<ForgotPasswordInput>, reply: FastifyReply) => {
+  try {
+    const result = await forgotPasswordService.forgotPassword(request.body);
+
+    // Single success path — intentionally identical whether or not the email exists.
+    return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+  } catch (error) {
+    console.error("Forgot password error:", error);
+    return reply
+      .code(HttpStatusCodes.INTERNAL_SERVER_ERROR)
+      .send({ message: "Failed to process forgot password request" });
+  }
+};
+
+/**
+ * Why: Verifies reset token and persists the new password.
+ * When: Used after user submits reset token + new password.
+ * Where: POST auth reset-password route.
+ */
+export const resetPassword = async (request: Body<ResetPasswordInput>, reply: FastifyReply) => {
+  try {
+    const result = await resetPasswordService.resetPassword(request.body);
+
+    switch (result.kind) {
+      case "invalid_token":
+        return reply.code(HttpStatusCodes.UNPROCESSABLE_ENTITY).send({ message: result.message });
+
+      case "reset":
+        return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+    }
+  } catch (error) {
+    console.error("Reset password error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to reset password" });
+  }
+};
+
+/**
+ * Why: Validates email verification token and marks user as verified.
+ * When: Used when user opens verification link from inbox.
+ * Where: POST auth verify-email route.
+ */
+export const verifyEmail = async (request: Body<VerifyEmailInput>, reply: FastifyReply) => {
+  try {
+    const result = await verifyEmailService.verifyEmail(request.body);
+
+    switch (result.kind) {
+      case "not_required":
+        return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+
+      case "invalid_token":
+        return reply.code(HttpStatusCodes.UNPROCESSABLE_ENTITY).send({ message: result.message });
+
+      case "verified":
+        return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+    }
+  } catch (error) {
+    console.error("Verify email error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to verify email" });
+  }
+};
+
+/**
+ * Why: Rotates refresh token and reissues access credentials.
+ * When: Used when access token expires but refresh token is still valid.
+ * Where: POST auth refresh-token route.
+ */
+export const refreshToken = async (request: Body<RefreshTokenInput>, reply: FastifyReply) => {
+  try {
+    const result = await refreshTokenService.refreshToken(request.body);
+
+    switch (result.kind) {
+      case "invalid_token":
+      case "revoked":
+      case "expired":
+      case "user_not_found":
+        return reply.code(HttpStatusCodes.UNAUTHORIZED).send({ message: result.message });
+
+      case "refreshed": {
+        // Cookie handling stays in the controller — it's an HTTP concern.
+        await cookie.setAuth(reply, result.cookies.accessToken);
+        await cookie.setRefresh(reply, result.cookies.refreshToken, result.cookies.refreshExpiry);
+
+        return reply.code(HttpStatusCodes.OK).send({
+          message: result.message,
+          data: result.data
+        });
+      }
+    }
+  } catch (error) {
+    console.error("Refresh token error:", error);
+    return reply.code(HttpStatusCodes.UNAUTHORIZED).send({ message: "Invalid or expired refresh token" });
+  }
+};
+
+/**
+ * Why: Revokes all refresh tokens for account-wide logout.
+ * When: Used for "logout from all devices" security action.
+ * Where: POST auth logout-all-devices route.
+ */
+export const logoutAllDevices = async (request: FastifyRequest, reply: FastifyReply) => {
+  try {
+    const auth = request.auth as { id: number } | undefined | null;
+
+    if (!auth) {
+      return reply.code(HttpStatusCodes.UNAUTHORIZED).send({ message: "Unauthorized" });
+    }
+
+    const result = await logoutAllDevicesService.logoutAllDevices(auth.id);
+
+    // cookie cleanup is an HTTP concern — stays in the controller
+    cookie.deleteAuth(reply);
+    cookie.deleteRefresh(reply);
+
+    return reply.code(HttpStatusCodes.OK).send({ message: result.message });
+  } catch (error) {
+    console.error("Logout all devices error:", error);
+    return reply.code(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: "Failed to logout from all devices" });
+  }
+};

package/fastify/src/modules/auth/controllers/role.ts

@@ -0,0 +1,35 @@
+import { eq } from "drizzle-orm";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { db, HttpStatusCodes } from "@/framework/facade.js";
+import { roles } from "@/modules/auth/database/models/role.js";
+
+function sanitizeRole(role: any) {
+  if (!role) return null;
+  return {
+    id: role.id,
+    name: role.name,
+    createdAt: role.createdAt ? String(role.createdAt) : null,
+    updatedAt: role.updatedAt ? String(role.updatedAt) : null
+  };
+}
+
+/**
+ * Why: Returns role records for role-aware UI and authorization setup.
+ * When: Used by admin/management screens that need available roles.
+ * Where: Mounted under auth role routes.
+ */
+export const index = async (_request: FastifyRequest, reply: FastifyReply) => {
+  const result = await db.query.roles.findMany();
+  return reply.code(HttpStatusCodes.OK).send({ message: "Success", data: result.map(sanitizeRole) });
+};
+
+/**
+ * Why: Fetches a single role to inspect role metadata by id.
+ * When: Used for detail views or role validation checks.
+ * Where: Mounted on auth role detail route with path param id.
+ */
+export const show = async (request: FastifyRequest<{ Params: { id: number } }>, reply: FastifyReply) => {
+  const { id } = request.params;
+  const result = await db.query.roles.findFirst({ where: eq(roles.id, Number(id)) });
+  return reply.code(HttpStatusCodes.OK).send({ message: "Success", data: sanitizeRole(result) });
+};

package/fastify/src/modules/auth/database/models/role.ts

@@ -0,0 +1,14 @@
+import { relations } from "drizzle-orm";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { users } from "@/modules/auth/database/models/user.js";
+
+export const roles = sqliteTable("roles", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull().unique(),
+  createdAt: integer("created_at", { mode: "timestamp" }).defaultNow().notNull(),
+  updatedAt: integer("updated_at", { mode: "timestamp" }).defaultNow().notNull()
+});
+
+export const rolesRelations = relations(roles, ({ many }) => ({
+  users: many(users)
+}));