nestjs-tenant-shield 0.1.0

package/dist/interfaces/tenant-shield-options.interface.d.ts

@@ -0,0 +1,141 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * TenantShieldModule.forRoot()에 넘기는 전역 설정 인터페이스.
+ *
+ * 라이브러리 사용자가 앱 시작 시 단 한 번 호출하며, 이 옵션이
+ * 모든 데코레이터/미들웨어/Subscriber의 동작을 결정합니다.
+ * ─────────────────────────────────────────────────────────────
+ */
+/**
+ * tenant ID를 요청에서 추출하는 방식.
+ * 보통 SaaS의 인증 방식과 매칭됩니다.
+ *
+ * - 'header'    : 모바일/내부 API에서 흔함. 예) X-Tenant-Id: academy-A
+ * - 'jwt'       : 표준적인 토큰 기반 인증.
+ * - 'subdomain' : academy-a.yourapp.com 같은 멀티 도메인 SaaS.
+ * - 'custom'    : 위 셋에 안 맞는 특수한 경우. 사용자가 함수를 직접 제공.
+ */
+export type TenantSource = 'header' | 'jwt' | 'subdomain' | 'custom';
+/**
+ * 멀티테넌시 격리 전략.
+ *
+ * v0.1에서는 'discriminator'만 구현됩니다.
+ * 나머지는 v0.2+에서 추가됩니다 (PRD §7 범위 제외 참조).
+ */
+export type TenantStrategy = 'discriminator' | 'schema' | 'database';
+/**
+ * forRoot()에 전달하는 옵션.
+ */
+export interface TenantShieldOptions {
+    /**
+     * 멀티테넌시 패턴.
+     *  - 'discriminator': 같은 테이블에 tenant_id 컬럼으로 구분 (v0.1)
+     *  - 'schema'       : Postgres schema 분리 (v0.2)
+     *  - 'database'     : DB-per-tenant (v0.2)
+     */
+    strategy: TenantStrategy;
+    /**
+     * Entity에서 tenant를 식별하는 컬럼/필드 이름.
+     * 회사마다 컨벤션이 다르므로 사용자가 지정합니다.
+     * 예: 'tenantId' (일반), 'spaceId' (슈퍼러닝), 'orgId' (Slack 스타일)
+     */
+    tenantIdField: string;
+    /**
+     * 요청에서 tenant ID를 어떻게 추출할지 지정.
+     * 아래 source 관련 옵션과 함께 사용.
+     */
+    tenantSource: TenantSource;
+    /**
+     * tenantSource가 'header'일 때 사용할 헤더 이름.
+     * 기본값: 'x-tenant-id'
+     */
+    headerName?: string;
+    /**
+     * tenantSource가 'jwt'일 때 사용할 JWT claim 이름.
+     * 기본값: 'tenant_id'
+     *
+     * 주의: JWT 디코딩 자체는 사용자의 인증 미들웨어 책임.
+     * 이 라이브러리는 request.user 또는 request.jwt에서 값만 꺼냅니다.
+     */
+    jwtClaim?: string;
+    /**
+     * tenantSource가 'subdomain'일 때 사용할 도메인 패턴.
+     * 예: '*.yourapp.com' → 'academy-a.yourapp.com'에서 'academy-a' 추출.
+     */
+    subdomainPattern?: string;
+    /**
+     * tenantSource가 'custom'일 때 사용자가 제공하는 추출 함수.
+     * null을 반환하면 tenant 컨텍스트가 설정되지 않은 것으로 간주.
+     *
+     * 예시:
+     *   customResolver: (req) => req.user?.organizationId ?? null
+     */
+    customResolver?: (request: unknown) => string | null;
+    /**
+     * Strict mode 활성화 여부 (기본 true, 강력 권장).
+     *
+     * true  : tenant 컨텍스트 없거나 cross-tenant 감지 시 즉시 throw.
+     * false : 경고 로그만 남기고 진행. 마이그레이션 중에만 임시 사용.
+     *
+     * 프로덕션에서는 절대 false로 두지 마세요. 데이터 누출 사고의 첫 단추.
+     */
+    strictMode?: boolean;
+    /**
+     * 시스템 작업(@SystemAction) 허용 여부 (기본 false).
+     *
+     * true로 켜면 cron, 마이그레이션, 모니터링 같은 작업이
+     * tenant 컨텍스트 없이 실행될 수 있습니다.
+     *
+     * 켜더라도 메서드에 @SystemAction()을 명시적으로 붙여야 합니다.
+     */
+    allowSystemActions?: boolean;
+    /**
+     * tenant 보호를 적용할 entity 클래스 목록.
+     *
+     * 미지정 시 라이브러리가 자동으로 tenantIdField를 가진 모든 entity를 감시.
+     * 명시하면 화이트리스트로 동작 (성능 + 안전성 둘 다 향상).
+     */
+    entities?: Function[];
+    /**
+     * 캐시 백엔드 교체 슬롯.
+     *
+     * 미지정 시 InMemoryTenantAwareCacheService(단일 프로세스용)가 사용됩니다.
+     * 프로덕션에서는 Redis 등 외부 캐시 어댑터로 교체 권장.
+     *
+     * 세 가지 형태로 제공 가능 (NestJS provider와 동일한 패턴):
+     *  - `useClass`   : 클래스 자체. NestJS DI가 인스턴스 생성.
+     *  - `useValue`   : 이미 만들어진 인스턴스. 외부에서 만든 싱글톤.
+     *  - `useFactory` : 비동기 셋업이 필요한 경우 (예: Redis client 초기화).
+     *
+     * 예시 (Redis 어댑터, 자세한 구현은 examples/redis-cache/ 참고):
+     *
+     *   cache: {
+     *     useFactory: (config: ConfigService) => new RedisCacheAdapter(config.get('REDIS_URL')),
+     *     inject: [ConfigService],
+     *   }
+     */
+    cache?: TenantShieldCacheProvider;
+}
+/**
+ * cache 슬롯에 들어갈 수 있는 세 가지 형태.
+ *
+ * 셋 중 정확히 하나만 채우는 것을 권장 (둘 이상 있으면 useFactory > useValue > useClass 순으로 우선).
+ */
+export interface TenantShieldCacheProvider {
+    useClass?: new (...args: any[]) => unknown;
+    useValue?: unknown;
+    useFactory?: (...args: any[]) => unknown | Promise<unknown>;
+    /** useFactory의 파라미터로 주입될 토큰들. */
+    inject?: any[];
+}
+/**
+ * forRootAsync()용 옵션. (v0.1.x 패치에서 추가 예정)
+ *
+ * ConfigService 같은 비동기 의존성을 통해 옵션을 만들고 싶을 때 사용.
+ */
+export interface TenantShieldAsyncOptions {
+    imports?: any[];
+    useFactory: (...args: any[]) => Promise<TenantShieldOptions> | TenantShieldOptions;
+    inject?: any[];
+}
+//# sourceMappingURL=tenant-shield-options.interface.d.ts.map

package/dist/interfaces/tenant-shield-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-shield-options.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/tenant-shield-options.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,EAAE,cAAc,CAAC;IAEzB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;IAErD;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,yBAAyB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,iCAAiC;IACjC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IACnF,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;CAChB"}

package/dist/interfaces/tenant-shield-options.interface.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * ─────────────────────────────────────────────────────────────
+ * TenantShieldModule.forRoot()에 넘기는 전역 설정 인터페이스.
+ *
+ * 라이브러리 사용자가 앱 시작 시 단 한 번 호출하며, 이 옵션이
+ * 모든 데코레이터/미들웨어/Subscriber의 동작을 결정합니다.
+ * ─────────────────────────────────────────────────────────────
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tenant-shield-options.interface.js.map

package/dist/interfaces/tenant-shield-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-shield-options.interface.js","sourceRoot":"","sources":["../../src/interfaces/tenant-shield-options.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tenant-context.middleware';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./tenant-context.middleware"), exports);
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8DAA4C"}

package/dist/middleware/tenant-context.middleware.d.ts

@@ -0,0 +1,30 @@
+import { NestMiddleware } from '@nestjs/common';
+import { TenantShieldOptions } from '../interfaces/tenant-shield-options.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 모든 HTTP 요청의 진입점에서 동작하는 미들웨어.
+ *
+ * 역할:
+ *  1) Resolver를 통해 요청에서 tenant ID 추출
+ *  2) AsyncLocalStorage.run()으로 컨텍스트를 만들어 next() 호출
+ *  3) 이후 컨트롤러/서비스/Subscriber 어디서든 getCurrentTenantId()로 조회 가능
+ *
+ * 이 미들웨어가 동작해야 비로소 라이브러리의 모든 기능이 켜집니다.
+ * TenantShieldModule이 자동으로 모든 라우트('*')에 적용해 줍니다.
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare class TenantContextMiddleware implements NestMiddleware {
+    private readonly options;
+    /**
+     * forRoot에서 만든 resolver를 한 번만 생성해 두고 재사용.
+     * (요청마다 새로 만들면 오버헤드)
+     */
+    private readonly resolver;
+    constructor(options: TenantShieldOptions);
+    /**
+     * Express 시그니처에 맞춘 미들웨어 함수.
+     * NestJS는 내부적으로 Express/Fastify 어댑터로 변환해 호출.
+     */
+    use(req: unknown, _res: unknown, next: (err?: unknown) => void): void;
+}
+//# sourceMappingURL=tenant-context.middleware.d.ts.map

package/dist/middleware/tenant-context.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/tenant-context.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAMpF;;;;;;;;;;;;GAYG;AACH,qBACa,uBAAwB,YAAW,cAAc;IAU1D,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;gBAKvB,OAAO,EAAE,mBAAmB;IAO/C;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;CAuBtE"}

package/dist/middleware/tenant-context.middleware.js

@@ -0,0 +1,68 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantContextMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../constants");
+const resolver_factory_1 = require("../resolvers/resolver.factory");
+const tenant_context_storage_1 = require("../context/tenant-context.storage");
+const missing_tenant_context_error_1 = require("../errors/missing-tenant-context.error");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 모든 HTTP 요청의 진입점에서 동작하는 미들웨어.
+ *
+ * 역할:
+ *  1) Resolver를 통해 요청에서 tenant ID 추출
+ *  2) AsyncLocalStorage.run()으로 컨텍스트를 만들어 next() 호출
+ *  3) 이후 컨트롤러/서비스/Subscriber 어디서든 getCurrentTenantId()로 조회 가능
+ *
+ * 이 미들웨어가 동작해야 비로소 라이브러리의 모든 기능이 켜집니다.
+ * TenantShieldModule이 자동으로 모든 라우트('*')에 적용해 줍니다.
+ * ─────────────────────────────────────────────────────────────
+ */
+let TenantContextMiddleware = class TenantContextMiddleware {
+    constructor(options) {
+        this.options = options;
+        // 부팅 시 옵션을 보고 적절한 resolver 인스턴스 생성.
+        // 잘못된 설정이면 여기서 InvalidTenantSourceError가 던져져 앱 부팅 실패.
+        this.resolver = (0, resolver_factory_1.createTenantResolver)(options);
+    }
+    /**
+     * Express 시그니처에 맞춘 미들웨어 함수.
+     * NestJS는 내부적으로 Express/Fastify 어댑터로 변환해 호출.
+     */
+    use(req, _res, next) {
+        // 1) 요청에서 tenant ID 추출 시도
+        const tenantId = this.resolver.resolve(req);
+        // 2) strict mode면 tenant 없을 때 즉시 차단
+        //    (단, allowSystemActions가 켜져있으면 시스템 작업 가능성이 있으므로
+        //     일단 통과시키고 메서드 단의 @RequireTenant가 최종 판단하도록 위임)
+        const strictMode = this.options.strictMode !== false; // 기본 true
+        if (!tenantId && strictMode && !this.options.allowSystemActions) {
+            // 미들웨어 단에서 throw하면 NestJS Exception Filter가 처리.
+            return next(new missing_tenant_context_error_1.MissingTenantContextError(`요청에서 tenant ID를 추출하지 못했습니다. source=${this.options.tenantSource}`, this.options.tenantSource));
+        }
+        // 3) AsyncLocalStorage.run()으로 컨텍스트 활성화.
+        //    next() 호출이 이 콜백 안에서 일어나야, 이후 모든 비동기 체인이
+        //    동일한 store를 공유합니다.
+        tenant_context_storage_1.tenantContextStorage.run({ tenantId, isSystemAction: false }, () => next());
+    }
+};
+exports.TenantContextMiddleware = TenantContextMiddleware;
+exports.TenantContextMiddleware = TenantContextMiddleware = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.TENANT_SHIELD_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], TenantContextMiddleware);
+//# sourceMappingURL=tenant-context.middleware.js.map

package/dist/middleware/tenant-context.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.middleware.js","sourceRoot":"","sources":["../../src/middleware/tenant-context.middleware.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoE;AACpE,4CAAqD;AAGrD,oEAAqE;AACrE,8EAAyE;AACzE,yFAAmF;AAEnF;;;;;;;;;;;;GAYG;AAEI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAOlC,YAGmB,OAA4B;QAA5B,YAAO,GAAP,OAAO,CAAqB;QAE7C,oCAAoC;QACpC,sDAAsD;QACtD,IAAI,CAAC,QAAQ,GAAG,IAAA,uCAAoB,EAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,GAAY,EAAE,IAAa,EAAE,IAA6B;QAC5D,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5C,oCAAoC;QACpC,oDAAoD;QACpD,mDAAmD;QACnD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC,UAAU;QAChE,IAAI,CAAC,QAAQ,IAAI,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAChE,gDAAgD;YAChD,OAAO,IAAI,CACT,IAAI,wDAAyB,CAC3B,sCAAsC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EACjE,IAAI,CAAC,OAAO,CAAC,YAAY,CAC1B,CACF,CAAC;QACJ,CAAC;QAED,yCAAyC;QACzC,6CAA6C;QAC7C,uBAAuB;QACvB,6CAAoB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF,CAAA;AA5CY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;IAUR,WAAA,IAAA,eAAM,EAAC,iCAAqB,CAAC,CAAA;;GATrB,uBAAuB,CA4CnC"}

package/dist/options/index.d.ts

@@ -0,0 +1,2 @@
+export * from './options.registry';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/options/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/options/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./options.registry"), exports);
+//# sourceMappingURL=index.js.map

package/dist/options/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/options/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC"}

package/dist/options/options.registry.d.ts

@@ -0,0 +1,8 @@
+import { TenantShieldOptions } from '../interfaces/tenant-shield-options.interface';
+/** 모듈 bootstrap 단계에서 1회 호출. */
+export declare function setGlobalOptions(options: TenantShieldOptions): void;
+/** wrapMethod가 런타임에 allowSystemActions 등을 읽기 위해 호출. */
+export declare function getGlobalOptions(): TenantShieldOptions | undefined;
+/** 테스트 격리용. 각 테스트 케이스 후 호출해서 오염 방지. */
+export declare function resetGlobalOptions(): void;
+//# sourceMappingURL=options.registry.d.ts.map

package/dist/options/options.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.registry.d.ts","sourceRoot":"","sources":["../../src/options/options.registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAsBpF,+BAA+B;AAC/B,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAEnE;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,mBAAmB,GAAG,SAAS,CAElE;AAED,uCAAuC;AACvC,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/options/options.registry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalOptions = setGlobalOptions;
+exports.getGlobalOptions = getGlobalOptions;
+exports.resetGlobalOptions = resetGlobalOptions;
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 글로벌 옵션 registry — @RequireTenant wrapMethod의 DI 우회로.
+ *
+ * 배경:
+ *   wrapMethod는 메서드 디스크립터를 decoration 시점에 감싸기 때문에
+ *   NestJS DI 컨테이너에서 forRoot 옵션을 꺼낼 방법이 없습니다.
+ *
+ *   해결: 모듈이 onApplicationBootstrap 시점에 옵션을 이 registry에 등록.
+ *   wrapMethod 내부의 wrapped function은 런타임에 registry에서 읽어옵니다.
+ *
+ * ⚠️ 한계:
+ *   - 한 프로세스에 하나의 forRoot 옵션만 가능 (대부분 SaaS에서는 OK)
+ *   - 테스트 격리를 위해 resetGlobalOptions() 필요
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+let globalOptions;
+/** 모듈 bootstrap 단계에서 1회 호출. */
+function setGlobalOptions(options) {
+    globalOptions = options;
+}
+/** wrapMethod가 런타임에 allowSystemActions 등을 읽기 위해 호출. */
+function getGlobalOptions() {
+    return globalOptions;
+}
+/** 테스트 격리용. 각 테스트 케이스 후 호출해서 오염 방지. */
+function resetGlobalOptions() {
+    globalOptions = undefined;
+}
+//# sourceMappingURL=options.registry.js.map

package/dist/options/options.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.registry.js","sourceRoot":"","sources":["../../src/options/options.registry.ts"],"names":[],"mappings":";;AAuBA,4CAEC;AAGD,4CAEC;AAGD,gDAEC;AAjCD;;;;;;;;;;;;;;;;GAgBG;AAEH,IAAI,aAA8C,CAAC;AAEnD,+BAA+B;AAC/B,SAAgB,gBAAgB,CAAC,OAA4B;IAC3D,aAAa,GAAG,OAAO,CAAC;AAC1B,CAAC;AAED,uDAAuD;AACvD,SAAgB,gBAAgB;IAC9B,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,uCAAuC;AACvC,SAAgB,kBAAkB;IAChC,aAAa,GAAG,SAAS,CAAC;AAC5B,CAAC"}

package/dist/resolvers/custom.resolver.d.ts

@@ -0,0 +1,29 @@
+import { TenantResolver } from './tenant-resolver.interface';
+/**
+ * 사용자가 직접 제공한 함수를 그대로 호출해 tenant ID를 얻는 resolver.
+ *
+ * Header/JWT/Subdomain 셋 어디에도 안 맞는 특수한 경우를 위한 탈출구입니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시 — multi-source 인증]
+ *
+ *   customResolver: (req) => {
+ *     // 모바일 앱은 헤더로, 웹은 JWT로, 외부 통합은 API 키로 보낼 때
+ *     return req.user?.organizationId
+ *         ?? req.headers['x-tenant-id']
+ *         ?? req.apiKey?.tenantId
+ *         ?? null;
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare class CustomTenantResolver implements TenantResolver {
+    private readonly fn;
+    /**
+     * @param fn - 사용자가 forRoot에서 제공한 customResolver 함수.
+     */
+    constructor(fn: (request: unknown) => string | null);
+    resolve(request: unknown): string | null;
+}
+//# sourceMappingURL=custom.resolver.d.ts.map

package/dist/resolvers/custom.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.resolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/custom.resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAI7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAH/B;;OAEG;gBAC0B,EAAE,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI;IAEpE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CAazC"}

package/dist/resolvers/custom.resolver.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomTenantResolver = void 0;
+/**
+ * 사용자가 직접 제공한 함수를 그대로 호출해 tenant ID를 얻는 resolver.
+ *
+ * Header/JWT/Subdomain 셋 어디에도 안 맞는 특수한 경우를 위한 탈출구입니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시 — multi-source 인증]
+ *
+ *   customResolver: (req) => {
+ *     // 모바일 앱은 헤더로, 웹은 JWT로, 외부 통합은 API 키로 보낼 때
+ *     return req.user?.organizationId
+ *         ?? req.headers['x-tenant-id']
+ *         ?? req.apiKey?.tenantId
+ *         ?? null;
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+class CustomTenantResolver {
+    /**
+     * @param fn - 사용자가 forRoot에서 제공한 customResolver 함수.
+     */
+    constructor(fn) {
+        this.fn = fn;
+    }
+    resolve(request) {
+        // 사용자 함수 호출 후 결과 검증.
+        // 빈 문자열, 잘못된 타입은 null로 정규화.
+        try {
+            const result = this.fn(request);
+            if (typeof result !== 'string' || result.length === 0)
+                return null;
+            return result;
+        }
+        catch {
+            // 사용자 함수가 throw해도 라이브러리 전체가 죽으면 안 됨.
+            // 추출 실패로 간주하고 미들웨어가 strict mode 정책에 따라 처리하도록 위임.
+            return null;
+        }
+    }
+}
+exports.CustomTenantResolver = CustomTenantResolver;
+//# sourceMappingURL=custom.resolver.js.map

package/dist/resolvers/custom.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.resolver.js","sourceRoot":"","sources":["../../src/resolvers/custom.resolver.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,oBAAoB;IAC/B;;OAEG;IACH,YAA6B,EAAuC;QAAvC,OAAE,GAAF,EAAE,CAAqC;IAAG,CAAC;IAExE,OAAO,CAAC,OAAgB;QACtB,qBAAqB;QACrB,4BAA4B;QAC5B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACnE,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;YACrC,iDAAiD;YACjD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAnBD,oDAmBC"}

package/dist/resolvers/header.resolver.d.ts

@@ -0,0 +1,22 @@
+import { TenantResolver } from './tenant-resolver.interface';
+/**
+ * HTTP 헤더에서 tenant ID를 추출하는 resolver.
+ *
+ * 가장 단순하고 흔한 방식. 클라이언트(웹/모바일/API)가
+ * 매 요청마다 X-Tenant-Id 같은 헤더를 보냅니다.
+ *
+ * ⚠️ 헤더 값은 클라이언트가 자유롭게 위조할 수 있습니다.
+ *    따라서 반드시 인증 미들웨어가 "이 사용자가 진짜 이 tenant 소속인지"
+ *    검증한 뒤에 이 resolver를 사용해야 합니다.
+ *    (이 라이브러리는 격리만 담당하고, 인증 자체는 책임지지 않음)
+ */
+export declare class HeaderTenantResolver implements TenantResolver {
+    private readonly headerName;
+    /**
+     * @param headerName - 어떤 헤더 이름을 읽을지. 기본 'x-tenant-id'
+     *                     (HTTP 헤더 이름은 대소문자 무시이지만, 노드는 보통 소문자로 정규화)
+     */
+    constructor(headerName?: string);
+    resolve(request: unknown): string | null;
+}
+//# sourceMappingURL=header.resolver.d.ts.map

package/dist/resolvers/header.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.resolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/header.resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAK7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJvC;;;OAGG;gBAC0B,UAAU,GAAE,MAAsB;IAE/D,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CAgBzC"}

package/dist/resolvers/header.resolver.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeaderTenantResolver = void 0;
+/**
+ * HTTP 헤더에서 tenant ID를 추출하는 resolver.
+ *
+ * 가장 단순하고 흔한 방식. 클라이언트(웹/모바일/API)가
+ * 매 요청마다 X-Tenant-Id 같은 헤더를 보냅니다.
+ *
+ * ⚠️ 헤더 값은 클라이언트가 자유롭게 위조할 수 있습니다.
+ *    따라서 반드시 인증 미들웨어가 "이 사용자가 진짜 이 tenant 소속인지"
+ *    검증한 뒤에 이 resolver를 사용해야 합니다.
+ *    (이 라이브러리는 격리만 담당하고, 인증 자체는 책임지지 않음)
+ */
+class HeaderTenantResolver {
+    /**
+     * @param headerName - 어떤 헤더 이름을 읽을지. 기본 'x-tenant-id'
+     *                     (HTTP 헤더 이름은 대소문자 무시이지만, 노드는 보통 소문자로 정규화)
+     */
+    constructor(headerName = 'x-tenant-id') {
+        this.headerName = headerName;
+    }
+    resolve(request) {
+        // Express/Fastify 모두 req.headers를 통해 헤더 dict에 접근 가능.
+        // 타입은 라이브러리 호환성을 위해 unknown으로 받고 안에서 좁힙니다.
+        const req = request;
+        // 헤더가 아예 없으면 null 반환.
+        const raw = req.headers?.[this.headerName.toLowerCase()];
+        if (!raw)
+            return null;
+        // 헤더는 같은 키로 여러 값이 올 수 있어 배열일 수 있음 → 첫 번째 값 사용.
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        // 빈 문자열도 null로 간주 (의미 있는 tenant ID로 보지 않음).
+        const trimmed = value?.trim();
+        return trimmed ? trimmed : null;
+    }
+}
+exports.HeaderTenantResolver = HeaderTenantResolver;
+//# sourceMappingURL=header.resolver.js.map

package/dist/resolvers/header.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.resolver.js","sourceRoot":"","sources":["../../src/resolvers/header.resolver.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;GAUG;AACH,MAAa,oBAAoB;IAC/B;;;OAGG;IACH,YAA6B,aAAqB,aAAa;QAAlC,eAAU,GAAV,UAAU,CAAwB;IAAG,CAAC;IAEnE,OAAO,CAAC,OAAgB;QACtB,qDAAqD;QACrD,2CAA2C;QAC3C,MAAM,GAAG,GAAG,OAAsE,CAAC;QAEnF,sBAAsB;QACtB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,+CAA+C;QAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAEhD,4CAA4C;QAC5C,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAClC,CAAC;CACF;AAvBD,oDAuBC"}

package/dist/resolvers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolver 관련 export.
+ *
+ * 일반 사용자는 직접 쓸 일이 거의 없습니다.
+ * 내부 모듈(미들웨어)이 factory로 인스턴스를 만들고 사용합니다.
+ */
+export * from './tenant-resolver.interface';
+export * from './header.resolver';
+export * from './jwt.resolver';
+export * from './subdomain.resolver';
+export * from './custom.resolver';
+export * from './resolver.factory';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resolvers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/resolvers/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Resolver 관련 export.
+ *
+ * 일반 사용자는 직접 쓸 일이 거의 없습니다.
+ * 내부 모듈(미들웨어)이 factory로 인스턴스를 만들고 사용합니다.
+ */
+__exportStar(require("./tenant-resolver.interface"), exports);
+__exportStar(require("./header.resolver"), exports);
+__exportStar(require("./jwt.resolver"), exports);
+__exportStar(require("./subdomain.resolver"), exports);
+__exportStar(require("./custom.resolver"), exports);
+__exportStar(require("./resolver.factory"), exports);
+//# sourceMappingURL=index.js.map

package/dist/resolvers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resolvers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,8DAA4C;AAC5C,oDAAkC;AAClC,iDAA+B;AAC/B,uDAAqC;AACrC,oDAAkC;AAClC,qDAAmC"}

package/dist/resolvers/jwt.resolver.d.ts

@@ -0,0 +1,35 @@
+import { TenantResolver } from './tenant-resolver.interface';
+/**
+ * JWT 페이로드의 claim에서 tenant ID를 추출하는 resolver.
+ *
+ * 동작 전제:
+ *  사용자의 인증 미들웨어(예: Passport, @nestjs/jwt)가 이미
+ *  JWT를 검증하고 페이로드를 request.user 또는 request.jwt에
+ *  넣어 둔 상태여야 합니다.
+ *
+ *  이 resolver는 그 객체에서 특정 키만 읽어옵니다.
+ *  즉, JWT 자체 검증은 이 라이브러리의 책임이 아님.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시 JWT 페이로드]
+ *
+ *   {
+ *     "sub": "user-123",
+ *     "tenant_id": "academy-A",
+ *     "exp": 1700000000
+ *   }
+ *
+ * → jwtClaim: 'tenant_id'로 설정하면 'academy-A'를 추출.
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare class JwtTenantResolver implements TenantResolver {
+    private readonly claimName;
+    /**
+     * @param claimName - JWT 페이로드에서 읽을 키 이름. 기본 'tenant_id'.
+     */
+    constructor(claimName?: string);
+    resolve(request: unknown): string | null;
+}
+//# sourceMappingURL=jwt.resolver.d.ts.map

package/dist/resolvers/jwt.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.resolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/jwt.resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAI1C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC;;OAEG;gBAC0B,SAAS,GAAE,MAAoB;IAE5D,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CAkBzC"}