@terreno/api 0.13.3 → 0.14.1

package/src/expressServer.ts

@@ -9,19 +9,28 @@ import passport from "passport";
 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 {
+  apiErrorMiddleware,
+  apiFallthroughErrorMiddleware,
+  apiUnauthorizedMiddleware,
+} from "./errors";
 import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
 import {sendToSlack} from "./notifiers";
 import {openApiCompatMiddleware, patchAppUse} from "./openApiCompat";
 import {openApiEtagMiddleware} from "./openApiEtag";
+import {
+  getCurrentRequestContext,
+  requestContextMiddleware,
+  updateRequestContextFromRequest,
+} from "./requestContext";
 import openapi from "./vendor/wesleytodd-openapi/index";
 
 const SLOW_READ_MAX = 200;
 const SLOW_WRITE_MAX = 500;
 const IS_JEST = process.env.JEST_WORKER_ID !== undefined;
 
-export function setupEnvironment(): void {
+export const setupEnvironment = (): void => {
   if (!process.env.TOKEN_ISSUER) {
     throw new Error("TOKEN_ISSUER must be set in env.");
   }
@@ -40,12 +49,13 @@ export function setupEnvironment(): void {
   if (!process.env.REFRESH_TOKEN_EXPIRES_IN && !IS_JEST) {
     logger.warn("REFRESH_TOKEN_EXPIRES_IN not set so using default.");
   }
-}
+};
 
 export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<unknown>>) => void;
 
+// biome-ignore lint/suspicious/noExplicitAny: also called from tests with mock request/response objects
 const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
-  const options = (res.locals.loggingOptions ?? {}) as LoggingOptions;
+  const options = (res.locals?.loggingOptions ?? {}) as LoggingOptions;
 
   const slowReadMs = options.logSlowRequestsReadMs ?? SLOW_READ_MAX;
   const slowWriteMs = options.logSlowRequestsWriteMs ?? SLOW_WRITE_MAX;
@@ -84,7 +94,8 @@ const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
   }
 };
 
-export function logRequests(req: any, res: any, next: any) {
+// biome-ignore lint/suspicious/noExplicitAny: also called from tests with mock request/response objects
+export const logRequests = (req: any, res: any, next: express.NextFunction): void => {
   const startTime = process.hrtime.bigint();
 
   let userString = "";
@@ -114,37 +125,48 @@ export function logRequests(req: any, res: any, next: any) {
   }
   onFinished(res, () => logRequestsFinished(req, res, startTime));
   next();
-}
+};
 
-export function createRouter(rootPath: string, addRoutes: AddRoutes, middleware: any[] = []) {
-  function routePathMiddleware(req: any, _res: any, next: any) {
+export const createRouter = (
+  rootPath: string,
+  addRoutes: AddRoutes,
+  middleware: express.RequestHandler[] = []
+): Array<string | express.RequestHandler | Router> => {
+  const routePathMiddleware = (
+    req: express.Request & {routeMount?: string[]},
+    _res: express.Response,
+    next: express.NextFunction
+  ): void => {
     if (!req.routeMount) {
       req.routeMount = [];
     }
     req.routeMount.push(rootPath);
     next();
-  }
+  };
 
   const router = express.Router();
   router.use(routePathMiddleware);
   addRoutes(router);
   return [rootPath, ...middleware, router];
-}
+};
 
-export function createRouterWithAuth(
+export const createRouterWithAuth = (
   rootPath: string,
   addRoutes: (router: Router) => void,
-  middleware: any[] = []
-) {
+  middleware: express.RequestHandler[] = []
+): Array<string | express.RequestHandler | Router> => {
   return createRouter(rootPath, addRoutes, [
     passport.authenticate("firebase-jwt", {session: false}),
     ...middleware,
   ]);
-}
+};
 
 export interface AuthOptions {
-  generateJWTPayload?: (user: any) => Record<string, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: user shape is provided by the consumer's User model — any preserves the loose-binding contract
+  generateJWTPayload?: (user: any) => Record<string, unknown>;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
   generateTokenExpiration?: (user: any) => number | jwt.SignOptions["expiresIn"];
+  // biome-ignore lint/suspicious/noExplicitAny: see above
   generateRefreshTokenExpiration?: (user: any) => number | jwt.SignOptions["expiresIn"];
 }
 
@@ -173,19 +195,20 @@ interface InitializeRoutesOptions {
   githubAuth?: GitHubAuthOptions;
 }
 
-function initializeRoutes(
+const initializeRoutes = (
   UserModel: UserMongooseModel,
   addRoutes: AddRoutes,
   options: InitializeRoutesOptions = {}
-): express.Application {
+): express.Application => {
   const app = express();
 
   // Record mount paths on layers for Express 5 → OpenAPI compat
   patchAppUse(app);
 
-  // TODO: Log a warning when we hit the array limit.
   app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: options.arrayLimit ?? 200}));
 
+  app.use(requestContextMiddleware);
+
   app.use(
     cors({
       origin: options.corsOrigin ?? "*",
@@ -199,8 +222,12 @@ function initializeRoutes(
   app.use(express.json({limit: "50mb"}));
 
   // Add login/signup/refresh_token before the JWT/auth middlewares
-  addAuthRoutes(app, UserModel as any, options?.authOptions);
-  setupAuth(app as any, UserModel as any);
+  addAuthRoutes(app, UserModel, options?.authOptions);
+  setupAuth(app, UserModel);
+  app.use((req, res, next) => {
+    updateRequestContextFromRequest(req, res);
+    next();
+  });
 
   if (options.logRequests !== false) {
     app.use(logRequests);
@@ -213,9 +240,13 @@ function initializeRoutes(
   });
 
   // Add Sentry scopes for session, transaction, and userId if any are set
-  app.use((req: any, _res: any, next: any) => {
+  app.use((req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    const context = getCurrentRequestContext();
     const transactionId = req.header("X-Transaction-ID");
-    const sessionId = req.header("X-Session-ID");
+    const sessionId = context?.sessionId ?? req.header("X-Session-ID");
+    if (context?.requestId) {
+      Sentry.getCurrentScope().setTag("request_id", context.requestId);
+    }
     if (transactionId) {
       Sentry.getCurrentScope().setTag("transaction_id", transactionId);
     }
@@ -223,7 +254,7 @@ function initializeRoutes(
       Sentry.getCurrentScope().setTag("session_id", sessionId);
     }
     if (req.user?._id) {
-      Sentry.getCurrentScope().setTag("user", req.user._id);
+      Sentry.getCurrentScope().setTag("user", String(req.user._id));
     }
     next();
   });
@@ -246,12 +277,12 @@ function initializeRoutes(
     app.use("/swagger", oapi.swaggerui());
   }
 
-  addMeRoutes(app, UserModel as any, options?.authOptions);
+  addMeRoutes(app, UserModel, options?.authOptions);
 
   // 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);
+    setupGitHubAuth(app, UserModel, options.githubAuth);
+    addGitHubAuthRoutes(app, UserModel, options.githubAuth, options.authOptions);
   }
 
   addRoutes(app, {openApi: oapi});
@@ -262,20 +293,17 @@ function initializeRoutes(
   app.use(apiUnauthorizedMiddleware);
   app.use(apiErrorMiddleware);
 
-  app.use(function onError(err: any, _req: any, res: any, _next: any) {
-    logger.error(`Fallthrough error: ${err}${err?.stack ? `\n${err.stack}` : ""}}`);
-    Sentry.captureException(err);
-    res.statusCode = 500;
-    res.end(`${res.sentry}\n`);
-  });
+  app.use(apiFallthroughErrorMiddleware);
 
   return app;
-}
+};
 
 export interface SetupServerOptions {
   userModel: UserMongooseModel;
   addRoutes: AddRoutes;
   loggingOptions?: LoggingOptions;
+  // Whether requests should be logged. Defaults to true.
+  logRequests?: boolean;
   authOptions?: AuthOptions;
   /**
    * GitHub OAuth configuration. When provided, enables GitHub authentication.
@@ -300,8 +328,7 @@ export interface SetupServerOptions {
   sentryOptions?: Sentry.BunOptions;
 }
 
-// Sets up the routes and returns the app.
-export function setupServer(options: SetupServerOptions): express.Application {
+export const setupServer = (options: SetupServerOptions): express.Application => {
   const UserModel = options.userModel;
   const addRoutes = options.addRoutes;
 
@@ -314,9 +341,12 @@ export function setupServer(options: SetupServerOptions): express.Application {
       authOptions: options.authOptions,
       corsOrigin: options.corsOrigin,
       githubAuth: options.githubAuth,
+      loggingOptions: options.loggingOptions,
+      logRequests: options.logRequests,
     });
-  } catch (error: any) {
-    logger.error(`Error initializing routes: ${error.stack}`);
+  } catch (error: unknown) {
+    const stack = error instanceof Error && error.stack ? error.stack : String(error);
+    logger.error(`Error initializing routes: ${stack}`);
     throw error;
   }
 
@@ -327,19 +357,19 @@ export function setupServer(options: SetupServerOptions): express.Application {
         logger.info(`Listening on port ${port}`);
       });
     } catch (error) {
-      logger.error(`Error trying to start HTTP server: ${error}\n${(error as any).stack}`);
+      const stack = error instanceof Error ? error.stack : String(error);
+      logger.error(`Error trying to start HTTP server: ${error}\n${stack}`);
       process.exit(1);
     }
   }
   return app;
-}
+};
 
-// Convenience method to execute cronjobs with an always-running server.
-export function cronjob(
+export const cronjob = (
   name: string,
   schedule: "hourly" | "minutely" | string,
   callback: () => void
-) {
+): void => {
   const cronSchedule =
     schedule === "hourly" ? "0 * * * *" : schedule === "minutely" ? "* * * * *" : schedule;
   logger.info(`Adding cronjob ${name}, running at: ${cronSchedule}`);
@@ -348,16 +378,17 @@ export function cronjob(
   } catch (error) {
     throw new Error(`Failed to create cronjob: ${error}`);
   }
-}
+};
 
 export interface WrapScriptOptions {
-  onFinish?: (result?: any) => void | Promise<void>;
+  onFinish?: (result?: unknown) => void | Promise<void>;
   terminateTimeout?: number; // in seconds, defaults to 300. Set to 0 to have no termination timeout.
   slackChannel?: string;
 }
-// Wrap up a script with some helpers, such as catching errors, reporting them to sentry, notifying
-// Slack of runs, etc. Also supports timeouts.
-export async function wrapScript(func: () => Promise<any>, options: WrapScriptOptions = {}) {
+export const wrapScript = async (
+  func: () => Promise<unknown>,
+  options: WrapScriptOptions = {}
+): Promise<void> => {
   const name = require.main?.filename.split("/").slice(-1)[0].replace(".ts", "");
   logger.info(`Running script ${name}`);
   await sendToSlack(`Running script ${name}`, {
@@ -383,7 +414,7 @@ export async function wrapScript(func: () => Promise<any>, options: WrapScriptOp
     }, closeTime);
   }
 
-  let result: any;
+  let result: unknown;
   try {
     result = await func();
     if (options.onFinish) {
@@ -397,6 +428,5 @@ export async function wrapScript(func: () => Promise<any>, options: WrapScriptOp
     process.exit(1);
   }
   await sendToSlack(`Success running script ${name}: ${result}`);
-  // Unclear why we have to exit here to prevent the script for continuing to run.
   process.exit(0);
-}
+};

package/src/githubAuth.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {afterEach, beforeEach, describe, expect, it, setSystemTime} from "bun:test";
 import type express from "express";
 import mongoose, {model, Schema} from "mongoose";

package/src/githubAuth.ts

@@ -1,8 +1,9 @@
 import type express from "express";
 import {Router} from "express";
+import type {Schema} from "mongoose";
 import passport from "passport";
 import {Strategy as GitHubStrategy, type Profile} from "passport-github2";
-import {generateTokens, type UserModel} from "./auth";
+import {generateTokens, type User, type UserModel} from "./auth";
 import {APIError} from "./errors";
 import type {AuthOptions} from "./expressServer";
 import {logger} from "./logger";
@@ -32,7 +33,9 @@ export interface GitHubAuthOptions {
     profile: Profile,
     accessToken: string,
     refreshToken: string,
+    // biome-ignore lint/suspicious/noExplicitAny: user shape varies per consumer's User model
     existingUser?: any
+    // biome-ignore lint/suspicious/noExplicitAny: passport user value remains untyped
   ) => Promise<any>;
 }
 
@@ -59,12 +62,19 @@ export interface GitHubUserFields {
  * userSchema.plugin(githubUserPlugin);
  * ```
  */
-export const githubUserPlugin = (schema: any): void => {
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
+export const githubUserPlugin = (schema: Schema<any, any, any, any>): void => {
   schema.add({
-    githubAvatarUrl: {type: String},
-    githubId: {index: true, sparse: true, type: String, unique: true},
-    githubProfileUrl: {type: String},
-    githubUsername: {type: String},
+    githubAvatarUrl: {description: "GitHub avatar image URL", type: String},
+    githubId: {
+      description: "GitHub user ID",
+      index: true,
+      sparse: true,
+      type: String,
+      unique: true,
+    },
+    githubProfileUrl: {description: "GitHub profile URL", type: String},
+    githubUsername: {description: "GitHub username", type: String},
   });
 };
 
@@ -81,6 +91,7 @@ export const setupGitHubAuth = (
 
   passport.use(
     "github",
+    // biome-ignore lint/suspicious/noExplicitAny: passport-github2's typed constructor overloads don't match passReqToCallback variant
     new (GitHubStrategy as any)(
       {
         callbackURL: githubOptions.callbackURL,
@@ -89,12 +100,12 @@ export const setupGitHubAuth = (
         passReqToCallback: true,
         scope,
       },
-      (async (
-        req: any,
+      async (
+        req: express.Request,
         accessToken: string,
         refreshToken: string,
         profile: Profile,
-        done: (error: any, user?: any) => void
+        done: (error: unknown, user?: unknown) => void
       ) => {
         try {
           const existingUser = req.user;
@@ -137,10 +148,11 @@ export const setupGitHubAuth = (
             // Link GitHub to existing user
             const user = await userModel.findById(existingUser._id);
             if (user) {
-              (user as any).githubId = githubId;
-              (user as any).githubUsername = profile.username;
-              (user as any).githubProfileUrl = profile.profileUrl;
-              (user as any).githubAvatarUrl = profile.photos?.[0]?.value;
+              const userWithGitHub = user as unknown as GitHubUserFields;
+              userWithGitHub.githubId = githubId;
+              userWithGitHub.githubUsername = profile.username;
+              userWithGitHub.githubProfileUrl = profile.profileUrl;
+              userWithGitHub.githubAvatarUrl = profile.photos?.[0]?.value;
               await user.save();
               return done(null, user);
             }
@@ -161,10 +173,11 @@ export const setupGitHubAuth = (
             if (existingEmailUser) {
               // If account linking is allowed, link GitHub to existing email account
               if (githubOptions.allowAccountLinking !== false) {
-                (existingEmailUser as any).githubId = githubId;
-                (existingEmailUser as any).githubUsername = profile.username;
-                (existingEmailUser as any).githubProfileUrl = profile.profileUrl;
-                (existingEmailUser as any).githubAvatarUrl = profile.photos?.[0]?.value;
+                const emailUserWithGitHub = existingEmailUser as unknown as GitHubUserFields;
+                emailUserWithGitHub.githubId = githubId;
+                emailUserWithGitHub.githubUsername = profile.username;
+                emailUserWithGitHub.githubProfileUrl = profile.profileUrl;
+                emailUserWithGitHub.githubAvatarUrl = profile.photos?.[0]?.value;
                 await existingEmailUser.save();
                 return done(null, existingEmailUser);
               }
@@ -186,7 +199,7 @@ export const setupGitHubAuth = (
             githubId,
             githubProfileUrl: profile.profileUrl,
             githubUsername: profile.username,
-          } as any);
+          } as unknown as Partial<User>);
 
           await newUser.save();
           return done(null, newUser);
@@ -194,7 +207,7 @@ export const setupGitHubAuth = (
           logger.error(`GitHub auth error: ${error}`);
           return done(error);
         }
-      }) as any
+      }
     ) as passport.Strategy
   );
 };
@@ -223,8 +236,9 @@ export const addGitHubAuthRoutes = (
       // Store the return URL in session or query for redirect after auth
       const returnTo = req.query.returnTo as string | undefined;
       if (returnTo) {
-        (req as any).session = (req as any).session || {};
-        (req as any).session.returnTo = returnTo;
+        const reqWithSession = req as express.Request & {session?: {returnTo?: string}};
+        reqWithSession.session = reqWithSession.session ?? {};
+        reqWithSession.session.returnTo = returnTo;
       }
       next();
     },
@@ -241,16 +255,17 @@ export const addGitHubAuthRoutes = (
     async (req: express.Request, res: express.Response) => {
       try {
         const tokens = await generateTokens(req.user, authOptions);
-        const returnTo = (req as any).session?.returnTo;
+        const returnTo = (req as express.Request & {session?: {returnTo?: string}}).session
+          ?.returnTo;
 
         // If there's a return URL, redirect with tokens as query params
         if (returnTo) {
           const url = new URL(returnTo);
-          url.searchParams.set("token", tokens.token || "");
+          url.searchParams.set("token", tokens.token ?? "");
           if (tokens.refreshToken) {
             url.searchParams.set("refreshToken", tokens.refreshToken);
           }
-          url.searchParams.set("userId", (req.user as any)?._id?.toString() || "");
+          url.searchParams.set("userId", req.user?._id ? String(req.user._id) : "");
           return res.redirect(url.toString());
         }
 
@@ -259,7 +274,7 @@ export const addGitHubAuthRoutes = (
           data: {
             refreshToken: tokens.refreshToken,
             token: tokens.token,
-            userId: (req.user as any)?._id,
+            userId: req.user?._id,
           },
         });
       } catch (error) {
@@ -280,14 +295,18 @@ export const addGitHubAuthRoutes = (
       "/github/link",
       (req: express.Request, res: express.Response, next: express.NextFunction): void => {
         // Require JWT authentication for linking
-        passport.authenticate("jwt", {session: false}, (err: any, user: any) => {
-          if (err || !user) {
-            res.status(401).json({message: "Authentication required to link GitHub account"});
-            return;
+        passport.authenticate(
+          "jwt",
+          {session: false},
+          (err: unknown, user: User | false | null) => {
+            if (err || !user) {
+              res.status(401).json({message: "Authentication required to link GitHub account"});
+              return;
+            }
+            req.user = user as unknown as express.Request["user"];
+            next();
           }
-          req.user = user;
-          next();
-        })(req, res, next);
+        )(req, res, next);
       },
       passport.authenticate("github", {session: false})
     );
@@ -303,14 +322,15 @@ export const addGitHubAuthRoutes = (
 
         try {
           // Explicitly select hash and salt fields which may be hidden by default
-          const user = await userModel.findById((req.user as any)._id).select("+hash +salt");
+          const user = await userModel.findById(req.user._id).select("+hash +salt");
           if (!user) {
             return res.status(404).json({message: "User not found"});
           }
 
           // Check if user has other authentication methods before unlinking
           // passport-local-mongoose stores password in hash and salt fields
-          const hasPassword = !!(user as any).hash || !!(user as any).salt;
+          const userWithAuth = user as unknown as {hash?: string; salt?: string};
+          const hasPassword = !!userWithAuth.hash || !!userWithAuth.salt;
           if (!hasPassword) {
             return res.status(400).json({
               message:
@@ -318,10 +338,11 @@ export const addGitHubAuthRoutes = (
             });
           }
 
-          (user as any).githubId = undefined;
-          (user as any).githubUsername = undefined;
-          (user as any).githubProfileUrl = undefined;
-          (user as any).githubAvatarUrl = undefined;
+          const userWithGitHub = user as unknown as GitHubUserFields;
+          userWithGitHub.githubId = undefined;
+          userWithGitHub.githubUsername = undefined;
+          userWithGitHub.githubProfileUrl = undefined;
+          userWithGitHub.githubAvatarUrl = undefined;
           await user.save();
 
           return res.json({data: {message: "GitHub account unlinked successfully"}});

package/src/index.ts

@@ -3,9 +3,11 @@ export * from "./auth";
 export * from "./betterAuth";
 export * from "./betterAuthApp";
 export * from "./betterAuthSetup";
+export * from "./config";
 export * from "./configurationApp";
 export * from "./configurationPlugin";
 export * from "./consentApp";
+export * from "./envConfigurationPlugin";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
@@ -22,6 +24,8 @@ export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./realtime";
+export * from "./requestContext";
 export * from "./scriptRunner";
 export * from "./secretProviders";
 export * from "./syncConsents";