@terreno/api 0.1.0 → 0.3.0

package/src/betterAuthSetup.ts

@@ -0,0 +1,251 @@
+/**
+ * Better Auth setup and initialization for @terreno/api.
+ *
+ * This module provides functions to initialize Better Auth with MongoDB,
+ * create session middleware, and sync users with the application User model.
+ */
+
+import {betterAuth} from "better-auth";
+import {mongodbAdapter} from "better-auth/adapters/mongodb";
+import {toNodeHandler} from "better-auth/node";
+import type {Application, NextFunction, Request, Response} from "express";
+import mongoose from "mongoose";
+import type {UserModel} from "./auth";
+import type {BetterAuthConfig, BetterAuthSessionData, BetterAuthUser} from "./betterAuth";
+import {logger} from "./logger";
+
+/**
+ * The Better Auth instance type.
+ */
+export type BetterAuthInstance = ReturnType<typeof betterAuth>;
+
+/**
+ * Options for creating a Better Auth instance.
+ */
+export interface CreateBetterAuthOptions {
+  config: BetterAuthConfig;
+  mongoClient: any;
+  userModel?: UserModel;
+}
+
+/**
+ * Creates a Better Auth instance with MongoDB adapter.
+ */
+export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthInstance => {
+  const {config, mongoClient} = options;
+
+  const secret = config.secret || process.env.BETTER_AUTH_SECRET;
+  if (!secret) {
+    throw new Error("BETTER_AUTH_SECRET must be set in env or config.secret must be provided.");
+  }
+
+  const baseURL = config.baseURL || process.env.BETTER_AUTH_URL;
+  if (!baseURL) {
+    throw new Error("BETTER_AUTH_URL must be set in env or config.baseURL must be provided.");
+  }
+
+  const basePath = config.basePath ?? "/api/auth";
+
+  const socialProviders: Record<string, {clientId: string; clientSecret: string}> = {};
+
+  if (config.googleOAuth) {
+    socialProviders.google = {
+      clientId: config.googleOAuth.clientId,
+      clientSecret: config.googleOAuth.clientSecret,
+    };
+  }
+
+  if (config.appleOAuth) {
+    socialProviders.apple = {
+      clientId: config.appleOAuth.clientId,
+      clientSecret: config.appleOAuth.clientSecret,
+    };
+  }
+
+  if (config.githubOAuth) {
+    socialProviders.github = {
+      clientId: config.githubOAuth.clientId,
+      clientSecret: config.githubOAuth.clientSecret,
+    };
+  }
+
+  const auth = betterAuth({
+    basePath,
+    baseURL,
+    database: mongodbAdapter(mongoClient.db()),
+    emailAndPassword: {
+      enabled: true,
+    },
+    secret,
+    session: {
+      cookieCache: {
+        enabled: true,
+        maxAge: 5 * 60, // 5 minutes
+      },
+    },
+    socialProviders: Object.keys(socialProviders).length > 0 ? socialProviders : undefined,
+    trustedOrigins: config.trustedOrigins ?? [],
+  });
+
+  return auth;
+};
+
+/**
+ * Creates Express middleware that extracts the Better Auth session
+ * and populates req.user with the application User model.
+ */
+export const createBetterAuthSessionMiddleware = (
+  auth: BetterAuthInstance,
+  userModel?: UserModel
+) => {
+  return async (req: Request, _res: Response, next: NextFunction): Promise<void> => {
+    try {
+      const session = await auth.api.getSession({
+        headers: req.headers as Record<string, string>,
+      });
+
+      if (session?.user && session?.session) {
+        const betterAuthUser = session.user as BetterAuthUser;
+
+        if (userModel) {
+          // Look up the application user by betterAuthId
+          const appUser = await userModel.findOne({betterAuthId: betterAuthUser.id});
+          if (appUser) {
+            (req as any).user = appUser;
+            (req as any).betterAuthSession = session;
+          } else {
+            // User exists in Better Auth but not synced yet - create them
+            const newUser = await syncBetterAuthUser(userModel, betterAuthUser);
+            (req as any).user = newUser;
+            (req as any).betterAuthSession = session;
+          }
+        } else {
+          // No user model - just attach the Better Auth user directly
+          (req as any).user = {
+            _id: betterAuthUser.id,
+            admin: false,
+            betterAuthId: betterAuthUser.id,
+            email: betterAuthUser.email,
+            id: betterAuthUser.id,
+            name: betterAuthUser.name,
+          };
+          (req as any).betterAuthSession = session;
+        }
+      }
+
+      next();
+    } catch (error) {
+      logger.debug(`Better Auth session extraction error: ${error}`);
+      next();
+    }
+  };
+};
+
+/**
+ * Syncs a Better Auth user to the application User model.
+ * Creates or updates the user as needed.
+ */
+export const syncBetterAuthUser = async (
+  userModel: UserModel,
+  betterAuthUser: BetterAuthUser,
+  oauthProvider?: string
+): Promise<any> => {
+  try {
+    const existingUser: any = await userModel.findOne({betterAuthId: betterAuthUser.id});
+
+    if (existingUser) {
+      // Update existing user if needed
+      existingUser.email = betterAuthUser.email;
+      if (betterAuthUser.name) {
+        existingUser.name = betterAuthUser.name;
+      }
+      await existingUser.save();
+      return existingUser;
+    }
+
+    // Check if user exists by email (migration case)
+    const userByEmail: any = await userModel.findOne({email: betterAuthUser.email});
+    if (userByEmail) {
+      // Link existing user to Better Auth
+      userByEmail.betterAuthId = betterAuthUser.id;
+      if (oauthProvider) {
+        userByEmail.oauthProvider = oauthProvider;
+      }
+      await userByEmail.save();
+      return userByEmail;
+    }
+
+    // Create new user
+    const newUser: any = new (userModel as any)({
+      admin: false,
+      betterAuthId: betterAuthUser.id,
+      email: betterAuthUser.email,
+      name: betterAuthUser.name || betterAuthUser.email.split("@")[0],
+      oauthProvider: oauthProvider || null,
+    });
+    await newUser.save();
+    logger.info(`Created new user from Better Auth: ${newUser.id}`);
+    return newUser;
+  } catch (error) {
+    logger.error(`Error syncing Better Auth user: ${error}`);
+    throw error;
+  }
+};
+
+/**
+ * Mounts Better Auth routes on the Express app.
+ */
+export const mountBetterAuthRoutes = (
+  app: Application,
+  auth: BetterAuthInstance,
+  basePath = "/api/auth"
+): void => {
+  const handler = toNodeHandler(auth);
+
+  // Mount at the base path with wildcard
+  app.all(`${basePath}/*`, (req, res) => {
+    return handler(req, res);
+  });
+
+  logger.info(`Better Auth routes mounted at ${basePath}/*`);
+};
+
+/**
+ * Gets the MongoDB client from the mongoose connection.
+ */
+export const getMongoClientFromMongoose = (): any => {
+  const connection = mongoose.connection;
+  const client = (connection as any).client;
+  if (!client) {
+    throw new Error("Mongoose is not connected. Ensure MongoDB connection is established first.");
+  }
+  return client;
+};
+
+/**
+ * Sets up Better Auth user sync hooks.
+ * This ensures users created/updated in Better Auth are synced to the application User model.
+ *
+ * Note: Better Auth doesn't have built-in event hooks, so we rely on the session middleware
+ * to create users on first session access.
+ */
+export const setupBetterAuthUserSync = (_auth: BetterAuthInstance, _userModel: UserModel): void => {
+  // Better Auth v1.x doesn't expose event hooks for user creation.
+  // User sync is handled in createBetterAuthSessionMiddleware when a session is accessed.
+  // This function is a placeholder for future versions that may support hooks.
+  logger.debug("Better Auth user sync configured (via session middleware)");
+};
+
+/**
+ * Extracts Better Auth session data from the request.
+ */
+export const getBetterAuthSession = (req: Request): BetterAuthSessionData | null => {
+  return (req as any).betterAuthSession ?? null;
+};
+
+/**
+ * Checks if the request has a valid Better Auth session.
+ */
+export const hasBetterAuthSession = (req: Request): boolean => {
+  return Boolean((req as any).betterAuthSession);
+};

package/src/expressServer.ts

@@ -177,7 +177,7 @@ function initializeRoutes(
   UserModel: UserMongooseModel,
   addRoutes: AddRoutes,
   options: InitializeRoutesOptions = {}
-) {
+): express.Application {
   const app = express();
 
   // TODO: Log a warning when we hit the array limit.
@@ -193,11 +193,10 @@ function initializeRoutes(
     options.addMiddleware(app);
   }
 
-  app.use(express.json());
+  app.use(express.json({limit: "50mb"}));
 
   // Add login/signup/refresh_token before the JWT/auth middlewares
   addAuthRoutes(app, UserModel as any, options?.authOptions);
-
   setupAuth(app as any, UserModel as any);
 
   if (options.logRequests !== false) {
@@ -245,7 +244,7 @@ function initializeRoutes(
 
   addMeRoutes(app, UserModel as any, options?.authOptions);
 
-  // Set up GitHub OAuth if configured
+  // Set up GitHub OAuth if configured (works with JWT auth)
   if (options.githubAuth) {
     setupGitHubAuth(app, UserModel as any, options.githubAuth);
     addGitHubAuthRoutes(app, UserModel as any, options.githubAuth, options.authOptions);
@@ -297,8 +296,8 @@ export interface SetupServerOptions {
   sentryOptions?: Sentry.BunOptions;
 }
 
-// Sets up the routes and returns a function to launch the API.
-export function setupServer(options: SetupServerOptions) {
+// Sets up the routes and returns the app.
+export function setupServer(options: SetupServerOptions): express.Application {
   const UserModel = options.userModel;
   const addRoutes = options.addRoutes;
 

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from "./api";
 export * from "./auth";
+export * from "./betterAuth";
+export * from "./betterAuthApp";
+export * from "./betterAuthSetup";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
@@ -12,6 +15,7 @@ export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./terrenoApp";
 export * from "./terrenoPlugin";
 export * from "./transformers";
 export * from "./utils";

package/src/openApiValidator.ts

@@ -183,7 +183,7 @@ function getAjvInstance(): Ajv {
       useDefaults: true,
       validateSchema: false,
     });
-    addFormats(instance);
+    addFormats(instance as any);
     ajvCache.set(key, instance);
   }
 

package/src/terrenoApp.test.ts

@@ -0,0 +1,201 @@
+import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
+import type express from "express";
+import supertest from "supertest";
+
+import {modelRouter} from "./api";
+import {Permissions} from "./permissions";
+import {TerrenoApp} from "./terrenoApp";
+import type {TerrenoPlugin} from "./terrenoPlugin";
+import {authAsUser, FoodModel, setupDb, UserModel} from "./tests";
+
+describe("TerrenoApp", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+      REFRESH_TOKEN_SECRET: "test-refresh-secret",
+      SESSION_SECRET: "test-session-secret",
+      TOKEN_EXPIRES_IN: "1h",
+      TOKEN_ISSUER: "test-issuer",
+      TOKEN_SECRET: "test-secret",
+    };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe("build", () => {
+    it("returns an express application without listening", () => {
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      }).build();
+
+      expect(app).toBeDefined();
+    });
+
+    it("creates server with custom corsOrigin", () => {
+      const app = new TerrenoApp({
+        corsOrigin: "https://example.com",
+        skipListen: true,
+        userModel: UserModel as any,
+      }).build();
+
+      expect(app).toBeDefined();
+    });
+  });
+
+  describe("start", () => {
+    it("returns an express application with skipListen", () => {
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      }).start();
+
+      expect(app).toBeDefined();
+    });
+  });
+
+  describe("register with modelRouter", () => {
+    let admin: any;
+
+    beforeEach(async () => {
+      [admin] = await setupDb();
+    });
+
+    it("mounts model router at the specified path", async () => {
+      const foodRegistration = modelRouter("/food", FoodModel, {
+        allowAnonymous: true,
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+        sort: "-created",
+      });
+
+      expect(foodRegistration.__type).toBe("modelRouter");
+      expect(foodRegistration.path).toBe("/food");
+
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      })
+        .register(foodRegistration)
+        .build();
+
+      await FoodModel.create({
+        calories: 100,
+        name: "Apple",
+        ownerId: admin._id,
+        source: {name: "Nature"},
+      });
+
+      const agent = await authAsUser(app, "admin");
+      const res = await agent.get("/food").expect(200);
+      expect(res.body.data).toHaveLength(1);
+      expect(res.body.data[0].name).toBe("Apple");
+    });
+
+    it("supports chaining multiple registrations", async () => {
+      const foodRegistration = modelRouter("/food", FoodModel, {
+        allowAnonymous: true,
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+      });
+
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      })
+        .register(foodRegistration)
+        .build();
+
+      expect(app).toBeDefined();
+    });
+  });
+
+  describe("register with plugin", () => {
+    it("calls plugin.register with the express app", () => {
+      const registerFn = mock(() => {});
+      const plugin: TerrenoPlugin = {
+        register: registerFn,
+      };
+
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      })
+        .register(plugin)
+        .build();
+
+      expect(registerFn).toHaveBeenCalledTimes(1);
+      // Verify the plugin received the express app
+      const calledWith = (registerFn.mock.calls as any[][])[0][0];
+      expect(calledWith).toBe(app);
+    });
+  });
+
+  describe("addMiddleware", () => {
+    it("runs request handler middleware", async () => {
+      let middlewareCalled = false;
+      const middleware: express.RequestHandler = (_req, _res, next) => {
+        middlewareCalled = true;
+        next();
+      };
+
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: UserModel as any,
+      })
+        .addMiddleware(middleware)
+        .build();
+
+      await supertest(app).get("/nonexistent").expect(404);
+      expect(middlewareCalled).toBe(true);
+    });
+  });
+
+  describe("modelRouter overload", () => {
+    it("returns ModelRouterRegistration when path is provided", () => {
+      const result = modelRouter("/food", FoodModel, {
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+      });
+
+      expect(result.__type).toBe("modelRouter");
+      expect(result.path).toBe("/food");
+      expect(result.router).toBeDefined();
+    });
+
+    it("returns express.Router when no path is provided", () => {
+      const result = modelRouter(FoodModel, {
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+      });
+
+      // Should be a regular router (function), not a ModelRouterRegistration
+      expect(typeof result).toBe("function");
+      expect((result as any).__type).toBeUndefined();
+    });
+  });
+});