@geekmidas/constructs 0.0.21 → 0.1.0

package/src/endpoints/EndpointBuilder.ts

@@ -12,7 +12,8 @@ import uniqBy from 'lodash.uniqby';
 import { ConstructType } from '../Construct';
 import { BaseFunctionBuilder } from '../functions';
 import type { HttpMethod } from '../types';
-import type { Authorizer } from './Authorizer';
+import type { Authorizer, SecurityScheme } from './Authorizer';
+import { getSecurityScheme } from './Authorizer';
 import { Endpoint, type EndpointSchemas } from './Endpoint';
 import type {
   AuthorizeFn,
@@ -66,6 +67,7 @@ export class EndpointBuilder<
   _authorizerName?: TAuthorizers[number];
   _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  _customSecuritySchemes: Record<string, SecurityScheme> = {};
 
   constructor(
     readonly route: TRoute,
@@ -616,9 +618,27 @@ export class EndpointBuilder<
     TDatabaseServiceName
   > {
     // Find authorizer metadata if name is set
-    const authorizer = this._authorizerName
-      ? this._availableAuthorizers.find((a) => a.name === this._authorizerName)
-      : undefined;
+    // If the authorizer name is set but not in availableAuthorizers, create a simple authorizer object
+    let authorizer: Authorizer | undefined;
+    if (this._authorizerName) {
+      const existingAuthorizer = this._availableAuthorizers.find(
+        (a) => a.name === this._authorizerName,
+      );
+
+      if (existingAuthorizer) {
+        authorizer = existingAuthorizer;
+      } else {
+        // Create authorizer with security scheme if available (built-in or custom)
+        const securityScheme = getSecurityScheme(
+          this._authorizerName as string,
+          this._customSecuritySchemes,
+        );
+        authorizer = {
+          name: this._authorizerName as string,
+          securityScheme,
+        };
+      }
+    }
 
     return new Endpoint({
       fn,

package/src/endpoints/EndpointFactory.ts

@@ -9,7 +9,11 @@ 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';
@@ -32,6 +36,10 @@ export class EndpointFactory<
   > = ExtractStorageAuditAction<NonNullable<TAuditStorage>>,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
 > {
   // @ts-ignore
   private defaultServices: TServices;
@@ -56,6 +64,7 @@ export class EndpointFactory<
     | Service<TDatabaseServiceName, TDatabase>
     | undefined;
   private defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  private customSecuritySchemes: TSecuritySchemes = {} as TSecuritySchemes;
 
   constructor({
     basePath,
@@ -70,6 +79,7 @@ export class EndpointFactory<
     defaultAuditorStorage,
     defaultDatabaseService,
     defaultActorExtractor,
+    customSecuritySchemes = {} as TSecuritySchemes,
   }: EndpointFactoryOptions<
     TServices,
     TBasePath,
@@ -81,7 +91,8 @@ export class EndpointFactory<
     TAuditStorage,
     TAuditStorageServiceName,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > = {}) {
     // Initialize default services
     this.defaultServices = uniqBy(
@@ -99,6 +110,7 @@ export class EndpointFactory<
     this.defaultAuditorStorage = defaultAuditorStorage;
     this.defaultDatabaseService = defaultDatabaseService;
     this.defaultActorExtractor = defaultActorExtractor;
+    this.customSecuritySchemes = customSecuritySchemes;
   }
 
   static joinPaths<TBasePath extends string, P extends string>(
@@ -153,7 +165,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const authorizerConfigs = authorizers.map((name) => ({
       name,
@@ -170,7 +183,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -183,6 +197,150 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+    });
+  }
+
+  /**
+   * 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,
+    });
+  }
+
+  /**
+   * 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:
+      | BuiltInSecuritySchemeId
+      | keyof TSecuritySchemes
+      | TAuthorizers[number]
+      | 'none',
+  ): EndpointFactory<
+    TServices,
+    TBasePath,
+    TLogger,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName,
+    TSecuritySchemes
+  > {
+    // 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,
+      );
+      if (!authorizerExists) {
+        const available = this.availableAuthorizers
+          .map((a) => a.name)
+          .join(', ');
+        throw new Error(
+          `Authorizer "${name as string}" not found in available authorizers: ${available}`,
+        );
+      }
+    }
+
+    return new EndpointFactory<
+      TServices,
+      TBasePath,
+      TLogger,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName,
+      TSecuritySchemes
+    >({
+      defaultServices: this.defaultServices,
+      basePath: this.basePath,
+      defaultAuthorizeFn: this.defaultAuthorizeFn,
+      defaultLogger: this.defaultLogger,
+      defaultSessionExtractor: this.defaultSessionExtractor,
+      defaultEventPublisher: this.defaultEventPublisher,
+      availableAuthorizers: this.availableAuthorizers,
+      defaultAuthorizerName:
+        name === 'none' ? undefined : (name as TAuthorizers[number]),
+      defaultAuditorStorage: this.defaultAuditorStorage,
+      defaultDatabaseService: this.defaultDatabaseService,
+      defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -201,7 +359,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const newBasePath = EndpointFactory.joinPaths(path, this.basePath);
     return new EndpointFactory<
@@ -216,7 +375,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: newBasePath,
@@ -229,6 +389,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -247,7 +408,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -261,7 +423,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -274,6 +437,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -292,7 +456,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       [...S, ...TServices],
@@ -306,7 +471,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: [...services, ...this.defaultServices],
       basePath: this.basePath,
@@ -319,6 +485,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -336,7 +503,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -350,7 +518,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -377,6 +546,7 @@ export class EndpointFactory<
         TSession,
         L
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -397,7 +567,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -411,7 +582,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -424,6 +596,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -441,7 +614,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -455,7 +629,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -477,6 +652,7 @@ export class EndpointFactory<
         T,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -498,7 +674,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     T,
-    TName
+    TName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -512,7 +689,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       T,
-      TName
+      TName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -528,6 +706,7 @@ export class EndpointFactory<
       defaultAuthorizerName: this.defaultAuthorizerName,
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: service,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -550,7 +729,8 @@ export class EndpointFactory<
     TName,
     ExtractStorageAuditAction<T>,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -564,7 +744,8 @@ export class EndpointFactory<
       TName,
       ExtractStorageAuditAction<T>,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -582,6 +763,7 @@ export class EndpointFactory<
         TSession,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -603,7 +785,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -617,7 +800,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -630,6 +814,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: extractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -718,6 +903,9 @@ export class EndpointFactory<
       builder._actorExtractor = this.defaultActorExtractor;
     }
 
+    // Set custom security schemes
+    builder._customSecuritySchemes = this.customSecuritySchemes;
+
     return builder;
   }
 
@@ -785,6 +973,10 @@ export interface EndpointFactoryOptions<
   TAuditStorageServiceName extends string = string,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
 > {
   defaultServices?: TServices;
   basePath?: TBasePath;
@@ -798,6 +990,7 @@ export interface EndpointFactoryOptions<
   defaultAuditorStorage?: Service<TAuditStorageServiceName, TAuditStorage>;
   defaultDatabaseService?: Service<TDatabaseServiceName, TDatabase>;
   defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  customSecuritySchemes?: TSecuritySchemes;
 }
 
 export const e = new EndpointFactory();

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -443,6 +443,8 @@ export class HonoEndpoint<
                 });
               }
             },
+            // Pass rawDb so storage can reuse existing transactions
+            { db: rawDb },
           );
 
           const { output, metadata } = result;

package/src/endpoints/TestEndpointAdaptor.ts

@@ -293,6 +293,8 @@ export class TestEndpointAdaptor<
           });
         }
       },
+      // Pass rawDb so storage can reuse existing transactions
+      { db: rawDb },
     );
 
     const { output, metadata } = result;

package/src/endpoints/__tests__/EndpointFactory.authorizers.spec.ts

@@ -294,3 +294,144 @@ describe('EndpointFactory.authorizers', () => {
     expect(endpoint.tags).toEqual(['public', 'contact']);
   });
 });
+
+describe('EndpointFactory.authorizer (default)', () => {
+  it('should set default authorizer for all endpoints', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt');
+
+    const endpoint1 = factory.get('/users').handle(async () => ({ users: [] }));
+    const endpoint2 = factory
+      .post('/users')
+      .body(z.object({ name: z.string() }))
+      .handle(async () => ({ id: '1' }));
+
+    expect(endpoint1.authorizer).toEqual({ name: 'jwt' });
+    expect(endpoint2.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should allow endpoint to override factory default authorizer', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt');
+
+    const endpoint = factory
+      .get('/admin')
+      .authorizer('iam')
+      .handle(async () => ({ admin: true }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'iam' });
+  });
+
+  it('should allow endpoint to disable authorizer with none', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt');
+
+    const endpoint = factory
+      .get('/public')
+      .authorizer('none')
+      .handle(async () => ({ public: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should throw error when setting non-existent default authorizer', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    expect(() => {
+      // @ts-expect-error - testing invalid authorizer
+      factory.authorizer('invalid');
+    }).toThrow(
+      'Authorizer "invalid" not found in available authorizers: iam, jwt',
+    );
+  });
+
+  it('should preserve default authorizer when chaining factory methods', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt')
+      .route('/api/v1');
+
+    const endpoint = factory.get('/users').handle(async () => ({ users: [] }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(endpoint.route).toBe('/api/v1/users');
+  });
+
+  it('should preserve default authorizer with services', () => {
+    const dbService = {
+      serviceName: 'database' as const,
+      register: async () => ({ query: async () => [] }),
+    };
+
+    const factory = new EndpointFactory()
+      .authorizers(['jwt'] as const)
+      .authorizer('jwt')
+      .services([dbService]);
+
+    const endpoint = factory.get('/users').handle(async ({ services }) => {
+      await services.database.query();
+      return { users: [] };
+    });
+
+    expect(endpoint.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should allow factory.authorizer("none") to clear default', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt')
+      .authorizer('none');
+
+    const endpoint = factory.get('/test').handle(async () => ({ test: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should allow setting default authorizer without calling authorizers() first', () => {
+    // When no authorizers are defined, validation is skipped
+    const factory = new EndpointFactory().authorizer('custom');
+
+    const endpoint = factory.get('/test').handle(async () => ({ test: true }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'custom' });
+  });
+
+  it('should work with nested route factories', () => {
+    const rootFactory = new EndpointFactory()
+      .authorizers(['iam', 'jwt', 'api-key'] as const)
+      .authorizer('jwt');
+
+    const apiFactory = rootFactory.route('/api');
+    const adminFactory = apiFactory.route('/admin');
+
+    const endpoint = adminFactory
+      .delete('/users/:id')
+      .params(z.object({ id: z.string() }))
+      .handle(async () => ({ deleted: true }));
+
+    expect(endpoint.route).toBe('/api/admin/users/:id');
+    expect(endpoint.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should allow sub-factory to override parent default authorizer', () => {
+    const rootFactory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .authorizer('jwt');
+
+    const adminFactory = rootFactory.route('/admin').authorizer('iam');
+
+    const publicEndpoint = rootFactory
+      .get('/public')
+      .handle(async () => ({ public: true }));
+
+    const adminEndpoint = adminFactory
+      .get('/dashboard')
+      .handle(async () => ({ admin: true }));
+
+    expect(publicEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(adminEndpoint.authorizer).toEqual({ name: 'iam' });
+  });
+});