@dvsa/appdev-api-common 0.4.4 → 0.5.0

package/README.md

@@ -2,6 +2,7 @@
 
 Common code used by the various serverless microservices withing AppDev systems, published as a NPM package.
 
+## Developing
 ### Pre-requisites
 
 - Node.js (Please see `.nvmrc` for specific version)
@@ -47,3 +48,291 @@ Then in the project you wish to use this package, run:
 
 Once you've completed your local testing and/or to start again from scratch, you can run:
 `npm unlink @dvsa/appdev-api-common`
+
+# Contents
+
+## JWTAuthChecker
+
+### Overview
+`JWTAuthChecker` is a utility class for verifying JSON Web Tokens (JWT) and enforcing role-based access control (RBAC) in an Express application using `routing-controllers`.
+
+It performs authentication by extracting the JWT from the request headers, verifying its validity, and checking whether the user has the required roles to access a resource.
+
+## Usage
+
+### Example Usage in a Controller
+The `JWTAuthChecker.execute` method can be used in conjunction with the `@Authorized` decorator to enforce authentication and role-based access.
+
+#### Basic Authentication Check
+In the entry point to your service/application e.g. `src/index.ts`, bind the `JWTAuthChecker.execute` method to the `authorizationChecker` option in the `createExpressServer` function.
+```ts
+// ...other imports
+import { JWTAuthChecker } from '@dvsa/appdev-api-common';
+import { MyResource } from '@resources/MyResource';
+import { createExpressServer } from 'routing-controllers';
+
+export const app = createExpressServer({
+   cors: true,
+   defaultErrorHandler: false,
+   controllers: [MyResource],
+   authorizationChecker: JWTAuthChecker.execute,
+});
+```
+
+
+If no roles are required, the function will simply verify the JWT token.
+
+```ts
+import { Authorized, Get, JsonController } from "routing-controllers";
+
+@JsonController("/example")
+export class ExampleController {
+  @Authorized()
+  @Get("/secure-endpoint")
+  secureEndpoint() {
+    return { message: "Access granted" };
+  }
+}
+```
+
+#### Role-Based Access Control
+If specific roles are required, they can be passed as an argument.
+
+```ts
+@JsonController("/admin")
+export class AdminController {
+  @Authorized(["admin"])
+  @Get("/dashboard")
+  getAdminDashboard() {
+    return { message: "Admin access granted" };
+  }
+}
+```
+
+### Manually Checking JWT Authentication
+The `execute` method can also be called manually within custom middleware or service logic.
+
+```ts
+import { Action } from "routing-controllers";
+
+async function checkUserAuthorization(action: Action) {
+  try {
+    const isAuthorized = await JWTAuthChecker.execute(action, ["editor"]);
+    if (isAuthorized) {
+      console.log("User is authorized");
+    }
+  } catch (error) {
+    console.error("Authorization failed", error);
+  }
+}
+```
+
+## Environment Variables
+The behavior of the authentication check can be controlled using environment variables:
+
+- `IS_OFFLINE`: If set to `true`, the authentication check is bypassed (useful for local development).
+- `FORCE_LOCAL_AUTH`: If set to `true`, authentication is enforced even in offline mode.
+
+Example `.env` file:
+```sh
+IS_OFFLINE=true
+FORCE_LOCAL_AUTH=false
+```
+
+## Error Handling
+`JWTAuthChecker` throws an `AuthError` in case of authentication or authorization failures. The errors are structured with an HTTP status code and message.
+
+Possible errors:
+- **Missing Authorization header**: No token found in the request.
+- **No roles found in token**: The JWT does not contain any roles.
+- **Insufficient permissions**: The user does not have the required role(s).
+
+Example error response:
+```json
+{
+  "status": 401,
+  "message": "Insufficient permissions",
+  "code": "UNAUTHORIZED"
+}
+```
+
+# ClientCredentials
+
+## Overview
+`ClientCredentials` is a utility class for handling OAuth2 client credentials authentication. It fetches and manages an access token from an authorization server, caching it for reuse until it expires.
+
+This implementation helps applications authenticate machine-to-machine (M2M) interactions by using client credentials to obtain a bearer token.
+
+## Usage
+
+### Importing the `ClientCredentials` Class
+```ts
+import { ClientCredentials } from '@dvsa/appdev-api-common';
+```
+
+### Initializing the ClientCredentials Instance
+```ts
+const clientCredentials = new ClientCredentials(
+  "https://auth.example.com/token", // Token URL
+  "your-client-id", // Client ID
+  "your-client-secret", // Client Secret
+  "your-scope", // OAuth2 Scope
+  true // Debug mode (optional)
+);
+```
+
+### Retrieving an Access Token
+To obtain an access token, call the `getAccessToken` method. This method caches the token and only fetches a new one if the current token is expired or unavailable.
+
+```ts
+async function authenticate() {
+  try {
+    const accessToken = await clientCredentials.getAccessToken();
+    console.log("Access Token:", accessToken);
+  } catch (error) {
+    console.error("Failed to retrieve access token", error);
+  }
+}
+
+authenticate();
+```
+
+### Debugging Mode
+If `debugMode` is enabled (set to `true` during instantiation), the class will log debug messages indicating whether it is fetching a new token or using a cached one.
+
+Example logs:
+```sh
+[DEBUG] New access token fetched: eyJhbGciOi...
+[DEBUG] Using existing access token: eyJhbGciOi...
+```
+
+## Error Handling
+`ClientCredentials` throws an error if token retrieval fails. Ensure your application catches these errors to prevent failures in authentication-dependent workflows.
+
+Possible errors:
+- **Failed to fetch client credentials**: Occurs when the token endpoint returns a non-OK response.
+- **Error decoding access token**: Happens when the received JWT is invalid or cannot be parsed.
+
+Example error handling:
+```ts
+try {
+  const token = await clientCredentials.getAccessToken();
+} catch (error) {
+  console.error("Authentication error:", error);
+}
+```
+
+# DateTime
+
+## Overview
+`DateTime` is a utility class built on `dayjs` to provide a structured and flexible way to handle date and time operations. It supports parsing, formatting, arithmetic operations, and comparisons.
+
+## Usage
+
+### Importing the `DateTime` Class
+```ts
+import { DateTime } from '@dvsa/appdev-api-common';
+```
+
+### Creating a `DateTime` Instance
+You can create an instance of `DateTime` using a `Date`, `string`, or another `DateTime` instance.
+
+```ts
+const now = new DateTime(); // Current date and time
+const fromString = new DateTime("15/03/2025", "DD/MM/YYYY");
+const fromDate = new DateTime(new Date());
+```
+
+### Formatting Dates
+You can format a `DateTime` instance using the `format` method.
+
+```ts
+console.log(now.format("YYYY-MM-DD HH:mm:ss"));
+```
+
+### Standard UK Local Date Formats
+The class provides helper methods for formatting dates in UK local formats:
+
+```ts
+console.log(DateTime.StandardUkLocalDateTimeAdapter(now)); // "DD/MM/YYYY HH:mm:ss"
+console.log(DateTime.StandardUkLocalDateAdapter(now)); // "DD/MM/YYYY"
+```
+
+### Arithmetic Operations
+You can add or subtract time units to/from a `DateTime` instance.
+
+```ts
+const futureDate = now.add(5, "days");
+const pastDate = now.subtract(2, "weeks");
+```
+
+### Date Comparisons
+```ts
+const date1 = new DateTime("2025-03-10");
+const date2 = new DateTime("2025-03-15");
+
+console.log(date1.isBefore(date2)); // true
+console.log(date2.isAfter(date1)); // true
+console.log(date1.isBetween("2025-03-05", "2025-03-20")); // true
+```
+
+### Difference Between Dates
+Get the difference in various units:
+
+```ts
+const daysDiff = date1.daysDiff(date2); // Number of whole days between dates
+const hoursDiff = date1.diff(date2, "hour");
+console.log(`Difference: ${daysDiff} days, ${hoursDiff} hours`);
+```
+
+### Comparing Durations
+```ts
+const duration = date1.compareDuration(date2, "minute");
+console.log(`Difference in minutes: ${duration}`);
+```
+
+### Getting the Current Date
+```ts
+const today = DateTime.today();
+console.log(today);
+```
+
+## Error Handling
+Ensure that input dates are in a valid format when creating a `DateTime` instance. If an invalid format is provided, `dayjs` will handle parsing failures gracefully but may return an invalid instance.
+
+Example error handling:
+```ts
+const invalidDate = new DateTime("invalid-date");
+console.log(invalidDate.toString()); // Returns an invalid date string
+```
+
+
+# Compression
+
+## Overview
+`DataCompression` is a utility class to simplify the compression & decompression using Gzip and Gunzip algorithms.
+
+## Usage
+
+### Importing the `DataCompression` Class
+```ts
+import { DataCompression } from '@dvsa/appdev-api-common';
+```
+
+### Compressing Data
+This is the process of taking a plain JSON object and compressing it using Gzip.
+
+```ts
+const data = { key: 'value' };
+const compressedData = DataCompression.compress(data);
+// H4sIAAAAAAAAA6tWyk6tVLJSKkvMKU1VqgUAv5wYPw8AAAA=
+```
+
+### Decompressing Data
+This is the process of taking a compressed JSON object and decompressing it using Gunzip.
+
+```ts
+const data = "H4sIAAAAAAAAA6tWyk6tVLJSKkvMKU1VqgUAv5wYPw8AAAA=";
+const decompressedData = DataCompression.decompress(data);
+// { key: 'value' }
+```

package/index.d.ts

@@ -3,5 +3,6 @@ export * from "./auth/auth-checker";
 export * from "./auth/auth-errors";
 export * from "./auth/client-credentials";
 export * from "./auth/verify-jwt";
+export * from "./utils/compression";
 export * from "./utils/date-time";
 export * from "./validation/request-body";

package/index.js

@@ -19,5 +19,6 @@ __exportStar(require("./auth/auth-checker"), exports);
 __exportStar(require("./auth/auth-errors"), exports);
 __exportStar(require("./auth/client-credentials"), exports);
 __exportStar(require("./auth/verify-jwt"), exports);
+__exportStar(require("./utils/compression"), exports);
 __exportStar(require("./utils/date-time"), exports);
 __exportStar(require("./validation/request-body"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dvsa/appdev-api-common",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"keywords": ["dvsa", "nodejs", "typescript"],
 	"author": "DVSA",
 	"description": "Utils library for common API functionality",

package/utils/compression.d.ts

@@ -0,0 +1,16 @@
+export declare class DataCompression {
+    /**
+     * Extracts a compressed (in base64) string using gunzip into a JSON object
+     * @template T
+     * @param {string} compressedData
+     * @returns {T}
+     */
+    static decompress<T>(compressedData: string): T;
+    /**
+     * Compresses (with gzip) a JSON object into a base64 string
+     * @template T
+     * @param {T} data
+     * @returns {string}
+     */
+    static compress<T>(data: T): string;
+}

package/utils/compression.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataCompression = void 0;
+const node_zlib_1 = require("node:zlib");
+// biome-ignore lint/complexity/noStaticOnlyClass: Valid use case for a static class
+class DataCompression {
+    /**
+     * Extracts a compressed (in base64) string using gunzip into a JSON object
+     * @template T
+     * @param {string} compressedData
+     * @returns {T}
+     */
+    static decompress(compressedData) {
+        const gzippedBytes = Buffer.from(compressedData, "base64");
+        const unzippedJson = (0, node_zlib_1.gunzipSync)(gzippedBytes).toString();
+        return JSON.parse(unzippedJson);
+    }
+    /**
+     * Compresses (with gzip) a JSON object into a base64 string
+     * @template T
+     * @param {T} data
+     * @returns {string}
+     */
+    static compress(data) {
+        const jsonString = JSON.stringify(data);
+        const gzippedData = (0, node_zlib_1.gzipSync)(Buffer.from(jsonString));
+        return gzippedData.toString("base64");
+    }
+}
+exports.DataCompression = DataCompression;

package/validation/request-body.js

@@ -40,8 +40,6 @@ function ValidateRequestBody(schema, opts = { isArray: false, errorDetails: true
             const isValid = validateFunction(payload);
             // if an error exists, then return a 400 with details
             if (!isValid) {
-                console.error("Validation failed on body:", JSON.stringify(body));
-                console.error(validateFunction.errors);
                 throw new validation_error_1.ValidationError(http_status_codes_1.HttpStatus.BAD_REQUEST, "Validation failed", opts?.errorDetails ? validateFunction.errors : null);
             }
             // proceed with attached method if schema is valid

package/validation/validation-error.d.ts

@@ -1,14 +1,18 @@
+import type { ErrorObject } from "ajv";
 import { HttpStatus } from "../api/http-status-codes";
+type ValidationErrorDetails = Partial<ErrorObject[]> | string | null;
 export declare class ValidationError extends Error {
     private readonly statusCode;
     private readonly details;
-    constructor(statusCode?: HttpStatus, message?: string, details?: unknown | null);
+    constructor(statusCode?: HttpStatus, message?: string, details?: ValidationErrorDetails);
     toJSON(): {
         error: {
             name: string;
             message: string;
-            details: unknown;
+            details: ValidationErrorDetails;
             statusCode: number;
         };
     };
+    private unwrapErrorDetails;
 }
+export {};

package/validation/validation-error.js

@@ -19,10 +19,24 @@ class ValidationError extends Error {
             error: {
                 name: this.name,
                 message: this.message,
-                details: this.details,
+                details: this.unwrapErrorDetails(this.details),
                 statusCode: this.statusCode,
             },
         };
     }
+    unwrapErrorDetails = (details) => {
+        if (Array.isArray(details)) {
+            return details.map((error) => {
+                if (error &&
+                    typeof error === "object" &&
+                    "keyword" in error &&
+                    error.keyword === "enum") {
+                    return `${error.instancePath.replace("/", "")} ${error.message}: ${error.params?.allowedValues.join(", ")}`;
+                }
+                return error?.message || error;
+            });
+        }
+        return details;
+    };
 }
 exports.ValidationError = ValidationError;