@terreno/api 0.0.18 → 0.2.0

package/src/api.ts

@@ -18,6 +18,12 @@ import {
   listOpenApiMiddleware,
   patchOpenApiMiddleware,
 } from "./openApi";
+import {
+  buildQuerySchemaFromFields,
+  type ModelRouterValidationOptions,
+  validateModelRequestBody,
+  validateQueryParams,
+} from "./openApiValidator";
 import {checkPermissions, permissionMiddleware, type RESTPermissions} from "./permissions";
 import type {PopulatePath} from "./populate";
 import {
@@ -263,6 +269,19 @@ export interface ModelRouterOptions<T> {
    * that you want to be documented and typed in the SDK.
    */
   openApiExtraModelProperties?: any;
+  /**
+   * Enable runtime validation of request bodies against the OpenAPI schema.
+   * When enabled, requests that don't match the documented schema will return 400 errors.
+   *
+   * Can be set to:
+   * - `true`: Enable validation for create and update operations
+   * - `false`: Disable validation (default)
+   * - Object with `validateCreate` and `validateUpdate` booleans for fine-grained control
+   *
+   * Note: Global validation can be enabled via `configureOpenApiValidator()`.
+   * This option overrides the global setting for this specific router.
+   */
+  validation?: boolean | ModelRouterValidationOptions;
 }
 
 // Ensures query params are allowed. Also checks nested query params when using $and/$or.
@@ -309,13 +328,143 @@ function checkQueryParamAllowed(
 //   return result;
 // }
 
+// Helper to determine if validation should be enabled for a specific operation.
+// When options.validation is not set, returns true — the middleware's own
+// isConfigured check will decide whether to actually validate.
+function shouldValidate(
+  options: ModelRouterOptions<any>,
+  operation: "create" | "update" | "query"
+): boolean {
+  // Check route-specific validation option first
+  if (options.validation !== undefined) {
+    if (typeof options.validation === "boolean") {
+      return options.validation;
+    }
+    if (operation === "create") {
+      return options.validation.validateCreate ?? true;
+    }
+    if (operation === "update") {
+      return options.validation.validateUpdate ?? true;
+    }
+    return options.validation.validateQuery ?? true;
+  }
+
+  // Default: let middleware's isConfigured check decide
+  return true;
+}
+
+// Get body validation middleware if validation is enabled
+function getBodyValidationMiddleware<T>(
+  model: Model<T>,
+  options: ModelRouterOptions<T>,
+  operation: "create" | "update"
+): (req: Request, res: Response, next: NextFunction) => void {
+  const validationOptions: import("./openApiValidator").RequestBodyValidatorOptions = {};
+  if (!shouldValidate(options, operation)) {
+    validationOptions.enabled = false;
+  }
+  if (typeof options.validation === "object") {
+    if (options.validation.onError) {
+      validationOptions.onError = options.validation.onError;
+    }
+    if (options.validation.onAdditionalPropertiesRemoved) {
+      validationOptions.onAdditionalPropertiesRemoved =
+        options.validation.onAdditionalPropertiesRemoved;
+    }
+    const excludeFields =
+      operation === "create"
+        ? options.validation.excludeFromCreate
+        : options.validation.excludeFromUpdate;
+    if (excludeFields?.length) {
+      validationOptions.excludeFields = excludeFields;
+    }
+  }
+
+  return validateModelRequestBody(model, validationOptions);
+}
+
+// Get query validation middleware if validation is enabled
+function getQueryValidationMiddleware<T>(
+  model: Model<T>,
+  options: ModelRouterOptions<T>
+): (req: Request, res: Response, next: NextFunction) => void {
+  const querySchema = buildQuerySchemaFromFields(model, options.queryFields);
+  const validationOptions: import("./openApiValidator").QueryValidatorOptions = {};
+  if (!shouldValidate(options, "query")) {
+    validationOptions.enabled = false;
+  }
+  if (typeof options.validation === "object" && options.validation.onError) {
+    validationOptions.onError = options.validation.onError;
+  }
+
+  return validateQueryParams(querySchema, validationOptions);
+}
+
+/**
+ * Registration object returned by modelRouter when called with a path.
+ *
+ * Used with `TerrenoApp.register()` to mount model routers at specific paths.
+ * Contains the Express router and the path it should be mounted at.
+ *
+ * @see modelRouter for creating registrations
+ * @see TerrenoApp for registering routers
+ */
+export interface ModelRouterRegistration {
+  /** Internal type discriminator for registration detection */
+  __type: "modelRouter";
+  /** The path where the router should be mounted (e.g., "/todos") */
+  path: string;
+  /** The Express router containing CRUD endpoints */
+  router: express.Router;
+}
+
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
- * @param model A Mongoose Model
- * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
+ * When called with a path as the first argument, returns a `ModelRouterRegistration` that can be
+ * passed to `TerrenoApp.register()`.
+ *
+ * @example
+ * // Traditional usage (returns express.Router):
+ * router.use("/todos", modelRouter(Todo, options));
+ *
+ * // Registration usage (returns ModelRouterRegistration):
+ * const todoRouter = modelRouter("/todos", Todo, options);
+ * app.register(todoRouter);
  */
-export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
+export function modelRouter<T>(
+  path: string,
+  model: Model<T>,
+  options: ModelRouterOptions<T>
+): ModelRouterRegistration;
+export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router;
+export function modelRouter<T>(
+  pathOrModel: string | Model<T>,
+  modelOrOptions: Model<T> | ModelRouterOptions<T>,
+  maybeOptions?: ModelRouterOptions<T>
+): express.Router | ModelRouterRegistration {
+  let model: Model<T>;
+  let options: ModelRouterOptions<T>;
+  let path: string | undefined;
+
+  if (typeof pathOrModel === "string") {
+    path = pathOrModel;
+    model = modelOrOptions as Model<T>;
+    options = maybeOptions as ModelRouterOptions<T>;
+  } else {
+    model = pathOrModel;
+    options = modelOrOptions as ModelRouterOptions<T>;
+  }
+
+  const router = _buildModelRouter(model, options);
+
+  if (path !== undefined) {
+    return {__type: "modelRouter", path, router};
+  }
+  return router;
+}
+
+function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
   const router = express.Router();
 
   // Do before the other router options so endpoints take priority.
@@ -325,12 +474,18 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
 
   const responseHandler = options.responseHandler ?? defaultResponseHandler;
 
+  // Always install validation middleware — they are no-ops until configureOpenApiValidator() is called
+  const createValidation = getBodyValidationMiddleware(model, options, "create");
+  const updateValidation = getBodyValidationMiddleware(model, options, "update");
+  const queryValidation = getQueryValidationMiddleware(model, options);
+
   router.post(
     "/",
     [
       authenticateMiddleware(options.allowAnonymous),
       createOpenApiMiddleware(model, options),
       permissionMiddleware(model, options),
+      createValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let body: Partial<T> | (Partial<T> | undefined)[] | null | undefined;
@@ -439,6 +594,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
       authenticateMiddleware(options.allowAnonymous),
       permissionMiddleware(model, options),
       listOpenApiMiddleware(model, options),
+      queryValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let query: any = {};
@@ -625,6 +781,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
       authenticateMiddleware(options.allowAnonymous),
       patchOpenApiMiddleware(model, options),
       permissionMiddleware(model, options),
+      updateValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let doc: mongoose.Document & T = (req as any).obj;
@@ -984,9 +1141,116 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
   return router;
 }
 
-// Since express doesn't handle async routes well, wrap them with this function.
-export const asyncHandler = (fn: any) => (req: Request, res: Response, next: NextFunction) => {
-  return Promise.resolve(fn(req, res, next)).catch(next);
+/**
+ * Options for the asyncHandler function.
+ */
+export interface AsyncHandlerOptions {
+  /**
+   * Schema for validating request body.
+   * When provided and validation is enabled, the request body will be validated
+   * against this schema before the handler runs.
+   */
+  bodySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+
+  /**
+   * Schema for validating query parameters.
+   * When provided and validation is enabled, query params will be validated
+   * against this schema before the handler runs.
+   */
+  querySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+
+  /**
+   * Override global validation setting for this handler.
+   * - `true`: Enable validation regardless of global setting
+   * - `false`: Disable validation regardless of global setting
+   * - `undefined`: Use global setting
+   */
+  validate?: boolean;
+}
+
+/**
+ * Wraps async route handlers to properly catch and forward errors.
+ *
+ * Since Express doesn't handle async routes well, wrap them with this function.
+ * Optionally supports integrated request validation.
+ *
+ * @param fn - The async route handler function
+ * @param options - Optional configuration for validation
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage without validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code
+ * }));
+ *
+ * // With integrated validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code - body is already validated
+ * }, {
+ *   bodySchema: {
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   },
+ *   validate: true,
+ * }));
+ * ```
+ */
+export const asyncHandler = (fn: any, options?: AsyncHandlerOptions) => {
+  // If no validation options, return simple handler
+  if (!options?.bodySchema && !options?.querySchema) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      return Promise.resolve(fn(req, res, next)).catch(next);
+    };
+  }
+
+  // Import validation functions dynamically to avoid circular deps at module load
+  const {
+    validateRequestBody,
+    validateQueryParams,
+    getOpenApiValidatorConfig,
+  } = require("./openApiValidator");
+
+  // Build validation middleware
+  const validators: ((req: Request, res: Response, next: NextFunction) => void)[] = [];
+
+  // Determine if validation should be enabled
+  const shouldValidate = options.validate ?? getOpenApiValidatorConfig().validateRequests ?? false;
+
+  if (shouldValidate) {
+    if (options.bodySchema) {
+      validators.push(validateRequestBody(options.bodySchema, {enabled: true}));
+    }
+    if (options.querySchema) {
+      validators.push(validateQueryParams(options.querySchema, {enabled: true}));
+    }
+  }
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Run validators sequentially, then the handler
+    const runValidators = (index: number): void => {
+      if (index >= validators.length) {
+        // All validators passed, run the actual handler
+        Promise.resolve(fn(req, res, next)).catch(next);
+        return;
+      }
+
+      try {
+        validators[index](req, res, (err?: any) => {
+          if (err) {
+            next(err);
+            return;
+          }
+          runValidators(index + 1);
+        });
+      } catch (err) {
+        next(err);
+      }
+    };
+
+    runValidators(0);
+  };
 };
 
 // For backwards compatibility with the old names.

package/src/auth.ts

@@ -299,7 +299,9 @@ export function addAuthRoutes(
         logger.warn(`Invalid login: ${info}`);
         return res.status(401).json({message: info?.message});
       }
-      logger.info(`User logged in: ${user._id}, type: ${(user as any).type || "N/A"}`);
+      if (process.env.NODE_ENV !== "test") {
+        logger.info(`User logged in: ${user._id}, type: ${(user as any).type || "N/A"}`);
+      }
       const tokens = await generateTokens(user, authOptions);
       return res.json({
         data: {refreshToken: tokens.refreshToken, token: tokens.token, userId: user?._id},

package/src/betterAuth.test.ts

@@ -0,0 +1,160 @@
+import {describe, expect, it} from "bun:test";
+
+import type {AuthProvider, BetterAuthConfig, BetterAuthOAuthProvider} from "./betterAuth";
+
+describe("Better Auth types", () => {
+  it("defines BetterAuthOAuthProvider interface correctly", () => {
+    const provider: BetterAuthOAuthProvider = {
+      clientId: "test-client-id",
+      clientSecret: "test-client-secret",
+    };
+
+    expect(provider.clientId).toBe("test-client-id");
+    expect(provider.clientSecret).toBe("test-client-secret");
+  });
+
+  it("defines BetterAuthConfig interface correctly", () => {
+    const config: BetterAuthConfig = {
+      basePath: "/api/auth",
+      baseURL: "http://localhost:3000",
+      enabled: true,
+      githubOAuth: {
+        clientId: "github-client-id",
+        clientSecret: "github-client-secret",
+      },
+      googleOAuth: {
+        clientId: "google-client-id",
+        clientSecret: "google-client-secret",
+      },
+      secret: "test-secret",
+      trustedOrigins: ["terreno://", "exp://"],
+    };
+
+    expect(config.enabled).toBe(true);
+    expect(config.googleOAuth?.clientId).toBe("google-client-id");
+    expect(config.githubOAuth?.clientId).toBe("github-client-id");
+    expect(config.trustedOrigins).toContain("terreno://");
+    expect(config.basePath).toBe("/api/auth");
+  });
+
+  it("allows minimal BetterAuthConfig", () => {
+    const minimalConfig: BetterAuthConfig = {
+      enabled: false,
+    };
+
+    expect(minimalConfig.enabled).toBe(false);
+    expect(minimalConfig.googleOAuth).toBeUndefined();
+    expect(minimalConfig.basePath).toBeUndefined();
+  });
+
+  it("defines AuthProvider type correctly", () => {
+    const jwtProvider: AuthProvider = "jwt";
+    const betterAuthProvider: AuthProvider = "better-auth";
+
+    expect(jwtProvider).toBe("jwt");
+    expect(betterAuthProvider).toBe("better-auth");
+  });
+});
+
+describe("Better Auth setup", () => {
+  it("syncBetterAuthUser creates a new user when not found", async () => {
+    // This test would require mocking MongoDB which is complex
+    // For now we test the interface structure
+    const betterAuthUser = {
+      createdAt: new Date(),
+      email: "test@example.com",
+      emailVerified: true,
+      id: "ba-user-123",
+      image: null,
+      name: "Test User",
+      updatedAt: new Date(),
+    };
+
+    expect(betterAuthUser.id).toBe("ba-user-123");
+    expect(betterAuthUser.email).toBe("test@example.com");
+    expect(betterAuthUser.name).toBe("Test User");
+  });
+
+  it("BetterAuthSession has correct structure", () => {
+    const session = {
+      createdAt: new Date(),
+      expiresAt: new Date(Date.now() + 3600000),
+      id: "session-123",
+      ipAddress: "127.0.0.1",
+      updatedAt: new Date(),
+      userAgent: "Mozilla/5.0",
+      userId: "user-456",
+    };
+
+    expect(session.id).toBe("session-123");
+    expect(session.userId).toBe("user-456");
+    expect(session.expiresAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it("BetterAuthSessionData combines session and user", () => {
+    const sessionData = {
+      session: {
+        createdAt: new Date(),
+        expiresAt: new Date(),
+        id: "session-123",
+        ipAddress: null,
+        updatedAt: new Date(),
+        userAgent: null,
+        userId: "user-456",
+      },
+      user: {
+        createdAt: new Date(),
+        email: "test@example.com",
+        emailVerified: false,
+        id: "user-456",
+        image: null,
+        name: "Test",
+        updatedAt: new Date(),
+      },
+    };
+
+    expect(sessionData.session.userId).toBe(sessionData.user.id);
+  });
+});
+
+describe("Better Auth config validation", () => {
+  it("basePath defaults to /api/auth when not specified", () => {
+    const config: BetterAuthConfig = {
+      enabled: true,
+    };
+
+    const basePath = config.basePath ?? "/api/auth";
+    expect(basePath).toBe("/api/auth");
+  });
+
+  it("trustedOrigins defaults to empty array when not specified", () => {
+    const config: BetterAuthConfig = {
+      enabled: true,
+    };
+
+    const trustedOrigins = config.trustedOrigins ?? [];
+    expect(trustedOrigins).toEqual([]);
+  });
+
+  it("supports multiple OAuth providers simultaneously", () => {
+    const config: BetterAuthConfig = {
+      appleOAuth: {
+        clientId: "apple-id",
+        clientSecret: "apple-secret",
+      },
+      enabled: true,
+      githubOAuth: {
+        clientId: "github-id",
+        clientSecret: "github-secret",
+      },
+      googleOAuth: {
+        clientId: "google-id",
+        clientSecret: "google-secret",
+      },
+    };
+
+    expect(config.googleOAuth).toBeDefined();
+    expect(config.githubOAuth).toBeDefined();
+    expect(config.appleOAuth).toBeDefined();
+  });
+});

package/src/betterAuth.ts

@@ -0,0 +1,104 @@
+/**
+ * Better Auth types and configuration interfaces for @terreno/api.
+ *
+ * These types support optional Better Auth integration alongside the existing
+ * JWT/Passport authentication system.
+ */
+
+/**
+ * OAuth provider configuration for Better Auth.
+ */
+export interface BetterAuthOAuthProvider {
+  clientId: string;
+  clientSecret: string;
+}
+
+/**
+ * Configuration options for Better Auth integration.
+ */
+export interface BetterAuthConfig {
+  /**
+   * Whether Better Auth is enabled for this server.
+   */
+  enabled: boolean;
+
+  /**
+   * Google OAuth provider configuration.
+   */
+  googleOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * Apple OAuth provider configuration.
+   */
+  appleOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * GitHub OAuth provider configuration.
+   */
+  githubOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * Trusted origins for CORS and redirect validation.
+   * Include your app's deep link schemes (e.g., "terreno://", "exp://").
+   */
+  trustedOrigins?: string[];
+
+  /**
+   * Base path for Better Auth routes.
+   * @default "/api/auth"
+   */
+  basePath?: string;
+
+  /**
+   * Secret key for Better Auth session encryption.
+   * If not provided, falls back to BETTER_AUTH_SECRET environment variable.
+   */
+  secret?: string;
+
+  /**
+   * Base URL for the auth server.
+   * If not provided, falls back to BETTER_AUTH_URL environment variable.
+   */
+  baseURL?: string;
+}
+
+/**
+ * Auth provider selection for setupServer.
+ * - "jwt": Traditional JWT/Passport authentication (default)
+ * - "better-auth": Better Auth with OAuth support
+ */
+export type AuthProvider = "jwt" | "better-auth";
+
+/**
+ * User data from Better Auth session.
+ */
+export interface BetterAuthUser {
+  id: string;
+  email: string;
+  name: string | null;
+  image: string | null;
+  emailVerified: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Session data from Better Auth.
+ */
+export interface BetterAuthSession {
+  id: string;
+  userId: string;
+  expiresAt: Date;
+  ipAddress: string | null;
+  userAgent: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Combined session and user data from Better Auth.
+ */
+export interface BetterAuthSessionData {
+  session: BetterAuthSession;
+  user: BetterAuthUser;
+}