@terreno/api 0.0.18 → 0.2.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/errors.ts

@@ -136,21 +136,24 @@ export class APIError extends Error {
 // model.
 export function errorsPlugin(schema: Schema): void {
   const errorSchema = new Schema({
-    code: String,
-    detail: String,
-    id: String,
+    code: {description: "Application-specific error code", type: String},
+    detail: {description: "Human-readable explanation of the error", type: String},
+    id: {description: "Unique identifier for this error occurrence", type: String},
     links: {
-      about: String,
-      type: String,
+      about: {description: "Link to documentation about this error", type: String},
+      type: {description: "Link describing the error type", type: String},
     },
-    meta: Schema.Types.Mixed,
+    meta: {description: "Non-standard meta information about the error", type: Schema.Types.Mixed},
     source: {
-      header: String,
-      parameter: String,
-      pointer: String,
+      header: {description: "HTTP header that caused the error", type: String},
+      parameter: {description: "Query parameter that caused the error", type: String},
+      pointer: {
+        description: "JSON pointer to the request field that caused the error",
+        type: String,
+      },
     },
-    status: Number,
-    title: {required: true, type: String},
+    status: {description: "HTTP status code for this error", type: Number},
+    title: {description: "Short summary of the error", required: true, type: String},
   });
 
   schema.add({apiErrors: errorSchema});

package/src/example.ts

@@ -32,8 +32,8 @@ interface Food {
 }
 
 const userSchema = new Schema<User>({
-  admin: {default: false, type: Boolean},
-  username: String,
+  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  username: {description: "The user's username", type: String},
 });
 
 userSchema.plugin(passportLocalMongoose as any, {usernameField: "email"});
@@ -42,11 +42,11 @@ userSchema.plugin(baseUserPlugin);
 const UserModel = model<User>("User", userSchema);
 
 const schema = new Schema<Food>({
-  calories: Number,
-  created: Date,
-  hidden: {default: false, type: Boolean},
-  name: String,
-  ownerId: {ref: "User", type: "ObjectId"},
+  calories: {description: "Number of calories in the food", type: Number},
+  created: {description: "When this food was created", type: Date},
+  hidden: {default: false, description: "Whether this food is hidden from listings", type: Boolean},
+  name: {description: "The name of the food", type: String},
+  ownerId: {description: "The user who owns this food entry", ref: "User", type: "ObjectId"},
 });
 
 const FoodModel = model<Food>("Food", schema);

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.
@@ -197,7 +197,6 @@ function initializeRoutes(
 
   // 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/githubAuth.test.ts

@@ -20,9 +20,9 @@ interface TestUser extends GitHubUserFields {
 
 // Create schema for GitHub-enabled user
 const testUserSchema = new Schema<TestUser>({
-  admin: {default: false, type: Boolean},
-  name: String,
-  username: String,
+  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  name: {description: "The user's display name", type: String},
+  username: {description: "The user's username", type: String},
 });
 
 testUserSchema.plugin(passportLocalMongoose as any, {

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";
@@ -8,8 +11,11 @@ export * from "./middleware";
 export * from "./notifiers";
 export * from "./openApiBuilder";
 export * from "./openApiEtag";
+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/openApi.test.ts

@@ -160,13 +160,13 @@ describe("openApi", () => {
     // Ensure that a Number query field supports gt/gte/lt/lte and just a Number
     expect(foodQuery.schema).toEqual({
       oneOf: [
-        {type: "number"},
+        {description: "Number of calories in the food", type: "number"},
         {
           properties: {
-            $gt: {type: "number"},
-            $gte: {type: "number"},
-            $lt: {type: "number"},
-            $lte: {type: "number"},
+            $gt: {description: "Number of calories in the food", type: "number"},
+            $gte: {description: "Number of calories in the food", type: "number"},
+            $lt: {description: "Number of calories in the food", type: "number"},
+            $lte: {description: "Number of calories in the food", type: "number"},
           },
           type: "object",
         },
@@ -278,6 +278,7 @@ describe("openApi populate", () => {
           type: "string",
         },
         name: {
+          description: "The user's display name",
           type: "string",
         },
       },
@@ -293,12 +294,14 @@ describe("openApi populate", () => {
     });
 
     expect(properties.likesIds).toEqual({
+      description: "User likes for this food",
       items: {
         properties: {
           _id: {
             type: "string",
           },
           likes: {
+            description: "Whether the user liked the item",
             type: "boolean",
           },
           userId: {

package/src/openApiBuilder.ts

@@ -34,6 +34,12 @@ import merge from "lodash/merge";
 import type {ModelRouterOptions} from "./api";
 import {logger} from "./logger";
 import {defaultOpenApiErrorResponses} from "./openApi";
+import {
+  getOpenApiValidatorConfig,
+  isOpenApiValidatorConfigured,
+  validateQueryParams,
+  validateRequestBody,
+} from "./openApiValidator";
 
 /**
  * Defines a property within an OpenAPI schema.
@@ -222,6 +228,33 @@ interface OpenApiConfig {
   responses: Record<number | string, OpenApiResponse>;
 }
 
+/**
+ * Internal validation configuration for the builder.
+ */
+interface ValidationConfig {
+  /** Whether to validate request body */
+  validateBody?: boolean;
+  /** Whether to validate query parameters */
+  validateQuery?: boolean;
+  /** Override the global validation enabled setting */
+  enabled?: boolean;
+}
+
+/**
+ * Result from building OpenAPI middleware with schemas exposed.
+ * Useful when you want to use the schemas with asyncHandler's validation.
+ */
+export interface OpenApiBuildResult {
+  /** The OpenAPI documentation middleware */
+  middleware: any;
+  /** Request body schema if defined */
+  bodySchema?: Record<string, OpenApiSchemaProperty>;
+  /** Query parameter schemas if defined */
+  querySchema?: Record<string, OpenApiSchemaProperty>;
+  /** Whether validation was enabled on this builder */
+  validationEnabled: boolean;
+}
+
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -255,6 +288,15 @@ export class OpenApiMiddlewareBuilder {
   /** Accumulated OpenAPI configuration from builder methods */
   private config: OpenApiConfig;
 
+  /** Validation configuration */
+  private validationConfig: ValidationConfig;
+
+  /** Store the raw request body schema for validation */
+  private requestBodySchema?: Record<string, OpenApiSchemaProperty>;
+
+  /** Store the raw query parameter schemas for validation */
+  private queryParamSchemas: Record<string, OpenApiSchemaProperty> = {};
+
   /**
    * Creates a new OpenApiMiddlewareBuilder instance.
    *
@@ -265,6 +307,7 @@ export class OpenApiMiddlewareBuilder {
     this.config = {
       responses: {},
     };
+    this.validationConfig = {};
   }
 
   /**
@@ -368,6 +411,10 @@ export class OpenApiMiddlewareBuilder {
       },
       required: options?.required ?? true,
     };
+
+    // Store the schema for validation
+    this.requestBodySchema = schema as Record<string, OpenApiSchemaProperty>;
+
     return this;
   }
 
@@ -515,6 +562,13 @@ export class OpenApiMiddlewareBuilder {
       required: options?.required ?? false,
       schema,
     });
+
+    // Store for validation
+    this.queryParamSchemas[name] = {
+      ...schema,
+      required: options?.required,
+    };
+
     return this;
   }
 
@@ -557,6 +611,90 @@ export class OpenApiMiddlewareBuilder {
     return this;
   }
 
+  /**
+   * Enables runtime validation for this route.
+   *
+   * When enabled, the built middleware will validate incoming requests
+   * against the documented schema before the handler runs.
+   *
+   * @param options - Optional configuration for validation
+   * @param options.body - Enable body validation (default: true if request body is defined)
+   * @param options.query - Enable query parameter validation (default: true if query params are defined)
+   * @param options.enabled - Override the global validation enabled setting
+   * @returns The builder instance for chaining
+   *
+   * @example
+   * ```typescript
+   * createOpenApiBuilder(options)
+   *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+   *   .withValidation() // Enable validation
+   *   .build();
+   * ```
+   */
+  withValidation(options?: {body?: boolean; query?: boolean; enabled?: boolean}): this {
+    this.validationConfig = {
+      enabled: options?.enabled ?? true,
+      validateBody: options?.body ?? true,
+      validateQuery: options?.query ?? true,
+    };
+    return this;
+  }
+
+  /**
+   * Builds and returns the OpenAPI middleware along with schemas.
+   *
+   * This method is useful when you want to use asyncHandler's integrated
+   * validation instead of separate validation middleware.
+   *
+   * @returns Object containing middleware and schemas
+   *
+   * @example
+   * ```typescript
+   * const {middleware, bodySchema} = createOpenApiBuilder(options)
+   *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+   *   .buildWithSchemas();
+   *
+   * router.post("/users", middleware, asyncHandler(async (req, res) => {
+   *   // handler code
+   * }, {bodySchema, validate: true}));
+   * ```
+   */
+  buildWithSchemas(): OpenApiBuildResult {
+    const noop = (_a: any, _b: any, next: () => void): void => next();
+
+    // Build the OpenAPI documentation middleware only (no validation middleware)
+    let openApiMiddleware: any = noop;
+    if (this.options.openApi?.path) {
+      openApiMiddleware = this.options.openApi.path(
+        merge(
+          {
+            ...this.config,
+            responses: {
+              ...this.config.responses,
+              ...defaultOpenApiErrorResponses,
+            },
+          },
+          this.options.openApiOverwrite?.get ?? {}
+        )
+      );
+    } else {
+      logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
+    }
+
+    const globalConfig = getOpenApiValidatorConfig();
+    const validationEnabled =
+      this.validationConfig.enabled ??
+      (isOpenApiValidatorConfigured() && (globalConfig.validateRequests ?? false));
+
+    return {
+      bodySchema: this.requestBodySchema,
+      middleware: openApiMiddleware,
+      querySchema:
+        Object.keys(this.queryParamSchemas).length > 0 ? this.queryParamSchemas : undefined,
+      validationEnabled,
+    };
+  }
+
   /**
    * Builds and returns the OpenAPI middleware.
    *
@@ -564,10 +702,13 @@ export class OpenApiMiddlewareBuilder {
    * that integrates with the OpenAPI documentation system. If no OpenAPI
    * path is configured in options, returns a no-op middleware.
    *
+   * If validation was enabled via `withValidation()`, returns an array
+   * of middleware: [openApiDocMiddleware, validationMiddleware].
+   *
    * Default error responses (400, 401, 403, 404, 405) are automatically
    * merged with the configured responses.
    *
-   * @returns Express middleware function for OpenAPI documentation
+   * @returns Express middleware function(s) for OpenAPI documentation and optional validation
    *
    * @example
    * ```typescript
@@ -582,23 +723,55 @@ export class OpenApiMiddlewareBuilder {
   build(): any {
     const noop = (_a: any, _b: any, next: () => void): void => next();
 
-    if (!this.options.openApi?.path) {
+    // Build the OpenAPI documentation middleware
+    let openApiMiddleware: any = noop;
+    if (this.options.openApi?.path) {
+      openApiMiddleware = this.options.openApi.path(
+        merge(
+          {
+            ...this.config,
+            responses: {
+              ...this.config.responses,
+              ...defaultOpenApiErrorResponses,
+            },
+          },
+          this.options.openApiOverwrite?.get ?? {}
+        )
+      );
+    } else {
       logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
-      return noop;
     }
 
-    return this.options.openApi.path(
-      merge(
-        {
-          ...this.config,
-          responses: {
-            ...this.config.responses,
-            ...defaultOpenApiErrorResponses,
-          },
-        },
-        this.options.openApiOverwrite?.get ?? {}
-      )
-    );
+    // Check if validation should be enabled
+    const globalConfig = getOpenApiValidatorConfig();
+    const shouldValidate =
+      this.validationConfig.enabled ??
+      (isOpenApiValidatorConfigured() && (globalConfig.validateRequests ?? false));
+
+    if (!shouldValidate) {
+      return openApiMiddleware;
+    }
+
+    // Build validation middleware
+    const validators: any[] = [openApiMiddleware];
+
+    // Add body validation if we have a request body schema
+    if (this.validationConfig.validateBody && this.requestBodySchema) {
+      validators.push(validateRequestBody(this.requestBodySchema, {enabled: true}));
+    }
+
+    // Add query validation if we have query parameter schemas
+    if (this.validationConfig.validateQuery && Object.keys(this.queryParamSchemas).length > 0) {
+      validators.push(validateQueryParams(this.queryParamSchemas, {enabled: true}));
+    }
+
+    // If only one middleware (the openApi one), return it directly
+    if (validators.length === 1) {
+      return openApiMiddleware;
+    }
+
+    // Return array of middleware to be spread in route definition
+    return validators;
   }
 }