create-nexwire 4.0.0 → 4.1.1

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

@@ -0,0 +1,214 @@
+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"
+};
+
+/**
+ * Build a fake `tx`.
+ * Options:
+ *   - consumeRow: the row returned by delete().returning(), or null for "no match"
+ *   - failOnUpdate: 1-indexed update that should reject, or undefined for none
+ */
+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);
+
+    // 1st update: user's password, matched by id
+    expect((updateCalls[0].table as any).__table).toBe("users");
+    expect(updateCalls[0].values).toEqual({
+      password: "hashed-new-pw",
+      updatedAt: expect.any(Date)
+    });
+
+    // 2nd update: revoke all refresh tokens for this user
+    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/hono/src/modules/auth/__tests__/verifyemail.test.ts

@@ -0,0 +1,189 @@
+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" };
+
+/**
+ * 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({
+      kind: "invalid_token",
+      message: "Invalid or expired verification 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({
+      kind: "invalid_token",
+      message: "Invalid or expired verification 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({
+      kind: "invalid_token",
+      message: "Invalid or expired verification token" // ← matches the service
+    });
+  });
+
+  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({
+      kind: "invalid_token",
+      message: "Invalid or expired verification token"
+    });
+
+    expect(updateCalls).toHaveLength(1);
+    expect((updateCalls[0].table as any).__table).toBe("users");
+  });
+});

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

@@ -0,0 +1,238 @@
+import type { Handler } from "hono";
+import { cookie, HttpStatusCodes } from "@/framework/facade.js";
+import { forgotPasswordService } from "@/modules/auth/services/forgetpassword.js";
+import { loginService } from "@/modules/auth/services/login.js";
+import { logoutService } from "@/modules/auth/services/logout.js";
+import { meService } from "@/modules/auth/services/me.js";
+import { registerService } from "@/modules/auth/services/register.js";
+import { resetPasswordService } from "@/modules/auth/services/resetpassword.js";
+import {
+  ForgotPasswordInput,
+  LoginInput,
+  RefreshTokenInput,
+  RegisterInput,
+  ResetPasswordInput,
+  VerifyEmailInput
+} from "@/modules/auth/types/auth.js";
+import { logoutAllDevicesService } from "../services/logoutalldevices.js";
+import { refreshTokenService } from "../services/refreshtoken.js";
+import { verifyEmailService } from "../services/verifyemail.js";
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as RegisterInput;
+    const result = await registerService.register(c, body);
+
+    switch (result.kind) {
+      case "email_exists":
+        return c.json({ message: result.message }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+
+      case "verification_required":
+        return c.json({ message: result.message }, HttpStatusCodes.CREATED);
+
+      case "registered":
+        return c.json({ message: result.message, data: result.data }, HttpStatusCodes.CREATED);
+    }
+  } catch (error) {
+    console.error("Register error:", error);
+    return c.json({ message: "Failed to register user" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as LoginInput;
+    const result = await loginService.login(c, body);
+
+    switch (result.kind) {
+      case "invalid_credentials":
+        return c.json({ message: result.message }, HttpStatusCodes.UNAUTHORIZED);
+
+      case "email_not_verified":
+        return c.json({ message: result.message }, HttpStatusCodes.FORBIDDEN);
+
+      case "logged_in":
+        return c.json({ message: result.message, data: result.data }, HttpStatusCodes.OK);
+    }
+  } catch (error) {
+    console.error("Login error:", error);
+    return c.json({ message: "Failed to login" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * Why: Returns the currently authenticated user profile.
+ * When: Used by clients to bootstrap session/user state.
+ * Where: GET auth me route.
+ */
+export const me: Handler = async (c: any) => {
+  try {
+    const auth = c.get("auth");
+    const result = await meService.me(auth.id);
+
+    switch (result.kind) {
+      case "not_found":
+        return c.json({ message: result.message }, HttpStatusCodes.NOT_FOUND);
+
+      case "found":
+        return c.json({ message: result.message, data: result.data }, HttpStatusCodes.OK);
+    }
+  } catch (error) {
+    console.error("Me error:", error);
+    return c.json({ message: "Failed to fetch user" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const result = await logoutService.logout(c);
+
+    return c.json({ message: result.message }, HttpStatusCodes.OK);
+  } catch (error) {
+    console.error("Logout error:", error);
+
+    // always clear cookies, even if revocation failed
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+
+    return c.json({ message: "Failed to logout" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as ForgotPasswordInput;
+    const result = await forgotPasswordService.forgotPassword(body);
+
+    // Single success path — intentionally identical whether or not the email exists.
+    return c.json({ message: result.message }, HttpStatusCodes.OK);
+  } catch (error) {
+    console.error("Forgot password error:", error);
+    return c.json({ message: "Failed to process forgot password request" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as ResetPasswordInput;
+    const result = await resetPasswordService.resetPassword(body);
+
+    switch (result.kind) {
+      case "invalid_token":
+        return c.json({ message: result.message }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+
+      case "reset":
+        return c.json({ message: result.message }, HttpStatusCodes.OK);
+    }
+  } catch (error) {
+    console.error("Reset password error:", error);
+    return c.json({ message: "Failed to reset password" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as VerifyEmailInput;
+    const result = await verifyEmailService.verifyEmail(body);
+
+    switch (result.kind) {
+      case "not_required":
+        return c.json({ message: result.message }, HttpStatusCodes.OK);
+
+      case "invalid_token":
+        return c.json({ message: result.message }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+
+      case "verified":
+        return c.json({ message: result.message }, HttpStatusCodes.OK);
+    }
+  } catch (error) {
+    console.error("Verify email error:", error);
+    return c.json({ message: "Failed to verify email" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const body = c.req.valid("json") as RefreshTokenInput;
+    const result = await refreshTokenService.refreshToken(body);
+
+    switch (result.kind) {
+      case "invalid_token":
+      case "revoked":
+      case "expired":
+      case "user_not_found":
+        return c.json({ message: result.message }, HttpStatusCodes.UNAUTHORIZED);
+
+      case "refreshed": {
+        // Cookie handling stays in the controller — it's an HTTP concern.
+        await cookie.setAuth(c, result.cookies.accessToken);
+        await cookie.setRefresh(c, result.cookies.refreshToken, result.cookies.refreshExpiry);
+
+        return c.json({ message: result.message, data: result.data }, HttpStatusCodes.OK);
+      }
+    }
+  } catch (error) {
+    console.error("Refresh token error:", error);
+    return c.json({ message: "Invalid or expired refresh token" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  try {
+    const auth = c.get("auth");
+    if (!auth) {
+      return c.json({ message: "Unauthorized" }, HttpStatusCodes.UNAUTHORIZED);
+    }
+
+    const result = await logoutAllDevicesService.logoutAllDevices(auth.id);
+
+    // Cookies are an HTTP concern — kept out of the service.
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+
+    return c.json({ message: result.message }, HttpStatusCodes.OK);
+  } catch (error) {
+    console.error("Logout all devices error:", error);
+    return c.json({ message: "Failed to logout from all devices" }, HttpStatusCodes.INTERNAL_SERVER_ERROR);
+  }
+};

package/hono/src/modules/auth/controllers/{role.controller.ts → role.ts}

@@ -1,25 +1,25 @@
-import { eq } from "drizzle-orm";
-import type { Handler } from "hono";
-import { db, HttpStatusCodes } from "@/framework/facade.js";
-import { roles } from "@/modules/auth/database/models/role.js";
-
-/**
- * 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: Handler = async (c: any) => {
-  const result = await db.query.roles.findMany();
-  return c.json({ message: "Success", data: result }, HttpStatusCodes.OK);
-};
-
-/**
- * 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: Handler = async (c: any) => {
-  const { id } = c.req.valid("param");
-  const result = await db.query.roles.findFirst({ where: eq(roles.id, id) });
-  return c.json({ message: "Success", data: result }, HttpStatusCodes.OK);
-};
+import { eq } from "drizzle-orm";
+import type { Handler } from "hono";
+import { db, HttpStatusCodes } from "@/framework/facade.js";
+import { roles } from "@/modules/auth/database/models/role.js";
+
+/**
+ * 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: Handler = async (c: any) => {
+  const result = await db.query.roles.findMany();
+  return c.json({ message: "Success", data: result }, HttpStatusCodes.OK);
+};
+
+/**
+ * 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: Handler = async (c: any) => {
+  const { id } = c.req.valid("param");
+  const result = await db.query.roles.findFirst({ where: eq(roles.id, id) });
+  return c.json({ message: "Success", data: result }, HttpStatusCodes.OK);
+};

package/{express/src/modules/auth/database/models/notifications.ts → hono/src/modules/auth/database/models/notification.ts}

@@ -21,4 +21,4 @@ export const notificationsRelations = relations(notifications, ({ one }) => ({
     fields: [notifications.userId],
     references: [users.id]
   })
-}));
+}));