serverless-event-orchestrator 2.0.1 → 2.3.0

package/src/index.ts

@@ -1,127 +1,128 @@
-/**
- * serverless-event-orchestrator
- * 
- * A lightweight, type-safe event dispatcher and middleware orchestrator for AWS Lambda.
- * Designed for hexagonal architectures with support for segmented routing,
- * Cognito User Pool validation, and built-in infrastructure middlewares.
- */
-
-// Core dispatcher
-export { dispatchEvent, detectEventType, createOrchestrator } from './dispatcher.js';
-
-// Types
-export {
-  EventType,
-  RouteSegment,
-} from './types/event-type.enum.js';
-
-export {
-  HttpMethod,
-  MiddlewareFn,
-  RouteConfig,
-  CorsConfig,
-  RateLimitConfig,
-  HttpRouter,
-  SegmentedHttpRouter,
-  SegmentConfig,
-  AdvancedSegmentedRouter,
-  EventBridgeRoutes,
-  LambdaRoutes,
-  SqsRoutes,
-  DispatchRoutes,
-  IdentityContext,
-  RouteMatch,
-  NormalizedEvent,
-  OrchestratorConfig,
-  JwtVerificationPoolConfig,
-} from './types/routes.js';
-
-// HTTP utilities
-export {
-  HttpStatus,
-  StandardResponse,
-  HttpResponse,
-  DefaultResponseCode,
-  createStandardResponse,
-  successResponse,
-  createdResponse,
-  badRequestResponse,
-  unauthorizedResponse,
-  forbiddenResponse,
-  notFoundResponse,
-  conflictResponse,
-  validationErrorResponse,
-  internalErrorResponse,
-  customErrorResponse,
-} from './http/response.js';
-
-export {
-  parseJsonBody,
-  parseQueryParams,
-  withJsonBodyParser,
-} from './http/body-parser.js';
-
-export {
-  isPreflightRequest,
-  createPreflightResponse,
-  applyCorsHeaders,
-  withCors,
-} from './http/cors.js';
-
-// Identity utilities
-export {
-  extractIdentity,
-  extractUserPoolId,
-  validateIssuer,
-  hasAnyGroup,
-  hasAllGroups,
-} from './identity/extractor.js';
-
-export type { ExtractIdentityOptions } from './identity/extractor.js';
-
-export { verifyJwt } from './identity/jwt-verifier.js';
-
-// Path utilities
-export {
-  matchPath,
-  patternToRegex,
-  hasPathParameters,
-  normalizePath,
-} from './utils/path-matcher.js';
-
-// Header utilities
-export {
-  normalizeHeaders,
-  getHeader,
-  getCorsHeaders,
-} from './utils/headers.js';
-
-// Tenant context
-export { TenantContext } from './tenant/TenantContext.js';
-
-export type {
-  TenantInfo,
-  TenantType,
-  Plan,
-  TenantFeatures,
-  TenantClaims,
-} from './tenant/types.js';
-
-export {
-  isTenantType,
-  isPlan,
-  TENANT_HEADERS,
-} from './tenant/types.js';
-
-export {
-  tenantInfoFromClaims,
-  tenantInfoFromHeaders,
-  tenantInfoToHeaders,
-} from './tenant/helpers.js';
-
-// Tenant middleware
-export {
-  initTenantContext,
-  tenantGuard,
-  crmGuard,
-} from './middleware/index.js';
+/**
+ * serverless-event-orchestrator
+ * 
+ * A lightweight, type-safe event dispatcher and middleware orchestrator for AWS Lambda.
+ * Designed for hexagonal architectures with support for segmented routing,
+ * Cognito User Pool validation, and built-in infrastructure middlewares.
+ */
+
+// Core dispatcher
+export { dispatchEvent, detectEventType, createOrchestrator } from './dispatcher.js';
+
+// Types
+export {
+  EventType,
+  RouteSegment,
+} from './types/event-type.enum.js';
+
+export {
+  HttpMethod,
+  MiddlewareFn,
+  RouteConfig,
+  CorsConfig,
+  RateLimitConfig,
+  HttpRouter,
+  SegmentedHttpRouter,
+  SegmentConfig,
+  AdvancedSegmentedRouter,
+  EventBridgeRoutes,
+  LambdaRoutes,
+  SqsRoutes,
+  ScheduledRoutes,
+  DispatchRoutes,
+  IdentityContext,
+  RouteMatch,
+  NormalizedEvent,
+  OrchestratorConfig,
+  JwtVerificationPoolConfig,
+} from './types/routes.js';
+
+// HTTP utilities
+export {
+  HttpStatus,
+  StandardResponse,
+  HttpResponse,
+  DefaultResponseCode,
+  createStandardResponse,
+  successResponse,
+  createdResponse,
+  badRequestResponse,
+  unauthorizedResponse,
+  forbiddenResponse,
+  notFoundResponse,
+  conflictResponse,
+  validationErrorResponse,
+  internalErrorResponse,
+  customErrorResponse,
+} from './http/response.js';
+
+export {
+  parseJsonBody,
+  parseQueryParams,
+  withJsonBodyParser,
+} from './http/body-parser.js';
+
+export {
+  isPreflightRequest,
+  createPreflightResponse,
+  applyCorsHeaders,
+  withCors,
+} from './http/cors.js';
+
+// Identity utilities
+export {
+  extractIdentity,
+  extractUserPoolId,
+  validateIssuer,
+  hasAnyGroup,
+  hasAllGroups,
+} from './identity/extractor.js';
+
+export type { ExtractIdentityOptions } from './identity/extractor.js';
+
+export { verifyJwt } from './identity/jwt-verifier.js';
+
+// Path utilities
+export {
+  matchPath,
+  patternToRegex,
+  hasPathParameters,
+  normalizePath,
+} from './utils/path-matcher.js';
+
+// Header utilities
+export {
+  normalizeHeaders,
+  getHeader,
+  getCorsHeaders,
+} from './utils/headers.js';
+
+// Tenant context
+export { TenantContext } from './tenant/TenantContext.js';
+
+export type {
+  TenantInfo,
+  TenantType,
+  Plan,
+  TenantFeatures,
+  TenantClaims,
+} from './tenant/types.js';
+
+export {
+  isTenantType,
+  isPlan,
+  TENANT_HEADERS,
+} from './tenant/types.js';
+
+export {
+  tenantInfoFromClaims,
+  tenantInfoFromHeaders,
+  tenantInfoToHeaders,
+} from './tenant/helpers.js';
+
+// Tenant middleware
+export {
+  initTenantContext,
+  tenantGuard,
+  crmGuard,
+} from './middleware/index.js';

package/src/middleware/crm-guard.ts

@@ -1,51 +1,51 @@
-import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
-import { forbiddenResponse } from '../http/response.js';
-import { hasAnyGroup } from '../identity/extractor.js';
-
-/**
- * Roles that bypass CRM plan check.
- */
-const CRM_BYPASS_ROLES = ['PLATFORM_ADMIN'];
-
-/**
- * Middleware that enforces CRM access based on the tenant's subscription plan.
- *
- * Checks event.context.tenantInfo.hasCRM (set by initTenantContext from JWT claims).
- * If the tenant doesn't have CRM access, returns 403 with upgrade message.
- *
- * IMPORTANT: This middleware MUST run AFTER tenantGuard (which ensures tenantInfo exists).
- *
- * Usage: Add as route-level or segment middleware for CRM-only endpoints.
- *
- * ```typescript
- * private: {
- *   middleware: [tenantGuard],  // ← runs first
- *   routes: {
- *     get: {
- *       '/crm/dashboard': { handler: getCRMDashboard, middleware: [crmGuard] },  // ← runs second
- *       '/crm/leads': { handler: getLeads, middleware: [crmGuard] },
- *     }
- *   }
- * }
- * ```
- */
-export const crmGuard: MiddlewareFn = async (
-  event: NormalizedEvent
-): Promise<NormalizedEvent> => {
-  // PLATFORM_ADMIN bypasses CRM check
-  if (hasAnyGroup(event.context.identity, CRM_BYPASS_ROLES)) {
-    return event;
-  }
-
-  const tenantInfo = event.context.tenantInfo;
-
-  // Check hasCRM from tenantInfo (set from JWT claim custom:hasCRM)
-  if (!tenantInfo?.hasCRM) {
-    throw forbiddenResponse(
-      'CRM access requires a paid plan. Please upgrade your subscription.',
-      'CRM_ACCESS_DENIED' as any
-    );
-  }
-
-  return event;
-};
+import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
+import { forbiddenResponse } from '../http/response.js';
+import { hasAnyGroup } from '../identity/extractor.js';
+
+/**
+ * Roles that bypass CRM plan check.
+ */
+const CRM_BYPASS_ROLES = ['PLATFORM_ADMIN'];
+
+/**
+ * Middleware that enforces CRM access based on the tenant's subscription plan.
+ *
+ * Checks event.context.tenantInfo.hasCRM (set by initTenantContext from JWT claims).
+ * If the tenant doesn't have CRM access, returns 403 with upgrade message.
+ *
+ * IMPORTANT: This middleware MUST run AFTER tenantGuard (which ensures tenantInfo exists).
+ *
+ * Usage: Add as route-level or segment middleware for CRM-only endpoints.
+ *
+ * ```typescript
+ * private: {
+ *   middleware: [tenantGuard],  // ← runs first
+ *   routes: {
+ *     get: {
+ *       '/crm/dashboard': { handler: getCRMDashboard, middleware: [crmGuard] },  // ← runs second
+ *       '/crm/leads': { handler: getLeads, middleware: [crmGuard] },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export const crmGuard: MiddlewareFn = async (
+  event: NormalizedEvent
+): Promise<NormalizedEvent> => {
+  // PLATFORM_ADMIN bypasses CRM check
+  if (hasAnyGroup(event.context.identity, CRM_BYPASS_ROLES)) {
+    return event;
+  }
+
+  const tenantInfo = event.context.tenantInfo;
+
+  // Check hasCRM from tenantInfo (set from JWT claim custom:hasCRM)
+  if (!tenantInfo?.hasCRM) {
+    throw forbiddenResponse(
+      'CRM access requires a paid plan. Please upgrade your subscription.',
+      'CRM_ACCESS_DENIED' as any
+    );
+  }
+
+  return event;
+};

package/src/middleware/index.ts

@@ -1,3 +1,3 @@
-export { initTenantContext } from './init-tenant-context.js';
-export { tenantGuard } from './tenant-guard.js';
-export { crmGuard } from './crm-guard.js';
+export { initTenantContext } from './init-tenant-context.js';
+export { tenantGuard } from './tenant-guard.js';
+export { crmGuard } from './crm-guard.js';

package/src/middleware/init-tenant-context.ts

@@ -1,59 +1,59 @@
-import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
-import {
-  TenantContext,
-  tenantInfoFromClaims,
-  tenantInfoFromHeaders,
-  type TenantInfo,
-} from '../tenant/index.js';
-
-/**
- * Middleware that initializes the TenantContext from JWT claims or headers.
- *
- * Execution order: globalMiddleware (runs on ALL routes, before segment middleware).
- *
- * Resolution strategy:
- * 1. Private/Backoffice segments → extract from identity.claims (JWT)
- * 2. Internal segment → extract from headers (X-Tenant-Id, Lambda-to-Lambda)
- * 3. Public segment → try claims first (authenticated public), then headers, then skip
- *
- * If tenant info is found:
- *   - Sets TenantContext via AsyncLocalStorage (for repositories)
- *   - Adds tenantInfo to event.context (for handlers and logger)
- *
- * If tenant info is NOT found:
- *   - Does NOT throw (public routes are allowed without tenant)
- *   - tenantGuard (segment middleware) will enforce tenant requirement where needed
- */
-export const initTenantContext: MiddlewareFn = async (
-  event: NormalizedEvent
-): Promise<NormalizedEvent> => {
-  let tenantInfo: TenantInfo | undefined;
-
-  // Strategy 1: From JWT claims (private, backoffice, or authenticated public)
-  if (event.context.identity?.claims) {
-    tenantInfo = tenantInfoFromClaims(event.context.identity.claims);
-  }
-
-  // Strategy 2: From headers (internal Lambda-to-Lambda, or fallback)
-  if (!tenantInfo && event.payload.headers) {
-    tenantInfo = tenantInfoFromHeaders(event.payload.headers);
-  }
-
-  // If we found tenant info, set it everywhere
-  if (tenantInfo) {
-    // 1. Set AsyncLocalStorage (for TenantAwareDynamoRepository and ApiInvoker)
-    TenantContext.set(tenantInfo);
-
-    // 2. Enrich event.context (for handlers, logger, and downstream middleware)
-    return {
-      ...event,
-      context: {
-        ...event.context,
-        tenantInfo,
-      },
-    };
-  }
-
-  // No tenant info found — this is normal for public routes
-  return event;
-};
+import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
+import {
+  TenantContext,
+  tenantInfoFromClaims,
+  tenantInfoFromHeaders,
+  type TenantInfo,
+} from '../tenant/index.js';
+
+/**
+ * Middleware that initializes the TenantContext from JWT claims or headers.
+ *
+ * Execution order: globalMiddleware (runs on ALL routes, before segment middleware).
+ *
+ * Resolution strategy:
+ * 1. Private/Backoffice segments → extract from identity.claims (JWT)
+ * 2. Internal segment → extract from headers (X-Tenant-Id, Lambda-to-Lambda)
+ * 3. Public segment → try claims first (authenticated public), then headers, then skip
+ *
+ * If tenant info is found:
+ *   - Sets TenantContext via AsyncLocalStorage (for repositories)
+ *   - Adds tenantInfo to event.context (for handlers and logger)
+ *
+ * If tenant info is NOT found:
+ *   - Does NOT throw (public routes are allowed without tenant)
+ *   - tenantGuard (segment middleware) will enforce tenant requirement where needed
+ */
+export const initTenantContext: MiddlewareFn = async (
+  event: NormalizedEvent
+): Promise<NormalizedEvent> => {
+  let tenantInfo: TenantInfo | undefined;
+
+  // Strategy 1: From JWT claims (private, backoffice, or authenticated public)
+  if (event.context.identity?.claims) {
+    tenantInfo = tenantInfoFromClaims(event.context.identity.claims);
+  }
+
+  // Strategy 2: From headers (internal Lambda-to-Lambda, or fallback)
+  if (!tenantInfo && event.payload.headers) {
+    tenantInfo = tenantInfoFromHeaders(event.payload.headers);
+  }
+
+  // If we found tenant info, set it everywhere
+  if (tenantInfo) {
+    // 1. Set AsyncLocalStorage (for TenantAwareDynamoRepository and ApiInvoker)
+    TenantContext.set(tenantInfo);
+
+    // 2. Enrich event.context (for handlers, logger, and downstream middleware)
+    return {
+      ...event,
+      context: {
+        ...event.context,
+        tenantInfo,
+      },
+    };
+  }
+
+  // No tenant info found — this is normal for public routes
+  return event;
+};

package/src/middleware/tenant-guard.ts

@@ -1,54 +1,54 @@
-import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
-import { forbiddenResponse } from '../http/response.js';
-import { hasAnyGroup } from '../identity/extractor.js';
-
-/**
- * Roles that can operate cross-tenant (bypass tenant check).
- * PLATFORM_ADMIN = MLHolding employees in the Backoffice pool.
- */
-const CROSS_TENANT_ROLES = ['PLATFORM_ADMIN'];
-
-/**
- * Middleware that enforces tenant context on protected routes.
- * FAIL-CLOSED: If no tenant context exists and user is not PLATFORM_ADMIN, request is denied.
- *
- * Usage: Add as segment middleware for private and backoffice segments.
- *
- * ```typescript
- * const routes: AdvancedSegmentedRouter = {
- *   public: { routes: { ... } },                    // ← NO tenantGuard
- *   private: { middleware: [tenantGuard], routes: { ... } },   // ← YES
- *   backoffice: { middleware: [tenantGuard], routes: { ... } }, // ← YES
- *   internal: { routes: { ... } },                  // ← NO (uses headers, initTenantContext handles it)
- * };
- * ```
- *
- * Throws forbiddenResponse (403) if:
- *   - No tenantInfo in context AND user is not PLATFORM_ADMIN
- *   - tenantInfo exists but tenantId is empty or whitespace-only
- *
- * Allows through if:
- *   - tenantInfo exists with valid non-empty tenantId
- *   - User is PLATFORM_ADMIN (cross-tenant access)
- */
-export const tenantGuard: MiddlewareFn = async (
-  event: NormalizedEvent
-): Promise<NormalizedEvent> => {
-  const tenantInfo = event.context.tenantInfo;
-  const identity = event.context.identity;
-
-  // PLATFORM_ADMIN can operate without tenant context (cross-tenant)
-  if (hasAnyGroup(identity, CROSS_TENANT_ROLES)) {
-    return event;
-  }
-
-  // Fail-closed: validate tenantInfo exists AND tenantId is not empty
-  if (!tenantInfo?.tenantId || tenantInfo.tenantId.trim() === '') {
-    throw forbiddenResponse(
-      'Tenant context required. Ensure you are authenticated with a valid tenant.',
-      'TENANT_CONTEXT_MISSING' as any
-    );
-  }
-
-  return event;
-};
+import type { NormalizedEvent, MiddlewareFn } from '../types/routes.js';
+import { forbiddenResponse } from '../http/response.js';
+import { hasAnyGroup } from '../identity/extractor.js';
+
+/**
+ * Roles that can operate cross-tenant (bypass tenant check).
+ * PLATFORM_ADMIN = MLHolding employees in the Backoffice pool.
+ */
+const CROSS_TENANT_ROLES = ['PLATFORM_ADMIN'];
+
+/**
+ * Middleware that enforces tenant context on protected routes.
+ * FAIL-CLOSED: If no tenant context exists and user is not PLATFORM_ADMIN, request is denied.
+ *
+ * Usage: Add as segment middleware for private and backoffice segments.
+ *
+ * ```typescript
+ * const routes: AdvancedSegmentedRouter = {
+ *   public: { routes: { ... } },                    // ← NO tenantGuard
+ *   private: { middleware: [tenantGuard], routes: { ... } },   // ← YES
+ *   backoffice: { middleware: [tenantGuard], routes: { ... } }, // ← YES
+ *   internal: { routes: { ... } },                  // ← NO (uses headers, initTenantContext handles it)
+ * };
+ * ```
+ *
+ * Throws forbiddenResponse (403) if:
+ *   - No tenantInfo in context AND user is not PLATFORM_ADMIN
+ *   - tenantInfo exists but tenantId is empty or whitespace-only
+ *
+ * Allows through if:
+ *   - tenantInfo exists with valid non-empty tenantId
+ *   - User is PLATFORM_ADMIN (cross-tenant access)
+ */
+export const tenantGuard: MiddlewareFn = async (
+  event: NormalizedEvent
+): Promise<NormalizedEvent> => {
+  const tenantInfo = event.context.tenantInfo;
+  const identity = event.context.identity;
+
+  // PLATFORM_ADMIN can operate without tenant context (cross-tenant)
+  if (hasAnyGroup(identity, CROSS_TENANT_ROLES)) {
+    return event;
+  }
+
+  // Fail-closed: validate tenantInfo exists AND tenantId is not empty
+  if (!tenantInfo?.tenantId || tenantInfo.tenantId.trim() === '') {
+    throw forbiddenResponse(
+      'Tenant context required. Ensure you are authenticated with a valid tenant.',
+      'TENANT_CONTEXT_MISSING' as any
+    );
+  }
+
+  return event;
+};