create-nexwire 4.0.0

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

@@ -0,0 +1,99 @@
+import type { Context } from "hono";
+import { deleteCookie, getSignedCookie, setSignedCookie } from "hono/cookie";
+import { appConfig, cookieConfig, jwtConfig } from "@/config/index.js";
+
+function originOf(url?: string) {
+  if (!url) return "";
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+}
+
+function needsCrossSiteCookie() {
+  const appOrigin = originOf(appConfig.url);
+  const frontendOrigin = originOf(appConfig.frontendUrl);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+function baseOptions() {
+  const crossSiteCookie = needsCrossSiteCookie();
+  const sameSite: "None" | "Lax" = crossSiteCookie ? "None" : "Lax";
+  return {
+    httpOnly: true,
+    secure: crossSiteCookie,
+    sameSite,
+    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.
+   */
+  async setAuth(c: Context, token: string) {
+    await setSignedCookie(c, `${cookieConfig.name}_access`, token, cookieConfig.secret, {
+      ...baseOptions(),
+      maxAge: jwtConfig.accessExpirySeconds
+    });
+  },
+
+  /**
+   * 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.
+   */
+  async setRefresh(c: Context, token: string, maxAge?: number) {
+    await setSignedCookie(c, `${cookieConfig.name}_refresh`, token, cookieConfig.secret, {
+      ...baseOptions(),
+      maxAge: typeof maxAge === "number" ? maxAge : jwtConfig.refreshExpirySeconds
+    });
+  },
+
+  /**
+   * 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.
+   */
+  async getAuth(c: Context) {
+    const token = await getSignedCookie(c, cookieConfig.secret, `${cookieConfig.name}_access`);
+    return token || undefined;
+  },
+
+  /**
+   * 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.
+   */
+  async getRefresh(c: Context) {
+    const token = await getSignedCookie(c, cookieConfig.secret, `${cookieConfig.name}_refresh`);
+    return token || undefined;
+  },
+
+  /**
+   * 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, `${cookieConfig.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, `${cookieConfig.name}_refresh`, { path: "/" });
+  }
+};

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

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { sign, verify } from "hono/jwt";
+import { jwtConfig } from "@/config/index.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"
+          ? jwtConfig.refreshExpirySeconds
+          : jwtConfig.accessExpirySeconds);
+    const secret = type === "refresh" ? jwtConfig.refreshSecret : jwtConfig.accessSecret;
+    const jti = type === "refresh" ? randomUUID() : undefined;
+
+    const tokenPayload = { ...payload, type, iat: now, exp, ...(jti ? { jti } : {}) };
+    const token = await sign(tokenPayload, secret, jwtConfig.algorithm);
+
+    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" ? jwtConfig.refreshSecret : jwtConfig.accessSecret;
+      const payload = await verify(token, secret, jwtConfig.algorithm);
+      return payload.type === type ? payload : null;
+    } catch {
+      return null;
+    }
+  }
+};

package/hono/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/hono/src/framework/support/logger.ts

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Writable } from "node:stream";
+import pino from "pino";
+import { appConfig, loggingConfig } from "@/config/index.js";
+
+const logDir = path.resolve(process.cwd(), "src", "storage", "logs");
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+if (!fs.existsSync(logDir)) {
+  fs.mkdirSync(logDir, { recursive: true });
+}
+
+const LEVEL_COLORS: Record<number, string> = {
+  10: "\x1b[90m",
+  20: "\x1b[90m",
+  30: "\x1b[32m",
+  40: "\x1b[33m",
+  50: "\x1b[31m",
+  60: "\x1b[31m"
+};
+
+const RESET = "\x1b[0m";
+
+function formatLine(chunk: string, colorize: boolean): string {
+  const line = chunk.trim();
+  if (!line) return "";
+
+  let record: Record<string, unknown>;
+  try {
+    record = JSON.parse(line);
+  } catch {
+    return colorize ? line : `${line}\n`;
+  }
+
+  const time = typeof record.time === "number" ? new Date(record.time) : new Date(String(record.time));
+  const timestamp = Number.isNaN(time.getTime()) ? "" : `[${time.toLocaleTimeString("en-GB", { hour12: false })}] `;
+  const levelNumber = typeof record.level === "number" ? record.level : 30;
+  const label = pino.levels.labels[levelNumber] ?? "info";
+  const message = typeof record.msg === "string" ? record.msg : "";
+
+  const ignored = new Set(["time", "level", "msg", "pid", "hostname", "service"]);
+  const meta: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!ignored.has(key)) meta[key] = value;
+  }
+
+  const level = colorize ? `${LEVEL_COLORS[levelNumber] ?? ""}${label}${RESET}` : label;
+  const metaString = Object.keys(meta).length ? `\n${JSON.stringify(meta, null, 2)}` : "";
+  return `${timestamp}${level} -> ${message}${metaString}\n`;
+}
+
+function consoleWriter() {
+  return new Writable({
+    write(chunk, _encoding, callback) {
+      const text = formatLine(chunk.toString("utf8"), true);
+      if (text) process.stdout.write(text);
+      callback();
+    }
+  });
+}
+
+function rotate(filePath: string, maxFiles: number) {
+  for (let index = maxFiles - 1; index >= 1; index--) {
+    const from = `${filePath}.${index}`;
+    const to = `${filePath}.${index + 1}`;
+    if (fs.existsSync(from)) fs.renameSync(from, to);
+  }
+  if (fs.existsSync(filePath)) fs.renameSync(filePath, `${filePath}.1`);
+}
+
+function fileWriter(filePath: string, maxFiles: number) {
+  let bytes = 0;
+
+  return new Writable({
+    write(chunk, _encoding, callback) {
+      const text = formatLine(chunk.toString("utf8"), false);
+      bytes += Buffer.byteLength(text);
+      if (bytes >= MAX_FILE_BYTES) {
+        rotate(filePath, maxFiles);
+        bytes = 0;
+      }
+      try {
+        fs.appendFileSync(filePath, text);
+      } catch {
+        // best-effort file logging
+      }
+      callback();
+    }
+  });
+}
+
+const base = pino(
+  {
+    level: loggingConfig.level,
+    base: { service: appConfig.name },
+    timestamp: pino.stdTimeFunctions.isoTime
+  },
+  pino.multistream([
+    { stream: consoleWriter(), level: loggingConfig.level },
+    { stream: fileWriter(path.join(logDir, "app.log"), 5), level: "info" },
+    { stream: fileWriter(path.join(logDir, "fatal.log"), 3), level: "error" }
+  ])
+);
+
+type CompatLogger = {
+  fatal: (message: string, meta?: Record<string, unknown>) => void;
+  error: (message: string, meta?: Record<string, unknown>) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
+  info: (message: string, meta?: Record<string, unknown>) => void;
+  debug: (message: string, meta?: Record<string, unknown>) => void;
+  trace: (message: string, meta?: Record<string, unknown>) => void;
+  child: (bindings: Record<string, unknown>) => CompatLogger;
+};
+
+function compat(child: pino.Logger): CompatLogger {
+  const wrap = (log: (obj: object, msg?: string, ...args: unknown[]) => void) => (message: string, meta?: Record<string, unknown>) =>
+    log.call(child, meta ?? {}, message);
+
+  return {
+    fatal: wrap(child.fatal),
+    error: wrap(child.error),
+    warn: wrap(child.warn),
+    info: wrap(child.info),
+    debug: wrap(child.debug),
+    trace: wrap(child.trace),
+    child: (bindings) => compat(child.child(bindings))
+  };
+}
+
+/**
+ * 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: Emits JSON via pino to a color console sink plus rotating app/fatal
+ *      files, keeping the legacy `(message, meta)` call signature.
+ */
+export const logger: CompatLogger = compat(base);
+
+process.on("uncaughtException", (error) => {
+  logger.error("Uncaught exception", { error: { name: error.name, message: error.message, stack: error.stack } });
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  const error = reason instanceof Error ? reason : new Error(String(reason));
+  logger.error("Unhandled rejection", { error: { name: error.name, message: error.message, stack: error.stack } });
+});

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

@@ -0,0 +1,48 @@
+import nodemailer from "nodemailer";
+import { mailConfig } from "@/config/index.js";
+import { CircuitBreaker } from "@/framework/circuit-breaker/cb.js";
+import { logger } from "@/framework/support/logger.js";
+
+type MailPayload = {
+  to: string;
+  subject: string;
+  html?: string;
+  text?: string;
+};
+
+const transport = nodemailer.createTransport({
+  host: mailConfig.host,
+  port: mailConfig.port,
+  secure: mailConfig.encryption === "ssl",
+  auth: mailConfig.username ? { user: mailConfig.username, pass: mailConfig.password } : undefined
+});
+
+const mailBreaker = new CircuitBreaker();
+
+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 the fail-silent setting.
+   */
+  async sendMail(payload: MailPayload) {
+    try {
+      return await mailBreaker.exec(() =>
+        transport.sendMail({
+          from: mailConfig.fromAddress,
+          ...payload
+        })
+      );
+    } catch (error) {
+      logger.error("Mail send failed", {
+        to: payload.to,
+        subject: payload.subject,
+        error: error instanceof Error ? error.message : error
+      });
+
+      if (!mailConfig.failSilent) throw error;
+      return null;
+    }
+  }
+};

package/hono/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/hono/src/framework/support/url.ts

@@ -0,0 +1,41 @@
+import { appConfig } from "@/config/index.js";
+import { hasUiBuild } from "@/framework/http/static.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 the configured app URL.
+   */
+  appUrl() {
+    return appConfig.url.replace(/\/$/, "");
+  },
+
+  /**
+   * Why: Builds absolute URL pointing at the SPA page that handles the path.
+   * When: Creating links for emails / external callbacks (reset, verify).
+   * Where: Auth/password reset and integrations.
+   * How: Three independent knobs decide the origin —
+   *      appConfig.frontendUrl: the SPA is a separate build/origin (dev Vite
+   *          dev server, or a separately deployed SPA). Link there.
+   *      appConfig.uiEnabled + hasUiBuild(): the framework serves the built
+   *          SPA itself, so the page resolves to the app origin.
+   *      appConfig.uiEnabled + no UI build: the Vite dev server is still
+   *          running (UI not built yet) — use the origin the maker-cli
+   *          injected (NEXWIRE_FRONTEND_URL, dev Vite dev server).
+   *      When BOTH origin knobs are unset (API-only mode) there is no SPA to
+   *          point at — fall back to the app URL so the link is valid.
+   */
+  url(path = "") {
+    const base =
+      appConfig.frontendUrl ||                                // explicit SPA origin — wins
+      (appConfig.uiEnabled
+        ? hasUiBuild()
+          ? urls.appUrl()                                     // built SPA, framework serves it — same origin
+          : process.env.NEXWIRE_FRONTEND_URL || urls.appUrl()  // dev Vite dev server — injected by maker-cli
+        : appConfig.url);                                     // API-only
+    if (!path) return base;
+    return `${base}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+};

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

@@ -0,0 +1,98 @@
+import { eq } from "drizzle-orm";
+import type { Context, Next } from "hono";
+import { cookie, db, jwt, HttpStatusCodes } from "@/framework/facade.js";
+import { refreshTokens, users } from "@/modules/auth/database/models/user.js";
+
+export async function authMiddleware(c: Context, next: Next) {
+  const accessToken = await 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" }, HttpStatusCodes.UNAUTHORIZED);
+      }
+
+      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 = await cookie.getRefresh(c);
+
+  if (!refreshToken) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Unauthorized" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+
+  const refreshPayload = await jwt.verifyToken(refreshToken, "refresh");
+
+  if (!refreshPayload?.jti) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Invalid token" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+
+  const storedToken = await db.query.refreshTokens.findFirst({
+    where: eq(refreshTokens.jti, refreshPayload.jti as string)
+  });
+
+  if (!storedToken || storedToken.revoked) {
+    cookie.deleteAuth(c);
+    cookie.deleteRefresh(c);
+    return c.json({ message: "Invalid token" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+
+  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" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+
+  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" }, HttpStatusCodes.UNAUTHORIZED);
+  }
+
+  const newAccessToken = await jwt.generateToken(
+    {
+      id: user.id,
+      email: user.email,
+      roleId: user.role?.id ?? null,
+      role: user.role?.name ?? null
+    },
+    "access"
+  );
+
+  await 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/hono/src/middlewares/role-middleware.ts

@@ -0,0 +1,25 @@
+import type { Context, Next } from "hono";
+import { HttpStatusCodes } from "@/framework/facade.js";
+
+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" }, HttpStatusCodes.UNAUTHORIZED);
+    }
+
+    const userRole = String(auth.role ?? "").toLowerCase();
+    if (!roles.includes(userRole)) {
+      return c.json({ message: "Forbidden: Insufficient permissions" }, HttpStatusCodes.FORBIDDEN);
+    }
+
+    return await next();
+  };
+}