@terreno/api 0.0.17 → 0.1.0

package/src/api.ts

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import express, {type NextFunction, type Request, type Response} from "express";
 import cloneDeep from "lodash/cloneDeep";
 import mongoose, {type Document, type Model} from "mongoose";
@@ -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,6 +328,78 @@ 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);
+}
+
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
@@ -325,12 +416,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 +536,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 +723,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 +1083,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/errors.ts

@@ -1,5 +1,5 @@
 // https://jsonapi.org/format/#errors
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
 import {Schema} from "mongoose";
 
@@ -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

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import openapi from "@wesleytodd/openapi";
 import cors from "cors";
 import cron from "cron";
@@ -12,6 +12,7 @@ import qs from "qs";
 import type {ModelRouterOptions} from "./api";
 import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
 import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
+import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
 import {sendToSlack} from "./notifiers";
 import {openApiEtagMiddleware} from "./openApiEtag";
@@ -168,6 +169,8 @@ interface InitializeRoutesOptions {
   logRequests?: boolean;
   loggingOptions?: LoggingOptions;
   authOptions?: AuthOptions;
+  /** GitHub OAuth configuration. When provided, enables GitHub authentication. */
+  githubAuth?: GitHubAuthOptions;
 }
 
 function initializeRoutes(
@@ -241,6 +244,13 @@ function initializeRoutes(
   }
 
   addMeRoutes(app, UserModel as any, options?.authOptions);
+
+  // Set up GitHub OAuth if configured
+  if (options.githubAuth) {
+    setupGitHubAuth(app, UserModel as any, options.githubAuth);
+    addGitHubAuthRoutes(app, UserModel as any, options.githubAuth, options.authOptions);
+  }
+
   addRoutes(app, {openApi: oapi});
 
   Sentry.setupExpressErrorHandler(app);
@@ -264,6 +274,11 @@ export interface SetupServerOptions {
   addRoutes: AddRoutes;
   loggingOptions?: LoggingOptions;
   authOptions?: AuthOptions;
+  /**
+   * GitHub OAuth configuration. When provided, enables GitHub authentication.
+   * Requires the user schema to have GitHub fields (use githubUserPlugin).
+   */
+  githubAuth?: GitHubAuthOptions;
   skipListen?: boolean;
   corsOrigin?:
     | string
@@ -279,7 +294,7 @@ export interface SetupServerOptions {
       ) => void);
   addMiddleware?: AddRoutes;
   ignoreTraces?: string[];
-  sentryOptions?: Sentry.NodeOptions;
+  sentryOptions?: Sentry.BunOptions;
 }
 
 // Sets up the routes and returns a function to launch the API.
@@ -295,6 +310,7 @@ export function setupServer(options: SetupServerOptions) {
       addMiddleware: options.addMiddleware,
       authOptions: options.authOptions,
       corsOrigin: options.corsOrigin,
+      githubAuth: options.githubAuth,
     });
   } catch (error: any) {
     logger.error(`Error initializing routes: ${error.stack}`);

package/src/githubAuth.test.ts

@@ -0,0 +1,223 @@
+import {afterEach, beforeEach, describe, expect, it, setSystemTime} from "bun:test";
+import type express from "express";
+import mongoose, {model, Schema} from "mongoose";
+import passportLocalMongoose from "passport-local-mongoose";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+
+import {setupServer} from "./expressServer";
+import {type GitHubUserFields, githubUserPlugin} from "./githubAuth";
+import {logger} from "./logger";
+import {createdUpdatedPlugin, isDisabledPlugin} from "./plugins";
+
+interface TestUser extends GitHubUserFields {
+  admin: boolean;
+  name?: string;
+  username: string;
+  email: string;
+  disabled?: boolean;
+}
+
+// Create schema for GitHub-enabled user
+const testUserSchema = new Schema<TestUser>({
+  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, {
+  attemptsField: "attempts",
+  interval: 1,
+  limitAttempts: true,
+  maxAttempts: 3,
+  maxInterval: 1,
+  usernameCaseInsensitive: true,
+  usernameField: "email",
+});
+testUserSchema.plugin(createdUpdatedPlugin);
+testUserSchema.plugin(isDisabledPlugin);
+testUserSchema.plugin(githubUserPlugin);
+
+// Get or create model to avoid model redefinition errors
+const GitHubTestUserModel =
+  mongoose.models.GitHubTestUser || model<TestUser>("GitHubTestUser", testUserSchema);
+
+// Connect to database before tests
+const connectDb = async () => {
+  if (mongoose.connection.readyState === 0) {
+    await mongoose
+      .connect("mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000")
+      .catch(logger.catch);
+  }
+  process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+  process.env.TOKEN_SECRET = "secret";
+  process.env.TOKEN_EXPIRES_IN = "30m";
+  process.env.TOKEN_ISSUER = "example.com";
+  process.env.SESSION_SECRET = "session";
+};
+
+describe("githubUserPlugin", () => {
+  it("adds GitHub fields to schema", () => {
+    const paths = testUserSchema.paths;
+    expect(paths.githubId).toBeDefined();
+    expect(paths.githubUsername).toBeDefined();
+    expect(paths.githubProfileUrl).toBeDefined();
+    expect(paths.githubAvatarUrl).toBeDefined();
+  });
+
+  it("githubId is indexed and sparse", () => {
+    const githubIdPath = testUserSchema.path("githubId");
+    expect((githubIdPath as any).options.index).toBe(true);
+    expect((githubIdPath as any).options.sparse).toBe(true);
+    expect((githubIdPath as any).options.unique).toBe(true);
+  });
+});
+
+describe("GitHub auth routes", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await connectDb();
+
+    await GitHubTestUserModel.deleteMany({});
+
+    // Create test user with password
+    const testUser = await GitHubTestUserModel.create({
+      admin: false,
+      email: "test@example.com",
+      name: "Test User",
+    });
+    await (testUser as any).setPassword("password123");
+    await testUser.save();
+
+    function addRoutes(router: express.Router): void {
+      router.get("/test", (_req, res) => res.json({ok: true}));
+    }
+
+    app = setupServer({
+      addRoutes,
+      githubAuth: {
+        allowAccountLinking: true,
+        callbackURL: "http://localhost:9000/auth/github/callback",
+        clientId: "test-client-id",
+        clientSecret: "test-client-secret",
+      },
+      skipListen: true,
+      userModel: GitHubTestUserModel as any,
+    });
+    agent = supertest.agent(app);
+  });
+
+  afterEach(async () => {
+    setSystemTime();
+  });
+
+  it("GET /auth/github redirects to GitHub OAuth", async () => {
+    const res = await agent.get("/auth/github").expect(302);
+    expect(res.headers.location).toContain("github.com");
+    expect(res.headers.location).toContain("client_id=test-client-id");
+  });
+
+  it("GET /auth/github/failure returns 401", async () => {
+    const res = await agent.get("/auth/github/failure").expect(401);
+    expect(res.body.message).toBe("GitHub authentication failed");
+  });
+
+  it("DELETE /auth/github/unlink requires authentication", async () => {
+    const res = await agent.delete("/auth/github/unlink").expect(401);
+    expect(res.body).toBeDefined();
+  });
+
+  it("DELETE /auth/github/unlink works when authenticated with password", async () => {
+    // Login as test user
+    const loginRes = await agent
+      .post("/auth/login")
+      .send({email: "test@example.com", password: "password123"})
+      .expect(200);
+
+    // Link github to this user
+    const user = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    if (user) {
+      (user as any).githubId = "99999";
+      (user as any).githubUsername = "testghuser";
+      await user.save();
+    }
+
+    // Unlink
+    const res = await agent
+      .delete("/auth/github/unlink")
+      .set("authorization", `Bearer ${loginRes.body.data.token}`)
+      .expect(200);
+
+    expect(res.body.data.message).toBe("GitHub account unlinked successfully");
+
+    // Verify github fields are cleared
+    const updatedUser = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect((updatedUser as any).githubId).toBeUndefined();
+    expect((updatedUser as any).githubUsername).toBeUndefined();
+  });
+
+  it("user can have both password and GitHub auth", async () => {
+    const user = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect(user).toBeDefined();
+    if (!user) {
+      return;
+    }
+
+    // Link GitHub
+    (user as any).githubId = "88888";
+    (user as any).githubUsername = "linkeduser";
+    await user.save();
+
+    // Can still login with password
+    const res = await agent
+      .post("/auth/login")
+      .send({email: "test@example.com", password: "password123"})
+      .expect(200);
+
+    expect(res.body.data.token).toBeDefined();
+
+    // User has both auth methods - successful login proves password works
+    // and we verify GitHub fields are set
+    const updatedUser = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect(updatedUser).toBeDefined();
+    expect((updatedUser as any).githubId).toBe("88888");
+    expect((updatedUser as any).githubUsername).toBe("linkeduser");
+  });
+});
+
+describe("GitHub auth disabled", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await connectDb();
+
+    await GitHubTestUserModel.deleteMany({});
+
+    function addRoutes(router: express.Router): void {
+      router.get("/test", (_req, res) => res.json({ok: true}));
+    }
+
+    // Setup server WITHOUT GitHub auth
+    app = setupServer({
+      addRoutes,
+      skipListen: true,
+      userModel: GitHubTestUserModel as any,
+    });
+    agent = supertest.agent(app);
+  });
+
+  afterEach(async () => {
+    setSystemTime();
+  });
+
+  it("GitHub routes are not available when githubAuth is not configured", async () => {
+    await agent.get("/auth/github").expect(404);
+    await agent.get("/auth/github/callback").expect(404);
+    await agent.delete("/auth/github/unlink").expect(404);
+  });
+});