@geekmidas/constructs 0.0.22 → 0.2.0

package/src/endpoints/EndpointFactory.ts

@@ -9,10 +9,15 @@ import { ConsoleLogger } from '@geekmidas/logger/console';
 import type { Service } from '@geekmidas/services';
 import uniqBy from 'lodash.uniqby';
 import type { HttpMethod } from '../types';
-import type { Authorizer } from './Authorizer';
+import type {
+  Authorizer,
+  BuiltInSecuritySchemeId,
+  SecurityScheme,
+} from './Authorizer';
 import type { AuthorizeFn, SessionFn } from './Endpoint';
 import { EndpointBuilder } from './EndpointBuilder';
 import type { ActorExtractor } from './audit';
+import type { RlsConfig } from './rls';
 
 const DEFAULT_LOGGER = new ConsoleLogger() as any;
 
@@ -32,6 +37,13 @@ export class EndpointFactory<
   > = ExtractStorageAuditAction<NonNullable<TAuditStorage>>,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
+  TRlsConfig extends
+    | RlsConfig<TServices, TSession, TLogger>
+    | undefined = undefined,
 > {
   // @ts-ignore
   private defaultServices: TServices;
@@ -56,6 +68,8 @@ export class EndpointFactory<
     | Service<TDatabaseServiceName, TDatabase>
     | undefined;
   private defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  private customSecuritySchemes: TSecuritySchemes = {} as TSecuritySchemes;
+  private defaultRlsConfig?: TRlsConfig;
 
   constructor({
     basePath,
@@ -70,6 +84,8 @@ export class EndpointFactory<
     defaultAuditorStorage,
     defaultDatabaseService,
     defaultActorExtractor,
+    customSecuritySchemes = {} as TSecuritySchemes,
+    defaultRlsConfig,
   }: EndpointFactoryOptions<
     TServices,
     TBasePath,
@@ -81,7 +97,9 @@ export class EndpointFactory<
     TAuditStorage,
     TAuditStorageServiceName,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes,
+    TRlsConfig
   > = {}) {
     // Initialize default services
     this.defaultServices = uniqBy(
@@ -99,6 +117,8 @@ export class EndpointFactory<
     this.defaultAuditorStorage = defaultAuditorStorage;
     this.defaultDatabaseService = defaultDatabaseService;
     this.defaultActorExtractor = defaultActorExtractor;
+    this.customSecuritySchemes = customSecuritySchemes;
+    this.defaultRlsConfig = defaultRlsConfig;
   }
 
   static joinPaths<TBasePath extends string, P extends string>(
@@ -153,7 +173,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const authorizerConfigs = authorizers.map((name) => ({
       name,
@@ -170,7 +191,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -183,6 +206,74 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
+    });
+  }
+
+  /**
+   * Define custom security schemes for this factory.
+   * These extend the built-in schemes (jwt, bearer, apiKey, oauth2, oidc).
+   *
+   * @example
+   * ```typescript
+   * const router = e.securitySchemes({
+   *   awsIamSigV4: {
+   *     type: 'apiKey',
+   *     in: 'header',
+   *     name: 'Authorization',
+   *     'x-amazon-apigateway-authtype': 'awsSigv4',
+   *   },
+   * });
+   * ```
+   */
+  securitySchemes<T extends Record<string, SecurityScheme>>(
+    schemes: T,
+  ): EndpointFactory<
+    TServices,
+    TBasePath,
+    TLogger,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName,
+    TSecuritySchemes & T
+  > {
+    return new EndpointFactory<
+      TServices,
+      TBasePath,
+      TLogger,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName,
+      TSecuritySchemes & T
+    >({
+      defaultServices: this.defaultServices,
+      basePath: this.basePath,
+      defaultAuthorizeFn: this.defaultAuthorizeFn,
+      defaultLogger: this.defaultLogger,
+      defaultSessionExtractor: this.defaultSessionExtractor,
+      defaultEventPublisher: this.defaultEventPublisher,
+      availableAuthorizers: this.availableAuthorizers,
+      defaultAuthorizerName: this.defaultAuthorizerName,
+      defaultAuditorStorage: this.defaultAuditorStorage,
+      defaultDatabaseService: this.defaultDatabaseService,
+      defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: {
+        ...this.customSecuritySchemes,
+        ...schemes,
+      } as TSecuritySchemes & T,
     });
   }
 
@@ -190,9 +281,18 @@ export class EndpointFactory<
    * Set the default authorizer for all endpoints created from this factory.
    * Individual endpoints can override this by calling `.authorizer()` on the builder.
    * Use `'none'` to explicitly disable authorization for all endpoints.
+   *
+   * Accepts:
+   * - Built-in security scheme names: 'jwt', 'bearer', 'apiKey', 'oauth2', 'oidc'
+   * - Custom security scheme names defined via `.securitySchemes()`
+   * - 'none' to disable authorization
    */
   authorizer(
-    name: TAuthorizers[number] | 'none',
+    name:
+      | BuiltInSecuritySchemeId
+      | keyof TSecuritySchemes
+      | TAuthorizers[number]
+      | 'none',
   ): EndpointFactory<
     TServices,
     TBasePath,
@@ -205,9 +305,10 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
-    // Validate that the authorizer exists in available authorizers
+    // Validate that the authorizer exists in available authorizers (if authorizers() was called)
     if (name !== 'none' && this.availableAuthorizers.length > 0) {
       const authorizerExists = this.availableAuthorizers.some(
         (a) => a.name === name,
@@ -234,7 +335,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -243,10 +346,13 @@ export class EndpointFactory<
       defaultSessionExtractor: this.defaultSessionExtractor,
       defaultEventPublisher: this.defaultEventPublisher,
       availableAuthorizers: this.availableAuthorizers,
-      defaultAuthorizerName: name === 'none' ? undefined : name,
+      defaultAuthorizerName:
+        name === 'none' ? undefined : (name as TAuthorizers[number]),
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -265,7 +371,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const newBasePath = EndpointFactory.joinPaths(path, this.basePath);
     return new EndpointFactory<
@@ -280,7 +387,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: newBasePath,
@@ -293,6 +402,8 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -311,7 +422,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -325,7 +437,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -338,6 +452,8 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -356,7 +472,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       [...S, ...TServices],
@@ -370,7 +487,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: [...services, ...this.defaultServices],
       basePath: this.basePath,
@@ -383,6 +502,8 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -400,7 +521,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -414,7 +536,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -441,6 +565,8 @@ export class EndpointFactory<
         TSession,
         L
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -461,7 +587,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -475,7 +602,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -488,6 +617,8 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -505,7 +636,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -519,7 +651,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -541,6 +675,8 @@ export class EndpointFactory<
         T,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -562,7 +698,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     T,
-    TName
+    TName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -576,7 +713,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       T,
-      TName
+      TName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -592,6 +731,8 @@ export class EndpointFactory<
       defaultAuthorizerName: this.defaultAuthorizerName,
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: service,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -614,7 +755,8 @@ export class EndpointFactory<
     TName,
     ExtractStorageAuditAction<T>,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -628,7 +770,9 @@ export class EndpointFactory<
       TName,
       ExtractStorageAuditAction<T>,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -646,6 +790,8 @@ export class EndpointFactory<
         TSession,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
     });
   }
 
@@ -667,7 +813,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -681,7 +828,9 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TRlsConfig
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -694,6 +843,76 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: extractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: this.defaultRlsConfig,
+    });
+  }
+
+  /**
+   * Set the RLS (Row-Level Security) configuration for endpoints created from this factory.
+   * This enables automatic PostgreSQL session variable setting for RLS policies.
+   *
+   * @example
+   * ```typescript
+   * const api = new EndpointFactory()
+   *   .database(databaseService)
+   *   .session(extractSession)
+   *   .rls({
+   *     extractor: ({ session }) => ({
+   *       user_id: session.userId,
+   *       tenant_id: session.tenantId,
+   *     }),
+   *     prefix: 'app',
+   *   });
+   * ```
+   */
+  rls<TConfig extends RlsConfig<TServices, TSession, TLogger>>(
+    config: TConfig,
+  ): EndpointFactory<
+    TServices,
+    TBasePath,
+    TLogger,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName,
+    TSecuritySchemes,
+    TConfig
+  > {
+    return new EndpointFactory<
+      TServices,
+      TBasePath,
+      TLogger,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName,
+      TSecuritySchemes,
+      TConfig
+    >({
+      defaultServices: this.defaultServices,
+      basePath: this.basePath,
+      defaultAuthorizeFn: this.defaultAuthorizeFn,
+      defaultLogger: this.defaultLogger,
+      defaultSessionExtractor: this.defaultSessionExtractor,
+      defaultEventPublisher: this.defaultEventPublisher,
+      availableAuthorizers: this.availableAuthorizers,
+      defaultAuthorizerName: this.defaultAuthorizerName,
+      defaultAuditorStorage: this.defaultAuditorStorage,
+      defaultDatabaseService: this.defaultDatabaseService,
+      defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+      defaultRlsConfig: config,
     });
   }
 
@@ -782,6 +1001,14 @@ export class EndpointFactory<
       builder._actorExtractor = this.defaultActorExtractor;
     }
 
+    // Set custom security schemes
+    builder._customSecuritySchemes = this.customSecuritySchemes;
+
+    // Set RLS config if configured
+    if (this.defaultRlsConfig) {
+      builder._rlsConfig = this.defaultRlsConfig as any;
+    }
+
     return builder;
   }
 
@@ -849,6 +1076,13 @@ export interface EndpointFactoryOptions<
   TAuditStorageServiceName extends string = string,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
+  TRlsConfig extends
+    | RlsConfig<TServices, TSession, TLogger>
+    | undefined = undefined,
 > {
   defaultServices?: TServices;
   basePath?: TBasePath;
@@ -862,6 +1096,8 @@ export interface EndpointFactoryOptions<
   defaultAuditorStorage?: Service<TAuditStorageServiceName, TAuditStorage>;
   defaultDatabaseService?: Service<TDatabaseServiceName, TDatabase>;
   defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  customSecuritySchemes?: TSecuritySchemes;
+  defaultRlsConfig?: TRlsConfig;
 }
 
 export const e = new EndpointFactory();