Merge pull request #209 from MerlinTheWhiz/types/tighten-express-locals-typing

Types: tighten Express locals typing

Author: greatest0fallt1me

jest.config.cjs

@@ -1,30 +1,34 @@
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['**/?(*.)+(spec|test).ts'],
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/?(*.)+(spec|test).ts"],
   // Exclude tests that use Node.js native test runner
-  testPathIgnorePatterns: ['/node_modules/', 'event.emitter.test.ts'],
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  testPathIgnorePatterns: ["/node_modules/", "event.emitter.test.ts"],
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
   moduleNameMapper: {
-    '^(.*/)?generated/prisma/client(\\.js)?$': '<rootDir>/src/test-support/prismaClient.jest.ts',
-    '^(\\.{1,2}/.*)\\.js$': '$1',
+    "^(.*/)?generated/prisma/client(\\.js)?$":
+      "<rootDir>/src/test-support/prismaClient.jest.ts",
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+    "^uuid$": "<rootDir>/src/test-support/uuid.jest.cjs",
   },
   transform: {
-    '^.+\\.ts$': [
-      'ts-jest',
+    "^.+\\.ts$": [
+      "ts-jest",
       {
         useESM: false,
         tsconfig: {
-          module: 'commonjs',
-          moduleResolution: 'node',
+          module: "commonjs",
+          moduleResolution: "node",
           isolatedModules: true,
         },
       },
     ],
   },
+  // Transform selected ESM packages (e.g. uuid) so Jest can parse them
+  transformIgnorePatterns: ["node_modules/(?!(uuid)/)"],
   // Parallel execution settings
-  maxWorkers: '50%', // Use 50% of available CPU cores
+  maxWorkers: "50%", // Use 50% of available CPU cores
   // Ensure proper cleanup between tests
   clearMocks: true,
   resetMocks: false,

src/lib/prisma.ts

@@ -12,7 +12,7 @@ function getPrismaClient(): PrismaClientLike {
   if (!prisma) {
     const connectionString = process.env.DATABASE_URL;
     if (!connectionString) {
-      throw new Error('DATABASE_URL environment variable is required');
+      throw new Error("DATABASE_URL environment variable is required");
     }
     const adapter = new PrismaPg({ connectionString });
     prisma = new PrismaClient({ adapter }) as unknown as PrismaClientLike;
@@ -31,6 +31,6 @@ export default new Proxy({} as PrismaClientLike, {
   get(_target, prop, receiver) {
     const client = getPrismaClient();
     const value = Reflect.get(client, prop, receiver);
-    return typeof value === 'function' ? value.bind(client) : value;
+    return typeof value === "function" ? value.bind(client) : value;
   },
 });

src/middleware/requireAuth.ts

@@ -1,43 +1,37 @@
-import type { NextFunction, Request, Response } from 'express';
-import jwt from 'jsonwebtoken';
+import type { NextFunction, Request, Response } from "express";
+import jwt from "jsonwebtoken";
 
-import type { AuthenticatedUser } from '../types/auth.js';
-import { UnauthorizedError } from '../errors/index.js';
-import { logger } from '../logger.js';
+import type { AuthenticatedUser } from "../types/auth.js";
+import { UnauthorizedError } from "../errors/index.js";
+import { logger } from "../logger.js";
 
-export interface AuthenticatedLocals {
+// Re-export the locals shape for files that import it from this module
+export type AuthenticatedLocals = {
   authenticatedUser?: AuthenticatedUser;
-}
-
-// Extend Express Request to carry the authenticated developer id
-declare module 'express-serve-static-core' {
-  interface Request {
-    developerId?: string;
-  }
-}
+};
 
 /** Restrict accepted signing algorithms to prevent algorithm-confusion attacks. */
-const ALLOWED_ALGORITHMS: jwt.Algorithm[] = ['HS256'];
+const ALLOWED_ALGORITHMS: jwt.Algorithm[] = ["HS256"];
 
 export const requireAuth = (
   req: Request,
   res: Response<unknown, AuthenticatedLocals>,
-  next: NextFunction
+  next: NextFunction,
 ): void => {
   let userId: string | undefined;
 
-  const authHeader = req.header('authorization');
-  if (authHeader?.startsWith('Bearer ')) {
-    const token = authHeader.slice('Bearer '.length).trim();
+  const authHeader = req.header("authorization");
+  if (authHeader?.startsWith("Bearer ")) {
+    const token = authHeader.slice("Bearer ".length).trim();
 
     if (!token) {
-      next(new UnauthorizedError('Missing token', 'MISSING_TOKEN'));
+      next(new UnauthorizedError("Missing token", "MISSING_TOKEN"));
       return;
     }
 
     const secret = process.env.JWT_SECRET;
     if (!secret) {
-      logger.error('[requireAuth] JWT_SECRET is not configured');
+      logger.error("[requireAuth] JWT_SECRET is not configured");
       next(new UnauthorizedError());
       return;
     }
@@ -48,37 +42,45 @@ export const requireAuth = (
       });
 
       // jwt.verify can return a plain string for unsigned payloads
-      if (typeof decoded === 'string' || !decoded) {
-        logger.warn('[requireAuth] Token payload is not a valid object');
-        next(new UnauthorizedError('Invalid token', 'INVALID_TOKEN'));
+      if (typeof decoded === "string" || !decoded) {
+        logger.warn("[requireAuth] Token payload is not a valid object");
+        next(new UnauthorizedError("Invalid token", "INVALID_TOKEN"));
         return;
       }
 
       const uid = (decoded as Record<string, unknown>).userId;
-      if (typeof uid !== 'string' || uid.trim() === '') {
-        logger.warn('[requireAuth] Token missing required userId claim');
-        next(new UnauthorizedError('Token missing required claims', 'MISSING_CLAIMS'));
+      if (typeof uid !== "string" || uid.trim() === "") {
+        logger.warn("[requireAuth] Token missing required userId claim");
+        next(
+          new UnauthorizedError(
+            "Token missing required claims",
+            "MISSING_CLAIMS",
+          ),
+        );
         return;
       }
 
       userId = uid;
     } catch (err) {
       // Log the failure reason but never the token contents
-      const code = err instanceof jwt.TokenExpiredError
-        ? 'TOKEN_EXPIRED'
-        : err instanceof jwt.NotBeforeError
-          ? 'TOKEN_NOT_ACTIVE'
-          : 'INVALID_TOKEN';
+      const code =
+        err instanceof jwt.TokenExpiredError
+          ? "TOKEN_EXPIRED"
+          : err instanceof jwt.NotBeforeError
+            ? "TOKEN_NOT_ACTIVE"
+            : "INVALID_TOKEN";
 
-      logger.warn('[requireAuth] JWT verification failed', { code });
-      next(new UnauthorizedError(
-        code === 'TOKEN_EXPIRED' ? 'Token expired' : 'Invalid token',
-        code,
-      ));
+      logger.warn("[requireAuth] JWT verification failed", { code });
+      next(
+        new UnauthorizedError(
+          code === "TOKEN_EXPIRED" ? "Token expired" : "Invalid token",
+          code,
+        ),
+      );
       return;
     }
   } else {
-    userId = req.header('x-user-id');
+    userId = req.header("x-user-id");
   }
 
   if (!userId) {

src/test-support/uuid.jest.cjs

@@ -0,0 +1,5 @@
+const { randomUUID } = require("crypto");
+
+module.exports = {
+  v4: () => randomUUID(),
+};

src/types/express.d.ts

@@ -1,7 +1,20 @@
+import type { AuthenticatedUser } from "./auth";
+
 declare global {
   namespace Express {
+    /**
+     * Locals available on Response.locals throughout the app.
+     * Add other commonly used locals here to avoid per-file casts.
+     */
+    interface Locals {
+      authenticatedUser?: AuthenticatedUser;
+      // dbPool is set in `app.ts` during initialization and is useful in handlers
+      dbPool?: unknown;
+    }
+
     interface Request {
       id: string;
+      developerId?: string;
       user?: Record<string, unknown>;
       vault?: Record<string, unknown> | null;
       api?: Record<string, unknown>;