rename method & add doc comments

Author: vas3a

src/core/auth/guards/auth.guard.ts

@@ -1,8 +1,14 @@
 import { Request } from 'express';
-import { decode } from './guards.utils';
+import { decodeAuthToken } from './guards.utils';
 
+/**
+ * Auth guard function to validate the authorization token from the request headers.
+ *
+ * @param req - The incoming HTTP request object.
+ * @returns A promise that resolves to `true` if the authorization token is valid, otherwise `false`.
+ */
 export const authGuard = async (req: Request) => {
-  if (!(await decode(req.headers.authorization ?? ''))) {
+  if (!(await decodeAuthToken(req.headers.authorization ?? ''))) {
     return false;
   }
 

src/core/auth/guards/guards.utils.ts

@@ -1,16 +1,25 @@
 import * as jwt from 'jsonwebtoken';
-// import { UnauthorizedException } from '@nestjs/common';
 import { Logger } from 'src/shared/global';
 import { getSigningKey } from '../jwt';
 
 const logger = new Logger('guards.utils()');
 
-export const decode = async (authHeader: string) => {
+/**
+ * Decodes and verifies a JWT token from the provided authorization header.
+ *
+ * @param authHeader - The authorization header containing the token, expected in the format "Bearer <token>".
+ * @returns A promise that resolves to the decoded JWT payload if the token is valid,
+ *          a string if the payload is a string, or `false` if the token is invalid or the header is improperly formatted.
+ *
+ * @throws This function does not throw directly but will return `false` if an error occurs during verification.
+ */
+export const decodeAuthToken = async (
+  authHeader: string,
+): Promise<boolean | jwt.JwtPayload | string> => {
   const [type, idToken] = authHeader?.split(' ') ?? [];
 
   if (type !== 'Bearer' || !idToken) {
     return false;
-    // throw new UnauthorizedException('Missing Authorization header!');
   }
 
   let decoded: jwt.JwtPayload | string;
@@ -20,7 +29,6 @@ export const decode = async (authHeader: string) => {
   } catch (error) {
     logger.error('Error verifying JWT', error);
     return false;
-    // throw new UnauthorizedException('Invalid or expired JWT!');
   }
 
   return decoded;

src/core/auth/guards/m2m-scope.guard.ts

@@ -1,12 +1,23 @@
 import { Request } from 'express';
-import { decode } from './guards.utils';
+import { decodeAuthToken } from './guards.utils';
 import { JwtPayload } from 'jsonwebtoken';
 import { M2mScope } from '../auth.constants';
 
+/**
+ * A utility function to check if the required M2M (Machine-to-Machine) scopes are present
+ * in the authorization token provided in the request headers.
+ *
+ * @param {...M2mScope[]} requiredM2mScopes - The list of required M2M scopes to validate against.
+ * @returns {Promise<(req: Request) => boolean>} A function that takes an Express `Request` object
+ * and returns a boolean indicating whether the required scopes are present.
+ *
+ * The function decodes the authorization token from the request headers and checks if
+ * the required scopes are included in the token's scope claim.
+ */
 export const checkM2MScope =
   (...requiredM2mScopes: M2mScope[]) =>
   async (req: Request) => {
-    const decodedAuth = await decode(req.headers.authorization ?? '');
+    const decodedAuth = await decodeAuthToken(req.headers.authorization ?? '');
 
     const authorizedScopes = ((decodedAuth as JwtPayload).scope ?? '').split(
       ' ',

src/core/auth/guards/role.guard.ts

@@ -1,11 +1,22 @@
 import { Request } from 'express';
-import { decode } from './guards.utils';
+import { decodeAuthToken } from './guards.utils';
 import { Role } from '../auth.constants';
 
+/**
+ * A utility function to check if the required user role are present
+ * in the authorization token provided in the request headers.
+ *
+ * @param {...Role[]} requiredUserRoles - The list of required user roles to validate against.
+ * @returns {Promise<(req: Request) => boolean>} A function that takes an Express `Request` object
+ * and returns a boolean indicating whether the required scopes are present.
+ *
+ * The function decodes the authorization token from the request headers and checks if
+ * the required user roles are included in the token's scope claim.
+ */
 export const checkHasUserRole =
   (...requiredUserRoles: Role[]) =>
   async (req: Request) => {
-    const decodedAuth = await decode(req.headers.authorization ?? '');
+    const decodedAuth = await decodeAuthToken(req.headers.authorization ?? '');
 
     const decodedUserRoles = Object.keys(decodedAuth).reduce((roles, key) => {
       if (key.match(/claims\/roles$/gi)) {