Merge pull request #51 from DouglasNeuroInformatics/dev

add ability to pass metadata not included in token payload to `defineAbility` function

Author: joshunrau

example/app.ts

@@ -1,11 +1,11 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
 import { z } from 'zod';
 
 import { $BaseEnv, AppFactory, AuthModule, CryptoService } from '../src/index.js';
 import { AppController } from './app.controller.js';
 import { CatsModule } from './cats/cats.module.js';
 
-import type { UserQueryResult } from '../src/index.js';
-
 export default AppFactory.create({
   controllers: [AppController],
   docs: {
@@ -18,7 +18,7 @@ export default AppFactory.create({
       inject: [CryptoService],
       useFactory: (cryptoService: CryptoService) => {
         return {
-          defineAbility: (ability, payload): void => {
+          defineAbility: (ability, payload) => {
             if (payload.isAdmin) {
               ability.can('manage', 'all');
             }
@@ -32,7 +32,7 @@ export default AppFactory.create({
               isAdmin: z.boolean()
             })
           },
-          userQuery: async ({ username }): Promise<null | UserQueryResult<{ isAdmin: true }>> => {
+          userQuery: async ({ username }) => {
             if (username !== 'admin') {
               return null;
             }

src/modules/auth/__tests__/ability.factory.spec.ts

@@ -2,6 +2,8 @@ import { Test } from '@nestjs/testing';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { Mock } from 'vitest';
 
+import { MockFactory } from '../../../testing/index.js';
+import { LoggingService } from '../../logging/logging.service.js';
 import { AbilityFactory } from '../ability.factory.js';
 import { DEFINE_ABILITY_TOKEN } from '../auth.config.js';
 
@@ -19,22 +21,23 @@ describe('AbilityFactory', () => {
         {
           provide: DEFINE_ABILITY_TOKEN,
           useValue: defineAbility
-        }
+        },
+        MockFactory.createForService(LoggingService)
       ]
     }).compile();
     abilityFactory = moduleRef.get(AbilityFactory);
   });
 
   describe('createForPayload', () => {
     it('should return an empty ruleset, if defineAbility is undefined', () => {
-      const ability = abilityFactory.createForPayload({});
+      const ability = abilityFactory.createForPayload({}, null);
       expect(ability.rules).toStrictEqual([]);
     });
     it('should add the correct ruleset for the ability', () => {
       defineAbility.mockImplementationOnce((ability) => {
         ability.can('manage', 'all');
       });
-      const ability = abilityFactory.createForPayload({});
+      const ability = abilityFactory.createForPayload({}, null);
       expect(ability.rules).toStrictEqual([
         {
           action: 'manage',
@@ -47,7 +50,7 @@ describe('AbilityFactory', () => {
       defineAbility.mockImplementationOnce((ability) => {
         ability.can('manage', 'Cat', { id: { in: [0, 1] } });
       });
-      const ability = abilityFactory.createForPayload({});
+      const ability = abilityFactory.createForPayload({}, null);
       expect(ability.rules).toStrictEqual([
         {
           action: 'manage',

src/modules/auth/__tests__/auth.module.spec.ts

@@ -118,15 +118,15 @@ describe('AuthModule', () => {
 
     it('should return status code 401 if the hashed password is incorrect', async () => {
       const comparePassword = vi.spyOn(CryptoService.prototype, 'comparePassword');
-      userQuery.mockResolvedValueOnce({ hashedPassword: '123$123', tokenPayload });
+      userQuery.mockResolvedValueOnce({ hashedPassword: '123$123', metadata: null, tokenPayload });
       const response = await request(server).post('/auth/login').send(loginCredentials);
       expect(response.status).toBe(401);
       expect(userQuery).toHaveBeenCalledExactlyOnceWith(loginCredentials);
       expect(comparePassword).toHaveBeenCalledExactlyOnceWith(loginCredentials.password, '123$123');
     });
 
     it('should return status code 200 and an access token if the credentials are correct', async () => {
-      userQuery.mockResolvedValueOnce({ hashedPassword, tokenPayload });
+      userQuery.mockResolvedValueOnce({ hashedPassword, metadata: null, tokenPayload });
       const response = await request(server).post('/auth/login').send(loginCredentials);
       expect(response.status).toBe(200);
       expect(response.body).toStrictEqual({
@@ -152,7 +152,7 @@ describe('AuthModule', () => {
       });
       it('should reject queries with a valid access token, but insufficient permissions', async () => {
         const signAsync = vi.spyOn(jwtService, 'signAsync');
-        userQuery.mockResolvedValueOnce({ hashedPassword, tokenPayload });
+        userQuery.mockResolvedValueOnce({ hashedPassword, metadata: null, tokenPayload });
         defineAbility.mockImplementationOnce((ability) => {
           ability.can('delete', 'Cat');
         });
@@ -177,7 +177,7 @@ describe('AuthModule', () => {
       let accessToken: string;
 
       beforeAll(async () => {
-        userQuery.mockResolvedValueOnce({ hashedPassword, tokenPayload });
+        userQuery.mockResolvedValueOnce({ hashedPassword, metadata: null, tokenPayload });
         defineAbility.mockImplementationOnce((ability) => {
           ability.can('manage', 'Cat');
         });

src/modules/auth/__tests__/auth.service.spec.ts

@@ -6,6 +6,7 @@ import type { Mock } from 'vitest';
 
 import { MockFactory } from '../../../testing/index.js';
 import { CryptoService } from '../../crypto/crypto.service.js';
+import { LoggingService } from '../../logging/logging.service.js';
 import { AbilityFactory } from '../ability.factory.js';
 import { USER_QUERY_TOKEN } from '../auth.config.js';
 import { AuthService } from '../auth.service.js';
@@ -31,7 +32,8 @@ describe('AuthService', () => {
         AuthService,
         MockFactory.createForService(AbilityFactory),
         MockFactory.createForService(CryptoService),
-        MockFactory.createForService(JwtService)
+        MockFactory.createForService(JwtService),
+        MockFactory.createForService(LoggingService)
       ]
     }).compile();
     abilityFactory = moduleRef.get(AbilityFactory);

src/modules/auth/ability.factory.ts

@@ -2,6 +2,7 @@ import { AbilityBuilder, detectSubjectType } from '@casl/ability';
 import { createPrismaAbility } from '@casl/prisma';
 import { Inject, Injectable } from '@nestjs/common';
 
+import { LoggingService } from '../logging/logging.service.js';
 import { DEFINE_ABILITY_TOKEN } from './auth.config.js';
 
 import type { AppAbilities, AppAbility, DefineAbility, Permission } from './auth.config.js';
@@ -15,19 +16,31 @@ export class AbilityFactory {
     return detectSubjectType(obj);
   };
 
-  constructor(@Inject(DEFINE_ABILITY_TOKEN) private readonly defineAbility?: DefineAbility) {}
+  constructor(
+    private readonly loggingService: LoggingService,
+    @Inject(DEFINE_ABILITY_TOKEN) private readonly defineAbility?: DefineAbility
+  ) {}
 
-  createForPayload(tokenPayload: { [key: string]: any }): AppAbility {
+  createForPayload(payload: { [key: string]: any }, metadata: unknown): AppAbility {
+    this.loggingService.verbose({
+      message: 'Creating Ability From Payload',
+      metadata,
+      payload
+    });
     const abilityBuilder = new AbilityBuilder<AppAbility>(createPrismaAbility);
     if (this.defineAbility) {
-      this.defineAbility(abilityBuilder, tokenPayload);
+      this.defineAbility(abilityBuilder, payload, metadata);
     }
     return abilityBuilder.build({
       detectSubjectType: this.detectSubjectType
     });
   }
 
   createForPermissions(permissions: Permission[]): AppAbility {
+    this.loggingService.verbose({
+      message: 'Creating Ability From Permissions',
+      permissions
+    });
     return createPrismaAbility<AppAbilities>(permissions, {
       detectSubjectType: this.detectSubjectType
     });

src/modules/auth/auth.config.ts

@@ -5,6 +5,7 @@ import type { FallbackIfNever } from '@douglasneuroinformatics/libjs';
 import { ConfigurableModuleBuilder } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
 import type { DefaultSelection } from '@prisma/client/runtime/library';
+import type { IfNever } from 'type-fest';
 import type { z } from 'zod';
 
 import { defineToken } from '../../utils/token.utils.js';
@@ -33,9 +34,10 @@ type AppConditions = FallbackIfNever<PrismaQuery, unknown>;
 
 type AppAbility = PureAbility<AppAbilities, AppConditions>;
 
-type DefineAbility<TPayload extends { [key: string]: unknown } = { [key: string]: unknown }> = (
+type DefineAbility<TPayload extends { [key: string]: unknown } = { [key: string]: unknown }, TMetadata = any> = (
   ability: AbilityBuilder<AppAbility>,
-  tokenPayload: TPayload
+  tokenPayload: TPayload,
+  metadata: TMetadata
 ) => void;
 
 type Permission = RawRuleOf<PureAbility<[AppAction, AppSubjectName]>>;
@@ -51,34 +53,44 @@ interface JwtPayload {
   permissions: Permission[];
 }
 
-type UserQueryResult<TPayload extends { [key: string]: unknown } = { [key: string]: unknown }> = {
+type UserQueryResult<
+  TPayload extends { [key: string]: unknown } = { [key: string]: unknown },
+  TMetadata = never
+> = IfNever<TMetadata, {}, { metadata: TMetadata }> & {
   hashedPassword: string;
   tokenPayload: TPayload;
 };
 
 type UserQuery<
   TLoginCredentials extends BaseLoginCredentials = BaseLoginCredentials,
-  TPayload extends { [key: string]: unknown } = { [key: string]: unknown }
-> = (credentials: TLoginCredentials) => Promise<null | UserQueryResult<TPayload>>;
+  TPayload extends { [key: string]: unknown } = { [key: string]: unknown },
+  TMetadata = any
+> = (credentials: TLoginCredentials) => Promise<null | UserQueryResult<TPayload, TMetadata>>;
 
 type LoginResponseBody = {
   accessToken: string;
 };
 
 type AuthModuleOptions<
   TLoginCredentialsSchema extends BaseLoginCredentialsSchema = BaseLoginCredentialsSchema,
-  TPayloadSchema extends z.ZodType<{ [key: string]: unknown }> = z.ZodType<{ [key: string]: unknown }>
+  TPayloadSchema extends z.ZodType<{ [key: string]: unknown }> = z.ZodType<{ [key: string]: unknown }>,
+  TMetadataSchema extends z.ZodTypeAny = z.ZodNever
 > = {
-  defineAbility: (ability: AbilityBuilder<AppAbility>, tokenPayload: z.TypeOf<TPayloadSchema>) => any;
+  defineAbility: (
+    ability: AbilityBuilder<AppAbility>,
+    tokenPayload: z.TypeOf<TPayloadSchema>,
+    metadata: z.TypeOf<TMetadataSchema>
+  ) => any;
   schemas: {
     loginCredentials: TLoginCredentialsSchema;
+    metadata?: TMetadataSchema;
     tokenPayload: TPayloadSchema;
   };
-  userQuery: UserQuery<z.TypeOf<TLoginCredentialsSchema>, z.TypeOf<TPayloadSchema>>;
+  userQuery: UserQuery<z.TypeOf<TLoginCredentialsSchema>, z.TypeOf<TPayloadSchema>, z.TypeOf<TMetadataSchema>>;
 };
 
 export const { ConfigurableModuleClass: ConfigurableAuthModule, MODULE_OPTIONS_TOKEN: AUTH_MODULE_OPTIONS_TOKEN } =
-  new ConfigurableModuleBuilder<AuthModuleOptions<any, any>>()
+  new ConfigurableModuleBuilder<AuthModuleOptions<any, any, any>>()
     .setClassMethodName('forRoot')
     .setExtras({}, (definition) => ({
       ...definition,

src/modules/auth/auth.module.ts

@@ -65,15 +65,20 @@ export class AuthModule extends ConfigurableAuthModule implements OnModuleInit {
 
   static forRoot<
     TLoginCredentialsSchema extends BaseLoginCredentialsSchema,
-    TPayloadSchema extends z.ZodType<{ [key: string]: unknown }>
-  >(options: AuthModuleOptions<TLoginCredentialsSchema, TPayloadSchema>): DynamicModule {
+    TPayloadSchema extends z.ZodType<{ [key: string]: unknown }>,
+    TMetadataSchema extends z.ZodTypeAny = z.ZodNever
+  >(options: AuthModuleOptions<TLoginCredentialsSchema, TPayloadSchema, TMetadataSchema>): DynamicModule {
     return super.forRoot(options);
   }
   static forRootAsync<
     TLoginCredentialsSchema extends BaseLoginCredentialsSchema,
-    TPayloadSchema extends z.ZodType<{ [key: string]: unknown }>
+    TPayloadSchema extends z.ZodType<{ [key: string]: unknown }>,
+    TMetadataSchema extends z.ZodTypeAny = z.ZodNever
   >(
-    options: ConfigurableModuleAsyncOptions<AuthModuleOptions<TLoginCredentialsSchema, TPayloadSchema>, 'create'>
+    options: ConfigurableModuleAsyncOptions<
+      AuthModuleOptions<TLoginCredentialsSchema, TPayloadSchema, TMetadataSchema>,
+      'create'
+    >
   ): DynamicModule {
     return super.forRootAsync(options);
   }

src/modules/auth/auth.service.ts

@@ -2,6 +2,7 @@ import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 
 import { CryptoService } from '../crypto/crypto.service.js';
+import { LoggingService } from '../logging/logging.service.js';
 import { AbilityFactory } from './ability.factory.js';
 import { USER_QUERY_TOKEN } from './auth.config.js';
 
@@ -13,7 +14,8 @@ export class AuthService {
     @Inject(USER_QUERY_TOKEN) private readonly userQuery: UserQuery,
     private readonly abilityFactory: AbilityFactory,
     private readonly cryptoService: CryptoService,
-    private readonly jwtService: JwtService
+    private readonly jwtService: JwtService,
+    private readonly loggingService: LoggingService
   ) {}
 
   async login(credentials: BaseLoginCredentials): Promise<LoginResponseBody> {
@@ -26,12 +28,16 @@ export class AuthService {
       throw new UnauthorizedException('Invalid Credentials');
     }
 
-    const ability = this.abilityFactory.createForPayload(user.tokenPayload);
+    const ability = this.abilityFactory.createForPayload(user.tokenPayload, user.metadata);
 
     return { accessToken: await this.signToken({ ...user.tokenPayload, permissions: ability.rules }) };
   }
 
   private async signToken(payload: JwtPayload): Promise<string> {
+    this.loggingService.verbose({
+      message: 'Signing JWT',
+      payload
+    });
     return this.jwtService.signAsync(payload, {
       expiresIn: '1d'
     });

src/modules/auth/guards/__tests__/jwt-auth.guard.spec.ts

@@ -24,6 +24,7 @@ vi.mock('@nestjs/passport', () => ({ AuthGuard: () => BaseConstructor }));
 describe('JwtAuthGuard', () => {
   let guard: JwtAuthGuard;
 
+  let abilityFactory: AbilityFactory;
   let loggingService: MockedInstance<LoggingService>;
   let reflector: MockedInstance<Reflector>;
 
@@ -39,6 +40,7 @@ describe('JwtAuthGuard', () => {
     loggingService = MockFactory.createMock(LoggingService);
     reflector = MockFactory.createMock(Reflector);
     guard = new JwtAuthGuard(loggingService as any, reflector);
+    abilityFactory = new AbilityFactory(loggingService as unknown as LoggingService);
   });
 
   it('should extend BaseConstructor', () => {
@@ -94,7 +96,7 @@ describe('JwtAuthGuard', () => {
       subject: 'all'
     } satisfies RouteAccessType);
     BaseConstructor.prototype.canActivate.mockResolvedValueOnce(true);
-    const ability = AbilityFactory.prototype.createForPermissions([{ action: 'manage', subject: 'Cat' }]);
+    const ability = abilityFactory.createForPermissions([{ action: 'manage', subject: 'Cat' }]);
     getRequest.mockReturnValueOnce({ url: 'http://localhost:5500', user: { ability } });
     await expect(guard.canActivate(context)).resolves.toBe(false);
   });
@@ -111,7 +113,7 @@ describe('JwtAuthGuard', () => {
       }
     ] satisfies RouteAccessType);
     BaseConstructor.prototype.canActivate.mockResolvedValueOnce(true);
-    const ability = AbilityFactory.prototype.createForPermissions([{ action: 'read', subject: 'Cat' }]);
+    const ability = abilityFactory.createForPermissions([{ action: 'read', subject: 'Cat' }]);
     getRequest.mockReturnValueOnce({ url: 'http://localhost:5500', user: { ability } });
     await expect(guard.canActivate(context)).resolves.toBe(false);
   });
@@ -122,7 +124,7 @@ describe('JwtAuthGuard', () => {
       subject: 'all'
     } satisfies RouteAccessType);
     BaseConstructor.prototype.canActivate.mockResolvedValueOnce(true);
-    const ability = AbilityFactory.prototype.createForPermissions([{ action: 'manage', subject: 'all' }]);
+    const ability = abilityFactory.createForPermissions([{ action: 'manage', subject: 'all' }]);
     getRequest.mockReturnValueOnce({ url: 'http://localhost:5500', user: { ability } });
     await expect(guard.canActivate(context)).resolves.toBe(true);
   });