@terreno/api 0.0.1

package/src/tests.ts

@@ -0,0 +1,218 @@
+import express, {type Express} from "express";
+import mongoose, {type Model, model, Schema} from "mongoose";
+import passportLocalMongoose from "passport-local-mongoose";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+
+import {logger} from "./logger";
+import {createdUpdatedPlugin, DateOnly, isDisabledPlugin} from "./plugins";
+
+export interface User {
+  admin: boolean;
+  name?: string;
+  username: string;
+  email: string;
+  age?: number;
+  disabled?: boolean;
+}
+
+export interface SuperUser extends User {
+  superTitle: string;
+}
+
+export interface StaffUser extends User {
+  department: string;
+}
+
+export interface FoodCategory {
+  _id?: string;
+  name: string;
+  show: boolean;
+  created: Date;
+  updated: Date;
+}
+
+export interface Food {
+  _id: string;
+  name: string;
+  calories: number;
+  created: Date;
+  ownerId: mongoose.Types.ObjectId | User;
+  hidden?: boolean;
+  source: {
+    name: string;
+    href?: string;
+    dateAdded?: string;
+  };
+  tags: string[];
+  eatenBy: [Schema.Types.ObjectId | User];
+  // We want to test that map type works.
+  lastEatenWith: {[name: string]: Date};
+  categories: FoodCategory[];
+  expiration: string;
+  likesIds: {userId: string; likes: boolean}[];
+}
+
+const userSchema = new Schema<User>({
+  admin: {default: false, type: Boolean},
+  age: Number,
+  name: String,
+  username: String,
+});
+
+userSchema.plugin(passportLocalMongoose as any, {
+  attemptsField: "attempts",
+  interval: process.env.NODE_ENV === "test" ? 1 : 100,
+  limitAttempts: true,
+  maxAttempts: 3,
+  maxInterval: process.env.NODE_ENV === "test" ? 1 : 300000,
+  usernameCaseInsensitive: true,
+  usernameField: "email",
+});
+// userSchema.plugin(tokenPlugin);
+userSchema.plugin(createdUpdatedPlugin);
+userSchema.plugin(isDisabledPlugin);
+userSchema.methods.postCreate = async function (body: any) {
+  this.age = body.age;
+  return this.save();
+};
+
+export const UserModel = model<User>("User", userSchema);
+
+const superUserSchema = new Schema<SuperUser>({
+  superTitle: {required: true, type: String},
+});
+export const SuperUserModel = UserModel.discriminator("SuperUser", superUserSchema);
+
+const staffUserSchema = new Schema<StaffUser>({
+  department: {required: true, type: String},
+});
+export const StaffUserModel = UserModel.discriminator("Staff", staffUserSchema);
+
+const foodCategorySchema = new Schema<FoodCategory>(
+  {
+    name: String,
+    show: Boolean,
+  },
+  {timestamps: {createdAt: "created", updatedAt: "updated"}}
+);
+
+const likesSchema = new Schema<any>({
+  likes: Boolean,
+  userId: {ref: "User", type: "ObjectId"},
+});
+
+const foodSchema = new Schema<Food>(
+  {
+    calories: Number,
+    categories: [foodCategorySchema],
+    created: Date,
+    eatenBy: [
+      {
+        ref: "User",
+        required: true,
+        type: Schema.Types.ObjectId,
+      },
+    ],
+    expiration: DateOnly,
+    hidden: {default: false, type: Boolean},
+    lastEatenWith: {
+      of: Date,
+      type: Map,
+    },
+    likesIds: {required: true, type: [likesSchema]},
+    name: String,
+    ownerId: {ref: "User", type: "ObjectId"},
+    source: {
+      dateAdded: String,
+      href: String,
+      name: String,
+    },
+    tags: [String],
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+foodSchema.virtual("description").get(function (this: Food) {
+  return `${this.name} has ${this.calories} calories`;
+});
+
+export const FoodModel: Model<Food> = model<Food>("Food", foodSchema);
+
+interface RequiredField {
+  name: string;
+  about?: string;
+}
+
+const requiredSchema = new Schema<RequiredField>({
+  about: String,
+  name: {required: true, type: String},
+});
+export const RequiredModel = model<RequiredField>("Required", requiredSchema);
+
+export function getBaseServer(): Express {
+  const app = express();
+
+  app.all("/*", (req, res, next) => {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Headers", "*");
+    // intercepts OPTIONS method
+    if (req.method === "OPTIONS") {
+      res.send(200);
+    } else {
+      next();
+    }
+  });
+  app.use(express.json());
+  return app;
+}
+
+export async function authAsUser(
+  app: express.Application,
+  type: "admin" | "notAdmin"
+): Promise<TestAgent> {
+  const email = type === "admin" ? "admin@example.com" : "notAdmin@example.com";
+  const password = type === "admin" ? "securePassword" : "password";
+
+  const agent = supertest.agent(app);
+  const res = await agent.post("/auth/login").send({email, password}).expect(200);
+  await agent.set("authorization", `Bearer ${res.body.data.token}`);
+  return agent;
+}
+
+export async function setupDb() {
+  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";
+
+  // Broken out of the try/catch below so you can test the catch logger by shutting down mongo.
+  await Promise.all([UserModel.deleteMany({}), FoodModel.deleteMany({})]).catch(logger.catch);
+
+  try {
+    const [notAdmin, admin, adminOther] = await Promise.all([
+      UserModel.create({email: "notAdmin@example.com", name: "Not Admin"}),
+      UserModel.create({admin: true, email: "admin@example.com", name: "Admin"}),
+      UserModel.create({admin: true, email: "admin+other@example.com", name: "Admin Other"}),
+    ]);
+    await (notAdmin as any).setPassword("password");
+    await notAdmin.save();
+
+    await (admin as any).setPassword("securePassword");
+    await admin.save();
+
+    await (adminOther as any).setPassword("otherPassword");
+
+    await adminOther.save();
+
+    return [admin, notAdmin, adminOther];
+  } catch (error) {
+    console.error("Error setting up DB", error);
+    throw error;
+  }
+}

package/src/transformers.test.ts

@@ -0,0 +1,202 @@
+import {beforeEach, describe, expect, it} from "bun:test";
+import type express from "express";
+import type {ObjectId} from "mongoose";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+
+import {modelRouter} from "./api";
+import {addAuthRoutes, setupAuth} from "./auth";
+import {Permissions} from "./permissions";
+import {authAsUser, type Food, FoodModel, getBaseServer, setupDb, UserModel} from "./tests";
+import {AdminOwnerTransformer} from "./transformers";
+
+describe("query and transform", () => {
+  let notAdmin: any;
+  let admin: any;
+  let server: TestAgent;
+  let app: express.Application;
+
+  beforeEach(async () => {
+    process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
+
+    [admin, notAdmin] = await setupDb();
+
+    await Promise.all([
+      FoodModel.create({
+        calories: 1,
+        created: new Date(),
+        name: "Spinach",
+        ownerId: notAdmin._id,
+      }),
+      FoodModel.create({
+        calories: 100,
+        created: Date.now() - 10,
+        hidden: true,
+        name: "Apple",
+        ownerId: admin._id,
+      }),
+      FoodModel.create({
+        calories: 100,
+        created: Date.now() - 10,
+        name: "Carrots",
+        ownerId: admin._id,
+      }),
+    ]);
+    app = getBaseServer();
+    setupAuth(app, UserModel as any);
+    addAuthRoutes(app, UserModel as any);
+    app.use(
+      "/food",
+      modelRouter(FoodModel, {
+        allowAnonymous: true,
+        permissions: {
+          create: [Permissions.IsAny],
+          delete: [Permissions.IsAny],
+          list: [Permissions.IsAny],
+          read: [Permissions.IsAny],
+          update: [Permissions.IsAny],
+        },
+        queryFilter: (user?: {_id: ObjectId | string; admin: boolean}) => {
+          if (!user?.admin) {
+            return {hidden: {$ne: true}};
+          }
+          return {};
+        },
+        transformer: AdminOwnerTransformer<Food>({
+          adminReadFields: ["name", "calories", "created", "ownerId"],
+          adminWriteFields: ["name", "calories", "created", "ownerId"],
+          anonReadFields: ["name"],
+          anonWriteFields: [],
+          authReadFields: ["name", "calories", "created"],
+          authWriteFields: ["name", "calories"],
+          ownerReadFields: ["name", "calories", "created", "ownerId"],
+          ownerWriteFields: ["name", "calories", "created"],
+        }),
+      })
+    );
+    server = supertest(app);
+  });
+
+  it("filters list for non-admin", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food").expect(200);
+    expect(foodRes.body.data).toHaveLength(2);
+  });
+
+  it("does not filter list for admin", async () => {
+    const agent = await authAsUser(app, "admin");
+    const foodRes = await agent.get("/food").expect(200);
+    expect(foodRes.body.data).toHaveLength(3);
+  });
+
+  it("admin read transform", async () => {
+    const agent = await authAsUser(app, "admin");
+    const foodRes = await agent.get("/food").expect(200);
+    expect(foodRes.body.data).toHaveLength(3);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    expect(spinach.created).toBeDefined();
+    expect(spinach.id).toBeDefined();
+    expect(spinach.ownerId).toBeDefined();
+    expect(spinach.name).toBe("Spinach");
+    expect(spinach.calories).toBe(1);
+    expect(spinach.hidden).toBeUndefined();
+  });
+
+  it("admin write transform", async () => {
+    const agent = await authAsUser(app, "admin");
+    const foodRes = await agent.get("/food").expect(200);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    const spinachRes = await agent.patch(`/food/${spinach.id}`).send({name: "Lettuce"}).expect(200);
+    expect(spinachRes.body.data.name).toBe("Lettuce");
+  });
+
+  it("owner read transform", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food").expect(200);
+    expect(foodRes.body.data).toHaveLength(2);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    expect(spinach.id).toBeDefined();
+    expect(spinach.name).toBe("Spinach");
+    expect(spinach.calories).toBe(1);
+    expect(spinach.created).toBeDefined();
+    expect(spinach.ownerId).toBeDefined();
+    expect(spinach.hidden).toBeUndefined();
+  });
+
+  it("owner write transform", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food").expect(200);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    await agent.patch(`/food/${spinach.id}`).send({ownerId: admin.id}).expect(403);
+  });
+
+  it("owner write transform fails", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food").expect(200);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    const spinachRes = await agent
+      .patch(`/food/${spinach.id}`)
+      .send({ownerId: notAdmin.id})
+      .expect(403);
+    expect(spinachRes.body.title.includes("User of type owner cannot write fields: ownerId")).toBe(
+      true
+    );
+  });
+
+  it("auth read transform", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food").expect(200);
+    expect(foodRes.body.data).toHaveLength(2);
+    const spinach = foodRes.body.data.find((food: Food) => food.name === "Spinach");
+    expect(spinach.id).toBeDefined();
+    expect(spinach.name).toBe("Spinach");
+    expect(spinach.calories).toBe(1);
+    expect(spinach.created).toBeDefined();
+    // Owner, so this is defined.
+    expect(spinach.ownerId).toBeDefined();
+    expect(spinach.hidden).toBeUndefined();
+
+    const carrots = foodRes.body.data.find((food: Food) => food.name === "Carrots");
+    expect(carrots.id).toBeDefined();
+    expect(carrots.name).toBe("Carrots");
+    expect(carrots.calories).toBe(100);
+    expect(carrots.created).toBeDefined();
+    // Not owner, so undefined.
+    expect(carrots.ownerId).toBeUndefined();
+    expect(spinach.hidden).toBeUndefined();
+  });
+
+  it("auth write transform", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food");
+    const carrots = foodRes.body.data.find((food: Food) => food.name === "Carrots");
+    const carrotRes = await agent.patch(`/food/${carrots.id}`).send({calories: 2000}).expect(200);
+    expect(carrotRes.body.data.calories).toBe(2000);
+  });
+
+  it("auth write transform fail", async () => {
+    const agent = await authAsUser(app, "notAdmin");
+    const foodRes = await agent.get("/food");
+    const carrots = foodRes.body.data.find((food: Food) => food.name === "Carrots");
+    const writeRes = await agent
+      .patch(`/food/${carrots.id}`)
+      .send({created: "2020-01-01T00:00:00Z"})
+      .expect(403);
+    expect(writeRes.body.title.includes("User of type auth cannot write fields: created")).toBe(
+      true
+    );
+  });
+
+  it("anon read transform", async () => {
+    const res = await server.get("/food");
+    expect(res.body.data).toHaveLength(2);
+    expect(res.body.data.find((f: Food) => f.name === "Spinach")).toBeDefined();
+    expect(res.body.data.find((f: Food) => f.name === "Carrots")).toBeDefined();
+  });
+
+  it("anon write transform fails", async () => {
+    const foodRes = await server.get("/food");
+    const carrots = foodRes.body.data.find((food: Food) => food.name === "Carrots");
+    await server.patch(`/food/${carrots.id}`).send({calories: 10}).expect(403);
+  });
+});

package/src/transformers.ts

@@ -0,0 +1,170 @@
+import type express from "express";
+import type {Document} from "mongoose";
+
+import type {modelRouterOptions} from "./api";
+import type {User} from "./auth";
+import {APIError} from "./errors";
+import {logger} from "./logger";
+
+export interface TerrenoTransformer<T> {
+  // Runs before create or update operations. Allows throwing out fields that the user should be
+  // able to write to, modify data, check permissions, etc.
+  transform?: (obj: Partial<T>, method: "create" | "update", user?: User) => Partial<T> | undefined;
+  // Runs after create/update operations but before data is returned from the API. Serialize fetched
+  // data, dropping fields based on user, changing data, etc.
+  serialize?: (obj: T, user?: User) => Partial<T> | undefined;
+}
+
+function getUserType(user?: User, obj?: any): "anon" | "auth" | "owner" | "admin" {
+  if (user?.admin) {
+    return "admin";
+  }
+  if (obj && user && String(obj?.ownerId) === String(user?.id)) {
+    return "owner";
+  }
+  if (user?.id) {
+    return "auth";
+  }
+  return "anon";
+}
+
+export function AdminOwnerTransformer<T>(options: {
+  // TODO: do something with KeyOf here.
+  anonReadFields?: string[];
+  authReadFields?: string[];
+  ownerReadFields?: string[];
+  adminReadFields?: string[];
+  anonWriteFields?: string[];
+  authWriteFields?: string[];
+  ownerWriteFields?: string[];
+  adminWriteFields?: string[];
+}): TerrenoTransformer<T> {
+  function pickFields(obj: Partial<T>, fields: any[]): Partial<T> {
+    const newData: Partial<T> = {};
+    for (const field of fields) {
+      if (obj[field] !== undefined) {
+        newData[field] = obj[field];
+      }
+    }
+    return newData;
+  }
+
+  return {
+    serialize: (obj: T, user?: User) => {
+      const userType = getUserType(user, obj);
+      if (userType === "admin") {
+        return pickFields(obj, [...(options.adminReadFields ?? []), "id"]);
+      }
+      if (userType === "owner") {
+        return pickFields(obj, [...(options.ownerReadFields ?? []), "id"]);
+      }
+      if (userType === "auth") {
+        return pickFields(obj, [...(options.authReadFields ?? []), "id"]);
+      }
+      return pickFields(obj, [...(options.anonReadFields ?? []), "id"]);
+    },
+    // TODO: Migrate AdminOwnerTransform to use pre-hooks.
+    transform: (obj: Partial<T>, _method: "create" | "update", user?: User) => {
+      const userType = getUserType(user, obj);
+      let allowedFields: any;
+      if (userType === "admin") {
+        allowedFields = options.adminWriteFields ?? [];
+      } else if (userType === "owner") {
+        allowedFields = options.ownerWriteFields ?? [];
+      } else if (userType === "auth") {
+        allowedFields = options.authWriteFields ?? [];
+      } else {
+        allowedFields = options.anonWriteFields ?? [];
+      }
+      const unallowedFields = Object.keys(obj).filter((k) => !allowedFields.includes(k));
+      if (unallowedFields.length) {
+        throw new Error(
+          `User of type ${userType} cannot write fields: ${unallowedFields.join(", ")}`
+        );
+      }
+      return obj;
+    },
+  };
+}
+
+export function transform<T>(
+  options: modelRouterOptions<T>,
+  data: Partial<T> | Partial<T>[],
+  method: "create" | "update",
+  user?: User
+) {
+  if (!options.transformer?.transform) {
+    return data;
+  }
+
+  logger.warn(
+    "transform functions are deprecated, use preCreate/preUpdate/preDelete hooks instead"
+  );
+
+  // TS doesn't realize this is defined otherwise...
+  const transformFn = options.transformer?.transform;
+
+  if (!Array.isArray(data)) {
+    return transformFn(data, method, user);
+  }
+  return data.map((d) => transformFn(d, method, user));
+}
+
+export function serialize<T>(
+  req: express.Request,
+  options: modelRouterOptions<T>,
+  data: (Document<any, any, any> & T) | (Document<any, any, any> & T)[]
+) {
+  const serializeFn = (serializeData: Document<any, any, any> & T, serializeUser?: User) => {
+    const dataObject = serializeData.toObject() as T;
+    (dataObject as any).id = serializeData._id;
+
+    // Search for any value that is a Map and transform it to a plain object.
+    // Otherwise Express drops the contents.
+    for (const key in dataObject) {
+      const value = dataObject[key];
+      if (value instanceof Map) {
+        dataObject[key] = Object.fromEntries(value);
+      }
+    }
+
+    if (options.transformer?.serialize) {
+      return options.transformer?.serialize(dataObject, serializeUser);
+    }
+    return dataObject;
+  };
+
+  if (options.transformer?.serialize) {
+    logger.warn(
+      "transform.serialize functions are deprecated, use post* hooks and serialize instead"
+    );
+  }
+  if (!Array.isArray(data)) {
+    return serializeFn(data, req.user);
+  }
+  return data.map((d) => serializeFn(d, req.user));
+}
+
+/**
+ * Default response handler for modelRouter. Calls toObject on each doc and returns the result,
+ * using transformers.serializer if provided.
+ */
+export async function defaultResponseHandler<T>(
+  doc: (Document<any, any, any> & T) | (Document<any, any, any> & T)[] | null,
+  method: "list" | "create" | "read" | "update",
+  request: express.Request,
+  options: modelRouterOptions<T>
+) {
+  if (!doc) {
+    return null;
+  }
+  try {
+    return serialize(request, options, doc);
+  } catch (error: any) {
+    throw new APIError({
+      error,
+      status: 400,
+      title: `Error serializing ${method} response: ${error.message}`,
+    });
+  }
+}

package/src/utils.test.ts

@@ -0,0 +1,14 @@
+import {describe, expect, it} from "bun:test";
+
+import {isValidObjectId} from "./utils";
+
+describe("utils", () => {
+  it("checks valid ObjectIds", () => {
+    expect(isValidObjectId("62c44da0003d9f8ee8cc925c")).toBe(true);
+    expect(isValidObjectId("620000000000000000000000")).toBe(true);
+    // Mongoose's builtin "ObjectId.isValid" will falsely say this is an ObjectId.
+    expect(isValidObjectId("1234567890ab")).toBe(false);
+    expect(isValidObjectId("microsoft123")).toBe(false);
+    expect(isValidObjectId("62c44da0003d9f8ee8cc925x")).toBe(false);
+  });
+});

package/src/utils.ts

@@ -0,0 +1,47 @@
+import mongoose, {Types} from "mongoose";
+
+import {logger} from "./logger";
+
+// A better version of mongoose's ObjectId.isValid,
+// which falsely will say any 12 character string is valid.
+export function isValidObjectId(id: string): boolean {
+  try {
+    return new Types.ObjectId(id).toString() === id;
+  } catch (error) {
+    logger.error(`Error validating object id ${id}: ${error}`);
+    return false;
+  }
+}
+
+export const timeout = async (ms: number): Promise<NodeJS.Timeout> => {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+/**
+ * Ensure that all mongoose models are set to strict mode.
+ * This validates that models will throw errors when attempting to set
+ * properties that aren't defined in the schema.
+ *
+ * @param ignoredModels - Array of model names to skip validation for
+ * @throws Error if any model is not set to strict mode or missing virtual settings
+ */
+export function checkModelsStrict(ignoredModels: string[] = []): void {
+  const models = mongoose.modelNames();
+  for (const model of models) {
+    const schema = mongoose.model(model).schema;
+
+    if (schema.get("toObject")?.virtuals !== true) {
+      throw new Error(`Model ${model} toObject.virtuals not set to true`);
+    }
+    if (schema.get("toJSON")?.virtuals !== true) {
+      throw new Error(`Model ${model} toJSON.virtuals not set to true`);
+    }
+
+    if (ignoredModels.includes(model)) {
+      continue;
+    }
+    if (schema.get("strict") !== "throw") {
+      throw new Error(`Model ${model} is not set to strict mode.`);
+    }
+  }
+}