@geekmidas/constructs 0.0.22 → 0.2.0

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-DKf0juBf.mjs";
+import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-CScirkHt.mjs";
 export { HttpMethod, LowerHttpMethod, RemoveUndefined };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "0.0.22",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -68,10 +68,11 @@
     "openapi-types": "~12.1.3",
     "@geekmidas/audit": "0.0.8",
     "@geekmidas/cache": "0.0.7",
-    "@geekmidas/events": "0.0.2",
+    "@geekmidas/db": "0.1.0",
     "@geekmidas/errors": "0.0.1",
     "@geekmidas/logger": "0.0.1",
     "@geekmidas/rate-limit": "0.1.0",
+    "@geekmidas/events": "0.0.2",
     "@geekmidas/schema": "0.0.2",
     "@geekmidas/services": "0.0.1"
   },
@@ -91,7 +92,7 @@
     "@middy/core": ">=6.3.1",
     "@types/aws-lambda": ">=8.10.92",
     "hono": ">=4.8.2",
-    "@geekmidas/envkit": "~0.0.8"
+    "@geekmidas/envkit": "~0.1.0"
   },
   "scripts": {
     "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"

package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts

@@ -1,4 +1,5 @@
 import type { AuditStorage, AuditableAction } from '@geekmidas/audit';
+import { withRlsContext } from '@geekmidas/db/rls';
 import type { Logger } from '@geekmidas/logger';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { HttpMethod } from '../types';
@@ -297,6 +298,21 @@ export abstract class AmazonApiGatewayEndpoint<
     // Get pre-resolved database from middleware
     const rawDb = (event as any).db;
 
+    // Extract RLS context if configured and not bypassed
+    const rlsActive =
+      this.endpoint.rlsConfig &&
+      !this.endpoint.rlsBypass &&
+      rawDb !== undefined;
+    const rlsContext = rlsActive
+      ? await this.endpoint.rlsConfig!.extractor({
+          services: event.services as ServiceRecord<TServices>,
+          session: event.session,
+          header: event.header,
+          cookie: event.cookie,
+          logger,
+        })
+      : undefined;
+
     // Execute handler with automatic audit transaction support
     const result = await executeWithAuditTransaction(
       auditContext,
@@ -306,39 +322,54 @@ export abstract class AmazonApiGatewayEndpoint<
           auditContext?.storage?.databaseServiceName &&
           auditContext.storage.databaseServiceName ===
             this.endpoint.databaseService?.serviceName;
-        const db = sameDatabase
+        const baseDb = sameDatabase
           ? (auditor?.getTransaction?.() ?? rawDb)
           : rawDb;
 
-        const responseBuilder = new ResponseBuilder();
-        const response = await this.endpoint.handler(
-          {
-            header: event.header,
-            cookie: event.cookie,
-            logger: event.logger,
-            services: event.services,
-            session: event.session,
-            auditor,
-            db,
-            ...input,
-          } as any,
-          responseBuilder,
-        );
+        // Helper to execute handler with given db
+        const executeHandler = async (db: any) => {
+          const responseBuilder = new ResponseBuilder();
+          const response = await this.endpoint.handler(
+            {
+              header: event.header,
+              cookie: event.cookie,
+              logger: event.logger,
+              services: event.services,
+              session: event.session,
+              auditor,
+              db,
+              ...input,
+            } as any,
+            responseBuilder,
+          );
 
-        // Check if response has metadata
-        let data = response;
-        let metadata = responseBuilder.getMetadata();
+          // Check if response has metadata
+          let data = response;
+          let metadata = responseBuilder.getMetadata();
 
-        if (Endpoint.hasMetadata(response)) {
-          data = response.data;
-          metadata = response.metadata;
-        }
+          if (Endpoint.hasMetadata(response)) {
+            data = response.data;
+            metadata = response.metadata;
+          }
 
-        const output = this.endpoint.outputSchema
-          ? await this.endpoint.parseOutput(data)
-          : undefined;
+          const output = this.endpoint.outputSchema
+            ? await this.endpoint.parseOutput(data)
+            : undefined;
+
+          return { output, metadata, responseBuilder };
+        };
+
+        // If RLS is active, wrap handler with RLS context
+        if (rlsActive && rlsContext && baseDb) {
+          return withRlsContext(
+            baseDb,
+            rlsContext,
+            async (trx: any) => executeHandler(trx),
+            { prefix: this.endpoint.rlsConfig!.prefix },
+          );
+        }
 
-        return { output, metadata, responseBuilder };
+        return executeHandler(baseDb);
       },
       // Process declarative audits after handler (inside transaction)
       async (result, auditor) => {
@@ -356,6 +387,8 @@ export abstract class AmazonApiGatewayEndpoint<
           });
         }
       },
+      // Pass rawDb so storage can reuse existing transactions
+      { db: rawDb },
     );
 
     const { output, metadata } = result;

package/src/endpoints/Authorizer.ts

@@ -1,3 +1,89 @@
+/**
+ * OpenAPI 3.1 compliant security scheme definition.
+ * @see https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+ */
+export interface SecurityScheme {
+  /** The type of the security scheme */
+  type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';
+  /** A description for security scheme */
+  description?: string;
+  /** Required for apiKey. The name of the header, query or cookie parameter */
+  name?: string;
+  /** Required for apiKey. The location of the API key */
+  in?: 'query' | 'header' | 'cookie';
+  /** Required for http. The name of the HTTP Authorization scheme (e.g., 'bearer') */
+  scheme?: string;
+  /** Optional for http bearer. A hint to the format of the bearer token */
+  bearerFormat?: string;
+  /** Required for oauth2. An object containing configuration for the flow types */
+  flows?: OAuthFlows;
+  /** Required for openIdConnect. The URL to discover OAuth2 configuration */
+  openIdConnectUrl?: string;
+  /** Vendor extensions (e.g., x-amazon-apigateway-authtype) */
+  [key: `x-${string}`]: unknown;
+}
+
+/**
+ * OAuth2 flow configuration
+ */
+export interface OAuthFlows {
+  implicit?: OAuthFlow;
+  password?: OAuthFlow;
+  clientCredentials?: OAuthFlow;
+  authorizationCode?: OAuthFlow;
+}
+
+export interface OAuthFlow {
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes: Record<string, string>;
+}
+
+/**
+ * Built-in security schemes available by default.
+ * Users can use these without defining them via .securitySchemes().
+ */
+export const BUILT_IN_SECURITY_SCHEMES = {
+  jwt: {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+    description: 'JWT Bearer token authentication',
+  },
+  bearer: {
+    type: 'http',
+    scheme: 'bearer',
+    description: 'Bearer token authentication',
+  },
+  apiKey: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-API-Key',
+    description: 'API key authentication via header',
+  },
+  oauth2: {
+    type: 'oauth2',
+    flows: {},
+    description: 'OAuth 2.0 authentication',
+  },
+  oidc: {
+    type: 'openIdConnect',
+    openIdConnectUrl: '',
+    description: 'OpenID Connect authentication',
+  },
+  iam: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'Authorization',
+    description: 'AWS IAM Signature Version 4 authentication',
+    'x-amazon-apigateway-authtype': 'awsSigv4',
+  },
+} as const satisfies Record<string, SecurityScheme>;
+
+/** Names of built-in security schemes */
+export type BuiltInSecuritySchemeId = keyof typeof BUILT_IN_SECURITY_SCHEMES;
+
 /**
  * Represents an authorizer configuration for endpoints
  */
@@ -6,18 +92,25 @@ export interface Authorizer {
    * Unique identifier for the authorizer
    */
   name: string;
+  /**
+   * The OpenAPI security scheme definition for this authorizer
+   */
+  securityScheme?: SecurityScheme;
   /**
    * Type of authorizer (e.g., 'iam', 'jwt', 'custom')
+   * @deprecated Use securityScheme.type instead
    */
   type?: string;
   /**
    * Description of what this authorizer does
+   * @deprecated Use securityScheme.description instead
    */
   description?: string;
   /**
    * Additional metadata specific to the authorizer type
+   * @deprecated Use securityScheme with x-* extensions instead
    */
-  metadata?: Record<string, any>;
+  metadata?: Record<string, unknown>;
 }
 
 /**
@@ -32,3 +125,28 @@ export function createAuthorizer(
     ...options,
   };
 }
+
+/**
+ * Check if a name is a built-in security scheme
+ */
+export function isBuiltInSecurityScheme(
+  name: string,
+): name is BuiltInSecuritySchemeId {
+  return name in BUILT_IN_SECURITY_SCHEMES;
+}
+
+/**
+ * Get a security scheme by name (built-in or custom)
+ */
+export function getSecurityScheme(
+  name: string,
+  customSchemes?: Record<string, SecurityScheme>,
+): SecurityScheme | undefined {
+  if (customSchemes && name in customSchemes) {
+    return customSchemes[name];
+  }
+  if (isBuiltInSecurityScheme(name)) {
+    return BUILT_IN_SECURITY_SCHEMES[name];
+  }
+  return undefined;
+}

package/src/endpoints/Endpoint.ts

@@ -29,6 +29,7 @@ import { Function, type FunctionHandler } from '../functions';
 import type { HttpMethod, LowerHttpMethod, RemoveUndefined } from '../types';
 import type { Authorizer } from './Authorizer';
 import type { ActorExtractor, MappedAudit } from './audit';
+import type { RlsConfig } from './rls';
 
 /**
  * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,
@@ -123,6 +124,10 @@ export class Endpoint<
   public audits: MappedAudit<TAuditAction, OutSchema>[] = [];
   /** Database service for this endpoint */
   public declare databaseService?: Service<TDatabaseServiceName, TDatabase>;
+  /** RLS configuration for this endpoint */
+  public rlsConfig?: RlsConfig<TServices, TSession, TLogger>;
+  /** Whether to bypass RLS for this endpoint */
+  public rlsBypass?: boolean;
   /** The endpoint handler function */
   private endpointFn!: EndpointHandler<
     TInput,
@@ -593,6 +598,8 @@ export class Endpoint<
     actorExtractor,
     audits,
     databaseService,
+    rlsConfig,
+    rlsBypass,
   }: EndpointOptions<
     TRoute,
     TMethod,
@@ -658,6 +665,14 @@ export class Endpoint<
     if (databaseService) {
       this.databaseService = databaseService;
     }
+
+    if (rlsConfig) {
+      this.rlsConfig = rlsConfig;
+    }
+
+    if (rlsBypass) {
+      this.rlsBypass = rlsBypass;
+    }
   }
 }
 
@@ -775,6 +790,10 @@ export interface EndpointOptions<
   audits?: MappedAudit<TAuditAction, OutSchema>[];
   /** Database service for this endpoint */
   databaseService?: Service<TDatabaseServiceName, TDatabase>;
+  /** RLS configuration for this endpoint */
+  rlsConfig?: RlsConfig<TServices, TSession, TLogger>;
+  /** Whether to bypass RLS for this endpoint */
+  rlsBypass?: boolean;
 }
 
 /**

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,
@@ -21,6 +22,8 @@ import type {
   SuccessStatus,
 } from './Endpoint';
 import type { ActorExtractor, MappedAudit } from './audit';
+import type { RlsBypass, RlsConfig } from './rls';
+import { RLS_BYPASS } from './rls';
 
 export class EndpointBuilder<
   TRoute extends string,
@@ -66,6 +69,9 @@ export class EndpointBuilder<
   _authorizerName?: TAuthorizers[number];
   _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  _customSecuritySchemes: Record<string, SecurityScheme> = {};
+  _rlsConfig?: RlsConfig<TServices, TSession, TLogger>;
+  _rlsBypass?: boolean;
 
   constructor(
     readonly route: TRoute,
@@ -581,6 +587,57 @@ export class EndpointBuilder<
     >;
   }
 
+  /**
+   * Configure RLS (Row-Level Security) context for this endpoint.
+   * Pass `false` or `RLS_BYPASS` to explicitly bypass RLS for this endpoint.
+   *
+   * @example
+   * ```typescript
+   * // Custom RLS config for this endpoint
+   * .rls({
+   *   extractor: ({ session }) => ({
+   *     user_id: session.userId,
+   *     tenant_id: session.tenantId,
+   *   }),
+   *   prefix: 'app',
+   * })
+   *
+   * // Bypass RLS (for admin endpoints)
+   * .rls(false)
+   * ```
+   */
+  rls(
+    config: RlsConfig<TServices, TSession, TLogger> | false | RlsBypass,
+  ): this {
+    if (config === false || config === RLS_BYPASS) {
+      this._rlsBypass = true;
+      this._rlsConfig = undefined;
+    } else {
+      this._rlsConfig = config;
+      this._rlsBypass = false;
+    }
+    return this;
+  }
+
+  /**
+   * Explicitly bypass RLS for this endpoint.
+   * Useful for admin operations that need unrestricted database access.
+   *
+   * @example
+   * ```typescript
+   * .rlsBypass()
+   * .handle(async ({ db }) => {
+   *   // Full access, no RLS filtering
+   *   return db.selectFrom('orders').selectAll().execute();
+   * })
+   * ```
+   */
+  rlsBypass(): this {
+    this._rlsBypass = true;
+    this._rlsConfig = undefined;
+    return this;
+  }
+
   // EndpointBuilder doesn't have a generic input method - it uses body, query, params instead
   input(_schema: any): any {
     throw new Error(
@@ -617,11 +674,26 @@ export class EndpointBuilder<
   > {
     // Find authorizer metadata if name is set
     // If the authorizer name is set but not in availableAuthorizers, create a simple authorizer object
-    const authorizer = this._authorizerName
-      ? (this._availableAuthorizers.find(
-          (a) => a.name === this._authorizerName,
-        ) ?? { name: this._authorizerName })
-      : undefined;
+    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,
@@ -646,6 +718,8 @@ export class EndpointBuilder<
       actorExtractor: this._actorExtractor,
       audits: this._audits,
       databaseService: this._databaseService,
+      rlsConfig: this._rlsConfig,
+      rlsBypass: this._rlsBypass,
     });
   }
 }