create-nexwire 4.2.2 → 4.2.3

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();
 }

package/express/src/providers/README.md

@@ -0,0 +1,107 @@
+# Providers
+
+Provider files in this folder are imported automatically when the application
+boots. Use them for anything the **whole app** needs — a replacement auth
+implementation, a payment gateway, an SMS driver, a storage backend.
+
+There is no wiring step: drop a file in here and it runs.
+
+## How it works
+
+1. Every `src/providers/**/*.{ts,js,mjs}` file is imported at boot.
+2. Every `src/modules/<module>/providers.ts` file is imported at boot too, so a
+   module can plug itself into the app without the app knowing about it.
+3. Every `src/modules/<module>/providers/*.ts` file is imported at boot as well,
+   for a module that offers more than one implementation.
+4. A provider file claims a contract by registering an implementation.
+
+```ts
+// src/providers/payment.ts
+import { registerProvider } from "@/framework/facade.js";
+
+registerProvider("payment", {
+  async charge(order) {
+    return { id: "ch_123", status: "paid" };
+  }
+});
+```
+
+Read it back the same way:
+
+```ts
+import { getProvider } from "@/framework/facade.js";
+
+const payment = getProvider<any>("payment");
+```
+
+## Generating one
+
+```bash
+npm run maker provider:make payment
+npm run maker module:make-provider billing stripe
+```
+
+`provider:make` writes `src/providers/<name>.ts` for the whole app.
+`module:make-provider` writes `src/modules/<module>/providers/<name>.ts` for a
+single module. Both files register themselves when they are imported.
+
+## Replacing the built-in auth
+
+The framework ships with an auth module under `src/modules/auth`. To replace
+it, delete that folder and register your own auth provider:
+
+```ts
+// src/providers/auth.ts
+import { registerAuthProvider } from "@/framework/facade.js";
+import type { AuthProvider } from "@/framework/facade.js";
+
+const authProvider: AuthProvider = {
+  async getUserById(id) {
+    // Return any user shape you like. Extra fields (tenantId, plan, status, ...)
+    // are passed straight through to `c.get("auth")` / `res.locals.auth`.
+    return { id, email: "user@example.com", tenantId: 42, plan: "pro" };
+  },
+  async findRefreshToken(jti) {
+    // Return the stored refresh token, or null when it is unknown.
+    return { id: 1, jti, revoked: false, expiresAt: new Date() };
+  },
+  async revokeRefreshToken(tokenId) {
+    // Optional. Called when a refresh token is expired or revoked.
+  },
+  async getAuthContext(user, payload) {
+    // Optional. Shapes what handlers receive as the auth context.
+    return { id: user.id, email: user.email, tenantId: user.tenantId };
+  },
+  async getUserContact(userId) {
+    // Optional. Used by `notify()` to find the email address of a user.
+    return { email: "user@example.com", name: "User" };
+  }
+};
+
+registerAuthProvider(authProvider);
+```
+
+Import `registerAuthProvider` and the `AuthProvider` type from
+`@/framework/facade.js` — never from `@/framework/...` internals. The facade is
+the public API of the framework.
+
+## Module-to-module
+
+Modules do not import each other. They talk through:
+
+- `src/modules/<module>/facade.ts` — the public API of a module.
+- `dispatchEvent` / `dispatchCommand` — for cross-module notifications.
+- `src/providers/` — for app-wide implementations.
+
+## Contract reference
+
+| Method                              | Required | Purpose                                                        |
+| ----------------------------------- | -------- | -------------------------------------------------------------- |
+| `getUserById(id)`                   | Yes      | Loads a user. Any extra fields are passed through to the auth context. |
+| `findRefreshToken(jti)`             | Yes      | Loads a stored refresh token by its JWT id.                    |
+| `revokeRefreshToken(id)`            | No       | Revokes a refresh token. `deleteRefreshToken(id)` also works.  |
+| `getAuthContext(user, payload)`     | No       | Shapes the object handlers receive as `auth`.                   |
+| `getUserContact(userId)`            | No       | Finds the email/name of a user, used by notifications.         |
+
+When no provider is registered and `src/modules/auth` was deleted, the auth
+middleware logs a warning and lets the request through instead of crashing.

package/hono/src/database/migrations/sqlite/meta/0000_snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "e2276ee8-13c8-4baf-ab07-32e843a089ac",
+  "id": "a2d9b389-ddab-4eec-bd8c-e0cca638e287",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "notifications": {

package/hono/src/database/migrations/sqlite/meta/_journal.json

@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "6",
-      "when": 1791141088797,
+      "when": 1792609267184,
       "tag": "0000_init",
       "breakpoints": true
     }

package/hono/src/framework/database/app-schema.ts

@@ -0,0 +1,37 @@
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+
+/**
+ * Why: Builds the Drizzle schema from the modules that actually exist.
+ * When: The database connection is initialised.
+ * Where: Framework database connection.
+ * How: Discovers `src/modules/**\/database/models/*` and merges their exports.
+ *      The generated barrel at `src/database/schema.ts` is only used by
+ *      drizzle-kit, so deleting or replacing a module never leaves the
+ *      framework importing a file that is no longer there.
+ */
+let cachedSchema: Record<string, unknown> | null = null;
+
+export async function loadAppSchema(): Promise<Record<string, unknown>> {
+  if (cachedSchema) return cachedSchema;
+
+  const schema: Record<string, unknown> = {};
+  const files = await discoverModuleFiles("**/database/models/*.{ts,js}");
+
+  for (const file of files) {
+    try {
+      const models = await importFile(file);
+      Object.assign(schema, models);
+    } catch {
+      // A model file that fails to load is skipped: the rest of the schema
+      // still works, and the framework keeps booting.
+    }
+  }
+
+  cachedSchema = schema;
+  return schema;
+}
+
+/** Clears the cached schema. Mainly useful in tests. */
+export function clearAppSchema(): void {
+  cachedSchema = null;
+}