feat: add auditor to coreServices

Signed-off-by: Paul Schultz <pschultz@pobox.com> add auditor service Signed-off-by: Paul Schultz <pschultz@pobox.com> create eventAuditor and rootEventAuditor mockServices Signed-off-by: Paul Schultz <pschultz@pobox.com> run api report Signed-off-by: Paul Schultz <pschultz@pobox.com> rerun api report Signed-off-by: Paul Schultz <pschultz@pobox.com> apply requested changes Signed-off-by: Paul Schultz <pschultz@pobox.com> remove rootAuditor Signed-off-by: Paul Schultz <pschultz@pobox.com> run build:api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> misc fixes Signed-off-by: Paul Schultz <pschultz@pobox.com> misc fixes Signed-off-by: Paul Schultz <pschultz@pobox.com> add dynamic plugin auditor service factory Signed-off-by: Paul Schultz <pschultz@pobox.com> fix api report Signed-off-by: Paul Schultz <pschultz@pobox.com> rerun api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> add comments to auditor service Signed-off-by: Paul Schultz <pschultz@pobox.com> update api report Signed-off-by: Paul Schultz <pschultz@pobox.com> update api report Signed-off-by: Paul Schultz <pschultz@pobox.com> run api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> apply requested changes Signed-off-by: Paul Schultz <pschultz@pobox.com> run api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> fix tests Signed-off-by: Paul Schultz <pschultz@pobox.com> add auditor to the catalog plugin Signed-off-by: Paul Schultz <pschultz@pobox.com> fix tsc issues Signed-off-by: Paul Schultz <pschultz@pobox.com> update auditor service Signed-off-by: Paul Schultz <pschultz@pobox.com> rename 'args' to 'options' Signed-off-by: Paul Schultz <pschultz@pobox.com> update auditor event shape Signed-off-by: Paul Schultz <pschultz@pobox.com> add error option in auditor event shape Signed-off-by: Paul Schultz <pschultz@pobox.com> rename events Signed-off-by: Paul Schultz <pschultz@pobox.com> demo new api? Signed-off-by: Paul Schultz <pschultz@pobox.com> update service impl Signed-off-by: Paul Schultz <pschultz@pobox.com> update auditor api Signed-off-by: Paul Schultz <pschultz@pobox.com> update auditor api Signed-off-by: Paul Schultz <pschultz@pobox.com> add the auditor service to the scaffolder Signed-off-by: Paul Schultz <pschultz@pobox.com> update tests Signed-off-by: Paul Schultz <pschultz@pobox.com> run api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> revert config secret enumerator changes Signed-off-by: Paul Schultz <pschultz@pobox.com> clean up auditor api Signed-off-by: Paul Schultz <pschultz@pobox.com> add documentation Signed-off-by: Paul Schultz <pschultz@pobox.com> update auditor Signed-off-by: Paul Schultz <pschultz@pobox.com> add auditor to sign in/out Signed-off-by: Paul Schultz <pschultz@pobox.com> remove dynamic auditor Signed-off-by: Paul Schultz <pschultz@pobox.com> add winston dep back Signed-off-by: Paul Schultz <pschultz@pobox.com> run api-reports Signed-off-by: Paul Schultz <pschultz@pobox.com> run prettier Signed-off-by: Paul Schultz <pschultz@pobox.com> add the auditor service as a default service factory Signed-off-by: Paul Schultz <pschultz@pobox.com> fix eslint errror Signed-off-by: Paul Schultz <pschultz@pobox.com> revert auth changes Signed-off-by: Paul Schultz <pschultz@pobox.com>
2024-08-29 19:16:29 -05:00
parent 7b77cead3f
commit e0ae80edee
40 changed files with 3256 additions and 909 deletions
@@ -26,6 +26,40 @@ import { Readable } from 'stream';
 import type { Request as Request_2 } from 'express';
 import type { Response as Response_2 } from 'express';

+// @public (undocumented)
+export type AuditorCreateEvent<TRootMeta extends JsonObject> = (options: {
+  eventId: string;
+  severityLevel?: AuditorEventSeverityLevel;
+  request?: Request_2<any, any, any, any, any>;
+  meta?: TRootMeta;
+  suppressInitialEvent?: boolean;
+}) => Promise<{
+  success<TMeta extends JsonObject>(options?: { meta?: TMeta }): Promise<void>;
+  fail<TMeta extends JsonObject, TError extends Error>(
+    options: {
+      meta?: TMeta;
+    } & (
+      | {
+          error: TError;
+        }
+      | {
+          errors: TError[];
+        }
+    ),
+  ): Promise<void>;
+}>;
+
+// @public
+export type AuditorEventSeverityLevel = 'low' | 'medium' | 'high' | 'critical';
+
+// @public
+export interface AuditorService {
+  // (undocumented)
+  createEvent<TMeta extends JsonObject>(
+    options: Parameters<AuditorCreateEvent<TMeta>>[0],
+  ): ReturnType<AuditorCreateEvent<TMeta>>;
+}
+
 // @public
 export interface AuthService {
  authenticate(
@@ -185,6 +219,7 @@ export namespace coreServices {
  const httpRouter: ServiceRef<HttpRouterService, 'plugin', 'singleton'>;
  const lifecycle: ServiceRef<LifecycleService, 'plugin', 'singleton'>;
  const logger: ServiceRef<LoggerService, 'plugin', 'singleton'>;
+  const auditor: ServiceRef<AuditorService, 'plugin', 'singleton'>;
  const permissions: ServiceRef<PermissionsService, 'plugin', 'singleton'>;
  const permissionsRegistry: ServiceRef<
    PermissionsRegistryService,
@@ -0,0 +1,70 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { JsonObject } from '@backstage/types';
+import type { Request } from 'express';
+
+/**
+ * TODO: Rigorously define each level
+ *
+ * low (default): normal usage
+ * medium: accessing write endpoints
+ * high: non-root permission changes
+ * critical: root permission changes
+ * @public
+ */
+export type AuditorEventSeverityLevel = 'low' | 'medium' | 'high' | 'critical';
+
+/** @public */
+export type AuditorCreateEvent<TRootMeta extends JsonObject> = (options: {
+  /**
+   * Use kebab-case to name audit events (e.g., "user-login", "file-download").
+   *
+   * The `pluginId` already provides plugin/module context, so avoid redundant prefixes in the `eventId`.
+   */
+  eventId: string;
+
+  severityLevel?: AuditorEventSeverityLevel;
+
+  /** (Optional) The associated HTTP request, if applicable. */
+  request?: Request<any, any, any, any, any>;
+
+  /** (Optional) Additional metadata relevant to the event, structured as a JSON object. */
+  meta?: TRootMeta;
+
+  /** (Optional) Suppresses the automatic initial event. */
+  suppressInitialEvent?: boolean;
+}) => Promise<{
+  success<TMeta extends JsonObject>(options?: { meta?: TMeta }): Promise<void>;
+  fail<TMeta extends JsonObject, TError extends Error>(
+    options: {
+      meta?: TMeta;
+    } & ({ error: TError } | { errors: TError[] }),
+  ): Promise<void>;
+}>;
+
+/**
+ * A service that provides an auditor facility.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/auditor | service documentation} for more details.
+ *
+ * @public
+ */
+export interface AuditorService {
+  createEvent<TMeta extends JsonObject>(
+    options: Parameters<AuditorCreateEvent<TMeta>>[0],
+  ): ReturnType<AuditorCreateEvent<TMeta>>;
+}
@@ -161,6 +161,19 @@ export namespace coreServices {
    import('./LoggerService').LoggerService
  >({ id: 'core.logger' });

+  /**
+   * Plugin-level auditing.
+   *
+   * See {@link AuditorService}
+   * and {@link https://backstage.io/docs/backend-system/core-services/auditor | the service docs}
+   * for more information.
+   *
+   * @public
+   */
+  export const auditor = createServiceRef<
+    import('./AuditorService').AuditorService
+  >({ id: 'core.auditor' });
+
  /**
   * Permission system integration for authorization of user actions.
   *
@@ -14,36 +14,39 @@
 * limitations under the License.
 */

-export { coreServices } from './coreServices';
+export type {
+  AuditorCreateEvent,
+  AuditorEventSeverityLevel,
+  AuditorService,
+} from './AuditorService';
 export type {
  AuthService,
  BackstageCredentials,
-  BackstageUserPrincipal,
-  BackstageServicePrincipal,
+  BackstageNonePrincipal,
  BackstagePrincipalAccessRestrictions,
  BackstagePrincipalTypes,
-  BackstageNonePrincipal,
+  BackstageServicePrincipal,
+  BackstageUserPrincipal,
 } from './AuthService';
 export type {
  CacheService,
  CacheServiceOptions,
  CacheServiceSetOptions,
 } from './CacheService';
-export type { RootConfigService } from './RootConfigService';
+export { coreServices } from './coreServices';
 export type { DatabaseService } from './DatabaseService';
 export type { DiscoveryService } from './DiscoveryService';
-export type { RootHealthService } from './RootHealthService';
+export type { HttpAuthService } from './HttpAuthService';
 export type {
  HttpRouterService,
  HttpRouterServiceAuthPolicy,
 } from './HttpRouterService';
-export type { HttpAuthService } from './HttpAuthService';
 export type {
  LifecycleService,
-  LifecycleServiceStartupHook,
-  LifecycleServiceStartupOptions,
  LifecycleServiceShutdownHook,
  LifecycleServiceShutdownOptions,
+  LifecycleServiceStartupHook,
+  LifecycleServiceStartupOptions,
 } from './LifecycleService';
 export type { LoggerService } from './LoggerService';
 export type {
@@ -55,6 +58,8 @@ export type {
  PermissionsRegistryServiceAddResourceTypeOptions,
 } from './PermissionsRegistryService';
 export type { PluginMetadataService } from './PluginMetadataService';
+export type { RootConfigService } from './RootConfigService';
+export type { RootHealthService } from './RootHealthService';
 export type { RootHttpRouterService } from './RootHttpRouterService';
 export type { RootLifecycleService } from './RootLifecycleService';
 export type { RootLoggerService } from './RootLoggerService';
@@ -69,15 +74,15 @@ export type {
  SchedulerServiceTaskScheduleDefinitionConfig,
 } from './SchedulerService';
 export type {
+  UrlReaderService,
  UrlReaderServiceReadTreeOptions,
  UrlReaderServiceReadTreeResponse,
  UrlReaderServiceReadTreeResponseDirOptions,
  UrlReaderServiceReadTreeResponseFile,
-  UrlReaderServiceReadUrlResponse,
  UrlReaderServiceReadUrlOptions,
+  UrlReaderServiceReadUrlResponse,
  UrlReaderServiceSearchOptions,
  UrlReaderServiceSearchResponse,
  UrlReaderServiceSearchResponseFile,
-  UrlReaderService,
 } from './UrlReaderService';
 export type { BackstageUserInfo, UserInfoService } from './UserInfoService';