create-nexwire 4.2.1 → 4.2.3

package/express/src/framework/notification/index.ts

@@ -1,10 +1,27 @@
 import { eq } from "drizzle-orm";
 import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 import { mail } from "@/framework/support/mail.js";
-import { notifications } from "@/modules/auth/database/models/notification.js";
-import { users } from "@/modules/auth/database/models/user.js";
+
+let notifications: any = null;
+let modelsLoaded = false;
+let modelsLoadAttempted = false;
+
+async function loadNotificationModel() {
+  if (modelsLoaded) return true;
+  if (modelsLoadAttempted) return false;
+  modelsLoadAttempted = true;
+  try {
+    const notificationMod = await import("@/modules/auth/database/models/notification.js").catch(() => null);
+    if (notificationMod?.notifications) notifications = notificationMod.notifications;
+    modelsLoaded = !!notifications;
+    return modelsLoaded;
+  } catch {
+    return false;
+  }
+}
 
 /** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
 export type NotificationOptions = {
@@ -22,6 +39,8 @@ export type NotificationOptions = {
   broadcast?: boolean;
   /** Email delivery options */
   mail?: {
+    /** Explicit recipient. Skips the auth provider contact lookup. */
+    to?: string;
     subject?: string;
     html?: string;
   };
@@ -29,6 +48,13 @@ export type NotificationOptions = {
 
 /** Create a notification and persist it to the database. Optionally broadcast via Socket.IO and/or send by email. */
 export async function notify(userId: number, options: NotificationOptions) {
+  const ok = await loadNotificationModel();
+  if (!ok || !notifications) {
+    console.warn(
+      "[notification] skipped: notification model not available (@/modules/auth/database/models/notification.js). Delete or replace auth/notification without breaking framework."
+    );
+    return null;
+  }
   const insertResult = await db.insert(notifications).values({
     userId,
     type: options.type || "info",
@@ -63,9 +89,39 @@ async function sendMailChannel(
   notification: { id: number; title: string; body: string | null },
   options: NotificationOptions
 ) {
-  const [user] = await db.select({ email: users.email, name: users.name }).from(users).where(eq(users.id, userId));
+  let to: string | null = (options.mail as any)?.to || null;
+  let name: string | null = null;
+
+  if (!to) {
+    try {
+      const provider = await resolveAuthProvider();
+      if (provider?.getUserContact) {
+        const contact = await provider.getUserContact(userId);
+        if (contact?.email) {
+          to = contact.email as string;
+          name = (contact.name as string) || null;
+        }
+      }
+    } catch {}
+  }
+
+  if (!to) {
+    try {
+      const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
+      if (userMod?.users) {
+        const [user] = await db
+          .select({ email: userMod.users.email, name: (userMod.users as any).name })
+          .from(userMod.users)
+          .where(eq(userMod.users.id, userId));
+        if (user?.email) {
+          to = user.email as string;
+          name = (user as any).name || null;
+        }
+      }
+    } catch {}
+  }
 
-  if (!user?.email) return;
+  if (!to) return;
 
   const subject = options.mail?.subject || notification.title;
   const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
@@ -74,14 +130,14 @@ async function sendMailChannel(
     await dispatchEvent(
       "notification:mail",
       {
-        to: user.email,
+        to,
         subject,
         html
       },
       { queue: "mail" }
     );
   } else {
-    await mail.sendMail({ to: user.email, subject, html });
+    await mail.sendMail({ to, subject, html });
   }
 }
 
@@ -95,7 +151,7 @@ function escapeHtml(str: string) {
 }
 
 /** Convert a DB row into the normalized response shape, parsing the `data` JSON column. */
-function normalize(row: typeof notifications.$inferSelect) {
+function normalize(row: any) {
   let parsed: unknown = null;
   if (row.data) {
     try {

package/express/src/framework/providers/adapter.ts

@@ -0,0 +1,125 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import type { AuthProvider } from "./contracts.js";
+import { loadProviders } from "./loader.js";
+import { getAuthProvider } from "./registry.js";
+
+let defaultProvider: AuthProvider | null = null;
+let defaultLoadAttempted = false;
+
+/**
+ * Why: Builds the built-in auth provider from the default auth module.
+ * When: No custom provider was registered by the application.
+ * Where: Auth provider adapter.
+ * How: Lazily imports the default user/refresh-token models. When the default
+ *      auth module was deleted or replaced, no provider is produced.
+ */
+async function loadDefaultProvider(): Promise<AuthProvider | null> {
+  if (defaultProvider) return defaultProvider;
+  if (defaultLoadAttempted) return null;
+  defaultLoadAttempted = true;
+  try {
+    const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
+    if (!userMod?.users || !userMod?.refreshTokens) return null;
+
+    const users = userMod.users;
+    const refreshTokens = userMod.refreshTokens;
+
+    defaultProvider = {
+      async getUserById(id: number) {
+        try {
+          const user = await (db.query.users.findFirst as any)?.({
+            where: eq(users.id, id),
+            with: { role: true }
+          });
+          if (user) return user;
+        } catch {}
+        try {
+          const rows = await db.select().from(users).where(eq(users.id, id));
+          return rows?.[0] ?? null;
+        } catch {
+          return null;
+        }
+      },
+      async findRefreshToken(jti: string) {
+        try {
+          const token = await (db.query.refreshTokens.findFirst as any)?.({
+            where: eq(refreshTokens.jti, jti)
+          });
+          if (token) return token;
+        } catch {}
+        try {
+          const rows = await db.select().from(refreshTokens).where(eq(refreshTokens.jti, jti));
+          return rows?.[0] ?? null;
+        } catch {
+          return null;
+        }
+      },
+      async deleteRefreshToken(tokenId: number) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+        } catch {}
+      },
+      async revokeRefreshToken(tokenId: number) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+        } catch {}
+      },
+      async getAuthContext(user: any, payload?: any) {
+        try {
+          if (user?.role && typeof user.role === "object") {
+            return {
+              ...(payload || {}),
+              id: user.id,
+              email: user.email,
+              roleId: user.role?.id ?? null,
+              role: user.role?.name ?? null,
+              ...user
+            };
+          }
+        } catch {}
+        return {
+          ...(payload || {}),
+          id: user.id,
+          email: user.email,
+          roleId: user.roleId ?? null,
+          role: user.role ?? null,
+          ...user
+        };
+      },
+      async getUserContact(userId: number) {
+        try {
+          const user = await this.getUserById(userId);
+          if (!user) return null;
+          return {
+            email: user.email ?? null,
+            name: user.name ?? user.fullName ?? user.username ?? null,
+            phone: user.phone ?? user.phoneNumber ?? null
+          };
+        } catch {
+          return null;
+        }
+      }
+    };
+    return defaultProvider;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why: Resolves the auth provider the framework should use.
+ * When: The auth middleware or the notification mailer needs user data.
+ * Where: Auth provider adapter.
+ * How: Application providers are loaded first, so a file in `src/providers/`
+ *      wins. Otherwise the built-in provider from the default auth module is
+ *      used. When neither exists the framework degrades gracefully.
+ */
+export async function resolveAuthProvider(): Promise<AuthProvider | null> {
+  await loadProviders();
+  const registered = getAuthProvider();
+  if (registered) return registered;
+  const def = await loadDefaultProvider();
+  if (def) return def;
+  return null;
+}

package/express/src/framework/providers/contracts.ts

@@ -0,0 +1,56 @@
+/**
+ * Why: Defines the shapes a pluggable provider has to satisfy.
+ * When: A developer replaces a framework default (auth today, payments later).
+ * Where: Imported through the framework facade, never from framework internals.
+ * How: Interfaces stay deliberately loose so custom user shapes pass through.
+ */
+
+/** Registry key of the built-in auth provider contract. */
+export const AUTH_PROVIDER_KEY = "auth";
+
+/**
+ * Registry key for any provider implementation.
+ *
+ * `string & {}` keeps the literal keys above discoverable by editors while
+ * still accepting any custom key, so a project can register its own contracts
+ * (payments, otp, storage, ...) without the framework having to know them.
+ */
+export type ProviderKey = typeof AUTH_PROVIDER_KEY | (string & {});
+
+export interface AuthProviderUser {
+  id: number;
+  email?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthProviderRefreshToken {
+  id: number;
+  jti: string;
+  revoked?: boolean | null;
+  expiresAt?: Date | string | null;
+  userId?: number | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContext {
+  id: number;
+  email?: string | null;
+  roleId?: number | null;
+  role?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContact {
+  email?: string | null;
+  name?: string | null;
+  phone?: string | null;
+}
+
+export interface AuthProvider {
+  getUserById(id: number): Promise<AuthProviderUser | null>;
+  findRefreshToken(jti: string): Promise<AuthProviderRefreshToken | null>;
+  revokeRefreshToken?(tokenId: number): Promise<void>;
+  deleteRefreshToken?(tokenId: number): Promise<void>;
+  getAuthContext?(user: AuthProviderUser, payload?: any): Promise<AuthUserContext | any>;
+  getUserContact?(userId: number): Promise<AuthUserContact | null>;
+}

package/express/src/framework/providers/loader.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { glob } from "glob";
+import { discoverModuleFiles } from "@/framework/modules/discover.js";
+import { logger } from "@/framework/support/logger.js";
+
+/**
+ * Why: Finds the app-level provider folder for the running code.
+ * When: Providers are loaded at boot.
+ * Where: Provider loader.
+ * How: Mirrors the module discovery rule — `src/providers` in development,
+ *      `dist/src/providers` when the compiled server is the entrypoint.
+ */
+function resolveProvidersPath() {
+  const cwd = process.cwd();
+  const srcProviders = path.resolve(cwd, "src/providers");
+  const distProviders = path.resolve(cwd, "dist/src/providers");
+  const entry = String(process.argv[1] || "");
+  const runningDist = /[\\/]dist[\\/]/.test(entry);
+
+  if (runningDist && fs.existsSync(distProviders)) return distProviders;
+  return srcProviders;
+}
+
+export const providersPath = resolveProvidersPath();
+
+let loadPromise: Promise<number> | null = null;
+let loading = false;
+
+/**
+ * Why: Collects every provider file that should run at boot.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Globs `src/providers/**` for app-wide providers, and
+ *      `src/modules/**\/providers.ts` plus `src/modules/**\/providers/*.ts` for
+ *      module-scoped ones. Tests and declaration files are ignored.
+ */
+async function collectProviderFiles(): Promise<string[]> {
+  const files: string[] = [];
+
+  if (fs.existsSync(providersPath)) {
+    const appFiles = await glob("**/*.{ts,js,mjs}", {
+      cwd: providersPath,
+      absolute: true,
+      nodir: true,
+      ignore: ["**/__tests__/**", "**/*.d.ts", "**/*.test.*", "**/*.spec.*"],
+      windowsPathsNoEscape: true
+    });
+    files.push(...appFiles);
+  }
+
+  try {
+    // A module plugs its own implementation in either from a single file
+    // (providers.ts) or from a folder (providers/*.ts). Both are imported.
+    const moduleFiles = await discoverModuleFiles("**/providers.{ts,js}");
+    const moduleProviderFiles = await discoverModuleFiles("**/providers/*.{ts,js}");
+    files.push(...moduleFiles, ...moduleProviderFiles);
+  } catch {}
+
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Why: Imports each discovered provider file so its registration runs.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Imports in sorted order; a broken file is logged and skipped instead of
+ *      taking the whole application down.
+ */
+async function loadProviderFiles(): Promise<number> {
+  const files = await collectProviderFiles();
+
+  for (const file of files) {
+    try {
+      await import(pathToFileURL(file).href);
+    } catch (error) {
+      logger.warn("Provider file failed to load", {
+        file,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return files.length;
+}
+
+/**
+ * Why: Runs the application's provider files exactly once.
+ * When: The kernel boots, and on the first provider lookup.
+ * Where: Kernel startup and the auth provider adapter.
+ * How: Caches the promise so repeated lookups cost nothing. A provider file
+ *      that itself asks for a provider during load gets an immediate answer
+ *      instead of deadlocking on its own load.
+ */
+export async function loadProviders(): Promise<number> {
+  if (loading) return 0;
+  if (!loadPromise) {
+    loading = true;
+    loadPromise = loadProviderFiles().finally(() => {
+      loading = false;
+    });
+  }
+  return loadPromise;
+}

package/express/src/framework/providers/registry.ts

@@ -0,0 +1,62 @@
+import { AUTH_PROVIDER_KEY, type AuthProvider, type ProviderKey } from "./contracts.js";
+
+/**
+ * Why: Holds the app-wide provider implementations in one place.
+ * When: A provider file in `src/providers/` (or a module's `providers.ts`)
+ *       registers its implementation at boot.
+ * Where: Read by the framework through `resolve*Provider()` helpers.
+ * How: A plain key/value map. No container, no decorators, no auto-wiring.
+ */
+const registry = new Map<string, unknown>();
+
+/**
+ * Why: Registers a provider implementation under a key.
+ * When: A provider file runs at boot and claims a contract.
+ * Where: Application code, through the framework facade.
+ * How: Stores the implementation and returns it so it can be inlined.
+ */
+export function registerProvider<T>(key: ProviderKey, implementation: T): T {
+  registry.set(key, implementation);
+  return implementation;
+}
+
+/** Returns the registered implementation for a key, or null when absent. */
+export function getProvider<T = unknown>(key: ProviderKey): T | null {
+  const found = registry.get(key);
+  return (found as T) ?? null;
+}
+
+/** Reports whether a provider is registered for a key. */
+export function hasProvider(key: ProviderKey): boolean {
+  return registry.has(key);
+}
+
+/** Removes a registered provider. Mainly useful in tests. */
+export function clearProvider(key: ProviderKey): void {
+  registry.delete(key);
+}
+
+/** Lists every registered provider key, sorted for stable output. */
+export function listProviders(): string[] {
+  return [...registry.keys()].sort();
+}
+
+/** Registers the auth provider that the framework's auth middleware uses. */
+export function registerAuthProvider(provider: AuthProvider): AuthProvider {
+  return registerProvider(AUTH_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered auth provider, or null when none was registered. */
+export function getAuthProvider(): AuthProvider | null {
+  return getProvider<AuthProvider>(AUTH_PROVIDER_KEY);
+}
+
+/** Reports whether a custom auth provider is registered. */
+export function hasAuthProvider(): boolean {
+  return hasProvider(AUTH_PROVIDER_KEY);
+}
+
+/** Removes the registered auth provider. Mainly useful in tests. */
+export function clearAuthProvider(): void {
+  clearProvider(AUTH_PROVIDER_KEY);
+}

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

@@ -1,19 +1,23 @@
-import { eq } from "drizzle-orm";
 import { type NextFunction, type Request, type Response } from "express";
-import { cookie, db, HttpStatusCodes, jwt } from "@/framework/facade.js";
-import { refreshTokens, users } from "@/modules/auth/database/models/user.js";
+import { cookie, HttpStatusCodes, jwt } from "@/framework/facade.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
 
 export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const provider = await resolveAuthProvider();
+  if (!provider) {
+    console.warn(
+      "[auth-middleware] auth provider not available; skipping auth. Register one in src/providers/ or restore src/modules/auth."
+    );
+    return next();
+  }
+
   const accessToken = await cookie.getAuth(req);
 
   if (accessToken) {
-    const accessPayload = await jwt.verifyToken(accessToken, "access");
+    const accessPayload: any = 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 }
-      });
+      const user = await provider.getUserById((accessPayload as any)?.id);
 
       if (!user) {
         cookie.deleteAuth(res);
@@ -21,13 +25,20 @@ export async function authMiddleware(req: Request, res: Response, next: NextFunc
         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
-      };
+      let authCtx: any;
+      if (provider.getAuthContext) {
+        authCtx = await provider.getAuthContext(user, accessPayload);
+      } else {
+        authCtx = {
+          ...(accessPayload || {}),
+          id: (user as any).id,
+          email: (user as any).email,
+          roleId: (user as any).role?.id ?? (user as any).roleId ?? null,
+          role: (user as any).role?.name ?? (user as any).role ?? null,
+          ...(user as any)
+        };
+      }
+      res.locals.auth = authCtx;
       return next();
     }
   }
@@ -40,7 +51,7 @@ export async function authMiddleware(req: Request, res: Response, next: NextFunc
     return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
   }
 
-  const refreshPayload = await jwt.verifyToken(refreshToken, "refresh");
+  const refreshPayload: any = await jwt.verifyToken(refreshToken, "refresh");
 
   if (!refreshPayload?.jti) {
     cookie.deleteAuth(res);
@@ -48,27 +59,27 @@ export async function authMiddleware(req: Request, res: Response, next: NextFunc
     return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Invalid token" });
   }
 
-  const storedToken = await db.query.refreshTokens.findFirst({
-    where: eq(refreshTokens.jti, refreshPayload.jti as string)
-  });
+  const storedToken = await provider.findRefreshToken((refreshPayload as any)?.jti);
 
-  if (!storedToken || storedToken.revoked) {
+  if (!storedToken || (storedToken as any).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 expiresAt = (storedToken as any).expiresAt;
+  if (expiresAt) {
+    const exp = expiresAt instanceof Date ? expiresAt.getTime() : new Date(expiresAt).getTime();
+    if (!Number.isNaN(exp) && exp < Date.now()) {
+      if (provider.deleteRefreshToken) await provider.deleteRefreshToken((storedToken as any).id);
+      else if (provider.revokeRefreshToken) await provider.revokeRefreshToken((storedToken as any).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 }
-  });
+  const user = await provider.getUserById((refreshPayload as any)?.id);
 
   if (!user) {
     cookie.deleteAuth(res);
@@ -76,23 +87,39 @@ export async function authMiddleware(req: Request, res: Response, next: NextFunc
     return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
   }
 
+  let baseCtx: any;
+  if (provider.getAuthContext) {
+    baseCtx = await provider.getAuthContext(user, refreshPayload);
+  } else {
+    baseCtx = {
+      ...(refreshPayload || {}),
+      id: (user as any).id,
+      email: (user as any).email,
+      roleId: (user as any).role?.id ?? (user as any).roleId ?? null,
+      role: (user as any).role?.name ?? (user as any).role ?? null,
+      ...(user as any)
+    };
+  }
+
   const newAccessToken = await jwt.generateToken(
     {
-      id: user.id,
-      email: user.email,
-      roleId: user.role?.id ?? null,
-      role: user.role?.name ?? null
+      id: (user as any).id,
+      email: (user as any).email,
+      roleId: baseCtx?.roleId ?? (user as any).role?.id ?? (user as any).roleId ?? null,
+      role: baseCtx?.role ?? (user as any).role?.name ?? (user as any).role ?? 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"
+    ...(baseCtx || {}),
+    id: (user as any).id,
+    email: (user as any).email,
+    roleId: baseCtx?.roleId ?? (user as any).role?.id ?? (user as any).roleId ?? null,
+    role: baseCtx?.role ?? (user as any).role?.name ?? (user as any).role ?? null,
+    type: "access",
+    ...(user as any)
   };
   return next();
 }