@terreno/api 0.0.1

package/src/auth.ts

@@ -0,0 +1,408 @@
+import express from "express";
+import jwt, {type JwtPayload} from "jsonwebtoken";
+import type {Model, ObjectId} from "mongoose";
+import ms, {type StringValue} from "ms";
+import passport from "passport";
+import {Strategy as AnonymousStrategy} from "passport-anonymous";
+import {
+  type JwtFromRequestFunction,
+  Strategy as JwtStrategy,
+  type StrategyOptions,
+} from "passport-jwt";
+import {Strategy as LocalStrategy} from "passport-local";
+
+import {APIError, apiErrorMiddleware} from "./errors";
+import type {AuthOptions} from "./expressServer";
+import {logger} from "./logger";
+
+export interface User {
+  _id: ObjectId | string;
+  id: string;
+  // Whether the user should be treated as an admin or not.
+  // Admins can have extra abilities in permissions declarations
+  admin: boolean;
+  /**
+   * We support anonymous users, which do not yet have login information.
+   * This can be helpful for pre-signup users.
+   */
+  isAnonymous?: boolean;
+}
+
+export interface UserModel extends Model<User> {
+  createAnonymousUser?: (id?: string) => Promise<User>;
+  // Allows additional setup during signup. This will be passed the rest of req.body from the signup
+  postCreate?: (body: any) => Promise<void>;
+
+  createStrategy(): any;
+  serializeUser(): any;
+  deserializeUser(): any;
+  findByUsername(username: string, findOpts: any): any;
+}
+
+export function authenticateMiddleware(anonymous = false) {
+  const strategies = ["jwt"];
+  if (anonymous) {
+    strategies.push("anonymous");
+  }
+  return passport.authenticate(strategies, {
+    failureMessage: false, // this is just avoiding storing the message in the session
+    failWithError: true,
+    session: false,
+  });
+}
+
+export async function signupUser(
+  userModel: UserModel,
+  email: string,
+  password: string,
+  body?: any
+) {
+  // Strip email and password from the body. They can cause mongoose to throw an error if strict is
+  // set.
+  const {email: _email, password: _password, ...bodyRest} = body;
+
+  try {
+    const user = await (userModel as any).register({email, ...bodyRest}, password);
+
+    if (user.postCreate) {
+      try {
+        await user.postCreate(bodyRest);
+      } catch (error: any) {
+        logger.error(`Error in user.postCreate: ${error}`);
+        throw error;
+      }
+    }
+    await user.save();
+    return user;
+  } catch (error: any) {
+    throw new APIError({title: error.message});
+  }
+}
+
+/**
+ * Generates both an access token (JWT) and a refresh token for a given user.
+ *
+ * This function:
+ * - Signs the user's `_id` into a short-lived JWT (`token`)
+ *   and a long-lived refresh token (`refreshToken`).
+ * - Supports custom expiration logic
+ *   and payload customization via `AuthOptions`.
+ * - Reads token secrets, issuer,
+ *   and default expirations from environment variables.
+ * - Returns `{ token, refreshToken }`,
+ *   or `{ token: null, refreshToken: null }` if the user is missing.
+ *
+ * It is exported to allow external implementations (such as OAuth integrations or other
+ * authentication providers) to reuse and customize the same token generation logic.
+ * This ensures consistent and secure token issuance across different authentication flows.
+ */
+export const generateTokens = async (user: any, authOptions?: AuthOptions) => {
+  const tokenSecretOrKey = process.env.TOKEN_SECRET;
+  if (!tokenSecretOrKey) {
+    throw new Error("TOKEN_SECRET must be set in env.");
+  }
+  if (!user?._id) {
+    logger.warn("No user found for token generation");
+    return {refreshToken: null, token: null};
+  }
+  let payload: Record<string, any> = {id: user._id.toString()};
+  if (authOptions?.generateJWTPayload) {
+    payload = {...authOptions.generateJWTPayload(user), ...payload};
+  }
+  const tokenOptions: jwt.SignOptions = {
+    expiresIn: "15m",
+  };
+  if (authOptions?.generateTokenExpiration) {
+    tokenOptions.expiresIn = authOptions.generateTokenExpiration(user);
+  } else if (process.env.TOKEN_EXPIRES_IN) {
+    try {
+      // this call to ms is purely for validation of the env variable. If it is invalid,
+      // we want to be able to log the error and use the default.
+      ms(process.env.TOKEN_EXPIRES_IN as StringValue);
+      tokenOptions.expiresIn = process.env.TOKEN_EXPIRES_IN as StringValue;
+    } catch (error) {
+      // This error will result in using the default value above of 15m.
+      logger.error(error as string);
+    }
+  }
+  if (process.env.TOKEN_ISSUER) {
+    tokenOptions.issuer = process.env.TOKEN_ISSUER;
+  }
+
+  const token = jwt.sign(payload, tokenSecretOrKey, tokenOptions);
+  const refreshTokenSecretOrKey = process.env.REFRESH_TOKEN_SECRET;
+  let refreshToken;
+  if (refreshTokenSecretOrKey) {
+    const refreshTokenOptions: jwt.SignOptions = {
+      expiresIn: "30d",
+    };
+    if (authOptions?.generateRefreshTokenExpiration) {
+      refreshTokenOptions.expiresIn = authOptions.generateRefreshTokenExpiration(user);
+    } else if (process.env.REFRESH_TOKEN_EXPIRES_IN) {
+      try {
+        // this call to ms is purely for validation of the env variable. If it is invalid,
+        // we want to be able to log the error and use the default.
+        ms(process.env.REFRESH_TOKEN_EXPIRES_IN as StringValue);
+        refreshTokenOptions.expiresIn = process.env.REFRESH_TOKEN_EXPIRES_IN as StringValue;
+      } catch (error) {
+        // This error will result in using the default value above of 30d.
+        logger.error(error as string);
+      }
+    }
+    refreshToken = jwt.sign(payload, refreshTokenSecretOrKey, refreshTokenOptions);
+  } else {
+    logger.info("REFRESH_TOKEN_SECRET not set so refresh tokens will not be issued");
+  }
+  return {refreshToken, token};
+};
+
+// TODO allow customization
+export function setupAuth(app: express.Application, userModel: UserModel) {
+  passport.use(new AnonymousStrategy());
+  passport.use(userModel.createStrategy());
+  passport.use(
+    "signup",
+    new LocalStrategy(
+      {
+        passReqToCallback: true,
+        passwordField: "password",
+        usernameField: "email",
+      },
+      async (req, email, password, done) => {
+        try {
+          done(undefined, await signupUser(userModel, email, password, req.body));
+        } catch (error) {
+          return done(error);
+        }
+      }
+    ) as passport.Strategy
+  );
+
+  if (!userModel.createStrategy) {
+    throw new Error("setupAuth userModel must have .createStrategy()");
+  }
+
+  const customTokenExtractor: JwtFromRequestFunction = (req) => {
+    let token: string | null = null;
+    if (req?.cookies?.jwt) {
+      token = req.cookies.jwt;
+    } else if (req?.headers?.authorization) {
+      token = req?.headers?.authorization.split(" ")[1];
+    }
+    return token;
+  };
+
+  if (process.env.TOKEN_SECRET) {
+    if (process.env.NODE_ENV !== "test") {
+      logger.debug("Setting up JWT Authentication");
+    }
+
+    const secretOrKey = process.env.TOKEN_SECRET;
+    if (!secretOrKey) {
+      throw new Error("TOKEN_SECRET must be set in env.");
+    }
+    const jwtOpts: StrategyOptions = {
+      issuer: process.env.TOKEN_ISSUER,
+      jwtFromRequest: customTokenExtractor,
+      secretOrKey,
+    };
+    passport.use(
+      "jwt",
+      new JwtStrategy(jwtOpts, async (jwtPayload: JwtPayload, done) => {
+        let user;
+        if (!jwtPayload) {
+          return done(null, false);
+        }
+        try {
+          user = await userModel.findById(jwtPayload.id);
+        } catch (error) {
+          logger.warn(`[jwt] Error finding user from id: ${error}`);
+          return done(error, false);
+        }
+        if (user) {
+          return done(null, user);
+        }
+        if (userModel.createAnonymousUser) {
+          logger.info("[jwt] Creating anonymous user");
+          user = await userModel.createAnonymousUser();
+          return done(null, user);
+        }
+        logger.info("[jwt] No user found from token");
+        return done(null, false);
+      }) as passport.Strategy
+    );
+  }
+
+  // Adds req.user to the request. This may wind up duplicating requests with passport,
+  // but passport doesn't give us req.user early enough.
+  async function decodeJWTMiddleware(req, res, next) {
+    if (!process.env.TOKEN_SECRET) {
+      return next();
+    }
+
+    // Allow requests with a "Secret" prefix to pass through since this is a string value,
+    // not a jwt that needs to be decoded
+    if (req?.headers?.authorization?.split(" ")[0] === "Secret") {
+      return next();
+    }
+
+    const token = customTokenExtractor(req);
+
+    // For some reason, our app will happily put null into the authorization header when logging
+    // out then back in.
+    if (!token || token === "null" || token === "undefined") {
+      return next();
+    }
+
+    let decoded;
+
+    try {
+      decoded = jwt.verify(token, process.env.TOKEN_SECRET, {
+        issuer: process.env.TOKEN_ISSUER,
+      }) as jwt.JwtPayload;
+    } catch (error: any) {
+      const userText = req.user?._id ? ` for user ${req.user._id} ` : "";
+      const details = `[jwt] Error decoding token${userText}: ${error}, expired at ${error?.expiredAt}, current time: ${Date.now()}`;
+      logger.debug(details);
+      return res.status(401).json({details, message: error?.message});
+    }
+    if (decoded.id) {
+      try {
+        req.user = await userModel.findById(decoded.id);
+        if (req.user?.disabled) {
+          logger.warn(`[jwt] User ${req.user.id} is disabled`);
+          return res.status(401).json({status: 401, title: "User is disabled"});
+        }
+      } catch (error) {
+        logger.warn(`[jwt] Error finding user from id: ${error}`);
+      }
+    }
+    return next();
+  }
+  app.use(decodeJWTMiddleware);
+  app.use(express.urlencoded({extended: false}) as any);
+}
+
+export function addAuthRoutes(
+  app: express.Application,
+  userModel: UserModel,
+  authOptions?: AuthOptions
+): void {
+  const router = express.Router();
+  router.post("/login", async (req, res, next) => {
+    passport.authenticate("local", {session: false}, async (err: any, user: any, info: any) => {
+      if (err) {
+        logger.error(`Error logging in: ${err}`);
+        return next(err);
+      }
+      if (!user) {
+        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"}`);
+      const tokens = await generateTokens(user, authOptions);
+      return res.json({
+        data: {refreshToken: tokens.refreshToken, token: tokens.token, userId: user?._id},
+      });
+    })(req, res, next);
+  });
+
+  router.post("/refresh_token", async (req, res) => {
+    if (!req.body.refreshToken) {
+      logger.error(
+        `No refresh token provided, must provide refreshToken in body, user id: ${req.user?.id}`
+      );
+      return res
+        .status(401)
+        .json({message: "No refresh token provided, must provide refreshToken in body"});
+    }
+    if (!process.env.REFRESH_TOKEN_SECRET) {
+      logger.error(`No REFRESH_TOKEN_SECRET set, cannot refresh token, user id: ${req.user?.id}`);
+      return res.status(401).json({message: "No REFRESH_TOKEN_SECRET set, cannot refresh token"});
+    }
+    const refreshTokenSecretOrKey = process.env.REFRESH_TOKEN_SECRET;
+    let decoded;
+    try {
+      decoded = jwt.verify(req.body.refreshToken, refreshTokenSecretOrKey) as JwtPayload;
+    } catch (error: any) {
+      logger.error(`Error refreshing token for user ${req.user?.id}: ${error}`);
+      return res.status(401).json({message: error?.message});
+    }
+    if (decoded?.id) {
+      const user = await userModel.findById(decoded.id);
+      const tokens = await generateTokens(user, authOptions);
+      logger.debug(`Refreshed token for ${user?.id}`);
+      return res.json({data: {refreshToken: tokens.refreshToken, token: tokens.token}});
+    }
+    logger.error(`Invalid refresh token, user id: ${req.user?.id}`);
+    return res.status(401).json({message: "Invalid refresh token"});
+  });
+
+  const signupDisabled = process.env.SIGNUP_DISABLED === "true";
+  if (!signupDisabled) {
+    router.post(
+      "/signup",
+      passport.authenticate("signup", {failWithError: true, session: false}),
+      async (req: any, res: any) => {
+        const tokens = await generateTokens(req.user, authOptions);
+        return res.json({
+          data: {refreshToken: tokens.refreshToken, token: tokens.token, userId: req.user._id},
+        });
+      }
+    );
+  }
+  app.set("etag", false);
+  app.use("/auth", router);
+}
+
+export function addMeRoutes(
+  app: express.Application,
+  userModel: UserModel,
+  _authOptions?: AuthOptions
+): void {
+  const router = express.Router();
+  router.get("/me", authenticateMiddleware(), async (req, res) => {
+    if (!req.user?.id) {
+      logger.debug("Not user found for /me");
+      return res.sendStatus(401);
+    }
+    const data = await userModel.findById(req.user.id);
+    if (!data) {
+      logger.debug("Not user data found for /me");
+      return res.sendStatus(404);
+    }
+    const dataObject = data.toObject();
+    (dataObject as any).id = data._id;
+    return res.json({data: dataObject});
+  });
+
+  router.patch("/me", authenticateMiddleware(), async (req, res) => {
+    if (!req.user?.id) {
+      return res.sendStatus(401);
+    }
+    const doc = await userModel.findById(req.user.id);
+    if (!doc) {
+      return res.sendStatus(404);
+    }
+    // TODO support limited updates for profile.
+    // try {
+    //   body = transform(req.body, "update", req.user);
+    // } catch (e) {
+    //   return res.status(403).send({message: (e as any).message});
+    // }
+    try {
+      Object.assign(doc, req.body);
+      await doc.save();
+
+      const dataObject = doc.toObject();
+      (dataObject as any).id = doc._id;
+      return res.json({data: dataObject});
+    } catch (error) {
+      return res.status(403).send({message: (error as any).message});
+    }
+  });
+
+  app.set("etag", false);
+  app.use("/auth", router);
+  app.use(apiErrorMiddleware);
+}

package/src/errors.ts

@@ -0,0 +1,225 @@
+// https://jsonapi.org/format/#errors
+import * as Sentry from "@sentry/node";
+import type {NextFunction, Request, Response} from "express";
+import {Schema} from "mongoose";
+
+import {logger} from "./logger";
+
+export interface APIErrorConstructor {
+  // Required. A short, human-readable summary of the problem that SHOULD NOT change from
+  // occurrence to occurrence of the problem, except for purposes of localization.
+  title: string;
+
+  // error messages to be displayed by a field in a form. this isn't in the JSONAPI spec.
+  // It will be folded into `meta` as `meta.fields` in the actual error payload.
+  // This is helpful to add it to the TS interface for ApiError.
+  fields?: {[id: string]: string};
+
+  // A unique identifier for this particular occurrence of the problem.
+  id?: string;
+  // A links object containing the following members:
+  links?: {about?: string; type?: string} | undefined;
+  // The HTTP status code applicable to this problem. defaults to 500. must be between 400 and 599.
+  status?: number;
+  // An application-specific error code, expressed as a string value.
+  code?: string;
+
+  // A human-readable explanation specific to this occurrence of the problem. Like title,
+  // this field’s value can be localized.
+  detail?: string;
+  // An object containing references to the source of the error,
+  // optionally including any of the following members:
+  source?: {
+    // pointer: a JSON Pointer [RFC6901] to the value in the request document that caused the error
+    // [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific
+    // attribute]. This MUST point to a value in the request document that exists; if it doesn’t,
+    // the client SHOULD simply ignore the pointer.
+    pointer?: string;
+    // a string indicating which URI query parameter caused the error.
+    parameter?: string;
+    // a string indicating the name of a single request header which caused the error.
+    header?: string;
+  };
+  // A meta object containing non-standard meta-information about the error.
+  meta?: {[id: string]: string};
+  error?: Error;
+  // If true, this error will not be sent to external error reporting tools like Sentry.
+  disableExternalErrorTracking?: boolean;
+}
+
+/**
+ * APIError is a simple way to throw an error in an API route and control what is shown and the
+ * HTTP code displayed. It follows the JSONAPI spec to standardize the fields,
+ * allowing the UI to show more consistent, better error messages.
+ *
+ * ```ts
+ *  throw new APIError({
+ *    title: "Only an admin can update that!",
+ *    status: 403,
+ *    code: "update-admin-error",
+ *    detail: "You must be an admin to change that field"
+ *  });
+ * ```
+ */
+export class APIError extends Error {
+  title: string;
+
+  id: string | undefined;
+
+  links: {about?: string; type?: string} | undefined;
+
+  status: number;
+
+  code: string | undefined;
+
+  detail: string | undefined;
+
+  source:
+    | {
+        pointer?: string;
+        parameter?: string;
+        header?: string;
+      }
+    | undefined;
+
+  meta: {[id: string]: any} | undefined;
+
+  error?: Error;
+
+  disableExternalErrorTracking?: boolean;
+
+  constructor(data: APIErrorConstructor) {
+    // Include details in when the error is printed to the console or sent to Sentry.
+    super(
+      `${data.title}${data.detail ? `: ${data.detail}` : ""}${
+        data.error ? `\n${data.error.stack}` : ""
+      }`
+    );
+    this.name = "APIError";
+
+    let {title, id, links, status, code, detail, source, meta, fields, error} = data;
+
+    if (!status) {
+      status = 500;
+    } else if (status && (status < 400 || status > 599)) {
+      logger.error(`Invalid ApiError status code: ${status}, using 500`);
+      status = 500;
+    }
+    this.status = status;
+
+    this.title = title;
+    this.id = id;
+    this.links = links;
+
+    this.code = code;
+    this.detail = detail;
+    this.source = source;
+    this.meta = meta ?? {};
+    this.disableExternalErrorTracking = data.disableExternalErrorTracking;
+    if (fields) {
+      this.meta.fields = fields;
+    }
+    this.error = error;
+    logger.error(
+      `APIError(${status}): ${title} ${detail ? detail : ""}${
+        data.error?.stack ? `\n${data.error?.stack}` : ""
+      }`
+    );
+  }
+}
+
+// This can be attached to any schema to store errors compatible with the JSONAPI spec.
+// Lazily initialize to avoid module loading order issues with Bun where mongoose
+// may not be fully initialized when this module loads.
+
+// Create an errors field for storing error information in a JSONAPI compatible form directly on a
+// model.
+export function errorsPlugin(schema: Schema): void {
+  const errorSchema = new Schema({
+    code: String,
+    detail: String,
+    id: String,
+    links: {
+      about: String,
+      type: String,
+    },
+    meta: Schema.Types.Mixed,
+    source: {
+      header: String,
+      parameter: String,
+      pointer: String,
+    },
+    status: Number,
+    title: {required: true, type: String},
+  });
+
+  schema.add({apiErrors: errorSchema});
+}
+
+export function isAPIError(error: Error): error is APIError {
+  return error.name === "APIError";
+}
+
+/**
+ * Safely extracts the disableExternalErrorTracking property from an error.
+ * Works with both APIError instances and regular Error objects that may have
+ * this property attached.
+ */
+export function getDisableExternalErrorTracking(error: unknown): boolean | undefined {
+  if (error instanceof Error) {
+    if (isAPIError(error)) {
+      return error.disableExternalErrorTracking;
+    }
+  }
+  if (error && typeof error === "object" && "disableExternalErrorTracking" in error) {
+    return (error as {disableExternalErrorTracking?: boolean}).disableExternalErrorTracking;
+  }
+  return undefined;
+}
+
+// Creates an APIError body to send to clients as JSON. Errors don't have a toJSON defined,
+// and we want to strip out things like message, name, and stack for the client.
+// There is almost certainly a more elegant solution to this.
+export function getAPIErrorBody(error: APIError): {[id: string]: any} {
+  const errorData = {status: error.status, title: error.title};
+  for (const key of [
+    "id",
+    "links",
+    "status",
+    "code",
+    "detail",
+    "source",
+    "meta",
+    "disableExternalErrorTracking",
+  ]) {
+    if (error[key]) {
+      errorData[key] = error[key];
+    }
+  }
+  return errorData;
+}
+
+export function apiUnauthorizedMiddleware(
+  err: Error,
+  _req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  if (err.message === "Unauthorized") {
+    // not using the actual APIError class here because we don't want to log it as an error.
+    res.status(401).json({status: 401, title: "Unauthorized"}).send();
+  } else {
+    next(err);
+  }
+}
+
+export function apiErrorMiddleware(err: Error, _req: Request, res: Response, next: NextFunction) {
+  if (isAPIError(err)) {
+    if (!err.disableExternalErrorTracking) {
+      Sentry.captureException(err);
+    }
+    res.status(err.status).json(getAPIErrorBody(err)).send();
+  } else {
+    next(err);
+  }
+}