@devmoods/express-extras 0.24.0 → 0.26.0

package/README.md

@@ -42,7 +42,7 @@ PORT=3000
 READINESS_PROBE_MS=
 FORCE_EXIT_TIMEOUT=
 
-APP_JWT_SECRET=123456
+AUTH_JWT_SECRET=123456
 
 POSTGRES_URL=postgresql://user:pass@localhost:5432/my_database
 REDIS_URL=

package/dist/auth.d.ts

@@ -1,27 +1,54 @@
 import { type Request, type RequestHandler, type Response, Router } from 'express';
 import type { RedisClient } from './redis.js';
+/**
+ * Returns a signed JWT token.
+ */
 export declare function createAuthToken(payload: any, secret?: string): string;
-export interface AuthLoginMethods<User = any> {
-    emailAndPassword?: (email: string, verifyPassword: (realPassword: string) => Promise<boolean>) => Promise<User>;
-}
-export interface AuthOptions<UserModel extends Record<string, any>> {
-    getUserByToken(token: Record<string, any>): Promise<UserModel>;
-    methods: AuthLoginMethods<UserModel>;
-    redis: RedisClient;
-    filterUser(user: UserModel): Partial<UserModel>;
-    tokenExpiry?: number;
+/**
+ * Decode the given JWT token.
+ */
+export declare function decodeAuthToken(token: string): {
+    [x: string]: any;
+    iss?: string | undefined;
+    sub?: string | undefined;
+    aud?: string | string[] | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    jti?: string | undefined;
+};
+export interface EmailAndPasswordOptions<UserModel = AnyUser> {
+    login: (email: string, verifyPassword: (realPassword: string) => Promise<boolean>) => Promise<UserModel>;
     onPasswordResetRequest?(user: UserModel, temporaryToken: string): void | Promise<void>;
     onPasswordChanged?(user: UserModel, newPassword: string): Promise<void>;
     onEmailVerificationRequest?(user: UserModel, temporaryToken: string): Promise<void>;
     onEmailVerified?(user: UserModel): Promise<void>;
 }
-export interface CreateAuth<UserModel extends Record<string, any>> {
+export declare function EmailAndPasswordAuthProvider<UserModel extends AnyUser>(options: EmailAndPasswordOptions<UserModel>): AuthProvider<UserModel>;
+export interface AuthProviderContext<UserModel extends AnyUser> {
+    filterUser: AuthOptions<UserModel>['filterUser'];
+    redis: AuthOptions<UserModel>['redis'];
+    setCurrentUser: (user: UserModel) => void;
+    createTemporaryToken(user: UserModel): Promise<string>;
+    middleware: (authorize?: boolean) => RequestHandler;
+}
+export type AnyUser = Record<string, any>;
+export interface AuthProvider<UserModel extends AnyUser> {
+    setupRoutes(router: Router, context: AuthProviderContext<UserModel>): void;
+}
+export interface AuthOptions<UserModel extends AnyUser> {
+    getUserByToken(token: Record<string, any>): Promise<UserModel>;
+    providers: AuthProvider<UserModel>[];
+    redis: RedisClient;
+    filterUser(user: UserModel): Partial<UserModel>;
+}
+export interface CreateAuth<UserModel extends AnyUser> {
     createRouter: () => Router;
     useCurrentUser: () => UserModel | undefined;
     middleware: (authorize?: boolean) => RequestHandler;
     createTemporaryToken(user: UserModel): Promise<string>;
 }
-export declare function createAuth<UserModel extends Record<string, any>>({ getUserByToken, methods: { emailAndPassword }, filterUser, redis, tokenExpiry, onPasswordResetRequest, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }: AuthOptions<UserModel>): CreateAuth<UserModel>;
+export declare function createAuth<UserModel extends AnyUser>({ getUserByToken, filterUser, redis, providers, }: AuthOptions<UserModel>): CreateAuth<UserModel>;
 /**
  * Extract a Bearer token from the HTTP Authorization header
  * of `req`.
@@ -35,6 +62,17 @@ export declare function parseAuthorizationHeader(req: Request): string | null;
  *   2. Cookie named `access_token`
  */
 export declare function extractAccessTokenFromRequest(req: Request): string | null;
+/**
+ * Set or expire the access token cookie.
+ *
+ * If the provided token is `null` the cookie will be cleared.
+ */
 export declare function setAccessTokenCookie(res: Response, token: string | null): void;
+/**
+ * Compare two password hashes using bcrypt.
+ */
 export declare function checkIfPasswordsMatch(realPassword: string, attemptedPassword: string): Promise<boolean>;
+/**
+ * Returns a hash of a password suitable for storage.
+ */
 export declare function hashPassword(password: string): Promise<string>;

package/dist/auth.js

@@ -13,20 +13,38 @@ const logger = getLogger('auth');
 const TOKEN_EXPIRES_IN = readEnv.number('AUTH_TOKEN_EXPIRES', 3600 * 48);
 const TEMP_TOKEN_EXIRES_IN = readEnv.number('AUTH_TEMP_TOKEN_EXPIRES', 3600);
 const AUTH_SECRET = readEnv('AUTH_JWT_SECRET', '');
+const tokenSchema = {
+    type: 'string',
+    minLength: 50,
+    maxLength: 256,
+};
+const passwordSchema = { type: 'string', minLength: 8 };
+const emailSchema = { type: 'string', minLength: 4 };
+/**
+ * Returns a signed JWT token.
+ */
 export function createAuthToken(payload, secret = AUTH_SECRET) {
     return jwt.sign(payload, secret, { expiresIn: TOKEN_EXPIRES_IN });
 }
-export function createAuth({ getUserByToken, methods: { emailAndPassword }, filterUser = (x) => x, redis, tokenExpiry = TOKEN_EXPIRES_IN, onPasswordResetRequest, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }) {
-    const useCurrentUser = () => useContext('currentUser');
-    const setCurrentUser = (user) => setContext('currentUser', user);
+/**
+ * Decode the given JWT token.
+ */
+export function decodeAuthToken(token) {
+    try {
+        const decoded = jwt.verify(token.trim(), AUTH_SECRET);
+        if (typeof decoded === 'string') {
+            throw new Error('decoded value not an object');
+        }
+        return { ...decoded };
+    }
+    catch (error) {
+        throw new Error(`Failed to decode auth token: ${error.message}`);
+    }
+}
+export function EmailAndPasswordAuthProvider(options) {
     const skipPasswordCheck = async () => true;
-    const createRouter = () => {
-        const router = Router();
-        router.get('/me', middleware(), route(() => {
-            const user = useCurrentUser();
-            return filterUser(user);
-        }));
-        if (emailAndPassword) {
+    return {
+        setupRoutes(router, context) {
             router.post('/login', validateBody({
                 type: 'object',
                 properties: {
@@ -36,11 +54,11 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 required: ['email', 'password'],
             }), route(async ({ body: { email, password } }, res) => {
                 try {
-                    const user = await emailAndPassword(email, (realPassword) => checkIfPasswordsMatch(realPassword, password));
-                    const token = createAuthToken(filterUser(user));
-                    await redis.set(token, '1', { EX: tokenExpiry });
+                    const user = await options.login(email, (realPassword) => checkIfPasswordsMatch(realPassword, password));
+                    const token = createAuthToken(context.filterUser(user));
+                    await context.redis.set(token, '1', { EX: TOKEN_EXPIRES_IN });
                     setAccessTokenCookie(res, token);
-                    setCurrentUser(user);
+                    context.setCurrentUser(user);
                     logger.info('access token created');
                     return [201, { token }];
                 }
@@ -49,38 +67,21 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                     throw Unauthorized(error.message);
                 }
             }));
-        }
-        router.get('/logout', route(async (req, res) => {
-            const token = extractAccessTokenFromRequest(req);
-            if (token) {
-                await redis.del(token);
-            }
-            setAccessTokenCookie(res, null);
-            res.redirect('/');
-        }));
-        const tokenSchema = {
-            type: 'string',
-            minLength: 50,
-            maxLength: 256,
-        };
-        const passwordSchema = { type: 'string', minLength: 8 };
-        const emailSchema = { type: 'string', minLength: 4 };
-        if (emailAndPassword) {
             router.post('/change-password', validateBody({
                 type: 'object',
                 properties: { token: tokenSchema, password: passwordSchema },
                 required: ['token', 'password'],
             }), route(async (req) => {
                 const { password, token } = req.body;
-                const email = await redis.get(token);
+                const email = await context.redis.get(token);
                 if (!email) {
                     logger.info('invalid reset token', { token });
                     throw BadRequest('invalid reset token');
                 }
-                const user = await emailAndPassword(email, skipPasswordCheck);
-                setCurrentUser(user);
-                await onPasswordChanged?.(user, await hashPassword(password));
-                await redis.del(token);
+                const user = await options.login(email, skipPasswordCheck);
+                context.setCurrentUser(user);
+                await options.onPasswordChanged?.(user, await hashPassword(password));
+                await context.redis.del(token);
                 logger.info('user changed password');
                 return 200;
             }));
@@ -90,12 +91,9 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 required: ['email'],
             }), route(async (req) => {
                 const { email } = req.body;
-                if (!emailAndPassword) {
-                    throw new Error('Not applicable for login method');
-                }
-                const user = await emailAndPassword(email, skipPasswordCheck);
-                const temporaryToken = await createTemporaryToken(user);
-                await onEmailVerificationRequest?.(user, temporaryToken);
+                const user = await options.login(email, skipPasswordCheck);
+                const temporaryToken = await context.createTemporaryToken(user);
+                await options.onEmailVerificationRequest?.(user, temporaryToken);
                 return 202;
             }));
             router.post('/verify-email', validateBody({
@@ -104,7 +102,7 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 required: ['token', 'email'],
             }), route(async (req) => {
                 const { token, email } = req.body;
-                const storedEmail = await redis.get(token);
+                const storedEmail = await context.redis.get(token);
                 if (!storedEmail) {
                     logger.info('invalid verification token', { token });
                     throw BadRequest('invalid verification token');
@@ -116,14 +114,57 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                     });
                     throw BadRequest('invalid verification token');
                 }
-                const user = await emailAndPassword(storedEmail, skipPasswordCheck);
-                setCurrentUser(user);
-                await onEmailVerified?.(user);
-                await redis.del(token);
+                const user = await options.login(storedEmail, skipPasswordCheck);
+                context.setCurrentUser(user);
+                await options.onEmailVerified?.(user);
+                await context.redis.del(token);
                 logger.info('user verified');
                 return 200;
             }));
-        }
+            router.post('/reset', context.middleware(false), validateBody({
+                type: 'object',
+                properties: { email: emailSchema },
+                required: ['email'],
+            }), route(async (req) => {
+                const { email } = req.body;
+                try {
+                    const user = await options.login(email, skipPasswordCheck);
+                    const temporaryToken = await context.createTemporaryToken(user);
+                    await options.onPasswordResetRequest?.(user, temporaryToken);
+                    logger.info('password reset request', { email });
+                }
+                catch (error) {
+                    logger.error(error, 'auth reset failed');
+                }
+                return 202;
+            }));
+        },
+    };
+}
+export function createAuth({ getUserByToken, filterUser = (x) => x, redis, providers, }) {
+    const useCurrentUser = () => useContext('currentUser');
+    const setCurrentUser = (user) => setContext('currentUser', user);
+    const providerContext = {
+        filterUser,
+        redis,
+        setCurrentUser,
+        createTemporaryToken,
+        middleware,
+    };
+    const createRouter = () => {
+        const router = Router();
+        router.get('/me', middleware(), route(() => {
+            const user = useCurrentUser();
+            return filterUser(user);
+        }));
+        router.get('/logout', route(async (req, res) => {
+            const token = extractAccessTokenFromRequest(req);
+            if (token) {
+                await redis.del(token);
+            }
+            setAccessTokenCookie(res, null);
+            res.redirect('/');
+        }));
         /**
          * Check that a reset token is valid.
          */
@@ -140,29 +181,6 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
             return 200;
         }));
-        /**
-         * Request password reset
-         */
-        router.post('/reset', middleware(false), validateBody({
-            type: 'object',
-            properties: { email: emailSchema },
-            required: ['email'],
-        }), route(async (req) => {
-            const { email } = req.body;
-            if (!emailAndPassword) {
-                throw new Error('Not applicable for login method');
-            }
-            try {
-                const user = await emailAndPassword(email, skipPasswordCheck);
-                const temporaryToken = await createTemporaryToken(user);
-                await onPasswordResetRequest?.(user, temporaryToken);
-                logger.info('password reset request', { email });
-            }
-            catch (error) {
-                logger.error(error, 'auth reset failed');
-            }
-            return 202;
-        }));
         router.get('/token/refresh', middleware(false), route(async (req, res) => {
             const user = useCurrentUser();
             if (!user) {
@@ -170,11 +188,14 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
             const { exp, iat, ...rest } = user;
             const token = createAuthToken(rest);
-            await redis.set(token, '1', { EX: tokenExpiry });
+            await redis.set(token, '1', { EX: TOKEN_EXPIRES_IN });
             setAccessTokenCookie(res, token);
             logger.info('refreshed token', { user });
             return { token };
         }));
+        for (const provider of providers) {
+            provider.setupRoutes(router, providerContext);
+        }
         return router;
     };
     function middleware(authorize = true) {
@@ -195,11 +216,8 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                     }
                     throw new InvalidToken('token expired');
                 }
-                const decoded = jwt.verify(token.trim(), AUTH_SECRET);
-                if (typeof decoded === 'string') {
-                    throw new Error('Failed to decode token');
-                }
-                const user = await getUserByToken({ ...decoded });
+                const decoded = decodeAuthToken(token);
+                const user = await getUserByToken(decoded);
                 setCurrentUser(user);
                 next();
             }
@@ -210,6 +228,10 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
         };
     }
+    /**
+     * Create a short-lived token tied to a user that can be
+     * used for different kinds of verification.
+     */
     async function createTemporaryToken(user) {
         try {
             const temporaryToken = crypto.randomBytes(32).toString('hex');
@@ -270,6 +292,11 @@ export function extractAccessTokenFromRequest(req) {
     }
     return null;
 }
+/**
+ * Set or expire the access token cookie.
+ *
+ * If the provided token is `null` the cookie will be cleared.
+ */
 export function setAccessTokenCookie(res, token) {
     if (token == null) {
         res.cookie('access_token', v4(), {
@@ -290,6 +317,9 @@ class InvalidToken extends Error {
         this.name = 'Invalid Token';
     }
 }
+/**
+ * Compare two password hashes using bcrypt.
+ */
 export async function checkIfPasswordsMatch(realPassword, attemptedPassword) {
     if (!realPassword) {
         throw new Error('User has no defined password');
@@ -300,6 +330,9 @@ export async function checkIfPasswordsMatch(realPassword, attemptedPassword) {
     }
     return true;
 }
+/**
+ * Returns a hash of a password suitable for storage.
+ */
 export function hashPassword(password) {
     return bcrypt.hash(password, 10);
 }

package/dist/cache.d.ts

@@ -0,0 +1,14 @@
+import { type RedisClient } from './redis.js';
+export interface CacheAdapter {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, expires?: number | null | undefined): Promise<void>;
+    clear(key?: string): Promise<void>;
+}
+export declare function createRedisCacheAdapter(redis: RedisClient): CacheAdapter;
+export declare function createMemoryCacheAdapter(): CacheAdapter;
+export declare function createCache(adapter: CacheAdapter): {
+    set: (key: string, value: any, expires?: number | null | undefined) => Promise<void>;
+    get: (key: string) => Promise<any>;
+    clear: (key?: string | undefined) => Promise<void>;
+    wrap: <T>(key: string, expiresMs: number | null | undefined, fn: () => Promise<T>) => Promise<T>;
+};

package/dist/cache.js

@@ -0,0 +1,64 @@
+export function createRedisCacheAdapter(redis) {
+    return {
+        async get(key) {
+            const value = await redis.get(key);
+            if (value == null) {
+                return null;
+            }
+            return JSON.parse(value);
+        },
+        async set(key, value, expires) {
+            await redis.set(key, JSON.stringify(value), { PX: expires });
+        },
+        async clear(key) {
+            if (key) {
+                await redis.del(key);
+            }
+        },
+    };
+}
+export function createMemoryCacheAdapter() {
+    const cache = new Map();
+    return {
+        async get(key) {
+            const entry = cache.get(key);
+            if (entry == null) {
+                return null;
+            }
+            const [value, expires] = entry;
+            if (expires != null && Date.now() >= expires) {
+                cache.delete(key);
+                return null;
+            }
+            return value;
+        },
+        async set(key, value, expires) {
+            cache.set(key, [value, expires == null ? null : Date.now() + expires]);
+        },
+        async clear(key) {
+            if (key) {
+                cache.delete(key);
+            }
+            else {
+                cache.clear();
+            }
+        },
+    };
+}
+export function createCache(adapter) {
+    async function cached(key, expiresMs, fn) {
+        const cachedValue = await adapter.get(key);
+        if (cachedValue != null) {
+            return cachedValue;
+        }
+        const result = await fn();
+        await adapter.set(key, result, expiresMs);
+        return result;
+    }
+    return {
+        set: adapter.set.bind(adapter),
+        get: adapter.get.bind(adapter),
+        clear: adapter.clear.bind(adapter),
+        wrap: cached,
+    };
+}

package/dist/errors.js

@@ -1,7 +1,7 @@
 import { STATUS_CODES } from 'node:http';
 import * as Sentry from '@sentry/node';
 import { errors } from 'compose-middleware';
-import { IntegrityError } from './postgres.js';
+import { DoesNotExistError, IntegrityError } from './postgres.js';
 export class ApiError extends Error {
 }
 export const BadRequest = (reason) => makeError(400, 'Invalid Params', { reason });
@@ -41,6 +41,9 @@ function convertToAPIError(error) {
     if (error instanceof IntegrityError) {
         return Conflict(error.message);
     }
+    if (error instanceof DoesNotExistError) {
+        return NotFound(error.message);
+    }
     return error;
 }
 function _errorHandler({ onError }) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './auth.js';
+export * from './cache.js';
 export * from './context.js';
 export * from './email.js';
 export * from './errors.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './auth.js';
+export * from './cache.js';
 export * from './context.js';
 export * from './email.js';
 export * from './errors.js';

package/dist/logger.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" resolution-mode="require"/>
 import type { CreateSentry } from './sentry.js';
 export type LoggerContext = Record<string, any>;
 export interface LoggerOptions {
@@ -13,11 +14,12 @@ export interface LoggerOptions {
      * Defaults to `process.env.NODE_ENV === 'test'`
      */
     silent?: () => boolean;
+    output?: NodeJS.WriteStream;
 }
 export declare function attachSentryClientToLoggers(sentryClient: CreateSentry['client']): void;
 export declare function setGlobalLoggerContext(getContext: () => LoggerContext): void;
 export type Logger = ReturnType<typeof createLogger>;
-export declare function createLogger({ name, getContext, silent, }: LoggerOptions): {
+export declare function createLogger({ name, getContext, silent, output, }: LoggerOptions): {
     debug(message: string, context?: LoggerContext): void;
     info(message: string, context?: LoggerContext): void;
     warn(message: string, context?: LoggerContext): void;

package/dist/logger.js

@@ -24,12 +24,13 @@ function defaultGetContext() {
         ..._globalGetContext?.(),
     };
 }
-export function createLogger({ name, getContext, silent = () => process.env.NODE_ENV === 'test', }) {
+export function createLogger({ name, getContext, silent = () => process.env.NODE_ENV === 'test', output = process.stdout, }) {
     if (_loggers.has(name)) {
         throw new Error(`A logger named ${name} already exists`);
     }
     const hostname = os.hostname();
     const pid = process.pid;
+    const env = process.env.NODE_ENV;
     const logLevel = silent() ? LEVELS.FATAL + 1 : LEVELS.INFO;
     function getFinalContext(context) {
         return {
@@ -41,6 +42,7 @@ export function createLogger({ name, getContext, silent = () => process.env.NODE
     function log(level, message, context) {
         const payload = JSON.stringify({
             level: LEVELS_TO_NAME[level],
+            env,
             hostname,
             pid,
             name,
@@ -50,7 +52,7 @@ export function createLogger({ name, getContext, silent = () => process.env.NODE
             v: 1,
         });
         if (level >= logLevel) {
-            console.log(payload);
+            output.write(payload + '\n');
         }
     }
     const api = {

package/dist/middleware.d.ts

@@ -29,4 +29,4 @@ export declare function after(): RequestHandler;
 /**
  * Alias of `route()`
  */
-export declare function asyncMiddleware<RequestBody, RequestQuery = void>(fn: RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>): RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>;
+export declare function asyncMiddleware<RequestBody, RequestQuery = object>(fn: RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>): RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>;

package/dist/middleware.js

@@ -104,7 +104,7 @@ export function after() {
  * Alias of `route()`
  */
 export function asyncMiddleware(fn) {
-    return (req, res, next) => {
+    const handler = (req, res, next) => {
         return Promise.resolve(fn(req, res, next))
             .then((result) => {
             if (Array.isArray(result) &&
@@ -125,4 +125,6 @@ export function asyncMiddleware(fn) {
         })
             .catch(next);
     };
+    Object.defineProperty(handler, 'name', { value: fn.name });
+    return handler;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devmoods/express-extras",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Kubernetes-ready utilities for rapid Node.js application development",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,16 +24,16 @@
   "license": "ISC",
   "devDependencies": {
     "@devmoods/eslint-config": "^1.2.0",
-    "@sentry/types": "^7.61.1",
+    "@sentry/types": "^7.64.0",
     "@types/express-serve-static-core": "^4.17.35",
-    "@types/node": "20.4.8",
+    "@types/node": "20.5.0",
     "@types/supertest": "^2.0.12",
     "@typescript-eslint/eslint-plugin": "^6.3.0",
     "@typescript-eslint/parser": "^6.3.0",
     "@vitest/coverage-v8": "^0.34.1",
     "@vitest/expect": "^0.34.1",
     "chalk": "^5.3.0",
-    "eslint": "^8.46.0",
+    "eslint": "^8.47.0",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.33.1",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@devmoods/fetch": "^3.3.0",
     "@godaddy/terminus": "^4.12.1",
-    "@sentry/node": "^7.61.1",
+    "@sentry/node": "^7.64.0",
     "@types/bcrypt": "^5.0.0",
     "@types/body-parser": "^1.19.2",
     "@types/cookie-parser": "^1.4.3",