create-nexwire 4.2.2 → 4.2.4

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

@@ -0,0 +1,139 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import type { AuthProvider, NotificationProvider } from "./contracts.js";
+import { loadProviders } from "./loader.js";
+import { getAuthProvider, getNotificationProvider } 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 | string) {
+        try {
+          const user = await (db.query.users.findFirst as any)?.({
+            where: eq(users.id, id as any),
+            with: { role: true }
+          });
+          if (user) return user;
+        } catch {}
+        try {
+          const rows = await db.select().from(users).where(eq(users.id, id as any));
+          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 | string) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
+        } catch {}
+      },
+      async revokeRefreshToken(tokenId: number | string) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
+        } 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 | string) {
+        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;
+}
+
+/**
+ * Why: Resolves the notification storage provider.
+ * When: `notify()` persists a notification; the HTTP handlers read it back.
+ * Where: Notification runtime and the generated notification controller.
+ * How: Provider files are loaded first, so a project can replace the store from
+ *      `src/providers/` or a module provider folder. The notification module is
+ *      opt-in, so an absent provider is a normal state: callers warn once
+ *      (runtime) or answer 503 (HTTP) instead of throwing.
+ */
+export async function resolveNotificationProvider(): Promise<NotificationProvider | null> {
+  await loadProviders();
+  return getNotificationProvider();
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Why: Defines the shapes a pluggable provider has to satisfy.
+ * When: A developer replaces a framework default (auth, notifications, 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 of the built-in notification storage provider. */
+export const NOTIFICATION_PROVIDER_KEY = "notification";
+
+/**
+ * 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 | typeof NOTIFICATION_PROVIDER_KEY | (string & {});
+
+export interface AuthProviderUser {
+  id: number | string;
+  email?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthProviderRefreshToken {
+  id: number | string;
+  jti: string;
+  revoked?: boolean | null;
+  expiresAt?: Date | string | null;
+  userId?: number | string | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContext {
+  id: number | string;
+  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 | string): Promise<AuthProviderUser | null>;
+  findRefreshToken(jti: string): Promise<AuthProviderRefreshToken | null>;
+  revokeRefreshToken?(tokenId: number | string): Promise<void>;
+  deleteRefreshToken?(tokenId: number | string): Promise<void>;
+  getAuthContext?(user: AuthProviderUser, payload?: any): Promise<AuthUserContext | any>;
+  getUserContact?(userId: number | string): Promise<AuthUserContact | null>;
+}
+
+/**
+ * Who a notification belongs to. `id` accepts a numeric auth id and a string
+ * id (UUID, ULID, ...) so replacing auth does not force a notification change.
+ * The provider always stores the id as text.
+ */
+export interface NotifiableTarget {
+  /** Notifiable class. Defaults to "user". */
+  type?: string;
+  id: number | string;
+}
+
+/** Payload accepted by `NotificationProvider.create()`. */
+export interface NotificationCreateInput {
+  type?: string;
+  title: string;
+  body?: string | null;
+  link?: string | null;
+  data?: Record<string, unknown> | null;
+}
+
+/** Normalized notification returned by every provider operation. */
+export interface NotificationRecord {
+  id: string;
+  notifiableType: string;
+  notifiableId: string;
+  type: string;
+  title: string;
+  body: string | null;
+  data: Record<string, unknown> | null;
+  link: string | null;
+  readAt: string | null;
+  createdAt: string;
+}
+
+export interface NotificationListOptions {
+  page?: number;
+  perPage?: number;
+}
+
+export interface NotificationPage {
+  data: NotificationRecord[];
+  total: number;
+  unread: number;
+  page: number;
+  perPage: number;
+}
+
+/**
+ * Why: Keeps notification storage replaceable without touching `notify()` or
+ *      the generated HTTP routes.
+ * When: The default `src/modules/notification` store is replaced by a custom
+ *       implementation (a different table, another service, ...).
+ * Where: Registered through `registerNotificationProvider()`.
+ * How: The framework only reads through this contract; mail and realtime
+ *      delivery stay in the runtime so a storage swap cannot disable them.
+ */
+export interface NotificationProvider {
+  create(target: NotifiableTarget, input: NotificationCreateInput): Promise<NotificationRecord>;
+  list(target: NotifiableTarget, options?: NotificationListOptions): Promise<NotificationPage>;
+  unreadCount(target: NotifiableTarget): Promise<number>;
+  markRead(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  markAllRead(target: NotifiableTarget): Promise<number>;
+  remove(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  /** Optional bulk cleanup when a notifiable target is deleted. */
+  deleteForTarget?(target: NotifiableTarget): Promise<number>;
+}

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,88 @@
+import {
+  AUTH_PROVIDER_KEY,
+  type AuthProvider,
+  NOTIFICATION_PROVIDER_KEY,
+  type NotificationProvider,
+  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);
+}
+
+/** Registers the storage provider `notify()` and `/api/notification/*` use. */
+export function registerNotificationProvider(provider: NotificationProvider): NotificationProvider {
+  return registerProvider(NOTIFICATION_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered notification provider, or null when none was registered. */
+export function getNotificationProvider(): NotificationProvider | null {
+  return getProvider<NotificationProvider>(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Reports whether a notification provider is registered. */
+export function hasNotificationProvider(): boolean {
+  return hasProvider(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Removes the registered notification provider. Mainly useful in tests. */
+export function clearNotificationProvider(): void {
+  clearProvider(NOTIFICATION_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();
 }