chore: deprecate audit-log-node

plugins/audit-log-node/README.md

@@ -1,222 +1,3 @@
-# @janus-idp/backstage-plugin-audit-log-node
+# ❗DEPRECATED❗
 
-This package contains common types and utility functions for audit logging the backend
-
-## Installation
-
-To install this plugin in a package/plugin, run the following command:
-
-```console
-yarn workspace <package/plugin> add @janus-idp/backstage-plugin-audit-log-node
-```
-
-### Usage
-
-The audit logging node package contains a helper class for generating audit logs with a common structure, as well as logging them.
-
-The `auditLog` function can be used to log out an audit log using the backstage `LoggerService`. You can provide a log level to the `auditLog` function. The supported levels are: `info`, `debug`, `warn`, and `error`. If no log level is provided, it defaults to the `info` level.
-
-Alternatively, if you want to generate the audit log object (does not contain message) without it being logged out for you, the `createAuditLogDetails` helper function of the `DefaultAuditLogger` can be used.
-
-The `DefaultAuditLogger.createAuditLogDetails` will generate the `actorId` of the actor with the following priority (highest to lowest):
-
-- The `actorId` provided in the arguments
-- The actor id generated from the `express.Request` object provided in the arguments
-- `null` if neither of the above fields were provided in the arguments
-
-#### Event Naming Convention
-
-It is recommended that you prefix the `eventName` value with the name of the component you are audit logging. This will help with searchability in the central log collector.
-
-For example, "ScaffolderTaskRead", "CatalogEntityFetch", etc.
-
----
-
-**IMPORTANT**
-
-Any fields containing secrets provided to these helper functions should have secrets redacted or else they will be logged as is.
-
-For the `DefaultAuditLogger`, these fields would include:
-
-- The `metadata` field
-- The following fields in the `request`:
-  - `request.body`
-  - `request.params`
-  - `request.query`
-- The `response.body` field
-
----
-
-The `getActorId` helper function grabs the specified entityRef of the user or service associated with the provided credentials in the provided express Request object. If no request is provided or no user/service was associated to the request, `undefined` is returned.
-
-### Example
-
-#### Audit Log Example
-
-In the following example, we add a simple audit log for the `/health` endpoint of a plugin's router to the `debug` log level.
-
-```ts plugins/test/src/service/router.ts
-import {
-  AuthService,
-  HttpAuthService,
-  LoggerService,
-} from '@backstage/backend-plugin-api';
-import { Config } from '@backstage/config';
-
-/* highlight-add-start */
-import { DefaultAuditLogger } from '@janus-idp/backstage-plugin-audit-log-node';
-
-/* highlight-add-end */
-
-export interface RouterOptions {
-  logger: LoggerService;
-  config: Config;
-  auth: AuthService;
-  httpAuth: HttpAuthService;
-}
-
-export async function createRouter(
-  options: RouterOptions,
-): Promise<express.Router> {
-  const { logger, config, auth, httpAuth } = options;
-
-  /* highlight-add-start */
-  const auditLogger = new DefaultAuditLogger({
-    logger,
-    auth,
-    httpAuth,
-  });
-  /* highlight-add-end */
-
-  const router = Router();
-  router.use(express.json());
-
-  router.get('/health', async (request, response) => {
-    logger.info('PONG!');
-    response.json({ status: 'ok' });
-
-    /* highlight-add-start */
-    // Note: if `level` is not provided, it defaults to `info`
-    auditLogger.auditLog({
-      eventName: 'HealthEndpointHit',
-      stage: 'completion',
-      status: 'succeeded',
-      level: 'debug',
-      request,
-      response: {
-        status: 200,
-        body: { status: 'ok' },
-      },
-      message: `The Health Endpoint was hit by ${await auditLogger.getActorId(
-        request,
-      )}`,
-    });
-    /* highlight-add-end */
-  });
-
-  const middleware = MiddlewareFactory.create({ logger, config });
-
-  router.use(middleware.error());
-  return router;
-}
-```
-
-Assuming the `user:default/tester` user hit requested this endpoint, something similar to the following would be outputted if the logger format is JSON:
-
-```JSON
-{"actor":{"actorId":"user:default/tester","hostname":"localhost","ip":"::1","userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"},"eventName":"HealthEndpointHit","isAuditLog":true,"level":"debug","message":"The Health Endpoint was hit by user:default/tester","meta":{},"plugin":"test","request":{"body": "","method":"GET","params":{},"query":{},"url":"/api/test/health"},"service":"backstage","stage":"completion","status":"succeeded","timestamp":"2024-05-17 11:17:07","type":"plugin"}
-```
-
-#### Audit Log Error Example
-
-In the following example, we utilize the `auditLog` utility function to generate and output an error log to the `error` log level:
-
-```ts plugins/test/src/service/router.ts
-import {
-  AuthService,
-  HttpAuthService,
-  LoggerService,
-} from '@backstage/backend-plugin-api';
-
-/* highlight-add-start */
-import { DefaultAuditLogger } from '@janus-idp/backstage-plugin-audit-log-node';
-
-/* highlight-add-end */
-
-export interface RouterOptions {
-  logger: LoggerService;
-  auth: AuthService;
-  httpAuth: HttpAuthService;
-}
-
-export async function createRouter(
-  options: RouterOptions,
-): Promise<express.Router> {
-  const { logger, auth, httpAuth } = options;
-
-  /* highlight-add-start */
-  const auditLogger = new DefaultAuditLogger({
-    logger,
-    auth,
-    httpAuth,
-  });
-  /* highlight-add-end */
-
-  const router = Router();
-  router.use(express.json());
-
-  router.get('/error', async (request, response) => {
-    try {
-      const customErr = new Error('Custom Error Occurred');
-      customErr.name = 'CustomError';
-
-      throw customErr;
-
-      response.json({
-        status: 'ok',
-      });
-    } catch (err) {
-      /* highlight-add-start */
-      auditLogger.auditLog({
-        eventName: 'ErrorEndpointHit',
-        stage: 'completion',
-        status: 'failed',
-        level: 'error',
-        request,
-        response: {
-          status: 501,
-          body: {
-            errors: [
-              {
-                name: (err as Error).name,
-                message: (err as Error).message,
-              },
-            ],
-          },
-        },
-        errors: [customErr],
-        message: `An error occurred when querying the '/errors' endpoint`,
-      });
-      /* highlight-add-end */
-      // Do something with the caught error
-      response.status(501).json({
-        errors: [
-          {
-            name: (err as Error).name,
-            message: (err as Error).message,
-          },
-        ],
-      });
-    }
-  });
-  router.use(errorHandler());
-  return router;
-}
-```
-
-An example error audit log would be in the following form:
-Note: the stack trace was removed redacted in this example due to its size.
-
-```JSON
-{"actor":{"actorId":"user:development/guest","hostname":"localhost","ip":"::1","userAgent":"curl/8.2.1"},"errors":[{"message":"Custom Error Occurred","name":"CustomError","stack":"CustomError: Custom Error Occurred\n    at STACK_TRACE]"}],"eventName":"ErrorEndpointHit","isAuditLog":true,"level":"error","message":"An error occurred when querying the '/errors' endpoint","meta":{},"plugin":"test","request":{"body":{},"method":"GET","params":{},"query":{},"url":"/api/test/error"},"response":{"body":{"errors":[{"name":"CustomError","message":"Custom Error Occurred"}]},"status":501},"service":"backstage","stage":"completion","status":"failed","timestamp":"2024-05-23 10:09:04"}
-```
+Starting from Backstage v1.36.0, the Auditor Service will be included in Backstage's core services. As a result, this package is now deprecated.