create-nexwire 4.0.0

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

@@ -0,0 +1,62 @@
+import type { Request, Response } from "express";
+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 = {
+  async setAuth(res: Response, token: string) {
+    res.cookie(`${cookieConfig.name}_access`, token, {
+      ...baseOptions(),
+      maxAge: jwtConfig.accessExpirySeconds * 1000,
+      signed: true
+    });
+  },
+
+  async setRefresh(res: Response, token: string, maxAge?: number) {
+    res.cookie(`${cookieConfig.name}_refresh`, token, {
+      ...baseOptions(),
+      maxAge: (typeof maxAge === "number" ? maxAge : jwtConfig.refreshExpirySeconds) * 1000,
+      signed: true
+    });
+  },
+
+  async getAuth(req: Request) {
+    return req.signedCookies?.[`${cookieConfig.name}_access`];
+  },
+
+  async getRefresh(req: Request) {
+    return req.signedCookies?.[`${cookieConfig.name}_refresh`];
+  },
+
+  deleteAuth(res: Response) {
+    res.clearCookie(`${cookieConfig.name}_access`, { path: "/" });
+  },
+
+  deleteRefresh(res: Response) {
+    res.clearCookie(`${cookieConfig.name}_refresh`, { path: "/" });
+  }
+};

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

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import jwtLib from "jsonwebtoken";
+import { jwtConfig } from "@/config/index.js";
+
+export const jwt = {
+  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 jwtLib.sign(tokenPayload, secret, { algorithm: jwtConfig.algorithm });
+
+    return { token, jti, exp };
+  },
+
+  async verifyToken(token: string, type: "access" | "refresh") {
+    try {
+      const secret = type === "refresh" ? jwtConfig.refreshSecret : jwtConfig.accessSecret;
+      const payload = (await jwtLib.verify(token, secret, { algorithms: [jwtConfig.algorithm] })) as Record<string, unknown>;
+      return payload.type === type ? payload : null;
+    } catch {
+      return null;
+    }
+  }
+};

package/express/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/express/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/express/src/framework/support/mail.ts

@@ -0,0 +1,48 @@
+import nodemailer from "nodemailer";
+import { mailConfig } from "@/config/index.js";
+import { logger } from "@/framework/support/logger.js";
+import { CircuitBreaker } from "@/framework/circuit-breaker/cb.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/express/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/express/src/framework/support/upload.ts

@@ -0,0 +1,160 @@
+import path from "node:path";
+import type { RequestHandler } from "express";
+import createError from "http-errors";
+import multer from "multer";
+
+export type UploadOptions = {
+  /**
+   * Form field name that carries the file(s). Matches the client's FormData key.
+   */
+  field: string;
+  /**
+   * When set, accepts an array of up to `multiple` files on that field.
+   * Omit for a single-file upload (parsed into `req.file`).
+   */
+  multiple?: number;
+  /**
+   * Maximum allowed file size in bytes. Defaults to unlimited.
+   */
+  maxSize?: number;
+  /**
+   * Allowed file extensions (lowercase, with dot), e.g. [".xlsx", ".xlsb"].
+   * Rejects others with a 422 message.
+   */
+  allowedExtensions?: string[];
+  /**
+   * Allowed MIME types, e.g. ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"].
+   * When provided alongside extensions, a file must satisfy both.
+   */
+  allowedMimeTypes?: string[];
+};
+
+export type UploadFieldsSpec = Array<{ name: string; maxCount?: number }>;
+
+function humanSize(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
+  let size = bytes;
+  while (size >= 1024 && i < units.length - 1) {
+    size /= 1024;
+    i += 1;
+  }
+  return `${Math.round(size * 100) / 100} ${units[i]}`;
+}
+
+/**
+ * Why: Parses multipart uploads as a reusable Express middleware factory.
+ * When: Any route needs to accept file uploads (single, multiple, or labeled fields).
+ * Where: Route files via `.api(route, [requireRole(...), upload({...})], handler)`.
+ * How: Wraps `multer` (memory storage) so controllers receive `req.file` /
+ *      `req.files` buffers and enforce size/extension/MIME rules; failures are
+ *      normalized into readable 422 errors before the controller runs.
+ */
+export function upload(options: UploadOptions): RequestHandler {
+  const { field, multiple, maxSize, allowedExtensions, allowedMimeTypes } = options;
+  const maxCount = multiple ?? 1;
+
+  const parser = multer({
+    storage: multer.memoryStorage(),
+    limits: {
+      fileSize: maxSize ?? Infinity,
+      files: maxCount
+    },
+    fileFilter: (_req, file, cb) => {
+      const ext = path.extname(file.originalname).toLowerCase();
+      if (allowedExtensions?.length && !allowedExtensions.includes(ext)) {
+        cb(createError(422, `File must be ${allowedExtensions.join(" or ")}`));
+        return;
+      }
+      if (allowedMimeTypes?.length && !allowedMimeTypes.includes(file.mimetype)) {
+        cb(createError(422, `File type ${file.mimetype} is not allowed`));
+        return;
+      }
+      cb(null, true);
+    }
+  });
+
+  const parse = multiple ? parser.array(field, maxCount) : parser.single(field);
+
+  return (req, res, next) => {
+    parse(req, res, (error) => {
+      if (error) {
+        if (error instanceof multer.MulterError) {
+          if (error.code === "LIMIT_FILE_SIZE") {
+            next(createError(422, `File size must be less than ${humanSize(maxSize ?? 0)}`));
+            return;
+          }
+          if (error.code === "LIMIT_FILE_COUNT" || error.code === "LIMIT_UNEXPECTED_FILE") {
+            next(createError(422, `Too many files, max ${maxCount} allowed`));
+            return;
+          }
+          next(createError(422, error.message));
+          return;
+        }
+        next(error);
+        return;
+      }
+
+      const received = multiple ? Array.isArray(req.files) && req.files.length > 0 : Boolean(req.file);
+
+      if (!received) {
+        next(createError(422, "File required"));
+        return;
+      }
+
+      next();
+    });
+  };
+}
+
+/**
+ * Why: Parses multipart forms carrying multiple labeled file fields at once.
+ * When: A form uploads several different inputs (e.g. avatar + document) in one request.
+ * Where: Route files via `.api(route, [fields([{ name: "avatar" }, { name: "docs", maxCount: 5 }])], handler)`.
+ * How: Uses `multer.fields()` and applies shared size/MIME/extension limits to every file.
+ */
+export function fields(spec: UploadFieldsSpec, options: Omit<UploadOptions, "field" | "multiple"> = {}): RequestHandler {
+  const { maxSize, allowedExtensions, allowedMimeTypes } = options;
+
+  const parser = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: maxSize ?? Infinity },
+    fileFilter: (_req, file, cb) => {
+      const ext = path.extname(file.originalname).toLowerCase();
+      if (allowedExtensions?.length && !allowedExtensions.includes(ext)) {
+        cb(createError(422, `File must be ${allowedExtensions.join(" or ")}`));
+        return;
+      }
+      if (allowedMimeTypes?.length && !allowedMimeTypes.includes(file.mimetype)) {
+        cb(createError(422, `File type ${file.mimetype} is not allowed`));
+        return;
+      }
+      cb(null, true);
+    }
+  }).fields(spec);
+
+  return (req, res, next) => {
+    parser(req, res, (error) => {
+      if (error) {
+        if (error instanceof multer.MulterError) {
+          if (error.code === "LIMIT_FILE_SIZE") {
+            next(createError(422, `File size must be less than ${humanSize(maxSize ?? 0)}`));
+            return;
+          }
+          next(createError(422, error.message));
+          return;
+        }
+        next(error);
+        return;
+      }
+
+      const files: Express.Multer.File[] = Object.values((req.files as Record<string, Express.Multer.File[]>) ?? {}).flat();
+      if (files.length === 0) {
+        next(createError(422, "File required"));
+        return;
+      }
+
+      next();
+    });
+  };
+}

package/express/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/express/src/middlewares/auth-middleware.ts

@@ -0,0 +1,98 @@
+import { eq } from "drizzle-orm";
+import { type NextFunction, type Request, type Response } from "express";
+import { cookie, db, jwt, HttpStatusCodes } from "@/framework/facade.js";
+import { refreshTokens, users } from "@/modules/auth/database/models/user.js";
+
+export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const accessToken = await cookie.getAuth(req);
+
+  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(res);
+        cookie.deleteRefresh(res);
+        return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
+      }
+
+      res.locals.auth = {
+        ...accessPayload,
+        id: user.id,
+        email: user.email,
+        roleId: user.role?.id ?? null,
+        role: user.role?.name ?? null
+      };
+      return next();
+    }
+  }
+
+  const refreshToken = await cookie.getRefresh(req);
+
+  if (!refreshToken) {
+    cookie.deleteAuth(res);
+    cookie.deleteRefresh(res);
+    return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
+  }
+
+  const refreshPayload = await jwt.verifyToken(refreshToken, "refresh");
+
+  if (!refreshPayload?.jti) {
+    cookie.deleteAuth(res);
+    cookie.deleteRefresh(res);
+    return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Invalid token" });
+  }
+
+  const storedToken = await db.query.refreshTokens.findFirst({
+    where: eq(refreshTokens.jti, refreshPayload.jti as string)
+  });
+
+  if (!storedToken || storedToken.revoked) {
+    cookie.deleteAuth(res);
+    cookie.deleteRefresh(res);
+    return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Invalid token" });
+  }
+
+  if (storedToken.expiresAt.getTime() < Date.now()) {
+    await db.delete(refreshTokens).where(eq(refreshTokens.id, storedToken.id));
+    cookie.deleteAuth(res);
+    cookie.deleteRefresh(res);
+    return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Invalid token" });
+  }
+
+  const user = await db.query.users.findFirst({
+    where: eq(users.id, refreshPayload.id as number),
+    with: { role: true }
+  });
+
+  if (!user) {
+    cookie.deleteAuth(res);
+    cookie.deleteRefresh(res);
+    return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "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(res, newAccessToken.token);
+  res.locals.auth = {
+    id: user.id,
+    email: user.email,
+    roleId: user.role?.id ?? null,
+    role: user.role?.name ?? null,
+    type: "access"
+  };
+  return next();
+}

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

@@ -0,0 +1,25 @@
+import type { NextFunction, Request, Response } from "express";
+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 (_req: Request, res: Response, next: NextFunction) => {
+    const auth = res.locals.auth as AuthPayload | undefined;
+
+    if (!auth) {
+      return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
+    }
+
+    const userRole = String(auth.role ?? "").toLowerCase();
+    if (!roles.includes(userRole)) {
+      return res.status(HttpStatusCodes.FORBIDDEN).json({ message: "Forbidden: Insufficient permissions" });
+    }
+
+    return next();
+  };
+}