create-nexgen 1.0.4

package/template/src/framework/support/cookie.ts

@@ -0,0 +1,78 @@
+import type { Context } from "hono";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { env } from "@/env.js";
+
+const baseOptions = {
+  httpOnly: true,
+  secure: false,
+  sameSite: "Lax" as const,
+  path: "/"
+};
+
+export const cookie = {
+  /**
+   * Why: Stores short-lived access token cookie for authenticated requests.
+   * When: Login/register/refresh responses.
+   * Where: Auth controllers/helpers.
+   * How: Sets httpOnly cookie with configured access expiry.
+   */
+  setAuth(c: Context, token: string) {
+    setCookie(c, `${env.COOKIE_NAME}_access`, token, {
+      ...baseOptions,
+      maxAge: env.JWT_ACCESS_EXPIRY
+    });
+  },
+
+  /**
+   * Why: Stores refresh token cookie for token rotation.
+   * When: Login/register/refresh responses.
+   * Where: Auth controllers/helpers.
+   * How: Sets httpOnly cookie with explicit or default refresh maxAge.
+   */
+  setRefresh(c: Context, token: string, maxAge?: number) {
+    setCookie(c, `${env.COOKIE_NAME}_refresh`, token, {
+      ...baseOptions,
+      maxAge: typeof maxAge === "number" ? maxAge : env.JWT_REFRESH_EXPIRY
+    });
+  },
+
+  /**
+   * Why: Reads access token cookie from request context.
+   * When: Auth middleware validates request identity.
+   * Where: Middleware and auth helpers.
+   * How: Resolves cookie by configured access cookie name.
+   */
+  getAuth(c: Context) {
+    return getCookie(c, `${env.COOKIE_NAME}_access`);
+  },
+
+  /**
+   * Why: Reads refresh token cookie from request context.
+   * When: Refresh and logout flows.
+   * Where: Auth middleware/controllers.
+   * How: Resolves cookie by configured refresh cookie name.
+   */
+  getRefresh(c: Context) {
+    return getCookie(c, `${env.COOKIE_NAME}_refresh`);
+  },
+
+  /**
+   * Why: Clears access token cookie.
+   * When: Logout or invalid token handling.
+   * Where: Auth middleware/controllers.
+   * How: Deletes cookie path-scoped to root.
+   */
+  deleteAuth(c: Context) {
+    deleteCookie(c, `${env.COOKIE_NAME}_access`, { path: "/" });
+  },
+
+  /**
+   * Why: Clears refresh token cookie.
+   * When: Logout or invalid token handling.
+   * Where: Auth middleware/controllers.
+   * How: Deletes cookie path-scoped to root.
+   */
+  deleteRefresh(c: Context) {
+    deleteCookie(c, `${env.COOKIE_NAME}_refresh`, { path: "/" });
+  }
+};

package/template/src/framework/support/jwt.ts

@@ -0,0 +1,45 @@
+import { sign, verify } from "hono/jwt";
+import { randomUUID } from "node:crypto";
+import { env } from "@/env.js";
+
+export const jwt = {
+  /**
+   * Why: Creates signed JWT access/refresh tokens with project claims.
+   * When: Auth flows issue or rotate credentials.
+   * Where: Auth controllers/helpers.
+   * How: Builds payload with iat/exp/type (+jti for refresh) and signs HS256.
+   */
+  async generateToken(payload: any, type: "access" | "refresh", expirySeconds?: number) {
+    const now = Math.floor(Date.now() / 1000);
+    const exp = now
+      + (typeof expirySeconds === "number"
+        ? expirySeconds
+        : type === "refresh"
+          ? env.JWT_REFRESH_EXPIRY
+          : env.JWT_ACCESS_EXPIRY);
+    const secret = type === "refresh" ? env.JWT_REFRESH_SECRET : env.JWT_ACCESS_SECRET;
+    const jti = type === "refresh" ? randomUUID() : undefined;
+
+    const tokenPayload = { ...payload, type, iat: now, exp, ...(jti ? { jti } : {}) };
+    const token = await sign(tokenPayload, secret, "HS256");
+
+    return { token, jti, exp };
+  },
+
+  /**
+   * Why: Validates JWT and enforces token type.
+   * When: Middleware and refresh flows verify credentials.
+   * Where: Auth and realtime handshake.
+   * How: Verifies signature/expiry with type-specific secret and checks payload type.
+   */
+  async verifyToken(token: string, type: "access" | "refresh") {
+    try {
+      const secret = type === "refresh" ? env.JWT_REFRESH_SECRET : env.JWT_ACCESS_SECRET;
+      const payload = await verify(token, secret, "HS256");
+      return payload.type === type ? payload : null;
+    } catch {
+      return null;
+    }
+  }
+};
+

package/template/src/framework/support/lifecycle.ts

@@ -0,0 +1,35 @@
+const shutdownSignals = ["SIGINT", "SIGTERM"] as const;
+export type ShutdownSignal = (typeof shutdownSignals)[number];
+
+type ShutdownHandler = (signal: ShutdownSignal) => Promise<void>;
+
+/**
+ * Why: Avoid duplicated graceful-shutdown wiring across runtime entrypoints.
+ * When: Server/worker/scheduler need signal handling.
+ * Where: Runtime bootstrap files.
+ * How: Registers SIGINT/SIGTERM handlers and forwards signal to async callback.
+ */
+export function registerShutdownSignals(handler: ShutdownHandler) {
+  for (const signal of shutdownSignals) {
+    process.on(signal, () => {
+      void handler(signal);
+    });
+  }
+}
+
+/**
+ * Why: Keep comma-separated CLI/env parsing consistent.
+ * When: Runtime options are provided as a single CSV string.
+ * Where: Worker and other entrypoints.
+ * How: Trims tokens, removes blanks, and falls back when empty.
+ */
+export function parseCsvOrFallback(value: string | undefined, fallback: string[]) {
+  if (!value) return fallback;
+
+  const parsed = value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  return parsed.length ? parsed : fallback;
+}

package/template/src/framework/support/logger.ts

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import winston from "winston";
+import { env } from "@/env.js";
+
+const logDir = path.resolve(process.cwd(), "src", "storage", "logs");
+
+if (!fs.existsSync(logDir)) {
+  fs.mkdirSync(logDir, { recursive: true });
+}
+
+function visibleMeta(meta: Record<string, unknown>) {
+  const { service: _service, ...rest } = meta;
+  return rest;
+}
+
+function normalizeMeta(meta: Record<string, unknown>) {
+  const next: Record<string, unknown> = { ...meta };
+
+  const processMeta = next.process as Record<string, unknown> | undefined;
+  if (processMeta && typeof processMeta === "object") {
+    const memoryUsage = processMeta.memoryUsage as Record<string, unknown> | undefined;
+    if (memoryUsage && typeof memoryUsage === "object") {
+      processMeta.memoryUsage = Object.entries(memoryUsage)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(" ");
+    }
+    if (Array.isArray(processMeta.argv)) {
+      processMeta.argv = `[${processMeta.argv.join(" ")}]`;
+    }
+    next.process = processMeta;
+  }
+
+  const trace = next.trace;
+  if (Array.isArray(trace) && trace.length > 3) {
+    next.trace = [...trace.slice(0, 3), `... ${trace.length - 3} more frame(s)`];
+  }
+
+  const osMeta = next.os as Record<string, unknown> | undefined;
+  if (osMeta && typeof osMeta === "object" && Array.isArray(osMeta.loadavg)) {
+    osMeta.loadavg = `[${osMeta.loadavg.join(",")}]`;
+    next.os = osMeta;
+  }
+
+  return next;
+}
+
+const fileFormat = winston.format.combine(
+  winston.format.timestamp({ format: "HH:mm:ss" }),
+  winston.format.printf(({ timestamp, level, message, stack, ...meta }) => {
+    const rest = normalizeMeta(visibleMeta(meta));
+    const metaString = Object.keys(rest).length ? `\n${JSON.stringify(rest, null, 2)}` : "";
+    return `[${timestamp}] ${level} -> ${stack || message}${metaString}\n`;
+  })
+);
+
+const consoleFormat = winston.format.combine(
+  winston.format.colorize(),
+  winston.format.timestamp({ format: "HH:mm:ss" }),
+  winston.format.printf(({ timestamp, level, message, stack, ...meta }) => {
+    const rest = normalizeMeta(visibleMeta(meta));
+    const metaString = Object.keys(rest).length ? `\n${JSON.stringify(rest, null, 2)}` : "";
+    return `[${timestamp}] ${level} -> ${stack || message}${metaString}`;
+  })
+);
+
+/**
+ * Why: Shared structured logger for app/runtime/framework internals.
+ * When: Any code needs operational logs or error reporting.
+ * Where: Imported across framework and modules.
+ * How: Writes color console logs + rotating files with exception/rejection handlers.
+ */
+export const logger = winston.createLogger({
+  level: env.LOG_LEVEL || "info",
+  defaultMeta: {
+    service: env.APP_NAME
+  },
+  transports: [
+    new winston.transports.Console({
+      level: env.LOG_LEVEL || "debug",
+      format: consoleFormat
+    }),
+    new winston.transports.File({
+      filename: path.join(logDir, "app.log"),
+      level: "info",
+      maxsize: 10 * 1024 * 1024,
+      maxFiles: 5,
+      tailable: true,
+      format: fileFormat
+    }),
+    new winston.transports.File({
+      filename: path.join(logDir, "fatal.log"),
+      level: "error",
+      maxsize: 10 * 1024 * 1024,
+      maxFiles: 3,
+      tailable: true,
+      handleExceptions: true,
+      handleRejections: true,
+      format: fileFormat
+    })
+  ]
+});

package/template/src/framework/support/mail.ts

@@ -0,0 +1,43 @@
+import nodemailer from "nodemailer";
+import { env } from "@/env.js";
+import { logger } from "@/framework/support/logger.js";
+
+type MailPayload = {
+  to: string;
+  subject: string;
+  html?: string;
+  text?: string;
+};
+
+const transport = nodemailer.createTransport({
+  host: env.MAIL_HOST,
+  port: env.MAIL_PORT,
+  secure: false,
+  auth: env.MAIL_USERNAME ? { user: env.MAIL_USERNAME, pass: env.MAIL_PASSWORD } : undefined
+});
+
+export const mail = {
+  /**
+   * Why: Sends transactional email through configured SMTP transport.
+   * When: Features need notifications/password reset/signup email.
+   * Where: Jobs and event handlers.
+   * How: Uses nodemailer transport and respects MAIL_FAIL_SILENT behavior.
+   */
+  async sendMail(payload: MailPayload) {
+    try {
+      return await transport.sendMail({
+        from: env.MAIL_FROM_ADDRESS,
+        ...payload
+      });
+    } catch (error) {
+      logger.error("Mail send failed", {
+        to: payload.to,
+        subject: payload.subject,
+        error: error instanceof Error ? error.message : error
+      });
+
+      if (!env.MAIL_FAIL_SILENT) throw error;
+      return null;
+    }
+  }
+};

package/template/src/framework/support/password.ts

@@ -0,0 +1,23 @@
+import bcrypt from "bcryptjs";
+
+export const password = {
+  /**
+   * Why: Hashes plaintext password before persistence.
+   * When: Registration and password reset flows.
+   * Where: Auth controllers/seeders.
+   * How: Uses bcrypt with cost factor 10.
+   */
+  async hashPassword(inputPassword: string) {
+    return await bcrypt.hash(inputPassword, 10);
+  },
+
+  /**
+   * Why: Compares plaintext password to stored hash.
+   * When: Login/authentication checks.
+   * Where: Auth controllers/middleware.
+   * How: Uses bcrypt secure compare.
+   */
+  async verifyPassword(inputPassword: string, hashedPassword: string) {
+    return await bcrypt.compare(inputPassword, hashedPassword);
+  }
+};

package/template/src/framework/support/url.ts

@@ -0,0 +1,25 @@
+import { env } from "@/env.js";
+
+export const urls = {
+  /**
+   * Why: Returns normalized app base URL without trailing slash.
+   * When: Building absolute links.
+   * Where: Mail/reset URL generation.
+   * How: Trims trailing slash from APP_URL.
+   */
+  appUrl() {
+    return env.APP_URL.replace(/\/$/, "");
+  },
+
+  /**
+   * Why: Builds absolute URL from APP_URL and a path.
+   * When: Creating links for emails or external callbacks.
+   * Where: Auth/password reset and integrations.
+   * How: Normalizes slash joining between base and path.
+   */
+  url(path = "") {
+    const base = urls.appUrl();
+    if (!path) return base;
+    return `${base}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+};

package/template/src/middlewares/auth-middleware.ts

@@ -0,0 +1,98 @@
+import type { Context, Next } from "hono";
+import { eq } from "drizzle-orm";
+import { cookie, db, jwt } from "@/framework/facade.js";
+import { refreshTokens, users } from "@/modules/auth/database/models/user.js";
+
+export async function authMiddleware(c: Context, next: Next) {
+  const accessToken = cookie.getAuth(c);
+
+  if (accessToken) {
+    const accessPayload = await jwt.verifyToken(accessToken, "access");
+
+    if (accessPayload) {
+      const user = await db.query.users.findFirst({
+        where: eq(users.id, accessPayload.id as number),
+        with: { role: true }
+      });
+
+      if (!user) {
+        cookie.deleteAuth(c);
+        cookie.deleteRefresh(c);
+        return c.json({ message: "Unauthorized" }, 401);
+      }
+
+      c.set("auth", {
+        ...accessPayload,
+        id: user.id,
+        email: user.email,
+        roleId: user.role?.id ?? null,
+        role: user.role?.name ?? null
+      });
+      return await next();
+    }
+  }
+
+  const refreshToken = cookie.getRefresh(c);
+
+  if (!refreshToken) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Unauthorized" }, 401);
+  }
+
+  const refreshPayload = await jwt.verifyToken(refreshToken, "refresh");
+
+  if (!refreshPayload?.jti) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Invalid token" }, 401);
+  }
+
+  const storedToken = await db.query.refreshTokens.findFirst({
+    where: eq(refreshTokens.jti, refreshPayload.jti as string)
+  });
+
+  if (!storedToken || storedToken.revoked === 1) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Invalid token" }, 401);
+  }
+
+  if (storedToken.expiresAt.getTime() < Date.now()) {
+    await db.delete(refreshTokens).where(eq(refreshTokens.id, storedToken.id));
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Invalid token" }, 401);
+  }
+
+  const user = await db.query.users.findFirst({
+    where: eq(users.id, refreshPayload.id as number),
+    with: { role: true }
+  });
+
+  if (!user) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Unauthorized" }, 401);
+  }
+
+  const newAccessToken = await jwt.generateToken(
+    {
+      id: user.id,
+      email: user.email,
+      roleId: user.role?.id ?? null,
+      role: user.role?.name ?? null
+    },
+    "access"
+  );
+
+  cookie.setAuth(c, newAccessToken.token);
+  c.set("auth", {
+    id: user.id,
+    email: user.email,
+    roleId: user.role?.id ?? null,
+    role: user.role?.name ?? null,
+    type: "access"
+  });
+  return await next();
+}

package/template/src/middlewares/role-middleware.ts

@@ -0,0 +1,24 @@
+import type { Context, Next } from "hono";
+
+type AuthPayload = {
+  role?: string | null;
+};
+
+export function requireRole(...allowedRoles: string[]) {
+  const roles = allowedRoles.map((role) => role.toLowerCase());
+
+  return async (c: Context, next: Next) => {
+    const auth = c.get("auth") as AuthPayload | undefined;
+
+    if (!auth) {
+      return c.json({ message: "Unauthorized" }, 401);
+    }
+
+    const userRole = String(auth.role ?? "").toLowerCase();
+    if (!roles.includes(userRole)) {
+      return c.json({ message: "Forbidden: Insufficient permissions" }, 403);
+    }
+
+    return await next();
+  };
+}