serverless-event-orchestrator 1.2.7 → 1.3.0

package/dist/tenant/TenantContext.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * 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.
+ */
+class TenantContext {
+    static storage = new node_async_hooks_1.AsyncLocalStorage();
+    /**
+     * 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(tenant, callback) {
+        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) {
+        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() {
+        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() {
+        return this.storage.getStore();
+    }
+    /**
+     * Checks if there's an active tenant context.
+     * Useful for conditionals without getting the full object.
+     */
+    static isActive() {
+        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() {
+        this.storage.disable();
+        this.storage = new node_async_hooks_1.AsyncLocalStorage();
+    }
+}
+exports.TenantContext = TenantContext;
+//# sourceMappingURL=TenantContext.js.map

package/dist/tenant/TenantContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantContext.js","sourceRoot":"","sources":["../../src/tenant/TenantContext.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAGrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,aAAa;IAChB,MAAM,CAAC,OAAO,GAAG,IAAI,oCAAiB,EAAc,CAAC;IAE7D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,CAAI,MAAkB,EAAE,QAAiB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,MAAkB;QAC3B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO;QACZ,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mFAAmF;gBACnF,wEAAwE,CACzE,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,eAAe;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtB,IAAY,CAAC,OAAO,GAAG,IAAI,oCAAiB,EAAc,CAAC;IAC9D,CAAC;;AAxFH,sCAyFC"}

package/dist/tenant/helpers.d.ts

@@ -0,0 +1,26 @@
+import type { TenantInfo } 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 declare function tenantInfoFromClaims(claims: Record<string, any>): TenantInfo | undefined;
+/**
+ * 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 declare function tenantInfoFromHeaders(headers: Record<string, string | undefined>): TenantInfo | undefined;
+/**
+ * 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 declare function tenantInfoToHeaders(tenant: TenantInfo): Record<string, string>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/tenant/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/tenant/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,UAAU,GAAG,SAAS,CAwBxF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,UAAU,GAAG,SAAS,CAwBxB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB9E"}

package/dist/tenant/helpers.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tenantInfoFromClaims = tenantInfoFromClaims;
+exports.tenantInfoFromHeaders = tenantInfoFromHeaders;
+exports.tenantInfoToHeaders = tenantInfoToHeaders;
+const types_js_1 = require("./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
+ */
+function tenantInfoFromClaims(claims) {
+    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 (!(0, types_js_1.isTenantType)(tenantType)) {
+        return undefined;
+    }
+    return {
+        tenantId,
+        tenantType,
+        userId,
+        personProfileId: claims['custom:personProfileId'],
+        orgProfileId: claims['custom:orgProfileId'],
+        countryCode,
+        plan: (0, types_js_1.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
+ */
+function tenantInfoFromHeaders(headers) {
+    const get = (key) => headers[key] || headers[key.toLowerCase()];
+    const tenantId = get(types_js_1.TENANT_HEADERS.TENANT_ID);
+    const tenantType = get(types_js_1.TENANT_HEADERS.TENANT_TYPE);
+    const userId = get(types_js_1.TENANT_HEADERS.USER_ID);
+    const countryCode = get(types_js_1.TENANT_HEADERS.COUNTRY_CODE);
+    if (!tenantId || !tenantType || !userId || !countryCode) {
+        return undefined;
+    }
+    if (!(0, types_js_1.isTenantType)(tenantType)) {
+        return undefined;
+    }
+    return {
+        tenantId,
+        tenantType: tenantType,
+        userId,
+        personProfileId: get(types_js_1.TENANT_HEADERS.PERSON_PROFILE_ID),
+        orgProfileId: get(types_js_1.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
+ */
+function tenantInfoToHeaders(tenant) {
+    const headers = {
+        [types_js_1.TENANT_HEADERS.TENANT_ID]: tenant.tenantId,
+        [types_js_1.TENANT_HEADERS.TENANT_TYPE]: tenant.tenantType,
+        [types_js_1.TENANT_HEADERS.USER_ID]: tenant.userId,
+        [types_js_1.TENANT_HEADERS.COUNTRY_CODE]: tenant.countryCode,
+    };
+    if (tenant.personProfileId) {
+        headers[types_js_1.TENANT_HEADERS.PERSON_PROFILE_ID] = tenant.personProfileId;
+    }
+    if (tenant.orgProfileId) {
+        headers[types_js_1.TENANT_HEADERS.ORG_PROFILE_ID] = tenant.orgProfileId;
+    }
+    return headers;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/tenant/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/tenant/helpers.ts"],"names":[],"mappings":"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"}

package/dist/tenant/index.d.ts

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/tenant/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tenant/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,YAAY,EACV,UAAU,EACV,UAAU,EACV,IAAI,EACJ,cAAc,EACd,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,MAAM,EACN,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/tenant/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tenantInfoToHeaders = exports.tenantInfoFromHeaders = exports.tenantInfoFromClaims = exports.TENANT_HEADERS = exports.isPlan = exports.isTenantType = exports.TenantContext = void 0;
+var TenantContext_js_1 = require("./TenantContext.js");
+Object.defineProperty(exports, "TenantContext", { enumerable: true, get: function () { return TenantContext_js_1.TenantContext; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "isTenantType", { enumerable: true, get: function () { return types_js_1.isTenantType; } });
+Object.defineProperty(exports, "isPlan", { enumerable: true, get: function () { return types_js_1.isPlan; } });
+Object.defineProperty(exports, "TENANT_HEADERS", { enumerable: true, get: function () { return types_js_1.TENANT_HEADERS; } });
+var helpers_js_1 = require("./helpers.js");
+Object.defineProperty(exports, "tenantInfoFromClaims", { enumerable: true, get: function () { return helpers_js_1.tenantInfoFromClaims; } });
+Object.defineProperty(exports, "tenantInfoFromHeaders", { enumerable: true, get: function () { return helpers_js_1.tenantInfoFromHeaders; } });
+Object.defineProperty(exports, "tenantInfoToHeaders", { enumerable: true, get: function () { return helpers_js_1.tenantInfoToHeaders; } });
+//# sourceMappingURL=index.js.map

package/dist/tenant/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tenant/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAUtB,uCAIoB;AAHlB,wGAAA,YAAY,OAAA;AACZ,kGAAA,MAAM,OAAA;AACN,0GAAA,cAAc,OAAA;AAGhB,2CAIsB;AAHpB,kHAAA,oBAAoB,OAAA;AACpB,mHAAA,qBAAqB,OAAA;AACrB,iHAAA,mBAAmB,OAAA"}

package/dist/tenant/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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;
+    'custom:hasWhiteLabel'?: string;
+}
+/**
+ * Headers used to propagate tenant in Lambda-to-Lambda calls.
+ */
+export declare const TENANT_HEADERS: {
+    readonly TENANT_ID: "x-tenant-id";
+    readonly TENANT_TYPE: "x-tenant-type";
+    readonly USER_ID: "x-user-id";
+    readonly COUNTRY_CODE: "x-country-code";
+    readonly PERSON_PROFILE_ID: "x-person-profile-id";
+    readonly ORG_PROFILE_ID: "x-org-profile-id";
+};
+/**
+ * Type guard: checks if a value is a valid TenantType.
+ */
+export declare function isTenantType(value: unknown): value is TenantType;
+/**
+ * Type guard: checks if a value is a valid Plan.
+ */
+export declare function isPlan(value: unknown): value is Plan;
+//# sourceMappingURL=types.d.ts.map

package/dist/tenant/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tenant/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,YAAY,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,YAAY,EAAE,OAAO,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IAEjB,kBAAkB;IAClB,UAAU,EAAE,UAAU,CAAC;IAEvB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IAEf,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,UAAU,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC;AAEX;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEpD"}

package/dist/tenant/types.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TENANT_HEADERS = void 0;
+exports.isTenantType = isTenantType;
+exports.isPlan = isPlan;
+/**
+ * Headers used to propagate tenant in Lambda-to-Lambda calls.
+ */
+exports.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',
+};
+/**
+ * Type guard: checks if a value is a valid TenantType.
+ */
+function isTenantType(value) {
+    return value === 'ORG' || value === 'PERSON';
+}
+/**
+ * Type guard: checks if a value is a valid Plan.
+ */
+function isPlan(value) {
+    return value === 'FREE' || value === 'BASIC' || value === 'PRO' || value === 'ENTERPRISE';
+}
+//# sourceMappingURL=types.js.map

package/dist/tenant/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tenant/types.ts"],"names":[],"mappings":";;;AA2FA,oCAEC;AAKD,wBAEC;AAxBD;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,SAAS,EAAE,aAAa;IACxB,WAAW,EAAE,eAAe;IAC5B,OAAO,EAAE,WAAW;IACpB,YAAY,EAAE,gBAAgB;IAC9B,iBAAiB,EAAE,qBAAqB;IACxC,cAAc,EAAE,kBAAkB;CAC1B,CAAC;AAEX;;GAEG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,SAAgB,MAAM,CAAC,KAAc;IACnC,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,YAAY,CAAC;AAC5F,CAAC"}

package/dist/types/routes.d.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
  */
@@ -130,6 +131,7 @@ export interface NormalizedEvent {
         segment: RouteSegment;
         identity?: IdentityContext;
         requestId?: string;
+        tenantInfo?: TenantInfo;
     };
 }
 /**

package/dist/types/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/types/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/types/routes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-event-orchestrator",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "A lightweight, type-safe event dispatcher and middleware orchestrator for AWS Lambda. Designed for hexagonal architectures with support for segmented routing (public, private, backoffice), Cognito User Pool validation, and built-in infrastructure middlewares.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,16 @@
       "import": "./dist/identity/index.js",
       "require": "./dist/identity/index.js",
       "types": "./dist/identity/index.d.ts"
+    },
+    "./middleware": {
+      "import": "./dist/middleware/index.js",
+      "require": "./dist/middleware/index.js",
+      "types": "./dist/middleware/index.d.ts"
+    },
+    "./tenant": {
+      "import": "./dist/tenant/index.js",
+      "require": "./dist/tenant/index.js",
+      "types": "./dist/tenant/index.d.ts"
     }
   },
   "scripts": {

package/src/dispatcher.ts

@@ -255,7 +255,22 @@ function validateSegmentUserPool(
 }
 
 /**
- * Executes middleware chain
+ * Checks if a thrown value is an HTTP response (used by middleware to halt execution)
+ */
+function isHttpResponse(value: unknown): value is { statusCode: number; body: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'statusCode' in value &&
+    typeof (value as any).statusCode === 'number'
+  );
+}
+
+/**
+ * Executes middleware chain.
+ * If a middleware throws an HttpResponse-like object (has statusCode),
+ * it is treated as an early return (e.g., 403 Forbidden from tenantGuard).
+ * If it throws a regular Error, it is re-thrown.
  */
 async function executeMiddleware(
   middleware: MiddlewareFn[],
@@ -402,14 +417,24 @@ export async function dispatchEvent(
       return applyCorsToResponse(config.responses?.forbidden?.() ?? forbiddenResponse('Access denied: Invalid token issuer'));
     }
     
-    // Execute global middleware
-    if (config.globalMiddleware?.length) {
-      normalized = await executeMiddleware(config.globalMiddleware, normalized);
-    }
-    
-    // Execute segment middleware
-    if (routeMatch.middleware?.length) {
-      normalized = await executeMiddleware(routeMatch.middleware, normalized);
+    // Execute middlewares with error handling for HttpResponse throws
+    try {
+      // Execute global middleware
+      if (config.globalMiddleware?.length) {
+        normalized = await executeMiddleware(config.globalMiddleware, normalized);
+      }
+      
+      // Execute segment middleware
+      if (routeMatch.middleware?.length) {
+        normalized = await executeMiddleware(routeMatch.middleware, normalized);
+      }
+    } catch (thrown) {
+      // If middleware threw an HttpResponse (e.g., forbiddenResponse from tenantGuard), return it
+      if (isHttpResponse(thrown)) {
+        return applyCorsToResponse(thrown);
+      }
+      // Otherwise, re-throw as unhandled error
+      throw thrown;
     }
     
     // Execute handler and apply CORS headers to response

package/src/index.ts

@@ -90,3 +90,33 @@ export {
   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

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

package/src/middleware/index.ts

@@ -0,0 +1,3 @@
+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

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