serverless-event-orchestrator 1.2.6 → 1.3.0

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

@@ -0,0 +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;
+};

package/src/middleware/tenant-guard.ts

@@ -0,0 +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;
+};

package/src/tenant/TenantContext.ts

@@ -0,0 +1,115 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { TenantInfo } from './types.js';
+
+/**
+ * TenantContext provides thread-safe (async-safe) access to the current tenant context.
+ *
+ * Uses Node.js AsyncLocalStorage to maintain TenantInfo throughout the
+ * execution of a request without needing to pass it as a parameter.
+ *
+ * Initialization:
+ *   - In HTTP requests: the `initTenantContext` middleware extracts the tenant
+ *     from JWT claims or headers and calls `TenantContext.set()`.
+ *   - In EventBridge/SQS: the handler extracts tenantId from event.detail and calls `TenantContext.run()`.
+ *
+ * Consumption:
+ *   - TenantAwareDynamoRepository: `TenantContext.current().tenantId`
+ *   - ApiInvoker: `TenantContext.currentOptional()` to propagate headers
+ *   - Use cases: `TenantContext.current()` when they need the tenant explicitly
+ *
+ * IMPORTANT:
+ *   - `current()` is FAIL-CLOSED: throws error if no context (prevents data leaks).
+ *   - `currentOptional()` returns undefined without error (for code that works with/without tenant).
+ *   - `run()` is for scenarios where an explicit scope is needed (EventBridge handlers).
+ *   - `set()` is for the orchestrator middleware that operates in the same async scope.
+ */
+export class TenantContext {
+  private static storage = new AsyncLocalStorage<TenantInfo>();
+
+  /**
+   * Executes a callback within a tenant context.
+   * Useful for EventBridge/SQS handlers where there's no orchestrator middleware.
+   *
+   * @example
+   * ```typescript
+   * await TenantContext.run(tenantInfo, async () => {
+   *   const props = await propertiesRepo.findByStatus('PUBLISHED');
+   *   // propertiesRepo automatically filters by tenantInfo.tenantId
+   * });
+   * ```
+   */
+  static run<T>(tenant: TenantInfo, callback: () => T): T {
+    return this.storage.run(tenant, callback);
+  }
+
+  /**
+   * Sets the tenant context in the current AsyncLocalStorage store.
+   * ONLY should be called by the initTenantContext middleware.
+   *
+   * NOTE: Requires an active store (created by AsyncLocalStorage.run()
+   * or by the Lambda runtime). If called outside an async context,
+   * the value is lost. For those cases, use `run()`.
+   *
+   * Internally uses enterWith() which replaces the current store.
+   */
+  static set(tenant: TenantInfo): void {
+    this.storage.enterWith(tenant);
+  }
+
+  /**
+   * Gets the current TenantInfo. FAIL-CLOSED: throws error if not initialized.
+   * Use in code that REQUIRES a tenant (repositories, guards).
+   *
+   * @throws Error if TenantContext is not initialized
+   *
+   * @example
+   * ```typescript
+   * const { tenantId } = TenantContext.current();
+   * // Safe: if we get here, tenantId exists
+   * ```
+   */
+  static current(): TenantInfo {
+    const tenant = this.storage.getStore();
+    if (!tenant) {
+      throw new Error(
+        'TenantContext not initialized. Ensure initTenantContext middleware is configured ' +
+        'in globalMiddleware, or use TenantContext.run() for non-HTTP triggers.'
+      );
+    }
+    return tenant;
+  }
+
+  /**
+   * Gets the current TenantInfo or undefined if not initialized.
+   * Use in code that works with or without tenant (ApiInvoker, loggers, public routes).
+   *
+   * @example
+   * ```typescript
+   * const tenant = TenantContext.currentOptional();
+   * if (tenant) {
+   *   headers['x-tenant-id'] = tenant.tenantId;
+   * }
+   * ```
+   */
+  static currentOptional(): TenantInfo | undefined {
+    return this.storage.getStore();
+  }
+
+  /**
+   * Checks if there's an active tenant context.
+   * Useful for conditionals without getting the full object.
+   */
+  static isActive(): boolean {
+    return this.storage.getStore() !== undefined;
+  }
+
+  /**
+   * Clears the current context. Only for testing.
+   * DO NOT use in production — the context is automatically cleaned when exiting the scope.
+   * @internal
+   */
+  static _reset(): void {
+    this.storage.disable();
+    (this as any).storage = new AsyncLocalStorage<TenantInfo>();
+  }
+}

package/src/tenant/helpers.ts

@@ -0,0 +1,95 @@
+import type { TenantInfo } from './types.js';
+import { isTenantType, isPlan, TENANT_HEADERS } from './types.js';
+
+/**
+ * Builds a TenantInfo from TenantClaims in the JWT.
+ * Used by initTenantContext middleware in serverless-event-orchestrator.
+ *
+ * @param claims - Partial claims object from JWT (event.context.identity.claims)
+ * @returns TenantInfo if all required fields are present, undefined otherwise
+ */
+export function tenantInfoFromClaims(claims: Record<string, any>): TenantInfo | undefined {
+  const tenantId = claims['custom:tenantId'];
+  const tenantType = claims['custom:tenantType'];
+  const userId = claims['custom:userId'] || claims['sub'];
+  const countryCode = claims['custom:countryCode'];
+
+  if (!tenantId || !tenantType || !userId || !countryCode) {
+    return undefined;
+  }
+
+  if (!isTenantType(tenantType)) {
+    return undefined;
+  }
+
+  return {
+    tenantId,
+    tenantType,
+    userId,
+    personProfileId: claims['custom:personProfileId'],
+    orgProfileId: claims['custom:orgProfileId'],
+    countryCode,
+    plan: isPlan(claims['custom:plan']) ? claims['custom:plan'] : undefined,
+    hasCRM: claims['custom:hasCRM'] === 'true',
+  };
+}
+
+/**
+ * Builds a TenantInfo from headers (Lambda-to-Lambda).
+ * Used by initTenantContext middleware for internal routes.
+ *
+ * @param headers - Headers object (may have original or lowercase keys)
+ * @returns TenantInfo if all required fields are present, undefined otherwise
+ */
+export function tenantInfoFromHeaders(
+  headers: Record<string, string | undefined>
+): TenantInfo | undefined {
+  const get = (key: string) => headers[key] || headers[key.toLowerCase()];
+
+  const tenantId = get(TENANT_HEADERS.TENANT_ID);
+  const tenantType = get(TENANT_HEADERS.TENANT_TYPE);
+  const userId = get(TENANT_HEADERS.USER_ID);
+  const countryCode = get(TENANT_HEADERS.COUNTRY_CODE);
+
+  if (!tenantId || !tenantType || !userId || !countryCode) {
+    return undefined;
+  }
+
+  if (!isTenantType(tenantType)) {
+    return undefined;
+  }
+
+  return {
+    tenantId,
+    tenantType: tenantType as 'ORG' | 'PERSON',
+    userId,
+    personProfileId: get(TENANT_HEADERS.PERSON_PROFILE_ID),
+    orgProfileId: get(TENANT_HEADERS.ORG_PROFILE_ID),
+    countryCode,
+  };
+}
+
+/**
+ * Converts TenantInfo to headers for Lambda-to-Lambda propagation.
+ * Used by ApiInvoker to propagate the context.
+ *
+ * @param tenant - TenantInfo to serialize
+ * @returns Headers object with X-Tenant-* headers
+ */
+export function tenantInfoToHeaders(tenant: TenantInfo): Record<string, string> {
+  const headers: Record<string, string> = {
+    [TENANT_HEADERS.TENANT_ID]: tenant.tenantId,
+    [TENANT_HEADERS.TENANT_TYPE]: tenant.tenantType,
+    [TENANT_HEADERS.USER_ID]: tenant.userId,
+    [TENANT_HEADERS.COUNTRY_CODE]: tenant.countryCode,
+  };
+
+  if (tenant.personProfileId) {
+    headers[TENANT_HEADERS.PERSON_PROFILE_ID] = tenant.personProfileId;
+  }
+  if (tenant.orgProfileId) {
+    headers[TENANT_HEADERS.ORG_PROFILE_ID] = tenant.orgProfileId;
+  }
+
+  return headers;
+}

package/src/tenant/index.ts

@@ -0,0 +1,21 @@
+export { TenantContext } from './TenantContext.js';
+
+export type {
+  TenantInfo,
+  TenantType,
+  Plan,
+  TenantFeatures,
+  TenantClaims,
+} from './types.js';
+
+export {
+  isTenantType,
+  isPlan,
+  TENANT_HEADERS,
+} from './types.js';
+
+export {
+  tenantInfoFromClaims,
+  tenantInfoFromHeaders,
+  tenantInfoToHeaders,
+} from './helpers.js';

package/src/tenant/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Tenant types for the multi-tenant system.
+ * - ORG: Organization/Agency (tenantId = orgProfileId)
+ * - PERSON: Independent agent (tenantId = personProfileId)
+ */
+export type TenantType = 'ORG' | 'PERSON';
+
+/**
+ * SaaS subscription plans.
+ * Determine the features available for a tenant.
+ * Stored in the Tenants table and injected into JWT via Pre Token Generation.
+ */
+export type Plan = 'FREE' | 'BASIC' | 'PRO' | 'ENTERPRISE';
+
+/**
+ * Features enabled per plan.
+ * Stored in the Tenants table and queried from JWT claim or table directly.
+ */
+export interface TenantFeatures {
+  maxProperties: number;
+  hasWhiteLabelWebsite: boolean;
+  hasCRMAccess: boolean;
+  hasAdvancedAnalytics: boolean;
+  maxAgents: number;
+}
+
+/**
+ * Tenant information that travels in the context of each request.
+ * Propagated via AsyncLocalStorage and available throughout the async chain.
+ *
+ * Filled from JWT claims (private/backoffice routes) or from headers
+ * X-Tenant-Id (internal routes, Lambda-to-Lambda).
+ */
+export interface TenantInfo {
+  /** Tenant ID: orgProfileId (ORG) or personProfileId (PERSON) */
+  tenantId: string;
+
+  /** Tenant type */
+  tenantType: TenantType;
+
+  /** Authenticated user ID (Cognito sub or custom:userId) */
+  userId: string;
+
+  /** PersonProfileId of the user (always present, it's their personal profile) */
+  personProfileId?: string;
+
+  /** OrgProfileId if belongs to an organization (only for TenantType = ORG) */
+  orgProfileId?: string;
+
+  /** User's country code (ISO 3166-1 alpha-2, e.g., 'CO', 'MX', 'US') */
+  countryCode: string;
+
+  /** Tenant's plan (optional, filled if present in JWT) */
+  plan?: Plan;
+
+  /** Whether the tenant has CRM access (shortcut for features.hasCRMAccess) */
+  hasCRM?: boolean;
+}
+
+/**
+ * Custom claims injected into the Cognito JWT via Pre Token Generation.
+ * These claims are available in event.context.identity.claims
+ * after the orchestrator extracts the identity.
+ */
+export interface TenantClaims {
+  'custom:tenantId': string;
+  'custom:tenantType': TenantType;
+  'custom:userId': string;
+  'custom:personProfileId': string;
+  'custom:orgProfileId'?: string;
+  'custom:countryCode': string;
+  'custom:plan'?: Plan;
+  'custom:hasCRM'?: string;       // 'true' | 'false' (Cognito only accepts strings)
+  'custom:hasWhiteLabel'?: string; // 'true' | 'false'
+}
+
+/**
+ * Headers used to propagate tenant in Lambda-to-Lambda calls.
+ */
+export const TENANT_HEADERS = {
+  TENANT_ID: 'x-tenant-id',
+  TENANT_TYPE: 'x-tenant-type',
+  USER_ID: 'x-user-id',
+  COUNTRY_CODE: 'x-country-code',
+  PERSON_PROFILE_ID: 'x-person-profile-id',
+  ORG_PROFILE_ID: 'x-org-profile-id',
+} as const;
+
+/**
+ * Type guard: checks if a value is a valid TenantType.
+ */
+export function isTenantType(value: unknown): value is TenantType {
+  return value === 'ORG' || value === 'PERSON';
+}
+
+/**
+ * Type guard: checks if a value is a valid Plan.
+ */
+export function isPlan(value: unknown): value is Plan {
+  return value === 'FREE' || value === 'BASIC' || value === 'PRO' || value === 'ENTERPRISE';
+}

package/src/types/routes.ts

@@ -1,4 +1,5 @@
 import { RouteSegment } from './event-type.enum.js';
+import type { TenantInfo } from '../tenant/types.js';
 
 /**
  * HTTP methods supported by the router
@@ -146,6 +147,7 @@ export interface NormalizedEvent {
     segment: RouteSegment;
     identity?: IdentityContext;
     requestId?: string;
+    tenantInfo?: TenantInfo;
   };
 }
 

package/src/utils/path-matcher.ts

@@ -10,18 +10,22 @@
  */
 export function patternToRegex(pattern: string): { regex: RegExp; paramNames: string[] } {
   const paramNames: string[] = [];
-  
+
+  // First, handle :paramName format (Express style) BEFORE escaping
+  // This converts :id to {id} for uniform processing
+  let normalizedPattern = pattern.replace(/:(\w+)/g, '{$1}');
+
   // Escape special regex characters except for our parameter syntax
-  let regexPattern = pattern
+  let regexPattern = normalizedPattern
     .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
     .replace(/\\\{(\w+)\\\}/g, (_, paramName) => {
       paramNames.push(paramName);
       return '([^/]+)';
     });
-  
+
   // Ensure exact match
   regexPattern = `^${regexPattern}$`;
-  
+
   return {
     regex: new RegExp(regexPattern),
     paramNames,
@@ -56,7 +60,8 @@ export function matchPath(pattern: string, path: string): Record<string, string>
  * @returns True if pattern has parameters
  */
 export function hasPathParameters(pattern: string): boolean {
-  return /\{[\w]+\}/.test(pattern);
+  // Support both {id} and :id formats
+  return /\{[\w]+\}/.test(pattern) || /:[\w]+/.test(pattern);
 }
 
 /**

package/tests/middleware/crm-guard.test.ts

@@ -0,0 +1,69 @@
+import { crmGuard } from '../../src/middleware/crm-guard';
+import { RouteSegment } from '../../src/types/event-type.enum';
+import type { NormalizedEvent } from '../../src/types/routes';
+import type { TenantInfo } from '../../src/tenant';
+
+function createEvent(options: {
+  hasCRM?: boolean;
+  groups?: string[];
+}): NormalizedEvent {
+  const tenantInfo: TenantInfo = {
+    tenantId: 'org_abc',
+    tenantType: 'ORG',
+    userId: 'user-1',
+    countryCode: 'CO',
+    hasCRM: options.hasCRM,
+  };
+
+  return {
+    eventRaw: {},
+    eventType: 'apigateway',
+    payload: { headers: {} },
+    params: {},
+    context: {
+      segment: RouteSegment.Private,
+      identity: {
+        userId: 'user-1',
+        groups: options.groups ?? [],
+        claims: {},
+      },
+      requestId: 'req-test',
+      tenantInfo,
+    },
+  };
+}
+
+describe('crmGuard', () => {
+  it('allows access when hasCRM is true', async () => {
+    const event = createEvent({ hasCRM: true });
+    const result = await crmGuard(event);
+    expect(result).toBeDefined();
+  });
+
+  it('throws 403 when hasCRM is false', async () => {
+    const event = createEvent({ hasCRM: false });
+    await expect(crmGuard(event)).rejects.toMatchObject({ statusCode: 403 });
+  });
+
+  it('throws 403 when hasCRM is undefined', async () => {
+    const event = createEvent({});
+    await expect(crmGuard(event)).rejects.toMatchObject({ statusCode: 403 });
+  });
+
+  it('PLATFORM_ADMIN bypasses CRM check', async () => {
+    const event = createEvent({ hasCRM: false, groups: ['PLATFORM_ADMIN'] });
+    const result = await crmGuard(event);
+    expect(result).toBeDefined();
+  });
+
+  it('error includes CRM_ACCESS_DENIED code', async () => {
+    const event = createEvent({ hasCRM: false, groups: ['ORG_ADMIN'] });
+    try {
+      await crmGuard(event);
+      fail('Should have thrown');
+    } catch (err: any) {
+      const body = JSON.parse(err.body);
+      expect(body.code).toBe('CRM_ACCESS_DENIED');
+    }
+  });
+});